@webappwiz/cli 0.0.1

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@webappwiz/cli",
+	"version": "0.0.1",
+	"description": "The webappwiz CLI: judge code against rules, sign off a diff, and manage agent skills",
+	"license": "MIT",
+	"author": "Jared Johnson",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jaredjj3/webappwiz.git",
+		"directory": "packages/cli"
+	},
+	"type": "module",
+	"engines": {
+		"bun": ">=1.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@webappwiz/rules": "^0.0.1",
+		"webappwiz": "^0.0.1"
+	},
+	"peerDependencies": {
+		"typescript": "^7"
+	},
+	"main": "./index.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"default": "./index.js"
+		},
+		"./webappwiz": {
+			"types": "./webappwiz.d.ts",
+			"default": "./webappwiz.js"
+		},
+		"./rules": {
+			"types": "./rules.d.ts",
+			"default": "./rules.js"
+		},
+		"./judge": {
+			"types": "./judge.d.ts",
+			"default": "./judge.js"
+		},
+		"./signoff": {
+			"types": "./signoff.d.ts",
+			"default": "./signoff.js"
+		}
+	},
+	"bin": {
+		"webappwiz": "./index.js"
+	}
+}

package/report.d.ts

@@ -0,0 +1,85 @@
+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
+ * knows which one they are in without scrolling back.
+ *
+ * What `--print` writes is pages of markdown with headings of its own, so a
+ * heading is not enough to mark a boundary. Unnamed, this is the closing line
+ * 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;
+/**
+ * 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
+ * be one more thing to install and one more thing to be wrong about, and the
+ * 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.
+ */
+export interface Planned {
+    files: number;
+    rules: number;
+    calls: number;
+    /** Tokens the plan can see, which is a floor on what the run reads. */
+    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[];
+/** A finished review as the report prints it: what the call covered, what it
+ * found, and what it cost. */
+export interface Finished {
+    /** The ids of the rules the review checked. */
+    rules: string[];
+    /** How many files this review's agent was told to read. */
+    files: number;
+    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;
+    done: number;
+    total: number;
+}
+/**
+ * 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[];
+/**
+ * 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;

package/rules.d.ts

@@ -0,0 +1,20 @@
+import { type Rule } from "@webappwiz/rules";
+/**
+ * Every rule webappwiz judges itself by, named one by one. There is no preset
+ * to spread and nothing runs implicitly: a rule is here or it does not run.
+ *
+ * A constant rather than a config file, because rules reach the harness as
+ * objects. A project with its own rules writes its own list and hands it to
+ * `JudgeCommands` or to `Check` directly, rather than pointing a flag at a
+ * module for one of these to import.
+ */
+export declare const JUDGE_RULES: import("@webappwiz/rules").RuleSet;
+/**
+ * What an agent weighs before merging a change, rather than what it checks a
+ * file against: whether the change needs a person to look at it.
+ *
+ * No command runs these. They are documents an agent reads and applies itself,
+ * which is why they carry no glob and no check, and `wiz rules show` prints
+ * them the same as any other.
+ */
+export declare const SIGNOFF_RULES: Rule[];

package/rules.js

@@ -0,0 +1,8 @@
+import {
+  JUDGE_RULES,
+  SIGNOFF_RULES
+} from "./index-8jpb8xae.js";
+export {
+  SIGNOFF_RULES,
+  JUDGE_RULES
+};

package/signoff.d.ts

@@ -0,0 +1,63 @@
+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;
+    agent?: string;
+    exec?: string;
+    /** Print the rules to the logger and spawn nothing, for the reader who is
+     * going to apply them itself. */
+    print?: boolean;
+    /** 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
+ * own or needs a person to look at it first.
+ *
+ * One agent call over the diff, rather than one per file like `judge`: these
+ * rules are about the change as a whole, and a run that saw one file at a time
+ * could not answer them. Exits 1 with a reason when the change needs a person,
+ * so it reads the same to a merge gate as to whoever ran it.
+ */
+/** 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;
+}
+export declare class Signoff {
+    private rules;
+    private defaultAgent;
+    private confirmer;
+    private log;
+    private ps;
+    private clock;
+    constructor(rules: Rule[], defaultAgent: string, opts?: SignoffOptions);
+    run(opts: SignoffRunOptions): Promise<void>;
+    /** The one call, and what it says about the change. */
+    private judge;
+    /**
+     * The verdict, and a reason for each rule that wants a person. Throws on any
+     * of them: an agent that ran this before merging should escalate rather than
+     * merge, and an exit code is what says so whoever is reading.
+     */
+    private say;
+    /** The change as the agent reads it, priced by the prompt: what a new file
+     * costs to open is the agent's business and unknowable from here. */
+    private review;
+    /**
+     * The rules in full, for the reader who is going to apply them. Nothing has
+     * to run these: an agent about to merge its own work can weigh it against
+     * them itself, and that is the cheapest signoff there is.
+     */
+    private print;
+}

