@duyquangnvx/agent-cli 0.2.0 → 0.3.0

package/dist/error-table.js

@@ -0,0 +1,10 @@
+import { CliError } from "./errors.js";
+/** Keeps each code's literal class and `details` schema, so `cliError` can type its throw sites. */
+export function defineErrors(table) {
+    return table;
+}
+/** A `CliError` for a code of `table`, whose `details` must match the code's schema. */
+export function cliError(_table, code, init, options) {
+    return new CliError({ ...init, code }, options);
+}
+//# sourceMappingURL=error-table.js.map

package/dist/error-table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-table.js","sourceRoot":"","sources":["../src/error-table.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAcvC,oGAAoG;AACpG,MAAM,UAAU,YAAY,CAAiC,KAAY;IACvE,OAAO,KAAK,CAAC;AACf,CAAC;AAmBD,wFAAwF;AACxF,MAAM,UAAU,QAAQ,CACtB,MAAa,EACb,IAAU,EACV,IAA+B,EAC/B,OAAsB;IAEtB,OAAO,IAAI,QAAQ,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC"}

package/dist/errors.d.ts

@@ -1,34 +1,39 @@
 import type { Env } from "./define.js";
 import type { Style } from "./style.js";
-export interface CliErrorDetails {
+export interface CliErrorFields {
     readonly code: string;
     readonly message: string;
     readonly hint: string;
-    readonly retryable: boolean;
+    /** Facts the caller acts on without parsing the message, shaped by the code's schema. */
+    readonly details?: unknown;
+    /** ISO 8601: when a wait-class failure may pass, set only when the source said so. */
+    readonly retryAt?: string;
 }
 export declare class CliError extends Error {
     readonly code: string;
     readonly hint: string;
-    readonly retryable: boolean;
-    constructor({ code, message, hint, retryable }: CliErrorDetails, options?: ErrorOptions);
+    readonly details: unknown;
+    readonly retryAt: string | undefined;
+    constructor({ code, message, hint, details, retryAt }: CliErrorFields, options?: ErrorOptions);
 }
-export type UsageErrorDetails = Omit<CliErrorDetails, "retryable">;
-/** The caller called the Agent CLI wrong; retrying the same call can't succeed. */
+export type UsageErrorFields = Pick<CliErrorFields, "code" | "message" | "hint">;
+/** The caller called the Agent CLI wrong; the same call can't succeed. */
 export declare class UsageError extends CliError {
-    constructor(details: UsageErrorDetails);
+    constructor(fields: UsageErrorFields);
 }
+export declare const INTERNAL_CODE = "INTERNAL";
 export interface ErrorFormat {
     readonly cliName: string;
     readonly json: boolean;
     readonly env: Env;
     readonly style: Style;
+    /** Whether `error` is a bug: not a `CliError`, or one whose code nobody declared. */
+    readonly isBug: (error: unknown) => boolean;
 }
+export declare function errnoOf(error: unknown): string | undefined;
 export declare function isMissingFile(error: unknown): boolean;
 export declare function debugVariable(cliName: string): string;
 export declare function messageOf(error: unknown): string;
+/** The errors a run failed with: each one an `AggregateError` holds, or the one it threw. */
+export declare function errorsOf(error: unknown): readonly unknown[];
 export declare function formatRuntimeError(error: unknown, format: ErrorFormat): string;
-/** A failure that still prints the Command's data on stdout, as `doctor` does with its rows. */
-export declare class FailureWithData extends CliError {
-    readonly data: unknown;
-    constructor(details: CliErrorDetails, data: unknown);
-}

package/dist/errors.js

@@ -1,25 +1,32 @@
 export class CliError extends Error {
     code;
     hint;
-    retryable;
-    constructor({ code, message, hint, retryable }, options) {
+    details;
+    retryAt;
+    constructor({ code, message, hint, details, retryAt }, options) {
         super(message, options);
         this.name = "CliError";
         this.code = code;
         this.hint = hint;
-        this.retryable = retryable;
+        this.details = details;
+        this.retryAt = retryAt;
     }
 }
-/** The caller called the Agent CLI wrong; retrying the same call can't succeed. */
+/** The caller called the Agent CLI wrong; the same call can't succeed. */
 export class UsageError extends CliError {
-    constructor(details) {
-        super({ ...details, retryable: false });
+    constructor(fields) {
+        super(fields);
         this.name = "UsageError";
     }
 }
-const INTERNAL_CODE = "INTERNAL";
+export const INTERNAL_CODE = "INTERNAL";
+export function errnoOf(error) {
+    return error instanceof Error && "code" in error && typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
 export function isMissingFile(error) {
-    return error instanceof Error && "code" in error && error.code === "ENOENT";
+    return errnoOf(error) === "ENOENT";
 }
 export function debugVariable(cliName) {
     return `${cliName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_DEBUG`;
@@ -30,43 +37,57 @@ export function messageOf(error) {
 function isDebug({ env, cliName }) {
     return Boolean(env[debugVariable(cliName)]);
 }
-function detailsOf(error, format) {
+function bugHint(format) {
+    return isDebug(format)
+        ? "the stack trace shows where it failed"
+        : `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`;
+}
+function fieldsOf(error, format) {
     if (error instanceof CliError) {
-        const { code, message, hint, retryable } = error;
-        return { code, message, hint, retryable };
+        const { code, message, hint, details, retryAt } = error;
+        return { code, message, hint: format.isBug(error) ? bugHint(format) : hint, details, retryAt };
     }
-    return {
-        code: INTERNAL_CODE,
-        message: messageOf(error),
-        hint: isDebug(format)
-            ? "the stack trace shows where it failed"
-            : `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`,
-        retryable: false,
-    };
+    return { code: INTERNAL_CODE, message: messageOf(error), hint: bugHint(format) };
 }
-function stackOf(error, format) {
-    return isDebug(format) && !(error instanceof CliError) && error instanceof Error
-        ? error.stack
-        : undefined;
+function causesOf(error) {
+    return error instanceof Error && error.cause !== undefined
+        ? [error.cause, ...causesOf(error.cause)]
+        : [];
 }
-export function formatRuntimeError(error, format) {
-    const details = detailsOf(error, format);
-    const stack = stackOf(error, format);
-    if (format.json) {
-        return `${JSON.stringify({ ...details, stack })}\n`;
-    }
+function traceOf(error) {
+    return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}
+/** Under debug: a bug's stack trace, then every error's cause chain. */
+function debugTrace(error, format) {
+    if (!isDebug(format))
+        return undefined;
+    const lines = [
+        ...(format.isBug(error) ? [traceOf(error)] : []),
+        ...causesOf(error).map((cause) => `caused by: ${traceOf(cause)}`),
+    ];
+    return lines.length === 0 ? undefined : lines.join("\n");
+}
+/** The errors a run failed with: each one an `AggregateError` holds, or the one it threw. */
+export function errorsOf(error) {
+    return error instanceof AggregateError && error.errors.length > 0 ? error.errors : [error];
+}
+function errorLines(error, format) {
+    const fields = fieldsOf(error, format);
+    const stack = debugTrace(error, format);
     const { style } = format;
-    const label = style.red(error instanceof CliError ? "error:" : "internal error:");
+    const label = style.red(format.isBug(error) ? "internal error:" : "error:");
     const trace = stack === undefined ? "" : `${stack}\n`;
-    return `${label} ${details.message}\n${trace}${style.cyan("hint:")} ${details.hint}\n`;
+    return `${label} ${fields.message}\n${trace}${style.cyan("hint:")} ${fields.hint}\n`;
 }
-/** A failure that still prints the Command's data on stdout, as `doctor` does with its rows. */
-export class FailureWithData extends CliError {
-    data;
-    constructor(details, data) {
-        super(details);
-        this.name = "FailureWithData";
-        this.data = data;
+export function formatRuntimeError(error, format) {
+    const errors = errorsOf(error);
+    if (format.json) {
+        const printed = errors.map((each) => ({
+            ...fieldsOf(each, format),
+            stack: debugTrace(each, format),
+        }));
+        return `${JSON.stringify({ errors: printed })}\n`;
     }
+    return errors.map((each) => errorLines(each, format)).join("");
 }
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/execute.d.ts

@@ -10,12 +10,18 @@ export interface ExecuteFlags {
     readonly dryRun: boolean;
     /** The target the caller named with `--confirm`, if any. */
     readonly confirm: string | undefined;
+    /** Whether the caller approved the cost with `--yes`. */
+    readonly yes: boolean;
+    /** Whether the caller allowed replacing existing outputs with `--force`. */
+    readonly force: boolean;
     /** The page a List Command's `run` receives with its input. */
     readonly page: PageInput;
     /** The caller's command line and the Command's, for the hint of a confirmation error. */
     readonly invocation: Invocation;
     readonly commandLine: string;
+    /** Prints a serve Command's data the moment `start` returns it. */
+    readonly started: (outcome: Outcome) => Promise<void>;
 }
-/** How the Command prints data it fails with, which is the data its `run` or `apply` returns. */
-export declare function renderOf(command: Command): (data: unknown, style: Style) => string;
-export declare function execute(command: Command, input: Record<string, unknown>, ctx: Context, { dryRun, confirm, page, invocation, commandLine }: ExecuteFlags): Promise<Outcome>;
+/** Delivered data as the Command prints it, which is the data its `run` or `apply` returns. */
+export declare function deliveredOutcome(command: Command, data: unknown): Outcome;
+export declare function execute(command: Command, input: Record<string, unknown>, ctx: Context, { dryRun, confirm, yes, force, page, invocation, commandLine, started }: ExecuteFlags): Promise<Outcome>;

package/dist/execute.js

@@ -1,23 +1,56 @@
+import { untilAborted } from "./abort.js";
 import { checkConfirmation } from "./confirm.js";
+import { checkCost } from "./cost.js";
+import { checkOutputs } from "./outputs.js";
+import { checkTools } from "./tools.js";
 function outcomeOf(value, render) {
     return { value, render: (style) => render(value, style) };
 }
-/** How the Command prints data it fails with, which is the data its `run` or `apply` returns. */
-export function renderOf(command) {
+/** Delivered data as the Command prints it, which is the data its `run` or `apply` returns. */
+export function deliveredOutcome(command, data) {
     // The union of render signatures only accepts the intersection of their data types.
-    return (data, style) => command.render(data, style);
+    return outcomeOf(data, command.render);
 }
-export async function execute(command, input, ctx, { dryRun, confirm, page, invocation, commandLine }) {
+function dryRunOutcome(command, plan) {
+    const renderPlan = (style) => command.renderPlan(plan, style);
+    if (command.outputs === undefined && command.cost === undefined) {
+        return { value: plan, render: renderPlan };
+    }
+    const outputs = command.outputs?.(plan);
+    const cost = command.cost?.(plan);
+    return {
+        // A costed Command's dry run keeps one JSON shape, with `cost: null` when the run is cheap.
+        value: {
+            plan,
+            ...(outputs === undefined ? {} : { outputs }),
+            ...(command.cost === undefined ? {} : { cost: cost ?? null }),
+        },
+        render: (style) => [
+            renderPlan(style),
+            ...(outputs === undefined ? [] : ["outputs:", ...outputs.map((path) => `  ${path}`)]),
+            ...(cost === undefined ? [] : [`cost: ${cost}`]),
+        ].join("\n"),
+    };
+}
+export async function execute(command, input, ctx, { dryRun, confirm, yes, force, page, invocation, commandLine, started }) {
+    await checkTools(command.tools ?? [], ctx.env);
     if (command.rows !== undefined) {
         return outcomeOf(await command.run({ ...input, ...page }, ctx), (data, style) => command.render(data, style));
     }
     if (command.effect === "read") {
         return outcomeOf(await command.run(input, ctx), (data, style) => command.render(data, style));
     }
+    if (command.effect === "serve") {
+        const data = await command.start(input, ctx);
+        await started(outcomeOf(data, (value, style) => command.render(value, style)));
+        return untilAborted(ctx.signal);
+    }
     const plan = await command.plan(input, ctx);
     if (dryRun) {
-        return outcomeOf(plan, (value, style) => command.renderPlan(value, style));
+        return dryRunOutcome(command, plan);
     }
+    await checkOutputs({ invocation, commandLine, force, files: ctx.files }, command.outputs?.(plan));
+    checkCost({ invocation, commandLine, yes }, command.cost?.(plan));
     if (command.effect === "destructive") {
         checkConfirmation({ invocation, commandLine, given: confirm }, command.confirm(plan));
     }

package/dist/execute.js.map

@@ -1 +1 @@
-{"version":3,"file":"execute.js","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAsBjD,SAAS,SAAS,CAAQ,KAAY,EAAE,MAA8C;IACpF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,QAAQ,CAAC,OAAgB;IACvC,oFAAoF;IACpF,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAE,OAAO,CAAC,MAAkD,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACnG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAgB,EAChB,KAA8B,EAC9B,GAAY,EACZ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAgB;IAEhE,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAC9E,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAC5B,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAChG,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QACrC,iBAAiB,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AACjG,CAAC"}
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"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"}

package/dist/exit-classes.d.ts

@@ -0,0 +1,31 @@
+import type { Cli } from "./define.js";
+import type { DeclaredExitClass, ErrorTable } from "./error-table.js";
+/** Who must act on a failure (ADR 0005), which sets the exit code. */
+export type ExitClass = "caller" | "operator" | "source" | "wait" | "bug" | "interrupted";
+export declare const SIGNAL_EXIT_CODES: {
+    readonly SIGINT: 130;
+    readonly SIGTERM: 143;
+};
+export type StopSignal = keyof typeof SIGNAL_EXIT_CODES;
+export declare const EXIT_CODES: {
+    readonly caller: 1;
+    readonly operator: 2;
+    readonly source: 3;
+    readonly wait: 75;
+    readonly bug: 70;
+};
+/** The codes of `errors` that the Runtime already declares, which a CLI cannot redeclare. */
+export declare function runtimeCodesIn(errors: ErrorTable): string[];
+export declare function isBug(error: unknown, errors: ErrorTable): boolean;
+/**
+ * The classes other than bug and interrupt that a run of `cli` can end in: those of the Runtime's
+ * codes it can reach, and those of its own table.
+ */
+export declare function reachableExitClasses(cli: Cli): Set<DeclaredExitClass>;
+/** The signal named by an interrupt's abort reason; any other reason counts as Ctrl-C. */
+export declare function stopSignalOf(reason: unknown): StopSignal;
+/**
+ * The exit code of a run that failed with `error`, given the CLI's error table; `stop` is the
+ * signal that interrupted it, if any.
+ */
+export declare function exitCodeOf(error: unknown, errors: ErrorTable, stop: AbortSignal | undefined): number;

package/dist/exit-classes.js

@@ -0,0 +1,107 @@
+import { CONFIRMATION_MISMATCH, CONFIRMATION_REQUIRED } from "./confirm.js";
+import { NOT_CONFIRMED } from "./cost.js";
+import { DOCTOR_PROBLEMS } from "./doctor.js";
+import { DISK_FULL, NOT_FOUND, PERMISSION_DENIED } from "./errno.js";
+import { CliError, errorsOf, INTERNAL_CODE, UsageError } from "./errors.js";
+import { NOT_GLOBAL_INSTALL } from "./global-install.js";
+import { DEADLINE_EXCEEDED, INTERRUPTED } from "./interrupts.js";
+import { UNKNOWN_FIELD } from "./list.js";
+import { INSTALL_FAILED, NO_LATEST, NPM_FAILED, REGISTRY_AUTH, REGISTRY_UNREACHABLE, } from "./npm.js";
+import { OUTPUT_EXISTS } from "./outputs.js";
+import { PROJECT_INVALID } from "./project.js";
+import { TOOL_FAILED } from "./spawn.js";
+import { TOOL_MISSING } from "./tools.js";
+import { INVALID_INPUT, UNKNOWN_COMMAND, UNKNOWN_OPTION } from "./usage.js";
+export const SIGNAL_EXIT_CODES = { SIGINT: 130, SIGTERM: 143 };
+export const EXIT_CODES = {
+    caller: 1,
+    operator: 2,
+    source: 3,
+    wait: 75,
+    bug: 70,
+};
+// Built on call: the modules that throw these codes import this one back (through output.ts), so
+// their constants are not initialised yet while this module loads.
+/** The codes the Runtime and its built-in Commands raise, each with the class that must act on it. */
+function runtimeCodes() {
+    return {
+        [INVALID_INPUT]: "caller",
+        [UNKNOWN_OPTION]: "caller",
+        [UNKNOWN_COMMAND]: "caller",
+        [UNKNOWN_FIELD]: "caller",
+        [CONFIRMATION_REQUIRED]: "caller",
+        [CONFIRMATION_MISMATCH]: "caller",
+        [NOT_CONFIRMED]: "operator",
+        [OUTPUT_EXISTS]: "caller",
+        [INTERRUPTED]: "interrupted",
+        [DEADLINE_EXCEEDED]: "wait",
+        [INTERNAL_CODE]: "bug",
+        [PERMISSION_DENIED]: "operator",
+        [DISK_FULL]: "operator",
+        [NOT_FOUND]: "caller",
+        [TOOL_FAILED]: "operator",
+        [TOOL_MISSING]: "operator",
+        [PROJECT_INVALID]: "operator",
+        [DOCTOR_PROBLEMS]: "operator",
+        [NOT_GLOBAL_INSTALL]: "operator",
+        [REGISTRY_UNREACHABLE]: "operator",
+        [REGISTRY_AUTH]: "operator",
+        [INSTALL_FAILED]: "operator",
+        [NPM_FAILED]: "operator",
+        [NO_LATEST]: "source",
+    };
+}
+/** The codes of `errors` that the Runtime already declares, which a CLI cannot redeclare. */
+export function runtimeCodesIn(errors) {
+    return Object.keys(errors).filter((code) => Object.hasOwn(runtimeCodes(), code));
+}
+// A code that neither the Runtime nor the CLI declares was thrown by mistake: a bug.
+function exitClassOfOne(error, errors) {
+    if (!(error instanceof CliError))
+        return "bug";
+    if (error instanceof UsageError)
+        return "caller";
+    return runtimeCodes()[error.code] ?? errors[error.code]?.class ?? "bug";
+}
+export function isBug(error, errors) {
+    return exitClassOfOne(error, errors) === "bug";
+}
+// Of several errors, the class that must act first decides; any bug makes the whole run one.
+const ACT_FIRST = ["caller", "operator", "source", "wait", "interrupted"];
+function exitClassOf(error, errors) {
+    const classes = errorsOf(error).map((each) => exitClassOfOne(each, errors));
+    if (classes.includes("bug"))
+        return "bug";
+    return ACT_FIRST.find((exitClass) => classes.includes(exitClass)) ?? "bug";
+}
+/**
+ * The classes other than bug and interrupt that a run of `cli` can end in: those of the Runtime's
+ * codes it can reach, and those of its own table.
+ */
+export function reachableExitClasses(cli) {
+    // Any CLI can write files or refuse an unconfirmed cost (the operator's); only `update` fails as
+    // the source's, when the registry has no release.
+    const runtime = [
+        "caller",
+        "operator",
+        "wait",
+        ...(cli.commands !== undefined && cli.install !== undefined ? ["source"] : []),
+    ];
+    const own = Object.values(cli.errors ?? {}).map((declaration) => declaration.class);
+    return new Set([...runtime, ...own]);
+}
+/** The signal named by an interrupt's abort reason; any other reason counts as Ctrl-C. */
+export function stopSignalOf(reason) {
+    return reason === "SIGTERM" ? "SIGTERM" : "SIGINT";
+}
+/**
+ * The exit code of a run that failed with `error`, given the CLI's error table; `stop` is the
+ * signal that interrupted it, if any.
+ */
+export function exitCodeOf(error, errors, stop) {
+    const exitClass = exitClassOf(error, errors);
+    return exitClass === "interrupted"
+        ? SIGNAL_EXIT_CODES[stopSignalOf(stop?.reason)]
+        : EXIT_CODES[exitClass];
+}
+//# sourceMappingURL=exit-classes.js.map

package/dist/exit-classes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-classes.js","sourceRoot":"","sources":["../src/exit-classes.ts"],"names":[],"mappings":"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"}

package/dist/files.d.ts

@@ -0,0 +1,9 @@
+/** The file system as Commands write to it; a test replaces it through `runCli`. */
+export interface Files {
+    /** Writes `data` to the absolute `path` whole or not at all. */
+    write(path: string, data: string | Uint8Array): Promise<void>;
+    /** Whether anything exists at the absolute `path`. */
+    exists(path: string): Promise<boolean>;
+}
+/** Real files for one run: the first write to each folder sweeps the temp files of dead writers. */
+export declare function realFiles(): Files;

package/dist/files.js

@@ -0,0 +1,59 @@
+import { access, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { errnoOf, isMissingFile } from "./errors.js";
+const TEMP_FILE = /^\..+\.agent-cli-(\d+)\.tmp$/;
+function tempPathOf(path) {
+    return join(dirname(path), `.${basename(path)}.agent-cli-${process.pid}.tmp`);
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to another user.
+        return errnoOf(error) === "EPERM";
+    }
+}
+async function sweep(folder) {
+    const names = await readdir(folder);
+    const dead = names.filter((name) => {
+        const pid = TEMP_FILE.exec(name)?.[1];
+        return pid !== undefined && !isAlive(Number(pid));
+    });
+    await Promise.all(dead.map((name) => rm(join(folder, name), { force: true })));
+}
+/** Real files for one run: the first write to each folder sweeps the temp files of dead writers. */
+export function realFiles() {
+    const swept = new Set();
+    return {
+        exists: async (path) => {
+            try {
+                await access(path);
+                return true;
+            }
+            catch (error) {
+                if (isMissingFile(error))
+                    return false;
+                throw error;
+            }
+        },
+        write: async (path, data) => {
+            const folder = dirname(path);
+            if (!swept.has(folder)) {
+                await sweep(folder);
+                swept.add(folder);
+            }
+            const temp = tempPathOf(path);
+            try {
+                await writeFile(temp, data);
+                await rename(temp, path);
+            }
+            catch (error) {
+                await rm(temp, { force: true });
+                throw error;
+            }
+        },
+    };
+}
+//# sourceMappingURL=files.js.map

package/dist/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAUrD,MAAM,SAAS,GAAG,8BAA8B,CAAC;AAEjD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,cAAc,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,OAAO,CAAC,GAAW;IAC1B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yDAAyD;QACzD,OAAO,OAAO,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC;IACpC,CAAC;AACH,CAAC;AAED,KAAK,UAAU,KAAK,CAAC,MAAc;IACjC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QACjC,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACtC,OAAO,GAAG,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACjF,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,SAAS;IACvB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,OAAO;QACL,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACrB,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;gBACnB,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,aAAa,CAAC,KAAK,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACvC,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QACD,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvB,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;gBACpB,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACpB,CAAC;YACD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC5B,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAChC,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/flags.d.ts

@@ -25,6 +25,12 @@ export declare const DRY_RUN_FLAG: StandardFlag & {
 export declare const CONFIRM_FLAG: StandardFlag & {
     readonly flag: "--confirm";
 };
+export declare const YES_FLAG: StandardFlag & {
+    readonly flag: "--yes";
+};
+export declare const FORCE_FLAG: StandardFlag & {
+    readonly flag: "--force";
+};
 declare const EFFECT_FLAGS: {
     readonly read: readonly [StandardFlag & {
         readonly flag: "--json";
@@ -41,10 +47,18 @@ declare const EFFECT_FLAGS: {
     }, StandardFlag & {
         readonly flag: "--confirm";
     }];
+    readonly serve: readonly [StandardFlag & {
+        readonly flag: "--json";
+    }];
 };
-export type StandardFlagName = NameOf<(typeof ROUTING_FLAGS)[number]> | NameOf<(typeof EFFECT_FLAGS)[Effect][number]["flag"]> | ListFlagName;
-/** The Standard flags of a Command with this Effect, and of a List Command. */
-export declare function standardFlagsFor(effect: Effect, list: ListSpec | undefined): readonly StandardFlag[];
+export type StandardFlagName = NameOf<(typeof ROUTING_FLAGS)[number]> | NameOf<(typeof EFFECT_FLAGS)[Effect][number]["flag"]> | NameOf<typeof YES_FLAG.flag> | NameOf<typeof FORCE_FLAG.flag> | ListFlagName;
+/** What a Command declares beyond its Effect that adds Standard flags. */
+export interface Declared {
+    readonly outputs: boolean;
+    readonly cost: boolean;
+}
+/** The Standard flags of a Command with this Effect and declarations, and of a List Command. */
+export declare function standardFlagsFor(effect: Effect, { outputs, cost }: Declared, list: ListSpec | undefined): readonly StandardFlag[];
 /** Throws when the Command declares an arg or option under a Standard flag's name. */
 export declare function checkNoStandardFlags(command: Command): void;
 export {};

package/dist/flags.js

@@ -28,16 +28,38 @@ export const CONFIRM_FLAG = standardFlag("--confirm", {
     takes: "value",
     schema: z.string(),
 });
+export const YES_FLAG = standardFlag("--yes", {
+    description: "approve the cost the run states; --dry-run shows it",
+    takes: "nothing",
+    schema: z.boolean(),
+});
+export const FORCE_FLAG = standardFlag("--force", {
+    description: "replace the files the run writes when they exist; --dry-run lists them",
+    takes: "nothing",
+    schema: z.boolean(),
+});
 const EFFECT_FLAGS = {
     read: [JSON_FLAG],
     write: [JSON_FLAG, DRY_RUN_FLAG],
     destructive: [JSON_FLAG, DRY_RUN_FLAG, CONFIRM_FLAG],
+    serve: [JSON_FLAG],
 };
 // Every name is reserved on every Command, whatever flags it gets, so a name means one thing.
-const RESERVED = new Map([...ROUTING_FLAGS, ...EFFECT_FLAGS.destructive.map(({ flag }) => flag), ...LIST_FLAGS].map((flag) => [nameOf(flag), flag]));
-/** The Standard flags of a Command with this Effect, and of a List Command. */
-export function standardFlagsFor(effect, list) {
-    return [...EFFECT_FLAGS[effect], ...(list?.standardFlags ?? [])];
+const RESERVED = new Map([
+    ...ROUTING_FLAGS,
+    ...EFFECT_FLAGS.destructive.map(({ flag }) => flag),
+    YES_FLAG.flag,
+    FORCE_FLAG.flag,
+    ...LIST_FLAGS,
+].map((flag) => [nameOf(flag), flag]));
+/** The Standard flags of a Command with this Effect and declarations, and of a List Command. */
+export function standardFlagsFor(effect, { outputs, cost }, list) {
+    return [
+        ...EFFECT_FLAGS[effect],
+        ...(outputs ? [FORCE_FLAG] : []),
+        ...(cost ? [YES_FLAG] : []),
+        ...(list?.standardFlags ?? []),
+    ];
 }
 /** Throws when the Command declares an arg or option under a Standard flag's name. */
 export function checkNoStandardFlags(command) {