@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9dbb6c1

package/api/integration/integrationAddComponent.doc.mjs

@@ -5,10 +5,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddComponent',
+  namespace: 'cli/api',
   displayName: 'integrationAddComponent()',
   summary: 'Add a complete component contribution.',
   description:
-    'Creates the same-stem component source and metadata pair, declares the components root on first use, preserves existing package allowlists, and publishes an exact source subpath when the package already has an exports map.',
+    'Creates the same-stem component source and metadata pair, declares the components root on first use, preserves existing package allowlists, and publishes an exact source subpath when the package already has an exports map. Refuses with ERR_FILE_EXISTS when a component doc anywhere under the components root already uses the name.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationAddComponent(name: string, options?: IntegrationAddComponentOptions): Promise<IntegrationAddResponse>',

package/api/integration/integrationAddDoc.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddDoc',
+  namespace: 'cli/api',
   displayName: 'integrationAddDoc()',
   summary: 'Add a complete reference-doc contribution.',
   description:

package/api/integration/integrationAddTemplate.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddTemplate',
+  namespace: 'cli/api',
   displayName: 'integrationAddTemplate()',
   summary: 'Add a complete page or block template contribution.',
   description:

package/api/integration/integrationAddTheme.doc.mjs

@@ -5,10 +5,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddTheme',
+  namespace: 'cli/api',
   displayName: 'integrationAddTheme()',
   summary: 'Add a source theme to an integration package.',
   description:
