@omega.js/extension 0.1.0

package/dist/vendor/devkit/target-secrets.js

@@ -0,0 +1,165 @@
+/**
+ * The `.env` → GitHub Actions secrets publisher, once, for every target that
+ * publishes plain string secrets
+ * ([#627](https://github.com/Omega-JS-Stack/omega/issues/627) review).
+ *
+ * Web built it first (#189) and the extension needed the same thing (#680), so
+ * for one wave there were two near-byte-identical copies — same five skip
+ * cases, same declared-repo guard, same `gh` transport, same wording. This is
+ * the ONE copy; each framework binds it with its own target string and nothing
+ * else.
+ *
+ *   1. DERIVE — the KEY SET is the env schema's: every entry whose `delivery`
+ *      names the target (`publishSecretKeys(target)`, @omega.js/config). Never
+ *      "whatever the composed .env holds", which published a brand's unrelated
+ *      keys to a runner.
+ *   2. COLLECT — the VALUES come from the target's COMPOSED env
+ *      (`composeTargetEnv`, [#678](https://github.com/Omega-JS-Stack/omega/issues/678)):
+ *      company ← brand ← target `.env`, the brand-side layers schema-filtered
+ *      to the keys that target reads with `deliverAs` applied (a brand's
+ *      GOOGLE_ANALYTICS_SECRET_WEB arrives as GOOGLE_ANALYTICS_SECRET). FILES
+ *      only — the shell is never a source, so CI gets what the brand's files
+ *      say under any shell. `machineLocal` keys (#454) need no filter here: the
+ *      schema drops them from the delivered set itself.
+ *   3. GUARD — secrets belong to the repo whose Actions run the workflow, and
+ *      the only acceptable proof of which repo that is, is the brand's own
+ *      config (`repo.providers.github`). An inferred git remote is not proof: a
+ *      target vendored into a framework/test monorepo, a cloned starter still
+ *      pointing at the template author, or any fork would publish this brand's
+ *      `.env` to a stranger's Actions.
+ *   4. PUBLISH — each collected key becomes a repo Actions secret via devkit's
+ *      `gh` boundary (values on stdin, never logged).
+ *
+ * Every skip is LOUD (a line, never silence). A missing/signed-out `gh` is NOT
+ * a skip — it throws the boundary's instructions (install, `gh auth login`, or
+ * `omega deploy --no-secrets`).
+ *
+ * Desktop binds it too ([#682](https://github.com/Omega-JS-Stack/omega/issues/682)),
+ * over the `resolveValue` seam: its signing secrets are named by PATH in the
+ * cascade (`CSC_LINK=config/certs/dev-id.p12`) and what CI needs is the FILE, so
+ * it base64-encodes an existing file between COLLECT and PUBLISH. That seam is
+ * the only shape difference between the three binds — the transport is one.
+ */
+const { composeTargetEnv } = require('../config/index.js');
+const { publishSecretKeys } = require('../config/env-delivery.js');
+const { publishActionsSecrets } = require('./actions-secrets.js');
+const { resolveRepo } = require('./deploy.js');
+
+/**
+ * The publishable secrets for a target: the schema's delivery set for it,
+ * valued from the composed env. An empty value never claims a key.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root (its .env is the local layer).
+ * @param {string} options.target - Target name ('web', 'extension', …).
+ * @param {function} [options.resolveValue] - `(value, key) => string`, the seam
+ *   applied to each collected value before it travels (desktop base64-encodes
+ *   its file-path signing secrets). A falsy return DROPS the key, exactly as an
+ *   empty composed value does.
+ * @returns {Object<string, string>} key → value, ready to publish.
+ */
+function collectTargetSecrets(options) {
+  const { targetDir, target, resolveValue } = options;
+  // PRODUCTION, named rather than sniffed: these values fuel the runner's
+  // release build, and the composer would otherwise default to whatever
+  // environment this shell happens to be
+  // ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)) — the same
+  // determinism the "FILES only, never the shell" rule above buys.
+  const { values } = composeTargetEnv({ targetDir, target, environment: 'production' });
+
+  const secrets = {};
+  for (const key of publishSecretKeys(target)) {
+    if (!values[key]) continue;
+    const value = resolveValue ? resolveValue(values[key], key) : values[key];
+    if (value) secrets[key] = value;
+  }
+
+  return secrets;
+}
+
+/**
+ * The brand's OWN repo as `owner/name`, from the target's resolved config — the
+ * same derivation `omega deploy --direct` uses (`repo.providers.github`, name
+ * falling back to brand.id). Null when the config declares nothing usable or
+ * doesn't load.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @param {string} options.target - Target name ('web', 'extension', …).
+ * @returns {string|null}
+ */
+function declaredBrandRepo(options) {
+  try {
+    const { loadConfig, brandRepoOwner, brandRepoName } = require('../config/index.js');
+    const { config } = loadConfig(options.targetDir, options.target);
+    if (!config) return null;
+
+    const owner = brandRepoOwner(config);
+    const name = brandRepoName(config);
+    return owner && name ? `${owner}/${name}` : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * The `omega deploy` precheck: publish the target's collected `.env` values as
+ * repo Actions secrets.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @param {string} options.target - Target name ('web', 'extension', …).
+ * @param {object} options.logger - `{ log, warn, error }`.
+ * @param {object} [options.env] - Env map (default: process.env).
+ * @param {function} [options.resolveValue] - Value seam (see collectTargetSecrets).
+ * @param {function} [options.execFn] - Injectable `gh` exec (tests).
+ * @param {function} [options.gitExecFn] - Injectable `git` exec for remote discovery (tests).
+ * @returns {{ skipped: string }|{ published: string[], failed: Array<object> }}
+ */
+function publishTargetSecrets(options) {
+  options = options || {};
+  const { targetDir, target, logger } = options;
+  const env = options.env || process.env;
+
+  // CI runs the generated workflow as its build/publish step — the secrets
+  // already exist there and the runner token can't write them.
+  if (env.GITHUB_ACTIONS === 'true' || env.CI === 'true') {
+    logger.log('Skipping secret publication — CI already has the repo secrets');
+    return { skipped: 'ci' };
+  }
+
+  const secrets = collectTargetSecrets({ targetDir, target, resolveValue: options.resolveValue });
+  const keys = Object.keys(secrets);
+  if (!keys.length) {
+    logger.warn('Skipping secret publication — no keys composed for this target from the .env cascade (company/brand/target)');
+    return { skipped: 'no-secrets' };
+  }
+
+  let repo;
+  try {
+    const { owner, repo: name } = resolveRepo({ cwd: targetDir, execFn: options.gitExecFn });
+    repo = `${owner}/${name}`;
+  } catch (e) {
+    logger.warn(`Skipping secret publication — no GitHub remote here (${e.message})`);
+    return { skipped: 'no-remote' };
+  }
+
+  const declared = declaredBrandRepo({ targetDir, target });
+  if (!declared) {
+    logger.warn('Skipping secret publication — this brand names no GitHub repo in config (repo.providers.github). Set it, then re-run `omega deploy`.');
+    return { skipped: 'no-declared-repo' };
+  }
+  if (declared.toLowerCase() !== repo.toLowerCase()) {
+    logger.warn(`Skipping secret publication — the git remote here is ${repo}, but this brand's repo is ${declared}. Run \`omega deploy\` from the brand's own checkout.`);
+    return { skipped: 'repo-mismatch' };
+  }
+
+  logger.log(`Publishing ${keys.length} secret(s) to ${repo}: ${keys.join(', ')}`);
+
+  const result = publishActionsSecrets({ repo, secrets, logger, execFn: options.execFn });
+  logger.log(`Published ${result.published.length}/${keys.length} secret(s) to ${repo}`);
+
+  return result;
+}
+
+module.exports = { collectTargetSecrets, declaredBrandRepo, publishTargetSecrets };

package/dist/vendor/devkit/test/assert.js

@@ -0,0 +1,120 @@
+// Tiny expect() — Jest/Vitest-compatible subset.
+// Each matcher throws on failure; the runner catches.
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== 'object') return false;
+
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((x, i) => deepEqual(x, b[i]));
+  }
+
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => deepEqual(a[k], b[k]));
+}
+
+function fmt(v) {
+  if (typeof v === 'string') return JSON.stringify(v);
+  if (v === undefined) return 'undefined';
+  try {
+    return JSON.stringify(v);
+  } catch (e) {
+    return String(v);
+  }
+}
+
+function fail(message) {
+  const err = new Error(message);
+  err.name = 'AssertionError';
+  throw err;
+}
+
+function buildMatchers(actual, negated) {
+  const not = negated ? 'not ' : '';
+
+  function check(cond, message) {
+    if (negated) cond = !cond;
+    if (!cond) fail(message);
+  }
+
+  return {
+    toBe(expected) {
+      check(actual === expected, `expected ${fmt(actual)} ${not}to be ${fmt(expected)}`);
+    },
+    toEqual(expected) {
+      check(deepEqual(actual, expected), `expected ${fmt(actual)} ${not}to deeply equal ${fmt(expected)}`);
+    },
+    toBeTruthy() {
+      check(!!actual, `expected ${fmt(actual)} ${not}to be truthy`);
+    },
+    toBeFalsy() {
+      check(!actual, `expected ${fmt(actual)} ${not}to be falsy`);
+    },
+    toBeDefined() {
+      check(actual !== undefined, `expected ${fmt(actual)} ${not}to be defined`);
+    },
+    toBeUndefined() {
+      check(actual === undefined, `expected ${fmt(actual)} ${not}to be undefined`);
+    },
+    toBeNull() {
+      check(actual === null, `expected ${fmt(actual)} ${not}to be null`);
+    },
+    toContain(item) {
+      const has = Array.isArray(actual)
+        ? actual.includes(item)
+        : (typeof actual === 'string' && actual.includes(item));
+      check(has, `expected ${fmt(actual)} ${not}to contain ${fmt(item)}`);
+    },
+    toHaveProperty(key) {
+      const has = actual != null && Object.prototype.hasOwnProperty.call(actual, key);
+      check(has, `expected ${fmt(actual)} ${not}to have property "${key}"`);
+    },
+    toMatch(regex) {
+      check(regex.test(actual), `expected ${fmt(actual)} ${not}to match ${regex}`);
+    },
+    toBeInstanceOf(cls) {
+      check(actual instanceof cls, `expected value ${not}to be instance of ${cls.name}`);
+    },
+    toBeGreaterThan(n) {
+      check(actual > n, `expected ${fmt(actual)} ${not}to be > ${n}`);
+    },
+    toBeLessThan(n) {
+      check(actual < n, `expected ${fmt(actual)} ${not}to be < ${n}`);
+    },
+    async toThrow(matcher) {
+      let threw = false;
+      let thrown;
+      try {
+        if (typeof actual === 'function') {
+          await actual();
+        }
+      } catch (e) {
+        threw = true;
+        thrown = e;
+      }
+      if (!threw) {
+        return check(false, `expected function ${not}to throw`);
+      }
+      if (matcher instanceof RegExp) {
+        check(matcher.test(thrown.message), `expected thrown message ${not}to match ${matcher} (got: ${thrown.message})`);
+      } else if (typeof matcher === 'string') {
+        check(thrown.message.includes(matcher), `expected thrown message ${not}to contain "${matcher}" (got: ${thrown.message})`);
+      } else {
+        check(true, '');
+      }
+    },
+  };
+}
+
+function expect(actual) {
+  const m = buildMatchers(actual, false);
+  m.not = buildMatchers(actual, true);
+  return m;
+}
+
+module.exports = expect;

