@peterxiaoyang/superspec 0.1.0

package/dist/src/archive.js

@@ -0,0 +1,428 @@
+import { closeSync, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { STATE_LOCK_FILENAME, allow, block, now, reason, renderList, repr, runtime, safe_within, sha256_file, sha256_text, toPosix, walkFiles, } from "./util.js";
+import { ensure_state_layout, sidecar_artifacts_dir, superspec_dir } from "./paths.js";
+export function archive_manifest_path(changeRoot) {
+    return join(sidecar_artifacts_dir(changeRoot), "archive-preservation.json");
+}
+export function archive_preservation_dir(changeRoot) {
+    return join(changeRoot, "superspec-preservation");
+}
+export function archive_preservation_manifest_path(changeRoot) {
+    return join(archive_preservation_dir(changeRoot), "manifest.json");
+}
+function archive_staging_root(changeRoot, runId) {
+    return join(changeRoot, ".superspec-staging", runId);
+}
+function fsync_dir_best_effort(dirPath) {
+    let fd = null;
+    try {
+        fd = openSync(dirPath, "r");
+        fsyncSync(fd);
+    }
+    catch {
+        // Directory fsync is best-effort across platforms.
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+function write_text(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text, "utf8");
+}
+function excluded_manifest_entry(relPath) {
+    if (relPath.endsWith(STATE_LOCK_FILENAME) || relPath.endsWith("superspec-state.tmp"))
+        return true;
+    if (relPath === ".superspec/artifacts/archive-preservation.json")
+        return true;
+    return false;
+}
+function manifest_entries(changeRoot, fileOverrides = {}) {
+    const base = superspec_dir(changeRoot);
+    const entries = [];
+    const pendingOverrides = new Set(Object.keys(fileOverrides));
+    if (existsSync(base) && statSync(base).isDirectory()) {
+        for (const filePath of walkFiles(base).sort()) {
+            const relPath = toPosix(relative(changeRoot, filePath));
+            if (excluded_manifest_entry(relPath))
+                continue;
+            if (pendingOverrides.has(relPath)) {
+                entries.push({ path: relPath, sha256: sha256_text(fileOverrides[relPath]) });
+                pendingOverrides.delete(relPath);
+            }
+            else {
+                entries.push({ path: relPath, sha256: sha256_file(filePath) });
+            }
+        }
+    }
+    for (const relPath of [...pendingOverrides].sort()) {
+        if (excluded_manifest_entry(relPath))
+            continue;
+        entries.push({ path: relPath, sha256: sha256_text(fileOverrides[relPath]) });
+    }
+    return entries.sort((a, b) => String(a.path).localeCompare(String(b.path)));
+}
+export function sidecar_manifest_entries(changeRoot) {
+    return manifest_entries(changeRoot);
+}
+function archive_manifest_data(change, changeRoot, fileOverrides = {}) {
+    ensure_state_layout(changeRoot);
+    return {
+        schema_version: 1,
+        change_id: change,
+        created_at: now(),
+        kind: "superspec_archive_preservation",
+        entries: manifest_entries(changeRoot, fileOverrides),
+    };
+}
+function write_manifest_file(filePath, manifest) {
+    write_text(filePath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return filePath;
+}
+export function write_archive_manifest(change, changeRoot) {
+    return write_manifest_file(archive_manifest_path(changeRoot), archive_manifest_data(change, changeRoot));
+}
+function stage_archive_bundle(change, changeRoot, runId, fileOverrides) {
+    const stagingRoot = archive_staging_root(changeRoot, runId);
+    const stagedManifestPath = join(stagingRoot, "next", "archive-preservation.json");
+    const stagedBundleDir = join(stagingRoot, "next", "superspec-preservation");
+    const stagedFilesRoot = join(stagedBundleDir, "files");
+    const manifest = archive_manifest_data(change, changeRoot, fileOverrides);
+    write_manifest_file(stagedManifestPath, manifest);
+    for (const entry of manifest.entries ?? []) {
+        const relPath = entry.path;
+        if (typeof relPath !== "string")
+            continue;
+        const dst = join(stagedFilesRoot, relPath);
+        if (relPath in fileOverrides) {
+            write_text(dst, fileOverrides[relPath]);
+            continue;
+        }
+        const src = join(changeRoot, relPath);
+        if (!existsSync(src) || !statSync(src).isFile())
+            continue;
+        mkdirSync(dirname(dst), { recursive: true });
+        copyFileSync(src, dst);
+    }
+    const bundleManifest = {
+        ...manifest,
+        kind: "superspec_archive_preservation_bundle",
+        source_manifest: ".superspec/artifacts/archive-preservation.json",
+        files_root: "files",
+    };
+    const stagedBundleManifestPath = join(stagedBundleDir, "manifest.json");
+    write_text(stagedBundleManifestPath, `${JSON.stringify(bundleManifest, null, 2)}\n`);
+    return { staged_manifest_path: stagedManifestPath, staged_bundle_dir: stagedBundleDir };
+}
+function restore_file_from_backup(finalPath, backupPath, hadFinal) {
+    if (existsSync(backupPath)) {
+        if (existsSync(finalPath))
+            rmSync(finalPath, { force: true });
+        mkdirSync(dirname(finalPath), { recursive: true });
+        renameSync(backupPath, finalPath);
+    }
+    else if (!hadFinal) {
+        if (existsSync(finalPath))
+            rmSync(finalPath, { force: true });
+    }
+    else {
+        throw new Error(`backup missing for ${finalPath}`);
+    }
+}
+function restore_dir_from_backup(finalPath, backupPath, hadFinal) {
+    if (existsSync(backupPath)) {
+        if (existsSync(finalPath))
+            rmSync(finalPath, { recursive: true, force: true });
+        renameSync(backupPath, finalPath);
+    }
+    else if (!hadFinal) {
+        if (existsSync(finalPath))
+            rmSync(finalPath, { recursive: true, force: true });
+    }
+    else {
+        throw new Error(`backup missing for ${finalPath}`);
+    }
+}
+function restore_promoted_bundle(state) {
+    restore_file_from_backup(state.final_manifest, state.backup_manifest, state.had_final_manifest);
+    restore_dir_from_backup(state.final_bundle_dir, state.backup_bundle_dir, state.had_final_bundle);
+}
+function promote_archive_bundle(changeRoot, runId, stagedManifestPath, stagedBundleDir) {
+    const finalManifest = archive_manifest_path(changeRoot);
+    const finalBundleDir = archive_preservation_dir(changeRoot);
+    const stagingRoot = archive_staging_root(changeRoot, runId);
+    const backupRoot = join(stagingRoot, "backup");
+    const backupManifest = join(backupRoot, "archive-preservation.json");
+    const backupBundleDir = join(backupRoot, "superspec-preservation");
+    const hadFinalManifest = existsSync(finalManifest);
+    const hadFinalBundle = existsSync(finalBundleDir);
+    const state = {
+        staging_root: stagingRoot,
+        final_manifest: finalManifest,
+        final_bundle_dir: finalBundleDir,
+        backup_manifest: backupManifest,
+        backup_bundle_dir: backupBundleDir,
+        had_final_manifest: hadFinalManifest,
+        had_final_bundle: hadFinalBundle,
+    };
+    mkdirSync(backupRoot, { recursive: true });
+    try {
+        if (hadFinalBundle) {
+            renameSync(finalBundleDir, backupBundleDir);
+            fsync_dir_best_effort(changeRoot);
+        }
+        if (hadFinalManifest) {
+            mkdirSync(dirname(backupManifest), { recursive: true });
+            renameSync(finalManifest, backupManifest);
+            fsync_dir_best_effort(dirname(finalManifest));
+        }
+        renameSync(stagedBundleDir, finalBundleDir);
+        fsync_dir_best_effort(changeRoot);
+        if (typeof runtime.after_archive_bundle_promote === "function") {
+            runtime.after_archive_bundle_promote({
+                change_root: changeRoot,
+                final_bundle_dir: finalBundleDir,
+                final_manifest: finalManifest,
+            });
+        }
+        mkdirSync(dirname(finalManifest), { recursive: true });
+        renameSync(stagedManifestPath, finalManifest);
+        fsync_dir_best_effort(dirname(finalManifest));
+        return state;
+    }
+    catch (err) {
+        try {
+            restore_promoted_bundle(state);
+            rmSync(stagingRoot, { recursive: true, force: true });
+        }
+        catch (restoreErr) {
+            throw new Error(`archive preservation promote failed: ${err.message}; rollback failed: ${restoreErr.message}`);
+        }
+        throw err;
+    }
+}
+export function begin_archive_preservation_bundle(change, changeRoot, opts = {}) {
+    const runId = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    const staged = stage_archive_bundle(change, changeRoot, runId, opts.file_overrides ?? {});
+    const promotion = promote_archive_bundle(changeRoot, runId, staged.staged_manifest_path, staged.staged_bundle_dir);
+    let settled = false;
+    return {
+        manifest_path: archive_manifest_path(changeRoot),
+        bundle_manifest_path: archive_preservation_manifest_path(changeRoot),
+        commit: () => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                rmSync(promotion.staging_root, { recursive: true, force: true });
+            }
+            catch {
+                // Commit is already durable; staging cleanup is best-effort.
+            }
+        },
+        rollback: () => {
+            if (settled)
+                return;
+            restore_promoted_bundle(promotion);
+            rmSync(promotion.staging_root, { recursive: true, force: true });
+            settled = true;
+        },
+    };
+}
+export function write_archive_preservation_bundle(change, changeRoot, opts = {}) {
+    const txn = begin_archive_preservation_bundle(change, changeRoot, opts);
+    txn.commit();
+    return txn.bundle_manifest_path;
+}
+export function find_archived_change(repoRoot, change) {
+    const archiveRoot = join(repoRoot, "openspec", "changes", "archive");
+    if (!existsSync(archiveRoot) || !lstatSync(archiveRoot).isDirectory())
+        return null;
+    const candidates = readdirSync(archiveRoot)
+        .filter((name) => name === change || (/^\d{4}-\d{2}-\d{2}-.+/.test(name) && name.slice(11) === change))
+        .map((name) => join(archiveRoot, name))
+        .filter((item) => {
+        const stat = lstatSync(item);
+        return !stat.isSymbolicLink() && stat.isDirectory();
+    })
+        .sort();
+    return candidates.at(-1) ?? null;
+}
+function manifest_change_id_reasons(change, manifest, label) {
+    if (manifest.change_id !== change) {
+        return [reason("archive_manifest_mismatch", `${label} manifest change_id=${repr(manifest.change_id)} does not match ${repr(change)}`)];
+    }
+    return [];
+}
+const PRIMARY_ARCHIVE_MANIFEST_KIND = "superspec_archive_preservation";
+const FALLBACK_ARCHIVE_MANIFEST_KIND = "superspec_archive_preservation_bundle";
+const REQUIRED_ARCHIVE_ENTRIES = [".superspec/ledger.jsonl", ".superspec/superspec-state.json"];
+function manifest_shape_reasons(change, manifest, label, expectedKind) {
+    const reasons = manifest_change_id_reasons(change, manifest, label);
+    if (manifest.kind !== expectedKind) {
+        reasons.push(reason("archive_manifest_mismatch", `${label} manifest kind=${repr(manifest.kind)} does not match ${repr(expectedKind)}`));
+    }
+    if (!Array.isArray(manifest.entries) || manifest.entries.length === 0) {
+        reasons.push(reason("archive_manifest_mismatch", `${label} manifest entries must be a non-empty list`));
+        return reasons;
+    }
+    const paths = new Set();
+    for (const entry of manifest.entries) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            reasons.push(reason("archive_manifest_mismatch", `${label} manifest entries must be objects`));
+            continue;
+        }
+        if (typeof entry.path === "string")
+            paths.add(entry.path);
+    }
+    const missingRequired = REQUIRED_ARCHIVE_ENTRIES.filter((entry) => !paths.has(entry));
+    if (missingRequired.length > 0) {
+        reasons.push(reason("archive_manifest_mismatch", `${label} manifest missing required entries: ${renderList([...missingRequired])}`, [...missingRequired]));
+    }
+    return reasons;
+}
+function manifest_entry_target(baseRoot, relPath) {
+    if (!relPath.startsWith(".superspec/"))
+        return null;
+    return safe_within(baseRoot, relPath);
+}
+function preserved_file_sha(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    const stat = lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink > 1)
+        return null;
+    return sha256_file(filePath);
+}
+export function check_archived(change, repoRoot) {
+    const archived = find_archived_change(repoRoot, change);
+    if (archived === null)
+        return block(change, "archived", [reason("archive_not_found", `archived change not found for ${change}`)]);
+    const manifestPath = archive_manifest_path(archived);
+    if (!existsSync(manifestPath) || !statSync(manifestPath).isFile()) {
+        const fallbackManifest = archive_preservation_manifest_path(archived);
+        if (!existsSync(fallbackManifest) || !statSync(fallbackManifest).isFile()) {
+            return block(change, "archived", [reason("superspec_not_preserved", "archive preservation manifest missing")]);
+        }
+        return check_archived_preservation_bundle(change, archived, fallbackManifest);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        return block(change, "archived", [reason("superspec_not_preserved", "archive preservation manifest is invalid JSON")]);
+    }
+    const shapeReasons = manifest_shape_reasons(change, manifest, "archive preservation", PRIMARY_ARCHIVE_MANIFEST_KIND);
+    if (shapeReasons.length > 0)
+        return block(change, "archived", shapeReasons);
+    const missing = [];
+    const mismatched = [];
+    const invalid = [];
+    for (const entry of manifest.entries) {
+        const relPath = entry.path;
+        const expected = entry.sha256;
+        if (typeof relPath !== "string" || typeof expected !== "string") {
+            mismatched.push(String(relPath));
+            continue;
+        }
+        const filePath = manifest_entry_target(archived, relPath);
+        if (filePath === null) {
+            invalid.push(relPath);
+            continue;
+        }
+        const actual = preserved_file_sha(filePath);
+        if (actual === null)
+            missing.push(relPath);
+        else if (actual !== expected)
+            mismatched.push(relPath);
+    }
+    const reasons = [];
+    if (invalid.length > 0)
+        reasons.push(reason("archive_manifest_mismatch", `archived .superspec manifest paths are invalid: ${renderList(invalid.slice(0, 20))}`, invalid.slice(0, 20)));
+    if (missing.length > 0)
+        reasons.push(reason("superspec_not_preserved", `archived .superspec files missing: ${renderList(missing.slice(0, 20))}`));
+    if (mismatched.length > 0)
+        reasons.push(reason("archive_manifest_mismatch", `archived .superspec files changed: ${renderList(mismatched.slice(0, 20))}`));
+    if (reasons.length > 0)
+        return block(change, "archived", reasons);
+    return allow(change, "archived", { gate_summary: { archive_root: archived, manifest_entries: (manifest.entries ?? []).length } });
+}
+export function check_archived_preservation_bundle(change, archived, manifestPath) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        return block(change, "archived", [reason("superspec_not_preserved", "fallback preservation manifest is invalid JSON")]);
+    }
+    const shapeReasons = manifest_shape_reasons(change, manifest, "fallback preservation", FALLBACK_ARCHIVE_MANIFEST_KIND);
+    if (shapeReasons.length > 0)
+        return block(change, "archived", shapeReasons);
+    if (typeof manifest.files_root !== "string" || !manifest.files_root) {
+        return block(change, "archived", [reason("archive_manifest_mismatch", "fallback preservation manifest requires files_root")]);
+    }
+    const filesRoot = safe_within(dirname(manifestPath), manifest.files_root);
+    if (filesRoot === null || !existsSync(filesRoot) || !lstatSync(filesRoot).isDirectory()) {
+        return block(change, "archived", [reason("archive_manifest_mismatch", `fallback preservation files_root is invalid: ${repr(manifest.files_root)}`)]);
+    }
+    const missing = [];
+    const mismatched = [];
+    const invalid = [];
+    for (const entry of manifest.entries) {
+        const relPath = entry.path;
+        const expected = entry.sha256;
+        if (typeof relPath !== "string" || typeof expected !== "string") {
+            mismatched.push(String(relPath));
+            continue;
+        }
+        const filePath = manifest_entry_target(filesRoot, relPath);
+        if (filePath === null) {
+            invalid.push(relPath);
+            continue;
+        }
+        const actual = preserved_file_sha(filePath);
+        if (actual === null)
+            missing.push(relPath);
+        else if (actual !== expected)
+            mismatched.push(relPath);
+    }
+    const reasons = [];
+    if (invalid.length > 0)
+        reasons.push(reason("archive_manifest_mismatch", `fallback .superspec manifest paths are invalid: ${renderList(invalid.slice(0, 20))}`, invalid.slice(0, 20)));
+    if (missing.length > 0)
+        reasons.push(reason("superspec_not_preserved", `fallback .superspec files missing: ${renderList(missing.slice(0, 20))}`));
+    if (mismatched.length > 0)
+        reasons.push(reason("archive_manifest_mismatch", `fallback .superspec files changed: ${renderList(mismatched.slice(0, 20))}`));
+    if (reasons.length > 0)
+        return block(change, "archived", reasons);
+    return allow(change, "archived", {
+        gate_summary: {
+            archive_root: archived,
+            fallback_manifest: toPosix(relative(archived, manifestPath)),
+            manifest_entries: (manifest.entries ?? []).length,
+        },
+    });
+}
+export function preset_upgrade_required(preset, changedPaths, flags = {}) {
+    if (preset === "full")
+        return false;
+    if (preset === "hotfix")
+        return changedPaths.length >= 3 || Boolean(flags.architecture) || Boolean(flags.schema) || Boolean(flags.public_api) || Boolean(flags.cross_module);
+    if (preset === "tweak")
+        return changedPaths.length >= 5 || Boolean(flags.cross_module) || Number(flags.new_tests ?? 0) >= 5 || Boolean(flags.config_key_add_remove);
+    return true;
+}
+export function preset_upgrade_reasons(config, changedPaths, humanConfirmed = false, flags = {}) {
+    const preset = String(config.preset ?? "full");
+    if (!preset_upgrade_required(preset, changedPaths, flags))
+        return [];
+    if (humanConfirmed)
+        return [];
+    return [reason("preset_upgrade_requires_human_confirmation", `preset ${repr(preset)} must upgrade to full before proceeding`)];
+}
+export function preset_upgrade_required_from_context(config, changedPaths) {
+    return preset_upgrade_required(String(config.preset ?? "full"), changedPaths);
+}

