@omega.js/manager 0.1.0

package/dist/lib/env-order.js

@@ -0,0 +1,236 @@
+/**
+ * Canonical .env ordering — the .env sibling of @omega.js/config's
+ * applyCanonicalOrder (cp137, Ian: "reorder our env files like the config
+ * files... moving comments too?").
+ *
+ * The grouping, the group comments, and the key inventory all live in
+ * @omega.js/config's env schema (#581): canonicalEnvGroups() is that schema
+ * rendered as .env sections, the scaffold stub renders from it and every
+ * reorder renders from it, so a freshly scaffolded .env and a years-old
+ * converged one have the same shape — and a key the composer knows can never
+ * be missing from the stub, because both derive from the same entries.
+ *
+ * Machine-owned comments — the boxed `# ── … ──`
+ * group headers, `# KEY=` placeholders, the SSOT note lines — are
+ * REGENERATED on every render (stale text self-heals); hand-written
+ * comments travel verbatim with the key directly below them; the file's
+ * leading comment block stays at the top as the header. Unknown keys keep
+ * their relative order in an "Other" section after the known groups.
+ *
+ * Duplicate keys collapse to the LAST occurrence — dotenv.parse's winner,
+ * so the effective value can never change — and hand comments from dropped
+ * occurrences move to the kept one.
+ *
+ * Loss-proof by construction: a structural pre-check accepts only comment /
+ * blank / KEY=value lines (anything else — multi-line quoted values,
+ * `export` forms — declines untouched), kept lines are carried VERBATIM,
+ * and a key→value equality post-check (last-wins, both sides) refuses to
+ * return a reorder that changed any effective value.
+ */
+
+const { envFileGroups, envKeysByGroup, envLine } = require('../vendor/config/index.js');
+
+/**
+ * The canonical .env sections: every schema group that renders into a file,
+ * in schema order, with its keys. Derived on every call so a key added to the
+ * schema needs no edit here (and the group's own `notes` travel with it).
+ *
+ * @returns {Array<{comment: string, notes?: string[], keys: string[]}>}
+ */
+function canonicalEnvGroups() {
+  const byGroup = envKeysByGroup();
+
+  return envFileGroups()
+    .map((group) => ({ comment: group.comment, notes: group.notes, keys: byGroup[group.id] || [] }))
+    .filter((group) => group.keys.length > 0);
+}
+
+const OTHER_COMMENT = 'Other keys (not in the canonical groups)';
+
+// Machine-owned comment lines are regenerated from the SSOT on every render,
+// so the parser drops them: boxed group headers (current or stale text),
+// `# KEY=` placeholders, the groups' own note lines, and the legacy scaffold
+// trailer (pre-cp137 stubs mentioned the auto-generated keys in prose).
+const MACHINE_COMMENT_PATTERNS = [
+  /^# ── .* ──$/,
+  /^# [A-Za-z_][A-Za-z0-9_]*=$/,
+];
+const MACHINE_COMMENT_EXACT = [
+  '# Auto-generated and persisted here on the first real run — leave unset:',
+  '# ACCOUNT_PASSWORD_SEED, CSC_KEY_PASSWORD',
+];
+
+function isMachineComment(line, groups) {
+  return MACHINE_COMMENT_EXACT.includes(line)
+    || groups.some((group) => (group.notes || []).some((note) => `# ${note}` === line))
+    || MACHINE_COMMENT_PATTERNS.some((pattern) => pattern.test(line));
+}
+
+const KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
+
+/**
+ * Parse a simple .env file into header, keyed entries, and stray comment
+ * blocks. Returns { unparseable: reason } when any line is neither a
+ * comment, blank, nor single-line KEY=value — the caller declines to
+ * reorder rather than risk a legal-but-exotic dotenv construct.
+ */
+function parseEnvFile(content) {
+  const groups = canonicalEnvGroups();
+  const header = [];
+  const entries = new Map(); // key → { raw, handComments: string[], order }
+  const strays = [];
+  let pending = [];
+  let sawKey = false;
+  let order = 0;
+
+  const flushStandalone = () => {
+    if (pending.length === 0) return;
+    if (!sawKey && header.length === 0) {
+      header.push(...pending);
+    } else {
+      strays.push(pending);
+    }
+    pending = [];
+  };
+
+  const lines = content.split('\n');
+  // A trailing newline yields one empty last element — structural, not a line
+  if (lines[lines.length - 1] === '') lines.pop();
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') {
+      flushStandalone();
+      continue;
+    }
+    if (line.trimStart().startsWith('#')) {
+      if (!isMachineComment(line, groups)) pending.push(line);
+      continue;
+    }
+    const match = KEY_LINE.exec(line);
+    if (!match) {
+      return { unparseable: `line ${i + 1} is not a comment, blank, or single-line KEY=value` };
+    }
+    sawKey = true;
+    const key = match[1];
+    const existing = entries.get(key);
+    if (existing) {
+      // Last occurrence wins (dotenv.parse semantics) — its raw line is
+      // kept verbatim; hand comments from every occurrence merge onto it
+      existing.raw = line;
+      existing.handComments.push(...pending);
+    } else {
+      entries.set(key, { raw: line, handComments: pending, order: order++ });
+    }
+    pending = [];
+  }
+  flushStandalone();
+
+  return { header, entries, strays };
+}
+
+/**
+ * Render the canonical .env layout: header, every group (real lines
+ * verbatim where present, `# KEY=` placeholders otherwise), then unknown
+ * keys and stray comment blocks under an "Other" section.
+ *
+ * @param {object} input
+ * @param {string[]} [input.header] - Verbatim comment lines for the top.
+ * @param {Map<string, {raw: string, handComments?: string[]}>|object} [input.entries] -
+ *   key → entry; `raw` is the exact line to emit for that key.
+ * @param {Array<string[]>} [input.strays] - Standalone comment blocks.
+ * @returns {string} File content, trailing newline included.
+ */
+function renderCanonicalEnv({ header = [], entries = new Map(), strays = [] } = {}) {
+  const entryMap = entries instanceof Map ? entries : new Map(Object.entries(entries));
+  const groups = canonicalEnvGroups();
+  const knownKeys = new Set(groups.flatMap((group) => group.keys));
+  const out = [];
+
+  if (header.length > 0) {
+    out.push(...header, '');
+  }
+
+  for (const group of groups) {
+    out.push(`# ── ${group.comment} ──`);
+    for (const note of group.notes || []) {
+      out.push(`# ${note}`);
+    }
+    for (const key of group.keys) {
+      const entry = entryMap.get(key);
+      if (entry) {
+        out.push(...(entry.handComments || []), entry.raw);
+      } else {
+        out.push(`# ${key}=`);
+      }
+    }
+    out.push('');
+  }
+
+  const unknown = [...entryMap.entries()]
+    .filter(([key]) => !knownKeys.has(key))
+    .sort(([, a], [, b]) => (a.order ?? 0) - (b.order ?? 0));
+  if (unknown.length > 0 || strays.length > 0) {
+    out.push(`# ── ${OTHER_COMMENT} ──`);
+    for (const [, entry] of unknown) {
+      out.push(...(entry.handComments || []), entry.raw);
+    }
+    for (const block of strays) {
+      out.push(...block);
+    }
+    out.push('');
+  }
+
+  return `${out.join('\n').replace(/\n+$/, '')}\n`;
+}
+
+/** key → verbatim value string, last occurrence wins — the equality probe. */
+function effectiveValues(content) {
+  const values = new Map();
+  for (const line of content.split('\n')) {
+    const match = KEY_LINE.exec(line);
+    if (match) values.set(match[1], match[2]);
+  }
+  return values;
+}
+
+/**
+ * Reorder .env content into the canonical layout, loss-proof.
+ *
+ * @param {string} content - Current file content.
+ * @param {object} [options]
+ * @param {string[]} [options.defaultHeader] - Header comment lines used only
+ *   when the file has none of its own.
+ * @returns {{ content: string, changed: boolean, skipped?: string, duplicatesCollapsed?: number }}
+ *   `skipped` names why the content was left untouched (unrecognized
+ *   structure, or the paranoia check tripping).
+ */
+function applyEnvOrder(content, { defaultHeader = [] } = {}) {
+  const parsed = parseEnvFile(content);
+  if (parsed.unparseable) {
+    return { content, changed: false, skipped: parsed.unparseable };
+  }
+
+  const keyLineCount = content.split('\n').filter((line) => KEY_LINE.test(line)).length;
+  const duplicatesCollapsed = keyLineCount - parsed.entries.size;
+
+  const rendered = renderCanonicalEnv({
+    header: parsed.header.length > 0 ? parsed.header : defaultHeader,
+    entries: parsed.entries,
+    strays: parsed.strays,
+  });
+
+  // Paranoia post-check: every key's effective value must survive verbatim
+  const before = effectiveValues(content);
+  const after = effectiveValues(rendered);
+  if (before.size !== after.size || [...before].some(([key, value]) => after.get(key) !== value)) {
+    return { content, changed: false, skipped: 'reorder would change effective values (bug guard)' };
+  }
+
+  return { content: rendered, changed: rendered !== content, duplicatesCollapsed };
+}
+
+// `envLine` is @omega.js/config's serializer, re-exported so the manager's
+// writebacks keep one import — the escaping rules live there, with the
+// composer that has to read them back.
+module.exports = { canonicalEnvGroups, envLine, renderCanonicalEnv, applyEnvOrder };

