@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-migrate-inspect/src/inspector.mjs

@@ -0,0 +1,237 @@
+// inspector.mjs — orchestrates platform modules to produce inspection.json.
+// READ-ONLY: never writes anything (cli.mjs handles --out file writes).
+
+import os from 'node:os';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+/**
+ * Run a full host inspection.
+ * @param {object} opts
+ * @param {string|null} [opts.daveRoot]
+ * @param {object} runner - injected runner (spawnCapture, readPlist)
+ * @returns {Promise<object>} inspection result
+ */
+export async function inspect(opts = {}, runner) {
+  const [host, runtimes, platformData, daveEnvData] = await Promise.all([
+    _collectHost(),
+    _collectRuntimes(runner),
+    _collectPlatformData(runner),
+    Promise.resolve(_collectDaveEnv(opts)),
+  ]);
+
+  const daveRoot = daveEnvData.daveRoot;
+  const [paths, extensions, ageKey] = await Promise.all([
+    _collectPaths(daveRoot),
+    _collectExtensions(daveRoot),
+    _collectAgeKey(opts),
+  ]);
+
+  return {
+    host,
+    runtimes,
+    scheduled: platformData.scheduled,
+    mounts: platformData.mounts,
+    daveEnv: daveEnvData,
+    paths,
+    extensions,
+    ageKey,
+    inspectedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Collect age private key locations. Reports v1 (`~/.config/dave/age-key.txt`)
+ * and v2 (`~/.config/stravica-pa/age-key.txt`) so callers can plan or perform
+ * a migration. Pure file existence checks — never reads key contents.
+ *
+ * @param {object} opts — may include { home } for tests.
+ * @returns {Promise<{v1Path: string, v1Exists: boolean, v2Path: string,
+ *                    v2Exists: boolean, recommendation: string}>}
+ */
+export async function _collectAgeKey(opts = {}) {
+  const home = opts.home ?? homedir();
+  const v1Path = join(home, '.config', 'dave', 'age-key.txt');
+  const v2Path = join(home, '.config', 'stravica-pa', 'age-key.txt');
+  const [v1Exists, v2Exists] = await Promise.all([_exists(v1Path), _exists(v2Path)]);
+
+  // Recommendation matrix:
+  //   v1 only            -> migrate (copy v1 -> v2, keep v1 as one-session safety net)
+  //   v2 only            -> ok (canonical location populated)
+  //   both               -> v2-already-populated (no action needed; v1 can be removed later)
+  //   neither            -> none-present (host genuinely has no key — e.g. smarthome01)
+  let recommendation;
+  if (v1Exists && !v2Exists) recommendation = 'migrate';
+  else if (!v1Exists && v2Exists) recommendation = 'ok';
+  else if (v1Exists && v2Exists) recommendation = 'v2-already-populated';
+  else recommendation = 'none-present';
+
+  return { v1Path, v1Exists, v2Path, v2Exists, recommendation };
+}
+
+function _collectHost() {
+  return {
+    hostname: os.hostname(),
+    os: process.platform,
+    osVersion: os.release(),
+    arch: process.arch,
+  };
+}
+
+async function _collectRuntimes(runner) {
+  const [nodeRes, pnpmRes, gitRes] = await Promise.all([
+    runner.spawnCapture('node', ['--version']),
+    runner.spawnCapture('pnpm', ['--version']),
+    runner.spawnCapture('git', ['--version']),
+  ]);
+
+  function parseVersion(res, pattern) {
+    if (res.exitCode !== 0) return null;
+    const m = res.stdout.trim().match(pattern);
+    return m ? m[1] : (res.stdout.trim() || null);
+  }
+
+  return {
+    nodeVersion: parseVersion(nodeRes, /v?(\d+\.\d+\.\d+)/),
+    pnpmVersion: parseVersion(pnpmRes, /(\d+\.\d+\.\d+)/),
+    gitVersion: parseVersion(gitRes, /git version (.+)/),
+  };
+}
+
+async function _collectPlatformData(runner) {
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    const { collectScheduled, collectMounts } = await import('./platforms/macos.mjs');
+    const [scheduled, mounts] = await Promise.all([
+      collectScheduled(runner),
+      collectMounts(runner),
+    ]);
+    return { scheduled, mounts };
+  } else if (platform === 'linux') {
+    const { collectScheduled, collectMounts } = await import('./platforms/linux.mjs');
+    const [scheduled, mounts] = await Promise.all([
+      collectScheduled(runner),
+      collectMounts(runner),
+    ]);
+    return { scheduled, mounts };
+  }
+  return {
+    scheduled: { crontab: [], launchdPlists: [] },
+    mounts: [],
+  };
+}
+
+function _collectDaveEnv(opts) {
+  const daveRoot =
+    opts.daveRoot ||
+    process.env.DAVE_ROOT ||
+    process.env.PA_REPO_ROOT ||
+    null;
+
+  const daveRelevantEnvVars = {};
+  for (const [key, val] of Object.entries(process.env)) {
+    if (key.startsWith('DAVE_') || key === 'PA_REPO_ROOT') {
+      daveRelevantEnvVars[key] = val;
+    }
+  }
+
+  const pathSegments = [];
+  if (daveRoot && process.env.PATH) {
+    const resolved = resolve(daveRoot);
+    for (const seg of process.env.PATH.split(':')) {
+      if (seg.startsWith(resolved)) {
+        pathSegments.push(seg);
+      }
+    }
+  }
+
+  return { daveRoot, daveRelevantEnvVars, pathSegments };
+}
+
+async function _collectPaths(daveRoot) {
+  if (!daveRoot) {
+    return {
+      daveRoot: null,
+      coreToolsPath: null,
+      operatorPath: null,
+      layoutVersion: 'unknown',
+    };
+  }
+
+  const coreToolsPath = join(daveRoot, 'core', 'tools');
+  const operatorPath = join(daveRoot, 'operator');
+  const pkgJsonPath = join(daveRoot, 'package.json');
+
+  const [hasCoreTools, hasOperator, hasPkgJson] = await Promise.all([
+    _exists(coreToolsPath),
+    _exists(operatorPath),
+    _exists(pkgJsonPath),
+  ]);
+
+  let layoutVersion = 'unknown';
+  if (hasCoreTools) {
+    layoutVersion = 'v1';
+  } else if (hasPkgJson) {
+    layoutVersion = 'v2';
+  }
+
+  return {
+    daveRoot,
+    coreToolsPath: hasCoreTools ? coreToolsPath : null,
+    operatorPath: hasOperator ? operatorPath : null,
+    layoutVersion,
+  };
+}
+
+async function _collectExtensions(daveRoot) {
+  if (!daveRoot) return [];
+
+  const extensionsToolsDir = join(daveRoot, 'operator', 'extensions', 'tools');
+  let entries;
+  try {
+    entries = await readdir(extensionsToolsDir);
+  } catch {
+    return [];
+  }
+
+  // Manifest may exist at operator/extensions/manifest.json. Accept array of
+  // { name } / { id } / plain strings, or object keyed by extension name.
+  let manifestNames = null;
+  try {
+    const manifestPath = join(daveRoot, 'operator', 'extensions', 'manifest.json');
+    const raw = await readFile(manifestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      manifestNames = new Set(parsed.map(e => (typeof e === 'string' ? e : e.name || e.id)).filter(Boolean));
+    } else if (parsed && typeof parsed === 'object') {
+      manifestNames = new Set(Object.keys(parsed));
+    }
+  } catch {
+    // no manifest — leave hasManifestEntry as false for all entries
+  }
+
+  const extensions = [];
+  for (const name of entries) {
+    const path = join(extensionsToolsDir, name);
+    let isDir = false;
+    try {
+      isDir = (await stat(path)).isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+    const hasManifestEntry = manifestNames ? manifestNames.has(name) : false;
+    extensions.push({ name, path, hasManifestEntry });
+  }
+  return extensions;
+}
+
+async function _exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/dist/engineering-pa-migrate-inspect/src/platforms/linux.mjs

@@ -0,0 +1,87 @@
+// linux.mjs — pure Linux-specific collectors.
+// All spawning is done via the injected runner for testability.
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Collect scheduled tasks: crontab entries + (empty) launchdPlists.
+ * @param {import('../runner.mjs')} runner
+ * @returns {Promise<{crontab: Array<{schedule: string, command: string}>, launchdPlists: []}>}
+ */
+export async function collectScheduled(runner) {
+  const crontab = await _collectCrontab(runner);
+  const cronD = await _collectCronD();
+  return { crontab: [...crontab, ...cronD], launchdPlists: [] };
+}
+
+async function _collectCrontab(runner) {
+  const { stdout, exitCode } = await runner.spawnCapture('crontab', ['-l']);
+  if (exitCode !== 0) return [];
+  return _parseCrontab(stdout);
+}
+
+async function _collectCronD() {
+  const cronDDir = '/etc/cron.d';
+  let files;
+  try {
+    files = await readdir(cronDDir);
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'EACCES') return [];
+    return [];
+  }
+  const entries = [];
+  for (const file of files) {
+    try {
+      const content = await readFile(join(cronDDir, file), 'utf8');
+      const parsed = _parseCrontab(content);
+      entries.push(...parsed);
+    } catch (err) {
+      if (err.code === 'ENOENT' || err.code === 'EACCES') continue;
+      // skip other errors silently
+    }
+  }
+  return entries;
+}
+
+function _parseCrontab(text) {
+  const entries = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    // skip env var lines (e.g. MAILTO=...)
+    if (trimmed.match(/^\w+=\S*/)) continue;
+    const parts = trimmed.split(/\s+/);
+    if (parts.length < 6) continue;
+    const schedule = parts.slice(0, 5).join(' ');
+    const command = parts.slice(5).join(' ');
+    entries.push({ schedule, command });
+  }
+  return entries;
+}
+
+/**
+ * Collect network/remote mounts from mount output.
+ * @param {import('../runner.mjs')} runner
+ * @returns {Promise<Array<{source: string, target: string, fsType: string}>>}
+ */
+export async function collectMounts(runner) {
+  const { stdout } = await runner.spawnCapture('mount', []);
+  const REMOTE_FS_TYPES = new Set(['nfs', 'cifs', 'smbfs', 'fuse', 'nfs4', 'ceph', 'glusterfs']);
+  const mounts = [];
+  for (const line of stdout.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    // Linux mount format: source on target type fstype (options)
+    const m = trimmed.match(/^(\S+)\s+on\s+(\S+)\s+type\s+(\S+)/);
+    if (!m) continue;
+    const [, source, target, fsType] = m;
+    const isRemote =
+      REMOTE_FS_TYPES.has(fsType) ||
+      source.includes('//') ||
+      source.match(/\S+:\//);
+    if (!isRemote) continue;
+    mounts.push({ source, target, fsType });
+  }
+  return mounts;
+}

package/dist/engineering-pa-migrate-inspect/src/platforms/macos.mjs

@@ -0,0 +1,105 @@
+// macos.mjs — pure macOS-specific collectors.
+// All spawning is done via the injected runner for testability.
+
+import os from 'node:os';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Collect scheduled tasks: crontab entries + launchd plists.
+ * @param {import('../runner.mjs')} runner
+ * @returns {Promise<{crontab: Array<{schedule: string, command: string}>, launchdPlists: Array<object>}>}
+ */
+export async function collectScheduled(runner) {
+  const crontab = await _collectCrontab(runner);
+  const launchdPlists = await _collectLaunchdPlists(runner);
+  return { crontab, launchdPlists };
+}
+
+async function _collectCrontab(runner) {
+  const { stdout, exitCode } = await runner.spawnCapture('crontab', ['-l']);
+  if (exitCode !== 0) return [];
+  return _parseCrontab(stdout);
+}
+
+function _parseCrontab(text) {
+  const entries = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    // first 5 fields = schedule, rest = command
+    const parts = trimmed.split(/\s+/);
+    if (parts.length < 6) continue;
+    const schedule = parts.slice(0, 5).join(' ');
+    const command = parts.slice(5).join(' ');
+    entries.push({ schedule, command });
+  }
+  return entries;
+}
+
+async function _collectLaunchdPlists(runner) {
+  const launchAgentsDir = join(os.homedir(), 'Library', 'LaunchAgents');
+  let files;
+  try {
+    files = await readdir(launchAgentsDir);
+  } catch {
+    return [];
+  }
+  const plists = [];
+  for (const file of files) {
+    if (!file.endsWith('.plist')) continue;
+    const filePath = join(launchAgentsDir, file);
+    try {
+      const parsed = await runner.readPlist(filePath);
+      plists.push(parsed);
+    } catch {
+      // skip unreadable plists
+    }
+  }
+  return plists;
+}
+
+/**
+ * Collect network/remote mounts from mount output.
+ * @param {import('../runner.mjs')} runner
+ * @returns {Promise<Array<{source: string, target: string, fsType: string}>>}
+ */
+export async function collectMounts(runner) {
+  const { stdout } = await runner.spawnCapture('mount', []);
+  const mounts = [];
+  for (const line of stdout.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    // macOS mount format: source on target (type, options)
+    // or: //user@host/share on /mount/point (type smbfs, ...)
+    const typeMatch = trimmed.match(/\(type\s+(\S+)/);
+    const fsType = typeMatch ? typeMatch[1].replace(',', '') : '';
+    const isRemote =
+      fsType === 'nfs' ||
+      fsType === 'smbfs' ||
+      fsType === 'afpfs' ||
+      trimmed.includes('//') ||
+      trimmed.match(/\S+:\//);
+    if (!isRemote) continue;
+    // parse: source on target (...)
+    const onMatch = trimmed.match(/^(.+?)\s+on\s+(.+?)\s+\(/);
+    if (!onMatch) continue;
+    mounts.push({
+      source: onMatch[1].trim(),
+      target: onMatch[2].trim(),
+      fsType: fsType || 'unknown',
+    });
+  }
+  return mounts;
+}
+
+/**
+ * Detect chip architecture and total memory.
+ * @returns {{ chip: string, memory: number }}
+ */
+export function detectChipAndMemory() {
+  return {
+    chip: process.arch,
+    memory: os.totalmem(),
+  };
+}

package/dist/engineering-pa-migrate-inspect/src/runner.mjs

@@ -0,0 +1,87 @@
+// runner.mjs — CHOKEPOINT: all subprocess spawning happens here.
+// Zero external deps; Node stdlib only.
+
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Spawns a process and captures stdout + stderr.
+ * Returns { stdout, stderr, exitCode }.
+ * Never throws unless spawn itself fails (in which case exitCode=3).
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {Promise<{stdout: string, stderr: string, exitCode: number}>}
+ */
+export async function spawnCapture(cmd, args) {
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      resolve({ stdout: '', stderr: err.message, exitCode: 3 });
+      return;
+    }
+
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+
+    child.on('error', (err) => {
+      resolve({ stdout, stderr: stderr + err.message, exitCode: 3 });
+    });
+
+    child.on('close', (code) => {
+      resolve({ stdout, stderr, exitCode: code ?? 0 });
+    });
+  });
+}
+
+/**
+ * Reads a macOS plist XML file and parses the relevant fields.
+ * Handles only the specific keys we need: Label, Program, ProgramArguments,
+ * WorkingDirectory, RunAtLoad, KeepAlive.
+ *
+ * @param {string} filePath
+ * @returns {Promise<{label: string|null, program: string|null, args: string[]|null, workingDirectory: string|null, runAtLoad: boolean, keepAlive: boolean}>}
+ */
+export async function readPlist(filePath) {
+  const xml = await readFile(filePath, 'utf8');
+
+  function extractStringAfterKey(key) {
+    // Matches <key>KeyName</key>\s*<string>value</string>
+    const re = new RegExp(`<key>${key}</key>\\s*<string>([^<]*)</string>`, 's');
+    const m = xml.match(re);
+    return m ? m[1].trim() : null;
+  }
+
+  function extractBoolAfterKey(key) {
+    const re = new RegExp(`<key>${key}</key>\\s*<(true|false)\\s*/>`, 's');
+    const m = xml.match(re);
+    if (!m) return false;
+    return m[1] === 'true';
+  }
+
+  function extractArrayAfterKey(key) {
+    const re = new RegExp(`<key>${key}</key>\\s*<array>(.*?)</array>`, 's');
+    const m = xml.match(re);
+    if (!m) return null;
+    const strings = [];
+    const strRe = /<string>([^<]*)<\/string>/g;
+    let sm;
+    while ((sm = strRe.exec(m[1])) !== null) {
+      strings.push(sm[1].trim());
+    }
+    return strings;
+  }
+
+  return {
+    label: extractStringAfterKey('Label'),
+    program: extractStringAfterKey('Program'),
+    args: extractArrayAfterKey('ProgramArguments'),
+    workingDirectory: extractStringAfterKey('WorkingDirectory'),
+    runAtLoad: extractBoolAfterKey('RunAtLoad'),
+    keepAlive: extractBoolAfterKey('KeepAlive'),
+  };
+}

