@stravica-ai/digital-operator-pa 0.1.26 → 0.1.28

package/bin/library

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// library - REMOTE-mode client CLI for the remote-library service.
+// Bundled entry: delegates to the copied @stravica-ai/engineering-pa-library-cli sources.
+import('../dist/engineering-pa-library-cli/src/cli.mjs').then((m) => {
+  return m.main(process.argv.slice(2));
+}).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    process.stderr.write(`[library] ${err?.message ?? err}\n`);
+    process.exit(typeof err?.exitCode === 'number' ? err.exitCode : 2);
+  },
+);

package/bin/library-tunnel

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// library-tunnel - durable SSH tunnel manager for the remote-library ingest.
+// Bundled entry: delegates to the copied @stravica-ai/engineering-pa-library-tunnel sources.
+import('../dist/engineering-pa-library-tunnel/src/cli.mjs').then((m) => {
+  return m.main(process.argv.slice(2));
+}).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    process.stderr.write(`[library-tunnel] ${err?.message ?? err}\n`);
+    process.exit(typeof err?.exitCode === 'number' ? err.exitCode : 2);
+  },
+);

package/dist/engineering-pa-cli/src/knowledge/context.mjs

@@ -29,7 +29,7 @@
 // §5.1 rules runtime unreachability non-fatal at boot; probing here
 // would drag the boot doctrine sideways.
 
-import { LibraryConfigError, getLibraryVariant, resolveLibraryConfig } from '../../../engineering-pa-core/src/library-config.mjs';
+import { LibraryConfigError, getLibraryVariant, resolveLibraryConfigWithRefs } from '../../../engineering-pa-core/src/library-config.mjs';
 import { readPreferences } from '../../../engineering-pa-core/src/preferences.mjs';
 
 import { getRepoRoot } from '../pa/repo-root.mjs';
