plumbbob 0.13.0 → 0.13.2

package/dist/verbs/checkpoint.js

@@ -12,7 +12,7 @@
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearPause, clearTick, detailPath, hasSession, intentPath, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
+import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearPause, clearTick, detailPath, hasSession, intentPath, readRun, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
 import { readCommitBody } from "../lib/commitbody.js";
 import { checkLatch } from "../lib/latch.js";
@@ -22,7 +22,8 @@ import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commit
 import { appendToSection, checkpointLogLine, logEntry, planLogLine } from "../lib/buildlog.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
 import { advisory, ending, notice, printEnding, transition } from "../lib/notice.js";
-import { boundaryEnding, planRecord, stepRecord } from "./handoff.js";
+import { boundaryEnding, detailsLink, parseDetailRange, planRecord, stepRecord } from "./handoff.js";
+import { isHarvestDetail } from "./harvest.js";
 /**
  * Land a step: latch, check gate, commit, record, return to the boundary.
  *
@@ -102,7 +103,12 @@ export async function checkpoint(cwd, args) {
     else {
         sha = headSha(root);
     }
-    clearDetail(root); // the detail is recorded in the Log below; clear it so no stale detail rides into the next step.
+    // The detail is recorded in the Log below; clear it so no stale detail rides
+    // into the next step. A stop's or a harvest's detail is the record's to
+    // clear, so it stays where it is.
+    if (!heldDetail(root)) {
+        clearDetail(root);
+    }
     appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
     const flipNotice = flipIntent(root, step);
     stampStepStat(root, undefined, step, 'landedAt', new Date().toISOString());
@@ -122,13 +128,18 @@ export async function checkpoint(cwd, args) {
     // pointer. Read after the flip and the ledger append, so the fold and the
     // pointer both see the boundary the human is standing at.
     const landed = boundaryEnding(root, activeBuild(root), step);
+    // A landing that completes the range a typed run marked owes the stop card:
+    // the record says so, and the relay check holds a turn that ends here.
+    const owes = landed.range !== null && readRun(root) === landed.range.item ? { range: landed.range.item, count: landed.range.count, step } : null;
     printEnding(root, {
         tier: 'orientation',
         render: 'checkpoint',
+        ...(owes === null ? {} : { owes }),
         text: ending({
             lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: leadDetail(sha, pointer) }),
             verdict: landed.verdict,
             advisories: [drift, flipNotice],
+            stop: landed.stop,
             pointer: landed.pointer,
         }),
     });
@@ -301,10 +312,11 @@ function flipIntent(root, step) {
 }
 /**
  * The lead line's trailing parenthetical: the short SHA, and where the Log
- * entry landed when one did, as the same `details:` clause Next Up carries.
+ * entry landed when one did, as the same short linked `details:` clause Next
+ * Up carries.
  */
 function leadDetail(sha, pointer) {
-    return pointer === null ? [sha.slice(0, 9)] : [sha.slice(0, 9), `details: \`${pointer}\``];
+    return pointer === null ? [sha.slice(0, 9)] : [sha.slice(0, 9), detailsLink(pointer.path, pointer.line)];
 }
 /**
  * Append the step's entry to the build-log's `## Log` section: the dated line,
@@ -313,8 +325,8 @@ function leadDetail(sha, pointer) {
  * The build's history accrues at each checkpoint instead of being reconstructed
  * at finish; the step's title is lifted from intent.md when still present.
  * Best-effort: a missing or odd build-log never blocks a checkpoint; the
- * `checkpoints` SHA is the source of truth. Returns where the line landed, as
- * `path:line` from the repo root, or null when nothing was written.
+ * `checkpoints` SHA is the source of truth. Returns where the line landed, or
+ * null when nothing was written.
  */
 function logCheckpoint(root, step, sha, record) {
     const date = new Date().toISOString().slice(0, 10);
@@ -328,8 +340,8 @@ function logPlan(root, sha, record) {
     return appendLog(root, planLogLine(new Date().toISOString().slice(0, 10), sha), record);
 }
 /**
- * Write one Log entry and say where its dated line landed (`path:line` from
- * the repo root), or null when the section is missing or the write failed.
+ * Write one Log entry and say where its dated line landed, or null when the
+ * section is missing or the write failed.
  */
 function appendLog(root, line, record) {
     try {
@@ -340,7 +352,7 @@ function appendLog(root, line, record) {
         }
         writeFileSync(path, updated);
         const at = updated.split('\n').lastIndexOf(line);
-        return at === -1 ? null : `${relative(root, path)}:${at + 1}`;
+        return at === -1 ? null : { path: relative(root, path), line: at + 1 };
     }
     catch {
         // best-effort ledger; never fail a checkpoint over the build-log.
@@ -459,13 +471,15 @@ function fallbackBody(root, step) {
  * the Log's record, and the caller clears it afterward. A missing or blank file
  * records nothing, and so does one whose header names a different step: that
  * file is a leftover, written after its own step had already landed, and
- * recording it would file one step's story under another. The plan commit
- * passes no step and takes the file as it is.
+ * recording it would file one step's story under another. A range's detail
+ * and a boundary harvest's record nothing here either: they are
+ * `plumbbob harvest`'s to record. The plan commit passes no step and takes the
+ * file as it is.
  */
 function readDetail(root, step) {
     try {
         const raw = readFileSync(detailPath(root), 'utf8').trim();
-        if (raw.length === 0) {
+        if (raw.length === 0 || (step !== null && heldDetail(root))) {
             return null;
         }
         const written = step === null ? null : parseDetailStep(raw);
@@ -475,6 +489,20 @@ function readDetail(root, step) {
         return null;
     }
 }
+/**
+ * Whether the detail file is one a step's checkpoint leaves alone: a range's,
+ * the stop card's wire, or a boundary harvest's, each read off its header and
+ * each recorded and cleared by `plumbbob harvest`.
+ */
+function heldDetail(root) {
+    try {
+        const raw = readFileSync(detailPath(root), 'utf8');
+        return parseDetailRange(raw) !== null || isHarvestDetail(raw);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The step's done-when line from intent.md, or null when absent or unreadable.
  */