@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/init/user/user.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file init.user leaf — the `--user` path behind `astryx init`.
+ *
+ * `user(options)` writes, refreshes, or (with `remove`) removes the
+ * computer-level agent text: one skill file in the home folder, linked into
+ * the skill folders agents read (spec AST-081 FR7, FR8). It records the
+ * setting and the links it made in the settings file, so the global copy,
+ * which keeps the text current in the background, does the same, or, after
+ * `remove`, writes nothing. The adapter does every file access. It works in any
+ * folder and never touches a project's agent docs. A file without the Astryx
+ * markers, one a person edited, or a symlinked one is kept as it is. When no
+ * `astryx` on the computer's search path runs the Astryx CLI, the text is
+ * still written and the receipt warns that the CLI should be installed for
+ * the computer.
+ *
+ * @input  `remove`; the home folder, search path, and settings of
+ *   the computer
+ * @output an `init.user` receipt
+ * @position packages/cli/api/init — dispatched by init.mjs
+ */
+
+import {
+  COMPUTER_COMMAND,
+  COMPUTER_INSTALL_STEP,
+  applyComputerAgentText,
+  displayHomePath,
+} from '../_adapter.mjs';
+import {logger} from '../../logger.mjs';
+
+/**
+ * @param {string} file
+ * @param {string} home
+ * @returns {string}
+ */
+const display = (file, home) => displayHomePath(file, home);
+
+/** @type {Record<import('../init.type.mjs').InitUserAction, string>} */
+const ACTION_LINES = {
+  written: '[ok] Wrote',
+  linked: '[ok] Linked',
+  unchanged: '[ok] Already current:',
+  removed: '[ok] Removed',
+  absent: '[ok] Nothing to remove:',
+  kept: '[skip] Kept',
+};
+
+/** @type {Record<'edited' | 'not-astryx', string>} */
+const KEPT_REASONS = {
+  edited: '(edited since Astryx wrote it; delete it to get the current text):',
+  'not-astryx': '(not created by Astryx):',
+};
+
+/**
+ * Write or remove the computer-level agent text and return an `init.user`
+ * receipt. Progress is emitted through the shared `logger` (silent by
+ * default); warnings go to its warn channel.
+ *
+ * @param {{remove?: boolean}} [options]
+ * @returns {Promise<import('../init.type.mjs').InitUserResponse>}
+ */
+export async function user({remove = false} = {}) {
+  const {home, command, files, cliOnSearchPath} = applyComputerAgentText({
+    remove,
+  });
+  /** @type {string[]} */
+  const warnings = [];
+  // A host's door is its own command; only the plain `astryx` needs a copy of
+  // the CLI installed for the computer.
+  if (!remove && command === COMPUTER_COMMAND && !cliOnSearchPath) {
+    warnings.push(
+      `No \`${COMPUTER_COMMAND}\` command on this computer runs the Astryx CLI, so agents cannot run the commands this text names. Install the CLI for the computer: ${COMPUTER_INSTALL_STEP}`,
+    );
+  }
+  for (const file of files) {
+    const reason = file.reason ? ` ${KEPT_REASONS[file.reason]}` : '';
+    logger.log(
+      `${ACTION_LINES[file.action]}${reason || (file.action === 'kept' ? ':' : '')} ${display(file.path, home)}`,
+    );
+  }
+  for (const warning of warnings) logger.warn(`[warn] ${warning}`);
+  return {
+    type: 'init.user',
+    data: {files, command, warnings},
+  };
+}

package/api/init/user/user.test.mjs

