@aperant/framework 0.6.2

package/dist/cli/util/fs-lock.mjs

@@ -0,0 +1,112 @@
+/**
+ * fs-lock.mjs — file-lock helpers extracted from apt-tools.mjs (C29).
+ *
+ * Depends on project.mjs (findProjectRootFromPath) and the `proper-lockfile`
+ * dependency. Behavior must match the originals byte-for-byte.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import properLockfileImport from 'proper-lockfile';
+import { findProjectRootFromPath } from './project.mjs';
+// proper-lockfile exposes lock/unlock/check on the default export in CJS.
+const properLockfile = properLockfileImport?.default ?? properLockfileImport;
+/**
+ * Acquire an exclusive file lock via `proper-lockfile`, run `fn`, then
+ * release. Kept synchronous to match the existing call sites (atomic JSON
+ * writers) that expect a value back from the callback.
+ *
+ * proper-lockfile manages its own `.lock` sidecar and handles stale locks
+ * via mtime polling, so C28 retires the ad-hoc `writeFileSync(...wx)`
+ * pattern. On acquisition failure we emit a structured event to
+ * `.aperant/events/lock_timeout_*.json` so operators can spot contention.
+ */
+export function withFileLock(targetPath, fn, options = {}) {
+    const maxRetries = options.maxRetries ?? 20;
+    const retryDelayMs = options.retryDelayMs ?? 50;
+    const maxRetryDelayMs = options.maxRetryDelayMs ?? 500;
+    const stale = options.stale ?? 5000;
+    const realpath = options.realpath ?? false;
+    mkdirSync(dirname(targetPath), { recursive: true });
+    if (!existsSync(targetPath)) {
+        writeFileSync(targetPath, '', { flag: 'a' });
+    }
+    // proper-lockfile's sync API does not accept the full retries object —
+    // only a number. Implement our own retry loop around lockSync.
+    let release = null;
+    let lastErr = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            release = properLockfile.lockSync(targetPath, {
+                stale,
+                realpath,
+            });
+            break;
+        }
+        catch (err) {
+            lastErr = err;
+            // Retry only on "already locked" style errors. Fatal errors (bad path,
+            // permission) should fail fast.
+            const msg = String(err?.message ?? err);
+            if (!/lock|ELOCKED|already held|EEXIST/i.test(msg) || attempt === maxRetries) {
+                break;
+            }
+            const jitter = retryDelayMs + Math.random() * Math.min(maxRetryDelayMs, retryDelayMs * (attempt + 1));
+            // Block this thread without spinning the CPU. Atomics.wait on a
+            // non-shared int just parks the event loop for the duration.
+            try {
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, jitter);
+            }
+            catch {
+                // Fallback for runtimes without SharedArrayBuffer — fall back to
+                // a spin with a short bound so we don't burn CPU indefinitely.
+                const startedAt = Date.now();
+                while (Date.now() - startedAt < Math.min(jitter, 100)) {
+                    /* spin */
+                }
+            }
+        }
+    }
+    if (!release) {
+        recordLockTimeoutEvent(targetPath, options.projectRoot, lastErr);
+        throw new Error(`Could not acquire lock at ${targetPath}.lock: ${lastErr?.message ?? lastErr}`);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            release?.();
+        }
+        catch {
+            /* already released or stale */
+        }
+    }
+}
+export function recordLockTimeoutEvent(targetPath, projectRoot, err) {
+    try {
+        const root = projectRoot ? resolve(projectRoot) : findProjectRootFromPath(targetPath);
+        if (!root)
+            return;
+        const eventsDir = join(root, '.aperant', 'events');
+        mkdirSync(eventsDir, { recursive: true });
+        const ts = new Date().toISOString().replace(/[:.]/g, '-');
+        const file = join(eventsDir, `lock_timeout_${ts}_${process.pid}.json`);
+        writeFileSync(file, JSON.stringify({
+            type: 'lock_timeout',
+            target: targetPath,
+            reason: err?.message ?? String(err),
+            pid: process.pid,
+            at: new Date().toISOString(),
+        }, null, 2));
+    }
+    catch {
+        /* best-effort only */
+    }
+}
+export function openSyncExclusive(path) {
+    return openSync(path, 'wx');
+}
+export function closeSyncFd(fd) {
+    closeSync(fd);
+}
+//# sourceMappingURL=fs-lock.mjs.map

