@ersbeth/codelife 0.0.0-stage → 0.11.1

package/scripts/tracker/mr.description.mjs

@@ -0,0 +1,8 @@
+// tracker.mr.description(n): the merge request's description as written, nothing else — read where
+// `mr.view`'s merge base is not needed, since on gh it costs a `mr.fetch_head` first.
+// `node mr.description.mjs <n>`.
+import { arg, cli, run } from './lib.mjs';
+
+const n = arg(0, '<n>');
+process.stdout.write(cli() === 'glab' ? JSON.parse(run(['mr', 'view', n, '-F', 'json'])).description || ''
+  : JSON.parse(run(['pr', 'view', n, '--json', 'body'])).body || '');

package/scripts/tracker/mr.fetch_head.mjs

@@ -0,0 +1,5 @@
+// tracker.mr.fetch_head(n): the merge request's head fetched — refs only, never a checkout.
+import { arg, cli, git } from './lib.mjs';
+
+const n = arg(0, '<n>');
+git('fetch', '-q', 'origin', cli() === 'glab' ? `refs/merge-requests/${n}/head` : `refs/pull/${n}/head`);

package/scripts/tracker/mr.find_for_branch.mjs

@@ -0,0 +1,9 @@
+// tracker.mr.find_for_branch(b): the merge requests whose source is that branch, in any state, one
+// `<number> <open|merged|closed>` per line — none when there is none.
+import { arg, cli, origin, run } from './lib.mjs';
+
+const b = arg(0, '<branch>');
+const STATE = { opened: 'open', open: 'open', merged: 'merged', closed: 'closed', locked: 'closed' };
+const rows = cli() === 'glab' ? JSON.parse(run(['mr', 'list', '--source-branch', b, '--all', '-F', 'json'])).map((m) => [m.iid, m.state])
+  : JSON.parse(run(['pr', 'list', '--head', b, '--state', 'all', '--json', 'number,state'])).map((p) => [p.number, p.state]);
+for (const [n, s] of rows) console.log(`${n} ${STATE[String(s).toLowerCase()] ?? s}`);

package/scripts/tracker/mr.post.mjs

@@ -0,0 +1,40 @@
+// `codelife mr post <n> <file>` (C-864, C-867): one new general comment on the merge request, its
+// body the file as written — never edited afterwards, never typed. A body whose first line opens on
+// `codelife:` and ends on a sha is about that head: when the merge request's head is another,
+// nothing is posted, since a pass's numbers and an answer's hashes name lines of the head they read;
+// and when that very comment is already there, a re-run's, nothing is posted either. On GitLab the
+// comment is then resolved, a record being no thread. Prints the comment's link, read back by its body.
+import { arg, body, cli, die, first, origin, run } from './lib.mjs';
+import { lf } from '../text.mjs';
+
+const n = arg(0, '<n> <file>');
+const comment = body(arg(1, '<n> <file>'));
+const glab = cli() === 'glab';
+const line = first(comment).trimEnd();
+// posted — that comment, as the forge stores it, latest first: its link, and on glab its note.
+const same = (b) => lf(b).trim() === lf(comment).trim();
+const posted = () => {
+  if (!glab) return { url: JSON.parse(run(['pr', 'view', n, '--json', 'comments'])).comments.filter((c) => same(c.body)).at(-1)?.url };
+  const { host, project } = origin();
+  const mine = JSON.parse(run(['mr', 'note', 'list', n, '-t', 'general', '-F', 'json']) || '[]')
+    .flatMap((d) => d.notes).filter((x) => !x.system && same(x.body)).at(-1);
+  return { url: mine && `https://${host}/${project}/-/merge_requests/${n}#note_${mine.id}`, note: mine };
+};
+const sha = line.match(/^codelife:.* — ([0-9a-f]{7,40})$/)?.[1];
+if (sha) {
+  const head = glab ? JSON.parse(run(['mr', 'view', n, '-F', 'json'])).sha : JSON.parse(run(['pr', 'view', n, '--json', 'headRefOid'])).headRefOid;
+  if (!head.startsWith(sha)) die(`the merge request moved: its head is ${head}, the comment reads ${sha}; nothing posted`);
+}
+let found = sha ? posted() : {};
+if (!found.url) {
+  if (glab) run(['mr', 'note', 'create', n, '-m', comment]);
+  else run(['pr', 'comment', n, '--body-file', '-'], comment);
+  found = posted();
+}
+if (!found.url) die('the comment was sent and does not read back');
+// A record is no question: on GitLab a general note is a resolvable discussion, counted among the
+// merge request's unresolved threads until someone resolves it, so its poster does (#1047) — and a
+// reply under it then reads as a comment after the pass (#1097). The merge request first: the
+// order glab 1.113.0 accepts, whatever its usage line says.
+if (found.note?.resolvable && !found.note.resolved) run(['mr', 'note', 'resolve', n, String(found.note.id)]);
+console.log(found.url);

