@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

package/api/hook/_adapter.mjs

@@ -15,7 +15,10 @@
  */
 
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
-import {findHookDoc, getAllHookNames} from '../../foundation/discovery/hook-discovery.mjs';
+import {
+  findHookDoc,
+  getAllHookNames,
+} from '../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../foundation/discovery/component-loader.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../error.mjs';
@@ -30,7 +33,11 @@ import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 export function resolveCoreDir(cwd) {
   const coreDir = findCoreDir(cwd);
   if (!coreDir) {
-    throw new AstryxError('Could not find @astryxdesign/core package', undefined, ERROR_CODES.ERR_CORE_NOT_FOUND);
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
   }
   return coreDir;
 }
@@ -44,7 +51,11 @@ export function resolveCoreDir(cwd) {
  * @param {{zh?: boolean, lang?: string|null}} [opts]
  * @returns {Promise<import('./hook.type.mjs').HookDoc>}
  */
-export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} = {}) {
+export async function resolveHookDoc(
+  coreDir,
+  name,
+  {zh = false, lang = null} = {},
+) {
   const docPath = findHookDoc(coreDir, name);
 
   if (!docPath) {
@@ -59,7 +70,10 @@ export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} =
       .filter(m => m.distance <= 5)
       .sort((a, b) => a.distance - b.distance)
       .slice(0, 5)
-      .map(m => ({name: m.name, reason: `similar name (distance ${m.distance})`}));
+      .map(m => ({
+        name: m.name,
+        reason: `similar name (distance ${m.distance})`,
+      }));
 
     throw new AstryxError(
       `No hook named "${name}"`,
@@ -68,5 +82,5 @@ export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} =
     );
   }
 
-  return loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
+  return loadDocs(docPath, {zh, lang, root: 'hooks'});
 }

package/api/hook/hook.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'hook',
+  namespace: 'cli/api',
   displayName: 'hook()',
   summary:
     'Resolve a hook by name, or list the catalog, with an optional params-only slice.',

package/api/hook/list/list.d.mts

@@ -10,7 +10,7 @@
  * @param {string|null} [options.lang]
  * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
  */
-export function list({ cwd, category, detail, zh, lang }?: {
+export function list({ cwd, category, detail, zh, lang, }?: {
     cwd?: string | undefined;
     category?: string | undefined;
     detail?: "compact" | "full" | "names" | "brief" | undefined;

package/api/hook/list/list.mjs

@@ -13,7 +13,10 @@
  * @position api/hook/list/list.mjs — dispatched from ../hook.mjs
  */
 
-import {discoverHooks, findHookDoc} from '../../../foundation/discovery/hook-discovery.mjs';
+import {
+  discoverHooks,
+  findHookDoc,
+} from '../../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
@@ -28,7 +31,13 @@ import {resolveCoreDir} from '../_adapter.mjs';
  * @param {string|null} [options.lang]
  * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
  */
-export async function list({cwd = process.cwd(), category, detail = 'names', zh = false, lang = null} = {}) {
+export async function list({
+  cwd = process.cwd(),
+  category,
+  detail = 'names',
+  zh = false,
+  lang = null,
+} = {}) {
   const coreDir = resolveCoreDir(cwd);
   const hooks = discoverHooks(coreDir);
 
@@ -51,20 +60,31 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
+            const docs = await loadDocs(docPath, {zh, lang, root: 'hooks'});
             entries.push({
               name: hookName,
               description: docs.usage?.description || '',
               import: docs.importPath || '@astryxdesign/core/hooks',
             });
           } catch {
-            entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+            entries.push({
+              name: hookName,
+              description: '',
+              import: '@astryxdesign/core/hooks',
+            });
           }
         } else {
-          entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+          entries.push({
+            name: hookName,
+            description: '',
+            import: '@astryxdesign/core/hooks',
+          });
         }
       }
-      return {type: 'hook.list', data: {detail: 'compact', components: {[match[0]]: entries}}};
+      return {
+        type: 'hook.list',
+        data: {detail: 'compact', components: {[match[0]]: entries}},
+      };
     }
 
     if (detail === 'full') {
@@ -74,19 +94,33 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            entries.push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
+            entries.push(await loadDocs(docPath, {zh, lang, root: 'hooks'}));
           } catch {
-            entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+            entries.push(
+              /** @type {import('../hook.type.mjs').HookDoc} */ ({
+                name: hookName,
+              }),
+            );
           }
         } else {
-          entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+          entries.push(
+            /** @type {import('../hook.type.mjs').HookDoc} */ ({
+              name: hookName,
+            }),
+          );
         }
       }
-      return {type: 'hook.list', data: {detail: 'full', components: {[match[0]]: entries}}};
+      return {
+        type: 'hook.list',
+        data: {detail: 'full', components: {[match[0]]: entries}},
+      };
     }
 
     // Default: names only