package/signoff.js

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

package/skills/add.d.ts

@@ -0,0 +1,7 @@
+import { type ProjectOptions } from "./skill.js";
+export interface AddOptions extends ProjectOptions {
+    /** The skill to install, as `skills ls` names it. */
+    skill: string;
+}
+/** Adds a skill a project does not have yet. */
+export declare function add(opts: AddOptions): Promise<void>;

package/skills/ls.d.ts

@@ -0,0 +1,7 @@
+import { type ProjectOptions } from "./skill.js";
+/**
+ * What there is to install, and what the project has of it. The version a
+ * project holds is the only thing `add` and `update` cannot tell it, so that
+ * is what this is for.
+ */
+export declare function ls(opts: ProjectOptions): Promise<void>;

package/skills/skill.d.ts

@@ -0,0 +1,36 @@
+import type { Logger } from "webappwiz/log";
+import type { Fs } from "webappwiz/system";
+/** Skill name to the document a project installs under that name. */
+export type Skills = Record<string, string>;
+/**
+ * The skills this package ships.
+ *
+ * They are imported rather than read out of a directory so they travel inside
+ * the build: what publishes is the compiled JavaScript, and a document sitting
+ * beside the source would not be part of it. Naming each one also means adding
+ * a skill is a line here rather than a file that a directory listing may or may
+ * not happen to pick up.
+ */
+export declare const bundled: Skills;
+export declare function versionOf(md: string): string | null;
+/** The project a skills command works on. */
+export interface ProjectOptions {
+    /** Its root: the directory holding `.agents/skills`. */
+    dir: string;
+    log?: Logger;
+    fs?: Fs;
+    /** The skills on offer; the ones this package ships by default. */
+    skills?: Skills;
+}
+/**
+ * Every skill on offer, name and document together, in the order they are
+ * listed and installed in.
+ */
+export declare function available(skills: Skills): Array<[string, string]>;
+/** What `copy` works through, once an action has resolved them. */
+export interface CopyOptions {
+    log: Logger;
+    fs: Fs;
+}
+/** Installs one skill into a project. */
+export declare function copy(name: string, doc: string, dir: string, opts: CopyOptions): Promise<void>;

package/skills/update.d.ts

@@ -0,0 +1,7 @@
+import { type ProjectOptions } from "./skill.js";
+/**
+ * Refreshes the skills a project already has. Which skills those are is the
+ * project's business, so this never adds one: a skill someone chose not to
+ * install should not arrive by way of an update.
+ */
+export declare function update(opts: ProjectOptions): Promise<void>;

package/table.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Row one is the header. Columns line up by what a cell shows rather than by
+ * what it holds, since a colored cell carries escapes nobody sees.
+ */
+export declare const table: (rows: string[][]) => string[];

package/update.d.ts

@@ -0,0 +1,22 @@
+import { type Logger } from "webappwiz/log";
+import { type Fs } from "webappwiz/system";
+import type { Skills } from "./skills/skill.js";
+/** Which tree to pin, and to what. */
+export interface UpdateOptions {
+    /** The directory to scan recursively for manifests. */
+    dir: string;
+    /** The version every webappwiz entry is set to. */
+    version: string;
+    log?: Logger;
+    fs?: Fs;
+    /** The skills to refresh with; the ones this package ships by default. */
+    skills?: Skills;
+}
+/**
+ * Pins every webappwiz dependency under `dir` to one version, so a project
+ * never runs two of these packages built against different versions of each
+ * other. They are released together, so there is only ever one right answer.
+ * Installed skills are copies of files those packages ship, so they are
+ * refreshed too.
+ */
+export declare function update(opts: UpdateOptions): Promise<void>;

