mewkit 1.13.0 → 1.14.1

package/dist/migrate/references/fence-aware-reference-rewriter.js

@@ -0,0 +1,182 @@
+// Fence-aware source-reference rewriter. Replaces the old binary rule
+// ("fence = preserve everything" / "direct-copy = replace everything") with a
+// span-based decision matrix:
+//
+//   span            mapped asset                  unmapped runtime      citation
+//   prose/inline    rewrite to target             neutralize + record   preserve
+//   frontmatter     rewrite to target             neutralize + record   preserve
+//   fenced/code     rewrite ONLY when the asset   preserve + warn       preserve
+//                   is in the migration set,
+//                   else preserve + warn
+//
+// Runnable content is never given a fabricated path: a fenced reference is only
+// rewritten when the referenced asset is provably part of the migration set.
+import { buildMarkdownSpanMap } from "./reference-classifier.js";
+import { SOURCE_ROOT, buildReferenceRewriteTable, resolveReferenceTarget, sourceConfigTokenPattern, sourceReferencePattern, } from "./reference-target-registry.js";
+/**
+ * Build an integrity index from source-relative entries. Entries ending with
+ * "/" match as directory prefixes (e.g. ".claude/skills/demo-skill/").
+ */
+export function createReferenceIntegrityIndex(entries) {
+    const files = new Set();
+    const prefixes = [];
+    for (const entry of entries) {
+        const normalized = entry.replace(/\\/g, "/");
+        if (normalized.endsWith("/"))
+            prefixes.push(normalized.toLowerCase());
+        else
+            files.add(normalized.toLowerCase());
+    }
+    return {
+        has(sourceRelativePath) {
+            const normalized = sourceRelativePath.replace(/\\/g, "/").toLowerCase();
+            if (files.has(normalized))
+                return true;
+            return prefixes.some((prefix) => normalized.startsWith(prefix));
+        },
+    };
+}
+export function combineIntegrityIndexes(...indexes) {
+    const present = indexes.filter((index) => Boolean(index));
+    return { has: (path) => present.some((index) => index.has(path)) };
+}
+const TYPE_DIRS = ["agents", "commands", "skills", "rules", "hooks"];
+// Provider-neutral phrases used when a reference has no provider target.
+const NEUTRAL_TYPE_PHRASE = {
+    rules: "project rules directory/",
+    agents: "project subagents directory/",
+    commands: "project commands directory/",
+    skills: "project skills directory/",
+    hooks: "project hooks directory/",
+};
+const NEUTRAL_ROOT_PHRASE = "project runtime data/";
+const NEUTRAL_CONFIG_PHRASE = "project configuration file";
+function classifySourcePath(path, table) {
+    const suffix = path.slice(SOURCE_ROOT.length);
+    const typeDir = TYPE_DIRS.find((dir) => suffix.toLowerCase().startsWith(`${dir}/`));
+    const target = resolveReferenceTarget(table, path);
+    if (target !== null) {
+        const rule = table.find((r) => path.toLowerCase().startsWith(r.sourcePrefix.toLowerCase()));
+        return {
+            kind: "mapped-asset",
+            target,
+            preservesSuffix: rule?.target?.isDirectory ?? false,
+            neutral: "",
+            reason: "",
+        };
+    }
+    if (typeDir) {
+        return {
+            kind: "unmapped-runtime",
+            target: null,
+            preservesSuffix: false,
+            neutral: `${NEUTRAL_TYPE_PHRASE[typeDir]}${suffix.slice(typeDir.length + 1)}`,
+            reason: `provider has no ${typeDir} surface`,
+        };
+    }
+    return {
+        kind: "unmapped-runtime",
+        target: null,
+        preservesSuffix: false,
+        neutral: `${NEUTRAL_ROOT_PHRASE}${suffix}`,
+        reason: "no provider equivalent for this source runtime path",
+    };
+}
+export function rewriteSourceReferences(content, options) {
+    const table = buildReferenceRewriteTable(options.provider, options.scope ?? "project");
+    const occurrences = [];
+    const warnings = [];
+    const file = options.file ?? "";
+    const record = (occurrence) => {
+        occurrences.push(occurrence);
+        if (occurrence.decision === "preserve-warn") {
+            warnings.push(`Unresolved reference preserved (line ${occurrence.line}): "${occurrence.original}" — ${occurrence.reason}`);
+        }
+    };
+    // Each replace pass shifts byte offsets, so the span map is rebuilt per pass.
+    const buildSpanHelpers = (input) => {
+        const spanMap = options.contentKind === "code" ? null : buildMarkdownSpanMap(input);
+        return {
+            spanAt: (offset) => spanMap?.spanAt(offset) ?? "fenced",
+            lineAt: (offset) => {
+                if (spanMap)
+                    return spanMap.lineNumberAt(offset);
+                let line = 1;
+                for (let i = 0; i < offset && i < input.length; i++)
+                    if (input[i] === "\n")
+                        line++;
+                return line;
+            },
+            isCitationAt: (offset) => spanMap?.isCitationAt(offset) ?? false,
+        };
+    };
+    let { spanAt, lineAt, isCitationAt } = buildSpanHelpers(content);
+    let result = content.replace(sourceReferencePattern(), (matched, ...args) => {
+        const offset = args[args.length - 2];
+        const span = spanAt(offset);
+        const line = lineAt(offset);
+        const base = { file, line, span, original: matched };
+        if (isCitationAt(offset)) {
+            record({ ...base, kind: "citation", decision: "preserve" });
+            return matched;
+        }
+        const classified = classifySourcePath(matched, table);
+        const runnable = span === "fenced";
+        if (!runnable) {
+            if (classified.kind === "mapped-asset" && classified.target !== null) {
+                record({ ...base, kind: "mapped-asset", decision: "rewrite", rewrittenTo: classified.target });
+                return classified.target;
+            }
+            record({
+                ...base,
+                kind: "unmapped-runtime",
+                decision: "rewrite",
+                rewrittenTo: classified.neutral,
+                reason: `${classified.reason}; neutralized`,
+            });
+            return classified.neutral;
+        }
+        // Runnable content: rewrite only with proof the referenced asset migrates
+        // too AND the target keeps the file suffix — a merged/non-directory target
+        // cannot express the file's real location, so rewriting would fabricate.
+        if (classified.kind === "mapped-asset" && classified.target !== null) {
+            if (classified.preservesSuffix && options.migratedRefs?.has(matched)) {
+                record({ ...base, kind: "mapped-asset", decision: "rewrite", rewrittenTo: classified.target });
+                return classified.target;
+            }
+            record({
+                ...base,
+                kind: "mapped-asset",
+                decision: "preserve-warn",
+                reason: classified.preservesSuffix
+                    ? "referenced asset is not part of this migration; left unchanged instead of guessing a target path"
+                    : "target surface is merged/non-directory; original path preserved to avoid a fabricated location",
+            });
+            return matched;
+        }
+        record({ ...base, kind: "unmapped-runtime", decision: "preserve-warn", reason: classified.reason });
+        return matched;
+    });
+    ({ spanAt, lineAt, isCitationAt } = buildSpanHelpers(result));
+    const configTarget = resolveReferenceTarget(table, "CLAUDE.md");
+    const configReplacement = configTarget ?? NEUTRAL_CONFIG_PHRASE;
+    result = result.replace(sourceConfigTokenPattern(), (matched, ...args) => {
+        const offset = args[args.length - 2];
+        const span = spanAt(offset);
+        const line = lineAt(offset);
+        const base = { file, line, span, original: matched };
+        if (isCitationAt(offset)) {
+            record({ ...base, kind: "citation", decision: "preserve" });
+            return matched;
+        }
+        if (span === "fenced") {
+            // Command examples keep the literal token — a rename would break the example.
+            record({ ...base, kind: "mapped-asset", decision: "preserve" });
+            return matched;
+        }
+        record({ ...base, kind: "mapped-asset", decision: "rewrite", rewrittenTo: configReplacement });
+        return configReplacement;
+    });
+    return { content: result, occurrences, warnings };
+}
+//# sourceMappingURL=fence-aware-reference-rewriter.js.map

