@skillsmith/core 0.8.2 → 0.10.0

package/dist/src/install/agent-config-merge.yaml.js

@@ -0,0 +1,133 @@
+/**
+ * YAML config-merge helper for Hermes (SMI-5456 Wave 1 Step 5).
+ *
+ * Hermes is the one target harness whose MCP config is YAML
+ * (`~/.hermes/config.yaml`, key `mcp_servers:` — spike report §(b),
+ * well-verified against three independent official doc pages). The repo
+ * already carries a real `yaml` dependency (`packages/core/package.json` /
+ * root `package.json`, `"yaml": "^2.8.3"` — also already used by
+ * `packages/core/src/services/agent-pack/agent-pack.test.ts`), so this uses
+ * the library's structured Document API (`parseDocument`/`Document#setIn`)
+ * rather than the textual delimited-block scheme the task brief allowed as a
+ * fallback for "no YAML dep" — that fallback does not apply here since the
+ * dependency exists.
+ *
+ * GOVERNANCE FIX (SMI-5456 code review, 2026-07-01): this module originally
+ * used the library's plain `parse`/`stringify` functions. Those DISCARD
+ * every comment in the source file on round-trip (verified: `# top comment`
+ * + `# a server` + a trailing inline `# inline comment` all vanish after a
+ * `parse` → mutate → `stringify` cycle) — a straightforward
+ * preserve-user-content violation for anyone who annotates their own
+ * `~/.hermes/config.yaml`. `yaml`'s `Document`/`parseDocument`/`setIn` API
+ * operates on the CST and round-trips comments, anchors, and key ordering
+ * untouched, only rewriting the one path this module actually sets — see the
+ * in-container verification in the SMI-5456 code review report. One
+ * documented gap remains: a source file whose root is YAML-null (`~`/`null`,
+ * or a fully empty document) with a comment attached to that null node loses
+ * that specific comment when the null root is replaced with a fresh mapping
+ * (there is no collection node for `setIn` to attach into) — an edge case for
+ * a config file that carries no actual config, accepted rather than adding a
+ * bespoke CST-splicing path for it.
+ *
+ * @module @skillsmith/core/install/agent-config-merge.yaml
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Document, isMap, isScalar, parseDocument } from 'yaml';
+import { deepEqualJson, looksLikeOurMcpEntry, markBackedUp, shouldBackup, } from './agent-config-merge.types.js';
+function writeBackup(sourcePath, backupDir) {
+    mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const baseName = sourcePath.split('/').pop() ?? 'config';
+    const backupPath = join(backupDir, `${stamp}-${baseName}.bak`);
+    writeFileSync(backupPath, readFileSync(sourcePath, 'utf-8'), { mode: 0o600 });
+    return backupPath;
+}
+/** Unwrap a `yaml` Document node (or plain value) into a plain JS value for comparison. */
+function toPlainValue(node) {
+    if (node &&
+        typeof node === 'object' &&
+        'toJSON' in node &&
+        typeof node.toJSON === 'function') {
+        return node.toJSON();
+    }
+    return node;
+}
+/**
+ * Merge a `skillsmith` entry into `mcp_servers:` of a YAML config file.
+ * Same created/updated/unchanged/conflict/error contract as
+ * {@link import('./agent-config-merge.json.js').mergeJsonMcpEntry}. Uses the
+ * `yaml` package's `Document` (CST-backed) API so every comment, anchor, and
+ * unrelated key in the user's file survives the merge byte-for-byte except
+ * for the one path this function actually sets — see module header.
+ */
+export function mergeYamlMcpEntry(opts) {
+    const { path, entryValue, backupDir, force = false, mcpServersKey, alreadyBackedUpPaths } = opts;
+    let doc;
+    const existed = existsSync(path);
+    if (existed) {
+        let raw;
+        try {
+            raw = readFileSync(path, 'utf-8');
+        }
+        catch (e) {
+            return { status: 'error', path, backupPath: null, errorMessage: e.message };
+        }
+        if (raw.trim().length === 0) {
+            doc = new Document({});
+        }
+        else {
+            const parsed = parseDocument(raw);
+            if (parsed.errors.length > 0) {
+                return {
+                    status: 'error',
+                    path,
+                    backupPath: null,
+                    errorMessage: parsed.errors[0]?.message ?? 'YAML parse error',
+                };
+            }
+            if (parsed.contents !== null && isScalar(parsed.contents) && parsed.contents.value === null) {
+                // YAML-null root (`~`, `null`, or comments-only-then-null) — treat as
+                // an empty mapping, matching the JSON merge helper's "missing file is
+                // treated as {}" behavior. A fresh `Document` (rather than mutating
+                // `parsed.contents` in place) sidesteps `Document.Parsed`'s stricter
+                // `ParsedNode`-only contents typing; behaviorally identical either
+                // way since a bare null-root file carries no salvageable structure.
+                // Documented CST-comment-loss edge case for this specific shape —
+                // see module header.
+                doc = new Document({});
+            }
+            else if (parsed.contents !== null && !isMap(parsed.contents)) {
+                return { status: 'error', path, backupPath: null, errorMessage: 'not a YAML mapping' };
+            }
+            else {
+                doc = parsed;
+            }
+        }
+    }
+    else {
+        doc = new Document({});
+    }
+    const existingEntry = toPlainValue(doc.getIn([mcpServersKey, 'skillsmith']));
+    if (existingEntry !== undefined) {
+        if (deepEqualJson(existingEntry, entryValue)) {
+            return { status: 'unchanged', path, backupPath: null };
+        }
+        if (!looksLikeOurMcpEntry(existingEntry) && !force) {
+            return { status: 'conflict', path, backupPath: null };
+        }
+        const backupPath = existed && shouldBackup(path, alreadyBackedUpPaths) ? writeBackup(path, backupDir) : null;
+        markBackedUp(path, alreadyBackedUpPaths);
+        doc.setIn([mcpServersKey, 'skillsmith'], entryValue);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, doc.toString(), { mode: 0o600 });
+        return { status: 'updated', path, backupPath };
+    }
+    const backupPath = existed && shouldBackup(path, alreadyBackedUpPaths) ? writeBackup(path, backupDir) : null;
+    markBackedUp(path, alreadyBackedUpPaths);
+    doc.setIn([mcpServersKey, 'skillsmith'], entryValue);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, doc.toString(), { mode: 0o600 });
+    return { status: 'created', path, backupPath };
+}
+//# sourceMappingURL=agent-config-merge.yaml.js.map

