halfcycle 0.4.13 → 0.4.15

package/dist/change.d.ts

@@ -0,0 +1,136 @@
+/**
+ * `npx halfcycle@latest change` — sorting a change, moving it up, and ending a small
+ * change (Safe, lean, fast · E3, feature `three-paths` AC2–AC4, AC6's writer, AC8's
+ * missing route; `mini-phase` *The CLI*).
+ *
+ * THREE FORMS, required flags declared once in `cli-contract.ts` (`missingRequirements`
+ * enforces them, and the remedy-string seam test reads the same table):
+ * - `change sort --request "<line>" --touches <path>… [--contract <from>:<to>]…
+ *   [--stored-data] [--standing-rule] [--new-part]` checks `docs/system.json` exactly as
+ *   `system` does (`checkAndReportDescription`, the one path), reads HEAD as the start
+ *   commit (a project with no commit cannot sort), sends the description, then the
+ *   sort, and prints control's answer: its sentence, the sorting's id, what to say next.
+ *   The path is never worked out here: control re-runs the one rule (`sortChange`) and
+ *   records its own answer. The request is checked locally with the contracts' own
+ *   `checkChangeSortRequest` first, so a request control would refuse costs no request.
+ * - `change up <mini|full> --change <id>` moves an unfinished small change up and, the
+ *   change now being finished, writes its record pair; `--phase <phase>` moves a mini
+ *   phase up instead. A move down is refused here with the contracts' own sentence,
+ *   before anything is sent; control refuses it again, as it refuses every move down.
+ * - `change done <id>` reads the record FIRST. A record found means the change has
+ *   ended: the pair is written, the outcome printed, and nothing else happens — no
+ *   runner is started, no report is sent. Only when the service says the change has
+ *   not ended does it start the runner's `observe --change <id>`, which reads the
+ *   basis, counts or finishes by the work standing, and prints one line this module
+ *   parses with `observeChangeRunResultSchema` (one home, shared with the runner).
+ *
+ * THE RECORD'S FILENAME COMES FROM THE `<id>` ARGUMENT, checked as a change id here and
+ * again by the writer, never from a field of the record (INV-023).
+ *
+ * A SMALL CHANGE IS NOT A PHASE (INV-024): no line here asks for, mentions or marks an
+ * approval. Every sentence about a path is the contracts' `CHANGE_PATH_WORDS` or
+ * control's own answer; none is restated here (INV-003). Nothing a step id; the next
+ * thing to say is the phrase control's answer carries (INV-016).
+ *
+ * TOPOLOGY. Every route here takes the project credential alone: no GitHub
+ * installation, no open phase, no portal session (INV-022). A service without a route
+ * is told apart by `isMissingRoute`, and the CLI says so and exits 1.
+ *
+ * INV-001: Node builtins, the global `fetch`, `@halfcycle/events` and `@halfcycle/core`
+ * only; the runner is spawned, never imported. SHIPS TO CLIENT DISK inside the CLI: no
+ * comment sits beside an object member, and every string is a sentence a person reads.
+ */
+import { type ChangeContract, type ObserveChangeRunResult, type SmallChangeRecord } from '@halfcycle/events';
+import { type HeadCommitOutcome } from './close-phase.js';
+import type { RepoCredential } from './open-phase.js';
+import { type SystemDeps, type SystemRun } from './system-report.js';
+import { type ChangeRecordPairResult } from './build-record/write-change.js';
+/** The verb's usage, one home: printed by `--help` and by a usage error. */
+export declare const CHANGE_USAGE: string;
+/** What one invocation asks for, once its words have been read. */
+export type ChangeArgs = {
+    readonly form: 'sort';
+    readonly request: string;
+    readonly touches: readonly string[];
+    readonly contracts: readonly ChangeContract[];
+    readonly storedData: boolean;
+    readonly standingRule: boolean;
+    readonly newPart: boolean;
+    readonly repoRoot?: string;
+} | {
+    readonly form: 'up';
+    readonly to: 'mini' | 'full';
+    readonly target: {
+        readonly kind: 'change';
+        readonly sortingId: string;
+    } | {
+        readonly kind: 'phase';
+        readonly phase: string;
+    };
+    readonly repoRoot?: string;
+} | {
+    readonly form: 'done';
+    readonly sortingId: string;
+    readonly repoRoot?: string;
+};
+/** The words read, or the line to print and the code to exit with. Nothing was sent. */
+export type ParsedChange = {
+    ok: true;
+    args: ChangeArgs;
+} | {
+    ok: false;
+    line: string;
+    exitCode: 1 | 2;
+};
+/**
+ * Read `rest` (the words after `change`). The required flags are the contract's
+ * (`missingRequirements`), refused first with the contract's own sentence; then each
+ * form's own words are read, and anything else is a usage error. Nothing is read from
+ * disk and nothing is sent.
+ */
+export declare function parseChangeArgs(rest: readonly string[]): ParsedChange;
+/** The pieces the verb reaches outside itself through; replaced in tests. */
+export interface ChangeDeps extends SystemDeps {
+    readonly readHead: (repoRoot: string) => HeadCommitOutcome;
+    readonly fetch: typeof fetch;
+    readonly observeChange: (credential: RepoCredential, repoRoot: string, sortingId: string) => Promise<ObserveChangeRunResult>;
+    readonly writePair: (repoRoot: string, sortingId: string, rawRecord: unknown, record: SmallChangeRecord) => ChangeRecordPairResult;
+}
+/**
+ * The one line the `observe --change` child printed, read through the shared
+ * `observeChangeRunResultSchema`, or `unreachable` when stdout holds no such line.
+ */
+export declare function readObserveChangeLine(stdout: string): ObserveChangeRunResult;
+/**
+ * End a small change through the runner's `observe --change <id>`, spawned the way the
+ * close step spawns the runner's verbs (`runRunnerChild`), with the same credential.
+ * The id is the checked argument. Never throws.
+ */
+export declare function runObserveChangeChild(binary: string | Error, credential: RepoCredential, repoRoot: string, sortingId: string): Promise<ObserveChangeRunResult>;
+/** The line naming what to say next: the phrase the service's answer carries. */
+export declare function nextSayLine(say: string): string;
+/** The command that ends a small change, or writes its record again: the one remedy. */
+export declare function changeDoneCommand(sortingId: string): string;
+/** What a finished change's record says about how it ended, in the contracts' words. */
+export declare function recordOutcomeLines(record: SmallChangeRecord): string;
+/**
+ * `change sort`. The local check runs with the description that just passed and the
+ * HEAD just read; the description version is not known until the service answers, so
+ * the local check is given the lowest version there is, which no rule reads beyond its
+ * shape. The request that leaves carries the version the service gave.
+ */
+export declare function runChangeSort(repoRoot: string, args: Extract<ChangeArgs, {
+    form: 'sort';
+}>, deps: ChangeDeps): Promise<SystemRun>;
+/** `change up`: a small change by its id, or a mini phase by its name. */
+export declare function runChangeUp(repoRoot: string, args: Extract<ChangeArgs, {
+    form: 'up';
+}>, deps: ChangeDeps): Promise<SystemRun>;
+/**
+ * `change done <id>`. The record is read first; the runner is started only when the
+ * service says the change has not ended (three-paths AC4).
+ */
+export declare function runChangeDone(repoRoot: string, sortingId: string, deps: ChangeDeps): Promise<SystemRun>;
+/** The whole verb, once its words are read: the form's run. */
+export declare function runChange(repoRoot: string, args: ChangeArgs, deps: ChangeDeps): Promise<SystemRun>;
+//# sourceMappingURL=change.d.ts.map