package/dist/migrate/references/fence-aware-reference-rewriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fence-aware-reference-rewriter.js","sourceRoot":"","sources":["../../../src/migrate/references/fence-aware-reference-rewriter.ts"],"names":[],"mappings":"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"}

package/dist/migrate/references/reference-classifier.d.ts

@@ -0,0 +1,27 @@
+import type { ReferenceSpan } from "./reference-types.js";
+export interface EnvReferenceClassification {
+    /** Provider-neutral replacement phrase pointing at the emitted policy scaffold. */
+    neutral: string;
+    /** Human-readable reason for the migration report (supersedes "no equivalent"). */
+    reason: string;
+}
+/** True when `path` is a `.claude/.env` (or `.env.*`) source reference. */
+export declare function isEnvReference(path: string): boolean;
+/**
+ * Classify a `.claude/.env` reference to point at the emitted Codex
+ * `[shell_environment_policy]` scaffold, replacing the old "no provider
+ * equivalent" classification. Returns null for any non-`.env` path so callers
+ * can fall through to their existing classification.
+ */
+export declare function classifyEnvReference(path: string): EnvReferenceClassification | null;
+export declare function isCitationLine(line: string): boolean;
+export interface MarkdownSpanMap {
+    /** Span type at a byte offset in the original content */
+    spanAt(offset: number): ReferenceSpan;
+    /** 1-based line number at a byte offset */
+    lineNumberAt(offset: number): number;
+    /** Whether the line containing the offset is a citation/attribution line */
+    isCitationAt(offset: number): boolean;
+}
+export declare function buildMarkdownSpanMap(content: string): MarkdownSpanMap;
+//# sourceMappingURL=reference-classifier.d.ts.map

