@omega.js/backend 0.1.0

package/bin/omega

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/omega-bin.js');

package/bin/omega-backend

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli/run.js').run();

package/bin/omg

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/omega-bin.js');

package/cli.js

@@ -0,0 +1,3 @@
+// '@omega.js/backend/cli' — resolvable without an exports map (this package
+// deliberately has none). Used by the omega/omg cross-framework dispatcher.
+module.exports = require('./dist/cli/run.js');

package/dist/cli/command-table.js

@@ -0,0 +1,268 @@
+// The dispatchable surface of `omega` (backend), as DATA.
+//
+// One table, read by both halves of the CLI: Main.process() dispatches down it
+// in order, and `omega help` renders it. Help can no longer drift from what
+// actually dispatches (issue #20 — a review already caught the install-spelling
+// mismatch when the listing was hand-maintained).
+//
+// The router frameworks get this for free from devkit's cli-router, which
+// generates help from its alias table + commands directory. Backend's CLI is a
+// different design (colon-style utility commands dispatching stateful command
+// classes, resolved in a deliberate order) — same guarantee, its own table.
+//
+// Entry shape:
+//   name        — the primary token, and the label help prints
+//   aliases     — other argv tokens that select this command
+//   args        — optional positional-argument map: `{ <arg>: [<arg aliases>] }`
+//   description — the help line
+//   default     — the command a bare `omega` runs (no entry claims it since
+//                 #675 retired setup: a bare `omega` prints help)
+//   match       — optional custom resolver; returns a truthy value passed to run()
+//   run         — (self, matched) => the command's execute()
+//
+// ORDER IS DISPATCH ORDER. Entries are matched top to bottom, first hit wins.
+
+const VersionCommand = require('./commands/version');
+const ClearCommand = require('./commands/clear');
+const CwdCommand = require('./commands/cwd');
+const BuildCommand = require('./commands/build');
+const InstallCommand = require('./commands/install');
+const ServeCommand = require('./commands/serve');
+const DeployCommand = require('./commands/deploy');
+const TestCommand = require('./commands/test');
+const EmulatorCommand = require('./commands/emulator');
+const CleanCommand = require('./commands/clean');
+const IndexesCommand = require('./commands/indexes');
+const WatchCommand = require('./commands/watch');
+const StripeCommand = require('./commands/stripe');
+const FirestoreCommand = require('./commands/firestore');
+const AuthCommand = require('./commands/auth');
+const LogsCommand = require('./commands/logs');
+const UpdateCommand = require('./commands/update');
+const McpCommand = require('./commands/mcp');
+const MigrateCommand = require('./commands/migrate');
+const MigrateRulesCommand = require('./commands/migrate-rules');
+const MigrateMarkersCommand = require('./commands/migrate-markers');
+
+// Returned by an args-taking command's match() when the command was named but no
+// argument was given — the branch that must name the real spellings instead of
+// falling through to the unknown-command tail (which would misreport a listed command).
+const MISSING_ARG = Symbol('missing-arg');
+
+// Every argv token that selects a command.
+function tokensOf(command) {
+  return [command.name, ...(command.aliases || [])];
+}
+
+// `local|live` — the argument names, in resolution order.
+function argsLabel(command) {
+  return Object.keys(command.args).join('|');
+}
+
+// `local: dev, development · live: prod, production` — the accepted argument spellings.
+function argsNote(command) {
+  return Object.entries(command.args)
+    .filter(([, aliases]) => aliases.length > 0)
+    .map(([arg, aliases]) => `${arg}: ${aliases.join(', ')}`)
+    .join(' · ');
+}
+
+// Default matcher: any of the command's tokens present in the parsed options.
+// A command with `args` also resolves WHICH argument was given, and reports
+// MISSING_ARG when it was named bare.
+function matchCommand(command, options) {
+  const named = tokensOf(command).some((token) => options[token]);
+
+  if (!command.args) {
+    return named;
+  }
+
+  for (const [arg, aliases] of Object.entries(command.args)) {
+    if ((named && aliases.some((alias) => options[alias])) || options[arg]) {
+      return arg;
+    }
+  }
+
+  return named ? MISSING_ARG : false;
+}
+
+const COMMANDS = [
+  {
+    name: 'version',
+    aliases: ['v', '-v', '--version'],
+    description: 'print the framework version',
+    run: (self) => new VersionCommand(self).execute(),
+  },
+  {
+    // Help never falls through to another command.
+    name: 'help',
+    aliases: ['--help', 'h', '-h'],
+    description: 'this listing',
+    run: () => console.log(buildHelpText()),
+  },
+  {
+    name: 'clear',
+    description: 'clear caches',
+    run: (self) => new ClearCommand(self).execute(),
+  },
+  {
+    name: 'cwd',
+    description: 'print the resolved target root',
+    run: (self) => new CwdCommand(self).execute(),
+  },
+  {
+    name: 'build',
+    description: 'stage src/ into dist/',
+    run: (self) => new BuildCommand(self).execute(),
+  },
+  {
+    name: 'install',
+    aliases: ['-i', 'i', '--install'],
+    args: { local: ['dev', 'development'], live: ['prod', 'production'] },
+    description: 'switch the installed framework copy',
+    run: (self, mode, command) => {
+      if (mode === MISSING_ARG) {
+        const spellings = Object.keys(command.args).map((arg) => `\`omega ${command.name} ${arg}\``).join(' or ');
+        console.error(`${command.name} needs a mode: ${spellings}. Aliases: ${argsNote(command)}.`);
+        process.exitCode = 1;
+        return;
+      }
+
+      return new InstallCommand(self).execute(mode);
+    },
+  },
+  {
+    name: 'serve',
+    description: 'run the local Firebase emulator suite',
+    run: (self) => new ServeCommand(self).execute(),
+  },
+  {
+    // `indexes` accepted bare — the documented sync verb.
+    name: 'indexes',
+    aliases: ['indexes:get', 'firestore:indexes', 'firestore:indexes:get'],
+    description: 'sync deployed Firestore indexes into firestore.indexes.json',
+    run: (self) => new IndexesCommand(self).get(undefined, true),
+  },
+  {
+    name: 'deploy',
+    description: 'deploy to Firebase',
+    run: (self) => new DeployCommand(self).execute(),
+  },
+  {
+    name: 'test',
+    description: 'run the test suites',
+    run: (self) => new TestCommand(self).execute(),
+  },
+  {
+    name: 'emulator',
+    aliases: ['emulators'],
+    description: 'emulator keep-alive mode',
+    run: (self) => new EmulatorCommand(self).execute(),
+  },
+  {
+    // `clean` accepted bare — every router framework answers it.
+    name: 'clean',
+    aliases: ['clean:npm'],
+    description: 'remove node_modules + lockfile and reinstall',
+    run: (self) => new CleanCommand(self).execute(),
+  },
+  {
+    name: 'watch',
+    description: 'hot-reload on framework source changes',
+    run: (self) => new WatchCommand(self).execute(),
+  },
+  {
+    name: 'stripe',
+    aliases: ['stripe:listen'],
+    description: 'forward Stripe webhooks locally',
+    run: (self) => new StripeCommand(self).execute(),
+  },
+  {
+    name: 'firestore:get',
+    aliases: ['firestore:set', 'firestore:query', 'firestore:delete'],
+    description: 'Firestore utilities',
+    run: (self) => new FirestoreCommand(self).execute(),
+  },
+  {
+    name: 'auth:get',
+    aliases: ['auth:list', 'auth:delete', 'auth:set-claims', 'auth:token'],
+    description: 'Auth utilities',
+    run: (self) => new AuthCommand(self).execute(),
+  },
+  {
+    // `logs` is an alias for `logs:read`.
+    name: 'logs',
+    aliases: ['logs:read', 'logs:tail', 'logs:stream'],
+    description: 'Cloud Logging utilities',
+    run: (self) => new LogsCommand(self).execute(),
+  },
+  {
+    name: 'update',
+    aliases: ['-u', '--update', 'outdated', 'out'],
+    description: 'dependency freshness report',
+    run: (self) => new UpdateCommand(self).execute(),
+  },
+  {
+    name: 'mcp',
+    description: 'run the MCP server',
+    run: (self) => new McpCommand(self).execute(),
+  },
+  {
+    // The ported-project REPORT: today the dependency-resolution scan (#600),
+    // shared with @omega.js/web's own migrate through devkit. It changes
+    // nothing, which is what separates it from the two conversions below.
+    name: 'migrate',
+    description: 'report what a ported backend still owes: bare requires of packages it never declared',
+    run: (self) => new MigrateCommand(self).execute(),
+  },
+  {
+    // The one-time move onto the compiled rules model — run ALONE and
+    // deliberately, because it changes what the live project enforces. Setup
+    // defers to it instead of healing the tree on the way to a deploy (#522).
+    name: 'migrate:rules',
+    aliases: ['migrate:firestore-rules'],
+    description: 'migrate legacy firestore.rules onto the compiled model (changes live posture)',
+    run: (self) => new MigrateRulesCommand(self).execute(),
+  },
+  {
+    // The one-time conversion of the PRE-FAMILY marker formats a tree carried
+    // over from BEM still holds. Evergreen verbs speak only the family grammar,
+    // so they detect those shapes and point here instead of converting
+    // ([#40](https://github.com/Omega-JS-Stack/omega/issues/40)).
+    name: 'migrate:markers',
+    description: 'convert pre-family marker formats ({{ backend-manager }}, # BEM>>>, ///---…---///) to the family grammar',
+    run: (self) => new MigrateMarkersCommand(self).execute(),
+  },
+];
+
+// The command a bare `omega` runs — undefined when nothing claims the slot,
+// which is the state since `setup` was retired (#675). The dispatcher falls
+// back to the help listing.
+function defaultCommand() {
+  return COMMANDS.find((command) => command.default);
+}
+
+// Width of the label column. Labels wider than this put their description on the
+// next line rather than shoving every other description right.
+const LABEL_COLUMN = 33;
+
+// `omega help` — rendered from COMMANDS, never hand-written.
+function buildHelpText() {
+  const lines = COMMANDS.map((command) => {
+    const tokens = tokensOf(command).join(' | ');
+    const label = command.args ? `${tokens} <${argsLabel(command)}>` : tokens;
+
+    const notes = [];
+    if (command.args) { notes.push(argsNote(command)); }
+    if (command.default) { notes.push('default'); }
+    const description = notes.length > 0 ? `${command.description} [${notes.join(' — ')}]` : command.description;
+
+    return label.length > LABEL_COLUMN - 3
+      ? `  ${label}\n${' '.repeat(LABEL_COLUMN)}${description}`
+      : `  ${label.padEnd(LABEL_COLUMN - 2)}${description}`;
+  });
+
+  return `Usage: omega <command> [options]\n\nCommands:\n${lines.join('\n')}`;
+}
+
+module.exports = { COMMANDS, MISSING_ARG, tokensOf, matchCommand, defaultCommand, buildHelpText };

