Merge pull request #212 from udecode/codex/208-209-deploy-env-passthrough

zbeyens · web-flow · commit 5010cd203d9d · 2026-04-15T11:41:56.000+02:00
diff --git a/.changeset/raw-convex-auth-kitcn.md b/.changeset/raw-convex-auth-kitcn.md
@@ -6,3 +6,5 @@
 
 - Fix raw Convex auth adoption so `kitcn add auth --preset convex --yes`
   installs `kitcn` before codegen and local bootstrap.
+- Fix `kitcn deploy` so CI deployment env vars reach Convex deploy, migrations,
+  and aggregate backfill.
diff --git a/docs/plans/2026-04-15-issues-208-209-deploy-env.md b/docs/plans/2026-04-15-issues-208-209-deploy-env.md
@@ -0,0 +1,31 @@
+# Issues 208 and 209 deploy env passthrough
+
+## Context
+
+- Source: GitHub issues #208 and #209.
+- Bug: `kitcn deploy` does not pass ambient Convex deployment env to the
+  `convex deploy` subprocess.
+- User-visible failure: CI sees no deployment config even when
+  `CONVEX_DEPLOY_KEY` is set.
+- Comment on #208 confirms `--env-file` workaround and points to #209.
+
+## Acceptance
+
+- `kitcn deploy` passes ambient Convex deployment env vars to `convex deploy`.
+- `kitcn dev` and `kitcn codegen` keep clearing ambient deployment env by
+  default.
+- Regression coverage proves deploy env passthrough through the CLI runner.
+- Published package change updates the active unreleased changeset.
+
+## Verification
+
+- Targeted red-green test in `packages/kitcn/src/cli/cli.commands.ts`.
+- `bun test ./packages/kitcn/src/cli/cli.commands.ts`.
+- `bun --cwd packages/kitcn build`.
+- `lint:fix`, `typecheck`, `check` before PR.
+
+## Notes
+
+- No browser surface.
+- The deploy fix had no scaffold impact. PR gate exposed a Start auth scaffold
+  route issue, so fixture sync/check became required and passed.
diff --git a/docs/solutions/integration-issues/deploy-must-forward-convex-deployment-env-20260415.md b/docs/solutions/integration-issues/deploy-must-forward-convex-deployment-env-20260415.md
@@ -0,0 +1,78 @@
+---
+title: kitcn deploy must forward Convex deployment env
+date: 2026-04-15
+category: integration-issues
+module: cli
+problem_type: integration_issue
+component: tooling
+symptoms:
+  - `kitcn deploy` fails in CI even when `CONVEX_DEPLOY_KEY` is set
+  - Convex reports missing deployment configuration or asks for `convex login`
+  - `bunx convex deploy` works with the same CI environment
+root_cause: wrong_api
+resolution_type: code_fix
+severity: high
+tags:
+  - convex
+  - deploy
+  - ci
+  - env
+  - cli
+---
+
+# kitcn deploy must forward Convex deployment env
+
+## Problem
+
+`kitcn deploy` wrapped `convex deploy` with `createBackendCommandEnv()` and
+therefore cleared `CONVEX_DEPLOY_KEY`, `CONVEX_DEPLOYMENT`, and self-hosted
+deployment env vars. CI deploys then fell back to anonymous or unconfigured
+Convex behavior.
+
+## Symptoms
+
+- CI logs say no Convex deployment configuration was found.
+- Convex suggests `convex login`, which is wrong for CI.
+- Passing `--env-file` works because Convex reads that file itself.
+
+## What Didn't Work
+
+- Keeping the deployment env wipe globally. That is correct for local dev and
+  codegen, but deploy is the opposite contract: ambient CI env is the target.
+- Forwarding env only to the first `convex deploy` call. Post-deploy migration
+  and aggregate backfill calls also need the same deployment target.
+
+## Solution
+
+Keep the default backend env wipe, but add a deploy-specific override sourced
+from the ambient Convex deployment env keys.
+
+```ts
+const deployCommandEnv =
+  backend === 'convex' ? getConvexDeploymentCommandEnv() : undefined;
+
+env: createBackendCommandEnv(deployCommandEnv);
+```
+
+Pass the same `deployCommandEnv` into post-deploy migration and aggregate
+backfill flows so the whole deploy pipeline targets the same deployment.
+
+## Why This Works
+
+Convex deployment env is not incidental process noise in CI. It is the target
+selection API for `convex deploy` and follow-up `convex run` calls.
+
+`kitcn dev` and `kitcn codegen` still clear ambient deployment env by default,
+so stale shell variables do not hijack local development.
+
+## Prevention
+
+- Test deploy wrappers with ambient `CONVEX_DEPLOY_KEY`, not only CLI flags.
+- When a deploy command fans out into post-deploy `run` commands, carry the
+  same target env through the whole flow.
+
+## Related Issues
+
+- [#208](https://github.com/udecode/kitcn/issues/208)
+- [#209](https://github.com/udecode/kitcn/issues/209)
+- [kitcn dev must honor remote Convex deployments from .env.local](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/dev-must-honor-remote-convex-deployments-from-env-local-20260404.md)
diff --git a/docs/solutions/integration-issues/start-auth-routes-must-use-literal-create-file-route-20260415.md b/docs/solutions/integration-issues/start-auth-routes-must-use-literal-create-file-route-20260415.md
@@ -0,0 +1,82 @@
+---
+title: Start auth routes must use literal createFileRoute paths
+date: 2026-04-15
+category: integration-issues
+module: cli
+problem_type: integration_issue
+component: tooling
+symptoms:
+  - TanStack Router generation fails with `expected route id to be a string literal or plain template literal`
+  - Start auth smoke fails after route generation leaves the API route unusable
+  - Plain `tsc` fails when new route files are present but `routeTree.gen.ts` is stale
+root_cause: wrong_api
+resolution_type: code_fix
+severity: medium
+tags:
+  - tanstack-start
+  - auth
+  - routes
+  - scaffold
+  - cli
+---
+
+# Start auth routes must use literal createFileRoute paths
+
+## Problem
+
+The Start auth scaffold emitted `createFileRoute('/auth' as never)` and
+`createFileRoute('/api/auth/$' as never)`. The cast hid stale
+`routeTree.gen.ts` type errors, but current TanStack Router generation rejects
+non-literal route arguments at runtime.
+
+## Symptoms
+
+- Vite logs `expected route id to be a string literal or plain template literal`.
+- `/api/auth/sign-up/email` returns a 500 because the Start auth route never
+  registers cleanly.
+- Replacing the cast with a clean literal fixes generation but makes fixture
+  `typecheck` fail until TanStack refreshes `routeTree.gen.ts`.
+
+## What Didn't Work
+
+- Keeping `as never`. It satisfies TypeScript but violates the router
+  generator's parser contract.
+- Using only clean literals. That works after route generation but fails the
+  repo's plain `tsc` fixture validation while `routeTree.gen.ts` is stale.
+
+## Solution
+
+Emit literal route paths and use a narrow `@ts-ignore` for the stale route tree
+window.
+
+```ts
+// @ts-ignore routeTree.gen.ts is refreshed by TanStack Router during dev/build.
+export const Route = createFileRoute('/auth')({
+  component: AuthPage,
+});
+```
+
+The generator sees the literal route path, and plain typecheck survives until
+TanStack updates `routeTree.gen.ts`.
+
+## Why This Works
+
+TanStack has two separate contracts here:
+
+- route generation needs a literal AST node
+- TypeScript needs `routeTree.gen.ts` to include the new route IDs
+
+The scaffold has to satisfy both during the gap between writing route files and
+running dev/build generation.
+
+## Prevention
+
+- Do not use type casts inside `createFileRoute(...)` arguments in generated
+  Start routes.
+- Verify Start auth changes with `scenario:test -- start-auth`, not just
+  fixture typecheck.
+
+## Related Issues
+
+- [raw Convex Start auth adoption must patch Start provider and React client](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/raw-convex-start-auth-adoption-must-patch-start-provider-and-react-client-20260410.md)
+- [start auth reload must rehydrate from persisted session token](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/start-auth-reload-must-rehydrate-from-persisted-session-token-20260408.md)
diff --git a/fixtures/next-auth/package.json b/fixtures/next-auth/package.json
@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "@base-ui/react": "^1.3.0",
+    "@base-ui/react": "^1.4.0",
     "@opentelemetry/api": "1.9.0",
     "@tanstack/react-query": "5.95.2",
     "better-auth": "1.5.3",
diff --git a/fixtures/next/package.json b/fixtures/next/package.json
@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "@base-ui/react": "^1.3.0",
+    "@base-ui/react": "^1.4.0",
     "@opentelemetry/api": "1.9.0",
     "@tanstack/react-query": "5.95.2",
     "class-variance-authority": "^0.7.1",
diff --git a/fixtures/start-auth/package.json b/fixtures/start-auth/package.json
@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "@base-ui/react": "^1.3.0",
+    "@base-ui/react": "^1.4.0",
     "@fontsource-variable/geist": "^5.2.8",
     "@opentelemetry/api": "1.9.0",
     "@tailwindcss/vite": "^4.1.18",
diff --git a/fixtures/start-auth/src/routes/api/auth/$.ts b/fixtures/start-auth/src/routes/api/auth/$.ts
@@ -2,7 +2,8 @@ import { createFileRoute } from '@tanstack/react-router';
 
 import { handler } from '@/lib/convex/auth-server';
 
-export const Route = createFileRoute('/api/auth/$' as never)({
+// @ts-ignore routeTree.gen.ts is refreshed by TanStack Router during dev/build.
+export const Route = createFileRoute('/api/auth/$')({
   server: {
     handlers: {
       GET: ({ request }) => handler(request),
diff --git a/fixtures/start-auth/src/routes/auth.tsx b/fixtures/start-auth/src/routes/auth.tsx
@@ -12,7 +12,8 @@ import {
   useSignUpMutationOptions,
 } from '@/lib/convex/auth-client';
 
-export const Route = createFileRoute('/auth' as never)({
+// @ts-ignore routeTree.gen.ts is refreshed by TanStack Router during dev/build.
+export const Route = createFileRoute('/auth')({
   component: AuthPage,
 });
 
diff --git a/fixtures/start/package.json b/fixtures/start/package.json
@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "@base-ui/react": "^1.3.0",
+    "@base-ui/react": "^1.4.0",
     "@fontsource-variable/geist": "^5.2.8",
     "@opentelemetry/api": "1.9.0",
     "@tailwindcss/vite": "^4.1.18",
diff --git a/fixtures/vite-auth/package.json b/fixtures/vite-auth/package.json
@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "@base-ui/react": "^1.3.0",
+    "@base-ui/react": "^1.4.0",
     "@fontsource-variable/geist": "^5.2.8",
     "@opentelemetry/api": "1.9.0",
     "@tailwindcss/vite": "^4.1.17",
diff --git a/fixtures/vite/package.json b/fixtures/vite/package.json
@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "@base-ui/react": "^1.3.0",
+    "@base-ui/react": "^1.4.0",
     "@fontsource-variable/geist": "^5.2.8",
     "@opentelemetry/api": "1.9.0",
     "@tailwindcss/vite": "^4.1.17",
diff --git a/packages/kitcn/src/cli/backend-core.ts b/packages/kitcn/src/cli/backend-core.ts
@@ -834,6 +834,14 @@ export function createBackendCommandEnv(
   };
 }
 
+export function getConvexDeploymentCommandEnv(
+  env: Record<string, string | undefined> = process.env
+): Record<string, string | undefined> {
+  return Object.fromEntries(
+    CONVEX_DEPLOYMENT_ENV_KEYS.map((key) => [key, env[key]])
+  ) as Record<string, string | undefined>;
+}
+
 export function hasRemoteConvexDeploymentEnv(
   env: Record<string, string | undefined>
 ): boolean {
diff --git a/packages/kitcn/src/cli/cli.commands.ts b/packages/kitcn/src/cli/cli.commands.ts
@@ -2220,7 +2220,10 @@ describe('cli/cli', () => {
         path.join(dir, 'src', 'routes', 'api', 'auth', '$.ts'),
         'utf8'
       );
-      expect(routeSource).toContain("createFileRoute('/api/auth/$' as never)");
+      expect(routeSource).toContain("createFileRoute('/api/auth/$')");
+      expect(routeSource).toContain(
+        'routeTree.gen.ts is refreshed by TanStack Router during dev/build'
+      );
       expect(routeSource).toContain(
         "import { handler } from '@/lib/convex/auth-server';"
       );
@@ -2229,7 +2232,10 @@ describe('cli/cli', () => {
         path.join(dir, 'src', 'routes', 'auth.tsx'),
         'utf8'
       );
-      expect(authPageSource).toContain("createFileRoute('/auth' as never)");
+      expect(authPageSource).toContain("createFileRoute('/auth')");
+      expect(authPageSource).toContain(
+        'routeTree.gen.ts is refreshed by TanStack Router during dev/build'
+      );
       expect(authPageSource).not.toContain('callbackURL');
     } finally {
       process.chdir(oldCwd);
@@ -4124,7 +4130,7 @@ describe('cli/cli', () => {
       expect(ratelimitPluginSource).not.toContain('tag/create:free');
       expectDependencyInstallCall(
         execaStub.mock.calls as unknown as unknown[],
-        'kitcn'
+        resolveScaffoldInstallSpec({})
       );
       expect(generateMetaStub).not.toHaveBeenCalled();
     } finally {
@@ -6339,6 +6345,80 @@ describe('cli/cli', () => {
     ]);
   });
 
+  test('run(deploy) passes ambient Convex deployment env through deploy flow', async () => {
+    const deploymentEnvKeys = [
+      'CONVEX_DEPLOYMENT',
+      'CONVEX_DEPLOY_KEY',
+      'CONVEX_SELF_HOSTED_URL',
+      'CONVEX_SELF_HOSTED_ADMIN_KEY',
+    ] as const;
+    const originalEnv = Object.fromEntries(
+      deploymentEnvKeys.map((key) => [key, process.env[key]])
+    );
+    const callEnvs: Array<Record<string, string | undefined> | undefined> = [];
+
+    process.env.CONVEX_DEPLOYMENT = 'prod:ci-deploy';
+    process.env.CONVEX_DEPLOY_KEY = 'prod:key';
+    process.env.CONVEX_SELF_HOSTED_URL = 'https://convex.example.com';
+    process.env.CONVEX_SELF_HOSTED_ADMIN_KEY = 'admin:key';
+
+    try {
+      const execaStub = mock(
+        async (
+          _cmd: string,
+          args: string[],
+          opts?: { env?: Record<string, string | undefined> }
+        ) => {
+          callEnvs.push(opts?.env);
+          if (args.includes('generated/server:migrationRun')) {
+            return {
+              exitCode: 0,
+              stdout: '{"status":"noop"}\n',
+              stderr: '',
+            } as any;
+          }
+          if (args.includes('generated/server:aggregateBackfill')) {
+            return {
+              exitCode: 0,
+              stdout: '{"status":"ok"}\n',
+              stderr: '',
+            } as any;
+          }
+          return { exitCode: 0, stdout: '', stderr: '' } as any;
+        }
+      );
+      const generateMetaStub = mock(async () => {});
+      const syncEnvStub = mock(async () => {});
+      const loadConfigStub = mock(() => createDefaultConfig());
+
+      const exitCode = await run(['deploy'], {
+        realConvex: '/fake/convex/main.js',
+        execa: execaStub as any,
+        generateMeta: generateMetaStub as any,
+        syncEnv: syncEnvStub as any,
+        loadCliConfig: loadConfigStub as any,
+      });
+
+      expect(exitCode).toBe(0);
+      expect(callEnvs.length).toBeGreaterThanOrEqual(3);
+      for (const env of callEnvs) {
+        expect(env?.CONVEX_DEPLOYMENT).toBe('prod:ci-deploy');
+        expect(env?.CONVEX_DEPLOY_KEY).toBe('prod:key');
+        expect(env?.CONVEX_SELF_HOSTED_URL).toBe('https://convex.example.com');
+        expect(env?.CONVEX_SELF_HOSTED_ADMIN_KEY).toBe('admin:key');
+      }
+    } finally {
+      for (const key of deploymentEnvKeys) {
+        const value = originalEnv[key];
+        if (value === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = value;
+        }
+      }
+    }
+  });
+
   test('run(deploy) uses concave deploy + concave run when backend is concave', async () => {
     const concaveCliPath = path.join(
       fs.mkdtempSync(path.join(os.tmpdir(), 'kitcn-concave-cli-')),
diff --git a/packages/kitcn/src/cli/commands/deploy.ts b/packages/kitcn/src/cli/commands/deploy.ts
diff --git a/packages/kitcn/src/cli/registry/items/auth/auth-start-page.template.ts b/packages/kitcn/src/cli/registry/items/auth/auth-start-page.template.ts
diff --git a/packages/kitcn/src/cli/registry/items/auth/auth-start-route.template.ts b/packages/kitcn/src/cli/registry/items/auth/auth-start-route.template.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"dependencies": {`
`3`		`- "@base-ui/react": "^1.3.0",`
	`3`	`+ "@base-ui/react": "^1.4.0",`
`4`	`4`	`"@opentelemetry/api": "1.9.0",`
`5`	`5`	`"@tanstack/react-query": "5.95.2",`
`6`	`6`	`"better-auth": "1.5.3",`