@bensandee/tooling 0.91.0 → 0.92.1

package/dist/bin.mjs

@@ -175,7 +175,7 @@ function loadEnvFileForBin(rawArgs, bin, io = processIo) {
 //#region src/env-file-preload.ts
 const envFileLoad = loadEnvFileForBin(process.argv.slice(2), {
 	name: "bst",
-	version: "0.91.0"
+	version: "0.92.1"
 });
 //#endregion
 //#region ../cli-kit/src/logger.ts
@@ -5433,7 +5433,7 @@ function buildManagedDevDeps(ctx) {
 	const devDeps = { ...rootDevDeps(ctx.config) };
 	if (!isMonorepo) Object.assign(devDeps, perPackageDevDeps(ctx.config));
 	if (ctx.config.stack !== "none" || ctx.config.ci === "forgejo") devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.15.0";
-	if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.91.0";
+	if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.92.1";
 	if (ctx.config.useEslintPlugin && ctx.config.stack !== "none") devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.17.0";
 	if (wantsAgentCli(ctx)) devDeps[AGENT_CLI_PACKAGE] = "0.1.2";
 	if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
@@ -9305,6 +9305,8 @@ const GIT_GUIDE_BODY = [
 	"",
 	"If the bst agent drives this repo, claim an issue or pull request before you work it by hand, so the agent does not start a run beside you: run `bst work:start <n>`. It prints the same orientation `bst work:status` does and then puts `agent-flags/hand-authored` on the object. It claims only where the repo's default branch sets `agent.enabled: true`, and does nothing anywhere else. **Exit 1 means do not start**: a run is live on the pair, or the agent holds it -- the output names which. Exit 0 means the pair is yours, whether the command wrote the flag or found it there already.",
 	"",
+	"The flag records who is working an object now, not who wrote it. Do not claim an issue or pull request you only file or open for later, even one a person or a coding session wrote by hand: leave it unclaimed so the agent can take it if asked. Claim it when you are about to work it.",
+	"",
 	"A pull request you open yourself that closes no claimed issue needs its own `bst work:start <n>` once it exists -- the flag on either half of a pair holds both, but there is no pair until something closes something.",
 	"",
 	"Hand the work back with the control panel's **Release to the agent**, or by removing `agent-flags/hand-authored` from both halves. Removing it does not queue anything: the agent picks the object up on its next cycle only if a label or a comment asks it to.",
@@ -9362,7 +9364,7 @@ const PLANNING_GUIDE_BODY = [
 	"Write for an executor who has not seen this repo or the spec. They write idiomatic code once they know the exact interface and the exact test, and make a reasonable choice wherever the plan leaves one open; what they cannot know is what you decided. A plan records those decisions -- it is not a transcript of the code. Save it under `docs/plans/`.",
 	"",
 	"- Check the plan's premises against the tree before building on them. \"Today X is broken\" is a claim: read the code that handles X, not just the line that throws.",
-	"- Label each task `Task <n>:` at the start of its heading or checkbox, numbered from 1, so `bst plan:brief` can find it. A checkbox's first sentence is the task's name on the control panel: end it with a period inside one short line, and put the files, commands, and checks in the sentences after it.",
+	"- Label each task `Task <n>:` at the start of its heading or checkbox, numbered from 1, so `bst plan:brief` can find it. To split a task after the plan is written, give the parts one lowercase letter (`Task 18a:`, `Task 18b:`) rather than renumbering, so later tasks and every cross-reference keep their numbers. A checkbox's first sentence is the task's name on the control panel: end it with a period inside one short line, and put the files, commands, and checks in the sentences after it.",
 	`- Give each task what makes it unambiguous and nothing more: a test's name and its assertions with the spec's exact values and why that test fails before the change, a code change's exact signature and file, a command with the output that means it passed. Write out a body only for an algorithm the signature and tests do not determine. Work that uses another task's result names that task's interfaces, never repeats its code. A task with no test to write says \`${TEST_EVIDENCE_PREFIXES.noTest} <reason>\` in the plan, so the executor inherits the call instead of making it cold.`,
 	"- Keep tasks small. Each one runs its own test cycle and ends in a result that can be checked on its own: write the failing test, watch it fail, make it pass, commit. A run cut off partway then loses one task, not the plan. A large plan is fine; a large task is not.",
 	"- A plan that builds on earlier work opens with a task that checks the prerequisite exists, and records a `**Blocked:**` note if it does not, instead of rebuilding it.",
@@ -9999,7 +10001,7 @@ function reportFailures(failed, command) {
 function generateMigratePrompt(results, config, detected) {
 	const sections = [];
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.91.0 repo:sync\` on ${timestamp}_\n`);
+	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.92.1 repo:sync\` on ${timestamp}_\n`);
 	const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
 	if (changed.length > 0) {
 		const items = changed.map((r) => {
@@ -17555,7 +17557,7 @@ function countDeferralNotes(content) {
 //#region src/plan-workspace/task-label.ts
 const HEADING = /^(#{1,6})[ \t]+(.*)$/;
 const BOX = /^([ \t]*)[-*] \[[ xX]\][ \t]*(.*)$/;
-const LABEL = /^Task[ \t]+([0-9]+)(?![0-9])/;
+const LABEL = /^Task[ \t]+([0-9]+)([a-z]?)(?![0-9A-Za-z])/;
 const FENCE_OPEN = /^[ \t]*(`{3,}|~{3,})/;
 const FENCE_CLOSE = /^[ \t]*(`{3,}|~{3,})[ \t]*$/;
 function closesFence(text, fenceChar, fenceLength) {
@@ -17588,10 +17590,11 @@ function fencedLines(lines) {
 	}
 	return fenced;
 }
-function taskLabelNumber(text) {
-	const digits = LABEL.exec(text.replace(/^(\*\*|__)/, ""))?.[1];
+function taskLabelId(text) {
+	const match = LABEL.exec(text.replace(/^(\*\*|__)/, ""));
+	const digits = match?.[1];
 	if (digits === void 0 || String(Number(digits)) !== digits) return null;
-	return Number(digits);
+	return `${digits}${match?.[2] ?? ""}`;
 }
 //#endregion
 //#region src/plan-workspace/plan-boxes.ts
@@ -17635,27 +17638,6 @@ function firstSentence$1(paragraph) {
 	}
 	return paragraph;
 }
-const LABEL_REGEX = /^[A-Za-z]+\s+\d+[a-z]?:\s+/;
-function firstClause(title) {
-	const label = LABEL_REGEX.exec(title)?.[0].length ?? 0;
-	let inCode = false;
-	for (let index = label; index < title.length; index++) {
-		const char = title[index];
-		if (char === "`") inCode = !inCode;
-		if (inCode || char !== ";" && char !== ":") continue;
-		if (index + 1 < title.length && !/\s/.test(title[index + 1] ?? "")) continue;
-		return title.slice(0, index).trimEnd();
-	}
-	return title;
-}
-function shortTitle(title) {
-	if (title.length <= 100) return title;
-	const clause = firstClause(title);
-	if (clause.length <= 100) return clause;
-	const room = clause.slice(0, 97);
-	const space = room.lastIndexOf(" ");
-	return `${(space > 0 ? room.slice(0, space) : room).trimEnd()}...`;
-}
 function stripStrong(text) {
 	return text.split(/(`[^`]*`)/).map((part) => part.startsWith("`") ? part : part.replaceAll("**", "")).join("").trim();
 }
@@ -17688,7 +17670,7 @@ function parsePlanBoxes(planText) {
 				break;
 			}
 		}
-		const title = shortTitle(stripStrong(unwrapEmphasis(firstSentence$1(boxParagraph(lines, fenced, box.index, blockEnd, box.rawTitle)))));
+		const title = stripStrong(unwrapEmphasis(firstSentence$1(boxParagraph(lines, fenced, box.index, blockEnd, box.rawTitle))));
 		const retireTask = RETIRE_TASK_REGEX.test(title);
 		if (box.checked) return {
 			line: box.index,
@@ -17735,16 +17717,16 @@ function parsePlanBoxes(planText) {
 //#endregion
 //#region src/plan-workspace/status.ts
 const RETIRED_SEGMENT = /(^|\/)retired\//;
-function enclosingTaskNumber(planText, line) {
+function enclosingTaskLabel(planText, line) {
 	const lines = planText.split("\n");
 	const fenced = fencedLines(lines);
 	let label = null;
 	for (let index = 0; index < lines.length; index++) {
 		const text = lines[index] ?? "";
-		if (index === line) return taskLabelNumber(BOX.exec(text)?.[2] ?? "") ?? label;
+		if (index === line) return taskLabelId(BOX.exec(text)?.[2] ?? "") ?? label;
 		if (fenced[index] === true) continue;
 		const title = BOX.exec(text)?.[2] ?? HEADING.exec(text)?.[2];
-		const n = title === void 0 ? null : taskLabelNumber(title);
+		const n = title === void 0 ? null : taskLabelId(title);
 		if (n !== null) label = n;
 	}
 	return null;
@@ -17766,7 +17748,7 @@ function planStatus(planText, planPath) {
 		outstanding: open.length,
 		declined: boxes.filter((box) => box.declined).length,
 		next: nextBox === void 0 || nextBox.title === "" ? null : nextBox.title,
-		nextTask: nextBox === void 0 ? null : enclosingTaskNumber(planText, nextBox.line),
+		nextTask: nextBox === void 0 ? null : enclosingTaskLabel(planText, nextBox.line),
 		onlyRetireLeft: open.length > 0 && open.every((box) => box.retireTask),
 		notes
 	};
@@ -26996,10 +26978,10 @@ function writeReviewPackage(planPath, base, head, cwd, out) {
 }
 //#endregion
 //#region src/plan-workspace/task-brief.ts
-function isTaskLabel(text, n) {
-	return taskLabelNumber(text) === n;
+function isTaskLabel(text, label) {
+	return taskLabelId(text) === label;
 }
-function extractTask(planText, n) {
+function extractTask(planText, label) {
 	const lines = planText.split("\n");
 	const fenced = fencedLines(lines);
 	let start = -1;
@@ -27011,13 +26993,13 @@ function extractTask(planText, n) {
 		const heading = HEADING.exec(line);
 		const box = BOX.exec(line);
 		if (shape === null) {
-			if (heading !== null && isTaskLabel(heading[2] ?? "", n)) {
+			if (heading !== null && isTaskLabel(heading[2] ?? "", label)) {
 				start = index;
 				shape = {
 					kind: "heading",
 					level: (heading[1] ?? "").length
 				};
-			} else if (box !== null && isTaskLabel(box[2] ?? "", n)) {
+			} else if (box !== null && isTaskLabel(box[2] ?? "", label)) {
 				start = index;
 				shape = {
 					kind: "box",
@@ -27036,16 +27018,16 @@ function extractTask(planText, n) {
 	if (start < 0) return null;
 	return `${lines.slice(start, end).join("\n").trimEnd()}\n`;
 }
-function writeTaskBrief(planPath, n, cwd, out) {
+function writeTaskBrief(planPath, label, cwd, out) {
 	let planText;
 	try {
 		planText = readFileSync(path.resolve(cwd, planPath), "utf-8");
 	} catch {
 		throw new FatalError(`no such plan file: ${planPath}`);
 	}
-	const task = extractTask(planText, n);
-	if (task === null) throw new FatalError(`task ${String(n)} not found in ${planPath} (no heading or checkbox starting "Task ${String(n)}")`);
-	const target = out === void 0 ? path.join(resolvePlanWorkspace(planPath, cwd), `task-${String(n)}-brief.md`) : resolveOutPath(out, cwd);
+	const task = extractTask(planText, label);
+	if (task === null) throw new FatalError(`task ${label} not found in ${planPath} (no heading or checkbox starting "Task ${label}")`);
+	const target = out === void 0 ? path.join(resolvePlanWorkspace(planPath, cwd), `task-${label}-brief.md`) : resolveOutPath(out, cwd);
 	writeFileSync(target, task);
 	return {
 		path: target,
@@ -27095,7 +27077,7 @@ const planBriefCommand = defineCommand({
 		"task-number": {
 			type: "positional",
 			required: true,
-			description: "The task's number, as its heading or checkbox names it"
+			description: "The task's label, as its heading or checkbox names it: a number, or a number and one lowercase letter (18a)"
 		},
 		out: {
 			type: "string",
@@ -27109,8 +27091,8 @@ const planBriefCommand = defineCommand({
 	run({ args }) {
 		const plan = nonEmpty(args.plan, "plan", "plan:brief");
 		const raw = args["task-number"];
-		if (!/^[1-9][0-9]*$/.test(raw)) throw new FatalError(`plan:brief: <task-number> must be a positive integer, got: ${raw}`);
-		const result = writeTaskBrief(plan, Number(raw), process.cwd(), args.out);
+		if (!/^[1-9][0-9]*[a-z]?$/.test(raw)) throw new FatalError(`plan:brief: <task-number> must be a positive integer, optionally followed by one lowercase letter (18, 18a), got: ${raw}`);
+		const result = writeTaskBrief(plan, raw, process.cwd(), args.out);
 		const out = createCliOutput(args.json === true);
 		out.json({
 			ok: true,
@@ -27157,7 +27139,7 @@ const planReviewPackageCommand = defineCommand({
 });
 function renderStatus(report) {
 	const next = report.next ?? "(none)";
-	const task = report.nextTask === null || taskLabelNumber(next) === report.nextTask ? "" : `Task ${String(report.nextTask)} -- `;
+	const task = report.nextTask === null || taskLabelId(next) === report.nextTask ? "" : `Task ${report.nextTask} -- `;
 	const lines = [`${report.plan}${report.retired ? " (retired)" : ""}: ${String(report.checked)} done, ${String(report.outstanding)} outstanding, ${String(report.declined)} declined`, `next: ${task}${next}${report.onlyRetireLeft ? " -- only the retire task is left" : ""}`];
 	for (const note of report.notes) lines.push(`  [${note.kind}] ${note.task}: ${note.text}`);
 	return lines.join("\n");
@@ -27171,7 +27153,7 @@ const planStatusCommand = defineCommand({
 		plan: PLAN_ARG,
 		json: {
 			type: "boolean",
-			description: "Emit one JSON document: plan, retired, checked, outstanding, declined, next (or null), nextTask (or null), onlyRetireLeft, notes ([{task, kind (progress | blocked | declined), text}]). next is null when there is none; nextTask is null when no task label encloses it."
+			description: "Emit one JSON document: plan, retired, checked, outstanding, declined, next (or null), nextTask (a task label string such as \"3\" or \"18a\", or null), onlyRetireLeft, notes ([{task, kind (progress | blocked | declined), text}]). next is null when there is none; nextTask is null when no task label encloses it."
 		}
 	},
 	run({ args }) {
@@ -27344,7 +27326,7 @@ async function runCli(config) {
 //#region src/cli-main.ts
 setLogLevel(resolveLogLevel({}));
 setForgejoLogger(log$1);
-const displayVersion = "0.91.0";
+const displayVersion = "0.92.1";
 const bstSubCommands = {
 	"repo:sync": syncCommand,
 	"checks:run": runChecksCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/tooling",
-  "version": "0.91.0",
+  "version": "0.92.1",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "license": "MIT",
   "repository": {