@shrkcrft/inspector 0.1.0-alpha.1

package/dist/pack-contributions-inventory.js

@@ -0,0 +1,732 @@
+/**
+ * Generic pack contributions inventory + conflict detector.
+ *
+ * Reads each pack's manifest, enumerates the contribution slots, and reports:
+ *   - one row per (kind, id, source) — the inventory
+ *   - one row per detected collision — the conflicts
+ *
+ * Both outputs are deterministic and read-only.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+// Structural loaders used to replace regex-fallback noise per kind.
+import { HELPERS } from "./helper-registry.js";
+import { listConventions } from "./convention-registry.js";
+import { listPluginLifecycleProfiles } from "./plugin-lifecycle-profile-registry.js";
+import { listPackHelpers } from "./pack-helper-registry.js";
+import { listTaskRoutingHints } from "./task-routing-hint-registry.js";
+import { listRegistrationHints } from "./registration-hint-registry.js";
+import { listPlaybooks } from "./playbook-registry.js";
+import { loadAllContractTemplates } from "./contract-template-registry.js";
+import { listMigrationProfilesFromPacks } from "./migration-profile-registry.js";
+export const PACK_CONTRIBUTIONS_INVENTORY_SCHEMA = 'sharkcraft.pack-contributions-inventory/v1';
+export var ContributionSource;
+(function (ContributionSource) {
+    ContributionSource["Builtin"] = "builtin";
+    ContributionSource["Local"] = "local";
+    ContributionSource["Pack"] = "pack";
+    ContributionSource["Fixture"] = "fixture";
+})(ContributionSource || (ContributionSource = {}));
+export var ContributionKind;
+(function (ContributionKind) {
+    ContributionKind["Knowledge"] = "knowledge";
+    ContributionKind["Rule"] = "rule";
+    ContributionKind["Path"] = "path";
+    ContributionKind["PathConvention"] = "path-convention";
+    ContributionKind["Template"] = "template";
+    ContributionKind["Pipeline"] = "pipeline";
+    ContributionKind["Preset"] = "preset";
+    ContributionKind["Boundary"] = "boundary";
+    ContributionKind["ScaffoldPattern"] = "scaffold-pattern";
+    ContributionKind["Policy"] = "policy";
+    ContributionKind["Construct"] = "construct";
+    ContributionKind["Playbook"] = "playbook";
+    ContributionKind["SearchTuning"] = "search-tuning";
+    ContributionKind["FeedbackRule"] = "feedback-rule";
+    ContributionKind["Decision"] = "decision";
+    ContributionKind["ContractTemplate"] = "contract-template";
+    ContributionKind["MigrationProfile"] = "migration-profile";
+    ContributionKind["PluginLifecycleProfile"] = "plugin-lifecycle-profile";
+    ContributionKind["ContextTest"] = "context-test";
+    ContributionKind["AgentTest"] = "agent-test";
+    ContributionKind["Helper"] = "helper";
+    ContributionKind["TaskRoutingHint"] = "task-routing-hint";
+    ContributionKind["Convention"] = "convention";
+    ContributionKind["Docs"] = "docs";
+})(ContributionKind || (ContributionKind = {}));
+export var ConflictKind;
+(function (ConflictKind) {
+    ConflictKind["DuplicateIdSameKind"] = "duplicate-id-same-kind";
+    ConflictKind["DuplicateIdDifferentSource"] = "duplicate-id-different-source";
+    ConflictKind["ShadowedLocalConfig"] = "shadowed-local-config";
+    ConflictKind["ShadowedPackConfig"] = "shadowed-pack-config";
+    ConflictKind["InvalidContribution"] = "invalid-contribution";
+    ConflictKind["MissingReferencedId"] = "missing-referenced-id";
+    ConflictKind["StaleSignature"] = "stale-signature";
+    ConflictKind["IncompatibleSchema"] = "incompatible-schema";
+    ConflictKind["MissingLoader"] = "missing-loader";
+})(ConflictKind || (ConflictKind = {}));
+const KIND_TO_SLOT = {
+    [ContributionKind.Knowledge]: 'knowledgeFiles',
+    [ContributionKind.Rule]: 'ruleFiles',
+    [ContributionKind.Path]: 'pathFiles',
+    [ContributionKind.PathConvention]: 'pathConventionFiles',
+    [ContributionKind.Template]: 'templateFiles',
+    [ContributionKind.Pipeline]: 'pipelineFiles',
+    [ContributionKind.Preset]: 'presetFiles',
+    [ContributionKind.Boundary]: 'boundaryFiles',
+    [ContributionKind.ScaffoldPattern]: 'scaffoldPatternFiles',
+    [ContributionKind.Policy]: 'policyCheckFiles',
+    [ContributionKind.Construct]: 'constructFiles',
+    [ContributionKind.Playbook]: 'playbookFiles',
+    [ContributionKind.SearchTuning]: 'searchTuningFiles',
+    [ContributionKind.FeedbackRule]: 'feedbackRuleFiles',
+    [ContributionKind.Decision]: 'decisionFiles',
+    [ContributionKind.ContractTemplate]: 'contractTemplateFiles',
+    [ContributionKind.MigrationProfile]: 'migrationProfileFiles',
+    [ContributionKind.PluginLifecycleProfile]: 'pluginLifecycleProfileFiles',
+    [ContributionKind.ContextTest]: 'contextTestFiles',
+    [ContributionKind.AgentTest]: 'agentTestFiles',
+    [ContributionKind.Helper]: 'helperFiles',
+    [ContributionKind.TaskRoutingHint]: 'taskRoutingHintFiles',
+    [ContributionKind.Convention]: 'conventionFiles',
+    [ContributionKind.Docs]: 'docsFiles',
+};
+function safeRead(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Lightweight static extractor — looks for `id: '...'` and `title: '...'`
+ * occurrences inside a contribution file. This works without importing the
+ * file (the engine already has dedicated loaders that do this; the inventory
+ * is intentionally a fast surface-level reporter that doesn't re-run them).
+ */
+function extractIdsFromFile(content) {
+    const entries = [];
+    const idRe = /\bid\s*:\s*['"]([A-Za-z_][\w.-]*)['"]/g;
+    let match;
+    while ((match = idRe.exec(content)) !== null) {
+        const id = match[1];
+        // Look ahead a bit for a title within the next ~200 chars.
+        const lookahead = content.slice(match.index, match.index + 400);
+        const titleMatch = /\btitle\s*:\s*['"]([^'"]+)['"]/.exec(lookahead);
+        const entry = { id };
+        if (titleMatch)
+            entry.title = titleMatch[1] ?? undefined;
+        entries.push(entry);
+    }
+    return entries;
+}
+function buildContribFileEntries(inspection) {
+    const out = [];
+    // Local contributions inferred from sharkcraft.config + conventional file
+    // names. (The engine doesn't have a single canonical list; we use the same
+    // file-name conventions the loaders accept.)
+    const dir = inspection.sharkcraftDir;
+    if (dir) {
+        const localConventions = [
+            { kind: ContributionKind.Knowledge, relCandidates: ['knowledge.ts'] },
+            { kind: ContributionKind.Rule, relCandidates: ['rules.ts'] },
+            { kind: ContributionKind.Path, relCandidates: ['paths.ts'] },
+            { kind: ContributionKind.PathConvention, relCandidates: ['path-conventions.ts'] },
+            { kind: ContributionKind.Template, relCandidates: ['templates.ts'] },
+            { kind: ContributionKind.Pipeline, relCandidates: ['pipelines.ts'] },
+            { kind: ContributionKind.ScaffoldPattern, relCandidates: ['scaffold-patterns.ts'] },
+            { kind: ContributionKind.Policy, relCandidates: ['policies.ts'] },
+            { kind: ContributionKind.Playbook, relCandidates: ['playbooks.ts'] },
+            { kind: ContributionKind.SearchTuning, relCandidates: ['search-tuning.ts'] },
+            { kind: ContributionKind.FeedbackRule, relCandidates: ['feedback-rules.ts'] },
+            { kind: ContributionKind.Decision, relCandidates: ['decisions.ts'] },
+            { kind: ContributionKind.AgentTest, relCandidates: ['agent-tests.ts'] },
+            {
+                kind: ContributionKind.PluginLifecycleProfile,
+                relCandidates: ['plugin-lifecycle-profiles.ts'],
+            },
+            { kind: ContributionKind.ContractTemplate, relCandidates: ['contract-templates.ts'] },
+            { kind: ContributionKind.MigrationProfile, relCandidates: ['migration-profiles.ts'] },
+            { kind: ContributionKind.Helper, relCandidates: ['helpers.ts'] },
+            { kind: ContributionKind.TaskRoutingHint, relCandidates: ['task-routing-hints.ts'] },
+            { kind: ContributionKind.Convention, relCandidates: ['conventions.ts'] },
+        ];
+        for (const c of localConventions) {
+            const files = c.relCandidates
+                .map((rel) => nodePath.join(dir, rel))
+                .filter((abs) => existsSync(abs));
+            if (files.length > 0) {
+                out.push({ kind: c.kind, files, source: ContributionSource.Local });
+            }
+        }
+    }
+    // Pack contributions from manifests.
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        for (const kind of Object.values(ContributionKind)) {
+            const slot = KIND_TO_SLOT[kind];
+            const rels = contributions[slot];
+            if (!rels || rels.length === 0)
+                continue;
+            const abs = rels.map((rel) => nodePath.resolve(pack.packageRoot, rel)).filter((f) => existsSync(f));
+            out.push({
+                kind,
+                packageName: pack.packageName,
+                packageRoot: pack.packageRoot,
+                files: abs,
+                source: ContributionSource.Pack,
+            });
+        }
+    }
+    return out;
+}
+async function loadStructuralEntries(inspection) {
+    const byKindAndFile = new Map();
+    const structuralFiles = new Map();
+    const structuralIds = new Map();
+    const projectRoot = inspection.projectRoot;
+    const rel = (abs) => abs ? nodePath.relative(projectRoot, abs) || abs : undefined;
+    const record = (kind, file, entry) => {
+        if (!file)
+            return;
+        const relPath = rel(file);
+        const kindKey = kind;
+        let m = byKindAndFile.get(kindKey);
+        if (!m) {
+            m = new Map();
+            byKindAndFile.set(kindKey, m);
+        }
+        let arr = m.get(relPath);
+        if (!arr) {
+            arr = [];
+            m.set(relPath, arr);
+        }
+        arr.push(entry);
+        let fileSet = structuralFiles.get(kindKey);
+        if (!fileSet) {
+            fileSet = new Set();
+            structuralFiles.set(kindKey, fileSet);
+        }
+        fileSet.add(relPath);
+        // Track `(kind, packageName||local, id)` so regex fallback can
+        // dedupe across multiple physical paths.
+        let idSet = structuralIds.get(kindKey);
+        if (!idSet) {
+            idSet = new Set();
+            structuralIds.set(kindKey, idSet);
+        }
+        const pkg = entry.packageName ?? '__local__';
+        idSet.add(`${pkg}:${entry.id}`);
+    };
+    // Knowledge / rules / paths / templates / pipelines come from inspection.
+    for (const k of inspection.knowledgeEntries) {
+        record(ContributionKind.Knowledge, k.source?.origin, {
+            id: k.id,
+            ...(k.title ? { title: k.title } : {}),
+            source: ContributionSource.Local,
+        });
+    }
+    try {
+        const rules = inspection.ruleService?.list?.() ?? [];
+        for (const r of rules) {
+            record(ContributionKind.Rule, r.source?.origin, {
+                id: r.id,
+                ...(r.title ? { title: r.title } : {}),
+                source: ContributionSource.Local,
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const paths = inspection.pathService?.list?.() ?? [];
+        for (const p of paths) {
+            record(ContributionKind.Path, p.source?.origin, {
+                id: p.id,
+                ...(p.title ? { title: p.title } : {}),
+                source: ContributionSource.Local,
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const templates = inspection.templateRegistry?.list?.() ?? [];
+        for (const t of templates) {
+            record(ContributionKind.Template, t.source?.origin, {
+                id: t.id,
+                ...(t.description ? { title: t.description } : {}),
+                source: ContributionSource.Local,
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const pipelines = inspection.pipelineRegistry?.list?.() ?? [];
+        for (const p of pipelines) {
+            record(ContributionKind.Pipeline, p.source?.origin, {
+                id: p.id,
+                ...(p.title ? { title: p.title } : {}),
+                source: ContributionSource.Local,
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Playbooks — these were a major source of nested step.id false positives.
+    try {
+        const playbooks = await listPlaybooks(inspection);
+        for (const p of playbooks) {
+            record(ContributionKind.Playbook, p.sourceFile, {
+                id: p.id,
+                ...(p.title ? { title: p.title } : {}),
+                source: p.source === 'pack' ? ContributionSource.Pack : ContributionSource.Local,
+                ...(p.packageName ? { packageName: p.packageName } : {}),
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Plugin-lifecycle profiles — same problem (sub-object ids).
+    try {
+        const entries = await listPluginLifecycleProfiles(inspection);
+        for (const e of entries) {
+            record(ContributionKind.PluginLifecycleProfile, e.sourceFile, {
+                id: e.profile.id,
+                ...(e.profile.title ? { title: e.profile.title } : {}),
+                source: e.source === 'pack'
+                    ? ContributionSource.Pack
+                    : ContributionSource.Local,
+                ...(e.packageName ? { packageName: e.packageName } : {}),
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Conventions, helpers, routing hints, registration hints, contract templates,
+    // migration profiles — all loader-backed today.
+    try {
+        const entries = await listConventions(inspection);
+        for (const e of entries) {
+            record(ContributionKind.Convention, e.sourceFile, {
+                id: e.convention.id,
+                ...(e.convention.title
+                    ? { title: e.convention.title }
+                    : {}),
+                source: e.source === 'pack'
+                    ? ContributionSource.Pack
+                    : ContributionSource.Local,
+                ...(e.packageName ? { packageName: e.packageName } : {}),
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const builtIns = HELPERS;
+        for (const h of builtIns) {
+            // Built-in helpers don't have a file; skip the structural mapping.
+            void h;
+        }
+        const packHelpers = await listPackHelpers(inspection);
+        for (const e of packHelpers) {
+            record(ContributionKind.Helper, e.sourceFile, {
+                id: e.helper.id,
+                ...(e.helper.description
+                    ? { title: e.helper.description }
+                    : {}),
+                source: ContributionSource.Pack,
+                ...(e.packageName ? { packageName: e.packageName } : {}),
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const entries = await listTaskRoutingHints(inspection);
+        for (const e of entries) {
+            record(ContributionKind.TaskRoutingHint, e.sourceFile, {
+                id: e.hint.id,
+                ...(e.hint.title ? { title: e.hint.title } : {}),
+                source: e.source === 'pack'
+                    ? ContributionSource.Pack
+                    : ContributionSource.Local,
+                ...(e.packageName ? { packageName: e.packageName } : {}),
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Registration hints don't have a dedicated `ContributionKind` today — they
+    // ship through templates' metadata + the registration-hint registry — so
+    // we deliberately skip them in the structural map. The self-config doctor
+    // surfaces broken registration-hint refs via its own check.
+    await Promise.resolve();
+    void listRegistrationHints;
+    try {
+        const pair = await loadAllContractTemplates(inspection);
+        for (const e of pair.entries) {
+            record(ContributionKind.ContractTemplate, e.sourceFile, {
+                id: e.template.id,
+                ...(e.template.title
+                    ? { title: e.template.title }
+                    : {}),
+                source: e.source === 'pack'
+                    ? ContributionSource.Pack
+                    : ContributionSource.Local,
+                ...(e.packageName ? { packageName: e.packageName } : {}),
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const profiles = await listMigrationProfilesFromPacks(inspection);
+        for (const p of profiles) {
+            record(ContributionKind.MigrationProfile, p.sourceFile, {
+                id: p.id,
+                ...(p.title ? { title: p.title } : {}),
+                source: ContributionSource.Pack,
+                ...(p.packageName ? { packageName: p.packageName } : {}),
+            });
+        }
+    }
+    catch {
+        // ignore
+    }
+    return {
+        byKindAndFile: byKindAndFile,
+        structuralFiles: structuralFiles,
+        structuralIds: structuralIds,
+    };
+}
+/**
+ * Build the inventory. Read-only. Never imports pack code beyond the
+ * registry loaders that already do.
+ *
+ * Structural-first extraction. For kinds with a dedicated loader, the
+ * inventory uses the loader's authoritative ids and **suppresses the
+ * regex fallback** for those same source files. This eliminates the
+ * nested-step-id false positives that previously produced duplicate /
+ * conflict noise.
+ */
+export function buildPackContributionsInventory(inspection) {
+    return buildPackContributionsInventorySync(inspection, null);
+}
+/**
+ * Async variant that loads structural per-kind entries first.
+ *
+ * Production callers should prefer this over the sync wrapper since it
+ * provides the noise-free output. The sync wrapper exists for backward
+ * compatibility with callers that haven't been awaited yet.
+ */
+export async function buildPackContributionsInventoryAsync(inspection) {
+    const structural = await loadStructuralEntries(inspection);
+    return buildPackContributionsInventorySync(inspection, structural);
+}
+function buildPackContributionsInventorySync(inspection, structural) {
+    const entriesByKind = {};
+    const entries = [];
+    const fileGroups = buildContribFileEntries(inspection);
+    // First, emit structural entries (authoritative ids).
+    if (structural) {
+        for (const [kindKey, files] of structural.byKindAndFile) {
+            for (const [relPath, list] of files) {
+                for (const s of list) {
+                    const entry = {
+                        kind: kindKey,
+                        id: s.id,
+                        ...(s.title ? { title: s.title } : {}),
+                        source: s.source,
+                        ...(s.packageName ? { packageName: s.packageName } : {}),
+                        sourceFile: relPath,
+                        validation: 'ok',
+                        extractionMode: 'structural',
+                        confidence: 'high',
+                    };
+                    (entriesByKind[kindKey] ??= []).push(entry);
+                    entries.push(entry);
+                }
+            }
+        }
+    }
+    const ingestFile = (group, file) => {
+        const rel = nodePath.relative(inspection.projectRoot, file) || file;
+        // Skip regex extraction when the structural loader already covered
+        // this (kind, file) pair. Otherwise nested step.id / anchor.id / sub-object
+        // ids re-appear as top-level contribution ids, producing duplicate noise.
+        const handled = structural?.structuralFiles.get(group.kind)?.has(rel);
+        if (handled)
+            return;
+        const content = safeRead(file);
+        if (content === null) {
+            const entry = {
+                kind: group.kind,
+                id: rel,
+                source: group.source,
+                ...(group.packageName ? { packageName: group.packageName } : {}),
+                sourceFile: rel,
+                validation: 'error',
+                validationMessage: 'file unreadable',
+            };
+            (entriesByKind[group.kind] ??= []).push(entry);
+            entries.push(entry);
+            return;
+        }
+        const extracted = extractIdsFromFile(content);
+        if (extracted.length === 0) {
+            const entry = {
+                kind: group.kind,
+                id: rel,
+                source: group.source,
+                ...(group.packageName ? { packageName: group.packageName } : {}),
+                sourceFile: rel,
+                validation: 'warning',
+                validationMessage: 'no `id:` extracted; loader may still see entries',
+                extractionMode: 'file-only',
+                confidence: 'low',
+            };
+            (entriesByKind[group.kind] ??= []).push(entry);
+            entries.push(entry);
+            return;
+        }
+        // Skip regex entries whose (kind, packageName||local, id) triple
+        // already came in through the structural loader. This dedupes the same
+        // logical pack contribution reachable from multiple physical paths
+        // (e.g. `node_modules/@example/sharkcraft-pack/...` vs the dev source).
+        const idsHandled = structural?.structuralIds.get(group.kind);
+        const groupPkg = group.packageName ?? '__local__';
+        for (const ex of extracted) {
+            if (idsHandled && idsHandled.has(`${groupPkg}:${ex.id}`))
+                continue;
+            const entry = {
+                kind: group.kind,
+                id: ex.id,
+                ...(ex.title ? { title: ex.title } : {}),
+                source: group.source,
+                ...(group.packageName ? { packageName: group.packageName } : {}),
+                sourceFile: rel,
+                validation: 'ok',
+                // Regex-based id extraction can pick up nested step.id / anchor.id /
+                // ref.id values. Tag these entries clearly so the conflict detector
+                // downgrades same-file collisions to info. The structural loader is
+                // preferred where available; this fallback fires only for kinds
+                // without a dedicated registry.
+                extractionMode: 'regex-fallback',
+                confidence: 'medium',
+            };
+            (entriesByKind[group.kind] ??= []).push(entry);
+            entries.push(entry);
+        }
+    };
+    for (const group of fileGroups) {
+        for (const f of group.files)
+            ingestFile(group, f);
+    }
+    const totals = {};
+    for (const [kind, list] of Object.entries(entriesByKind))
+        totals[kind] = list.length;
+    const conflicts = [];
+    for (const [kind, list] of Object.entries(entriesByKind)) {
+        const byId = new Map();
+        for (const e of list) {
+            const arr = byId.get(e.id) ?? [];
+            arr.push(e);
+            byId.set(e.id, arr);
+        }
+        for (const [id, arr] of byId) {
+            if (arr.length < 2)
+                continue;
+            const sourceVariants = new Set(arr.map((e) => e.source));
+            const conflictKind = sourceVariants.size > 1
+                ? ConflictKind.DuplicateIdDifferentSource
+                : ConflictKind.DuplicateIdSameKind;
+            // If a local entry shadows a pack entry, mark it as shadowed pack/local
+            // (informational; the loader behavior is documented per-kind).
+            const hasLocal = arr.some((e) => e.source === ContributionSource.Local);
+            const hasPack = arr.some((e) => e.source === ContributionSource.Pack);
+            if (hasLocal && hasPack) {
+                conflicts.push({
+                    kind: ConflictKind.ShadowedPackConfig,
+                    contributionKind: kind,
+                    id,
+                    sources: arr.map((e) => {
+                        const src = {
+                            source: e.source,
+                        };
+                        if (e.packageName)
+                            src.packageName = e.packageName;
+                        if (e.sourceFile)
+                            src.sourceFile = e.sourceFile;
+                        return src;
+                    }),
+                    severity: 'info',
+                    message: `Local "${kind}" "${id}" shadows pack contribution. Local entries win on duplicate ids.`,
+                });
+            }
+            else {
+                // Downgrade conflicts that come from a single source file
+                // when ALL participating entries are regex-fallback extractions.
+                // These are almost certainly nested `id:` fields (e.g.
+                // playbook.steps[].id, pipeline.steps[].id) masquerading as
+                // separate top-level contribution ids.
+                const allRegexFallback = arr.every((e) => e.extractionMode === 'regex-fallback');
+                const sourceFiles = new Set(arr.map((e) => e.sourceFile).filter((s) => Boolean(s)));
+                const singleSourceFile = sourceFiles.size === 1;
+                const nestedIdFalsePositive = allRegexFallback && singleSourceFile;
+                conflicts.push({
+                    kind: conflictKind,
+                    contributionKind: kind,
+                    id,
+                    sources: arr.map((e) => {
+                        const src = {
+                            source: e.source,
+                        };
+                        if (e.packageName)
+                            src.packageName = e.packageName;
+                        if (e.sourceFile)
+                            src.sourceFile = e.sourceFile;
+                        return src;
+                    }),
+                    severity: nestedIdFalsePositive ? 'info' : 'error',
+                    message: nestedIdFalsePositive
+                        ? `${arr.length} "${kind}" entries with id "${id}" extracted from a single source file via regex fallback — likely nested step.id fields, not real top-level duplicates.`
+                        : `Duplicate "${kind}" id "${id}" loaded from ${arr.length} sources.`,
+                    nextCommand: `shrk packs contributions --json | jq '.entries[] | select(.id=="${id}" and .kind=="${kind}")'`,
+                });
+            }
+        }
+    }
+    // Stale-signature warning: surfaced as a conflict so a single doctor view
+    // can highlight unsigned-by-secret manifests.
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const sig = pack.manifest?.signature;
+        if (!sig)
+            continue;
+        // The loader already validates HMAC strictly; we only surface stale
+        // when the manifest content has obviously been edited without re-signing.
+        // Heuristic: signature timestamp older than any contribution file mtime.
+        let staleSummary = null;
+        try {
+            const sigMs = new Date(sig.signedAt).getTime();
+            const contributions = pack.manifest?.contributions ?? {};
+            for (const slot of Object.values(KIND_TO_SLOT)) {
+                const rels = contributions[slot] ?? [];
+                for (const rel of rels) {
+                    const abs = nodePath.resolve(pack.packageRoot, rel);
+                    try {
+                        const stat = statSync(abs);
+                        if (stat.mtimeMs > sigMs + 1000) {
+                            staleSummary = `${rel} (mtime ${new Date(stat.mtimeMs).toISOString()}) is newer than signature (${sig.signedAt})`;
+                            break;
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                if (staleSummary)
+                    break;
+            }
+        }
+        catch {
+            // ignore
+        }
+        if (staleSummary) {
+            conflicts.push({
+                kind: ConflictKind.StaleSignature,
+                contributionKind: ContributionKind.Docs,
+                id: pack.packageName,
+                sources: [{ source: ContributionSource.Pack, packageName: pack.packageName, sourceFile: pack.packageRoot }],
+                severity: 'warning',
+                message: `Pack ${pack.packageName} signature is stale: ${staleSummary}`,
+                nextCommand: `SHARKCRAFT_PACK_SECRET=<secret> shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`,
+            });
+        }
+    }
+    return {
+        schema: PACK_CONTRIBUTIONS_INVENTORY_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        projectRoot: inspection.projectRoot,
+        entriesByKind,
+        totals,
+        entries,
+        conflicts,
+        packs: (inspection.packs.validPacks ?? []).map((p) => ({
+            name: p.packageName,
+            version: p.packageVersion,
+            root: p.packageRoot,
+            signaturePresent: Boolean(p.manifest?.signature),
+        })),
+    };
+}
+export function renderInventoryText(inv) {
+    const lines = [];
+    lines.push(`=== Pack contributions inventory (${inv.entries.length} entries) ===`);
+    lines.push(`  generatedAt   ${inv.generatedAt}`);
+    lines.push(`  packs         ${inv.packs.length}`);
+    for (const p of inv.packs)
+        lines.push(`    • ${p.name}@${p.version} (sig: ${p.signaturePresent ? 'present' : 'absent'})`);
+    lines.push('');
+    lines.push(`By kind:`);
+    for (const [k, n] of Object.entries(inv.totals).sort())
+        lines.push(`  ${k.padEnd(28)} ${n}`);
+    lines.push('');
+    if (inv.conflicts.length > 0) {
+        lines.push(`Conflicts (${inv.conflicts.length}):`);
+        for (const c of inv.conflicts.slice(0, 50)) {
+            lines.push(`  ${c.severity.padEnd(7)} [${c.kind}] ${c.contributionKind} "${c.id}" — ${c.message}`);
+            if (c.nextCommand)
+                lines.push(`         next: ${c.nextCommand}`);
+        }
+    }
+    else {
+        lines.push('No conflicts detected.');
+    }
+    return lines.join('\n') + '\n';
+}
+export function renderInventoryMarkdown(inv) {
+    const lines = [];
+    lines.push('# Pack contributions inventory');
+    lines.push('');
+    lines.push(`- generatedAt: ${inv.generatedAt}`);
+    lines.push(`- packs: ${inv.packs.length}`);
+    for (const p of inv.packs) {
+        lines.push(`  - **${p.name}** \`${p.version}\` (signature ${p.signaturePresent ? 'present' : 'absent'})`);
+    }
+    lines.push('');
+    lines.push('## By kind');
+    lines.push('| Kind | Count |');
+    lines.push('| --- | --- |');
+    for (const [k, n] of Object.entries(inv.totals).sort())
+        lines.push(`| \`${k}\` | ${n} |`);
+    lines.push('');
+    lines.push('## Conflicts');
+    if (inv.conflicts.length === 0) {
+        lines.push('None.');
+    }
+    else {
+        lines.push('| Severity | Kind | Contribution | Id | Message |');
+        lines.push('| --- | --- | --- | --- | --- |');
+        for (const c of inv.conflicts) {
+            lines.push(`| ${c.severity} | \`${c.kind}\` | \`${c.contributionKind}\` | \`${c.id}\` | ${c.message} |`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+export function selectConflicts(inv) {
+    return inv.conflicts;
+}