@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/body/render.js

@@ -0,0 +1,74 @@
+import { formatDuration } from "../duration.js";
+import { parseToAST } from "../markdown/parse.js";
+import { indexDocument, indexedHeadings, normalizeTitle, rawSlice } from "../markdown/query.js";
+import { CONTRACT_SECTIONS } from "./shape.js";
+function content(value) {
+    return value.trimEnd();
+}
+function section(title, value) {
+    return `## ${title}\n\n${content(value)}`;
+}
+function fenced(value, info = "") {
+    const marker = ["`", "~"]
+        .map((delimiter) => ({
+        delimiter,
+        length: Math.max(3, ...value.split("\n").map((line) => {
+            const match = new RegExp(`^ {0,3}\\${delimiter}+`).exec(line);
+            return (match?.[0].trim().length ?? 0) + 1;
+        })),
+    }))
+        .sort((left, right) => left.length - right.length)[0];
+    const boundary = marker.delimiter.repeat(marker.length);
+    return `${boundary}${info}\n${value}\n${boundary}`;
+}
+function verificationFence(declaration) {
+    return fenced(declaration.script, `${declaration.executor}${declaration.timeoutMs === undefined ? "" : ` timeout=${formatDuration(declaration.timeoutMs)}`}`);
+}
+function arcSection(arc) {
+    return [
+        "## Arc",
+        "### Sequence",
+        String(arc.seq),
+        "### Title",
+        content(arc.title),
+        "### Objective",
+        content(arc.objective),
+        "### Brief",
+        content(arc.brief),
+    ].join("\n\n");
+}
+export function renderContractBody(body, currentArc) {
+    const criteria = body.criteria.map((criterion) => `### ${criterion.title}\n\n${content(criterion.body)}`).join("\n\n");
+    const verification = body.verification.map(verificationFence).join("\n\n");
+    return [
+        `# ${body.title}`,
+        section(CONTRACT_SECTIONS.context.title, body.context),
+        section(CONTRACT_SECTIONS.objective.title, body.objective),
+        section(CONTRACT_SECTIONS.design.title, body.design),
+        section(CONTRACT_SECTIONS.region.title, fenced(body.region.join("\n"))),
+        section(CONTRACT_SECTIONS.criteria.title, criteria),
+        ...(verification.length === 0 ? [] : [section(CONTRACT_SECTIONS.verification.title, verification)]),
+        ...body.extensions.map((extension) => section(extension.title, extension.content)),
+        ...(currentArc === undefined ? [] : [arcSection(currentArc)]),
+    ].join("\n\n").concat("\n");
+}
+function sections(document) {
+    return indexedHeadings(indexDocument(document), { level: 2 })
+        .filter((node) => node.type === "section");
+}
+export function renderAmendedContractBody(currentSource, body, changedSections) {
+    const current = parseToAST(currentSource);
+    const renderedSource = renderContractBody(body);
+    const rendered = parseToAST(renderedSource);
+    const currentSections = sections(current);
+    const preserved = new Map(currentSections.map((node) => [
+        normalizeTitle(node.title),
+        rawSlice(current, node.span),
+    ]));
+    const first = currentSections[0];
+    const prefix = first === undefined ? currentSource : currentSource.slice(0, first.span.start);
+    return prefix + sections(rendered).map((node) => {
+        const name = normalizeTitle(node.title);
+        return changedSections.has(name) ? rawSlice(rendered, node.span) : preserved.get(name) ?? rawSlice(rendered, node.span);
+    }).join("");
+}

package/build/src/body/shape.d.ts

@@ -0,0 +1,29 @@
+export declare const CONTRACT_SECTIONS: {
+    readonly context: {
+        readonly title: "Context";
+        readonly required: true;
+    };
+    readonly objective: {
+        readonly title: "Objective";
+        readonly required: true;
+    };
+    readonly design: {
+        readonly title: "Design";
+        readonly required: true;
+    };
+    readonly region: {
+        readonly title: "Region";
+        readonly required: true;
+    };
+    readonly criteria: {
+        readonly title: "Criteria";
+        readonly required: true;
+    };
+    readonly verification: {
+        readonly title: "Verification";
+        readonly required: false;
+    };
+};
+export declare const RESERVED_SECTIONS: ReadonlySet<string>;
+export type ContractSectionName = keyof typeof CONTRACT_SECTIONS;
+export declare function contractSectionName(title: string): ContractSectionName | null;

package/build/src/body/shape.js

