@omega.js/manager 0.1.0

package/dist/lib/run-gates.js

@@ -0,0 +1,70 @@
+/**
+ * Run-mode gates — the standard "may this step do X?" checks and the
+ * standard step-asides when it can't.
+ *
+ * Three primitives every ensure-handler shares:
+ * - canPrompt(options) — interactive TTY and not a dry run: the only two
+ *   conditions that ever gate a prompt. Use it instead of hand-composing
+ *   isInteractive() with options.dryRun (three spellings of that compound
+ *   had drifted into the tree before this module existed).
+ * - dryRunPlan(message, result) — the canonical dry-run line
+ *   (`⊘ Dry run — would <message>`) with an optional pass-through return,
+ *   so the modal gate is one statement:
+ *   `if (options.dryRun) return dryRunPlan('create it', { output: … });`
+ *   Loop bodies call it bare and continue.
+ * - needsInteractiveSkip(key, action, note) — the warned step-aside return
+ *   carrying the #32 `needsInteractive` marker that the run summary
+ *   aggregates into its ⚑ section with a per-service rerun hint.
+ */
+const chalk = require('chalk').default;
+const { isInteractive } = require('../vendor/devkit/prompt.js');
+
+/**
+ * Whether a step may prompt: the input stream is a TTY and this is not a
+ * dry run.
+ *
+ * @param {object} [options] - The run options (may carry `dryRun`).
+ * @returns {boolean} True when prompts are allowed.
+ */
+function canPrompt(options) {
+  return isInteractive() && !options?.dryRun;
+}
+
+/**
+ * Print the canonical dry-run line and pass `result` back so the modal
+ * gate reads `return dryRunPlan('create 3 records', { output: … })`.
+ *
+ * @param {string} message - What the real run would do ("create list …").
+ * @param {*} [result] - Returned verbatim (a handler return, usually).
+ * @returns {*} The `result` argument.
+ */
+function dryRunPlan(message, result) {
+  console.log(`      ${chalk.dim(`⊘ Dry run — would ${message}`)}`);
+  return result;
+}
+
+/**
+ * The standard warned return for a step that needs a TTY (#32): `action`
+ * states what an interactive run would do — the run summary collects it
+ * into the ⚑ "needs an interactive run" section, and the `reason` names the
+ * step-aside in the summary's warned breakdown (#643).
+ *
+ * @param {string} key - The operation's output key (e.g. 'cloudMessaging').
+ * @param {string} action - What an interactive run would do.
+ * @param {string} [note] - Optional per-operation output note.
+ * @returns {object} A `{ status: 'warned', reason, output }` handler return.
+ */
+function needsInteractiveSkip(key, action, note) {
+  return {
+    status: 'warned',
+    reason: 'needs an interactive run',
+    output: {
+      [key]: {
+        ...(note ? { note } : {}),
+        needsInteractive: action,
+      },
+    },
+  };
+}
+
+module.exports = { canPrompt, dryRunPlan, needsInteractiveSkip };

package/dist/lib/run-output.js

@@ -0,0 +1,42 @@
+/**
+ * Per-run output — the ONLY thing a manage run writes into `.omega/`:
+ *
+ *   config/omega.json5      → every provisioned fact (ids, slugs, zones,
+ *                             confirmation flags), comment-preserving
+ *   .env                    → every secret the run resolves (never config —
+ *                             the loader hard-fails secret-shaped keys)
+ *   .omega/runs/{ts}.json   → this run's transient output (counts, status
+ *                             flags, errors), for post-mortem debugging
+ *
+ * The old third bucket — the durable cache of derived data `.omega/state.json`
+ * carried — is RETIRED ([#434](https://github.com/Omega-JS-Stack/omega/issues/434)):
+ * every fact it held either re-derives from the platform on each idempotent
+ * ensure, or has an authoritative home in config/.env. The FILE lives on as
+ * the per-machine RECORD home ([#479](https://github.com/Omega-JS-Stack/omega/issues/479))
+ * — deploy stamps under its `deploy` section, written by
+ * `@omega.js/devkit/deploy-record` and by nothing here. `.omega/` is
+ * gitignored (the workspace service ensures the entry).
+ */
+
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+
+/**
+ * Persist one run's transient output to .omega/runs/{timestamp}.json —
+ * failures, counts, and per-service flags for post-mortem debugging.
+ *
+ * @param {string} brandRoot - Brand-monorepo root
+ * @param {string} runTimestamp - Filesystem-safe ISO timestamp for this process
+ * @param {string} brandId - Brand ID
+ * @param {Array<{ service, status, output, error }>} services - Per-service results
+ */
+function writeRunOutput(brandRoot, runTimestamp, brandId, services) {
+  const runFile = join(brandRoot, '.omega', 'runs', `${runTimestamp}.json`);
+  jetpack.write(runFile, {
+    timestamp: new Date().toISOString(),
+    brandId,
+    services,
+  }, { jsonIndent: 2 });
+}
+
+module.exports = { writeRunOutput };