@@ -243,7 +243,7 @@ export async function runContext(argv, seam = {}) {
 
   let config;
   try {
-    config = resolveLibraryConfig(prefs);
+    config = resolveLibraryConfigWithRefs(prefs, { repoRoot });
   } catch (err) {
     if (err instanceof LibraryConfigError) {
       stderr.write(`[pa knowledge context] ${err.message}\n`);

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

@@ -25,7 +25,7 @@ import { mergePreferences } from '../../../engineering-pa-core/src/preferences.m
 import {
   LibraryConfigError,
   getLibraryVariant,
-  resolveLibraryConfig,
+  resolveLibraryConfigWithRefs,
 } from '../../../engineering-pa-core/src/library-config.mjs';
 
 /**
@@ -178,16 +178,17 @@ export async function buildSessionPlan(repoRoot, seam = {}) {
   }
 
   // Item 14: resolve the `library.*` block and select the CLAUDE.md
-  // rule-variant token. `resolveLibraryConfig` throws
+  // rule-variant token. `resolveLibraryConfigWithRefs` throws
   // LibraryConfigError on mode=remote misconfiguration (spec §5.1 —
   // refuse to boot the library subsystem, no silent fallback to
-  // SIMPLE). Item 15 will consume `libraryVariant` when it renders the
-  // effective CLAUDE.md and when `pa knowledge context` prints the
-  // resolved wording; the plan carries the token forward so item 15
-  // slots content in without changing the wiring here.
+  // SIMPLE), and additionally resolves a `library.remoteKey` carrying
+  // the full-scope vault reference form (`<scope>/<KEY_NAME>`) into
+  // its underlying literal via the `secrets` CLI. Item 15 consumes
+  // `libraryVariant` when it renders the effective CLAUDE.md and when
+  // `pa knowledge context` prints the resolved wording.
   let libraryConfig;
   try {
-    libraryConfig = resolveLibraryConfig(merged);
+    libraryConfig = resolveLibraryConfigWithRefs(merged, { repoRoot });
   } catch (err) {
     if (err instanceof LibraryConfigError) {
       throw new SessionError(

package/dist/engineering-pa-core/src/library-config.mjs

@@ -16,10 +16,31 @@
 // and will land in item 15; the wiring here is stable so item 15 slots
 // content into the existing shape without changing this file.
 //
-// The reader is DELIBERATELY pure — it consumes an already-merged
-// preferences object. Callers pair it with `readPreferences` /
+// `resolveLibraryConfig` is DELIBERATELY pure — it consumes an already-
+// merged preferences object. Callers pair it with `readPreferences` /
 // `readPreferencesSync` from ./preferences.mjs so the overlay-aware
 // path stays a single implementation.
+//
+// `resolveRemoteKeyRef` sits alongside it as an OPT-IN vault-fetching
+// resolver: `library.remoteKey` values that look like the full-scope
+// reference form (`<scope>/<KEY_NAME>` per Baz's w-2026-07-15-023
+// ruling) resolve to their vaulted literal via the `secrets` CLI so
+// canonical stravica-operator-barry never has to carry a literal
+// subkey in a git-tracked file. Literal values pass through untouched.
+// The wrapper `resolveLibraryConfigWithRefs(preferences, {repoRoot})`
+// composes the two so callers get one call: read → ref-resolve →
+// validate, refuse-boot on any failure.
+//
+// Written into the platform in w-2026-08-21-005 after the 2026-08-21T11:05Z
+// library-sync-cycle wipe: the canonical file had no library block, a
+// materialisation tick clobbered HQ's local plaintext block, and the
+// options collapsed to (a) put a literal secret in canonical (rejected
+// by policy — git history is forever), (b) hold sync-cycle indefinitely,
+// or (c) ship this resolver. The estate picked (c).
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
 
 /**
  * Default when `library.mode` is absent from preferences.
@@ -120,3 +141,134 @@ export function getLibraryVariant(config) {
   const mode = config?.mode ?? DEFAULT_LIBRARY_MODE;
   return mode === 'remote' ? 'remote' : 'simple';
 }
+
+/**
+ * Full-scope vault reference form for `library.remoteKey`, per Baz's
+ * ruling on w-2026-07-15-023: `<scope>/<KEY_NAME>` (e.g.
+ * `hq-estate/REMOTE_LIBRARY_SUBKEY_DAVE`). Distinct from the literal-
+ * subkey shape (`<subkeyId>:<secret>`) so the shape validator downstream
+ * still refuses garbage. Any value that neither matches this ref shape
+ * nor the literal shape is passed through and refused by the shape
+ * validator.
+ */
+export const REMOTE_KEY_REF_RE = /^([a-z0-9-]+)\/([A-Z][A-Z0-9_]*)$/;
+
+/**
+ * Resolve a `library.remoteKey` value that carries the full-scope vault
+ * reference form (`<scope>/<KEY_NAME>`) into the underlying literal
+ * `<subkeyId>:<secret>` by calling the estate `secrets` CLI. Literal
+ * values (containing a colon) and anything else pass through untouched;
+ * the shape validator in `resolveLibraryConfig` is authoritative on shape.
+ *
+ * Canonical stravica-operator-barry cannot carry the literal subkey (a
+ * sync-cycle materialisation would round-trip a plaintext secret through
+ * a git-tracked file). The reference lives in canonical; the vault holds
+ * the value; this function is the bridge. See w-2026-08-21-005 for the
+ * incident that made this the durable pattern.
+ *
+ * @param {string} refOrLiteral        the raw remoteKey value from preferences
+ * @param {object} opts
+ * @param {string} opts.repoRoot       repo root; used to locate the secrets bin
+ * @param {(args:{scope:string,key:string,repoRoot:string})=>string} [opts.secretsGet]
+ *                                     injectable resolver (tests)
+ * @returns {string}                   the resolved literal (never printed)
+ */
+export function resolveRemoteKeyRef(refOrLiteral, { repoRoot, secretsGet } = {}) {
+  if (typeof refOrLiteral !== 'string') return refOrLiteral;
+  const m = REMOTE_KEY_REF_RE.exec(refOrLiteral);
+  if (!m) return refOrLiteral;
+  const [, scope, key] = m;
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
+    throw new LibraryConfigError(
+      `library.remoteKey vault reference "${refOrLiteral}" cannot be resolved: ` +
+        `no repoRoot supplied. Callers must pass repoRoot when preferences carry a scope/KEY ref.`,
+      'remote-key-ref-unresolved',
+    );
+  }
+  const fetcher = secretsGet || defaultSecretsGet;
+  let resolved;
+  try {
+    resolved = fetcher({ scope, key, repoRoot });
+  } catch (err) {
+    throw new LibraryConfigError(
+      `library.remoteKey vault reference "${refOrLiteral}" failed to resolve ` +
+        `(scope=${scope} key=${key}): ${err && err.message ? err.message : err}. ` +
+        `Fix: pnpm exec secrets set ${key} --scope ${scope} <value>`,
+      'remote-key-ref-unresolved',
+    );
+  }
+  if (typeof resolved !== 'string' || resolved.length === 0) {
+    throw new LibraryConfigError(
+      `library.remoteKey vault reference "${refOrLiteral}" resolved to empty value ` +
+        `(scope=${scope} key=${key}). ` +
+        `Fix: pnpm exec secrets set ${key} --scope ${scope} <value>`,
+      'remote-key-ref-unresolved',
+    );
+  }
+  // secrets get can leave a trailing newline depending on subshell; strip
+  // trailing whitespace once at the boundary so the shape validator sees
+  // the clean payload.
+  return resolved.replace(/\s+$/, '');
+}
+
+/**
+ * Read + ref-resolve + validate in one call. Wraps `resolveLibraryConfig`
+ * with `resolveRemoteKeyRef` so callers get: (1) full-scope vault refs
+ * automatically resolved via the injected `secretsGet` (or the built-in
+ * `secrets` CLI); (2) the same shape/refuse-boot guarantees on the
+ * resolved literal. Preserves the pure `resolveLibraryConfig` for
+ * caller sites that never see refs.
+ *
+ * @param {object|null} preferences   merged preferences (base + overlay)
+ * @param {object} opts
+ * @param {string} opts.repoRoot      required when preferences may carry a
+ *                                    scope/KEY ref; ignored otherwise
+ * @param {(args:{scope:string,key:string,repoRoot:string})=>string} [opts.secretsGet]
+ * @returns {{mode: 'simple'|'remote', remoteEndpoint?: string, remoteKey?: string}}
+ */
+export function resolveLibraryConfigWithRefs(preferences, opts = {}) {
+  if (
+    preferences &&
+    typeof preferences === 'object' &&
+    !Array.isArray(preferences) &&
+    preferences.library &&
+    typeof preferences.library === 'object' &&
+    !Array.isArray(preferences.library) &&
+    preferences.library.mode === 'remote' &&
+    typeof preferences.library.remoteKey === 'string'
+  ) {
+    const original = preferences.library.remoteKey;
+    const resolved = resolveRemoteKeyRef(original, opts);
+    if (resolved !== original) {
+      preferences = {
+        ...preferences,
+        library: { ...preferences.library, remoteKey: resolved },
+      };
+    }
+  }
+  return resolveLibraryConfig(preferences);
+}
+
+/**
+ * Default vault fetcher: invokes the `secrets` bin from the installed
+ * `@stravica-ai/digital-operator-pa` package under `repoRoot`. Uses
+ * direct `node <bin>` invocation (not `pnpm exec`) to sidestep the
+ * pnpm-11 stdout footgun that has bitten sam-tasks and others. Value
+ * is never logged.
+ */
+function defaultSecretsGet({ scope, key, repoRoot }) {
+  const secretsBin = join(
+    repoRoot,
+    'node_modules',
+    '@stravica-ai',
+    'digital-operator-pa',
+    'bin',
+    'secrets',
+  );
+  const out = execFileSync('node', [secretsBin, 'get', key, '--scope', scope], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return out;
+}

package/dist/engineering-pa-library-cli/README.md

@@ -0,0 +1,64 @@
+# library-cli
+
+REMOTE-mode client for the `@stravica-ai/remote-library` service (spec §3.3).
+Ships the `library` bin with five verbs: `put`, `flush`, `get`, `search`, `status`.
+
+Only active when `operator/config/preferences.json` has `library.mode: "remote"`
+plus `library.remoteEndpoint` and `library.remoteKey`. SIMPLE-mode installs (or
+unset `library.mode`) refuse every verb with a clean exit-1 message; the CLI is
+deliberately not a shim for the pre-remote library sweep.
+
+## Verbs
+
+- `library put <path> [--kind <kind>] [--tier auto|<tier>]`
+  Streams a single event to `POST /events`. `--tier auto` sends the spec §2.3
+  sentinel; the server's routing engine resolves the actual tier.
+- `library flush`
+  Sweeps `<repoRoot>/agents/<paName>/staging/*` and streams one event per file.
+  Archives to `staging/_archived/` on `accepted` or `deduped` (both count as
+  ack per spec §4.2). Failures leave the file in place; next flush retries
+  (idempotent via `clientEventId`).
+- `library get <path>`
+  Reads from the local pulled clone. `<path>` is resolved under
+  `LIBRARY_PULL_CLONES_ROOT` (env; else `library.pullClonesRoot` in
+  preferences; else `~/stravica-library-clones/`).
+- `library search <query> [--files-only]`
+  Filesystem-native substring search over the pull-clones root.
+- `library status [--json]`
+  GETs `/status` from the service, plus `git rev-list HEAD..origin/main --count`
+  per tier clone.
+
+## Configuration
+
+- `operator/config/preferences.json` (base) and `preferences.local.json`
+  (device-local overlay; shallow-merged on top):
+
+  ```json
+  {
+    "library": {
+      "mode": "remote",
+      "remoteEndpoint": "https://ops-01.internal",
+      "remoteKey": "sk_barry_dave_deadbeef:secret"
+    }
+  }
+  ```
+
+- `LIBRARY_PULL_CLONES_ROOT` env — overrides the pull-clones root at runtime.
+
+Ingest authenticates by subkey alone (spec §3.4, main ruling 2026-08-20 option b);
+no install-key header is sent. The former `REMOTE_LIBRARY_INSTALL_KEY` env
+interim was removed in the same pass.
+
+## Exit codes
+
+`0` ok · `1` usage / configuration error · `2` operational failure · `3` transport/IO failure.
+
+## Testing
+
+```sh
+pnpm --dir operator/extensions/tools/library-cli test
+```
+
+All tests are `node:test` and hit a locally-bound mock ingest server (no
+network, no Mongo). Integration against the real docker-compose stack lands
+with item 16.

package/dist/engineering-pa-library-cli/bin/library

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// library — REMOTE-mode client CLI for the remote-library service.
+// See src/cli.mjs for the routing table and exit-code contract.
+
+import { main } from '../src/cli.mjs';
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code ?? 0))
+  .catch((err) => {
+    process.stderr.write(`[library] ${err?.message ?? err}\n`);
+    process.exit(typeof err?.exitCode === 'number' ? err.exitCode : 2);
+  });

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

@@ -0,0 +1,21 @@
+{
+  "name": "@stravica-ai/engineering-pa-library-cli",
+  "version": "0.1.1",
+  "description": "Local `library` CLI for the remote-library REMOTE-mode write path (spec §3.3): put | flush | get | search | status. SIMPLE mode installs refuse every verb with a clean not-applicable message.",
+  "type": "module",
+  "main": "./src/cli.mjs",
+  "exports": {
+    ".": "./src/cli.mjs"
+  },
+  "private": true,
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@stravica-ai/remote-library": "^0.1.1"
+  }
+}

