@stravica-ai/digital-operator-pa 0.1.0

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

@@ -0,0 +1,199 @@
+// checks.mjs — domain definitions for the smoke suite.
+import { PA_PACKAGE_NAME } from '../../../engineering-pa-core/src/config/pa-package-name.mjs';
+
+//
+// v2: the smoke suite validates a v2 operator-instance layout. There are
+// two distinct shapes the operator repo can be in, each with different
+// expectations:
+//
+//   • fresh-scaffold — the post-`pa-init --mode=solo` shape. Operator
+//     content is empty except for `.gitkeep` markers; node_modules is
+//     present from `pnpm install`. This mode is exercised when an
+//     operator first stands up the platform on a new host.
+//
+//   • live-repo — a populated operator repo with real work items,
+//     projects, profile content, etc. The `.gitkeep` markers may have
+//     been removed once real files exist in each directory. This is
+//     the day-to-day operator-machine shape.
+//
+// Mode selection is plumbed in cli.mjs (`--mode=fresh-scaffold|live-repo`,
+// default `live-repo`). Each mode builds its own check plan via
+// `buildCheckPlan(mode)`.
+//
+// Check classes:
+//
+//   path           — path exists (file or dir)
+//   dirExists      — directory exists (alias of path for clarity)
+//   dirNotEmpty    — directory exists AND contains at least one entry
+//   pkgInstalled   — node_modules/@stravica-ai/digital-operator-pa* present
+//   serverReady    — workspace server started on port N
+//   httpStatus     — GET url returns a specific status code
+//   jsonValid      — GET url returns parseable JSON
+//   cliExit        — running `<bin> --help` exits 0
+//   vaultExit      — `secrets` exits 0 or 1 (no vault yet is fine)
+
+/**
+ * Fresh-scaffold paths verified on disk. These are the v2 operator-instance
+ * shape produced by `pa-init --mode=solo`, with `.gitkeep` markers in every
+ * directory before the operator has populated them. Paths are
+ * operator-tree-relative.
+ */
+export const EXPECTED_PATHS_FRESH_SCAFFOLD = [
+  // Operator content scaffold.
+  'operator/.gitkeep',
+  'operator/profile/.gitkeep',
+  'operator/knowledge/.gitkeep',
+  'operator/notes/.gitkeep',
+  'operator/extensions/.gitkeep',
+  // Work and projects.
+  'work/.gitkeep',
+  'projects/.gitkeep',
+  // Schedules (gitkept folder, individual schedules created on demand).
+  'schedules/.gitkeep',
+  // Root files an operator repo always carries.
+  'CLAUDE.md',
+  'package.json',
+  '.gitignore',
+];
+
+/**
+ * Backwards-compat alias — pre-v0.1.3 callers and tests reference
+ * EXPECTED_PATHS. Keep the alias pointing at the fresh-scaffold list since
+ * that's the shape the existing tests exercise.
+ */
+export const EXPECTED_PATHS = EXPECTED_PATHS_FRESH_SCAFFOLD;
+
+/**
+ * Live-repo paths verified on disk. Same operator scaffold but expressed as
+ * directories (not `.gitkeep` markers) — operator activity may have removed
+ * the markers once real files arrived. The root files are unchanged.
+ */
+export const EXPECTED_PATHS_LIVE_REPO_DIRS = [
+  'operator',
+  'operator/profile',
+  'operator/knowledge',
+  'operator/notes',
+  'operator/extensions',
+  'work',
+  'projects',
+  'schedules',
+];
+
+export const EXPECTED_PATHS_LIVE_REPO_FILES = [
+  'CLAUDE.md',
+  'package.json',
+  '.gitignore',
+];
+
+/**
+ * Bundled package install paths verified on disk. These point inside
+ * node_modules — the package is read-only on the operator's machine.
+ */
+export const EXPECTED_PACKAGE_PATHS = [
+  `node_modules/${PA_PACKAGE_NAME}/package.json`,
+];
+
+/** HTML pages verified over HTTP. Labels mirror the operator UX. */
+export const HTML_PAGES = [
+  { label: '/ (shell)',                                   path: '/' },
+  { label: '/home.html',                                  path: '/home.html' },
+  { label: '/onboarding.html',                            path: '/onboarding.html' },
+  { label: '/tasks.html',                                 path: '/tasks.html' },
+  { label: '/knowledge.html',                             path: '/knowledge.html' },
+  { label: '/secrets.html',                               path: '/secrets.html' },
+  { label: '/viewer.html',                                path: '/viewer.html' },
+];
+
+/** JSON API endpoints exercised by the smoke suite. */
+export const API_ENDPOINTS = [
+  '/__api/overview',
+  '/__api/projects',
+  '/__api/work',
+];
+
+/**
+ * CLI --help invocations. In v2 these are installed bin shims; the smoke
+ * runner resolves them via `node_modules/.bin/<name>` rather than absolute
+ * repo paths.
+ */
+export const CLI_HELP_TOOLS = [
+  { name: 'desk --help',        binName: 'desk' },
+  { name: 'distill --help',     binName: 'distill' },
+  { name: 'memory-sync --help', binName: 'memory-sync' },
+  { name: 'sync --help',        binName: 'sync' },
+  { name: 'scheduler --help',   binName: 'scheduler' },
+  { name: 'pa --help',          binName: 'pa' },
+  { name: 'slice --help',       binName: 'slice' },
+];
+
+/** Test port for the workspace server. */
+export const TEST_PORT = 4201;
+
+/**
+ * Build the complete check plan. Returns an array of check descriptors in
+ * a stable order:
+ *
+ *   1. Operator-content paths
+ *   2. Package install paths
+ *   3. Server boot
+ *   4. HTML pages (gated on server)
+ *   5. JSON endpoints (gated on server)
+ *   6. CLI --help (one per bin shim)
+ *   7. Secrets exit-code probe
+ *
+ * @param {object} [opts]
+ * @param {'fresh-scaffold'|'live-repo'} [opts.mode] — defaults to fresh-scaffold
+ *   for backwards compatibility with v0.1.2-era callers and tests. The
+ *   CLI defaults to 'live-repo' for operator-machine usage.
+ */
+export function buildCheckPlan(opts = {}) {
+  const mode = opts.mode ?? 'fresh-scaffold';
+  const plan = [];
+
+  if (mode === 'live-repo') {
+    // In live-repo mode, directories must exist (any contents OK) and root
+    // files must exist. We never assert on `.gitkeep` markers because real
+    // operator content may have evicted them.
+    for (const p of EXPECTED_PATHS_LIVE_REPO_DIRS) {
+      plan.push({ id: `path-${p}`, class: 'path', path: p, label: `directory exists: ${p}` });
+    }
+    for (const p of EXPECTED_PATHS_LIVE_REPO_FILES) {
+      plan.push({ id: `path-${p}`, class: 'path', path: p, label: `path exists: ${p}` });
+    }
+  } else {
+    // fresh-scaffold (default for backwards compat).
+    for (const p of EXPECTED_PATHS_FRESH_SCAFFOLD) {
+      plan.push({ id: `path-${p}`, class: 'path', path: p, label: `path exists: ${p}` });
+    }
+  }
+
+  for (const p of EXPECTED_PACKAGE_PATHS) {
+    plan.push({ id: `pkg-${p}`, class: 'pkgInstalled', path: p, label: `package installed: ${p}` });
+  }
+
+  plan.push({ id: 'server-ready', class: 'serverReady', port: TEST_PORT, label: `workspace server started on port ${TEST_PORT}` });
+
+  for (const page of HTML_PAGES) {
+    plan.push({ id: `http-${page.path}`, class: 'httpStatus', path: page.path, expect: 200, label: `HTTP 200: ${page.label}`, requires: 'server' });
+  }
+
+  for (const ep of API_ENDPOINTS) {
+    plan.push({ id: `json-${ep}`, class: 'jsonValid', path: ep, label: `valid JSON: ${ep}`, requires: 'server' });
+  }
+
+  for (const tool of CLI_HELP_TOOLS) {
+    plan.push({ id: `cli-${tool.binName}`, class: 'cliExit', binName: tool.binName, label: `CLI exits 0: ${tool.name}` });
+  }
+
+  plan.push({ id: 'vault', class: 'vaultExit', binName: 'secrets', label: 'secrets runs' });
+
+  return plan;
+}
+
+/**
+ * Render the full JSON-endpoint URL for a given port and path.
+ * Centralised here so checks and tests see the same construction.
+ */
+export function apiUrl(port, path) {
+  return `http://localhost:${port}${path}`;
+}

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

