@shrkcrft/cli 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/cli
+
+SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/cli
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/asset-preview/apply-action-hint-stub.d.ts

@@ -0,0 +1,28 @@
+export interface IActionHintStubInput {
+    readonly cwd: string;
+    readonly targetPath: string;
+    readonly entryId: string;
+    readonly write: boolean;
+    readonly allowDivergent?: boolean;
+    /** Override the default stub body. */
+    readonly stubBody?: string;
+}
+export interface IActionHintStubResult {
+    readonly ok: boolean;
+    readonly refusal?: string;
+    readonly targetAbs: string;
+    readonly entryId: string;
+    /** Line where the stub was inserted (1-indexed). */
+    readonly insertedAtLine?: number;
+    readonly originalLength: number;
+    readonly nextLength: number;
+    /** Full unified-diff body for human review. */
+    readonly diff?: string;
+    readonly wrote: boolean;
+}
+/**
+ * Compute the patched body. Pure — no IO. The caller persists when
+ * `input.write` is true.
+ */
+export declare function applyActionHintStub(input: IActionHintStubInput): IActionHintStubResult;
+//# sourceMappingURL=apply-action-hint-stub.d.ts.map

package/dist/asset-preview/apply-action-hint-stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-action-hint-stub.d.ts","sourceRoot":"","sources":["../../src/asset-preview/apply-action-hint-stub.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AA0DD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,oBAAoB,GAC1B,qBAAqB,CAgGvB"}

package/dist/asset-preview/apply-action-hint-stub.js