@@ -0,0 +1,22 @@
+export const CONTRACT_SECTIONS = {
+    context: { title: "Context", required: true },
+    objective: { title: "Objective", required: true },
+    design: { title: "Design", required: true },
+    region: { title: "Region", required: true },
+    criteria: { title: "Criteria", required: true },
+    verification: { title: "Verification", required: false },
+};
+export const RESERVED_SECTIONS = new Set([
+    "gates",
+    "pipeline",
+    "after",
+    "arc",
+    "fulfillment",
+]);
+export function contractSectionName(title) {
+    for (const name of Object.keys(CONTRACT_SECTIONS)) {
+        if (CONTRACT_SECTIONS[name].title === title)
+            return name;
+    }
+    return null;
+}

package/build/src/body/types.d.ts

@@ -0,0 +1,28 @@
+import type { DocumentKey, DocumentSegmentKey } from "../core/facts/types.js";
+import type { VerificationDeclaration } from "../verification/declaration.js";
+export type ContractCriterion = Readonly<{
+    readonly title: string;
+    readonly body: string;
+}>;
+export type ContractExtension = Readonly<{
+    readonly title: string;
+    readonly content: string;
+}>;
+export type ContractBody = Readonly<{
+    readonly title: string;
+    readonly context: string;
+    readonly objective: string;
+    readonly design: string;
+    readonly region: readonly string[];
+    readonly criteria: readonly ContractCriterion[];
+    readonly verification: readonly VerificationDeclaration[];
+    readonly extensions: readonly ContractExtension[];
+}>;
+export type DecodedContractDocument = ContractBody & Readonly<{
+    readonly document: Readonly<{
+        readonly bytes: string;
+        readonly key: DocumentKey;
+    }>;
+    readonly segments: readonly DocumentSegmentKey[];
+    readonly verificationSegment: DocumentSegmentKey | null;
+}>;

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

@@ -0,0 +1,7 @@
+import type { DocumentNode, SectionNode } from "../markdown/types.js";
+import type { VerificationDeclaration } from "../verification/declaration.js";
+export type { VerificationDeclaration, VerificationExecutor } from "../verification/declaration.js";
+export declare class VerificationDocumentError extends Error {
+    constructor(message: string);
+}
+export declare function decodeVerificationDeclarations(document: DocumentNode, section: SectionNode): readonly VerificationDeclaration[];

package/build/src/body/verification.js

@@ -0,0 +1,40 @@
+import { directChildren, rawSlice } from "../markdown/query.js";
+import { parseDuration } from "../duration.js";
+export class VerificationDocumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VerificationDocumentError";
+    }
+}
+export function decodeVerificationDeclarations(document, section) {
+    const blocks = directChildren(section, "code_block");
+    if (blocks.length === 0)
+        throw new VerificationDocumentError("Verification must contain one or more fenced executor declarations");
+    const other = section.children.filter((node) => node.type !== "code_block" && rawSlice(document, node.span).trim().length > 0);
+    if (other.length > 0)
+        throw new VerificationDocumentError("Verification may contain only fenced executor declarations");
+    return blocks.map((block) => {
+        const info = /^(bash|zsh|pwsh)(?: timeout=([^ ]+))?$/.exec(block.info);
+        if (!block.closed || info === null) {
+            throw new VerificationDocumentError("Verification fences must be closed and use bash, zsh, or pwsh with optional timeout=<duration>");
+        }
+        const script = block.lines.slice(1, -1).join("\n");
+        if (script.trim().length === 0)
+            throw new VerificationDocumentError("Verification scripts must be nonblank");
+        const duration = info[2] === undefined ? undefined : parseDuration(info[2]);
+        if (duration?.kind === "invalid") {
+            throw new VerificationDocumentError("Verification timeout must be an integer duration with unit ms, s, m, or h");
+        }
+        if (duration?.kind === "overflow" || (duration?.kind === "parsed" && duration.milliseconds > 2_147_483_647)) {
+            throw new VerificationDocumentError("Verification timeout exceeds the supported process duration");
+        }
+        if (duration?.kind === "parsed" && duration.milliseconds === 0) {
+            throw new VerificationDocumentError("Verification timeout must be positive");
+        }
+        return {
+            executor: info[1],
+            script,
+            ...(duration === undefined ? {} : { timeoutMs: duration.milliseconds }),
+        };
+    });
+}

package/build/src/cli/accepted.d.ts