package/scripts/tracker/mr.update_description.mjs

@@ -0,0 +1,8 @@
+// tracker.mr.update_description(n, file): the merge request's description replaced by the file as
+// written; prints its link when the CLI answers one. `node mr.update_description.mjs <n> <file>`.
+import { arg, body, cli, run } from './lib.mjs';
+
+const n = arg(0, '<n> <file>'), file = arg(1, '<n> <file>');
+const description = body(file);
+const out = cli() === 'glab' ? run(['mr', 'update', n, '-d', description]) : run(['pr', 'edit', n, '--body-file', file]);
+console.log(out.match(/https?:\/\/\S+/g)?.at(-1) ?? '');

package/scripts/tracker/mr.verdict.mjs

@@ -0,0 +1,34 @@
+// `codelife mr verdict <n> approve|request [<pass link>]` (C-866): the forge's own verdict — on GitLab
+// the approval, or the reviewer state *requested changes*, which glab has no verb for and is read
+// back, since the API answers 204 to an account that is no reviewer and changes nothing; on GitHub a
+// review in the APPROVE or REQUEST_CHANGES state, its body the pass's link. An approval of one's own
+// merge request is refused: it would count toward the forge's approval rules with nobody else having read it (R-292). /review-mr's
+// preparation stops on one's own merge request first (work C-861); this is the verb's own
+// refusal, for any other caller.
+import { arg, call, cli, die, origin, run } from './lib.mjs';
+
+const n = arg(0, '<n> approve|request [<pass link>]');
+const verdict = arg(1, '<n> approve|request [<pass link>]');
+if (!['approve', 'request'].includes(verdict)) die(`usage: codelife mr verdict <n> approve|request [<pass link>] — not '${verdict}'`);
+const link = process.argv[4] || '';
+if (cli() === 'glab') {
+  const me = JSON.parse(run(['api', 'user', '--hostname', origin().host]));
+  const m = JSON.parse(run(['mr', 'view', n, '-F', 'json']));
+  if (verdict === 'approve') {
+    if (m.author?.username === me.username) die(`!${n} is ${me.username}'s own: no approval is sent`);
+    run(['mr', 'approve', n]);
+  } else {
+    call(['mr', 'revoke', n]); // an approval of ours an earlier pass sent; none is no failure
+    const ids = (m.reviewers || []).map((r) => r.id);
+    if (!ids.includes(me.id)) run(['api', '-X', 'PUT', `projects/:id/merge_requests/${n}`, '-f', `reviewer_ids=${[...ids, me.id].join(',')}`]);
+    run(['api', '-X', 'POST', `projects/:id/merge_requests/${n}/draft_notes/bulk_publish`, '-f', 'reviewer_state=requested_changes']);
+    const state = JSON.parse(run(['api', `projects/:id/merge_requests/${n}/reviewers`])).find((r) => r.user?.id === me.id)?.state;
+    if (state !== 'requested_changes') die(`the request for changes did not hold: the account's reviewer state reads ${state || 'nothing'}`);
+  }
+} else {
+  const me = run(['api', 'user', '--jq', '.login']).trim();
+  const author = JSON.parse(run(['pr', 'view', n, '--json', 'author'])).author?.login;
+  if (verdict === 'approve' && author === me) die(`#${n} is ${me}'s own: no approval is sent`);
+  run(['pr', 'review', n, verdict === 'approve' ? '--approve' : '--request-changes', '--body-file', '-'], link || (verdict === 'approve' ? 'Approved.' : 'Changes requested.'));
+}
+console.log(`${verdict === 'approve' ? 'approved' : 'changes requested'}: !${n}`);

package/scripts/tracker/mr.view.mjs