package/dist/engineering-pa-library-cli/src/ack.mjs

@@ -0,0 +1,64 @@
+// ack.mjs — parse the remote-library ingest `POST /events` response
+// (single-event path) into a discriminated ack.
+//
+// Wire contract (SOURCE OF TRUTH: remote-library/src/ingest/server.ts
+// as of 2026-08-20 rehearsal fix, RB-5). Locked on BOTH sides by
+// library-cli/test/ingest-contract.test.mjs (this side) and the
+// wire-shape assertions in remote-library/src/test/routing.test.ts
+// (server side).
+//
+//   Status 202 body {eventId: <ulid>, receivedAt: <iso8601>}
+//     -> newly-accepted event (worker will pick up on next tick).
+//   Status 200 body {eventId: <ulid>, deduped: true}
+//     -> clientEventId was already on record; return the eventId of
+//        the ORIGINAL insert so the producer sees the same anchor
+//        (spec §4.2). A retrying producer MUST see success and
+//        archive the source file, or the staging directory grows
+//        unboundedly across retries.
+//   Status 4xx / 5xx with {error: <code>, detail?: <string>, errors?}
+//     -> rejected. The `error` code is the taxonomy from
+//        ingest/server.ts::statusCodeForRejection (e.g.
+//        `no-matching-rule`, `subkey-not-permitted`, `schema-invalid`).
+//        Callers surface it verbatim.
+
+/**
+ * @typedef {{kind: 'accepted', eventId: string}
+ *          | {kind: 'deduped', eventId: string}
+ *          | {kind: 'rejected', reason: string}} IngestAck
+ */
+
+/**
+ * @param {{httpStatus: number, body: unknown}} res
+ * @returns {IngestAck}
+ */
+export function parseIngestAck(res) {
+  const { httpStatus, body } = res;
+  const isObj = body !== null && typeof body === 'object';
+
+  if (httpStatus === 202 && isObj) {
+    const eventId = /** @type {any} */ (body).eventId;
+    if (typeof eventId === 'string' && eventId.length > 0) {
+      return { kind: 'accepted', eventId };
+    }
+    return { kind: 'rejected', reason: `http 202 without eventId: ${JSON.stringify(body)}` };
+  }
+
+  if (httpStatus === 200 && isObj) {
+    const b = /** @type {any} */ (body);
+    if (b.deduped === true && typeof b.eventId === 'string' && b.eventId.length > 0) {
+      return { kind: 'deduped', eventId: b.eventId };
+    }
+    return { kind: 'rejected', reason: `http 200 without deduped ack shape: ${JSON.stringify(body)}` };
+  }
+
+  // Any other status is a rejection. Prefer the server's error code +
+  // detail; fall back to a JSON-encoded body so no signal is lost.
+  if (isObj) {
+    const b = /** @type {any} */ (body);
+    if (typeof b.error === 'string') {
+      const detail = typeof b.detail === 'string' ? `: ${b.detail}` : '';
+      return { kind: 'rejected', reason: `http ${httpStatus} ${b.error}${detail}` };
+    }
+  }
+  return { kind: 'rejected', reason: `http ${httpStatus}: ${JSON.stringify(body)}` };
+}

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

