@omega.js/backend 0.1.0

package/test/cli/setup-offline-mode.test.js

@@ -0,0 +1,276 @@
+/**
+ * Test: `npx omega setup --offline` never mutates the brand's live cloud
+ * project ([#284](https://github.com/Omega-JS-Stack/omega/issues/284)).
+ *
+ * Two setup checks reach outside the working tree with no opt-out:
+ * `firestore-indexes-synced.fix()` runs `firebase deploy --only
+ * firestore:indexes`, and `storage-lifecycle-policy.run()` runs `gsutil
+ * lifecycle set`. Scaffolding a fresh app therefore rewrote production
+ * infrastructure as a side effect. `--offline` downgrades both to REPORTED
+ * failures ('warn' — surfaced in the summary, never halting): the read-only
+ * drift report still runs, the mutation does not.
+ *
+ * The ONE stub here is `powertools.execute` — the single seam every one of
+ * these spawns goes through. The real calls deploy Firestore indexes and
+ * rewrite GCS bucket lifecycle on a LIVE project; neither surface has an
+ * emulator, and running them is the exact bug under test. Restored in a
+ * `finally`, and the read-only leg is shimmed to the real command's contract
+ * (`firebase firestore:indexes > <file>` writes the live JSON to <file>) so
+ * the check's own comparison logic runs for real.
+ *
+ * Run: npx omega test backend:cli/setup-offline-mode
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const powertools = require('node-powertools');
+const { BOOLEAN_FLAGS } = require('../../dist/cli/flags.js');
+const FirestoreIndexesSyncedTest = require('../../dist/cli/commands/setup-tests/firestore-indexes-synced.js');
+const StorageLifecyclePolicyTest = require('../../dist/cli/commands/setup-tests/storage-lifecycle-policy.js');
+const MarketingCampaignsSeededTest = require('../../dist/cli/commands/setup-tests/marketing-campaigns-seeded.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// What the target has committed vs what the live project actually carries — one
+// differing index is all the drift the check needs to fail.
+const LOCAL_INDEXES = {
+  indexes: [
+    { collectionGroup: 'users', queryScope: 'COLLECTION', fields: [{ fieldPath: 'email', order: 'ASCENDING' }] },
+  ],
+  fieldOverrides: [],
+};
+
+const LIVE_INDEXES = {
+  indexes: [
+    { collectionGroup: 'posts', queryScope: 'COLLECTION', fields: [{ fieldPath: 'published', order: 'DESCENDING' }] },
+  ],
+  fieldOverrides: [],
+};
+
+// Every command these checks spawn goes through powertools.execute. `onCommand`
+// shims the read-only leg; anything it does not answer throws, so an unexpected
+// spawn fails the test instead of reaching the network.
+async function withSpawnTrap(fn, onCommand) {
+  const original = powertools.execute;
+  const spawned = [];
+
+  powertools.execute = async (command, options) => {
+    spawned.push(command);
+
+    if (onCommand) {
+      return await onCommand(command, options);
+    }
+
+    throw new Error(`spawn trap: nothing may spawn here (got "${command}")`);
+  };
+
+  try {
+    return await fn(spawned);
+  } finally {
+    powertools.execute = original;
+  }
+}
+
+// The `firebase firestore:indexes > <file>` read: the real command writes the
+// live index JSON to the redirect target, which the check then require()s.
+function liveIndexRead(command) {
+  if (!command.startsWith('firebase firestore:indexes')) {
+    throw new Error(`spawn trap: only the read-only index fetch may spawn (got "${command}")`);
+  }
+
+  jetpack.write(command.split('> ')[1].trim(), JSON.stringify(LIVE_INDEXES, null, 2));
+
+  return '';
+}
+
+// An target root seeded with committed indexes that do NOT match live.
+function seedTarget() {
+  const targetPath = jetpack.tmpDir({ prefix: 'omega-setup-offline-' }).path();
+
+  jetpack.write(path.join(targetPath, 'firestore.indexes.json'), JSON.stringify(LOCAL_INDEXES, null, 2));
+
+  return targetPath;
+}
+
+function buildIndexesTest(targetPath, argv) {
+  return new FirestoreIndexesSyncedTest({
+    main: { projectId: 'real-project', argv: argv, firebaseProjectPath: targetPath },
+  });
+}
+
+function buildStorageTest(argv) {
+  return new StorageLifecyclePolicyTest({
+    main: { projectId: 'real-project', argv: argv, firebaseProjectPath: '/nonexistent/project' },
+  });
+}
+
+module.exports = defineCases({
+  description: 'setup --offline — live-mutating checks downgrade to reported failures',
+  type: 'group',
+  timeout: 20000,
+
+  tests: [
+    {
+      name: 'offline-is-a-declared-boolean',
+      auth: 'none',
+
+      async run({ assert }) {
+        // Undeclared, yargs would eat the next positional as --offline's value.
+        assert.equal(BOOLEAN_FLAGS.includes('offline'), true, 'offline must be in the declared boolean list');
+      },
+    },
+
+    {
+      name: 'indexes-drift-fails-into-the-live-deploy-without-the-flag',
+      auth: 'none',
+
+      async run({ assert }) {
+        // The bug, pinned: a plain scaffold run reaches `firebase deploy`.
+        const targetPath = seedTarget();
+        const test = buildIndexesTest(targetPath, {});
+
+        await withSpawnTrap(async (spawned) => {
+          assert.equal(await test.run(), false, 'drift must fail so the runner calls fix()');
+
+          await test.fix().catch(() => {});
+
+          assert.equal(
+            spawned.some((c) => c.startsWith('firebase deploy')),
+            true,
+            'without --offline the fix deploys indexes to the live project',
+          );
+        }, (command) => {
+          if (command.startsWith('firebase deploy')) {
+            return '';
+          }
+
+          return liveIndexRead(command);
+        });
+
+        jetpack.remove(targetPath);
+      },
+    },
+
+    {
+      name: 'indexes-drift-downgrades-to-a-warning-under-offline',
+      auth: 'none',
+
+      async run({ assert }) {
+        const targetPath = seedTarget();
+        const test = buildIndexesTest(targetPath, { offline: true });
+
+        await withSpawnTrap(async (spawned) => {
+          // The read-only drift report still runs — the check reports what is
+          // out of sync — but the verdict is a non-blocking warning, so the
+          // runner never reaches the mutating fix.
+          assert.equal(await test.run(), 'warn', '--offline downgrades drift to a reported warning');
+          assert.equal(
+            spawned.some((c) => c.startsWith('firebase deploy')),
+            false,
+            'no live deploy may spawn under --offline',
+          );
+        }, liveIndexRead);
+
+        assert.match(test.getWarning().join(' '), /--offline/, 'the warning must name the flag that suppressed the deploy');
+
+        jetpack.remove(targetPath);
+      },
+    },
+
+    {
+      name: 'indexes-fix-spawns-nothing-under-offline',
+      auth: 'none',
+
+      async run({ assert }) {
+        // Belt for any direct caller: run() already warns instead of failing,
+        // so the runner cannot reach this fix.
+        const targetPath = seedTarget();
+        const test = buildIndexesTest(targetPath, { offline: true });
+
+        await withSpawnTrap(async (spawned) => {
+          await test.fix();
+
+          assert.deepEqual(spawned, [], 'fix() must spawn nothing under --offline');
+        });
+
+        assert.deepEqual(
+          JSON.parse(jetpack.read(path.join(targetPath, 'firestore.indexes.json'))),
+          LOCAL_INDEXES,
+          'the committed index file stays untouched under --offline',
+        );
+
+        jetpack.remove(targetPath);
+      },
+    },
+
+    {
+      name: 'storage-lifecycle-runs-gsutil-without-the-flag',
+      auth: 'none',
+
+      async run({ assert }) {
+        // The bug's second half: this check IS the mutation.
+        const test = buildStorageTest({});
+
+        await withSpawnTrap(async (spawned) => {
+          await test.run();
+
+          assert.equal(spawned.length > 0, true, 'without --offline the check spawns gsutil');
+          assert.equal(spawned.every((c) => c.startsWith('gsutil ')), true, 'every spawned command is gsutil');
+        }, () => {
+          throw new Error('bucket unreachable');
+        });
+      },
+    },
+
+    {
+      name: 'storage-lifecycle-spawns-nothing-under-offline',
+      auth: 'none',
+
+      async run({ assert }) {
+        const test = buildStorageTest({ offline: true });
+
+        await withSpawnTrap(async (spawned) => {
+          assert.equal(await test.run(), 'warn', '--offline downgrades the policy write to a reported warning');
+          assert.deepEqual(spawned, [], 'no gsutil process may spawn under --offline');
+        });
+
+        assert.match(test.getWarning().join(' '), /--offline/, 'the warning must name the flag that suppressed the write');
+      },
+    },
+
+    {
+      name: 'storage-lifecycle-passes-demo-projects-even-under-offline',
+      auth: 'none',
+
+      async run({ assert }) {
+        // A demo-* project has no live buckets: the demo gate wins over the
+        // offline warning, so a demo scaffold does not warn about a policy
+        // that can never apply.
+        const test = new StorageLifecyclePolicyTest({
+          main: { projectId: 'demo-sandbox', argv: { offline: true }, firebaseProjectPath: '/nonexistent/project' },
+        });
+
+        await withSpawnTrap(async (spawned) => {
+          assert.equal(await test.run(), true, 'demo projects pass, never warn');
+          assert.deepEqual(spawned, [], 'no process may spawn for a demo project');
+        });
+      },
+    },
+
+    {
+      name: 'seed-campaigns-opt-in-loses-to-offline',
+      auth: 'none',
+
+      async run({ assert }) {
+        // --offline promises NO live mutations for the whole run; the seeding
+        // fix() writes real Firestore docs, so the opt-in is ignored and the
+        // drift verdict stays a non-blocking warning.
+        const test = new MarketingCampaignsSeededTest({
+          main: { projectId: 'real-project', argv: { offline: true, seedCampaigns: true, 'seed-campaigns': true }, firebaseProjectPath: '/nonexistent/project' },
+        });
+
+        assert.equal(test._seedingRequested(), false, '--offline must override --seed-campaigns');
+        assert.equal(test._driftVerdict(), 'warn', 'drift stays a warning, so the runner never calls the seeding fix()');
+        assert.match(test.getWarning().join(' '), /--offline/, 'the warning names the flag that suppressed the write, not the opt-in the user already passed');
+      },
+    },
+  ],
+});

package/test/cli/setup-retired.test.js

@@ -0,0 +1,64 @@
+/**
+ * Test: `omega setup` is retired
+ * ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+ *
+ * Nothing dispatches it, nothing lists it, and a bare `omega` at a backend
+ * target prints the help listing instead of running a command nobody asked
+ * for. The work it did rides the verbs now: the local scaffold in
+ * `ensureTarget()` (every verb, through ensureStaged) and the target checks
+ * in `omega test`.
+ *
+ * Run: npx omega test backend:cli/setup-retired
+ */
+const { COMMANDS, tokensOf, matchCommand, defaultCommand, buildHelpText } = require('../../dist/cli/command-table.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+module.exports = defineCases({
+  description: 'The setup command is retired — the verbs carry its work',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'no-setup-entry-in-the-table',
+      auth: 'none',
+
+      async run({ assert }) {
+        const tokens = COMMANDS.flatMap(tokensOf);
+
+        assert.equal(tokens.includes('setup'), false, 'nothing dispatches `omega setup`');
+        assert.equal(buildHelpText().includes('setup'), false, 'nothing lists it either');
+      },
+    },
+
+    {
+      name: 'no-command-claims-the-default-slot',
+      auth: 'none',
+
+      async run({ assert }) {
+        assert.equal(COMMANDS.some((command) => command.default), false, 'setup was the only default — nothing inherits the slot');
+        assert.equal(defaultCommand(), undefined, 'defaultCommand() answers "none" instead of throwing');
+      },
+    },
+
+    {
+      name: 'a-bare-invocation-resolves-to-help',
+      auth: 'none',
+
+      async run({ assert }) {
+        const help = COMMANDS.find((command) => command.name === 'help');
+        const lines = [];
+        const original = console.log;
+
+        console.log = (...args) => lines.push(args.map(String).join(' '));
+        try {
+          help.run();
+        } finally {
+          console.log = original;
+        }
+
+        assert.match(lines.join('\n'), /^Usage: omega <command>/, 'the fallback prints the listing');
+        assert.equal(matchCommand(help, {}), false, 'help still only matches when it is named');
+      },
+    },
+  ],
+});

