@webappwiz/cli 0.0.7 → 0.0.8

package/{index-6km6e845.js → index-rz4spnkb.js}

@@ -1,8 +1,8 @@
 import {
   table
-} from "./index-jbrs6gqt.js";
+} from "./index-4xj59vmx.js";
 // package.json
-var version = "0.0.7";
+var version = "0.0.8";
 
 // skills/add.ts
 import { ConsoleLogger } from "webappwiz/log";
@@ -15,7 +15,7 @@ import { dirname } from "node:path";
 var arbor_skill_default = `---
 name: arbor
 description: Use the @webappwiz/arbor CLI to land your work on trunk, or a base branch given as an argument, from an isolated git worktree without pull requests. Read this before making any code change in an arbor repository, since it decides where the work happens, and whenever you need to add, claim, merge, remove, list, show, locate, or escalate a task.
-version: 0.0.7
+version: 0.0.8
 ---
 
 # Using arbor
@@ -41,28 +41,35 @@ its changed files:
 \`git -C "$(arbor path <task>)" diff --name-only main...task/<task>\`
 (\`arbor show <task>\` for its plan; neither takes its lease).
 
-If nothing overlaps, carry on. If something does, do not pick a side
-yourself: \`arbor add\` your task if you have not already, record the overlap
-in \`ARBOR.md\` (which task, which files), then \`arbor escalate\` and ask the
-user whether to wait for the other task, work alongside it and accept the
-rebase, or drop yours. If they choose to wait, re-check periodically. A
-status is only true for the moment you read it,
-so re-run \`arbor ls\` every time you are about to repeat one. Act on what it
-becomes:
-
-- gone from \`arbor ls\`: it landed. Redo the overlap check (trunk moved) and
-  carry on.
+If nothing overlaps, carry on. If something does, \`arbor add\` your task if you
+have not already and record the overlap in \`ARBOR.md\` (which task, which
+files). Some overlap is normal: work alongside and accept the rebase. Only
+when the overlap is significant and you expect merge conflicts that would be
+hard to resolve, \`arbor wait <task>\` on the task you overlap with instead:
+let it land first and your rebase is onto its work rather than against it.
+
+Waiting is caution, reserved for overlap that warrants it. Escalate
+instead only when the other task is doing something majorly different from
+yours, or contrary to it: rewriting what you are extending, or asked for the
+opposite of what you were. Then \`arbor escalate\` and ask the user whether to
+wait for it, work alongside it and accept the rebase, or drop yours.
+
+Act on how the wait ends:
+
+- \`removed\`: it landed or was dropped. Redo the overlap check (trunk moved)
+  and carry on.
 - \`escalated\`: your work is blocked on a person too. Tell the human what it
   is blocked on and wait.
-- \`orphaned\`, \`stray\`, \`unrecorded\` or \`unknown\` with nobody driving it: that
-  tree is broken. Say so and ask. (A tree mid-merge can read as \`orphaned\`
-  for a moment, so trust a broken status only if it survives a second look.)
-- still \`working\` or \`merging\` after however long the human would tolerate
-  hearing nothing: offer the choice of waiting longer, working alongside, or
-  picking up something else, and say what you have not started.
+- \`orphaned\`, \`stray\`, \`unrecorded\` or \`unknown\`: that tree is broken. A tree
+  mid-merge can read as \`orphaned\` for a moment, so \`wait\` once more before
+  believing it, then say so and ask.
+- exit 14 \`timeout\`, still \`working\` or \`merging\`: \`wait\` again (with
+  \`--timeout-secs\` if the task looks close), or offer the choice of
+  working alongside it or picking up something else, saying what you have not
+  started.
 
 A \`stale\` lease on a \`working\` task is normal (arbor only heartbeats while a
-command runs): when waiting, watch a task's status, never its lease.
+command runs): watch a task's status, never its lease.
 
 ## Workflow
 
@@ -126,16 +133,38 @@ Anything else worth saying goes after this block, not instead of it.
 ## ARBOR.md
 
 Your session can die at any moment; \`ARBOR.md\` is what lets a stranger
-\`arbor claim\` the task and continue. Fill in \`## Goal\` (one or two lines on
-what done means), list the file paths you plan to touch under \`## Files\`,
-and list every step you can foresee under \`## Next\` as \`- [ ]\` items,
-roughly one commit each. Move items to \`## Done\` as you finish them: those
-checkboxes are the only progress the task reports. Decisions, dead ends and
-how to verify go under \`## Notes\`. Keep the whole file current throughout
-implementation, not at the end: after each step lands, check it off, and
-when the set of files you are touching changes, change \`## Files\` to match.
-A stale plan is worse than none, and a session that dies mid-task reports
-nothing.
+\`arbor claim\` the task and continue. Fill in the stub \`add\` wrote to this
+shape:
+
+\`\`\`\`markdown
+# <task>
+
+## Goal
+
+One or two lines on what done means.
+
+## Files
+
+- every/path/you/plan/to/touch.ts
+
+## Done
+
+- [x] finished steps move here: these checkboxes are the only progress the
+      task reports
+
+## Next
+
+- [ ] every step you can foresee, roughly one commit each
+
+## Notes
+
+Decisions, dead ends, and how to verify.
+\`\`\`\`
+
+Keep the whole file current throughout implementation, not at the end: after
+each step lands, check it off and move it to \`## Done\`, and when the set of
+files you are touching changes, change \`## Files\` to match. A stale plan is
+worse than none, and a session that dies mid-task reports nothing.
 
 \`arbor show <task>\` prints the file and every way it departs from the
 expected shape; run it on your own task after writing the file. \`add\` excludes
@@ -151,8 +180,70 @@ fewer than 5 commits, and wanting many more means the task wants splitting,
 not squashing.
 `;
 
