@stravica-ai/digital-operator-pa 0.1.27 → 0.1.29

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 };
+}