productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/selfCheckCache.js

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { machineStateDir } from "./machineState.js";
+// The self-check scan cache (cli_performance_v0 R-003, D-003): per-file scan
+// results keyed on git HEAD + per-file (mtime, size) + detector-set version, so
+// a warm `foo self check` rescans only changed, new, or unknown files instead of
+// regex-scanning the whole tracked corpus on every run.
+//
+// Correctness is the bar (B1): a secret added to any tracked file MUST still be
+// reported on the next run. The cache never weakens that — a changed file has a
+// different (mtime, size); a changed HEAD or allowlist or detector set
+// invalidates everything; anything unreadable is treated as cold.
+//
+// The cache holds scan METADATA only — detector names, line numbers, mtime, and
+// size. Never file contents, never matched values (the redaction engine itself
+// carries no secret material either). It lives under the machine state dir
+// (~/.foo), which is untracked by construction.
+// Bump when anything that can change a scan result changes: redactEngine
+// detectors, scan options (minEntropyLen), the PII feedback rule, or this
+// cache's own entry shape. Bumping forces every cache to a full rescan.
+export const SCAN_DETECTOR_VERSION = "self-check-scan-cache-v1";
+// Bounds (RISK-004): one file per repo root under <state>/self-check/, each
+// trimmed to these caps on save, and the directory pruned to the most recently
+// used MAX_CACHE_FILES repos. Entries beyond a cap are simply dropped — those
+// files get rescanned next run (cold), never reported clean from stale data.
+export const MAX_CACHE_ENTRIES = 50_000;
+export const MAX_CACHE_BYTES = 8 * 1024 * 1024;
+export const MAX_CACHE_FILES = 128;
+// One file per repo root, so concurrent checkouts of different repos never
+// race and per-repo caps stay per-repo. Resolve the root so the same repo
+// reached as "." and as an absolute path shares one cache; reached via a
+// different cwd-relative path it correctly reads as a different key.
+export function scanCachePath(root) {
+    const repoKey = path.resolve(root);
+    const hash = createHash("sha1").update(repoKey).digest("hex");
+    return path.join(machineStateDir(), "self-check", `${hash}.json`);
+}
+// sha1 of the allowlist file's raw bytes. The allowlist decides what counts as
+// a finding, so any change to it must invalidate the cache even when HEAD has
+// not moved yet (an uncommitted allowlist edit).
+export function allowlistDigest(root, allowFile) {
+    const file = path.join(root, allowFile);
+    if (!existsSync(file))
+        return null;
+    try {
+        return createHash("sha1").update(readFileSync(file)).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+// Returns the cache only when everything it was keyed on still matches; any
+// mismatch, corruption, or unreadable file reads as cold (a full scan).
+export function loadScanCache(root, head, detectorVersion, allowlistDigestValue) {
+    if (head === null)
+        return null; // no HEAD: cannot key safely, never cache
+    const file = scanCachePath(root);
+    if (!existsSync(file))
+        return null;
+    try {
+        const cache = JSON.parse(readFileSync(file, "utf8"));
+        if (cache?.schema_version !== 1 ||
+            cache.repo !== path.resolve(root) ||
+            cache.head !== head ||
+            cache.detector_version !== detectorVersion ||
+            cache.allowlist_digest !== allowlistDigestValue ||
+            typeof cache.entries !== "object" ||
+            cache.entries === null) {
+            return null;
+        }
+        return cache;
+    }
+    catch {
+        return null;
+    }
+}
+// Keeps the lexicographically first maxEntries keys — deterministic, and with
+// the entries map rebuilt from the tracked list each run, order carries no
+// staleness risk: a dropped entry just means a cold rescan for that file.
+export function capScanCacheEntries(entries, maxEntries) {
+    const keys = Object.keys(entries).sort();
+    if (keys.length <= maxEntries)
+        return entries;
+    const kept = {};
+    for (const key of keys.slice(0, maxEntries))
+        kept[key] = entries[key];
+    return kept;
+}
+// Halve the entry set until the serialized cache fits the byte cap. Also
+// deterministic; again only costs a cold rescan for dropped files. A single
+// entry too large to halve further (a pathological file can carry ~250k
+// findings) is dropped entirely — under-reporting is never an option, so an
+// entry the cap cannot hold is simply rescanned next run.
+function capSerializedSize(cache) {
+    let capped = cache;
+    while (JSON.stringify(capped).length > MAX_CACHE_BYTES && Object.keys(capped.entries).length > 1) {
+        capped = {
+            ...capped,
+            entries: capScanCacheEntries(capped.entries, Math.max(1, Math.floor(Object.keys(capped.entries).length / 2))),
+        };
+    }
+    if (JSON.stringify(capped).length > MAX_CACHE_BYTES && Object.keys(capped.entries).length > 0) {
+        return { ...capped, entries: {} };
+    }
+    return capped;
+}
+// Keeps the MAX_CACHE_FILES most recently written repo caches so ephemeral
+// repos (test temp dirs get a fresh root every run) cannot accumulate forever
+// in the state dir.
+export function pruneScanCacheDir(dir, maxFiles) {
+    let files;
+    try {
+        files = readdirSync(dir)
+            .filter((name) => name.endsWith(".json"))
+            .map((name) => ({ name, mtimeMs: statSync(path.join(dir, name)).mtimeMs }));
+    }
+    catch {
+        return; // the dir does not exist, or cannot be read — nothing to prune
+    }
+    if (files.length <= maxFiles)
+        return;
+    files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (const stale of files.slice(maxFiles)) {
+        try {
+            unlinkSync(path.join(dir, stale.name));
+        }
+        catch {
+            // another process already pruned it — fine
+        }
+    }
+}
+// Best-effort. A failed cache write must never turn self check red or silent
+// about a finding — it only costs the next run its warm path. The run's findings
+// are already in memory by the time this is called.
+export function saveScanCache(cache) {
+    const file = scanCachePath(cache.repo);
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, JSON.stringify(capSerializedSize({ ...cache, entries: capScanCacheEntries(cache.entries, MAX_CACHE_ENTRIES) })));
+        pruneScanCacheDir(path.dirname(file), MAX_CACHE_FILES);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist-public/src/severityClass.d.ts

@@ -0,0 +1,15 @@
+export type SeverityClass = "bad" | "sad";
+export interface SeverityClassSpec {
+    /** The word that carries the meaning. */
+    label: SeverityClass;
+    /** One-line gloss for a legend or help surface. */
+    gloss: string;
+    /** Maps to the web design tokens (web/tokens.css), like the glyph vocabulary. */
+    tone: "warn" | "neutral";
+}
+export declare const SEVERITY_CLASS: Record<SeverityClass, SeverityClassSpec>;
+export interface SeverityClassCounts {
+    bad: number;
+    sad: number;
+}
+export declare function countByClass(classes: Iterable<SeverityClass>): SeverityClassCounts;

package/dist-public/src/severityClass.js

@@ -0,0 +1,22 @@
+// Recoverability class for foo findings — Fiona Fung's "bad vs. sad" frame
+// (bad-vs-sad-severity-v0). Orthogonal to `severity` (how much a finding
+// matters): `class` answers "can this be recovered from?"
+//
+//   - bad: unrecoverable / boundary-breaking. A false "done", a structurally
+//     unprovable requirement — you cannot trust the result until it is fixed.
+//   - sad: recoverable. Missing proof, an unfinished-but-referenced requirement
+//     — real, but cleaned up by finishing the obvious next step.
+//
+// This is a shared signal primitive: `verify` adopts it first, and other signal
+// surfaces (reconcile, self check) can stamp the same axis later so a triager
+// sees one consistent "fix-now vs. clean-up" split everywhere.
+export const SEVERITY_CLASS = {
+    bad: { label: "bad", gloss: "unrecoverable — cannot trust the result until fixed", tone: "warn" },
+    sad: { label: "sad", gloss: "recoverable — real, but cleaned up by finishing the next step", tone: "neutral" },
+};
+export function countByClass(classes) {
+    const counts = { bad: 0, sad: 0 };
+    for (const c of classes)
+        counts[c] += 1;
+    return counts;
+}

package/dist-public/src/skillClientPolicy.d.ts

@@ -0,0 +1,8 @@
+export declare const BUNDLED_SKILL_TREE_DOMAIN = "foo.bundled-skill-tree.v1";
+export interface BundledSkillTreeAnchor {
+    /** Top-level canonical skill folders the package ships. */
+    skill_count: number;
+    /** foo.bundled-skill-tree.v1 digest over the shipped tree. */
+    tree_sha256: string;
+}
+export declare const BUNDLED_SKILL_TREE: BundledSkillTreeAnchor;

package/dist-public/src/skillClientPolicy.js

@@ -0,0 +1,16 @@
+// The bundled canonical skills tree this client ships, and the anchor that
+// makes an installed package's own skills trusted with no hosted call and no
+// per-machine approval (foo-open-source-transition-v0 T-003, R-001): the npm
+// tarball carries skills/ and its registry integrity binds the install, and
+// this anchor — the digest of that tree, regenerated by
+// `node scripts/skill-tree-anchor.mjs` after any review that changes skills/ —
+// binds the bytes at every read. A tree edited after packaging mismatches the
+// anchor and is refused, never executed; the drift test
+// (test/skillTreeAnchor.test.ts) fails a build that ships a stale anchor.
+export const BUNDLED_SKILL_TREE_DOMAIN = "foo.bundled-skill-tree.v1";
+export const BUNDLED_SKILL_TREE = Object.freeze({
+    // ==== skill-tree-anchor:generated (scripts/skill-tree-anchor.mjs) ====
+    skill_count: 65,
+    tree_sha256: "aa4cc26b6363c639ff3d08d4b7c7bf1305159aa88d4743d0444c42af62255e95",
+    // ==== end skill-tree-anchor:generated ====
+});

package/dist-public/src/skillLocal.d.ts

@@ -0,0 +1,98 @@
+import { type BundledSkillTreeAnchor } from "./skillClientPolicy.js";
+export declare function markSkillFailure(kind: SkillFailureKind, message: string): void;
+export type SkillFailureKind = "not-found" | "unapproved-source";
+declare const PACKAGE_ROOT: string;
+export declare class SkillDeliveryError extends Error {
+    readonly kind: SkillFailureKind;
+    constructor(kind: SkillFailureKind, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * productfoo executes only skill text it can tie to an approval made on this machine:
+ * the bundled release digest, or a development tree the operator approved by
+ * exact digest. That refusal is the control that stops a caller repository
+ * shadowing a canonical skill with its own instructions.
+ *
+ * It is a refusal, not an outage. The old wording called it a trust boundary
+ * being "rebuilt" and told the reader to "use package-root skills" — which is
+ * what they were already doing, so the one command that clears it never
+ * appeared. Each condition now names itself and the command that fixes it.
+ */
+export declare function refuseUnapprovedSkillSource(reason: "missing" | "refused"): never;
+/** A missing bundled resource is a local installation error. */
+export declare function skillNotBundledMessage(name: string): string;
+export declare function skillRelPath(name: string): string | null;
+declare const SHA256_HEX: RegExp;
+export interface DevelopmentSkillTrustRecord {
+    schema_version: "1";
+    record_kind: "foo.development-skill-source";
+    root: string;
+    skills_sha256: string;
+    issued_at: string;
+    expires_at: string;
+}
+export interface DevelopmentSkillTrustProposal extends DevelopmentSkillTrustRecord {
+    record_path: string;
+}
+export interface DevelopmentSkillTrustProposalOptions {
+    record_path?: string;
+    issued_at?: string;
+    days?: number;
+}
+export declare function exactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean;
+export declare function shellWord(value: string): string;
+export declare function createDevelopmentSkillTrustRecord(rootValue: string, validity: {
+    issued_at: string;
+    expires_at: string;
+}): DevelopmentSkillTrustRecord;
+export declare function developmentSkillTrustProposal(rootValue: string, options?: DevelopmentSkillTrustProposalOptions): DevelopmentSkillTrustProposal;
+export declare function approveDevelopmentSkillTrust(rootValue: string, expectedSkillsSha256: string, options?: DevelopmentSkillTrustProposalOptions): DevelopmentSkillTrustProposal;
+export type DevelopmentSkillTrustStatus = {
+    status: "missing";
+} | {
+    status: "refused";
+} | {
+    status: "ready";
+    root: string;
+    skills_sha256: string;
+    issued_at: string;
+    expires_at: string;
+    record_path: string;
+};
+type DevelopmentSkillTrustRead = DevelopmentSkillTrustStatus & {
+    target_bytes?: Buffer | null;
+};
+export declare function readDevelopmentSkillTrust(rootValue: string, recordPath: string, targetRelative?: string, nowValue?: string): DevelopmentSkillTrustRead;
+export declare function inspectDevelopmentSkillTrust(rootValue: string, recordPath?: string, nowValue?: string): DevelopmentSkillTrustStatus;
+export interface CanonicalSkillTrustOptions {
+    development_trust_record?: string;
+    /**
+     * Test-only anchor override: pins which tree a resolve must match, so the
+     * mismatch-refusal path stays reachable without mutating the package on
+     * disk. Production callers omit it and get the committed release anchor.
+     */
+    bundled_skill_tree?: BundledSkillTreeAnchor;
+    now?: string;
+}
+/**
+ * #897: doctor's view of the install-anchored path. True when this package's
+ * skills tree is exactly the release-anchored tree, so every bundled skill
+ * loads with no approval (readBundledCanonicalSkill). False when the tree is
+ * absent, unreadable, or edited; then `foo skill trust` is genuinely needed.
+ */
+export declare function bundledSkillTreeVerified(root?: string, anchor?: BundledSkillTreeAnchor): boolean;
+declare function readTrustedCanonicalSkill(name: string, trust: CanonicalSkillTrustOptions): string;
+export declare function resolveLocalSkill(name: string, trust?: CanonicalSkillTrustOptions): {
+    text: string;
+    source: "local";
+} | null;
+export { PACKAGE_ROOT, readTrustedCanonicalSkill, SHA256_HEX };
+export declare function resolveSkill(root: string, name: string, env?: NodeJS.ProcessEnv, trust?: CanonicalSkillTrustOptions): Promise<{
+    text: string;
+    source: "local";
+}>;
+export declare function runSkillCommand(root: string, args: string[], env?: NodeJS.ProcessEnv, trust?: CanonicalSkillTrustOptions): Promise<{
+    output: string;
+    exitCode: number;
+}>;