@stravica-ai/digital-operator-pa 0.1.0

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

@@ -0,0 +1,164 @@
+// work-cli.mjs — argv router for `pa work <verb>`.
+//
+// Verbs:
+//   pa work create [--project <id>] --title "..." --category <c> [--priority N] [--summary "..."] [--owner ...] [--assignee ...]
+//   pa work status <id> <status>
+//   pa work list   [--project <id>] [--status ...] [--mine] [--theirs] [--all] [--json]
+//
+// PA name (for --mine resolution) is read from
+// operator/config/preferences.json. Falls back to 'pa' if missing.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { createWork, setWorkStatus, listWork } from './work.mjs';
+import { getRepoRoot } from './repo-root.mjs';
+
+const USAGE = `pa work — manage operator-repo work items
+
+Usage:
+  pa work create [--project <id>] --title "..." --category <feature|bug|chore|discussion|research>
+                 [--priority 0|1|2|3] [--summary "..."] [--owner ...] [--assignee ...]
+  pa work status <id> <draft|planned|in-progress|blocked|done|archived>
+  pa work list   [--project <id>] [--status ...] [--category ...] [--mine] [--theirs] [--all] [--json]
+  pa work -h, --help
+
+Notes:
+  - status=done stamps \`completedAt\` to today (only if not already set).
+  - --mine resolves the PA name from operator/config/preferences.json
+    (paName / agentName). Default: "pa".
+
+Exit codes:
+  0 ok | 1 usage/not-found | 2 operational failure
+`;
+
+export async function run(argv) {
+  if (!argv.length || argv[0] === '-h' || argv[0] === '--help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const verb = argv[0];
+  const rest = argv.slice(1);
+
+  try {
+    switch (verb) {
+      case 'create':  return await doCreate(rest);
+      case 'status':  return await doStatus(rest);
+      case 'list':    return await doList(rest);
+      default:
+        process.stderr.write(`[pa work] unknown verb: ${verb}\n`);
+        process.stderr.write(USAGE);
+        return 1;
+    }
+  } catch (err) {
+    process.stderr.write(`[pa work] ${err.message || err}\n`);
+    return err.exitCode || 2;
+  }
+}
+
+function parseFlags(args) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const peek = args[i + 1];
+      if (peek == null || peek.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = peek;
+        i += 1;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+async function getPaName() {
+  try {
+    const repoRoot = await getRepoRoot();
+    const raw = await readFile(
+      join(repoRoot, 'operator', 'config', 'preferences.json'),
+      'utf8',
+    );
+    const config = JSON.parse(raw);
+    return config.paName || config.agentName || 'pa';
+  } catch {
+    return 'pa';
+  }
+}
+
+async function doCreate(args) {
+  const { flags } = parseFlags(args);
+  const priority = flags.priority != null && flags.priority !== true
+    ? Number(flags.priority)
+    : null;
+  const res = await createWork({
+    projectId: typeof flags.project === 'string' ? flags.project : null,
+    title: typeof flags.title === 'string' ? flags.title : null,
+    category: typeof flags.category === 'string' ? flags.category : null,
+    priority,
+    summary: typeof flags.summary === 'string' ? flags.summary : null,
+    owner: typeof flags.owner === 'string' ? flags.owner : null,
+    assignee: typeof flags.assignee === 'string' ? flags.assignee : null,
+  });
+  process.stdout.write(`created ${res.id}\n`);
+  process.stdout.write(`  ${res.path}\n`);
+  return 0;
+}
+
+async function doStatus(args) {
+  if (args.length < 2) {
+    process.stderr.write('usage: pa work status <id> <status>\n');
+    return 1;
+  }
+  const [id, status] = args;
+  const res = await setWorkStatus(id, status);
+  process.stdout.write(`work ${res.id} → ${res.status}\n`);
+  if (res.completedAt && status === 'done') {
+    process.stdout.write(`  completedAt: ${res.completedAt}\n`);
+  }
+  return 0;
+}
+
+async function doList(args) {
+  const { flags } = parseFlags(args);
+  const paName = (flags.mine || flags.theirs) ? await getPaName() : null;
+  const items = await listWork({
+    all: flags.all === true,
+    status: typeof flags.status === 'string' ? flags.status : null,
+    category: typeof flags.category === 'string' ? flags.category : null,
+    project: typeof flags.project === 'string' ? flags.project : null,
+    owner: typeof flags.owner === 'string' ? flags.owner : null,
+    assignee: typeof flags.assignee === 'string' ? flags.assignee : null,
+    mine: flags.mine === true,
+    theirs: flags.theirs === true,
+    paName,
+  });
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(items, null, 2) + '\n');
+    return 0;
+  }
+  if (!items.length) {
+    process.stdout.write('no work items match\n');
+    return 0;
+  }
+  const rows = items.map((w) => ({
+    id: w.id,
+    status: w.status || 'draft',
+    priority: w.priority == null ? '-' : `P${w.priority}`,
+    project: w.projectId || '-',
+    title: (w.title || '').slice(0, 60),
+  }));
+  const cols = ['id', 'status', 'priority', 'project', 'title'];
+  const widths = {};
+  for (const c of cols) widths[c] = Math.max(c.length, ...rows.map((r) => String(r[c]).length));
+  const pad = (s, w) => String(s).padEnd(w, ' ');
+  process.stdout.write(cols.map((c) => pad(c, widths[c])).join('  ') + '\n');
+  process.stdout.write(cols.map((c) => '-'.repeat(widths[c])).join('  ') + '\n');
+  for (const r of rows) process.stdout.write(cols.map((c) => pad(r[c], widths[c])).join('  ') + '\n');
+  return 0;
+}

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

