codz-cli 0.0.0-stage → 0.1.2

package/dist/adapters/reactNative.js

@@ -0,0 +1,109 @@
+// React Native adapter (Expo or the React Native CLI). API code is TypeScript
+// like in Next.js, so scanning and generating endpoints reuse the Next.js
+// adapter: fetch (directly or through a helper), axios, TanStack Query hooks,
+// interfaces for models. On top of that this adapter knows React Native's own
+// parts: the flavor (Expo or bare), navigation (React Navigation or Expo
+// Router), the screens folder, and the config file that holds the API URL.
+import { join } from 'node:path';
+import { exists, isDir, readJson, readText, walk } from "../core/fsutil.js";
+import { NEXT_CONVENTION_DOCS, nextjsAdapter } from "./nextjs.js";
+import { mostCommon } from "./nextjsScan.js";
+import { planReactNativeSetup, reactNativeArchitectures } from "./reactNativeSetup.js";
+export const RN_VERSION = '0.1.0';
+const { appDir: _appDir, ...SHARED_DOCS } = NEXT_CONVENTION_DOCS;
+export const RN_CONVENTION_DOCS = {
+    ...SHARED_DOCS,
+    flavor: 'expo or bare (React Native CLI)',
+    router: 'react-navigation, expo-router or none',
+    screensFolder: 'where screen components live',
+    navigatorFile: 'the React Navigation stack that lists the screens (react-navigation only)',
+    routerDir: 'the Expo Router app folder (expo-router only)',
+    configFile: 'file that exports API_URL and USE_MOCKS',
+};
+const NAVIGATOR = /create(?:NativeStack|Stack|BottomTab|Drawer)Navigator\s*(?:<[^>]*>)?\s*\(/;
+/** React Navigation screens: <Stack.Screen name="Orders" component={OrdersScreen} />. */
+function navigationRoutes(file, text) {
+    const out = [];
+    for (const m of text.matchAll(/<\w+\.Screen\b([^>]*?)\/?>/g)) {
+        const name = /\bname\s*=\s*["'{]\s*["']?([\w-]+)/.exec(m[1])?.[1];
+        if (!name)
+            continue;
+        const params = new RegExp(`\\b${name}\\s*:\\s*\\{([^}]*)\\}`).exec(text)?.[1]?.split(/[;,]/).map((p) => p.split(':')[0].replace(/\?$/, '').trim()).filter(Boolean) ?? [];
+        out.push({ name, path: name, params, file });
+    }
+    return out;
+}
+/** Expo Router: every file under app/ except layouts is a route; [id] segments are parameters. */
+function expoRoutes(routerDir, files) {
+    return files
+        .filter((f) => f.startsWith(`${routerDir}/`) && /\.(tsx|jsx|ts|js)$/.test(f) && !/(^|\/)(_layout|\+[\w-]+)\.\w+$/.test(f))
+        .map((f) => {
+        const segs = f.slice(routerDir.length + 1).replace(/\.\w+$/, '').split('/').filter((s) => !/^\(.*\)$/.test(s));
+        if (segs[segs.length - 1] === 'index')
+            segs.pop();
+        const params = segs.filter((s) => s.startsWith('[')).map((s) => s.replace(/[[\].]/g, ''));
+        const path = '/' + segs.map((s) => (s.startsWith('[') ? `{${s.replace(/[[\].]/g, '')}}` : s)).join('/');
+        return { name: segs.filter((s) => !s.startsWith('[')).join('-') || 'home', path: path === '/' ? '/' : path, params, file: f };
+    });
+}
+async function scan(root, configConventions) {
+    const map = await nextjsAdapter.scan(root, configConventions);
+    map.framework = 'react-native';
+    map.adapter = `react-native@${RN_VERSION}`;
+    map.notes = map.notes.filter((n) => !/app folder|Pages Router/.test(n));
+    map.routes = [];
+    const pkg = readJson(join(root, 'package.json')) ?? {};
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const files = walk(root, '.', { exts: ['.ts', '.tsx', '.js', '.jsx'], extraIgnored: ['android', 'ios'] });
+    const text = (f) => readText(join(root, f)) ?? '';
+    const src = isDir(join(root, 'src')) ? 'src/' : '';
+    const c = {};
+    c.flavor = deps.expo ? 'expo' : 'bare';
+    const routerDir = isDir(join(root, 'src/app')) ? 'src/app' : isDir(join(root, 'app')) ? 'app' : '';
+    const navigatorFile = files.find((f) => NAVIGATOR.test(text(f)) && /\.Navigator\b/.test(text(f))) ?? '';
+    c.router = deps['expo-router'] && routerDir ? 'expo-router' : deps['@react-navigation/native'] ? 'react-navigation' : 'none';
+    c.routerDir = c.router === 'expo-router' ? routerDir : '';
+    c.navigatorFile = c.router === 'react-navigation' ? navigatorFile || `${src}navigation/RootNavigator.tsx` : '';
+    const screenFiles = files.filter((f) => /Screen\.(tsx|jsx)$/.test(f));
+    c.screensFolder = mostCommon(screenFiles.map((f) => f.slice(0, f.lastIndexOf('/'))), `${src}screens`);
+    c.configFile = files.find((f) => /export\s+const\s+API_URL\b/.test(text(f))) ?? `${src}config/env.ts`;
+    // An API folder that was only guessed follows React Native layouts (src/api), not Next.js (lib/api).
+    const guessed = !map.endpoints.length && !configConventions.apiFolder && !exists(join(root, map.conventions.apiFolder ?? ''));
+    if (guessed)
+        c.apiFolder = `${src}api`;
+    if (!map.models.length && !configConventions.modelsFolder && !exists(join(root, map.conventions.modelsFolder ?? '')))
+        c.modelsFolder = `${src}types`;
+    if (map.conventions.dataFetching === 'react-query' && !configConventions.hooksFolder && !exists(join(root, map.conventions.hooksFolder ?? '')))
+        c.hooksFolder = `${src}hooks`;
+    const conv = (map.conventions = { ...map.conventions, ...c, ...configConventions });
+    delete conv.appDir;
+    // The API URL in the config file (a literal, or the fallback after ??) is a base URL too.
+    const cfgText = conv.configFile ? readText(join(root, conv.configFile)) ?? '' : '';
+    const cfgUrl = /export\s+const\s+API_URL\s*=\s*(?:[^'"\n]*\?\?\s*)?['"](https?:\/\/[^'"]+)['"]/.exec(cfgText)?.[1];
+    if (cfgUrl && !map.baseUrls.some((b) => b.value === cfgUrl))
+        map.baseUrls.push({ name: 'API_URL', value: cfgUrl, file: conv.configFile });
+    if (conv.router === 'expo-router' && conv.routerDir)
+        map.routes = expoRoutes(conv.routerDir, files);
+    else if (conv.router === 'react-navigation')
+        for (const f of files.filter((x) => /\.Screen\b/.test(text(x))))
+            map.routes.push(...navigationRoutes(f, text(f)));
+    map.routes.sort((a, b) => a.path.localeCompare(b.path));
+    if (conv.router === 'none')
+        map.notes.push('No navigation library found; screen add and route add need React Navigation or Expo Router (codz setup adds React Navigation).');
+    return map;
+}
+export const reactNativeAdapter = {
+    id: 'react-native',
+    version: RN_VERSION,
+    capabilities: { explain: true, apiAdd: true },
+    supportedSetup: 'React Native (Expo or React Native CLI), TypeScript, fetch (directly or through a helper) or axios, optionally TanStack Query; React Navigation or Expo Router.',
+    scan,
+    planEndpoint: nextjsAdapter.planEndpoint,
+    architectures: reactNativeArchitectures,
+    planSetup: planReactNativeSetup,
+    afterSetup(root) {
+        return exists(join(root, 'package.json')) ? { cmd: process.platform === 'win32' ? 'npm.cmd' : 'npm', args: ['install'], label: 'npm install' } : null;
+    },
+    formatCommand: nextjsAdapter.formatCommand,
+    verifyCommand: nextjsAdapter.verifyCommand,
+};

package/dist/adapters/reactNativeSetup.js

@@ -0,0 +1,236 @@
+// React Native `setup`: an API layer (and navigation, when there is none) for
+// a project that has neither yet.
+//
+//   fetch-helper        src/api/client.ts with apiFetch<T>() and ApiError
+//   axios               src/api/client.ts exporting an axios instance
+//   axios-react-query   the axios instance plus TanStack Query (QueryClientProvider)
+//
+// The API URL and the mocks switch live in src/config/env.ts: read from
+// EXPO_PUBLIC_API_URL in Expo, a constant in the React Native CLI (where
+// react-native-config is the usual next step). Without navigation, React
+// Navigation's native stack is added with a Home screen, so screen add works.
+import { join } from 'node:path';
+import { readJson, readText } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+/** Versions known to work with the generated code (React Native 0.76+ / Expo SDK 52+). */
+const PACKAGES = {
+    axios: '^1.7.7',
+    '@tanstack/react-query': '^5.59.0',
+    '@react-navigation/native': '^7.0.0',
+    '@react-navigation/native-stack': '^7.0.0',
+    'react-native-screens': '^4.0.0',
+    'react-native-safe-area-context': '^4.12.0',
+};
+export function reactNativeArchitectures(map) {
+    const c = map.conventions;
+    if (map.endpoints.length > 0 || (c.httpHelper && c.httpHelper !== 'fetch') || c.http === 'axios')
+        return [];
+    return [
+        { id: 'fetch-helper', label: 'Fetch helper', description: 'src/api/client.ts with apiFetch<T>() and ApiError; API URL in src/config/env.ts', recommended: true },
+        { id: 'axios', label: 'axios', description: 'An axios instance in src/api/client.ts; API functions call it', recommended: false },
+        { id: 'axios-react-query', label: 'axios + TanStack Query', description: 'The axios instance, plus a query hook for every endpoint and QueryClientProvider around the app', recommended: false },
+    ];
+}
+function envFile(expo, baseUrl, q, semi) {
+    const L = expo
+        ? [
+            '// App settings. Expo reads EXPO_PUBLIC_* variables from .env at build time.',
+            `export const API_URL = process.env.EXPO_PUBLIC_API_URL ?? ${q}${baseUrl}${q}${semi}`,
+            '',
+            '/** Answer API calls from mocks (codz mock add). Set EXPO_PUBLIC_USE_MOCKS=true in .env. */',
+            `export const USE_MOCKS = process.env.EXPO_PUBLIC_USE_MOCKS === ${q}true${q}${semi}`,
+        ]
+        : [
+            '// App settings. For per-build values, move these to react-native-config.',
+            `export const API_URL = ${q}${baseUrl}${q}${semi}`,
+            '',
+            '/** Answer API calls from mocks (codz mock add). */',
+            `export const USE_MOCKS = false${semi}`,
+        ];
+    return L.join('\n') + '\n';
+}
+export function fetchClient(q, semi) {
+    return [
+        `import { API_URL } from ${q}../config/env${q}${semi}`,
+        '',
+        '/** Thrown when the API answers with a status outside 200-299. */',
+        'export class ApiError extends Error {',
+        `  status: number${semi}`,
+        '',
+        '  constructor(status: number, message: string) {',
+        `    super(message)${semi}`,
+        `    this.status = status${semi}`,
+        '  }',
+        '}',
+        '',
+        '/** Calls the API and parses the JSON response. Add auth headers here. */',
+        'export async function apiFetch<T>(path: string, init: RequestInit = {}): Promise<T> {',
+        '  const res = await fetch(`${API_URL}${path}`, {',
+        '    ...init,',
+        `    headers: { ${q}Content-Type${q}: ${q}application/json${q}, ...init.headers },`,
+        `  })${semi}`,
+        `  if (!res.ok) throw new ApiError(res.status, await res.text())${semi}`,
+        `  if (res.status === 204) return undefined as T${semi}`,
+        `  return (await res.json()) as T${semi}`,
+        '}',
+        '',
+    ].join('\n');
+}
+export function axiosClient(q, semi) {
+    return [
+        `import axios from ${q}axios${q}${semi}`,
+        `import { API_URL } from ${q}../config/env${q}${semi}`,
+        '',
+        '/** The axios instance every API function uses. Add auth headers with an interceptor. */',
+        'export const api = axios.create({',
+        '  baseURL: API_URL,',
+        '  timeout: 20000,',
+        `  headers: { ${q}Content-Type${q}: ${q}application/json${q} },`,
+        `})${semi}`,
+        '',
+    ].join('\n');
+}
+function navigator(q, semi) {
+    return [
+        `import { createNativeStackNavigator } from ${q}@react-navigation/native-stack${q}${semi}`,
+        `import HomeScreen from ${q}../screens/HomeScreen${q}${semi}`,
+        '',
+        '/** Every screen and its parameters. codz route add and screen add add entries here. */',
+        'export type RootStackParamList = {',
+        `  Home: undefined${semi}`,
+        `}${semi}`,
+        '',
+        `const Stack = createNativeStackNavigator<RootStackParamList>()${semi}`,
+        '',
+        'export default function RootNavigator() {',
+        '  return (',
+        '    <Stack.Navigator>',
+        `      <Stack.Screen name=${'"'}Home${'"'} component={HomeScreen} />`,
+        '    </Stack.Navigator>',
+        `  )${semi}`,
+        '}',
+        '',
+    ].join('\n');
+}
+function homeScreen(semi) {
+    return [
+        `import { StyleSheet, Text, View } from 'react-native'${semi}`,
+        '',
+        'export default function HomeScreen() {',
+        '  return (',
+        '    <View style={styles.container}>',
+        '      <Text>Home</Text>',
+        '    </View>',
+        `  )${semi}`,
+        '}',
+        '',
+        'const styles = StyleSheet.create({',
+        "  container: { flex: 1, alignItems: 'center', justifyContent: 'center' },",
+        `})${semi}`,
+        '',
+    ].join('\n');
+}
+function appFile(nav, query, semi) {
+    const imports = [
+        ...(nav ? [`import { NavigationContainer } from '@react-navigation/native'${semi}`] : [`import { Text, View } from 'react-native'${semi}`]),
+        ...(query ? [`import { QueryClient, QueryClientProvider } from '@tanstack/react-query'${semi}`] : []),
+        ...(nav ? [`import RootNavigator from './src/navigation/RootNavigator'${semi}`] : []),
+    ];
+    let body = nav ? '<NavigationContainer>\n      <RootNavigator />\n    </NavigationContainer>' : '<View style={{ flex: 1, alignItems: \'center\', justifyContent: \'center\' }}>\n      <Text>Home</Text>\n    </View>';
+    if (query)
+        body = `<QueryClientProvider client={queryClient}>\n      ${body.replace(/\n/g, '\n  ')}\n    </QueryClientProvider>`;
+    return [...imports, '', ...(query ? [`const queryClient = new QueryClient()${semi}`, ''] : []), 'export default function App() {', '  return (', `    ${body}`, `  )${semi}`, '}', ''].join('\n');
+}
+export function planReactNativeSetup(ctx, choice) {
+    const { root, map } = ctx;
+    if (!['fetch-helper', 'axios', 'axios-react-query'].includes(choice.architecture))
+        throw new ToolError('bad_args', `Unknown architecture "${choice.architecture}". Choose fetch-helper, axios or axios-react-query.`);
+    const c0 = map.conventions;
+    const expo = c0.flavor === 'expo';
+    const src = 'src';
+    const q = c0.quote === 'double' ? '"' : "'";
+    const semi = c0.semicolons === 'false' ? '' : ';';
+    const baseUrl = choice.baseUrl || 'https://api.example.com';
+    const files = new Map();
+    const rewrites = [];
+    const summary = [];
+    const warnings = [];
+    if (!choice.baseUrl)
+        warnings.push(`No base URL was given, so ${src}/config/env.ts uses https://api.example.com. Change it there before calling the API.`);
+    const read = (p) => readText(join(root, p));
+    const create = (path, content, what) => {
+        if (read(path) !== null)
+            throw new ToolError('file_exists', `${path} already exists, so setup stopped without changing anything.`, 'Remove or rename it, or set up the project by hand and run codz init again.');
+        files.set(path, content);
+        summary.push(`Create ${path}: ${what}`);
+    };
+    const axios = choice.architecture !== 'fetch-helper';
+    const query = choice.architecture === 'axios-react-query';
+    const nav = c0.router === 'none' || !c0.router;
+    create(`${src}/config/env.ts`, envFile(expo, baseUrl, q, semi), expo ? 'API_URL from EXPO_PUBLIC_API_URL, and USE_MOCKS' : 'API_URL and USE_MOCKS');
+    create(`${src}/api/client.ts`, axios ? axiosClient(q, semi) : fetchClient(q, semi), axios ? 'the axios instance (baseURL from API_URL)' : 'apiFetch<T>() and ApiError');
+    if (!axios)
+        create(`${src}/api/index.ts`, `export * from ${q}./client${q}${semi}\n`, 'exports every API file');
+    if (expo) {
+        const env = read('.env.example');
+        files.set('.env.example', `${env ? env.replace(/\s*$/, '\n') : ''}EXPO_PUBLIC_API_URL=${baseUrl}\nEXPO_PUBLIC_USE_MOCKS=false\n`);
+        summary.push('Update .env.example: EXPO_PUBLIC_API_URL and EXPO_PUBLIC_USE_MOCKS');
+    }
+    if (nav) {
+        create(`${src}/navigation/RootNavigator.tsx`, navigator(q, semi), 'React Navigation native stack with RootStackParamList');
+        create(`${src}/screens/HomeScreen.tsx`, homeScreen(semi), 'the first screen');
+    }
+    if (nav || query) {
+        const app = ['App.tsx', 'App.js'].find((f) => read(f) !== null) ?? 'App.tsx';
+        if (c0.router === 'expo-router') {
+            warnings.push(`This project uses Expo Router; wrap the root layout in <QueryClientProvider client={new QueryClient()}> yourself.`);
+        }
+        else {
+            files.set(app, appFile(nav, query, semi));
+            rewrites.push(app); // replaced on purpose; the previous App is in codz undo
+            summary.push(`${read(app) === null ? 'Create' : 'Replace'} ${app}: ${[nav && 'NavigationContainer with RootNavigator', query && 'QueryClientProvider'].filter(Boolean).join(' and ')}${read(app) !== null ? ' (the previous App is in codz undo)' : ''}`);
+        }
+    }
+    // Dependencies.
+    const pkgText = read('package.json');
+    let dependenciesChanged = false;
+    if (pkgText !== null) {
+        const pkg = readJson(join(root, 'package.json')) ?? {};
+        const want = [...(axios ? ['axios'] : []), ...(query ? ['@tanstack/react-query'] : []), ...(nav ? ['@react-navigation/native', '@react-navigation/native-stack', 'react-native-screens', 'react-native-safe-area-context'] : [])];
+        const missing = want.filter((p) => !pkg.dependencies?.[p] && !pkg.devDependencies?.[p]);
+        if (missing.length) {
+            const parsed = JSON.parse(pkgText);
+            parsed.dependencies = { ...parsed.dependencies };
+            for (const p of missing)
+                parsed.dependencies[p] = PACKAGES[p];
+            parsed.dependencies = Object.fromEntries(Object.entries(parsed.dependencies).sort(([a], [b]) => a.localeCompare(b)));
+            files.set('package.json', JSON.stringify(parsed, null, 2) + '\n');
+            summary.push(`Update package.json: add ${missing.join(', ')}`);
+            dependenciesChanged = true;
+            if (expo)
+                warnings.push('Run npx expo install --fix after installing, so the native packages match your Expo SDK.');
+            else if (nav)
+                warnings.push('react-native-screens and react-native-safe-area-context are native: run cd ios && pod install after npm install.');
+        }
+    }
+    const conventions = {
+        ...c0,
+        http: axios ? 'axios' : 'fetch',
+        httpHelper: axios ? 'fetch' : 'apiFetch',
+        httpHelperFile: axios ? '' : `${src}/api/client.ts`,
+        apiFolder: `${src}/api`,
+        modelsFolder: `${src}/types`,
+        modelsLayout: 'per-file',
+        configFile: `${src}/config/env.ts`,
+        screensFolder: `${src}/screens`,
+        ...(axios ? { axiosInstance: 'api', axiosInstanceFile: `${src}/api/client.ts` } : {}),
+        ...(query ? { dataFetching: 'react-query', hooksFolder: `${src}/hooks` } : {}),
+        ...(nav ? { router: 'react-navigation', navigatorFile: `${src}/navigation/RootNavigator.tsx`, routerDir: '' } : {}),
+    };
+    if (!axios)
+        for (const k of ['axiosInstance', 'axiosInstanceFile'])
+            delete conventions[k];
+    delete conventions.baseUrlEnv;
+    summary.push(`Save conventions: API functions in ${src}/api, interfaces in ${src}/types, screens in ${src}/screens`);
+    return { files, summary, warnings, generated: [], conventions, dependenciesChanged, rewrites };
+}

package/dist/adapters/reactQuery.js

@@ -0,0 +1,89 @@
+// TanStack Query hooks for Next.js API functions (dataFetching: react-query).
+//
+//   GET      useQuery with a key of [resource, ...path params, query params]
+//   others   useMutation whose success invalidates the resource's queries
+//
+// One hooks file per API file: the hooks file that already imports from it,
+// otherwise use-<resource>.ts in the hooks folder.
+import { commentText, jsString } from "../core/safe.js";
+import { pascal } from "../input/naming.js";
+/** Splits a TypeScript parameter list at top-level commas. */
+export function splitTsParams(params) {
+    const parts = [];
+    let depth = 0;
+    let cur = '';
+    for (const ch of params) {
+        if ('{[(<'.includes(ch))
+            depth++;
+        else if ('}])>'.includes(ch))
+            depth--;
+        if (ch === ',' && depth === 0) {
+            parts.push(cur);
+            cur = '';
+        }
+        else
+            cur += ch;
+    }
+    if (cur.trim())
+        parts.push(cur);
+    return parts
+        .map((p) => p.trim())
+        .filter(Boolean)
+        .map((p) => {
+        const m = /^(\w+)(\??)\s*:\s*([\s\S]+)$/.exec(p);
+        return m ? { name: m[1], optional: m[2] === '?', type: m[3].trim() } : { name: p, optional: false, type: 'unknown' };
+    });
+}
+/** useUser for getUser, useUsers for listUsers? No: only a leading "get" is dropped (getUser → useUser, listUsers → useListUsers). */
+export function hookName(fn) {
+    const rest = /^get[A-Z]/.test(fn) ? fn.slice(3) : fn;
+    return `use${pascal(rest)}`;
+}
+export function renderQueryHook(spec, fn, params, resourceKey, s) {
+    const name = hookName(fn);
+    const { q, semi } = s;
+    const i1 = s.indent;
+    const i2 = s.indent.repeat(2);
+    const sig = params.map((p) => `${p.name}${p.optional ? '?' : ''}: ${p.type}`).join(', ');
+    const names = params.map((p) => p.name);
+    if (spec.method === 'GET') {
+        const key = [jsString(resourceKey, q), ...names].join(', ');
+        return {
+            name,
+            uses: ['useQuery'],
+            code: [
+                `/** ${spec.method} ${commentText(spec.path)} */`,
+                `export function ${name}(${sig}) {`,
+                `${i1}return useQuery({`,
+                `${i2}queryKey: [${key}],`,
+                `${i2}queryFn: () => ${fn}(${names.join(', ')}),`,
+                `${i1}})${semi}`,
+                '}',
+            ].join('\n'),
+        };
+    }
+    let vars = '()';
+    let call = `${fn}()`;
+    if (params.length === 1) {
+        vars = `(${params[0].name}: ${params[0].type}${params[0].optional ? ' | undefined' : ''})`;
+        call = `${fn}(${params[0].name})`;
+    }
+    else if (params.length > 1) {
+        vars = `({ ${names.join(', ')} }: { ${params.map((p) => `${p.name}${p.optional ? '?' : ''}: ${p.type}`).join('; ')} })`;
+        call = `${fn}(${names.join(', ')})`;
+    }
+    return {
+        name,
+        uses: ['useMutation', 'useQueryClient'],
+        code: [
+            `/** ${spec.method} ${commentText(spec.path)} */`,
+            `export function ${name}() {`,
+            `${i1}const queryClient = useQueryClient()${semi}`,
+            `${i1}return useMutation({`,
+            `${i2}mutationFn: ${vars} => ${call},`,
+            `${i2}onSuccess: () => queryClient.invalidateQueries({ queryKey: [${jsString(resourceKey, q)}] }),`,
+            `${i1}})${semi}`,
+            '}',
+        ].join('\n'),
+    };
+}

package/dist/adapters/reactSetup.js

@@ -0,0 +1,150 @@
+// React web `setup`: an API layer (and React Router, when there is none) for a
+// Vite or Create React App project that has neither yet.
+//
+//   fetch-helper        src/api/client.ts with apiFetch<T>() and ApiError
+//   axios               src/api/client.ts exporting an axios instance
+//   axios-react-query   the axios instance plus TanStack Query (QueryClientProvider)
+//
+// The API URL lives in src/config/env.ts, read from VITE_API_URL (Vite) or
+// REACT_APP_API_URL (Create React App). Without a router, React Router's
+// createBrowserRouter is added in src/router.tsx with a Home page, and App
+// renders it, so screen add works right away.
+import { join } from 'node:path';
+import { readJson, readText } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+import { axiosClient, fetchClient } from "./reactNativeSetup.js";
+/** Versions known to work with the generated code (React 18/19). */
+const PACKAGES = {
+    axios: '^1.7.7',
+    '@tanstack/react-query': '^5.59.0',
+    'react-router-dom': '^6.28.0',
+};
+export function reactArchitectures(map) {
+    const c = map.conventions;
+    if (map.endpoints.length > 0 || (c.httpHelper && c.httpHelper !== 'fetch') || c.http === 'axios')
+        return [];
+    return [
+        { id: 'fetch-helper', label: 'Fetch helper', description: 'src/api/client.ts with apiFetch<T>() and ApiError; API URL in src/config/env.ts', recommended: true },
+        { id: 'axios', label: 'axios', description: 'An axios instance in src/api/client.ts; API functions call it', recommended: false },
+        { id: 'axios-react-query', label: 'axios + TanStack Query', description: 'The axios instance, plus a query hook for every endpoint and QueryClientProvider around the app', recommended: false },
+    ];
+}
+function envFile(cra, baseUrl, q, semi) {
+    const v = cra ? 'process.env.REACT_APP_API_URL' : 'import.meta.env.VITE_API_URL';
+    return [`// App settings, read from .env at build time (${cra ? 'REACT_APP_*' : 'VITE_*'} variables).`, `export const API_URL: string = ${v} ?? ${q}${baseUrl}${q}${semi}`, ''].join('\n');
+}
+function routerFile(q, semi) {
+    return [
+        `import { createBrowserRouter } from ${q}react-router-dom${q}${semi}`,
+        `import HomePage from ${q}./pages/HomePage${q}${semi}`,
+        '',
+        '/** Every page and its path. codz route add and screen add add entries here. */',
+        'export const router = createBrowserRouter([',
+        `  { path: ${q}/${q}, element: <HomePage /> },`,
+        `])${semi}`,
+        '',
+    ].join('\n');
+}
+function homePage(semi) {
+    return ['export default function HomePage() {', '  return (', '    <main>', '      <h1>Home</h1>', '    </main>', `  )${semi}`, '}', ''].join('\n');
+}
+function appFile(nav, query, q, semi) {
+    const imports = [
+        ...(nav ? [`import { RouterProvider } from ${q}react-router-dom${q}${semi}`] : []),
+        ...(query ? [`import { QueryClient, QueryClientProvider } from ${q}@tanstack/react-query${q}${semi}`] : []),
+        ...(nav ? [`import { router } from ${q}./router${q}${semi}`] : []),
+    ];
+    let body = nav ? '<RouterProvider router={router} />' : '<main>\n      <h1>Home</h1>\n    </main>';
+    if (query)
+        body = `<QueryClientProvider client={queryClient}>\n      ${body.replace(/\n/g, '\n  ')}\n    </QueryClientProvider>`;
+    return [...imports, '', ...(query ? [`const queryClient = new QueryClient()${semi}`, ''] : []), 'export default function App() {', '  return (', `    ${body}`, `  )${semi}`, '}', ''].join('\n');
+}
+export function planReactSetup(ctx, choice) {
+    const { root, map } = ctx;
+    if (!['fetch-helper', 'axios', 'axios-react-query'].includes(choice.architecture))
+        throw new ToolError('bad_args', `Unknown architecture "${choice.architecture}". Choose fetch-helper, axios or axios-react-query.`);
+    const c0 = map.conventions;
+    const cra = c0.bundler === 'cra';
+    const src = 'src';
+    const q = c0.quote === 'double' ? '"' : "'";
+    const semi = c0.semicolons === 'false' ? '' : ';';
+    const baseUrl = choice.baseUrl || 'https://api.example.com';
+    const files = new Map();
+    const rewrites = [];
+    const summary = [];
+    const warnings = [];
+    if (!choice.baseUrl)
+        warnings.push(`No base URL was given, so ${src}/config/env.ts uses https://api.example.com. Change it there or in .env before calling the API.`);
+    const read = (p) => readText(join(root, p));
+    const create = (path, content, what) => {
+        if (read(path) !== null)
+            throw new ToolError('file_exists', `${path} already exists, so setup stopped without changing anything.`, 'Remove or rename it, or set up the project by hand and run codz init again.');
+        files.set(path, content);
+        summary.push(`Create ${path}: ${what}`);
+    };
+    const axios = choice.architecture !== 'fetch-helper';
+    const query = choice.architecture === 'axios-react-query';
+    const nav = c0.router === 'none' || !c0.router;
+    const envVar = cra ? 'REACT_APP_API_URL' : 'VITE_API_URL';
+    create(`${src}/config/env.ts`, envFile(cra, baseUrl, q, semi), `API_URL from ${envVar}`);
+    create(`${src}/api/client.ts`, axios ? axiosClient(q, semi) : fetchClient(q, semi), axios ? 'the axios instance (baseURL from API_URL)' : 'apiFetch<T>() and ApiError');
+    if (!axios)
+        create(`${src}/api/index.ts`, `export * from ${q}./client${q}${semi}\n`, 'exports every API file');
+    const env = read('.env.example');
+    if (!env || !env.includes(envVar)) {
+        files.set('.env.example', `${env ? env.replace(/\s*$/, '\n') : ''}${envVar}=${baseUrl}\n`);
+        summary.push(`${env ? 'Update' : 'Create'} .env.example: ${envVar}`);
+    }
+    if (!cra && read(`${src}/vite-env.d.ts`) === null) {
+        files.set(`${src}/vite-env.d.ts`, '/// <reference types="vite/client" />\n');
+        summary.push(`Create ${src}/vite-env.d.ts: types for import.meta.env`);
+    }
+    if (nav) {
+        create(`${src}/router.tsx`, routerFile(q, semi), 'React Router (createBrowserRouter) with the Home page');
+        create(`${src}/pages/HomePage.tsx`, homePage(semi), 'the first page');
+    }
+    if (nav || query) {
+        const app = [`${src}/App.tsx`, `${src}/App.jsx`, `${src}/App.js`].find((f) => read(f) !== null) ?? `${src}/App.tsx`;
+        files.set(app, appFile(nav, query, q, semi));
+        rewrites.push(app); // replaced on purpose; the previous App is in codz undo
+        summary.push(`${read(app) === null ? 'Create' : 'Replace'} ${app}: ${[nav && 'RouterProvider with the router', query && 'QueryClientProvider'].filter(Boolean).join(' and ')}${read(app) !== null ? ' (the previous App is in codz undo)' : ''}`);
+    }
+    // Dependencies.
+    const pkgText = read('package.json');
+    let dependenciesChanged = false;
+    if (pkgText !== null) {
+        const pkg = readJson(join(root, 'package.json')) ?? {};
+        const want = [...(axios ? ['axios'] : []), ...(query ? ['@tanstack/react-query'] : []), ...(nav ? ['react-router-dom'] : [])];
+        const missing = want.filter((p) => !pkg.dependencies?.[p] && !pkg.devDependencies?.[p]);
+        if (missing.length) {
+            const parsed = JSON.parse(pkgText);
+            parsed.dependencies = { ...parsed.dependencies };
+            for (const p of missing)
+                parsed.dependencies[p] = PACKAGES[p];
+            parsed.dependencies = Object.fromEntries(Object.entries(parsed.dependencies).sort(([a], [b]) => a.localeCompare(b)));
+            files.set('package.json', JSON.stringify(parsed, null, 2) + '\n');
+            summary.push(`Update package.json: add ${missing.join(', ')}`);
+            dependenciesChanged = true;
+        }
+    }
+    const conventions = {
+        ...c0,
+        http: axios ? 'axios' : 'fetch',
+        httpHelper: axios ? 'fetch' : 'apiFetch',
+        httpHelperFile: axios ? '' : `${src}/api/client.ts`,
+        apiFolder: `${src}/api`,
+        modelsFolder: `${src}/types`,
+        modelsLayout: 'per-file',
+        configFile: `${src}/config/env.ts`,
+        pagesFolder: `${src}/pages`,
+        ...(axios ? { axiosInstance: 'api', axiosInstanceFile: `${src}/api/client.ts` } : {}),
+        ...(query ? { dataFetching: 'react-query', hooksFolder: `${src}/hooks` } : {}),
+        ...(nav ? { router: 'react-router', routerFile: `${src}/router.tsx`, routerStyle: 'data' } : {}),
+    };
+    if (!axios)
+        for (const k of ['axiosInstance', 'axiosInstanceFile'])
+            delete conventions[k];
+    delete conventions.baseUrlEnv;
+    summary.push(`Save conventions: API functions in ${src}/api, interfaces in ${src}/types, pages in ${src}/pages`);
+    return { files, summary, warnings, generated: [], conventions, dependenciesChanged, rewrites };
+}