@astrosheep/keiyaku 2.8.5 → 2.9.1

package/build/config/settings/loader.js

@@ -0,0 +1,244 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isErrnoException } from "../../errno.js";
+import { SETTINGS_FILE } from "../../keiyaku.js";
+import { getKeiyakuHome } from "../env.js";
+import { KNOWN_SETTINGS_KNOBS, KNOWN_SETTINGS_ROOT_KEYS } from "./knobs.js";
+import { BUILTIN_PROVIDER_INSTANCE_CANDIDATES, knobSchemas, providerInstanceNameSchema, providerInstanceSchema, } from "./schema.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMerge(base, override) {
+    if (!isPlainObject(base) || !isPlainObject(override)) {
+        return override;
+    }
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        merged[key] = key in merged ? deepMerge(merged[key], value) : value;
+    }
+    return merged;
+}
+function formatZodIssues(error) {
+    return error.issues
+        .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+        .join("; ");
+}
+async function readSettingsSource(filePath) {
+    try {
+        const text = await fs.readFile(filePath, "utf-8");
+        try {
+            return { found: true, raw: JSON.parse(text) };
+        }
+        catch (error) {
+            const reason = error instanceof SyntaxError
+                ? `invalid JSON: ${error.message}`
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            return { found: true, raw: undefined, parseError: reason };
+        }
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT") {
+            return { found: false };
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        return { found: true, raw: undefined, parseError: reason };
+    }
+}
+function builtinProviderInstanceCatalog() {
+    return { selected: { ...BUILTIN_PROVIDER_INSTANCE_CANDIDATES }, shadows: [] };
+}
+function formatProviderInstanceIssues(name, error) {
+    return error.issues
+        .map((issue) => {
+        const suffix = issue.path.length === 0 ? "" : `.${issue.path.join(".")}`;
+        return `providers.${name}${suffix}: ${issue.message}`;
+    })
+        .join("; ");
+}
+function collectProviderCandidates(source, rawProviders) {
+    if (!isPlainObject(rawProviders)) {
+        return {
+            candidates: [],
+            disease: { source: source === "project" ? "local" : "global", knob: "providers", reason: "providers: must be a JSON object" },
+        };
+    }
+    const candidates = [];
+    for (const [name, rawInstance] of Object.entries(rawProviders)) {
+        const nameResult = providerInstanceNameSchema.safeParse(name);
+        if (!nameResult.success) {
+            candidates.push({
+                name,
+                source,
+                reason: formatProviderInstanceIssues(name, nameResult.error),
+            });
+            continue;
+        }
+        const instanceResult = providerInstanceSchema.safeParse(rawInstance);
+        if (!instanceResult.success) {
+            candidates.push({
+                name,
+                source,
+                reason: formatProviderInstanceIssues(name, instanceResult.error),
+            });
+            continue;
+        }
+        const instance = instanceResult.data;
+        if (instance.kind === "codex-app-server" && instance.writableRoots !== undefined && source === "global") {
+            let relativeIndex;
+            for (let i = 0; i < instance.writableRoots.length; i++) {
+                if (!path.posix.isAbsolute(instance.writableRoots[i])) {
+                    relativeIndex = i;
+                    break;
+                }
+            }
+            if (relativeIndex !== undefined) {
+                candidates.push({
+                    name,
+                    source,
+                    reason: `providers.${name}.writableRoots.${relativeIndex}: writableRoots item must be an absolute path for global provider instances`,
+                });
+                continue;
+            }
+        }
+        candidates.push({ name, source, instance: instanceResult.data });
+    }
+    return { candidates };
+}
+function mergeProviderCandidates(catalog, candidates) {
+    const selected = { ...catalog.selected };
+    const shadows = [...catalog.shadows];
+    for (const candidate of candidates) {
+        const prior = selected[candidate.name];
+        if (prior !== undefined) {
+            shadows.push({ name: candidate.name, source: prior.source, shadowedBy: candidate.source });
+        }
+        selected[candidate.name] = candidate;
+    }
+    return { selected, shadows };
+}
+function collectSourceDiseases(source, providerSource, read) {
+    if (!read.found) {
+        return { partial: {}, diseases: [], providerCandidates: [] };
+    }
+    if (read.parseError !== undefined) {
+        return {
+            partial: {},
+            diseases: [{ source, reason: `settings root is unreadable (${read.parseError})` }],
+            providerCandidates: [],
+        };
+    }
+    if (!isPlainObject(read.raw)) {
+        return {
+            partial: {},
+            diseases: [{ source, reason: "settings root must be a JSON object" }],
+            providerCandidates: [],
+        };
+    }
+    const diseases = [];
+    const partial = {};
+    let providerCandidates = [];
+    const raw = read.raw;
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_SETTINGS_ROOT_KEYS.includes(key)) {
+            diseases.push({
+                source,
+                knob: key,
+                reason: key === "agents"
+                    ? 'settings key "agents" has been removed; define profiles in .keiyaku/akuma/<name>.md'
+                    : `unknown settings key "${key}"`,
+            });
+        }
+    }
+    if ("providers" in raw) {
+        const collectedProviders = collectProviderCandidates(providerSource, raw.providers);
+        providerCandidates = collectedProviders.candidates;
+        if (collectedProviders.disease !== undefined)
+            diseases.push(collectedProviders.disease);
+    }
+    for (const knob of KNOWN_SETTINGS_KNOBS) {
+        if (!(knob in raw))
+            continue;
+        // worktreeBootstrap is project-layer only. Global/user presence is a named
+        // disease and never contributes execution authority.
+        if (knob === "worktreeBootstrap" && source === "global") {
+            diseases.push({
+                source,
+                knob,
+                reason: "worktreeBootstrap is project-only and never supplies a value from global settings",
+            });
+            continue;
+        }
+        const schema = knobSchemas[knob];
+        const result = schema.safeParse(raw[knob]);
+        if (!result.success) {
+            diseases.push({
+                source,
+                knob,
+                reason: formatZodIssues(result.error),
+            });
+            continue;
+        }
+        if (result.data === undefined)
+            continue;
+        partial[knob] = result.data;
+    }
+    return { partial, diseases, providerCandidates };
+}
+function mergeSettingsKnobs(base, override) {
+    // worktreeBootstrap is whole-value project authority; never field-merge it.
+    const { worktreeBootstrap: baseBootstrap, ...baseRest } = base;
+    const { worktreeBootstrap: overrideBootstrap, ...overrideRest } = override;
+    const mergedRaw = deepMerge(baseRest, overrideRest);
+    if (!isPlainObject(mergedRaw)) {
+        return overrideBootstrap !== undefined
+            ? { ...override, worktreeBootstrap: overrideBootstrap }
+            : { ...override };
+    }
+    const merged = {};
+    for (const knob of KNOWN_SETTINGS_KNOBS) {
+        if (knob === "worktreeBootstrap")
+            continue;
+        if (knob in mergedRaw) {
+            merged[knob] = mergedRaw[knob];
+        }
+    }
+    const bootstrap = overrideBootstrap ?? baseBootstrap;
+    if (bootstrap !== undefined)
+        merged.worktreeBootstrap = bootstrap;
+    return merged;
+}
+export async function loadKeiyakuSettings(cwd) {
+    const localSettingsPath = path.join(cwd, SETTINGS_FILE);
+    const globalSettingsPath = path.join(getKeiyakuHome(), path.basename(SETTINGS_FILE));
+    let globalRead;
+    let localRead;
+    try {
+        [globalRead, localRead] = await Promise.all([
+            readSettingsSource(globalSettingsPath),
+            readSettingsSource(localSettingsPath),
+        ]);
+    }
+    catch (error) {
+        // loadKeiyakuSettings never throws; unexpected I/O becomes a local root disease.
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            knobs: null,
+            diseases: [{ source: "local", reason: `settings root is unreadable (${reason})` }],
+            providerInstances: builtinProviderInstanceCatalog(),
+        };
+    }
+    const globalCollected = collectSourceDiseases("global", "global", globalRead);
+    const localCollected = collectSourceDiseases("local", "project", localRead);
+    const diseases = [...globalCollected.diseases, ...localCollected.diseases];
+    let providerInstances = builtinProviderInstanceCatalog();
+    providerInstances = mergeProviderCandidates(providerInstances, globalCollected.providerCandidates);
+    providerInstances = mergeProviderCandidates(providerInstances, localCollected.providerCandidates);
+    let knobs = null;
+    if (globalRead.found || localRead.found) {
+        knobs = mergeSettingsKnobs(globalCollected.partial, localCollected.partial);
+    }
+    // Empty object still means "settings files were present"; callers treat null as absent files.
+    return { knobs, diseases, providerInstances };
+}