package/dist/migrate/references/reference-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-classifier.d.ts","sourceRoot":"","sources":["../../../src/migrate/references/reference-classifier.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAkB1D,MAAM,WAAW,0BAA0B;IAC1C,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;CACf;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,0BAA0B,GAAG,IAAI,CAQpF;AAcD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKpD;AAID,MAAM,WAAW,eAAe;IAC/B,yDAAyD;IACzD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC;IACtC,2CAA2C;IAC3C,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACrC,4EAA4E;IAC5E,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CACtC;AAuFD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAkCrE"}

package/dist/migrate/references/reference-classifier.js

@@ -0,0 +1,177 @@
+// Markdown span tokenizer + citation detection for source-reference rewriting.
+// Span resolution is line-based (frontmatter / fenced) with per-line inline-code
+// detection. Ambiguous structures (unclosed fences) resolve to "fenced" so the
+// rewriter stays conservative — never rewrite on uncertainty.
+// --- .claude/.env reference classification --------------------------------
+//
+// A `.claude/.env` reference used to fall into the generic "no provider
+// equivalent for this source runtime path" bucket. That is now outdated at the
+// CONFIG level: Codex's documented `[shell_environment_policy]` is the analogue
+// for passing environment into shell subprocesses, and the migration emits a
+// keys-only scaffold for it (see shell-env-policy-emitter). This helper lets the
+// reference rewriter reclassify `.claude/.env` occurrences to POINT AT that
+// scaffold instead of the dead-end "no equivalent" phrase.
+//
+// SECURITY: this helper deals only with the reference PATH text (e.g. the string
+// ".claude/.env"), never with env values.
+/** Matches a source `.claude/.env` (optionally `.env.<suffix>`) path reference. */
+const ENV_REFERENCE = /^\.claude\/\.env(\.[A-Za-z0-9_.-]+)?$/i;
+/** True when `path` is a `.claude/.env` (or `.env.*`) source reference. */
+export function isEnvReference(path) {
+    return ENV_REFERENCE.test(path.replace(/\\/g, "/").trim());
+}
+/**
+ * Classify a `.claude/.env` reference to point at the emitted Codex
+ * `[shell_environment_policy]` scaffold, replacing the old "no provider
+ * equivalent" classification. Returns null for any non-`.env` path so callers
+ * can fall through to their existing classification.
+ */
+export function classifyEnvReference(path) {
+    if (!isEnvReference(path))
+        return null;
+    return {
+        neutral: "the generated [shell_environment_policy] scaffold in config.toml",
+        reason: "environment variables now map to the Codex [shell_environment_policy] scaffold " +
+            "(keys-only, placeholder values); fill values from your environment — do not paste secrets",
+    };
+}
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})/;
+const FRONTMATTER_DELIMITER = /^---\s*$/;
+// A line is a citation when it leads with an attribution verb, or is a
+// blockquote carrying an external URL or a repo slug next to an attribution dash.
+const CITATION_LEAD = /^(?:>\s*)*(?:source|from|ported\s+from)\b/i;
+const BLOCKQUOTE = /^\s*>/;
+const EXTERNAL_URL = /https?:\/\//i;
+// Repo slug like "org/repo"; the lookbehind rejects path segments (".claude/rules", "a/b/c").
+const REPO_SLUG = /(?<![\w./])[a-z0-9][\w.-]*\/[a-z0-9][\w.-]*(?![\w/])/i;
+const ATTRIBUTION_DASH = /[—–]/;
+export function isCitationLine(line) {
+    const trimmed = line.trim();
+    if (CITATION_LEAD.test(trimmed))
+        return true;
+    if (!BLOCKQUOTE.test(trimmed))
+        return false;
+    return EXTERNAL_URL.test(trimmed) || (REPO_SLUG.test(trimmed) && ATTRIBUTION_DASH.test(trimmed));
+}
+function buildLineStarts(content) {
+    const starts = [0];
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] === "\n")
+            starts.push(i + 1);
+    }
+    return starts;
+}
+function lineIndexAt(lineStarts, offset) {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineStarts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}
+function classifyLines(lines) {
+    const kinds = new Array(lines.length).fill("other");
+    let i = 0;
+    if (lines.length > 0 && FRONTMATTER_DELIMITER.test(lines[0])) {
+        const close = lines.findIndex((line, idx) => idx > 0 && FRONTMATTER_DELIMITER.test(line));
+        if (close > 0) {
+            for (let j = 0; j <= close; j++)
+                kinds[j] = "frontmatter";
+            i = close + 1;
+        }
+    }
+    let fenceMarker = null;
+    for (; i < lines.length; i++) {
+        const line = lines[i];
+        if (fenceMarker) {
+            kinds[i] = "fenced";
+            const close = line.match(FENCE_OPEN);
+            if (close && close[1][0] === fenceMarker.char && close[1].length >= fenceMarker.length && !line.trim().slice(close[1].length)) {
+                fenceMarker = null;
+            }
+            continue;
+        }
+        const open = line.match(FENCE_OPEN);
+        if (open) {
+            kinds[i] = "fenced";
+            fenceMarker = { char: open[1][0], length: open[1].length };
+        }
+    }
+    // An unclosed fence leaves fenceMarker set — remaining lines were already
+    // marked fenced inside the loop, which is the conservative resolution.
+    return kinds;
+}
+/** Inline code span ranges (column offsets, delimiters included) for one line. */
+function inlineCodeRanges(line) {
+    const ranges = [];
+    let i = 0;
+    while (i < line.length) {
+        if (line[i] !== "`") {
+            i++;
+            continue;
+        }
+        let openLen = 0;
+        while (line[i + openLen] === "`")
+            openLen++;
+        const openEnd = i + openLen;
+        // Find a closing run of the same length.
+        let j = openEnd;
+        while (j < line.length) {
+            if (line[j] !== "`") {
+                j++;
+                continue;
+            }
+            let runLen = 0;
+            while (line[j + runLen] === "`")
+                runLen++;
+            if (runLen === openLen) {
+                ranges.push([i, j + runLen]);
+                break;
+            }
+            j += runLen;
+        }
+        i = j < line.length ? j + openLen : openEnd;
+    }
+    return ranges;
+}
+export function buildMarkdownSpanMap(content) {
+    const lines = content.split("\n");
+    const lineStarts = buildLineStarts(content);
+    const lineKinds = classifyLines(lines);
+    const citationCache = new Map();
+    const inlineCache = new Map();
+    return {
+        spanAt(offset) {
+            const lineIdx = lineIndexAt(lineStarts, offset);
+            const kind = lineKinds[lineIdx];
+            if (kind === "frontmatter")
+                return "frontmatter";
+            if (kind === "fenced")
+                return "fenced";
+            let ranges = inlineCache.get(lineIdx);
+            if (!ranges) {
+                ranges = inlineCodeRanges(lines[lineIdx]);
+                inlineCache.set(lineIdx, ranges);
+            }
+            const column = offset - lineStarts[lineIdx];
+            return ranges.some(([start, end]) => column >= start && column < end) ? "inline-code" : "prose";
+        },
+        lineNumberAt(offset) {
+            return lineIndexAt(lineStarts, offset) + 1;
+        },
+        isCitationAt(offset) {
+            const lineIdx = lineIndexAt(lineStarts, offset);
+            let cached = citationCache.get(lineIdx);
+            if (cached === undefined) {
+                cached = isCitationLine(lines[lineIdx]);
+                citationCache.set(lineIdx, cached);
+            }
+            return cached;
+        },
+    };
+}
+//# sourceMappingURL=reference-classifier.js.map

