@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/verification/declaration.d.ts

@@ -0,0 +1,23 @@
+import type { Preparation } from "../core/decide.js";
+import { type ContractId, type DocumentSegmentKey, type Gate } from "../core/facts/types.js";
+export type VerificationExecutor = "bash" | "zsh" | "pwsh";
+export type VerificationDeclaration = Readonly<{
+    readonly executor: VerificationExecutor;
+    readonly script: string;
+    readonly timeoutMs?: number;
+}>;
+export type VerificationDefinition = Readonly<{
+    readonly segment: DocumentSegmentKey;
+    readonly declarations: readonly VerificationDeclaration[];
+}>;
+export type VerificationDeclarationRefusal = Readonly<{
+    kind: "verification-declaration-invalid";
+    contractId?: ContractId;
+}>;
+export type VerificationDeclarationPreparation = Preparation<VerificationDefinition | null, VerificationDeclarationRefusal>;
+export declare const VERIFIED: Gate;
+export declare function prepareVerificationDeclaration(input: Readonly<{
+    gates: readonly Gate[];
+    definition: VerificationDefinition | null;
+    contractId?: ContractId;
+}>): VerificationDeclarationPreparation;

package/build/src/verification/declaration.js

@@ -0,0 +1,14 @@
+import { gate } from "../core/facts/types.js";
+export const VERIFIED = gate("verified");
+export function prepareVerificationDeclaration(input) {
+    if (input.definition !== null || !input.gates.includes(VERIFIED)) {
+        return { kind: "prepared", data: input.definition };
+    }
+    return {
+        kind: "refused",
+        refusal: {
+            kind: "verification-declaration-invalid",
+            ...(input.contractId === undefined ? {} : { contractId: input.contractId }),
+        },
+    };
+}

package/build/src/verification/execution.d.ts

@@ -0,0 +1,49 @@
+import type { SnapshotId } from "../core/facts/types.js";
+import { type HookFailure } from "../git/hooks.js";
+import type { MaterializedScratchCandidate, WorktreeLeak } from "../git/scratch.js";
+import type { GitRepository } from "../git/repository.js";
+import type { Settings } from "../settings.js";
+import type { VerificationDeclaration } from "./declaration.js";
+type VerificationVerdict = "satisfied" | "unsatisfied";
+export type VerificationTerminalOutcome = Readonly<{
+    kind: "terminal";
+    verdict: VerificationVerdict;
+    summary?: string;
+}>;
+export type VerificationNonterminalOutcome = Readonly<{
+    kind: "unknown-exit";
+}> | Readonly<{
+    kind: "cancelled";
+}> | Readonly<{
+    kind: "spawn-error";
+    diagnostic: string;
+}>;
+export type VerificationExecutionStop = VerificationNonterminalOutcome | Readonly<{
+    kind: "candidate-unavailable" | "environment-failure";
+    diagnostic: string;
+}> | Readonly<{
+    kind: "environment-failure";
+    command: number;
+    detail: HookFailure;
+}>;
+export type VerificationExecution = Readonly<{
+    outcome: VerificationTerminalOutcome | VerificationExecutionStop;
+    cleanup?: Readonly<{
+        phase: "destroy";
+        command: number;
+        detail: HookFailure;
+    }>;
+    leak?: WorktreeLeak;
+}>;
+export type ExecuteVerificationInput = Readonly<{
+    repository: GitRepository;
+    candidate: SnapshotId;
+    declarations: readonly VerificationDeclaration[];
+    environment: NodeJS.ProcessEnv;
+    materializeScratchCandidate: (repository: GitRepository, candidate: SnapshotId) => MaterializedScratchCandidate;
+    projectSettings: (root: string) => Settings;
+    signal?: AbortSignal;
+}>;
+/** Execute one disposable Verification attempt over the exact integration snapshot. */
+export declare function executeVerification(input: ExecuteVerificationInput): Promise<VerificationExecution>;
+export {};

package/build/src/verification/execution.js

