@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/docs/staging-alias.md

@@ -0,0 +1,114 @@
+# pa staging-alias
+
+Canonical `staging.<site>` subdomain pattern for the operator's
+Cloudflare-Workers-hosted sites. One command flips the alias to the
+branch under review.
+
+## Pattern
+
+```
+                           +-----------------------------+
+  staging.stravica.ai ---->|  stravica-ai-staging         |
+  (CF Custom Domain)       |  (router worker, env=        |
+                           |   STAGING_TARGET=<preview>)  |
+                           +--------------+---------------+
+                                          |
+                                          v
+              +-------------------------------------------------+
+              | 350f46a0-stravica-ai.barry-ab9.workers.dev      |
+              | (workers.dev preview URL — version-pinned)      |
+              +-------------------------------------------------+
+                                          |
+                                          v
+                           +-----------------------------+
+                           |  stravica-ai (source worker)|
+                           |  prod -> stravica.ai apex   |
+                           +-----------------------------+
+```
+
+Why a router worker?
+
+Two CF Workers limitations forced this shape:
+
+1. **Custom Domains always serve the production deployment.** You cannot
+   bind a CF Custom Domain (`staging.stravica.ai`) directly to a
+   specific version of the source worker — it always serves whatever
+   `wrangler deploy` last promoted to 100%.
+2. **Preview URLs cannot run on a non-`workers.dev` subdomain.** CF
+   explicitly states: "You cannot currently configure Preview URLs to
+   run on a subdomain other than workers.dev." So a CNAME from
+   `staging.stravica.ai` → `<prefix>-stravica-ai.barry-ab9.workers.dev`
+   is rejected by the CF edge (cross-user CNAME).
+
+The router-worker indirection sidesteps both. It's a 25-line proxy that
+fetches `STAGING_TARGET` and returns the upstream response unchanged.
+Updating the staging target = re-deploying the router with a new
+`STAGING_TARGET` binding — a single API call.
+
+## Multi-account safety drill
+
+Cloudflare has multiple accounts in this estate (Stravica dedicated,
+Clive-shared). Using the wrong account's keys would catastrophically
+write to the wrong tenant. Every `set` / `unset` runs:
+
+1. Look up the site in the registry.
+2. Load the vault keys for the site's `accountKey` (`stravica` /
+   `clive` / ...).
+3. `GET /accounts/{account_id}` — read the account's display name.
+4. Compare against `expectedAccountName` from the site registry.
+5. ABORT (exit 2) on mismatch.
+6. Only then write.
+
+The drill output is echoed on stdout: `account verified: "X" (id)`.
+
+## Usage
+
+```bash
+# Wire staging.stravica.ai to the latest preview deployment of the
+# source worker. CF doesn't tag versions with branch, so this picks
+# the newest version — operator must have just pushed the branch.
+pa staging-alias set --site stravica.ai --branch peer-review
+
+# Pin a specific version explicitly (precise, branch tagging not needed).
+pa staging-alias set --site stravica.ai --branch peer-review \
+  --version 350f46a0-c38e-48a5-8395-216d3b290dac
+
+# Inspect current state.
+pa staging-alias status --site stravica.ai
+
+# Across all registered sites.
+pa staging-alias list
+
+# Remove the alias (binding + router worker).
+pa staging-alias unset --site stravica.ai
+```
+
+## Adding a fourth site
+
+Edit `src/staging-alias/sites.mjs`. Add one entry:
+
+```js
+'newsite.com': {
+  hostname: 'newsite.com',
+  sourceWorker: 'newsite',
+  routerWorker: 'newsite-staging',
+  accountKey: 'newsite',  // or 'stravica' / 'clive' if shared
+  expectedAccountName: "Owner's Account",
+  zoneName: 'newsite.com',
+},
+```
+
+…and store the vault keys: `CLOUDFLARE_PAGES_API_KEY_NEWSITE` +
+`CLOUDFLARE_PAGES_ACCOUNT_ID_NEWSITE`.
+
+## Exit codes
+
+- `0` ok
+- `1` usage error (bad flags, unknown site, no versions on source worker)
+- `2` operational failure (account-drill mismatch, CF API write failed)
+- `3` transport/IO failure (network down, non-JSON CF response)
+
+## Tests
+
+`node --test packages/cli/test/staging-alias/`. All CF API calls are
+mocked; no real account is touched in tests.

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

