@skillsmith/core 0.9.0 → 0.10.0

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

@@ -0,0 +1,134 @@
+/**
+ * JSON config-merge helper for `sklx agent install` (SMI-5456 Wave 1 Step 5).
+ *
+ * Targets the `mcpServers`/`mcp`-shaped config files four of the seven
+ * harnesses use (claude-code, cursor, copilot, windsurf; also opencode's
+ * best-effort `mcp` key — see `agent-harness-targets.ts`). Backup-first,
+ * idempotent, preserve-and-prompt semantics per the plan's P-5 "Harness MCP
+ * config files" invariant: "Installer merges keys it owns, never whole-file
+ * writes; detects foreign `skillsmith` entries and prompts."
+ *
+ * Survey of existing config-write patterns (plan-mandated, "convention check
+ * before novelty"): `grep -rn "mcp.json\|mcp_config\|claude.json"
+ * packages/cli/src/ packages/core/src/` turned up
+ * `mcp-server.template.snippets.ts` (SMI-4580, docs-only — renders snippet
+ * TEXT for a human to paste, never writes a file) and
+ * `skill-installation.policy.ts` (classifies `.mcp.json` as a scan target,
+ * never writes one). Neither is a merge-writer to follow structurally, so
+ * this module's shape instead mirrors the nearest write-path precedent in
+ * the codebase: `config/index.ts`'s `saveConfig()` (mkdir 0700 + writeFile
+ * 0600, read-merge-write, JSON.stringify(..., null, 2)).
+ *
+ * @module @skillsmith/core/install/agent-config-merge.json
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { deepEqualJson, looksLikeOurMcpEntry, markBackedUp, shouldBackup, } from './agent-config-merge.types.js';
+/** Read + set a nested key path on a JSON object, creating intermediate objects. */
+function getAtPath(root, keyPath) {
+    let cur = root;
+    for (const key of keyPath) {
+        if (!cur || typeof cur !== 'object' || Array.isArray(cur))
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+function setAtPath(root, keyPath, value) {
+    let cur = root;
+    for (let i = 0; i < keyPath.length - 1; i++) {
+        const key = keyPath[i];
+        const next = cur[key];
+        if (!next || typeof next !== 'object' || Array.isArray(next)) {
+            cur[key] = {};
+        }
+        cur = cur[key];
+    }
+    const lastKey = keyPath[keyPath.length - 1];
+    if (lastKey !== undefined)
+        cur[lastKey] = value;
+}
+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;
+}
+/**
+ * Merge a `skillsmith` MCP server entry into a JSON config file at
+ * `opts.path`, under `opts.keyPath` (e.g. `['mcpServers']`).
+ *
+ * Never performs a whole-file write of unrelated keys — the file is parsed,
+ * exactly one nested key (`skillsmith`) is set at `[...keyPath, 'skillsmith']`,
+ * and the WHOLE document (all other keys untouched) is re-serialized. A
+ * missing file is treated as `{}` (created fresh).
+ */
+export function mergeJsonMcpEntry(opts) {
+    const { path, keyPath, entryValue, backupDir, force = false, alreadyBackedUpPaths } = opts;
+    let doc = {};
+    let existed = false;
+    if (existsSync(path)) {
+        existed = true;
+        let raw;
+        try {
+            raw = readFileSync(path, 'utf-8');
+        }
+        catch (e) {
+            return { status: 'error', path, backupPath: null, errorMessage: e.message };
+        }
+        try {
+            const parsed = raw.trim().length === 0 ? {} : JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return { status: 'error', path, backupPath: null, errorMessage: 'not a JSON object' };
+            }
+            doc = parsed;
+        }
+        catch (e) {
+            return { status: 'error', path, backupPath: null, errorMessage: e.message };
+        }
+    }
+    const container = getAtPath(doc, keyPath);
+    const existingEntry = container && typeof container === 'object' && !Array.isArray(container)
+        ? container.skillsmith
+        : undefined;
+    if (existingEntry !== undefined) {
+        if (deepEqualJson(existingEntry, entryValue)) {
+            return { status: 'unchanged', path, backupPath: null };
+        }
+        if (!looksLikeOurMcpEntry(existingEntry) && !force) {
+            // Non-interactive refusal (P-5 preserve-existing): never clobber a
+            // foreign entry silently, never block on a prompt in a scripted
+            // install — surface a 'conflict' the CLI report + --force flag address.
+            return { status: 'conflict', path, backupPath: null };
+        }
+        // Recognizable as ours (or force=true): back up (once per install run),
+        // then overwrite. Marking `alreadyBackedUpPaths` UNCONDITIONALLY (not
+        // only when a backup was actually written) is what prevents a LATER
+        // merge into this same path this run from treating content THIS merge
+        // just wrote as pre-install state needing its own backup — see
+        // `agent-pack-installer.test.ts` "double-install idempotency" /
+        // "preserve-existing" suites.
+        const backupPath = existed && shouldBackup(path, alreadyBackedUpPaths) ? writeBackup(path, backupDir) : null;
+        markBackedUp(path, alreadyBackedUpPaths);
+        setAtPath(doc, keyPath, { ...container, skillsmith: entryValue });
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, JSON.stringify(doc, null, 2) + '\n', { mode: 0o600 });
+        return { status: 'updated', path, backupPath };
+    }
+    // No existing entry — safe create. Still back up the FILE (not the
+    // skillsmith key, which didn't exist) so a foreign file with unrelated
+    // content the user cares about is always one restore away — unless an
+    // earlier merge THIS RUN already captured the pre-install state.
+    const backupPath = existed && shouldBackup(path, alreadyBackedUpPaths) ? writeBackup(path, backupDir) : null;
+    markBackedUp(path, alreadyBackedUpPaths);
+    const currentContainer = container && typeof container === 'object' && !Array.isArray(container)
+        ? container
+        : {};
+    setAtPath(doc, keyPath, { ...currentContainer, skillsmith: entryValue });
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(doc, null, 2) + '\n', { mode: 0o600 });
+    return { status: 'created', path, backupPath };
+}
+//# sourceMappingURL=agent-config-merge.json.js.map

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

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

