codz-cli 0.0.0-stage → 0.1.0

package/dist/adapters/nextjsScan.js

@@ -0,0 +1,364 @@
+// Next.js adapter, part 1: reading a project (conventions, endpoints, models,
+// routes, locales) into a ProjectMap.
+import { join, posix } from 'node:path';
+import { isDir, readJson, readText, walk } from "../core/fsutil.js";
+import {} from "../core/types.js";
+import { detectFileNaming } from "../input/naming.js";
+import { emptyMap, fileStats, listRootEnvFiles, scanEnvBaseUrls, scanLocales } from "./common.js";
+import { detectTsStyle, matchBrace, skipString } from "./source.js";
+import { VERSION } from "./nextjs.js";
+const CODE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs'];
+/** Removes comments and trailing commas from JSONC (tsconfig.json), leaving strings untouched. */
+export function stripJsonc(text) {
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        const n = text[i + 1];
+        if (c === '"') {
+            let j = i + 1;
+            while (j < text.length && text[j] !== '"')
+                j += text[j] === '\\' ? 2 : 1;
+            out += text.slice(i, j + 1);
+            i = j + 1;
+        }
+        else if (c === '/' && n === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+        }
+        else if (c === '/' && n === '*') {
+            const end = text.indexOf('*/', i + 2);
+            i = end === -1 ? text.length : end + 2;
+        }
+        else if (c === ',') {
+            let j = i + 1;
+            while (j < text.length && /\s/.test(text[j]))
+                j++;
+            if (text[j] !== '}' && text[j] !== ']')
+                out += c;
+            i++;
+        }
+        else {
+            out += c;
+            i++;
+        }
+    }
+    return out;
+}
+function readTsconfig(root) {
+    const text = readText(join(root, 'tsconfig.json'));
+    if (!text)
+        return {};
+    const cleaned = stripJsonc(text);
+    try {
+        const json = JSON.parse(cleaned);
+        return json.compilerOptions ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+export const dirOf = (f) => (f.includes('/') ? f.slice(0, f.lastIndexOf('/')) : '.');
+export const baseNoExt = (f) => f.slice(f.lastIndexOf('/') + 1).replace(/\.(tsx?|jsx?|mjs)$/, '');
+export function mostCommon(items, fallback) {
+    const counts = new Map();
+    for (const i of items)
+        counts.set(i, (counts.get(i) ?? 0) + 1);
+    let best = fallback;
+    let n = 0;
+    for (const [k, v] of counts)
+        if (v > n)
+            [best, n] = [k, v];
+    return best;
+}
+/** Resolves an import specifier to a project-relative path without extension. */
+export function resolveImport(fromFile, spec, alias, aliasBase) {
+    if (alias && spec.startsWith(alias))
+        return posix.normalize(posix.join(aliasBase === '.' ? '' : aliasBase, spec.slice(alias.length)));
+    if (spec.startsWith('.'))
+        return posix.normalize(posix.join(dirOf(fromFile), spec));
+    return null;
+}
+function exportedFunctions(text) {
+    const out = [];
+    const re = /export\s+(?:async\s+)?function\s+(\w+)\s*(?:<[^>()]*>)?\s*\(|export\s+const\s+(\w+)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:<[^>()]*>)?\s*\(/g;
+    let m;
+    while ((m = re.exec(text))) {
+        const name = m[1] ?? m[2];
+        const open = m.index + m[0].length - 1;
+        const close = matchBrace(text, open);
+        if (close === -1)
+            continue;
+        const params = text.slice(open + 1, close);
+        let i = close + 1;
+        const arrow = text.indexOf('=>', i);
+        const brace = text.indexOf('{', i);
+        let returnType = '';
+        let bodyStart;
+        if (m[2] !== undefined) {
+            if (arrow === -1)
+                continue;
+            returnType = text.slice(i, arrow).replace(/^\s*:\s*/, '').trim();
+            i = arrow + 2;
+            while (/\s/.test(text[i]))
+                i++;
+            bodyStart = i;
+        }
+        else {
+            if (brace === -1)
+                continue;
+            returnType = text.slice(i, brace).replace(/^\s*:\s*/, '').trim();
+            bodyStart = brace;
+        }
+        let bodyEnd;
+        if (text[bodyStart] === '{')
+            bodyEnd = matchBrace(text, bodyStart);
+        else {
+            const nl = text.indexOf('\n\n', bodyStart);
+            bodyEnd = nl === -1 ? text.length : nl;
+        }
+        if (bodyEnd === -1)
+            continue;
+        out.push({ name, params, returnType, body: text.slice(bodyStart, bodyEnd + 1) });
+        re.lastIndex = bodyEnd;
+    }
+    return out;
+}
+/** Finds the URL argument of a fetch/helper call and turns it into a path with {params}. */
+function callPath(body, callee) {
+    const m = callee.exec(body);
+    if (!m)
+        return null;
+    let i = m.index + m[0].length;
+    while (/\s/.test(body[i]))
+        i++;
+    const q = body[i];
+    if (q !== '`' && q !== "'" && q !== '"')
+        return null;
+    const end = skipString(body, i, 'ts');
+    const literal = body.slice(i + 1, end - 1);
+    // Walk interpolations with brace matching, so nested template literals are handled.
+    let raw = '';
+    let j = 0;
+    let first = true;
+    while (j < literal.length) {
+        if (q === '`' && literal[j] === '$' && literal[j + 1] === '{') {
+            const close = matchBrace(literal, j + 1);
+            if (close === -1)
+                return null;
+            const expr = literal.slice(j + 2, close).trim();
+            if (first && raw === '') {
+                // A leading interpolation is the base URL.
+            }
+            else if (/^[A-Za-z_$][\w$]*(\??\.[A-Za-z_$][\w$]*)*$/.test(expr)) {
+                raw += `{${expr.split('.').pop().replace('?', '')}}`;
+            }
+            else {
+                // Anything else (a ternary, a call) builds the query string; it is not part of the path.
+            }
+            first = false;
+            j = close + 1;
+            continue;
+        }
+        raw += literal[j];
+        first = false;
+        j++;
+    }
+    raw = raw.split('?')[0];
+    if (!raw.startsWith('/'))
+        return null;
+    return raw;
+}
+function parseInterfaces(text, file) {
+    const out = [];
+    const re = /export\s+(?:interface\s+(\w+)(?:<[^>]*>)?(?:\s+extends\s+[^{]+)?|type\s+(\w+)(?:<[^>]*>)?\s*=)\s*\{/g;
+    let m;
+    while ((m = re.exec(text))) {
+        const open = m.index + m[0].length - 1;
+        const close = matchBrace(text, open);
+        if (close === -1)
+            continue;
+        const body = text.slice(open + 1, close);
+        const fields = [];
+        let depth = 0;
+        for (const line of body.split('\n')) {
+            if (depth === 0) {
+                const f = line.match(/^\s*(?:readonly\s+)?['"]?([\w$-]+)['"]?(\?)?\s*:\s*([^;\n]+?)\s*[;,]?\s*$/);
+                if (f)
+                    fields.push({ name: f[1], type: f[3].replace(/\s*\|\s*null/, '').replace(/\{$/, 'object').trim(), nullable: !!f[2] || /\|\s*null/.test(f[3]) });
+            }
+            depth += (line.match(/[{(]/g) ?? []).length - (line.match(/[})]/g) ?? []).length;
+        }
+        out.push({ name: m[1] ?? m[2], file, fields });
+        re.lastIndex = close;
+    }
+    return out;
+}
+export async function scan(root, configConventions) {
+    const map = emptyMap('nextjs', `nextjs@${VERSION}`);
+    const files = walk(root);
+    map.stats = fileStats(files);
+    const code = files.filter((f) => CODE_EXTS.some((e) => f.endsWith(e)) && !f.endsWith('.d.ts') && !/(^|\/)(next|tailwind|postcss|eslint)\.config\./.test(f));
+    const texts = new Map();
+    const text = (f) => {
+        if (!texts.has(f))
+            texts.set(f, readText(join(root, f)) ?? '');
+        return texts.get(f);
+    };
+    const pkg = readJson(join(root, 'package.json')) ?? {};
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const c = {};
+    // App Router.
+    c.appDir = isDir(join(root, 'src/app')) ? 'src/app' : isDir(join(root, 'app')) ? 'app' : '';
+    if (!c.appDir)
+        map.notes.push(isDir(join(root, 'pages')) || isDir(join(root, 'src/pages')) ? 'This project uses the Pages Router, which is not supported yet; routes are not mapped.' : 'No app folder found; routes are not mapped.');
+    const src = c.appDir.startsWith('src/') || isDir(join(root, 'src')) ? 'src/' : '';
+    const isUi = (f) => (c.appDir && f.startsWith(c.appDir + '/')) || /(^|\/)(components|hooks|pages|public|styles)\//.test(f) || /\.(tsx|jsx)$/.test(f);
+    // Path alias.
+    const tsc = readTsconfig(root);
+    const aliasKey = Object.keys(tsc.paths ?? {}).find((k) => k.endsWith('/*'));
+    c.importAlias = aliasKey ? aliasKey.slice(0, -1) : '';
+    c.aliasBase = aliasKey ? posix.normalize(posix.join(tsc.baseUrl ?? '.', (tsc.paths[aliasKey][0] ?? './*').replace(/\/?\*$/, ''))) : '.';
+    if (c.aliasBase === '')
+        c.aliasBase = '.';
+    // HTTP client and helper.
+    c.http = deps.axios && code.some((f) => /from ['"]axios['"]/.test(text(f))) ? 'axios' : 'fetch';
+    // axios: the shared instance (export const api = axios.create(...), or a default export).
+    if (c.http === 'axios') {
+        c.axiosInstance = '';
+        c.axiosInstanceFile = '';
+        for (const f of code) {
+            const t = text(f);
+            const m = t.match(/(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*axios\.create\s*\(/);
+            if (!m)
+                continue;
+            const exported = new RegExp(`export\\s+(?:const|let)\\s+${m[1]}\\b|export\\s*\\{[^}]*\\b${m[1]}\\b[^}]*\\}`).test(t);
+            const asDefault = new RegExp(`export\\s+default\\s+${m[1]}\\b`).test(t);
+            if (!exported && !asDefault)
+                continue;
+            c.axiosInstance = exported ? m[1] : `default:${m[1]}`;
+            c.axiosInstanceFile = f;
+            break;
+        }
+        if (!c.axiosInstance)
+            c.axiosInstance = 'axios';
+    }
+    const axiosName = (c.axiosInstance ?? '').replace(/^default:/, '');
+    // TanStack Query: hooks next to the API functions when the project already uses it.
+    const queryUsers = code.filter((f) => /from ['"]@tanstack\/react-query['"]/.test(text(f)));
+    if (deps['@tanstack/react-query'] && queryUsers.some((f) => /\buse(?:Query|Mutation|SuspenseQuery)\s*[<(]/.test(text(f)))) {
+        c.dataFetching = 'react-query';
+        const hookFiles = queryUsers.filter((f) => /\bexport\s+(?:function|const)\s+use[A-Z]/.test(text(f)));
+        c.hooksFolder = mostCommon(hookFiles.map(dirOf), `${src}hooks`);
+        // Feature-first projects keep hooks in many feature folders; none of them is "the" hooks folder.
+        const hookDirs = new Set(hookFiles.map(dirOf));
+        if (hookDirs.size >= 3 && hookFiles.filter((f) => dirOf(f) === c.hooksFolder).length * 2 < hookFiles.length)
+            c.hooksFolder = `${src}hooks`;
+    }
+    const axiosCall = axiosName && axiosName !== 'axios' ? new RegExp(`\\b${axiosName}\\.(?:get|post|put|patch|delete|head|request)\\s*[<(]`) : null;
+    const fetchFiles = code.filter((f) => !isUi(f) && f !== c.axiosInstanceFile && (/\bfetch\s*\(|\baxios\b/.test(text(f)) || (axiosCall?.test(text(f)) ?? false)));
+    let helper = '';
+    let helperFile = '';
+    for (const f of fetchFiles) {
+        const m = text(f).match(/export\s+(?:async\s+)?function\s+(\w+)\s*<[^>]*>\s*\(\s*(\w+)\s*:\s*string|export\s+const\s+(\w+)\s*=\s*(?:async\s*)?<[^>]*>\s*\(\s*(\w+)\s*:\s*string/);
+        if (m && /\bfetch\s*\(/.test(text(f))) {
+            helper = m[1] ?? m[3];
+            helperFile = f;
+            break;
+        }
+    }
+    c.httpHelper = helper || 'fetch';
+    c.httpHelperFile = helperFile;
+    const callerFiles = helper ? code.filter((f) => f !== helperFile && !isUi(f) && new RegExp(`\\b${helper}\\s*[<(]`).test(text(f))) : [];
+    const apiFiles = [...new Set([...fetchFiles, ...callerFiles])].filter((f) => f !== helperFile || !helper);
+    c.apiFolder = mostCommon(apiFiles.map(dirOf), helperFile ? dirOf(helperFile) : `${src}lib/api`);
+    const apiFolderFiles = code.filter((f) => dirOf(f) === c.apiFolder && !/\/index\.[tj]s$/.test('/' + f) && f !== helperFile && f !== c.axiosInstanceFile);
+    const apiBases = apiFolderFiles.map(baseNoExt);
+    c.apiFileNaming = detectFileNaming(apiBases, 'kebab');
+    const lastWords = apiBases.map((b) => b.split(/[-_]|(?=[A-Z])/).pop().toLowerCase());
+    const suffix = mostCommon(lastWords.filter((w) => ['service', 'api', 'client', 'requests', 'endpoints'].includes(w)), '');
+    const withSuffix = lastWords.filter((w) => w === suffix).length;
+    // One file called client.ts next to users.ts is not a naming pattern; two of three is.
+    c.apiFileSuffix = suffix && withSuffix * 2 >= lastWords.length && (withSuffix >= 2 || lastWords.length === 1) ? suffix : '';
+    const resourceWords = apiBases.map((b) => (c.apiFileSuffix ? b.replace(new RegExp(`[-_]?${c.apiFileSuffix}$`, 'i'), '') : b));
+    c.apiFileResource = resourceWords.length && resourceWords.filter((w) => /s$/i.test(w)).length * 2 < resourceWords.length ? 'singular' : 'plural';
+    // Base URL.
+    const envUse = apiFiles.concat(helperFile ? [helperFile] : []).map((f) => text(f).match(/process\.env\.(\w+)/)?.[1]).filter((x) => !!x);
+    c.baseUrlEnv = mostCommon(envUse, '');
+    map.baseUrls = scanEnvBaseUrls(root, listRootEnvFiles(root));
+    // Models.
+    const modelFiles = code.filter((f) => !isUi(f) && /export\s+(interface|type)\s+\w+/.test(text(f)));
+    const modelDirs = modelFiles.map(dirOf);
+    const preferred = modelDirs.filter((d) => /(^|\/)(types|models|interfaces|entities)$/.test(d));
+    c.modelsFolder = mostCommon(preferred.length ? preferred : modelDirs, `${src}types`);
+    const inFolder = modelFiles.filter((f) => dirOf(f) === c.modelsFolder);
+    const multi = inFolder.find((f) => (text(f).match(/export\s+(interface|type)\s+\w+/g) ?? []).length >= 2);
+    c.modelsLayout = multi && inFolder.length <= 2 ? 'single' : 'per-file';
+    c.modelsFile = c.modelsLayout === 'single' ? multi : '';
+    c.modelFileNaming = detectFileNaming(inFolder.map(baseNoExt).filter((b) => b !== 'index'), 'kebab');
+    for (const f of modelFiles)
+        map.models.push(...parseInterfaces(text(f), f));
+    // Import style and code style.
+    const apiTexts = apiFiles.map(text);
+    const aliasImports = c.importAlias ? apiTexts.join('\n').split(`from '${c.importAlias}`).length + apiTexts.join('\n').split(`from "${c.importAlias}`).length - 2 : 0;
+    const relImports = (apiTexts.join('\n').match(/from ['"]\.\.\//g) ?? []).length;
+    c.importStyle = c.importAlias && (aliasImports >= relImports || apiTexts.length === 0) ? 'alias' : 'relative';
+    const style = detectTsStyle(apiTexts.length ? apiTexts : code.slice(0, 20).map(text));
+    c.quote = style.quote === '"' ? 'double' : 'single';
+    c.semicolons = String(style.semi);
+    c.indent = style.indent === '\t' ? 'tab' : String(style.indent.length);
+    c.i18n = deps['next-intl'] ? 'next-intl' : deps['next-i18next'] ? 'next-i18next' : deps.i18next ? 'i18next' : '';
+    c.styling = deps.tailwindcss ? 'tailwind' : deps['styled-components'] ? 'styled-components' : '';
+    // Confirmed values in codz.config.yaml win.
+    map.conventions = { ...c, ...configConventions };
+    const conv = map.conventions;
+    // Endpoints.
+    const callee = new RegExp(`(?:\\bfetch|\\b${conv.httpHelper !== 'fetch' ? conv.httpHelper : 'fetch'}|\\b\\w+\\.(?:get|post|put|patch|delete))\\s*(?:<[^>]*>)?\\(`);
+    for (const f of apiFiles) {
+        for (const fn of exportedFunctions(text(f))) {
+            if (fn.name === conv.httpHelper)
+                continue;
+            const path = callPath(fn.body, new RegExp(callee.source));
+            if (!path || /^\/\{\w+\}$/.test(path))
+                continue;
+            const method = (fn.body.match(/method:\s*['"`](\w+)['"`]/)?.[1] ?? fn.body.match(/\.(get|post|put|patch|delete)\s*[<(]/)?.[1] ?? 'GET').toUpperCase();
+            const response = fn.returnType.match(/^Promise<(.+)>$/)?.[1]?.trim();
+            map.endpoints.push({ name: fn.name, method, path, response, file: f, calledFrom: [] });
+        }
+    }
+    // Call sites.
+    for (const f of code) {
+        const t = text(f);
+        const re = /import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g;
+        let m;
+        while ((m = re.exec(t))) {
+            const target = resolveImport(f, m[2], conv.importAlias, conv.aliasBase);
+            if (!target)
+                continue;
+            const names = m[1].split(',').map((s) => s.trim().split(/\s+as\s+/)[0].replace(/^type\s+/, ''));
+            for (const ep of map.endpoints) {
+                if (ep.file === f || !names.includes(ep.name))
+                    continue;
+                const epNoExt = ep.file.replace(/\.(tsx?|jsx?|mjs)$/, '');
+                if (target === epNoExt || target === dirOf(ep.file))
+                    ep.calledFrom.push(f);
+            }
+        }
+    }
+    // Routes.
+    if (conv.appDir) {
+        for (const f of files.filter((x) => x.startsWith(conv.appDir + '/') && /\/page\.(tsx|ts|jsx|js)$/.test(x))) {
+            const segs = f.slice(conv.appDir.length + 1).split('/').slice(0, -1);
+            const urlSegs = segs.filter((s) => !/^\(.*\)$/.test(s) && !s.startsWith('@'));
+            const params = urlSegs.filter((s) => s.startsWith('[')).map((s) => s.replace(/[[\].]/g, ''));
+            const path = '/' + urlSegs.map((s) => (s.startsWith('[') ? `{${s.replace(/[[\].]/g, '')}}` : s)).join('/');
+            const named = urlSegs.filter((s) => !s.startsWith('['));
+            const route = { name: named.length ? named.join('-') : 'home', path: path === '/' ? '/' : path, params, file: f };
+            map.routes.push(route);
+        }
+        map.routes.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    map.locales = scanLocales(root, files);
+    return map;
+}
+// ---------------- Generation ----------------

package/dist/adapters/nextjsSetup.js

@@ -0,0 +1,119 @@
+// Next.js `setup`: creates an API layer for a project that has none yet.
+//   fetch-helper  lib/api/client.ts with apiFetch<T>() and ApiError (recommended)
+//   plain-fetch   each generated function calls fetch itself
+// Both store the base URL in NEXT_PUBLIC_API_URL (.env.example and .env.local).
+import { jsString } from "../core/safe.js";
+import { join } from 'node:path';
+import { detectEol, readText, withEol } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+const ENV = 'NEXT_PUBLIC_API_URL';
+export function nextArchitectures(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: 'lib/api/client.ts with apiFetch<T>() and ApiError; one API file per resource; interfaces in types/', recommended: true },
+        { id: 'plain-fetch', label: 'Plain fetch', description: 'Each API function calls fetch directly; no shared helper', recommended: false },
+    ];
+}
+function clientFile(q, semi, baseUrl) {
+    return [
+        `// ${ENV} comes from .env.local; the fallback is the URL setup was given.`,
+        `const BASE_URL = process.env.${ENV} ?? ${jsString(baseUrl, 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(`${BASE_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');
+}
+/** Sets NAME=value in an env file, keeping everything else. */
+function setEnv(text, value) {
+    if (text === null)
+        return `${ENV}=${value}\n`;
+    const eol = detectEol(text);
+    const re = new RegExp(`^${ENV}=.*$`, 'm');
+    if (re.test(text))
+        return text;
+    return withEol(`${text.replace(/\s*$/, '')}${text.trim() ? '\n' : ''}${ENV}=${value}\n`, eol);
+}
+export function planNextSetup(ctx, choice) {
+    const { root, map } = ctx;
+    if (!['fetch-helper', 'plain-fetch'].includes(choice.architecture)) {
+        throw new ToolError('bad_args', `Unknown architecture "${choice.architecture}". Choose fetch-helper or plain-fetch.`);
+    }
+    const c = map.conventions;
+    const files = new Map();
+    const summary = [];
+    const warnings = [];
+    const read = (p) => readText(join(root, p));
+    const src = (c.appDir ?? '').startsWith('src/') ? 'src/' : '';
+    const apiFolder = `${src}lib/api`;
+    const q = c.quote === 'double' ? '"' : "'";
+    const semi = c.semicolons === 'false' ? '' : ';';
+    const baseUrl = choice.baseUrl || 'https://api.example.com';
+    if (!choice.baseUrl)
+        warnings.push(`No base URL was given, so ${ENV} is set to https://api.example.com. Change it in .env.example (and your .env.local).`);
+    const conventions = {
+        ...c,
+        http: 'fetch',
+        apiFolder,
+        apiFileNaming: 'kebab',
+        apiFileSuffix: '',
+        apiFileResource: 'plural',
+        baseUrlEnv: ENV,
+        modelsFolder: `${src}types`,
+        modelsLayout: 'per-file',
+        modelsFile: '',
+        modelFileNaming: 'kebab',
+        importStyle: c.importAlias ? 'alias' : 'relative',
+        httpHelper: 'fetch',
+        httpHelperFile: '',
+    };
+    if (choice.architecture === 'fetch-helper') {
+        const client = `${apiFolder}/client.ts`;
+        const index = `${apiFolder}/index.ts`;
+        for (const p of [client, index]) {
+            if (read(p) !== null)
+                throw new ToolError('file_exists', `${p} already exists, so setup stopped without changing anything.`, 'Remove or rename it, or run codz init again to use it as it is.');
+        }
+        files.set(client, clientFile(q, semi, baseUrl));
+        summary.push(`Create ${client}: apiFetch<T>() and ApiError, reading the base URL from ${ENV}`);
+        files.set(index, `export * from ${q}./client${q}${semi}\n`);
+        summary.push(`Create ${index}: exports every API file`);
+        conventions.httpHelper = 'apiFetch';
+        conventions.httpHelperFile = client;
+    }
+    // .env.example only: .env.local is the developer's own file and may hold secrets, so codz never writes it.
+    {
+        const envFile = '.env.example';
+        const before = read(envFile);
+        const after = setEnv(before, baseUrl);
+        if (after !== before) {
+            files.set(envFile, after);
+            summary.push(`${before === null ? 'Create' : 'Update'} ${envFile}: ${ENV}=${baseUrl}`);
+        }
+        const local = read('.env.local');
+        if (local === null || !new RegExp(`^${ENV}=`, 'm').test(local))
+            summary.push(`Copy ${ENV} from .env.example into .env.local (codz does not write .env.local)${choice.architecture === 'fetch-helper' ? `; until then lib/api/client.ts falls back to ${baseUrl}` : ': the API functions read it'}`);
+    }
+    summary.push(`Save conventions: API files in ${apiFolder}, interfaces in ${conventions.modelsFolder}`);
+    return { files, summary, warnings, generated: [], conventions, dependenciesChanged: false };
+}

package/dist/adapters/react.js

@@ -0,0 +1,89 @@
+// React web adapter (Vite or Create React App, TypeScript), for apps that are
+// not Next.js. API code is TypeScript like in Next.js, so scanning and writing
+// 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 the web app's own parts: the bundler (for the env variable
+// prefix), React Router (a <Routes> tree or createBrowserRouter), the pages
+// 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 { planReactSetup, reactArchitectures } from "./reactSetup.js";
+export const REACT_VERSION = '0.1.0';
+const { appDir: _appDir, ...SHARED_DOCS } = NEXT_CONVENTION_DOCS;
+export const REACT_CONVENTION_DOCS = {
+    ...SHARED_DOCS,
+    bundler: 'vite or cra (Create React App): decides the env variable prefix',
+    router: 'react-router or none',
+    routerStyle: 'jsx (<Routes><Route .../></Routes>) or data (createBrowserRouter([...]))',
+    routerFile: 'the file that lists the routes',
+    pagesFolder: 'where page components live',
+    configFile: 'file that exports API_URL',
+};
+/** <Route path="/team/:teamId" element={<TeamPage />} /> and { path: '/x', element: <X /> }. */
+function reactRoutes(file, text) {
+    const out = [];
+    const add = (path, comp) => out.push({ name: comp.replace(/Page$/, '') || 'home', path: path.replace(/:(\w+)/g, '{$1}'), params: [...path.matchAll(/:(\w+)/g)].map((m) => m[1]), file });
+    for (const m of text.matchAll(/<Route\b[^>]*?\bpath=["']([^"']+)["'][^>]*?element=\{<(\w+)/g))
+        add(m[1], m[2]);
+    for (const m of text.matchAll(/\{\s*path:\s*["']([^"']+)["']\s*,\s*element:\s*<(\w+)/g))
+        add(m[1], m[2]);
+    return out;
+}
+async function scan(root, configConventions) {
+    const map = await nextjsAdapter.scan(root, configConventions);
+    map.framework = 'react';
+    map.adapter = `react@${REACT_VERSION}`;
+    map.notes = map.notes.filter((n) => !/app folder|Pages Router|App 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: ['public', 'build', 'dist'] });
+    const text = (f) => readText(join(root, f)) ?? '';
+    const src = isDir(join(root, 'src')) ? 'src/' : '';
+    const c = {};
+    c.bundler = deps['react-scripts'] ? 'cra' : 'vite';
+    const routerFile = files.find((f) => /createBrowserRouter\s*\(/.test(text(f))) ?? files.find((f) => /<Routes\b/.test(text(f))) ?? '';
+    c.router = deps['react-router-dom'] || deps['react-router'] ? 'react-router' : 'none';
+    c.routerFile = c.router === 'react-router' ? routerFile || `${src}router.tsx` : '';
+    c.routerStyle = routerFile && /createBrowserRouter\s*\(/.test(text(routerFile)) ? 'data' : c.router === 'react-router' && routerFile ? 'jsx' : 'data';
+    const pageFiles = files.filter((f) => /(Page|View)\.(tsx|jsx)$/.test(f));
+    c.pagesFolder = mostCommon(pageFiles.map((f) => f.slice(0, f.lastIndexOf('/'))), `${src}pages`);
+    c.configFile = files.find((f) => /export\s+const\s+API_URL\b/.test(text(f))) ?? `${src}config/env.ts`;
+    // A guessed API folder follows web-app layouts (src/api), not Next.js (lib/api).
+    if (!map.endpoints.length && !configConventions.apiFolder && !exists(join(root, map.conventions.apiFolder ?? '')))
+        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.routerFile && exists(join(root, conv.routerFile)))
+        map.routes = reactRoutes(conv.routerFile, text(conv.routerFile));
+    map.routes.sort((a, b) => a.path.localeCompare(b.path));
+    if (conv.router === 'none')
+        map.notes.push('No React Router found; screen add and route add need it (codz setup adds React Router).');
+    return map;
+}
+export const reactAdapter = {
+    id: 'react',
+    version: REACT_VERSION,
+    capabilities: { explain: true, apiAdd: true },
+    supportedSetup: 'React web apps (Vite or Create React App), TypeScript, fetch (directly or through a helper) or axios, optionally TanStack Query; React Router.',
+    scan,
+    planEndpoint: nextjsAdapter.planEndpoint,
+    architectures: reactArchitectures,
+    planSetup: planReactSetup,
+    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,
+};