@shrkcrft/inspector 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/pack-asset-freshness.js

@@ -0,0 +1,340 @@
+/**
+ * THE pack-asset freshness authority — divergence by CONTENT, never age.
+ *
+ * Three mtime heuristics used to answer "is this pack stale?" (dev-status:
+ * signed-file mtime vs `src/assets` +500ms; signature-status and the
+ * contributions inventory: `signedAt` vs contribution mtimes +1000ms). They
+ * disagreed in both directions on the same pack, and none of them could see
+ * the case that actually bites: a compiled `dist/*.js` contribution built from
+ * an OLDER `src/*.ts` — shrk serves the previous build while every surface
+ * says OK.
+ *
+ * One question, one answer, from recorded content:
+ *
+ *   - **signature** — `shrk packs sign` records `sha256` of every contribution
+ *     file (and each compiled artifact's mapped source) on the signature
+ *     (`contentDigests`). Fresh iff every recorded file still has that content.
+ *     A signature with no record for a file is `unrecorded` — NOT verified,
+ *     never fresh.
+ *   - **build** — for each compiled contribution with a mapped source on disk,
+ *     the build-time record is the source map's `sourcesContent` (what the
+ *     compiler actually read) or, failing that, the signature's digests of the
+ *     artifact + source pair. Stale iff the source's content differs from the
+ *     record; `unrecorded` when no record exists.
+ *
+ * Consumed by `packs signature-status`, `packs dev-status`, the contributions
+ * inventory's stale-signature conflict, `packs doctor`, `shrk doctor` and the
+ * CLI startup warning — all of them read this function, none recompute it.
+ * Computed on read (never cached on the discovery object, whose cache is keyed
+ * by the lockfile and would itself go stale).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { CONTRIBUTION_FILE_KEYS, FUTURE_CONTRIBUTION_FILE_KEYS, } from '@shrkcrft/plugin-api';
+const COMPILED_EXT = /\.(?:js|mjs|cjs)$/i;
+const BUILD_DIRS = new Set(['dist', 'build', 'lib', 'out']);
+/** `sha256:<hex>` of a file's bytes (or of a string's UTF-8 bytes). */
+export function packContentDigest(content) {
+    return 'sha256:' + createHash('sha256').update(content).digest('hex');
+}
+function toPosix(p) {
+    return p.split(nodePath.sep).join('/');
+}
+function relToPack(packageRoot, abs) {
+    return toPosix(nodePath.relative(packageRoot, abs));
+}
+function digestFile(abs) {
+    try {
+        return packContentDigest(readFileSync(abs));
+    }
+    catch {
+        return null;
+    }
+}
+function readJsonTolerant(file) {
+    try {
+        const raw = readFileSync(file, 'utf8')
+            .replace(/\/\*[\s\S]*?\*\//g, '')
+            .replace(/(^|[^:"'\\])\/\/.*$/gm, '$1')
+            .replace(/,(\s*[}\]])/g, '$1');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Every declared contribution file that exists, pack-relative, deduped, sorted. */
+function contributionFiles(packageRoot, manifest) {
+    const out = new Set();
+    const contributions = (manifest?.contributions ?? {});
+    for (const key of [...CONTRIBUTION_FILE_KEYS, ...FUTURE_CONTRIBUTION_FILE_KEYS]) {
+        for (const rel of contributions[key] ?? []) {
+            if (typeof rel !== 'string' || rel.length === 0)
+                continue;
+            const abs = nodePath.resolve(packageRoot, rel);
+            if (existsSync(abs))
+                out.add(relToPack(packageRoot, abs));
+        }
+    }
+    return [...out].sort();
+}
+function sourceExtensionsFor(artifactExt) {
+    if (artifactExt === '.mjs')
+        return ['.mts', '.ts'];
+    if (artifactExt === '.cjs')
+        return ['.cts', '.ts'];
+    return ['.ts', '.tsx'];
+}
+/**
+ * The source a compiled artifact was built from: tsconfig `outDir` → `rootDir`
+ * (or `src` / `.` when `rootDir` is unset), else the `dist|build|lib|out` →
+ * `src` convention. `null` when no candidate exists on disk.
+ */
+function mapCompiledSource(packageRoot, artifactRel) {
+    const ext = nodePath.extname(artifactRel).toLowerCase();
+    const stem = artifactRel.slice(0, -ext.length);
+    const candidates = [];
+    const tsconfig = readJsonTolerant(nodePath.join(packageRoot, 'tsconfig.json'));
+    const co = (tsconfig?.['compilerOptions'] ?? {});
+    if (typeof co.outDir === 'string') {
+        const outDir = toPosix(nodePath.normalize(co.outDir)).replace(/^\.\//, '').replace(/\/$/, '');
+        if (stem.startsWith(outDir + '/')) {
+            const rest = stem.slice(outDir.length + 1);
+            const roots = typeof co.rootDir === 'string'
+                ? [toPosix(nodePath.normalize(co.rootDir)).replace(/^\.\//, '').replace(/\/$/, '')]
+                : ['src', '.'];
+            for (const r of roots)
+                candidates.push(r === '.' || r === '' ? rest : `${r}/${rest}`);
+        }
+    }
+    const [first, ...rest] = stem.split('/');
+    if (first && BUILD_DIRS.has(first) && rest.length > 0)
+        candidates.push(`src/${rest.join('/')}`);
+    for (const c of candidates) {
+        for (const e of sourceExtensionsFor(ext)) {
+            const rel = c + e;
+            if (existsSync(nodePath.join(packageRoot, rel)))
+                return rel;
+        }
+    }
+    return null;
+}
+/** The compiled contributions of a pack and their mapped sources. */
+function compiledArtifacts(packageRoot, files) {
+    return files
+        .filter((f) => COMPILED_EXT.test(f))
+        .map((artifact) => ({ artifact, source: mapCompiledSource(packageRoot, artifact) }));
+}
+/**
+ * The digest the artifact's source map recorded for `sourceRel` at build time
+ * (`sourcesContent`), or null when there is no map or it carries no content.
+ */
+function sourceMapRecordedDigest(packageRoot, artifactRel, sourceRel) {
+    const artifactAbs = nodePath.join(packageRoot, artifactRel);
+    let text;
+    try {
+        text = readFileSync(artifactAbs, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let map = null;
+    let mapDir = nodePath.dirname(artifactAbs);
+    const urlMatch = /\/\/[#@]\s*sourceMappingURL=(\S+)\s*$/m.exec(text.slice(-4096));
+    const url = urlMatch?.[1];
+    try {
+        if (url && url.startsWith('data:')) {
+            const b64 = url.slice(url.indexOf(',') + 1);
+            map = JSON.parse(Buffer.from(b64, 'base64').toString('utf8'));
+        }
+        else {
+            const mapAbs = url ? nodePath.resolve(mapDir, url) : `${artifactAbs}.map`;
+            if (existsSync(mapAbs)) {
+                map = JSON.parse(readFileSync(mapAbs, 'utf8'));
+                mapDir = nodePath.dirname(mapAbs);
+            }
+        }
+    }
+    catch {
+        map = null;
+    }
+    if (!map || !Array.isArray(map.sources) || !Array.isArray(map.sourcesContent))
+        return null;
+    const sourceAbs = nodePath.join(packageRoot, sourceRel);
+    const root = typeof map.sourceRoot === 'string' ? map.sourceRoot : '';
+    for (let i = 0; i < map.sources.length; i += 1) {
+        const s = map.sources[i];
+        const content = map.sourcesContent[i];
+        if (typeof s !== 'string' || typeof content !== 'string')
+            continue;
+        const cleaned = s.replace(/^(?:file|webpack):\/+/, s.startsWith('file://') ? '/' : '');
+        if (nodePath.resolve(mapDir, root, cleaned) === sourceAbs)
+            return packContentDigest(content);
+    }
+    return null;
+}
+/**
+ * The content record `shrk packs sign` stores on the signature: every
+ * contribution file plus each compiled artifact's mapped source. The SAME
+ * enumeration {@link detectPackAssetFreshness} compares against — one function
+ * records, the other reads, so they cannot disagree about which files count.
+ */
+export function computePackContentDigests(packageRoot, manifest) {
+    const out = {};
+    const files = contributionFiles(packageRoot, manifest);
+    const tracked = new Set(files);
+    for (const a of compiledArtifacts(packageRoot, files))
+        if (a.source)
+            tracked.add(a.source);
+    for (const rel of [...tracked].sort()) {
+        const d = digestFile(nodePath.join(packageRoot, rel));
+        if (d)
+            out[rel] = d;
+    }
+    return out;
+}
+/** True when any contribution is a compiled `.js`/`.mjs`/`.cjs` file (cheap; no hashing). */
+export function packHasCompiledContributions(manifest) {
+    const contributions = (manifest?.contributions ?? {});
+    for (const key of [...CONTRIBUTION_FILE_KEYS, ...FUTURE_CONTRIBUTION_FILE_KEYS]) {
+        if ((contributions[key] ?? []).some((rel) => typeof rel === 'string' && COMPILED_EXT.test(rel)))
+            return true;
+    }
+    return false;
+}
+function rebuildCommandFor(packageRoot) {
+    const pkg = readJsonTolerant(nodePath.join(packageRoot, 'package.json'));
+    const scripts = (pkg?.['scripts'] ?? {});
+    return typeof scripts['build'] === 'string' ? 'npm run build' : null;
+}
+/** Detect one pack's signature + build freshness from recorded content. */
+export function detectPackAssetFreshness(pack) {
+    const { packageRoot, manifest } = pack;
+    const files = contributionFiles(packageRoot, manifest);
+    const artifacts = compiledArtifacts(packageRoot, files);
+    const current = new Map();
+    const digestOf = (rel) => {
+        if (!current.has(rel))
+            current.set(rel, digestFile(nodePath.join(packageRoot, rel)));
+        return current.get(rel) ?? null;
+    };
+    // ── signature ──
+    const sig = manifest?.signature;
+    const recorded = sig?.contentDigests ?? {};
+    const diverged = [];
+    const unrecorded = [];
+    let signatureState = 'unsigned';
+    if (sig) {
+        const checked = new Set([...files, ...artifacts.flatMap((a) => (a.source ? [a.source] : []))]);
+        for (const rel of [...checked].sort()) {
+            const was = recorded[rel];
+            if (was === undefined)
+                unrecorded.push(rel);
+            else if (digestOf(rel) !== was)
+                diverged.push(rel);
+        }
+        // A recorded file that no longer exists diverged too (deleted since signing).
+        for (const rel of Object.keys(recorded).sort()) {
+            if (!checked.has(rel) && !existsSync(nodePath.join(packageRoot, rel)))
+                diverged.push(rel);
+        }
+        signatureState = diverged.length > 0 ? 'diverged' : unrecorded.length > 0 ? 'unrecorded' : 'fresh';
+    }
+    // ── build ──
+    const artifactStates = artifacts.map((a) => {
+        if (!a.source)
+            return { artifact: a.artifact, source: null, state: 'no-source' };
+        const sourceNow = digestOf(a.source);
+        const mapRecord = sourceMapRecordedDigest(packageRoot, a.artifact, a.source);
+        if (mapRecord) {
+            return {
+                artifact: a.artifact,
+                source: a.source,
+                state: mapRecord === sourceNow ? 'fresh' : 'stale',
+                recordedBy: 'source-map',
+            };
+        }
+        const recArtifact = recorded[a.artifact];
+        const recSource = recorded[a.source];
+        if (recArtifact !== undefined && recSource !== undefined && digestOf(a.artifact) === recArtifact) {
+            // The artifact is exactly the signed build; its source must still be the signed source.
+            return {
+                artifact: a.artifact,
+                source: a.source,
+                state: sourceNow === recSource ? 'fresh' : 'stale',
+                recordedBy: 'signature',
+            };
+        }
+        return { artifact: a.artifact, source: a.source, state: 'unrecorded' };
+    });
+    const buildState = artifactStates.length === 0
+        ? 'not-compiled'
+        : artifactStates.some((a) => a.state === 'stale')
+            ? 'stale'
+            : artifactStates.some((a) => a.state === 'unrecorded')
+                ? 'unrecorded'
+                : artifactStates.every((a) => a.state === 'no-source')
+                    ? 'no-source'
+                    : 'fresh';
+    return {
+        packageName: pack.packageName,
+        packageRoot,
+        basis: 'content-digest',
+        signature: {
+            state: signatureState,
+            ...(sig?.signedAt ? { signedAt: sig.signedAt } : {}),
+            dev: sig?.dev === true,
+            diverged,
+            unrecorded,
+        },
+        build: {
+            state: buildState,
+            artifacts: artifactStates,
+            rebuildCommand: artifactStates.length > 0 ? rebuildCommandFor(packageRoot) : null,
+        },
+    };
+}
+function firstWith(f, state) {
+    return f.build.artifacts.find((a) => a.state === state);
+}
+/**
+ * THE wording of a pack's freshness — every surface prints these sentences
+ * rather than composing its own. `undefined` when there is nothing to say.
+ */
+export function describePackAssetFreshness(f) {
+    const out = {};
+    const where = f.build.rebuildCommand ? ` — run \`${f.build.rebuildCommand}\` in ${f.packageRoot}` : '';
+    if (f.build.state === 'stale') {
+        const n = f.build.artifacts.filter((a) => a.state === 'stale').length;
+        const eg = firstWith(f, 'stale');
+        out.build =
+            `pack ${f.packageName}: ${n} compiled artifact(s) differ from their source` +
+                (eg ? ` (e.g. ${eg.artifact} was built from an older ${eg.source})` : '') +
+                ` — shrk is serving the previous build${where || '; rebuild the pack'}`;
+    }
+    else if (f.build.state === 'unrecorded') {
+        const n = f.build.artifacts.filter((a) => a.state === 'unrecorded').length;
+        const eg = firstWith(f, 'unrecorded');
+        out.build =
+            `pack ${f.packageName}: ${n} compiled artifact(s)` +
+                (eg ? ` (e.g. ${eg.artifact})` : '') +
+                ` have no build record, so shrk cannot tell whether they match ${eg?.source ?? 'their source'} — NOT VERIFIED. ` +
+                'Emit source maps with sourcesContent ("sourceMap": true, "inlineSources": true) or record one with `shrk packs sign`.';
+    }
+    if (f.signature.state === 'diverged') {
+        const first = f.signature.diverged[0];
+        const more = f.signature.diverged.length > 1 ? ` (+${f.signature.diverged.length - 1} more)` : '';
+        out.signature =
+            `pack ${f.packageName}: signature is stale — "${first}"${more} changed since it was signed` +
+                (f.signature.signedAt ? ` (${f.signature.signedAt})` : '');
+    }
+    else if (f.signature.state === 'unrecorded') {
+        const first = f.signature.unrecorded[0];
+        const more = f.signature.unrecorded.length > 1 ? ` (+${f.signature.unrecorded.length - 1} more)` : '';
+        out.signature =
+            `pack ${f.packageName}: signature freshness NOT verified — it records no content digest for "${first}"${more} ` +
+                '(signed before content digests existed, or the file was added since); re-sign to record one';
+    }
+    return out;
+}

package/dist/pack-author-ux.d.ts

@@ -2,23 +2,42 @@
  * Pack-author developer UX.
  *
  *  - buildPackDevStatus({ packPath, consumerPath }) — what the consumer sees:
- *    source vs node_modules vs symlink, signed-manifest staleness, contribution
- *    counts.
+ *    source vs node_modules vs symlink, signature + compiled-build freshness
+ *    (from THE pack-asset freshness authority — content digests, never mtimes),
+ *    and the contribution FILES the manifest declares.
  *  - planPackWatchCommand({ packPath, command }) — pure helper that returns
  *    the resolved watch command and the file globs to observe (no spawning
  *    happens here — the CLI command spawns the child).
  */
+import { type IPackAssetFreshness } from './pack-asset-freshness.js';
 export interface IPackDevStatus {
     schema: 'sharkcraft.pack-dev-status/v1';
     packPath: string;
     consumerPath?: string | undefined;
     packExists: boolean;
+    /** The manifest `package.json` `sharkcraft.manifest` points at. */
     manifestPath: string | null;
+    /** The signed manifest (`<manifest>.signed.json`, as `packs sign` writes it), when present. */
     signedManifestPath: string | null;
     packVersion: string | null;
     consumerSeesPackFrom: 'source' | 'node_modules' | 'symlink' | 'not-installed' | 'self';
+    /**
+     * Signature freshness from the one authority: `stale` = a contribution's
+     * content changed since signing; `unknown` = the signature records no
+     * content digests (NOT verified) or the manifest could not be read.
+     */
     signatureStaleness: 'fresh' | 'stale' | 'missing' | 'unknown';
+    /** Pack-relative files whose content changed since signing. */
     staleAssets: ReadonlyArray<string>;
+    /** Compiled-artifact freshness (`dist/*.js` vs its source) from the one authority. */
+    buildStaleness: IPackAssetFreshness['build']['state'] | 'unknown';
+    /** Compiled artifacts built from an older source. */
+    staleArtifacts: ReadonlyArray<string>;
+    /**
+     * Declared contribution FILES per kind, read from the manifest
+     * (`countContributions`) — never a regex count of array entries, which used
+     * to split the default-export text on commas and report nonsense.
+     */
     contributionCounts: Readonly<{
         rules: number;
         paths: number;
@@ -31,13 +50,15 @@ export interface IPackDevStatus {
         constructs: number;
         docsFiles: number;
     }>;
+    /** The full freshness record (null when the manifest could not be read). */
+    freshness: IPackAssetFreshness | null;
     warnings: ReadonlyArray<string>;
     nextCommandHint: string;
 }
 export declare function buildPackDevStatus(input: {
     packPath: string;
     consumerPath?: string;
-}): IPackDevStatus;
+}): Promise<IPackDevStatus>;
 export interface IPackWatchPlan {
     schema: 'sharkcraft.pack-watch-plan/v1';
     packPath: string;

package/dist/pack-author-ux.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack-author-ux.d.ts","sourceRoot":"","sources":["../src/pack-author-ux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,+BAA+B,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oBAAoB,EAAE,QAAQ,GAAG,cAAc,GAAG,SAAS,GAAG,eAAe,GAAG,MAAM,CAAC;IACvF,kBAAkB,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9D,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,kBAAkB,EAAE,QAAQ,CAAC;QAC3B,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;CACzB;AA4ED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,cAAc,CAwFjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,+BAA+B,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,KAAK,CAAC;CACjB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,cAAc,CAYjB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAyBtE"}
+{"version":3,"file":"pack-author-ux.d.ts","sourceRoot":"","sources":["../src/pack-author-ux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,+BAA+B,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,mEAAmE;IACnE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,+FAA+F;IAC/F,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oBAAoB,EAAE,QAAQ,GAAG,cAAc,GAAG,SAAS,GAAG,eAAe,GAAG,MAAM,CAAC;IACvF;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9D,+DAA+D;IAC/D,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,sFAAsF;IACtF,cAAc,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;IAClE,qDAAqD;IACrD,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,kBAAkB,EAAE,QAAQ,CAAC;QAC3B,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,4EAA4E;IAC5E,SAAS,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACtC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;CACzB;AAwDD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,cAAc,CAAC,CA+F1B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,+BAA+B,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,KAAK,CAAC;CACjB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,cAAc,CAYjB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA8BtE"}

package/dist/pack-author-ux.js

@@ -2,14 +2,18 @@
  * Pack-author developer UX.
  *
  *  - buildPackDevStatus({ packPath, consumerPath }) — what the consumer sees:
- *    source vs node_modules vs symlink, signed-manifest staleness, contribution
- *    counts.
+ *    source vs node_modules vs symlink, signature + compiled-build freshness
+ *    (from THE pack-asset freshness authority — content digests, never mtimes),
+ *    and the contribution FILES the manifest declares.
  *  - planPackWatchCommand({ packPath, command }) — pure helper that returns
  *    the resolved watch command and the file globs to observe (no spawning
  *    happens here — the CLI command spawns the child).
  */
-import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative, resolve, sep } from 'node:path';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { countContributions } from '@shrkcrft/packs';
+import { describePackAssetFreshness, detectPackAssetFreshness, } from "./pack-asset-freshness.js";
+import { readPackManifest } from "./pack-manifest-reader.js";
 const WATCHED_GLOBS = Object.freeze([
     'src/assets/**/*.ts',
     'package.json',
@@ -18,6 +22,18 @@ const WATCHED_GLOBS = Object.freeze([
     'README.md',
     'SECURITY.md',
 ]);
+const ZERO_COUNTS = Object.freeze({
+    rules: 0,
+    paths: 0,
+    templates: 0,
+    pipelines: 0,
+    presets: 0,
+    boundaries: 0,
+    knowledge: 0,
+    playbooks: 0,
+    constructs: 0,
+    docsFiles: 0,
+});
 function readJsonSafe(p) {
     try {
         return JSON.parse(readFileSync(p, 'utf8'));
@@ -26,41 +42,6 @@ function readJsonSafe(p) {
         return null;
     }
 }
-function countTsExports(absFile) {
-    if (!existsSync(absFile))
-        return 0;
-    const txt = readFileSync(absFile, 'utf8');
-    // Count default array entries: lines like `  pluginContract,` at brace depth 1.
-    const m = txt.match(/^export default \[([\s\S]*?)\];/m);
-    if (m && m[1]) {
-        return m[1].split(',').filter((s) => s.trim().length > 0).length;
-    }
-    // Fallback: count named exports.
-    const named = txt.match(/^export const /gm);
-    return named ? named.length : 0;
-}
-function walkSourceAssetMtimes(packPath) {
-    const root = join(packPath, 'src', 'assets');
-    let newestMtimeMs = 0;
-    const out = [];
-    if (!existsSync(root))
-        return { newestMtimeMs, files: out };
-    const walk = (dir) => {
-        for (const e of readdirSync(dir, { withFileTypes: true })) {
-            const p = join(dir, e.name);
-            if (e.isDirectory())
-                walk(p);
-            else if (e.isFile() && e.name.endsWith('.ts')) {
-                const st = statSync(p);
-                out.push(p);
-                if (st.mtimeMs > newestMtimeMs)
-                    newestMtimeMs = st.mtimeMs;
-            }
-        }
-    };
-    walk(root);
-    return { newestMtimeMs, files: out };
-}
 function detectConsumerSource(packPath, consumerPath) {
     // Read consumer package.json to find pack name.
     const pkgPath = join(packPath, 'package.json');
@@ -86,7 +67,7 @@ function detectConsumerSource(packPath, consumerPath) {
         return 'self';
     return 'source';
 }
-export function buildPackDevStatus(input) {
+export async function buildPackDevStatus(input) {
     const { packPath } = input;
     const warnings = [];
     if (!existsSync(packPath)) {
@@ -100,79 +81,86 @@ export function buildPackDevStatus(input) {
             consumerSeesPackFrom: 'not-installed',
             signatureStaleness: 'unknown',
             staleAssets: [],
-            contributionCounts: {
-                rules: 0,
-                paths: 0,
-                templates: 0,
-                pipelines: 0,
-                presets: 0,
-                boundaries: 0,
-                knowledge: 0,
-                playbooks: 0,
-                constructs: 0,
-                docsFiles: 0,
-            },
+            buildStaleness: 'unknown',
+            staleArtifacts: [],
+            contributionCounts: ZERO_COUNTS,
+            freshness: null,
             warnings: [`Pack path does not exist: ${packPath}`],
             nextCommandHint: 'shrk packs new <name>',
         };
     }
-    const manifestPath = join(packPath, 'manifest.json');
-    const signedManifestPath = join(packPath, 'sharkcraft.plugin.signed.json');
     const pkg = readJsonSafe(join(packPath, 'package.json'));
+    const loaded = await readPackManifest(packPath);
+    const { manifestPath, signedManifestPath } = loaded;
+    if (loaded.error)
+        warnings.push(`Cannot read the pack manifest: ${loaded.error}. Freshness NOT verified.`);
+    const manifest = loaded.manifest;
+    const c = countContributions(manifest?.contributions);
     const contributionCounts = {
-        rules: countTsExports(join(packPath, 'src/assets/rules.ts')),
-        paths: countTsExports(join(packPath, 'src/assets/paths.ts')),
-        templates: countTsExports(join(packPath, 'src/assets/templates.ts')),
-        pipelines: countTsExports(join(packPath, 'src/assets/pipelines.ts')),
-        presets: countTsExports(join(packPath, 'src/assets/presets.ts')),
-        boundaries: countTsExports(join(packPath, 'src/assets/boundaries.ts')),
-        knowledge: countTsExports(join(packPath, 'src/assets/knowledge.ts')),
-        playbooks: countTsExports(join(packPath, 'src/assets/playbooks.ts')),
-        constructs: countTsExports(join(packPath, 'src/assets/constructs.ts')),
-        docsFiles: 0,
+        rules: c['ruleFiles'] ?? 0,
+        paths: (c['pathFiles'] ?? 0) + (c['pathConventionFiles'] ?? 0),
+        templates: c['templateFiles'] ?? 0,
+        pipelines: c['pipelineFiles'] ?? 0,
+        presets: c['presetFiles'] ?? 0,
+        boundaries: c['boundaryFiles'] ?? 0,
+        knowledge: c['knowledgeFiles'] ?? 0,
+        playbooks: c['playbookFiles'] ?? 0,
+        constructs: c['constructFiles'] ?? 0,
+        docsFiles: c['docsFiles'] ?? 0,
     };
-    let signatureStaleness = 'unknown';
-    const staleAssets = [];
-    if (existsSync(signedManifestPath)) {
-        const sigMtime = statSync(signedManifestPath).mtimeMs;
-        const { newestMtimeMs, files } = walkSourceAssetMtimes(packPath);
-        if (newestMtimeMs > sigMtime + 500) {
-            signatureStaleness = 'stale';
-            for (const f of files) {
-                const st = statSync(f).mtimeMs;
-                if (st > sigMtime + 500)
-                    staleAssets.push(relative(packPath, f));
-            }
-            warnings.push(`Signed manifest is older than ${staleAssets.length} asset file(s). Re-sign with \`shrk packs sign\`.`);
+    const freshness = manifest
+        ? detectPackAssetFreshness({ packageName: pkg?.name ?? basename(packPath), packageRoot: packPath, manifest })
+        : null;
+    const signatureStaleness = !freshness
+        ? 'unknown'
+        : freshness.signature.state === 'unsigned'
+            ? 'missing'
+            : freshness.signature.state === 'diverged'
+                ? 'stale'
+                : freshness.signature.state === 'unrecorded'
+                    ? 'unknown'
+                    : 'fresh';
+    if (freshness) {
+        const said = describePackAssetFreshness(freshness);
+        if (said.signature)
+            warnings.push(said.signature);
+        if (said.build)
+            warnings.push(said.build);
+        if (freshness.signature.state === 'unsigned') {
+            warnings.push('No signed manifest found. Run `shrk packs sign` before publishing.');
         }
-        else {
-            signatureStaleness = 'fresh';
-        }
-    }
-    else {
-        signatureStaleness = 'missing';
-        warnings.push('No signed manifest found. Run `shrk packs sign` before publishing.');
     }
+    const staleArtifacts = freshness
+        ? freshness.build.artifacts.filter((a) => a.state === 'stale').map((a) => a.artifact)
+        : [];
     const consumerPath = input.consumerPath ? resolve(input.consumerPath) : undefined;
     const consumerSeesPackFrom = consumerPath
         ? detectConsumerSource(packPath, consumerPath)
         : 'not-installed';
+    const nextCommandHint = freshness?.build.state === 'stale'
+        ? freshness.build.rebuildCommand
+            ? `(cd ${packPath} && ${freshness.build.rebuildCommand})`
+            : `rebuild ${packPath}`
+        : signatureStaleness === 'stale' || signatureStaleness === 'unknown'
+            ? `shrk packs sign ${packPath}`
+            : `shrk packs doctor --release --cwd ${packPath}`;
     return {
         schema: 'sharkcraft.pack-dev-status/v1',
         packPath,
         consumerPath: consumerPath ?? undefined,
         packExists: true,
-        manifestPath: existsSync(manifestPath) ? manifestPath : null,
-        signedManifestPath: existsSync(signedManifestPath) ? signedManifestPath : null,
+        manifestPath,
+        signedManifestPath,
         packVersion: pkg?.version ?? null,
         consumerSeesPackFrom,
         signatureStaleness,
-        staleAssets,
+        staleAssets: freshness?.signature.diverged ?? [],
+        buildStaleness: freshness?.build.state ?? 'unknown',
+        staleArtifacts,
         contributionCounts,
+        freshness,
         warnings,
-        nextCommandHint: signatureStaleness === 'stale'
-            ? `shrk packs sign --pack ${packPath.split(sep).pop()}`
-            : `shrk packs doctor --release --cwd ${packPath}`,
+        nextCommandHint,
     };
 }
 export function planPackWatchCommand(input) {
@@ -196,14 +184,20 @@ export function renderPackDevStatusText(status) {
         lines.push(`  consumer        ${status.consumerPath}`);
     lines.push(`  version         ${status.packVersion ?? '(unknown)'}`);
     lines.push(`  seen as         ${status.consumerSeesPackFrom}`);
-    lines.push(`  signature       ${status.signatureStaleness}`);
+    lines.push(`  signature       ${status.signatureStaleness}${status.signatureStaleness === 'unknown' ? ' (NOT verified)' : ''}`);
     if (status.staleAssets.length > 0) {
-        lines.push(`  stale assets    ${status.staleAssets.length}`);
+        lines.push(`  changed since signing  ${status.staleAssets.length}`);
         for (const a of status.staleAssets.slice(0, 8))
             lines.push(`                  • ${a}`);
     }
+    lines.push(`  build           ${status.buildStaleness}${status.buildStaleness === 'unrecorded' ? ' (NOT verified)' : ''}`);
+    if (status.staleArtifacts.length > 0) {
+        lines.push(`  stale artifacts ${status.staleArtifacts.length}`);
+        for (const a of status.staleArtifacts.slice(0, 8))
+            lines.push(`                  • ${a}`);
+    }
     lines.push('');
-    lines.push('Contributions:');
+    lines.push('Contribution files (declared in the manifest):');
     for (const [k, v] of Object.entries(status.contributionCounts)) {
         lines.push(`  ${k.padEnd(12)} ${v}`);
     }