package/dist/src/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/dist/src/cli.js

@@ -0,0 +1,20 @@
+import { block, dispatch, GuardError, printDecision, reason } from "./core.js";
+import { emitArgparsePreamble, parse_argv } from "./cli_args.js";
+export function main(argv = process.argv.slice(2)) {
+    let args = null;
+    try {
+        const argparseExit = emitArgparsePreamble(argv);
+        if (argparseExit !== null)
+            return argparseExit;
+        args = parse_argv(argv);
+        const [decision] = dispatch(args);
+        printDecision(decision);
+        return decision.allowed ? 0 : 1;
+    }
+    catch (err) {
+        const change = args?.change ?? "?";
+        const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
+        printDecision(block(change, "guard_error", [errReason]));
+        return 2;
+    }
+}

package/dist/src/cli_args.d.ts

@@ -0,0 +1,12 @@
+export type ParsedArgs = {
+    command: string;
+    change: string;
+    artifact?: string;
+    gate?: string;
+    task_id?: string;
+    create?: boolean;
+    force_unlock?: boolean;
+    rebuild_corrupt?: boolean;
+};
+export declare function emitArgparsePreamble(argv: string[]): number | null;
+export declare function parse_argv(argv: string[]): ParsedArgs;

package/dist/src/cli_args.js

