@stravica-ai/digital-operator-pa 0.1.34 → 0.1.35

package/dist/engineering-pa-cli/src/secrets/commands/get.mjs

@@ -10,7 +10,7 @@ import {
   depInstallMessage,
   checkVault,
   secretsFileExists,
-  sopsDecrypt,
+  sopsDecryptOrReport,
   readVaultKeyNames,
   VaultError,
 } from '../vault.mjs';
@@ -70,7 +70,7 @@ export async function runGet(args, overrides = {}) {
     throw new VaultError('missing dependencies', 1);
   }
 
-  const data = await sopsDecrypt(paths, paths.secretsFile);
+  const data = await sopsDecryptOrReport(paths, paths.secretsFile);
   if (!(key in data)) {
     console.error(`Error: Key "${key}" not found.`);
     throw new VaultError('key not found', 1);

package/dist/engineering-pa-cli/src/secrets/commands/list.mjs

@@ -6,7 +6,7 @@ import {
   depInstallMessage,
   checkVault,
   secretsFileExists,
-  sopsDecrypt,
+  sopsDecryptOrReport,
   VaultError,
 } from '../vault.mjs';
 
@@ -30,7 +30,7 @@ export async function runList(overrides = {}) {
     return 0;
   }
 
-  const data = await sopsDecrypt(paths, paths.secretsFile);
+  const data = await sopsDecryptOrReport(paths, paths.secretsFile);
   const keys = Object.keys(data).sort();
   for (const key of keys) console.log(key);
   return 0;

package/dist/engineering-pa-cli/src/secrets/vault.mjs

@@ -782,6 +782,83 @@ export async function sopsDecrypt(paths, filePath) {
   return JSON.parse(stdout);
 }
 
+/**
+ * Parse the age recipient public keys out of a sops config file. Kept
+ * deliberately narrow: reads every line of the YAML at `sopsConfigPath`
+ * and extracts anything shaped like `age1[0-9a-z]+` (matches both inline
+ * `age: age1abc...` and the multi-line `age: >-\n  age1abc...` shapes the
+ * scoped-vault fixtures use). Order is stable, duplicates deduplicated.
+ * Returns an empty array on any read failure. This helper only feeds a
+ * diagnostic message and must never throw over its own IO.
+ */
+export function readRecipientsFromSopsConfig(sopsConfigPath) {
+  let text;
+  try {
+    text = readFileSync(sopsConfigPath, 'utf-8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  const seen = new Set();
+  const re = /age1[0-9a-z]+/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const value = m[0];
+    if (!seen.has(value)) {
+      seen.add(value);
+      out.push(value);
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the single stderr diagnostic line that names, without ever
+ * decrypting anything, WHY a decrypt failed: the scope (or vault path),
+ * the caller's age public key (never the private key, never the value),
+ * and the scope's recipient list read from the sops config. Falls back
+ * to a shorter form when one of those pieces cannot be recovered. The
+ * caller still needs a message, and silence on this seam is the defect
+ * being fixed (w-2026-09-02-dave-015 part 1).
+ */
+export function formatDecryptFailure(paths) {
+  const target = paths.scope
+    ? `scope "${paths.scope}"`
+    : (paths.secretsFile ? `vault ${paths.secretsFile}` : 'vault');
+  let callerPub = null;
+  try {
+    callerPub = publicKeyFromKeyFile(paths.keyFile);
+  } catch { /* no key file, or unreadable: leave callerPub null */ }
+  const callerDesc = callerPub
+    ? `age key ${callerPub}`
+    : `age key at ${paths.keyFile}`;
+  const recipients = paths.sopsConfig ? readRecipientsFromSopsConfig(paths.sopsConfig) : [];
+  const recipientsDesc = recipients.length > 0
+    ? `recipients (from ${paths.sopsConfig}): ${recipients.join(', ')}`
+    : `recipients could not be read from ${paths.sopsConfig ?? '<no sops config>'}`;
+  return `Error: cannot decrypt ${target}: this host's ${callerDesc} is not in the recipient list; ${recipientsDesc}. Fix: add this host's public key to the scope's recipients, or run this verb from a host that already has decrypt access.`;
+}
+
+/**
+ * Decrypt wrapper for the interactive verbs (get, list). On failure it
+ * prints the {@link formatDecryptFailure} one-liner to stderr and
+ * re-throws with exitCode 2 preserved, so main() exits with the correct
+ * code AND the caller sees why, closing the silent-exit-2 seam
+ * (w-2026-09-02-dave-015 part 1). Never handles the decrypted value on
+ * the failure path; on success it returns exactly what sopsDecrypt did.
+ */
+export async function sopsDecryptOrReport(paths, filePath) {
+  try {
+    return await sopsDecrypt(paths, filePath);
+  } catch (err) {
+    console.error(formatDecryptFailure(paths));
+    if (err && typeof err === 'object' && err.exitCode == null) {
+      err.exitCode = 2;
+    }
+    throw err;
+  }
+}
+
 /** Encrypt a JSON object to the secrets file with the given public key recipient. */
 export async function sopsEncrypt(paths, pubKey, obj) {
   const tmp = mkdtempSync(join(tmpdir(), 'vault-'));

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

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-library-cli",
-  "version": "0.2.0",
+  "version": "0.2.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",

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

@@ -11,6 +11,9 @@
 //     error surface is the resolveLibraryConfig throw path.
 
 import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { loadLibraryConfig, LibraryConfigError } from './config.mjs';
 import { runPut } from './verbs/put.mjs';
@@ -20,6 +23,26 @@ import { runSearch } from './verbs/search.mjs';
 import { runStatus } from './verbs/status.mjs';
 import { runRefreshClones } from './verbs/refresh-clones.mjs';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Own-package version, read from the shipped package.json alongside this
+ * source (both in-tree and bundled under
+ * dist/engineering-pa-library-cli/). Read at invocation, not import: a
+ * missing/malformed package.json degrades to 'unknown' rather than
+ * crashing --version, which is the whole point of the vault-free help
+ * seam (w-2026-09-02-dave-015 part 2).
+ */
+function readOwnVersion() {
+  try {
+    const raw = readFileSync(join(__dirname, '..', 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
 const USAGE = `library — REMOTE-mode client for the remote-library service.
 
 Usage:
@@ -30,9 +53,15 @@ Usage:
   library status [--json]
   library refresh-clones [--json] [--timeout-ms <n>] [--tier <name>]...
   library -h | --help
+  library -v | --version
 
 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.
+Verbs are only active in REMOTE mode. SIMPLE mode 'library status' prints a
+one-line mode summary and exits 0; every other verb exits 1 in SIMPLE mode
+with a clean not-applicable message.
+
+--help and --version never touch config or the vault, so they always work
+from a directory with no operator config and no vault installed.
 `;
 
 /**
@@ -44,10 +73,19 @@ 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'));
 
+  // --help and --version are answered BEFORE any config or vault
+  // resolution runs. Both must work from a directory with no operator
+  // config and no vault installed at all: the vault-free help/version
+  // seam (w-2026-09-02-dave-015 part 2). Everything after this line is
+  // allowed to touch preferences.json; nothing before it is.
   if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
     log(USAGE);
     return 0;
   }
+  if (argv[0] === '-v' || argv[0] === '--version') {
+    log(readOwnVersion());
+    return 0;
+  }
 
   const verb = argv[0];
   const rest = argv.slice(1);
@@ -64,6 +102,20 @@ export async function main(argv, seams = {}) {
   }
 
   if (config.mode === 'simple') {
+    // `library status` is the one verb useful in SIMPLE mode too: a plain
+    // one-line mode summary that tells the operator the CLI is installed
+    // and the remote path is intentionally not wired. No vault touch,
+    // no network call, exit 0. The "must work with no vault at all"
+    // requirement from w-2026-09-02-dave-015 part 2.
+    if (verb === 'status') {
+      const wantsJson = rest.includes('--json');
+      if (wantsJson) {
+        log(JSON.stringify({ mode: 'simple' }, null, 2));
+      } else {
+        log('mode: simple (library CLI installed; no remote endpoint configured)');
+      }
+      return 0;
+    }
     err(
       `[library] not applicable in simple mode (library.mode="simple"). ` +
         `The library CLI is a REMOTE-mode client only (spec §3.3). ` +

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

@@ -13,12 +13,30 @@
 
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
-import { isAbsolute, normalize, relative, sep } from 'node:path';
+import { basename, extname, isAbsolute, normalize, relative, sep } from 'node:path';
 
 import { EVENT_KINDS, canonicalJson } from '@stravica-ai/remote-library';
 
 export const KNOWN_KINDS = new Set(EVENT_KINDS);
 
+/**
+ * Kinds whose ingest schema accepts an optional `payload.source` routing
+ * hint (spec §2.3 payloadSource dimension). When the operator asserts
+ * an explicit `--tier <repo>` on `library put`, the CLI stamps
+ * `payload.source = <repo>` on these four kinds so the routing engine's
+ * `payloadSource` match can direct the event to the correct tier repo.
+ *
+ * Kept in lockstep with the remote-library package's per-kind payload
+ * schemas: adding a source-accepting kind here without the matching
+ * schema field would 422 at ingest.
+ */
+export const KINDS_ACCEPTING_SOURCE = new Set([
+  'knowledge.doc.upsert',
+  'knowledge.doc.delete',
+  'profile.upsert',
+  'profile.slice.upsert',
+]);
+
 /**
  * Compute the sha256 hash of the canonical JSON form of a payload.
  * The `sha256:` prefix matches the server's contentSha convention.
@@ -118,9 +136,13 @@ export function guessKindFromPath(sourcePath) {
  * @param {string} [args.tier]       default "auto" sentinel (spec §2.3)
  * @param {'staging'|'flush'|'role-output'|'manual'|'synthesis'} [args.sourceKind]
  *   default "manual"; `library flush` passes "flush"
- * @param {string} [args.source]     optional routing hint; only encoded
- *   into the payload for `knowledge.doc.delete` (mirrors the schema's
- *   optional `source` field for the delete kind — spec §3.1 shape).
+ * @param {string} [args.source]     optional routing hint; encoded into
+ *   the payload for any kind whose ingest schema accepts `source`
+ *   (KINDS_ACCEPTING_SOURCE: knowledge.doc.upsert, knowledge.doc.delete,
+ *   profile.upsert, profile.slice.upsert; spec §3.1 shape). When
+ *   `--tier` is asserted explicitly (not the `auto` sentinel), the tier
+ *   value is used as the source stamp for these kinds automatically, so
+ *   callers rarely pass this directly.
  * @param {() => Date} [args.clock]  test seam
  * @returns {object} EventInput ready for POST /events
  */
@@ -170,26 +192,75 @@ export function buildEnvelope({
 
   const now = clock();
   // Per-kind payload construction (spec §3.1 + `remote-library` payload
-  // schema). Fix Wave E (w-2026-08-24-dave-029): before this branch the
-  // envelope encoded `{path, content}` for every kind, and the ingest
-  // schema for `knowledge.doc.delete` refused the `content` key with
-  // 422 (additionalProperties:false, required=["path"]). Result: the
-  // delete verb structurally could not succeed via the CLI — the same
-  // deferred-defect class the retirement programme is here to close.
-  // The delete branch omits `content` and (optionally) attaches
-  // `source`. Every other kind keeps the pre-cure `{path, content}`
-  // shape byte-for-byte; the regression test in envelope.test.mjs
-  // asserts that determinism against a frozen contentSha.
-  const payload =
-    resolvedKind === 'knowledge.doc.delete'
-      ? {
-          path: relPath ?? null,
-          ...(source !== undefined ? { source } : {}),
-        }
-      : {
-          path: relPath ?? null,
-          content,
-        };
+  // schema).
+  //
+  // The delete branch omits `content` (ingest 422 otherwise; Fix Wave E
+  // w-2026-08-24-dave-029). profile.slice.upsert takes `{slice, content}`
+  // (slice is a single filename component, derived from the source
+  // path's basename minus its extension; the schema pattern refuses
+  // path separators). Every other content-bearing kind ships as
+  // `{path, content}` byte-identical to the pre-Wave-E encoding.
+  //
+  // Source stamping (w-2026-09-03-dave-010): when the caller asserts an
+  // explicit tier and the kind's ingest schema accepts a routing hint,
+  // `payload.source = <tier>` is attached. The routing engine's
+  // `payloadSource` match then directs the event to the matching tier
+  // rule (the operator-barry-profile rules from rules v23 depend on
+  // this signal). Kinds not in KINDS_ACCEPTING_SOURCE keep their
+  // pre-cure payload shape byte-identical; the envelope regression
+  // tests pin that determinism against a frozen contentSha.
+  const shouldStampFromTier =
+    tier !== 'auto' && KINDS_ACCEPTING_SOURCE.has(resolvedKind);
+  const effectiveSource = shouldStampFromTier ? tier : source;
+  const stampSource =
+    effectiveSource !== undefined &&
+    KINDS_ACCEPTING_SOURCE.has(resolvedKind);
+  let payload;
+  if (resolvedKind === 'knowledge.doc.delete') {
+    payload = {
+      path: relPath ?? null,
+      ...(stampSource ? { source: effectiveSource } : {}),
+    };
+  } else if (resolvedKind === 'profile.slice.upsert') {
+    // Slice is the source path's basename without its extension. The
+    // ingest schema's pattern (`^[A-Za-z0-9][A-Za-z0-9._-]*$`) refuses
+    // path separators, empty strings, and leading dot/hyphen. Callers
+    // passing a source path outside the slice tree get an actionable
+    // client-side refusal here rather than a 422 from the wire.
+    const filename = basename(relPath ?? sourcePath ?? '');
+    const slice = filename.endsWith('.md')
+      ? filename.slice(0, -3)
+      : extname(filename)
+        ? filename.slice(0, -extname(filename).length)
+        : filename;
+    if (!slice) {
+      const err = new Error(
+        `profile.slice.upsert requires a non-empty slice name (derived from ` +
+          `basename of sourcePath minus extension); sourcePath=${JSON.stringify(sourcePath)}`,
+      );
+      err.exitCode = 1;
+      throw err;
+    }
+    payload = {
+      slice,
+      content,
+      ...(stampSource ? { source: effectiveSource } : {}),
+    };
+  } else if (KINDS_ACCEPTING_SOURCE.has(resolvedKind)) {
+    // knowledge.doc.upsert, profile.upsert.
+    payload = {
+      path: relPath ?? null,
+      content,
+      ...(stampSource ? { source: effectiveSource } : {}),
+    };
+  } else {
+    // Every other kind keeps the pre-cure {path, content} shape
+    // byte-identical.
+    payload = {
+      path: relPath ?? null,
+      content,
+    };
+  }
 
   const envelope = {
     clientEventId: randomUUID(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",