@omega.js/desktop 0.1.0

package/dist/commands/logs.js

@@ -0,0 +1,185 @@
+// `npx omega logs [runtime|dev|build|test]` — show / tail / locate one of the
+// project's log files.
+//
+// The optional positional names the surface (default `runtime`) and resolves to
+// <projectRoot>/logs/<surface>.log — the same four files documented in
+// docs/logging.md. Every flag below works on whichever surface was named.
+//
+// `runtime` resolves to the file the runtime logger writes to:
+//   - Dev (running from a project directory): <projectRoot>/logs/runtime.log
+//   - Outside a project: prints the conventional Electron user-data path the runtime
+//     would resolve to in production, but doesn't read it (we don't know the AppName
+//     from outside the running app).
+//
+// Flags:
+//   (default)        Print the resolved path, then `tail -50` of the file.
+//   --tail / -f      Follow mode — keep printing as the file grows. Ctrl+C to stop.
+//   --path / -p      Just print the resolved path. Useful for piping to your own tools.
+//   --open           Open the log file in the OS default editor.
+//   --lines=<N>      How many lines for the default (non-follow) read. Defaults to 50.
+
+const path    = require('path');
+const fs      = require('fs');
+const jetpack = require('fs-jetpack');
+const { spawn, spawnSync } = require('child_process');
+const { STOP_SIGNALS } = require('../vendor/devkit/stop-signals.js');
+
+// The tee'd surfaces a project writes into logs/ — one file each, same names on
+// every framework (docs/shared/logging.md).
+const SURFACES = ['runtime', 'dev', 'build', 'test'];
+
+module.exports = async function logs(options) {
+  options = options || {};
+  options._ = options._ || [];
+
+  // `omega logs dev` → options._ = ['logs', 'dev'], the router's positional
+  // convention. No positional keeps the historical runtime surface.
+  const surface = options._[1] || 'runtime';
+  if (!SURFACES.includes(surface)) {
+    throw new Error(`Unknown log surface "${surface}". Try one of: ${SURFACES.join(', ')}.`);
+  }
+
+  const logPath = resolveLogPath(surface);
+  const exists = jetpack.exists(logPath) === 'file';
+
+  // --path: print and exit. Pipe-friendly.
+  if (options.path || options.p) {
+    console.log(logPath);
+    return;
+  }
+
+  // --open: open in default editor and exit.
+  if (options.open) {
+    if (!exists) {
+      console.error(`No log file at ${logPath}. Run the app or verb that writes it at least once to generate logs.`);
+      process.exitCode = 1;
+      return;
+    }
+    openInDefaultEditor(logPath);
+    console.log(`Opened ${logPath}`);
+    return;
+  }
+
+  // --tail / -f: follow mode.
+  if (options.tail || options.f) {
+    if (!exists) {
+      // It's fine to follow a file that doesn't exist yet — we'll start tailing once
+      // it appears. Useful workflow: launch `mgr logs --tail` in one terminal, then
+      // `npm start` in another, and watch the log appear.
+      console.log(`Watching for log file at ${logPath} (will start tailing once it exists)...`);
+      jetpack.dir(path.dirname(logPath));
+    }
+    return tailFollow(logPath);
+  }
+
+  // Default: print path + last N lines.
+  const lines = parseInt(options.lines, 10) || 50;
+  console.log(`Log file: ${logPath}`);
+  if (!exists) {
+    console.log('(file does not exist yet — run the app or verb that writes it to generate logs)');
+    return;
+  }
+  console.log(`(last ${lines} lines)`);
+  console.log('─'.repeat(60));
+  const content = fs.readFileSync(logPath, 'utf8');
+  const allLines = content.split(/\r?\n/);
+  const tailLines = allLines.slice(Math.max(0, allLines.length - lines));
+  process.stdout.write(tailLines.join('\n'));
+  if (!tailLines[tailLines.length - 1]?.endsWith('\n')) process.stdout.write('\n');
+};
+
+// Resolve a surface's log path the same way its writer does — for `runtime`,
+// that's lib/logger-lite.js. We don't require logger-lite here because that
+// would attempt to load `electron`, which is only available when running inside
+// the Electron runtime (not from a CLI).
+function resolveLogPath(surface) {
+  // CLI runs from the consumer project root, so this matches dev-mode logger
+  // resolution exactly: <cwd>/logs/<surface>.log.
+  return path.join(process.cwd(), 'logs', `${surface}.log`);
+}
+
+// Cross-platform "open in default app" — uses the OS's URL/file handler.
+function openInDefaultEditor(filePath) {
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    spawnSync('open', [filePath], { stdio: 'inherit' });
+  } else if (platform === 'win32') {
+    // start needs the shell to interpret it. Empty quoted title arg avoids cmd
+    // treating the first quoted token as a window title.
+    spawnSync('cmd', ['/c', 'start', '""', filePath], { stdio: 'inherit' });
+  } else {
+    spawnSync('xdg-open', [filePath], { stdio: 'inherit' });
+  }
+}
+
+// `tail -f` semantics, implemented in pure Node so it works on Windows where there's
+// no `tail` binary. Strategy:
+//   1. Print everything in the file already (so user has full context).
+//   2. Watch the file for size changes; on each change, read from the previous size
+//      to the new size and print the delta.
+//   3. Handle truncation (file rotation) by resetting the offset to 0.
+//
+// Returns a Promise that resolves when the user Ctrl+Cs (or the watcher errors).
+function tailFollow(logPath) {
+  return new Promise((resolve) => {
+    let lastSize = 0;
+
+    // Initial dump of everything currently in the file.
+    if (jetpack.exists(logPath) === 'file') {
+      const data = fs.readFileSync(logPath, 'utf8');
+      process.stdout.write(data);
+      lastSize = Buffer.byteLength(data, 'utf8');
+    }
+
+    // fs.watch fires on rename / change events. We poll on change rather than
+    // streaming because Node's stream interface against a growing file is fiddly
+    // (you have to manage your own offset anyway).
+    let watcher;
+    try {
+      jetpack.dir(path.dirname(logPath));
+      watcher = fs.watch(path.dirname(logPath), { persistent: true }, (eventType, filename) => {
+        if (filename !== path.basename(logPath)) return;
+        try {
+          if (jetpack.exists(logPath) !== 'file') return;
+          const stat = fs.statSync(logPath);
+          if (stat.size < lastSize) {
+            // File was truncated (rotation). Reset and re-read from start.
+            lastSize = 0;
+            process.stdout.write('\n--- log rotated ---\n');
+          }
+          if (stat.size > lastSize) {
+            const fd = fs.openSync(logPath, 'r');
+            try {
+              const buf = Buffer.alloc(stat.size - lastSize);
+              fs.readSync(fd, buf, 0, buf.length, lastSize);
+              process.stdout.write(buf.toString('utf8'));
+              lastSize = stat.size;
+            } finally {
+              fs.closeSync(fd);
+            }
+          }
+        } catch (e) {
+          // File may have been momentarily missing during rotation — just wait
+          // for the next event.
+        }
+      });
+      watcher.on('error', (e) => {
+        console.error(`watcher error: ${e.message}`);
+        resolve();
+      });
+    } catch (e) {
+      console.error(`Could not watch ${logPath}: ${e.message}`);
+      resolve();
+      return;
+    }
+
+    // Clean up on every way this follow is asked to stop, off the ONE devkit
+    // list ([#629](https://github.com/Omega-JS-Stack/omega/issues/629)): a
+    // closed terminal (SIGHUP) used to kill the run with the watcher still open.
+    STOP_SIGNALS.forEach((signal) => process.on(signal, () => {
+      if (watcher) watcher.close();
+      console.log('\n(stopped following)');
+      resolve();
+    }));
+  });
+}

