@omega.js/backend 0.1.0

package/test/routes/admin/repo-content.test.js

@@ -0,0 +1,223 @@
+/**
+ * Test: POST /admin/repo/content
+ * Tests the admin write repo content endpoint
+ * Writes arbitrary content to a GitHub repository
+ * Requires admin/blogger role, GitHub API key, and a resolvable github repo (targets.backend.github.repo slug or repo.providers.github.org + brand.id)
+ *
+ * IMPORTANT: These tests require GH_TOKEN and a resolvable github repo to be configured.
+ * If GitHub is not configured, the tests will fail.
+ *
+ * This is a suite because we need to clean up created files and cancel workflows after tests.
+ */
+const { Octokit } = require('@octokit/rest');
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+
+// Test file paths that will be created and need cleanup
+const TEST_FILES = [
+  '_test/backend-write-test.txt',
+  '_test/type-test.txt',
+];
+
+module.exports = defineCases({
+  description: 'Admin write content to GitHub repo',
+  type: 'suite',
+  timeout: 120000,
+  skip: !process.env.TEST_EXTENDED_MODE ? 'TEST_EXTENDED_MODE env var not set (skipping GitHub write tests)' : false,
+
+  tests: [
+    // Test 1: Missing path returns 400 error
+    {
+      name: 'missing-path-rejected',
+      auth: 'admin',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('backend-manager/admin/repo/content', {
+          content: 'Test content',
+        });
+
+        assert.isError(response, 400, 'Missing path should return 400');
+      },
+    },
+
+    // Test 2: Missing content returns 400 error
+    {
+      name: 'missing-content-rejected',
+      auth: 'admin',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('backend-manager/admin/repo/content', {
+          path: '_test/backend-test-file.txt',
+        });
+
+        assert.isError(response, 400, 'Missing content should return 400');
+      },
+    },
+
+    // Test 3: Admin can write content
+    {
+      name: 'admin-can-write-content',
+      auth: 'admin',
+      timeout: 60000,
+
+      async run({ http, assert, state }) {
+        const uniqueContent = `@omega.js/backend Test - ${new Date().toISOString()}`;
+        const response = await http.post('backend-manager/admin/repo/content', {
+          path: '_test/backend-write-test.txt',
+          content: uniqueContent,
+        });
+
+        assert.isSuccess(response, 'Admin should be able to write content');
+        assert.hasProperty(response, 'data.path', 'Response should contain path');
+        assert.equal(response.data.path, '_test/backend-write-test.txt', 'Path should match');
+
+        // Store for cleanup
+        state.filesCreated = state.filesCreated || [];
+        state.filesCreated.push('_test/backend-write-test.txt');
+      },
+    },
+
+    // Test 4: Content type defaults to text
+    {
+      name: 'content-type-default',
+      auth: 'admin',
+      timeout: 30000,
+
+      async run({ http, assert, state }) {
+        const response = await http.post('backend-manager/admin/repo/content', {
+          path: '_test/type-test.txt',
+          content: 'Test content with default type',
+        });
+
+        assert.isSuccess(response, 'Write with default type should succeed');
+        assert.hasProperty(response, 'data.type', 'Response should contain type');
+        assert.equal(response.data.type, 'text', 'Default type should be text');
+
+        // Store for cleanup
+        state.filesCreated = state.filesCreated || [];
+        state.filesCreated.push('_test/type-test.txt');
+      },
+    },
+
+    // Test 5: Non-existent repo returns 404
+    {
+      name: 'nonexistent-repo-returns-404',
+      auth: 'admin',
+      timeout: 30000,
+
+      async run({ http, assert }) {
+        const response = await http.post('backend-manager/admin/repo/content', {
+          path: '_test/custom-repo-test.txt',
+          content: 'Test content',
+        });
+
+        assert.isError(response, 404, 'Non-existent repo should return 404');
+      },
+    },
+
+    // --- Auth rejection tests (at end per convention) ---
+    {
+      name: 'unauthenticated-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('backend-manager/admin/repo/content', {
+          path: '_test/backend-test-file.txt',
+          content: 'Test content',
+        });
+
+        assert.isError(response, 401, 'Write repo content should fail without authentication');
+      },
+    },
+
+    {
+      name: 'non-admin-rejected',
+      auth: 'basic',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('backend-manager/admin/repo/content', {
+          path: '_test/backend-test-file.txt',
+          content: 'Test content',
+        });
+
+        assert.isError(response, 403, 'Write repo content should fail for non-admin user');
+      },
+    },
+
+    // Cleanup - delete test files and cancel workflows
+    {
+      name: 'cleanup',
+      auth: 'admin',
+      timeout: 60000,
+
+      async run({ state, config }) {
+        const { brandRepoOwner, brandRepoName } = require('../../helpers/_shared-config.js');
+        if (!process.env.GH_TOKEN || !brandRepoOwner(config) || !brandRepoName(config)) {
+          return;
+        }
+
+        const octokit = new Octokit({ auth: process.env.GH_TOKEN });
+
+        // Owner/repo from the shared brand-repo derivation (e.g., 'https://github.com/owner/repo')
+        const repoMatch = [null, brandRepoOwner(config), brandRepoName(config)];
+        if (!repoMatch) {
+          return;
+        }
+        const owner = repoMatch[1];
+        const repo = repoMatch[2];
+
+        // Delete test files
+        const filesToDelete = state.filesCreated || TEST_FILES;
+        for (const filePath of filesToDelete) {
+          try {
+            const { data: fileData } = await octokit.rest.repos.getContent({
+              owner,
+              repo,
+              path: filePath,
+            });
+
+            await octokit.rest.repos.deleteFile({
+              owner,
+              repo,
+              path: filePath,
+              message: `🧹 @omega.js/backend test cleanup: ${filePath}`,
+              sha: fileData.sha,
+            });
+          } catch (e) {
+            // File might not exist, ignore
+          }
+        }
+
+        // Cancel running workflows triggered by our test commits
+        try {
+          const { data: runs } = await octokit.rest.actions.listWorkflowRunsForRepo({
+            owner,
+            repo,
+            status: 'in_progress',
+            per_page: 10,
+          });
+
+          for (const run of runs.workflow_runs) {
+            if (run.head_commit?.message?.includes('admin:write-repo-content')
+                || run.head_commit?.message?.includes('@omega.js/backend test cleanup')) {
+              try {
+                await octokit.rest.actions.cancelWorkflowRun({
+                  owner,
+                  repo,
+                  run_id: run.id,
+                });
+              } catch (e) {
+                // May already be completed, ignore
+              }
+            }
+          }
+        } catch (e) {
+          // Workflow cancellation failed, not critical
+        }
+      },
+    },
+  ],
+});

