@astryxdesign/cli 0.4.1 → 0.4.2-canary.464a445

package/api/theme/build/font-warning.mjs

@@ -0,0 +1,214 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Font-loading warning helpers for `astryx theme build` (#5015).
+ *
+ * Nothing in the pipeline loads font files — defineTheme and the built CSS
+ * only set `font-family` — so a theme that names a webfont renders in the
+ * fallback typeface on every machine whose app never loads it, and no step
+ * says so. These helpers close that gap at build time.
+ *
+ * `collectUnloadedFonts` inspects a RESOLVED theme (raw typography configs
+ * are already collapsed into `--font-family-*` tokens by the time the build
+ * sees the theme, so tokens + component-override `fontFamily` values are the
+ * complete font surface on both load paths) and returns the families that
+ * are neither CSS generics nor known preinstalled system fonts. Unrecognized
+ * names are assumed to be webfonts on purpose: a missed warning hides the
+ * bug, a spurious one costs a glance.
+ *
+ * @input A resolved theme object ({tokens, components}) from build.mjs.
+ * @output Ordered, case-insensitively deduped family names, and the human
+ *   help snippet (<link> pair + @font-face) printed after the install
+ *   instructions.
+ * @position Sits beside build.mjs (api/theme/build/). Pure functions, no IO,
+ *   so the `--json` receipt and the human output share one source of truth.
+ */
+
+// font-family values that never need loading: CSS generic families, the ui-*
+// system keywords, and CSS-wide keywords that can appear in a token value.
+const GENERIC_KEYWORDS = new Set([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'math',
+  'emoji',
+  'fangsong',
+  'ui-serif',
+  'ui-sans-serif',
+  'ui-monospace',
+  'ui-rounded',
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'revert-layer',
+]);
+
+// Families a clean machine already has: the members of core's own default
+// stacks (tokens.stylex.ts typographyDefaults) plus the classic web-safe
+// macOS/Windows set. Deliberately short — an unknown family warns, and for a
+// preinstalled rarity that is a one-line false alarm, not a broken theme.
+const SYSTEM_FAMILIES = new Set([
+  '-apple-system',
+  'blinkmacsystemfont',
+  'segoe ui',
+  'segoe ui emoji',
+  'segoe ui symbol',
+  'roboto',
+  'helvetica',
+  'helvetica neue',
+  'arial',
+  'arial black',
+  'sf mono',
+  'sf pro',
+  'sf pro text',
+  'sf pro display',
+  'monaco',
+  'consolas',
+  'menlo',
+  'courier',
+  'courier new',
+  'georgia',
+  'times',
+  'times new roman',
+  'verdana',
+  'tahoma',
+  'trebuchet ms',
+  'impact',
+  'palatino',
+  'cambria',
+  'calibri',
+  'lucida grande',
+  'lucida console',
+  'gill sans',
+  'brush script mt',
+  'snell roundhand',
+  'old english text mt',
+  // Linux staples — the shipped themes' fallback stacks name these on
+  // purpose (e.g. neutral's code stack ends in Liberation Mono).
+  'liberation mono',
+  'liberation sans',
+  'liberation serif',
+  'dejavu sans',
+  'dejavu sans mono',
+]);
+
+/**
+ * Split a CSS font-family value into clean family names. Complete `var()`
+ * calls are stripped first — neither the reference nor its fallback
+ * arguments are this theme's own family declarations (the referenced token
+ * is checked in its own right) — then names are unquoted and
+ * whitespace-collapsed, and any remaining function-shaped fragment is
+ * dropped. The unquoted branch of the tokenizer cannot start at whitespace
+ * or a quote, so a quoted name is always taken whole even mid-list (commas
+ * inside quotes stay inside the name).
+ *
+ * @param {string} value
+ * @returns {string[]}
+ */
+function splitFamilies(value) {
+  const families = [];
+  const withoutVars = value.replace(/var\([^()]*(?:\([^()]*\)[^()]*)*\)/g, '');
+  for (const segment of withoutVars.match(/"[^"]*"|'[^']*'|[^,"'\s][^,]*/g) ??
+    []) {
+    let name = segment.trim();
+    if (!name) continue;
+    // /s: a quoted name may span lines (template-literal theme sources).
+    const quoted = /^(["']).*\1$/s.test(name);
+    if (quoted) name = name.slice(1, -1);
+    name = name.trim().replace(/\s+/g, ' ');
+    if (!name || (!quoted && /[()]/.test(name))) continue;
+    families.push(name);
+  }
+  return families;
+}
+
+/**
+ * Collect the font families a resolved theme names but does not load —
+ * every `--font-family-*` token plus every component-override `fontFamily`,
+ * minus generics, CSS-wide keywords, `var()` references, and known system
+ * families. Source order, first-seen casing, deduped case-insensitively.
+ *
+ * @param {{tokens?: Record<string, string>, components?: object}} resolvedTheme
+ * @returns {string[]}
+ */
+export function collectUnloadedFonts(resolvedTheme) {
+  const seen = new Set();
+  /** @type {string[]} */
+  const unloaded = [];
+
+  /** @param {unknown} value */
+  const consider = value => {
+    if (typeof value !== 'string') return;
+    for (const family of splitFamilies(value)) {
+      const key = family.toLowerCase();
+      if (GENERIC_KEYWORDS.has(key) || SYSTEM_FAMILIES.has(key)) continue;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      unloaded.push(family);
+    }
+  };
+
+  for (const [token, value] of Object.entries(resolvedTheme?.tokens ?? {})) {
+    if (token.startsWith('--font-family-')) consider(value);
+  }
+
+  // Component overrides are plain CSS maps of unknown depth (style keys,
+  // nested at-rule blocks) — walk them and pick up every fontFamily.
+  /** @param {unknown} node */
+  const walk = node => {
+    if (!node || typeof node !== 'object') return;
+    for (const [key, value] of Object.entries(node)) {
+      if (key === 'fontFamily') consider(value);
+      else walk(value);
+    }
+  };
+  walk(resolvedTheme?.components);
+
+  return unloaded;
+}
+
+/**
+ * Render the human fix printed after the install instructions: which fonts
+ * the theme names but does not load, the Google Fonts `<link>` recipe, and
+ * the self-hosted `@font-face` alternative.
+ *
+ * @param {string} themeName
+ * @param {string[]} families
+ * @returns {string}
+ */
+export function formatFontLoadingHelp(themeName, families) {
+  const named = families.map(f => `"${f}"`).join(', ');
+  const cssHref =
+    'https://fonts.googleapis.com/css2?' +
+    families
+      .map(f => `family=${encodeURIComponent(f).replace(/%20/g, '+')}`)
+      .join('&') +
+    '&display=swap';
+  const first = families[0];
+  const slug = first.toLowerCase().replace(/ /g, '-');
+  return `
+⚠ Theme "${themeName}" names fonts it does not load: ${named}
+  The built CSS only sets font-family — load these in your app, or every
+  browser quietly falls back.
+
+  Google Fonts (add :wght@… axes as your theme's weights require):
+
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link rel="stylesheet" href="${cssHref}" />
+
+  Self-hosted (repeat per family and weight):
+
+    @font-face {
+      font-family: ${JSON.stringify(first)};
+      src: url('/fonts/${slug}.woff2') format('woff2');
+      font-display: swap;
+    }
+
+  Recipe and fallback-stack guidance: astryx docs typography
+`;
+}

package/api/theme/build/font-warning.test.mjs

@@ -0,0 +1,242 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Unit tests for the font-loading warning helpers behind `astryx theme build`
+ * (#5015). `collectUnloadedFonts()` reads a RESOLVED theme — `--font-family-*`
+ * tokens plus component-override `fontFamily` values (typography configs are
+ * already collapsed into tokens by the time the build sees the theme) — and
+ * returns the families the theme names but nothing loads. CSS generics,
+ * CSS-wide keywords, `var()` references, and known preinstalled system
+ * families are treated as loaded; anything unrecognized is assumed to be a
+ * webfont, because a missed warning is worse than a spurious one.
+ * `formatFontLoadingHelp()` renders the human snippet (<link> pair +
+ * @font-face) printed after the install instructions.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {collectUnloadedFonts, formatFontLoadingHelp} from './font-warning.mjs';
+
+describe('collectUnloadedFonts', () => {
+  it('returns webfont families from font-family tokens, skipping known fallbacks', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': '"Fraunces", Georgia, serif'},
+      }),
+    ).toEqual(['Fraunces']);
+  });
+
+  it('returns nothing for the default system stacks', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body':
+            '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+          '--font-family-code': '"SF Mono", Monaco, Consolas, monospace',
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it('treats bare system keywords like ui-monospace as loaded', () => {
+    expect(
+      collectUnloadedFonts({tokens: {'--font-family-code': 'ui-monospace'}}),
+    ).toEqual([]);
+  });
+
+  it('handles single-quoted and unquoted multi-word family names', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': "'JetBrains Mono', monospace",
+          '--font-family-heading': 'Space Grotesk, sans-serif',
+        },
+      }),
+    ).toEqual(['JetBrains Mono', 'Space Grotesk']);
+  });
+
+  it('dedupes case-insensitively across roles, keeping the first casing', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': '"Space Grotesk", sans-serif',
+          '--font-family-heading': '"space grotesk", serif',
+        },
+      }),
+    ).toEqual(['Space Grotesk']);
+  });
+
+  it('skips var() references and CSS-wide keywords', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-heading': 'var(--font-family-body)',
+          '--font-family-code': 'inherit',
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it("strips whole var() calls — fallback arguments are not this theme's declarations", () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': 'var(--x, "Web Font")',
+          '--font-family-heading': 'var(--x, "Web Font", serif)',
+        },
+      }),
+    ).toEqual([]);
+    // Families outside the var() call still count.
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-code': 'var(--x), Bungee'},
+      }),
+    ).toEqual(['Bungee']);
+  });
+
+  it('keeps a comma inside a quoted name whole, even mid-list', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': 'Georgia, "Foo, Bar", serif'},
+      }),
+    ).toEqual(['Foo, Bar']);
+  });
+
+  it('ignores an empty font-family token', () => {
+    expect(collectUnloadedFonts({tokens: {'--font-family-body': ''}})).toEqual(
+      [],
+    );
+  });
+
+  it('collects component-override fontFamily values, any style key', () => {
+    expect(
+      collectUnloadedFonts({
+        components: {
+          Button: {base: {fontFamily: '"Orbitron", sans-serif'}},
+          Card: {'variant:hero': {fontFamily: 'Bungee'}},
+        },
+      }),
+    ).toEqual(['Orbitron', 'Bungee']);
+  });
+
+  it('matches known system families case-insensitively', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': 'arial, sans-serif'},
+      }),
+    ).toEqual([]);
+  });
+
+  it('returns nothing for a theme with no tokens or components', () => {
+    expect(collectUnloadedFonts({})).toEqual([]);
+  });
+
+  it('returns nothing for a null or undefined resolved theme', () => {
+    // Older build.mjs consumers guard with `resolvedTheme || themeDef` — if
+    // a path ever hands the collector nothing, it must shrug, not throw.
+    expect(collectUnloadedFonts(null)).toEqual([]);
+    expect(collectUnloadedFonts(undefined)).toEqual([]);
+  });
+
+  it('ignores non-string values without throwing: numeric or object-valued', () => {
+    // The generator only allows object values under ':pseudo' keys, so an
+    // object-valued fontFamily is not a family declaration — skip, not crash.
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': 42},
+        components: {
+          button: {base: {fontFamily: 700}},
+          card: {base: {fontFamily: {default: '"Sneaky"'}}},
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it('collects fontFamily nested under a pseudo-class block', () => {
+    // generateThemeRules accepts {':hover': {fontFamily}} inside a style
+    // key — a family named only there must still warn.
+    expect(
+      collectUnloadedFonts({
+        components: {
+          button: {base: {':hover': {fontFamily: '"Rubik Doodle", cursive'}}},
+        },
+      }),
+    ).toEqual(['Rubik Doodle']);
+  });
+
+  it('strips a var() whose fallback list contains another var()', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': 'var(--brand, var(--fallback), "Web Font")',
+        },
+      }),
+    ).toEqual([]);
+    // …and still keeps a family declared outside the nested call.
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-code': 'var(--a, var(--b, serif)), Bungee'},
+      }),
+    ).toEqual(['Bungee']);
+  });
+
+  it('matches generic keywords case-insensitively', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': 'Sans-Serif',
+          '--font-family-heading': 'SERIF',
+          '--font-family-code': 'Ui-Monospace',
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it('collapses newlines and whitespace runs inside a family name', () => {
+    // Template-literal theme sources wrap long stacks across lines.
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': '"Space\n      Grotesk",\n  serif'},
+      }),
+    ).toEqual(['Space Grotesk']);
+  });
+});
+
+describe('formatFontLoadingHelp', () => {
+  const help = formatFontLoadingHelp('ocean', ['Fraunces', 'JetBrains Mono']);
+
+  it('names the theme and every family in the headline', () => {
+    expect(help).toContain('⚠');
+    expect(help).toContain('ocean');
+    expect(help).toContain('"Fraunces"');
+    expect(help).toContain('"JetBrains Mono"');
+  });
+
+  it('includes the Google Fonts recipe: preconnect pair + the exact css2 URL', () => {
+    expect(help).toContain(
+      '<link rel="preconnect" href="https://fonts.googleapis.com"',
+    );
+    expect(help).toContain('https://fonts.gstatic.com');
+    // The whole href, so a malformed URL cannot hide behind fragment checks.
+    expect(help).toContain(
+      'href="https://fonts.googleapis.com/css2?family=Fraunces&family=JetBrains+Mono&display=swap"',
+    );
+  });
+
+  it('includes a self-hosted @font-face alternative with font-display: swap', () => {
+    expect(help).toContain('@font-face');
+    expect(help).toContain('font-family: "Fraunces"');
+    expect(help).toContain('woff2');
+    expect(help).toContain('font-display: swap');
+  });
+
+  it('points at the docs recipe', () => {
+    expect(help).toContain('astryx docs typography');
+  });
+
+  it('percent-encodes family names in the css2 URL', () => {
+    const spiced = formatFontLoadingHelp('spice', ['P&Co Sans', 'Sömething']);
+    expect(spiced).toContain(
+      'href="https://fonts.googleapis.com/css2?family=P%26Co+Sans&family=S%C3%B6mething&display=swap"',
+    );
+  });
+});

