apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/formatter-lifecycle.d.ts

@@ -0,0 +1,69 @@
+/**
+ * VF.5 plus PS.2: the formatter lifecycle. A formatter runs against an
+ * isolated copy of the workspace, never the workspace itself, and only the
+ * changes matching its declared paths are promoted back. An undeclared write
+ * is left behind in the discarded stage directory, so the live workspace never
+ * holds bytes the policy did not declare.
+ *
+ * This replaces post-hoc reporting. The earlier lifecycle ran the formatter in
+ * the live workspace and listed undeclared writes afterwards, which is a
+ * report, not a boundary: the stray bytes were already on disk. `status` is
+ * now `scope-violated` whenever a write fell outside the declared set, and
+ * that value can never read as `passed`.
+ *
+ * What this does NOT confine, deliberately and recorded rather than implied:
+ * a formatter writing to an absolute path outside the workspace, or reaching
+ * the network. Those are the OS sandbox's job. Copy plus restricted promotion
+ * confines workspace mutation, nothing wider.
+ *
+ * Promotion refuses any file whose live bytes changed during the run, because
+ * overwriting there would destroy a concurrent edit by the user. Such a run
+ * fails rather than reverting the user's work.
+ *
+ * The snapshot is a bounded walk (harness directories skipped, per-file and
+ * total byte caps). `truncatedSnapshot` is set when coverage was cut short, so
+ * an "unchanged" verdict can be read with the right suspicion.
+ */
+import type { AuthorizeConfiguredCommand } from "./permissions/policy-command.ts";
+import { type PolicyRunStatus } from "./policy-executor.ts";
+import type { FormatterPolicy } from "./policy-loader.ts";
+import type { WorkspaceArtifactRef, WorkspaceArtifactStore } from "./workspace/artifacts.ts";
+export interface FormatterMutationReport {
+    /** Workspace-relative paths (forward slashes) that differ before vs after. */
+    changedPaths: string[];
+    /** Changed paths the policy did not declare inside its pathScope. */
+    undeclaredPaths: string[];
+    /** Changed paths whose real location resolves outside the workspace. */
+    escapedPaths: string[];
+    /** True when nothing in the snapshot differs. */
+    unchanged: boolean;
+    /** True when the walk hit its caps before covering the whole workspace. */
+    truncatedSnapshot: boolean;
+}
+export interface FormatterEvidence {
+    policyId: string;
+    executable: string;
+    argv: string[];
+    cwd: string;
+    status: PolicyRunStatus;
+    durationMs: number;
+    exitCode?: number;
+    signal?: string;
+    truncated: boolean;
+    artifact?: WorkspaceArtifactRef;
+}
+export interface FormatterRunOutcome {
+    status: PolicyRunStatus;
+    mutations: FormatterMutationReport;
+    evidence: FormatterEvidence;
+    refusalReason?: string;
+}
+export interface FormatterRunOptions {
+    workspaceRoot: string;
+    signal?: AbortSignal;
+    artifactStore?: WorkspaceArtifactStore;
+    /** PS.1. A blocked formatter is refused before the snapshot and before the spawn. */
+    authorize?: AuthorizeConfiguredCommand;
+}
+export declare function runFormatterCommand(policy: FormatterPolicy, options: FormatterRunOptions): Promise<FormatterRunOutcome>;
+//# sourceMappingURL=formatter-lifecycle.d.ts.map

