@duyquangnvx/agent-cli 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,8 +1,12 @@
 export { agentCli } from "./agent-cli.js";
-export { ALREADY_EXISTS, DISK_FULL, NOT_FOUND, PERMISSION_DENIED } from "./errno.js";
+export { ALREADY_EXISTS, DISK_FULL, NOT_A_FILE, NOT_FOUND, PERMISSION_DENIED, } from "./errno.js";
 export { cliError, defineErrors } from "./error-table.js";
 export { CliError, debugVariable, UsageError } from "./errors.js";
-export { paginate } from "./list.js";
+export { DEADLINE_EXCEEDED, INTERRUPTED } from "./interrupts.js";
+export { page, paginate } from "./list.js";
+export { NEEDS_OPERATOR } from "./operator.js";
 export { runCli } from "./run-cli.js";
 export { runProcess } from "./run-process.js";
+export { SIDE_TASK_WAIT_MS } from "./side-task.js";
+export { orStdin, STDIN_IDLE_MS, STDIN_STALLED } from "./stdin.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AA0B1C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAOrF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGlE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AA6B1C,OAAO,EACL,cAAc,EACd,SAAS,EAET,UAAU,EACV,SAAS,EACT,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAOpB,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEjE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/input.d.ts

@@ -11,8 +11,10 @@ export interface InputField {
     readonly defaultValue: unknown;
     readonly description: string | undefined;
     readonly choices: readonly string[] | undefined;
-    /** An arg whose schema is `z.array(...)`, taking every remaining operand; `type` and `choices` are its element's. */
+    /** A `z.array(...)` field: an arg taking every remaining operand, or an option taking every occurrence of its flag; `type` and `choices` are its element's. */
     readonly variadic: boolean;
+    /** Marked with `orStdin`: the operand `-` stands for the text on stdin. */
+    readonly stdin: boolean;
     /** How the caller names it: `<name>` for an arg, `--name` or `--no-name` for an option. */
     readonly label: string;
     /** How the caller passes it: the label plus a value placeholder such as `<value>` or `<a|b>`. */
@@ -23,4 +25,8 @@ export declare function optionField(key: string, schema: z.ZodType): InputField;
 export declare function argFields(schema: InputSchema | undefined): InputField[];
 /** Throws when an arg that takes every remaining operand is not the last arg. */
 export declare function checkArrayArgLast(name: string, args: InputSchema | undefined): void;
+/** Throws unless at most one arg, and no option, is marked with `orStdin`. */
+export declare function checkStdinFields(name: string, args: InputSchema | undefined, options: InputSchema | undefined): void;
 export declare function optionFields(schema: InputSchema | undefined): InputField[];
+/** Throws when an option is an array of booleans, which a switch cannot express. */
+export declare function checkNoBooleanArrayOption(name: string, options: InputSchema | undefined): void;

package/dist/input.js

@@ -1,4 +1,5 @@
 import * as z from "zod";
+import { isStdinSchema } from "./stdin.js";
 function isWrapper(schema) {
     return (schema instanceof z.ZodOptional ||
         schema instanceof z.ZodNullable ||
@@ -20,6 +21,7 @@ function describe(schema) {
     let description = current.description;
     let required = true;
     let defaultValue;
+    let stdin = isStdinSchema(current);
     while (isWrapper(current)) {
         if (current instanceof z.ZodDefault || current instanceof z.ZodPrefault) {
             defaultValue = current.def.defaultValue;
@@ -27,6 +29,7 @@ function describe(schema) {
         required = false;
         current = current.unwrap();
         description ??= current.description;
+        stdin ||= isStdinSchema(current);
     }
     const variadic = current instanceof z.ZodArray;
     if (current instanceof z.ZodArray) {
@@ -39,9 +42,13 @@ function describe(schema) {
         description,
         choices: current instanceof z.ZodEnum ? current.options.map(String) : undefined,
         variadic,
+        stdin,
     };
 }
-function argLabel(key, { variadic, required }) {
+function argLabel(key, { variadic, required, stdin }) {
+    if (stdin) {
+        return required ? `<${key}|->` : `[${key}|-]`;
+    }
     if (!variadic) {
         return `<${key}>`;
     }
@@ -58,7 +65,8 @@ export function optionField(key, schema) {
     const isBoolean = described.type === "boolean";
     // A boolean that defaults to true can only be changed by turning it off.
     const label = isBoolean && described.defaultValue === true ? `--no-${name}` : `--${name}`;
-    const usage = isBoolean ? label : `${label} <${described.choices?.join("|") ?? "value"}>`;
+    const value = `<${described.choices?.join("|") ?? "value"}>${described.variadic ? "..." : ""}`;
+    const usage = isBoolean ? label : `${label} ${value}`;
     return { key, name, schema, ...described, label, usage };
 }
 function fieldsOf(schema, toField) {
@@ -69,17 +77,38 @@ function fieldsOf(schema, toField) {
 export function argFields(schema) {
     return fieldsOf(schema, argField);
 }
+function keysOf(fields) {
+    return fields.map(({ key }) => `'${key}'`).join(", ");
+}
 /** Throws when an arg that takes every remaining operand is not the last arg. */
 export function checkArrayArgLast(name, args) {
     const misplaced = argFields(args)
         .slice(0, -1)
         .filter((field) => field.variadic);
     if (misplaced.length > 0) {
-        const keys = misplaced.map(({ key }) => `'${key}'`).join(", ");
-        throw new Error(`Command '${name}' declares array arg ${keys} before its last arg; only the last arg may be an array`);
+        throw new Error(`Command '${name}' declares array arg ${keysOf(misplaced)} before its last arg; only the last arg may be an array`);
+    }
+}
+/** Throws unless at most one arg, and no option, is marked with `orStdin`. */
+export function checkStdinFields(name, args, options) {
+    const stdinArgs = argFields(args).filter((field) => field.stdin);
+    if (stdinArgs.length > 1) {
+        throw new Error(`Command '${name}' marks args ${keysOf(stdinArgs)} with orStdin; only one arg may read stdin`);
+    }
+    const stdinOptions = optionFields(options).filter((field) => field.stdin);
+    if (stdinOptions.length > 0) {
+        const noun = stdinOptions.length === 1 ? "option" : "options";
+        throw new Error(`Command '${name}' marks ${noun} ${keysOf(stdinOptions)} with orStdin; only an arg may read stdin`);
     }
 }
 export function optionFields(schema) {
     return fieldsOf(schema, optionField);
 }
+/** Throws when an option is an array of booleans, which a switch cannot express. */
+export function checkNoBooleanArrayOption(name, options) {
+    const booleans = optionFields(options).filter((field) => field.variadic && field.type === "boolean");
+    if (booleans.length > 0) {
+        throw new Error(`Command '${name}' declares boolean array option ${keysOf(booleans)}; a switch cannot repeat, use a boolean`);
+    }
+}
 //# sourceMappingURL=input.js.map

package/dist/input.js.map

@@ -1 +1 @@
-{"version":3,"file":"input.js","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA4B3C,SAAS,SAAS,CAAC,MAAiB;IAClC,OAAO,CACL,MAAM,YAAY,CAAC,CAAC,WAAW;QAC/B,MAAM,YAAY,CAAC,CAAC,WAAW;QAC/B,MAAM,YAAY,CAAC,CAAC,UAAU;QAC9B,MAAM,YAAY,CAAC,CAAC,WAAW,CAChC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,GAAW;IAC/B,OAAO,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,0EAA0E;AAC1E,SAAS,MAAM,CAAC,MAAiB;IAC/B,IAAI,MAAM,YAAY,CAAC,CAAC,SAAS,EAAE,CAAC;QAClC,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,MAAM,YAAY,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC/D,CAAC;AAED,SAAS,QAAQ,CAAC,MAAiB;IACjC,IAAI,OAAO,GAAG,MAAM,CAAC;IACrB,IAAI,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACtC,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,IAAI,YAAqB,CAAC;IAC1B,IAAI,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,IAAI,OAAO,YAAY,CAAC,CAAC,UAAU,IAAI,OAAO,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;YACxE,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QAC1C,CAAC;QACD,QAAQ,GAAG,KAAK,CAAC;QACjB,OAAO,GAAG,OAAO,CAAC,MAAM,EAAe,CAAC;QACxC,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC;QACpC,KAAK,KAAK,aAAa,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,YAAY,CAAC,CAAC,QAAQ,CAAC;IAC/C,IAAI,OAAO,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC;QAClC,OAAO,GAAG,OAAO,CAAC,OAAoB,CAAC;IACzC,CAAC;IACD,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC;QACrB,QAAQ;QACR,YAAY;QACZ,WAAW;QACX,OAAO,EAAE,OAAO,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;QAC/E,QAAQ;QACR,KAAK;KACN,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAa;IACrE,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC;IAChD,CAAC;IACD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,GAAG,GAAG,CAAC;IACpB,CAAC;IACD,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,MAAM,CAAC;AAClD,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW,EAAE,MAAiB;IAC9C,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACvC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,MAAiB;IACxD,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC;IAC/C,yEAAyE;IACzE,MAAM,KAAK,GAAG,SAAS,IAAI,SAAS,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;IAC1F,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,OAAO,IAAI,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC/F,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,KAAK,EAAE,CAAC;IACtD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC3D,CAAC;AAED,SAAS,QAAQ,CACf,MAA+B,EAC/B,OAAuD;IAEvD,OAAO,MAAM,KAAK,SAAS;QACzB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAA+B;IACvD,OAAO,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,MAAM,CAAC,MAA6B;IAC3C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,IAA6B;IAC3E,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC;SAC9B,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;SACZ,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,wBAAwB,MAAM,CAAC,SAAS,CAAC,yDAAyD,CACnH,CAAC;IACJ,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,IAA6B,EAC7B,OAAgC;IAEhC,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,gBAAgB,MAAM,CAAC,SAAS,CAAC,4CAA4C,CAC9F,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1E,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9D,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,WAAW,IAAI,IAAI,MAAM,CAAC,YAAY,CAAC,2CAA2C,CACnG,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAA+B;IAC1D,OAAO,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AACvC,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,yBAAyB,CAAC,IAAY,EAAE,OAAgC;IACtF,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,MAAM,CAC3C,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CACtD,CAAC;IACF,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,mCAAmC,MAAM,CAAC,QAAQ,CAAC,yCAAyC,CAC7G,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/interrupts.d.ts

@@ -12,7 +12,7 @@ export interface RunControlOptions {
     /** The whole run's deadline and the hint, naming the resume command line, it ends with. */
     readonly runDeadline: {
         readonly ms: number;
-        readonly hint: string;
+        readonly hint: () => string;
     } | undefined;
 }
 /** One Command run's cancellation: its signal, its deadlines and the steps it must finish. */
@@ -21,12 +21,17 @@ export declare class RunControl {
     readonly signal: AbortSignal;
     constructor({ commandLine, outer, clock, progress, runDeadline }: RunControlOptions);
     deadline(ms: number): AbortSignal;
+    timeout(ms: number): AbortSignal;
     runToEnd<T>(name: string, work: () => Promise<T>): Promise<T>;
     /** Waits for the Command, its must-finish steps, and no longer than the grace once interrupted. */
     settle<T>(work: Promise<T>): Promise<T>;
     /**
-     * The error a run ends with: an interrupt or a missed deadline outranks what the Command threw,
+     * The error a run ends with: an interrupt or the run deadline outranks what the Command threw,
      * unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
+     * Otherwise each leaf that is not a `CliError` and whose cause chain holds a deadline's or timeout's
+     * abort is reported as that abort, so a declared error keeps its own code.
      */
     errorAfter(error: unknown): unknown;
+    /** Stops the run's timers and its hold on the caller's signal, for a run that never settles. */
+    close(): void;
 }

package/dist/interrupts.js

@@ -1,5 +1,5 @@
 import { after } from "./clock.js";
-import { CliError } from "./errors.js";
+import { CliError, causesOf, errorsOf } from "./errors.js";
 export const INTERRUPTED = "INTERRUPTED";
 export const DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED";
 /** How long an interrupted Command may take to settle before the run ends without it. */
@@ -13,10 +13,10 @@ function interruptedError() {
     });
 }
 const WAIT_HINT = "run it again later, when the service it waits on may answer faster";
-function deadlineError(commandLine, ms, hint) {
+function deadlineError(commandLine, ms, hint, bound = "deadline") {
     return new CliError({
         code: DEADLINE_EXCEEDED,
-        message: `${commandLine} ran past its ${ms} ms deadline`,
+        message: `${commandLine} ran past its ${ms} ms ${bound}`,
         hint,
     });
 }
@@ -32,7 +32,8 @@ export class RunControl {
     #progress;
     #clock;
     #disposed = new AbortController();
-    #deadlineHit;
+    /** The reasons this run's deadlines and timeouts aborted with, to tell them in a Command's error. */
+    #abortReasons = new WeakSet();
     #graceCancel = new AbortController();
     #endGrace = () => { };
     #graceOver = new Promise((resolve) => {
@@ -53,16 +54,23 @@ export class RunControl {
         }
         if (runDeadline !== undefined) {
             const { ms, hint } = runDeadline;
-            after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, hint)));
+            after(clock, ms, this.#disposed.signal, () => this.#controller.abort(deadlineError(commandLine, ms, hint())));
         }
     }
     deadline(ms) {
+        return AbortSignal.any([this.signal, this.#abortsAfter(ms, "deadline")]);
+    }
+    timeout(ms) {
+        return this.#abortsAfter(ms, "timeout");
+    }
+    #abortsAfter(ms, bound) {
         const controller = new AbortController();
         after(this.#clock, ms, this.#disposed.signal, () => {
-            this.#deadlineHit ??= deadlineError(this.#commandLine, ms, WAIT_HINT);
-            controller.abort(this.#deadlineHit);
+            const reason = deadlineError(this.#commandLine, ms, WAIT_HINT, bound);
+            this.#abortReasons.add(reason);
+            controller.abort(reason);
         });
-        return AbortSignal.any([this.signal, controller.signal]);
+        return controller.signal;
     }
     async runToEnd(name, work) {
         this.#graceCancel.abort();
@@ -91,21 +99,26 @@ export class RunControl {
         }
         finally {
             await this.#stepsDone();
-            this.#dispose();
+            this.close();
         }
     }
     /**
-     * The error a run ends with: an interrupt or a missed deadline outranks what the Command threw,
+     * The error a run ends with: an interrupt or the run deadline outranks what the Command threw,
      * unless the Command threw its own `INTERRUPTED`, saying what it finished before it stopped.
+     * Otherwise each leaf that is not a `CliError` and whose cause chain holds a deadline's or timeout's
+     * abort is reported as that abort, so a declared error keeps its own code.
      */
     errorAfter(error) {
         if (this.signal.aborted) {
             return error instanceof CliError && error.code === INTERRUPTED ? error : this.signal.reason;
         }
-        if (this.#deadlineHit !== undefined && !(error instanceof CliError)) {
-            return this.#deadlineHit;
-        }
-        return error;
+        const leaves = errorsOf(error).map((leaf) => this.#abortIn(leaf) ?? leaf);
+        return leaves.length === 1 ? leaves[0] : new AggregateError(leaves);
+    }
+    #abortIn(error) {
+        if (error instanceof CliError)
+            return undefined;
+        return causesOf(error).find((each) => each instanceof CliError && this.#abortReasons.has(each));
     }
     #onStop() {
         for (const name of this.#steps.values())
@@ -127,7 +140,8 @@ export class RunControl {
             await Promise.all(this.#steps.keys());
         }
     }
-    #dispose() {
+    /** Stops the run's timers and its hold on the caller's signal, for a run that never settles. */
+    close() {
         this.#graceCancel.abort();
         this.#disposed.abort();
         this.#outer?.removeEventListener("abort", this.#onOuterAbort);

package/dist/interrupts.js.map

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

package/dist/invocation.d.ts

@@ -1,14 +1,19 @@
+import { type KnownFlag } from "./tokenize.js";
 export declare const END_OF_OPTIONS = "--";
 export interface Invocation {
     readonly cliName: string;
     readonly argv: readonly string[];
+    /** What each flag of the routed Command takes after it; empty before routing. */
+    readonly flags: readonly KnownFlag[];
+}
+export interface CommandLineChange {
+    readonly add?: readonly string[];
+    readonly remove?: readonly string[];
 }
-/** The caller's command line as typed, ready to paste. */
-export declare function commandLineOf({ cliName, argv }: Invocation): string;
 /**
- * The caller's command line, ready to paste, with `flag value` (or `flag` alone, for a flag that
- * takes nothing) replacing any value they gave.
+ * The caller's command line as typed, ready to paste, with each flag in `remove` dropped along with
+ * its value and the words in `add` placed before any `--`.
  */
-export declare function commandLineWith({ cliName, argv }: Invocation, flag: string, value?: string): string;
+export declare function commandLineOf({ cliName, argv, flags }: Invocation, { add, remove }?: CommandLineChange): string;
 /** The caller's command line, ready to paste, with each flag in `renames` typed as its new name. */
 export declare function commandLineRenaming({ cliName, argv }: Invocation, renames: ReadonlyMap<string, string>): string;

package/dist/invocation.js

@@ -1,3 +1,4 @@
+import { isOptionLike } from "./tokenize.js";
 export const END_OF_OPTIONS = "--";
 const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
 // POSIX quoting: Coding agents run commands in a POSIX shell, Git Bash included on Windows.
@@ -7,27 +8,39 @@ function quoted(token) {
 function pasteable(cliName, tokens) {
     return [cliName, ...tokens].map(quoted).join(" ");
 }
-/** The caller's command line as typed, ready to paste. */
-export function commandLineOf({ cliName, argv }) {
-    return pasteable(cliName, argv);
-}
 function split(argv) {
     const end = argv.indexOf(END_OF_OPTIONS);
     return end === -1
         ? { options: [...argv], operands: [] }
         : { options: argv.slice(0, end), operands: argv.slice(end) };
 }
-function without(flag, tokens) {
-    return tokens.filter((token, index) => token !== flag && !token.startsWith(`${flag}=`) && tokens[index - 1] !== flag);
+// Mirrors how `tokenize` reads the flag, so the word it took as the value goes with it.
+function tookValue(takes, next) {
+    return (takes === "value" || (takes === "optional value" && next !== undefined && !isOptionLike(next)));
+}
+function without(flag, takes, tokens) {
+    const kept = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index] ?? "";
+        if (token === flag) {
+            if (tookValue(takes, tokens[index + 1]))
+                index += 1;
+        }
+        else if (!token.startsWith(`${flag}=`)) {
+            kept.push(token);
+        }
+    }
+    return kept;
 }
 /**
- * The caller's command line, ready to paste, with `flag value` (or `flag` alone, for a flag that
- * takes nothing) replacing any value they gave.
+ * The caller's command line as typed, ready to paste, with each flag in `remove` dropped along with
+ * its value and the words in `add` placed before any `--`.
  */
-export function commandLineWith({ cliName, argv }, flag, value) {
+export function commandLineOf({ cliName, argv, flags }, { add = [], remove = [] } = {}) {
     const { options, operands } = split(argv);
-    const added = value === undefined ? [flag] : [flag, value];
-    return pasteable(cliName, [...without(flag, options), ...added, ...operands]);
+    const takes = new Map(flags.map((known) => [known.flag, known.takes]));
+    const kept = remove.reduce((tokens, flag) => without(flag, takes.get(flag) ?? "nothing", tokens), options);
+    return pasteable(cliName, [...kept, ...add, ...operands]);
 }
 function renamed(token, renames) {
     const [flag = token, ...value] = token.split("=");

package/dist/invocation.js.map

@@ -1 +1 @@
-{"version":3,"file":"invocation.js","sourceRoot":"","sources":["../src/invocation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"invocation.js","sourceRoot":"","sources":["../src/invocation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA8B,MAAM,eAAe,CAAC;AAEzE,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AACnC,MAAM,UAAU,GAAG,kBAAkB,CAAC;AActC,4FAA4F;AAC5F,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;AAChF,CAAC;AAED,SAAS,SAAS,CAAC,OAAe,EAAE,MAAyB;IAC3D,OAAO,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,KAAK,CAAC,IAAuB;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACzC,OAAO,GAAG,KAAK,CAAC,CAAC;QACf,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE;QACtC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;AACjE,CAAC;AAED,wFAAwF;AACxF,SAAS,SAAS,CAAC,KAAY,EAAE,IAAwB;IACvD,OAAO,CACL,KAAK,KAAK,OAAO,IAAI,CAAC,KAAK,KAAK,gBAAgB,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAC/F,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,KAAY,EAAE,MAAyB;IACpE,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;gBAAE,KAAK,IAAI,CAAC,CAAC;QACtD,CAAC;aAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAc,EACpC,EAAE,GAAG,GAAG,EAAE,EAAE,MAAM,GAAG,EAAE,EAAE,GAAsB,EAAE;IAEjD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACvE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CACxB,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,MAAM,CAAC,EACrE,OAAO,CACR,CAAC;IACF,OAAO,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,GAAG,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,OAAO,CAAC,KAAa,EAAE,OAAoC;IAClE,MAAM,CAAC,IAAI,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,mBAAmB,CACjC,EAAE,OAAO,EAAE,IAAI,EAAc,EAC7B,OAAoC;IAEpC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC;AAC/F,CAAC"}

package/dist/list.d.ts

@@ -6,16 +6,25 @@ export declare const UNKNOWN_FIELD = "UNKNOWN_FIELD";
 declare const FIELDS_FLAG = "--fields";
 export declare const PAGE_INPUT: z.ZodObject<{
     limit: z.ZodDefault<z.ZodNumber>;
-    cursor: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PageInput = z.output<typeof PAGE_INPUT>;
 export type ListFlagName = keyof PageInput | NameOf<typeof FIELDS_FLAG>;
 export type RowSchema = z.ZodObject;
 export declare class Page<Item> {
     readonly items: readonly Item[];
-    readonly nextCursor: number | undefined;
-    constructor(items: readonly Item[], nextCursor: number | undefined);
+    readonly nextCursor: string | undefined;
+    constructor(items: readonly Item[], nextCursor: string | undefined);
 }
+/**
+ * A page whose source pages itself, such as a remote API: `next` is the cursor the source gave for
+ * the following page, which the caller passes back as `--cursor`, or absent on the last page.
+ */
+export declare function page<Item>(items: readonly Item[], next?: string): Page<Item>;
+/**
+ * The page of `items` that `limit` and `cursor` select, for a list held whole in memory; a cursor
+ * it never gave is a usage error.
+ */
 export declare function paginate<Item>(items: readonly Item[], { limit, cursor }: PageInput): Page<Item>;
 /** What the Runtime adds to a List Command, derived from its row schema. */
 export interface ListSpec {

package/dist/list.js

@@ -1,7 +1,7 @@
 import * as z from "zod";
 import { UsageError } from "./errors.js";
 import { optionField, optionFields } from "./input.js";
-import { commandLineWith } from "./invocation.js";
+import { commandLineOf } from "./invocation.js";
 import { INVALID_INPUT } from "./usage.js";
 export const UNKNOWN_FIELD = "UNKNOWN_FIELD";
 const DEFAULT_PAGE_LIMIT = 20;
@@ -9,9 +9,10 @@ const FIELDS_FLAG = "--fields";
 const SEPARATOR = ",";
 const COLUMN_SEPARATOR = "\t";
 const UNSAFE_IN_COLUMN = /[\t\n\r]/;
+const OFFSET = /^\d+$/;
 export const PAGE_INPUT = z.object({
     limit: z.number().int().positive().default(DEFAULT_PAGE_LIMIT),
-    cursor: z.number().int().nonnegative().optional(),
+    cursor: z.string().min(1).optional(),
 });
 export class Page {
     items;
@@ -21,9 +22,32 @@ export class Page {
         this.nextCursor = nextCursor;
     }
 }
-export function paginate(items, { limit, cursor = 0 }) {
-    const end = cursor + limit;
-    return new Page(items.slice(cursor, end), end < items.length ? end : undefined);
+/**
+ * A page whose source pages itself, such as a remote API: `next` is the cursor the source gave for
+ * the following page, which the caller passes back as `--cursor`, or absent on the last page.
+ */
+export function page(items, next) {
+    return new Page(items, next);
+}
+function offsetOf(cursor, length) {
+    const offset = Number(cursor);
+    if (!OFFSET.test(cursor) || String(offset) !== cursor || offset > length) {
+        throw new UsageError({
+            code: INVALID_INPUT,
+            message: `--cursor ${cursor}: not a cursor this list gave`,
+            hint: "drop --cursor to start from the first page, then follow each page's next",
+        });
+    }
+    return offset;
+}
+/**
+ * The page of `items` that `limit` and `cursor` select, for a list held whole in memory; a cursor
+ * it never gave is a usage error.
+ */
+export function paginate(items, { limit, cursor }) {
+    const start = cursor === undefined ? 0 : offsetOf(cursor, items.length);
+    const end = start + limit;
+    return new Page(items.slice(start, end), end < items.length ? String(end) : undefined);
 }
 const PAGE_FLAG_DESCRIPTIONS = {
     limit: `how many rows to show, a positive whole number (default: ${DEFAULT_PAGE_LIMIT})`,
@@ -112,12 +136,20 @@ export function renderRows(rows, fields) {
     const lines = [fields, ...rows.map((row) => fields.map((field) => cell(row[field])))];
     return `${lines.map((line) => line.join(COLUMN_SEPARATOR)).join("\n")}\n`;
 }
+// A cursor starting with `-` would read as a flag, so it rides on `=`.
+function cursorWords(cursor) {
+    const { flag } = PAGE_FLAGS.cursor;
+    return cursor.startsWith("-") ? [`${flag}=${cursor}`] : [flag, cursor];
+}
 export function printedPage(page, invocation) {
     return page.nextCursor === undefined
         ? { items: page.items }
         : {
             items: page.items,
-            next: commandLineWith(invocation, PAGE_FLAGS.cursor.flag, String(page.nextCursor)),
+            next: commandLineOf(invocation, {
+                remove: [PAGE_FLAGS.cursor.flag],
+                add: cursorWords(page.nextCursor),
+            }),
         };
 }
 /** The line that ends a rendered page, so the caller always knows whether and how to get more. */

package/dist/list.js.map

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

package/dist/manifest.d.ts

@@ -0,0 +1,17 @@
+import * as z from "zod";
+declare const manifestSchema: z.ZodObject<{
+    repository: z.ZodCatch<z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>]>, z.ZodTransform<string, string | {
+        url: string;
+    }>>>>;
+    bugs: z.ZodCatch<z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>]>, z.ZodTransform<string, string | {
+        url: string;
+    }>>>>;
+}, z.core.$strip>;
+/** The fields of the CLI's package.json the Runtime reads; each is absent when missing or malformed. */
+export type Manifest = z.infer<typeof manifestSchema>;
+export declare function manifestAt(packageRoot: string): Manifest;
+export {};

package/dist/manifest.js

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import * as z from "zod";
+const link = z
+    .union([z.string(), z.object({ url: z.string() })])
+    .transform((value) => (typeof value === "string" ? value : value.url))
+    .optional()
+    .catch(undefined);
+const manifestSchema = z.object({ repository: link, bugs: link });
+const NO_MANIFEST = {};
+// The fields only help, so a package.json that cannot be read or parsed gives none. It is read
+// synchronously because an error's hint, which may name `bugs`, is built synchronously.
+export function manifestAt(packageRoot) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+    }
+    catch {
+        return NO_MANIFEST;
+    }
+    const parsed = manifestSchema.safeParse(manifest);
+    return parsed.success ? parsed.data : NO_MANIFEST;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,MAAM,IAAI,GAAG,CAAC;KACX,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC;KAClD,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;KACrE,QAAQ,EAAE;KACV,KAAK,CAAC,SAAS,CAAC,CAAC;AAEpB,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAKlE,MAAM,WAAW,GAAa,EAAE,CAAC;AAEjC,+FAA+F;AAC/F,wFAAwF;AACxF,MAAM,UAAU,UAAU,CAAC,WAAmB;IAC5C,IAAI,QAAiB,CAAC;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;AACpD,CAAC"}

package/dist/operator.d.ts

@@ -0,0 +1,5 @@
+import type { CommandSpec } from "./command-spec.js";
+import type { Env } from "./context.js";
+export declare const NEEDS_OPERATOR = "NEEDS_OPERATOR";
+/** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
+export declare function checkOperator({ operator, commandLine }: CommandSpec, env: Env, callerLine: string): void;

package/dist/operator.js

@@ -0,0 +1,15 @@
+import { isAgent } from "./agent.js";
+import { CliError } from "./errors.js";
+export const NEEDS_OPERATOR = "NEEDS_OPERATOR";
+/** Fails with `NEEDS_OPERATOR` when a Coding agent runs an Operator Command. */
+export function checkOperator({ operator, commandLine }, env, callerLine) {
+    if (!operator || !isAgent(env))
+        return;
+    throw new CliError({
+        code: NEEDS_OPERATOR,
+        message: `\`${commandLine}\` must be run by a person at a terminal, not a Coding agent`,
+        // Typed at Claude Code's prompt, `!` runs the rest of the line in the operator's own shell.
+        hint: `ask the operator to type: ! ${callerLine}`,
+    });
+}
+//# sourceMappingURL=operator.js.map

package/dist/operator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.js","sourceRoot":"","sources":["../src/operator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAE/C,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAC3B,EAAE,QAAQ,EAAE,WAAW,EAAe,EACtC,GAAQ,EACR,UAAkB;IAElB,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO;IACvC,MAAM,IAAI,QAAQ,CAAC;QACjB,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,KAAK,WAAW,8DAA8D;QACvF,4FAA4F;QAC5F,IAAI,EAAE,+BAA+B,UAAU,EAAE;KAClD,CAAC,CAAC;AACL,CAAC"}