wachiman 1.14.0 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +2 -1
  2. package/package.json +4 -2
  3. package/src/accounts/commands.ts +3 -2
  4. package/src/accounts/confirm.ts +63 -4
  5. package/src/accounts/profile-list.ts +24 -0
  6. package/src/cli.ts +161 -142
  7. package/src/config.ts +19 -6
  8. package/src/connectors/local-git.ts +47 -0
  9. package/src/doctor/checks.ts +106 -1
  10. package/src/doctor/run.ts +9 -1
  11. package/src/engine.ts +294 -97
  12. package/src/help.ts +637 -0
  13. package/src/init/args.ts +5 -2
  14. package/src/init/github-login.ts +13 -0
  15. package/src/init/options.ts +31 -3
  16. package/src/init/prompt.ts +46 -15
  17. package/src/init/run.ts +238 -32
  18. package/src/init/settings.ts +127 -0
  19. package/src/init/write.ts +16 -102
  20. package/src/ledger-read/command.ts +106 -0
  21. package/src/ledger-read/credentials.ts +103 -0
  22. package/src/ledger-read/files.ts +141 -0
  23. package/src/ledger-read/pull.ts +69 -0
  24. package/src/ledger-read/rows.ts +60 -0
  25. package/src/ledger-read/types.ts +127 -0
  26. package/src/ledger.ts +34 -18
  27. package/src/local-ask.ts +5 -4
  28. package/src/local.ts +55 -10
  29. package/src/loop/command.ts +5 -5
  30. package/src/pr-template/adopt.ts +434 -0
  31. package/src/pr-template/catalog.ts +429 -0
  32. package/src/pr-template/check-run.ts +328 -0
  33. package/src/pr-template/check.ts +338 -0
  34. package/src/pr-template/describe.ts +368 -0
  35. package/src/pr-template/format.ts +399 -0
  36. package/src/pr-template/gh.ts +159 -0
  37. package/src/pr-template/install.ts +288 -0
  38. package/src/pr-template/legacy-guides.ts +50 -0
  39. package/src/pr-template/pr-risk.ts +426 -0
  40. package/src/pr-template/render.ts +302 -0
  41. package/src/pr-template/resolve.ts +65 -0
  42. package/src/pr-template/run.ts +88 -0
  43. package/src/pr-template/strip.ts +171 -0
  44. package/src/pr-template/write.ts +139 -0
  45. package/src/providers/claude-code.ts +7 -8
  46. package/src/providers/codex.ts +4 -4
  47. package/src/providers/spawn.ts +95 -0
  48. package/src/providers/types.ts +5 -2
  49. package/src/repo-settings.ts +159 -0
  50. package/src/setup/prompt.ts +49 -33
  51. package/src/setup/run.ts +58 -16
  52. package/src/sinks/common.ts +10 -3
  53. package/src/sinks/markdown.ts +3 -2
  54. package/src/sinks/terminal.ts +3 -2
  55. package/src/spend/report.ts +349 -0
  56. package/src/status/command.ts +150 -36
  57. package/src/store/command.ts +20 -3
  58. package/src/store/html.ts +205 -8
  59. package/src/store/index.ts +64 -5
  60. package/src/store/rows.ts +103 -0
  61. package/src/upgrade/command.ts +286 -0
  62. package/src/upgrade/pin.ts +112 -0
  63. package/src/wizard/interactive.ts +11 -0
  64. package/src/wizard/launcher.ts +340 -0
  65. package/src/wizard/load.ts +30 -0
  66. package/src/wizard/mascot.ts +228 -0
  67. package/src/wizard/prompt-fancy.ts +135 -0
  68. package/src/wizard/prompt.ts +108 -61
  69. package/src/wizard/style.ts +93 -13
  70. package/src/wizard/tone.ts +11 -0
  71. package/src/wizard/ui.ts +80 -0
  72. package/templates/pr/sections.json +163 -0
package/src/config.ts CHANGED
@@ -14,6 +14,9 @@ export type Trigger = string;
14
14
  /** Whether a run started by `trigger` spends from the pull request's automatic ceiling. */
15
15
  export const isAutomatic = (trigger: Trigger | undefined) => trigger !== undefined && trigger !== "comment";