package/dist/commands/package.js

@@ -0,0 +1,31 @@
+// Libraries
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('package');
+const { runPipeline } = require('../utils/build-pipeline.js');
+
+// `npx omega package` (the consumer's `package` script) builds the full installer
+// set; `--quick` (the `package:quick` script) builds only the host platform/arch.
+// That is ALL `--quick` does (#737): the build ahead of it is full and cold, and
+// the flag is read here and nowhere else.
+function plan(options) {
+  options = options || {};
+
+  const quick = options.quick === true || options.q === true;
+
+  return {
+    env: { OMEGA_BUILD_MODE: 'true' },
+    steps: [
+      { type: 'clean' },
+      { type: 'certs' },
+      { type: 'gulp', task: quick ? 'packageQuick' : 'packageBuild' },
+    ],
+  };
+}
+
+module.exports = async function (options) {
+  logger.log('Running package...');
+
+  await runPipeline(plan(options), options);
+};
+
+module.exports.plan = plan;

package/dist/commands/publish.js

@@ -0,0 +1,34 @@
+// Libraries
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('publish');
+const { runPipeline } = require('../utils/build-pipeline.js');
+
+// `npx omega publish` publishes from an already-built tree (the CI lane calls it
+// after its own build); `--local` (the consumer's `release:local` script) cleans
+// first. Both deliver the Apple signing artifacts (#678) and then run cert
+// validation before the gulp task — a warning gate unless `--strict` makes it
+// fatal (validate-certs.js owns that).
+function plan(options) {
+  options = options || {};
+
+  const steps = [];
+
+  if (options.local === true) {
+    steps.push({ type: 'clean' });
+  }
+
+  steps.push({ type: 'certs' }, { type: 'validate-certs' }, { type: 'gulp', task: 'publish' });
+
+  return {
+    env: { OMEGA_BUILD_MODE: 'true', OMEGA_IS_PUBLISH: 'true' },
+    steps: steps,
+  };
+}
+
+module.exports = async function (options) {
+  logger.log('Running publish...');
+
+  await runPipeline(plan(options), options);
+};
+
+module.exports.plan = plan;