package/dist/cli/util/fs-lock.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-lock.mjs","sourceRoot":"","sources":["../../../src/cli/util/fs-lock.mjs"],"names":[],"mappings":"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"}

package/dist/cli/util/init-hints.d.mts

@@ -0,0 +1,29 @@
+/**
+ * One-time hint after a real `apt-tools init` (when `config.json` was
+ * actually written fresh — NOT on noop re-install). Caller MUST gate on
+ * the genuine "config created" signal.
+ *
+ * Single stderr line. Never throws. No-op when suppressed.
+ *
+ * @internal
+ */
+export function emitInitConfigHint(): void;
+/**
+ * One-time hint after a real `apt-tools pr-review init-pr` (when
+ * `pr-state.json` was just seeded — NOT on subsequent calls where the file
+ * already exists / `rounds_completed > 0`). Caller MUST gate on the
+ * genuine "state created" signal.
+ *
+ * Since 2026-04 the artifact is **ephemeral** (local framework coordination,
+ * not a git artifact). The hint exists so users seeing the file under
+ * `.aperant/pr-reviews/` know it's intentional local state and not stray
+ * scratch — and so they don't try to commit it.
+ *
+ * Single stderr block. Never throws. No-op when suppressed.
+ *
+ * @param {number|string} prNumber  PR number, used for path-templating the
+ *                                   hint so users can copy-paste the path.
+ * @internal
+ */
+export function emitInitPrStateHint(prNumber: number | string): void;
+//# sourceMappingURL=init-hints.d.mts.map

package/dist/cli/util/init-hints.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-hints.d.mts","sourceRoot":"","sources":["../../../src/cli/util/init-hints.mjs"],"names":[],"mappings":"AAwCA;;;;;;;;GAQG;AACH,2CAWC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,8CAJW,MAAM,GAAC,MAAM,QAevB"}

package/dist/cli/util/init-hints.mjs

@@ -0,0 +1,89 @@
+/**
+ * init-hints.mjs — one-time UX hints emitted at the tail of fresh
+ * `apt-tools init` and first `apt-tools pr-review init-pr` invocations,
+ * explaining which `.aperant/` files are intentionally team-shared
+ * (committed) vs gitignored (ephemeral).
+ *
+ * Why: users routinely see `M .aperant/config.json` in `git status` after a
+ * `/apt:setup` run and assume the framework forgot to gitignore it. They
+ * are correct that it shows up — but wrong about the cause: `config.json`
+ * is intentionally committable team-level prefs (per
+ * `packages/framework/docs/artifact-lifecycle.md`'s classification table),
+ * sitting next to ephemeral siblings like `state.json` and `team-status/`
+ * that ARE gitignored. This printer closes that documented confusion with
+ * a single stderr line at the right moment in each workflow.
+ *
+ * Stderr (not stdout) so the existing machine-readable JSON envelope from
+ * `output()` stays parseable. Same channel as the gitignore-drift warning
+ * (see `gitignore-drift.mjs` precedent).
+ *
+ * Suppressible via `APT_SUPPRESS_INIT_HINTS=1` for scripted/CI runs that
+ * already understand the model — mirrors the
+ * `APT_SUPPRESS_GITIGNORE_DRIFT=1` precedent.
+ *
+ * Callers are responsible for the "first-time only" gate (e.g. only call
+ * `emitInitConfigHint` when `.aperant/config.json` was actually just
+ * created — not on a noop re-install).
+ *
+ * @internal — consumed only from init.mjs and pr-review.mjs.
+ */
+/**
+ * Returns true when the suppress env var is set to `'1'`. Centralized so
+ * callers don't repeat the comparison.
+ *
+ * @returns {boolean}
+ */
+function isSuppressed() {
+    return process.env.APT_SUPPRESS_INIT_HINTS === '1';
+}
+/**
+ * One-time hint after a real `apt-tools init` (when `config.json` was
+ * actually written fresh — NOT on noop re-install). Caller MUST gate on
+ * the genuine "config created" signal.
+ *
+ * Single stderr line. Never throws. No-op when suppressed.
+ *
+ * @internal
+ */
+export function emitInitConfigHint() {
+    if (isSuppressed())
+        return;
+    try {
+        process.stderr.write('[apt-tools init] Note: .aperant/config.json is intentionally committed (team-shared framework prefs).\n' +
+            '                       Commit it alongside your work. .aperant/state.json + team-status/ are gitignored\n' +
+            '                       and never travel.\n');
+    }
+    catch {
+        /* never block init on a hint write */
+    }
+}
+/**
+ * One-time hint after a real `apt-tools pr-review init-pr` (when
+ * `pr-state.json` was just seeded — NOT on subsequent calls where the file
+ * already exists / `rounds_completed > 0`). Caller MUST gate on the
+ * genuine "state created" signal.
+ *
+ * Since 2026-04 the artifact is **ephemeral** (local framework coordination,
+ * not a git artifact). The hint exists so users seeing the file under
+ * `.aperant/pr-reviews/` know it's intentional local state and not stray
+ * scratch — and so they don't try to commit it.
+ *
+ * Single stderr block. Never throws. No-op when suppressed.
+ *
+ * @param {number|string} prNumber  PR number, used for path-templating the
+ *                                   hint so users can copy-paste the path.
+ * @internal
+ */
+export function emitInitPrStateHint(prNumber) {
+    if (isSuppressed())
+        return;
+    try {
+        process.stderr.write(`[apt-tools pr-review init-pr] Note: .aperant/pr-reviews/pr-${prNumber}/pr-state.json is local-only\n` +
+            '                                    (per-PR coordination — authorship pin, round counters, lock).\n' +
+            '                                    Gitignored; auto-pruned by close-round on PR merge.\n');
+    }
+    catch {
+        /* never block init-pr on a hint write */
+    }
+}
+//# sourceMappingURL=init-hints.mjs.map