package/dist/src/install/agent-config-merge.toml-block.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Marker-delimited TOML block merge for Codex (SMI-5456 Wave 1 Step 5).
+ *
+ * Codex's config lives entirely in `~/.codex/config.toml` — MCP server
+ * registration (`[mcp_servers.skillsmith]`), the named-agent shim
+ * (`[agents.skillsmith-agent]`, already rendered as TOML text by
+ * `renderCodexToml` in the — locked for this step — agent-pack generator),
+ * and hook wiring all share this one file. The repo has no confirmed real
+ * TOML dependency (`smol-toml` appears only under root `overrides`, pinning
+ * a transitive tool dependency, not a direct `dependencies`/`devDependencies`
+ * entry of `@skillsmith/core` or `@skillsmith/cli`) — adding one is a
+ * lockfile-risk change out of scope for this step. Per the task brief's
+ * explicit fallback for "no [format] dep": generate the block textually with
+ * a clearly-delimited managed section, exactly mirroring how
+ * `renderCodexToml` (shims.ts, locked) already emits raw TOML text via
+ * `JSON.stringify`-quoted strings rather than a library. This keeps every
+ * OTHER line of the user's `config.toml` — their own tables, comments,
+ * formatting — completely untouched; only the text between our markers is
+ * ever rewritten.
+ *
+ * Ownership model: text between `# >>> skillsmith:<markerId> >>>` and
+ * `# <<< skillsmith:<markerId> <<<` is unambiguously ours (idempotent
+ * update-in-place). A bare occurrence of the target table header OUTSIDE any
+ * marker block (`foreignHeaderPattern`) is a hand-written foreign entry —
+ * `force` does NOT override this case: appending a second `[table]` header
+ * with the same name risks producing invalid/ambiguous TOML without a real
+ * parser to detect and merge it, so this always returns `'conflict'` for a
+ * genuinely foreign, non-delimited entry regardless of `force`.
+ *
+ * @module @skillsmith/core/install/agent-config-merge.toml-block
+ */
+import { type MergeResult } from './agent-config-merge.types.js';
+export interface TomlBlockMergeOptions {
+    path: string;
+    /** Stable id for the marker comment, e.g. `'mcp_servers.skillsmith'`. */
+    markerId: string;
+    /** Raw TOML text to install between the markers (no marker lines, no leading/trailing blank lines required). */
+    blockContent: string;
+    /** Matches a bare (non-delimited) occurrence of the same table header, e.g. `/^\[mcp_servers\.skillsmith\]/m`. */
+    foreignHeaderPattern: RegExp;
+    backupDir: string;
+    force?: boolean;
+    /** See `MergeOptions.alreadyBackedUpPaths` — Codex merges TWO blocks (MCP + agents shim) into the same `config.toml` per install run. */
+    alreadyBackedUpPaths?: Set<string>;
+}
+/** Merge a marker-delimited TOML block into `opts.path`. See module header for the full ownership contract. */
+export declare function mergeTomlBlock(opts: TomlBlockMergeOptions): MergeResult;
+//# sourceMappingURL=agent-config-merge.toml-block.d.ts.map