package/dist/migrate/references/reference-classifier.js.map

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

package/dist/migrate/references/reference-target-registry.d.ts

@@ -0,0 +1,42 @@
+import type { ProviderType } from "../types.js";
+/** Portable-type keys that have a per-provider target path */
+export type ReferenceTargetType = "agents" | "commands" | "skills" | "rules" | "config" | "hooks";
+export type ReferenceScope = "project" | "global";
+export interface ReferenceTarget {
+    /** Normalized target path; ends with "/" when it is a directory */
+    path: string;
+    isDirectory: boolean;
+}
+export interface ReferenceRewriteRule {
+    type: ReferenceTargetType;
+    /** Source path prefix this rule matches (e.g. ".claude/agents/") */
+    sourcePrefix: string;
+    /** Resolved provider target, or null when the provider has no such surface */
+    target: ReferenceTarget | null;
+    /** Special-case suffix mapping (e.g. Codex command → skill directory filename) */
+    resolveSuffix?: (suffix: string) => string;
+}
+/** Root of the source runtime tree. The only place this literal may appear. */
+export declare const SOURCE_ROOT = ".claude/";
+/** Source config filename token */
+export declare const SOURCE_CONFIG_TOKEN = "CLAUDE.md";
+export declare function sourcePrefixForType(type: ReferenceTargetType): string;
+/**
+ * Resolve the provider target for one portable type. Mirrors the historical
+ * md-strip resolution exactly: prefer the scope's path, fall back to the other.
+ */
+export declare function getReferenceTarget(provider: ProviderType | undefined, type: ReferenceTargetType, scope?: ReferenceScope): ReferenceTarget | null;
+/** Build the full rewrite table for one provider (one rule per portable type). */
+export declare function buildReferenceRewriteTable(provider: ProviderType | undefined, scope?: ReferenceScope): ReferenceRewriteRule[];
+/**
+ * Resolve one source path (e.g. ".claude/skills/x/run.py") against a rewrite
+ * table. Returns the rewritten target path, or null when unmapped.
+ */
+export declare function resolveReferenceTarget(table: ReferenceRewriteRule[], sourcePath: string): string | null;
+/** Any `.claude/<path>` reference, longest path-like run captured */
+export declare function sourceReferencePattern(): RegExp;
+/** Line filter used when the provider has no hooks surface */
+export declare function sourceHooksLinePattern(): RegExp;
+/** The `CLAUDE.md` token in prose */
+export declare function sourceConfigTokenPattern(): RegExp;
+//# sourceMappingURL=reference-target-registry.d.ts.map

