@stravica-ai/digital-operator-pa 0.1.0

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

@@ -0,0 +1,352 @@
+// projects.mjs — write-side commands for `pa project <verb>`.
+//
+// Source of truth is projects/<id>/project.json. We never cache; every
+// command re-reads. This matches the desk CLI's read-side discipline.
+//
+// What lives here:
+//   - create:    scaffold a new project (dir + project.json + README.md)
+//   - status:    change project status (stamps `shipped` on done)
+//   - docAdd:    append a doc entry (migrates flat → grouped on first write)
+//   - docRm:     remove a doc entry by path
+//   - list:      list projects, optionally filtered
+//
+// Status enum and category list match packages/core/schema/project.json.
+
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { getRepoRoot } from './repo-root.mjs';
+import { readJson, writeJson, ensureDir, listSubdirs, today } from './io.mjs';
+import { addDoc, removeDocByPath, setDocStatus, DEFAULT_GROUP, VALID_DOC_STATUSES } from './doc-groups.mjs';
+import { filterProjectsByTeam, readTeamScopeConfig } from '../../../engineering-pa-core/src/desk/team-scope.mjs';
+
+const STATUSES = new Set(['draft', 'planned', 'in-progress', 'blocked', 'done', 'archived']);
+
+const KNOWN_CATEGORIES = new Set([
+  'feature', 'bug', 'chore', 'product', 'growth', 'discussion', 'research',
+]);
+
+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 (!KNOWN_CATEGORIES.has(category)) {
+    const err = new Error(
+      `invalid category: ${category} (expected one of: ${[...KNOWN_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;
+  }
+}
+
+function validateId(id) {
+  if (!id || typeof id !== 'string') {
+    const err = new Error('project id is required');
+    err.exitCode = 1;
+    throw err;
+  }
+  if (!/^[a-z0-9][a-z0-9.-]*$/i.test(id)) {
+    const err = new Error(
+      `invalid project id: ${id} (lowercase letters, digits, '-' and '.' only; must start with a letter or digit)`,
+    );
+    err.exitCode = 1;
+    throw err;
+  }
+}
+
+/**
+ * Scan every projects/*\/project.json for the highest `number`. Returns
+ * 0 if no projects exist; the next free number is +1.
+ */
+async function nextProjectNumber(repoRoot) {
+  const dir = join(repoRoot, 'projects');
+  const subdirs = await listSubdirs(dir);
+  let max = 0;
+  for (const name of subdirs) {
+    const manifest = join(dir, name, 'project.json');
+    if (!existsSync(manifest)) continue;
+    try {
+      const p = await readJson(manifest);
+      if (typeof p.number === 'number' && p.number > max) max = p.number;
+    } catch {
+      // Skip unparseable manifests — they are not our concern here.
+    }
+  }
+  return max + 1;
+}
+
+/**
+ * Create a new project. Writes:
+ *   projects/<id>/project.json
+ *   projects/<id>/README.md (only if it doesn't already exist)
+ *
+ * Returns { number, projectJsonPath, readmePath, created: { json, readme } }.
+ */
+export async function createProject(opts) {
+  validateId(opts.id);
+  if (!opts.name) {
+    const err = new Error('--name is required');
+    err.exitCode = 1;
+    throw err;
+  }
+  validateCategory(opts.category);
+  validatePriority(opts.priority);
+
+  const repoRoot = await getRepoRoot();
+  const projDir = join(repoRoot, 'projects', opts.id);
+  const projectJsonPath = join(projDir, 'project.json');
+  if (existsSync(projectJsonPath)) {
+    const err = new Error(`project already exists: ${opts.id} (${projectJsonPath})`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  await ensureDir(projDir);
+  const number = await nextProjectNumber(repoRoot);
+  const todayStr = today();
+
+  const manifest = {
+    id: opts.id,
+    number,
+    name: opts.name,
+    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: todayStr,
+    shipped: null,
+    updated: todayStr,
+    path: `projects/${opts.id}`,
+    summary: opts.summary || '',
+    docs: {
+      [DEFAULT_GROUP]: [
+        { label: 'README', path: `projects/${opts.id}/README.md` },
+      ],
+    },
+  };
+  await writeJson(projectJsonPath, manifest);
+
+  const readmePath = join(projDir, 'README.md');
+  let readmeCreated = false;
+  if (!existsSync(readmePath)) {
+    const readme = `# ${opts.name}\n\n${opts.summary || '_TODO: project summary._'}\n`;
+    await writeFile(readmePath, readme, 'utf8');
+    readmeCreated = true;
+  }
+
+  return {
+    id: opts.id,
+    number,
+    projectJsonPath,
+    readmePath,
+    created: { json: true, readme: readmeCreated },
+  };
+}
+
+/**
+ * Set project status. Stamps `shipped` to today when status=done (only
+ * if not already set). Always bumps `updated`.
+ */
+export async function setProjectStatus(id, status) {
+  validateId(id);
+  validateStatus(status);
+
+  const repoRoot = await getRepoRoot();
+  const path = join(repoRoot, 'projects', id, 'project.json');
+  if (!existsSync(path)) {
+    const err = new Error(`project not found: ${id}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  const manifest = await readJson(path);
+  manifest.status = status;
+  manifest.updated = today();
+  if (status === 'done' && !manifest.shipped) {
+    manifest.shipped = today();
+  }
+  await writeJson(path, manifest);
+  return { id, status, shipped: manifest.shipped, path };
+}
+
+/**
+ * Append a doc entry to a group. Migrates a legacy flat-array shape to
+ * grouped in the same write. Idempotent on {label,path} match.
+ */
+export async function addProjectDoc(id, { label, path: docPath, group, status }) {
+  validateId(id);
+  if (!label) {
+    const err = new Error('--label is required');
+    err.exitCode = 1;
+    throw err;
+  }
+  if (!docPath) {
+    const err = new Error('--path is required');
+    err.exitCode = 1;
+    throw err;
+  }
+  if (status && !VALID_DOC_STATUSES.has(status)) {
+    const err = new Error(
+      `invalid doc status: ${status} (expected one of: ${[...VALID_DOC_STATUSES].join(', ')})`,
+    );
+    err.exitCode = 1;
+    throw err;
+  }
+  const repoRoot = await getRepoRoot();
+  const manifestPath = join(repoRoot, 'projects', id, 'project.json');
+  if (!existsSync(manifestPath)) {
+    const err = new Error(`project not found: ${id}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  const manifest = await readJson(manifestPath);
+  const before = JSON.stringify(manifest.docs);
+  const entry = { label, path: docPath };
+  if (status) entry.status = status;
+  manifest.docs = addDoc(manifest.docs, group, entry);
+  const after = JSON.stringify(manifest.docs);
+  if (before !== after) {
+    manifest.updated = today();
+  }
+  await writeJson(manifestPath, manifest);
+  return {
+    id,
+    group: group || DEFAULT_GROUP,
+    label,
+    path: docPath,
+    status: status || null,
+    changed: before !== after,
+    manifestPath,
+  };
+}
+
+/**
+ * Remove a doc entry by path (matches across all groups). Reports the
+ * number of entries removed; returns changed=false when nothing matched.
+ */
+export async function removeProjectDoc(id, { path: docPath }) {
+  validateId(id);
+  if (!docPath) {
+    const err = new Error('--path is required');
+    err.exitCode = 1;
+    throw err;
+  }
+  const repoRoot = await getRepoRoot();
+  const manifestPath = join(repoRoot, 'projects', id, 'project.json');
+  if (!existsSync(manifestPath)) {
+    const err = new Error(`project not found: ${id}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  const manifest = await readJson(manifestPath);
+  const { docs: nextDocs, removed } = removeDocByPath(manifest.docs, docPath);
+  if (removed > 0) {
+    manifest.docs = nextDocs;
+    manifest.updated = today();
+    await writeJson(manifestPath, manifest);
+  }
+  return { id, path: docPath, removed, manifestPath };
+}
+
+/**
+ * Set or remove the status field on a doc entry identified by path.
+ * Searches across all groups.
+ */
+export async function setProjectDocStatus(id, { path: docPath, status }) {
+  validateId(id);
+  if (!docPath) {
+    const err = new Error('--path is required');
+    err.exitCode = 1;
+    throw err;
+  }
+  if (status && !VALID_DOC_STATUSES.has(status)) {
+    const err = new Error(
+      `invalid doc status: ${status} (expected one of: ${[...VALID_DOC_STATUSES].join(', ')})`,
+    );
+    err.exitCode = 1;
+    throw err;
+  }
+  const repoRoot = await getRepoRoot();
+  const manifestPath = join(repoRoot, 'projects', id, 'project.json');
+  if (!existsSync(manifestPath)) {
+    const err = new Error(`project not found: ${id}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  const manifest = await readJson(manifestPath);
+  const { docs: nextDocs, matched } = setDocStatus(manifest.docs, docPath, status || null);
+  if (matched > 0) {
+    manifest.docs = nextDocs;
+    manifest.updated = today();
+    await writeJson(manifestPath, manifest);
+  }
+  return { id, path: docPath, status: status || null, matched, manifestPath };
+}
+
+/**
+ * List projects. Filters: status, category, owner, assignee, all,
+ * allTeams, team. By default excludes done + archived (mirrors desk-list
+ * semantics). Team scoping mirrors desk exactly — see
+ * `@stravica-ai/engineering-pa-core/src/desk/team-scope.mjs` for the rules
+ * (executor/assignee scoping key, fail-open on unclassifiable projects,
+ * disabled unless operator/config/preferences.json opts in).
+ */
+export async function listProjects(filters = {}) {
+  const repoRoot = await getRepoRoot();
+  const dir = join(repoRoot, 'projects');
+  const subdirs = await listSubdirs(dir);
+  const projects = [];
+  for (const name of subdirs) {
+    const manifest = join(dir, name, 'project.json');
+    if (!existsSync(manifest)) continue;
+    try {
+      projects.push(await readJson(manifest));
+    } catch {
+      // Skip unparseable — surfacing here would mask the user's intent.
+    }
+  }
+  const teamScopeConfig = await readTeamScopeConfig(repoRoot);
+  let filtered = filterProjectsByTeam(projects, {
+    selfIdentities: teamScopeConfig.teamIdentities,
+    scopeEnabled: teamScopeConfig.scopeEnabled,
+    allTeams: filters.allTeams === true,
+    team: filters.team || null,
+  });
+  if (!filters.all) {
+    filtered = filtered.filter((p) => !['done', 'archived'].includes(p.status));
+  }
+  if (filters.status) filtered = filtered.filter((p) => p.status === filters.status);
+  if (filters.category) filtered = filtered.filter((p) => p.category === filters.category);
+  if (filters.owner) filtered = filtered.filter((p) => p.owner === filters.owner);
+  if (filters.assignee) filtered = filtered.filter((p) => p.assignee === filters.assignee);
+  // Stable display order: status priority, then numeric priority, then number.
+  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.number || 999) - (b.number || 999);
+  });
+  return filtered;
+}

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

@@ -0,0 +1,64 @@
+// repo-root.mjs — operator repo root discovery for the `pa project` /
+// `pa work` write-side CLIs.
+//
+// Mirrors packages/cli/src/launch/repo-root.mjs. Own copy avoids
+// cross-module coupling for a pure utility; the launch CLI's cache is
+// independent.
+//
+// Resolution order:
+//   1. DAVE_REPO_ROOT / PA_REPO_ROOT env var (explicit override)
+//   2. Walk upward from process.cwd() looking for a `.git` entry
+//
+// Either a `.git` directory (primary checkout) or `.git` file (worktree)
+// counts as the marker.
+
+import { stat } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+
+async function pathKind(p) {
+  try {
+    const s = await stat(p);
+    if (s.isDirectory()) return 'dir';
+    if (s.isFile()) return 'file';
+    return 'other';
+  } catch {
+    return 'missing';
+  }
+}
+
+export async function findRepoRoot(start) {
+  let d = start;
+  while (d && d !== dirname(d)) {
+    const k = await pathKind(join(d, '.git'));
+    if (k === 'dir' || k === 'file') return d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+let _cache = null;
+
+export async function getRepoRoot() {
+  if (_cache) return _cache;
+  const envRoot = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
+  if (envRoot) {
+    _cache = resolve(envRoot);
+    return _cache;
+  }
+  const found = await findRepoRoot(process.cwd());
+  if (!found) {
+    const err = new Error(
+      'could not find operator repo root from ' + process.cwd() +
+      ' (no .git ancestor; set DAVE_REPO_ROOT or PA_REPO_ROOT to override)',
+    );
+    err.exitCode = 2;
+    throw err;
+  }
+  _cache = found;
+  return _cache;
+}
+
+// Test seam: reset the cached root between test cases.
+export function _resetRepoRoot() {
+  _cache = null;
+}

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

@@ -0,0 +1,254 @@
+// session.mjs — `pa session` verb.
+//
+// Resolve the operator repo root, read `operator/config/preferences.json`,
+// chdir to `agents/<paName>/`, and exec `claude --dangerously-skip-permissions`
+// so the operator boots straight into a PA session.
+//
+// Replaces v1's `dave.sh` wrapper, which was dropped during the v2 cutover.
+// Fresh operators (Dex's upcoming cutover; future operators) saw
+// `pa-init: done.` with no guidance on how to actually launch their PA —
+// `pa session` closes that gap.
+//
+// Errors are surfaced with a clear stderr message; exit code 1 for
+// user/config errors, exit code 2 for internal/unexpected failures, per
+// the tooling standard §6.
+//
+// All filesystem effects + process replacement happen behind a `seam`
+// argument so tests can drive the logic without touching disk or actually
+// spawning `claude`.
+
+import { readFile, stat } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * Resolve the operator repo root with the priority documented in the brief:
+ *   1. process.env.DAVE_REPO_ROOT (if set and the directory exists)
+ *   2. process.env.PA_REPO_ROOT   (if set and the directory exists)
+ *   3. Walk upward from `startDir` looking for a `.git/` directory
+ *   4. Fallback: `startDir` itself, with a warning to stderr
+ *
+ * Returns `{ root, source }` where `source` is one of:
+ *   'DAVE_REPO_ROOT' | 'PA_REPO_ROOT' | '.git-walk' | 'cwd-fallback'.
+ *
+ * The seam exists so tests can inject a fake env + fake startDir without
+ * mutating process state.
+ */
+export async function resolveRepoRoot(seam = {}) {
+  const env = seam.env ?? process.env;
+  const startDir = seam.startDir ?? process.cwd();
+  const pathExists = seam.pathExists ?? defaultPathExists;
+  const stderr = seam.stderr ?? process.stderr;
+
+  for (const varName of ['DAVE_REPO_ROOT', 'PA_REPO_ROOT']) {
+    const v = env[varName];
+    if (v) {
+      const abs = resolve(v);
+      if (await pathExists(abs, 'dir')) {
+        return { root: abs, source: varName };
+      }
+    }
+  }
+
+  let d = resolve(startDir);
+  while (d && d !== dirname(d)) {
+    if (await pathExists(join(d, '.git'), 'dir-or-file')) {
+      return { root: d, source: '.git-walk' };
+    }
+    d = dirname(d);
+  }
+
+  const fallback = resolve(startDir);
+  stderr.write(
+    `[pa session] warning: no .git ancestor found from ${startDir}; falling back to current directory\n`,
+  );
+  return { root: fallback, source: 'cwd-fallback' };
+}
+
+async function defaultPathExists(p, mode) {
+  try {
+    const s = await stat(p);
+    if (mode === 'dir') return s.isDirectory();
+    if (mode === 'dir-or-file') return s.isDirectory() || s.isFile();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The thin error class. `exitCode` carries the suggested process exit
+ * code. `userMessage` is the operator-facing string written to stderr.
+ */
+export class SessionError extends Error {
+  constructor(userMessage, exitCode) {
+    super(userMessage);
+    this.userMessage = userMessage;
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Read the preferences.json at the given repo root, validate `paName`,
+ * and confirm `agents/<paName>/` exists. Returns a plan object describing
+ * what the verb is about to do — `runSession` then either execs `claude`
+ * or hands the plan to a test seam.
+ */
+export async function buildSessionPlan(repoRoot, seam = {}) {
+  const readFileImpl = seam.readFile ?? readFile;
+  const pathExists = seam.pathExists ?? defaultPathExists;
+
+  const preferencesPath = join(repoRoot, 'operator', 'config', 'preferences.json');
+
+  let raw;
+  try {
+    raw = await readFileImpl(preferencesPath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      throw new SessionError(
+        `preferences.json not found at ${preferencesPath}. Run \`pa-init\` to scaffold an operator config.`,
+        1,
+      );
+    }
+    throw new SessionError(
+      `failed to read preferences.json at ${preferencesPath}: ${err.message ?? err}`,
+      2,
+    );
+  }
+
+  let prefs;
+  try {
+    prefs = JSON.parse(raw);
+  } catch (err) {
+    throw new SessionError(
+      `preferences.json at ${preferencesPath} is not valid JSON: ${err.message ?? err}`,
+      1,
+    );
+  }
+
+  if (!prefs || typeof prefs !== 'object' || Array.isArray(prefs)) {
+    throw new SessionError(
+      `preferences.json at ${preferencesPath} must be a JSON object.`,
+      1,
+    );
+  }
+
+  const paName = prefs.paName;
+  if (typeof paName !== 'string' || paName.trim().length === 0) {
+    throw new SessionError(
+      `preferences.json at ${preferencesPath} is missing required field \`paName\`.`,
+      1,
+    );
+  }
+
+  const agentDir = join(repoRoot, 'agents', paName);
+  if (!(await pathExists(agentDir, 'dir'))) {
+    throw new SessionError(
+      `agent directory ${agentDir} does not exist. Did you complete \`pa-init\`?`,
+      1,
+    );
+  }
+
+  return {
+    repoRoot,
+    preferencesPath,
+    paName,
+    agentDir,
+    command: 'claude',
+    args: ['--dangerously-skip-permissions'],
+  };
+}
+
+/**
+ * Execute the plan: chdir to the agent directory and spawn `claude`,
+ * inheriting stdio. We use `spawn` rather than a process-replacing exec
+ * because Node has no portable cross-platform `execvp`; spawning with
+ * `stdio: 'inherit'` and exiting with the child's code is the standard
+ * Node equivalent.
+ *
+ * The seam is the chokepoint: tests inject a fake spawner and a fake
+ * chdir to verify the plan without launching real processes.
+ */
+export async function runSession(plan, seam = {}) {
+  const chdirImpl = seam.chdir ?? ((d) => process.chdir(d));
+  const spawner = seam.spawner ?? defaultSpawner;
+  const stderr = seam.stderr ?? process.stderr;
+
+  try {
+    chdirImpl(plan.agentDir);
+  } catch (err) {
+    throw new SessionError(
+      `failed to chdir to ${plan.agentDir}: ${err.message ?? err}`,
+      2,
+    );
+  }
+
+  try {
+    const code = await spawner(plan);
+    return typeof code === 'number' ? code : 0;
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      stderr.write(
+        '[pa session] `claude` not found on PATH. Install Claude Code or ensure `claude` is on `PATH` before running `pa session`.\n',
+      );
+      return 1;
+    }
+    throw new SessionError(
+      `failed to spawn \`claude\`: ${err.message ?? err}`,
+      2,
+    );
+  }
+}
+
+function defaultSpawner(plan) {
+  return new Promise((resolveP, rejectP) => {
+    const child = spawn(plan.command, plan.args, { stdio: 'inherit' });
+    child.on('close', (code) => resolveP(code ?? 0));
+    child.on('error', (err) => rejectP(err));
+  });
+}
+
+/**
+ * Top-level verb entry. Wires resolve → plan → run, translates SessionError
+ * to a stderr write + the carried exit code, and lets unexpected throws
+ * surface as exit code 2.
+ */
+export async function executeSession(seam = {}) {
+  const stderr = seam.stderr ?? process.stderr;
+  const stdout = seam.stdout ?? process.stdout;
+
+  let repoRoot;
+  try {
+    const resolved = await resolveRepoRoot(seam);
+    repoRoot = resolved.root;
+    if (seam.verbose) {
+      stdout.write(`[pa session] repo root: ${repoRoot} (via ${resolved.source})\n`);
+    }
+  } catch (err) {
+    stderr.write(`[pa session] ${err.message ?? err}\n`);
+    return 2;
+  }
+
+  let plan;
+  try {
+    plan = await buildSessionPlan(repoRoot, seam);
+  } catch (err) {
+    if (err instanceof SessionError) {
+      stderr.write(`[pa session] ${err.userMessage}\n`);
+      return err.exitCode;
+    }
+    stderr.write(`[pa session] ${err.message ?? err}\n`);
+    return 2;
+  }
+
+  try {
+    return await runSession(plan, seam);
+  } catch (err) {
+    if (err instanceof SessionError) {
+      stderr.write(`[pa session] ${err.userMessage}\n`);
+      return err.exitCode;
+    }
+    stderr.write(`[pa session] ${err.message ?? err}\n`);
+    return 2;
+  }
+}