@@ -0,0 +1,20 @@
+// tracker.mr.view(n): the merge request as JSON — sha, base, source, target, author, reviewers, draft, state,
+// description. On gh there is no base sha: the merge base is computed from the target the forge
+// named, fetched from it first — the clone's own copy may be stale or missing —, after
+// tracker.mr.fetch_head.
+import { arg, cli, git, run } from './lib.mjs';
+
+const n = arg(0, '<n>');
+let view;
+if (cli() === 'glab') {
+  const m = JSON.parse(run(['mr', 'view', n, '-F', 'json']));
+  view = { sha: m.sha, base: m.diff_refs?.base_sha, source: m.source_branch, target: m.target_branch, author: m.author?.username,
+    reviewers: (m.reviewers || []).map((r) => r.username), draft: !!m.draft, state: m.state, description: m.description || '' };
+} else {
+  const m = JSON.parse(run(['pr', 'view', n, '--json', 'headRefOid,headRefName,baseRefName,author,isDraft,state,body,reviewRequests']));
+  git('fetch', '-q', 'origin', `+refs/heads/${m.baseRefName}:refs/remotes/origin/${m.baseRefName}`);
+  view = { sha: m.headRefOid, base: git('merge-base', `origin/${m.baseRefName}`, m.headRefOid).trim(), source: m.headRefName, target: m.baseRefName,
+    author: m.author?.login, reviewers: (m.reviewRequests || []).map((r) => r.login), draft: !!m.isDraft, state: m.state,
+    description: m.body || '' };
+}
+console.log(JSON.stringify(view));

package/scripts/tracker/none.mjs

