@omega.js/manager 0.1.0

package/dist/lib/node-version.js

@@ -0,0 +1,127 @@
+/**
+ * node-version — resolve which Node a target's commands run under, from its
+ * own `.nvmrc` (friction #15: one brand spans Node majors — web pins 24,
+ * backend functions pin 22 — so the manager drives each target's commands
+ * under THAT target's Node instead of whatever it was launched with).
+ *
+ * Ported from legacy omega-manager's update-service resolution: the pinned
+ * major is matched against nvm's installed versions ($NVM_DIR/versions/node,
+ * highest patch wins) and that version's bin dir is prepended to PATH for
+ * the spawned command — node, npm, and npx all resolve to it. No .nvmrc →
+ * inherited PATH. Pinned major not installed → a hard error naming the
+ * `nvm install` to run.
+ */
+const path = require('node:path');
+const os = require('node:os');
+const jetpack = require('fs-jetpack');
+
+/** nvm's installed-versions dir (resolved per call — tests override NVM_DIR). */
+function nvmVersionsDir() {
+  return path.join(process.env.NVM_DIR || path.join(os.homedir(), '.nvm'), 'versions', 'node');
+}
+
+/**
+ * Parse the Node major out of an .nvmrc spec ('v24/*', 'v24', '24', '24.1.0' → 24).
+ *
+ * @param {string} content - Raw .nvmrc content.
+ * @returns {number|null} The major, or null when unparseable.
+ */
+function parseNvmrcMajor(content) {
+  const match = String(content || '').trim().match(/^v?(\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Find the target's .nvmrc — the target root is the ONE authored home (the
+ * backend's stage step copies it into dist/ for the Firebase runtime).
+ *
+ * @param {string} targetDir - The target directory commands run in.
+ * @returns {{ spec: string, file: string }|null} The trimmed spec + its file.
+ */
+function findNvmrc(targetDir) {
+  const file = path.join(targetDir, '.nvmrc');
+  const content = jetpack.read(file);
+  if (content && content.trim()) {
+    return { spec: content.trim(), file };
+  }
+  return null;
+}
+
+/**
+ * Find the highest nvm-installed Node for a major (24 → { version, binDir }).
+ *
+ * @param {number} major - Required Node major.
+ * @returns {{ version: string, binDir: string }|null} Best install, or null.
+ */
+function findInstalledNode(major) {
+  const versions = (jetpack.list(nvmVersionsDir()) || [])
+    .map((name) => {
+      const match = name.match(/^v(\d+)\.(\d+)\.(\d+)$/);
+      return match ? { name, parts: [Number(match[1]), Number(match[2]), Number(match[3])] } : null;
+    })
+    .filter(Boolean)
+    .filter((v) => v.parts[0] === major)
+    .sort((a, b) => b.parts[1] - a.parts[1] || b.parts[2] - a.parts[2]);
+
+  if (!versions.length) {
+    return null;
+  }
+  return {
+    version: versions[0].name,
+    binDir: path.join(nvmVersionsDir(), versions[0].name, 'bin'),
+  };
+}
+
+/**
+ * Resolve which Node a target's commands should run under.
+ *
+ * @param {string} targetDir - The directory the command will run in.
+ * @returns {null|object} null (no/unparseable .nvmrc: inherited PATH),
+ *   { major, spec, file, version, binDir } (binDir null when the current
+ *   Node already matches), or { major, spec, file, error } (major not
+ *   installed in nvm).
+ */
+function resolveTargetNode(targetDir) {
+  const found = findNvmrc(targetDir);
+  if (!found) {
+    return null;
+  }
+
+  const major = parseNvmrcMajor(found.spec);
+  if (!major) {
+    return null;
+  }
+
+  const currentMajor = Number(process.versions.node.split('.')[0]);
+  if (major === currentMajor) {
+    return { major, spec: found.spec, file: found.file, version: `v${process.versions.node}`, binDir: null };
+  }
+
+  const installed = findInstalledNode(major);
+  if (!installed) {
+    return {
+      major,
+      spec: found.spec,
+      file: found.file,
+      error: `Node v${major} required by .nvmrc (${found.spec}) is not installed — run: nvm install ${major}`,
+    };
+  }
+
+  return { major, spec: found.spec, file: found.file, version: installed.version, binDir: installed.binDir };
+}
+
+/**
+ * Env overrides for a spawned command so node/npm/npx resolve to the target's
+ * Node ({} when the inherited PATH is already right).
+ *
+ * @param {object|null} resolved - A resolveTargetNode() result.
+ * @returns {object} Env override ({ PATH } or {}).
+ */
+function nodeEnvFor(resolved) {
+  if (!resolved?.binDir) {
+    return {};
+  }
+  return { PATH: `${resolved.binDir}${path.delimiter}${process.env.PATH}` };
+}
+
+module.exports = { parseNvmrcMajor, findInstalledNode, resolveTargetNode, nodeEnvFor };

package/dist/lib/owner-plan.js

@@ -0,0 +1,78 @@
+/**
+ * Shared comp-plan reconciliation for the operator-product services
+ * (forms, chat, email): the brand's owner account on the product is
+ * set to the configured plan as an internal comp.
+ *
+ * Diff-synced on the subscription's leaf fields, and the patch masks only
+ * those leaves — sibling subscription fields written by the product's own
+ * backend (trial, cancellation flags, …) survive, exactly like the admin
+ * SDK merge-write this replaces. A missing user document is created by the
+ * same patch.
+ */
+const chalk = require('chalk').default;
+
+const SUBSCRIPTION_FIELD_PATHS = [
+  'subscription.product.id',
+  'subscription.product.name',
+  'subscription.status',
+  'subscription.payment.provider',
+  'subscription.payment.frequency',
+  'subscription.payment.price',
+  'subscription.payment.resourceId',
+  'subscription.payment.orderId',
+];
+
+/**
+ * Ensure the owner account's subscription matches the comp plan.
+ *
+ * @param {Object} params
+ * @param {Object} params.db - FirestoreREST client (or test fake)
+ * @param {string} params.ownerUid - The owner account's UID
+ * @param {{ id: string, name: string }} params.plan - The plan to grant
+ * @param {boolean} params.dryRun - Report the patch instead of writing it
+ * @returns {'synced'|'planned'|'updated'}
+ */
+async function ensureOwnerPlan({ db, ownerUid, plan, dryRun }) {
+  // Subscription shape matches the @omega.js/backend user schema
+  const desired = {
+    product: { id: plan.id, name: plan.name },
+    status: 'active',
+    payment: {
+      provider: 'internal',
+      frequency: 'annually',
+      price: 0,
+      resourceId: null,
+      orderId: null,
+    },
+  };
+
+  const user = await db.getDoc(`users/${ownerUid}`);
+  const sub = user?.subscription || {};
+
+  const drifted = sub.product?.id !== plan.id
+    || sub.product?.name !== plan.name
+    || sub.status !== 'active'
+    || sub.payment?.provider !== 'internal'
+    || sub.payment?.frequency !== 'annually'
+    || sub.payment?.price !== 0
+    || (sub.payment?.resourceId ?? null) !== null
+    || (sub.payment?.orderId ?? null) !== null;
+
+  if (!drifted) {
+    console.log(`      ${chalk.green('✓')} User ${chalk.dim(ownerUid)} already on ${chalk.cyan(plan.name)} plan ${chalk.dim('(internal)')}`);
+    return 'synced';
+  }
+
+  if (dryRun) {
+    console.log(`      ${chalk.yellow('[DRY RUN]')} Would set user ${chalk.cyan(ownerUid)} to ${chalk.cyan(plan.name)} plan ${chalk.dim('(internal)')}`);
+    return 'planned';
+  }
+
+  await db.patchDoc(`users/${ownerUid}`, { subscription: desired }, SUBSCRIPTION_FIELD_PATHS);
+
+  console.log(`      ${chalk.green('✓')} User ${chalk.dim(ownerUid)} set to ${chalk.cyan(plan.name)} plan ${chalk.dim('(internal)')}`);
+
+  return 'updated';
+}
+
+module.exports = { ensureOwnerPlan, SUBSCRIPTION_FIELD_PATHS };

package/dist/lib/package-scripts.js

@@ -0,0 +1,152 @@
+/**
+ * Brand-root package.json script healing — guarantees a `deploy` script, so
+ * `npm run deploy` works in every brand, and migrates the legacy
+ * `start: 'omega'` shape to the current convention (`npm start` boots the dev
+ * stack, `npm run manage` runs the manage cycle — as the NAMED verb
+ * `omega manage` since #229). Script VALUES only, and
+ * only the ones named here: every other script, key, and ordering is untouched.
+ */
+
+// The scripts minted when a brand root is missing them
+const DEPLOY_SCRIPT = 'omega deploy';
+const START_SCRIPT = 'omega dev';
+const MANAGE_SCRIPT = 'omega manage';
+
+// The pre-migration `start` value: a bare manage cycle on `npm start`
+const LEGACY_START_SCRIPT = 'omega';
+
+// The pre-migration `manage` value: a bare `omega` prints help now (#229),
+// so a brand still carrying it would run nothing at all
+const LEGACY_MANAGE_SCRIPT = 'omega';
+
+/**
+ * Heal a package.json's scripts map. Pure — never touches disk.
+ *
+ * @param {Object} pkg - parsed package.json
+ * @returns {{ scripts: Object, changes: string[] }}
+ *   scripts = the healed map (same key order, minted scripts appended)
+ *   changes = one `key: 'value'` line per heal, empty when converged
+ */
+function healPackageScripts(pkg) {
+  const scripts = { ...((pkg || {}).scripts || {}) };
+  const changes = [];
+
+  // The migration: only the legacy value moves — a brand that customized
+  // `start` to something of its own keeps it
+  if (scripts.start === LEGACY_START_SCRIPT) {
+    scripts.start = START_SCRIPT;
+    changes.push(`start: '${START_SCRIPT}'`);
+  }
+
+  // Minted whenever missing (a new key overwrites nothing): the manager's own
+  // retry hints print `npm run manage`, so every brand root must answer it.
+  // The same migration rule as `start` above — only the legacy value moves,
+  // a brand that customized `manage` keeps it.
+  if (!scripts.manage) {
+    scripts.manage = MANAGE_SCRIPT;
+    changes.push(`manage: '${MANAGE_SCRIPT}'`);
+  } else if (scripts.manage === LEGACY_MANAGE_SCRIPT) {
+    scripts.manage = MANAGE_SCRIPT;
+    changes.push(`manage: '${MANAGE_SCRIPT}'`);
+  }
+
+  if (!scripts.deploy) {
+    scripts.deploy = DEPLOY_SCRIPT;
+    changes.push(`deploy: '${DEPLOY_SCRIPT}'`);
+  }
+
+  return { scripts, changes };
+}
+
+// The command #675 retired. Every pre-#675 framework `projectScripts` chained
+// it — as the head (`npx omega setup && npx omega emulator`), mid-chain
+// (`npx omega clean && npx omega setup && npm run gulp --`), or alone
+// (`setup: 'npx omega setup'`). The command is gone, so any script still
+// naming it dies at `Unknown command "setup"` (#707): the segment is
+// framework-authored residue, never consumer intent.
+const RETIRED_SETUP_COMMAND = 'npx omega setup';
+
+/**
+ * The pre-#675 residue check: does this script value still run the retired
+ * command as one leg of its `&&` chain?
+ */
+function hasRetiredSetup(value) {
+  return value.split('&&').some((segment) => segment.trim() === RETIRED_SETUP_COMMAND);
+}
+
+/**
+ * The value with the retired leg dropped — `''` when the whole script WAS the
+ * retired command and nothing else is left to run.
+ */
+function withoutRetiredSetup(value) {
+  return value
+    .split('&&')
+    .map((segment) => segment.trim())
+    .filter((segment) => segment !== RETIRED_SETUP_COMMAND)
+    .join(' && ');
+}
+
+/**
+ * Sync a TARGET manifest's scripts to its framework's own `projectScripts`
+ * declaration. ONE ownership policy (#689): a key the framework declares is
+ * FRAMEWORK-owned and takes the default value on every run — the walk and the
+ * framework's own ensureTarget agree, so a hand-edited standard script is
+ * rewritten either way and hook points are the customization seam. A key the
+ * framework never declares is the consumer's own and is never touched.
+ *
+ * Two rules, in order:
+ *
+ * 1. One-time migration (#707): a value still naming the retired
+ *    `npx omega setup` (#675) is framework-authored residue — it takes the
+ *    manifest's current value, or, for a key the manifest no longer declares,
+ *    just loses that leg (and the key goes when nothing is left to run). Once
+ *    rewritten nothing matches again, so no standing machinery accrues.
+ * 2. Overwrite-to-default for every declared key. This also covers the
+ *    onboard→dev cycle break (#675): the framework's ensureTarget writes these
+ *    on the first verb run, but the dev fan-out reaches that verb THROUGH
+ *    these scripts, so a freshly scaffolded target needs them before any verb
+ *    has ever run.
+ *
+ * `brandOwnedKeys` carves the exception out per key, never per target: a
+ * custom-server backend (#584) names its own `start`/`deploy` because those
+ * verbs refuse in that mode, so those keys are skipped by BOTH rules — never
+ * written, never scaffolded, not even a placeholder to delete.
+ *
+ * @param {Object} pkg - parsed target package.json
+ * @param {Object} projectScripts - the framework package's projectScripts map
+ * @param {string[]} [brandOwnedKeys] - declared keys this target owns instead
+ * @returns {{ scripts: Object, changes: string[], skipped: string[] }}
+ *   skipped = the brand-owned keys the framework declares, for the report
+ */
+function syncTargetScripts(pkg, projectScripts, brandOwnedKeys = []) {
+  const scripts = { ...((pkg || {}).scripts || {}) };
+  const manifest = projectScripts || {};
+  const brandOwned = new Set(brandOwnedKeys);
+  const changes = [];
+
+  for (const [key, value] of Object.entries(scripts)) {
+    if (brandOwned.has(key) || !hasRetiredSetup(value)) continue;
+
+    const healed = manifest[key] === undefined ? withoutRetiredSetup(value) : manifest[key];
+    if (healed) {
+      scripts[key] = healed;
+      changes.push(`${key}: '${healed}' (was '${RETIRED_SETUP_COMMAND}')`);
+    } else {
+      delete scripts[key];
+      changes.push(`${key}: removed (was '${RETIRED_SETUP_COMMAND}')`);
+    }
+  }
+
+  for (const [key, value] of Object.entries(manifest)) {
+    if (brandOwned.has(key) || scripts[key] === value) continue;
+
+    scripts[key] = value;
+    changes.push(`${key}: '${value}'`);
+  }
+
+  const skipped = Object.keys(manifest).filter((key) => brandOwned.has(key));
+
+  return { scripts, changes, skipped };
+}
+
+module.exports = { healPackageScripts, syncTargetScripts, DEPLOY_SCRIPT, START_SCRIPT, MANAGE_SCRIPT };