feat

zbeyens · zbeyens · commit 1c30ea3d4499 · 2026-04-17T17:18:20.000+02:00
diff --git a/.changeset/fix-auth-env-runner.md b/.changeset/fix-auth-env-runner.md
@@ -6,3 +6,4 @@
 
 - Fix auth env sync and local auth bootstrap so `kitcn add auth`, `kitcn env push`, and `kitcn dev --bootstrap` use the real Convex CLI entrypoint more reliably across runtimes and platforms.
 - Fix `kitcn init -t <next|start|vite>` custom shadcn preset exits so they stop with a clear rerun instruction instead of crashing while patching scaffold files.
+- Improve `kitcn init -t <next|start|vite>` fresh scaffolds by syncing the shadcn wrapper to `shadcn@4.3.0` and regenerating the starter outputs against the latest upstream template contract.
diff --git a/docs/solutions/workflow-issues/shadcn-pin-bumps-must-sync-scaffold-doubles-and-starters-20260417.md b/docs/solutions/workflow-issues/shadcn-pin-bumps-must-sync-scaffold-doubles-and-starters-20260417.md
@@ -0,0 +1,89 @@
+---
+title: shadcn pin bumps must sync scaffold doubles and starters
+date: 2026-04-17
+category: workflow-issues
+module: init-scaffolds
+problem_type: workflow_issue
+component: tooling
+symptoms:
+  - "`packages/kitcn/src/cli/backend-core.ts` still pins an older `shadcn@x.y.z` while upstream starters have already moved on"
+  - "Local scaffold doubles in `packages/kitcn/src/cli/test-utils.ts` keep passing init tests even though fresh upstream scaffold output has changed"
+  - "`fixtures:sync` and scenario lanes become the first place real drift shows up"
+root_cause: missing_workflow_step
+resolution_type: code_fix
+severity: medium
+tags:
+  - shadcn
+  - scaffolding
+  - fixtures
+  - scenarios
+  - parity
+  - test-doubles
+---
+
+# shadcn pin bumps must sync scaffold doubles and starters
+
+## Problem
+
+`kitcn` wraps shadcn scaffolding in two places:
+
+- the real CLI pin used by `init -t`
+- fake scaffold output used by local tests
+
+If those move separately, the repo starts lying. Unit tests still pass against
+stale fake output while fresh scaffold generation and runtime scenarios follow a
+different upstream contract.
+
+## Symptoms
+
+- The pinned `INIT_SHADCN_PACKAGE_SPEC` lags behind the upstream release range.
+- Starter package versions and `components.json` fields drift from the current
+  shadcn template contract.
+- `fixtures:sync`, `fixtures:check`, or prepared scenario apps expose drift
+  that targeted unit tests missed.
+
+## What Didn't Work
+
+- Bumping only the shadcn version pin is incomplete. It leaves fake scaffold
+  output frozen in old template assumptions.
+- Updating only the local doubles is also incomplete. It keeps committed
+  starters and runtime scenarios on the wrong upstream release.
+
+## Solution
+
+Treat the shadcn pin, the scaffold doubles, and the committed starters as one
+contract.
+
+When bumping shadcn:
+
+1. Update the real `INIT_SHADCN_PACKAGE_SPEC`.
+2. Sync local scaffold doubles in `packages/kitcn/src/cli/test-utils.ts` to the
+   same upstream starter shape.
+3. Refresh committed starters with `bun run fixtures:sync`.
+4. Prove they still match with `bun run fixtures:check`.
+5. Run runtime scenario proof for the affected template lanes.
+
+For the `4.0.1 -> 4.3.0` bump, that meant syncing starter dependency versions,
+monorepo root metadata, and shadcn-owned `components.json` fields like
+`iconLibrary`.
+
+## Why This Works
+
+The real scaffold pin decides what users get. The local doubles decide what the
+tests believe users get.
+
+Keeping both on the same upstream release removes the false-green state where:
+
+- unit tests validate stale fake output
+- fixture regeneration rewrites half the repo
+- scenario lanes become the first honest signal
+
+## Prevention
+
+- Never treat a shadcn version bump as a one-line constant change.
+- If `init -t` owns a scaffold lane, its fake output in test helpers must match
+  the same upstream release.
+- After every scaffold contract bump, run both fixture lanes and at least the
+  relevant runtime scenarios before calling it done.
+- If fresh fixtures change more than expected, assume the local doubles are
+  stale until proven otherwise.
diff --git a/fixtures/next-auth/app/layout.tsx b/fixtures/next-auth/app/layout.tsx
@@ -5,10 +5,7 @@ import { ThemeProvider } from "@/components/theme-provider"
 import { cn } from "@/lib/utils";
 import { Providers } from "@/components/providers";
 
