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

package/api/doctor/doctor.test.mjs

@@ -6,15 +6,23 @@
  * invariant (the counts must always add up to the number of checks).
  */
 
-import {describe, it, expect, afterEach} from 'vitest';
+import {describe, it, expect, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
+import {
+  AUTHORING_ROOT,
+  AUTHORING_SELF_DOCS,
+  auditAuthoringSelfDocs,
+} from '../../foundation/discovery/authoring-self-docs.mjs';
+import {docs} from '../docs/docs.mjs';
+import {auditCliSelfDocs} from '../../foundation/discovery/cli-self-docs.mjs';
 import {
   doctor,
   checkAuthoringDocs,
+  checkCliDocs,
   checkDocsProgressiveDisclosure,
   checkImplicitIntegrations,
   checkProviderIdentity,
@@ -444,6 +452,323 @@ describe('checkAuthoringDocs', () => {
   }, SLOW);
 });
 
+describe('checkCliDocs', () => {
+  const CLI_DOCS_FIX =
+    'Set `namespace` on each CLI doc to the one that reads it: cli/commands for a command, cli/api for an API function or the output schema, error codes, and response types, and authoring for a file an author writes (and list it in AUTHORING_SELF_DOCS).';
+
+  /** A doc tree under the working directory, as the CLI root. */
+  function writeRoot(/** @type {Record<string, any>} */ docsByPath) {
+    const root = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-cli-docs-'));
+    tmpDirs.push(root);
+    for (const [rel, doc] of Object.entries(docsByPath)) {
+      const file = path.join(root, rel);
+      fs.mkdirSync(path.dirname(file), {recursive: true});
+      fs.writeFileSync(file, `export const doc = ${JSON.stringify(doc)};\n`);
+    }
+    return root;
+  }
+
+  it(
+    'passes on this repo, counting where each CLI doc is read',
+    async () => {
+      const audit = await auditCliSelfDocs();
+      expect(await checkCliDocs()).toEqual({
+        id: 'cli-docs',
+        label: 'CLI docs',
+        status: 'pass',
+        message: `All ${audit.docs} CLI docs are readable: ${audit.sections} in \`astryx docs cli\` and ${audit.authoring} in \`astryx docs authoring\`.`,
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'fails on a doc with no namespace and one no topic reads, and names the fix',
+    async () => {
+      const root = writeRoot({
+        'api/alpha/alpha.doc.mjs': {
+          type: 'function',
+          kind: 'api',
+          name: 'alpha',
+          displayName: 'alpha()',
+          summary: 'The alpha function.',
+          params: [],
+          returns: [{type: 'alpha', description: 'The alpha.'}],
+        },
+        'clients/cli/commands/beta.doc.mjs': {
+          type: 'command',
+          name: 'beta',
+          displayName: 'astryx beta',
+          namespace: 'cli',
+          summary: 'Do beta',
+        },
+      });
+      expect(
+        await checkCliDocs(undefined, {root, authoringSources: []}),
+      ).toEqual({
+        id: 'cli-docs',
+        label: 'CLI docs',
+        status: 'fail',
+        message:
+          '2 problems: api/alpha/alpha.doc.mjs has no namespace, so no `astryx docs` topic reads it; clients/cli/commands/beta.doc.mjs has namespace "cli", which no `astryx docs` topic reads',
+        fix: CLI_DOCS_FIX,
+      });
+    },
+    SLOW,
+  );
+});
+
+describe('checkAuthoringDocs against the public authoring surface', () => {
+  const NAMESPACE = 'doctypes/namespace/namespace.doc.mjs';
+  const NAMESPACE_TYPES =
+    'NamespaceDoc, NamespaceProviderScope, NamespaceSlotAcceptance, NamespaceSlot, NamespaceAdoptionSource, NamespaceAdoptionRule from doctypes/namespace/type.ts have no doc in `astryx docs authoring`';
+  const SURFACE_FIX =
+    'Put a self-doc beside each module whose types @astryxdesign/cli/authoring exports and list it in AUTHORING_SELF_DOCS; export what each listed self-doc documents, or remove that self-doc.';
+
+  /** A copy of this repo's authoring tree, to break one piece of at a time. */
+  function copyAuthoring() {
+    const root = fs.mkdtempSync(
+      path.join(process.cwd(), '.astryx-doctor-authoring-'),
+    );
+    tmpDirs.push(root);
+    fs.cpSync(AUTHORING_ROOT, root, {
+      recursive: true,
+      filter: src => !src.endsWith('.test.mjs'),
+    });
+    return root;
+  }
+
+  /** @param {string} source */
+  const without = source => AUTHORING_SELF_DOCS.filter(s => s !== source);
+
+  /** @param {string} text */
+  const escape = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  it(
+    'passes on this repo and prints exactly what it printed before',
+    async () => {
+      expect(await checkAuthoringDocs()).toEqual({
+        id: 'authoring-docs',
+        label: 'Authoring docs',
+        status: 'pass',
+        message: `All ${AUTHORING_SELF_DOCS.length} authoring schemas are readable in \`astryx docs authoring\`.`,
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'passes on an unchanged copy of the tree, and writes nothing to it',
+    async () => {
+      const root = copyAuthoring();
+      const before = snapshot(root);
+      expect(await checkAuthoringDocs(undefined, {root})).toMatchObject({
+        status: 'pass',
+      });
+      expect(snapshot(root)).toEqual(before);
+    },
+    SLOW,
+  );
+
+  it(
+    'fails when the NamespaceDoc self-doc is left out of AUTHORING_SELF_DOCS',
+    async () => {
+      const root = copyAuthoring();
+      const c = await checkAuthoringDocs(undefined, {
+        root,
+        sources: without(NAMESPACE),
+      });
+      expect(c.status).toBe('fail');
+      expect(c.message).toBe(
+        `2 problems: ${NAMESPACE} is not in \`astryx docs authoring\`; ${NAMESPACE_TYPES}: ${NAMESPACE} is not listed in AUTHORING_SELF_DOCS`,
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    "fails when the topic's index no longer exposes the NamespaceDoc section",
+    async () => {
+      const index = await docs('authoring', undefined, {index: true});
+      const topicKeys = new Set(
+        index.data.sections
+          .map((/** @type {any} */ s) => s.id)
+          .filter((/** @type {string} */ id) => id !== 'namespace-doc'),
+      );
+      const c = await checkAuthoringDocs(undefined, {topicKeys});
+      expect(c).toMatchObject({
+        status: 'fail',
+        message: `${NAMESPACE_TYPES}: ${NAMESPACE} renders section "namespace-doc", which the topic's index does not list`,
+        fix: SURFACE_FIX,
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'fails when @astryxdesign/cli/authoring stops exporting NamespaceDoc',
+    async () => {
+      const root = copyAuthoring();
+      const index = path.join(root, 'index.d.ts');
+      const before = fs.readFileSync(index, 'utf8');
+      const after = before.replace(
+        /^export type \{NamespaceDoc\} from .*\n/m,
+        '',
+      );
+      expect(after).not.toBe(before);
+      fs.writeFileSync(index, after);
+      expect(await checkAuthoringDocs(undefined, {root})).toMatchObject({
+        status: 'fail',
+        message: `${NAMESPACE} documents NamespaceDoc, which @astryxdesign/cli/authoring does not export`,
+        fix: SURFACE_FIX,
+      });
+    },
+    SLOW,
+  );
+
+  it.each([
+    [
+      'the graph-fields doc',
+      'doctypes/base/graph-fields.doc.mjs',
+      'doctypes/base/type.ts',
+      [
+        'AuthoredDocKind',
+        'DocAudience',
+        'DocPlacement',
+        'AuthoredDocGraphFields',
+      ],
+    ],
+    [
+      'the identity doc',
+      'identity/identity.doc.mjs',
+      'identity/type.ts',
+      [
+        'ProviderId',
+        'ArtifactId',
+        'DocId',
+        'ProviderInstance',
+        'AuthoredDocEntry',
+      ],
+    ],
+    [
+      'the semantic-block doc',
+      'doctypes/reference/reference.doc.mjs',
+      'doctypes/reference/type.ts',
+      [
+        'WorkflowStep',
+        'WorkflowDocBlock',
+        'CollectionDocBlock',
+        'ReferenceDocBlock',
+      ],
+    ],
+  ])(
+    'fails when %s is removed, which the self-doc audit alone passes',
+    async (_what, source, module, names) => {
+      const root = copyAuthoring();
+      fs.rmSync(path.join(root, source));
+      const sources = without(source);
+      expect(await auditAuthoringSelfDocs({root, sources})).toEqual({
+        sections: sources.length,
+        unreachable: [],
+        failed: [],
+        oversized: [],
+      });
+      const c = await checkAuthoringDocs(undefined, {root, sources});
+      expect(c.status).toBe('fail');
+      expect(c.fix).toBe(SURFACE_FIX);
+      expect(c.message).toMatch(
+        new RegExp(
+          `^[A-Za-z, ]+ from ${escape(module)} have no doc in \`astryx docs authoring\`: no self-doc sits beside ${escape(module)}$`,
+        ),
+      );
+      for (const name of names) {
+        expect(c.message).toMatch(new RegExp(`(^|, )${name}(,| from)`));
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'keeps the message and fix of a failure only the self-doc audit reports',
+    async () => {
+      const root = copyAuthoring();
+      fs.writeFileSync(
+        path.join(root, 'identity', 'broken.doc.mjs'),
+        'export const doc = {;\n',
+      );
+      const c = await checkAuthoringDocs(undefined, {
+        root,
+        sources: [...AUTHORING_SELF_DOCS, 'identity/broken.doc.mjs'],
+      });
+      expect(c.status).toBe('fail');
+      expect(c.message).toMatch(/^identity\/broken\.doc\.mjs failed to load: /);
+      expect(c.fix).toBe(
+        'List every authoring self-doc in AUTHORING_SELF_DOCS, fix the one that fails to load, and split a section that is too large.',
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'reports a topic it cannot read rather than skipping the comparison',
+    async () => {
+      const spy = vi
+        .spyOn(DocsCatalog, 'fromBuiltins')
+        .mockImplementationOnce(() => {
+          throw new Error('no built-in docs');
+        });
+      try {
+        expect(await checkAuthoringDocs()).toMatchObject({
+          status: 'fail',
+          message:
+            '`astryx docs authoring` could not be read: no built-in docs',
+          fix: SURFACE_FIX,
+        });
+      } finally {
+        spy.mockRestore();
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'fails rather than passes when the surface exports no types at all',
+    async () => {
+      const root = copyAuthoring();
+      fs.writeFileSync(
+        path.join(root, 'index.d.ts'),
+        "export {parseDoc} from './doctypes/parse.mjs';\n",
+      );
+      const c = await checkAuthoringDocs(undefined, {root});
+      expect(c.status).toBe('fail');
+      expect(c.message).toContain(
+        '@astryxdesign/cli/authoring exports no types, so nothing was compared with `astryx docs authoring`',
+      );
+    },
+    SLOW,
+  );
+});
+
+/**
+ * Every file under `root` with its contents.
+ * @param {string} root
+ * @returns {Record<string, string>}
+ */
+function snapshot(root) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  /** @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 out[path.relative(root, full)] = fs.readFileSync(full, 'utf8');
+    }
+  };
+  walk(root);
+  return out;
+}
+
 describe('doctor docs checks', () => {
   it('runs both docs checks and they pass on the repo', async () => {
     const r = await doctor({cwd});

package/api/gap-report/gap-report.doc.mjs

@@ -10,6 +10,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'gapReport',
+  namespace: 'cli/api',
   displayName: 'gapReport()',
   summary: 'Route a design-system gap through the fan-out handler composition.',
   description:

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[]} */