@astryxdesign/cli 0.7.2-canary.caec7ca → 0.7.2-canary.caf5673

package/api/search/search.test.mjs

@@ -616,6 +616,42 @@ describe('search leaf — a theme is found by its names; its description is pros
   );
 });
 
+describe('search leaf — components whose docs live in a family folder', () => {
+  it("indexes a family member from its own entry, not the family's keywords", async () => {
+    // HStack and VStack are documented in Stack's doc, whose keywords
+    // (horizontal, vertical, row, column, ...) describe Stack.
+    const reasons = async (/** @type {string} */ query) =>
+      Object.fromEntries(
+        (await search(query, {cwd, type: 'component'})).data.results.map(r => [
+          r.name,
+          r.reason,
+        ]),
+      );
+    const column = await reasons('column');
+    expect(column.HStack ?? '').not.toMatch(/keyword/);
+    expect(column.VStack ?? '').not.toMatch(/keyword/);
+    expect(column.Stack).toMatch(/keyword/);
+    const vertical = (await search('vertical', {cwd, type: 'component'})).data.results.map(
+      r => r.name,
+    );
+    expect(vertical.indexOf('VStack')).toBeGreaterThanOrEqual(0);
+    if (vertical.includes('HStack')) {
+      expect(vertical.indexOf('VStack')).toBeLessThan(vertical.indexOf('HStack'));
+    }
+  }, SLOW);
+
+  it('ranks VStack, HStack and Heading first for their own names, with their own import', async () => {
+    for (const name of ['VStack', 'HStack', 'Heading']) {
+      const r = await search(name.toLowerCase(), {cwd, type: 'component'});
+      expect(r.data.results[0]).toMatchObject({
+        domain: 'component',
+        name,
+        import: `@astryxdesign/core/${name}`,
+      });
+    }
+  }, SLOW);
+});
+
 describe('search leaf — integration components', () => {
   /**
    * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`
@@ -827,3 +863,142 @@ describe('search — usage guidance is indexed, a tier below description', () =>
     expect(hit?.score).toBe(45);
   });
 });
+
+describe('search leaf — compound names, other names, and word forms', () => {
+  it('finds a compound name typed as separate words inside a longer query', async () => {
+    const {data} = await search('table header cell with sort arrow', {cwd});
+    expect(
+      data.results.slice(0, 3).map(r => r.name),
+    ).toContain('TableHeaderCell');
+  }, SLOW);
+
+  it('finds a one-word keyword typed as separate words', async () => {
+    // MetadataList declares `keyvalue`.
+    const {data} = await search('key value pairs', {cwd});
+    expect(data.results[0]).toMatchObject({
+      domain: 'component',
+      name: 'MetadataList',
+    });
+  }, SLOW);
+
+  it('finds a hook named by its words without the `use` prefix', async () => {
+    const {data} = await search('persisted table column settings', {cwd});
+    expect(data.results[0]).toMatchObject({
+      domain: 'hook',
+      name: 'useTableColumnSettings',
+    });
+  }, SLOW);
+
+  it('reads a camelCase identifier as the words it spells', async () => {
+    const {data} = await search('useTablePaginationState', {cwd});
+    expect(data.results[0]).toMatchObject({
+      domain: 'hook',
+      name: 'useTablePagination',
+    });
+  }, SLOW);
+
+  it('keeps each identifier of a multi-word query whole', async () => {
+    const {data} = await search('ChatMessageList ChatComposer', {cwd});
+    expect(data.results.slice(0, 2).map(r => r.name).sort()).toEqual([
+      'ChatComposer',
+      'ChatMessageList',
+    ]);
+  }, SLOW);
+
+  it("finds a component by another library's name for it", async () => {
+    for (const [q, name] of [
+      ['ScrollArea viewport', 'ScrollableArea'],
+      ['toggle group of buttons', 'ToggleButtonGroup'],
+      ['circular progress for uploads', 'Spinner'],
+    ]) {
+      const {data} = await search(q, {cwd});
+      expect(data.results[0], q).toMatchObject({domain: 'component', name});
+    }
+  }, SLOW);
+
+  it('reads a one-identifier other name as typed', async () => {
+    const {data} = await search('AppHeader', {cwd});
+    expect(data.results[0]).toMatchObject({
+      domain: 'component',
+      name: 'LayoutHeader',
+    });
+  }, SLOW);
+
+  it('adds no near siblings beside an entry the query names outright', async () => {
+    const {data} = await search('top nav mega menu', {cwd});
+    expect(data.results[0]).toMatchObject({name: 'TopNavMegaMenu'});
+    // Its sub-parts start with its name; read joined they would score in the
+    // whole-name tier right under it.
+    const siblings = data.results.filter(
+      r => r.name !== 'TopNavMegaMenu' && r.name.startsWith('TopNavMegaMenu'),
+    );
+    for (const sibling of siblings) expect(sibling.score).toBeLessThan(190);
+  }, SLOW);
+
+  it('ranks an entry the query names above a match on part of another name', async () => {
+    // `table header` names TableHeader; useTableStickyColumns only holds the
+    // words `sticky columns`.
+    const {data} = await search('table header with sticky columns', {cwd});
+    const names = data.results.map(r => r.name);
+    expect(names.indexOf('TableHeader')).toBeLessThan(
+      names.indexOf('useTableStickyColumns') === -1
+        ? Infinity
+        : names.indexOf('useTableStickyColumns'),
+    );
+  }, SLOW);
+
+  it('keeps an entry a query word names by its whole name at its own rank', async () => {
+    // Two words join into TextInput, and TextArea also matches two words
+    // through its joined keyword; one word is still TextArea's whole name.
+    const {data} = await search('text input and textarea with multi line', {
+      cwd,
+    });
+    expect(data.results[0]).toMatchObject({name: 'TextArea'});
+  }, SLOW);
+
+  it('ranks a match on more of the query above a shorter named entry', async () => {
+    const {data} = await search('dropdown menu radio options', {cwd});
+    expect(data.results[0]).toMatchObject({name: 'DropdownMenuRadioItem'});
+  }, SLOW);
+
+  it('lets a plural start a name through its singular', () => {
+    expect(
+      scoreCandidate('tokens', {domain: 'component', name: 'Tokenizer'}),
+    ).toMatchObject({score: 60});
+  });
+
+  it('finds Icon by a glyph name', async () => {
+    for (const q of ['cog', 'lightning bolt']) {
+      const {data} = await search(q, {cwd});
+      expect(data.results[0], q).toMatchObject({
+        domain: 'component',
+        name: 'Icon',
+      });
+    }
+  }, SLOW);
+
+  it('matches a verb form against its verb', () => {
+    // "spacing" lost the final e of "space".
+    expect(
+      scoreCandidate('spacing', {domain: 'component', name: 'Gap', keywords: ['space']}),
+    ).toMatchObject({score: 88});
+    expect(
+      scoreCandidate('dragging', {domain: 'component', name: 'Gap', keywords: ['drag']}),
+    ).toMatchObject({score: 88});
+  });
+
+  it('lets a plural start a longer word through its singular', () => {
+    expect(
+      scoreCandidate('chips', {domain: 'component', name: 'Chipset'}),
+    ).toMatchObject({score: 60});
+    // A four-letter singular is too short: "stats" does not start "statusbar".
+    expect(
+      scoreCandidate('stats', {domain: 'component', name: 'Statusbar'}),
+    ).toBeNull();
+  });
+
+  it('leaves an identifier joined with _ unmatched when nothing has it', async () => {
+    const {data} = await search('qqzz_no_match_here', {cwd});
+    expect(data.results).toEqual([]);
+  }, SLOW);
+});

package/api/swizzle/copy/copy.mjs

@@ -21,8 +21,10 @@ import {checkGhCli} from '../_github.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
 import {
   CORE_PACKAGE,
-  findIntegrationComponentDoc,
-  findIntegrationComponentSource,
+  docStem,
+  findComponentReadme,
+  findIntegrationComponent,
+  unscopedComponentOwners,
 } from '../../../foundation/discovery/component-discovery.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError, writeFailed} from '../../error.mjs';
@@ -126,33 +128,38 @@ async function loadConfigSafely(cwd) {
 
 /**
  * Build the set of OWNER packages that provide a component named `name` across
- * core + every loaded integration.
+ * core + every loaded integration. Core holds every name it documents, but has
+ * source to copy (`sourceDir`) only for a name with its own folder.
  * @param {string} coreDir
  * @param {Array<{name: string, components?: string, issuesUrl?: string}>} loadedIntegrations
  * @param {string} name
  * @param {string|undefined} coreIssuesUrl
- * @returns {Array<{package: string, sourceDir: string|null, ownerPackage: string, issuesUrl: string|undefined}>}
+ * @returns {Array<{package: string, sourceDir: string|null, docPath: string|null, ownerPackage: string, issuesUrl: string|undefined, hold: string}>}
  */
 function resolveOwners(coreDir, loadedIntegrations, name, coreIssuesUrl) {
   const owners = [];
   const coreComponentDir = path.join(coreDir, 'src', name);
-  if (fs.existsSync(coreComponentDir)) {
+  const coreFolder = fs.existsSync(coreComponentDir);
+  if (coreFolder || findComponentReadme(coreDir, name)) {
     owners.push({
       package: CORE_PACKAGE,
-      sourceDir: coreComponentDir,
+      sourceDir: coreFolder ? coreComponentDir : null,
+      docPath: null,
       ownerPackage: CORE_PACKAGE,
       issuesUrl: coreIssuesUrl || DEFAULT_ISSUES_URL,
+      hold: 'core',
     });
   }
   for (const integration of loadedIntegrations) {
-    const docPath = findIntegrationComponentDoc(integration, name);
-    if (!docPath) continue;
-    const sourcePath = findIntegrationComponentSource(integration, name);
+    const found = findIntegrationComponent(integration, name);
+    if (!found) continue;
     owners.push({
       package: integration.name,
-      sourceDir: sourcePath ? path.dirname(sourcePath) : null,
+      sourceDir: found.sourcePath ? path.dirname(found.sourcePath) : null,
+      docPath: found.docPath,
       ownerPackage: integration.name,
       issuesUrl: integration.issuesUrl,
+      hold: found.hold,
     });
   }
   return owners;
@@ -222,25 +229,32 @@ export async function swizzleCopy(component, options = {}) {
     : undefined;
   // An active integration replacement answers to the Core name it replaces,
   // bare or qualified by its own package (spec:AST-035 FR11): copy it under its
-  // own name. `--package @astryxdesign/core` still copies the Core original.
+  // doc's file name, the folder it has always gone to. `--package
+  // @astryxdesign/core` still copies the Core original.
   if (pkg !== CORE_PACKAGE) {
     const replacement = await resolveComponentReplacement(
       coreDir,
       loadedIntegrations,
       dirName,
     );
+    const copyName = replacement ? docStem(replacement.docPath) : null;
     if (
       replacement &&
-      (!pkg || (pkg === replacement.package && replacement.name !== dirName))
+      copyName &&
+      (!pkg || (pkg === replacement.package && copyName !== dirName))
     ) {
-      return swizzleCopy(replacement.name, {
+      return swizzleCopy(copyName, {
         ...options,
         package: replacement.package,
       });
     }
   }
 
-  const allOwners = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+  const found = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+  // The owner rule, then a Core name without its own folder drops out.
+  const allOwners = (pkg ? found : unscopedComponentOwners(found)).filter(
+    owner => owner.package !== CORE_PACKAGE || owner.sourceDir != null,
+  );
 
   if (allOwners.length === 0) {
     throw new AstryxError(

package/api/theme/build/build.family.test.mjs

@@ -13,6 +13,7 @@ import {themeBuild, themeBuildFamily} from './build.mjs';
 import {interceptCore} from './core-interception.mjs';
 import {ensureCoreBuilt} from '../../../clients/cli/commands/ensure-core-built.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 vi.setConfig({testTimeout: 120_000});
 const CLI_ROOT = path.resolve(import.meta.dirname, '../../..');
 const FAMILY_KEY = 'ocean-family';
@@ -252,6 +253,69 @@ describe('themeBuildFamily()', () => {
     expect(fs.existsSync(dtsPath)).toBe(false);
   });
 
+  it('refuses to write family outputs outside cwd, and checks them read-only', async () => {
+    const dir = makeDir();
+    const files = writeFamily(dir).map(file => path.join(dir, file));
+    const app = path.join(dir, 'app');
+    fs.mkdirSync(app);
+
+    await expect(
+      themeBuildFamily(files, {familyKey: FAMILY_KEY}, {cwd: app}),
+    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    const checked = await themeBuildFamily(
+      files,
+      {familyKey: FAMILY_KEY, check: true},
+      {cwd: app},
+    );
+    expect(checked?.type).toBe('theme.build.check');
+    expect(checked?.data.upToDate).toBe(false);
+    // The `.css.d.ts` import stub may be absent in check mode.
+    expect(checked?.data.stale).toEqual(
+      OUTPUTS.filter(file => !file.endsWith('.css.d.ts')).map(file => ({
+        path: `../themes/${file}`,
+        reason: 'missing',
+      })),
+    );
+    for (const output of OUTPUTS) {
+      expect(fs.existsSync(path.join(dir, 'themes', output))).toBe(false);
+    }
+  });
+
+  it('ends a stale family report for outputs outside cwd with a remedy that works', async () => {
+    const dir = makeDir();
+    const files = writeFamily(dir).map(file => path.join(dir, file));
+    const app = path.join(dir, 'app');
+    fs.mkdirSync(app);
+    const family = ['--family', ...files, '--family-key', FAMILY_KEY];
+
+    const stale = await runCli(['theme', 'build', ...family, '--check'], app);
+    expect(stale.code).toBe(1);
+    // The old remedy ran the build from cwd, which refuses these outputs.
+    expect(stale.stderr).not.toContain('Rebuild with:');
+
+    const lines = stale.stderr.split('\n').map(line => line.trim());
+    const runDir = lines.find(line => line.startsWith('cd '))?.slice(3);
+    expect(runDir).toBe(fs.realpathSync(path.join(dir, 'themes')));
+    const stem = `${getCliInvocation(runDir)} theme build `;
+    const [buildArgs, checkArgs] = lines
+      .filter(line => line.startsWith(stem))
+      .map(line => line.slice(stem.length).split(' '));
+    expect(checkArgs).toEqual([...buildArgs, '--check']);
+
+    // Following the remedy builds, and the check from there passes.
+    const built = await runCli(['theme', 'build', ...buildArgs], runDir);
+    expect(built.code).toBe(0);
+    for (const output of OUTPUTS) {
+      expect(fs.existsSync(path.join(dir, 'themes', output))).toBe(true);
+    }
+    const checked = await runCli(
+      ['--json', 'theme', 'build', ...checkArgs],
+      runDir,
+    );
+    expect(checked.code).toBe(0);
+    expect(JSON.parse(checked.stdout).data.upToDate).toBe(true);
+  });
+
   it('fails without publishing a mixed trio when staging a write fails', async () => {
     const dir = makeDir();
     const files = writeFamily(dir);

package/api/theme/build/build.mjs

@@ -27,6 +27,10 @@
  * files; an internal callback lets the CLI make only the process status fail.
  * Human progress is emitted through the shared `logger` (silent by default), so
  * the CLI keeps its exact output while a programmatic caller stays quiet.
+ * Every output a build writes, explicit or beside the theme file, stays inside
+ * `cwd` (`ERR_PATH_TRAVERSAL` otherwise). Check mode writes nothing, so it
+ * compares outputs outside `cwd` read-only; only a relative `out` path that
+ * escapes `cwd` is refused there too.
  *
  * The installed `@astryxdesign/core` is an independently versioned optional
  * peer, so it can be older than the CLI. A theme that uses only baseline
@@ -58,7 +62,10 @@ import {isBuiltin} from 'node:module';
 import {fileURLToPath, pathToFileURL} from 'node:url';
 import {parse} from '@babel/parser';
 import {createJiti} from 'jiti';
-import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {
+  formatCliCommand,
+  getCliInvocation,
+} from '../../../foundation/env/package-manager.mjs';
 import {
   CLI_ROOT,
   findCoreDir,
@@ -270,6 +277,25 @@ function realOrSelf(file) {
   }
 }
 
+/**
+ * `target` spelled through real directories: the deepest ancestor that exists
+ * is resolved through its symlinks, and the missing rest is appended as given.
+ * @param {string} target absolute path
+ * @returns {string}
+ */
+function realLocation(target) {
+  /** @type {string[]} */
+  const missing = [];
+  let existing = target;
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) break;
+    missing.unshift(path.basename(existing));
+    existing = parent;
+  }
+  return path.join(realOrSelf(existing), ...missing);
+}
+
 /**
  * The Core the project at `cwd` installed, when it differs from the one the
  * CLI's own import found and loads. The app's `<Theme>` runs on the app's
@@ -506,6 +532,127 @@ function checkedBuildOutputs(writes, cwd) {
     .map(write => path.relative(cwd, write.dest));
 }
 
+/** Remedies that end a confinement error, by where the output path came from. */
+const OUT_REMEDY = 'Pass an --out path inside it.';
+const SOURCE_REMEDY =
+  'Without --out the outputs go beside the theme file, so run the build from a directory that contains the theme file, or pass an --out path inside the working directory.';
+const FAMILY_REMEDY =
+  "Family outputs go beside the family's root theme file, so run the build from a directory that contains it.";
+
+/**
+ * Refuse an output outside `root`: every write is confined, whether `out` names
+ * the path or it defaults to the theme file's directory (architecture:cli-surface
+ * INV10). Both sides are compared by real location, so an absolute path that
+ * reaches the working directory through a symlink is inside it, and a symlink
+ * inside it that leads elsewhere is not.
+ * @param {string} dest absolute output path
+ * @param {string} root the directory writes stay inside: the working directory
+ * @param {string} remedy what to do instead; ends the error message
+ * @param {string} [shown] the path as the caller wrote it, for the message
+ */
+function confineOutput(dest, root, remedy, shown = dest) {
+  try {
+    assertWithin(realLocation(dest), realOrSelf(path.resolve(root)), {
+      allowAbsolute: true,
+      label: 'output path',
+    });
+  } catch (err) {
+    if (!(err instanceof PathSafetyError)) throw err;
+    throw new AstryxError(
+      err.code === ERROR_CODES.ERR_PATH_TRAVERSAL
+        ? `Output path "${shown}" is outside the working directory (${root}). ${remedy}`
+        : err.message,
+      undefined,
+      ERROR_CODES.ERR_PATH_TRAVERSAL,
+    );
+  }
+}
+
+/** @param {Array<{dest: string}>} writes @param {string} root @param {string} remedy */
+function confineOutputs(writes, root, remedy) {
+  for (const write of writes) confineOutput(write.dest, root, remedy);
+}
+
+/** @param {string} dest absolute output path @param {string} root @returns {boolean} whether a build at `root` refuses to write `dest` */
+function refusedOutput(dest, root) {
+  try {
+    confineOutput(dest, root, '');
+    return false;
+  } catch (err) {
+    if (
+      err instanceof AstryxError &&
+      err.code === ERROR_CODES.ERR_PATH_TRAVERSAL
+    )
+      return true;
+    throw err;
+  }
+}
+
+/** @param {string[]} dirs absolute directories @returns {string | null} the deepest directory containing all of them, or null across roots */
+function commonDirectory(dirs) {
+  let common = dirs[0];
+  for (const dir of dirs.slice(1)) {
+    while (
+      path.relative(common, dir).startsWith('..') ||
+      path.isAbsolute(path.relative(common, dir))
+    ) {
+      const parent = path.dirname(common);
+      if (parent === common) return null;
+      common = parent;
+    }
+  }
+  return common;
+}
+
+/** @param {string} value @returns {string} `value` as one shell word */
+function shellWord(value) {
+  if (/^[A-Za-z0-9@%+=:,./_-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * How a stale check report ends when outputs sit outside the write root. A
+ * build there refuses them, and each output's `Source:` header records the
+ * directory its build ran from, so the build and the check both run from the
+ * nearest directory that contains every theme file and output.
+ * @param {Array<{dest: string}>} writes
+ * @param {string[]} sources absolute theme files the build reads
+ * @param {string} root the directory a build here keeps its writes inside
+ * @param {(relative: (file: string) => string) => string[]} args the arguments after `theme build`, given each path relative to the directory to run from
+ * @returns {string[] | null} report lines, or null when every output is inside `root`
+ */
+function outsideCheckRemedy(writes, sources, root, args) {
+  if (!writes.some(write => refusedOutput(write.dest, root))) return null;
+  const real = (/** @type {string} */ file) => realLocation(path.resolve(file));
+  const dir = commonDirectory([
+    ...sources.map(file => path.dirname(real(file))),
+    ...writes.map(write => path.dirname(real(write.dest))),
+  ]);
+  if (!dir) {
+    return [
+      'These outputs are outside the working directory, so a build here refuses them. Build and check them from one directory that contains the theme files and the outputs.',
+    ];
+  }
+  const command = (/** @type {string[]} */ extra) =>
+    formatCliCommand(
+      [
+        'theme',
+        'build',
+        ...args(file => path.relative(dir, real(file))),
+        ...extra,
+      ]
+        .map(shellWord)
+        .join(' '),
+      dir,
+    );
+  return [
+    'These outputs are outside the working directory, so a build here refuses them, and each output records the directory it was built from. Build and check them from a directory that contains them:',
+    `  cd ${shellWord(dir)}`,
+    `  ${command([])}`,
+    `  ${command(['--check'])}`,
+  ];
+}
+
 /** @param {Array<{dest: string, content: string}>} writes */
 function writeBuildOutputs(writes) {
   if (writes.length === 0) return;
@@ -2344,9 +2491,10 @@ function validateHeadingTypeAugmentationSupport(themeDef) {
  * `logger` (silent by default).
  *
  * @param {string} file - Theme file path, resolved against `cwd`.
- * @param {{out?: string, check?: boolean, iconsSpecifier?: string, __prepareFamily?: boolean, __familyLoader?: any, __familyInterception?: any, __onPrivateVarError?: () => void}} [options] -
+ * @param {{out?: string, check?: boolean, iconsSpecifier?: string, __prepareFamily?: boolean, __familyLoader?: any, __familyInterception?: any, __onPrivateVarError?: () => void, __writeRoot?: string}} [options] -
  *   `out` overrides the output CSS path; `check` compares against on-disk outputs
- *   instead of writing. `iconsSpecifier` overrides the icon registry import
+ *   instead of writing. `__writeRoot` replaces `cwd` as the directory every
+ *   output must stay inside, for a CLI-internal scratch build. `iconsSpecifier` overrides the icon registry import
  *   specifier in the generated module (e.g. `./icons.mjs`); when omitted, the
  *   direct registry specifiers from the theme source are emitted unchanged.
  * @param {{cwd?: string}} [ctx]
@@ -2791,24 +2939,17 @@ async function themeBuildInternal(
   // Derive the default CSS name from the theme name so .css/.js/.d.ts
   // share one scheme; an explicit --out still wins.
   const baseName = themeDef.name;
+  // Every write stays inside cwd. A CLI-internal caller that renders into a
+  // scratch directory it creates and removes names that directory instead.
+  const writeRoot = options.__writeRoot ?? cwd;
   let outPath;
   if (options.out) {
     outPath = path.resolve(cwd, options.out);
-    // Guard: relative paths must not escape cwd via `../`. Absolute paths are
-    // trusted (the user explicitly controls where output goes, like gcc -o).
-    if (!path.isAbsolute(options.out)) {
-      try {
-        assertWithin(options.out, cwd, {label: 'output path'});
-      } catch (err) {
-        if (err instanceof PathSafetyError) {
-          throw new AstryxError(
-            err.message,
-            undefined,
-            ERROR_CODES.ERR_PATH_TRAVERSAL,
-          );
-        }
-        throw err;
-      }
+    // A build keeps the explicit output inside the write root, relative or
+    // absolute. Check mode writes nothing, so it refuses only a relative path
+    // that escapes cwd.
+    if (!options.check || !path.isAbsolute(options.out)) {
+      confineOutput(outPath, writeRoot, OUT_REMEDY, options.out);
     }
   } else {
     outPath = path.join(path.dirname(filePath), `${baseName}.css`);
@@ -2905,6 +3046,13 @@ async function themeBuildInternal(
     writes.push({dest: variantDtsPath, content: variantContent});
   }
 
+  // Every output a build writes stays inside cwd, including the defaults
+  // beside the theme file. Check mode writes nothing, so it compares outputs
+  // outside cwd read-only.
+  if (!options.check) {
+    confineOutputs(writes, writeRoot, options.out ? OUT_REMEDY : SOURCE_REMEDY);
+  }
+
   // Check mode: compare generated content against what's on disk instead of
   // writing. A file is "stale" if it's missing or its content differs once the
   // volatile @generated `Command:` line is ignored. Returns a
@@ -2923,7 +3071,10 @@ async function themeBuildInternal(
           `  ${s.reason === 'missing' ? 'missing' : 'stale'}: ${s.path}`,
         );
       }
-      logger.error(`\n  Rebuild with: ${buildCommand}`);
+      // prettier-ignore
+      const remedy = outsideCheckRemedy(writes, [filePath], writeRoot, relative => [relative(filePath), ...(options.out ? ['--out', relative(outPath)] : []), ...(options.iconsSpecifier ? ['--icons-specifier', options.iconsSpecifier] : [])]);
+      if (remedy) logger.error(`\n  ${remedy.join('\n  ')}`);
+      else logger.error(`\n  Rebuild with: ${buildCommand}`);
     }
     return {
       type: 'theme.build.check',
@@ -3036,7 +3187,7 @@ function printBuildTrailer(trailer) {
   logger.log(`
 Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${trailer.exportName} } from '${trailer.jsImport}';
   import '${trailer.cssImport}';
 
@@ -3046,7 +3197,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours lives
 
 Or with a <link> tag:
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${trailer.exportName} } from '${trailer.jsImport}';
 
   <link rel="stylesheet" href="${trailer.cssImport}" />
@@ -3072,7 +3223,7 @@ export function printBatchTrailer(trailers) {
   logger.log(`
 Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${first.exportName} } from '${first.jsImport}';
   import '${first.cssImport}';
 
@@ -3082,7 +3233,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours lives
 
 Or with a <link> tag:
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${first.exportName} } from '${first.jsImport}';
 
   <link rel="stylesheet" href="${first.cssImport}" />
@@ -3449,6 +3600,8 @@ export async function themeBuildFamily(
     js: path.relative(cwd, jsPath),
     dts: path.relative(cwd, dtsPath),
   };
+  // A family build's outputs stay inside cwd too; check mode only reads them.
+  if (!options.check) confineOutputs(writes, cwd, FAMILY_REMEDY);
   if (options.check) {
     const stale = staleBuildOutputs(writes, cwd);
     const upToDate = stale.length === 0;
@@ -3465,7 +3618,10 @@ export async function themeBuildFamily(
           `  ${entry.reason === 'missing' ? 'missing' : 'stale'}: ${entry.path}`,
         );
       }
-      logger.error(`\n  Rebuild with: ${buildCommand}`);
+      // prettier-ignore
+      const remedy = outsideCheckRemedy(writes, members.map(member => member.filePath), cwd, relative => ['--family', ...members.map(member => relative(member.filePath)), '--family-key', baseName, ...(options.iconsSpecifier ? ['--icons-specifier', options.iconsSpecifier] : [])]);
+      if (remedy) logger.error(`\n  ${remedy.join('\n  ')}`);
+      else logger.error(`\n  Rebuild with: ${buildCommand}`);
     }
     return {
       type: 'theme.build.check',