@peterxiaoyang/superspec 0.1.7 → 0.1.8

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

@@ -0,0 +1,4 @@
+import type { Reason } from "../util.ts";
+export declare function hookManifestHash(repoRoot: string): string | null;
+export declare function managedHooksManifestPresent(repoRoot: string): boolean;
+export declare function hookInitReasons(repoRoot: string): Reason[];

package/dist/src/hooks/health.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { reason, sha256_file } from "../util.js";
+import { HOOK_ADAPTER_VERSION } from "./types.js";
+const HOOK_COMMAND = 'superspec-hook --change "$SUPERSPEC_CHANGE"';
+const EXPECTED_HOOK_MATRIX = [
+    {
+        eventName: "PreToolUse",
+        matcher: "Bash|apply_patch|Edit|Write|mcp__.*",
+        timeout: 10,
+        statusMessage: "SuperSpec hook write policy",
+    },
+    {
+        eventName: "PostToolUse",
+        matcher: "Bash",
+        timeout: 30,
+        statusMessage: "SuperSpec hook runtime evidence",
+    },
+    {
+        eventName: "SubagentStart",
+        matcher: ".*",
+        timeout: 30,
+        statusMessage: "SuperSpec hook subagent start",
+    },
+    {
+        eventName: "SubagentStop",
+        matcher: ".*",
+        timeout: 30,
+        statusMessage: "SuperSpec hook subagent stop",
+    },
+];
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function hookEntryMatches(entry, expected) {
+    if (entry.matcher !== expected.matcher)
+        return false;
+    if (!Array.isArray(entry.hooks) || entry.hooks.length !== 1)
+        return false;
+    const hook = entry.hooks[0];
+    if (!isRecord(hook))
+        return false;
+    if (!hasExactKeys(hook, ["type", "command", "timeout", "statusMessage"]))
+        return false;
+    return hook.type === "command"
+        && hook.command === HOOK_COMMAND
+        && hook.timeout === expected.timeout
+        && hook.statusMessage === expected.statusMessage;
+}
+function hookMatrixPresent(parsed) {
+    const hooks = parsed?.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return false;
+    if (!isRecord(hooks))
+        return false;
+    if (!hasExactKeys(hooks, EXPECTED_HOOK_MATRIX.map((entry) => entry.eventName)))
+        return false;
+    return EXPECTED_HOOK_MATRIX.every((expected) => {
+        const entries = hooks[expected.eventName];
+        return Array.isArray(entries)
+            && entries.length === 1
+            && hookEntryMatches(entries[0], expected);
+    });
+}
+export function hookManifestHash(repoRoot) {
+    const hookPath = join(repoRoot, ".codex", "hooks.json");
+    if (!existsSync(hookPath) || !statSync(hookPath).isFile())
+        return null;
+    return sha256_file(hookPath);
+}
+export function managedHooksManifestPresent(repoRoot) {
+    const hookPath = join(repoRoot, ".codex", "hooks.json");
+    if (!existsSync(hookPath) || !statSync(hookPath).isFile())
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(hookPath, "utf8"));
+        return parsed?.superspec?.managed === true
+            && parsed?.superspec?.adapter_version === HOOK_ADAPTER_VERSION
+            && parsed?.superspec?.strict_profile_default === "audit-only-until-r1-provenance-passes"
+            && hookMatrixPresent(parsed);
+    }
+    catch {
+        return false;
+    }
+}
+export function hookInitReasons(repoRoot) {
+    const hookPath = join(repoRoot, ".codex", "hooks.json");
+    if (!existsSync(hookPath))
+        return [];
+    if (managedHooksManifestPresent(repoRoot))
+        return [];
+    return [reason("hook_manifest_unmanaged", ".codex/hooks.json exists but is not the SuperSpec-managed v2 hook manifest; strict profile must downgrade")];
+}

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

@@ -0,0 +1,41 @@
+import type { JsonMap, Reason } from "../util.ts";
+import type { HookEvent } from "./types.ts";
+export type NormalizedHookEvent = {
+    event: HookEvent;
+    hook_event_id: string;
+    hook_event_name: string;
+    session_id: string;
+    cwd: string;
+    tool_name: string;
+    command: string;
+};
+export type WriteExtraction = {
+    target_paths: string[];
+    trust_root_text_matches: string[];
+    archive_command: boolean;
+    internal_hook_writer_command: boolean;
+    unsafe_lifecycle_termination_command: boolean;
+    unsupported_write_surface: boolean;
+    task_checkbox_completions: string[];
+    task_checkbox_reopens: string[];
+    shell_write_command: boolean;
+    reasons: Reason[];
+};
+export declare function readHookEventRef(eventRef: string): HookEvent;
+export declare function normalizeHookEvent(event: HookEvent): NormalizedHookEvent;
+export declare function cleanRelPath(pathValue: string): string;
+export declare function pathsIntersect(a: string, b: string): boolean;
+export declare function isSuperSpecTrustRootPath(pathValue: string, opts?: {
+    changeRootRel?: string;
+}): boolean;
+export declare function anyPathInScope(paths: string[], scope: string): boolean;
+export declare function commandLooksLikeTestValidation(command: string, depth?: number): boolean;
+export declare function extractWriteIntent(event: HookEvent, repoRoot: string): WriteExtraction;
+export declare function eventContentHash(event: HookEvent): string;
+export declare function nonce(): string;
+export declare function relFromChangeOrRepo(repoRoot: string, changeRoot: string, pathValue: string): {
+    root: "repo" | "change";
+    path: string;
+} | null;
+export declare function pinnedFileRef(baseRoot: string, relPath: string): JsonMap | null;
+export declare function renderReasons(reasons: Reason[]): string;