@orchestrator-claude/definitions 3.32.2 → 3.34.0

package/dist/commands/InstallCommand.js

@@ -0,0 +1,253 @@
+/**
+ * InstallCommand - orchestrates the 5 SRP install modules (Materializer,
+ * McpRegistrar, HooksWirer, ProjectSettingsNeutralizer, DevCheckoutDetector)
+ * per spec §6's 7-step atomicity sequence:
+ *   1. Stage    (Materializer.stage() + copySkillAssets())
+ *   2. Verify   (Materializer.verify(stagingDir))
+ *   3. MCP      (McpRegistrar.checkClaudeAvailable() + ensureRegistered())
+ *   4. Swap     (Materializer.swap(stagingDir) + HooksWirer.wire())
+ *   5. Backup   (ProjectSettingsNeutralizer.backup())
+ *   6. Neutralize — the point of no return (ProjectSettingsNeutralizer.neutralize())
+ *   7. Report
+ *
+ * ADR-001: this class is deliberately thin — pure orchestration, no I/O logic
+ * of its own beyond reading the 2 bundled JSON assets (hooks template, MCP
+ * server list) that the constructor's `packageRoot` ships alongside the
+ * manifest. Never imports `ApiClient` (ADR-005) — `install`'s target is the
+ * operator's local filesystem + the `claude` CLI, not the orchestrator API.
+ *
+ * Atomicity (AC-005, TASK-031/032): every step from `stage()` through
+ * `swap()`'s post-swap verification runs inside ONE try/catch. Any throw —
+ * whether from `stage()`, `verify()`, the MCP step, or `swap()` — jumps
+ * straight to the catch, which builds an abort `InstallResult` WITHOUT ever
+ * reaching `ProjectSettingsNeutralizer.backup()`/`neutralize()` (both
+ * declared strictly AFTER the post-swap verification, by construction — no
+ * code path reaches them except after a verified-successful swap). Only
+ * `neutralize()` itself has a nested try/catch that calls
+ * `ProjectSettingsNeutralizer.restore(bakPath)` before propagating (AC-006).
+ */
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ManifestLoader } from '../manifest/ManifestLoader.js';
+import { Materializer } from '../install/Materializer.js';
+import { McpRegistrar } from '../install/McpRegistrar.js';
+import { NodeProcessRunner } from '../install/ProcessRunner.js';
+import { HooksWirer } from '../install/HooksWirer.js';
+import { ProjectSettingsNeutralizer } from '../install/ProjectSettingsNeutralizer.js';
+import { DevCheckoutDetector } from '../install/DevCheckoutDetector.js';
+import { LocalDiffReporter } from '../install/LocalDiffReporter.js';
+const MONOREPO_ROOT_PLACEHOLDER = '{{MONOREPO_ROOT}}';
+function emptySummary() {
+    return {
+        filesWritten: 0,
+        filesUnchanged: 0,
+        mcpServersRegistered: 0,
+        mcpServersSkipped: 0,
+        hooksWired: false,
+        projectNeutralized: false,
+    };
+}
+export class InstallCommand {
+    loader;
+    constructor(packageRoot) {
+        this.loader = new ManifestLoader(packageRoot);
+    }
+    async execute(options) {
+        const homeDir = options.homeDir ?? homedir();
+        const cwd = options.cwd ?? process.cwd();
+        const targetRoot = join(homeDir, '.claude');
+        const targetSettingsPath = join(targetRoot, 'settings.json');
+        const projectSettingsPath = join(cwd, '.claude', 'settings.json');
+        const warnings = [];
+        const errors = [];
+        const summary = emptySummary();
+        const manifest = this.loader.load();
+        const manifestAgentSlugs = manifest.definitions.agents.map((entry) => entry.slug);
+        const detector = new DevCheckoutDetector(manifestAgentSlugs);
+        const detection = detector.detect(cwd);
+        // Gate: dev-checkout without explicit ack aborts BEFORE step 1 (RF-002, AC-010) —
+        // no other module is ever touched on this path.
+        if (detection.mode === 'dev-checkout' && !options.devCheckoutAck) {
+            return this.buildResult(false, detection.mode, options, summary, warnings, [detection.reason]);
+        }
+        const materializer = new Materializer(this.loader, targetRoot);
+        const localDiffReporter = new LocalDiffReporter(this.loader, targetRoot);
+        let stagingDir;
+        try {
+            // Step 1: Stage
+            const staged = await materializer.stage();
+            stagingDir = staged.stagingDir;
+            await materializer.copySkillAssets(stagingDir);
+            // Step 2: Verify (staged content vs. manifest checksums)
+            const verifyResult = materializer.verify(stagingDir);
+            if (!verifyResult.valid) {
+                errors.push(`Checksum verification failed for staged entries: ${verifyResult.mismatches.map((m) => m.file).join(', ')}`);
+                return this.buildResult(false, detection.mode, options, summary, warnings, errors);
+            }
+            // LocalDiffReporter's plan, computed once — reused by both the
+            // --dry-run report below AND the idempotency short-circuit (RF-007).
+            const diff = localDiffReporter.report(stagingDir);
+            // --dry-run short-circuit (RF-008, AC-011): stops BEFORE step 3 (MCP) and
+            // step 4 (swap) — reports the "would-write" plan via LocalDiffReporter,
+            // never invokes `claude mcp add`, never touches targetRoot/project settings.
+            if (options.dryRun) {
+                summary.filesWritten = diff.entries.filter((e) => e.status !== 'unchanged').length;
+                summary.filesUnchanged = diff.entries.filter((e) => e.status === 'unchanged').length;
+                return this.buildResult(true, detection.mode, options, summary, warnings, errors);
+            }
+            const runner = new NodeProcessRunner();
+            const servers = this.resolveMcpServers(options.monorepoRoot, warnings);
+            const registrar = new McpRegistrar(runner, servers);
+            // Idempotency short-circuit (RF-007, AC-004 completo): nothing changed
+            // since the last install (diff has no changes) AND every configured MCP
+            // server is already registered -> skip steps 3-6 entirely, zero writes,
+            // zero `claude mcp add`.
+            const alreadyRegisteredNames = new Set(await registrar.listRegistered());
+            const allServersAlreadyRegistered = servers.every((server) => alreadyRegisteredNames.has(server.name));
+            if (!diff.hasChanges && allServersAlreadyRegistered) {
+                summary.filesWritten = 0;
+                summary.filesUnchanged = diff.entries.length;
+                summary.mcpServersRegistered = 0;
+                summary.mcpServersSkipped = servers.length;
+                return this.buildResult(true, detection.mode, options, summary, warnings, errors);
+            }
+            // Step 3: MCP registration (R-3: availability checked BEFORE any add)
+            const claudeAvailable = await registrar.checkClaudeAvailable();
+            if (!claudeAvailable) {
+                errors.push('claude CLI not found in PATH. Register MCP servers manually: ' +
+                    servers.map((s) => s.name).join(', '));
+                return this.buildResult(false, detection.mode, options, summary, warnings, errors);
+            }
+            const mcpResult = await registrar.ensureRegistered();
+            summary.mcpServersRegistered = mcpResult.registered.length;
+            summary.mcpServersSkipped = mcpResult.skipped.length;
+            // Step 4: Swap + hooks wiring
+            const swapResult = await materializer.swap(stagingDir);
+            stagingDir = undefined; // swap() cleans up staging in its own finally, whether it succeeds or throws
+            summary.filesWritten = swapResult.filesWritten;
+            summary.filesUnchanged = swapResult.filesUnchanged;
+            // Post-swap verification (spec §6.4): read back targetRoot and re-compare
+            // checksums BEFORE the point of no return. `neutralize()` (step 6) must
+            // never be reached unless this passes — by construction, throwing here
+            // jumps straight to the outer catch, skipping hooks-wire/backup/neutralize.
+            const postSwapVerify = materializer.verify(targetRoot);
+            if (!postSwapVerify.valid) {
+                throw new Error(`Post-swap verification failed for: ${postSwapVerify.mismatches.map((m) => m.file).join(', ')}`);
+            }
+            const hooksTemplate = this.loadHooksTemplate();
+            const hooksWirer = new HooksWirer(hooksTemplate, targetSettingsPath);
+            hooksWirer.wire();
+            summary.hooksWired = true;
+            // Steps 5-6: Backup + neutralize (only when the project has settings to neutralize)
+            if (existsSync(projectSettingsPath)) {
+                const neutralizer = new ProjectSettingsNeutralizer(projectSettingsPath);
+                const bakPath = neutralizer.backup();
+                try {
+                    const neutralizeResult = neutralizer.neutralize();
+                    summary.projectNeutralized = neutralizeResult.neutralized;
+                }
+                catch (neutralizeError) {
+                    neutralizer.restore(bakPath);
+                    throw new Error(`Failed to neutralize project settings (restored from backup): ${neutralizeError.message}`);
+                }
+            }
+            // Step 7: Report
+            return this.buildResult(true, detection.mode, options, summary, warnings, errors);
+        }
+        catch (error) {
+            errors.push(error.message);
+            return this.buildResult(false, detection.mode, options, summary, warnings, errors);
+        }
+        finally {
+            if (stagingDir && existsSync(stagingDir)) {
+                rmSync(stagingDir, { recursive: true, force: true });
+            }
+        }
+    }
+    buildResult(success, mode, options, summary, warnings, errors) {
+        return { success, mode, dryRun: !!options.dryRun, summary, warnings, errors };
+    }
+    loadHooksTemplate() {
+        const raw = readFileSync(join(this.loader.getPackageRoot(), 'hooks-settings-template.json'), 'utf-8');
+        return JSON.parse(raw);
+    }
+    /**
+     * Loads the bundled MCP server specs (ADR-007), resolving the
+     * `{{MONOREPO_ROOT}}` placeholder in stdio `args` per mode:
+     *
+     *   - dev-checkout (`monorepoRoot` provided): in-place string
+     *     substitution of the placeholder token within each arg — UNCHANGED
+     *     from the original ADR-007 behavior (RNF-001, byte-for-byte).
+     *   - npm-user (`monorepoRoot` absent, ADR-P001/ADR-P003): resolves the
+     *     REAL installed location of `@orchestrator-claude/mcp-server` via
+     *     `resolveModulePath()` and replaces ONLY the placeholder-bearing arg
+     *     with the FULL resolved path — never a substring splice inside the
+     *     original arg, which would leave a duplicated/invalid path (e.g.
+     *     `.../mcp-server/dist/index.js/packages/mcp-server/dist/index.js`).
+     *     On any resolution failure (AD-004 — e.g. a from-scratch npm install
+     *     without hoisting, Yarn PnP, etc.), falls back to the pre-existing
+     *     skip+warning behavior, unchanged. `resolveModulePath()` is never
+     *     called at all when `monorepoRoot` is provided (AD-001).
+     */
+    resolveMcpServers(monorepoRoot, warnings) {
+        const raw = JSON.parse(readFileSync(join(this.loader.getPackageRoot(), 'mcp-servers.json'), 'utf-8'));
+        if (monorepoRoot) {
+            return raw.servers.map((server) => ({
+                ...server,
+                ...(server.args
+                    ? { args: server.args.map((arg) => arg.replaceAll(MONOREPO_ROOT_PLACEHOLDER, monorepoRoot)) }
+                    : {}),
+            }));
+        }
+        let resolvedMcpServerPath;
+        try {
+            resolvedMcpServerPath = this.resolveModulePath('@orchestrator-claude/mcp-server');
+        }
+        catch {
+            resolvedMcpServerPath = undefined;
+        }
+        if (resolvedMcpServerPath !== undefined) {
+            const resolvedPath = resolvedMcpServerPath;
+            return raw.servers.map((server) => ({
+                ...server,
+                ...(server.args
+                    ? {
+                        args: server.args.map((arg) => arg.includes(MONOREPO_ROOT_PLACEHOLDER) ? resolvedPath : arg),
+                    }
+                    : {}),
+            }));
+        }
+        const resolvable = [];
+        const skipped = [];
+        for (const server of raw.servers) {
+            const needsMonorepoRoot = server.args?.some((arg) => arg.includes(MONOREPO_ROOT_PLACEHOLDER)) ?? false;
+            if (needsMonorepoRoot) {
+                skipped.push(server.name);
+                continue;
+            }
+            resolvable.push(server);
+        }
+        if (skipped.length > 0) {
+            warnings.push(`monorepoRoot not resolved — skipping MCP servers that require it: ${skipped.join(', ')}. Use --monorepo-root to register them.`);
+        }
+        return resolvable;
+    }
+    /**
+     * Resolves a bare module specifier to its real on-disk path (ADR-P001).
+     * This file is ESM (`"type": "module"`) — bare `require.resolve` doesn't
+     * exist here, so `createRequire(import.meta.url)` is used to synthesize a
+     * CJS-style resolver bound to this file's location. Deliberately NOT
+     * `import.meta.resolve` (rejected — historically unstable/experimental
+     * across Node versions). An instance method (not a standalone function)
+     * so it is mockable via `vi.spyOn(InstallCommand.prototype,
+     * 'resolveModulePath')`, the same DI-via-prototype-spy seam already used
+     * for `Materializer`/`NodeProcessRunner`/`ProjectSettingsNeutralizer` in
+     * this class's tests.
+     */
+    resolveModulePath(specifier) {
+        return createRequire(import.meta.url).resolve(specifier);
+    }
+}
+//# sourceMappingURL=InstallCommand.js.map

