@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-workspace/src/ws.mjs

@@ -0,0 +1,633 @@
+#!/usr/bin/env node
+
+/**
+ * ws.mjs — Workspace server CLI
+ *
+ * Manages the workspace dev server (server.mjs) as a background process.
+ *
+ * Usage:
+ *   node ws.mjs start [--port N] [--no-open]   Start server as background daemon
+ *   node ws.mjs stop                            Stop the running server
+ *   node ws.mjs restart [--port N] [--no-open]  Stop then start
+ *   node ws.mjs status                          Show server status
+ *   node ws.mjs open                            Open browser to server URL
+ */
+
+import { spawn, execSync } from 'node:child_process';
+import { readFileSync, writeFileSync, unlinkSync, existsSync, statSync, realpathSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { platform } from 'node:os';
+import { get } from 'node:http';
+import {
+  detectSupervisor,
+  readSupervisorState,
+  findPortListener,
+  restartCommand,
+} from './supervisor.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, '..', '..', '..');
+
+const SERVER_SCRIPT = join(__dirname, 'server.mjs');
+// Env overrides let tests point at a temp directory so the real repo's
+// .ws.pid / .ws.log are never written to during the subprocess test runs.
+const PID_FILE = process.env.WS_PID_FILE || join(REPO_ROOT, '.ws.pid');
+const LOG_FILE = process.env.WS_LOG_FILE || join(REPO_ROOT, '.ws.log');
+const PREFS_FILE = join(REPO_ROOT, 'operator', 'config', 'preferences.json');
+
+// Test-only override: lets e2e tests assert cross-platform parity by forcing
+// the supervisor probe to behave as if it were running on a different OS.
+// Honours the same dependency-injection contract as detectSupervisor's
+// `platform` argument — when set, it is the *only* value the CLI passes
+// through, so the production code path (no env var) remains untouched.
+const PLATFORM_OVERRIDE = process.env.WORKSPACE_SUPERVISOR_PLATFORM_OVERRIDE || undefined;
+
+// Single-call helper so the override env var is honoured everywhere the
+// CLI asks "which supervisor manages this host?". Tests set the env var
+// when spawning the ws.mjs subprocess; production callers pass nothing and
+// detectSupervisor falls back to os.platform().
+function getSupervisor() {
+  return detectSupervisor(PLATFORM_OVERRIDE ? { platform: PLATFORM_OVERRIDE } : undefined);
+}
+
+// --- Arg parsing ---
+
+const args = process.argv.slice(2);
+const command = args[0];
+const flags = args.slice(1);
+
+function getFlag(name) {
+  const idx = flags.indexOf(name);
+  if (idx === -1) return undefined;
+  return flags[idx + 1];
+}
+
+function hasFlag(name) {
+  return flags.includes(name);
+}
+
+// --- Port resolution ---
+
+function resolvePort() {
+  // 1. Default
+  let port = 4200;
+
+  // 2. Preferences override
+  try {
+    const prefs = JSON.parse(readFileSync(PREFS_FILE, 'utf-8'));
+    if (prefs.workspacePort) port = prefs.workspacePort;
+  } catch { /* no prefs — use default */ }
+
+  // 3. CLI flag override
+  const flagPort = getFlag('--port');
+  if (flagPort) {
+    const parsed = parseInt(flagPort, 10);
+    if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+      console.error(`Error: Invalid port "${flagPort}". Must be 1-65535.`);
+      process.exit(1);
+    }
+    port = parsed;
+  }
+
+  return port;
+}
+
+// --- PID file helpers ---
+
+function readPid() {
+  try {
+    const raw = JSON.parse(readFileSync(PID_FILE, 'utf-8'));
+    return { pid: raw.pid, port: raw.port };
+  } catch {
+    return null;
+  }
+}
+
+function writePid(pid, port) {
+  writeFileSync(PID_FILE, JSON.stringify({ pid, port }, null, 2) + '\n');
+}
+
+function removePid() {
+  try { unlinkSync(PID_FILE); } catch { /* already gone */ }
+}
+
+// --- Process checks ---
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function checkPort(port, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const sock = createConnection({ host: '127.0.0.1', port }, () => {
+      sock.destroy();
+      resolve(true);
+    });
+    sock.on('error', () => resolve(false));
+    sock.setTimeout(timeoutMs, () => {
+      sock.destroy();
+      resolve(false);
+    });
+  });
+}
+
+// Best-effort: identify the PID currently listening on a port. Returns
+// { pid, command } or null if the information is unavailable (unsupported
+// platform, no listener, or the probe fails). Used for diagnostic output
+// when a stale pidfile collides with an unrelated port holder.
+function findPortHolder(port) {
+  try {
+    if (platform() === 'win32') {
+      const raw = execSync(`netstat -ano -p tcp | findstr :${port}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+      const line = raw.split(/\r?\n/).find((l) => l.includes('LISTENING'));
+      if (!line) return null;
+      const parts = line.trim().split(/\s+/);
+      const pid = parseInt(parts[parts.length - 1], 10);
+      if (!pid || Number.isNaN(pid)) return null;
+      return { pid, command: null };
+    }
+    const raw = execSync(`lsof -nP -iTCP:${port} -sTCP:LISTEN -Fpc`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+    const lines = raw.split(/\r?\n/).filter(Boolean);
+    let pid = null; let command = null;
+    for (const l of lines) {
+      if (l.startsWith('p')) pid = parseInt(l.slice(1), 10);
+      else if (l.startsWith('c')) command = l.slice(1);
+    }
+    if (!pid || Number.isNaN(pid)) return null;
+    return { pid, command };
+  } catch {
+    return null;
+  }
+}
+
+function httpCheck(port, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    const req = get(`http://127.0.0.1:${port}/`, { timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve(res.statusCode);
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+// --- Wait for port to become available ---
+
+function waitForPort(port, maxMs = 3000) {
+  const start = Date.now();
+  return new Promise((resolve) => {
+    const check = async () => {
+      if (await checkPort(port)) return resolve(true);
+      if (Date.now() - start > maxMs) return resolve(false);
+      setTimeout(check, 200);
+    };
+    check();
+  });
+}
+
+// --- Kill process ---
+
+async function killProcess(pid) {
+  const isWindows = platform() === 'win32';
+
+  if (!isProcessAlive(pid)) return true;
+
+  // Graceful shutdown
+  if (isWindows) {
+    try { execSync(`taskkill /PID ${pid}`, { stdio: 'ignore' }); } catch { /* ignore */ }
+  } else {
+    try { process.kill(pid, 'SIGTERM'); } catch { /* ignore */ }
+  }
+
+  // Wait up to 5s for graceful exit
+  const start = Date.now();
+  while (Date.now() - start < 5000) {
+    if (!isProcessAlive(pid)) return true;
+    await new Promise(r => setTimeout(r, 200));
+  }
+
+  // Force kill
+  if (isProcessAlive(pid)) {
+    if (isWindows) {
+      try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore' }); } catch { /* ignore */ }
+    } else {
+      try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ }
+    }
+    // Brief wait for force kill
+    await new Promise(r => setTimeout(r, 500));
+  }
+
+  return !isProcessAlive(pid);
+}
+
+// --- Open browser ---
+
+function openBrowser(url) {
+  const plat = platform();
+  try {
+    if (plat === 'darwin') {
+      execSync(`open "${url}"`);
+    } else if (plat === 'win32') {
+      execSync(`start "" "${url}"`);
+    } else {
+      execSync(`xdg-open "${url}"`);
+    }
+  } catch {
+    console.error('Could not open browser automatically. Visit: ' + url);
+  }
+}
+
+// --- Uptime formatting ---
+
+function formatUptime(ms) {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  return `${h}h ${m % 60}m`;
+}
+
+// --- Commands ---
+
+async function cmdStart() {
+  const port = resolvePort();
+  const noOpen = hasFlag('--no-open');
+
+  // Supervisor-aware short-circuit. When launchd / systemd is managing the
+  // workspace, ws.mjs MUST NOT spawn a competing process — KeepAlive /
+  // Restart=always would otherwise hand the port back to the supervised
+  // instance and ours would lose the bind race. Friendly exit-0 if the
+  // supervised process is up; helpful message if it's not, telling the
+  // operator how to bounce it.
+  const supervisor = getSupervisor();
+  if (supervisor.kind) {
+    const sup = readSupervisorState(supervisor);
+    if (sup.state === 'running' && sup.pid) {
+      const url = `http://127.0.0.1:${port}`;
+      console.log(`Workspace server already running (supervised by ${supervisor.kind}, PID ${sup.pid}).`);
+      console.log(`  ${url}`);
+      if (!noOpen) openBrowser(url);
+      process.exit(0);
+    }
+    // Supervisor configured but not currently running. Don't spawn a
+    // detached one — that would race the supervisor's next relaunch.
+    // Tell the operator how to bring it up via the supervisor.
+    const restartCmd = restartCommand(supervisor);
+    console.error(`Error: Workspace is ${supervisor.kind}-managed at ${supervisor.unitPath} but is not currently running.`);
+    if (restartCmd) console.error(`  Bring it up with: ${restartCmd}`);
+    if (supervisor.kind === 'launchd') {
+      console.error(`  Or reload the plist: launchctl load -w ${supervisor.unitPath}`);
+    } else if (supervisor.kind === 'systemd') {
+      console.error(`  Or start the unit: systemctl --user start ${supervisor.label}`);
+    }
+    process.exit(2);
+  }
+
+  // Check if already running
+  const existing = readPid();
+  if (existing && isProcessAlive(existing.pid)) {
+    const portUp = await checkPort(existing.port);
+    if (portUp) {
+      console.log(`Workspace server already running (PID ${existing.pid}, port ${existing.port}).`);
+      console.log(`  http://127.0.0.1:${existing.port}`);
+      process.exit(0);
+    }
+    // Process alive but port not listening — stale state, clean up
+    await killProcess(existing.pid);
+    removePid();
+  } else if (existing) {
+    // PID file exists but process is dead. Before deleting the pidfile, check
+    // whether the port it claims is actually held by something unrelated — if
+    // so, surface a diagnostic and stop. We MUST NOT kill an unrelated holder.
+    if (existing.port && await checkPort(existing.port)) {
+      const holder = findPortHolder(existing.port);
+      const who = holder ? ` (held by PID ${holder.pid}${holder.command ? ` — ${holder.command}` : ''})` : '';
+      console.error(`Error: Stale PID file references dead PID ${existing.pid}, but port ${existing.port} is in use${who}.`);
+      console.error('Refusing to kill an unrelated process. Remove the PID file manually or use a different port.');
+      process.exit(1);
+    }
+    removePid();
+  }
+
+  // Check if port is already in use by something else
+  if (await checkPort(port)) {
+    console.error(`Error: Port ${port} is already in use by another process.`);
+    process.exit(1);
+  }
+
+  // Build spawn args
+  const serverArgs = ['--no-timeout'];
+  serverArgs.push('--port', String(port));
+  serverArgs.push('--no-open'); // CLI handles browser open, not server
+
+  // Open log file for stdout/stderr
+  const { openSync, close } = await import('node:fs');
+  const logFd = openSync(LOG_FILE, 'w');
+
+  // Spawn detached
+  const child = spawn(process.execPath, [SERVER_SCRIPT, ...serverArgs], {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    cwd: REPO_ROOT,
+  });
+
+  child.unref();
+  close(logFd);
+
+  const pid = child.pid;
+  writePid(pid, port);
+
+  // Wait for the port to come up
+  const ready = await waitForPort(port, 3000);
+
+  if (!ready) {
+    // Check if process died (e.g. port conflict detected by server itself)
+    if (!isProcessAlive(pid)) {
+      removePid();
+      // Try to read log for clues
+      try {
+        const log = readFileSync(LOG_FILE, 'utf-8').trim();
+        if (log) console.error('Server output:\n' + log);
+      } catch { /* ignore */ }
+      console.error('Error: Server failed to start. Check .ws.log for details.');
+      process.exit(1);
+    }
+    console.warn('Warning: Server started but port not yet responding. It may still be initialising.');
+  }
+
+  const url = `http://127.0.0.1:${port}`;
+  console.log(`Workspace server started (PID ${pid}).`);
+  console.log(`  ${url}`);
+  console.log(`  Log: ${LOG_FILE}`);
+
+  if (!noOpen) {
+    openBrowser(url);
+  }
+}
+
+async function cmdStop() {
+  // Supervisor-aware refusal. Killing a supervised process triggers an
+  // instant relaunch via KeepAlive / Restart=always — `stop` is a no-op at
+  // best and a confusing port-conflict at worst. Refuse and point the
+  // operator at the right tool.
+  const supervisor = getSupervisor();
+  if (supervisor.kind) {
+    console.error(`Error: Workspace is ${supervisor.kind}-managed at ${supervisor.unitPath}.`);
+    if (supervisor.kind === 'launchd') {
+      console.error(`  To stop it: launchctl unload -w ${supervisor.unitPath}`);
+    } else {
+      console.error(`  To stop it: systemctl --user stop ${supervisor.label}`);
+    }
+    console.error('  To bounce it for in-place version pickup: ws.mjs restart');
+    process.exit(1);
+  }
+
+  const existing = readPid();
+  if (!existing) {
+    console.log('Workspace server is not running (no PID file).');
+    process.exit(0);
+  }
+
+  if (!isProcessAlive(existing.pid)) {
+    console.log('Workspace server is not running (PID ' + existing.pid + ' is dead). Cleaning up.');
+    removePid();
+    process.exit(0);
+  }
+
+  console.log(`Stopping workspace server (PID ${existing.pid})...`);
+  const killed = await killProcess(existing.pid);
+  removePid();
+
+  if (killed) {
+    console.log('Server stopped.');
+  } else {
+    console.error('Warning: Could not confirm process termination. PID file cleaned up.');
+  }
+}
+
+async function cmdRestart() {
+  // Supervisor-aware restart. Under launchd / systemd we ask the supervisor
+  // to bounce the service — `launchctl kickstart -k` and
+  // `systemctl --user restart` are both KeepAlive-safe and idempotent.
+  // Under no supervisor we fall back to the legacy stop-then-start dance.
+  const supervisor = getSupervisor();
+  if (supervisor.kind) {
+    const cmd = restartCommand(supervisor);
+    if (!cmd) {
+      console.error(`Error: Could not build restart command for ${supervisor.kind}.`);
+      process.exit(2);
+    }
+    try {
+      execSync(cmd, { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      console.error(`Error: Supervisor restart failed: ${err.message || err}`);
+      process.exit(3);
+    }
+    // Re-read state so we can report the new PID.
+    const sup = readSupervisorState(supervisor);
+    if (sup.pid) {
+      console.log(`Workspace server restarted (supervised by ${supervisor.kind}, PID ${sup.pid}).`);
+    } else {
+      // launchctl kickstart -k can return before the new PID is published.
+      console.log(`Workspace server restart requested (supervised by ${supervisor.kind}).`);
+    }
+    const port = resolvePort();
+    console.log(`  http://127.0.0.1:${port}`);
+    return;
+  }
+  await cmdStop();
+  await cmdStart();
+}
+
+async function cmdStatus() {
+  const supervisor = getSupervisor();
+
+  // Supervisor-aware status. When a unit file is installed, the supervisor
+  // is the source of truth — the legacy pidfile is only written when ws.mjs
+  // itself spawned the server, so a supervised process is invisible to the
+  // pidfile-only check (bug 1 of 2 in this PR).
+  if (supervisor.kind) {
+    const port = resolvePort();
+    const sup = readSupervisorState(supervisor);
+    const listener = findPortListener(port);
+    const portUp = await checkPort(port);
+    const httpStatus = portUp ? await httpCheck(port) : null;
+
+    const running = sup.state === 'running' || portUp;
+    console.log(`Status: ${running ? 'running' : (sup.state === 'loaded' ? 'loaded (not running)' : 'stopped')} (supervised by ${supervisor.kind})`);
+    console.log(`  Supervisor: ${supervisor.kind} — ${supervisor.unitPath}`);
+    console.log(`  State:      ${sup.state}`);
+    if (sup.pid) console.log(`  PID:        ${sup.pid}`);
+    console.log(`  Port:       ${port}`);
+    if (listener) {
+      const cmdName = listener.command ? ` (${listener.command})` : '';
+      console.log(`  Listener:   PID ${listener.pid}${cmdName}`);
+      if (sup.pid && listener.pid !== sup.pid) {
+        console.log('  Warning:    port listener PID differs from supervised PID — another process is on this port.');
+      }
+    } else if (portUp) {
+      console.log('  Listener:   port held (lsof/ss unavailable to identify PID)');
+    } else {
+      console.log('  Listener:   none');
+    }
+    console.log(`  URL:        http://127.0.0.1:${port}`);
+    if (portUp && httpStatus !== null) {
+      console.log(`  Health:     OK (HTTP ${httpStatus})`);
+    } else if (portUp) {
+      console.log('  Health:     port open, HTTP check failed');
+    } else {
+      console.log('  Health:     port not responding');
+    }
+    process.exit(running ? 0 : 2);
+  }
+
+  // Legacy pidfile-managed status (no supervisor installed).
+  const existing = readPid();
+
+  if (!existing) {
+    console.log('Status: stopped');
+    console.log('  No PID file found.');
+    process.exit(0);
+  }
+
+  const alive = isProcessAlive(existing.pid);
+  if (!alive) {
+    console.log('Status: stopped (stale PID file)');
+    console.log(`  PID ${existing.pid} is no longer running.`);
+    removePid();
+    process.exit(0);
+  }
+
+  // Uptime from PID file mtime
+  let uptime = '';
+  try {
+    const pidStat = statSync(PID_FILE);
+    const ms = Date.now() - pidStat.mtimeMs;
+    uptime = formatUptime(ms);
+  } catch { /* ignore */ }
+
+  const portUp = await checkPort(existing.port);
+  let httpStatus = null;
+  if (portUp) {
+    httpStatus = await httpCheck(existing.port);
+  }
+
+  console.log('Status: running');
+  console.log(`  PID:    ${existing.pid}`);
+  console.log(`  Port:   ${existing.port}`);
+  if (uptime) console.log(`  Uptime: ${uptime}`);
+  console.log(`  URL:    http://127.0.0.1:${existing.port}`);
+  if (portUp && httpStatus !== null) {
+    console.log(`  Health: OK (HTTP ${httpStatus})`);
+  } else if (portUp) {
+    console.log('  Health: port open, HTTP check failed');
+  } else {
+    console.log('  Health: port not responding');
+  }
+}
+
+async function cmdOpen() {
+  // Supervisor-aware open. Under launchd/systemd there is no pidfile, so
+  // we resolve the port via the standard preference chain and probe the
+  // socket directly.
+  const supervisor = getSupervisor();
+  if (supervisor.kind) {
+    const port = resolvePort();
+    const portUp = await checkPort(port);
+    if (!portUp) {
+      console.error(`Error: Workspace is ${supervisor.kind}-managed but port ${port} is not responding.`);
+      const cmd = restartCommand(supervisor);
+      if (cmd) console.error(`  Try: ${cmd}`);
+      process.exit(2);
+    }
+    const url = `http://127.0.0.1:${port}`;
+    console.log('Opening ' + url);
+    openBrowser(url);
+    return;
+  }
+
+  const existing = readPid();
+
+  if (!existing || !isProcessAlive(existing.pid)) {
+    console.error('Error: Workspace server is not running. Start it first: node ws.mjs start');
+    process.exit(1);
+  }
+
+  const portUp = await checkPort(existing.port);
+  if (!portUp) {
+    console.error('Error: Server process exists but port ' + existing.port + ' is not responding.');
+    process.exit(1);
+  }
+
+  const url = `http://127.0.0.1:${existing.port}`;
+  console.log('Opening ' + url);
+  openBrowser(url);
+}
+
+// --- Exports for tests ---
+// Helpers are exported so test.mjs can exercise them without shelling out.
+// Importing this module must not trigger CLI dispatch — the entrypoint guard
+// below ensures the switch only runs when ws.mjs is invoked directly.
+export { isProcessAlive, checkPort, findPortHolder };
+
+// --- Main ---
+
+const USAGE = `Usage: node ws.mjs <command> [options]
+
+Commands:
+  start   [--port N] [--no-open]   Start workspace server
+  stop                              Stop workspace server
+  restart [--port N] [--no-open]   Restart workspace server
+  status                            Show server status
+  open                              Open browser to server URL`;
+
+// Only dispatch the CLI when this file is the entrypoint. When imported as a
+// module (e.g. by tests that pull in exported helpers), skip the switch so
+// the importing process is not terminated by the default-case process.exit.
+//
+// ISMAIN-AUDIT (bug-3 sweep): the previous check compared import.meta.url
+// (always realpath-resolved by Node) against `pathToFileURL(argv[1])`
+// with NO symlink resolution on the argv[1] side — same class of
+// fragility as the endsWith idiom fixed in the scheduler. It also threw
+// outright if argv[1] was undefined. `pa workspace <verb>`'s fallback
+// path spawns this file via an explicit absolute path (not a pnpm .bin
+// symlink), so this has not been proven to misfire in production, but is
+// fixed defensively to the same realpath-both-sides pattern used
+// elsewhere (and already correct in server.mjs / install-daemon.mjs in
+// this same package).
+function isDirectlyInvoked() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectlyInvoked()) {
+  switch (command) {
+    case 'start':   await cmdStart(); break;
+    case 'stop':    await cmdStop(); break;
+    case 'restart': await cmdRestart(); break;
+    case 'status':  await cmdStatus(); break;
+    case 'open':    await cmdOpen(); break;
+    case '--help':
+    case '-h':
+    case 'help':
+      console.log(USAGE);
+      process.exit(0);
+    default:
+      if (command) console.error(`Unknown command: ${command}\n`);
+      console.log(USAGE);
+      process.exit(command ? 1 : 0);
+  }
+}

package/index.mjs

@@ -0,0 +1,60 @@
+// @stravica-ai/digital-operator-pa — public package surface.
+//
+// Single-bundled wrapper for the engineering-pa platform (approach A2 — see
+// ./README.md and build.mjs). The wrapper ships ONE tarball that contains
+// the wrapper code plus a `dist/` tree of the internal workspace packages
+// with `@stravica-ai/engineering-pa-*` imports rewritten to relative paths.
+//
+// Operators install one package, pin one version. Internals stay
+// `private: true` in the monorepo and are not individually publishable.
+
+export const name = '@stravica-ai/digital-operator-pa';
+export const version = '0.1.1';
+
+// Bin entry points exposed by the wrapper (mirrors package.json#bin).
+// Programmatic consumers normally spawn the bins; this list is for
+// introspection / scaffolders.
+export const bins = [
+  'pa',
+  'desk',
+  'launch',
+  'sync',
+  'secrets',
+  'scheduler',
+  'smoke',
+  'distill',
+  'memory-sync',
+  'migrate-inspect',
+  'pa-init',
+  'slice',
+  'research',
+  'pa-coordinator-hook',
+];
+
+// Bundled internal packages (mirrors build.mjs PACKAGES catalog).
+// Useful for debugging install layouts.
+export const bundled = [
+  '@stravica-ai/engineering-pa-core',
+  '@stravica-ai/engineering-pa-runbook',
+  '@stravica-ai/engineering-pa-cli',
+  '@stravica-ai/engineering-pa-migrate-inspect',
+  '@stravica-ai/engineering-pa-workspace',
+  '@stravica-ai/engineering-pa-scaffold',
+  '@stravica-ai/engineering-pa-librarian',
+  '@stravica-ai/engineering-pa-types-engineering',
+  '@stravica-ai/engineering-pa-core-extensions-atlassian',
+  '@stravica-ai/engineering-pa-core-extensions-n8n',
+];
+
+/**
+ * Returns a metadata snapshot describing this installed wrapper. Useful for
+ * `pa status` and operator-side install verification.
+ */
+export function describe() {
+  return {
+    name,
+    version,
+    bins,
+    bundled,
+  };
+}