@geekmidas/cli 1.10.35 → 1.10.36

package/src/init/generators/web-tanstack.ts

@@ -0,0 +1,348 @@
+import type { GeneratedFile, TemplateOptions } from '../templates/index.js';
+import { GEEKMIDAS_VERSIONS } from '../versions.js';
+
+/**
+ * Generate TanStack Start web app files for the fullstack template.
+ *
+ * Mirrors the Next.js scaffold (apps/web) but on Vite + TanStack Start +
+ * TanStack Router with the `VITE_` env-var convention.
+ */
+export function generateTanStackWebFiles(
+	options: TemplateOptions,
+): GeneratedFile[] {
+	if (!options.monorepo || options.template !== 'fullstack') {
+		return [];
+	}
+
+	const packageName = `@${options.name}/web`;
+	const apiPackage = `@${options.name}/api`;
+	const modelsPackage = `@${options.name}/models`;
+	const uiPackage = `@${options.name}/ui`;
+
+	const packageJson = {
+		name: packageName,
+		version: '0.0.1',
+		private: true,
+		type: 'module',
+		scripts: {
+			dev: 'gkm exec -- vite dev',
+			build: 'gkm exec -- vite build',
+			start: 'node .output/server/index.mjs',
+			typecheck: 'tsc --noEmit',
+		},
+		dependencies: {
+			[apiPackage]: 'workspace:*',
+			[modelsPackage]: 'workspace:*',
+			[uiPackage]: 'workspace:*',
+			'@geekmidas/client': GEEKMIDAS_VERSIONS['@geekmidas/client'],
+			'@geekmidas/envkit': GEEKMIDAS_VERSIONS['@geekmidas/envkit'],
+			'@tanstack/react-query': '~5.80.0',
+			'@tanstack/react-router': '^1.87.0',
+			'@tanstack/react-start': '^1.87.0',
+			'better-auth': '~1.2.0',
+			react: '~19.2.0',
+			'react-dom': '~19.2.0',
+		},
+		devDependencies: {
+			'@geekmidas/cli': GEEKMIDAS_VERSIONS['@geekmidas/cli'],
+			'@tailwindcss/vite': '^4.0.0',
+			'@tanstack/router-plugin': '^1.87.0',
+			'@types/node': '~22.0.0',
+			'@types/react': '~19.0.0',
+			'@types/react-dom': '~19.0.0',
+			'@vitejs/plugin-react': '^4.3.4',
+			tailwindcss: '^4.0.0',
+			tsx: '~4.20.0',
+			typescript: '~5.8.2',
+			vite: '^7.0.0',
+			'vite-tsconfig-paths': '~5.1.0',
+		},
+	};
+
+	const viteConfig = `import { Credentials } from '@geekmidas/envkit/credentials';
+import tailwindcss from '@tailwindcss/vite';
+import { tanstackStart } from '@tanstack/react-start/plugin/vite';
+import viteReact from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+  server: {
+    port: Number(Credentials.PORT ?? 3001),
+  },
+  // VITE_* vars are inlined automatically; no manual loadEnv needed.
+  envPrefix: 'VITE_',
+  plugins: [
+    tsconfigPaths({ root: import.meta.dirname }),
+    tailwindcss(),
+    tanstackStart(),
+    viteReact(),
+  ],
+});
+`;
+
+	const tsConfig = {
+		extends: '../../tsconfig.json',
+		compilerOptions: {
+			lib: ['dom', 'dom.iterable', 'ES2022'],
+			allowJs: true,
+			skipLibCheck: true,
+			strict: true,
+			noEmit: true,
+			allowImportingTsExtensions: true,
+			esModuleInterop: true,
+			module: 'ESNext',
+			moduleResolution: 'bundler',
+			resolveJsonModule: true,
+			isolatedModules: true,
+			jsx: 'preserve',
+			incremental: true,
+			baseUrl: '.',
+			types: ['vite/client'],
+			paths: {
+				'~/*': ['./src/*', '../../packages/ui/src/*'],
+				[modelsPackage]: ['../../packages/models/src'],
+				[`${modelsPackage}/*`]: ['../../packages/models/src/*'],
+				[uiPackage]: ['../../packages/ui/src'],
+				[`${uiPackage}/*`]: ['../../packages/ui/src/*'],
+				[`${apiPackage}/client`]: ['../../apps/api/.gkm/openapi.ts'],
+			},
+		},
+		include: ['**/*.ts', '**/*.tsx', 'src/routeTree.gen.ts'],
+		exclude: ['node_modules', '.output', '.vinxi', 'dist'],
+	};
+
+	const queryClientTs = `import { QueryClient } from '@tanstack/react-query';
+
+function makeQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+      },
+    },
+  });
+}
+
+let browserQueryClient: QueryClient | undefined = undefined;
+
+export function getQueryClient() {
+  if (typeof window === 'undefined') {
+    return makeQueryClient();
+  }
+  if (!browserQueryClient) browserQueryClient = makeQueryClient();
+  return browserQueryClient;
+}
+`;
+
+	const clientConfigTs = `import { EnvironmentParser } from '@geekmidas/envkit';
+
+// Client config - VITE_* vars are inlined at build time.
+const envParser = new EnvironmentParser({
+  VITE_API_URL: import.meta.env.VITE_API_URL,
+  VITE_AUTH_URL: import.meta.env.VITE_AUTH_URL,
+});
+
+export const clientConfig = envParser
+  .create((get) => ({
+    apiUrl: get('VITE_API_URL').string(),
+    authUrl: get('VITE_AUTH_URL').string(),
+  }))
+  .parse();
+`;
+
+	const serverConfigTs = `import { EnvironmentParser } from '@geekmidas/envkit';
+
+// Server config - all env vars (server-side only, not exposed to browser).
+// Access these only in TanStack Start server functions / server routes.
+const envParser = new EnvironmentParser({ ...process.env });
+
+export const serverConfig = envParser
+  .create((_get) => ({
+    // Add server-only secrets here
+    // Example: stripeSecretKey: _get('STRIPE_SECRET_KEY').string(),
+  }))
+  .parse();
+`;
+
+	const authClientTs = `import { magicLinkClient } from 'better-auth/client/plugins';
+import { createAuthClient } from 'better-auth/react';
+import { clientConfig } from '~/config/client.ts';
+
+export const authClient = createAuthClient({
+  baseURL: clientConfig.authUrl,
+  plugins: [magicLinkClient()],
+});
+
+export const { signIn, signUp, signOut, useSession, magicLink } = authClient;
+`;
+
+	const apiIndexTs = `import { createApi } from '${apiPackage}/client';
+import { clientConfig } from '~/config/client.ts';
+import { getQueryClient } from '~/lib/query-client.ts';
+
+export function createAppApi(options?: { headers?: Record<string, string> }) {
+  return createApi({
+    baseURL: clientConfig.apiUrl,
+    queryClient: getQueryClient(),
+    headers: options?.headers,
+    onRequest: (config) => ({ ...config, credentials: 'include' }),
+  });
+}
+
+export const api = createAppApi();
+`;
+
+	const routerTs = `import { createRouter } from '@tanstack/react-router';
+import { routeTree } from './routeTree.gen.ts';
+
+export function getRouter() {
+  return createRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreload: 'intent',
+  });
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>;
+  }
+}
+`;
+
+	// Placeholder routeTree.gen — TanStack's plugin regenerates this on dev.
+	const routeTreeGen = `// This file is auto-generated by @tanstack/router-plugin.
+// It will be overwritten on the next \`vite dev\` run.
+import { rootRouteWithContext } from '@tanstack/react-router';
+
+export const routeTree = rootRouteWithContext()({
+  // Routes are populated by the plugin from src/routes/**.tsx
+} as never);
+`;
+
+	const rootRouteTsx = `/// <reference types="vite/client" />
+import '~/styles/globals.css';
+
+import { QueryClientProvider } from '@tanstack/react-query';
+import {
+  HeadContent,
+  Outlet,
+  Scripts,
+  createRootRoute,
+} from '@tanstack/react-router';
+import type { ReactNode } from 'react';
+import { getQueryClient } from '~/lib/query-client.ts';
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      { title: '${options.name}' },
+    ],
+  }),
+  component: RootComponent,
+});
+
+function RootComponent() {
+  const queryClient = getQueryClient();
+  return (
+    <RootDocument>
+      <QueryClientProvider client={queryClient}>
+        <Outlet />
+      </QueryClientProvider>
+    </RootDocument>
+  );
+}
+
+function RootDocument({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+`;
+
+	const indexRouteTsx = `import { createFileRoute } from '@tanstack/react-router';
+import { api } from '~/api/index.ts';
+
+export const Route = createFileRoute('/')({
+  component: HomeComponent,
+});
+
+function HomeComponent() {
+  const { data: health } = api.useQuery('GET /health', {});
+
+  return (
+    <main className="min-h-screen bg-background p-8">
+      <div className="mx-auto max-w-4xl space-y-8">
+        <div className="space-y-2">
+          <h1 className="text-4xl font-bold tracking-tight">
+            Welcome to ${options.name}
+          </h1>
+          <p className="text-muted-foreground">
+            Your TanStack Start app is ready.
+          </p>
+        </div>
+
+        <section className="rounded-lg border p-6">
+          <h2 className="text-xl font-semibold">API Status</h2>
+          {health ? (
+            <pre className="mt-4 rounded bg-muted p-4 text-sm">
+              {JSON.stringify(health, null, 2)}
+            </pre>
+          ) : (
+            <p className="mt-2 text-muted-foreground">Connecting…</p>
+          )}
+        </section>
+      </div>
+    </main>
+  );
+}
+`;
+
+	const globalsCss = `@import '${uiPackage}/styles';
+
+@source "../..";
+@source "../../../../packages/ui/src";
+`;
+
+	const gitignore = `.output/
+.vinxi/
+node_modules/
+.env.local
+*.log
+src/routeTree.gen.ts
+`;
+
+	return [
+		{
+			path: 'apps/web/package.json',
+			content: `${JSON.stringify(packageJson, null, 2)}\n`,
+		},
+		{ path: 'apps/web/vite.config.ts', content: viteConfig },
+		{
+			path: 'apps/web/tsconfig.json',
+			content: `${JSON.stringify(tsConfig, null, 2)}\n`,
+		},
+		{ path: 'apps/web/src/lib/query-client.ts', content: queryClientTs },
+		{ path: 'apps/web/src/lib/auth-client.ts', content: authClientTs },
+		{ path: 'apps/web/src/config/client.ts', content: clientConfigTs },
+		{ path: 'apps/web/src/config/server.ts', content: serverConfigTs },
+		{ path: 'apps/web/src/api/index.ts', content: apiIndexTs },
+		{ path: 'apps/web/src/router.tsx', content: routerTs },
+		{ path: 'apps/web/src/routeTree.gen.ts', content: routeTreeGen },
+		{ path: 'apps/web/src/routes/__root.tsx', content: rootRouteTsx },
+		{ path: 'apps/web/src/routes/index.tsx', content: indexRouteTsx },
+		{ path: 'apps/web/src/styles/globals.css', content: globalsCss },
+		{ path: 'apps/web/.gitignore', content: gitignore },
+	];
+}

