@omega.js/manager 0.1.0

package/dist/services/search/index.js

@@ -0,0 +1,61 @@
+/**
+ * Search service (`search.providers.searchConsole`) — the brand's Search
+ * Console domain property (`sc-domain:{domain}` covers every subdomain),
+ * created and verified via a DNS TXT record written through Cloudflare, plus
+ * sitemap submission and the GA-association nudge.
+ *
+ * Runs after the edge service (the zone must exist for TXT verification) and
+ * after analytics (the GA property is what ga-link associates with).
+ *
+ * Auth: GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET in the brand .env (OAuth2;
+ * tokens cache to the ONE shared .omega/auth/google-tokens.json store
+ * (lib/google-auth.js) alongside the firebase and analytics grants — the
+ * webmasters + siteverification scopes ride the same file). No credentials →
+ * the service skips.
+ */
+const { serviceInputSpec } = require('../../config.js');
+const { googleTokenStorePath } = require('../../lib/google-auth.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { CloudflareAPI } = require('../edge/lib/cloudflare-api.js');
+const { getApexDomain } = require('../../lib/domain-utils.js');
+const { GoogleSearchConsoleAPI } = require('./lib/search-console-api.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const searchConsole = context.brandConfig.search?.providers?.searchConsole || {};
+
+    if (searchConsole.enabled === false) {
+      return { skip: true, reason: 'search.providers.searchConsole.enabled = false' };
+    }
+
+    const domain = (context.brandConfig.brand?.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
+    if (!domain) {
+      return { skip: true, reason: 'no brand.url configured' };
+    }
+
+    // The shared setup contract (#608) — provide, skip this run, or disable
+    // the service for good; a headless run steps aside loudly.
+    if (!context.searchConsoleApi) {
+      const gate = await requestServiceInput(context, serviceInputSpec('search'));
+      if (gate) return gate;
+    }
+
+    const apexDomain = getApexDomain(domain);
+
+    // Tests inject fake clients via context.searchConsoleApi / context.cloudflareApi.
+    // Cloudflare is only needed when the property still has to be DNS-verified;
+    // without a token the property operation prints the record to add manually.
+    return {
+      searchConsoleApi: context.searchConsoleApi || new GoogleSearchConsoleAPI({
+        tokenStorePath: googleTokenStorePath(context.brandRoot),
+      }),
+      cloudflareApi: context.cloudflareApi
+        || (process.env.CLOUDFLARE_TOKEN ? new CloudflareAPI() : null),
+      domain,
+      apexDomain,
+      propertyUrl: `sc-domain:${domain}`,
+    };
+  },
+});

package/dist/services/search/lib/search-console-api.js