package/dist/engineering-pa-runbook/README.md

@@ -0,0 +1,103 @@
+# @stravica-ai/engineering-pa-runbook
+
+Migration runbook JSON Schema, reference runbooks, and structural validator.
+
+## What the runbook schema is for
+
+A migration runbook is a structured, machine-readable document that describes the sequence of steps needed to migrate a Dave PA instance from v1 (fork layout) to v2 (operator-repo layout). Each step has a declared `intent`, optional `params`, optional `preconditions`, expected outcomes (`expect`), and a `rollback` spec.
+
+Runbooks are designed to be executed by an autonomous agent that reads `inspection.json` (output of `pa migrate-inspect`), substitutes template variables, and dispatches each step to host-specific actuators.
+
+## Intent vocabulary
+
+| Intent | Description |
+|---|---|
+| `snapshot-v1-fork` | Preserve the v1 fork as a rollback point (git tag or directory copy) before migration begins |
+| `run-migrate-to-v2` | Invoke the `migrate-to-v2` CLI to produce the v2 operator-repo layout from the v1 fork |
+| `rewrite-crontab` | Rewrite one or more crontab entries to use the new v2 instance working directory |
+| `drop-cron-entry` | Remove a specific named cron entry (e.g. `upstream-triage`) that is not carried forward to v2 |
+| `update-host-service` | Update a service/daemon entry — launchd plist on macOS, systemd unit on Linux |
+| `verify-sync-continuity` | Verify sync jobs run and reach their destinations (e.g. NFS/SMB mount reachable, sync exits 0) |
+| `verify-boot-health` | Run `pa status` in the v2 instance and assert exit 0 |
+| `define-roster-entry` | Add or update a host entry in the operator roster, recording layout version and daveRoot |
+
+## The inspect → runbook → execute flow
+
+```
+1. pa migrate-inspect --out inspection-<host>.json
+       Produces a structured snapshot of host state: layout version, runtimes,
+       crontab entries, launchd plists, mounts, env vars, extensions.
+
+2. Agent reads inspection-<host>.json and selects the appropriate reference
+   runbook from reference/ (or a custom runbook), substituting {{daveRoot}}
+   and {{inspectedAt}} template variables.
+
+3. Agent executes each step sequentially:
+       - Evaluates preconditions against inspection data or live host state
+       - Dispatches the intent to a host-specific actuator
+       - Checks expect outcomes
+       - On failure: triggers rollback action
+
+4. On completion: define-roster-entry registers the host as v2.
+```
+
+## Executing-agent contract
+
+When an agent interprets a runbook step, it maps `intent` to host-specific commands as follows:
+
+| Intent | macOS | Linux |
+|---|---|---|
+| `snapshot-v1-fork` | `git tag` or `cp -r` | Same |
+| `run-migrate-to-v2` | `node migrate-to-v2/cli.mjs` | Same |
+| `rewrite-crontab` | `crontab -l` + edit + `crontab -` | Same |
+| `drop-cron-entry` | `crontab -l` + filter + `crontab -` | Same |
+| `update-host-service` | Edit `~/Library/LaunchAgents/<label>.plist`, `launchctl unload/load` | Edit `/etc/systemd/system/<unit>.service`, `systemctl daemon-reload && restart` |
+| `verify-sync-continuity` | Check mount reachable, run sync script | Same |
+| `verify-boot-health` | `pa status` in `daveRoot` | Same |
+| `define-roster-entry` | Write to `operator/roster.json` | Same |
+
+The agent reads the `host.os` field from `inspection.json` to determine which platform-specific path to take for `update-host-service`. All other intents are platform-neutral.
+
+## Schema reference
+
+- `schema/runbook.schema.json` — JSON Schema 2020-12 for runbook documents
+- `schema/inspection.schema.json` — JSON Schema 2020-12 for inspection.json output
+
+## How to validate a runbook
+
+```js
+import { validate } from '@stravica-ai/engineering-pa-runbook/src/validator.mjs';
+import { readFileSync } from 'node:fs';
+
+const schema = JSON.parse(readFileSync('./schema/runbook.schema.json', 'utf8'));
+const runbook = JSON.parse(readFileSync('./reference/hq-dave.runbook.json', 'utf8'));
+const result = validate(schema, runbook);
+if (!result.valid) {
+  console.error(result.errors);
+}
+```
+
+Or from the CLI:
+
+```bash
+node -e "
+import('./src/validator.mjs').then(async ({validate}) => {
+  const {readFile} = await import('node:fs/promises');
+  const schema = JSON.parse(await readFile('./schema/runbook.schema.json','utf8'));
+  const rb = JSON.parse(await readFile('./reference/hq-dave.runbook.json','utf8'));
+  const r = validate(schema, rb);
+  console.log(r.valid ? 'VALID' : 'INVALID: ' + r.errors.join('; '));
+});
+"
+```
+
+## Tests
+
+```bash
+pnpm --filter @stravica-ai/engineering-pa-runbook test
+# or
+node --test 'test/**/*.test.mjs'
+```
+
+- `test/validator.test.mjs` — unit tests for the structural validator
+- `test/runbooks.test.mjs` — validates all 3 reference runbooks against the schema

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

@@ -0,0 +1,18 @@
+{
+  "name": "@stravica-ai/engineering-pa-runbook",
+  "version": "0.1.1",
+  "description": "Migration runbook JSON Schema, reference runbooks, and structural validator.",
+  "type": "module",
+  "main": "./src/validator.mjs",
+  "exports": {
+    ".": "./src/validator.mjs",
+    "./src/*": "./src/*"
+  },
+  "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."
+}