package/dist/lib/run-summary.js

@@ -0,0 +1,384 @@
+/**
+ * Run Summary — collects service results across all brands and prints a
+ * summary. Ported from omega-manager's src/lib/run-summary.js: same stats,
+ * per-brand breakdown, drilled-down details for update failures and testing
+ * warnings, and a copy-pasteable retry command.
+ *
+ * Created once in runManage(), accumulates across every service (and, in the
+ * future company mode, across brands). Always prints a summary at the end.
+ */
+
+const chalk = require('chalk').default;
+
+const { formatDuration } = require('./duration.js');
+const { stripLeadingVerb } = require('./argv.js');
+
+class RunSummary {
+  constructor() {
+    this.entries = [];
+    this.startTime = Date.now();
+    this.argv = process.argv.slice(2);
+  }
+
+  /**
+   * Record a service result
+   *
+   * @param {string} brandId - Brand ID
+   * @param {string} brandName - Brand display name
+   * @param {string} serviceName - Service that ran
+   * @param {Object} result - Result from runService() { status, error?, output? }
+   */
+  add(brandId, brandName, serviceName, result) {
+    this.entries.push({ brandId, brandName, serviceName, result });
+  }
+
+  /**
+   * Check if any service had errors
+   */
+  hasErrors() {
+    return this.entries.some((entry) => this._isError(entry));
+  }
+
+  /**
+   * Print full summary (always)
+   */
+  printSummary() {
+    const elapsed = formatDuration(Date.now() - this.startTime);
+    const hasErrors = this.hasErrors();
+
+    // Gather stats
+    const brandSet = new Set();
+    const serviceSet = new Set();
+    let successCount = 0;
+    let warnedCount = 0;
+    let errorCount = 0;
+    let skippedCount = 0;
+
+    for (const entry of this.entries) {
+      brandSet.add(entry.brandId);
+      serviceSet.add(entry.serviceName);
+
+      if (this._isError(entry)) {
+        errorCount++;
+      } else if (entry.result.status === 'skipped') {
+        skippedCount++;
+      } else if (entry.result.status === 'warned') {
+        warnedCount++;
+      } else {
+        successCount++;
+      }
+    }
+
+    // Header
+    const hasWarnings = warnedCount > 0;
+    const headerColor = hasErrors ? chalk.yellow : hasWarnings ? chalk.yellow : chalk.green;
+    const headerIcon = hasErrors ? '⚠' : hasWarnings ? '⚠' : '✅';
+    console.log('');
+    console.log(headerColor('━'.repeat(70)));
+    console.log(`  ${headerColor.bold(`${headerIcon} Summary`)}`);
+    console.log(headerColor('━'.repeat(70)));
+
+    // Stats
+    console.log('');
+    console.log(`  ${chalk.dim('Brands:')}    ${brandSet.size}`);
+    console.log(`  ${chalk.dim('Services:')}  ${serviceSet.size}`);
+    console.log(`  ${chalk.dim('Duration:')}  ${elapsed}`);
+    const passedTotal = successCount + warnedCount;
+    const resultParts = [
+      chalk.green(`${passedTotal} passed`),
+      errorCount > 0 ? chalk.red(`, ${errorCount} failed`) : chalk.dim(', 0 failed'),
+    ];
+    if (warnedCount > 0) {
+      resultParts.push(chalk.yellow(`, ${warnedCount} warned`));
+    }
+    if (skippedCount > 0) {
+      resultParts.push(chalk.dim(`, ${skippedCount} skipped`));
+    }
+    console.log(`  ${chalk.dim('Results:')}   ${resultParts.join('')}`);
+
+    // Per-brand breakdown
+    console.log('');
+    for (const brandId of brandSet) {
+      const brandEntries = this.entries.filter((e) => e.brandId === brandId);
+      const brandName = brandEntries[0].brandName;
+      const brandErrors = brandEntries.filter((e) => this._isError(e));
+      const brandWarnings = brandEntries.filter((e) => e.result.status === 'warned');
+
+      if (brandErrors.length > 0) {
+        console.log(`  ${chalk.red('✗')} ${chalk.bold(brandName)}`);
+
+        for (const entry of brandErrors) {
+          const details = this._getErrorDetails(entry.serviceName, entry.result);
+
+          for (const detail of details) {
+            console.log(`      ${detail}`);
+          }
+        }
+      } else if (brandWarnings.length > 0) {
+        console.log(`  ${chalk.yellow('⚠')} ${chalk.bold(brandName)}`);
+
+        for (const entry of brandWarnings) {
+          const details = this._getWarningDetails(entry.serviceName, entry.result);
+
+          for (const detail of details) {
+            console.log(`      ${detail}`);
+          }
+        }
+      } else {
+        console.log(`  ${chalk.green('✓')} ${chalk.bold(brandName)}`);
+      }
+    }
+
+    // Needs-interactive aggregate (#32): steps that stepped aside for lack
+    // of a TTY say so HERE, not just in scroll-back
+    const needsInteractive = this._getNeedsInteractive();
+    if (needsInteractive.length > 0) {
+      const multiBrand = brandSet.size > 1;
+      console.log('');
+      console.log(`  ${chalk.yellow('⚑')} Skipped — needs an interactive run:`);
+      for (const item of needsInteractive) {
+        const prefix = multiBrand ? `${item.brandName} · ` : '';
+        console.log(`      ${prefix}${chalk.bold(`${item.serviceName}/${item.operation}`)}: ${item.what}`);
+      }
+      for (const serviceName of [...new Set(needsInteractive.map((item) => item.serviceName))]) {
+        console.log(`      ${chalk.dim(`→ npm run manage -- --service=${serviceName}   (from the brand root)`)}`);
+      }
+    }
+
+    // Missing-secrets aggregate (cp114): services that skipped for lack of
+    // an env var name the exact keys HERE — and an interactive rerun asks
+    // for them and saves them to the brand .env
+    const missingEnv = this._getMissingEnv();
+    if (missingEnv.length > 0) {
+      const multiBrand = brandSet.size > 1;
+      console.log('');
+      console.log(`  ${chalk.yellow('🔑')} Missing secrets — add to the brand .env, or rerun interactively to paste them:`);
+      for (const item of missingEnv) {
+        const prefix = multiBrand ? `${item.brandName} · ` : '';
+        console.log(`      ${prefix}${chalk.bold(item.serviceName)}: ${item.vars.join(', ')}`);
+      }
+      for (const serviceName of [...new Set(missingEnv.map((item) => item.serviceName))]) {
+        console.log(`      ${chalk.dim(`→ npm run manage -- --service=${serviceName}   (from the brand root)`)}`);
+      }
+    }
+
+    // Retry command
+    if (hasErrors) {
+      console.log('');
+      console.log(`  ${chalk.red('✗')} Retry:`);
+      console.log(`  ${chalk.dim(this._buildRetryCommand())}`);
+    }
+
+    console.log('');
+    console.log(headerColor('━'.repeat(70)));
+  }
+
+  /**
+   * Build a retry command from the original argv. `npm run manage` is the blessed
+   * form — npx can be rerouted by shell wrappers (npu) that pipe stdio and
+   * kill interactivity.
+   */
+  _buildRetryCommand() {
+    // The `manage` script IS the verb (#229), so the leading subcommand must
+    // not ride along — `npm run manage -- manage --service=x` would run
+    // `omega manage manage`.
+    const args = stripLeadingVerb(this.argv).join(' ').trim();
+    return args ? `npm run manage -- ${args}` : 'npm run manage';
+  }
+
+  /**
+   * Collect missing-secret skips (cp114): service results carry
+   * `missingEnv: ['CLOUDFLARE_TOKEN', …]` when setup skipped for absent
+   * env vars (the setup contract, lib/service-input.js).
+   */
+  _getMissingEnv() {
+    const items = [];
+
+    for (const entry of this.entries) {
+      const vars = entry.result?.missingEnv;
+      if (Array.isArray(vars) && vars.length > 0) {
+        items.push({
+          brandId: entry.brandId,
+          brandName: entry.brandName,
+          serviceName: entry.serviceName,
+          vars,
+        });
+      }
+    }
+
+    return items;
+  }
+
+  /**
+   * Collect needs-interactive markers (#32): any handler output sub-object
+   * may carry `needsInteractive: '<what an interactive run would do>'` —
+   * the convention for steps that step aside without a TTY.
+   */
+  _getNeedsInteractive() {
+    const items = [];
+
+    for (const entry of this.entries) {
+      const output = entry.result?.output;
+      if (!output || typeof output !== 'object') {
+        continue;
+      }
+
+      for (const [operation, data] of Object.entries(output)) {
+        if (data && typeof data === 'object' && typeof data.needsInteractive === 'string') {
+          items.push({
+            brandId: entry.brandId,
+            brandName: entry.brandName,
+            serviceName: entry.serviceName,
+            operation,
+            what: data.needsInteractive,
+          });
+        }
+      }
+    }
+
+    return items;
+  }
+
+  /**
+   * Check if an entry represents an error
+   */
+  _isError(entry) {
+    const { result, serviceName } = entry;
+
+    // Explicit error status
+    if (result.status === 'error') {
+      return true;
+    }
+
+    // Update service: check for failed targets even when status is 'success'
+    if (serviceName === 'update' && result.output?.results) {
+      return this._hasFailedTargets(result.output.results);
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if update results contain failed targets
+   */
+  _hasFailedTargets(results) {
+    for (const target of Object.keys(results)) {
+      const steps = results[target].steps || [];
+
+      if (steps.some((s) => s.success === false)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Get human-readable error details for a service result
+   */
+  _getErrorDetails(serviceName, result) {
+    const details = [];
+
+    // Update service: show per-target, per-phase failures
+    if (serviceName === 'update' && result.output?.results) {
+      const failedTargets = this._getFailedTargets(result.output.results);
+
+      if (failedTargets.length > 0) {
+        details.push(`${chalk.red(serviceName)}:`);
+
+        for (const { target, phase, error } of failedTargets) {
+          const errorMsg = error ? chalk.dim(`: ${error}`) : '';
+          details.push(`  ${chalk.bold(target)} → ${chalk.red(`${phase} failed`)}${errorMsg}`);
+        }
+      }
+
+      // Also show top-level error if present
+      if (result.status === 'error' && result.error && failedTargets.length === 0) {
+        details.push(`${chalk.red(serviceName)}: ${result.error}`);
+      }
+
+      return details;
+    }
+
+    // Testing service: show per-check failures. Stays ahead of the generic
+    // failed renderer below — the per-check messages live here, while the
+    // runner-level entry for the same run is names-only.
+    if (result.output?.results?.failed?.length) {
+      details.push(`${chalk.red(serviceName)}:`);
+      for (const { name, error } of result.output.results.failed) {
+        const msg = error ? chalk.dim(`: ${error}`) : '';
+        details.push(`  ${chalk.bold(name)}${msg}`);
+      }
+
+      return details;
+    }
+
+    // Every recorded failed operation, by name (#643): the service runner
+    // records `{ operation, reason }` on `result.failed`, so a service that
+    // ran past its first failure names each one instead of collapsing into a
+    // single message.
+    if (result.failed?.length) {
+      details.push(`${chalk.red(serviceName)}:`);
+      for (const { operation, reason } of result.failed) {
+        const msg = reason ? chalk.dim(`: ${reason}`) : '';
+        details.push(`  ${chalk.bold(operation)}${msg}`);
+      }
+
+      return details;
+    }
+
+    // Generic service error
+    details.push(`${chalk.red(serviceName)}: ${result.error || 'failed'}`);
+    return details;
+  }
+
+  /**
+   * Get human-readable warning details for a service result
+   *
+   * ONE generic renderer (#643): the service runner records every warned
+   * operation as `{ operation, reason }` on `result.warned`, so the breakdown
+   * names what warned and why — no per-service special cases, and no service
+   * left saying "some operations had issues".
+   */
+  _getWarningDetails(serviceName, result) {
+    const details = [];
+
+    if (result.warned?.length) {
+      details.push(`${chalk.yellow(serviceName)}:`);
+      for (const { operation, reason } of result.warned) {
+        const msg = reason ? chalk.dim(`: ${reason}`) : '';
+        details.push(`  ${chalk.bold(operation)}${msg}`);
+      }
+
+      return details;
+    }
+
+    details.push(`${chalk.yellow(serviceName)}: some operations had issues`);
+    return details;
+  }
+
+  /**
+   * Extract failed targets from update results
+   */
+  _getFailedTargets(results) {
+    const failed = [];
+
+    for (const [target, targetResult] of Object.entries(results)) {
+      const steps = targetResult.steps || [];
+
+      for (const step of steps) {
+        if (step.success === false) {
+          failed.push({
+            target,
+            phase: step.phase || 'unknown',
+            error: step.error || null,
+          });
+        }
+      }
+    }
+
+    return failed;
+  }
+}
+
+module.exports = { RunSummary };