package/api/theme/template/template.d.mts

@@ -0,0 +1,21 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Write the annotated theme template into a project.
+ *
+ * Refuses to overwrite without `overwrite`: an edited copy is the consumer's
+ * work, and this command is safe to re-run (init calls it on every setup).
+ *
+ * @param {{targetPath?: string, overwrite?: boolean, cwd?: string}} [options]
+ * @returns {import('../theme.type.mjs').ThemeTemplateResponse}
+ */
+export function themeTemplate(options?: {
+    targetPath?: string;
+    overwrite?: boolean;
+    cwd?: string;
+}): import("../theme.type.mjs").ThemeTemplateResponse;
+/** The annotated `defineTheme` reference that ships with the CLI. */
+export const THEME_TEMPLATE_SRC: string;
+/** Where it lands when the caller does not say. */
+export const THEME_TEMPLATE_DEFAULT_PATH: "theme.template.ts";

package/api/theme/template/template.mjs

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx theme template` leaf — writes the annotated theme template into the
+ * consumer's project.
+ *
+ * Sibling of `theme add`: both answer "put a theme starting point in my
+ * project", and they split on where you start. `add` copies a theme we ship
+ * (you like stone, you want to own it); `template` writes the blank annotated
+ * reference (you want your own, and need to know what the surface contains).
+ *
+ * The template is a doc that happens to compile, so it is one file at the
+ * project root by default rather than a package under src/themes/ — you read
+ * it, copy what you need into your own theme file, and delete it.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
+import {assertWithin, PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {stripCopyrightHeader} from '../../../foundation/text/copyright-header.mjs';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+
+/** The annotated `defineTheme` reference that ships with the CLI. */
+export const THEME_TEMPLATE_SRC = path.join(CLI_ROOT, 'assets', 'theme.template.ts');
+
+/** Where it lands when the caller does not say. */
+export const THEME_TEMPLATE_DEFAULT_PATH = 'theme.template.ts';
+
+/**
+ * Write the annotated theme template into a project.
+ *
+ * Refuses to overwrite without `overwrite`: an edited copy is the consumer's
+ * work, and this command is safe to re-run (init calls it on every setup).
+ *
+ * @param {{targetPath?: string, overwrite?: boolean, cwd?: string}} [options]
+ * @returns {import('../theme.type.mjs').ThemeTemplateResponse}
+ */
+export function themeTemplate(options = {}) {
+  const {
+    targetPath = THEME_TEMPLATE_DEFAULT_PATH,
+    overwrite = false,
+    cwd = process.cwd(),
+  } = options;
+
+  let resolved;
+  try {
+    resolved = assertWithin(targetPath, cwd, {label: 'theme template path'});
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+
+  const relative = path.relative(cwd, resolved) || targetPath;
+
+  if (fs.existsSync(resolved) && !overwrite) {
+    return {type: 'theme.template', data: {path: relative, written: false, reason: 'exists'}};
+  }
+
+  // Our repo header has no business in someone else's source tree.
+  const contents = stripCopyrightHeader(fs.readFileSync(THEME_TEMPLATE_SRC, 'utf-8'));
+  fs.mkdirSync(path.dirname(resolved), {recursive: true});
+  fs.writeFileSync(resolved, contents);
+
+  return {type: 'theme.template', data: {path: relative, written: true, reason: null}};
+}

package/api/theme/template/template.test.mjs

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Direct API tests for `themeTemplate()` — the function behind
+ * `astryx theme template` and `astryx init --features theme`.
+ *
+ * What matters here is that it never destroys work: the template lands once,
+ * a second run leaves an edited copy alone, and a path that escapes the
+ * project is refused.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {themeTemplate, THEME_TEMPLATE_DEFAULT_PATH} from './template.mjs';
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-template-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('themeTemplate()', () => {
+  it('writes the template and returns a theme.template receipt', () => {
+    const res = themeTemplate({cwd: tmpDir});
+
+    expect(res).toEqual({
+      type: 'theme.template',
+      data: {path: THEME_TEMPLATE_DEFAULT_PATH, written: true, reason: null},
+    });
+    const written = fs.readFileSync(path.join(tmpDir, THEME_TEMPLATE_DEFAULT_PATH), 'utf-8');
+    expect(written).toMatch(/defineTheme/);
+  });
+
+  it('does not carry our copyright header into the consumer tree', () => {
+    themeTemplate({cwd: tmpDir});
+    const written = fs.readFileSync(path.join(tmpDir, THEME_TEMPLATE_DEFAULT_PATH), 'utf-8');
+    expect(written).not.toMatch(/Copyright \(c\) Meta Platforms/);
+    expect(written.startsWith('/**')).toBe(true);
+  });
+
+  it('leaves an existing file alone and says so', () => {
+    const dest = path.join(tmpDir, THEME_TEMPLATE_DEFAULT_PATH);
+    fs.writeFileSync(dest, '// mine\n');
+
+    const res = themeTemplate({cwd: tmpDir});
+
+    expect(res.data).toEqual({
+      path: THEME_TEMPLATE_DEFAULT_PATH,
+      written: false,
+      reason: 'exists',
+    });
+    expect(fs.readFileSync(dest, 'utf-8')).toBe('// mine\n');
+  });
+
+  it('overwrites when asked', () => {
+    const dest = path.join(tmpDir, THEME_TEMPLATE_DEFAULT_PATH);
+    fs.writeFileSync(dest, '// mine\n');
+
+    const res = themeTemplate({cwd: tmpDir, overwrite: true});
+
+    expect(res.data.written).toBe(true);
+    expect(fs.readFileSync(dest, 'utf-8')).toMatch(/defineTheme/);
+  });
+
+  it('honors a custom path and creates its directory', () => {
+    const res = themeTemplate({cwd: tmpDir, targetPath: 'src/themes/starter.ts'});
+
+    expect(res.data.path).toBe(path.join('src', 'themes', 'starter.ts'));
+    expect(fs.existsSync(path.join(tmpDir, 'src/themes/starter.ts'))).toBe(true);
+  });
+
+  it('refuses a path that escapes the project', () => {
+    expect(() => themeTemplate({cwd: tmpDir, targetPath: '../escaped.ts'})).toThrow(
+      /theme template path/,
+    );
+    expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.ts'))).toBe(false);
+  });
+});

package/api/theme/theme.d.mts

@@ -2,6 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 export { themeAdd } from "./add/add.mjs";
+export { themeTemplate } from "./template/template.mjs";
 export { themeList } from "./list/list.mjs";
 export { listThemes } from "./_adapter.mjs";
 export { themeBuild, importSpecifier } from "./build/build.mjs";

package/api/theme/theme.mjs

@@ -10,5 +10,6 @@
 
 export {themeBuild, importSpecifier} from './build/build.mjs';
 export {themeAdd} from './add/add.mjs';
+export {themeTemplate} from './template/template.mjs';
 export {themeList} from './list/list.mjs';
 export {listThemes} from './_adapter.mjs';

package/api/theme/theme.type.d.mts

@@ -66,3 +66,16 @@ export type ThemeAddResponse = {
         files: string[];
     };
 };
+/**
+ * xds --json theme template
+ * `written: false` with `reason: 'exists'` is a success: the command is safe to
+ * re-run, and an edited template is the consumer's file to keep.
+ */
+export type ThemeTemplateResponse = {
+    type: "theme.template";
+    data: {
+        path: string;
+        written: boolean;
+        reason: "exists" | null;
+    };
+};

package/api/theme/theme.type.mjs

@@ -12,9 +12,10 @@
  * xds --json theme build <file> --check     -> theme.build.check
  * xds --json theme list                     -> theme.list
  * xds --json theme add <slug>               -> theme.add
+ * xds --json theme template                 -> theme.template
  * (file not found / parse error)            -> CLIError
  *
- * @position api — colocated typedefs for api/theme/{theme,build,add,list,_adapter}
+ * @position api — colocated typedefs for api/theme/{theme,build,add,list,template,_adapter}
  */
 
 /**
@@ -54,6 +55,15 @@
  * @property {{slug: string, displayName: string, maintained: boolean, outputDir: string, entry: string, exportName: string, files: string[]}} data
  */
 
+/**
+ * xds --json theme template
+ * `written: false` with `reason: 'exists'` is a success: the command is safe to
+ * re-run, and an edited template is the consumer's file to keep.
+ * @typedef {object} ThemeTemplateResponse
+ * @property {'theme.template'} type
+ * @property {{path: string, written: boolean, reason: 'exists' | null}} data
+ */
+
 // Make this a module so the @typedefs above are importable as types via
 // `import('./theme.type.mjs').ThemeBuildResponse` (and re-exportable from a .d.ts).
 export {};