@omega.js/backend 0.1.0

package/dist/vendor/devkit/attach-log-file.js

@@ -0,0 +1,262 @@
+// attachLogFile(filePath, options) — tee process.stdout + process.stderr to a log file.
+//
+// Every chunk reaches BOTH sinks: the terminal exactly as written (colors intact) and the
+// file with ANSI escapes stripped, so `grep`/`tail -f` reads clean. The file opens
+// truncated — a new launch clears the previous run's log (no history kept).
+//
+// Writes go to an open fd SYNCHRONOUSLY. A stream's buffer dies with the process, which
+// dropped exactly the lines describing a crash; the per-write syscall buys the crash tail.
+//
+// `append: true` opens the file for APPEND instead, for a log MORE THAN ONE process writes
+// (the signing box's runner log: a `runner start` parent, then every `sign-windows` its
+// listener spawns). Default is unchanged — one launch, one log.
+//
+// attach(filePath, { env, attachInCI, append }) — `env` is the environment the CI check
+// reads (the test seam), `attachInCI` keeps the tee on a runner, `append` keeps what the
+// last process wrote.
+//
+// The default export is a process-wide SINGLETON (the common case: one CLI verb tees its
+// whole run to one file). `createTee()` returns an INDEPENDENT tee. Tees STACK: an attach
+// captures the CURRENT writers — the raw stream, or an outer tee's patched writer — so
+// writes fan out through every layer and each detach restores the exact writers it found.
+// That is what keeps an inner tee's detach from stealing (and truncating) the outer tee's
+// file, the way a shared singleton did.
+//
+// Skipped in CI: a runner has its own log capture and wants no logs/ left in the workspace.
+// `attachInCI: true` opts out of that skip, for a sink whose file is the POINT rather than
+// workspace debris (the signing box's own runner log, which a CI job is exactly when it
+// matters). Default is unchanged: every other caller still skips.
+//
+// `createChildLog()` is the sibling sink for output that never passes through this
+// process' writers at all — a SPAWNED child's piped stdout/stderr. See below.
+
+// Libraries
+const fs = require('fs');
+const path = require('path');
+const Logger = require('./logger');
+
+// Variables
+const logger = new Logger('attach-log-file');
+const ANSI_PATTERN = /\x1B\[[0-9;]*[a-zA-Z]/g;
+const NOOP_DETACH = function () {};
+
+function stripAnsi(value) {
+  return String(value).replace(ANSI_PATTERN, '');
+}
+
+// Same predicate the rest of the repo uses for "a runner is driving this".
+function isCI(env) {
+  return env.GITHUB_ACTIONS === 'true' || env.CI === 'true';
+}
+
+// Factory — each call returns an independent tee with its own closure state.
+function createTee() {
+  let activePath = null;
+  let activeDetach = null;
+  let warned = false;
+
+  function attach(filePath, options) {
+    const env = (options && options.env) || process.env;
+    const attachInCI = Boolean(options && options.attachInCI);
+
+    if (!filePath || (isCI(env) && !attachInCI)) { return NOOP_DETACH; }
+
+    const abs = path.resolve(filePath);
+
+    // Already teeing this exact file — do not patch a second time (that would write
+    // every line twice).
+    if (activePath === abs) { return activeDetach; }
+    if (activeDetach) { activeDetach(); }
+
+    let fd;
+    try {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fd = fs.openSync(abs, options && options.append ? 'a' : 'w');
+      fs.writeSync(fd, `# omega log — ${new Date().toISOString()} — pid=${process.pid}\n`);
+    } catch (e) {
+      // A log file we cannot open is a lost log, never a lost process — the tee exists to
+      // observe the run, so it declines and the run continues untouched.
+      if (!warned) {
+        warned = true;
+        logger.warn(`Could not open log file ${abs} — continuing without one (${e.message})`);
+      }
+      return NOOP_DETACH;
+    }
+
+    // Whatever is installed right now, captured by reference so detach restores it exactly.
+    const priorStdoutWrite = process.stdout.write;
+    const priorStderrWrite = process.stderr.write;
+
+    function writeToFile(chunk) {
+      try {
+        fs.writeSync(fd, stripAnsi(chunk));
+      } catch (e) {
+        // A broken log sink never breaks the writer it wraps.
+      }
+    }
+
+    process.stdout.write = function (chunk, ...rest) {
+      writeToFile(chunk);
+      return priorStdoutWrite.call(process.stdout, chunk, ...rest);
+    };
+    process.stderr.write = function (chunk, ...rest) {
+      writeToFile(chunk);
+      return priorStderrWrite.call(process.stderr, chunk, ...rest);
+    };
+
+    function closeFd() {
+      try {
+        fs.closeSync(fd);
+      } catch (e) {
+        // Already closed, or the process is tearing down.
+      }
+    }
+
+    // The fd outlives a crash otherwise — the writes already landed, this is the handle.
+    process.on('exit', closeFd);
+
+    let detached = false;
+    function detach() {
+      if (detached) { return; }
+      detached = true;
+
+      process.stdout.write = priorStdoutWrite;
+      process.stderr.write = priorStderrWrite;
+      process.off('exit', closeFd);
+      closeFd();
+
+      if (activeDetach === detach) {
+        activePath = null;
+        activeDetach = null;
+      }
+    }
+
+    activePath = abs;
+    activeDetach = detach;
+
+    return detach;
+  }
+
+  return {
+    attach,
+    detach: () => { if (activeDetach) { activeDetach(); } },
+  };
+}
+
+// createChildLog(options) — the sink for a SPAWNED process' output.
+//
+// The tee above patches this process' writers; a child's stdout/stderr never
+// pass through them — they arrive as buffers on a pipe. The caller mirrors each
+// buffer to the terminal untouched and hands it here, where it lands
+// ANSI-stripped in a file that opens truncated, same as the tee's.
+//
+// The roll is what the tee has no need for: a child that stays up for days (a
+// Firebase emulator) has to be truncatable MID-RUN, so a sibling process asks
+// for a fresh log by touching `resetPath` and the poll below honors it within
+// `pollMs`. Ported from BEM's emulator/serve commands, which carried a copy each.
+//
+// Writes go to an open fd synchronously, for the same reason the tee's do: the
+// lines describing a crash are the ones a buffered stream drops.
+//
+// Every operation is best-effort — a broken log sink must never break the
+// process it observes. It does say so ONCE though: a file that would not open
+// warns on the first write it drops, so a silently empty log is never a
+// surprise, and stays quiet after that.
+//
+// @param {object} options
+// @param {string} options.logPath - File the child's output lands in (truncated on open)
+// @param {string} [options.resetPath] - Sentinel another process touches to request a fresh log
+// @param {number} [options.pollMs=500] - Sentinel poll interval
+// @returns {{ path: string, write: Function, roll: Function, close: Function }}
+function createChildLog(options) {
+  const logPath = path.resolve(options.logPath);
+  const resetPath = options.resetPath ? path.resolve(options.resetPath) : null;
+  const pollMs = options.pollMs || 500;
+
+  let fd = null;
+  let openError = null;
+  let warned = false;
+
+  function removeSentinel() {
+    if (!resetPath) { return; }
+    try {
+      fs.unlinkSync(resetPath);
+    } catch (e) {
+      // Not there — the normal case.
+    }
+  }
+
+  function closeFd() {
+    if (fd === null) { return; }
+    try {
+      fs.closeSync(fd);
+    } catch (e) {
+      // Already closed, or the process is tearing down.
+    }
+    fd = null;
+  }
+
+  // Reopen with 'w' rather than truncating in place: an external truncate leaves
+  // the writer's offset where it was, so the file comes back sparse.
+  function roll() {
+    closeFd();
+    try {
+      fs.mkdirSync(path.dirname(logPath), { recursive: true });
+      fd = fs.openSync(logPath, 'w');
+      openError = null;
+    } catch (e) {
+      // A log we cannot open is a lost log, never a lost process — but a
+      // SILENT one is a run whose output nobody knows went nowhere, so the
+      // first dropped write says so (once), same as the tee's own warn.
+      fd = null;
+      openError = e;
+    }
+  }
+
+  function write(chunk) {
+    if (fd === null) {
+      if (openError && !warned) {
+        warned = true;
+        logger.warn(`Could not open log file ${logPath} — child output is not being recorded (${openError.message})`);
+      }
+      return;
+    }
+    try {
+      fs.writeSync(fd, stripAnsi(chunk));
+    } catch (e) {
+      // A broken log sink never breaks the stream it mirrors.
+    }
+  }
+
+  roll();
+
+  // A sentinel a crashed run left behind would roll the fresh log on the first poll.
+  removeSentinel();
+
+  const timer = resetPath ? setInterval(() => {
+    if (!fs.existsSync(resetPath)) { return; }
+    roll();
+    removeSentinel();
+  }, pollMs) : null;
+
+  function close() {
+    if (timer) { clearInterval(timer); }
+    closeFd();
+    removeSentinel();
+  }
+
+  return { path: logPath, write, roll, close };
+}
+
+// Process-wide singleton — the production entry point.
+const singleton = createTee();
+
+function attachLogFile(filePath, options) {
+  return singleton.attach(filePath, options);
+}
+
+module.exports = attachLogFile;
+module.exports.detach         = singleton.detach;
+module.exports.stripAnsi      = stripAnsi;
+module.exports.createTee      = createTee;
+module.exports.createChildLog = createChildLog;

package/dist/vendor/devkit/bare-requires.js

@@ -0,0 +1,153 @@
+/**
+ * "Does this project declare everything its sources require?" The migrate
+ * report's dependency-resolution scan ([#600](https://github.com/Omega-JS-Stack/omega/issues/600)).
+ *
+ * Under the legacy FLAT install every framework dependency sat in the
+ * consumer's own `node_modules`, so a ported file could `require('fs-jetpack')`
+ * and be right. Under OMEGA the framework is a package with its own tree, and a
+ * bare require of something the consumer never declared resolves only by
+ * HOISTING, which holds on one install and not on the next. The requires that
+ * carried this were LAZY (inside the function that needs them), so the module
+ * loads fine and the code 500s the first time it actually runs.
+ *
+ * REPORT ONLY, and by the consumer's own manifest: every bare specifier under
+ * the scanned tree that is neither a Node built-in, nor an alias the caller's
+ * framework resolves, nor a declared dependency, named file:line with the fix
+ * (declare it). Never an auto-install: which package version a brand wants is
+ * the brand's call.
+ *
+ * It lives HERE because both frameworks whose consumers were ported need it,
+ * and the answer must not differ between them: @omega.js/web's `omega migrate`
+ * and @omega.js/backend's `omega migrate` each pass their own alias list and
+ * read the same verdict. Stdlib-only, like every vendorable module.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { builtinModules } = require('node:module');
+
+// Both spellings of every built-in: `require('fs')` and `require('node:fs')`.
+const BUILTINS = new Set([...builtinModules, ...builtinModules.map((name) => `node:${name}`)]);
+
+const REQUIRE_CALL = /\brequire\(\s*(['"])([^'"\n]+)\1\s*\)/g;
+
+// Build output, vendored trees and the archive dirs a port leaves behind: none
+// of them is source this project ships, and scanning them reports findings
+// nobody can act on.
+const SKIP_DIRS = ['node_modules', 'dist', '_site', '_legacy', '_backup', '.git'];
+
+// The dependency fields npm resolves a bare specifier from at RUNTIME or in a
+// build. A peer the consumer declares is installed beside it like any other.
+const MANIFEST_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+
+/**
+ * The PACKAGE a specifier resolves to: `@scope/name` keeps two segments,
+ * everything else keeps one, and the subpath is not the dependency.
+ *
+ * @param {string} specifier
+ * @returns {string}
+ */
+function packageName(specifier) {
+  const segments = specifier.split('/');
+
+  return specifier.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
+}
+
+/**
+ * Every `.js` file under a dir, build output and archive dirs skipped.
+ *
+ * @param {string} dir
+ * @returns {string[]} Absolute paths, sorted.
+ */
+function collectScriptFiles(dir) {
+  const files = [];
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.includes(entry.name)) walk(full);
+        continue;
+      }
+
+      if (entry.isFile() && path.extname(entry.name) === '.js') files.push(full);
+    }
+  };
+
+  if (fs.existsSync(dir)) walk(dir);
+
+  return files.sort();
+}
+
+/**
+ * Every package name the consumer's own package.json declares.
+ *
+ * @param {string} root - Consumer project root.
+ * @returns {Set<string>|null} null when there is no manifest to judge against.
+ */
+function declaredPackages(root) {
+  const manifestPath = path.join(root, 'package.json');
+  if (!fs.existsSync(manifestPath)) return null;
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null; // an unparseable manifest says nothing about what is declared
+  }
+
+  const declared = new Set();
+  for (const field of MANIFEST_FIELDS) {
+    for (const name of Object.keys(manifest[field] || {})) declared.add(name);
+  }
+
+  return declared;
+}
+
+/**
+ * Scan a consumer's sources for bare requires of packages it does not declare.
+ *
+ * @param {string} root - Consumer project root (the manifest is judged from here).
+ * @param {object} [options]
+ * @param {string[]} [options.aliases] - Package names the framework RESOLVES for
+ *   the consumer (a bundler alias, a runtime the framework owns). None is a
+ *   dependency a consumer may declare, so naming one would hand the report a
+ *   fix that breaks the project.
+ * @param {string} [options.srcDir] - The tree to scan, relative to root. Defaults to `src`.
+ * @returns {Array<{ file: string, line: number, module: string, fix: string }>}
+ *   One entry per file+package, at its first sighting.
+ */
+function collectBareRequires(root, options = {}) {
+  const aliases = options.aliases || [];
+  const declared = declaredPackages(root);
+  if (!declared) return [];
+
+  const found = [];
+  for (const filePath of collectScriptFiles(path.join(root, options.srcDir || 'src'))) {
+    const source = fs.readFileSync(filePath, 'utf8');
+    const seen = new Set();
+
+    REQUIRE_CALL.lastIndex = 0;
+    let match;
+    while ((match = REQUIRE_CALL.exec(source)) !== null) {
+      const specifier = match[2];
+      if (specifier.startsWith('.') || specifier.startsWith('/')) continue; // a path, not a package
+      if (BUILTINS.has(specifier)) continue;
+
+      const name = packageName(specifier);
+      if (aliases.includes(name)) continue;
+      if (declared.has(name) || seen.has(name)) continue;
+      seen.add(name);
+
+      found.push({
+        file: path.relative(root, filePath),
+        line: source.slice(0, match.index).split('\n').length,
+        module: name,
+        fix: `add it to this project's package.json (\`npm install ${name}\`), it resolved through the legacy flat install and resolves under OMEGA only by hoisting`,
+      });
+    }
+  }
+
+  return found;
+}
+
+module.exports = { collectBareRequires, packageName };

