@bensandee/tooling 0.101.0 → 0.102.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/dist/bin.mjs CHANGED
@@ -173,7 +173,7 @@ function loadEnvFileForBin(rawArgs, bin, io = processIo) {
173
173
  // src/env-file-preload.ts
174
174
  const envFileLoad = loadEnvFileForBin(process.argv.slice(2), {
175
175
  name: "bst",
176
- version: "0.101.0"
176
+ version: "0.102.0"
177
177
  });
178
178
  // ../cli-kit/src/logger.ts
179
179
  const RANK = {
@@ -1732,6 +1732,7 @@ const AgentConfigSchema = z.strictObject({
1732
1732
  preRunRebase: z.boolean().optional().meta({ description: "Merge the current default branch into the work branch before the container starts (default true) -- for an implement (execute) run, and for a spec or plan rerun on an existing branch. A clean merge or an already-up-to-date branch runs the container as is; a conflicting merge is aborted, recorded on the run's status comment, and the run proceeds on the un-synced branch -- a conflict, timeout or failed merge never fails the run, for any phase. Only the execute phase keeps the two-strike rule: two consecutive conflicting attempts hand the unit to agent/repair before any container runs, while a docs run just tries again on its next slice. Set false to skip the attempt entirely for this repo, in every phase: no fetch, no merge, no abort, and the branch is worked exactly as cloned." }),
1733
1733
  backlog: z.boolean().optional().meta({ description: "Whether the agent may self-trigger backlog runs consuming this repo's .agent/findings/ ledger (default: on wherever the ledger exists, which only happens in a repo whose own review loop wrote it). A backlog run opens a pull request that fixes or refutes the pending findings; false disarms it, leaving the ledger to accumulate for a human. A run starts only once at least three findings are pending or one is older than seven days." }),
1734
1734
  lintSweep: LintSweepConfigSchema.optional().meta({ description: "The lint-warning sweep: a periodic agent job that measures this repo's oxlint warnings on its default branch in a container and, past minWarnings, opens a pull request carrying a generated plan for an agent/implement run to work off. Expired @compat warnings leave that plan and each get their own issue instead (see compatIssues)." }),
1735
+ openDocs: z.boolean().optional().meta({ description: "Whether the agent reads this repo's open specs and plans on its default branch and classifies each one's next phase for the control panel's Inbox (default: on). On unless `false`: the sweep is advice only -- it writes nothing to this repo or the forge, and the only write a row can cause is an operator's click. `false` skips the repo in the sweep entirely, so it costs no classifier runs and contributes no rows." }),
1735
1736
  priority: z.record(z.string(), z.enum([
1736
1737
  "critical",
1737
1738
  "high",
@@ -5799,9 +5800,9 @@ function buildManagedDevDeps(ctx) {
5799
5800
  const devDeps = { ...rootDevDeps(ctx.config) };
5800
5801
  if (!isMonorepo) Object.assign(devDeps, perPackageDevDeps(ctx.config));
5801
5802
  if (ctx.config.stack !== "none") devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.15.1";
5802
- if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.101.0";
5803
+ if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.102.0";
5803
5804
  if (ctx.config.useEslintPlugin && ctx.config.stack !== "none") devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.18.0";
5804
- if (wantsAgentCli(ctx)) devDeps[AGENT_CLI_PACKAGE] = "0.3.0";
5805
+ if (wantsAgentCli(ctx)) devDeps[AGENT_CLI_PACKAGE] = "0.3.1";
5805
5806
  if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
5806
5807
  "@changesets/cli": "3.0.3",
5807
5808
  "@release-it/bumper": "8.0.1",
@@ -9647,7 +9648,7 @@ function agentRulesTail(agentWorked) {
9647
9648
  "",
9648
9649
  "**Small change** -- a fix, a doc edit, a one-file tweak: work on the default branch and leave it unstaged. Don't commit; surface the commit message as text for the user to run.",
9649
9650
  "",
9650
- "**Large effort** -- anything that warranted a written plan or spec (spec, then plan, then code, each approved before the next): start it in a worktree (see the Git guide), commit as you go, finish with `pnpm exec bst pr:create`. Push later commits with `pnpm exec bst pr:update`, which rewrites nothing unless given `--title`/`--body`. The one exception: a headless agent run (a spec, plan, execute, or review container) never starts a worktree -- it works and commits on the branch it was started on."
9651
+ "**Large effort** -- anything that warranted a written plan or spec (spec, then plan, then code, each approved before the next): start it in a worktree (see the Git guide), commit as you go, finish with `pnpm exec bst pr:create`. Push later commits with `pnpm exec bst pr:update`, which rewrites nothing unless given `--title`/`--body`; `--closes <n>` on either links an issue. The one exception: a headless agent run (a spec, plan, execute, or review container) never starts a worktree -- it works and commits on the branch it was started on."
9651
9652
  ];
9652
9653
  }
9653
9654
  const COMMENTS_GUIDE_BODY = [
@@ -9700,7 +9701,7 @@ const GIT_GUIDE_BODY = [
9700
9701
  "",
9701
9702
  "## Issue linking",
9702
9703
  "",
9703
- "An issue never becomes a pull request -- the two share a numbering sequence but are separate objects, and a branch named `fix/273-...` links nothing. **A closing keyword in the PR body is the only link:** `Closes #273` (or `Fixes` / `Resolves`) closes the issue on merge. `pr:create` derives the body from `git log <base>..HEAD`, so a keyword in a commit message carries through; `pr:update` does not -- pass `--body`.",
9704
+ "**A closing keyword in the PR body is the only link.** A branch name like `fix/273-...` links nothing. Link an issue with `pnpm exec bst pr:create --closes 273` or `pr:update --closes 273`; each adds the line only when the body does not already close the issue. Add it from the first push, on a spec or plan pull request too, because the agent uses the keyword to find an issue's open pull request. Without the CLI, put `Closes #273` (or `Fixes` / `Resolves`) on its own line in the body.",
9704
9705
  "",
9705
9706
  "It fails silently: an issue still open after its PR merged means the merger lacked permission to close it. The merge succeeds either way, so nothing reports it.",
9706
9707
  "",
@@ -10401,7 +10402,7 @@ function reportFailures(failed, command) {
10401
10402
  function generateMigratePrompt(results, config, detected) {
10402
10403
  const sections = [];
10403
10404
  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
10404
- sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.101.0 repo:sync\` on ${timestamp}_\n`);
10405
+ sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.102.0 repo:sync\` on ${timestamp}_\n`);
10405
10406
  const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
10406
10407
  if (changed.length > 0) {
10407
10408
  const items = changed.map((r) => {
@@ -13330,6 +13331,7 @@ const PullReviewCommentSchema = z.object({
13330
13331
  user: z.object({ login: z.string() }).nullish()
13331
13332
  });
13332
13333
  z.array(PullReviewCommentSchema);
13334
+ z.array(z.object({ id: z.number() }));
13333
13335
  // src/release/publish/child-output.ts
13334
13336
  function childOutput(result) {
13335
13337
  return [result.stdout, result.stderr].filter((stream) => stream.trim() !== "").join("\n");
@@ -14447,18 +14449,20 @@ function extractClosingRefs(messages) {
14447
14449
  return [...byIssue.values()];
14448
14450
  }
14449
14451
  function issuesClosedBy(body, repository) {
14452
+ return issuesInRepository(extractClosingRefs([body]).map((ref) => ref.issue), repository);
14453
+ }
14454
+ function issuesInRepository(refs, repository) {
14450
14455
  const numbers = /* @__PURE__ */ new Set();
14451
- for (const ref of extractClosingRefs([body])) {
14452
- const name = ref.issue.toLowerCase();
14456
+ for (const ref of refs) {
14457
+ const name = ref.toLowerCase();
14453
14458
  const hash = name.lastIndexOf("#");
14454
14459
  const repoPart = name.slice(0, hash);
14455
- const number = Number(name.slice(hash + 1));
14456
14460
  if (repoPart !== "" && repoPart !== repository.toLowerCase()) continue;
14457
- numbers.add(number);
14461
+ numbers.add(Number(name.slice(hash + 1)));
14458
14462
  }
14459
- const closed = [...numbers];
14460
- closed.sort((a, b) => a - b);
14461
- return closed;
14463
+ const sorted = [...numbers];
14464
+ sorted.sort((a, b) => a - b);
14465
+ return sorted;
14462
14466
  }
14463
14467
  function closedIssues(text) {
14464
14468
  return new Set(extractClosingRefs([text]).map((ref) => ref.issue.toLowerCase()));
@@ -14473,6 +14477,15 @@ function carryForwardClosingRefs(source, target) {
14473
14477
  const refLines = missing.map((ref) => ref.text).join("\n");
14474
14478
  return target.trim() === "" ? refLines : `${target}\n\n${refLines}`;
14475
14479
  }
14480
+ function parseIssueList(value) {
14481
+ const numbers = /* @__PURE__ */ new Set();
14482
+ for (const part of value.split(",")) {
14483
+ const match = /^#?([1-9]\d*)$/.exec(part.trim());
14484
+ if (match?.[1] === void 0) throw new FatalError(`--closes takes issue numbers separated by commas, such as 12 or 12,15; got ${JSON.stringify(value)}.`);
14485
+ numbers.add(Number(match[1]));
14486
+ }
14487
+ return [...numbers];
14488
+ }
14476
14489
  // ../forgejo/src/issues.ts
14477
14490
  function repositoryFromUrl(url) {
14478
14491
  if (!URL.canParse(url)) return null;
@@ -15397,6 +15410,7 @@ function branchNotFoundMessage(conn, branch) {
15397
15410
  return `Branch ${branch} not found in ${conn.repository}`;
15398
15411
  }
15399
15412
  const RepoFullNameSchema = z.object({ full_name: z.string() });
15413
+ z.object({ description: z.string().optional() });
15400
15414
  async function getRepoFullName(executor, conn) {
15401
15415
  const res = await executor.fetch(repoBase(conn), { headers: authHeaders(conn) });
15402
15416
  if (!res.ok) await throwForgejoFailure(res, {
@@ -20016,7 +20030,51 @@ function checkClosingLinks(messages, plan, allowUnlink) {
20016
20030
  unlinked
20017
20031
  };
20018
20032
  }
20033
+ function addClosingIssues(plan, issues) {
20034
+ const wanted = issues.map((issue) => `Closes #${String(issue)}`).join("\n");
20035
+ const added = droppedClosingRefs([wanted], plan.effective.body).map((ref) => Number(ref.issue.slice(1)));
20036
+ if (added.length === 0) return {
20037
+ plan,
20038
+ added
20039
+ };
20040
+ const body = carryForwardClosingRefs(wanted, plan.effective.body);
20041
+ return {
20042
+ plan: {
20043
+ ...plan,
20044
+ patch: {
20045
+ ...plan.patch,
20046
+ body
20047
+ },
20048
+ effective: {
20049
+ ...plan.effective,
20050
+ body
20051
+ }
20052
+ },
20053
+ added
20054
+ };
20055
+ }
20019
20056
  const ALWAYS_PROTECTED = /* @__PURE__ */ new Set(["main", "master"]);
20057
+ async function planUpsert(host, existing, derived, options) {
20058
+ let plan;
20059
+ if (existing === null) plan = {
20060
+ patch: {
20061
+ title: derived.title,
20062
+ body: derived.body
20063
+ },
20064
+ effective: derived,
20065
+ previousBody: null
20066
+ };
20067
+ else plan = planPrUpdate(options, derived, prUpdateNeedsLive(options) ? await host.readLive(existing, options.signal ?? null) : null, host.wipTitles);
20068
+ if (options.closes === void 0) return {
20069
+ plan,
20070
+ closesAdded: void 0
20071
+ };
20072
+ const linked = addClosingIssues(plan, options.closes);
20073
+ return {
20074
+ plan: linked.plan,
20075
+ closesAdded: linked.added
20076
+ };
20077
+ }
20020
20078
  async function runPrUpsert$1(git, host, options) {
20021
20079
  const { cwd } = options;
20022
20080
  const mode = options.mode ?? "upsert";
@@ -20049,22 +20107,14 @@ async function runPrUpsert$1(git, host, options) {
20049
20107
  const existing = open?.number ?? null;
20050
20108
  assertModeAllows(mode, existing, branch);
20051
20109
  if (!options.dryRun && options.skipPush !== true) await pushBranch(git, cwd, branch, options.pushEnv, options.forceWithLease);
20052
- let plan;
20053
- if (existing === null) plan = {
20054
- patch: {
20055
- title: derived.title,
20056
- body: derived.body
20057
- },
20058
- effective: derived,
20059
- previousBody: null
20060
- };
20061
- else plan = planPrUpdate(options, derived, prUpdateNeedsLive(options) ? await host.readLive(existing, signal) : null, host.wipTitles);
20110
+ const { plan, closesAdded } = await planUpsert(host, existing, derived, options);
20062
20111
  const report = checkClosingLinks(messages, plan, options.allowUnlink === true);
20063
20112
  options.onClosingLinks?.(report);
20064
20113
  const shape = {
20065
20114
  branch,
20066
20115
  base: open?.base ?? localBase,
20067
- ...plan.effective
20116
+ ...plan.effective,
20117
+ ...closesAdded === void 0 ? {} : { closesAdded }
20068
20118
  };
20069
20119
  if (options.dryRun) return {
20070
20120
  action: existing === null ? "would-create" : "would-update",
@@ -20100,7 +20150,7 @@ function describeClosingLinks(report, flags) {
20100
20150
  const lines = [];
20101
20151
  if (report.fromCommits.length > 0) {
20102
20152
  const said = report.fromCommits.map((dropped) => dropped.text).join(", ");
20103
- lines.push(`The commits say ${said}, but the PR body does not -- the issue may not close on merge. Add it to ${flags.body}.`);
20153
+ lines.push(`The commits say ${said}, but the PR body does not -- the issue may not close on merge. Link it with ${flags.closes}.`);
20104
20154
  }
20105
20155
  if (report.unlinked.length > 0) {
20106
20156
  const lost = report.unlinked.map((dropped) => dropped.text).join(", ");
@@ -20152,15 +20202,17 @@ function formatPrCreate(result) {
20152
20202
  };
20153
20203
  }
20154
20204
  function formatPrUpdate(result, rewrites, flags) {
20205
+ const added = result.closesAdded ?? [];
20155
20206
  if (isDryRun(result)) return {
20156
20207
  lines: [`[dry-run] Would push ${prTarget(result)} to ${prLabel(result)}`],
20157
20208
  body: {
20158
- heading: rewrites ? "[dry-run] Body" : "[dry-run] Body (unchanged)",
20209
+ heading: rewrites || added.length > 0 ? "[dry-run] Body" : "[dry-run] Body (unchanged)",
20159
20210
  text: result.body
20160
20211
  }
20161
20212
  };
20162
20213
  const lines = [`Updated ${prLabel(result)} (${prTarget(result)})`];
20163
- if (!rewrites) lines.push(`Title and body left as authored -- pass ${flags.title}/${flags.body} to change them.`);
20214
+ if (added.length > 0) lines.push(`Linked ${added.map((issue) => `#${String(issue)}`).join(", ")} with a Closes line.`);
20215
+ else if (!rewrites) lines.push(`Title and body left as authored -- pass ${flags.title}/${flags.body} to change them.`);
20164
20216
  if (result.url !== null) lines.push(result.url);
20165
20217
  return {
20166
20218
  lines,
@@ -20173,7 +20225,7 @@ const BST_COMMANDS = {
20173
20225
  update: "pnpm exec bst pr:update"
20174
20226
  };
20175
20227
  const BST_FLAGS = {
20176
- body: "--body",
20228
+ closes: "--closes",
20177
20229
  allowUnlink: "--allow-unlink"
20178
20230
  };
20179
20231
  function executorGit(executor) {
@@ -20332,13 +20384,17 @@ const prCreateCommand = defineCommand({
20332
20384
  type: "boolean",
20333
20385
  description: "With --upsert: permit a --body that drops a closing keyword the PR carries"
20334
20386
  },
20387
+ closes: {
20388
+ type: "string",
20389
+ description: "Issues the PR closes, comma-separated (12 or 12,15): adds a Closes #<n> line to the body for each one it does not already close"
20390
+ },
20335
20391
  "dry-run": {
20336
20392
  type: "boolean",
20337
20393
  description: "Show what would happen without pushing"
20338
20394
  },
20339
20395
  json: {
20340
20396
  type: "boolean",
20341
- description: "Emit one JSON document: action (created | updated | would-create | would-update), number (or null), url (or null), branch, base, title, body, droppedRefs? ([{text, issue}]), dryRun, claims? ([{issue, owner: unclaimed | agent | person | null, label?}]) -- present after a create in an agent-enabled Forgejo repo whose body closes an issue; owner null means the labels could not be read. bst pr:create is the one command that reports claims; bst-fj pr:create does not. A create or would-create carries droppedRefs; on a dry run, number and url are null."
20397
+ description: "Emit one JSON document: action (created | updated | would-create | would-update), number (or null), url (or null), branch, base, title, body, droppedRefs? ([{text, issue}]), closesAdded? (with --closes: the issues it added a Closes line for), dryRun, claims? ([{issue, owner: unclaimed | agent | person | null, label?}]) -- present after a create in an agent-enabled Forgejo repo whose body closes an issue; owner null means the labels could not be read. bst pr:create is the one command that reports claims; bst-fj pr:create does not. A create or would-create carries droppedRefs; on a dry run, number and url are null."
20342
20398
  },
20343
20399
  verbose: {
20344
20400
  type: "boolean",
@@ -20358,6 +20414,7 @@ const prCreateCommand = defineCommand({
20358
20414
  body,
20359
20415
  base: args.base ?? void 0,
20360
20416
  allowUnlink: args["allow-unlink"] === true,
20417
+ closes: args.closes === void 0 ? void 0 : parseIssueList(args.closes),
20361
20418
  draft: args.draft === true ? true : void 0,
20362
20419
  dryRun: args["dry-run"] === true,
20363
20420
  verbose: args.verbose === true || isEnvVerbose()
@@ -20636,13 +20693,17 @@ const prUpdateCommand = defineCommand({
20636
20693
  type: "boolean",
20637
20694
  description: "Permit a --body that drops a closing keyword the current body carries"
20638
20695
  },
20696
+ closes: {
20697
+ type: "string",
20698
+ description: "Issues the PR closes, comma-separated (12 or 12,15): adds a Closes #<n> line to the body for each one it does not already close"
20699
+ },
20639
20700
  "dry-run": {
20640
20701
  type: "boolean",
20641
20702
  description: "Show what would happen without pushing"
20642
20703
  },
20643
20704
  json: {
20644
20705
  type: "boolean",
20645
- description: "Emit one JSON document: action (updated | would-update), number (or null), url (or null), branch, base, title, body, dryRun, rewrites. On a dry run, number and url are null."
20706
+ description: "Emit one JSON document: action (updated | would-update), number (or null), url (or null), branch, base, title, body, closesAdded? (with --closes: the issues it added a Closes line for), dryRun, rewrites. On a dry run, number and url are null."
20646
20707
  },
20647
20708
  verbose: {
20648
20709
  type: "boolean",
@@ -20661,6 +20722,7 @@ const prUpdateCommand = defineCommand({
20661
20722
  body,
20662
20723
  base: args.base ?? void 0,
20663
20724
  allowUnlink: args["allow-unlink"] === true,
20725
+ closes: args.closes === void 0 ? void 0 : parseIssueList(args.closes),
20664
20726
  draft: void 0,
20665
20727
  dryRun: args["dry-run"] === true,
20666
20728
  verbose: args.verbose === true || isEnvVerbose()
@@ -27081,6 +27143,128 @@ const docsCheckCommand = defineCommand({
27081
27143
  process.exitCode = exitCode;
27082
27144
  }
27083
27145
  });
27146
+ // src/docs-check/open-docs.ts
27147
+ const HASH_REF = /(?<![\w./#-])#([0-9]+)(?![0-9A-Za-z_-])/g;
27148
+ const WORD_REF = /\b(?:pull request|pr)\s+#?([0-9]+)\b/gi;
27149
+ const FORGE_REF = /\/(?:issues|pulls)\/([0-9]+)(?![0-9])/g;
27150
+ function forgeRefPattern(repoUrl) {
27151
+ const base = repoUrl?.replace(/\/+$/, "");
27152
+ if (base === void 0 || base === "") return FORGE_REF;
27153
+ return new RegExp(`${escapeRegex(base)}/(?:issues|pulls)/([0-9]+)(?![0-9])`, "g");
27154
+ }
27155
+ function titleOf(body) {
27156
+ return /^# +(.*\S)[ \t]*$/m.exec(stripCode(body))?.[1] ?? null;
27157
+ }
27158
+ function refsOf$1(body, repoUrl) {
27159
+ const scannable = stripCode(body);
27160
+ const found = /* @__PURE__ */ new Set();
27161
+ for (const re of [
27162
+ HASH_REF,
27163
+ WORD_REF,
27164
+ forgeRefPattern(repoUrl)
27165
+ ]) {
27166
+ re.lastIndex = 0;
27167
+ for (const match of scannable.matchAll(re)) {
27168
+ const digits = (match[1] ?? match[0]).replaceAll("#", "");
27169
+ const value = Number(digits);
27170
+ if (Number.isSafeInteger(value)) found.add(value);
27171
+ }
27172
+ }
27173
+ return [...found].toSorted((a, b) => a - b);
27174
+ }
27175
+ function linksOf(body, fileDir) {
27176
+ const found = /* @__PURE__ */ new Set();
27177
+ for (const link of relativeLinks(body, fileDir)) if (resolvesInsideDocs(link.target)) found.add(link.target);
27178
+ return [...found].toSorted();
27179
+ }
27180
+ function classOf(status) {
27181
+ if (status !== void 0 && PARTIAL_STATUS.test(status)) return "partial";
27182
+ if (status !== void 0 && OPEN_STATUS.test(status)) return "not-started";
27183
+ return "other";
27184
+ }
27185
+ function kindOf(docPath) {
27186
+ return classifyConventionalDoc(docPath)?.kind ?? "configured";
27187
+ }
27188
+ function readOpenDoc(exec, docPath, repoUrl) {
27189
+ const body = exec.readFile(docPath);
27190
+ if (body === void 0) return void 0;
27191
+ const status = statusOf(body);
27192
+ return {
27193
+ path: docPath,
27194
+ kind: kindOf(docPath),
27195
+ title: titleOf(body),
27196
+ status: status ?? null,
27197
+ statusClass: classOf(status),
27198
+ lastChangedISO: exec.lastContentChangeISO(docPath),
27199
+ refs: refsOf$1(body, repoUrl),
27200
+ links: linksOf(body, path.posix.dirname(docPath))
27201
+ };
27202
+ }
27203
+ function byPath(a, b) {
27204
+ if (a.path < b.path) return -1;
27205
+ if (a.path > b.path) return 1;
27206
+ return 0;
27207
+ }
27208
+ function listOpenDocs(exec, config, options = {}) {
27209
+ if (!config.enabled) return [];
27210
+ const docs = [];
27211
+ for (const pair of discoverPairs(exec, config)) for (const docPath of listDocs(exec, pair.active, pair.activePattern)) {
27212
+ const doc = readOpenDoc(exec, docPath, options.repoUrl);
27213
+ if (doc !== void 0) docs.push(doc);
27214
+ }
27215
+ return docs.toSorted(byPath);
27216
+ }
27217
+ // src/commands/docs-list.ts
27218
+ function dayOf(iso) {
27219
+ if (iso === void 0) return "unknown";
27220
+ const day = iso.slice(0, 10);
27221
+ return /^\d{4}-\d{2}-\d{2}$/.test(day) ? day : "unknown";
27222
+ }
27223
+ function refsOf(refs) {
27224
+ if (refs.length === 0) return "-";
27225
+ return refs.map((n) => `#${String(n)}`).join(",");
27226
+ }
27227
+ function runDocsList(exec, config) {
27228
+ const docs = listOpenDocs(exec, config);
27229
+ const lines = docs.map((doc) => `${doc.path} ${doc.statusClass} ${dayOf(doc.lastChangedISO)} ${refsOf(doc.refs)}`);
27230
+ return {
27231
+ payload: {
27232
+ ok: true,
27233
+ docs
27234
+ },
27235
+ text: lines.join("\n")
27236
+ };
27237
+ }
27238
+ const docsListCommand = defineCommand({
27239
+ meta: {
27240
+ name: "docs:list",
27241
+ description: "List the active specs and plans -- exactly the docs docs:check counts as active -- with what can be read mechanically from each: kind, title, raw Status value and its class (not-started, partial, other), the date its content last changed, the issue and pull request numbers it names, and the docs it links to. Reports and never writes; a Status line is data here, never a filter. Docs on a branch other than the default branch are not catalogued."
27242
+ },
27243
+ args: {
27244
+ dir: {
27245
+ type: "positional",
27246
+ valueHint: "dir",
27247
+ description: "Project directory (default: current directory)",
27248
+ required: false
27249
+ },
27250
+ json: {
27251
+ type: "boolean",
27252
+ description: "Emit one JSON document: ok, docs ([{path, kind (spec | plan | legacy-plan | configured), title, status, statusClass (not-started | partial | other), lastChangedISO, refs, links}])."
27253
+ },
27254
+ verbose: {
27255
+ type: "boolean",
27256
+ description: "Emit detailed debug logging"
27257
+ }
27258
+ },
27259
+ run({ args }) {
27260
+ const targetDir = path.resolve(args.dir ?? ".");
27261
+ const out = createCliOutput(args.json === true);
27262
+ const { payload, text } = runDocsList(createRealDocsExecutor(targetDir), resolveDocsConfig(targetDir));
27263
+ debug({ verbose: args.verbose === true || isEnvVerbose() }, `docs:list: ${String(payload.docs.length)} open doc(s)`);
27264
+ out.json(payload);
27265
+ if (text !== "") out.text(text);
27266
+ }
27267
+ });
27084
27268
  // src/docs-delink/engine.ts
27085
27269
  function textRestatesTarget(text, target) {
27086
27270
  const plain = text.replaceAll("`", "").trim();
@@ -29583,7 +29767,7 @@ async function runCli(config) {
29583
29767
  // src/cli-main.ts
29584
29768
  setLogLevel(resolveLogLevel({}));
29585
29769
  setForgejoLogger(log$1);
29586
- const displayVersion = "0.101.0";
29770
+ const displayVersion = "0.102.0";
29587
29771
  const bstSubCommands = {
29588
29772
  "repo:sync": syncCommand,
29589
29773
  "checks:run": runChecksCommand,
@@ -29621,6 +29805,7 @@ const bstSubCommands = {
29621
29805
  "ascii:check": asciiCheckAliasCommand,
29622
29806
  "branch:prune": branchPruneCommand,
29623
29807
  "docs:check": docsCheckCommand,
29808
+ "docs:list": docsListCommand,
29624
29809
  "docs:delink": docsDelinkCommand,
29625
29810
  "docs:relocate": docsRelocateCommand,
29626
29811
  "docs:retire": docsRetireCommand,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bensandee/tooling",
3
- "version": "0.101.0",
3
+ "version": "0.102.0",
4
4
  "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -748,6 +748,10 @@
748
748
  },
749
749
  "additionalProperties": false
750
750
  },
751
+ "openDocs": {
752
+ "description": "Whether the agent reads this repo's open specs and plans on its default branch and classifies each one's next phase for the control panel's Inbox (default: on). On unless `false`: the sweep is advice only -- it writes nothing to this repo or the forge, and the only write a row can cause is an operator's click. `false` skips the repo in the sweep entirely, so it costs no classifier runs and contributes no rows.",
753
+ "type": "boolean"
754
+ },
751
755
  "priority": {
752
756
  "description": "Map this repo's own issue-label names onto the agent's four priority levels, e.g. {\"P1\": \"critical\", \"P4\": \"low\"}. The map UNIONS with the built-in priority/<level> names rather than replacing them, and the agent does not create aliased labels -- the repo owns names the agent did not choose. Priority affects claim order only: it never changes a run's model, effort, or any budget.",
753
757
  "type": "object",