@duyquangnvx/agent-cli 0.16.0 → 0.18.0

package/dist/context/stdin.js.map

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

package/dist/{tools.d.ts → context/tools.d.ts}

@@ -1,9 +1,10 @@
-import type { Env } from "./context.js";
-import { type Commands, type DoctorCheck, type Tool } from "./define.js";
+import type { Env } from "../context.js";
+import type { Commands, DoctorCheck, Tool } from "../define.js";
+import { type Rerun } from "../next-step.js";
 export declare const TOOL_MISSING = "TOOL_MISSING";
 /** Where `name` is found on `PATH` from `env`, or undefined. */
 export declare function findTool(name: string, env: Env): Promise<string | undefined>;
 /** Fails with `TOOL_MISSING`, naming every missing tool at once, unless all are on `PATH`. */
-export declare function checkTools(tools: readonly Tool[], env: Env, callerLine: string): Promise<void>;
+export declare function checkTools(tools: readonly Tool[], env: Env, rerun: Rerun): Promise<void>;
 /** One `doctor` row per distinct tool the CLI and its Commands declare, with its install command as the fix. */
 export declare function toolRows(tools: readonly Tool[], commands: Commands): DoctorCheck[];

package/dist/{tools.js → context/tools.js}

@@ -1,8 +1,9 @@
 import { constants } from "node:fs";
 import { access } from "node:fs/promises";
 import { delimiter, extname, join } from "node:path";
