@stravica-ai/digital-operator-pa 0.1.0

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

@@ -0,0 +1,58 @@
+// delete KEY — remove a secret and re-encrypt.
+
+import {
+  defaultPaths,
+  checkDeps,
+  depInstallMessage,
+  checkVault,
+  getPublicKey,
+  secretsFileExists,
+  decryptStoreForWrite,
+  sopsEncrypt,
+  sopsEncryptScoped,
+  VaultError,
+} from '../vault.mjs';
+
+export async function runDelete(args, overrides = {}) {
+  const paths = overrides.paths || defaultPaths(overrides);
+  const key = args[0];
+
+  if (!key) {
+    console.error('Usage: secrets delete KEY');
+    throw new VaultError('usage', 1);
+  }
+
+  const missing = await checkDeps();
+  if (missing.length > 0) {
+    console.error(depInstallMessage(missing[0]));
+    throw new VaultError('missing dependencies', 1);
+  }
+
+  const vaultState = checkVault(paths);
+  if (!vaultState.ok) {
+    console.error(vaultState.message);
+    throw new VaultError(vaultState.reason || 'vault not initialised', vaultState.exitCode ?? 1);
+  }
+
+  if (!secretsFileExists(paths)) {
+    console.error(paths.scoped ? `Error: No secrets file found at ${paths.secretsFile}.` : 'Error: No secrets file found.');
+    throw new VaultError('no secrets file', 1);
+  }
+
+  const pubKey = paths.scoped ? null : getPublicKey(paths);
+  const data = await decryptStoreForWrite(paths);
+
+  if (!(key in data)) {
+    console.error(`Error: Key "${key}" not found.`);
+    throw new VaultError('key not found', 1);
+  }
+
+  delete data[key];
+  if (paths.scoped) {
+    await sopsEncryptScoped(paths, data);
+  } else {
+    await sopsEncrypt(paths, pubKey, data);
+  }
+  console.log(`Secret '${key}' deleted.`);
+  return 0;
+}

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

@@ -0,0 +1,36 @@
+// find KEY (alias: which) — report every vault whose plaintext key-name
+// structure contains KEY. Names and paths only — values are NEVER read;
+// no decryption happens anywhere in this command (sops JSON keeps key
+// names in plaintext, values encrypted).
+
+import { VaultError, readVaultKeyNames } from '../vault.mjs';
+import { vaultEntriesFor } from './vaults.mjs';
+
+// Estate key-name discipline — validated before the name is used anywhere.
+const KEY_NAME_RE = /^[A-Z0-9_]+$/;
+
+export async function runFind(args, overrides = {}) {
+  const key = args[0];
+
+  if (!key) {
+    console.error('Usage: secrets find KEY');
+    throw new VaultError('usage', 1);
+  }
+  if (!KEY_NAME_RE.test(key)) {
+    console.error(`Error: Invalid key name "${key}". Key names must match ${KEY_NAME_RE}.`);
+    throw new VaultError('invalid key name', 1);
+  }
+
+  const entries = vaultEntriesFor(overrides);
+  const hits = entries.filter((e) => (readVaultKeyNames(e.path) ?? []).includes(key));
+
+  if (hits.length === 0) {
+    console.error(`Key "${key}" not found in any of ${entries.length} vault(s).`);
+    return 1;
+  }
+
+  for (const h of hits) {
+    console.log(`${h.scope}\t${h.layout}\t${h.path}`);
+  }
+  return 0;
+}

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

@@ -0,0 +1,49 @@
+// get KEY — print the value of a single secret to stdout.
+
+import {
+  resolveCommandPaths,
+  checkDeps,
+  depInstallMessage,
+  checkVault,
+  secretsFileExists,
+  sopsDecrypt,
+  VaultError,
+} from '../vault.mjs';
+
+export async function runGet(args, overrides = {}) {
+  // resolveCommandPaths prints the interim stderr notice (naming the
+  // target vault) whenever --scope/--file wasn't given upstream in
+  // cli.mjs — see vault.mjs's default-scope resolution section.
+  const paths = resolveCommandPaths(overrides);
+  const key = args[0];
+
+  if (!key) {
+    console.error('Usage: secrets get KEY');
+    throw new VaultError('usage', 1);
+  }
+
+  const missing = await checkDeps();
+  if (missing.length > 0) {
+    console.error(depInstallMessage(missing[0]));
+    throw new VaultError('missing dependencies', 1);
+  }
+
+  const vaultState = checkVault(paths);
+  if (!vaultState.ok) {
+    console.error(vaultState.message);
+    throw new VaultError(vaultState.reason || 'vault not initialised', vaultState.exitCode ?? 1);
+  }
+
+  if (!secretsFileExists(paths)) {
+    console.error(paths.scoped ? `Error: No secrets file found at ${paths.secretsFile}.` : "Error: No secrets file found. Run 'secrets init' first.");
+    throw new VaultError('no secrets file', 1);
+  }
+
+  const data = await sopsDecrypt(paths, paths.secretsFile);
+  if (!(key in data)) {
+    console.error(`Error: Key "${key}" not found.`);
+    throw new VaultError('key not found', 1);
+  }
+  console.log(data[key]);
+  return 0;
+}

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