package/dist/src/install/agent-config-merge.toml-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config-merge.toml-block.d.ts","sourceRoot":"","sources":["../../../src/install/agent-config-merge.toml-block.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,EAA8B,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAE5F,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;IAChB,gHAAgH;IAChH,YAAY,EAAE,MAAM,CAAA;IACpB,kHAAkH;IAClH,oBAAoB,EAAE,MAAM,CAAA;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,yIAAyI;IACzI,oBAAoB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CACnC;AAkBD,+GAA+G;AAC/G,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,WAAW,CAmEvE"}

package/dist/src/install/agent-config-merge.toml-block.js

@@ -0,0 +1,107 @@
+/**
+ * Marker-delimited TOML block merge for Codex (SMI-5456 Wave 1 Step 5).
+ *
+ * Codex's config lives entirely in `~/.codex/config.toml` — MCP server
+ * registration (`[mcp_servers.skillsmith]`), the named-agent shim
+ * (`[agents.skillsmith-agent]`, already rendered as TOML text by
+ * `renderCodexToml` in the — locked for this step — agent-pack generator),
+ * and hook wiring all share this one file. The repo has no confirmed real
+ * TOML dependency (`smol-toml` appears only under root `overrides`, pinning
+ * a transitive tool dependency, not a direct `dependencies`/`devDependencies`
+ * entry of `@skillsmith/core` or `@skillsmith/cli`) — adding one is a
+ * lockfile-risk change out of scope for this step. Per the task brief's
+ * explicit fallback for "no [format] dep": generate the block textually with
+ * a clearly-delimited managed section, exactly mirroring how
+ * `renderCodexToml` (shims.ts, locked) already emits raw TOML text via
+ * `JSON.stringify`-quoted strings rather than a library. This keeps every
+ * OTHER line of the user's `config.toml` — their own tables, comments,
+ * formatting — completely untouched; only the text between our markers is
+ * ever rewritten.
+ *
+ * Ownership model: text between `# >>> skillsmith:<markerId> >>>` and
+ * `# <<< skillsmith:<markerId> <<<` is unambiguously ours (idempotent
+ * update-in-place). A bare occurrence of the target table header OUTSIDE any
+ * marker block (`foreignHeaderPattern`) is a hand-written foreign entry —
+ * `force` does NOT override this case: appending a second `[table]` header
+ * with the same name risks producing invalid/ambiguous TOML without a real
+ * parser to detect and merge it, so this always returns `'conflict'` for a
+ * genuinely foreign, non-delimited entry regardless of `force`.
+ *
+ * @module @skillsmith/core/install/agent-config-merge.toml-block
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { markBackedUp, shouldBackup } from './agent-config-merge.types.js';
+function markerStart(markerId) {
+    return `# >>> skillsmith:${markerId} >>>`;
+}
+function markerEnd(markerId) {
+    return `# <<< skillsmith:${markerId} <<<`;
+}
+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;
+}
+/** Merge a marker-delimited TOML block into `opts.path`. See module header for the full ownership contract. */
+export function mergeTomlBlock(opts) {
+    const { path, markerId, blockContent, foreignHeaderPattern, backupDir, force = false, alreadyBackedUpPaths, } = opts;
+    const start = markerStart(markerId);
+    const end = markerEnd(markerId);
+    const trimmedBlock = blockContent.trim();
+    const existed = existsSync(path);
+    let raw = '';
+    if (existed) {
+        try {
+            raw = readFileSync(path, 'utf-8');
+        }
+        catch (e) {
+            return { status: 'error', path, backupPath: null, errorMessage: e.message };
+        }
+    }
+    const blockRegex = new RegExp(`${escapeRegExp(start)}\\n([\\s\\S]*?)\\n${escapeRegExp(end)}`);
+    const match = raw.match(blockRegex);
+    if (match) {
+        const existingBlock = (match[1] ?? '').trim();
+        if (existingBlock === trimmedBlock) {
+            return { status: 'unchanged', path, backupPath: null };
+        }
+        const backupPath = shouldBackup(path, alreadyBackedUpPaths)
+            ? writeBackup(path, backupDir)
+            : null;
+        markBackedUp(path, alreadyBackedUpPaths);
+        const replacement = `${start}\n${trimmedBlock}\n${end}`;
+        const updated = raw.replace(blockRegex, replacement);
+        writeFileSync(path, updated, { mode: 0o600 });
+        return { status: 'updated', path, backupPath };
+    }
+    // No marker block found. A bare same-name table header outside any marker
+    // is a foreign hand-written entry — never safely mergeable without a real
+    // TOML parser (see module header). `force` does not override this case.
+    if (foreignHeaderPattern.test(raw)) {
+        void force;
+        return { status: 'conflict', path, backupPath: null };
+    }
+    const backupPath = existed && shouldBackup(path, alreadyBackedUpPaths) ? writeBackup(path, backupDir) : null;
+    markBackedUp(path, alreadyBackedUpPaths);
+    const separator = raw.length > 0 && !raw.endsWith('\n\n') ? (raw.endsWith('\n') ? '\n' : '\n\n') : '';
+    const appended = `${raw}${separator}${start}\n${trimmedBlock}\n${end}\n`;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, appended, { mode: 0o600 });
+    // Always 'created', never `existed ? 'updated' : 'created'`: OUR block
+    // didn't exist before this write regardless of whether the surrounding
+    // FILE pre-existed (a foreign file with unrelated content, or — within
+    // one install run — a file another block already created moments ago,
+    // e.g. Codex's agents-shim block creating config.toml before the
+    // mcp_servers block merges into it). 'updated' is reserved for replacing
+    // OUR OWN previously-installed block with different content (the `match`
+    // branch above).
+    return { status: 'created', path, backupPath };
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=agent-config-merge.toml-block.js.map

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

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

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