package/dist/cli/util/init-hints.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-hints.mjs","sourceRoot":"","sources":["../../../src/cli/util/init-hints.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;GAKG;AACH,SAAS,YAAY;IACpB,OAAO,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,GAAG,CAAA;AACnD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB;IACjC,IAAI,YAAY,EAAE;QAAE,OAAM;IAC1B,IAAI,CAAC;QACJ,OAAO,CAAC,MAAM,CAAC,KAAK,CACnB,yGAAyG;YACxG,2GAA2G;YAC3G,4CAA4C,CAC7C,CAAA;IACF,CAAC;IAAC,MAAM,CAAC;QACR,sCAAsC;IACvC,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAQ;IAC3C,IAAI,YAAY,EAAE;QAAE,OAAM;IAC1B,IAAI,CAAC;QACJ,OAAO,CAAC,MAAM,CAAC,KAAK,CACnB,8DAA8D,QAAQ,gCAAgC;YACrG,qGAAqG;YACrG,2FAA2F,CAC5F,CAAA;IACF,CAAC;IAAC,MAAM,CAAC;QACR,yCAAyC;IAC1C,CAAC;AACF,CAAC"}

package/dist/cli/util/io.d.mts

@@ -0,0 +1,18 @@
+/**
+ * Read framework package.json and return a "<name> <version>" identity string.
+ * Resolves relative to this module's location so the CLI keeps its own
+ * package.json as source of truth regardless of cwd.
+ */
+export function getVersion(): string;
+/**
+ * Write a JSON-stringified value to stdout, followed by a trailing newline.
+ * Everything apt-tools prints to stdout goes through this.
+ */
+export function output(data: any): void;
+/**
+ * Print a structured error envelope to stdout and exit the process with
+ * status 1. Used for all fatal-from-CLI conditions.
+ */
+export function fail(message: any): void;
+export { appendJsonl, atomicWriteJson, atomicWriteText } from "./atomic-write.mjs";
+//# sourceMappingURL=io.d.mts.map

package/dist/cli/util/io.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.mts","sourceRoot":"","sources":["../../../src/cli/util/io.mjs"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,qCAKC;AAED;;;GAGG;AACH,wCAEC;AAED;;;GAGG;AACH,yCAGC"}

package/dist/cli/util/io.mjs

