beadcyte 0.4.0

package/src/mutate.mjs

@@ -0,0 +1,193 @@
+// mutate.mjs — the one place that says what beadcyte may write to a tracker
+// (bp-ocs). Shared by the server, which turns a mutation into a bd command,
+// and the client, which applies the same mutation optimistically while the
+// command runs. One whitelist, one argv builder, one optimistic patch, so the
+// menu, the endpoint and the rollback cannot disagree about what an action is.
+//
+// The operations are the ones the allocate ritual runs through the CLI, one
+// click away: claim, assign to a roster member, mark spec:ready (and undo
+// it), add a label, defer. Each
+// is one bead at a time; there is no bulk, and no client-side undo — the
+// notice points at bd for correction.
+
+const ID_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:\.[a-z0-9]+)*$/i;
+const LABEL_RE = /^[a-z0-9][a-z0-9:_./-]{0,63}$/i;
+const HANDLE_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const TITLE_RE = /^[^\x00-\x1f\x7f]{1,200}$/;
+const TYPES = ["task", "feature", "bug", "chore", "epic", "decision"];
+const UNTIL_RE = /^(\+\d{1,3}[hdw]|tomorrow|next (monday|tuesday|wednesday|thursday|friday|saturday|sunday)|\d{4}-\d{2}-\d{2})$/i;
+
+export const READY_LABEL = "spec:ready";
+
+/** @typedef {"claim" | "assign" | "priority" | "spec-ready" | "unspec-ready" | "add-label" | "defer" | "create"} MutationAction */
+export const MUTATION_ACTIONS = /** @type {const} */ (["claim", "assign", "priority", "spec-ready", "unspec-ready", "add-label", "defer", "create"]);
+
+/** The defer horizons the menu offers; bd's own relative syntax. */
+export const DEFER_CHOICES = /** @type {const} */ ([
+  { until: "+1d", label: "a day" },
+  { until: "+3d", label: "three days" },
+  { until: "+1w", label: "a week" },
+  { until: "+2w", label: "two weeks" },
+  { until: "+4w", label: "a month" },
+]);
+
+/**
+ * Check a request body and return the mutation, or throw a message fit for a
+ * 400. Everything a shell argument is built from passes a pattern first.
+ * @param {unknown} raw
+ * @returns {{ action: MutationAction, id: string, label?: string, until?: string, assignee?: string, priority?: number, title?: string, type?: string, labels?: string[] }}
+ */
+export function validateMutation(raw) {
+  if (!raw || typeof raw !== "object") throw new Error("body must be an object");
+  const b = /** @type {Record<string, unknown>} */ (raw);
+  const action = b.action;
+  if (typeof action !== "string" || !MUTATION_ACTIONS.includes(/** @type {any} */ (action))) {
+    throw new Error(`unknown action; expected one of ${MUTATION_ACTIONS.join(", ")}`);
+  }
+  // create has no id yet: the title is what it acts on.
+  if (action === "create") {
+    if (typeof b.title !== "string" || !TITLE_RE.test(b.title.trim())) throw new Error("title must be 1–200 printable characters");
+    if (typeof b.type !== "string" || !TYPES.includes(b.type)) throw new Error(`type must be one of ${TYPES.join(", ")}`);
+    const pri = b.priority;
+    if (typeof pri !== "number" || !Number.isInteger(pri) || pri < 0 || pri > 4) throw new Error("priority must be an integer 0–4");
+    const labels = Array.isArray(b.labels) ? b.labels : [];
+    for (const l of labels) if (typeof l !== "string" || !LABEL_RE.test(l)) throw new Error("labels must be 1–64 of [a-z0-9:_./-]");
+    const out = { action: /** @type {MutationAction} */ ("create"), id: "", title: b.title.trim(), type: b.type, priority: pri, labels: /** @type {string[]} */ (labels) };
+    if (b.assignee !== undefined && b.assignee !== null && b.assignee !== "") {
+      if (typeof b.assignee !== "string" || !HANDLE_RE.test(b.assignee)) throw new Error("assignee must be a handle: 1–64 of [a-z0-9._-]");
+      out.assignee = b.assignee;
+    }
+    return out;
+  }
+  const id = b.id;
+  if (typeof id !== "string" || !ID_RE.test(id)) throw new Error("id is not a bead id");
+  const out = { action: /** @type {MutationAction} */ (action), id };
+  if (action === "priority") {
+    const pri = b.priority;
+    if (typeof pri !== "number" || !Number.isInteger(pri) || pri < 0 || pri > 4) throw new Error("priority must be an integer 0–4");
+    out.priority = pri;
+  }
+  if (action === "assign") {
+    if (typeof b.assignee !== "string" || !HANDLE_RE.test(b.assignee)) throw new Error("assignee must be a handle: 1–64 of [a-z0-9._-]");
+    out.assignee = b.assignee;
+  }
+  if (action === "add-label") {
+    if (typeof b.label !== "string" || !LABEL_RE.test(b.label)) throw new Error("label must be 1–64 of [a-z0-9:_./-]");
+    out.label = b.label;
+  }
+  if (action === "defer") {
+    if (b.until !== undefined && b.until !== null && b.until !== "") {
+      if (typeof b.until !== "string" || !UNTIL_RE.test(b.until)) throw new Error("until must be +Nh/+Nd/+Nw, tomorrow, next <weekday> or YYYY-MM-DD");
+      out.until = b.until;
+    }
+  }
+  return out;
+}
+
+/**
+ * The bd command for a mutation, as argv (no shell). Always the one form the
+ * CLI documents, so a failure can be reproduced by hand from the notice.
+ * @param {{ action: MutationAction, id: string, label?: string, until?: string, assignee?: string }} m
+ * @returns {string[]}
+ */
+export function bdArgsFor(m) {
+  switch (m.action) {
+    case "claim":
+      return ["update", m.id, "--claim"];
+    case "assign":
+      return ["update", m.id, "--assignee", /** @type {string} */ (m.assignee)];
+    case "priority":
+      return ["update", m.id, "--priority", String(m.priority)];
+    case "create": {
+      const args = ["create", /** @type {string} */ (m.title), "-t", /** @type {string} */ (m.type), "-p", String(m.priority)];
+      if (m.labels && m.labels.length) args.push("-l", m.labels.join(","));
+      if (m.assignee) args.push("-a", m.assignee);
+      return args;
+    }
+    case "spec-ready":
+      return ["update", m.id, "--add-label", READY_LABEL];
+    case "unspec-ready":
+      return ["update", m.id, "--remove-label", READY_LABEL];
+    case "add-label":
+      return ["update", m.id, "--add-label", /** @type {string} */ (m.label)];
+    case "defer":
+      return m.until ? ["defer", m.id, "--until", m.until] : ["defer", m.id];
+  }
+  throw new Error(`no command for ${String(m.action)}`);
+}
+
+/** "bd update bp-x --claim" — for logs and docs; the UI speaks in outcomes. */
+export function describeMutation(m) {
+  return `bd ${bdArgsFor(m).join(" ")}`;
+}
+
+/** "claimed", "assigned to alice", "deferred for a week" — what the toast says. */
+export function describeOutcome(m) {
+  switch (m.action) {
+    case "claim":
+      return "claimed";
+    case "assign":
+      return `assigned to ${m.assignee}`;
+    case "priority":
+      return `set to P${m.priority}`;
+    case "create":
+      return `created`;
+    case "spec-ready":
+      return `marked ${READY_LABEL}`;
+    case "unspec-ready":
+      return `${READY_LABEL} removed`;
+    case "add-label":
+      return `label ${m.label} added`;
+    case "defer": {
+      const choice = DEFER_CHOICES.find((c) => c.until === m.until);
+      return m.until ? `deferred for ${choice ? choice.label : m.until}` : "deferred";
+    }
+  }
+  return String(m.action);
+}
+
+/**
+ * What the bead will look like once bd has done it — applied on the client
+ * while the request runs, replaced by the server's fresh bead on success and
+ * by the original on failure. `actor` is the client's best guess at who
+ * `--claim` assigns; the fresh bead corrects it.
+ * @template {{ id: string, status: string, assignee?: string | null, labels?: string[] | null, started_at?: string | null, updated_at?: string }} B
+ * @param {B} bead
+ * @param {{ action: MutationAction, id: string, label?: string, until?: string, assignee?: string }} m
+ * @param {string | null} actor
+ * @param {Date} [now]
+ * @returns {B}
+ */
+export function applyOptimistic(bead, m, actor, now = new Date()) {
+  const iso = now.toISOString();
+  const labels = [...(bead.labels ?? [])];
+  switch (m.action) {
+    case "claim":
+      return { ...bead, status: "in_progress", assignee: actor ?? bead.assignee ?? null, started_at: bead.started_at ?? iso, updated_at: iso };
+    case "assign":
+      // Assignment only: the status is whatever it was. Claiming is the one
+      // that starts work.
+      return { ...bead, assignee: /** @type {string} */ (m.assignee), updated_at: iso };
+    case "priority":
+      return { ...bead, priority: /** @type {number} */ (m.priority), updated_at: iso };
+    case "spec-ready":
+      return { ...bead, labels: labels.includes(READY_LABEL) ? labels : [...labels, READY_LABEL], updated_at: iso };
+    case "unspec-ready":
+      return { ...bead, labels: labels.filter((l) => l !== READY_LABEL), updated_at: iso };
+    case "add-label":
+      return { ...bead, labels: labels.includes(/** @type {string} */ (m.label)) ? labels : [...labels, /** @type {string} */ (m.label)], updated_at: iso };
+    case "defer":
+      return { ...bead, status: "deferred", updated_at: iso };
+  }
+  return bead;
+}
+
+/**
+ * The id of the bead `bd create` just made, from its output line
+ * ("✓ Created issue: bp-abc — title"). Null when the line is not there.
+ * @param {string} stdout
+ */
+export function createdIdFrom(stdout) {
+  const m = /Created issue:\s+(\S+)/.exec(stdout ?? "");
+  return m ? m[1] : null;
+}

