@expcat/tigercat-cli 1.0.7 → 1.2.0

package/dist/index.js

@@ -3,13 +3,35 @@ 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
 var CLI_NAME = "tigercat";
 var CLI_VERSION = "0.9.0";
 var TEMPLATES = ["vue3", "react"];
+var TEMPLATE_VERSIONS = {
+  // Tigercat packages (use caret on latest major)
+  tigercat: "^1.0.0",
+  // Frameworks
+  vue: "^3.5.33",
+  react: "^19.2.5",
+  reactDom: "^19.2.5",
+  // Build toolchain
+  typescript: "^6.0.3",
+  vite: "^8.0.10",
+  tailwindcss: "^4.2.4",
+  tailwindcssVite: "^4.2.4",
+  // Vite plugins
+  vitejsPluginVue: "^6.0.6",
+  vitejsPluginReact: "^6.0.1",
+  // Type definitions
+  typesReact: "^19.2.14",
+  typesReactDom: "^19.2.3",
+  // Vue-specific
+  vueTsconfig: "^0.9.1",
+  vueTsc: "^3.2.7"
+};
 var COMPONENT_CATEGORIES = {
   basic: [
     "Alert",
@@ -65,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)) {
@@ -123,17 +145,18 @@ function vue3PackageJson(name) {
         preview: "vite preview"
       },
       dependencies: {
-        "@expcat/tigercat-vue": "^0.9.0",
-        vue: "^3.5.26"
+        "@expcat/tigercat-vue": TEMPLATE_VERSIONS.tigercat,
+        vue: TEMPLATE_VERSIONS.vue
       },
       devDependencies: {
-        "@tailwindcss/vite": "^4.1.18",
-        "@vitejs/plugin-vue": "^6.0.3",
-        "@vue/tsconfig": "^0.7.0",
-        tailwindcss: "^4.1.18",
-        typescript: "^5.9.3",
-        vite: "^7.3.0",
-        "vue-tsc": "^2.2.0"
+        "@expcat/tigercat-core": TEMPLATE_VERSIONS.tigercat,
+        "@tailwindcss/vite": TEMPLATE_VERSIONS.tailwindcssVite,
+        "@vitejs/plugin-vue": TEMPLATE_VERSIONS.vitejsPluginVue,
+        "@vue/tsconfig": TEMPLATE_VERSIONS.vueTsconfig,
+        tailwindcss: TEMPLATE_VERSIONS.tailwindcss,
+        typescript: TEMPLATE_VERSIONS.typescript,
+        vite: TEMPLATE_VERSIONS.vite,
+        "vue-tsc": TEMPLATE_VERSIONS.vueTsc
       }
     },
     null,