@@ -0,0 +1,92 @@
+/**
+ * Google Search Console client — the Webmasters v3 API (sites + sitemaps)
+ * plus the Site Verification v1 API (DNS_TXT domain verification). Named-
+ * method surface over the shared GoogleOAuth2Client so tests can fake it
+ * method-for-method.
+ *
+ * Auth: GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET in the brand .env; the ONE
+ * shared token store (GOOGLE_SCOPES union — one consent covers everything).
+ */
+const { GoogleOAuth2Client, GOOGLE_SCOPES } = require('../../../lib/google-auth.js');
+
+const SEARCH_CONSOLE_API_BASE = 'https://www.googleapis.com/webmasters/v3';
+const SITE_VERIFICATION_API_BASE = 'https://www.googleapis.com/siteVerification/v1';
+
+class GoogleSearchConsoleAPI {
+  constructor(options = {}) {
+    this.auth = new GoogleOAuth2Client({
+      clientId: options.clientId || process.env.GOOGLE_CLIENT_ID,
+      clientSecret: options.clientSecret || process.env.GOOGLE_CLIENT_SECRET,
+      tokenStorePath: options.tokenStorePath,
+      scopes: GOOGLE_SCOPES,
+    });
+  }
+
+  async makeRequest(endpoint, options = {}) {
+    return this.auth.makeRequest(`${SEARCH_CONSOLE_API_BASE}${endpoint}`, options);
+  }
+
+  // ========== Sites ==========
+
+  async listSites() {
+    const data = await this.makeRequest('/sites');
+    return data.siteEntry || [];
+  }
+
+  /** siteUrl: 'https://example.com/' or 'sc-domain:example.com' */
+  async addSite(siteUrl) {
+    await this.makeRequest(`/sites/${encodeURIComponent(siteUrl)}`, { method: 'PUT' });
+    return { added: true, siteUrl };
+  }
+
+  // ========== Sitemaps ==========
+
+  async listSitemaps(siteUrl) {
+    const data = await this.makeRequest(`/sites/${encodeURIComponent(siteUrl)}/sitemaps`);
+    return data.sitemap || [];
+  }
+
+  async submitSitemap(siteUrl, sitemapUrl) {
+    await this.makeRequest(
+      `/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(sitemapUrl)}`,
+      { method: 'PUT' },
+    );
+    return { submitted: true, siteUrl, sitemapUrl };
+  }
+
+  // ========== Site Verification ==========
+
+  async makeVerificationRequest(endpoint, options = {}) {
+    return this.auth.makeRequest(`${SITE_VERIFICATION_API_BASE}${endpoint}`, options);
+  }
+
+  /**
+   * Get the verification token for a site. Idempotent — the same token comes
+   * back for the same site+method until it's used.
+   *
+   * @param {string} identifier - Domain (INET_DOMAIN) or URL (SITE)
+   * @param {string} verificationMethod - 'DNS_TXT' | 'DNS_CNAME' | 'FILE' | 'META'
+   * @param {string} type - 'INET_DOMAIN' (domain property) | 'SITE' (URL prefix)
+   */
+  async getVerificationToken(identifier, verificationMethod = 'DNS_TXT', type = 'INET_DOMAIN') {
+    return await this.makeVerificationRequest('/token', {
+      method: 'POST',
+      body: JSON.stringify({
+        site: { type, identifier },
+        verificationMethod,
+      }),
+    });
+  }
+
+  /** Claim ownership once the token is in place (method goes in the query). */
+  async verifySite(identifier, verificationMethod = 'DNS_TXT', type = 'INET_DOMAIN') {
+    return await this.makeVerificationRequest(`/webResource?verificationMethod=${verificationMethod}`, {
+      method: 'POST',
+      body: JSON.stringify({
+        site: { type, identifier },
+      }),
+    });
+  }
+}
+
+module.exports = { GoogleSearchConsoleAPI };

package/dist/services/seo/ensure/github-repos.js