-    'Creates an integration manifest when the package has none, writes a minimal named-export defineTheme source file, adds its entry to the root theme catalog, declares the optional themes root on first use, and includes the manifest and root in package.json files when the package already uses an allowlist. Every path is confined to the package and existing theme files are never overwritten.',
+    'Creates an integration manifest when the package has none, writes a minimal named-export defineTheme source file plus its strongly typed same-stem ThemeDoc, declares the optional themes root on first use, and includes the manifest and root in package.json files when the package already uses an allowlist. Every path is confined to the package and existing theme directories are never overwritten.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationAddTheme(name: string, options?: IntegrationAddThemeOptions): Promise<IntegrationAddResponse>',
@@ -17,7 +18,7 @@ export const doc = {
     {
       name: 'name',
       type: 'string',
-      description: 'Lowercase kebab-case theme name and catalog slug.',
+      description: 'Lowercase kebab-case theme name and directory slug.',
       required: true,
     },
     {
@@ -51,7 +52,7 @@ export const doc = {
     },
     {
       code: 'ERR_FILE_EXISTS',
-      when: 'the theme slug or source file already exists',
+      when: 'the theme slug directory already exists',
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
@@ -63,7 +64,7 @@ export const doc = {
     },
     {
       code: 'ERR_THEME_INVALID',
-      when: 'the package, integration manifest, or theme catalog is invalid',
+      when: 'the package, integration manifest, or theme descriptor is invalid',
     },
     {
       code: 'ERR_WRITE_FAILED',
@@ -80,6 +81,6 @@ export const doc = {
       code: "await integrationAddTheme('ocean', {dryRun: true});",
     },
   ],
-  command: 'integration add',
+  command: 'integration add theme',
   related: ['themeList', 'themeAdd', 'validateIntegration'],
 };

package/api/integration/integrationComponentConflicts.doc.mjs

@@ -7,6 +7,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationComponentConflicts',
+  namespace: 'cli/api',
   displayName: 'integrationComponentConflicts()',
   summary: 'Find integration component names that also exist in Core.',
   description:

package/api/integration/integrationDocConflicts.doc.mjs

@@ -7,6 +7,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationDocConflicts',
+  namespace: 'cli/api',
   displayName: 'integrationDocConflicts()',
   summary: 'Classify integration doc overlaps with Core topics.',
   description:

package/api/integration/integrationPackCheck.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationPackCheck',
+  namespace: 'cli/api',
   displayName: 'integrationPackCheck()',
   summary: 'Prove an integration package survives npm packing.',
   description:

package/api/integration/integrationTemplateConflicts.doc.mjs

@@ -9,6 +9,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationTemplateConflicts',
+  namespace: 'cli/api',
   displayName: 'integrationTemplateConflicts()',
   summary: 'Find integration template ids that also exist in Core.',
   description:

package/api/integration/pack-check.mjs

@@ -388,6 +388,14 @@ async function validatePackedComponentExports(integration, scratchBase) {
     components.map(component => component.specifier),
     scratchBase,
   );
+  issues.push(
+    ...validateSpecifierExtensions(
+      components.map(({name, specifier}) => ({
+        label: `Component "${name}"`,
+        specifier,
+      })),
+    ),
+  );
   for (const {name, specifier} of components) {
     const result = resolved.get(specifier);
     if (!result?.url || result.error) {
@@ -427,19 +435,27 @@ async function validatePackedComponentExports(integration, scratchBase) {
  */
 async function validatePackedTemplateExports(integration, scratchBase) {
   const {templates} = await discoverIntegrationTemplatesForOne(integration);
-  const entries = templates.map(template => ({
-    id: template.dirName,
-    specifier: `${integration.name}/${path
+  const entries = templates.map(template => {
+    const relPath = path
       .relative(integration.__packageDir, template.filePath)
       .split(path.sep)
-      .join('/')}`,
-  }));
+      .join('/');
+    const extensionless = relPath.replace(/\.tsx?$/u, '');
+    return {
+      id: template.dirName,
+      specifier: `${integration.name}/${extensionless}`,
+    };
+  });
   const resolved = resolveConsumerSpecifiers(
     entries.map(entry => entry.specifier),
     scratchBase,
   );
-  /** @type {Issue[]} */
-  const issues = [];
+  const issues = validateSpecifierExtensions(
+    entries.map(({id, specifier}) => ({
+      label: `Template "${id}"`,
+      specifier,
+    })),
+  );
   for (const {id, specifier} of entries) {
     const result = resolved.get(specifier);
     if (!result?.url || result.error) {
@@ -469,6 +485,32 @@ async function validatePackedTemplateExports(integration, scratchBase) {
   return issues;
 }
 
+const TS_EXTENSION_RE = /\.tsx?$/u;
+
+/**
+ * Reject specifiers that end in a TypeScript extension — they fail under
+ * default `moduleResolution` with TS5097/TS2307 unless the consumer enables
+ * `allowImportingTsExtensions`.
+ *
+ * @param {Array<{label: string, specifier: string}>} entries
+ * @returns {Issue[]}
+ */
+function validateSpecifierExtensions(entries) {
+  /** @type {Issue[]} */
+  const issues = [];
+  for (const {label, specifier} of entries) {
+    if (TS_EXTENSION_RE.test(specifier)) {
+      issues.push(
+        error(
+          'typescript_extension_in_specifier',
+          `${label} advertises import "${specifier}", which ends in a TypeScript extension. A consumer with default moduleResolution will reject it (TS5097). Use an extensionless specifier mapped through the package exports.`,
+        ),
+      );
+    }
+  }
+  return issues;
+}
+
 /**
  * Verify an integration package is ready to publish.
  *

package/api/integration/pack-check.test.mjs

@@ -53,25 +53,10 @@ function writePackage({
       "import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const oceanTheme = defineTheme({name: 'ocean'});\n",
     );
     fs.writeFileSync(
-      path.join(root, 'manifest.json'),
-      JSON.stringify(
-        {
-          version: 1,
-          themes: [
-            {
-              slug: 'ocean',
-              displayName: 'Ocean',
-              description: 'Ocean theme.',
-              maintained: true,
-              entry: 'oceanTheme.ts',
-              exportName: 'oceanTheme',
-              files: ['oceanTheme.ts'],
-            },
-          ],
-        },
-        null,
-        2,
-      ) + '\n',
+      path.join(root, 'ocean', 'oceanTheme.doc.mjs'),
+      `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Ocean theme.', maintained: true};
+`,
     );
   }
   if (components) {
@@ -109,7 +94,7 @@ describe('integrationPackCheck', () => {
     );
   });
 
-  it('fails when a theme entry omits its catalog export', async () => {
+  it('fails when a theme entry omits its inferred runtime export', async () => {
     writePackage({files: ['astryx.integration.mjs', 'themes']});
     fs.writeFileSync(
       path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
@@ -129,19 +114,12 @@ describe('integrationPackCheck', () => {
     );
   });
 
-  it('fails when a theme imports a file omitted from its catalog', async () => {
+  it('fails when a theme imports a missing local file', async () => {
     writePackage({files: ['astryx.integration.mjs', 'themes']});
-    fs.mkdirSync(path.join(tmpDir, 'themes', 'ocean', 'tokens'), {
-      recursive: true,
-    });
     fs.writeFileSync(
       path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
       "import {oceanPalette} from './tokens/ocean.palette';\nexport const oceanTheme = {oceanPalette};\n",
     );
-    fs.writeFileSync(
-      path.join(tmpDir, 'themes', 'ocean', 'tokens', 'ocean.palette.ts'),
-      'export const oceanPalette = {};\n',
-    );
 
     const result = await integrationPackCheck({cwd: tmpDir});
 
@@ -150,7 +128,7 @@ describe('integrationPackCheck', () => {
       expect.objectContaining({
         code: 'invalid_theme',
         message: expect.stringContaining(
-          'must resolve to a listed file inside the theme directory',
+          'must resolve to a file inside the theme directory',
         ),
       }),
     );
@@ -231,7 +209,7 @@ describe('integrationPackCheck', () => {
     );
     fs.mkdirSync(path.join(tmpDir, 'templates'));
     fs.writeFileSync(
-      path.join(tmpDir, 'templates', 'account-page.template.mjs'),
+      path.join(tmpDir, 'templates', 'account-page.doc.mjs'),
       "export default {type: 'page', name: 'Account page', description: 'Account page.'};\n",
     );
     fs.writeFileSync(
@@ -314,10 +292,10 @@ describe('integrationPackCheck', () => {
     const script = [
       "const fs=require('fs')",
       "fs.renameSync('themes/ocean','themes/storm')",
-      "const p='themes/manifest.json'",
-      'const x=JSON.parse(fs.readFileSync(p))',
-      "x.themes[0].slug='storm'",
-      'fs.writeFileSync(p,JSON.stringify(x))',
+      "const p='themes/storm/oceanTheme.doc.mjs'",
+      "let x=fs.readFileSync(p,'utf8')",
+      "x=x.replace(/name: 'ocean'/, 'name: '+String.fromCharCode(39)+'storm'+String.fromCharCode(39))",
+      'fs.writeFileSync(p,x)',
     ].join(';');
     writePackage({
       files: ['astryx.integration.mjs', 'themes'],
@@ -513,23 +491,15 @@ describe('integrationPackCheck', () => {
 });
 
 describe('pack-check mutation tests', () => {
-  it('detects when a theme file is deleted after initial add', async () => {
+  it('detects when a theme source is deleted after initial authoring', async () => {
     writePackage({files: ['astryx.integration.mjs', 'themes']});
-
-    // Write a second theme file then delete it — catalog still references it
-    const catalog = JSON.parse(
-      fs.readFileSync(path.join(tmpDir, 'themes', 'manifest.json'), 'utf-8'),
-    );
-    catalog.themes[0].files.push('tokens.ts');
-    fs.writeFileSync(
-      path.join(tmpDir, 'themes', 'manifest.json'),
-      JSON.stringify(catalog, null, 2) + '\n',
-    );
-    // tokens.ts doesn't exist on disk → will be in inventory but not on disk
-    // (Phase 1 catches this; the file won't be in the pack list either)
+    fs.rmSync(path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'));
 
     const result = await integrationPackCheck({cwd: tmpDir});
     expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({code: 'invalid_theme'}),
+    );
   });
 
   it('detects when files[] is narrowed after add removes themes', async () => {
@@ -567,3 +537,252 @@ describe('pack-check mutation tests', () => {
     }
   });
 });
+
+describe('extensionless subpath resolution', () => {
+  it('rejects .tsx public specifiers before publishing', async () => {
+    // Manually construct a package with OLD-style .tsx exports keys
+    writePackage({
+      manifest: "export default {components: './components'};\n",
+      files: ['astryx.integration.mjs', 'components', 'index.mjs'],
+      themes: false,
+    });
+    const pkgFile = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    pkg.exports = {
+      '.': './index.mjs',
+      './components/AcmeWidget.tsx': './components/AcmeWidget.tsx',
+    };
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    fs.writeFileSync(
+      path.join(tmpDir, 'index.mjs'),
+      'export const existing = 1;\n',
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeWidget.doc.mjs'),
+      `export default {type: 'component', name: 'AcmeWidget', import: '@acme/widgets/components/AcmeWidget.tsx', description: 'Widget.', props: []};\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    // The .tsx extension in the specifier must be caught
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({
+        code: 'typescript_extension_in_specifier',
+        message: expect.stringContaining('.tsx'),
+      }),
+    );
+  });
+
+  it('generated extensionless component specifier resolves through exports map', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['index.mjs'],
+        exports: {'.': './index.mjs'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'index.mjs'),
+      'export const existing = 1;\n',
+    );
+    await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
+
+    // Verify the exports map has extensionless key → .tsx target
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+    );
+    expect(pkg.exports['./components/AcmeWidget']).toBe(
+      './components/AcmeWidget.tsx',
+    );
+    expect(pkg.exports['./components/AcmeWidget.tsx']).toBeUndefined();
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(true);
+    expect(result.data.issues).not.toContainEqual(
+      expect.objectContaining({code: 'typescript_extension_in_specifier'}),
+    );
+    expect(result.data.issues).not.toContainEqual(
+      expect.objectContaining({code: 'component_import_unresolvable'}),
+    );
+  });
+
+  it('validates generated imports without project-local TypeScript', async () => {
+    fs.rmSync(tmpDir, {recursive: true, force: true});
+    tmpDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'astryx-pack-check-no-typescript-'),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['index.mjs'],
+        exports: {'.': './index.mjs'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'index.mjs'),
+      'export const existing = 1;\n',
+    );
+    await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(true);
+    expect(result.data.issues).not.toContainEqual(
+      expect.objectContaining({code: 'component_import_unresolvable'}),
+    );
+  });
+
+  it('generated extensionless template specifiers resolve for page and block types', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['index.mjs'],
+        exports: {'.': './index.mjs'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'index.mjs'),
+      'export const existing = 1;\n',
+    );
+    await integrationAddTemplate('account-page', {cwd: tmpDir, type: 'page'});
+    await integrationAddTemplate('info-card', {cwd: tmpDir, type: 'block'});
+
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+    );
+    expect(pkg.exports['./templates/account-page']).toBe(
+      './templates/account-page.tsx',
+    );
+    expect(pkg.exports['./templates/info-card']).toBe(
+      './templates/info-card.tsx',
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(true);
+    expect(result.data.issues).not.toContainEqual(
+      expect.objectContaining({code: 'template_import_unresolvable'}),
+    );
+    expect(result.data.issues).not.toContainEqual(
+      expect.objectContaining({code: 'typescript_extension_in_specifier'}),
+    );
+  });
+
+  it('preserves condition-style exports sugar without creating a map', async () => {
+    // Package with condition-only exports (sugar, no subpaths)
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['index.mjs'],
+        exports: {import: './index.mjs', require: './index.cjs'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'index.mjs'),
+      'export const existing = 1;\n',
+    );
+    fs.writeFileSync(path.join(tmpDir, 'index.cjs'), 'exports.existing = 1;\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+
+    await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
+
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+    );
+    // Condition sugar wrapped into subpath map with the component added
+    expect(pkg.exports['.']).toEqual({
+      import: './index.mjs',
+      require: './index.cjs',
+    });
+    expect(pkg.exports['./components/AcmeWidget']).toBe(
+      './components/AcmeWidget.tsx',
+    );
+  });
+
+  it('no-map: pack-check fails when generated component has no exports map', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['dist'],
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+
+    await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
+    await integrationAddTemplate('hero-page', {cwd: tmpDir, type: 'page'});
+
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+    );
+    // No exports map created
+    expect(pkg.exports).toBeUndefined();
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    // The extensionless import cannot resolve without an exports map —
+    // pack-check must fail closed, not false-green.
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({
+        severity: 'error',
+        message: expect.stringContaining('AcmeWidget'),
+      }),
+    );
+  });
+
+  it('idempotent when extensionless export already exists', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['index.mjs'],
+        exports: {
+          '.': './index.mjs',
+          './components/AcmeWidget': './components/AcmeWidget.tsx',
+        },
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'index.mjs'),
+      'export const existing = 1;\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+
+    await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
+
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+    );
+    // Export preserved, no duplicate
+    expect(
+      Object.keys(pkg.exports).filter(k => k.includes('AcmeWidget')),
+    ).toEqual(['./components/AcmeWidget']);
+  });
+});

package/api/integration/summarizeIssues.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'summarizeIssues',
+  namespace: 'cli/api',
   displayName: 'summarizeIssues()',
   summary:
     'Tally integration issues by severity into error and warning counts.',