@@ -145,9 +168,9 @@ function vue3Tsconfig() {
     {
       extends: "@vue/tsconfig/tsconfig.dom.json",
       compilerOptions: {
-        target: "ES2020",
+        target: "ES2022",
         module: "ESNext",
-        lib: ["ES2020", "DOM", "DOM.Iterable"],
+        lib: ["ES2022", "DOM", "DOM.Iterable"],
         skipLibCheck: true,
         moduleResolution: "bundler",
         resolveJsonModule: true,
@@ -204,18 +227,58 @@ createApp(App).mount('#app')
 }
 function vue3App() {
   return `<script setup lang="ts">
-import { Button, Alert } from '@expcat/tigercat-vue'
+import { ref } from 'vue'
+import { Button, Alert, Switch } from '@expcat/tigercat-vue'
+
+const dark = ref(false)
+const modern = ref(true)
+
+function syncRoot() {
+  const root = document.documentElement
+  root.classList.toggle('dark', dark.value)
+  if (modern.value) {
+    root.setAttribute('data-tiger-style', 'modern')
+  } else {
+    root.removeAttribute('data-tiger-style')
+  }
+}
+
+syncRoot()
+
+function toggleDark(v: boolean) {
+  dark.value = v
+  syncRoot()
+}
+
+function toggleModern(v: boolean) {
+  modern.value = v
+  syncRoot()
+}
 </script>
 
 <template>
   <div class="min-h-screen bg-[var(--tiger-surface,#ffffff)] p-8">
-    <h1 class="text-2xl font-bold text-[var(--tiger-text,#111827)] mb-6">
-      Tigercat + Vue 3
-    </h1>
+    <div class="flex items-center justify-between mb-6">
+      <h1 class="text-2xl font-bold text-[var(--tiger-text,#111827)]">
+        Tigercat + Vue 3
+      </h1>
+      <div class="flex items-center gap-4 text-sm text-[var(--tiger-text-muted,#6b7280)]">
+        <label class="flex items-center gap-2">
+          <span>Modern</span>
+          <Switch :checked="modern" size="sm" @update:checked="toggleModern" />
+        </label>
+        <label class="flex items-center gap-2">
+          <span>Dark</span>
+          <Switch :checked="dark" size="sm" @update:checked="toggleDark" />
+        </label>
+      </div>
+    </div>
 
     <div class="space-y-4">
       <Alert variant="info">
         Welcome to your Tigercat project! Edit src/App.vue to get started.
+        Toggle <code>Modern</code> to preview the opt-in modern visual style
+        (radius / shadow / motion tokens).
       </Alert>
 
       <div class="flex gap-2">
@@ -233,38 +296,26 @@ function vue3EnvDts() {
 
 declare module '*.vue' {
   import type { DefineComponent } from 'vue'
-  const component: DefineComponent<{}, {}, any>
+  const component: DefineComponent<{}, {}, unknown>
   export default component
 }
 `;
 }
 function commonStyleCss() {
   return `@import "tailwindcss";
+@plugin "@expcat/tigercat-core/tailwind/modern";
 
-:root {
-  --tiger-primary: #2563eb;
-  --tiger-primary-hover: #1d4ed8;
-  --tiger-surface: #ffffff;
-  --tiger-surface-muted: #f9fafb;
-  --tiger-text: #111827;
-  --tiger-text-muted: #6b7280;
-  --tiger-border: #e5e7eb;
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    --tiger-primary: #3b82f6;
-    --tiger-primary-hover: #2563eb;
-    --tiger-surface: #111827;
-    --tiger-surface-muted: #1f2937;
-    --tiger-text: #f9fafb;
-    --tiger-text-muted: #9ca3af;
-    --tiger-border: #374151;
-  }
+/*
+ * The tigercat tailwind plugin injects every --tiger-* design token for
+ * both light (:root) and dark (.dark) modes, plus the opt-in modern
+ * overrides activated by data-tiger-style="modern". The demo App toggles
+ * dark mode via .dark on <html> and prefers-color-scheme via the rule
+ * below. Swap the @plugin line for a tailwind.config.ts calling
+ * createTigercatPlugin({ preset }) to use a custom preset.
+ */
 
-  html {
-    color-scheme: dark;
-  }
+html {
+  color-scheme: light dark;
 }
 `;
 }
@@ -295,18 +346,19 @@ function reactPackageJson(name) {
         preview: "vite preview"
       },
       dependencies: {
-        "@expcat/tigercat-react": "^0.9.0",
-        react: "^19.2.3",
-        "react-dom": "^19.2.3"
+        "@expcat/tigercat-react": TEMPLATE_VERSIONS.tigercat,
+        react: TEMPLATE_VERSIONS.react,
+        "react-dom": TEMPLATE_VERSIONS.reactDom
       },
       devDependencies: {
-        "@tailwindcss/vite": "^4.1.18",
-        "@types/react": "^19.2.7",
-        "@types/react-dom": "^19.2.2",
-        "@vitejs/plugin-react": "^4.3.4",
-        tailwindcss: "^4.1.18",
-        typescript: "^5.9.3",
-        vite: "^7.3.0"
+        "@expcat/tigercat-core": TEMPLATE_VERSIONS.tigercat,
+        "@tailwindcss/vite": TEMPLATE_VERSIONS.tailwindcssVite,
+        "@types/react": TEMPLATE_VERSIONS.typesReact,
+        "@types/react-dom": TEMPLATE_VERSIONS.typesReactDom,
+        "@vitejs/plugin-react": TEMPLATE_VERSIONS.vitejsPluginReact,
+        tailwindcss: TEMPLATE_VERSIONS.tailwindcss,
+        typescript: TEMPLATE_VERSIONS.typescript,
+        vite: TEMPLATE_VERSIONS.vite
       }
     },
     null,
@@ -317,9 +369,9 @@ function reactTsconfig() {
   return JSON.stringify(
     {
       compilerOptions: {
-        target: "ES2020",
+        target: "ES2022",
         useDefineForClassFields: true,
-        lib: ["ES2020", "DOM", "DOM.Iterable"],
+        lib: ["ES2022", "DOM", "DOM.Iterable"],
         module: "ESNext",
         skipLibCheck: true,
         moduleResolution: "bundler",
@@ -400,18 +452,49 @@ createRoot(document.getElementById('root')!).render(
 `;
 }
 function reactApp() {
-  return `import { Button, Alert } from '@expcat/tigercat-react'
+  return `import { useState, useCallback, useEffect } from 'react'
+import { Button, Alert, Switch } from '@expcat/tigercat-react'
 
 export default function App() {
+  const [dark, setDark] = useState(false)
+  const [modern, setModern] = useState(true)
+
+  useEffect(() => {
+    const root = document.documentElement
+    root.classList.toggle('dark', dark)
+    if (modern) {
+      root.setAttribute('data-tiger-style', 'modern')
+    } else {
+      root.removeAttribute('data-tiger-style')
+    }
+  }, [dark, modern])
+
+  const onDark = useCallback((v: boolean) => setDark(v), [])
+  const onModern = useCallback((v: boolean) => setModern(v), [])
+
   return (
     <div className="min-h-screen bg-[var(--tiger-surface,#ffffff)] p-8">
-      <h1 className="text-2xl font-bold text-[var(--tiger-text,#111827)] mb-6">
-        Tigercat + React
-      </h1>
+      <div className="flex items-center justify-between mb-6">
+        <h1 className="text-2xl font-bold text-[var(--tiger-text,#111827)]">
+          Tigercat + React
+        </h1>
+        <div className="flex items-center gap-4 text-sm text-[var(--tiger-text-muted,#6b7280)]">
+          <label className="flex items-center gap-2">
+            <span>Modern</span>
+            <Switch checked={modern} size="sm" onChange={onModern} />
+          </label>
+          <label className="flex items-center gap-2">
+            <span>Dark</span>
+            <Switch checked={dark} size="sm" onChange={onDark} />
+          </label>
+        </div>
+      </div>
 
       <div className="space-y-4">
         <Alert variant="info">
           Welcome to your Tigercat project! Edit src/App.tsx to get started.
+          Toggle <code>Modern</code> to preview the opt-in modern visual style
+          (radius / shadow / motion tokens).
         </Alert>
 
         <div className="flex gap-2">
@@ -427,42 +510,30 @@ export default function App() {
 }
 function commonStyleCss2() {
   return `@import "tailwindcss";
+@plugin "@expcat/tigercat-core/tailwind/modern";
 
-:root {
-  --tiger-primary: #2563eb;
-  --tiger-primary-hover: #1d4ed8;
-  --tiger-surface: #ffffff;
-  --tiger-surface-muted: #f9fafb;
-  --tiger-text: #111827;
-  --tiger-text-muted: #6b7280;
-  --tiger-border: #e5e7eb;
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    --tiger-primary: #3b82f6;
-    --tiger-primary-hover: #2563eb;
-    --tiger-surface: #111827;
-    --tiger-surface-muted: #1f2937;
-    --tiger-text: #f9fafb;
-    --tiger-text-muted: #9ca3af;
-    --tiger-border: #374151;
-  }
+/*
+ * The tigercat tailwind plugin injects every --tiger-* design token for
+ * both light (:root) and dark (.dark) modes, plus the opt-in modern
+ * overrides activated by data-tiger-style="modern". The demo App toggles
+ * dark mode via .dark on <html> and prefers-color-scheme via the rule
+ * below. Swap the @plugin line for a tailwind.config.ts calling
+ * createTigercatPlugin({ preset }) to use a custom preset.
+ */
 
-  html {
-    color-scheme: dark;
-  }
+html {
+  color-scheme: light dark;
 }
 `;
 }
 
 // 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;
@@ -483,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",
@@ -497,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);
@@ -513,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) {
@@ -529,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 = [];
@@ -542,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) {
@@ -561,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) {
@@ -582,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);
@@ -594,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}'
@@ -621,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;
@@ -647,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");
@@ -670,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;
 }
@@ -734,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)) {
@@ -743,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) {
@@ -753,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 = [
@@ -776,9 +964,533 @@ 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"],
+    templateDeps: ["@tailwindcss/vite", "@vitejs/plugin-vue", "typescript", "vite", "vue-tsc"]
+  },
+  react: {
+    peers: ["@expcat/tigercat-react", "@expcat/tigercat-core", "react", "react-dom"],
+    templateDeps: ["@tailwindcss/vite", "@vitejs/plugin-react", "typescript", "vite"]
+  }
+};
+function createDoctorCommand() {
+  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 = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const packageResult = readProjectPackage(cwd);
+  const nodeVersion = options.nodeVersion ?? process.versions.node;
+  const checks = [createPackageCheck(packageResult)];
+  checks.push(createNodeCheck(nodeVersion));
+  checks.push(createPnpmCheck(packageResult.packageJson, env));
+  if (!packageResult.packageJson) {
+    return checks;
+  }
+  checks.push(createTailwindCheck(packageResult.packageJson));
+  checks.push(createPeerDepsCheck(packageResult.packageJson));
+  checks.push(createTemplateCompatibilityCheck(packageResult.packageJson));
+  checks.push(createCompatibilityMatrixCheck(packageResult.packageJson));
+  return checks;
+}
+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) {
+    printCheck(check);
+  }
+  console.log();
+  const failures = checks.filter((check) => check.status === "fail");
+  const warnings = checks.filter((check) => check.status === "warn");
+  if (failures.length > 0) {
+    logError(`${failures.length} check${failures.length === 1 ? "" : "s"} failed`);
+    process.exit(1);
+  }
+  if (warnings.length > 0) {
+    logWarn2(`${warnings.length} warning${warnings.length === 1 ? "" : "s"} found`);
+    return;
+  }
+  logSuccess("All checks passed");
+}
+function readProjectPackage(cwd) {
+  const packagePath = join(cwd, "package.json");
+  const content = readFileSafe(packagePath);
+  if (!content) {
+    return { packageJson: null, error: `package.json not found in ${cwd}` };
+  }
+  try {
+    return { packageJson: JSON.parse(content) };
+  } catch {
+    return { packageJson: null, error: "package.json is not valid JSON" };
+  }
+}
+function createPackageCheck(result) {
+  if (!result.packageJson) {
+    return {
+      name: "Project package",
+      status: "fail",
+      message: result.error ?? "package.json could not be read",
+      suggestions: ["Run this command from a project root that contains package.json"]
+    };
+  }
+  return {
+    name: "Project package",
+    status: "pass",
+    message: "package.json is readable"
+  };
+}
+function createNodeCheck(version) {
+  const parsed = parseVersion(version);
+  if (!parsed || parsed.major < MIN_NODE_MAJOR) {
+    return {
+      name: "Node.js",
+      status: "fail",
+      message: `Node ${MIN_NODE_MAJOR}+ is required, current version is ${version}`,
+      suggestions: [`Install Node ${MIN_NODE_MAJOR}+ and rerun tigercat doctor`]
+    };
+  }
+  return {
+    name: "Node.js",
+    status: "pass",
+    message: `Node ${version} satisfies >=${MIN_NODE_MAJOR}`
+  };
+}
+function createPnpmCheck(packageJson, env) {
+  const version = getPnpmVersion(packageJson, env);
+  if (!version) {
+    return {
+      name: "pnpm",
+      status: "warn",
+      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);
+  if (!parsed || parsed.major < MIN_PNPM_MAJOR) {
+    return {
+      name: "pnpm",
+      status: "fail",
+      message: `pnpm ${MIN_PNPM_MAJOR}+ is required, detected ${version}`,
+      suggestions: [`Upgrade pnpm to ${MIN_PNPM_MAJOR}+`]
+    };
+  }
+  return {
+    name: "pnpm",
+    status: "pass",
+    message: `pnpm ${version} satisfies >=${MIN_PNPM_MAJOR}`
+  };
+}
+function createTailwindCheck(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+",
+      suggestions: ["Install tailwindcss and @tailwindcss/vite"]
+    };
+  }
+  const tailwindMajor = getRangeMajor(tailwindRange);
+  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}+`,
+      suggestions: [`Upgrade tailwindcss to ${REQUIRED_TAILWIND_MAJOR}+`]
+    };
+  }
+  if (tailwindMajor === null) {
+    return {
+      name: "Tailwind CSS",
+      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+"]
+    };
+  }
+  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}+`,
+      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`]
+    };
+  }
+  return {
+    name: "Tailwind CSS",
+    status: "pass",
+    message: `tailwindcss ${tailwindRange} uses the Tailwind CSS ${REQUIRED_TAILWIND_MAJOR} build pipeline`,
+    details: [`@tailwindcss/vite ${vitePluginRange}`]
+  };
+}
+function createPeerDepsCheck(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",
+      suggestions: ["Install @expcat/tigercat-vue or @expcat/tigercat-react"]
+    };
+  }
+  const missing = [
+    ...new Set(
+      frameworks.flatMap(
+        (framework) => FRAMEWORK_REQUIREMENTS[framework].peers.filter((dependency) => !allDeps[dependency])
+      )
+    )
+  ];
+  const incompatible = frameworks.flatMap(
+    (framework) => FRAMEWORK_REQUIREMENTS[framework].peers.filter((dependency) => dependency.startsWith("@expcat/tigercat-")).filter((dependency) => isOlderMajor(allDeps[dependency], REQUIRED_TIGERCAT_MAJOR)).map((dependency) => `${dependency}@${allDeps[dependency]}`)
+  );
+  if (missing.length > 0 || incompatible.length > 0) {
+    return {
+      name: "Peer dependencies",
+      status: "fail",
+      message: "Tigercat peer dependencies are incomplete or incompatible",
+      details: [...missing.map((dependency) => `Missing ${dependency}`), ...incompatible],
+      suggestions: ["Run tigercat add --install or install the listed dependencies manually"]
+    };
+  }
+  return {
+    name: "Peer dependencies",
+    status: "pass",
+    message: `${frameworks.map(formatFramework).join(" + ")} peer dependencies are present`
+  };
+}
+function createTemplateCompatibilityCheck(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",
+      suggestions: ["Install a Tigercat framework package to enable template compatibility checks"]
+    };
+  }
+  const missing = [
+    ...new Set(
+      frameworks.flatMap(
+        (framework) => FRAMEWORK_REQUIREMENTS[framework].templateDeps.filter((dependency) => !allDeps[dependency])
+      )
+    )
+  ];
+  if (missing.length > 0) {
+    return {
+      name: "Template compatibility",
+      status: "warn",
+      message: "Project differs from current CLI template dependencies",
+      details: missing.map((dependency) => `Template dependency not found: ${dependency}`),
+      suggestions: ["Compare your project dependencies with the latest tigercat create template"]
+    };
+  }
+  return {
+    name: "Template compatibility",
+    status: "pass",
+    message: `${frameworks.map(formatFramework).join(" + ")} template dependencies are present`
+  };
+}
+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,
+    ...packageJson.devDependencies
+  };
+}
+function detectTigercatFrameworks(dependencies) {
+  const frameworks = [];
+  if (dependencies["@expcat/tigercat-vue"]) {
+    frameworks.push("vue3");
+  }
+  if (dependencies["@expcat/tigercat-react"]) {
+    frameworks.push("react");
+  }
+  return frameworks;
+}
+function getPnpmVersion(packageJson, env) {
+  const packageManager = packageJson?.packageManager;
+  if (typeof packageManager === "string") {
+    const match2 = /^pnpm@(.+)$/.exec(packageManager);
+    if (match2) return match2[1];
+  }
+  const userAgent = env.npm_config_user_agent;
+  const match = userAgent ? /pnpm\/(\d+\.\d+\.\d+)/.exec(userAgent) : null;
+  return match?.[1] ?? null;
+}
+function parseVersion(value) {
+  const match = /^(?:v)?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(value.trim());
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2] ?? 0),
+    patch: Number(match[3] ?? 0)
+  };
+}
+function getRangeMajor(range) {
+  if (!range) return null;
+  if (/^(workspace|file|link|catalog):/.test(range)) return null;
+  const match = /(?:\^|~|>=|<=|>|<|=)?\s*v?(\d+)/.exec(range);
+  return match ? Number(match[1]) : null;
+}
+function isOlderMajor(range, expectedMajor) {
+  const major = getRangeMajor(range);
+  return major !== null && major < expectedMajor;
+}
+function formatFramework(framework) {
+  return framework === "vue3" ? "Vue 3" : "React";
+}
+function printCheck(check) {
+  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(`  ${pc2.dim("-")} ${detail}`);
+  }
+  for (const suggestion of check.suggestions ?? []) {
+    console.log(`  ${pc2.dim("fix:")} ${suggestion}`);
+  }
+}
 
 // src/index.ts
 var program = new Command();
@@ -787,4 +1499,5 @@ program.addCommand(createCreateCommand());
 program.addCommand(createAddCommand());
 program.addCommand(createPlaygroundCommand());
 program.addCommand(createGenerateCommand());
+program.addCommand(createDoctorCommand());
 program.parse();