package/test/routes/admin/stats.test.js

@@ -0,0 +1,114 @@
+/**
+ * Test: GET /admin/stats
+ * Tests the admin get stats endpoint
+ * Requires admin authentication
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Admin get stats operation',
+  type: 'group',
+  tests: [
+    // Test 1: Admin can get stats
+    {
+      name: 'admin-get-stats-succeeds',
+      auth: 'admin',
+      timeout: 30000,
+
+      async run({ http, assert }) {
+        const response = await http.get('backend-manager/admin/stats', {});
+
+        assert.isSuccess(response, 'Get stats should succeed with admin auth');
+        assert.ok(
+          typeof response.data === 'object',
+          'Response data should be an object'
+        );
+      },
+    },
+
+    // Test 2: Stats contains users field
+    {
+      name: 'stats-contains-users',
+      auth: 'admin',
+      timeout: 30000,
+
+      async run({ http, assert }) {
+        const response = await http.get('backend-manager/admin/stats', {});
+
+        assert.isSuccess(response, 'Get stats should succeed');
+        assert.hasProperty(response, 'data.users', 'Stats should contain users field');
+        assert.hasProperty(response, 'data.users.total', 'Users should have total field');
+        assert.ok(
+          typeof response.data.users.total === 'number',
+          'users.total should be a number'
+        );
+      },
+    },
+
+    // Test 3: Stats with update flag refreshes data
+    {
+      name: 'stats-with-update',
+      auth: 'admin',
+      timeout: 60000,
+
+      async run({ http, assert }) {
+        const response = await http.get('backend-manager/admin/stats', {
+          update: { users: true },
+        });
+
+        assert.isSuccess(response, 'Get stats with update should succeed');
+        assert.hasProperty(response, 'data.users.total', 'Updated stats should have users.total');
+        assert.ok(
+          response.data.users.total >= 0,
+          'users.total should be a non-negative number'
+        );
+      },
+    },
+
+    // Test 4: Stats contains metadata
+    {
+      name: 'stats-has-metadata',
+      auth: 'admin',
+      timeout: 30000,
+
+      async run({ http, assert }) {
+        await http.get('backend-manager/admin/stats', {
+          update: { users: true },
+        });
+
+        const response = await http.get('backend-manager/admin/stats', {});
+
+        assert.isSuccess(response, 'Get stats should succeed');
+        if (response.data.metadata) {
+          assert.hasProperty(response, 'data.metadata.updated', 'Metadata should have updated timestamp');
+        }
+      },
+    },
+
+    // Test 5: Unauthenticated request fails
+    {
+      name: 'unauthenticated-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.get('backend-manager/admin/stats', {});
+
+        assert.isError(response, 401, 'Get stats should fail without authentication');
+      },
+    },
+
+    // Test 6: Non-admin user fails
+    {
+      name: 'non-admin-rejected',
+      auth: 'user',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.get('backend-manager/admin/stats', {});
+
+        assert.isError(response, 403, 'Get stats should fail for non-admin user');
+      },
+    },
+  ],
+});

package/test/routes/admin/users-disable.test.js

@@ -0,0 +1,63 @@
+/**
+ * Test: routes/admin/users/disable
+ * POST /admin/users/disable — auth-level disable/enable with refresh-token
+ * revocation on disable. Read back through GET /admin/users/list (the auth
+ * join carries the disabled flag). The round-trip re-enables the persona so
+ * the fixture is left exactly how it was found.
+ *
+ * Run: npx omega test routes/admin/users-disable
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'routes/admin/users/disable',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'disable-round-trip-via-auth-join',
+      async run({ http, assert, accounts }) {
+        const uid = accounts.refunded.uid;
+
+        // Disable
+        const disable = await http.as('admin').post('backend-manager/admin/users/disable', { uid });
+        assert.isSuccess(disable, 'disable responds');
+        assert.ok(disable.data.disabled === true, 'response reflects disabled');
+
+        // Read back through the list route's auth join
+        const listDisabled = await http.as('admin').get('backend-manager/admin/users/list', { search: uid });
+        assert.isSuccess(listDisabled, 'list responds');
+        assert.ok(listDisabled.data.users.length === 1, 'uid search finds the user');
+        assert.ok(listDisabled.data.users[0].auth.disabled === true, 'auth join shows disabled');
+
+        // Re-enable (leave the persona how we found it)
+        const enable = await http.as('admin').post('backend-manager/admin/users/disable', { uid, disabled: false });
+        assert.isSuccess(enable, 'enable responds');
+        assert.ok(enable.data.disabled === false, 'response reflects enabled');
+
+        const listEnabled = await http.as('admin').get('backend-manager/admin/users/list', { search: uid });
+        assert.ok(listEnabled.data.users[0].auth.disabled === false, 'auth join shows enabled again');
+      },
+    },
+
+    {
+      name: 'self-disable-blocked',
+      async run({ http, assert, accounts }) {
+        // Authenticate AS the admin user (private key) — .as('admin') is the
+        // admin KEY, which carries no uid for the self-guard to match
+        const response = await http.withPrivateKey(accounts.admin.privateKey).post('backend-manager/admin/users/disable', { uid: accounts.admin.uid });
+
+        assert.isError(response, 400, 'self-disable is refused');
+      },
+    },
+
+    {
+      name: 'unknown-uid-404s',
+      async run({ http, assert }) {
+        const response = await http.as('admin').post('backend-manager/admin/users/disable', { uid: 'no-such-user-omega-test' });
+
+        assert.isError(response, 404, 'unknown uid 404s');
+      },
+    },
+  ],
+});

package/test/routes/admin/users-list.test.js

@@ -0,0 +1,71 @@
+/**
+ * Test: routes/admin/users/list
+ * GET /admin/users/list — the paginated user directory with the Firebase
+ * Auth join (providers, disabled, verification, last sign-in) that client
+ * SDKs cannot read. Powers the admin users table + the list_users MCP tool.
+ *
+ * Run: npx omega test routes/admin/users-list
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'routes/admin/users/list',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'lists-users-with-auth-join',
+      async run({ http, assert }) {
+        const response = await http.as('admin').get('backend-manager/admin/users/list', { limit: 5 });
+
+        assert.isSuccess(response, 'Route responds');
+        assert.ok(Array.isArray(response.data.users), 'users is an array');
+        assert.ok(response.data.users.length > 0, 'seeded personas appear');
+        assert.ok(response.data.users.length <= 5, 'limit respected');
+
+        const row = response.data.users[0];
+        assert.ok(typeof row.uid === 'string' && row.uid.length, 'row carries uid');
+        assert.ok('email' in row && 'plan' in row && 'roles' in row, 'row carries directory fields');
+        assert.ok(row.auth === null || typeof row.auth.disabled === 'boolean', 'auth join carries disabled flag');
+        assert.ok(row.auth === null || Array.isArray(row.auth.providers), 'auth join carries providers');
+      },
+    },
+
+    {
+      name: 'search-filters-by-email-prefix',
+      async run({ http, assert }) {
+        const response = await http.as('admin').get('backend-manager/admin/users/list', { search: '_test.admin' });
+
+        assert.isSuccess(response, 'Route responds');
+        assert.ok(Array.isArray(response.data.users), 'users is an array');
+        assert.ok(response.data.users.length >= 1, 'prefix search finds the admin persona');
+        assert.ok(
+          response.data.users.every((u) => String(u.email || '').startsWith('_test.admin')),
+          'every hit matches the prefix'
+        );
+      },
+    },
+
+    {
+      name: 'cursor-pagination-advances',
+      async run({ http, assert }) {
+        const page1 = await http.as('admin').get('backend-manager/admin/users/list', { limit: 2 });
+
+        assert.isSuccess(page1, 'page 1 responds');
+        assert.ok(page1.data.users.length === 2, 'page 1 is full');
+        assert.ok(typeof page1.data.nextCursor === 'string' && page1.data.nextCursor.length, 'full page carries nextCursor');
+
+        const page2 = await http.as('admin').get('backend-manager/admin/users/list', { limit: 2, startAfter: page1.data.nextCursor });
+
+        assert.isSuccess(page2, 'page 2 responds');
+        assert.ok(page2.data.users.length > 0, 'page 2 has rows');
+
+        const page1Uids = new Set(page1.data.users.map((u) => u.uid));
+        assert.ok(
+          page2.data.users.every((u) => !page1Uids.has(u.uid)),
+          'page 2 never repeats page 1'
+        );
+      },
+    },
+  ],
+});

package/test/routes/content/post.test.js

@@ -0,0 +1,60 @@
+/**
+ * Test: GET /content/post
+ * Tests the content fetch post endpoint
+ * Fetches blog post content from GitHub
+ * Requires GitHub API key and a resolvable github repo (targets.backend.github.repo slug or repo.providers.github.org + brand.id)
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'General fetch post from GitHub',
+  type: 'group',
+  tests: [
+    // Test 1: Missing URL returns 400 error
+    {
+      name: 'missing-url-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.get('backend-manager/content/post', {});
+
+        assert.isError(response, 400, 'Missing URL should return 400');
+      },
+    },
+
+    // Test 2: Non-existent post returns 404
+    // The route searches live GitHub (route 500s "not configured" without a token),
+    // so this only runs when GH_TOKEN is set — matches the mailbox-key skip pattern.
+    {
+      name: 'nonexistent-post-returns-404',
+      auth: 'none',
+      timeout: 30000,
+      skip: !process.env.GH_TOKEN ? 'GH_TOKEN not set (content/post searches live GitHub)' : false,
+
+      async run({ http, assert }) {
+        const response = await http.get('backend-manager/content/post', {
+          url: 'https://example.com/blog/this-post-definitely-does-not-exist-12345',
+        });
+
+        assert.isError(response, 404, 'Non-existent post should return 404');
+      },
+    },
+
+    // Test 3: Authenticated user fetching non-existent post returns 404
+    {
+      name: 'authenticated-nonexistent-returns-404',
+      auth: 'basic',
+      timeout: 30000,
+      skip: !process.env.GH_TOKEN ? 'GH_TOKEN not set (content/post searches live GitHub)' : false,
+
+      async run({ http, assert }) {
+        const response = await http.get('backend-manager/content/post', {
+          url: 'https://example.com/blog/nonexistent-test-post-12345',
+        });
+
+        assert.isError(response, 404, 'Non-existent post should return 404');
+      },
+    },
+  ],
+});

package/test/routes/general/uuid.test.js

@@ -0,0 +1,133 @@
+/**
+ * Test: UUID Route
+ * Tests the new RESTful UUID endpoint using proper HTTP verbs
+ */
+
+const defineCases = require('../../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'UUID route',
+  type: 'group',
+  tests: [
+    {
+      name: 'v4-random-uuid',
+      auth: 'none',
+      timeout: 10000,
+
+      async run({ http, assert }) {
+        // POST /omega/general/uuid
+        const response = await http.post('backend-manager/general/uuid', {
+          version: '4',
+        });
+
+        assert.isSuccess(response, 'UUID v4 generation should succeed');
+        assert.hasProperty(response, 'data.uuid', 'Response should contain uuid');
+        assert.match(
+          response.data.uuid,
+          /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+          'UUID v4 should have correct format'
+        );
+
+        return { success: true };
+      },
+    },
+
+    {
+      name: 'v5-namespaced-uuid',
+      auth: 'none',
+      timeout: 10000,
+
+      async run({ http, assert }) {
+        const response = await http.post('backend-manager/general/uuid', {
+          version: '5',
+          name: 'test-name-for-uuid',
+        });
+
+        assert.isSuccess(response, 'UUID v5 generation should succeed');
+        assert.hasProperty(response, 'data.uuid', 'Response should contain uuid');
+        assert.match(
+          response.data.uuid,
+          /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+          'UUID v5 should have correct format'
+        );
+
+        return { success: true };
+      },
+    },
+
+    {
+      name: 'v5-deterministic',
+      auth: 'none',
+      timeout: 10000,
+
+      async run({ http, assert }) {
+        const response1 = await http.post('backend-manager/general/uuid', {
+          version: '5',
+          name: 'test-name-for-uuid',
+        });
+
+        const response2 = await http.post('backend-manager/general/uuid', {
+          version: '5',
+          name: 'test-name-for-uuid',
+        });
+
+        assert.isSuccess(response1, 'First UUID v5 generation should succeed');
+        assert.isSuccess(response2, 'Second UUID v5 generation should succeed');
+        assert.equal(
+          response1.data.uuid,
+          response2.data.uuid,
+          'UUID v5 should be deterministic - same input should produce same output'
+        );
+
+        return { success: true };
+      },
+    },
+
+    {
+      name: 'v5-requires-name',
+      auth: 'none',
+      timeout: 10000,
+
+      async run({ http, assert }) {
+        const response = await http.post('backend-manager/general/uuid', {
+          version: '5',
+        });
+
+        assert.isError(response, 400, 'UUID v5 without name should return 400');
+
+        return { success: true };
+      },
+    },
+
+    {
+      name: 'invalid-version-rejected',
+      auth: 'none',
+      timeout: 10000,
+
+      async run({ http, assert }) {
+        const response = await http.post('backend-manager/general/uuid', {
+          version: '99',
+        });
+
+        assert.isError(response, 400, 'Invalid version should return 400');
+
+        return { success: true };
+      },
+    },
+
+    {
+      name: 'method-mismatch-is-405',
+      auth: 'none',
+      timeout: 10000,
+
+      async run({ http, assert }) {
+        // uuid is a method-file route (post.js only) — a GET must answer an
+        // honest 405, not the old 500 "Unable to load route" (friction #17)
+        const response = await http.get('backend-manager/general/uuid');
+
+        assert.isError(response, 405, 'GET on a POST-only route should return 405');
+
+        return { success: true };
+      },
+    },
+  ],
+});