@astrosheep/keiyaku 2.9.12 → 4.0.0

package/build/src/body/render.js

@@ -0,0 +1,73 @@
+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);
+}
+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,16 @@
+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"]);
+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,25 @@
+import { directChildren, rawSlice } from "../markdown/query.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 executor = block.info.trim();
+        if (!block.closed || (executor !== "bash" && executor !== "zsh" && executor !== "pwsh")) {
+            throw new VerificationDocumentError("Verification fences must be closed and use bash, zsh, or pwsh");
+        }
+        const script = block.lines.slice(1, -1).join("\n");
+        if (script.trim().length === 0)
+            throw new VerificationDocumentError("Verification scripts must be nonblank");
+        return { executor, script };
+    });
+}

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

@@ -0,0 +1,16 @@
+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;
+    obligations?: Pick<AcceptedResult, "verification" | "placement" | "leak">;
+    diff?: AcceptedResult["diff"];
+}>;
+type MutationCallOptions<Result extends MutationObservation> = Readonly<{
+    coordinate?: ContractId;
+    project?: (result: Result) => ResultOptions | Promise<ResultOptions>;
+}>;
+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,65 @@
+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.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: 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,53 @@
+import { type AkuId, type AkumaStatus, type InterruptReceipt, type KillEvidence, type TellReceipt } from "../../akuma/index.js";
+import type { ActivityHistory } from "../../akuma/index.js";
+import { type CallResult, type ForkResult, type Keiyaku as KeiyakuContract, type Repo } from "../../index.js";
+import type { Settings } from "../../settings.js";
+import type { ParsedAkumaCommand } from "./akuma.js";
+export type AkumaInvocationResult = Readonly<{
+    kind: "akuma";
+    action: "call";
+    result: CallResult;
+}> | Readonly<{
+    kind: "akuma";
+    action: "status";
+    status: AkumaStatus;
+}> | Readonly<{
+    kind: "akuma";
+    action: "wait";
+    status: AkumaStatus;
+}> | Readonly<{
+    kind: "akuma";
+    action: "tell";
+    akuma: AkuId;
+    receipt: TellReceipt;
+    status: AkumaStatus;
+}> | Readonly<{
+    kind: "akuma";
+    action: "interrupt";
+    akuma: AkuId;
+    receipt: InterruptReceipt;
+}> | Readonly<{
+    kind: "akuma";
+    action: "history";
+    akuma: AkuId;
+    history: ActivityHistory;
+    answer?: string;
+}> | Readonly<{
+    kind: "akuma";
+    action: "fork";
+    akuma: AkuId;
+    receipt: ForkResult;
+}> | Readonly<{
+    kind: "akuma";
+    action: "kill";
+    id: AkuId;
+    evidence: KillEvidence;
+}>;
+export declare function invokeAkuma(command: ParsedAkumaCommand, input: Readonly<{
+    path: string;
+    settings: Settings;
+    contract?: KeiyakuContract;
+    repo?: Repo;
+    readStdin(): string;
+}>): Promise<AkumaInvocationResult>;
+export declare function invokeAkumaStatus(path: string, id: string): AkumaInvocationResult;

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

@@ -0,0 +1,68 @@
+import { resolve } from "node:path";
+import { Akuma, } from "../../akuma/index.js";
+import { Keiyaku } from "../../index.js";
+export async function invokeAkuma(command, input) {
+    const world = () => Akuma.at({ path: input.path, settings: input.settings });
+    switch (command.command) {
+        case "call": {
+            const result = await Keiyaku.call({
+                path: input.path,
+                archetype: command.archetype,
+                body: input.readStdin(),
+                settings: input.settings,
+                ...(command.workdir === undefined ? {} : { cwd: resolve(input.path, command.workdir) }),
+                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 {
+            kind: "akuma",
+            action: "wait",
+            status: await world().of({ id: command.id }).wait(undefined, command.timeoutMs === undefined ? {} : { timeoutMs: command.timeoutMs }),
+        };
+        case "tell": {
+            const handle = world().of({ id: command.id });
+            const receipt = await handle.tell(input.readStdin());
+            return { kind: "akuma", action: "tell", akuma: command.id, receipt, status: handle.status() };
+        }
+        case "interrupt": return {
+            kind: "akuma",
+            action: "interrupt",
+            akuma: command.id,
+            receipt: await world().of({ id: command.id }).interrupt(input.readStdin()),
+        };
+        case "history": {
+            const handle = world().of({ id: command.id });
+            const history = handle.history({
+                ...(command.before === undefined ? {} : { before: command.before }),
+                ...(command.since === undefined ? {} : { since: command.since }),
+            });
+            return {
+                kind: "akuma",
+                action: "history",
+                akuma: command.id,
+                history,
+                ...(command.last ? { answer: handle.lastAnswer() } : {}),
+            };
+        }
+        case "fork": return {
+            kind: "akuma",
+            action: "fork",
+            akuma: command.id,
+            receipt: await Keiyaku.fork({
+                path: input.path,
+                akuma: command.id,
+                at: command.at,
+                settings: input.settings,
+                ...(input.repo === undefined ? {} : { repo: input.repo }),
+            }),
+        };
+        case "kill": return { kind: "akuma", action: "kill", id: command.id, evidence: await world().of({ id: command.id }).kill() };
+    }
+}
+export function invokeAkumaStatus(path, id) {
+    return { kind: "akuma", action: "status", status: Akuma.at({ path }).of({ id }).status() };
+}

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

@@ -0,0 +1,42 @@
+import { type AkumaAlias } from "../../identity/selector.js";
+import { type AkuId } from "../../akuma/identity.js";
+type Output = Readonly<{
+    output: "text" | "json";
+}>;
+type Addressed = Readonly<{
+    id: AkuId;
+}>;
+export type ParsedAkumaCommand = Output & (Readonly<{
+    command: "call";
+    archetype: string;
+    workdir?: string;
+    contract?: string;
+    alias?: AkumaAlias;
+    mode: "wait" | "detach";
+    timeoutMs?: number;
+}> | (Readonly<{
+    command: "kill";
+}> & Addressed) | (Readonly<{
+    command: "wait";
+    timeoutMs?: number;
+}> & Addressed) | (Readonly<{
+    command: "tell" | "interrupt";
+}> & 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 parseAkumaCommand(argv: readonly string[]): ParsedAkumaCommand;
+export {};