kigumi 0.12.0 → 0.13.0

package/README.md

@@ -115,20 +115,61 @@ The doctor command checks for:
 
 Useful after upgrading Kigumi CLI, switching tiers (Free↔Pro), or encountering import errors.
 
-### Upgrading
+### `status`
 
-When a new version of Kigumi CLI is released, run:
+Show your project's current configuration at a glance:
 
 ```bash
-# 1. Check for issues — auto-fixes config and shows upgrade instructions
-npx kigumi doctor
+npx kigumi status
+```
+
+### `upgrade`
+
+When a new version of Kigumi CLI is released, see what changed and update your project:
+
+```bash
+npx kigumi upgrade             # Show upgrade guide and update version
+npx kigumi upgrade --dry-run   # Preview changes without modifying config
+```
+
+The upgrade command shows:
+
+- **Version comparison** — your pinned version vs. the CLI version
+- **Web Awesome version changes** — whether the underlying WA dependency changed
+- **Breaking changes** — what changed and how to migrate
+- **Recommended actions** — step-by-step instructions
+
+### `diff`
+
+Compare your installed components against the current templates to see what's changed:
 
-# 2. Follow the doctor's output to update Web Awesome if needed
+```bash
+npx kigumi diff                # Diff all installed components
+npx kigumi diff button card    # Diff specific components
+```
+
+Useful before running `--overwrite` to understand which files have local modifications.
+
+### Version Pinning
+
+Kigumi tracks which CLI version generated your project in `kigumi.config.json`. This ensures you stay on a compatible version and don't accidentally upgrade Web Awesome.
 
-# 3. Regenerate all components from updated templates
-npx kigumi add --all --overwrite
+```bash
+# Pin your project to the current CLI version
+npx kigumi upgrade
+
+# Use a specific CLI version (matches your project)
+npx kigumi@0.12.0 add button
+
+# Check your pinned version
+npx kigumi status
 ```
 
+When the CLI version doesn't match your project:
+
+- **Minor mismatch** (e.g., 0.11 → 0.12): warning, continues normally
+- **Major mismatch** (e.g., 0.x → 1.x): hard error with instructions to upgrade or use the matching version
+
 ### `registry`
 
 Manage community component and theme registries:

package/dist/{chunk-KGQWJAYL.js → chunk-E52EX5AP.js}

@@ -4,7 +4,7 @@ import {
   WEB_AWESOME_FREE_PACKAGE,
   detectTierSync,
   getWebAwesomePackage
-} from "./chunk-3ENVKW5V.js";
+} from "./chunk-VFMTPOZY.js";
 
 // src/output/console.ts
 import * as p from "@clack/prompts";
@@ -366,6 +366,7 @@ var KigumiError = class extends Error {
     if (code >= 400 && code < 500) return 4;
     if (code >= 500 && code < 600) return 5;
     if (code >= 600 && code < 700) return 6;
+    if (code >= 700 && code < 800) return 7;
     return 1;
   }
   /**
@@ -816,6 +817,29 @@ var DependencyInstallError = class extends KigumiError {
   }
 };
 
+// src/errors/version.ts
+var VersionMismatchError = class extends KigumiError {
+  constructor(configVersion, cliVersion) {
+    super(
+      700 /* VERSION_MISMATCH */,
+      `CLI version ${cliVersion} does not match project version ${configVersion}`,
+      { configVersion, cliVersion },
+      [
+        {
+          title: "Use the matching CLI version",
+          steps: [`npx kigumi@${configVersion} add <component>`]
+        },
+        {
+          title: "Or upgrade your project to the current CLI version",
+          steps: [`npx kigumi@${cliVersion} upgrade`]
+        }
+      ]
+    );
+    this.configVersion = configVersion;
+    this.cliVersion = cliVersion;
+  }
+};
+
 // src/errors/index.ts
 function handleError(error, output) {
   const kigumiError = error instanceof KigumiError ? error : UnknownError.from(error);
@@ -1107,7 +1131,9 @@ var installedComponentSchema = z.object({
   source: z.enum(["builtin", "community"]),
   registryUrl: z.string().optional(),
   registryVersion: z.string().optional(),
-  installedAt: z.string().optional()
+  installedAt: z.string().optional(),
+  /** Kigumi CLI version that generated this component */
+  kigumiVersion: z.string().optional()
 });
 var installedThemeSchema = z.object({
   source: z.enum(["builtin", "community"]),
@@ -1130,7 +1156,9 @@ var kigumiConfigSchema = z.object({
   /** Provenance tracking for installed components */
   installedComponents: z.record(z.string(), installedComponentSchema).optional(),
   /** Provenance tracking for installed themes */
-  installedThemes: z.record(z.string(), installedThemeSchema).optional()
+  installedThemes: z.record(z.string(), installedThemeSchema).optional(),
+  /** Kigumi CLI version that initialized/last upgraded this project */
+  kigumiVersion: z.string().optional()
 });
 var DEFAULT_CONFIG2 = {
   framework: "react",
@@ -1380,6 +1408,7 @@ export {
   FrameworkMismatchError,
   CircularDependencyError,
   PreFlightCheckError,
+  VersionMismatchError,
   handleError,
   FRAMEWORKS,
   frameworkSchema,

package/dist/{chunk-3ENVKW5V.js → chunk-VFMTPOZY.js}

@@ -3,6 +3,9 @@ import fs2 from "fs-extra";
 import path2 from "path";
 
 // src/constants.ts
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 var WEB_AWESOME_FREE_PACKAGE = "@awesome.me/webawesome";
 var WEB_AWESOME_PRO_PACKAGE = "@awesome.me/webawesome-pro";
 var WEB_AWESOME_SCOPE = "@awesome.me";
@@ -20,6 +23,12 @@ var GITHUB_RAW_BASE_URL = "https://raw.githubusercontent.com";
 var KIGUMI_CACHE_DIR = ".kigumi/cache";
 var REGISTRY_CACHE_TTL_MS = 36e5;
 var REGISTRY_FILE_NAME = "registry.json";
+var __constants_filename = fileURLToPath(import.meta.url);
+var __constants_dirname = dirname(__constants_filename);
+var __cliPackageJson = JSON.parse(
+  readFileSync(join(__constants_dirname, "..", "package.json"), "utf-8")
+);
+var CLI_VERSION = __cliPackageJson.version;
 
 // src/utils/token.ts
 import fs from "fs-extra";
@@ -218,6 +227,7 @@ export {
   KIGUMI_CACHE_DIR,
   REGISTRY_CACHE_TTL_MS,
   REGISTRY_FILE_NAME,
+  CLI_VERSION,
   detectProTokenSync,
   getTokenSourceSync,
   describeTokenSource,