@@ -0,0 +1,146 @@
+const SIMPLE_COMMANDS = [
+    "status",
+    "recompute",
+    "check-init",
+    "check-apply-ready",
+    "check-review-ready",
+    "check-review-complete",
+    "check-verify-ready",
+    "check-archive-ready",
+    "check-archived",
+];
+const COMMANDS = [
+    "init",
+    ...SIMPLE_COMMANDS,
+    "check-artifact",
+    "check-enter",
+    "check-task-reopen",
+    "check-task-edit",
+    "check-task-complete",
+];
+const COMMAND_LIST = COMMANDS.join(",");
+const COMMAND_CHOICES = COMMANDS.map((item) => `'${item}'`).join(", ");
+function requiredValueFlags(command) {
+    const flags = ["--change"];
+    if (command === "check-artifact")
+        flags.push("--artifact");
+    if (command === "check-enter")
+        flags.push("--gate");
+    if (command === "check-task-reopen" || command === "check-task-edit" || command === "check-task-complete")
+        flags.push("--task-id");
+    return flags;
+}
+function requiredBooleanFlags(command) {
+    return command === "init" ? ["--create"] : [];
+}
+function optionalBooleanFlags(command) {
+    return command === "recompute" ? ["--force-unlock", "--rebuild-corrupt"] : [];
+}
+function rootUsage() {
+    return `usage: superspec_guard [-h]\n                     {${COMMAND_LIST}}\n                     ...\n`;
+}
+function rootHelp() {
+    return `${rootUsage()}\nsuperspec Sync Guard (v1)\n\npositional arguments:\n  {${COMMAND_LIST}}\n\noptional arguments:\n  -h, --help            show this help message and exit\n`;
+}
+function commandUsage(command) {
+    const usageFlags = [
+        "[-h]",
+        ...requiredValueFlags(command).map((flag) => `${flag} ${flag.slice(2).replace(/-/g, "_").toUpperCase()}`),
+        ...requiredBooleanFlags(command),
+        ...optionalBooleanFlags(command),
+    ];
+    return `usage: superspec_guard ${command} ${usageFlags.join(" ")}\n`;
+}
+function commandHelp(command) {
+    const lines = [commandUsage(command), "\noptional arguments:\n", "  -h, --help           show this help message and exit\n"];
+    for (const flag of requiredValueFlags(command)) {
+        const metavariable = flag.slice(2).replace(/-/g, "_").toUpperCase();
+        lines.push(`  ${flag} ${metavariable}\n`);
+    }
+    for (const flag of requiredBooleanFlags(command)) {
+        lines.push(`  ${flag}\n`);
+    }
+    for (const flag of optionalBooleanFlags(command)) {
+        lines.push(`  ${flag}\n`);
+    }
+    return lines.join("");
+}
+function hasFlag(argv, flag) {
+    return argv.includes(flag);
+}
+function missingRequiredFlags(command, args) {
+    return [...requiredValueFlags(command), ...requiredBooleanFlags(command)].filter((flag) => !hasFlag(args, flag));
+}
+export function emitArgparsePreamble(argv) {
+    if (argv.length === 0) {
+        process.stderr.write(`${rootUsage()}superspec_guard: error: the following arguments are required: command\n`);
+        return 2;
+    }
+    const command = argv[0];
+    if (command === "-h" || command === "--help") {
+        process.stdout.write(rootHelp());
+        return 0;
+    }
+    if (!COMMANDS.includes(command)) {
+        process.stderr.write(`${rootUsage()}superspec_guard: error: argument command: invalid choice: '${command}' (choose from ${COMMAND_CHOICES})\n`);
+        return 2;
+    }
+    const args = argv.slice(1);
+    if (args.includes("-h") || args.includes("--help")) {
+        process.stdout.write(commandHelp(command));
+        return 0;
+    }
+    const missing = missingRequiredFlags(command, args);
+    if (missing.length > 0) {
+        process.stderr.write(`${commandUsage(command)}superspec_guard ${command}: error: the following arguments are required: ${missing.join(", ")}\n`);
+        return 2;
+    }
+    return null;
+}
+export function parse_argv(argv) {
+    if (argv.length === 0)
+        throw new Error("missing command");
+    const command = argv[0];
+    const args = argv.slice(1);
+    const getValue = (flag) => {
+        const idx = args.indexOf(flag);
+        if (idx === -1)
+            return undefined;
+        return args[idx + 1];
+    };
+    const change = getValue("--change");
+    if (!change)
+        throw new Error("missing required --change");
+    if (command === "init") {
+        if (!hasFlag(args, "--create"))
+            throw new Error("missing required --create");
+        return { command, change, create: true };
+    }
+    if (command === "check-artifact") {
+        const artifact = getValue("--artifact");
+        if (!artifact)
+            throw new Error("missing required --artifact");
+        return { command, change, artifact };
+    }
+    if (command === "check-enter") {
+        const gate = getValue("--gate");
+        if (!gate)
+            throw new Error("missing required --gate");
+        return { command, change, gate };
+    }
+    if (command === "check-task-reopen" || command === "check-task-edit" || command === "check-task-complete") {
+        const taskId = getValue("--task-id");
+        if (!taskId)
+            throw new Error("missing required --task-id");
+        return { command, change, task_id: taskId };
+    }
+    const simple = new Set(SIMPLE_COMMANDS);
+    if (!simple.has(command))
+        throw new Error(`unknown command: ${command}`);
+    return {
+        command,
+        change,
+        force_unlock: command === "recompute" && hasFlag(args, "--force-unlock"),
+        rebuild_corrupt: command === "recompute" && hasFlag(args, "--rebuild-corrupt"),
+    };
+}

package/dist/src/core.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+export * from "./util.ts";
+export * from "./openspec.ts";
+export * from "./paths.ts";
+export * from "./disclosure.ts";
+export * from "./evidence.ts";
+export * from "./tasks.ts";
+export * from "./invariants.ts";
+export * from "./git.ts";
+export * from "./state.ts";
+export * from "./archive.ts";
+export * from "./gates.ts";
+export * from "./install_engine.ts";
+import type { ParsedArgs } from "./cli_args.ts";
+import type { JsonMap } from "./util.ts";
+export declare function load_context(change: string): [JsonMap, string, string, JsonMap[]];
+export declare function cmd_status(change: string): JsonMap;
+export declare function cmd_init_summary(change: string, changeRoot: string, decision: JsonMap): JsonMap;
+export declare function dispatch(args: ParsedArgs): [JsonMap, string];