@peterxiaoyang/superspec 0.1.0

package/dist/src/git.d.ts

@@ -0,0 +1,8 @@
+import type { JsonMap, Reason, TaskInfo } from "./util.ts";
+export declare function file_blob_sha(filePath: string): string;
+export declare function git_lines(repoRoot: string, ...args: string[]): string[];
+export declare function dirty_worktree_paths(repoRoot: string): string[];
+export declare function dirty_worktree_reasons(repoRoot: string, changeRoot: string, evidences: JsonMap[]): Reason[];
+export declare function dirty_write_scope_red_reasons(repoRoot: string, tasks: Record<string, TaskInfo>, evidences: JsonMap[]): Reason[];
+export declare function review_diff_paths(repoRoot: string, baseRef: string, headRef: string): string[];
+export declare function review_diff_coverage_reasons(repoRoot: string, ev: JsonMap): Reason[];

package/dist/src/git.js

@@ -0,0 +1,112 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute, relative } from "node:path";
+import { GuardError, reason, renderList, runCommand, runtime } from "./util.js";
+import { splitList, task_test_evidence } from "./tasks.js";
+import { live_pass } from "./evidence.js";
+export function file_blob_sha(filePath) {
+    if (!existsSync(filePath) || !statSync(filePath).isFile())
+        throw new GuardError(`git_blob_inspection_failure: reviewed target missing: ${filePath}`);
+    const proc = runCommand("git", ["hash-object", "--no-filters", filePath], { cwd: dirname(filePath), timeout: 30_000 });
+    if (proc.error || proc.status !== 0)
+        throw new GuardError(`git_blob_inspection_failure: git hash-object failed: ${proc.stderr.trim()}`);
+    return proc.stdout.trim();
+}
+export function git_lines(repoRoot, ...args) {
+    const proc = runCommand("git", args, { cwd: repoRoot, timeout: 30_000 });
+    if (proc.error || proc.status !== 0)
+        throw new GuardError(`git_blob_inspection_failure: git ${args.join(" ")} exit ${proc.status}: ${proc.stderr.trim()}`);
+    return proc.stdout.split(/\r?\n/).filter((line) => line.trim());
+}
+export function dirty_worktree_paths(repoRoot) {
+    const paths = new Set();
+    const proc = runCommand("git", ["status", "--porcelain=v1", "-z", "--no-renames"], { cwd: repoRoot, timeout: 30_000 });
+    if (proc.error || proc.status !== 0) {
+        throw new GuardError(`git_blob_inspection_failure: git status --porcelain=v1 -z --no-renames exit ${proc.status}: ${proc.stderr.trim()}`);
+    }
+    const entries = proc.stdout.split("\0").filter(Boolean);
+    for (const entry of entries) {
+        if (entry.length < 4)
+            continue;
+        const item = entry.slice(3);
+        if (item)
+            paths.add(item);
+    }
+    return [...paths].sort();
+}
+export function dirty_worktree_reasons(repoRoot, changeRoot, evidences) {
+    let dirty;
+    try {
+        dirty = runtime.dirty_worktree_paths(repoRoot);
+    }
+    catch (err) {
+        return [reason("dirty_worktree_unavailable", `dirty worktree paths could not be inspected: ${String(err.message ?? err)}`)];
+    }
+    if (dirty.length === 0)
+        return [];
+    let changeRel = "";
+    const rel = relative(repoRoot, changeRoot);
+    if (rel && !rel.startsWith("..") && !isAbsolute(rel))
+        changeRel = rel;
+    const unknown = dirty.filter((item) => !(changeRel && item.startsWith(`${changeRel}/`)));
+    if (unknown.length === 0)
+        return [];
+    const confirmations = live_pass(evidences, { gate: "branch_handling", kind: "human_confirmation" });
+    const confirmedScopes = confirmations.flatMap((ev) => (Array.isArray(ev.confirmed_paths) ? ev.confirmed_paths.map((item) => String(item)).filter(Boolean) : []));
+    const unconfirmed = unknown.filter((item) => !confirmedScopes.some((scope) => pathInScope(item, scope)));
+    if (unconfirmed.length === 0)
+        return [];
+    return [reason("dirty_worktree_unattributed", `dirty/untracked files require branch/scope handling evidence with confirmed_paths before review_ready: ${renderList(unconfirmed.slice(0, 20))}`)];
+}
+function pathInScope(pathValue, scope) {
+    const normalized = scope.replace(/\/+$/, "");
+    return pathValue === normalized || pathValue.startsWith(`${normalized}/`);
+}
+export function dirty_write_scope_red_reasons(repoRoot, tasks, evidences) {
+    let dirty;
+    try {
+        dirty = runtime.dirty_worktree_paths(repoRoot);
+    }
+    catch (err) {
+        return [reason("dirty_worktree_unavailable", `dirty worktree paths could not be inspected: ${String(err.message ?? err)}`)];
+    }
+    const reasons = [];
+    for (const [taskId, task] of Object.entries(tasks)) {
+        const scopes = splitList(task.attrs.write_scope ?? "");
+        if (scopes.length === 0)
+            continue;
+        const touched = dirty.filter((item) => scopes.some((scope) => pathInScope(item, scope)));
+        if (touched.length === 0)
+            continue;
+        const tddRequired = (task.attrs.tdd_required ?? "true").toLowerCase() !== "false";
+        const tddMode = task.attrs.tdd_mode ?? "new-behavior";
+        if (!tddRequired || tddMode === "behavior-preserving-refactor")
+            continue;
+        if (task_test_evidence(evidences, taskId, "expected_failure", "task_edit").length === 0) {
+            reasons.push(reason("missing_red_evidence", `task ${taskId} write_scope changed without RED evidence: ${renderList(touched.slice(0, 20))}`, touched.slice(0, 20)));
+        }
+    }
+    return reasons;
+}
+export function review_diff_paths(repoRoot, baseRef, headRef) {
+    return runtime.git_lines(repoRoot, "diff", "--name-only", `${baseRef}..${headRef}`);
+}
+export function review_diff_coverage_reasons(repoRoot, ev) {
+    const { base_ref: baseRef, head_ref: headRef, reviewed_files: reviewedFiles } = ev;
+    if (typeof baseRef !== "string" || !baseRef || typeof headRef !== "string" || !headRef) {
+        return [reason("review_evidence_incomplete", `${ev._path}: base_ref and head_ref must be non-empty strings`)];
+    }
+    if (!Array.isArray(reviewedFiles) || reviewedFiles.length === 0)
+        return [];
+    let diffFiles;
+    try {
+        diffFiles = new Set(runtime.review_diff_paths(repoRoot, baseRef, headRef));
+    }
+    catch (err) {
+        return [reason("review_diff_unavailable", String(err.message ?? err))];
+    }
+    const reviewed = new Set(reviewedFiles.map((item) => String(item)));
+    const missing = [...diffFiles].filter((item) => !reviewed.has(item)).sort();
+    if (missing.length === 0)
+        return [];
+    return [reason("review_diff_not_covered", `${ev._path}: reviewed_files missing diff paths: ${renderList(missing.slice(0, 20))}`, missing.slice(0, 20))];
+}