@@ -0,0 +1,87 @@
+/**
+ * Shared result/option types for the agent-install config-merge helpers
+ * (SMI-5456 Wave 1 Step 5). One shape reused by the JSON, YAML, and
+ * TOML-block merge implementations so the installer orchestrator branches on
+ * a single result contract regardless of which harness's config format it
+ * just merged into.
+ *
+ * @module @skillsmith/core/install/agent-config-merge.types
+ */
+/**
+ * Outcome of a single merge attempt.
+ *
+ *   created   - the file (or the whole key path) did not exist; created fresh.
+ *   updated   - an entry recognizable as OURS existed with different content
+ *               (e.g. a version bump); backed up the file, then overwrote.
+ *   unchanged - an entry recognizable as OURS already matched exactly —
+ *               idempotent no-op, no backup written (P-5 double-install test).
+ *   conflict  - an entry existed that does NOT look like ours; left
+ *               untouched unless `force` was passed.
+ *   error     - the file could not be read/parsed/written; left untouched.
+ */
+export type MergeStatus = 'created' | 'updated' | 'unchanged' | 'conflict' | 'error';
+export interface MergeResult {
+    status: MergeStatus;
+    path: string;
+    /** Absolute path to the pre-write backup, or null when no backup was needed. */
+    backupPath: string | null;
+    /** Present only when status is 'error'. */
+    errorMessage?: string;
+}
+export interface MergeOptions {
+    path: string;
+    /** The value to install under the `skillsmith` key. */
+    entryValue: Record<string, unknown>;
+    /** Directory backups are written into. Caller ensures it exists. */
+    backupDir: string;
+    /**
+     * When an existing entry does not look like ours, overwrite it anyway.
+     * Defaults to false — the non-interactive refusal path (P-5 preserve-
+     * existing test): no prompt, no silent clobber, just a `'conflict'` result
+     * the caller surfaces in the per-harness report.
+     */
+    force?: boolean;
+    /**
+     * Paths already backed up during THIS `installAgentPack` run (shared
+     * across every merge call in the run — `HarnessInstallCtx.backedUpPaths`).
+     * Some harnesses (claude-code) merge into the SAME file more than once per
+     * run (SessionStart hook, SessionEnd hook, then MCP registration, all in
+     * `~/.claude/settings.json`) — without this, the second and third merges
+     * would each "back up" a state that WE ourselves just wrote earlier in the
+     * same run, producing redundant, meaningless backups. A path is only ever
+     * backed up once per run, capturing genuine pre-install content.
+     */
+    alreadyBackedUpPaths?: Set<string>;
+}
+/**
+ * Decide whether a merge should take a backup of `path` right now: only if
+ * it hasn't already been backed up earlier in this same install run. Callers
+ * that DO write a backup must call {@link markBackedUp} immediately after.
+ */
+export declare function shouldBackup(path: string, alreadyBackedUpPaths: Set<string> | undefined): boolean;
+/** Record that `path` has now been backed up for the remainder of this install run. */
+export declare function markBackedUp(path: string, alreadyBackedUpPaths: Set<string> | undefined): void;
+/**
+ * Heuristic ownership check shared by every format-specific merge helper:
+ * does an existing entry look like a Skillsmith MCP server registration we
+ * (a prior `sklx agent install` run) wrote, as opposed to a user's own
+ * hand-written `skillsmith`-named entry pointing somewhere else entirely?
+ *
+ * There is no injected marker field in the entry value itself (that would
+ * pollute a config another tool's strict-schema client might read) — instead
+ * this checks for the structural fingerprint our own entries always carry,
+ * across BOTH entry conventions the installer writes:
+ *   - mcpServers convention (claude-code/cursor/copilot/windsurf/hermes):
+ *     an `args` array mentioning `@skillsmith/mcp-server`, or an
+ *     `env.SKILLSMITH_TOOL_PROFILE` key.
+ *   - OpenCode convention (`buildOpenCodeMcpEntryValue`): a `command` ARRAY
+ *     mentioning `@skillsmith/mcp-server`, or an
+ *     `environment.SKILLSMITH_TOOL_PROFILE` key. Without these two checks, a
+ *     re-install after any entry-value change would misclassify our own
+ *     prior OpenCode entry as foreign and refuse to update it.
+ * Any one is a strong, low-false-positive signal.
+ */
+export declare function looksLikeOurMcpEntry(value: unknown): boolean;
+/** Deep structural equality for plain JSON-shaped values (objects/arrays/primitives). */
+export declare function deepEqualJson(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=agent-config-merge.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config-merge.types.d.ts","sourceRoot":"","sources":["../../../src/install/agent-config-merge.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,CAAA;AAEpF,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,gFAAgF;IAChF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CACnC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,GAAG,OAAO,CAEjG;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI,CAE9F;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAa5D;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAkB7D"}

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

@@ -0,0 +1,83 @@
+/**
+ * Shared result/option types for the agent-install config-merge helpers
+ * (SMI-5456 Wave 1 Step 5). One shape reused by the JSON, YAML, and
+ * TOML-block merge implementations so the installer orchestrator branches on
+ * a single result contract regardless of which harness's config format it
+ * just merged into.
+ *
+ * @module @skillsmith/core/install/agent-config-merge.types
+ */
+/**
+ * Decide whether a merge should take a backup of `path` right now: only if
+ * it hasn't already been backed up earlier in this same install run. Callers
+ * that DO write a backup must call {@link markBackedUp} immediately after.
+ */
+export function shouldBackup(path, alreadyBackedUpPaths) {
+    return !alreadyBackedUpPaths?.has(path);
+}
+/** Record that `path` has now been backed up for the remainder of this install run. */
+export function markBackedUp(path, alreadyBackedUpPaths) {
+    alreadyBackedUpPaths?.add(path);
+}
+/**
+ * Heuristic ownership check shared by every format-specific merge helper:
+ * does an existing entry look like a Skillsmith MCP server registration we
+ * (a prior `sklx agent install` run) wrote, as opposed to a user's own
+ * hand-written `skillsmith`-named entry pointing somewhere else entirely?
+ *
+ * There is no injected marker field in the entry value itself (that would
+ * pollute a config another tool's strict-schema client might read) — instead
+ * this checks for the structural fingerprint our own entries always carry,
+ * across BOTH entry conventions the installer writes:
+ *   - mcpServers convention (claude-code/cursor/copilot/windsurf/hermes):
+ *     an `args` array mentioning `@skillsmith/mcp-server`, or an
+ *     `env.SKILLSMITH_TOOL_PROFILE` key.
+ *   - OpenCode convention (`buildOpenCodeMcpEntryValue`): a `command` ARRAY
+ *     mentioning `@skillsmith/mcp-server`, or an
+ *     `environment.SKILLSMITH_TOOL_PROFILE` key. Without these two checks, a
+ *     re-install after any entry-value change would misclassify our own
+ *     prior OpenCode entry as foreign and refuse to update it.
+ * Any one is a strong, low-false-positive signal.
+ */
+export function looksLikeOurMcpEntry(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    const mentionsOurPackage = (arr) => Array.isArray(arr) &&
+        arr.some((a) => typeof a === 'string' && a.includes('@skillsmith/mcp-server'));
+    if (mentionsOurPackage(v.args))
+        return true;
+    if (mentionsOurPackage(v.command))
+        return true;
+    const hasProfileKey = (obj) => !!obj && typeof obj === 'object' && 'SKILLSMITH_TOOL_PROFILE' in obj;
+    if (hasProfileKey(v.env))
+        return true;
+    if (hasProfileKey(v.environment))
+        return true;
+    return false;
+}
+/** Deep structural equality for plain JSON-shaped values (objects/arrays/primitives). */
+export function deepEqualJson(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqualJson(v, b[i]));
+    }
+    if (typeof a === 'object' && typeof b === 'object') {
+        const aKeys = Object.keys(a).sort();
+        const bKeys = Object.keys(b).sort();
+        if (aKeys.length !== bKeys.length || aKeys.some((k, i) => k !== bKeys[i]))
+            return false;
+        return aKeys.every((k) => deepEqualJson(a[k], b[k]));
+    }
+    return false;
+}
+//# sourceMappingURL=agent-config-merge.types.js.map

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

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

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

@@ -0,0 +1,46 @@
+/**
+ * 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 { type MergeOptions, type MergeResult } from './agent-config-merge.types.js';
+/**
+ * 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 declare function mergeYamlMcpEntry(opts: MergeOptions & {
+    mcpServersKey: string;
+}): MergeResult;
+//# sourceMappingURL=agent-config-merge.yaml.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config-merge.yaml.d.ts","sourceRoot":"","sources":["../../../src/install/agent-config-merge.yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAOH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAA;AAwBtC;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAqE7F"}