@stravica-ai/digital-operator-pa 0.1.27 → 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-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 };
+}

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

@@ -0,0 +1,239 @@
+// config.mjs — read + validate the `library.*` block in
+// operator/config/preferences.json (with the standard preferences.local.json
+// overlay applied on top).
+//
+// Spec §5.1 (remote-library-spec.md):
+//   - mode is EXPLICIT (`library.mode`), never auto-detected
+//   - mode=remote with missing endpoint or key REFUSES to boot; there is
+//     NO silent fallback to SIMPLE (falling back is a data-loss path)
+//
+// Implementation notes:
+//   - The reader mirrors the platform's overlay-aware `readPreferences`
+//     shape (shallow merge; overlay wins; missing/malformed = null)
+//     rather than importing it, so the tool has no runtime coupling to
+//     the installed `@stravica-ai/digital-operator-pa` package layout.
+//   - Consumers pass `{ repoRoot }` or the resolved paths; both surfaces
+//     are seams for tests.
+
+import { readFileSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// operator/extensions/tools/library-cli/src/ → up five levels to the repo root.
+export const DEFAULT_REPO_ROOT = resolve(__dirname, '..', '..', '..', '..', '..');
+
+export class LibraryConfigError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'LibraryConfigError';
+    this.code = code;
+    this.exitCode = 1; // usage / configuration error (tooling exit-code contract)
+  }
+}
+
+const VALID_MODES = new Set(['simple', 'remote']);
+const DEFAULT_MODE = 'simple';
+
+function readJsonObject(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Merge base + optional device-local overlay preferences, shallow.
+ * Fail-open: missing/malformed either file contributes nothing.
+ *
+ * @param {object} paths
+ * @param {string} paths.base   preferences.json path
+ * @param {string} paths.local  preferences.local.json path
+ * @returns {object}            merged preferences (empty object if both absent)
+ */
+export function readMergedPreferences({ base, local }) {
+  const b = readJsonObject(base) || {};
+  const o = readJsonObject(local) || {};
+  return { ...b, ...o };
+}
+
+/**
+ * Resolve the library subsystem config from a merged preferences object.
+ * Returns `{ mode, remoteEndpoint?, remoteKey? }` on success.
+ * Throws {@link LibraryConfigError} on invalid shape or on
+ * `mode=remote` with missing required fields (spec §5.1 refuse-boot).
+ *
+ * @param {object} preferences  merged preferences (base + overlay)
+ * @returns {{mode: 'simple'|'remote', remoteEndpoint?: string, remoteKey?: string}}
+ */
+export function resolveLibraryConfig(preferences) {
+  const raw = preferences && typeof preferences === 'object' ? preferences.library : null;
+  const block = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+
+  const mode = block.mode ?? DEFAULT_MODE;
+
+  if (!VALID_MODES.has(mode)) {
+    throw new LibraryConfigError(
+      `library.mode must be "simple" or "remote", got ${JSON.stringify(mode)}`,
+      'invalid-mode',
+    );
+  }
+
+  if (mode === 'simple') {
+    return { mode };
+  }
+
+  // mode === 'remote'; validate required fields per spec §5.1.
+  const missing = [];
+  const endpoint = block.remoteEndpoint;
+  const key = block.remoteKey;
+  if (typeof endpoint !== 'string' || endpoint.trim() === '') missing.push('library.remoteEndpoint');
+  if (typeof key !== 'string' || key.trim() === '') missing.push('library.remoteKey');
+  if (missing.length > 0) {
+    throw new LibraryConfigError(
+      `library.mode="remote" but required field(s) missing/empty: ${missing.join(', ')}. ` +
+        `Refusing to boot the library subsystem (spec §5.1: no silent fallback to SIMPLE).`,
+      'remote-config-missing',
+    );
+  }
+
+  // Shape check on remoteKey (`<subkeyId>:<secret>`) is cheap and catches
+  // a common paste mistake without over-validating (the server does the
+  // authoritative check).
+  if (!/^[^:\s]+:[^\s]+$/.test(key)) {
+    throw new LibraryConfigError(
+      `library.remoteKey must be of shape "<subkeyId>:<secret>" (no whitespace, colon separator).`,
+      'remote-key-shape',
+    );
+  }
+
+  return { mode, remoteEndpoint: endpoint, remoteKey: key };
+}
+
+/**
+ * Full-scope vault reference form for `library.remoteKey`, per Barry's
+ * ruling on w-2026-07-15-023: `<scope>/<KEY_NAME>` (e.g.
+ * `hq-estate/REMOTE_LIBRARY_SUBKEY_DAVE`). Kept separate 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 refused by resolveLibraryConfig.
+ */
+const REMOTE_KEY_REF_RE = /^([a-z0-9-]+)\/([A-Z][A-Z0-9_]*)$/;
+
+/**
+ * Resolve a `library.remoteKey` value that is a full-scope vault
+ * reference into the underlying literal `<subkeyId>:<secret>` by calling
+ * the estate `secrets` CLI. Literal values (containing a colon) and
+ * anything else pass through untouched; the caller-side shape validator
+ * is authoritative on shape.
+ *
+ * Canonical stravica-operator-barry cannot carry the literal subkey
+ * (sync-cycle 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]     defaults to DEFAULT_REPO_ROOT
+ * @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 = DEFAULT_REPO_ROOT, secretsGet = defaultSecretsGet } = {},
+) {
+  if (typeof refOrLiteral !== 'string') return refOrLiteral;
+  const m = REMOTE_KEY_REF_RE.exec(refOrLiteral);
+  if (!m) return refOrLiteral;
+  const [, scope, key] = m;
+  let resolved;
+  try {
+    resolved = secretsGet({ 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
+  // whitespace once at the boundary so the shape validator sees the
+  // clean payload.
+  return resolved.replace(/\s+$/, '');
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Read + resolve in one call. Returns `{ mode, ...remoteFields, repoRoot,
+ * preferences }` on success or throws {@link LibraryConfigError}. The
+ * `preferences` field is the full merged object so callers can pluck
+ * neighbours (paName, pullClonesRoot, workspacePort) without a second read.
+ *
+ * Also resolves a `library.remoteKey` that carries the full-scope vault
+ * reference form (`<scope>/<KEY_NAME>`) into its underlying literal via
+ * `resolveRemoteKeyRef`. Literal values pass through unchanged.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot]  defaults to DEFAULT_REPO_ROOT
+ * @returns {{mode: 'simple'|'remote', remoteEndpoint?: string, remoteKey?: string, repoRoot: string, preferences: object}}
+ */
+export function loadLibraryConfig({ repoRoot = DEFAULT_REPO_ROOT } = {}) {
+  const base = join(repoRoot, 'operator', 'config', 'preferences.json');
+  const local = join(repoRoot, 'operator', 'config', 'preferences.local.json');
+  const preferences = readMergedPreferences({ base, local });
+  // Vault-ref resolution runs BEFORE resolveLibraryConfig's shape check
+  // so a ref value never reaches the `<subkeyId>:<secret>` validator.
+  // The check on the returned literal still fires and refuses garbage.
+  if (
+    preferences &&
+    preferences.library &&
+    preferences.library.mode === 'remote' &&
+    typeof preferences.library.remoteKey === 'string'
+  ) {
+    const original = preferences.library.remoteKey;
+    const resolved = resolveRemoteKeyRef(original, { repoRoot });
+    if (resolved !== original) {
+      preferences.library = { ...preferences.library, remoteKey: resolved };
+    }
+  }
+  const resolved = resolveLibraryConfig(preferences);
+  return { ...resolved, repoRoot, preferences };
+}