@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.f04b501

package/foundation/integrations/contribution-inventory.d.mts

@@ -15,7 +15,7 @@
  */
 /**
  * Compute the files the tarball must contain for an integration's
- * contributions to be visible. Reads catalogs and walks directories;
+ * contributions to be visible. Walks descriptor-owned directories;
  * never imports or executes authored modules.
  *
  * @param {import('./integrations.mjs').LoadedIntegration} loaded

package/foundation/integrations/contribution-inventory.mjs

@@ -14,8 +14,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {isDeepStrictEqual} from 'node:util';
-import {THEME_MANIFEST_BASENAME} from '../discovery/theme-discovery.mjs';
-import {discoverIntegrationThemes} from '../discovery/theme-discovery.mjs';
+import {
+  discoverIntegrationThemes,
+  isThemeFolder,
+  listThemeFiles,
+} from '../discovery/theme-discovery.mjs';
 import {discoverIntegrationComponents} from '../discovery/component-discovery.mjs';
 import {loadComponentDoc} from '../discovery/component-loader.mjs';
 import {discoverIntegrationTemplatesForOne} from '../discovery/template-adapter.mjs';
@@ -65,27 +68,21 @@ function rel(packageDir, file) {
 
 /** @param {string} root @param {string} pkgDir */
 function enumerateThemeFiles(root, pkgDir) {
+  if (!root || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    return [];
+  }
+  // Exactly what `theme add` copies: each theme folder's files, including
+  // tests and fixtures, but no dot entry or file npm never publishes. Files
+  // beside the theme folders belong to no theme.
   /** @type {string[]} */
   const files = [];
-  const catalog = path.join(root, THEME_MANIFEST_BASENAME);
-  if (!fs.existsSync(catalog)) return files;
-  files.push(rel(pkgDir, catalog));
-  try {
-    const data = JSON.parse(fs.readFileSync(catalog, 'utf-8'));
-    if (data?.version !== 1 || !Array.isArray(data.themes)) return files;
-    for (const theme of data.themes) {
-      if (typeof theme.slug !== 'string' || !Array.isArray(theme.files))
-        continue;
-      for (const f of theme.files) {
-        if (typeof f === 'string') {
-          files.push(rel(pkgDir, path.join(root, theme.slug, f)));
-        }
-      }
+  for (const entry of fs.readdirSync(root, {withFileTypes: true})) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory() && isThemeFolder(full)) {
+      files.push(...listThemeFiles(full).map(file => path.join(full, file)));
     }
-  } catch {
-    /* Phase 1 catches structural issues */
   }
-  return files;
+  return files.sort().map(file => rel(pkgDir, file));
 }
 
 /** @param {string} root @param {string} pkgDir */