@@ -0,0 +1,18 @@
+import { type ContractId, type MutationResult } from "../index.js";
+import type { AcceptedResult, InvocationResult } from "./result.js";
+type MutationObservation = Pick<MutationResult<unknown>, "facts" | "head" | "effects" | "lags" | "settlement">;
+type ResultOptions = Readonly<{
+    coordinate?: ContractId;
+    target?: string | null;
+    report?: import("../index.js").AuditReport;
+    workspace?: AcceptedResult["workspace"];
+    obligations?: Pick<AcceptedResult, "verification" | "placement" | "leak">;
+    diff?: AcceptedResult["diff"];
+}>;
+type MutationCallOptions<Result extends MutationObservation> = Readonly<{
+    coordinate?: ContractId;
+    project?: (result: Result) => ResultOptions | Promise<ResultOptions>;
+    projectRefusal?: (refusal: unknown) => unknown;
+}>;
+export declare function resultFromMutationCall<Result extends MutationObservation & object>(verb: string, call: () => Promise<Result>, options?: MutationCallOptions<Result>): Promise<InvocationResult>;
+export {};

package/build/src/cli/accepted.js

@@ -0,0 +1,66 @@
+import { KeiyakuRefused, KeiyakuRetry, } from "../index.js";
+function hasOverlaps(value) {
+    return "overlaps" in value;
+}
+function hasOverlapFailure(value) {
+    return "overlapFailure" in value;
+}
+function hasDocumentDiff(value) {
+    return "documentDiff" in value && typeof value.documentDiff === "string";
+}
+function resultFromMutation(verb, result, options) {
+    const acceptedContract = options.coordinate ?? result.facts[0]?.contract;
+    if (acceptedContract === undefined)
+        throw new Error("accepted mutation is missing its contract identity");
+    return {
+        kind: "accepted",
+        verb,
+        contract: acceptedContract,
+        head: result.head,
+        facts: result.facts.map((fact) => ({
+            contract: fact.contract,
+            entry: fact.entry,
+            kind: fact.kind,
+        })),
+        effects: result.effects,
+        settlement: result.settlement,
+        ...(options.target === undefined ? {} : { target: options.target }),
+        ...options.obligations,
+        ...(hasOverlaps(result) ? { overlaps: result.overlaps } : {}),
+        ...(hasOverlapFailure(result) ? { overlapFailure: result.overlapFailure } : {}),
+        ...(hasDocumentDiff(result) ? { diff: result.documentDiff } : {}),
+        ...(options.report === undefined ? {} : { report: options.report }),
+        ...(options.workspace === undefined ? {} : { workspace: options.workspace }),
+        ...(options.diff === undefined ? {} : { diff: options.diff }),
+        ...(result.lags.length === 0 ? {} : { lag: result.lags }),
+    };
+}
+export async function resultFromMutationCall(verb, call, options = {}) {
+    try {
+        const result = await call();
+        const projected = options.project === undefined ? {} : await options.project(result);
+        return resultFromMutation(verb, result, {
+            ...projected,
+            ...(options.coordinate === undefined ? {} : { coordinate: options.coordinate }),
+        });
+    }
+    catch (error) {
+        if (error instanceof KeiyakuRefused) {
+            return {
+                kind: "refused",
+                verb,
+                ...(options.coordinate === undefined ? {} : { contract: options.coordinate }),
+                refusal: options.projectRefusal === undefined ? error.refusal : options.projectRefusal(error.refusal),
+            };
+        }
+        if (error instanceof KeiyakuRetry) {
+            return {
+                kind: "retry",
+                verb,
+                ...(options.coordinate === undefined ? {} : { contract: options.coordinate }),
+                detail: error.reason,
+            };
+        }
+        throw error;
+    }
+}

package/build/src/cli/actor.d.ts

@@ -0,0 +1,8 @@
+import type { ActorId } from "../index.js";
+type ActorResolutionInput = Readonly<{
+    env?: Readonly<Record<string, string | undefined>>;
+    actor?: string;
+}>;
+/** Resolve optional caller testimony from the current CLI edge vocabulary. */
+export declare function resolveActor(input?: ActorResolutionInput): ActorId | undefined;
+export {};

package/build/src/cli/actor.js

@@ -0,0 +1,11 @@
+const PROJECTION_ID_ENV = "KEIYAKU_PROJECTION_ID";
+/** Resolve optional caller testimony from the current CLI edge vocabulary. */
+export function resolveActor(input = {}) {
+    if (input.actor !== undefined) {
+        if (input.actor.trim().length === 0)
+            throw new TypeError("actor must be a nonblank string");
+        return input.actor;
+    }
+    const projectionId = input.env?.[PROJECTION_ID_ENV];
+    return projectionId !== undefined && projectionId.trim().length > 0 ? projectionId : undefined;
+}

package/build/src/cli/commands/akuma-invoke.d.ts

