halfcycle 0.4.13 → 0.4.14

package/dist/claude-plan.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ *   3. OTHERWISE the question is asked (`askLine`), the answer 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;
+    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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;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,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,CA+BjC"}

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"];
 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,6KAA8K,CAAC;AAErM,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;AAqID,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"}