-    return {type: 'hook.list', data: {detail: 'names', components: {[match[0]]: match[1]}}};
+    return {
+      type: 'hook.list',
+      data: {detail: 'names', components: {[match[0]]: match[1]}},
+    };
   }
 
   // All hooks
@@ -99,17 +133,25 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
+            const docs = await loadDocs(docPath, {zh, lang, root: 'hooks'});
             result[cat].push({
               name: hookName,
               description: docs.usage?.description || '',
               import: docs.importPath || '@astryxdesign/core/hooks',
             });
           } catch {
-            result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+            result[cat].push({
+              name: hookName,
+              description: '',
+              import: '@astryxdesign/core/hooks',
+            });
           }
         } else {
-          result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+          result[cat].push({
+            name: hookName,
+            description: '',
+            import: '@astryxdesign/core/hooks',
+          });
         }
       }
     }
@@ -125,12 +167,22 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            result[cat].push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
+            result[cat].push(
+              await loadDocs(docPath, {zh, lang, root: 'hooks'}),
+            );
           } catch {
-            result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+            result[cat].push(
+              /** @type {import('../hook.type.mjs').HookDoc} */ ({
+                name: hookName,
+              }),
+            );
           }
         } else {
-          result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+          result[cat].push(
+            /** @type {import('../hook.type.mjs').HookDoc} */ ({
+              name: hookName,
+            }),
+          );
         }
       }
     }

package/api/init/init.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'init',
+  namespace: 'cli/api',
   displayName: 'init()',
   summary:
     'Non-interactive project setup: install agent docs and point at the theme + build workflows.',

package/api/integration/add-contribution.mjs

@@ -5,8 +5,7 @@
  * contribution into an integration package.
  *
  * Dispatches component, doc, template, codemod, and agent-doc. Theme
- * delegates to the existing `integrationAddTheme` (not modified here).
- * Every root-based kind shares: first add creates the manifest; one shared
+ * delegates to the dedicated same-stem descriptor writer. Every root-based kind shares: first add creates the manifest; one shared
  * writer; never creates `files`/`exports`; atomic staged writes; no clobber;
  * dry-run receipt predicts real run; post-write verify through the real
  * discovery/parser seam.
@@ -263,7 +262,7 @@ async function addComponent(name, options) {
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
   const importSpecifier = `${owner}/${extensionlessPath}`;
-  const docContents = `export default {\n  type: 'component',\n  name: '${name}',\n  import: ${JSON.stringify(importSpecifier)},\n  description: '${name} component.',\n  props: [],\n};\n`;
+  const docContents = `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */\nexport default {\n  type: 'component',\n  name: '${name}',\n  displayName: '${name}',\n  import: ${JSON.stringify(importSpecifier)},\n  usage: {description: '${name} component.'},\n  props: [],\n};\n`;
   const sourceContents = `export function ${name}() {\n  return <div>${name}</div>;\n}\n`;
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */
@@ -438,7 +437,7 @@ async function addDoc(name, options) {
     : options.extends
       ? `\n  extends: '${options.extends}',`
       : '';
-  const docContents = `export default {\n  type: 'generic',\n  name: '${name}',\n  title: '${title}',\n  description: '${title} documentation.',${relationship}\n  sections: [\n    {\n      title: 'Overview',\n      content: [\n        { type: 'prose', text: '${title} documentation.' },\n      ],\n    },\n  ],\n};\n`;
+  const docContents = `/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n  type: 'generic',\n  name: '${name}',\n  title: '${title}',\n  description: '${title} documentation.',${relationship}\n  sections: [\n    {\n      title: 'Overview',\n      content: [\n        { type: 'prose', text: '${title} documentation.' },\n      ],\n    },\n  ],\n};\n`;
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */
   const plans = [{path: docFile, contents: docContents, createOnly: true}];
@@ -565,8 +564,8 @@ async function addTemplate(name, options) {
     throw error;
   }
 
-  const specFile = assertWithin(`${name}.template.mjs`, root, {
-    label: 'template spec',
+  const specFile = assertWithin(`${name}.doc.mjs`, root, {
+    label: 'template descriptor',
   });
   const sourceFile = assertWithin(`${name}.tsx`, root, {
     label: 'template source',
@@ -589,7 +588,8 @@ async function addTemplate(name, options) {
   const pascalName = kebabToPascal(name);
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
-  const specContents = `export default {\n  type: '${templateType}',\n  name: '${name}',\n  description: '${kebabToTitle(name)} template.',\n};\n`;
+  const blockFields = templateType === 'block' ? '\n  aspectRatio: 1,' : '';
+  const specContents = `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n  type: '${templateType}',\n  name: '${name}',\n  displayName: '${kebabToTitle(name)}',\n  description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;
   const sourceContents = `export default function ${pascalName}() {\n  return <div>${kebabToTitle(name)}</div>;\n}\n`;
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */

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

@@ -77,6 +77,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: []');
@@ -304,6 +305,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'");
 
@@ -390,13 +392,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'");
 
@@ -432,10 +435,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 +680,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 +744,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 () => {

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,