@@ -0,0 +1,77 @@
+import { type AkuId, type ActivityHistory } from "../../akuma/index.js";
+import { Keiyaku, type AkumaKillResult, type AkumaHistoryResult, type AkumaStatusView, type AkumaTellResult, type AkumaWaitResult, type CallResult, type ForkResult, type Keiyaku as KeiyakuContract, type Repo } from "../../index.js";
+import type { Settings } from "../../settings.js";
+import type { WorldRoot } from "../../world.js";
+import type { ParsedAkumaCommand } from "./akuma.js";
+export type AkumaInvocationResult = Readonly<{
+    kind: "akuma";
+    action: "call";
+    result: CallResult;
+}> | Readonly<{
+    kind: "akuma";
+    action: "status";
+    status: AkumaStatusView;
+    alias?: string;
+}> | Readonly<{
+    kind: "akuma";
+    action: "wait";
+    result: AkumaWaitResult;
+    alias?: string;
+}> | Readonly<{
+    kind: "akuma";
+    action: "tell";
+    mode: "ordinary";
+    result: AkumaTellResult;
+    body: string;
+    alias?: string;
+}> | Readonly<{
+    kind: "akuma";
+    action: "tell";
+    mode: "interrupt";
+    result: Awaited<ReturnType<typeof Keiyaku.interrupt>>;
+    body: string;
+    alias?: string;
+}> | Readonly<{
+    kind: "akuma";
+    action: "history";
+    akuma: AkuId;
+    mode: "page";
+    history: ActivityHistory;
+    historyResult: AkumaHistoryResult;
+    alias?: string;
+}> | Readonly<{
+    kind: "akuma";
+    action: "history";
+    akuma: AkuId;
+    mode: "last";
+    answer: string;
+    historyResult: AkumaHistoryResult;
+    alias?: string;
+}> | Readonly<{
+    kind: "akuma";
+    action: "history";
+    akuma: AkuId;
+    mode: "no-answer";
+    historyResult: AkumaHistoryResult;
+    alias?: string;
+}> | Readonly<{
+    kind: "akuma";
+    action: "fork";
+    receipt: ForkResult;
+}> | Readonly<{
+    kind: "akuma";
+    action: "kill";
+    result: AkumaKillResult;
+    alias?: string;
+}>;
+type InvokeInput = Readonly<{
+    path: WorldRoot;
+    executionCwd: string;
+    settings: Settings;
+    contract?: KeiyakuContract;
+    repo?: Repo;
+    readStdin(): string;
+}>;
+export declare function invokeAkuma(command: ParsedAkumaCommand, input: InvokeInput): Promise<AkumaInvocationResult>;
+export declare function invokeAkumaStatus(path: WorldRoot, akuma: string, settings: Settings, alias?: string, repo?: Repo): AkumaInvocationResult;
+export {};

package/build/src/cli/commands/akuma-invoke.js

