@omega.js/desktop 0.52.0 → 0.54.0

package/dist/vendor/devkit/env-lines.js

@@ -0,0 +1,183 @@
+/**
+ * The .env line grammar the marker engine merges by and every in-place key
+ * writer sets keys by: logical lines (a quoted value spanning several physical
+ * lines is one unit), the key a line assigns, the double-quote normalization,
+ * and the replace-or-append of a key's lines. dotenv is the reader every OMEGA loader
+ * uses, so it is the judge: a normalized line must read back to the same value,
+ * and a key's winning line is its LAST one, as dotenv reads it.
+ */
+const dotenv = require('dotenv');
+const { envLine } = require('../config/index.js');
+
+// An assignment dotenv accepts: optional indent and `export `, then KEY=
+const ASSIGNMENT = /^(\s*(?:export\s+)?)([\w.-]+)\s*=(.*)$/s;
+const QUOTED_OPEN = /^\s*(?:export\s+)?[\w.-]+\s*=\s*(["'`])/;
+
+/**
+ * The index of the quote closing a value opened at `from`, as dotenv picks it:
+ * a quote after a backslash may close the value or be passed, the first quote
+ * after no backslash cannot be passed, and dotenv takes the LAST closing
+ * candidate followed on its line by only whitespace or a `# comment`, so
+ * `K="x\"` reads `x\`. -1 when none closes it.
+ *
+ * @param {string} text
+ * @param {string} quote - `"`, `'` or a backtick
+ * @param {number} from - First index after the opening quote
+ * @returns {number}
+ */
+function closingQuote(text, quote, from) {
+  const lineRest = /[^\S\n]*(?:#[^\n]*)?(?:\n|$)/y;
+  let close = -1;
+  for (let i = from; i < text.length; i += 1) {
+    if (text[i] !== quote) continue;
+    lineRest.lastIndex = i + 1;
+    if (lineRest.test(text)) close = i;
+    if (text[i - 1] !== '\\') break;
+  }
+  return close;
+}
+
+/**
+ * Group physical lines into logical ones: a quoted value that closes on a later
+ * line joins those lines (newlines kept) into one unit, so it moves and
+ * survives whole. An unterminated quote stays line by line, as dotenv reads it.
+ *
+ * @param {string[]} lines - The file split on `\n`
+ * @returns {string[]}
+ */
+function joinEnvUnits(lines) {
+  const units = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const open = lines[i].match(QUOTED_OPEN);
+    const rest = open ? lines.slice(i).join('\n') : '';
+    const close = open ? closingQuote(rest, open[1], open[0].length) : -1;
+    if (close < 0) {
+      units.push(lines[i]);
+      continue;
+    }
+
+    const end = i + rest.slice(0, close).split('\n').length - 1;
+    units.push(lines.slice(i, end + 1).join('\n'));
+    i = end;
+  }
+  return units;
+}
+
+/**
+ * The key a line assigns, or null for a comment, a blank, or anything else.
+ *
+ * @param {string} line
+ * @returns {string|null}
+ */
+function envKey(line) {
+  const match = line.match(ASSIGNMENT);
+  return match ? match[2] : null;
+}
+
+// The inline comment after a raw value: past the closing quote of a quoted
+// value, from the first `#` of an unquoted one.
+function trailingComment(raw) {
+  let rest = raw;
+  if (raw[0] === "'" || raw[0] === '`') {
+    const close = closingQuote(raw, raw[0], 1);
+    if (close >= 0) rest = raw.slice(close + 1);
+  }
+  const hash = rest.indexOf('#');
+  return hash < 0 ? '' : rest.slice(hash).trim();
+}
+
+/**
+ * Normalize one .env line to the double-quoted form: `KEY=raw` and `KEY='x'`
+ * become `KEY="..."`, an inline comment kept; an empty value becomes `KEY=""`;
+ * a double-quoted value, a comment and a blank are left alone. The rewrite
+ * happens only when dotenv reads the same value back; otherwise the line stays.
+ *
+ * @param {string} line - One logical line
+ * @returns {string}
+ */
+function normalizeEnvLine(line) {
+  const match = line.match(ASSIGNMENT);
+  if (!match) return line;
+  const [, prefix, key, rawValue] = match;
+  const raw = rawValue.trim();
+
+  if (raw === '') return `${prefix}${key}=""`;
+  if (raw.startsWith('"')) return line;
+
+  const value = dotenv.parse(line)[key];
+  if (value === undefined) return line;
+
+  let quoted;
+  try {
+    quoted = envLine(key, value);
+  } catch (e) {
+    // envLine refuses a value dotenv would read back changed: the line stays
+    return line;
+  }
+  const comment = trailingComment(raw);
+  const candidate = `${prefix}${quoted}${comment ? ` ${comment}` : ''}`;
+  return dotenv.parse(candidate)[key] === value ? candidate : line;
+}
+
+/**
+ * The line that sets `key`: the LAST one, the value dotenv reads.
+ *
+ * @param {string[]} lines
+ * @param {string} key
+ * @returns {string} - `KEY=""` when no line sets it
+ */
+function findKeyLine(lines, key) {
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (envKey(lines[i]) === key) return lines[i];
+  }
+  return `${key}=""`;
+}
+
+// A placeholder, `# KEY=""` or a bare `# KEY=`, → KEY; any other comment → null.
+function parsePlaceholderKey(trimmed) {
+  const match = trimmed.match(/^#\s*([A-Za-z_][A-Za-z0-9_]*)=\s*(?:"")?\s*$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Set keys in .env content by logical line: the first unit assigning a key, or
+ * its `# KEY=""` placeholder, becomes the given line and every later one drops,
+ * so dotenv reads the new value; a key the content never had is appended.
+ * Every other line keeps its place.
+ *
+ * @param {string} content - Current file content ('' for none)
+ * @param {Object<string, string>} lineFor - KEY to its whole line, e.g. envLine's
+ * @returns {string} The new content, ending in exactly one newline
+ */
+function setEnvLines(content, lineFor) {
+  const body = content.replace(/(?:\r?\n)+$/, '');
+  const seen = new Set();
+
+  const out = joinEnvUnits(body === '' ? [] : body.split(/\r?\n/)).flatMap((unit) => {
+    const key = envKey(unit) ?? parsePlaceholderKey(unit.trim());
+    if (key === null || !Object.hasOwn(lineFor, key)) return [unit];
+    if (seen.has(key)) return [];
+    seen.add(key);
+    return [lineFor[key]];
+  });
+  for (const key of Object.keys(lineFor)) {
+    if (!seen.has(key)) out.push(lineFor[key]);
+  }
+  return `${out.join('\n')}\n`;
+}
+
+// The framework's own .env comment grammar: a boxed group header or a
+// `# KEY=""` placeholder. Regenerated from the template, never a consumer's note.
+function isMachineComment(trimmed) {
+  return /^# ── .* ──$/.test(trimmed) || parsePlaceholderKey(trimmed) !== 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 === "''";
+}
+
+module.exports = { joinEnvUnits, envKey, normalizeEnvLine, findKeyLine, parsePlaceholderKey, isMachineComment, envValueIsEmpty, setEnvLines };

package/dist/vendor/devkit/local.js

@@ -16,9 +16,9 @@
  *   into the monorepo is read-only and stops the boot loudly, any other local
  *   checkout is rebuilt and the invocation re-execs once
  *
- * Consumers: `omega dev --local` (@omega.js/web), `mgr i local`
- * (@omega.js/backend, @omega.js/desktop, @omega.js/extension), and the monorepo's
- * own scripts/watch-all.js (lock helpers + vendor propagation).
+ * Consumers: `omega dev --local` (@omega.js/web), @omega.js/manager's
+ * brand-root `omega i local` / `omega i live` (src/commands/install.js), and the
+ * monorepo's own scripts/watch-all.js (lock helpers + vendor propagation).
  */
 
 // Libraries
@@ -276,6 +276,43 @@ function regenerateBrandLockfile(installRoot, logger) {
   return regenerateLockfile({ root: installRoot, log: logger ? (line) => logger.log(line) : undefined });
 }
 
+/**
+ * Prune the install root's lockfile before a tree install (#862): npm's install
+ * honors a locked link just as its lock-only run does. Loaded lazily, as above.
+ * @param {string} installRoot - The brand root (or standalone target).
+ * @param {object} [logger] - Logger with log (silent when omitted).
+ */
+function pruneBrandLockfile(installRoot, logger) {
+  const { pruneLockfile } = require('./lockfile.js');
+  pruneLockfile({ root: installRoot, log: logger ? (line) => logger.log(line) : undefined });
+}
+
+/**
+ * Throw when any @omega.js package of the tree still resolves into a checkout
+ * (#862): a symlink under the install root's or any target's node_modules, or
+ * a resolution that lands in a monorepo. The one check `omega i live` ends on.
+ * @param {string} installRoot - The brand root (or standalone target).
+ */
+function assertRegistryTree(installRoot) {
+  for (const targetDir of discoverTargets(installRoot)) {
+    const scopeDir = path.join(targetDir, 'node_modules', SCOPE);
+    // No scope folder here: this target's copies are hoisted, or it has none.
+    if (!fs.existsSync(scopeDir)) continue;
+
+    for (const name of fs.readdirSync(scopeDir)) {
+      const installed = path.join(scopeDir, name);
+      if (fs.lstatSync(installed).isSymbolicLink()) {
+        throw new Error(`omega i live left ${installed} linked into ${path.resolve(scopeDir, fs.readlinkSync(installed))}`);
+      }
+    }
+  }
+
+  const monorepoRoot = resolveLinkedMonorepo(installRoot);
+  if (monorepoRoot) {
+    throw new Error(`omega i live left ${installRoot} linked into ${monorepoRoot}`);
+  }
+}
+
 /**
  * Whether the install root's lockfile is missing or disagrees with its
  * manifests' @omega.js registry specs: the deploy gate's own read (#938).
@@ -301,9 +338,10 @@ function brandLockfileStale(installRoot) {
  * ONE `npm install` materializes the links for the whole tree. Standalone
  * targets degenerate to themselves.
  *
- * Idempotent: dependencies already resolving to the monorepo copy are
- * skipped, and when nothing needs linking no install runs. An install is
- * followed by the brand's OWN lockfile regeneration (#938).
+ * Idempotent: dependencies already resolving to the monorepo copy AND
+ * already declaring its file: spec are skipped, and when nothing needs
+ * linking no install runs. An install is followed by the brand's OWN
+ * lockfile regeneration (#938).
  * @param {object} options
  * @param {string} options.dir - Target directory to link from (any target in the brand).
  * @param {string} options.monorepoRoot - Monorepo root path.
@@ -339,13 +377,13 @@ async function linkLocalPackages(options) {
         continue;
       }
 
-      if (isLinkedTo(entry.dir, entry.name, target)) {
+      const spec = `file:${relativeSpecPath(entry.dir, target)}`;
+      if (isLinkedTo(entry.dir, entry.name, target) && entry.spec === spec) {
         actions.push({ name: entry.name, dir: entry.dir, target, action: 'skip' });
         logger && logger.log(`${entry.name}: already linked to the monorepo`);
         continue;
       }
 
-      const spec = `file:${relativeSpecPath(entry.dir, target)}`;
       if (entry.spec === spec) {
         // Spec already correct, only the install is missing — no rewrite,
         // so a committed relative spec is never churned to a new layout.
@@ -398,8 +436,9 @@ async function linkLocalPackages(options) {
  * caller owns that string. Idempotent: registry-spec'd entries are untouched;
  * nothing to flip → no install. Same transactional manifest restore as the
  * linker when the install fails. Either way the brand's OWN lockfile ends up
- * agreeing with the manifests (#938): regenerated after the install, and
- * regenerated alone when nothing flipped but the lock still disagrees.
+ * agreeing with the manifests (#938): pruned before the install and
+ * regenerated after it, and regenerated alone when nothing flipped but the lock
+ * still disagrees. Every run but a dryRun ends on assertRegistryTree() (#862).
  * @param {object} options
  * @param {string} options.dir - Any directory inside the brand.
  * @param {object} [options.logger] - Logger with log/warn (silent when omitted).
@@ -456,12 +495,21 @@ async function restoreRegistrySpecs(options) {
   }
 
   if (installNeeded) {
+    // The prune below rewrites the lock, so a failed install puts it back too.
+    const lockPath = path.join(installRoot, 'package-lock.json');
+    const lockBackup = fs.existsSync(lockPath) ? fs.readFileSync(lockPath, 'utf8') : null;
+
     try {
+      // BEFORE the install (#862): npm keeps a locked link whose checkout
+      // satisfies the flipped spec, in the lock and in node_modules' hidden lock.
+      pruneBrandLockfile(installRoot, logger);
+      fs.rmSync(path.join(installRoot, 'node_modules', '.package-lock.json'), { force: true });
       await safeInstall('npm install', { log: true, config: { cwd: installRoot } });
     } catch (error) {
       for (const [manifestPath, contents] of manifestBackups) {
         fs.writeFileSync(manifestPath, contents);
       }
+      if (lockBackup !== null) fs.writeFileSync(lockPath, lockBackup);
       logger && logger.warn(`install failed — restored ${manifestBackups.size} manifest(s) to their file: specs`);
       throw error;
     }
@@ -476,6 +524,10 @@ async function restoreRegistrySpecs(options) {
     await regenerateBrandLockfile(installRoot, logger);
   }
 
+  // Every run, not only after an install: a brand already on registry specs
+  // can still be linked, which is the state this verb exists to end.
+  assertRegistryTree(installRoot);
+
   return actions;
 }
 
@@ -1981,6 +2033,8 @@ module.exports = {
   findBrandRoot,
   discoverTargets,
   frameworkPackagesOf,
+  resolvePackageRealDir,
+  isLocalCheckout,
   linkLocalPackages,
   restoreRegistrySpecs,
   resolveLinkedMonorepo,

package/dist/vendor/devkit/lockfile.js

@@ -82,6 +82,34 @@ function dropDrift(lock, drift) {
   return dropped;
 }
 
+/**
+ * Prune `root`'s package-lock.json in place: the stale path entries, then the
+ * @omega.js entries the deploy gate refuses. The lock-only regeneration runs it
+ * first, and so does `omega i live` before its tree install
+ * ([#862](https://github.com/Omega-JS-Stack/omega/issues/862)), since that
+ * install honors the lock's old links just the same.
+ *
+ * @param {object} options
+ * @param {string} options.root - The install root whose lock is pruned.
+ * @param {function} [options.log] - Line sink (silent when omitted).
+ * @returns {void}
+ */
+function pruneLockfile({ root, log }) {
+  const { lockPath, lock, drift } = brandLockfileDrift({ root });
+
+  // No lock, or one without a `packages` map, has no entry to prune.
+  if (!lock || !lock.packages) return;
+
+  const pruned = dropStalePaths(lock, root);
+  const dropped = dropDrift(lock, drift);
+
+  if (pruned.length || dropped.length) {
+    jetpack.write(lockPath, `${JSON.stringify(lock, null, 2)}\n`);
+  }
+  if (log && pruned.length) log(`Pruned the lock entries of folders no longer on disk (${pruned.join(', ')}) so npm stops honoring what they declare`);
+  if (log && dropped.length) log(`Dropped the stale lock entries of ${dropped.join(', ')} so npm resolves them from the manifests`);
+}
+
 /**
  * Regenerate `root`'s package-lock.json from its manifests, lock-only: no
  * scripts, no node_modules writes.
@@ -92,19 +120,10 @@ function dropDrift(lock, drift) {
  * @returns {Promise<void>}
  */
 async function regenerateLockfile({ root, log }) {
-  const { lockPath, lock, drift } = brandLockfileDrift({ root });
-  const original = lock ? jetpack.read(lockPath) : null;
-
-  if (lock && lock.packages) {
-    const pruned = dropStalePaths(lock, root);
-    const dropped = dropDrift(lock, drift);
+  const lockPath = path.join(root, 'package-lock.json');
+  const original = jetpack.exists(lockPath) === 'file' ? jetpack.read(lockPath) : null;
 
-    if (pruned.length || dropped.length) {
-      jetpack.write(lockPath, `${JSON.stringify(lock, null, 2)}\n`);
-    }
-    if (log && pruned.length) log(`Pruned the lock entries of folders no longer on disk (${pruned.join(', ')}) so npm stops honoring what they declare`);
-    if (log && dropped.length) log(`Dropped the stale lock entries of ${dropped.join(', ')} so npm resolves them from the manifests`);
-  }
+  pruneLockfile({ root, log });
 
   if (log) log(`Regenerating ${path.basename(root)}/package-lock.json...`);
 
@@ -124,4 +143,4 @@ async function regenerateLockfile({ root, log }) {
   }
 }
 
-module.exports = { regenerateLockfile };
+module.exports = { pruneLockfile, regenerateLockfile };

package/dist/vendor/devkit/logger.js

@@ -1,5 +1,5 @@
 // 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,
+// tasks, and test runners. `new Logger('setup')` then logger.log/error/warn/info/debug,
 // which prints `[HH:MM:SS] [@omega.js/<package>:setup] message`.
 //
 // NOT for app/runtime logging — frameworks with runtime logging needs (e.g. desktop's
@@ -87,8 +87,13 @@ function Logger(name) {
 }
 
 // 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) => {
+['log', 'error', 'warn', 'info', 'debug'].forEach((method) => {
   Logger.prototype[method] = function () {
+    // debug is the one opt-in level (docs/shared/logging.md): OMEGA_DEBUG, read live.
+    if (method === 'debug' && !process.env.OMEGA_DEBUG) {
+      return;
+    }
+
     const time = new Date().toLocaleTimeString('en-US', {
       hour12: false,
       hour:   '2-digit',