package/src/init/index.ts

@@ -17,6 +17,7 @@ import {
 	generateDockerFiles,
 } from './generators/docker.js';
 import { generateEnvFiles } from './generators/env.js';
+import { generateExpoAppFiles } from './generators/mobile-expo.js';
 import { generateModelsPackage } from './generators/models.js';
 import { generateMonorepoFiles } from './generators/monorepo.js';
 import { generatePackageJson } from './generators/package.js';
@@ -24,10 +25,13 @@ import { generateSourceFiles } from './generators/source.js';
 import { generateTestFiles } from './generators/test.js';
 import { generateUiPackageFiles } from './generators/ui.js';
 import { generateWebAppFiles } from './generators/web.js';
+import { generateTanStackWebFiles } from './generators/web-tanstack.js';
 import {
 	type DeployTarget,
 	deployTargetChoices,
 	eventsBackendChoices,
+	type FullstackFrontendFramework,
+	frontendFrameworkChoices,
 	getTemplate,
 	isFullstackTemplate,
 	loggerTypeChoices,
@@ -154,6 +158,18 @@ export async function initCommand(
 				choices: routesStructureChoices,
 				initial: 0,
 			},
+			{
+				// Only prompt for frontend framework on the fullstack template.
+				type: (_prev, values) =>
+					!options.yes &&
+					(options.template === 'fullstack' || values.template === 'fullstack')
+						? 'select'
+						: null,
+				name: 'frontendFramework',
+				message: 'Frontend framework:',
+				choices: frontendFrameworkChoices,
+				initial: 0,
+			},
 		],
 		{ onCancel },
 	);