package/dist/src/install/agent-config-merge.yaml.js.map

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

package/dist/src/install/agent-config-merge.yaml.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-config-merge.yaml.test.d.ts.map

package/dist/src/install/agent-config-merge.yaml.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config-merge.yaml.test.d.ts","sourceRoot":"","sources":["../../../src/install/agent-config-merge.yaml.test.ts"],"names":[],"mappings":""}

package/dist/src/install/agent-config-merge.yaml.test.js

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Unit tests for `mergeYamlMcpEntry` (SMI-5456 governance
+ *               follow-up, code review 2026-07-01).
+ * @module @skillsmith/core/install/agent-config-merge.yaml.test
+ *
+ * Added because this module previously had ZERO direct test coverage — the
+ * only harness exercising the YAML config format (Hermes) is never
+ * "detected" in `agent-pack-installer.test.ts` (no test creates `~/.hermes`),
+ * so the plain-`parse`/`stringify` comment-loss bug this file's governance
+ * fix addresses shipped with no test that could have caught it. Covers the
+ * created/updated/unchanged/conflict/error contract plus the comment-
+ * preservation regression itself.
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mergeYamlMcpEntry } from './agent-config-merge.yaml.js';
+let dir;
+let configPath;
+let backupDir;
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'skillsmith-yaml-merge-'));
+    configPath = join(dir, 'config.yaml');
+    backupDir = join(dir, 'backups');
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+const ENTRY = {
+    command: 'npx',
+    args: ['-y', '@skillsmith/mcp-server'],
+    env: { SKILLSMITH_TOOL_PROFILE: 'agent' },
+};
+describe('mergeYamlMcpEntry', () => {
+    it('creates the file + mcp_servers.skillsmith key when absent', () => {
+        const result = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(result.status).toBe('created');
+        expect(result.backupPath).toBeNull();
+        expect(existsSync(configPath)).toBe(true);
+        const content = readFileSync(configPath, 'utf-8');
+        expect(content).toContain('mcp_servers:');
+        expect(content).toContain('skillsmith:');
+    });
+    it('is idempotent: a second merge with the same entryValue reports unchanged and writes no backup', () => {
+        mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        const second = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(second.status).toBe('unchanged');
+        expect(second.backupPath).toBeNull();
+        expect(existsSync(backupDir)).toBe(false);
+    });
+    it('PRESERVES comments, unrelated keys, and key order on merge (governance regression test)', () => {
+        const src = [
+            '# top-of-file comment',
+            'some_other_tool:',
+            '  # a nested comment',
+            '  enabled: true # inline comment',
+            'mcp_servers:',
+            '  # an existing server',
+            '  other_server:',
+            '    command: bar',
+            '',
+        ].join('\n');
+        writeFileSync(configPath, src);
+        const result = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(result.status).toBe('created');
+        const out = readFileSync(configPath, 'utf-8');
+        expect(out).toContain('# top-of-file comment');
+        expect(out).toContain('# a nested comment');
+        expect(out).toContain('# inline comment');
+        expect(out).toContain('# an existing server');
+        expect(out).toContain('other_server:');
+        expect(out).toContain('enabled: true');
+        expect(out).toContain('skillsmith:');
+    });
+    it('does not clobber a foreign non-Skillsmith skillsmith entry (conflict, no force)', () => {
+        writeFileSync(configPath, 'mcp_servers:\n  skillsmith:\n    command: some-other-tool\n');
+        const result = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(result.status).toBe('conflict');
+        const out = readFileSync(configPath, 'utf-8');
+        expect(out).toContain('some-other-tool');
+    });
+    it('force: true overwrites a foreign entry and backs up the pre-existing file first', () => {
+        writeFileSync(configPath, 'mcp_servers:\n  skillsmith:\n    command: some-other-tool\n');
+        const result = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+            force: true,
+        });
+        expect(result.status).toBe('updated');
+        expect(result.backupPath).not.toBeNull();
+        expect(existsSync(result.backupPath)).toBe(true);
+        expect(readFileSync(result.backupPath, 'utf-8')).toContain('some-other-tool');
+    });
+    it('recognizes a prior skillsmith-owned entry (by structural fingerprint) and updates without --force', () => {
+        writeFileSync(configPath, 'mcp_servers:\n  skillsmith:\n    command: node\n    args:\n      - old/path/@skillsmith/mcp-server\n');
+        const result = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(result.status).toBe('updated');
+    });
+    it('never backs up twice for the same path in one run (alreadyBackedUpPaths)', () => {
+        writeFileSync(configPath, 'mcp_servers:\n  skillsmith:\n    command: node\n    args: ["@skillsmith/mcp-server"]\n');
+        const alreadyBackedUpPaths = new Set();
+        const first = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+            alreadyBackedUpPaths,
+        });
+        expect(first.backupPath).not.toBeNull();
+        // Merge into a DIFFERENT key path in the same file — simulates a second
+        // merge call touching the same shared config file within one install run.
+        const second = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'other_servers',
+            entryValue: ENTRY,
+            backupDir,
+            alreadyBackedUpPaths,
+        });
+        expect(second.backupPath).toBeNull();
+        expect(existsSync(backupDir)).toBe(true);
+    });
+    it('returns an error status (never throws) for malformed YAML', () => {
+        writeFileSync(configPath, ': not: valid: yaml: [');
+        const result = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(result.status).toBe('error');
+        expect(result.errorMessage).toBeTruthy();
+    });
+    it('returns an error status for a non-mapping YAML root (a list)', () => {
+        writeFileSync(configPath, '- one\n- two\n');
+        const result = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(result.status).toBe('error');
+    });
+    it('treats a YAML-null root (~) as an empty mapping, matching the "missing file" behavior', () => {
+        writeFileSync(configPath, '~\n');
+        const result = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(result.status).toBe('created');
+        expect(readFileSync(configPath, 'utf-8')).toContain('skillsmith:');
+    });
+    it('treats an empty file the same as a missing one', () => {
+        writeFileSync(configPath, '');
+        const result = mergeYamlMcpEntry({
+            path: configPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(result.status).toBe('created');
+    });
+    it('creates the parent directory when it does not exist', () => {
+        const nestedPath = join(dir, 'nested', 'dir', 'config.yaml');
+        mkdirSync(join(dir, 'nested'), { recursive: false });
+        const result = mergeYamlMcpEntry({
+            path: nestedPath,
+            mcpServersKey: 'mcp_servers',
+            entryValue: ENTRY,
+            backupDir,
+        });
+        expect(result.status).toBe('created');
+        expect(existsSync(nestedPath)).toBe(true);
+    });
+});
+//# sourceMappingURL=agent-config-merge.yaml.test.js.map