-const fontSans = Geist({
-  subsets: ["latin"],
-  variable: "--font-sans",
-})
+const geist = Geist({subsets:['latin'],variable:'--font-sans'})
 
 const fontMono = Geist_Mono({
   subsets: ["latin"],
@@ -24,7 +21,7 @@ export default function RootLayout({
     <html
       lang="en"
       suppressHydrationWarning
-      className={cn("antialiased", fontMono.variable, "font-sans", fontSans.variable)}
+      className={cn("antialiased", fontMono.variable, "font-sans", geist.variable)}
     >
       <body>
         <ThemeProvider><Providers>{children}</Providers></ThemeProvider>
diff --git a/fixtures/next-auth/package.json b/fixtures/next-auth/package.json
@@ -10,7 +10,7 @@
     "hono": "4.12.9",
     "kitcn": "workspace:*",
     "lucide-react": "^1.8.0",
-    "next": "16.1.6",
+    "next": "16.1.7",
     "next-themes": "^0.4.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
@@ -22,16 +22,16 @@
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3",
-    "@tailwindcss/postcss": "^4.1.18",
-    "@types/node": "^25.1.0",
-    "@types/react": "^19.2.10",
+    "@tailwindcss/postcss": "^4.2.1",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "eslint": "^9.39.2",
-    "eslint-config-next": "16.1.6",
+    "eslint": "^9.39.4",
+    "eslint-config-next": "16.1.7",
     "prettier": "^3.8.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "postcss": "^8",
-    "tailwindcss": "^4.1.18",
+    "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3",
     "@types/bun": "latest",
     "@concavejs/cli": "latest"
diff --git a/fixtures/next/app/layout.tsx b/fixtures/next/app/layout.tsx
@@ -5,10 +5,7 @@ import { ThemeProvider } from "@/components/theme-provider"
 import { cn } from "@/lib/utils";
 import { Providers } from "@/components/providers";
 
-const fontSans = Geist({
-  subsets: ["latin"],
-  variable: "--font-sans",
-})
+const geist = Geist({subsets:['latin'],variable:'--font-sans'})
 
 const fontMono = Geist_Mono({
   subsets: ["latin"],
@@ -24,7 +21,7 @@ export default function RootLayout({
     <html
       lang="en"
       suppressHydrationWarning
-      className={cn("antialiased", fontMono.variable, "font-sans", fontSans.variable)}
+      className={cn("antialiased", fontMono.variable, "font-sans", geist.variable)}
     >
       <body>
         <ThemeProvider><Providers>{children}</Providers></ThemeProvider>
diff --git a/fixtures/next/package.json b/fixtures/next/package.json
@@ -9,7 +9,7 @@
     "hono": "4.12.9",
     "kitcn": "workspace:*",
     "lucide-react": "^1.8.0",
-    "next": "16.1.6",
+    "next": "16.1.7",
     "next-themes": "^0.4.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
@@ -21,16 +21,16 @@
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3",
-    "@tailwindcss/postcss": "^4.1.18",
-    "@types/node": "^25.1.0",
-    "@types/react": "^19.2.10",
+    "@tailwindcss/postcss": "^4.2.1",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "eslint": "^9.39.2",
-    "eslint-config-next": "16.1.6",
+    "eslint": "^9.39.4",
+    "eslint-config-next": "16.1.7",
     "prettier": "^3.8.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "postcss": "^8",
-    "tailwindcss": "^4.1.18",
+    "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3",
     "@types/bun": "latest",
     "@concavejs/cli": "latest"
diff --git a/fixtures/start-auth/package.json b/fixtures/start-auth/package.json
@@ -3,14 +3,14 @@
     "@base-ui/react": "^1.4.0",
     "@fontsource-variable/geist": "^5.2.8",
     "@opentelemetry/api": "1.9.0",
-    "@tailwindcss/vite": "^4.1.18",
-    "@tanstack/react-devtools": "^0.7.0",
+    "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/react-devtools": "^0.10.0",
     "@tanstack/react-query": "5.95.2",
-    "@tanstack/react-router": "^1.132.0",
-    "@tanstack/react-router-devtools": "^1.132.0",
-    "@tanstack/react-router-ssr-query": "^1.131.7",
-    "@tanstack/react-start": "^1.132.0",
-    "@tanstack/router-plugin": "^1.132.0",
+    "@tanstack/react-router": "^1.167.4",
+    "@tanstack/react-router-devtools": "^1.166.9",
+    "@tanstack/react-router-ssr-query": "^1.166.9",
+    "@tanstack/react-start": "^1.166.15",
+    "@tanstack/router-plugin": "^1.166.13",
     "better-auth": "1.6.5",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -19,31 +19,31 @@
     "kitcn": "workspace:*",
     "lucide-react": "^1.8.0",
     "nitro": "latest",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "shadcn": "latest",
     "superjson": "^2.2.6",
     "tailwind-merge": "^3.5.0",
-    "tailwindcss": "^4.0.6",
+    "tailwindcss": "^4.2.1",
     "tw-animate-css": "^1.4.0",
     "vite-tsconfig-paths": "^5.1.4",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@tanstack/devtools-vite": "^0.3.11",
-    "@tanstack/eslint-config": "^0.3.0",
-    "@testing-library/dom": "^10.4.0",
-    "@testing-library/react": "^16.2.0",
-    "@types/node": "^22.10.2",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "@vitejs/plugin-react": "^5.0.4",
-    "jsdom": "^27.0.0",
-    "prettier": "^3.5.3",
+    "@tanstack/devtools-vite": "^0.6.0",
+    "@tanstack/eslint-config": "^0.4.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.19.15",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "jsdom": "^27.4.0",
+    "prettier": "^3.8.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
-    "typescript": "^5.7.2",
-    "vite": "^7.1.7",
-    "vitest": "^3.0.5",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^3.2.4",
     "web-vitals": "^5.1.0",
     "@types/bun": "latest",
     "@concavejs/cli": "latest"
diff --git a/fixtures/start/package.json b/fixtures/start/package.json
@@ -3,46 +3,46 @@
     "@base-ui/react": "^1.4.0",
     "@fontsource-variable/geist": "^5.2.8",
     "@opentelemetry/api": "1.9.0",
-    "@tailwindcss/vite": "^4.1.18",
-    "@tanstack/react-devtools": "^0.7.0",
+    "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/react-devtools": "^0.10.0",
     "@tanstack/react-query": "5.95.2",
-    "@tanstack/react-router": "^1.132.0",
-    "@tanstack/react-router-devtools": "^1.132.0",
-    "@tanstack/react-router-ssr-query": "^1.131.7",
-    "@tanstack/react-start": "^1.132.0",
-    "@tanstack/router-plugin": "^1.132.0",
+    "@tanstack/react-router": "^1.167.4",
+    "@tanstack/react-router-devtools": "^1.166.9",
+    "@tanstack/react-router-ssr-query": "^1.166.9",
+    "@tanstack/react-start": "^1.166.15",
+    "@tanstack/router-plugin": "^1.166.13",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "convex": "1.35.1",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
     "lucide-react": "^1.8.0",
     "nitro": "latest",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "shadcn": "latest",
     "superjson": "^2.2.6",
     "tailwind-merge": "^3.5.0",
-    "tailwindcss": "^4.0.6",
+    "tailwindcss": "^4.2.1",
     "tw-animate-css": "^1.4.0",
     "vite-tsconfig-paths": "^5.1.4",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@tanstack/devtools-vite": "^0.3.11",
-    "@tanstack/eslint-config": "^0.3.0",
-    "@testing-library/dom": "^10.4.0",
-    "@testing-library/react": "^16.2.0",
-    "@types/node": "^22.10.2",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "@vitejs/plugin-react": "^5.0.4",
-    "jsdom": "^27.0.0",
-    "prettier": "^3.5.3",
+    "@tanstack/devtools-vite": "^0.6.0",
+    "@tanstack/eslint-config": "^0.4.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.19.15",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "jsdom": "^27.4.0",
+    "prettier": "^3.8.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
-    "typescript": "^5.7.2",
-    "vite": "^7.1.7",
-    "vitest": "^3.0.5",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^3.2.4",
     "web-vitals": "^5.1.0",
     "@types/bun": "latest",
     "@concavejs/cli": "latest"
diff --git a/fixtures/vite-auth/package.json b/fixtures/vite-auth/package.json
@@ -3,7 +3,7 @@
     "@base-ui/react": "^1.4.0",
     "@fontsource-variable/geist": "^5.2.8",
     "@opentelemetry/api": "1.9.0",
-    "@tailwindcss/vite": "^4.1.17",
+    "@tailwindcss/vite": "^4.2.1",
     "@tanstack/react-query": "5.95.2",
     "better-auth": "1.6.5",
     "class-variance-authority": "^0.7.1",
@@ -12,30 +12,30 @@
     "hono": "4.12.9",
     "kitcn": "workspace:*",
     "lucide-react": "^1.8.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "shadcn": "latest",
     "superjson": "^2.2.6",
     "tailwind-merge": "^3.5.0",
-    "tailwindcss": "^4.1.17",
+    "tailwindcss": "^4.2.1",
     "tw-animate-css": "^1.4.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^24.10.1",
-    "@types/react": "^19.2.5",
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.1",
-    "eslint": "^9.39.1",
+    "@vitejs/plugin-react": "^5.2.0",
+    "eslint": "^9.39.4",
     "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.4.24",
+    "eslint-plugin-react-refresh": "^0.5.2",
     "globals": "^16.5.0",
     "prettier": "^3.8.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.46.4",
-    "vite": "^7.2.4",
+    "typescript-eslint": "^8.57.1",
+    "vite": "^7.3.1",
     "@types/bun": "latest",
     "@concavejs/cli": "latest"
   },
diff --git a/fixtures/vite/package.json b/fixtures/vite/package.json
diff --git a/packages/kitcn/src/cli/backend-core.ts b/packages/kitcn/src/cli/backend-core.ts
diff --git a/packages/kitcn/src/cli/commands/init.test.ts b/packages/kitcn/src/cli/commands/init.test.ts
diff --git a/packages/kitcn/src/cli/test-utils.ts b/packages/kitcn/src/cli/test-utils.ts

Original file line number	Diff line number	Diff line change
`@@ -6,3 +6,4 @@`
`6`	`6`
`7`	`7`	- Fix auth env sync and local auth bootstrap so `kitcn add auth`, `kitcn env push`, and `kitcn dev --bootstrap` use the real Convex CLI entrypoint more reliably across runtimes and platforms.
`8`	`8`	- Fix `kitcn init -t <next\|start\|vite>` custom shadcn preset exits so they stop with a clear rerun instruction instead of crashing while patching scaffold files.
	`9`	+- Improve `kitcn init -t <next\|start\|vite>` fresh scaffolds by syncing the shadcn wrapper to `shadcn@4.3.0` and regenerating the starter outputs against the latest upstream template contract.