@peterxiaoyang/superspec 0.1.0

package/dist/src/paths.js

@@ -0,0 +1,203 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ALLOWED_CONFIG_KEYS, BUILTIN_CONFIG, CHANGE_CONFIG_ALIASES, CONFIG_FILENAME, GuardError, PROJECT_CONFIG_ALIASES, REQUIRED_SIDECAR_DIRS, STATE_ALIASES, isObject, reason, repr, safe_within, } from "./util.js";
+export function superspec_dir(changeRoot) {
+    return join(changeRoot, ".superspec");
+}
+export function project_superspec_dir(repoRoot) {
+    return join(repoRoot, ".superspec");
+}
+export function sidecar_artifacts_dir(changeRoot) {
+    return join(superspec_dir(changeRoot), "artifacts");
+}
+export function sidecar_test_contract_path(changeRoot) {
+    return join(sidecar_artifacts_dir(changeRoot), "test-contract.md");
+}
+export function sidecar_business_invariants_path(changeRoot) {
+    return join(sidecar_artifacts_dir(changeRoot), "business-invariants.md");
+}
+export function sidecar_discovery_path(changeRoot) {
+    return join(sidecar_artifacts_dir(changeRoot), "discovery.md");
+}
+export function sidecar_output_path(changeRoot, relPath) {
+    const target = safe_within(superspec_dir(changeRoot), relPath);
+    if (target === null)
+        throw new GuardError(`sidecar_path_invalid: ${relPath}`);
+    return target;
+}
+export function write_sidecar_text(changeRoot, relPath, text) {
+    const filePath = sidecar_output_path(changeRoot, relPath);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, text, "utf8");
+    return filePath;
+}
+export function write_sidecar_json(changeRoot, relPath, data) {
+    return write_sidecar_text(changeRoot, relPath, `${JSON.stringify(data, null, 2)}\n`);
+}
+export function config_file(changeRoot) {
+    return join(superspec_dir(changeRoot), CONFIG_FILENAME);
+}
+export function project_config_file(repoRoot) {
+    return join(project_superspec_dir(repoRoot), CONFIG_FILENAME);
+}
+export function required_sidecar_paths(changeRoot) {
+    return REQUIRED_SIDECAR_DIRS.map((relPath) => join(superspec_dir(changeRoot), relPath));
+}
+export function ensure_sidecar_layout(changeRoot) {
+    ensure_state_layout(changeRoot);
+    for (const dirPath of required_sidecar_paths(changeRoot))
+        mkdirSync(dirPath, { recursive: true });
+}
+export function ensure_state_layout(changeRoot) {
+    const base = superspec_dir(changeRoot);
+    mkdirSync(base, { recursive: true });
+    const ledger = join(base, "ledger.jsonl");
+    if (!existsSync(ledger))
+        writeFileSync(ledger, "");
+}
+export function find_forbidden_aliases(repoRoot, changeRoot) {
+    const aliases = [];
+    for (const relPath of PROJECT_CONFIG_ALIASES) {
+        const candidate = join(repoRoot, relPath);
+        if (existsSync(candidate))
+            aliases.push(candidate);
+    }
+    for (const relPath of CHANGE_CONFIG_ALIASES) {
+        const candidate = join(changeRoot, relPath);
+        if (existsSync(candidate))
+            aliases.push(candidate);
+    }
+    for (const relPath of STATE_ALIASES) {
+        const candidate = join(changeRoot, relPath);
+        if (existsSync(candidate))
+            aliases.push(candidate);
+    }
+    return aliases;
+}
+export function read_skill_frontmatter_name(skillPath) {
+    let lines;
+    try {
+        lines = readFileSync(skillPath, "utf8").split(/\r?\n/);
+    }
+    catch {
+        return null;
+    }
+    if (lines.length === 0 || lines[0].trim() !== "---")
+        return null;
+    for (const raw of lines.slice(1)) {
+        const stripped = raw.trim();
+        if (stripped === "---")
+            return null;
+        if (stripped.startsWith("name:"))
+            return stripped.split(":", 2)[1].trim().replace(/^['"]|['"]$/g, "");
+    }
+    return null;
+}
+export function read_agent_toml_name(agentPath) {
+    let lines;
+    try {
+        lines = readFileSync(agentPath, "utf8").split(/\r?\n/);
+    }
+    catch {
+        return null;
+    }
+    for (const raw of lines) {
+        const match = raw.match(/^\s*name\s*=\s*["']([^"']+)["']\s*$/);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+function parseScalar(raw) {
+    const value = raw.trim();
+    if (!value)
+        return "";
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (value === "null" || value === "None")
+        return null;
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+        return value.slice(1, -1);
+    if (/^-?\d+$/.test(value))
+        return Number.parseInt(value, 10);
+    return value;
+}
+export function parse_simple_yaml(filePath) {
+    const data = {};
+    let currentKey = null;
+    const lines = readFileSync(filePath, "utf8").split(/\r?\n/);
+    lines.forEach((raw, idx) => {
+        const stripped = raw.trim();
+        if (!stripped || stripped.startsWith("#"))
+            return;
+        const indent = raw.length - raw.trimStart().length;
+        if (!stripped.includes(":"))
+            throw new GuardError(`config_parse_error: ${filePath}:${idx + 1}: expected key: value`);
+        const [keyRaw, ...rest] = stripped.split(":");
+        const key = keyRaw.trim();
+        const value = rest.join(":");
+        if (!key)
+            throw new GuardError(`config_parse_error: ${filePath}:${idx + 1}: empty key`);
+        if (indent === 0) {
+            if (value.trim()) {
+                data[key] = parseScalar(value);
+                currentKey = null;
+            }
+            else {
+                data[key] = {};
+                currentKey = key;
+            }
+        }
+        else if (indent === 2 && currentKey) {
+            const parent = data[currentKey];
+            if (!isObject(parent))
+                throw new GuardError(`config_parse_error: ${filePath}:${idx + 1}: parent is not mapping`);
+            parent[key] = parseScalar(value);
+        }
+        else {
+            throw new GuardError(`config_parse_error: ${filePath}:${idx + 1}: unsupported indentation`);
+        }
+    });
+    return data;
+}
+export function merge_config(base, override) {
+    const merged = JSON.parse(JSON.stringify(base));
+    for (const [key, value] of Object.entries(override)) {
+        if (isObject(value) && isObject(merged[key]))
+            merged[key] = { ...merged[key], ...value };
+        else
+            merged[key] = value;
+    }
+    return merged;
+}
+export function validate_config_keys(config, source) {
+    const problems = [];
+    for (const key of Object.keys(config)) {
+        if (ALLOWED_CONFIG_KEYS.has(key) || key.startsWith("x-"))
+            continue;
+        problems.push(reason("unknown_config_key", `${source}: unknown config key ${repr(key)}`));
+    }
+    return problems;
+}
+export function load_config(repoRoot, changeRoot) {
+    const problems = [];
+    for (const aliasPath of find_forbidden_aliases(repoRoot, changeRoot)) {
+        problems.push(reason("forbidden_alias_path", `forbidden superspec alias exists: ${aliasPath}`));
+    }
+    let config = JSON.parse(JSON.stringify(BUILTIN_CONFIG));
+    const projectCfg = project_config_file(repoRoot);
+    if (existsSync(projectCfg) && statSync(projectCfg).isFile()) {
+        const parsed = parse_simple_yaml(projectCfg);
+        problems.push(...validate_config_keys(parsed, projectCfg));
+        config = merge_config(config, parsed);
+    }
+    const changeCfg = config_file(changeRoot);
+    if (existsSync(changeCfg) && statSync(changeCfg).isFile()) {
+        const parsed = parse_simple_yaml(changeCfg);
+        problems.push(...validate_config_keys(parsed, changeCfg));
+        config = merge_config(config, parsed);
+    }
+    return [config, problems];
+}

package/dist/src/project_init.d.ts

@@ -0,0 +1,4 @@
+import { type JsonMap } from "./core.ts";
+export declare function project_init(repoRootRaw?: string, opts?: {
+    force?: boolean;
+}): JsonMap;

package/dist/src/project_init.js

@@ -0,0 +1,161 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_OPENSPEC_CODEX_SKILLS, block, reason, read_agent_toml_name, read_skill_frontmatter_name, commandExists, runCommand, } from "./core.js";
+import { install_workflow } from "./install_engine.js";
+const ROLE_DESCRIPTIONS = {
+    architect: "System design, boundaries, interfaces, and long-horizon tradeoffs",
+    critic: "Critical review of plans, evidence, assumptions, and scope drift",
+    "test-engineer": "Test strategy, coverage, and RED/GREEN evidence review",
+    "code-reviewer": "Code/spec/security review lane for the code-review workflow",
+    verifier: "Final completion evidence and verification review",
+};
+function commandFailure(proc) {
+    return (proc.error?.message ?? (proc.stderr || proc.stdout)).trim();
+}
+function openspecSkillProblems(repoRoot) {
+    const skillsRoot = join(repoRoot, ".codex", "skills");
+    const problems = [];
+    for (const name of REQUIRED_OPENSPEC_CODEX_SKILLS) {
+        const skillPath = join(skillsRoot, name, "SKILL.md");
+        if (!existsSync(skillPath) || !statSync(skillPath).isFile()) {
+            problems.push(name);
+            continue;
+        }
+        if (read_skill_frontmatter_name(skillPath) !== name)
+            problems.push(name);
+    }
+    return problems.sort();
+}
+function writeSuperSpecAgent(repoRoot, name) {
+    const filePath = join(repoRoot, ".codex", "agents", `${name}.toml`);
+    mkdirSync(join(repoRoot, ".codex", "agents"), { recursive: true });
+    writeFileSync(filePath, [
+        `name = "${name}"`,
+        `description = "${ROLE_DESCRIPTIONS[name] ?? `superspec ${name} role`}"`,
+        'model_reasoning_effort = "high"',
+        'developer_instructions = """',
+        `You are the repo-local superspec ${name} native subagent.`,
+        "Follow the assigned superspec gate evidence task, cite concrete files, and report blockers upward.",
+        "Do not substitute main-thread self-review for required role evidence.",
+        '"""',
+        "",
+    ].join("\n"), "utf8");
+    return filePath;
+}
+function writeSuperSpecPrompt(repoRoot, name) {
+    const filePath = join(repoRoot, ".codex", "prompts", `${name}.md`);
+    mkdirSync(join(repoRoot, ".codex", "prompts"), { recursive: true });
+    writeFileSync(filePath, [
+        "---",
+        `description: "${ROLE_DESCRIPTIONS[name] ?? `superspec ${name} role`}"`,
+        'argument-hint: "superspec gate evidence task"',
+        "---",
+        "",
+        `You are the repo-local superspec ${name} role.`,
+        "",
+        "Review the provided superspec gate context with concrete file-backed evidence. Produce a concise pass/block report, cite source anchors and target refs, and do not replace required native-subagent evidence with main-thread self-review.",
+        "",
+    ].join("\n"), "utf8");
+    return filePath;
+}
+function ensureOpenSpecCodex(repoRoot, actions) {
+    if (!commandExists("openspec", { cwd: repoRoot }))
+        return ["openspec CLI is not available in PATH"];
+    let problems = openspecSkillProblems(repoRoot);
+    if (problems.length === 0) {
+        actions.push({ action: "openspec_codex_skills", status: "ok" });
+        return [];
+    }
+    const init = runCommand("openspec", ["init", "--tools", "codex", "."], { cwd: repoRoot, timeout: 60_000 });
+    actions.push({
+        action: "openspec init --tools codex .",
+        status: init.status === 0 ? "updated" : "failed",
+        refs: problems,
+        detail: init.status === 0 ? undefined : (init.stderr || init.stdout).trim(),
+    });
+    if (init.error || init.status !== 0)
+        return [`openspec init failed: ${commandFailure(init)}`];
+    problems = openspecSkillProblems(repoRoot);
+    if (problems.length === 0)
+        return [];
+    const update = runCommand("openspec", ["update", "--force", "."], { cwd: repoRoot, timeout: 60_000 });
+    actions.push({
+        action: "openspec update --force .",
+        status: update.status === 0 ? "updated" : "failed",
+        refs: problems,
+        detail: update.status === 0 ? undefined : (update.stderr || update.stdout).trim(),
+    });
+    if (update.error || update.status !== 0)
+        return [`openspec update failed: ${commandFailure(update)}`];
+    problems = openspecSkillProblems(repoRoot);
+    return problems.length === 0 ? [] : [`OpenSpec Codex skills remain missing/invalid: ${problems.join(", ")}`];
+}
+function ensureSuperSpecRoles(repoRoot, actions) {
+    const problems = [];
+    const created = [];
+    for (const name of REQUIRED_SUPERSPEC_AGENT_ROLES) {
+        const agentPath = join(repoRoot, ".codex", "agents", `${name}.toml`);
+        if (!existsSync(agentPath) || !statSync(agentPath).isFile()) {
+            created.push(writeSuperSpecAgent(repoRoot, name));
+        }
+        else if (read_agent_toml_name(agentPath) !== name) {
+            problems.push(`invalid agent ${agentPath}`);
+        }
+        const promptPath = join(repoRoot, ".codex", "prompts", `${name}.md`);
+        if (!existsSync(promptPath) || !statSync(promptPath).isFile()) {
+            created.push(writeSuperSpecPrompt(repoRoot, name));
+        }
+        else if (!readFileSync(promptPath, "utf8").trim()) {
+            problems.push(`empty prompt ${promptPath}`);
+        }
+    }
+    actions.push({
+        action: "superspec_repo_local_roles",
+        status: problems.length > 0 ? "failed" : created.length > 0 ? "created" : "ok",
+        refs: created.length > 0 ? created : undefined,
+    });
+    return problems;
+}
+// D4 (audit G-1): SuperSpec's own surfaces are installed manifest-driven from the install map;
+// it runs before the role fallback generator so canonical templates win on fresh installs.
+function ensureSuperSpecWorkflow(repoRoot, actions, force) {
+    const result = install_workflow(repoRoot, { force, scope: "project" });
+    for (const item of result.actions) {
+        actions.push({
+            action: item.action,
+            status: item.status === "removed" || item.status === "would_remove" ? "updated" : item.status,
+            refs: item.refs,
+            detail: item.detail,
+        });
+    }
+    return result.problems;
+}
+export function project_init(repoRootRaw = process.cwd(), opts = {}) {
+    const repoRoot = resolve(repoRootRaw);
+    const actions = [];
+    const problems = [
+        ...ensureOpenSpecCodex(repoRoot, actions),
+        ...ensureSuperSpecWorkflow(repoRoot, actions, opts.force === true),
+        ...ensureSuperSpecRoles(repoRoot, actions),
+    ];
+    if (problems.length > 0) {
+        const decision = block("project", "project_init", problems.map((item) => reason("project_init_failed", item)));
+        return {
+            ...decision,
+            project_root: repoRoot,
+            actions,
+            next_allowed_actions: ["fix project_init_failed reasons, then rerun superspec init --scope project"],
+        };
+    }
+    return {
+        allowed: true,
+        decision: "allow",
+        change_id: null,
+        gate: "project_init",
+        project_root: repoRoot,
+        actions,
+        block_reasons: [],
+        next_allowed_actions: ["create/select a change during superspec-explore, then run change-scoped guard checks"],
+        trust_warnings: ["project init installs project surfaces only; change sidecars are created lazily by later superspec phases"],
+    };
+}

package/dist/src/state.d.ts

@@ -0,0 +1,37 @@
+import type { JsonMap, Reason } from "./util.ts";
+export declare function state_file(changeRoot: string): string;
+export declare function ledger_file(changeRoot: string): string;
+export declare function load_state(changeRoot: string): JsonMap | null;
+export declare function state_file_corrupt(changeRoot: string): boolean;
+export declare function state_corrupt_reasons(changeRoot: string): Reason[];
+export declare function read_ledger_text(changeRoot: string): string;
+export declare function compute_fingerprints(changeRoot: string, status: JsonMap): JsonMap;
+export declare function state_stale_reasons(changeRoot: string, status: JsonMap): Reason[];
+export declare function materialize_ledger_event(event: JsonMap): JsonMap;
+export declare function ledger_event_line(event: JsonMap): string;
+export declare function with_state_lock<T>(changeRoot: string, fn: () => T): T;
+export declare function force_unlock_state(changeRoot: string): boolean;
+export declare function prepare_recomputed_state_write(change: string, changeRoot: string, status: JsonMap, guardRoutePhase: string, activeGate: string, decision: JsonMap, opts?: {
+    config?: JsonMap | null;
+    preset_upgrade_required?: boolean;
+    fingerprints?: JsonMap | null;
+}): JsonMap;
+export declare function write_prepared_state_locked(changeRoot: string, prepared: JsonMap): void;
+export declare function restore_state_snapshot_locked(changeRoot: string, snapshot: {
+    state_text: string | null;
+    ledger_text: string;
+}): void;
+export declare function write_state_atomic(changeRoot: string, state: JsonMap, opts?: {
+    expected_state_fingerprints?: JsonMap | null;
+    ledger_event?: JsonMap | null;
+}): void;
+export declare function append_ledger(changeRoot: string, event: JsonMap): void;
+export declare function record_supersede_ledger_events(change: string, changeRoot: string, evidences: JsonMap[]): void;
+export declare function recompute_and_write_state_locked(change: string, changeRoot: string, status: JsonMap, guardRoutePhase: string, activeGate: string, decision: JsonMap, opts?: {
+    config?: JsonMap | null;
+    preset_upgrade_required?: boolean;
+}): JsonMap;
+export declare function recompute_and_write_state(change: string, changeRoot: string, status: JsonMap, guardRoutePhase: string, activeGate: string, decision: JsonMap, opts?: {
+    config?: JsonMap | null;
+    preset_upgrade_required?: boolean;
+}): JsonMap;