@@ -0,0 +1,112 @@
+import { Keiyaku, } from "../../index.js";
+function inputAlias(selector) {
+    return selector.startsWith("@") ? selector : undefined;
+}
+async function invokeWait(command, input) {
+    const alias = command.akuma.length === 1 ? inputAlias(command.akuma[0]) : undefined;
+    return {
+        kind: "akuma",
+        action: "wait",
+        result: await Keiyaku.wait({
+            path: input.path,
+            akuma: command.akuma,
+            settings: input.settings,
+            ...(input.repo === undefined ? {} : { repo: input.repo }),
+            ...(command.completion === undefined ? {} : { completion: command.completion }),
+            ...(command.timeoutMs === undefined ? {} : { timeoutMs: command.timeoutMs }),
+        }),
+        ...(alias === undefined ? {} : { alias }),
+    };
+}
+async function invokeTell(command, input) {
+    const body = input.readStdin();
+    if (command.interrupt) {
+        const result = await Keiyaku.interrupt({ path: input.path, akuma: command.akuma, settings: input.settings, body, ...(input.repo === undefined ? {} : { repo: input.repo }) });
+        const alias = inputAlias(command.akuma);
+        return { kind: "akuma", action: "tell", mode: "interrupt", result, body, ...(alias === undefined ? {} : { alias }) };
+    }
+    const result = await Keiyaku.tell({ path: input.path, akuma: command.akuma, settings: input.settings, body, ...(input.repo === undefined ? {} : { repo: input.repo }) });
+    const alias = inputAlias(command.akuma);
+    return { kind: "akuma", action: "tell", mode: "ordinary", result, body, ...(alias === undefined ? {} : { alias }) };
+}
+function invokeHistory(command, input) {
+    const result = Keiyaku.history({
+        path: input.path,
+        akuma: command.akuma,
+        settings: input.settings,
+        ...(input.repo === undefined ? {} : { repo: input.repo }),
+        ...(command.before === undefined ? {} : { before: command.before }),
+        ...(command.since === undefined ? {} : { since: command.since }),
+        last: command.last,
+    });
+    return {
+        kind: "akuma",
+        action: "history",
+        akuma: result.id,
+        historyResult: result,
+        ...(inputAlias(command.akuma) === undefined ? {} : { alias: command.akuma }),
+        ...(result.kind === "history"
+            ? { mode: "page", history: result.history }
+            : result.kind === "last"
+                ? { mode: "last", answer: result.answer }
+                : { mode: "no-answer" }),
+    };
+}
+async function invokeFork(command, input) {
+    return {
+        kind: "akuma",
+        action: "fork",
+        receipt: await Keiyaku.fork({
+            path: input.path,
+            akuma: command.akuma,
+            at: command.at,
+            settings: input.settings,
+            ...(input.repo === undefined ? {} : { repo: input.repo }),
+        }),
+    };
+}
+async function invokeKill(command, input) {
+    const alias = command.akuma.length === 1 ? inputAlias(command.akuma[0]) : undefined;
+    return {
+        kind: "akuma",
+        action: "kill",
+        result: await Keiyaku.kill({
+            path: input.path,
+            akuma: command.akuma,
+            settings: input.settings,
+            ...(input.repo === undefined ? {} : { repo: input.repo }),
+        }),
+        ...(alias === undefined ? {} : { alias }),
+    };
+}
+export async function invokeAkuma(command, input) {
+    switch (command.command) {
+        case "call": {
+            const result = await Keiyaku.call({
+                path: input.path,
+                archetype: command.archetype,
+                body: input.readStdin(),
+                settings: input.settings,
+                cwd: input.executionCwd,
+                mode: command.mode,
+                ...(command.timeoutMs === undefined ? {} : { timeoutMs: command.timeoutMs }),
+                ...(input.contract === undefined ? {} : { contract: input.contract }),
+                ...(command.alias === undefined ? {} : { alias: command.alias }),
+            });
+            return { kind: "akuma", action: "call", result };
+        }
+        case "wait": return await invokeWait(command, input);
+        case "tell": return await invokeTell(command, input);
+        case "history": return invokeHistory(command, input);
+        case "fork": return await invokeFork(command, input);
+        case "kill": return await invokeKill(command, input);
+    }
+}
+export function invokeAkumaStatus(path, akuma, settings, alias, repo) {
+    return {
+        kind: "akuma",
+        action: "status",
+        status: Keiyaku.status({ path, akuma, settings, ...(repo === undefined ? {} : { repo }) }),
+        ...(alias === undefined ? {} : { alias }),
+    };
+}

package/build/src/cli/commands/akuma.d.ts

@@ -0,0 +1,50 @@
+import { type AkumaAlias } from "../../identity/selector.js";
+type Output = Readonly<{
+    output: "text" | "json";
+}>;
+type Addressed = Readonly<{
+    akuma: string;
+}>;
+export type ParsedAkumaCommand = Output & (Readonly<{
+    command: "call";
+    archetype: string;
+    contract?: string;
+    alias?: AkumaAlias;
+    mode: "wait" | "detach";
+    timeoutMs?: number;
+}> | Readonly<{
+    command: "kill";
+    akuma: readonly string[];
+}> | Readonly<{
+    command: "wait";
+    akuma: readonly string[];
+    completion?: "any" | "all";
+    timeoutMs?: number;
+}> | (Readonly<{
+    command: "tell";
+    interrupt: boolean;
+}> & Addressed) | (Readonly<{
+    command: "history";
+    last: boolean;
+    before?: number;
+    since?: number;
+}> & Addressed) | (Readonly<{
+    command: "fork";
+    at: string;
+}> & Addressed));
+export type AkumaAction = ParsedAkumaCommand["command"];
+export declare function isAkumaAction(value: string | undefined): value is AkumaAction;
+export declare function isParsedAkumaCommand(command: Readonly<{
+    command: string;
+}>): command is ParsedAkumaCommand;
+export declare function renderAkumaRootRows(): readonly string[];
+export declare function renderAkumaHelp(action: AkumaAction): string;
+export declare function renderAkumaUsage(action: AkumaAction): string;
+export declare function parseAkumaCatalogPath(value: string): Readonly<{
+    kind: "archetypes";
+} | {
+    kind: "akuma";
+    archetype?: string;
+}> | null;
+export declare function parseAkumaCommand(argv: readonly string[]): ParsedAkumaCommand;
+export {};