@skillsmith/mcp-server 0.4.13 → 0.5.0

package/dist/src/audit/namespace-overrides.js

@@ -0,0 +1,228 @@
+/**
+ * @fileoverview Atomic reader/writer for the namespace-overrides ledger
+ *               (SMI-4588 Wave 2 Step 1, PR #1).
+ * @module @skillsmith/mcp-server/audit/namespace-overrides
+ *
+ * Persists `~/.skillsmith/namespace-overrides.json` — the load-bearing
+ * artifact that makes consumer-side namespace renames durable across pack
+ * version bumps. Conceptually equivalent to git's `rerere` but for
+ * namespace identifiers.
+ *
+ * Atomicity: every write goes through `<path>.tmp` + `fs.rename`. On read,
+ * a missing file degrades gracefully to an empty ledger; malformed JSON
+ * surfaces as a typed `namespace.ledger.malformed` discriminator (the
+ * caller decides whether to log + reset, never silently). A
+ * higher-than-supported `version` returns
+ * `namespace.ledger.version_unsupported` rather than a silent empty
+ * ledger — see plan §2 Edit 6.
+ *
+ * Concurrent-write boundary: last-write-wins on a single Node event loop
+ * via `<path>.tmp` + `fs.rename`. Multi-process scenarios (two MCP
+ * instances on the same machine) can lose one write under a tight race;
+ * documented as a known limitation in the plan. If multi-process safety
+ * becomes load-bearing, a future revision adds advisory locking via
+ * `proper-lockfile`.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { ulid } from 'ulid';
+import { CURRENT_VERSION, } from './namespace-overrides.types.js';
+/**
+ * Default ledger path resolver. Re-evaluates `os.homedir()` on every call so
+ * test harnesses that toggle `process.env.HOME` (mirroring `getBackupsDir`'s
+ * pattern in `tools/install.conflict-helpers.ts`) see the updated location.
+ * A captured-at-module-load constant would freeze the path to the spawning
+ * process's home directory and silently route all writes there — observed
+ * regression during PR #2 test authoring (SMI-4588 Wave 2).
+ */
+function defaultLedgerPath() {
+    return path.join(os.homedir(), '.skillsmith', 'namespace-overrides.json');
+}
+const ULID_PREFIX = 'ovr_';
+/**
+ * Empty ledger sentinel — used when the file is missing or malformed.
+ * Returned by value so callers never share state with a private const.
+ */
+function emptyLedger() {
+    return { version: CURRENT_VERSION, overrides: [] };
+}
+/**
+ * Read the ledger from disk and return a tagged union. Missing file →
+ * `{ kind: 'ok', ledger: <empty> }`. Malformed JSON →
+ * `{ kind: 'namespace.ledger.malformed', reason }`. `version > CURRENT_VERSION`
+ * → `{ kind: 'namespace.ledger.version_unsupported', found, expected }`.
+ *
+ * Callers that want the simpler "read or empty" semantics should use
+ * `readLedger()` (below) which collapses the discriminator.
+ */
+export async function readLedgerResult(opts = {}) {
+    const ledgerPath = opts.ledgerPath ?? defaultLedgerPath();
+    let raw;
+    try {
+        raw = await fs.readFile(ledgerPath, 'utf-8');
+    }
+    catch (err) {
+        // ENOENT — missing file degrades to an empty ledger. Anything else
+        // (permission denied, EISDIR, etc.) bubbles as malformed so the
+        // caller can decide whether to alert.
+        if (err.code === 'ENOENT') {
+            return { kind: 'ok', ledger: emptyLedger() };
+        }
+        return {
+            kind: 'namespace.ledger.malformed',
+            reason: `read failed: ${err.message}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            kind: 'namespace.ledger.malformed',
+            reason: `parse failed: ${err.message}`,
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return { kind: 'namespace.ledger.malformed', reason: 'top-level is not an object' };
+    }
+    const candidate = parsed;
+    const versionValue = candidate.version;
+    if (typeof versionValue !== 'number' || !Number.isInteger(versionValue) || versionValue < 1) {
+        return {
+            kind: 'namespace.ledger.malformed',
+            reason: `invalid version: ${String(versionValue)}`,
+        };
+    }
+    if (versionValue > CURRENT_VERSION) {
+        return {
+            kind: 'namespace.ledger.version_unsupported',
+            found: versionValue,
+            expected: CURRENT_VERSION,
+        };
+    }
+    if (!Array.isArray(candidate.overrides)) {
+        return { kind: 'namespace.ledger.malformed', reason: 'overrides is not an array' };
+    }
+    // Shape verified; cast back to the canonical type. Per-record validation
+    // is intentionally minimal — additive future fields are preserved by the
+    // writer's read-modify-write cycle.
+    return {
+        kind: 'ok',
+        ledger: { version: CURRENT_VERSION, overrides: candidate.overrides },
+    };
+}
+/**
+ * Convenience wrapper: returns the ledger directly, collapsing the
+ * `malformed` branch to an empty ledger plus a `console.warn`. Higher-
+ * version files still bubble a thrown error — silently empty-ing a
+ * higher-version ledger would corrupt forward-compat (plan §2 Edit 6).
+ *
+ * For callers that need the typed discriminator, use `readLedgerResult`.
+ */
+export async function readLedger(opts = {}) {
+    const result = await readLedgerResult(opts);
+    switch (result.kind) {
+        case 'ok':
+            return result.ledger;
+        case 'namespace.ledger.malformed':
+            // Malformed → degrade to empty + warn. Install must not break.
+            console.warn(`[namespace-overrides] ledger malformed (${result.reason}); using empty ledger`);
+            return emptyLedger();
+        case 'namespace.ledger.version_unsupported': {
+            // Higher-version file: bubble as a typed error — silently empty-ing
+            // would shadow the user's persisted renames on a downgrade.
+            const err = new Error(`namespace-overrides ledger version ${String(result.found)} is newer than supported version ${String(result.expected)}`);
+            err.kind = result.kind;
+            err.found = result.found;
+            err.expected = result.expected;
+            throw err;
+        }
+        default: {
+            // Exhaustiveness — TS verifies via `never`.
+            const _exhaustive = result;
+            throw new Error(`unreachable: ${String(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Write the ledger atomically: `<path>.tmp` + `fs.rename`. Creates the
+ * parent directory on first run with `recursive: true` (mirrors
+ * audit-history.ts E-MISS-2 fix).
+ */
+export async function writeLedger(ledger, opts = {}) {
+    const ledgerPath = opts.ledgerPath ?? defaultLedgerPath();
+    // Per-call unique tmp path: two concurrent writers must not clobber
+    // each other's staging file (a fixed `<path>.tmp` would race on the
+    // writeFile + rename interleaving and surface as ENOENT on rename).
+    // The unique suffix preserves last-write-wins on the rename target
+    // while making the staging step independent.
+    const tmpSuffix = crypto.randomBytes(6).toString('hex');
+    const tmpPath = `${ledgerPath}.${tmpSuffix}.tmp`;
+    await fs.mkdir(path.dirname(ledgerPath), { recursive: true });
+    // Always serialize at CURRENT_VERSION; readers gate on it.
+    const normalized = { version: CURRENT_VERSION, overrides: ledger.overrides };
+    const json = JSON.stringify(normalized, null, 2);
+    try {
+        await fs.writeFile(tmpPath, json, 'utf-8');
+        await fs.rename(tmpPath, ledgerPath);
+    }
+    catch (err) {
+        // Best-effort cleanup of stranded tmp file. ENOENT here is fine —
+        // the rename may have already moved the tmp out from under us.
+        try {
+            await fs.rm(tmpPath, { force: true });
+        }
+        catch {
+            // swallow
+        }
+        throw err;
+    }
+}
+/**
+ * Pure helper: append a new override to a ledger and return a new copy.
+ * Original ledger is not mutated. The caller is responsible for
+ * persisting the result via `writeLedger` (separation of concerns —
+ * tests can build ledgers without touching disk).
+ *
+ * Idempotency: if an override with the same
+ * `(skillId, kind, originalIdentifier, renamedTo)` quadruple already
+ * exists, the input is returned unchanged. The caller can detect the
+ * no-op by reference equality (`appended === ledger`).
+ */
+export function appendOverride(ledger, override) {
+    const duplicate = ledger.overrides.find((existing) => existing.skillId === override.skillId &&
+        existing.kind === override.kind &&
+        existing.originalIdentifier === override.originalIdentifier &&
+        existing.renamedTo === override.renamedTo);
+    if (duplicate) {
+        return ledger;
+    }
+    const fullRecord = {
+        ...override,
+        id: `${ULID_PREFIX}${ulid()}`,
+        appliedAt: new Date().toISOString(),
+    };
+    return { version: ledger.version, overrides: [...ledger.overrides, fullRecord] };
+}
+/**
+ * Pure lookup: find an override by `(skillId, kind, originalIdentifier)`.
+ * `skillId` may be omitted for local/unregistered artifacts; in that case
+ * only `kind` + `originalIdentifier` are matched. Returns the first match
+ * or `null`.
+ */
+export function findOverride(ledger, query) {
+    const match = ledger.overrides.find((entry) => {
+        if (entry.originalIdentifier !== query.originalIdentifier)
+            return false;
+        if (query.kind !== undefined && entry.kind !== query.kind)
+            return false;
+        if (query.skillId !== undefined && entry.skillId !== query.skillId)
+            return false;
+        return true;
+    });
+    return match ?? null;
+}
+//# sourceMappingURL=namespace-overrides.js.map

package/dist/src/audit/namespace-overrides.js.map

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

package/dist/src/audit/namespace-overrides.types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Type vocabulary for the namespace-overrides ledger
+ *               (SMI-4588 Wave 2 Step 1, PR #1).
+ * @module @skillsmith/mcp-server/audit/namespace-overrides.types
+ *
+ * Schema for `~/.skillsmith/namespace-overrides.json`. Modeled on the
+ * dependency-intelligence persistence pattern (SMI-3137). The schema is
+ * versioned; `CURRENT_VERSION` is bumped only when the on-disk shape
+ * changes incompatibly. Reader/writer live in `./namespace-overrides.ts`.
+ *
+ * Plan: docs/internal/implementation/smi-4588-rename-engine-ledger-install.md §2.
+ */
+import type { InventoryKind } from '../utils/local-inventory.types.js';
+/**
+ * Current ledger schema version. Bumped only when the on-disk shape
+ * changes incompatibly. Read-path behavior:
+ *
+ * - `version === CURRENT_VERSION` → return as-is.
+ * - `version < CURRENT_VERSION` → caller may run a `migrateLedger` shim
+ *   (currently no historical versions exist, so any value below 1 is
+ *   unreachable in practice).
+ * - `version > CURRENT_VERSION` → reader returns a typed
+ *   `namespace.ledger.version_unsupported` error rather than silently
+ *   degrading to an empty ledger (plan §2 Edit 6).
+ */
+export declare const CURRENT_VERSION: 1;
+export type LedgerVersion = typeof CURRENT_VERSION;
+/**
+ * One applied rename. Persisted in `~/.skillsmith/namespace-overrides.json`
+ * under `overrides[]`. ULID `id` lets later operations (revert, replay,
+ * forensics) reference the entry without depending on `(skillId, kind,
+ * originalIdentifier)` triple equality.
+ */
+export interface OverrideRecord {
+    /** ULID prefixed with `ovr_` for log-grep readability. */
+    id: string;
+    /**
+     * Skillsmith manifest skill id (`<author>/<name>`) when the renamed
+     * artifact is a registered skill, else `null` for local/unregistered
+     * commands and agents.
+     */
+    skillId: string | null;
+    /**
+     * Which inventory kind this override applies to. Mirrors
+     * `InventoryKind` from local-inventory so a single ledger covers skills,
+     * commands, agents, and CLAUDE.md rules (the last for future use; Wave 2
+     * does not write claude_md_rule entries).
+     */
+    kind: InventoryKind;
+    /**
+     * The original triggering identifier — e.g. `/ship` for a command,
+     * `code-review` for a skill name. This is the field the install-time
+     * ledger replay matches against when deciding whether to re-apply a
+     * rename.
+     */
+    originalIdentifier: string;
+    /**
+     * The chosen renamed identifier — e.g. `/anthropic-ship`,
+     * `anthropic-code-review`.
+     */
+    renamedTo: string;
+    /** Absolute path to the original on-disk artifact at apply time. */
+    originalPath: string;
+    /** Absolute path to the renamed on-disk artifact post-apply. */
+    renamedPath: string;
+    /** ISO-8601 timestamp recorded by the writer (UTC). */
+    appliedAt: string;
+    /**
+     * FK to `~/.skillsmith/audits/<auditId>/result.json`. Lets a forensic
+     * lookup re-derive the original collision context.
+     */
+    auditId: string;
+    /**
+     * Human-readable reason — e.g.
+     * `"collision with skillsmith/release-tools /ship"`. Surfaced verbatim
+     * in the audit-report writer (Wave 2 PR #4 extension).
+     */
+    reason: string;
+}
+/**
+ * On-disk shape of `~/.skillsmith/namespace-overrides.json`.
+ *
+ * `version` is required and validated on read. Unknown future fields are
+ * preserved on read-modify-write at the writer layer (additive
+ * extensions don't break older clients), but any `version` strictly
+ * greater than `CURRENT_VERSION` triggers a typed error per plan §2.
+ */
+export interface OverridesLedger {
+    version: LedgerVersion;
+    overrides: OverrideRecord[];
+}
+/**
+ * Typed error returned by `readLedger` when the on-disk file declares a
+ * higher version than this client understands. The reader does NOT throw
+ * — it returns this discriminator so callers can decide whether to abort
+ * or fall back. Plan §2 Edit 6.
+ */
+export interface LedgerVersionUnsupportedError {
+    kind: 'namespace.ledger.version_unsupported';
+    found: number;
+    expected: LedgerVersion;
+}
+/**
+ * Discriminated union returned by `readLedger`. The success branch is the
+ * ledger; the error branches are typed so callers `switch` on `kind` and
+ * never silently absorb a higher-version file as empty.
+ */
+export type ReadLedgerResult = {
+    kind: 'ok';
+    ledger: OverridesLedger;
+} | LedgerVersionUnsupportedError | {
+    kind: 'namespace.ledger.malformed';
+    reason: string;
+};
+//# sourceMappingURL=namespace-overrides.types.d.ts.map

package/dist/src/audit/namespace-overrides.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace-overrides.types.d.ts","sourceRoot":"","sources":["../../../src/audit/namespace-overrides.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAA;AAEtE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,EAAG,CAAU,CAAA;AAEzC,MAAM,MAAM,aAAa,GAAG,OAAO,eAAe,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;;;;OAKG;IACH,IAAI,EAAE,aAAa,CAAA;IACnB;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,CAAA;IACtB,SAAS,EAAE,cAAc,EAAE,CAAA;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,sCAAsC,CAAA;IAC5C,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,aAAa,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACvC,6BAA6B,GAC7B;IAAE,IAAI,EAAE,4BAA4B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA"}

package/dist/src/audit/namespace-overrides.types.js

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Type vocabulary for the namespace-overrides ledger
+ *               (SMI-4588 Wave 2 Step 1, PR #1).
+ * @module @skillsmith/mcp-server/audit/namespace-overrides.types
+ *
+ * Schema for `~/.skillsmith/namespace-overrides.json`. Modeled on the
+ * dependency-intelligence persistence pattern (SMI-3137). The schema is
+ * versioned; `CURRENT_VERSION` is bumped only when the on-disk shape
+ * changes incompatibly. Reader/writer live in `./namespace-overrides.ts`.
+ *
+ * Plan: docs/internal/implementation/smi-4588-rename-engine-ledger-install.md §2.
+ */
+/**
+ * Current ledger schema version. Bumped only when the on-disk shape
+ * changes incompatibly. Read-path behavior:
+ *
+ * - `version === CURRENT_VERSION` → return as-is.
+ * - `version < CURRENT_VERSION` → caller may run a `migrateLedger` shim
+ *   (currently no historical versions exist, so any value below 1 is
+ *   unreachable in practice).
+ * - `version > CURRENT_VERSION` → reader returns a typed
+ *   `namespace.ledger.version_unsupported` error rather than silently
+ *   degrading to an empty ledger (plan §2 Edit 6).
+ */
+export const CURRENT_VERSION = 1;
+//# sourceMappingURL=namespace-overrides.types.js.map

package/dist/src/audit/namespace-overrides.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace-overrides.types.js","sourceRoot":"","sources":["../../../src/audit/namespace-overrides.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAU,CAAA"}

package/dist/src/audit/rename-engine.apply-paths.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Apply-path helpers for the rename engine
+ *               (SMI-4588 Wave 2 Step 4, PR #2).
+ * @module @skillsmith/mcp-server/audit/rename-engine.apply-paths
+ *
+ * Path computation, backup orchestration, and summary formatting helpers
+ * extracted from `rename-engine.ts` to keep the main file <500 LOC per
+ * CLAUDE.md file-size enforcement (Edit 4 / SMI-1865 governance).
+ *
+ * **No backup writer here either** — the canonical `createSkillBackup`
+ * lives in `tools/install.conflict-helpers.ts`; this file orchestrates
+ * single-file staging so that helper can copy a directory worth of one
+ * file. Plan §1 Edit 4 still applies.
+ */
+import type { OverrideRecord } from './namespace-overrides.types.js';
+import type { RenameAction, RenameError, RenameSuggestion } from './rename-engine.types.js';
+/**
+ * Map a `RenameAction` to the `OverrideRecord.kind` field. `command` /
+ * `agent` are 1:1; `rename_skill_dir_and_frontmatter` maps to `skill`.
+ */
+export declare function actionToKind(action: RenameAction): OverrideRecord['kind'];
+/**
+ * Compute the destination path on disk for a rename. For command/agent
+ * files, swap the basename (sans `.md`) with `newName.md`. For skill
+ * directories, rename the directory itself.
+ */
+export declare function computeDestPath(suggestion: RenameSuggestion, newName: string): string;
+/**
+ * `entry.meta?.author` may carry a slug like `anthropic` or a Skillsmith
+ * manifest skillId like `anthropic/code-helper`. The latter is what the
+ * ledger persists as `skillId`; the former is `null`. Heuristic: contains
+ * `/` ⇒ skillId.
+ */
+export declare function deriveSkillId(suggestion: RenameSuggestion): string | null;
+export declare function fsErr(reason: string): RenameError;
+export declare function pathExists(target: string): Promise<boolean>;
+/**
+ * Run a backup before any on-disk mutation. Returns the backup directory
+ * path on success; throws on failure. The error path is wrapped in a
+ * typed `RenameError` by the caller.
+ *
+ * Backup naming: `<getBackupsDir()>/<skillName>/<timestamp>_namespace-rename/`
+ * via the canonical helper (plan §1 Edit 4).
+ */
+export declare function runBackup(suggestion: RenameSuggestion): Promise<string>;
+/**
+ * Build the inline revert summary (decision #10):
+ *   `"Renamed /<OLD> → /<NEW>. To undo: sklx audit revert <auditId>"`
+ *
+ * For skill renames (no leading `/`), the summary still uses the `/`
+ * prefix per the plan's literal text — agents render it as-is.
+ */
+export declare function buildSummary(oldIdentifier: string, newIdentifier: string, auditId: string, action: 'apply' | 'revert'): string;
+//# sourceMappingURL=rename-engine.apply-paths.d.ts.map

package/dist/src/audit/rename-engine.apply-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rename-engine.apply-paths.d.ts","sourceRoot":"","sources":["../../../src/audit/rename-engine.apply-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAE3F;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAAC,MAAM,CAAC,CASzE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMrF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAIzE;AAED,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAMjD;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQjE;AAaD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB7E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,GAAG,QAAQ,GACzB,MAAM,CAKR"}

package/dist/src/audit/rename-engine.apply-paths.js

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Apply-path helpers for the rename engine
+ *               (SMI-4588 Wave 2 Step 4, PR #2).
+ * @module @skillsmith/mcp-server/audit/rename-engine.apply-paths
+ *
+ * Path computation, backup orchestration, and summary formatting helpers
+ * extracted from `rename-engine.ts` to keep the main file <500 LOC per
+ * CLAUDE.md file-size enforcement (Edit 4 / SMI-1865 governance).
+ *
+ * **No backup writer here either** — the canonical `createSkillBackup`
+ * lives in `tools/install.conflict-helpers.ts`; this file orchestrates
+ * single-file staging so that helper can copy a directory worth of one
+ * file. Plan §1 Edit 4 still applies.
+ */
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createSkillBackup } from '../tools/install.conflict-helpers.js';
+/**
+ * Map a `RenameAction` to the `OverrideRecord.kind` field. `command` /
+ * `agent` are 1:1; `rename_skill_dir_and_frontmatter` maps to `skill`.
+ */
+export function actionToKind(action) {
+    switch (action) {
+        case 'rename_command_file':
+            return 'command';
+        case 'rename_agent_file':
+            return 'agent';
+        case 'rename_skill_dir_and_frontmatter':
+            return 'skill';
+    }
+}
+/**
+ * Compute the destination path on disk for a rename. For command/agent
+ * files, swap the basename (sans `.md`) with `newName.md`. For skill
+ * directories, rename the directory itself.
+ */
+export function computeDestPath(suggestion, newName) {
+    const src = suggestion.entry.source_path;
+    if (suggestion.applyAction === 'rename_skill_dir_and_frontmatter') {
+        return path.join(path.dirname(src), newName);
+    }
+    return path.join(path.dirname(src), `${newName}.md`);
+}
+/**
+ * `entry.meta?.author` may carry a slug like `anthropic` or a Skillsmith
+ * manifest skillId like `anthropic/code-helper`. The latter is what the
+ * ledger persists as `skillId`; the former is `null`. Heuristic: contains
+ * `/` ⇒ skillId.
+ */
+export function deriveSkillId(suggestion) {
+    const author = suggestion.entry.meta?.author;
+    if (typeof author !== 'string' || author.length === 0)
+        return null;
+    return author.includes('/') ? author : null;
+}
+export function fsErr(reason) {
+    return {
+        kind: 'namespace.rename.fs_error',
+        reason,
+        message: `filesystem error during rename: ${reason}`,
+    };
+}
+export async function pathExists(target) {
+    try {
+        await fs.stat(target);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+/**
+ * Stage a single command/agent file under a tmp directory so
+ * `createSkillBackup` (which copies a directory) backs up only that file.
+ * Returns the tmp-dir path; the caller removes it after the helper runs.
+ */
+async function stageSingleFileForBackup(srcFile) {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'skillsmith-rename-stage-'));
+    await fs.copyFile(srcFile, path.join(tmp, path.basename(srcFile)));
+    return tmp;
+}
+/**
+ * Run a backup before any on-disk mutation. Returns the backup directory
+ * path on success; throws on failure. The error path is wrapped in a
+ * typed `RenameError` by the caller.
+ *
+ * Backup naming: `<getBackupsDir()>/<skillName>/<timestamp>_namespace-rename/`
+ * via the canonical helper (plan §1 Edit 4).
+ */
+export async function runBackup(suggestion) {
+    const skillName = path.basename(suggestion.entry.source_path).replace(/\.md$/, '');
+    const action = suggestion.applyAction;
+    if (action === 'rename_skill_dir_and_frontmatter') {
+        return createSkillBackup(skillName, suggestion.entry.source_path, 'namespace-rename');
+    }
+    // Single-file path — stage, back up the staged dir, clean up.
+    const staged = await stageSingleFileForBackup(suggestion.entry.source_path);
+    try {
+        return await createSkillBackup(skillName, staged, 'namespace-rename');
+    }
+    finally {
+        try {
+            await fs.rm(staged, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort
+        }
+    }
+}
+/**
+ * Build the inline revert summary (decision #10):
+ *   `"Renamed /<OLD> → /<NEW>. To undo: sklx audit revert <auditId>"`
+ *
+ * For skill renames (no leading `/`), the summary still uses the `/`
+ * prefix per the plan's literal text — agents render it as-is.
+ */
+export function buildSummary(oldIdentifier, newIdentifier, auditId, action) {
+    if (action === 'revert') {
+        return `Reverted /${oldIdentifier} → /${newIdentifier}. Audit: ${auditId}`;
+    }
+    return `Renamed /${oldIdentifier} → /${newIdentifier}. To undo: sklx audit revert ${auditId}`;
+}
+//# sourceMappingURL=rename-engine.apply-paths.js.map

package/dist/src/audit/rename-engine.apply-paths.js.map

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

package/dist/src/audit/rename-engine.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Rename engine — applies confirmed namespace renames
+ *               (SMI-4588 Wave 2 Step 4, PR #2).
+ * @module @skillsmith/mcp-server/audit/rename-engine
+ *
+ * Three apply paths, gated on `RenameAction`:
+ *
+ * - `rename_command_file` — `~/.claude/commands/foo.md` → `<author>-foo.md`
+ * - `rename_agent_file` — `~/.claude/agents/foo.md` → `<author>-foo.md`
+ * - `rename_skill_dir_and_frontmatter` — rename the directory AND rewrite
+ *   the SKILL.md `name:` frontmatter field.
+ *
+ * Plus `action: 'revert'` semantics: looks up the ledger entry by
+ * `auditId`, performs the inverse rename (back to `originalIdentifier`),
+ * removes the ledger entry, and restores the SKILL.md frontmatter.
+ *
+ * Backups are owned by the canonical `createSkillBackup` helper at
+ * `tools/install.conflict-helpers.ts:87` (plan §1 Edit 4). Single-file
+ * renames stage the file under a tmp directory so the helper (which
+ * expects a source dir) backs up only the relevant file. Backups land in
+ * `~/.claude/skills/.backups/<name>/<timestamp>_namespace-rename/`.
+ *
+ * Idempotency: before mutating, the engine consults the namespace-overrides
+ * ledger. When the same `(skillId, originalIdentifier)` pair is already
+ * in the ledger AND the on-disk filename matches the recorded
+ * `renamedTo`, the call is a no-op (returns success with
+ * `fromPath === toPath` and `backupPath === ''`).
+ *
+ * Disk-vs-ledger divergence: when the ledger has an entry but the on-disk
+ * filename does NOT match `renamedTo`, the engine returns
+ * `namespace.ledger.disk_divergence` rather than silently re-applying.
+ *
+ * Plan: docs/internal/implementation/smi-4588-rename-engine-ledger-install.md §1.
+ */
+import { getBackupsDir } from '../tools/install.conflict-helpers.js';
+import type { ApplyRenameRequest, ApplyRenameResult } from './rename-engine.types.js';
+export { generateSuggestionChain } from './suggestion-chain.js';
+/**
+ * Public summary prefix used by the agent / CLI to detect inline revert
+ * messages. Matches plan §1 decision #10 verbatim.
+ */
+export declare const REVERT_SUMMARY_PREFIX = "Renamed";
+/**
+ * Apply (or revert) a rename. Single entrypoint for Wave 4's MCP tool.
+ * Each apply path runs: idempotency check → backup → mutate → ledger
+ * append → result. Revert: ledger lookup → inverse rename → ledger
+ * remove → result.
+ *
+ * Idempotency contract: re-applying the same suggestion when the ledger
+ * already records it AND on-disk state matches → returns success with
+ * `fromPath === toPath` and `backupPath === ''` (no second backup).
+ *
+ * Disk-vs-ledger divergence: ledger entry exists but on-disk path does
+ * NOT match `renamedTo` → `namespace.ledger.disk_divergence` error;
+ * caller decides whether to `customName` over the divergence.
+ */
+export declare function applyRename(input: ApplyRenameRequest): Promise<ApplyRenameResult>;
+export { getBackupsDir };
+//# sourceMappingURL=rename-engine.d.ts.map

package/dist/src/audit/rename-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rename-engine.d.ts","sourceRoot":"","sources":["../../../src/audit/rename-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAKH,OAAO,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAA;AAYpE,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAE/D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,YAAY,CAAA;AAE9C;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0MvF;AAiJD,OAAO,EAAE,aAAa,EAAE,CAAA"}