@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/commands/agent-docs.test.mjs

@@ -0,0 +1,551 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  generateCompressedIndex,
+  detectStylingSystem,
+  getXdsVersion,
+  installAgentDocs,
+  injectAgentsMd,
+  injectClaudeMd,
+  injectXdsBlock,
+  removeAgentDocs,
+  removeXdsBlock,
+  discoverAgentDocs,
+  resolveAgentPaths,
+} from './agent-docs.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+  vi.restoreAllMocks();
+});
+
+describe('generateCompressedIndex', () => {
+  it('includes the version number', () => {
+    const result = generateCompressedIndex('1.2.3');
+    expect(result).toContain('Astryx v1.2.3');
+    expect(result).toContain('<!-- ASTRYX:START -->');
+    expect(result).toContain('<!-- ASTRYX:END -->');
+  });
+
+  it('includes theme nudge rule', () => {
+    const result = generateCompressedIndex('1.0.0');
+    expect(result).toMatch(/astryx theme/);
+    expect(result).toMatch(/never override --color-/);
+  });
+
+  it('defaults to the CSS-variable styling path (no compiler)', () => {
+    const result = generateCompressedIndex('1.0.0');
+    expect(result).toMatch(/style\/className with tokens/);
+    expect(result).toMatch(/var\(--color-\*/);
+    // Must NOT push xstyle when no StyleX compiler is present.
+    expect(result).not.toMatch(/xstyle prop/);
+  });
+
+  it('recommends xstyle when StyleX is configured', () => {
+    const result = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});
+    expect(result).toMatch(/xstyle prop \/ StyleX tokens/);
+  });
+
+  it('recommends Tailwind utilities when Tailwind is configured', () => {
+    const result = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
+    expect(result).toMatch(/Tailwind utilities backed by tokens/);
+    expect(result).toMatch(/tailwind-theme\.css/);
+  });
+
+  it('includes upgrade command and migration rule', () => {
+    const result = generateCompressedIndex('1.0.0');
+    expect(result).toContain('upgrade --apply');
+    expect(result).toMatch(/after any @astryxdesign\/core bump/);
+  });
+
+  it('states the runPrefix once in the CLI header', () => {
+    const result = generateCompressedIndex('1.0.0', {runPrefix: 'yarn'});
+    expect(result).toContain('yarn astryx <cmd>');
+    expect(result).not.toContain('npx astryx');
+  });
+
+  it('uses pnpm exec prefix', () => {
+    const result = generateCompressedIndex('1.0.0', {runPrefix: 'pnpm exec'});
+    expect(result).toContain('pnpm exec astryx <cmd>');
+    expect(result).not.toContain('npx astryx');
+  });
+});
+
+describe('detectStylingSystem', () => {
+  function writePkg(deps) {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'x', devDependencies: deps}),
+    );
+  }
+
+  it('defaults to css when no package.json', () => {
+    expect(detectStylingSystem(tmpDir)).toBe('css');
+  });
+
+  it('returns css for a plain project', () => {
+    writePkg({react: '19.0.0', vite: '6.0.0'});
+    expect(detectStylingSystem(tmpDir)).toBe('css');
+  });
+
+  it('detects stylex when the compiler plugin is present', () => {
+    writePkg({'@stylexjs/babel-plugin': '0.0.1'});
+    expect(detectStylingSystem(tmpDir)).toBe('stylex');
+  });
+
+  it('detects tailwind when tailwindcss is present', () => {
+    writePkg({tailwindcss: '4.0.0'});
+    expect(detectStylingSystem(tmpDir)).toBe('tailwind');
+  });
+
+  it('does NOT treat the StyleX runtime alone as a compiler', () => {
+    // Only the runtime, no compiler plugin → must stay on the safe css path.
+    writePkg({'@stylexjs/stylex': '0.0.1'});
+    expect(detectStylingSystem(tmpDir)).toBe('css');
+  });
+
+  it('prefers stylex over tailwind when both are configured', () => {
+    writePkg({'@stylexjs/babel-plugin': '0.0.1', tailwindcss: '4.0.0'});
+    expect(detectStylingSystem(tmpDir)).toBe('stylex');
+  });
+});
+
+describe('getXdsVersion', () => {
+  it('reads version from core package.json', () => {
+    const coreDir = path.join(tmpDir, 'core');
+    fs.mkdirSync(coreDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(coreDir, 'package.json'),
+      JSON.stringify({version: '3.4.5'}),
+    );
+
+    expect(getXdsVersion(coreDir)).toBe('3.4.5');
+  });
+});
+
+describe('injectXdsBlock', () => {
+  it('injects into an existing file without markers', () => {
+    const filePath = path.join(tmpDir, 'test.md');
+    fs.writeFileSync(filePath, '# Existing content\n');
+
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');
+
+    expect(result).toBe(true);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    expect(content).toContain('# Existing content');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+  });
+
+  it('replaces existing markers', () => {
+    const filePath = path.join(tmpDir, 'test.md');
+    fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
+
+    injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    expect(content).toContain('new');
+    expect(content).not.toContain('old');
+    expect(content).toContain('before');
+    expect(content).toContain('after');
+  });
+
+  it('returns false and does not create file when createIfMissing is false', () => {
+    const filePath = path.join(tmpDir, 'nonexistent.md');
+
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->');
+
+    expect(result).toBe(false);
+    expect(fs.existsSync(filePath)).toBe(false);
+  });
+
+  it('skips files without markers when onlyReplace is true', () => {
+    const filePath = path.join(tmpDir, 'test.md');
+    fs.writeFileSync(filePath, '# Existing content\n\nNo XDS markers here.\n');
+
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});
+
+    expect(result).toBe(false);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    expect(content).not.toContain('<!-- ASTRYX:START -->');
+    expect(content).toBe('# Existing content\n\nNo XDS markers here.\n');
+  });
+
+  it('replaces existing markers even when onlyReplace is true', () => {
+    const filePath = path.join(tmpDir, 'test.md');
+    fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
+
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});
+
+    expect(result).toBe(true);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    expect(content).toContain('new');
+    expect(content).not.toContain('old');
+  });
+
+  it('creates file when createIfMissing is true', () => {
+    const filePath = path.join(tmpDir, 'new.md');
+
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->', {
+      createIfMissing: true,
+      header: '# Header',
+    });
+
+    expect(result).toBe(true);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    expect(content).toContain('# Header');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+  });
+});
+
+describe('injectAgentsMd', () => {
+  it('creates new AGENTS.md when none exists', () => {
+    injectAgentsMd(tmpDir, '1.0.0');
+
+    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toContain('# AGENTS.md');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(content).toContain('Astryx v1.0.0');
+    expect(content).toContain('<!-- ASTRYX:END -->');
+  });
+
+  it('updates existing AGENTS.md by replacing XDS markers', () => {
+    const existing = `# My Project
+
+Some content.
+
+<!-- XDS:START -->
+old content
+<!-- XDS:END -->
+
+More stuff.
+`;
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), existing);
+
+    injectAgentsMd(tmpDir, '2.0.0');
+
+    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toContain('Astryx v2.0.0');
+    expect(content).not.toContain('old content');
+    expect(content).toContain('Some content.');
+    expect(content).toContain('More stuff.');
+  });
+
+  it('appends to existing AGENTS.md without markers', () => {
+    const existing = `# My Project
+
+Existing agent docs.
+`;
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), existing);
+
+    injectAgentsMd(tmpDir, '1.0.0');
+
+    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toContain('Existing agent docs.');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(content).toContain('Astryx v1.0.0');
+  });
+});
+
+describe('injectClaudeMd', () => {
+  it('injects into existing CLAUDE.md', () => {
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude Config\n\nExisting rules.\n');
+
+    const result = injectClaudeMd(tmpDir, '1.0.0');
+
+    expect(result).toBe(true);
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('# Claude Config');
+    expect(content).toContain('Existing rules.');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(content).toContain('Astryx v1.0.0');
+  });
+
+  it('does not create CLAUDE.md when it does not exist', () => {
+    const result = injectClaudeMd(tmpDir, '1.0.0');
+
+    expect(result).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'CLAUDE.md'))).toBe(false);
+  });
+
+  it('updates existing markers in CLAUDE.md', () => {
+    const existing = `# Claude Config
+
+<!-- XDS:START -->
+old content
+<!-- XDS:END -->
+
+Other rules.
+`;
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), existing);
+
+    injectClaudeMd(tmpDir, '2.0.0');
+
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('Astryx v2.0.0');
+    expect(content).not.toContain('old content');
+    expect(content).toContain('Other rules.');
+  });
+});
+
+describe('removeAgentDocs', () => {
+  it('removes XDS section from AGENTS.md', () => {
+    const content = `# My Project
+
+Custom content here.
+
+<!-- XDS:START -->
+XDS index stuff
+<!-- XDS:END -->
+
+More custom content.
+`;
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), content);
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    removeAgentDocs(tmpDir);
+
+    const result = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(result).toContain('Custom content here.');
+    expect(result).toContain('More custom content.');
+    expect(result).not.toContain('<!-- XDS:START -->');
+    expect(result).not.toContain('XDS index stuff');
+  });
+
+  it('removes the file entirely when only XDS content remains', () => {
+    const content = `# AGENTS.md
+
+Project-specific guidance for AI coding agents.
+
+<!-- XDS:START -->
+XDS index stuff
+<!-- XDS:END -->
+`;
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), content);
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    removeAgentDocs(tmpDir);
+
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+  });
+
+  it('removes XDS section from CLAUDE.md when present', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'AGENTS.md'),
+      '# AGENTS.md\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '# Claude\n\nRules.\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n\nMore rules.\n',
+    );
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    removeAgentDocs(tmpDir);
+
+    const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(claudeContent).toContain('Rules.');
+    expect(claudeContent).toContain('More rules.');
+    expect(claudeContent).not.toContain('<!-- XDS:START -->');
+  });
+});
+
+describe('installAgentDocs', () => {
+  function setupCorePackage(dir, version = '1.0.0') {
+    // Create a minimal @astryxdesign/core so getXdsVersion works
+    const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(coreDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(coreDir, 'package.json'),
+      JSON.stringify({version}),
+    );
+  }
+
+  it('creates .claude/CLAUDE.md when no agent docs exist', () => {
+    setupCorePackage(tmpDir);
+
+    const written = installAgentDocs(tmpDir);
+
+    expect(written).toEqual(['.claude/CLAUDE.md']);
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+    const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+  });
+
+  it('injects into CLAUDE.md at root when it exists', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules.\n');
+
+    const written = installAgentDocs(tmpDir);
+
+    expect(written).toEqual(['CLAUDE.md']);
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+    const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(claudeContent).toContain('<!-- ASTRYX:START -->');
+    expect(claudeContent).toContain('Project rules.');
+  });
+
+  it('injects into all existing agent doc files', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nAgent rules.\n');
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nClaude rules.\n');
+
+    const written = installAgentDocs(tmpDir);
+
+    expect(written).toContain('AGENTS.md');
+    expect(written).toContain('CLAUDE.md');
+    const agentsContent = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(agentsContent).toContain('<!-- ASTRYX:START -->');
+    expect(claudeContent).toContain('<!-- ASTRYX:START -->');
+  });
+
+  it('updates existing .claude/CLAUDE.md', () => {
+    setupCorePackage(tmpDir);
+    fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '# Project\n\nExisting content.\n');
+
+    const written = installAgentDocs(tmpDir);
+
+    expect(written).toEqual(['.claude/CLAUDE.md']);
+    const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('Existing content.');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+  });
+
+  it('respects --agent claude preset: finds existing CLAUDE.md', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nRules.\n');
+
+    const written = installAgentDocs(tmpDir, {agent: 'claude'});
+
+    expect(written).toEqual(['CLAUDE.md']);
+  });
+
+  it('respects --agent claude preset: creates .claude/CLAUDE.md when nothing exists', () => {
+    setupCorePackage(tmpDir);
+
+    const written = installAgentDocs(tmpDir, {agent: 'claude'});
+
+    expect(written).toEqual(['.claude/CLAUDE.md']);
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);
+  });
+
+  it('respects --agent codex preset: creates AGENTS.md', () => {
+    setupCorePackage(tmpDir);
+
+    const written = installAgentDocs(tmpDir, {agent: 'codex'});
+
+    expect(written).toEqual(['AGENTS.md']);
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
+  });
+
+  it('respects explicit --paths', () => {
+    setupCorePackage(tmpDir);
+
+    const written = installAgentDocs(tmpDir, {paths: ['custom/AGENT.md']});
+
+    expect(written).toEqual(['custom/AGENT.md']);
+    expect(fs.existsSync(path.join(tmpDir, 'custom', 'AGENT.md'))).toBe(true);
+  });
+
+  it('onlyReplace: skips files without XDS markers', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules only.\n');
+
+    const written = installAgentDocs(tmpDir, {onlyReplace: true});
+
+    expect(written).toEqual([]);
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).not.toContain('<!-- ASTRYX:START -->');
+    expect(content).toBe('# Claude\n\nProject rules only.\n');
+  });
+
+  it('onlyReplace: updates files that have XDS markers', () => {
+    setupCorePackage(tmpDir, '2.0.0');
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '# Claude\n\n<!-- XDS:START -->\nPLACEHOLDER_STALE_CONTENT\n<!-- XDS:END -->\n\nOther rules.\n',
+    );
+
+    const written = installAgentDocs(tmpDir, {onlyReplace: true});
+
+    expect(written).toEqual(['CLAUDE.md']);
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('Astryx v2.0.0');
+    expect(content).not.toContain('PLACEHOLDER_STALE_CONTENT');
+    expect(content).toContain('Other rules.');
+  });
+
+  it('onlyReplace: does not create default .claude/CLAUDE.md when nothing exists', () => {
+    setupCorePackage(tmpDir);
+
+    const written = installAgentDocs(tmpDir, {onlyReplace: true});
+
+    expect(written).toEqual([]);
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+  });
+});
+
+describe('discoverAgentDocs', () => {
+  it('finds AGENTS.md and CLAUDE.md at root', () => {
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '');
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');
+
+    const found = discoverAgentDocs(tmpDir);
+
+    expect(found).toContain('AGENTS.md');
+    expect(found).toContain('CLAUDE.md');
+  });
+
+  it('finds .claude/CLAUDE.md', () => {
+    fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '');
+
+    const found = discoverAgentDocs(tmpDir);
+
+    expect(found).toContain('.claude/CLAUDE.md');
+  });
+
+  it('returns empty when nothing exists', () => {
+    expect(discoverAgentDocs(tmpDir)).toEqual([]);
+  });
+});
+
+describe('resolveAgentPaths', () => {
+  it('claude preset finds existing CLAUDE.md at root', () => {
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');
+    const result = resolveAgentPaths(tmpDir, 'claude');
+    expect(result).toEqual({inject: ['CLAUDE.md'], create: []});
+  });
+
+  it('claude preset falls back to .claude/CLAUDE.md', () => {
+    const result = resolveAgentPaths(tmpDir, 'claude');
+    expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});
+  });
+
+  it('all preset discovers existing files', () => {
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '');
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');
+    const result = resolveAgentPaths(tmpDir, 'all');
+    expect(result.inject).toContain('AGENTS.md');
+    expect(result.inject).toContain('CLAUDE.md');
+    expect(result.create).toEqual([]);
+  });
+
+  it('all preset creates defaults when nothing exists', () => {
+    const result = resolveAgentPaths(tmpDir, 'all');
+    expect(result.inject).toEqual([]);
+    expect(result.create).toContain('AGENTS.md');
+    expect(result.create).toContain('.claude/CLAUDE.md');
+  });
+});

