@stravica-ai/digital-operator-pa 0.1.13 → 0.1.16

package/README.md

@@ -11,8 +11,9 @@ code into a self-contained tarball.
 pnpm add @stravica-ai/digital-operator-pa
 ```
 
-Requires Node 24+. See [`../../docs/installing.md`](../../docs/installing.md)
-for the GitHub Packages `~/.npmrc` setup (PAT with `read:packages` scope).
+Requires Node 24+. The package is public on `registry.npmjs.org` and needs no
+registry auth. See [`../../docs/installing.md`](../../docs/installing.md) for the
+full install guide.
 
 ## Bins
 
@@ -157,9 +158,21 @@ pnpm --filter @stravica-ai/digital-operator-pa pack              # produce a rea
 
 ## Publish target
 
-`publishConfig.registry` points at `https://npm.pkg.github.com`. Publishes
-happen via `.github/workflows/publish.yml` on `v*.*.*` tag push or manual
-dispatch. See the root README for the release flow.
+`publishConfig.registry` points at `https://registry.npmjs.org/` with
+`access: public`. Publishes are manual (run by a maintainer with npmjs publish
+rights) from this directory: `pnpm publish` triggers `build.mjs` via `prepack`,
+then ships the bundled tarball to npmjs.org. `ci.yml`'s `dry-publish` job proves
+the pack/publish mechanics on every push. See [`../../docs/installing.md`](../../docs/installing.md)
+for the release-pipeline section.
+
+### Retired predecessor
+
+The prior identity of this codebase was `@stravica/engineering-pa` on GitHub
+Packages (`https://npm.pkg.github.com`, scope `@stravica`). That package is
+retired as of 2026-07-30; its final version (`0.6.2`) is a republish of `0.6.1`
+carrying a deprecation notice. Note the scope difference from `@stravica-ai`
+(the current package) and from `@stravica-ai/engineering-pa-core`, which is a
+separate live package and is unaffected.
 
 ## Standards
 

