@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/api/integration/pack-check.mjs

@@ -27,6 +27,11 @@ import {spawnSync} from 'node:child_process';
 import jscodeshift from 'jscodeshift';
 import {assertWithin} from '../../foundation/fs/path-safety.mjs';
 import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs';
+import {
+  docsTreeCliProblem,
+  replacesCliProblem,
+} from '../../foundation/integrations/cli-requirement.mjs';
+import {discoverIntegrationDocs} from '../../foundation/discovery/docs-discovery.mjs';
 import {
   discoverIntegrationComponents,
   resolveIntegrationImportPath,
@@ -388,6 +393,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 +440,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 +490,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.
  *
@@ -549,6 +596,35 @@ export async function integrationPackCheck(options = {}) {
       );
     }
   }
+  // A namespace doc or a placed guide needs a CLI that reads the docs tree
+  // (spec:AST-046 FR11): an older CLI can hide every doc topic the package
+  // ships, so the declared CLI range must admit only CLIs that read it.
+  if (loaded.docs) {
+    const {namespaces, guides} = await discoverIntegrationDocs(loaded).catch(
+      () => ({namespaces: [], guides: []}),
+    );
+    const problem =
+      namespaces.length > 0 || guides.length > 0
+        ? docsTreeCliProblem(pkg)
+        : null;
+    if (problem != null) {
+      issues.push(error('docs_tree_needs_cli', problem));
+    }
+  }
+  // A template that sets `replaces` needs a CLI that reads the field
+  // (spec:AST-035): an older CLI withholds the package's templates and docs.
+  if (loaded.templates) {
+    const found = await discoverIntegrationTemplatesForOne(loaded).catch(
+      () => ({templates: [], errors: []}),
+    );
+    const setsReplaces =
+      found.templates.some(template => template.replaces != null) ||
+      found.errors.some(
+        (/** @type {any} */ issue) => issue.replacementTarget != null,
+      );
+    const problem = setsReplaces ? replacesCliProblem(pkg) : null;
+    if (problem != null) issues.push(error('replaces_needs_cli', problem));
+  }
 
   // Temp resources — always cleaned up
   const tgzTmpDir = fs.mkdtempSync(

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(
@@ -302,6 +280,93 @@ describe('integrationPackCheck', () => {
     expect(fileErrors.length).toBeGreaterThan(0);
   });
 
+  it('fails a package that ships a namespace doc on a CLI range that cannot read it', async () => {
+    writePackage({manifest: "export default {docs: './docs'};\n", themes: false});
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme.doc.mjs'),
+      "export default {type: 'namespace', name: 'acme', title: 'Acme', summary: 'Acme guides.', slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}}};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'deploying.doc.mjs'),
+      "export default {type: 'generic', name: 'deploying', title: 'Deploying', description: 'Ship it.', placement: {parent: 'namespace:acme', slot: 'guides'}, sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}]};\n",
+    );
+    const file = path.join(tmpDir, 'package.json');
+    const peer = (/** @type {string | undefined} */ range) => {
+      const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+      if (range == null) delete pkg.peerDependencies;
+      else pkg.peerDependencies = {'@astryxdesign/cli': range};
+      fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+    };
+    const codes = async () =>
+      (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
+        (/** @type {{code: string}} */ issue) => issue.code,
+      );
+
+    peer(undefined);
+    expect(await codes()).toContain('docs_tree_needs_cli');
+    peer('^0.6.0 || >=0.7.0');
+    expect(await codes()).toContain('docs_tree_needs_cli');
+    peer('>=0.7.0');
+    expect(await codes()).not.toContain('docs_tree_needs_cli');
+  }, 120_000);
+
+  it('fails a package with only a placed guide on a CLI range that cannot read the docs tree, and passes flat topics', async () => {
+    writePackage({manifest: "export default {docs: './docs'};\n", themes: false});
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'notes.doc.mjs'),
+      "export default {type: 'generic', name: 'notes', title: 'Notes', description: 'Notes.', sections: [{title: 'Overview', content: [{type: 'prose', text: 'Notes.'}]}]};\n",
+    );
+    const codes = async () =>
+      (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
+        (/** @type {{code: string}} */ issue) => issue.code,
+      );
+    // Flat topics alone need no CLI peer.
+    expect(await codes()).not.toContain('docs_tree_needs_cli');
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'setup.doc.mjs'),
+      "export default {type: 'generic', name: 'setup', title: 'Setup', description: 'Set up.', placement: {parent: 'namespace:acme', slot: 'guides'}, sections: [{title: 'Overview', content: [{type: 'prose', text: 'Set up.'}]}]};\n",
+    );
+    expect(await codes()).toContain('docs_tree_needs_cli');
+    const file = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    pkg.peerDependencies = {'@astryxdesign/cli': '>=0.7.0'};
+    fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+    expect(await codes()).not.toContain('docs_tree_needs_cli');
+  }, 120_000);
+
+  it('fails a package with a template that sets replaces on a CLI range that rejects the field', async () => {
+    writePackage({manifest: "export default {templates: './templates'};\n", themes: false});
+    fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'templates', 'acme-shell.doc.mjs'),
+      "export default {type: 'page', name: 'acme-shell', description: 'Acme shell.', replaces: 'shell-side-nav'};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'templates', 'acme-shell.tsx'),
+      'export default function AcmeShell() { return null; }\n',
+    );
+    const file = path.join(tmpDir, 'package.json');
+    const peer = (/** @type {string | undefined} */ range) => {
+      const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+      if (range == null) delete pkg.peerDependencies;
+      else pkg.peerDependencies = {'@astryxdesign/cli': range};
+      fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+    };
+    const codes = async () =>
+      (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
+        (/** @type {{code: string}} */ issue) => issue.code,
+      );
+
+    peer(undefined);
+    expect(await codes()).toContain('replaces_needs_cli');
+    peer('^0.6.0');
+    expect(await codes()).toContain('replaces_needs_cli');
+    peer('>=0.7.0');
+    expect(await codes()).not.toContain('replaces_needs_cli');
+  }, 120_000);
+
   it('passes when package.json has no files field', async () => {
     writePackage({files: undefined});
     const result = await integrationPackCheck({cwd: tmpDir});
@@ -310,14 +375,48 @@ describe('integrationPackCheck', () => {
     expect(result.data.packable).toBe(true);
   });
 
+  it('detects a lifecycle script that changes packed template replacements', async () => {
+    const script = [
+      "const fs=require('fs')",
+      "const p='templates/acme-shell.template.mjs'",
+      "const s=fs.readFileSync(p,'utf8')",
+      "fs.writeFileSync(p,s.replace('shell-side-nav','shell-top-nav'))",
+    ].join(';');
+    writePackage({
+      manifest: "export default {templates: './templates'};\n",
+      files: ['astryx.integration.mjs', 'templates'],
+      themes: false,
+      scripts: {prepack: `node -e "${script}"`},
+    });
+    fs.mkdirSync(path.join(tmpDir, 'templates'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'templates', 'acme-shell.template.mjs'),
+      "export default {type: 'page', name: 'Acme shell', description: 'Fixture.', replaces: 'shell-side-nav'};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'templates', 'acme-shell.tsx'),
+      'export default function AcmeShell() { return null; }\n',
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({
+        code: 'identity_mismatch',
+        message: expect.stringContaining('acme-shell'),
+      }),
+    );
+  });
+
   it('detects a lifecycle script that changes the packed identity', async () => {
     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 +612,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 +658,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/pack-check.type.d.mts

@@ -9,6 +9,30 @@ export type IntegrationPackCheckResponse = {
     data: PackCheckData;
 };
 export type PackCheckResponse = IntegrationPackCheckResponse;
+/**
+ * Public contribution inventory returned by pack-check. Kept here rather than
+ * importing the runtime inventory module so the type-only `/json` surface does
+ * not pull implementation dependencies into downstream type checking.
+ */
+export type PackCheckContributionIdentities = {
+    themes: {
+        slug: string;
+        exportName: string;
+    }[];
+    components: string[];
+    templates: {
+        id: string;
+        type: string;
+        name: string;
+        replaces?: string;
+    }[];
+    codemods: {
+        version: string;
+        id: string;
+    }[];
+    docs: string[];
+    agentDocsAppend: string[];
+};
 export type PackCheckData = {
     name: string | null;
     version: string | null;
@@ -19,8 +43,8 @@ export type PackCheckData = {
     tarball: PackCheckTarball | null;
     inventory: PackCheckInventory;
     contributions: {
-        local: import("../../foundation/integrations/contribution-inventory.mjs").ContributionIdentities | null;
-        packed: import("../../foundation/integrations/contribution-inventory.mjs").ContributionIdentities | null;
+        local: PackCheckContributionIdentities | null;
+        packed: PackCheckContributionIdentities | null;
     };
     issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
 };