@@ -0,0 +1,104 @@
+import { runHookCommands, worktreeHooksFrom } from "../git/hooks.js";
+import { runProcess } from "../runtime/proc/run.js";
+const SUMMARY_BYTES = 32 * 1024;
+function argvFor(declaration) {
+    const args = declaration.executor === "pwsh" ? ["-Command", declaration.script] : ["-c", declaration.script];
+    return [declaration.executor, ...args];
+}
+function processDiagnostic(declaration, index, outcome) {
+    if (outcome.code === 0 && outcome.stdout.length === 0 && outcome.stderr.length === 0 && !outcome.truncated) {
+        return null;
+    }
+    return [
+        `[${index + 1} ${declaration.executor} exit ${outcome.code}${outcome.truncated ? " output-truncated" : ""}]`,
+        ...(outcome.stdout.length === 0 ? [] : [`stdout:\n${outcome.stdout}`]),
+        ...(outcome.stderr.length === 0 ? [] : [`stderr:\n${outcome.stderr}`]),
+    ].join("\n");
+}
+function appendSummary(current, diagnostic) {
+    if (diagnostic === null)
+        return current;
+    const combined = Buffer.from(current === undefined ? diagnostic : `${current}\n\n${diagnostic}`);
+    if (combined.length <= SUMMARY_BYTES)
+        return combined.toString("utf8");
+    const marker = Buffer.from("[earlier output truncated]\n");
+    let start = combined.length - (SUMMARY_BYTES - marker.length);
+    while (start < combined.length && (combined[start] & 0xc0) === 0x80)
+        start += 1;
+    return Buffer.concat([marker, combined.subarray(start)]).toString("utf8");
+}
+async function executeDeclarations(input) {
+    let verdict = "satisfied";
+    let summary;
+    for (const [index, declaration] of input.declarations.entries()) {
+        const outcome = await runProcess({
+            argv: argvFor(declaration),
+            cwd: input.cwd,
+            env: input.environment,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(declaration.timeoutMs === undefined ? {} : { timeoutMs: declaration.timeoutMs }),
+        });
+        if (outcome.kind === "timeout") {
+            verdict = "unsatisfied";
+            summary = appendSummary(summary, `[${index + 1} ${declaration.executor} timeout after ${declaration.timeoutMs}ms]`);
+            continue;
+        }
+        if (outcome.kind === "spawn-error" || outcome.kind === "unknown-exit" || outcome.kind === "cancelled")
+            return outcome;
+        if (outcome.code !== 0)
+            verdict = "unsatisfied";
+        summary = appendSummary(summary, processDiagnostic(declaration, index, outcome));
+    }
+    return { kind: "terminal", verdict, ...(summary === undefined ? {} : { summary }) };
+}
+/** Execute one disposable Verification attempt over the exact integration snapshot. */
+export async function executeVerification(input) {
+    let scratch;
+    try {
+        scratch = input.materializeScratchCandidate(input.repository, input.candidate);
+    }
+    catch (error) {
+        return { outcome: { kind: "candidate-unavailable", diagnostic: error instanceof Error ? error.message : String(error) } };
+    }
+    let outcome;
+    let cleanup;
+    let leak = null;
+    let destroy;
+    try {
+        try {
+            const hooks = worktreeHooksFrom({ settings: input.projectSettings(scratch.cwd) });
+            destroy = hooks.destroy;
+            const readiness = await runHookCommands(scratch.cwd, hooks.create, input.signal);
+            outcome = readiness.kind === "cancelled"
+                ? { kind: "cancelled" }
+                : readiness.kind === "failed"
+                    ? { kind: "environment-failure", command: readiness.command, detail: readiness.failure }
+                    : await executeDeclarations({
+                        declarations: input.declarations,
+                        cwd: scratch.cwd,
+                        environment: input.environment,
+                        ...(input.signal === undefined ? {} : { signal: input.signal }),
+                    });
+        }
+        catch (error) {
+            outcome = { kind: "environment-failure", diagnostic: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    finally {
+        if (destroy !== undefined) {
+            const result = await runHookCommands(scratch.cwd, destroy);
+            if (result.kind === "cancelled")
+                throw new Error("scratch destroy cancelled without a signal");
+            if (result.kind === "failed")
+                cleanup = { phase: "destroy", command: result.command, detail: result.failure };
+        }
+        leak = scratch.dispose();
+    }
+    if (outcome === undefined)
+        throw new Error("Verification ended without an outcome");
+    return {
+        outcome,
+        ...(cleanup === undefined ? {} : { cleanup }),
+        ...(leak === null ? {} : { leak }),
+    };
+}

package/build/src/world.d.ts

@@ -0,0 +1,13 @@
+declare const WORLD_BRAND: unique symbol;
+export type WorldRoot = string & {
+    readonly [WORLD_BRAND]: true;
+};
+export declare class WorldError extends Error {
+    readonly kind: "invalid-world" | "home-world" | "root-world";
+    constructor(kind: "invalid-world" | "home-world" | "root-world", message: string);
+}
+export declare const World: Readonly<{
+    locate(input: string): WorldRoot | null;
+    at(input: string): WorldRoot;
+}>;
+export {};

package/build/src/world.js

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, parse, resolve } from "node:path";
+const WORLD_BRAND = Symbol("keiyaku.world");
+export class WorldError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "WorldError";
+        this.kind = kind;
+    }
+}
+function homeRoot() {
+    try {
+        return realpathSync(resolve(homedir()));
+    }
+    catch {
+        return resolve(homedir());
+    }
+}
+function directory(input, label) {
+    if (typeof input !== "string" || input.trim().length === 0) {
+        throw new TypeError(`${label} must be a nonblank path`);
+    }
+    const path = resolve(input);
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch (error) {
+        throw new WorldError("invalid-world", `world path is not an existing directory: ${path}`);
+    }
+    try {
+        if (!statSync(real).isDirectory())
+            throw new Error("not a directory");
+    }
+    catch {
+        throw new WorldError("invalid-world", `world path is not a directory: ${real}`);
+    }
+    return real;
+}
+function brand(path) { return path; }
+function marker(root) { return join(root, ".keiyaku"); }
+function rejectReservedRoot(root) {
+    if (root === homeRoot()) {
+        throw new WorldError("home-world", "the user home directory cannot be a Keiyaku world");
+    }
+    if (root === parse(root).root) {
+        throw new WorldError("root-world", "the filesystem root cannot be a Keiyaku world");
+    }
+}
+function ensureMarker(root) {
+    const path = marker(root);
+    if (existsSync(path)) {
+        try {
+            if (!statSync(path).isDirectory())
+                throw new Error("not a directory");
+        }
+        catch {
+            throw new WorldError("invalid-world", `world marker is not a directory: ${path}`);
+        }
+        return;
+    }
+    mkdirSync(path, { recursive: true });
+}
+function exact(input) {
+    const root = directory(input, "world");
+    rejectReservedRoot(root);
+    ensureMarker(root);
+    return brand(root);
+}
+function locateInput(input) {
+    return directory(input, "world location");
+}
+export const World = Object.freeze({
+    locate(input) {
+        let candidate = locateInput(input);
+        const home = homeRoot();
+        for (;;) {
+            const filesystemRoot = parse(candidate).root;
+            if (candidate !== home && candidate !== filesystemRoot && existsSync(marker(candidate))) {
+                try {
+                    if (!statSync(marker(candidate)).isDirectory()) {
+                        throw new WorldError("invalid-world", `world marker is not a directory: ${marker(candidate)}`);
+                    }
+                }
+                catch (error) {
+                    if (error instanceof WorldError)
+                        throw error;
+                    throw new WorldError("invalid-world", `world marker is not a directory: ${marker(candidate)}`);
+                }
+                return brand(candidate);
+            }
+            const parent = dirname(candidate);
+            if (parent === candidate || candidate === filesystemRoot)
+                return null;
+            candidate = parent;
+        }
+    },
+    at(input) {
+        return exact(input);
+    },
+});

