@shrkcrft/cli 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/finish/run-finish.d.ts

@@ -0,0 +1,62 @@
+import { type IChangedScopeOptions } from '@shrkcrft/inspector';
+export declare const FINISH_SCHEMA: "sharkcraft.finish/v1";
+/** Outcome of one sub-gate. `skipped` = nothing to evaluate (loud, never silent green). */
+export type FinishGateStatus = 'pass' | 'fail' | 'skipped';
+/** One failing/relevant item, with file:line where the engine provides it. */
+export interface IFinishItem {
+    readonly file?: string;
+    readonly line?: number;
+    readonly message: string;
+}
+export interface IFinishGate {
+    readonly name: 'boundaries' | 'imports' | 'wiring' | 'policy' | 'orphans';
+    readonly status: FinishGateStatus;
+    /** One-line reason (e.g. why skipped, or the error/warning counts). */
+    readonly detail: string;
+    readonly errors: number;
+    readonly warnings: number;
+    /** Failing/notable items (capped by the renderer, full in JSON). */
+    readonly items: readonly IFinishItem[];
+}
+export interface IFinishImpact {
+    readonly ran: boolean;
+    readonly risk?: string;
+    readonly directDependents?: number;
+    readonly transitiveDependents?: number;
+    /** Why the summary could not run (no graph index / no changed files). */
+    readonly note?: string;
+}
+export interface IFinishReport {
+    readonly schema: typeof FINISH_SCHEMA;
+    readonly scope: {
+        readonly mode: 'worktree' | 'staged' | 'since' | 'files';
+        readonly files: readonly string[];
+        readonly fileCount: number;
+    };
+    readonly gates: readonly IFinishGate[];
+    readonly impact: IFinishImpact;
+    /** `fail` iff any gate failed OR the config could not load; else `pass`. */
+    readonly verdict: 'pass' | 'fail';
+    /** Total warning-severity findings across gates (non-blocking). */
+    readonly warnings: number;
+    /** Set when sharkcraft.config.ts could not be loaded — forces a `fail`. */
+    readonly configError?: string;
+    readonly summary: string;
+    readonly nextAction: string;
+}
+export interface IRunFinishInput {
+    readonly cwd: string;
+    readonly mode: 'worktree' | 'staged' | 'since' | 'files';
+    readonly scope: IChangedScopeOptions;
+}
+/**
+ * The composite "is this changeset safe to finish?" orchestrator. Runs every
+ * deterministic CHANGED-ONLY gate inline — boundaries + import-hygiene + wiring
+ * + policy + deleted-orphans — plus a best-effort impact summary, and folds
+ * them into ONE pass/fail. This is the single trustworthy "done?" call an
+ * autonomous agent needs and can't reliably assemble by hand (only shrk can run
+ * the alias-resolved layer/wiring gates). Honors the `0-rules → skipped`
+ * semantics so a no-op sub-check is reported, never silently passed. Read-only.
+ */
+export declare function runFinishGates(input: IRunFinishInput): Promise<IFinishReport>;
+//# sourceMappingURL=run-finish.d.ts.map

package/dist/finish/run-finish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-finish.d.ts","sourceRoot":"","sources":["../../src/finish/run-finish.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAa7B,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAE7D,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1E,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAYD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAkHnF"}

package/dist/finish/run-finish.js

