Merge pull request #210 from udecode/codex/fix-raw-convex-auth-kitcn-dep

Author: zbeyens

.changeset/raw-convex-auth-kitcn.md

@@ -0,0 +1,8 @@
+---
+"kitcn": patch
+---
+
+## Patches
+
+- Fix raw Convex auth adoption so `kitcn add auth --preset convex --yes`
+  installs `kitcn` before codegen and local bootstrap.

docs/solutions/integration-issues/raw-convex-auth-adoption-must-install-kitcn-runtime-20260415.md

@@ -0,0 +1,91 @@
+---
+title: Raw Convex auth adoption must install kitcn runtime before codegen
+date: 2026-04-15
+category: integration-issues
+module: auth-adoption
+problem_type: integration_issue
+component: tooling
+severity: high
+symptoms:
+  - '`kitcn add auth --preset convex --yes` fails during Convex bootstrap with `Could not resolve "kitcn/auth"` or `Could not resolve "kitcn/auth/http"`'
+  - raw Convex auth adoption writes `convex/auth.ts`, `convex/http.ts`, and `src/lib/convex/auth-client.ts`, but the app `package.json` still lacks `kitcn`'
+  - local scenario runs with `KITCN_INSTALL_SPEC` can end up with duplicate `kitcn` dependency keys if the hint is pre-resolved too early'
+root_cause: missing_tooling
+resolution_type: code_fix
+tags:
+  - convex
+  - auth
+  - cli
+  - scaffolding
+  - package-management
+  - scenarios
+---
+
+# Raw Convex auth adoption must install kitcn runtime before codegen
+
+## Problem
+
+The raw Convex auth preset generated files that import `kitcn/*`, but the
+install plan only guaranteed `better-auth` and OpenTelemetry.
+
+That meant `kitcn add auth --preset convex --yes` could scaffold the right
+files and then immediately die when Convex tried to bundle them.
+
+## Symptoms
+
+- `convex/auth.ts` imports `kitcn/auth`, but the app has no `kitcn`
+  dependency
+- Convex bootstrap fails before JWKS sync with unresolved `kitcn/*` imports
+- local scenario runs can show duplicate `kitcn` keys in `package.json` if the
+  dependency hint is stored as a pre-resolved tarball path
+
+## What Didn't Work
+
+- treating `better-auth` as the only runtime dependency for the raw preset
+- storing the raw preset hint as an already-resolved install spec like
+  `file:/.../kitcn-0.12.27.tgz`
+
+The second cut was especially sneaky: it fixed published installs, but it
+defeated package-name detection during local scenario runs, so the CLI could no
+longer tell that `kitcn` was already present.
+
+## Solution
+
+Keep the raw preset dependency hint at the package-name level:
+
+- declare `kitcn` as a raw auth scaffold dependency hint
+- resolve that hint to the current package install spec only at install time
+
+That keeps both paths honest:
+
+1. published CLI runs install `kitcn@<current-version>`
+2. local scenario runs still collapse to the tarball override from
+   `KITCN_INSTALL_SPEC`
+3. duplicate detection still works because the missing-dependency scan compares
+   against the raw package name `kitcn`, not a tarball URL
+
+## Why This Works
+
+The raw preset contract is different from the managed kitcn baseline.
+
+Managed apps already depend on `kitcn`, so auth scaffolding can assume the
+runtime helpers exist. Raw Convex adoption cannot. It patches a foreign app in
+place, so every emitted `kitcn/*` import must be matched by an explicit
+dependency install before codegen or local bootstrap runs.
+
+Resolving the install spec too early turns `kitcn` into an opaque file URL,
+which breaks the package-name check that prevents duplicate installs.
+
+## Prevention
+
+1. If a preset emits `kitcn/*` imports into an app that did not come from
+   `kitcn init`, treat `kitcn` as an explicit scaffold dependency.
+2. Keep dependency hints as package-name specs until install time. Resolve
+   local tarball overrides as late as possible.
+3. Keep `raw-start-auth-adoption` in the scenario gate. This bug is easy to
+   miss in file-only tests and obvious in the real bootstrap lane.
+
+## Related Issues
+
+- `docs/solutions/integration-issues/raw-convex-auth-adoption-bootstrap-20260318.md`
+- `docs/solutions/integration-issues/raw-convex-start-auth-adoption-must-patch-start-provider-and-react-client-20260410.md`

packages/kitcn/src/cli/backend-core.ts

@@ -128,8 +128,11 @@ import {
   BASELINE_DEPENDENCY_INSTALL_SPECS,
   getPackageNameFromInstallSpec,
   INIT_TEMPLATE_DEPENDENCY_INSTALL_SPECS,
-  KITCN_INSTALL_SPEC_ENV,
+  resolveScaffoldInstallSpec,
 } from './supported-dependencies.js';
