@omega.js/backend 0.1.0

package/dist/cli/commands/logs.js

@@ -0,0 +1,358 @@
+const BaseCommand = require('./base-command');
+const chalk = require('chalk').default;
+const fs = require('fs');
+const { execSync, spawn } = require('child_process');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const { resolveProjectId } = require('./firebase-init');
+const { STOP_SIGNALS } = require('../../vendor/devkit/stop-signals.js');
+
+const SEVERITY_COLORS = {
+  DEFAULT: 'gray',
+  DEBUG: 'gray',
+  INFO: 'cyan',
+  NOTICE: 'blue',
+  WARNING: 'yellow',
+  ERROR: 'red',
+  CRITICAL: 'redBright',
+  ALERT: 'redBright',
+  EMERGENCY: 'redBright',
+};
+
+class LogsCommand extends BaseCommand {
+  async execute() {
+    const argv = this.main.argv;
+    const args = argv._ || [];
+    const subcommand = args[0]; // e.g., 'logs:read' (bare `logs` aliases to `logs:read`)
+    const action = subcommand === 'logs' ? 'read' : subcommand.split(':')[1];
+
+    // Check gcloud is installed
+    if (!this.isGcloudInstalled()) {
+      this.logError('gcloud CLI is not installed or not in PATH.');
+      this.log(chalk.gray('  Install it: https://cloud.google.com/sdk/docs/install'));
+      return;
+    }
+
+    // Resolve project ID
+    const projectId = this.resolveProject();
+    if (!projectId) {
+      this.logError('Could not resolve project ID.');
+      this.log(chalk.gray('  Ensure functions/service-account.json, .firebaserc, or GCLOUD_PROJECT exists.'));
+      return;
+    }
+
+    this.log(chalk.gray(`  Project: ${projectId}\n`));
+
+    switch (action) {
+      case 'read':
+        return await this.read(projectId, argv);
+      case 'tail':
+      case 'stream':
+        return await this.tail(projectId, argv);
+      default:
+        this.logError(`Unknown logs subcommand: ${action}`);
+        this.log(chalk.gray('  Available: logs:read, logs:tail, logs:stream'));
+    }
+  }
+
+  /**
+   * Fetch historical logs.
+   * Usage: npx bm logs:read [--fn omega_api] [--severity ERROR] [--since 1h] [--limit 300] [--search "text"] [--order desc] [--filter 'raw gcloud filter']
+   */
+  async read(projectId, argv) {
+    const filter = this.buildFilter(argv);
+    const limit = parseInt(argv.limit, 10) || 300;
+    const order = argv.order || 'desc';
+
+    const cmd = [
+      'gcloud', 'logging', 'read',
+      filter ? `'${filter}'` : '',
+      `--project=${projectId}`,
+      `--limit=${limit}`,
+      '--format=json',
+      `--order=${order}`,
+    ].filter(Boolean).join(' ');
+
+    // Set up log file in the project's functions/ directory
+    const logPath = this.getLogsPath('production.log');
+
+    this.log(chalk.gray(`  Filter: ${filter || '(none)'}`));
+    this.log(chalk.gray(`  Limit: ${limit}`));
+    this.log(chalk.gray(`  Logs saving to: ${logPath}\n`));
+
+    try {
+      const output = execSync(cmd, {
+        encoding: 'utf8',
+        maxBuffer: 10 * 1024 * 1024, // 10MB
+        timeout: 60000,
+      });
+
+      const entries = JSON.parse(output || '[]');
+
+      // Save as newline-delimited JSON (matches tail format)
+      jetpack.write(logPath, entries.map(e => JSON.stringify(e)).join('\n'));
+
+      if (entries.length === 0) {
+        this.logWarning('No log entries found.');
+        return;
+      }
+
+      if (argv.raw) {
+        this.log(JSON.stringify(entries, null, 2));
+        return;
+      }
+
+      this.log(chalk.gray(`  Found ${entries.length} entries\n`));
+      for (const entry of entries) {
+        this.formatEntry(entry);
+      }
+    } catch (error) {
+      if (error.status) {
+        this.logError(`gcloud command failed (exit code ${error.status}):`);
+        this.log(chalk.gray(error.stderr || error.message));
+      } else {
+        this.logError(`Failed to read logs: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Poll for live logs by repeatedly running gcloud logging read.
+   * Usage: npx bm logs:tail [--fn omega_api] [--severity ERROR] [--interval 5]
+   */
+  async tail(projectId, argv) {
+    const interval = (parseInt(argv.interval, 10) || 5) * 1000;
+    let lastTimestamp = new Date(Date.now() - 60000).toISOString(); // Start 1 min ago
+    const seenIds = new Set();
+    let stopped = false;
+
+    // Set up log file in the project's functions/ directory
+    const logPath = this.getLogsPath('production.log');
+    const logStream = fs.createWriteStream(logPath, { flags: 'w' });
+
+    const filter = this.buildFilter(argv, { excludeTimestamp: true });
+    this.log(chalk.gray(`  Filter: ${filter || '(none)'}`));
+    this.log(chalk.gray(`  Polling every ${interval / 1000}s`));
+    this.log(chalk.gray(`  Logs saving to: ${logPath}`));
+    this.log(chalk.gray('  Tailing logs (Ctrl+C to stop)...\n'));
+
+    // Every way this tail is asked to stop ends it gracefully, off the ONE
+    // devkit list ([#629](https://github.com/Omega-JS-Stack/omega/issues/629)):
+    // a closed terminal (SIGHUP) used to kill the run mid-poll, leaving the log
+    // file open on a half-written line.
+    STOP_SIGNALS.forEach((signal) => process.on(signal, () => {
+      stopped = true;
+    }));
+
+    while (!stopped) {
+      try {
+        const timestampFilter = `timestamp>="${lastTimestamp}"`;
+        const fullFilter = filter
+          ? `${filter} AND ${timestampFilter}`
+          : `${timestampFilter}`;
+
+        const cmd = [
+          'gcloud', 'logging', 'read',
+          `'${fullFilter}'`,
+          `--project=${projectId}`,
+          '--limit=100',
+          '--format=json',
+          '--order=asc',
+        ].join(' ');
+
+        const output = execSync(cmd, {
+          encoding: 'utf8',
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: 15000,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+
+        const entries = JSON.parse(output || '[]');
+
+        for (const entry of entries) {
+          // Deduplicate using insertId
+          const entryId = entry.insertId || `${entry.timestamp}-${entry.textPayload || ''}`;
+          if (seenIds.has(entryId)) {
+            continue;
+          }
+          seenIds.add(entryId);
+
+          // Write to log file
+          logStream.write(JSON.stringify(entry) + '\n');
+
+          // Display
+          if (argv.raw) {
+            this.log(JSON.stringify(entry));
+          } else {
+            this.formatEntry(entry);
+          }
+
+          // Advance timestamp watermark
+          if (entry.timestamp && entry.timestamp > lastTimestamp) {
+            lastTimestamp = entry.timestamp;
+          }
+        }
+
+        // Cap seenIds to prevent memory leak
+        if (seenIds.size > 5000) {
+          const arr = [...seenIds];
+          arr.splice(0, arr.length - 2500);
+          seenIds.clear();
+          arr.forEach(id => seenIds.add(id));
+        }
+      } catch (error) {
+        // Silently skip transient errors during polling
+        if (error.status) {
+          this.log(chalk.gray(`  (poll error: ${(error.stderr || error.message).trim().split('\n')[0]})`));
+        }
+      }
+
+      // Wait before next poll
+      if (!stopped) {
+        await new Promise(resolve => setTimeout(resolve, interval));
+      }
+    }
+
+    logStream.end();
+    this.log(chalk.gray('\n  Tail stopped.'));
+  }
+
+  /**
+   * Build a gcloud logging filter string from CLI flags.
+   */
+  buildFilter(argv, options = {}) {
+    const parts = [];
+
+    // Always scope to Cloud Functions
+    parts.push('resource.type="cloud_function"');
+
+    // Function name filter
+    if (argv.fn) {
+      parts.push(`resource.labels.function_name="${argv.fn}"`);
+    }
+
+    // Severity filter
+    if (argv.severity) {
+      parts.push(`severity>=${argv.severity.toUpperCase()}`);
+    }
+
+    // Text search filter (searches textPayload)
+    if (argv.search) {
+      parts.push(`textPayload:"${argv.search}"`);
+    }
+
+    // Raw filter passthrough (appended as-is)
+    if (argv.filter) {
+      parts.push(argv.filter);
+    }
+
+    // Timestamp filter (read only, not tail)
+    if (!options.excludeTimestamp) {
+      const since = argv.since || '1h';
+      const timestamp = this.parseSince(since);
+      if (timestamp) {
+        parts.push(`timestamp>="${timestamp}"`);
+      }
+    }
+
+    return parts.join(' AND ');
+  }
+
+  /**
+   * Parse a human-friendly duration (e.g., '1h', '2d', '30m') into an ISO timestamp.
+   */
+  parseSince(since) {
+    const match = since.match(/^(\d+)([mhdw])$/);
+    if (!match) {
+      this.logWarning(`Invalid --since format: "${since}". Use e.g., 30m, 1h, 2d, 1w`);
+      return null;
+    }
+
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    const now = new Date();
+
+    switch (unit) {
+      case 'm': now.setMinutes(now.getMinutes() - value); break;
+      case 'h': now.setHours(now.getHours() - value); break;
+      case 'd': now.setDate(now.getDate() - value); break;
+      case 'w': now.setDate(now.getDate() - (value * 7)); break;
+    }
+
+    return now.toISOString();
+  }
+
+  /**
+   * Pretty-print a single log entry.
+   */
+  formatEntry(entry) {
+    const severity = entry.severity || 'DEFAULT';
+    const colorFn = chalk[SEVERITY_COLORS[severity] || 'white'];
+    const timestamp = entry.timestamp || entry.receiveTimestamp || '';
+    const fnName = entry.resource?.labels?.function_name || '';
+
+    // Extract the actual message
+    let message = '';
+    if (entry.textPayload) {
+      message = entry.textPayload;
+    } else if (entry.jsonPayload) {
+      message = typeof entry.jsonPayload.message === 'string'
+        ? entry.jsonPayload.message
+        : JSON.stringify(entry.jsonPayload, null, 2);
+    } else if (entry.protoPayload) {
+      message = JSON.stringify(entry.protoPayload, null, 2);
+    }
+
+    // Format timestamp to local time
+    let timeStr = '';
+    if (timestamp) {
+      const date = new Date(timestamp);
+      timeStr = date.toLocaleTimeString();
+    }
+
+    const severityTag = colorFn(`[${severity.padEnd(8)}]`);
+    const fnTag = fnName ? chalk.blue(`[${fnName}]`) : '';
+    const timeTag = chalk.gray(timeStr);
+
+    this.log(`${timeTag} ${severityTag} ${fnTag} ${message}`);
+  }
+
+  /**
+   * Resolve the project ID without initializing firebase-admin.
+   */
+  resolveProject() {
+    const projectDir = this.firebaseProjectPath;
+
+    // Try the authored service-account chain first (target root → brand
+    // secrets — most reliable for production; no stage required)
+    const { resolveServiceAccountPath } = require('../utils/stage-functions');
+    const serviceAccountPath = resolveServiceAccountPath(projectDir);
+    if (serviceAccountPath) {
+      try {
+        const sa = JSON.parse(jetpack.read(serviceAccountPath));
+        if (sa.project_id) {
+          return sa.project_id;
+        }
+      } catch (e) {
+        // Fall through
+      }
+    }
+
+    // Fall back to shared resolver
+    return resolveProjectId(projectDir);
+  }
+
+  /**
+   * Check if gcloud CLI is available.
+   */
+  isGcloudInstalled() {
+    try {
+      execSync('gcloud --version', { encoding: 'utf8', stdio: 'pipe' });
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+}
+
+module.exports = LogsCommand;

package/dist/cli/commands/mcp.js

@@ -0,0 +1,41 @@
+const path = require('path');
+const BaseCommand = require('./base-command');
+
+class McpCommand extends BaseCommand {
+  async execute() {
+    const self = this;
+
+    // dist/ is staged output — a fresh clone has none; the MCP server reads
+    // its config from the staged tree (same view as the runtime). `development`
+    // is PINNED (#586): mcp is a LOCAL lane like emulator/serve, and the stage
+    // and the read below must name the same environment or this process would
+    // read an overlay its own stage never composed.
+    this.ensureStaged({ environment: 'development' });
+    const functionsDir = path.join(self.firebaseProjectPath, 'dist');
+
+    // Load the .env cascade so OMEGA_ADMIN_KEY is available
+    require('../../vendor/config/index.js').loadEnv(functionsDir, { environment: 'development' });
+
+    // Resolve the @omega.js/backend server URL
+    const baseUrl = self.argv.url
+      || process.env.OMEGA_BACKEND_URL
+      || 'http://localhost:5002';
+
+    // Resolve auth credentials
+    const adminKey = self.argv.key
+      || process.env.OMEGA_ADMIN_KEY
+      || '';
+    const userToken = self.argv.token || '';
+
+    const { startServer } = require('../../mcp/index.js');
+
+    await startServer({
+      baseUrl,
+      adminKey: userToken ? '' : adminKey,
+      userToken,
+      cwd: functionsDir,
+    });
+  }
+}
+
+module.exports = McpCommand;

package/dist/cli/commands/migrate-markers.js

@@ -0,0 +1,176 @@
+const chalk = require('chalk').default;
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const BaseCommand = require('./base-command');
+const { omegaAllRulesRegex } = require('./setup-tests/helpers');
+const {
+  BRAND_RULES_FILE,
+  isPreFamilyMarkerFile,
+  migratePreFamilyMarkerFile,
+  preFamilyPlaceholderRegex,
+} = require('../utils/compile-rules');
+
+// The realtime rules file, at the target root — still marker-managed (only
+// firestore.rules moved to the compiled model).
+const REALTIME_RULES_FILE = 'database.rules.json';
+
+// The framework's own realtime template, whose family zone a placeholder-only
+// file is given wholesale.
+const REALTIME_RULES_TEMPLATE = path.resolve(__dirname, '..', '..', '..', 'templates', REALTIME_RULES_FILE);
+
+/**
+ * BEM's .gitignore block, byte-exact. Its own fix() deleted the WHOLE match,
+ * content included — those lines were framework-owned, and the family's Default
+ * zone re-writes them on the next verb. Fresh regex per call (/g carries
+ * lastIndex).
+ * @returns {RegExp}
+ */
+function bemGitignoreBlockRegex() {
+  return /# BEM>>>([\s\S]*?)# <<<BEM\n?/g;
+}
+
+// The legacy version stamp, its own line above the block's content. The family
+// folded the version into the open marker's label, so the two collapse into one.
+const PRE_FAMILY_VERSION_LINE = /\/\/\/---version=(.*?)---\/\/\//;
+
+/**
+ * `omega migrate:markers` — the one-time conversion of PRE-FAMILY marker
+ * formats onto the family grammar
+ * ([#40](https://github.com/Omega-JS-Stack/omega/issues/40)).
+ *
+ * Four shapes predate the family (_attic/plans/archive/marker-harmonization.md):
+ * the hand-written `{{ backend-manager }}` placeholder, the `# BEM>>>` gitignore
+ * block, the `///---backend-manager---///` rules block, and the cp72-74
+ * `///---omega---///` interim flavor. Nothing evergreen matches any of them, so
+ * a tree carried over from BEM never converges — the verbs report the shape and
+ * point here rather than converting behind the brand's back.
+ *
+ * Idempotent: a target already speaking the family is reported clean and left
+ * byte-untouched.
+ */
+class MigrateMarkersCommand extends BaseCommand {
+  async execute() {
+    const projectDir = this.main.firebaseProjectPath;
+    const firebaseJSON = jetpack.read(path.join(projectDir, 'firebase.json'), 'json');
+
+    this.ui.header('Pre-family marker migration', { subtitle: projectDir, subtitleColor: chalk.dim });
+
+    if (!firebaseJSON) {
+      this.ui.status('fail', chalk.red(`No firebase.json at ${projectDir} — run this from the target root.`));
+      process.exitCode = 1;
+      return;
+    }
+
+    const converted = [
+      this.migrateGitignore(projectDir),
+      this.migrateFirestoreRules(projectDir),
+      this.migrateRealtimeRules(projectDir),
+    ].filter(Boolean);
+
+    if (!converted.length) {
+      this.ui.status('skip', 'Nothing to migrate — every marker in this target already speaks the family grammar.');
+      return;
+    }
+
+    this.ui.blank();
+    this.ui.status('running', `Next: read the diff (${chalk.bold(`git diff ${converted.join(' ')}`)}), then run ${chalk.bold('npx omega test')} — the target checks converge the core rules and the Default zones from here.`);
+  }
+
+  /**
+   * Delete every `# BEM>>>` … `# <<<BEM` block, content included. Everything
+   * outside is the consumer's and stays byte-untouched: the two-zone merge that
+   * re-writes the framework lines is `ensureTarget()`'s, on the next verb.
+   * @param {string} projectDir - The target root.
+   * @returns {string|null} The file name when it was rewritten.
+   */
+  migrateGitignore(projectDir) {
+    const filePath = path.join(projectDir, '.gitignore');
+    const contents = jetpack.read(filePath);
+
+    if (!contents || !bemGitignoreBlockRegex().test(contents)) {
+      return null;
+    }
+
+    jetpack.write(filePath, contents.replace(bemGitignoreBlockRegex(), ''));
+    this.ui.status('change', `Removed the legacy ${chalk.bold('# BEM>>>')} block from ${chalk.bold('.gitignore')} — its lines were framework-owned, and the Default zone carries them now. Everything you wrote is untouched.`);
+
+    return '.gitignore';
+  }
+
+  /**
+   * Convert a pre-family firestore.rules onto the compiled model's source: the
+   * managed block (or the bare placeholder) goes, the brand's own rules land in
+   * the current seed.
+   * @param {string} projectDir - The target root.
+   * @returns {string|null} The file name when it was rewritten.
+   */
+  migrateFirestoreRules(projectDir) {
+    const filePath = path.join(projectDir, BRAND_RULES_FILE);
+    const contents = jetpack.read(filePath);
+
+    if (!contents || !isPreFamilyMarkerFile(contents)) {
+      return null;
+    }
+
+    jetpack.write(filePath, migratePreFamilyMarkerFile(contents));
+    this.ui.status('change', `Migrated ${chalk.bold(BRAND_RULES_FILE)} onto the compiled-rules source shape — your own rules were kept, and the framework's managed block is gone (it ships inside @omega.js/backend and compiles in).`);
+
+    return BRAND_RULES_FILE;
+  }
+
+  /**
+   * Convert a pre-family database.rules.json. It is still marker-MANAGED, so
+   * the markers are re-cut rather than removed:
+   *   - open + version line → one family open line carrying that version
+   *   - tests/resources dividers → dropped (the family has no twin for them)
+   *   - end marker → the family close
+   * A placeholder-only file has no block to re-cut, so it is given the current
+   * template's whole managed block at v0.0.0 — which the setup checks then
+   * converge to the live rules version.
+   * @param {string} projectDir - The target root.
+   * @returns {string|null} The file name when it was rewritten.
+   */
+  migrateRealtimeRules(projectDir) {
+    const filePath = path.join(projectDir, REALTIME_RULES_FILE);
+    const contents = jetpack.read(filePath);
+
+    if (!contents || !isPreFamilyMarkerFile(contents)) {
+      return null;
+    }
+
+    const stamp = versionStamp(contents);
+
+    jetpack.write(filePath, contents
+      .replace(/^([^\S\n]*)\/\/\/---(?:backend-manager|omega)---\/\/\/[^\S\n]*\n(?:[^\S\n]*\/\/\/---version=.*?---\/\/\/[^\S\n]*\n)?/m, `$1// ========== OMEGA Rules (v${stamp}) ==========\n`)
+      .replace(/^[^\S\n]*\/\/\/-+(?:tests|resources)-+\/\/\/[^\S\n]*\n/gm, '')
+      .replace(/^([^\S\n]*)\/\/\/---------end---------\/\/\/[^\S\n]*$/m, '$1// ========== End OMEGA Rules ==========')
+      .replace(preFamilyPlaceholderRegex(), () => managedRealtimeBlock()));
+    this.ui.status('change', `Re-cut the managed block in ${chalk.bold(REALTIME_RULES_FILE)} to the family grammar (${chalk.bold(`// ========== OMEGA Rules (v${stamp}) ==========`)}) — the rules inside it are unchanged.`);
+
+    return REALTIME_RULES_FILE;
+  }
+}
+
+/**
+ * The version the legacy stamp declared, for the family open marker's label.
+ * Unparseable (or absent, which is the placeholder flavor) reads as 0.0.0, and
+ * the setup checks converge it to the live rules version on the next run.
+ * @param {string} contents - The pre-family file.
+ * @returns {string} An `X.Y.Z` version.
+ */
+function versionStamp(contents) {
+  const declared = PRE_FAMILY_VERSION_LINE.exec(contents)?.[1] || '';
+
+  return /^\d+\.\d+\.\d+$/.test(declared) ? declared : '0.0.0';
+}
+
+/**
+ * The framework template's whole managed block — markers included, at the
+ * template's own v0.0.0 stamp.
+ * @returns {string}
+ */
+function managedRealtimeBlock() {
+  return jetpack.read(REALTIME_RULES_TEMPLATE).match(omegaAllRulesRegex)[0];
+}
+
+module.exports = MigrateMarkersCommand;

package/dist/cli/commands/migrate-rules.js

@@ -0,0 +1,90 @@
+const chalk = require('chalk').default;
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const BaseCommand = require('./base-command');
+const {
+  BRAND_RULES_FILE,
+  COMPILED_RULES_FILE,
+  MARKER_MIGRATION_COMMAND,
+  compileFirestoreRules,
+  deferredRulesTarget,
+  ensureBrandRulesSource,
+} = require('../utils/compile-rules');
+
+/**
+ * `omega migrate:rules` — the one-time move onto the compiled rules model
+ * ([#522](https://github.com/Omega-JS-Stack/omega/issues/522)).
+ *
+ * A brand whose firebase.json still names its own `firestore.rules` deploys the
+ * brand half alone. Adopting the compiled artifact adds the framework half and
+ * modernizes the source, which CHANGES what the live project enforces — so it
+ * is this verb's job, run alone and deliberately, never something another
+ * verb heals on the way to a deploy (the target checks defer instead).
+ *
+ * Idempotent: a brand already on `dist/firestore.rules` is reported and left
+ * alone.
+ */
+class MigrateRulesCommand extends BaseCommand {
+  async execute() {
+    const projectDir = this.main.firebaseProjectPath;
+    const firebaseJSONPath = path.join(projectDir, 'firebase.json');
+    const firebaseJSON = jetpack.read(firebaseJSONPath, 'json');
+
+    this.ui.header('Firestore rules migration', { subtitle: projectDir, subtitleColor: chalk.dim });
+
+    if (!firebaseJSON) {
+      this.ui.status('fail', chalk.red(`No firebase.json at ${projectDir} — run this from the target root.`));
+      process.exitCode = 1;
+      return;
+    }
+
+    const deferred = deferredRulesTarget({ projectDir: projectDir, firebaseJSON: firebaseJSON });
+
+    if (!deferred) {
+      this.ui.status('skip', `Nothing to migrate — firebase.json already points firestore.rules at ${chalk.bold(firebaseJSON.firestore?.rules || COMPILED_RULES_FILE)}.`);
+      return;
+    }
+
+    this.ui.status('warn', chalk.yellow(`This CHANGES LIVE POSTURE on your next deploy: ${COMPILED_RULES_FILE} carries the framework half beside your rules, and a legacy \`allow write\` becomes \`allow create, update\` (a client deleting its own doc flips allowed → denied).`));
+    this.ui.blank();
+
+    // Half one: the brand's authored source, migrated in place.
+    const result = ensureBrandRulesSource({ projectDir: projectDir });
+
+    // A pre-family source is refused untouched, so NEITHER half may run:
+    // repointing firebase.json here would deploy a compile of a file still
+    // carrying `///---...---///` markers ([#40](https://github.com/Omega-JS-Stack/omega/issues/40)).
+    if (result.refused) {
+      this.ui.status('fail', chalk.red(`${BRAND_RULES_FILE} still carries a pre-family marker ('{{ backend-manager }}' or a '///---...---///' block), which this migration does not speak — nothing was changed. Run ${chalk.bold(MARKER_MIGRATION_COMMAND)} first, then run this again.`));
+      process.exitCode = 1;
+      return;
+    }
+
+    if (result.created) {
+      this.ui.status('add', `Seeded ${BRAND_RULES_FILE} — your rules, compiled with the framework half. It is yours to edit.`);
+    }
+    if (result.migrated) {
+      this.ui.status('change', `Migrated ${BRAND_RULES_FILE} to rules v3 (merge-by-match) — your own rules were kept, and a match block of yours that names a framework path now MERGES into it instead of sitting beside it.`);
+    }
+    for (const hook of result.strippedHooks) {
+      this.ui.status('change', chalk.yellow(`Removed the retired \`${hook}()\` hook from ${BRAND_RULES_FILE} — it still carried the default body, and nothing calls it any more.`));
+    }
+    for (const hook of result.keptHooks) {
+      this.ui.status('warn', chalk.red(`${BRAND_RULES_FILE}: the retired \`${hook}()\` hook carried YOUR code, so it was kept as an ordinary function — but NOTHING CALLS IT NOW. Move what it enforced into a \`match\` block of your own (it merges into the framework's), then delete it.`));
+    }
+
+    // Half two: firebase.json, repointed at the artifact both the emulator and
+    // `firebase deploy` read.
+    firebaseJSON.firestore = { ...firebaseJSON.firestore, rules: COMPILED_RULES_FILE };
+    jetpack.write(firebaseJSONPath, JSON.stringify(firebaseJSON, null, 2));
+    this.ui.status('change', `firebase.json now points firestore.rules at ${chalk.bold(COMPILED_RULES_FILE)} (was "${deferred}").`);
+
+    compileFirestoreRules({ projectDir: projectDir });
+    this.ui.status('pass', `Compiled ${COMPILED_RULES_FILE}.`);
+
+    this.ui.blank();
+    this.ui.status('running', `Next: read the diff (${chalk.bold(`git diff ${BRAND_RULES_FILE} firebase.json`)}), run ${chalk.bold('npx omega test')}, then deploy when the new posture is what you want.`);
+  }
+}
+
+module.exports = MigrateRulesCommand;