package/dist/migrate/references/reference-target-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-target-registry.d.ts","sourceRoot":"","sources":["../../../src/migrate/references/reference-target-registry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElG,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElD,MAAM,WAAW,eAAe;IAC/B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,kFAAkF;IAClF,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAED,+EAA+E;AAC/E,eAAO,MAAM,WAAW,aAAa,CAAC;AAEtC,mCAAmC;AACnC,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAI/C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAErE;AAQD;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,YAAY,GAAG,SAAS,EAClC,IAAI,EAAE,mBAAmB,EACzB,KAAK,GAAE,cAA0B,GAC/B,eAAe,GAAG,IAAI,CAoBxB;AAED,kFAAkF;AAClF,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,YAAY,GAAG,SAAS,EAClC,KAAK,GAAE,cAA0B,GAC/B,oBAAoB,EAAE,CAcxB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBvG;AAMD,qEAAqE;AACrE,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED,8DAA8D;AAC9D,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED,qCAAqC;AACrC,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}

package/dist/migrate/references/reference-target-registry.js

@@ -0,0 +1,100 @@
+// Single source of truth for rewriting source-runtime references
+// (`.claude/<type>/...`, `CLAUDE.md`) to provider target paths. All mapping
+// strings and source patterns live HERE — converters must consume this module
+// instead of holding their own literals (guarded by a unit test).
+import { homedir } from "node:os";
+import { providers } from "../provider-registry.js";
+import { codexCommandSkillRelativePath } from "./codex-command-skill-path.js";
+/** Root of the source runtime tree. The only place this literal may appear. */
+export const SOURCE_ROOT = ".claude/";
+/** Source config filename token */
+export const SOURCE_CONFIG_TOKEN = "CLAUDE.md";
+const DIRECTORY_TYPES = ["agents", "commands", "skills", "rules", "hooks"];
+export function sourcePrefixForType(type) {
+    return type === "config" ? SOURCE_CONFIG_TOKEN : `${SOURCE_ROOT}${type}/`;
+}
+function normalizeTargetPath(path) {
+    const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
+    const home = homedir().replace(/\\/g, "/");
+    return normalized.startsWith(home) ? normalized.replace(home, "~") : normalized;
+}
+/**
+ * Resolve the provider target for one portable type. Mirrors the historical
+ * md-strip resolution exactly: prefer the scope's path, fall back to the other.
+ */
+export function getReferenceTarget(provider, type, scope = "project") {
+    if (!provider)
+        return null;
+    const pathConfig = providers[provider][type];
+    if (!pathConfig)
+        return null;
+    const resolvedPath = scope === "global"
+        ? (pathConfig.globalPath ?? pathConfig.projectPath)
+        : (pathConfig.projectPath ?? pathConfig.globalPath);
+    if (!resolvedPath)
+        return null;
+    const normalized = normalizeTargetPath(resolvedPath);
+    const isDirectory = pathConfig.writeStrategy === "per-file" ||
+        pathConfig.writeStrategy === "yaml-merge" ||
+        pathConfig.writeStrategy === "json-merge";
+    return {
+        path: isDirectory && !normalized.endsWith("/") ? `${normalized}/` : normalized,
+        isDirectory,
+    };
+}
+/** Build the full rewrite table for one provider (one rule per portable type). */
+export function buildReferenceRewriteTable(provider, scope = "project") {
+    const types = [...DIRECTORY_TYPES, "config"];
+    return types.map((type) => {
+        const rule = {
+            type,
+            sourcePrefix: sourcePrefixForType(type),
+            target: getReferenceTarget(provider, type, scope),
+        };
+        // Commands that install as Agent Skills live in one directory per command.
+        if (type === "commands" && provider && providers[provider].commands?.format === "command-to-codex-skill") {
+            rule.resolveSuffix = (suffix) => codexCommandSkillRelativePath(suffix);
+        }
+        return rule;
+    });
+}
+/**
+ * Resolve one source path (e.g. ".claude/skills/x/run.py") against a rewrite
+ * table. Returns the rewritten target path, or null when unmapped.
+ */
+export function resolveReferenceTarget(table, sourcePath) {
+    const normalized = sourcePath.replace(/\\/g, "/");
+    for (const rule of table) {
+        if (rule.type === "config") {
+            if (normalized === rule.sourcePrefix)
+                return rule.target?.path ?? null;
+            continue;
+        }
+        if (!normalized.toLowerCase().startsWith(rule.sourcePrefix.toLowerCase()))
+            continue;
+        if (!rule.target)
+            return null;
+        const suffix = normalized.slice(rule.sourcePrefix.length);
+        if (rule.resolveSuffix && rule.target.isDirectory && suffix) {
+            return `${rule.target.path}${rule.resolveSuffix(suffix)}`;
+        }
+        return rule.target.isDirectory ? `${rule.target.path}${suffix}` : rule.target.path;
+    }
+    return null;
+}
+// --- Source patterns ------------------------------------------------------
+// Regexes matching source references. Kept as factory functions so every
+// caller gets fresh lastIndex state for the global flags.
+/** Any `.claude/<path>` reference, longest path-like run captured */
+export function sourceReferencePattern() {
+    return /\.claude\/[a-zA-Z0-9_./-]*/gi;
+}
+/** Line filter used when the provider has no hooks surface */
+export function sourceHooksLinePattern() {
+    return /\.claude\/hooks\//i;
+}
+/** The `CLAUDE.md` token in prose */
+export function sourceConfigTokenPattern() {
+    return /\bCLAUDE\.md\b/g;
+}
+//# sourceMappingURL=reference-target-registry.js.map

