@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/api/init/run/run.mjs

@@ -4,10 +4,12 @@
  * @file init.run leaf — non-interactive project setup + feature installer.
  *
  * `run(options, ctx)` is the default / `--features` / `--all` path behind
- * `astryx init`. It installs the AGENTS.md/CLAUDE.md agent-docs cheat sheet,
- * points at the theme + page-building workflows, and (optionally) scaffolds a
- * starter template — with NO prompts, so it behaves identically for humans,
- * agents, CI, and piped I/O. It performs the side effects and returns an
+ * `astryx init`. It installs the agent-docs cheat sheet at the project root so
+ * every agent reads it (AGENTS.md, a copy in the project's Claude Code file, and
+ * a GEMINI.md import), points at the theme + page-building workflows, and
+ * (optionally) scaffolds a starter template — with NO prompts, so it behaves
+ * identically for humans, agents, CI, and piped I/O. It performs the side
+ * effects and returns an
  * `init.run` receipt. Hard errors (unknown feature/template) throw AstryxError
  * with a stable code. Human output is emitted through the shared `logger`
  * (silent by default) so the CLI keeps its exact plain output and a
@@ -21,8 +23,11 @@ import {PathSafetyError, assertWithin} from '../../../foundation/fs/path-safety.
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
 import {
+  AgentDocsHomeError,
+  assertAgentDocsTarget,
   installAgentDocs,
   renderAgentDocsBlock,
+  agentDocsTargetDir,
 } from '../../../foundation/agent-docs/agent-docs.mjs';
 import {themeTemplate} from '../../theme/template/template.mjs';
 import {listTemplates} from '../../template/template.mjs';
@@ -64,6 +69,24 @@ export function getNextSteps(invocation) {
   ];
 }
 
+/**
+ * Whether two paths name one folder, links resolved.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function sameFolder(a, b) {
+  /** @param {string} p */
+  const real = p => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  return real(a) === real(b);
+}
+
 /**
  * Install the agent-docs block; records the outcome (or soft error) on `data`.
  * Mirrors the CLI's historical soft-error policy: a PathSafetyError surfaces its
@@ -92,14 +115,46 @@ async function applyAgents(cwd, options, invocation, data) {
         ? options.agentDocsPath
         : [options.agentDocsPath]
       : undefined;
-    const renderedBlock = await renderAgentDocsBlock(cwd);
-    const written = installAgentDocs(cwd, {
+    // The docs belong at the project root, not in the subfolder init ran in;
+    // with no project above, they go where init ran, as before. Explicit
+    // --agent-docs-path entries stay relative to where init ran.
+    const root = agentDocsTargetDir(cwd);
+    const targetDir = paths ? cwd : root;
+    // With explicit paths, installAgentDocs checks each file's own folder.
+    if (!paths) assertAgentDocsTarget(targetDir);
+    const renderedBlock = await renderAgentDocsBlock(root);
+    /** @type {string[]} */
+    const skipped = [];
+    const files = installAgentDocs(targetDir, {
       agent: options.agent,
       paths,
       renderedBlock,
+      onSkipped: (rel, reason) => skipped.push(`${rel} (${reason})`),
+      // Below the project root, 0.7.1 wrote in the folder init ran in, so a
+      // project-root file that escapes the project is skipped and reported,
+      // not refused.
+      refuseEscapes: sameFolder(targetDir, cwd),
     });
+    // Each file is reported from where init ran, as before.
+    const written =
+      path.resolve(targetDir) === path.resolve(cwd)
+        ? files
+        : files.map(rel =>
+            path.relative(cwd, path.join(targetDir, rel)).split(path.sep).join('/'),
+          );
     data.docsWritten = written;
     logger.log(`[ok] AI agent docs installed -> ${written.join(', ')}`);