package/dist/core/formatter-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter-lifecycle.d.ts","sourceRoot":"","sources":["../../src/core/formatter-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAiBH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,sBAAsB,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAa7F,MAAM,WAAW,uBAAuB;IACvC,8EAA8E;IAC9E,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,qEAAqE;IACrE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,wEAAwE;IACxE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,iBAAiB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,uBAAuB,CAAC;IACnC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,qFAAqF;IACrF,SAAS,CAAC,EAAE,0BAA0B,CAAC;CACvC;AAyPD,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,mBAAmB,GAC1B,OAAO,CAAC,mBAAmB,CAAC,CAkG9B","sourcesContent":["/**\n * VF.5 plus PS.2: the formatter lifecycle. A formatter runs against an\n * isolated copy of the workspace, never the workspace itself, and only the\n * changes matching its declared paths are promoted back. An undeclared write\n * is left behind in the discarded stage directory, so the live workspace never\n * holds bytes the policy did not declare.\n *\n * This replaces post-hoc reporting. The earlier lifecycle ran the formatter in\n * the live workspace and listed undeclared writes afterwards, which is a\n * report, not a boundary: the stray bytes were already on disk. `status` is\n * now `scope-violated` whenever a write fell outside the declared set, and\n * that value can never read as `passed`.\n *\n * What this does NOT confine, deliberately and recorded rather than implied:\n * a formatter writing to an absolute path outside the workspace, or reaching\n * the network. Those are the OS sandbox's job. Copy plus restricted promotion\n * confines workspace mutation, nothing wider.\n *\n * Promotion refuses any file whose live bytes changed during the run, because\n * overwriting there would destroy a concurrent edit by the user. Such a run\n * fails rather than reverting the user's work.\n *\n * The snapshot is a bounded walk (harness directories skipped, per-file and\n * total byte caps). `truncatedSnapshot` is set when coverage was cut short, so\n * an \"unchanged\" verdict can be read with the right suspicion.\n */\n\nimport { createHash } from \"node:crypto\";\nimport {\n\tcopyFileSync,\n\ttype Dirent,\n\tmkdirSync,\n\tmkdtempSync,\n\treaddirSync,\n\treadFileSync,\n\trealpathSync,\n\trmSync,\n\tstatSync,\n} from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, isAbsolute, join, relative, resolve, sep } from \"node:path\";\nimport { minimatch } from \"minimatch\";\nimport type { AuthorizeConfiguredCommand } from \"./permissions/policy-command.ts\";\nimport { type PolicyRunStatus, runPolicyCommand } from \"./policy-executor.ts\";\nimport type { FormatterPolicy } from \"./policy-loader.ts\";\nimport { preparePathOperation, writePreparedPath } from \"./tools/path-utils.ts\";\nimport type { WorkspaceArtifactRef, WorkspaceArtifactStore } from \"./workspace/artifacts.ts\";\n\n/** Per-file hash cap: larger files compare by size plus prefix hash. */\nconst MAX_HASH_BYTES_PER_FILE = 5 * 1024 * 1024;\n/** Prefix length hashed when a file exceeds the per-file cap. */\nconst LARGE_FILE_PREFIX_BYTES = 64 * 1024;\n/** File-count cap for the before/after walk. */\nconst MAX_SNAPSHOT_FILES = 2_000;\n/** Total bytes hashed across one snapshot. */\nconst MAX_SNAPSHOT_BYTES = 32 * 1024 * 1024;\n/** Directory names never part of a formatter's honest workspace view. */\nconst SKIPPED_DIRECTORIES = new Set([\".git\", \"node_modules\", \".apex-code\", \"sessions\"]);\n\nexport interface FormatterMutationReport {\n\t/** Workspace-relative paths (forward slashes) that differ before vs after. */\n\tchangedPaths: string[];\n\t/** Changed paths the policy did not declare inside its pathScope. */\n\tundeclaredPaths: string[];\n\t/** Changed paths whose real location resolves outside the workspace. */\n\tescapedPaths: string[];\n\t/** True when nothing in the snapshot differs. */\n\tunchanged: boolean;\n\t/** True when the walk hit its caps before covering the whole workspace. */\n\ttruncatedSnapshot: boolean;\n}\n\nexport interface FormatterEvidence {\n\tpolicyId: string;\n\texecutable: string;\n\targv: string[];\n\tcwd: string;\n\tstatus: PolicyRunStatus;\n\tdurationMs: number;\n\texitCode?: number;\n\tsignal?: string;\n\ttruncated: boolean;\n\tartifact?: WorkspaceArtifactRef;\n}\n\nexport interface FormatterRunOutcome {\n\tstatus: PolicyRunStatus;\n\tmutations: FormatterMutationReport;\n\tevidence: FormatterEvidence;\n\trefusalReason?: string;\n}\n\nexport interface FormatterRunOptions {\n\tworkspaceRoot: string;\n\tsignal?: AbortSignal;\n\tartifactStore?: WorkspaceArtifactStore;\n\t/** PS.1. A blocked formatter is refused before the snapshot and before the spawn. */\n\tauthorize?: AuthorizeConfiguredCommand;\n}\n\ninterface ScopeSnapshot {\n\t/** Workspace-relative path -> content fingerprint. */\n\thashes: Map<string, string>;\n\ttruncated: boolean;\n}\n\nfunction matchesAny(relPath: string, patterns: string[]): boolean {\n\treturn patterns.some((pattern) => minimatch(relPath, pattern, { dot: true }));\n}\n\nfunction fingerprint(buffer: Buffer): string {\n\treturn createHash(\"sha256\").update(buffer).digest(\"hex\");\n}\n\nfunction hashFile(absolute: string, size: number): string {\n\tif (size <= MAX_HASH_BYTES_PER_FILE) return fingerprint(readFileSync(absolute));\n\t// Oversized file: fingerprint the prefix and let the size field the\n\t// snapshot caller already compared catch whole-file rewrites.\n\treturn fingerprint(readFileSync(absolute).subarray(0, LARGE_FILE_PREFIX_BYTES));\n}\n\nfunction snapshotScope(root: string, priority: string[], background: string[]): ScopeSnapshot {\n\tconst hashes = new Map<string, string>();\n\tlet truncated = false;\n\tlet budgetFiles = MAX_SNAPSHOT_FILES;\n\tlet budgetBytes = MAX_SNAPSHOT_BYTES;\n\n\tconst walk = (dir: string): void => {\n\t\tif (budgetFiles <= 0 || budgetBytes <= 0) {\n\t\t\ttruncated = true;\n\t\t\treturn;\n\t\t}\n\t\tlet entries: Dirent[];\n\t\ttry {\n\t\t\tentries = readdirSync(dir, { withFileTypes: true });\n\t\t} catch {\n\t\t\treturn; // unreadable directory: skip, never throw\n\t\t}\n\t\tfor (const entry of entries) {\n\t\t\tif (budgetFiles <= 0 || budgetBytes <= 0) {\n\t\t\t\ttruncated = true;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (entry.isDirectory()) {\n\t\t\t\tif (!SKIPPED_DIRECTORIES.has(entry.name)) walk(join(dir, entry.name));\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!entry.isFile() && !entry.isSymbolicLink()) continue;\n\t\t\tconst absolute = join(dir, entry.name);\n\t\t\tconst rel = relative(root, absolute).split(sep).join(\"/\");\n\t\t\tif (!matchesAny(rel, priority) && !matchesAny(rel, background)) continue;\n\t\t\tlet size: number;\n\t\t\ttry {\n\t\t\t\tsize = statSync(absolute).size;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tbudgetFiles -= 1;\n\t\t\tif (size > budgetBytes) truncated = true;\n\t\t\ttry {\n\t\t\t\tbudgetBytes -= Math.min(size, MAX_HASH_BYTES_PER_FILE);\n\t\t\t\thashes.set(rel, hashFile(absolute, size));\n\t\t\t} catch {\n\t\t\t\t// presence without a fingerprint would lie; mark it honestly\n\t\t\t\thashes.set(rel, `unreadable:${size}`);\n\t\t\t}\n\t\t}\n\t};\n\n\twalk(resolve(root));\n\treturn { hashes, truncated };\n}\n\nfunction insideWorkspace(root: string, absolute: string): boolean {\n\t// The root itself may sit behind a symlink (macOS /tmp -> /private/tmp):\n\t// compare the changed path's realpath against the root's realpath, or\n\t// every workspace under a linked directory reads as an escape.\n\tlet realRoot = root;\n\ttry {\n\t\trealRoot = realpathSync(root);\n\t} catch {\n\t\t// root vanished between snapshots: compare as-given\n\t}\n\tconst rel = relative(realRoot, absolute);\n\treturn rel === \"\" || (!rel.startsWith(\"..\") && !isAbsolute(rel));\n}\n\nfunction diffScope(before: ScopeSnapshot, after: ScopeSnapshot): string[] {\n\tconst changed: string[] = [];\n\tfor (const [relPath, beforeHash] of before.hashes) {\n\t\tif (after.hashes.get(relPath) !== beforeHash) changed.push(relPath);\n\t}\n\tfor (const relPath of after.hashes.keys()) {\n\t\tif (!before.hashes.has(relPath)) changed.push(relPath);\n\t}\n\treturn changed.sort();\n}\n\n/**\n * Patterns from declaredPaths that remain inside pathScope. A pattern is\n * kept when it equals a scope pattern or a scope pattern is a directory\n * prefix of it; minimatch cannot express containment between globs, so\n * prefix containment is the conservative reading.\n */\nfunction intersectPatterns(declared: string[], scope: string[]): string[] {\n\treturn declared.filter((pattern) =>\n\t\tscope.some(\n\t\t\t(scopePattern) =>\n\t\t\t\tpattern === scopePattern ||\n\t\t\t\tpattern.startsWith(scopePattern.endsWith(\"/\") ? scopePattern : `${scopePattern}/`),\n\t\t),\n\t);\n}\n\nfunction emptyMutations(): FormatterMutationReport {\n\treturn { changedPaths: [], undeclaredPaths: [], escapedPaths: [], unchanged: true, truncatedSnapshot: false };\n}\n\n/** A formatter that never ran. Nothing was spawned, so the mutation report is empty by construction. */\nfunction refused(policy: FormatterPolicy, workspaceRoot: string, reason: string): FormatterRunOutcome {\n\treturn {\n\t\tstatus: \"refused\",\n\t\tmutations: emptyMutations(),\n\t\tevidence: {\n\t\t\tpolicyId: policy.id,\n\t\t\texecutable: policy.executable,\n\t\t\targv: policy.argv,\n\t\t\tcwd: workspaceRoot,\n\t\t\tstatus: \"refused\",\n\t\t\tdurationMs: 0,\n\t\t\ttruncated: false,\n\t\t},\n\t\trefusalReason: reason,\n\t};\n}\n\n/**\n * Copy the workspace into a private stage directory the formatter runs in.\n * Regular files only: a symlink is not reproduced, so a formatter cannot reach\n * a link's target through the stage, and the live link is never followed on\n * promotion either.\n */\nfunction materializeStage(root: string): { stageRoot: string; truncated: boolean } {\n\tconst stageRoot = mkdtempSync(join(tmpdir(), \"apex-formatter-stage-\"));\n\tlet truncated = false;\n\tlet budgetFiles = MAX_SNAPSHOT_FILES;\n\tlet budgetBytes = MAX_SNAPSHOT_BYTES;\n\n\tconst walk = (dir: string): void => {\n\t\tlet entries: Dirent[];\n\t\ttry {\n\t\t\tentries = readdirSync(dir, { withFileTypes: true });\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t\tfor (const entry of entries) {\n\t\t\tif (budgetFiles <= 0 || budgetBytes <= 0) {\n\t\t\t\ttruncated = true;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst absolute = join(dir, entry.name);\n\t\t\tif (entry.isDirectory()) {\n\t\t\t\tif (SKIPPED_DIRECTORIES.has(entry.name)) continue;\n\t\t\t\tmkdirSync(join(stageRoot, relative(root, absolute)), { recursive: true });\n\t\t\t\twalk(absolute);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!entry.isFile()) continue;\n\t\t\tlet size: number;\n\t\t\ttry {\n\t\t\t\tsize = statSync(absolute).size;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tbudgetFiles -= 1;\n\t\t\tbudgetBytes -= size;\n\t\t\ttry {\n\t\t\t\tcopyFileSync(absolute, join(stageRoot, relative(root, absolute)));\n\t\t\t} catch {\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t}\n\t};\n\n\twalk(root);\n\treturn { stageRoot, truncated };\n}\n\ninterface PromotionResult {\n\tpromoted: string[];\n\t/** Declared changes refused because the live file changed during the run. */\n\tconflicted: string[];\n}\n\n/**\n * Write the declared stage changes back into the live workspace through the\n * canonical no-follow write path (CA.2), so a symlink planted at the live\n * target is never followed. A file whose live bytes no longer match the\n * pre-run fingerprint belongs to a concurrent editor and is refused.\n */\nfunction promoteDeclaredChanges(\n\tworkspaceRoot: string,\n\tstageRoot: string,\n\tdeclaredChanges: string[],\n\tpreRun: Map<string, string>,\n): PromotionResult {\n\tconst promoted: string[] = [];\n\tconst conflicted: string[] = [];\n\tfor (const relPath of declaredChanges) {\n\t\tconst livePath = join(workspaceRoot, ...relPath.split(\"/\"));\n\t\tconst stagePath = join(stageRoot, ...relPath.split(\"/\"));\n\t\tlet liveHash: string | undefined;\n\t\ttry {\n\t\t\tliveHash = hashFile(livePath, statSync(livePath).size);\n\t\t} catch {\n\t\t\tliveHash = undefined;\n\t\t}\n\t\tif (liveHash !== preRun.get(relPath)) {\n\t\t\tconflicted.push(relPath);\n\t\t\tcontinue;\n\t\t}\n\t\tlet content: Buffer;\n\t\ttry {\n\t\t\tcontent = readFileSync(stagePath);\n\t\t} catch {\n\t\t\tconflicted.push(relPath);\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tmkdirSync(dirname(livePath), { recursive: true });\n\t\t\tconst prepared = preparePathOperation(livePath, workspaceRoot);\n\t\t\t// A symlink at the live target canonicalizes to whatever it points at.\n\t\t\t// Promotion writes only inside the workspace, so a target that resolves\n\t\t\t// out is refused rather than followed.\n\t\t\tif (!insideWorkspace(workspaceRoot, prepared.path.value)) {\n\t\t\t\tconflicted.push(relPath);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\twritePreparedPath(prepared, content);\n\t\t\tpromoted.push(relPath);\n\t\t} catch {\n\t\t\tconflicted.push(relPath);\n\t\t}\n\t}\n\treturn { promoted, conflicted };\n}\n\nexport async function runFormatterCommand(\n\tpolicy: FormatterPolicy,\n\toptions: FormatterRunOptions,\n): Promise<FormatterRunOutcome> {\n\tconst workspaceRoot = resolve(options.workspaceRoot);\n\n\t// The loader rejects traversal and absolute scope patterns; this is the\n\t// defensive second gate, because the worst outcome here is running a\n\t// mutator whose declared scope points outside the workspace.\n\tconst scopePatterns = [...policy.declaredPaths, ...(policy.pathScope ?? [])];\n\tconst offending = scopePatterns.find((pattern) => pattern.includes(\"..\") || isAbsolute(pattern));\n\tif (offending !== undefined) {\n\t\treturn refused(\n\t\t\tpolicy,\n\t\t\tworkspaceRoot,\n\t\t\t`declared scope ${JSON.stringify(offending)} must stay inside the workspace`,\n\t\t);\n\t}\n\n\tconst tracked =\n\t\tpolicy.pathScope === undefined ? policy.declaredPaths : intersectPatterns(policy.declaredPaths, policy.pathScope);\n\n\tif (options.authorize !== undefined) {\n\t\tconst decision = await options.authorize({\n\t\t\tpolicyId: policy.id,\n\t\t\texecutable: policy.executable,\n\t\t\targv: policy.argv,\n\t\t\tcwd: workspaceRoot,\n\t\t\twriteScope: tracked,\n\t\t\tcapabilities: new Set([\"exec\", \"fs.write\"]),\n\t\t\tpermission: policy.permission,\n\t\t});\n\t\tif (decision.block) return refused(policy, workspaceRoot, decision.reason ?? \"not permitted\");\n\t}\n\n\t// Background coverage is everything: an unexpected mutation lives\n\t// outside every declared pattern, so only a whole-workspace view can\n\t// report it. Caps bound the walk; truncatedSnapshot carries the doubt.\n\tconst preRun = snapshotScope(workspaceRoot, tracked, [\"**\"]);\n\tconst stage = materializeStage(workspaceRoot);\n\tconst before = snapshotScope(stage.stageRoot, tracked, [\"**\"]);\n\tconst run = await runPolicyCommand(policy, {\n\t\tworkspaceRoot: stage.stageRoot,\n\t\tsignal: options.signal,\n\t\tartifactStore: options.artifactStore,\n\t});\n\tconst after = snapshotScope(stage.stageRoot, tracked, [\"**\"]);\n\n\tconst changedPaths = diffScope(before, after);\n\tconst undeclaredPaths: string[] = [];\n\tconst escapedPaths: string[] = [];\n\tfor (const relPath of changedPaths) {\n\t\tif (!matchesAny(relPath, tracked)) undeclaredPaths.push(relPath);\n\t\tconst absolute = join(stage.stageRoot, ...relPath.split(\"/\"));\n\t\ttry {\n\t\t\tconst real = realpathSync(absolute);\n\t\t\tif (!insideWorkspace(stage.stageRoot, real)) escapedPaths.push(relPath);\n\t\t} catch {\n\t\t\t// deleted or unresolvable between snapshots: no live escape to flag\n\t\t}\n\t}\n\n\tconst declaredChanges = changedPaths.filter(\n\t\t(relPath) => matchesAny(relPath, tracked) && !escapedPaths.includes(relPath),\n\t);\n\tconst promotion = promoteDeclaredChanges(workspaceRoot, stage.stageRoot, declaredChanges, preRun.hashes);\n\trmSync(stage.stageRoot, { recursive: true, force: true });\n\n\tconst outOfScope = undeclaredPaths.length > 0 || escapedPaths.length > 0;\n\tconst status: PolicyRunStatus =\n\t\trun.status !== \"passed\"\n\t\t\t? run.status\n\t\t\t: outOfScope\n\t\t\t\t? \"scope-violated\"\n\t\t\t\t: promotion.conflicted.length > 0\n\t\t\t\t\t? \"failed\"\n\t\t\t\t\t: \"passed\";\n\n\treturn {\n\t\tstatus,\n\t\tmutations: {\n\t\t\tchangedPaths,\n\t\t\tundeclaredPaths,\n\t\t\tescapedPaths,\n\t\t\tunchanged: changedPaths.length === 0,\n\t\t\ttruncatedSnapshot: preRun.truncated || before.truncated || after.truncated || stage.truncated,\n\t\t},\n\t\tevidence: {\n\t\t\tpolicyId: run.policyId,\n\t\t\texecutable: run.executable,\n\t\t\targv: run.argv,\n\t\t\tcwd: run.cwd,\n\t\t\tstatus,\n\t\t\tdurationMs: run.durationMs,\n\t\t\texitCode: run.exitCode,\n\t\t\tsignal: run.signal,\n\t\t\ttruncated: run.truncated,\n\t\t\tartifact: run.artifact,\n\t\t},\n\t\trefusalReason: run.refusalReason,\n\t};\n}\n"]}