package/dist/lib/env-secret.js

@@ -0,0 +1,78 @@
+/**
+ * Brand .env writeback — persist a secret so every future run (and CI)
+ * sees the same value. Used for machine-generated secrets that only have
+ * to stay stable (CSC_KEY_PASSWORD, ACCOUNT_PASSWORD_SEED) and for
+ * interactively-entered ones (the payment provider-setup flows). Replaces
+ * the variable's line in place when it already exists, appends otherwise —
+ * then applies the canonical ordering (env-order.js, cp137), the same way
+ * writeConfigValues applies the omega.json5 canonical order on every
+ * writeback. The order pass is a polish step: if it declines (exotic file
+ * structure), the plain replace/append result is written unchanged.
+ *
+ * mintGeneratedKey is the ONE mint for the keys OMEGA generates for itself
+ * (the env schema's `generated:` set): the workspace service's env-keys op
+ * does it for the whole set up front, the setup contract (lib/service-input.js)
+ * does it for a single key a service reached first — same write, same export,
+ * same success line, so a brand cannot tell which one got there first.
+ */
+const { join } = require('node:path');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+
+const { generatedEnvKeys } = require('../vendor/config/index.js');
+const { applyEnvOrder, envLine } = require('./env-order.js');
+
+/**
+ * Write NAME="value" into the brand .env (replace-or-append).
+ *
+ * @param {string} brandRoot - Brand-monorepo root (its .env is the target)
+ * @param {string} name - Env var name, e.g. 'CSC_KEY_PASSWORD'
+ * @param {string} value - Value to persist
+ */
+function writeEnvValue(brandRoot, name, value) {
+  const envPath = join(brandRoot, '.env');
+  // envLine escapes \ " and newlines (env-order.js's serializer — the SSOT);
+  // the replacer FUNCTION keeps $& / $1 in a secret from being expanded by String.replace
+  const line = envLine(name, value);
+  const pattern = new RegExp(`^${name}\\s*=.*$`, 'm');
+
+  let envContent = jetpack.exists(envPath) ? jetpack.read(envPath) : '';
+  if (pattern.test(envContent)) {
+    envContent = envContent.replace(pattern, () => line);
+  } else {
+    // Terminate any existing content with exactly one newline, then append
+    envContent = envContent === '' ? '' : envContent.replace(/\n*$/, '\n');
+    envContent += `${line}\n`;
+  }
+  jetpack.write(envPath, applyEnvOrder(envContent).content);
+}
+
+/**
+ * Mint one of OMEGA's own generated keys into the brand .env and into THIS
+ * process's env, so the same run that minted it can use it. Values are never
+ * printed — the line names the key only.
+ *
+ * @param {string} brandRoot - Brand-monorepo root (its .env is the target)
+ * @param {string} name - An env-schema `generated:` key, e.g. 'OMEGA_WEBHOOK_KEY'
+ * @param {object} [options]
+ * @param {string} [options.indent] - Leading spaces for the success line, so a
+ *   service-level caller and an operation-level one both sit at their own depth
+ * @returns {string} The minted value
+ */
+function mintGeneratedKey(brandRoot, name, options = {}) {
+  const generate = generatedEnvKeys()[name];
+  if (!generate) {
+    // Programmer error: only the env schema says what OMEGA can mint, so a
+    // name that is not in that set has no generator and never will
+    throw new Error(`${name} is not a generated env key — nothing can mint it`);
+  }
+
+  const value = generate();
+  writeEnvValue(brandRoot, name, value);
+  process.env[name] = value;
+  console.log(`${options.indent ?? '      '}${chalk.green('✓')} ${name} minted into the brand .env`);
+
+  return value;
+}
+
+module.exports = { writeEnvValue, mintGeneratedKey };