+    // A file 0.7.1 did not write (GEMINI.md, or a project-root file when init
+    // runs below the root) that resolves outside the project is left as it
+    // is, reported in docsError with one note; the exit code stays 0. A file
+    // 0.7.1 wrote whose path escapes the project still fails the run (below).
+    if (skipped.length > 0) {
+      const message =
+        `Left as ${skipped.length === 1 ? 'it is' : 'they are'}: ${skipped.join('; ')}. ` +
+        'To have init write the Astryx block there, make it a regular file inside the project, or copy the block from AGENTS.md by hand.';
+      logger.warn(`Note: ${message}`);
+      data.docsError = {kind: 'install-failed', message};
+    }
   } catch (err) {
     // PathSafetyError carries a precise, user-actionable message — surface it
     // (and flag exit 1) instead of the generic "could not install" warning so
@@ -109,6 +164,14 @@ async function applyAgents(cwd, options, invocation, data) {
       data.docsError = {kind: 'path-safety', message: err.message};
       return;
     }
+    // The home folder, and a settings folder in it outside a project, are
+    // refused: nothing is written, the reason is printed as a note, and the
+    // exit code stays 0.
+    if (err instanceof AgentDocsHomeError) {
+      logger.warn(`Note: ${err.message}`);
+      data.docsError = {kind: 'install-failed', message: err.message};
+      return;
+    }
     logger.error(
       `Could not install agent docs. Try again with \`${invocation} init --features agents\`.`,
     );

package/api/integration/authoring-checks.mjs

@@ -51,6 +51,8 @@ import {
   validateInstalledIntegration,
   validateLocalIntegration,
 } from './validate-integration.mjs';
+import {rootProblem} from '../../foundation/integrations/validate-contributions.mjs';
+import {normalizeProviderId} from '../../foundation/identity/provider-identity.mjs';
 
 /** @param {string} value */
 export function shellArg(value) {
@@ -58,15 +60,61 @@ export function shellArg(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * The provider ID a package without a name is checked under: a valid bare
+ * package name no published package can hold (npm names are lowercase).
+ */
+const UNNAMED_PROVIDER = 'astryx-unnamed-local-package';
+
+/**
+ * A message as the package sees it: the stand-in provider ID gone, its docs
+ * named by their path in the package.
+ * @param {string} message
+ */
+function unnamedShown(message) {
+  return message
+    .split(`${UNNAMED_PROVIDER}/`)
+    .join('')
+    .split(UNNAMED_PROVIDER)
+    .join('this package');
+}
+
 /**
  * Resolve one local or installed integration for an authoring check.
  * @param {string | undefined} pkg
  * @param {string} cwd
  */
 async function resolveIntegration(pkg, cwd) {
-  return pkg
-    ? validateInstalledIntegration(pkg, cwd)
-    : validateLocalIntegration(cwd);
+  const resolved = pkg
+    ? await validateInstalledIntegration(pkg, cwd)
+    : await validateLocalIntegration(cwd);
+  const integration = resolved.found ? resolved.integration : undefined;
+  if (!integration) return resolved;
+  // A root that is not a readable folder is reported in the issues; the
+  // checks read nothing from it rather than fail on it.
+  /** @type {typeof integration & {__unnamed?: boolean}} */
+  const usable = {...integration};
+  // The provider ID readers key the package on: the manifest's providerId,
+  // else its name. A package with neither (validate warned about it) is
+  // still checked; the docs check names its docs under a stand-in ID.
+  try {
+    usable.providerId = normalizeProviderId(
+      integration.__declaredProviderId ?? integration.name,
+    );
+  } catch {
+    usable.__unnamed = true;
+  }
+  for (const kind of /** @type {const} */ ([
+    'components',
+    'templates',
+    'codemods',
+    'docs',
+    'themes',
+  ])) {
+    const root = usable[kind];
+    if (root != null && rootProblem(root)) usable[kind] = undefined;
+  }
+  return {...resolved, integration: usable};
 }
 
 /**
@@ -387,8 +435,20 @@ export async function integrationDocConflicts(pkg, options = {}) {
     };
   }
 
+  // The docs tree names a package's docs by its provider ID, which a
+  // package.json without a name does not give: its docs are checked under a
+  // stand-in ID, which no message names.
+  const unnamed = /** @type {{__unnamed?: boolean}} */ (resolved.integration)
+    .__unnamed;
+  const docsIntegration = unnamed
+    ? {
+        ...resolved.integration,
+        name: UNNAMED_PROVIDER,
+        providerId: UNNAMED_PROVIDER,
+      }
+    : resolved.integration;
   const [discovered, builtinTopics] = await Promise.all([
-    discoverIntegrationDocs(resolved.integration),
+    discoverIntegrationDocs(docsIntegration),
     Promise.resolve(discoverBuiltinTopics()),
   ]);
   const {records, errors} = discovered;
@@ -458,27 +518,40 @@ export async function integrationDocConflicts(pkg, options = {}) {
   // its docs (spec:AST-046, spec:AST-047).
   if (errors.length === 0) {
     for (const {severity, message} of await packageDocsProblems(
-      /** @type {{name: string}} */ (resolved.integration),
+      /** @type {{name: string}} */ (docsIntegration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_graph', severity, message});
+      issues.push({
+        code: 'invalid_doc_graph',
+        severity,
+        message: unnamedShown(message),
+      });
     }
 
     // A reference block includes content rather than linking to it, so one
     // that cannot include what it names loses that content for every reader:
     // an error, where a link that names no doc still prints as written.
     for (const message of await packageReferenceProblems(
-      /** @type {{name: string}} */ (resolved.integration),
+      /** @type {{name: string}} */ (docsIntegration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_reference', severity: 'error', message});
+      issues.push({
+        code: 'invalid_doc_reference',
+        severity: 'error',
+        message: unnamedShown(message),
+      });
     }
 
     // One fact has one owner: a passage two topics repeat goes stale in one
     // of them. Each is listed and is a warning (architecture:cli-surface
     // DEC-8), so `integration check --strict` fails until it is fixed;
     // `doctor integration docs` keeps its exit code, as it fails on errors.
-    copiedPassages.push(...(await integrationCopiedPassages(discovered)));
+    copiedPassages.push(
+      ...(await integrationCopiedPassages(discovered)).map(passage => ({
+        ...passage,
+        message: unnamedShown(passage.message),
+      })),
+    );
     for (const {message} of copiedPassages) {
       issues.push({code: 'copied_passage', severity: 'warning', message});
     }
@@ -488,6 +561,7 @@ export async function integrationDocConflicts(pkg, options = {}) {
       ...(await integrationFluff(discovered)).map(each => ({
         ...each,
         file: fromPackage(each.file),
+        message: unnamedShown(each.message),
       })),
     );
     for (const {message} of fluff) {

package/api/integration/pack-check.mjs

@@ -26,6 +26,11 @@ import {fileURLToPath} from 'node:url';
 import {spawnSync} from 'node:child_process';
 import {assertWithin} from '../../foundation/fs/path-safety.mjs';
 import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs';
+import {
+  literalThemeName,
+  rootProblem,
+  symlinkedFolder,
+} from '../../foundation/integrations/validate-contributions.mjs';
 import {
   componentReplacesCliProblem,
   docsTreeCliProblem,
@@ -953,6 +958,10 @@ async function validatePackedThemeExports(
       );
     }
 
+    // The name the source gives defineTheme, when the file says it: the
+    // build names its files after it.
+    const builtName = literalThemeName(source, localTheme.exportName);
+
     const declaredOutputs = declaredThemeBuildOutputs(
       localIntegration,
       localTheme,
@@ -1097,7 +1106,15 @@ async function validatePackedThemeExports(
                 ? `Theme "${localTheme.slug}" module is not the module \`${formatCliCommand(`theme build ${sourceRelative}`, localIntegration.__packageDir)}\` writes and does not only wrap it: ${localWrapper.reason}. A module that wraps the built module may only import the theme's own stylesheet and font stylesheet for their side effects and re-export from the built module either everything or only its theme, as ${localTheme.exportName}.`
                 : localWrapper && !localWrapper.ok
                   ? `Theme "${localTheme.slug}" module re-exports ${localWrapper.reason}, which does not match ${sourceRelative}. Run \`${formatCliCommand(`theme build ${sourceRelative}`, localIntegration.__packageDir)}\` before packing.`
-                  : `Theme "${localTheme.slug}" ${output.kind} does not match ${sourceRelative}. Run \`${formatCliCommand(`theme build ${sourceRelative}`, localIntegration.__packageDir)}\` before packing.`,
+                  : (renamedOutputMessage(
+                      localTheme,
+                      output.kind,
+                      output.local,
+                      source,
+                      builtName,
+                      localIntegration.__packageDir,
+                    ) ??
+                    `Theme "${localTheme.slug}" ${output.kind} does not match ${sourceRelative}. Run \`${formatCliCommand(`theme build ${sourceRelative}`, localIntegration.__packageDir)}\` before packing.`),
             ),
           );
         }
@@ -1265,7 +1282,17 @@ export async function integrationPackCheck(options = {}) {
   // ── Phase 1: structure validation ──
   const localResult = await validateLocalIntegration(cwd);
   /** @type {Issue[]} */
-  const issues = [...localResult.issues];
+  const issues = [
+    ...localResult.issues,
+    // Validate lists these layout findings without counting them. A
+    // package.json npm cannot pack is what fails the pack here, as it did
+    // before they were named; the rest stay warnings, which fail nothing.
+    ...(localResult.found ? (localResult.listed ?? []) : []).map(issue =>
+      issue.code === 'invalid_package_json'
+        ? {...issue, severity: /** @type {const} */ ('error')}
+        : issue,
+    ),
+  ];
 
   if (!localResult.found || !localResult.integration) {
     return emptyReceipt(pkgName, [
@@ -1314,6 +1341,8 @@ export async function integrationPackCheck(options = {}) {
     );
   }
   for (const root of fileInv.roots) {
+    // A root that is not a readable folder has its own issue.
+    if (rootProblem(/** @type {string} */ (loaded[root.kind]))) continue;
     if (root.files.length === 0) {
       issues.push(
         error(
@@ -1403,6 +1432,9 @@ export async function integrationPackCheck(options = {}) {
   );
   /** @type {string|null} */
   let scratchBase = null;
+  /** @type {string|undefined} the packed copy of the package */
+  let extractDir;
+  const issuesBeforePack = issues.length;
 
   try {
     // npm pack
@@ -1451,11 +1483,16 @@ export async function integrationPackCheck(options = {}) {
     for (const root of fileInv.roots) {
       const missing = root.files.filter(f => !packResult.packedPaths.has(f));
       if (missing.length === root.files.length && root.files.length > 0) {
+        const absolute = /** @type {string} */ (loaded[root.kind]);
+        const link = symlinkedFolder(absolute, packageDir);
         issues.push(
           error(
             'root_not_packed',
             `Declared ${root.kind} root "${root.path}" has 0 of ${root.files.length} expected ` +
-              `files in the pack list. Add "${root.path.replace(/^\.\//, '')}" to "files" in package.json.`,
+              `files in the pack list. ` +
+              (link
+                ? `It is reached through the symlink "${path.relative(packageDir, link.path).split(path.sep).join('/')}", and npm pack does not follow a symlinked folder. Fix: replace the link with the folder itself, or point "${root.kind}" at the folder it links to.`
+                : `Add "${root.path.replace(/^\.\//, '')}" to "files" in package.json.`),
           ),
         );
       } else {
@@ -1494,7 +1531,6 @@ export async function integrationPackCheck(options = {}) {
     }
 
     // ── Phase 3: extract + identity comparison ──
-    let extractDir;
     try {
       extractDir = resolvePackageDir(pkgName, scratchBase);
     } catch (err) {
@@ -1616,11 +1652,94 @@ export async function integrationPackCheck(options = {}) {
       issues,
     );
   } finally {
+    // The packed copy lives in a scratch folder that is gone once this
+    // returns: name its files the way the package does.
+    if (extractDir && scratchBase) {
+      packageRelative(issues.slice(issuesBeforePack), extractDir, scratchBase);
+    }
     removeTreeBestEffort(tgzTmpDir, 'temporary tarball directory', issues);
     removeTreeBestEffort(scratchBase, 'scratch consumer', issues);
   }
 }
 
+/**
+ * When a theme's source names it something other than the file the package
+ * exports for it, a rebuild writes new files under that name and leaves the
+ * exported one stale forever: say so, with both ways out. Null otherwise.
+ * @param {{slug: string}} theme
+ * @param {string} kind 'module' or 'stylesheet'
+ * @param {string} exported the file the package exports for it
+ * @param {string} source the theme's source
+ * @param {string | null} builtName the literal defineTheme name, if any
+ * @param {string} packageDir
+ * @returns {string | null}
+ */
+function renamedOutputMessage(
+  theme,
+  kind,
+  exported,
+  source,
+  builtName,
+  packageDir,
+) {
+  if (builtName == null || builtName === theme.slug) return null;
+  const extension = kind === 'module' ? '.js' : '.css';
+  if (path.basename(exported) === `${builtName}${extension}`) return null;
+  const rel = (/** @type {string} */ file) =>
+    path.relative(packageDir, file).split(path.sep).join('/');
+  const built = rel(
+    path.join(path.dirname(source), `${builtName}${extension}`),
+  );
+  return `Theme "${theme.slug}" ${kind} is ${rel(exported)}, but ${path.basename(source)} calls defineTheme with name: '${builtName}', so \`${formatCliCommand(`theme build ${rel(source)}`, packageDir)}\` writes ${built} instead and rebuilding never updates ${path.basename(exported)}. Fix: point the package export that serves it at ${built} after building, or set name: '${theme.slug}' in ${path.basename(source)} and rebuild.`;
+}
+
+/**
+ * Rewrite the scratch copy's absolute paths in each issue's message: a file
+ * of the packed package as its path in the package, and any other path in the
+ * scratch consumer (such as the module that resolved an import) as that
+ * consumer. Both folders are gone once verify returns.
+ * @param {Issue[]} issues
+ * @param {string} packedDir the packed package inside the scratch consumer
+ * @param {string} consumerDir the scratch consumer
+ */
+function packageRelative(issues, packedDir, consumerDir) {
+  /** @param {string} dir */
+  const spellings = dir => {
+    const out = [dir];
+    try {
+      const real = fs.realpathSync(dir);
+      if (real !== dir) out.push(real);
+    } catch {
+      // Already removed: the plain path is all there is.
+    }
+    return out;
+  };
+  /** @param {string} text */
+  const escape = text => text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const packed = spellings(packedDir);
+  const consumer = spellings(consumerDir);
+  for (const issue of issues) {
+    if (typeof issue.message !== 'string') continue;
+    let message = issue.message;
+    for (const prefix of packed) {
+      message = message
+        .split(`${prefix}${path.sep}`)
+        .join('')
+        .replace(
+          new RegExp(`${escape(prefix)}(?![\\w-]|\\.\\w)`, 'gu'),
+          'the package root',
+        );
+    }
+    for (const prefix of consumer) {
+      message = message.replace(
+        new RegExp(`${escape(prefix)}[^\\s"'\`]*`, 'gu'),
+        'a consumer project',
+      );
+    }
+    issue.message = message;
+  }
+}
+
 /**
  * Assemble the receipt.
  * @param {string} name

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

@@ -580,6 +580,24 @@ describe('a theme module that loads its own styles', () => {
     expect(cli.status, cli.stderr).toBe(0);
   });
 
+  it('says a rebuild cannot fix exports that name the theme after its folder once its source renames it', async () => {
+    writePackage({
+      files: ['astryx.integration.mjs', 'themes'],
+      themeExports: true,
+    });
+    fs.writeFileSync(
+      path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
+      "import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const oceanTheme = defineTheme({name: 'sea'});\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues.map(issue => issue.message)).toEqual([
+      `Theme "ocean" module is themes/ocean/ocean.js, but oceanTheme.ts calls defineTheme with name: 'sea', so \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` writes themes/ocean/sea.js instead and rebuilding never updates ocean.js. Fix: point the package export that serves it at themes/ocean/sea.js after building, or set name: 'ocean' in oceanTheme.ts and rebuild.`,
+      `Theme "ocean" stylesheet is themes/ocean/ocean.css, but oceanTheme.ts calls defineTheme with name: 'sea', so \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` writes themes/ocean/sea.css instead and rebuilding never updates ocean.css. Fix: point the package export that serves it at themes/ocean/sea.css after building, or set name: 'ocean' in oceanTheme.ts and rebuild.`,
+    ]);
+  });
+
   it('compares a partial export set with the module named after the theme', async () => {
     writeRenamedOcean();
     setThemeExports({'./themes/ocean': './themes/ocean/deep-sea.js'});
@@ -1919,6 +1937,75 @@ describe('integrationPackCheck', () => {
     expect(sourceWarnings[0].message).toContain('stray.tsx');
   });
 
+  it('says npm pack skips a symlinked root instead of asking for a "files" entry', async () => {
+    writePackage({
+      manifest:
+        "export default {themes: './themes', components: './components'};\n",
+    });
+    const real = path.join(tmpDir, 'real-components');
+    fs.mkdirSync(real, {recursive: true});
+    fs.writeFileSync(
+      path.join(real, 'Card.doc.mjs'),
+      "export default {type: 'component', name: 'Card', displayName: 'Card', usage: {description: 'Card.'}, props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(real, 'Card.tsx'),
+      'export function Card() { return null; }\n',
+    );
+    fs.symlinkSync('real-components', path.join(tmpDir, 'components'));
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    const codes = result.data.issues.map(issue => issue.code);
+    expect(codes).toContain('symlinked_root');
+    const notPacked = result.data.issues.find(
+      issue => issue.code === 'root_not_packed',
+    );
+    expect(notPacked?.message).toBe(
+      'Declared components root "components" has 0 of 2 expected files in the pack list. It is reached through the symlink "components", and npm pack does not follow a symlinked folder. Fix: replace the link with the folder itself, or point "components" at the folder it links to.',
+    );
+  });
+
+  it('names packed files by their path in the package, never the scratch copy', async () => {
+    writePackage({
+      manifest:
+        "export default {themes: './themes', docs: './docs/a.doc.mjs'};\n",
+    });
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, 'docs', 'a.doc.mjs'), '');
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    const messages = result.data.issues.map(issue => issue.message);
+    expect(messages.join('\n')).not.toContain(
+      path.join(tmpDir, '.astryx-pack-check-'),
+    );
+    expect(messages).toContain(
+      'Packed: Declared docs root is a file, not a folder: docs/a.doc.mjs. Fix: point "docs" in the manifest at the folder that holds them.',
+    );
+    // The root's own issue covers it: no empty-root error, no raw errno.
+    const codes = result.data.issues.map(issue => issue.code);
+    expect(codes).not.toContain('empty_contribution_root');
+    expect(codes).not.toContain('local_discovery_failed');
+    expect(codes).not.toContain('packed_discovery_failed');
+  });
+
+  it('fails on a package.json npm cannot pack, which validate only warns about', async () => {
+    writePackage({files: ['astryx.integration.mjs', 'themes']});
+    const packageFile = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(packageFile, 'utf-8'));
+    delete pkg.name;
+    fs.writeFileSync(packageFile, `${JSON.stringify(pkg, null, 2)}\n`);
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(
+      result.data.issues.map(issue => [issue.code, issue.severity]),
+    ).toEqual([
+      ['invalid_package_json', 'error'],
+      ['pack_failed', 'error'],
+    ]);
+  });
+
   it('cleans up its scratch consumer when npm pack fails', async () => {
     writePackage({
       files: ['astryx.integration.mjs', 'themes'],

package/api/integration/validate-integration-case-disk.test.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A component doc whose file name differs from its source only in
+ * letter case, on a case-insensitive disk (macOS, Windows), where discovery
+ * still pairs the two: a warning naming the rename, not an error. The disk is
+ * simulated by finding the doc's source case-insensitively.
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+vi.mock(
+  '../../foundation/discovery/component-discovery.mjs',
+  async importOriginal => {
+    const original =
+      /** @type {typeof import('../../foundation/discovery/component-discovery.mjs')} */ (
+        await importOriginal()
+      );
+    return {
+      ...original,
+      /** @param {string} docPath */
+      integrationSourceForDoc: docPath => {
+        const dir = path.dirname(docPath);
+        const want = `${path
+          .basename(docPath)
+          .replace(/\.doc\.(ts|mjs|js)$/u, '')}.tsx`.toLowerCase();
+        const found = fs
+          .readdirSync(dir)
+          .find(name => name.toLowerCase() === want);
+        return found ? path.join(dir, found) : null;
+      },
+    };
+  },
+);
+
+const {validateIntegration} = await import('./validate-integration.mjs');
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-case-disk-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('a doc whose name differs from its source only in case, on a case-insensitive disk', () => {
+  it('lists source_without_component_doc with the rename, without an issue', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Acmewidget.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeWidget', displayName: 'AcmeWidget', usage: {description: 'A widget.'}, props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+
+    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
+    expect(data.issues).toEqual([]);
+    expect(data.notes).toEqual([
+      {
+        code: 'source_without_component_doc',
+        message:
+          'Component doc "Acmewidget.doc.mjs" and its source "AcmeWidget.tsx" differ only in letter case. They pair on a case-insensitive disk (macOS, Windows) but not on Linux, where CI and most installs run, so there the component is missing. Fix: rename Acmewidget.doc.mjs to AcmeWidget.doc.mjs.',
+      },
+    ]);
+  });
+
+  it('lists a hidden doc that pairs with its source, without an issue', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Acmewidget.doc.mjs'),
+      "export default {type: 'component',\n  hidden: true,\n  name: 'AcmeWidget', displayName: 'AcmeWidget', usage: {description: 'A widget.'}, props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+
+    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
+    expect(data.issues).toEqual([]);
+    expect(data.notes).toEqual([
+      {
+        code: 'source_without_component_doc',
+        message:
+          'Hidden component doc "Acmewidget.doc.mjs" and its source "AcmeWidget.tsx" differ only in letter case. They pair on a case-insensitive disk (macOS, Windows) but not on Linux, where CI and most installs run. Fix: rename Acmewidget.doc.mjs to AcmeWidget.doc.mjs.',
+      },
+    ]);
+  });
+});