@omega.js/manager 0.1.0

package/dist/vendor/config/env-delivery.js

@@ -0,0 +1,145 @@
+/**
+ * The delivery renderer — every workflow secrets block, bake list and
+ * push-secrets set, derived from the env schema alone
+ * ([#627](https://github.com/Omega-JS-Stack/omega/issues/627)).
+ *
+ * HOW a key reaches its consumer used to be decided in three unrelated places:
+ * the web target scanned the resolved .env to render its workflow block, the
+ * extension and desktop workflows carried hand-written `${{ secrets.KEY }}`
+ * lists, and each build's bake was hand-coded per framework. Three systems for
+ * one concern. The schema's `delivery` field is now the single declaration
+ * (see env-schema.js's header for the three modes) and this module is its ONE
+ * reader — no framework keeps a list.
+ *
+ * Two rules ride on every list here:
+ *
+ *   - `deliverAs` is honored: the DELIVERED name is what a runner and an
+ *     artifact ever see (the brand's `GOOGLE_ANALYTICS_SECRET_WEB` is
+ *     `GOOGLE_ANALYTICS_SECRET` in CI), so a repo secret is named for what
+ *     reads it, not for the brand-level slot it came from.
+ *   - `machineLocal` keys never leave the developer's machine
+ *     ([#454](https://github.com/Omega-JS-Stack/omega/issues/454)), so they
+ *     drop out of every rendered and published set.
+ *
+ * Pattern families (`match`, no `name`) carry a delivery like anything else,
+ * but have no fixed name to render, so nothing here can list them.
+ *
+ * Every function takes an optional `schema` so a caller — the tests — can
+ * exercise the rules against a fixture; the default is the real one.
+ */
+
+const { ENV_SCHEMA } = require('./env-schema.js');
+
+// Keys a generated workflow's own `env:` block already declares. The generated
+// block never restates one (a repeated YAML mapping key is invalid) — they are
+// still PUBLISHED, they just aren't re-rendered.
+const WORKFLOW_OWNED_KEYS = ['GH_TOKEN', 'CLOUDFLARE_TOKEN', 'NODE_VERSION', 'NODE_ENV'];
+
+// Rendered in place of the block when a target delivers nothing, so the
+// generated region is always a valid, self-explaining line of YAML.
+const EMPTY_BLOCK = '# (no CI-delivered keys for this target — the next omega verb regenerates this block)';
+
+/**
+ * The delivered names a target receives in the given modes, sorted and
+ * deduplicated.
+ *
+ * The publicAtRest gate lives here, so EVERY lane that walks a baking entry
+ * refuses it: a `secret: true` key with no `publicAtRest` declaration can
+ * never reach a shipped artifact, not through a bake list and not through the
+ * workflow injection its bake implies.
+ *
+ * @param {string} target - Target name ('web', 'backend', 'desktop', …).
+ * @param {string[]} modes - The delivery modes to collect.
+ * @param {object[]} schema - Env schema entries.
+ * @returns {string[]} Delivered env var names.
+ */
+function deliveredNames(target, modes, schema) {
+  const names = new Set();
+
+  for (const entry of schema) {
+    const mode = entry.delivery && entry.delivery[target];
+    if (!mode) continue;
+
+    if (mode === 'bake' && entry.secret && !entry.publicAtRest) {
+      throw new Error(`${entry.name || entry.match}: bakes into the ${target} artifact but declares no publicAtRest — a secret can never ride a shipped build`);
+    }
+
+    if (!modes.includes(mode)) continue;
+    if (!entry.name) continue;
+    if (entry.machineLocal) continue;
+
+    names.add(entry.deliverAs || entry.name);
+  }
+
+  return [...names].sort();
+}
+
+/**
+ * The keys a target's generated workflow needs in the runner env: every `ci`
+ * delivery, plus every `bake` (a bake is injected before it is baked).
+ *
+ * @param {string} target - Target name.
+ * @param {object} [options]
+ * @param {object[]} [options.schema] - Env schema entries (default: the real schema).
+ * @returns {string[]} Delivered env var names, sorted.
+ */
+function workflowSecretKeys(target, { schema = ENV_SCHEMA } = {}) {
+  return deliveredNames(target, ['ci', 'bake'], schema);
+}
+
+/**
+ * The keys a target's build writes INTO its shipped artifact — what a packaged
+ * app carries because it runs with no .env. Every one is public at rest.
+ *
+ * @param {string} target - Target name.
+ * @param {object} [options]
+ * @param {object[]} [options.schema] - Env schema entries.
+ * @returns {string[]} Delivered env var names, sorted.
+ */
+function bakeKeys(target, { schema = ENV_SCHEMA } = {}) {
+  return deliveredNames(target, ['bake'], schema);
+}
+
+/**
+ * The repo Actions secrets a push-secrets publisher sends for a target: the
+ * same set the workflow consumes (a secret CI never reads has no business in
+ * the repo, and a key the workflow injects must exist as one). Workflow-owned
+ * names are included — the template's `${{ secrets.GH_TOKEN }}` needs the
+ * secret to exist even though the generated block never restates it.
+ *
+ * @param {string} target - Target name.
+ * @param {object} [options]
+ * @param {object[]} [options.schema] - Env schema entries.
+ * @returns {string[]} Delivered env var names, sorted.
+ */
+function publishSecretKeys(target, options) {
+  return workflowSecretKeys(target, options);
+}
+
+/**
+ * Render a workflow's generated env block: one `KEY: ${{ secrets.KEY }}` line
+ * per CI-delivered key, sorted (a deterministic block re-renders
+ * byte-identical, so a scaffold's idempotency check reports no write). Lines
+ * join at `indent`; the template's token supplies the first line's.
+ *
+ * @param {string} target - Target name.
+ * @param {object} [options]
+ * @param {object[]} [options.schema] - Env schema entries.
+ * @param {string} [options.indent] - The token's indent (default two spaces).
+ * @returns {string} The block body (no leading indent).
+ */
+function renderSecretsBlock(target, { schema = ENV_SCHEMA, indent = '  ' } = {}) {
+  const lines = workflowSecretKeys(target, { schema })
+    .filter((key) => !WORKFLOW_OWNED_KEYS.includes(key))
+    .map((key) => `${key}: \${{ secrets.${key} }}`);
+
+  return lines.length ? lines.join(`\n${indent}`) : EMPTY_BLOCK;
+}
+
+module.exports = {
+  WORKFLOW_OWNED_KEYS,
+  workflowSecretKeys,
+  bakeKeys,
+  publishSecretKeys,
+  renderSecretsBlock,
+};

