iriai-build 0.1.0

package/v3/adapters/interface.js

@@ -0,0 +1,146 @@
+// interface.js — InterfaceAdapter base class.
+// All user-facing I/O flows through this contract.
+// Implementations: SlackAdapter, TerminalAdapter, DesktopAdapter.
+
+/**
+ * @typedef {Object} DecisionSpec
+ * @property {string} id - Semantic ID, e.g. "gate-2-review", "plan-approval"
+ * @property {string} title - Human-readable title
+ * @property {string} [context] - Brief context text
+ * @property {string} [type] - "approval" | "choice" | "confirmation"
+ * @property {Array<{id: string, label: string, style?: string, description?: string}>} options
+ * @property {string} [reviewUrl] - URL to interactive doc review tool (qa-feedback)
+ * @property {string} [qaUrl] - URL to interactive QA testing session (qa-feedback proxy)
+ */
+
+export class InterfaceAdapter {
+  // Default channel/workspace ref. Adapters set this to their primary channel.
+  // Used by orchestrator for feature disambiguation when multiple features are active.
+  planningChannel = null;
+
+  /**
+   * Create a feature channel/workspace. Returns an opaque channel reference string.
+   * @param {number} featureId
+   * @param {string} slug
+   * @returns {Promise<string|null>} channelRef — opaque handle (Slack channel ID, terminal slug, etc.)
+   */
+  async createFeatureChannel(featureId, slug) {
+    throw new Error("InterfaceAdapter.createFeatureChannel() not implemented");
+  }
+
+  /**
+   * Post a general message to the feature's channel.
+   * @param {number} featureId
+   * @param {string} text
+   * @returns {Promise<{ref?: string}>} Opaque message reference
+   */
+  async postMessage(featureId, text) {
+    throw new Error("InterfaceAdapter.postMessage() not implemented");
+  }
+
+  /**
+   * Post a message to the feature's parent thread (e.g. planning channel thread).
+   * @param {number} featureId
+   * @param {string} text
+   * @returns {Promise<void>}
+   */
+  async postThreadMessage(featureId, text) {
+    throw new Error("InterfaceAdapter.postThreadMessage() not implemented");
+  }
+
+  /**
+   * Post a pipeline/system status message.
+   * @param {number} featureId
+   * @param {string} text
+   * @returns {Promise<{ref?: string}>}
+   */
+  async postPipelineMessage(featureId, text) {
+    throw new Error("InterfaceAdapter.postPipelineMessage() not implemented");
+  }
+
+  /**
+   * Post an agent response (with media handling).
+   * @param {number} featureId
+   * @param {string} agentLabel - Display name of the agent
+   * @param {string} content - Raw content (may contain media markers)
+   * @returns {Promise<{ref?: string}>}
+   */
+  async postAgentResponse(featureId, agentLabel, content) {
+    throw new Error("InterfaceAdapter.postAgentResponse() not implemented");
+  }
+
+  /**
+   * Upload an artifact file.
+   * @param {number} featureId
+   * @param {string} filePath - Absolute path to file
+   * @param {string} title - Display title
+   * @returns {Promise<void>}
+   */
+  async uploadArtifact(featureId, filePath, title) {
+    throw new Error("InterfaceAdapter.uploadArtifact() not implemented");
+  }
+
+  /**
+   * Post a decision prompt (buttons/choices).
+   * @param {number} featureId
+   * @param {DecisionSpec} decision
+   * @returns {Promise<{ref?: string}>} Opaque decision message reference
+   */
+  async postDecision(featureId, decision) {
+    throw new Error("InterfaceAdapter.postDecision() not implemented");
+  }
+
+  /**
+   * Update a decision message to show resolved state.
+   * @param {number} featureId
+   * @param {string} messageRef - Opaque reference from postDecision
+   * @param {string} decisionId
+   * @param {string} selectedOption - Option ID
+   * @param {string} selectedLabel - Human label
+   * @param {string} resolvedBy - User ID
+   * @param {string} [feedback]
+   * @returns {Promise<void>}
+   */
+  async resolveDecisionMessage(featureId, messageRef, decisionId, selectedOption, selectedLabel, resolvedBy, feedback) {
+    throw new Error("InterfaceAdapter.resolveDecisionMessage() not implemented");
+  }
+
+  /**
+   * Post plan artifacts and approval decision.
+   * @param {number} featureId
+   * @param {string} planDir - Directory containing plan artifacts
+   * @returns {Promise<{ref?: string}>}
+   */
+  async postPlanForApproval(featureId, planDir) {
+    throw new Error("InterfaceAdapter.postPlanForApproval() not implemented");
+  }
+
+  /**
+   * Post feature completion message.
+   * @param {number} featureId
+   * @returns {Promise<void>}
+   */
+  async postFeatureComplete(featureId) {
+    throw new Error("InterfaceAdapter.postFeatureComplete() not implemented");
+  }
+
+  /**
+   * Add a processing indicator (e.g. :eyes: reaction).
+   * @param {number} featureId
+   * @param {string} messageRef
+   * @returns {Promise<void>}
+   */
+  async markProcessing(featureId, messageRef) {
+    // Optional — default no-op
+  }
+
+  /**
+   * Clear a processing indicator.
+   * @param {number} featureId
+   * @param {string} messageRef
+   * @returns {Promise<void>}
+   */
+  async clearProcessing(featureId, messageRef) {
+    // Optional — default no-op
+  }
+}