@astryxdesign/cli 0.1.2-canary.ff01f6d → 0.1.3-canary.6d57c8d

package/src/codemods/transforms/v0.1.0/migrate-xds-declare-module.mjs

@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate `declare module "@xds/..."` augmentations to
+ * `@astryxdesign/...`
+ *
+ * The v0.1.0 release moved the public package scope from @xds to
+ * @astryxdesign. TypeScript module augmentations (`declare module "@xds/core"
+ * { ... }`) reference the package by its string specifier, so they are dead
+ * after the scope rename: TypeScript resolves the augmentation against a
+ * module that no longer exists.
+ *
+ * This transform rewrites the augmented module string on `TSModuleDeclaration`
+ * nodes whose `id` is a StringLiteral matching a renamed @xds package (or one
+ * of its subpaths). It only touches the module path — identifiers *inside* the
+ * augmentation (e.g. an augmented interface name) are a separate concern
+ * handled by drop-xds-prefix-imports.
+ *
+ * Ordered AFTER migrate-xds-module-specifiers in the v0.1.0 manifest: it uses
+ * the same PACKAGE_RENAMES mapping and cleans up the module-augmentation
+ * surface alongside the import/export/require specifier rename.
+ */
+
+export const meta = {
+  title: 'Migrate declare-module augmentations from @xds/* to @astryxdesign/*',
+  description:
+    'Rewrites the module specifier on TypeScript `declare module "@xds/..."` ' +
+    'augmentations to the @astryxdesign/* packages used by Astryx v0.1.0. ' +
+    'Only the augmented module path is changed; identifiers inside the ' +
+    'augmentation are left untouched.',
+  pr: '#3092',
+  fileExtensions: ['.ts', '.d.ts', '.tsx'],
+};
+
+const PACKAGE_RENAMES = new Map([
+  ['@xds/build', '@astryxdesign/build'],
+  ['@xds/cli', '@astryxdesign/cli'],
+  ['@xds/core', '@astryxdesign/core'],
+  ['@xds/lab', '@astryxdesign/lab'],
+  ['@xds/theme-butter', '@astryxdesign/theme-butter'],
+  ['@xds/theme-chocolate', '@astryxdesign/theme-chocolate'],
+  ['@xds/theme-daily', '@astryxdesign/theme-neutral'],
+  ['@xds/theme-default', '@astryxdesign/theme-neutral'],
+  ['@xds/theme-gothic', '@astryxdesign/theme-gothic'],
+  ['@xds/theme-matcha', '@astryxdesign/theme-matcha'],
+  ['@xds/theme-neutral', '@astryxdesign/theme-neutral'],
+  ['@xds/theme-stone', '@astryxdesign/theme-stone'],
+  ['@xds/theme-y2k', '@astryxdesign/theme-y2k'],
+]);
+
+function renamePackageSpecifier(value) {
+  if (typeof value !== 'string') return value;
+  for (const [from, to] of PACKAGE_RENAMES) {
+    if (value === from) return to;
+    if (value.startsWith(from + '/')) return to + value.slice(from.length);
+  }
+  return value;
+}
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  root.find(j.TSModuleDeclaration).forEach(path => {
+    const id = path.node.id;
+    // Module augmentations name the module with a string literal id; a
+    // `namespace Foo {}` uses an Identifier id, which we ignore.
+    if (!id || (id.type !== 'StringLiteral' && id.type !== 'Literal')) return;
+    if (typeof id.value !== 'string') return;
+    const next = renamePackageSpecifier(id.value);
+    if (next === id.value) return;
+    id.value = next;
+    hasChanges = true;
+  });
+
+  return hasChanges ? root.toSource() : undefined;
+}

package/src/commands/agent-docs.mjs

@@ -180,6 +180,9 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
   // Rules — the top error-preventers.
   lines.push('RULES:');
   lines.push('- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.');