package/test/cli/setup-shared-project-indexes.test.js

@@ -0,0 +1,262 @@
+/**
+ * Test: the index checks leave a SHARED cloud project's indexes alone
+ * ([#716](https://github.com/Omega-JS-Stack/omega/issues/716)).
+ *
+ * A `cloud.shared: true` project is one Firebase project carrying every tenant
+ * brand's collections. `firestore-indexes-synced` pulled its deployed indexes
+ * down and merged them into THIS brand's `firestore.indexes.json` — ~400 lines
+ * of other brands' collections (campaigns, courses, enrollments, inboxes) landing
+ * silently during a test run, ready for the next `git add -A`. On a shared
+ * project the live index set is nobody's single brand to track, so the whole
+ * check is skipped and the consumer's file stays authored.
+ *
+ * `firestore-indexes-file` is the SAME leak one step earlier: it runs BEFORE the
+ * sync check (setup-tests/index.js:89 vs :91), and when the file is missing or
+ * poisoned its fix live-pulled the tenant set in to create it — so gating only
+ * the sync check left the first write ungated. It seeds the template instead,
+ * the same answer a demo-* project already got.
+ *
+ * The ONE stub is `powertools.execute` — the single seam every spawn in these
+ * checks goes through, and the same seam setup-offline-mode.test.js uses. Here it
+ * refuses EVERY command, so any surviving live read fails the test instead of
+ * reaching the network; the control case shims the read-only fetch to the real
+ * command's contract (`firebase firestore:indexes > <file>`) so the ungated path
+ * is proved to still run.
+ *
+ * Run: npx omega test backend:cli/setup-shared-project-indexes
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const powertools = require('node-powertools');
+const FirestoreIndexesSyncedTest = require('../../dist/cli/commands/setup-tests/firestore-indexes-synced.js');
+const FirestoreIndexesFileTest = require('../../dist/cli/commands/setup-tests/firestore-indexes-file.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+// What the indexes-file fix seeds when there is no live set to pull.
+const TEMPLATE_INDEXES = JSON.parse(jetpack.read(path.resolve(__dirname, '../../templates/firestore.indexes.json')));
+
+// What the brand authored, and what the shared project actually carries — the
+// live set is another tenant's collection entirely.
+const LOCAL_INDEXES = {
+  indexes: [
+    { collectionGroup: 'users', queryScope: 'COLLECTION', fields: [{ fieldPath: 'email', order: 'ASCENDING' }] },
+  ],
+  fieldOverrides: [],
+};
+
+const TENANT_INDEXES = {
+  indexes: [
+    { collectionGroup: 'enrollments', queryScope: 'COLLECTION', fields: [{ fieldPath: 'courseId', order: 'ASCENDING' }] },
+  ],
+  fieldOverrides: [],
+};
+
+// Nothing may spawn: on a shared project every live read is the bug.
+async function withSpawnTrap(fn, onCommand) {
+  const original = powertools.execute;
+  const spawned = [];
+
+  powertools.execute = async (command, options) => {
+    spawned.push(command);
+
+    if (onCommand) {
+      return await onCommand(command, options);
+    }
+
+    throw new Error(`spawn trap: nothing may spawn here (got "${command}")`);
+  };
+
+  try {
+    return await fn(spawned);
+  } finally {
+    powertools.execute = original;
+  }
+}
+
+// The `firebase firestore:indexes > <file>` read: the real command writes the
+// live index JSON to the redirect target, which the check then require()s.
+function liveIndexRead(command) {
+  if (!command.startsWith('firebase firestore:indexes')) {
+    throw new Error(`spawn trap: only the read-only index fetch may spawn (got "${command}")`);
+  }
+
+  jetpack.write(command.split('> ')[1].trim(), JSON.stringify(TENANT_INDEXES, null, 2));
+
+  return '';
+}
+
+/**
+ * A target root with committed indexes and a real (non-demo) project id, whose
+ * config declares the cloud project shared or not.
+ *
+ * `opts.indexes` swaps what lands on disk for the indexes-file cases: `false`
+ * writes no file at all, `'poisoned'` writes the 403 error text a failed live
+ * pull shell-redirects into it.
+ */
+function seedTarget(shared, opts = {}) {
+  const targetPath = jetpack.tmpDir({ prefix: 'omega-shared-indexes-' }).path();
+
+  if (opts.indexes === 'poisoned') {
+    jetpack.write(path.join(targetPath, 'firestore.indexes.json'), 'Error 403: Caller is missing permission');
+  } else if (opts.indexes !== false) {
+    jetpack.write(path.join(targetPath, 'firestore.indexes.json'), JSON.stringify(LOCAL_INDEXES, null, 2));
+  }
+
+  jetpack.write(path.join(targetPath, 'config', 'omega.json5'), JSON.stringify({
+    brand: { name: 'Tenant Brand' },
+    cloud: shared ? { shared: true, config: { projectId: 'shared-project' } } : { config: { projectId: 'own-project' } },
+    targets: { backend: {} },
+  }, null, 2));
+
+  return targetPath;
+}
+
+function buildIndexesTest(TestClass, targetPath, projectId) {
+  return new TestClass({
+    main: { projectId: projectId, argv: {}, firebaseProjectPath: targetPath },
+  });
+}
+
+function readIndexes(targetPath) {
+  return JSON.parse(jetpack.read(path.join(targetPath, 'firestore.indexes.json')));
+}
+
+module.exports = defineCases({
+  description: 'the firestore index checks skip a shared cloud project',
+  type: 'group',
+  timeout: 20000,
+
+  tests: [
+    {
+      name: 'a-shared-project-is-never-read',
+      auth: 'none',
+
+      async run({ assert }) {
+        const targetPath = seedTarget(true);
+        const test = buildIndexesTest(FirestoreIndexesSyncedTest, targetPath, 'shared-project');
+
+        await withSpawnTrap(async (spawned) => {
+          assert.equal(await test.run(), true, 'a shared project has no drift of this brand\'s to report');
+          assert.deepEqual(spawned, [], 'no live index read may spawn for a shared project');
+        });
+
+        jetpack.remove(targetPath);
+      },
+    },
+
+    {
+      name: 'a-shared-project-leaves-the-authored-file-untouched',
+      auth: 'none',
+
+      async run({ assert }) {
+        // Belt for a direct caller: run() passes, so the runner never reaches
+        // fix() — and if something does, the merge-and-write stays off.
+        const targetPath = seedTarget(true);
+        const test = buildIndexesTest(FirestoreIndexesSyncedTest, targetPath, 'shared-project');
+
+        await withSpawnTrap(async (spawned) => {
+          await test.fix();
+
+          assert.deepEqual(spawned, [], 'fix() must spawn nothing for a shared project');
+        });
+
+        assert.deepEqual(readIndexes(targetPath), LOCAL_INDEXES, 'the consumer\'s index file stays exactly as authored');
+
+        jetpack.remove(targetPath);
+      },
+    },
+
+    {
+      name: 'a-brands-own-project-still-syncs',
+      auth: 'none',
+
+      async run({ assert }) {
+        // The gate is the shared flag, not a blanket skip: a project this brand
+        // owns still gets its drift read and reported.
+        const targetPath = seedTarget(false);
+        const test = buildIndexesTest(FirestoreIndexesSyncedTest, targetPath, 'own-project');
+
+        await withSpawnTrap(async (spawned) => {
+          assert.equal(await test.run(), false, 'drift on the brand\'s own project must still fail');
+          assert.equal(
+            spawned.some((c) => c.startsWith('firebase firestore:indexes')),
+            true,
+            'the brand\'s own project is still read',
+          );
+        }, liveIndexRead);
+
+        jetpack.remove(targetPath);
+      },
+    },
+
+    {
+      name: 'a-shared-project-seeds-the-template-instead-of-pulling',
+      auth: 'none',
+
+      async run({ assert }) {
+        // The earlier check: with no file to read, the fix used to create one
+        // from the live pull — the tenant set, written in whole.
+        const targetPath = seedTarget(true, { indexes: false });
+        const test = buildIndexesTest(FirestoreIndexesFileTest, targetPath, 'shared-project');
+
+        assert.equal(await test.run(), false, 'a missing indexes file still needs writing');
+
+        await withSpawnTrap(async (spawned) => {
+          await test.fix();
+
+          assert.deepEqual(spawned, [], 'no live index pull may spawn for a shared project');
+        }, liveIndexRead);
+
+        assert.deepEqual(readIndexes(targetPath), TEMPLATE_INDEXES, 'the template\'s empty shape is seeded, not the tenant set');
+
+        jetpack.remove(targetPath);
+      },
+    },
+
+    {
+      name: 'a-shared-project-rewrites-a-poisoned-file-from-the-template',
+      auth: 'none',
+
+      async run({ assert }) {
+        // The other way in: a file poisoned by an earlier failed pull is
+        // treated as missing, and that rewrite pulled the tenant set too.
+        const targetPath = seedTarget(true, { indexes: 'poisoned' });
+        const test = buildIndexesTest(FirestoreIndexesFileTest, targetPath, 'shared-project');
+
+        assert.equal(await test.run(), false, 'a poisoned file is treated as missing');
+
+        await withSpawnTrap(async (spawned) => {
+          await test.fix();
+
+          assert.deepEqual(spawned, [], 'no live index pull may spawn for a shared project');
+        }, liveIndexRead);
+
+        assert.deepEqual(readIndexes(targetPath), TEMPLATE_INDEXES, 'the poisoned file is replaced by the template, not the tenant set');
+
+        jetpack.remove(targetPath);
+      },
+    },
+
+    {
+      name: 'a-demo-project-still-seeds-the-template',
+      auth: 'none',
+
+      async run({ assert }) {
+        // Control: widening the gate must not change what a demo-* project
+        // already did — same seed, same silence.
+        const targetPath = seedTarget(false, { indexes: false });
+        const test = buildIndexesTest(FirestoreIndexesFileTest, targetPath, 'demo-tenant-brand');
+
+        await withSpawnTrap(async (spawned) => {
+          await test.fix();
+
+          assert.deepEqual(spawned, [], 'a demo project has no live project to pull from');
+        }, liveIndexRead);
+
+        assert.deepEqual(readIndexes(targetPath), TEMPLATE_INDEXES, 'the template\'s empty shape is seeded');
+
+        jetpack.remove(targetPath);
+      },
+    },
+  ],
+});