package/dist/vendor/devkit/test/define-cases.js

@@ -0,0 +1,104 @@
+// defineCases — the wrapper every OMEGA case file exports its spec through
+// ([#630](https://github.com/Omega-JS-Stack/omega/issues/630)).
+//
+// A case file is a plain module: `module.exports = { tests: [...] }` with the
+// bodies as `run(ctx)` functions. Only the OMEGA runner (src/test/runner-core.js
+// here, @omega.js/backend's own runner there) ever CALLS those bodies. So
+// `node --test <case-file>` loads the module, executes nothing, and reports
+// `pass 1` — a hollow green that reads like a passing suite to a human and to a
+// verifier alike. That is the trap this closes.
+//
+// The signal is `NODE_TEST_CONTEXT`, which node:test sets in the child process
+// it spawns per file (`child-v8`); it is present for the whole module load, so a
+// require-time check sees it. It is NOT enough on its own: the env var is
+// inherited, so a legitimate `omega test` run nested inside a node:test process
+// would trip too. The runners therefore call markRunnerActive() before loading
+// any case file, and that opt-out is an ENV var rather than a module flag
+// because the desktop/extension lanes load their case files in spawned children
+// (Electron), which inherit the environment but not module state.
+
+const path = require('path');
+
+// Set by every OMEGA case runner before it loads a case file; inherited by the
+// children those runners spawn. Its presence means "the cases are about to run
+// for real", which is exactly what NODE_TEST_CONTEXT alone cannot tell us.
+const RUNNER_ENV = 'OMEGA_CASE_RUNNER';
+
+/**
+ * Mark the current process (and anything it spawns) as an OMEGA case run.
+ * @returns {void}
+ */
+function markRunnerActive() {
+  process.env[RUNNER_ENV] = 'true';
+}
+
+/**
+ * Resolve the file that called defineCases, so the failure can name it.
+ * @returns {string|null} Absolute path, or null when the stack is unreadable.
+ */
+function callerFile() {
+  const original = Error.prepareStackTrace;
+  try {
+    Error.prepareStackTrace = (_, frames) => frames;
+    const error = new Error();
+    Error.captureStackTrace(error, defineCases);
+    const frames = error.stack;
+    return (frames && frames[0] && frames[0].getFileName()) || null;
+  } catch (e) {
+    return null;
+  } finally {
+    Error.prepareStackTrace = original;
+  }
+}
+
+/**
+ * The runner-scoped path a human types to run just this file, derived from the
+ * case file's position under its test root (`test/suites/` or `test/`).
+ * @param {string|null} file - Absolute path of the case file.
+ * @returns {string} A path filter, or '' when the file sits outside a test root.
+ */
+function scopedPath(file) {
+  if (!file) return '';
+  const normalized = file.split(path.sep).join('/');
+  const root = ['/test/suites/', '/test/'].find((marker) => normalized.includes(marker));
+  if (!root) return '';
+  // FIRST occurrence anchors on the package's test root: a nested test/ dir
+  // (backend test/routes/test/) must stay part of the filter, not swallow it.
+  return normalized
+    .slice(normalized.indexOf(root) + root.length)
+    .replace(/\.test\.js$/, '')
+    .replace(/\.js$/, '');
+}
+
+/**
+ * Return a case spec, failing loudly when the file was loaded by `node --test`.
+ * @param {object|Array} spec - The case-runner spec (suite, group, standalone, or array form).
+ * @returns {object|Array} The same spec, unchanged.
+ */
+function defineCases(spec) {
+  // NODE_TEST_CONTEXT only exists in the default per-file child; with
+  // --experimental-test-isolation=none the file loads in the main process,
+  // where the --test flag itself is the surviving signal.
+  if ((process.env.NODE_TEST_CONTEXT || process.execArgv.includes('--test')) && process.env[RUNNER_ENV] !== 'true') {
+    const file = callerFile();
+    const filter = scopedPath(file);
+    throw new Error([
+      'OMEGA case file loaded under `node --test` — NOTHING RAN.',
+      '',
+      `  ${file || '(this file)'}`,
+      '',
+      '`node --test` only loads the module; the case bodies never execute, so the',
+      'run reports a hollow pass. These cases run under the OMEGA runner:',
+      '',
+      `  npx omega test framework:${filter}   (a framework suite)`,
+      `  npx omega test ${filter}             (a project's own test/)`,
+      '',
+    ].join('\n'));
+  }
+
+  return spec;
+}
+
+module.exports = defineCases;
+module.exports.markRunnerActive = markRunnerActive;
+module.exports.RUNNER_ENV = RUNNER_ENV;

package/dist/vendor/devkit/test/extended-mode-warning.js

@@ -0,0 +1,22 @@
+// TEST_EXTENDED_MODE warning — SSOT for consistent messaging across the frameworks.
+//
+// `TEST_EXTENDED_MODE` is the shared, unprefixed env var that opts a test run into
+// hitting REAL external services instead of skipping/stubbing them. Off by default so
+// `npx omega test` stays fast and offline-safe. Each framework passes its own detail
+// lines describing what "real calls" means on its surface; the headline is shared.
+
+/**
+ * Build the warning-line array printed (and teed to logs/test.log) by each
+ * framework's test command when TEST_EXTENDED_MODE is on.
+ *
+ * @param {string[]} detailLines - Framework-specific lines describing the blast radius
+ * @returns {string[]} Headline + detail lines
+ */
+function makeExtendedModeWarning(detailLines) {
+  return [
+    '⚠️⚠️⚠️  WARNING: TEST_EXTENDED_MODE IS TRUE  ⚠️⚠️⚠️',
+    ...detailLines,
+  ];
+}
+
+module.exports = { makeExtendedModeWarning };