@peterxiaoyang/superspec 0.1.13 → 0.1.15-alpha

package/dist/src/git.d.ts

@@ -1,8 +0,0 @@
-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

@@ -1,112 +0,0 @@
-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_user_confirmations } 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_user_confirmations(evidences, "branch_handling");
-    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/hooks/adapter.d.ts

@@ -1,5 +0,0 @@
-export declare function runHookAdapter(argv?: string[], stdin?: string): {
-    code: number;
-    stdout: string;
-    stderr: string;
-};

package/dist/src/hooks/adapter.js

@@ -1,347 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { tmpdir } from "node:os";
-import { isObject } from "../util.js";
-import { hookCheckCommand, hookCheckWrite, hookRecordSubagentStart, hookRecordSubagentStop, hookRecordTest, } from "./guard_api.js";
-import { commandLooksLikeTestValidation, extractWriteIntent, isSuperSpecTrustRootPath } from "./policy_event.js";
-function parseArgs(argv) {
-    let change = process.env.SUPERSPEC_CHANGE || null;
-    for (let idx = 0; idx < argv.length; idx += 1) {
-        if (argv[idx] === "--change")
-            change = argv[idx + 1] || null;
-    }
-    return { change };
-}
-function isDir(path) {
-    try {
-        return statSync(path).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-function readJson(path) {
-    try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        return isObject(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
-function validReasonArray(value) {
-    return Array.isArray(value) && value.every((item) => (isObject(item)
-        && typeof item.code === "string"
-        && item.code.length > 0
-        && typeof item.message === "string"
-        && item.message.length > 0
-        && Array.isArray(item.refs)
-        && item.refs.every((ref) => typeof ref === "string")));
-}
-function validActiveSessionRecord(path, change, repoRoot, event) {
-    const record = readJson(path);
-    if (!record)
-        return false;
-    if (record.schema_version !== 2 || record.kind !== "hook_active_session")
-        return false;
-    if (record.trust !== "audit-only" && record.trust !== "trusted")
-        return false;
-    if (record.strict_profile !== "available" && record.strict_profile !== "unavailable")
-        return false;
-    if (record.change_id !== change)
-        return false;
-    if (resolve(String(record.repo_root ?? "")) !== resolve(repoRoot))
-        return false;
-    if (typeof record.session_id !== "string" || !record.session_id)
-        return false;
-    if (!validReasonArray(record.audit_only_reasons))
-        return false;
-    const eventSessionId = typeof event.session_id === "string" && event.session_id ? event.session_id : "";
-    const auditRepoChangeLeaseFallback = record.trust === "audit-only"
-        && record.strict_profile === "unavailable"
-        && record.session_id === "manual-cli-session";
-    if (eventSessionId && record.session_id !== eventSessionId && !auditRepoChangeLeaseFallback)
-        return false;
-    const expiresAt = Date.parse(String(record.expires_at ?? ""));
-    if (!Number.isFinite(expiresAt) || expiresAt <= Date.now())
-        return false;
-    return true;
-}
-function inferChangeFromActiveSessions(event) {
-    const repoRoot = findRepoRootFromCwd(event);
-    const changesDir = join(repoRoot, "openspec", "changes");
-    if (!isDir(changesDir))
-        return { state: "none" };
-    const candidates = readdirSync(changesDir).filter((change) => {
-        const runtimeDir = join(changesDir, change, ".superspec", "hook-runtime");
-        const activeDir = join(changesDir, change, ".superspec", "hook-runtime", "active-sessions");
-        if (isDir(activeDir) && readdirSync(activeDir).some((name) => (name.endsWith(".json") && validActiveSessionRecord(join(activeDir, name), change, repoRoot, event))))
-            return true;
-        return isDir(runtimeDir);
-    });
-    const unique = [...new Set(candidates)];
-    if (unique.length === 1)
-        return { state: "unique", change: unique[0] };
-    if (unique.length > 1)
-        return { state: "ambiguous", changes: unique.sort() };
-    return { state: "none" };
-}
-function cwdRoot(event) {
-    return typeof event.cwd === "string" && event.cwd ? resolve(event.cwd) : process.cwd();
-}
-function findRepoRootFromCwd(event) {
-    let dir = cwdRoot(event);
-    while (true) {
-        if ((isDir(join(dir, "openspec")) || isDir(join(dir, ".codex"))) && statMaybe(join(dir, "package.json")) === "file")
-            return dir;
-        if (isDir(join(dir, "openspec", "changes")) || isDir(join(dir, ".codex")))
-            return dir;
-        if (statMaybe(join(dir, ".git")))
-            return dir;
-        const parent = dirname(dir);
-        if (parent === dir)
-            return cwdRoot(event);
-        dir = parent;
-    }
-}
-function passThrough(message) {
-    return {
-        hookSpecificOutput: {
-            hookEventName: "PreToolUse",
-            additionalContext: message,
-        },
-    };
-}
-function statMaybe(path) {
-    try {
-        const st = statSync(path);
-        if (st.isFile())
-            return "file";
-        if (st.isDirectory())
-            return "dir";
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
-function denyPreToolUse(reason) {
-    return {
-        hookSpecificOutput: {
-            hookEventName: "PreToolUse",
-            permissionDecision: "deny",
-            permissionDecisionReason: reason,
-        },
-    };
-}
-function isTestValidationCommand(event) {
-    if (String(event.tool_name ?? "") !== "Bash")
-        return false;
-    const toolInput = isObject(event.tool_input) ? event.tool_input : {};
-    const command = typeof toolInput.command === "string" ? toolInput.command : "";
-    return commandLooksLikeTestValidation(command);
-}
-function inertPostToolUseOutput() {
-    return {
-        systemMessage: "SuperSpec hook ignored non-test command; no test telemetry was recorded.",
-        hookSpecificOutput: {
-            hookEventName: "PostToolUse",
-            additionalContext: "SuperSpec runtime telemetry is inert for non-test commands.",
-        },
-    };
-}
-function noChangeFallback(event, inference) {
-    if (String(event.hook_event_name ?? "PreToolUse") !== "PreToolUse") {
-        return { systemMessage: "SuperSpec hook inert: SUPERSPEC_CHANGE/--change not set" };
-    }
-    const intent = extractWriteIntent(event, findRepoRootFromCwd(event));
-    const writeCapable = intent.target_paths.length > 0
-        || intent.archive_command
-        || intent.internal_hook_writer_command
-        || intent.unsupported_write_surface
-        || intent.shell_write_command
-        || intent.reasons.length > 0
-        || ["apply_patch", "Edit", "Write"].includes(String(event.tool_name ?? ""));
-    if (inference.state === "ambiguous" && writeCapable) {
-        return denyPreToolUse(`blocked by SuperSpec hook policy: multiple active SuperSpec sessions (${inference.changes.join(", ")}); set SUPERSPEC_CHANGE or close stale leases`);
-    }
-    if (intent.internal_hook_writer_command) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: internal hook writer invocation requires Guard-owned hook authority");
-    }
-    if (intent.unsafe_lifecycle_termination_command) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: hook session cancellation requires trusted terminal authority");
-    }
-    if (intent.reasons.some((item) => item.code === "target_path_outside_repo")) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: write target escapes the current repository root");
-    }
-    if (intent.reasons.some((item) => item.code === "protected_trust_root_link_source")) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: link source points at a SuperSpec trust root");
-    }
-    if (intent.reasons.some((item) => item.code === "shell_path_may_touch_trust_root")) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: shell-expanded path may touch SuperSpec trust roots");
-    }
-    if (intent.reasons.some((item) => item.code === "curl_config_write_target_unknown")) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: curl config-driven writes have unknown targets");
-    }
-    if (intent.reasons.some((item) => item.code === "curl_write_target_unknown")) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: curl write options have unknown targets");
-    }
-    if (intent.target_paths.some((path) => isSuperSpecTrustRootPath(path))) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: direct writes to SuperSpec trust roots require an active Guard context");
-    }
-    if (intent.shell_write_command && intent.trust_root_text_matches.length > 0) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: pathless write-capable command appears to touch SuperSpec trust roots");
-    }
-    if (intent.archive_command) {
-        return denyPreToolUse("blocked by SuperSpec hook policy: openspec archive requires an active Guard context and archive_ready allow");
-    }
-    return passThrough("SuperSpec hook inert: SUPERSPEC_CHANGE/--change not set");
-}
-function preToolUseOutput(decision) {
-    if (!decision.allowed) {
-        return {
-            hookSpecificOutput: {
-                hookEventName: "PreToolUse",
-                permissionDecision: "deny",
-                permissionDecisionReason: decision.block_reasons.map((item) => item.message).join("; ") || "blocked by SuperSpec hook policy",
-            },
-        };
-    }
-    return {
-        hookSpecificOutput: {
-            hookEventName: "PreToolUse",
-            additionalContext: `SuperSpec hook ${decision.enforcement}; strict_profile=${decision.strict_profile}; trust=${decision.trust}`,
-        },
-    };
-}
-function postToolUseOutput(decision) {
-    return {
-        systemMessage: `SuperSpec hook telemetry recorded as ${decision.trust}; strict_profile=${decision.strict_profile}`,
-        hookSpecificOutput: {
-            hookEventName: "PostToolUse",
-            additionalContext: `SuperSpec runtime evidence is ${decision.strict_profile === "available" ? "runtime-verified" : "audit-only"}.`,
-        },
-    };
-}
-function isSubagentHookEvent(eventName) {
-    return eventName === "SubagentStart" || eventName === "SubagentStop";
-}
-function subagentOutput(decision, eventName) {
-    if (!decision.allowed) {
-        return {
-            systemMessage: `SuperSpec ${eventName} runlog skipped; ${decision.block_reasons.map((item) => item.message).join("; ") || "audit telemetry unavailable"}`,
-            hookSpecificOutput: {
-                hookEventName: eventName,
-                additionalContext: "SuperSpec subagent telemetry is best-effort and did not block the workflow.",
-            },
-        };
-    }
-    return {
-        systemMessage: `SuperSpec ${eventName} runlog recorded as ${decision.trust}; strict_profile=${decision.strict_profile}`,
-    };
-}
-function inertSubagentOutput(eventName, message) {
-    return {
-        systemMessage: message,
-        hookSpecificOutput: {
-            hookEventName: eventName,
-            additionalContext: "SuperSpec subagent telemetry is best-effort and did not block the workflow.",
-        },
-    };
-}
-function writeTempEvent(event) {
-    const path = join(tmpdir(), `superspec-hook-event-${randomUUID()}.json`);
-    writeFileSync(path, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
-    return path;
-}
-function validateHookEvent(event) {
-    const eventName = typeof event.hook_event_name === "string" ? event.hook_event_name : "";
-    if (!eventName)
-        return "hook event missing required hook_event_name";
-    if (!["PreToolUse", "PostToolUse", "SubagentStart", "SubagentStop"].includes(eventName)) {
-        return `unsupported hook_event_name: ${eventName}`;
-    }
-    if ((eventName === "PreToolUse" || eventName === "PostToolUse") && (typeof event.cwd !== "string" || !event.cwd)) {
-        return "hook event missing required cwd";
-    }
-    if (eventName === "PreToolUse") {
-        if (typeof event.tool_name !== "string" || !event.tool_name)
-            return "PreToolUse hook event missing required tool_name";
-        if (!isObject(event.tool_input))
-            return "PreToolUse hook event missing required tool_input object";
-    }
-    return null;
-}
-export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSync(0, "utf8")) {
-    const parsedArgs = parseArgs(argv);
-    let event;
-    let eventNameForFailure = "";
-    try {
-        if (!stdin.trim())
-            throw new Error("hook stdin is empty");
-        const parsed = JSON.parse(stdin);
-        if (!isObject(parsed))
-            throw new Error("hook stdin must be a JSON object");
-        event = parsed;
-        eventNameForFailure = typeof event.hook_event_name === "string" ? event.hook_event_name : "";
-        const validationError = validateHookEvent(event);
-        if (validationError)
-            throw new Error(validationError);
-    }
-    catch (err) {
-        if (isSubagentHookEvent(eventNameForFailure)) {
-            const payload = inertSubagentOutput(eventNameForFailure, `SuperSpec ${eventNameForFailure} runlog skipped: ${err.message}`);
-            return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
-        }
-        return { code: 2, stdout: "", stderr: `SuperSpec hook event parse failed: ${err.message}\n` };
-    }
-    const inference = parsedArgs.change ? { state: "unique", change: parsedArgs.change } : inferChangeFromActiveSessions(event);
-    const change = inference.state === "unique" ? inference.change : null;
-    if (!change) {
-        const payload = noChangeFallback(event, inference);
-        return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
-    }
-    let eventRef = null;
-    try {
-        eventRef = writeTempEvent(event);
-        const eventName = String(event.hook_event_name ?? "");
-        let payload;
-        if (eventName === "PreToolUse") {
-            const toolName = String(event.tool_name ?? "");
-            const decision = toolName === "Bash" ? hookCheckCommand(change, eventRef) : hookCheckWrite(change, eventRef);
-            payload = preToolUseOutput(decision);
-        }
-        else if (eventName === "PostToolUse") {
-            payload = isTestValidationCommand(event) ? postToolUseOutput(hookRecordTest(change, eventRef)) : inertPostToolUseOutput();
-        }
-        else if (eventName === "SubagentStart") {
-            payload = subagentOutput(hookRecordSubagentStart(change, eventRef), "SubagentStart");
-        }
-        else if (eventName === "SubagentStop") {
-            payload = subagentOutput(hookRecordSubagentStop(change, eventRef), "SubagentStop");
-        }
-        else {
-            payload = { systemMessage: `SuperSpec hook ignored unsupported event ${eventName}` };
-        }
-        return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
-    }
-    catch (err) {
-        if (isSubagentHookEvent(String(event.hook_event_name ?? ""))) {
-            const eventName = String(event.hook_event_name ?? "");
-            const payload = inertSubagentOutput(eventName, `SuperSpec ${eventName} runlog skipped: ${err.message}`);
-            return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
-        }
-        return { code: 2, stdout: "", stderr: `SuperSpec hook failed closed: ${err.message}\n` };
-    }
-    finally {
-        if (eventRef) {
-            try {
-                unlinkSync(resolve(eventRef));
-            }
-            catch {
-                // best effort temp cleanup
-            }
-        }
-    }
-}

package/dist/src/hooks/guard_api.d.ts

@@ -1,12 +0,0 @@
-import type { Reason } from "../util.ts";
-import type { HookDecision } from "./types.ts";
-export declare function hookCheckWrite(change: string, eventRef: string): HookDecision;
-export declare function hookCheckCommand(change: string, eventRef: string): HookDecision;
-export declare function hookHealth(change: string): HookDecision;
-export declare function hookSessionBegin(change: string, workflow: string, _entrypointToken: string): HookDecision;
-export declare function hookSessionStatus(change: string): HookDecision;
-export declare function hookSessionEnd(change: string, endReason: string, _lifecycleToken: string): HookDecision;
-export declare function hookRecordTest(change: string, eventRef: string): HookDecision;
-export declare function hookRecordSubagentStart(change: string, eventRef: string): HookDecision;
-export declare function hookRecordSubagentStop(change: string, eventRef: string): HookDecision;
-export declare function hookInitReasons(repoRoot: string): Reason[];