@skillsmith/mcp-server 0.4.12 → 0.5.0

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

@@ -0,0 +1,393 @@
+/**
+ * @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 * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { getBackupsDir } from '../tools/install.conflict-helpers.js';
+import { appendOverride, findOverride, readLedger, writeLedger } from './namespace-overrides.js';
+import { actionToKind, buildSummary, computeDestPath, deriveSkillId, fsErr, pathExists, runBackup, } from './rename-engine.apply-paths.js';
+import { rewriteFrontmatterName } from './rename-engine.helpers.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 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 async function applyRename(input) {
+    const { suggestion, request } = input;
+    const auditId = request.auditId;
+    if (request.action === 'revert') {
+        return revertRename(suggestion, auditId);
+    }
+    const newName = request.customName ?? suggestion.suggested;
+    const skillId = deriveSkillId(suggestion);
+    const action = suggestion.applyAction;
+    const kind = actionToKind(action);
+    const ledger = await readLedger();
+    // Idempotency / divergence check: do we already have a ledger entry for
+    // this `(skillId, kind, originalIdentifier)`?
+    const existing = findOverride(ledger, {
+        skillId,
+        kind,
+        originalIdentifier: suggestion.currentName,
+    });
+    if (existing) {
+        const onDiskMatches = await pathExists(existing.renamedPath);
+        if (onDiskMatches) {
+            // Idempotent no-op. Return success without touching disk or ledger.
+            return {
+                success: true,
+                collisionId: suggestion.collisionId,
+                appliedAction: action,
+                appliedRequest: 'apply',
+                fromPath: existing.renamedPath,
+                toPath: existing.renamedPath,
+                backupPath: '',
+                ledgerEntryId: existing.id,
+                summary: buildSummary(suggestion.currentName, existing.renamedTo, auditId, 'apply'),
+            };
+        }
+        // Divergence — ledger says renamedTo, but it's not on disk. Refuse.
+        return {
+            success: false,
+            collisionId: suggestion.collisionId,
+            appliedAction: action,
+            appliedRequest: 'apply',
+            fromPath: suggestion.entry.source_path,
+            toPath: '',
+            backupPath: '',
+            ledgerEntryId: '',
+            summary: '',
+            error: {
+                kind: 'namespace.ledger.disk_divergence',
+                ledgerRenamedTo: existing.renamedTo,
+                onDisk: suggestion.entry.source_path,
+                message: `ledger records rename to ${existing.renamedTo} but no file at ${existing.renamedPath}`,
+                remediationHint: 're-run skill_inventory_audit and reapply, or call apply_namespace_rename with customName to overwrite the ledger entry',
+            },
+        };
+    }
+    // Compute destination + verify it doesn't already exist (other than as
+    // the source for an idempotent no-op handled above).
+    const destPath = computeDestPath(suggestion, newName);
+    if (destPath !== suggestion.entry.source_path && (await pathExists(destPath))) {
+        return {
+            success: false,
+            collisionId: suggestion.collisionId,
+            appliedAction: action,
+            appliedRequest: 'apply',
+            fromPath: suggestion.entry.source_path,
+            toPath: destPath,
+            backupPath: '',
+            ledgerEntryId: '',
+            summary: '',
+            error: {
+                kind: 'namespace.rename.target_exists',
+                target: destPath,
+                message: `rename target already exists: ${destPath}`,
+            },
+        };
+    }
+    // Backup before any mutation.
+    let backupPath;
+    try {
+        backupPath = await runBackup(suggestion);
+    }
+    catch (err) {
+        return {
+            success: false,
+            collisionId: suggestion.collisionId,
+            appliedAction: action,
+            appliedRequest: 'apply',
+            fromPath: suggestion.entry.source_path,
+            toPath: destPath,
+            backupPath: '',
+            ledgerEntryId: '',
+            summary: '',
+            error: {
+                kind: 'namespace.rename.backup_failed',
+                reason: err.message,
+                message: `backup failed: ${err.message}`,
+            },
+        };
+    }
+    // Mutate. For skill dirs: rewrite SKILL.md frontmatter, then rename the
+    // directory. For command/agent: just rename.
+    try {
+        if (action === 'rename_skill_dir_and_frontmatter') {
+            const skillMdPath = path.join(suggestion.entry.source_path, 'SKILL.md');
+            let original;
+            try {
+                original = await fs.readFile(skillMdPath, 'utf-8');
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    collisionId: suggestion.collisionId,
+                    appliedAction: action,
+                    appliedRequest: 'apply',
+                    fromPath: suggestion.entry.source_path,
+                    toPath: destPath,
+                    backupPath,
+                    ledgerEntryId: '',
+                    summary: '',
+                    error: fsErr(`reading SKILL.md: ${err.message}`),
+                };
+            }
+            const rewriteResult = rewriteFrontmatterName(original, newName);
+            if (!rewriteResult.ok) {
+                return {
+                    success: false,
+                    collisionId: suggestion.collisionId,
+                    appliedAction: action,
+                    appliedRequest: 'apply',
+                    fromPath: suggestion.entry.source_path,
+                    toPath: destPath,
+                    backupPath,
+                    ledgerEntryId: '',
+                    summary: '',
+                    error: {
+                        kind: 'namespace.rename.frontmatter_rewrite_failed',
+                        reason: rewriteResult.error.message,
+                        message: `frontmatter rewrite failed: ${rewriteResult.error.message}`,
+                    },
+                };
+            }
+            await fs.writeFile(skillMdPath, rewriteResult.content, 'utf-8');
+            await fs.rename(suggestion.entry.source_path, destPath);
+        }
+        else {
+            await fs.rename(suggestion.entry.source_path, destPath);
+        }
+    }
+    catch (err) {
+        return {
+            success: false,
+            collisionId: suggestion.collisionId,
+            appliedAction: action,
+            appliedRequest: 'apply',
+            fromPath: suggestion.entry.source_path,
+            toPath: destPath,
+            backupPath,
+            ledgerEntryId: '',
+            summary: '',
+            error: fsErr(err.message),
+        };
+    }
+    // Append ledger entry + persist.
+    const updated = appendOverride(ledger, {
+        skillId,
+        kind,
+        originalIdentifier: suggestion.currentName,
+        renamedTo: newName,
+        originalPath: suggestion.entry.source_path,
+        renamedPath: destPath,
+        auditId,
+        reason: suggestion.reason,
+    });
+    // `appendOverride` returns reference-equal ledger when a duplicate
+    // exists. Fresh appends produce a non-equal copy. Either way, persist
+    // the updated state.
+    if (updated !== ledger) {
+        await writeLedger(updated);
+    }
+    const newEntry = updated === ledger
+        ? findOverride(updated, {
+            skillId,
+            kind,
+            originalIdentifier: suggestion.currentName,
+        })
+        : updated.overrides[updated.overrides.length - 1];
+    return {
+        success: true,
+        collisionId: suggestion.collisionId,
+        appliedAction: action,
+        appliedRequest: 'apply',
+        fromPath: suggestion.entry.source_path,
+        toPath: destPath,
+        backupPath,
+        ledgerEntryId: newEntry?.id ?? '',
+        summary: buildSummary(suggestion.currentName, newName, auditId, 'apply'),
+    };
+}
+/**
+ * Inverse of `applyRename`. Looks up the ledger entry by `auditId`,
+ * renames the file back to `originalIdentifier`, and removes the ledger
+ * entry. Backup is kept for forensics until the 30-day GC sweep.
+ *
+ * Idempotency: calling revert twice on the same `auditId` returns success
+ * with `fromPath === toPath` on the second call (the entry is gone, so
+ * we treat it as a no-op success).
+ */
+async function revertRename(suggestion, auditId) {
+    const ledger = await readLedger();
+    const entry = ledger.overrides.find((o) => o.auditId === auditId);
+    if (!entry) {
+        // Idempotent no-op — already reverted.
+        return {
+            success: true,
+            collisionId: suggestion.collisionId,
+            appliedAction: suggestion.applyAction,
+            appliedRequest: 'revert',
+            fromPath: suggestion.entry.source_path,
+            toPath: suggestion.entry.source_path,
+            backupPath: '',
+            ledgerEntryId: '',
+            summary: buildSummary(suggestion.currentName, suggestion.currentName, auditId, 'revert'),
+        };
+    }
+    const action = suggestion.applyAction;
+    const onDisk = entry.renamedPath;
+    const target = entry.originalPath;
+    if (!(await pathExists(onDisk))) {
+        return {
+            success: false,
+            collisionId: suggestion.collisionId,
+            appliedAction: action,
+            appliedRequest: 'revert',
+            fromPath: onDisk,
+            toPath: target,
+            backupPath: '',
+            ledgerEntryId: entry.id,
+            summary: '',
+            error: {
+                kind: 'namespace.ledger.disk_divergence',
+                ledgerRenamedTo: entry.renamedTo,
+                onDisk,
+                message: `revert source missing on disk: ${onDisk}`,
+                remediationHint: 'restore from ~/.claude/skills/.backups or remove the ledger entry manually',
+            },
+        };
+    }
+    if (target !== onDisk && (await pathExists(target))) {
+        return {
+            success: false,
+            collisionId: suggestion.collisionId,
+            appliedAction: action,
+            appliedRequest: 'revert',
+            fromPath: onDisk,
+            toPath: target,
+            backupPath: '',
+            ledgerEntryId: entry.id,
+            summary: '',
+            error: {
+                kind: 'namespace.rename.target_exists',
+                target,
+                message: `revert target already exists: ${target}`,
+            },
+        };
+    }
+    // Inverse rename. For skills, also restore the SKILL.md frontmatter
+    // `name:` field to the original identifier. Backup is kept (forensics);
+    // no fresh backup is taken on revert — the apply backup covers this case.
+    try {
+        if (action === 'rename_skill_dir_and_frontmatter') {
+            const skillMdPath = path.join(onDisk, 'SKILL.md');
+            const current = await fs.readFile(skillMdPath, 'utf-8');
+            const restored = rewriteFrontmatterName(current, entry.originalIdentifier);
+            if (!restored.ok) {
+                return {
+                    success: false,
+                    collisionId: suggestion.collisionId,
+                    appliedAction: action,
+                    appliedRequest: 'revert',
+                    fromPath: onDisk,
+                    toPath: target,
+                    backupPath: '',
+                    ledgerEntryId: entry.id,
+                    summary: '',
+                    error: {
+                        kind: 'namespace.rename.frontmatter_rewrite_failed',
+                        reason: restored.error.message,
+                        message: `revert frontmatter rewrite failed: ${restored.error.message}`,
+                    },
+                };
+            }
+            await fs.writeFile(skillMdPath, restored.content, 'utf-8');
+            await fs.rename(onDisk, target);
+        }
+        else {
+            await fs.rename(onDisk, target);
+        }
+    }
+    catch (err) {
+        return {
+            success: false,
+            collisionId: suggestion.collisionId,
+            appliedAction: action,
+            appliedRequest: 'revert',
+            fromPath: onDisk,
+            toPath: target,
+            backupPath: '',
+            ledgerEntryId: entry.id,
+            summary: '',
+            error: fsErr(err.message),
+        };
+    }
+    // Remove the ledger entry.
+    const filtered = {
+        version: ledger.version,
+        overrides: ledger.overrides.filter((o) => o.id !== entry.id),
+    };
+    await writeLedger(filtered);
+    return {
+        success: true,
+        collisionId: suggestion.collisionId,
+        appliedAction: action,
+        appliedRequest: 'revert',
+        fromPath: onDisk,
+        toPath: target,
+        backupPath: '',
+        ledgerEntryId: entry.id,
+        summary: buildSummary(entry.renamedTo, entry.originalIdentifier, auditId, 'revert'),
+    };
+}
+// Re-export `getBackupsDir` so downstream tooling (Wave 4) can resolve the
+// backup directory without reaching into `tools/install.conflict-helpers.js`.
+export { getBackupsDir };
+//# sourceMappingURL=rename-engine.js.map

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

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

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

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Type vocabulary for the rename engine
+ *               (SMI-4588 Wave 2 Steps 2-4, PR #2).
+ * @module @skillsmith/mcp-server/audit/rename-engine.types
+ *
+ * Defines the public surface for `generateSuggestionChain`, `applyRename`,
+ * and the `apply | revert` action discriminator. The shapes here are the
+ * canonical replacement for `RenameSuggestionRef` shipped in
+ * `namespace-audit.types.ts` PR #1 — the structural shape is preserved so
+ * the swap-in is a drop-in replacement.
+ *
+ * Plan: docs/internal/implementation/smi-4588-rename-engine-ledger-install.md §1.
+ */
+import type { CollisionId, InventoryEntry } from './collision-detector.types.js';
+/**
+ * Three on-disk apply paths. Each maps to a distinct mutation strategy:
+ *
+ * - `rename_command_file` — `~/.claude/commands/foo.md` → `~/.claude/commands/<author>-foo.md`
+ * - `rename_agent_file` — `~/.claude/agents/foo.md` → `~/.claude/agents/<author>-foo.md`
+ * - `rename_skill_dir_and_frontmatter` — rename the directory AND rewrite the
+ *   `name:` field inside SKILL.md frontmatter.
+ */
+export type RenameAction = 'rename_command_file' | 'rename_agent_file' | 'rename_skill_dir_and_frontmatter';
+/**
+ * One concrete rename suggestion attached to a detected collision. PR #1's
+ * `RenameSuggestionRef` shim in `namespace-audit.types.ts` is structurally
+ * compatible with this shape; PR #2 replaces the shim with this canonical
+ * type.
+ *
+ * Wave 4's `apply_namespace_rename` MCP tool accepts a `RenameSuggestion`
+ * (or a `customName` override) plus an action discriminator and dispatches
+ * to `applyRename`.
+ */
+export interface RenameSuggestion {
+    /** Stable across audit runs — derived via `deriveCollisionId`. */
+    collisionId: CollisionId;
+    /** The inventory entry whose identifier collides. */
+    entry: InventoryEntry;
+    /** Current on-disk identifier (filename without `.md`, or skill name). */
+    currentName: string;
+    /**
+     * First non-colliding candidate from `generateSuggestionChain`. Walking
+     * the chain (and selecting alternatives on collision) is the agent's job;
+     * `suggested` is the chain's first viable rename.
+     */
+    suggested: string;
+    /** Which on-disk mutation strategy applies. */
+    applyAction: RenameAction;
+    /** Human-readable, e.g. `"collision with skillsmith/release-tools /ship"`. */
+    reason: string;
+}
+/**
+ * Action discriminator for `applyRename`. PR #2 ships `apply` + `revert`;
+ * `customName` (caller supplies override) lands in PR #3 alongside the
+ * install-integration plumbing.
+ */
+export type RenameActionRequest = {
+    action: 'apply';
+    auditId: string;
+    customName?: string;
+} | {
+    action: 'revert';
+    auditId: string;
+};
+/**
+ * Top-level apply request. `auditId` is the FK into the audit-history
+ * `~/.skillsmith/audits/<auditId>/result.json` so forensic lookups can
+ * re-derive the original collision context.
+ */
+export interface ApplyRenameRequest {
+    /** Suggestion produced by `generateRenameSuggestions` / chain walk. */
+    suggestion: RenameSuggestion;
+    /** `apply` (forward rename) or `revert` (inverse, by ledger lookup). */
+    request: RenameActionRequest;
+}
+/**
+ * Result of a rename apply (or revert). `success === false` populates
+ * `error` with a typed discriminator; `success === true` populates the
+ * ledger linkage + on-disk paths + the inline revert summary.
+ *
+ * Idempotent re-apply on the same `(skillId, originalIdentifier)` pair is
+ * indicated by `fromPath === toPath` and `backupPath === ''` — callers may
+ * detect a no-op without re-reading the ledger.
+ */
+export interface ApplyRenameResult {
+    success: boolean;
+    collisionId: CollisionId;
+    appliedAction: RenameAction;
+    /** Action that ran — useful when `request.action === 'revert'`. */
+    appliedRequest: RenameActionRequest['action'];
+    /** Pre-mutation absolute path. */
+    fromPath: string;
+    /** Post-mutation absolute path. Equal to `fromPath` for idempotent no-ops. */
+    toPath: string;
+    /**
+     * Backup directory created by `createSkillBackup`. Empty string when the
+     * call was a no-op (idempotent re-apply) — no backup is created in that
+     * case because the on-disk state already matches the ledger.
+     */
+    backupPath: string;
+    /** ULID of the appended ledger entry — `''` for revert (ledger entry removed). */
+    ledgerEntryId: string;
+    /**
+     * Inline revert summary (decision #10). Populated on success; empty
+     * string on failure. Literal text:
+     *
+     *   `"Renamed /<OLD> → /<NEW>. To undo: sklx audit revert <auditId>"`
+     *
+     * The agent surfaces this directly to the user in tool-response output.
+     */
+    summary: string;
+    /** Discriminated error on failure; `undefined` on success. */
+    error?: RenameError;
+}
+/**
+ * Typed errors surfaced by `applyRename`. Discriminated by `kind` so
+ * callers `switch` rather than parsing strings. Plan §1.
+ */
+export type RenameError = {
+    kind: 'namespace.rename.target_exists';
+    target: string;
+    message: string;
+} | {
+    kind: 'namespace.rename.backup_failed';
+    reason: string;
+    message: string;
+} | {
+    kind: 'namespace.rename.frontmatter_rewrite_failed';
+    reason: string;
+    message: string;
+} | {
+    kind: 'namespace.rename.fs_error';
+    reason: string;
+    message: string;
+} | {
+    kind: 'namespace.ledger.disk_divergence';
+    ledgerRenamedTo: string;
+    onDisk: string;
+    message: string;
+    remediationHint: string;
+} | {
+    kind: 'namespace.rename.revert_not_found';
+    auditId: string;
+    message: string;
+};
+/**
+ * Output of `generateSuggestionChain`. Up to 3 ordered candidates; if all
+ * three collide, `exhausted: true` and the agent must escalate to the
+ * human via `customName`.
+ */
+export interface SuggestionChain {
+    /** Up to 3 ordered candidates per decision #11. */
+    candidates: string[];
+    /** `true` when all 3 candidates collide. */
+    exhausted: boolean;
+}
+//# sourceMappingURL=rename-engine.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rename-engine.types.d.ts","sourceRoot":"","sources":["../../../src/audit/rename-engine.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAEhF;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB,qBAAqB,GACrB,mBAAmB,GACnB,kCAAkC,CAAA;AAEtC;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,WAAW,EAAE,WAAW,CAAA;IACxB,qDAAqD;IACrD,KAAK,EAAE,cAAc,CAAA;IACrB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,+CAA+C;IAC/C,WAAW,EAAE,YAAY,CAAA;IACzB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEzC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,UAAU,EAAE,gBAAgB,CAAA;IAC5B,wEAAwE;IACxE,OAAO,EAAE,mBAAmB,CAAA;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,WAAW,CAAA;IACxB,aAAa,EAAE,YAAY,CAAA;IAC3B,mEAAmE;IACnE,cAAc,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IAC7C,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB;IACE,IAAI,EAAE,gCAAgC,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,GACD;IACE,IAAI,EAAE,gCAAgC,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,GACD;IACE,IAAI,EAAE,6CAA6C,CAAA;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,GACD;IACE,IAAI,EAAE,2BAA2B,CAAA;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,GACD;IACE,IAAI,EAAE,kCAAkC,CAAA;IACxC,eAAe,EAAE,MAAM,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,MAAM,CAAA;CACxB,GACD;IACE,IAAI,EAAE,mCAAmC,CAAA;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAEL;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAA;CACnB"}

package/dist/src/audit/rename-engine.types.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Type vocabulary for the rename engine
+ *               (SMI-4588 Wave 2 Steps 2-4, PR #2).
+ * @module @skillsmith/mcp-server/audit/rename-engine.types
+ *
+ * Defines the public surface for `generateSuggestionChain`, `applyRename`,
+ * and the `apply | revert` action discriminator. The shapes here are the
+ * canonical replacement for `RenameSuggestionRef` shipped in
+ * `namespace-audit.types.ts` PR #1 — the structural shape is preserved so
+ * the swap-in is a drop-in replacement.
+ *
+ * Plan: docs/internal/implementation/smi-4588-rename-engine-ledger-install.md §1.
+ */
+export {};
+//# sourceMappingURL=rename-engine.types.js.map

package/dist/src/audit/rename-engine.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rename-engine.types.js","sourceRoot":"","sources":["../../../src/audit/rename-engine.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}