@omega.js/manager 0.1.0

package/dist/services/seo/templates/developer-tool/_README.md.js

@@ -0,0 +1,121 @@
+/**
+ * README.md generator for the developer-tool template — hero with badges,
+ * platform download buttons, features, star-history chart, contributing.
+ */
+
+// Windows brand icon as a base64 SVG — shields.io renders macOS/Linux from
+// its built-in logo set but has no working Windows logo, so it's inlined.
+const ICON_WINDOWS = 'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NDggNTEyIj48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTAgOTMuN2wxODMuNi0yNS4zIDAgMTc3LjQtMTgzLjYgMCAwLTE1Mi4xek0wIDQxOC4zbDE4My42IDI1LjMgMC0xNzUuMi0xODMuNiAwIDAgMTQ5Ljl6bTIwMy44IDI4bDI0NC4yIDMzLjcgMC0yMTEuNi0yNDQuMiAwIDAgMTc3Ljl6bTAtMzgwLjZsMCAxODAuMSAyNDQuMiAwIDAtMjEzLjgtMjQ0LjIgMzMuN3oiLz48L3N2Zz4=';
+
+/**
+ * Generate README.md from content item + brand data
+ *
+ * @param {Object} data - { name, org, title, description, features, cta, custom, brand }
+ * @returns {string} Generated markdown
+ */
+module.exports = function generateReadme(data) {
+  const { name, org, title, description, features, cta, custom, brand } = data;
+
+  const brandmarkUrl = brand?.images?.brandmark || '';
+  const platformUrl = cta?.platform || cta?.url || brand?.url || '';
+  const downloadUrl = cta?.url || brand?.url || '';
+  const brandUrl = brand?.url || '';
+  const brandDescription = brand?.description || '';
+  const domain = brandUrl.replace(/^https?:\/\//, '').replace(/\/$/, '');
+  const encodedUrl = encodeURIComponent(brandUrl);
+
+  const lines = [];
+
+  // --- Hero ---
+  lines.push('<div align="center">');
+  lines.push('');
+  lines.push(`<img src="${brandmarkUrl}" width="60" alt="${title} Logo">`);
+  lines.push('');
+  lines.push(`<h1>${title}</h1>`);
+  lines.push('');
+  lines.push(`<p><strong>Free <a href="${platformUrl}">${title.toLowerCase()}</a></strong> that ${description}</p>`);
+  lines.push('');
+  lines.push('<p>');
+  lines.push(`<a href="${downloadUrl}"><img src="https://img.shields.io/badge/Download-Free-28a745?style=for-the-badge" alt="Download Free"></a>`);
+  lines.push('&nbsp;');
+  lines.push(`<a href="${platformUrl}"><img src="https://img.shields.io/badge/Website-${domain}-blue?style=for-the-badge" alt="Visit Website"></a>`);
+  lines.push('</p>');
+  lines.push('');
+  lines.push('<p>');
+  lines.push(`<a href="https://github.com/${org}/${name}/stargazers"><img src="https://img.shields.io/github/stars/${org}/${name}?style=flat-square&logo=github" alt="Stars"></a>`);
+  lines.push(`<a href="https://github.com/${org}/${name}/network/members"><img src="https://img.shields.io/github/forks/${org}/${name}?style=flat-square&logo=github" alt="Forks"></a>`);
+  lines.push(`<a href="https://github.com/${org}/${name}/issues"><img src="https://img.shields.io/github/issues/${org}/${name}?style=flat-square" alt="Issues"></a>`);
+  lines.push(`<a href="${brandUrl}"><img src="https://img.shields.io/website?url=${encodedUrl}&style=flat-square" alt="Website"></a>`);
+  lines.push('</p>');
+  lines.push('');
+  lines.push('</div>');
+  lines.push('');
+  lines.push('<br>');
+  lines.push('');
+
+  // --- Blockquote ---
+  lines.push(`> ${brandDescription}`);
+  lines.push('');
+  lines.push('<br>');
+  lines.push('');
+
+  // --- Getting Started ---
+  lines.push('## 🚀 Getting Started');
+  lines.push('');
+  lines.push('### Option 1: Direct download (recommended)');
+  lines.push('');
+  lines.push('Download the app for your platform.');
+  lines.push('');
+  lines.push(`<a href="${downloadUrl}?download=windows"><img src="https://img.shields.io/badge/Windows-0078D4?style=for-the-badge&logo=data:image/svg+xml;base64,${ICON_WINDOWS}" alt="Windows"></a>&nbsp;`);
+  lines.push(`<a href="${downloadUrl}?download=macos"><img src="https://img.shields.io/badge/macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="macOS"></a>&nbsp;`);
+  lines.push(`<a href="${downloadUrl}?download=linux"><img src="https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Linux"></a>`);
+  lines.push('');
+  lines.push('### Option 2: From source');
+  lines.push('');
+  lines.push('Requires [Node.js](https://nodejs.org) and [Git](https://git-scm.com).');
+  lines.push('');
+  lines.push('```bash');
+  lines.push(`git clone https://github.com/${org}/${name}.git`);
+  lines.push(`cd ${name}`);
+  lines.push('npm install');
+  lines.push('npm start');
+  lines.push('```');
+  lines.push('');
+
+  // --- Features ---
+  if (features?.length) {
+    lines.push('## ✨ Features');
+    lines.push('');
+    for (const feature of features) {
+      lines.push(`- ${feature}`);
+    }
+    lines.push('');
+  }
+
+  // --- Custom markdown ---
+  if (custom) {
+    lines.push(custom);
+    lines.push('');
+  }
+
+  // --- Star History ---
+  lines.push('## ⭐ Star History');
+  lines.push('');
+  lines.push(`<a href="https://www.star-history.com/#${org}/${name}&Date">`);
+  lines.push('  <picture>');
+  lines.push(`    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=${org}/${name}&type=Date&theme=dark" />`);
+  lines.push(`    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=${org}/${name}&type=Date" />`);
+  lines.push(`    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=${org}/${name}&type=Date" width="100%" />`);
+  lines.push('  </picture>');
+  lines.push('</a>');
+  lines.push('');
+
+  // --- Contributing ---
+  lines.push('## 🤝 Contributing');
+  lines.push('');
+  lines.push('Contributions are welcome. Issues, pull requests, feature ideas, documentation, design.');
+  lines.push('');
+  lines.push('<sub>If this project helped you grow, consider giving it a ⭐</sub>');
+
+  return lines.join('\n');
+};

package/dist/services/seo/templates/developer-tool/_package.json.js

@@ -0,0 +1,33 @@
+/**
+ * package.json generator for the developer-tool template.
+ */
+
+/**
+ * Generate package.json from content item + brand data
+ *
+ * @param {Object} data - { name, org, title, description, cta, topics, brand }
+ * @returns {string} Stringified JSON
+ */
+module.exports = function generatePackageJson(data) {
+  const { name, org, title, description, cta, topics, brand } = data;
+
+  const pkg = {
+    name: `${org}-${name}`,
+    version: '1.0.0',
+    description: `${title} ${description}`,
+    main: 'src/index.js',
+    scripts: {
+      start: 'node src/index.js',
+    },
+    keywords: topics || [],
+    author: brand?.name || '',
+    license: 'ISC',
+    homepage: cta?.platform || cta?.url || brand?.url || '',
+    repository: {
+      type: 'git',
+      url: `git+https://github.com/${org}/${name}.git`,
+    },
+  };
+
+  return JSON.stringify(pkg, null, 2) + '\n';
+};

package/dist/services/seo/templates/developer-tool/src/index.js

@@ -0,0 +1,120 @@
+const { exec } = require('child_process');
+const { createWriteStream } = require('fs');
+const { pipeline } = require('stream/promises');
+const os = require('os');
+const path = require('path');
+const pkg = require('../package.json');
+
+const PLATFORM_MAP = {
+  darwin: 'mac',
+  win32: 'windows',
+  linux: 'linux',
+};
+
+function log(msg) {
+  console.log(`[${new Date().toLocaleTimeString()}] ${msg}`);
+}
+
+function getDownloadsFolder() {
+  return path.join(os.homedir(), 'Downloads');
+}
+
+function launchFile(filePath) {
+  const platform = os.platform();
+  log(`Launching ${filePath}...`);
+
+  if (platform === 'darwin') {
+    exec(`open "${filePath}"`);
+  } else if (platform === 'win32') {
+    exec(`start "" "${filePath}"`);
+  } else {
+    exec(`xdg-open "${filePath}"`);
+  }
+}
+
+async function main() {
+  const platform = os.platform();
+  const platformKey = PLATFORM_MAP[platform] || 'linux';
+
+  log(`${pkg.name} v${pkg.version}`);
+  log(`Platform: ${platform} (${platformKey})`);
+
+  // Fetch download URLs from the website's config.json
+  const siteUrl = new URL(pkg.homepage).origin;
+  const configUrl = `${siteUrl}/config.json`;
+  log(`Fetching download info from ${configUrl}...`);
+
+  const configRes = await fetch(configUrl);
+
+  if (!configRes.ok) {
+    throw new Error(`Failed to fetch config: ${configRes.status} ${configRes.statusText}`);
+  }
+
+  const config = await configRes.json();
+  const downloads = config.download || {};
+  const platformDownloads = downloads[platformKey];
+
+  if (!platformDownloads) {
+    throw new Error(`No downloads available for ${platformKey}`);
+  }
+
+  const url = platformDownloads.universal || platformDownloads.debian || '';
+
+  if (!url) {
+    throw new Error(`No download URL found for ${platformKey}`);
+  }
+
+  log(`Download URL: ${url}`);
+
+  // Download the file
+  const fileName = url.split('/').pop();
+  const filePath = path.join(getDownloadsFolder(), fileName);
+
+  log(`Downloading to ${filePath}...`);
+
+  const downloadRes = await fetch(url);
+
+  if (!downloadRes.ok) {
+    throw new Error(`Download failed: ${downloadRes.status} ${downloadRes.statusText}`);
+  }
+
+  const fileStream = createWriteStream(filePath);
+  await pipeline(downloadRes.body, fileStream);
+
+  log(`Download complete: ${fileName}`);
+
+  // Install and launch
+  if (platform === 'darwin' && fileName.endsWith('.dmg')) {
+    log('Mounting DMG...');
+    const { execSync } = require('child_process');
+    const mountOutput = execSync(`hdiutil attach "${filePath}" -nobrowse`, { encoding: 'utf8' });
+    const mountPoint = mountOutput.split('\t').pop().trim();
+    log(`Mounted at ${mountPoint}`);
+
+    const appName = require('fs').readdirSync(mountPoint).find((f) => f.endsWith('.app'));
+
+    if (appName) {
+      const appSource = path.join(mountPoint, appName);
+      const appDest = path.join('/Applications', appName);
+      log(`Copying ${appName} to /Applications...`);
+      execSync(`cp -R "${appSource}" "${appDest}"`);
+      log('Launching app...');
+      exec(`open "${appDest}"`);
+      log(`Ejecting ${mountPoint}...`);
+      exec(`hdiutil detach "${mountPoint}"`);
+    } else {
+      log('No .app found in DMG, opening manually...');
+      launchFile(filePath);
+    }
+  } else {
+    launchFile(filePath);
+  }
+
+  log('Done!');
+}
+
+main().catch((err) => {
+  console.error(`[${new Date().toLocaleTimeString()}] Error: ${err.message}`);
+  console.log(`\nVisit ${pkg.homepage} to download manually.`);
+  process.exit(1);
+});

package/dist/services/seo/templates/index.js

@@ -0,0 +1,57 @@
+/**
+ * SEO template registry with convention-based auto-discovery. Each template
+ * is a directory here; files starting with `_` and ending with `.js` are
+ * generators (strip both → target path, e.g. _README.md.js → README.md),
+ * everything else is a static file pushed as-is.
+ */
+const { join, relative, resolve, dirname, basename } = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const TEMPLATES = [
+  'developer-tool',
+];
+
+const loaded = {};
+
+for (const name of TEMPLATES) {
+  const templateDir = join(__dirname, name);
+  // find() returns cwd-relative paths — resolve to absolute so template
+  // loading works from any cwd (the manager runs from the brand root)
+  const allPaths = jetpack.find(templateDir, { recursive: true, files: true }).map((p) => resolve(p));
+  const files = [];
+
+  for (const absPath of allPaths) {
+    const relPath = relative(templateDir, absPath);
+    const fileName = basename(absPath);
+
+    if (fileName.startsWith('_') && fileName.endsWith('.js')) {
+      const targetName = fileName.slice(1, -3);
+      const dir = dirname(relPath);
+      const targetPath = dir === '.' ? targetName : join(dir, targetName);
+      files.push({ path: targetPath, generate: require(absPath) });
+    } else {
+      files.push({ path: relPath, content: jetpack.read(absPath) });
+    }
+  }
+
+  loaded[name] = { files };
+}
+
+/**
+ * Load a template by name
+ *
+ * @param {string} name - Template name (e.g. 'developer-tool')
+ * @returns {{ files: Array<{path: string, generate?: Function, content?: string}> }}
+ */
+function loadTemplate(name) {
+  const template = loaded[name];
+
+  if (!template) {
+    const available = Object.keys(loaded).join(', ');
+    throw new Error(`Unknown SEO template: "${name}". Available: ${available}`);
+  }
+
+  return template;
+}
+
+module.exports = { loadTemplate };

package/dist/services/server/ensure/brands.js

@@ -0,0 +1,63 @@
+/**
+ * Sync the brand's registry entry to the company server's Firestore at
+ * brands/{brand.id}. Only the whitelisted top-level config sections cross
+ * (brand identity, repo org info, sponsorship terms), and the document
+ * is fully REPLACED on write so keys removed from config disappear from
+ * the registry too — omega-manager's `set(data, { merge: false })`
+ * semantic, but diff-synced: omega-manager overwrote the document blindly
+ * on every run with no dry-run guard; the port reads first and only
+ * writes on drift.
+ */
+const chalk = require('chalk').default;
+
+// Only these top-level config sections are published to the registry
+const SYNCED_KEYS = ['brand', 'repo', 'sponsorships'];
+
+/** Structural equality, key-order-insensitive — a full-replace write means
+ * ANY difference (including extra keys in the current doc) is drift. */
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (a && b && typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+    const aKeys = Object.keys(a);
+    return aKeys.length === Object.keys(b).length && aKeys.every((key) => key in b && deepEqual(a[key], b[key]));
+  }
+  return false;
+}
+
+module.exports = async function ensureBrands(context) {
+  const { brandConfig, db, options } = context;
+  const dryRun = options?.dryRun || false;
+
+  const registryId = brandConfig.brand.id;
+  const docPath = `brands/${registryId}`;
+
+  const desired = {};
+  for (const key of SYNCED_KEYS) {
+    if (brandConfig[key] !== undefined) {
+      desired[key] = brandConfig[key];
+    }
+  }
+
+  const current = await db.getDoc(docPath);
+
+  if (deepEqual(current, desired)) {
+    console.log(`      ${chalk.green('✓')} Registry entry ${chalk.dim(docPath)} in sync`);
+    return { output: { brands: { synced: true } } };
+  }
+
+  const action = current ? 'update' : 'create';
+
+  if (dryRun) {
+    console.log(`      ${chalk.yellow('[DRY RUN]')} Would ${action} registry entry ${chalk.cyan(docPath)}`);
+    return { output: { brands: { planned: action } } };
+  }
+
+  await db.setDoc(docPath, desired);
+
+  console.log(`      ${chalk.green('✓')} Registry entry ${chalk.dim(docPath)} ${action}d`);
+
+  return { output: { brands: { [`${action}d`]: true } } };
+};

