@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.
- package/.bkit/README.md +3 -2
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/rules.md +8 -2
- package/.bkit/core/.bkit/README.md +2 -1
- package/.bkit/core/.bkit/cloud.md +33 -33
- package/.bkit/core/.bkit/comparison.md +1 -1
- package/.bkit/core/.bkit/install.md +6 -5
- package/.bkit/core/.bkit/lite.md +6 -6
- package/.bkit/core/.bkit/pipeline.md +4 -3
- package/.bkit/core/.bkit/prompts.md +4 -3
- package/.bkit/core/.bkit/providers.md +1 -1
- package/.bkit/core/.bkit/templates.md +35 -5
- package/.bkit/core/.bkit/trackers.md +7 -8
- package/.bkit/core/.bkit/workflows.md +106 -86
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
- package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/engine/checks/status-holes.ts +0 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
- package/.bkit/core/engine/checks/tips/index.ts +49 -27
- package/.bkit/core/engine/cli.ts +22 -15
- package/.bkit/core/engine/commands/comply.ts +25 -16
- package/.bkit/core/engine/commands/install/install.ts +11 -4
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +10 -8
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +7 -3
- package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
- package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
- package/.bkit/core/engine/commands/workflow/status.ts +33 -11
- package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
- package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
- package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
- package/.bkit/core/engine/install/modules/core.ts +15 -0
- package/.bkit/core/engine/install/placeholders.ts +13 -17
- package/.bkit/core/engine/shared/settings.ts +8 -0
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
- package/.bkit/core/workflows/bkit-auto.md +2 -2
- package/.bkit/core/workflows/bkit-build.md +7 -7
- package/.bkit/core/workflows/bkit-debug.md +11 -11
- package/.bkit/core/workflows/bkit-design.md +20 -11
- package/.bkit/core/workflows/bkit-plan.md +23 -13
- package/.bkit/core/workflows/bkit-ship.md +82 -93
- package/.bkit/shared/.claude/bkit-cloud.md +12 -12
- package/.bkit/shared/.claude/settings.json +1 -0
- package/.bkit/shared/docs/deployments.md +29 -25
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
- package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
- package/.bkit/templates/.husky/pre-commit +6 -0
- package/.bkit/templates/.husky/pre-push +7 -0
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
- package/CHANGELOG.md +48 -0
- package/README.md +97 -96
- package/dist/checks/status-holes.js +0 -1
- package/dist/checks/tips/catalogue.js +14 -0
- package/dist/checks/tips/index.js +44 -28
- package/dist/cli.js +22 -16
- package/dist/commands/comply.js +20 -13
- package/dist/commands/install/install.js +10 -4
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +9 -6
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +300 -243
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/issues.js +63 -27
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +5 -2
- package/dist/commands/workflow/roadmap.js +49 -56
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +18 -11
- package/dist/commands/workflow/workflows.js +388 -247
- package/dist/commands/workflow/workstreams.js +3 -2
- package/dist/commands/workflow/worktrees.js +11 -1
- package/dist/install/modules/core.js +13 -0
- package/dist/install/placeholders.js +13 -19
- package/dist/shared/settings.js +5 -0
- package/dist/shared/timeouts.js +8 -7
- package/package.json +1 -1
|
@@ -154,7 +154,17 @@ function textVerb(ctx: RunContext): number {
|
|
|
154
154
|
// ---------------------------------------------------------------------------
|
|
155
155
|
|
|
156
156
|
/** Mutually exclusive: setting one drops the others. */
|
|
157
|
-
export const PHASE_LABELS = [
|
|
157
|
+
export const PHASE_LABELS = [
|
|
158
|
+
"bkit:design",
|
|
159
|
+
"bkit:plan",
|
|
160
|
+
"bkit:build",
|
|
161
|
+
"bkit:debug",
|
|
162
|
+
"bkit:ship",
|
|
163
|
+
"bkit:merged",
|
|
164
|
+
];
|
|
165
|
+
|
|
166
|
+
/** Prefix of the labels naming an issue's next best workflow; setting a phase drops them. */
|
|
167
|
+
export const NEXT_LABEL_PREFIX = "next:";
|
|
158
168
|
|
|
159
169
|
/** The issue label that opts a feature into CI auto-routing. */
|
|
160
170
|
export const AUTO_LABEL = "bkit:auto";
|
|
@@ -164,7 +174,6 @@ export const AUTO_ROUTE_SUFFIX = " bkit [auto route]";
|
|
|
164
174
|
export interface LabelTransition {
|
|
165
175
|
phase?: string;
|
|
166
176
|
failed?: boolean;
|
|
167
|
-
debug?: boolean;
|
|
168
177
|
}
|
|
169
178
|
|
|
170
179
|
export function transitionLabels(current: string[], t: LabelTransition) {
|
|
@@ -178,10 +187,12 @@ export function transitionLabels(current: string[], t: LabelTransition) {
|
|
|
178
187
|
if (t.phase !== undefined) {
|
|
179
188
|
const label = `bkit:${t.phase}`;
|
|
180
189
|
for (const l of have) if (PHASE_LABELS.includes(l) && l !== label) remove.add(l);
|
|
190
|
+
for (const l of have) if (l.startsWith(NEXT_LABEL_PREFIX)) remove.add(l);
|
|
181
191
|
want(label, true);
|
|
182
192
|
}
|
|
183
|
-
|
|
184
|
-
|
|
193
|
+
// A phase starting supersedes any earlier Failure Path.
|
|
194
|
+
const failed = t.failed ?? (t.phase !== undefined ? false : undefined);
|
|
195
|
+
if (failed !== undefined) want("bkit:failed", failed);
|
|
185
196
|
return {
|
|
186
197
|
add,
|
|
187
198
|
remove: [...remove],
|
|
@@ -191,11 +202,11 @@ export function transitionLabels(current: string[], t: LabelTransition) {
|
|
|
191
202
|
|
|
192
203
|
/**
|
|
193
204
|
* Linear's issue state for the same transition, as the workflows set it: a
|
|
194
|
-
* shipped
|
|
205
|
+
* shipped or failed issue waits on a human ("In Review"); a phase
|
|
195
206
|
* starting is "In Progress". Null when the transition sets no state.
|
|
196
207
|
*/
|
|
197
208
|
export function linearState(t: LabelTransition, board: string | undefined): string | null {
|
|
198
|
-
if (t.phase === "merged" || t.failed === true
|
|
209
|
+
if (t.phase === "merged" || t.failed === true) return "In Review";
|
|
199
210
|
if (t.phase !== undefined) return "In Progress";
|
|
200
211
|
if (board === "review") return "In Review";
|
|
201
212
|
if (board === "progress") return "In Progress";
|
|
@@ -288,21 +299,19 @@ function boardPayload(
|
|
|
288
299
|
function labelsVerb(ctx: RunContext): number {
|
|
289
300
|
const phase = str(ctx.flags.phase);
|
|
290
301
|
if (phase !== undefined && !PHASE_LABELS.includes(`bkit:${phase}`)) {
|
|
291
|
-
throw new CommandError(
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
// A merged issue must not keep a stale Failure Path marker.
|
|
296
|
-
if (phase === "merged") {
|
|
297
|
-
if (failed === true)
|
|
298
|
-
throw new CommandError(EXIT.USAGE, "--phase=merged clears bkit:failed; drop --failed=on");
|
|
299
|
-
failed = false;
|
|
302
|
+
throw new CommandError(
|
|
303
|
+
EXIT.USAGE,
|
|
304
|
+
"--phase must be design, plan, build, debug, ship, or merged",
|
|
305
|
+
);
|
|
300
306
|
}
|
|
307
|
+
const failed = onOff(ctx.flags.failed, "failed");
|
|
308
|
+
if (phase !== undefined && failed === true)
|
|
309
|
+
throw new CommandError(EXIT.USAGE, "--phase clears bkit:failed; drop --failed=on");
|
|
301
310
|
const board = str(ctx.flags.board);
|
|
302
311
|
if (board !== undefined && BOARD_OPTION[board] === undefined) {
|
|
303
312
|
throw new CommandError(EXIT.USAGE, "--board must be progress or review");
|
|
304
313
|
}
|
|
305
|
-
const t: LabelTransition = { phase, failed
|
|
314
|
+
const t: LabelTransition = { phase, failed };
|
|
306
315
|
const { add, remove, labels } = transitionLabels(
|
|
307
316
|
(ctx.flags.label as string[] | undefined) ?? [],
|
|
308
317
|
t,
|
|
@@ -383,7 +392,9 @@ function fenced(text: string): string {
|
|
|
383
392
|
|
|
384
393
|
/** Everything one `###### bkit:generated` comment is built from. */
|
|
385
394
|
export interface CommentInput {
|
|
386
|
-
kind?: "step" | "failure" | "handover";
|
|
395
|
+
kind?: "step" | "failure" | "handover" | "audit";
|
|
396
|
+
/** Audit: the template slug in `### Audit Summary: <slug>`. */
|
|
397
|
+
auditSlug?: string;
|
|
387
398
|
/** With `workflowHeading`: Step 1 puts `## <Workflow>` above the step. */
|
|
388
399
|
workflow?: string;
|
|
389
400
|
workflowHeading?: boolean;
|
|
@@ -401,7 +412,7 @@ export interface CommentInput {
|
|
|
401
412
|
prNumber?: string;
|
|
402
413
|
prUrl?: string;
|
|
403
414
|
runId?: string;
|
|
404
|
-
/** Repo paths linked at `ref` (default `tree`). */
|
|
415
|
+
/** Repo paths linked at `ref` (default `tree`); `path#Heading` links that section. */
|
|
405
416
|
artifacts?: string[];
|
|
406
417
|
ref?: string;
|
|
407
418
|
lines?: string[];
|
|
@@ -429,13 +440,37 @@ function links(o: CommentInput): string[] {
|
|
|
429
440
|
if (artifacts.length) {
|
|
430
441
|
const ref = o.ref ?? o.tree;
|
|
431
442
|
if (ref === undefined) throw new CommandError(EXIT.USAGE, "--artifact needs --ref (or --tree)");
|
|
432
|
-
for (const a of artifacts)
|
|
433
|
-
|
|
443
|
+
for (const a of artifacts) {
|
|
444
|
+
const hash = a.indexOf("#");
|
|
445
|
+
const file = (hash < 0 ? a : a.slice(0, hash)).replace(/^\/+/, "");
|
|
446
|
+
const heading = hash < 0 ? undefined : a.slice(hash + 1).trim();
|
|
447
|
+
if (heading === "")
|
|
448
|
+
throw new CommandError(EXIT.USAGE, `--artifact "${a}" has an empty #Heading`);
|
|
449
|
+
const url = `${gh}/blob/${ref}/${file}`;
|
|
450
|
+
out.push(
|
|
451
|
+
heading === undefined
|
|
452
|
+
? `[${path.basename(file)}](${url})`
|
|
453
|
+
: `[${path.basename(file)} § ${heading}](${url}#${headingAnchor(heading)})`,
|
|
454
|
+
);
|
|
455
|
+
}
|
|
434
456
|
}
|
|
435
457
|
return out;
|
|
436
458
|
}
|
|
437
459
|
|
|
438
|
-
|
|
460
|
+
/**
|
|
461
|
+
* GitHub's anchor for a markdown heading: lowercased, punctuation dropped,
|
|
462
|
+
* spaces to hyphens. A repeated heading's later copies take `-1`, `-2`; this
|
|
463
|
+
* names the first.
|
|
464
|
+
*/
|
|
465
|
+
export function headingAnchor(heading: string): string {
|
|
466
|
+
return heading
|
|
467
|
+
.trim()
|
|
468
|
+
.toLowerCase()
|
|
469
|
+
.replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, "")
|
|
470
|
+
.replace(/ /g, "-");
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
const KINDS = ["step", "failure", "handover", "audit"];
|
|
439
474
|
|
|
440
475
|
/** The exact comment body; files (`bodyFile`, `sections`, `stderrFile`, `errorFile`) resolve against `cwd`. */
|
|
441
476
|
export function buildComment(cwd: string, o: CommentInput): string {
|
|
@@ -490,6 +525,14 @@ export function buildComment(cwd: string, o: CommentInput): string {
|
|
|
490
525
|
const captured = tail(readInput(cwd, o.stderrFile, "stderr-file"), 20);
|
|
491
526
|
if (captured.trim() !== "") lines.push("Stderr:", fenced(captured));
|
|
492
527
|
}
|
|
528
|
+
} else if (kind === "audit") {
|
|
529
|
+
const slug = o.auditSlug;
|
|
530
|
+
if (slug === undefined || !/^[a-z0-9-]+$/.test(slug)) {
|
|
531
|
+
throw new CommandError(EXIT.USAGE, "--kind=audit needs --audit-slug=<template slug>");
|
|
532
|
+
}
|
|
533
|
+
lines.push(
|
|
534
|
+
[`### Audit Summary: ${slug}`, ...(o.fields ?? []).map(([k, v]) => `${k}: ${v}`)].join(" - "),
|
|
535
|
+
);
|
|
493
536
|
} else {
|
|
494
537
|
lines.push("### Workflow Handover");
|
|
495
538
|
}
|
|
@@ -522,11 +565,12 @@ export function commentBody(ctx: RunContext): string {
|
|
|
522
565
|
}
|
|
523
566
|
return buildComment(ctx.cwd, {
|
|
524
567
|
kind: kind as CommentInput["kind"],
|
|
568
|
+
auditSlug: str(ctx.flags.auditSlug),
|
|
525
569
|
workflow: str(ctx.flags.workflow),
|
|
526
570
|
workflowHeading: ctx.flags.workflowHeading === true,
|
|
527
571
|
stepNumber: str(ctx.flags.stepNumber),
|
|
528
572
|
stepTitle: str(ctx.flags.stepTitle),
|
|
529
|
-
fields: kind === "step" ? headerFields(ctx) : [],
|
|
573
|
+
fields: kind === "step" || kind === "audit" ? headerFields(ctx) : [],
|
|
530
574
|
subStep: str(ctx.flags.subStep),
|
|
531
575
|
error: str(ctx.flags.error),
|
|
532
576
|
errorFile: str(ctx.flags.errorFile),
|
|
@@ -578,10 +622,9 @@ export const issuesCommand: CommandSpec = {
|
|
|
578
622
|
{
|
|
579
623
|
name: "phase",
|
|
580
624
|
type: "string",
|
|
581
|
-
help: "set this phase: design | plan | build | ship | merged",
|
|
625
|
+
help: "set this phase: design | plan | build | debug | ship | merged (drops next:* and bkit:failed)",
|
|
582
626
|
},
|
|
583
|
-
{ name: "failed", type: "string", help: "bkit:failed on | off (
|
|
584
|
-
{ name: "debug", type: "string", help: "bkit:debug on | off" },
|
|
627
|
+
{ name: "failed", type: "string", help: "bkit:failed on | off (a phase implies off)" },
|
|
585
628
|
{
|
|
586
629
|
name: "board",
|
|
587
630
|
type: "string",
|
|
@@ -604,9 +647,11 @@ export const issuesCommand: CommandSpec = {
|
|
|
604
647
|
run: labelsVerb,
|
|
605
648
|
},
|
|
606
649
|
comment: {
|
|
607
|
-
summary:
|
|
650
|
+
summary:
|
|
651
|
+
"The exact body of a ###### bkit:generated step, failure, handover, or audit comment.",
|
|
608
652
|
flags: [
|
|
609
|
-
{ name: "kind", type: "string", help: "step (default) | failure | handover" },
|
|
653
|
+
{ name: "kind", type: "string", help: "step (default) | failure | handover | audit" },
|
|
654
|
+
{ name: "audit-slug", type: "string", help: "audit: template slug, e.g. security" },
|
|
610
655
|
{ name: "step-number", type: "string", help: "step number in the heading" },
|
|
611
656
|
{ name: "step-title", type: "string", help: "step title in the heading, e.g. Plan Verify" },
|
|
612
657
|
{ name: "workflow", type: "string", help: "design | plan | build | debug | ship | auto" },
|
|
@@ -637,7 +682,7 @@ export const issuesCommand: CommandSpec = {
|
|
|
637
682
|
name: "artifact",
|
|
638
683
|
type: "string",
|
|
639
684
|
repeatable: true,
|
|
640
|
-
help: "link this repo path at --ref",
|
|
685
|
+
help: "link this repo path at --ref; path#Heading links that section",
|
|
641
686
|
},
|
|
642
687
|
{ name: "ref", type: "string", help: "ref the --artifact links point at (default --tree)" },
|
|
643
688
|
{ name: "line", type: "string", repeatable: true, help: "a raw line after the links" },
|
|
@@ -1,16 +1,13 @@
|
|
|
1
|
-
// bkit locks acquire|release — the per-feature workflow lock
|
|
1
|
+
// bkit locks acquire|release — the per-feature workflow lock.
|
|
2
2
|
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
// dev `.bkit/.dev.lock` in the main checkout: held across every checkout /
|
|
8
|
-
// commit / push of `dev` there. Acquire waits a bounded time; the shell
|
|
9
|
-
// releases it from `trap ... EXIT`.
|
|
3
|
+
// `docs/plans/{month}/logs/{fid}/.lock` in the main checkout: one phase workflow
|
|
4
|
+
// per feature at a time. A lock left behind is reclaimed as soon as its holder is
|
|
5
|
+
// idle: its run is not IN_PROGRESS, or stepped no sooner than 30 minutes ago. The
|
|
6
|
+
// lock file's own age is not checked.
|
|
10
7
|
//
|
|
11
|
-
//
|
|
12
|
-
// this caller owns (same token, else same workflow and feature), so a Failure
|
|
13
|
-
// that never got the lock cannot delete the holder's.
|
|
8
|
+
// The lock holds one line, `{at} {workflow} {fid} {token}`. Release removes only a
|
|
9
|
+
// lock this caller owns (same token, else same workflow and feature), so a Failure
|
|
10
|
+
// Path that never got the lock cannot delete the holder's.
|
|
14
11
|
|
|
15
12
|
import { randomBytes } from "node:crypto";
|
|
16
13
|
import * as fs from "node:fs";
|
|
@@ -26,7 +23,6 @@ import {
|
|
|
26
23
|
import {
|
|
27
24
|
CommandError,
|
|
28
25
|
EXIT,
|
|
29
|
-
git,
|
|
30
26
|
parseJson,
|
|
31
27
|
repoRoot,
|
|
32
28
|
statusRelPath,
|
|
@@ -35,13 +31,10 @@ import {
|
|
|
35
31
|
type FlagSpec,
|
|
36
32
|
type RunContext,
|
|
37
33
|
} from "../lib.js";
|
|
38
|
-
import { TIMEOUTS } from "../../shared/timeouts.js";
|
|
39
34
|
import { str } from "./status.js";
|
|
40
35
|
|
|
41
36
|
/** A workflow lock whose holder shows no sign of life for this long is stale. */
|
|
42
37
|
export const WORKFLOW_LOCK_IDLE_S = 1800;
|
|
43
|
-
/** Seconds between dev-lock attempts while it is busy. */
|
|
44
|
-
export const DEV_LOCK_POLL_S = 5;
|
|
45
38
|
|
|
46
39
|
/** Exit code: the feature has logs in more than one month bucket. */
|
|
47
40
|
export const EXIT_SPLIT_BUCKET = 7;
|
|
@@ -50,7 +43,7 @@ export const EXIT_NOT_OWNER = 4;
|
|
|
50
43
|
/** Exit code: the lock file is still there after removing it. */
|
|
51
44
|
export const EXIT_REMOVE_FAILED = 5;
|
|
52
45
|
|
|
53
|
-
const KINDS = ["workflow"
|
|
46
|
+
const KINDS = ["workflow"] as const;
|
|
54
47
|
type Kind = (typeof KINDS)[number];
|
|
55
48
|
|
|
56
49
|
// ---------------------------------------------------------------------------
|
|
@@ -92,20 +85,9 @@ export function resolveMonth(root: string, fid: string, month: string | undefine
|
|
|
92
85
|
return buckets[0] ?? utcMonth();
|
|
93
86
|
}
|
|
94
87
|
|
|
95
|
-
/**
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
*/
|
|
99
|
-
export function lockRoot(cwd: string, workflow: string, devPushes: boolean): string {
|
|
100
|
-
const root = repoRoot(cwd);
|
|
101
|
-
if (workflow !== "ship" || devPushes) return root;
|
|
102
|
-
return git(cwd, ["rev-parse", "--show-toplevel"]) ?? root;
|
|
103
|
-
}
|
|
104
|
-
|
|
105
|
-
export const workflowLockPath = (bookRoot: string, month: string, fid: string) =>
|
|
106
|
-
path.join(bookRoot, "docs", "plans", month, "logs", fid, ".lock");
|
|
107
|
-
|
|
108
|
-
export const devLockPath = (root: string) => path.join(root, ".bkit", ".dev.lock");
|
|
88
|
+
/** The feature's workflow lock, in the main checkout `root` (gitignored). */
|
|
89
|
+
export const workflowLockPath = (root: string, month: string, fid: string) =>
|
|
90
|
+
path.join(root, "docs", "plans", month, "logs", fid, ".lock");
|
|
109
91
|
|
|
110
92
|
// ---------------------------------------------------------------------------
|
|
111
93
|
// Lock file
|
|
@@ -127,7 +109,7 @@ export function readHolder(file: string): Holder | undefined {
|
|
|
127
109
|
}
|
|
128
110
|
|
|
129
111
|
/** Create `file` only if absent (`set -C`); false when someone else holds it. */
|
|
130
|
-
function tryCreate(file: string, line: string): boolean {
|
|
112
|
+
export function tryCreate(file: string, line: string): boolean {
|
|
131
113
|
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
132
114
|
const fd = openExclusive(file);
|
|
133
115
|
if (fd === undefined) return false;
|
|
@@ -146,11 +128,6 @@ function openExclusive(file: string): number | undefined {
|
|
|
146
128
|
}
|
|
147
129
|
}
|
|
148
130
|
|
|
149
|
-
const ageSeconds = (file: string, now: number): number | undefined => {
|
|
150
|
-
const st = fs.statSync(file, { throwIfNoEntry: false });
|
|
151
|
-
return st === undefined ? undefined : Math.floor((now - st.mtimeMs) / 1000);
|
|
152
|
-
};
|
|
153
|
-
|
|
154
131
|
const newToken = () => randomBytes(4).toString("hex");
|
|
155
132
|
|
|
156
133
|
const lockLine = (workflow: string, fid: string, token: string) =>
|
|
@@ -177,7 +154,6 @@ export interface WorkflowLockResult {
|
|
|
177
154
|
/** Why a held workflow lock is still live, or why it may be reclaimed. */
|
|
178
155
|
function liveReason(
|
|
179
156
|
root: string,
|
|
180
|
-
bookRoot: string,
|
|
181
157
|
month: string,
|
|
182
158
|
fid: string,
|
|
183
159
|
holder: Holder,
|
|
@@ -185,7 +161,7 @@ function liveReason(
|
|
|
185
161
|
): { live: string } | { reason: "finished" | "stale" | "orphaned" } {
|
|
186
162
|
const rel = statusRelPath(month, fid);
|
|
187
163
|
const worktreeCopy = path.join(root, ".worktrees", fid, rel);
|
|
188
|
-
const own = fs.existsSync(worktreeCopy) ? worktreeCopy : path.join(
|
|
164
|
+
const own = fs.existsSync(worktreeCopy) ? worktreeCopy : path.join(root, rel);
|
|
189
165
|
const run =
|
|
190
166
|
holder.workflow === undefined ? undefined : lastRun(readRunsLenient(own), holder.workflow);
|
|
191
167
|
const lastAt = run?.steps.at(-1)?.at;
|
|
@@ -219,19 +195,17 @@ export function acquireWorkflowLock(opts: {
|
|
|
219
195
|
workflow: string;
|
|
220
196
|
fid: string;
|
|
221
197
|
month?: string;
|
|
222
|
-
devPushes: boolean;
|
|
223
198
|
log: (m: string) => void;
|
|
224
199
|
}): WorkflowLockResult {
|
|
225
200
|
const root = repoRoot(opts.cwd);
|
|
226
201
|
const month = resolveMonth(root, opts.fid, opts.month);
|
|
227
|
-
const
|
|
228
|
-
const file = workflowLockPath(bookRoot, month, opts.fid);
|
|
202
|
+
const file = workflowLockPath(root, month, opts.fid);
|
|
229
203
|
const token = newToken();
|
|
230
204
|
const line = lockLine(opts.workflow, opts.fid, token);
|
|
231
205
|
if (tryCreate(file, line)) return { path: file, month, token, reclaimed: null };
|
|
232
206
|
|
|
233
207
|
const holder = readHolder(file) ?? { line: "" };
|
|
234
|
-
const verdict = liveReason(root,
|
|
208
|
+
const verdict = liveReason(root, month, opts.fid, holder, Date.now());
|
|
235
209
|
if ("live" in verdict) {
|
|
236
210
|
throw new CommandError(
|
|
237
211
|
EXIT.NO,
|
|
@@ -244,47 +218,6 @@ export function acquireWorkflowLock(opts: {
|
|
|
244
218
|
return { path: file, month, token, reclaimed: { holder: holder.line, reason: verdict.reason } };
|
|
245
219
|
}
|
|
246
220
|
|
|
247
|
-
// ---------------------------------------------------------------------------
|
|
248
|
-
// Dev lock
|
|
249
|
-
// ---------------------------------------------------------------------------
|
|
250
|
-
|
|
251
|
-
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
252
|
-
|
|
253
|
-
export async function acquireDevLock(opts: {
|
|
254
|
-
cwd: string;
|
|
255
|
-
workflow: string;
|
|
256
|
-
fid: string;
|
|
257
|
-
deadlineS: number;
|
|
258
|
-
log: (m: string) => void;
|
|
259
|
-
}): Promise<{ path: string; token: string; reclaimed: string | null; waitedS: number }> {
|
|
260
|
-
const file = devLockPath(repoRoot(opts.cwd));
|
|
261
|
-
const token = newToken();
|
|
262
|
-
const start = Date.now();
|
|
263
|
-
const deadline = start + opts.deadlineS * 1000;
|
|
264
|
-
let reclaimed: string | null = null;
|
|
265
|
-
for (;;) {
|
|
266
|
-
if (tryCreate(file, lockLine(opts.workflow, opts.fid, token))) {
|
|
267
|
-
return { path: file, token, reclaimed, waitedS: Math.round((Date.now() - start) / 1000) };
|
|
268
|
-
}
|
|
269
|
-
const now = Date.now();
|
|
270
|
-
const age = ageSeconds(file, now);
|
|
271
|
-
if (age === undefined) continue; // released between the attempt and the stat
|
|
272
|
-
if (age >= TIMEOUTS.SHIP_DEV_LOCK_STALE_S) {
|
|
273
|
-
reclaimed = readHolder(file)?.line ?? "";
|
|
274
|
-
opts.log(`reclaiming stale dev lock (${age}s old): ${reclaimed}`);
|
|
275
|
-
fs.rmSync(file, { force: true });
|
|
276
|
-
continue;
|
|
277
|
-
}
|
|
278
|
-
if (now >= deadline) {
|
|
279
|
-
throw new CommandError(
|
|
280
|
-
EXIT.NO,
|
|
281
|
-
`dev lock held by: ${readHolder(file)?.line ?? "?"} — serialise this run or use a separate clone`,
|
|
282
|
-
);
|
|
283
|
-
}
|
|
284
|
-
await sleep(Math.min(DEV_LOCK_POLL_S * 1000, deadline - now));
|
|
285
|
-
}
|
|
286
|
-
}
|
|
287
|
-
|
|
288
221
|
// ---------------------------------------------------------------------------
|
|
289
222
|
// Release
|
|
290
223
|
// ---------------------------------------------------------------------------
|
|
@@ -324,7 +257,7 @@ const KIND_FLAG: FlagSpec = {
|
|
|
324
257
|
name: "kind",
|
|
325
258
|
type: "string",
|
|
326
259
|
required: true,
|
|
327
|
-
help: "workflow (per-feature .lock)
|
|
260
|
+
help: "workflow (the per-feature .lock)",
|
|
328
261
|
};
|
|
329
262
|
const LOCK_WORKFLOW_FLAG: FlagSpec = {
|
|
330
263
|
name: "workflow",
|
|
@@ -338,83 +271,41 @@ const MONTH_FLAG: FlagSpec = {
|
|
|
338
271
|
type: "string",
|
|
339
272
|
help: "workflow kind: month bucket YYYYMM (default: the feature's bucket, else this UTC month)",
|
|
340
273
|
};
|
|
341
|
-
const DEV_PUSHES_FLAG: FlagSpec = {
|
|
342
|
-
name: "dev-pushes",
|
|
343
|
-
type: "boolean",
|
|
344
|
-
help: "ship only: this runtime pushes to dev (lock lives in the main checkout)",
|
|
345
|
-
};
|
|
346
274
|
|
|
347
275
|
function kindOf(ctx: RunContext): Kind {
|
|
348
276
|
const kind = String(ctx.flags.kind);
|
|
349
277
|
if (!(KINDS as readonly string[]).includes(kind))
|
|
350
|
-
throw new CommandError(EXIT.USAGE, "--kind must be workflow
|
|
278
|
+
throw new CommandError(EXIT.USAGE, "--kind must be workflow");
|
|
351
279
|
return kind as Kind;
|
|
352
280
|
}
|
|
353
281
|
|
|
354
|
-
function deadlineOf(ctx: RunContext): number {
|
|
355
|
-
const raw = str(ctx.flags.deadline);
|
|
356
|
-
if (raw === undefined) return TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S;
|
|
357
|
-
if (!/^[0-9]+$/.test(raw))
|
|
358
|
-
throw new CommandError(EXIT.USAGE, `--deadline must be whole seconds, got "${raw}"`);
|
|
359
|
-
return Number(raw);
|
|
360
|
-
}
|
|
361
|
-
|
|
362
282
|
export const locksCommand: CommandSpec = {
|
|
363
283
|
noun: "locks",
|
|
364
|
-
summary: "Acquire and release the per-feature workflow lock
|
|
284
|
+
summary: "Acquire and release the per-feature workflow lock.",
|
|
365
285
|
verbs: {
|
|
366
286
|
acquire: {
|
|
367
|
-
summary: "Take
|
|
368
|
-
flags: [
|
|
369
|
-
KIND_FLAG,
|
|
370
|
-
LOCK_WORKFLOW_FLAG,
|
|
371
|
-
FID_FLAG,
|
|
372
|
-
MONTH_FLAG,
|
|
373
|
-
DEV_PUSHES_FLAG,
|
|
374
|
-
{
|
|
375
|
-
name: "deadline",
|
|
376
|
-
type: "string",
|
|
377
|
-
help: `dev kind: seconds to wait for a busy lock (default ${TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S})`,
|
|
378
|
-
},
|
|
379
|
-
],
|
|
287
|
+
summary: "Take the workflow lock, reclaiming a dead holder's.",
|
|
288
|
+
flags: [KIND_FLAG, LOCK_WORKFLOW_FLAG, FID_FLAG, MONTH_FLAG],
|
|
380
289
|
output: {
|
|
381
|
-
kind: "workflow
|
|
290
|
+
kind: "workflow",
|
|
382
291
|
path: "absolute path of the lock file",
|
|
383
292
|
token: "this holder's token; pass it to release",
|
|
384
|
-
month: "
|
|
385
|
-
reclaimed:
|
|
386
|
-
"workflow kind: {holder, reason: finished|stale|orphaned}; dev kind: the stale line; null when none",
|
|
387
|
-
waitedS: "dev kind: seconds spent waiting (null for workflow)",
|
|
293
|
+
month: "the month bucket",
|
|
294
|
+
reclaimed: "{holder, reason: finished|stale|orphaned}; null when none",
|
|
388
295
|
},
|
|
389
296
|
exitCodes: {
|
|
390
|
-
[EXIT_SPLIT_BUCKET]: "
|
|
297
|
+
[EXIT_SPLIT_BUCKET]: "the feature has logs in more than one month bucket",
|
|
391
298
|
},
|
|
392
|
-
run:
|
|
299
|
+
run: (ctx) => {
|
|
393
300
|
const kind = kindOf(ctx);
|
|
394
|
-
const
|
|
395
|
-
const fid = String(ctx.flags.fid);
|
|
396
|
-
if (kind === "workflow") {
|
|
397
|
-
if (ctx.flags.deadline !== undefined)
|
|
398
|
-
throw new CommandError(EXIT.USAGE, "--deadline applies to --kind=dev only");
|
|
399
|
-
const lock = acquireWorkflowLock({
|
|
400
|
-
cwd: ctx.cwd,
|
|
401
|
-
workflow,
|
|
402
|
-
fid,
|
|
403
|
-
month: str(ctx.flags.month),
|
|
404
|
-
devPushes: ctx.flags.devPushes === true,
|
|
405
|
-
log: ctx.log,
|
|
406
|
-
});
|
|
407
|
-
ctx.emit({ kind, ...lock, waitedS: null });
|
|
408
|
-
return EXIT.OK;
|
|
409
|
-
}
|
|
410
|
-
const lock = await acquireDevLock({
|
|
301
|
+
const lock = acquireWorkflowLock({
|
|
411
302
|
cwd: ctx.cwd,
|
|
412
|
-
workflow,
|
|
413
|
-
fid,
|
|
414
|
-
|
|
303
|
+
workflow: String(ctx.flags.workflow),
|
|
304
|
+
fid: String(ctx.flags.fid),
|
|
305
|
+
month: str(ctx.flags.month),
|
|
415
306
|
log: ctx.log,
|
|
416
307
|
});
|
|
417
|
-
ctx.emit({ kind, ...lock
|
|
308
|
+
ctx.emit({ kind, ...lock });
|
|
418
309
|
return EXIT.OK;
|
|
419
310
|
},
|
|
420
311
|
},
|
|
@@ -425,7 +316,6 @@ export const locksCommand: CommandSpec = {
|
|
|
425
316
|
LOCK_WORKFLOW_FLAG,
|
|
426
317
|
FID_FLAG,
|
|
427
318
|
MONTH_FLAG,
|
|
428
|
-
DEV_PUSHES_FLAG,
|
|
429
319
|
{
|
|
430
320
|
name: "token",
|
|
431
321
|
type: "string",
|
|
@@ -433,15 +323,14 @@ export const locksCommand: CommandSpec = {
|
|
|
433
323
|
},
|
|
434
324
|
],
|
|
435
325
|
output: {
|
|
436
|
-
kind: "workflow
|
|
326
|
+
kind: "workflow",
|
|
437
327
|
path: "absolute path of the lock file",
|
|
438
328
|
existed: "a lock file was there",
|
|
439
329
|
released: "this call removed it",
|
|
440
330
|
heldBy: "the other owner's lock line when it was left in place, else null",
|
|
441
331
|
},
|
|
442
332
|
exitCodes: {
|
|
443
|
-
[EXIT_SPLIT_BUCKET]:
|
|
444
|
-
"workflow kind without --month: the feature has logs in more than one month bucket",
|
|
333
|
+
[EXIT_SPLIT_BUCKET]: "no --month and the feature has logs in more than one month bucket",
|
|
445
334
|
[EXIT_NOT_OWNER]: "the lock belongs to another owner and was left in place",
|
|
446
335
|
[EXIT_REMOVE_FAILED]: "the lock file is still there after removing it",
|
|
447
336
|
},
|
|
@@ -453,14 +342,11 @@ export const locksCommand: CommandSpec = {
|
|
|
453
342
|
token: str(ctx.flags.token),
|
|
454
343
|
};
|
|
455
344
|
const root = repoRoot(ctx.cwd);
|
|
456
|
-
const file =
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
resolveMonth(root, who.fid, str(ctx.flags.month)),
|
|
462
|
-
who.fid,
|
|
463
|
-
);
|
|
345
|
+
const file = workflowLockPath(
|
|
346
|
+
root,
|
|
347
|
+
resolveMonth(root, who.fid, str(ctx.flags.month)),
|
|
348
|
+
who.fid,
|
|
349
|
+
);
|
|
464
350
|
const { removeFailed, ...result } = releaseLock(file, who);
|
|
465
351
|
ctx.emit({ kind, ...result });
|
|
466
352
|
if (removeFailed) {
|
|
@@ -620,17 +620,26 @@ export function crossCheckFile(
|
|
|
620
620
|
file: string,
|
|
621
621
|
transport: string,
|
|
622
622
|
log: (m: string) => void,
|
|
623
|
+
): { ok: boolean; runtimeGithubCli: boolean | null; transport: string; fallbackRows: number } {
|
|
624
|
+
return crossCheckRows(readStatusRows(file), file, transport, log);
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
/** crossCheckFile over rows already read; `label` names where they came from. */
|
|
628
|
+
export function crossCheckRows(
|
|
629
|
+
rows: StatusRow[],
|
|
630
|
+
label: string,
|
|
631
|
+
transport: string,
|
|
632
|
+
log: (m: string) => void,
|
|
623
633
|
): { ok: boolean; runtimeGithubCli: boolean | null; transport: string; fallbackRows: number } {
|
|
624
634
|
if (!TRANSPORTS.includes(transport)) {
|
|
625
635
|
throw new CommandError(EXIT.USAGE, `--transport must be ${TRANSPORTS.join(", ")}`);
|
|
626
636
|
}
|
|
627
|
-
const rows = readStatusRows(file);
|
|
628
637
|
const runtimeGithubCli = capability(lastRow(rows, "runtime-resolved")?.runtimeGithubCli);
|
|
629
638
|
const fallbackRows = rows.filter((r) => r.type === "transport-fallback").length;
|
|
630
639
|
const violated = runtimeGithubCli === false && transport === "mcp" && fallbackRows === 0;
|
|
631
640
|
if (violated) {
|
|
632
641
|
log(
|
|
633
|
-
`runtime-resolved logged runtimeGithubCli=false and this close used transport mcp, but no transport-fallback row exists in ${
|
|
642
|
+
`runtime-resolved logged runtimeGithubCli=false and this close used transport mcp, but no transport-fallback row exists in ${label}`,
|
|
634
643
|
);
|
|
635
644
|
}
|
|
636
645
|
return { ok: !violated, runtimeGithubCli, transport, fallbackRows };
|