@@ -0,0 +1,42 @@
+/**
+ * io.mjs — layer-0 I/O + process-exit helpers extracted from apt-tools.mjs (C29).
+ *
+ * These are pure leaf helpers with zero internal dependencies. Behavior must
+ * match the originals byte-for-byte; the CLI snapshot harness enforces this.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Re-export the hardened atomic-write primitives so every existing call site
+// (import { atomicWriteJson } from '../util/io.mjs') keeps working. See
+// atomic-write.mjs for the fsync + tmp-file semantics.
+export { appendJsonl, atomicWriteJson, atomicWriteText } from './atomic-write.mjs';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Read framework package.json and return a "<name> <version>" identity string.
+ * Resolves relative to this module's location so the CLI keeps its own
+ * package.json as source of truth regardless of cwd.
+ */
+export function getVersion() {
+    // src/cli/util/io.mjs → up three levels → packages/framework/package.json
+    const pkgPath = resolve(__dirname, '..', '..', '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return `${pkg.name} ${pkg.version}`;
+}
+/**
+ * Write a JSON-stringified value to stdout, followed by a trailing newline.
+ * Everything apt-tools prints to stdout goes through this.
+ */
+export function output(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+/**
+ * Print a structured error envelope to stdout and exit the process with
+ * status 1. Used for all fatal-from-CLI conditions.
+ */
+export function fail(message) {
+    output({ error: message });
+    process.exit(1);
+}
+//# sourceMappingURL=io.mjs.map

package/dist/cli/util/io.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.mjs","sourceRoot":"","sources":["../../../src/cli/util/io.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,6EAA6E;AAC7E,wEAAwE;AACxE,uDAAuD;AACvD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAElF,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AAErC;;;;GAIG;AACH,MAAM,UAAU,UAAU;IACzB,0EAA0E;IAC1E,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAA;IACpE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;IACtD,OAAO,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,CAAA;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,IAAI;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,OAAO;IAC3B,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;IAC1B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAChB,CAAC"}

package/dist/cli/util/project.d.mts

@@ -0,0 +1,12 @@
+/**
+ * Walk upward from the target path until we find a `.aperant/` directory.
+ * Returns the containing project root, or null if none is found within
+ * 8 parent levels.
+ */
+export function findProjectRootFromPath(filePath: any): string | null;
+/**
+ * Get the shared lock directory — uses git common dir so locks coordinate
+ * across worktrees. Falls back to local .aperant/locks/ if not in git.
+ */
+export function getSharedLockDir(projectDir: any): string;
+//# sourceMappingURL=project.d.mts.map

package/dist/cli/util/project.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.mts","sourceRoot":"","sources":["../../../src/cli/util/project.mjs"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,sEASC;AAED;;;GAGG;AACH,0DAYC"}

package/dist/cli/util/project.mjs

@@ -0,0 +1,46 @@
+/**
+ * project.mjs — project-root + shared-lock-dir helpers (C29).
+ *
+ * As of subtask 03 `detectWorktree` lives in `src/cli/git/worktree-detect.mjs`
+ * so this module imports it directly. Earlier call sites that passed the
+ * detector as an explicit argument no longer need to — callers can invoke
+ * `getSharedLockDir(projectDir)` with a single argument.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { detectWorktree } from '../git/worktree-detect.mjs';
+/**
+ * Walk upward from the target path until we find a `.aperant/` directory.
+ * Returns the containing project root, or null if none is found within
+ * 8 parent levels.
+ */
+export function findProjectRootFromPath(filePath) {
+    let cur = resolve(filePath);
+    for (let i = 0; i < 8; i++) {
+        const parent = dirname(cur);
+        if (parent === cur)
+            return null;
+        if (existsSync(join(parent, '.aperant')))
+            return parent;
+        cur = parent;
+    }
+    return null;
+}
+/**
+ * Get the shared lock directory — uses git common dir so locks coordinate
+ * across worktrees. Falls back to local .aperant/locks/ if not in git.
+ */
+export function getSharedLockDir(projectDir) {
+    const wt = detectWorktree(projectDir);
+    if (wt.is_worktree && wt.main_repo_root) {
+        // Use main repo's .aperant/locks/ so all worktrees share the same locks
+        const sharedDir = join(wt.main_repo_root, '.aperant', 'locks');
+        mkdirSync(sharedDir, { recursive: true });
+        return sharedDir;
+    }
+    // Not a worktree — use local
+    const localDir = join(resolve(projectDir), '.aperant', 'locks');
+    mkdirSync(localDir, { recursive: true });
+    return localDir;
+}
+//# sourceMappingURL=project.mjs.map

package/dist/cli/util/project.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.mjs","sourceRoot":"","sources":["../../../src/cli/util/project.mjs"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAE3D;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAQ;IAC/C,IAAI,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QAC3B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAA;QAC/B,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAAE,OAAO,MAAM,CAAA;QACvD,GAAG,GAAG,MAAM,CAAA;IACb,CAAC;IACD,OAAO,IAAI,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAU;IAC1C,MAAM,EAAE,GAAG,cAAc,CAAC,UAAU,CAAC,CAAA;IACrC,IAAI,EAAE,CAAC,WAAW,IAAI,EAAE,CAAC,cAAc,EAAE,CAAC;QACzC,wEAAwE;QACxE,MAAM,SAAS,GAAG,IAAI,CAAC,EAAE,CAAC,cAAc,EAAE,UAAU,EAAE,OAAO,CAAC,CAAA;QAC9D,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACzC,OAAO,SAAS,CAAA;IACjB,CAAC;IACD,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,CAAA;IAC/D,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACxC,OAAO,QAAQ,CAAA;AAChB,CAAC"}