@@ -0,0 +1,69 @@
+// init — generate age keypair, write recipients, write SOPS config,
+// create an empty encrypted secrets file if none exists.
+
+import {
+  defaultPaths,
+  checkDeps,
+  depInstallMessage,
+  ageKeygen,
+  publicKeyFromKeyFile,
+  ensureKeyDir,
+  ensureVaultDir,
+  chmodKeyFile,
+  writeRecipients,
+  writeSopsConfig,
+  keyFileExists,
+  secretsFileExists,
+  sopsEncrypt,
+  VaultError,
+} from '../vault.mjs';
+
+export async function runInit(overrides = {}) {
+  const paths = overrides.paths || defaultPaths({ ...overrides, allowGitRootWithoutVault: true });
+
+  const missing = await checkDeps();
+  if (missing.length > 0) {
+    console.error(depInstallMessage(missing[0]));
+    if (missing.length > 1) console.error(depInstallMessage(missing[1]));
+    throw new VaultError('missing dependencies', 1);
+  }
+
+  console.log('Initialising vault...');
+
+  ensureKeyDir(paths);
+
+  if (keyFileExists(paths)) {
+    console.log(`Age private key already exists at ${paths.keyFile}`);
+  } else {
+    await ageKeygen(paths);
+    chmodKeyFile(paths);
+    console.log(`Generated age private key: ${paths.keyFile}`);
+  }
+
+  const pubKey = publicKeyFromKeyFile(paths.keyFile);
+  if (!pubKey) {
+    throw new VaultError(`Could not extract public key from ${paths.keyFile}`, 2);
+  }
+
+  ensureVaultDir(paths);
+  writeRecipients(paths, pubKey);
+  console.log(`Public key written to ${paths.recipientsFile}`);
+
+  writeSopsConfig(paths, pubKey);
+  console.log(`SOPS config written to ${paths.sopsConfig}`);
+
+  if (!secretsFileExists(paths)) {
+    await sopsEncrypt(paths, pubKey, {});
+    console.log('Created empty encrypted secrets file.');
+  } else {
+    console.log('Encrypted secrets file already exists.');
+  }
+
+  console.log('');
+  console.log('Vault initialised.');
+  console.log(`  Private key: ${paths.keyFile} (NEVER commit this)`);
+  console.log(`  Public key:  ${paths.recipientsFile} (safe to commit)`);
+  console.log(`  Secrets:     ${paths.secretsFile} (safe to commit)`);
+
+  return 0;
+}

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

