@webappwiz/cli 0.0.7 → 0.0.9

package/README.md

@@ -9,49 +9,24 @@ bunx @webappwiz/cli skills add arbor   # install an agent skill
 bunx @webappwiz/cli skills update      # refresh the ones already installed
 bunx @webappwiz/cli rules ls           # every rule there is
 bunx @webappwiz/cli judge .            # check a directory against them
-bunx @webappwiz/cli signoff            # does this change need a person?
 ```
 
 ## rules
 
 Every rule webappwiz judges itself by is named in [`rules.ts`](./rules.ts), as
-`JUDGE_RULES` and `SIGNOFF_RULES`, off the classes
-[`@webappwiz/rules`](../rules/rules) ships. There is no config file and no
-preset: a rule is in one of those lists or it does not exist.
+`JUDGE_RULES`, off the classes [`@webappwiz/rules`](../rules/rules) ships.
+There is no config file and no preset: a rule is in that list or it does not
+exist.
 
 ```
-ID                  RULE                       SET      LEVEL    FILES
-no-em-dashes        No em dashes               judge    error    **/*.ts
-one-class-per-file  One class per file         judge    error    **/*.ts
-visual-work-tested  Visual work is tested      signoff
+ID                  RULE                 LEVEL    FILES
+no-em-dashes        No em dashes         error    **/*.ts
+one-class-per-file  One class per file   error    **/*.ts
 ```
 
 `rules show <id>` prints one in full: its glob, its level, and the document an
 agent is handed verbatim.
 
-The `SET` column is which of the two lists a rule is in. `judge` rules are what
-`judge` checks files against, file by file. `signoff` rules have no glob and no
-level because they are about a change rather than a file: `signoff` weighs them,
-and what they answer is whether it needs a person rather than where the code is
-wrong.
-
-## signoff
-
-Weighs a change against the signoff rules and exits 1 with a reason when one of
-them wants a person to look before it merges. One agent call over the whole
-diff, since that is what these rules are about.
-
-```bash
-bunx @webappwiz/cli signoff                    # everything since main
-bunx @webappwiz/cli signoff --since HEAD~3     # measured against another ref
-bunx @webappwiz/cli signoff --print            # the rules, to apply yourself
-```
-
-`--print` is the cheapest signoff there is: the agent about to merge reads the
-rules and weighs its own change, spawning nothing. A project points its agent
-instructions at that rather than at a list of rule ids, which goes stale the
-next time a rule is added.
-
 ## judge
 
 Runs the rules over a directory, one agent call per set of rules sharing a set
@@ -59,16 +34,17 @@ of files.
 
 ```bash
 bunx @webappwiz/cli judge . --agent haiku
-bunx @webappwiz/cli judge . --estimate        # what would this read, and cost
 bunx @webappwiz/cli judge . --print           # print the prompts, spawn nothing
 bunx @webappwiz/cli judge . --since main      # only what changed
+bunx @webappwiz/cli judge . --ci              # plain lines, no live block
 ```
 
 Each rule's code half runs first, free, and only what it escalates reaches an
-agent. `--budget` caps what a run may read before it asks whether you meant it;
-`--estimate` answers that without having to guess a budget low enough to be
-refused. `--print`, `--estimate` and running are three things to do with one
-plan, so passing two of them is an error rather than one quietly winning. Code excuses itself from a rule with a `rule-ignore <id>: <reason>`
+agent. On a terminal a run draws a live status line (a bar over the calls,
+how many are out, and the tokens spent so far), then dumps the report in one
+block; `--ci`, or any output that is not a terminal, prints line by line as
+reviews finish instead. `--print` and running are two things to do with one
+plan, so passing both is an error rather than one quietly winning. Code excuses itself from a rule with a `rule-ignore <id>: <reason>`
 comment above the line, or `rule-ignore-file <id>: <reason>` for the file.
 
 ## update
@@ -100,11 +76,15 @@ bunx @webappwiz/cli skills update ./project
 ```
 
 ```
-SKILL  SHIPS  INSTALLED
-arbor  1.4.0  1.3.0
-other  1.4.0  -
+SKILL      SHIPS  INSTALLED
+arbor      1.4.0  1.3.0
+webappwiz  1.4.0  -
 ```
 
+Two ship: `arbor`, which lands an agent's work from its own worktree, and
+`webappwiz`, which sends an agent to the package's catalogue before it writes
+infrastructure by hand.
+
 `add` installs one skill by name. `update` refreshes the ones a project already
 has and never installs a new one: which skills a project uses is its own
 business, and a skill nobody chose should not arrive by way of an update. `ls`

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

@@ -1,8 +1,8 @@
 import {
   table
-} from "./index-jbrs6gqt.js";
+} from "./index-pyjg1rtk.js";
 // package.json
-var version = "0.0.7";
+var version = "0.0.9";
 
 // 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.9
 ---
 
 # 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.9
+---
+
+# 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-3p0t2exn.js → index-htwb54c6.js}

@@ -5,6 +5,7 @@ import {
   CommentsSayWhyNotWhat,
   DevServersFindAPort,
   DocCommentsAddressUsers,
+  ExportLeadsTheFile,
   FakesOverMocks,
   MatchersOverTestLogic,
   NamedOptionsLast,
@@ -16,18 +17,19 @@ import {
   ReactiveOverUseState,
   ResourcesAreDisposable,
   SimpleTestSetup,
-  TestsNotWeakened,
-  VisualWorkTested
+  TestsOwnTheirState
 } from "@webappwiz/rules/catalog";
 var JUDGE_RULES = defineRules({
   rules: [
     new NoEmDashes,
     new OneClassPerFile,
+    new ExportLeadsTheFile,
     new ParametersDeclareFields,
     new ClassesOverFunctionExports,
     new ObjectsOverCallbacks,
     new NamedOptionsLast,
     new SimpleTestSetup,
+    new TestsOwnTheirState,
     new FakesOverMocks,
     new MatchersOverTestLogic,
     new CommentsSayWhyNotWhat,
@@ -38,9 +40,5 @@ var JUDGE_RULES = defineRules({
     new ResourcesAreDisposable
   ]
 });
-var SIGNOFF_RULES = [
-  new TestsNotWeakened,
-  new VisualWorkTested
-];
 
-export { JUDGE_RULES, SIGNOFF_RULES };
+export { JUDGE_RULES };