package/test/cli/setup-tests-requires.test.js

@@ -0,0 +1,45 @@
+/**
+ * Test: setup-tests relative requires resolve (pure logic)
+ *
+ * The lazy requires in the setup tests' live-project branches only execute
+ * during a real-project setup run, so a broken path ships silently and first
+ * fails in a consumer's boot (the playground's full `omega dev` walk hit
+ * `require('../index')`, a module that never existed). Every relative require
+ * in the directory must resolve from its own location.
+ *
+ * Run: npx omega test backend:cli/setup-tests-requires
+ */
+const fs = require('fs');
+const path = require('path');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const DIR = path.join(__dirname, '..', '..', 'dist', 'cli', 'commands', 'setup-tests');
+
+module.exports = defineCases({
+  description: 'Setup-tests relative requires resolve',
+  type: 'group',
+  tests: [
+    {
+      name: 'every-relative-require-in-setup-tests-resolves',
+      async run({ assert }) {
+        const files = fs.readdirSync(DIR).filter((f) => f.endsWith('.js'));
+        assert.equal(files.length > 10, true, `setup-tests directory found (${files.length} modules)`);
+
+        for (const file of files) {
+          const source = fs.readFileSync(path.join(DIR, file), 'utf8');
+
+          for (const match of source.matchAll(/require\(\s*['"](\.[^'"]+)['"]\s*\)/g)) {
+            const target = match[1];
+            let resolved = true;
+            try {
+              require.resolve(path.join(DIR, target));
+            } catch (e) {
+              resolved = false;
+            }
+            assert.equal(resolved, true, `${file} requires "${target}" which does not resolve`);
+          }
+        }
+      },
+    },
+  ],
+});