package/dist/engineering-pa-cli/scripts/migrate-doc-paths.mjs

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+// migrate-doc-paths.mjs — one-shot data migration for the repo-relative
+// doc-path contract (Baz ruling 2026-08-06, w-2026-08-06-007).
+//
+// Background:
+//   `pa project doc add <id> --path <p>` used to store <p> verbatim with
+//   no validation. Operators frequently supplied project-relative paths
+//   (`docs/foo.md`, `equity-analysis.md`), which then 404'd in the
+//   workspace viewer because the viewer's file API resolves paths against
+//   the repo root. Ruling: repo-relative wins (see doc-path.mjs header).
+//
+// What this does:
+//   For every entry in projects/*\/project.json:docs (both flat-array and
+//   grouped shape), apply the same normalisation rule as the runtime CLI:
+//     - resolves as-is under repoRoot         -> untouched
+//     - resolves only under projects/<id>/    -> rewrite path to the joined form
+//     - resolves neither way                  -> REPORT only (never rewrite, never delete)
+//
+// Shape preservation:
+//   Entries may carry {label, path}, {label, path, status}, {group, label,
+//   path}, or {title, path, role} (bowmark-legal). This script only ever
+//   rewrites the `path` string on entries where the join rule triggers.
+//   Every other key stays exactly as it was, in its original insertion
+//   order. Docs shape (flat vs grouped) is preserved — the script does not
+//   promote flat arrays to grouped.
+//
+// Idempotence:
+//   After a successful --apply run, a second dry-run reports 0 joins.
+//
+// Usage:
+//   node <script> [--repo <path>] [--apply] [--json]
+//
+//   --repo <path>  Operator repo root. Defaults to $DAVE_REPO_ROOT /
+//                  $PA_REPO_ROOT, else walks upward from cwd for .git.
+//   --apply        Actually write the mutated project.json files. Default
+//                  is dry-run (no writes).
+//   --json         Emit the per-entry report as JSON on stdout instead of
+//                  a human-readable log.
+//
+// Exit codes (tooling-standard §6):
+//   0 ok (regardless of unresolvables — they are reported, not gated).
+//   1 usage error / invalid --repo / project.json parse failure.
+//   2 filesystem write failure.
+
+import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve, relative, isAbsolute, sep, posix } from 'node:path';
+
+// -- args --------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = { repo: null, apply: false, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') out.help = true;
+    else if (a === '--apply') out.apply = true;
+    else if (a === '--json') out.json = true;
+    else if (a === '--repo') {
+      out.repo = argv[i + 1];
+      i += 1;
+    } else if (a.startsWith('--repo=')) {
+      out.repo = a.slice('--repo='.length);
+    } else {
+      throw usageError(`unknown argument: ${a}`);
+    }
+  }
+  return out;
+}
+
+const USAGE = `migrate-doc-paths — normalise project.json doc entries to repo-relative paths.
+
+Usage:
+  node migrate-doc-paths.mjs [--repo <path>] [--apply] [--json]
+
+Options:
+  --repo <path>  Operator repo root. Defaults to $DAVE_REPO_ROOT / $PA_REPO_ROOT,
+                 else walks upward from the current directory for a .git marker.
+  --apply        Actually write the changes. Default is dry-run.
+  --json         Emit the per-entry report as JSON on stdout.
+  -h, --help     Show this help.
+
+Behaviour:
+  For every projects/*\/project.json:docs entry, apply the same normalisation
+  rule as \`pa project doc add\`:
+    - path resolves under repoRoot                -> untouched
+    - path resolves only under projects/<id>/     -> rewrite to the joined form
+    - neither resolves                            -> REPORT only (no rewrite, no delete)
+
+  Entry shape is preserved exactly — only the \`path\` string is ever mutated.
+  Docs shape (flat array vs grouped object) is preserved.
+
+Exit codes:
+  0 ok  |  1 usage/invalid input  |  2 filesystem write failure.
+`;
+
+function usageError(msg) {
+  const err = new Error(msg);
+  err.exitCode = 1;
+  return err;
+}
+
+// -- repo root discovery -----------------------------------------------------
+
+async function pathKind(p) {
+  try {
+    const s = await stat(p);
+    if (s.isDirectory()) return 'dir';
+    if (s.isFile()) return 'file';
+    return 'other';
+  } catch { return 'missing'; }
+}
+
+async function findRepoRoot(start) {
+  let d = start;
+  while (d && d !== dirname(d)) {
+    const k = await pathKind(join(d, '.git'));
+    if (k === 'dir' || k === 'file') return d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+async function resolveRepoRoot(explicit) {
+  if (explicit) {
+    const abs = resolve(explicit);
+    if (!existsSync(abs)) throw usageError(`--repo path does not exist: ${abs}`);
+    return abs;
+  }
+  const env = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
+  if (env) return resolve(env);
+  const found = await findRepoRoot(process.cwd());
+  if (!found) throw usageError(`could not find repo root from ${process.cwd()} (no .git ancestor)`);
+  return found;
+}
+
+// -- normalisation (mirrors packages/cli/src/pa/doc-path.mjs) ---------------
+
+// A tiny in-file re-implementation of the same rule so this script has
+// zero cross-package coupling and stays runnable as a plain node script
+// after install. Keep in lockstep with doc-path.mjs — the migration
+// script's tests pin the equivalence.
+function classify({ repoRoot, projectId, docPath }) {
+  if (!docPath || typeof docPath !== 'string') {
+    return { action: 'report-unresolvable', reason: 'empty or non-string path' };
+  }
+  if (isAbsolute(docPath)) {
+    return { action: 'report-unresolvable', reason: `absolute path: ${docPath}` };
+  }
+  const asIsAbs = resolve(repoRoot, docPath);
+  if (insideRepo(repoRoot, asIsAbs) && existsSync(asIsAbs)) {
+    return { action: 'untouched', absPath: asIsAbs, storedPath: toPosix(docPath) };
+  }
+  const joinedAbs = resolve(repoRoot, 'projects', projectId, docPath);
+  if (insideRepo(repoRoot, joinedAbs) && existsSync(joinedAbs)) {
+    return {
+      action: 'joined',
+      absPath: joinedAbs,
+      storedPath: toPosix(relative(repoRoot, joinedAbs)),
+    };
+  }
+  return {
+    action: 'report-unresolvable',
+    reason: 'not found as-is under repoRoot nor when joined under projects/<id>/',
+    triedAsIs: asIsAbs,
+    triedJoined: joinedAbs,
+  };
+}
+
+function insideRepo(repoRoot, absPath) {
+  const rel = relative(repoRoot, absPath);
+  if (rel.startsWith('..')) return false;
+  return resolve(repoRoot, rel) === absPath;
+}
+
+function toPosix(p) {
+  if (sep === posix.sep) return p;
+  return p.split(sep).join(posix.sep);
+}
+
+// -- walk + rewrite ----------------------------------------------------------
+
+async function listProjectDirs(projectsRoot) {
+  let entries;
+  try { entries = await readdir(projectsRoot, { withFileTypes: true }); }
+  catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+
+// Read + parse a project.json. Returns { manifest, raw } or null when the
+// file is missing / unreadable / unparseable. Parse failure is reported
+// upstream so the operator sees it.
+async function readManifest(manifestPath) {
+  if (!existsSync(manifestPath)) return null;
+  const raw = await readFile(manifestPath, 'utf8');
+  try {
+    return { manifest: JSON.parse(raw), raw };
+  } catch (err) {
+    throw usageError(`failed to parse ${manifestPath}: ${err.message}`);
+  }
+}
+
+// Walk one project's docs and yield per-entry rows. Docs may be a flat
+// array (legacy) or a grouped object. Entries may carry any set of keys —
+// we only reason about `.path`.
+function* iterDocEntries(docs) {
+  if (docs == null) return;
+  if (Array.isArray(docs)) {
+    for (let i = 0; i < docs.length; i++) {
+      yield { group: null, index: i, entry: docs[i] };
+    }
+    return;
+  }
+  if (typeof docs === 'object') {
+    for (const [group, arr] of Object.entries(docs)) {
+      if (!Array.isArray(arr)) continue;
+      for (let i = 0; i < arr.length; i++) {
+        yield { group, index: i, entry: arr[i] };
+      }
+    }
+  }
+}
+
+// Reassign only `.path` on the entry object. All other keys stay in place
+// and in their original insertion order because we mutate rather than
+// spread — `{...entry, path: X}` would re-order path to the end.
+function rewritePathInPlace(entry, newPath) {
+  entry.path = newPath;
+}
+
+// Serialise back to the operator-repo JSON convention (2-space, trailing
+// newline). Matches io.mjs's writeJson.
+function stringifyManifest(manifest) {
+  return JSON.stringify(manifest, null, 2) + '\n';
+}
+
+async function processProject({ repoRoot, projectId, apply }) {
+  const manifestPath = join(repoRoot, 'projects', projectId, 'project.json');
+  const loaded = await readManifest(manifestPath);
+  if (!loaded) return { projectId, missingManifest: true, rows: [] };
+  const { manifest, raw } = loaded;
+  const rows = [];
+  let dirty = false;
+
+  for (const { group, index, entry } of iterDocEntries(manifest.docs)) {
+    if (!entry || typeof entry !== 'object') {
+      rows.push({ projectId, group, index, entry, action: 'skipped-not-an-object' });
+      continue;
+    }
+    const docPath = entry.path;
+    const cls = classify({ repoRoot, projectId, docPath });
+    const row = { projectId, group, index, path: docPath, entryShape: Object.keys(entry).sort() };
+    if (cls.action === 'untouched') {
+      row.action = 'untouched';
+    } else if (cls.action === 'joined') {
+      row.action = 'joined';
+      row.newPath = cls.storedPath;
+      if (apply) {
+        rewritePathInPlace(entry, cls.storedPath);
+        dirty = true;
+      }
+    } else {
+      row.action = 'report-unresolvable';
+      row.reason = cls.reason;
+      if (cls.triedAsIs) row.triedAsIs = cls.triedAsIs;
+      if (cls.triedJoined) row.triedJoined = cls.triedJoined;
+    }
+    rows.push(row);
+  }
+
+  let wrote = false;
+  if (apply && dirty) {
+    // Preserve the file exactly if nothing changed; only touch on real change.
+    const next = stringifyManifest(manifest);
+    if (next !== raw) {
+      try {
+        await writeFile(manifestPath, next, 'utf8');
+        wrote = true;
+      } catch (err) {
+        const e = new Error(`failed to write ${manifestPath}: ${err.message}`);
+        e.exitCode = 2;
+        throw e;
+      }
+    }
+  }
+  return { projectId, manifestPath, rows, wrote, dirty };
+}
+
+// -- reporting ---------------------------------------------------------------
+
+function summarise(results) {
+  let untouched = 0, joined = 0, unresolvable = 0, skipped = 0;
+  let projectsWritten = 0;
+  const unresolvables = [];
+  const joins = [];
+  for (const r of results) {
+    if (r.wrote) projectsWritten += 1;
+    for (const row of r.rows) {
+      if (row.action === 'untouched') untouched += 1;
+      else if (row.action === 'joined') { joined += 1; joins.push(row); }
+      else if (row.action === 'report-unresolvable') { unresolvable += 1; unresolvables.push(row); }
+      else skipped += 1;
+    }
+  }
+  return { untouched, joined, unresolvable, skipped, projectsWritten, unresolvables, joins };
+}
+
+function renderHumanLog(results, summary, { apply, repoRoot }) {
+  const out = [];
+  out.push(`migrate-doc-paths ${apply ? '(APPLY)' : '(dry-run)'}  repo: ${repoRoot}`);
+  out.push('');
+  for (const r of results) {
+    if (r.missingManifest) continue;
+    if (r.rows.length === 0) continue;
+    out.push(`# ${r.projectId}`);
+    for (const row of r.rows) {
+      if (row.action === 'untouched') {
+        out.push(`  ok       ${formatLocation(row)}  ${row.path}`);
+      } else if (row.action === 'joined') {
+        out.push(`  join     ${formatLocation(row)}  ${row.path}  ->  ${row.newPath}`);
+      } else if (row.action === 'report-unresolvable') {
+        out.push(`  UNRESOLV ${formatLocation(row)}  ${row.path}`);
+        out.push(`             reason: ${row.reason}`);
+        if (row.triedAsIs) out.push(`             tried as-is:  ${row.triedAsIs}`);
+        if (row.triedJoined) out.push(`             tried joined: ${row.triedJoined}`);
+      } else {
+        out.push(`  skip     ${formatLocation(row)}  ${row.action}`);
+      }
+    }
+    if (r.wrote) out.push(`  -> wrote ${r.manifestPath}`);
+    else if (r.dirty && !apply) out.push(`  (dry-run: would write ${r.manifestPath})`);
+    out.push('');
+  }
+  out.push('---');
+  out.push(`untouched:     ${summary.untouched}`);
+  out.push(`joined:        ${summary.joined}${apply ? '' : ' (dry-run — no files written)'}`);
+  out.push(`unresolvable:  ${summary.unresolvable} (report-only; no entries deleted)`);
+  if (summary.skipped) out.push(`skipped:       ${summary.skipped}`);
+  out.push(`projects ${apply ? 'written' : 'that would be written'}: ${summary.projectsWritten}`);
+  return out.join('\n') + '\n';
+}
+
+function formatLocation(row) {
+  const group = row.group == null ? 'flat' : `[${row.group}]`;
+  return `${group}#${row.index}`.padEnd(14, ' ');
+}
+
+// -- main --------------------------------------------------------------------
+
+export async function main(argv) {
+  let args;
+  try { args = parseArgs(argv); }
+  catch (err) {
+    process.stderr.write(err.message + '\n');
+    process.stderr.write(USAGE);
+    return err.exitCode || 1;
+  }
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let repoRoot;
+  try { repoRoot = await resolveRepoRoot(args.repo); }
+  catch (err) {
+    process.stderr.write(err.message + '\n');
+    return err.exitCode || 1;
+  }
+  const projectsRoot = join(repoRoot, 'projects');
+  const projectIds = await listProjectDirs(projectsRoot);
+  const results = [];
+  for (const projectId of projectIds) {
+    try {
+      const r = await processProject({ repoRoot, projectId, apply: args.apply });
+      results.push(r);
+    } catch (err) {
+      process.stderr.write(err.message + '\n');
+      return err.exitCode || 2;
+    }
+  }
+  const summary = summarise(results);
+  if (args.json) {
+    process.stdout.write(JSON.stringify({
+      repoRoot,
+      apply: args.apply,
+      summary: {
+        untouched: summary.untouched,
+        joined: summary.joined,
+        unresolvable: summary.unresolvable,
+        skipped: summary.skipped,
+        projectsWritten: summary.projectsWritten,
+      },
+      results,
+    }, null, 2) + '\n');
+  } else {
+    process.stdout.write(renderHumanLog(results, summary, { apply: args.apply, repoRoot }));
+  }
+  return 0;
+}
+
+// Export the helpers so the test suite can pin per-piece behaviour without
+// spawning a subprocess.
+export { classify, iterDocEntries, processProject, summarise };
+
+// Direct-run entrypoint.
+const isDirectRun =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith('/migrate-doc-paths.mjs');
+
+if (isDirectRun) {
+  main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write((err.stack || err.message || String(err)) + '\n');
+      process.exit(err.exitCode || 2);
+    });
+}

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

@@ -0,0 +1,77 @@
+// audit.mjs — orchestrator for the agent baseline audit.
+//
+// Given a manifest and an audit context, run every probe and fold in
+// severity + hostDependent semantics to produce the final per-capability
+// status. Pure — no filesystem writes here; the CLI (cli.mjs) handles
+// cache IO and stdout.
+
+import { capabilitySeverity } from '../../../engineering-pa-core/src/agent-baseline/manifest.mjs';
+
+import { runProbe } from './probes.mjs';
+
+/**
+ * Fold a probe outcome + capability metadata into a final rendered status.
+ *
+ * Status ladder:
+ *   'pass'             — probe matched
+ *   'warn'             — probe failed but severity=warn (never gates --strict)
+ *   'fail'             — probe failed and severity=fail
+ *   'unverified-here'  — mechanically indeterminate on this host (host-pinned
+ *                        capability declared elsewhere, tool absent, or
+ *                        probe threw)
+ *
+ * `hostDependent` upgrades a hard mechanical fail into unverified-here only
+ * when the probe itself already tells us the reason is host-shape (schedule
+ * declared on another host). A simple missing-file on a host-dependent
+ * probe is still a fail — there is no host on the estate that has it.
+ */
+export function foldOutcome(cap, mech) {
+  if (mech.outcome === 'pass') return { status: 'pass', detail: mech.detail };
+  if (mech.outcome === 'unverified-here') return { status: 'unverified-here', detail: mech.detail };
+  // mech.outcome === 'fail'
+  const sev = capabilitySeverity(cap);
+  if (sev === 'warn') return { status: 'warn', detail: mech.detail };
+  return { status: 'fail', detail: mech.detail };
+}
+
+/**
+ * Run every capability probe in the manifest.
+ */
+export function auditManifest(manifest, ctx) {
+  const capabilities = manifest.capabilities.map((cap) => {
+    const mech = runProbe(cap.probe, ctx);
+    const folded = foldOutcome(cap, mech);
+    return {
+      id: cap.id,
+      label: cap.label,
+      sinceVersion: cap.sinceVersion,
+      severity: capabilitySeverity(cap),
+      hostDependent: cap.hostDependent === true,
+      status: folded.status,
+      detail: folded.detail,
+    };
+  });
+  return {
+    capturedAt: new Date().toISOString(),
+    manifestVersion: manifest.manifestVersion,
+    schemaVersion: manifest.schemaVersion,
+    context: {
+      repoRoot: ctx.repoRoot,
+      paName: ctx.paName,
+      hostname: ctx.hostname ?? null,
+    },
+    summary: summarise(capabilities),
+    capabilities,
+  };
+}
+
+function summarise(caps) {
+  const summary = { total: caps.length, pass: 0, warn: 0, fail: 0, unverifiedHere: 0 };
+  for (const c of caps) {
+    if (c.status === 'pass') summary.pass++;
+    else if (c.status === 'warn') summary.warn++;
+    else if (c.status === 'fail') summary.fail++;
+    else if (c.status === 'unverified-here') summary.unverifiedHere++;
+  }
+  return summary;
+}