package/build/config/settings/schema.js

@@ -0,0 +1,276 @@
+import { z } from "zod";
+import { CLAUDE_SETTING_SOURCES, } from "../../keiyaku.js";
+const tomlValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.array(tomlValueSchema),
+    z.record(z.string(), tomlValueSchema),
+]));
+const structuredTomlValueSchema = z.record(z.string(), tomlValueSchema);
+const executableSchema = z.string().superRefine((value, ctx) => {
+    if (value.length === 0 || /\s/.test(value) || value.includes("\"") || value.includes("'")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "must be a single program name token with no spaces or quotes.",
+        });
+    }
+});
+const nonblankOptionalString = z
+    .string()
+    .refine((value) => value.trim().length > 0, { message: "must not be blank." })
+    .optional();
+const providerCommonFields = {
+    description: nonblankOptionalString,
+};
+const providerEnvSchema = z.record(z.string(), z.string()).optional();
+function refinePiEnvInjection(data, ctx) {
+    if (data.env === undefined)
+        return;
+    if (Object.keys(data.env).length === 0)
+        return;
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["env"],
+        message: "env injection not supported for provider pi",
+    });
+}
+const CODEX_SDK_FORBIDDEN_THREAD_OPTIONS_KEYS = [
+    "model",
+    "modelReasoningEffort",
+    "sandboxMode",
+    "networkAccessEnabled",
+    "webSearchMode",
+    "approvalPolicy",
+    "workingDirectory",
+    "skipGitRepoCheck",
+];
+const FORBIDDEN_CONFIG_KEYS = [
+    "model",
+    "model_reasoning_effort",
+];
+function isConfigKeyForbidden(key) {
+    return FORBIDDEN_CONFIG_KEYS.includes(key);
+}
+const claudeSettingSourceSchema = z.enum(CLAUDE_SETTING_SOURCES);
+const writableRootItemSchema = z.string().superRefine((value, ctx) => {
+    if (value.length === 0) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must not be empty." });
+        return;
+    }
+    if (value.startsWith("~")) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must not begin with tilde." });
+        return;
+    }
+    if (value.includes("\0")) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must not contain NUL byte." });
+        return;
+    }
+    if (/\$[A-Za-z_]/.test(value) || /\$\{/.test(value)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must not contain environment variable references." });
+        return;
+    }
+});
+export const providerInstanceSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("codex-sdk"),
+        ...providerCommonFields,
+        executable: executableSchema.optional(),
+        profile: z.string().optional(),
+        config: structuredTomlValueSchema.optional(),
+        threadOptions: structuredTomlValueSchema.optional(),
+    })
+        .strict()
+        .superRefine((data, ctx) => {
+        if (data.threadOptions) {
+            for (const key of CODEX_SDK_FORBIDDEN_THREAD_OPTIONS_KEYS) {
+                if (key in data.threadOptions) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ["threadOptions", key],
+                        message: `"${key}" is owned by the Akuma or Keiyaku execution, not this provider instance`,
+                    });
+                }
+            }
+        }
+        if (data.config) {
+            for (const key of Object.keys(data.config)) {
+                if (isConfigKeyForbidden(key)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ["config", key],
+                        message: `"${key}" is owned by the Akuma or Keiyaku execution, not this provider instance`,
+                    });
+                }
+            }
+        }
+    }),
+    z
+        .object({
+        kind: z.literal("codex-app-server"),
+        ...providerCommonFields,
+        executable: executableSchema.optional(),
+        profile: z.string().optional(),
+        config: structuredTomlValueSchema.optional(),
+        writableRoots: z.array(writableRootItemSchema).optional(),
+        env: providerEnvSchema,
+    })
+        .strict()
+        .superRefine((data, ctx) => {
+        if (data.config) {
+            for (const key of Object.keys(data.config)) {
+                if (isConfigKeyForbidden(key)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ["config", key],
+                        message: `"${key}" is owned by the Akuma or Keiyaku execution, not this provider instance`,
+                    });
+                }
+            }
+        }
+    }),
+    z
+        .object({
+        kind: z.literal("claude-agent-sdk"),
+        ...providerCommonFields,
+        executable: executableSchema.optional(),
+        settingSources: z.array(claudeSettingSourceSchema).optional(),
+        env: providerEnvSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("opencode-sdk"),
+        ...providerCommonFields,
+        executable: executableSchema.optional(),
+        env: providerEnvSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("pi"),
+        ...providerCommonFields,
+        env: providerEnvSchema,
+    })
+        .strict()
+        .superRefine(refinePiEnvInjection),
+]);
+const PROVIDER_INSTANCE_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+export const providerInstanceNameSchema = z
+    .string()
+    .max(64, "must contain at most 64 characters.")
+    .regex(PROVIDER_INSTANCE_NAME_PATTERN, "must match ^[a-z0-9][a-z0-9-]*$.");
+export const BUILTIN_PROVIDER_INSTANCE_CANDIDATES = {
+    "codex-sdk": { name: "codex-sdk", source: "builtin", instance: { kind: "codex-sdk", executable: "codex" } },
+    "codex-app-server": {
+        name: "codex-app-server",
+        source: "builtin",
+        instance: { kind: "codex-app-server", executable: "codex" },
+    },
+    "claude-agent-sdk": {
+        name: "claude-agent-sdk",
+        source: "builtin",
+        instance: { kind: "claude-agent-sdk", executable: "claude", settingSources: ["project"] },
+    },
+    "opencode-sdk": {
+        name: "opencode-sdk",
+        source: "builtin",
+        instance: { kind: "opencode-sdk", executable: "opencode" },
+    },
+    pi: { name: "pi", source: "builtin", instance: { kind: "pi" } },
+};
+const AGENT_NAME_PATTERN = /^[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9]+)*$/;
+export const agentNameSchema = z
+    .string()
+    .min(1, "must not be empty.")
+    .regex(AGENT_NAME_PATTERN, "must contain only alphanumeric characters, dots, and hyphens, and must not start or end with a separator.");
+function optionalTrimmedString() {
+    return z.string().transform((value) => {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }).optional();
+}
+function requiredTrimmedString(message) {
+    return z.string().transform((value, ctx) => {
+        const trimmed = value.trim();
+        if (trimmed.length === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message,
+            });
+            return z.NEVER;
+        }
+        return trimmed;
+    });
+}
+const gateCommandSchema = z
+    .object({
+    label: requiredTrimmedString("must not be empty."),
+    command: requiredTrimmedString("must not be empty.").superRefine((value, ctx) => {
+        if (/\s/.test(value) || value.includes("\"") || value.includes("'")) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "must be a single program name token with no spaces or quotes.",
+            });
+        }
+    }),
+    args: z.array(z.string()).optional(),
+})
+    .strict()
+    .transform((value) => ({
+    ...value,
+    args: value.args ?? [],
+}));
+const gateSchema = z
+    .object({
+    commands: z.array(gateCommandSchema).optional(),
+})
+    .strict();
+const WORKTREE_BOOTSTRAP_DEFAULT_TIMEOUT_MS = 300_000;
+const WORKTREE_BOOTSTRAP_MIN_TIMEOUT_MS = 1;
+const WORKTREE_BOOTSTRAP_MAX_TIMEOUT_MS = 3_600_000;
+export const worktreeBootstrapSchema = z
+    .object({
+    command: z
+        .array(z.string())
+        .min(1, "command must be a nonempty argv array.")
+        .superRefine((items, ctx) => {
+        items.forEach((item, index) => {
+            if (item.trim().length === 0) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [index],
+                    message: "command items must be nonempty after trimming.",
+                });
+            }
+        });
+    }),
+    timeoutMs: z
+        .number()
+        .int("timeoutMs must be an integer.")
+        .min(WORKTREE_BOOTSTRAP_MIN_TIMEOUT_MS, `timeoutMs must be >= ${WORKTREE_BOOTSTRAP_MIN_TIMEOUT_MS}.`)
+        .max(WORKTREE_BOOTSTRAP_MAX_TIMEOUT_MS, `timeoutMs must be <= ${WORKTREE_BOOTSTRAP_MAX_TIMEOUT_MS}.`)
+        .optional(),
+})
+    .strict()
+    .transform((value) => ({
+    command: value.command,
+    timeoutMs: value.timeoutMs ?? WORKTREE_BOOTSTRAP_DEFAULT_TIMEOUT_MS,
+}));
+const settingsSchema = z
+    .object({
+    default: agentNameSchema.optional(),
+    reviewer: agentNameSchema.optional(),
+    gate: gateSchema.optional(),
+    defaultBranch: optionalTrimmedString(),
+    worktreeBootstrap: worktreeBootstrapSchema.optional(),
+})
+    .strict();
+export const knobSchemas = {
+    default: agentNameSchema,
+    reviewer: agentNameSchema,
+    gate: gateSchema,
+    defaultBranch: optionalTrimmedString(),
+    worktreeBootstrap: worktreeBootstrapSchema,
+};

