@omega.js/manager 0.1.0

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 };

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

@@ -0,0 +1,180 @@
+/**
+ * The per-brand deploy record — `<target>` under the `deploy` section of
+ * `.omega/state.json` (gitignored, per-machine). Multi-instance targets key
+ * per target: the primary stays `<target>`, other instances record under
+ * `<target>:<id>` (see deployKey).
+ *
+ * Written by every framework's deploy verb on success; read by the
+ * manager's testing service to tell "never deployed" (live-URL checks skip
+ * with a nudge) from "deployed but down" (an honest error). A record-less
+ * brand whose live URL answers gets ADOPTED — recorded on the spot — so
+ * fresh clones of long-deployed brands self-heal on their first manage run
+ * (Ian 2026-07-17).
+ *
+ * state.json is the ONE per-machine record file, sectioned per fact kind
+ * (#479): future record-shaped facts join it as sibling top-level sections, so
+ * this module reads and writes ONLY `deploy` and passes every other section
+ * through verbatim — including the config-shaped keys an unmigrated brand
+ * still carries from the retired state CONTENT (#434), which belong to the
+ * state-retirement migration and to nothing here.
+ *
+ * The record spent 0.45.0 in a `.omega/deploys.json` of its own (#449); a
+ * brand still carrying that file has it adopted here, once and loudly.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const Logger = require('./logger.js');
+const { findBrandRoot } = require('./local.js');
+
+const logger = new Logger('deploy-record');
+
+function stateFile(dir) {
+  return path.join(findBrandRoot(dir), '.omega', 'state.json');
+}
+
+/**
+ * Read the machine state with its `deploy` section resolved, folding in the
+ * interim `.omega/deploys.json` (#449) on the way — one-time and LOUD, so a
+ * brand that deployed on 0.45.0 keeps its stamps and the operator sees where
+ * they went. Records already in state.json WIN: newest write, newest home.
+ *
+ * A brand whose state.json already carries a `deploy` key is home — the
+ * records are read in place, silently, whatever else the file still holds.
+ *
+ * Rewrites the files it touches, so callers hold the lock.
+ *
+ * @param {string} file - The state.json path.
+ * @returns {Object} The machine state, `deploy` section included.
+ */
+function loadState(file) {
+  const state = jetpack.read(file, 'json') || {};
+  const records = state.deploy || {};
+
+  const deploysFile = path.join(path.dirname(file), 'deploys.json');
+  const deploys = jetpack.read(deploysFile, 'json');
+
+  state.deploy = deploys ? { ...deploys, ...records } : records;
+  if (!deploys) return state;
+
+  // The new home lands before the old file goes: a crash between the two
+  // writes must never leave the records with no file at all.
+  jetpack.write(file, state, { jsonIndent: 2 });
+  jetpack.remove(deploysFile);
+
+  if (Object.keys(deploys).length > 0) {
+    logger.log(`Adopted ${describe(deploys)} from .omega/deploys.json into .omega/state.json — the old file was removed.`);
+  }
+
+  return state;
+}
+
+/**
+ * "1 deploy record" / "3 deploy records" — the adoption line's subject.
+ * @param {Object} records - key → record.
+ * @returns {string}
+ */
+function describe(records) {
+  const count = Object.keys(records).length;
+  return `${count} deploy record${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * Record key for a target's instance (multi-instance targets): the primary
+ * keeps today's bare target key (zero breaking change — existing records
+ * stay valid); any other instance keys `<target>:<id>`, matching the
+ * per-target deploy model (each target deploys its own instance).
+ * @param {string} target - Target key (web/backend/desktop/extension)
+ * @param {string} [instance] - Instance id ('main' or absent = the primary)
+ * @returns {string} The deploy-record key
+ */
+function deployKey(target, instance) {
+  return instance && instance !== 'main' ? `${target}:${instance}` : target;
+}
+
+/**
+ * Run fn under a best-effort cross-process lock on the records file, so two
+ * targets deploying in parallel can't drop each other's record in the
+ * read-modify-write. Lock contention waits briefly; a stale lock (owner
+ * crashed) is stolen after 5s; on timeout we proceed unlocked — a deploy
+ * must never fail over its bookkeeping.
+ * @param {string} file - Records file path.
+ * @param {function} fn - Critical section.
+ * @returns {*} fn's result.
+ */
+function withStateLock(file, fn) {
+  const lockDir = `${file}.lock`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  const deadline = Date.now() + 2000;
+  let locked = false;
+  while (Date.now() < deadline) {
+    try {
+      fs.mkdirSync(lockDir);
+      locked = true;
+      break;
+    } catch (e) {
+      try {
+        if (Date.now() - fs.statSync(lockDir).mtimeMs > 5000) {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+          continue;
+        }
+      } catch (statError) {
+        continue; // Lock vanished between mkdir and stat — retry immediately
+      }
+      // Synchronous 25ms wait (no async surface here by design)
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    if (locked) {
+      fs.rmSync(lockDir, { recursive: true, force: true });
+    }
+  }
+}
+
+/**
+ * Record a successful deploy for a target.
+ *
+ * @param {Object} options
+ * @param {string} options.dir - Any directory inside the brand (target or root)
+ * @param {string} options.target - Target key (web/backend/desktop/extension)
+ * @param {string} [options.instance] - Instance id; non-main instances record
+ *   under their own `<target>:<id>` key (per-target deploy records)
+ * @param {Object} [options.detail] - Extra fields (method, adopted, …)
+ * @returns {Object} The written record
+ */
+function recordDeploy(options) {
+  const file = stateFile(options.dir);
+  const key = deployKey(options.target, options.instance);
+
+  return withStateLock(file, () => {
+    const state = loadState(file);
+
+    state.deploy[key] = { at: new Date().toISOString(), ...(options.detail || {}) };
+    jetpack.write(file, state, { jsonIndent: 2 });
+
+    return state.deploy[key];
+  });
+}
+
+/**
+ * The recorded deploy for a target's instance — null when the brand has
+ * never deployed it from this machine (and no manage run has adopted a live
+ * site yet).
+ *
+ * @param {Object} options - { dir, target, instance? }
+ * @returns {Object|null}
+ */
+function readDeployRecord(options) {
+  const file = stateFile(options.dir);
+  // Under the lock because the read is also where a legacy record is adopted
+  const state = withStateLock(file, () => loadState(file));
+  return state.deploy[deployKey(options.target, options.instance)] || null;
+}
+
+module.exports = { recordDeploy, readDeployRecord, deployKey };

package/dist/vendor/devkit/flows.js

@@ -0,0 +1,317 @@
+/**
+ * Interactive terminal flows — browser-open and wait/poll loops, TTY-safe
+ * like prompt.js. omega-manager's terminal-utils ported: openBrowserAndPoll
+ * drives the "do something in a browser, poll the API until it shows up"
+ * onboarding flows; pollWithSpinner is the wait half on its own; withSpinner
+ * wraps a slow call in a live spinner.
+ *
+ * Degradation without a TTY (CI, company-mode children, node --test):
+ * nothing prompts, nothing draws — openBrowserAndPoll prints the URL and
+ * skips; pollWithSpinner polls quietly (or skips when manualOnly);
+ * withSpinner prints one line instead of animating.
+ *
+ * Test seams: streams ride prompt.js's setPromptStreams (keypresses in,
+ * spinner + prompt output out — real keystrokes, no mocks), and
+ * setBrowserOpener(fn) replaces the platform browser launcher so tests
+ * never open a real browser.
+ */
+const { spawn } = require('node:child_process');
+const readline = require('node:readline');
+const chalk = require('chalk').default;
+const { input, isInteractive, getPromptStreams, enterToOpenMessage } = require('./prompt.js');
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+let _opener = null;
+
+/**
+ * Replace the platform browser launcher (test seam). Pass null to restore.
+ */
+function setBrowserOpener(fn) {
+  _opener = fn || null;
+}
+
+function platformOpener(url) {
+  const [command, args] = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.once('spawn', () => {
+      child.unref();
+      resolve(true);
+    });
+    child.once('error', () => resolve(false));
+  });
+}
+
+/**
+ * Open a URL in the default browser. Resolves false when no launcher is
+ * available (callers always print the URL first, so failure just means
+ * the user clicks it themselves).
+ *
+ * @param {string} url - URL to open
+ * @returns {Promise<boolean>} - Whether a browser launch was started
+ */
+function openBrowser(url) {
+  return (_opener || platformOpener)(url);
+}
+
+/**
+ * Run an async function with a live spinner (one static line without a TTY).
+ *
+ * @param {string} message - Message to display while waiting
+ * @param {Function} fn - Async function to execute
+ * @param {Object} [options]
+ * @param {string} [options.indent] - Indentation prefix
+ * @returns {any} - Result of fn()
+ */
+async function withSpinner(message, fn, options = {}) {
+  const { indent = '      ' } = options;
+  const { output } = getPromptStreams();
+
+  if (!isInteractive()) {
+    output.write(`${indent}${message}...\n`);
+    return fn();
+  }
+
+  let spinnerIndex = 0;
+  const startTime = Date.now();
+
+  const interval = setInterval(() => {
+    const frame = SPINNER_FRAMES[spinnerIndex % SPINNER_FRAMES.length];
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    output.write(`\r${indent}${frame} ${message}... (${elapsed}s)`);
+    spinnerIndex++;
+  }, 100);
+
+  try {
+    return await fn();
+  } finally {
+    clearInterval(interval);
+    output.write('\r' + ' '.repeat(70) + '\r');
+  }
+}
+
+/**
+ * Poll until a condition is met, with a spinner and keyboard controls
+ * (ENTER = check now — or "I'm done" when manualOnly; S = skip waiting).
+ *
+ * Without a TTY there are no keys and no spinner: manualOnly returns
+ * skipped immediately (nobody can press ENTER), API-checked polls run
+ * quietly on the interval.
+ *
+ * @param {Object} options
+ * @param {Function} options.check - Async () => { done: boolean, result?: any, error?: string }
+ * @param {number} [options.intervalMs] - Interval between checks (default: 10000)
+ * @param {string} [options.message] - Message to display while waiting
+ * @param {string} [options.indent] - Indentation prefix
+ * @param {boolean} [options.manualOnly] - No API check available; just wait for ENTER
+ * @returns {Promise<{ success: boolean, result?: any, error?: string, skipped?: boolean }>}
+ */
+async function pollWithSpinner(options) {
+  const {
+    check,
+    intervalMs = 10000,
+    message = 'Waiting',
+    indent = '        ',
+    manualOnly = false,
+  } = options;
+
+  const { input, output } = getPromptStreams();
+
+  // Non-interactive: no keys, no spinner
+  if (!isInteractive()) {
+    if (manualOnly) {
+      output.write(`${indent}${chalk.dim('⊘ Non-interactive — cannot wait for manual confirmation')}\n`);
+      return { success: false, skipped: true };
+    }
+
+    output.write(`${indent}${message}... ${chalk.dim(`(checking every ${Math.round(intervalMs / 1000)}s)`)}\n`);
+    while (true) {
+      try {
+        const result = await check();
+        if (result.done) {
+          if (result.error) {
+            return { success: false, error: result.error };
+          }
+          return { success: true, result: result.result };
+        }
+      } catch (error) {
+        return { success: false, error: error.message };
+      }
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  }
+
+  output.write(`\n${indent}${chalk.dim(`(enter)=${manualOnly ? 'done' : 'check now'}, (s)=skip`)}\n\n`);
+
+  let spinnerIndex = 0;
+  let lastCheck = Date.now();
+  let checkNow = false;
+  let skip = false;
+
+  // Keyboard input on the effective stream (fake TTYs in tests lack
+  // setRawMode — a stream-level capability, not something we own)
+  readline.emitKeypressEvents(input);
+  input.setRawMode?.(true);
+  input.resume();
+
+  const keypressHandler = (ch, key) => {
+    if (key?.name === 'return') {
+      checkNow = true;
+    } else if (ch?.toLowerCase() === 's') {
+      skip = true;
+    } else if (key?.ctrl && key?.name === 'c') {
+      process.exit();
+    }
+  };
+  input.on('keypress', keypressHandler);
+
+  const startTime = Date.now();
+  const spinnerInterval = setInterval(() => {
+    const frame = SPINNER_FRAMES[spinnerIndex % SPINNER_FRAMES.length];
+    if (manualOnly) {
+      const elapsed = Math.floor((Date.now() - startTime) / 1000);
+      output.write(`\r${indent}${frame} ${message}... (${elapsed}s)`);
+    } else {
+      const elapsed = Math.floor((Date.now() - lastCheck) / 1000);
+      const remaining = Math.max(0, intervalMs / 1000 - elapsed);
+      output.write(`\r${indent}${frame} ${message}... (${remaining}s)`);
+    }
+    spinnerIndex++;
+  }, 100);
+
+  const cleanup = () => {
+    clearInterval(spinnerInterval);
+    output.write('\r' + ' '.repeat(70) + '\r');
+    // Only remove OUR keypress listener (inquirer manages its own)
+    input.removeListener('keypress', keypressHandler);
+    input.setRawMode?.(false);
+    input.pause();
+  };
+
+  try {
+    while (true) {
+      if (skip) {
+        cleanup();
+        return { success: false, skipped: true };
+      }
+
+      // In manual mode, ENTER means "I'm done" — success immediately
+      if (manualOnly && checkNow) {
+        cleanup();
+        return { success: true };
+      }
+
+      if (!manualOnly) {
+        try {
+          const result = await check();
+          if (result.done) {
+            cleanup();
+            if (result.error) {
+              return { success: false, error: result.error };
+            }
+            return { success: true, result: result.result };
+          }
+        } catch (error) {
+          cleanup();
+          return { success: false, error: error.message };
+        }
+      }
+
+      // Wait for the next interval — or until a key cuts it short
+      lastCheck = Date.now();
+      checkNow = false;
+
+      await new Promise((resolve) => {
+        let timer = null;
+        const keyPoll = setInterval(() => {
+          if (checkNow || skip) {
+            clearInterval(keyPoll);
+            clearTimeout(timer);
+            resolve();
+          }
+        }, 100);
+        // In manual mode there's no auto-check — only user input resolves
+        if (!manualOnly) {
+          timer = setTimeout(() => {
+            clearInterval(keyPoll);
+            resolve();
+          }, intervalMs);
+        }
+      });
+    }
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}
+
+/**
+ * Print instructions + a URL, open the browser (Enter-gated), and poll
+ * until the condition is met. The core onboarding-flow shape: "create the
+ * thing in this dashboard; I'll wait until I can see it via the API."
+ *
+ * Without a TTY the URL is printed and the flow returns skipped.
+ *
+ * The open is gated behind Enter — the ONE synonymous walkthrough gate
+ * (prompt.js enterToOpenMessage); skipping the step happens at the poll
+ * via (s), never by declining the open.
+ *
+ * @param {Object} options
+ * @param {string} options.url - URL to open
+ * @param {string} options.promptMessage - What needs to be done there
+ * @param {string} [options.label] - What the Enter gate calls the page
+ * @param {string} options.waitMessage - Message shown while polling
+ * @param {Function} [options.check] - Async condition (see pollWithSpinner)
+ * @param {number} [options.intervalMs] - Poll interval (default: 10000)
+ * @param {string} [options.indent] - Indentation prefix
+ * @param {boolean} [options.manualOnly] - No API check; wait for ENTER
+ * @returns {Promise<{ success: boolean, result?: any, error?: string, skipped?: boolean }>}
+ */
+async function openBrowserAndPoll(options) {
+  const {
+    url,
+    promptMessage,
+    label = 'this page',
+    waitMessage,
+    check,
+    intervalMs = 10000,
+    indent = '        ',
+    manualOnly = false,
+  } = options;
+
+  const { output } = getPromptStreams();
+
+  output.write(`\n${indent}${promptMessage}\n${indent}URL: ${chalk.cyan(url)}\n\n`);
+
+  if (!isInteractive()) {
+    output.write(`${indent}${chalk.dim('⊘ Non-interactive — skipping browser open + poll')}\n`);
+    return { success: false, skipped: true };
+  }
+
+  await input({ message: enterToOpenMessage(label) });
+
+  const opened = await openBrowser(url);
+  if (!opened) {
+    output.write(`${indent}${chalk.dim("(couldn't launch a browser — open the URL above manually)")}\n`);
+  }
+
+  return pollWithSpinner({
+    check,
+    intervalMs,
+    message: waitMessage,
+    indent,
+    manualOnly,
+  });
+}
+
+module.exports = {
+  openBrowser,
+  setBrowserOpener,
+  withSpinner,
+  pollWithSpinner,
+  openBrowserAndPoll,
+};