@@ -0,0 +1,196 @@
+// work.mjs — write-side commands for `pa work <verb>`.
+//
+// Source of truth is work/w-YYYY-MM-DD-NNN.json. We never cache.
+//
+// What lives here:
+//   - create: scaffold a new work item with the next-free NNN for today
+//   - status: change status (stamps `completedAt` on done)
+//   - list:   list work items, optionally filtered
+//
+// ID format and status/category enums match
+// packages/core/schema/work-item.json.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getRepoRoot } from './repo-root.mjs';
+import { readJson, writeJson, ensureDir, listJsonFiles, today } from './io.mjs';
+
+const STATUSES = new Set(['draft', 'planned', 'in-progress', 'blocked', 'done', 'archived']);
+
+const CATEGORIES = new Set(['feature', 'bug', 'chore', 'discussion', 'research']);
+
+const ID_RE = /^w-(\d{4}-\d{2}-\d{2})-(\d{3})$/;
+
+function validateStatus(status) {
+  if (!STATUSES.has(status)) {
+    const err = new Error(
+      `invalid status: ${status} (expected one of: ${[...STATUSES].join(', ')})`,
+    );
+    err.exitCode = 1;
+    throw err;
+  }
+}
+
+function validateCategory(category) {
+  if (!category) return;
+  if (!CATEGORIES.has(category)) {
+    const err = new Error(
+      `invalid category: ${category} (expected one of: ${[...CATEGORIES].join(', ')})`,
+    );
+    err.exitCode = 1;
+    throw err;
+  }
+}
+
+function validatePriority(priority) {
+  if (priority == null) return;
+  if (!Number.isInteger(priority) || priority < 0 || priority > 3) {
+    const err = new Error(`invalid priority: ${priority} (expected integer 0–3)`);
+    err.exitCode = 1;
+    throw err;
+  }
+}
+
+/**
+ * Scan work/*.json for the highest NNN with today's date. Returns the
+ * next free NNN, zero-padded to 3 digits. Result is always "001"–"999".
+ *
+ * If 999 is already taken, throws — callers should treat as an
+ * operational failure and report. In practice this is unreachable.
+ */
+async function nextWorkNumber(repoRoot, dateStr) {
+  const dir = join(repoRoot, 'work');
+  const files = await listJsonFiles(dir);
+  let max = 0;
+  const prefix = `w-${dateStr}-`;
+  for (const file of files) {
+    if (!file.startsWith(prefix)) continue;
+    const m = file.match(/^w-\d{4}-\d{2}-\d{2}-(\d{3})\.json$/);
+    if (!m) continue;
+    const n = parseInt(m[1], 10);
+    if (Number.isFinite(n) && n > max) max = n;
+  }
+  const next = max + 1;
+  if (next > 999) {
+    const err = new Error(`no free work-item slot for ${dateStr} (NNN exhausted)`);
+    err.exitCode = 2;
+    throw err;
+  }
+  return String(next).padStart(3, '0');
+}
+
+/**
+ * Create a new work item. Returns { id, path }.
+ *
+ * Status defaults to "draft" per the brief. Date and NNN are
+ * auto-derived from today; we do not accept overrides.
+ */
+export async function createWork(opts) {
+  if (!opts.title) {
+    const err = new Error('--title is required');
+    err.exitCode = 1;
+    throw err;
+  }
+  validateCategory(opts.category);
+  validatePriority(opts.priority);
+
+  const repoRoot = await getRepoRoot();
+  const workDir = join(repoRoot, 'work');
+  await ensureDir(workDir);
+
+  const dateStr = today();
+  const nnn = await nextWorkNumber(repoRoot, dateStr);
+  const id = `w-${dateStr}-${nnn}`;
+  const path = join(workDir, `${id}.json`);
+
+  const item = {
+    id,
+    projectId: opts.projectId || null,
+    title: opts.title,
+    category: opts.category || 'chore',
+    status: 'draft',
+    priority: opts.priority == null ? 2 : opts.priority,
+    owner: opts.owner || 'system-architect',
+    assignee: opts.assignee || opts.owner || 'system-architect',
+    created: dateStr,
+    updated: dateStr,
+    completedAt: null,
+    summary: opts.summary || '',
+    blocked: null,
+    links: [],
+  };
+  await writeJson(path, item);
+  return { id, path };
+}
+
+/**
+ * Set work-item status. Stamps `completedAt` to today's date when
+ * status=done (only if not already set). Always bumps `updated`.
+ */
+export async function setWorkStatus(id, status) {
+  if (!ID_RE.test(id)) {
+    const err = new Error(`invalid work id: ${id} (expected w-YYYY-MM-DD-NNN)`);
+    err.exitCode = 1;
+    throw err;
+  }
+  validateStatus(status);
+
+  const repoRoot = await getRepoRoot();
+  const path = join(repoRoot, 'work', `${id}.json`);
+  if (!existsSync(path)) {
+    const err = new Error(`work item not found: ${id}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  const item = await readJson(path);
+  item.status = status;
+  item.updated = today();
+  if (status === 'done' && !item.completedAt) {
+    item.completedAt = today();
+  }
+  await writeJson(path, item);
+  return { id, status, completedAt: item.completedAt, path };
+}
+
+/**
+ * List work items. Filters: status, category, project, owner, assignee,
+ * mine, theirs, all, paName (used for --mine resolution).
+ * By default excludes done + archived (mirrors desk-list semantics).
+ */
+export async function listWork(filters = {}) {
+  const repoRoot = await getRepoRoot();
+  const dir = join(repoRoot, 'work');
+  const files = await listJsonFiles(dir);
+  const items = [];
+  for (const f of files) {
+    try {
+      items.push(await readJson(join(dir, f)));
+    } catch {
+      // Skip unparseable.
+    }
+  }
+  let filtered = items;
+  if (!filters.all) {
+    filtered = filtered.filter((w) => !['done', 'archived'].includes(w.status));
+  }
+  if (filters.status) filtered = filtered.filter((w) => w.status === filters.status);
+  if (filters.category) filtered = filtered.filter((w) => w.category === filters.category);
+  if (filters.project) filtered = filtered.filter((w) => w.projectId === filters.project);
+  if (filters.owner) filtered = filtered.filter((w) => w.owner === filters.owner);
+  if (filters.assignee) filtered = filtered.filter((w) => w.assignee === filters.assignee);
+  if (filters.mine && filters.paName) filtered = filtered.filter((w) => w.assignee === filters.paName);
+  if (filters.theirs) filtered = filtered.filter((w) => w.assignee === 'operator');
+
+  const STATE_ORDER = ['in-progress', 'blocked', 'planned', 'draft', 'done', 'archived'];
+  filtered.sort((a, b) => {
+    const sa = STATE_ORDER.indexOf(a.status || 'draft');
+    const sb = STATE_ORDER.indexOf(b.status || 'draft');
+    if (sa !== sb) return sa - sb;
+    const pa = a.priority == null ? 99 : a.priority;
+    const pb = b.priority == null ? 99 : b.priority;
+    if (pa !== pb) return pa - pb;
+    return (a.id || '').localeCompare(b.id || '');
+  });
+  return filtered;
+}

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

@@ -0,0 +1,201 @@
+// workstreams.mjs — write-side commands for `pa project workstream <verb>`.
+//
+// A workstream is a named unit of work within a project. Each workstream
+// has its own status, blockedOn signal, next-action text for operator and
+// Dave, and owns a set of documents.
+//
+// Workstream schema:
+//   {
+//     "id":           "content-pipeline",     // kebab-case
+//     "name":         "Content pipeline",
+//     "status":       "in-progress",          // same vocab as project status
+//     "blockedOn":    "operator",             // optional: "operator" | "dave" | free text
+//     "nextOperator": "Review week 1 drafts", // optional
+//     "nextDave":     "Publish after approval",// optional
+//     "docs":         [{ "label": "...", "path": "...", "status": "review" }]
+//   }
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getRepoRoot } from './repo-root.mjs';
+import { readJson, writeJson, today } from './io.mjs';
+import { VALID_DOC_STATUSES } from './doc-groups.mjs';
+
+const STATUSES = new Set(['draft', 'planned', 'in-progress', 'blocked', 'done', 'archived']);
+
+function fail(msg, code = 1) {
+  const err = new Error(msg);
+  err.exitCode = code;
+  throw err;
+}
+
+function validateWsId(id) {
+  if (!id || typeof id !== 'string') fail('workstream --id is required');
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+    fail(`invalid workstream id: ${id} (lowercase letters, digits, and '-' only; must start with a letter or digit)`);
+  }
+}
+
+function validateStatus(status) {
+  if (!STATUSES.has(status)) {
+    fail(`invalid status: ${status} (expected one of: ${[...STATUSES].join(', ')})`);
+  }
+}
+
+async function loadProject(projectId) {
+  const repoRoot = await getRepoRoot();
+  const path = join(repoRoot, 'projects', projectId, 'project.json');
+  if (!existsSync(path)) fail(`project not found: ${projectId}`);
+  const manifest = await readJson(path);
+  return { manifest, path };
+}
+
+async function saveProject(path, manifest) {
+  manifest.updated = today();
+  await writeJson(path, manifest);
+}
+
+function ensureWorkstreams(manifest) {
+  if (!Array.isArray(manifest.workstreams)) {
+    manifest.workstreams = [];
+  }
+  return manifest.workstreams;
+}
+
+function findWorkstream(workstreams, wsId) {
+  return workstreams.find((ws) => ws.id === wsId);
+}
+
+/**
+ * Add a new workstream to a project.
+ */
+export async function addWorkstream(projectId, { id: wsId, name, status, blockedOn }) {
+  validateWsId(wsId);
+  if (!name) fail('--name is required');
+  if (status) validateStatus(status);
+
+  const { manifest, path } = await loadProject(projectId);
+  const workstreams = ensureWorkstreams(manifest);
+
+  if (findWorkstream(workstreams, wsId)) {
+    fail(`workstream already exists: ${wsId} in project ${projectId}`);
+  }
+
+  const ws = {
+    id: wsId,
+    name,
+    status: status || 'draft',
+    docs: [],
+  };
+  if (blockedOn) ws.blockedOn = blockedOn;
+
+  workstreams.push(ws);
+  await saveProject(path, manifest);
+
+  return { projectId, workstream: ws, path };
+}
+
+/**
+ * Update a workstream's status and optionally blockedOn.
+ */
+export async function setWorkstreamStatus(projectId, { id: wsId, status, blockedOn }) {
+  validateWsId(wsId);
+  validateStatus(status);
+
+  const { manifest, path } = await loadProject(projectId);
+  const workstreams = ensureWorkstreams(manifest);
+  const ws = findWorkstream(workstreams, wsId);
+  if (!ws) fail(`workstream not found: ${wsId} in project ${projectId}`);
+
+  ws.status = status;
+  if (blockedOn !== undefined) {
+    if (blockedOn) {
+      ws.blockedOn = blockedOn;
+    } else {
+      delete ws.blockedOn;
+    }
+  }
+
+  await saveProject(path, manifest);
+  return { projectId, workstream: ws, path };
+}
+
+/**
+ * Set the next-action text for operator and/or Dave on a workstream.
+ */
+export async function setWorkstreamNext(projectId, { id: wsId, operator: nextOp, dave: nextDave }) {
+  validateWsId(wsId);
+
+  const { manifest, path } = await loadProject(projectId);
+  const workstreams = ensureWorkstreams(manifest);
+  const ws = findWorkstream(workstreams, wsId);
+  if (!ws) fail(`workstream not found: ${wsId} in project ${projectId}`);
+
+  if (nextOp !== undefined) {
+    if (nextOp) {
+      ws.nextOperator = nextOp;
+    } else {
+      delete ws.nextOperator;
+    }
+  }
+  if (nextDave !== undefined) {
+    if (nextDave) {
+      ws.nextDave = nextDave;
+    } else {
+      delete ws.nextDave;
+    }
+  }
+
+  await saveProject(path, manifest);
+  return { projectId, workstream: ws, path };
+}
+
+/**
+ * Remove a workstream from a project.
+ */
+export async function removeWorkstream(projectId, { id: wsId }) {
+  validateWsId(wsId);
+
+  const { manifest, path } = await loadProject(projectId);
+  const workstreams = ensureWorkstreams(manifest);
+  const idx = workstreams.findIndex((ws) => ws.id === wsId);
+  if (idx === -1) fail(`workstream not found: ${wsId} in project ${projectId}`);
+
+  workstreams.splice(idx, 1);
+  await saveProject(path, manifest);
+
+  return { projectId, removed: wsId, path };
+}
+
+/**
+ * Add a doc entry to a specific workstream's docs array.
+ * Idempotent on {label, path} match within the workstream.
+ */
+export async function addDocToWorkstream(projectId, wsId, { label, path: docPath, status }) {
+  validateWsId(wsId);
+  if (!label) fail('--label is required');
+  if (!docPath) fail('--path is required');
+  if (status && !VALID_DOC_STATUSES.has(status)) {
+    fail(`invalid doc status: ${status} (expected one of: ${[...VALID_DOC_STATUSES].join(', ')})`);
+  }
+
+  const { manifest, path } = await loadProject(projectId);
+  const workstreams = ensureWorkstreams(manifest);
+  const ws = findWorkstream(workstreams, wsId);
+  if (!ws) fail(`workstream not found: ${wsId} in project ${projectId}`);
+
+  if (!Array.isArray(ws.docs)) ws.docs = [];
+
+  const dup = ws.docs.find((d) => d.path === docPath && d.label === label);
+  if (dup) {
+    return { projectId, workstream: wsId, label, path: docPath, status: status || null, changed: false, manifestPath: path };
+  }
+
+  const entry = { label, path: docPath };
+  if (status) entry.status = status;
+  ws.docs.push(entry);
+
+  await saveProject(path, manifest);
+  return { projectId, workstream: wsId, label, path: docPath, status: status || null, changed: true, manifestPath: path };
+}