package/dist/core/formatter-lifecycle.js

@@ -0,0 +1,360 @@
+/**
+ * VF.5 plus PS.2: the formatter lifecycle. A formatter runs against an
+ * isolated copy of the workspace, never the workspace itself, and only the
+ * changes matching its declared paths are promoted back. An undeclared write
+ * is left behind in the discarded stage directory, so the live workspace never
+ * holds bytes the policy did not declare.
+ *
+ * This replaces post-hoc reporting. The earlier lifecycle ran the formatter in
+ * the live workspace and listed undeclared writes afterwards, which is a
+ * report, not a boundary: the stray bytes were already on disk. `status` is
+ * now `scope-violated` whenever a write fell outside the declared set, and
+ * that value can never read as `passed`.
+ *
+ * What this does NOT confine, deliberately and recorded rather than implied:
+ * a formatter writing to an absolute path outside the workspace, or reaching
+ * the network. Those are the OS sandbox's job. Copy plus restricted promotion
+ * confines workspace mutation, nothing wider.
+ *
+ * Promotion refuses any file whose live bytes changed during the run, because
+ * overwriting there would destroy a concurrent edit by the user. Such a run
+ * fails rather than reverting the user's work.
+ *
+ * The snapshot is a bounded walk (harness directories skipped, per-file and
+ * total byte caps). `truncatedSnapshot` is set when coverage was cut short, so
+ * an "unchanged" verdict can be read with the right suspicion.
+ */
+import { createHash } from "node:crypto";
+import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { minimatch } from "minimatch";
+import { runPolicyCommand } from "./policy-executor.js";
+import { preparePathOperation, writePreparedPath } from "./tools/path-utils.js";
+/** Per-file hash cap: larger files compare by size plus prefix hash. */
+const MAX_HASH_BYTES_PER_FILE = 5 * 1024 * 1024;
+/** Prefix length hashed when a file exceeds the per-file cap. */
+const LARGE_FILE_PREFIX_BYTES = 64 * 1024;
+/** File-count cap for the before/after walk. */
+const MAX_SNAPSHOT_FILES = 2_000;
+/** Total bytes hashed across one snapshot. */
+const MAX_SNAPSHOT_BYTES = 32 * 1024 * 1024;
+/** Directory names never part of a formatter's honest workspace view. */
+const SKIPPED_DIRECTORIES = new Set([".git", "node_modules", ".apex-code", "sessions"]);
+function matchesAny(relPath, patterns) {
+    return patterns.some((pattern) => minimatch(relPath, pattern, { dot: true }));
+}
+function fingerprint(buffer) {
+    return createHash("sha256").update(buffer).digest("hex");
+}
+function hashFile(absolute, size) {
+    if (size <= MAX_HASH_BYTES_PER_FILE)
+        return fingerprint(readFileSync(absolute));
+    // Oversized file: fingerprint the prefix and let the size field the
+    // snapshot caller already compared catch whole-file rewrites.
+    return fingerprint(readFileSync(absolute).subarray(0, LARGE_FILE_PREFIX_BYTES));
+}
+function snapshotScope(root, priority, background) {
+    const hashes = new Map();
+    let truncated = false;
+    let budgetFiles = MAX_SNAPSHOT_FILES;
+    let budgetBytes = MAX_SNAPSHOT_BYTES;
+    const walk = (dir) => {
+        if (budgetFiles <= 0 || budgetBytes <= 0) {
+            truncated = true;
+            return;
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable directory: skip, never throw
+        }
+        for (const entry of entries) {
+            if (budgetFiles <= 0 || budgetBytes <= 0) {
+                truncated = true;
+                return;
+            }
+            if (entry.isDirectory()) {
+                if (!SKIPPED_DIRECTORIES.has(entry.name))
+                    walk(join(dir, entry.name));
+                continue;
+            }
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            const absolute = join(dir, entry.name);
+            const rel = relative(root, absolute).split(sep).join("/");
+            if (!matchesAny(rel, priority) && !matchesAny(rel, background))
+                continue;
+            let size;
+            try {
+                size = statSync(absolute).size;
+            }
+            catch {
+                continue;
+            }
+            budgetFiles -= 1;
+            if (size > budgetBytes)
+                truncated = true;
+            try {
+                budgetBytes -= Math.min(size, MAX_HASH_BYTES_PER_FILE);
+                hashes.set(rel, hashFile(absolute, size));
+            }
+            catch {
+                // presence without a fingerprint would lie; mark it honestly
+                hashes.set(rel, `unreadable:${size}`);
+            }
+        }
+    };
+    walk(resolve(root));
+    return { hashes, truncated };
+}
+function insideWorkspace(root, absolute) {
+    // The root itself may sit behind a symlink (macOS /tmp -> /private/tmp):
+    // compare the changed path's realpath against the root's realpath, or
+    // every workspace under a linked directory reads as an escape.
+    let realRoot = root;
+    try {
+        realRoot = realpathSync(root);
+    }
+    catch {
+        // root vanished between snapshots: compare as-given
+    }
+    const rel = relative(realRoot, absolute);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function diffScope(before, after) {
+    const changed = [];
+    for (const [relPath, beforeHash] of before.hashes) {
+        if (after.hashes.get(relPath) !== beforeHash)
+            changed.push(relPath);
+    }
+    for (const relPath of after.hashes.keys()) {
+        if (!before.hashes.has(relPath))
+            changed.push(relPath);
+    }
+    return changed.sort();
+}
+/**
+ * Patterns from declaredPaths that remain inside pathScope. A pattern is
+ * kept when it equals a scope pattern or a scope pattern is a directory
+ * prefix of it; minimatch cannot express containment between globs, so
+ * prefix containment is the conservative reading.
+ */
+function intersectPatterns(declared, scope) {
+    return declared.filter((pattern) => scope.some((scopePattern) => pattern === scopePattern ||
+        pattern.startsWith(scopePattern.endsWith("/") ? scopePattern : `${scopePattern}/`)));
+}
+function emptyMutations() {
+    return { changedPaths: [], undeclaredPaths: [], escapedPaths: [], unchanged: true, truncatedSnapshot: false };
+}
+/** A formatter that never ran. Nothing was spawned, so the mutation report is empty by construction. */
+function refused(policy, workspaceRoot, reason) {
+    return {
+        status: "refused",
+        mutations: emptyMutations(),
+        evidence: {
+            policyId: policy.id,
+            executable: policy.executable,
+            argv: policy.argv,
+            cwd: workspaceRoot,
+            status: "refused",
+            durationMs: 0,
+            truncated: false,
+        },
+        refusalReason: reason,
+    };
+}
+/**
+ * Copy the workspace into a private stage directory the formatter runs in.
+ * Regular files only: a symlink is not reproduced, so a formatter cannot reach
+ * a link's target through the stage, and the live link is never followed on
+ * promotion either.
+ */
+function materializeStage(root) {
+    const stageRoot = mkdtempSync(join(tmpdir(), "apex-formatter-stage-"));
+    let truncated = false;
+    let budgetFiles = MAX_SNAPSHOT_FILES;
+    let budgetBytes = MAX_SNAPSHOT_BYTES;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (budgetFiles <= 0 || budgetBytes <= 0) {
+                truncated = true;
+                return;
+            }
+            const absolute = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIPPED_DIRECTORIES.has(entry.name))
+                    continue;
+                mkdirSync(join(stageRoot, relative(root, absolute)), { recursive: true });
+                walk(absolute);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            let size;
+            try {
+                size = statSync(absolute).size;
+            }
+            catch {
+                continue;
+            }
+            budgetFiles -= 1;
+            budgetBytes -= size;
+            try {
+                copyFileSync(absolute, join(stageRoot, relative(root, absolute)));
+            }
+            catch {
+                truncated = true;
+            }
+        }
+    };
+    walk(root);
+    return { stageRoot, truncated };
+}
+/**
+ * Write the declared stage changes back into the live workspace through the
+ * canonical no-follow write path (CA.2), so a symlink planted at the live
+ * target is never followed. A file whose live bytes no longer match the
+ * pre-run fingerprint belongs to a concurrent editor and is refused.
+ */
+function promoteDeclaredChanges(workspaceRoot, stageRoot, declaredChanges, preRun) {
+    const promoted = [];
+    const conflicted = [];
+    for (const relPath of declaredChanges) {
+        const livePath = join(workspaceRoot, ...relPath.split("/"));
+        const stagePath = join(stageRoot, ...relPath.split("/"));
+        let liveHash;
+        try {
+            liveHash = hashFile(livePath, statSync(livePath).size);
+        }
+        catch {
+            liveHash = undefined;
+        }
+        if (liveHash !== preRun.get(relPath)) {
+            conflicted.push(relPath);
+            continue;
+        }
+        let content;
+        try {
+            content = readFileSync(stagePath);
+        }
+        catch {
+            conflicted.push(relPath);
+            continue;
+        }
+        try {
+            mkdirSync(dirname(livePath), { recursive: true });
+            const prepared = preparePathOperation(livePath, workspaceRoot);
+            // A symlink at the live target canonicalizes to whatever it points at.
+            // Promotion writes only inside the workspace, so a target that resolves
+            // out is refused rather than followed.
+            if (!insideWorkspace(workspaceRoot, prepared.path.value)) {
+                conflicted.push(relPath);
+                continue;
+            }
+            writePreparedPath(prepared, content);
+            promoted.push(relPath);
+        }
+        catch {
+            conflicted.push(relPath);
+        }
+    }
+    return { promoted, conflicted };
+}
+export async function runFormatterCommand(policy, options) {
+    const workspaceRoot = resolve(options.workspaceRoot);
+    // The loader rejects traversal and absolute scope patterns; this is the
+    // defensive second gate, because the worst outcome here is running a
+    // mutator whose declared scope points outside the workspace.
+    const scopePatterns = [...policy.declaredPaths, ...(policy.pathScope ?? [])];
+    const offending = scopePatterns.find((pattern) => pattern.includes("..") || isAbsolute(pattern));
+    if (offending !== undefined) {
+        return refused(policy, workspaceRoot, `declared scope ${JSON.stringify(offending)} must stay inside the workspace`);
+    }
+    const tracked = policy.pathScope === undefined ? policy.declaredPaths : intersectPatterns(policy.declaredPaths, policy.pathScope);
+    if (options.authorize !== undefined) {
+        const decision = await options.authorize({
+            policyId: policy.id,
+            executable: policy.executable,
+            argv: policy.argv,
+            cwd: workspaceRoot,
+            writeScope: tracked,
+            capabilities: new Set(["exec", "fs.write"]),
+            permission: policy.permission,
+        });
+        if (decision.block)
+            return refused(policy, workspaceRoot, decision.reason ?? "not permitted");
+    }
+    // Background coverage is everything: an unexpected mutation lives
+    // outside every declared pattern, so only a whole-workspace view can
+    // report it. Caps bound the walk; truncatedSnapshot carries the doubt.
+    const preRun = snapshotScope(workspaceRoot, tracked, ["**"]);
+    const stage = materializeStage(workspaceRoot);
+    const before = snapshotScope(stage.stageRoot, tracked, ["**"]);
+    const run = await runPolicyCommand(policy, {
+        workspaceRoot: stage.stageRoot,
+        signal: options.signal,
+        artifactStore: options.artifactStore,
+    });
+    const after = snapshotScope(stage.stageRoot, tracked, ["**"]);
+    const changedPaths = diffScope(before, after);
+    const undeclaredPaths = [];
+    const escapedPaths = [];
+    for (const relPath of changedPaths) {
+        if (!matchesAny(relPath, tracked))
+            undeclaredPaths.push(relPath);
+        const absolute = join(stage.stageRoot, ...relPath.split("/"));
+        try {
+            const real = realpathSync(absolute);
+            if (!insideWorkspace(stage.stageRoot, real))
+                escapedPaths.push(relPath);
+        }
+        catch {
+            // deleted or unresolvable between snapshots: no live escape to flag
+        }
+    }
+    const declaredChanges = changedPaths.filter((relPath) => matchesAny(relPath, tracked) && !escapedPaths.includes(relPath));
+    const promotion = promoteDeclaredChanges(workspaceRoot, stage.stageRoot, declaredChanges, preRun.hashes);
+    rmSync(stage.stageRoot, { recursive: true, force: true });
+    const outOfScope = undeclaredPaths.length > 0 || escapedPaths.length > 0;
+    const status = run.status !== "passed"
+        ? run.status
+        : outOfScope
+            ? "scope-violated"
+            : promotion.conflicted.length > 0
+                ? "failed"
+                : "passed";
+    return {
+        status,
+        mutations: {
+            changedPaths,
+            undeclaredPaths,
+            escapedPaths,
+            unchanged: changedPaths.length === 0,
+            truncatedSnapshot: preRun.truncated || before.truncated || after.truncated || stage.truncated,
+        },
+        evidence: {
+            policyId: run.policyId,
+            executable: run.executable,
+            argv: run.argv,
+            cwd: run.cwd,
+            status,
+            durationMs: run.durationMs,
+            exitCode: run.exitCode,
+            signal: run.signal,
+            truncated: run.truncated,
+            artifact: run.artifact,
+        },
+        refusalReason: run.refusalReason,
+    };
+}
+//# sourceMappingURL=formatter-lifecycle.js.map