package/dist/commands/push-secrets.js

@@ -0,0 +1,141 @@
+/**
+ * The `.env` → GitHub Actions secrets publisher for the desktop target.
+ *
+ * Since [#682](https://github.com/Omega-JS-Stack/omega/issues/682) this is a
+ * BIND of `@omega.js/devkit/target-secrets`, exactly as web and the extension
+ * are: the same derive (the schema's desktop delivery set, #627) → collect (the
+ * COMPOSED target env, company ← brand ← target, files only, #678) → guard (the
+ * brand's DECLARED repo, never an inferred remote) → publish, over the ONE `gh`
+ * transport (values on stdin, never logged), with the same five loud skips. It
+ * used to run @octokit/rest + libsodium-wrappers itself on a GH_TOKEN PAT the
+ * consumer had to mint; `gh`'s own auth session is the credential now and the
+ * sealed-box crypto is the CLI's.
+ *
+ * What is desktop's OWN is the value resolver, the seam the shared publisher
+ * applies between collect and publish: a desktop secret can name a FILE
+ * (`CSC_LINK=config/certs/dev-id.p12`, `APPLE_API_KEY=.omega/secrets/key.p8` —
+ * target-root relative, falling back to the brand root), and CI needs the
+ * BYTES, so an existing file publishes as its base64 contents. The workflow
+ * decodes it back to a temp file at job start.
+ *
+ * Usage:
+ *   npx omega push-secrets                       # push every composed desktop key
+ *   npx omega push-secrets --only=GH_TOKEN,CSC_LINK
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('push-secrets');
+const { collectTargetSecrets, declaredBrandRepo: declaredRepoFor, publishTargetSecrets } = require('../vendor/devkit/target-secrets.js');
+const { findBrandRoot } = require('../vendor/config/index.js');
+
+const TARGET = 'desktop';
+
+module.exports = async function (options) {
+  options = options || {};
+
+  return publishEnvSecrets({
+    targetDir: process.cwd(),
+    logger,
+    only: options.only,
+  });
+};
+
+/**
+ * Desktop's value seam: base64 for a value that names an existing file, the
+ * value itself otherwise, and null for a key `--only` leaves out (the publisher
+ * drops a falsy value, the same way it drops an empty composed one).
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @param {string} [options.only] - Comma-separated key names to narrow to.
+ * @returns {function} `(value, key) => string|null`
+ */
+function fileValueResolver(options) {
+  const { targetDir } = options;
+  const only = options.only ? String(options.only).split(',').map((s) => s.trim()).filter(Boolean) : null;
+  const brandRoot = findBrandRoot(targetDir);
+
+  return (value, key) => {
+    if (only && !only.includes(key)) return null;
+    return fileContentsBase64(value, { targetDir, brandRoot }) || value;
+  };
+}
+
+// The base64 contents of the file `value` names, or null when it names none.
+// Heuristic: a path-shaped value (a separator, or a typical cert/key extension)
+// that resolves to a real file under the target root or the brand root. A
+// path-shaped value that exists nowhere is pushed as-is — it is a string.
+function fileContentsBase64(value, { targetDir, brandRoot }) {
+  const looksLikePath = /[/\\]/.test(value) || /\.(p12|pem|cer|p8|provisionprofile|crt|key|json)$/i.test(value);
+  if (!looksLikePath) return null;
+
+  const roots = path.isAbsolute(value) ? [''] : [targetDir, brandRoot].filter(Boolean);
+  for (const root of roots) {
+    const absolute = path.isAbsolute(value) ? value : path.join(root, value);
+    if (fs.existsSync(absolute) && fs.statSync(absolute).isFile()) {
+      return fs.readFileSync(absolute).toString('base64');
+    }
+  }
+
+  return null;
+}
+
+/**
+ * The publishable secrets: the schema's desktop delivery set, valued from the
+ * composed env with file-path values resolved to their base64 contents. An
+ * empty value never claims a key.
+ *
+ * @param {string} targetDir - The target root (its .env is the local layer).
+ * @param {object} [options]
+ * @param {string} [options.only] - Comma-separated key names to narrow to.
+ * @returns {Object<string, string>} key → value, ready to publish.
+ */
+function collectEnvSecrets(targetDir, options) {
+  return collectTargetSecrets({
+    targetDir,
+    target: TARGET,
+    resolveValue: fileValueResolver({ targetDir, only: (options || {}).only }),
+  });
+}
+
+/**
+ * The brand's OWN repo as `owner/name`, from the composed config. Null when the
+ * config declares nothing usable or doesn't load.
+ *
+ * @param {string} targetDir - The target root.
+ * @returns {string|null}
+ */
+function declaredBrandRepo(targetDir) {
+  return declaredRepoFor({ targetDir, target: TARGET });
+}
+
+/**
+ * The `omega deploy` precheck step: publish the target's composed values as
+ * repo Actions secrets.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @param {object} options.logger - `{ log, warn, error }`.
+ * @param {object} [options.env] - Env map (default: process.env).
+ * @param {string} [options.only] - Comma-separated key names to narrow to (`--only`).
+ * @param {function} [options.execFn] - Injectable `gh` exec (tests).
+ * @param {function} [options.gitExecFn] - Injectable `git` exec for remote discovery (tests).
+ * @returns {{ skipped: string }|{ published: string[], failed: Array<object> }}
+ */
+function publishEnvSecrets(options) {
+  options = options || {};
+
+  return publishTargetSecrets({
+    ...options,
+    target: TARGET,
+    resolveValue: fileValueResolver({ targetDir: options.targetDir, only: options.only }),
+  });
+}
+
+module.exports.collectEnvSecrets = collectEnvSecrets;
+module.exports.declaredBrandRepo = declaredBrandRepo;
+module.exports.fileValueResolver = fileValueResolver;
+module.exports.publishEnvSecrets = publishEnvSecrets;