16
16
 
17
+ /** Where a setting's value came from: the environment (a workflow input or `WACHIMAN_*`), the repository's `.wachiman.yml`, or the built-in default. */
18
+ export type SettingSource = "env" | "file" | "default";
19
+
17
20
  export type LimitMode = "fail" | "notice";
18
21
  export type LedgerUnavailableMode = "run" | "stop";
19
22
 
@@ -64,8 +67,13 @@ export interface EngineConfig {
64
67
  * reviewed, without reading the previous-review marker. Only together with `dryRun`.
65
68
  */
66
69
  fullReview: boolean;
67
- /** The provider's default (`DEFAULT_MODELS`) when unset. */
70
+ /**
71
+ * `WACHIMAN_MODEL`, else `model` of the repository's `.wachiman.yml` (`applyRepoSettings`), else the
72
+ * provider's default (`DEFAULT_MODELS`).
73
+ */
68
74
  model: string;
75
+ /** Where `model` came from. `loadConfig` sets `env` or `default`; `applyRepoSettings` may change `default` to `file`. */
76
+ modelSource?: SettingSource;
69
77
  provider: string;
70
78
  /** `WACHIMAN_PRICE_PER_MTOK`: "input,cached_input,output" USD per million tokens, for a Codex model without a built-in price. */
71
79
  pricePerMTok?: string;
@@ -74,6 +82,8 @@ export interface EngineConfig {
74
82
  * alter reviews. Passed as `--effort` (Claude Code) or `model_reasoning_effort` (Codex).
75
83
  */
76
84
  effort: Effort;
85
+ /** Where `effort` came from, as for `modelSource`. */
86
+ effortSource?: SettingSource;
77
87
  /**
78
88
  * `WACHIMAN_MAX_TURNS`: the most agent turns one provider call may take. Passed as
79
89
  * `--max-turns` (Claude Code); Codex has no equivalent and ignores it.
@@ -149,7 +159,7 @@ export function readSetting(env: Env, name: string, warn: (line: string) => void
149
159
  * else the default. An unknown value is a configuration error: a silent fallback would run the
150
160
  * review at an effort nobody chose.
151
161
  */
152
- function readEffort(env: Env, warn: (line: string) => void): Effort {
162
+ function readEffort(env: Env, warn: (line: string) => void): { value: Effort; source: SettingSource } {
153
163
  const current = readSetting(env, "EFFORT", warn);
154
164
  const old = readSetting(env, "REASONING_EFFORT", () => {});
155
165
  let name = "WACHIMAN_EFFORT";
@@ -161,11 +171,11 @@ function readEffort(env: Env, warn: (line: string) => void): Effort {
161
171
  name = "WACHIMAN_REASONING_EFFORT";
162
172
  }
163
173
  }
164
- if (raw === undefined) return DEFAULT_EFFORT;
174
+ if (raw === undefined) return { value: DEFAULT_EFFORT, source: "default" };
165
175
  if (!(EFFORTS as readonly string[]).includes(raw)) {
166
176
  throw new UsageError(`${name} must be one of ${EFFORTS.join(", ")}, got "${raw}".`);
167
177
  }
168
- return raw as Effort;
178
+ return { value: raw as Effort, source: "env" };
169
179
  }
170
180
 
171
181
  export function loadConfig(env: Env, warn: (line: string) => void = console.error): EngineConfig {
@@ -185,6 +195,7 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
185
195
  throw new UsageError(`WACHIMAN_ON_PROVIDER_UNAVAILABLE must be warn or fail, got "${onProviderUnavailable}".`);
186
196
  }
187
197
  const provider = get("PROVIDER") ?? "claude-code";
198
+ const modelFromEnv = get("MODEL");
188
199
  const dryRun = get("DRY_RUN") === "1";
189
200
  const fullReview = get("FULL_REVIEW") === "1";
190
201
  if (fullReview && !dryRun) {
@@ -250,10 +261,12 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
250
261
  batchChars: number("BATCH_CHARS", 140000, true),
251
262
  dryRun,
252
263
  fullReview,
253
- model: get("MODEL") ?? DEFAULT_MODELS[provider as keyof typeof DEFAULT_MODELS] ?? DEFAULT_MODELS["claude-code"],
264
+ model: modelFromEnv ?? DEFAULT_MODELS[provider as keyof typeof DEFAULT_MODELS] ?? DEFAULT_MODELS["claude-code"],
265
+ modelSource: modelFromEnv === undefined ? "default" : "env",
254
266
  provider,
255
267
  pricePerMTok: get("PRICE_PER_MTOK"),
256
- effort,
268
+ effort: effort.value,
269
+ effortSource: effort.source,
257
270
  maxTurns: number("MAX_TURNS", DEFAULT_MAX_TURNS, true),
258
271
  callTimeoutS: number("CALL_TIMEOUT_S", DEFAULT_CALL_TIMEOUT_S, true),
259
272
  onProviderUnavailable,
@@ -17,6 +17,7 @@ import { UsageError } from "../config";
17
17
  import {
18
18
  instructionFileOf,
19
19
  instructionsFrom,
20
+ MAX_INSTRUCTION_BYTES,
20
21
  REVIEW_INPUT_FORMAT,
21
22
  resolveScope,
22
23
  type BaseInstructions,
@@ -24,6 +25,7 @@ import {
24
25
  type ReviewInput,
25
26
  } from "../engine";
26
27
  import { GIT_BASE_ARGS, gitEnv, spawnGit, type GitRunner } from "../evidence";
28
+ import { parseRepoSettings, SETTINGS_PATH, type RepoSettings } from "../repo-settings";
27
29
 
28
30
  const TIMEOUT_MS = 60_000;
29
31
  /** The whole branch diff is one output; a large branch can be far over the evidence step's 8 MB. */
@@ -353,6 +355,51 @@ export function localInstructions(
353
355
  );
354
356
  }
355
357
 
358
+ /** What decides the commit whose `.wachiman.yml` a local run reads: the same scope flags the review itself takes. */
359
+ export interface SettingsScope {
360
+ /** `--working-tree`: the instruction files are read at `HEAD`, and so is the settings file. */
361
+ workingTree?: "staged" | "all";
362
+ base?: string;
363
+ commit?: string;
364
+ from?: string;
365
+ maxDepth?: number;
366
+ /** `--input`: the base commit the input file names. */
367
+ inputBase?: string;
368
+ }
369
+
370
+ /**
371
+ * The commit whose `.wachiman.yml` a local run reads, the one the instruction files are read at:
372
+ * the merge-base (the start of the diff), `HEAD` for a working-tree review, or the input file's
373
+ * base. Never the head, so a branch cannot raise the model or the effort it is reviewed under.
374
+ * Undefined when the scope does not resolve; the review's own ref checks report that, with their
375
+ * message, a moment later.
376
+ */
377
+ export function localSettingsCommit(repoDir: string, scope: SettingsScope, git: GitRunner = spawnGit): string | undefined {
378
+ if (scope.inputBase !== undefined) return scope.inputBase;
379
+ try {
380
+ if (scope.workingTree) return run(git, repoDir, ["rev-parse", "--verify", "HEAD^{commit}"]).trim();
381
+ return resolveRefs(repoDir, scope.base, git, scope.maxDepth, { commit: scope.commit, from: scope.from }).mergeBase;
382
+ } catch {
383
+ return undefined;
384
+ }
385
+ }
386
+
387
+ /**
388
+ * `.wachiman.yml` as it is at `sha`, parsed, or undefined when there is none there (or `sha` is
389
+ * not in this clone: an `--input` file can name one that is not). An invalid file is a usage error.
390
+ */
391
+ export function localRepoSettings(repoDir: string, sha: string, git: GitRunner = spawnGit): RepoSettings | undefined {
392
+ let bytes: Buffer | null;
393
+ try {
394
+ bytes = blobAt(repoDir, sha, SETTINGS_PATH, git);
395
+ } catch {
396
+ return undefined;
397
+ }
398
+ if (!bytes) return undefined;
399
+ if (bytes.length > MAX_INSTRUCTION_BYTES) throw new UsageError(`${SETTINGS_PATH} at ${short(sha)} is over ${MAX_INSTRUCTION_BYTES / 1024} KB, too large for a settings file.`);
400
+ return parseRepoSettings(bytes.toString("utf8"));
401
+ }
402
+
356
403
  const names = (out: string) => out.split("\0").filter(Boolean);
357
404
 
358
405
  /**
@@ -16,10 +16,13 @@ import type { HistoryRepository } from "../history/types";
16
16
  import { detectInstall, type InstallKind } from "../install-kind";
17
17
  import { inspectIsolatedProfile } from "../profiles";
18
18
  import { buildChildEnv } from "../providers/claude-code";
19
+ import { effectiveSettings, OLD_SETTINGS_PATH, parseRepoSettings, SETTINGS_PATH } from "../repo-settings";
20
+ import { UsageError } from "../config";
21
+ import { classifyRef, compareVersions, parseTag, scanWorkflows } from "../upgrade/pin";
19
22
 
20
23
  export type CheckLevel = "required" | "optional";
21
24
  export type CheckStatus = "ok" | "fail" | "warn" | "skip";
22
- export type CheckId = "wachiman" | "bun" | "git" | "tar" | "config" | "profile" | "auth" | "environment" | "project" | "history" | "skills" | "isolation";
25
+ export type CheckId = "wachiman" | "bun" | "git" | "tar" | "config" | "profile" | "auth" | "environment" | "project" | "settings" | "workflow-pin" | "history" | "skills" | "isolation";
23
26
 
24
27
  export interface DoctorRow {
25
28
  id: CheckId;
@@ -49,6 +52,8 @@ export interface DoctorFs {
49
52
  isDirectory: (path: string) => boolean;
50
53
  /** The names in a directory; empty when it cannot be listed. */
51
54
  list: (path: string) => string[];
55
+ /** Like `list`, but throws when the directory cannot be read (used by the workflow-pin row). */
56
+ listStrict?: (path: string) => string[];
52
57
  /** Permission bits, or undefined where the platform has none. */
53
58
  mode: (path: string) => number | undefined;
54
59
  /** Used only for a managed profile's `settings.json`. */
@@ -56,6 +61,7 @@ export interface DoctorFs {
56
61
  }
57
62
 
58
63
  export const realDoctorFs: DoctorFs = {
64
+ listStrict: (p) => readdirSync(p),
59
65
  exists: (p) => existsSync(p),
60
66
  isDirectory: (p) => {
61
67
  try {
@@ -102,6 +108,10 @@ export interface DoctorContext {
102
108
  config: ConfigRead;
103
109
  /** The repository of `--repo-dir`, or why there is none. */
104
110
  repository: { ok: true; value: HistoryRepository } | { ok: false; reason: string };
111
+ /** The top of the working tree of `--repo-dir` (where `.wachiman.yml` is looked for); undefined when it is not one. */
112
+ root?: string;
113
+ /** `.wachiman.yml` differs from the last commit (new, edited or deleted): runs do not see the working copy yet. */
114
+ settingsUncommitted?: boolean;
105
115
  /** The profile the full resolution picks (or the one `--profile` names); undefined when it resolves to nothing. */
106
116
  primary: ResolvedProfile | undefined;
107
117
  /** The profile this pass of `profile`, `auth` and `isolation` looks at. */
@@ -359,6 +369,101 @@ export const CHECKS: DoctorCheck[] = [
359
369
  };
360
370
  },
361
371
  },
372
+ {
373
+ // Read-only: reports the repository's `.wachiman.yml` (the working tree is fine here; a run reads
374
+ // the base commit) and where the model and the effort of a run would come from. Never writes or moves anything.
375
+ id: "settings",
376
+ level: "optional",
377
+ run: ({ root, env, fs, settingsUncommitted }) => {
378
+ if (root === undefined) return { id: "settings", level: "optional", status: "skip", evidence: "not in a git working tree: no repository settings to read" };
379
+ const file = join(root, SETTINGS_PATH);
380
+ const old = join(root, OLD_SETTINGS_PATH);
381
+ const hasFile = fs.exists(file);
382
+ const hasOld = fs.exists(old);
383
+ let settings: ReturnType<typeof parseRepoSettings> | undefined;
384
+ if (hasFile) {
385
+ try {
386
+ settings = parseRepoSettings(fs.read(file));
387
+ } catch (error) {
388
+ const why = error instanceof UsageError ? error.message : `${SETTINGS_PATH} cannot be read (${error instanceof Error ? error.message : error})`;
389
+ return {
390
+ id: "settings",
391
+ level: "optional",
392
+ status: "warn",
393
+ evidence: `the working copy of ${SETTINGS_PATH} is invalid: ${why} Runs read it at the base commit (Actions) or the merge-base (local), so it takes effect once committed and merged; a run with a broken file at that commit ignores it with a warning and uses the defaults.`,
394
+ fix: `fix ${SETTINGS_PATH} (effort is low, medium, high, xhigh or max; model is a model name), or remove it to use the defaults`,
395
+ detail: { file, valid: false },
396
+ };
397
+ }
398
+ }
399
+ const effective = effectiveSettings(env, settings);
400
+ const from = (s: { value: string; source: string; skipped?: string }) =>
401
+ `${s.value} (${s.source === "file" ? `from ${SETTINGS_PATH}` : s.source === "env" ? "from the environment" : s.skipped !== undefined ? `default; the model "${settings?.model}" in ${SETTINGS_PATH} is skipped: ${s.skipped}` : "default"})`;
402
+ const read = hasFile ? `${SETTINGS_PATH}: kind ${settings?.kind ?? "not set"}, model ${settings?.model ?? "not set"}, effort ${settings?.effort ?? "not set"}` : `no ${SETTINGS_PATH}`;
403
+ const detail = {
404
+ file: hasFile ? file : null,
405
+ valid: true,
406
+ kind: settings?.kind ?? null,
407
+ model: settings?.model ?? null,
408
+ effort: settings?.effort ?? null,
409
+ effectiveModel: effective.model.value,
410
+ modelFrom: effective.model.source,
411
+ modelSkipped: effective.model.skipped ?? null,
412
+ effectiveEffort: effective.effort.value,
413
+ effortFrom: effective.effort.source,
414
+ uncommitted: settingsUncommitted === true,
415
+ };
416
+ // A run reads the committed file, so with uncommitted changes the working copy says what will apply once committed, not now.
417
+ const runs = settingsUncommitted
418
+ ? `${SETTINGS_PATH} has changes that are not committed, and runs read the committed file: once committed (and merged, for Actions) a run would use model ${from(effective.model)}, effort ${from(effective.effort)}`
419
+ : `a run here would use model ${from(effective.model)}, effort ${from(effective.effort)}`;
420
+ const evidence = `${read}; ${runs}. GitHub Actions reads the file from the base commit of the pull request, not from the head`;
421
+ if (hasOld) {
422
+ return {
423
+ id: "settings",
424
+ level: "optional",
425
+ status: "warn",
426
+ evidence: `${OLD_SETTINGS_PATH} exists and is never read (the settings file is ${SETTINGS_PATH} at the root); ${evidence}`,
427
+ fix: hasFile ? `merge ${OLD_SETTINGS_PATH} into ${SETTINGS_PATH}, then remove it` : `mv ${OLD_SETTINGS_PATH} ${SETTINGS_PATH}`,
428
+ detail: { ...detail, oldLocation: old },
429
+ };
430
+ }
431
+ return { id: "settings", level: "optional", status: "ok", evidence, detail };
432
+ },
433
+ },
434
+ {
435
+ id: "workflow-pin",
436
+ level: "optional",
437
+ run: ({ root, fs, version }) => {
438
+ const row = (status: CheckStatus, evidence: string, extra: Partial<DoctorRow> = {}): DoctorRow => ({ id: "workflow-pin", level: "optional", status, evidence, ...extra });
439
+ const installed = parseTag(version);
440
+ if (root === undefined) return row("skip", "not in a git repository, so no workflow was read");
441
+ const scan = scanWorkflows(root, fs);
442
+ const unreadable = [...(scan.unreadableDir ? [`${scan.unreadableDir} (directory)`] : []), ...scan.unreadable];
443
+ const unreadableNote = unreadable.length > 0 ? `; could not read ${unreadable.join(", ")}, so its pins are unknown` : "";
444
+ const pins = scan.files.flatMap(({ file, refs }) => refs.map((ref) => ({ file, ref })));
445
+ if (pins.length === 0) {
446
+ return unreadable.length > 0
447
+ ? row("warn", `no readable workflow calls a Wachiman reusable workflow${unreadableNote}`, { detail: { unreadable: unreadable.length } })
448
+ : row("skip", "no workflow in .github/workflows calls a Wachiman reusable workflow");
449
+ }
450
+ if (installed === undefined) return row("skip", `the installed version "${version}" is not a release version, so pins cannot be compared`);
451
+ const older = pins.filter((p) => classifyRef(p.ref) === "tag" && compareVersions(parseTag(p.ref)!, installed) < 0);
452
+ const fixed = pins.filter((p) => classifyRef(p.ref) === "tag");
453
+ const other = pins.filter((p) => classifyRef(p.ref) !== "tag");
454
+ const list = (items: typeof pins) => items.map((p) => `${p.file} @${classifyRef(p.ref) === "sha" ? p.ref.slice(0, 12) : p.ref}`).join(", ");
455
+ const detail = { pins: pins.length, older: older.length, notReleaseTag: other.length, unreadable: unreadable.length };
456
+ if (older.length > 0) {
457
+ return row("warn", `${list(older)} older than the installed v${version}: reviews in Actions run that older release${unreadableNote}`, {
458
+ fix: "wachiman upgrade --repo-only",
459
+ detail,
460
+ });
461
+ }
462
+ const note = (other.length > 0 ? `; ${list(other)} is a commit or branch, which is not compared` : "") + unreadableNote;
463
+ if (fixed.length === 0) return row(unreadable.length > 0 ? "warn" : "skip", `${list(other)} is a commit or branch, not a release tag, so it is not compared${unreadableNote}`, { detail });
464
+ return row(unreadable.length > 0 ? "warn" : "ok", `${list(fixed)} is not older than the installed v${version}${note}`, { detail });
465
+ },
466
+ },
362
467
  {
363
468
  id: "history",
364
469
  level: "optional",
package/src/doctor/run.ts CHANGED
@@ -9,7 +9,7 @@ import { confirmProfile, type ConfirmIo, type SpawnFn } from "../accounts/confir
9
9
  import { buildProfileList, managedDir } from "../accounts/profile-list";
10
10
  import { parseProfileRef, resolveProfile } from "../accounts/resolve";
11
11
  import { UsageError } from "../config";
12
- import { type GitRunner } from "../evidence";
12
+ import { spawnGit, type GitRunner } from "../evidence";
13
13
  import { parseFlags } from "../flags";
14
14
  import { repositoryKey } from "../history/store";
15
15
  import { CHECKS, detectInstall, PROFILE_SCOPED, realDoctorFs, tierOf, type DoctorContext, type DoctorFs, type DoctorReport, type InstallKind, type Target } from "./checks";
@@ -76,6 +76,12 @@ export function buildDoctorReport(opts: DoctorOptions, env: Record<string, strin
76
76
  } catch {
77
77
  repository = { ok: false, reason: `${opts.repoDir} is not a git repository` };
78
78
  }
79
+ // Where `.wachiman.yml` is looked for: the top of the working tree (a linked worktree has its own copy).
80
+ const top = (deps.git ?? spawnGit)(["rev-parse", "--show-toplevel"], { cwd: opts.repoDir, timeoutMs: 15_000 });
81
+ const root = top.status === 0 && top.stdout.trim() !== "" ? top.stdout.trim() : undefined;
82
+ // Runs read the committed file, so an edit not committed yet does not apply to them.
83
+ const pending = root === undefined ? undefined : (deps.git ?? spawnGit)(["status", "--porcelain", "--", ".wachiman.yml"], { cwd: root, timeoutMs: 15_000 });
84
+ const settingsUncommitted = pending !== undefined && pending.status === 0 && pending.stdout.trim() !== "";
79
85
  const binding =
80
86
  repository.ok && accounts && Object.hasOwn(accounts.projects, repository.value.key) ? accounts.projects[repository.value.key] : undefined;
81
87
 
@@ -111,6 +117,8 @@ export function buildDoctorReport(opts: DoctorOptions, env: Record<string, strin
111
117
  arch,
112
118
  config,
113
119
  repository,
120
+ root,
121
+ settingsUncommitted,
114
122
  primary,
115
123
  };
116
124