@omega.js/manager 0.1.0

package/dist/services/migrations/index.js

@@ -0,0 +1,101 @@
+/**
+ * Migrations service — runs migrations on the brand's Firestore collections
+ * and (`local: true` operations) on the brand's own files. Only runs when the
+ * --migration flag is set (bare = all migrations, --migration=<name> = just
+ * that one), so a normal manage run never touches collection data. Even then
+ * the run is an AUDIT: it prints what every fix WOULD do and writes nothing
+ * until `--execute`.
+ *
+ * The framework (runner, validator, snapshots) plus the two canonical
+ * @omega.js/backend-schema migrations (notifications, users) are ported from
+ * omega-manager; its other 25 registered migrations are company-instance
+ * one-offs (per-target data repairs) and stay there. firebase-admin is
+ * replaced by the shared Identity Toolkit + FirestoreREST clients over the
+ * brand's own service account. The orders and payments-intents migrations are
+ * native to OMEGA: they carry the same #384 attribution fold as users and
+ * notifications onto the two payment collections. payment-provider is native
+ * too — the #428 word rename's data half, sweeping the stored `processor`
+ * field to `provider` across all five payment-touching collections.
+ * Two are `local: true` — they work on the brand's own files, so they need
+ * neither a backend target nor a service account: state-retirement moves the
+ * retired .omega/state.json CONTENT into config + .env and leaves the file's
+ * machine records untouched (#434, #479), and targets-rename
+ * moves a pre-#443 brand's apps/ folder to targets/. The rename is also the
+ * one migration a walk never reaches on the brand it fixes (discovery fails
+ * loud on the old shape), so `--migration=targets-rename` runs it alone from
+ * runManage; here it only ever re-checks a converged brand.
+ *
+ * Add new migrations by creating handlers in ensure/ and registering them
+ * in config.js OPERATIONS.migrations.
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { FirestoreREST, loadServiceAccount } = require('../../lib/firestore-rest.js');
+const { createAuthAdmin } = require('../../lib/auth-admin.js');
+
+const SERVICE_ACCOUNT_PATH = join('.omega', 'secrets', 'service-account.json');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: (context) => {
+    const { options, operations } = context;
+
+    if (!options?.migration) {
+      return { skip: true, reason: '--migration flag not set' };
+    }
+
+    // Filter to a specific migration if a name was provided (--migration=users)
+    const migrationName = typeof options.migration === 'string' ? options.migration : null;
+    const filteredOperations = migrationName
+      ? operations.filter((op) => op.name === migrationName)
+      : operations;
+
+    if (migrationName && filteredOperations.length === 0) {
+      console.log(`    ${chalk.yellow('⚠')} ${chalk.yellow(`Migration "${chalk.cyan(migrationName)}" not found. Available: ${chalk.cyan(operations.map((op) => op.name).join(', '))}`)}`);
+
+      return { skip: true, reason: `migration "${migrationName}" not found` };
+    }
+
+    // Log skipped migrations
+    if (migrationName) {
+      for (const op of operations.filter((o) => o.name !== migrationName)) {
+        console.log(`    ${chalk.dim(`⊘ ${op.name}: skipped (--migration=${migrationName})`)}`);
+      }
+    }
+
+    // Firestore gates apply only to the migrations that actually touch it —
+    // a `local: true` migration works on the brand's own files, so it runs on
+    // a brand with no backend at all
+    const needsFirestore = filteredOperations.some((op) => !op.local);
+
+    const targets = context.brandConfig.targets || {};
+    if (needsFirestore && !targets.backend) {
+      return { skip: true, reason: 'no backend target' };
+    }
+
+    // Skip for shared Firebase projects — migrations iterate whole collections,
+    // so the owning brand's run covers the project; per-shared-brand runs would
+    // just repeat the same migration against the same Firestore
+    if (needsFirestore && context.brandConfig.cloud?.shared === true) {
+      return { skip: true, reason: 'shared Firebase project (owning brand runs migrations)' };
+    }
+
+    // Tests inject fakes via context
+    let authAdmin = context.authAdmin;
+    let firestore = context.firestore;
+    if (needsFirestore && !authAdmin) {
+      if (!jetpack.exists(join(context.brandRoot, SERVICE_ACCOUNT_PATH))) {
+        return { skip: true, reason: `no service account at ${SERVICE_ACCOUNT_PATH} (run the cloud service first)` };
+      }
+
+      const serviceAccount = loadServiceAccount(SERVICE_ACCOUNT_PATH, context.brandRoot);
+      authAdmin = createAuthAdmin(serviceAccount);
+      firestore = new FirestoreREST(serviceAccount);
+    }
+
+    return { operations: filteredOperations, authAdmin, firestore };
+  },
+});

package/dist/services/migrations/lib/attribution-touch.js

@@ -0,0 +1,64 @@
+/**
+ * Attribution fold fix — converts the pre-#384 attribution blob
+ * (`attribution.utm`, last-tagged-wins) into the touch model
+ * (`attribution.first` + `attribution.last`) every current reader expects.
+ *
+ * The same fold runs on every surface that stores attribution: user docs,
+ * payments-orders, payments-intents. The client already ships the identical
+ * fold for its localStorage copy (@omega.js/web core/js/core/query-strings.js
+ * migrateLegacyAttribution) — this is its server-side mirror, so a browser and
+ * its documents converge on the same shape.
+ *
+ * What the old blob cannot answer stays unanswered: the true first touch is
+ * unrecoverable (the blob only ever held the newest tagged visit), so both
+ * slots take the same touch; `clickIds` and `referrer` were never captured, so
+ * they are omitted/null rather than invented as empty husks — the capture
+ * convention writes a key only when the visit carried one.
+ */
+const { FieldValue } = require('./migration-runner.js');
+
+/**
+ * Create a migration fix that folds a legacy `attribution.utm` blob into
+ * `attribution.first` / `attribution.last` and deletes the blob.
+ *
+ * Idempotent: a document already carrying a touch keeps it (only a leftover
+ * blob is dropped), and a document with no blob is a strict no-op — nothing,
+ * including `attribution` itself, is ever synthesized.
+ *
+ * @returns {Function} Fix function for runMigration: (data) => updates or null
+ */
+function createAttributionFoldFix() {
+  return (data) => {
+    const attribution = data.attribution;
+    if (!attribution || typeof attribution !== 'object') {
+      return null;
+    }
+
+    const legacy = attribution.utm;
+    if (!legacy || typeof legacy !== 'object') {
+      return null;
+    }
+
+    // Already folded (by an earlier run, or by the client writing through) —
+    // the touches are newer than this blob, so only the blob goes.
+    if (attribution.first || attribution.last) {
+      return { 'attribution.utm': FieldValue.delete() };
+    }
+
+    const touch = {
+      ...(legacy.tags && Object.keys(legacy.tags).length > 0 ? { tags: legacy.tags } : {}),
+      referrer: null,
+      url: legacy.url || null,
+      page: legacy.page || null,
+      timestamp: legacy.timestamp || null,
+    };
+
+    return {
+      'attribution.first': touch,
+      'attribution.last': { ...touch },
+      'attribution.utm': FieldValue.delete(),
+    };
+  };
+}
+
+module.exports = { createAttributionFoldFix };

