@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/runtime/lifecycle/release.js

@@ -0,0 +1,241 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * `lifecycle --action release` and `--action merged` (IC-020, IC-021, DEC-021, DEC-022, DEC-030,
+ * DEC-044). A release is previewed from git and recorded, on `--confirm`, as one local
+ * `release.recorded` event; nothing is written into the release commit, nothing is staged or
+ * committed, and no ignore rule is written. Each function returns a result object without printing.
+ *
+ * The integration ref is `facts.integration_ref` from `do-git-state.sh --lifecycle`, the very value
+ * the status deriver pins, so a preview before the tag and the overview agree about one ref and this
+ * module never resolves a ref a second way.
+ *
+ * Candidate choice reuses `deriveStatuses` with the release tags minus the tag being recorded: a
+ * feature then reads `finished` only when a record names it or an OTHER unrecorded `v*` tag contains
+ * its merge (DEC-030), which is the "ignore containment in `--tag`" rule without a change to status.js.
+ * A feature is dropped for exactly three reasons (IC-020): a release record names it, another
+ * unrecorded `v*` tag contains it, or no evidence of its merge reaches X.
+ *
+ * Evidence into X is looked for in two places: the derivation against the pinned integration ref
+ * (the normal case: features merge into develop, the tag is cut from it) and, when the tag exists, a
+ * second derivation against the tag's own first-parent chain (a hotfix merged only into the
+ * production branch). Each gives the full merge commit, which must be an ancestor of X. When a branch
+ * was merged more than once, the newest merge may lie after the tag; an earlier merge of the same
+ * branch (or of a merge naming the slug) that X contains then counts. The ancestry questions about X
+ * are answered from one graph read (`readHistory`) of the pinned ref, X and the evidence branch tips,
+ * so the preview costs a fixed number of git calls however many features and merges there are.
+ * Accepted ceiling: the search for an earlier merge walks, in memory, the integration ref's
+ * first-parent merges inside X once per feature that needs it.
+ *
+ * `evidence.commit` and the pinned sha come from `deriveStatuses` (`evidenceCommits`, `integrationSha`),
+ * so this module neither re-resolves the integration ref nor an abbreviated sha.
+ */
+
+const nodeFs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const { isSafeSlug, invalidSlugRefusal } = require('../task-scope.js');
+const { appendEvents, readFold } = require('./event-store.js');
+const { deriveStatuses, readGitFacts, behindNote, subjectNames, readMerges, readBranchTips, readHistory } = require('./status.js');
+const { FollowupUsageError, oneLine, channelBy } = require('./followup.js');
+
+/** The release-tag pattern of IC-020, the one `git-state` filters by. */
+const RELEASE_TAG = /^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/;
+
+const refusal = (action     , finding     , message     ) => ({ ok: false, action, finding, message });
+
+/** Trimmed stdout of a git call, or null when git exits non-zero. */
+function gitOut(root     , args     ) {
+  const run = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+  return run.status === 0 ? run.stdout.trim() : null;
+}
+
+function commitOf(root     , ref     ) { return gitOut(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]) || null; }
+
+/** `a` is an ancestor of (or equal to) `b`. */
+function isAncestor(root     , a     , b     ) {
+  return spawnSync('git', ['merge-base', '--is-ancestor', a, b], { cwd: root, stdio: 'ignore' }).status === 0;
+}
+
+/**
+ * Evidence of an earlier merge of a branch that was merged more than once: a merge X contains, committed
+ * since tracking, whose subject names the slug or whose non-first parent is an ancestor of the branch tip.
+ * `merges` are the pinned ref's first-parent merges inside X, newest first; `history` holds X and the tip.
+ */
+function earlierMerge({ slug, evidence, tip, lowerBound, merges, bound, history }     ) {
+  if (tip && history.isAncestor(tip, bound)) return { ...evidence };
+  for (const merge of merges) {
+    if (merge.ct < lowerBound) continue;
+    // The merged side is this branch's own when it is an ancestor of the tip and the merge itself is not: a
+    // branch cut from the integration ref after that merge has the merge in its history and did not make it.
+    // A parent outside the first parent's history is one this merge introduced.
+    const own = (parent     ) => history.introducer(parent) === merge.sha && history.isAncestor(parent, tip);
+    if (tip && merge.parents.slice(1).some(own) && !history.isAncestor(merge.sha, tip)) return { ...evidence };
+    if (subjectNames(merge.subject, slug)) return { kind: 'merge-subject', ref: merge.sha.slice(0, 7) };
+  }
+  return null;
+}
+
+/**
+ * The tag a release follows (it only feeds the output): the base tag `git-state` proposes versions
+ * from, other than `tag`, when it is a release tag lying in X's history; else the newest release tag
+ * other than `tag` merged into X (git's version order). A `v*` tag that is not a release (`vnext`)
+ * never qualifies.
+ */
+function previousTagOf(root     , { tag, facts, bound }     ) {
+  const known = new Set(facts.release_tags);
+  if (facts.base_tag && facts.base_tag !== tag && known.has(facts.base_tag) && isAncestor(root, `refs/tags/${facts.base_tag}`, bound)) return facts.base_tag;
+  const merged = gitOut(root, ['tag', '--list', 'v*', '--sort=-v:refname', '--merged', bound]);
+  return (merged || '').split('\n').find((name     ) => name && name !== tag && known.has(name)) || null;
+}
+
+function slugList(raw     , label     ) {
+  const list = [...new Set((Array.isArray(raw) ? raw : raw === undefined || raw === null ? [] : [raw]).map(String))];
+  for (const slug of list) if (!isSafeSlug(slug)) throw new FollowupUsageError(`${label}: ${invalidSlugRefusal(slug).message}`);
+  return list;
+}
+
+/**
+ * IC-020. Without `confirm` nothing is written; with it one `release.recorded` event is.
+ * @param {Object} options
+ * @param {string} options.root the IC-001 root
+ * @param {string} options.tag `vX.Y.Z[-pre]`
+ * @param {boolean} [options.confirm]
+ * @param {string[]} [options.features] `--feature` slugs to add
+ * @param {string[]} [options.exclude] `--exclude` slugs to leave out
+ * @param {string} [options.channel]
+ * @param {Object} [options.facts] `readGitFacts` output, for a caller that already has it
+ */
+function releaseFeatures({ root, tag, confirm = false, features, exclude, channel, now = new Date(), fsImpl = nodeFs, facts: givenFacts }     ) {
+  if (typeof tag !== 'string' || !RELEASE_TAG.test(tag)) throw new FollowupUsageError(`--tag is required and must look like v1.2.3 or v1.2.3-rc.1 (got '${tag ?? ''}')`);
+  const added = slugList(features, '--feature');
+  const excluded = slugList(exclude, '--exclude');
+  const by = channelBy(channel);
+
+  const facts = givenFacts || readGitFacts(root);
+  if (facts.error) return refusal('release', 'no-integration-ref', `git facts are unavailable (${facts.error}), so no release can be previewed or recorded. Nothing was written.`);
+  if (!facts.integration_ref) return refusal('release', 'no-integration-ref', 'no integration ref resolves (develop, main, master, origin/HEAD), so no release can be previewed or recorded. Nothing was written.');
+
+  const fold = readFold(root, { fsImpl, now });
+  const trackedSlugs = new Set(fold.features.map((f     ) => f.slug));
+  // An exclusion is permanent for its tag, so a mistyped slug must not be recorded any more than a mistyped addition.
+  const untracked = [...new Set([...added, ...excluded])].filter((slug) => !trackedSlugs.has(slug));
+  if (untracked.length) {
+    return refusal('release', 'untracked-feature', `${untracked.join(', ')} ${untracked.length === 1 ? 'is' : 'are'} not tracked, so ${untracked.length === 1 ? 'it' : 'they'} cannot be added to or excluded from a release; run doflow-run lifecycle --action init --slug <slug> first. Nothing was written.`);
+  }
+
+  // DEC-030: containment in the tag being recorded never finishes a feature before its record exists.
+  const otherTags = { ...facts, release_tags: facts.release_tags.filter((name     ) => name !== tag) };
+  const derived = deriveStatuses({ root, fold, facts: otherTags });
+  if (derived.releaseMode === 'unknown' || !derived.integrationSha) return refusal('release', 'no-integration-ref', `${derived.reason || `${facts.integration_ref} does not resolve to a commit`}. Nothing was written.`);
+
+  // X: the tag's commit once it exists, else the commit the status view pinned the integration ref to (DEC-044).
+  const tagCommit = commitOf(root, `refs/tags/${tag}`);
+  const bound = tagCommit || derived.integrationSha;
+  const previousTag = previousTagOf(root, { tag, facts, bound });
+  // A hotfix merged only into the tag's own history has no evidence on the integration chain: derive against the tag as well.
+  const atTag = tagCommit && tagCommit !== derived.integrationSha ? deriveStatuses({ root, fold, facts: { ...otherTags, integration_ref: tagCommit } }) : null;
+
+  const recorded = new Set(fold.releases.flatMap((release     ) => release.features.map((f     ) => f.slug)));
+  const tagged = derived.releaseMode === 'tagged';
+  // While X is the pinned commit, every evidence commit is in its history. Once X is a tag elsewhere, one
+  // graph read of the pinned ref, X and the evidence branch tips answers every ancestry question about X.
+  let read      = null;
+  const readOfX = () => {
+    if (read) return read;
+    const branchRefs = new Set(fold.features.map((f     ) => derived.statuses[f.slug].evidence).filter((e     ) => e && e.kind === 'branch').map((e     ) => e.ref));
+    // Local branches are listed first, so a ref resolves as refs/heads/<ref> before refs/remotes/<ref>.
+    const tips = new Map();
+    for (const t of readBranchTips(root)) if (branchRefs.has(t.short) && !tips.has(t.short)) tips.set(t.short, t.sha);
+    const history = readHistory(root, derived.integrationSha, [bound, ...tips.values()]);
+    const merges = readMerges(root, derived.integrationSha).filter((m     ) => history.isAncestor(m.sha, bound)).reverse();
+    read = { history, merges, tips };
+    return read;
+  };
+  const inX = (commit     ) => bound === derived.integrationSha || readOfX().history.isAncestor(commit, bound);
+  const candidates = [];
+  const notDetected = [];
+  // A git failure while reading X's history is an environment fault: a refusal, never a throw that would
+  // reach failure capture (NFR-005), as the status derivation reports its own as `unknown`.
+  try {
+    for (const feature of fold.features) {
+      const { slug } = feature;
+      if (recorded.has(slug)) continue;
+      const entry = derived.statuses[slug];
+      const hotfix = atTag && atTag.statuses[slug];
+      // With another v* tag in play, `finished` here means an unrecorded tag already contains the merge.
+      if (tagged && (entry.status === 'finished' || (hotfix && hotfix.status === 'finished'))) continue;
+      const evidence = entry.evidence;
+      let found = null;
+      if (evidence) {
+        const commit = derived.evidenceCommits[slug];
+        if (evidence.kind === 'confirmed' || (commit && inX(commit))) found = evidence;
+      }
+      if (!found && hotfix && hotfix.evidence) found = hotfix.evidence;
+      if (!found && evidence) {
+        const { history, merges, tips } = readOfX();
+        const tip = evidence.kind === 'branch' ? tips.get(evidence.ref) || null : null;
+        const lowerBound = Math.floor(Date.parse(feature.trackedAt) / 1000);
+        found = earlierMerge({ slug, evidence, tip, lowerBound, merges, bound, history });
+      }
+      if (found) candidates.push({ slug, evidence: found.kind, ref: found.ref }); else notDetected.push(slug);
+    }
+  } catch (error     ) {
+    return refusal('release', 'no-integration-ref', `git could not answer while reading the history of ${tagCommit ? tag : facts.integration_ref} (git-state-failed): ${String(error.message).split('\n')[0]}. Nothing was written.`);
+  }
+
+  const shipped = [...candidates];
+  for (const slug of added) if (!shipped.some((c) => c.slug === slug)) shipped.push({ slug, evidence: 'confirmed', ref: null });
+  const finishing = shipped.filter((c) => !excluded.includes(c.slug));
+  const finishingSlugs = new Set(finishing.map((c) => c.slug));
+  const followupsDone = fold.followups.filter((item     ) => item.state === 'taken' && finishingSlugs.has(item.takenBy)).map((item     ) => item.id);
+
+  const base      = { ok: true, action: 'release', tag, previousTag, bound: tagCommit ? tag : facts.integration_ref, integrationRef: facts.integration_ref };
+  if (derived.integrationBehind > 0) base.note = behindNote(facts.integration_ref, derived.integrationBehind);
+
+  if (!confirm) {
+    const addHint = 'add --feature <slug> for a feature listed under notDetected that shipped';
+    return {
+      ...base, recorded: false, candidates, added, excluded, notDetected, followupsDone,
+      next: [tagCommit
+        ? `Record it: doflow-run lifecycle --action release --tag ${tag} --confirm (${addHint}; --exclude <slug> leaves one out)`
+        : `After git tag ${tag}: doflow-run lifecycle --action release --tag ${tag} --confirm (${addHint})`],
+    };
+  }
+  if (!tagCommit) return refusal('release', 'tag-missing', `${tag} does not exist; create the tag first, then confirm. Nothing was written.`);
+  const out = appendEvents(root, [{ type: 'release.recorded', by, data: { tag, commit: tagCommit, features: finishing, excluded } }], { now, fsImpl });
+  if (!out.ok) return refusal('release', out.finding, out.message);
+  return { ...base, recorded: true, candidates, added, excluded, notDetected, followupsDone, events: out.written.map((w     ) => w.file), next: [] };
+}
+
+/**
+ * IC-021 `merged`: the user's confirmation of a merge git cannot show (squash, rebase, fast-forward,
+ * cherry-pick). It records an observed fact after the merge, one `feature.merged` event, and the
+ * status stays derived from events on read, so nothing is written ahead of the fact (DEC-022).
+ */
+function recordMerged({ root, slug, reason, channel, now = new Date(), fsImpl = nodeFs }     ) {
+  if (!slug) throw new FollowupUsageError('--slug is required for --action merged');
+  if (!isSafeSlug(slug)) throw new FollowupUsageError(invalidSlugRefusal(slug).message);
+  const problems        = [];
+  const cleanReason = reason === undefined ? null : oneLine(reason, '--reason', problems);
+  if (!problems.length && !cleanReason) problems.push('--reason is required for --action merged: how the merge happened, for example "squash-merged by hand"');
+  if (problems.length) throw new FollowupUsageError(problems.join('; '));
+  const by = channelBy(channel);
+
+  const fold = readFold(root, { fsImpl, now });
+  if (!fold.features.some((f     ) => f.slug === slug)) {
+    return refusal('merged', 'untracked-feature', `${slug} is not a tracked feature, so no merge can be confirmed for it; run doflow-run lifecycle --action init --slug ${slug} first. Nothing was written.`);
+  }
+  const before = deriveStatuses({ root, fold }).statuses[slug];
+  if (before.status === 'unknown') return refusal('merged', 'no-integration-ref', `git cannot answer here, so a merge cannot be confirmed against an integration ref. Nothing was written.`);
+  if (before.evidence) {
+    return refusal('merged', 'already-merged', `${slug} already has merge evidence (${before.evidence.kind}${before.evidence.ref ? ` ${before.evidence.ref}` : ''}); nothing to confirm. Nothing was written.`);
+  }
+  const out = appendEvents(root, [{ type: 'feature.merged', by, data: { slug, reason: cleanReason } }], { now, fsImpl });
+  if (!out.ok) return refusal('merged', out.finding, out.message);
+  const after = deriveStatuses({ root, fold: readFold(root, { fsImpl, now }) }).statuses[slug];
+  return { ok: true, action: 'merged', slug, status: after.status, evidence: after.evidence, release: after.release, events: out.written.map((w     ) => w.file), next: [] };
+}
+
+module.exports = { releaseFeatures, recordMerged, RELEASE_TAG };

