@cbartens/bkit 5.3.0 → 5.4.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 (128) hide show
  1. package/.bkit/README.md +3 -2
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +8 -2
  4. package/.bkit/core/.bkit/README.md +2 -1
  5. package/.bkit/core/.bkit/cloud.md +33 -33
  6. package/.bkit/core/.bkit/comparison.md +1 -1
  7. package/.bkit/core/.bkit/install.md +6 -5
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +4 -3
  10. package/.bkit/core/.bkit/prompts.md +4 -3
  11. package/.bkit/core/.bkit/providers.md +1 -1
  12. package/.bkit/core/.bkit/templates.md +35 -5
  13. package/.bkit/core/.bkit/trackers.md +7 -8
  14. package/.bkit/core/.bkit/workflows.md +106 -86
  15. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  16. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  17. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  25. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  26. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  30. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  32. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  34. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  36. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  38. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  39. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  40. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  43. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  44. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  47. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  48. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  49. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  50. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  51. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
  52. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  53. package/.bkit/core/engine/cli.ts +22 -15
  54. package/.bkit/core/engine/commands/comply.ts +25 -16
  55. package/.bkit/core/engine/commands/install/install.ts +11 -4
  56. package/.bkit/core/engine/commands/land.ts +156 -0
  57. package/.bkit/core/engine/commands/lib.ts +10 -8
  58. package/.bkit/core/engine/commands/registry.ts +2 -0
  59. package/.bkit/core/engine/commands/tips.ts +7 -3
  60. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  61. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  62. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  63. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  64. package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
  65. package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
  66. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  67. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  68. package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
  69. package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
  70. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  71. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  72. package/.bkit/core/engine/install/modules/core.ts +15 -0
  73. package/.bkit/core/engine/install/placeholders.ts +13 -17
  74. package/.bkit/core/engine/shared/settings.ts +8 -0
  75. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  76. package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
  77. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
  78. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
  79. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
  80. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
  81. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
  82. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
  83. package/.bkit/core/workflows/bkit-auto.md +2 -2
  84. package/.bkit/core/workflows/bkit-build.md +7 -7
  85. package/.bkit/core/workflows/bkit-debug.md +11 -11
  86. package/.bkit/core/workflows/bkit-design.md +20 -11
  87. package/.bkit/core/workflows/bkit-plan.md +23 -13
  88. package/.bkit/core/workflows/bkit-ship.md +82 -93
  89. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  90. package/.bkit/shared/.claude/settings.json +1 -0
  91. package/.bkit/shared/docs/deployments.md +29 -25
  92. package/.bkit/shared/gitignore +1 -2
  93. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  94. package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
  95. package/.bkit/templates/.husky/pre-commit +6 -0
  96. package/.bkit/templates/.husky/pre-push +7 -0
  97. package/.bkit/templates/.lintstagedrc.json +5 -1
  98. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  99. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  100. package/CHANGELOG.md +48 -0
  101. package/README.md +97 -96
  102. package/dist/checks/status-holes.js +0 -1
  103. package/dist/checks/tips/catalogue.js +14 -0
  104. package/dist/checks/tips/index.js +44 -28
  105. package/dist/cli.js +22 -16
  106. package/dist/commands/comply.js +20 -13
  107. package/dist/commands/install/install.js +10 -4
  108. package/dist/commands/land.js +129 -0
  109. package/dist/commands/lib.js +9 -6
  110. package/dist/commands/registry.js +2 -0
  111. package/dist/commands/tips.js +7 -3
  112. package/dist/commands/workflow/branches.js +300 -243
  113. package/dist/commands/workflow/disk.js +452 -0
  114. package/dist/commands/workflow/issues.js +63 -27
  115. package/dist/commands/workflow/locks.js +35 -130
  116. package/dist/commands/workflow/prs.js +5 -2
  117. package/dist/commands/workflow/roadmap.js +49 -56
  118. package/dist/commands/workflow/runtime.js +3 -2
  119. package/dist/commands/workflow/status.js +32 -12
  120. package/dist/commands/workflow/steps.js +18 -11
  121. package/dist/commands/workflow/workflows.js +388 -247
  122. package/dist/commands/workflow/workstreams.js +3 -2
  123. package/dist/commands/workflow/worktrees.js +11 -1
  124. package/dist/install/modules/core.js +13 -0
  125. package/dist/install/placeholders.js +13 -19
  126. package/dist/shared/settings.js +5 -0
  127. package/dist/shared/timeouts.js +8 -7
  128. package/package.json +1 -1