+  lines.push('- Frame first: pick the shell (AppShell / Layout+LayoutPanel) and budget regions in px BEFORE writing content (`astryx docs layout`).');
+  lines.push('- Dense data = rows (Table, List/Item) edge-to-edge — never Card-wrapped list items. Card = dashboard widgets, galleries, settings groups only.');
+  lines.push('- Status → StatusDot/Token; Badge only for counts and enumerated states, never decoration.');
   // Styling guidance tailored to the project's configured system — never
   // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
   // utilities need Tailwind). Tokens are always the source of truth.
@@ -207,7 +210,7 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
       .sort();
     if (topics.length > 0) lines.push(`  docs <topic>       ${topics.join(', ')}`);
   }
-  lines.push('  swizzle <Name>     eject component source (--gap reports why)');
+  lines.push('  swizzle <Name>     eject component source for deep customization');
   lines.push('  upgrade --apply    run after any @astryxdesign/core bump');
   lines.push(MARKER_END);
 

package/src/commands/blog.mjs

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file blog command (hidden) — read the Astryx blog from the published feed.
+ *
+ * Hidden on purpose: it's not part of the documented command surface and does
+ * not appear in --help or the manifest. It reads the blog the same way any
+ * feed reader would — over the public RSS feed — and prints a post's plaintext
+ * (.txt) variant. Nothing about the blog's structure has to change for this to
+ * work; the CLI is just a consumer of the feed.
+ *
+ *   astryx blog                    List posts from the feed
+ *   astryx blog <slug>             Print a post as plaintext
+ */
+
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {blog as blogApi} from '../api/blog.mjs';
+
+function formatList({feedUrl, posts}, run) {
+  const lines = [`\nAstryx blog · feed: ${feedUrl}\n`];
+  if (posts.length === 0) {
+    lines.push('No posts found in the feed.');
+    return lines.join('\n');
+  }
+  for (const p of posts) {
+    lines.push(`  ${p.slug}`);
+    lines.push(`    ${p.title}`);
+    if (p.type) lines.push(`    ${p.type}`);
+    if (p.textUrl) lines.push(`    ${p.textUrl}`);
+    lines.push('');
+  }
+  lines.push(`Read one: ${run} astryx blog <slug>`);
+  return lines.join('\n');
+}
+
+export function registerBlog(program) {
+  program
+    .command('blog [slug]', {hidden: true})
+    .description('Read the Astryx blog from the published feed')
+    .action(async slug => {
+      const run = getRunPrefix();
+      let result;
+      try {
+        result = await blogApi(slug);
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        return;
+      }
+
+      if (result.type === 'blog.list') {
+        humanLog(formatList(result.data, run));
+      } else {
+        // blog.detail — print the feed URL, then the plaintext body.
+        humanLog(`Feed: ${result.data.feedUrl}\n`);
+        humanLog(result.data.text);
+      }
+    });
+}

package/src/commands/build-theme.import-path.test.mjs

