@omega.js/manager 0.1.0

package/dist/devlog/index.js

@@ -0,0 +1,226 @@
+/**
+ * Devlog — auto-generated commit-digest blog posts: collect recent commits
+ * across GitHub orgs + brand repos → have Ghostii write a first-person devlog
+ * article → publish to the brand's website target (syndication platforms later).
+ *
+ * Standalone command, not a service: publishing a new post every run is not
+ * idempotent reconciliation, so devlog never runs during manage. Stateless by
+ * design — every run computes `since = now − lookbackDays` and fetches fresh;
+ * nothing is read from or written to .omega/runs/. Running
+ * twice in one window writes two posts about the same commits — the cadence
+ * is owned by whoever runs it.
+ *
+ * Works from a brand root (that brand publishes; company siblings via the
+ * .omega/company.json stamp still feed the backlink map) or a company root
+ * (--brand, or the single brand with devlog.enabled).
+ */
+
+const { join } = require('node:path');
+
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+const { loadEnvRoots, chosenProvider } = require('../vendor/config/index.js');
+
+const { resolveBrandRoot, loadBrand } = require('../lib/brand.js');
+const {
+  isCompanyRoot, discoverBrands, readCompanyMarker,
+} = require('../lib/company.js');
+const { GitHubAPI } = require('../services/repo/lib/github-api.js');
+const { collectCommits } = require('./lib/collect-commits.js');
+const { buildProjectMap, buildBrandRepos } = require('./lib/project-map.js');
+const { generatePost } = require('./lib/generate-post.js');
+const { publishToWebsite, renderPostFile } = require('./lib/publish-website.js');
+
+/**
+ * Pick the brand that publishes: explicit --brand wins; otherwise exactly one
+ * loaded brand must have devlog.enabled.
+ *
+ * @param {Array} brands - Loaded brands (lib/brand.js loadBrand shape)
+ * @param {string} [explicitId] - Brand ID passed via --brand
+ * @returns {object} The publishing brand
+ */
+function pickBrand(brands, explicitId) {
+  if (explicitId) {
+    const brand = brands.find((b) => b.id === explicitId);
+    if (!brand) {
+      throw new Error(`Brand not found: ${explicitId} (known: ${brands.map((b) => b.id).join(', ')})`);
+    }
+    return brand;
+  }
+
+  const enabled = brands.filter((b) => b.config.devlog.enabled === true);
+
+  if (enabled.length === 0) {
+    throw new Error('No brand has devlog.enabled — set it in the brand\'s config/omega.json5 or pass --brand');
+  }
+  if (enabled.length > 1) {
+    throw new Error(`Multiple brands have devlog.enabled (${enabled.map((b) => b.id).join(', ')}) — pass --brand`);
+  }
+
+  return enabled[0];
+}
+
+/**
+ * Resolve the run context from any cwd: the publishing brand, every sibling
+ * brand (they feed the backlink map — the brand configs are the SSOT for
+ * where repos live), and the company root when one is in play.
+ *
+ * @param {string} startDir - Any directory inside a brand or company workspace
+ * @param {string} [explicitId] - Brand ID passed via --brand
+ * @returns {{ brand: object, brands: Array, companyRoot: string|null }}
+ */
+function resolveContext(startDir, explicitId) {
+  const root = resolveBrandRoot(startDir);
+
+  if (!root) {
+    throw new Error(
+      `No brand or company workspace found at or above ${startDir} — `
+      + 'expected a config/omega.json5 at the root (see docs/shared/config.md).',
+    );
+  }
+
+  // Company root: every managed brand loads with the company layer (folded by
+  // @omega.js/config off each brand's own .omega/company.json stamp — #83); the
+  // publishing brand is picked from among them.
+  if (isCompanyRoot(root)) {
+    const brands = discoverBrands(root).brands.map((b) => loadBrand(b.root));
+
+    if (brands.length === 0) {
+      throw new Error(`No brands found under ${root} — nothing to devlog about`);
+    }
+
+    return { brand: pickBrand(brands, explicitId), brands, companyRoot: root };
+  }
+
+  // Brand root: this brand publishes. The company stamp (when present and
+  // fresh) surfaces the sibling brands for the project map and the company
+  // .env; the config layer itself rides the same stamp inside loadBrand.
+  const marker = readCompanyMarker(root);
+  let companyRoot = null;
+
+  if (marker?.stale) {
+    console.log(chalk.yellow(`⚠ .omega/company.json points at ${marker.companyRoot}, which is no longer a company workspace — running standalone`));
+  } else if (marker) {
+    companyRoot = marker.companyRoot;
+  }
+
+  const brand = loadBrand(root);
+
+  if (explicitId && explicitId !== brand.id) {
+    throw new Error(`--brand=${explicitId} does not match this brand root (${brand.id}) — run from the company root to target siblings`);
+  }
+
+  let brands = [brand];
+  if (companyRoot) {
+    const siblings = discoverBrands(companyRoot).brands
+      .filter((b) => b.id !== brand.id)
+      .map((b) => loadBrand(b.root));
+    brands = [brand, ...siblings];
+  }
+
+  return { brand, brands, companyRoot };
+}
+
+/**
+ * Main devlog runner: collect commits → map projects → generate post →
+ * publish (or preview on --dry-run).
+ *
+ * @param {string} startDir - Any directory inside the brand/company workspace
+ * @param {object} [options] - { brand?, days?, dryRun? }
+ * @param {object} [deps] - Test seams: { githubApi?, generatePost? } — prod
+ *   callers pass nothing and get the real GitHubAPI + Ghostii pipeline
+ * @returns {Promise<{ published: boolean, commits: number, previewPath?: string, posts?: Array }>}
+ */
+async function runDevlog(startDir, options = {}, deps = {}) {
+  console.log(chalk.bold.cyan('Omega Manager — Devlog'));
+  console.log('');
+
+  const { brand, brands, companyRoot } = resolveContext(startDir, options.brand);
+
+  if (!brand.config.devlog.enabled) {
+    throw new Error(`Devlog is disabled for ${brand.id} — set devlog.enabled: true`);
+  }
+
+  // The writer is a KEY under devlog.providers (#425) and its settings live
+  // inside it — the role level carries only `enabled`.
+  const writer = chosenProvider(brand.config.devlog.providers);
+  if (!writer) {
+    throw new Error(`No devlog writer configured for ${brand.id} — add devlog.providers.ghostii`);
+  }
+  const settings = brand.config.devlog.providers[writer];
+
+  if (!settings.orgs.length) {
+    throw new Error(`No devlog.providers.${writer}.orgs configured for ${brand.id}`);
+  }
+
+  // Secrets chain: shell env > brand .env > company .env — the shared
+  // cascade (files load strongest-first, never overriding what's set), each
+  // layer overlaid by its own `.env.<environment>` file (#586). `production`
+  // is PINNED, never the shell's answer: a devlog run reads REAL GitHub and
+  // publishes with the brand's real writer account.
+  loadEnvRoots([brand.root, companyRoot], { environment: 'production' });
+
+  const days = Number(options.days || settings.lookbackDays);
+  const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+
+  console.log(`${chalk.dim('→')} Brand: ${chalk.cyan(brand.config.brand?.name || brand.id)} (${brand.id})`);
+  console.log(`${chalk.dim('→')} Window: last ${days} days (since ${since.toISOString()})`);
+  console.log('');
+
+  // 1. Brand configs are the SSOT for repos: the backlink map + the full repo
+  //    list across every brand (the `orgs` list only adds non-brand repos
+  //    like frameworks and tooling)
+  const projectMap = buildProjectMap(brands, { excludeRepos: settings.excludeRepos });
+  const brandRepos = buildBrandRepos(brands, { excludeRepos: settings.excludeRepos });
+
+  // 2. Collect commits from GitHub
+  const api = deps.githubApi || new GitHubAPI();
+  const { commits, repos } = collectCommits({
+    api,
+    orgs: settings.orgs,
+    brandRepos,
+    since,
+    excludeRepos: settings.excludeRepos,
+    excludeCommits: settings.excludeCommits,
+    includePrivate: settings.includePrivate,
+  });
+
+  if (!commits.length) {
+    console.log(`${chalk.yellow('⚠')} No commits found in the last ${days} days — nothing to write about`);
+    return { published: false, commits: 0 };
+  }
+
+  console.log('');
+  console.log(`${chalk.green('✓')} Collected ${commits.length} commits across ${repos.length} repos`);
+
+  // 3. Generate the post
+  console.log(`${chalk.dim('→')} Generating post via ${writer}...`);
+  const generate = deps.generatePost || generatePost;
+  const post = await generate({ brandConfig: brand.config, commits, projectMap, days });
+  console.log(`${chalk.green('✓')} Generated: ${chalk.cyan(post.title)}`);
+  console.log('');
+
+  // 4. Publish (or preview on --dry-run)
+  if (options.dryRun) {
+    const previewPath = join(brand.root, '.omega', 'devlog', `${post.slug}.md`);
+    jetpack.write(previewPath, renderPostFile(brand.config, post));
+    console.log(`${chalk.green('✓')} Dry run — preview written to ${chalk.cyan(previewPath)}`);
+    return { published: false, commits: commits.length, previewPath };
+  }
+
+  const posts = [];
+  for (const destination of settings.destinations) {
+    if (destination === 'website') {
+      const { postPath, url } = publishToWebsite({ brand, post });
+      posts.push({ destination, postPath, url });
+      console.log(`${chalk.green('✓')} Website: ${chalk.cyan(postPath)}`);
+      console.log(`  ${chalk.dim('→')} Live at ${chalk.cyan(url)} after the site build finishes`);
+    } else {
+      console.log(`${chalk.yellow('⚠')} Destination not implemented yet: ${destination}`);
+    }
+  }
+
+  return { published: posts.length > 0, commits: commits.length, posts };
+}
+
+module.exports = { runDevlog };