package/build/core/addressing.js

@@ -3,7 +3,7 @@ import { FlowError } from "../flow-error.js";
 import { listContractIds, readLedger } from "./ledger.js";
 import { isResponseArtifactId } from "./response-artifact-id.js";
 import { stableRepoRoot } from "./worktree-path.js";
-import { deriveContractState, isTerminalState, } from "./status.js";
+import { deriveContractState, isTerminalState, } from "./status/lifecycle.js";
 function normalizeAddressQuery(raw) {
     const value = raw.startsWith("@") ? raw.slice(1) : raw;
     if (!value.trim()) {

package/build/core/amend.js

@@ -1,13 +1,13 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { FlowError } from "../flow-error.js";
-import { getCurrentBranch, isGitRepo } from "../git/branches.js";
+import { getCurrentBranch, requireGitRepository } from "../git/branches.js";
 import { KEIYAKU_FILE } from "../keiyaku.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
-import { renderContractView } from "./render.js";
-import { deriveContractState, isTerminalState } from "./status.js";
+import { renderContractView } from "./contract-view.js";
+import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
 import { resolveContractAddress, withResolvedAddress } from "./addressing.js";
-import { resolveDefaultBranch } from "./status.js";
+import { resolveDefaultBranch } from "./status/drift.js";
 import { assertCleanWorkingTree } from "./arc.js";
 import { normalizeScopePattern } from "./scope.js";
 function requireAmendment(value) {
@@ -71,10 +71,7 @@ export async function amendContract(input) {
     return { contractId: input.contractId, amendmentNumber, ledgerHead: result.head };
 }
 export async function amendKeiyaku(input) {
-    const isRepo = await isGitRepo(input.cwd);
-    if (!isRepo) {
-        throw new FlowError("NOT_GIT_REPO", `${input.cwd} is not a git repository`);
-    }
+    await requireGitRepository(input.cwd, "amend");
     const address = await resolveContractAddress(input.cwd, input.contractId, input.contractAddressSource);
     return await withResolvedAddress(address, async () => {
         const contractId = address.binding.commissionId;

package/build/core/arc.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { requireText, FlowError } from "../flow-error.js";
-import { getCurrentBranch, isGitRepo } from "../git/branches.js";
+import { getCurrentBranch, requireGitRepository } from "../git/branches.js";
 import { DIRTY_FILE_CATEGORY, getDirtyFiles, renderDirtyFileStatusLine } from "../git/worktree.js";
 import { KEIYAKU_FILE, ACTOR_IDENTITY } from "../keiyaku.js";
 import { buildDirtyWorktreeArtifactHint } from "./hints.js";
@@ -9,9 +9,10 @@ import { normalizeInlineTitle } from "./markdown/titles.js";
 import { parseCommandMarkdown, requireMarkdownTextSection, requireMarkdownTitle, } from "./command-io.js";
 import { resolveContractAddress, withResolvedAddress } from "./addressing.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
-import { renderContractView } from "./render.js";
-import { findOpenArc, getMaxArc, sealOpenArc } from "./seal.js";
-import { deriveContractState, isTerminalState, resolveDefaultBranch } from "./status.js";
+import { renderContractView } from "./contract-view.js";
+import { findOpenArc, getMaxArc, sealCurrentArc } from "./seal.js";
+import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
+import { resolveDefaultBranch } from "./status/drift.js";
 import { persistResponseHistory } from "./transcripts.js";
 const DIRTY_WORKTREE_LIST_LIMIT = 10;
 const KEIYAKU_ARTIFACT_DIR_PREFIX = ".keiyaku/";
@@ -111,7 +112,7 @@ export async function openArc(input) {
         throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} not found or not active`);
     }
     assertArcOpenable(input.contractId, ledger.entries);
-    const sealed = await sealOpenArc({
+    const sealed = await sealCurrentArc({
         cwd: input.cwd,
         renderCwd: input.cwd,
         contractId: input.contractId,
@@ -160,9 +161,7 @@ async function readBranchLabels(cwd) {
     return { currentBranch, baseBranch };
 }
 export async function arcKeiyaku(input) {
-    if (!(await isGitRepo(input.cwd))) {
-        throw new FlowError("NOT_GIT_REPO", `${input.cwd} is not a git repository`);
-    }
+    await requireGitRepository(input.cwd, "arc");
     const address = await resolveContractAddress(input.cwd, input.contractId, input.contractAddressSource);
     return await withResolvedAddress(address, async () => {
         await assertCleanWorkingTree(input.cwd, []);