@josstei/maestro 1.6.4-rc.1

package/src/mcp/handlers/design-gate.js

@@ -0,0 +1,393 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { assertSessionId } = require('../../lib/validation');
+const { ValidationError } = require('../../lib/errors');
+const { resolveStateDirPath } = require('../../state/session-state');
+const { atomicWriteSync } = require('../../lib/io');
+
+const GATE_FILENAME = '.design-gate.json';
+
+/**
+ * Resolves the filesystem path for the gate file for a given session.
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function gatePath(projectRoot, sessionId) {
+  const stateDir = resolveStateDirPath(projectRoot);
+  return path.join(stateDir, 'state', `${sessionId}${GATE_FILENAME}`);
+}
+
+/**
+ * Canonical location where approved design documents live. Runtimes (including
+ * Plan Mode) may write design docs to arbitrary temporary locations; this
+ * function is the single source of truth for the post-approval location so the
+ * archive flow can reliably find and move the document.
+ *
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function plansDirPath(projectRoot) {
+  return path.join(resolveStateDirPath(projectRoot), 'plans');
+}
+
+/**
+ * Copy a design document to `<state_dir>/plans/<basename>` when it isn't
+ * already there. Idempotent: returns the in-plans path regardless of whether a
+ * copy was needed. Preserves the source file so runtime-managed tmp locations
+ * (Plan Mode) remain intact.
+ *
+ * @param {string} projectRoot
+ * @param {string} sourcePath - absolute path to the approved design document
+ * @returns {string} absolute path to the canonical location inside plans/
+ */
+function ensureDesignDocumentInPlans(projectRoot, sourcePath) {
+  const plansDir = plansDirPath(projectRoot);
+  const resolvedPlansDir = path.resolve(plansDir) + path.sep;
+  const resolvedSource = path.resolve(sourcePath);
+
+  if (resolvedSource.startsWith(resolvedPlansDir)) {
+    return resolvedSource;
+  }
+
+  fs.mkdirSync(plansDir, { recursive: true });
+  const destination = path.join(plansDir, path.basename(resolvedSource));
+  fs.copyFileSync(resolvedSource, destination);
+  return destination;
+}
+
+/**
+ * Validate that a caller-provided filename is safe to join into the plans
+ * directory. Rejects anything that could escape the directory or collide with a
+ * nested path.
+ *
+ * @param {string} filename
+ * @param {string} paramName - name of the parameter for error messages (e.g. "design_document_filename")
+ * @throws {ValidationError}
+ */
+function assertPlansFilename(filename, paramName) {
+  if (typeof filename !== 'string' || filename.length === 0) {
+    throw new ValidationError(`${paramName} is required`);
+  }
+  if (filename.includes('\0')) {
+    throw new ValidationError(`${paramName} contains null bytes`, {
+      details: { value: filename },
+    });
+  }
+  if (filename !== path.basename(filename) || filename === '..' || filename === '.') {
+    throw new ValidationError(
+      `${paramName} must be a pure basename (no path separators, no '.' or '..')`,
+      { details: { value: filename } }
+    );
+  }
+}
+
+/**
+ * Write caller-supplied document content to `<state_dir>/plans/<filename>`
+ * atomically and return the canonical absolute path. The content-based
+ * counterpart to `ensureDesignDocumentInPlans` — callers that cannot guarantee
+ * filesystem visibility across runtime boundaries (e.g. Gemini Plan Mode writes
+ * to `~/.gemini/tmp/...`) use this to bypass path-resolution ambiguity
+ * entirely.
+ *
+ * @param {string} projectRoot
+ * @param {string} filename - basename-only, validated via assertPlansFilename
+ * @param {string} content - UTF-8 document content
+ * @param {string} filenameParam - parameter name for validation errors
+ * @returns {string} absolute canonical path inside plans/
+ */
+function writePlansDocumentContent(projectRoot, filename, content, filenameParam) {
+  assertPlansFilename(filename, filenameParam);
+  if (typeof content !== 'string' || content.length === 0) {
+    throw new ValidationError(
+      `${filenameParam.replace(/_filename$/, '_content')} must be a non-empty string`
+    );
+  }
+  const destination = path.join(plansDirPath(projectRoot), filename);
+  atomicWriteSync(destination, content);
+  return destination;
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @returns {{ session_id: string, entered_at: string | null, approved_at: string | null, design_document_path: string | null } | null}
+ */
+function readGate(projectRoot, sessionId) {
+  const filePath = gatePath(projectRoot, sessionId);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @param {object} data
+ */
+function writeGate(projectRoot, sessionId, data) {
+  const filePath = gatePath(projectRoot, sessionId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  atomicWriteSync(filePath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * @param {{ session_id: string }} params
+ * @param {string} projectRoot
+ */
+function handleEnterDesignGate(params, projectRoot) {
+  assertSessionId(params.session_id);
+  const existing = readGate(projectRoot, params.session_id);
+  if (existing && existing.entered_at) {
+    return { success: true, entered_at: existing.entered_at, already_entered: true };
+  }
+  const gate = {
+    session_id: params.session_id,
+    entered_at: new Date().toISOString(),
+    approved_at: null,
+    design_document_path: null,
+  };
+  writeGate(projectRoot, params.session_id, gate);
+  return { success: true, entered_at: gate.entered_at, already_entered: false };
+}
+
+/**
+ * Resolve the caller's approved-design input to a canonical absolute path.
+ * Accepts exactly one of (design_document_path) or (design_document_content +
+ * design_document_filename). The content variant materializes the file
+ * immediately inside `<state_dir>/plans/`, eliminating the path-resolution
+ * ambiguity that arises when callers write through a runtime surface whose
+ * filesystem root differs from the MCP server's workspace (e.g. Gemini Plan
+ * Mode writes to `~/.gemini/tmp/<uuid>/...`).
+ *
+ * @param {object} params
+ * @param {string} [params.design_document_path]
+ * @param {string} [params.design_document_content]
+ * @param {string} [params.design_document_filename]
+ * @param {string} projectRoot
+ * @returns {string} canonical absolute path of the approved design document
+ * @throws {ValidationError} when neither or both input variants are supplied
+ */
+function resolveApprovedDesignDocument(params, projectRoot) {
+  const hasPath =
+    typeof params.design_document_path === 'string' &&
+    params.design_document_path.length > 0;
+  const hasContent =
+    typeof params.design_document_content === 'string' &&
+    params.design_document_content.length > 0;
+  const hasFilename =
+    typeof params.design_document_filename === 'string' &&
+    params.design_document_filename.length > 0;
+  const contentVariantProvided = hasContent || hasFilename;
+
+  if (hasPath && contentVariantProvided) {
+    throw new ValidationError(
+      'design_document_path is mutually exclusive with design_document_content/design_document_filename'
+    );
+  }
+
+  if (contentVariantProvided) {
+    if (!hasContent) {
+      throw new ValidationError('design_document_content is required');
+    }
+    if (!hasFilename) {
+      throw new ValidationError('design_document_filename is required');
+    }
+    return writePlansDocumentContent(
+      projectRoot,
+      params.design_document_filename,
+      params.design_document_content,
+      'design_document_filename'
+    );
+  }
+
+  if (!hasPath) {
+    throw new ValidationError(
+      'record_design_approval requires either design_document_path or both design_document_content and design_document_filename'
+    );
+  }
+
+  return path.isAbsolute(params.design_document_path)
+    ? params.design_document_path
+    : path.join(projectRoot, params.design_document_path);
+}
+
+/**
+ * @param {{ session_id: string, design_document_path?: string, design_document_content?: string, design_document_filename?: string }} params
+ * @param {string} projectRoot
+ */
+function handleRecordDesignApproval(params, projectRoot) {
+  assertSessionId(params.session_id);
+  const absDesignPath = resolveApprovedDesignDocument(params, projectRoot);
+
+  const gate = readGate(projectRoot, params.session_id) || {
+    session_id: params.session_id,
+    entered_at: new Date().toISOString(),
+    approved_at: null,
+    design_document_path: null,
+  };
+  gate.approved_at = new Date().toISOString();
+  gate.design_document_path = absDesignPath;
+  writeGate(projectRoot, params.session_id, gate);
+
+  return {
+    success: true,
+    entered_at: gate.entered_at,
+    approved_at: gate.approved_at,
+    design_document_path: absDesignPath,
+  };
+}
+
+/**
+ * @param {{ session_id: string }} params
+ * @param {string} projectRoot
+ */
+function handleGetDesignGateStatus(params, projectRoot) {
+  assertSessionId(params.session_id);
+  const gate = readGate(projectRoot, params.session_id);
+  if (!gate) {
+    return {
+      session_id: params.session_id,
+      entered_at: null,
+      approved_at: null,
+      design_document_path: null,
+    };
+  }
+  return gate;
+}
+
+/**
+ * Returns true when a session has entered the design gate but not yet received approval.
+ * Used by create_session (Task 12) to block session creation until the gate is cleared.
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @returns {boolean}
+ */
+function isDesignGateBlockingCreate(projectRoot, sessionId) {
+  const gate = readGate(projectRoot, sessionId);
+  if (!gate) return false;
+  return !!(gate.entered_at && !gate.approved_at);
+}
+
+/**
+ * Returns true when a gate artifact exists on disk for the given session_id,
+ * regardless of whether it is approved. Used by the orphan-gate guard in
+ * create_session to distinguish "orchestrator never entered this session's
+ * gate" from "orchestrator is in the normal approve-then-create flow".
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @returns {boolean}
+ */
+function hasDesignGate(projectRoot, sessionId) {
+  return readGate(projectRoot, sessionId) !== null;
+}
+
+/**
+ * Read the design document path persisted on the gate after approval. Used by
+ * create_session to auto-populate `state.design_document` when the orchestrator
+ * does not pass it explicitly — avoids losing the document during archival.
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @returns {string | null}
+ */
+function getApprovedDesignDocumentPath(projectRoot, sessionId) {
+  const gate = readGate(projectRoot, sessionId);
+  if (!gate || !gate.approved_at) return null;
+  return gate.design_document_path || null;
+}
+
+/**
+ * Enumerate every approved design gate currently persisted in the workspace.
+ * Reads the `state/` directory once and parses each `<session_id>.design-gate.json`
+ * artifact. Corrupt or unapproved gate files are skipped silently. Used by
+ * create_session to detect session_id drift across the enter_design_gate →
+ * record_design_approval → create_session sequence.
+ *
+ * @param {string} projectRoot
+ * @returns {Array<{session_id: string, approved_at: string, design_document_path: string | null}>}
+ */
+function listApprovedGates(projectRoot) {
+  const stateDir = path.join(resolveStateDirPath(projectRoot), 'state');
+  if (!fs.existsSync(stateDir)) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(stateDir);
+  } catch {
+    return [];
+  }
+  const gates = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(GATE_FILENAME)) continue;
+    const sessionId = entry.slice(0, -GATE_FILENAME.length);
+    if (sessionId.length === 0) continue;
+    const filePath = path.join(stateDir, entry);
+    try {
+      const gate = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      if (gate && typeof gate.approved_at === 'string' && gate.approved_at.length > 0) {
+        gates.push({
+          session_id: sessionId,
+          approved_at: gate.approved_at,
+          design_document_path: gate.design_document_path || null,
+        });
+      }
+    } catch {
+      // unreadable or corrupt gate — skip; detection is best-effort.
+    }
+  }
+  return gates;
+}
+
+/**
+ * Find approved design gates whose session_id does not match the caller's.
+ * The orchestrator must use a single session_id from enter_design_gate through
+ * archive_session; a mismatched approved gate signals either (a) an in-flight
+ * workflow the caller forgot to continue with the original id or (b) an
+ * abandoned prior run. create_session uses this to fail fast rather than
+ * silently discard the approved design document.
+ *
+ * @param {string} projectRoot
+ * @param {string} currentSessionId
+ * @returns {Array<{session_id: string, approved_at: string, design_document_path: string | null}>}
+ */
+function findOrphanedApprovedGates(projectRoot, currentSessionId) {
+  return listApprovedGates(projectRoot).filter(
+    (gate) => gate.session_id !== currentSessionId
+  );
+}
+
+/**
+ * Remove the design-gate artifact for a session. Called by archive_session so
+ * the gate doesn't linger in state/ after the session is archived — otherwise
+ * a future session reusing the same id would inherit a stale "already approved"
+ * gate from the prior run.
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @returns {string | null} path of the removed gate file, or null if no gate existed
+ */
+function removeDesignGate(projectRoot, sessionId) {
+  const filePath = gatePath(projectRoot, sessionId);
+  if (!fs.existsSync(filePath)) return null;
+  fs.unlinkSync(filePath);
+  return filePath;
+}
+
+module.exports = {
+  handleEnterDesignGate,
+  handleRecordDesignApproval,
+  handleGetDesignGateStatus,
+  isDesignGateBlockingCreate,
+  hasDesignGate,
+  getApprovedDesignDocumentPath,
+  listApprovedGates,
+  findOrphanedApprovedGates,
+  ensureDesignDocumentInPlans,
+  writePlansDocumentContent,
+  plansDirPath,
+  removeDesignGate,
+};

package/src/mcp/handlers/get-agent.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { DEFAULT_RUNTIME_CONFIG } = require('./get-skill-content');
+const { AGENT_ALLOWLIST } = require('../content/runtime-content');
+const { createContentProvider } = require('../content/provider');
+const { ValidationError } = require('../../lib/errors');
+const { toSnakeCase, toKebabCase } = require('../../lib/naming');
+
+function createHandler(runtimeConfig = DEFAULT_RUNTIME_CONFIG, canonicalSrcRoot) {
+  return function handleGetAgent(params) {
+    const requestedAgents = params.agents;
+    if (!Array.isArray(requestedAgents) || requestedAgents.length === 0) {
+      throw new ValidationError('agents must be a non-empty array of agent identifiers');
+    }
+
+    const provider = createContentProvider(runtimeConfig, canonicalSrcRoot);
+    const agents = {};
+    const errors = {};
+
+    for (const rawName of requestedAgents) {
+      const inputName = String(rawName || '').trim();
+      const canonicalName = toKebabCase(inputName);
+
+      if (!AGENT_ALLOWLIST.includes(canonicalName)) {
+        errors[inputName || '(empty)'] =
+          `Unknown agent identifier: "${inputName}". Known identifiers: ${AGENT_ALLOWLIST.join(', ')}`;
+        continue;
+      }
+
+      const result = provider.readAgent(canonicalName);
+      if (result.error) {
+        errors[inputName] = result.error;
+        continue;
+      }
+
+      const toolName =
+        runtimeConfig.agentNaming === 'snake_case'
+          ? toSnakeCase(canonicalName)
+          : canonicalName;
+
+      agents[inputName] = { ...result.agent, tool_name: toolName };
+    }
+
+    return { agents, errors };
+  };
+}
+
+const handleGetAgent = createHandler();
+
+module.exports = {
+  AGENT_ALLOWLIST,
+  createHandler,
+  handleGetAgent,
+};

package/src/mcp/handlers/get-runtime-context.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { KNOWN_AGENTS, AGENT_CAPABILITIES } = require('../../core/agent-registry');
+const { normalizeRuntimeConfig } = require('../runtime/runtime-config-map');
+const { toKebabCase } = require('../../lib/naming');
+
+const MCP_PREFIXES = {
+  gemini: 'mcp_maestro_',
+  claude: 'mcp__plugin_maestro_maestro__',
+  codex: 'mcp__maestro_maestro__',
+};
+
+const PLAN_MODE_NATIVE = { claude: true, gemini: true, codex: false, qwen: false };
+
+function createHandler(runtimeConfig, getWorkspaceSuggestion = () => null) {
+  const resolvedRuntimeConfig = normalizeRuntimeConfig(runtimeConfig);
+  const agentNames = KNOWN_AGENTS.map((name) =>
+    resolvedRuntimeConfig.agentNaming === 'kebab-case'
+      ? toKebabCase(name)
+      : name
+  );
+
+  const prefix = resolvedRuntimeConfig.name === 'claude' ? 'maestro:' : '';
+  const delegation = resolvedRuntimeConfig.delegation || { pattern: '', constraints: {} };
+
+  return function handleGetRuntimeContext(_params) {
+    return {
+      runtime: resolvedRuntimeConfig.name,
+      tools: resolvedRuntimeConfig.tools || {},
+      agent_dispatch: {
+        pattern: delegation.pattern || '',
+        naming: resolvedRuntimeConfig.agentNaming || 'kebab-case',
+        prefix,
+      },
+      delegation: {
+        pattern: delegation.pattern || '',
+        constraints: delegation.constraints || {},
+      },
+      mcp_prefix: MCP_PREFIXES[resolvedRuntimeConfig.name] || '',
+      paths: resolvedRuntimeConfig.paths || {},
+      agents: agentNames,
+      agent_capabilities: AGENT_CAPABILITIES,
+      plan_mode_native: PLAN_MODE_NATIVE[resolvedRuntimeConfig.name] || false,
+      workspace_suggestion: getWorkspaceSuggestion() || null,
+    };
+  };
+}
+
+module.exports = { createHandler };

package/src/mcp/handlers/get-skill-content.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const { getDefaultRuntimeConfig } = require('../runtime/runtime-config-map');
+const {
+  RESOURCE_ALLOWLIST,
+  applyRuntimeTransforms,
+} = require('../content/runtime-content');
+const { createContentProvider } = require('../content/provider');
+const { ValidationError } = require('../../lib/errors');
+
+const DEFAULT_RUNTIME_CONFIG = getDefaultRuntimeConfig();
+
+function createHandler(runtimeConfig = DEFAULT_RUNTIME_CONFIG, canonicalSrcRoot) {
+  return function handleGetSkillContent(params) {
+    const resources = params.resources;
+    if (!Array.isArray(resources) || resources.length === 0) {
+      throw new ValidationError('resources must be a non-empty array of resource identifiers');
+    }
+
+    const provider = createContentProvider(runtimeConfig, canonicalSrcRoot);
+    const contents = {};
+    const errors = {};
+
+    for (const id of resources) {
+      if (!RESOURCE_ALLOWLIST[id]) {
+        errors[id] = `Unknown resource identifier: "${id}". Known identifiers: ${Object.keys(RESOURCE_ALLOWLIST).join(', ')}`;
+        continue;
+      }
+
+      const result = provider.readResource(id);
+      if (result.error) {
+        errors[id] = result.error;
+        continue;
+      }
+
+      contents[id] = result.content;
+    }
+
+    return { contents, errors };
+  };
+}
+
+const handleGetSkillContent = createHandler();
+
+module.exports = {
+  RESOURCE_ALLOWLIST,
+  DEFAULT_RUNTIME_CONFIG,
+  applyRuntimeTransforms,
+  createHandler,
+  handleGetSkillContent,
+};

package/src/mcp/handlers/initialize-workspace.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { ensureWorkspace, resolveStateDirPath } = require('../../state/session-state');
+const { resolveSetting } = require('../../config/setting-resolver');
+const {
+  requireExplicitWorkspaceRoot,
+} = require('../../core/project-root-resolver');
+const { writeWorkspaceMarker } = require('../contracts/workspace-marker');
+
+async function handleInitializeWorkspace(params = {}, cachedProjectRoot) {
+  const workspacePath =
+    params.workspace_path || cachedProjectRoot || null;
+
+  const resolvedWorkspace = requireExplicitWorkspaceRoot({
+    workspacePath,
+  });
+
+  const stateDir =
+    params.state_dir ||
+    resolveSetting('MAESTRO_STATE_DIR', resolvedWorkspace) ||
+    'docs/maestro';
+  const fullStatePath = resolveStateDirPath(resolvedWorkspace, stateDir);
+  const alreadyExisted = fs.existsSync(path.join(fullStatePath, 'state'));
+
+  ensureWorkspace(stateDir, resolvedWorkspace);
+  writeWorkspaceMarker(fullStatePath, resolvedWorkspace);
+
+  return {
+    success: true,
+    workspace_path: resolvedWorkspace,
+    state_dir: stateDir,
+    created_directories: [
+      'state/',
+      'state/archive/',
+      'plans/',
+      'plans/archive/',
+    ].map((dir) => path.join(stateDir, dir)),
+    already_existed: alreadyExisted,
+  };
+}
+
+module.exports = { handleInitializeWorkspace };