@@ -1,6 +1,6 @@
1
1
  // bkit roadmap fold|feature|mirror — rewrite the generated region of
2
2
  // docs/roadmap.md from .bkit/issues.jsonl, its SOLE input; append a feature's
3
- // row; and copy a build / debug close's row to dev under the dev lock.
3
+ // row; and copy a build / debug close's row to dev through a throwaway checkout.
4
4
  //
5
5
  // The status block is a pure projection of the ledger, re-rendered in full, so
6
6
  // a close never parses the board back. The two `## Notes` blocks and the
@@ -31,7 +31,7 @@ import {
31
31
  type CommandSpec,
32
32
  type RunContext,
33
33
  } from "../lib.js";
34
- import { acquireDevLock, releaseLock } from "./locks.js";
34
+ import { landDir, pushToDev } from "../land.js";
35
35
  import { str } from "./status.js";
36
36
 
37
37
  /** Roadmap status each workflow's close moves the feature to. */
@@ -414,17 +414,14 @@ function feature(ctx: RunContext): number {
414
414
  return ctx.flags.strict === true && !r.appended ? EXIT.NO : EXIT.OK;
415
415
  }
416
416
 
417
- /** Seconds the mirror waits for a busy dev lock before skipping. */
418
- export const MIRROR_DEV_LOCK_DEADLINE_S = 60;
419
-
420
417
  const ROADMAP_FILES = [".bkit/issues.jsonl", "docs/roadmap.md"];
421
418
 
422
419
  /**
423
- * Build / debug close: append the feature row in the worktree, then copy the
424
- * SAME row to `dev` in the main checkout under the dev lock — checkout dev,
425
- * fast-forward, append, commit the two roadmap files, push, return to the prior
426
- * branch. Skipped in adopt mode (the worktree IS the main checkout) and when the
427
- * dev lock stays busy. Fail-open throughout: the feat-side row is already written.
420
+ * Build / debug close: append the feature row in the worktree, then land the
421
+ * SAME row on `dev` through a throwaway origin/dev checkout (`pushToDev`). The
422
+ * main checkout is never touched. Skipped when the run's own checkout is on dev
423
+ * (the row rides that branch's commit). Fail-open throughout: the feat-side row
424
+ * is already written and reaches dev with ship's merge.
428
425
  */