@@ -0,0 +1,17 @@
+// @stravica-ai/engineering-pa-cli — operator-facing CLIs.
+//
+// Bin entries: pa, secrets, scheduler, sync, smoke, launch (declared in package.json).
+// desk, distill, memory-sync own their bin entries on @stravica-ai/engineering-pa-core.
+//
+// Public surface is intentionally narrow — most consumers spawn the bin
+// shims. This module exports the underlying run/main functions for
+// in-process composition (e.g. by `pa workspace` proxying to `ws.mjs`).
+
+export const name = './';
+export const version = '0.1.1';
+export const bins = ['pa', 'secrets', 'scheduler', 'sync', 'smoke', 'launch'];
+
+export { run as runSmokeCli } from './src/smoke/cli.mjs';
+export { run as runSchedulerCli } from './src/scheduler/cli.mjs';
+export { run as runLaunchCli } from './src/launch/cli.mjs';
+export { runSmoke } from './src/smoke/commands/run.mjs';

package/dist/engineering-pa-cli/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@stravica-ai/engineering-pa-cli",
+  "version": "0.2.2",
+  "description": "Operator-facing CLIs — pa, secrets, scheduler, sync, smoke, launch.",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./src/*": "./src/*"
+  },
+  "bin": {
+    "pa": "bin/pa",
+    "secrets": "bin/secrets",
+    "scheduler": "bin/scheduler",
+    "estate-sync": "bin/estate-sync",
+    "sync": "bin/sync",
+    "smoke": "bin/smoke",
+    "launch": "bin/launch",
+    "research": "bin/research",
+    "pa-coordinator-hook": "bin/pa-coordinator-hook"
+  },
+  "dependencies": {
+    "@stravica-ai/engineering-pa-core": "workspace:*",
+    "@stravica-ai/engineering-pa-migrate-inspect": "workspace:*",
+    "google-auth-library": "^9.15.0",
+    "googleapis": "^144.0.0"
+  },
+  "private": true,
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test --test-isolation=none 'test/**/*.test.mjs'"
+  },
+  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie."
+}

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

