@shrkcrft/inspector 0.1.0-alpha.2

package/dist/pack-release-check.js

@@ -0,0 +1,258 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { validatePackManifest } from '@shrkcrft/plugin-api';
+export const PACK_RELEASE_CHECK_SCHEMA = 'sharkcraft.pack-release-check/v1';
+function findManifest(packPath) {
+    const pkgFile = nodePath.join(packPath, 'package.json');
+    if (!existsSync(pkgFile))
+        return { manifestFile: null, pkgFile: null };
+    let pkg = {};
+    try {
+        pkg = JSON.parse(readFileSync(pkgFile, 'utf8'));
+    }
+    catch {
+        /* ignore */
+    }
+    const rel = pkg.sharkcraft?.manifest;
+    if (!rel)
+        return { manifestFile: null, pkgFile };
+    const manifestFile = nodePath.resolve(packPath, rel);
+    return { manifestFile: existsSync(manifestFile) ? manifestFile : null, pkgFile };
+}
+async function loadManifest(file) {
+    try {
+        if (file.endsWith('.json')) {
+            return JSON.parse(readFileSync(file, 'utf8'));
+        }
+        const { pathToFileURL } = await import('node:url');
+        const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+        return mod.default ?? mod.manifest ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function checkFilesWhitelist(pkgFile, manifestFile) {
+    let pkg = {};
+    try {
+        pkg = JSON.parse(readFileSync(pkgFile, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!pkg.files || pkg.files.length === 0) {
+        return {
+            code: 'no-files-whitelist',
+            severity: 'warning',
+            message: 'package.json has no "files" whitelist — all files will be published.',
+            suggestedFix: 'Add a "files" array to your package.json so publishes ship only the assets you intend.',
+            suggestedCommand: 'jq \'.files = ["dist", "src/assets/**", "src/sharkcraft.plugin.signed.json"]\' package.json > package.json.tmp && mv package.json.tmp package.json',
+            file: pkgFile,
+        };
+    }
+    if (manifestFile) {
+        const rel = nodePath.relative(nodePath.dirname(pkgFile), manifestFile).split(nodePath.sep).join('/');
+        // The signed manifest needs to ship; check if the patterns cover it.
+        const covered = pkg.files.some((p) => {
+            if (p === rel)
+                return true;
+            const segment = p.split('/')[0];
+            return rel.startsWith(segment);
+        });
+        if (!covered) {
+            return {
+                code: 'manifest-not-in-files',
+                severity: 'warning',
+                message: `Signed manifest "${rel}" is not covered by package.json "files".`,
+                suggestedFix: `Add "${rel}" (or its directory prefix) to package.json files[] so the signed manifest ships with the pack.`,
+                suggestedCommand: `# Edit package.json: ensure "files" contains "${rel}" or its parent directory.`,
+                file: pkgFile,
+            };
+        }
+    }
+    return null;
+}
+export async function runPackReleaseCheck(packPath) {
+    const findings = [];
+    const absPath = nodePath.resolve(packPath);
+    if (!existsSync(absPath)) {
+        findings.push({
+            code: 'pack-not-found',
+            severity: 'error',
+            message: `Pack path does not exist: ${absPath}`,
+        });
+        return {
+            schema: PACK_RELEASE_CHECK_SCHEMA,
+            packPath: absPath,
+            manifestFile: null,
+            packageJsonFile: null,
+            contributionsFound: 0,
+            findings,
+            passed: false,
+        };
+    }
+    const { manifestFile, pkgFile } = findManifest(absPath);
+    if (!pkgFile) {
+        findings.push({
+            code: 'no-package-json',
+            severity: 'error',
+            message: 'No package.json found at pack path.',
+        });
+        return {
+            schema: PACK_RELEASE_CHECK_SCHEMA,
+            packPath: absPath,
+            manifestFile: null,
+            packageJsonFile: null,
+            contributionsFound: 0,
+            findings,
+            passed: false,
+        };
+    }
+    if (!manifestFile) {
+        findings.push({
+            code: 'no-manifest',
+            severity: 'error',
+            message: 'package.json sharkcraft.manifest is missing or points at a non-existent file.',
+            suggestedFix: 'Sign the manifest with `shrk packs sign` and reference the .signed.json in package.json.',
+            suggestedCommand: 'shrk packs sign <path-to-pack> --verify-after-sign',
+            file: pkgFile,
+        });
+        return {
+            schema: PACK_RELEASE_CHECK_SCHEMA,
+            packPath: absPath,
+            manifestFile: null,
+            packageJsonFile: pkgFile,
+            contributionsFound: 0,
+            findings,
+            passed: false,
+        };
+    }
+    const manifest = await loadManifest(manifestFile);
+    if (!manifest) {
+        findings.push({
+            code: 'manifest-load-failed',
+            severity: 'error',
+            message: `Failed to load manifest file: ${manifestFile}`,
+            suggestedFix: 'Check the manifest exports a `definePackManifest({...})` default export and parses as JSON / TypeScript without errors.',
+            file: manifestFile,
+        });
+        return {
+            schema: PACK_RELEASE_CHECK_SCHEMA,
+            packPath: absPath,
+            manifestFile,
+            packageJsonFile: pkgFile,
+            contributionsFound: 0,
+            findings,
+            passed: false,
+        };
+    }
+    const validation = validatePackManifest(manifest);
+    if (!validation.valid) {
+        for (const i of validation.issues) {
+            findings.push({
+                code: `manifest-invalid:${i.field}`,
+                severity: 'error',
+                message: i.message,
+            });
+        }
+    }
+    // Contribution file existence + load.
+    let contributionsFound = 0;
+    const c = manifest.contributions ?? {};
+    const allBuckets = [
+        'knowledgeFiles',
+        'ruleFiles',
+        'pathFiles',
+        'templateFiles',
+        'pipelineFiles',
+        'docsFiles',
+        'presetFiles',
+        'boundaryFiles',
+        'contextTestFiles',
+        'agentTestFiles',
+        'scaffoldPatternFiles',
+        'policyCheckFiles',
+        'constructFiles',
+        'constructFacetFiles',
+        'playbookFiles',
+        'searchTuningFiles',
+    ];
+    for (const key of allBuckets) {
+        const list = c[key];
+        if (!list || list.length === 0)
+            continue;
+        for (const rel of list) {
+            const full = nodePath.resolve(absPath, rel);
+            if (!existsSync(full)) {
+                findings.push({
+                    code: 'contribution-missing',
+                    severity: 'error',
+                    message: `${key} entry "${rel}" missing at ${full}.`,
+                    suggestedFix: `Either restore the file under ${absPath}/${rel} or remove it from manifest.contributions.${key}.`,
+                    file: full,
+                });
+            }
+            else {
+                contributionsFound += 1;
+                // Try to import to catch parse errors. Skip docs/markdown.
+                if (/\.(ts|js|mjs|cjs)$/.test(rel)) {
+                    try {
+                        const { pathToFileURL } = await import('node:url');
+                        await import(__rewriteRelativeImportExtension(pathToFileURL(full).href));
+                    }
+                    catch (e) {
+                        const message = e.message;
+                        const helperMissing = /does not provide an export named|is not exported by|has no exported member|not a function/i.test(message);
+                        findings.push({
+                            code: helperMissing ? 'contribution-helper-missing' : 'contribution-load-failed',
+                            severity: 'error',
+                            message: `${key} entry "${rel}" failed to load: ${message}`,
+                            file: full,
+                            ...(helperMissing
+                                ? {
+                                    suggestedFix: 'The consumer\'s @shrkcrft/plugin-api version is missing a helper this contribution uses. Either bump the dependency, declare a `peerDependencies."@shrkcrft/plugin-api"` range that includes the helper, or rewrite the contribution as a structural object literal.',
+                                    suggestedCommand: 'shrk packs compat <path-to-pack>',
+                                }
+                                : {
+                                    suggestedFix: 'Open the file and resolve the import or runtime error. Use `bun run packages/inspector/src/__tests__/load-pack.ts <file>` to reproduce.',
+                                }),
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Signature presence.
+    if (!manifest.signature) {
+        findings.push({
+            code: 'unsigned-manifest',
+            severity: 'warning',
+            message: 'Manifest has no HMAC signature. Adopters who run `shrk packs verify` will see signature status "missing-signature".',
+            suggestedFix: 'Run `shrk packs sign <manifest.ts> --output ...signed.json` with SHARKCRAFT_PACK_SECRET set.',
+            suggestedCommand: 'shrk packs sign ' + manifestFile + ' --verify-after-sign',
+            file: manifestFile,
+        });
+    }
+    // Files whitelist sanity.
+    const filesFinding = checkFilesWhitelist(pkgFile, manifestFile);
+    if (filesFinding)
+        findings.push(filesFinding);
+    const passed = findings.every((f) => f.severity !== 'error');
+    return {
+        schema: PACK_RELEASE_CHECK_SCHEMA,
+        packPath: absPath,
+        manifestFile,
+        packageJsonFile: pkgFile,
+        contributionsFound,
+        findings,
+        passed,
+    };
+}

package/dist/pack-signature-status.d.ts

@@ -0,0 +1,72 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const PACK_SIGNATURE_STATUS_SCHEMA = "sharkcraft.pack-signature-status/v1";
+export declare enum PackSignatureStatusKind {
+    Present = "present",
+    Stale = "stale",
+    Missing = "missing"
+}
+export interface IPackSignatureEntry {
+    readonly packageName: string;
+    readonly packageVersion: string;
+    readonly packageRoot: string;
+    readonly status: PackSignatureStatusKind;
+    readonly signatureSignedAt?: string;
+    readonly reason?: string;
+    readonly newerContributionFile?: string;
+    readonly newerContributionMtime?: string;
+    readonly secretAvailable: boolean;
+    readonly nextCommand?: string;
+    /**
+     * True when the pack's signature was produced by the dev/local
+     * signing flow (`shrk packs sign --dev`). Dev signatures verify but are
+     * NOT release-trusted; release apply paths reject them unless explicitly
+     * allowed.
+     */
+    readonly dev?: boolean;
+}
+export interface IPackSignatureStatusReport {
+    readonly schema: typeof PACK_SIGNATURE_STATUS_SCHEMA;
+    readonly generatedAt: string;
+    readonly packs: readonly IPackSignatureEntry[];
+    readonly summary: {
+        readonly total: number;
+        readonly present: number;
+        readonly stale: number;
+        readonly missing: number;
+        /** Packs whose latest signature is dev-only (subset of `present`). */
+        readonly dev: number;
+    };
+    readonly secretAvailable: boolean;
+    readonly nextCommands: readonly string[];
+}
+export declare function buildPackSignatureStatusReport(inspection: ISharkcraftInspection): IPackSignatureStatusReport;
+/**
+ * Pack signature explanation. Surfaces the distinct lifecycle
+ * states (`unsigned`, `stale`, `invalid`, `valid`, `secret-missing`,
+ * `not-required`) per pack with a one-line "why this matters".
+ *
+ * Read-only. Reads `inspection.packs.discoveredPacks[i].signatureStatus`
+ * which already reflects the verifier's outcome when the inspector was
+ * constructed with `verifyPackSignatures: true`.
+ */
+export type PackSignatureExplainState = 'valid' | 'unsigned' | 'stale' | 'invalid' | 'secret-missing' | 'not-required' | 'unknown';
+export interface IPackSignatureExplainEntry {
+    readonly packageName: string;
+    readonly packageVersion: string;
+    readonly packageRoot: string;
+    readonly state: PackSignatureExplainState;
+    readonly explanation: string;
+    readonly nextCommand?: string;
+}
+export interface IPackSignatureExplainReport {
+    readonly schema: 'sharkcraft.pack-signature-explain/v1';
+    readonly generatedAt: string;
+    readonly secretAvailable: boolean;
+    readonly mode: 'required' | 'optional';
+    readonly packs: readonly IPackSignatureExplainEntry[];
+}
+export interface IExplainPackSignatureStatusOptions {
+    requireSignatures?: boolean;
+}
+export declare function explainPackSignatureStatus(inspection: ISharkcraftInspection, options?: IExplainPackSignatureStatusOptions): IPackSignatureExplainReport;
+//# sourceMappingURL=pack-signature-status.d.ts.map

package/dist/pack-signature-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-signature-status.d.ts","sourceRoot":"","sources":["../src/pack-signature-status.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,4BAA4B,wCAAwC,CAAC;AAElF,oBAAY,uBAAuB;IACjC,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,OAAO,4BAA4B,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,sEAAsE;QACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAgCD,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,qBAAqB,GAChC,0BAA0B,CA6F5B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,yBAAyB,GACjC,OAAO,GACP,UAAU,GACV,OAAO,GACP,SAAS,GACT,gBAAgB,GAChB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,yBAAyB,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,EAAE,sCAAsC,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACvD;AAED,MAAM,WAAW,kCAAkC;IACjD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,kCAAuC,GAC/C,2BAA2B,CA6D7B"}

package/dist/pack-signature-status.js

@@ -0,0 +1,222 @@
+/**
+ * Pack signature freshness inspector.
+ *
+ * Reports each discovered pack's signature state without ever computing or
+ * faking HMAC. Surfaces three statuses:
+ *
+ *   present       — manifest has a signature and the timestamp is >= any
+ *                   contribution file mtime we can see (heuristic — real
+ *                   HMAC validation happens in pack-doctor).
+ *   stale         — manifest has a signature but at least one contribution
+ *                   file has a newer mtime than the signature timestamp.
+ *   missing       — manifest has no signature block.
+ *
+ * The check is deterministic, read-only, and never requires the pack secret.
+ */
+import { existsSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const PACK_SIGNATURE_STATUS_SCHEMA = 'sharkcraft.pack-signature-status/v1';
+export var PackSignatureStatusKind;
+(function (PackSignatureStatusKind) {
+    PackSignatureStatusKind["Present"] = "present";
+    PackSignatureStatusKind["Stale"] = "stale";
+    PackSignatureStatusKind["Missing"] = "missing";
+})(PackSignatureStatusKind || (PackSignatureStatusKind = {}));
+const CONTRIB_SLOTS = [
+    'knowledgeFiles',
+    'ruleFiles',
+    'pathFiles',
+    'pathConventionFiles',
+    'templateFiles',
+    'pipelineFiles',
+    'presetFiles',
+    'boundaryFiles',
+    'contextTestFiles',
+    'agentTestFiles',
+    'scaffoldPatternFiles',
+    'policyCheckFiles',
+    'constructFiles',
+    'constructFacetFiles',
+    'playbookFiles',
+    'searchTuningFiles',
+    'feedbackRuleFiles',
+    'decisionFiles',
+    'mcpToolFiles',
+    'aiProviderFiles',
+    'docsFiles',
+    'pluginLifecycleProfileFiles',
+    'contractTemplateFiles',
+    'migrationProfileFiles',
+    'conventionFiles',
+    'helperFiles',
+    'taskRoutingHintFiles',
+];
+export function buildPackSignatureStatusReport(inspection) {
+    const secret = Boolean(process.env['SHARKCRAFT_PACK_SECRET']);
+    const out = [];
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const sig = pack.manifest?.signature;
+        if (!sig) {
+            out.push({
+                packageName: pack.packageName,
+                packageVersion: pack.packageVersion,
+                packageRoot: pack.packageRoot,
+                status: PackSignatureStatusKind.Missing,
+                reason: 'no signature block on manifest',
+                secretAvailable: secret,
+                nextCommand: secret
+                    ? `shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`
+                    : `SHARKCRAFT_PACK_SECRET=<secret> shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`,
+            });
+            continue;
+        }
+        const sigMs = (() => {
+            try {
+                return new Date(sig.signedAt).getTime();
+            }
+            catch {
+                return 0;
+            }
+        })();
+        let newerFile;
+        let newerMtime;
+        const contributions = (pack.manifest?.contributions ?? {});
+        for (const slot of CONTRIB_SLOTS) {
+            const rels = contributions[slot];
+            if (!rels)
+                continue;
+            for (const rel of rels) {
+                const abs = nodePath.resolve(pack.packageRoot, rel);
+                if (!existsSync(abs))
+                    continue;
+                try {
+                    const st = statSync(abs);
+                    if (st.mtimeMs > sigMs + 1000) {
+                        newerFile = rel;
+                        newerMtime = new Date(st.mtimeMs).toISOString();
+                        break;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (newerFile)
+                break;
+        }
+        if (newerFile) {
+            out.push({
+                packageName: pack.packageName,
+                packageVersion: pack.packageVersion,
+                packageRoot: pack.packageRoot,
+                status: PackSignatureStatusKind.Stale,
+                signatureSignedAt: sig.signedAt,
+                reason: `contribution file "${newerFile}" mtime (${newerMtime}) is newer than signature (${sig.signedAt})`,
+                newerContributionFile: newerFile,
+                newerContributionMtime: newerMtime,
+                secretAvailable: secret,
+                nextCommand: secret
+                    ? `shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`
+                    : `SHARKCRAFT_PACK_SECRET=<secret> shrk packs sign ${nodePath.relative(inspection.projectRoot, pack.packageRoot)}`,
+            });
+        }
+        else {
+            out.push({
+                packageName: pack.packageName,
+                packageVersion: pack.packageVersion,
+                packageRoot: pack.packageRoot,
+                status: PackSignatureStatusKind.Present,
+                signatureSignedAt: sig.signedAt,
+                secretAvailable: secret,
+                ...(sig.dev === true ? { dev: true } : {}),
+            });
+        }
+    }
+    return {
+        schema: PACK_SIGNATURE_STATUS_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        packs: out,
+        summary: {
+            total: out.length,
+            present: out.filter((p) => p.status === PackSignatureStatusKind.Present).length,
+            stale: out.filter((p) => p.status === PackSignatureStatusKind.Stale).length,
+            missing: out.filter((p) => p.status === PackSignatureStatusKind.Missing).length,
+            dev: out.filter((p) => p.dev === true).length,
+        },
+        secretAvailable: secret,
+        nextCommands: out
+            .filter((p) => p.nextCommand)
+            .map((p) => p.nextCommand)
+            .filter((c, i, a) => a.indexOf(c) === i),
+    };
+}
+export function explainPackSignatureStatus(inspection, options = {}) {
+    const secretAvailable = Boolean(process.env['SHARKCRAFT_PACK_SECRET']);
+    const mode = options.requireSignatures ? 'required' : 'optional';
+    const freshness = buildPackSignatureStatusReport(inspection);
+    const freshnessByRoot = new Map(freshness.packs.map((p) => [p.packageRoot, p]));
+    const out = [];
+    for (const pack of inspection.packs.discoveredPacks ?? []) {
+        const fresh = freshnessByRoot.get(pack.packageRoot);
+        const verifier = pack.signatureStatus;
+        const rel = nodePathRelative(inspection.projectRoot, pack.packageRoot);
+        const signCmd = secretAvailable
+            ? `shrk packs sign ${rel}`
+            : `SHARKCRAFT_PACK_SECRET=<secret> shrk packs sign ${rel}`;
+        let state = 'unknown';
+        let explanation = '';
+        let nextCommand;
+        if (verifier === 'verified') {
+            state = 'valid';
+            explanation = 'HMAC verified at inspection time.';
+        }
+        else if (verifier === 'invalid-signature') {
+            state = 'invalid';
+            explanation = 'Manifest signature failed HMAC verification — pack contents may have been tampered with.';
+            nextCommand = 'shrk packs verify --required';
+        }
+        else if (verifier === 'missing-signature' || (!verifier && fresh?.status === 'missing')) {
+            state = 'unsigned';
+            explanation = 'Manifest has no signature block.';
+            nextCommand = signCmd;
+        }
+        else if (verifier === 'missing-secret' || (!verifier && !secretAvailable && fresh?.status !== 'present')) {
+            state = 'secret-missing';
+            explanation = 'SHARKCRAFT_PACK_SECRET is unset; cannot verify or re-sign in this session.';
+            nextCommand = signCmd;
+        }
+        else if (fresh?.status === 'stale') {
+            state = 'stale';
+            explanation = `${fresh.reason ?? 'Signature is older than at least one contribution file.'}`;
+            nextCommand = signCmd;
+        }
+        else if (fresh?.status === 'present') {
+            state = 'valid';
+            explanation = 'Signature timestamp is newer than every contribution file.';
+        }
+        else {
+            state = mode === 'required' ? 'unknown' : 'not-required';
+            explanation = mode === 'required'
+                ? 'Verifier did not run; rerun with --verify-signatures.'
+                : 'Signatures are not required in this run.';
+        }
+        out.push({
+            packageName: pack.packageName,
+            packageVersion: pack.packageVersion,
+            packageRoot: pack.packageRoot,
+            state,
+            explanation,
+            ...(nextCommand ? { nextCommand } : {}),
+        });
+    }
+    return {
+        schema: 'sharkcraft.pack-signature-explain/v1',
+        generatedAt: new Date().toISOString(),
+        secretAvailable,
+        mode,
+        packs: out,
+    };
+}
+function nodePathRelative(from, to) {
+    return nodePath.relative(from, to) || '.';
+}

package/dist/pack-symbol-compat.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Plugin-api symbol compatibility diff.
+ *
+ * Reads `import { … } from '@shrkcrft/plugin-api'` lines from each pack
+ * contribution file, resolves the consumer's installed plugin-api source,
+ * and reports which symbols the pack uses that the consumer's plugin-api
+ * does not export.
+ *
+ * This is intentionally a regex/structural parser — we do not depend on
+ * the TypeScript compiler. The goal is to catch the dominant failure
+ * mode (`Export named 'X' not found in module '@shrkcrft/plugin-api'`)
+ * before publish, not to be a full module-graph analyser.
+ */
+export declare const PACK_SYMBOL_COMPAT_SCHEMA = "sharkcraft.pack-symbol-compat/v1";
+export interface IPluginApiImport {
+    /** Absolute path to the pack contribution file. */
+    file: string;
+    /** Specifier exactly as it appears in the import statement. */
+    importedSymbols: readonly string[];
+}
+export interface IPackSymbolCompatFinding {
+    /** Symbol the pack imports. */
+    symbol: string;
+    /** Where the symbol is used. */
+    files: readonly string[];
+    status: 'available' | 'missing';
+}
+export type PackSymbolSourceMode = 'source' | 'declaration' | 'dist-js' | 'fallback' | 'none';
+export type PackSymbolConfidence = 'high' | 'medium' | 'low';
+export interface IPackSymbolCompatReport {
+    schema: typeof PACK_SYMBOL_COMPAT_SCHEMA;
+    packPath: string;
+    consumerRoot: string | null;
+    pluginApiSource: string | null;
+    pluginApiResolution: 'consumer-node-modules' | 'consumer-symlink' | 'pack-node-modules' | 'not-found';
+    availableSymbols: readonly string[];
+    findings: readonly IPackSymbolCompatFinding[];
+    /** Convenience: symbols the pack uses that are missing from the consumer. */
+    missingSymbols: readonly string[];
+    /** Total imports inspected. */
+    imports: readonly IPluginApiImport[];
+    /** True iff there are no missing symbols. */
+    compatible: boolean;
+    /** Suggested fixes for each missing symbol (best-effort, deterministic). */
+    suggestions: readonly string[];
+    /** How the symbols were discovered. */
+    sourceMode: PackSymbolSourceMode;
+    /** Confidence in the export list. */
+    confidence: PackSymbolConfidence;
+    /** Files inspected when collecting available symbols. */
+    filesInspected: readonly string[];
+}
+export interface IPackSymbolCompatInput {
+    packPath: string;
+    consumerRoot?: string | null;
+    /** Scan dist/*.js patterns even when TS source is present. */
+    distAware?: boolean;
+}
+export declare function checkPackSymbolCompat(input: IPackSymbolCompatInput): IPackSymbolCompatReport;
+//# sourceMappingURL=pack-symbol-compat.d.ts.map

package/dist/pack-symbol-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-symbol-compat.d.ts","sourceRoot":"","sources":["../src/pack-symbol-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,eAAO,MAAM,yBAAyB,qCAAqC,CAAC;AAE5E,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,wBAAwB;IACvC,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAC9F,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE7D,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,yBAAyB,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mBAAmB,EAAE,uBAAuB,GAAG,kBAAkB,GAAG,mBAAmB,GAAG,WAAW,CAAC;IACtG,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC9C,6EAA6E;IAC7E,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACrC,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,4EAA4E;IAC5E,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,uCAAuC;IACvC,UAAU,EAAE,oBAAoB,CAAC;IACjC,qCAAqC;IACrC,UAAU,EAAE,oBAAoB,CAAC;IACjC,yDAAyD;IACzD,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAgPD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAUD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,sBAAsB,GAC5B,uBAAuB,CAqGzB"}