package/dist/commands/release.js

@@ -0,0 +1,286 @@
+// release — trigger the GitHub Actions Build & Release workflow + stream logs locally.
+//
+// Replaces the old "do it from my laptop" release flow with "let CI do it, but make it
+// feel local." User runs `npm run release` (or `npx omega release`) and gets:
+//   1. A workflow_dispatch POST to GH Actions on the brand's repo (owner/repo from the
+//      config, and the workflow file the scaffold actually wrote: see dispatchTarget).
+//   2. A few seconds of waiting while GH spins up the run.
+//   3. Live polling of every job's logs at 5s intervals, printing NEW lines as they
+//      arrive (job-prefixed) so it looks like streaming.
+//   4. Everything teed to <root>/logs/ci.log with ANSI codes preserved on stdout
+//      and stripped from the file (matches the dev/build log convention).
+//   5. Exit 0 on success, 1 on any job failure.
+//
+// Why poll instead of stream? GH Actions doesn't expose live stdout — logs are only
+// fetchable AFTER each STEP completes. So "streaming" is a polite fiction: every 5s
+// we re-fetch each job's logs and diff against what we already printed.
+
+const path     = require('path');
+const fs       = require('fs');
+const jetpack  = require('fs-jetpack');
+
+const { getOctokit } = require('../utils/github.js');
+const { dispatchRepo } = require('../vendor/devkit/deploy.js');
+const Manager = new (require('../build.js'));
+
+const logger = Manager.logger('release');
+
+const POLL_INTERVAL_MS = 5000;
+
+module.exports = async function release(options = {}) {
+  const projectRoot = process.cwd();
+
+  if (!process.env.GH_TOKEN) {
+    throw new Error('GH_TOKEN not set in env. Set it in .env (or shell) so we can dispatch the workflow.');
+  }
+
+  // silent: true — suppress octokit's default console output for transient 404s
+  // (in-progress job logs return 404 until the step completes).
+  const octokit = getOctokit({ silent: true });
+  if (!octokit) {
+    throw new Error('Failed to create octokit (missing GH_TOKEN?).');
+  }
+
+  const { owner, repo, workflow: WORKFLOW_FILE } = dispatchTarget({ projectRoot, config: Manager.getConfig() });
+
+  // Discover ref (current branch or override via --ref).
+  const ref = options.ref || (await currentBranch(projectRoot)) || 'main';
+
+  // Optional --platforms / --platform flag forwarded as a workflow input. Accepts a
+  // single value ('windows') or comma-separated list ('mac,linux'). Special value
+  // 'all' or undefined builds every platform — same as the workflow's default. We
+  // only attach `inputs` when the user explicitly passed a flag, so older consumer
+  // workflows (without a `platforms` input declared) keep working unchanged.
+  const platforms = options.platforms || options.platform || null;
+
+  const dispatchArgs = { owner, repo, workflow_id: WORKFLOW_FILE, ref };
+  if (platforms) dispatchArgs.inputs = { platforms: String(platforms) };
+
+  const platformsLabel = platforms ? ` (platforms=${platforms})` : '';
+  logger.log(`Triggering ${owner}/${repo} workflow ${WORKFLOW_FILE} on ref=${ref}${platformsLabel}...`);
+
+  // 1. Mark a "before" timestamp so we can identify the new run we just dispatched.
+  const before = new Date();
+
+  // 2. Dispatch.
+  await octokit.rest.actions.createWorkflowDispatch(dispatchArgs);
+
+  // 3. Wait for the new run to appear (GH Actions takes a few seconds to register it).
+  const run = await waitForNewRun({ octokit, owner, repo, after: before, workflowFile: WORKFLOW_FILE });
+  if (!run) {
+    throw new Error('Workflow dispatch succeeded but no new run appeared after 60s. Check GitHub Actions UI.');
+  }
+
+  logger.log(`Run started: ${run.html_url}`);
+  require('../vendor/devkit/deploy-record.js').recordDeploy({ dir: projectRoot, target: 'desktop', detail: { method: 'release-dispatch' } });
+
+  // 4. Set up the CI log tee.
+  const logsDir = path.join(projectRoot, 'logs');
+  jetpack.dir(logsDir);
+  const ciLogPath = path.join(logsDir, 'ci.log');
+  // Truncate so each release run starts fresh.
+  fs.writeFileSync(ciLogPath, `# release run ${run.html_url}\n# started ${new Date().toISOString()}\n\n`);
+  const logFile = fs.createWriteStream(ciLogPath, { flags: 'a' });
+
+  // Spinner state. We tick every 250ms even between polls so the terminal feels alive.
+  // The spinner line uses \r to overwrite itself; before printing real content we clear
+  // the line, write content, then re-render the spinner. File output is unaffected.
+  const startedAt   = Date.now();
+  const isTty       = process.stdout.isTTY === true;
+  const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let spinnerFrame = 0;
+  let pollCount    = 0;
+  let latestState  = null;
+  let latestJobs   = [];
+
+  function clearSpinner() {
+    if (!isTty) return;
+    process.stdout.write('\r\x1b[2K');
+  }
+
+  function renderSpinner() {
+    if (!isTty || !latestState) return;
+    const frame   = SPINNER_FRAMES[spinnerFrame % SPINNER_FRAMES.length];
+    const elapsed = formatElapsed(Date.now() - startedAt);
+    const status  = `${latestState.status}${latestState.conclusion ? ` (${latestState.conclusion})` : ''}`;
+    const jobBits = latestJobs.map((j) => `${jobSymbol(j)} ${j.name}`).join(' ');
+    const line    = `${frame}  ${status} · ${elapsed} · ${pollCount} polls · ${jobBits}`;
+    // Truncate so we never wrap (which breaks the \r overwrite).
+    const cols    = process.stdout.columns || 120;
+    const safe    = line.length > cols - 1 ? line.slice(0, cols - 2) + '…' : line;
+    process.stdout.write(`\r${safe}`);
+  }
+
+  // Print line(s) to stdout AND tee to file. Clears spinner first; spinner re-renders next tick.
+  function print(line) {
+    clearSpinner();
+    process.stdout.write(line);
+    logFile.write(stripAnsi(line));
+  }
+
+  // Tick the spinner ~4 times/sec so it animates between polls.
+  const spinnerTimer = isTty ? setInterval(() => {
+    spinnerFrame += 1;
+    renderSpinner();
+  }, 250) : null;
+
+  // 5. Poll until completion. Track byte offsets per job so we only print new lines.
+  const printedByJob = new Map(); // jobId -> chars printed so far
+  let lastStatusLine = '';
+
+  try {
+    while (true) {
+      pollCount += 1;
+      const { data: state } = await octokit.rest.actions.getWorkflowRun({
+        owner, repo, run_id: run.id,
+      });
+
+      // Pull all jobs. Each job has steps; each step has a step-level status.
+      const { data: jobsResp } = await octokit.rest.actions.listJobsForWorkflowRun({
+        owner, repo, run_id: run.id, per_page: 100,
+      });
+      const jobs = jobsResp.jobs || [];
+      latestState = state;
+      latestJobs  = jobs;
+
+      // For each job, fetch its logs (only available once steps complete; for in-progress
+      // jobs, GH returns 404 or partial — we tolerate both).
+      for (const job of jobs) {
+        // Skip queued jobs entirely (no logs yet).
+        if (job.status === 'queued') continue;
+
+        let logsText = '';
+        try {
+          const { data } = await octokit.request('GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs', {
+            owner, repo, job_id: job.id,
+          });
+          // Octokit returns the raw text content here.
+          logsText = typeof data === 'string' ? data : Buffer.from(data || '').toString('utf8');
+        } catch (e) {
+          // 404 = logs not ready yet. Other errors we just skip until next tick.
+          continue;
+        }
+
+        const printed = printedByJob.get(job.id) || 0;
+        if (logsText.length > printed) {
+          const fresh = logsText.slice(printed);
+          // Prefix each line with the job name so interleaved output is readable.
+          const prefix = `[${job.name}] `;
+          for (const rawLine of fresh.split('\n')) {
+            if (!rawLine) continue;
+            print(`${prefix}${rawLine}\n`);
+          }
+          printedByJob.set(job.id, logsText.length);
+        }
+      }
+
+      // Print a one-line status banner if it changed (no spam — only on transition).
+      const banner = formatStatusBanner(state, jobs);
+      if (banner !== lastStatusLine) {
+        print(`\n${banner}\n`);
+        lastStatusLine = banner;
+      }
+
+      if (state.status === 'completed') {
+        clearSpinner();
+        logFile.end();
+        const success = state.conclusion === 'success';
+        const symbol  = success ? '✓' : '✗';
+        logger.log(`${symbol} Run ${state.conclusion} — ${state.html_url}`);
+        logger.log(`Logs: ${path.relative(projectRoot, ciLogPath)}`);
+        if (!success) {
+          process.exitCode = 1;
+          throw new Error(`Release run failed (conclusion=${state.conclusion}). See ${ciLogPath} or ${state.html_url}.`);
+        }
+        return;
+      }
+
+      await sleep(POLL_INTERVAL_MS);
+    }
+  } finally {
+    if (spinnerTimer) clearInterval(spinnerTimer);
+    clearSpinner();
+  }
+};
+
+// The CI dispatch address, from the config and the scaffold: the brand's APP
+// repo (`@omega.js/devkit/deploy`'s dispatchRepo, the one call web and the
+// extension deploy verbs make too) and the workflow file the target's
+// ensure-target pass actually wrote (composed as `desktop-build.yml` at the
+// brand root inside a monorepo, plain `build.yml` standalone:
+// `@omega.js/devkit/ci-workflows` owns that name for all four frameworks).
+// Never the git remote: a brand nested in another repo would dispatch on the
+// enclosing one, which for the playground is the framework monorepo itself.
+// Exported for tests.
+function dispatchTarget({ projectRoot, config }) {
+  const { composedWorkflowName } = require('../vendor/devkit/ci-workflows.js');
+  const { resolveSeedMode } = require('../vendor/config/index.js');
+  const { owner, repo } = dispatchRepo(config);
+
+  return {
+    owner,
+    repo,
+    workflow: composedWorkflowName({
+      targetDir: projectRoot,
+      brandRoot: resolveSeedMode(projectRoot).brandRoot,
+      workflow: 'build.yml',
+    }),
+  };
+}
+
+function formatElapsed(ms) {
+  const totalSec = Math.floor(ms / 1000);
+  const m = Math.floor(totalSec / 60);
+  const s = totalSec % 60;
+  return m > 0 ? `${m}m ${String(s).padStart(2, '0')}s` : `${s}s`;
+}
+
+function jobSymbol(j) {
+  if (j.status === 'completed') return j.conclusion === 'success' ? '✓' : '✗';
+  if (j.status === 'in_progress') return '…';
+  if (j.status === 'queued') return '·';
+  return '?';
+}
+
+async function waitForNewRun({ octokit, owner, repo, after, workflowFile }) {
+  const deadline = Date.now() + 60_000;
+  while (Date.now() < deadline) {
+    const { data } = await octokit.rest.actions.listWorkflowRuns({
+      owner, repo, workflow_id: workflowFile, per_page: 5, event: 'workflow_dispatch',
+    });
+    const runs = data.workflow_runs || [];
+    // The newest run created strictly after our dispatch timestamp.
+    const fresh = runs.find((r) => new Date(r.created_at).getTime() >= after.getTime() - 1000);
+    if (fresh) return fresh;
+    await sleep(2000);
+  }
+  return null;
+}
+
+function formatStatusBanner(run, jobs) {
+  const parts = jobs.map((j) => `${jobSymbol(j)} ${j.name}`);
+  return `── ${run.status}${run.conclusion ? ` (${run.conclusion})` : ''} ── ${parts.join('  |  ')}`;
+}
+
+async function currentBranch(projectRoot) {
+  try {
+    const { execute } = require('node-powertools');
+    const out = await execute('git rev-parse --abbrev-ref HEAD', { cwd: projectRoot, log: false });
+    return String(out || '').trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function stripAnsi(s) {
+  // Minimal ANSI stripper — handles CSI sequences (colors, cursor moves).
+  return String(s).replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+}
+
+// Exported for tests + `omega deploy`, which prints the exact dispatch this
+// sends before delegating here.
+module.exports.dispatchTarget = dispatchTarget;