package/dist/vendor/devkit/command-path.js

@@ -0,0 +1,46 @@
+/**
+ * "Is this tool installed?" — the ONE cross-platform PATH probe.
+ *
+ * Every framework asks it of an external CLI it shells out to (mkcert,
+ * nodemon, the Stripe CLI) and the answer decides whether a lane runs or
+ * degrades. The probe itself is platform-specific: Unix has `which`, Windows
+ * has `where`, and each host has only its own — a bare `which` on Windows is
+ * not "not installed", it's a crash the caller reads as "not installed".
+ */
+const { execSync } = require('child_process');
+
+/**
+ * Is a command installed? An EXISTENCE probe.
+ *
+ * **Never spawn what this returns.** The path is for REPORTING — a log line, a
+ * diagnostic, a "which one did we find". Running the tool means naming it BARE
+ * and letting the host resolve it (`spawnOnPath` in @omega.js/backend does
+ * exactly that), because on Windows `where` prints the extensionless shell shim
+ * FIRST, and neither that shim nor the `.cmd` beside it is something Node's
+ * CreateProcess can execute — only a shell can, and only a shell applies
+ * PATHEXT. Truthiness is the answer this exists to give.
+ *
+ * @param {string} name - Command name, e.g. 'mkcert'
+ * @param {object} [options]
+ * @param {string} [options.platform] - Host platform (test seam)
+ * @param {function} [options.exec] - execSync (test seam)
+ * @returns {string|null} The first path the probe reported, or null when it is not installed
+ */
+function commandOnPath(name, { platform = process.platform, exec = execSync } = {}) {
+  const probe = platform === 'win32' ? 'where' : 'which';
+
+  try {
+    const found = exec(`${probe} ${name}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+
+    // `where` prints EVERY match, one per line (`which` prints one); the first
+    // is the one the shell would pick — on Windows that is the extensionless
+    // shim, which is why this answer is reported and not spawned.
+    return String(found).split(/\r?\n/)[0].trim() || null;
+  } catch (e) {
+    // Both probes exit nonzero when the name isn't found — the expected answer,
+    // not a failure.
+    return null;
+  }
+}
+
+module.exports = { commandOnPath };