429
426
  async function mirror(ctx: RunContext): Promise<number> {
430
427
  const workflow = String(ctx.flags.workflow);
@@ -438,47 +435,45 @@ async function mirror(ctx: RunContext): Promise<number> {
438
435
  ctx.emit({ row: feat.row, appended: feat.appended, mirrored, skipped });
439
436
  return EXIT.OK;
440
437
  };
441
- if (path.resolve(wt) === path.resolve(root)) return done(false, "adopt mode");
442
-
443
- let lock: { path: string; token: string };
444
- try {
445
- lock = await acquireDevLock({
446
- cwd: root,
447
- workflow,
448
- fid,
449
- deadlineS: MIRROR_DEV_LOCK_DEADLINE_S,
450
- log: ctx.log,
451
- });
452
- } catch (err) {
453
- // A busy lock skips the mirror; it never fails the close.
454
- return done(false, `dev lock busy: ${(err as Error).message}`);
455
- }
456
- try {
457
- const prior = git(root, ["branch", "--show-current"]) ?? "";
458
- if (
459
- !runGit(root, ["checkout", DEV]).ok ||
460
- !runGit(root, ["pull", "--ff-only", "origin", DEV]).ok
461
- ) {
462
- if (prior) runGit(root, ["checkout", prior]);
463
- return done(false, "dev checkout / pull failed");
464
- }
465
- const onDev = appendFeature(root, { row: JSON.stringify(feat.row) }, ctx.log);
466
- if (!onDev.appended) ctx.log("roadmap row skipped on dev");
467
- runGit(root, ["add", "--", ...ROADMAP_FILES]);
468
- runGit(root, [
469
- "commit",
470
- "--allow-empty",
471
- "-m",
472
- `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
473
- "--",
474
- ...ROADMAP_FILES,
475
- ]);
476
- const pushed = runGit(root, ["push", "origin", DEV]).ok;
477
- if (!pushed) ctx.log("dev push failed — feat-side row already written");
478
- if (prior) runGit(root, ["checkout", prior]);
479
- return done(pushed, pushed ? null : "dev push failed");
480
- } finally {
481
- releaseLock(lock.path, { workflow, fid, token: lock.token });
438
+ if (git(wt, ["branch", "--show-current"]) === DEV) return done(false, "on dev");
439
+
440
+ // A build that commits nothing pushes origin/dev back to itself, which git
441
+ // reports as success — so a landing counts only when this attempt committed.
442
+ let committed = "";
443
+ const res = await pushToDev({
444
+ root,
445
+ dir: landDir(root, fid),
446
+ build: (dir) => {
447
+ committed = "";
448
+ if (!appendFeature(dir, { row: JSON.stringify(feat.row) }, ctx.log).appended) {
449
+ committed = "row not appended on dev";
450
+ return;
451
+ }
452
+ runGit(dir, ["add", "--", ...ROADMAP_FILES]);
453
+ const made = runGit(dir, [
454
+ "commit",
455
+ "-m",
456
+ `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
457
+ "--",
458
+ ...ROADMAP_FILES,
459
+ ]);
460
+ if (!made.ok) committed = `roadmap commit failed: ${made.stderr || made.stdout}`;
461
+ },
462
+ log: ctx.log,
463
+ });
464
+ switch (res.kind) {
465
+ case "landed":
466
+ return committed ? done(false, committed) : done(true, null);
467
+ case "refused":
468
+ return done(false, `dev push refused: ${res.stderr}`);
469
+ case "push-failed":
470
+ return done(false, `dev push failed: ${res.stderr}`);
471
+ case "exhausted":
472
+ return done(false, `dev moved before each of ${res.attempts} pushes`);
473
+ case "fetch-failed":
474
+ return done(false, `fetch of dev failed: ${res.stderr}`);
475
+ case "setup-failed":
476
+ return done(false, `throwaway checkout failed: ${res.stderr}`);
482
477
  }
483
478
  }
484
479
 
@@ -559,7 +554,7 @@ export const roadmapCommand: CommandSpec = {
559
554
  },