@@ -0,0 +1,239 @@
+import { buildImportHygieneReport, filterViolationsToChangedScope, inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { evaluateBoundaries, loadTsconfigPaths, runPolicyLint, runWiring, scanImports, } from '@shrkcrft/boundaries';
+import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
+export const FINISH_SCHEMA = 'sharkcraft.finish/v1';
+/** Map the changed-scope onto the orphan check's diff inputs. */
+function orphanOptsFor(input) {
+    if (input.mode === 'files')
+        return undefined; // a file list has no diff to read deletions from
+    if (input.mode === 'staged')
+        return { staged: true };
+    if (input.mode === 'since' && input.scope.since)
+        return { since: input.scope.since };
+    // Worktree mode: diff deletions vs HEAD so the orphan gate's "deleted" set
+    // matches the working-tree scope the other gates use (not the whole branch).
+    return { since: 'HEAD' };
+}
+/**
+ * The composite "is this changeset safe to finish?" orchestrator. Runs every
+ * deterministic CHANGED-ONLY gate inline — boundaries + import-hygiene + wiring
+ * + policy + deleted-orphans — plus a best-effort impact summary, and folds
+ * them into ONE pass/fail. This is the single trustworthy "done?" call an
+ * autonomous agent needs and can't reliably assemble by hand (only shrk can run
+ * the alias-resolved layer/wiring gates). Honors the `0-rules → skipped`
+ * semantics so a no-op sub-check is reported, never silently passed. Read-only.
+ */
+export async function runFinishGates(input) {
+    const { cwd } = input;
+    const changed = resolveChangedFiles(input.scope);
+    const changedFiles = changed.files;
+    const gates = [];
+    // ── boundaries (changed-only) ────────────────────────────────────────
+    const inspection = await inspectSharkcraft({ cwd });
+    const boundaryRules = inspection.boundaryRegistry.list();
+    if (boundaryRules.length === 0) {
+        gates.push(skip('boundaries', 'no boundary rules configured'));
+    }
+    else if (changedFiles.length === 0) {
+        gates.push(skip('boundaries', 'no files in changed scope'));
+    }
+    else {
+        const scan = scanImports({ projectRoot: cwd });
+        const tsconfigPaths = loadTsconfigPaths(cwd);
+        const evalResult = evaluateBoundaries(scan, boundaryRules, {
+            ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
+        });
+        const filtered = filterViolationsToChangedScope(evalResult.violations, input.scope);
+        const errors = filtered.includedViolations.filter((v) => v.severity === 'error');
+        const warnings = filtered.includedViolations.filter((v) => v.severity === 'warning');
+        gates.push({
+            name: 'boundaries',
+            status: errors.length > 0 ? 'fail' : 'pass',
+            detail: `${errors.length} error(s), ${warnings.length} warning(s) across ${changedFiles.length} changed file(s)`,
+            errors: errors.length,
+            warnings: warnings.length,
+            items: [...errors, ...warnings].map((v) => ({
+                file: v.file,
+                line: v.line,
+                message: `[${v.severity}] ${v.ruleId}: ${v.message}`,
+            })),
+        });
+    }
+    // ── import hygiene (changed-only) ────────────────────────────────────
+    if (changedFiles.length === 0) {
+        gates.push(skip('imports', 'no files in changed scope'));
+    }
+    else {
+        const report = buildImportHygieneReport(cwd, { files: changedFiles });
+        const errors = report.counts?.['error'] ?? (report.verdict === 'errors' ? report.findings.length : 0);
+        const warnings = report.counts?.['warning'] ?? (report.verdict === 'warnings' ? report.findings.length : 0);
+        gates.push({
+            name: 'imports',
+            status: report.verdict === 'errors' ? 'fail' : 'pass',
+            detail: `verdict=${report.verdict} (${report.findings.length} finding(s))`,
+            errors,
+            warnings,
+            items: report.findings.map((f) => ({
+                file: f.file,
+                line: f.line,
+                message: `${f.kind}: ${f.suggestedFix || f.reason || f.snippet}`.trim(),
+            })),
+        });
+    }
+    // ── wiring + policy (changed-only, from resolved config) ─────────────
+    const loaded = await resolveProjectConfig(cwd);
+    let configError;
+    if (!loaded.ok) {
+        // A MALFORMED config in a real sharkcraft project is a fail (the wiring/
+        // policy gates can't be trusted). The mere ABSENCE of a sharkcraft/ folder
+        // is not — those gates simply don't apply, so skip them without failing.
+        const isSharkcraftProject = existsSync(nodePath.join(cwd, 'sharkcraft'));
+        if (isSharkcraftProject)
+            configError = loaded.error.message;
+        const detail = isSharkcraftProject
+            ? `config did not load: ${loaded.error.message}`
+            : 'no sharkcraft config (gate not applicable)';
+        gates.push(skip('wiring', detail));
+        gates.push(skip('policy', detail));
+    }
+    else {
+        gates.push(wiringGate(cwd, loaded.value.config.wiringRules ?? [], changedFiles), policyGate(cwd, loaded.value.config.policyRules ?? [], changedFiles));
+    }
+    // ── deleted-orphans (write-safety) ───────────────────────────────────
+    gates.push(await orphansGate(input));
+    // ── impact summary (informational, best-effort) ──────────────────────
+    const impact = await impactSummary(cwd, changedFiles);
+    // ── fold into one verdict ────────────────────────────────────────────
+    const failed = gates.filter((g) => g.status === 'fail');
+    const warnings = gates.reduce((n, g) => n + g.warnings, 0);
+    const verdict = failed.length > 0 || configError ? 'fail' : 'pass';
+    const skipped = gates.filter((g) => g.status === 'skipped').map((g) => g.name);
+    const summary = verdict === 'fail'
+        ? `Not safe to finish: ${configError ? 'config failed to load; ' : ''}${failed.map((g) => `${g.name} (${g.errors} error(s))`).join(', ') || 'see gates'}.`
+        : changedFiles.length === 0 && input.mode !== 'files'
+            ? 'No files in the changed scope — nothing to gate.'
+            : `Safe to finish: every applicable gate passed${warnings > 0 ? ` (${warnings} non-blocking warning(s))` : ''}${skipped.length > 0 ? `; skipped: ${skipped.join(', ')}` : ''}.`;
+    const nextAction = verdict === 'fail'
+        ? 'Fix every failing gate item (each carries file:line), then re-run `shrk finish`.'
+        : 'Safe to declare done.';
+    return {
+        schema: FINISH_SCHEMA,
+        scope: { mode: input.mode, files: changedFiles, fileCount: changedFiles.length },
+        gates,
+        impact,
+        verdict,
+        warnings,
+        ...(configError ? { configError } : {}),
+        summary,
+        nextAction,
+    };
+}
+function skip(name, detail) {
+    return { name, status: 'skipped', detail, errors: 0, warnings: 0, items: [] };
+}
+function wiringGate(cwd, rules, changedFiles) {
+    if (rules.length === 0)
+        return skip('wiring', 'no wiring rules configured');
+    const report = runWiring(cwd, rules, { changedOnly: true, changedFiles });
+    if (report.evaluated === 0) {
+        return skip('wiring', `${report.rules.length} rule(s) configured but none matched the changed scope`);
+    }
+    const errors = report.violations.filter((v) => v.severity === 'error');
+    const warnings = report.violations.filter((v) => v.severity === 'warning');
+    // A misconfigured rule (bad regex / no capture group) yields a diagnostic +
+    // rule-level error but NO violation — it must FAIL the gate, never read as a
+    // silent green ("loud, never silent green").
+    const diag = report.diagnostics;
+    return {
+        name: 'wiring',
+        status: report.verdict === 'errors' || diag.length > 0 ? 'fail' : 'pass',
+        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}`,
+        errors: errors.length + diag.length,
+        warnings: warnings.length,
+        items: [
+            ...report.violations.map((v) => ({
+                file: v.file,
+                line: v.line,
+                message: `[${v.severity}] ${v.ruleId}: "${v.token}" ${v.direction === 'registered-missing' ? 'registered but not declared' : 'declared but not registered'}`,
+            })),
+            ...diag.map((d) => ({ message: `misconfigured rule: ${d}` })),
+        ],
+    };
+}
+function policyGate(cwd, rules, changedFiles) {
+    if (rules.length === 0)
+        return skip('policy', 'no policy rules configured');
+    const report = runPolicyLint(cwd, rules, { changedOnly: true, changedFiles });
+    if (report.evaluated === 0) {
+        return skip('policy', `${report.rules.length} rule(s) configured but none matched the changed scope`);
+    }
+    const errors = report.findings.filter((f) => f.severity === 'error');
+    const warnings = report.findings.filter((f) => f.severity === 'warning');
+    const diag = report.diagnostics;
+    return {
+        name: 'policy',
+        status: report.verdict === 'errors' || diag.length > 0 ? 'fail' : 'pass',
+        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}`,
+        errors: errors.length + diag.length,
+        warnings: warnings.length,
+        items: [
+            ...report.findings.map((f) => ({
+                file: f.file,
+                line: f.line,
+                message: `[${f.severity}] ${f.ruleId}: ${f.message ?? ''}`.trim(),
+            })),
+            ...diag.map((d) => ({ message: `misconfigured rule: ${d}` })),
+        ],
+    };
+}
+async function orphansGate(input) {
+    const opts = orphanOptsFor(input);
+    if (!opts)
+        return skip('orphans', 'explicit --files scope has no diff to read deletions from');
+    const scan = await computeDeletedOrphans(input.cwd, opts);
+    if (!scan.ok) {
+        return skip('orphans', scan.reason === 'graph-missing'
+            ? 'code-graph index missing — run `shrk graph index` to enable the orphan check'
+            : `diff unavailable: ${scan.error ?? 'unknown'}`);
+    }
+    if (scan.deleted.length === 0)
+        return skip('orphans', `nothing deleted (vs ${scan.ref})`);
+    const orphans = scan.report?.orphans ?? [];
+    return {
+        name: 'orphans',
+        status: orphans.length > 0 ? 'fail' : 'pass',
+        detail: `${scan.deleted.length} deleted file(s) (vs ${scan.ref}) — ${orphans.length} surviving importer(s)`,
+        errors: orphans.length,
+        warnings: 0,
+        items: orphans.map((o) => ({
+            file: o.path ?? o.id,
+            ...(typeof o.line === 'number' ? { line: o.line } : {}),
+            message: o.via === 'reference' && o.symbol
+                ? `references \`${o.symbol}\` from deleted ${o.deletedFile}`
+                : `imports deleted ${o.deletedFile}`,
+        })),
+    };
+}
+async function impactSummary(cwd, changedFiles) {
+    if (changedFiles.length === 0)
+        return { ran: false, note: 'no changed files' };
+    try {
+        const { GraphStore } = await import('@shrkcrft/graph');
+        if (!new GraphStore(cwd).exists()) {
+            return { ran: false, note: 'code-graph index missing — run `shrk graph index`' };
+        }
+        const { analyzeGraphImpact } = await import('@shrkcrft/impact-engine');
+        const analysis = analyzeGraphImpact({ kind: 'files', files: [...changedFiles] }, { projectRoot: cwd, maxDepth: 5, limit: 200 });
+        return {
+            ran: true,
+            risk: analysis.risk,
+            directDependents: analysis.directDependents.length,
+            transitiveDependents: analysis.transitiveDependents.length,
+        };
+    }
+    catch (e) {
+        return { ran: false, note: `impact summary unavailable: ${e instanceof Error ? e.message : String(e)}` };
+    }
+}

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AA0X/B,wBAAgB,aAAa,IAAI,eAAe,CA8X/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAsHD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AA4X/B,wBAAgB,aAAa,IAAI,eAAe,CAgY/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -22,6 +22,7 @@ import { presetsListCommand, presetsGetCommand, presetsExplainCommand, presetsRe
 import { taskCommand } from "./commands/task.command.js";
 import { preflightCommand } from "./commands/preflight.command.js";
 import { checkCommand } from "./commands/check.command.js";
+import { finishCommand } from "./commands/finish.command.js";
 import { diffCheckCommand } from "./commands/diff-check.command.js";
 import { driftCommand } from "./commands/drift.command.js";
 import { graphCommand } from "./commands/graph.command.js";
@@ -33,6 +34,7 @@ import { frameworkCommand } from "./commands/framework.command.js";
 import { apiDiffCommand } from "./commands/api-diff.command.js";
 import { gateCommand } from "./commands/gate.command.js";
 import { policyLintCommand } from "./commands/policy-lint.command.js";
+import { wiringCommand } from "./commands/wiring.command.js";
 import { reuseCommand } from "./commands/reuse.command.js";
 import { migrateCommand } from "./commands/migrate.command.js";
 import { coverageCommand } from "./commands/coverage.command.js";
@@ -189,6 +191,7 @@ export function buildRegistry() {
     registry.register(explainCommand);
     registry.register(checkCommand);
     registry.register(diffCheckCommand);
+    registry.register(finishCommand);
     // changed-only preflight orchestrator.
     registry.register(preflightCommand);
     registry.register(driftCommand);
@@ -201,6 +204,7 @@ export function buildRegistry() {
     registry.register(apiDiffCommand);
     registry.register(gateCommand);
     registry.register(policyLintCommand);
+    registry.register(wiringCommand);
     registry.register(reuseCommand);
     registry.register(migrateCommand);
     registry.register(coverageCommand);
@@ -601,7 +605,21 @@ async function runCliInner(argv) {
     // (`shrk doctor`, `shrk packs list`, `shrk pack author status`). The
     // resolver stops when it hits a flag or a token that isn't a child of the
     // current node, returning the deepest handler + the leftover tokens.
-    const { handler, matchedPath, rest: leftover, node } = registry.resolve(cleanArgv);
+    let { handler, matchedPath, rest: leftover, node } = registry.resolve(cleanArgv);
+    // A multi-word command passed as a SINGLE quoted token (`shrk "graph status"`)
+    // arrives as one argv element with internal whitespace. The trie has no atomic
+    // `graph status` node, so the first descent misses (handler undefined) — yet
+    // did-you-mean would still list `graph status` as the #1 closest match, a
+    // self-contradiction. Re-split the lone token on whitespace and retry so the
+    // quoted form behaves identically to the unquoted `shrk graph status`.
+    // Genuinely unknown tokens leave `handler` undefined and fall through to the
+    // existing unknown-command path unchanged.
+    if (!handler && cleanArgv.length === 1 && /\s/.test(cleanArgv[0])) {
+        const retry = registry.resolve(cleanArgv[0].trim().split(/\s+/));
+        if (retry.handler) {
+            ({ handler, matchedPath, rest: leftover, node } = retry);
+        }
+    }
     // `--help` / `-h` immediately after a (sub)group → render help for that
     // path. This works at any depth.
     if (leftover[0] === '--help' || leftover[0] === '-h') {

package/dist/status/freshness.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Source-mtime freshness — a small shared CLI helper.
+ *
+ * Several `… status` commands (`framework status`, `context status`) need to
+ * answer the same question: "is this stored artefact stale relative to the
+ * source tree it was built from?" They all walk the workspace for the newest
+ * source-file mtime and compare it to a stored build timestamp. This module
+ * is the single home for that walk so the commands stay byte-identical.
+ *
+ * NOTE: this is deliberately CLI-local and distinct from
+ * `@shrkcrft/graph`'s `detectGraphFreshness` — that one models the graph
+ * store's own freshness and graph sits BELOW cli in the layer order, so it
+ * cannot be reused here.
+ */
+export declare const FRESHNESS_SKIP_DIRS: Set<string>;
+export declare const FRESHNESS_SOURCE_EXTS: Set<string>;
+export interface IStatusFreshness {
+    state: 'fresh' | 'stale' | 'unknown';
+    lastBuiltAt: string | null;
+    lastChangedAt: string | null;
+    behindMs: number;
+}
+/** Newest source-file mtime (ms) under `root`, ignoring build/output dirs. 0
+ *  when nothing matched. */
+export declare function newestSourceMtimeMs(root: string): number;
+/** Compare a stored build timestamp to the newest source mtime in `scope`.
+ *  `stale` when a source file is newer than the build; `unknown` when the
+ *  build timestamp can't be parsed. */
+export declare function computeMtimeFreshness(scope: string, builtAtIso: string | undefined | null): IStatusFreshness;
+//# sourceMappingURL=freshness.d.ts.map

package/dist/status/freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../src/status/freshness.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,mBAAmB,aAG9B,CAAC;AACH,eAAO,MAAM,qBAAqB,aAGhC,CAAC;AAEH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;4BAC4B;AAC5B,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA8BxD;AAED;;uCAEuC;AACvC,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,gBAAgB,CAc5G"}

package/dist/status/freshness.js

@@ -0,0 +1,81 @@
+import { readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+/**
+ * Source-mtime freshness — a small shared CLI helper.
+ *
+ * Several `… status` commands (`framework status`, `context status`) need to
+ * answer the same question: "is this stored artefact stale relative to the
+ * source tree it was built from?" They all walk the workspace for the newest
+ * source-file mtime and compare it to a stored build timestamp. This module
+ * is the single home for that walk so the commands stay byte-identical.
+ *
+ * NOTE: this is deliberately CLI-local and distinct from
+ * `@shrkcrft/graph`'s `detectGraphFreshness` — that one models the graph
+ * store's own freshness and graph sits BELOW cli in the layer order, so it
+ * cannot be reused here.
+ */
+export const FRESHNESS_SKIP_DIRS = new Set([
+    'node_modules', 'dist', 'build', 'coverage', '.git', '.sharkcraft',
+    '.next', '.cache', '.tmp-pack', 'out', 'target',
+]);
+export const FRESHNESS_SOURCE_EXTS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.java', '.cs', '.py', '.go', '.rs', '.kt', '.swift',
+]);
+/** Newest source-file mtime (ms) under `root`, ignoring build/output dirs. 0
+ *  when nothing matched. */
+export function newestSourceMtimeMs(root) {
+    let newest = 0;
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (FRESHNESS_SKIP_DIRS.has(name) || name.startsWith('.'))
+                continue;
+            const full = nodePath.join(dir, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!FRESHNESS_SOURCE_EXTS.has(nodePath.extname(full).toLowerCase()))
+                continue;
+            if (st.mtimeMs > newest)
+                newest = st.mtimeMs;
+        }
+    }
+    return newest;
+}
+/** Compare a stored build timestamp to the newest source mtime in `scope`.
+ *  `stale` when a source file is newer than the build; `unknown` when the
+ *  build timestamp can't be parsed. */
+export function computeMtimeFreshness(scope, builtAtIso) {
+    const newestMs = newestSourceMtimeMs(scope);
+    const lastChangedAt = newestMs > 0 ? new Date(newestMs).toISOString() : null;
+    const builtMs = builtAtIso ? Date.parse(builtAtIso) : NaN;
+    if (!Number.isFinite(builtMs)) {
+        return { state: 'unknown', lastBuiltAt: builtAtIso ?? null, lastChangedAt, behindMs: 0 };
+    }
+    const behindMs = newestMs > builtMs ? Math.round(newestMs - builtMs) : 0;
+    return {
+        state: behindMs > 0 ? 'stale' : 'fresh',
+        lastBuiltAt: builtAtIso ?? null,
+        lastChangedAt,
+        behindMs,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/cli",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "description": "SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -47,38 +47,38 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.22",
-    "@shrkcrft/compress": "^0.1.0-alpha.22",
-    "@shrkcrft/config": "^0.1.0-alpha.22",
-    "@shrkcrft/workspace": "^0.1.0-alpha.22",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.22",
-    "@shrkcrft/context": "^0.1.0-alpha.22",
-    "@shrkcrft/rules": "^0.1.0-alpha.22",
-    "@shrkcrft/paths": "^0.1.0-alpha.22",
-    "@shrkcrft/templates": "^0.1.0-alpha.22",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.22",
-    "@shrkcrft/dashboard": "^0.1.0-alpha.22",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.22",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.22",
-    "@shrkcrft/presets": "^0.1.0-alpha.22",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.22",
-    "@shrkcrft/graph": "^0.1.0-alpha.22",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.22",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.22",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.22",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.22",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.22",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.22",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.22",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.22",
-    "@shrkcrft/migrate": "^0.1.0-alpha.22",
-    "@shrkcrft/generator": "^0.1.0-alpha.22",
-    "@shrkcrft/importer": "^0.1.0-alpha.22",
-    "@shrkcrft/inspector": "^0.1.0-alpha.22",
-    "@shrkcrft/ai": "^0.1.0-alpha.22",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.22",
-    "@shrkcrft/shared": "^0.1.0-alpha.22",
-    "@shrkcrft/mcp-server": "^0.1.0-alpha.22",
+    "@shrkcrft/core": "^0.1.0-alpha.24",
+    "@shrkcrft/compress": "^0.1.0-alpha.24",
+    "@shrkcrft/config": "^0.1.0-alpha.24",
+    "@shrkcrft/workspace": "^0.1.0-alpha.24",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.24",
+    "@shrkcrft/context": "^0.1.0-alpha.24",
+    "@shrkcrft/rules": "^0.1.0-alpha.24",
+    "@shrkcrft/paths": "^0.1.0-alpha.24",
+    "@shrkcrft/templates": "^0.1.0-alpha.24",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.24",
+    "@shrkcrft/dashboard": "^0.1.0-alpha.24",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.24",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.24",
+    "@shrkcrft/presets": "^0.1.0-alpha.24",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.24",
+    "@shrkcrft/graph": "^0.1.0-alpha.24",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.24",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.24",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.24",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.24",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.24",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.24",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.24",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.24",
+    "@shrkcrft/migrate": "^0.1.0-alpha.24",
+    "@shrkcrft/generator": "^0.1.0-alpha.24",
+    "@shrkcrft/importer": "^0.1.0-alpha.24",
+    "@shrkcrft/inspector": "^0.1.0-alpha.24",
+    "@shrkcrft/ai": "^0.1.0-alpha.24",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.24",
+    "@shrkcrft/shared": "^0.1.0-alpha.24",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.24",
     "@huggingface/transformers": "^3.7.5"
   },
   "publishConfig": {