codz-cli 0.0.0-stage → 0.1.0

package/dist/skills/reactUi.js

@@ -0,0 +1,352 @@
+// React web pages: route add, screen add (data) and screen add --form.
+//
+//   <Name>Page.tsx in the pages folder, registered in the router file:
+//     data style   { path: '/orders/:id', element: <OrderPage /> } in createBrowserRouter([...])
+//     jsx style    <Route path="/orders/:id" element={<OrderPage />} /> inside <Routes>
+//   Path parameters (:id) are read with useParams().
+//
+// A data page loads the endpoint (through its TanStack Query hook when the
+// project has one) and shows loading, the error with Retry, and the data (a
+// list, or the fields). A form page has one input per request field and goes
+// back after saving.
+import { join, posix } from 'node:path';
+import { importPath } from "../adapters/nextjs.js";
+import { splitTsParams } from "../adapters/reactQuery.js";
+import { buildChangeSet } from "../core/changeset.js";
+import { exists, readText, walk } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+import { camel, kebab, pascal, words } from "../input/naming.js";
+import { findDeclaration } from "./apiEdit.js";
+import { responseShape, titleField } from "./screen.js";
+import { reactPrefill } from "./prefill.js";
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+function routeParamsOf(path) {
+    return [...(path ?? '').matchAll(/[:{]([\w-]+)\}?/g)].map((m) => camel(m[1]));
+}
+function names(name) {
+    const base = pascal(name.replace(/[-_ ]?(page|screen)$/i, ''));
+    return { base, component: `${base}Page`, title: words(base).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ') };
+}
+/** Index of the bracket that closes the one at `open`, skipping strings and template literals. */
+function closing(text, open) {
+    const pairs = { '[': ']', '(': ')', '{': '}' };
+    const stack = [];
+    for (let i = open; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '"' || ch === "'" || ch === '`') {
+            for (i++; i < text.length && text[i] !== ch; i++)
+                if (text[i] === '\\')
+                    i++;
+            continue;
+        }
+        if (pairs[ch])
+            stack.push(pairs[ch]);
+        else if (ch === stack[stack.length - 1]) {
+            stack.pop();
+            if (!stack.length)
+                return i;
+        }
+    }
+    return -1;
+}
+function place(root, map, opts) {
+    const c = map.conventions;
+    if (c.router !== 'react-router')
+        throw new ToolError('not_supported', 'This project has no React Router, so codz cannot add a page to it.', 'Run codz setup (it adds React Router), or add react-router-dom.');
+    const routerFile = c.routerFile;
+    const routerText = routerFile ? readText(join(root, routerFile)) : null;
+    if (!routerFile || routerText === null)
+        throw new ToolError('no_router', `The router file ${routerFile || '(none)'} was not found.`, 'Set routerFile in codz.config.yaml to the file with createBrowserRouter or <Routes>.');
+    const n = names(opts.name);
+    const route = (opts.path ?? `/${kebab(n.base)}`).replace(/\{([\w-]+)\}/g, ':$1');
+    return { file: `${c.pagesFolder || 'src/pages'}/${n.component}.tsx`, route, routerFile, routerText };
+}
+/** Adds the page to the router file (createBrowserRouter array or <Routes>). */
+function register(p, map, opts) {
+    const n = names(opts.name);
+    const c = map.conventions;
+    const q = c.quote === 'double' ? '"' : "'";
+    const semi = c.semicolons === 'false' ? '' : ';';
+    let t = p.routerText;
+    if (new RegExp(`path[=:]\\s*\\{?["'\`]${p.route.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}["'\`]`).test(t))
+        throw new ToolError('route_exists', `${p.routerFile} already has a route for ${p.route}.`);
+    const data = /createBrowserRouter\s*\(/.exec(t);
+    if (data) {
+        const open = t.indexOf('[', data.index);
+        const close = open >= 0 ? closing(t, open) : -1;
+        if (close < 0)
+            throw new ToolError('no_router', `Could not read the route list in ${p.routerFile}.`);
+        const before = t.slice(0, close).replace(/\s*$/, '');
+        const indent = /\n([ \t]+)\{\s*path/.exec(t.slice(open))?.[1] ?? '  ';
+        const comma = /[,[]\s*$/.test(before) ? '' : ',';
+        const entry = `{ path: ${q}${p.route}${q}, element: <${n.component} /> },`;
+        t = opts.initial ? t.slice(0, open + 1) + `\n${indent}${entry}` + t.slice(open + 1) : `${before}${comma}\n${indent}${entry}\n` + t.slice(close);
+    }
+    else {
+        const end = t.lastIndexOf('</Routes>');
+        if (end < 0)
+            throw new ToolError('no_router', `Could not find createBrowserRouter or </Routes> in ${p.routerFile}.`);
+        const lineStart = t.lastIndexOf('\n', end) + 1;
+        const indent = /\n([ \t]+)<Route\b[^\n]*\n[ \t]*<\/Routes>/.exec(t)?.[1] ?? `${t.slice(lineStart, end)}  `;
+        t = `${t.slice(0, lineStart)}${indent}<Route path="${p.route}" element={<${n.component} />} />\n${t.slice(lineStart)}`;
+    }
+    const imp = `import ${n.component} from ${q}${importPath(p.routerFile, p.file, { ...c, importStyle: 'relative' }).replace(/\.tsx$/, '')}${q}${semi}`;
+    const imports = [...t.matchAll(/^import[^\n]*\n/gm)];
+    const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length : 0;
+    return t.slice(0, at) + imp + '\n' + t.slice(at);
+}
+function paramsCode(params) {
+    if (!params.length)
+        return { imports: [], lines: [] };
+    return { imports: [`import { useParams } from 'react-router-dom';`], lines: [`  const { ${params.map((p) => `${p} = ''`).join(', ')} } = useParams();`] };
+}
+function finish(root, skill, p, page, map, opts, summary, warnings) {
+    const files = new Map([
+        [p.file, page],
+        [p.routerFile, register(p, map, opts)],
+    ]);
+    summary.push(`Update ${p.routerFile}: add ${p.route}`);
+    summary.push(`Open it with: <Link to=${p.route.includes(':') ? `{\`${p.route.replace(/:(\w+)/g, '${$1}')}\`}` : `"${p.route}"`}> or navigate(...)`);
+    return buildChangeSet(root, skill, { files, summary, warnings, generated: [] });
+}
+export function planReactRoute(root, map, opts) {
+    const p = place(root, map, opts);
+    if (exists(join(root, p.file)))
+        throw new ToolError('route_exists', `${p.file} already exists.`);
+    const n = names(opts.name);
+    const params = routeParamsOf(p.route);
+    const pc = paramsCode(params);
+    const page = [...pc.imports, ...(pc.imports.length ? [''] : []), `export default function ${n.component}() {`, ...pc.lines, '  return (', '    <main>', `      <h1>${n.title}${params.length ? ` {${params[0]}}` : ''}</h1>`, '    </main>', '  );', '}', ''].join('\n');
+    return finish(root, 'route add', p, page, map, opts, [`Create ${p.file}: ${n.component}`], []);
+}
+function findEp(map, name) {
+    const ep = map.endpoints.find((e) => e.name === name) ?? map.endpoints.find((e) => e.name.toLowerCase() === name.toLowerCase());
+    if (!ep)
+        throw new ToolError('no_endpoint', `No endpoint called ${name} was found.`, map.endpoints.length ? `Endpoints: ${map.endpoints.map((e) => e.name).join(', ')}` : 'Add one first with: codz api add');
+    return ep;
+}
+function callArgs(root, ep, params, skip = () => false) {
+    const decl = findDeclaration(readText(join(root, ep.file)) ?? '', ep.name, 'ts');
+    if (!decl)
+        throw new ToolError('no_endpoint', `Could not read ${ep.name} in ${ep.file}.`);
+    const ps = splitTsParams(decl.params);
+    const missing = ps.filter((x) => !x.optional && !skip(x.name) && !params.includes(x.name)).map((x) => x.name);
+    const args = ps.filter((x) => !skip(x.name) && params.includes(x.name)).map((x) => (/^number$/.test(x.type) ? `Number(${x.name})` : x.name));
+    return { args: args.join(', '), missing, decl, ps };
+}
+function hookFor(root, map, ep) {
+    if (map.conventions.dataFetching !== 'react-query' || !map.conventions.hooksFolder)
+        return null;
+    for (const f of walk(root, map.conventions.hooksFolder, { exts: ['.ts', '.tsx'] })) {
+        const t = readText(join(root, f)) ?? '';
+        const m = new RegExp(`export function (use\\w+)\\([^)]*\\)\\s*\\{\\s*return useQuery\\(\\{[^}]*?queryFn: \\(\\) => ${ep.name}\\(`).exec(t);
+        if (m)
+            return { name: m[1], file: f };
+    }
+    return null;
+}
+function apiImport(root, map, from, ep) {
+    const dir = posix.dirname(ep.file);
+    const barrel = [`${dir}/index.ts`].find((f) => exists(join(root, f)) && /export\s+\*\s+from/.test(readText(join(root, f)) ?? ''));
+    return importPath(from, barrel ?? ep.file, map.conventions).replace(/\.tsx?$/, '');
+}
+export function planReactScreen(root, map, opts) {
+    if (!opts.api)
+        return planReactRoute(root, map, opts);
+    const ep = findEp(map, opts.api);
+    if (opts.form)
+        return planReactForm(root, map, opts, ep);
+    if (ep.method !== 'GET')
+        throw new ToolError('screen_needs_get', `${ep.name} is a ${ep.method} endpoint; a page loads data with a GET.`, 'For a form that sends it, add --form.');
+    const p = place(root, map, opts);
+    if (exists(join(root, p.file)))
+        throw new ToolError('route_exists', `${p.file} already exists.`);
+    const n = names(opts.name);
+    const params = routeParamsOf(p.route);
+    const { args, missing, decl } = callArgs(root, ep, params);
+    if (missing.length)
+        throw new ToolError('screen_args', `${ep.name}() needs ${missing.join(', ')}, which the page does not have.`, `Give the route a matching parameter, for example: --path /${kebab(n.base)}/:${missing[0]}`);
+    const shape = responseShape(decl.returnType, map);
+    const tf = titleField(shape.model);
+    const idf = shape.model?.fields.find((f) => /^(id|uuid|key|slug)$/.test(f.name))?.name;
+    const pc = paramsCode(params);
+    const hook = hookFor(root, map, ep);
+    const c = map.conventions;
+    const T = shape.raw || 'unknown';
+    const access = (v, f) => (IDENT.test(f) ? `${v}.${f}` : `${v}['${f}']`);
+    const view = shape.list
+        ? [
+            '      {data.length === 0 ? (',
+            '        <p>Nothing here yet.</p>',
+            '      ) : (',
+            '        <ul>',
+            `          {data.map((${idf ? 'item' : 'item, index'}) => (`,
+            `            <li key={${idf ? `String(${access('item', idf)})` : 'index'}}>{${tf ? `String(${access('item', tf)})` : 'JSON.stringify(item)'}}</li>`,
+            '          ))}',
+            '        </ul>',
+            '      )}',
+        ]
+        : [
+            '      <dl>',
+            ...(shape.model?.fields.length ? shape.model.fields.flatMap((f) => [`        <dt>${f.name}</dt>`, `        <dd>{String(${access('data', f.name)} ?? '')}</dd>`]) : ['        <pre>{JSON.stringify(data, null, 2)}</pre>']),
+            '      </dl>',
+        ];
+    const stateLines = hook
+        ? [`  const { data, isLoading: loading, error, refetch: load } = ${hook.name}(${args});`]
+        : [
+            `  const [data, setData] = useState<${T} | null>(null);`,
+            '  const [loading, setLoading] = useState(true);',
+            '  const [error, setError] = useState<unknown>(null);',
+            '',
+            '  const load = useCallback(async () => {',
+            '    setLoading(true);',
+            '    setError(null);',
+            '    try {',
+            `      setData(await ${ep.name}(${args}));`,
+            '    } catch (e) {',
+            '      setError(e);',
+            '    } finally {',
+            '      setLoading(false);',
+            '    }',
+            `  }, [${params.join(', ')}]);`,
+            '',
+            '  useEffect(() => {',
+            '    load();',
+            '  }, [load]);',
+        ];
+    const page = [
+        ...(hook ? [] : [`import { useCallback, useEffect, useState } from 'react';`]),
+        ...pc.imports,
+        hook ? `import { ${hook.name} } from '${importPath(p.file, hook.file, c).replace(/\.tsx?$/, '')}';` : `import { ${ep.name} } from '${apiImport(root, map, p.file, ep)}';`,
+        ...(shape.model && !hook ? [`import type { ${shape.model.name} } from '${importPath(p.file, shape.model.file, c).replace(/\.tsx?$/, '')}';`] : []),
+        '',
+        `export default function ${n.component}() {`,
+        ...pc.lines,
+        ...stateLines,
+        '',
+        '  if (loading && !data) return <p>Loading…</p>;',
+        '  if (error) {',
+        '    return (',
+        '      <div role="alert">',
+        '        <p>{error instanceof Error ? error.message : String(error)}</p>',
+        '        <button type="button" onClick={() => load()}>Retry</button>',
+        '      </div>',
+        '    );',
+        '  }',
+        '  if (!data) return null;',
+        '  return (',
+        '    <main>',
+        `      <h1>${n.title}</h1>`,
+        ...view,
+        '    </main>',
+        '  );',
+        '}',
+        '',
+    ].join('\n');
+    return finish(root, 'screen add', p, page, map, opts, [`Create ${p.file}: ${n.component} loads ${hook ? `${hook.name}()` : `${ep.name}()`} and shows loading, the error with Retry, and the data`], []);
+}
+function kind(type) {
+    const t = type.replace(/\s*\|\s*null$/, '').trim();
+    if (t === 'string')
+        return 'text';
+    if (t === 'number')
+        return 'number';
+    if (t === 'boolean')
+        return 'bool';
+    if (t === 'string[]')
+        return 'strings';
+    return null;
+}
+function planReactForm(root, map, opts, ep) {
+    if (ep.method === 'GET' || ep.method === 'HEAD')
+        throw new ToolError('form_needs_body', `${ep.name} is a ${ep.method} endpoint; a form sends data with POST, PUT or PATCH.`);
+    const p = place(root, map, opts);
+    if (exists(join(root, p.file)))
+        throw new ToolError('route_exists', `${p.file} already exists.`);
+    const n = names(opts.name);
+    const params = routeParamsOf(p.route);
+    const { args, missing, ps } = callArgs(root, ep, params, (x) => x === 'body');
+    if (missing.length)
+        throw new ToolError('screen_args', `${ep.name}() needs ${missing.join(', ')}, which the page does not have.`, `Give the route a matching parameter, for example: --path /${kebab(n.base)}/:${missing[0]}`);
+    const body = ps.find((x) => x.name === 'body');
+    if (!body)
+        throw new ToolError('form_needs_body', `${ep.name}() takes no request body, so there is nothing for a form to send.`);
+    const partial = /^Partial</.test(body.type);
+    const model = map.models.find((m) => m.name === body.type.replace(/^Partial<(.+)>$/, '$1'));
+    if (!model)
+        throw new ToolError('form_fields', `The request type ${body.type} is not a model codz knows, so it cannot build the inputs.`);
+    const fields = model.fields.map((f) => ({ f, k: kind(f.type), required: !partial && !f.nullable }));
+    const cannot = fields.filter((x) => !x.k && x.required).map((x) => `${x.f.name} (${x.f.type})`);
+    if (cannot.length)
+        throw new ToolError('form_fields', `${model.name} has required fields a form cannot fill: ${cannot.join(', ')}.`, `Write the form for ${ep.name} by hand, or make those fields optional.`);
+    const usable = fields.filter((x) => x.k);
+    const key = (s) => (IDENT.test(s) ? s : `'${s}'`);
+    const get = (s) => (IDENT.test(s) ? `values.${s}` : `values['${s}']`);
+    const value = (x) => {
+        const v = get(x.f.name);
+        const conv = x.k === 'number' ? `Number(${v})` : x.k === 'strings' ? `${v}.split(',').map((s) => s.trim()).filter(Boolean)` : v;
+        if (x.k === 'bool' || x.required)
+            return conv;
+        return `${v} === '' ? undefined : ${conv}`;
+    };
+    const pc = paramsCode(params);
+    const c = map.conventions;
+    const input = (x) => {
+        const id = kebab(x.f.name);
+        if (x.k === 'bool')
+            return [`        <label>`, `          <input type="checkbox" checked={${get(x.f.name)}} onChange={(e) => setValues({ ...values, ${key(x.f.name)}: e.target.checked })} />`, `          ${x.f.name}`, '        </label>'].join('\n');
+        const type = x.k === 'number' ? 'number' : /email/i.test(x.f.name) ? 'email' : 'text';
+        return [
+            `        <label htmlFor="${id}">${x.f.name}${x.required ? ' *' : ''}</label>`,
+            `        <input id="${id}" type="${type}"${x.required ? ' required' : ''}${x.k === 'strings' ? ' placeholder="a, b, c"' : ''} value={${get(x.f.name)}} onChange={(e) => setValues({ ...values, ${key(x.f.name)}: e.target.value })} />`,
+        ].join('\n');
+    };
+    const pre = reactPrefill(root, map, opts.load, usable.map((x) => ({ json: x.f.name, kind: x.k })), params, key);
+    const apiFrom = apiImport(root, map, p.file, ep);
+    const preFrom = pre ? apiImport(root, map, p.file, pre.ep) : '';
+    const page = [
+        `import { ${pre ? 'useEffect, ' : ''}useState, type FormEvent } from 'react';`,
+        `import { ${params.length ? 'useNavigate, useParams' : 'useNavigate'} } from 'react-router-dom';`,
+        ...(pre && preFrom === apiFrom ? [`import { ${[ep.name, pre.ep.name].sort().join(', ')} } from '${apiFrom}';`] : [`import { ${ep.name} } from '${apiFrom}';`, ...(pre ? [`import { ${pre.ep.name} } from '${preFrom}';`] : [])]),
+        `import type { ${model.name} } from '${importPath(p.file, model.file, c).replace(/\.tsx?$/, '')}';`,
+        '',
+        `export default function ${n.component}() {`,
+        ...pc.lines,
+        '  const navigate = useNavigate();',
+        `  const [values, setValues] = useState({ ${usable.map((x) => `${key(x.f.name)}: ${x.k === 'bool' ? 'false' : "''"}`).join(', ')} });`,
+        '  const [saving, setSaving] = useState(false);',
+        '  const [error, setError] = useState<string | null>(null);',
+        ...(pre?.lines ?? []),
+        '',
+        '  async function submit(e: FormEvent<HTMLFormElement>) {',
+        '    e.preventDefault();',
+        '    setSaving(true);',
+        '    setError(null);',
+        '    try {',
+        `      const body: ${partial ? `Partial<${model.name}>` : model.name} = {`,
+        ...usable.map((x) => `        ${key(x.f.name)}: ${value(x)},`),
+        '      };',
+        `      await ${ep.name}(${[args, 'body'].filter(Boolean).join(', ')});`,
+        '      navigate(-1);',
+        '    } catch (err) {',
+        '      setError(err instanceof Error ? err.message : String(err));',
+        '    } finally {',
+        '      setSaving(false);',
+        '    }',
+        '  }',
+        '',
+        '  return (',
+        '    <main>',
+        `      <h1>${n.title}</h1>`,
+        '      <form onSubmit={submit}>',
+        ...usable.map(input),
+        '        {error && <p role="alert">{error}</p>}',
+        `        <button type="submit" disabled={saving}>{saving ? 'Saving…' : 'Save'}</button>`,
+        '      </form>',
+        '    </main>',
+        '  );',
+        '}',
+        '',
+    ].join('\n');
+    return finish(root, 'screen add', p, page, map, opts, [`Create ${p.file}: a form for ${model.name} (${usable.length} field${usable.length === 1 ? '' : 's'}) that calls ${ep.name}() and goes back after saving`], []);
+}

package/dist/skills/report.js

@@ -0,0 +1,75 @@
+// codz report: what codz did in this project, for beta feedback. It is
+// built from codz's own records (.codz/history.json and events.jsonl) and
+// holds counts, dates and the setup (framework, HTTP client, router, ...), never
+// code, file names, endpoint paths or URLs, so it can be pasted into a form.
+import { readEvents } from "../core/events.js";
+import { readHistory } from "../core/changeset.js";
+/** Conventions that describe the setup without naming anything in the project. */
+const SETUP_KEYS = ['http', 'dataFetching', 'stateManagement', 'di', 'router', 'ui', 'flavor', 'bundler', 'serialization', 'apiStyle', 'fileSync', 'routerStyle'];
+const day = (iso) => iso.slice(0, 10);
+/** History ids start with the UTC time: 20261029-143012-ab12cd. */
+const idDay = (id) => (/^(\d{4})(\d{2})(\d{2})-/.exec(id) ? id.replace(/^(\d{4})(\d{2})(\d{2})-.*$/, '$1-$2-$3') : '');
+export function buildReport(root, adapter, map, version) {
+    const events = readEvents(root);
+    const history = readHistory(root);
+    const setup = {};
+    for (const k of SETUP_KEYS) {
+        const v = map.conventions[k];
+        if (typeof v === 'string' && v && /^[\w-]+$/.test(v))
+            setup[k] = v;
+    }
+    const byCmd = new Map();
+    const byCode = new Map();
+    for (const e of events) {
+        const c = byCmd.get(e.cmd) ?? { runs: 0, failed: 0 };
+        c.runs++;
+        if (!e.ok) {
+            c.failed++;
+            byCode.set(e.code ?? 'unknown', (byCode.get(e.code ?? 'unknown') ?? 0) + 1);
+        }
+        byCmd.set(e.cmd, c);
+    }
+    const bySkill = new Map();
+    for (const h of history) {
+        const s = bySkill.get(h.skill) ?? { applied: 0, undone: 0 };
+        s.applied++;
+        if (h.undone)
+            s.undone++;
+        bySkill.set(h.skill, s);
+    }
+    const days = new Set([...events.map((e) => day(e.t)), ...history.map((h) => idDay(h.id)).filter(Boolean)]);
+    const sorted = [...days].sort();
+    const applied = history.length;
+    const undone = history.filter((h) => h.undone).length;
+    return {
+        codz: version,
+        node: process.versions.node,
+        os: process.platform,
+        framework: adapter.id,
+        setup,
+        size: { endpoints: map.endpoints.length, models: map.models.length, routes: map.routes.length },
+        activity: { first: sorted[0], last: sorted.at(-1), activeDays: sorted.length },
+        commands: [...byCmd].map(([name, c]) => ({ name, ...c })).sort((a, b) => b.runs - a.runs),
+        errors: [...byCode].map(([code, count]) => ({ code, count })).sort((a, b) => b.count - a.count),
+        changes: { applied, undone, undoRate: applied ? `${Math.round((undone / applied) * 100)}%` : '-', bySkill: [...bySkill].map(([skill, s]) => ({ skill, ...s })).sort((a, b) => b.applied - a.applied) },
+    };
+}
+export function renderReport(r) {
+    const out = [
+        `codz ${r.codz} · Node ${r.node} · ${r.os}`,
+        `Project: ${r.framework}${Object.keys(r.setup).length ? ` (${Object.entries(r.setup).map(([k, v]) => `${k} ${v}`).join(', ')})` : ''}`,
+        `Size: ${r.size.endpoints} endpoints, ${r.size.models} models, ${r.size.routes} routes`,
+        `Used on ${r.activity.activeDays} day${r.activity.activeDays === 1 ? '' : 's'}${r.activity.first ? `, ${r.activity.first} to ${r.activity.last}` : ''}`,
+        '',
+        `Changes: ${r.changes.applied} applied, ${r.changes.undone} undone (undo rate ${r.changes.undoRate})`,
+        ...r.changes.bySkill.map((s) => `  ${s.skill.padEnd(16)} ${String(s.applied).padStart(4)} applied  ${String(s.undone).padStart(3)} undone`),
+        '',
+        'Commands:',
+        ...(r.commands.length ? r.commands.map((c) => `  ${c.name.padEnd(16)} ${String(c.runs).padStart(4)} runs  ${c.failed ? `${c.failed} failed` : ''}`.trimEnd()) : ['  none recorded yet']),
+        ...(r.errors.length ? ['', 'Errors:', ...r.errors.map((e) => `  ${e.code.padEnd(24)} ${e.count}`)] : []),
+        '',
+        'This report has counts and setup names only: no code, file names, endpoint paths or URLs.',
+        'Paste it into the beta feedback form, or share the JSON from codz report --json.',
+    ];
+    return out.join('\n');
+}

package/dist/skills/route.js

@@ -0,0 +1,230 @@
+// route add <name> [--path /x/:id]: a new screen and its route.
+//
+// GetX → a module (binding, controller, view, GetPage). go_router → a page
+// widget plus a GoRoute in the router's routes list. Navigator → a page plus an
+// entry in MaterialApp routes: {}. Next.js → app/<path>/page.tsx (or pages/).
+import { join, posix } from 'node:path';
+import { addDartImport, importUri } from "../adapters/flutter.js";
+import { matchBrace } from "../adapters/source.js";
+import { loadMap } from "../core/cache.js";
+import { buildChangeSet } from "../core/changeset.js";
+import { loadConfig } from "../core/config.js";
+import { detectEol, exists, readJson, readText, walk, withEol } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+import { camel, kebab, pascal, snake, words } from "../input/naming.js";
+import { planModuleAdd } from "./module.js";
+function normPath(name, path) {
+    let p = path ?? `/${kebab(name)}`;
+    if (!p.startsWith('/'))
+        p = `/${p}`;
+    p = p.replace(/\[(\w+)\]/g, ':$1').replace(/\{([^/{}]+)\}/g, ':$1');
+    return { path: p, params: [...p.matchAll(/:(\w+)/g)].map((m) => m[1]) };
+}
+// ---------------- Flutter ----------------
+function pageSuffix(map) {
+    const screens = map.routes.filter((r) => /Screen$/.test(r.name)).length;
+    const pages = map.routes.filter((r) => /Page$/.test(r.name)).length;
+    return screens > pages ? 'Screen' : 'Page';
+}
+/** Where pages live: next to an existing page as features/<name>/ or screens/. */
+function pageFile(root, map, cls, base) {
+    const dart = walk(root, 'lib', { exts: ['.dart'] });
+    for (const r of map.routes) {
+        const f = dart.find((x) => new RegExp(`class\\s+${r.name}\\s+extends`).test(readText(join(root, x)) ?? ''));
+        if (!f)
+            continue;
+        const dir = posix.dirname(f);
+        const parent = posix.dirname(dir);
+        // features/home/home_page.dart → features/<name>/<name>_page.dart
+        if (/\/(features|modules|pages|screens|views)$/.test(parent) || parent.endsWith('/features'))
+            return `${parent}/${base}/${snake(cls)}.dart`;
+        return `${dir}/${snake(cls)}.dart`;
+    }
+    return exists(join(root, 'lib/features')) ? `lib/features/${base}/${snake(cls)}.dart` : `lib/screens/${snake(cls)}.dart`;
+}
+function pageWidget(cls, title, params) {
+    const fields = params.map((p) => `  final String ${camel(p)};\n`).join('');
+    const ctor = params.length ? `const ${cls}({super.key, ${params.map((p) => `required this.${camel(p)}`).join(', ')}});` : `const ${cls}({super.key});`;
+    return [
+        "import 'package:flutter/material.dart';",
+        '',
+        `class ${cls} extends StatelessWidget {`,
+        `  ${ctor}`,
+        fields ? `\n${fields.trimEnd()}` : '',
+        '',
+        '  @override',
+        '  Widget build(BuildContext context) {',
+        '    return Scaffold(',
+        `      appBar: AppBar(title: const Text('${title}')),`,
+        `      body: ${params.length ? `Center(child: Text('${title} \$${camel(params[0])}'))` : `const Center(child: Text('${title}'))`},`,
+        '    );',
+        '  }',
+        '}',
+        '',
+    ]
+        .filter((l, i, a) => !(l === '' && a[i - 1] === ''))
+        .join('\n');
+}
+function planFlutterRoute(root, map, opts, files, summary, warnings) {
+    const c = map.conventions;
+    const { path, params } = normPath(opts.name, opts.path);
+    const cls = pascal(`${opts.name} ${pageSuffix(map)}`).replace(/(Page|Screen)(Page|Screen)$/, '$1');
+    if (map.routes.some((r) => r.path.replace(/\{([^/{}]+)\}/g, ':$1') === path))
+        throw new ToolError('route_exists', `There is already a route for ${path}.`);
+    const file = pageFile(root, map, cls, snake(opts.name.replace(/(page|screen)$/i, '')) || snake(opts.name));
+    if (exists(join(root, file)))
+        throw new ToolError('file_exists', `${file} already exists.`);
+    const title = words(opts.name.replace(/(page|screen)$/i, '')).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+    files.set(file, pageWidget(cls, title, params));
+    summary.push(`Create ${file}: ${cls}`);
+    const args = params.map((p) => `${camel(p)}: state.pathParameters['${p}']!`).join(', ');
+    if (c.router === 'go_router') {
+        const dart = walk(root, 'lib', { exts: ['.dart'] });
+        const rf = dart.find((f) => /\bGoRouter\s*\(/.test(readText(join(root, f)) ?? ''));
+        if (!rf) {
+            warnings.push(`No GoRouter(...) found; add GoRoute(path: '${path}', builder: (context, state) => ${params.length ? '' : 'const '}${cls}(${args})) to your routes.`);
+            return;
+        }
+        const orig = readText(join(root, rf));
+        let t = orig.replace(/\r\n/g, '\n');
+        const g = /\bGoRouter\s*\(/.exec(t);
+        const gClose = matchBrace(t, g.index + g[0].length - 1, 'dart');
+        const routes = /\broutes\s*:\s*(?:<[^>]*>\s*)?\[/.exec(t.slice(g.index, gClose));
+        if (!routes) {
+            warnings.push(`${rf} has no routes: [...] list; add the GoRoute for ${path} yourself.`);
+            return;
+        }
+        const open = g.index + routes.index + routes[0].length - 1;
+        const close = matchBrace(t, open, 'dart');
+        const closeIndent = t.slice(t.lastIndexOf('\n', close) + 1, close).match(/^[ \t]*/)[0];
+        const ind = `${closeIndent}  `;
+        const name = camel(opts.name.replace(/(page|screen)$/i, '')) || camel(opts.name);
+        const entry = [
+            `${ind}GoRoute(`,
+            `${ind}  path: '${path}',`,
+            `${ind}  name: '${name}',`,
+            `${ind}  builder: (context, state) => ${params.length ? '' : 'const '}${cls}(${args}),`,
+            `${ind}),`,
+        ].join('\n');
+        const before = t.slice(0, close).replace(/\s*$/, '');
+        t = `${before}${before.endsWith('[') || before.endsWith(',') ? '' : ','}\n${entry}\n${closeIndent}${t.slice(close)}`;
+        t = addDartImport(t, importUri(rf, file, c));
+        files.set(rf, withEol(t, detectEol(orig)));
+        summary.push(`Update ${rf}: GoRoute '${path}' → ${cls}`);
+        summary.push(`Open it with: context.go('${path.replace(/:(\w+)/g, '\${$1}')}')  or  context.goNamed('${name}'${params.length ? `, pathParameters: {${params.map((p) => `'${p}': ${camel(p)}`).join(', ')}}` : ''})`);
+        return;
+    }
+    if (c.router === 'auto_route') {
+        warnings.push(`auto_route needs @RoutePage() and a build_runner run; add ${cls} to your AppRouter routes and run dart run build_runner build.`);
+        return;
+    }
+    // Navigator: MaterialApp(routes: {...}).
+    const mainFile = 'lib/main.dart';
+    const orig = readText(join(root, mainFile));
+    if (orig === null)
+        return;
+    let t = orig.replace(/\r\n/g, '\n');
+    if (params.length) {
+        warnings.push(`Navigator named routes cannot read ${params.map((p) => `:${p}`).join(', ')} from the path; open ${cls} with Navigator.push(context, MaterialPageRoute(builder: (_) => ${cls}(...))).`);
+        return;
+    }
+    const app = /\bMaterialApp\s*\(/.exec(t);
+    if (!app)
+        return;
+    const aClose = matchBrace(t, app.index + app[0].length - 1, 'dart');
+    const routes = /\broutes\s*:\s*(?:<[^>]*>\s*)?\{/.exec(t.slice(app.index, aClose));
+    const entry = `'${path}': (context) => const ${cls}(),`;
+    if (routes) {
+        const open = app.index + routes.index + routes[0].length - 1;
+        const close = matchBrace(t, open, 'dart');
+        const closeIndent = t.slice(t.lastIndexOf('\n', close) + 1, close).match(/^[ \t]*/)[0];
+        const before = t.slice(0, close).replace(/\s*$/, '');
+        t = `${before}${before.endsWith('{') || before.endsWith(',') ? '' : ','}\n${closeIndent}  ${entry}\n${closeIndent}${t.slice(close)}`;
+    }
+    else {
+        const indent = t.slice(t.lastIndexOf('\n', app.index) + 1).match(/^[ \t]*/)[0];
+        const at = app.index + app[0].length;
+        t = `${t.slice(0, at)}\n${indent}  routes: {\n${indent}    ${entry}\n${indent}  },${t.slice(at)}`;
+    }
+    t = addDartImport(t, importUri(mainFile, file, c));
+    files.set(mainFile, withEol(t, detectEol(orig)));
+    summary.push(`Update ${mainFile}: route '${path}' → ${cls}`);
+    summary.push(`Open it with: Navigator.pushNamed(context, '${path}')`);
+}
+// ---------------- Next.js ----------------
+function nextMajor(root) {
+    const pkg = readJson(join(root, 'package.json'));
+    const v = pkg?.dependencies?.next ?? pkg?.devDependencies?.next ?? '';
+    return Number(/\d+/.exec(v)?.[0] ?? 15);
+}
+function planNextRoute(root, map, opts, files, summary) {
+    const { path, params } = normPath(opts.name, opts.path);
+    const appDir = ['src/app', 'app'].find((d) => exists(join(root, d)));
+    const pagesDir = ['src/pages', 'pages'].find((d) => exists(join(root, d)));
+    const segs = path.split('/').filter(Boolean).map((s) => s.replace(/^:(\w+)$/, '[$1]'));
+    const comp = pascal(`${opts.name} page`).replace(/PagePage$/, 'Page');
+    const title = words(opts.name.replace(/page$/i, '')).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+    const tsx = exists(join(root, 'tsconfig.json'));
+    const typed = (s) => (tsx ? s : '');
+    let file;
+    let body;
+    if (appDir || !pagesDir) {
+        file = posix.join(appDir ?? 'app', ...segs, `page.${tsx ? 'tsx' : 'jsx'}`);
+        if (!params.length) {
+            body = `export default function ${comp}() {\n  return (\n    <main>\n      <h1>${title}</h1>\n    </main>\n  );\n}\n`;
+        }
+        else if (nextMajor(root) >= 15) {
+            const t = `{ ${params.map((p) => `${p}: string`).join('; ')} }`;
+            body = `export default async function ${comp}({ params }${typed(`: { params: Promise<${t}> }`)}) {\n  const { ${params.join(', ')} } = await params;\n  return (\n    <main>\n      <h1>${title} {${params[0]}}</h1>\n    </main>\n  );\n}\n`;
+        }
+        else {
+            const t = `{ ${params.map((p) => `${p}: string`).join('; ')} }`;
+            body = `export default function ${comp}({ params }${typed(`: { params: ${t} }`)}) {\n  return (\n    <main>\n      <h1>${title} {params.${params[0]}}</h1>\n    </main>\n  );\n}\n`;
+        }
+    }
+    else {
+        file = posix.join(pagesDir, ...(segs.length ? segs : ['index'])) + `.${tsx ? 'tsx' : 'jsx'}`;
+        body = params.length
+            ? `import { useRouter } from 'next/router';\n\nexport default function ${comp}() {\n  const { ${params.join(', ')} } = useRouter().query;\n  return (\n    <main>\n      <h1>${title} {${params[0]}}</h1>\n    </main>\n  );\n}\n`
+            : `export default function ${comp}() {\n  return (\n    <main>\n      <h1>${title}</h1>\n    </main>\n  );\n}\n`;
+    }
+    if (exists(join(root, file)))
+        throw new ToolError('route_exists', `${file} already exists.`);
+    const clash = map.routes.find((r) => r.path.replace(/\{([^/{}]+)\}/g, ':$1').replace(/\[(\w+)\]/g, ':$1') === path);
+    if (clash)
+        throw new ToolError('route_exists', `There is already a page for ${path} (${clash.file}).`);
+    files.set(file, body);
+    summary.push(`Create ${file}: ${comp} at ${path.replace(/:(\w+)/g, '[$1]')}`);
+    summary.push(params.length ? `Link to it with: <Link href={\`${path.replace(/:(\w+)/g, '${$1}')}\`}>` : `Link to it with: <Link href="${path}">`);
+}
+export async function planRouteAdd(root, adapter, opts) {
+    if (!/^[A-Za-z][\w-]*$/.test(opts.name))
+        throw new ToolError('bad_args', `"${opts.name}" is not a valid route name.`, 'Use letters, digits, - or _, e.g. order-details.');
+    const { map } = await loadMap(root, adapter, loadConfig(root).conventions);
+    const c = map.conventions;
+    if (adapter.id === 'flutter' && (c.router === 'getx' || c.di === 'getx' || c.stateManagement === 'getx')) {
+        const cs = await planModuleAdd(root, adapter, { name: opts.name, initial: opts.initial });
+        cs.skill = 'route add';
+        if (opts.path && /:/.test(opts.path))
+            cs.warnings.push(`GetX routes are /${kebab(opts.name)}; pass ${normPath(opts.name, opts.path).params.join(', ')} with Get.toNamed(Routes.X, parameters: {...}) and read Get.parameters in the controller.`);
+        return cs;
+    }
+    if (adapter.id === 'android')
+        return (await import("./androidUi.js")).planAndroidRoute(root, map, opts);
+    if (adapter.id === 'react-native')
+        return (await import("./reactNativeUi.js")).planRnRoute(root, map, opts);
+    if (adapter.id === 'react')
+        return (await import("./reactUi.js")).planReactRoute(root, map, opts);
+    if (adapter.id === 'ios')
+        return (await import("./iosUi.js")).planIosRoute(root, map, opts);
+    const files = new Map();
+    const summary = [];
+    const warnings = [];
+    if (adapter.id === 'flutter')
+        planFlutterRoute(root, map, opts, files, summary, warnings);
+    else if (adapter.id === 'nextjs')
+        planNextRoute(root, map, opts, files, summary);
+    else
+        throw new ToolError('not_supported', `route add needs the Next.js, Flutter, React Native or Android adapter; this project uses the ${adapter.id} adapter.`);
+    return buildChangeSet(root, 'route add', { files, summary, warnings, generated: [] });
+}