commandmate 0.11.4 → 0.12.1

package/dist/server/src/lib/skills/operation-reconciler.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Crash reconciliation for Skill operations (Issue #1234)
+ *
+ * Runs at startup and on demand. For every journal entry that is not terminal
+ * it asks one question — *did the payload actually land?* — and drives the entry
+ * to the answer the filesystem already gave:
+ *
+ * - payload present  → replay the index step, converge on SUCCEEDED
+ * - payload absent   → FAILED_RECONCILABLE, the operation is genuinely undone
+ *
+ * The DB is never treated as the source of truth: an operation that committed
+ * to the filesystem and then lost its DB write is *installed*, and reporting it
+ * as failed would be a lie the user could see on disk.
+ *
+ * Payload probing and index rebuilding are injected ports, because this issue
+ * deliberately does not implement payload installation (#1235 owns that).
+ *
+ * @module lib/skills/operation-reconciler
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileSkillOperation = reconcileSkillOperation;
+exports.reconcileSkillOperations = reconcileSkillOperations;
+const operation_lock_1 = require("../../lib/skills/operation-lock");
+const operation_journal_1 = require("../../lib/skills/operation-journal");
+const operation_audit_1 = require("../../lib/skills/operation-audit");
+function toError(error) {
+    return {
+        code: 'SKILL_RECONCILE_FAILED',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+/**
+ * Whether an entry is currently owned by a running operation.
+ *
+ * A lock held by a live owner means the process is still working; reconciling
+ * underneath it would race the very write it is performing.
+ */
+function isLockedByLiveOwner(entry, options) {
+    const record = (0, operation_lock_1.readSkillOperationLock)(entry.lockKey, options);
+    if (record === null)
+        return false;
+    if (record.operationId !== entry.operationId)
+        return false;
+    const disposition = (0, operation_lock_1.evaluateSkillLock)(record, options);
+    return disposition === 'HELD' || disposition === 'HELD_BY_LIVE_OWNER';
+}
+/** Drive one journal entry to its final state. */
+function reconcileSkillOperation(entry, ports, options = {}) {
+    const from = entry.state;
+    const base = { operationId: entry.operationId, idempotencyKey: entry.idempotencyKey, from };
+    if ((0, operation_journal_1.isSkillOperationTerminal)(entry)) {
+        return { ...base, to: from, action: 'SKIPPED_TERMINAL' };
+    }
+    if (isLockedByLiveOwner(entry, options)) {
+        return { ...base, to: from, action: 'SKIPPED_LOCK_HELD' };
+    }
+    // The journal may have crashed before recording the commit, so the filesystem
+    // is consulted even for PREPARING rather than trusting the last written state.
+    const committed = (0, operation_journal_1.hasSkillFilesystemCommit)(entry) || ports.hasCommittedPayload(entry);
+    if (!committed) {
+        if (from === 'FAILED_RECONCILABLE') {
+            return { ...base, to: from, action: 'CONVERGED_FAILED' };
+        }
+        const failed = (0, operation_journal_1.transitionSkillOperation)(entry, 'FAILED_RECONCILABLE', { error: { code: 'SKILL_OPERATION_ROLLED_BACK', message: 'no payload was committed' } }, options);
+        ports.recordAudit((0, operation_audit_1.buildSkillOperationAuditInput)(failed, 'failed', options.now));
+        return { ...base, to: failed.state, action: 'CONVERGED_FAILED' };
+    }
+    let current = entry;
+    try {
+        if (current.state === 'PREPARING') {
+            current = (0, operation_journal_1.transitionSkillOperation)(current, 'FS_COMMITTED', {}, options);
+        }
+        ports.reindex(current);
+        if (current.state !== 'INDEXED') {
+            current = (0, operation_journal_1.transitionSkillOperation)(current, 'INDEXED', {}, options);
+        }
+        current = (0, operation_journal_1.transitionSkillOperation)(current, 'SUCCEEDED', { error: null }, options);
+    }
+    catch (error) {
+        const stalled = (0, operation_journal_1.transitionSkillOperation)(current, 'FAILED_RECONCILABLE', { error: toError(error) }, options);
+        ports.recordAudit((0, operation_audit_1.buildSkillOperationAuditInput)(stalled, 'failed', options.now));
+        return { ...base, to: stalled.state, action: 'RECONCILE_FAILED' };
+    }
+    ports.recordAudit((0, operation_audit_1.buildSkillOperationAuditInput)(current, 'reconciled', options.now));
+    return { ...base, to: current.state, action: 'CONVERGED_SUCCEEDED' };
+}
+/**
+ * Reconcile every journal entry and clean up locks whose owner is verifiably
+ * gone. Called at startup so a restart restores a single, explainable answer
+ * for each operation (UX-06/UX-07).
+ */
+function reconcileSkillOperations(ports, options = {}) {
+    const outcomes = (0, operation_journal_1.listSkillOperationJournal)(options).map((entry) => reconcileSkillOperation(entry, ports, options));
+    // Locks are cleaned after reconciliation: an entry still owned by a live
+    // process must be observed as locked, not as an orphan.
+    const orphanLocksReleased = options.skipOrphanLocks ? [] : (0, operation_lock_1.releaseOrphanSkillLocks)(options);
+    return {
+        scanned: outcomes.length,
+        converged: outcomes.filter((o) => o.action === 'CONVERGED_SUCCEEDED').length,
+        failed: outcomes.filter((o) => o.action === 'CONVERGED_FAILED' || o.action === 'RECONCILE_FAILED')
+            .length,
+        skipped: outcomes.filter((o) => o.action === 'SKIPPED_TERMINAL' || o.action === 'SKIPPED_LOCK_HELD').length,
+        orphanLocksReleased,
+        outcomes,
+    };
+}

package/dist/server/src/lib/skills/operation-store.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Service-owned state layout for Skill operations (Issue #1234)
+ *
+ * Two staging areas exist and must not be confused:
+ * - *Package* staging is service-owned. It lives under the CommandMate config
+ *   root (0700), never inside a repository, and is never visible to an Agent.
+ * - *Install commit* staging is worktree-local, because the commit point is an
+ *   atomic rename and rename only works within one filesystem. It uses the
+ *   reserved `.agents/skills/.commandmate-staging/` namespace, which callers
+ *   must exclude from Skill discovery, installed status and diff previews.
+ *
+ * Every file written here is 0600 under a 0700 directory and is written through
+ * a temp+rename so a crash can never leave a half-parsed record behind.
+ *
+ * @module lib/skills/operation-store
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_INSTALL_STAGING_REL_PATHS = exports.SKILL_INSTALL_STAGING_REL_PATH = exports.SKILL_REDACTED_TEXT_MAX_LENGTH = exports.SKILL_STATE_FILE_MODE = exports.SKILL_STATE_DIR_MODE = exports.SKILL_PACKAGE_STAGING_DIRNAME = exports.SKILL_JOURNAL_DIRNAME = exports.SKILL_LOCK_DIRNAME = exports.SKILL_STATE_DIRNAME = void 0;
+exports.getSkillStateRoot = getSkillStateRoot;
+exports.ensureSkillStateDir = ensureSkillStateDir;
+exports.getSkillPackageStagingRoot = getSkillPackageStagingRoot;
+exports.getSkillInstallStagingRoot = getSkillInstallStagingRoot;
+exports.isSkillInstallStagingPath = isSkillInstallStagingPath;
+exports.redactSkillOperationText = redactSkillOperationText;
+exports.writeSkillStateFile = writeSkillStateFile;
+exports.readSkillStateFile = readSkillStateFile;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const constants_1 = require("../../lib/skills/constants");
+const install_context_1 = require("../../cli/utils/install-context");
+/** Directory under the config root that holds all Skill operation state. */
+exports.SKILL_STATE_DIRNAME = 'skills';
+/** Sub-directory holding one lock file per (worktree, skill) pair. */
+exports.SKILL_LOCK_DIRNAME = 'locks';
+/** Sub-directory holding one journal file per operation. */
+exports.SKILL_JOURNAL_DIRNAME = 'journal';
+/** Sub-directory holding service-owned package staging (downloads, extraction). */
+exports.SKILL_PACKAGE_STAGING_DIRNAME = 'package-staging';
+/** Owner-only directory mode. */
+exports.SKILL_STATE_DIR_MODE = 0o700;
+/** Owner-only file mode. */
+exports.SKILL_STATE_FILE_MODE = 0o600;
+/** Maximum length of any redacted string persisted to a journal or audit row. */
+exports.SKILL_REDACTED_TEXT_MAX_LENGTH = 500;
+/**
+ * Root of all Skill operation state, inside the CommandMate config directory.
+ * Never inside a repository, so nothing here is reachable as Skill payload.
+ */
+function getSkillStateRoot(options = {}) {
+    return options.root ?? (0, path_1.join)((0, install_context_1.ensureConfigDir)(), exports.SKILL_STATE_DIRNAME);
+}
+/** Create (if needed) and return a 0700 directory under the state root. */
+function ensureSkillStateDir(segment, options = {}) {
+    const dir = (0, path_1.join)(getSkillStateRoot(options), segment);
+    (0, fs_1.mkdirSync)(dir, { recursive: true, mode: exports.SKILL_STATE_DIR_MODE });
+    // mkdir's mode is masked by umask, so a 0022 umask would leave 0755 behind.
+    (0, fs_1.chmodSync)(dir, exports.SKILL_STATE_DIR_MODE);
+    return dir;
+}
+/** Service-owned package staging directory (downloads and extraction). */
+function getSkillPackageStagingRoot(options = {}) {
+    return ensureSkillStateDir(exports.SKILL_PACKAGE_STAGING_DIRNAME, options);
+}
+/**
+ * Worktree-local install commit staging root, under one install root prefix.
+ *
+ * Each install root gets its own staging namespace so the atomic rename stays on
+ * the same filesystem as *that* root's destination (#1460). The default is the
+ * primary `.agents/skills` root, preserving the single-root callers.
+ *
+ * @param worktreePath - Absolute path of a *server-resolved* worktree. Callers
+ *   must never pass a client-supplied path.
+ * @param rootPrefix - Install root prefix; defaults to the primary root.
+ */
+function getSkillInstallStagingRoot(worktreePath, rootPrefix = constants_1.SKILL_INSTALL_ROOT_PREFIX) {
+    return (0, path_1.join)(worktreePath, rootPrefix, constants_1.SKILL_STAGING_DIRNAME);
+}
+/** Repository-relative form of the reserved install staging root (primary). */
+exports.SKILL_INSTALL_STAGING_REL_PATH = `${constants_1.SKILL_INSTALL_ROOT_PREFIX}/${constants_1.SKILL_STAGING_DIRNAME}`;
+/** Repository-relative staging namespace under every install root prefix (#1460). */
+exports.SKILL_INSTALL_STAGING_REL_PATHS = constants_1.SKILL_INSTALL_ROOT_PREFIXES.map((prefix) => `${prefix}/${constants_1.SKILL_STAGING_DIRNAME}`);
+/**
+ * Whether a repository-relative path belongs to a reserved install staging
+ * namespace under any install root. Slash-command loading, installed status and
+ * diff previews must treat a true result as "not payload".
+ */
+function isSkillInstallStagingPath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+    return exports.SKILL_INSTALL_STAGING_REL_PATHS.some((rel) => normalized === rel || normalized.startsWith(`${rel}/`));
+}
+/**
+ * Strip secrets and machine identity from free text before it is persisted.
+ *
+ * Journals and audit rows are read by support flows and may be exported, so a
+ * signed URL query, a bearer token or a home directory path must not survive
+ * into them. Structured fields (digests, refs) are stored in their own columns
+ * and never routed through here.
+ */
+function redactSkillOperationText(value) {
+    let text = value;
+    // URLs first: keep origin+path (useful for diagnosis), drop userinfo, query
+    // and fragment (where signed-URL credentials live).
+    text = text.replace(/https?:\/\/\S+/gi, (match) => {
+        try {
+            const url = new URL(match);
+            return `${url.protocol}//${url.host}${url.pathname}`;
+        }
+        catch {
+            return '[url]';
+        }
+    });
+    text = text.replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, '[redacted]');
+    text = text.replace(/\bgh[pousr]_[A-Za-z0-9]{16,}\b/g, '[redacted]');
+    text = text.replace(/\bgithub_pat_[A-Za-z0-9_]{16,}\b/g, '[redacted]');
+    text = text.replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, '[redacted]');
+    text = text.replace(/\b(token|secret|password|api[_-]?key|authorization)\s*[=:]\s*\S+/gi, '$1=[redacted]');
+    // Machine-absolute paths. The leading boundary keeps this from re-matching the
+    // pathname of a URL already normalized above.
+    text = text.replace(/(^|[\s"'(\[<])(\/[A-Za-z0-9._@+-]+){2,}\/?/g, '$1[path]');
+    text = text.replace(/(^|[\s"'(\[<])[A-Za-z]:\\[^\s"'\])>]*/g, '$1[path]');
+    return text.length > exports.SKILL_REDACTED_TEXT_MAX_LENGTH
+        ? `${text.slice(0, exports.SKILL_REDACTED_TEXT_MAX_LENGTH)}…`
+        : text;
+}
+/** Write JSON atomically as a 0600 file. */
+function writeSkillStateFile(filePath, payload) {
+    const tempPath = `${filePath}.tmp-${(0, crypto_1.randomBytes)(8).toString('hex')}`;
+    (0, fs_1.writeFileSync)(tempPath, JSON.stringify(payload), { mode: exports.SKILL_STATE_FILE_MODE });
+    (0, fs_1.chmodSync)(tempPath, exports.SKILL_STATE_FILE_MODE);
+    try {
+        (0, fs_1.renameSync)(tempPath, filePath);
+    }
+    catch (error) {
+        try {
+            (0, fs_1.unlinkSync)(tempPath);
+        }
+        catch {
+            // Best effort: the temp file is namespaced and reconciliation ignores it.
+        }
+        throw error;
+    }
+}
+/** Read and parse a state file. Returns null when absent or malformed. */
+function readSkillStateFile(filePath) {
+    try {
+        return JSON.parse((0, fs_1.readFileSync)(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}