package/dist/src/init_cli.d.ts

@@ -0,0 +1,2 @@
+export declare function main_init(argv?: string[]): number;
+export declare function main_init_async(argv?: string[]): Promise<number>;

package/dist/src/init_cli.js

@@ -0,0 +1,145 @@
+import { block, GuardError, printDecision, reason } from "./core.js";
+import { project_init } from "./project_init.js";
+import { install_workflow, uninstall_workflow, update_workflow } from "./install_engine.js";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+function usage() {
+    return "usage: superspec init [-h] [--scope {project,user}] [--path PATH] [--codex-home PATH] [--create] [--update] [--uninstall] [--dry-run] [--force]\n";
+}
+function help() {
+    return `${usage()}\noptional arguments:\n  -h, --help             show this help message and exit\n  --scope {project,user} install into this project's .codex directory or into the Codex user home (default: project)\n  --project              shortcut for --scope project\n  --user                 shortcut for --scope user\n  --global               compatibility alias for --user\n  --path PATH            project root for --scope project (default: current directory)\n  --codex-home PATH      Codex user home for --scope user (default: $CODEX_HOME or ~/.codex)\n  --create               accepted for compatibility; init creates missing surfaces by default\n  --update               manifest-driven update of managed SuperSpec surfaces (user-modified files kept, new version written to *.new)\n  --uninstall            manifest-driven removal of managed SuperSpec surfaces (.superspec data and preexisting/user-modified files are kept)\n  --dry-run              with --uninstall: print what would be removed without touching files\n  --force                with install: overwrite pre-existing different files (backs up *.bak)\n`;
+}
+function parse_init_argv(argv) {
+    const getValue = (flag) => {
+        const idx = argv.indexOf(flag);
+        if (idx === -1)
+            return undefined;
+        const value = argv[idx + 1];
+        if (value === undefined || value.startsWith("--"))
+            throw new GuardError(`${flag} requires a value`);
+        return value;
+    };
+    const update = argv.includes("--update");
+    const uninstall = argv.includes("--uninstall");
+    if (update && uninstall)
+        throw new GuardError("--update and --uninstall are mutually exclusive");
+    const scopeFlag = getValue("--scope");
+    if (scopeFlag !== undefined && !["project", "user", "global"].includes(scopeFlag))
+        throw new GuardError("--scope must be project or user");
+    const userShortcut = argv.includes("--user") || argv.includes("--global");
+    if (userShortcut && argv.includes("--project"))
+        throw new GuardError("--user/--global and --project are mutually exclusive");
+    let scope = scopeFlag === "global" ? "user" : scopeFlag ?? null;
+    if (userShortcut)
+        scope = "user";
+    if (argv.includes("--project"))
+        scope = "project";
+    return {
+        path: resolve(getValue("--path") ?? process.cwd()),
+        codexHome: resolve(getValue("--codex-home") ?? process.env.CODEX_HOME ?? joinHomeCodex()),
+        mode: uninstall ? "uninstall" : update ? "update" : "install",
+        scope,
+        dryRun: argv.includes("--dry-run"),
+        force: argv.includes("--force"),
+    };
+}
+function joinHomeCodex() {
+    return `${homedir()}/.codex`;
+}
+function engineDecision(gate, projectRoot, result, nextActions) {
+    if (result.problems.length > 0) {
+        const decision = block("project", gate, result.problems.map((item) => reason(`${gate}_failed`, item)));
+        return { ...decision, project_root: projectRoot, actions: result.actions, next_allowed_actions: [`fix ${gate}_failed reasons, then rerun`] };
+    }
+    return {
+        allowed: true,
+        decision: "allow",
+        change_id: null,
+        gate,
+        project_root: projectRoot,
+        actions: result.actions,
+        block_reasons: [],
+        next_allowed_actions: nextActions,
+        trust_warnings: [".superspec runtime data is never touched by install/update/uninstall; only manifest-managed files are"],
+    };
+}
+async function promptInstallScope() {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        for (;;) {
+            const answer = (await rl.question("Install SuperSpec Codex surfaces to project or user? [project] ")).trim().toLowerCase();
+            if (answer === "" || answer === "project" || answer === "p" || answer === "1")
+                return "project";
+            if (answer === "user" || answer === "u" || answer === "2" || answer === "global" || answer === "g")
+                return "user";
+            process.stderr.write("Please answer project or user.\n");
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+function canPrompt() {
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+}
+function run_init(args, scope) {
+    const targetRoot = scope === "user" ? args.codexHome : args.path;
+    const gatePrefix = scope === "user" ? "user" : "project";
+    let summary;
+    if (args.mode === "uninstall") {
+        summary = engineDecision(`${gatePrefix}_uninstall`, targetRoot, uninstall_workflow(targetRoot, { dryRun: args.dryRun, scope }), [
+            `managed SuperSpec surfaces removed; run superspec init --scope ${scope} to reinstall`,
+        ]);
+    }
+    else if (args.mode === "update") {
+        summary = engineDecision(`${gatePrefix}_update`, targetRoot, update_workflow(targetRoot, { scope }), [
+            scope === "project" ? "review *.new files for user-modified surfaces, then rerun superspec guard check-init" : "review *.new files for user-modified user-level surfaces",
+        ]);
+    }
+    else if (scope === "user") {
+        summary = engineDecision("user_install", targetRoot, install_workflow(targetRoot, { force: args.force, scope: "user" }), [
+            "user-level SuperSpec Codex surfaces installed; use superspec init --scope project inside a repo when project-local surfaces are needed",
+        ]);
+    }
+    else {
+        summary = project_init(args.path, { force: args.force });
+    }
+    summary.install_scope = scope;
+    summary.install_root = targetRoot;
+    printDecision(summary);
+    return summary.allowed ? 0 : 1;
+}
+export function main_init(argv = process.argv.slice(2)) {
+    try {
+        if (argv.includes("-h") || argv.includes("--help")) {
+            process.stdout.write(help());
+            return 0;
+        }
+        const args = parse_init_argv(argv);
+        return run_init(args, args.scope ?? "project");
+    }
+    catch (err) {
+        const change = "project";
+        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;
+    }
+}
+export async function main_init_async(argv = process.argv.slice(2)) {
+    try {
+        if (argv.includes("-h") || argv.includes("--help")) {
+            process.stdout.write(help());
+            return 0;
+        }
+        const args = parse_init_argv(argv);
+        const scope = args.scope ?? (canPrompt() ? await promptInstallScope() : "project");
+        return run_init(args, scope);
+    }
+    catch (err) {
+        const change = "project";
+        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/install_engine.d.ts

@@ -0,0 +1,54 @@
+import { type JsonMap } from "./util.ts";
+export declare const INSTALL_MAP_REL: string;
+export declare const PACKAGE_ROOT: string;
+export declare const PROJECT_INSTALL_MANIFEST_REL: string;
+export declare const USER_INSTALL_MANIFEST_REL: string;
+export declare const INSTALL_MANIFEST_REL: string;
+export type InstallMapping = {
+    kind: string;
+    source: string;
+    target: string;
+};
+export type InstallScope = "project" | "user";
+export type ManifestFileEntry = {
+    path: string;
+    sha256: string;
+    managed: boolean;
+    preexisting: boolean;
+};
+export type EngineAction = {
+    action: string;
+    status: "ok" | "created" | "updated" | "skipped" | "removed" | "would_remove" | "failed";
+    refs?: string[];
+    detail?: string;
+};
+export type EngineResult = {
+    actions: EngineAction[];
+    problems: string[];
+    manifest: JsonMap | null;
+};
+export declare function load_install_map(packageRoot?: string): {
+    mappings: InstallMapping[];
+    problems: string[];
+};
+export declare function manifest_shape_problems(manifest: any): string[];
+export declare function read_install_manifest(repoRoot: string, opts?: {
+    scope?: InstallScope;
+}): {
+    manifest: JsonMap | null;
+    problems: string[];
+};
+export declare function install_manifest_rel(scope?: InstallScope): string;
+export declare function install_workflow(repoRoot: string, opts?: {
+    force?: boolean;
+    packageRoot?: string;
+    scope?: InstallScope;
+}): EngineResult;
+export declare function update_workflow(repoRoot: string, opts?: {
+    packageRoot?: string;
+    scope?: InstallScope;
+}): EngineResult;
+export declare function uninstall_workflow(repoRoot: string, opts?: {
+    dryRun?: boolean;
+    scope?: InstallScope;
+}): EngineResult;