@orchestrator-claude/definitions 3.32.2 → 3.33.0

package/dist/install/Materializer.js

@@ -0,0 +1,196 @@
+/**
+ * Materializer - stage→verify→swap atomic materialization of manifest
+ * entries into the target filesystem root (RF-001, ADR-001/ADR-003/ADR-004).
+ *
+ * Never mutates `targetRoot` directly: `stage()` writes to an isolated
+ * sibling staging directory (the `~/.claude.install-tmp-<pid>/` pattern);
+ * only `swap()` touches `targetRoot`, via an atomic rename per category
+ * (falling back to copy+remove across filesystem boundaries, ADR-003).
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, renameSync, cpSync, lstatSync, } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+function sha256(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+export class Materializer {
+    loader;
+    targetRoot;
+    constructor(loader, targetRoot) {
+        this.loader = loader;
+        this.targetRoot = targetRoot;
+    }
+    /**
+     * Stages every manifested definition entry into an isolated sibling
+     * directory (never `targetRoot`). Iterates exclusively via
+     * `loader.getAllEntries()` — never `package.json.files` (R-7 regression,
+     * spec finding 2.4.1: the dead `workflows` entry).
+     */
+    async stage() {
+        const stagingDir = this.stagingDirPath();
+        if (existsSync(stagingDir)) {
+            rmSync(stagingDir, { recursive: true, force: true });
+        }
+        mkdirSync(stagingDir, { recursive: true });
+        const entries = this.loader.getAllEntries();
+        for (const entry of entries) {
+            const destPath = join(stagingDir, entry.file);
+            mkdirSync(dirname(destPath), { recursive: true });
+            writeFileSync(destPath, this.loader.readDefinitionContent(entry));
+        }
+        return { stagingDir, entries };
+    }
+    /**
+     * Recomputes the SHA-256 checksum of every staged file against the
+     * manifest. Pure read-only comparison — never mutates `targetRoot`, so
+     * aborting after a failed `verify()` is always safe.
+     */
+    verify(stagingDir) {
+        const entries = this.loader.getAllEntries();
+        const mismatches = [];
+        for (const entry of entries) {
+            const stagedPath = join(stagingDir, entry.file);
+            if (!existsSync(stagedPath)) {
+                mismatches.push(entry);
+                continue;
+            }
+            const content = readFileSync(stagedPath, 'utf-8');
+            if (sha256(content) !== entry.checksum) {
+                mismatches.push(entry);
+            }
+        }
+        return { valid: mismatches.length === 0, mismatches };
+    }
+    /**
+     * Atomically renames each staged category directory into `targetRoot`
+     * (ADR-003). Removes an INTERIM symlink at the target category before
+     * writing (FA-002) — never writes through it. Cleans up the staging
+     * directory in a `finally`, whether swap succeeds or aborts partway
+     * (ADR-003 consequence).
+     */
+    async swap(stagingDir) {
+        try {
+            const entries = this.loader.getAllEntries();
+            const { filesWritten, filesUnchanged } = this.countChanges(stagingDir, entries);
+            const categories = Array.from(new Set(entries.map((entry) => entry.category)));
+            for (const category of categories) {
+                this.swapCategory(stagingDir, category);
+            }
+            return { filesWritten, filesUnchanged };
+        }
+        finally {
+            if (existsSync(stagingDir)) {
+                rmSync(stagingDir, { recursive: true, force: true });
+            }
+        }
+    }
+    /**
+     * Recursively copies skill asset files that are NOT covered by any
+     * manifest entry (spec finding 2.4.2 / risk R-5) — e.g.
+     * `skills/<slug>/scripts/*.js`, never scanned by generate-manifest.ts,
+     * which only tracks a single `.md` level directly under each skill
+     * directory (no recursion into subdirectories).
+     */
+    async copySkillAssets(stagingDir) {
+        const packageRoot = this.loader.getPackageRoot();
+        const skillsDir = resolve(packageRoot, 'skills');
+        if (!existsSync(skillsDir)) {
+            return [];
+        }
+        const manifestedSkillFiles = new Set(this.loader
+            .getAllEntries()
+            .filter((entry) => entry.category === 'skills')
+            .map((entry) => entry.file));
+        const copied = [];
+        const slugs = readdirSync(skillsDir).filter((name) => statSync(join(skillsDir, name)).isDirectory());
+        for (const slug of slugs) {
+            const slugRelativeDir = join('skills', slug);
+            for (const relativeFile of this.walkRecursive(join(skillsDir, slug), slugRelativeDir)) {
+                if (manifestedSkillFiles.has(relativeFile)) {
+                    continue;
+                }
+                const destPath = join(stagingDir, relativeFile);
+                mkdirSync(dirname(destPath), { recursive: true });
+                copyFileSync(resolve(packageRoot, relativeFile), destPath);
+                copied.push(relativeFile);
+            }
+        }
+        return copied;
+    }
+    countChanges(stagingDir, entries) {
+        let filesWritten = 0;
+        let filesUnchanged = 0;
+        for (const entry of entries) {
+            const targetPath = join(this.targetRoot, entry.file);
+            if (existsSync(targetPath)) {
+                const stagedPath = join(stagingDir, entry.file);
+                if (readFileSync(targetPath, 'utf-8') === readFileSync(stagedPath, 'utf-8')) {
+                    filesUnchanged++;
+                    continue;
+                }
+            }
+            filesWritten++;
+        }
+        return { filesWritten, filesUnchanged };
+    }
+    stagingDirPath() {
+        return `${this.targetRoot}.install-tmp-${process.pid}`;
+    }
+    swapCategory(stagingDir, category) {
+        const stagingCategoryPath = join(stagingDir, category);
+        if (!existsSync(stagingCategoryPath)) {
+            return;
+        }
+        const targetCategoryPath = join(this.targetRoot, category);
+        this.removeExistingTarget(targetCategoryPath);
+        mkdirSync(this.targetRoot, { recursive: true });
+        try {
+            renameSync(stagingCategoryPath, targetCategoryPath);
+        }
+        catch (error) {
+            if (error.code === 'EXDEV') {
+                cpSync(stagingCategoryPath, targetCategoryPath, { recursive: true });
+                rmSync(stagingCategoryPath, { recursive: true, force: true });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Removes whatever currently occupies `targetPath` before the atomic
+     * rename. An INTERIM symlink (dev-checkout, FA-002) is unlinked directly —
+     * never followed/recursed into — so its link target is left untouched.
+     */
+    removeExistingTarget(targetPath) {
+        let stat;
+        try {
+            stat = lstatSync(targetPath);
+        }
+        catch {
+            return;
+        }
+        if (stat.isSymbolicLink()) {
+            rmSync(targetPath, { force: true });
+        }
+        else {
+            rmSync(targetPath, { recursive: true, force: true });
+        }
+    }
+    walkRecursive(dir, relativeBase) {
+        const results = [];
+        for (const name of readdirSync(dir)) {
+            const fullPath = join(dir, name);
+            const relativePath = join(relativeBase, name);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                results.push(...this.walkRecursive(fullPath, relativePath));
+            }
+            else if (stat.isFile()) {
+                results.push(relativePath);
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=Materializer.js.map

package/dist/install/Materializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Materializer.js","sourceRoot":"","sources":["../../src/install/Materializer.ts"],"names":[],"mappings":"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"}

package/dist/install/McpRegistrar.d.ts

@@ -0,0 +1,63 @@
+/**
+ * McpRegistrar - registers the bundled MCP servers via the `claude` CLI
+ * (RF-004, ADR-007). Delegates 100% to `ProcessRunner` (DIP, ADR-002) —
+ * never writes to `~/.claude.json`/`~/.claude/.mcp.json` directly (AC-003):
+ * no module in this file imports `node:fs` for that purpose, by construction.
+ *
+ * The exact `claude mcp add`/`claude mcp list` syntax used below was
+ * MEASURED empirically in TASK-014 (Universal Invariant 6), not inferred
+ * from the plan's original assumption — see
+ * `tests/install/fixtures/claude-mcp-cli-output.md` §5 for the 3 concrete
+ * divergences found (mandatory `--` separator for stdio subprocess args,
+ * explicit `--transport http` for HTTP-type servers, `-e KEY=value` per env
+ * var instead of a JSON block).
+ */
+import type { ProcessRunner } from './ProcessRunner.js';
+import type { McpServerSpec } from './types.js';
+export declare class McpRegistrar {
+    private readonly runner;
+    private readonly servers;
+    constructor(runner: ProcessRunner, servers: McpServerSpec[]);
+    /**
+     * Detects whether the `claude` CLI is reachable on PATH (AC-009, R-3),
+     * BEFORE any `claude mcp add` is attempted. Runs a lightweight `claude
+     * --version` via the injected `ProcessRunner`.
+     */
+    checkClaudeAvailable(): Promise<boolean>;
+    /**
+     * Lists the names of every MCP server `claude` currently knows about
+     * (any scope — user, project, plugin), by parsing `claude mcp list`
+     * stdout. Used by `ensureRegistered()` for idempotency (AC-004 parcial).
+     */
+    listRegistered(): Promise<string[]>;
+    /**
+     * Registers every configured server that isn't already known to `claude`
+     * (idempotent — AC-004 parcial), never touching a server already present.
+     * Never writes to `~/.claude.json`/`~/.claude/.mcp.json` directly
+     * (AC-003 parcial) — every mutation goes through `claude mcp add`.
+     */
+    ensureRegistered(): Promise<{
+        registered: string[];
+        skipped: string[];
+    }>;
+    /**
+     * Builds the `claude mcp add` args for one server, per the syntax
+     * measured in TASK-014 (`claude mcp add --scope user --help`):
+     *   - `--transport http` when `type === 'http'` (default is stdio).
+     *   - `-e KEY=value` repeated, once per env var.
+     *   - stdio: `-- <command> [args...]` (the `--` separator is mandatory —
+     *     without it, subprocess args starting with `-` would be parsed as
+     *     `claude mcp add`'s own flags).
+     *   - http: the url as the final positional (no `--` separator, no args).
+     */
+    private buildAddArgs;
+    /**
+     * Parses `claude mcp list` stdout into a flat list of server names.
+     * Format observed (TASK-014): `<name>: <details> - <status-glyph> ...`.
+     * Header/diagnostic lines (`⚠ ...`, `Checking MCP server health…`,
+     * `Location: ...`, `└ [Warning] ...`) never match `<something> - <glyph>`
+     * and are skipped naturally.
+     */
+    private parseRegisteredNames;
+}
+//# sourceMappingURL=McpRegistrar.d.ts.map

package/dist/install/McpRegistrar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpRegistrar.d.ts","sourceRoot":"","sources":["../../src/install/McpRegistrar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,aAAa,EAAE;IAG3C;;;;OAIG;IACG,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC;IAK9C;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQzC;;;;;OAKG;IACG,gBAAgB,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAuB9E;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;IA4BpB;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;CAoB7B"}

package/dist/install/McpRegistrar.js

@@ -0,0 +1,114 @@
+/** Status glyphs `claude mcp list` prefixes each entry's health with. */
+const STATUS_GLYPH_PATTERN = / - (✔|✘|!|⏸)/;
+export class McpRegistrar {
+    runner;
+    servers;
+    constructor(runner, servers) {
+        this.runner = runner;
+        this.servers = servers;
+    }
+    /**
+     * Detects whether the `claude` CLI is reachable on PATH (AC-009, R-3),
+     * BEFORE any `claude mcp add` is attempted. Runs a lightweight `claude
+     * --version` via the injected `ProcessRunner`.
+     */
+    async checkClaudeAvailable() {
+        const result = await this.runner.run('claude', ['--version']);
+        return result.exitCode === 0;
+    }
+    /**
+     * Lists the names of every MCP server `claude` currently knows about
+     * (any scope — user, project, plugin), by parsing `claude mcp list`
+     * stdout. Used by `ensureRegistered()` for idempotency (AC-004 parcial).
+     */
+    async listRegistered() {
+        const result = await this.runner.run('claude', ['mcp', 'list']);
+        if (result.exitCode !== 0) {
+            return [];
+        }
+        return this.parseRegisteredNames(result.stdout);
+    }
+    /**
+     * Registers every configured server that isn't already known to `claude`
+     * (idempotent — AC-004 parcial), never touching a server already present.
+     * Never writes to `~/.claude.json`/`~/.claude/.mcp.json` directly
+     * (AC-003 parcial) — every mutation goes through `claude mcp add`.
+     */
+    async ensureRegistered() {
+        const alreadyRegistered = new Set(await this.listRegistered());
+        const registered = [];
+        const skipped = [];
+        for (const server of this.servers) {
+            if (alreadyRegistered.has(server.name)) {
+                skipped.push(server.name);
+                continue;
+            }
+            const args = this.buildAddArgs(server);
+            const result = await this.runner.run('claude', args);
+            if (result.exitCode === 0) {
+                registered.push(server.name);
+            }
+            else {
+                skipped.push(server.name);
+            }
+        }
+        return { registered, skipped };
+    }
+    /**
+     * Builds the `claude mcp add` args for one server, per the syntax
+     * measured in TASK-014 (`claude mcp add --scope user --help`):
+     *   - `--transport http` when `type === 'http'` (default is stdio).
+     *   - `-e KEY=value` repeated, once per env var.
+     *   - stdio: `-- <command> [args...]` (the `--` separator is mandatory —
+     *     without it, subprocess args starting with `-` would be parsed as
+     *     `claude mcp add`'s own flags).
+     *   - http: the url as the final positional (no `--` separator, no args).
+     */
+    buildAddArgs(server) {
+        const args = ['mcp', 'add', '--scope', 'user'];
+        if (server.type === 'http') {
+            args.push('--transport', 'http');
+        }
+        for (const [key, value] of Object.entries(server.env ?? {})) {
+            args.push('-e', `${key}=${value}`);
+        }
+        args.push(server.name);
+        if (server.type === 'http') {
+            if (!server.url) {
+                throw new Error(`McpRegistrar: server "${server.name}" is type "http" but has no url`);
+            }
+            args.push(server.url);
+        }
+        else {
+            if (!server.command) {
+                throw new Error(`McpRegistrar: server "${server.name}" is stdio but has no command`);
+            }
+            args.push('--', server.command, ...(server.args ?? []));
+        }
+        return args;
+    }
+    /**
+     * Parses `claude mcp list` stdout into a flat list of server names.
+     * Format observed (TASK-014): `<name>: <details> - <status-glyph> ...`.
+     * Header/diagnostic lines (`⚠ ...`, `Checking MCP server health…`,
+     * `Location: ...`, `└ [Warning] ...`) never match `<something> - <glyph>`
+     * and are skipped naturally.
+     */
+    parseRegisteredNames(stdout) {
+        const names = [];
+        for (const rawLine of stdout.split('\n')) {
+            const line = rawLine.trim();
+            const separatorIndex = line.indexOf(': ');
+            if (separatorIndex === -1) {
+                continue;
+            }
+            const rest = line.slice(separatorIndex + 2);
+            if (!STATUS_GLYPH_PATTERN.test(rest)) {
+                continue;
+            }
+            names.push(line.slice(0, separatorIndex));
+        }
+        return names;
+    }
+}
+//# sourceMappingURL=McpRegistrar.js.map

package/dist/install/McpRegistrar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpRegistrar.js","sourceRoot":"","sources":["../../src/install/McpRegistrar.ts"],"names":[],"mappings":"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"}

package/dist/install/ProcessRunner.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ProcessRunner - abstraction for running external processes (DIP, ADR-002).
+ *
+ * `NodeProcessRunner` is the production implementation, backed by
+ * `node:child_process.execFile`. It never throws on a non-zero exit code or
+ * on ENOENT (binary missing from PATH) — callers such as the future
+ * McpRegistrar (Fase 2) need to inspect `exitCode` directly, e.g. to detect
+ * a missing `claude` CLI (AC-009).
+ */
+export interface ProcessRunner {
+    run(command: string, args: string[]): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+}
+export declare class NodeProcessRunner implements ProcessRunner {
+    run(command: string, args: string[]): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    private toResult;
+}
+//# sourceMappingURL=ProcessRunner.d.ts.map

package/dist/install/ProcessRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessRunner.d.ts","sourceRoot":"","sources":["../../src/install/ProcessRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrG;AASD,qBAAa,iBAAkB,YAAW,aAAa;IAC/C,GAAG,CACP,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAShE,OAAO,CAAC,QAAQ;CAiBjB"}

package/dist/install/ProcessRunner.js

@@ -0,0 +1,41 @@
+/**
+ * ProcessRunner - abstraction for running external processes (DIP, ADR-002).
+ *
+ * `NodeProcessRunner` is the production implementation, backed by
+ * `node:child_process.execFile`. It never throws on a non-zero exit code or
+ * on ENOENT (binary missing from PATH) — callers such as the future
+ * McpRegistrar (Fase 2) need to inspect `exitCode` directly, e.g. to detect
+ * a missing `claude` CLI (AC-009).
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** Sentinel exit code used when the target binary cannot be found (ENOENT). */
+const ENOENT_EXIT_CODE = 127;
+export class NodeProcessRunner {
+    async run(command, args) {
+        try {
+            const { stdout, stderr } = await execFileAsync(command, args);
+            return { stdout, stderr, exitCode: 0 };
+        }
+        catch (error) {
+            return this.toResult(error);
+        }
+    }
+    toResult(error) {
+        if (error.code === 'ENOENT') {
+            return {
+                stdout: '',
+                stderr: error.message ?? `Command not found: ${error.code}`,
+                exitCode: ENOENT_EXIT_CODE,
+            };
+        }
+        const exitCode = typeof error.code === 'number' ? error.code : 1;
+        return {
+            stdout: error.stdout ?? '',
+            stderr: error.stderr ?? error.message ?? 'Unknown process error',
+            exitCode,
+        };
+    }
+}
+//# sourceMappingURL=ProcessRunner.js.map

package/dist/install/ProcessRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessRunner.js","sourceRoot":"","sources":["../../src/install/ProcessRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,+EAA+E;AAC/E,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAa7B,MAAM,OAAO,iBAAiB;IAC5B,KAAK,CAAC,GAAG,CACP,OAAe,EACf,IAAc;QAEd,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAsB,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAEO,QAAQ,CAAC,KAAoB;QACnC,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO;gBACL,MAAM,EAAE,EAAE;gBACV,MAAM,EAAE,KAAK,CAAC,OAAO,IAAI,sBAAsB,KAAK,CAAC,IAAI,EAAE;gBAC3D,QAAQ,EAAE,gBAAgB;aAC3B,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAEjE,OAAO;YACL,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;YAC1B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,uBAAuB;YAChE,QAAQ;SACT,CAAC;IACJ,CAAC;CACF"}

package/dist/install/ProjectSettingsNeutralizer.d.ts

@@ -0,0 +1,39 @@
+export declare class ProjectSettingsNeutralizer {
+    private readonly projectSettingsPath;
+    constructor(projectSettingsPath: string);
+    /**
+     * Copies `projectSettingsPath` to `<path>.orch-install-bak` (R-2). Safe to
+     * call more than once — always re-copies the CURRENT on-disk content, so
+     * a caller that already backed up before calling `neutralize()` (which
+     * also backs up internally) never loses the true pre-mutation state.
+     */
+    backup(): string;
+    /**
+     * Removes only the `hooks` key from `projectSettingsPath`, preserving
+     * every other key untouched. Calls `backup()` unconditionally as its
+     * first action (R-2) — no branch in this method mutates the file before
+     * a backup exists.
+     */
+    neutralize(): {
+        neutralized: boolean;
+    };
+    /**
+     * Restores `projectSettingsPath` from a previously-created backup path
+     * (as returned by `backup()`). Called by the ORCHESTRATOR's own `catch` —
+     * see module JSDoc — never invoked internally by this class.
+     */
+    restore(bakPath: string): void;
+    private backupPath;
+    private readSettings;
+    /**
+     * Stage-then-swap for a SINGLE file (ADR-003 discipline, scaled down from
+     * `Materializer`'s per-category directory rename): write to a sibling
+     * temp path, then `renameSync` over the target. A failure at either step
+     * never touches `projectSettingsPath` — the temp file is the only thing
+     * that can be left in an inconsistent state, and it is cleaned up in the
+     * `catch`.
+     */
+    private writeAtomic;
+    private tmpPath;
+}
+//# sourceMappingURL=ProjectSettingsNeutralizer.d.ts.map

package/dist/install/ProjectSettingsNeutralizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectSettingsNeutralizer.d.ts","sourceRoot":"","sources":["../../src/install/ProjectSettingsNeutralizer.ts"],"names":[],"mappings":"AA8BA,qBAAa,0BAA0B;IACzB,OAAO,CAAC,QAAQ,CAAC,mBAAmB;gBAAnB,mBAAmB,EAAE,MAAM;IAExD;;;;;OAKG;IACH,MAAM,IAAI,MAAM;IAMhB;;;;;OAKG;IACH,UAAU,IAAI;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE;IAYtC;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI9B,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,YAAY;IAKpB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAgBnB,OAAO,CAAC,OAAO;CAGhB"}

package/dist/install/ProjectSettingsNeutralizer.js

@@ -0,0 +1,100 @@
+/**
+ * ProjectSettingsNeutralizer - backup + atomic removal of the `hooks` key
+ * from the target project's `.claude/settings.json`, with rollback
+ * (RF-003/RF-006, R-2).
+ *
+ * Two independent safety nets protect against a partial mutation corrupting
+ * the project's settings file:
+ *   1. **Atomic write** (this module, `writeAtomic()`): `neutralize()` never
+ *      writes through `projectSettingsPath` directly — it writes the next
+ *      content to a sibling temp file and `renameSync`s it over the target
+ *      (same stage-then-swap discipline as `Materializer`, ADR-003). A
+ *      rename replaces whatever directory entry currently sits at the
+ *      target path (including a symlink, FA-002) without following it, so a
+ *      mid-write failure (e.g. a mocked `ENOSPC`) always leaves the
+ *      ORIGINAL file untouched — never a half-written one.
+ *   2. **Backup + restore** (R-2, AC-006): `neutralize()` unconditionally
+ *      calls `backup()` as its very first action — there is no code path
+ *      that mutates `projectSettingsPath` without a `.orch-install-bak`
+ *      copy already on disk. `restore(bakPath)` is the counterpart the
+ *      ORCHESTRATOR (`InstallCommand`, TASK-032, Fase 6 — out of this
+ *      module's scope) calls from its own `catch` if a LATER step of the
+ *      overall install sequence fails after `neutralize()` already
+ *      succeeded. This class only implements the primitive — it never
+ *      calls `restore()` on itself.
+ *
+ * `neutralize()` removes ONLY the `hooks` key — every other key (`env`,
+ * `permissions`, `enabledPlugins`, ...) is preserved untouched.
+ */
+import { copyFileSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+export class ProjectSettingsNeutralizer {
+    projectSettingsPath;
+    constructor(projectSettingsPath) {
+        this.projectSettingsPath = projectSettingsPath;
+    }
+    /**
+     * Copies `projectSettingsPath` to `<path>.orch-install-bak` (R-2). Safe to
+     * call more than once — always re-copies the CURRENT on-disk content, so
+     * a caller that already backed up before calling `neutralize()` (which
+     * also backs up internally) never loses the true pre-mutation state.
+     */
+    backup() {
+        const bakPath = this.backupPath();
+        copyFileSync(this.projectSettingsPath, bakPath);
+        return bakPath;
+    }
+    /**
+     * Removes only the `hooks` key from `projectSettingsPath`, preserving
+     * every other key untouched. Calls `backup()` unconditionally as its
+     * first action (R-2) — no branch in this method mutates the file before
+     * a backup exists.
+     */
+    neutralize() {
+        this.backup();
+        const current = this.readSettings();
+        const hadHooks = Object.prototype.hasOwnProperty.call(current, 'hooks');
+        const { hooks: _hooks, ...rest } = current;
+        this.writeAtomic(JSON.stringify(rest, null, 2));
+        return { neutralized: hadHooks };
+    }
+    /**
+     * Restores `projectSettingsPath` from a previously-created backup path
+     * (as returned by `backup()`). Called by the ORCHESTRATOR's own `catch` —
+     * see module JSDoc — never invoked internally by this class.
+     */
+    restore(bakPath) {
+        copyFileSync(bakPath, this.projectSettingsPath);
+    }
+    backupPath() {
+        return `${this.projectSettingsPath}.orch-install-bak`;
+    }
+    readSettings() {
+        const raw = readFileSync(this.projectSettingsPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    /**
+     * Stage-then-swap for a SINGLE file (ADR-003 discipline, scaled down from
+     * `Materializer`'s per-category directory rename): write to a sibling
+     * temp path, then `renameSync` over the target. A failure at either step
+     * never touches `projectSettingsPath` — the temp file is the only thing
+     * that can be left in an inconsistent state, and it is cleaned up in the
+     * `catch`.
+     */
+    writeAtomic(content) {
+        const tmpPath = this.tmpPath();
+        try {
+            writeFileSync(tmpPath, content, 'utf-8');
+            renameSync(tmpPath, this.projectSettingsPath);
+        }
+        catch (error) {
+            if (existsSync(tmpPath)) {
+                rmSync(tmpPath, { force: true });
+            }
+            throw new Error(`ProjectSettingsNeutralizer.neutralize() failed writing "${this.projectSettingsPath}": ${error.message}`, { cause: error });
+        }
+    }
+    tmpPath() {
+        return `${this.projectSettingsPath}.orch-neutralize-tmp-${process.pid}`;
+    }
+}
+//# sourceMappingURL=ProjectSettingsNeutralizer.js.map

package/dist/install/ProjectSettingsNeutralizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectSettingsNeutralizer.js","sourceRoot":"","sources":["../../src/install/ProjectSettingsNeutralizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEpG,MAAM,OAAO,0BAA0B;IACR;IAA7B,YAA6B,mBAA2B;QAA3B,wBAAmB,GAAnB,mBAAmB,CAAQ;IAAG,CAAC;IAE5D;;;;;OAKG;IACH,MAAM;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAClC,YAAY,CAAC,IAAI,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,UAAU;QACR,IAAI,CAAC,MAAM,EAAE,CAAC;QAEd,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;QAE3C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAEhD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,OAAe;QACrB,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAClD,CAAC;IAEO,UAAU;QAChB,OAAO,GAAG,IAAI,CAAC,mBAAmB,mBAAmB,CAAC;IACxD,CAAC;IAEO,YAAY;QAClB,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;IACpD,CAAC;IAED;;;;;;;OAOG;IACK,WAAW,CAAC,OAAe;QACjC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YACzC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxB,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACnC,CAAC;YACD,MAAM,IAAI,KAAK,CACb,2DAA2D,IAAI,CAAC,mBAAmB,MAAO,KAAe,CAAC,OAAO,EAAE,EACnH,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,OAAO;QACb,OAAO,GAAG,IAAI,CAAC,mBAAmB,wBAAwB,OAAO,CAAC,GAAG,EAAE,CAAC;IAC1E,CAAC;CACF"}