@omega.js/extension 0.1.0

package/dist/vendor/config/index.js

@@ -0,0 +1,237 @@
+/**
+ * @omega.js/config — the single config format for every OMEGA project type.
+ *
+ * One file, config/omega.json5 (functions/config/omega.json5 for standalone
+ * backends), identical shape everywhere: shared sections (brand,
+ * cloud, analytics, payment, monitoring, connections, theme) + a `targets`
+ * object whose KEY PRESENCE says which targets a brand enables and whose
+ * values hold target-scoped settings — any shared key inside a target entry
+ * overrides the shared value for that surface (one agnostic deep merge).
+ *
+ * Replaces the per-framework config zoo (UJM's _config.yml + JSON split,
+ * EM's config/electron-manager.json, @omega.js/backend's backend-manager-config.json,
+ * BXM's config) with NO dual-read: each framework flips to omega.json5
+ * outright and legacy brands migrate their file once (docs/shared/config.md has
+ * the mapping tables). omega-manager's disperse enumerates SHARED_SECTIONS
+ * instead of hardcoding per-target mapping blocks.
+ *
+ * Private workspace package — vendored/bundled into the published frameworks
+ * at prepare time, never published on its own.
+ */
+
+const { TARGETS, CUSTOM_TARGET_TYPE, isCustomTargetEntry, BACKEND_PROJECT_TYPES, backendProjectType, SHARED_SECTIONS, SHARED_SCHEMA, TARGET_SCHEMAS, BRAND_ID_PATTERN } = require('./schema.js');
+const { deepMerge } = require('./merge.js');
+const { findSecretKeys, SECRET_KEY_PATTERN } = require('./secrets.js');
+const { findRetiredKeys, RETIRED_KEYS, RETIRED_PATHS } = require('./retired-keys.js');
+const { chosenProvider } = require('./providers.js');
+const { validateConfig, runSchema, formatErrors, resolvedBrandHost } = require('./validate.js');
+const { loadConfig, composeTargetConfig, hasOmegaConfig, resolveConfigPath, getEnabledTargets, findBrandRoot, findBrandConfigPath, resolveBrandRoot, FILE_NAME, CONFIG_LOCATIONS } = require('./load.js');
+const { loadEnv, reloadEnv, ENV_ENVIRONMENTS, envEnvironment, resolveEnvChain, envLayerFiles, loadEnvChain, loadEnvRoots, applyDeliverAs, composeTargetEnv, envLine, serializeEnv } = require('./env.js');
+const { ENV_SCHEMA, ENV_GROUPS, DELIVERY_MODES, envFileGroups, envSchemaEntry, envKeysForTarget, generatedEnvKeys, requiredEnvKeys, envKeysByGroup } = require('./env-schema.js');
+const { WORKFLOW_OWNED_KEYS, workflowSecretKeys, bakeKeys, publishSecretKeys, renderSecretsBlock } = require('./env-delivery.js');
+const { checkEnvRules } = require('./env-rules.js');
+const { readCompanyRoot, COMPANY_MARKER } = require('./company.js');
+const { applyConfigEdits, writeConfigValues, applyConfigRemovals, removeConfigValues } = require('./edit.js');
+const { schemaDefaults, missingDefaults, defaultComments } = require('./defaults.js');
+const { applyCanonicalOrder, CANONICAL_TOP_LEVEL_ORDER } = require('./order.js');
+const { resolveSeedMode } = require('./seed.js');
+const { resolveHook, loadHook } = require('./hooks.js');
+const { toSiteGlobal } = require('./site-global.js');
+const { DESKTOP_ARTIFACTS, desktopProductName, sanitizeProductName, desktopArtifactName, desktopArtifactNames } = require('./desktop-artifacts.js');
+const { resolveWinbackOffer, WINBACK_OFFER_DEFAULTS, WINBACK_DURATIONS } = require('./winback.js');
+const { parseRepoSlug, brandRepoName, brandRepoOwner, brandRepo, releasesRepo } = require('./repo.js');
+const { isDemoProject } = require('./demo.js');
+const { CLASSIC_PORTS, CLASSIC_DEV_ORIGIN, isPortFree, resolvePorts, writePortsFile, readPortsFile, clearPortsFile, readSiblingPorts, readSiblingOrigin, envName, portsToEnv, envPort, envPorts } = require('./ports.js');
+const { DIR_TARGETS, TARGET_DIRS, MAIN_INSTANCE, INSTANCE_ID_PATTERN, normalizeTargetInstances, instanceIdFromDirName, instanceTargetDir, targetInstance, resolveInstanceEntry, instancePortOffset, resolveInstanceUrl } = require('./instances.js');
+
+module.exports = {
+  // Loading
+  loadConfig,
+  composeTargetConfig,
+  hasOmegaConfig,
+  resolveConfigPath,
+  getEnabledTargets,
+  findBrandRoot,
+  findBrandConfigPath,
+  resolveBrandRoot,
+  FILE_NAME,
+  CONFIG_LOCATIONS,
+
+  // .env cascade (shell > local .env > brand .env > company .env), each layer
+  // overlaid by its own `.env.<environment>` file (#586)
+  loadEnv,
+  // The reload half: drops what a file layer owns, then loads again, so an
+  // EDITED value lands and the shell still wins (#724)
+  reloadEnv,
+  resolveEnvChain,
+  envLayerFiles,
+  loadEnvChain,
+  loadEnvRoots,
+
+  // The ONE environment vocabulary ('development' | 'testing' | 'production') —
+  // the overlay's file suffix and every framework's own environment answer
+  ENV_ENVIRONMENTS,
+  envEnvironment,
+
+  // The schema's `deliverAs` rename (#678) — the ONE place a brand-level name
+  // becomes the name a target's runtime reads
+  applyDeliverAs,
+
+  // The dist/.env composition (#678) — FILES only (company ← brand ← target),
+  // schema-filtered per target, written by every verb that stages an artifact
+  composeTargetEnv,
+
+  // The .env serializer SSOT — every writeback renders through these
+  envLine,
+  serializeEnv,
+
+  // The env schema (#581) — the ONE inventory of the keys OMEGA needs: the
+  // manager's mint and order lanes, every verb's target delivery, and the
+  // backend's env reader all derive from it, so a new key is one entry
+  ENV_SCHEMA,
+  ENV_GROUPS,
+  DELIVERY_MODES,
+  envFileGroups,
+  envSchemaEntry,
+  envKeysForTarget,
+  generatedEnvKeys,
+  requiredEnvKeys,
+  envKeysByGroup,
+
+  // The delivery renderer (#627) — the ONE derivation of how a declared key
+  // reaches each target: the generated workflow's secrets block, the build's
+  // bake list, and the set a push-secrets publisher sends. No framework keeps
+  // a hand-written list, and a secret can never bake into an artifact
+  WORKFLOW_OWNED_KEYS,
+  workflowSecretKeys,
+  bakeKeys,
+  publishSecretKeys,
+  renderSecretsBlock,
+
+  // The env presence checker (#626) — the ONE evaluator of `required` and
+  // `requiredWhen`; every consumer calls it, none keeps its own if
+  checkEnvRules,
+
+  // Company layer discovery (the .omega/company.json stamp) — shared by the
+  // config chain, the .env chain, and owner hooks
+  readCompanyRoot,
+  COMPANY_MARKER,
+
+  // Writeback (comment-preserving edits + canonical top-level key order)
+  applyConfigEdits,
+  writeConfigValues,
+  applyConfigRemovals,
+  removeConfigValues,
+  applyCanonicalOrder,
+  CANONICAL_TOP_LEVEL_ORDER,
+
+  // Schema-derived defaults (#478) — the merge chain's lowest layer, and the
+  // heal list the manage walk materializes into a brand's omega.json5
+  schemaDefaults,
+  missingDefaults,
+  defaultComments,
+
+  // Layer-aware consumer seeding (brand target = no local-layer config at all)
+  resolveSeedMode,
+
+  // Owner hooks (config/hooks/<call-site>.js — brand root, then company root)
+  resolveHook,
+  loadHook,
+
+  // Template surface
+  toSiteGlobal,
+
+  // The desktop release assets' versionless names (#620) — @omega.js/desktop
+  // packages under them, the site links straight at them
+  DESKTOP_ARTIFACTS,
+  desktopProductName,
+  sanitizeProductName,
+  desktopArtifactName,
+  desktopArtifactNames,
+
+  // The cancel-flow save offer (#268) — ONE home for the 50%-off default, read
+  // by the backend's apply route and baked into the web client blob at build
+  resolveWinbackOffer,
+  WINBACK_OFFER_DEFAULTS,
+  WINBACK_DURATIONS,
+
+  // Brand repo derivation from the shared repo.providers.github block, overlaid
+  // by a target's own github entry (backend: targets.backend.github.repo slug —
+  // "owner/name" or bare name; name → `<brand.id>-omega`, owner → repo.providers.github.org)
+  parseRepoSlug,
+  // demo-* project ids are emulator-only (Firebase's convention) — cloud
+  // surfaces short-circuit on this instead of 403ing at Google
+  isDemoProject,
+  brandRepoName,
+  brandRepoOwner,
+  // The finished form a framework hands to consumer code (#290) — owner, name,
+  // and the "owner/name" slug — so brands never re-derive the rule
+  brandRepo,
+  // The brand's ONE public releases repo (#799): `<brand.id>-releases` under the
+  // brand repo's owner unless `targets.desktop.releases` names its own, the one
+  // home every release reader takes its address from
+  releasesRepo,
+
+  // Validation
+  validateConfig,
+  runSchema,
+  formatErrors,
+
+  // The brand's own HOST, resolved from an instance `url` or `brand.url` — the
+  // ONE derivation of it ([#708](https://github.com/Omega-JS-Stack/omega/issues/708)):
+  // authDomain validation, and every lane that composes a test persona's email
+  resolvedBrandHost,
+
+  findSecretKeys,
+  SECRET_KEY_PATTERN,
+  findRetiredKeys,
+  RETIRED_KEYS,
+  RETIRED_PATHS,
+
+  // The one provider shape (#425) — `role.providers.<provider>`, where key
+  // presence is the pick and `false` is the deliberate off switch
+  chosenProvider,
+
+  // Merge
+  deepMerge,
+
+  // Port auto-allocation (N7 — dev/emulator only)
+  CLASSIC_PORTS,
+  CLASSIC_DEV_ORIGIN,
+  isPortFree,
+  resolvePorts,
+  writePortsFile,
+  readPortsFile,
+  clearPortsFile,
+  readSiblingPorts,
+  readSiblingOrigin,
+  envName,
+  portsToEnv,
+  envPort,
+  envPorts,
+
+  // Multi-instance targets (_attic/plans/multi-instance-targets.md): normalization
+  // is the ONE iteration mechanism — object form = [{ id: 'main', ...entry }]
+  DIR_TARGETS,
+  TARGET_DIRS,
+  MAIN_INSTANCE,
+  INSTANCE_ID_PATTERN,
+  normalizeTargetInstances,
+  instanceIdFromDirName,
+  instanceTargetDir,
+  targetInstance,
+  resolveInstanceEntry,
+  instancePortOffset,
+  resolveInstanceUrl,
+
+  // Schema (pure data)
+  TARGETS,
+  CUSTOM_TARGET_TYPE,
+  isCustomTargetEntry,
+  BACKEND_PROJECT_TYPES,
+  backendProjectType,
+  SHARED_SECTIONS,
+  SHARED_SCHEMA,
+  TARGET_SCHEMAS,
+  BRAND_ID_PATTERN,
+};