@@ -0,0 +1,142 @@
+// cli.mjs — argv dispatch for `library`.
+//
+// Exit code contract (tooling standard §6):
+//   0 ok | 1 usage error | 2 operational failure | 3 transport/IO failure
+//
+// Modes:
+//   - SIMPLE mode installs (or unset library.mode) print a clean
+//     "not applicable in simple mode" message and exit 1. Spec §3.3
+//     is explicit that the verbs are REMOTE-mode only.
+//   - REMOTE mode with misconfig refuses to boot (spec §5.1); the
+//     error surface is the resolveLibraryConfig throw path.
+
+import { parseArgs } from 'node:util';
+
+import { loadLibraryConfig, LibraryConfigError } from './config.mjs';
+import { runPut } from './verbs/put.mjs';
+import { runFlush } from './verbs/flush.mjs';
+import { runGet } from './verbs/get.mjs';
+import { runSearch } from './verbs/search.mjs';
+import { runStatus } from './verbs/status.mjs';
+
+const USAGE = `library — REMOTE-mode client for the remote-library service.
+
+Usage:
+  library put <path> [--kind <kind>] [--tier auto|<tier>]
+  library flush
+  library get <path>
+  library search <query> [--files-only]
+  library status [--json]
+  library -h | --help
+
+Reads config from operator/config/preferences.json (+ preferences.local.json overlay).
+Verbs are only active in REMOTE mode. SIMPLE mode exits 1 with a clean message.
+`;
+
+/**
+ * @param {string[]} argv          process.argv.slice(2)
+ * @param {object} [seams]         test seams (fetchImpl, git, log, err, repoRoot)
+ * @returns {Promise<number>}      exit code
+ */
+export async function main(argv, seams = {}) {
+  const log = seams.log ?? ((...m) => process.stdout.write(m.join(' ') + '\n'));
+  const err = seams.err ?? ((...m) => process.stderr.write(m.join(' ') + '\n'));
+
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    log(USAGE);
+    return 0;
+  }
+
+  const verb = argv[0];
+  const rest = argv.slice(1);
+
+  let config;
+  try {
+    config = loadLibraryConfig({ repoRoot: seams.repoRoot });
+  } catch (e) {
+    if (e instanceof LibraryConfigError) {
+      err(`[library] ${e.message}`);
+      return e.exitCode ?? 1;
+    }
+    throw e;
+  }
+
+  if (config.mode === 'simple') {
+    err(
+      `[library] not applicable in simple mode (library.mode="simple"). ` +
+        `The library CLI is a REMOTE-mode client only (spec §3.3). ` +
+        `Set library.mode="remote" in operator/config/preferences.json (with ` +
+        `library.remoteEndpoint + library.remoteKey) to enable.`,
+    );
+    return 1;
+  }
+
+  const ctx = {
+    config,
+    fetchImpl: seams.fetchImpl,
+    log,
+    err,
+    git: seams.git,
+  };
+
+  try {
+    switch (verb) {
+      case 'put':      return await runPut({ ...ctx, args: parsePut(rest) });
+      case 'flush':    return await runFlush({ ...ctx, args: parseFlush(rest) });
+      case 'get':      return await runGet({ ...ctx, args: parseGet(rest) });
+      case 'search':   return await runSearch({ ...ctx, args: parseSearch(rest) });
+      case 'status':   return await runStatus({ ...ctx, args: parseStatus(rest) });
+      default:
+        err(`[library] unknown verb: ${verb}`);
+        log(USAGE);
+        return 1;
+    }
+  } catch (e) {
+    err(`[library ${verb}] ${e.message ?? e}`);
+    return typeof e.exitCode === 'number' ? e.exitCode : 2;
+  }
+}
+
+function parsePut(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: {
+      kind: { type: 'string' },
+      tier: { type: 'string', default: 'auto' },
+    },
+  });
+  return { path: positionals[0], kind: values.kind, tier: values.tier };
+}
+function parseFlush(argv) {
+  parseArgs({ args: argv, strict: true, allowPositionals: true, options: {} });
+  return {};
+}
+function parseGet(argv) {
+  const { positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: {},
+  });
+  return { path: positionals[0] };
+}
+function parseSearch(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: { 'files-only': { type: 'boolean', default: false } },
+  });
+  return { query: positionals[0], filesOnly: values['files-only'] };
+}
+function parseStatus(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: false,
+    options: { json: { type: 'boolean', default: false } },
+  });
+  return { json: values.json };
+}