package/package.json

@@ -1,58 +1,79 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "2.9.13",
-  "description": "CLI for running iterative keiyaku workflows with Codex subagents.",
-  "license": "MIT",
+  "version": "4.0.1",
+  "files": [
+    "build"
+  ],
+  "main": "./build/src/index.js",
+  "types": "./build/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/src/index.d.ts",
+      "import": "./build/src/index.js"
+    },
+    "./task": {
+      "types": "./build/src/task/index.d.ts",
+      "import": "./build/src/task/index.js"
+    },
+    "./kanshi": {
+      "types": "./build/src/kanshi/index.d.ts",
+      "import": "./build/src/kanshi/index.js"
+    },
+    "./akuma": {
+      "types": "./build/src/akuma/index.d.ts",
+      "import": "./build/src/akuma/index.js"
+    }
+  },
+  "bin": {
+    "keiyaku": "build/src/cli/index.js"
+  },
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
   },
-  "main": "./build/index.js",
-  "bin": {
-    "keiyaku": "build/index.js"
+  "scripts": {
+    "build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('build', { recursive: true, force: true })\" && tsc -p tsconfig.json && node scripts/copy-integrations.js && node --input-type=module -e \"import { chmodSync } from 'node:fs'; chmodSync('build/src/cli/index.js', 0o755)\"",
+    "review:model-impact": "node --import tsx scripts/model-change-impact.ts",
+    "test": "npm run test:architecture && npm run test:maintainability && npm run test:reachability && node --import tsx scripts/run-tests.mjs",
+    "test:architecture": "node --import tsx scripts/check-architecture.ts",
+    "test:e2e": "npm run build && node --import tsx --test tests/packaged-cli.e2e.ts",
+    "test:maintainability": "node scripts/check-maintainability.js",
+    "test:focused": "node --import tsx --test --test-reporter=dot",
+    "test:reachability": "knip --include files,dependencies,unlisted,unresolved,duplicates",
+    "test:typecheck": "tsc -p tsconfig.json --noEmit"
   },
-  "files": [
-    "build",
-    "skills",
-    "README.md"
-  ],
-  "exports": {
-    ".": "./build/index.js"
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "@typescript-eslint/parser": "^8.66.0",
+    "eslint": "^9.39.5",
+    "knip": "^6.31.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.226",
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@opencode-ai/sdk": "1.18.3",
+    "diff": "^8.0.4",
+    "yaml": "^2.9.0"
   },
+  "description": "Keiyaku is an agent-facing contract workflow.",
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "sync:version": "node scripts/generate-version.mjs",
-    "preversion": "npm test --silent",
-    "version": "npm run sync:version --silent && git add src/generated/version.ts",
-    "dev": "npx tsx src/index.ts",
-    "build": "node scripts/build.mjs",
-    "test:typecheck": "npx tsc --project tsconfig.tests.json",
-    "prepublishOnly": "npm run build",
-    "start": "node build/index.js",
-    "test:unit": "node scripts/run-unit-tests.mjs",
-    "test:boundaries": "node scripts/check-import-boundaries.mjs",
-    "test:integration": "node --import ./tests/support/real-provider-path-sentinel.mjs --import tsx --test --test-concurrency=4 tests/integration/*.test.ts",
-    "pretest:cli-expect": "npm run build",
-    "test:cli-expect": "node --import ./tests/support/real-provider-path-sentinel.mjs --test --test-concurrency=8 tests/cli-expect/suite/*.test.mjs",
-    "test:real-providers": "KEIYAKU_REAL_PROVIDERS=1 node --import tsx --test --test-concurrency=1 tests/real-provider/matrix.test.ts",
-    "test": "npm run test:unit && npm run test:typecheck && npm run test:boundaries && npm run test:integration && npm run test:cli-expect",
-    "release": "npm version patch && npm publish"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astrosheep-zero/keiyaku.git"
   },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.204",
-    "@anthropic-ai/sdk": "^0.110.0",
-    "@earendil-works/pi-coding-agent": "^0.80.10",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opencode-ai/sdk": "1.18.3",
-    "simple-git": "^3.21.0",
-    "yaml": "^2.9.0",
-    "zod": "4.3.6"
+  "bugs": {
+    "url": "https://github.com/astrosheep-zero/keiyaku/issues"
   },
-  "devDependencies": {
-    "@types/node": "25.2.2",
-    "tsx": "4.23.0",
-    "typescript": "5.9.3"
-  }
+  "homepage": "https://github.com/astrosheep-zero/keiyaku#readme"
 }