package/dist/migrate/references/reference-target-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-target-registry.js","sourceRoot":"","sources":["../../../src/migrate/references/reference-target-registry.ts"],"names":[],"mappings":"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"}

package/dist/migrate/references/reference-types.d.ts

@@ -0,0 +1,23 @@
+/** Markdown span the occurrence was found in */
+export type ReferenceSpan = "frontmatter" | "fenced" | "inline-code" | "prose";
+/** What the reference points at */
+export type ReferenceKind = "mapped-asset" | "unmapped-runtime" | "citation" | "brand" | "env" | "slash-command";
+/** What the rewriter decided to do with the occurrence */
+export type RewriteDecision = "rewrite" | "preserve" | "preserve-warn";
+/** One classified occurrence, emitted so the report layer can surface every decision */
+export interface ReferenceOccurrence {
+    /** File the occurrence belongs to (target-relative filename or source path) */
+    file: string;
+    /** 1-based line number in the scanned content */
+    line: number;
+    span: ReferenceSpan;
+    kind: ReferenceKind;
+    decision: RewriteDecision;
+    /** The matched source text */
+    original: string;
+    /** Present when decision === "rewrite" */
+    rewrittenTo?: string;
+    /** Human-readable reason for preserve-warn decisions */
+    reason?: string;
+}
+//# sourceMappingURL=reference-types.d.ts.map