package/dist/services/migrations/lib/ensure-metadata.js

@@ -0,0 +1,144 @@
+/**
+ * Metadata timestamp fix — moves legacy created/updated fields into
+ * metadata.created/metadata.updated, falling back to the document's server
+ * create/update times. The REST client surfaces those as ISO strings
+ * (doc.createTime/doc.updateTime), not admin-SDK Timestamp objects.
+ */
+const { FieldValue } = require('./migration-runner.js');
+
+const EPOCH = '1970-01-01T00:00:00.000Z';
+
+/**
+ * Convert a document server timestamp (ISO string from doc.createTime /
+ * doc.updateTime) to our standard { timestamp, timestampUNIX } format.
+ */
+function serverTimestampToObject(isoString) {
+  if (!isoString) {
+    return null;
+  }
+
+  const date = new Date(isoString);
+
+  return {
+    timestamp: date.toISOString(),
+    timestampUNIX: Math.round(date.getTime() / 1000),
+  };
+}
+
+/**
+ * Check if a metadata timestamp is missing or is the epoch default
+ */
+function isMissingOrEpoch(ts) {
+  if (!ts) {
+    return true;
+  }
+
+  if (typeof ts === 'object' && ts.timestamp === EPOCH && ts.timestampUNIX === 0) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Creates a fix function that moves legacy fields into metadata.created/metadata.updated,
+ * then falls back to the document's createTime/updateTime for any that are still missing.
+ *
+ * This should be added as the LAST metadata-related fix in any migration, after any legacy
+ * field renames have already been applied.
+ *
+ * @param {Object} options
+ * @param {Array<string>} options.legacyCreatedFields - Legacy field paths to check for created (e.g. ['created', 'dateAdded'])
+ * @param {Array<string>} options.legacyUpdatedFields - Legacy field paths to check for updated (e.g. ['updated', 'edited'])
+ * @returns {Function} Fix function: (data, doc) => updates or null
+ */
+function createMetadataFix(options = {}) {
+  const legacyCreatedFields = options.legacyCreatedFields || ['created'];
+  const legacyUpdatedFields = options.legacyUpdatedFields || ['updated'];
+
+  return (data, doc) => {
+    const updates = {};
+    let hasUpdates = false;
+
+    // Step 1: Move legacy created fields → metadata.created, and clean up all legacy fields
+    for (const field of legacyCreatedFields) {
+      const value = getNestedValue(data, field);
+      if (!value) {
+        continue;
+      }
+
+      // Use the first legacy value for metadata.created if not already set
+      if (!data.metadata?.created && !updates['metadata.created']) {
+        updates['metadata.created'] = value;
+      }
+
+      // Always delete the legacy field
+      updates[field] = FieldValue.delete();
+      hasUpdates = true;
+    }
+
+    // Step 2: Move legacy updated fields → metadata.updated, and clean up all legacy fields
+    for (const field of legacyUpdatedFields) {
+      const value = getNestedValue(data, field);
+      if (!value) {
+        continue;
+      }
+
+      // Use the first legacy value for metadata.updated if not already set
+      if (!data.metadata?.updated && !updates['metadata.updated']) {
+        updates['metadata.updated'] = value;
+      }
+
+      // Always delete the legacy field
+      updates[field] = FieldValue.delete();
+      hasUpdates = true;
+    }
+
+    // Step 3: Determine effective metadata after legacy migration
+    const effectiveCreated = updates['metadata.created'] || data.metadata?.created;
+    const effectiveUpdated = updates['metadata.updated'] || data.metadata?.updated;
+
+    // Step 4: Fall back to document server timestamps for missing/epoch metadata
+    const docCreated = serverTimestampToObject(doc.createTime);
+    const docUpdated = serverTimestampToObject(doc.updateTime);
+
+    if (isMissingOrEpoch(effectiveCreated)) {
+      // Try doc.createTime, then doc.updateTime, then effectiveUpdated
+      const fallback = docCreated || docUpdated || effectiveUpdated;
+
+      if (fallback && !isMissingOrEpoch(fallback)) {
+        updates['metadata.created'] = fallback;
+        hasUpdates = true;
+      }
+    }
+
+    if (isMissingOrEpoch(effectiveUpdated)) {
+      // Try doc.updateTime, then the resolved created value
+      const resolvedCreated = updates['metadata.created'] || effectiveCreated;
+      const fallback = docUpdated || docCreated || resolvedCreated;
+
+      if (fallback && !isMissingOrEpoch(fallback)) {
+        updates['metadata.updated'] = fallback;
+        hasUpdates = true;
+      }
+    }
+
+    return hasUpdates ? updates : null;
+  };
+}
+
+/**
+ * Get a nested value from an object using dot-notation path
+ */
+function getNestedValue(obj, path) {
+  const parts = path.split('.');
+  let value = obj;
+
+  for (const part of parts) {
+    value = value?.[part];
+  }
+
+  return value;
+}
+
+module.exports = { createMetadataFix };