package/dist/devlog/lib/collect-commits.js

@@ -0,0 +1,136 @@
+/**
+ * Devlog collect stage — build the scan worklist (org listings + brand-derived
+ * repos) and pull every eligible commit since the window start via the gh CLI.
+ * Org listings come with metadata (archived, pushed_at, private, homepage) so
+ * inactive repos are pre-filtered; brand repos get a direct commits probe.
+ */
+
+const chalk = require('chalk').default;
+
+// Newest-first cap per repo so fleet-wide automated pushes can't drown the digest
+const MAX_COMMITS_PER_REPO = 30;
+
+/**
+ * Run a paginated `gh api` call and merge multi-page output.
+ * `--paginate` concatenates page arrays back-to-back (`[...][...]`), which
+ * breaks JSON.parse — join the boundaries before parsing.
+ *
+ * @param {object} api - GitHubAPI client
+ * @param {string} path - API path including query string
+ * @returns {Array} Parsed results (empty array when no output)
+ */
+function runPaginatedJson(api, path) {
+  const raw = api.runCommand(['api', path, '--paginate']);
+
+  if (!raw) {
+    return [];
+  }
+
+  return JSON.parse(raw.replace(/\]\s*\[/g, ','));
+}
+
+/**
+ * List repos for a GitHub owner — org endpoint first, user endpoint fallback
+ * (devlog.providers.ghostii.orgs may mix orgs and personal accounts).
+ *
+ * @param {object} api - GitHubAPI client
+ * @param {string} owner - Org or user name
+ * @returns {Array} Repos
+ */
+function listReposForOwner(api, owner) {
+  try {
+    return runPaginatedJson(api, `orgs/${owner}/repos?per_page=100`);
+  } catch {
+    return runPaginatedJson(api, `users/${owner}/repos?per_page=100`);
+  }
+}
+
+/**
+ * Collect commits since a given date across the full scan worklist: every
+ * repo in the configured `orgs` listings PLUS every brand repo derived from
+ * the brand configs. Skips archived/excluded repos, merge/bot/fleet commits,
+ * and excludeCommits matches.
+ *
+ * @param {object} params - { api, orgs, brandRepos, since, excludeRepos, excludeCommits, includePrivate }
+ * @returns {{ commits: Array, repos: Array<string> }} Commits + active repo full names
+ */
+function collectCommits({ api, orgs = [], brandRepos = [], since, excludeRepos = [], excludeCommits = [], includePrivate = true }) {
+  const sinceIso = since.toISOString();
+  const excludePatterns = excludeCommits.map((pattern) => new RegExp(pattern, 'i'));
+  const commits = [];
+  const activeRepos = [];
+
+  // Build the worklist. Org listings come with metadata (pushed_at, private,
+  // homepage) so inactive repos are pre-filtered; brand-derived repos from
+  // other orgs have no listing, so they get a direct commits probe instead.
+  const seen = new Set();
+  const worklist = [];
+
+  for (const owner of orgs) {
+    console.log(`${chalk.dim('→')} Listing ${chalk.cyan(owner)}...`);
+
+    for (const repo of listReposForOwner(api, owner)) {
+      seen.add(`${owner}/${repo.name}`.toLowerCase());
+
+      const eligible = !repo.archived
+        && new Date(repo.pushed_at) >= since
+        && !excludeRepos.includes(repo.name)
+        && (includePrivate || !repo.private);
+
+      if (eligible) {
+        worklist.push({ owner, repo: repo.name, homepage: repo.homepage || '' });
+      }
+    }
+  }
+
+  for (const { owner, repo } of brandRepos) {
+    if (!seen.has(`${owner}/${repo}`.toLowerCase())) {
+      worklist.push({ owner, repo, homepage: '' });
+    }
+  }
+
+  console.log(`${chalk.dim('→')} Scanning ${worklist.length} repos...`);
+
+  worklist.forEach(({ owner, repo, homepage }, index) => {
+    let raw;
+
+    try {
+      raw = runPaginatedJson(api, `repos/${owner}/${repo}/commits?since=${sinceIso}&per_page=100`);
+    } catch {
+      // Brand-derived repos may not exist yet (404) or be empty (409) — skip quietly
+      console.log(`  ${chalk.dim(`[${index + 1}/${worklist.length}]`)} ${owner}/${repo}: ${chalk.dim('unavailable (missing or empty)')}`);
+      return;
+    }
+
+    const cleaned = raw
+      .filter((c) => !c.commit.message.startsWith('Merge '))
+      .filter((c) => !c.commit.message.startsWith('📦 Omega:')) // fleet-automation commits — noise, and automated content is banned anyway
+      .filter((c) => !excludePatterns.some((pattern) => pattern.test(c.commit.message))) // banned-topic commits never reach the writer
+      .filter((c) => !(c.author?.login || '').endsWith('[bot]') && !(c.commit.author?.name || '').endsWith('[bot]'))
+      .map((c) => ({
+        owner,
+        repo,
+        homepage,
+        sha: c.sha.slice(0, 7),
+        message: c.commit.message.split('\n')[0],
+        date: c.commit.author?.date,
+      }));
+
+    const trimmed = cleaned.length > MAX_COMMITS_PER_REPO
+      ? chalk.dim(` (keeping latest ${MAX_COMMITS_PER_REPO})`)
+      : '';
+    console.log(`  ${chalk.dim(`[${index + 1}/${worklist.length}]`)} ${owner}/${repo}: ${cleaned.length} commits${trimmed}`);
+
+    // API returns newest first, so slice keeps the most recent
+    const kept = cleaned.slice(0, MAX_COMMITS_PER_REPO);
+
+    if (kept.length) {
+      commits.push(...kept);
+      activeRepos.push(`${owner}/${repo}`);
+    }
+  });
+
+  return { commits, repos: activeRepos };
+}
+
+module.exports = { collectCommits };