package/dist/lib/firestore-rest.js

@@ -0,0 +1,326 @@
+/**
+ * Firestore REST client authenticated with a Google service account —
+ * the non-interactive replacement for omega-manager's firebase-admin
+ * `getFirestore(brandId)` (which read `.output/{brandId}/secrets/`).
+ *
+ * Used by the services that write into an external product's Firestore
+ * (forms, and chat/email when they port): the operator provides a
+ * service-account JSON for that product's Firebase project via an env var
+ * holding a file path (absolute, or relative to the brand root — e.g.
+ * `.omega/secrets/slapform-service-account.json`).
+ *
+ * Auth is a plain RS256 JWT-bearer grant (node:crypto — no SDK dependency).
+ * Documents cross the API as plain JS objects; the Firestore typed-value
+ * encoding is internal. Handlers call named methods (getDoc/patchDoc/setDoc)
+ * so tests fake this surface method-for-method.
+ */
+const { isAbsolute, join } = require('node:path');
+const fs = require('node:fs');
+
+const { createTokenProvider } = require('./google-token.js');
+
+const FIRESTORE_API_BASE = 'https://firestore.googleapis.com/v1';
+const SCOPE = 'https://www.googleapis.com/auth/datastore';
+
+/**
+ * Load and validate a service-account JSON from an env-provided path.
+ *
+ * @param {string} envValue - Path from the env var (absolute or brand-root-relative)
+ * @param {string} brandRoot - Brand-monorepo root for resolving relative paths
+ * @returns {Object} Parsed service-account credentials
+ */
+function loadServiceAccount(envValue, brandRoot) {
+  const path = isAbsolute(envValue) ? envValue : join(brandRoot, envValue);
+
+  if (!fs.existsSync(path)) {
+    throw new Error(`Service-account file not found at ${path}`);
+  }
+
+  let serviceAccount;
+  try {
+    serviceAccount = JSON.parse(fs.readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`Service-account file at ${path} is not valid JSON: ${error.message}`);
+  }
+
+  if (!serviceAccount.project_id || !serviceAccount.client_email || !serviceAccount.private_key) {
+    throw new Error(`Service-account file at ${path} is missing project_id/client_email/private_key`);
+  }
+
+  return serviceAccount;
+}
+
+/**
+ * Encode a plain JS value as a Firestore typed value.
+ */
+function encodeValue(value) {
+  if (value === null || value === undefined) {
+    return { nullValue: null };
+  }
+  if (typeof value === 'boolean') {
+    return { booleanValue: value };
+  }
+  if (typeof value === 'number') {
+    // REST integers are string-encoded (int64)
+    return Number.isInteger(value) ? { integerValue: String(value) } : { doubleValue: value };
+  }
+  if (typeof value === 'string') {
+    return { stringValue: value };
+  }
+  if (Array.isArray(value)) {
+    return { arrayValue: { values: value.map(encodeValue) } };
+  }
+  if (typeof value === 'object') {
+    return { mapValue: { fields: encodeFields(value) } };
+  }
+  throw new Error(`Cannot encode value of type ${typeof value} for Firestore`);
+}
+
+function encodeFields(obj) {
+  const fields = {};
+  for (const [key, value] of Object.entries(obj)) {
+    fields[key] = encodeValue(value);
+  }
+  return fields;
+}
+
+/**
+ * Decode a Firestore typed value back to plain JS.
+ */
+function decodeValue(typed) {
+  if ('nullValue' in typed) return null;
+  if ('booleanValue' in typed) return typed.booleanValue;
+  if ('integerValue' in typed) return parseInt(typed.integerValue, 10);
+  if ('doubleValue' in typed) return typed.doubleValue;
+  if ('stringValue' in typed) return typed.stringValue;
+  if ('timestampValue' in typed) return typed.timestampValue;
+  if ('referenceValue' in typed) return typed.referenceValue;
+  if ('arrayValue' in typed) return (typed.arrayValue.values || []).map(decodeValue);
+  if ('mapValue' in typed) return decodeFields(typed.mapValue.fields || {});
+  return null;
+}
+
+function decodeFields(fields) {
+  const obj = {};
+  for (const [key, typed] of Object.entries(fields)) {
+    obj[key] = decodeValue(typed);
+  }
+  return obj;
+}
+
+class FirestoreREST {
+  constructor(serviceAccount) {
+    this.serviceAccount = serviceAccount;
+    this.projectId = serviceAccount.project_id;
+    this.tokenProvider = createTokenProvider(serviceAccount, SCOPE);
+  }
+
+  /**
+   * Access token for the datastore scope (cached by the shared provider).
+   */
+  getAccessToken() {
+    return this.tokenProvider.getAccessToken();
+  }
+
+  async request(method, docPath, { query, body } = {}) {
+    const token = await this.getAccessToken();
+    const url = new URL(`${FIRESTORE_API_BASE}/projects/${this.projectId}/databases/(default)/documents/${docPath}`);
+
+    for (const [key, values] of Object.entries(query || {})) {
+      for (const value of [].concat(values)) {
+        url.searchParams.append(key, value);
+      }
+    }
+
+    const response = await fetch(url, {
+      method,
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      throw new Error(`Firestore API error: ${data.error?.message || JSON.stringify(data)}`);
+    }
+
+    return data;
+  }
+
+  /**
+   * POST to a colon method on the documents root (documents:runQuery,
+   * documents:runAggregationQuery) — those can't go through request()'s
+   * docPath URL builder.
+   */
+  async rootRequest(method, body) {
+    const token = await this.getAccessToken();
+    const url = `${FIRESTORE_API_BASE}/projects/${this.projectId}/databases/(default)/documents:${method}`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30000),
+    });
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      throw new Error(`Firestore API error: ${data.error?.message || JSON.stringify(data)}`);
+    }
+
+    return data;
+  }
+
+  /**
+   * Read a document as a plain JS object. Missing document → null.
+   *
+   * @param {string} docPath - e.g. 'forms/abc123'
+   */
+  async getDoc(docPath) {
+    const doc = await this.request('GET', docPath);
+    return doc ? decodeFields(doc.fields || {}) : null;
+  }
+
+  /**
+   * Read a document with its server metadata — the REST stand-in for the
+   * admin SDK's DocumentSnapshot (create/update times are ISO strings).
+   * Missing document → null.
+   *
+   * @param {string} docPath - e.g. 'users/uid123'
+   * @returns {Promise<{ id, createTime, updateTime, data }|null>}
+   */
+  async getDocWithMeta(docPath) {
+    const doc = await this.request('GET', docPath);
+    if (!doc) {
+      return null;
+    }
+    return {
+      id: doc.name.split('/').pop(),
+      createTime: doc.createTime,
+      updateTime: doc.updateTime,
+      data: decodeFields(doc.fields || {}),
+    };
+  }
+
+  /**
+   * List one page of a collection's documents (ordered by name — Firestore's
+   * listDocuments default), with server metadata like getDocWithMeta.
+   *
+   * @param {string} collectionPath - e.g. 'users'
+   * @param {Object} [options]
+   * @param {number} [options.pageSize=500]
+   * @param {string} [options.pageToken] - From the previous page's nextPageToken
+   * @returns {Promise<{ docs: Array<{ id, createTime, updateTime, data }>, nextPageToken: string|null }>}
+   */
+  async listDocs(collectionPath, { pageSize = 500, pageToken } = {}) {
+    const query = { pageSize };
+    if (pageToken) {
+      query.pageToken = pageToken;
+    }
+
+    const data = (await this.request('GET', collectionPath, { query })) || {};
+
+    return {
+      docs: (data.documents || []).map((doc) => ({
+        id: doc.name.split('/').pop(),
+        createTime: doc.createTime,
+        updateTime: doc.updateTime,
+        data: decodeFields(doc.fields || {}),
+      })),
+      nextPageToken: data.nextPageToken || null,
+    };
+  }
+
+  /**
+   * Count a collection's documents server-side (aggregation query — no
+   * document reads billed beyond the aggregation).
+   *
+   * @param {string} collectionId - Top-level collection id, e.g. 'users'
+   * @returns {Promise<number>}
+   */
+  async countDocs(collectionId) {
+    const data = await this.rootRequest('runAggregationQuery', {
+      structuredAggregationQuery: {
+        structuredQuery: { from: [{ collectionId }] },
+        aggregations: [{ alias: 'count', count: {} }],
+      },
+    });
+
+    const entry = (data || []).find((e) => e.result);
+    return entry ? parseInt(entry.result.aggregateFields.count.integerValue, 10) : 0;
+  }
+
+  /**
+   * Delete a document. Deleting a missing document is a no-op (Firestore
+   * returns success either way).
+   *
+   * @param {string} docPath - e.g. 'users/uid123'
+   */
+  async deleteDoc(docPath) {
+    return this.request('DELETE', docPath);
+  }
+
+  /**
+   * Merge-write specific fields of a document (created if missing) — the
+   * REST equivalent of the admin SDK's `set(data, { merge: true })`:
+   * updateMask carries the LEAF field paths so sibling fields the caller
+   * doesn't mention survive untouched.
+   *
+   * @param {string} docPath - e.g. 'users/uid123'
+   * @param {Object} data - Plain nested object with the desired values
+   * @param {string[]} fieldPaths - Dotted leaf paths to write (the updateMask)
+   */
+  async patchDoc(docPath, data, fieldPaths) {
+    return this.request('PATCH', docPath, {
+      query: { 'updateMask.fieldPaths': fieldPaths },
+      body: { fields: encodeFields(data) },
+    });
+  }
+
+  /**
+   * Replace-write a whole document (created if missing) — the REST
+   * equivalent of the admin SDK's `set(data, { merge: false })`: no
+   * updateMask, so fields absent from `data` are removed from the document.
+   *
+   * @param {string} docPath - e.g. 'brands/my-brand'
+   * @param {Object} data - Plain nested object; becomes the ENTIRE document
+   */
+  async setDoc(docPath, data) {
+    return this.request('PATCH', docPath, {
+      body: { fields: encodeFields(data) },
+    });
+  }
+
+  /**
+   * Run a structured query and return matching documents as plain objects.
+   *
+   * @param {Object} structuredQuery - Firestore StructuredQuery, e.g.
+   *   { from: [{ collectionId: 'users' }], where: { fieldFilter: ... } }
+   * @returns {Promise<Array<{ id: string, data: Object }>>}
+   */
+  async runQuery(structuredQuery) {
+    const data = await this.rootRequest('runQuery', { structuredQuery });
+
+    // Streamed response: one entry per result, some carry only readTime
+    return data
+      .filter((entry) => entry.document)
+      .map((entry) => ({
+        id: entry.document.name.split('/').pop(),
+        data: decodeFields(entry.document.fields || {}),
+      }));
+  }
+}
+
+module.exports = { FirestoreREST, loadServiceAccount, encodeFields, decodeFields };