package/src/commands/build-theme.import-path.test.mjs

@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for `astryx theme build` install-instructions import paths.
+ *
+ * Covers the relDir-empty case: when the output directory equals the current
+ * working directory, the relative dir is an empty string. Previously this
+ * produced a double-slash import path like `from './/<name>'`. The build now
+ * collapses the prefix to `./` so the emitted import is `from './<name>'`.
+ *
+ * Also covers the non-empty subdir case (`./<sub>/<name>`) to guard against
+ * regressions in the opposite direction.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+const CORE_THEME_ENTRY = path.join(
+  REPO_ROOT,
+  'packages/core/dist/theme/index.js',
+);
+
+function runCli(args, cwd) {
+  try {
+    const out = execFileSync('node', [CLI_BIN, ...args], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0'},
+    });
+    return {code: 0, stdout: out, stderr: ''};
+  } catch (e) {
+    return {
+      code: e.status ?? 1,
+      stdout: e.stdout?.toString() ?? '',
+      stderr: e.stderr?.toString() ?? '',
+    };
+  }
+}
+
+function writeTheme(dir, name) {
+  fs.mkdirSync(dir, {recursive: true});
+  const file = path.join(dir, `${name}.mjs`);
+  fs.writeFileSync(
+    file,
+    `export default { name: ${JSON.stringify(name)}, tokens: { '--color-bg': '#fff' } };\n`,
+  );
+  return file;
+}
+
+// `astryx theme build` imports the compiled @astryxdesign/core/theme entry (there is no
+// in-CLI fallback generator). Build core once if it isn't already present so
+// the suite works in any CI job, regardless of job ordering.
+beforeAll(() => {
+  if (!fs.existsSync(CORE_THEME_ENTRY)) {
+    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
+      cwd: REPO_ROOT,
+      stdio: 'pipe',
+      timeout: 180_000,
+    });
+  }
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-import-path-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build install-instructions import path', () => {
+  it('emits ./<name> (no double slash) when out dir equals cwd', () => {
+    // Source theme lives directly in the project root, so the output dir
+    // is the cwd and the relative dir is an empty string.
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(project, 'cwd-theme');
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+    // No double slash anywhere in the install instructions.
+    expect(result.stdout).not.toContain('.//');
+    // Import + css + link paths all use the clean ./<name> form.
+    expect(result.stdout).toContain("from './cwd-theme'");
+    expect(result.stdout).toContain("import './cwd-theme.css'");
+    expect(result.stdout).toContain('href="./cwd-theme.css"');
+  });
+
+  it('emits ./<sub>/<name> when out dir is a subdirectory of cwd', () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(path.join(project, 'themes'), 'sub-theme');
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).not.toContain('.//');
+    expect(result.stdout).toContain("from './themes/sub-theme'");
+    expect(result.stdout).toContain("import './themes/sub-theme.css'");
+    expect(result.stdout).toContain('href="./themes/sub-theme.css"');
+  });
+});