560
555
  mirror: {
561
556
  summary:
562
- "Build / debug close: append the feature row in the worktree, then the same row on dev under the dev lock (fail-open).",
557
+ "Build / debug close: append the feature row in the worktree, then land the same row on dev through a throwaway origin/dev checkout (fail-open).",
563
558
  flags: [
564
559
  { name: "workflow", type: "string", required: true, help: "build | debug" },
565
560
  { name: "fid", type: "string", required: true, help: "feature id (the row's key)" },
@@ -569,7 +564,7 @@ export const roadmapCommand: CommandSpec = {
569
564
  appended: "false when the worktree ledger could not be written",
570
565
  mirrored: "the row was committed and pushed on dev",
571
566
  skipped:
572
- "why the dev side was skipped: adopt mode | dev lock busy | dev checkout / pull failed | dev push failed (null when mirrored)",
567
+ "why the dev side was skipped: on dev | row not appended on dev | dev push refused | dev moved before each push | fetch of dev failed | throwaway checkout failed (null when mirrored)",
573
568
  },
574
569
  run: (ctx) => mirror(ctx),
575
570
  },
@@ -106,8 +106,9 @@ export function classify(env: NodeJS.ProcessEnv, root: string, log: (m: string)
106
106
 
107
107
  /**
108
108
  * Default capabilities per runtime. CLOUD_CURSOR matches GITHUB_ACTION on
109
- * purpose (isolated VM, real git, mints and pushes its own branch); a claude.ai
110
- * session's proxy only lets it push the current branch, so it gets neither.
109
+ * purpose (isolated VM, real git, mints and pushes its own branch). A claude.ai
110
+ * session gets neither: whether it may push dev can't be tested without making
111
+ * that push, and a wrong guess strands the session on a dev checkout.
111
112
  */
112
113
  const capable = (runtime: Runtime) =>
113
114
  runtime === "LOCAL" || runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR";
@@ -19,6 +19,7 @@ import {
19
19
  import {
20
20
  CommandError,
21
21
  EXIT,
22
+ git,
22
23
  parseJson,
23
24
  statusLocation,
24
25
  type CommandSpec,
@@ -58,20 +59,43 @@ export const SUB_PLAN_FLAG: FlagSpec = {
58
59
  /** Exit code: status.jsonl missing, unreadable, or not valid NDJSON. */
59
60
  export const EXIT_NO_STATUS = 3;
60
61
 
61
- /** Parse every line of `status.jsonl`. Missing, unreadable or malformed is an error, never "no rows". */
62
62
  /** Every row of status.jsonl, whatever its type; exit 3 when the file is missing or a line is not JSON. */
63
63
  export function readStatusRows(file: string): StatusRow[] {
64
64
  if (!fs.existsSync(file)) throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
65
- return fs
66
- .readFileSync(file, "utf-8")
65
+ return parseStatusRows(fs.readFileSync(file, "utf-8"), file);
66
+ }
67
+
68
+ /**
69
+ * The rows of status.jsonl as committed on `ref`, not as on disk: exit 3 when
70
+ * the ref does not carry the file. `file` need not exist; the repo is the one
71
+ * holding its nearest existing parent directory.
72
+ */
73
+ export function readStatusRowsAt(file: string, ref: string): StatusRow[] {
74
+ let dir = path.dirname(file);
75
+ while (!fs.existsSync(dir) && path.dirname(dir) !== dir) dir = path.dirname(dir);
76
+ const top = git(dir, ["rev-parse", "--show-toplevel"]);
77
+ if (top === null) throw new CommandError(EXIT_NO_STATUS, `${file} is not inside a git repo`);
78
+ const rel = path
79
+ .relative(fs.realpathSync(top), path.join(fs.realpathSync(dir), path.relative(dir, file)))
80
+ .split(path.sep)
81
+ .join("/");
82
+ const spec = `${ref}:${rel}`;
83
+ const text = git(top, ["show", spec]);
84
+ if (text === null) throw new CommandError(EXIT_NO_STATUS, `${spec} does not exist`);
85
+ return parseStatusRows(text, spec);
86
+ }
87
+
88
+ /** Parse NDJSON status text; `label` names it in errors. Malformed is an error, never "no rows". */
89
+ function parseStatusRows(text: string, label: string): StatusRow[] {
90
+ return text
67
91
  .split("\n")
68
92
  .map((l) => l.trim())
69
93
  .filter((l) => l !== "")
70
94
  .map((l, i) => {
71
95
  const parsed = parseJson(l);
72
- if (!parsed.ok) throw new CommandError(EXIT_NO_STATUS, `${file} line ${i + 1} is not JSON`);
96
+ if (!parsed.ok) throw new CommandError(EXIT_NO_STATUS, `${label} line ${i + 1} is not JSON`);
73
97
  if (typeof parsed.value !== "object" || parsed.value === null) {
74
- throw new CommandError(EXIT_NO_STATUS, `${file} line ${i + 1} is not a JSON object`);
98
+ throw new CommandError(EXIT_NO_STATUS, `${label} line ${i + 1} is not a JSON object`);
75
99
  }
76
100
  return parsed.value as StatusRow;
77
101
  });
@@ -83,6 +107,10 @@ export const readStatusEvents = (file: string): StatusEvent[] =>
83
107
 
84
108
  export const readRuns = (file: string): WorkflowRun[] => fold(readStatusEvents(file));
85
109
 
110
+ /** The runs as committed on `ref` (see readStatusRowsAt). */
111
+ export const readRunsAt = (file: string, ref: string): WorkflowRun[] =>
112
+ fold(readStatusRowsAt(file, ref) as StatusEvent[]);
113
+
86
114
  /** `--file`, resolved against the command's working directory. */
87
115
  export const statusFile = (ctx: RunContext) => path.resolve(ctx.cwd, String(ctx.flags.file));
88
116
 
@@ -242,11 +270,6 @@ export const statusCommand: CommandSpec = {
242
270
  WORKFLOW_FLAG,
243
271
  { name: "fid", type: "string", required: true, help: "feature id" },
244
272
  { name: "month", type: "string", required: true, help: "month bucket, YYYYMM" },
245
- {
246
- name: "dev-pushes",
247
- type: "boolean",
248
- help: "ship only: this runtime pushes to dev (RUNTIME_DEVPUSHES=true)",
249
- },
250
273
  ],
251
274
  output: {
252
275
  path: "absolute path to status.jsonl",
@@ -261,7 +284,6 @@ export const statusCommand: CommandSpec = {
261
284
  workflow: String(ctx.flags.workflow),
262
285
  fid: String(ctx.flags.fid),
263
286
  month,
264
- devPushes: ctx.flags.devPushes === true,
265
287
  });
266
288
  ctx.emit({ ...loc, exists: fs.existsSync(loc.path) });
267
289
  return EXIT.OK;
@@ -35,7 +35,7 @@ import {
35
35
  } from "../lib.js";
36
36
  import { FID_PATTERNS, readIssueTracker } from "./fids.js";
37
37
  import { buildComment } from "./issues.js";
38
- import { lockRoot, readHolder, resolveMonth, workflowLockPath } from "./locks.js";
38
+ import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
39
39
  import {
40
40
  EXIT_NO_STATUS,
41
41
  FILE_FLAG,
@@ -46,6 +46,7 @@ import {
46
46
  nonNegativeInt,
47
47
  positiveInt,
48
48
  readRuns,
49
+ readRunsAt,
49
50
  statusFile,
50
51
  str,
51
52
  } from "./status.js";
@@ -422,6 +423,8 @@ export interface Check {
422
423
 
423
424
  interface GateOptions {
424
425
  file?: string;
426
+ /** Read `file` as committed on this ref instead of from disk. */
427
+ ref?: string;
425
428
  workflow: string;
426
429
  step: string;
427
430
  subPlan?: number;
@@ -432,7 +435,6 @@ interface GateOptions {
432
435
  fid?: string;
433
436
  month?: string;
434
437
  token?: string;
435
- devPushes?: boolean;
436
438
  placeholders: string[];
437
439
  }
438
440
 
@@ -463,11 +465,8 @@ function gateChecks(cwd: string, o: GateOptions): Check[] {
463
465
  `${tracker} shape`,
464
466
  );
465
467
  if (o.token !== undefined) {
466
- const lock = workflowLockPath(
467
- lockRoot(cwd, o.workflow, o.devPushes === true),
468
- resolveMonth(repoRoot(cwd), o.fid, o.month),
469
- o.fid,
470
- );
468
+ const root = repoRoot(cwd);
469
+ const lock = workflowLockPath(root, resolveMonth(root, o.fid, o.month), o.fid);
471
470
  const holder = readHolder(lock);
472
471
  add(
473
472
  "workflow lock",
@@ -513,7 +512,8 @@ function gateChecks(cwd: string, o: GateOptions): Check[] {
513
512
  }
514
513
 
515
514
  if (o.file === undefined) return checks;
516
- const rows = activeDoneSteps(readRuns(o.file), o.workflow, { step: o.step, subPlan: o.subPlan });
515
+ const runs = o.ref === undefined ? readRuns(o.file) : readRunsAt(o.file, o.ref);
516
+ const rows = activeDoneSteps(runs, o.workflow, { step: o.step, subPlan: o.subPlan });
517
517
  const row = rows.filter((r) => o.attempt === undefined || r.attempt === o.attempt).at(-1);
518
518
  const rowProblems: string[] = [];
519
519
  if (!row) {
@@ -1187,6 +1187,11 @@ export const stepsCommand: CommandSpec = {
1187
1187
  required: false,
1188
1188
  help: "path to status.jsonl; without it the status row is not checked (Step 1)",
1189
1189
  },
1190
+ {
1191
+ name: "ref",
1192
+ type: "string",
1193
+ help: "read --file as committed on this ref (e.g. origin/dev), not from disk",
1194
+ },
1190
1195
  WORKFLOW_FLAG,
1191
1196
  STEP_FLAG,
1192
1197
  SUB_PLAN_FLAG,
@@ -1225,15 +1230,11 @@ export const stepsCommand: CommandSpec = {
1225
1230
  type: "string",
1226
1231
  help: "the workflow lock must be held with this token (needs --fid)",
1227
1232
  },
1228
- {
1229
- name: "dev-pushes",
1230
- type: "boolean",
1231
- help: "ship only: the lock lives in the main checkout",
1232
- },
1233
1233
  ],
1234
1234
  output: { pass: "true when every check passed", checks: "[{check, ok, detail}] per check" },
1235
1235
  exitCodes: {
1236
- [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON",
1236
+ [EXIT_NO_STATUS]:
1237
+ "status.jsonl missing (on disk, or on --ref), unreadable, or not valid NDJSON",
1237
1238
  },
1238
1239
  run: (ctx) => {
1239
1240
  const f = ctx.flags;
@@ -1244,12 +1245,21 @@ export const stepsCommand: CommandSpec = {
1244
1245
  throw new CommandError(EXIT.USAGE, "give --attempt or --attempt-of, not both");
1245
1246
  if (f.attemptOf !== undefined && file === undefined)
1246
1247
  throw new CommandError(EXIT.USAGE, "--attempt-of needs --file");
1248
+ const ref = str(f.ref);
1249
+ if (ref !== undefined && file === undefined)
1250
+ throw new CommandError(EXIT.USAGE, "--ref needs --file");
1251
+ if (ref !== undefined && f.attemptOf !== undefined)
1252
+ throw new CommandError(
1253
+ EXIT.USAGE,
1254
+ "--attempt-of reads the file on disk; give --attempt with --ref",
1255
+ );
1247
1256
  const attempt =
1248
1257
  f.attemptOf !== undefined
1249
1258
  ? derivedCounter(file!, workflow, String(f.attemptOf), subPlan, undefined)
1250
1259
  : nonNegativeInt(f.attempt, "attempt");
1251
1260
  const checks = gateChecks(ctx.cwd, {
1252
1261
  file,
1262
+ ref,
1253
1263
  workflow,
1254
1264
  step: String(f.step),
1255
1265
  subPlan,
@@ -1260,7 +1270,6 @@ export const stepsCommand: CommandSpec = {
1260
1270
  fid: str(f.fid),
1261
1271
  month: str(f.month),
1262
1272
  token: str(f.token),
1263
- devPushes: f.devPushes === true,
1264
1273
  placeholders: list(f.placeholder),
1265
1274
  });
1266
1275
  const pass = checks.every((c) => c.ok);