@stravica-ai/digital-operator-pa 0.1.0

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

@@ -0,0 +1,369 @@
+// pa — operator-facing top-level CLI.
+//
+// Status: minimal v0.1.0 surface. The verbs landing here are the ones the
+// scaffolder (`pa-init`) and the operator runbook rely on. Each verb routes
+// to a specialist CLI or library.
+
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { run as runDesk } from '../../../engineering-pa-core/src/desk/cli.mjs';
+import { PA_PACKAGE_NAME } from '../../../engineering-pa-core/src/config/pa-package-name.mjs';
+import { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspect/src/cli.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const USAGE = `pa — operator personal-assistant 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 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)
+  pa gsc <verb>               Google Search Console automation (add-property | verify-via-cf-dns | submit-sitemap | pull-analytics | list-properties)
+  pa knowledge <verb>         Query the operator's knowledge graph (related | search | domain | orphans | path)
+  pa research <verb>          Deep-research session store (run | list | show | gates | prune | mark | paths)
+  pa autonomy <verb>          Per-agent per-task-type approval state (init | get | set | list)
+  pa environment [verb]       Session-boot environment cache (default | refresh | extended)
+  pa staging-alias <verb>     Canonical staging.<site> alias for CF Workers sites (set | unset | status | list)
+  pa lint <verb>              Lint operator text against voice rules (linkedin)
+  pa migrate-inspect [options]  Host inspection for migration planning
+  pa launch --agent=<n> --task=<id> [--dry-run]
+                              Boot a scoped agent instance bound to an identity and task
+  pa -h, --help               Show this help
+
+Routed sub-CLIs (also available as standalone bins):
+  desk          Task and project queries (read-side complement of \`pa project\` / \`pa work\`)
+  secrets       Vault management
+  sync          Per-host single-writer git sync
+  scheduler     Scheduling primitives
+  memory-sync   PA-memory cache mirror
+  distill       Librarian distillation sweep
+
+Exit codes (tooling standard §6):
+  0 ok | 1 usage error | 2 operational failure | 3 transport/IO failure
+`;
+
+export async function main(argv) {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const verb = argv[0];
+  const rest = argv.slice(1);
+
+  switch (verb) {
+    case 'session':
+      return await doSession(rest);
+    case 'status':
+      return await doStatus();
+    case 'workspace':
+      return await doWorkspace(rest);
+    case 'project':
+      return await doProject(rest);
+    case 'work':
+      return await doWork(rest);
+    case 'gsc':
+      return await doGsc(rest);
+    case 'knowledge':
+      return await doKnowledge(rest);
+    case 'research':
+      return await doResearch(rest);
+    case 'autonomy':
+      return await doAutonomy(rest);
+    case 'environment':
+      return await doEnvironment(rest);
+    case 'lint':
+      return await doLint(rest);
+    case 'staging-alias':
+      return await doStagingAlias(rest);
+    case 'migrate-inspect':
+      return await runMigrateInspect(rest);
+    case 'launch':
+      return await doLaunch(rest);
+    default:
+      process.stderr.write(`[pa] unknown verb: ${verb}\n`);
+      process.stderr.write(USAGE);
+      return 1;
+  }
+}
+
+async function doStatus(opts = {}) {
+  // Three structured probes followed by a desk overview snapshot.
+  //
+  //   1. Operator content present — does the cwd look like an operator repo?
+  //      Reports each well-known path as "present" or "missing".
+  //   2. Package install integrity — is `@stravica-ai/digital-operator-pa` installed
+  //      under node_modules/? If so, report its version.
+  //   3. Workspace reachability — try GET /__api/identity on the configured
+  //      workspace port (default 4200). Reports "reachable", "not running",
+  //      or "error: …". Workspace-not-running is informational, not failure.
+  //
+  // After the probes, run `desk overview` in-process and emit its output as
+  // the final section. Exit 0 if all structural prerequisites are present
+  // (operator/, installed package), 2 if any are missing.
+  //
+  // Why `desk` runs in-process rather than spawning `node_modules/.bin/desk`:
+  // under pnpm's hoisted install layout, no `node_modules/.bin/desk` is
+  // adjacent to this package; the bin shim lives off the operator-repo root.
+  // Subpath import via `@stravica-ai/engineering-pa-core/src/desk/cli.mjs` is
+  // permitted by the widened `exports` map in the core package.
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const cwd = opts.cwd ?? process.cwd();
+  const repoRoot = opts.repoRoot
+    ?? process.env.DAVE_REPO_ROOT
+    ?? process.env.PA_REPO_ROOT
+    ?? cwd;
+  const workspacePort = resolveWorkspacePort(repoRoot, opts);
+
+  let allOk = true;
+
+  // 1. Operator content probes.
+  out.write('Operator content:\n');
+  const operatorPaths = [
+    'operator/',
+    'operator/profile/profile.md',
+    'agents/',
+    'work/',
+    'projects/',
+  ];
+  const operatorMissing = [];
+  for (const rel of operatorPaths) {
+    const present = existsSync(join(repoRoot, rel));
+    out.write(`  ${rel.padEnd(36)} ${present ? 'present' : 'missing'}\n`);
+    if (!present) operatorMissing.push(rel);
+  }
+  // Treat absence of `operator/` itself as a structural failure — the other
+  // paths are recommended but not all are required on every operator repo
+  // (e.g. a brand-new scaffold may not yet have a profile.md).
+  if (operatorMissing.includes('operator/')) allOk = false;
+
+  // 2. Package install probe. Informational: a missing
+  // node_modules/@stravica-ai/digital-operator-pa is reported in the output so the
+  // operator can see it, but does not flip the exit code. Rationale: this
+  // verb is exercised against scenarios (CI fixtures, pre-install operator
+  // repos, pa-init dry-runs) where the package is intentionally absent.
+  // The pa-cli is sometimes invoked directly from the dev monorepo against
+  // an operator-shape repo before `pnpm install` has populated
+  // node_modules; treating that as a structural failure would block
+  // legitimate diagnostic use. Operator content remains the load-bearing
+  // exit-code probe (#1 above).
+  out.write('\nInstalled package:\n');
+  const pkgJson = join(repoRoot, 'node_modules', PA_PACKAGE_NAME, 'package.json');
+  if (existsSync(pkgJson)) {
+    try {
+      const meta = JSON.parse(readFileSync(pkgJson, 'utf8'));
+      out.write(`  ${PA_PACKAGE_NAME}         ${meta.version ?? '(no version)'}\n`);
+    } catch (e) {
+      out.write(`  ${PA_PACKAGE_NAME}         error reading package.json: ${e.message}\n`);
+    }
+  } else {
+    out.write(`  ${PA_PACKAGE_NAME}         missing (informational)\n`);
+  }
+
+  // 3. Workspace reachability probe.
+  out.write('\nWorkspace:\n');
+  const probeUrl = `http://localhost:${workspacePort}/__api/identity`;
+  const reachability = await probeWorkspace(probeUrl, opts.fetchImpl);
+  out.write(`  ${probeUrl}\n`);
+  out.write(`  status: ${reachability.status}`);
+  if (reachability.detail) out.write(` (${reachability.detail})`);
+  out.write('\n');
+  // Workspace-not-running is OK — operators may run pa status before
+  // starting the workspace server.
+
+  // 4. Desk overview snapshot.
+  out.write('\nOverview:\n');
+  try {
+    const code = await runDesk(['overview']);
+    if (typeof code === 'number' && code !== 0) {
+      // Desk reported a non-zero — propagate as operational failure.
+      return 2;
+    }
+  } catch (e) {
+    err.write(`[pa status] ${e?.message || e}\n`);
+    return 2;
+  }
+
+  return allOk ? 0 : 2;
+}
+
+function resolveWorkspacePort(repoRoot, opts = {}) {
+  if (opts.workspacePort) return opts.workspacePort;
+  try {
+    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
+    if (existsSync(prefsPath)) {
+      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
+      if (typeof prefs.workspacePort === 'number') return prefs.workspacePort;
+    }
+  } catch { /* fall through to default */ }
+  return 4200;
+}
+
+async function probeWorkspace(url, fetchImpl) {
+  const fetchFn = fetchImpl ?? globalThis.fetch;
+  if (typeof fetchFn !== 'function') {
+    return { status: 'error', detail: 'fetch unavailable' };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 1500);
+  try {
+    const res = await fetchFn(url, { signal: controller.signal });
+    if (res.status >= 200 && res.status < 500) {
+      return { status: 'reachable', detail: `HTTP ${res.status}` };
+    }
+    return { status: 'error', detail: `HTTP ${res.status}` };
+  } catch (e) {
+    // ECONNREFUSED / abort / DNS — server is not running.
+    const code = e && (e.cause?.code || e.code);
+    if (code === 'ECONNREFUSED' || code === 'ENOTFOUND' || e?.name === 'AbortError') {
+      return { status: 'not running', detail: null };
+    }
+    return { status: 'error', detail: e?.message || String(e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export { doStatus, probeWorkspace, resolveWorkspacePort };
+
+async function doLaunch(rest) {
+  const { run } = await import('../launch/cli.mjs');
+  return await run(rest);
+}
+
+async function doProject(rest) {
+  const { run } = await import('./project-cli.mjs');
+  return await run(rest);
+}
+
+async function doWork(rest) {
+  const { run } = await import('./work-cli.mjs');
+  return await run(rest);
+}
+
+async function doGsc(rest) {
+  const { run } = await import('../gsc/cli.mjs');
+  return await run(rest);
+}
+
+async function doLint(rest) {
+  const { main } = await import('../lint/cli.mjs');
+  return await main(rest);
+}
+
+async function doKnowledge(rest) {
+  const { run } = await import('../knowledge/cli.mjs');
+  return await run(rest);
+}
+
+async function doResearch(rest) {
+  const { main } = await import('../research/cli.mjs');
+  return await main(rest);
+}
+
+async function doAutonomy(rest) {
+  const { run } = await import('../autonomy/cli.mjs');
+  return await run(rest);
+}
+
+async function doEnvironment(rest) {
+  const { run } = await import('../environment/cli.mjs');
+  return await run(rest);
+}
+
+async function doStagingAlias(rest) {
+  const { main } = await import('../staging-alias/cli.mjs');
+  return await main(rest);
+}
+
+async function doSession(rest) {
+  // `pa session` takes no arguments today. Reject anything to make typos
+  // (`pa session help`, `pa session start`) surface fast rather than
+  // silently boot a Claude session.
+  if (rest.length > 0) {
+    if (rest[0] === '-h' || rest[0] === '--help') {
+      process.stdout.write(SESSION_USAGE);
+      return 0;
+    }
+    process.stderr.write(`[pa session] unexpected arguments: ${rest.join(' ')}\n`);
+    process.stderr.write(SESSION_USAGE);
+    return 1;
+  }
+  const { executeSession } = await import('./session.mjs');
+  return await executeSession();
+}
+
+const SESSION_USAGE = `pa session — start a PA session
+
+Usage:
+  pa session            Chdir to the agent dir for the configured PA and exec \`claude\`
+  pa session -h, --help Show this help
+
+Resolution order for the operator repo root:
+  1. \$DAVE_REPO_ROOT (if set)
+  2. \$PA_REPO_ROOT   (if set)
+  3. Walk upward from CWD looking for a \`.git\` directory
+  4. Fall back to CWD (with a warning)
+
+Reads \`operator/config/preferences.json\`; the \`paName\` field selects
+which \`agents/<paName>/\` directory the session runs in.
+
+Exit codes (tooling standard §6):
+  0 ok | 1 usage/config error | 2 operational failure
+`;
+
+const WORKSPACE_USAGE = `pa workspace — workspace server lifecycle
+
+Usage:
+  pa workspace start [--port N] [--no-open]   Start the workspace server
+  pa workspace stop                            Stop the running server (refuses if supervised)
+  pa workspace restart [--port N] [--no-open]  Restart (supervisor-aware: launchctl kickstart / systemctl restart)
+  pa workspace status                          Show server status (supervisor-aware)
+  pa workspace open                            Open the workspace URL in a browser
+  pa workspace -h, --help                      Show this help
+
+When the workspace is supervised by launchd (~/Library/LaunchAgents/com.dave.workspace.plist)
+or systemd (~/.config/systemd/user/dave-workspace.service), \`stop\` is refused and \`restart\`
+delegates to the supervisor — this is the in-place version-pickup path after \`pnpm update\`.
+
+Exit codes (tooling standard §6):
+  0 ok | 1 usage error | 2 operational failure | 3 transport/IO failure
+`;
+
+async function doWorkspace(rest) {
+  // Intercept --help / -h before routing — keeps the verb consistent with
+  // every other `pa` verb and avoids surfacing "Unknown command: --help"
+  // from the underlying ws.mjs.
+  if (rest.length > 0 && (rest[0] === '--help' || rest[0] === '-h' || rest[0] === 'help')) {
+    process.stdout.write(WORKSPACE_USAGE);
+    return 0;
+  }
+
+  // Defer to @stravica-ai/engineering-pa-workspace/src/ws.mjs by argv proxy.
+  // ws.mjs handles start/stop/status/open/restart.
+  try {
+    const wsPath = await import('../../../engineering-pa-workspace/src/ws.mjs');
+    // ws.mjs is currently a CLI script with its own main() — execute via
+    // argv when imported. The runtime emits an exit code that we propagate.
+    // Implementation detail: when imported (not executed) ws.mjs exposes a
+    // run() function in v2; here we just invoke its top-level for the
+    // common verbs.
+    if (typeof wsPath.run === 'function') {
+      return await wsPath.run(rest);
+    }
+    // Fallback: spawn ws.mjs as a child process.
+    const child = spawn(process.execPath, [
+      resolve(__dirname, '..', '..', '..', 'engineering-pa-workspace', 'src', 'ws.mjs'),
+      ...rest,
+    ], { stdio: 'inherit' });
+    return await new Promise((res) => child.on('close', (code) => res(code ?? 0)));
+  } catch (err) {
+    process.stderr.write(`[pa workspace] ${err.message || err}\n`);
+    return 2;
+  }
+}

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

@@ -0,0 +1,164 @@
+// doc-groups.mjs — schema migration + write helpers for project.json:docs.
+//
+// `docs` historically was a flat array of {label, path}. The new shape is
+// an object keyed by group name; each value is an array of {label, path}.
+//
+//   Legacy:  "docs": [ { "label": "README", "path": "..." } ]
+//   New:     "docs": { "Documents": [ { "label": "README", "path": "..." } ] }
+//
+// Backwards-compat is strict: a flat array means a single "Documents"
+// group. The first write through `addDoc` migrates the project to the
+// grouped shape; reads via `readGroups` work for both shapes.
+//
+// Group order is preserved as insertion order — JavaScript Map / plain
+// object semantics are sufficient. "Documents" stays first when it exists.
+//
+// Doc entries may carry an optional `status` field:
+//   "draft" | "review" | "approved" | undefined
+// The field is preserved through normalisation and addDoc; setDocStatus
+// provides a dedicated write path.
+
+export const DEFAULT_GROUP = 'Documents';
+
+export const VALID_DOC_STATUSES = new Set(['draft', 'review', 'approved']);
+
+/**
+ * Normalise a project's `docs` field into the new {group: entry[]} shape.
+ *
+ *  - undefined / null → {}
+ *  - flat array       → { [DEFAULT_GROUP]: array }
+ *  - object           → returned as-is (defensive copy, arrays cloned)
+ *
+ * Defensive copy so callers can mutate without leaking back to the input.
+ */
+export function normaliseDocs(docs) {
+  if (docs == null) return {};
+  if (Array.isArray(docs)) {
+    if (docs.length === 0) return {};
+    return { [DEFAULT_GROUP]: docs.map((d) => ({ ...d })) };
+  }
+  if (typeof docs === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(docs)) {
+      if (!Array.isArray(v)) continue;
+      out[k] = v.map((d) => ({ ...d }));
+    }
+    return out;
+  }
+  return {};
+}
+
+/**
+ * True iff the project's docs field is already in the grouped shape
+ * (object of arrays). Empty objects count as grouped.
+ */
+export function isGrouped(docs) {
+  return docs != null && !Array.isArray(docs) && typeof docs === 'object';
+}
+
+/**
+ * Add a doc entry to a group. Returns a new docs object — pure, does
+ * not mutate the input.
+ *
+ *  - Migrates flat-array shape to grouped shape under DEFAULT_GROUP.
+ *  - Creates the group if missing.
+ *  - Idempotent: if {label, path} already exists in the target group,
+ *    returns the input unchanged (still normalised to grouped shape).
+ */
+export function addDoc(docs, group, entry) {
+  if (!entry || typeof entry !== 'object') {
+    throw new Error('addDoc: entry must be { label, path }');
+  }
+  if (!entry.label || !entry.path) {
+    throw new Error('addDoc: entry must have label and path');
+  }
+  const groupKey = group || DEFAULT_GROUP;
+  const next = normaliseDocs(docs);
+  const existing = next[groupKey] || [];
+  const dup = existing.find((d) => d.path === entry.path && d.label === entry.label);
+  if (dup) {
+    // Already present — return the normalised-but-unchanged shape so
+    // callers writing it back still benefit from the migration even on
+    // a no-op add.
+    next[groupKey] = existing;
+    return next;
+  }
+  const newEntry = { label: entry.label, path: entry.path };
+  if (entry.status) newEntry.status = entry.status;
+  next[groupKey] = [...existing, newEntry];
+  return next;
+}
+
+/**
+ * Remove all entries with `path` from every group. Returns:
+ *   { docs: <new docs>, removed: <number> }
+ *
+ * Empty groups are dropped so the project doesn't accumulate dead
+ * headings.
+ */
+export function removeDocByPath(docs, path) {
+  const next = normaliseDocs(docs);
+  let removed = 0;
+  for (const [group, entries] of Object.entries(next)) {
+    const kept = entries.filter((d) => {
+      if (d.path === path) {
+        removed += 1;
+        return false;
+      }
+      return true;
+    });
+    if (kept.length === 0) {
+      delete next[group];
+    } else {
+      next[group] = kept;
+    }
+  }
+  return { docs: next, removed };
+}
+
+/**
+ * Iterate groups in display order. Returns [{group, entries}] with
+ * DEFAULT_GROUP first (if present), then the rest in insertion order.
+ */
+export function listGroups(docs) {
+  const normalised = normaliseDocs(docs);
+  const keys = Object.keys(normalised);
+  const ordered = [];
+  if (Object.prototype.hasOwnProperty.call(normalised, DEFAULT_GROUP)) {
+    ordered.push(DEFAULT_GROUP);
+  }
+  for (const k of keys) {
+    if (k !== DEFAULT_GROUP) ordered.push(k);
+  }
+  return ordered.map((g) => ({ group: g, entries: normalised[g] }));
+}
+
+/**
+ * Set or remove the status field on doc entries matching `path`.
+ *
+ *  - `status` must be one of VALID_DOC_STATUSES, or falsy to remove.
+ *  - Searches across all groups.
+ *  - Returns { docs, matched } where matched is the count of entries updated.
+ */
+export function setDocStatus(docs, path, status) {
+  if (status && !VALID_DOC_STATUSES.has(status)) {
+    throw new Error(
+      `invalid doc status: ${status} (expected one of: ${[...VALID_DOC_STATUSES].join(', ')})`,
+    );
+  }
+  const next = normaliseDocs(docs);
+  let matched = 0;
+  for (const entries of Object.values(next)) {
+    for (const entry of entries) {
+      if (entry.path === path) {
+        if (status) {
+          entry.status = status;
+        } else {
+          delete entry.status;
+        }
+        matched += 1;
+      }
+    }
+  }
+  return { docs: next, matched };
+}

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

@@ -0,0 +1,80 @@
+// io.mjs — shared JSON read/write helpers for the pa write-side CLIs.
+//
+// The operator-repo convention is 2-space-indented JSON with a trailing
+// newline. We always honour that on write so diffs stay clean.
+//
+// Read helpers are intentionally thin — node:fs/promises already throws
+// sensible errors for ENOENT/EACCES; callers translate to exit codes.
+
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+export async function readJson(path) {
+  const raw = await readFile(path, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Write a JSON file with the operator-repo convention: 2-space indent and a
+ * trailing newline. Creates parent directories if needed.
+ */
+export async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const body = JSON.stringify(value, null, 2) + '\n';
+  await writeFile(path, body, 'utf8');
+}
+
+/**
+ * Ensure a directory exists. Returns the absolute path.
+ */
+export async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+  return path;
+}
+
+/**
+ * List the directories inside `dir`. Returns an empty array if `dir`
+ * does not exist; throws on other errors.
+ */
+export async function listSubdirs(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+/**
+ * List the .json files in `dir`. Returns an empty array if `dir`
+ * does not exist; throws on other errors.
+ */
+export async function listJsonFiles(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.json'))
+    .map((e) => e.name);
+}
+
+/**
+ * Build an absolute path inside the repo. Convenience wrapper for callers
+ * that already have the repo root resolved.
+ */
+export function repoPath(repoRoot, ...parts) {
+  return join(repoRoot, ...parts);
+}
+
+/**
+ * Today's date in YYYY-MM-DD (UTC).
+ */
+export function today() {
+  return new Date().toISOString().slice(0, 10);
+}