@@ -0,0 +1,170 @@
+/**
+ * Action-hint stub splicer.
+ *
+ * Inserts a commented `actionHints: { ... }` block into the matching
+ * knowledge entry in `sharkcraft/knowledge.ts`. The stub is the same
+ * shape that `fix --action-hints` previews today, but the splicer
+ * actually applies it in place rather than just writing a preview file
+ * under `.sharkcraft/fixes/`.
+ *
+ * Hard rules:
+ *   - Refuses path-escape on target.
+ *   - Refuses pack-contributed entries unless explicitly asked.
+ *   - Refuses if the entry already has an `actionHints` field
+ *     (idempotent).
+ *   - Preview-first: callers must compute the patch first; the writer
+ *     only persists when `write: true`.
+ *   - Stubs are commented placeholders (`/* TODO: ... *\/`). Doctor
+ *     continues to warn (now via `action-hint-quality`) until the
+ *     placeholders are filled.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { findEntryRange as sharedFindEntryRange } from "./entry-mutator.js";
+const DEFAULT_STUB_BODY = [
+    '  // TODO(action-hints): fill the placeholders, then doctor warnings flip off.',
+    '  actionHints: {',
+    '    commands: [/* TODO: shrk commands an agent should run */],',
+    '    mcpTools: [/* TODO: read-only MCP tool names */],',
+    '    forbiddenActions: [/* TODO: things the agent must not do */],',
+    '    verificationCommands: [/* TODO: ids from sharkcraft.config.ts verificationCommands[] */],',
+    "    writePolicy: 'preview-only' /* TODO: 'preview-only' | 'cli-only' | 'plan-first' */,",
+    '  },',
+].join('\n');
+function escapesCwd(cwd, absPath) {
+    const rel = nodePath.relative(cwd, absPath);
+    return rel.startsWith('..') || nodePath.isAbsolute(rel);
+}
+/**
+ * `findEntryRange` lives in `entry-mutator.ts` so the four apply paths
+ * (action-hint, knowledge-stale, template-drift, templates-update)
+ * share the same primitive. This wrapper preserves the call-site name.
+ */
+const findEntryRange = sharedFindEntryRange;
+function entryHasActionHints(body, range) {
+    const slice = body.slice(range.open, range.close + 1);
+    // Match `actionHints:` at the top level — we'll be conservative and look
+    // for the field name preceded by whitespace and followed by `:`.
+    return /\bactionHints\s*:/.test(slice);
+}
+function buildUnifiedDiff(rel, a, b) {
+    const aLines = a.split('\n');
+    const bLines = b.split('\n');
+    let prefix = 0;
+    while (prefix < aLines.length && prefix < bLines.length && aLines[prefix] === bLines[prefix]) {
+        prefix += 1;
+    }
+    let suffix = 0;
+    while (suffix < aLines.length - prefix &&
+        suffix < bLines.length - prefix &&
+        aLines[aLines.length - 1 - suffix] === bLines[bLines.length - 1 - suffix]) {
+        suffix += 1;
+    }
+    const aMid = aLines.slice(prefix, aLines.length - suffix);
+    const bMid = bLines.slice(prefix, bLines.length - suffix);
+    const head = `--- ${rel}\n+++ ${rel}\n@@ -${prefix + 1},${aMid.length} +${prefix + 1},${bMid.length} @@\n`;
+    return (head +
+        aMid.map((l) => `-${l}`).join('\n') +
+        (aMid.length ? '\n' : '') +
+        bMid.map((l) => `+${l}`).join('\n'));
+}
+/**
+ * Compute the patched body. Pure — no IO. The caller persists when
+ * `input.write` is true.
+ */
+export function applyActionHintStub(input) {
+    const cwd = nodePath.resolve(input.cwd);
+    const targetAbs = nodePath.resolve(cwd, input.targetPath);
+    if (escapesCwd(cwd, targetAbs)) {
+        return {
+            ok: false,
+            refusal: `Target path escapes the project root (cwd=${cwd}).`,
+            targetAbs,
+            entryId: input.entryId,
+            originalLength: 0,
+            nextLength: 0,
+            wrote: false,
+        };
+    }
+    if (!existsSync(targetAbs)) {
+        return {
+            ok: false,
+            refusal: `Target file not found: ${targetAbs}`,
+            targetAbs,
+            entryId: input.entryId,
+            originalLength: 0,
+            nextLength: 0,
+            wrote: false,
+        };
+    }
+    const body = readFileSync(targetAbs, 'utf8');
+    const range = findEntryRange(body, input.entryId);
+    if (!range) {
+        return {
+            ok: false,
+            refusal: `Entry "${input.entryId}" not found in ${nodePath.relative(cwd, targetAbs)}.`,
+            targetAbs,
+            entryId: input.entryId,
+            originalLength: body.length,
+            nextLength: body.length,
+            wrote: false,
+        };
+    }
+    if (entryHasActionHints(body, range) && !input.allowDivergent) {
+        return {
+            ok: false,
+            refusal: `Entry "${input.entryId}" already has an actionHints field. Pass --allow-divergent to overwrite.`,
+            targetAbs,
+            entryId: input.entryId,
+            originalLength: body.length,
+            nextLength: body.length,
+            wrote: false,
+        };
+    }
+    const stubBody = input.stubBody ?? DEFAULT_STUB_BODY;
+    // Match the closing brace's indent + 2 spaces for the stub.
+    const childIndent = range.indent + '  ';
+    const indentedStub = stubBody
+        .split('\n')
+        .map((l) => (l.length > 0 ? childIndent + l.replace(/^ {2}/, '') : l))
+        .join('\n');
+    // Insert before the closing `}` of the entry literal, with a leading
+    // newline so the result lands on its own lines.
+    const before = body.slice(0, range.close);
+    const after = body.slice(range.close);
+    // Ensure the inserted block is separated from the previous content by a
+    // newline + appropriate indent.
+    const trimmedBefore = before.replace(/[ \t]*$/, '');
+    // Ensure the preceding line ends with a comma (object literal field).
+    const ensuredComma = /[,{][ \t\r\n]*$/.test(trimmedBefore)
+        ? trimmedBefore
+        : trimmedBefore.replace(/[ \t\r\n]*$/, '') + ',';
+    // See `insertField` in entry-mutator.ts: the inserted line carries
+    // the indent for the next `}`, so `after` is appended verbatim —
+    // slicing the indent here strips the closing `}` whenever it lived
+    // on its own indented line.
+    const insertedLine = (ensuredComma.length > 0 && !ensuredComma.endsWith('\n') ? '\n' : '') +
+        indentedStub +
+        '\n' +
+        range.indent;
+    const nextBody = ensuredComma + insertedLine + after;
+    let wrote = false;
+    if (input.write && nextBody !== body) {
+        writeFileSync(targetAbs, nextBody, 'utf8');
+        wrote = true;
+    }
+    const rel = nodePath.relative(cwd, targetAbs) || nodePath.basename(targetAbs);
+    const diff = buildUnifiedDiff(rel, body, nextBody);
+    // Compute the line where the stub starts (after the comma we ensured).
+    const insertedAt = ensuredComma.split('\n').length;
+    return {
+        ok: true,
+        targetAbs,
+        entryId: input.entryId,
+        insertedAtLine: insertedAt,
+        originalLength: body.length,
+        nextLength: nextBody.length,
+        diff,
+        wrote,
+    };
+}

package/dist/asset-preview/apply-asset-preview.d.ts

@@ -0,0 +1,31 @@
+/** Asset file kinds the merge knows how to insert into. */
+export type AssetTargetKind = 'knowledge' | 'rules' | 'paths' | 'templates' | 'pipelines' | 'boundaries' | 'presets' | 'unknown';
+/** Single unified-diff entry for the preview output. */
+export interface IDiffSummary {
+    readonly added: number;
+    readonly removed: number;
+    /** First 20 lines of context; full text available in `unifiedDiff`. */
+    readonly preview: string;
+    readonly unifiedDiff: string;
+}
+export interface IAssetPreviewInput {
+    readonly cwd: string;
+    readonly draftPath: string;
+    readonly targetPath: string;
+    readonly write: boolean;
+    readonly allowUnknownTarget: boolean;
+}
+export interface IAssetPreviewResult {
+    readonly ok: boolean;
+    readonly refusal?: string;
+    readonly draftAbs: string;
+    readonly targetAbs: string;
+    readonly targetKind: AssetTargetKind;
+    readonly originalLength: number;
+    readonly nextLength: number;
+    readonly diff?: IDiffSummary;
+    readonly wrote: boolean;
+    readonly validationCommands: readonly string[];
+}
+export declare function applyAssetPreview(input: IAssetPreviewInput): IAssetPreviewResult;
+//# sourceMappingURL=apply-asset-preview.d.ts.map

package/dist/asset-preview/apply-asset-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-asset-preview.d.ts","sourceRoot":"","sources":["../../src/asset-preview/apply-asset-preview.ts"],"names":[],"mappings":"AAwBA,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GACvB,WAAW,GACX,OAAO,GACP,OAAO,GACP,WAAW,GACX,WAAW,GACX,YAAY,GACZ,SAAS,GACT,SAAS,CAAC;AAYd,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AAiFD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CAmHhF"}

package/dist/asset-preview/apply-asset-preview.js

@@ -0,0 +1,210 @@
+/**
+ * `shrk apply --asset-preview <draft.ts> --target <file>`.
+ *
+ * Paste-with-review for authoring drafts. The agent generated a preview
+ * under `.sharkcraft/authoring/<...>.draft.ts` (via `knowledge add` /
+ * `rules scaffold` / etc.) and now needs to *merge* that draft into the
+ * actual asset file (`sharkcraft/knowledge.ts` or a pack's equivalent).
+ *
+ *   Default dry-run. `--write` to persist.
+ *   Refuses path-escape on `--target`.
+ *   Refuses unknown asset types unless `--allow-unknown-target`.
+ *   Surfaces signature status after pack asset changes.
+ *   Records provenance automatically.
+ *   Prints the exact validation commands to run next.
+ *
+ * Merge strategy: insert the draft body just before the last `]` in the
+ * target. Asset files are arrays of literal entries, so this preserves
+ * formatting and keeps the entries grouped. When no `]` is found, the
+ * draft appends to the end (this can only happen for non-array targets,
+ * which require `--allow-unknown-target` anyway).
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+const KNOWN_ASSET_BASENAMES = new Map([
+    ['knowledge.ts', 'knowledge'],
+    ['rules.ts', 'rules'],
+    ['paths.ts', 'paths'],
+    ['templates.ts', 'templates'],
+    ['pipelines.ts', 'pipelines'],
+    ['boundaries.ts', 'boundaries'],
+    ['presets.ts', 'presets'],
+]);
+function classifyTarget(absPath) {
+    return KNOWN_ASSET_BASENAMES.get(nodePath.basename(absPath)) ?? 'unknown';
+}
+function escapesCwd(cwd, absPath) {
+    const rel = nodePath.relative(cwd, absPath);
+    return rel.startsWith('..') || nodePath.isAbsolute(rel);
+}
+/** Insert `draftBody` before the last `]` in `targetBody`. */
+function mergeIntoArray(targetBody, draftBody) {
+    const trimmedDraft = draftBody.trimEnd();
+    if (!trimmedDraft)
+        return targetBody;
+    const close = targetBody.lastIndexOf(']');
+    if (close === -1) {
+        // Not an array file — append.
+        const sep = targetBody.endsWith('\n') ? '\n' : '\n\n';
+        return targetBody + sep + trimmedDraft + '\n';
+    }
+    const before = targetBody.slice(0, close);
+    const after = targetBody.slice(close);
+    const ensureComma = trimmedDraft.endsWith(',') ? trimmedDraft : trimmedDraft + ',';
+    // Preserve the indentation of the last entry — pick the leading whitespace
+    // of the line containing the `]`.
+    const lineStart = before.lastIndexOf('\n');
+    const closingIndent = lineStart === -1 ? '' : before.slice(lineStart + 1);
+    const indent = closingIndent.replace(/[^ \t]/g, '');
+    const childIndent = indent + '  ';
+    const indented = ensureComma
+        .split('\n')
+        .map((l) => (l.length > 0 ? childIndent + l : l))
+        .join('\n');
+    return before.trimEnd() + '\n' + indented + '\n' + closingIndent + after.slice(0);
+}
+function buildUnifiedDiff(aPath, a, bPath, b) {
+    const aLines = a.split('\n');
+    const bLines = b.split('\n');
+    // Tiny diff: line-level common-prefix + common-suffix + middle delta.
+    let prefix = 0;
+    while (prefix < aLines.length && prefix < bLines.length && aLines[prefix] === bLines[prefix]) {
+        prefix += 1;
+    }
+    let suffix = 0;
+    while (suffix < aLines.length - prefix &&
+        suffix < bLines.length - prefix &&
+        aLines[aLines.length - 1 - suffix] === bLines[bLines.length - 1 - suffix]) {
+        suffix += 1;
+    }
+    const aMiddle = aLines.slice(prefix, aLines.length - suffix);
+    const bMiddle = bLines.slice(prefix, bLines.length - suffix);
+    const ctxBefore = aLines.slice(Math.max(0, prefix - 3), prefix);
+    const ctxAfter = aLines.slice(aLines.length - suffix, Math.min(aLines.length, aLines.length - suffix + 3));
+    const head = `--- ${aPath}\n+++ ${bPath}\n@@ -${prefix + 1},${aMiddle.length} +${prefix + 1},${bMiddle.length} @@\n`;
+    const body = ctxBefore.map((l) => ` ${l}`).join('\n') +
+        (ctxBefore.length ? '\n' : '') +
+        aMiddle.map((l) => `-${l}`).join('\n') +
+        (aMiddle.length ? '\n' : '') +
+        bMiddle.map((l) => `+${l}`).join('\n') +
+        (bMiddle.length ? '\n' : '') +
+        ctxAfter.map((l) => ` ${l}`).join('\n');
+    const unified = head + body;
+    const previewLines = unified.split('\n').slice(0, 24).join('\n');
+    return {
+        added: bMiddle.length,
+        removed: aMiddle.length,
+        preview: previewLines,
+        unifiedDiff: unified,
+    };
+}
+export function applyAssetPreview(input) {
+    const validationCommands = [
+        'shrk doctor',
+        'shrk knowledge stale-check --ci',
+        'shrk check boundaries --changed-only',
+    ];
+    const cwd = nodePath.resolve(input.cwd);
+    const draftAbs = nodePath.resolve(cwd, input.draftPath);
+    const targetAbs = nodePath.resolve(cwd, input.targetPath);
+    if (escapesCwd(cwd, draftAbs)) {
+        return {
+            ok: false,
+            refusal: `Draft path escapes the project root (cwd=${cwd}).`,
+            draftAbs,
+            targetAbs,
+            targetKind: 'unknown',
+            originalLength: 0,
+            nextLength: 0,
+            wrote: false,
+            validationCommands,
+        };
+    }
+    if (escapesCwd(cwd, targetAbs)) {
+        return {
+            ok: false,
+            refusal: `Target path escapes the project root (cwd=${cwd}).`,
+            draftAbs,
+            targetAbs,
+            targetKind: 'unknown',
+            originalLength: 0,
+            nextLength: 0,
+            wrote: false,
+            validationCommands,
+        };
+    }
+    if (!existsSync(draftAbs)) {
+        return {
+            ok: false,
+            refusal: `Draft file not found: ${draftAbs}`,
+            draftAbs,
+            targetAbs,
+            targetKind: 'unknown',
+            originalLength: 0,
+            nextLength: 0,
+            wrote: false,
+            validationCommands,
+        };
+    }
+    if (!existsSync(targetAbs)) {
+        return {
+            ok: false,
+            refusal: `Target file not found: ${targetAbs}`,
+            draftAbs,
+            targetAbs,
+            targetKind: 'unknown',
+            originalLength: 0,
+            nextLength: 0,
+            wrote: false,
+            validationCommands,
+        };
+    }
+    const targetKind = classifyTarget(targetAbs);
+    if (targetKind === 'unknown' && !input.allowUnknownTarget) {
+        return {
+            ok: false,
+            refusal: `Target is not a known asset/config type (${nodePath.basename(targetAbs)}). Pass --allow-unknown-target to override.`,
+            draftAbs,
+            targetAbs,
+            targetKind,
+            originalLength: 0,
+            nextLength: 0,
+            wrote: false,
+            validationCommands,
+        };
+    }
+    const draftBody = readFileSync(draftAbs, 'utf8');
+    const targetBody = readFileSync(targetAbs, 'utf8');
+    const nextBody = mergeIntoArray(targetBody, draftBody);
+    const diff = buildUnifiedDiff(input.targetPath, targetBody, input.targetPath, nextBody);
+    let wrote = false;
+    if (input.write && nextBody !== targetBody) {
+        writeFileSync(targetAbs, nextBody, 'utf8');
+        wrote = true;
+    }
+    // Provide a kind-aware extra validation command.
+    const kindValidation = {
+        knowledge: 'shrk knowledge stale-check --ci',
+        rules: 'shrk rules lint',
+        paths: 'shrk paths list',
+        templates: 'shrk templates drift --min-severity warning',
+        pipelines: 'shrk pipelines lint',
+        boundaries: 'shrk check boundaries --changed-only',
+        presets: 'shrk presets list --json',
+    };
+    const extra = kindValidation[targetKind];
+    const allValidation = extra
+        ? Array.from(new Set([extra, ...validationCommands]))
+        : validationCommands;
+    return {
+        ok: true,
+        draftAbs,
+        targetAbs,
+        targetKind,
+        originalLength: targetBody.length,
+        nextLength: nextBody.length,
+        diff,
+        wrote,
+        validationCommands: allValidation,
+    };
+}

package/dist/asset-preview/apply-knowledge-stale-fix.d.ts

@@ -0,0 +1,37 @@
+import type { IKnowledgeReference } from '@shrkcrft/knowledge';
+/**
+ * Optional rename payload. When present, the apply rewrites the
+ * matching reference's identifying field (`path` / `id` / `symbol`)
+ * rather than removing the whole element. Migration is strictly safer
+ * than drop when the engine can identify the new location.
+ */
+export interface IKnowledgeStaleRename {
+    readonly path?: string;
+    readonly id?: string;
+    readonly symbol?: string;
+}
+export interface IKnowledgeStaleFixInput {
+    readonly cwd: string;
+    readonly targetPath: string;
+    readonly entryId: string;
+    readonly reference: IKnowledgeReference;
+    readonly write: boolean;
+    /** When present, rename in place instead of dropping. */
+    readonly renameTo?: IKnowledgeStaleRename;
+}
+export interface IKnowledgeStaleFixResult {
+    readonly ok: boolean;
+    readonly refusal?: string;
+    readonly targetAbs: string;
+    readonly entryId: string;
+    readonly originalLength: number;
+    readonly nextLength: number;
+    /** Number of references dropped (only meaningful in `drop` mode). */
+    readonly removedCount: number;
+    /** Mode the splicer actually applied. */
+    readonly mode: 'drop' | 'rename';
+    readonly diff?: string;
+    readonly wrote: boolean;
+}
+export declare function applyKnowledgeStaleFix(input: IKnowledgeStaleFixInput): IKnowledgeStaleFixResult;
+//# sourceMappingURL=apply-knowledge-stale-fix.d.ts.map

package/dist/asset-preview/apply-knowledge-stale-fix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-knowledge-stale-fix.d.ts","sourceRoot":"","sources":["../../src/asset-preview/apply-knowledge-stale-fix.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG/D;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AA2MD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,uBAAuB,GAC7B,wBAAwB,CAwI1B"}