@peterxiaoyang/superspec 0.1.0

package/dist/src/install_engine.js

@@ -0,0 +1,351 @@
+// Manifest-driven install/update/uninstall engine (audit G-1, Phase 5 decision D4, 2026-06-10).
+// Single engine behind `superspec_init` / `--update` / `--uninstall`, per DISTRIBUTION.md §5-§6:
+// - install-map (adapters/codex/install-map.json) is the only source of what gets installed;
+// - install-manifest (.codex/superspec/install-manifest.json) is the only basis for update/uninstall;
+// - manifest sha256 is the managed BASELINE: mismatch means the user edited the file, which the
+//   engine must never overwrite or delete (dpkg-style *.new / skip + warn).
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SCHEMA_VERSION, isObject, sha256_file } from "./util.js";
+function find_package_root(moduleUrl) {
+    const moduleDir = dirname(fileURLToPath(moduleUrl));
+    for (const candidate of [resolve(moduleDir, ".."), resolve(moduleDir, "..", "..")]) {
+        if (existsSync(join(candidate, "package.json")) && existsSync(join(candidate, INSTALL_MAP_REL)))
+            return candidate;
+    }
+    return resolve(moduleDir, "..");
+}
+export const INSTALL_MAP_REL = join("adapters", "codex", "install-map.json");
+export const PACKAGE_ROOT = find_package_root(import.meta.url);
+export const PROJECT_INSTALL_MANIFEST_REL = join(".codex", "superspec", "install-manifest.json");
+export const USER_INSTALL_MANIFEST_REL = join("superspec", "install-manifest.json");
+export const INSTALL_MANIFEST_REL = PROJECT_INSTALL_MANIFEST_REL;
+function package_version(packageRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function load_install_map(packageRoot = PACKAGE_ROOT) {
+    const mapPath = join(packageRoot, INSTALL_MAP_REL);
+    if (!existsSync(mapPath))
+        return { mappings: [], problems: [`install map missing: ${mapPath}`] };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(mapPath, "utf8"));
+    }
+    catch (err) {
+        return { mappings: [], problems: [`install map unparsable: ${err.message}`] };
+    }
+    if (!isObject(raw) || !Array.isArray(raw.mappings))
+        return { mappings: [], problems: ["install map must contain a mappings list"] };
+    const mappings = [];
+    const problems = [];
+    raw.mappings.forEach((item, idx) => {
+        if (!isObject(item) || typeof item.kind !== "string" || typeof item.source !== "string" || !item.source
+            || typeof item.target !== "string" || !item.target) {
+            problems.push(`install map mappings[${idx}] is malformed`);
+            return;
+        }
+        if (!existsSync(join(packageRoot, item.source))) {
+            problems.push(`install map source missing: ${item.source}`);
+            return;
+        }
+        mappings.push({ kind: item.kind, source: item.source, target: item.target });
+    });
+    return { mappings, problems };
+}
+export function manifest_shape_problems(manifest) {
+    // Lightweight mirror of schemas/install-manifest.schema.json (no runtime deps allowed).
+    const problems = [];
+    if (!isObject(manifest))
+        return ["manifest is not an object"];
+    if (typeof manifest.superspecVersion !== "string" || !manifest.superspecVersion)
+        problems.push("superspecVersion missing");
+    if (typeof manifest.installedAt !== "string" || Number.isNaN(Date.parse(manifest.installedAt)))
+        problems.push("installedAt missing or not a date-time");
+    if (!Number.isInteger(manifest.guardSchemaVersion) || manifest.guardSchemaVersion < 1)
+        problems.push("guardSchemaVersion missing");
+    if (!["global-bin", "npm-bin", "repo-wrapper"].includes(manifest.guardWiring))
+        problems.push("guardWiring must be global-bin, npm-bin, or repo-wrapper");
+    if (manifest.installScope !== undefined && !["project", "user"].includes(manifest.installScope))
+        problems.push("installScope must be project or user");
+    if (!Array.isArray(manifest.createdDirs) || manifest.createdDirs.some((item) => typeof item !== "string" || !item))
+        problems.push("createdDirs malformed");
+    if (!Array.isArray(manifest.dataGlobs) || manifest.dataGlobs.some((item) => typeof item !== "string" || !item))
+        problems.push("dataGlobs malformed");
+    if (!Array.isArray(manifest.files)) {
+        problems.push("files missing");
+    }
+    else {
+        manifest.files.forEach((entry, idx) => {
+            if (!isObject(entry) || typeof entry.path !== "string" || !entry.path
+                || typeof entry.sha256 !== "string" || !/^sha256:[0-9a-f]{64}$/.test(entry.sha256)
+                || typeof entry.managed !== "boolean" || typeof entry.preexisting !== "boolean") {
+                problems.push(`files[${idx}] malformed`);
+            }
+        });
+    }
+    return problems;
+}
+export function read_install_manifest(repoRoot, opts = {}) {
+    const manifestPath = join(repoRoot, install_manifest_rel(opts.scope ?? "project"));
+    if (!existsSync(manifestPath))
+        return { manifest: null, problems: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch (err) {
+        return { manifest: null, problems: [`install manifest unparsable: ${err.message}`] };
+    }
+    const shapeProblems = manifest_shape_problems(parsed);
+    if (shapeProblems.length > 0)
+        return { manifest: null, problems: shapeProblems.map((item) => `install manifest invalid: ${item}`) };
+    return { manifest: parsed, problems: [] };
+}
+export function install_manifest_rel(scope = "project") {
+    return scope === "user" ? USER_INSTALL_MANIFEST_REL : PROJECT_INSTALL_MANIFEST_REL;
+}
+function scoped_mapping(mapping, scope) {
+    if (scope === "project")
+        return mapping;
+    if (mapping.kind === "wrapper")
+        return null;
+    const prefix = ".codex/";
+    return {
+        ...mapping,
+        target: mapping.target.startsWith(prefix) ? mapping.target.slice(prefix.length) : mapping.target,
+    };
+}
+function scoped_mappings(mappings, scope) {
+    return mappings.flatMap((mapping) => {
+        const scoped = scoped_mapping(mapping, scope);
+        return scoped === null ? [] : [scoped];
+    });
+}
+function write_install_manifest(repoRoot, packageRoot, files, createdDirs, scope) {
+    const manifest = {
+        superspecVersion: package_version(packageRoot),
+        installedAt: new Date().toISOString(),
+        guardSchemaVersion: SCHEMA_VERSION,
+        guardWiring: "global-bin",
+        installScope: scope,
+        files,
+        createdDirs: [...new Set(createdDirs)].sort(),
+        dataGlobs: ["**/.superspec"],
+    };
+    const manifestPath = join(repoRoot, install_manifest_rel(scope));
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return manifest;
+}
+function ensure_parent_dirs(repoRoot, targetAbs, createdDirs) {
+    const parent = dirname(targetAbs);
+    if (existsSync(parent))
+        return;
+    // Record every directory level this install creates so uninstall can remove exactly those.
+    let probe = parent;
+    const missing = [];
+    while (!existsSync(probe) && probe.startsWith(repoRoot) && probe !== repoRoot) {
+        missing.push(probe);
+        probe = dirname(probe);
+    }
+    mkdirSync(parent, { recursive: true });
+    for (const dir of missing)
+        createdDirs.push(dir.slice(repoRoot.length + 1));
+}
+function install_one(repoRoot, packageRoot, mapping, createdDirs) {
+    const sourceAbs = join(packageRoot, mapping.source);
+    const targetAbs = join(repoRoot, mapping.target);
+    const sourceSha = sha256_file(sourceAbs);
+    ensure_parent_dirs(repoRoot, targetAbs, createdDirs);
+    copyFileSync(sourceAbs, targetAbs);
+    if (mapping.kind === "wrapper")
+        chmodSync(targetAbs, 0o755);
+    return {
+        entry: { path: mapping.target, sha256: sourceSha, managed: true, preexisting: false },
+        action: { action: `install ${mapping.target}`, status: "created" },
+    };
+}
+export function install_workflow(repoRoot, opts = {}) {
+    const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+    const scope = opts.scope ?? "project";
+    const loaded = load_install_map(packageRoot);
+    const mappings = scoped_mappings(loaded.mappings, scope);
+    const problems = loaded.problems;
+    const actions = [];
+    if (problems.length > 0)
+        return { actions, problems, manifest: null };
+    const files = [];
+    const createdDirs = [];
+    for (const mapping of mappings) {
+        const sourceAbs = join(packageRoot, mapping.source);
+        const targetAbs = join(repoRoot, mapping.target);
+        const sourceSha = sha256_file(sourceAbs);
+        const targetSha = sha256_file(targetAbs);
+        if (targetSha === null) {
+            const result = install_one(repoRoot, packageRoot, mapping, createdDirs);
+            files.push(result.entry);
+            actions.push(result.action);
+        }
+        else if (targetSha === sourceSha) {
+            // Identical content: adopt as managed (idempotent re-init).
+            files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
+            actions.push({ action: `install ${mapping.target}`, status: "ok" });
+        }
+        else if (opts.force) {
+            copyFileSync(targetAbs, `${targetAbs}.bak`);
+            copyFileSync(sourceAbs, targetAbs);
+            if (mapping.kind === "wrapper")
+                chmodSync(targetAbs, 0o755);
+            files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
+            actions.push({ action: `install ${mapping.target}`, status: "updated", detail: `existing file backed up to ${mapping.target}.bak` });
+        }
+        else {
+            // Pre-existing different file: never overwrite, never delete (DISTRIBUTION §5 red line).
+            files.push({ path: mapping.target, sha256: targetSha, managed: false, preexisting: true });
+            actions.push({ action: `install ${mapping.target}`, status: "skipped", detail: "pre-existing file with different content kept; rerun with --force to overwrite (backs up *.bak)" });
+        }
+    }
+    const manifest = write_install_manifest(repoRoot, packageRoot, files, createdDirs, scope);
+    return { actions, problems: [], manifest };
+}
+export function update_workflow(repoRoot, opts = {}) {
+    const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+    const scope = opts.scope ?? "project";
+    const actions = [];
+    const { manifest: previous, problems: manifestProblems } = read_install_manifest(repoRoot, { scope });
+    if (manifestProblems.length > 0)
+        return { actions, problems: manifestProblems, manifest: null };
+    if (previous === null)
+        return { actions, problems: ["install manifest missing; run superspec init before --update"], manifest: null };
+    const loaded = load_install_map(packageRoot);
+    const mappings = scoped_mappings(loaded.mappings, scope);
+    const problems = loaded.problems;
+    if (problems.length > 0)
+        return { actions, problems, manifest: null };
+    const prevByPath = new Map(previous.files.map((entry) => [entry.path, entry]));
+    const files = [];
+    const createdDirs = [...previous.createdDirs];
+    const mappedTargets = new Set();
+    for (const mapping of mappings) {
+        mappedTargets.add(mapping.target);
+        const sourceAbs = join(packageRoot, mapping.source);
+        const targetAbs = join(repoRoot, mapping.target);
+        const sourceSha = sha256_file(sourceAbs);
+        const targetSha = sha256_file(targetAbs);
+        const prev = prevByPath.get(mapping.target);
+        if (prev?.preexisting) {
+            // Was the user's file before we arrived: keep hands off forever.
+            files.push({ ...prev, sha256: targetSha ?? prev.sha256 });
+            actions.push({ action: `update ${mapping.target}`, status: "skipped", detail: "preexisting file is never touched" });
+        }
+        else if (targetSha === null) {
+            const result = install_one(repoRoot, packageRoot, mapping, createdDirs);
+            files.push(result.entry);
+            actions.push({ ...result.action, action: `update ${mapping.target}` });
+        }
+        else if (targetSha === sourceSha) {
+            files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
+            actions.push({ action: `update ${mapping.target}`, status: "ok" });
+        }
+        else if (prev && targetSha === prev.sha256) {
+            // Managed and unmodified since install: safe to roll forward.
+            copyFileSync(sourceAbs, targetAbs);
+            if (mapping.kind === "wrapper")
+                chmodSync(targetAbs, 0o755);
+            files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
+            actions.push({ action: `update ${mapping.target}`, status: "updated" });
+        }
+        else {
+            // User-modified managed file: keep the user's version, ship ours as *.new (dpkg style).
+            // Manifest keeps the OLD baseline sha so uninstall still detects the modification.
+            copyFileSync(sourceAbs, `${targetAbs}.new`);
+            files.push(prev ?? { path: mapping.target, sha256: targetSha, managed: false, preexisting: true });
+            actions.push({ action: `update ${mapping.target}`, status: "skipped", detail: `user-modified file kept; new version written to ${mapping.target}.new` });
+        }
+    }
+    // Mappings removed from the new install map: delete the old managed file only when unmodified.
+    for (const prev of prevByPath.values()) {
+        if (mappedTargets.has(prev.path) || !prev.managed || prev.preexisting)
+            continue;
+        const targetAbs = join(repoRoot, prev.path);
+        const targetSha = sha256_file(targetAbs);
+        if (targetSha === null)
+            continue;
+        if (targetSha === prev.sha256) {
+            unlinkSync(targetAbs);
+            actions.push({ action: `update ${prev.path}`, status: "removed", detail: "managed file no longer shipped" });
+        }
+        else {
+            files.push(prev);
+            actions.push({ action: `update ${prev.path}`, status: "skipped", detail: "no longer shipped but user-modified; kept" });
+        }
+    }
+    const manifest = write_install_manifest(repoRoot, packageRoot, files, createdDirs, scope);
+    return { actions, problems: [], manifest };
+}
+function remove_empty_created_dirs(repoRoot, createdDirs, actions) {
+    const byDepth = [...new Set(createdDirs)].sort((a, b) => b.split("/").length - a.split("/").length);
+    for (const rel of byDepth) {
+        const abs = join(repoRoot, rel);
+        if (!existsSync(abs) || !statSync(abs).isDirectory())
+            continue;
+        if (readdirSync(abs).length > 0)
+            continue;
+        rmdirSync(abs);
+        actions.push({ action: `uninstall rmdir ${rel}`, status: "removed" });
+    }
+}
+export function uninstall_workflow(repoRoot, opts = {}) {
+    const scope = opts.scope ?? "project";
+    const actions = [];
+    const { manifest, problems: manifestProblems } = read_install_manifest(repoRoot, { scope });
+    if (manifestProblems.length > 0)
+        return { actions, problems: manifestProblems, manifest: null };
+    if (manifest === null)
+        return { actions, problems: ["install manifest missing; nothing to uninstall (manifest is the only removal authority)"], manifest: null };
+    for (const entry of manifest.files) {
+        const targetAbs = join(repoRoot, entry.path);
+        if (!entry.managed || entry.preexisting) {
+            actions.push({ action: `uninstall ${entry.path}`, status: "skipped", detail: "preexisting/unmanaged file is never touched" });
+            continue;
+        }
+        const targetSha = sha256_file(targetAbs);
+        if (targetSha === null) {
+            actions.push({ action: `uninstall ${entry.path}`, status: "ok", detail: "already absent" });
+            continue;
+        }
+        if (targetSha !== entry.sha256) {
+            actions.push({ action: `uninstall ${entry.path}`, status: "skipped", detail: "user-modified since install; kept" });
+            continue;
+        }
+        if (opts.dryRun) {
+            actions.push({ action: `uninstall ${entry.path}`, status: "would_remove" });
+        }
+        else {
+            unlinkSync(targetAbs);
+            actions.push({ action: `uninstall ${entry.path}`, status: "removed" });
+        }
+    }
+    if (!opts.dryRun) {
+        remove_empty_created_dirs(repoRoot, manifest.createdDirs, actions);
+        const manifestRel = install_manifest_rel(scope);
+        const manifestPath = join(repoRoot, manifestRel);
+        if (existsSync(manifestPath)) {
+            unlinkSync(manifestPath);
+            actions.push({ action: `uninstall ${manifestRel}`, status: "removed" });
+        }
+        const manifestDir = dirname(manifestPath);
+        if (existsSync(manifestDir) && readdirSync(manifestDir).length === 0)
+            rmdirSync(manifestDir);
+    }
+    // .superspec runtime data (dataGlobs) is intentionally untouched: default uninstall keeps all
+    // evidence/state; a --purge with preservation bundle is future work (DISTRIBUTION §6.4).
+    return { actions, problems: [], manifest };
+}

package/dist/src/invariants.d.ts

@@ -0,0 +1,16 @@
+import type { JsonMap, Reason, TaskInfo } from "./util.ts";
+export declare function business_invariants_text(changeRoot: string): string;
+export declare function parse_business_invariant_records(changeRoot: string): JsonMap[];
+export declare function business_invariant_ids(changeRoot: string): Set<string>;
+export declare function hard_business_invariant_ids(changeRoot: string): Set<string>;
+export declare function automated_hard_business_invariant_ids(changeRoot: string): Set<string>;
+export declare function post_implementation_business_invariant_ids(changeRoot: string): Set<string>;
+export declare function human_confirmation_business_invariant_ids(changeRoot: string): Set<string>;
+export declare function business_invariant_validation_reasons(changeRoot: string): Reason[];
+export declare function test_contract_invariant_ids(changeRoot: string): Set<string>;
+export declare function task_invariant_refs(tasks: Record<string, TaskInfo>): Set<string>;
+export declare function evidence_invariant_refs(ev: JsonMap): Set<string>;
+export declare function red_green_invariant_ids(evidences: JsonMap[]): Set<string>;
+export declare function evidence_invariant_ref_reasons(evidences: JsonMap[], taskId: string, declared: Set<string>, validIds: Set<string>, semanticStatus: string): Reason[];
+export declare function evidence_test_contract_invariant_reasons(evidences: JsonMap[], taskId: string, byTest: Map<string, Set<string>>, semanticStatus: string): Reason[];
+export declare function invariant_matrix_coverage_reasons(changeRoot: string, ev: JsonMap, evidences: JsonMap[]): Reason[];