package/dist/cli/util/result.d.mts

@@ -0,0 +1,113 @@
+/**
+ * @typedef {Object} CommandResult
+ * @property {{ status: string, command?: string, [k: string]: unknown }} envelope
+ * @property {number} exitCode
+ *
+ * @typedef {Object} RawCommandResult
+ * @property {string} rawText
+ * @property {number} exitCode
+ */
+/**
+ * Success path — pass envelope through verbatim, exit 0.
+ *
+ * @param {{ status: string, command?: string, [k: string]: unknown }} envelope
+ * @returns {CommandResult}
+ */
+export function ok(envelope: {
+    status: string;
+    command?: string;
+    [k: string]: unknown;
+}): CommandResult;
+/**
+ * Generic error path — synthesize a standard error envelope at the requested
+ * exit code. `extra` merges in additional envelope fields (e.g. command name).
+ *
+ * @param {string} msg
+ * @param {number} [exitCode=1]
+ * @param {Record<string, unknown>} [extra]
+ * @returns {CommandResult}
+ */
+export function err(msg: string, exitCode?: number, extra?: Record<string, unknown>): CommandResult;
+/**
+ * Pre-built envelope + explicit exit code. Used when the command has its own
+ * domain-shaped envelope (e.g. pr-review's busy/mismatch envelopes) and only
+ * needs to set the exit code.
+ *
+ * @param {{ status: string, command?: string, [k: string]: unknown }} envelope
+ * @param {number} exitCode
+ * @returns {CommandResult}
+ */
+export function exitWith(envelope: {
+    status: string;
+    command?: string;
+    [k: string]: unknown;
+}, exitCode: number): CommandResult;
+/**
+ * Raw-text output path — for cmds that emit non-JSON content (template dump,
+ * effects list, consistency check --format human, precompact-hook). The wrap()
+ * helper routes this through `process.stdout.write(text)` instead of
+ * `output(envelope)`, then sets the exit code.
+ *
+ * @param {string} text
+ * @param {number} [exitCode=0]
+ * @returns {RawCommandResult}
+ */
+export function rawText(text: string, exitCode?: number): RawCommandResult;
+/**
+ * result.mjs — D-01 (d) command-result helpers.
+ *
+ * Every Layer 1 cmdX(opts) function returns one of two `CommandResult` shapes:
+ *
+ *     { envelope: { status, command?, ... }, exitCode: number }   ← JSON cmds
+ *     { rawText: string, exitCode: number }                       ← non-JSON cmds
+ *
+ * The Layer 2 wrapper (`wrap()` in dispatch.mjs) routes both:
+ *   - JSON shape   → output(envelope) + (exitCode !== 0 ? process.exit(exitCode))
+ *   - rawText shape → process.stdout.write(rawText) + (exitCode !== 0 ? process.exit(exitCode))
+ *
+ * The transport metadata (exitCode) lives OUTSIDE the envelope — the envelope
+ * shape is exactly the pre-refactor JSON contract callers parse from stdout.
+ * There is intentionally NO `_exitCode` (or other transport field) on the
+ * envelope; D-01 (d) was adopted specifically to keep the public JSON contract
+ * clean.
+ *
+ * Helpers:
+ *
+ *   ok(envelope)               — JSON path, exit 0, envelope unchanged.
+ *   err(msg, exitCode = 1, x)  — JSON path, exit `exitCode`, synthesizes a
+ *                                 { status: 'error', error: msg, ...x } envelope.
+ *   exitWith(envelope, code)   — JSON path, exit `code`, envelope unchanged.
+ *                                 Used for the documented exit-2 semantics
+ *                                 (pr-review busy/mismatch/exhausted, audit
+ *                                 pending-artifacts --fail-on-dirty,
+ *                                 state-artifacts secrets-found).
+ *   rawText(text, code = 0)    — Non-JSON path, exit `code`, raw text on stdout.
+ *                                 Used by template, effects list, consistency
+ *                                 check --format human, precompact-hook.
+ *
+ * The CommandResult typedef is JSDoc-only (no TypeScript here — Layer 1 lives
+ * in .mjs). Tests assert on `result.envelope`/`result.rawText` and
+ * `result.exitCode` separately.
+ */
+/**
+ * Sentinel base class for helper-level usage failures inside Layer 1 cmds.
+ * Subclass per-cmd (`class FooUsageError extends UsageError { ... }`) so
+ * each cmd's catch boundary can remain narrowly scoped via `instanceof`.
+ * The dispatcher's catch block converts any UsageError into `err(e.message)`.
+ */
+export class UsageError extends Error {
+    constructor(message: any);
+}
+export type CommandResult = {
+    envelope: {
+        status: string;
+        command?: string;
+        [k: string]: unknown;
+    };
+    exitCode: number;
+};
+export type RawCommandResult = {
+    rawText: string;
+    exitCode: number;
+};
+//# sourceMappingURL=result.d.mts.map