package/dist/change.d.ts.map

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

package/dist/check-tasks.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `npx halfcycle@latest check-tasks <phase> [--with-task-list] [--repo <root>]`
+ * (`collision-free-parallel-work` AC3; `checks-as-work-lands` AC3, AC6).
+ *
+ * OFFLINE, ALWAYS. This verb reads at most two files on the person's own machine —
+ * `docs/build-records/task-plan.json` and, with `--with-task-list`,
+ * `docs/build-records/build-tasks.json` — and nothing else. It opens no credential
+ * file, makes no network call, and needs no sign-in. Everything it prints comes from
+ * `checkTaskPlan` (`@halfcycle/core`), which is pure: this module's whole job is
+ * reading the two files, handing them to that function, and printing what it
+ * returns.
+ *
+ * ONE HOME FOR THE PLAN'S SHAPE AND ITS RULES (INV-003): `taskPlanSchema`,
+ * `taskListFileSchema`, `checkTaskPlan` and every line it prints live in
+ * `@halfcycle/core`'s `task-plan.ts`. This file restates none of them — it only
+ * turns a missing or unparsable file into the one kind of answer this verb gives for
+ * that (exit 2, naming the file), and turns the function's lines into the exit code
+ * the spec pins (0 clean, 1 any refusal).
+ *
+ * THE TASK LIST IS READ ONLY WHEN ASKED. Without `--with-task-list` this verb never
+ * opens `build-tasks.json`, so a stale or disagreeing list on disk from an earlier
+ * phase changes nothing about a planning run — the one case
+ * `collision-free-parallel-work`'s *Decisions taken* exists to prevent.
+ *
+ * A MISSING TASK LIST IS NOT AN ERROR. Only the plan file is required input; a task
+ * list that is missing, names another phase, or carries no phase at all (the shape
+ * written before this release) reads as `checkTaskPlan`'s note N1 and exits 0 on an
+ * otherwise clean plan. A plan file in the same state is always a hard failure (exit
+ * 2), because the plan is this verb's one required input.
+ *
+ * SHIPS TO CLIENT DISK inside the CLI (INV-001: Node builtins, `@halfcycle/core`
+ * only — no network, so no `@halfcycle/events` and no `fetch`). Every string here is
+ * a sentence a person reads in their own terminal, so none names an internal
+ * register, a route, or this project's own tooling; no comment sits beside an
+ * object member.
+ */
+/** The usage line, printed for no phase, an extra argument or an unknown flag. */
+export declare const CHECK_TASKS_USAGE = "npx halfcycle@latest check-tasks <phase> [--with-task-list] [--repo <root>]";
+/**
+ * What the arguments after `check-tasks` came to. Exactly one positional (the
+ * phase), at most one `--with-task-list` and at most one `--repo <root>`; anything
+ * else, no phase included, is usage.
+ */
+export type CheckTasksArgs = {
+    ok: true;
+    phase: string;
+    withTaskList: boolean;
+    repoRoot: string | undefined;
+} | {
+    ok: false;
+};
+export declare function parseCheckTasksArgs(argv: readonly string[]): CheckTasksArgs;
+/** What a run of the verb came to. */
+export interface CheckTasksRun {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/**
+ * The whole verb. Reads `docs/build-records/task-plan.json` under `repoRoot`, and,
+ * with `withTaskList`, `docs/build-records/build-tasks.json`; hands both to
+ * `checkTaskPlan` and prints its lines, one per line, in the order it returns them,
+ * or `checkTaskPlan`'s own clear line when there is nothing to report. Never throws.
+ *
+ * Exit 0 when nothing refuses, 1 when anything does, 2 when the plan file is
+ * missing or either file cannot be read or parsed as JSON or does not match the
+ * shape this tool reads (naming which file, and where). A missing task list is not
+ * an error (see the module header) and never changes the exit code on its own.
+ */
+export declare function runCheckTasks(repoRoot: string, phase: string, withTaskList: boolean): CheckTasksRun;
+//# sourceMappingURL=check-tasks.d.ts.map

package/dist/check-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-tasks.d.ts","sourceRoot":"","sources":["../src/check-tasks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAgBH,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,gFAAgF,CAAC;AAE/G;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAChF;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAElB,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAuB3E;AA2CD,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,aAAa,CA4BnG"}

package/dist/claude-plan.d.ts

@@ -0,0 +1,133 @@
+/**
+ * SETUP ASKS THE CLAUDE PLAN ONCE (`builds-paced-to-plan` AC2, setup half).
+ *
+ * `bin.ts`'s setup arm calls `setupClaudePlan` after the project is created or found.
+ * In order:
+ *
+ *   1. NOBODY IS ASKED, AND NOTHING IS SENT, unless this account owns the project
+ *      and a person is there (`isInteractiveRun`: a terminal on standard input and no
+ *      `CI`). That one gate covers a script, CI, an agent running `npx halfcycle` from
+ *      its own shell (no terminal on standard input) and a guest. A remembered answer
+ *      is not sent either: the spec's "a setup with no person there sends nothing".
+ *   2. A COMPUTER THAT WAS TOLD BEFORE is not asked again: the remembered plan is
+ *      sent, and, once control has taken it, the remembered line says so. THIS STEP
+ *      IS NOT GATED ON `--yes` (below) — a bounded network call with a timeout cannot
+ *      wait forever on anybody, so there is nothing for `--yes` to protect against
+ *      here, and a `--yes` run genuinely at a real terminal still wants its
+ *      already-known plan kept in sync silently.
+ *   3. OTHERWISE THE QUESTION IS ASKED (`askLine`) — UNLESS `--yes` WAS GIVEN, in
+ *      which case this step is skipped the same way "no person there" is (W-09 O-W9:
+ *      a console can be attached with nobody at it — a Windows run started with no
+ *      interactive session still measured a TTY — so `--yes` is read here the same
+ *      way `confirmActingIdentity` already reads it, before the TTY is trusted, as
+ *      the stronger, explicit signal that nobody is going to answer). Otherwise: the
+ *      answer is remembered on this computer and sent. An answer that names no plan
+ *      is asked again, up to `PLAN_QUESTION_TRIES` times in all; after that nothing is
+ *      remembered or sent, and the plan stays unknown until the owner sets it in the
+ *      console.
+ *
+ * ONE HOME FOR EVERY WORD AND SHAPE, AND IT IS NOT HERE. The question, the answer's
+ * reading, the remembered line, the seven plans and the request body are
+ * `@halfcycle/events`' `pacing.ts`; the remembered file's shape IS the request body
+ * (`claudePlanRequestSchema`), so the file and the wire cannot drift apart. This
+ * module holds only the order above and the file and network I/O.
+ *
+ * THE CREDENTIAL IS THE MACHINE'S ACCOUNT CREDENTIAL, read the way the create route's
+ * is (`HALFCYCLE_TOKEN` in the environment first, else this machine's saved sign-in),
+ * and never a browser sign-in: the project is already set up, and a sign-in for a
+ * question about pacing would be out of all proportion. The engagement credential is
+ * never sent; control refuses it on this route. With no account credential the answer
+ * is still remembered, so the next setup sends it.
+ *
+ * BEST EFFORT, NEVER A FAILURE. The install has already succeeded when this runs. A
+ * network error, a timeout, a refusal (control not yet carrying the route, or a
+ * project this account does not own after all) or a file that cannot be written is
+ * silent: the remembered answer is re-sent by the next setup, and the owner can set
+ * the plan in the console. Nothing here throws.
+ *
+ * A REMEMBERED ANSWER IS RE-SENT ON EVERY LATER SETUP, as the spec says, so a plan the
+ * owner changed in the console is set back by their next `npx halfcycle` on this
+ * computer. That is the spec's rule, written down here so it is not mistaken for a
+ * defect of this module.
+ *
+ * INV-001: Node builtins, `@halfcycle/core`, `@halfcycle/events` and this package's
+ * own modules. Nothing about usage crosses (ADR-015): only the plan's id.
+ */
+import { type ClaudePlanId } from '@halfcycle/events';
+/** The remembered answer's file name, under `~/.halfcycle/`. Machine-level, never in a project (INV-016). */
+export declare const CLAUDE_PLAN_FILENAME = "claude-plan.json";
+/** How many times the question is put before an answer that names no plan is given up on. */
+export declare const PLAN_QUESTION_TRIES = 3;
+/** `~/.halfcycle/claude-plan.json`. */
+export declare function claudePlanPath(home?: string): string;
+/**
+ * The plan this computer was told before, or `undefined` when it was never told or
+ * the file does not read as one: a file that does not parse is asked about again and
+ * overwritten, never an error.
+ */
+export declare function readRememberedClaudePlan(home?: string): ClaudePlanId | undefined;
+/**
+ * Remember the plan on this computer, owner-only, the account store's posture
+ * (`account-credential.ts`). Returns false when it could not be written.
+ */
+export declare function rememberClaudePlan(plan: ClaudePlanId, home?: string): boolean;
+/**
+ * The owner's settings page, under the project's console address, or `undefined` when
+ * this run has no console address (an older control, or none configured). No address
+ * is guessed: `bin.ts` passes the same address it prints as the project's console.
+ */
+export declare function settingsPageUrl(consoleUrl: string | undefined): string | undefined;
+/**
+ * Send the plan to `PUT /engagements/:engagementId/claude-plan` with the account
+ * credential. True only when control took it (a 2xx). Never throws.
+ */
+export declare function sendClaudePlan(serviceUrl: string, engagementId: string, credential: string, plan: ClaudePlanId, fetchImpl?: typeof fetch): Promise<boolean>;
+/** What `setupClaudePlan` did, for the caller's tests; `bin.ts` reads none of it. */
+export type ClaudePlanSetupOutcome = {
+    readonly kind: 'not-owner';
+} | {
+    readonly kind: 'no-person';
+} | {
+    readonly kind: 'no-answer';
+} | {
+    readonly kind: 'failed';
+} | {
+    readonly kind: 'remembered';
+    readonly plan: ClaudePlanId;
+    readonly sent: boolean;
+} | {
+    readonly kind: 'answered';
+    readonly plan: ClaudePlanId;
+    readonly sent: boolean;
+};
+export interface ClaudePlanSetupInput {
+    readonly serviceUrl: string;
+    readonly engagementId: string;
+    /** True when this run's account owns the project; false for a guest, or when ownership is not known. */
+    readonly ownsProject: boolean;
+    /** The project's console address this run prints, if any; the settings page is under it. */
+    readonly consoleUrl: string | undefined;
+}
+export interface ClaudePlanSetupDeps {
+    readonly interactive: () => boolean;
+    readonly ask: (question: string) => Promise<string>;
+    readonly write: (text: string) => void;
+    /**
+     * `--yes` on the command line: never ask the question, the same as `interactive()`
+     * false for THAT ONE STEP (W-09 O-W9 — a measured TTY is not proof somebody is there
+     * to answer it). Does NOT also suppress resending an already-remembered plan — that
+     * step is a bounded network call, never a wait on a human, so `--yes` has nothing to
+     * protect there and a real terminal that happens to pass `--yes` still wants its
+     * known plan kept in sync.
+     */
+    readonly assumeYes?: boolean;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly home?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * The setup arm's one call: ask the plan once, remember it, send it (module
+ * docblock). Never throws; the outcome is for tests.
+ */
+export declare function setupClaudePlan(input: ClaudePlanSetupInput, deps: ClaudePlanSetupDeps): Promise<ClaudePlanSetupOutcome>;
+//# sourceMappingURL=claude-plan.d.ts.map

package/dist/claude-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-plan.d.ts","sourceRoot":"","sources":["../src/claude-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAKH,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAG3B,6GAA6G;AAC7G,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AAEvD,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAQrC,uCAAuC;AACvC,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAOhF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAU7E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGlF;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,YAAY,EAClB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,OAAO,CAAC,CAiBlB;AAED,qFAAqF;AACrF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACpF;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEvF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wGAAwG;IACxG,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AASD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,sBAAsB,CAAC,CAqCjC"}

package/dist/cli-contract.d.ts

@@ -62,7 +62,7 @@
  * home is the failure mode it exists to prevent.
  */
 /** The verbs the CLI dispatches. Anything else after `halfcycle ` is unknown. */
-export declare const CLI_VERBS: readonly ["install", "check-drift", "build-record", "open-phase", "close-phase", "system", "draw", "plan", "review", "uninstall"];
+export declare const CLI_VERBS: readonly ["install", "check-drift", "build-record", "open-phase", "close-phase", "system", "draw", "plan", "review", "check-tasks", "uninstall", "change", "pace", "prove", "preview", "doctor", "restore"];
 export type CliVerb = (typeof CLI_VERBS)[number];
 /** A flag every invocation of the verb must carry. */
 export interface RequiredFlag {
@@ -85,10 +85,21 @@ export interface ConditionalFlag {
     readonly takesValue: boolean;
     readonly missingMessage: string;
 }
+/**
+ * One form of a verb that has several, chosen by the first word after the verb
+ * (`change sort`, `change up`, `change done`). Each form declares its own required
+ * flags; the verb's own lists stay empty.
+ */
+export interface FormContract {
+    readonly form: string;
+    readonly required: readonly RequiredFlag[];
+    readonly conditional: readonly ConditionalFlag[];
+}
 export interface VerbContract {
     readonly verb: CliVerb;
     readonly required: readonly RequiredFlag[];
     readonly conditional: readonly ConditionalFlag[];
+    readonly forms?: readonly FormContract[];
 }
 /** The contract for a verb, or `undefined` when the CLI has no such verb. */
 export declare function contractFor(verb: string): VerbContract | undefined;

package/dist/cli-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-contract.d.ts","sourceRoot":"","sources":["../src/cli-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAIH,iFAAiF;AACjF,eAAO,MAAM,SAAS,mIAAoI,CAAC;AAE3J,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;CAClD;AAiFD,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAElE;AAED,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,CAyBxF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMvE;AASD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;CAErB,CAAC;AAyBX;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAa1F"}
+{"version":3,"file":"cli-contract.d.ts","sourceRoot":"","sources":["../src/cli-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAIH,iFAAiF;AACjF,eAAO,MAAM,SAAS,6MAA8M,CAAC;AAErO,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;CAClD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;AAwID,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAElE;AAED,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,CAyBxF;AAuBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMvE;AASD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;CAErB,CAAC;AA0BX;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAa1F"}