package/src/projects.mjs

@@ -0,0 +1,120 @@
+// projects.mjs — which directories beadcyte serve is willing to read beads from.
+//
+// The browser holds the list of project locations (localStorage), but the
+// server is what executes `bd`. So a path necessarily arrives from the
+// client, and that makes /api/beads a request to run a subprocess in a
+// caller-chosen directory. Any page the user visits can issue requests to
+// localhost; it cannot read the responses cross-origin, but it can still
+// make this server probe the filesystem and infer results from timing or
+// error shape.
+//
+// Hence two steps rather than one. Registration validates a path and admits
+// it to a per-process allowlist; reads serve only what was admitted. A path
+// that was never registered is refused WITHOUT touching the filesystem, so
+// an unregistered request cannot be used to test whether a directory exists.
+
+import { existsSync, realpathSync, statSync, accessSync, constants } from "node:fs";
+import { basename, isAbsolute, join, resolve } from "node:path";
+
+/** Why a path was refused. Kept as codes so the UI can phrase them. */
+export const REFUSAL = {
+  NOT_ABSOLUTE: "not-absolute",
+  MISSING: "missing",
+  NOT_A_DIRECTORY: "not-a-directory",
+  NO_BEADS: "no-beads",
+  NOT_READABLE: "not-readable",
+};
+
+/**
+ * Validate a candidate project directory.
+ *
+ * Returns the canonical path on success — symlinks resolved — and the client
+ * is expected to store and resend exactly that, so later reads normalise to
+ * the same string without the server having to call realpath again.
+ */
+export function inspectProject(rawPath) {
+  if (typeof rawPath !== "string" || !rawPath.trim()) {
+    return { ok: false, reason: REFUSAL.MISSING };
+  }
+  const candidate = rawPath.trim();
+
+  // Relative paths are ambiguous once the server's cwd stops being the one
+  // project, so require the caller to be explicit.
+  if (!isAbsolute(candidate)) {
+    return { ok: false, reason: REFUSAL.NOT_ABSOLUTE };
+  }
+
+  if (!existsSync(candidate)) return { ok: false, reason: REFUSAL.MISSING };
+
+  let real;
+  try {
+    real = realpathSync(candidate);
+  } catch {
+    return { ok: false, reason: REFUSAL.MISSING };
+  }
+
+  let st;
+  try {
+    st = statSync(real);
+  } catch {
+    return { ok: false, reason: REFUSAL.NOT_READABLE };
+  }
+  if (!st.isDirectory()) {
+    return { ok: false, reason: REFUSAL.NOT_A_DIRECTORY };
+  }
+
+  try {
+    accessSync(real, constants.R_OK | constants.X_OK);
+  } catch {
+    return { ok: false, reason: REFUSAL.NOT_READABLE };
+  }
+
+  // A beads project is a directory with a .beads database in it. Checked
+  // before admitting rather than on first read, so a mistyped path fails at
+  // the moment the user types it instead of looking like an empty project.
+  if (!existsSync(join(real, ".beads"))) {
+    return { ok: false, reason: REFUSAL.NO_BEADS };
+  }
+
+  return { ok: true, path: real, label: basename(real) || real };
+}
+
+/**
+ * Per-process set of admitted project paths.
+ *
+ * Deliberately not persisted: the allowlist is a statement about this
+ * running server, and a restart should not silently inherit permission to
+ * read directories from a previous session's browser state.
+ */
+export function createAllowlist(seedPaths = []) {
+  const admitted = new Set();
+
+  for (const p of seedPaths) {
+    const seen = inspectProject(p);
+    if (seen.ok) admitted.add(seen.path);
+  }
+
+  return {
+    /** Validate and admit. Returns the inspection result either way. */
+    register(rawPath) {
+      const seen = inspectProject(rawPath);
+      if (seen.ok) admitted.add(seen.path);
+      return seen;
+    },
+
+    /**
+     * Is this path allowed to be read? Uses a PURE normalisation (resolve
+     * only — no realpath, no stat), so refusing an unknown path costs no
+     * filesystem access and leaks nothing about what exists.
+     */
+    allows(rawPath) {
+      if (typeof rawPath !== "string" || !rawPath) return false;
+      if (!isAbsolute(rawPath)) return false;
+      return admitted.has(resolve(rawPath));
+    },
+
+    list() {
+      return [...admitted];
+    },
+  };
+}