package/dist/src/install/agent-config-merge.yaml.test.js.map

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

package/dist/src/install/agent-harness-targets.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Per-harness on-disk targets for the `sklx agent install` / `uninstall`
+ * commands (SMI-5456 Wave 1 Step 5).
+ *
+ * This module is pure data (no filesystem access) — it says WHERE each
+ * harness's MCP config and hook config live and in what format, so
+ * `agent-config-merge*.ts` can merge into them generically and
+ * `agent-pack-installer.ts` doesn't hard-code per-harness path logic inline.
+ *
+ * Confidence levels (documented per plan's own Validation Ladder philosophy —
+ * Level 2a/3 in docs/internal/implementation/smi-5456-skillsmith-agent-wave1.md
+ * is explicitly where per-harness wire formats get confirmed against real
+ * harness binaries; Step-6 eval-worker web-verification 2026-07-01 upgraded
+ * three rows from the original Step-5 estimates):
+ *   - claude-code, cursor, windsurf: HIGH — MCP config path/shape verified
+ *     against `packages/cli/src/templates/mcp-server.template.snippets.ts`
+ *     (SMI-4580, already shipped and used in docs/website).
+ *   - hermes: HIGH for the skill path + YAML config shape (spike report §(b),
+ *     3 independent official doc pages agree); hooks are spike-verified
+ *     ABSENT (no SessionStart equivalent) — {@link AGENT_HOOK_TARGETS}
+ *     therefore carries no hook target for hermes.
+ *   - codex: HIGH for the config file path (`~/.codex/config.toml`, same
+ *     snippet table) AND — per Step-6 verification of
+ *     developers.openai.com/codex/hooks — HIGH for the hook-registration
+ *     shape: inline `[[hooks.SessionStart]]` / `[[hooks.SessionStart.hooks]]`
+ *     array-of-tables carrying `{type, command, timeout, statusMessage}`.
+ *     Codex has NO SessionEnd event, and its Stop event fires PER-TURN (not
+ *     per-session) — see `installCodexHooks` in
+ *     `agent-pack-installer.harness.ts` for why nothing is wired for cleanup.
+ *   - copilot: HIGH — `~/.copilot/mcp-config.json`, top-level `mcpServers`
+ *     key (Step-6 verified; the earlier `mcp.json` guess was wrong). Global,
+ *     not VS Code's workspace `.vscode/mcp.json`, remains correct: Copilot
+ *     CLI removed `.vscode/mcp.json` support, and `sklx agent install` is a
+ *     global (not per-project) command.
+ *   - opencode: HIGH — `~/.config/opencode/opencode.json` under the `mcp`
+ *     key, entries typed `local|remote` (Step-6 verified against
+ *     opencode.ai/docs; entry VALUE shape differs from the mcpServers
+ *     convention — see `buildOpenCodeMcpEntryValue` in
+ *     `agent-pack-installer.entry.ts`). Agent markdown lives at
+ *     `~/.config/opencode/agents/` — plural (opencode.ai/docs/agents/; the
+ *     earlier singular `agent/` guess was wrong).
+ */
+import type { HarnessId } from '../services/agent-pack/index.js';
+/** Harnesses that can receive an MCP server registration (all 7 targets). */
+export type McpHarnessId = HarnessId | 'windsurf' | 'hermes';
+/** Config-file format the merge helper must speak for a given target. */
+export type ConfigFormat = 'json' | 'yaml' | 'toml-block';
+/**
+ * Where + how to merge the Skillsmith MCP server registration for one harness.
+ *
+ * `keyPath` is only meaningful for `format: 'json'` — the property path (from
+ * the parsed document root) to the object the merge helper inserts
+ * `skillsmith: {...}` into, creating intermediate objects as needed.
+ * `format: 'toml-block'` targets ignore `keyPath` — see
+ * `agent-config-merge.toml-block.ts` for the marker-delimited scheme.
+ */
+export interface McpConfigTarget {
+    harness: McpHarnessId;
+    path: string;
+    format: ConfigFormat;
+    keyPath: string[];
+}
+/** Where to write a named-agent shim file for a harness that has one. */
+export interface ShimTarget {
+    harness: HarnessId;
+    /** Absolute file path the rendered shim content is written to verbatim. */
+    path: string;
+}
+/**
+ * Where to install a hook SCRIPT and how to wire it into that harness's hook
+ * config. `configFormat`/`configPath`/`keyPath` follow the same shape as
+ * {@link McpConfigTarget} so hook wiring reuses the same merge helpers.
+ */
+export interface HookInstallTarget {
+    harness: 'claude-code' | 'cursor' | 'codex';
+    /** Directory the hook script itself is copied into (chmod 0755). */
+    scriptDir: string;
+    configPath: string;
+    configFormat: ConfigFormat;
+    /** Key path to the array this hook's command entry is appended to. */
+    sessionStartKeyPath: string[];
+    sessionEndKeyPath: string[];
+}
+/** MCP registration targets for every harness the pack supports (PRD §3.1). */
+export declare const AGENT_MCP_TARGETS: Readonly<Record<McpHarnessId, McpConfigTarget>>;
+/**
+ * Named-agent shim file targets, per {@link HarnessId} (PRD §3.1 constraint
+ * 2 / architecture doc artifacts A2-A5). Cursor and (VS Code's) Copilot both
+ * read `.claude/agents/*.md` natively per the constraint matrix, so they
+ * share the claude-code shim file rather than getting a second copy — only
+ * harnesses with their OWN native shim format get a dedicated target here.
+ */
+export declare const AGENT_SHIM_TARGETS: Readonly<Record<HarnessId, ShimTarget | null>>;
+/** Hook install targets — only harnesses with a real SessionStart hook (HOOK_HARNESSES). */
+export declare const AGENT_HOOK_TARGETS: Readonly<Record<'claude-code' | 'cursor' | 'codex', HookInstallTarget>>;
+/** Codex's `[agents.skillsmith-agent]` TOML entry lives in the same config file as its MCP registration. */
+export declare const CODEX_CONFIG_TOML_PATH: string;
+//# sourceMappingURL=agent-harness-targets.d.ts.map

