@expcat/tigercat-cli 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @expcat/tigercat-cli
 
-CLI tooling for the [Tigercat](https://github.com/expcats/Tigercat) UI component library.
+CLI tooling for the [Tigercat](https://github.com/expcat/Tigercat) UI component library.
 
 ## Installation
 
@@ -10,6 +10,84 @@ pnpm add -g @expcat/tigercat-cli
 npx @expcat/tigercat-cli
 ```
 
+## Usage Examples
+
+### Start a Vue 3 project
+
+```bash
+tigercat create admin-console --template vue3
+cd admin-console
+pnpm install
+pnpm dev
+```
+
+Preview the generated file list without writing files:
+
+```bash
+tigercat create admin-console --template vue3 --dry-run
+```
+
+### Start a React project
+
+```bash
+tigercat create design-lab --template react
+cd design-lab
+pnpm install
+pnpm dev
+```
+
+### Add component boilerplate to an existing project
+
+Run from a project that already depends on `@expcat/tigercat-vue` or `@expcat/tigercat-react`:
+
+```bash
+tigercat add Button Form Input Select
+tigercat add --framework vue3 --install --snippet src/tigercat-components.ts
+```
+
+When no component names are provided, `add` opens an interactive multi-select prompt.
+The command prints the correct package import, detects missing peer dependencies,
+can install them with `--install`, and creates `src/components/*Demo.vue` or
+`src/components/*Demo.tsx` files when a `src/components` directory exists.
+
+```bash
+tigercat add Button Form Input Select --dry-run
+```
+
+### Open a temporary playground
+
+```bash
+tigercat playground --template vue3 --port 3456
+tigercat playground --template react --port 3457
+tigercat playground --template react --no-open
+```
+
+Playground files are created under `.tigercat-playground/` in the current working directory.
+
+```bash
+tigercat playground --template react --port 3457 --dry-run
+```
+
+### Generate API docs from type definitions
+
+```bash
+tigercat generate docs --input packages/core/src/types --output docs/api
+tigercat generate docs --input packages/core/src/types --output docs/api --dry-run
+tigercat generate test Button --framework both
+tigercat generate doc-template Button --output docs/components
+```
+
+### Check project compatibility
+
+```bash
+tigercat doctor
+tigercat doctor --json
+```
+
+`doctor` verifies `package.json`, Node.js, pnpm, Tailwind CSS, Tigercat peer dependencies,
+template dependency compatibility, and the supported version compatibility matrix. JSON output is
+designed for CI and automated diagnostics.
+
 ## Commands
 
 ### `tigercat create <name>`
@@ -19,6 +97,7 @@ Create a new project with Tigercat pre-configured.
 ```bash
 tigercat create my-app --template vue3
 tigercat create my-app --template react
+tigercat create my-app --template vue3 --dry-run
 ```
 
 ### `tigercat add <component>`
@@ -28,6 +107,8 @@ Add a component to your project with import boilerplate.
 ```bash
 tigercat add Button
 tigercat add Form Input Select DatePicker
+tigercat add --framework react --install --snippet src/tigercat-components.ts
+tigercat add Button --dry-run
 ```
 
 ### `tigercat playground`
@@ -37,6 +118,8 @@ Launch an interactive playground for testing components.
 ```bash
 tigercat playground
 tigercat playground --template react
+tigercat playground --template react --no-open
+tigercat playground --template react --dry-run
 ```
 
 ### `tigercat generate docs`
@@ -46,6 +129,26 @@ Generate API documentation from component type definitions.
 ```bash
 tigercat generate docs
 tigercat generate docs --output ./docs/api
+tigercat generate docs --output ./docs/api --dry-run
+```
+
+### `tigercat generate test`
+
+Generate Vue and/or React starter test templates for a component.
+
+```bash
+tigercat generate test Button --framework both
+tigercat generate test Button --framework vue3
+tigercat generate test Button --framework react --dry-run
+```
+
+### `tigercat generate doc-template`
+
+Generate a component documentation page template.
+
+```bash
+tigercat generate doc-template Button
+tigercat generate doc-template Button --output docs/components --dry-run
 ```
 
 ### `tigercat doctor`
@@ -54,6 +157,7 @@ Check whether the current project has compatible Node, pnpm, Tailwind CSS, Tiger
 
 ```bash
 tigercat doctor
+tigercat doctor --json
 ```
 
 ## Windows Support
@@ -67,11 +171,11 @@ with backslash paths, paths containing spaces, and UNC paths.
 When installed globally or locally, each package manager creates platform-specific shims
 so that `tigercat` can be invoked directly from PowerShell, CMD, or Git Bash:
 
-| Package manager | Global install                        | Shim files created               |
-| --------------- | ------------------------------------- | -------------------------------- |
-| **pnpm**        | `pnpm add -g @expcat/tigercat-cli`    | `tigercat.cmd`, `tigercat` (sh)  |
-| **npm**         | `npm i -g @expcat/tigercat-cli`       | `tigercat.cmd`, `tigercat` (sh), `tigercat.ps1` |
-| **bun**         | `bun add -g @expcat/tigercat-cli`     | `tigercat.cmd`, `tigercat` (sh)  |
+| Package manager | Global install                     | Shim files created                              |
+| --------------- | ---------------------------------- | ----------------------------------------------- |
+| **pnpm**        | `pnpm add -g @expcat/tigercat-cli` | `tigercat.cmd`, `tigercat` (sh)                 |
+| **npm**         | `npm i -g @expcat/tigercat-cli`    | `tigercat.cmd`, `tigercat` (sh), `tigercat.ps1` |
+| **bun**         | `bun add -g @expcat/tigercat-cli`  | `tigercat.cmd`, `tigercat` (sh)                 |
 
 For local (non-global) installs, run via `npx tigercat`, `pnpm exec tigercat`, or
 `bunx tigercat`. The `#!/usr/bin/env node` shebang in the built output is used by all

package/dist/index.js

@@ -3,7 +3,7 @@ import { Command } from 'commander';
 import prompts from 'prompts';
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { resolve, join, dirname, basename } from 'path';
-import pc from 'picocolors';
+import pc2 from 'picocolors';
 import { execSync } from 'child_process';
 
 // src/constants.ts
@@ -87,19 +87,19 @@ var COMPONENT_CATEGORIES = {
 };
 var ALL_COMPONENTS = Object.values(COMPONENT_CATEGORIES).flat();
 function logSuccess(msg) {
-  console.log(pc.green("\u2714") + " " + msg);
+  console.log(pc2.green("\u2714") + " " + msg);
 }
 function logInfo(msg) {
-  console.log(pc.blue("\u2139") + " " + msg);
+  console.log(pc2.blue("\u2139") + " " + msg);
 }
-function logWarn(msg) {
-  console.log(pc.yellow("\u26A0") + " " + msg);
+function logWarn2(msg) {
+  console.log(pc2.yellow("\u26A0") + " " + msg);
 }
 function logError(msg) {
-  console.error(pc.red("\u2716") + " " + msg);
+  console.error(pc2.red("\u2716") + " " + msg);
 }
 function logStep(step, total, msg) {
-  console.log(pc.dim(`[${step}/${total}]`) + " " + msg);
+  console.log(pc2.dim(`[${step}/${total}]`) + " " + msg);
 }
 function ensureDir(dir) {
   if (!existsSync(dir)) {
@@ -296,7 +296,7 @@ function vue3EnvDts() {
 
 declare module '*.vue' {
   import type { DefineComponent } from 'vue'
-  const component: DefineComponent<{}, {}, any>
+  const component: DefineComponent<{}, {}, unknown>
   export default component
 }
 `;
@@ -529,11 +529,11 @@ html {
 
 // src/commands/create.ts
 function createCreateCommand() {
-  return new Command("create").argument("<name>", "Project name").option("-t, --template <template>", "Project template (vue3 | react)").description("Create a new project with Tigercat pre-configured").action(async (name, opts) => {
-    await runCreate(name, opts.template);
+  return new Command("create").argument("<name>", "Project name").option("-t, --template <template>", "Project template (vue3 | react)").option("--dry-run", "Preview files without writing them").description("Create a new project with Tigercat pre-configured").action(async (name, opts) => {
+    await runCreate(name, opts.template, Boolean(opts.dryRun));
   });
 }
-async function runCreate(name, templateArg) {
+async function runCreate(name, templateArg, dryRun = false) {
   let template;
   if (templateArg && TEMPLATES.includes(templateArg)) {
     template = templateArg;
@@ -554,7 +554,7 @@ async function runCreate(name, templateArg) {
     template = response.template;
   }
   const targetDir = resolve(process.cwd(), name);
-  if (existsSync(targetDir) && !isDirEmpty(targetDir)) {
+  if (!dryRun && existsSync(targetDir) && !isDirEmpty(targetDir)) {
     const { overwrite } = await prompts({
       type: "confirm",
       name: "overwrite",
@@ -568,6 +568,13 @@ async function runCreate(name, templateArg) {
   }
   logInfo(`Creating ${template} project in ${targetDir}...`);
   const files = template === "vue3" ? getVue3Template(name) : getReactTemplate(name);
+  if (dryRun) {
+    logInfo("Dry run: no files will be written.");
+    for (const filePath of Object.keys(files)) {
+      console.log(`  ${filePath}`);
+    }
+    return;
+  }
   const totalSteps = Object.keys(files).length;
   let step = 0;
   ensureDir(targetDir);
@@ -584,8 +591,8 @@ async function runCreate(name, templateArg) {
   console.log("  pnpm dev\n");
 }
 function createAddCommand() {
-  return new Command("add").argument("<components...>", "Component names to add (e.g. Button Input Select)").description("Add component import boilerplate to your project").action(async (components) => {
-    await runAdd(components);
+  return new Command("add").argument("[components...]", "Component names to add (e.g. Button Input Select)").option("-f, --framework <framework>", "Framework override (vue3 | react)").option("--install", "Install missing Tigercat dependencies before generating snippets").option("--snippet <file>", "Generate a reusable import snippet file").option("--dry-run", "Preview generated demo files without writing them").description("Add component import boilerplate to your project").action(async (components, opts) => {
+    await runAdd(components ?? [], opts);
   });
 }
 function detectFramework(cwd) {
@@ -600,6 +607,45 @@ function detectFramework(cwd) {
   }
   return null;
 }
+function normalizeFramework(value) {
+  if (value === "vue3" || value === "react") return value;
+  return null;
+}
+async function resolveComponents(components) {
+  if (components.length > 0) return components;
+  const response = await prompts({
+    type: "multiselect",
+    name: "components",
+    message: "Select components to add",
+    choices: ALL_COMPONENTS.map((component) => ({ title: component, value: component })),
+    min: 1
+  });
+  return response.components ?? [];
+}
+function collectDependencies(framework) {
+  return framework === "vue3" ? ["@expcat/tigercat-vue", "@expcat/tigercat-core", "vue"] : ["@expcat/tigercat-react", "@expcat/tigercat-core", "react", "react-dom"];
+}
+function readPackageDeps(cwd) {
+  const pkg = readFileSafe(join(cwd, "package.json"));
+  if (!pkg) return {};
+  try {
+    const parsed = JSON.parse(pkg);
+    return { ...parsed.dependencies, ...parsed.devDependencies, ...parsed.peerDependencies };
+  } catch {
+    return {};
+  }
+}
+function detectPackageManager(cwd) {
+  if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+function formatAddCommand(packageManager, dependencies) {
+  const deps = dependencies.join(" ");
+  if (packageManager === "yarn") return `yarn add ${deps}`;
+  if (packageManager === "npm") return `npm install ${deps}`;
+  return `pnpm add ${deps}`;
+}
 function validateComponents(names) {
   const valid = [];
   const invalid = [];
@@ -613,18 +659,20 @@ function validateComponents(names) {
   }
   return { valid, invalid };
 }
-async function runAdd(components) {
+async function runAdd(components, options = {}) {
   const cwd = process.cwd();
-  const framework = detectFramework(cwd);
+  const framework = normalizeFramework(options.framework) ?? detectFramework(cwd);
+  const dryRun = Boolean(options.dryRun);
   if (!framework) {
     logError(
       "Could not detect framework. Make sure you are in a project with @expcat/tigercat-vue or @expcat/tigercat-react installed."
     );
     process.exit(1);
   }
-  const { valid, invalid } = validateComponents(components);
+  const selectedComponents = await resolveComponents(components);
+  const { valid, invalid } = validateComponents(selectedComponents);
   if (invalid.length > 0) {
-    logWarn(`Unknown components: ${invalid.join(", ")}`);
+    logWarn2(`Unknown components: ${invalid.join(", ")}`);
     logInfo(`Available: ${ALL_COMPONENTS.join(", ")}`);
   }
   if (valid.length === 0) {
@@ -632,11 +680,34 @@ async function runAdd(components) {
     process.exit(1);
   }
   const pkgName = framework === "vue3" ? "@expcat/tigercat-vue" : "@expcat/tigercat-react";
+  const requiredDeps = collectDependencies(framework);
+  const installedDeps = readPackageDeps(cwd);
+  const missingDeps = requiredDeps.filter((dependency) => !installedDeps[dependency]);
+  if (missingDeps.length > 0) {
+    const packageManager = detectPackageManager(cwd);
+    const installCommand = formatAddCommand(packageManager, missingDeps);
+    if (options.install && !dryRun) {
+      logInfo(`Installing missing dependencies: ${missingDeps.join(", ")}`);
+      execSync(installCommand, { cwd, stdio: "inherit" });
+    } else {
+      logInfo(`Missing dependencies detected. Run: ${installCommand}`);
+    }
+  }
   const importLine = `import { ${valid.join(", ")} } from '${pkgName}'`;
   logSuccess(`Add this import to your project:
 `);
   console.log(`  ${importLine}
 `);
+  if (options.snippet) {
+    const snippetFile = resolve(cwd, options.snippet);
+    const snippet = generateImportSnippet(valid, pkgName);
+    if (dryRun) {
+      logInfo(`Would create import snippet ${snippetFile}`);
+    } else {
+      writeFileSafe(snippetFile, snippet);
+      logSuccess(`Created import snippet ${snippetFile}`);
+    }
+  }
   if (framework === "vue3") {
     logInfo("Vue 3 usage example:\n");
     for (const comp of valid) {
@@ -653,11 +724,18 @@ async function runAdd(components) {
   if (!existsSync(sampleDir)) {
     return;
   }
+  if (dryRun) {
+    logInfo("Dry run: no demo files will be written.");
+  }
   for (const comp of valid) {
     const ext = framework === "vue3" ? "vue" : "tsx";
     const sampleFile = join(sampleDir, `${comp}Demo.${ext}`);
     if (existsSync(sampleFile)) {
-      logWarn(`${sampleFile} already exists, skipping`);
+      logWarn2(`${sampleFile} already exists, skipping`);
+      continue;
+    }
+    if (dryRun) {
+      logInfo(`Would create ${sampleFile}`);
       continue;
     }
     const content = framework === "vue3" ? generateVue3Demo(comp, pkgName) : generateReactDemo(comp, pkgName);
@@ -665,6 +743,14 @@ async function runAdd(components) {
     logSuccess(`Created ${sampleFile}`);
   }
 }
+function generateImportSnippet(components, pkg) {
+  return `import { ${components.join(", ")} } from '${pkg}'
+
+export const tigercatComponents = {
+${components.map((component) => `  ${component}`).join(",\n")}
+}
+`;
+}
 function generateVue3Demo(component, pkg) {
   return `<script setup lang="ts">
 import { ${component} } from '${pkg}'
@@ -692,11 +778,11 @@ export default function ${component}Demo() {
 `;
 }
 function createPlaygroundCommand() {
-  return new Command("playground").option("-t, --template <template>", "Framework template (vue3 | react)").option("-p, --port <port>", "Dev server port", "3456").description("Launch an interactive playground for testing components").action(async (opts) => {
-    await runPlayground(opts.template, opts.port);
+  return new Command("playground").option("-t, --template <template>", "Framework template (vue3 | react)").option("-p, --port <port>", "Dev server port", "3456").option("--no-open", "Do not open the playground in the default browser").option("--dry-run", "Preview playground setup without writing files or starting Vite").description("Launch an interactive playground for testing components").action(async (opts) => {
+    await runPlayground(opts.template, opts.port, opts.open !== false, Boolean(opts.dryRun));
   });
 }
-async function runPlayground(templateArg, port = "3456") {
+async function runPlayground(templateArg, port = "3456", open = true, dryRun = false) {
   let template;
   if (templateArg && TEMPLATES.includes(templateArg)) {
     template = templateArg;
@@ -718,6 +804,19 @@ async function runPlayground(templateArg, port = "3456") {
   }
   const tmpDir = resolve(process.cwd(), ".tigercat-playground");
   const projectDir = join(tmpDir, `playground-${template}`);
+  if (dryRun) {
+    const safePort = /^\d+$/.test(port) ? port : "3456";
+    logInfo(`Dry run: would prepare ${template} playground in ${projectDir}.`);
+    if (!existsSync(projectDir)) {
+      const files = template === "vue3" ? getVue3Template("playground") : getReactTemplate("playground");
+      for (const filePath of Object.keys(files)) {
+        console.log(`  ${filePath}`);
+      }
+      logInfo("Would run pnpm install");
+    }
+    logInfo(`Would start Vite on port ${safePort}${open ? " and open the browser" : ""}`);
+    return;
+  }
   if (!existsSync(projectDir)) {
     logInfo(`Setting up ${template} playground...`);
     const files = template === "vue3" ? getVue3Template("playground") : getReactTemplate("playground");
@@ -741,14 +840,23 @@ async function runPlayground(templateArg, port = "3456") {
 `);
   try {
     const safePort = /^\d+$/.test(port) ? port : "3456";
-    execSync(`npx vite --port ${safePort}`, { cwd: projectDir, stdio: "inherit" });
+    const openFlag = open ? " --open" : "";
+    execSync(`npx vite --port ${safePort}${openFlag}`, { cwd: projectDir, stdio: "inherit" });
   } catch {
   }
 }
 function createGenerateCommand() {
   const cmd = new Command("generate").description("Code generation utilities");
-  cmd.command("docs").option("-i, --input <dir>", "Types directory", "packages/core/src/types").option("-o, --output <dir>", "Output directory", "docs/api").description("Generate API documentation from component type definitions").action(async (opts) => {
-    await runGenerateDocs(opts.input, opts.output);
+  cmd.command("docs").option("-i, --input <dir>", "Types directory", "packages/core/src/types").option("-o, --output <dir>", "Output directory", "docs/api").option("--dry-run", "Preview generated docs without writing files").description("Generate API documentation from component type definitions").action(async (opts) => {
+    await runGenerateDocs(opts.input, opts.output, Boolean(opts.dryRun));
+  });
+  cmd.command("test <component>").option("-f, --framework <framework>", "Target framework (vue3 | react | both)", "both").option("-o, --output <dir>", "Tests root directory", "tests").option("--dry-run", "Preview generated test files without writing files").description("Generate starter test templates for a component").action(
+    async (component, opts) => {
+      await runGenerateTest(component, opts.framework, opts.output, Boolean(opts.dryRun));
+    }
+  );
+  cmd.command("doc-template <component>").option("-o, --output <dir>", "Documentation output directory", "docs/components").option("--dry-run", "Preview generated documentation without writing files").description("Generate a component documentation page template").action(async (component, opts) => {
+    await runGenerateDocTemplate(component, opts.output, Boolean(opts.dryRun));
   });
   return cmd;
 }
@@ -805,7 +913,7 @@ function generateMarkdown(doc) {
   }
   return lines.join("\n");
 }
-async function runGenerateDocs(inputDir, outputDir) {
+async function runGenerateDocs(inputDir, outputDir, dryRun = false) {
   const resolvedInput = resolve(process.cwd(), inputDir);
   const resolvedOutput = resolve(process.cwd(), outputDir);
   if (!existsSync(resolvedInput)) {
@@ -814,7 +922,11 @@ async function runGenerateDocs(inputDir, outputDir) {
   }
   const files = readdirSync(resolvedInput).filter((f) => f.endsWith(".ts") && f !== "index.ts").sort();
   logInfo(`Found ${files.length} type files in ${inputDir}`);
-  ensureDir(resolvedOutput);
+  if (dryRun) {
+    logInfo("Dry run: no documentation files will be written.");
+  } else {
+    ensureDir(resolvedOutput);
+  }
   const docs = [];
   let step = 0;
   for (const file of files) {
@@ -824,7 +936,12 @@ async function runGenerateDocs(inputDir, outputDir) {
     if (doc) {
       docs.push(doc);
       const md = generateMarkdown(doc);
-      writeFileSafe(join(resolvedOutput, `${doc.fileName}.md`), md);
+      const outputPath = join(resolvedOutput, `${doc.fileName}.md`);
+      if (dryRun) {
+        logInfo(`Would generate ${outputPath}`);
+      } else {
+        writeFileSafe(outputPath, md);
+      }
     }
   }
   const indexLines = [
@@ -847,13 +964,184 @@ async function runGenerateDocs(inputDir, outputDir) {
     }
     indexLines.push("");
   }
-  writeFileSafe(join(resolvedOutput, "index.md"), indexLines.join("\n"));
+  const indexPath = join(resolvedOutput, "index.md");
+  if (dryRun) {
+    logInfo(`Would generate ${indexPath}`);
+    logSuccess(`Dry run completed for ${docs.length} component docs in ${outputDir}`);
+    return;
+  }
+  writeFileSafe(indexPath, indexLines.join("\n"));
   logSuccess(`Generated docs for ${docs.length} components in ${outputDir}`);
 }
+async function runGenerateTest(component, frameworkArg, outputDir, dryRun = false) {
+  const componentName = normalizeComponentName(component);
+  if (!componentName) {
+    logError(`Unknown component: ${component}`);
+    process.exit(1);
+  }
+  const framework = normalizeFrameworkTarget(frameworkArg);
+  if (!framework) {
+    logError(`Unknown framework target: ${frameworkArg}. Use vue3, react, or both.`);
+    process.exit(1);
+  }
+  const targets = framework === "both" ? ["vue3", "react"] : [framework];
+  for (const target of targets) {
+    const ext = target === "vue3" ? "ts" : "tsx";
+    const folder = target === "vue3" ? "vue" : "react";
+    const filePath = resolve(process.cwd(), outputDir, folder, `${componentName}.spec.${ext}`);
+    const content = target === "vue3" ? generateVueTest(componentName) : generateReactTest(componentName);
+    if (existsSync(filePath)) {
+      logWarn(`${filePath} already exists, skipping`);
+      continue;
+    }
+    if (dryRun) {
+      logInfo(`Would generate ${filePath}`);
+      continue;
+    }
+    writeFileSafe(filePath, content);
+    logSuccess(`Generated ${filePath}`);
+  }
+}
+async function runGenerateDocTemplate(component, outputDir, dryRun = false) {
+  const componentName = normalizeComponentName(component);
+  if (!componentName) {
+    logError(`Unknown component: ${component}`);
+    process.exit(1);
+  }
+  const fileName = `${componentName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()}.md`;
+  const filePath = resolve(process.cwd(), outputDir, fileName);
+  const content = generateComponentDocTemplate(componentName);
+  if (existsSync(filePath)) {
+    logWarn(`${filePath} already exists, skipping`);
+    return;
+  }
+  if (dryRun) {
+    logInfo(`Would generate ${filePath}`);
+    return;
+  }
+  writeFileSafe(filePath, content);
+  logSuccess(`Generated ${filePath}`);
+}
+function normalizeComponentName(component) {
+  return ALL_COMPONENTS.find((name) => name.toLowerCase() === component.toLowerCase()) ?? null;
+}
+function normalizeFrameworkTarget(value) {
+  if (value === "vue3" || value === "react" || value === "both") return value;
+  return null;
+}
+function generateVueTest(component) {
+  return `/**
+ * @vitest-environment happy-dom
+ */
+
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/vue'
+import { ${component} } from '@expcat/tigercat-vue'
+import { expectNoA11yViolationsIsolated } from '../utils'
+
+describe('${component}', () => {
+  it('renders without crashing', () => {
+    const { container } = render(${component}, {
+      attrs: { 'data-testid': '${component.toLowerCase()}' }
+    })
+
+    expect(screen.getByTestId('${component.toLowerCase()}')).toBeInTheDocument()
+    expect(container.firstElementChild).toBeTruthy()
+  })
+
+  describe('a11y', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(${component})
+      await expectNoA11yViolationsIsolated(container)
+    })
+  })
+
+  describe('Edge Cases', () => {
+    it('keeps rendering with empty props', () => {
+      const { container } = render(${component})
+      expect(container.firstElementChild).toBeTruthy()
+    })
+  })
+})
+`;
+}
+function generateReactTest(component) {
+  return `/**
+ * @vitest-environment happy-dom
+ */
+
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import React from 'react'
+import { ${component} } from '@expcat/tigercat-react'
+import { expectNoA11yViolationsIsolated } from '../utils/react'
+
+describe('${component}', () => {
+  it('renders without crashing', () => {
+    const { container } = render(<${component} data-testid="${component.toLowerCase()}" />)
+
+    expect(screen.getByTestId('${component.toLowerCase()}')).toBeInTheDocument()
+    expect(container.firstElementChild).toBeTruthy()
+  })
+
+  describe('a11y', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(<${component} />)
+      await expectNoA11yViolationsIsolated(container)
+    })
+  })
+
+  describe('Edge Cases', () => {
+    it('keeps rendering with empty props', () => {
+      const { container } = render(<${component} />)
+      expect(container.firstElementChild).toBeTruthy()
+    })
+  })
+})
+`;
+}
+function generateComponentDocTemplate(component) {
+  return `# ${component}
+
+## Overview
+
+Describe the user-facing purpose and primary workflow for ${component}.
+
+## Import
+
+\`\`\`ts
+import { ${component} } from '@expcat/tigercat-vue'
+import { ${component} } from '@expcat/tigercat-react'
+\`\`\`
+
+## Basic Usage
+
+Add one minimal Vue example and one minimal React example from \`skills/tigercat/references\`.
+
+## Props
+
+Keep this section aligned with \`packages/core/src/types\` and regenerate API docs after changes.
+
+## Accessibility
+
+Document keyboard behavior, roles, labels, and focus management.
+
+## Edge Cases
+
+List boundary states, empty states, loading states, and controlled/uncontrolled behavior.
+`;
+}
 var MIN_NODE_MAJOR = 20;
 var MIN_PNPM_MAJOR = 8;
 var REQUIRED_TAILWIND_MAJOR = 4;
 var REQUIRED_TIGERCAT_MAJOR = 1;
