@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/api/integration/add-contribution.test.mjs

@@ -12,6 +12,7 @@ import {
   integrationAddTemplate,
 } from './add-contribution.mjs';
 import {validateLocalIntegration} from './validate-integration.mjs';
+import {DOCS_TREE_CLI} from '../../foundation/integrations/cli-requirement.mjs';
 
 let tmpDir;
 
@@ -77,6 +78,7 @@ describe('integrationAdd component', () => {
       path.join(tmpDir, 'components/MyWidget.doc.mjs'),
       'utf-8',
     );
+    expect(doc).toContain("@astryxdesign/cli/authoring').ComponentDoc");
     expect(doc).toContain("type: 'component'");
     expect(doc).toContain("name: 'MyWidget'");
     expect(doc).toContain('props: []');
@@ -118,14 +120,14 @@ describe('integrationAdd component', () => {
     );
     expect(pkg.exports).toEqual({
       '.': './index.mjs',
-      './components/MyWidget.tsx': './components/MyWidget.tsx',
+      './components/MyWidget': './components/MyWidget.tsx',
     });
     expect(
       fs.readFileSync(
         path.join(tmpDir, 'components/MyWidget.doc.mjs'),
         'utf-8',
       ),
-    ).toContain('import: "@acme/integration/components/MyWidget.tsx"');
+    ).toContain('import: "@acme/integration/components/MyWidget"');
   });
 
   it('does not create exports when the package has no exports map', async () => {
@@ -143,7 +145,7 @@ describe('integrationAdd component', () => {
     setup({
       exports: {
         '.': './index.mjs',
-        './components/MyWidget.tsx': './different.tsx',
+        './components/MyWidget': './different.tsx',
       },
     });
 
@@ -304,6 +306,7 @@ describe('integrationAdd doc', () => {
       path.join(tmpDir, 'docs/my-guide.doc.mjs'),
       'utf-8',
     );
+    expect(doc).toContain("@astryxdesign/cli/authoring').ReferenceDoc");
     expect(doc).toContain("type: 'generic'");
     expect(doc).toContain("name: 'my-guide'");
 
@@ -312,6 +315,142 @@ describe('integrationAdd doc', () => {
     expect(docErrors).toEqual([]);
   });
 
+  it('refuses to write from a folder with no package.json into the package above it', async () => {
+    setupBare();
+    const inside = path.join(tmpDir, 'kit');
+    fs.mkdirSync(inside);
+    await expect(
+      integrationAdd('doc', 'my-guide', {cwd: inside, parent: 'acme'}),
+    ).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+      message: expect.stringContaining('has no package.json'),
+    });
+    expect(fs.existsSync(path.join(tmpDir, 'docs'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'astryx.integration.mjs'))).toBe(false);
+  });
+
+  it('finds an integration from a folder inside it', async () => {
+    setup();
+    const inside = path.join(tmpDir, 'src');
+    fs.mkdirSync(inside);
+    const result = await integrationAdd('doc', 'my-guide', {cwd: inside});
+    expect(result.data.files).toContain('docs/my-guide.doc.mjs');
+    expect(fs.existsSync(path.join(tmpDir, 'docs/my-guide.doc.mjs'))).toBe(true);
+  });
+
+  it('places a guide in a namespace of the package, writing the namespace once', async () => {
+    setup();
+    const first = await integrationAdd('doc', 'deploying', {
+      cwd: tmpDir,
+      parent: 'acme',
+    });
+    expect(first.data.files).toEqual(
+      expect.arrayContaining(['docs/deploying.doc.mjs', 'docs/acme.doc.mjs']),
+    );
+    const guide = fs.readFileSync(path.join(tmpDir, 'docs/deploying.doc.mjs'), 'utf-8');
+    expect(guide).toContain("placement: {parent: 'namespace:acme', slot: 'guides'}");
+    const namespace = fs.readFileSync(path.join(tmpDir, 'docs/acme.doc.mjs'), 'utf-8');
+    expect(namespace).toContain("type: 'namespace'");
+    expect(namespace).toContain("guides: {title: 'Guides', accepts: {kinds: ['generic']}}");
+
+    // The namespace doc needs a CLI that reads it, declared as an optional peer.
+    const pkg = JSON.parse(fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'));
+    expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': `>=${DOCS_TREE_CLI}`});
+    expect(pkg.peerDependenciesMeta).toEqual({'@astryxdesign/cli': {optional: true}});
+
+    const second = await integrationAdd('doc', 'upgrading', {
+      cwd: tmpDir,
+      parent: 'acme',
+    });
+    expect(second.data.files).not.toContain('docs/acme.doc.mjs');
+
+    const validation = await validateLocalIntegration(tmpDir);
+    expect(validation.issues.filter(i => i.code === 'invalid_doc')).toEqual([]);
+  });
+
+  it('finds the --parent namespace by its name, wherever its file is, and uses its slot', async () => {
+    setup({manifest: "export default {docs: './docs'};\n"});
+    fs.mkdirSync(path.join(tmpDir, 'docs', 'ns'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'ns', 'acme.doc.mjs'),
+      "export default {type: 'namespace', name: 'acme', title: 'Acme', summary: 'Acme.', slots: {items: {title: 'Items', accepts: {kinds: ['generic']}}}};\n",
+    );
+    const result = await integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'acme'});
+    expect(result.data.files).not.toContain('docs/acme.doc.mjs');
+    expect(fs.existsSync(path.join(tmpDir, 'docs', 'acme.doc.mjs'))).toBe(false);
+    expect(fs.readFileSync(path.join(tmpDir, 'docs', 'deploying.doc.mjs'), 'utf-8')).toContain(
+      "placement: {parent: 'namespace:acme', slot: 'items'}",
+    );
+  });
+
+  it('refuses --parent when its file is not that namespace, or the namespace has no slot for a guide', async () => {
+    setup({manifest: "export default {docs: './docs'};\n"});
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    const nsFile = path.join(tmpDir, 'docs', 'acme.doc.mjs');
+    fs.writeFileSync(
+      nsFile,
+      "export default {type: 'generic', name: 'acme', title: 'Acme', description: 'A topic.', sections: [{title: 'Only', content: [{type: 'prose', text: 'x'}]}]};\n",
+    );
+    await expect(
+      integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'acme'}),
+    ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
+    // A fresh file: the module loader keeps the first import of a path.
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'beta.doc.mjs'),
+      "export default {type: 'namespace', name: 'beta', title: 'Beta', summary: 'Beta.', slots: {items: {title: 'Items', accepts: {kinds: ['function']}}}};\n",
+    );
+    await expect(
+      integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'beta'}),
+    ).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+      message: expect.stringContaining('no slot that takes a guide'),
+    });
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'gamma.doc.mjs'),
+      "export default {type: 'namespace', name: 'gamma', title: 'Gamma', summary: 'Gamma.', slots: {guides: {title: 'Guides', accepts: {kinds: ['function']}}, more: {title: 'More', accepts: {kinds: ['generic']}}, extra: {title: 'Extra', accepts: {kinds: ['generic']}}}};\n",
+    );
+    await expect(
+      integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'gamma'}),
+    ).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+      message: expect.stringContaining('more than one slot that takes a guide (more, extra)'),
+    });
+    expect(fs.existsSync(path.join(tmpDir, 'docs', 'deploying.doc.mjs'))).toBe(false);
+  });
+
+  it('raises a CLI peer that admits a CLI too old for namespace docs, and keeps one that does not', async () => {
+    setup();
+    const file = path.join(tmpDir, 'package.json');
+    const write = (/** @type {string} */ range) => {
+      const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+      pkg.peerDependencies = {'@astryxdesign/cli': range};
+      fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+    };
+    write('^0.6.0');
+    await integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'acme'});
+    expect(JSON.parse(fs.readFileSync(file, 'utf-8')).peerDependencies).toEqual({
+      '@astryxdesign/cli': `>=${DOCS_TREE_CLI}`,
+    });
+    write('^9.1.0');
+    await integrationAdd('doc', 'upgrading', {cwd: tmpDir, parent: 'acme'});
+    expect(JSON.parse(fs.readFileSync(file, 'utf-8')).peerDependencies).toEqual({
+      '@astryxdesign/cli': '^9.1.0',
+    });
+  });
+
+  it('refuses --parent with a relationship, or a namespace name that is not a route segment', async () => {
+    setup();
+    await expect(
+      integrationAdd('doc', 'x', {cwd: tmpDir, parent: 'acme', replaces: 'getting-started'}),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+    await expect(
+      integrationAdd('doc', 'x', {cwd: tmpDir, parent: 'Acme Kit'}),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+    await expect(
+      integrationAdd('template', 'x', {cwd: tmpDir, parent: 'acme'}),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+  });
+
   it('includes replaces in the generated doc', async () => {
     setup();
     const result = await integrationAdd('doc', 'my-tokens', {
@@ -390,13 +529,14 @@ describe('integrationAdd template', () => {
     expect(result.data.kind).toBe('template');
     expect(result.data.name).toBe('my-widget');
     expect(result.data.root).toEqual({path: './templates', created: true});
-    expect(result.data.files).toContain('templates/my-widget.template.mjs');
+    expect(result.data.files).toContain('templates/my-widget.doc.mjs');
     expect(result.data.files).toContain('templates/my-widget.tsx');
 
     const spec = fs.readFileSync(
-      path.join(tmpDir, 'templates/my-widget.template.mjs'),
+      path.join(tmpDir, 'templates/my-widget.doc.mjs'),
       'utf-8',
     );
+    expect(spec).toContain("@astryxdesign/cli/authoring').TemplateDoc");
     expect(spec).toContain("type: 'page'");
     expect(spec).toContain("name: 'my-widget'");
 
@@ -421,7 +561,7 @@ describe('integrationAdd template', () => {
     );
     expect(pkg.exports).toEqual({
       '.': './index.mjs',
-      './templates/my-widget.tsx': './templates/my-widget.tsx',
+      './templates/my-widget': './templates/my-widget.tsx',
     });
   });
 
@@ -432,10 +572,11 @@ describe('integrationAdd template', () => {
       templateType: 'block',
     });
     const spec = fs.readFileSync(
-      path.join(tmpDir, 'templates/my-card.template.mjs'),
+      path.join(tmpDir, 'templates/my-card.doc.mjs'),
       'utf-8',
     );
     expect(spec).toContain("type: 'block'");
+    expect(spec).toContain('aspectRatio: 1');
   });
 
   it('rejects an invalid template type', async () => {
@@ -676,6 +817,35 @@ describe('custom root preservation', () => {
   });
 });
 
+describe('typed descriptor conformance', () => {
+  it('emits a strongly typed .doc.mjs for every canonical item writer', async () => {
+    setup();
+    await integrationAdd('component', 'MyWidget', {cwd: tmpDir});
+    await integrationAdd('doc', 'my-guide', {cwd: tmpDir});
+    await integrationAdd('template', 'my-page', {cwd: tmpDir});
+    await integrationAdd('theme', 'ocean', {cwd: tmpDir});
+
+    // Codemod and agent-doc keep their released formats for compatibility;
+    // no new kind may copy those exceptions.
+    for (const [relativePath, type] of [
+      ['components/MyWidget.doc.mjs', 'ComponentDoc'],
+      ['docs/my-guide.doc.mjs', 'ReferenceDoc'],
+      ['templates/my-page.doc.mjs', 'TemplateDoc'],
+      ['themes/ocean/oceanTheme.doc.mjs', 'ThemeDoc'],
+    ]) {
+      const source = fs.readFileSync(path.join(tmpDir, relativePath), 'utf-8');
+      expect(source).toContain(`@astryxdesign/cli/authoring').${type}`);
+      expect(source).toContain('export default {');
+    }
+    expect(
+      fs.existsSync(path.join(tmpDir, 'templates/my-page.template.mjs')),
+    ).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'themes/manifest.json'))).toBe(
+      false,
+    );
+  });
+});
+
 describe('public per-kind APIs', () => {
   it('exposes narrow functions for every non-theme contribution kind', async () => {
     setup();
@@ -711,6 +881,7 @@ describe('public dispatcher', () => {
     const result = await integrationAdd('theme', 'ocean', {cwd: tmpDir});
     expect(result.data).toMatchObject({kind: 'theme', name: 'ocean'});
     expect(result.data.files).toContain('themes/ocean/oceanTheme.ts');
+    expect(result.data.files).toContain('themes/ocean/oceanTheme.doc.mjs');
   });
 
   it('refuses a kind-specific option on the wrong kind', async () => {
@@ -731,3 +902,83 @@ describe('public dispatcher', () => {
     ).rejects.toThrow(/component, doc, template, codemod, agent-doc, or theme/);
   });
 });
+
+describe('dry-run receipts match the real write', () => {
+  /** Package states each writer has to plan for. */
+  const STATES = {
+    'no manifest': {pkg: {files: ['dist']}},
+    'an empty manifest': {pkg: {}, manifest: 'export default {};\n'},
+    'declared roots and an exports map': {
+      pkg: {files: ['dist'], exports: {'.': './dist/index.js'}},
+      manifest:
+        "export default {\n  components: './components',\n  docs: './docs',\n  templates: './templates',\n  codemods: './codemods',\n  themes: './themes',\n};\n",
+    },
+  };
+  /** @type {Array<[any, string, Record<string, unknown>]>} */
+  const KINDS = [
+    ['component', 'AcmeWidget', {}],
+    ['doc', 'deploying', {}],
+    ['template', 'account-page', {}],
+    ['template', 'account-card', {templateType: 'block'}],
+    ['codemod', 'rename-widget', {to: '1.2.0'}],
+    ['agent-doc', 'Run acme verify before finishing.', {}],
+    ['theme', 'ocean', {}],
+  ];
+
+  /** Every file under the package, keyed by project path, with its bytes. */
+  function snapshot() {
+    /** @type {Record<string, string>} */
+    const files = {};
+    /** @param {string} dir */
+    const walk = dir => {
+      for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else {
+          files[path.relative(tmpDir, full).split(path.sep).join('/')] =
+            fs.readFileSync(full, 'base64');
+        }
+      }
+    };
+    walk(tmpDir);
+    return files;
+  }
+
+  for (const [stateName, state] of Object.entries(STATES)) {
+    for (const [kind, name, options] of KINDS) {
+      it(`${kind} ${name} in a package with ${stateName}`, async () => {
+        fs.writeFileSync(
+          path.join(tmpDir, 'package.json'),
+          `${JSON.stringify({name: '@acme/integration', version: '1.0.0', ...state.pkg}, null, 2)}\n`,
+        );
+        if (state.manifest != null) {
+          fs.writeFileSync(
+            path.join(tmpDir, 'astryx.integration.mjs'),
+            state.manifest,
+          );
+        }
+        const before = snapshot();
+
+        const plan = await integrationAdd(kind, name, {
+          cwd: tmpDir,
+          dryRun: true,
+          ...options,
+        });
+        expect(snapshot()).toEqual(before);
+
+        const written = await integrationAdd(kind, name, {
+          cwd: tmpDir,
+          ...options,
+        });
+        const after = snapshot();
+        const changed = Object.keys(after)
+          .filter(file => after[file] !== before[file])
+          .sort();
+
+        expect(written.data.root).toEqual(plan.data.root);
+        expect(written.data.files).toEqual(plan.data.files);
+        expect([...written.data.files].sort()).toEqual(changed);
+      });
+    }
+  }
+});

package/api/integration/add-helpers.d.mts

@@ -8,7 +8,7 @@ export function findPackageDir(startDir: string): string;
 /**
  * @typedef {object} WritePlan
  * @property {string} path
- * @property {string} contents
+ * @property {string | Buffer} contents a Buffer is written byte for byte
  * @property {boolean} createOnly
  * @property {Buffer} [expectedOriginal] bytes captured before validation;
  *   a different current file is a concurrent edit and must never be overwritten
@@ -56,7 +56,10 @@ export function packageJsonUpdate(packageFile: string, rootPath: string, manifes
 export function applyWrites(plans: WritePlan[]): () => void;
 export type WritePlan = {
     path: string;
-    contents: string;
+    /**
+     * a Buffer is written byte for byte
+     */
+    contents: string | Buffer;
     createOnly: boolean;
     /**
      * bytes captured before validation;

package/api/integration/add-helpers.mjs

@@ -5,7 +5,8 @@
  *
  * Hosts the atomic staged-write transaction, package.json files-array
  * maintenance, package-dir resolution, and project-path normalization that
- * every `integration add <kind>` command needs. Stateless and side-effect-free
+ * every `integration add <kind>` command needs. `theme add` and `theme build`
+ * write through the same transaction. Stateless and side-effect-free
  * outside of {@link applyWrites}.
  */
 
@@ -40,7 +41,7 @@ export function findPackageDir(startDir) {
 /**
  * @typedef {object} WritePlan
  * @property {string} path
- * @property {string} contents
+ * @property {string | Buffer} contents a Buffer is written byte for byte
  * @property {boolean} createOnly
  * @property {Buffer} [expectedOriginal] bytes captured before validation;
  *   a different current file is a concurrent edit and must never be overwritten
@@ -192,21 +193,29 @@ export function packageJsonUpdate(
 
 // ── Atomic staged-write transaction ─────────────────────────────────
 
-/** @param {string} file */
+/**
+ * @param {string} file
+ * @returns {boolean} false when the file is still there
+ */
 function removeTemporary(file) {
   try {
     fs.rmSync(file, {force: true});
+    return true;
   } catch {
     // Best effort. The transaction error remains the actionable failure.
+    return false;
   }
 }
 
 /**
  * Restore writes that already published.  Best-effort so callers preserve
- * the original actionable error.
+ * the original actionable error; returns every path it could not put back.
  * @param {Array<WritePlan & {temporary: string, original: Buffer|null, mode: number}>} published
+ * @returns {string[]}
  */
 function rollbackWrites(published) {
+  /** @type {string[]} */
+  const unrestored = [];
   for (const plan of [...published].reverse()) {
     let restore = null;
     try {
@@ -225,12 +234,18 @@ function rollbackWrites(published) {
         fs.renameSync(restore, plan.path);
         restore = null;
       }
-    } catch {
-      // Best effort. A concurrent edit belongs to its writer, not this rollback.
+    } catch (error) {
+      // A created file that is already gone needs nothing. Any other failure
+      // leaves this call's bytes, or no bytes, where the original was.
+      const gone =
+        error instanceof Error &&
+        /** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT';
+      if (!(gone && plan.original == null)) unrestored.push(plan.path);
     } finally {
       if (restore != null) removeTemporary(restore);
     }
   }
+  return unrestored;
 }
 
 /** @param {string} file */
@@ -325,10 +340,22 @@ export function applyWrites(plans) {
       }
       published.push(plan);
     }
-    return () => rollbackWrites(published);
+    return () => {
+      rollbackWrites(published);
+    };
   } catch (error) {
-    for (const plan of staged) removeTemporary(plan.temporary);
-    rollbackWrites(published);
+    const leftovers = staged
+      .filter(plan => !removeTemporary(plan.temporary))
+      .map(plan => plan.temporary);
+    const unrestored = rollbackWrites(published);
+    if (error instanceof Error) {
+      if (unrestored.length > 0) {
+        error.message += ` Could not restore: ${unrestored.join(', ')}.`;
+      }
+      if (leftovers.length > 0) {
+        error.message += ` Could not remove temporary files: ${leftovers.join(', ')}.`;
+      }
+    }
     throw error;
   }
 }

package/api/integration/add-theme.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx integration add theme` — scaffold one valid source theme into
- * an integration package, update its theme catalog, and declare the root on
- * first use.
+ * @file `astryx integration add theme` — scaffold one strongly typed,
+ * same-stem source/descriptor pair into an integration package and declare the
+ * themes root on first use.
  */
 
 import * as fs from 'node:fs';
@@ -15,16 +15,14 @@ import {
   PathSafetyError,
   sanitizeName,
 } from '../../foundation/fs/path-safety.mjs';
-import {
-  discoverThemeCatalog,
-  THEME_MANIFEST_BASENAME,
-} from '../../foundation/discovery/theme-discovery.mjs';
+import {discoverThemeDirectory} from '../../foundation/discovery/theme-discovery.mjs';
 import {
   findLocalIntegrationManifestOrNull,
   IntegrationRootConflictError,
   patchIntegrationRoot,
 } from '../../foundation/integrations/manifest-writer.mjs';
 import {loadManifestObject} from '../../foundation/integrations/integrations.mjs';
+import {themeDescriptorSource} from '../../foundation/integrations/theme-descriptor.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
 import {
   applyWrites,
@@ -70,6 +68,7 @@ function themeIdentity(slug) {
     displayName,
     exportName: `${identifier}Theme`,
     entry: `${identifier}Theme.ts`,
+    descriptor: `${identifier}Theme.doc.mjs`,
   };
 }
 
@@ -78,9 +77,20 @@ function themeSource(identity) {
   return `import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const ${identity.exportName} = defineTheme({\n  name: '${identity.slug}',\n});\n`;
 }
 
+/** @param {{slug: string, displayName: string}} identity */
+function themeDescriptor(identity) {
+  return themeDescriptorSource({
+    type: 'theme',
+    name: identity.slug,
+    displayName: identity.displayName,
+    description: `${identity.displayName} theme.`,
+    maintained: true,
+  });
+}
+
 /**
- * Read the bytes back through the same integration-theme discovery seam Project
- * uses. A write is not successful until the requested slug resolves.
+ * Read bytes back through the same discovery seam Project uses. A write is not
+ * successful until the requested slug resolves.
  * @param {string} packageDir
  * @param {string} manifestFile
  * @param {string} owner
@@ -176,6 +186,9 @@ export async function integrationAddTheme(name, options = {}) {
       dryRun: true,
       createIfMissing: true,
     });
+    if (fs.existsSync(root)) {
+      discoverThemeDirectory(root, owner);
+    }
   } catch (error) {
     if (error instanceof IntegrationRootConflictError) {
       throw new AstryxError(
@@ -197,72 +210,29 @@ export async function integrationAddTheme(name, options = {}) {
   const sourceFile = assertWithin(identity.entry, themeDir, {
     label: 'theme source file',
   });
-  if (fs.existsSync(sourceFile)) {
-    throw new AstryxError(
-      `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, sourceFile))}.`,
-      undefined,
-      ERROR_CODES.ERR_FILE_EXISTS,
-    );
-  }
-
-  const catalogFile = assertWithin(THEME_MANIFEST_BASENAME, root, {
-    label: 'theme catalog manifest',
+  const descriptorFile = assertWithin(identity.descriptor, themeDir, {
+    label: 'theme descriptor file',
   });
-  /** @type {{version: 1, themes: Array<Record<string, unknown>>, [key: string]: unknown}} */
-  let catalog = {version: 1, themes: []};
-  /** @type {Buffer|null} */
-  let catalogOriginal = null;
-  if (fs.existsSync(catalogFile)) {
-    try {
-      catalogOriginal = fs.readFileSync(catalogFile);
-      catalog = JSON.parse(catalogOriginal.toString('utf-8'));
-      // The discovery seam is the schema/source-of-truth validator. The write
-      // plan carries catalogOriginal, so any concurrent change between this read
-      // and publish is refused rather than overwritten with this snapshot.
-      discoverThemeCatalog(root, owner);
-    } catch (error) {
+  // An existing folder is filled; only a file this would write is refused.
+  for (const file of [sourceFile, descriptorFile]) {
+    if (fs.existsSync(file)) {
       throw new AstryxError(
-        error instanceof Error ? error.message : String(error),
+        `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, file))}.`,
         undefined,
-        ERROR_CODES.ERR_THEME_INVALID,
+        ERROR_CODES.ERR_FILE_EXISTS,
       );
     }
   }
-  if (
-    catalog.themes.some(
-      theme =>
-        typeof theme.slug === 'string' &&
-        theme.slug.toLowerCase() === identity.slug.toLowerCase(),
-    )
-  ) {
-    throw new AstryxError(
-      `Theme "${identity.slug}" already exists in ${projectPath(path.relative(packageDir, catalogFile))}.`,
-      undefined,
-      ERROR_CODES.ERR_FILE_EXISTS,
-    );
-  }
-
-  catalog.themes.push({
-    slug: identity.slug,
-    displayName: identity.displayName,
-    description: `${identity.displayName} theme.`,
-    maintained: true,
-    entry: identity.entry,
-    exportName: identity.exportName,
-    files: [identity.entry],
-  });
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */
-  const plans = [];
-  plans.push(
+  const plans = [
     {path: sourceFile, contents: themeSource(identity), createOnly: true},
     {
-      path: catalogFile,
-      contents: `${JSON.stringify(catalog, null, 2)}\n`,
-      createOnly: catalogOriginal == null,
-      expectedOriginal: catalogOriginal ?? undefined,
+      path: descriptorFile,
+      contents: themeDescriptor(identity),
+      createOnly: true,
     },
-  );
+  ];
   const packageUpdate = packageJsonUpdate(
     packageFile,
     rootPath,