@omega.js/manager 0.1.0

package/dist/devlog/lib/project-map.js

@@ -0,0 +1,98 @@
+/**
+ * Devlog backlink SSOT — map every known brand repo to its public project
+ * (name + URL) so the writer can link each mentioned repo to the product it
+ * belongs to. Repos not in the map are treated as standalone and linked to
+ * GitHub instead.
+ *
+ * In the brand-monorepo world every brand is ONE repo, addressed by
+ * `@omega.js/config`'s `brandRepo` — the typed `repo.providers.github.repo` slug
+ * (whose owner half wins when it carries one), else `<brand.id>-omega` under
+ * `repo.providers.github.org`, the ONE derivation the github service reads too;
+ * omega-manager's per-target + subdomain repo fan-out collapsed at the
+ * redesign. Brands without a repo.providers.github.org are skipped (the github service
+ * skips them too).
+ */
+
+const { brandRepo: deriveBrandRepo, brandRepoName } = require('../../vendor/config/index.js');
+
+/**
+ * Resolve a loaded brand's repo identity, or null when it has none.
+ *
+ * @param {object} brand - Loaded brand (lib/brand.js loadBrand shape)
+ * @returns {{ owner: string, repo: string }|null}
+ */
+function brandRepo(brand) {
+  const github = brand.config.repo?.providers?.github;
+
+  if (!github.org) {
+    return null;
+  }
+
+  // BOTH halves from the one derivation: an `owner/name` slug houses the repo
+  // under its own owner. The loaded brand's own id stands in for a config that
+  // names none.
+  const { owner, name } = deriveBrandRepo(brand.config);
+
+  return { owner, repo: name || brandRepoName({ brand: { id: brand.id } }) };
+}
+
+/**
+ * Build the repo → project map across every loaded brand.
+ *
+ * @param {Array} brands - Loaded brands
+ * @param {object} [params] - { excludeRepos }
+ * @returns {Object<string, {project: string, url: string}>} repoName → project
+ */
+function buildProjectMap(brands, { excludeRepos = [] } = {}) {
+  const map = {};
+
+  for (const brand of brands) {
+    const identity = brandRepo(brand);
+
+    if (!identity || excludeRepos.includes(identity.repo)) {
+      continue;
+    }
+
+    map[identity.repo] = {
+      project: brand.config.brand?.name || brand.id,
+      url: brand.config.brand?.url || '',
+    };
+  }
+
+  return map;
+}
+
+/**
+ * Build the complete brand repo list. The brand configs are the SSOT for
+ * where every repo lives, so scanning is never limited to the hand-maintained
+ * `orgs` list — that list only supplements this with non-brand repos
+ * (frameworks, tooling).
+ *
+ * @param {Array} brands - Loaded brands
+ * @param {object} [params] - { excludeRepos }
+ * @returns {Array<{ owner: string, repo: string }>} Unique owner/repo pairs
+ */
+function buildBrandRepos(brands, { excludeRepos = [] } = {}) {
+  const seen = new Set();
+  const repos = [];
+
+  for (const brand of brands) {
+    const identity = brandRepo(brand);
+
+    if (!identity || excludeRepos.includes(identity.repo)) {
+      continue;
+    }
+
+    const key = `${identity.owner}/${identity.repo}`.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    repos.push(identity);
+  }
+
+  return repos;
+}
+
+module.exports = { buildProjectMap, buildBrandRepos };

package/dist/devlog/lib/publish-website.js