-import { isCommand } from "./define.js";
-import { CliError, errnoOf, isNothingThere } from "./errors.js";
+import { errnoOf, isNothingThere, runtimeError } from "../errors.js";
+import { wholeLine } from "../next-step.js";
+import { declaredIn } from "./declared.js";
 export const TOOL_MISSING = "TOOL_MISSING";
 const WINDOWS_EXTENSIONS = ".COM;.EXE;.BAT;.CMD";
 function pathOf(env) {
@@ -45,25 +46,22 @@ export async function findTool(name, env) {
     return undefined;
 }
 /** Fails with `TOOL_MISSING`, naming every missing tool at once, unless all are on `PATH`. */
-export async function checkTools(tools, env, callerLine) {
+export async function checkTools(tools, env, rerun) {
     const found = await Promise.all(tools.map((tool) => findTool(tool.name, env)));
     const missing = tools.filter((_tool, index) => found[index] === undefined);
     if (missing.length === 0)
         return;
     const names = missing.map(({ name }) => name).join(", ");
-    throw new CliError({
+    throw runtimeError({
         code: TOOL_MISSING,
         message: `${missing.length === 1 ? "a tool it runs is" : "tools it runs are"} not on PATH: ${names}`,
-        hint: `install ${missing.map(({ name, install }) => `${name} (\`${install}\`)`).join(", ")}, then run \`${callerLine}\` again`,
+        hint: "run the Next steps in order: each install, then the command again",
+        next: [...missing.map(({ install }) => wholeLine(install)), rerun],
     });
 }
-function toolsIn(node) {
-    return isCommand(node) ? [...(node.tools ?? [])] : Object.values(node).flatMap(toolsIn);
-}
 /** One `doctor` row per distinct tool the CLI and its Commands declare, with its install command as the fix. */
 export function toolRows(tools, commands) {
-    const byName = new Map([...tools, ...toolsIn(commands)].map((tool) => [tool.name, tool]));
-    return [...byName.values()].map(({ name, install }) => ({
+    return declaredIn(tools, commands, (command) => command.tools).map(({ name, install }) => ({
         name,
         run: async (ctx) => {
             const file = await findTool(name, ctx.env);

package/dist/context/tools.js.map

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

package/dist/context.d.ts

@@ -1,10 +1,14 @@
 import type * as z from "zod";
 import type { Clock } from "./clock.js";
-import type { FileAccess } from "./errno.js";
-import type { Files } from "./files.js";
-import type { CommandLineChange } from "./invocation.js";
-import type { Secret } from "./secrets.js";
-import type { ContextSpawn, ContextSpawnDetached } from "./spawn.js";
+import type { CommandLineChange } from "./command-line/invocation.js";
+import type { FileAccess } from "./context/errno.js";
+import type { Files } from "./context/files.js";
+import type { DeadlineOptions } from "./context/interrupts.js";
+import type { Secret } from "./context/secrets.js";
+import type { ContextSpawn, ContextSpawnDetached } from "./context/spawn.js";
+import type { CliErrorInit, ErrorTable, NoErrors } from "./error-table.js";
+import type { CliError } from "./errors.js";
+import type { Rerun } from "./next-step.js";
 export type Env = Readonly<Record<string, string | undefined>>;
 export interface PollOptions {
     readonly intervalMs: number;
@@ -17,7 +21,18 @@ export interface BuildStamp {
     readonly dirty: boolean;
     readonly builtAt: string;
 }
-export interface Context<Ports = unknown, Settings = unknown> {
+/**
+ * What a Command declares it needs, which types its `ctx`: `secretName`, the names of its `secrets`,
+ * and `errors`, the part of the Error table its `errors` names.
+ */
+export interface Needs<SecretName extends string = string, Errors extends ErrorTable = ErrorTable> {
+    readonly secretName: SecretName;
+    readonly errors: Errors;
+}
+/** The Needs of a Command that declares no Secrets and no errors. */
+export type NoNeeds = Needs<never, NoErrors>;
+/** `Declared` is what the Command declares it needs, so `secret` and `fail` take only those. */
+export interface Context<Ports = unknown, Settings = unknown, Declared extends Needs = NoNeeds> {
     readonly cwd: string;
     readonly env: Env;
     /** The CLI's version, as `--version` prints it. */
@@ -56,15 +71,11 @@ export interface Context<Ports = unknown, Settings = unknown> {
      * Returns a signal that aborts with `ctx.signal`, and with `DEADLINE_EXCEEDED` (exit 75) once
      * `ms` have passed. The run reports that deadline for each error, or leaf of an `AggregateError`,
      * that is not a `CliError` and whose `cause` chain holds its abort; any other error is reported
-     * as it is, so a `CliError` keeping the abort as `cause` keeps its own code.
+     * as it is, so a `CliError` keeping the abort as `cause` keeps its own code. With `ignoreStop`,
+     * it follows neither `ctx.signal` nor the run deadline: it bounds a call inside `runToEnd` that
+     * Ctrl-C must not cut short, and its hint warns the call may have been billed.
      */
-    deadline(ms: number): AbortSignal;
-    /**
-     * Returns a signal that aborts with `DEADLINE_EXCEEDED` (exit 75) once `ms` have passed, and
-     * follows neither `ctx.signal` nor the run deadline: it bounds a call inside `runToEnd` that
-     * Ctrl-C must not cut short. Its abort is reported as `ctx.deadline`'s is.
-     */
-    timeout(ms: number): AbortSignal;
+    deadline(ms: number, options?: DeadlineOptions): AbortSignal;
     /**
      * Runs a step that must not stop halfway: the run waits for it even when stopped, and then
      * prints `finishing <name>` on stderr.
@@ -76,13 +87,13 @@ export interface Context<Ports = unknown, Settings = unknown> {
      * returned value replaces it. Delivered data spills like returned data.
      */
     deliver(data: unknown): void;
-    /** The outside systems the CLI declared with `agentCli<Ports>()`. */
+    /** The outside systems the CLI declared with `agentCli({ ports })`. */
     readonly ports: Ports;
     /**
      * Reads, lists, removes and atomically writes files and folders, paths resolved against `cwd`. A
      * failure fails the run naming the path: `PERMISSION_DENIED` (exit 2, with a hint on allowing the
      * path in a Coding agent's sandbox), `DISK_FULL` (exit 2), `NOT_FOUND`, `NOT_A_FILE` or
-     * `ALREADY_EXISTS` (exit 1); the codes are exported.
+     * `ALREADY_EXISTS` (exit 1); the codes are on `runtimeCodes`.
      */
     readonly files: Files;
     /**
@@ -111,10 +122,16 @@ export interface Context<Ports = unknown, Settings = unknown> {
      */
     readonly project: Project<Settings> | undefined;
     /**
-     * Reads `name` from the env, then from `$XDG_CONFIG_HOME/<cli>/.env` (default `~/.config`), with
-     * where it came from; a `.env` it cannot read fails the run with `PERMISSION_DENIED`.
+     * One of the Command's declared `secrets`, with where it came from: the env, then
+     * `$XDG_CONFIG_HOME/<cli>/.env` (default `~/.config`). The Runtime checked each before the
+     * Command started, so it is always set.
      */
-    secret(name: string): Secret | undefined;
+    secret(name: Declared["secretName"]): Secret;
+    /**
+     * The `CliError` for one of the Command's declared `errors`, as `cliError` builds it, for the
+     * Command to throw: `details` must match the code's schema.
+     */
+    fail<Code extends keyof Declared["errors"] & string>(code: Code, init: CliErrorInit<Declared["errors"][Code]>, options?: ErrorOptions): CliError;
     /**
      * The `.env` that `secret` reads: `$XDG_CONFIG_HOME/<cli>/.env`, or `~/.config/<cli>/.env`
      * without it. Name it in a hint that asks for a missing key.
@@ -128,16 +145,15 @@ export interface Context<Ports = unknown, Settings = unknown> {
     /** Whether the caller passed `--force`; always false for a Command without it. */
     readonly force: boolean;
     /**
-     * The command line as the caller typed it, starting with the CLI's name and shell-quoted, with
-     * each flag in `remove` dropped along with its value (`--from 3` and `--from=3`, every time it was
-     * given) and the words in `add` placed before any `--`. When an `orStdin` arg was given `-`, the
-     * line ends in `< <name file>`, since the shell kept what it fed in. Build every hint that names a
-     * command to run with it.
+     * The caller's own line as a Next step, with each flag in `remove` dropped along with its value
+     * (`--from 3` and `--from=3`, every time it was given) and the words in `add` placed before any
+     * `--`. When an `orStdin` arg was given `-`, the line ends in `< <name file>`, since the shell
+     * kept what it fed in.
      */
-    commandLine(change?: CommandLineChange): string;
+    rerun(change?: CommandLineChange): Rerun;
 }
 /** A serve Command's `Context`, whose run it may end itself. */
-export interface ServeContext<Ports = unknown, Settings = unknown> extends Context<Ports, Settings> {
+export interface ServeContext<Ports = unknown, Settings = unknown, Declared extends Needs = NoNeeds> extends Context<Ports, Settings, Declared> {
     /**
      * Ends the run with exit 0, printing nothing more, as a stop does; for a Daemon that a newer one
      * replaces. Stop the work before calling it: `ctx.signal` does not abort.
@@ -148,7 +164,14 @@ export interface ServeContext<Ports = unknown, Settings = unknown> extends Conte
  * The slice of `Context` the ports factory receives, which exists before the ports do; a test that
  * keeps the real factory gives it the test's env and fakes.
  */
-export type PortsBase = Pick<Context, "env" | "cwd" | "packageRoot" | "secret" | "envFile" | "spawn" | "spawnDetached" | "files" | "clock" | "signal" | "progress" | "version" | "build" | "self" | "fileError">;
+export interface PortsBase extends PortsBaseOfContext {
+    /**
+     * Reads `name` as `ctx.secret` does, or `undefined` when it is unset: the factory serves every
+     * Command, whatever Secrets it declares. A `.env` it cannot read fails with `PERMISSION_DENIED`.
+     */
+    secret(name: string): Secret | undefined;
+}
+type PortsBaseOfContext = Pick<Context, "env" | "cwd" | "packageRoot" | "envFile" | "spawn" | "spawnDetached" | "files" | "clock" | "signal" | "progress" | "version" | "build" | "self" | "fileError">;
 export interface Project<Settings = unknown> {
     /** The folder holding the Project file. */
     readonly root: string;
@@ -159,3 +182,4 @@ export interface ProjectFile<Settings = unknown> {
     readonly file: string;
     readonly schema: z.ZodType<Settings>;
 }
+export {};

package/dist/define-command.d.ts

@@ -0,0 +1,47 @@
+import type * as z from "zod";
+import { type StandardFlagName } from "./command-line/flags.js";
+import type { Needs } from "./context.js";
+import type { ActCommand, Command, DestructiveCommand, InputSchema, ListCommand, NoInput, ReadCommand, ServeCommand, WriteCommand } from "./define.js";
+import type { ErrorTable, NoErrors } from "./error-table.js";
+import type { RowSchema } from "./list.js";
+type Kebab<Key extends string> = Key extends `${infer Head}${infer Tail}` ? `${Head extends Lowercase<Head> ? Head : `-${Lowercase<Head>}`}${Kebab<Tail>}` : Key;
+type Taken<Schema extends InputSchema> = Extract<Kebab<Extract<keyof Schema["shape"], string>>, StandardFlagName>;
+type Unreserved<Schema extends InputSchema> = [Taken<Schema>] extends [never] ? unknown : {
+    readonly standardFlagDeclared: Taken<Schema>;
+};
+interface WithoutStandardFlags<Args extends InputSchema, Options extends InputSchema> {
+    readonly args?: Unreserved<Args>;
+    readonly options?: Unreserved<Options>;
+}
+type Returns<Schema extends z.ZodType> = z.input<Schema>;
+type Prints<Schema extends z.ZodType> = z.output<Schema>;
+interface WithOutput<Schema extends z.ZodType> {
+    readonly output: Schema;
+}
+interface WithoutOutput {
+    readonly output?: undefined;
+}
+type LiteralSecretNames<Name extends string> = NoInfer<string extends Name ? {
+    readonly secrets?: {
+        readonly "give each Secret's name as a literal, or the object as const": never;
+    };
+} : unknown>;
+/** Declares a Command whose `ctx.ports` is the CLI's `Ports`. */
+export interface DefineCommand<Ports, Settings = unknown, Table extends ErrorTable = NoErrors> {
+    <Row extends RowSchema, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: ListCommand<Args, Options, Row, Ports, Settings, Needs<SecretName, Pick<Table, Code>>> & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): ListCommand<Args, Options, Row, Ports, Settings, Needs<SecretName, Pick<Table, Code>>>;
+    <Schema extends z.ZodType, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: ReadCommand<Args, Options, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema> & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): ReadCommand<Args, Options, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema>;
+    <Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: ReadCommand<Args, Options, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): ReadCommand<Args, Options, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput;
+    <Schema extends z.ZodType, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: ActCommand<Args, Options, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema> & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): ActCommand<Args, Options, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema>;
+    <Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: ActCommand<Args, Options, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): ActCommand<Args, Options, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput;
+    <Schema extends z.ZodType, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: ServeCommand<Args, Options, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema> & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): ServeCommand<Args, Options, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema>;
+    <Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: ServeCommand<Args, Options, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): ServeCommand<Args, Options, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput;
+    <Plan, Schema extends z.ZodType, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: WriteCommand<Args, Options, Plan, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema> & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): WriteCommand<Args, Options, Plan, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema>;
+    <Plan, Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: WriteCommand<Args, Options, Plan, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): WriteCommand<Args, Options, Plan, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput;
+    <Plan, Schema extends z.ZodType, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: DestructiveCommand<Args, Options, Plan, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema> & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): DestructiveCommand<Args, Options, Plan, Returns<Schema>, Ports, Settings, Prints<Schema>, Needs<SecretName, Pick<Table, Code>>> & WithOutput<Schema>;
+    <Plan, Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput, const SecretName extends string = never, Code extends keyof Table & string = never>(command: DestructiveCommand<Args, Options, Plan, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput & WithoutStandardFlags<Args, Options> & LiteralSecretNames<SecretName>): DestructiveCommand<Args, Options, Plan, Data, Ports, Settings, Data, Needs<SecretName, Pick<Table, Code>>> & WithoutOutput;
+}
+/** Throws when the Command's declaration breaks a rule its type cannot express; `label` names it. */
+export declare function checkCommand(command: Command, label: string, table: ErrorTable): void;
+export declare function defineCommandFor<Ports, Settings, Table extends ErrorTable = NoErrors>(): DefineCommand<Ports, Settings, Table>;
+export declare const defineCommand: DefineCommand<unknown>;
+export {};

package/dist/define-command.js

@@ -0,0 +1,25 @@
+import { checkForce, checkNoStandardFlags } from "./command-line/flags.js";
+import { checkArrayArgLast, checkNoBooleanArrayOption, checkStdinFields, } from "./command-line/input.js";
+/** Throws when the Command's declaration breaks a rule its type cannot express; `label` names it. */
+export function checkCommand(command, label, table) {
+    checkNoStandardFlags(command, label);
+    checkForce(command, label);
+    checkArrayArgLast(label, command.args);
+    checkStdinFields(label, command.args, command.options);
+    checkNoBooleanArrayOption(label, command.options);
+    checkErrors(command, label, table);
+}
+function checkErrors(command, label, table) {
+    const unknown = (command.errors ?? []).filter((code) => !Object.hasOwn(table, code));
+    if (unknown.length > 0) {
+        throw new Error(`${label} declares ${unknown.join(", ")} in errors, a code the Error table lacks`);
+    }
+}
+export function defineCommandFor() {
+    return declared;
+}
+function declared(command) {
+    return command;
+}
+export const defineCommand = defineCommandFor();
+//# sourceMappingURL=define-command.js.map

package/dist/define-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-command.js","sourceRoot":"","sources":["../src/define-command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAyB,MAAM,yBAAyB,CAAC;AAClG,OAAO,EACL,iBAAiB,EACjB,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAgXjC,qGAAqG;AACrG,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,KAAa,EAAE,KAAiB;IAC7E,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACrC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC3B,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,yBAAyB,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,WAAW,CAAC,OAAgB,EAAE,KAAa,EAAE,KAAiB;IACrE,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IACrF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,aAAa,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,0CAA0C,CAClF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB;IAK9B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,QAAQ,CAA2B,OAAiB;IAC3D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAA2B,gBAAgB,EAAE,CAAC"}

package/dist/define.d.ts

@@ -1,9 +1,9 @@
 import type * as z from "zod";
-import type { BuildStamp, Context, PortsBase, ProjectFile, ServeContext } from "./context.js";
+import type { SideTaskRun } from "./context/side-task.js";
+import type { Context, Needs, NoNeeds, PortsBase, ProjectFile, ServeContext } from "./context.js";
 import type { ErrorTable } from "./error-table.js";
-import { type StandardFlagName } from "./flags.js";
 import type { Page, PageInput, RowSchema } from "./list.js";
-import type { SideTaskRun } from "./side-task.js";
+import type { NextStep } from "./next-step.js";
 import type { Style } from "./style.js";
 /** Shown in help and help JSON. */
 export interface Example {
@@ -25,19 +25,22 @@ export interface Tool {
     /** The command that installs it, shown when it is missing. */
     readonly install: string;
 }
+/** A key or token a Command needs, read as `ctx.secret` reads it. */
+export interface SecretDeclaration<Name extends string = string> {
+    readonly name: Name;
+    /** Where to obtain the key, such as the page that issues it; shown when it is missing. */
+    readonly get: string;
+}
 /** Bounds a whole run, so a long run stops before the caller's own timeout and can be continued. */
 export interface RunDeadline<In> {
     readonly ms: number;
     /**
-     * The command line that continues the work, given as the hint of the run's `DEADLINE_EXCEEDED`;
-     * `commandLine` is `ctx.commandLine`. Once the deadline passes, every error of the run becomes
-     * `DEADLINE_EXCEEDED`.
+     * The Next step that continues the work, given by the run's `DEADLINE_EXCEEDED`; `rerun` is
+     * `ctx.rerun`. Once the deadline passes, every error of the run becomes `DEADLINE_EXCEEDED`.
      */
-    resume(input: In, commandLine: Context["commandLine"]): string;
+    resume(input: In, rerun: Context["rerun"]): NextStep;
 }
-interface CommandBase<Args extends InputSchema, Options extends InputSchema> {
-    /** The word the Command is listed under in `commands`; it labels the Command in errors and spill files. */
-    readonly name: string;
+interface CommandBase<Args extends InputSchema, Options extends InputSchema, Declared extends Needs> {
     /** One line, shown in help and help JSON. */
     readonly description: string;
     /** A paragraph printed after the options in text help, and carried as `help` in help JSON. */
@@ -56,6 +59,18 @@ interface CommandBase<Args extends InputSchema, Options extends InputSchema> {
      * `TOOL_MISSING` (exit 2), naming each with its `install`, and `doctor` checks each.
      */
     readonly tools?: readonly Tool[];
+    /**
+     * Read after `tools`, before `plan`, `run` or `start`, `--dry-run` included: missing ones fail the
+     * run with `SECRET_MISSING` (exit 2), naming each with its `get` and the CLI's `.env`. `ctx.secret`
+     * reads only these, help JSON lists them, and `doctor` checks each.
+     */
+    readonly secrets?: readonly SecretDeclaration<Declared["secretName"]>[];
+    /**
+     * The codes of the CLI's Error table the Command throws, listed with their class in help JSON;
+     * `ctx.fail` throws only these. A run ending in a table code missing here, an `AggregateError`
+     * leaf included, fails as a bug (exit 70). Runtime codes are never listed.
+     */
+    readonly errors?: readonly (keyof Declared["errors"] & string)[];
     /**
      * Positional operands, in the schema's order; each field's `.describe()` is its help. The last
      * field may be a `z.array(...)`, which takes every remaining operand, and one string field may be
@@ -71,19 +86,35 @@ interface CommandBase<Args extends InputSchema, Options extends InputSchema> {
     /** At `ms`, `ctx.signal` aborts and the run ends with `DEADLINE_EXCEEDED` (exit 75). */
     readonly deadline?: RunDeadline<Input<Args, Options>>;
 }
-interface UnpagedCommand<Args extends InputSchema, Options extends InputSchema> extends CommandBase<Args, Options> {
-    /** The schema of the data the Command prints, published as JSON Schema in help JSON. */
-    readonly output?: z.ZodType;
+/** `Data` is what the Command returns or delivers; `Printed` is what prints, its `output`'s parse of it. */
+interface UnpagedCommand<Args extends InputSchema, Options extends InputSchema, Data, Printed, Declared extends Needs> extends CommandBase<Args, Options, Declared> {
+    /**
+     * The schema of the data the Command prints, published as JSON Schema in help JSON. The
+     * Runtime parses returned and delivered data with it before printing: data it rejects fails the
+     * run as a bug (exit 70), and its defaults and transforms show in what prints.
+     */
+    readonly output?: z.ZodType<Printed, Data>;
     readonly rows?: never;
-}
-export interface ReadCommand<Args extends InputSchema, Options extends InputSchema, Data, Ports = unknown, Settings = unknown> extends UnpagedCommand<Args, Options> {
-    readonly effect: "read";
-    run(input: Input<Args, Options>, ctx: Context<Ports, Settings>): Data | Promise<Data>;
     /**
      * Turns the data into short text; `--json` prints the data itself. `style` colours only when a
-     * person watches a terminal or `FORCE_COLOR` is set.
+     * person watches a terminal or `FORCE_COLOR` is set. Without it, text prints the data as TOON, or
+     * nothing when the data is `undefined`.
      */
-    render(data: Data, style: Style): string;
+    render?(data: Printed, style: Style): string;
+}
+interface UnpagedRunCommand<Args extends InputSchema, Options extends InputSchema, Data, Ports, Settings, Printed, Declared extends Needs> extends UnpagedCommand<Args, Options, Data, Printed, Declared> {
+    run(input: Input<Args, Options>, ctx: Context<Ports, Settings, Declared>): Data | Promise<Data>;
+}
+export interface ReadCommand<Args extends InputSchema, Options extends InputSchema, Data, Ports = unknown, Settings = unknown, Printed = Data, Declared extends Needs = NoNeeds> extends UnpagedRunCommand<Args, Options, Data, Ports, Settings, Printed, Declared> {
+    readonly effect: "read";
+}
+/**
+ * A Command that changes the state of a program already running, such as a page in a browser tab,
+ * which ends with that program: not files or remote services, which are `write`. It runs as a read
+ * Command does, with no Plan and of the Standard flags only `--json`, and running it again may act again.
+ */
+export interface ActCommand<Args extends InputSchema, Options extends InputSchema, Data, Ports = unknown, Settings = unknown, Printed = Data, Declared extends Needs = NoNeeds> extends UnpagedRunCommand<Args, Options, Data, Ports, Settings, Printed, Declared> {
+    readonly effect: "act";
 }
 /**
  * A read Command whose data is a page of rows, from `paginate` or `page`; the Runtime adds `--limit`
@@ -91,29 +122,29 @@ export interface ReadCommand<Args extends InputSchema, Options extends InputSche
  * the command line for the following page, and as text ends it with a line saying how many rows were
  * shown and either that command line or that no pages remain. A page never spills, and `--fields` keeps only the named fields.
  */
-export interface ListCommand<Args extends InputSchema, Options extends InputSchema, Row extends RowSchema, Ports = unknown, Settings = unknown> extends CommandBase<Args, Options> {
+export interface ListCommand<Args extends InputSchema, Options extends InputSchema, Row extends RowSchema, Ports = unknown, Settings = unknown, Declared extends Needs = NoNeeds> extends CommandBase<Args, Options, Declared> {
     readonly effect: "read";
     /** The schema of one row; the page's output schema is derived from it. */
     readonly rows: Row;
     readonly output?: never;
-    run(input: Flatten<OutputOf<Args> & OutputOf<Options> & PageInput>, ctx: Context<Ports, Settings>): Page<z.output<Row>> | Promise<Page<z.output<Row>>>;
-    /** Receives the page; render `page.items`. */
-    render(page: Page<z.output<Row>>, style: Style): string;
+    run(input: Flatten<OutputOf<Args> & OutputOf<Options> & PageInput>, ctx: Context<Ports, Settings, Declared>): Page<z.output<Row>> | Promise<Page<z.output<Row>>>;
+    /** Receives the page; render `page.items`. Without it, text prints `page.items` as TOON. */
+    render?(page: Page<z.output<Row>>, style: Style): string;
 }
 /**
  * A Command that changes something: `plan` has no side effects, `apply` performs the Plan. The
  * Runtime adds `--dry-run`, which prints the Plan and stops; between `plan` and `apply` it checks
  * `outputs`, then `cost`, then `confirm`, each refusal's hint holding the command line plus its flag.
  */
-interface PlannedCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data, Ports, Settings> extends UnpagedCommand<Args, Options> {
-    plan(input: Input<Args, Options>, ctx: Context<Ports, Settings>): Plan | Promise<Plan>;
-    apply(plan: Plan, ctx: Context<Ports, Settings>): Data | Promise<Data>;
-    render(data: Data, style: Style): string;
+interface PlannedCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data, Ports, Settings, Printed, Declared extends Needs> extends UnpagedCommand<Args, Options, Data, Printed, Declared> {
+    plan(input: Input<Args, Options>, ctx: Context<Ports, Settings, Declared>): Plan | Promise<Plan>;
+    apply(plan: Plan, ctx: Context<Ports, Settings, Declared>): Data | Promise<Data>;
     /**
      * `--dry-run --json` prints the Plan itself, or `{ plan, outputs?, cost }` when the Command
-     * declares `outputs` or `cost`; a byte array in it prints as an index-keyed object.
+     * declares `outputs` or `cost`; a byte array in it prints as an index-keyed object. Without it,
+     * text prints `Would run <command line>:` and under it the Plan as TOON, indented two spaces.
      */
-    renderPlan(plan: Plan, style: Style): string;
+    renderPlan?(plan: Plan, style: Style): string;
     /**
      * A sentence stating what the Plan costs, or undefined when it is cheap. Declaring it adds
      * `--yes`; a run whose cost is a sentence and lacks it refuses with `NOT_CONFIRMED` (exit 2), and
@@ -133,10 +164,10 @@ interface PlannedCommand<Args extends InputSchema, Options extends InputSchema,
      */
     readonly force?: string;
 }
-export interface WriteCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data, Ports = unknown, Settings = unknown> extends PlannedCommand<Args, Options, Plan, Data, Ports, Settings> {
+export interface WriteCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data, Ports = unknown, Settings = unknown, Printed = Data, Declared extends Needs = NoNeeds> extends PlannedCommand<Args, Options, Plan, Data, Ports, Settings, Printed, Declared> {
     readonly effect: "write";
 }
-export interface DestructiveCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data, Ports = unknown, Settings = unknown> extends PlannedCommand<Args, Options, Plan, Data, Ports, Settings> {
+export interface DestructiveCommand<Args extends InputSchema, Options extends InputSchema, Plan, Data, Ports = unknown, Settings = unknown, Printed = Data, Declared extends Needs = NoNeeds> extends PlannedCommand<Args, Options, Plan, Data, Ports, Settings, Printed, Declared> {
     readonly effect: "destructive";
     /**
      * The value the caller must repeat as `--confirm`, naming the target the Plan changes; without it
@@ -148,16 +179,20 @@ export interface DestructiveCommand<Args extends InputSchema, Options extends In
  * A Command that keeps running, such as a preview server, until Ctrl-C or SIGTERM stops it or it
  * calls `ctx.end()`, either with exit 0. Of the Standard flags it gets only `--json`.
  */
-export interface ServeCommand<Args extends InputSchema, Options extends InputSchema, Data, Ports = unknown, Settings = unknown> extends UnpagedCommand<Args, Options> {
+export interface ServeCommand<Args extends InputSchema, Options extends InputSchema, Data, Ports = unknown, Settings = unknown, Printed = Data, Declared extends Needs = NoNeeds> extends UnpagedCommand<Args, Options, Data, Printed, Declared> {
     readonly effect: "serve";
     /** Starts the work and returns its data, which prints at once; stop the work on `ctx.signal`. */
-    start(input: Input<Args, Options>, ctx: ServeContext<Ports, Settings>): Data | Promise<Data>;
-    render(data: Data, style: Style): string;
+    start(input: Input<Args, Options>, ctx: ServeContext<Ports, Settings, Declared>): Data | Promise<Data>;
 }
-export type Command<Ports = unknown, Settings = unknown> = ReadCommand<InputSchema, InputSchema, unknown, Ports, Settings> | ListCommand<InputSchema, InputSchema, RowSchema, Ports, Settings> | WriteCommand<InputSchema, InputSchema, unknown, unknown, Ports, Settings> | DestructiveCommand<InputSchema, InputSchema, unknown, unknown, Ports, Settings> | ServeCommand<InputSchema, InputSchema, unknown, Ports, Settings>;
+export type Command<Ports = unknown, Settings = unknown> = ReadCommand<InputSchema, InputSchema, unknown, Ports, Settings, unknown, Needs> | ActCommand<InputSchema, InputSchema, unknown, Ports, Settings, unknown, Needs> | ListCommand<InputSchema, InputSchema, RowSchema, Ports, Settings, Needs> | WriteCommand<InputSchema, InputSchema, unknown, unknown, Ports, Settings, unknown, Needs> | DestructiveCommand<InputSchema, InputSchema, unknown, unknown, Ports, Settings, unknown, Needs> | ServeCommand<InputSchema, InputSchema, unknown, Ports, Settings, unknown, Needs>;
 export interface Commands<Ports = unknown, Settings = unknown> {
     readonly [key: string]: Command<Ports, Settings> | Commands<Ports, Settings>;
 }
+export type HubSkillSource = {
+    readonly source: string;
+} | {
+    readonly page: string;
+};
 export interface PackagedSkillSource {
     readonly packaged: string;
     readonly agents?: string;
@@ -167,8 +202,6 @@ interface CliBase<Ports, Settings> {
     readonly version: string;
     /** One line saying what the CLI does, shown under the first line of its help and in help JSON. */
     readonly description: string;
-    /** The commit the build was made from and when, stamped by the bundler; `--version` prints it. */
-    readonly build?: BuildStamp;
     /** Every code the CLI throws; a code missing here exits 70, as a bug. */
     readonly errors?: ErrorTable;
     /** Builds the real ports when a run first reads `ctx.ports`; `runCli`'s `ports` replaces them in a test. */
@@ -179,10 +212,16 @@ interface CliBase<Ports, Settings> {
      * typically the git URL of the Skill Hub its release commits the skill to; without `skill`,
      * `doctor` and `update` give no line that installs it.
      *
+     * `{ page }` is an `https` page of a Skill Hub that gives each user their own install line, such
+     * as an API Skill Hub's page for the skill. `doctor` and `update` then give no line that installs
+     * it: for a missing copy, or one that states no version, they name the page, `doctor` in the
+     * `skill` row's message and `update` as a Notice. A copy older than the CLI still gets
+     * `npx -y skills update <name>`, which reinstalls from the user's own URL.
+     *
      * `{ packaged }` is a Packaged skill: a folder, relative to the package root, holding `SKILL.md`
      * and its files. The Runtime then adds the Built-in `skill install`, which copies that folder to
      * `.claude/skills/<name>` at the package manager's project root (removing files the package no
-     * longer has). With `agents`, it also writes that text verbatim as the CLI's block in the
+     * longer has). With `agents`, it also writes that text verbatim as the CLI's Agents section in the
      * `AGENTS.md` there, between `<!-- BEGIN:<name> -->` and `<!-- END:<name> -->`, and names the
      * `@AGENTS.md` line `CLAUDE.md` lacks. A copy of another `metadata.version` refreshes at once;
      * in a copy at the package's version, a file that differs was edited, and replacing or removing
@@ -193,13 +232,11 @@ interface CliBase<Ports, Settings> {
      * `skill: { copy, copyVersion, packageVersion, home? }`, `home` naming that folder. Every other
      * Command run from an install gives that row's problem as a Notice before the Command runs, or
      * one saying the copy could not be checked when a file is unreadable. With `agents`, the
-     * advisory `agents` row reports a project root `AGENTS.md` without the CLI's block, or with
+     * advisory `agents` row reports a project root `AGENTS.md` without the CLI's Agents section, or with
      * another one (fix: `<run-as> skill install`), and a `CLAUDE.md` without `@AGENTS.md`. Only a CLI with several
      * Commands may declare it: `defineCli` throws otherwise.
      */
-    readonly skill?: {
-        readonly source: string;
-    } | PackagedSkillSource;
+    readonly skill?: HubSkillSource | PackagedSkillSource;
     /**
      * Work that runs beside every Command run, such as a usage count; return `undefined` to decline.
      * It starts once the input is parsed, before `plan`, `run` or `start`, so it also runs for a run a
@@ -268,6 +305,8 @@ export interface CommandTreeCli<Ports = unknown, Settings = unknown> extends Cli
     readonly doctor?: readonly DoctorCheck<Ports, Settings>[];
     /** Tools `doctor` checks besides the Commands' own; no Command requires them. */
     readonly tools?: readonly Tool[];
+    /** Secrets `doctor` checks besides the Commands' own; no Command requires them. */
+    readonly secrets?: readonly SecretDeclaration[];
 }
 /** An Agent CLI that is one Command, run with no Command name, as in `tool <args>`. */
 export interface SingleCommandCli<Ports = unknown, Settings = unknown> extends CliBase<Ports, Settings> {
@@ -275,24 +314,5 @@ export interface SingleCommandCli<Ports = unknown, Settings = unknown> extends C
     readonly commands?: never;
 }
 export type Cli<Ports = unknown, Settings = unknown> = CommandTreeCli<Ports, Settings> | SingleCommandCli<Ports, Settings>;
-type Kebab<Key extends string> = Key extends `${infer Head}${infer Tail}` ? `${Head extends Lowercase<Head> ? Head : `-${Lowercase<Head>}`}${Kebab<Tail>}` : Key;
-type Taken<Schema extends InputSchema> = Extract<Kebab<Extract<keyof Schema["shape"], string>>, StandardFlagName>;
-type Unreserved<Schema extends InputSchema> = [Taken<Schema>] extends [never] ? unknown : {
-    readonly standardFlagDeclared: Taken<Schema>;
-};
-interface WithoutStandardFlags<Args extends InputSchema, Options extends InputSchema> {
-    readonly args?: Unreserved<Args>;
-    readonly options?: Unreserved<Options>;
-}
-/** Declares a Command whose `ctx.ports` is the CLI's `Ports`. */
-export interface DefineCommand<Ports, Settings = unknown> {
-    <Row extends RowSchema, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: ListCommand<Args, Options, Row, Ports, Settings> & WithoutStandardFlags<Args, Options>): ListCommand<Args, Options, Row, Ports, Settings>;
-    <Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: ReadCommand<Args, Options, Data, Ports, Settings> & WithoutStandardFlags<Args, Options>): ReadCommand<Args, Options, Data, Ports, Settings>;
-    <Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: ServeCommand<Args, Options, Data, Ports, Settings> & WithoutStandardFlags<Args, Options>): ServeCommand<Args, Options, Data, Ports, Settings>;
-    <Plan, Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: WriteCommand<Args, Options, Plan, Data, Ports, Settings> & WithoutStandardFlags<Args, Options>): WriteCommand<Args, Options, Plan, Data, Ports, Settings>;
-    <Plan, Data, Args extends InputSchema = NoInput, Options extends InputSchema = NoInput>(command: DestructiveCommand<Args, Options, Plan, Data, Ports, Settings> & WithoutStandardFlags<Args, Options>): DestructiveCommand<Args, Options, Plan, Data, Ports, Settings>;
-}
-export declare function defineCommandFor<Ports, Settings>(): DefineCommand<Ports, Settings>;
-export declare const defineCommand: DefineCommand<unknown>;
 export declare function isCommand(node: Command | Commands): node is Command;
 export {};

package/dist/define.js

@@ -1,17 +1,3 @@
-import { checkForce, checkNoStandardFlags } from "./flags.js";
-import { checkArrayArgLast, checkNoBooleanArrayOption, checkStdinFields } from "./input.js";
-function checkedCommand(command) {
-    checkNoStandardFlags(command);
-    checkForce(command);
-    checkArrayArgLast(command.name, command.args);
-    checkStdinFields(command.name, command.args, command.options);
-    checkNoBooleanArrayOption(command.name, command.options);
-    return command;
-}
-export function defineCommandFor() {
-    return checkedCommand;
-}
-export const defineCommand = defineCommandFor();
 // A group's values are always objects, so a string `effect` can only belong to a Command.
 export function isCommand(node) {
     return typeof node.effect === "string";

package/dist/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAyB,MAAM,YAAY,CAAC;AACrF,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA4Y5F,SAAS,cAAc,CAA2B,OAAiB;IACjE,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,UAAU,CAAC,OAAO,CAAC,CAAC;IACpB,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,gBAAgB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,yBAAyB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAA2B,gBAAgB,EAAE,CAAC;AAExE,0FAA0F;AAC1F,MAAM,UAAU,SAAS,CAAC,IAAwB;IAChD,OAAO,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC;AACzC,CAAC"}
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAmbA,0FAA0F;AAC1F,MAAM,UAAU,SAAS,CAAC,IAAwB;IAChD,OAAO,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC;AACzC,CAAC"}