@@ -0,0 +1,108 @@
+// cli.mjs — arg parsing, exit-code translation, usage.
+//
+// The smoke tool has a single default verb: run. It is invoked via
+// `npm run test:smoke` which resolves to `node core/tools/smoke/bin/smoke`.
+//
+// Exit codes (see README §Exit codes):
+//   0  all checks passed
+//   1  one or more checks failed
+//   2  internal error (uncaught exception)
+//   3  IO / transport failure during setup (tempdir, copy, server spawn)
+
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { PA_PACKAGE_NAME } from '../../../engineering-pa-core/src/config/pa-package-name.mjs';
+import { runSmoke } from './commands/run.mjs';
+
+const USAGE = `
+smoke — operator-instance smoke suite for the v2 platform
+
+Usage:
+  smoke                          Run the live-repo suite against the auto-detected root
+  smoke --mode <mode>            'live-repo' (default) or 'fresh-scaffold'
+  smoke --root <path>            Repo root (default: auto-detect)
+  smoke --port <n>               HTTP port for the workspace server (default: 4201)
+  smoke -h, --help               Show this help
+
+Modes:
+  live-repo       Probe a populated operator repo in-place — no tempdir copy.
+                  Asserts that operator/ subdirs exist (any contents), required
+                  root files are present, the installed ${PA_PACKAGE_NAME}
+                  package is reachable, the workspace server starts, the API
+                  responds, and every published bin shim returns exit 0 on --help.
+
+  fresh-scaffold  Verify the layout produced by 'pa-init --mode=solo' on a
+                  freshly-scaffolded operator repo. Asserts the .gitkeep
+                  markers, root files, the installed package, and the same
+                  HTTP/CLI surfaces. Copies the source tree into a tempdir
+                  to keep the original untouched.
+
+Exit codes:
+  0  all checks passed
+  1  one or more checks failed
+  2  internal error
+  3  IO / transport failure (tempdir, copy, server launch)
+`;
+
+const VALID_MODES = new Set(['live-repo', 'fresh-scaffold']);
+
+export async function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        help: { type: 'boolean', short: 'h' },
+        root: { type: 'string' },
+        port: { type: 'string' },
+        mode: { type: 'string' },
+      },
+      strict: true,
+      allowPositionals: false,
+    });
+  } catch (err) {
+    console.error(`smoke: ${err.message}`);
+    console.error('Run `smoke --help` for usage.');
+    return 1;
+  }
+
+  if (parsed.values.help) {
+    console.log(USAGE.trim());
+    return 0;
+  }
+
+  const mode = parsed.values.mode ?? 'live-repo';
+  if (!VALID_MODES.has(mode)) {
+    console.error(`smoke: invalid --mode value: ${mode}. Must be one of: ${[...VALID_MODES].join(', ')}`);
+    return 1;
+  }
+
+  const repoRoot = parsed.values.root
+    ? resolve(parsed.values.root)
+    : autoDetectRepoRoot();
+
+  const port = parsed.values.port ? Number(parsed.values.port) : undefined;
+  if (port != null && (!Number.isInteger(port) || port <= 0 || port > 65535)) {
+    console.error(`smoke: invalid port: ${parsed.values.port}`);
+    return 1;
+  }
+
+  try {
+    const result = await runSmoke(repoRoot, { port, mode });
+    return result.exitCode;
+  } catch (err) {
+    console.error(`smoke: ${err.message || err}`);
+    return 3;
+  }
+}
+
+/**
+ * Auto-detect the repo root. The binary lives at
+ * `<root>/core/tools/smoke/bin/smoke`, so the root is four levels up
+ * from this module.
+ */
+function autoDetectRepoRoot() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '..', '..', '..', '..');
+}