@@ -0,0 +1,37 @@
+// list — print all secret key names (not values), one per line, sorted.
+
+import {
+  defaultPaths,
+  checkDeps,
+  depInstallMessage,
+  checkVault,
+  secretsFileExists,
+  sopsDecrypt,
+  VaultError,
+} from '../vault.mjs';
+
+export async function runList(overrides = {}) {
+  const paths = overrides.paths || defaultPaths(overrides);
+
+  const missing = await checkDeps();
+  if (missing.length > 0) {
+    console.error(depInstallMessage(missing[0]));
+    throw new VaultError('missing dependencies', 1);
+  }
+
+  const vaultState = checkVault(paths);
+  if (!vaultState.ok) {
+    console.error(vaultState.message);
+    throw new VaultError(vaultState.reason || 'vault not initialised', vaultState.exitCode ?? 1);
+  }
+
+  if (!secretsFileExists(paths)) {
+    console.log('No secrets stored.');
+    return 0;
+  }
+
+  const data = await sopsDecrypt(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/commands/rotate.mjs

@@ -0,0 +1,46 @@
+// rotate — decrypt-and-re-encrypt in place using the current recipients.
+// Used after a key change so existing payloads carry the updated recipient.
+
+import {
+  defaultPaths,
+  checkDeps,
+  depInstallMessage,
+  checkVault,
+  getPublicKey,
+  secretsFileExists,
+  decryptStoreForWrite,
+  sopsEncrypt,
+  sopsEncryptScoped,
+  VaultError,
+} from '../vault.mjs';
+
+export async function runRotate(overrides = {}) {
+  const paths = overrides.paths || defaultPaths(overrides);
+
+  const missing = await checkDeps();
+  if (missing.length > 0) {
+    console.error(depInstallMessage(missing[0]));
+    throw new VaultError('missing dependencies', 1);
+  }
+
+  const vaultState = checkVault(paths);
+  if (!vaultState.ok) {
+    console.error(vaultState.message);
+    throw new VaultError(vaultState.reason || 'vault not initialised', vaultState.exitCode ?? 1);
+  }
+
+  if (!secretsFileExists(paths)) {
+    console.log('No secrets file to rotate.');
+    return 0;
+  }
+
+  const pubKey = paths.scoped ? null : getPublicKey(paths);
+  const data = await decryptStoreForWrite(paths);
+  if (paths.scoped) {
+    await sopsEncryptScoped(paths, data);
+  } else {
+    await sopsEncrypt(paths, pubKey, data);
+  }
+  console.log('Secrets re-encrypted with current recipients.');
+  return 0;
+}

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

@@ -0,0 +1,123 @@
+// set KEY VALUE — upsert a secret and re-encrypt.
+// Passing `-` as VALUE reads the secret from stdin (trailing newline stripped),
+// which keeps the value out of argv / process listings / shell history.
+//
+// --canonical-clone PATH: write the canonical clone's vault file FIRST,
+// then this workspace copy SECOND. If the canonical write fails for any
+// reason, the command aborts (exit 2) BEFORE touching the workspace copy
+// at all — a device-side vault mutation never round-trips only halfway
+// (see up-path-single-writer-ownership's vault follow-up: "device-side
+// vault mutations must round-trip to canonical immediately"). Without the
+// flag, behaviour is exactly as before (workspace copy only).
+
+import { readFileSync } from 'node:fs';
+import {
+  resolveCommandPaths,
+  resolveScopePaths,
+  checkDeps,
+  depInstallMessage,
+  checkVault,
+  getPublicKey,
+  secretsFileExists,
+  decryptStoreForWrite,
+  sopsEncrypt,
+  sopsEncryptScoped,
+  VaultError,
+} from '../vault.mjs';
+
+// --canonical-clone may appear anywhere in argv, matching the --scope/
+// --file convention in cli.mjs. Local to `set` (not a global flag) since
+// no other command writes to a second target.
+function extractCanonicalCloneFlag(argv) {
+  const rest = [];
+  let canonicalClone;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--canonical-clone') { canonicalClone = argv[i + 1]; i += 1; continue; }
+    if (a.startsWith('--canonical-clone=')) { canonicalClone = a.slice('--canonical-clone='.length); continue; }
+    rest.push(a);
+  }
+  return { canonicalClone, rest };
+}
+
+export async function runSet(args, overrides = {}) {
+  // resolveCommandPaths prints the interim stderr notice (naming the
+  // target vault) whenever --scope/--file wasn't given upstream in
+  // cli.mjs — see vault.mjs's default-scope resolution section.
+  const paths = resolveCommandPaths(overrides);
+  const { canonicalClone, rest } = extractCanonicalCloneFlag(args);
+  const key = rest[0];
+  let value = rest[1];
+
+  if (!key || value == null || value === '') {
+    console.error('Usage: secrets set KEY VALUE [--canonical-clone PATH]   (use `-` as VALUE to read from stdin)');
+    throw new VaultError('usage', 1);
+  }
+
+  if (value === '-') {
+    const readStdin = overrides.readStdin ?? (() => readFileSync(0, 'utf-8'));
+    const raw = readStdin();
+    // Strip a single trailing newline (\r\n or \n) — common when piping from
+    // `echo` or heredocs. Preserve all other whitespace in case the secret
+    // legitimately contains it.
+    value = raw.replace(/\r?\n$/, '');
+    if (value === '') {
+      console.error('Empty value on stdin — refusing to store an empty secret.');
+      throw new VaultError('empty stdin', 1);
+    }
+  }
+
+  const missing = await checkDeps();
+  if (missing.length > 0) {
+    console.error(depInstallMessage(missing[0]));
+    throw new VaultError('missing dependencies', 1);
+  }
+
+  const vaultState = checkVault(paths);
+  if (!vaultState.ok) {
+    console.error(vaultState.message);
+    throw new VaultError(vaultState.reason || 'vault not initialised', vaultState.exitCode ?? 1);
+  }
+
+  // Canonical FIRST. Resolved the same way `--file` already works for
+  // every other scope-aware command — an arbitrary path, its own
+  // .sops.yaml expected alongside it, reusing THIS host's key material
+  // (same recipients in practice for a workspace/canonical-clone pair).
+  // Any failure here (existing canonical store undecryptable, sops
+  // encrypt failure) throws and propagates straight out of runSet —
+  // the workspace write below is never reached.
+  if (canonicalClone) {
+    const canonicalPaths = overrides.canonicalPaths || resolveScopePaths({
+      file: canonicalClone,
+      keyDir: paths.keyDir,
+      keyFile: paths.keyFile,
+    });
+
+    let canonicalData = {};
+    if (secretsFileExists(canonicalPaths)) {
+      canonicalData = await decryptStoreForWrite(canonicalPaths);
+    }
+    canonicalData[key] = value;
+    await sopsEncryptScoped(canonicalPaths, canonicalData);
+    console.log(`Secret '${key}' stored in canonical clone (${canonicalPaths.secretsFile}).`);
+  }
+
+  const pubKey = paths.scoped ? null : getPublicKey(paths);
+
+  // A store that exists but cannot be decrypted REFUSES the write — the old
+  // `catch { data = {} }` fallback meant a host without the right age key
+  // would silently replace the vault's entire contents with this one key.
+  let data = {};
+  if (secretsFileExists(paths)) {
+    data = await decryptStoreForWrite(paths);
+  }
+
+  data[key] = value;
+  if (paths.scoped) {
+    await sopsEncryptScoped(paths, data);
+  } else {
+    await sopsEncrypt(paths, pubKey, data);
+  }
+  console.log(`Secret '${key}' stored.`);
+  return 0;
+}

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

@@ -0,0 +1,146 @@
+// status — report vault health.
+// Returns 0 when every core artefact is present, 1 otherwise, so callers
+// can gate operations on initialisation state.
+
+import { readFileSync } from 'node:fs';
+import {
+  defaultPaths,
+  runCmd,
+  hasBinary,
+  keyFileExists,
+  secretsFileExists,
+  recipientsFileExists,
+  sopsConfigExists,
+  sopsDecrypt,
+} from '../vault.mjs';
+
+async function printDepVersions() {
+  console.log('');
+  if (await hasBinary('sops')) {
+    const { stdout, stderr } = await runCmd('sops', ['--version']);
+    const line = ((stdout || stderr).split('\n')[0] || '').trim();
+    console.log(`sops: ${line}`);
+  } else {
+    console.log('sops: NOT INSTALLED');
+  }
+  if (await hasBinary('age')) {
+    const { stdout, stderr } = await runCmd('age', ['--version']);
+    const line = ((stdout || stderr).split('\n')[0] || '').trim();
+    console.log(`age:  ${line}`);
+  } else {
+    console.log('age:  NOT INSTALLED');
+  }
+}
+
+export async function runStatus(overrides = {}) {
+  const paths = overrides.paths || defaultPaths(overrides);
+  if (paths.scoped) return runStatusScoped(paths);
+
+  let ok = true;
+
+  console.log('Vault status');
+  console.log('============');
+  console.log('');
+
+  // Private key
+  if (keyFileExists(paths)) {
+    console.log(`Private key: ${paths.keyFile} (present)`);
+  } else {
+    console.log(`Private key: ${paths.keyFile} (MISSING)`);
+    ok = false;
+  }
+
+  // Recipients
+  if (recipientsFileExists(paths)) {
+    const pub = readFileSync(paths.recipientsFile, 'utf-8').split('\n')[0];
+    console.log(`Public key:  ${pub}`);
+  } else {
+    console.log(`Public key:  ${paths.recipientsFile} (MISSING)`);
+    ok = false;
+  }
+
+  // Secrets file + count
+  if (secretsFileExists(paths)) {
+    if (keyFileExists(paths)) {
+      let count = '?';
+      try {
+        const data = await sopsDecrypt(paths, paths.secretsFile);
+        count = String(Object.keys(data).length);
+      } catch {
+        count = '?';
+      }
+      console.log(`Secrets:     ${paths.secretsFile} (${count} keys)`);
+    } else {
+      console.log(`Secrets:     ${paths.secretsFile} (present, cannot count without private key)`);
+    }
+  } else {
+    console.log(`Secrets:     ${paths.secretsFile} (not created)`);
+    ok = false;
+  }
+
+  // SOPS config
+  if (sopsConfigExists(paths)) {
+    console.log(`SOPS config: ${paths.sopsConfig} (present)`);
+  } else {
+    console.log(`SOPS config: ${paths.sopsConfig} (MISSING)`);
+    ok = false;
+  }
+
+  // Dependency versions
+  await printDepVersions();
+
+  return ok ? 0 : 1;
+}
+
+// Scoped vaults have no recipients.txt — a scope's recipients live in
+// per-file creation_rules inside the shared .sops.yaml, so the "public
+// key" line has no single-value equivalent. Rather than hand-roll a YAML
+// parser to enumerate them for a cosmetic status line (real recipient
+// resolution stays entirely sops's job at encrypt/decrypt time), this
+// points at the config file instead of guessing.
+async function runStatusScoped(paths) {
+  let ok = true;
+  const heading = paths.scope ? `Vault status (scope: ${paths.scope})` : 'Vault status (scoped)';
+
+  console.log(heading);
+  console.log('='.repeat(heading.length));
+  console.log('');
+
+  if (keyFileExists(paths)) {
+    console.log(`Private key: ${paths.keyFile} (present)`);
+  } else {
+    console.log(`Private key: ${paths.keyFile} (MISSING)`);
+    ok = false;
+  }
+
+  if (sopsConfigExists(paths)) {
+    console.log(`SOPS config: ${paths.sopsConfig} (present)`);
+  } else {
+    console.log(`SOPS config: ${paths.sopsConfig} (MISSING)`);
+    ok = false;
+  }
+
+  if (secretsFileExists(paths)) {
+    if (keyFileExists(paths)) {
+      let count = '?';
+      try {
+        const data = await sopsDecrypt(paths, paths.secretsFile);
+        count = String(Object.keys(data).length);
+      } catch {
+        count = '?';
+      }
+      console.log(`Secrets:     ${paths.secretsFile} (${count} keys)`);
+    } else {
+      console.log(`Secrets:     ${paths.secretsFile} (present, cannot count without private key)`);
+    }
+  } else {
+    console.log(`Secrets:     ${paths.secretsFile} (not created)`);
+    ok = false;
+  }
+
+  console.log(`Recipients:  see ${paths.sopsConfig} (per-scope creation_rules; not enumerated in scoped mode)`);
+
+  await printDepVersions();
+
+  return ok ? 0 : 1;
+}

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

@@ -0,0 +1,57 @@
+// vaults — enumerate every vault visible from the resolved workspace:
+// legacy .vault/secrets.enc.json, workspace scopes .vault/scopes/*.enc.json,
+// and canonical vault/*.enc.json. Key counts come from the plaintext
+// structure of the sops JSON (key names are not encrypted; values are) —
+// no decryption, no private key required, no secret material touched.
+//
+// --scope / --file narrow to a single vault (paths arrive pre-resolved
+// from the CLI layer).
+
+import {
+  resolveWorkspaceRoot,
+  enumerateVaults,
+  readVaultKeyNames,
+} from '../vault.mjs';
+
+/** Shared with `find`: turn overrides into the list of vault entries in play. */
+export function vaultEntriesFor(overrides = {}) {
+  const paths = overrides.paths;
+  if (paths && paths.scoped) {
+    return [{
+      scope: paths.scope ?? '(file)',
+      layout: paths.layout === 'workspace' ? 'workspace-scoped' : paths.layout,
+      path: paths.secretsFile,
+    }];
+  }
+  const root = paths?.root
+    ?? resolveWorkspaceRoot({ cwd: overrides.cwd, env: overrides.env, home: overrides.home }).root;
+  return enumerateVaults(root);
+}
+
+export async function runVaults(overrides = {}) {
+  const entries = vaultEntriesFor(overrides);
+
+  if (entries.length === 0) {
+    console.log('No vaults found.');
+    return 1;
+  }
+
+  const rows = entries.map((e) => {
+    const names = readVaultKeyNames(e.path);
+    return { ...e, keys: names == null ? '?' : String(names.length) };
+  });
+
+  const w = (sel, heading) => Math.max(heading.length, ...rows.map((r) => sel(r).length));
+  const cols = [
+    ['SCOPE', (r) => r.scope],
+    ['LAYOUT', (r) => r.layout],
+    ['KEYS', (r) => r.keys],
+    ['PATH', (r) => r.path],
+  ];
+  const widths = cols.map(([h, sel]) => w(sel, h));
+  console.log(cols.map(([h], i) => h.padEnd(widths[i])).join('  ').trimEnd());
+  for (const r of rows) {
+    console.log(cols.map(([, sel], i) => sel(r).padEnd(widths[i])).join('  ').trimEnd());
+  }
+  return 0;
+}