package/webappwiz.d.ts

@@ -0,0 +1,15 @@
+import { type Deps } from "webappwiz/cmd";
+import type { Fs, Glob } from "webappwiz/system";
+import type { Clock } from "webappwiz/time";
+/** What webappwiz's commands are run with, on top of what any cli needs. */
+export interface CommandDeps extends Deps {
+    fs: Fs;
+    clock: Clock;
+    glob: Glob;
+}
+/**
+ * The `webappwiz` program. Run on its own it is the `webappwiz` bin; mounted
+ * (`wiz.mount("cli", webappwiz)`) the same commands answer as `wiz cli`, so
+ * neither spelling shells out to the other.
+ */
+export declare const webappwiz: import("webappwiz/cmd").Cli<CommandDeps, CommandDeps>;

package/webappwiz.js

@@ -0,0 +1,100 @@
+import {
+  add,
+  ls,
+  update,
+  update1 as update2,
+  version
+} from "./index-g2q5rg7s.js";
+import {
+  JUDGE_RULES,
+  SIGNOFF_RULES
+} from "./index-8jpb8xae.js";
+import {
+  Signoff
+} from "./index-3k3rtw49.js";
+import {
+  JudgeCommands
+} from "./index-jbrs6gqt.js";
+
+// webappwiz.ts
+import { AGENTS } from "@webappwiz/rules";
+import { cli } from "webappwiz/cmd";
+import { t } from "webappwiz/t";
+var webappwiz = cli("webappwiz");
+webappwiz.command("update").description("pin every webappwiz dependency in a tree to one version").arg("dir", t.string(), {
+  default: ".",
+  description: "directory to scan recursively (default: .)"
+}).option("version", t.string(), {
+  default: version,
+  description: "version to pin to"
+}).action((opts, { log, fs }) => update2({ ...opts, log, fs }));
+var judge = ({ log, fs, ps, clock, glob }) => new JudgeCommands(JUDGE_RULES, {
+  signoffRules: SIGNOFF_RULES,
+  log,
+  fs,
+  ps,
+  clock,
+  glob
+});
+webappwiz.command("judge").description("check a directory against the config, one agent per glob").arg("dir", t.string(), {
+  default: ".",
+  description: "directory to judge (default: .)"
+}).option("agent", t.optional(t.enum(Object.keys(AGENTS))), {
+  description: "model to check with (default: the config's agent)"
+}).option("exec", t.optional(t.string()), {
+  description: "command the prompt is passed to, instead of --agent"
+}).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"
+}).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: ".",
+  description: "directory whose change is weighed (default: .)"
+}).option("agent", t.optional(t.enum(Object.keys(AGENTS))), {
+  description: "model to weigh it with (default: the config's agent)"
+}).option("exec", t.optional(t.string()), {
+  description: "command the prompt is passed to, instead of --agent"
+}).option("print", t.boolean(), {
+  default: false,
+  description: "print the rules to apply yourself, and run no agent"
+}).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,
+  clock
+}).run(opts));
+var rules = webappwiz.group("rules").description("list and print the rules, to run or to read yourself");
+rules.command("ls").description("list the rules").action((_opts, deps) => judge(deps).ls());
+rules.command("show").description("print one rule in full, by the id `rules ls` gives it").arg("id", t.string(), { description: "rule id" }).action((opts, deps) => judge(deps).show(opts));
+var skillsGroup = webappwiz.group("skills").description("manage webappwiz agent skills in .agents/skills");
+skillsGroup.command("ls").description("list the skills there are, and what the project has of them").arg("dir", t.string(), {
+  default: ".",
+  description: "project to inspect (default: .)"
+}).action((opts, { log, fs }) => ls({ ...opts, log, fs }));
+skillsGroup.command("add").description("add a skill to a project").arg("skill", t.string(), { description: "skill name" }).arg("dir", t.string(), {
+  default: ".",
+  description: "project to add it to (default: .)"
+}).action((opts, { log, fs }) => add({ ...opts, log, fs }));
+skillsGroup.command("update").description("refresh the skills a project already has").arg("dir", t.string(), {
+  default: ".",
+  description: "project to refresh (default: .)"
+}).action((opts, { log, fs }) => update({ ...opts, log, fs }));
+export {
+  webappwiz
+};