package/dist/services/server/index.js

@@ -0,0 +1,42 @@
+/**
+ * Server service — publishes the brand's registry entry to the company
+ * server's Firestore at brands/{brand.id}. The company's parent backend
+ * keeps a registry of every brand it serves (webhook fan-out, cross-brand
+ * features read it); this service keeps that entry in sync with the brand
+ * config.
+ *
+ * Auth: SERVER_SERVICE_ACCOUNT in the brand .env — a path to the company
+ * server's Firebase service-account JSON (absolute, or relative to the
+ * brand root). omega-manager hardcoded the company project
+ * ('itw-creative-works') and read its secrets from the company-instance
+ * .output/ tree instead; its legacy-brand `_` prefix skip was a
+ * company-instance convention and is dropped.
+ */
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { FirestoreREST, loadServiceAccount } = require('../../lib/firestore-rest.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const config = context.brandConfig.server;
+
+    if (config === false || config?.enabled === false) {
+      return { skip: true, reason: 'server.enabled = false' };
+    }
+
+    // Tests inject a fake client via context.serverDb
+    let db = context.serverDb;
+    if (!db) {
+      // The shared setup contract (#608): a company-server operator provides
+      // the path here; every standalone brand answers Disable once and is
+      // never asked again.
+      const gate = await requestServiceInput(context, serviceInputSpec('server'));
+      if (gate) return gate;
+      db = new FirestoreREST(loadServiceAccount(process.env.SERVER_SERVICE_ACCOUNT, context.brandRoot));
+    }
+
+    return { db };
+  },
+});