@@ -18,14 +18,10 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {fileURLToPath} from 'node:url';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-const REPO_ROOT = path.resolve(__dirname, '../../../..');
-const CORE_THEME_ENTRY = path.join(
-  REPO_ROOT,
-  'packages/core/dist/theme/index.js',
-);
 
 function runCli(args, cwd) {
   try {
@@ -59,13 +55,7 @@ function writeTheme(dir, name) {
 // in-CLI fallback generator). Build core once if it isn't already present so
 // the suite works in any CI job, regardless of job ordering.
 beforeAll(() => {
-  if (!fs.existsSync(CORE_THEME_ENTRY)) {
-    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
-      cwd: REPO_ROOT,
-      stdio: 'pipe',
-      timeout: 180_000,
-    });
-  }
+  ensureCoreBuilt();
 }, 200_000);
 
 let tmpDir;

package/src/commands/build-theme.mjs

@@ -15,6 +15,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL, fileURLToPath} from 'node:url';
+import {spawn} from 'node:child_process';
 import {createJiti} from 'jiti';
 import {getRunPrefix} from '../utils/package-manager.mjs';
 import {
@@ -597,6 +598,104 @@ function validatePrivateVars(themeDef) {
   return errors;
 }
 
+/**
+ * Path to this CLI's real entry (bin/astryx.mjs), resolved from this module's
+ * location (src/commands/build-theme.mjs → ../../bin/astryx.mjs). Used to
+ * re-invoke `theme build` as a child process in watch mode.
+ */
+function resolveCliBin() {
+  const commandsDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(commandsDir, '../../bin/astryx.mjs');
+}
+
+/**
+ * Run a single `theme build` as a child process, reusing the exact
+ * single-build code path (and its error handling) rather than duplicating it.
+ * Resolves with the child's exit code; never rejects.
+ *
+ * @param {string} file - The theme file argument, as the user passed it.
+ * @param {object} options - Parsed command options (only `out` is forwarded).
+ * @returns {Promise<number>}
+ */
+function runThemeBuildOnceChild(file, options) {
+  const cliBin = resolveCliBin();
+  const args = [cliBin, 'theme', 'build', file];
+  if (options.out) args.push('--out', options.out);
+  return new Promise(resolve => {
+    const child = spawn(process.execPath, args, {
+      stdio: 'inherit',
+      env: process.env,
+    });
+    child.on('close', code => resolve(code ?? 0));
+    child.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Watch a theme file and rebuild on change. Runs an initial build, then
+ * rebuilds (debounced) whenever the file changes, until interrupted with
+ * Ctrl-C. Each rebuild runs in a child process so a build error (which the
+ * single-build path reports via a hard exit) is contained and the watcher
+ * keeps running.
+ *
+ * @param {string} file - The theme file argument, as the user passed it.
+ * @param {string} filePath - Absolute path to the theme file.
+ * @param {object} options - Parsed command options.
+ * @returns {Promise<void>} Resolves when the watcher is stopped (Ctrl-C).
+ */
+async function runThemeBuildWatch(file, filePath, options) {
+  const rel = path.relative(process.cwd(), filePath);
+
+  // Initial build.
+  await runThemeBuildOnceChild(file, options);
+
+  humanLog(`\n👀 Watching ${rel} for changes — press Ctrl-C to stop.`);
+
+  let building = false;
+  let queued = false;
+  let debounce = null;
+
+  const rebuild = async () => {
+    if (building) {
+      // Coalesce changes that land mid-build into a single follow-up run.
+      queued = true;
+      return;
+    }
+    building = true;
+    humanLog(`\n♻️  Change detected — rebuilding ${rel}...`);
+    await runThemeBuildOnceChild(file, options);
+    building = false;
+    humanLog(`\n👀 Watching ${rel} for changes — press Ctrl-C to stop.`);
+    if (queued) {
+      queued = false;
+      rebuild();
+    }
+  };
+
+  // Some editors replace the file (rename) rather than writing in place, which
+  // can drop the watch. Watch the containing directory and filter to our file
+  // so edits survive atomic-save/rename.
+  const watchDir = path.dirname(filePath);
+  const baseName = path.basename(filePath);
+  const watcher = fs.watch(watchDir, (_eventType, changed) => {
+    if (changed && changed !== baseName) return;
+    clearTimeout(debounce);
+    // Debounce: editors often emit several events per save.
+    debounce = setTimeout(rebuild, 100);
+  });
+
+  await new Promise(resolve => {
+    const stop = () => {
+      clearTimeout(debounce);
+      watcher.close();
+      humanLog('\nStopped watching.');
+      resolve();
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  });
+}
+
 export function registerTheme(program) {
   const theme = program
     .command('theme')
@@ -621,6 +720,10 @@ export function registerTheme(program) {
     .command('build <file>')
     .description('Compile a defineTheme file to CSS + JS')
     .option('-o, --out <path>', 'Output CSS file path')
+    .option(
+      '-w, --watch',
+      'Rebuild automatically when the theme file changes (Ctrl-C to stop)',
+    )
     .action(async (file, options) => {
       const filePath = path.resolve(process.cwd(), file);
       const json = program.opts().json || false;
@@ -630,6 +733,20 @@ export function registerTheme(program) {
         return;
       }
 
+      // Watch mode: run an initial build, then rebuild on every change to the
+      // theme file. Watch is a human-interactive, long-running mode — it is not
+      // supported in --json (machine) mode, which expects a single envelope.
+      if (options.watch) {
+        if (json) {
+          cliError('--watch is not supported with --json', {
+            code: ERROR_CODES.ERR_THEME_INVALID,
+          });
+          return;
+        }
+        await runThemeBuildWatch(file, filePath, options);
+        return;
+      }
+
       if (!json) humanLog(`\nBuilding theme from ${path.relative(process.cwd(), filePath)}...`);
 
       // Extract theme definition

package/src/commands/build-theme.prose.test.mjs

@@ -18,9 +18,9 @@
  *   - paragraphs use the body font, not the heading font.
  *
  * Building `astryx theme build` requires a compiled @astryxdesign/core (there is no in-CLI
- * fallback generator), so this suite builds core once in beforeAll — mirroring
- * scripts/build-css.test.mjs — to stay self-sufficient regardless of CI job
- * ordering.
+ * fallback generator), so this suite builds core once in beforeAll via the
+ * shared ensureCoreBuilt() helper — which serializes concurrent Vitest workers
+ * behind a lock — to stay self-sufficient regardless of CI job ordering.
  */
 
 import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
@@ -29,14 +29,10 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {fileURLToPath} from 'node:url';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-const REPO_ROOT = path.resolve(__dirname, '../../../..');
-const CORE_THEME_ENTRY = path.join(
-  REPO_ROOT,
-  'packages/core/dist/theme/index.js',
-);
 
 function runCli(args, cwd) {
   try {
@@ -71,13 +67,7 @@ function writeTheme(dir, name) {
 // `astryx theme build` imports the compiled @astryxdesign/core/theme entry. Build core
 // once if it isn't already present so the suite works in any CI job.
 beforeAll(() => {
-  if (!fs.existsSync(CORE_THEME_ENTRY)) {
-    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
-      cwd: REPO_ROOT,
-      stdio: 'pipe',
-      timeout: 180_000,
-    });
-  }
+  ensureCoreBuilt();
 }, 200_000);
 
 let tmpDir;

package/src/commands/build-theme.watch.test.mjs

@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for `astryx theme build --watch` (#3375).
+ *
+ * Watch mode runs an initial build, then rebuilds whenever the theme file
+ * changes, until interrupted. Each rebuild runs in a child process so a build
+ * error (reported by the single-build path via a hard exit) is contained and
+ * the watcher keeps running.
+ *
+ * Building `astryx theme build` requires a compiled @astryxdesign/core, so this
+ * suite builds core once in beforeAll via the shared ensureCoreBuilt() helper —
+ * which serializes concurrent Vitest workers behind a lock — to stay
+ * self-sufficient regardless of CI job ordering.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import {execFileSync, spawn} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+
+function runCli(args, cwd) {
+  try {
+    const out = execFileSync('node', [CLI_BIN, ...args], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0'},
+    });
+    return {code: 0, stdout: out, stderr: ''};
+  } catch (e) {
+    return {
+      code: e.status ?? 1,
+      stdout: e.stdout?.toString() ?? '',
+      stderr: e.stderr?.toString() ?? '',
+    };
+  }
+}
+
+/** Poll until `predicate()` is true or the timeout elapses. */
+async function waitFor(predicate, {timeout = 8000, interval = 50} = {}) {
+  const start = Date.now();
+  for (;;) {
+    if (predicate()) return true;
+    if (Date.now() - start > timeout) return false;
+    await new Promise(r => setTimeout(r, interval));
+  }
+}
+
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-watch-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build --watch', () => {
+  it('advertises the flag in --help', () => {
+    const result = runCli(['theme', 'build', '--help'], process.cwd());
+    const out = result.stdout + result.stderr;
+    expect(out).toMatch(/--watch/);
+  });
+
+  it('rejects --watch together with --json (single-envelope contract)', () => {
+    const themeFile = path.join(tmpDir, 'wt.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default { name: 'wt', tokens: { '--color-bg': '#fff' } };\n`,
+    );
+    const result = runCli(
+      ['--json', 'theme', 'build', path.relative(tmpDir, themeFile), '--watch'],
+      tmpDir,
+    );
+    expect(result.code).not.toBe(0);
+    expect(result.stdout + result.stderr).toMatch(/watch/i);
+  });
+
+  it('builds initially, rebuilds on change, and stops cleanly on SIGINT', async () => {
+    const themeFile = path.join(tmpDir, 'wt.mjs');
+    const cssFile = path.join(tmpDir, 'wt.css');
+    fs.writeFileSync(
+      themeFile,
+      `export default { name: 'wt', tokens: { '--color-bg': '#ffffff' } };\n`,
+    );
+
+    const child = spawn(
+      process.execPath,
+      [CLI_BIN, 'theme', 'build', 'wt.mjs', '--watch'],
+      {cwd: tmpDir, env: {...process.env, FORCE_COLOR: '0'}},
+    );
+    let stdout = '';
+    child.stdout.on('data', d => (stdout += d.toString()));
+    child.stderr.on('data', d => (stdout += d.toString()));
+
+    try {
+      // Initial build produces the CSS.
+      const built = await waitFor(() => fs.existsSync(cssFile));
+      expect(built).toBe(true);
+      const firstCss = fs.readFileSync(cssFile, 'utf-8');
+      expect(firstCss).toMatch(/#ffffff/);
+
+      // Wait until the watcher is actually watching before editing, so the
+      // change isn't missed.
+      await waitFor(() => /Watching/i.test(stdout));
+
+      // Change the theme — the token value changes so the CSS must change.
+      fs.writeFileSync(
+        themeFile,
+        `export default { name: 'wt', tokens: { '--color-bg': '#010203' } };\n`,
+      );
+
+      // The rebuilt CSS should reflect the new value.
+      const rebuilt = await waitFor(() => {
+        try {
+          return fs.readFileSync(cssFile, 'utf-8').includes('#010203');
+        } catch {
+          return false;
+        }
+      });
+      expect(rebuilt).toBe(true);
+      expect(stdout).toMatch(/rebuild/i);
+    } finally {
+      // SIGINT must stop the watcher and exit cleanly.
+      child.kill('SIGINT');
+    }
+
+    const exited = await new Promise(resolve => {
+      let done = false;
+      child.on('exit', () => {
+        done = true;
+        resolve(true);
+      });
+      setTimeout(() => resolve(done), 4000);
+    });
+    expect(exited).toBe(true);
+    expect(stdout).toMatch(/Stopped watching/);
+  }, 30_000);
+});

package/src/commands/ensure-core-built.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared test helper: build @astryxdesign/core once, race-free.
+ *
+ * `astryx theme build` imports the compiled @astryxdesign/core/theme entry
+ * (there is no in-CLI fallback generator), so any test exercising it needs a
+ * built core. The CI `test` job runs `pnpm test` without a prior core build,
+ * and Vitest runs test files in parallel worker forks. When two build-theme
+ * suites each ran `if (!exists) pnpm -F @astryxdesign/core build` in their own
+ * beforeAll, both workers saw dist missing and launched concurrent builds that
+ * collided on the shared packages/core/dist (core's build starts with
+ * `rimraf dist`): one worker wiped dist while the other was mid-write, failing
+ * nondeterministically ("Could not resolve dist/index.js" / "ENOTEMPTY rmdir
+ * dist/hooks").
+ *
+ * This serializes the build behind a filesystem lock so exactly one worker
+ * builds and the rest wait for it to finish before reading dist.
+ */
+
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+const CORE_THEME_ENTRY = path.join(
+  REPO_ROOT,
+  'packages/core/dist/theme/index.js',
+);
+// A lock directory (mkdir is atomic across processes) guards the build.
+const LOCK_DIR = path.join(os.tmpdir(), 'astryx-core-build.lock');
+
+const BUILD_TIMEOUT_MS = 180_000;
+// A lock older than this is assumed abandoned by a crashed/killed worker.
+const STALE_LOCK_MS = BUILD_TIMEOUT_MS + 20_000;
+const POLL_MS = 250;
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function buildCore() {
+  execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
+    cwd: REPO_ROOT,
+    stdio: 'pipe',
+    timeout: BUILD_TIMEOUT_MS,
+  });
+}
+
+function lockIsStale() {
+  try {
+    return Date.now() - fs.statSync(LOCK_DIR).mtimeMs > STALE_LOCK_MS;
+  } catch {
+    // Vanished between the exists check and stat — treat as released.
+    return false;
+  }
+}
+
+/** Try to acquire the lock. Returns true if this worker now holds it. */
+function tryAcquire() {
+  try {
+    fs.mkdirSync(LOCK_DIR);
+    return true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') {
+      throw err;
+    }
+    if (lockIsStale()) {
+      fs.rmSync(LOCK_DIR, {recursive: true, force: true});
+      try {
+        fs.mkdirSync(LOCK_DIR);
+        return true;
+      } catch (retryErr) {
+        if (retryErr.code !== 'EEXIST') {
+          throw retryErr;
+        }
+      }
+    }
+    return false;
+  }
+}
+
+/**
+ * Ensure packages/core/dist is built exactly once, even when called
+ * concurrently from parallel Vitest workers. Safe to call from every
+ * build-theme suite's beforeAll.
+ */
+export function ensureCoreBuilt() {
+  if (fs.existsSync(CORE_THEME_ENTRY)) {
+    return;
+  }
+
+  const deadline = Date.now() + STALE_LOCK_MS;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(CORE_THEME_ENTRY)) {
+      return;
+    }
+    if (tryAcquire()) {
+      try {
+        if (!fs.existsSync(CORE_THEME_ENTRY)) {
+          buildCore();
+        }
+      } finally {
+        fs.rmSync(LOCK_DIR, {recursive: true, force: true});
+      }
+      return;
+    }
+    // Another worker is building; wait for it to finish and release the lock.
+    sleepSync(POLL_MS);
+  }
+
+  // Waited past the stale threshold without the artifact appearing — build it
+  // ourselves rather than let the suite fail on a missing entry.
+  buildCore();
+}

package/src/index.mjs

@@ -245,6 +245,7 @@ const commands = [
   {name: 'init', path: './commands/init.mjs', register: 'registerInit'},
   {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},
   {name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},
+  {name: 'blog', path: './commands/blog.mjs', register: 'registerBlog'},
   {name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
   // agent-docs folded into init — functions still importable from agent-docs.mjs
   {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},

package/src/lib/error-codes.mjs

@@ -75,6 +75,8 @@
  *   | 'ERR_INVALID_VERSION'
  *   | 'ERR_DEP_MISSING'
  *   | 'ERR_GH_CLI'
+ *   | 'ERR_UNKNOWN_POST'
+ *   | 'ERR_FETCH_FAILED'
  *   | 'ERR_LAYOUT_PARSE'
  *   | 'ERR_LAYOUT_INVALID'
  * )} ErrorCode
@@ -181,6 +183,12 @@ export const ERROR_CODES = Object.freeze({
   /** GitHub CLI (`gh`) is not installed or not authenticated. */
   ERR_GH_CLI: 'ERR_GH_CLI',
 
+  // ── Blog (read via the published RSS feed) ───────────────────────
+  /** No blog post matched the requested slug in the feed. */
+  ERR_UNKNOWN_POST: 'ERR_UNKNOWN_POST',
+  /** A network fetch (RSS feed or post text) failed. */
+  ERR_FETCH_FAILED: 'ERR_FETCH_FAILED',
+
   // ── Layout expressions (XLE/XLO) ─────────────────────────────────
   /** A layout expression failed to parse (syntax error, with line/col). */
   ERR_LAYOUT_PARSE: 'ERR_LAYOUT_PARSE',