Merge pull request #206 from udecode/codex/fix-start-init-bunx-parse

Author: zbeyens

.changeset/ten-bees-swim.md

@@ -0,0 +1,9 @@
+---
+"kitcn": patch
+---
+
+## Patches
+
+- Fix `bunx --bun kitcn init -t start --yes` so Bun-native parse-time imports
+  no longer bypass project aliases and crash first-run codegen on scaffolded
+  Start files.

docs/plans/2026-04-11-fix-start-init-bunx-codegen-parse.md

@@ -0,0 +1,36 @@
+## Task
+
+Fix the remaining published-package `bunx --bun kitcn@latest init -t start --yes`
+bootstrap parse failure where scaffolded `messages.ts`/`http.ts` still resolve
+through Bun's install cache and crash on `convex/server`, while `kitcn dev`
+already works.
+
+## Source Of Truth
+
+- User repro from published `kitcn@latest`
+- `docs/solutions/integration-issues/bunx-kitcn-self-resolution-must-not-break-scaffold-codegen-20260407.md`
+- Current parser + init scaffolding in `packages/kitcn/src/cli/**`
+
+## Likely Seam
+
+- `packages/kitcn/src/cli/utils/project-jiti.ts`
+- `packages/kitcn/src/cli/codegen.ts`
+- Published/package-intent regression coverage if the bug only reproduces from
+  the packed artifact path
+
+## Plan
+
+1. Reproduce against a real temp app with published `kitcn`.
+2. Compare the real start scaffold import graph vs existing codegen regressions.
+3. Add a failing targeted regression at the parser/package seam.
+4. Fix the import-resolution seam, not each scaffold file.
+5. Verify with targeted tests, package build, and the real published-style path.
+
+## Completion Checks
+
+- `typecheck` if changed `.ts` files require it
+- `lint:fix`
+- targeted tests for the failing seam
+- `bun --cwd packages/kitcn build`
+- update active unreleased changeset if package code changes
+- evaluate `ce-compound` only after the fix is verified

docs/solutions/integration-issues/bunx-kitcn-self-resolution-must-not-break-scaffold-codegen-20260407.md

@@ -1,7 +1,7 @@
 ---
 title: bunx kitcn self-resolution must not break scaffold codegen
 date: 2026-04-07
-last_updated: 2026-04-07
+last_updated: 2026-04-11
 category: integration-issues
 module: cli-codegen
 problem_type: integration_issue
@@ -49,6 +49,8 @@ The failing files were the stock scaffold backend demo files, not user code.
 - relying on source-level cache-path tests alone; the published bundled
   `backend-core` artifact can still miss a direct-import rewrite that never
   shows up in the raw TypeScript path
+- relying on entry-file rewrites alone; Bun-native imports can bypass Jiti
+  aliases for transitive files like the generated server placeholder
 - treating local deployment detection as only `local:*` or `anonymous:*`; plain
   `anonymous-agent` now shows up too
 
@@ -59,10 +61,12 @@ Patch the loader seam, not each scaffold file:
 1. create a project-aware `jiti` helper for CLI parsing
 2. alias `kitcn/server` to a tiny parser shim so scaffold parsing does not need
    the real runtime package graph during bootstrap
-3. rewrite direct `from "kitcn/server"` imports to the project shim path before
+3. force `tryNative: false` so Bun never takes over parse-time project imports
+   and skips the Jiti alias table for transitive files
+4. rewrite direct `from "kitcn/server"` imports to the project shim path before
    the bundled parser imports the module
-4. keep local `convex` export aliases so project-local resolution still works
-5. treat plain `anonymous-agent` as a local deployment and preserve
+5. keep local `convex` export aliases so project-local resolution still works
+6. treat plain `anonymous-agent` as a local deployment and preserve
    `CONVEX_AGENT_MODE=anonymous` in `dev`
 
 ## Why This Works
@@ -77,9 +81,15 @@ install-cache copy of `kitcn`, which then re-entered `dist/api-entry-*.js` and
 crashed on `convex/server` even though the generated app had already installed
 the right dependencies.
 
-Rewriting direct `kitcn/server` imports to the absolute project shim path
-removes bare-specifier resolution from that parse step, so the bundled parser
-never falls back to the Bun cache copy.
+The missing piece was Bun-native import. `createProjectJiti` still allowed
+`tryNative`, so the entry module could be rewritten but transitive files were
+still imported by Bun directly. Once Bun owned that transitive import chain,
+Jiti aliases no longer applied, and the generated server placeholder could fall
+back to the packaged `kitcn/server` bundle in Bun's temp install cache.
+
+Turning native import off keeps parse-time project modules inside Jiti end to
+end. That makes the project shim and local package aliases apply to the whole
+import graph instead of only the root file.
 
 The `anonymous-agent` follow-up bug was separate but adjacent: local deployment
 classification missed the plain `anonymous-agent` value, so `dev` failed to
@@ -89,8 +99,12 @@ carry the anonymous mode back into Convex subprocesses.
 
 - When a CLI package parses scaffolded project files during bootstrap, do not
   assume package self-resolution points at the new app install
+- Do not rely on Bun-native import for parse-time project modules when aliasing
+  or shim rewrites are part of the contract
 - For Bun-specific bootstrap bugs, verify both the source path and the packed
   artifact path; source tests alone can miss a bundled regression
+- Lock the Jiti helper itself so packed builds cannot silently re-enable native
+  import
 - Add a packed-artifact regression whenever the real bug only reproduces from
   `bunx` or another published-package entry point
 - Treat local deployment-name formats as compatibility inputs; upstream CLI

packages/kitcn/src/cli/utils/project-jiti.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createProjectJiti } from './project-jiti';
+
+describe('cli/utils/project-jiti', () => {
+  test('forces tryNative off for project parse-time imports', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kitcn-project-jiti-'));
+    const previous = process.env.JITI_TRY_NATIVE;
+
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({ name: 'project-jiti-test', private: true }, null, 2)
+    );
+
+    try {
+      process.env.JITI_TRY_NATIVE = 'true';
+
+      const jiti = createProjectJiti(dir);
+
+      expect(jiti.options.tryNative).toBe(false);
+    } finally {
+      if (previous === undefined) {
+        process.env.JITI_TRY_NATIVE = undefined;
+      } else {
+        process.env.JITI_TRY_NATIVE = previous;
+      }
+      fs.rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});

packages/kitcn/src/cli/utils/project-jiti.ts

@@ -260,6 +260,9 @@ export const createProjectJiti = (cwd = process.cwd()) =>
       runtime: 'automatic',
     },
     moduleCache: false,
+    // Bun-native import bypasses Jiti aliasing for transitive project files.
+    // Parse-time CLI imports need Jiti in the loop end-to-end.
+    tryNative: false,
     alias: {
       ...buildTsconfigPathAliases(cwd),
       ...buildLocalPackageExportAliases(cwd, 'kitcn'),

packages/kitcn/src/package-intent.test.ts

@@ -302,6 +302,7 @@ describe('package intent metadata', () => {
       expect(backendCoreSource).toContain('getProjectServerParserShimPath');
       expect(backendCoreSource).toContain('kitcn-parse.ts');
       expect(backendCoreSource).toContain('kitcn/server');
+      expect(backendCoreSource).toContain('tryNative: false');
     } finally {
       rmSync(packDir, { force: true, recursive: true });
     }