package/dist/devlog/lib/generate-post.js

@@ -0,0 +1,201 @@
+/**
+ * Devlog generate stage — group the collected commits into a per-repo digest
+ * (Ghostii's sourceContent), assemble the brief (description), and have the
+ * provider write the article. Project URLs go through Ghostii's `links`
+ * param — its allocator assigns them to sections natively.
+ */
+
+const chalk = require('chalk').default;
+const { chosenProvider } = require('../../vendor/config/index.js');
+
+const { writeArticle, blocksToPost, MAX_DESCRIPTION_LENGTH, MAX_SOURCE_CONTENT_LENGTH } = require('./ghostii.js');
+
+/**
+ * Group commits by repo and render the digest Ghostii works from (sourceContent).
+ * Each repo header carries its project mapping so the writer knows which
+ * product the work belongs to.
+ *
+ * @param {Array} commits - Collected commits
+ * @param {object} projectMap - repoName → { project, url }
+ * @returns {string} Digest text
+ */
+function buildDigest(commits, projectMap) {
+  const byRepo = new Map();
+
+  for (const commit of commits) {
+    const key = `${commit.owner}/${commit.repo}`;
+
+    if (!byRepo.has(key)) {
+      byRepo.set(key, []);
+    }
+
+    byRepo.get(key).push(commit);
+  }
+
+  const sections = [];
+
+  for (const [fullName, repoCommits] of byRepo) {
+    const [, repo] = fullName.split('/');
+    const mapped = projectMap[repo];
+    const { name, url } = resolveProject(repoCommits[0], projectMap);
+    const label = mapped
+      ? `${repo} — part of "${name}" (${url})`
+      : `${repo} — project: ${name} (${url})`;
+
+    sections.push(`## ${label}\n${repoCommits.map((c) => `- ${c.message}`).join('\n')}`);
+  }
+
+  return sections.join('\n\n');
+}
+
+/**
+ * Resolve a commit's repo to the best public link, in priority order:
+ * brand-config product URL > GitHub repo homepage field > GitHub repo URL.
+ *
+ * @param {object} commit - A collected commit (carries owner/repo/homepage)
+ * @param {object} projectMap - repoName → { project, url }
+ * @returns {{ name: string, url: string }} Display name + link
+ */
+function resolveProject(commit, projectMap) {
+  const mapped = projectMap[commit.repo];
+
+  return {
+    name: mapped ? mapped.project : commit.repo,
+    url: mapped?.url
+      || commit.homepage
+      || `https://github.com/${commit.owner}/${commit.repo}`,
+  };
+}
+
+/**
+ * Collect the unique project links actually touched by the commits, so the
+ * brief and Ghostii's `links` param only carry URLs grounded in real work.
+ *
+ * @param {Array} commits - Collected commits
+ * @param {object} projectMap - repoName → { project, url }
+ * @returns {Array<{ name: string, url: string }>} Unique projects
+ */
+function collectProjectLinks(commits, projectMap) {
+  const seen = new Map();
+
+  for (const commit of commits) {
+    const { name, url } = resolveProject(commit, projectMap);
+
+    if (!seen.has(url)) {
+      seen.set(url, { name, url });
+    }
+  }
+
+  return [...seen.values()];
+}
+
+/**
+ * Build the Ghostii brief (description). Hard 2KB cap — assembled in priority
+ * order (task > blocklist > voice) so only the voice section ever gets truncated.
+ *
+ * @param {object} params - { brandConfig, days }
+ * @returns {string} Brief within Ghostii's description cap
+ */
+function buildBrief({ brandConfig, days }) {
+  const { brand } = brandConfig;
+  const ghostii = brandConfig.devlog?.providers?.ghostii || {};
+  // Voice: the newsletter generator's instructions blob when the brand's
+  // omega.json5 carries one (it's @omega.js/backend data, not manager config — presence is
+  // genuinely uncertain), else the brand description.
+  const voice = brandConfig.marketing?.newsletter?.content?.[0]?.instructions
+    || brand.description
+    || '';
+
+  const task = `First-person devlog post for ${brand.name} (${brand.url}): the founder's honest recap of the last ${days} days of real development work across his product portfolio. Base the article ONLY on the commit digest provided as source content — never invent work that isn't there. Weave a narrative (what shipped, why it matters, lessons learned); skip trivial chores like version bumps and dependency updates.
+
+Title style: short, punchy, and specific — like a git commit summary of the period's most interesting work (e.g. "Auth Round Trips and Quieter Cron Jobs"). Max ~8 words. NEVER use time-window phrasing ("Five Days of...", "A Week of...") — the post is dated already.`;
+
+  const blocklist = ghostii.excludeTopics.length
+    ? `NEVER discuss, mention, or allude to: ${ghostii.excludeTopics.join('; ')}.`
+    : '';
+
+  // Project URLs go through Ghostii's `links` param (its allocator assigns them
+  // to sections natively) — keeping them out of the brief keeps it light enough
+  // for the outline step's reasoning budget.
+  const fixed = [task, blocklist].filter(Boolean).join('\n\n');
+  // Cap the voice excerpt well below the 2KB description limit — a lean brief
+  // keeps the outline step's reasoning budget in check.
+  const remaining = Math.min(MAX_DESCRIPTION_LENGTH - fixed.length - '\n\nVoice: '.length, 600);
+
+  if (remaining < 50) {
+    console.log(`${chalk.yellow('⚠')} Brief is at Ghostii's 2KB cap — voice instructions dropped`);
+    return fixed.slice(0, MAX_DESCRIPTION_LENGTH);
+  }
+
+  return voice
+    ? `${fixed}\n\nVoice: ${voice.slice(0, remaining)}`
+    : fixed;
+}
+
+/**
+ * Generate a devlog post via the configured provider (Ghostii).
+ *
+ * @param {object} params - { brandConfig, commits, projectMap, days, write? }
+ *   (`write` is the article writer — tests inject a fake; prod uses Ghostii)
+ * @returns {Promise<{title, slug, description, tags, categories, body, headerImageUrl}>}
+ */
+async function generatePost({ brandConfig, commits, projectMap, days, write = writeArticle }) {
+  const writer = chosenProvider(brandConfig.devlog?.providers);
+
+  if (writer !== 'ghostii') {
+    throw new Error(`Unknown devlog writer: ${writer} (only 'ghostii' is supported — set devlog.providers.ghostii)`);
+  }
+
+  const ghostii = brandConfig.devlog.providers.ghostii;
+
+  const digest = buildDigest(commits, projectMap);
+  const projectLinks = collectProjectLinks(commits, projectMap);
+  const brief = buildBrief({ brandConfig, days });
+
+  if (digest.length > MAX_SOURCE_CONTENT_LENGTH) {
+    console.log(`${chalk.yellow('⚠')} Digest is ${digest.length} chars — Ghostii only reads the first ${MAX_SOURCE_CONTENT_LENGTH} (later repos get cut)`);
+  }
+
+  const article = await write({
+    brandConfig,
+    description: brief,
+    links: projectLinks.map((p) => p.url),
+    sourceContent: digest,
+    overrides: ghostii.overrides,
+  });
+
+  // Prefer the structured blocks (clean title/body separation); fall back to
+  // Ghostii's flat fields when blocks are absent.
+  const post = blocksToPost(article.json);
+  const title = post.title || article.title || '';
+  const body = post.body || article.body || '';
+
+  if (!title.trim() || !body.trim()) {
+    throw new Error('Ghostii response missing title or body');
+  }
+
+  return {
+    title: title.trim(),
+    slug: slugify(title),
+    description: (article.description || '').trim(),
+    tags: Array.isArray(article.keywords) ? article.keywords : [],
+    categories: Array.isArray(article.categories) ? article.categories : [],
+    body: body.trim(),
+    headerImageUrl: post.headerImageUrl || article.headerImageUrl || '',
+  };
+}
+
+/**
+ * Slugify a title: lowercase, alphanumerics + hyphens only.
+ *
+ * @param {string} input - Title text
+ * @returns {string} URL slug
+ */
+function slugify(input) {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+module.exports = { generatePost };

package/dist/devlog/lib/ghostii.js

@@ -0,0 +1,122 @@
+/**
+ * Ghostii API client — mirror of @omega.js/backend's Ghostii client
+ * (@omega.js/backend src/manager/libraries/content/ghostii.js). The SSOT for
+ * the request shape is @omega.js/backend; keep this in sync when it changes.
+ *
+ * Raw Cloud Functions URL (not api.ghostii.ai) to get the 5-min function
+ * timeout instead of Firebase Hosting's hard 60s proxy timeout.
+ */
+
+const GHOSTII_WRITE_URL = 'https://us-central1-ghostii.cloudfunctions.net/writeGlobal/write/article';
+
+// Ghostii API caps
+const MAX_DESCRIPTION_LENGTH = 2000;
+const MAX_SOURCE_CONTENT_LENGTH = 16000;
+
+/**
+ * node-powertools' random({ mode: 'gaussian' }) equivalent — the mean of two
+ * uniform draws biases toward the middle of the range.
+ *
+ * @param {number} min - Inclusive lower bound
+ * @param {number} max - Inclusive upper bound
+ * @returns {number} Integer in [min, max]
+ */
+function gaussianRandomInt(min, max) {
+  const draw = () => min + Math.random() * (max - min);
+
+  return Math.round((draw() + draw()) / 2);
+}
+
+/**
+ * Generate an article via the Ghostii API.
+ *
+ * @param {object} args
+ * @param {object} args.brandConfig - Merged brand config
+ * @param {string} args.description - Article brief (truncated to Ghostii's 2KB cap)
+ * @param {string[]} [args.links] - URLs to inject into the article body
+ * @param {string} [args.sourceContent] - Reference text (the commit digest; 16KB cap)
+ * @param {object} [args.overrides] - Ghostii API param overrides (length, research, images, ...)
+ * @returns {Promise<object>} Ghostii's generic article response
+ *   ({ title, description, body, json, headerImageUrl, categories, keywords, ... })
+ */
+async function writeArticle({ brandConfig, description, links = [], sourceContent, overrides = {} }) {
+  if (!process.env.OMEGA_ADMIN_KEY) {
+    throw new Error('OMEGA_ADMIN_KEY is not set — required to call the Ghostii API (brand or company .env)');
+  }
+
+  const { brand } = brandConfig;
+
+  const body = {
+    // Ghostii's LIVE wire contract: its production backend runs legacy BEM,
+    // whose auth reads exactly this payload field. Renames to the omega
+    // spelling only when Ghostii itself migrates to the new stack — never
+    // "fix" unilaterally (it would break devlog publishing).
+    backendManagerKey: process.env.OMEGA_ADMIN_KEY,
+    keywords: overrides.keywords || [],
+    description: description.slice(0, MAX_DESCRIPTION_LENGTH),
+    insertLinks: overrides.insertLinks ?? true,
+    research: overrides.research ?? true,
+    insertImages: overrides.insertImages ?? true,
+    length: overrides.length || 'long',
+    maxLinks: overrides.maxLinks || 6,
+    headerImageUrl: overrides.headerImageUrl || 'unsplash',
+    url: brand.url,
+    sectionQuantity: overrides.sectionQuantity || gaussianRandomInt(3, 6),
+    feedUrl: overrides.feedUrl || `${brand.url}/feeds/posts.json`,
+    links,
+  };
+
+  if (sourceContent) {
+    body.sourceContent = sourceContent.slice(0, MAX_SOURCE_CONTENT_LENGTH);
+  }
+
+  const response = await fetch(GHOSTII_WRITE_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(180000),
+  });
+
+  if (!response.ok) {
+    const detail = (await response.text().catch(() => '')).slice(0, 300);
+    throw new Error(`Ghostii API ${response.status}: ${detail || response.statusText}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Transform Ghostii's JSON block array into a clean post shape.
+ * Mirror of @omega.js/backend's blocksToPost(): title ← first heading-1, headerImageUrl ←
+ * first image block, body ← every remaining block joined as markdown (no
+ * title embedded).
+ *
+ * @param {Array} json - Ghostii's block array ([{ name, content }])
+ * @returns {{ title: string, headerImageUrl: string, body: string }}
+ */
+function blocksToPost(json) {
+  const blocks = Array.isArray(json) ? json : [];
+
+  const titleBlock = blocks.find((b) => b.name === 'heading-1');
+  const imageBlock = blocks.find((b) => b.name === 'image');
+
+  const title = (titleBlock?.content || '').replace(/^#+\s*/, '').trim();
+
+  const imageMatch = (imageBlock?.content || '').match(/\((.*?)\)\s*$/);
+  const headerImageUrl = imageMatch ? imageMatch[1] : '';
+
+  const body = blocks
+    .filter((b) => b !== titleBlock && b !== imageBlock)
+    .map((b) => b.content)
+    .join('\n\n')
+    .trim();
+
+  return { title, headerImageUrl, body };
+}
+
+module.exports = {
+  writeArticle,
+  blocksToPost,
+  MAX_DESCRIPTION_LENGTH,
+  MAX_SOURCE_CONTENT_LENGTH,
+};