+// templates/webappwiz.skill.md
+var webappwiz_skill_default = `---
+name: webappwiz
+description: Check whether the webappwiz package already covers a piece of infrastructure before writing it by hand or adding a dependency for it. Read this before writing any of: time, clocks, durations or timers; logging; id generation; HTTP serving; CLI argument parsing; background tasks or queues; web workers; markdown parsing; typed event emitters; 2D geometry or spatial indexes; filesystem, env or process access; typed RPC over fetch; schema validation; AbortSignal plumbing; disposable resources; browser scroll, animation frames or visibility. Also use whenever the user says webappwiz.
+version: 0.0.8
+---
+
+# Using webappwiz
+
+\`webappwiz\` is the parts of a web app that get written again every time, behind
+interfaces a test can replace. One package, one subpath per module. Before
+writing any of that here, find out whether it already exists there.
+
+Its README carries the whole catalogue, a table of every subpath and what it is
+for. Read it from \`node_modules/webappwiz/README.md\`, or, in a project that has
+not installed it yet, from
+\`https://raw.githubusercontent.com/jaredjj3/webappwiz/main/packages/webappwiz/README.md\`.
+
+Nothing in the table is close: say so in a line and write it here. Something is:
+read that module's own README and the exports of its \`index.ts\`, and judge
+against what is actually needed rather than the one-line blurb.
+
+## It fits
+
+\`bun add webappwiz\` and import the subpath. There is no package entry point, so
+import \`webappwiz/time\`, never \`webappwiz\`. Fakes live under \`/testing\` beside
+what they replace.
+
+## It nearly fits
+
+Do not vendor it, fork it, or patch \`node_modules\`. Write what this project
+needs here so nobody is blocked, leave a \`TODO: webappwiz/<subpath> once <gap>\`
+on it, and hand the gap over: print the block below and tell the user to give it
+to an agent working on the webappwiz repo.
+
+\`\`\`markdown
+In \`packages/webappwiz/<subpath>\`: <the gap, in a sentence>.
+
+Wanted by <this project> for <the usecase, concretely>.
+
+What is there now: <the export that comes closest, and where it stops>.
+What is missing: <the smallest change that closes the gap: one more method, a
+widened parameter, another implementation of an interface>.
+Called like: <the call site, written the way the caller wants to write it>.
+\`\`\`
+
+Describe the gap and stop. Do not design the API in the handoff: that repo has a
+style guide and a judge, and neither of them is here.
+
+## It does not fit
+
+One line naming the subpath you read and why it is not the one, then write it
+here. A wrong module taken up is worse than one written twice.
+
+## Rules
+
+- Never edit the webappwiz repository from this project's thread.
+- Never copy its source into this project.
+- Reading the table is the whole check, and it is cheap. Do it before adding a
+  dependency, not after.
+`;
+
 // skills/skill.ts
