@omega.js/manager 0.1.0

package/dist/lib/company-scaffold.js

@@ -0,0 +1,213 @@
+/**
+ * Company-workspace scaffolding — the file plan `omega company init` writes.
+ *
+ * The COMPANY rung's counterpart to lib/scaffold.js (brands): a company
+ * workspace is a REPO, not a machine cache — the config layer every brand
+ * inherits, the `.env` that sits UNDER every brand's own, and the shared
+ * Apple signing tree — so init is one plan of files in one directory, written
+ * with the same fill-missing semantics (existing files are never touched).
+ *
+ * What the repo TRACKS is the config skeleton, the README, and the
+ * .gitignore. Everything the workspace holds that is unshareable stays out of
+ * git: `.env` (secrets), `.omega/` (the signing tree's `.p8`/`.p12`/CSR
+ * private keys, run output, logs), and `brands/` (each managed brand is its
+ * OWN repo — never an embedded one).
+ */
+
+const path = require('node:path');
+
+// The .env template is a canonical render with NO values — one SSOT
+// (lib/env-order.js) shared with the brand scaffold stub and every
+// writeEnvValue writeback, so a company .env and a brand .env look alike.
+const { renderCanonicalEnv } = require('./env-order.js');
+
+// The ONE environment vocabulary — the same three overlays the brand scaffold
+// plans beside its own .env (#586)
+const { ENV_ENVIRONMENTS } = require('../vendor/config/index.js');
+
+// Directories init guarantees. The signing tree is the certificates service's
+// layout under {signingRoot}/.omega/certificates/apple/ — created empty so
+// the operator has an obvious home for the App Store Connect `AuthKey_*.p8`
+// before any run; `brands/` is the default `brands.roots` entry (a missing
+// one is a company-config error on the next manage).
+const COMPANY_DIRS = [
+  'brands',
+  '.omega/certificates/apple/certificates',
+  '.omega/certificates/apple/csr',
+  '.omega/certificates/apple/profiles',
+];
+
+/**
+ * The company-level config/omega.json5: the `brands` key (which is what MAKES
+ * a directory a company root) plus commented, brand-agnostic placeholders for
+ * the layers a company usually owns. Every key here is a DEFAULT its brands
+ * inherit and can override.
+ */
+function renderCompanyConfig(name) {
+  return [
+    `// ${name} — company-level omega.json5: the config layer EVERY managed brand`,
+    '// inherits (manager DEFAULTS ← this file ← the brand ← the brand\'s targets), so a key',
+    '// set here is a default any brand can override in its own config/omega.json5.',
+    '// Secrets NEVER live here — they go in the gitignored .env beside this file.',
+    '{',
+    '  // Where the brands are, RELATIVE to this root (absolute paths are an error).',
+    '  // Keep them inside the workspace with \'./brands\', or point at the org folder',
+    '  // with [\'..\'] to treat this workspace\'s SIBLING directories as the brands.',
+    '  brands: {',
+    '    roots: ["./brands"],',
+    '  },',
+    '',
+    '  // Company identity — a brand without its own value inherits these.',
+    '  // brand: {',
+    '  //   name: "My Company",',
+    '  //   url: "https://mycompany.com",',
+    '  //   contact: { email: "support@mycompany.com" },',
+    '  // },',
+    '',
+    '  // Managed Firebase Auth accounts every brand should carry (account service).',
+    '  // Passwords never live here — see the brand scaffold\'s notes on the seed.',
+    '  // account: {',
+    '  //   admins: [',
+    '  //     { email: "you@mycompany.com", account: true, marketing: false },',
+    '  //   ],',
+    '  // },',
+    '',
+    '  // The company GA account: a brand\'s analytics setup defaults to it instead',
+    '  // of prompting for one (a brand-level accountId always wins).',
+    '  // analytics: {',
+    '  //   providers: { google: { accountId: "123456789" } },',
+    '  // },',
+    '',
+    '  // Error monitoring: the Sentry org every brand\'s projects live under.',
+    '  // monitoring: {',
+    '  //   providers: { sentry: { org: "my-company" } },',
+    '  // },',
+    '',
+    '  // Apple signing: ONE Apple account signs everything the company ships, so',
+    '  // the reverse-DNS prefix (and the signing tree below) belongs here.',
+    '  // certificates: {',
+    '  //   providers: { apple: { bundleIdPrefix: "com.mycompany" } },',
+    '  // },',
+    '}',
+    '',
+  ].join('\n');
+}
+
+/**
+ * The company `.env` template — every canonical group, every key commented
+ * out. Nothing is generated: the company file holds only what EVERY brand
+ * shares (the Apple signing account, a company-wide token), and a brand's own
+ * `.env` wins over it.
+ */
+function renderCompanyEnvStub(name) {
+  return renderCanonicalEnv({
+    header: [
+      `# ${name} — COMPANY secrets (gitignored; loaded UNDER every managed brand's own .env).`,
+      '# Precedence: shell env > brand .env > this file. Put here only what every brand',
+      '# shares — anything brand-specific belongs in that brand\'s .env, never here.',
+    ],
+  });
+}
+
+/**
+ * A company environment-overlay stub — a header comment and NOTHING else, the
+ * same shape the BRAND scaffold plans
+ * ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)). The company
+ * layer is a layer like any other: its `.env` is the one file that documents
+ * the keys, and an overlay holds only the handful that differ for one
+ * environment (a sandbox Apple account, a staging token).
+ *
+ * @param {string} environment - `development` | `testing` | `production`.
+ * @returns {string} The file contents.
+ */
+function renderCompanyEnvOverlayStub(environment) {
+  return [
+    `# .env.${environment} — overlays .env when a managed brand runs in ${environment} (gitignored).`,
+    '# Only the keys that differ — anything not set here falls through to .env.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * The company repo's .gitignore. The `.omega/` and `logs/` entries match the
+ * shared healer's (lib/gitignore.js) exactly, so a company root scaffolded
+ * here is already 'present' when a company run checks.
+ */
+function renderCompanyGitignore() {
+  return [
+    '# Dependencies',
+    'node_modules/',
+    '',
+    '# Omega manager state (durable IDs + per-run output) — and the SHARED SIGNING',
+    '# TREE: .omega/certificates/apple/ holds Apple private key material (.p8, .p12,',
+    '# CSR keys). It never goes in git — move it between machines out of band.',
+    '.omega/',
+    '',
+    '# Run logs (truncated on every launch — never committed)',
+    'logs/',
+    '',
+    '# Secrets — the shared .env and its per-environment overlays',
+    '.env',
+    '.env.*',
+    '',
+    '# Managed brands — each one is its OWN git repo, never embedded in this one',
+    'brands/',
+    '',
+    '# OS',
+    '.DS_Store',
+    '',
+  ].join('\n');
+}
+
+function renderCompanyReadme(name) {
+  return `# ${name}
+
+The OMEGA **company workspace** — the layer every brand this company ships
+inherits. It is a repo, not a machine cache: config, shared secrets, and the
+shared Apple signing tree live here, and each brand stays its own repo.
+
+## What's here
+
+- \`config/omega.json5\` — the company config layer (\`brands.roots\` says where the
+  brands are; every other key is a default a brand can override).
+- \`.env\` — company secrets, loaded UNDER each brand's own \`.env\`
+  (shell > brand \`.env\` > this file). Gitignored.
+- \`.env.<environment>\` — the per-environment overlay (\`development\`, \`testing\`,
+  \`production\`): only the keys that differ there.
+- \`.omega/certificates/apple/\` — the shared Apple signing tree: one Apple
+  account signs everything the company ships. Gitignored; drop the App Store
+  Connect \`AuthKey_*.p8\` here.
+- \`brands/\` — the managed brands (each its own git repo; gitignored here).
+
+## Verbs
+
+\`\`\`bash
+npx omega company adopt <brand-path>  # stamp an existing brand: it inherits this company
+npx omega onboard                     # create a NEW brand under brands/ (stamped for you)
+npx omega manage                      # the full manage walk, once per managed brand
+npx omega manage --brand=<id>         # ... just one brand
+npx omega manage --parallel           # ... every brand concurrently
+\`\`\`
+`;
+}
+
+/**
+ * Build the scaffold plan for a company workspace.
+ *
+ * @param {string} name - Display name for the generated headers (the dir name)
+ * @returns {Array<{ path: string, contents: string }>} - Company-root-relative file plan
+ */
+function buildCompanyScaffoldPlan(name) {
+  return [
+    { path: path.join('config', 'omega.json5'), contents: renderCompanyConfig(name) },
+    { path: '.gitignore', contents: renderCompanyGitignore() },
+    { path: '.env', contents: renderCompanyEnvStub(name) },
+    ...ENV_ENVIRONMENTS.map((environment) => ({ path: `.env.${environment}`, contents: renderCompanyEnvOverlayStub(environment) })),
+    { path: 'README.md', contents: renderCompanyReadme(name) },
+    // Self-protecting: signing material can never be committed even if the
+    // root .gitignore is edited or the tree is copied into another repo.
+    { path: path.join('.omega', 'certificates', 'apple', '.gitignore'), contents: '*\n!.gitignore\n' },
+  ];
+}
+
+module.exports = { COMPANY_DIRS, buildCompanyScaffoldPlan };

package/dist/lib/company.js

@@ -0,0 +1,227 @@
+/**
+ * Company-workspace helpers — the COMPANY → BRAND rung of the hierarchy
+ * (Task M3 design, settled 2026-07-07).
+ *
+ * A company root is a directory whose config/omega.json5 has a `brands` key:
+ *
+ *   brands: { roots: ['./brands'] }   // dirs to scan, RELATIVE to the
+ *                                     // company root (never absolute)
+ *
+ * Anything under a root with its own config/omega.json5 is a brand. A brand
+ * behaves IDENTICALLY everywhere (standalone / nested / loose sibling) — the
+ * company layer only changes what defaults it inherits:
+ *
+ *   manager DEFAULTS ← company omega.json5 ← brand ← local …  (config)
+ *   company .env ← brand .env ← shell env                    (secrets)
+ *
+ * The reverse link without nesting: company runs idempotently stamp
+ * `.omega/company.json` ({ root }) into each managed brand; brand-local runs
+ * read the stamp and layer the company config + .env, warn when it's stale,
+ * and run standalone when it's absent.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const JSON5 = require('json5');
+const jetpack = require('fs-jetpack');
+
+const { resolveConfigPath, hasOmegaConfig, findSecretKeys, readCompanyRoot, COMPANY_MARKER } = require('../vendor/config/index.js');
+const { resolveBrandRoot } = require('./brand.js');
+const { stripLeadingVerb } = require('./argv.js');
+
+const DEFAULT_BRAND_ROOTS = ['./brands'];
+
+/**
+ * Raw config/omega.json5 read — no merge, no validation, null when the file
+ * is missing or unparseable (discovery must never throw on a broken brand;
+ * the brand's own workspace service reports it).
+ */
+function readRawConfig(dir) {
+  const configPath = resolveConfigPath(dir);
+  if (!configPath) return null;
+
+  try {
+    return JSON5.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is this directory a company root (config with a `brands` key)?
+ */
+function isCompanyRoot(dir) {
+  return !!readRawConfig(dir)?.brands;
+}
+
+/**
+ * Resolve what kind of root contains startDir: the nearest omega.json5 root
+ * (brand walk-up rules), classified as company or brand.
+ *
+ * @returns {{ root: string, isCompany: boolean }|null}
+ */
+function resolveManageRoot(startDir) {
+  const root = resolveBrandRoot(startDir);
+  if (!root) return null;
+
+  return { root, isCompany: isCompanyRoot(root) };
+}
+
+/**
+ * Discover the brands a company manages: for each entry in brands.roots
+ * (relative to the company root), every immediate child directory with a
+ * config/omega.json5 is a brand. The company root itself and nested company
+ * configs are skipped (one rung: company → brands).
+ *
+ * Throws on config mistakes (absolute or missing roots); broken brand
+ * configs do NOT throw — the brand is listed and its own run reports them.
+ *
+ * @param {string} companyRoot - Absolute company root
+ * @returns {{ brands: Array<{ id, name, dirName, root, enabled }>, skipped: Array<{ dir, reason }> }}
+ */
+function discoverBrands(companyRoot) {
+  const raw = readRawConfig(companyRoot) || {};
+  const roots = raw.brands?.roots || DEFAULT_BRAND_ROOTS;
+
+  if (!Array.isArray(roots) || roots.length === 0) {
+    throw new Error('brands.roots must be a non-empty array of directories relative to the company root');
+  }
+
+  const companyReal = fs.realpathSync(companyRoot);
+  const seen = new Set();
+  const brands = [];
+  const skipped = [];
+
+  for (const rootSpec of roots) {
+    if (path.isAbsolute(rootSpec)) {
+      throw new Error(`brands.roots entries must be RELATIVE to the company root — got absolute path: ${rootSpec}`);
+    }
+
+    const scanDir = path.resolve(companyRoot, rootSpec);
+    if (!fs.existsSync(scanDir)) {
+      throw new Error(`brands root not found: ${rootSpec} (${scanDir})`);
+    }
+
+    for (const entry of fs.readdirSync(scanDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+
+      const brandDir = path.join(scanDir, entry.name);
+      const real = fs.realpathSync(brandDir);
+      if (real === companyReal || seen.has(real)) continue;
+
+      if (!hasOmegaConfig(brandDir)) continue;
+      seen.add(real);
+
+      const brandRaw = readRawConfig(brandDir);
+      if (brandRaw?.brands) {
+        skipped.push({ dir: brandDir, reason: 'nested company workspace (one rung: company → brands)' });
+        continue;
+      }
+
+      brands.push({
+        id: brandRaw?.brand?.id || entry.name,
+        name: brandRaw?.brand?.name || brandRaw?.brand?.id || entry.name,
+        dirName: entry.name,
+        root: brandDir,
+        enabled: brandRaw?.enabled !== false,
+      });
+    }
+  }
+
+  brands.sort((a, b) => a.id.localeCompare(b.id));
+  return { brands, skipped };
+}
+
+/**
+ * The company config layer a brand inherits: the raw company omega.json5
+ * minus the `brands` key (company plumbing, meaningless inside a brand).
+ * Hard-fails on secret-shaped keys — same rule as every omega.json5.
+ */
+function loadCompanyConfig(companyRoot) {
+  const raw = readRawConfig(companyRoot);
+  if (!raw) return {};
+
+  const secretKeys = findSecretKeys(raw);
+  if (secretKeys.length > 0) {
+    throw new Error(
+      `Secret-shaped keys in company config ${companyRoot}: ${secretKeys.join(', ')} — `
+      + `secrets live in the company .env, never in omega.json5`,
+    );
+  }
+
+  const { brands, ...inheritable } = raw;
+  return inheritable;
+}
+
+/**
+ * Idempotently stamp `.omega/company.json` into a brand so its local runs
+ * layer this company's defaults.
+ *
+ * @returns {boolean} - true when the marker was (re)written
+ */
+function stampCompanyMarker(brandRoot, companyRoot) {
+  const markerPath = path.join(brandRoot, COMPANY_MARKER);
+  const existing = jetpack.read(markerPath, 'json');
+
+  if (existing?.root === companyRoot) {
+    return false;
+  }
+
+  jetpack.write(markerPath, { root: companyRoot }, { jsonIndent: 2 });
+  return true;
+}
+
+/**
+ * Read a brand's company marker. null when absent (standalone brand);
+ * `stale: true` when the marker points at something that is no longer a
+ * company workspace.
+ *
+ * @returns {{ companyRoot: string, stale: boolean }|null}
+ */
+function readCompanyMarker(brandRoot) {
+  const root = readCompanyRoot(brandRoot);
+  if (!root) return null;
+
+  return { companyRoot: root, stale: !isCompanyRoot(root) };
+}
+
+/**
+ * Strip the leading verb (#229 — each child spawn names `manage` itself) and
+ * the company-only flags from a raw argv, so the remainder forwards to
+ * per-brand child processes verbatim (--brand/--concurrency take values in
+ * both --flag=x and --flag x forms; --parallel is boolean).
+ */
+function filterChildArgs(rawArgv) {
+  const argv = stripLeadingVerb(rawArgv);
+  const VALUE_FLAGS = new Set(['--brand', '--concurrency']);
+  const BOOLEAN_FLAGS = new Set(['--parallel']);
+  const out = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const name = argv[i].split('=')[0];
+
+    if (BOOLEAN_FLAGS.has(name)) continue;
+    if (VALUE_FLAGS.has(name)) {
+      if (!argv[i].includes('=') && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) {
+        i++;
+      }
+      continue;
+    }
+
+    out.push(argv[i]);
+  }
+
+  return out;
+}
+
+module.exports = {
+  DEFAULT_BRAND_ROOTS,
+  readRawConfig,
+  isCompanyRoot,
+  resolveManageRoot,
+  discoverBrands,
+  loadCompanyConfig,
+  stampCompanyMarker,
+  readCompanyMarker,
+  filterChildArgs,
+};