package/src/runtime/lifecycle/report-store.js

@@ -0,0 +1,221 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The machine-local report body (IC-005, DEC-014). A report's text can hold a crash trace, a log or
+ * pasted output, so it never enters the repository: the body is masked with the body profile (IC-012),
+ * cut to at most 1 MiB and written once under the same per-machine home the failure store uses,
+ * `<XDG_CONFIG_HOME or $HOME/.config>/doflow/reports/<projectKey>/<FU-id>.txt`, folder 0700 and file
+ * 0600. The project event carries only a reference, the size and a masked 2 KB excerpt.
+ *
+ * `projectKey` is the first 12 hex characters of the SHA-256 of the IC-001 root's real path, so two
+ * clones of one project on one machine keep separate bodies, and a body is found again from any
+ * worktree that shares the root.
+ *
+ * The cut is by bytes and backs off to a UTF-8 boundary. Nothing here touches the network.
+ */
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const mask = require('../mask.js');
+
+/** A `--file` or `--stdin` source is read for at most this many bytes; the rest could not be kept anyway. */
+const MAX_READ_BYTES = 16 * 1024 * 1024;
+/** The most a stored body holds, marker line included. */
+const MAX_BODY_BYTES = 1024 * 1024;
+const TRUNCATED = '[truncated by doflow at 1 MiB]';
+/** Masking sees at most this much of a long body: the limit plus a margin that masking can shrink back into it. */
+const MASK_INPUT_BYTES = MAX_BODY_BYTES + 64 * 1024;
+const FU_ID = /^FU-[0-9a-hjkmnp-tv-z]{6}$/;
+/** CSI (`ESC [ ... final`) and OSC (`ESC ] ... BEL` or `ESC \`) sequences: terminal colour and title codes in a pasted log. */
+const ANSI = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
+/** The most of the masked body the project event carries. */
+const EXCERPT_BYTES = 2048;
+
+/** A caller mistake in the report input (exit 2); the verb layer maps it with the other usage errors. */
+class ReportInputError extends Error {}
+
+/**
+ * The folder holding every project's report bodies, or null when no home resolves. It resolves the
+ * base the way IC-011 resolves the failure home (`XDG_CONFIG_HOME` when set, non-empty and absolute,
+ * else `$HOME/.config` when `HOME` is absolute) and sits beside it, `doflow/reports`. The rule is
+ * repeated here rather than required from the failure module, so the follow-up service still loads in
+ * a build or an install where the failure modules cannot be loaded (IC-016).
+ */
+function reportsHome(env                                     = process.env)                {
+  const xdg = env.XDG_CONFIG_HOME;
+  if (typeof xdg === 'string' && xdg !== '') return path.isAbsolute(xdg) ? path.join(xdg, 'doflow', 'reports') : null;
+  const home = env.HOME;
+  return typeof home === 'string' && path.isAbsolute(home) ? path.join(home, '.config', 'doflow', 'reports') : null;
+}
+
+function realProjectRoot(root        , fsImpl      = nodeFs)         {
+  try { return fsImpl.realpathSync(root); } catch { return root; }
+}
+
+function projectKey(root        , fsImpl      = nodeFs)         {
+  return crypto.createHash('sha256').update(realProjectRoot(root, fsImpl)).digest('hex').slice(0, 12);
+}
+
+/** @returns {string|null} the body file of a report of this project, or null when no home resolves */
+function bodyPath(root        , id        , { env = process.env, fsImpl = nodeFs }      = {})                {
+  const home = reportsHome(env);
+  return home === null ? null : path.join(home, projectKey(root, fsImpl), `${id}.txt`);
+}
+
+/** The `hasBody` the fold needs (IC-003): a report whose body file is on this machine. */
+function bodyChecker(root        , { env = process.env, fsImpl = nodeFs }      = {})                         {
+  const home = reportsHome(env);
+  const folder = home === null ? null : path.join(home, projectKey(root, fsImpl));
+  return (item     )          => {
+    // The id comes from an event file, so it is checked before it becomes part of a path.
+    if (folder === null || !FU_ID.test(String(item.id)) || item.bodyRef !== `local:${item.id}`) return false;
+    try { return fsImpl.statSync(path.join(folder, `${item.id}.txt`)).isFile(); } catch { return false; }
+  };
+}
+
+/** Reads at most `max` bytes from an open descriptor. */
+function readCapped(fsImpl     , fd        , max        )         {
+  const chunks           = [];
+  let total = 0;
+  const chunk = Buffer.allocUnsafe(64 * 1024);
+  while (total < max) {
+    const n = fsImpl.readSync(fd, chunk, 0, Math.min(chunk.length, max - total), null);
+    if (n === 0) break;
+    chunks.push(Buffer.from(chunk.subarray(0, n)));
+    total += n;
+  }
+  return Buffer.concat(chunks);
+}
+
+/**
+ * The raw report text from exactly one of `--file`, `--stdin` or `--text`. A file is read as text, at
+ * most 16 MiB (`--file -` reads stdin); a binary one (a NUL byte) is refused.
+ * @param {{file?: string, stdin?: boolean, text?: string}} source
+ * @returns {string}
+ */
+function readReportText({ file, stdin: stdinFlag, text }                                                   , { fsImpl = nodeFs }      = {})         {
+  // `--file -` is stdin, as everywhere else a `-` stands for it.
+  const stdin = Boolean(stdinFlag) || file === '-';
+  if (file === '-') file = undefined;
+  const given = [file !== undefined, Boolean(stdin), text !== undefined].filter(Boolean).length;
+  if (given !== 1) throw new ReportInputError('give the report body with exactly one of --file <path>, --stdin or --text "<body>" (--file and --stdin also take text that starts with -)');
+  if (text !== undefined) return String(text);
+  let bytes        ;
+  if (stdin) {
+    try { bytes = readCapped(fsImpl, 0, MAX_READ_BYTES); } catch (error     ) { throw new ReportInputError(`cannot read the report from stdin: ${error.message}`); }
+  } else {
+    const target = path.resolve(file          );
+    let fd                    ;
+    try {
+      if (!fsImpl.statSync(target).isFile()) throw new ReportInputError(`--file ${file} is not a regular file`);
+      fd = fsImpl.openSync(target, 'r');
+      bytes = readCapped(fsImpl, fd          , MAX_READ_BYTES);
+    } catch (error     ) {
+      if (error instanceof ReportInputError) throw error;
+      throw new ReportInputError(`cannot read --file ${file}: ${error.code || error.message}`);
+    } finally {
+      if (fd !== undefined) { try { fsImpl.closeSync(fd); } catch { /* read already done */ } }
+    }
+  }
+  if (bytes.includes(0)) throw new ReportInputError('the report body is binary (it holds a NUL byte); give a text file or paste the text');
+  return bytes.toString('utf8');
+}
+
+/** The length of the longest prefix of `buffer` of at most `limit` bytes that ends on a UTF-8 boundary. */
+function boundary(buffer        , limit        )         {
+  let end = Math.min(limit, buffer.length);
+  if (end === buffer.length) return end;
+  while (end > 0 && (buffer[end] & 0xc0) === 0x80) end -= 1;
+  return end;
+}
+
+/**
+ * The text masking will see: ANSI sequences removed, then cut to the limit plus a margin so one very
+ * long input cannot make a mask rule recurse too deep. The cut is at the last line end in range, else the
+ * last whitespace, else nothing is kept (an unbroken run has no clean boundary), always on a UTF-8
+ * boundary; a token straddling the cut goes with the incomplete tail, never half-masked.
+ * @returns {{text: string, cut: boolean}}
+ */
+function boundMaskInput(raw        )                                 {
+  const stripped = raw.replace(ANSI, '');
+  const whole = Buffer.from(stripped, 'utf8');
+  if (whole.length <= MASK_INPUT_BYTES) return { text: stripped, cut: false };
+  const head = whole.subarray(0, boundary(whole, MASK_INPUT_BYTES));
+  let end = head.lastIndexOf(0x0a);
+  if (end < 0) for (let i = head.length - 1; i >= 0; i -= 1) if ([0x20, 0x09, 0x0d, 0x0b, 0x0c].includes(head[i])) { end = i; break; }
+  return { text: end < 0 ? '' : head.subarray(0, end).toString('utf8'), cut: true };
+}
+
+/**
+ * Masks a report body with the body profile and keeps at most 1 MiB of it. A longer body is cut at a
+ * UTF-8 boundary and ends with the marker line, so the stored text is never over the limit. A body
+ * the mask cannot process is refused as a caller mistake, with one line and no echo of the input.
+ * @param {string} raw
+ * @param {{home?: string}} [options] the home directory the mask replaces with `~`
+ * @returns {{buffer: Buffer, masked: number, truncated: boolean}}
+ */
+function prepareBody(raw        , { home }                    = {})                                                         {
+  const { text: bounded, cut } = boundMaskInput(raw);
+  let result     ;
+  try {
+    result = mask.maskBody(bounded, home === undefined ? undefined : { home });
+  } catch {
+    throw new ReportInputError('the report body could not be masked safely (its text is too irregular to process); cut it down or file the relevant part');
+  }
+  const whole = Buffer.from(result.text, 'utf8');
+  if (whole.length <= MAX_BODY_BYTES && !cut) return { buffer: whole, masked: result.masked, truncated: false };
+  const marker = Buffer.from(`\n${TRUNCATED}`, 'utf8');
+  const kept = whole.subarray(0, boundary(whole, MAX_BODY_BYTES - marker.length));
+  return { buffer: Buffer.concat([kept, marker]), masked: result.masked, truncated: true };
+}
+
+/**
+ * The first 2048 bytes of a stored body, cut at a UTF-8 boundary and, when a line end lies inside
+ * the limit, at that line end (DEC-014).
+ * @param {Buffer} body
+ * @returns {string}
+ */
+function excerptOf(body        )         {
+  if (body.length <= EXCERPT_BYTES) return body.toString('utf8').replace(/\s+$/, '');
+  const head = body.subarray(0, boundary(body, EXCERPT_BYTES));
+  const lineEnd = head.lastIndexOf(0x0a);
+  return (lineEnd > 0 ? head.subarray(0, lineEnd) : head).toString('utf8').replace(/\s+$/, '');
+}
+
+/**
+ * Writes the body once: exclusive create, file 0600, folders 0700, never inside the repository.
+ * @returns {{ok: true, file: string}|{ok: false, reason: 'no-home'|'exists'|'error', message?: string}}
+ */
+function writeBody(root        , id        , buffer        , { env = process.env, fsImpl = nodeFs }      = {})                                                                    {
+  const file = bodyPath(root, id, { env, fsImpl });
+  if (file === null) return { ok: false, reason: 'no-home' };
+  const folder = path.dirname(file);
+  try {
+    fsImpl.mkdirSync(folder, { recursive: true, mode: 0o700 });
+    // `mkdir -p` applies the mode under the umask; the two folders that are ours are set outright.
+    fsImpl.chmodSync(folder, 0o700);
+    fsImpl.chmodSync(path.dirname(folder), 0o700);
+    try {
+      fsImpl.writeFileSync(path.join(folder, '.root'), `${realProjectRoot(root, fsImpl)}\n`, { flag: 'wx', mode: 0o600 });
+    } catch (error     ) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+    fsImpl.writeFileSync(file, buffer, { flag: 'wx', mode: 0o600 });
+    return { ok: true, file };
+  } catch (error     ) {
+    return error.code === 'EEXIST' ? { ok: false, reason: 'exists' } : { ok: false, reason: 'error', message: error.code || error.message };
+  }
+}
+
+/** Removes a body this process just wrote, when the event that names it could not be written. */
+function removeBody(file        , fsImpl      = nodeFs)       {
+  try { fsImpl.rmSync(file, { force: true }); } catch { /* the failure being reported stands */ }
+}
+
+module.exports = {
+  readReportText, prepareBody, excerptOf, writeBody, removeBody, bodyChecker, bodyPath, reportsHome, projectKey,
+  ReportInputError, MAX_READ_BYTES, MAX_BODY_BYTES, MASK_INPUT_BYTES, EXCERPT_BYTES, TRUNCATED,
+};