package/dist/commands/InstallCommand.js.map

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

package/dist/http/ApiClient.d.ts

@@ -39,6 +39,11 @@ export declare class ApiClient {
             version: string;
             origin: string;
         }>;
+        personas: Array<{
+            slug: string;
+            version: string;
+            origin: string;
+        }>;
         kb: Array<{
             slug: string;
             version: string;

package/dist/http/ApiClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiClient.d.ts","sourceRoot":"","sources":["../../src/http/ApiClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,KAAK,CAAgB;gBAEjB,OAAO,EAAE,gBAAgB;IAKrC;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB3D;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IASjG;;OAEG;IACG,sBAAsB,IAAI,OAAO,CAAC;QACtC,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjE,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjE,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAChE,SAAS,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACpE,EAAE,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC9D,CAAC;YAIY,OAAO;CAqBtB"}
+{"version":3,"file":"ApiClient.d.ts","sourceRoot":"","sources":["../../src/http/ApiClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,KAAK,CAAgB;gBAEjB,OAAO,EAAE,gBAAgB;IAKrC;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB3D;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IASjG;;OAEG;IACG,sBAAsB,IAAI,OAAO,CAAC;QACtC,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjE,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjE,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAChE,SAAS,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACpE,QAAQ,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACnE,EAAE,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC9D,CAAC;YAIY,OAAO;CAqBtB"}

package/dist/http/ApiClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiClient.js","sourceRoot":"","sources":["../../src/http/ApiClient.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,SAAS;IACH,OAAO,CAAS;IACzB,KAAK,CAAgB;IAE7B,YAAY,OAAyB;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,KAAa,EAAE,QAAgB;QACzC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,oBAAoB,EAAE;YAChE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;SAC1C,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,iBAAiB,QAAQ,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAsB,CAAC;QAC1D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,OAAoB,EAAE,IAA0C;QACzE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,0BAA0B,EAAE;YAC9D,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,CAAC;SAC3C,CAAC,CAAC;QAEH,OAAO,QAAsB,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,sBAAsB;QAO1B,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,8BAA8B,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAQ,CAAC;IACtF,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,IAAiB;QACnD,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;SACnC,CAAC;QAEF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC;QACpD,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YACrD,GAAG,IAAI;YACP,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,GAAI,IAAI,CAAC,OAA8C,EAAE;SACjF,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,CAAC,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,CAAC,CAAC;QAC9E,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"ApiClient.js","sourceRoot":"","sources":["../../src/http/ApiClient.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,SAAS;IACH,OAAO,CAAS;IACzB,KAAK,CAAgB;IAE7B,YAAY,OAAyB;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,KAAa,EAAE,QAAgB;QACzC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,oBAAoB,EAAE;YAChE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;SAC1C,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,iBAAiB,QAAQ,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAsB,CAAC;QAC1D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,OAAoB,EAAE,IAA0C;QACzE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,0BAA0B,EAAE;YAC9D,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,CAAC;SAC3C,CAAC,CAAC;QAEH,OAAO,QAAsB,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,sBAAsB;QAQ1B,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,8BAA8B,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAQ,CAAC;IACtF,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,IAAiB;QACnD,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;SACnC,CAAC;QAEF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC;QACpD,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YACrD,GAAG,IAAI;YACP,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,GAAI,IAAI,CAAC,OAA8C,EAAE;SACjF,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,CAAC,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,CAAC,CAAC;QAC9E,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/install/DevCheckoutDetector.d.ts

@@ -0,0 +1,66 @@
+/**
+ * DevCheckoutDetector — read-only dual-condition heuristic (RF-002 / spec
+ * §5.1, ADR-004) for the "inverted precedence" risk between `.claude/agents`
+ * (project-scope) and `.claude/skills` (user-scope, per Claude Code's
+ * documentation): once the installer lands, `~/.claude/agents` resolves from
+ * the distributed package while `<repo>/.claude/agents` remains the authored
+ * source — they can diverge silently.
+ *
+ * Detection requires BOTH conditions (reduces false-positives, risk R-6):
+ *   (i)  walk-up from `cwd` to the nearest ancestor `package.json` whose
+ *        `name` matches the orchestrator monorepo root package
+ *        (`@orchestrator-cli/core` — confirmed via direct Read of
+ *        `/home/cmac/workOrch-Claude/orchestrator/package.json`, plan
+ *        §11 Verify-Before-Assert);
+ *   (ii) that same ancestor's `.claude/agents/*.md` contains REAL files
+ *        (never symlinks — `lstatSync(...).isSymbolicLink()`, distinguishing
+ *        authored files from the C6/TD-204 INTERIM per-file symlinks) whose
+ *        slug (basename without `.md`) collides with `manifestSlugs`.
+ *
+ * Never mutates anything — `detect()` only reads `package.json` and lists
+ * `.claude/agents/`. This module is purely read-only by design.
+ *
+ * ---
+ * MEASURED WARNING TEXT (TASK-036/AC-007 gate — CLOSED, S385):
+ * `DEV_CHECKOUT_WARNING_REASON` previously named the precedence risk
+ * WITHOUT asserting a verified direction ("provisional" — Universal
+ * Invariant 6 forbids hard-coding an unverified claim about third-party CLI
+ * behavior). `scripts/probes/ac007-precedence-probe.ts` (TASK-035) has since
+ * run the AC-007 gate for real (TASK-036): isolated `CLAUDE_CONFIG_DIR` probe
+ * (S382 method), 3/3 deterministic runs per axis, real-`~/.claude`
+ * hard-isolation-gate verified unchanged. **Verdict: CONFIRMS the documented
+ * claim** — agents resolve by PROJECT-scope, skills resolve by USER-scope.
+ * The precedence direction is NOT inverted. The text below now states this
+ * as measured fact and names the real practical risk it implies: the two
+ * scopes can still silently DRIFT APART over time (a project-scope skill
+ * edit has no effect on a live session until `orch-defs install` refreshes
+ * `~/.claude/skills`, unless the file happens to be an INTERIM symlink —
+ * C6/TD-204), independent of the (now-settled) precedence-direction
+ * question. Raw probe output: `tests/install/fixtures/
+ * ac007-precedence-probe-output.md`.
+ */
+import type { DetectionResult } from './types.js';
+export declare class DevCheckoutDetector {
+    private readonly manifestSlugs;
+    constructor(manifestSlugs: string[]);
+    /**
+     * Read-only detection. Never throws on a missing `.claude/agents`
+     * directory or a missing/unparseable ancestor `package.json` — those
+     * cases simply resolve to `'clean-install'`.
+     */
+    detect(cwd: string): DetectionResult;
+    /**
+     * Walks up from `cwd` looking for the nearest ancestor directory whose
+     * `package.json` has `name === MONOREPO_PACKAGE_NAME` (§5.1: "presença de
+     * package.json na raiz do cwd, ou ancestral via walk-up").
+     */
+    private findAncestorWithMatchingPackageName;
+    private hasMatchingName;
+    /**
+     * Real (non-symlink) `.claude/agents/*.md` files at `root` whose slug
+     * (basename without `.md`) collides with `manifestSlugs`.
+     */
+    private findMatchingRealAgentSlugs;
+    private cleanInstall;
+}
+//# sourceMappingURL=DevCheckoutDetector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DevCheckoutDetector.d.ts","sourceRoot":"","sources":["../../src/install/DevCheckoutDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA4BlD,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,MAAM,EAAE;IAEpD;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe;IAkBpC;;;;OAIG;IACH,OAAO,CAAC,mCAAmC;IAiB3C,OAAO,CAAC,eAAe;IASvB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IA4BlC,OAAO,CAAC,YAAY;CAOrB"}

package/dist/install/DevCheckoutDetector.js

@@ -0,0 +1,150 @@
+/**
+ * DevCheckoutDetector — read-only dual-condition heuristic (RF-002 / spec
+ * §5.1, ADR-004) for the "inverted precedence" risk between `.claude/agents`
+ * (project-scope) and `.claude/skills` (user-scope, per Claude Code's
+ * documentation): once the installer lands, `~/.claude/agents` resolves from
+ * the distributed package while `<repo>/.claude/agents` remains the authored
+ * source — they can diverge silently.
+ *
+ * Detection requires BOTH conditions (reduces false-positives, risk R-6):
+ *   (i)  walk-up from `cwd` to the nearest ancestor `package.json` whose
+ *        `name` matches the orchestrator monorepo root package
+ *        (`@orchestrator-cli/core` — confirmed via direct Read of
+ *        `/home/cmac/workOrch-Claude/orchestrator/package.json`, plan
+ *        §11 Verify-Before-Assert);
+ *   (ii) that same ancestor's `.claude/agents/*.md` contains REAL files
+ *        (never symlinks — `lstatSync(...).isSymbolicLink()`, distinguishing
+ *        authored files from the C6/TD-204 INTERIM per-file symlinks) whose
+ *        slug (basename without `.md`) collides with `manifestSlugs`.
+ *
+ * Never mutates anything — `detect()` only reads `package.json` and lists
+ * `.claude/agents/`. This module is purely read-only by design.
+ *
+ * ---
+ * MEASURED WARNING TEXT (TASK-036/AC-007 gate — CLOSED, S385):
+ * `DEV_CHECKOUT_WARNING_REASON` previously named the precedence risk
+ * WITHOUT asserting a verified direction ("provisional" — Universal
+ * Invariant 6 forbids hard-coding an unverified claim about third-party CLI
+ * behavior). `scripts/probes/ac007-precedence-probe.ts` (TASK-035) has since
+ * run the AC-007 gate for real (TASK-036): isolated `CLAUDE_CONFIG_DIR` probe
+ * (S382 method), 3/3 deterministic runs per axis, real-`~/.claude`
+ * hard-isolation-gate verified unchanged. **Verdict: CONFIRMS the documented
+ * claim** — agents resolve by PROJECT-scope, skills resolve by USER-scope.
+ * The precedence direction is NOT inverted. The text below now states this
+ * as measured fact and names the real practical risk it implies: the two
+ * scopes can still silently DRIFT APART over time (a project-scope skill
+ * edit has no effect on a live session until `orch-defs install` refreshes
+ * `~/.claude/skills`, unless the file happens to be an INTERIM symlink —
+ * C6/TD-204), independent of the (now-settled) precedence-direction
+ * question. Raw probe output: `tests/install/fixtures/
+ * ac007-precedence-probe-output.md`.
+ */
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** Root package name of the orchestrator monorepo (Verify-Before-Assert, plan §11). */
+const MONOREPO_PACKAGE_NAME = '@orchestrator-cli/core';
+/**
+ * DEFINITIVE (measured — see module JSDoc / TASK-036 gate, S385). Names the
+ * precedence direction as a settled, empirically-confirmed fact and the
+ * real practical risk it implies (silent drift), not a hypothetical.
+ */
+const DEV_CHECKOUT_WARNING_REASON = 'Dev-checkout detectado: este cwd pertence ao monorepo orchestrator e ' +
+    '`.claude/agents/` contém arquivos reais cujos slugs colidem com o ' +
+    'manifest do pacote. Precedência MEDIDA empiricamente (AC-007/TASK-036, ' +
+    'gate S385, 3/3 runs determinísticos por eixo, probe isolado): agents ' +
+    'resolvem por PROJECT-scope (edições locais neste repo têm efeito ' +
+    'imediato numa sessão live) e skills resolvem por USER-scope ' +
+    '(`~/.claude/skills`) — editar um skill aqui NÃO afeta uma sessão live ' +
+    'até rodar `orch-defs install` novamente, a menos que o arquivo esteja ' +
+    'symlinkado (INTERIM/C6-TD-204). Isso CONFIRMA a direção documentada ' +
+    'pelo Claude Code (não é uma precedência invertida) — o risco real é a ' +
+    'divergência SILENCIOSA entre as duas cópias ao longo do tempo, não a ' +
+    'direção da precedência em si.';
+export class DevCheckoutDetector {
+    manifestSlugs;
+    constructor(manifestSlugs) {
+        this.manifestSlugs = manifestSlugs;
+    }
+    /**
+     * Read-only detection. Never throws on a missing `.claude/agents`
+     * directory or a missing/unparseable ancestor `package.json` — those
+     * cases simply resolve to `'clean-install'`.
+     */
+    detect(cwd) {
+        const monorepoRoot = this.findAncestorWithMatchingPackageName(cwd);
+        if (!monorepoRoot) {
+            return this.cleanInstall();
+        }
+        const matchedSlugs = this.findMatchingRealAgentSlugs(monorepoRoot);
+        if (matchedSlugs.length === 0) {
+            return this.cleanInstall();
+        }
+        return {
+            mode: 'dev-checkout',
+            matchedSlugs,
+            reason: DEV_CHECKOUT_WARNING_REASON,
+        };
+    }
+    /**
+     * Walks up from `cwd` looking for the nearest ancestor directory whose
+     * `package.json` has `name === MONOREPO_PACKAGE_NAME` (§5.1: "presença de
+     * package.json na raiz do cwd, ou ancestral via walk-up").
+     */
+    findAncestorWithMatchingPackageName(cwd) {
+        let current = resolve(cwd);
+        while (true) {
+            const packageJsonPath = join(current, 'package.json');
+            if (existsSync(packageJsonPath) && this.hasMatchingName(packageJsonPath)) {
+                return current;
+            }
+            const parent = dirname(current);
+            if (parent === current) {
+                return null;
+            }
+            current = parent;
+        }
+    }
+    hasMatchingName(packageJsonPath) {
+        try {
+            const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            return parsed.name === MONOREPO_PACKAGE_NAME;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Real (non-symlink) `.claude/agents/*.md` files at `root` whose slug
+     * (basename without `.md`) collides with `manifestSlugs`.
+     */
+    findMatchingRealAgentSlugs(root) {
+        const agentsDir = join(root, '.claude', 'agents');
+        if (!existsSync(agentsDir)) {
+            return [];
+        }
+        const manifestSlugSet = new Set(this.manifestSlugs);
+        const matched = [];
+        for (const name of readdirSync(agentsDir)) {
+            if (!name.endsWith('.md')) {
+                continue;
+            }
+            const filePath = join(agentsDir, name);
+            if (lstatSync(filePath).isSymbolicLink()) {
+                continue;
+            }
+            const slug = name.slice(0, -'.md'.length);
+            if (manifestSlugSet.has(slug)) {
+                matched.push(slug);
+            }
+        }
+        return matched;
+    }
+    cleanInstall() {
+        return {
+            mode: 'clean-install',
+            matchedSlugs: [],
+            reason: 'Nenhuma condição de dev-checkout detectada (package.json não corresponde ao monorepo, ou nenhum agent real com slug colidente).',
+        };
+    }
+}
+//# sourceMappingURL=DevCheckoutDetector.js.map

package/dist/install/DevCheckoutDetector.js.map

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

package/dist/install/HooksWirer.d.ts

@@ -0,0 +1,29 @@
+import type { HooksTemplate } from './types.js';
+type HooksBlock = HooksTemplate['hooks'];
+export declare class HooksWirer {
+    private readonly template;
+    private readonly targetSettingsPath;
+    constructor(template: HooksTemplate, targetSettingsPath: string);
+    wire(): {
+        merged: boolean;
+        hooksBlock: HooksBlock;
+    };
+    private readExistingSettings;
+    /**
+     * Turns every relative `command` path in the template (e.g.
+     * `hooks/session-start.mjs`) into a runnable shell command anchored at
+     * `targetRoot` (`dirname(targetSettingsPath)`).
+     *
+     * TASK-043 (RFC-040 installer, hook bundling): the template now references
+     * pre-bundled, self-contained ESM `.mjs` files (esbuild, build-time —
+     * `bundle-hooks.ts`), so the command is a plain `node <path>` — no `npx
+     * tsx` (and no node_modules resolution) required at all on the install
+     * target. This is the fix for the AC-008 probe's `MODULE_NOT_FOUND`
+     * finding: a fresh install target has no node_modules for `tsx` to resolve
+     * a raw `.ts` hook's non-builtin imports against.
+     */
+    private resolveTemplateHooks;
+    private writeSettings;
+}
+export {};
+//# sourceMappingURL=HooksWirer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HooksWirer.d.ts","sourceRoot":"","sources":["../../src/install/HooksWirer.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,KAAK,UAAU,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;AAOzC,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBADlB,QAAQ,EAAE,aAAa,EACvB,kBAAkB,EAAE,MAAM;IAG7C,IAAI,IAAI;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE;IAenD,OAAO,CAAC,oBAAoB;IAQ5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,oBAAoB;IAkB5B,OAAO,CAAC,aAAa;CAItB"}

package/dist/install/HooksWirer.js

@@ -0,0 +1,80 @@
+/**
+ * HooksWirer - read-modify-write merge of the (pre-filtered, ADR-006) hooks
+ * template into a target `settings.json` (RF-005).
+ *
+ * Non-destructive at two levels (TASK-013):
+ *   1. Root of the JSON document — every non-`hooks` key already present
+ *      (`env`, `permissions`, ...) is preserved untouched.
+ *   2. Inside the `hooks` object — any event key NOT managed by this
+ *      template (e.g. a foreign plugin's event) is preserved untouched;
+ *      only the template's own event keys are (re)written, so re-running
+ *      `wire()` is idempotent for those keys (no duplication).
+ *
+ * `targetSettingsPath` is injected (ADR-004) — never resolved internally.
+ * `targetRoot` (the directory commands are prefixed with) is derived from
+ * `dirname(targetSettingsPath)`, since the template stores bare relative
+ * paths (e.g. `hooks/session-start.mjs`, a bundled artifact since TASK-043)
+ * that only become a runnable command once joined with the install target
+ * root.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export class HooksWirer {
+    template;
+    targetSettingsPath;
+    constructor(template, targetSettingsPath) {
+        this.template = template;
+        this.targetSettingsPath = targetSettingsPath;
+    }
+    wire() {
+        const existingSettings = this.readExistingSettings();
+        const resolvedTemplateHooks = this.resolveTemplateHooks();
+        const mergedHooks = {
+            ...(existingSettings.hooks ?? {}),
+            ...resolvedTemplateHooks,
+        };
+        const mergedSettings = { ...existingSettings, hooks: mergedHooks };
+        this.writeSettings(mergedSettings);
+        return { merged: true, hooksBlock: mergedHooks };
+    }
+    readExistingSettings() {
+        if (!existsSync(this.targetSettingsPath)) {
+            return {};
+        }
+        const raw = readFileSync(this.targetSettingsPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    /**
+     * Turns every relative `command` path in the template (e.g.
+     * `hooks/session-start.mjs`) into a runnable shell command anchored at
+     * `targetRoot` (`dirname(targetSettingsPath)`).
+     *
+     * TASK-043 (RFC-040 installer, hook bundling): the template now references
+     * pre-bundled, self-contained ESM `.mjs` files (esbuild, build-time —
+     * `bundle-hooks.ts`), so the command is a plain `node <path>` — no `npx
+     * tsx` (and no node_modules resolution) required at all on the install
+     * target. This is the fix for the AC-008 probe's `MODULE_NOT_FOUND`
+     * finding: a fresh install target has no node_modules for `tsx` to resolve
+     * a raw `.ts` hook's non-builtin imports against.
+     */
+    resolveTemplateHooks() {
+        const targetRoot = dirname(this.targetSettingsPath);
+        const resolved = {};
+        for (const [eventName, groups] of Object.entries(this.template.hooks)) {
+            resolved[eventName] = groups.map((group) => ({
+                matcher: group.matcher,
+                hooks: group.hooks.map((hook) => ({
+                    type: hook.type,
+                    command: `node ${join(targetRoot, hook.command)}`,
+                    timeout: hook.timeout,
+                })),
+            }));
+        }
+        return resolved;
+    }
+    writeSettings(settings) {
+        mkdirSync(dirname(this.targetSettingsPath), { recursive: true });
+        writeFileSync(this.targetSettingsPath, JSON.stringify(settings, null, 2));
+    }
+}
+//# sourceMappingURL=HooksWirer.js.map