@@ -0,0 +1,79 @@
+// What `tracker.kind: none` reads: `issues/NNN-<slug>.md`, one issue per file (none-fallback.md),
+// as the JSON a forge's view gives — title, body, state, labels, milestone, its notes as comments in
+// order, and no history of its state; and the two writes a close makes, each changing its part of
+// the file and nothing else.
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { die, word } from './lib.mjs';
+import { lf } from '../text.mjs';
+
+// issues — every file of issues/; none before the first issue, which creates the folder (#1067).
+const issues = () => {
+  if (!existsSync('issues')) return [];
+  return readdirSync('issues').filter((f) => /^\d+-.*\.md$/.test(f)).sort().map((f) => {
+    const [, head = '', rest = ''] = lf(readFileSync(`issues/${f}`, 'utf8')).match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/) ?? [];
+    const meta = Object.fromEntries([...head.matchAll(/^(\w+):[ \t]*(.*?)[ \t]*(?:#.*)?$/gm)].map((m) => [m[1], m[2]]));
+    const [, title = '', after = ''] = rest.match(/^\n*# (.*)\n([\s\S]*)$/) ?? [];
+    const [body, notes = ''] = after.split(/^## Notes[ \t]*$/m);
+    return { id: Number(meta.id), path: `issues/${f}`, meta, title, body: body.replace(/^\n+|\s+$/g, ''), notes };
+  });
+};
+
+// open — `#<id>\t<title>` for each issue still open, or every one when `all`.
+export const lines = (all) => issues().filter((i) => all || i.meta.status === 'open').map((i) => `#${i.id}\t${i.title}`);
+
+// matching — `#<id>\t<title>` for each open issue whose file holds the term as a whole word.
+export const matching = (term) => {
+  const holds = word(term);
+  return issues().filter((i) => i.meta.status === 'open' && holds(readFileSync(i.path, 'utf8'))).map((i) => `#${i.id}\t${i.title}`);
+};
+
+const one = (n) => issues().find((x) => x.id === Number(n)) ?? die(`no issue ${n} under issues/`);
+
+export const view = (n) => {
+  const i = one(n);
+  const labels = [i.meta.nature, i.meta.severity && `severity-${i.meta.severity}`, i.meta.lot === 'true' && 'lot', i.meta.status === 'wontfix' && 'wontfix'].filter(Boolean);
+  const comments = i.notes.split(/^### /m).slice(1).map((s) => {
+    const [first, ...text] = s.split('\n');
+    const [, date = '', line = first] = first.match(/^(\d{4}-\d{2}-\d{2}) — (.*)$/) ?? [];
+    return { author: '', date, body: [line, ...text].join('\n').trim() };
+  });
+  return { title: i.title, body: i.body, state: i.meta.status === 'open' ? 'opened' : 'closed', labels, milestone: i.meta.milestone || '', comments, events: [] };
+};
+
+// close — the comment appended as a dated section under `## Notes`, then the status set, in that order.
+// note — one dated section appended under `## Notes`, opened when the file has none.
+export const note = (n, comment) => {
+  const i = one(n);
+  appendFileSync(i.path, `${/^## Notes[ \t]*$/m.test(readFileSync(i.path, 'utf8')) ? '' : '\n## Notes\n'}\n### ${new Date().toISOString().slice(0, 10)} — ${comment}\n`);
+  return i;
+};
+export const close = (n, comment, wontfix) => {
+  const i = note(n, comment);
+  writeFileSync(i.path, readFileSync(i.path, 'utf8').replace(/^status:[ \t]*\w+/m, `status: ${wontfix ? 'wontfix' : 'closed'}`));
+};
+
+// create — a new file after the highest id, `status: open`, created today; returns its path.
+export const create = (title, body, nature, severity) => {
+  const id = Math.max(0, ...issues().map((i) => i.id)) + 1;
+  const slug = title.replace(/^\[[^\]]*\]\s*/, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 50).replace(/-$/, '');
+  const path = `issues/${String(id).padStart(3, '0')}-${slug}.md`;
+  mkdirSync('issues', { recursive: true });
+  writeFileSync(path, `---\nid: ${id}\nstatus: open\nnature: ${nature}\n${severity ? `severity: ${severity}\n` : ''}created: ${new Date().toISOString().slice(0, 10)}\n---\n# ${title}\n\n${body}\n`);
+  return path;
+};
+
+// retitle — the `# ` line after the frontmatter replaced, nothing else.
+export const retitle = (n, title) => {
+  const i = one(n), text = readFileSync(i.path, 'utf8'), at = text.indexOf(`\n# ${i.title}\n`, text.indexOf('\n---\n') + 4);
+  if (at < 0) die(`${i.path}: no title to replace`);
+  writeFileSync(i.path, `${text.slice(0, at)}\n# ${title}\n${text.slice(at + i.title.length + 4)}`);
+};
+
+// update — the body replaced where it stands, after the title, so a frontmatter value or a title the
+// body repeats is never what is replaced (#1093); the notes untouched.
+export const update = (n, body) => {
+  const i = one(n), text = readFileSync(i.path, 'utf8');
+  const at = i.body ? text.indexOf(i.body, text.indexOf(`\n# ${i.title}\n`, text.indexOf('\n---\n') + 4) + i.title.length + 3) : -1;
+  if (at < 0) die(`${i.path}: no body to replace`);
+  writeFileSync(i.path, `${text.slice(0, at)}${body}${text.slice(at + i.body.length)}`);
+};

package/scripts/tracker/note.mjs

@@ -0,0 +1,12 @@
+// tracker.note(n, file): one new comment on the issue, read from its file — the plan posted before
+// the first edit, or a STATUS at a stop — never a subagent's (R-290). `codelife issue note <n> <comment file>`.
+import { arg, body, cli, kind, run } from './lib.mjs';
+import { note } from './none.mjs';
+
+const usage = '<n> <comment file>';
+const n = arg(0, usage), file = arg(1, usage);
+const comment = body(file);
+if (kind() === 'none') note(n, comment);
+else if (cli() === 'glab') run(['issue', 'note', n, '-m', comment]);
+else run(['issue', 'comment', n, '--body-file', file]);
+console.log(`noted #${n}`);

package/scripts/tracker/reopen.mjs

@@ -0,0 +1,8 @@
+// tracker.reopen(n): the issue reopened — a held choice the user refused, after its `refused` note,
+// never a `wontfix`. Refused under `tracker.kind: none`, as every write `none.mjs` does not carry: a
+// held choice is validated by its push, and there is no merge request to push it with. `node reopen.mjs <n>`.
+import { arg, run } from './lib.mjs';
+
+const n = arg(0, '<n>');
+run(['issue', 'reopen', n]);
+console.log(`reopened #${n}`);

package/scripts/tracker/search.mjs

@@ -0,0 +1,8 @@
+// tracker.search, one term at a time — the issues that match it, one line each, every page:
+// `node search.mjs <term file> [--all]`. The term arrives by file and goes to the CLI as one argument,
+// with no shell to run a backtick span or a `$(…)` it quotes; `--all` adds the closed issues, as
+// `tracker.search_id` wants them. The ranking across terms is `rank`'s (lib.mjs).
+import { arg, matching, text } from './lib.mjs';
+
+const term = text(arg(0, '<term file> [--all]'));
+process.stdout.write(matching(term, process.argv[3] === '--all').map((l) => `${l}\n`).join(''));

package/scripts/tracker/search_id.mjs

@@ -0,0 +1,18 @@
+// tracker.search_id(<key>, all?): the open issues — every one with `--all` — whose title's tag holds
+// the key whole, one line each: search.mjs (under `none`, issues/ titles) piped into title.search_id_filter.mjs. `node search_id.mjs <key file> [--all]`; a failure of either is the operation's.
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { arg, die, kind } from './lib.mjs';
+import { lines } from './none.mjs';
+
+const key = arg(0, '<key file> [--all]');
+const step = (script, args, input = '') => {
+  const r = spawnSync(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), script), ...args], { encoding: 'utf8', input, maxBuffer: 256 * 1024 * 1024 });
+  if (r.status !== 0) die((r.stderr || r.stdout).trim());
+  return r.stdout;
+};
+const all = process.argv[3] === '--all';
+// Under `none` the listing is issues/'s own titles; on a forge, search.mjs's.
+const listing = kind() === 'none' ? lines(all).join('\n') : step('search.mjs', process.argv.slice(2));
+process.stdout.write(step('title.search_id_filter.mjs', [key], listing));