package/dist/vendor/config/env-rules.js

@@ -0,0 +1,93 @@
+/**
+ * The env presence checker — the ONE evaluator of the schema's `required` and
+ * `requiredWhen` rules
+ * ([#626](https://github.com/Omega-JS-Stack/omega/issues/626)).
+ *
+ * Every such rule used to be a hand-written if in whatever target noticed it
+ * first: the extension's build threw when a GA4 id had no Measurement Protocol
+ * secret, the manager's captcha service paired site key and secret on its own.
+ * Each was one more place to drift, and each protected one target only. The
+ * schema declares the rule once (env-schema.js) and this checker answers it
+ * for its three real consumers:
+ *
+ *   - the backend's boot reader (@omega.js/backend, libraries/env.js
+ *     `assertRules`) — production refuses, everything else warns;
+ *   - the two BAKE lanes, where a missing key would be frozen into a shipped
+ *     artifact: the extension's build.json bake (gulp/tasks/package.js) and the
+ *     desktop's bundle `define` bake (gulp/tasks/bundle.js), both
+ *     refusing in build/publish mode and warning in development. Web has NO
+ *     bake seam — a site reads its values at request time, so there is nothing
+ *     to freeze and nothing to check;
+ *   - the manager's manage-time workspace op
+ *     (services/workspace/ensure/env-rules.js), evaluated per ENABLED target
+ *     against that target's resolved config — the earliest a human hears about
+ *     any of it, and a warning every time.
+ *
+ * PRESENCE ONLY, never a value shape (Ian 2026-08-26): a rule fires when the
+ * key is empty, never because a value "looks wrong". `requiredWhen` is
+ * one-directional — a truthy config path makes the key mandatory; an empty key
+ * never says anything about the config.
+ *
+ * The checker NEVER throws and never logs. It returns the violations and the
+ * caller decides the severity (build mode and production boot fail loudly,
+ * development warns and continues).
+ */
+
+const { ENV_SCHEMA } = require('./env-schema.js');
+const { getPath } = require('./validate.js');
+
+/**
+ * Whether a key has a value in the given env map, under its own name or the
+ * name it is DELIVERED under (a target's build holds
+ * `GOOGLE_ANALYTICS_SECRET`, never the brand-level
+ * `GOOGLE_ANALYTICS_SECRET_WEB` it came from). An empty string is absent —
+ * the same rule the .env cascade applies.
+ *
+ * @param {object} env - Env var map (process.env, a composed target env, …).
+ * @param {object} entry - The schema entry.
+ * @returns {boolean}
+ */
+function hasValue(env, entry) {
+  if (env[entry.name]) return true;
+
+  return Boolean(entry.deliverAs && env[entry.deliverAs]);
+}
+
+/**
+ * Check a resolved config + env pair against the schema's presence rules.
+ *
+ * Pass the caller's `target` and only the entries that name it are evaluated —
+ * a web build never owes the desktop's Snap credentials. Without one, every
+ * entry is checked, which is the manager's brand-wide view.
+ *
+ * @param {object} config - The resolved omega.json5 config.
+ * @param {object} env - Env var map (process.env, a composed target env, …).
+ * @param {object} [options]
+ * @param {string} [options.target] - Target name ('web', 'backend', …).
+ * @param {object[]} [options.schema] - Env schema entries (default: the real schema).
+ * @returns {Array<{ key: string, rule: 'required'|'requiredWhen', path: string|null }>}
+ *   One violation per empty key that owes a value; `path` is the config path
+ *   that made it mandatory, null for an unconditional `required`.
+ */
+function checkEnvRules(config, env, { target, schema = ENV_SCHEMA } = {}) {
+  const values = env || {};
+  const violations = [];
+
+  for (const entry of schema) {
+    // A pattern family has no fixed name, so nothing can be owed under it
+    if (!entry.name) continue;
+    if (target && !entry.targets.includes(target)) continue;
+    if (!entry.required && !entry.requiredWhen) continue;
+    if (hasValue(values, entry)) continue;
+
+    if (entry.required) {
+      violations.push({ key: entry.name, rule: 'required', path: null });
+    } else if (getPath(config, entry.requiredWhen)) {
+      violations.push({ key: entry.name, rule: 'requiredWhen', path: entry.requiredWhen });
+    }
+  }
+
+  return violations;
+}
+
+module.exports = { checkEnvRules };