package/dist/core/formatter-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter-lifecycle.js","sourceRoot":"","sources":["../../src/core/formatter-lifecycle.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * VF.5 plus PS.2: the formatter lifecycle. A formatter runs against an\n * isolated copy of the workspace, never the workspace itself, and only the\n * changes matching its declared paths are promoted back. An undeclared write\n * is left behind in the discarded stage directory, so the live workspace never\n * holds bytes the policy did not declare.\n *\n * This replaces post-hoc reporting. The earlier lifecycle ran the formatter in\n * the live workspace and listed undeclared writes afterwards, which is a\n * report, not a boundary: the stray bytes were already on disk. `status` is\n * now `scope-violated` whenever a write fell outside the declared set, and\n * that value can never read as `passed`.\n *\n * What this does NOT confine, deliberately and recorded rather than implied:\n * a formatter writing to an absolute path outside the workspace, or reaching\n * the network. Those are the OS sandbox's job. Copy plus restricted promotion\n * confines workspace mutation, nothing wider.\n *\n * Promotion refuses any file whose live bytes changed during the run, because\n * overwriting there would destroy a concurrent edit by the user. Such a run\n * fails rather than reverting the user's work.\n *\n * The snapshot is a bounded walk (harness directories skipped, per-file and\n * total byte caps). `truncatedSnapshot` is set when coverage was cut short, so\n * an \"unchanged\" verdict can be read with the right suspicion.\n */\n\nimport { createHash } from \"node:crypto\";\nimport {\n\tcopyFileSync,\n\ttype Dirent,\n\tmkdirSync,\n\tmkdtempSync,\n\treaddirSync,\n\treadFileSync,\n\trealpathSync,\n\trmSync,\n\tstatSync,\n} from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, isAbsolute, join, relative, resolve, sep } from \"node:path\";\nimport { minimatch } from \"minimatch\";\nimport type { AuthorizeConfiguredCommand } from \"./permissions/policy-command.ts\";\nimport { type PolicyRunStatus, runPolicyCommand } from \"./policy-executor.ts\";\nimport type { FormatterPolicy } from \"./policy-loader.ts\";\nimport { preparePathOperation, writePreparedPath } from \"./tools/path-utils.ts\";\nimport type { WorkspaceArtifactRef, WorkspaceArtifactStore } from \"./workspace/artifacts.ts\";\n\n/** Per-file hash cap: larger files compare by size plus prefix hash. */\nconst MAX_HASH_BYTES_PER_FILE = 5 * 1024 * 1024;\n/** Prefix length hashed when a file exceeds the per-file cap. */\nconst LARGE_FILE_PREFIX_BYTES = 64 * 1024;\n/** File-count cap for the before/after walk. */\nconst MAX_SNAPSHOT_FILES = 2_000;\n/** Total bytes hashed across one snapshot. */\nconst MAX_SNAPSHOT_BYTES = 32 * 1024 * 1024;\n/** Directory names never part of a formatter's honest workspace view. */\nconst SKIPPED_DIRECTORIES = new Set([\".git\", \"node_modules\", \".apex-code\", \"sessions\"]);\n\nexport interface FormatterMutationReport {\n\t/** Workspace-relative paths (forward slashes) that differ before vs after. */\n\tchangedPaths: string[];\n\t/** Changed paths the policy did not declare inside its pathScope. */\n\tundeclaredPaths: string[];\n\t/** Changed paths whose real location resolves outside the workspace. */\n\tescapedPaths: string[];\n\t/** True when nothing in the snapshot differs. */\n\tunchanged: boolean;\n\t/** True when the walk hit its caps before covering the whole workspace. */\n\ttruncatedSnapshot: boolean;\n}\n\nexport interface FormatterEvidence {\n\tpolicyId: string;\n\texecutable: string;\n\targv: string[];\n\tcwd: string;\n\tstatus: PolicyRunStatus;\n\tdurationMs: number;\n\texitCode?: number;\n\tsignal?: string;\n\ttruncated: boolean;\n\tartifact?: WorkspaceArtifactRef;\n}\n\nexport interface FormatterRunOutcome {\n\tstatus: PolicyRunStatus;\n\tmutations: FormatterMutationReport;\n\tevidence: FormatterEvidence;\n\trefusalReason?: string;\n}\n\nexport interface FormatterRunOptions {\n\tworkspaceRoot: string;\n\tsignal?: AbortSignal;\n\tartifactStore?: WorkspaceArtifactStore;\n\t/** PS.1. A blocked formatter is refused before the snapshot and before the spawn. */\n\tauthorize?: AuthorizeConfiguredCommand;\n}\n\ninterface ScopeSnapshot {\n\t/** Workspace-relative path -> content fingerprint. */\n\thashes: Map<string, string>;\n\ttruncated: boolean;\n}\n\nfunction matchesAny(relPath: string, patterns: string[]): boolean {\n\treturn patterns.some((pattern) => minimatch(relPath, pattern, { dot: true }));\n}\n\nfunction fingerprint(buffer: Buffer): string {\n\treturn createHash(\"sha256\").update(buffer).digest(\"hex\");\n}\n\nfunction hashFile(absolute: string, size: number): string {\n\tif (size <= MAX_HASH_BYTES_PER_FILE) return fingerprint(readFileSync(absolute));\n\t// Oversized file: fingerprint the prefix and let the size field the\n\t// snapshot caller already compared catch whole-file rewrites.\n\treturn fingerprint(readFileSync(absolute).subarray(0, LARGE_FILE_PREFIX_BYTES));\n}\n\nfunction snapshotScope(root: string, priority: string[], background: string[]): ScopeSnapshot {\n\tconst hashes = new Map<string, string>();\n\tlet truncated = false;\n\tlet budgetFiles = MAX_SNAPSHOT_FILES;\n\tlet budgetBytes = MAX_SNAPSHOT_BYTES;\n\n\tconst walk = (dir: string): void => {\n\t\tif (budgetFiles <= 0 || budgetBytes <= 0) {\n\t\t\ttruncated = true;\n\t\t\treturn;\n\t\t}\n\t\tlet entries: Dirent[];\n\t\ttry {\n\t\t\tentries = readdirSync(dir, { withFileTypes: true });\n\t\t} catch {\n\t\t\treturn; // unreadable directory: skip, never throw\n\t\t}\n\t\tfor (const entry of entries) {\n\t\t\tif (budgetFiles <= 0 || budgetBytes <= 0) {\n\t\t\t\ttruncated = true;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (entry.isDirectory()) {\n\t\t\t\tif (!SKIPPED_DIRECTORIES.has(entry.name)) walk(join(dir, entry.name));\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!entry.isFile() && !entry.isSymbolicLink()) continue;\n\t\t\tconst absolute = join(dir, entry.name);\n\t\t\tconst rel = relative(root, absolute).split(sep).join(\"/\");\n\t\t\tif (!matchesAny(rel, priority) && !matchesAny(rel, background)) continue;\n\t\t\tlet size: number;\n\t\t\ttry {\n\t\t\t\tsize = statSync(absolute).size;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tbudgetFiles -= 1;\n\t\t\tif (size > budgetBytes) truncated = true;\n\t\t\ttry {\n\t\t\t\tbudgetBytes -= Math.min(size, MAX_HASH_BYTES_PER_FILE);\n\t\t\t\thashes.set(rel, hashFile(absolute, size));\n\t\t\t} catch {\n\t\t\t\t// presence without a fingerprint would lie; mark it honestly\n\t\t\t\thashes.set(rel, `unreadable:${size}`);\n\t\t\t}\n\t\t}\n\t};\n\n\twalk(resolve(root));\n\treturn { hashes, truncated };\n}\n\nfunction insideWorkspace(root: string, absolute: string): boolean {\n\t// The root itself may sit behind a symlink (macOS /tmp -> /private/tmp):\n\t// compare the changed path's realpath against the root's realpath, or\n\t// every workspace under a linked directory reads as an escape.\n\tlet realRoot = root;\n\ttry {\n\t\trealRoot = realpathSync(root);\n\t} catch {\n\t\t// root vanished between snapshots: compare as-given\n\t}\n\tconst rel = relative(realRoot, absolute);\n\treturn rel === \"\" || (!rel.startsWith(\"..\") && !isAbsolute(rel));\n}\n\nfunction diffScope(before: ScopeSnapshot, after: ScopeSnapshot): string[] {\n\tconst changed: string[] = [];\n\tfor (const [relPath, beforeHash] of before.hashes) {\n\t\tif (after.hashes.get(relPath) !== beforeHash) changed.push(relPath);\n\t}\n\tfor (const relPath of after.hashes.keys()) {\n\t\tif (!before.hashes.has(relPath)) changed.push(relPath);\n\t}\n\treturn changed.sort();\n}\n\n/**\n * Patterns from declaredPaths that remain inside pathScope. A pattern is\n * kept when it equals a scope pattern or a scope pattern is a directory\n * prefix of it; minimatch cannot express containment between globs, so\n * prefix containment is the conservative reading.\n */\nfunction intersectPatterns(declared: string[], scope: string[]): string[] {\n\treturn declared.filter((pattern) =>\n\t\tscope.some(\n\t\t\t(scopePattern) =>\n\t\t\t\tpattern === scopePattern ||\n\t\t\t\tpattern.startsWith(scopePattern.endsWith(\"/\") ? scopePattern : `${scopePattern}/`),\n\t\t),\n\t);\n}\n\nfunction emptyMutations(): FormatterMutationReport {\n\treturn { changedPaths: [], undeclaredPaths: [], escapedPaths: [], unchanged: true, truncatedSnapshot: false };\n}\n\n/** A formatter that never ran. Nothing was spawned, so the mutation report is empty by construction. */\nfunction refused(policy: FormatterPolicy, workspaceRoot: string, reason: string): FormatterRunOutcome {\n\treturn {\n\t\tstatus: \"refused\",\n\t\tmutations: emptyMutations(),\n\t\tevidence: {\n\t\t\tpolicyId: policy.id,\n\t\t\texecutable: policy.executable,\n\t\t\targv: policy.argv,\n\t\t\tcwd: workspaceRoot,\n\t\t\tstatus: \"refused\",\n\t\t\tdurationMs: 0,\n\t\t\ttruncated: false,\n\t\t},\n\t\trefusalReason: reason,\n\t};\n}\n\n/**\n * Copy the workspace into a private stage directory the formatter runs in.\n * Regular files only: a symlink is not reproduced, so a formatter cannot reach\n * a link's target through the stage, and the live link is never followed on\n * promotion either.\n */\nfunction materializeStage(root: string): { stageRoot: string; truncated: boolean } {\n\tconst stageRoot = mkdtempSync(join(tmpdir(), \"apex-formatter-stage-\"));\n\tlet truncated = false;\n\tlet budgetFiles = MAX_SNAPSHOT_FILES;\n\tlet budgetBytes = MAX_SNAPSHOT_BYTES;\n\n\tconst walk = (dir: string): void => {\n\t\tlet entries: Dirent[];\n\t\ttry {\n\t\t\tentries = readdirSync(dir, { withFileTypes: true });\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t\tfor (const entry of entries) {\n\t\t\tif (budgetFiles <= 0 || budgetBytes <= 0) {\n\t\t\t\ttruncated = true;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst absolute = join(dir, entry.name);\n\t\t\tif (entry.isDirectory()) {\n\t\t\t\tif (SKIPPED_DIRECTORIES.has(entry.name)) continue;\n\t\t\t\tmkdirSync(join(stageRoot, relative(root, absolute)), { recursive: true });\n\t\t\t\twalk(absolute);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!entry.isFile()) continue;\n\t\t\tlet size: number;\n\t\t\ttry {\n\t\t\t\tsize = statSync(absolute).size;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tbudgetFiles -= 1;\n\t\t\tbudgetBytes -= size;\n\t\t\ttry {\n\t\t\t\tcopyFileSync(absolute, join(stageRoot, relative(root, absolute)));\n\t\t\t} catch {\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t}\n\t};\n\n\twalk(root);\n\treturn { stageRoot, truncated };\n}\n\ninterface PromotionResult {\n\tpromoted: string[];\n\t/** Declared changes refused because the live file changed during the run. */\n\tconflicted: string[];\n}\n\n/**\n * Write the declared stage changes back into the live workspace through the\n * canonical no-follow write path (CA.2), so a symlink planted at the live\n * target is never followed. A file whose live bytes no longer match the\n * pre-run fingerprint belongs to a concurrent editor and is refused.\n */\nfunction promoteDeclaredChanges(\n\tworkspaceRoot: string,\n\tstageRoot: string,\n\tdeclaredChanges: string[],\n\tpreRun: Map<string, string>,\n): PromotionResult {\n\tconst promoted: string[] = [];\n\tconst conflicted: string[] = [];\n\tfor (const relPath of declaredChanges) {\n\t\tconst livePath = join(workspaceRoot, ...relPath.split(\"/\"));\n\t\tconst stagePath = join(stageRoot, ...relPath.split(\"/\"));\n\t\tlet liveHash: string | undefined;\n\t\ttry {\n\t\t\tliveHash = hashFile(livePath, statSync(livePath).size);\n\t\t} catch {\n\t\t\tliveHash = undefined;\n\t\t}\n\t\tif (liveHash !== preRun.get(relPath)) {\n\t\t\tconflicted.push(relPath);\n\t\t\tcontinue;\n\t\t}\n\t\tlet content: Buffer;\n\t\ttry {\n\t\t\tcontent = readFileSync(stagePath);\n\t\t} catch {\n\t\t\tconflicted.push(relPath);\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tmkdirSync(dirname(livePath), { recursive: true });\n\t\t\tconst prepared = preparePathOperation(livePath, workspaceRoot);\n\t\t\t// A symlink at the live target canonicalizes to whatever it points at.\n\t\t\t// Promotion writes only inside the workspace, so a target that resolves\n\t\t\t// out is refused rather than followed.\n\t\t\tif (!insideWorkspace(workspaceRoot, prepared.path.value)) {\n\t\t\t\tconflicted.push(relPath);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\twritePreparedPath(prepared, content);\n\t\t\tpromoted.push(relPath);\n\t\t} catch {\n\t\t\tconflicted.push(relPath);\n\t\t}\n\t}\n\treturn { promoted, conflicted };\n}\n\nexport async function runFormatterCommand(\n\tpolicy: FormatterPolicy,\n\toptions: FormatterRunOptions,\n): Promise<FormatterRunOutcome> {\n\tconst workspaceRoot = resolve(options.workspaceRoot);\n\n\t// The loader rejects traversal and absolute scope patterns; this is the\n\t// defensive second gate, because the worst outcome here is running a\n\t// mutator whose declared scope points outside the workspace.\n\tconst scopePatterns = [...policy.declaredPaths, ...(policy.pathScope ?? [])];\n\tconst offending = scopePatterns.find((pattern) => pattern.includes(\"..\") || isAbsolute(pattern));\n\tif (offending !== undefined) {\n\t\treturn refused(\n\t\t\tpolicy,\n\t\t\tworkspaceRoot,\n\t\t\t`declared scope ${JSON.stringify(offending)} must stay inside the workspace`,\n\t\t);\n\t}\n\n\tconst tracked =\n\t\tpolicy.pathScope === undefined ? policy.declaredPaths : intersectPatterns(policy.declaredPaths, policy.pathScope);\n\n\tif (options.authorize !== undefined) {\n\t\tconst decision = await options.authorize({\n\t\t\tpolicyId: policy.id,\n\t\t\texecutable: policy.executable,\n\t\t\targv: policy.argv,\n\t\t\tcwd: workspaceRoot,\n\t\t\twriteScope: tracked,\n\t\t\tcapabilities: new Set([\"exec\", \"fs.write\"]),\n\t\t\tpermission: policy.permission,\n\t\t});\n\t\tif (decision.block) return refused(policy, workspaceRoot, decision.reason ?? \"not permitted\");\n\t}\n\n\t// Background coverage is everything: an unexpected mutation lives\n\t// outside every declared pattern, so only a whole-workspace view can\n\t// report it. Caps bound the walk; truncatedSnapshot carries the doubt.\n\tconst preRun = snapshotScope(workspaceRoot, tracked, [\"**\"]);\n\tconst stage = materializeStage(workspaceRoot);\n\tconst before = snapshotScope(stage.stageRoot, tracked, [\"**\"]);\n\tconst run = await runPolicyCommand(policy, {\n\t\tworkspaceRoot: stage.stageRoot,\n\t\tsignal: options.signal,\n\t\tartifactStore: options.artifactStore,\n\t});\n\tconst after = snapshotScope(stage.stageRoot, tracked, [\"**\"]);\n\n\tconst changedPaths = diffScope(before, after);\n\tconst undeclaredPaths: string[] = [];\n\tconst escapedPaths: string[] = [];\n\tfor (const relPath of changedPaths) {\n\t\tif (!matchesAny(relPath, tracked)) undeclaredPaths.push(relPath);\n\t\tconst absolute = join(stage.stageRoot, ...relPath.split(\"/\"));\n\t\ttry {\n\t\t\tconst real = realpathSync(absolute);\n\t\t\tif (!insideWorkspace(stage.stageRoot, real)) escapedPaths.push(relPath);\n\t\t} catch {\n\t\t\t// deleted or unresolvable between snapshots: no live escape to flag\n\t\t}\n\t}\n\n\tconst declaredChanges = changedPaths.filter(\n\t\t(relPath) => matchesAny(relPath, tracked) && !escapedPaths.includes(relPath),\n\t);\n\tconst promotion = promoteDeclaredChanges(workspaceRoot, stage.stageRoot, declaredChanges, preRun.hashes);\n\trmSync(stage.stageRoot, { recursive: true, force: true });\n\n\tconst outOfScope = undeclaredPaths.length > 0 || escapedPaths.length > 0;\n\tconst status: PolicyRunStatus =\n\t\trun.status !== \"passed\"\n\t\t\t? run.status\n\t\t\t: outOfScope\n\t\t\t\t? \"scope-violated\"\n\t\t\t\t: promotion.conflicted.length > 0\n\t\t\t\t\t? \"failed\"\n\t\t\t\t\t: \"passed\";\n\n\treturn {\n\t\tstatus,\n\t\tmutations: {\n\t\t\tchangedPaths,\n\t\t\tundeclaredPaths,\n\t\t\tescapedPaths,\n\t\t\tunchanged: changedPaths.length === 0,\n\t\t\ttruncatedSnapshot: preRun.truncated || before.truncated || after.truncated || stage.truncated,\n\t\t},\n\t\tevidence: {\n\t\t\tpolicyId: run.policyId,\n\t\t\texecutable: run.executable,\n\t\t\targv: run.argv,\n\t\t\tcwd: run.cwd,\n\t\t\tstatus,\n\t\t\tdurationMs: run.durationMs,\n\t\t\texitCode: run.exitCode,\n\t\t\tsignal: run.signal,\n\t\t\ttruncated: run.truncated,\n\t\t\tartifact: run.artifact,\n\t\t},\n\t\trefusalReason: run.refusalReason,\n\t};\n}\n"]}