@@ -0,0 +1,329 @@
+// cli.mjs — argv router for `pa autonomy <verb>`.
+//
+// Verbs:
+//   pa autonomy init <agent> [--owner <name>]
+//   pa autonomy get  <agent> [<task-type>]  [--format table|json]
+//   pa autonomy set  <agent> <task-type> <state> [--label <text>] [--note <text>]
+//   pa autonomy list [<agent>]              [--format table|json]
+//
+// Exit codes (tooling standard §6):
+//   0 ok  |  1 usage  |  2 invalid state / unknown agent / envelope parse
+//   3 IO failure
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { getRepoRoot } from '../pa/repo-root.mjs';
+import {
+  VALID_STATES,
+  parseEnvelope,
+  renderEnvelope,
+  extractHistory,
+  validateFrontmatter,
+  nowIso,
+  emptyEnvelope,
+} from './envelope.mjs';
+
+const USAGE = `pa autonomy — per-agent per-task-type approval state
+
+Usage:
+  pa autonomy init <agent> [--owner <name>]
+      Create an empty envelope for <agent>. Errors if the envelope already
+      exists. --owner defaults to \$USER or "operator".
+
+  pa autonomy get <agent> [<task-type>] [--format table|json]
+      Print current state. Task-type optional — prints full table if omitted.
+
+  pa autonomy set <agent> <task-type> <state> [--label <text>] [--note <text>]
+      Update state for the given task type. Creates the task type if it
+      doesn't exist yet. State: fullyApproved | checkBeforeCommitting |
+      needsFullSupervision.
+
+  pa autonomy list [<agent>] [--format table|json]
+      List envelopes (all agents, or one). Flags stale envelopes (>30 days).
+
+  pa autonomy -h, --help
+      Show this help.
+
+Envelope files live at <repo-root>/agents/<agent>/autonomy-envelope.md.
+Repo-root resolution: DAVE_REPO_ROOT / PA_REPO_ROOT env var, else walk
+upward from cwd looking for a .git entry.
+
+Schema: @stravica-ai/engineering-pa-core/schema/autonomy-envelope.schema.json.
+
+Exit codes (tooling standard §6):
+  0 ok | 1 usage error | 2 invalid state / unknown agent / parse
+  3 IO 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 'init': return await doInit(rest);
+      case 'get': return await doGet(rest);
+      case 'set': return await doSet(rest);
+      case 'list': return await doList(rest);
+      default:
+        process.stderr.write(`[pa autonomy] unknown verb: ${verb}\n`);
+        process.stderr.write(USAGE);
+        return 1;
+    }
+  } catch (err) {
+    process.stderr.write(`[pa autonomy] ${err.message || err}\n`);
+    return err.exitCode ?? 2;
+  }
+}
+
+async function doInit(rest) {
+  const { positionals, flags } = parseArgs(rest, ['owner']);
+  if (positionals.length !== 1) {
+    process.stderr.write('[pa autonomy init] expected: pa autonomy init <agent> [--owner <name>]\n');
+    return 1;
+  }
+  const [agent] = positionals;
+  const owner = flags.owner || process.env.USER || 'operator';
+  const envelopePath = await resolveEnvelopePath(agent);
+  if (existsSync(envelopePath)) {
+    process.stderr.write(`[pa autonomy init] envelope already exists at ${envelopePath}\n`);
+    return 2;
+  }
+  const { frontmatter } = emptyEnvelope(agent, owner);
+  mkdirSync(dirname(envelopePath), { recursive: true });
+  writeFileSync(envelopePath, renderEnvelope(frontmatter, []));
+  process.stdout.write(`Initialised autonomy envelope for '${agent}' at ${envelopePath}\n`);
+  return 0;
+}
+
+async function doGet(rest) {
+  const { positionals, flags } = parseArgs(rest, ['format']);
+  if (positionals.length < 1 || positionals.length > 2) {
+    process.stderr.write('[pa autonomy get] expected: pa autonomy get <agent> [<task-type>] [--format json]\n');
+    return 1;
+  }
+  const [agent, taskType] = positionals;
+  const format = flags.format || 'table';
+  const envelope = await loadEnvelopeOrHint(agent);
+  if (taskType) {
+    const entry = envelope.frontmatter.taskTypes.find((t) => t.id === taskType);
+    if (!entry) {
+      process.stderr.write(`[pa autonomy get] task type '${taskType}' not present on ${agent}'s envelope\n`);
+      return 2;
+    }
+    if (format === 'json') {
+      process.stdout.write(JSON.stringify(entry, null, 2) + '\n');
+    } else {
+      process.stdout.write(formatEntry(entry) + '\n');
+    }
+    return 0;
+  }
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({
+      agent: envelope.frontmatter.agent,
+      owner: envelope.frontmatter.owner,
+      updated: envelope.frontmatter.updated,
+      taskTypes: envelope.frontmatter.taskTypes,
+    }, null, 2) + '\n');
+  } else {
+    process.stdout.write(formatEnvelopeTable(envelope) + '\n');
+  }
+  return 0;
+}
+
+async function doSet(rest) {
+  const { positionals, flags } = parseArgs(rest, ['label', 'note']);
+  if (positionals.length !== 3) {
+    process.stderr.write('[pa autonomy set] expected: pa autonomy set <agent> <task-type> <state> [--label <text>] [--note <text>]\n');
+    return 1;
+  }
+  const [agent, taskType, state] = positionals;
+  if (!VALID_STATES.includes(state)) {
+    process.stderr.write(`[pa autonomy set] invalid state '${state}' — must be one of: ${VALID_STATES.join(', ')}\n`);
+    return 2;
+  }
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(taskType)) {
+    process.stderr.write(`[pa autonomy set] invalid task-type slug '${taskType}' — must match ^[a-z0-9][a-z0-9-]*$\n`);
+    return 2;
+  }
+  const envelope = await loadEnvelopeOrHint(agent);
+  const now = nowIso();
+  const existing = envelope.frontmatter.taskTypes.find((t) => t.id === taskType);
+  if (existing) {
+    existing.state = state;
+    existing.stateSince = now;
+    if (flags.label) existing.label = flags.label;
+    if (flags.note !== undefined) existing.operatorNote = flags.note;
+  } else {
+    envelope.frontmatter.taskTypes.push({
+      id: taskType,
+      label: flags.label || taskType.replace(/-/g, ' '),
+      state,
+      stateSince: now,
+      ...(flags.note !== undefined ? { operatorNote: flags.note } : {}),
+    });
+  }
+  envelope.frontmatter.updated = now;
+  envelope.history.push({
+    at: now,
+    taskTypeId: taskType,
+    state,
+    note: flags.note ?? null,
+  });
+  validateFrontmatter(envelope.frontmatter);
+  const envelopePath = await resolveEnvelopePath(agent);
+  writeFileSync(envelopePath, renderEnvelope(envelope.frontmatter, envelope.history));
+  process.stdout.write(`Set ${agent}/${taskType} → ${state}\n`);
+  return 0;
+}
+
+async function doList(rest) {
+  const { positionals, flags } = parseArgs(rest, ['format']);
+  const format = flags.format || 'table';
+  const agents = positionals.length === 1
+    ? [positionals[0]]
+    : await discoverAgents();
+  const results = [];
+  for (const agent of agents) {
+    const envelopePath = await resolveEnvelopePath(agent);
+    if (!existsSync(envelopePath)) {
+      results.push({ agent, present: false, staleDays: null, taskTypeCount: 0 });
+      continue;
+    }
+    try {
+      const source = readFileSync(envelopePath, 'utf8');
+      const { frontmatter } = parseEnvelope(source);
+      const updatedMs = Date.parse(frontmatter.updated || '');
+      const staleDays = Number.isFinite(updatedMs)
+        ? Math.floor((Date.now() - updatedMs) / (1000 * 60 * 60 * 24))
+        : null;
+      results.push({
+        agent,
+        present: true,
+        staleDays,
+        taskTypeCount: (frontmatter.taskTypes ?? []).length,
+        updated: frontmatter.updated,
+      });
+    } catch (err) {
+      results.push({ agent, present: true, error: err.message });
+    }
+  }
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+  } else {
+    if (results.length === 0) {
+      process.stdout.write('No agents found under <repo-root>/agents/.\n');
+    } else {
+      process.stdout.write('Agent           | State                 | Task types | Updated\n');
+      process.stdout.write('----------------|-----------------------|------------|-------------------\n');
+      for (const r of results) {
+        if (!r.present) {
+          process.stdout.write(`${pad(r.agent, 15)} | (no envelope)         |          - | -\n`);
+          continue;
+        }
+        if (r.error) {
+          process.stdout.write(`${pad(r.agent, 15)} | ERROR: ${r.error}\n`);
+          continue;
+        }
+        const stale = r.staleDays != null && r.staleDays > 30 ? ` (stale ${r.staleDays}d)` : '';
+        process.stdout.write(`${pad(r.agent, 15)} | present${stale.padEnd(14)} | ${String(r.taskTypeCount).padStart(10)} | ${r.updated ?? '-'}\n`);
+      }
+    }
+  }
+  return 0;
+}
+
+function parseArgs(rest, allowedFlags) {
+  const positionals = [];
+  const flags = {};
+  const allowed = new Set(allowedFlags);
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg.startsWith('--')) {
+      const eqIdx = arg.indexOf('=');
+      const name = eqIdx === -1 ? arg.slice(2) : arg.slice(2, eqIdx);
+      if (!allowed.has(name)) {
+        const err = new Error(`unknown flag --${name}`);
+        err.exitCode = 1;
+        throw err;
+      }
+      const value = eqIdx === -1 ? rest[++i] : arg.slice(eqIdx + 1);
+      if (value == null) {
+        const err = new Error(`flag --${name} requires a value`);
+        err.exitCode = 1;
+        throw err;
+      }
+      flags[name] = value;
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, flags };
+}
+
+async function resolveEnvelopePath(agent) {
+  const root = await getRepoRoot();
+  return join(root, 'agents', agent, 'autonomy-envelope.md');
+}
+
+async function loadEnvelopeOrHint(agent) {
+  const envelopePath = await resolveEnvelopePath(agent);
+  if (!existsSync(envelopePath)) {
+    const err = new Error(
+      `no envelope for '${agent}' at ${envelopePath} — run \`pa autonomy init ${agent}\` first`,
+    );
+    err.exitCode = 2;
+    throw err;
+  }
+  const source = readFileSync(envelopePath, 'utf8');
+  const parsed = parseEnvelope(source);
+  validateFrontmatter(parsed.frontmatter);
+  const history = extractHistory(parsed.body);
+  return { frontmatter: parsed.frontmatter, history };
+}
+
+async function discoverAgents() {
+  const root = await getRepoRoot();
+  const agentsDir = join(root, 'agents');
+  if (!existsSync(agentsDir)) return [];
+  return readdirSync(agentsDir).filter((name) => {
+    if (name.startsWith('.')) return false;
+    return statSync(join(agentsDir, name)).isDirectory();
+  });
+}
+
+function formatEntry(entry) {
+  const parts = [
+    `id: ${entry.id}`,
+    `label: ${entry.label}`,
+    `state: ${entry.state}`,
+    entry.stateSince ? `stateSince: ${entry.stateSince}` : null,
+    entry.operatorNote ? `operatorNote: ${entry.operatorNote}` : null,
+  ].filter((x) => x != null);
+  return parts.join('\n');
+}
+
+function formatEnvelopeTable(envelope) {
+  const fm = envelope.frontmatter;
+  const lines = [];
+  lines.push(`Envelope: ${fm.agent}   Owner: ${fm.owner}   Updated: ${fm.updated}`);
+  lines.push('');
+  if (!fm.taskTypes || fm.taskTypes.length === 0) {
+    lines.push('(no task types configured)');
+    return lines.join('\n');
+  }
+  lines.push('Task type                | State                    | Since');
+  lines.push('-------------------------|--------------------------|-------------------');
+  for (const t of fm.taskTypes) {
+    lines.push(`${pad(t.id, 25)} | ${pad(t.state, 24)} | ${t.stateSince ?? '-'}`);
+  }
+  return lines.join('\n');
+}
+
+function pad(str, n) {
+  const s = String(str ?? '');
+  return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}