package/scripts/tracker/templates/bug.md

@@ -0,0 +1,35 @@
+<!-- generated by codelife — edit the plugin, not this file -->
+<!-- codelife: name="Bug" about="Something behaves differently from what it promises" labels="bug" -->
+<!-- Title: the symptom as someone meets it, in one short sentence that fits a line of the issue list. The cause and the mechanism go in the body. -->
+<!-- Body: written for a reader who knows the language and the forge, not this repository. A term the project coined is explained in a few words where it first appears, and linked to the document that defines it; a decision is restated in a sentence, never cited by its number alone. Every link is a full URL: a relative one resolves against the issue's page, not the repository. The length is what that reader needs, and no more. -->
+
+One or two sentences that stand on their own: what goes wrong, for whom. A reader who stops here
+knows what the issue is about.
+
+## Context
+
+The part of the project involved, what it is for, and what it promises — enough for someone new to
+the repository to follow the next section.
+
+## What goes wrong
+
+The behaviour observed against the behaviour promised, with a concrete example. Name the promise —
+a documented API, a test, a stated invariant — rather than an expectation.
+
+## How to see it
+
+The shortest path to the behaviour: a command, a snippet, a test that fails. If the reproduction
+would be an exploitation path on a public repository, say so here and leave it out — it belongs
+in the conversation with the maintainer, not in a public issue.
+
+## Where it comes from
+
+One sentence saying what the title's origin points at, linked: the audit finding, the merge
+request, the issue it was noticed on — or the module, the commit or the release where it appears.
+
+From the specification, it cites the rule and, under it, one line per case the issue covers —
+their headings as on the day it is filed, a snapshot nobody corrects, since the identifier still
+resolves — then the link to the document, there for the click and no part of the address:
+
+R-<n> — <heading>
+- C-<n> — <heading>

package/scripts/tracker/templates/feature.md