+
+export { resolveScaffoldInstallSpec } from './supported-dependencies.js';
+
 import { isContentEquivalent } from './utils/content-compare.js';
 import { CRPC_BUILDER_STUB_SOURCE } from './utils/crpc-builder-stub.js';
 import {
@@ -146,7 +149,6 @@ import { createTypeScriptProxy } from './utils/typescript-runtime.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-let ownVersion: string | undefined | null;
 const ts = createTypeScriptProxy();
 
 // Resolve real convex CLI binary
@@ -796,54 +798,6 @@ export function createCommandEnv(
   };
 }
 
-function resolveOwnPackageJsonPath(filePath: string): string {
-  let current = dirname(filePath);
-
-  while (true) {
-    const candidate = join(current, 'package.json');
-    if (fs.existsSync(candidate)) {
-      const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8')) as {
-        name?: string;
-        version?: string;
-      };
-      if (parsed.name === 'kitcn') {
-        return candidate;
-      }
-    }
-
-    const parent = dirname(current);
-    if (parent === current) {
-      throw new Error(`Could not find kitcn package.json from ${filePath}.`);
-    }
-    current = parent;
-  }
-}
-
-function readOwnVersion() {
-  if (ownVersion !== undefined) {
-    return ownVersion ?? undefined;
-  }
-
-  const packageJsonPath = resolveOwnPackageJsonPath(__filename);
-  const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) as {
-    version?: string;
-  };
-  ownVersion = parsed.version ?? null;
-  return ownVersion ?? undefined;
-}
-
-export function resolveScaffoldInstallSpec(
-  env: Record<string, string | undefined> = process.env
-) {
-  const override = env[KITCN_INSTALL_SPEC_ENV]?.trim();
-  if (override) {
-    return override;
-  }
-
-  const version = readOwnVersion();
-  return version ? `kitcn@${version}` : 'kitcn';
-}
-
 const CONVEX_DEPLOYMENT_ENV_KEYS = [
   'CONVEX_DEPLOYMENT',
   'CONVEX_DEPLOY_KEY',

packages/kitcn/src/cli/cli.commands.ts

@@ -1,7 +1,6 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { resolveScaffoldInstallSpec } from './backend-core';
 import {
   collectPluginScaffoldTemplates,
   ensureConvexGitignoreEntry,
@@ -19,7 +18,11 @@ import {
 } from './commands/init';
 import { getPluginCatalogEntry } from './registry/index';
 import { RESEND_SCHEMA_TEMPLATE } from './registry/items/resend/resend-schema.template';
-import { BETTER_AUTH_INSTALL_SPEC } from './supported-dependencies';
+import {
+  BETTER_AUTH_INSTALL_SPEC,
+  OPENTELEMETRY_API_INSTALL_SPEC,
+  resolveScaffoldInstallSpec,
+} from './supported-dependencies';
 import {
   writeShadcnNextApp,
   writeShadcnStartApp,
@@ -2573,6 +2576,10 @@ describe('cli/cli', () => {
       expect(httpSource).toContain('allowedOrigins: [process.env.SITE_URL!]');
       expect(httpSource).not.toContain('authMiddleware');
       expect(httpSource).not.toContain('createHttpRouter');
+      expectDependencyInstallCallWithPackages(
+        execaStub.mock.calls as unknown as unknown[],
+        [OPENTELEMETRY_API_INSTALL_SPEC, resolveScaffoldInstallSpec()]
+      );
 
       const schemaSource = fs.readFileSync(
         path.join(dir, 'convex', 'schema.ts'),

packages/kitcn/src/cli/registry/dependencies.ts

@@ -172,17 +172,20 @@ export const applyDependencyHintsInstall = async (
   const missingDependencyHints = resolveMissingDependencyHints(
     dependencyHints
   ).filter((dependencyHint) => !preinstalledSpecs.includes(dependencyHint));
-  if (missingDependencyHints.length === 0) {
+  const installSpecs = missingDependencyHints.map((dependencyHint) =>
+    resolveSupportedDependencyInstallSpec(dependencyHint)
+  );
+  if (installSpecs.length === 0) {
     return preinstalledSpecs;
   }
 
   const { packageJsonPath } = resolvePackageJsonInstallTarget();
-  await execaFn('bun', ['add', ...missingDependencyHints], {
+  await execaFn('bun', ['add', ...installSpecs], {
     cwd: dirname(packageJsonPath),
     stdio: 'inherit',
   });
 
-  return [...preinstalledSpecs, ...missingDependencyHints];
+  return [...preinstalledSpecs, ...installSpecs];
 };
 
 export const applyPlanningDependencyInstall = async (
@@ -193,17 +196,20 @@ export const applyPlanningDependencyInstall = async (
   const missingDependencySpecs = resolveMissingDependencyHints(
     dependencySpecs
   ).filter((dependencySpec) => !preinstalledSpecs.includes(dependencySpec));
-  if (missingDependencySpecs.length === 0) {
+  const installSpecs = missingDependencySpecs.map((dependencySpec) =>
+    resolveSupportedDependencyInstallSpec(dependencySpec)
+  );
+  if (installSpecs.length === 0) {
     return preinstalledSpecs;
   }
 
   const { packageJsonPath } = resolvePackageJsonInstallTarget();
-  await execaFn('bun', ['add', ...missingDependencySpecs], {
+  await execaFn('bun', ['add', ...installSpecs], {
     cwd: dirname(packageJsonPath),
     stdio: 'inherit',
   });
 
-  return [...preinstalledSpecs, ...missingDependencySpecs];
+  return [...preinstalledSpecs, ...installSpecs];
 };
 
 export const applyPluginDependencyInstall = async (

packages/kitcn/src/cli/registry/items/auth/auth-item.ts

@@ -138,8 +138,9 @@ const AUTH_CONVEX_FILES = [
     target: 'functions',
     content: AUTH_CONVEX_TEMPLATE,
     requires: ['auth-config-convex'],
-    dependencyHintMessage: 'Auth runtime depends on OpenTelemetry API.',
-    dependencyHints: [OPENTELEMETRY_API_INSTALL_SPEC],
+    dependencyHintMessage:
+      'Auth runtime depends on OpenTelemetry API and kitcn runtime helpers.',
+    dependencyHints: [OPENTELEMETRY_API_INSTALL_SPEC, 'kitcn'],
   }),
   createRegistryFile({
     id: 'auth-client-convex',

packages/kitcn/src/cli/supported-dependencies.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
 import {
   BASELINE_DEPENDENCY_INSTALL_SPECS,
   BETTER_AUTH_INSTALL_SPEC,
@@ -9,6 +10,7 @@ import {
   PINNED_HONO_INSTALL_SPEC,
   PINNED_TANSTACK_REACT_QUERY_INSTALL_SPEC,
   PINNED_ZOD_INSTALL_SPEC,
+  resolveScaffoldInstallSpec,
   resolveSupportedDependencyInstallSpec,
   SUPPORTED_DEPENDENCY_VERSIONS,
 } from './supported-dependencies';
@@ -73,4 +75,15 @@ describe('cli/supported-dependencies', () => {
       resolveSupportedDependencyInstallSpec('better-auth@1.5.3', env)
     ).toBe('better-auth@1.5.3');
   });
+
+  test('pins scaffold kitcn installs to the current package version', () => {
+    const packageJson = JSON.parse(
+      fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+    ) as { version: string };
+
+    expect(resolveScaffoldInstallSpec({})).toBe(`kitcn@${packageJson.version}`);
+    expect(resolveSupportedDependencyInstallSpec('kitcn', {})).toBe(
+      `kitcn@${packageJson.version}`
+    );
+  });
 });

packages/kitcn/src/cli/supported-dependencies.ts

@@ -1,3 +1,7 @@
+import fs from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 const EXACT_VERSION_RE = /^(\d+)\.(\d+)\.\d+$/;
 const SUPPORTED_CONVEX_VERSION = '1.33.0';
 const SUPPORTED_BETTER_AUTH_VERSION = '1.5.3';
@@ -9,6 +13,8 @@ const SUPPORTED_ZOD_VERSION = '4.3.6';
 export const KITCN_INSTALL_SPEC_ENV = 'KITCN_INSTALL_SPEC';
 export const KITCN_RESEND_INSTALL_SPEC_ENV = 'KITCN_RESEND_INSTALL_SPEC';
 
+let ownVersion: string | null | undefined;
+
 export function getMinimumVersionRange(version: string): string {
   const match = EXACT_VERSION_RE.exec(version);
   if (!match) {
@@ -55,6 +61,10 @@ export function resolveSupportedDependencyInstallSpec(
   spec: string,
   env: Record<string, string | undefined> = process.env
 ) {
+  if (getPackageNameFromInstallSpec(spec) === 'kitcn') {
+    return resolveScaffoldInstallSpec(env);
+  }
+
   const envKey =
     LOCAL_INSTALL_SPEC_ENV_BY_PACKAGE_NAME[
       getPackageNameFromInstallSpec(
@@ -65,6 +75,46 @@ export function resolveSupportedDependencyInstallSpec(
   return override && override.length > 0 ? override : spec;
 }
 
+function readOwnVersion() {
+  if (ownVersion !== undefined) {
+    return ownVersion ?? undefined;
+  }
+
+  let currentDir = dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const packageJsonPath = join(currentDir, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) as {
+        name?: string;
+        version?: string;
+      };
+      if (parsed.name === 'kitcn') {
+        ownVersion = parsed.version ?? null;
+        return ownVersion ?? undefined;
+      }
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      ownVersion = null;
+      return undefined;
+    }
+    currentDir = parentDir;
+  }
+}
+
+export function resolveScaffoldInstallSpec(
+  env: Record<string, string | undefined> = process.env
+) {
+  const override = env[KITCN_INSTALL_SPEC_ENV]?.trim();
+  if (override) {
+    return override;
+  }
+
+  const version = readOwnVersion();
+  return version ? `kitcn@${version}` : 'kitcn';
+}
+
 export const SUPPORTED_DEPENDENCY_VERSIONS = {
   convex: {
     exact: SUPPORTED_CONVEX_VERSION,