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

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

@@ -32,7 +32,7 @@ afterEach(() => {
 });
 
 describe('integrationAddTheme', () => {
-  it('writes a valid source theme, catalog, root, package files entry, and receipt', async () => {
+  it('writes a typed same-stem descriptor and source with no central catalog', async () => {
     setup();
     const result = await integrationAddTheme('ocean', {cwd: tmpDir});
 
@@ -45,7 +45,7 @@ describe('integrationAddTheme', () => {
         manifest: 'astryx.integration.mjs',
         files: [
           'themes/ocean/oceanTheme.ts',
-          'themes/manifest.json',
+          'themes/ocean/oceanTheme.doc.mjs',
           'package.json',
           'astryx.integration.mjs',
         ],
@@ -56,21 +56,17 @@ describe('integrationAddTheme', () => {
     expect(
       fs.readFileSync(path.join(tmpDir, 'themes/ocean/oceanTheme.ts'), 'utf-8'),
     ).toContain('export const oceanTheme = defineTheme');
-    expect(
-      JSON.parse(
-        fs.readFileSync(path.join(tmpDir, 'themes/manifest.json'), 'utf-8'),
-      ),
-    ).toMatchObject({
-      version: 1,
-      themes: [
-        {
-          slug: 'ocean',
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    });
+
+    const descriptor = fs.readFileSync(
+      path.join(tmpDir, 'themes/ocean/oceanTheme.doc.mjs'),
+      'utf-8',
+    );
+    expect(descriptor).toContain("@astryxdesign/cli/authoring').ThemeDoc");
+    expect(descriptor).toContain("type: 'theme'");
+    expect(descriptor).toContain("name: 'ocean'");
+    expect(fs.existsSync(path.join(tmpDir, 'themes/manifest.json'))).toBe(
+      false,
+    );
     expect(
       fs.readFileSync(path.join(tmpDir, 'astryx.integration.mjs'), 'utf-8'),
     ).toContain("themes: './themes'");
@@ -96,6 +92,7 @@ describe('integrationAddTheme', () => {
     expect(result.data.dryRun).toBe(true);
     expect(result.data.root).toEqual({path: './themes', created: true});
     expect(result.data.files).toContain('themes/ocean/oceanTheme.ts');
+    expect(result.data.files).toContain('themes/ocean/oceanTheme.doc.mjs');
     expect(fs.existsSync(path.join(tmpDir, 'themes'))).toBe(false);
     expect(
       fs.readFileSync(path.join(tmpDir, 'astryx.integration.mjs'), 'utf-8'),
@@ -125,22 +122,69 @@ describe('integrationAddTheme', () => {
     expect(
       fs.existsSync(path.join(tmpDir, 'src/themes/ocean/oceanTheme.ts')),
     ).toBe(true);
+    expect(
+      fs.existsSync(path.join(tmpDir, 'src/themes/ocean/oceanTheme.doc.mjs')),
+    ).toBe(true);
   });
 
-  it('refuses an invalid existing catalog without changing its bytes', async () => {
+  it('keeps each theme to its own folder: a second theme touches no shared file', async () => {
+    setup({manifest: "export default {themes: './themes'};\n"});
+    await integrationAddTheme('ocean', {cwd: tmpDir});
+    const shared = ['package.json', 'astryx.integration.mjs'].map(file =>
+      fs.readFileSync(path.join(tmpDir, file), 'utf-8'),
+    );
+
+    const result = await integrationAddTheme('reef', {cwd: tmpDir});
+
+    expect(result.data.files).toEqual([
+      'themes/reef/reefTheme.ts',
+      'themes/reef/reefTheme.doc.mjs',
+    ]);
+    expect(fs.readdirSync(path.join(tmpDir, 'themes')).sort()).toEqual([
+      'ocean',
+      'reef',
+    ]);
+    expect(
+      ['package.json', 'astryx.integration.mjs'].map(file =>
+        fs.readFileSync(path.join(tmpDir, file), 'utf-8'),
+      ),
+    ).toEqual(shared);
+  });
+
+  it('refuses an obsolete central catalog without changing its bytes', async () => {
     setup();
     fs.mkdirSync(path.join(tmpDir, 'themes'));
     const catalog = path.join(tmpDir, 'themes', 'manifest.json');
-    fs.writeFileSync(catalog, '{not-json\n');
+    fs.writeFileSync(catalog, '{"version":1}\n');
 
     await expect(
       integrationAddTheme('ocean', {cwd: tmpDir}),
     ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
-    expect(fs.readFileSync(catalog, 'utf-8')).toBe('{not-json\n');
+    expect(fs.readFileSync(catalog, 'utf-8')).toBe('{"version":1}\n');
     expect(fs.existsSync(path.join(tmpDir, 'themes', 'ocean'))).toBe(false);
   });
 
-  it('refuses duplicate themes and existing source files', async () => {
+  it('refuses an invalid existing descriptor without changing it', async () => {
+    setup();
+    const existing = path.join(tmpDir, 'themes', 'forest');
+    fs.mkdirSync(existing, {recursive: true});
+    const descriptor = path.join(existing, 'forestTheme.doc.mjs');
+    fs.writeFileSync(descriptor, 'export default {type: "theme"};\n');
+    fs.writeFileSync(
+      path.join(existing, 'forestTheme.ts'),
+      'export const forestTheme = {};\n',
+    );
+
+    await expect(
+      integrationAddTheme('ocean', {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
+    expect(fs.readFileSync(descriptor, 'utf-8')).toBe(
+      'export default {type: "theme"};\n',
+    );
+    expect(fs.existsSync(path.join(tmpDir, 'themes', 'ocean'))).toBe(false);
+  });
+
+  it('refuses a duplicate valid theme directory', async () => {
     setup();
     await integrationAddTheme('ocean', {cwd: tmpDir});
     await expect(
@@ -148,6 +192,46 @@ describe('integrationAddTheme', () => {
     ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
   });
 
+  it('refuses an existing invalid theme directory', async () => {
+    setup();
+    fs.mkdirSync(path.join(tmpDir, 'themes', 'ocean'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
+      'export const oceanTheme = {};\n',
+    );
+    await expect(
+      integrationAddTheme('ocean', {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
+  });
+
+  it.each([
+    ['an empty folder', []],
+    ['a folder holding .gitkeep', ['.gitkeep']],
+    ['a folder holding NOTES.md', ['NOTES.md']],
+  ])('fills %s', async (_, files) => {
+    setup();
+    const dir = path.join(tmpDir, 'themes', 'ocean');
+    fs.mkdirSync(dir, {recursive: true});
+    for (const file of files) fs.writeFileSync(path.join(dir, file), 'x\n');
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.written).toBe(true);
+    expect(fs.readdirSync(dir).sort()).toEqual(
+      [...files, 'oceanTheme.doc.mjs', 'oceanTheme.ts'].sort(),
+    );
+  });
+
+  it('refuses to overwrite a file it would write', async () => {
+    setup();
+    await integrationAddTheme('ocean', {cwd: tmpDir});
+    await expect(
+      integrationAddTheme('ocean', {cwd: tmpDir}),
+    ).rejects.toMatchObject({
+      code: 'ERR_FILE_EXISTS',
+      message:
+        'Refusing to overwrite existing file themes/ocean/oceanTheme.ts.',
+    });
+  });
+
   it.each(['../ocean', 'Ocean', 'ocean theme', '.ocean'])(
     'refuses unsafe or noncanonical name %s',
     async name => {

package/api/integration/authoring-checks.test.mjs

@@ -33,7 +33,7 @@ function writeIntegration({id, name, type = 'block', root = tmpDir}) {
   const stem = path.join(root, 'templates', id);
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
-    `${stem}.template.mjs`,
+    `${stem}.doc.mjs`,
     `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
   );
   fs.writeFileSync(
@@ -176,7 +176,7 @@ describe('integrationTemplateConflicts', () => {
     );
     fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
     fs.writeFileSync(
-      path.join(tmpDir, 'templates', 'broken.template.mjs'),
+      path.join(tmpDir, 'templates', 'broken.doc.mjs'),
       `throw new Error('broken fixture');\n`,
     );
     fs.writeFileSync(
@@ -221,7 +221,9 @@ describe('integrationComponentConflicts', () => {
     expect(core).toBeDefined();
     writeComponentIntegration(core.name);
 
-    const result = await integrationComponentConflicts(undefined, {cwd: tmpDir});
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
 
     expect(result.type).toBe('integration.component-conflicts');
     expect(result.data.issues).toEqual([]);
@@ -240,7 +242,9 @@ describe('integrationComponentConflicts', () => {
   it('does not flag an integration-only component name', async () => {
     writeComponentIntegration('AcmeOnlyWidget');
 
-    const result = await integrationComponentConflicts(undefined, {cwd: tmpDir});
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
 
     expect(result.data.conflicts).toEqual([]);
     expect(result.data.issues).toEqual([]);

package/api/integration/integration-block-exports.test.mjs

@@ -51,7 +51,7 @@ const ESBUILD_BIN = resolveBin('esbuild/bin/esbuild');
 let tmpDir;
 
 /**
- * Build an @acme/widgets fixture: a block template (`.template.ts` doc +
+ * Build an @acme/widgets fixture: a block template (released `.template.ts` compatibility descriptor +
  * same-stem `.tsx` source) under `templates/`, plus an astryx.integration
  * manifest, plus a caller-supplied `exports` map.
  * @param {Record<string, string> | undefined} exportsMap
@@ -71,7 +71,7 @@ function makeWidgets(exportsMap) {
     path.join(pkgDir, 'astryx.integration.mjs'),
     `export default { templates: './templates' };\n`,
   );
-  // The template-spec doc (canonical `.template.*` family).
+  // The released `.template.*` compatibility form remains resolvable.
   fs.writeFileSync(
     path.join(blockDir, 'GaugeShowcase.template.ts'),
     `export default { name: 'Gauge showcase', description: 'A gauge.' };\n`,
@@ -127,10 +127,14 @@ function writeTsconfig() {
 /** @returns {{ok: boolean, out: string}} */
 function runTsc() {
   try {
-    execFileSync(process.execPath, [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'], {
-      cwd: tmpDir,
-      stdio: 'pipe',
-    });
+    execFileSync(
+      process.execPath,
+      [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'],
+      {
+        cwd: tmpDir,
+        stdio: 'pipe',
+      },
+    );
     return {ok: true, out: ''};
   } catch (e) {
     return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};

package/api/integration/integrationAdd.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAdd',
+  namespace: 'cli/api',
   displayName: 'integrationAdd()',
   summary: 'Add one working contribution to an integration package.',
   description:

package/api/integration/integrationAddAgentDoc.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddAgentDoc',
+  namespace: 'cli/api',
   displayName: 'integrationAddAgentDoc()',
   summary: 'Append one validated agent-guidance line.',
   description:

package/api/integration/integrationAddCodemod.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddCodemod',
+  namespace: 'cli/api',
   displayName: 'integrationAddCodemod()',
   summary: 'Add a safe identity codemod at an exact target version.',
   description:

package/api/integration/integrationAddComponent.doc.mjs

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

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.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 () => {

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.',