@omega.js/manager 0.1.0

package/dist/commands/help.js

@@ -0,0 +1,48 @@
+/**
+ * `omega help` — and what a bare `omega` prints (#229). The manager's own
+ * help, not devkit's generated listing: a brand root is where a stranger
+ * lands, so the three verbs that matter come first, in the order a brand
+ * actually needs them, and every line says what the verb DOES.
+ */
+const chalk = require('chalk').default;
+
+// verb → what it does. Order is the story: reconcile, run, publish, then the
+// rest of the surface.
+const VERBS = [
+  ['omega manage', 'reconcile every service to config/omega.json5 — safe to rerun (`npm run manage`)'],
+  ['omega dev', 'boot the local stack: website + backend emulator (`npm start`)'],
+  ['omega deploy', 'publish each target, backend first — deliberate, never automatic (`npm run deploy`)'],
+  ['omega onboard', 'create a NEW brand monorepo from scratch (the wizard)'],
+  ['omega company', 'the company workspace: `init` scaffolds one, `adopt <brand>` stamps a brand into it'],
+  ['omega test', "run every target's test suites"],
+  ['omega build', 'build every target, backend first'],
+  ['omega clean', "wipe every target's build output"],
+  ['omega update', 'dependency-freshness fan-out over the targets'],
+  ['omega migrate', 'delete retired keys from config/omega.json5 (comments preserved)'],
+  ['omega pipeline', 'the live full-cycle test: manage → deploy → verify'],
+  ['omega devlog', "the manager's own development log"],
+  ['omega version', 'print the installed version'],
+];
+
+module.exports = async () => {
+  const pad = Math.max(...VERBS.map(([verb]) => verb.length));
+
+  console.log('');
+  console.log(chalk.bold('OMEGA — brand orchestration'));
+  console.log(chalk.dim('Usage: omega <command> [options]   (`omg` and `mgr` are the same bin)'));
+  console.log('');
+  for (const [verb, what] of VERBS) {
+    console.log(`  ${chalk.cyan(verb.padEnd(pad))}  ${what}`);
+  }
+  console.log('');
+  console.log(chalk.dim('  Common options: --service=<name>, --dry-run, --continue-on-error, --strict'));
+  console.log('');
+  console.log(chalk.bold('New here?'));
+  console.log(`  ${chalk.dim('1.')} ${chalk.cyan('npx omega onboard')}  ${chalk.dim('— scaffold a brand (skip if you already have one)')}`);
+  console.log(`  ${chalk.dim('2.')} ${chalk.cyan('npm install')}        ${chalk.dim('— every target gets its framework; the verbs scaffold on first run')}`);
+  console.log(`  ${chalk.dim('3.')} ${chalk.cyan('npm run manage')}     ${chalk.dim('— reconcile everything; it says what it still needs')}`);
+  console.log(`  ${chalk.dim('4.')} ${chalk.cyan('npm start')}          ${chalk.dim('— boot the local stack and build')}`);
+  console.log('');
+};
+
+module.exports.VERBS = VERBS;

package/dist/commands/manage.js

@@ -0,0 +1,53 @@
+/**
+ * `omega-manager manage` — context-sensitive on where it runs:
+ *   inside a brand monorepo    → run every service (or --service=<name>)
+ *                                against that brand
+ *   inside a company workspace → run the same per-brand manage for every
+ *                                discovered brand (--brand=<id[,id]> filters,
+ *                                --parallel runs children concurrently)
+ *
+ * Sets process.exitCode = 1 when any service errored so CI and scripts can
+ * gate on it.
+ */
+const path = require('node:path');
+const attachLogFile = require('../vendor/devkit/attach-log-file.js');
+const { runManage } = require('../manage.js');
+const { runCompany } = require('../company.js');
+const { resolveManageRoot, filterChildArgs } = require('../lib/company.js');
+
+module.exports = async (options) => {
+  const resolved = resolveManageRoot(process.cwd());
+
+  // Tee the whole fan-out to <brandRoot>/logs/manage.log (#197) — one greppable
+  // record of the service walk. Outside a brand the verb errors out anyway, so
+  // cwd is the honest fallback.
+  attachLogFile(path.join(resolved?.root || process.cwd(), 'logs', 'manage.log'));
+
+  let report;
+  if (resolved?.isCompany) {
+    // Children get the user's argv minus the company-only flags
+    report = await runCompany(resolved.root, {
+      brand: options.brand,
+      parallel: options.parallel,
+      concurrency: options.concurrency,
+    }, filterChildArgs(process.argv.slice(2)));
+  } else {
+    report = await runManage(process.cwd(), {
+      service: options.service,
+      continueOnError: options.continueOnError,
+      dryRun: options.dryRun,
+      strict: options.strict,
+      verbose: options.verbose,
+      migration: options.migration,
+      execute: options.execute,
+      limit: options.limit,
+      ids: options.ids,
+      resetAssets: options.resetAssets,
+      force: options.force,
+    });
+  }
+
+  if (report.hasErrors) {
+    process.exitCode = 1;
+  }
+};