package/dist/src/install/agent-harness-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-harness-targets.d.ts","sourceRoot":"","sources":["../../../src/install/agent-harness-targets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAA;AAEhE,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAA;AAE5D,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,CAAA;AAEzD;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,SAAS,CAAA;IAClB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAA;IAC3C,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,YAAY,CAAA;IAC1B,sEAAsE;IACtE,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAC5B;AAID,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,CA2C7E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC,CAqB7E,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CACvC,MAAM,CAAC,aAAa,GAAG,QAAQ,GAAG,OAAO,EAAE,iBAAiB,CAAC,CA+B9D,CAAA;AAED,4GAA4G;AAC5G,eAAO,MAAM,sBAAsB,QAA+B,CAAA"}

package/dist/src/install/agent-harness-targets.js

@@ -0,0 +1,154 @@
+/**
+ * Per-harness on-disk targets for the `sklx agent install` / `uninstall`
+ * commands (SMI-5456 Wave 1 Step 5).
+ *
+ * This module is pure data (no filesystem access) — it says WHERE each
+ * harness's MCP config and hook config live and in what format, so
+ * `agent-config-merge*.ts` can merge into them generically and
+ * `agent-pack-installer.ts` doesn't hard-code per-harness path logic inline.
+ *
+ * Confidence levels (documented per plan's own Validation Ladder philosophy —
+ * Level 2a/3 in docs/internal/implementation/smi-5456-skillsmith-agent-wave1.md
+ * is explicitly where per-harness wire formats get confirmed against real
+ * harness binaries; Step-6 eval-worker web-verification 2026-07-01 upgraded
+ * three rows from the original Step-5 estimates):
+ *   - claude-code, cursor, windsurf: HIGH — MCP config path/shape verified
+ *     against `packages/cli/src/templates/mcp-server.template.snippets.ts`
+ *     (SMI-4580, already shipped and used in docs/website).
+ *   - hermes: HIGH for the skill path + YAML config shape (spike report §(b),
+ *     3 independent official doc pages agree); hooks are spike-verified
+ *     ABSENT (no SessionStart equivalent) — {@link AGENT_HOOK_TARGETS}
+ *     therefore carries no hook target for hermes.
+ *   - codex: HIGH for the config file path (`~/.codex/config.toml`, same
+ *     snippet table) AND — per Step-6 verification of
+ *     developers.openai.com/codex/hooks — HIGH for the hook-registration
+ *     shape: inline `[[hooks.SessionStart]]` / `[[hooks.SessionStart.hooks]]`
+ *     array-of-tables carrying `{type, command, timeout, statusMessage}`.
+ *     Codex has NO SessionEnd event, and its Stop event fires PER-TURN (not
+ *     per-session) — see `installCodexHooks` in
+ *     `agent-pack-installer.harness.ts` for why nothing is wired for cleanup.
+ *   - copilot: HIGH — `~/.copilot/mcp-config.json`, top-level `mcpServers`
+ *     key (Step-6 verified; the earlier `mcp.json` guess was wrong). Global,
+ *     not VS Code's workspace `.vscode/mcp.json`, remains correct: Copilot
+ *     CLI removed `.vscode/mcp.json` support, and `sklx agent install` is a
+ *     global (not per-project) command.
+ *   - opencode: HIGH — `~/.config/opencode/opencode.json` under the `mcp`
+ *     key, entries typed `local|remote` (Step-6 verified against
+ *     opencode.ai/docs; entry VALUE shape differs from the mcpServers
+ *     convention — see `buildOpenCodeMcpEntryValue` in
+ *     `agent-pack-installer.entry.ts`). Agent markdown lives at
+ *     `~/.config/opencode/agents/` — plural (opencode.ai/docs/agents/; the
+ *     earlier singular `agent/` guess was wrong).
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const home = homedir();
+/** MCP registration targets for every harness the pack supports (PRD §3.1). */
+export const AGENT_MCP_TARGETS = {
+    'claude-code': {
+        harness: 'claude-code',
+        path: join(home, '.claude', 'settings.json'),
+        format: 'json',
+        keyPath: ['mcpServers'],
+    },
+    cursor: {
+        harness: 'cursor',
+        path: join(home, '.cursor', 'mcp.json'),
+        format: 'json',
+        keyPath: ['mcpServers'],
+    },
+    copilot: {
+        harness: 'copilot',
+        path: join(home, '.copilot', 'mcp-config.json'),
+        format: 'json',
+        keyPath: ['mcpServers'],
+    },
+    windsurf: {
+        harness: 'windsurf',
+        path: join(home, '.codeium', 'windsurf', 'mcp_config.json'),
+        format: 'json',
+        keyPath: ['mcpServers'],
+    },
+    opencode: {
+        harness: 'opencode',
+        path: join(home, '.config', 'opencode', 'opencode.json'),
+        format: 'json',
+        keyPath: ['mcp'],
+    },
+    codex: {
+        harness: 'codex',
+        path: join(home, '.codex', 'config.toml'),
+        format: 'toml-block',
+        keyPath: [],
+    },
+    hermes: {
+        harness: 'hermes',
+        path: join(home, '.hermes', 'config.yaml'),
+        format: 'yaml',
+        keyPath: ['mcp_servers'],
+    },
+};
+/**
+ * Named-agent shim file targets, per {@link HarnessId} (PRD §3.1 constraint
+ * 2 / architecture doc artifacts A2-A5). Cursor and (VS Code's) Copilot both
+ * read `.claude/agents/*.md` natively per the constraint matrix, so they
+ * share the claude-code shim file rather than getting a second copy — only
+ * harnesses with their OWN native shim format get a dedicated target here.
+ */
+export const AGENT_SHIM_TARGETS = {
+    'claude-code': {
+        harness: 'claude-code',
+        path: join(home, '.claude', 'agents', 'skillsmith-agent.md'),
+    },
+    // Cursor 2.4+ reads `.claude/agents/` natively — no separate shim file.
+    cursor: null,
+    copilot: {
+        harness: 'copilot',
+        path: join(home, '.copilot', 'agents', 'skillsmith-agent.agent.md'),
+    },
+    opencode: {
+        harness: 'opencode',
+        // Step-6 verified (opencode.ai/docs/agents/): global agent markdown
+        // lives at ~/.config/opencode/agents/ — plural.
+        path: join(home, '.config', 'opencode', 'agents', 'skillsmith-agent.md'),
+    },
+    // Codex's shim is a TOML `[agents.*]` table entry merged into
+    // ~/.codex/config.toml, not a standalone file — see AGENT_MCP_TARGETS.codex
+    // and agent-config-merge.toml-block.ts. No separate ShimTarget.
+    codex: null,
+};
+/** Hook install targets — only harnesses with a real SessionStart hook (HOOK_HARNESSES). */
+export const AGENT_HOOK_TARGETS = {
+    'claude-code': {
+        harness: 'claude-code',
+        scriptDir: join(home, '.claude', 'hooks'),
+        configPath: join(home, '.claude', 'settings.json'),
+        configFormat: 'json',
+        sessionStartKeyPath: ['hooks', 'SessionStart'],
+        sessionEndKeyPath: ['hooks', 'SessionEnd'],
+    },
+    cursor: {
+        harness: 'cursor',
+        scriptDir: join(home, '.cursor', 'hooks'),
+        configPath: join(home, '.cursor', 'hooks.json'),
+        configFormat: 'json',
+        // Cursor's hooks.json is Claude-compatible (PRD §3.1) but is itself the
+        // hooks map (no wrapping "hooks" key) — see module header confidence note.
+        sessionStartKeyPath: ['SessionStart'],
+        sessionEndKeyPath: ['SessionEnd'],
+    },
+    codex: {
+        harness: 'codex',
+        scriptDir: join(home, '.codex', 'hooks'),
+        configPath: join(home, '.codex', 'config.toml'),
+        configFormat: 'toml-block',
+        // Unused for toml-block wiring (the block text carries its own
+        // `[[hooks.SessionStart]]` headers); SessionEnd does not exist as a
+        // Codex event at all — see `installCodexHooks`.
+        sessionStartKeyPath: [],
+        sessionEndKeyPath: [],
+    },
+};
+/** Codex's `[agents.skillsmith-agent]` TOML entry lives in the same config file as its MCP registration. */
+export const CODEX_CONFIG_TOML_PATH = AGENT_MCP_TARGETS.codex.path;
+//# sourceMappingURL=agent-harness-targets.js.map

package/dist/src/install/agent-harness-targets.js.map

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