@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-workspace/src/nav.mjs

@@ -0,0 +1,190 @@
+/**
+ * Workspace nav manifest loader.
+ *
+ * Reads the core manifest at core/tools/workspace/app/nav.json and, if present,
+ * the operator extension manifest at operator/extensions/workspace/nav.json.
+ * Merges them into a single ordered list of nav items.
+ *
+ * Merge rules:
+ *   - Core items come first, in manifest order.
+ *   - Extension items are appended; on id collision, the extension entry
+ *     replaces the core entry in place (extension wins, warning logged).
+ *   - A missing or absent operator manifest is not an error.
+ *   - A malformed manifest is logged and skipped; the other side still loads.
+ *
+ * Caching: each load checks both manifest mtimes. The cached merged list is
+ * returned unchanged if neither file changed since the last load. Missing
+ * files are tracked with mtime 0 so their appearance triggers a reload.
+ */
+
+import { readFileSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CACHE = {
+  coreMtimeMs: -1,
+  extMtimeMs: -1,
+  items: null,
+};
+
+function mtime(path) {
+  try { return statSync(path).mtimeMs; } catch { return 0; }
+}
+
+function validateItem(raw, source, warn) {
+  if (!raw || typeof raw !== 'object') {
+    warn('[nav] warning: ' + source + ' contains a non-object entry, skipping');
+    return null;
+  }
+  if (typeof raw.id !== 'string' || !raw.id) {
+    warn('[nav] warning: ' + source + ' entry missing string "id", skipping');
+    return null;
+  }
+  if (typeof raw.label !== 'string' || !raw.label) {
+    warn('[nav] warning: ' + source + ' entry "' + raw.id + '" missing string "label", skipping');
+    return null;
+  }
+  if (typeof raw.href !== 'string' || !raw.href) {
+    warn('[nav] warning: ' + source + ' entry "' + raw.id + '" missing string "href", skipping');
+    return null;
+  }
+  const item = {
+    id: raw.id,
+    label: raw.label,
+    href: raw.href,
+    section: typeof raw.section === 'string' && raw.section ? raw.section : 'Workspace',
+  };
+  if (Array.isArray(raw.aliases)) {
+    item.aliases = raw.aliases.filter(function(a) { return typeof a === 'string' && a; });
+  } else {
+    item.aliases = [];
+  }
+  return item;
+}
+
+function readManifest(path, source, warn) {
+  if (!existsSync(path)) return [];
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (e) {
+    warn('[nav] warning: ' + source + ' is not valid JSON (' + e.message + '), skipping');
+    return [];
+  }
+  if (!Array.isArray(raw)) {
+    warn('[nav] warning: ' + source + ' must be a JSON array, got ' + typeof raw + ', skipping');
+    return [];
+  }
+  const items = [];
+  for (let i = 0; i < raw.length; i++) {
+    const item = validateItem(raw[i], source, warn);
+    if (item) items.push(item);
+  }
+  return items;
+}
+
+/**
+ * Merge core and extension items. Extension items with a matching id replace
+ * the corresponding core item in its original slot (preserving core ordering)
+ * and emit a warning. Extension items with no collision are appended in
+ * manifest order.
+ */
+function mergeItems(coreItems, extItems, warn) {
+  const merged = coreItems.slice();
+  const indexById = new Map();
+  for (let i = 0; i < merged.length; i++) {
+    indexById.set(merged[i].id, i);
+  }
+  for (const ext of extItems) {
+    if (indexById.has(ext.id)) {
+      warn('[nav] warning: extension nav id "' + ext.id + '" shadows core item');
+      merged[indexById.get(ext.id)] = ext;
+    } else {
+      indexById.set(ext.id, merged.length);
+      merged.push(ext);
+    }
+  }
+  return merged;
+}
+
+/**
+ * Validate that every item's href resolves to an existing page, either under
+ * APP_DIR or EXT_DIR (for top-level /<name>.html). Non-resolving items are
+ * kept in the list with a warning so operators can see their work-in-progress.
+ */
+function warnOnMissingHrefs(items, appDir, extDir, warn) {
+  for (const item of items) {
+    const href = item.href;
+    // Core-shape paths: /core/tools/workspace/app/<file>
+    const corePrefix = '/core/tools/workspace/app/';
+    if (href.indexOf(corePrefix) === 0) {
+      const name = href.slice(corePrefix.length).split('?')[0].split('#')[0];
+      if (!existsSync(join(appDir, name))) {
+        warn('[nav] warning: nav item "' + item.id + '" points at missing page ' + href);
+      }
+      continue;
+    }
+    // Top-level extension-shape: /<file>.html
+    const topMatch = href.match(/^\/([^/?#]+\.html)(?:[?#].*)?$/);
+    if (topMatch) {
+      const name = topMatch[1];
+      const inExt = extDir && existsSync(join(extDir, name));
+      const inApp = existsSync(join(appDir, name));
+      if (!inExt && !inApp) {
+        warn('[nav] warning: nav item "' + item.id + '" points at missing page ' + href);
+      }
+      continue;
+    }
+    // Any other shape we leave alone — might be an external link or a deep core path.
+  }
+}
+
+/**
+ * Returns the merged nav items array. Reads from disk when either manifest's
+ * mtime has changed since the previous call; otherwise returns the cached list.
+ *
+ * @param {object} opts
+ * @param {string} opts.appDir   absolute path to core app dir
+ * @param {string} [opts.extDir] absolute path to operator extension dir
+ * @param {function(string):void} [opts.warn] warning sink (defaults to console.warn)
+ * @returns {Array<{id:string,label:string,href:string,section:string,aliases:string[]}>}
+ */
+export function loadNav(opts) {
+  const appDir = opts.appDir;
+  const extDir = opts.extDir || null;
+  const warn = opts.warn || function(m) { console.warn(m); };
+
+  const coreManifest = join(appDir, 'nav.json');
+  const extManifest = extDir ? join(extDir, 'nav.json') : null;
+
+  const coreMtime = mtime(coreManifest);
+  const extMtime = extManifest ? mtime(extManifest) : 0;
+
+  if (
+    CACHE.items !== null &&
+    CACHE.coreMtimeMs === coreMtime &&
+    CACHE.extMtimeMs === extMtime
+  ) {
+    return CACHE.items;
+  }
+
+  const coreItems = readManifest(coreManifest, 'core nav manifest', warn);
+  const extItems = extManifest
+    ? readManifest(extManifest, 'extension nav manifest', warn)
+    : [];
+  const merged = mergeItems(coreItems, extItems, warn);
+  warnOnMissingHrefs(merged, appDir, extDir, warn);
+
+  CACHE.coreMtimeMs = coreMtime;
+  CACHE.extMtimeMs = extMtime;
+  CACHE.items = merged;
+  return merged;
+}
+
+/**
+ * Test-only helper: clear the in-memory cache so reloads re-read manifests.
+ */
+export function _resetNavCache() {
+  CACHE.coreMtimeMs = -1;
+  CACHE.extMtimeMs = -1;
+  CACHE.items = null;
+}

package/dist/engineering-pa-workspace/src/secrets-api.mjs

@@ -0,0 +1,175 @@
+// secrets-api.mjs — in-process bridge to the vault module.
+//
+// History:
+//   v0.1.4  spawned `node core/tools/secrets/bin/secrets` — a v1 path that
+//           doesn't exist in v2 installs, so every GET reported
+//           initialised:false on healthy vaults (w-2026-05-18-014).
+//   v0.1.5  imported the vault primitives in-process, but only spoke to the
+//           LEGACY single-file vault — on the live estate that hid 29 of 50
+//           secrets (the scoped vaults) and silently pointed every write at
+//           the legacy store.
+//   v0.5.3  (this file) rebuilt on the scoped-vault primitives:
+//           enumerateVaults + readVaultKeyNames for listing (key NAMES are
+//           plaintext in sops JSON — no decryption, no age key, no binaries
+//           needed to list), and explicit-target writes (legacy OR scope) —
+//           a write with no vault target is refused, never defaulted.
+//
+// Values are NEVER returned by any function in this module.
+
+import {
+  defaultPaths,
+  resolveScopePaths,
+  enumerateVaults,
+  readVaultKeyNames,
+  checkDeps,
+  checkVault,
+  getPublicKey,
+  secretsFileExists,
+  sopsDecrypt,
+  sopsEncrypt,
+  sopsEncryptScoped,
+} from '../../engineering-pa-cli/src/secrets/vault.mjs';
+
+/** Sentinel accepted (in either spelling) as the explicit legacy-vault target. */
+const LEGACY_TARGETS = new Set(['legacy', '(legacy)']);
+
+export const MISSING_TARGET_ERROR =
+  "Missing vault target — pass vault: 'legacy' or a scope name. Writes never default to a vault silently.";
+
+/**
+ * Enumerate every vault visible from the workspace and their key NAMES.
+ * No decryption anywhere on this path: names come from the plaintext
+ * structure of the sops JSON, so this works with no age key and no
+ * sops/age binaries installed.
+ *
+ * Returns:
+ *   {
+ *     initialised: boolean,   // at least one vault store file visible
+ *     vaults: [{ scope, layout, path, keys: string[] }],
+ *     keys: string[],         // flat sorted union — back-compat for
+ *                             // consumers of the pre-0.5.3 shape
+ *   }
+ *
+ * @param {string} repoRoot
+ * @param {object} [overrides]                 Injected for tests.
+ * @param {Function} [overrides.enumerate]     (root) => [{scope,layout,path}].
+ * @param {Function} [overrides.readKeyNames]  (path) => string[]|null.
+ */
+export async function getSecretsStatus(repoRoot, overrides = {}) {
+  const enumerate = overrides.enumerate || enumerateVaults;
+  const readKeyNames = overrides.readKeyNames || readVaultKeyNames;
+
+  const vaults = enumerate(repoRoot).map((v) => ({
+    scope: v.scope,
+    layout: v.layout,
+    path: v.path,
+    keys: readKeyNames(v.path) ?? [],
+  }));
+
+  const union = new Set();
+  for (const v of vaults) for (const k of v.keys) union.add(k);
+
+  return {
+    initialised: vaults.length > 0,
+    vaults,
+    keys: [...union].sort(),
+  };
+}
+
+/**
+ * Upsert a secret into an EXPLICITLY targeted vault. Returns
+ * `{ success: true }` or `{ success: false, error }` — never throws.
+ *
+ * `vault` is required: the string 'legacy' (or '(legacy)') for the legacy
+ * single-file vault, or a scope name for a scoped vault. There is no
+ * default — a missing target is refused so a UI or caller bug can never
+ * silently write a secret into the wrong store.
+ *
+ * @param {string} repoRoot
+ * @param {string} key
+ * @param {string} value
+ * @param {string} vault                       REQUIRED explicit target.
+ * @param {object} [overrides]                 Injected for tests.
+ * @returns {Promise<{success: boolean, error?: string}>}
+ */
+export async function setSecret(repoRoot, key, value, vault, overrides = {}) {
+  if (!key || value == null || value === '') {
+    return { success: false, error: 'Missing key or value' };
+  }
+  if (!vault || typeof vault !== 'string') {
+    return { success: false, error: MISSING_TARGET_ERROR };
+  }
+
+  const checkDepsFn = overrides.checkDeps || checkDeps;
+  const checkVaultFn = overrides.checkVault || checkVault;
+  const getPubFn = overrides.getPublicKey || getPublicKey;
+  const decryptFn = overrides.decrypt || sopsDecrypt;
+  const encryptFn = overrides.encrypt || sopsEncrypt;
+  const encryptScopedFn = overrides.encryptScoped || sopsEncryptScoped;
+
+  const isLegacy = LEGACY_TARGETS.has(vault);
+
+  let paths;
+  try {
+    if (overrides.makePaths) {
+      paths = overrides.makePaths(vault);
+    } else if (isLegacy) {
+      paths = defaultPaths({ root: repoRoot });
+    } else {
+      // Scope-name validation, workspace/canonical layout resolution, and
+      // ambiguity refusal all live in resolveScopePaths. cwd is pinned to
+      // the workspace root the server was started for.
+      paths = resolveScopePaths({ scope: vault, cwd: repoRoot, env: overrides.env, home: overrides.home });
+    }
+  } catch (err) {
+    return { success: false, error: err && err.message ? err.message : String(err) };
+  }
+
+  const missingDeps = await checkDepsFn();
+  if (missingDeps.length > 0) {
+    return { success: false, error: `missing dependency: ${missingDeps[0]}` };
+  }
+
+  const vaultState = checkVaultFn(paths);
+  if (!vaultState.ok) {
+    return { success: false, error: vaultState.message || 'vault not initialised' };
+  }
+
+  // Legacy encrypts to an explicit --age recipient from recipients.txt;
+  // scoped vaults have no recipients.txt — recipients come from the scope's
+  // own .sops.yaml creation_rule inside sopsEncryptScoped.
+  const pubKey = isLegacy ? getPubFn(paths) : null;
+
+  let data = {};
+  if (secretsFileExists(paths)) {
+    try {
+      data = await decryptFn(paths, paths.secretsFile);
+    } catch (err) {
+      // The pre-0.5.3 bridge (and the CLI's `set`) fall back to `data = {}`
+      // here — which REPLACES the entire store on the next encrypt if this
+      // host merely can't decrypt it (key not a recipient, wrong key, sops
+      // hiccup). That is the vault-clobber incident class. The workspace API
+      // refuses instead: an existing store you can't read is never a store
+      // you may overwrite.
+      const detail = err && err.message ? err.message : String(err);
+      return {
+        success: false,
+        error: `refusing to write: existing store at ${paths.secretsFile} could not be decrypted (${detail}) — writing would replace its contents`,
+      };
+    }
+  }
+
+  data[key] = value;
+
+  try {
+    if (isLegacy) {
+      await encryptFn(paths, pubKey, data);
+    } else {
+      await encryptScopedFn(paths, data);
+    }
+  } catch (err) {
+    return { success: false, error: err && err.message ? err.message : String(err) };
+  }
+
+  return { success: true };
+}