-var bundled = { arbor: arbor_skill_default };
+var bundled = { arbor: arbor_skill_default, webappwiz: webappwiz_skill_default };
 function versionOf(md) {
   const frontmatter = md.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "";
   return frontmatter.match(/^version:\s*(.+)$/m)?.[1]?.trim() ?? null;

package/index.js

@@ -6,17 +6,18 @@ import {
   update,
   update1 as update2,
   version
-} from "./index-6km6e845.js";
+} from "./index-rz4spnkb.js";
 import {
   JUDGE_RULES,
   SIGNOFF_RULES
-} from "./index-3p0t2exn.js";
-import {
-  Signoff
-} from "./index-3k3rtw49.js";
+} from "./index-hz6bwqfy.js";
 import {
   JudgeCommands
-} from "./index-jbrs6gqt.js";
+} from "./index-r14q0cmx.js";
+import {
+  Signoff
+} from "./index-fh8js68z.js";
+import"./index-4xj59vmx.js";
 
 // index.ts
 import { NodeFs, NodeGlob } from "webappwiz/system";
@@ -52,17 +53,16 @@ webappwiz.command("judge").description("check a directory against the config, on
 }).option("print", t.boolean(), {
   default: false,
   description: "print the prompts and run no agent at all"
-}).option("estimate", t.boolean(), {
-  default: false,
-  description: "print what a run would read, and run nothing"
 }).option("chunk", t.number(), {
   default: 25,
   description: "files per review"
 }).option("since", t.optional(t.string()), {
   description: "only check files added or changed since this git ref"
-}).option("budget", t.number(), {
-  default: 200000,
-  description: "confirm before reading more than this many tokens"
+}).option("concurrency-override", t.optional(t.number()), {
+  description: "agent calls in flight at once, over the config's concurrency"
+}).option("ci", t.boolean(), {
+  default: false,
+  description: "line-by-line output with no live progress block"
 }).action((opts, deps) => judge(deps).judge(opts));
 webappwiz.command("signoff").description("weigh a change against the rules that ask for a person").arg("dir", t.string(), {
   default: ".",
@@ -77,9 +77,6 @@ webappwiz.command("signoff").description("weigh a change against the rules that
 }).option("since", t.string(), {
   default: "main",
   description: "the ref the change is measured against"
-}).option("budget", t.number(), {
-  default: 200000,
-  description: "confirm before reading more than this many tokens"
 }).action((opts, { log, ps, clock }) => new Signoff(SIGNOFF_RULES, JUDGE_RULES.agent, {
   log,
   ps,

package/judge.d.ts

@@ -2,10 +2,7 @@ import { type Rule, type RuleSet } from "@webappwiz/rules";
 import { type Logger } from "webappwiz/log";
 import { type Fs, type Glob, type Ps } from "webappwiz/system";
 import { type Clock } from "webappwiz/time";
-/** Asked before a run spends more than it was allowed to. */
-export interface Confirm {
-    confirm(question: string): boolean | Promise<boolean>;
-}
+import { type Screen } from "./progress.js";
 export interface ShowOptions {
     /** The rule to print, as `rules ls` lists it. */
     id: string;
@@ -17,27 +14,21 @@ export interface JudgeOptions {
     exec?: string;
     /** Print the prompts to the logger and spawn nothing. */
     print?: boolean;
-    /** Print what a run would read and stop. */
-    estimate?: boolean;
     /** Files per review. */
     chunk: number;
     /** Narrows the run to what git says has changed since this ref. */
     since?: string;
-    /** Tokens a run may read before it asks whether you meant it. */
-    budget: number;
+    /** Agent calls in flight at once, over the config's `concurrency`. */
+    "concurrency-override"?: number;
+    /** Line-by-line output with no live block, the way a log wants it. */
+    ci?: boolean;
 }
-/**
- * Answers on the terminal, and answers no without one: a run nobody is watching
- * should stop and say the number rather than block forever waiting to be told
- * to go ahead.
- */
-export declare const ask: Confirm;
 /** What a `JudgeCommands` runs through, and what else it lists. */
 export interface JudgeCommandsOptions {
     /** Rules only a reader applies, listed beside the ones a run checks. */
     signoffRules?: Rule[];
-    /** Who is asked before a run goes over budget; the terminal by default. */
-    confirmer?: Confirm;
+    /** Where live progress draws; this process's terminal by default. */
+    screen?: Screen;
     log?: Logger;
     fs?: Fs;
     ps?: Ps;
@@ -47,7 +38,7 @@ export interface JudgeCommandsOptions {
 export declare class JudgeCommands {
     private rules;
     private signoffRules;
-    private confirmer;
+    private screen;
     private log;
     private fs;
     private ps;
@@ -72,28 +63,9 @@ export declare class JudgeCommands {
      * it spawns nothing and prints the prompts instead, for an agent that would
      * rather hand them to subagents of its own.
      *
-     * `since` narrows the run to what git says has changed, and `budget` caps
-     * what it may read before asking whether you meant it. Under `estimate` it
-     * prints that size and stops, which is the answer to "what would this cost"
-     * without having to guess a budget low enough to be refused.
+     * `since` narrows the run to what git says has changed.
      */
     judge(opts: JudgeOptions): Promise<void>;
-    /**
-     * Measures what one call cost over the files it was handed and leaves that
-     * behind, so the next `--estimate` on this agent has something better than a
-     * floor. Per call rather than per token, because that is how the charge
-     * falls: an agent pays for its own system prompt once per spawn, whatever it
-     * was asked to read, so a figure taken from a two-call run still holds for a
-     * fifteen-call one.
-     *
-     * A run nobody priced records nothing, and a failed write is said aloud
-     * rather than thrown: the agents have already been paid for by this point,
-     * and losing the measurement costs the next estimate accuracy, not the run.
-     */
-    private record;
     /** The agent a command runs with: what it was told, else the config's. */
     private agent;
-    /** The model a run asks, or undefined for an `--exec` command, which is a
-     * model nothing here can name or price. */
-    private model;
 }

package/judge.js

@@ -1,8 +1,7 @@
 import {
-  JudgeCommands,
-  ask
-} from "./index-jbrs6gqt.js";
+  JudgeCommands
+} from "./index-r14q0cmx.js";
+import"./index-4xj59vmx.js";
 export {
-  ask,
   JudgeCommands
 };

package/mode.d.ts

@@ -1,6 +1,6 @@
 /** What a command does with the plan it has made. */
-export type Mode = "print" | "estimate" | "run";
-/** The flags that choose between the three, on top of the two that name an
+export type Mode = "print" | "run";
+/** The flags that choose between the two, on top of the two that name an
  * agent. */
 export interface ModeOptions {
     /** A model to ask. */
@@ -9,15 +9,13 @@ export interface ModeOptions {
     exec?: string;
     /** Print to the logger and spawn nothing. */
     print?: boolean;
-    /** Print what a run would read, and spawn nothing. */
-    estimate?: boolean;
 }
 /**
- * Which of the three a caller asked for, with running the default: a command
+ * Which of the two a caller asked for, with running the default: a command
  * given nothing but a directory is one somebody means to run.
  *
  * Naming two is an error rather than a quiet winner. All of these say what to
  * do with one plan, and letting one silently beat the other would leave a
  * caller unsure which of the two things they asked for they got.
  */
-export declare function mode({ print, estimate, agent, exec }: ModeOptions): Mode;
+export declare function mode({ print, agent, exec }: ModeOptions): Mode;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webappwiz/cli",
-	"version": "0.0.7",
+	"version": "0.0.8",
 	"description": "The webappwiz CLI: judge code against rules, sign off a diff, and manage agent skills",
 	"license": "MIT",
 	"author": "Jared Johnson",
@@ -17,8 +17,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@webappwiz/rules": "^0.0.7",
-		"webappwiz": "^0.0.7"
+		"@webappwiz/rules": "^0.0.8",
+		"webappwiz": "^0.0.8"
 	},
 	"peerDependencies": {
 		"typescript": "^7"

package/progress.d.ts

@@ -0,0 +1,64 @@
+import { type Timer } from "webappwiz/time";
+/**
+ * Where live progress draws. `tty` is whether a line can be redrawn in
+ * place: without one, judge stays line-by-line and never writes here.
+ */
+export interface Screen {
+    tty: boolean;
+    write(text: string): void;
+}
+/** The terminal this process writes to. */
+export declare const terminal: () => Screen;
+/** A run as the status line shows it: how far along, what it is on, what it
+ * has spent, and what it has found. */
+export interface RunView {
+    /** Calls finished. */
+    done: number;
+    /** Calls the run will make in all. */
+    total: number;
+    /** Files the calls out right now are reading. Every review names at least
+     * one, so zero here is the same as nothing running. */
+    files: number;
+    /** Tokens spent so far, when any agent has reported usage. */
+    tokens?: number;
+    /** Violations found so far; said aloud once the first call is home. */
+    problems: number;
+}
+/** The spinner's walk, one step per tick while any call is out. */
+export declare const FRAMES: string[];
+/**
+ * The status line. Pure, so what it says is testable without a terminal:
+ * the `Progress` around it only draws and redraws it. `frame` indexes the
+ * spinner's walk; with nothing running there is nothing to spin.
+ */
+export declare function render(view: RunView, frame?: number): string;
+/** What a `Progress` paces its spinner with; the real one by default. */
+export interface ProgressOptions {
+    timer?: Timer;
+}
+/**
+ * The live line a run draws while agents are out: progress over the calls
+ * and the tokens they have spent, redrawn on every event and spun on a
+ * tick between them. `stop` takes the line down, and whatever prints next
+ * lands where it was.
+ */
+export declare class Progress {
+    private screen;
+    private total;
+    private done;
+    private files;
+    private problems;
+    private tokens;
+    private drawn;
+    private frame;
+    private ticking;
+    constructor(screen: Screen, total: number, opts?: ProgressOptions);
+    /** A call went out over this many files. */
+    started(files: number): void;
+    /** A call came home: the files it read, what it spent, what it found. */
+    finished(files: number, spent?: number, problems?: number): void;
+    /** Takes the line down for good; call it before printing the report. */
+    stop(): void;
+    private erase;
+    private draw;
+}

package/report.d.ts

@@ -1,6 +1,5 @@
 import type { Violation } from "@webappwiz/rules";
 import type { Duration } from "webappwiz/time";
-import { type Overheads } from "./cost.js";
 export declare const count: (total: number, word: string) => string;
 /**
  * Where one printed document stops and the next starts, named so a reader
@@ -11,7 +10,8 @@ export declare const count: (total: number, word: string) => string;
  * the last document wants as much as the others want an opening one.
  */
 export declare const divider: (name?: string) => string;
-export declare const usd: (amount: number) => string;
+/** How every token figure prints: "14K", not "14,000". */
+export declare const compact: Intl.NumberFormat;
 /**
  * What a plan costs to read, at the four-bytes-a-token rule of thumb. Rough on
  * purpose: an estimate that needed a tokenizer, or an API call to count, would
@@ -19,28 +19,10 @@ export declare const usd: (amount: number) => string;
  * decision it informs is only ever "is this the order of magnitude I meant".
  */
 export declare const tokens: (bytes: number) => number;
-/**
- * Why the estimate is a floor: each call pays for the agent's own system
- * prompt and for whatever it re-reads as it works, none of which is knowable
- * from here.
- */
-export declare function overBudget(estimate: number, budget: number, cost?: number): string;
-/**
- * The whole of what `--estimate` prints: the plan, then what it costs on each
- * agent that has a price.
- *
- * Two columns, because the floor alone is misleading. It prices the files a
- * plan can see, and a call also pays for the agent's own system prompt every
- * time, which on a small repo is most of the bill. `overheads` carries what
- * past runs measured that per-call charge to be, so an agent that has been run
- * here gets a second figure worth trusting.
- */
-export declare function estimate(files: number, rules: number, calls: number, tokens: number, overheads: Overheads): string[];
 /**
  * The plan, before the first agent starts. Counts calls rather than reviews
- * because a call is what a run is billed for, and it is the denominator of the
- * `[n/total]` headings below. Without an `agent` it is the whole of what
- * `--estimate` prints, so it names no command it is not going to run.
+ * because a call is what a run spawns, and it is the denominator of the
+ * `[n/total]` headings below.
  */
 export interface Planned {
     files: number;
@@ -50,14 +32,12 @@ export interface Planned {
     estimate: number;
     /** Agent calls in flight at once, which is what the wall clock turns on. */
     concurrency?: number;
-    /** What those calls are predicted to cost, when the agent has a price. */
-    cost?: number;
     /** The command the run will spawn. */
     agent?: string;
 }
-export declare function planned({ files, rules, calls, estimate, concurrency, cost, agent, }: Planned): string[];
+export declare function planned({ files, rules, calls, estimate, concurrency, agent, }: Planned): string[];
 /** A finished review as the report prints it: what the call covered, what it
- * found, and what it cost. */
+ * found, and what it read. */
 export interface Finished {
     /** The ids of the rules the review checked. */
     rules: string[];
@@ -66,8 +46,12 @@ export interface Finished {
     violations: Violation[];
     /** How long this review's agent took. */
     took: Duration;
-    /** Dollars this review's call was billed, when the agent reported a figure. */
-    cost?: number;
+    /** Tokens this review's call touched, when the agent reported usage. */
+    tokens?: number;
+    /** Which worker ran the call, 0-based. */
+    worker: number;
+    /** Tokens that worker has touched so far, this review included. */
+    workerTokens?: number;
     done: number;
     total: number;
 }
@@ -75,11 +59,11 @@ export interface Finished {
  * A finished review, as it should print the moment its agent returns: a status
  * line sizing the call, then one finding per violation.
  */
-export declare function finished({ rules, files, violations, took, cost, done, total, }: Finished): string[];
+export declare function finished({ rules, files, violations, took, tokens, worker, workerTokens, done, total, }: Finished): string[];
 /**
  * One violation: a location a reader can click, what the code does that the
  * rule forbids, and the line it happens on. The heading above names only the
  * glob, so the finding says which of its rules this one breaks.
  */
 export declare function finding(violation: Violation): string[];
-export declare function summary(violations: Violation[], took: Duration, cost?: number): string;
+export declare function summary(violations: Violation[], took: Duration, tokens?: number): string;

package/rules.js

@@ -1,7 +1,7 @@
 import {
   JUDGE_RULES,
   SIGNOFF_RULES
-} from "./index-3p0t2exn.js";
+} from "./index-hz6bwqfy.js";
 export {
   SIGNOFF_RULES,
   JUDGE_RULES

package/signoff.d.ts

@@ -2,7 +2,6 @@ import { type Rule } from "@webappwiz/rules";
 import { type Logger } from "webappwiz/log";
 import { type Ps } from "webappwiz/system";
 import { type Clock } from "webappwiz/time";
-import { type Confirm } from "./judge.js";
 export interface SignoffRunOptions {
     /** The directory whose change is being weighed. */
     dir: string;
@@ -14,8 +13,6 @@ export interface SignoffRunOptions {
     /** The ref the change is measured against: everything since it is the
      * change. */
     since: string;
-    /** Tokens a run may read before it asks whether you meant it. */
-    budget: number;
 }
 /**
  * Weighs a change against the rules that decide whether it can merge on its
@@ -28,8 +25,6 @@ export interface SignoffRunOptions {
  */
 /** What a `Signoff` runs through. */
 export interface SignoffOptions {
-    /** Who is asked before a run goes over budget; the terminal by default. */
-    confirmer?: Confirm;
     log?: Logger;
     ps?: Ps;
     clock?: Clock;
@@ -37,7 +32,6 @@ export interface SignoffOptions {
 export declare class Signoff {
     private rules;
     private defaultAgent;
-    private confirmer;
     private log;
     private ps;
     private clock;

package/signoff.js

@@ -1,7 +1,7 @@
 import {
   Signoff
-} from "./index-3k3rtw49.js";
-import"./index-jbrs6gqt.js";
+} from "./index-fh8js68z.js";
+import"./index-4xj59vmx.js";
 export {
   Signoff
 };