package/dist/cli/commands/auth.js

@@ -0,0 +1,259 @@
+const BaseCommand = require('./base-command');
+const chalk = require('chalk').default;
+const { confirm } = require('@inquirer/prompts');
+const { initFirebase } = require('./firebase-init');
+const { resolveTarget } = require('../utils/target');
+
+class AuthCommand extends BaseCommand {
+  async execute() {
+    const argv = this.main.argv;
+    const args = argv._ || [];
+    const subcommand = args[0]; // e.g., 'auth:get' or 'auth:set-claims'
+    const action = subcommand.split(':').slice(1).join(':'); // handles 'auth:set-claims'
+
+    // Initialize Firebase. Every subcommand — reads and writes alike — defaults
+    // to the EMULATOR; --production is the deliberate opt-in to touch live
+    // (src/cli/utils/target.js owns the rule).
+    const { emulator: isEmulator, label: target } = resolveTarget(argv);
+    let firebase;
+
+    try {
+      firebase = initFirebase({
+        firebaseProjectPath: this.firebaseProjectPath,
+        emulator: isEmulator,
+      });
+    } catch (error) {
+      this.logError(`Firebase init failed: ${error.message}`);
+      return;
+    }
+
+    const { admin, projectId } = firebase;
+    this.log(chalk.gray(`  Target: ${projectId} (${target})\n`));
+
+    // Dispatch to subcommand handler
+    switch (action) {
+      case 'get':
+        return await this.get(admin, args, argv);
+      case 'list':
+        return await this.list(admin, args, argv);
+      case 'delete':
+        return await this.del(admin, args, argv, isEmulator, target);
+      case 'set-claims':
+        return await this.setClaims(admin, args, argv, target);
+      case 'token':
+        return await this.token(admin, args, argv, isEmulator);
+      default:
+        this.logError(`Unknown auth subcommand: ${action}`);
+        this.log(chalk.gray('  Available: auth:get, auth:list, auth:delete, auth:set-claims, auth:token'));
+    }
+  }
+
+  /**
+   * Mint a custom token for a user and print the one-click sign-in URL —
+   * the QA "log in as anyone" surface. The auth pages already consume
+   * ?authCustomToken= (+ optional authReturnUrl), so the printed URL signs
+   * the browser in directly. Emulator by default; --production is explicit.
+   * Usage: npx omega auth:token _test.admin@playground.omegajs.dev
+   *        npx omega auth:token <uid> [--production] --url http://localhost:4000 --return /account
+   */
+  async token(admin, args, argv, isEmulator) {
+    const identifier = args[1];
+
+    if (!identifier) {
+      this.logError('Usage: npx omega auth:token <uid-or-email> [--production] [--url http://localhost:4000] [--return /account]');
+      return;
+    }
+
+    try {
+      const user = await this.resolveUser(admin, identifier);
+      const token = await admin.auth().createCustomToken(user.uid);
+      const base = String(argv.url || 'http://localhost:4000').replace(/\/+$/, '');
+      const returnUrl = String(argv.return || '/dashboard/account');
+      const signinUrl = `${base}/signin?authCustomToken=${encodeURIComponent(token)}&authReturnUrl=${encodeURIComponent(returnUrl)}`;
+
+      this.log(chalk.bold(`\n  Custom token for ${user.email || user.uid}${isEmulator ? chalk.gray(' (emulator)') : chalk.red(' (PRODUCTION)')}`));
+      this.log(`  ${chalk.gray('Sign-in URL:')}`);
+      this.log(`  ${chalk.cyan(signinUrl)}\n`);
+    } catch (error) {
+      this.logError(`Token mint failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Resolve a user identifier to a UserRecord.
+   * Accepts UID or email address (auto-detected via @).
+   */
+  async resolveUser(admin, identifier) {
+    if (!identifier) {
+      return null;
+    }
+
+    // If it contains '@', treat as email
+    if (identifier.includes('@')) {
+      return await admin.auth().getUserByEmail(identifier);
+    }
+
+    return await admin.auth().getUser(identifier);
+  }
+
+  /**
+   * Get a user by UID or email.
+   * Usage: npx bm auth:get user@email.com
+   *        npx bm auth:get abc123uid
+   */
+  async get(admin, args, argv) {
+    const identifier = args[1];
+
+    if (!identifier) {
+      this.logError('Usage: npx bm auth:get <uid-or-email>');
+      return;
+    }
+
+    try {
+      const user = await this.resolveUser(admin, identifier);
+      this.output(user.toJSON(), argv);
+    } catch (error) {
+      if (error.code === 'auth/user-not-found') {
+        this.logWarning(`User not found: ${identifier}`);
+        return;
+      }
+      this.logError(`Failed to get user: ${error.message}`);
+    }
+  }
+
+  /**
+   * List users.
+   * Usage: npx bm auth:list [--limit 100] [--page-token TOKEN]
+   */
+  async list(admin, args, argv) {
+    const limit = parseInt(argv.limit, 10) || 100;
+    const pageToken = argv['page-token'] || argv.pageToken || undefined;
+
+    try {
+      const result = await admin.auth().listUsers(limit, pageToken);
+
+      const users = result.users.map(user => ({
+        uid: user.uid,
+        email: user.email || null,
+        displayName: user.displayName || null,
+        disabled: user.disabled,
+        createdAt: user.metadata.creationTime,
+        lastSignIn: user.metadata.lastSignInTime,
+        customClaims: user.customClaims || {},
+      }));
+
+      this.log(chalk.gray(`  Found ${users.length} user(s)\n`));
+
+      if (result.pageToken) {
+        this.log(chalk.gray(`  Next page: --page-token ${result.pageToken}\n`));
+      }
+
+      this.output(users, argv);
+    } catch (error) {
+      this.logError(`Failed to list users: ${error.message}`);
+    }
+  }
+
+  /**
+   * Delete a user. Emulator unless --production.
+   * Usage: npx bm auth:delete user@email.com [--production] [--force]
+   */
+  async del(admin, args, argv, isEmulator, target) {
+    const identifier = args[1];
+
+    if (!identifier) {
+      this.logError('Usage: npx bm auth:delete <uid-or-email> [--production] [--force]');
+      return;
+    }
+
+    // Resolve user first to show who we're deleting
+    let user;
+    try {
+      user = await this.resolveUser(admin, identifier);
+    } catch (error) {
+      if (error.code === 'auth/user-not-found') {
+        this.logWarning(`User not found: ${identifier}`);
+        return;
+      }
+      this.logError(`Failed to resolve user: ${error.message}`);
+      return;
+    }
+
+    this.log(chalk.gray(`  User: ${user.uid} (${user.email || 'no email'})`));
+
+    // Require confirmation for production (skip for emulator or --force)
+    if (!isEmulator && !argv.force) {
+      const confirmed = await confirm({
+        message: `Delete user "${user.uid}" (${user.email || 'no email'}) from PRODUCTION?`,
+        default: false,
+      });
+
+      if (!confirmed) {
+        this.log(chalk.gray('  Aborted.'));
+        return;
+      }
+    }
+
+    try {
+      await admin.auth().deleteUser(user.uid);
+      this.logSuccess(`User deleted from ${target}: ${user.uid}`);
+    } catch (error) {
+      this.logError(`Failed to delete user: ${error.message}`);
+    }
+  }
+
+  /**
+   * Set custom claims on a user. Emulator unless --production.
+   * Usage: npx bm auth:set-claims user@email.com '{"admin": true}' [--production]
+   */
+  async setClaims(admin, args, argv, target) {
+    const identifier = args[1];
+    const jsonString = args[2];
+
+    if (!identifier || !jsonString) {
+      this.logError('Usage: npx bm auth:set-claims <uid-or-email> \'<json>\' [--production]');
+      return;
+    }
+
+    let claims;
+    try {
+      claims = JSON.parse(jsonString);
+    } catch (error) {
+      this.logError(`Invalid JSON: ${error.message}`);
+      return;
+    }
+
+    let user;
+    try {
+      user = await this.resolveUser(admin, identifier);
+    } catch (error) {
+      if (error.code === 'auth/user-not-found') {
+        this.logWarning(`User not found: ${identifier}`);
+        return;
+      }
+      this.logError(`Failed to resolve user: ${error.message}`);
+      return;
+    }
+
+    try {
+      await admin.auth().setCustomUserClaims(user.uid, claims);
+      this.logSuccess(`Custom claims set for ${user.uid} on ${target}:`);
+      this.output(claims, argv);
+    } catch (error) {
+      this.logError(`Failed to set claims: ${error.message}`);
+    }
+  }
+
+  /**
+   * Output data as JSON.
+   */
+  output(data, argv) {
+    if (argv.raw) {
+      this.log(JSON.stringify(data));
+    } else {
+      this.log(JSON.stringify(data, null, 2));
+    }
+  }
+}
+
+module.exports = AuthCommand;