package/dist/vendor/config/instances.js

@@ -0,0 +1,208 @@
+/**
+ * Multi-instance targets — the normalization trick and the target-dir mapping
+ * (_attic/plans/multi-instance-targets.md, shape ratified by Ian 2026-07-20).
+ *
+ * `targets.<type>` may be an object (today's single-instance shape) or an
+ * ARRAY of id'd instance entries. Normalization is the whole mechanism: a
+ * single object normalizes to `[{ id: 'main', ...entry }]` internally, so
+ * every consumer of target config iterates instances and the single-instance
+ * world is just length 1 — zero breaking change for existing brands.
+ *
+ * Target-dir mapping: the `main` instance (or the single-object form) lives in
+ * `targets/<canonical dir>` (targets/website, unchanged); any other id lives in
+ * `targets/<canonical dir>-<id>` (targets/website-admin). The inverse walk resolves
+ * WHICH instance a target dir is, and loadConfig/composeTargetConfig use it to
+ * pick the instance entry as the target layer of the merge chain.
+ *
+ * This module is the ONE home for the instance iteration mechanism (mirrored-
+ * implementation rule) — frameworks and the manager import it, never copy it.
+ * The canonical dir names moved here from the manager's config.js so the
+ * mapping and its inverse walk share a single SSOT.
+ */
+
+const path = require('node:path');
+
+const { isPlainObject } = require('./merge.js');
+
+// targets/<dir> → target mapping when the target dir doesn't declare its target
+// in its own omega.json5. Exact match or `<name>-<id>` suffix (targets/website-admin →
+// web, instance admin). Moved here from @omega.js/manager's config.js (which
+// re-exports it) so the target-dir walk has one home.
+const DIR_TARGETS = {
+  website: 'web',
+  backend: 'backend',
+  desktop: 'desktop',
+  extension: 'extension',
+  mobile: 'mobile',
+};
+
+// Inverse: canonical target dir per target (targets/website for web, …)
+const TARGET_DIRS = Object.fromEntries(
+  Object.entries(DIR_TARGETS).map(([dir, target]) => [target, dir]),
+);
+
+// The conventional primary instance id — the single-object form normalizes
+// to it, and it maps to the canonical (un-suffixed) target dir.
+const MAIN_INSTANCE = 'main';
+
+// Instance ids are target-dir suffixes, so they must be dir-safe slugs
+const INSTANCE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Normalize a `targets.<type>` entry to the instances array. The whole trick:
+ * a single object becomes `[{ id: 'main', ...entry }]` (an authored `id`
+ * inside the object wins); an array passes through as-is — the validator, not
+ * this function, enforces that array entries carry ids.
+ * @param {object|Array|null|undefined} entry - The raw targets.<type> value.
+ * @returns {Array<object>} Instance entries (shallow copies); [] when absent.
+ */
+function normalizeTargetInstances(entry) {
+  if (entry === undefined || entry === null) return [];
+  if (Array.isArray(entry)) return entry.map((instance) => (isPlainObject(instance) ? { ...instance } : instance));
+  return [{ id: MAIN_INSTANCE, ...entry }];
+}
+
+/**
+ * Target dir name → instance id for a target. The inverse walk of the mapping:
+ * the canonical dir (targets/website) is `main`; a `<canonical>-<id>` suffix
+ * names the instance (targets/website-admin → admin). Unconventional dir names
+ * resolve to `main` — today's behavior for dirs like targets/api.
+ * @param {string} dirName - The target directory basename.
+ * @param {string} target - Canonical target name ('web', 'backend', ...).
+ * @returns {string} The instance id.
+ */
+function instanceIdFromDirName(dirName, target) {
+  const canonical = TARGET_DIRS[target] || target;
+  if (dirName.startsWith(`${canonical}-`)) {
+    return dirName.slice(canonical.length + 1);
+  }
+  return MAIN_INSTANCE;
+}
+
+/**
+ * Instance id → its target dir name (`main` → the canonical dir, anything else
+ * → `<canonical>-<id>`).
+ * @param {string} target - Canonical target name.
+ * @param {string} id - Instance id.
+ * @returns {string} The target directory basename.
+ */
+function instanceTargetDir(target, id) {
+  const canonical = TARGET_DIRS[target] || target;
+  return id === MAIN_INSTANCE ? canonical : `${canonical}-${id}`;
+}
+
+/**
+ * Resolve THIS project dir's instance id for a target: TARGET_SUBDIR dirs
+ * (functions/, dist/) normalize up to their target root, and only targets inside a
+ * brand monorepo resolve through the dir-name walk — a standalone project
+ * (whose dir name is arbitrary) is always `main`.
+ * @param {string} projectDir - Target root (or one of its TARGET_SUBDIRS).
+ * @param {string} target - Canonical target name.
+ * @returns {string} The instance id.
+ */
+function targetInstance(projectDir, target) {
+  // Local require to avoid a load-time cycle (load.js requires this module)
+  const { findBrandRoot, TARGET_SUBDIRS } = require('./load.js');
+
+  let targetRoot = path.resolve(projectDir);
+  if (TARGET_SUBDIRS.includes(path.basename(targetRoot))) {
+    targetRoot = path.dirname(targetRoot);
+  }
+
+  if (!findBrandRoot(targetRoot)) return MAIN_INSTANCE;
+  return instanceIdFromDirName(path.basename(targetRoot), target);
+}
+
+/**
+ * The merge-chain layer for one instance: the single-object form applies to
+ * EVERY target dir of the type (today's semantics, unchanged); the array form
+ * applies only to the exact-id match — no match means no instance layer
+ * (shared config alone). The `id` key is bookkeeping, never config — it is
+ * stripped from the returned entry.
+ * @param {object|Array|null|undefined} entry - The raw targets.<type> value.
+ * @param {string} instanceId - The instance to resolve.
+ * @returns {object|null} The instance's merge layer, or null.
+ */
+function resolveInstanceEntry(entry, instanceId) {
+  if (entry === undefined || entry === null) return null;
+  if (!Array.isArray(entry)) return entry;
+
+  const hit = entry.find((instance) => isPlainObject(instance) && instance.id === instanceId);
+  if (!hit) return null;
+
+  const { id, ...rest } = hit;
+  return rest;
+}
+
+/**
+ * Deterministic dev-port offset for an instance: its position in the
+ * normalized instances array (main-or-object form = 0), so N instances get N
+ * side-by-side ports off the same classic base. Unknown ids offset 0 — the
+ * N7 bump-if-taken allocator still guarantees a free port.
+ * @param {object|Array|null|undefined} entry - The raw targets.<type> value.
+ * @param {string} instanceId - The instance id.
+ * @returns {number} Zero-based offset.
+ */
+function instancePortOffset(entry, instanceId) {
+  const index = normalizeTargetInstances(entry).findIndex((instance) => isPlainObject(instance) && instance.id === instanceId);
+  return index > 0 ? index : 0;
+}
+
+/**
+ * The host `brand.url` names, EXACTLY as it states it: a `www.` label is kept
+ * (a www brand is a www brand), any path is dropped, a port survives. A
+ * scheme-less value is read as https.
+ * @param {string} url - A brand URL.
+ * @returns {string} The host, or '' when the value is not a URL.
+ */
+function brandHost(url) {
+  try {
+    return new URL(url.includes('://') ? url : `https://${url}`).host;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The live URL of an instance: its entry's `url` (the spec's per-instance
+ * key), an instance-scoped `brand.url` override, then, for every id but
+ * `main`, the id AS A SUBDOMAIN of the brand host (#588), and the
+ * brand-shared brand.url for `main`. The manager's per-instance live checks,
+ * the resolved config's top-level `url` and site-global all read this.
+ *
+ * The id-is-the-subdomain default is what makes `web: [{ id: 'main' },
+ * { id: 'admin' }]` a complete declaration; an explicit `url` overrides it for
+ * a custom host (`{ id: 'store', url: 'https://shop.acme.com' }`). Nothing is
+ * half-derived: no usable brand.url means null for every id, never
+ * `https://admin.`.
+ * @param {object|Array|null|undefined} entry - The raw targets.<type> value.
+ * @param {string} instanceId - The instance id.
+ * @param {object} config - The (resolved) config carrying brand.url.
+ * @returns {string|null} The instance's URL, or null when none is known.
+ */
+function resolveInstanceUrl(entry, instanceId, config) {
+  const instance = resolveInstanceEntry(entry, instanceId);
+  if (instance?.url) return instance.url;
+  if (instance?.brand?.url) return instance.brand.url;
+
+  const brandUrl = config?.brand?.url;
+  if (!brandUrl) return null;
+  if (instanceId === MAIN_INSTANCE) return brandUrl;
+
+  const host = brandHost(brandUrl);
+  return host ? `https://${instanceId}.${host}` : null;
+}
+
+module.exports = {
+  DIR_TARGETS,
+  TARGET_DIRS,
+  MAIN_INSTANCE,
+  INSTANCE_ID_PATTERN,
+  normalizeTargetInstances,
+  instanceIdFromDirName,
+  instanceTargetDir,
+  targetInstance,
+  resolveInstanceEntry,
+  instancePortOffset,
+  resolveInstanceUrl,
+};