package/dist/cli/util/result.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.mts","sourceRoot":"","sources":["../../../src/cli/util/result.mjs"],"names":[],"mappings":"AAkDA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,6BAHW;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GACxD,aAAa,CAIzB;AAED;;;;;;;;GAQG;AACH,yBALW,MAAM,aACN,MAAM,UACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrB,aAAa,CAOzB;AAED;;;;;;;;GAQG;AACH,mCAJW;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,YAC1D,MAAM,GACJ,aAAa,CAIzB;AAED;;;;;;;;;GASG;AACH,8BAJW,MAAM,aACN,MAAM,GACJ,gBAAgB,CAI5B;AA/GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;GAKG;AACH;IACC,0BAGC;CACD;;cAIa;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE;cAC1D,MAAM;;;aAGN,MAAM;cACN,MAAM"}

package/dist/cli/util/result.mjs

@@ -0,0 +1,107 @@
+/**
+ * result.mjs — D-01 (d) command-result helpers.
+ *
+ * Every Layer 1 cmdX(opts) function returns one of two `CommandResult` shapes:
+ *
+ *     { envelope: { status, command?, ... }, exitCode: number }   ← JSON cmds
+ *     { rawText: string, exitCode: number }                       ← non-JSON cmds
+ *
+ * The Layer 2 wrapper (`wrap()` in dispatch.mjs) routes both:
+ *   - JSON shape   → output(envelope) + (exitCode !== 0 ? process.exit(exitCode))
+ *   - rawText shape → process.stdout.write(rawText) + (exitCode !== 0 ? process.exit(exitCode))
+ *
+ * The transport metadata (exitCode) lives OUTSIDE the envelope — the envelope
+ * shape is exactly the pre-refactor JSON contract callers parse from stdout.
+ * There is intentionally NO `_exitCode` (or other transport field) on the
+ * envelope; D-01 (d) was adopted specifically to keep the public JSON contract
+ * clean.
+ *
+ * Helpers:
+ *
+ *   ok(envelope)               — JSON path, exit 0, envelope unchanged.
+ *   err(msg, exitCode = 1, x)  — JSON path, exit `exitCode`, synthesizes a
+ *                                 { status: 'error', error: msg, ...x } envelope.
+ *   exitWith(envelope, code)   — JSON path, exit `code`, envelope unchanged.
+ *                                 Used for the documented exit-2 semantics
+ *                                 (pr-review busy/mismatch/exhausted, audit
+ *                                 pending-artifacts --fail-on-dirty,
+ *                                 state-artifacts secrets-found).
+ *   rawText(text, code = 0)    — Non-JSON path, exit `code`, raw text on stdout.
+ *                                 Used by template, effects list, consistency
+ *                                 check --format human, precompact-hook.
+ *
+ * The CommandResult typedef is JSDoc-only (no TypeScript here — Layer 1 lives
+ * in .mjs). Tests assert on `result.envelope`/`result.rawText` and
+ * `result.exitCode` separately.
+ */
+/**
+ * Sentinel base class for helper-level usage failures inside Layer 1 cmds.
+ * Subclass per-cmd (`class FooUsageError extends UsageError { ... }`) so
+ * each cmd's catch boundary can remain narrowly scoped via `instanceof`.
+ * The dispatcher's catch block converts any UsageError into `err(e.message)`.
+ */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+/**
+ * @typedef {Object} CommandResult
+ * @property {{ status: string, command?: string, [k: string]: unknown }} envelope
+ * @property {number} exitCode
+ *
+ * @typedef {Object} RawCommandResult
+ * @property {string} rawText
+ * @property {number} exitCode
+ */
+/**
+ * Success path — pass envelope through verbatim, exit 0.
+ *
+ * @param {{ status: string, command?: string, [k: string]: unknown }} envelope
+ * @returns {CommandResult}
+ */
+export function ok(envelope) {
+    return { envelope, exitCode: 0 };
+}
+/**
+ * Generic error path — synthesize a standard error envelope at the requested
+ * exit code. `extra` merges in additional envelope fields (e.g. command name).
+ *
+ * @param {string} msg
+ * @param {number} [exitCode=1]
+ * @param {Record<string, unknown>} [extra]
+ * @returns {CommandResult}
+ */
+export function err(msg, exitCode = 1, extra = {}) {
+    return {
+        envelope: { status: 'error', error: msg, ...extra },
+        exitCode,
+    };
+}
+/**
+ * Pre-built envelope + explicit exit code. Used when the command has its own
+ * domain-shaped envelope (e.g. pr-review's busy/mismatch envelopes) and only
+ * needs to set the exit code.
+ *
+ * @param {{ status: string, command?: string, [k: string]: unknown }} envelope
+ * @param {number} exitCode
+ * @returns {CommandResult}
+ */
+export function exitWith(envelope, exitCode) {
+    return { envelope, exitCode };
+}
+/**
+ * Raw-text output path — for cmds that emit non-JSON content (template dump,
+ * effects list, consistency check --format human, precompact-hook). The wrap()
+ * helper routes this through `process.stdout.write(text)` instead of
+ * `output(envelope)`, then sets the exit code.
+ *
+ * @param {string} text
+ * @param {number} [exitCode=0]
+ * @returns {RawCommandResult}
+ */
+export function rawText(text, exitCode = 0) {
+    return { rawText: text, exitCode };
+}
+//# sourceMappingURL=result.mjs.map