package/dist/migrate/references/reference-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-types.d.ts","sourceRoot":"","sources":["../../../src/migrate/references/reference-types.ts"],"names":[],"mappings":"AAIA,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAC;AAE/E,mCAAmC;AACnC,MAAM,MAAM,aAAa,GACtB,cAAc,GACd,kBAAkB,GAClB,UAAU,GACV,OAAO,GACP,KAAK,GACL,eAAe,CAAC;AAEnB,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,GAAG,eAAe,CAAC;AAEvE,wFAAwF;AACxF,MAAM,WAAW,mBAAmB;IACnC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,eAAe,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/migrate/references/reference-types.js

@@ -0,0 +1,5 @@
+// Shared types for source-reference classification and rewriting.
+// A "reference" is any occurrence of a source-runtime path (`.claude/...`) or
+// the source config token (`CLAUDE.md`) inside migrated content.
+export {};
+//# sourceMappingURL=reference-types.js.map

package/dist/migrate/references/reference-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-types.js","sourceRoot":"","sources":["../../../src/migrate/references/reference-types.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,8EAA8E;AAC9E,iEAAiE"}

package/dist/migrate/runtime-compat-audit.d.ts

@@ -1,6 +1,8 @@
 import type { PortableItem, ProviderType } from "./types.js";
+import type { ReferenceOccurrence } from "./references/reference-types.js";
 export interface RuntimeCompatAuditResult {
     errors: string[];
+    warnings: string[];
 }
-export declare function auditRuntimeCompatibility(content: string, item: Pick<PortableItem, "name" | "type">, targetProvider: ProviderType): RuntimeCompatAuditResult;
+export declare function auditRuntimeCompatibility(content: string, item: Pick<PortableItem, "name" | "type">, targetProvider: ProviderType, occurrences?: ReferenceOccurrence[]): RuntimeCompatAuditResult;
 //# sourceMappingURL=runtime-compat-audit.d.ts.map

package/dist/migrate/runtime-compat-audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-compat-audit.d.ts","sourceRoot":"","sources":["../../src/migrate/runtime-compat-audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAgB,YAAY,EAAE,MAAM,YAAY,CAAC;AAG3E,MAAM,WAAW,wBAAwB;IACxC,MAAM,EAAE,MAAM,EAAE,CAAC;CACjB;AAID,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,EACzC,cAAc,EAAE,YAAY,GAC1B,wBAAwB,CAU1B"}
+{"version":3,"file":"runtime-compat-audit.d.ts","sourceRoot":"","sources":["../../src/migrate/runtime-compat-audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAgB,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAG3E,MAAM,WAAW,wBAAwB;IACxC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAID,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,EACzC,cAAc,EAAE,YAAY,EAC5B,WAAW,GAAE,mBAAmB,EAAO,GACrC,wBAAwB,CAe1B"}