@@ -0,0 +1,40 @@
+<!-- generated by codelife — edit the plugin, not this file -->
+<!-- codelife: name="Feature" about="Something the repository should do and does not yet" labels="feature" -->
+<!-- Title: the symptom as someone meets it, in one short sentence that fits a line of the issue list. The cause and the mechanism go in the body. -->
+<!-- Body: written for a reader who knows the language and the forge, not this repository. A term the project coined is explained in a few words where it first appears, and linked to the document that defines it; a decision is restated in a sentence, never cited by its number alone. Every link is a full URL: a relative one resolves against the issue's page, not the repository. The length is what that reader needs, and no more. -->
+
+One or two sentences that stand on their own: what is missing, for whom. A reader who stops here
+knows what the issue is about.
+
+## Context
+
+The part of the project involved, what it is for, and what it promises — enough for someone new to
+the repository to follow the next sections.
+
+## What is missing
+
+The capability, from the point of view of whoever needs it — a consumer of the library, a
+contributor, an agent working the repository — and what it makes possible that is not possible
+today.
+
+## What it would change
+
+The public surface, the configuration, the documentation — anything a consumer would notice, and
+whether it breaks one.
+
+## What it is not
+
+The nearest thing this issue deliberately does not cover, so that scope creep has a line to cross
+visibly. A rejected alternative and its reason belong here too.
+
+## Where it comes from
+
+One sentence saying what the title's origin points at, linked: the audit finding, the feature
+document, the merge request or the issue it was noticed on.
+
+From the specification, it cites the rule and, under it, one line per case the issue covers —
+their headings as on the day it is filed, a snapshot nobody corrects, since the identifier still
+resolves — then the link to the document, there for the click and no part of the address:
+
+R-<n> — <heading>
+- C-<n> — <heading>

package/scripts/tracker/templates/lot.md

@@ -0,0 +1,46 @@
+<!-- generated by codelife — edit the plugin, not this file -->
+<!-- codelife: name="Lot" about="An umbrella issue carrying the remediation order of a lot" labels="lot" -->
+
+<!--
+  The umbrella of a lot. Title: [lot · <origin>] <name> — audit:A<n>-lot-<X> for an audit's lot,
+  spec:C-<n> for a specification's, its first case — an older one's spec:J-<n> or spec:K-<n> —,
+  citation for the citation lot, triage:<slug> for a triage's. `codelife issue create` writes
+  the tag itself: the `# ` line of the file it is handed carries the name alone.
+  The name is the symptom the members share, in one short sentence that fits a line of the
+  issue list; the cause goes in the body.
+  One lot is one merge request on one lot/ branch, so a lot that no longer fits one
+  merge request is two lots.
+-->
+<!-- Body: written for a reader who knows the language and the forge, not this repository. A term the project coined is explained in a few words where it first appears, and linked to the document that defines it; a decision is restated in a sentence, never cited by its number alone. Every link is a full URL: a relative one resolves against the issue's page, not the repository. The length is what that reader needs, and no more. -->
+
+One or two sentences that stand on their own: the symptom these issues share, and what landing
+them restores. A reader who stops here knows what the lot is about.
+
+## Context
+
+The common cause, explained with one concrete example — a root cause, a subsystem, a promise to
+restore. Then one sentence per member saying how it is an instance of that cause. A lot whose
+members share only their severity is not a lot.
+
+## The order
+
+The remediation order, and it is an order: each line is ticked by `codelife issue close` as it closes.
+Leave it empty here — every row is appended by `codelife lot join`, the only writer of this list,
+so a number is read from the member it joined rather than typed before that member exists.
+
+Effort is `S` / `M` / `L`, proposed by the audit's lens subagent and corrected by hand here. It moves as the work is understood, which is why it is a
+line in this list and not a label.
+
+## Dependencies
+
+What must land before this lot starts, inside or outside the repository. *None* is an answer.
+
+## Done when
+
+The observable state that closes this umbrella — a suite green, a promise restored, a drift
+measured back to zero. Not "all the issues are closed": that is the task list's job.
+
+## Where it comes from
+
+One sentence saying what the title's origin points at, linked: the audit's plan, the feature
+document, or the triage that grouped these issues.

package/scripts/tracker/title.join.mjs

@@ -0,0 +1,6 @@
+// A member's title once it joins lot #n: `node title.join.mjs <n> < <title file>`.
+import { arg, text } from './lib.mjs';
+
+const [n, title] = [arg(0, '<n> < <title file>'), text(0)];
+const close = title.indexOf(']');
+console.log(title.startsWith('[') && title.startsWith('] ', close) ? `${title.slice(0, close)} · lot #${n}]${title.slice(close + 1)}` : `[lot #${n}] ${title}`);

package/scripts/tracker/title.leave.mjs

@@ -0,0 +1,7 @@
+// A member's title once it leaves lot #n, only the half `title.join.mjs` wrote:
+// `node title.leave.mjs <n> < <title file>`.
+import { arg, text } from './lib.mjs';
+
+const [n, title] = [arg(0, '<n> < <title file>'), text(0)];
+const bare = title.replace(` · lot #${n}]`, () => ']');
+console.log(bare.startsWith(`[lot #${n}] `) ? bare.slice(`[lot #${n}] `.length) : bare);