package/dist/cli/util/result.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.mjs","sourceRoot":"","sources":["../../../src/cli/util/result.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;GAKG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACpC,YAAY,OAAO;QAClB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,YAAY,CAAA;IACzB,CAAC;CACD;AAED;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,EAAE,CAAC,QAAQ;IAC1B,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAA;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE;IAChD,OAAO;QACN,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE;QACnD,QAAQ;KACR,CAAA;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAC1C,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAA;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,CAAC;IACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;AACnC,CAAC"}

package/dist/cli/util/skill-installs.d.mts

@@ -0,0 +1,14 @@
+export function getSkillInstallSurfaces(projectDir: any): {
+    version_file: string;
+    host: string;
+    skills_dir: string;
+}[];
+export function readSkillInstallState(projectDir: any, frameworkVersion: any): {
+    installed: boolean;
+    installed_version: string | null;
+    stale: boolean;
+    version_file: string;
+    host: string;
+    skills_dir: string;
+}[];
+//# sourceMappingURL=skill-installs.d.mts.map

package/dist/cli/util/skill-installs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-installs.d.mts","sourceRoot":"","sources":["../../../src/cli/util/skill-installs.mjs"],"names":[],"mappings":"AAOA;;;;IAeC;AAED;;;;;;;IAYC"}