@@ -0,0 +1,232 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `init({user})` and `astryx init --user`: the `init.user` receipt, the
+ * install warning, the refused combinations, and that it touches nothing in
+ * the folder it runs in. Every test uses a temporary home folder and search
+ * path.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {init} from '../init.mjs';
+import {user} from './user.mjs';
+import {runWithCliDoor} from '../../../foundation/env/cli-command.mjs';
+import {renderComputerAgentText} from '../../../foundation/agent-docs/computer-agent-text.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {settingsFile} from '../../../foundation/env/user-settings.mjs';
+import {readGlobalState} from '../../../foundation/release/global-state.mjs';
+import {cliVersion} from '../../../foundation/release/run-context.mjs';
+
+/** @type {string[]} */
+const dirs = [];
+/** @param {string} label */
+function tmp(label) {
+  const dir = fs.mkdtempSync(
+    path.join(os.tmpdir(), `astryx-init-user-${label}-`),
+  );
+  dirs.push(dir);
+  return dir;
+}
+
+let home = '';
+let emptyPath = '';
+beforeEach(() => {
+  home = tmp('home');
+  emptyPath = tmp('path');
+  vi.stubEnv('HOME', home);
+  vi.stubEnv('USERPROFILE', home);
+  vi.stubEnv('PATH', emptyPath);
+  // The settings file and the cache live under this home folder too.
+  vi.stubEnv('XDG_CONFIG_HOME', path.join(home, '.config'));
+  vi.stubEnv('XDG_CACHE_HOME', path.join(home, '.cache'));
+  vi.stubEnv('APPDATA', path.join(home, 'AppData', 'Roaming'));
+  vi.stubEnv('LOCALAPPDATA', path.join(home, 'AppData', 'Local'));
+});
+
+/** The settings file under the temporary home folder. */
+const settings = () => {
+  try {
+    return JSON.parse(fs.readFileSync(settingsFile(), 'utf8'));
+  } catch {
+    return null;
+  }
+};
+afterEach(() => {
+  vi.unstubAllEnvs();
+  while (dirs.length) {
+    fs.rmSync(/** @type {string} */ (dirs.pop()), {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+const FILE = path.join('.agents', 'skills', 'astryx', 'SKILL.md');
+const CLAUDE = path.join('.claude', 'skills', 'astryx');
+
+/** Put a linked Astryx CLI first on the search path. */
+function installCliOnPath() {
+  const prefix = tmp('prefix');
+  const pkg = path.join(prefix, 'lib', 'node_modules', '@astryxdesign', 'cli');
+  fs.mkdirSync(pkg, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkg, 'package.json'),
+    '{"name":"@astryxdesign/cli"}',
+  );
+  fs.writeFileSync(path.join(pkg, 'bin.mjs'), '#!/usr/bin/env node\n');
+  fs.chmodSync(path.join(pkg, 'bin.mjs'), 0o755);
+  fs.mkdirSync(path.join(prefix, 'bin'));
+  fs.symlinkSync(path.join(pkg, 'bin.mjs'), path.join(prefix, 'bin', 'astryx'));
+  vi.stubEnv('PATH', path.join(prefix, 'bin'));
+}
+
+describe('init({user: true})', () => {
+  it('writes the file, links Claude Code to it, and returns the init.user receipt, warning when no astryx runs the CLI', async () => {
+    const r = await init({user: true}, {cwd: tmp('cwd')});
+    expect(r.type).toBe('init.user');
+    if (r.type !== 'init.user') return;
+    expect(r.data.files).toEqual([
+      {path: path.join(home, FILE), action: 'written'},
+      {path: path.join(home, CLAUDE), action: 'linked'},
+    ]);
+    expect(r.data.command).toBe('astryx');
+    expect(r.data.warnings).toHaveLength(1);
+    expect(r.data.warnings[0]).toContain('npm i -g @astryxdesign/cli');
+    expect(fs.readFileSync(path.join(home, FILE), 'utf8')).toBe(
+      renderComputerAgentText({command: 'astryx'}),
+    );
+    expect(fs.readFileSync(path.join(home, CLAUDE, 'SKILL.md'), 'utf8')).toBe(
+      renderComputerAgentText({command: 'astryx'}),
+    );
+  });
+
+  it.skipIf(process.platform === 'win32')(
+    'does not warn when the astryx on the search path is the Astryx CLI',
+    async () => {
+      installCliOnPath();
+      const r = await user();
+      expect(r.data.warnings).toEqual([]);
+    },
+  );
+
+  it("names the host's door and does not ask for a global install", async () => {
+    const r = await runWithCliDoor('acme astryx', () => user());
+    expect(r.data.command).toBe('acme astryx');
+    expect(r.data.warnings).toEqual([]);
+    expect(fs.readFileSync(path.join(home, FILE), 'utf8')).toContain(
+      "`acme astryx search '<what you need>'`",
+    );
+  });
+
+  it('works inside a project and writes nothing in it', async () => {
+    const dir = tmp('project');
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}',
+    );
+    const before = fs.readdirSync(dir).sort();
+    const r = await init({user: true}, {cwd: dir});
+    expect(r.type).toBe('init.user');
+    expect(fs.readdirSync(dir).sort()).toEqual(before);
+  });
+
+  it('records the links it made, and the release that wrote the text', async () => {
+    await init({user: true});
+    expect(settings()).toEqual({
+      computerAgentText: {install: true, links: [path.join(home, CLAUDE)]},
+    });
+    expect(readGlobalState().agentText).toEqual({writtenBy: cliVersion()});
+  });
+
+  it('keeps every other setting when it records the choice', async () => {
+    fs.mkdirSync(path.dirname(settingsFile()), {recursive: true});
+    fs.writeFileSync(settingsFile(), '{"other": 1}');
+    await init({user: true, removeAgents: true});
+    expect(settings()).toEqual({
+      other: 1,
+      computerAgentText: {install: false, links: []},
+    });
+  });
+
+  it('with removeAgents removes the file and the links it made, and records that the text is not wanted', async () => {
+    await init({user: true});
+    const r = await init({user: true, removeAgents: true});
+    expect(r.type).toBe('init.user');
+    if (r.type !== 'init.user') return;
+    expect(r.data.files).toEqual([
+      {path: path.join(home, FILE), action: 'removed'},
+      {path: path.join(home, CLAUDE), action: 'removed'},
+    ]);
+    expect(r.data.warnings).toEqual([]);
+    expect(fs.existsSync(path.join(home, FILE))).toBe(false);
+    expect(fs.existsSync(path.join(home, CLAUDE))).toBe(false);
+    expect(settings()).toEqual({
+      computerAgentText: {install: false, links: []},
+    });
+  });
+
+  it.each([
+    [{features: 'agents'}, '--features'],
+    [{all: true}, '--all'],
+    [{agentDocsPath: 'X.md'}, '--agent-docs-path'],
+    [{agent: 'claude'}, '--agent'],
+    [{removeAgents: true, agent: 'claude'}, '--agent'],
+  ])(
+    'refuses %o with ERR_INVALID_ARGUMENT and writes nothing',
+    async (extra, flag) => {
+      await expect(init({user: true, ...extra})).rejects.toMatchObject({
+        code: 'ERR_INVALID_ARGUMENT',
+        message: expect.stringContaining(flag),
+      });
+      expect(fs.existsSync(path.join(home, '.agents'))).toBe(false);
+      expect(fs.existsSync(path.join(home, '.claude'))).toBe(false);
+    },
+  );
+});
+
+describe('astryx init --user', () => {
+  it('prints the file, the link, and the install warning in text mode', async () => {
+    const r = await runCli(['init', '--user'], tmp('cwd'));
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain(`Wrote ~${path.sep}${FILE}`);
+    expect(r.stdout).toContain(`Linked ~${path.sep}${CLAUDE}`);
+    expect(r.stderr).toContain('npm i -g @astryxdesign/cli');
+  });
+
+  it('emits the init.user envelope under --json', async () => {
+    const r = await runCli(['--json', 'init', '--user'], tmp('cwd'));
+    expect(r.status).toBe(0);
+    const env = JSON.parse(r.stdout);
+    expect(env.type).toBe('init.user');
+    expect(
+      env.data.files.map((/** @type {{action: string}} */ f) => f.action),
+    ).toEqual(['written', 'linked']);
+    expect(env.data.command).toBe('astryx');
+  });
+
+  it('names a file a person edited as kept, and why', async () => {
+    await runCli(['init', '--user'], tmp('cwd'));
+    const file = path.join(home, FILE);
+    fs.appendFileSync(file, 'my note\n');
+    const r = await runCli(['init', '--user'], tmp('cwd'));
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain(
+      `Kept (edited since Astryx wrote it; delete it to get the current text): ~${path.sep}${FILE}`,
+    );
+    expect(fs.readFileSync(file, 'utf8')).toMatch(/my note\n$/u);
+  });
+
+  it('exits 1 with ERR_INVALID_ARGUMENT when combined with --all or --agent', async () => {
+    for (const extra of [['--all'], ['--agent', 'claude']]) {
+      const r = await runCli(
+        ['--json', 'init', '--user', ...extra],
+        tmp('cwd'),
+      );
+      expect(r.status).toBe(1);
+      expect(JSON.parse(r.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+    }
+  });
+});

package/api/integration/_adapter.d.mts

@@ -0,0 +1,45 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Each component doc's props compared with the component's TypeScript props,
+ * read with the project's own compiler (spec:AST-039 FR12). Without one, the
+ * report says the comparison was skipped.
+ * @param {any} integration a loaded integration
+ * @param {string} cwd
+ * @returns {Promise<import('../../foundation/discovery/prop-drift.mjs').PropDriftReport>}
+ */
+export function integrationPropDrift(integration: any, cwd: string): Promise<import("../../foundation/discovery/prop-drift.mjs").PropDriftReport>;
+/**
+ * The passages two of a package's topics, or one of them and a Core topic,
+ * repeat word for word (architecture:cli-surface DEC-8). Reads the package's
+ * topics and Core's guides.
+ *
+ * @param {Parameters<typeof findCopiedPassages>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ */
+export function integrationCopiedPassages(discovered: Parameters<typeof findCopiedPassages>[0]): Promise<import("./authoring-checks.type.mjs").CopiedPassage[]>;
+/**
+ * Padding phrases and low-density topics in a package's prose
+ * (architecture:cli-surface DEC-8). Reads the package's topics, and Core's
+ * guides for the density median a finding names.
+ *
+ * @param {Parameters<typeof findFluff>[0]} discovered the package's docs, as
+ *   discoverIntegrationDocs returns them
+ */
+export function integrationFluff(discovered: Parameters<typeof findFluff>[0]): Promise<import("./authoring-checks.type.mjs").DocFluff[]>;
+/**
+ * Code spans in a package's prose that write `astryx docs <name>` for a doc
+ * that exists, where `{@link generic:<name>}` would be checked
+ * (architecture:cli-surface DEC-8). Reads the package's topics, its own
+ * component docs, and the names of Core's docs.
+ *
+ * @param {Parameters<typeof findStrayPointers>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ * @param {any} [integration] the loaded integration, whose component docs are
+ *   read too
+ */
+export function integrationStrayPointers(discovered: Parameters<typeof findStrayPointers>[0], integration?: any): Promise<import("./authoring-checks.type.mjs").StrayPointer[]>;
+import { findCopiedPassages } from '../../foundation/discovery/copied-passages.mjs';
+import { findFluff } from '../../foundation/discovery/doc-fluff.mjs';
+import { findStrayPointers } from '../../foundation/discovery/stray-pointers.mjs';

package/api/integration/_adapter.mjs

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The integration subject's access to the environment (INV21): reading
+ * one package's component docs and sources with the project's own TypeScript.
+ *
+ * @input a loaded integration and the directory the command runs in
+ * @output the reports the integration checks attach to their results
+ * @position api/integration (internal; not exported from ./api)
+ */
+
+import {
+  discoverValidIntegrationComponents,
+  forEachIntegrationDoc,
+  integrationSourceForDoc,
+} from '../../foundation/discovery/component-discovery.mjs';
+import {comparePropDocs} from '../../foundation/discovery/prop-drift.mjs';
+import {findCopiedPassages} from '../../foundation/discovery/copied-passages.mjs';
+import {findFluff} from '../../foundation/discovery/doc-fluff.mjs';
+import {findStrayPointers} from '../../foundation/discovery/stray-pointers.mjs';
+
+/**
+ * Each component doc's props compared with the component's TypeScript props,
+ * read with the project's own compiler (spec:AST-039 FR12). Without one, the
+ * report says the comparison was skipped.
+ * @param {any} integration a loaded integration
+ * @param {string} cwd
+ * @returns {Promise<import('../../foundation/discovery/prop-drift.mjs').PropDriftReport>}
+ */
+export async function integrationPropDrift(integration, cwd) {
+  const packageDir = /** @type {{__packageDir?: string}} */ (integration)
+    .__packageDir;
+  const {components} = await discoverValidIntegrationComponents(integration);
+  // Every doc the package ships has its prop tables compared or listed as not
+  // compared. A doc discovery leaves out (a hidden one, a second doc for one
+  // name, or one whose source or own file doesn't load) gets a record under
+  // its file name.
+  const recorded = new Set(components.map(c => c.docPath));
+  /** @type {typeof components} */
+  const left = [];
+  forEachIntegrationDoc(integration?.components, (docPath, stem) => {
+    if (recorded.has(docPath)) return;
+    recorded.add(docPath);
+    left.push({
+      name: stem,
+      package: integration.name,
+      docPath,
+      sourcePath: integrationSourceForDoc(docPath),
+      issuesUrl: integration.issuesUrl,
+      group: null,
+    });
+  });
+  return comparePropDocs([...components, ...left], {
+    packageDir: packageDir ?? cwd,
+    resolveFrom: [cwd, packageDir],
+  });
+}
+
+/**
+ * The passages two of a package's topics, or one of them and a Core topic,
+ * repeat word for word (architecture:cli-surface DEC-8). Reads the package's
+ * topics and Core's guides.
+ *
+ * @param {Parameters<typeof findCopiedPassages>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ */
+export function integrationCopiedPassages(discovered) {
+  return findCopiedPassages(discovered);
+}
+
+/**
+ * Padding phrases and low-density topics in a package's prose
+ * (architecture:cli-surface DEC-8). Reads the package's topics, and Core's
+ * guides for the density median a finding names.
+ *
+ * @param {Parameters<typeof findFluff>[0]} discovered the package's docs, as
+ *   discoverIntegrationDocs returns them
+ */
+export function integrationFluff(discovered) {
+  return findFluff(discovered);
+}
+
+/**
+ * Code spans in a package's prose that write `astryx docs <name>` for a doc
+ * that exists, where `{@link generic:<name>}` would be checked
+ * (architecture:cli-surface DEC-8). Reads the package's topics, its own
+ * component docs, and the names of Core's docs.
+ *
+ * @param {Parameters<typeof findStrayPointers>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ * @param {any} [integration] the loaded integration, whose component docs are
+ *   read too
+ */
+export async function integrationStrayPointers(discovered, integration) {
+  /** @type {{name: string, file: string}[]} */
+  const components = [];
+  if (integration?.components) {
+    const seen = new Set();
+    try {
+      const {components: records} =
+        await discoverValidIntegrationComponents(integration);
+      for (const record of records) {
+        if (!record.docPath || seen.has(record.docPath)) continue;
+        seen.add(record.docPath);
+        components.push({name: record.name, file: record.docPath});
+      }
+    } catch {
+      // `validate` reports component docs that do not load.
+    }
+  }
+  return findStrayPointers({...discovered, components});
+}

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

@@ -98,6 +98,72 @@ describe('integrationAddComponent name collisions', () => {
     expect(snapshot()).toEqual(before);
   });
 
+  it('adds a name a family doc lists but the module it imports does not export', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist'], exports: {'./tabs': './components/tabs/index.ts'}}, null, 2)}\n`,
+    );
+    const tabs = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(tabs, {recursive: true});
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabExtra', description: 'x'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTabExtra() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'index.ts'),
+      "export {AcmeTabs} from './AcmeTabs';\n",
+    );
+
+    const result = await integrationAdd('component', 'AcmeTabExtra', {
+      cwd: tmpDir,
+      dryRun: true,
+    });
+    expect(result.data.files).toContain('components/AcmeTabExtra.doc.mjs');
+  });
+
+  it('refuses a member a family exports through built output', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist'], exports: {'./tabs': './dist/tabs/index.js'}}, null, 2)}\n`,
+    );
+    const tabs = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(tabs, {recursive: true});
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTab', description: 'x'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTab.tsx'),
+      'export function AcmeTab() { return null; }\n',
+    );
+    const dist = path.join(tmpDir, 'dist', 'tabs');
+    fs.mkdirSync(dist, {recursive: true});
+    fs.writeFileSync(
+      path.join(dist, 'index.js'),
+      "export {AcmeTabs} from './tabs.js';\nexport {AcmeTab} from './tab.js';\n",
+    );
+    fs.writeFileSync(
+      path.join(dist, 'tabs.js'),
+      'export function AcmeTabs() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(dist, 'tab.js'),
+      'export function AcmeTab() { return null; }\n',
+    );
+
+    await expect(
+      integrationAdd('component', 'AcmeTab', {cwd: tmpDir, dryRun: true}),
+    ).rejects.toThrow('Refusing to add component "AcmeTab"');
+  });
+
   it('still adds a component whose name is free', async () => {
     writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
 

package/api/integration/add-contribution.mjs

@@ -264,9 +264,13 @@ async function addComponent(name, options) {
       ERROR_CODES.ERR_FILE_EXISTS,
     );
   }
-  // Discovery keys components by doc stem anywhere under the root, so a second
-  // doc with this name would shadow one of the two.
-  const existingDoc = findIntegrationComponentDoc({components: root}, name);
+  // A second doc under a name discovery already records, by a doc's file name
+  // anywhere under the root or by a name a doc documents, would shadow one of
+  // the two.
+  const existingDoc = findIntegrationComponentDoc(
+    {name: owner, components: root, __packageDir: packageDir},
+    name,
+  );
   if (existingDoc != null) {
     throw new AstryxError(
       `Refusing to add component "${name}": ${projectPath(path.relative(packageDir, existingDoc))} already defines it.`,
@@ -691,7 +695,7 @@ async function addTemplate(name, options) {
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
   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 specContents = `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */\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

@@ -536,7 +536,9 @@ describe('integrationAdd template', () => {
       path.join(tmpDir, 'templates/my-widget.doc.mjs'),
       'utf-8',
     );
-    expect(spec).toContain("@astryxdesign/cli/authoring').TemplateDoc");
+    expect(spec).toContain(
+      "@astryxdesign/cli/authoring').IntegrationTemplateDoc",
+    );
     expect(spec).toContain("type: 'page'");
     expect(spec).toContain("name: 'my-widget'");
 
@@ -830,7 +832,7 @@ describe('typed descriptor conformance', () => {
     for (const [relativePath, type] of [
       ['components/MyWidget.doc.mjs', 'ComponentDoc'],
       ['docs/my-guide.doc.mjs', 'ReferenceDoc'],
-      ['templates/my-page.doc.mjs', 'TemplateDoc'],
+      ['templates/my-page.doc.mjs', 'IntegrationTemplateDoc'],
       ['themes/ocean/oceanTheme.doc.mjs', 'ThemeDoc'],
     ]) {
       const source = fs.readFileSync(path.join(tmpDir, relativePath), 'utf-8');