kitcn 0.12.2 → 0.12.4

package/dist/cli.mjs

@@ -2521,6 +2521,16 @@ const applyDependencyHintsInstall = async (dependencyHints, execaFn) => {
 	});
 	return missingDependencyHints;
 };
+const applyPlanningDependencyInstall = async (dependencySpecs, execaFn) => {
+	const missingDependencySpecs = resolveMissingDependencyHints(dependencySpecs);
+	if (missingDependencySpecs.length === 0) return [];
+	const { packageJsonPath } = resolvePackageJsonInstallTarget();
+	await execaFn("bun", ["add", ...missingDependencySpecs], {
+		cwd: dirname(packageJsonPath),
+		stdio: "inherit"
+	});
+	return missingDependencySpecs;
+};
 const applyPluginDependencyInstall = async (install, execaFn) => {
 	if (install.skipped || !install.packageName || !install.packageJsonPath) return install;
 	const packageSpec = install.packageSpec ?? install.packageName;
@@ -5633,6 +5643,7 @@ const authRegistryItem = defineInternalRegistryItem({
 	},
 	internal: {
 		localDocsPath: "www/content/docs/auth/server.mdx",
+		planningDependencies: [OPENTELEMETRY_API_INSTALL_SPEC],
 		envFields: AUTH_ENV_FIELDS,
 		liveBootstrap: { mode: "local" },
 		schemaRegistration: {
@@ -7297,6 +7308,7 @@ function toPluginCatalogEntry(definition) {
 		},
 		packageName: getPackageNameFromInstallSpec(installDependency),
 		packageInstallSpec: installDependency,
+		planningDependencies: internal.planningDependencies,
 		envFields: internal.envFields,
 		liveBootstrap: internal.liveBootstrap,
 		schemaRegistration: internal.schemaRegistration,
@@ -11941,6 +11953,7 @@ const handleAddCommand = async (argv, deps = {}) => {
 			templates: selectedTemplates
 		})) throw new Error(AUTH_SCHEMA_ONLY_MISSING_ERROR);
 	}
+	if (!addArgs.dryRun) await applyPlanningDependencyInstall(pluginDescriptor.planningDependencies ?? [], execaFn);
 	const plan = filterPluginInstallPlanForAddScope({
 		plan: await buildPluginInstallPlan({
 			applyScope,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",

package/skills/convex/references/features/auth.md

@@ -69,7 +69,7 @@ Use the CLI-first path:
 npx kitcn add auth --yes
 ```
 
-If kitcn is not bootstrapped yet, start with `npx kitcn init -t next --yes` for a fresh app or `npx kitcn init --yes` for in-place adoption.
+If kitcn is not bootstrapped yet, start with `npx kitcn@latest init -t next --yes` for a fresh app or `npx kitcn@latest init --yes` for in-place adoption.
 
 On local Convex, `add auth --yes` also finishes the first auth bootstrap pass: generated runtime, `BETTER_AUTH_SECRET`, and `JWKS`.
 
@@ -279,6 +279,12 @@ export const {
 
 ### Sign In
 
+Rule:
+
+1. The standard Next local path assumes `NEXT_PUBLIC_SITE_URL=http://localhost:3000`.
+2. If the app runs on another port, update `.env.local` `NEXT_PUBLIC_SITE_URL`,
+   `convex/.env` `SITE_URL`, and the app dev script together.
+
 **Social:**
 ```ts
 const signInSocial = useMutation(useSignInSocialMutationOptions());

package/skills/convex/references/setup/auth.md

@@ -7,10 +7,10 @@ Feature gate: only apply this section if auth is enabled.
 If kitcn is not bootstrapped yet, start there first:
 
 ```bash
-bunx kitcn init -t next --yes
+npx kitcn@latest init -t next --yes
 ```
 
-Use `bunx kitcn init --yes` instead for in-place adoption of the
+Use `npx kitcn@latest init --yes` instead for in-place adoption of the
 current supported app.
 
 Then install auth:
@@ -82,7 +82,7 @@ export default defineAuth(() => ({
 
 Canonical rule:
 
-1. `bunx kitcn init --yes`, `bunx kitcn dev`, and `bunx kitcn add auth --yes` all drive generation of `convex/functions/generated/` when they own the local Convex flow.
+1. `npx kitcn@latest init --yes`, `bunx kitcn dev`, and `bunx kitcn add auth --yes` all drive generation of `convex/functions/generated/` when they own the local Convex flow.
 2. `auth.ts` default-exports `defineAuth(() => ({ ...options, triggers }))` imported from `./generated/auth`.
 3. Import runtime auth contract (`getAuth`, `authClient`, CRUD/triggers, `auth`) from `<functionsDir>/generated/auth`.
 4. If `auth.ts` is missing or incomplete, codegen still succeeds and generated runtime exports `authEnabled = false` with setup guidance at call time.

package/skills/convex/references/setup/index.md

@@ -86,7 +86,7 @@ Quickstart path:
 ```bash
 mkdir my-app
 cd my-app
-bunx kitcn init -t next --yes
+npx kitcn@latest init -t next --yes
 ```
 
 Then start the long-running backend with `bunx kitcn dev`, run the
@@ -99,19 +99,19 @@ Use the CLI first:
 
 ```bash
 # Adopt the current supported app in place
-bunx kitcn init --yes
+npx kitcn@latest init --yes
 
 # Adopt the current supported app on Concave
-bunx kitcn --backend concave init --yes
+npx kitcn@latest --backend concave init --yes
 
 # New Next.js app with deterministic shadcn bootstrap + first local Convex bootstrap
-bunx kitcn init -t next --yes
+npx kitcn@latest init -t next --yes
 
 # New Vite app with the React baseline + first local Convex bootstrap
-bunx kitcn init -t vite --yes
+npx kitcn@latest init -t vite --yes
 
 # Nested app target
-bunx kitcn init -t next --yes --cwd apps --name web
+npx kitcn@latest init -t next --yes --cwd apps --name web
 ```
 
 Then add only the features you want:
@@ -373,6 +373,13 @@ NEXT_PUBLIC_SITE_URL=http://localhost:3000
 
 Rule: real-time URL uses `.cloud`; HTTP/router/caller URL uses `.site`.
 
+Local auth contract:
+
+1. Default app origin is `http://localhost:3000`.
+2. If you move the app to another local port, update `.env.local`
+   `NEXT_PUBLIC_SITE_URL`, `convex/.env` `SITE_URL`, and the app dev script
+   together.
+
 ### 4.3 Typed env helper (recommended for full backend parity)
 
 When multiple Convex functions and libs share env values (auth, billing, dev guards), create one typed helper:
@@ -598,6 +605,7 @@ CLI commands:
 ```bash
 bunx kitcn dev
 # deterministic one-shot local runtime proof:
+# stop any long-running local backend first
 bunx kitcn verify
 # optional fallback only if dev cannot run and backend is already active:
 bunx kitcn codegen
@@ -622,6 +630,7 @@ dev session and auto-pushes later edits. Keep `env push` for `--prod`,
 Run these after base setup (Sections 3-5) and before starting Section 6:
 
 ```bash
+# stop any long-running local backend first
 bunx kitcn verify
 bunx convex run internal.seed.seed
 bunx convex run internal.init.default
@@ -643,6 +652,7 @@ Then sanity-check runtime paths (non-auth only):
 Run this after Section 6 and before Sections 7-10:
 
 ```bash
+# stop any long-running local backend first
 bunx kitcn verify
 bun run typecheck || bunx tsc --noEmit
 bun test

package/skills/convex/references/setup/react.md

@@ -172,4 +172,3 @@ Provider mount checklist:
 1. `AppConvexProvider` wraps app routes before client feature components render.
 2. `CRPCProvider` is nested inside TanStack Query provider (`QueryClientProvider`).
 3. Next.js apps pass token where required (Section 8.A.4) or intentionally run without token for public-only paths.
-

package/skills/convex/references/setup/server.md

@@ -1,6 +1,6 @@
 ## 5. Core Backend
 
-For production bootstrap, start in the CLI Registry: use `bunx kitcn init -t <next|vite> --yes` for the shortest fresh local path, `bunx kitcn init --yes` to adopt the current app and finish the first local Convex bootstrap in one command, and `bunx kitcn add <plugin>` for feature layers. This file is the manual backend wiring reference.
+For production bootstrap, start in the CLI Registry: use `npx kitcn@latest init -t <next|vite> --yes` for the shortest fresh local path, `npx kitcn@latest init --yes` to adopt the current app and finish the first local Convex bootstrap in one command, and `bunx kitcn add <plugin>` for feature layers. This file is the manual backend wiring reference.
 
 ### 5.1 Define schema and relations
 
@@ -204,8 +204,8 @@ Do not fake generated files.
 
 Automation/non-interactive path:
 
-1. Run `bunx kitcn init --yes` when you want scaffold or adoption plus the one-shot local Convex bootstrap in one command.
-2. Run `bunx kitcn verify` when you want a non-interactive local runtime proof in the current app. It reuses an existing local deployment when one is already configured, and only falls back to anonymous fresh-local setup when it has to.
+1. Run `npx kitcn@latest init --yes` when you want scaffold or adoption plus the one-shot local Convex bootstrap in one command.
+2. Run `bunx kitcn verify` when you want a non-interactive local runtime proof in the current app. Stop any long-running local backend first. It reuses an existing local deployment when one is already configured, and only falls back to anonymous fresh-local setup when it has to.
 3. Confirm the generated runtime exists in `convex/functions/generated/server.ts`.
 4. Then run `bunx kitcn dev` for ongoing codegen/API refresh.
 
@@ -222,7 +222,7 @@ Agent command policy:
 1. Default to `bunx kitcn dev`.
 2. `kitcn dev` already runs codegen/API generation.
 3. Do not run `bunx kitcn codegen` as a separate default step.
-4. Use `bunx kitcn verify` for one-shot local runtime proof in CI or agent runs.
+4. Use `bunx kitcn verify` for one-shot local runtime proof in CI or agent runs, with any long-running local backend stopped first.
 5. Use manual `bunx kitcn codegen` only as fallback when `kitcn dev` cannot be run and backend is already active.
 6. Use `bunx kitcn insights` for cloud-deployment debugging; it forwards to the upstream Convex insights CLI.