@omega.js/extension 0.1.0

package/dist/vendor/devkit/cli-router.js

@@ -0,0 +1,156 @@
+// createCliRouter(config) — the shared OMEGA framework CLI dispatcher.
+//
+// Every framework bin parses argv (yargs) and hands the result to a Main class
+// whose process() resolves a command name and runs commands/<name>.js from the
+// framework's dist. That router was copy-pasted per framework (UJM/BXM/EM,
+// drift-identical); this is the single implementation. @omega.js/backend's CLI is a different
+// design (colon-style utility commands dispatching stateful command classes)
+// and does not use this.
+//
+// Resolution order (unchanged from the framework copies):
+//   1. Positional command (`mgr build`) — matched against command names and
+//      their aliases; unknown names pass through as-is (missing file = error).
+//   2. Flag-style alias (`mgr --build`, `mgr -b`) — first alias-table hit wins.
+//   3. The default command (OMEGA convention: help — `setup` is retired,
+//      #675, and every verb runs its own local scaffold).
+//
+// dotenv loading and any process-env fixups (e.g. EM's ELECTRON_RUN_AS_NODE
+// strip) stay in the framework's cli.js/bin — they're framework concerns, not
+// dispatch.
+
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+/**
+ * Build a framework CLI Main class.
+ *
+ * @param {object} config
+ * @param {string} config.commandsDir - Absolute directory of command modules — <name>.js exporting `async (options) => {}`
+ * @param {Object<string, string[]>} [config.aliases] - Command name → positional/flag aliases (e.g. `{ install: ['-i', 'i', '--install'] }`)
+ * @param {string} [config.defaultCommand='help'] - Command used when no positional or flag alias matches
+ * @returns {Function} Main class — bins do `new Main(argv)` then `await main.process(argv)`
+ */
+function createCliRouter(config) {
+  config = config || {};
+
+  const commandsDir = config.commandsDir;
+  const aliases = config.aliases || {};
+  const defaultCommand = config.defaultCommand || 'help';
+
+  if (!commandsDir) {
+    throw new Error('[devkit cli-router] commandsDir is required');
+  }
+
+  // Resolve command name from positional args or flag-style aliases
+  function resolveCommand(options) {
+    // `--help`/`-h` route to the built-in help FIRST — before positionals, so
+    // `omega deploy --help` prints help instead of RUNNING deploy, and never
+    // the default command (the old fallthrough ran setup/manage on a help
+    // request). Frameworks must disable yargs' built-in help so the flag
+    // reaches the router.
+    if (options.help || options.h) {
+      return 'help';
+    }
+
+    // Check if a command was explicitly passed via positional argument
+    if (options._.length > 0) {
+      const command = options._[0];
+      for (const [key, names] of Object.entries(aliases)) {
+        if (command === key || names.includes(command)) {
+          return key;
+        }
+      }
+      return command; // If not found in aliases, return as-is
+    }
+
+    // Check if any alias was passed as a flag (e.g., -v)
+    for (const [key, names] of Object.entries(aliases)) {
+      for (const alias of names) {
+        if (options[alias.replace(/^-+/, '')]) { // Remove leading `-`
+          return key;
+        }
+      }
+    }
+
+    return defaultCommand; // Fallback to default if no match is found
+  }
+
+  // Command names = the dispatchable surface: commands/<name>.js files.
+  function listCommands() {
+    return (jetpack.list(commandsDir) || [])
+      .filter((f) => f.endsWith('.js'))
+      .map((f) => f.replace(/\.js$/, ''))
+      .sort();
+  }
+
+  // Built-in help — generated from the alias table + the commands directory so
+  // it can never drift from what actually dispatches. A framework can override
+  // it by shipping its own commands/help.js.
+  function printHelp() {
+    const lines = listCommands().map((name) => {
+      const parts = [`  ${name}`];
+      const aliasNames = (aliases[name] || []).join(', ');
+      if (aliasNames) parts.push(`(${aliasNames})`);
+      if (name === defaultCommand) parts.push('[default]');
+      return parts.join(' ');
+    });
+    console.log(`Usage: omega <command> [options]\n\nCommands:\n${lines.join('\n')}`);
+  }
+
+  // Main Function
+  function Main() {}
+
+  // Expose the resolved dispatch table for introspection — framework structure
+  // tests verify every aliased command has a command file without scraping
+  // the cli.js source.
+  Main.config = { commandsDir, aliases, defaultCommand };
+
+  Main.prototype.process = async function (options) {
+    // Fix options
+    options = options || {};
+    options._ = options._ || [];
+
+    // Determine the command (use default if not provided)
+    const command = resolveCommand(options);
+
+    // Get the command file path
+    const commandFile = path.join(commandsDir, `${command}.js`);
+
+    if (!jetpack.exists(commandFile)) {
+      // Built-in help (a framework's own commands/help.js would have won above)
+      if (command === 'help') {
+        printHelp();
+        return;
+      }
+
+      // Unknown command: name the valid surface and fail loud — the old path
+      // threw a doubled "Error executing… Error: Command…" with no listing.
+      // An empty listing means the dist itself is broken, not a typo — say so.
+      const available = listCommands();
+      if (available.length === 0) {
+        console.error(`No commands found in ${commandsDir} — the framework dist is missing or broken (rebuild/reinstall it).`);
+      } else {
+        console.error(`Unknown command "${command}". Available: ${available.join(', ')}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    try {
+      // Execute the command
+      const Command = require(commandFile);
+      await Command(options);
+    } catch (e) {
+      // The command's own error is the only surface — no wrapper prefix, no
+      // rethrow (which double-printed via the unhandled-rejection handler).
+      // A crafted refusal (devkit scaffold-guard.js) prints its message alone:
+      // the stack belongs to a bug, and a refusal is not one (#706).
+      console.error(e && e.refusal ? e.message : (e.stack || String(e)));
+      process.exitCode = 1;
+    }
+  };
+
+  return Main;
+}
+
+module.exports = { createCliRouter };

package/dist/vendor/devkit/defaults-engine.js

@@ -0,0 +1,372 @@
+// applyDefaults(config) — the shared OMEGA defaults-scaffolding engine.
+//
+// Every framework ships a defaults tree (src/defaults/ → dist/defaults/) that
+// setup copies into the consumer project. The copy rules lived as two divergent
+// implementations (BXM's gulp FILE_MAP task — the real one — and EM's plain-fs
+// copyDefaults; UJM carries a third copy of the BXM shape). This is the single
+// plain-fs engine, a normalized superset of both.
+//
+// File-map rules: minimatch patterns (dot:true) matched against the RAW path
+// relative to defaultsDir, last-match-wins option merging. Per-rule options:
+//   overwrite  bool|fn(item)  default true — write even if the destination exists
+//   skip       bool|fn(item)  default false — never process this file
+//   name       fn(item)       rename the output file
+//   path       fn(item)       re-destination the output (relative dir)
+//   template   object         render `{{ key.path }}` tokens with this data
+//                             (tolerant: unknown keys survive verbatim, so GitHub
+//                             Actions' `${{ secrets.X }}` passes through)
+//   merge      bool           JSON5 defaults-merge with the existing file
+//   mergeLines bool           OMEGA marker-section line merge (.env/.gitignore/AGENTS.md)
+//   retire     bool           brand-context per-target doc retirement: NEVER scaffold
+//                             the file; an existing framework-owned-only copy is
+//                             DELETED (one-time heal — the brand root is the doc
+//                             home), a copy carrying consumer content stays with a
+//                             loud move-it warning (never destroyed)
+//
+// Engine built-ins (not expressed in the file map):
+//   - `_.name` segments lose the leading `_` (dotfiles ship past npm's filter)
+//   - non-final segments starting `_` (but not `_.`) are ARCHIVE dirs — skipped
+//     (reference material that ships in the framework package, e.g. EM's `_mas/`)
+//   - `.gitkeep` creates the destination directory, the file itself never copies
+//   - `.DS_Store` never copies
+//   - text writes are skipped when the destination is byte-identical (idempotent
+//     re-runs report zero writes)
+//   - a destination carrying the OMEGA section markers when the current template
+//     no longer does is a PRIOR-GENERATION generated file: framework-owned, so
+//     `retire` sweeps it and `overwrite: false` still heals it
+//   - binary files (by extension) copy verbatim — never templated/merged/transformed
+
+const path = require('path');
+const fs = require('fs');
+const jetpack = require('fs-jetpack');
+const { minimatch } = require('minimatch');
+const { mergeLineBasedFiles, hasSectionMarkers, getCustomSection } = require('./merge-line-files');
+
+// Files with these extensions copy byte-for-byte and never go through
+// template/merge/transform (matches BXM's binary detection list).
+const BINARY_EXTENSIONS = /\.(jpg|jpeg|png|gif|webp|svg|ico|woff|woff2|ttf|otf|eot|pdf|zip|tar|gz|mp3|mp4|avi|mov)$/i;
+
+const RULE_DEFAULTS = {
+  overwrite: true,
+  skip: false,
+  name: null,
+  path: null,
+  template: null,
+  merge: false,
+  mergeLines: false,
+  retire: false,
+  rule: null,
+};
+
+/**
+ * Scaffold a framework defaults tree into a consumer project.
+ *
+ * @param {object} config
+ * @param {string} config.defaultsDir - Absolute root of the defaults tree (e.g. <framework>/dist/defaults)
+ * @param {string} config.outputDir - Absolute consumer project root to scaffold into
+ * @param {Object<string, object>} [config.fileMap] - minimatch pattern → rule options (see header)
+ * @param {string[]} [config.files] - Only process these absolute source paths (watch single-file mode)
+ * @param {Function} [config.transform] - `(contents, item) => contents` global hook, run on every
+ *   non-binary file after per-rule processing (BXM's site-token templating pass)
+ * @param {object} [config.logger] - `{ log, warn, error }` (defaults to console)
+ * @returns {{ written: string[], merged: string[], skipped: string[], removed: string[] }} destination-relative paths per outcome
+ */
+function applyDefaults(config) {
+  config = config || {};
+
+  const defaultsDir = config.defaultsDir;
+  const outputDir = config.outputDir;
+  const fileMap = config.fileMap || {};
+  const only = config.files ? config.files.map((f) => path.resolve(f)) : null;
+  const transform = config.transform || null;
+  const logger = config.logger || console;
+
+  if (!defaultsDir || !outputDir) {
+    throw new Error('[devkit defaults-engine] defaultsDir and outputDir are required');
+  }
+  if (!jetpack.exists(defaultsDir)) {
+    throw new Error(`[devkit defaults-engine] defaultsDir does not exist: ${defaultsDir}`);
+  }
+
+  const result = { written: [], merged: [], skipped: [], removed: [] };
+
+  for (const source of walkFiles(defaultsDir)) {
+    if (only && !only.includes(source)) {
+      continue;
+    }
+
+    const relative = path.relative(defaultsDir, source).split(path.sep).join('/');
+    const segments = relative.split('/');
+    const basename = segments[segments.length - 1];
+
+    // Archive dirs: any non-final `_x` segment (but `_.x` files are renames, not archives).
+    const dirSegments = segments.slice(0, -1);
+    if (dirSegments.some((s) => s.startsWith('_') && !s.startsWith('_.'))) {
+      continue;
+    }
+
+    if (basename === '.DS_Store') {
+      continue;
+    }
+
+    // `.gitkeep` → ensure the directory exists, never copy the file itself.
+    if (basename === '.gitkeep') {
+      jetpack.dir(path.join(outputDir, ...strippedSegments(segments).slice(0, -1)));
+      continue;
+    }
+
+    const options = resolveOptions(relative, fileMap);
+
+    // Item passed to rule functions — built from the `_.`-stripped path.
+    const stripped = strippedSegments(segments);
+    const item = {
+      source: path.dirname(source),
+      name: stripped[stripped.length - 1],
+      destination: stripped.slice(0, -1).join('/'),
+    };
+
+    if (typeof options.name === 'function') {
+      item.name = options.name(item);
+    }
+    if (typeof options.path === 'function') {
+      item.destination = options.path(item);
+    }
+    if (typeof options.skip === 'function') {
+      options.skip = options.skip(item);
+    }
+    if (typeof options.overwrite === 'function') {
+      options.overwrite = options.overwrite(item);
+    }
+
+    const finalRelative = path.join(item.destination, item.name);
+    const destination = path.join(outputDir, finalRelative);
+    const exists = jetpack.exists(destination);
+    const isBinary = BINARY_EXTENSIONS.test(item.name);
+
+    if (options.skip) {
+      result.skipped.push(finalRelative);
+      continue;
+    }
+
+    // Retire: the file never scaffolds. An existing framework-owned-only copy
+    // is deleted (one-time heal); consumer content is never destroyed.
+    if (options.retire) {
+      if (!exists) {
+        result.skipped.push(finalRelative);
+        continue;
+      }
+
+      let owned;
+      if (isBinary) {
+        owned = jetpack.read(source, 'buffer').equals(jetpack.read(destination, 'buffer'));
+      } else {
+        // Render the template through the same pipeline the scaffold used, so
+        // an untouched consumer copy compares equal.
+        let rendered = jetpack.read(source);
+        if (options.template) {
+          rendered = renderTemplate(rendered, options.template);
+        }
+        if (transform) {
+          rendered = transform(rendered, item);
+        }
+        owned = isFrameworkOwned(jetpack.read(destination), rendered);
+      }
+
+      if (owned) {
+        jetpack.remove(destination);
+        pruneEmptyDirs(path.dirname(destination), outputDir);
+        result.removed.push(finalRelative);
+        logger.warn(`Retired ${finalRelative} — framework-owned per-target doc; in a brand monorepo the BRAND ROOT (AGENTS.md / CHANGELOG.md / docs/) is the one doc home`);
+      } else {
+        result.skipped.push(finalRelative);
+        logger.warn(`Kept ${finalRelative} — it carries consumer content. Per-target docs are retired in brand monorepos: move that content to the brand root (AGENTS.md notes / brand CHANGELOG.md / brand docs/), then delete the file`);
+      }
+      continue;
+    }
+
+    // Binary: copy or preserve — no content processing.
+    if (isBinary) {
+      if (exists && !options.overwrite) {
+        result.skipped.push(finalRelative);
+        continue;
+      }
+      jetpack.copy(source, destination, { overwrite: true });
+      result.written.push(finalRelative);
+      continue;
+    }
+
+    let contents = jetpack.read(source);
+    let didMerge = false;
+
+    // Per-rule template render happens BEFORE merging, so merges compare
+    // rendered framework defaults against the consumer's file (EM semantic).
+    if (options.template) {
+      contents = renderTemplate(contents, options.template);
+    }
+
+    if (options.merge && exists) {
+      try {
+        const JSON5 = require('json5');
+        const merged = mergeJson5Defaults(JSON5.parse(jetpack.read(destination)), JSON5.parse(contents));
+        contents = JSON5.stringify(merged, null, 2);
+        didMerge = true;
+      } catch (error) {
+        logger.error(`Error merging config file ${finalRelative}: ${error.message}`);
+        // Fall through to normal processing.
+      }
+    }
+
+    if (options.mergeLines && exists) {
+      try {
+        contents = mergeLineBasedFiles(jetpack.read(destination), contents, item.name);
+        didMerge = true;
+      } catch (error) {
+        logger.error(`Error merging line-based file ${finalRelative}: ${error.message}`);
+      }
+    }
+
+    // Preserve the consumer's file unless a rule says otherwise — except a
+    // prior-generation marker artifact, which the framework owns and heals to
+    // the current template even under `overwrite: false` (the standalone twin
+    // of the retire sweep below).
+    if (exists && !options.overwrite && !didMerge && !isLegacyMarkerArtifact(jetpack.read(destination), contents)) {
+      result.skipped.push(finalRelative);
+      continue;
+    }
+
+    if (transform) {
+      contents = transform(contents, item);
+    }
+
+    // Idempotency: identical content is not a write.
+    if (exists && jetpack.read(destination) === contents) {
+      result.skipped.push(finalRelative);
+      continue;
+    }
+
+    jetpack.write(destination, contents);
+    (didMerge ? result.merged : result.written).push(finalRelative);
+    logger.log(`${didMerge ? 'Merged' : 'Scaffolded'} → ${finalRelative}`);
+  }
+
+  return result;
+}
+
+// Judge whether an existing consumer file is framework-owned-only (safe to
+// retire). Marker files are judged by their Custom section — empty,
+// whitespace-only, or exactly the template's shipped boilerplate all count as
+// untouched. Marker-less files must match the rendered template outright.
+function isFrameworkOwned(existing, rendered) {
+  if (hasSectionMarkers(existing)) {
+    if (isLegacyMarkerArtifact(existing, rendered)) return true;
+    const existingCustom = getCustomSection(existing).trim();
+    return existingCustom === '' || existingCustom === getCustomSection(rendered).trim();
+  }
+  return existing.trim() === rendered.trim();
+}
+
+// A generation change: the destination carries the OMEGA marker grammar — which
+// only this framework's own scaffold writes — while the current template has
+// dropped it. That file is a PRIOR GENERATION's generated copy (e.g. the
+// content-bearing CLAUDE.md written before it became the one-line `@AGENTS.md`
+// pointer), so comparing it against the current render can never match and the
+// framework, not the consumer, owns it.
+function isLegacyMarkerArtifact(existing, rendered) {
+  return hasSectionMarkers(existing) && !hasSectionMarkers(rendered);
+}
+
+// Remove now-empty ancestor dirs of a retired file, stopping at (and never
+// removing) rootDir — a retired docs/README.md takes its empty docs/ with it.
+function pruneEmptyDirs(dir, rootDir) {
+  const root = path.resolve(rootDir);
+  let current = path.resolve(dir);
+  while (current !== root && current.startsWith(root + path.sep)) {
+    if ((jetpack.list(current) || []).length > 0) return;
+    jetpack.remove(current);
+    current = path.dirname(current);
+  }
+}
+
+// Depth-first file walk that never follows symlinks.
+function* walkFiles(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      yield* walkFiles(abs);
+    } else if (entry.isFile()) {
+      yield abs;
+    }
+  }
+}
+
+// `_.name` → `.name` on every segment (dotfiles ship past npm's tarball filter).
+function strippedSegments(segments) {
+  return segments.map((s) => (s.startsWith('_.') ? s.slice(1) : s));
+}
+
+// Last-match-wins option resolution across the file map (BXM's getFileOptions).
+function resolveOptions(relativePath, fileMap) {
+  let options = { ...RULE_DEFAULTS };
+
+  for (const pattern in fileMap) {
+    if (minimatch(relativePath, pattern, { dot: true })) {
+      options = { ...options, ...fileMap[pattern] };
+      options.rule = pattern;
+    }
+  }
+
+  return options;
+}
+
+// Minimal `{{ key.path }}` substitution (EM's tolerant renderer — the standard).
+// Unknown keys render as the original `{{ ... }}` string, so non-template content
+// with literal braces (e.g. GitHub Actions `${{ secrets.X }}`) survives.
+function renderTemplate(content, context) {
+  if (typeof content !== 'string' || !content.includes('{{')) return content;
+  return content.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (full, keyPath) => {
+    const value = keyPath.split('.').reduce((acc, k) => (acc == null ? acc : acc[k]), context);
+    return (value === undefined || value === null) ? full : String(value);
+  });
+}
+
+// JSON5 defaults merge (BXM's mergeConfigs): framework defaults provide shape and
+// order; the consumer's values win unless they're the literal string 'default';
+// consumer-only keys survive at every nesting level.
+function mergeJson5Defaults(existingConfig, newConfig) {
+  const merged = { ...newConfig };
+
+  function mergeNested(target, source, newDefaults) {
+    for (const key in newDefaults) {
+      if (Object.prototype.hasOwnProperty.call(newDefaults, key)) {
+        const newValue = newDefaults[key];
+        const existingValue = source[key];
+
+        if (typeof newValue === 'object' && newValue !== null && !Array.isArray(newValue)) {
+          target[key] = target[key] || {};
+          mergeNested(target[key], existingValue || {}, newValue);
+        } else if (Object.prototype.hasOwnProperty.call(source, key) && existingValue !== 'default') {
+          target[key] = existingValue;
+        } else {
+          target[key] = newValue;
+        }
+      }
+    }
+
+    // Consumer-only keys survive at every level.
+    for (const key in source) {
+      if (!Object.prototype.hasOwnProperty.call(newDefaults, key)) {
+        target[key] = source[key];
+      }
+    }
+  }
+
+  mergeNested(merged, existingConfig, newConfig);
+
+  return merged;
+}
+
+module.exports = { applyDefaults, mergeJson5Defaults, renderTemplate };

package/dist/vendor/devkit/deploy-precheck.js

@@ -0,0 +1,54 @@
+/**
+ * runDeployPrecheck — the shared runner for the NETWORK half `omega setup`
+ * used to own ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+ *
+ * Setup's local half rides every verb (each framework's ensure-target); what
+ * needs the network rides the ONE verb that needs the remote side right —
+ * `omega deploy` — as a precheck before the dispatch. The STEPS differ per
+ * framework (desktop signs and provisions release repos, extension checks its
+ * own freshness, web publishes Actions secrets); the RUNNER does not, so it
+ * lives here and every framework file is its list.
+ *
+ * The contract the runner guarantees:
+ *   - `--no-secrets` (yargs: `secrets: false`) skips the whole precheck — the
+ *     same opt-out name on web, desktop and extension (parity; desktop's old
+ *     `--quick` is gone).
+ *   - Every step is SOFT: a throwing step is reported as a warning and the run
+ *     continues. A precheck reports; the deploy is the caller's decision.
+ *   - Steps run in list order and `ran` names the ones that finished, so a test
+ *     hands its own recorder in and reads back exactly what happened.
+ */
+
+/**
+ * @param {object} input
+ * @param {string} input.projectDir - The target root.
+ * @param {object} [input.options] - The parsed CLI options (`secrets: false` = opted out).
+ * @param {object} input.logger - `{ log, warn, error }`.
+ * @param {Array<{ name: string, run: function }>} input.steps - The framework's step list.
+ * @returns {Promise<{ skipped: string }|{ ran: string[] }>} The steps that ran, or the opt-out marker.
+ */
+async function runDeployPrecheck({ projectDir, options, logger, steps }) {
+  // yargs turns `--no-secrets` into `secrets: false`.
+  if (options && options.secrets === false) {
+    logger.log('Skipping the network prechecks (--no-secrets)');
+    return { skipped: 'opt-out' };
+  }
+
+  const log = (line) => logger.log(line);
+  const warn = (line) => logger.warn(line);
+  const ran = [];
+
+  for (const step of steps) {
+    try {
+      await step.run({ projectDir, log, warn });
+      ran.push(step.name);
+    } catch (e) {
+      // A precheck REPORTS; the deploy is the caller's decision.
+      warn(`${step.name} failed during the deploy precheck (non-fatal): ${e.message}`);
+    }
+  }
+
+  return { ran };
+}
+
+module.exports = { runDeployPrecheck };