@webappwiz/cli 0.0.9 → 0.0.11

package/index-d8p57dk5.js

@@ -0,0 +1,593 @@
+// package.json
+var version = "0.0.11";
+
+// documents.ts
+import { dirname } from "node:path";
+import { ConsoleLogger } from "webappwiz/log";
+import { NodeFs } from "webappwiz/system";
+function versionOf(md) {
+  const frontmatter = md.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "";
+  return frontmatter.match(/^version:\s*(.+)$/m)?.[1]?.trim() ?? null;
+}
+
+class Documents {
+  docs;
+  layout;
+  log;
+  fs;
+  constructor(docs, layout, opts = {}) {
+    this.docs = docs;
+    this.layout = layout;
+    this.log = opts.log ?? new ConsoleLogger;
+    this.fs = opts.fs ?? new NodeFs;
+  }
+  available() {
+    return Object.entries(this.docs).toSorted(([left], [right]) => left.localeCompare(right));
+  }
+  path(dir, name) {
+    return `${dir}/${this.layout.root}/${name}/${this.layout.file}`;
+  }
+  async installed(dir) {
+    const names = await this.fs.readdir(`${dir}/${this.layout.root}`).catch(() => []);
+    const present = [];
+    for (const name of names.toSorted()) {
+      if (await this.fs.exists(this.path(dir, name))) {
+        present.push(name);
+      }
+    }
+    return present;
+  }
+  async installedVersion(dir, name) {
+    return this.fs.read(this.path(dir, name)).then(versionOf).catch(() => null);
+  }
+  async add(name, dir) {
+    const doc = this.docs[name];
+    if (doc === undefined) {
+      const have = this.available().map(([known]) => known);
+      throw new Error(`no such ${this.layout.noun}: ${name} (have ${have.join(", ")})`);
+    }
+    await this.copy(name, doc, dir);
+  }
+  async update(dir) {
+    const installed = await this.installed(dir);
+    const ours = this.available().filter(([name]) => installed.includes(name));
+    for (const [name, doc] of ours) {
+      await this.copy(name, doc, dir);
+    }
+    return ours.map(([name]) => name);
+  }
+  async copy(name, doc, dir) {
+    const target = this.path(dir, name);
+    await this.fs.mkdir(dirname(target));
+    await this.fs.write(target, doc);
+    this.log.info(`wrote ${target}`);
+  }
+}
+
+// rules/rule-set.ts
+import { catalog } from "@webappwiz/rules/catalog";
+var RULES = {
+  root: ".wiz/rules",
+  file: "RULE.md",
+  noun: "rule"
+};
+var offered = (opts) => opts.rules ?? catalog;
+
+// rules/add.ts
+async function add(opts) {
+  const documents = new Documents(offered(opts), RULES, opts);
+  await documents.add(opts.rule, opts.dir);
+}
+
+// rules/ls.ts
+import { Rule, Rules } from "@webappwiz/rules";
+import { ConsoleLogger as ConsoleLogger2, color as color2 } from "webappwiz/log";
+
+// table.ts
+import { color } from "webappwiz/log";
+var table = (rows) => {
+  const width = (cell) => color.strip(cell).length;
+  const widths = rows[0]?.map((_, i) => Math.max(...rows.map((row) => width(row[i] ?? ""))));
+  return rows.map((row) => row.map((cell, i) => cell.padEnd((widths?.[i] ?? 0) + cell.length - width(cell))).join("   ").trimEnd());
+};
+
+// rules/ls.ts
+async function ls(opts) {
+  const log = opts.log ?? new ConsoleLogger2;
+  const documents = new Documents(offered(opts), RULES, opts);
+  const local = await Rules.load(opts.dir, { fs: opts.fs });
+  const shipped = new Map(documents.available().map(([id, doc]) => [id, Rule.parse(doc, { id })]));
+  const ids = new Set([...local.all.map((rule) => rule.id), ...shipped.keys()]);
+  const rows = [
+    [
+      "rule",
+      "level",
+      "complexity",
+      "files",
+      "ships",
+      "installed",
+      "description"
+    ].map(color2.dim)
+  ];
+  let stale = 0;
+  for (const id of [...ids].toSorted()) {
+    const rule = local.get(id) ?? shipped.get(id);
+    if (!rule) {
+      continue;
+    }
+    const ships = shipped.get(id)?.version ?? null;
+    const installed = local.get(id) ? local.get(id)?.version ?? "local" : null;
+    if (ships !== null && installed !== null && ships !== installed) {
+      stale++;
+    }
+    rows.push([
+      id,
+      rule.level,
+      rule.complexity,
+      rule.files,
+      ships ?? "-",
+      installed ?? "-",
+      rule.description
+    ]);
+  }
+  const lines = table(rows);
+  if (stale > 0) {
+    lines.push("", `${stale} out of date: run \`rules update\``);
+  }
+  log.info(lines.join(`
+`));
+}
+
+// rules/new.ts
+import { RULE_FILE, RULES_ROOT, template } from "@webappwiz/rules";
+import { ConsoleLogger as ConsoleLogger3 } from "webappwiz/log";
+import { NodeFs as NodeFs2 } from "webappwiz/system";
+async function newRule(opts) {
+  const log = opts.log ?? new ConsoleLogger3;
+  const fs = opts.fs ?? new NodeFs2;
+  const dir = `${opts.dir}/${RULES_ROOT}/${opts.name}`;
+  const path = `${dir}/${RULE_FILE}`;
+  if (await fs.exists(path)) {
+    throw new Error(`${path} already exists`);
+  }
+  const doc = template(opts.name);
+  await fs.mkdir(dir);
+  await fs.write(path, doc);
+  log.info(`wrote ${path}`);
+}
+
+// rules/review.ts
+import { changed, Rules as Rules2 } from "@webappwiz/rules";
+import { ConsoleLogger as ConsoleLogger4 } from "webappwiz/log";
+async function review(opts) {
+  const log = opts.log ?? new ConsoleLogger4;
+  const rules = await Rules2.load(opts.dir, { fs: opts.fs });
+  if (rules.all.length === 0) {
+    throw new Error(`no rules in ${opts.dir}/.wiz/rules: copy one in with \`rules add\`, or write one with \`rules new\``);
+  }
+  const files = await changed(opts.dir, opts.since, { ps: opts.ps });
+  if (files.length === 0) {
+    log.info(`nothing has changed since ${opts.since}`);
+    return;
+  }
+  const blocks = rules.review(files, { chunk: opts.chunk, glob: opts.glob });
+  const count = (total, noun) => `${total} ${noun}${total === 1 ? "" : "s"}`;
+  if (blocks.length === 0) {
+    log.info(`no rule matches the ${count(files.length, "file")} changed since ${opts.since}`);
+    return;
+  }
+  const matched = new Set(blocks.map((block) => block.rule.id)).size;
+  log.info(`${count(files.length, "file")} changed since ${opts.since}; ` + `${count(matched, "rule")} matched, ${count(blocks.length, "block")} to review`);
+  for (const block of blocks) {
+    log.info("");
+    log.info(block.prompt(opts.since));
+  }
+}
+
+// rules/update.ts
+import { ConsoleLogger as ConsoleLogger5 } from "webappwiz/log";
+async function update(opts) {
+  const log = opts.log ?? new ConsoleLogger5;
+  const documents = new Documents(offered(opts), RULES, opts);
+  const refreshed = await documents.update(opts.dir);
+  if (refreshed.length === 0) {
+    log.info(`no webappwiz rules in ${opts.dir}: add one with \`rules add\``);
+  }
+}
+
+// templates/arbor.skill.md
+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.11
+---
+
+# Using arbor
+
+\`arbor\` runs many agents on one repo, each in its own git worktree, landing on
+trunk without pull requests. Run it with \`bunx @webappwiz/arbor <command>\` (or
+\`arbor\` if on PATH). \`arbor --help\` explains the commands; this file covers
+only what the CLI cannot tell you.
+
+**Rule:** never use raw git for state transitions arbor covers. Every landing
+goes through \`arbor merge\`. The only exception is finishing an in-progress
+rebase (\`git add\`, \`git rebase --continue\`), then merging again.
+
+A failed command prints \`{reason}\` JSON on stdout and instructions on stderr:
+do what stderr says. The one case to memorize is exit 4 \`lease_lost\`: stop,
+do not retry, another agent owns the tree.
+
+## Before you start
+
+Other agents may already be working. Before creating anything, list the files
+you expect to touch, then \`arbor ls\`, and for each task in flight compare with
+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, \`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\`: 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): watch a task's status, never its lease.
+
+## Workflow
+
+1. \`arbor add <task>\`, or \`arbor claim <task>\` to resume one. When this skill
+   is invoked with a branch argument (\`/arbor feature/auth\`), or the user
+   names the branch the work should land on, pass it as \`--base\` to every
+   task you create for that request. Otherwise omit \`--base\`; never guess a
+   base from the currently checked-out branch.
+2. Fill in the \`ARBOR.md\` stub \`add\` wrote at the worktree root (see below)
+   before touching code.
+3. Do the work, updating \`ARBOR.md\` as you go; commit with git (arbor never
+   commits for you).
+4. \`arbor merge\`. On failure, do what stderr says and merge again.
+
+A successful merge deletes the worktree, and your working directory with it:
+\`cd\` to the main tree (merge prints its path) before running anything else.
+
+## Escalation
+
+Merge only work you verified yourself. Escalate instead when verification
+needs a person: external services, destructive migrations, anything tests
+cannot confirm. And if the user asked to see the work before it lands,
+escalate regardless.
+
+1. \`arbor escalate <reason>\`.
+2. Under \`## Blocked\` in \`ARBOR.md\`, state what needs verifying, ending in a
+   question a yes/no or a sentence can answer.
+3. Leave something the human can look at and print its **absolute path**
+   (start from \`arbor path <task>\`). For anything visual or UX, that means a
+   screenshot; if producing one is expensive or has side effects, ask before
+   starting and say what it will cost.
+
+If you claim a tree whose \`## Blocked\` question is unanswered, do not resume
+or merge: ask the user and wait for the answer.
+
+## Reporting
+
+However a task ends, say so in one block; only a merge names a base:
+
+\`\`\`markdown
+### ✅ Merged \`<task>\` onto \`<base>\`
+
+One sentence blending what the task set out to do with where it ended up.
+\`\`\`
+
+\`\`\`markdown
+### ⚠️ Escalated \`<task>\`
+
+One sentence blending what the task set out to do with what it now waits on.
+\`\`\`
+
+\`\`\`markdown
+### 🛑 Removed \`<task>\`
+
+One sentence blending what the task set out to do with why you \`arbor rm\`ed
+it instead.
+\`\`\`
+
+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 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
+\`ARBOR.md\` from git for you: never commit it, and never mention it in a commit
+message.
+
+## Committing
+
+Plain, human-style commit messages with **no attribution**: no
+\`Co-authored-by:\` trailers, no "Generated with", no agent or model names, no
+\`--author\` overrides. Commit as often as it helps you; a task usually takes
+fewer than 5 commits, and wanting many more means the task wants splitting,
+not squashing.
+`;
+
+// templates/review.skill.md
+var review_skill_default = `---
+name: review
+description: "Review a change against the RULE.md rules in this project's .wiz/rules directory by handing each rule to a subagent, without reading a rule yourself. Use only when the project has a .wiz/rules directory and the user asks to run, check, or apply the rules, the wiz rules, or the webappwiz rules to a change, or asks to write, add, or edit a rule there. Not for a general code review, a pull request review, a security review, or any review that does not name the rules."
+version: 0.0.11
+---
+
+# Reviewing against the rules
+
+The rules are markdown, one per directory under \`.wiz/rules\`, each a \`RULE.md\`
+a subagent reads. You never read one. Reading rules loads their prose into
+your context and you start reasoning about style instead of running the
+review, so the whole loop is built to keep them out of your sight: the CLI
+divides the work into blocks that name a rule's file, and a subagent opens it.
+
+Run the CLI with \`bunx @webappwiz/cli rules <command>\` (or \`wiz cli rules\`
+if \`wiz\` is on PATH). \`rules --help\` lists the commands; this file covers
+only what the CLI cannot tell you.
+
+## The loop
+
+1. Make sure the work is finished and its tests pass. Review is the last step,
+   not a way to find out what to build.
+2. Run \`rules review --since <ref>\`, with the ref the change is measured from:
+   \`main\` for a branch, \`HEAD\` for uncommitted work. It prints a summary line
+   and then one block per unit of work, each starting with a \`## \` heading.
+3. Spawn one subagent per block, all in parallel, and give each the whole
+   block verbatim as its prompt. Add nothing. The block already says which
+   file to read, which files to judge, how to see the change, and how to
+   answer.
+4. Collect the replies. Each is a JSON array of \`{file, line, message}\`, empty
+   when the rule found nothing.
+5. Report the findings grouped by file, each with its rule id and the rule's
+   level from the block heading. Then stop. Fixing is a separate decision.
+
+If a block's reply is not a JSON array, run that block again once, then
+report it as unanswered rather than guessing what it found.
+
+## Choosing a model
+
+Every heading carries the rule's complexity:
+
+\`\`\`
+## no-em-dashes (3 files, complexity low)
+\`\`\`
+
+Complexity is how hard the rule is to judge. \`low\` is a grep or a count:
+give it the cheapest, fastest model available. \`high\` is design judgment
+across a whole file: give it the strongest. \`medium\` is whatever the harness
+uses by default.
+
+## Fixing
+
+When asked to fix what the review found, spawn one subagent per finding with
+a prompt like this, and nothing else about the rule:
+
+\`\`\`
+Read \`.wiz/rules/<id>/RULE.md\`. In \`<file>\` at line <line>, the code <message>.
+Change the code so it follows the rule, touching as little as you can, and
+reply with the diff.
+\`\`\`
+
+The subagent reads the rule and decides the fix. You still have not read it.
+
+## Writing a rule
+
+When asked to write a rule, or to add one from the catalog:
+
+- \`rules ls\` lists every rule that ships and every rule the project has.
+- \`rules add <id>\` copies a shipped rule into \`.wiz/rules/<id>/RULE.md\`,
+  where it runs and can be edited.
+- \`rules new <name>\` scaffolds \`.wiz/rules/<name>/RULE.md\` to fill in. The
+  frontmatter has \`description\`, \`files\` (the glob a review matches changed
+  files against), \`level\` (\`error\` or \`warning\`), \`complexity\` (\`low\`,
+  \`medium\` or \`high\`). The body is yours, as a skill's is: the template
+  suggests a title, the prose a subagent judges by, and \`## Good\` and
+  \`## Bad\` sections with examples, and nothing checks for them. Fill it in,
+  delete the comment that explains it, and run \`rules ls\`: it validates the
+  frontmatter of every rule and names the line that is wrong.
+
+Rules are English. A rule that only concerns some files says so in its glob;
+a rule that only concerns files with some construct says so in its prose, and
+the subagent that reads it greps or writes a script to find them. There is no
+code to write for a rule, ever.
+
+Writing a rule is the one time you read one, and only the one you are
+writing. To remove a rule, delete its directory.
+`;
+
+// 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.11
+---
+
+# 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 review, 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, review: review_skill_default, webappwiz: webappwiz_skill_default };
+var SKILLS = {
+  root: ".agents/skills",
+  file: "SKILL.md",
+  noun: "skill"
+};
+
+// skills/add.ts
+async function add2(opts) {
+  const documents = new Documents(opts.skills ?? bundled, SKILLS, opts);
+  await documents.add(opts.skill, opts.dir);
+}
+
+// skills/ls.ts
+import { ConsoleLogger as ConsoleLogger6, color as color3 } from "webappwiz/log";
+async function ls2(opts) {
+  const log = opts.log ?? new ConsoleLogger6;
+  const documents = new Documents(opts.skills ?? bundled, SKILLS, opts);
+  const rows = [["skill", "ships", "installed"].map(color3.dim)];
+  let stale = 0;
+  for (const [name, doc] of documents.available()) {
+    const ships = versionOf(doc) ?? "?";
+    const installed = await documents.installedVersion(opts.dir, name);
+    if (installed !== null && installed !== ships) {
+      stale++;
+    }
+    rows.push([name, ships, installed ?? "-"]);
+  }
+  const lines = table(rows);
+  if (stale > 0) {
+    lines.push("", `${stale} out of date: run \`skills update\``);
+  }
+  log.info(lines.join(`
+`));
+}
+
+// skills/update.ts
+import { ConsoleLogger as ConsoleLogger7 } from "webappwiz/log";
+async function update2(opts) {
+  const log = opts.log ?? new ConsoleLogger7;
+  const documents = new Documents(opts.skills ?? bundled, SKILLS, opts);
+  const refreshed = await documents.update(opts.dir);
+  if (refreshed.length === 0) {
+    log.info(`no webappwiz skills in ${opts.dir}: add one with \`skills add\``);
+  }
+}
+
+// update.ts
+import { basename } from "node:path";
+import { ConsoleLogger as ConsoleLogger8 } from "webappwiz/log";
+import { NodeFs as NodeFs3, walk } from "webappwiz/system";
+var DEPENDENCY = /("(?:webappwiz|@webappwiz\/[^"]+)"\s*:\s*")(?!workspace:)[^"]*(")/g;
+async function update3(opts) {
+  const log = opts.log ?? new ConsoleLogger8;
+  const fs = opts.fs ?? new NodeFs3;
+  let count = 0;
+  for await (const path of walk(opts.dir, { fs })) {
+    if (basename(path) !== "package.json") {
+      continue;
+    }
+    const before = await fs.read(path);
+    const after = before.replace(DEPENDENCY, `$1${opts.version}$2`);
+    if (after === before) {
+      continue;
+    }
+    await fs.write(path, after);
+    log.info(`updated ${path}`);
+    count++;
+  }
+  log.info(`${count} package.json pinned to ${opts.version}`);
+  await update2({ dir: opts.dir, log, fs, skills: opts.skills });
+  await update({ dir: opts.dir, log, fs, rules: opts.rules });
+}
+
+export { version, add, ls, newRule, review, update, add2 as add1, ls2 as ls1, update2 as update1, update3 as update2 };