@stravica-ai/digital-operator-pa 0.1.0

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

@@ -0,0 +1,385 @@
+// project-cli.mjs — argv router for `pa project <verb>`.
+//
+// Verbs:
+//   pa project create <id> --name "..." --category <c> [--priority N] [--owner ...] [--assignee ...] [--summary "..."]
+//   pa project status <id> <status>
+//   pa project doc add <id> --label "..." --path "..." [--group "..."] [--workstream <wsId>]
+//   pa project doc rm  <id> --path "..."
+//   pa project workstream add <id> --id <wsId> --name "..." [--status ...] [--blockedOn ...]
+//   pa project workstream status <id> --id <wsId> --status <status> [--blockedOn <who>]
+//   pa project workstream next <id> --id <wsId> [--operator "..."] [--dave "..."]
+//   pa project workstream rm <id> --id <wsId>
+//   pa project list [--status ...] [--category ...] [--all] [--json]
+//                   [--all-teams] [--team <identity>]
+//
+// Each verb returns an exit code per the tooling-standard §6:
+//   0 ok | 1 usage/not-found | 2 operational
+
+import {
+  createProject, setProjectStatus, addProjectDoc, removeProjectDoc,
+  setProjectDocStatus, listProjects,
+} from './projects.mjs';
+import {
+  addWorkstream, setWorkstreamStatus, setWorkstreamNext,
+  removeWorkstream, addDocToWorkstream,
+} from './workstreams.mjs';
+
+const USAGE = `pa project -- manage operator-repo project state
+
+Usage:
+  pa project create <id> --name "..." --category <feature|bug|chore|product|growth|discussion|research>
+                         [--priority 0|1|2|3] [--owner ...] [--assignee ...] [--summary "..."]
+  pa project status <id> <draft|planned|in-progress|blocked|done|archived>
+  pa project doc add <id> --label "..." --path "..." [--group "..."] [--workstream <wsId>] [--status draft|review|approved]
+  pa project doc rm  <id> --path "..."
+  pa project doc status <id> --path "..." --status <draft|review|approved>
+  pa project workstream add <id> --id <wsId> --name "..." [--status in-progress] [--blockedOn operator]
+  pa project workstream status <id> --id <wsId> --status <status> [--blockedOn <who>]
+  pa project workstream next <id> --id <wsId> [--operator "..."] [--dave "..."]
+  pa project workstream rm <id> --id <wsId>
+  pa project list [--status ...] [--category ...] [--all] [--json]
+                  [--all-teams] [--team <identity>]
+  pa project -h, --help
+
+Notes:
+  - \`docs\` is grouped: an object keyed by group name -> array of {label, path, status?}.
+    Legacy flat-array shape is migrated transparently on first write.
+  - Default group is "Documents".
+  - Doc status values: draft, review, approved. Omit to clear.
+  - Project status=done stamps \`shipped\` to today (only if not already set).
+  - Workstreams are named units of work within a project; each has its own
+    status, blockedOn signal, and doc list. Use --workstream on doc add to
+    add a document to a workstream instead of the project-level docs.
+  - \`list\` is team-scoped by executor/assignee identity when
+    operator/config/preferences.json sets "scopeProjectsToTeam": true
+    (disabled by default — unscoped, pre-scoping behaviour). Own-team is a
+    SET: "teamIdentities" (string[], mixed agent + role names) when present,
+    else [paName]; paName is always a member. --all-teams bypasses scoping;
+    --team <identity> filters to one identity explicitly. Projects with
+    neither executor nor assignee set always show (fail open).
+
+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 'doc':         return await doDoc(rest);
+      case 'workstream':  return await doWorkstream(rest);
+      case 'list':        return await doList(rest);
+      default:
+        process.stderr.write(`[pa project] unknown verb: ${verb}\n`);
+        process.stderr.write(USAGE);
+        return 1;
+    }
+  } catch (err) {
+    process.stderr.write(`[pa project] ${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);
+      // Boolean flag if next token is missing or another flag.
+      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 doCreate(args) {
+  const { positional, flags } = parseFlags(args);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa project create <id> --name "..." --category <c> [opts]\n');
+    return 1;
+  }
+  const id = positional[0];
+  const priority = flags.priority != null && flags.priority !== true
+    ? Number(flags.priority)
+    : null;
+  const res = await createProject({
+    id,
+    name: typeof flags.name === 'string' ? flags.name : null,
+    category: typeof flags.category === 'string' ? flags.category : null,
+    priority,
+    owner: typeof flags.owner === 'string' ? flags.owner : null,
+    assignee: typeof flags.assignee === 'string' ? flags.assignee : null,
+    summary: typeof flags.summary === 'string' ? flags.summary : null,
+  });
+  process.stdout.write(`created project ${res.id} (#${res.number})\n`);
+  process.stdout.write(`  ${res.projectJsonPath}\n`);
+  if (res.created.readme) process.stdout.write(`  ${res.readmePath}\n`);
+  return 0;
+}
+
+async function doStatus(args) {
+  if (args.length < 2) {
+    process.stderr.write('usage: pa project status <id> <status>\n');
+    return 1;
+  }
+  const [id, status] = args;
+  const res = await setProjectStatus(id, status);
+  process.stdout.write(`project ${res.id} → ${res.status}\n`);
+  if (res.shipped && status === 'done') {
+    process.stdout.write(`  shipped: ${res.shipped}\n`);
+  }
+  return 0;
+}
+
+async function doDoc(args) {
+  const [sub, ...rest] = args;
+  if (sub === 'add') return await doDocAdd(rest);
+  if (sub === 'rm' || sub === 'remove') return await doDocRm(rest);
+  if (sub === 'status') return await doDocStatus(rest);
+  process.stderr.write(`usage: pa project doc <add|rm|status> ...\n`);
+  return 1;
+}
+
+async function doDocAdd(args) {
+  const { positional, flags } = parseFlags(args);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa project doc add <id> --label "..." --path "..." [--group "..."] [--workstream <wsId>] [--status draft|review|approved]\n');
+    return 1;
+  }
+  const id = positional[0];
+  const wsId = typeof flags.workstream === 'string' ? flags.workstream : null;
+
+  if (wsId) {
+    // Add to a workstream's doc list
+    const res = await addDocToWorkstream(id, wsId, {
+      label: typeof flags.label === 'string' ? flags.label : null,
+      path: typeof flags.path === 'string' ? flags.path : null,
+      status: typeof flags.status === 'string' ? flags.status : null,
+    });
+    if (res.changed) {
+      let msg = `added "${res.label}" -> workstream [${res.workstream}] in ${id}`;
+      if (res.status) msg += ` (status: ${res.status})`;
+      process.stdout.write(msg + '\n');
+    } else {
+      process.stdout.write(`no-op: "${res.label}" already present in workstream [${res.workstream}] for ${id}\n`);
+    }
+    return 0;
+  }
+
+  // Add to project-level docs (existing behaviour)
+  const res = await addProjectDoc(id, {
+    label: typeof flags.label === 'string' ? flags.label : null,
+    path: typeof flags.path === 'string' ? flags.path : null,
+    group: typeof flags.group === 'string' ? flags.group : null,
+    status: typeof flags.status === 'string' ? flags.status : null,
+  });
+  if (res.changed) {
+    let msg = `added "${res.label}" -> [${res.group}] in ${id}`;
+    if (res.status) msg += ` (status: ${res.status})`;
+    process.stdout.write(msg + '\n');
+  } else {
+    process.stdout.write(`no-op: "${res.label}" already present in [${res.group}] for ${id}\n`);
+  }
+  return 0;
+}
+
+async function doDocRm(args) {
+  const { positional, flags } = parseFlags(args);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa project doc rm <id> --path "..."\n');
+    return 1;
+  }
+  const id = positional[0];
+  const res = await removeProjectDoc(id, {
+    path: typeof flags.path === 'string' ? flags.path : null,
+  });
+  if (res.removed > 0) {
+    process.stdout.write(`removed ${res.removed} entr${res.removed === 1 ? 'y' : 'ies'} matching ${res.path} from ${id}\n`);
+    return 0;
+  }
+  process.stderr.write(`no doc found with path ${res.path} in ${id}\n`);
+  return 1;
+}
+
+async function doDocStatus(args) {
+  const { positional, flags } = parseFlags(args);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa project doc status <id> --path "..." --status <draft|review|approved>\n');
+    return 1;
+  }
+  const id = positional[0];
+  const docPath = typeof flags.path === 'string' ? flags.path : null;
+  if (!docPath) {
+    process.stderr.write('usage: pa project doc status <id> --path "..." --status <draft|review|approved>\n');
+    return 1;
+  }
+  // An omitted or empty --status removes the field.
+  const status = typeof flags.status === 'string' ? flags.status : null;
+  const res = await setProjectDocStatus(id, { path: docPath, status });
+  if (res.matched > 0) {
+    if (status) {
+      process.stdout.write(`set status "${status}" on ${res.matched} entr${res.matched === 1 ? 'y' : 'ies'} matching ${docPath} in ${id}\n`);
+    } else {
+      process.stdout.write(`cleared status on ${res.matched} entr${res.matched === 1 ? 'y' : 'ies'} matching ${docPath} in ${id}\n`);
+    }
+    return 0;
+  }
+  process.stderr.write(`no doc found with path ${docPath} in ${id}\n`);
+  return 1;
+}
+
+async function doWorkstream(args) {
+  const [sub, ...rest] = args;
+  if (sub === 'add') return await doWsAdd(rest);
+  if (sub === 'status') return await doWsStatus(rest);
+  if (sub === 'next') return await doWsNext(rest);
+  if (sub === 'rm' || sub === 'remove') return await doWsRm(rest);
+  process.stderr.write('usage: pa project workstream <add|status|next|rm> ...\n');
+  return 1;
+}
+
+async function doWsAdd(args) {
+  const { positional, flags } = parseFlags(args);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa project workstream add <projectId> --id <wsId> --name "..." [--status ...] [--blockedOn ...]\n');
+    return 1;
+  }
+  const projectId = positional[0];
+  const res = await addWorkstream(projectId, {
+    id: typeof flags.id === 'string' ? flags.id : null,
+    name: typeof flags.name === 'string' ? flags.name : null,
+    status: typeof flags.status === 'string' ? flags.status : null,
+    blockedOn: typeof flags.blockedOn === 'string' ? flags.blockedOn : null,
+  });
+  process.stdout.write(`added workstream "${res.workstream.name}" [${res.workstream.id}] to ${projectId}\n`);
+  return 0;
+}
+
+async function doWsStatus(args) {
+  const { positional, flags } = parseFlags(args);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa project workstream status <projectId> --id <wsId> --status <status> [--blockedOn <who>]\n');
+    return 1;
+  }
+  const projectId = positional[0];
+  const wsId = typeof flags.id === 'string' ? flags.id : null;
+  const status = typeof flags.status === 'string' ? flags.status : null;
+  if (!wsId || !status) {
+    process.stderr.write('usage: pa project workstream status <projectId> --id <wsId> --status <status> [--blockedOn <who>]\n');
+    return 1;
+  }
+  const blockedOn = typeof flags.blockedOn === 'string' ? flags.blockedOn : undefined;
+  const res = await setWorkstreamStatus(projectId, { id: wsId, status, blockedOn });
+  let msg = `workstream ${res.workstream.id} -> ${res.workstream.status}`;
+  if (res.workstream.blockedOn) msg += ` (blocked on: ${res.workstream.blockedOn})`;
+  process.stdout.write(msg + '\n');
+  return 0;
+}
+
+async function doWsNext(args) {
+  const { positional, flags } = parseFlags(args);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa project workstream next <projectId> --id <wsId> [--operator "..."] [--dave "..."]\n');
+    return 1;
+  }
+  const projectId = positional[0];
+  const wsId = typeof flags.id === 'string' ? flags.id : null;
+  if (!wsId) {
+    process.stderr.write('usage: pa project workstream next <projectId> --id <wsId> [--operator "..."] [--dave "..."]\n');
+    return 1;
+  }
+  const res = await setWorkstreamNext(projectId, {
+    id: wsId,
+    operator: flags.operator !== undefined ? (typeof flags.operator === 'string' ? flags.operator : '') : undefined,
+    dave: flags.dave !== undefined ? (typeof flags.dave === 'string' ? flags.dave : '') : undefined,
+  });
+  let msg = `workstream ${res.workstream.id} next actions updated`;
+  if (res.workstream.nextOperator) msg += `\n  next (you): ${res.workstream.nextOperator}`;
+  if (res.workstream.nextDave) msg += `\n  next (Dave): ${res.workstream.nextDave}`;
+  process.stdout.write(msg + '\n');
+  return 0;
+}
+
+async function doWsRm(args) {
+  const { positional, flags } = parseFlags(args);
+  if (positional.length === 0) {
+    process.stderr.write('usage: pa project workstream rm <projectId> --id <wsId>\n');
+    return 1;
+  }
+  const projectId = positional[0];
+  const wsId = typeof flags.id === 'string' ? flags.id : null;
+  if (!wsId) {
+    process.stderr.write('usage: pa project workstream rm <projectId> --id <wsId>\n');
+    return 1;
+  }
+  const res = await removeWorkstream(projectId, { id: wsId });
+  process.stdout.write(`removed workstream ${res.removed} from ${projectId}\n`);
+  return 0;
+}
+
+async function doList(args) {
+  const { flags } = parseFlags(args);
+  // Team scoping is applied inside listProjects() alongside every other
+  // filter, so an unscoped count for the notice requires a second,
+  // unscoped call — cheap (small JSON reads) and keeps the scoping logic
+  // in one place (team-scope.mjs) rather than duplicated here.
+  const scopeFilters = {
+    all: flags.all === true,
+    status: typeof flags.status === 'string' ? flags.status : null,
+    category: typeof flags.category === 'string' ? flags.category : null,
+    owner: typeof flags.owner === 'string' ? flags.owner : null,
+    assignee: typeof flags.assignee === 'string' ? flags.assignee : null,
+    allTeams: flags.allTeams === true,
+    team: typeof flags.team === 'string' ? flags.team : null,
+  };
+  const projects = await listProjects(scopeFilters);
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(projects, null, 2) + '\n');
+    return 0;
+  }
+  if (!scopeFilters.allTeams && !scopeFilters.team) {
+    const unscopedCount = (await listProjects({ ...scopeFilters, allTeams: true })).length;
+    const hidden = unscopedCount - projects.length;
+    if (hidden > 0) {
+      process.stdout.write(`(${hidden} other-team project${hidden === 1 ? '' : 's'} hidden — use --all-teams to show)\n`);
+    }
+  }
+  if (!projects.length) {
+    process.stdout.write('no projects match\n');
+    return 0;
+  }
+  // Compact tabular output.
+  const rows = projects.map((p) => ({
+    id: p.id,
+    name: p.name || '',
+    status: p.status || 'draft',
+    priority: p.priority == null ? '-' : `P${p.priority}`,
+    updated: p.updated || p.created || '-',
+  }));
+  const cols = ['id', 'name', 'status', 'priority', 'updated'];
+  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;
+}