@@ -158,7 +155,7 @@ const ROOT_KINDS = /** @type {const} */ ([
 
 /**
  * Compute the files the tarball must contain for an integration's
- * contributions to be visible. Reads catalogs and walks directories;
+ * contributions to be visible. Walks descriptor-owned directories;
  * never imports or executes authored modules.
  *
  * @param {import('./integrations.mjs').LoadedIntegration} loaded

package/foundation/integrations/contribution-inventory.test.mjs

@@ -37,30 +37,37 @@ function loaded(overrides = {}) {
 
 function writeTheme(slug, files = [`${slug}Theme.ts`]) {
   const root = path.join(tmpDir, 'themes');
-  fs.mkdirSync(path.join(root, slug), {recursive: true});
-  for (const f of files) {
-    fs.writeFileSync(path.join(root, slug, f), `// ${f}\n`);
+  const themeDir = path.join(root, slug);
+  fs.mkdirSync(themeDir, {recursive: true});
+  for (const file of files) {
+    const target = path.join(themeDir, file);
+    fs.mkdirSync(path.dirname(target), {recursive: true});
+    fs.writeFileSync(target, `// ${file}\n`);
   }
-  const catalogPath = path.join(root, 'manifest.json');
-  let catalog = {version: 1, themes: []};
-  if (fs.existsSync(catalogPath)) {
-    catalog = JSON.parse(fs.readFileSync(catalogPath, 'utf-8'));
-  }
-  catalog.themes.push({
-    slug,
-    displayName: slug,
-    description: `${slug} theme.`,
-    maintained: true,
-    entry: files[0],
-    exportName: `${slug}Theme`,
-    files,
-  });
-  fs.writeFileSync(catalogPath, JSON.stringify(catalog, null, 2) + '\n');
+  fs.writeFileSync(
+    path.join(themeDir, `${slug}Theme.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: '${slug}', displayName: '${slug}', description: '${slug} theme.', maintained: true};\n`,
+  );
   return root;
 }
 
+const UNPUBLISHED = [
+  '.DS_Store',
+  '._oceanTheme.ts',
+  '.gitignore',
+  '.npmignore',
+  '.npmrc',
+  'oceanTheme.ts.orig',
+  'npm-debug.log',
+  'palette/.DS_Store',
+  'palette/npm-debug.log',
+  '.git/HEAD',
+  'CVS/Entries',
+  'node_modules/dep/index.js',
+];
+
 describe('computeRequiredFiles', () => {
-  it('enumerates manifest + theme catalog files', () => {
+  it('enumerates each complete descriptor-owned theme directory', () => {
     const root = writeTheme('ocean', ['oceanTheme.ts', 'tokens.ts']);
     const inv = computeRequiredFiles(loaded({themes: root}));
 
@@ -69,13 +76,46 @@ describe('computeRequiredFiles', () => {
     expect(inv.roots[0].kind).toBe('themes');
     expect(inv.roots[0].files).toEqual(
       expect.arrayContaining([
-        'themes/manifest.json',
+        'themes/ocean/oceanTheme.doc.mjs',
         'themes/ocean/oceanTheme.ts',
         'themes/ocean/tokens.ts',
       ]),
     );
     expect(inv.allFiles).toContain('astryx.integration.mjs');
-    expect(inv.allFiles).toContain('themes/manifest.json');
+    expect(inv.allFiles).toContain('themes/ocean/oceanTheme.doc.mjs');
+    expect(inv.allFiles).not.toContain('themes/manifest.json');
+  });
+
+  it('requires no file npm leaves out, at any depth, and none beside the themes', () => {
+    const root = writeTheme('ocean', ['oceanTheme.ts', 'palette/tokens.ts']);
+    for (const file of [
+      ...UNPUBLISHED.map(name => `ocean/${name}`),
+      'README.md',
+      'npm-debug.log',
+    ]) {
+      fs.mkdirSync(path.dirname(path.join(root, file)), {recursive: true});
+      fs.writeFileSync(path.join(root, file), 'x\n');
+    }
+    expect(computeRequiredFiles(loaded({themes: root})).roots[0].files).toEqual(
+      [
+        'themes/ocean/oceanTheme.doc.mjs',
+        'themes/ocean/oceanTheme.ts',
+        'themes/ocean/palette/tokens.ts',
+      ],
+    );
+  });
+
+  it('requires only the folders theme discovery reads', () => {
+    const root = writeTheme('ocean');
+    for (const file of ['shared/palette.ts', '.cache/state.json']) {
+      fs.mkdirSync(path.dirname(path.join(root, file)), {recursive: true});
+      fs.writeFileSync(path.join(root, file), '{}\n');
+    }
+    const inv = computeRequiredFiles(loaded({themes: root}));
+    expect(inv.roots[0].files).toEqual([
+      'themes/ocean/oceanTheme.doc.mjs',
+      'themes/ocean/oceanTheme.ts',
+    ]);
   });
 
   it('enumerates paired component metadata and source files', () => {
@@ -139,31 +179,31 @@ describe('computeRequiredFiles', () => {
     const root = path.join(tmpDir, 'templates');
     fs.mkdirSync(path.join(root, 'dashboard'), {recursive: true});
     fs.writeFileSync(
-      path.join(root, 'dashboard', 'dashboard.template.mjs'),
+      path.join(root, 'dashboard', 'dashboard.doc.mjs'),
       '// tmpl\n',
     );
     fs.writeFileSync(path.join(root, 'dashboard', 'dashboard.tsx'), '// src\n');
     const inv = computeRequiredFiles(loaded({templates: root}));
 
     expect(inv.roots[0].files).toContain(
-      'templates/dashboard/dashboard.template.mjs',
+      'templates/dashboard/dashboard.doc.mjs',
     );
     expect(inv.roots[0].files).toContain('templates/dashboard/dashboard.tsx');
   });
 
-  it('enumerates legacy .doc template metadata with paired sources', () => {
+  it('enumerates released .template compatibility metadata with paired sources', () => {
     const root = path.join(tmpDir, 'templates');
     fs.mkdirSync(path.join(root, 'dashboard'), {recursive: true});
     fs.writeFileSync(
-      path.join(root, 'dashboard', 'dashboard.doc.mjs'),
-      '// legacy template\n',
+      path.join(root, 'dashboard', 'dashboard.template.mjs'),
+      '// released compatibility template\n',
     );
     fs.writeFileSync(path.join(root, 'dashboard', 'dashboard.tsx'), '// src\n');
 
     const inv = computeRequiredFiles(loaded({templates: root}));
 
     expect(inv.roots[0].files).toEqual([
-      'templates/dashboard/dashboard.doc.mjs',
+      'templates/dashboard/dashboard.template.mjs',
       'templates/dashboard/dashboard.tsx',
     ]);
   });

package/foundation/integrations/integration-warnings.mjs

@@ -41,6 +41,12 @@ export async function warnOnIntegrationIssues(loadedIntegrations, {json = false}
     }
     for (const integration of loadedIntegrations) {
       if (!integration || typeof integration !== 'object') continue;
+      // A package set aside for a provider-ID conflict is fine in isolation,
+      // so `doctor integration validate` would not explain it. Say it here.
+      if (integration.__providerConflict) {
+        console.error(`Warning: ${integration.__providerConflict.message}`);
+        continue;
+      }
       let issues;
       try {
         issues = await validateLoadedIntegration(integration);

package/foundation/integrations/integrations.d.mts

@@ -1,6 +1,26 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * Resolve provider identity across loaded integrations, in precedence order.
+ *
+ * Artifact and document IDs are provider-scoped, so two packages cannot both
+ * contribute under one provider ID. The same package reached twice (an npm
+ * alias beside the package it aliases, with the same name and version) loads
+ * once. Any other later claimant, including the same package at another
+ * version, stays as an inert entry that carries the conflict. The package being
+ * authored claims its ID before precedence order is considered, because the
+ * source being edited is authoritative. The winner still contributes; Project
+ * issues, Doctor, and the per-command warning name the one set aside instead of
+ * dropping it without a word.
+ *
+ * The conflict pass of {@link resolveProviders}, for a list that is already
+ * assembled.
+ *
+ * @param {LoadedIntegration[]} integrations in precedence order
+ * @returns {LoadedIntegration[]}
+ */
+export function markProviderConflicts(integrations: LoadedIntegration[]): LoadedIntegration[];
 /**
  * Return the conventional root manifest paths present in `dir`, in
  * load-precedence order. Unlike {@link resolveManifestPath} this never throws —
@@ -75,12 +95,15 @@ export function loadLocalIntegration(packageDir: string, { fresh }?: {
  * Load configured integrations.
  *
  * @param {string[]} [specs] package names
- * @param {{cwd?: string, fresh?: boolean}} [options]
+ * @param {{cwd?: string, fresh?: boolean, resolveProviders?: boolean}} [options]
+ *   `resolveProviders: false` leaves provider identity to a caller that
+ *   resolves it once over a larger set (Project.load)
  * @returns {Promise<LoadedIntegration[]>}
  */
-export function loadIntegrations(specs?: string[], { cwd, fresh }?: {
+export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProviders }?: {
     cwd?: string;
     fresh?: boolean;
+    resolveProviders?: boolean;
 }): Promise<LoadedIntegration[]>;
 /**
  * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
@@ -89,6 +112,10 @@ export function loadIntegrations(specs?: string[], { cwd, fresh }?: {
  * are internal bookkeeping used by Doctor integration validation and Project.
  * @typedef {object} LoadedIntegration
  * @property {string} name
+ * @property {import('../../authoring/identity/type').ProviderId} [providerId]
+ *   normalized stable provider identity; absent only for a legacy unnamed local
+ *   package. Unique among contributing integrations: a later claimant is kept
+ *   inert with `__providerConflict` (see {@link markProviderConflicts})
  * @property {string} [version]
  * @property {string} [components]
  * @property {string} [templates]
@@ -107,6 +134,10 @@ export function loadIntegrations(specs?: string[], { cwd, fresh }?: {
  * @property {string} __manifestFile
  * @property {string} [__loadError] set when the manifest failed to load/validate;
  *   such an integration contributes nothing and is surfaced via Project.issues()
+ * @property {{providerId: import('../../authoring/identity/type').ProviderId, claimedBy: string, message: string}} [__providerConflict]
+ *   set on a package whose provider ID an earlier-loaded package already
+ *   claims; it contributes nothing and is reported as a `duplicate_provider`
+ *   warning
  * @property {string[]} [__unknownKeys] manifest keys this CLI does not know —
  *   surfaced as a warning; the rest of the manifest still contributes
  * @property {boolean} [__autolinked] loaded because the project declares the
@@ -134,6 +165,12 @@ export const MANIFEST_BASENAMES: string[];
  */
 export type LoadedIntegration = {
     name: string;
+    /**
+     * normalized stable provider identity; absent only for a legacy unnamed local
+     * package. Unique among contributing integrations: a later claimant is kept
+     * inert with `__providerConflict` (see {@link markProviderConflicts})
+     */
+    providerId?: import("../../authoring/identity/type").ProviderId | undefined;
     version?: string | undefined;
     components?: string | undefined;
     templates?: string | undefined;
@@ -163,6 +200,16 @@ export type LoadedIntegration = {
      * such an integration contributes nothing and is surfaced via Project.issues()
      */
     __loadError?: string | undefined;
+    /**
+     * set on a package whose provider ID an earlier-loaded package already
+     * claims; it contributes nothing and is reported as a `duplicate_provider`
+     * warning
+     */
+    __providerConflict?: {
+        providerId: import("../../authoring/identity/type").ProviderId;
+        claimedBy: string;
+        message: string;
+    } | undefined;
     /**
      * manifest keys this CLI does not know —
      * surfaced as a warning; the rest of the manifest still contributes

package/foundation/integrations/integrations.mjs

@@ -6,13 +6,19 @@
  * Integrations are PACKAGE NAMES listed in astryx.config.{ts,mjs,js}. Each
  * package declares a single conventional root manifest sibling to its
  * package.json — astryx.integration.{ts,mjs,js} — which contributes
- * components/templates/codemods/docs/themes roots and an optional issuesUrl. Identity
- * (name, version) comes from the package's package.json, not the manifest.
+ * components/templates/codemods/docs/themes roots and an optional issuesUrl.
+ * Stable provider identity and package metadata come from package.json, not the
+ * manifest.
+ *
+ * @input Integration package names, package.json files, and root manifests.
+ * @output LoadedIntegration records with normalized provider identity and roots.
+ * @position foundation/integrations — package contribution loading boundary.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {assertWithin} from '../fs/path-safety.mjs';
+import {normalizeProviderId} from '../identity/provider-identity.mjs';
 // The key census and contribution parsers are internal to the schema module on
 // purpose: the public parser still validates the complete authored type, while
 // the loader can isolate an invalid optional contribution from valid roots.
@@ -23,6 +29,7 @@ import {
 } from '../../authoring/integration/schema.mjs';
 import {importUserModule, findPresentFiles} from '../fs/module-loader.mjs';
 import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
+import {resolveProviders} from './provider-resolution.mjs';
 
 /**
  * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
@@ -31,6 +38,10 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
  * are internal bookkeeping used by Doctor integration validation and Project.
  * @typedef {object} LoadedIntegration
  * @property {string} name
+ * @property {import('../../authoring/identity/type').ProviderId} [providerId]
+ *   normalized stable provider identity; absent only for a legacy unnamed local
+ *   package. Unique among contributing integrations: a later claimant is kept
+ *   inert with `__providerConflict` (see {@link markProviderConflicts})
  * @property {string} [version]
  * @property {string} [components]
  * @property {string} [templates]
@@ -49,6 +60,10 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
  * @property {string} __manifestFile
  * @property {string} [__loadError] set when the manifest failed to load/validate;
  *   such an integration contributes nothing and is surfaced via Project.issues()
+ * @property {{providerId: import('../../authoring/identity/type').ProviderId, claimedBy: string, message: string}} [__providerConflict]
+ *   set on a package whose provider ID an earlier-loaded package already
+ *   claims; it contributes nothing and is reported as a `duplicate_provider`
+ *   warning
  * @property {string[]} [__unknownKeys] manifest keys this CLI does not know —
  *   surfaced as a warning; the rest of the manifest still contributes
  * @property {boolean} [__autolinked] loaded because the project declares the
@@ -74,6 +89,50 @@ export const MANIFEST_BASENAMES = [
   'astryx.integration.js',
 ];
 
+/**
+ * Normalize a package-owned provider ID without rejecting legacy unnamed local
+ * packages at this compatibility boundary.
+ * @param {unknown} name
+ * @returns {import('../../authoring/identity/type').ProviderId | undefined}
+ */
+function providerIdForPackage(name) {
+  if (typeof name !== 'string' || name.length === 0) return undefined;
+  try {
+    return normalizeProviderId(name);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve provider identity across loaded integrations, in precedence order.
+ *
+ * Artifact and document IDs are provider-scoped, so two packages cannot both
+ * contribute under one provider ID. The same package reached twice (an npm
+ * alias beside the package it aliases, with the same name and version) loads
+ * once. Any other later claimant, including the same package at another
+ * version, stays as an inert entry that carries the conflict. The package being
+ * authored claims its ID before precedence order is considered, because the
+ * source being edited is authoritative. The winner still contributes; Project
+ * issues, Doctor, and the per-command warning name the one set aside instead of
+ * dropping it without a word.
+ *
+ * The conflict pass of {@link resolveProviders}, for a list that is already
+ * assembled.
+ *
+ * @param {LoadedIntegration[]} integrations in precedence order
+ * @returns {LoadedIntegration[]}
+ */
+export function markProviderConflicts(integrations) {
+  return resolveProviders(
+    integrations.map(integration => ({
+      source: /** @type {const} */ ('configured'),
+      integration,
+      spec: integration?.__spec,
+    })),
+  ).integrations;
+}
+
 /**
  * Return the conventional root manifest paths present in `dir`, in
  * load-precedence order. Unlike {@link resolveManifestPath} this never throws —
@@ -274,6 +333,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     typeof pkg.name === 'string' && pkg.name.length > 0
       ? pkg.name
       : '(local integration)';
+  const packageProviderId = providerIdForPackage(pkg.name);
   const manifestFile = resolveManifestPath(packageDir, spec);
 
   let manifest;
@@ -299,6 +359,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
   } catch (err) {
     return {
       name: spec,
+      ...(packageProviderId == null ? {} : {providerId: packageProviderId}),
       version: pkg.version,
       __spec: spec,
       __packageDir: packageDir,
@@ -308,6 +369,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     };
   }
 
+  const providerId = providerIdForPackage(manifest.providerId ?? pkg.name);
+
   /** @param {string | null | undefined} value */
   const resolveRoot = value => {
     if (value == null) return undefined;
@@ -320,6 +383,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
 
   return {
     name: spec,
+    ...(providerId == null ? {} : {providerId}),
     version: pkg.version,
     components: resolveRoot(manifest.components),
     templates: resolveRoot(manifest.templates),
@@ -345,20 +409,22 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
  * Load configured integrations.
  *
  * @param {string[]} [specs] package names
- * @param {{cwd?: string, fresh?: boolean}} [options]
+ * @param {{cwd?: string, fresh?: boolean, resolveProviders?: boolean}} [options]
+ *   `resolveProviders: false` leaves provider identity to a caller that
+ *   resolves it once over a larger set (Project.load)
  * @returns {Promise<LoadedIntegration[]>}
  */
 export async function loadIntegrations(
   specs = [],
-  {cwd = process.cwd(), fresh = false} = {},
+  {cwd = process.cwd(), fresh = false, resolveProviders = true} = {},
 ) {
   /** @type {LoadedIntegration[]} */
   const integrations = [];
-  const seen = new Set();
+  const seenSpecs = new Set();
 
   for (const spec of specs) {
-    if (!spec || seen.has(spec)) continue;
-    seen.add(spec);
+    if (!spec || seenSpecs.has(spec)) continue;
+    seenSpecs.add(spec);
 
     const packageDir = resolvePackageDir(spec, cwd);
     const pkgPath = path.join(packageDir, 'package.json');
@@ -371,6 +437,7 @@ export async function loadIntegrations(
       );
     }
 
+    const packageProviderId = providerIdForPackage(pkg.name ?? spec);
     const manifestFile = resolveManifestPath(packageDir, spec);
     let manifest;
     /** @type {string[]} */
@@ -399,6 +466,7 @@ export async function loadIntegrations(
       // discovery loops naturally skip it (no components/templates/codemods).
       integrations.push({
         name: pkg.name ?? spec,
+        ...(packageProviderId == null ? {} : {providerId: packageProviderId}),
         version: pkg.version,
         __spec: spec,
         __packageDir: packageDir,
@@ -408,6 +476,10 @@ export async function loadIntegrations(
       continue;
     }
 
+    const providerId = providerIdForPackage(
+      manifest.providerId ?? pkg.name ?? spec,
+    );
+
     /** @param {string | null | undefined} value */
     const resolveRoot = value => {
       if (value == null) return undefined;
@@ -421,6 +493,7 @@ export async function loadIntegrations(
 
     integrations.push({
       name: pkg.name ?? spec,
+      ...(providerId == null ? {} : {providerId}),
       version: pkg.version,
       components: resolveRoot(manifest.components),
       templates: resolveRoot(manifest.templates),
@@ -441,5 +514,5 @@ export async function loadIntegrations(
     });
   }
 
-  return integrations;
+  return resolveProviders ? markProviderConflicts(integrations) : integrations;
 }