package/dist/engineering-pa-cli/src/smoke/commands/run.mjs

@@ -0,0 +1,237 @@
+// commands/run.mjs — orchestrate the full smoke suite.
+//
+// Flow (mirrors test/smoke.sh):
+//   1. mktemp and copy the repo (excluding .git, node_modules)
+//   2. cd (conceptually) into the temp dir
+//   3. Run path checks
+//   4. Launch the workspace server, wait for ready
+//   5. Run HTTP / JSON checks (gated on ready)
+//   6. Run CLI --help checks
+//   7. Run secrets check
+//   8. Run dave.sh --help check
+//   9. Cleanup (kill server, remove temp dir)
+//  10. Print PASS/FAIL lines and summary, return exit code
+
+import { resolve as pathResolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  spawnProcess,
+  launchProcess,
+  killProcess,
+  makeTempDir,
+  removeDir,
+  copyTree,
+  pathExists,
+  pathExecutable,
+  waitForHttp,
+  httpGet,
+} from '../runner.mjs';
+import { PA_PACKAGE_NAME } from '../../../../engineering-pa-core/src/config/pa-package-name.mjs';
+import { buildCheckPlan, apiUrl, TEST_PORT } from '../checks.mjs';
+
+/**
+ * Run the full smoke suite against `repoRoot`.
+ * Returns { pass, fail, results, exitCode }.
+ *
+ * `opts.runner` (optional) injects a fake for unit tests.
+ * `opts.mode`   ('live-repo' | 'fresh-scaffold') — default 'fresh-scaffold'
+ *   to preserve the pre-v0.1.3 calling convention (the CLI overrides to
+ *   'live-repo'). Live-repo mode runs against the source root in-place
+ *   (no tempdir copy) because copying excludes node_modules and breaks
+ *   every CLI/cliExit probe against the destination.
+ */
+export async function runSmoke(repoRoot, opts = {}) {
+  const log = opts.log ?? ((line) => console.log(line));
+  const io = opts.runner ?? defaultRunner();
+  const port = opts.port ?? TEST_PORT;
+  const mode = opts.mode ?? 'fresh-scaffold';
+
+  const absRoot = pathResolve(repoRoot);
+  // Live-repo runs in-place; fresh-scaffold copies into a tempdir.
+  const useTempDir = mode !== 'live-repo';
+  const tempDir = useTempDir ? await io.makeTempDir() : null;
+  const workRoot = useTempDir ? tempDir : absRoot;
+  let serverChild = null;
+  const results = [];
+
+  try {
+    if (useTempDir) {
+      await io.copyTree(absRoot, tempDir);
+    }
+
+    const plan = buildCheckPlan({ mode });
+    let serverReady = false;
+
+    for (const check of plan) {
+      // Lazy-launch the server the first time we hit a server-ready check.
+      if (check.class === 'serverReady') {
+        serverChild = io.launchWorkspace(workRoot, port);
+        const url = apiUrl(port, '/');
+        serverReady = await io.waitForHttp(url);
+        results.push(record(check, serverReady));
+        log(line(check, serverReady));
+        continue;
+      }
+
+      // HTTP / JSON checks are skipped if the server never came up.
+      if (check.requires === 'server' && !serverReady) {
+        continue;
+      }
+
+      const ok = await runCheck(check, workRoot, port, io);
+      results.push(record(check, ok));
+      log(line(check, ok));
+    }
+
+    const pass = results.filter((r) => r.ok).length;
+    const fail = results.filter((r) => !r.ok).length;
+    const total = pass + fail;
+
+    log('');
+    log('========================================');
+    log(`${pass}/${total} passed`);
+    if (fail > 0) {
+      log(`${fail} test(s) failed`);
+      return { pass, fail, results, exitCode: 1 };
+    }
+    log('All tests passed');
+    return { pass, fail, results, exitCode: 0 };
+  } finally {
+    if (serverChild) await io.killProcess(serverChild);
+    if (useTempDir) await io.removeDir(tempDir);
+  }
+}
+
+/**
+ * Execute a single check. Returns a boolean pass/fail.
+ */
+async function runCheck(check, root, port, io) {
+  switch (check.class) {
+    case 'execFile':
+      return io.pathExecutable(pathJoin(root, check.path));
+
+    case 'file':
+    case 'path':
+      return io.pathExists(pathJoin(root, check.path));
+
+    case 'httpStatus': {
+      const res = await io.httpGet(apiUrl(port, check.path));
+      return res.status === check.expect;
+    }
+
+    case 'jsonValid': {
+      const res = await io.httpGet(apiUrl(port, check.path));
+      try { JSON.parse(res.body); return true; } catch { return false; }
+    }
+
+    case 'cliExit': {
+      // v2: invoke via the installed bin shim. Under pnpm's hoisted layout
+      // there is no `node_modules/.bin/<name>` symlink adjacent to the
+      // operator-repo root (the .bin lives off the @stravica-ai/digital-operator-pa
+      // package's own node_modules, not the operator repo's). Resolve to the
+      // package's `bin/<name>` shim instead — that is the canonical entry
+      // point for published commands.
+      const bin = await resolveBin(root, check.binName, io);
+      if (!bin) return false;
+      const res = await io.spawnProcess(bin, ['--help'], { cwd: root, timeoutMs: 15000 });
+      return res.code === 0;
+    }
+
+    case 'vaultExit': {
+      const bin = await resolveBin(root, check.binName ?? 'secrets', io);
+      if (!bin) return false;
+      const res = await io.spawnProcess(bin, [], { cwd: root, timeoutMs: 15000 });
+      return res.code === 0 || res.code === 1;
+    }
+
+    case 'pkgInstalled':
+      return io.pathExists(pathJoin(root, check.path));
+
+    case 'cliShell': {
+      // v1-compat — no v2 check uses this class but the runner remains
+      // backwards-compatible for operator-extension smoke suites that
+      // drop in their own check sets.
+      const res = await io.spawnProcess('bash', [check.path, '--help'], { cwd: root, timeoutMs: 15000 });
+      return res.code === 0;
+    }
+
+    default:
+      throw new Error(`smoke: unknown check class: ${check.class}`);
+  }
+}
+
+function record(check, ok) {
+  return { id: check.id, class: check.class, label: check.label, ok };
+}
+
+function line(check, ok) {
+  return `${ok ? 'PASS' : 'FAIL'}: ${check.label}`;
+}
+
+function pathJoin(root, p) {
+  return `${root}/${p}`;
+}
+
+/**
+ * Resolve a published bin shim for a given command. We try, in order:
+ *
+ *   1. node_modules/@stravica-ai/digital-operator-pa/bin/<name>  — canonical v2 path
+ *   2. node_modules/.bin/<name>                          — pnpm-symlinked
+ *
+ * Returns the first absolute path that exists, or null if neither does.
+ * The lookup uses the injected runner so tests can fake it without
+ * touching disk.
+ */
+async function resolveBin(root, name, io) {
+  const candidates = [
+    pathJoin(root, `node_modules/${PA_PACKAGE_NAME}/bin/${name}`),
+    pathJoin(root, `node_modules/.bin/${name}`),
+  ];
+  for (const candidate of candidates) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await io.pathExists(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Default runner — the production chokepoint bindings. Tests pass their
+ * own object matching this shape to avoid touching the filesystem / network.
+ */
+function defaultRunner() {
+  return {
+    makeTempDir,
+    removeDir,
+    copyTree,
+    pathExists,
+    pathExecutable,
+    waitForHttp,
+    httpGet,
+    spawnProcess,
+    killProcess,
+    launchWorkspace(cwd, port) {
+      // The workspace server lives in different places depending on
+      // install layout. In the published @stravica-ai/digital-operator-pa bundle
+      // it lives under `node_modules/@stravica-ai/digital-operator-pa/dist/
+      // engineering-pa-workspace/src/server.mjs`. In the dev monorepo
+      // (or any layout where workspace is installed as a separate
+      // package), it's at `node_modules/@stravica-ai/engineering-pa-workspace/
+      // src/server.mjs`. Try the bundled path first because that's the
+      // canonical operator-machine layout.
+      //
+      // Operators don't run server.mjs directly — the `pa workspace start`
+      // bin shim handles supervision in production — but the smoke suite
+      // bypasses that to keep the child PID easy to reap.
+      const candidates = [
+        `node_modules/${PA_PACKAGE_NAME}/dist/engineering-pa-workspace/src/server.mjs`,
+        'node_modules/@stravica-ai/engineering-pa-workspace/src/server.mjs',
+      ];
+      const serverScript = candidates.find((rel) => existsSync(`${cwd}/${rel}`)) ?? candidates[0];
+      return launchProcess(
+        'node',
+        [serverScript, '--port', String(port), '--no-open', '--no-timeout'],
+        { cwd, stdio: ['ignore', 'ignore', 'pipe'] },
+      );
+    },
+  };
+}