@josstei/maestro 1.6.4-rc.1

package/claude/src/mcp/handlers/reconciliation.js

@@ -0,0 +1,224 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { assertSessionId } = require('../../lib/validation');
+const { ValidationError, NotFoundError, StateError } = require('../../lib/errors');
+const { readActiveSession, withSessionState } = require('./session-state-core');
+const { isExtensionCachePath } = require('../contracts/cache-path-rejector');
+const { isValidPhaseId } = require('../contracts/plan-schema');
+const {
+  normalizeDownstreamContext,
+  isDownstreamContextPopulated,
+} = require('../contracts/downstream-context');
+
+const DEFAULT_IGNORE_DIRS = new Set([
+  '.git',
+  'node_modules',
+  '.worktrees',
+  '.claude',
+]);
+const DOCS_MAESTRO = path.join('docs', 'maestro');
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string[]}
+ */
+function parseIgnoreEnv(env = process.env) {
+  const raw = env.MAESTRO_SCAN_IGNORE;
+  if (!raw) return [];
+  return raw
+    .split(':')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+/**
+ * @param {string} relPath
+ * @param {string} name
+ * @returns {boolean}
+ */
+function shouldSkipDir(relPath, name) {
+  if (DEFAULT_IGNORE_DIRS.has(name)) return true;
+  if (relPath === DOCS_MAESTRO) return true;
+  if (isExtensionCachePath(relPath)) return true;
+  return false;
+}
+
+/**
+ * @param {string} workspace
+ * @param {string} startedAt
+ * @param {number} maxFiles
+ * @param {string[]} extraIgnore
+ * @returns {{ created: string[], modified: string[], ignored: Array<{path: string, reason: string}>, truncated: boolean }}
+ */
+function scanWorkspace(workspace, startedAt, maxFiles, extraIgnore) {
+  const startedMs = Date.parse(startedAt);
+  const ignored = [];
+  const created = [];
+  const modified = [];
+  let truncated = false;
+  let seen = 0;
+
+  function walk(dir, relDir) {
+    if (seen >= maxFiles) {
+      truncated = true;
+      return;
+    }
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (seen >= maxFiles) {
+        truncated = true;
+        return;
+      }
+      const absPath = path.join(dir, entry.name);
+      const relPath = relDir ? path.join(relDir, entry.name) : entry.name;
+      if (entry.isDirectory()) {
+        if (shouldSkipDir(relPath, entry.name) || extraIgnore.some((i) => relPath.startsWith(i))) {
+          ignored.push({ path: relPath, reason: 'ignored directory' });
+          continue;
+        }
+        walk(absPath, relPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      seen += 1;
+      let stat;
+      try {
+        stat = fs.statSync(absPath);
+      } catch {
+        continue;
+      }
+      const mtimeMs = stat.mtimeMs || 0;
+      const birthtimeMs = stat.birthtimeMs || 0;
+      const isNewByBirthtime = birthtimeMs > 0 && birthtimeMs >= startedMs;
+      const isNewByMtime = birthtimeMs === 0 && mtimeMs >= startedMs;
+      if (isNewByBirthtime || isNewByMtime) {
+        created.push(relPath);
+      } else if (mtimeMs >= startedMs) {
+        modified.push(relPath);
+      }
+    }
+  }
+
+  walk(workspace, '');
+  return { created, modified, ignored, truncated };
+}
+
+/**
+ * @param {{ session_id: string, phase_id: number }} params
+ * @param {string} projectRoot
+ */
+function handleScanPhaseChanges(params, projectRoot) {
+  assertSessionId(params.session_id);
+  if (!isValidPhaseId(params.phase_id)) {
+    throw new ValidationError(
+      'phase_id must be a positive integer or a non-empty string'
+    );
+  }
+  const { state } = readActiveSession(projectRoot);
+
+  if (state.session_id !== params.session_id) {
+    throw new StateError(
+      `Session mismatch: active session is '${state.session_id}', got '${params.session_id}'`
+    );
+  }
+
+  const phase = (state.phases || []).find((p) => p.id === params.phase_id);
+  if (!phase) {
+    throw new NotFoundError(`Phase ${params.phase_id} not found in session state`);
+  }
+  if (!phase.started) {
+    throw new StateError(
+      `Phase ${params.phase_id} has not started; nothing to scan`
+    );
+  }
+  const maxFiles = Number(process.env.MAESTRO_SCAN_MAX_FILES || 5000);
+  const extraIgnore = parseIgnoreEnv();
+  const result = scanWorkspace(projectRoot, phase.started, maxFiles, extraIgnore);
+
+  return {
+    phase_id: phase.id,
+    started_at: phase.started,
+    scanned_at: new Date().toISOString(),
+    candidates: { created: result.created.sort(), modified: result.modified.sort() },
+    ignored_count: result.ignored.length,
+    truncated: result.truncated,
+    max_files: maxFiles,
+  };
+}
+
+/**
+ * @param {{ session_id: string, phase_id: number, files_created?: string[], files_modified?: string[], files_deleted?: string[], downstream_context?: object, reason?: string }} params
+ * @param {string} projectRoot
+ */
+function handleReconcilePhase(params, projectRoot) {
+  assertSessionId(params.session_id);
+  if (!isValidPhaseId(params.phase_id)) {
+    throw new ValidationError(
+      'phase_id must be a positive integer or a non-empty string'
+    );
+  }
+
+  const filesCreated = Array.isArray(params.files_created) ? params.files_created : [];
+  const filesModified = Array.isArray(params.files_modified) ? params.files_modified : [];
+  const filesDeleted = Array.isArray(params.files_deleted) ? params.files_deleted : [];
+  const hasFilesPayload =
+    filesCreated.length + filesModified.length + filesDeleted.length > 0;
+  const normalizedContext = normalizeDownstreamContext(params.downstream_context);
+  const hasContextPayload = isDownstreamContextPopulated(normalizedContext);
+
+  if (!hasFilesPayload && !hasContextPayload) {
+    throw new ValidationError(
+      'reconcile_phase requires at least one of files_created, files_modified, files_deleted, or a populated downstream_context. An empty payload cannot clear requires_reconciliation.',
+      { code: 'RECONCILIATION_EMPTY_PAYLOAD' }
+    );
+  }
+
+  return withSessionState(projectRoot, ({ state }) => {
+    if (state.session_id !== params.session_id) {
+      throw new StateError(
+        `Session mismatch: active session is '${state.session_id}', got '${params.session_id}'`
+      );
+    }
+
+    const phase = (state.phases || []).find((p) => p.id === params.phase_id);
+    if (!phase) {
+      throw new NotFoundError(`Phase ${params.phase_id} not found`);
+    }
+    if (params.files_created !== undefined) {
+      phase.files_created = filesCreated;
+    }
+    if (params.files_modified !== undefined) {
+      phase.files_modified = filesModified;
+    }
+    if (params.files_deleted !== undefined) {
+      phase.files_deleted = filesDeleted;
+    }
+    if (hasContextPayload) {
+      phase.downstream_context = normalizedContext;
+    }
+    phase.requires_reconciliation = false;
+    if (params.reason) {
+      phase.reconciliation_reason = params.reason;
+    }
+    state.updated = new Date().toISOString();
+    return {
+      response: {
+        success: true,
+        phase_id: phase.id,
+        files_created: phase.files_created,
+        files_modified: phase.files_modified,
+      },
+      writeBack: true,
+    };
+  });
+}
+
+module.exports = { handleScanPhaseChanges, handleReconcilePhase };

package/claude/src/mcp/handlers/resolve-settings.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const { resolveSetting } = require('../../config/setting-resolver');
+
+const KNOWN_SETTINGS = [
+  'MAESTRO_DISABLED_AGENTS',
+  'MAESTRO_MAX_RETRIES',
+  'MAESTRO_AUTO_ARCHIVE',
+  'MAESTRO_VALIDATION_STRICTNESS',
+  'MAESTRO_STATE_DIR',
+  'MAESTRO_MAX_CONCURRENT',
+  'MAESTRO_EXECUTION_MODE',
+];
+
+function handleResolveSettings(params, projectRoot) {
+  const requested =
+    Array.isArray(params.settings) && params.settings.length > 0
+      ? params.settings.filter((name) => KNOWN_SETTINGS.includes(name))
+      : KNOWN_SETTINGS;
+
+  const settings = {};
+  for (const name of requested) {
+    settings[name] = resolveSetting(name, projectRoot) ?? null;
+  }
+
+  return {
+    settings,
+    disabled_agents: settings.MAESTRO_DISABLED_AGENTS
+      ? settings.MAESTRO_DISABLED_AGENTS.split(',')
+          .map((value) => value.trim())
+          .filter(Boolean)
+      : [],
+  };
+}
+
+module.exports = {
+  KNOWN_SETTINGS,
+  handleResolveSettings,
+};

package/claude/src/mcp/handlers/session-state-core.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const markdownState = require('../../core/markdown-state');
+const {
+  readState,
+  writeState,
+  resolveStateDirPath,
+} = require('../../state/session-state');
+
+const ACTIVE_SESSION_REL = path.join('state', 'active-session.md');
+
+function resolveBasePath(projectRoot) {
+  return resolveStateDirPath(projectRoot);
+}
+
+function resolveActiveSessionPath(basePath) {
+  return path.join(basePath, ACTIVE_SESSION_REL);
+}
+
+function parseSessionState(content) {
+  return markdownState.parse(content).data;
+}
+
+function serializeSessionState(data, bodyContent) {
+  return markdownState.serialize(data, bodyContent);
+}
+
+function extractBody(content) {
+  return markdownState.parse(content).body;
+}
+
+function readActiveSession(projectRoot) {
+  const basePath = resolveBasePath(projectRoot);
+  const content = readState(ACTIVE_SESSION_REL, basePath);
+  return {
+    basePath,
+    sessionPath: resolveActiveSessionPath(basePath),
+    content,
+    state: parseSessionState(content),
+  };
+}
+
+function readActiveSessionOrNull(projectRoot) {
+  const basePath = resolveBasePath(projectRoot);
+  const sessionPath = resolveActiveSessionPath(basePath);
+  if (!fs.existsSync(sessionPath)) {
+    return null;
+  }
+  const content = readState(ACTIVE_SESSION_REL, basePath);
+  return {
+    basePath,
+    sessionPath,
+    content,
+    state: parseSessionState(content),
+  };
+}
+
+function writeActiveSession(basePath, state, body) {
+  writeState(ACTIVE_SESSION_REL, serializeSessionState(state, body), basePath);
+}
+
+/**
+ * Read the active session, run a mutator against it, and conditionally
+ * persist the result. Callers MUST return an outcome object of shape
+ * `{ response, writeBack, body? }`:
+ *
+ *   - `response` is what `withSessionState` will return to the caller.
+ *   - `writeBack: true` persists the (mutated-in-place) state; the body
+ *     defaults to the existing body unless `body` is set explicitly.
+ *   - For read-only flows, return `{ response, writeBack: false }` (or
+ *     simply `{ response }`) — do NOT rely on returning `undefined` to
+ *     signal read-only, because the coalesce below silently discards
+ *     any in-memory state mutation the caller made before returning.
+ *
+ * Returning `undefined` is tolerated (the coalesce falls back to `{}`
+ * so the helper does not crash), but it is a footgun: a mutator that
+ * mutates `session.state` in place and forgets to return
+ * `{ writeBack: true }` will see its mutation silently dropped. Always
+ * return an explicit outcome object.
+ */
+function withSessionState(projectRoot, mutator) {
+  const session = readActiveSession(projectRoot);
+  const outcome = mutator(session) || {};
+
+  if (outcome.writeBack) {
+    const body =
+      Object.prototype.hasOwnProperty.call(outcome, 'body')
+        ? outcome.body
+        : extractBody(session.content);
+    writeActiveSession(session.basePath, session.state, body);
+  }
+
+  return outcome.response;
+}
+
+module.exports = {
+  resolveBasePath,
+  resolveActiveSessionPath,
+  parseSessionState,
+  serializeSessionState,
+  extractBody,
+  readActiveSession,
+  readActiveSessionOrNull,
+  writeActiveSession,
+  withSessionState,
+};