package/dist/commands/migrate.js

@@ -0,0 +1,76 @@
+/**
+ * `omega migrate` at a brand root — bring an already-converted omega.json5
+ * forward: delete every key `@omega.js/config`'s retired-keys table names,
+ * in place, comments and formatting preserved.
+ *
+ *   omega migrate            → remove the retired keys, one line each
+ *   omega migrate --dry-run  → print the same plan and write nothing
+ *
+ * There is no dual-read anywhere in OMEGA, so a retired key is a setting the
+ * brand still believes in and nothing reads — the validator says so loudly on
+ * every load. The UJM→omega converter drops them on its way through
+ * (@omega.js/web's `omega migrate`), but a brand ALREADY on omega.json5 had
+ * only that error and an edit by hand. Editing an AUTHORED omega.json5 is the
+ * manager's lane (#612), so the rule lives here.
+ *
+ * The file is read raw (JSON5, no merge): the retired key must be deleted
+ * where the brand WROTE it, and a merged view would name paths that exist in
+ * no file. Idempotent by construction — a key that isn't there is skipped, so
+ * a converged brand's rerun leaves the file byte-identical.
+ */
+const fs = require('node:fs');
+const chalk = require('chalk').default;
+const JSON5 = require('json5');
+
+const { findRetiredKeys, resolveConfigPath, removeConfigValues } = require('../vendor/config/index.js');
+const { resolveBrandRoot } = require('../lib/brand.js');
+
+module.exports = async (options = {}) => {
+  const brandRoot = resolveBrandRoot(process.cwd());
+  if (!brandRoot) {
+    console.error(chalk.red('✗ Not inside a brand monorepo (no config/omega.json5 up the tree) — run `omega migrate` at the brand root.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const configPath = resolveConfigPath(brandRoot);
+  let authored;
+
+  try {
+    authored = JSON5.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    console.error(chalk.red(`✗ ${configPath} does not parse — fix the syntax first: ${e.message}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  // One finding per key, in file order. The table can name the same path
+  // twice (a key that is both a retired NAME and a retired PATH); the file
+  // has one property to delete either way.
+  const findings = [];
+  for (const finding of findRetiredKeys(authored)) {
+    if (!findings.some((seen) => seen.path === finding.path)) findings.push(finding);
+  }
+
+  const dryRun = !!(options['dry-run'] || options.dryRun);
+
+  console.log(chalk.bold(`\nOMEGA migrate — ${configPath}`));
+
+  if (findings.length === 0) {
+    console.log(`  ${chalk.green('✓')} no retired keys — this config is current`);
+    return;
+  }
+
+  const report = removeConfigValues(brandRoot, findings.map((finding) => finding.path), { dryRun });
+
+  for (const finding of findings) {
+    const verb = dryRun ? chalk.dim('⊘ would remove') : `${chalk.green('✓')} removed`;
+    console.log(`  ${verb} ${chalk.cyan(finding.path)} ${chalk.dim(`→ ${finding.replacement}`)}`);
+    console.log(`      ${chalk.dim(finding.why)}`);
+  }
+
+  const count = report.removed.length;
+  console.log(dryRun
+    ? chalk.dim(`\n  ${count} retired key${count === 1 ? '' : 's'} would be removed — nothing written (dry run)`)
+    : chalk.dim(`\n  ${count} retired key${count === 1 ? '' : 's'} removed — move each setting to the block named above`));
+};

package/dist/commands/onboard.js

@@ -0,0 +1,31 @@
+/**
+ * `omega-manager onboard [id]` — create (or converge) a brand monorepo.
+ *
+ * Flags: --id/--name/--url/--description/--tagline/--contactName (plus the
+ * optional --contactImage/--contactUrl)/--targets=web,backend pre-answer the
+ * wizard (prompts only fill the gaps in a TTY; non-interactive runs derive
+ * the rest from the id — the contact person is never derived). --dry-run
+ * prints the file plan without writing or prompting; --manage/--no-manage
+ * forces the manage handoff instead of asking.
+ */
+const { runOnboard } = require('../onboard.js');
+
+module.exports = async (options) => {
+  const report = await runOnboard(process.cwd(), {
+    id: options.id ?? options._?.[1],
+    name: options.name,
+    url: options.url,
+    description: options.description,
+    tagline: options.tagline,
+    contactName: options.contactName,
+    contactImage: options.contactImage,
+    contactUrl: options.contactUrl,
+    targets: options.targets,
+    dryRun: options.dryRun,
+    manage: options.manage,
+  });
+
+  if (!report.valid || (report.manageExitCode != null && report.manageExitCode !== 0)) {
+    process.exitCode = 1;
+  }
+};

package/dist/commands/pipeline.js

@@ -0,0 +1,319 @@
+/**
+ * `omega-manager pipeline` — the brand's full-pipeline LIVE test (Ian:
+ * "automate running the manager CLI as the test — the playground exists
+ * to shit-test the full pipeline").
+ *
+ * Spawns the REAL manage cycle with stdin detached, so no prompt can ever
+ * fire (isInteractive() reads stdin's TTY) — every answer must already be
+ * seeded in its non-interactive home: omega.json5 (choices), the brand
+ * .env (secrets), the Google token cache (scopes), state (latches). Then
+ * asserts the machine-readable run record (.omega/runs/{ts}.json):
+ *
+ *  - Any service at status "error" fails the pipeline.
+ *  - CORE services (workspace, repo, edge, domain, firebase,
+ *    testing) must RUN green (success/warned) — a core skip means a
+ *    broken seed (missing token, unconfigured section) and fails.
+ *  - Everything else may succeed, warn, or skip; skips are listed with
+ *    reasons for visibility, not failure.
+ *  - `--require=a,b` promotes more services into the core set (tighten as
+ *    seeds land: --require=sendgrid,account,captcha).
+ *  - `--service=<name>` narrows the child run to one service; the
+ *    core-presence check only applies to full runs.
+ *  - `--dry-run` forwards to the child (plan-only pass, still asserted).
+ *  - `--deploy=web,backend,desktop,extension` runs the DEPLOY legs after
+ *    the service cycle (web = `omega deploy --direct` gh-pages push;
+ *    backend = a REAL functions deploy). Off by default; each leg lands in
+ *    the scorecard as `deploy:<target>` and an exit-nonzero leg fails the
+ *    pipeline. desktop/extension are PUBLISH legs (GH release flow / store
+ *    CI dispatch — both Ian-gated): without `--publish` they record as a
+ *    gated skip instead of running.
+ *  - After the deploy legs, the VERIFY sweep runs automatically for whatever
+ *    was deployed (web → site + domain + cloudflare), landing as
+ *    `verify:<name>` rows — a failed check fails the run exactly like a
+ *    failed deploy leg. `--verify` alone runs the sweep without deploying
+ *    (the post-hoc "is it still up?" pass); a dry run, a demo-* brand, and a
+ *    brand with no cloud project all record gated skips and never touch the
+ *    network (lib/verify-live.js).
+ *
+ * This spends real API calls and reconciles real infrastructure — run it
+ * on demand, SPARINGLY. It is deliberately NOT part of `npm test` or CI.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const chalk = require('chalk').default;
+const attachLogFile = require('../vendor/devkit/attach-log-file.js');
+
+const { resolveBrandRoot, loadBrand, discoverTargets } = require('../lib/brand.js');
+const { runVerifyLegs, VERIFY_LEGS } = require('../lib/verify-live.js');
+
+// deploy target → the command run in that target's dir (desktop/
+// extension targets carry no deploy script — their D13 verb is the local bin)
+const DEPLOY_LEGS = {
+  web: ['npm', 'run', 'deploy', '--', '--direct'],
+  backend: ['npm', 'run', 'deploy'],
+  desktop: ['npx', 'omega', 'deploy'],
+  extension: ['npx', 'omega', 'deploy'],
+};
+
+// Legs that PUBLISH (desktop → the GH release flow, extension → the store
+// CI workflow dispatch). Releases and Actions dispatches are Ian-gated, so
+// these run only with the explicit `--publish` flag — otherwise the leg
+// records a gated skip.
+const PUBLISH_LEGS = new Set(['desktop', 'extension']);
+
+// Services that must RUN green on a full pipeline pass — these are the
+// provisioning spine; a skip here means a seed is missing, not a choice.
+// search/campaigns/account/captcha graduated into the spine once
+// their seeds converged (cp116–120): a skip there is a regression now.
+const CORE_SERVICES = [
+  'workspace', 'repo', 'edge', 'domain', 'cloud', 'testing',
+  'search', 'campaigns', 'account', 'captcha',
+];
+
+const STATUS_ICONS = { success: chalk.green('✓'), warned: chalk.yellow('⚠'), skipped: chalk.dim('⊘'), error: chalk.red('✗') };
+
+/**
+ * Which targets the verify sweep covers: whatever was just deployed, or —
+ * with `--verify` and no deploy — every target that HAS a live surface (the
+ * post-hoc "is it still up?" check).
+ *
+ * @param {object} argv - Parsed CLI args.
+ * @param {string[]} deployTargets - Targets whose deploy legs just ran.
+ * @returns {string[]}
+ */
+function resolveVerifyTargets(argv, deployTargets) {
+  if (deployTargets.length > 0) {
+    return deployTargets;
+  }
+  return argv.verify ? Object.keys(VERIFY_LEGS) : [];
+}
+
+/**
+ * Judge one run record against the pipeline policy.
+ *
+ * @param {object} runRecord - Parsed .omega/runs/{ts}.json ({ services: [{ service, status, reason?, error? }] }).
+ * @param {object} [options] - { require: string[] (extra core services), scoped: boolean (single-service child run) }.
+ * @returns {{ pass: boolean, failures: string[], skips: string[], rows: object[] }}
+ */
+function evaluatePipeline(runRecord, options = {}) {
+  const services = runRecord?.services || [];
+  const core = new Set([...CORE_SERVICES, ...(options.require || [])]);
+  const failures = [];
+  const skips = [];
+  const rows = [];
+
+  const byName = new Map(services.map((entry) => [entry.service, entry]));
+
+  for (const entry of services) {
+    rows.push(entry);
+
+    if (entry.status === 'error') {
+      failures.push(`${entry.service}: error${entry.error ? ` — ${entry.error}` : ''}`);
+    } else if (entry.status === 'skipped') {
+      if (core.has(entry.service)) {
+        failures.push(`${entry.service}: CORE service skipped${entry.reason ? ` — ${entry.reason}` : ''} (seed missing)`);
+      } else {
+        skips.push(`${entry.service}${entry.reason ? ` — ${entry.reason}` : ''}`);
+      }
+    }
+  }
+
+  // Full runs must actually contain every core service
+  if (!options.scoped) {
+    for (const name of core) {
+      if (!byName.has(name)) {
+        failures.push(`${name}: CORE service missing from the run record`);
+      }
+    }
+  }
+
+  return { pass: failures.length === 0, failures, skips, rows };
+}
+
+/**
+ * Newest run record written at/after `since` for the brand.
+ *
+ * @param {string} brandRoot - Brand root directory.
+ * @param {number} since - ms timestamp; records older than this are ignored.
+ * @returns {{ file: string, record: object }|null}
+ */
+function findRunRecord(brandRoot, since) {
+  const runsDir = path.join(brandRoot, '.omega', 'runs');
+  if (!fs.existsSync(runsDir)) {
+    return null;
+  }
+
+  const candidates = fs.readdirSync(runsDir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => ({ name, mtime: fs.statSync(path.join(runsDir, name)).mtimeMs }))
+    .filter((entry) => entry.mtime >= since)
+    .sort((a, b) => b.mtime - a.mtime);
+
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  const file = path.join(runsDir, candidates[0].name);
+  return { file, record: JSON.parse(fs.readFileSync(file, 'utf8')) };
+}
+
+/**
+ * The manage child's argv: the VERB first (#229 — a bare CLI prints help and
+ * walks nothing, which would leave the pipeline with no run record), then the
+ * run flags the pipeline always imposes.
+ *
+ * @param {object} [argv] - The pipeline's own options.
+ * @returns {string[]} The child invocation's arguments.
+ */
+function buildChildArgs(argv = {}) {
+  const args = ['manage', '--continue-on-error'];
+
+  if (argv.service) {
+    args.push(`--service=${argv.service}`);
+  }
+  if (argv.dryRun || argv['dry-run']) {
+    args.push('--dry-run');
+  }
+
+  return args;
+}
+
+module.exports = async (argv = {}) => {
+  const brandRoot = resolveBrandRoot(process.cwd());
+  if (!brandRoot) {
+    console.error(chalk.red('✗ Not inside a brand (no config/omega.json5 found walking up)'));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Tee the run to <brandRoot>/logs/pipeline.log (#623) — the scorecard is the
+  // verdict worth keeping; the children spawn with stdio inherit, so each leg's
+  // own output stays in its own log.
+  attachLogFile(path.join(brandRoot, 'logs', 'pipeline.log'));
+
+  const requireExtra = String(argv.require || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const childArgs = buildChildArgs(argv);
+
+  console.log(chalk.bold('\n🧪 Pipeline — live full-cycle test (non-interactive by construction)\n'));
+  console.log(`  Brand:   ${chalk.cyan(brandRoot)}`);
+  console.log(`  Child:   omega ${childArgs.join(' ')}`);
+  console.log(`  Core:    ${[...CORE_SERVICES, ...requireExtra].join(', ')}\n`);
+
+  const started = Date.now();
+  // cli-run.js self-executes when spawned as main — spawning it directly
+  // deliberately bypasses the bin's dispatcher (#276): this child must run
+  // THIS manager, never re-dispatch on the child's cwd.
+  const bin = path.join(__dirname, '..', 'cli-run.js');
+
+  // Non-interactive by construction: stdin detached AND the explicit env
+  // switch (google-auth counts stdout-TTY as a watching human — the env
+  // beats it, so consent flows fail fast instead of opening browsers).
+  const exitCode = await new Promise((resolve) => {
+    const child = spawn(process.execPath, [bin, ...childArgs], {
+      cwd: brandRoot,
+      stdio: ['ignore', 'inherit', 'inherit'],
+      env: { ...process.env, OMEGA_NON_INTERACTIVE: '1' },
+    });
+    child.on('close', (code) => resolve(code ?? 1));
+  });
+
+  const found = findRunRecord(brandRoot, started);
+  if (!found) {
+    console.error(chalk.red(`\n✗ PIPELINE FAIL — no run record appeared in .omega/runs/ (child exit ${exitCode})`));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Deploy legs — spawned in the owning target's dir, same non-interactive
+  // construction; results join the record as deploy:<target> rows so the
+  // evaluator's any-error rule covers them
+  const deployTargets = String(argv.deploy || '').split(',').map((s) => s.trim()).filter(Boolean);
+  for (const target of deployTargets) {
+    const leg = DEPLOY_LEGS[target];
+    const entry = discoverTargets(brandRoot).find((item) => item.target === target);
+
+    if (!leg || !entry) {
+      found.record.services.push({
+        service: `deploy:${target}`,
+        status: 'error',
+        output: null,
+        error: leg ? `no ${target} dir in this brand` : `unknown deploy target (${Object.keys(DEPLOY_LEGS).join(', ')})`,
+      });
+      continue;
+    }
+
+    // Publish legs stay behind their own flag: running them means a GH
+    // release / store CI dispatch, and both are gated until Ian opens them.
+    if (PUBLISH_LEGS.has(target) && !argv.publish) {
+      console.log(chalk.yellow(`\n⊘ Deploy leg ${target}: publish leg gated — pass --publish to run it (releases/dispatches are gated)`));
+      found.record.services.push({
+        service: `deploy:${target}`,
+        status: 'skipped',
+        output: null,
+        error: null,
+        reason: 'publish leg gated — pass --publish (releases/dispatches are gated)',
+      });
+      continue;
+    }
+
+    console.log(chalk.bold(`\n🧪 Deploy leg: ${target} ${chalk.dim(`(${leg.join(' ')} in ${entry.dir})`)}`));
+    const legExit = await new Promise((resolve) => {
+      const child = spawn(leg[0], leg.slice(1), {
+        cwd: entry.path,
+        stdio: ['ignore', 'inherit', 'inherit'],
+        env: { ...process.env, OMEGA_NON_INTERACTIVE: '1' },
+      });
+      child.on('close', (code) => resolve(code ?? 1));
+    });
+
+    found.record.services.push({
+      service: `deploy:${target}`,
+      status: legExit === 0 ? 'success' : 'error',
+      output: null,
+      error: legExit === 0 ? null : `exit ${legExit}`,
+    });
+  }
+
+  // Verify sweep — the last mile: the deploy legs pushed, these prove the
+  // launch surface answers. Rows join the record as verify:<name> so a
+  // failed check fails the pipeline exactly like a failed deploy leg.
+  const verifyTargets = resolveVerifyTargets(argv, deployTargets).filter((target) => VERIFY_LEGS[target]);
+  if (verifyTargets.length > 0) {
+    const dryRun = Boolean(argv.dryRun || argv['dry-run']);
+    console.log(chalk.bold(`\n🧪 Verify sweep: ${verifyTargets.join(', ')}${dryRun ? chalk.dim(' (dry run — plan only)') : ''}`));
+    found.record.services.push(...await runVerifyLegs(verifyTargets, loadBrand(brandRoot).config, {}, { dryRun }));
+  }
+
+  const verdict = evaluatePipeline(found.record, { require: requireExtra, scoped: Boolean(argv.service) });
+
+  console.log(chalk.bold('\n🧪 Pipeline scorecard'));
+  console.log(`  ${chalk.dim(`record: ${path.basename(found.file)}`)}`);
+  for (const row of verdict.rows) {
+    const icon = STATUS_ICONS[row.status] || chalk.dim('·');
+    console.log(`  ${icon} ${row.service}${row.status === 'skipped' && row.reason ? chalk.dim(` — ${row.reason}`) : ''}`);
+  }
+
+  if (verdict.skips.length > 0) {
+    console.log(`\n  ${chalk.dim(`⊘ acceptable skips: ${verdict.skips.length} (listed above)`)}`);
+  }
+
+  if (verdict.pass) {
+    console.log(chalk.green.bold('\n✅ PIPELINE PASS\n'));
+    return;
+  }
+
+  console.log(chalk.red.bold('\n❌ PIPELINE FAIL'));
+  for (const failure of verdict.failures) {
+    console.log(`  ${chalk.red('✗')} ${failure}`);
+  }
+  console.log('');
+  process.exitCode = 1;
+};
+
+module.exports.evaluatePipeline = evaluatePipeline;
+module.exports.findRunRecord = findRunRecord;
+module.exports.resolveVerifyTargets = resolveVerifyTargets;
+module.exports.buildChildArgs = buildChildArgs;
+module.exports.CORE_SERVICES = CORE_SERVICES;
+module.exports.PUBLISH_LEGS = PUBLISH_LEGS;