Skip to main content

qualia_app_contract/
descriptor.rs

1//! Command descriptor definitions and availability status.
2
3use crate::effects::{EffectSet, InteractionKind, UndoPolicy};
4use crate::error::ContractError;
5use crate::id::{AppId, CommandId};
6use serde::{Deserialize, Serialize};
7
8/// Target kind on which a command operates.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
10#[serde(rename_all = "snake_case")]
11pub enum TargetKind {
12    TextSelection,
13    CellRange,
14    Layer,
15    VectorPath,
16    TimelineClip,
17    CadEntity,
18    Document,
19    Scene,
20    Generic,
21}
22
23/// Dynamic availability status of a command given current target and session state.
24#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
25#[serde(tag = "status", rename_all = "snake_case")]
26pub enum Availability {
27    Available,
28    Disabled {
29        reason_code: String,
30        localized_reason: String,
31        #[serde(skip_serializing_if = "Option::is_none")]
32        missing_prerequisite: Option<String>,
33    },
34    Hidden {
35        reason_code: String,
36    },
37}
38
39impl Availability {
40    /// `true` when available.
41    pub fn is_available(&self) -> bool {
42        matches!(self, Self::Available)
43    }
44
45    /// Disabled variant.
46    pub fn disabled(code: impl Into<String>, reason: impl Into<String>) -> Self {
47        Self::Disabled {
48            reason_code: code.into(),
49            localized_reason: reason.into(),
50            missing_prerequisite: None,
51        }
52    }
53}
54
55/// Canonical metadata descriptor for an application command.
56#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
57pub struct CommandDescriptor {
58    pub schema_version: u32,
59    pub command_id: CommandId,
60    pub command_version: String,
61    pub app_id: AppId,
62    pub upstream_id: String,
63    pub label_key: String,
64    pub description_key: String,
65    pub input_schema: serde_json::Value,
66    pub output_schema: serde_json::Value,
67    pub target_kinds: Vec<TargetKind>,
68    pub effects: EffectSet,
69    pub required_capabilities: Vec<String>,
70    pub undo_policy: UndoPolicy,
71    pub interaction: InteractionKind,
72    #[serde(skip_serializing_if = "Option::is_none")]
73    pub menu: Option<String>,
74    #[serde(skip_serializing_if = "Option::is_none")]
75    pub toolbox: Option<String>,
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub tool_chain: Option<String>,
78    #[serde(skip_serializing_if = "Option::is_none")]
79    pub orb_group: Option<String>,
80    #[serde(default, skip_serializing_if = "Vec::is_empty")]
81    pub shortcuts: Vec<String>,
82}
83
84impl CommandDescriptor {
85    /// Validate descriptor fields against the canonical contract.
86    pub fn validate(&self) -> Result<(), ContractError> {
87        if self.schema_version != 1 {
88            return Err(ContractError::UnknownVersion(self.schema_version));
89        }
90
91        if self.label_key.trim().is_empty() {
92            return Err(ContractError::MalformedParams("label_key cannot be empty".into()));
93        }
94
95        // Schema must be valid JSON Schema object or boolean
96        if !self.input_schema.is_object() && !self.input_schema.is_boolean() && !self.input_schema.is_null() {
97            return Err(ContractError::MalformedParams("input_schema must be an object or boolean".into()));
98        }
99
100        if !self.output_schema.is_object() && !self.output_schema.is_boolean() && !self.output_schema.is_null() {
101            return Err(ContractError::MalformedParams("output_schema must be an object or boolean".into()));
102        }
103
104        // Validate command ID matches app ID
105        if self.command_id.app_id() != self.app_id.as_str() {
106            return Err(ContractError::InvalidCommandIdFormat(format!(
107                "command ID app prefix '{}' does not match app ID '{}'",
108                self.command_id.app_id(),
109                self.app_id.as_str()
110            )));
111        }
112
113        Ok(())
114    }
115}