package/dist/services/testing/ensure/target-checks.js

@@ -0,0 +1,97 @@
+/**
+ * Per-target health checks, grouped by target — omega-manager's target-checks
+ * for brand monorepos. Local checks always run; live checks (homepage, API
+ * health, npm latest, GitHub Actions) are skipped in dry-run with a "would"
+ * line, so a dry run never touches the network.
+ *
+ * Checks by target:
+ *   web      → package.json, dist/index.html, installed framework vs npm
+ *              latest, homepage fetch
+ *   backend  → package.json, firebase.json, staged dist/ (build output),
+ *              installed framework vs npm latest, API health + deployed
+ *              version (skipped for shared Firebase projects)
+ *   (all)    → package.json, framework version when declared
+ *
+ * Repo-level (once): working tree clean, latest GitHub Actions run (only
+ * with repo.providers.github.org configured).
+ *
+ * The output shape matches omega-manager's testing service so RunSummary's
+ * drill-down works unchanged. Data problems roll up honestly: any failed
+ * check → error, any warning → warned.
+ *
+ * omega-manager deltas: build.json check stays behind (a UJM artifact —
+ * @omega.js/web has no build manifest); the stash check stays behind (nothing
+ * stashes in the new update service); GitHub Actions is repo-level (one repo
+ * per brand, not one per target).
+ */
+const chalk = require('chalk').default;
+
+const {
+  createRecorder,
+  defaultExec,
+  checkTargetFiles,
+  checkFrameworkVersion,
+  checkWorkingTree,
+  checkHomepage,
+  checkApiHealth,
+  checkGitHubActions,
+} = require('../lib/checks.js');
+
+module.exports = async (context) => {
+  const { brandId, brandRoot, brandConfig, targets, options } = context;
+
+  // Tests inject fetch/exec/retryDelayMs via options (they ride runManage
+  // options so full-loop tests stay network-free); production uses the reals
+  const ctx = {
+    brandId,
+    brandRoot,
+    brandConfig,
+    dryRun: options?.dryRun || false,
+    fetchImpl: options?.fetch || globalThis.fetch,
+    exec: options?.exec || defaultExec,
+    retryDelayMs: options?.retryDelayMs ?? 1000,
+    versionCache: {},
+  };
+
+  const recorder = createRecorder();
+
+  for (const entry of targets.filter((item) => item.target)) {
+    console.log(`      ${chalk.cyan('┌')} ${chalk.cyan.bold(entry.name)} ${chalk.dim(`→ ${entry.target}`)}`);
+
+    checkTargetFiles(recorder, entry);
+    checkFrameworkVersion(recorder, entry, ctx);
+
+    if (entry.target === 'web') {
+      await checkHomepage(recorder, entry, ctx);
+    }
+
+    if (entry.target === 'backend') {
+      await checkApiHealth(recorder, entry, ctx);
+    }
+
+    console.log(`      ${chalk.cyan('└')}`);
+  }
+
+  console.log(`      ${chalk.cyan('┌')} ${chalk.cyan.bold('repo')}`);
+  checkWorkingTree(recorder, ctx);
+  checkGitHubActions(recorder, ctx);
+  console.log(`      ${chalk.cyan('└')}`);
+
+  const { passed, warned, failed } = recorder.results();
+  const status = failed.length > 0 ? 'error' : warned.length > 0 ? 'warned' : 'success';
+
+  return {
+    status,
+    ...(failed.length > 0 ? { error: failed.map((f) => f.name).join(', ') } : {}),
+    // The reason carries each warned check's own text, not just its name —
+    // the summary line is all a run prints for a warned service, so
+    // `outdated (1.0.0 → 1.2.0)` has to survive the rollup.
+    ...(status === 'warned'
+      ? { reason: warned.map((w) => (w.warning ? `${w.name}: ${w.warning}` : w.name)).join('; ') }
+      : {}),
+    output: {
+      results: { passed, warned, failed },
+      counts: recorder.counts(),
+    },
+  };
+};

package/dist/services/testing/index.js

@@ -0,0 +1,11 @@
+/**
+ * Testing service — health checks after every other service ran. Same role
+ * as omega-manager's testing service: per-target local checks (build output,
+ * backend scaffolding, framework version vs npm latest) plus live checks
+ * against the deployed brand (homepage, API health + deployed version,
+ * GitHub Actions). Live checks skip under --dry-run — a dry run never
+ * touches the network.
+ */
+const { createServiceRunner } = require('../../lib/service-runner.js');
+
+module.exports.run = createServiceRunner({ serviceDir: __dirname });