@@ -0,0 +1,271 @@
+/**
+ * Ensure the brand's parasite SEO repos exist and match their template:
+ * create the repo if missing (public, auto-init README), push generated +
+ * static template files (content-compared — unchanged files are never
+ * rewritten), delete stale non-template files, reconcile description/
+ * homepage/topics, and star the repo as the author.
+ *
+ * Collision guardrail (critical safety, ported verbatim): a parasite repo
+ * this handler created only ever contains the template's files, so before
+ * ANY write the existing tree is inspected — more than MAX_STALE_FILES
+ * non-template files means the configured name collides with a REAL repo,
+ * and the item errors without touching anything. Never reuse a real
+ * repo's name for a parasite entry.
+ *
+ * Per-item author identity: author.token (`env:VAR` or literal) overrides
+ * the gh auth for that item's API calls; author.git rides the Contents
+ * API commits as author/committer.
+ */
+const chalk = require('chalk').default;
+
+const { loadTemplate } = require('../templates/index.js');
+
+/**
+ * Maximum non-template ("stale") files tolerated before the handler
+ * refuses to manage the repo — the cap that stops a name collision from
+ * overwriting or wiping a real project. Legit parasite repos sit at 0–2
+ * stale files after a template change.
+ */
+const MAX_STALE_FILES = 10;
+
+/**
+ * Resolve an author token config value (`env:VAR_NAME` reads process.env).
+ */
+function resolveToken(tokenConfig) {
+  if (!tokenConfig) {
+    return null;
+  }
+
+  if (tokenConfig.startsWith('env:')) {
+    const envVar = tokenConfig.slice(4);
+    const value = process.env[envVar];
+
+    if (!value) {
+      console.log(`        ${chalk.yellow('⚠')} Token env var ${envVar} is not set — using default gh auth`);
+      return null;
+    }
+
+    return value;
+  }
+
+  return tokenConfig;
+}
+
+function sleep(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+/**
+ * Poll for the repo after creation — `gh repo create` can silently create
+ * under the authenticated user when the owner is a user account the token
+ * doesn't control, so the caller fails loudly when this returns null.
+ */
+async function waitForRepo(api, slug, token, attempts = 3) {
+  for (let i = 0; i < attempts; i++) {
+    const repo = await api.getRepo(slug, token);
+    if (repo) {
+      return repo;
+    }
+    if (i < attempts - 1) {
+      await sleep(1500);
+    }
+  }
+  return null;
+}
+
+/**
+ * Reconcile one content item to its repo. Returns the item status:
+ * 'created' | 'updated' | 'synced' | 'planned'.
+ */
+async function reconcileItem(api, slug, org, item, brandConfig, token, dryRun) {
+  let repo = await api.getRepo(slug, token);
+  let created = false;
+
+  if (!repo) {
+    const template = loadTemplate(item.template || 'developer-tool');
+    if (dryRun) {
+      console.log(`        ${chalk.cyan('[DRY RUN]')} Would create repo + push ${template.files.length} files`);
+      return 'planned';
+    }
+    await api.createRepo(slug, item.description || '', token);
+    repo = await waitForRepo(api, slug, token);
+    if (!repo) {
+      throw new Error(
+        `repo not created at ${slug} — is "${org}" an org (or user) this token can create repos in? `
+        + `it may have been created under the authenticated account instead`,
+      );
+    }
+    created = true;
+  }
+
+  const template = loadTemplate(item.template || 'developer-tool');
+  const data = { ...item, org, brand: brandConfig.brand };
+  const templatePaths = new Set(template.files.map((f) => f.path));
+
+  // Collision guard: inspect the tree BEFORE modifying anything
+  const tree = await api.getTree(slug, token);
+  const staleFiles = tree.filter((t) => t.type === 'blob' && !templatePaths.has(t.path));
+
+  if (staleFiles.length > MAX_STALE_FILES) {
+    throw new Error(
+      `refusing to manage: ${staleFiles.length} non-template files exceed cap of ${MAX_STALE_FILES} `
+      + `— this looks like a real repo with a name collision, not a parasite repo we created`,
+    );
+  }
+
+  let pushed = 0;
+  let unchanged = 0;
+  let deleted = 0;
+  let planned = 0;
+
+  // Push template files (content-compared; unchanged files skipped)
+  for (const file of template.files) {
+    const content = file.generate ? file.generate(data) : file.content;
+
+    const current = await api.getContents(slug, file.path, token);
+    if (current) {
+      const existing = Buffer.from(current.content, 'base64').toString();
+      if (existing === content) {
+        unchanged++;
+        continue;
+      }
+    }
+
+    if (dryRun) {
+      planned++;
+      continue;
+    }
+
+    const body = {
+      message: current ? `Update ${file.path}` : `Add ${file.path}`,
+      content: Buffer.from(content).toString('base64'),
+    };
+    if (current) {
+      body.sha = current.sha;
+    }
+    if (item.author?.git) {
+      body.author = item.author.git;
+      body.committer = item.author.git;
+    }
+
+    await api.putContents(slug, file.path, body, token);
+    pushed++;
+  }
+
+  // Delete the (few, guardrail-capped) stale files
+  for (const stale of staleFiles) {
+    if (dryRun) {
+      planned++;
+      continue;
+    }
+
+    const meta = await api.getContents(slug, stale.path, token);
+    const body = { message: `Remove ${stale.path}`, sha: meta.sha };
+    if (item.author?.git) {
+      body.author = item.author.git;
+      body.committer = item.author.git;
+    }
+
+    await api.deleteContents(slug, stale.path, body, token);
+    deleted++;
+  }
+
+  if (dryRun && planned > 0) {
+    console.log(`        ${chalk.cyan('[DRY RUN]')} Files: ${planned} would change, ${unchanged} unchanged`);
+  } else if (pushed + deleted > 0) {
+    console.log(`        Files: ${pushed} pushed, ${unchanged} unchanged, ${deleted} deleted`);
+  }
+
+  // Repo settings — normalized compare (the API returns null for empty
+  // fields; omega-manager compared null !== '' and re-PATCHed every run)
+  const description = item.description || '';
+  const homepage = item.cta?.platform || item.cta?.url || brandConfig.brand?.url || '';
+  if ((repo.description || '') !== description || (repo.homepage || '') !== homepage) {
+    if (dryRun) {
+      console.log(`        ${chalk.cyan('[DRY RUN]')} Would update description/homepage`);
+      planned++;
+    } else {
+      await api.patchRepo(slug, { description, homepage }, token);
+      pushed++;
+    }
+  }
+
+  // Topics — order-insensitive compare
+  if (item.topics?.length) {
+    const current = await api.getTopics(slug, token);
+    if ([...current].sort().join(',') !== [...item.topics].sort().join(',')) {
+      if (dryRun) {
+        console.log(`        ${chalk.cyan('[DRY RUN]')} Would set topics: ${item.topics.join(', ')}`);
+        planned++;
+      } else {
+        await api.putTopics(slug, item.topics, token);
+        console.log(`        Topics: ${item.topics.join(', ')}`);
+        pushed++;
+      }
+    }
+  }
+
+  // Star as the author (token) user
+  if (!(await api.isStarred(slug, token))) {
+    if (dryRun) {
+      planned++;
+    } else {
+      await api.starRepo(slug, token);
+      pushed++;
+    }
+  }
+
+  if (created) return 'created';
+  if (dryRun) return planned > 0 ? 'planned' : 'synced';
+  return pushed + deleted > 0 ? 'updated' : 'synced';
+}
+
+module.exports = async (context) => {
+  const { seoApi: api, seoContent: content, brandConfig } = context;
+  const dryRun = context.options?.dryRun || false;
+
+  const defaultOrg = brandConfig.repo?.providers?.github?.org;
+  const results = [];
+
+  for (let i = 0; i < content.length; i++) {
+    const item = content[i];
+    const org = item.org || defaultOrg;
+    const name = item.name;
+
+    if (!org || !name) {
+      console.log(`      ${chalk.red('✗')} [${i + 1}/${content.length}] Missing org or name — skipping`);
+      results.push({ repo: `${org || '?'}/${name || '?'}`, status: 'error', error: 'missing org or name (set item.org or repo.providers.github.org)' });
+      continue;
+    }
+
+    const slug = `${org}/${name}`;
+    console.log(`      [${i + 1}/${content.length}] ${chalk.cyan(slug)}`);
+
+    try {
+      const token = resolveToken(item.author?.token);
+      const status = await reconcileItem(api, slug, org, item, brandConfig, token, dryRun);
+      console.log(`        ${chalk.green('✓')} ${status}`);
+      results.push({ repo: slug, status });
+    } catch (error) {
+      console.log(`        ${chalk.red('✗')} ${error.message}`);
+      results.push({ repo: slug, status: 'error', error: error.message });
+    }
+  }
+
+  const counts = {};
+  for (const result of results) {
+    counts[result.status] = (counts[result.status] || 0) + 1;
+  }
+  console.log(`      Summary: ${results.length} repos — ${Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ')}`);
+
+  const failed = results.filter((r) => r.status === 'error');
+  const output = { githubRepos: { repos: results, ...counts } };
+
+  // Item failures surface as a service error (omega-manager swallowed them
+  // into a success) — items are independent, so the loop still ran them all
+  if (failed.length > 0) {
+    return { output, status: 'error', error: `${failed.length} repo(s) failed: ${failed.map((r) => r.repo).join(', ')}` };
+  }
+
+  return { output };
+};

package/dist/services/seo/index.js

@@ -0,0 +1,55 @@
+/**
+ * SEO service — parasite SEO content: programmatically created GitHub
+ * repos with templated READMEs, download scripts, and a maintenance
+ * workflow, defined per brand under seo.github.content[].
+ *
+ * Content lives in config/omega.json5 (`seo.github.content`) or the
+ * config/seo.json5 sidecar (the chatsy.md/replyify.md convention — big
+ * content sections in their own file; the sidecar's keys merge over the
+ * config's seo section). omega-manager kept the sidecar at
+ * .brands/{id}/seo.json and auto-created a default entry for every brand
+ * — the port never writes config (auto-creating entries is a parked onboarding follow-up); no
+ * content → clean skip.
+ *
+ * Auth: the default `gh` CLI auth, with per-item author overrides
+ * (author.token `env:VAR` + author.git identity) for parasite repos owned
+ * by separate accounts.
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const JSON5 = require('json5');
+
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const ghApi = require('./lib/gh-api.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: (context) => {
+    const config = context.brandConfig.seo;
+
+    if (config === false || config?.enabled === false) {
+      return { skip: true, reason: 'seo.enabled = false' };
+    }
+
+    // Sidecar keys merge over the config's seo section (omega-manager parity)
+    let seo = config || {};
+    const sidecarPath = join(context.brandRoot, 'config', 'seo.json5');
+    if (jetpack.exists(sidecarPath)) {
+      seo = { ...seo, ...JSON5.parse(jetpack.read(sidecarPath)) };
+    }
+
+    if (!seo.github?.content?.length) {
+      return { skip: true, reason: 'no SEO content configured (add seo.github.content to config/omega.json5 or a config/seo.json5 sidecar)' };
+    }
+
+    // Tests inject a fake API via context.seoApi; the real path needs gh
+    // installed + authenticated before any item work starts
+    let seoApi = context.seoApi;
+    if (!seoApi) {
+      ghApi.verifyGhCli();
+      seoApi = ghApi;
+    }
+
+    return { seoApi, seoContent: seo.github.content };
+  },
+});

package/dist/services/seo/lib/gh-api.js

@@ -0,0 +1,161 @@
+/**
+ * GitHub operations for the seo service, over the `gh` CLI. Kept separate
+ * from the github service's GitHubAPI class because parasite repos need a
+ * per-item auth model: every method takes an optional token (the content
+ * item's author identity — a GH_TOKEN env override for that one call),
+ * falling back to the default `gh` auth. Tests fake this surface
+ * method-for-method via context.seoApi.
+ */
+const { execSync } = require('node:child_process');
+
+/**
+ * Build execSync options with an optional GH_TOKEN override.
+ */
+function ghOptions(token) {
+  const opts = { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
+
+  if (token) {
+    opts.env = { ...process.env, GH_TOKEN: token };
+  }
+
+  return opts;
+}
+
+function gh(args, token, input) {
+  const opts = ghOptions(token);
+  if (input !== undefined) {
+    opts.input = input;
+  }
+  try {
+    return execSync(`gh ${args}`, opts).trim();
+  } catch (error) {
+    const stderr = error.stderr?.toString() || error.message;
+    throw new Error(`gh command failed: ${stderr.trim()}`);
+  }
+}
+
+function ghJson(args, token, input) {
+  const result = gh(args, token, input);
+  return result ? JSON.parse(result) : null;
+}
+
+/**
+ * Escape a string for use inside double quotes in a shell command.
+ */
+function shellEscape(str) {
+  return str.replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
+}
+
+/**
+ * Verify gh CLI is installed and authenticated (default auth — per-item
+ * tokens are validated by their own API calls).
+ */
+function verifyGhCli() {
+  try {
+    execSync('gh --version', { encoding: 'utf8', stdio: 'pipe' });
+  } catch {
+    throw new Error('GitHub CLI (gh) is not installed. Install from: https://cli.github.com/');
+  }
+
+  try {
+    execSync('gh auth status', { encoding: 'utf8', stdio: 'pipe' });
+  } catch {
+    throw new Error('GitHub CLI is not authenticated. Run: gh auth login (or set GH_TOKEN in the brand .env)');
+  }
+}
+
+/** Repo details, or null when it doesn't exist. */
+function getRepo(slug, token) {
+  try {
+    return ghJson(`api repos/${slug}`, token);
+  } catch (error) {
+    if (error.message.includes('404')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/** Create a public repo with an auto-init README. */
+function createRepo(slug, description, token) {
+  const desc = description ? ` --description "${shellEscape(description)}"` : '';
+  gh(`repo create ${slug} --public --add-readme${desc}`, token);
+}
+
+/** Flat file tree of the main branch ([{ path, type }]); [] when unreadable (e.g. empty repo). */
+function getTree(slug, token) {
+  try {
+    const tree = ghJson(`api repos/${slug}/git/trees/main?recursive=1`, token);
+    return tree?.tree || [];
+  } catch {
+    return [];
+  }
+}
+
+/** Contents-API file record ({ content: base64, sha }), or null when absent. */
+function getContents(slug, path, token) {
+  try {
+    return ghJson(`api repos/${slug}/contents/${path}`, token);
+  } catch (error) {
+    if (error.message.includes('404')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/** Create/update a file via the Contents API (body: message, content, sha?, author?, committer?). */
+function putContents(slug, path, body, token) {
+  return ghJson(`api repos/${slug}/contents/${path} -X PUT --input -`, token, JSON.stringify(body));
+}
+
+/** Delete a file via the Contents API (body: message, sha, author?, committer?). */
+function deleteContents(slug, path, body, token) {
+  return ghJson(`api repos/${slug}/contents/${path} -X DELETE --input -`, token, JSON.stringify(body));
+}
+
+/** PATCH repo settings from a JSON body (description, homepage, ...). */
+function patchRepo(slug, fields, token) {
+  return ghJson(`api repos/${slug} -X PATCH --input -`, token, JSON.stringify(fields));
+}
+
+/** Current topic names. */
+function getTopics(slug, token) {
+  const result = ghJson(`api repos/${slug}/topics`, token);
+  return result?.names || [];
+}
+
+/** Replace the topic set. */
+function putTopics(slug, names, token) {
+  return ghJson(`api repos/${slug}/topics -X PUT --input -`, token, JSON.stringify({ names }));
+}
+
+/** Whether the authenticated (token) user has starred the repo. */
+function isStarred(slug, token) {
+  try {
+    gh(`api user/starred/${slug} -X GET`, token);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Star the repo as the authenticated (token) user. */
+function starRepo(slug, token) {
+  gh(`api user/starred/${slug} -X PUT`, token);
+}
+
+module.exports = {
+  verifyGhCli,
+  getRepo,
+  createRepo,
+  getTree,
+  getContents,
+  putContents,
+  deleteContents,
+  patchRepo,
+  getTopics,
+  putTopics,
+  isStarred,
+  starRepo,
+};

package/dist/services/seo/templates/developer-tool/.github/workflows/maintenance.yml

@@ -0,0 +1,25 @@
+name: Maintenance
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 1 * * *'
+
+permissions:
+  contents: write
+
+jobs:
+  ping:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Bump maintenance branch
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+          git checkout maintenance 2>/dev/null || git checkout -b maintenance
+          git commit --allow-empty --amend -m "Maintenance" || git commit --allow-empty -m "Maintenance"
+          git push --force origin maintenance

package/dist/services/seo/templates/developer-tool/.nvmrc

@@ -0,0 +1 @@
+22