package/src/provenance.mjs

@@ -0,0 +1,75 @@
+// provenance.mjs — how a stored value says it was not measured.
+//
+// Two unrelated-looking things need the same answer. `metadata.economics`
+// carries figures that may have been reconstructed (bp-67g.58 rebuilt worked
+// hours from session transcripts), and `metadata.ship` carries evidence that
+// may have been recovered rather than recorded (bp-67g.56 read closing
+// commits out of `Closes <id>` trailers). Both gate models — economics feeds
+// the estimator, ship evidence feeds velocity, the estimator AND the trend —
+// so both need a reader that cannot drift from the other.
+//
+// The convention is a `provenance` sibling map keyed by the field it
+// describes, rather than wrapping each value:
+//
+//   metadata.economics.provenance.by_seat = { method, at, note }
+//   metadata.ship.provenance.commit       = { method, at, note }
+//
+// so every existing reader keeps working and only code that cares about
+// provenance looks it up.
+
+/**
+ * @typedef {Object} Provenance
+ * @property {"recorded" | "derived" | "reconstructed"} kind
+ * @property {string | null} method  the writer's own machine tag, e.g.
+ *   "derived:git-trailer"
+ * @property {string | null} note    the writer's own prose. Printed verbatim
+ *   by the UI: a reconstruction is only judgeable if it says how it was made,
+ *   and the writer knows that while beadcyte does not.
+ * @property {string | null} at      when it was reconstructed
+ */
+
+/** A value nobody flagged. See `readProvenance` for why absence means this. */
+export const RECORDED = /** @type {Provenance} */ ({
+  kind: "recorded",
+  method: null,
+  note: null,
+  at: null,
+});
+
+function str(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+
+/**
+ * Read one field's provenance out of a `provenance` map.
+ *
+ * Accepts either an object (`{method, at, note}`) or a bare string, which is
+ * taken as the method — both are what people actually write. Any entry at all
+ * means the field was not measured; nothing here interprets the method.
+ *
+ * Returns null when there is no entry, which callers read as RECORDED. That
+ * is an assumption and the only one available: every record written before
+ * this convention existed was written at close time by something that had
+ * measured it. A tool that reconstructs a value is expected to say so.
+ *
+ * @param {unknown} raw    the `provenance` map, if any
+ * @param {string} field   the field being asked about
+ * @returns {Provenance | null}
+ */
+export function readProvenance(raw, field) {
+  if (!raw || typeof raw !== "object") return null;
+  const entry = /** @type {Record<string, unknown>} */ (raw)[field];
+  if (entry === undefined || entry === null) return null;
+  if (typeof entry === "string") {
+    const m = str(entry);
+    return m ? { kind: "reconstructed", method: m, note: null, at: null } : null;
+  }
+  if (typeof entry !== "object") return null;
+  const o = /** @type {Record<string, unknown>} */ (entry);
+  return {
+    kind: "reconstructed",
+    method: str(o.method),
+    note: str(o.note),
+    at: str(o.at),
+  };
+}

package/src/review-hours.mjs

@@ -0,0 +1,117 @@
+// review-hours.mjs — hours_in_review from bd history (bp-67g.57).
+//
+// The one economics phase that is recoverable but not cheaply. The first
+// transition into `in_review` lives only in `bd history`, and
+// `bd history --json <id>` returns a FULL issue snapshot per Dolt commit:
+// measured on this repo, 139 entries and 435KB in 435ms for one bead. So it
+// is never read in the request path. history-walk.mjs walks beads in the
+// background, one shell-out per bead whose `updated_at` moved since the last
+// walk, and caches the answer; this file is the arithmetic on what it finds.
+//
+// Pure, so every rule is testable without bd.
+
+const MS_PER_HOUR = 3_600_000;
+
+/**
+ * The moment a bead first entered `in_review`, from its history entries as
+ * `bd history --json` returns them: `{ CommitHash, Committer, CommitDate,
+ * Issue }` in any order. The snapshot's own `updated_at` is preferred — it
+ * is the bead's clock — with the commit date as the fallback. Null when the
+ * bead never entered review, which the caller must keep as ABSENT, not zero.
+ *
+ * @param {ReadonlyArray<{CommitDate?: string, Issue?: {status?: string, updated_at?: string}}>} entries
+ * @returns {string | null} ISO timestamp
+ */
+export function firstInReviewAt(entries) {
+  let best = null;
+  for (const e of entries ?? []) {
+    if (e?.Issue?.status !== "in_review") continue;
+    const at = e.Issue.updated_at || e.CommitDate;
+    const t = at ? Date.parse(at) : NaN;
+    if (!Number.isFinite(t)) continue;
+    if (best === null || t < best) best = t;
+  }
+  return best === null ? null : new Date(best).toISOString();
+}
+
+/**
+ * The moment a bead first had an assignee, from the same history entries:
+ * the earliest snapshot whose Issue.assignee is set (bp-7c9). Null when it
+ * never had one — kept absent downstream, like in_review.
+ *
+ * @param {ReadonlyArray<{CommitDate?: string, Issue?: {assignee?: string|null, updated_at?: string}}>} entries
+ * @returns {string | null}
+ */
+export function firstAssignedAt(entries) {
+  let best = null;
+  for (const e of entries ?? []) {
+    if (!e?.Issue?.assignee) continue;
+    const at = e.Issue.updated_at || e.CommitDate;
+    const t = at ? Date.parse(at) : NaN;
+    if (!Number.isFinite(t)) continue;
+    if (best === null || t < best) best = t;
+  }
+  return best === null ? null : new Date(best).toISOString();
+}
+
+/**
+ * Hours from entering review to the close, or to now while the bead is
+ * still open. Clamped at zero; null when there is no entry time.
+ *
+ * @param {string | null | undefined} inReviewAt
+ * @param {string | null | undefined} closedAt
+ * @param {number} now
+ */
+export function reviewHours(inReviewAt, closedAt, now = Date.now()) {
+  if (!inReviewAt) return null;
+  const start = Date.parse(inReviewAt);
+  if (!Number.isFinite(start)) return null;
+  const endRaw = closedAt ? Date.parse(closedAt) : now;
+  const end = Number.isFinite(endRaw) ? endRaw : now;
+  return Math.max(0, (end - start) / MS_PER_HOUR);
+}
+
+/**
+ * Which beads the walker must visit: anything without a cache entry at its
+ * current `updated_at`. A bead that has not changed since it was last walked
+ * cannot have gained a transition, so the walk is incremental after the
+ * first pass — the first pass is the whole cost.
+ *
+ * @param {ReadonlyArray<{id: string, updated_at?: string}>} beads
+ * @param {Record<string, {updated_at?: string}>} cache
+ * @returns {string[]} bead ids
+ */
+export function planWalk(beads, cache) {
+  const out = [];
+  for (const b of beads) {
+    const hit = cache[b.id];
+    // An entry from before assigned_at existed (bp-7c9) is missing a fact
+    // the walk now records: revisit it once, whatever its updated_at.
+    if (!hit || hit.updated_at !== b.updated_at || hit.assigned_at === undefined) out.push(b.id);
+  }
+  return out;
+}
+
+/**
+ * Attach what the walk knows to each bead as `history`, in place. A bead the
+ * walk has not reached (or that changed since) gets nothing, so the UI
+ * reports the phase as absent rather than as zero or as stale.
+ *
+ * @template {{id: string, updated_at?: string, history?: unknown}} B
+ * @param {B[]} beads
+ * @param {Record<string, {updated_at?: string, in_review_at: string | null, assigned_at?: string | null, walked_at?: string}>} cache
+ * @returns {number} how many beads carry history after the merge
+ */
+export function mergeHistory(beads, cache) {
+  let n = 0;
+  for (const b of beads) {
+    const hit = cache[b.id];
+    if (hit && hit.updated_at === b.updated_at) {
+      b.history = { in_review_at: hit.in_review_at ?? null, assigned_at: hit.assigned_at ?? null, walked_at: hit.walked_at ?? null };
+      n++;
+    } else if (b.history) {
+      delete b.history;
+    }
+  }
+  return n;
+}

package/src/roster-path.mjs

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+/** Conventional roster path. `beadcyte --roster PATH` overrides it. */
+export const ROSTER_CANDIDATES = [
+  ".beadcyte/roster.json",
+];
+
+/**
+ * Resolve the roster for a project directory.
+ *
+ * @param {string} projectDir
+ * @param {string} [override] value of --roster; used verbatim when given,
+ *   because an explicit path must not be second-guessed
+ * @returns {{ path: string } | null} null when none exists
+ */
+export function resolveRosterPath(projectDir, override) {
+  if (override) {
+    const abs = isAbsolute(override) ? override : join(projectDir, override);
+    return existsSync(abs) ? { path: abs } : null;
+  }
+  const abs = join(projectDir, ROSTER_CANDIDATES[0]);
+  return existsSync(abs) ? { path: abs } : null;
+}