commandmate 0.16.0 → 0.18.0

package/dist/server/src/lib/session/status-mapping.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Session status vocabulary mapping (Issue #1550).
+ *
+ * The same session reality is expressed in several vocabularies:
+ *
+ * | Vocabulary          | Defined in                          | Values                                    |
+ * |---------------------|-------------------------------------|-------------------------------------------|
+ * | `SessionStatus`     | `lib/detection/status-detector.ts`  | idle / ready / running / waiting          |
+ * | `BranchStatus`      | `types/sidebar.ts`                  | idle / ready / running / waiting / generating |
+ * | boolean triple      | `lib/session/worktree-status-helper.ts` | isRunning / isWaitingForResponse / isProcessing |
+ * | `UIPhase`           | `types/ui-state.ts`                 | idle / waiting / receiving / prompt / complete |
+ *
+ * This module is the single place where those vocabularies are converted into
+ * one another, so the correspondence cannot drift between call sites. It is a
+ * pure module (type-only imports) and is therefore safe to import from client
+ * components.
+ *
+ * ## The live conversion chain
+ *
+ *   terminal output
+ *     -> detectSessionStatus()                  (status-detector, NOT touched here)
+ *     -> SessionStatus
+ *     -> sessionStatusToActivityFlags()         (this module)
+ *     -> boolean triple (+ isRunning from tmux session existence)
+ *     -> deriveCliStatus()                      (this module)
+ *     -> BranchStatus                           (sidebar / header / tab dots)
+ *
+ * `deriveSessionStatus()` is the reverse edge of that chain: the worktrees API
+ * folds the boolean triple back into a `SessionStatus` for its JSON payload.
+ *
+ * ## Why `UIPhase` has no mapping function here
+ *
+ * `UIPhase` is a state machine, not a projection of `SessionStatus`: `waiting`
+ * -> `receiving` -> `complete` is a sequence driven by user sends and streamed
+ * output, and the same `SessionStatus` can legitimately correspond to several
+ * phases depending on history. The only edge that is a pure table lookup is
+ * "an active prompt was detected -> phase `prompt`", and that edge is already
+ * expressed exactly once, by the `SHOW_PROMPT` case of `worktreeUIReducer`
+ * (`hooks/useWorktreeUIState.ts`). Re-encoding it here would add an indirection
+ * with no second call site, so the reducer stays the single owner.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionStatusToActivityFlags = sessionStatusToActivityFlags;
+exports.deriveCliStatus = deriveCliStatus;
+exports.deriveSessionStatus = deriveSessionStatus;
+exports.deriveBranchStatus = deriveBranchStatus;
+/**
+ * Project a detected `SessionStatus` onto the activity flags.
+ *
+ * `isRunning` is deliberately NOT derived here: it comes from tmux session
+ * existence (plus the Claude health check), which is independent of what the
+ * terminal output says.
+ *
+ * | SessionStatus | isWaitingForResponse | isProcessing |
+ * |---------------|----------------------|--------------|
+ * | `idle`        | false                | false        |
+ * | `ready`       | false                | false        |
+ * | `running`     | false                | true         |
+ * | `waiting`     | true                 | false        |
+ */
+function sessionStatusToActivityFlags(status) {
+    switch (status) {
+        case 'waiting':
+            return { isWaitingForResponse: true, isProcessing: false };
+        case 'running':
+            return { isWaitingForResponse: false, isProcessing: true };
+        case 'idle':
+        case 'ready':
+            return { isWaitingForResponse: false, isProcessing: false };
+        default:
+            // exhaustive check: SessionStatus extensions cause a compile error [DR2-005]
+            status;
+            return { isWaitingForResponse: false, isProcessing: false };
+    }
+}
+/**
+ * Derive `BranchStatus` from one session's boolean triple.
+ *
+ * Shared by the sidebar (`toBranchItem`), the worktree detail tab dots, the
+ * desktop header status row, Sessions and Review.
+ *
+ * Precedence is waiting > running > ready > idle: a session that is both
+ * waiting for an answer and processing is shown as `waiting`, because the user
+ * action it needs is the more significant fact.
+ *
+ * Note that `generating` is never produced here — it exists in `BranchStatus`
+ * but has no boolean-triple source. Resolving that asymmetry is out of scope
+ * for Issue #1550 (this issue only moves the conversions to one place).
+ */
+function deriveCliStatus(toolStatus) {
+    if (!toolStatus)
+        return 'idle';
+    if (toolStatus.isWaitingForResponse)
+        return 'waiting';
+    if (toolStatus.isProcessing)
+        return 'running';
+    if (toolStatus.isRunning)
+        return 'ready';
+    return 'idle';
+}
+/**
+ * Fold a worktree-level boolean triple back into a `SessionStatus` for the
+ * worktrees API payload — the reverse edge of `sessionStatusToActivityFlags`.
+ *
+ * Returns `null` (not `'idle'`) when no session is running, because the API
+ * contract distinguishes "no session" from "a session that reports idle".
+ */
+function deriveSessionStatus(status) {
+    if (!status.isSessionRunning)
+        return null;
+    if (status.isWaitingForResponse)
+        return 'waiting';
+    if (status.isProcessing)
+        return 'running';
+    return 'ready';
+}
+/**
+ * The `SessionStatus` -> `BranchStatus` correspondence, as one table.
+ *
+ * Composed from the two conversions the live chain actually uses, so it can
+ * never drift from them.
+ *
+ * | isRunning | SessionStatus | BranchStatus |
+ * |-----------|---------------|--------------|
+ * | false     | (any / null)  | `idle`       |
+ * | true      | `null`        | `ready`      |
+ * | true      | `idle`        | `ready`      |
+ * | true      | `ready`       | `ready`      |
+ * | true      | `running`     | `running`    |
+ * | true      | `waiting`     | `waiting`    |
+ *
+ * The `idle` -> `ready` row is not a mistake: once a tmux session exists, the
+ * sidebar shows `ready` (the user can send a message) even while the detector
+ * still reports `idle` for the terminal contents.
+ */
+function deriveBranchStatus(sessionStatus, isRunning) {
+    if (!isRunning)
+        return 'idle';
+    return deriveCliStatus({
+        isRunning: true,
+        ...(sessionStatus
+            ? sessionStatusToActivityFlags(sessionStatus)
+            : { isWaitingForResponse: false, isProcessing: false }),
+    });
+}

package/dist/server/src/lib/tasks/contract-parser.js

@@ -0,0 +1,385 @@
+"use strict";
+/**
+ * Loader and validator for `.commandmate/tasks/<name>.yaml` — the execution
+ * contract (Issue #1545, Phase 2-1).
+ *
+ * Canonical spec: docs/design/task-contract.md
+ *
+ * A contract declares, before the message is ever sent, what the task is for,
+ * which paths may change, what counts as done, and what the auto-answer policy
+ * is. This module only *validates and preserves* those declarations: the scope
+ * gate is #1546 and autoYes enforcement is #1547.
+ *
+ * Written in the same discipline as `lib/verification/verify-config.ts`: the
+ * `yaml` package, every violation collected rather than thrown one at a time,
+ * a closed key set, and a dedicated error class. Note that the Issue body says
+ * "ignore unknown keys" while also requiring that discipline; verify-config
+ * rejects them, and so does this. A misspelled `allowPromtTypes` that parsed
+ * cleanly would produce a contract that looks like it constrains auto-answering
+ * and does not — the worst failure a contract can have.
+ *
+ * Server-only: reads from disk, so import from API routes / CLI only.
+ *
+ * @module lib/tasks/contract-parser
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskContractError = exports.MAX_ALLOW_PROMPT_TYPES = exports.MAX_DENY_PATTERNS = exports.MAX_GATE_IDS = exports.MAX_SCOPE_PATTERNS = exports.MAX_PATTERN_LENGTH = exports.MAX_GOAL_LENGTH = exports.MAX_TITLE_LENGTH = exports.PROMPT_TYPES = exports.AUTO_YES_MODES = exports.TASK_CONTRACT_DIR = void 0;
+exports.parseTaskContract = parseTaskContract;
+exports.loadTaskContract = loadTaskContract;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+const path_validator_1 = require("../../lib/security/path-validator");
+/** Directory contracts live in, relative to the worktree root. */
+exports.TASK_CONTRACT_DIR = '.commandmate/tasks';
+/**
+ * Auto-answer policy modes.
+ *
+ * A contract that omits `autoYes.mode` leaves the mode `null`, which is *not*
+ * `off`: null means "this contract says nothing about auto-answering, keep the
+ * existing behaviour", while `off` is an active prohibition. Phase 2-3's
+ * enforcement has to be able to tell those apart.
+ */
+exports.AUTO_YES_MODES = ['off', 'safe', 'allow-listed'];
+/**
+ * Prompt-type names accepted in `autoYes.allowPromptTypes`.
+ *
+ * Built from a `Record<PromptType, true>` so the list is exhaustive by
+ * construction: adding a variant to {@link PromptType} without adding it here
+ * fails the build, instead of silently making a valid contract invalid.
+ */
+const PROMPT_TYPE_KEYS = {
+    yes_no: true,
+    multiple_choice: true,
+    approval: true,
+    choice: true,
+    input: true,
+    continue: true,
+};
+exports.PROMPT_TYPES = Object.keys(PROMPT_TYPE_KEYS);
+exports.MAX_TITLE_LENGTH = 200;
+exports.MAX_GOAL_LENGTH = 8000;
+/** Applies to scope patterns and to autoYes.denyPatterns (ReDoS bound). */
+exports.MAX_PATTERN_LENGTH = 200;
+exports.MAX_SCOPE_PATTERNS = 200;
+exports.MAX_GATE_IDS = 32;
+exports.MAX_DENY_PATTERNS = 32;
+exports.MAX_ALLOW_PROMPT_TYPES = 16;
+const TOP_LEVEL_KEYS = ['version', 'title', 'goal', 'scope', 'verify', 'autoYes', 'success'];
+const SCOPE_KEYS = ['allow', 'deny'];
+const VERIFY_KEYS = ['gates'];
+const AUTO_YES_KEYS = ['mode', 'allowPromptTypes', 'denyPatterns'];
+const SUCCESS_KEYS = ['requireWorkEvidence', 'requireScopeClean', 'autoVerifyOnStop'];
+/** Mirrors GATE_ID_PATTERN in verify-config.ts: a contract can only name ids that could exist. */
+const GATE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+class TaskContractError extends Error {
+    issues;
+    constructor(issues) {
+        super(`invalid task contract:\n${issues.map((issue) => `  - ${issue}`).join('\n')}`);
+        this.name = 'TaskContractError';
+        this.issues = issues;
+    }
+}
+exports.TaskContractError = TaskContractError;
+function isMapping(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asInteger(value) {
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? value : null;
+    if (typeof value === 'string' && /^-?\d+$/.test(value))
+        return Number(value);
+    return null;
+}
+function asBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return null;
+}
+function describe(value) {
+    if (value === undefined)
+        return 'nothing';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return 'a list';
+    if (typeof value === 'object')
+        return 'a mapping';
+    return String(value);
+}
+function collectUnknownKeys(mapping, allowed, at, issues) {
+    for (const key of Object.keys(mapping)) {
+        if (!allowed.includes(key)) {
+            issues.push(`${at}: unknown key "${key}" (v1 is a closed set)`);
+        }
+    }
+}
+/**
+ * Validate a list of strings, rejecting per-entry violations individually.
+ *
+ * @returns the accepted entries; entries that produced an issue are dropped so
+ *          the returned contract never carries a value that failed validation
+ */
+function validateStringList(value, at, limits, issues) {
+    if (value === undefined)
+        return null;
+    if (value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        issues.push(`${at}: must be a list (got ${describe(value)})`);
+        return null;
+    }
+    if (value.length > limits.maxEntries) {
+        issues.push(`${at}: at most ${limits.maxEntries} entries (got ${value.length})`);
+        return null;
+    }
+    const accepted = [];
+    value.forEach((entry, index) => {
+        const entryAt = `${at}[${index}]`;
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            issues.push(`${entryAt}: must be a non-empty string (got ${describe(entry)})`);
+            return;
+        }
+        if (entry.length > limits.maxLength) {
+            issues.push(`${entryAt}: at most ${limits.maxLength} characters (got ${entry.length})`);
+            return;
+        }
+        accepted.push(entry);
+    });
+    return accepted;
+}
+/**
+ * A scope pattern can only speak about the inside of the worktree.
+ *
+ * An absolute path or a `..` segment is unjudgeable by the Phase 2-2 gate, and
+ * a NUL byte is never a path — all three are rejected at declaration time
+ * rather than becoming a pattern that silently matches nothing.
+ */
+function validateScopePattern(pattern, at, issues) {
+    if (pattern.includes('\0')) {
+        issues.push(`${at}: must not contain a NUL byte`);
+        return;
+    }
+    if (pattern.startsWith('/')) {
+        issues.push(`${at}: must be relative to the worktree root (got the absolute path "${pattern}")`);
+        return;
+    }
+    if (pattern.split('/').includes('..')) {
+        issues.push(`${at}: must not escape the worktree root with ".." (got "${pattern}")`);
+    }
+}
+function validateScope(value, issues) {
+    const scope = { allow: [], deny: [] };
+    if (value === undefined || value === null)
+        return scope;
+    if (!isMapping(value)) {
+        issues.push(`scope: must be a mapping (got ${describe(value)})`);
+        return scope;
+    }
+    collectUnknownKeys(value, SCOPE_KEYS, 'scope', issues);
+    const limits = { maxEntries: exports.MAX_SCOPE_PATTERNS, maxLength: exports.MAX_PATTERN_LENGTH };
+    for (const key of ['allow', 'deny']) {
+        const list = validateStringList(value[key], `scope.${key}`, limits, issues);
+        if (!list)
+            continue;
+        list.forEach((pattern, index) => validateScopePattern(pattern, `scope.${key}[${index}]`, issues));
+        scope[key] = list;
+    }
+    return scope;
+}
+function validateVerify(value, issues) {
+    if (value === undefined || value === null)
+        return { gates: null };
+    if (!isMapping(value)) {
+        issues.push(`verify: must be a mapping (got ${describe(value)})`);
+        return { gates: null };
+    }
+    collectUnknownKeys(value, VERIFY_KEYS, 'verify', issues);
+    if (value.gates === undefined || value.gates === null)
+        return { gates: null };
+    const gates = validateStringList(value.gates, 'verify.gates', { maxEntries: exports.MAX_GATE_IDS, maxLength: 32 }, issues);
+    if (!gates)
+        return { gates: null };
+    // An empty list would read as "pass with no gates run". "Run everything" is
+    // spelled by omitting the key, so the two can never be confused.
+    if (Array.isArray(value.gates) && value.gates.length === 0) {
+        issues.push('verify.gates: must name at least one gate (omit the key to run every gate)');
+        return { gates: null };
+    }
+    const valid = [];
+    const seen = new Set();
+    gates.forEach((id, index) => {
+        if (!GATE_ID_PATTERN.test(id)) {
+            issues.push(`verify.gates[${index}]: "${id}" must match ${GATE_ID_PATTERN.source}`);
+            return;
+        }
+        if (seen.has(id)) {
+            issues.push(`verify.gates[${index}]: duplicate gate id "${id}"`);
+            return;
+        }
+        seen.add(id);
+        valid.push(id);
+    });
+    return { gates: valid.length > 0 ? valid : null };
+}
+function validateAutoYes(value, issues) {
+    const autoYes = { mode: null, allowPromptTypes: [], denyPatterns: [] };
+    if (value === undefined || value === null)
+        return autoYes;
+    if (!isMapping(value)) {
+        issues.push(`autoYes: must be a mapping (got ${describe(value)})`);
+        return autoYes;
+    }
+    collectUnknownKeys(value, AUTO_YES_KEYS, 'autoYes', issues);
+    if (value.mode !== undefined && value.mode !== null) {
+        if (typeof value.mode !== 'string' ||
+            !exports.AUTO_YES_MODES.includes(value.mode)) {
+            issues.push(`autoYes.mode: must be one of ${exports.AUTO_YES_MODES.join(', ')} (got ${describe(value.mode)})`);
+        }
+        else {
+            autoYes.mode = value.mode;
+        }
+    }
+    const promptTypes = validateStringList(value.allowPromptTypes, 'autoYes.allowPromptTypes', { maxEntries: exports.MAX_ALLOW_PROMPT_TYPES, maxLength: 64 }, issues);
+    if (promptTypes) {
+        promptTypes.forEach((type, index) => {
+            if (!exports.PROMPT_TYPES.includes(type)) {
+                issues.push(`autoYes.allowPromptTypes[${index}]: unknown prompt type "${type}" ` +
+                    `(known: ${exports.PROMPT_TYPES.join(', ')})`);
+                return;
+            }
+            autoYes.allowPromptTypes.push(type);
+        });
+    }
+    const denyPatterns = validateStringList(value.denyPatterns, 'autoYes.denyPatterns', { maxEntries: exports.MAX_DENY_PATTERNS, maxLength: exports.MAX_PATTERN_LENGTH }, issues);
+    if (denyPatterns) {
+        denyPatterns.forEach((pattern, index) => {
+            try {
+                new RegExp(pattern);
+            }
+            catch (error) {
+                issues.push(`autoYes.denyPatterns[${index}]: not a valid regular expression: ${error.message}`);
+                return;
+            }
+            autoYes.denyPatterns.push(pattern);
+        });
+    }
+    return autoYes;
+}
+function validateSuccess(value, issues) {
+    const success = {
+        requireWorkEvidence: true,
+        requireScopeClean: true,
+        autoVerifyOnStop: false,
+    };
+    if (value === undefined || value === null)
+        return success;
+    if (!isMapping(value)) {
+        issues.push(`success: must be a mapping (got ${describe(value)})`);
+        return success;
+    }
+    collectUnknownKeys(value, SUCCESS_KEYS, 'success', issues);
+    for (const key of SUCCESS_KEYS) {
+        if (value[key] === undefined)
+            continue;
+        const parsed = asBoolean(value[key]);
+        if (parsed === null) {
+            issues.push(`success.${key}: must be true or false (got ${describe(value[key])})`);
+            continue;
+        }
+        success[key] = parsed;
+    }
+    return success;
+}
+function validateText(value, key, maxLength, issues) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        issues.push(`${key}: required, must be a non-empty string (got ${describe(value)})`);
+        return '';
+    }
+    if (value.length > maxLength) {
+        issues.push(`${key}: at most ${maxLength} characters (got ${value.length})`);
+        return '';
+    }
+    return value.trim();
+}
+/**
+ * Parse and validate a contract document.
+ *
+ * @param raw YAML source
+ * @param sourceLabel path or label used to prefix document-level issues
+ * @throws TaskContractError with every violation collected in `issues`
+ */
+function parseTaskContract(raw, sourceLabel) {
+    let document;
+    try {
+        document = (0, yaml_1.parse)(raw);
+    }
+    catch (error) {
+        throw new TaskContractError([`${sourceLabel}: YAML parse error: ${error.message}`]);
+    }
+    if (!isMapping(document)) {
+        throw new TaskContractError([
+            `${sourceLabel}: expected a YAML mapping at the top level (got ${describe(document)})`,
+        ]);
+    }
+    const issues = [];
+    collectUnknownKeys(document, TOP_LEVEL_KEYS, 'top level', issues);
+    if (!('version' in document)) {
+        issues.push('version: required, v1 contracts must declare "version: 1"');
+    }
+    else if (asInteger(document.version) !== 1) {
+        issues.push(`version: must be 1 (got ${describe(document.version)})`);
+    }
+    const title = validateText(document.title, 'title', exports.MAX_TITLE_LENGTH, issues);
+    const goal = validateText(document.goal, 'goal', exports.MAX_GOAL_LENGTH, issues);
+    const success = validateSuccess(document.success, issues);
+    const scope = validateScope(document.scope, issues);
+    const verify = validateVerify(document.verify, issues);
+    const autoYes = validateAutoYes(document.autoYes, issues);
+    // Checked after both sections are parsed: "keep changes inside scope" with no
+    // scope listed makes the Phase 2-2 gate reject every change the moment it
+    // switches on, so the contract is rejected now instead.
+    if (success.requireScopeClean && scope.allow.length === 0) {
+        issues.push('scope.allow: at least one pattern is required while success.requireScopeClean is true');
+    }
+    if (issues.length > 0)
+        throw new TaskContractError(issues);
+    return { version: 1, title, goal, scope, verify, autoYes, success };
+}
+/**
+ * Read and validate a contract inside a worktree.
+ *
+ * `relativePath` is resolved against `worktreePath` and must stay inside it: a
+ * contract is a statement about one worktree, and a path that leaves it would
+ * let a send read an arbitrary file off the server's disk.
+ *
+ * @throws TaskContractError when the path escapes, the file is unreadable, or
+ *         the document is invalid
+ */
+function loadTaskContract(worktreePath, relativePath) {
+    if (!(0, path_validator_1.isPathSafe)(relativePath, worktreePath)) {
+        throw new TaskContractError([
+            `${relativePath}: contract path must be inside the worktree (${worktreePath})`,
+        ]);
+    }
+    const absolutePath = (0, path_1.join)(worktreePath, relativePath);
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(absolutePath, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        throw new TaskContractError([
+            code === 'ENOENT'
+                ? `${relativePath}: contract file not found in ${worktreePath}`
+                : `${relativePath}: ${error.message}`,
+        ]);
+    }
+    return parseTaskContract(raw, relativePath);
+}