package/dist/core/hooks/command-handler.d.ts

@@ -0,0 +1,19 @@
+import { type HookCommandHandlerConfig, type HookHandler, type HookOutcome } from "./types.ts";
+/**
+ * Shared decision parsing for command stdout and HTTP response bodies.
+ * Non-JSON output, a non-object, or an unknown decision value is "no decision"
+ * plus a warning -- never an allow (spec, Risks).
+ */
+export declare function parseHookDecisionOutput(text: string): HookOutcome;
+/**
+ * A command handler runs through the platform shell (`sh -c`, PowerShell on
+ * Windows) with the event payload on stdin and its decision on stdout.
+ *
+ * Exit-code table (behavioral reference:
+ * docs/research/2026-08-31-harness-landscape.md § 2.1): exit 0 + JSON = that
+ * decision; exit 0 + no output = no decision; exit 2 = block with stderr as
+ * the reason; any other nonzero exit (and spawn failure, and timeout) is a
+ * failure outcome, which the runtime turns into a fail-closed block.
+ */
+export declare function commandHookHandler(config: HookCommandHandlerConfig): HookHandler;
+//# sourceMappingURL=command-handler.d.ts.map

package/dist/core/hooks/command-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-handler.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/command-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,wBAAwB,EAE7B,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,MAAM,YAAY,CAAC;AAUpB;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAsBjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,WAAW,CAwDhF","sourcesContent":["import { spawn } from \"node:child_process\";\nimport {\n\tDEFAULT_HOOK_TIMEOUT_MS,\n\ttype HookCommandHandlerConfig,\n\ttype HookEventPayload,\n\ttype HookHandler,\n\ttype HookOutcome,\n} from \"./types.ts\";\n\n// A runaway formatter can emit megabytes; the decision that matters is at the\n// start, so cap what we retain rather than what the child may write.\nconst MAX_HOOK_OUTPUT_CHARS = 1_000_000;\n\nfunction truncate(text: string): string {\n\treturn text.length > 200 ? `${text.slice(0, 200)}...` : text;\n}\n\n/**\n * Shared decision parsing for command stdout and HTTP response bodies.\n * Non-JSON output, a non-object, or an unknown decision value is \"no decision\"\n * plus a warning -- never an allow (spec, Risks).\n */\nexport function parseHookDecisionOutput(text: string): HookOutcome {\n\tconst trimmed = text.trim();\n\tif (trimmed.length === 0) return { ok: true };\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(trimmed);\n\t} catch {\n\t\treturn { ok: true, warning: `hook output was not valid JSON: ${truncate(trimmed)}` };\n\t}\n\tif (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n\t\treturn { ok: true, warning: `hook output was not a JSON object: ${truncate(trimmed)}` };\n\t}\n\tconst decision = (parsed as { decision?: unknown }).decision;\n\tif (decision === undefined) return { ok: true };\n\tif (decision !== \"allow\" && decision !== \"block\" && decision !== \"ask\") {\n\t\treturn { ok: true, warning: `hook output had an unknown decision: ${truncate(String(decision))}` };\n\t}\n\tconst reason = (parsed as { reason?: unknown }).reason;\n\treturn {\n\t\tok: true,\n\t\tdecision: { decision, ...(typeof reason === \"string\" && reason.length > 0 ? { reason } : {}) },\n\t};\n}\n\n/**\n * A command handler runs through the platform shell (`sh -c`, PowerShell on\n * Windows) with the event payload on stdin and its decision on stdout.\n *\n * Exit-code table (behavioral reference:\n * docs/research/2026-08-31-harness-landscape.md § 2.1): exit 0 + JSON = that\n * decision; exit 0 + no output = no decision; exit 2 = block with stderr as\n * the reason; any other nonzero exit (and spawn failure, and timeout) is a\n * failure outcome, which the runtime turns into a fail-closed block.\n */\nexport function commandHookHandler(config: HookCommandHandlerConfig): HookHandler {\n\tconst timeoutMs = config.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;\n\tconst commandRef = truncate(config.command);\n\treturn {\n\t\tasync execute(payload: HookEventPayload): Promise<HookOutcome> {\n\t\t\tconst shell = process.platform === \"win32\" ? \"powershell.exe\" : \"sh\";\n\t\t\tconst args =\n\t\t\t\tprocess.platform === \"win32\" ? [\"-NoProfile\", \"-Command\", config.command] : [\"-c\", config.command];\n\t\t\treturn await new Promise<HookOutcome>((resolve) => {\n\t\t\t\tconst child = spawn(shell, args, { stdio: [\"pipe\", \"pipe\", \"pipe\"] });\n\t\t\t\tlet stdout = \"\";\n\t\t\t\tlet stderr = \"\";\n\t\t\t\tlet settled = false;\n\t\t\t\tconst finish = (outcome: HookOutcome) => {\n\t\t\t\t\tif (settled) return;\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tclearTimeout(timer);\n\t\t\t\t\tresolve(outcome);\n\t\t\t\t};\n\t\t\t\tconst timer = setTimeout(() => {\n\t\t\t\t\tchild.kill();\n\t\t\t\t\tfinish({ ok: false, warning: `hook timed out after ${timeoutMs}ms: ${commandRef}` });\n\t\t\t\t}, timeoutMs);\n\t\t\t\tchild.stdout.on(\"data\", (chunk: Buffer) => {\n\t\t\t\t\tif (stdout.length < MAX_HOOK_OUTPUT_CHARS) stdout += chunk.toString(\"utf8\");\n\t\t\t\t});\n\t\t\t\tchild.stderr.on(\"data\", (chunk: Buffer) => {\n\t\t\t\t\tif (stderr.length < MAX_HOOK_OUTPUT_CHARS) stderr += chunk.toString(\"utf8\");\n\t\t\t\t});\n\t\t\t\t// A hook that closes stdin early must not crash the write; the exit code decides.\n\t\t\t\tchild.stdin.on(\"error\", () => {});\n\t\t\t\tchild.on(\"error\", (error) => finish({ ok: false, warning: `hook failed to spawn: ${error.message}` }));\n\t\t\t\tchild.on(\"close\", (code) => {\n\t\t\t\t\tif (code === 0) {\n\t\t\t\t\t\tfinish(parseHookDecisionOutput(stdout));\n\t\t\t\t\t} else if (code === 2) {\n\t\t\t\t\t\tfinish({\n\t\t\t\t\t\t\tok: true,\n\t\t\t\t\t\t\tdecision: {\n\t\t\t\t\t\t\t\tdecision: \"block\",\n\t\t\t\t\t\t\t\treason: stderr.trim() || stdout.trim() || \"blocked by hook (exit 2)\",\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t});\n\t\t\t\t\t} else if (code === null) {\n\t\t\t\t\t\tfinish({ ok: false, warning: `hook terminated by a signal: ${commandRef}` });\n\t\t\t\t\t} else {\n\t\t\t\t\t\tfinish({\n\t\t\t\t\t\t\tok: false,\n\t\t\t\t\t\t\twarning: `hook exited with exit code ${code}: ${stderr.trim() || stdout.trim() || commandRef}`,\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t\tchild.stdin.end(JSON.stringify(payload));\n\t\t\t});\n\t\t},\n\t};\n}\n"]}