package/scripts/tracker/title.lot_of.mjs

@@ -0,0 +1,8 @@
+// The lot a member's title names — nothing for an umbrella or an orphan:
+// `node title.lot_of.mjs < <title file>`.
+import { text } from './lib.mjs';
+
+const title = text(0);
+const tag = title.startsWith('[') && title.includes(']') ? title.slice(0, title.indexOf(']')) : '';
+if (tag.startsWith('[lot #')) console.log(tag.slice('[lot #'.length));
+else if (tag.includes(' · lot #')) console.log(tag.slice(tag.lastIndexOf(' · lot #') + ' · lot #'.length));

package/scripts/tracker/title.search_id_filter.mjs

@@ -0,0 +1,17 @@
+// The titles of a list, one per line on stdin, whose leading tag holds the key whole — `[`, `:` or a
+// space before it, `]` or a space after — so `A3-PKG-2` is not `A3-PKG-21` and a key cited in the
+// sentence is no hit: `node title.search_id_filter.mjs <key file> < <list>`.
+import { arg, text } from './lib.mjs';
+
+const key = text(arg(0, '<key file> < <list>'));
+const whole = (tag) => {
+  for (let i = tag.indexOf(key); key && i >= 0; i = tag.indexOf(key, i + 1)) {
+    if (i > 0 && '[: '.includes(tag[i - 1]) && '] '.includes(tag[i + key.length] ?? '\0')) return true;
+  }
+  return false;
+};
+for (const line of text(0).split('\n')) {
+  const b = line.indexOf('[');
+  const e = b < 0 ? -1 : line.indexOf(']', b);
+  if (e >= 0 && whole(line.slice(b, e + 1))) console.log(line);
+}

package/scripts/tracker/title.sentence_of.mjs

@@ -0,0 +1,5 @@
+// A title without its tag: `node title.sentence_of.mjs < <title file>`.
+import { text } from './lib.mjs';
+
+const title = text(0);
+console.log(title.startsWith('[') && title.includes('] ') ? title.slice(title.indexOf('] ') + 2) : title);

package/scripts/tracker/view.mjs

@@ -0,0 +1,25 @@
+// The issue as JSON — title, body, state, labels, milestone, its comments oldest first (lib.mjs's
+// `comments`) and its state events, each close and reopening with its date: on glab from their own
+// endpoint, a close being no note; on gh the events API. Under `none`, the file, with no history of
+// its state. `--bare` reads neither comments nor events, one forge call: what a lot's join and leave read.
+import { arg, cli, comments, commentsOf, kind, ndjson, origin, run } from './lib.mjs';
+import { view } from './none.mjs';
+import { lf } from '../text.mjs';
+
+const n = arg(0, '<n> [--bare]'), bare = process.argv[3] === '--bare';
+let issue;
+if (kind() === 'none') issue = view(n);
+else if (cli() === 'glab') {
+  const i = JSON.parse(run(['issue', 'view', n, '-F', 'json']));
+  issue = { title: i.title, body: i.description || '', state: i.state, labels: i.labels || [], milestone: i.milestone?.title || '' };
+  if (!bare) Object.assign(issue, { comments: commentsOf(run(comments(n))),
+    events: ndjson(run(['api', `projects/:id/issues/${n}/resource_state_events`, '--paginate', '--output', 'ndjson']))
+      .map((e) => ({ state: e.state, date: e.created_at })) });
+} else {
+  const out = run(['issue', 'view', n, '--json', `title,body,state,labels,milestone${bare ? '' : ',comments'}`]), i = JSON.parse(out);
+  issue = { title: i.title, body: i.body || '', state: i.state, labels: (i.labels || []).map((l) => l.name), milestone: i.milestone?.title || '' };
+  if (!bare) Object.assign(issue, { comments: commentsOf(out),
+    events: JSON.parse(run(['api', `repos/${origin().project}/issues/${n}/events`, '--paginate', '--slurp'])).flat()
+      .filter((e) => e.event === 'closed' || e.event === 'reopened').map((e) => ({ state: e.event, date: e.created_at })) });
+}
+console.log(JSON.stringify(issue, (_, v) => (typeof v === 'string' ? lf(v) : v)));