@omega.js/manager 0.1.0

package/dist/lib/config-flow.js

@@ -0,0 +1,350 @@
+/**
+ * Config-landing interactive flows — omega-manager's schema-prompter engine
+ * reshaped for the new world. When a required config value is missing and
+ * the session is interactive (and not a dry run), offer the setup flow —
+ * select from an API list (brand matches sorted first, create-new via API
+ * handler or browser) or paste back an id from a dashboard — and land the
+ * result in omega.json5 via the comment-preserving writeback. The in-memory
+ * brandConfig is patched too, so the rest of the run sees the value.
+ *
+ * Non-interactive or dry-run sessions get null back and each service keeps
+ * its clean skip; every flow leads with a uniform Yes / Skip / Disable
+ * gate ("Disable" writes `<section>: false` so the service stops asking).
+ *
+ * Tri-state standard (#33, Ian's call): a missing/null value means ASK
+ * (this module), `false` at the path — or any ancestor section — means the
+ * user OPTED OUT (silent skip, never prompt or warn again), and any other
+ * value means USE IT. Every flow can land the `false`: the gate's Disable
+ * writes it (disablePath defaults to the value's own path), and selection
+ * flows may offer an inline opt-out choice via `spec.optOut`.
+ */
+const chalk = require('chalk').default;
+const { input, select } = require('../vendor/devkit/prompt.js');
+const { openBrowser } = require('../vendor/devkit/flows.js');
+const { writeBrandConfig } = require('./config-write.js');
+const { canPrompt } = require('./run-gates.js');
+
+const CREATE_NEW = '__CREATE_NEW__';
+const OPT_OUT = '__OPT_OUT__';
+
+/**
+ * Read a dot-notation path for the tri-state standard: `false` at the path
+ * or any ancestor section means opted out; missing segments are undefined.
+ */
+function readTriState(obj, path) {
+  let node = obj;
+  for (const key of path.split('.')) {
+    if (node === false) {
+      return { optedOut: true, value: undefined };
+    }
+    if (node == null) {
+      return { optedOut: false, value: undefined };
+    }
+    node = node[key];
+  }
+  return { optedOut: node === false, value: node === false ? undefined : node };
+}
+
+/**
+ * Set a dot-notation path on an object, creating intermediate objects.
+ */
+function setAtPath(obj, path, value) {
+  const keys = path.split('.');
+  const last = keys.pop();
+  let node = obj;
+  for (const key of keys) {
+    if (typeof node[key] !== 'object' || node[key] === null) {
+      node[key] = {};
+    }
+    node = node[key];
+  }
+  node[last] = value;
+}
+
+/**
+ * Whether an item's display name fuzzily matches the brand (id, name, or
+ * domain, ignoring case/spaces/hyphens) — those sort to the top of lists.
+ */
+function matchesBrand(itemName, brand) {
+  if (!brand) {
+    return false;
+  }
+
+  const brandId = (brand.id || '').toLowerCase().replace(/-/g, '');
+  const brandName = (brand.name || '').toLowerCase().replace(/\s+/g, '');
+  const brandUrl = (brand.url || '').toLowerCase().replace(/^https?:\/\//, '').replace(/\./g, '');
+  const name = itemName.toLowerCase().replace(/[\s-]/g, '');
+
+  return Boolean(
+    (brandId && (name.includes(brandId) || brandId.includes(name)))
+    || (brandName && (name.includes(brandName) || brandName.includes(name)))
+    || (brandUrl && name.includes(brandUrl)),
+  );
+}
+
+/**
+ * Build a select() choices array from API items: "create new" first, then
+ * the default item (cursor lands there), then brand matches, then the rest
+ * alphabetically.
+ *
+ * @param {Array} items - Raw API items
+ * @param {Object} brand - brandConfig.brand (for match sorting)
+ * @param {Object} spec
+ * @param {Function} [spec.getName] - item → display name
+ * @param {Function} [spec.getValue] - item → choice value
+ * @param {*} [spec.defaultValue] - Value whose item sorts to the top
+ * @param {string} [spec.createNewLabel] - Adds a "+ Create new …" choice
+ * @returns {{ choices: Array, defaultValue: * }} - defaultValue resolved for select()
+ */
+function sortChoicesForBrand(items, brand, spec = {}) {
+  const { getName, getValue, defaultValue, createNewLabel } = spec;
+  const nameOf = (item) => (getName ? getName(item) : String(item));
+  const valueOf = (item) => (getValue ? getValue(item) : item);
+  const isDefault = (item) => defaultValue !== undefined && defaultValue !== null && valueOf(item) === defaultValue;
+
+  const sorted = [...items].sort((a, b) => {
+    const aMatches = matchesBrand(nameOf(a), brand);
+    const bMatches = matchesBrand(nameOf(b), brand);
+    if (aMatches !== bMatches) {
+      return aMatches ? -1 : 1;
+    }
+    if (isDefault(a) !== isDefault(b)) {
+      return isDefault(a) ? -1 : 1;
+    }
+    return nameOf(a).toLowerCase().localeCompare(nameOf(b).toLowerCase());
+  });
+
+  const defaultItem = sorted.find(isDefault) || null;
+  const choices = [];
+
+  if (createNewLabel) {
+    choices.push({ name: `+ Create new ${createNewLabel}`, value: CREATE_NEW });
+  }
+  if (defaultItem) {
+    choices.push({ name: nameOf(defaultItem), value: valueOf(defaultItem) });
+  }
+  for (const item of sorted) {
+    if (item === defaultItem) {
+      continue;
+    }
+    choices.push({ name: nameOf(item), value: valueOf(item) });
+  }
+
+  // Cursor: the default item when given, else the best real item (the
+  // brand match after sorting) — never "+ Create new" by accident
+  const cursorItem = defaultItem || sorted[0] || null;
+
+  return { choices, defaultValue: cursorItem ? valueOf(cursorItem) : undefined };
+}
+
+/**
+ * Land a value: write it into omega.json5 (comment-preserving) and patch
+ * the in-memory brandConfig so the rest of the run sees it.
+ */
+function landValue(context, path, value) {
+  writeBrandConfig(context, { [path]: value });
+  setAtPath(context.brandConfig, path, value);
+}
+
+/**
+ * The uniform Yes / Skip / Disable gate every config-landing flow leads
+ * with — the ONE place that wording lives, so a flow built by hand
+ * (the pixel provisioning's token ask) and the shared setup contract
+ * (lib/service-input.js, #608) open exactly like resolveConfigValue.
+ * "Disable" lands `false` at disablePath (the tri-state opt-out) and says
+ * where to delete it.
+ *
+ * @param {Object} context - Service context
+ * @param {Object} spec
+ * @param {string} spec.label - Human name ("Meta Pixel", "GA4 property")
+ * @param {string[]} [spec.instructions] - Numbered guidance lines
+ * @param {string} spec.disablePath - Where Disable writes `false`
+ * @returns {Promise<'yes'|'skip'|'disable'>} - The chosen outcome; callers that
+ *   only proceed on Yes compare against 'yes', the ones that report WHICH
+ *   step-aside happened (#608) read the other two.
+ */
+async function confirmSetup(context, spec) {
+  const { label, instructions, disablePath } = spec;
+  const brandName = context.brandConfig.brand?.name || context.brandId;
+
+  console.log(`    ${chalk.yellow('!')} ${label} not configured for ${chalk.cyan(brandName)}`);
+  for (const line of instructions || []) {
+    console.log(`        ${line}`);
+  }
+
+  const action = await select({
+    message: 'Set up now?',
+    choices: [
+      { name: 'Yes', value: 'yes' },
+      { name: 'Skip for now', value: 'skip' },
+      { name: 'Disable (stop prompting)', value: 'disable' },
+    ],
+    default: 'yes',
+  });
+
+  if (action === 'disable') {
+    landValue(context, disablePath, false);
+    console.log(`    ${chalk.yellow('!')} ${label} disabled in omega.json5 (${disablePath}: false — delete the line to be asked again)`);
+  }
+
+  return action;
+}
+
+/**
+ * Selection flow: list items from the API, pick one (or create new via
+ * API handler / browser + refresh). Returns the picked value or null.
+ */
+async function runSelection(context, spec) {
+  const { label, choices: listItems, getName, getValue, defaultValue, createNew } = spec;
+
+  const items = await listItems(context);
+  const built = sortChoicesForBrand(items, context.brandConfig.brand, {
+    getName,
+    getValue,
+    defaultValue,
+    createNewLabel: createNew ? (createNew.label || label) : null,
+  });
+
+  // Inline opt-out (tri-state): picking it lands `false` — resolveConfigValue
+  // handles the landing so this stays a pure selection
+  if (spec.optOut) {
+    built.choices.push({ name: spec.optOut.label || `No ${label} — don't ask again`, value: OPT_OUT });
+  }
+
+  const picked = await select({
+    message: spec.message || `Select ${label}:`,
+    choices: built.choices,
+    default: built.defaultValue,
+  });
+
+  if (picked !== CREATE_NEW) {
+    return picked;
+  }
+
+  // Create new via API handler
+  if (createNew.handler) {
+    console.log(`    ${chalk.dim('→')} Creating new ${createNew.label || label}...`);
+    const value = await createNew.handler(context);
+    console.log(`    ${chalk.green('✓')} Created`);
+    return value;
+  }
+
+  // Create new via browser, then re-list or paste back
+  console.log(`    ${chalk.dim('→')} Opening browser to create a new ${createNew.label || label}...`);
+  console.log(`    ${chalk.dim('→')} URL: ${chalk.cyan(createNew.url)}`);
+  await openBrowser(createNew.url);
+  await input({ message: 'Press ENTER when done...' });
+
+  if (createNew.refreshChoices) {
+    console.log(`    ${chalk.dim('→')} Refreshing list...`);
+    const fresh = await listItems(context);
+    const rebuilt = sortChoicesForBrand(fresh, context.brandConfig.brand, { getName, getValue, defaultValue });
+    return select({
+      message: `Select the new ${createNew.label || label}:`,
+      choices: rebuilt.choices,
+      default: rebuilt.defaultValue,
+    });
+  }
+
+  return input({ message: `Enter the ${createNew.label || label} you just created:` });
+}
+
+/**
+ * Entry flow: open the dashboard and take a pasted-back value.
+ */
+async function runEntry(context, spec) {
+  const { url, message, validate } = spec.entry;
+
+  if (url) {
+    await openBrowser(url);
+  }
+
+  const value = await input({
+    message,
+    validate: validate || ((val) => (val?.trim() ? true : 'Required')),
+  });
+
+  return value.trim();
+}
+
+/**
+ * Resolve a required config value interactively and land it in omega.json5.
+ *
+ * Tri-state (#33): returns the value already in config if present
+ * (idempotent); returns null WITHOUT prompting when the value — or any
+ * ancestor section — is `false` (the user opted out); returns null without
+ * prompting when non-interactive or dry-run, and when the user skips or
+ * disables — callers keep their existing clean-skip handling.
+ *
+ * @param {Object} context - Service context (brandConfig, brandRoot, options)
+ * @param {Object} spec
+ * @param {string} spec.path - omega.json5 dot path the value lands at
+ * @param {string} spec.label - Human name ("GA4 property", "Chatsy chat agent")
+ * @param {string[]} [spec.instructions] - Numbered guidance lines shown before the gate
+ * @param {string} [spec.message] - Selection prompt (default "Select <label>:")
+ * @param {Function} [spec.choices] - async (context) → items (selection mode)
+ * @param {Function} [spec.getName] - item → display name
+ * @param {Function} [spec.getValue] - item → value
+ * @param {*} [spec.defaultValue] - Sorts its item to the top of the list
+ * @param {Object} [spec.createNew] - { label, handler } (API) or { label, url, refreshChoices } (browser)
+ * @param {Object} [spec.entry] - { url, message, validate } (paste-back mode)
+ * @param {Object} [spec.optOut] - { label } inline selection choice → lands `false`
+ * @param {string} [spec.disablePath] - Where Disable/opt-out writes `false`
+ *   (defaults to spec.path — section paths let one opt-out cover a service)
+ * @param {boolean} [spec.gate] - false = skip the Yes/Skip/Disable gate (a
+ *   chained value whose flow the user already said Yes to)
+ * @returns {Promise<*>} - The landed value, or null
+ */
+async function resolveConfigValue(context, spec) {
+  const { path, label } = spec;
+  const disablePath = spec.disablePath || path;
+
+  const { optedOut, value: existing } = readTriState(context.brandConfig, path);
+  if (optedOut) {
+    return null;
+  }
+  if (existing !== undefined && existing !== null) {
+    return existing;
+  }
+
+  if (!canPrompt(context.options)) {
+    return null;
+  }
+
+  if (spec.gate !== false) {
+    const action = await confirmSetup(context, {
+      label,
+      instructions: spec.instructions,
+      disablePath,
+    });
+    if (action !== 'yes') {
+      return null;
+    }
+  }
+
+  const value = spec.choices
+    ? await runSelection(context, spec)
+    : await runEntry(context, spec);
+
+  if (value === OPT_OUT) {
+    landValue(context, disablePath, false);
+    console.log(`    ${chalk.yellow('!')} ${label}: opted out (${disablePath}: false — delete the line to be asked again)`);
+    return null;
+  }
+
+  if (value === undefined || value === null || value === '') {
+    return null;
+  }
+
+  landValue(context, path, value);
+  return value;
+}
+
+module.exports = {
+  resolveConfigValue,
+  confirmSetup,
+  readTriState,
+  sortChoicesForBrand,
+  setAtPath,
+  landValue,
+};

package/dist/lib/config-write.js

@@ -0,0 +1,41 @@
+/**
+ * Brand-config writeback — the manager side of @omega.js/config's
+ * comment-preserving editor. Services resolve IDs against external APIs
+ * (SendGrid list, Beehiiv publication, payment product IDs, the Firebase SDK
+ * config) and land them in config/omega.json5, their one authoritative home;
+ * state keeps the resolved values as a cache/self-heal layer. This helper
+ * gives every service the same dry-run gate and logging.
+ */
+
+const chalk = require('chalk').default;
+const { writeConfigValues } = require('../vendor/config/index.js');
+const { dryRunPlan } = require('./run-gates.js');
+
+/**
+ * Write resolved values into the brand's omega.json5. Already-equal values
+ * are skipped by the editor, so calling this on every run is idempotent and
+ * reruns leave the file byte-identical. Dry-run reports what would land and
+ * touches nothing.
+ *
+ * @param {Object} context - Handler context ({ brandRoot, options }).
+ * @param {Object<string, *>} edits - Dot-path → value (see @omega.js/config
+ *   edit paths: dots, numeric indexes, and [key=value] array matchers).
+ * @returns {string[]} The paths actually written (empty on dry-run or no-op).
+ */
+function writeBrandConfig(context, edits) {
+  const dryRun = context.options?.dryRun || false;
+  const report = writeConfigValues(context.brandRoot, edits, { dryRun });
+
+  if (report.applied.length === 0) {
+    return [];
+  }
+
+  if (dryRun) {
+    return dryRunPlan(`write ${report.applied.join(', ')} to omega.json5`, []);
+  }
+
+  console.log(`      ${chalk.green('✓')} omega.json5 ← ${chalk.cyan(report.applied.join(', '))}`);
+  return report.applied;
+}
+
+module.exports = { writeBrandConfig };

package/dist/lib/custom-target.js

@@ -0,0 +1,75 @@
+/**
+ * Custom targets (#603) — the ONE home for a target the framework does not
+ * own: a Render API, a worker, a script. It is declared like any other target
+ * (`targets.<name>: { type: 'custom' }`, or the array form for instances), and
+ * everything it can DO comes from its own package.json scripts:
+ *
+ *   start · build · test · deploy · clean
+ *
+ * The manager runs each verb through `npm run <verb>` when the script is
+ * there and SKIPS IT LOUDLY when it is not — a verb that quietly did nothing
+ * is indistinguishable from one that worked. Nothing is inferred, defaulted,
+ * or synthesized: no script, no verb. This module holds only what a custom
+ * target IS (its names, its dirs, the scripts it declares); the run itself has
+ * one home for every target type, `framework-bin.js`'s `resolveTargetRun`.
+ *
+ * What a custom target does NOT get is every framework service op — there is
+ * no framework to reconcile. Discovery leaves `entry.target` null, so the
+ * `filter((entry) => entry.target)` every service already applies skips them
+ * by construction; the ONE deliberate exception reads `entry.custom`: the
+ * workspace service recognizes the dir (agent docs, settings, the structure
+ * check) instead of warning it unmapped. Nothing is composed into its own .env
+ * file (#678); it INHERITS the brand keys instead — manage.js loads the env
+ * chain into process.env before it spawns anything, so a custom target started
+ * by `omega dev`/`omega deploy` has them. A standalone run inside the target
+ * dir does not: there is no @omega.js/config in there to walk the cascade.
+ */
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const { isCustomTargetEntry, normalizeTargetInstances, instanceTargetDir } = require('../vendor/config/index.js');
+
+/**
+ * The custom target NAMES a brand config declares.
+ *
+ * @param {object} brandConfig - The merged brand config.
+ * @returns {string[]} Target names, in config order.
+ */
+function customTargetNames(brandConfig) {
+  const targets = brandConfig?.targets;
+  if (!targets || typeof targets !== 'object') {
+    return [];
+  }
+
+  return Object.keys(targets).filter((name) => isCustomTargetEntry(targets[name]));
+}
+
+/**
+ * The target DIRS those declarations expect under targets/ — the shared
+ * multi-instance mapping (`main` → the bare dir, any other id → `<name>-<id>`).
+ *
+ * @param {object} brandConfig - The merged brand config.
+ * @returns {string[]} Directory basenames.
+ */
+function customTargetDirs(brandConfig) {
+  return customTargetNames(brandConfig).flatMap((name) => normalizeTargetInstances(brandConfig.targets[name])
+    .map((instance) => instanceTargetDir(name, instance.id)));
+}
+
+/**
+ * A target dir's package.json scripts — the whole verb surface of a custom
+ * target. An unreadable or absent package.json declares nothing.
+ *
+ * @param {string} targetPath - Absolute path to the target dir.
+ * @returns {Object<string, string>} Script name → command.
+ */
+function targetScripts(targetPath) {
+  const pkg = jetpack.read(path.join(targetPath, 'package.json'), 'json');
+  return (pkg && typeof pkg.scripts === 'object' && pkg.scripts) || {};
+}
+
+module.exports = {
+  customTargetNames,
+  customTargetDirs,
+  targetScripts,
+};

package/dist/lib/domain-utils.js

@@ -0,0 +1,19 @@
+/**
+ * Domain helpers — apex/subdomain resolution via the public suffix list
+ * (omega-manager's src/lib/domain-utils.js, trimmed to what the manager uses).
+ */
+const psl = require('psl');
+
+/**
+ * Get the apex (registrable) domain for any domain.
+ * e.g. 'api.mybrand.com' → 'mybrand.com', 'sub.example.co.uk' → 'example.co.uk'
+ *
+ * @param {string} domain - Full domain (no protocol)
+ * @returns {string} Apex domain
+ */
+function getApexDomain(domain) {
+  const parsed = psl.parse(domain);
+  return parsed.domain || domain;
+}
+
+module.exports = { getApexDomain };

package/dist/lib/duration.js

@@ -0,0 +1,39 @@
+/**
+ * Wall-clock formatting for the manage walk — the ONE duration renderer the
+ * per-service lines and the run summary's total share.
+ *
+ *   formatDuration(340)    → '340ms'
+ *   formatDuration(14_200) → '14s'
+ *   formatDuration(94_000) → '1m 34s'
+ */
+
+/**
+ * Format elapsed milliseconds for humans.
+ *
+ * @param {number} ms - Elapsed milliseconds
+ * @returns {string}
+ */
+function formatDuration(ms) {
+  if (ms < 1000) {
+    return `${Math.round(ms)}ms`;
+  }
+
+  const seconds = Math.floor(ms / 1000);
+
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+
+  if (minutes < 60) {
+    return `${minutes}m ${remainingSeconds}s`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours}h ${remainingMinutes}m ${remainingSeconds}s`;
+}
+
+module.exports = { formatDuration };