@omega.js/backend 0.1.0

package/dist/vendor/devkit/logger.js

@@ -0,0 +1,128 @@
+// Build-time logger — timestamped, tag-scoped console output for CLI commands, gulp
+// tasks, and test runners. `new Logger('setup')` then logger.log/error/warn/info,
+// which prints `[HH:MM:SS] [@omega.js/<package>:setup] message`.
+//
+// NOT for app/runtime logging — frameworks with runtime logging needs (e.g. desktop's
+// Electron file-transport logger-lite) keep their own, and emit the same tag WITHOUT
+// the timestamp (devtools stamps runtime lines).
+
+// Libraries
+const chalk = require('chalk').default;
+const path = require('path');
+// Plain fs, not fs-jetpack: this module is VENDORED into every framework, and
+// vendoring requires the host to declare each runtime dependency the vendored
+// code uses (tools/vendor.js) — a logger must not push a dep onto its hosts.
+const fs = require('fs');
+
+// The one identity tag: [@omega.js/<package>:<module>]. The package segment is
+// derived from the file that CONSTRUCTED the logger — call sites stay
+// `new Logger('setup')` and never name their own package.
+//
+// KNOWN LIMIT: the derivation reports whatever package owns the constructing
+// file, so a CONSUMER file constructing one (a brand's own build script, a
+// consumer hook) would stamp the consumer's package name — e.g.
+// `[my-brand:deploy]`, not `[@omega.js/web:deploy]`. That is arguably the honest
+// answer (the line really does come from consumer code), and no such call site
+// exists today: every construction is inside a framework here or in its vendored
+// dist copy. It stays a documented limit rather than a check because the repo
+// guard (scripts/log-tags.test.js) cannot see consumer trees at all.
+const FALLBACK_PACKAGE = '@omega.js/devkit';
+
+// Cache the directory → package-name lookup; a build constructs many loggers.
+const packageNameCache = new Map();
+
+// Walk up from a directory to the nearest package.json and read its name.
+function findPackageName(startDir) {
+  if (packageNameCache.has(startDir)) {
+    return packageNameCache.get(startDir);
+  }
+
+  let name = null;
+  let dir = startDir;
+  while (true) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      if (manifest && manifest.name) {
+        name = manifest.name;
+        break;
+      }
+    } catch (e) {
+      // No package.json here (or unreadable) — keep walking up.
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) { break; }
+    dir = parent;
+  }
+
+  packageNameCache.set(startDir, name);
+  return name;
+}
+
+// Derive the package segment from the first stack frame outside this file.
+// A logger must NEVER throw, so every failure path lands on FALLBACK_PACKAGE:
+// stack formats vary by runtime (and vendored/bundled copies can lose paths),
+// and a mislabelled log line is always cheaper than a crashed build.
+function derivePackage() {
+  try {
+    const frames = (new Error().stack || '').split('\n').slice(1);
+    for (const frame of frames) {
+      const match = frame.match(/\((.*):\d+:\d+\)\s*$/) || frame.match(/at (.*):\d+:\d+\s*$/);
+      if (!match) { continue; }
+      const file = match[1].replace(/^file:\/\//, '');
+      if (!path.isAbsolute(file)) { continue; }
+      if (file === __filename) { continue; }
+      return findPackageName(path.dirname(file)) || FALLBACK_PACKAGE;
+    }
+  } catch (e) {
+    // Fall through to the fallback below.
+  }
+  return FALLBACK_PACKAGE;
+}
+
+// Logger class
+function Logger(name) {
+  const self = this;
+  self.name = name;
+  self.package = derivePackage();
+}
+
+// Make methods that log to console with the tag and time: [xx:xx:xx] [@omega.js/pkg:name] message
+['log', 'error', 'warn', 'info'].forEach((method) => {
+  Logger.prototype[method] = function () {
+    const time = new Date().toLocaleTimeString('en-US', {
+      hour12: false,
+      hour:   '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+    });
+
+    let color;
+    switch (method) {
+      case 'warn':
+        color = chalk.yellow;
+        break;
+      case 'error':
+        color = chalk.red;
+        break;
+      default:
+        color = (text) => text;
+    }
+
+    const args = [`[${chalk.magenta(time)}] [${chalk.cyan(`${this.package}:${this.name}`)}]`, ...Array.from(arguments).map((arg) => {
+      if (typeof arg === 'string') {
+        return color(arg);
+      }
+      if (arg instanceof Error) {
+        return color(arg.stack);
+      }
+      return arg;
+    })];
+
+    console[method].apply(console, args);
+  };
+});
+
+// Export chalk as format
+Logger.prototype.format = chalk;
+
+module.exports = Logger;

package/dist/vendor/devkit/merge-line-files.js

@@ -0,0 +1,296 @@
+// Merge line-based files (.env, .gitignore, AGENTS.md) during framework setup —
+// the OMEGA marker-section protocol. Canonical version is EM's (it added .env
+// double-quote normalization and order-safe key substitution over the older
+// BXM/UJM inline copies) plus @omega.js/backend's custom-key promotion (a key the framework
+// newly adopts into its Default section is promoted UP from the user's Custom
+// section with their value, instead of appearing empty in Default and set in
+// Custom).
+//
+// Convention (the ONE OMEGA marker grammar — `<comment> ========== <Label> ==========`,
+// comment token per file type; the rules-file managed block is the `//` flavor of the
+// same family, owned by @omega.js/backend — see _attic/plans/archive/marker-harmonization.md):
+//
+//   # ========== Default Values ==========
+//   # framework-managed; overwritten on every setup
+//   KEY1=
+//   KEY2="value with spaces"
+//
+//   # ========== Custom Values ==========
+//   # user's section; preserved verbatim across setups
+//   USER_SECRET="my-secret"
+//
+// Behavior:
+//   - The Default section is replaced with the new framework's defaults.
+//   - Keys that already had values (in either Default or Custom) keep those values
+//     in the same section they were in.
+//   - Keys the user added to the Default section that are NOT in the new framework's
+//     defaults migrate to the Custom section (so framework cleanups don't lose user data).
+//   - .env values are normalized to **double-quoted** form on every merge:
+//       KEY=raw-value         →   KEY="raw-value"
+//       KEY="already-quoted"  →   KEY="already-quoted"  (left alone)
+//       KEY=                  →   KEY=                  (empty stays empty/unquoted)
+//     This protects values containing spaces, #, $, or other shell-meaningful chars.
+//   - .env COMMENTED PLACEHOLDERS (`# KEY=` in the template's Default section)
+//     mark keys the framework knows but ships no value for (the env cascade
+//     supplies values from stronger layers — dogfood friction #20). On merge:
+//     an existing NON-EMPTY value for that key (either section) keeps its line
+//     in Default; an existing EMPTY value (`KEY=` / `KEY=""`) converges to the
+//     commented placeholder instead of migrating to Custom.
+//   - .gitignore: same logic, line-based instead of key-based (no quoting).
+//   - AGENTS.md: same logic as .gitignore (line-based, no quoting). The markers
+//     render as visible H1 headings in markdown — that's intentional UX.
+//   - First setup (no existing file): the framework template lands as-is.
+
+const DEFAULT_MARKER = '# ========== Default Values ==========';
+const CUSTOM_MARKER  = '# ========== Custom Values ==========';
+
+function mergeLineBasedFiles(existingContent, newContent, fileName) {
+  const isEnvFile = fileName === '.env';
+
+  const existingLines = existingContent.split('\n');
+  const newLines      = newContent.split('\n');
+
+  // Parse existing into default + custom sections.
+  const { defaultLines: existingDefault, customLines: existingCustom, existingDefaultKeys, existingCustomKeys }
+    = splitSections(existingLines, isEnvFile);
+
+  // Parse new content. We only use its default section (custom is the user's domain).
+  const { defaultLines: newDefault, customLines: newCustom } = splitSections(newLines, isEnvFile);
+
+  // Build the merged default section: walk new defaults in order, substituting the
+  // user's existing value for any key they had set in either section.
+  const newDefaultKeys = new Set();
+  const mergedDefault  = [];
+  const emit = (line) => mergedDefault.push(isEnvFile ? normalizeEnvLine(line) : line);
+
+  for (const line of newDefault) {
+    const trimmed = line.trim();
+
+    if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
+      const key = trimmed.split('=')[0].trim();
+      if (key) {
+        newDefaultKeys.add(key);
+        if (existingDefaultKeys.has(key)) {
+          emit(findKeyLine(existingDefault, key));
+          continue;
+        }
+        if (existingCustomKeys.has(key)) {
+          // The framework newly adopted a key the user had in their Custom section.
+          // Promote it UP into Default with the user's value, and drop the Custom copy
+          // (handled below) so the key isn't duplicated / left empty.
+          emit(findKeyLine(existingCustom, key));
+          continue;
+        }
+      }
+      emit(line);
+    } else if (!isEnvFile && trimmed && !trimmed.startsWith('#')) {
+      // .gitignore: just keep the new line.
+      mergedDefault.push(line);
+    } else {
+      // Comment / blank — for .env, a `# KEY=` placeholder claims the key:
+      // an existing set value keeps its line, an empty one converges away.
+      const placeholderKey = isEnvFile ? parsePlaceholderKey(trimmed) : null;
+
+      if (placeholderKey) {
+        newDefaultKeys.add(placeholderKey);
+
+        const existingLine = existingDefaultKeys.has(placeholderKey)
+          ? findKeyLine(existingDefault, placeholderKey)
+          : existingCustomKeys.has(placeholderKey)
+            ? findKeyLine(existingCustom, placeholderKey)
+            : null;
+
+        if (existingLine && !envValueIsEmpty(existingLine)) {
+          emit(existingLine);
+          continue;
+        }
+      }
+
+      mergedDefault.push(line);
+    }
+  }
+
+  // User-added stuff in their Default section that the new framework doesn't know about
+  // → migrate to Custom so it's preserved without being clobbered next setup.
+  const migratedToCustom = [];
+  for (const line of existingDefault) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    if (isEnvFile) {
+      const key = trimmed.split('=')[0].trim();
+      if (key && !newDefaultKeys.has(key) && !existingCustomKeys.has(key)) {
+        migratedToCustom.push(normalizeEnvLine(line));
+      }
+    } else {
+      // .gitignore: line not in new defaults → migrate.
+      const inNew = newLines.some((nl) => nl.trim() === trimmed);
+      if (!inNew) {
+        migratedToCustom.push(line);
+      }
+    }
+  }
+
+  // The user's Custom section is preserved — except (a) .env values get normalized
+  // to double-quoted form for consistent quoting, and (b) any key that was promoted
+  // UP into the Default section above is dropped here so it isn't duplicated. Keys
+  // present in BOTH sections are NOT dropped (the Default copy's value won there,
+  // so removing the Custom copy would silently change dotenv's effective value).
+  const finalCustom = isEnvFile
+    ? existingCustom
+        .filter((line) => {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed.startsWith('#')) return true;
+          const key = trimmed.split('=')[0].trim();
+          return !(key && newDefaultKeys.has(key) && !existingDefaultKeys.has(key));
+        })
+        .map((line) => normalizeEnvLine(line))
+    : existingCustom;
+
+  const result = [];
+  result.push(DEFAULT_MARKER);
+  result.push(...mergedDefault);
+  // Insert a single blank line before CUSTOM_MARKER, but only if the merged default
+  // doesn't already end with one (otherwise we'd accumulate an extra blank line on
+  // every merge — breaking idempotency on the first re-run after a fresh `jetpack.copy`).
+  if (mergedDefault.length === 0 || mergedDefault[mergedDefault.length - 1].trim() !== '') {
+    result.push('');
+  }
+  result.push(CUSTOM_MARKER);
+  if (migratedToCustom.length > 0) {
+    result.push(...migratedToCustom);
+  }
+  result.push(...finalCustom);
+
+  return result.join('\n');
+}
+
+// Normalize a single .env line:
+//   - Comments / blanks unchanged
+//   - KEY=  (empty value) unchanged
+//   - KEY="..." (already double-quoted) unchanged
+//   - KEY=raw-value → KEY="raw-value" (with embedded " and \ escaped)
+//   - KEY='single' → KEY="single"  (canonicalize single → double)
+function normalizeEnvLine(line) {
+  if (typeof line !== 'string') return line;
+
+  // Preserve comments and blank lines verbatim.
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return line;
+
+  // Capture leading whitespace so we don't lose indentation.
+  const leadingMatch = line.match(/^(\s*)/);
+  const leading = leadingMatch ? leadingMatch[1] : '';
+
+  const eqIdx = trimmed.indexOf('=');
+  if (eqIdx < 0) return line; // no `=` — not a KEY=VALUE line
+
+  const key = trimmed.slice(0, eqIdx).trim();
+  let value = trimmed.slice(eqIdx + 1);
+
+  // Strip trailing whitespace + inline comment-after-value (rare; we only strip a # that follows a space).
+  // We do NOT strip # inside quoted values. Detect that by checking if value starts with a quote.
+  if (value.length === 0) {
+    return `${leading}${key}=`;
+  }
+
+  // Already double-quoted? Leave alone (preserves user's exact contents).
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    return `${leading}${key}=${value}`;
+  }
+
+  // Single-quoted → canonicalize to double-quoted.
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    const inner = value.slice(1, -1);
+    return `${leading}${key}="${escapeForDoubleQuote(inner)}"`;
+  }
+
+  // Raw value → wrap.
+  return `${leading}${key}="${escapeForDoubleQuote(value)}"`;
+}
+
+function escapeForDoubleQuote(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function splitSections(lines, isEnvFile) {
+  const defaultLines = [];
+  const customLines  = [];
+  const existingDefaultKeys = new Set();
+  const existingCustomKeys  = new Set();
+
+  let mode = null; // null | 'default' | 'custom'
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === DEFAULT_MARKER) { mode = 'default'; continue; }
+    if (trimmed === CUSTOM_MARKER)  { mode = 'custom';  continue; }
+
+    // Lines before any marker are treated as default (legacy / fresh files).
+    if (mode === 'custom') {
+      customLines.push(line);
+      if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
+        const key = trimmed.split('=')[0].trim();
+        if (key) existingCustomKeys.add(key);
+      }
+    } else {
+      defaultLines.push(line);
+      if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
+        const key = trimmed.split('=')[0].trim();
+        if (key) existingDefaultKeys.add(key);
+      }
+    }
+  }
+
+  return { defaultLines, customLines, existingDefaultKeys, existingCustomKeys };
+}
+
+function findKeyLine(lines, key) {
+  const re = new RegExp(`^\\s*${key}\\s*=`);
+  for (const line of lines) {
+    if (re.test(line)) return line;
+  }
+  return `${key}=`;
+}
+
+// `# KEY=` (nothing after the =) → KEY; any other comment → null.
+function parsePlaceholderKey(trimmed) {
+  const match = trimmed.match(/^#\s*([A-Za-z_][A-Za-z0-9_]*)=\s*$/);
+  return match ? match[1] : null;
+}
+
+// KEY= / KEY="" / KEY='' (whitespace tolerated) count as empty.
+function envValueIsEmpty(line) {
+  const eqIdx = line.indexOf('=');
+  if (eqIdx < 0) return true;
+  const value = line.slice(eqIdx + 1).trim();
+  return value === '' || value === '""' || value === "''";
+}
+
+/**
+ * Check whether a file already carries both section markers (i.e. has been
+ * through the merge protocol at least once). Setup validators use this to
+ * distinguish legacy/no-marker files from protocol-managed ones.
+ * @param {string} content
+ * @returns {boolean}
+ */
+function hasSectionMarkers(content) {
+  return typeof content === 'string'
+    && content.includes(DEFAULT_MARKER)
+    && content.includes(CUSTOM_MARKER);
+}
+
+/**
+ * Extract the consumer-owned Custom section of a marker file (everything after
+ * the Custom marker), or '' when there is no marker. The defaults engine's
+ * `retire` rule uses this to judge whether a per-target doc carries consumer
+ * content or is framework-owned-only.
+ * @param {string} content
+ * @returns {string}
+ */
+function getCustomSection(content) {
+  if (typeof content !== 'string') return '';
+  const idx = content.indexOf(CUSTOM_MARKER);
+  return idx < 0 ? '' : content.slice(idx + CUSTOM_MARKER.length);
+}
+
+module.exports = { mergeLineBasedFiles, normalizeEnvLine, hasSectionMarkers, getCustomSection, DEFAULT_MARKER, CUSTOM_MARKER };

package/dist/vendor/devkit/npm-registry.js

@@ -0,0 +1,52 @@
+/**
+ * npm-registry — minimal npm registry reads shared by every framework CLI
+ * (replaces the unmaintained npm-api dependency).
+ *
+ * Both functions treat network/registry failure as an expected external
+ * condition and return null — callers decide their own fallback (skip the
+ * check, assume up-to-date, warn). They never throw.
+ */
+
+const REGISTRY_URL = 'https://registry.npmjs.org';
+const FETCH_TIMEOUT_MS = 30 * 1000;
+
+/**
+ * Fetch a package's latest-version manifest (the `<registry>/<name>/latest`
+ * document: version, dependencies, peerDependencies, …).
+ *
+ * @param {string} packageName - npm package name (scoped names supported)
+ * @param {object} [options]
+ * @param {string} [options.registryUrl] - registry base URL (test seam)
+ * @param {number} [options.timeout] - fetch timeout in ms
+ * @returns {Promise<object|null>} manifest object, or null on any failure
+ */
+async function getPackageManifest(packageName, options = {}) {
+  const registryUrl = (options.registryUrl || REGISTRY_URL).replace(/\/$/, '');
+  // Scoped names encode the slash but keep the leading @ (registry convention)
+  const encoded = encodeURIComponent(packageName).replace(/^%40/, '@');
+
+  try {
+    const response = await fetch(`${registryUrl}/${encoded}/latest`, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(options.timeout || FETCH_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    return await response.json();
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Fetch a package's latest published version.
+ *
+ * @param {string} packageName - npm package name
+ * @param {object} [options] - same options as getPackageManifest
+ * @returns {Promise<string|null>} version string, or null on any failure
+ */
+async function getLatestVersion(packageName, options) {
+  const manifest = await getPackageManifest(packageName, options);
+  return (manifest && manifest.version) || null;
+}
+
+module.exports = { getPackageManifest, getLatestVersion };