@stravica-ai/digital-operator-pa 0.1.66 → 0.1.67

package/dist/engineering-pa-cli/src/pa/cli.mjs

@@ -24,6 +24,7 @@ import {
 import { resolveDefaultScope } from '../secrets/vault.mjs';
 import { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspect/src/cli.mjs';
 import { doOnboard } from './onboard.mjs';
+import { SUBVERBS as STATUS_BOARD_SUBVERBS, run as runStatusBoard } from './status-board-cli.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -32,6 +33,9 @@ const USAGE = `pa - Digital Operator CLI
 Usage:
   pa session                  Start a PA session — chdir to agent dir, exec \`claude\`
   pa status                   Probe operator content, installed package, and workspace reachability, then print a desk overview
+  pa status set [--file <p>]  Replace this PA's daily status board from a JSON file or stdin
+  pa status patch [flags]     Merge one board item or on-me entry, set statuses, append to done
+  pa status show [--json]     Print the daily status board (never hand-edit its JSON)
   pa workspace <verb>         Workspace server lifecycle (start | stop | status | open)
   pa project <verb>           Project state writes (create | status | doc add/rm | list)
   pa work <verb>              Work-item state writes (create | status | list)
@@ -102,6 +106,10 @@ export async function main(argv) {
     case 'session':
       return await doSession(rest);
     case 'status':
+      // Bare `pa status` (and any argv that is not a board subverb) stays
+      // the environment probe; set | patch | show write and read the daily
+      // status board.
+      if (STATUS_BOARD_SUBVERBS.includes(rest[0])) return await runStatusBoard(rest);
       return await doStatus();
     case 'workspace':
       return await doWorkspace(rest);

package/dist/engineering-pa-cli/src/pa/status-board-cli.mjs

@@ -0,0 +1,425 @@
+// status-board-cli.mjs - argv router for `pa status set | patch | show`.
+//
+// Bare `pa status` (no subverb) stays the environment probe in cli.mjs;
+// only the three subverbs below route here. Every write goes through
+// `writeBoardAtomic` in status-board.mjs: validated first, then a temp
+// file renamed over the board, so a refused or half-written board never
+// lands. The PA keeps the board current through these verbs and never
+// hand-edits the JSON.
+
+import { getRepoRoot } from './repo-root.mjs';
+import {
+  BoardError,
+  STATUS_VALUES,
+  boardPath,
+  boardRelPath,
+  isValidAgentName,
+  parseBoard,
+  readBoard,
+  resolveAgentName,
+  writeBoardAtomic,
+} from './status-board.mjs';
+
+export const SUBVERBS = ['set', 'patch', 'show'];
+
+const USAGE = `pa status - environment probe, plus the daily status board subverbs
+
+Usage:
+  pa status <set|patch|show> --help   Show this help
+  pa status                       Probe operator content, installed package and workspace (unchanged)
+  pa status set   [--file <path>] [--agent <name>]
+                                  Replace the whole board from a JSON file, or stdin when --file is absent or "-"
+  pa status patch [--agent <name>] [--headline "..."]
+                  [--id <id> | --match "<title or question>"] [--on-me]
+                  [--title "..."] [--status <status>] [--where "..."] [--stage "..."] [--note "..."]
+                  [--ids a,b] [--link <url>] [--group "<label>"]
+                  [--question "..."] [--options "a|b"] [--workstream "..."] [--remove]
+                  [--add-done "<title>"]
+                                  Merge one item or one on-me entry, set statuses, append to done
+  pa status show  [--agent <name>] [--json]
+                                  Print the board
+
+Notes:
+  - The board is agents/<agent>/workspace/status-board.json. The agent comes
+    from --agent, else preferences.json paName, else the single agents/*
+    folder holding next-session.md, else "dave".
+  - Every write stamps the board's updatedAt from the clock, is validated
+    against the schema and lands atomically (temp file, then rename).
+  - Status values: ${STATUS_VALUES.join(' | ')}. The legacy key and status
+    "onBaz" are read as "onMe" and written as "onMe".
+  - patch --id matches items (or with --on-me, on-me entries) whose ids hold
+    the id; --match matches the exact title (or question). More than one
+    match is refused. No match creates the entry (an item needs --group).
+  - --status done also appends the item to the done list.
+
+Exit codes:
+  0 ok | 1 usage error or schema refusal | 2 operational failure | 3 IO failure
+`;
+
+class UsageError extends Error {
+  constructor(msg) { super(msg); this.exitCode = 1; }
+}
+class OpError extends Error {
+  constructor(msg) { super(msg); this.exitCode = 2; }
+}
+
+const FLAGS = {
+  set: ['file', 'agent'],
+  show: ['agent', 'json'],
+  patch: [
+    'agent', 'headline', 'id', 'match', 'on-me', 'title', 'status', 'where', 'stage', 'note',
+    'ids', 'link', 'group', 'question', 'options', 'workstream', 'remove', 'add-done',
+  ],
+};
+const BOOLEAN_FLAGS = new Set(['json', 'on-me', 'remove']);
+
+/**
+ * @param {string[]} argv  subverb and its flags (argv after `status`)
+ * @param {object} [opts]  test seams: repoRoot, now, stdin (string), stdout, stderr
+ */
+export async function run(argv, opts = {}) {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const verb = argv[0];
+  if (argv.includes('-h') || argv.includes('--help')) { out.write(USAGE); return 0; }
+  try {
+    if (!SUBVERBS.includes(verb)) throw new UsageError('unknown subverb: ' + verb);
+    const flags = parseFlags(argv.slice(1), FLAGS[verb]);
+    const repoRoot = opts.repoRoot ?? await getRepoRoot();
+    const agent = pickAgent(flags.agent, repoRoot);
+    const file = boardPath(repoRoot, agent);
+    const ctx = { repoRoot, agent, file, flags, out, err, now: opts.now ?? (() => new Date()), stdin: opts.stdin };
+    if (verb === 'set') return await doSet(ctx);
+    if (verb === 'patch') return await doPatch(ctx);
+    return await doShow(ctx);
+  } catch (e) {
+    if (e instanceof BoardError) {
+      err.write('[pa status] refused, nothing written:\n' + e.problems.map((p) => '  - ' + p + '\n').join(''));
+      return 1;
+    }
+    err.write('[pa status] ' + (e.message || e) + '\n');
+    if (e.exitCode === 1) err.write('Run `pa status set --help` for usage.\n');
+    if (e.exitCode) return e.exitCode;
+    return e.code ? 3 : 2;
+  }
+}
+
+function parseFlags(args, allowed) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith('--')) throw new UsageError('unexpected argument: ' + a);
+    const eq = a.indexOf('=');
+    const key = eq === -1 ? a.slice(2) : a.slice(2, eq);
+    if (!allowed.includes(key)) throw new UsageError('unknown flag: --' + key);
+    if (BOOLEAN_FLAGS.has(key)) {
+      if (eq !== -1) throw new UsageError('--' + key + ' takes no value');
+      flags[key] = true;
+      continue;
+    }
+    if (eq !== -1) { flags[key] = a.slice(eq + 1); continue; }
+    const v = args[i + 1];
+    if (v === undefined) throw new UsageError('--' + key + ' needs a value');
+    flags[key] = v;
+    i += 1;
+  }
+  return flags;
+}
+
+function pickAgent(flag, repoRoot) {
+  if (flag === undefined) return resolveAgentName(repoRoot);
+  if (!isValidAgentName(flag)) throw new UsageError('--agent must be a lowercase agent folder name, got "' + flag + '"');
+  return flag;
+}
+
+function stamp(now) {
+  return now().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+async function readStdin(given) {
+  if (typeof given === 'string') return given;
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// -- set ----------------------------------------------------------------
+
+async function doSet(ctx) {
+  const { flags } = ctx;
+  let text;
+  if (flags.file === undefined || flags.file === '-') {
+    text = await readStdin(ctx.stdin);
+  } else {
+    const { readFile } = await import('node:fs/promises');
+    text = await readFile(flags.file, 'utf8');
+  }
+  let board;
+  try {
+    board = JSON.parse(text);
+  } catch (e) {
+    throw new UsageError('input is not valid JSON: ' + e.message);
+  }
+  if (board === null || typeof board !== 'object' || Array.isArray(board)) {
+    throw new BoardError(['board must be a JSON object']);
+  }
+  board.updatedAt = stamp(ctx.now);
+  const written = await writeBoardAtomic(ctx.file, withDefaults(board));
+  ctx.out.write('Board set for ' + ctx.agent + ' at ' + boardRelPath(ctx.agent) + ' (' + counts(written) + ').\n');
+  return 0;
+}
+
+// Fill the optional arrays so the file on disk always carries every list.
+// `updatedAt` stays first so the file reads top-down like the page.
+function withDefaults(board) {
+  const { updatedAt, ...rest } = board;
+  const out = { updatedAt, ...rest };
+  for (const k of ['onMe', 'groups', 'done']) {
+    if (out[k] === undefined && !(k === 'onMe' && 'onBaz' in out)) out[k] = [];
+  }
+  return out;
+}
+
+// -- show ---------------------------------------------------------------
+
+async function doShow(ctx) {
+  const parsed = await loadExisting(ctx, { strictStatus: false });
+  if (parsed.problems.length) {
+    throw new OpError('board at ' + boardRelPath(ctx.agent) + ' does not match the schema:\n  - ' + parsed.problems.join('\n  - '));
+  }
+  if (ctx.flags.json) {
+    ctx.out.write(JSON.stringify(parsed.board, null, 2) + '\n');
+    return 0;
+  }
+  const b = parsed.board;
+  const lines = [];
+  lines.push('Status board for ' + ctx.agent + ' (' + boardRelPath(ctx.agent) + ')');
+  lines.push('Updated ' + b.updatedAt);
+  lines.push('Headline: ' + b.headline);
+  const onMe = b.onMe || [];
+  lines.push('');
+  lines.push('On me (' + onMe.length + ')');
+  if (!onMe.length) lines.push('  nothing');
+  for (const a of onMe) lines.push('  - ' + a.question + idsSuffix(a.ids));
+  for (const g of b.groups || []) {
+    lines.push('');
+    lines.push(g.label || 'Untitled workstream');
+    if (!g.items.length) lines.push('  nothing in flight');
+    for (const it of g.items) {
+      lines.push('  [' + (it.status || 'queued') + '] ' + it.title + idsSuffix(it.ids) + (it.where ? '  @' + it.where : ''));
+    }
+  }
+  lines.push('');
+  lines.push('Done today (' + (b.done || []).length + ')');
+  for (const it of b.done || []) lines.push('  - ' + it.title + (it.workstream ? '  (' + it.workstream + ')' : ''));
+  ctx.out.write(lines.join('\n') + '\n');
+  return 0;
+}
+
+function idsSuffix(ids) {
+  return Array.isArray(ids) && ids.length ? ' (' + ids.join(', ') + ')' : '';
+}
+
+function counts(b) {
+  const items = (b.groups || []).reduce((n, g) => n + g.items.length, 0);
+  return (b.groups || []).length + ' groups, ' + items + ' items, ' + (b.onMe || []).length + ' on me, ' + (b.done || []).length + ' done';
+}
+
+async function loadExisting(ctx, opts) {
+  let parsed;
+  try {
+    parsed = await readBoard(ctx.file, opts);
+  } catch (e) {
+    if (e instanceof SyntaxError) throw new OpError('board at ' + boardRelPath(ctx.agent) + ' is not valid JSON: ' + e.message);
+    throw e;
+  }
+  if (!parsed) throw new OpError('no status board for ' + ctx.agent + ' yet at ' + boardRelPath(ctx.agent) + '; start one with `pa status set`');
+  return parsed;
+}
+
+// -- patch --------------------------------------------------------------
+
+const ITEM_FIELDS = ['title', 'status', 'where', 'stage', 'note', 'link'];
+const ASK_FIELDS = ['question', 'workstream', 'link'];
+
+async function doPatch(ctx) {
+  const f = ctx.flags;
+  const hasTarget = f.id !== undefined || f.match !== undefined;
+  if (f.id !== undefined && f.match !== undefined) throw new UsageError('give --id or --match, not both');
+  if (!hasTarget) {
+    const stray = Object.keys(f).filter((k) => !['agent', 'headline', 'add-done', 'workstream', 'ids'].includes(k));
+    if (stray.length) throw new UsageError('--' + stray[0] + ' needs a target (--id or --match)');
+    if (f.headline === undefined && f['add-done'] === undefined) {
+      throw new UsageError('patch needs --headline, --add-done, or a target (--id or --match)');
+    }
+  }
+  if (f.status !== undefined && !STATUS_VALUES.includes(normaliseStatusValue(f.status))) {
+    throw new UsageError('--status must be one of ' + STATUS_VALUES.join(', '));
+  }
+  if (f['on-me']) {
+    const bad = ['title', 'status', 'where', 'stage', 'note', 'group'].find((k) => f[k] !== undefined);
+    if (bad) throw new UsageError('--' + bad + ' applies to items, not --on-me entries');
+  } else {
+    const bad = ['question', 'options'].find((k) => f[k] !== undefined);
+    if (bad) throw new UsageError('--' + bad + ' applies to --on-me entries');
+  }
+
+  const parsed = await loadExisting(ctx, { strictStatus: true });
+  if (parsed.problems.length) throw new OpError('board on disk is invalid; fix it with `pa status set`:\n  - ' + parsed.problems.join('\n  - '));
+  const board = structuredClone(parsed.board);
+  board.onMe = board.onMe || [];
+  board.groups = board.groups || [];
+  board.done = board.done || [];
+  const now = stamp(ctx.now);
+  const notes = [];
+
+  if (f.headline !== undefined) { board.headline = f.headline; notes.push('headline set'); }
+  if (hasTarget) notes.push(f['on-me'] ? patchAsk(board, f, now) : patchItem(board, f, now));
+  if (f['add-done'] !== undefined) {
+    board.done.push(doneEntry({ title: f['add-done'], ids: splitList(f.ids, ',') || [] }, f.workstream, now));
+    notes.push('done entry added');
+  }
+
+  board.updatedAt = now;
+  await writeBoardAtomic(ctx.file, board);
+  ctx.out.write('Board patched for ' + ctx.agent + ': ' + notes.join('; ') + '.\n');
+  return 0;
+}
+
+function normaliseStatusValue(s) {
+  return s === 'onBaz' ? 'onMe' : s;
+}
+
+function splitList(v, sep) {
+  if (v === undefined) return undefined;
+  return v.split(sep).map((s) => s.trim()).filter(Boolean);
+}
+
+function refusal(matches, describe) {
+  return new UsageError('more than one entry matches, refusing to pick one:\n' + matches.map((m) => '  - ' + describe(m)).join('\n'));
+}
+
+function patchItem(board, f, now) {
+  const hits = [];
+  board.groups.forEach((g, gi) => g.items.forEach((it, ii) => {
+    const ok = f.id !== undefined
+      ? Array.isArray(it.ids) && it.ids.includes(f.id)
+      : String(it.title).trim() === f.match.trim();
+    if (ok) hits.push({ gi, ii });
+  }));
+  if (hits.length > 1) {
+    throw refusal(hits, (h) => '"' + board.groups[h.gi].items[h.ii].title + '" in ' + (board.groups[h.gi].label || 'group ' + (h.gi + 1)));
+  }
+
+  if (!hits.length) {
+    if (f.remove) throw new OpError('no item matches; nothing to remove');
+    if (f.group === undefined) throw new UsageError('no item matches; to add one, give --group');
+    const title = f.title ?? f.match;
+    if (title === undefined) throw new UsageError('no item matches --id ' + f.id + '; to add one, give --title and --group');
+    const ids = mergeIds(splitList(f.ids, ',') || [], f.id);
+    const item = {
+      title,
+      status: normaliseStatusValue(f.status ?? 'queued'),
+      where: f.where ?? '',
+      stage: f.stage ?? '',
+      note: f.note ?? '',
+      ids,
+      updatedAt: now,
+    };
+    if (f.link !== undefined) item.link = f.link;
+    const g = groupFor(board, f.group);
+    g.items.push(item);
+    if (item.status === 'done') addDoneOnce(board, item, g.label, now);
+    return 'item "' + title + '" added to ' + g.label;
+  }
+
+  const { gi, ii } = hits[0];
+  const fromGroup = board.groups[gi];
+  if (f.remove) {
+    const [gone] = fromGroup.items.splice(ii, 1);
+    return 'item "' + gone.title + '" removed';
+  }
+  const item = fromGroup.items[ii];
+  for (const k of ITEM_FIELDS) {
+    if (f[k] !== undefined) item[k] = k === 'status' ? normaliseStatusValue(f[k]) : f[k];
+  }
+  if (f.ids !== undefined) item.ids = splitList(f.ids, ',');
+  item.updatedAt = now;
+  let label = fromGroup.label;
+  if (f.group !== undefined && f.group !== fromGroup.label) {
+    fromGroup.items.splice(ii, 1);
+    const to = groupFor(board, f.group);
+    to.items.push(item);
+    label = to.label;
+  }
+  if (f.status !== undefined && item.status === 'done') addDoneOnce(board, item, label, now);
+  return 'item "' + item.title + '" updated';
+}
+
+function patchAsk(board, f, now) {
+  const hits = [];
+  board.onMe.forEach((a, i) => {
+    const ok = f.id !== undefined
+      ? Array.isArray(a.ids) && a.ids.includes(f.id)
+      : String(a.question).trim() === f.match.trim();
+    if (ok) hits.push(i);
+  });
+  if (hits.length > 1) throw refusal(hits, (i) => '"' + board.onMe[i].question + '"');
+
+  if (!hits.length) {
+    if (f.remove) throw new OpError('no on-me entry matches; nothing to remove');
+    const question = f.question ?? f.match;
+    if (question === undefined) throw new UsageError('no on-me entry matches --id ' + f.id + '; to add one, give --question');
+    const ask = { since: now };
+    if (f.workstream !== undefined) ask.workstream = f.workstream;
+    ask.question = question;
+    ask.options = splitList(f.options, '|') || [];
+    ask.ids = mergeIds(splitList(f.ids, ',') || [], f.id);
+    if (f.link !== undefined) ask.link = f.link;
+    board.onMe.push(ask);
+    return 'on-me entry added';
+  }
+
+  const i = hits[0];
+  if (f.remove) {
+    board.onMe.splice(i, 1);
+    return 'on-me entry removed';
+  }
+  const ask = board.onMe[i];
+  for (const k of ASK_FIELDS) if (f[k] !== undefined) ask[k] = f[k];
+  if (f.options !== undefined) ask.options = splitList(f.options, '|');
+  if (f.ids !== undefined) ask.ids = splitList(f.ids, ',');
+  return 'on-me entry updated';
+}
+
+function mergeIds(ids, id) {
+  if (id !== undefined && !ids.includes(id)) ids.push(id);
+  return ids;
+}
+
+function groupFor(board, label) {
+  let g = board.groups.find((x) => x.label === label);
+  if (!g) {
+    // New groups land last: group order is priority order, and the PA
+    // reorders with `pa status set` when priorities change.
+    g = { label, items: [] };
+    board.groups.push(g);
+  }
+  return g;
+}
+
+function doneEntry(item, workstream, now) {
+  const e = { title: item.title, status: 'done' };
+  if (workstream) e.workstream = workstream;
+  e.where = item.where ?? '';
+  e.stage = item.stage ?? '';
+  e.note = item.note ?? '';
+  e.ids = item.ids ? [...item.ids] : [];
+  e.updatedAt = now;
+  return e;
+}
+
+function addDoneOnce(board, item, workstream, now) {
+  if (board.done.some((d) => d.title === item.title)) return;
+  board.done.push(doneEntry(item, workstream, now));
+}