@@ -221,6 +237,11 @@ export async function initCommand(
 		: (answers.deployTarget ?? 'dokploy');
 
 	const database = services.db;
+	const frontendFramework: FullstackFrontendFramework | undefined = isFullstack
+		? options.yes
+			? 'nextjs'
+			: (answers.frontendFramework ?? 'nextjs')
+		: undefined;
 	const templateOptions: TemplateOptions = {
 		name,
 		template,
@@ -236,6 +257,7 @@ export async function initCommand(
 		packageManager: pkgManager,
 		deployTarget,
 		services,
+		frontendFramework,
 	};
 
 	const targetDir = join(cwd, name);
@@ -293,8 +315,14 @@ export async function initCommand(
 			]
 		: [];
 
-	// Collect web app files for fullstack template
-	const webAppFiles = isFullstack ? generateWebAppFiles(templateOptions) : [];
+	// Collect frontend app files for fullstack template, dispatched by framework
+	const webAppFiles = isFullstack
+		? frontendFramework === 'tanstack-start'
+			? generateTanStackWebFiles(templateOptions)
+			: frontendFramework === 'expo'
+				? generateExpoAppFiles(templateOptions)
+				: generateWebAppFiles(templateOptions)
+		: [];
 
 	// Collect auth app files for fullstack template
 	const authAppFiles = isFullstack ? generateAuthAppFiles(templateOptions) : [];
@@ -473,7 +501,16 @@ function printNextSteps(
 		console.log(`  │   ├── api/          # Backend API`);
 		if (isFullstackTemplate(options.template)) {
 			console.log(`  │   ├── auth/         # Auth service (better-auth)`);
-			console.log(`  │   └── web/          # Next.js frontend`);
+			switch (options.frontendFramework) {
+				case 'tanstack-start':
+					console.log(`  │   └── web/          # TanStack Start frontend`);
+					break;
+				case 'expo':
+					console.log(`  │   └── app/          # Expo (React Native) app`);
+					break;
+				default:
+					console.log(`  │   └── web/          # Next.js frontend`);
+			}
 		}
 		console.log(`  ├── packages/`);
 		console.log(`  │   ├── models/       # Shared Zod schemas`);

package/src/init/templates/index.ts

@@ -47,6 +47,14 @@ export interface ServicesSelection {
 	events?: import('../../types.js').EventsBackend;
 }
 
+/**
+ * Frontend framework for the fullstack template's client app.
+ * Limited to the three with first-class scaffolds; the wider
+ * `FrontendFramework` type also covers `vite` and `remix` which
+ * users can configure manually after init.
+ */
+export type FullstackFrontendFramework = 'nextjs' | 'tanstack-start' | 'expo';
+
 /**
  * Options collected from user prompts
  */
@@ -67,6 +75,8 @@ export interface TemplateOptions {
 	deployTarget: DeployTarget;
 	/** Services selection */
 	services: ServicesSelection;
+	/** Frontend framework (fullstack template only) */
+	frontendFramework?: FullstackFrontendFramework;
 }
 
 /**
@@ -156,6 +166,27 @@ export const allTemplateChoices = [
 	},
 ];
 
+/**
+ * Frontend framework choices for the fullstack template prompt.
+ */
+export const frontendFrameworkChoices = [
+	{
+		title: 'Next.js',
+		value: 'nextjs' as FullstackFrontendFramework,
+		description: 'React server components, app router (default)',
+	},
+	{
+		title: 'TanStack Start',
+		value: 'tanstack-start' as FullstackFrontendFramework,
+		description: 'File-based router on Vite + Nitro',
+	},
+	{
+		title: 'Expo',
+		value: 'expo' as FullstackFrontendFramework,
+		description: 'React Native mobile app (iOS + Android)',
+	},
+];
+
 /**
  * Logger type choices for prompts
  */

package/src/init/versions.ts

@@ -35,9 +35,9 @@ export const GEEKMIDAS_VERSIONS = {
 	'@geekmidas/constructs': '~3.0.9',
 	'@geekmidas/db': '~1.0.1',
 	'@geekmidas/emailkit': '~1.0.0',
-	'@geekmidas/envkit': '~1.0.5',
+	'@geekmidas/envkit': '~1.0.6',
 	'@geekmidas/errors': '~1.0.0',
-	'@geekmidas/events': '~1.1.0',
+	'@geekmidas/events': '~1.1.1',
 	'@geekmidas/logger': '~1.0.1',
 	'@geekmidas/rate-limit': '~2.0.0',
 	'@geekmidas/schema': '~1.0.0',

package/src/openapi.ts

@@ -1,15 +1,25 @@
 #!/usr/bin/env -S npx tsx
 
+import { spawn } from 'node:child_process';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { loadWorkspaceConfig } from './config.js';
 import { EndpointGenerator } from './generators/EndpointGenerator.js';
 import { OpenApiTsGenerator } from './generators/OpenApiTsGenerator.js';
 import type { GkmConfig, OpenApiConfig } from './types.js';
 import { normalizeRoutes } from './workspace/client-generator.js';
+import type { NormalizedAppConfig } from './workspace/types.js';
 
 interface OpenAPIOptions {
 	cwd?: string;
+	/**
+	 * Workspace mode: generate for a single named backend app. When set,
+	 * generation runs in-process against the current CWD. When unset,
+	 * workspace mode spawns one subprocess per backend app so each gets a
+	 * fresh tsx that loads the app's own tsconfig (path aliases included).
+	 */
+	app?: string;
 }
 
 /**
@@ -132,37 +142,114 @@ export async function openapiCommand(
 				return;
 			}
 
-			// Generate OpenAPI for each backend app
-			for (const [appName, app] of backendApps) {
-				if (app.type !== 'backend' || !app.routes) continue;
-
-				const appPath = join(workspaceRoot, app.path);
-				const routes = normalizeRoutes(app.routes);
-				const routesGlob = routes.map((r) => join(appPath, r));
-
-				const gkmConfig: GkmConfig = {
-					routes: routesGlob,
-					envParser: app.envParser || '',
-					logger: app.logger || '',
-					openapi: app.openapi,
-				};
-
-				// Change to app directory for generation
-				const originalCwd = process.cwd();
-				process.chdir(appPath);
-
-				const result = await generateOpenApi(gkmConfig, { silent: true });
-
-				process.chdir(originalCwd);
-
+			// Single-app mode: generate in-process. The caller is expected to
+			// have CWD set to the app's directory (e.g., when invoked as a
+			// subprocess), so tsx picks up the app's tsconfig path aliases.
+			if (options.app) {
+				const entry = backendApps.find(([name]) => name === options.app);
+				if (!entry) {
+					throw new Error(
+						`App "${options.app}" not found or has OpenAPI disabled`,
+					);
+				}
+				const [appName, app] = entry;
+				const result = await generateOpenApiForApp(workspaceRoot, appName, app);
 				if (result) {
 					logger.log(
 						`📄 [${appName}] Generated OpenAPI (${result.endpointCount} endpoints)`,
 					);
 				}
+				return;
+			}
+
+			// Multi-app mode: spawn a subprocess per backend app. Each
+			// subprocess starts with CWD at the app's directory so that
+			// tsx's tsconfig discovery picks up the app's `paths` aliases
+			// (e.g., `~/*`) instead of the workspace root's tsconfig.
+			for (const [appName, app] of backendApps) {
+				if (app.type !== 'backend' || !app.routes) continue;
+				const appPath = join(workspaceRoot, app.path);
+				await runOpenApiInSubprocess(appPath, appName);
 			}
 		}
 	} catch (error) {
 		throw new Error(`OpenAPI generation failed: ${(error as Error).message}`);
 	}
 }
+
+/**
+ * Generate OpenAPI for a single named app within a workspace.
+ * Runs in-process. The caller is responsible for ensuring `process.cwd()`
+ * is the app's directory so tsx loads the app's tsconfig path aliases.
+ */
+async function generateOpenApiForApp(
+	workspaceRoot: string,
+	_appName: string,
+	app: NormalizedAppConfig,
+): Promise<{ outputPath: string; endpointCount: number } | null> {
+	if (app.type !== 'backend' || !app.routes) {
+		return null;
+	}
+
+	const appPath = join(workspaceRoot, app.path);
+	const routes = normalizeRoutes(app.routes);
+	const routesGlob = routes.map((r) => join(appPath, r));
+
+	const gkmConfig: GkmConfig = {
+		routes: routesGlob,
+		envParser: app.envParser || '',
+		logger: app.logger || '',
+		openapi: app.openapi,
+	};
+
+	return generateOpenApi(gkmConfig, { silent: true });
+}
+
+/**
+ * Resolve the gkm bin path. Tests can override via `GKM_BIN_PATH` env var
+ * to avoid depending on the built dist.
+ */
+function resolveGkmBinPath(): string {
+	if (process.env.GKM_BIN_PATH) {
+		return process.env.GKM_BIN_PATH;
+	}
+	return fileURLToPath(new URL('../bin/gkm.mjs', import.meta.url));
+}
+
+/**
+ * Spawn a subprocess that runs `gkm openapi --app <name>` with `cwd` set to
+ * the app's directory. Inherits `NODE_OPTIONS` (which already contains
+ * `--import tsx`), so the child gets a fresh tsx instance whose tsconfig
+ * discovery picks up the app's tsconfig path aliases.
+ */
+async function runOpenApiInSubprocess(
+	appCwd: string,
+	appName: string,
+): Promise<void> {
+	const binPath = resolveGkmBinPath();
+
+	await new Promise<void>((resolve, reject) => {
+		const child = spawn(
+			process.execPath,
+			[binPath, 'openapi', '--app', appName],
+			{
+				cwd: appCwd,
+				stdio: 'inherit',
+				env: process.env,
+			},
+		);
+
+		child.on('error', reject);
+		child.on('close', (code) => {
+			if (code === 0) {
+				resolve();
+			} else {
+				reject(
+					new Error(
+						`OpenAPI generation for app "${appName}" exited with code ${code}`,
+					),
+				);
+			}
+		});
+	});
+}