+var VERSION_COMPATIBILITY_MATRIX = [
+  { name: "Node.js", range: ">=20.11.0", reason: "Matches workspace engines and CLI templates" },
+  { name: "pnpm", range: ">=8.0.0", reason: "Required by workspace package management" },
+  { name: "Tailwind CSS", range: ">=4.0.0", reason: "Required by Tigercat theme utilities" },
+  { name: "Vue", range: "^3.0.0", reason: "Peer range for @expcat/tigercat-vue" },
+  { name: "React", range: "^19.0.0", reason: "Peer range for @expcat/tigercat-react" }
+];
 var FRAMEWORK_REQUIREMENTS = {
   vue3: {
     peers: ["@expcat/tigercat-vue", "@expcat/tigercat-core", "vue"],
@@ -865,8 +1153,8 @@ var FRAMEWORK_REQUIREMENTS = {
   }
 };
 function createDoctorCommand() {
-  return new Command("doctor").description("Check whether the current project is compatible with Tigercat").action(() => {
-    runDoctor();
+  return new Command("doctor").option("--json", "Print structured JSON output").description("Check whether the current project is compatible with Tigercat").action((opts) => {
+    runDoctor(Boolean(opts.json));
   });
 }
 function collectDoctorChecks(options = {}) {
@@ -883,10 +1171,28 @@ function collectDoctorChecks(options = {}) {
   checks.push(createTailwindCheck(packageResult.packageJson));
   checks.push(createPeerDepsCheck(packageResult.packageJson));
   checks.push(createTemplateCompatibilityCheck(packageResult.packageJson));
+  checks.push(createCompatibilityMatrixCheck(packageResult.packageJson));
   return checks;
 }
-function runDoctor() {
+function runDoctor(json = false) {
   const checks = collectDoctorChecks();
+  if (json) {
+    const failures2 = checks.filter((check) => check.status === "fail");
+    const warnings2 = checks.filter((check) => check.status === "warn");
+    console.log(
+      JSON.stringify(
+        {
+          status: failures2.length > 0 ? "fail" : warnings2.length > 0 ? "warn" : "pass",
+          checks,
+          compatibilityMatrix: VERSION_COMPATIBILITY_MATRIX
+        },
+        null,
+        2
+      )
+    );
+    if (failures2.length > 0) process.exit(1);
+    return;
+  }
   logInfo("Running Tigercat project checks...");
   console.log();
   for (const check of checks) {
@@ -900,7 +1206,7 @@ function runDoctor() {
     process.exit(1);
   }
   if (warnings.length > 0) {
-    logWarn(`${warnings.length} warning${warnings.length === 1 ? "" : "s"} found`);
+    logWarn2(`${warnings.length} warning${warnings.length === 1 ? "" : "s"} found`);
     return;
   }
   logSuccess("All checks passed");
@@ -922,7 +1228,8 @@ function createPackageCheck(result) {
     return {
       name: "Project package",
       status: "fail",
-      message: result.error ?? "package.json could not be read"
+      message: result.error ?? "package.json could not be read",
+      suggestions: ["Run this command from a project root that contains package.json"]
     };
   }
   return {
@@ -937,7 +1244,8 @@ function createNodeCheck(version) {
     return {
       name: "Node.js",
       status: "fail",
-      message: `Node ${MIN_NODE_MAJOR}+ is required, current version is ${version}`
+      message: `Node ${MIN_NODE_MAJOR}+ is required, current version is ${version}`,
+      suggestions: [`Install Node ${MIN_NODE_MAJOR}+ and rerun tigercat doctor`]
     };
   }
   return {
@@ -952,7 +1260,8 @@ function createPnpmCheck(packageJson, env) {
     return {
       name: "pnpm",
       status: "warn",
-      message: `Could not detect pnpm version; Tigercat templates expect pnpm ${MIN_PNPM_MAJOR}+`
+      message: `Could not detect pnpm version; Tigercat templates expect pnpm ${MIN_PNPM_MAJOR}+`,
+      suggestions: ["Add packageManager: pnpm@10.26.2 to package.json or run through pnpm"]
     };
   }
   const parsed = parseVersion(version);
@@ -960,7 +1269,8 @@ function createPnpmCheck(packageJson, env) {
     return {
       name: "pnpm",
       status: "fail",
-      message: `pnpm ${MIN_PNPM_MAJOR}+ is required, detected ${version}`
+      message: `pnpm ${MIN_PNPM_MAJOR}+ is required, detected ${version}`,
+      suggestions: [`Upgrade pnpm to ${MIN_PNPM_MAJOR}+`]
     };
   }
   return {
@@ -970,55 +1280,75 @@ function createPnpmCheck(packageJson, env) {
   };
 }
 function createTailwindCheck(packageJson) {
-  const allDeps = collectDependencies(packageJson);
+  const allDeps = collectDependencies2(packageJson);
   const tailwindRange = allDeps.tailwindcss;
   const vitePluginRange = allDeps["@tailwindcss/vite"];
   if (!tailwindRange) {
     return {
       name: "Tailwind CSS",
       status: "fail",
-      message: "tailwindcss is missing; Tigercat requires Tailwind CSS 4+"
+      message: "tailwindcss is missing; Tigercat requires Tailwind CSS 4+",
+      suggestions: ["Install tailwindcss and @tailwindcss/vite"]
     };
   }
   const tailwindMajor = getRangeMajor(tailwindRange);
-  const pluginMajor = vitePluginRange ? getRangeMajor(vitePluginRange) : null;
   if (tailwindMajor !== null && tailwindMajor < REQUIRED_TAILWIND_MAJOR) {
     return {
       name: "Tailwind CSS",
       status: "fail",
-      message: `tailwindcss ${tailwindRange} is not compatible; use Tailwind CSS ${REQUIRED_TAILWIND_MAJOR}+`
+      message: `tailwindcss ${tailwindRange} is not compatible; use Tailwind CSS ${REQUIRED_TAILWIND_MAJOR}+`,
+      suggestions: [`Upgrade tailwindcss to ${REQUIRED_TAILWIND_MAJOR}+`]
     };
   }
   if (tailwindMajor === null) {
     return {
       name: "Tailwind CSS",
-      status: "warn",
-      message: `Could not verify tailwindcss range ${tailwindRange}; expected ${REQUIRED_TAILWIND_MAJOR}+`
+      status: "fail",
+      message: `Could not verify tailwindcss range ${tailwindRange}; Tigercat builds with Tailwind CSS ${REQUIRED_TAILWIND_MAJOR}+ only`,
+      suggestions: [`Use an explicit Tailwind CSS ${REQUIRED_TAILWIND_MAJOR}+ semver range`]
+    };
+  }
+  if (!vitePluginRange) {
+    return {
+      name: "Tailwind CSS",
+      status: "fail",
+      message: "@tailwindcss/vite is required; Tigercat builds with Tailwind CSS 4 only",
+      suggestions: ["Install @tailwindcss/vite 4+"]
     };
   }
-  if (vitePluginRange && pluginMajor !== null && pluginMajor < REQUIRED_TAILWIND_MAJOR) {
+  const pluginMajor = getRangeMajor(vitePluginRange);
+  if (pluginMajor !== null && pluginMajor < REQUIRED_TAILWIND_MAJOR) {
     return {
       name: "Tailwind CSS",
       status: "fail",
-      message: `@tailwindcss/vite ${vitePluginRange} is not compatible; use ${REQUIRED_TAILWIND_MAJOR}+`
+      message: `@tailwindcss/vite ${vitePluginRange} is not compatible; use ${REQUIRED_TAILWIND_MAJOR}+`,
+      suggestions: [`Upgrade @tailwindcss/vite to ${REQUIRED_TAILWIND_MAJOR}+`]
+    };
+  }
+  if (pluginMajor === null) {
+    return {
+      name: "Tailwind CSS",
+      status: "fail",
+      message: `Could not verify @tailwindcss/vite range ${vitePluginRange}; Tigercat builds with Tailwind CSS ${REQUIRED_TAILWIND_MAJOR}+ only`,
+      suggestions: [`Use an explicit @tailwindcss/vite ${REQUIRED_TAILWIND_MAJOR}+ semver range`]
     };
   }
-  const details = vitePluginRange ? [`@tailwindcss/vite ${vitePluginRange}`] : ["@tailwindcss/vite is recommended for Vite templates"];
   return {
     name: "Tailwind CSS",
-    status: vitePluginRange ? "pass" : "warn",
-    message: `tailwindcss ${tailwindRange} satisfies Tigercat requirements`,
-    details
+    status: "pass",
+    message: `tailwindcss ${tailwindRange} uses the Tailwind CSS ${REQUIRED_TAILWIND_MAJOR} build pipeline`,
+    details: [`@tailwindcss/vite ${vitePluginRange}`]
   };
 }
 function createPeerDepsCheck(packageJson) {
-  const allDeps = collectDependencies(packageJson);
+  const allDeps = collectDependencies2(packageJson);
   const frameworks = detectTigercatFrameworks(allDeps);
   if (frameworks.length === 0) {
     return {
       name: "Peer dependencies",
       status: "warn",
-      message: "No Tigercat Vue or React package was detected"
+      message: "No Tigercat Vue or React package was detected",
+      suggestions: ["Install @expcat/tigercat-vue or @expcat/tigercat-react"]
     };
   }
   const missing = [
@@ -1036,7 +1366,8 @@ function createPeerDepsCheck(packageJson) {
       name: "Peer dependencies",
       status: "fail",
       message: "Tigercat peer dependencies are incomplete or incompatible",
-      details: [...missing.map((dependency) => `Missing ${dependency}`), ...incompatible]
+      details: [...missing.map((dependency) => `Missing ${dependency}`), ...incompatible],
+      suggestions: ["Run tigercat add --install or install the listed dependencies manually"]
     };
   }
   return {
@@ -1046,13 +1377,14 @@ function createPeerDepsCheck(packageJson) {
   };
 }
 function createTemplateCompatibilityCheck(packageJson) {
-  const allDeps = collectDependencies(packageJson);
+  const allDeps = collectDependencies2(packageJson);
   const frameworks = detectTigercatFrameworks(allDeps);
   if (frameworks.length === 0) {
     return {
       name: "Template compatibility",
       status: "warn",
-      message: "Skipped because no supported Tigercat framework package was detected"
+      message: "Skipped because no supported Tigercat framework package was detected",
+      suggestions: ["Install a Tigercat framework package to enable template compatibility checks"]
     };
   }
   const missing = [
@@ -1067,7 +1399,8 @@ function createTemplateCompatibilityCheck(packageJson) {
       name: "Template compatibility",
       status: "warn",
       message: "Project differs from current CLI template dependencies",
-      details: missing.map((dependency) => `Template dependency not found: ${dependency}`)
+      details: missing.map((dependency) => `Template dependency not found: ${dependency}`),
+      suggestions: ["Compare your project dependencies with the latest tigercat create template"]
     };
   }
   return {
@@ -1076,7 +1409,29 @@ function createTemplateCompatibilityCheck(packageJson) {
     message: `${frameworks.map(formatFramework).join(" + ")} template dependencies are present`
   };
 }
-function collectDependencies(packageJson) {
+function createCompatibilityMatrixCheck(packageJson) {
+  const dependencies = collectDependencies2(packageJson);
+  const details = VERSION_COMPATIBILITY_MATRIX.map(
+    (item) => `${item.name} ${item.range} - ${item.reason}`
+  );
+  const frameworks = detectTigercatFrameworks(dependencies);
+  if (frameworks.length === 0) {
+    return {
+      name: "Version compatibility matrix",
+      status: "warn",
+      message: "Framework-specific matrix checks were skipped",
+      details,
+      suggestions: ["Install a Tigercat Vue or React package to validate framework peer ranges"]
+    };
+  }
+  return {
+    name: "Version compatibility matrix",
+    status: "pass",
+    message: `${frameworks.map(formatFramework).join(" + ")} compatibility matrix is available`,
+    details
+  };
+}
+function collectDependencies2(packageJson) {
   return {
     ...packageJson.peerDependencies,
     ...packageJson.dependencies,
@@ -1126,11 +1481,14 @@ function formatFramework(framework) {
   return framework === "vue3" ? "Vue 3" : "React";
 }
 function printCheck(check) {
-  const symbol = check.status === "pass" ? pc.green("\u2714") : check.status === "warn" ? pc.yellow("\u26A0") : pc.red("\u2716");
-  const name = pc.bold(check.name);
+  const symbol = check.status === "pass" ? pc2.green("\u2714") : check.status === "warn" ? pc2.yellow("\u26A0") : pc2.red("\u2716");
+  const name = pc2.bold(check.name);
   console.log(`${symbol} ${name}: ${check.message}`);
   for (const detail of check.details ?? []) {
-    console.log(`  ${pc.dim("-")} ${detail}`);
+    console.log(`  ${pc2.dim("-")} ${detail}`);
+  }
+  for (const suggestion of check.suggestions ?? []) {
+    console.log(`  ${pc2.dim("fix:")} ${suggestion}`);
   }
 }
 

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@expcat/tigercat-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "CLI tooling for Tigercat UI library — project scaffolding, component generation, and more",
   "license": "MIT",
   "author": "Yizhe Wang",
   "repository": {
     "type": "git",
-    "url": "https://github.com/expcats/Tigercat.git",
+    "url": "https://github.com/expcat/Tigercat",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/expcats/Tigercat#readme",
+  "homepage": "https://github.com/expcat/Tigercat#readme",
   "bugs": {
-    "url": "https://github.com/expcats/Tigercat/issues"
+    "url": "https://github.com/expcat/Tigercat/issues"
   },
   "keywords": [
     "tigercat",