@omega.js/backend 0.1.0

package/dist/vendor/devkit/deploy.js

@@ -0,0 +1,286 @@
+/**
+ * Deploy executor — the ONE dispatch path for deliberate deploys (D13/D9).
+ *
+ * Commits never auto-publish: scaffolded workflows carry no push triggers, so
+ * publishing is an explicit dispatch of the SAME CI build — from the local
+ * CLI (`omega deploy`), a server-side action (the admin post route's
+ * content-publish), or any plain HTTP caller. All three converge here: a
+ * GitHub REST `workflow_dispatch` call (native fetch, no gh-CLI dependency —
+ * Cloud Functions and laptops share the code path; locally the token can
+ * still come from `gh auth token`).
+ */
+const path = require('node:path');
+const { execSync, execFileSync } = require('node:child_process');
+
+const { findBrandRoot, discoverTargets, frameworkPackagesOf } = require('./local.js');
+
+const API_BASE = 'https://api.github.com';
+
+/**
+ * Parse a git remote URL into { owner, repo }.
+ * Handles ssh (git@github.com:o/r.git), https (https://github.com/o/r.git),
+ * and .git-less forms.
+ * @param {string} url - remote URL
+ * @returns {{ owner: string, repo: string }|null}
+ */
+function parseRemoteUrl(url) {
+  const match = (url || '').trim().match(/github\.com[/:]([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2] };
+}
+
+/**
+ * The repo a CI dispatch addresses: the BRAND's own repo, from its config
+ * ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)). Every framework's
+ * deploy verb asks this instead of `resolveRepo` above, because a git remote
+ * answers the repo the working tree sits in: inside a brand monorepo nested in
+ * another repo (a brand inside the framework monorepo, a target checked out
+ * under someone else's tree) that is the ENCLOSING repo, so the dispatch went to
+ * a workflow that was never there.
+ *
+ * Half an address addresses nothing, so it throws rather than POST to
+ * `undefined/<name>`.
+ *
+ * @param {object} config - Composed omega config for the target being deployed.
+ * @returns {{ owner: string, repo: string }} the brand repo's owner and bare name
+ * @throws {Error} when the config names no repo
+ */
+function dispatchRepo(config) {
+  const { brandRepo } = require('../config/index.js');
+  const { owner, name } = brandRepo(config);
+
+  if (!owner || !name) {
+    throw new Error('Could not determine the brand repo to dispatch on. Set repo.providers.github.org (and repo.providers.github.repo when the repo name is not <brand.id>-omega) in config/omega.json5.');
+  }
+
+  return { owner, repo: name };
+}
+
+/**
+ * Resolve the GitHub repo for a working directory from its origin remote.
+ * @param {object} [options]
+ * @param {string} [options.cwd] - repo directory (default: process.cwd())
+ * @param {string} [options.remote] - remote name (default: origin)
+ * @param {function} [options.execFn] - injectable exec (tests)
+ * @returns {{ owner: string, repo: string }}
+ */
+function resolveRepo(options = {}) {
+  const execFn = options.execFn || ((cmd, opts) => execSync(cmd, opts).toString());
+  const url = execFn(`git config --get remote.${options.remote || 'origin'}.url`, {
+    cwd: options.cwd || process.cwd(),
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const parsed = parseRemoteUrl(url);
+  if (!parsed) {
+    throw new Error(`Cannot parse a GitHub repo from remote url: ${String(url).trim() || '(none)'}`);
+  }
+  return parsed;
+}
+
+/**
+ * Resolve a GitHub token: GH_TOKEN → GITHUB_TOKEN → `gh auth token`.
+ * @param {object} [options]
+ * @param {object} [options.env] - env map (default: process.env)
+ * @param {function} [options.execFn] - injectable exec (tests)
+ * @returns {string|null}
+ */
+function resolveToken(options = {}) {
+  const env = options.env || process.env;
+  if (env.GH_TOKEN) return env.GH_TOKEN;
+  if (env.GITHUB_TOKEN) return env.GITHUB_TOKEN;
+
+  const execFn = options.execFn || ((cmd, opts) => execSync(cmd, opts).toString());
+  try {
+    const token = execFn('gh auth token', { stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return token || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Build a workflow_dispatch plan — the exact REST call a deploy will make.
+ * This IS the dry-run output: everything except the send.
+ * @param {object} options
+ * @param {string} options.owner - repo owner
+ * @param {string} options.repo - repo name
+ * @param {string} options.workflow - workflow file name (e.g. build.yml)
+ * @param {string} [options.ref] - branch/tag to run on (default: main)
+ * @param {object} [options.inputs] - workflow_dispatch inputs
+ * @returns {{ method: string, url: string, body: object, runsUrl: string }}
+ */
+function buildDispatch(options) {
+  for (const key of ['owner', 'repo', 'workflow']) {
+    if (!options[key]) throw new Error(`buildDispatch: missing ${key}`);
+  }
+  const body = { ref: options.ref || 'main' };
+  if (options.inputs && Object.keys(options.inputs).length > 0) body.inputs = options.inputs;
+
+  return {
+    method: 'POST',
+    url: `${API_BASE}/repos/${options.owner}/${options.repo}/actions/workflows/${options.workflow}/dispatches`,
+    body: body,
+    runsUrl: `https://github.com/${options.owner}/${options.repo}/actions/workflows/${options.workflow}`,
+  };
+}
+
+/**
+ * Send a dispatch plan to GitHub (204 = accepted).
+ * @param {object} plan - buildDispatch() result
+ * @param {object} options
+ * @param {string} options.token - GitHub token
+ * @param {function} [options.fetchFn] - injectable fetch (tests)
+ * @returns {Promise<object>} the plan, on success
+ */
+async function dispatchWorkflow(plan, options = {}) {
+  if (!options.token) {
+    throw new Error('No GitHub token — set GH_TOKEN in .env or sign in with `gh auth login`');
+  }
+  const fetchFn = options.fetchFn || fetch;
+  const response = await fetchFn(plan.url, {
+    method: plan.method,
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${options.token}`,
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': 'omega-deploy',
+    },
+    body: JSON.stringify(plan.body),
+  });
+
+  if (response.status !== 204) {
+    const text = await response.text().catch(() => '');
+    throw new Error(`workflow_dispatch failed (${response.status}): ${text || response.statusText || 'unknown error'}`);
+  }
+  return plan;
+}
+
+/**
+ * The one deploy path: resolve repo + token, build the plan, dispatch — or
+ * return the plan untouched when dryRun is set.
+ * @param {object} options
+ * @param {string} options.workflow - workflow file name
+ * @param {string} [options.cwd] - repo dir for remote resolution
+ * @param {string} [options.owner] - explicit owner (skips git resolution)
+ * @param {string} [options.repo] - explicit repo (skips git resolution)
+ * @param {string} [options.ref] - branch (default main)
+ * @param {object} [options.inputs] - workflow inputs
+ * @param {boolean} [options.dryRun] - build the plan but never send
+ * @param {object} [options.env] - env map for token resolution
+ * @param {function} [options.fetchFn] - injectable fetch
+ * @param {function} [options.execFn] - injectable exec
+ * @returns {Promise<{ plan: object, dispatched: boolean }>}
+ */
+async function deployViaDispatch(options) {
+  const target = options.owner && options.repo
+    ? { owner: options.owner, repo: options.repo }
+    : resolveRepo({ cwd: options.cwd, execFn: options.execFn });
+
+  const plan = buildDispatch({
+    owner: target.owner,
+    repo: target.repo,
+    workflow: options.workflow,
+    ref: options.ref,
+    inputs: options.inputs,
+  });
+
+  if (options.dryRun) {
+    return { plan, dispatched: false };
+  }
+
+  const token = options.token || resolveToken({ env: options.env, execFn: options.execFn });
+  await dispatchWorkflow(plan, { token, fetchFn: options.fetchFn });
+  return { plan, dispatched: true };
+}
+
+/**
+ * Find every `file:` @omega.js spec in the brand tree. npm resolves the
+ * WHOLE workspace tree on any install, so one linked sibling target breaks a
+ * CI install even when the deploying target is clean (the cp194 lesson —
+ * linking is tree-wide, so detection is too). Deploy verbs use this to
+ * AUTO-SELECT their local-artifact lane (mirrored rule, Ian 2026-07-20:
+ * a linked brand ships the LOCAL framework — build here, ship the artifact;
+ * CI dispatch is only for registry-clean trees).
+ * @param {object} [options]
+ * @param {string} [options.dir] - Any directory inside the brand (default cwd).
+ * @returns {string[]} One line per offender: `<manifest> → <name>: <spec>`.
+ */
+function findLocalSpecs(options = {}) {
+  const brandRoot = findBrandRoot(options.dir || process.cwd());
+  const offenders = [];
+
+  for (const targetDir of discoverTargets(brandRoot)) {
+    for (const entry of frameworkPackagesOf(targetDir)) {
+      if (entry.spec.startsWith('file:')) {
+        const manifest = path.relative(brandRoot, path.join(targetDir, 'package.json')) || 'package.json';
+        offenders.push(`${manifest} → ${entry.name}: ${entry.spec}`);
+      }
+    }
+  }
+
+  return offenders;
+}
+
+/**
+ * Throw when the brand tree carries `file:` @omega.js specs — for lanes with
+ * no local-artifact fallback where dispatching would only burn a CI run.
+ * @param {object} [options]
+ * @param {string} [options.dir] - Any directory inside the brand (default cwd).
+ * @throws {Error} Listing every file:-spec'd @omega.js dependency, per target.
+ */
+function assertNoLocalSpecs(options = {}) {
+  const offenders = findLocalSpecs(options);
+  if (offenders.length > 0) {
+    throw new Error(
+      'Local file: packages are linked somewhere in this brand — CI cannot install them.\n'
+      + `  ${offenders.join('\n  ')}\n`
+      + 'Deploy from the local-artifact lane, or restore registry specs first (omega i live).'
+    );
+  }
+}
+
+/**
+ * Commit + push the working tree before a dispatch deploy (D13: the push
+ * itself triggers NOTHING — scaffolded workflows carry no push triggers).
+ * Plain git via argument arrays: universal on consumer machines and
+ * injection-safe for the message.
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Repo directory (default process.cwd()).
+ * @param {string} [options.message] - Commit message (default 'Deploy').
+ * @param {object} [options.logger] - Logger with log (silent when omitted).
+ */
+function syncWorkingTree(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const message = options.message || 'Deploy';
+
+  execFileSync('git', ['add', '-A'], { cwd, stdio: 'inherit' });
+
+  // `git diff --cached --quiet` exits 1 exactly when something is staged
+  let hasStaged = false;
+  try {
+    execFileSync('git', ['diff', '--cached', '--quiet'], { cwd, stdio: 'ignore' });
+  } catch (e) {
+    hasStaged = true;
+  }
+
+  if (hasStaged) {
+    execFileSync('git', ['commit', '-m', message], { cwd, stdio: 'inherit' });
+  } else if (options.logger) {
+    options.logger.log('Working tree clean — nothing to commit');
+  }
+
+  execFileSync('git', ['push'], { cwd, stdio: 'inherit' });
+}
+
+module.exports = {
+  parseRemoteUrl,
+  dispatchRepo,
+  resolveRepo,
+  resolveToken,
+  buildDispatch,
+  dispatchWorkflow,
+  deployViaDispatch,
+  findLocalSpecs,
+  assertNoLocalSpecs,
+  syncWorkingTree,
+};

package/dist/vendor/devkit/license.js

@@ -0,0 +1,155 @@
+/**
+ * resolveLicenseVerdict — the deploy-time license check
+ * ([#320](https://github.com/Omega-JS-Stack/omega/issues/320)).
+ *
+ * A published OMEGA install needs a license to enable the payment system and
+ * remove the omega attribution. A license is a subscription bought on
+ * omegajs.dev and the KEY is that account's API key — opaque, one per account,
+ * unlimited brands for now. The verdict is decided SERVER-side: the key plus
+ * the brand id go to the omega brand's own backend and the resolved
+ * subscription on the answer decides. No offline signing, no local shape check.
+ *
+ * This module is the "get the verdict" half only. Each target's deploy asks
+ * once and bakes the answer into that artifact; runtime never phones home, so
+ * a cancelled key holds until the next deploy (accepted, spec call 3).
+ *
+ * Honesty system, deliberately (spec call 6): plain readable code, no
+ * obfuscation and no artifact signing. The legal backing is the package license
+ * (Elastic License 2.0), whose terms forbid circumventing license-key
+ * functionality and removing notices.
+ */
+
+const { isDemoProject } = require('../config/index.js');
+const { resolveSubscription } = require('../account/index.js');
+
+// The omega brand's own api host, HARDCODED. Every other api base in OMEGA is
+// derived from a brand's `brand.url` (api.<host>) because it belongs to that
+// brand — this one is the PRODUCT's license server, the same host for every
+// brand that installs OMEGA, so config can never name it.
+const LICENSE_ENDPOINT = 'https://api.omegajs.dev/omega/user';
+
+const FETCH_TIMEOUT_MS = 30 * 1000;
+
+// The one keyless answer: payments in test mode, attribution shown.
+function keyless(reason) {
+  return { licensed: false, payments: 'gated', attribution: 'shown', reason };
+}
+
+/**
+ * Resolve what a deploy is licensed to ship.
+ *
+ * @param {object} input
+ * @param {object} input.config - The resolved omega.json5 (brand.id, cloud.config.projectId).
+ * @param {object} [input.env] - The environment holding OMEGA_LICENSE_KEY (default: process.env).
+ * @param {function} [input.transport] - The fetch seam (default: global fetch).
+ * @returns {Promise<{ licensed: boolean, payments: 'live'|'gated', attribution: 'removed'|'shown', reason: string }>}
+ * @throws {Error} A key IS present but the server could not answer for it.
+ */
+async function resolveLicenseVerdict({ config, env = process.env, transport = fetch } = {}) {
+  const projectId = config?.cloud?.config?.projectId;
+
+  // Local dev, the test brands and every demo-* project run keyless forever
+  // (spec call 5) — the carve-out comes FIRST, so a developer with a real key
+  // in their shell still never spends a check on an emulator-only build.
+  if (isDemoProject(projectId)) {
+    return keyless(`${projectId} is a demo-* (emulator-only) project — no license check runs`);
+  }
+
+  const key = String(env.OMEGA_LICENSE_KEY || '').trim();
+  if (!key) {
+    return keyless('no OMEGA_LICENSE_KEY in the environment');
+  }
+
+  const url = new URL(LICENSE_ENDPOINT);
+  url.searchParams.set('apiKey', key);
+  // Sent on every check and ignored by the server today: it is what lets a
+  // future per-key brand limit be a server-side change alone (spec call 1).
+  url.searchParams.set('brandId', String(config?.brand?.id || ''));
+
+  let response;
+  try {
+    response = await transport(url.toString(), {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+  } catch (e) {
+    // LOUD: a key is present, so the brand believes it is licensed. Shipping a
+    // gated artifact because the network blinked would be the worst answer.
+    throw new Error(`OMEGA_LICENSE_KEY is set but the license server could not be reached (${LICENSE_ENDPOINT}): ${e.message}`);
+  }
+
+  if (!response.ok) {
+    throw new Error(`OMEGA_LICENSE_KEY was rejected by the license server (HTTP ${response.status}) — check the key on omegajs.dev`);
+  }
+
+  let body;
+  try {
+    body = await response.json();
+  } catch (e) {
+    throw new Error(`The license server's answer could not be read as JSON (${LICENSE_ENDPOINT}): ${e.message}`);
+  }
+
+  const user = body?.user;
+  if (!user) {
+    throw new Error(`OMEGA_LICENSE_KEY resolved no account on omegajs.dev — check the key on your account's API page`);
+  }
+
+  // The SAME derivation the backend and the client run, so "licensed" means
+  // exactly what "subscribed" means everywhere else: `basic` is the reserved
+  // free sentinel a cancelled or never-paid account resolves to.
+  const { plan } = resolveSubscription(user);
+  if (plan === 'basic') {
+    return keyless('the OMEGA_LICENSE_KEY account has no active omegajs.dev subscription');
+  }
+
+  return {
+    licensed: true,
+    payments: 'live',
+    attribution: 'removed',
+    reason: `licensed by the omegajs.dev "${plan}" subscription`,
+  };
+}
+
+/**
+ * The verdict as an ARTIFACT records it: the three decided facts under one
+ * shape, shared by every consumer — the website's `site.license` build fact,
+ * the desktop/extension build stamp, and the backend's OMEGA_LICENSE_STATUS
+ * (its `status` alone, because an env value is a string). The human `reason`
+ * is dropped: it names the account's plan, and a shipped bundle is public.
+ *
+ * @param {object} verdict - A resolveLicenseVerdict answer.
+ * @returns {{ status: 'licensed'|'keyless', payments: string, attribution: string }}
+ */
+function licenseStamp(verdict) {
+  return {
+    status: verdict.licensed ? 'licensed' : 'keyless',
+    payments: verdict.payments,
+    attribution: verdict.attribution,
+  };
+}
+
+// What a build that ran no check at all carries (a dev build, a test, any lane
+// that never asks) — the keyless verdict's own stamp, because that is exactly
+// what such a build is.
+const KEYLESS_STAMP = Object.freeze(licenseStamp(keyless('no license check ran')));
+
+/**
+ * The stamp a build bakes: a PRODUCTION build asks the license server once (a
+ * key that cannot be answered for throws, gating the deploy); everything else
+ * is keyless by definition and never phones home — spec call 5's "no check
+ * fires outside deploy" half, with ONE home for all three baking targets.
+ *
+ * @param {object} input
+ * @param {object} input.config - The resolved omega.json5.
+ * @param {boolean} input.production - Whether this build ships.
+ * @param {object} [input.env] - See resolveLicenseVerdict.
+ * @param {function} [input.transport] - See resolveLicenseVerdict.
+ * @returns {Promise<{ status: string, payments: string, attribution: string }>}
+ */
+async function resolveLicenseStamp({ config, production, env, transport }) {
+  if (!production) return { ...KEYLESS_STAMP };
+
+  return licenseStamp(await resolveLicenseVerdict({ config, env, transport }));
+}
+
+module.exports = { resolveLicenseVerdict, resolveLicenseStamp, licenseStamp, KEYLESS_STAMP, LICENSE_ENDPOINT };