@cbartens/bkit 5.5.1 → 6.0.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 +30 -20
- package/.bkit/core/.agents/docs.md +1 -0
- package/.bkit/core/.agents/rules.md +35 -26
- package/.bkit/core/.bkit/README.md +29 -19
- package/.bkit/core/.bkit/authoring.md +117 -0
- package/.bkit/core/.bkit/cloud.md +11 -11
- package/.bkit/core/.bkit/comparison.md +5 -5
- package/.bkit/core/.bkit/install.md +19 -18
- package/.bkit/core/.bkit/jsonl.md +202 -122
- package/.bkit/core/.bkit/lite.md +1 -1
- package/.bkit/core/.bkit/pipeline.md +49 -52
- package/.bkit/core/.bkit/prompts.md +91 -167
- package/.bkit/core/.bkit/providers.md +29 -32
- package/.bkit/core/.bkit/templates.md +12 -11
- package/.bkit/core/.bkit/trackers.md +51 -28
- package/.bkit/core/.bkit/workflows.md +394 -355
- package/.bkit/core/AGENTS.md +16 -22
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
- package/.bkit/core/docs/templates/bkit-plan.md +97 -226
- package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
- package/.bkit/core/engine/checks/after/github.ts +95 -17
- package/.bkit/core/engine/checks/after/index.ts +10 -7
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +46 -91
- package/.bkit/core/engine/checks/before/env.ts +2 -2
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +18 -1
- package/.bkit/core/engine/checks/before/repo.ts +168 -2
- package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
- package/.bkit/core/engine/checks/tips/detect.ts +34 -0
- package/.bkit/core/engine/checks/tips/index.ts +6 -6
- package/.bkit/core/engine/cli.ts +20 -53
- package/.bkit/core/engine/commands/analysis.ts +171 -140
- package/.bkit/core/engine/commands/ci/ci.ts +6 -6
- package/.bkit/core/engine/commands/comply.ts +77 -103
- package/.bkit/core/engine/commands/install/doctor.ts +2 -2
- package/.bkit/core/engine/commands/install/install.ts +57 -18
- package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
- package/.bkit/core/engine/commands/land.ts +18 -12
- package/.bkit/core/engine/commands/lib.ts +79 -17
- package/.bkit/core/engine/commands/registry.ts +4 -0
- package/.bkit/core/engine/commands/setup/setup.ts +7 -7
- package/.bkit/core/engine/commands/stats.ts +204 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
- package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
- package/.bkit/core/engine/commands/workflow/context.ts +853 -29
- package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
- package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
- package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
- package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
- package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
- package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
- package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
- package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
- package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
- package/.bkit/core/engine/commands/workflow/status.ts +142 -29
- package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
- package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
- package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
- package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
- package/.bkit/core/engine/install/manifest.ts +11 -9
- package/.bkit/core/engine/install/modules/cloud.ts +21 -13
- package/.bkit/core/engine/install/modules/core.ts +250 -3
- package/.bkit/core/engine/install/modules/opencode.ts +2 -2
- package/.bkit/core/engine/install/version-file.ts +6 -2
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +92 -15
- package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
- package/.bkit/core/engine/render/hosts.ts +4 -0
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/egress.ts +7 -0
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/settings.ts +157 -20
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
- package/.bkit/core/engine/tools/instructions.ts +1751 -0
- package/.bkit/core/hooks/gateguard-engine.js +24 -23
- package/.bkit/core/hooks/guardrails-shell.js +2 -3
- package/.bkit/core/hooks/guardrails-tiers.js +7 -1
- package/.bkit/core/hooks/readguard-engine.js +2 -2
- package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
- package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
- package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
- package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
- package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
- package/.bkit/core/prompts/bkit-design-generate.md +32 -14
- package/.bkit/core/prompts/bkit-design-organise.md +25 -12
- package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
- package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
- package/.bkit/core/prompts/bkit-design-spike.md +30 -13
- package/.bkit/core/prompts/bkit-design-update.md +33 -19
- package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
- package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
- package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
- package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
- package/.bkit/core/prompts/bkit-plan-update.md +61 -24
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
- package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
- package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
- package/.bkit/core/workflows/bkit-auto.md +54 -46
- package/.bkit/core/workflows/bkit-build.md +577 -458
- package/.bkit/core/workflows/bkit-debug.md +348 -333
- package/.bkit/core/workflows/bkit-design.md +201 -237
- package/.bkit/core/workflows/bkit-plan.md +210 -321
- package/.bkit/core/workflows/bkit-ship.md +328 -278
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/settings.json +11 -0
- package/.bkit/shared/.cursor/mcp.json +1 -1
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
- package/.bkit/shared/.gitattributes +1 -1
- package/.bkit/shared/.mcp.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -0
- package/.bkit/shared/CLAUDE.md +2 -2
- package/.bkit/shared/GEMINI.md +2 -2
- package/.bkit/shared/docs/architecture.md +1 -1
- package/.bkit/shared/docs/data-schema.md +1 -1
- package/.bkit/shared/docs/deployments.md +11 -11
- package/.bkit/shared/docs/design.md +1 -1
- package/.bkit/shared/docs/noise.md +1 -1
- package/.bkit/shared/docs/observability.md +2 -2
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/setup.md +1 -1
- package/.bkit/shared/docs/technology.md +1 -1
- package/.bkit/shared/docs/testing.md +16 -7
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
- package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
- package/.bkit/templates/.husky/pre-push +4 -4
- package/.bkit/templates/.prettierignore +7 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
- package/CHANGELOG.md +112 -0
- package/README.md +50 -35
- package/dist/checks/after/ci-yml.js +39 -28
- package/dist/checks/after/github.js +91 -17
- package/dist/checks/after/index.js +11 -8
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +39 -82
- package/dist/checks/before/env.js +2 -2
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +15 -2
- package/dist/checks/before/repo.js +163 -2
- package/dist/checks/tips/catalogue.js +14 -5
- package/dist/checks/tips/detect.js +32 -0
- package/dist/checks/tips/index.js +4 -4
- package/dist/cli.js +19 -47
- package/dist/commands/analysis.js +109 -100
- package/dist/commands/ci/ci.js +6 -6
- package/dist/commands/comply.js +54 -91
- package/dist/commands/install/doctor.js +2 -2
- package/dist/commands/install/install.js +50 -19
- package/dist/commands/install/uninstall.js +59 -28
- package/dist/commands/land.js +16 -12
- package/dist/commands/lib.js +51 -16
- package/dist/commands/registry.js +4 -0
- package/dist/commands/setup/setup.js +7 -7
- package/dist/commands/stats.js +136 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +656 -56
- package/dist/commands/workflow/challenge.js +556 -0
- package/dist/commands/workflow/context.js +709 -30
- package/dist/commands/workflow/counters.js +208 -75
- package/dist/commands/workflow/decisions.js +441 -0
- package/dist/commands/workflow/disk.js +2 -2
- package/dist/commands/workflow/fids.js +689 -33
- package/dist/commands/workflow/issues.js +343 -59
- package/dist/commands/workflow/ledgers.js +762 -27
- package/dist/commands/workflow/locks.js +24 -2
- package/dist/commands/workflow/plan-blocks.js +437 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/prs.js +142 -32
- package/dist/commands/workflow/repo.js +52 -8
- package/dist/commands/workflow/roadmap.js +9 -7
- package/dist/commands/workflow/run-facts.js +426 -0
- package/dist/commands/workflow/runs.js +144 -43
- package/dist/commands/workflow/runtime.js +12 -1
- package/dist/commands/workflow/status.js +130 -29
- package/dist/commands/workflow/step-table.js +276 -0
- package/dist/commands/workflow/steps.js +171 -80
- package/dist/commands/workflow/summary.js +275 -0
- package/dist/commands/workflow/tests.js +834 -136
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +834 -195
- package/dist/commands/workflow/workstreams.js +11 -5
- package/dist/commands/workflow/worktrees.js +147 -9
- package/dist/install/manifest.js +11 -9
- package/dist/install/modules/cloud.js +22 -13
- package/dist/install/modules/core.js +247 -3
- package/dist/install/modules/opencode.js +2 -2
- package/dist/install/version-file.js +6 -2
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +61 -8
- package/dist/ledgers/telemetry.js +905 -124
- package/dist/render/hosts.js +4 -0
- package/dist/render/models.js +12 -0
- package/dist/shared/branches.js +3 -1
- package/dist/shared/egress.js +7 -0
- package/dist/shared/json.js +20 -7
- package/dist/shared/settings.js +125 -17
- package/dist/shared/text.js +333 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +721 -0
- package/dist/tools/instructions.js +1579 -0
- package/package.json +113 -24
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- package/.bkit/core/engine/tools/wording.ts +0 -748
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
- package/.bkit/core/prompts/bkit-build-summary.md +0 -94
- package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
- package/.bkit/core/prompts/bkit-design-summary.md +0 -107
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
- package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
- package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
- package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
- package/dist/commands/harvest.js +0 -353
- package/dist/tools/wording.js +0 -680
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
// bkit context clamp|clamp-log|ledger-scan|list-blocks|run-block|finalise —
|
|
2
|
-
// size-bound context artifacts and
|
|
1
|
+
// bkit context clamp|clamp-log|ledger-scan|diff|brief|list-blocks|run-block|finalise —
|
|
2
|
+
// size-bound context artifacts, write the run's diff and a build group's brief,
|
|
3
|
+
// and fetch the consumer's evidence.
|
|
3
4
|
//
|
|
4
5
|
// clamp is a runaway backstop, NOT a routine cap: a normal run never fires it.
|
|
5
6
|
// Every removal is marked in place and footered. Profiles:
|
|
@@ -13,6 +14,10 @@
|
|
|
13
14
|
//
|
|
14
15
|
// Bytes are counted as raw bytes (as `LC_ALL=C awk` counts them), never as
|
|
15
16
|
// characters, so a multi-byte line is measured by what it costs on disk.
|
|
17
|
+
//
|
|
18
|
+
// A cut file keeps its untouched original as `{name}.raw.{ext}` in the outbox
|
|
19
|
+
// (`keepRaw`), never under `logs/`; the record names it (`raw`) with the command
|
|
20
|
+
// that produced the file (`source`) and when it ran (`fetchedAt`).
|
|
16
21
|
|
|
17
22
|
import { spawnSync } from "node:child_process";
|
|
18
23
|
import * as fs from "node:fs";
|
|
@@ -29,14 +34,26 @@ import {
|
|
|
29
34
|
CommandError,
|
|
30
35
|
EXIT,
|
|
31
36
|
git,
|
|
37
|
+
outboxRel,
|
|
38
|
+
outboxRoot,
|
|
32
39
|
type CommandSpec,
|
|
33
40
|
type FlagSpec,
|
|
34
41
|
type RunContext,
|
|
35
42
|
} from "../lib.js";
|
|
36
|
-
import { resolveRepoSlug } from "../../ledgers/telemetry.js";
|
|
43
|
+
import { gitEnv, resolveRepoSlug } from "../../ledgers/telemetry.js";
|
|
44
|
+
import { parseJson } from "../../shared/json.js";
|
|
45
|
+
import { checkedTable } from "../../shared/text.js";
|
|
37
46
|
import { buildComment } from "./issues.js";
|
|
47
|
+
import {
|
|
48
|
+
parsePlanBlocks,
|
|
49
|
+
reuseInventory,
|
|
50
|
+
type PlanGroup,
|
|
51
|
+
type PlanTaskBlock,
|
|
52
|
+
} from "./plan-blocks.js";
|
|
53
|
+
import { COMMENT_FILE_OUTPUT, commentFileOf } from "./tracker.js";
|
|
38
54
|
import { EXIT_NO_STATUS, positiveInt, readRuns, str } from "./status.js";
|
|
39
55
|
import { EXIT_COMMIT, writeStepRow } from "./steps.js";
|
|
56
|
+
import { doneTasks, redRows } from "./tests.js";
|
|
40
57
|
|
|
41
58
|
/** Exit code: the artifact to clamp is missing, unreadable, or could not be replaced. */
|
|
42
59
|
export const EXIT_ARTIFACT = 4;
|
|
@@ -83,8 +100,61 @@ export interface ClampRecord {
|
|
|
83
100
|
keptBytes: number;
|
|
84
101
|
lineCapped: number;
|
|
85
102
|
ceilingHit: boolean;
|
|
103
|
+
/** The untouched original in the outbox, main-checkout relative; null when nothing was cut. */
|
|
104
|
+
raw: string | null;
|
|
105
|
+
/** The exact command and inputs that produced the file; null when the caller did not say. */
|
|
106
|
+
source: string | null;
|
|
107
|
+
/** When the source ran (UTC); a re-run returns the source's data now, not then. */
|
|
108
|
+
fetchedAt: string | null;
|
|
109
|
+
/** `context fetch` only: `table` when the output was rendered as a table, else `raw`. */
|
|
110
|
+
render?: Render;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** How `context fetch` writes a block's output. */
|
|
114
|
+
export type Render = "table" | "raw";
|
|
115
|
+
const RENDERS: readonly Render[] = ["table", "raw"];
|
|
116
|
+
|
|
117
|
+
/** Where a cut file's original goes and what produced it. */
|
|
118
|
+
export interface Provenance {
|
|
119
|
+
/** Folder for `{name}.raw.{ext}`; null when there is none (outside a git repo). */
|
|
120
|
+
rawDir: string | null;
|
|
121
|
+
source?: string;
|
|
122
|
+
fetchedAt?: string;
|
|
123
|
+
/** An untouched copy already in the outbox (the runner's own log): no second copy. */
|
|
124
|
+
original?: string;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Copy the original of a file about to be trimmed or rendered to
|
|
129
|
+
* `{rawDir}/{name}.raw.{ext}`, byte for byte; `content` stands in for a file that
|
|
130
|
+
* was never written whole. Returns the copy's path.
|
|
131
|
+
*/
|
|
132
|
+
export function keepRaw(file: string, rawDir: string, content?: Buffer): string {
|
|
133
|
+
const ext = path.extname(file);
|
|
134
|
+
const raw = path.join(rawDir, `${path.basename(file, ext)}.raw${ext}`);
|
|
135
|
+
fs.mkdirSync(rawDir, { recursive: true });
|
|
136
|
+
if (content === undefined) fs.copyFileSync(file, raw);
|
|
137
|
+
else fs.writeFileSync(raw, content);
|
|
138
|
+
return raw;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** `keepRaw`, with a failed copy handed back as its error so the caller picks the exit code. */
|
|
142
|
+
function keepRawOrError(file: string, rawDir: string): string | Error {
|
|
143
|
+
try {
|
|
144
|
+
return keepRaw(file, rawDir);
|
|
145
|
+
} catch (err) {
|
|
146
|
+
return err instanceof Error ? err : new Error(String(err));
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** The outbox folder a feature's originals go to (the outbox root without a fid); null outside a repo. */
|
|
151
|
+
export function rawDirFor(cwd: string, fid: string | undefined): string | null {
|
|
152
|
+
const root = outboxRoot(cwd);
|
|
153
|
+
return root === null ? null : path.join(root, fid ?? "");
|
|
86
154
|
}
|
|
87
155
|
|
|
156
|
+
const utcNow = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
|
|
157
|
+
|
|
88
158
|
const LEDGER = { maxLines: 200, maxBytes: 51200 };
|
|
89
159
|
const EVIDENCE = {
|
|
90
160
|
softLines: 3000,
|
|
@@ -301,7 +371,12 @@ function selectEvidence(buf: Buffer): Selection {
|
|
|
301
371
|
* left byte-identical; otherwise the kept content plus footer replace it via a
|
|
302
372
|
* sibling temp file, never truncating in place.
|
|
303
373
|
*/
|
|
304
|
-
export function clampFile(
|
|
374
|
+
export function clampFile(
|
|
375
|
+
file: string,
|
|
376
|
+
profile: string,
|
|
377
|
+
artifact = file,
|
|
378
|
+
keep?: Provenance,
|
|
379
|
+
): ClampRecord {
|
|
305
380
|
if (!(CLAMP_PROFILES as readonly string[]).includes(profile)) {
|
|
306
381
|
throw new CommandError(
|
|
307
382
|
EXIT.USAGE,
|
|
@@ -314,6 +389,8 @@ export function clampFile(file: string, profile: string, artifact = file): Clamp
|
|
|
314
389
|
}
|
|
315
390
|
const buf = read.buf;
|
|
316
391
|
const sel = profile === "ledger" ? selectLedger(buf) : selectEvidence(buf);
|
|
392
|
+
const source = keep?.source ?? null;
|
|
393
|
+
const fetchedAt = keep?.fetchedAt ?? (source === null ? null : utcNow());
|
|
317
394
|
const untouched = (s: Selection | null): ClampRecord => ({
|
|
318
395
|
artifact,
|
|
319
396
|
clamped: false,
|
|
@@ -323,9 +400,24 @@ export function clampFile(file: string, profile: string, artifact = file): Clamp
|
|
|
323
400
|
keptBytes: s?.keptBytes ?? buf.length,
|
|
324
401
|
lineCapped: 0,
|
|
325
402
|
ceilingHit: false,
|
|
403
|
+
raw: null,
|
|
404
|
+
source,
|
|
405
|
+
fetchedAt,
|
|
326
406
|
});
|
|
327
407
|
if (sel === null || sel.body.length === 0) return untouched(sel);
|
|
328
408
|
|
|
409
|
+
let raw: string | null = keep?.original ?? null;
|
|
410
|
+
if (raw === null && keep?.rawDir) {
|
|
411
|
+
const kept = keepRawOrError(file, keep.rawDir);
|
|
412
|
+
// The trim would lose the only copy: refuse it, the file stays whole.
|
|
413
|
+
if (kept instanceof Error)
|
|
414
|
+
throw new CommandError(
|
|
415
|
+
EXIT_ARTIFACT,
|
|
416
|
+
`cannot keep the original of '${artifact}': ${kept.message}`,
|
|
417
|
+
);
|
|
418
|
+
raw = kept;
|
|
419
|
+
}
|
|
420
|
+
|
|
329
421
|
const footer: string[] = [];
|
|
330
422
|
if (sel.lineCapped > 1) {
|
|
331
423
|
footer.push(`> [bkit] ${sel.lineCapped} over-long lines were shortened; each says so inline.`);
|
|
@@ -353,6 +445,9 @@ export function clampFile(file: string, profile: string, artifact = file): Clamp
|
|
|
353
445
|
keptBytes: sel.keptBytes,
|
|
354
446
|
lineCapped: sel.lineCapped,
|
|
355
447
|
ceilingHit: sel.ceilingHit,
|
|
448
|
+
raw: raw === null ? null : outboxRel(path.dirname(file), raw),
|
|
449
|
+
source,
|
|
450
|
+
fetchedAt,
|
|
356
451
|
};
|
|
357
452
|
}
|
|
358
453
|
|
|
@@ -420,8 +515,17 @@ const RECORD_OUTPUT: Record<string, string> = {
|
|
|
420
515
|
keptBytes: "content bytes kept",
|
|
421
516
|
lineCapped: "over-long lines shortened in place",
|
|
422
517
|
ceilingHit: "true when the hard ceiling dropped matching lines too",
|
|
518
|
+
raw: "the untouched original in the outbox ({name}.raw.{ext}), or null when nothing was cut",
|
|
519
|
+
source: "the command that produced the file (--source), or null",
|
|
520
|
+
fetchedAt: "when the source ran (UTC; the clamp time with --source), or null",
|
|
423
521
|
};
|
|
424
522
|
|
|
523
|
+
/** Say so when a cut had nowhere to keep its original. */
|
|
524
|
+
function warnNoRaw(ctx: RunContext, record: ClampRecord, keep: Provenance) {
|
|
525
|
+
if (record.clamped && record.raw === null && keep.rawDir === null)
|
|
526
|
+
ctx.log(`${record.artifact}: not inside a git repo — original not kept`);
|
|
527
|
+
}
|
|
528
|
+
|
|
425
529
|
// ---------------------------------------------------------------------------
|
|
426
530
|
// Ledger scan — plan Step 4's related deferrals / failures
|
|
427
531
|
// ---------------------------------------------------------------------------
|
|
@@ -593,31 +697,496 @@ function asCaptured(out: Buffer): Buffer {
|
|
|
593
697
|
return Buffer.concat([bytes.subarray(0, end), Buffer.from("\n")]);
|
|
594
698
|
}
|
|
595
699
|
|
|
700
|
+
// ---------------------------------------------------------------------------
|
|
701
|
+
// Diff artifact — the one definition of "the run's diff"
|
|
702
|
+
//
|
|
703
|
+
// Build briefs, the challenge size gate and per-group verify read the same range
|
|
704
|
+
// the same way: `{base}...HEAD` with `docs/plans/**` excluded, written to one
|
|
705
|
+
// file. Past the guard the file holds a per-file budget instead of the whole diff
|
|
706
|
+
// (`--stat`, then the largest files first, each cut), and its first line says so.
|
|
707
|
+
// ---------------------------------------------------------------------------
|
|
708
|
+
|
|
709
|
+
/** Exit code: --base does not name a commit. */
|
|
710
|
+
export const EXIT_BASE = 5;
|
|
711
|
+
|
|
712
|
+
export const DIFF_BASE = "origin/dev";
|
|
713
|
+
export const DIFF_EXCLUDES = ["docs/plans/**"];
|
|
714
|
+
export const PARTIAL_MARK = "partial diff coverage";
|
|
715
|
+
|
|
716
|
+
export interface DiffGuard {
|
|
717
|
+
/** A diff longer than this is written as a per-file budget. */
|
|
718
|
+
fullLines: number;
|
|
719
|
+
/** Files shown in budget mode, largest change first. */
|
|
720
|
+
topFiles: number;
|
|
721
|
+
/** Lines kept per shown file. */
|
|
722
|
+
perFileLines: number;
|
|
723
|
+
/** Lines kept in all; the file stops there. */
|
|
724
|
+
totalLines: number;
|
|
725
|
+
}
|
|
726
|
+
export const DIFF_GUARD: DiffGuard = {
|
|
727
|
+
fullLines: 10000,
|
|
728
|
+
topFiles: 20,
|
|
729
|
+
perFileLines: 500,
|
|
730
|
+
totalLines: 50000,
|
|
731
|
+
};
|
|
732
|
+
|
|
733
|
+
export interface DiffStat {
|
|
734
|
+
filesChanged: number;
|
|
735
|
+
linesAdded: number;
|
|
736
|
+
linesDeleted: number;
|
|
737
|
+
linesChanged: number;
|
|
738
|
+
}
|
|
739
|
+
|
|
740
|
+
export interface DiffArtifact {
|
|
741
|
+
range: string;
|
|
742
|
+
stat: DiffStat;
|
|
743
|
+
diffLines: number;
|
|
744
|
+
partial: boolean;
|
|
745
|
+
/** Files whose diff is not in the artifact whole: not shown, or cut. */
|
|
746
|
+
omitted: string[];
|
|
747
|
+
record: ClampRecord;
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
/** git's stdout as bytes; empty when git fails (a range it rejects diffs as nothing). */
|
|
751
|
+
function gitBytes(cwd: string, args: string[]): Buffer {
|
|
752
|
+
const res = spawnSync("git", args, { cwd, env: gitEnv(), maxBuffer: 1 << 29 });
|
|
753
|
+
return res.status === 0 ? (res.stdout ?? Buffer.alloc(0)) : Buffer.alloc(0);
|
|
754
|
+
}
|
|
755
|
+
|
|
756
|
+
const excludeSpec = (): string[] => ["--", ".", ...DIFF_EXCLUDES.map((e) => `:(exclude)${e}`)];
|
|
757
|
+
|
|
758
|
+
/** Per-file `--numstat` rows over the range and excludes; a binary file counts with no lines. */
|
|
759
|
+
export function diffNumstat(
|
|
760
|
+
cwd: string,
|
|
761
|
+
range: string,
|
|
762
|
+
): { files: { path: string; lines: number }[]; stat: DiffStat } {
|
|
763
|
+
const files: { path: string; lines: number }[] = [];
|
|
764
|
+
let linesAdded = 0;
|
|
765
|
+
let linesDeleted = 0;
|
|
766
|
+
const rows = gitBytes(cwd, ["diff", "--numstat", "--no-renames", range, ...excludeSpec()])
|
|
767
|
+
.toString("utf-8")
|
|
768
|
+
.split("\n");
|
|
769
|
+
for (const row of rows) {
|
|
770
|
+
if (row === "") continue;
|
|
771
|
+
const [a, d, ...rest] = row.split("\t");
|
|
772
|
+
const added = Number(a) || 0;
|
|
773
|
+
const deleted = Number(d) || 0;
|
|
774
|
+
linesAdded += added;
|
|
775
|
+
linesDeleted += deleted;
|
|
776
|
+
files.push({ path: rest.join("\t"), lines: added + deleted });
|
|
777
|
+
}
|
|
778
|
+
return {
|
|
779
|
+
files,
|
|
780
|
+
stat: {
|
|
781
|
+
filesChanged: files.length,
|
|
782
|
+
linesAdded,
|
|
783
|
+
linesDeleted,
|
|
784
|
+
linesChanged: linesAdded + linesDeleted,
|
|
785
|
+
},
|
|
786
|
+
};
|
|
787
|
+
}
|
|
788
|
+
|
|
789
|
+
const joinLines = (lines: Buffer[]): Buffer =>
|
|
790
|
+
lines.length === 0 ? Buffer.alloc(0) : Buffer.concat([...lines.flatMap((l) => [l, lineOf("")])]);
|
|
791
|
+
|
|
792
|
+
/** {@link writeDiffArtifact}; the artifact, or the error text when the write fails. */
|
|
793
|
+
function tryWriteDiffArtifact(
|
|
794
|
+
...args: Parameters<typeof writeDiffArtifact>
|
|
795
|
+
): { ok: true; result: DiffArtifact } | { ok: false; error: string } {
|
|
796
|
+
try {
|
|
797
|
+
return { ok: true, result: writeDiffArtifact(...args) };
|
|
798
|
+
} catch (err) {
|
|
799
|
+
// Reported as the artifact exit code, with the reason.
|
|
800
|
+
return { ok: false, error: (err as Error).message };
|
|
801
|
+
}
|
|
802
|
+
}
|
|
803
|
+
|
|
804
|
+
/** Write the range's diff to `out`: whole under the guard, else a per-file budget; the record says which. */
|
|
805
|
+
export function writeDiffArtifact(
|
|
806
|
+
cwd: string,
|
|
807
|
+
out: string,
|
|
808
|
+
artifact: string,
|
|
809
|
+
range: string,
|
|
810
|
+
guard: DiffGuard = DIFF_GUARD,
|
|
811
|
+
keep: Provenance = { rawDir: null },
|
|
812
|
+
): DiffArtifact {
|
|
813
|
+
const fetchedAt = utcNow();
|
|
814
|
+
const { files, stat } = diffNumstat(cwd, range);
|
|
815
|
+
const full = gitBytes(cwd, ["diff", range, ...excludeSpec()]);
|
|
816
|
+
const diffLines = records(full).length;
|
|
817
|
+
let content: Buffer;
|
|
818
|
+
let partial = false;
|
|
819
|
+
let ceilingHit = false;
|
|
820
|
+
const omitted: string[] = [];
|
|
821
|
+
if (diffLines === 0) {
|
|
822
|
+
content = lineOf(`No changes in ${range} outside ${DIFF_EXCLUDES.join(", ")}.`);
|
|
823
|
+
} else if (diffLines <= guard.fullLines) {
|
|
824
|
+
content = full;
|
|
825
|
+
} else {
|
|
826
|
+
partial = true;
|
|
827
|
+
const ranked = [...files].sort((a, b) => b.lines - a.lines || a.path.localeCompare(b.path));
|
|
828
|
+
const shown = ranked.slice(0, guard.topFiles);
|
|
829
|
+
const stat0 = gitBytes(cwd, ["diff", "--stat", range, ...excludeSpec()]);
|
|
830
|
+
// Header, omitted-files line, a blank, --stat and a blank count toward the total.
|
|
831
|
+
const room0 = guard.totalLines - (4 + records(stat0).length);
|
|
832
|
+
const body: Buffer[] = [];
|
|
833
|
+
let used = 0;
|
|
834
|
+
const add = (b: Buffer) => {
|
|
835
|
+
body.push(b);
|
|
836
|
+
used += records(b).length;
|
|
837
|
+
};
|
|
838
|
+
let stopped = false;
|
|
839
|
+
for (const f of ranked) {
|
|
840
|
+
if (stopped || !shown.includes(f)) {
|
|
841
|
+
omitted.push(f.path);
|
|
842
|
+
continue;
|
|
843
|
+
}
|
|
844
|
+
const room = Math.min(guard.perFileLines, room0 - used);
|
|
845
|
+
if (room <= 0) {
|
|
846
|
+
ceilingHit = true;
|
|
847
|
+
stopped = true;
|
|
848
|
+
omitted.push(f.path);
|
|
849
|
+
add(lineOf(`# total line budget reached; ${f.path} and smaller files not shown`));
|
|
850
|
+
continue;
|
|
851
|
+
}
|
|
852
|
+
const lines = records(gitBytes(cwd, ["diff", range, "--", f.path]));
|
|
853
|
+
const kept = lines.slice(0, room);
|
|
854
|
+
if (kept.length < lines.length && room < guard.perFileLines) ceilingHit = true;
|
|
855
|
+
add(lineOf(`### ${f.path}`));
|
|
856
|
+
add(joinLines(kept));
|
|
857
|
+
if (kept.length < lines.length) {
|
|
858
|
+
omitted.push(f.path);
|
|
859
|
+
add(lineOf(`# ${lines.length - kept.length} more lines of ${f.path} not shown`));
|
|
860
|
+
}
|
|
861
|
+
add(lineOf(""));
|
|
862
|
+
}
|
|
863
|
+
omitted.sort((a, b) => a.localeCompare(b));
|
|
864
|
+
content = Buffer.concat([
|
|
865
|
+
lineOf(
|
|
866
|
+
`# ${PARTIAL_MARK}: ${range} has ${diffLines} diff lines across ${stat.filesChanged} files; showing the ${shown.length} largest files, ${guard.perFileLines} lines each, at most ${guard.totalLines} lines in all. Say "${PARTIAL_MARK}" in any verdict read from this file.`,
|
|
867
|
+
),
|
|
868
|
+
lineOf(`# not shown whole: ${omitted.join(", ")}`),
|
|
869
|
+
lineOf(""),
|
|
870
|
+
stat0,
|
|
871
|
+
lineOf(""),
|
|
872
|
+
...body,
|
|
873
|
+
]);
|
|
874
|
+
}
|
|
875
|
+
const raw = partial && keep.rawDir !== null ? keepRaw(out, keep.rawDir, full) : null;
|
|
876
|
+
fs.mkdirSync(path.dirname(out), { recursive: true });
|
|
877
|
+
fs.writeFileSync(out, content);
|
|
878
|
+
const record: ClampRecord = {
|
|
879
|
+
artifact,
|
|
880
|
+
clamped: partial,
|
|
881
|
+
origLines: diffLines,
|
|
882
|
+
keptLines: partial ? records(content).length : diffLines,
|
|
883
|
+
origBytes: full.length,
|
|
884
|
+
keptBytes: content.length,
|
|
885
|
+
lineCapped: 0,
|
|
886
|
+
ceilingHit,
|
|
887
|
+
raw: raw === null ? null : outboxRel(cwd, raw),
|
|
888
|
+
source: `git diff ${range} -- . ${DIFF_EXCLUDES.map((e) => `':(exclude)${e}'`).join(" ")}`,
|
|
889
|
+
fetchedAt,
|
|
890
|
+
};
|
|
891
|
+
return { range, stat, diffLines, partial, omitted, record };
|
|
892
|
+
}
|
|
893
|
+
|
|
894
|
+
// ---------------------------------------------------------------------------
|
|
895
|
+
// Brief — what one group's build agents read
|
|
896
|
+
//
|
|
897
|
+
// The engine writes it so the orchestrator never reads the plan: the plan's
|
|
898
|
+
// why and what, where the group sits, the group's open task blocks verbatim,
|
|
899
|
+
// one-line summaries of the earlier tasks they depend on, the Reuse Inventory
|
|
900
|
+
// rows and Architecture entries for the open tasks' files, and the deviations
|
|
901
|
+
// note when there is one.
|
|
902
|
+
// ---------------------------------------------------------------------------
|
|
903
|
+
|
|
904
|
+
/** A brief whose work section is over this many bytes warns: the group may not fit one fresh context. */
|
|
905
|
+
export const BRIEF_WORK_WARN_BYTES = 8 * 1024;
|
|
906
|
+
|
|
907
|
+
/** The plan sections a brief carries as its why and what, by heading text. */
|
|
908
|
+
const BRIEF_SECTIONS = ["Context & Goals", "Narrative", "Success Criteria", "Out of Scope"];
|
|
909
|
+
|
|
910
|
+
/** The plan-execute logs whose `DONE — TASK N` lines mark a task done. */
|
|
911
|
+
const EXECUTE_LOG = /^build-plan-execute-.+-log\.md$/;
|
|
912
|
+
|
|
913
|
+
/** A heading's text without leading emoji and marks. */
|
|
914
|
+
const headingText = (text: string) => text.replace(/^[^A-Za-z0-9]+/, "").trim();
|
|
915
|
+
|
|
916
|
+
/**
|
|
917
|
+
* The body of the first heading named `name`, up to the next heading of the
|
|
918
|
+
* same or a higher level. Lines inside code fences are never headings.
|
|
919
|
+
*/
|
|
920
|
+
function planSection(lines: string[], name: string): string | undefined {
|
|
921
|
+
let start = -1;
|
|
922
|
+
let level = 0;
|
|
923
|
+
let fence = false;
|
|
924
|
+
for (let i = 0; i < lines.length; i++) {
|
|
925
|
+
const line = lines[i]!;
|
|
926
|
+
if (/^\s*(`{3,}|~{3,})/.test(line)) fence = !fence;
|
|
927
|
+
const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
|
|
928
|
+
if (m === null) continue;
|
|
929
|
+
if (start >= 0 && m[1]!.length <= level) return lines.slice(start, i).join("\n").trim();
|
|
930
|
+
if (start < 0 && headingText(m[2]!) === name) {
|
|
931
|
+
start = i + 1;
|
|
932
|
+
level = m[1]!.length;
|
|
933
|
+
}
|
|
934
|
+
}
|
|
935
|
+
return start < 0 ? undefined : lines.slice(start).join("\n").trim();
|
|
936
|
+
}
|
|
937
|
+
|
|
938
|
+
/** Every task number a plan-execute log in `dir` records `DONE`. */
|
|
939
|
+
function loggedDone(dir: string): Set<number> {
|
|
940
|
+
const done = new Set<number>();
|
|
941
|
+
if (!fs.existsSync(dir)) return done;
|
|
942
|
+
for (const f of fs.readdirSync(dir).filter((f) => EXECUTE_LOG.test(f)))
|
|
943
|
+
for (const n of doneTasks(fs.readFileSync(path.join(dir, f), "utf-8"))) done.add(n);
|
|
944
|
+
return done;
|
|
945
|
+
}
|
|
946
|
+
|
|
947
|
+
/** The plan sections whose entries a brief copies for the group's files. */
|
|
948
|
+
const INVENTORY_SECTION = "Reuse Inventory";
|
|
949
|
+
const ARCHITECTURE_SECTION = "Architecture & Component Changes";
|
|
950
|
+
|
|
951
|
+
/** Backticked repo-relative paths in `text`, normalised. */
|
|
952
|
+
const backticked = (text: string) =>
|
|
953
|
+
[...text.matchAll(/`([^`]+)`/g)].map((m) => path.posix.normalize(m[1]!));
|
|
954
|
+
|
|
955
|
+
/**
|
|
956
|
+
* The Reuse Inventory table's header and separator lines (`reuseInventory`), and its rows
|
|
957
|
+
* whose `File` cell names a file in `files`. No table or no `File` column → no rows.
|
|
958
|
+
*/
|
|
959
|
+
function inventoryRows(lines: string[], files: Set<string>): { head: string[]; rows: string[] } {
|
|
960
|
+
const table = reuseInventory(lines.join("\n"));
|
|
961
|
+
if (table === null) return { head: [], rows: [] };
|
|
962
|
+
const rows = table.rows.filter((r) => r.files.some((f) => files.has(f))).map((r) => r.line);
|
|
963
|
+
return { head: table.head, rows };
|
|
964
|
+
}
|
|
965
|
+
|
|
966
|
+
/**
|
|
967
|
+
* The Architecture & Component Changes entries whose heading names a file in `files`:
|
|
968
|
+
* the heading through the line before the next heading of the same or a higher level.
|
|
969
|
+
* Lines inside code fences are never headings.
|
|
970
|
+
*/
|
|
971
|
+
function architectureEntries(lines: string[], files: Set<string>): string[] {
|
|
972
|
+
const body = (planSection(lines, ARCHITECTURE_SECTION) ?? "").split("\n");
|
|
973
|
+
const heads: Array<{ i: number; level: number; text: string }> = [];
|
|
974
|
+
let fence = false;
|
|
975
|
+
body.forEach((line, i) => {
|
|
976
|
+
if (/^\s*(`{3,}|~{3,})/.test(line)) fence = !fence;
|
|
977
|
+
const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
|
|
978
|
+
if (m !== null) heads.push({ i, level: m[1]!.length, text: m[2]! });
|
|
979
|
+
});
|
|
980
|
+
return heads.flatMap((h, k) => {
|
|
981
|
+
if (!backticked(h.text).some((f) => files.has(f))) return [];
|
|
982
|
+
const end = heads.slice(k + 1).find((n) => n.level <= h.level)?.i ?? body.length;
|
|
983
|
+
return [body.slice(h.i, end).join("\n").trim()];
|
|
984
|
+
});
|
|
985
|
+
}
|
|
986
|
+
|
|
987
|
+
/** The next free `build-brief-{group}-{n}.md` in `dir`. */
|
|
988
|
+
function nextBriefPath(dir: string, group: number): string {
|
|
989
|
+
const re = new RegExp(`^build-brief-${group}-([0-9]+)\\.md$`);
|
|
990
|
+
const taken = fs.existsSync(dir)
|
|
991
|
+
? fs.readdirSync(dir).map((f) => Number(re.exec(f)?.[1] ?? 0))
|
|
992
|
+
: [];
|
|
993
|
+
return path.join(dir, `build-brief-${group}-${Math.max(0, ...taken) + 1}.md`);
|
|
994
|
+
}
|
|
995
|
+
|
|
996
|
+
export interface BriefInput {
|
|
997
|
+
plan: string;
|
|
998
|
+
/** The plan's path as given, named where left-out entries can be read. */
|
|
999
|
+
planFile: string;
|
|
1000
|
+
group: PlanGroup;
|
|
1001
|
+
groups: PlanGroup[];
|
|
1002
|
+
isDone: (t: PlanTaskBlock) => boolean;
|
|
1003
|
+
reds: Array<Record<string, unknown>>;
|
|
1004
|
+
note?: string;
|
|
1005
|
+
}
|
|
1006
|
+
|
|
1007
|
+
/** The brief's text and its work section's size in bytes. */
|
|
1008
|
+
export function briefText(o: BriefInput): { text: string; workBytes: number } {
|
|
1009
|
+
const lines = o.plan.split("\n");
|
|
1010
|
+
const title = lines.find((l) => /^#\s/.test(l))?.replace(/^#\s+/, "") ?? "Plan";
|
|
1011
|
+
const out = [`# Brief: group ${o.group.group} — ${o.group.title}`, "", `Plan: ${title}`, ""];
|
|
1012
|
+
|
|
1013
|
+
out.push("## Why and what", "");
|
|
1014
|
+
for (const name of BRIEF_SECTIONS) {
|
|
1015
|
+
const body = planSection(lines, name);
|
|
1016
|
+
if (body !== undefined && body !== "") out.push(`### ${name}`, "", body, "");
|
|
1017
|
+
}
|
|
1018
|
+
|
|
1019
|
+
out.push("## Where it fits", "");
|
|
1020
|
+
const nextGroup = o.groups.find(
|
|
1021
|
+
(g) => g.group > o.group.group && g.tasks.some((t) => !o.isDone(t)),
|
|
1022
|
+
);
|
|
1023
|
+
for (const g of o.groups) {
|
|
1024
|
+
const state = g.tasks.every(o.isDone)
|
|
1025
|
+
? "done"
|
|
1026
|
+
: g === o.group
|
|
1027
|
+
? "this group"
|
|
1028
|
+
: g === nextGroup
|
|
1029
|
+
? "next"
|
|
1030
|
+
: g.group > o.group.group
|
|
1031
|
+
? "later"
|
|
1032
|
+
: "open";
|
|
1033
|
+
out.push(`- Group ${g.group}: ${g.title} — ${state}`);
|
|
1034
|
+
for (const t of g.tasks)
|
|
1035
|
+
out.push(` - TASK ${t.task}: ${t.title} — ${o.isDone(t) ? "done" : "open"}`);
|
|
1036
|
+
}
|
|
1037
|
+
out.push("");
|
|
1038
|
+
|
|
1039
|
+
const open = o.group.tasks.filter((t) => !o.isDone(t));
|
|
1040
|
+
const work = ["## The work", ""];
|
|
1041
|
+
for (const t of open) work.push(t.text.trim(), "");
|
|
1042
|
+
const openNums = new Set(open.map((t) => t.task));
|
|
1043
|
+
const reds = o.reds.filter((r) => openNums.has(Number(r.task)));
|
|
1044
|
+
if (reds.length > 0) {
|
|
1045
|
+
work.push("### Reds already recorded", "");
|
|
1046
|
+
for (const r of reds)
|
|
1047
|
+
work.push(
|
|
1048
|
+
`- TASK ${Number(r.task)}: red already recorded for \`${String(r.test)}\` \`${String(r.testName)}\` — test written and seen failing; code may be partly done in the files it names`,
|
|
1049
|
+
);
|
|
1050
|
+
work.push("");
|
|
1051
|
+
}
|
|
1052
|
+
const deps = [...new Set(open.flatMap((t) => t.dependsOn))]
|
|
1053
|
+
.filter((n) => !o.group.tasks.some((t) => t.task === n))
|
|
1054
|
+
.sort((a, b) => a - b)
|
|
1055
|
+
.map((n) => o.groups.flatMap((g) => g.tasks).find((t) => t.task === n))
|
|
1056
|
+
.filter((t): t is PlanTaskBlock => t !== undefined);
|
|
1057
|
+
if (deps.length > 0) {
|
|
1058
|
+
work.push("### Earlier tasks this group depends on", "");
|
|
1059
|
+
for (const t of deps) {
|
|
1060
|
+
const files = [...new Set([...t.create, ...t.update, ...t.delete].map((r) => r.file))];
|
|
1061
|
+
const where = files.length > 0 ? ` — ${files.map((f) => `\`${f}\``).join(", ")}` : "";
|
|
1062
|
+
work.push(
|
|
1063
|
+
`- TASK ${t.task} (group ${t.group}, ${o.isDone(t) ? "done" : "open"}): ${t.title}${where}`,
|
|
1064
|
+
);
|
|
1065
|
+
}
|
|
1066
|
+
work.push("");
|
|
1067
|
+
}
|
|
1068
|
+
work.push(...planEntries(lines, open, work, o.planFile));
|
|
1069
|
+
out.push(...work);
|
|
1070
|
+
|
|
1071
|
+
if (o.note !== undefined) out.push("## Deviations", "", o.note.trim(), "");
|
|
1072
|
+
return {
|
|
1073
|
+
text: out.join("\n"),
|
|
1074
|
+
workBytes: Buffer.byteLength(work.join("\n")),
|
|
1075
|
+
};
|
|
1076
|
+
}
|
|
1077
|
+
|
|
1078
|
+
/**
|
|
1079
|
+
* The Reuse Inventory rows, then the Architecture entries, for the files on the open
|
|
1080
|
+
* tasks' CREATE / UPDATE / DELETE lines, each in plan order while the work section stays
|
|
1081
|
+
* within BRIEF_WORK_WARN_BYTES; the rest are counted in a closing line naming where to
|
|
1082
|
+
* read them.
|
|
1083
|
+
*/
|
|
1084
|
+
function planEntries(
|
|
1085
|
+
lines: string[],
|
|
1086
|
+
open: PlanTaskBlock[],
|
|
1087
|
+
work: string[],
|
|
1088
|
+
planFile: string,
|
|
1089
|
+
): string[] {
|
|
1090
|
+
const files = new Set(
|
|
1091
|
+
open.flatMap((t) =>
|
|
1092
|
+
[...t.create, ...t.update, ...t.delete].map((r) => path.posix.normalize(r.file)),
|
|
1093
|
+
),
|
|
1094
|
+
);
|
|
1095
|
+
const inventory = inventoryRows(lines, files);
|
|
1096
|
+
const arch = architectureEntries(lines, files);
|
|
1097
|
+
const keptRows: string[] = [];
|
|
1098
|
+
const keptArch: string[] = [];
|
|
1099
|
+
const render = (rowsLeft: number, archLeft: number) => {
|
|
1100
|
+
const part: string[] = [];
|
|
1101
|
+
if (keptRows.length > 0)
|
|
1102
|
+
part.push("### Reuse Inventory rows", "", ...inventory.head, ...keptRows, "");
|
|
1103
|
+
if (keptArch.length > 0)
|
|
1104
|
+
part.push("### Architecture entries", "", ...keptArch.flatMap((e) => [e, ""]));
|
|
1105
|
+
if (rowsLeft + archLeft > 0)
|
|
1106
|
+
part.push(
|
|
1107
|
+
`Reuse Inventory rows left out: ${rowsLeft}; Architecture entries left out: ${archLeft} — read them in ${planFile} § ${INVENTORY_SECTION} and § ${ARCHITECTURE_SECTION}.`,
|
|
1108
|
+
"",
|
|
1109
|
+
);
|
|
1110
|
+
return part;
|
|
1111
|
+
};
|
|
1112
|
+
const fits = (rowsLeft: number, archLeft: number) =>
|
|
1113
|
+
Buffer.byteLength([...work, ...render(rowsLeft, archLeft)].join("\n")) <= BRIEF_WORK_WARN_BYTES;
|
|
1114
|
+
// The counts passed to `fits` are those not yet kept, an upper bound on the final ones.
|
|
1115
|
+
let rowsLeft = inventory.rows.length;
|
|
1116
|
+
let archLeft = arch.length;
|
|
1117
|
+
for (const row of inventory.rows) {
|
|
1118
|
+
keptRows.push(row);
|
|
1119
|
+
if (fits(rowsLeft - 1, archLeft)) rowsLeft--;
|
|
1120
|
+
else keptRows.pop();
|
|
1121
|
+
}
|
|
1122
|
+
for (const entry of arch) {
|
|
1123
|
+
keptArch.push(entry);
|
|
1124
|
+
if (fits(rowsLeft, archLeft - 1)) archLeft--;
|
|
1125
|
+
else keptArch.pop();
|
|
1126
|
+
}
|
|
1127
|
+
return render(rowsLeft, archLeft);
|
|
1128
|
+
}
|
|
1129
|
+
|
|
596
1130
|
// ---------------------------------------------------------------------------
|
|
597
1131
|
// Command
|
|
598
1132
|
// ---------------------------------------------------------------------------
|
|
599
1133
|
|
|
1134
|
+
const RUN_BLOCK_FLAGS: FlagSpec[] = [
|
|
1135
|
+
{ name: "idx", type: "string", required: true, help: "block ordinal from list-blocks" },
|
|
1136
|
+
{
|
|
1137
|
+
name: "script",
|
|
1138
|
+
type: "string",
|
|
1139
|
+
required: true,
|
|
1140
|
+
help: "file holding the block body as customised for this failure (run with bash)",
|
|
1141
|
+
},
|
|
1142
|
+
FID_FLAG,
|
|
1143
|
+
MONTH_FLAG,
|
|
1144
|
+
...ATTEMPT_FLAGS,
|
|
1145
|
+
];
|
|
1146
|
+
|
|
1147
|
+
const RUN_BLOCK_OUTPUT: Record<string, string> = {
|
|
1148
|
+
outcome: "checked (data written) | self-skipped (skip line written) | silent (nothing) | not-run",
|
|
1149
|
+
artifact: "the artifact path, or null when nothing was written",
|
|
1150
|
+
skip: "the block's [context-fetch:<name>] stderr line, or null",
|
|
1151
|
+
clamp: "the payload's clamp record, or null",
|
|
1152
|
+
reason: "why the block was not run, or null",
|
|
1153
|
+
};
|
|
1154
|
+
|
|
600
1155
|
export const contextCommand: CommandSpec = {
|
|
601
1156
|
noun: "context",
|
|
602
1157
|
summary:
|
|
603
|
-
"Clamp context artifacts; scan ledgers; list, run and record consumer context-fetch blocks.",
|
|
1158
|
+
"Clamp context artifacts; scan ledgers; write the run's diff and a build group's brief; list, run and record consumer context-fetch blocks.",
|
|
604
1159
|
verbs: {
|
|
605
1160
|
clamp: {
|
|
606
1161
|
summary: "Clamp an artifact to a size profile in place (a backstop, not a routine cap).",
|
|
607
1162
|
flags: [
|
|
608
1163
|
{ name: "artifact", type: "string", required: true, help: "file to clamp" },
|
|
609
1164
|
{ name: "profile", type: "string", required: true, help: "ledger | debug-evidence" },
|
|
1165
|
+
{
|
|
1166
|
+
name: "source",
|
|
1167
|
+
type: "string",
|
|
1168
|
+
help: "the exact command and inputs that produced the artifact (recorded with the time)",
|
|
1169
|
+
},
|
|
610
1170
|
...LOG_FLAGS,
|
|
611
1171
|
],
|
|
612
1172
|
output: RECORD_OUTPUT,
|
|
613
|
-
exitCodes: {
|
|
1173
|
+
exitCodes: {
|
|
1174
|
+
[EXIT_ARTIFACT]:
|
|
1175
|
+
"artifact missing, unreadable, or could not be replaced; or its original could not be kept",
|
|
1176
|
+
},
|
|
614
1177
|
run: (ctx) => {
|
|
615
1178
|
const artifact = String(ctx.flags.artifact);
|
|
1179
|
+
const keep: Provenance = {
|
|
1180
|
+
rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
|
|
1181
|
+
source: str(ctx.flags.source),
|
|
1182
|
+
};
|
|
616
1183
|
const record = clampFile(
|
|
617
1184
|
path.resolve(ctx.cwd, artifact),
|
|
618
1185
|
String(ctx.flags.profile),
|
|
619
1186
|
artifact,
|
|
1187
|
+
keep,
|
|
620
1188
|
);
|
|
1189
|
+
warnNoRaw(ctx, record, keep);
|
|
621
1190
|
const log = logPath(ctx);
|
|
622
1191
|
if (log !== undefined) appendRecord(log, record);
|
|
623
1192
|
if (record.clamped)
|
|
@@ -672,6 +1241,7 @@ export const contextCommand: CommandSpec = {
|
|
|
672
1241
|
kept: "lines written (at most 40)",
|
|
673
1242
|
clamp: "the clamp record",
|
|
674
1243
|
},
|
|
1244
|
+
textOmit: ["clamp"],
|
|
675
1245
|
exitCodes: { [EXIT_ARTIFACT]: "artifact could not be written or replaced" },
|
|
676
1246
|
run: (ctx) => {
|
|
677
1247
|
const log = logPath(ctx);
|
|
@@ -683,18 +1253,216 @@ export const contextCommand: CommandSpec = {
|
|
|
683
1253
|
}
|
|
684
1254
|
const sourceFile = path.resolve(ctx.cwd, String(ctx.flags.source));
|
|
685
1255
|
const source = fs.existsSync(sourceFile) ? fs.readFileSync(sourceFile, "utf-8") : undefined;
|
|
686
|
-
const
|
|
1256
|
+
const terms = String(ctx.flags.terms);
|
|
1257
|
+
const scan = ledgerScan(source, terms);
|
|
687
1258
|
const artifact = String(ctx.flags.artifact);
|
|
688
1259
|
const out = path.resolve(ctx.cwd, artifact);
|
|
689
1260
|
fs.mkdirSync(path.dirname(out), { recursive: true });
|
|
690
1261
|
fs.writeFileSync(out, scan.content);
|
|
691
|
-
const
|
|
1262
|
+
const keep: Provenance = {
|
|
1263
|
+
rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
|
|
1264
|
+
source: `bkit context ledger-scan --source=${String(ctx.flags.source)} --terms="${terms}"`,
|
|
1265
|
+
};
|
|
1266
|
+
const clamp = clampFile(out, "ledger", artifact, keep);
|
|
1267
|
+
warnNoRaw(ctx, clamp, keep);
|
|
692
1268
|
if (log !== undefined) appendRecord(log, clamp);
|
|
693
1269
|
ctx.log(`${artifact}: ${scan.total} matching line(s), ${scan.kept} kept`);
|
|
694
1270
|
ctx.emit({ total: scan.total, kept: scan.kept, clamp });
|
|
695
1271
|
return EXIT.OK;
|
|
696
1272
|
},
|
|
697
1273
|
},
|
|
1274
|
+
diff: {
|
|
1275
|
+
summary:
|
|
1276
|
+
"Write the run's diff ({base}...HEAD, docs/plans/** excluded) as one artifact — whole, or a per-file budget past the guard — and print its numbers.",
|
|
1277
|
+
flags: [
|
|
1278
|
+
{ name: "artifact", type: "string", required: true, help: "file to write" },
|
|
1279
|
+
{
|
|
1280
|
+
name: "base",
|
|
1281
|
+
type: "string",
|
|
1282
|
+
help: `merge base or a group's start commit (default ${DIFF_BASE})`,
|
|
1283
|
+
},
|
|
1284
|
+
...LOG_FLAGS,
|
|
1285
|
+
{
|
|
1286
|
+
name: "reset-log",
|
|
1287
|
+
type: "boolean",
|
|
1288
|
+
help: "empty the clamp log first (the step's first writer)",
|
|
1289
|
+
},
|
|
1290
|
+
],
|
|
1291
|
+
output: {
|
|
1292
|
+
artifact: "the artifact path as given",
|
|
1293
|
+
base: "the base used",
|
|
1294
|
+
range: "the range diffed ({base}...HEAD)",
|
|
1295
|
+
filesChanged: "files in the diff (--numstat, same excludes)",
|
|
1296
|
+
linesAdded: "lines added",
|
|
1297
|
+
linesDeleted: "lines deleted",
|
|
1298
|
+
linesChanged: "linesAdded + linesDeleted",
|
|
1299
|
+
diffLines: "lines in the whole diff",
|
|
1300
|
+
partial: `true when the diff exceeded ${DIFF_GUARD.fullLines} lines and the per-file budget (${DIFF_GUARD.topFiles} files, ${DIFF_GUARD.perFileLines} lines each, ${DIFF_GUARD.totalLines} in all) was written instead`,
|
|
1301
|
+
omitted:
|
|
1302
|
+
"files whose diff is not in the artifact whole (not shown, or cut); [] unless partial — the artifact's second line lists them too",
|
|
1303
|
+
clamp:
|
|
1304
|
+
"the clamp record (clamped = partial; raw = the whole diff in the outbox when partial)",
|
|
1305
|
+
},
|
|
1306
|
+
textOmit: ["clamp"],
|
|
1307
|
+
exitCodes: {
|
|
1308
|
+
[EXIT_BASE]: "--base does not name a commit",
|
|
1309
|
+
[EXIT_ARTIFACT]: "the artifact could not be written",
|
|
1310
|
+
},
|
|
1311
|
+
run: (ctx) => {
|
|
1312
|
+
const base = str(ctx.flags.base) ?? DIFF_BASE;
|
|
1313
|
+
if (git(ctx.cwd, ["rev-parse", "-q", "--verify", `${base}^{commit}`]) === null) {
|
|
1314
|
+
throw new CommandError(
|
|
1315
|
+
EXIT_BASE,
|
|
1316
|
+
`--base ${base} does not name a commit (fetch origin, or pass the group's start sha)`,
|
|
1317
|
+
);
|
|
1318
|
+
}
|
|
1319
|
+
const artifact = String(ctx.flags.artifact);
|
|
1320
|
+
const log = logPath(ctx);
|
|
1321
|
+
if (ctx.flags.resetLog === true) {
|
|
1322
|
+
if (log === undefined)
|
|
1323
|
+
throw new CommandError(EXIT.USAGE, "--reset-log needs --log, or --fid and --step");
|
|
1324
|
+
fs.mkdirSync(path.dirname(log), { recursive: true });
|
|
1325
|
+
fs.writeFileSync(log, "");
|
|
1326
|
+
}
|
|
1327
|
+
const written = tryWriteDiffArtifact(
|
|
1328
|
+
ctx.cwd,
|
|
1329
|
+
path.resolve(ctx.cwd, artifact),
|
|
1330
|
+
artifact,
|
|
1331
|
+
`${base}...HEAD`,
|
|
1332
|
+
DIFF_GUARD,
|
|
1333
|
+
{ rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)) },
|
|
1334
|
+
);
|
|
1335
|
+
if (!written.ok) throw new CommandError(EXIT_ARTIFACT, `${artifact}: ${written.error}`);
|
|
1336
|
+
const result = written.result;
|
|
1337
|
+
if (log !== undefined) appendRecord(log, result.record);
|
|
1338
|
+
if (result.partial) {
|
|
1339
|
+
ctx.log(
|
|
1340
|
+
`${artifact}: ${result.diffLines} diff lines, over the ${DIFF_GUARD.fullLines}-line guard — per-file budget written (${PARTIAL_MARK})`,
|
|
1341
|
+
);
|
|
1342
|
+
}
|
|
1343
|
+
ctx.emit({
|
|
1344
|
+
artifact,
|
|
1345
|
+
base,
|
|
1346
|
+
range: result.range,
|
|
1347
|
+
...result.stat,
|
|
1348
|
+
diffLines: result.diffLines,
|
|
1349
|
+
partial: result.partial,
|
|
1350
|
+
omitted: result.omitted,
|
|
1351
|
+
clamp: result.record,
|
|
1352
|
+
});
|
|
1353
|
+
return EXIT.OK;
|
|
1354
|
+
},
|
|
1355
|
+
},
|
|
1356
|
+
brief: {
|
|
1357
|
+
summary:
|
|
1358
|
+
"Write one group's brief (why and what, where it fits, its open task blocks, the earlier tasks they depend on, the Reuse Inventory rows and Architecture entries for their files, deviations) as build-brief-{group}-{n}.md, and print only its path and sizes.",
|
|
1359
|
+
flags: [
|
|
1360
|
+
{ name: "plan", type: "string", required: true, help: "the plan file" },
|
|
1361
|
+
{ name: "group", type: "string", help: "the group to brief" },
|
|
1362
|
+
{
|
|
1363
|
+
name: "next",
|
|
1364
|
+
type: "boolean",
|
|
1365
|
+
help: "brief the first group with an open task (none open → nothing written, group null)",
|
|
1366
|
+
},
|
|
1367
|
+
{
|
|
1368
|
+
name: "dir",
|
|
1369
|
+
type: "string",
|
|
1370
|
+
required: true,
|
|
1371
|
+
help: "the run's logs folder: the brief is written there, and its build-plan-execute-*-log.md DONE lines mark tasks done",
|
|
1372
|
+
},
|
|
1373
|
+
{
|
|
1374
|
+
name: "file",
|
|
1375
|
+
type: "string",
|
|
1376
|
+
help: "status.jsonl, to name the reds already recorded for open tasks",
|
|
1377
|
+
},
|
|
1378
|
+
{
|
|
1379
|
+
name: "note-file",
|
|
1380
|
+
type: "string",
|
|
1381
|
+
help: "text for the Deviations section (left out when not given)",
|
|
1382
|
+
},
|
|
1383
|
+
],
|
|
1384
|
+
output: {
|
|
1385
|
+
artifact: "the brief's path (null when --next finds no open group)",
|
|
1386
|
+
bytes: "the brief's size in bytes",
|
|
1387
|
+
group: "the group briefed (null when --next finds no open group)",
|
|
1388
|
+
tasks: "the open task numbers the brief carries",
|
|
1389
|
+
workBytes: "the work section's size in bytes (0 when --next finds no open group)",
|
|
1390
|
+
workCap: `the work section's cap in bytes (${BRIEF_WORK_WARN_BYTES}): Reuse Inventory rows and Architecture entries past it are left out and counted; task blocks over it warn on stderr`,
|
|
1391
|
+
},
|
|
1392
|
+
exitCodes: {
|
|
1393
|
+
[EXIT_ARTIFACT]: "the plan or note file is missing, or the plan's blocks do not parse",
|
|
1394
|
+
[EXIT_NO_STATUS]: "--file names a missing or malformed status.jsonl",
|
|
1395
|
+
},
|
|
1396
|
+
run: (ctx) => {
|
|
1397
|
+
const groupFlag = positiveInt(ctx.flags.group, "group");
|
|
1398
|
+
if ((groupFlag === undefined) === (ctx.flags.next !== true))
|
|
1399
|
+
throw new CommandError(EXIT.USAGE, "give exactly one of --group=N and --next");
|
|
1400
|
+
const planFile = path.resolve(ctx.cwd, String(ctx.flags.plan));
|
|
1401
|
+
if (!fs.existsSync(planFile))
|
|
1402
|
+
throw new CommandError(EXIT_ARTIFACT, `${String(ctx.flags.plan)} does not exist`);
|
|
1403
|
+
const plan = fs.readFileSync(planFile, "utf-8");
|
|
1404
|
+
const blocks = parsePlanBlocks(plan);
|
|
1405
|
+
if (blocks.errors.length > 0) {
|
|
1406
|
+
const e = blocks.errors[0]!;
|
|
1407
|
+
throw new CommandError(
|
|
1408
|
+
EXIT_ARTIFACT,
|
|
1409
|
+
`${String(ctx.flags.plan)}:${e.line}: ${e.message} — run \`bkit tests plan-check\``,
|
|
1410
|
+
);
|
|
1411
|
+
}
|
|
1412
|
+
const dir = path.resolve(ctx.cwd, String(ctx.flags.dir));
|
|
1413
|
+
const done = loggedDone(dir);
|
|
1414
|
+
const isDone = (t: PlanTaskBlock) => t.done || done.has(t.task);
|
|
1415
|
+
const group =
|
|
1416
|
+
groupFlag === undefined
|
|
1417
|
+
? blocks.groups.find((g) => g.tasks.some((t) => !isDone(t)))
|
|
1418
|
+
: blocks.groups.find((g) => g.group === groupFlag);
|
|
1419
|
+
if (group === undefined && groupFlag !== undefined)
|
|
1420
|
+
throw new CommandError(EXIT.USAGE, `the plan has no group ${groupFlag}`);
|
|
1421
|
+
if (group === undefined) {
|
|
1422
|
+
ctx.emit({
|
|
1423
|
+
artifact: null,
|
|
1424
|
+
bytes: 0,
|
|
1425
|
+
group: null,
|
|
1426
|
+
tasks: [],
|
|
1427
|
+
workBytes: 0,
|
|
1428
|
+
workCap: BRIEF_WORK_WARN_BYTES,
|
|
1429
|
+
});
|
|
1430
|
+
return EXIT.OK;
|
|
1431
|
+
}
|
|
1432
|
+
const noteFlag = str(ctx.flags.noteFile);
|
|
1433
|
+
const noteFile = noteFlag === undefined ? undefined : path.resolve(ctx.cwd, noteFlag);
|
|
1434
|
+
if (noteFile !== undefined && !fs.existsSync(noteFile))
|
|
1435
|
+
throw new CommandError(EXIT_ARTIFACT, `${noteFlag} does not exist`);
|
|
1436
|
+
const status = str(ctx.flags.file);
|
|
1437
|
+
const { text, workBytes } = briefText({
|
|
1438
|
+
plan,
|
|
1439
|
+
planFile: String(ctx.flags.plan),
|
|
1440
|
+
group,
|
|
1441
|
+
groups: blocks.groups,
|
|
1442
|
+
isDone,
|
|
1443
|
+
reds: status === undefined ? [] : redRows(path.resolve(ctx.cwd, status), "build"),
|
|
1444
|
+
note: noteFile === undefined ? undefined : fs.readFileSync(noteFile, "utf-8"),
|
|
1445
|
+
});
|
|
1446
|
+
const out = nextBriefPath(dir, group.group);
|
|
1447
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
1448
|
+
fs.writeFileSync(out, text);
|
|
1449
|
+
if (workBytes > BRIEF_WORK_WARN_BYTES) {
|
|
1450
|
+
ctx.log(
|
|
1451
|
+
`${out}: the work section is ${humanBytes(workBytes)}, over ${humanBytes(BRIEF_WORK_WARN_BYTES)} — the group may not fit one fresh context`,
|
|
1452
|
+
);
|
|
1453
|
+
}
|
|
1454
|
+
const artifact = path.isAbsolute(String(ctx.flags.dir)) ? out : path.relative(ctx.cwd, out);
|
|
1455
|
+
ctx.emit({
|
|
1456
|
+
artifact,
|
|
1457
|
+
bytes: Buffer.byteLength(text),
|
|
1458
|
+
group: group.group,
|
|
1459
|
+
tasks: group.tasks.filter((t) => !isDone(t)).map((t) => t.task),
|
|
1460
|
+
workBytes,
|
|
1461
|
+
workCap: BRIEF_WORK_WARN_BYTES,
|
|
1462
|
+
});
|
|
1463
|
+
return EXIT.OK;
|
|
1464
|
+
},
|
|
1465
|
+
},
|
|
698
1466
|
"list-blocks": {
|
|
699
1467
|
summary: "Enumerate the consumer's context-fetch blocks and narrate coverage per context.",
|
|
700
1468
|
flags: [],
|
|
@@ -739,31 +1507,41 @@ export const contextCommand: CommandSpec = {
|
|
|
739
1507
|
"run-block": {
|
|
740
1508
|
summary:
|
|
741
1509
|
"Run one customised block; write its output fenced (clamped first), its skip line, or nothing.",
|
|
1510
|
+
flags: RUN_BLOCK_FLAGS,
|
|
1511
|
+
output: RUN_BLOCK_OUTPUT,
|
|
1512
|
+
textOmit: ["clamp"],
|
|
1513
|
+
exitCodes: {
|
|
1514
|
+
[EXIT_ARTIFACT]: "the payload could not be clamped or written",
|
|
1515
|
+
[EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
|
|
1516
|
+
},
|
|
1517
|
+
run: (ctx) => runBlock(ctx),
|
|
1518
|
+
},
|
|
1519
|
+
fetch: {
|
|
1520
|
+
summary:
|
|
1521
|
+
"run-block, with a JSON array of flat objects written as a markdown table; the raw output stays in the outbox.",
|
|
742
1522
|
flags: [
|
|
743
|
-
|
|
1523
|
+
...RUN_BLOCK_FLAGS,
|
|
744
1524
|
{
|
|
745
|
-
name: "
|
|
1525
|
+
name: "render",
|
|
746
1526
|
type: "string",
|
|
747
|
-
|
|
748
|
-
help: "file holding the block body as customised for this failure (run with bash)",
|
|
1527
|
+
help: "table (default): a JSON array of flat objects becomes a markdown table when it reads back unchanged, else the output is written as printed; raw: as printed",
|
|
749
1528
|
},
|
|
750
|
-
FID_FLAG,
|
|
751
|
-
MONTH_FLAG,
|
|
752
|
-
...ATTEMPT_FLAGS,
|
|
753
1529
|
],
|
|
754
1530
|
output: {
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
artifact: "the artifact path, or null when nothing was written",
|
|
758
|
-
skip: "the block's [context-fetch:<name>] stderr line, or null",
|
|
759
|
-
clamp: "the payload's clamp record, or null",
|
|
760
|
-
reason: "why the block was not run, or null",
|
|
1531
|
+
...RUN_BLOCK_OUTPUT,
|
|
1532
|
+
render: "table | raw: how the output was written; null when nothing was written",
|
|
761
1533
|
},
|
|
1534
|
+
textOmit: ["clamp"],
|
|
762
1535
|
exitCodes: {
|
|
763
1536
|
[EXIT_ARTIFACT]: "the payload could not be clamped or written",
|
|
764
1537
|
[EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
|
|
765
1538
|
},
|
|
766
|
-
run: (ctx) =>
|
|
1539
|
+
run: (ctx) => {
|
|
1540
|
+
const render = str(ctx.flags.render) ?? "table";
|
|
1541
|
+
if (!(RENDERS as readonly string[]).includes(render))
|
|
1542
|
+
throw new CommandError(EXIT.USAGE, `--render must be ${RENDERS.join("|")}`);
|
|
1543
|
+
return runBlock(ctx, render as Render);
|
|
1544
|
+
},
|
|
767
1545
|
},
|
|
768
1546
|
finalise: {
|
|
769
1547
|
summary:
|
|
@@ -796,6 +1574,7 @@ export const contextCommand: CommandSpec = {
|
|
|
796
1574
|
commit: "--record: the new commit's sha, else null",
|
|
797
1575
|
comment:
|
|
798
1576
|
"the step comment (with --number): verdict, contexts, artifact links, a NOT CONFIGURED line per context with no block; else null",
|
|
1577
|
+
commentFile: COMMENT_FILE_OUTPUT,
|
|
799
1578
|
},
|
|
800
1579
|
exitCodes: {
|
|
801
1580
|
[EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
|
|
@@ -878,6 +1657,7 @@ export const contextCommand: CommandSpec = {
|
|
|
878
1657
|
row: record ? written.row : null,
|
|
879
1658
|
commit: written.commit,
|
|
880
1659
|
comment,
|
|
1660
|
+
commentFile: commentFileOf(ctx.cwd, comment),
|
|
881
1661
|
});
|
|
882
1662
|
return written.code;
|
|
883
1663
|
},
|
|
@@ -885,7 +1665,22 @@ export const contextCommand: CommandSpec = {
|
|
|
885
1665
|
},
|
|
886
1666
|
};
|
|
887
1667
|
|
|
888
|
-
|
|
1668
|
+
/** A block's output as a checked markdown table, or why it stays as printed. */
|
|
1669
|
+
function tableOf(stdout: Buffer): { text: string } | { reason: string } {
|
|
1670
|
+
const parsed = parseJson(stdout.toString("utf-8"));
|
|
1671
|
+
if (!parsed.ok) return { reason: "not JSON" };
|
|
1672
|
+
const table = checkedTable(parsed.value);
|
|
1673
|
+
return table.ok ? { text: table.text } : { reason: table.reason };
|
|
1674
|
+
}
|
|
1675
|
+
|
|
1676
|
+
/**
|
|
1677
|
+
* Run consumer block `--idx` and write what it printed, fenced and clamped. With `render`
|
|
1678
|
+
* (`context fetch`), a JSON array of flat objects is written as a table instead; the
|
|
1679
|
+
* output as printed goes to the outbox first, and the record says which was written.
|
|
1680
|
+
*/
|
|
1681
|
+
function runBlock(ctx: RunContext, render?: Render): number {
|
|
1682
|
+
const shape = (out: Record<string, unknown>, written: Render | null) =>
|
|
1683
|
+
render === undefined ? out : { ...out, render: written };
|
|
889
1684
|
const idx = positiveInt(ctx.flags.idx, "idx")!;
|
|
890
1685
|
const attempt = debugAttempt(ctx);
|
|
891
1686
|
const fid = String(ctx.flags.fid);
|
|
@@ -895,7 +1690,7 @@ function runBlock(ctx: RunContext): number {
|
|
|
895
1690
|
const block = fetchBlocks(consumerSection(readContextMd(ctx) ?? "")).find((b) => b.idx === idx);
|
|
896
1691
|
const notRun = (reason: string) => {
|
|
897
1692
|
ctx.log(`context-fetch: ${reason} — NOT RUN`);
|
|
898
|
-
ctx.emit({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason });
|
|
1693
|
+
ctx.emit(shape({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason }, null));
|
|
899
1694
|
return EXIT.OK;
|
|
900
1695
|
};
|
|
901
1696
|
if (!block) return notRun(`no block ${idx} after <!-- bkit:end -->`);
|
|
@@ -909,6 +1704,7 @@ function runBlock(ctx: RunContext): number {
|
|
|
909
1704
|
return notRun(`block ${idx} (context=${block.context} name=${label}) has no fenced body`);
|
|
910
1705
|
|
|
911
1706
|
const repoRoot = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
|
|
1707
|
+
const fetchedAt = utcNow();
|
|
912
1708
|
// The inline block ran inside the step's shell, so these were in scope for it.
|
|
913
1709
|
const res = spawnSync("bash", [script], {
|
|
914
1710
|
cwd: ctx.cwd,
|
|
@@ -936,12 +1732,38 @@ function runBlock(ctx: RunContext): number {
|
|
|
936
1732
|
|
|
937
1733
|
if (stdout.some((b) => b !== 0x0a && b !== 0)) {
|
|
938
1734
|
fs.mkdirSync(path.dirname(out), { recursive: true });
|
|
939
|
-
|
|
940
|
-
|
|
1735
|
+
const keep: Provenance = {
|
|
1736
|
+
rawDir: rawDirFor(ctx.cwd, fid),
|
|
1737
|
+
source: fs.readFileSync(script, "utf-8"),
|
|
1738
|
+
fetchedAt,
|
|
1739
|
+
};
|
|
1740
|
+
let payload = asCaptured(stdout);
|
|
1741
|
+
let written: Render | null = null;
|
|
1742
|
+
if (render !== undefined) {
|
|
1743
|
+
const table = render === "table" ? tableOf(stdout) : null;
|
|
1744
|
+
if (table !== null && "text" in table) {
|
|
1745
|
+
// The table replaces the printed output: keep that output whole first.
|
|
1746
|
+
if (keep.rawDir !== null) keep.original = keepRaw(out, keep.rawDir, stdout);
|
|
1747
|
+
payload = Buffer.from(`${table.text}\n`);
|
|
1748
|
+
written = "table";
|
|
1749
|
+
} else {
|
|
1750
|
+
if (table !== null) ctx.log(`render: raw (${table.reason})`);
|
|
1751
|
+
written = "raw";
|
|
1752
|
+
}
|
|
1753
|
+
}
|
|
1754
|
+
fs.writeFileSync(out, payload);
|
|
1755
|
+
let clamp = clampFile(out, "debug-evidence", artifact, keep);
|
|
1756
|
+
warnNoRaw(ctx, clamp, keep);
|
|
1757
|
+
if (written !== null) {
|
|
1758
|
+
const raw = clamp.raw ?? (keep.original ? outboxRel(path.dirname(out), keep.original) : null);
|
|
1759
|
+
clamp = { ...clamp, raw, render: written };
|
|
1760
|
+
}
|
|
941
1761
|
appendRecord(clampLogPath(ctx.cwd, fid, "context-fetch", attempt), clamp);
|
|
942
1762
|
fs.writeFileSync(out, fenced(fs.readFileSync(out)));
|
|
943
1763
|
ctx.log(`${shown} CHECKED — data returned`);
|
|
944
|
-
ctx.emit(
|
|
1764
|
+
ctx.emit(
|
|
1765
|
+
shape({ outcome: "checked", artifact, skip: skip ?? null, clamp, reason: null }, written),
|
|
1766
|
+
);
|
|
945
1767
|
return EXIT.OK;
|
|
946
1768
|
}
|
|
947
1769
|
if (skip !== undefined) {
|
|
@@ -950,12 +1772,14 @@ function runBlock(ctx: RunContext): number {
|
|
|
950
1772
|
ctx.log(
|
|
951
1773
|
`${shown} SELF-SKIPPED (${skip}) — NOT CHECKED; this is NOT evidence that this source was clean (Trusted egress may also silently block the host — see .agents/context.md § Allowed domains)`,
|
|
952
1774
|
);
|
|
953
|
-
ctx.emit({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null });
|
|
1775
|
+
ctx.emit(shape({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null }, null));
|
|
954
1776
|
return EXIT.OK;
|
|
955
1777
|
}
|
|
956
1778
|
ctx.log(
|
|
957
1779
|
`${shown} produced neither data nor a skip breadcrumb — NOT CHECKED (unexpected silent exit; treat as unavailable, never as clean)`,
|
|
958
1780
|
);
|
|
959
|
-
ctx.emit(
|
|
1781
|
+
ctx.emit(
|
|
1782
|
+
shape({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null }, null),
|
|
1783
|
+
);
|
|
960
1784
|
return EXIT.OK;
|
|
961
1785
|
}
|