@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/api/template/template-suffix.test.mjs

@@ -1,25 +1,20 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file The canonical `.template.{ts,mjs,js}` suffix is discovered identically
- * to the legacy `.doc.{ts,mjs,js}` suffix.
+ * @file The canonical `.doc.{mjs,ts,js}` suffix is discovered identically
+ * to the released `.template.{ts,mjs,js}` compatibility suffix.
  *
- * Template-spec files are named for what they are: a scaffoldable TEMPLATE
- * stamped with `type: 'page' | 'block'`. The `.doc.*` suffix was
- * inherited from the component-doc convention and is still accepted during the
- * transition. These tests stand up integration templates and external blocks in
- * both families and assert byte-for-byte-equivalent discovery + scaffolding.
+ * New authoring writes `.doc.mjs`, the canonical typed descriptor. Stable
+ * 0.6.0 already accepted `.template.*`, so these tests
+ * keep that family as a compatibility input and assert equivalent discovery +
+ * scaffolding.
  */
 
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {
-  template,
-  findShowcase,
-  findRelatedBlocks,
-} from './template.mjs';
+import {template, findShowcase, findRelatedBlocks} from './template.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -82,8 +77,8 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
-describe('integration templates: .template.* discovered like legacy .doc.*', () => {
-  for (const suffix of ['.template.ts', '.template.mjs', '.doc.mjs']) {
+describe('integration templates: canonical .doc.* plus released .template.* compatibility', () => {
+  for (const suffix of ['.doc.mjs', '.doc.ts', '.template.mjs']) {
     it(`discovers + lists a page template authored as ${suffix}`, async () => {
       const pkgDir = installWidgets(tmpDir);
       writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
@@ -124,7 +119,7 @@ describe('integration templates: .template.* discovered like legacy .doc.*', ()
     });
   }
 
-  it('treats a .template.ts and a legacy .doc.mjs identically (same shape)', async () => {
+  it('treats canonical .doc.mjs and released .template.ts identically (same shape)', async () => {
     const pkgDir = installWidgets(tmpDir);
     writeTemplate(pkgDir, 'gauge', {kind: 'block', suffix: '.template.ts'});
     writeTemplate(pkgDir, 'chip', {kind: 'block', suffix: '.doc.mjs'});
@@ -143,12 +138,33 @@ describe('integration templates: .template.* discovered like legacy .doc.*', ()
     expect(gauge.type).toBe(chip.type);
     expect(gauge.package).toBe(chip.package);
   });
+  it('lists both same-stem specs and reads the id as ambiguous', async () => {
+    for (const [first, second] of [
+      ['.doc.mjs', '.template.ts'],
+      ['.doc.ts', '.doc.mjs'],
+    ]) {
+      const pkgDir = installWidgets(tmpDir);
+      fs.rmSync(path.join(pkgDir, 'templates'), {recursive: true, force: true});
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix: first});
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix: second});
+
+      const result = await template(undefined, {list: true, cwd: tmpDir});
+      expect(
+        result.data.filter(entry => entry.id === 'pricing'),
+        `${first} + ${second}`,
+      ).toHaveLength(2);
+      await expect(
+        template('pricing', {cwd: tmpDir}),
+        `${first} + ${second}`,
+      ).rejects.toMatchObject({code: 'ERR_AMBIGUOUS_TEMPLATE'});
+    }
+  });
 });
 
-describe('external showcase blocks: .template.* discovered like legacy .doc.*', () => {
+describe('external showcase blocks: canonical .doc.* plus released .template.* compatibility', () => {
   /**
    * Create a consumer whose @test/ext package contributes two showcase blocks,
-   * one authored as `Foo.template.ts` and one as legacy `Bar.doc.mjs`.
+   * one authored with released `Foo.template.ts` and one with canonical `Bar.doc.mjs`.
    */
   function makeShowcaseFixture() {
     // Symlink the real core package (needed by findCoreDir during discovery).
@@ -166,7 +182,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
     const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
     const blocksDir = path.join(extDir, 'blocks', 'components');
 
-    // Foo showcase — canonical .template.ts (stamped type: 'block' default export).
+    // Foo showcase — released .template.ts compatibility input.
     const fooDir = path.join(blocksDir, 'Foo');
     fs.mkdirSync(fooDir, {recursive: true});
     fs.writeFileSync(
@@ -185,7 +201,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
       "'use client';\nexport default function FooShowcase() { return <div>Foo</div>; }",
     );
 
-    // Bar showcase — legacy .doc.mjs (export const doc).
+    // Bar showcase — canonical .doc.mjs (historical named export).
     const barDir = path.join(blocksDir, 'Bar');
     fs.mkdirSync(barDir, {recursive: true});
     fs.writeFileSync(
@@ -209,7 +225,11 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
       path.join(extDir, 'package.json'),
       JSON.stringify({
         name: '@test/ext',
-        astryx: {docs: './src', category: 'Common', blocks: './blocks/components'},
+        astryx: {
+          docs: './src',
+          category: 'Common',
+          blocks: './blocks/components',
+        },
       }),
     );
     fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});
@@ -223,7 +243,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
     expect(result.filePath).toContain('FooShowcase.tsx');
   });
 
-  it('findShowcase resolves a legacy .doc.mjs external block by componentsUsed', async () => {
+  it('findShowcase resolves a canonical .doc.mjs external block by componentsUsed', async () => {
     makeShowcaseFixture();
     const result = await findShowcase('Bar', tmpDir);
     expect(result).not.toBeNull();

package/api/template/template.d.mts

@@ -31,7 +31,7 @@ export function template(name?: string, options?: {
     skeleton?: boolean | undefined;
     cdn?: string | boolean | undefined;
     show?: boolean | undefined;
-    type?: "block" | "page" | undefined;
+    type?: "page" | "block" | undefined;
     package?: string | undefined;
     cwd?: string | undefined;
 }): Promise<{

package/api/template/template.doc.mjs

@@ -11,20 +11,33 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'template',
+  namespace: 'cli/api',
   displayName: 'template()',
   summary: 'List, inspect, or scaffold page and block templates.',
   description:
     'One entry point for the template family: with no name it lists the discovered ' +
     "templates; with a name it returns that template's source, a layout skeleton, or " +
-    'scaffolds it into the project. Templates are discovered across core, external ' +
-    'packages, and integrations, so the same id can appear in more than one place; ' +
-    'narrow an ambiguous name with type and/or package. The cdn option writes the ' +
-    'annotated no-build-step CDN starter page, which ships as an asset rather than as ' +
+    'scaffolds it into the project. A configured integration may replace a Core ' +
+    'template id for unqualified discovery and lookup; package selection still ' +
+    'addresses the Core original. Other duplicate ids remain ambiguous and can be ' +
+    'narrowed by type and/or package. The cdn option writes the annotated ' +
+    'no-build-step CDN starter page, which ships as an asset rather than as ' +
     'a discovered template.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'template(name?: string, options?: TemplateOptions): Promise<TemplateListResponse | TemplateShowResponse | TemplateSkeletonResponse | TemplateCopyResponse | TemplateCdnResponse>',
-  keywords: ['template', 'scaffold', 'page', 'block', 'skeleton', 'starter', 'cdn', 'esm', 'importmap', 'no-build'],
+  keywords: [
+    'template',
+    'scaffold',
+    'page',
+    'block',
+    'skeleton',
+    'starter',
+    'cdn',
+    'esm',
+    'importmap',
+    'no-build',
+  ],
   params: [
     {
       name: 'name',
@@ -69,13 +82,14 @@ export const doc = {
       name: 'options.package',
       type: 'string',
       description:
-        'Narrow lookups to templates from a specific owning package (core templates report @astryxdesign/core).',
+        'Narrow lookups to templates from a specific owning package. Without it, a valid integration replacement is selected for the Core id; use @astryxdesign/core to select the original.',
     },
     {
       name: 'options.targetPath',
       type: 'string',
       description:
-        'Destination (relative to cwd) to scaffold the template into. Its presence switches a named lookup into a copy.',
+        'Destination (relative to cwd) to scaffold the template into. Its presence switches a named lookup into a copy. ' +
+        'A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; any other path is a directory, which receives page.tsx for a page template or the block\'s own file name for a block.',
     },
     {
       name: 'options.overwrite',
@@ -88,13 +102,14 @@ export const doc = {
       type: 'string',
       description:
         'Directory to discover templates and resolve the target path from.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
     {
       type: 'template.list',
       description:
-        'Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags. Filtered by type/package when provided.',
+        'The effective templates (page + block); a valid integration replacement takes the place of its Core target and carries `replaces`. Pass `package` to list one package, including replaced Core originals.',
     },
     {
       type: 'template.show',
@@ -120,7 +135,7 @@ export const doc = {
   throws: [
     {
       code: 'ERR_UNKNOWN_TEMPLATE',
-      when: 'the named template does not exist, or --skeleton is run without a name',
+      when: 'the named template does not exist, or options.skeleton is set without a name',
     },
     {
       code: 'ERR_AMBIGUOUS_TEMPLATE',
@@ -141,7 +156,15 @@ export const doc = {
   ],
   examples: [
     {label: 'List templates', code: 'const {data} = await template();'},
+    {
+      label: 'List exact Core ids',
+      code: "await template(undefined, {list: true, package: '@astryxdesign/core'});",
+    },
     {label: 'Show source', code: "await template('dashboard');"},
+    {
+      label: 'Select a replaced Core original',
+      code: "await template('shell-side-nav', {package: '@astryxdesign/core'});",
+    },
     {
       label: 'Layout skeleton',
       code: "await template('dashboard', {skeleton: true});",

package/api/template/template.mjs

@@ -15,7 +15,13 @@
  *   ./list, ./show, ./skeleton, ./copy, ./cdn and shared discovery in foundation/discovery.
  */
 
-import {discoverAll, pkgOf} from '../../foundation/discovery/template-adapter.mjs';
+import {
+  discoverAll,
+  discoverAllResolved,
+  discoverAllUnresolved,
+  pkgOf,
+  templateLookupIds,
+} from '../../foundation/discovery/template-adapter.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {templateList} from './list/list.mjs';
@@ -88,18 +94,49 @@ export async function template(name, options = {}) {
     });
   }
 
-  const templates = await discoverAll(cwd);
+  const templates =
+    packageFilter === '@astryxdesign/core'
+      ? await discoverAllUnresolved(cwd)
+      : packageFilter
+        ? await discoverAllResolved(cwd)
+        : await discoverAll(cwd);
 
   if (list || (!name && !skeleton)) {
     return templateList(templates, {type, package: packageFilter});
   }
 
-  // Resolve `name` to a single template. The same id can appear across types
-  // and/or packages (e.g. a core "hero" page and an integration "hero"
-  // block); narrow with --type / --package.
-  let candidates = templates.filter(t => t.dirName === name);
-  if (type) candidates = candidates.filter(t => t.type === type);
-  if (packageFilter) candidates = candidates.filter(t => pkgOf(t) === packageFilter);
+  // Resolve `name` to a single template. Without an explicit package, an active
+  // integration replacement owns the Core id it names. Package-qualified lookup
+  // stays exact, which keeps the original addressable as
+  // `--package @astryxdesign/core`.
+  let pool = templates;
+  if (type) pool = pool.filter(t => t.type === type);
+  if (packageFilter) pool = pool.filter(t => pkgOf(t) === packageFilter);
+  // With no name there is nothing to replace; `--skeleton` alone must still
+  // fail as an unknown template.
+  const replacements =
+    packageFilter || name == null ? [] : pool.filter(t => t.replaces === name);
+  let candidates = packageFilter
+    ? pool.filter(t => t.dirName === (name ?? ''))
+    : replacements.length > 0
+      ? replacements
+      : pool.filter(t => templateLookupIds(t).includes(name ?? ''));
+
+  // A rejected same-id declaration must not displace Core for the bare command,
+  // but a different-kind integration template remains reachable with --type.
+  if (!packageFilter && !type && candidates.length > 1) {
+    const core = candidates.filter(t => pkgOf(t) === '@astryxdesign/core');
+    const rejected = candidates.filter(t => pkgOf(t) !== '@astryxdesign/core');
+    if (
+      core.length === 1 &&
+      rejected.length === candidates.length - 1 &&
+      rejected.every(
+        t => t.replacementRejected && t.replacementTarget === (name ?? ''),
+      )
+    ) {
+      candidates = core;
+    }
+  }
 
   if (name && candidates.length === 0) {
     throw new AstryxError(

package/api/template/template.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json template [--list]
+ * astryx --json template [--list]
  */
 export type TemplateListResponse = {
     type: "template.list";
@@ -21,6 +21,10 @@ export type TemplateListEntry = {
      * - Owning package; core (built-in) templates report '@astryxdesign/core'.
      */
     package: string;
+    /**
+     * - Core template id this integration template replaces by default.
+     */
+    replaces?: string | undefined;
     /**
      * - Optional grouping/category label.
      */
@@ -53,7 +57,7 @@ export type TemplateListEntry = {
     scaffold?: boolean | undefined;
 };
 /**
- * xds --json template <name>
+ * astryx --json template <name>
  */
 export type TemplateShowResponse = {
     type: "template.show";
@@ -66,7 +70,7 @@ export type TemplateShowResponse = {
     };
 };
 /**
- * xds --json template <name> --skeleton
+ * astryx --json template <name> --skeleton
  */
 export type TemplateSkeletonResponse = {
     type: "template.skeleton";
@@ -78,7 +82,7 @@ export type TemplateSkeletonResponse = {
     };
 };
 /**
- * xds --json template <name> [path]
+ * astryx --json template <name> [path]
  */
 export type TemplateCopyResponse = {
     type: "template.copy";
@@ -90,7 +94,7 @@ export type TemplateCopyResponse = {
     };
 };
 /**
- * xds --json template --cdn [path]
+ * astryx --json template --cdn [path]
  * `written: false` with `reason: 'exists'` is a success: the command is safe to
  * re-run, and an edited page is the consumer's file to keep. `version` is the
  * Astryx version every CDN URL in the file was pinned to.
@@ -116,17 +120,11 @@ export type TemplateOptions = {
      */
     cdn?: string | boolean | undefined;
     /**
-     * Filter templates by kind: 'page' or 'block'. Only applies to list views.
+     * Filter templates by kind: 'page' or 'block'. Narrows both list and direct lookup.
      */
-    type?: "block" | "page" | undefined;
+    type?: "page" | "block" | undefined;
     /**
-     * Narrow to templates from a specific package (id-only lookups across packages are ambiguous).
+     * Narrow to templates from a specific package. Without it, a valid integration replacement is selected for the Core id;
      */
     package?: string | undefined;
-    targetPath?: string | undefined;
-    /**
-     * Overwrite an existing target file instead of erroring (ERR_FILE_EXISTS).
-     */
-    overwrite?: boolean | undefined;
-    cwd?: string | undefined;
 };

package/api/template/template.type.mjs

@@ -6,18 +6,18 @@
  *
  * Each template is exactly two files: page.tsx (code) + template.doc.mjs (metadata).
  *
- * Invocation                                 -> type discriminator
+ * Invocation                               -> type discriminator
  * ------------------------------------------------------------------
- * xds --json template [--list]              -> template.list
- * xds --json template <name>               -> template.show
- * xds --json template <name> --skeleton    -> template.skeleton
- * xds --json template <name> [path]        -> template.copy
- * xds --json template --cdn [path]         -> template.cdn
- * (unknown template)                        -> CLIError
+ * astryx --json template [--list]          -> template.list
+ * astryx --json template <name>            -> template.show
+ * astryx --json template <name> --skeleton -> template.skeleton
+ * astryx --json template <name> [path]     -> template.copy
+ * astryx --json template --cdn [path]      -> template.cdn
+ * (unknown template)                       -> CLIError
  */
 
 /**
- * xds --json template [--list]
+ * astryx --json template [--list]
  * @typedef {object} TemplateListResponse
  * @property {'template.list'} type
  * @property {TemplateListEntry[]} data
@@ -31,6 +31,7 @@
  * @property {string} description
  * @property {'page' | 'block'} type
  * @property {string} package - Owning package; core (built-in) templates report '@astryxdesign/core'.
+ * @property {string} [replaces] - Core template id this integration template replaces by default.
  * @property {string} [category] - Optional grouping/category label.
  * @property {string[]} [componentsUsed] - Component display names the template composes.
  * @property {number} [aspectRatio] - Block preview width/height ratio.
@@ -43,7 +44,7 @@
  */
 
 /**
- * xds --json template <name>
+ * astryx --json template <name>
  * @typedef {object} TemplateShowResponse
  * @property {'template.show'} type
  * @property {object} data
@@ -55,7 +56,7 @@
  */
 
 /**
- * xds --json template <name> --skeleton
+ * astryx --json template <name> --skeleton
  * @typedef {object} TemplateSkeletonResponse
  * @property {'template.skeleton'} type
  * @property {object} data
@@ -66,7 +67,7 @@
  */
 
 /**
- * xds --json template <name> [path]
+ * astryx --json template <name> [path]
  * @typedef {object} TemplateCopyResponse
  * @property {'template.copy'} type
  * @property {object} data
@@ -77,7 +78,7 @@
  */
 
 /**
- * xds --json template --cdn [path]
+ * astryx --json template --cdn [path]
  * `written: false` with `reason: 'exists'` is a success: the command is safe to
  * re-run, and an edited page is the consumer's file to keep. `version` is the
  * Astryx version every CDN URL in the file was pinned to.
@@ -93,8 +94,8 @@
  * @property {boolean} [skeleton]
  * @property {boolean} [show]
  * @property {boolean | string} [cdn] Write the no-build-step CDN starter page instead of resolving a template. A string is used as the destination path.
- * @property {'page' | 'block'} [type] Filter templates by kind: 'page' or 'block'. Only applies to list views.
- * @property {string} [package] Narrow to templates from a specific package (id-only lookups across packages are ambiguous).
+ * @property {'page' | 'block'} [type] Filter templates by kind: 'page' or 'block'. Narrows both list and direct lookup.
+ * @property {string} [package] Narrow to templates from a specific package. Without it, a valid integration replacement is selected for the Core id; @astryxdesign/core explicitly selects the original.
  * @property {string} [targetPath]
  * @property {boolean} [overwrite] Overwrite an existing target file instead of erroring (ERR_FILE_EXISTS).
  * @property {string} [cwd]

package/api/theme/_adapter.d.mts

@@ -13,7 +13,7 @@
 export function listThemes(): BundledTheme[];
 /**
  * Bundled themes plus source themes from integrations installed in `cwd`.
- * A project/config load failure degrades to the bundled catalog, preserving the
+ * A project/config load failure degrades to the bundled set, preserving the
  * command's historical usefulness outside a configured project.
  * @param {string} [cwd]
  * @returns {Promise<import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[]>}
@@ -35,6 +35,5 @@ export function findTheme(slug?: string, options?: {
  */
 export type BundledTheme = Pick<import("../../foundation/discovery/theme-discovery.mjs").DiscoveredTheme, "slug" | "displayName" | "description" | "maintained" | "entry" | "exportName" | "files">;
 import { BUNDLED_THEME_PACKAGE } from '../../foundation/discovery/theme-discovery.mjs';
-import { MANIFEST_PATH } from '../../foundation/discovery/theme-discovery.mjs';
 import { THEMES_DIR } from '../../foundation/discovery/theme-discovery.mjs';
-export { BUNDLED_THEME_PACKAGE, MANIFEST_PATH, THEMES_DIR };
+export { BUNDLED_THEME_PACKAGE, THEMES_DIR };

package/api/theme/_adapter.mjs

@@ -5,20 +5,19 @@
  *
  * `listThemes()` intentionally keeps its historical synchronous, bundled-only
  * contract. Project-aware callers use `listAvailableThemes()`, which asks
- * Project for the bundled catalog plus every installed integration catalog.
+ * Project for the bundled themes plus every installed integration theme root.
  */
 
 import {Project} from '../../foundation/config/project.mjs';
 import {
   BUNDLED_THEME_PACKAGE,
-  MANIFEST_PATH,
   THEMES_DIR,
   discoverBundledThemes,
 } from '../../foundation/discovery/theme-discovery.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
-export {BUNDLED_THEME_PACKAGE, MANIFEST_PATH, THEMES_DIR};
+export {BUNDLED_THEME_PACKAGE, THEMES_DIR};
 
 /**
  * A bundled theme entry kept for the historical public `listThemes()` helper.
@@ -55,7 +54,7 @@ function availableBundledThemes() {
 /**
  * Load available themes with any package-owned integration issues found while
  * discovering them. The issue set lets a package-scoped lookup distinguish an
- * absent theme from an installed package whose catalog is broken.
+ * absent theme from an installed package whose theme descriptors are broken.
  * @param {string} cwd
  * @returns {Promise<{themes: import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[], issues: Array<import('../../foundation/integrations/issue').AstryxIntegrationIssue & {package: string}>}>}
  */
@@ -71,7 +70,7 @@ async function availableThemeState(cwd) {
 
 /**
  * Bundled themes plus source themes from integrations installed in `cwd`.
- * A project/config load failure degrades to the bundled catalog, preserving the
+ * A project/config load failure degrades to the bundled set, preserving the
  * command's historical usefulness outside a configured project.
  * @param {string} [cwd]
  * @returns {Promise<import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[]>}

package/api/theme/add/add.binary.test.mjs

@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {themeAdd} from './add.mjs';
+
+const HEADER = '// Copyright (c) Meta Platforms, Inc. and affiliates.\n\n';
+
+let tmpDir;
+
+/** Every byte value, so any lossy text decoding shows up as a changed file. */
+const FONT_BYTES = Buffer.concat([
+  Buffer.from('wOF2'),
+  Buffer.from(Array.from({length: 256}, (_, byte) => byte)),
+]);
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-binary-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({
+      name: 'consumer',
+      dependencies: {'@acme/themes': '^1.0.0'},
+    }),
+  );
+  const packageDir = path.join(tmpDir, 'node_modules', '@acme', 'themes');
+  const themeDir = path.join(packageDir, 'themes', 'ocean');
+  fs.mkdirSync(path.join(themeDir, 'fonts'), {recursive: true});
+  fs.writeFileSync(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify({name: '@acme/themes', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(packageDir, 'astryx.integration.mjs'),
+    "export default {themes: './themes'};\n",
+  );
+  fs.writeFileSync(
+    path.join(themeDir, 'oceanTheme.doc.mjs'),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Integration theme that ships a font.', maintained: true};
+`,
+  );
+  fs.writeFileSync(
+    path.join(themeDir, 'oceanTheme.ts'),
+    `${HEADER}export const oceanTheme = {};\n`,
+  );
+  fs.writeFileSync(path.join(themeDir, 'fonts', 'ocean.woff2'), FONT_BYTES);
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('themeAdd copies every file of the theme', () => {
+  it('copies a binary file byte for byte', async () => {
+    const result = await themeAdd('ocean', {
+      cwd: tmpDir,
+      package: '@acme/themes',
+    });
+
+    expect(result.data.files).toEqual([
+      'oceanTheme.ts',
+      'fonts/ocean.woff2',
+      'oceanTheme.doc.mjs',
+    ]);
+    const copied = fs.readFileSync(
+      path.join(tmpDir, 'src', 'themes', 'ocean', 'fonts', 'ocean.woff2'),
+    );
+    expect(copied.equals(FONT_BYTES)).toBe(true);
+  });
+
+  it('still strips the repo header from a text source', async () => {
+    await themeAdd('ocean', {cwd: tmpDir, package: '@acme/themes'});
+
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, 'src', 'themes', 'ocean', 'oceanTheme.ts'),
+        'utf-8',
+      ),
+    ).toBe('export const oceanTheme = {};\n');
+  });
+});