@@ -0,0 +1,88 @@
+/**
+ * Devlog publish stage — write the post into the brand's website target and
+ * push it live. In the brand-monorepo world the website is a target INSIDE the brand
+ * repo (targets/{website}/src), so the commit lands in the brand monorepo itself.
+ * Publishing IS the push — the site auto-builds and deploys on push. Only the
+ * post file is committed; unrelated dirty files are untouched.
+ */
+
+const { execSync } = require('node:child_process');
+const { join } = require('node:path');
+
+const jetpack = require('fs-jetpack');
+
+/**
+ * Local YYYY-MM-DD stamp — local (not UTC) so a late-night run never
+ * future-dates the post, which the site build would silently skip.
+ *
+ * @param {Date} date - Date to stamp
+ * @returns {string} YYYY-MM-DD
+ */
+function localDateStamp(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Render the post file (blueprint front matter + markdown body).
+ *
+ * @param {object} brandConfig - Merged brand config
+ * @param {object} post - Generated post { title, slug, description, tags, categories, body }
+ * @returns {string} Full post file contents
+ */
+function renderPostFile(brandConfig, post) {
+  return [
+    '---',
+    'layout: blueprint/blog/post',
+    '',
+    'post:',
+    `  title: ${JSON.stringify(post.title)}`,
+    `  description: ${JSON.stringify(post.description)}`,
+    `  author: ${brandConfig.brand.id}`,
+    `  id: ${Math.floor(Date.now() / 1000)}`,
+    `  tags: ${JSON.stringify(post.tags)}`,
+    `  categories: ${JSON.stringify(post.categories)}`,
+    '---',
+    '',
+    post.body,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Write the post into the brand's website target, commit only the post file in
+ * the brand monorepo, and push.
+ *
+ * @param {object} params - { brand, post } (brand = lib/brand.js loadBrand shape)
+ * @returns {{ postPath: string, url: string }} Written file + eventual live URL
+ */
+function publishToWebsite({ brand, post }) {
+  const webTarget = brand.targets.find((entry) => entry.target === 'web');
+
+  if (!webTarget) {
+    throw new Error(`Brand ${brand.id} has no website target under targets/ — devlog's 'website' destination needs one`);
+  }
+
+  const now = new Date();
+  const date = localDateStamp(now);
+  const relativePath = join(webTarget.dir, 'src', '_posts', String(now.getFullYear()), brand.config.devlog.providers.ghostii.postPath, `${date}-${post.slug}.md`);
+  const postPath = join(brand.root, relativePath);
+
+  jetpack.write(postPath, renderPostFile(brand.config, post));
+
+  const git = (args) => execSync(`git ${args}`, { cwd: brand.root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+
+  git(`add "${relativePath}"`);
+  git(`commit -m "📦 Omega: Add devlog post ${date}-${post.slug}" -- "${relativePath}"`);
+  git('push');
+
+  return {
+    postPath,
+    url: `${brand.config.brand.url}/blog/${post.slug}`,
+  };
+}
+
+module.exports = { publishToWebsite, renderPostFile };

package/dist/index.js

@@ -0,0 +1,45 @@
+/**
+ * @omega.js/manager — the OMEGA orchestration engine for brand monorepos.
+ * Public surface: the manage runner, the service-runner factory (services
+ * and tests build on it), brand loading, and the registry.
+ */
+
+const { runManage } = require('./manage.js');
+const { createServiceRunner, splitReturn, getOperationHandler } = require('./lib/service-runner.js');
+const { RunSummary } = require('./lib/run-summary.js');
+const { resolveBrandRoot, loadBrand, discoverTargets, targetFromDirName } = require('./lib/brand.js');
+const { writeRunOutput } = require('./lib/run-output.js');
+const {
+  SERVICE_ORDER,
+  OPERATIONS,
+  DEFAULTS,
+  DIR_TARGETS,
+  TARGET_DIRS,
+  templateObject,
+} = require('./config.js');
+
+module.exports = {
+  // Orchestrator
+  runManage,
+
+  // Service framework
+  createServiceRunner,
+  splitReturn,
+  getOperationHandler,
+  RunSummary,
+
+  // Brand + run output
+  resolveBrandRoot,
+  loadBrand,
+  discoverTargets,
+  targetFromDirName,
+  writeRunOutput,
+
+  // Registry
+  SERVICE_ORDER,
+  OPERATIONS,
+  DEFAULTS,
+  DIR_TARGETS,
+  TARGET_DIRS,
+  templateObject,
+};

package/dist/lib/agents-md.js

@@ -0,0 +1,201 @@
+/**
+ * Brand agent-docs chain (Ian 2026-07-20, amended 2026-07-27): every brand
+ * root carries an AGENTS.md whose FIRST line imports the TOP-LEVEL omega
+ * AGENTS.md — the map, the one agent entry — through the scope path
+ * `node_modules/@omega.js/AGENTS.md`, plus a one-line CLAUDE.md pointer
+ * (`@AGENTS.md`). The scope file is a symlink this service maintains: it
+ * resolves the framework monorepo through the installed manager package and
+ * links straight at the live top-level map; a published install has no
+ * monorepo, so it links at the map the prepare lane vendored into the package
+ * (`docs/AGENTS.md`). Idempotent: create when missing, heal a missing/stale
+ * first-line import in place, never touch consumer content below the import.
+ */
+const { join, dirname } = require('node:path');
+const fs = require('node:fs');
+const jetpack = require('fs-jetpack');
+
+const GUIDE_SUBPATH = 'node_modules/@omega.js/AGENTS.md';
+const IMPORT_LINE = `@${GUIDE_SUBPATH}`;
+const CLAUDE_POINTER = '@AGENTS.md';
+
+const SCOPE_PREFIXES = ['', '../', '../../', '../../../'];
+
+/**
+ * Is this line an import of the framework guide (any relative depth)?
+ *
+ * @param {string} line - A single file line
+ * @returns {boolean}
+ */
+function isImportLine(line) {
+  const trimmed = line.trim();
+  return trimmed.startsWith('@') && trimmed.endsWith(GUIDE_SUBPATH);
+}
+
+/**
+ * The @omega.js scope directory serving this brand: the brand's own
+ * node_modules normally, an ancestor's when hoisted (npm workspaces).
+ *
+ * @param {string} brandRoot - Absolute brand monorepo root
+ * @returns {{prefix: string, scopeDir: string}|null}
+ */
+function findScope(brandRoot) {
+  for (const prefix of SCOPE_PREFIXES) {
+    const scopeDir = join(brandRoot, prefix, 'node_modules', '@omega.js');
+    if (jetpack.exists(scopeDir) !== 'dir') continue;
+    // Only a scope that can back the import counts: the map link is already
+    // there, or the manager package is present for ensureGuideLink to resolve
+    // it. An empty dir from a partial install would leave the import dangling
+    // while the real scope sits a level up (#153).
+    if (jetpack.exists(join(scopeDir, 'AGENTS.md')) !== false
+      || jetpack.exists(join(scopeDir, 'manager')) !== false) {
+      return { prefix, scopeDir };
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the import line for THIS brand — the depth that reaches the scope
+ * directory holding `@omega.js/AGENTS.md`. Falls back to the canonical
+ * brand-local path when nothing is installed yet (pre-install).
+ *
+ * @param {string} brandRoot - Absolute brand monorepo root
+ * @returns {string} - The `@<relative path>` import line
+ */
+function resolveImportLine(brandRoot) {
+  const scope = findScope(brandRoot);
+  return scope ? `@${scope.prefix}${GUIDE_SUBPATH}` : IMPORT_LINE;
+}
+
+/**
+ * Ensure `node_modules/@omega.js/AGENTS.md` links at the omega map. The
+ * installed manager package's real path (the local-era file: symlink) names
+ * both candidates, in this order: the monorepo's LIVE map two dirs up, then
+ * the copy the prepare lane vendors into the package (`docs/AGENTS.md`, #144).
+ * The live map wins wherever it exists, so a locally linked brand never lands
+ * on the generated copy sitting in that same monorepo's packages/manager.
+ * Neither present (pre-install) → the link is left alone and the step skips.
+ *
+ * @param {string} brandRoot - Absolute brand monorepo root
+ * @returns {'present'|'created'|'healed'|'skipped'} - What happened
+ */
+function ensureGuideLink(brandRoot) {
+  const scope = findScope(brandRoot);
+  if (!scope) {
+    return 'skipped';
+  }
+
+  let mapFile;
+  try {
+    const managerReal = fs.realpathSync(join(scope.scopeDir, 'manager'));
+    mapFile = [
+      join(dirname(dirname(managerReal)), 'AGENTS.md'),
+      join(managerReal, 'docs', 'AGENTS.md'),
+    ].find((candidate) => jetpack.exists(candidate) === 'file');
+  } catch {
+    return 'skipped';
+  }
+  if (!mapFile) {
+    return 'skipped';
+  }
+
+  const linkPath = join(scope.scopeDir, 'AGENTS.md');
+  try {
+    if (fs.readlinkSync(linkPath) === mapFile) {
+      return 'present';
+    }
+  } catch {
+    // Not a symlink (missing, or a stale regular file) — fall through and place it.
+  }
+
+  const existed = jetpack.exists(linkPath) !== false;
+  jetpack.remove(linkPath);
+  fs.symlinkSync(mapFile, linkPath);
+  return existed ? 'healed' : 'created';
+}
+
+/**
+ * Render a fresh brand AGENTS.md.
+ *
+ * @param {string} brandName - Display name for the brand-notes heading
+ * @returns {string} - Full file content
+ */
+function renderAgentsMd(brandName, importLine = IMPORT_LINE) {
+  return [
+    importLine,
+    '',
+    `# ${brandName} — brand notes`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Ensure the brand-root AGENTS.md exists with the framework import as its
+ * first line. Existing consumer content is preserved verbatim; a stray copy
+ * of the import lower in the file is removed when healing (no duplicates).
+ *
+ * @param {string} brandRoot - Absolute brand monorepo root
+ * @param {string} brandName - Display name used when creating fresh
+ * @returns {'present'|'created'|'healed'} - What happened
+ */
+function ensureAgentsMd(brandRoot, brandName) {
+  const file = join(brandRoot, 'AGENTS.md');
+  const importLine = resolveImportLine(brandRoot);
+  const existing = jetpack.read(file);
+
+  if (existing === undefined) {
+    jetpack.write(file, renderAgentsMd(brandName, importLine));
+    return 'created';
+  }
+
+  const lines = existing.split('\n');
+  const hasCruft = lines.some((line, i) => i > 0 && isImportLine(line));
+
+  if (lines[0].trim() === importLine && !hasCruft) {
+    return 'present';
+  }
+
+  // Heal: the resolved import goes to the top; drop any stray/stale-depth
+  // import copy so heals never stack cruft
+  const body = lines.filter((line) => !isImportLine(line));
+  jetpack.write(file, [importLine, ...(body[0]?.trim() === '' ? [] : ['']), ...body].join('\n'));
+  return 'healed';
+}
+
+/**
+ * Ensure the brand-root CLAUDE.md is the one-line `@AGENTS.md` pointer.
+ * A content-bearing CLAUDE.md is NEVER clobbered — that content belongs in
+ * AGENTS.md (the caller warns with the move-it message).
+ *
+ * @param {string} brandRoot - Absolute brand monorepo root
+ * @returns {'present'|'created'|'content-bearing'} - What happened
+ */
+function ensureClaudePointer(brandRoot) {
+  const file = join(brandRoot, 'CLAUDE.md');
+  const existing = jetpack.read(file);
+
+  if (existing === undefined) {
+    jetpack.write(file, `${CLAUDE_POINTER}\n`);
+    return 'created';
+  }
+
+  const meaningful = existing.split('\n').map((line) => line.trim()).filter(Boolean);
+  if (meaningful.includes(CLAUDE_POINTER)) {
+    return 'present';
+  }
+
+  return 'content-bearing';
+}
+
+module.exports = {
+  GUIDE_SUBPATH,
+  IMPORT_LINE,
+  CLAUDE_POINTER,
+  isImportLine,
+  findScope,
+  resolveImportLine,
+  ensureGuideLink,
+  renderAgentsMd,
+  ensureAgentsMd,
+  ensureClaudePointer,
+};

package/dist/lib/analytics-secret.js

@@ -0,0 +1,22 @@
+/**
+ * The brand-.env home of each target's GA4 Measurement Protocol secret — the
+ * ONE name the analytics service resolves from GA and writes. Per-target
+ * because every surface measures through its own stream; the per-target name
+ * is delivered as GOOGLE_ANALYTICS_SECRET on every verb (composed into
+ * dist/.env for backend, loaded into process.env for the others) — the env
+ * schema's rename, #678.
+ *
+ * It is a secret, so config/omega.json5 is not an option (the loader
+ * hard-fails secret-shaped keys) — before #434 it lived in .omega/state.json
+ * and the composition read it from there.
+ */
+
+/**
+ * @param {string} target - Target key (web/backend/desktop/extension/mobile)
+ * @returns {string} The brand .env variable name, e.g. GOOGLE_ANALYTICS_SECRET_BACKEND
+ */
+function streamSecretEnvName(target) {
+  return `GOOGLE_ANALYTICS_SECRET_${target.toUpperCase()}`;
+}
+
+module.exports = { streamSecretEnvName };

package/dist/lib/argv.js

@@ -0,0 +1,21 @@
+/**
+ * argv shaping — the one rule about the leading VERB (#229).
+ *
+ * Every manager invocation now names its command (`omega manage --service=x`),
+ * so anything that REBUILDS an invocation from the raw argv — the run
+ * summary's copy-pasteable retry line, the company runner's per-brand child
+ * args — has to drop that verb first, or it doubles into `omega manage manage`.
+ */
+
+/**
+ * The argv without its leading command verb. A first entry that starts with
+ * `-` is a flag, not a verb, and is left alone.
+ *
+ * @param {string[]} argv - Raw arguments (process.argv.slice(2) shaped).
+ * @returns {string[]} The arguments after the verb.
+ */
+function stripLeadingVerb(argv) {
+  return argv[0] && !argv[0].startsWith('-') ? argv.slice(1) : argv;
+}
+
+module.exports = { stripLeadingVerb };

package/dist/lib/auth-admin.js

@@ -0,0 +1,120 @@
+/**
+ * Firebase Auth admin client over the Identity Toolkit REST API — the
+ * non-interactive replacement for omega-manager's firebase-admin
+ * `getAuth(brandId)`. Authenticates with the brand's own service account
+ * (.omega/secrets/service-account.json, provisioned by the firebase
+ * service) via the shared google-token provider; custom tokens are signed
+ * locally with the shared jwt helper, so there is no SDK dependency.
+ * Shared by the account service (required accounts) and the migrations
+ * service (orphaned-doc detection + creation-time reconciliation).
+ *
+ * Handlers call named methods, so tests fake this surface
+ * method-for-method. Lookups return null for missing users (instead of
+ * firebase-admin's auth/user-not-found throw).
+ */
+const { createTokenProvider } = require('./google-token.js');
+const { signJwt } = require('./jwt.js');
+
+const IDENTITY_TOOLKIT_BASE = 'https://identitytoolkit.googleapis.com/v1';
+const SCOPE = 'https://www.googleapis.com/auth/identitytoolkit';
+
+// Fixed audience for Firebase custom tokens (not the project)
+const CUSTOM_TOKEN_AUD = 'https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit';
+
+/**
+ * Map an Identity Toolkit user record to the subset the services use.
+ * createdAt is Identity Toolkit's ms-since-epoch string; it surfaces as
+ * metadata.creationTime (ISO) to mirror firebase-admin's UserRecord shape.
+ */
+function toUser(record) {
+  return {
+    uid: record.localId,
+    email: record.email,
+    providerData: (record.providerUserInfo || []).map((p) => ({ providerId: p.providerId })),
+    metadata: {
+      creationTime: record.createdAt ? new Date(Number(record.createdAt)).toISOString() : null,
+    },
+  };
+}
+
+/**
+ * Create the auth admin client.
+ *
+ * @param {Object} serviceAccount - Parsed service-account JSON
+ * @returns {Object} { getUserByEmail, getUser, createUser, updateUser, createCustomToken }
+ */
+function createAuthAdmin(serviceAccount) {
+  const projectId = serviceAccount.project_id;
+  const tokenProvider = createTokenProvider(serviceAccount, SCOPE);
+
+  async function request(method, body) {
+    const token = await tokenProvider.getAccessToken();
+
+    const response = await fetch(`${IDENTITY_TOOLKIT_BASE}/projects/${projectId}/${method}`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30000),
+    });
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      throw new Error(`Identity Toolkit API error: ${data.error?.message || JSON.stringify(data)}`);
+    }
+
+    return data;
+  }
+
+  return {
+    /** Look up a user by email. Missing → null. */
+    async getUserByEmail(email) {
+      const data = await request('accounts:lookup', { email: [email] });
+      return data.users?.[0] ? toUser(data.users[0]) : null;
+    },
+
+    /** Look up a user by uid. Missing → null. */
+    async getUser(uid) {
+      const data = await request('accounts:lookup', { localId: [uid] });
+      return data.users?.[0] ? toUser(data.users[0]) : null;
+    },
+
+    /** Create a user with email + password. */
+    async createUser({ email, password }) {
+      const data = await request('accounts', { email, password });
+      return { uid: data.localId, email };
+    },
+
+    /** Update a user's password. */
+    async updateUser(uid, { password }) {
+      await request('accounts:update', { localId: uid, password });
+    },
+
+    /**
+     * Mint a Firebase custom token for a uid — signed locally with the
+     * service account's key (RS256), exchangeable for an ID token via the
+     * public signInWithCustomToken endpoint.
+     */
+    createCustomToken(uid) {
+      const now = Math.floor(Date.now() / 1000);
+
+      return signJwt(
+        { alg: 'RS256', typ: 'JWT' },
+        {
+          iss: serviceAccount.client_email,
+          sub: serviceAccount.client_email,
+          aud: CUSTOM_TOKEN_AUD,
+          iat: now,
+          exp: now + 3600,
+          uid,
+        },
+        serviceAccount.private_key,
+      );
+    },
+  };
+}
+
+module.exports = { createAuthAdmin, CUSTOM_TOKEN_AUD };