codz-cli 0.1.3 → 0.1.8

package/dist/core/commands.js

@@ -29,6 +29,8 @@ export const FLAGS = {
     url: { value: "'<url>'", desc: 'A URL (or "POST https://...")' },
     method: { value: '<GET|POST|...>', desc: 'HTTP method (api add), or only these methods (api import)', choices: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] },
     clipboard: { desc: 'Read the cURL command (and response) from the clipboard' },
+    'from-clipboard': { desc: 'Read the JSON from the clipboard' },
+    split: { desc: 'One file per model, instead of nested models in the file of the model that uses them' },
     sample: { value: '<file.json>', desc: 'Response sample; repeat for several samples', repeat: true, path: true },
     'request-sample': { value: '<file.json>', desc: 'Request body sample', path: true },
     name: { value: '<functionName>', desc: 'Override the derived function name' },
@@ -56,6 +58,12 @@ export const FLAGS = {
     spec: { value: '<file>', desc: 'OpenAPI, Swagger, Postman or HAR file to take the endpoints from', path: true },
     'no-forms': { desc: 'No create or edit form screens' },
     'no-tests': { desc: 'Do not generate tests' },
+    // mock serve
+    port: { value: '<n>', desc: 'Port for the mock API (default 4010)' },
+    delay: { value: '<ms>', desc: 'Wait before each answer, so loading states show (default 300)' },
+    items: { value: '<n>', desc: 'Items in each list to start with (default 5)' },
+    lan: { desc: 'Listen on your network too, for a phone on the same Wi-Fi (default: this computer only)' },
+    scenario: { value: '<name>', desc: 'How the mock answers at the start; switch live at /__codz', choices: ['normal', 'empty', 'error', 'unauthorized', 'slow', 'offline'] },
     // api diff
     format: { value: '<text|md|json|sarif>', desc: 'Report format (default text; md for a pull request comment, sarif for code scanning)', choices: ['text', 'md', 'json', 'sarif'] },
     report: { value: '<file>', desc: 'Write the report to a file', path: true },
@@ -108,6 +116,9 @@ export const FLAGS = {
     refresh: { desc: 'Download the catalog again even if it has not changed' },
     clear: { desc: 'Delete every downloaded starter' },
     'no-browser': { desc: 'Do not open the login page; print it only' },
+    paginate: { desc: 'List screens: load page after page as you scroll (the endpoint needs a page or offset parameter)' },
+    search: { desc: 'List screens: a search box (on the server with a q/search parameter, otherwise over the loaded items)' },
+    'model-dir': { value: '<folder>', desc: 'Write new models into this folder for this command only (e.g. lib/features/orders/models); set modelsFolder in codz.config.yaml to change it for good', path: true },
 };
 export const GLOBAL_FLAGS = ['json', 'cwd', 'root', 'no-color', 'help', 'h', 'version', 'v'];
 export const CHANGE_FLAGS = ['dry-run', 'plan', 'yes', 'y', 'allow-dirty', 'no-format', 'no-verify', 'commit', 'commit-message', 'open'];
@@ -116,9 +127,9 @@ export const COMMAND_LIST = [
     { group: 'Start', cmd: 'init', usage: '[--root <folder>] [--force]', summary: 'Detect the framework, scan, write codz.config.yaml; offers to set up an API layer when there is none', flags: ['force', 'architecture', 'base-url', 'yes', 'y'] },
     { group: 'Start', cmd: 'setup', usage: '[--architecture <id>] [--base-url <url>]', summary: 'Create the API layer for a fresh project', flags: ['architecture', 'base-url'], change: true },
     { group: 'Start', cmd: 'explain', usage: '[--rescan]', summary: 'Show routes, endpoints, models, locales and conventions', flags: ['rescan'] },
-    { group: 'Endpoints', cmd: 'api', sub: 'add', usage: '[input] [options]', summary: 'Add an endpoint: model, function and registration', flags: ['curl', 'url', 'method', 'clipboard', 'sample', 'request-sample', 'name', 'path', 'model-name', 'no-unwrap', 'into', 'no-load'], change: true, notes: ['Input: --curl, --url, --clipboard, or a cURL command or URL pasted on stdin, optionally followed by "response:" and JSON (and "request:" and JSON). A response sample is strongly recommended.'] },
-    { group: 'Endpoints', cmd: 'api', sub: 'import', usage: '<file> [filters]', summary: 'Add every endpoint from an OpenAPI 3, Swagger 2, Postman or HAR file', flags: ['tag', 'only', 'path', 'method', 'max', 'list', 'base-url', 'include-errors', 'skip-conflicts'], change: true, args: 'file' },
-    { group: 'Endpoints', cmd: 'api', sub: 'sync', usage: '<file> [--add] [--remove] [--check]', summary: 'Bring endpoints in line with an API spec: update changed ones, report breaking changes', flags: ['add', 'remove', 'check', 'tag', 'path', 'base-url'], change: true, args: 'file' },
+    { group: 'Endpoints', cmd: 'api', sub: 'add', usage: '[input] [options]', summary: 'Add an endpoint: model, function and registration', flags: ['curl', 'url', 'method', 'clipboard', 'sample', 'request-sample', 'name', 'path', 'model-name', 'no-unwrap', 'into', 'no-load', 'model-dir', 'split'], change: true, notes: ['Input: --curl, --url, --clipboard, or a cURL command or URL pasted on stdin, optionally followed by "response:" and JSON (and "request:" and JSON). A response sample is strongly recommended.'] },
+    { group: 'Endpoints', cmd: 'api', sub: 'import', usage: '<file> [filters]', summary: 'Add every endpoint from an OpenAPI 3, Swagger 2, Postman or HAR file', flags: ['tag', 'only', 'path', 'method', 'max', 'list', 'base-url', 'include-errors', 'skip-conflicts', 'model-dir', 'split'], change: true, args: 'file' },
+    { group: 'Endpoints', cmd: 'api', sub: 'sync', usage: '<file> [--add] [--remove] [--check]', summary: 'Bring endpoints in line with an API spec: update changed ones, report breaking changes', flags: ['add', 'remove', 'check', 'tag', 'path', 'base-url', 'model-dir', 'split'], change: true, args: 'file' },
     { group: 'Endpoints', cmd: 'api', sub: 'diff', usage: '<old spec> <new spec> [--format md] [--fail-on breaking]', summary: 'What changed between two API specs, what breaks, and the lines in this project that use it', flags: ['format', 'report', 'fail-on', 'tag', 'path'], notes: ['Breaking: an operation removed, a response field removed or retyped, a new path parameter, a new required request field. Warning: a field that can now be null, a removed query parameter, a retyped request field.', 'Inside a project each change lists the files and lines that use it. Works outside a project too.', 'CI: codz api diff main.yaml pr.yaml --format md --report api-diff.md (exit 1 on breaking changes); --format sarif for GitHub code scanning.'] },
     { group: 'Endpoints', cmd: 'api', sub: 'update', usage: '<endpoint> --sample <file>', summary: 'Rebuild the response model from new samples', flags: ['sample', 'no-unwrap'], change: true, args: 'endpoint' },
     { group: 'Endpoints', cmd: 'api', sub: 'remove', usage: '<endpoint>', summary: 'Remove an endpoint and list callers that break', flags: [], change: true, args: 'endpoint' },
@@ -126,14 +137,23 @@ export const COMMAND_LIST = [
     { group: 'Endpoints', cmd: 'api', sub: 'wire', usage: '<endpoint> --into <module>', summary: "Call an endpoint from a module's controller (GetX)", flags: ['into', 'no-load'], change: true, args: 'endpoint' },
     { group: 'Endpoints', cmd: 'api', sub: 'list', usage: '[filter]', summary: 'Every endpoint: method, path, function, response, file', flags: [] },
     { group: 'Endpoints', cmd: 'api', sub: 'show', usage: '<endpoint>', summary: 'One endpoint: signature, models, every place that uses it', flags: [], args: 'endpoint' },
+    { group: 'Screens and app', cmd: 'assets', usage: '', summary: 'Typed names for images, icons and fonts, kept in step with the files; lists unused ones', flags: [], change: true, notes: ['Flutter: lib/gen/assets.dart (AppImages.logo, AppFonts.inter) and every asset folder and font family in pubspec.yaml. React Native: src/assets/index.ts with require() for each file. Next.js and Vite: paths for public/ (and imports for src/assets in Vite). Android and iOS already have typed resources; codz checks names and lists unused drawables.', 'Run it again after adding or removing files.'] },
+    { group: 'Screens and app', cmd: 'env', sub: 'add', usage: '<name> --base-url <url>', summary: 'Add an API environment (staging, qa, ...) the app can run against', flags: ['base-url', 'force'], change: true, notes: ['Next.js and Expo: .env.<name> plus npm scripts that load it (dotenv-cli). Vite: .env.<name> and --mode <name>. React Native CLI: an API_URLS table in env.ts. Flutter: env/<name>.json for --dart-define-from-file, and a VS Code run configuration. Android: an apiUrls table in the app build file, picked with -PapiEnv=<name> into BuildConfig.BASE_URL. iOS: an AppEnvironment enum, picked with APP_ENV in the scheme.', 'The base URL you have now becomes the default environment. Never writes .env.local.'] },
+    { group: 'Screens and app', cmd: 'env', sub: 'list', usage: '', summary: 'The API environments and their base URLs', flags: [] },
+    { group: 'Screens and app', cmd: 'env', sub: 'use', usage: '<name>', summary: 'Switch the app to an environment (React Native CLI, Android, iOS)', flags: [], change: true },
+    { group: 'Endpoints', cmd: 'model', usage: '<Name> --from-clipboard | --sample <file.json>', summary: 'A model (and its nested models) from JSON, without an endpoint', flags: ['from-clipboard', 'sample', 'model-dir', 'no-unwrap', 'force', 'split'], change: true, notes: ['Reads the JSON from --from-clipboard, --sample, or standard input (pipe or paste, then Ctrl+D). Nested objects become their own classes (Order → OrderItem, OrderAddress), written in the same file as the main model; --split gives each its own file. A list gives the model of its items; {"data": ...} is unwrapped unless --no-unwrap.', 'Writes into the models folder, or --model-dir <folder> for this model only. An existing model with the same name is replaced only with --force.'] },
+    { group: 'Endpoints', cmd: 'field', sub: 'add', usage: '<Model> <name:type> [...]', summary: 'Add a field to a model, in every place the model spells it', flags: [], change: true, notes: ['Types: string, int, double, bool, date, any, a model name, or a list (string[], list<Category>). End with ? for an optional field: rating:double?. The name is the JSON key (created_at); codz writes the property name the project uses (createdAt).', 'TypeScript interfaces, Dart classes (plain, json_serializable, freezed: constructor, fromJson, field and toJson), Kotlin data classes and Swift Codable structs (CodingKeys too). Only the new lines are added; then it lists the files that use the model.'] },
+    { group: 'Endpoints', cmd: 'field', sub: 'remove', usage: '<Model> <field> [...]', summary: 'Remove a field from a model and list the lines that still use it', flags: [], change: true },
+    { group: 'Endpoints', cmd: 'mock', sub: 'serve', usage: '[--spec <file>] [--port 4010] [--delay 300] [--items 5] [--scenario normal] [--lan]', summary: 'A local fake API with sample data, so screens show data before the backend exists', flags: ['spec', 'port', 'delay', 'items', 'scenario', 'lan'], notes: ["Answers the project's endpoints, or every operation in --spec (OpenAPI, Swagger, Postman, HAR), with sample data from the response models. A list and its items share in-memory data, so create, edit and delete work and the list shows the change; restarting resets it. Paths match by their last segments, so /v1/products reaches GET /products. Prints how to point the app at it (emulator, simulator, phone).", 'Scenarios check every screen state: empty (empty lists), error (500), unauthorized (401), slow (3 s), offline (connection drops). Open http://localhost:4010/__codz to switch them, for every endpoint or one, reset the data, and see each request with its body.'] },
     { group: 'Endpoints', cmd: 'mock', sub: 'add', usage: '<endpoint>... | --all', summary: 'Mock responses for building screens before the backend', flags: ['all', 'sample', 'keep-values', 'force'], change: true, args: 'endpoints', notes: ['Next.js, React Native and Flutter. Not yet on Android.'] },
     { group: 'Endpoints', cmd: 'test', sub: 'add', usage: '<endpoint>... | --all', summary: 'Unit tests for API functions with the network faked', flags: ['all'], change: true, args: 'endpoints', notes: ['Next.js: Vitest or Jest. React Native: Jest. Flutter: flutter_test with a fake Dio adapter. Android: JUnit with MockWebServer (adds the test dependencies).'] },
-    { group: 'Screens and app', cmd: 'screen', sub: 'add', usage: '<name> --api <endpoint> [--path /x/:id] [--form]', summary: 'A working screen (route, page, the call, loading, error, data), or a form with --form', flags: ['api', 'path', 'initial', 'form'], change: true, notes: ['Android: a Compose screen plus a ViewModel (Hilt, Koin or the service locator) with a UiState StateFlow, registered in the NavHost.'] },
+    { group: 'Screens and app', cmd: 'screen', sub: 'add', usage: '<name> --api <endpoint> [--path /x/:id] [--paginate] [--search] [--form]', summary: 'A working screen (route, page, the call, loading, error, data), or a form with --form', flags: ['api', 'path', 'initial', 'form', 'paginate', 'search'], change: true, notes: ['Android: a Compose screen plus a ViewModel (Hilt, Koin or the service locator) with a UiState StateFlow, registered in the NavHost.'] },
     { group: 'Screens and app', cmd: 'route', sub: 'add', usage: '<name> [--path /x/:id]', summary: 'Add a screen and its route (GetX module, GoRoute, Next.js page, React Navigation or Expo Router screen, Compose NavHost entry)', flags: ['path', 'initial'], change: true },
-    { group: 'Screens and app', cmd: 'feature', sub: 'add', usage: '<name> --spec <file> | --api <endpoint>...', summary: 'A whole feature in one change: endpoints, list, detail, create and edit screens, routes and tests', flags: ['spec', 'tag', 'path', 'api', 'base-url', 'architecture', 'initial', 'no-forms', 'no-tests', 'skip-conflicts', 'no-install'], change: true, notes: ['A project with no API layer yet is set up first, in the same change: the recommended architecture (or --architecture), with the base URL from --base-url or the spec.', 'Without --tag or --path, the endpoints are those whose path or tag names the feature (orders: /orders, /orders/{id}, /users/{id}/orders).', 'Screens: a list for a GET that returns a list, a detail for a GET with an id, a create form for a POST with a body, an edit form for a PUT or PATCH with a body. Other endpoints are added and listed.', 'Everything is planned in a private copy of the project and shown as one diff: one apply, one undo.'] },
+    { group: 'Screens and app', cmd: 'feature', sub: 'add', usage: '<name> --spec <file> | --api <endpoint>...', summary: 'A whole feature in one change: endpoints, list, detail, create and edit screens, routes and tests', flags: ['spec', 'tag', 'path', 'api', 'base-url', 'architecture', 'initial', 'no-forms', 'no-tests', 'skip-conflicts', 'no-install', 'model-dir', 'split'], change: true, notes: ['A project with no API layer yet is set up first, in the same change: the recommended architecture (or --architecture), with the base URL from --base-url or the spec.', 'Without --tag or --path, the endpoints are those whose path or tag names the feature (orders: /orders, /orders/{id}, /users/{id}/orders).', 'Screens: a list for a GET that returns a list, a detail for a GET with an id, a create form for a POST with a body, an edit form for a PUT or PATCH with a body. Other endpoints are added and listed.', 'Everything is planned in a private copy of the project and shown as one diff: one apply, one undo.'] },
     { group: 'Screens and app', cmd: 'auth', sub: 'add', usage: '[--login-path /auth/login] [--me-path /auth/me]', summary: 'Sign-in for this project: secure token storage, the token on every request, sign out on 401, a login screen and a guard', flags: ['login-path', 'me-path', 'logout-path', 'refresh-path', 'token-field', 'refresh-field', 'public'], change: true, notes: ['Next.js: server actions, an HttpOnly session cookie, middleware that sends signed-out visitors to /login, withAuth() for server calls.', 'React Native: expo-secure-store (or react-native-keychain), the fetch helper or axios sends the token, AuthProvider and useAuth().', 'Flutter: flutter_secure_storage, a Dio interceptor (refresh or sign out on 401), AuthService, a go_router redirect.', 'Android (Hilt): EncryptedSharedPreferences, an OkHttp interceptor, AuthApi, AuthRepository, a login screen with a ViewModel.'] },
     { group: 'Screens and app', cmd: 'module', sub: 'add', usage: '<name> [--api <endpoint>]', summary: 'Create a GetX module: binding, controller, view, route', flags: ['api', 'initial', 'no-load'], change: true },
     { group: 'Screens and app', cmd: 'locale', sub: 'add', usage: '<lang> [--from en]', summary: 'Add a language: copies every key from the default one', flags: ['from'], change: true },
+    { group: 'Screens and app', cmd: 'locale', sub: 'extract', usage: '[files...]', summary: 'Move the text in screens into the locale files and read it back', flags: [], change: true, args: 'file', notes: ['Finds Text(...) and hint, label and tooltip text (Flutter), JSX text and placeholder, title, alt and aria-label (React, Next.js, React Native), and Text("...") in Compose. Writes AppLocalizations.of(context)!.key (ARB, wiring it into MaterialApp the first time), \'key\'.tr (GetX), t(\'key\') with next-intl or react-i18next, or stringResource(R.string.key) with strings.xml.', 'Keys are named after the screen (products.nothingHereYet); text in several screens goes under common, and text that already has a key reuses it. Without files, every screen.'] },
     { group: 'Screens and app', cmd: 'locale', sub: 'key', usage: '<key> "<text>" [--value hi="..."]', summary: 'Add a text key to every language file', flags: ['value', 'force'], change: true },
     { group: 'Screens and app', cmd: 'theme', sub: 'set', usage: '<name> <value> [...]', summary: 'Set a color (#hex), size (number) or font in the app theme', flags: [], change: true, args: 'theme', notes: ['Example: codz theme set primary "#6750A4" radius 12 font Inter'] },
     { group: 'Screens and app', cmd: 'templates', sub: 'list', usage: '', summary: 'Which templates the project customizes', flags: [] },
@@ -145,7 +165,6 @@ export const COMMAND_LIST = [
     { group: 'Setup', cmd: 'config', sub: 'get', usage: '<key>', summary: 'One convention', flags: [], args: 'configKey' },
     { group: 'Setup', cmd: 'config', sub: 'set', usage: '<key> <value>', summary: "Change one convention in codz.config.yaml ('' = detect)", flags: ['force'], change: true, args: 'configKey' },
     { group: 'Setup', cmd: 'config', sub: 'check', usage: '', summary: 'Find problems in codz.config.yaml (exit 1 on errors)', flags: [] },
-    { group: 'Setup', cmd: 'mcp', usage: '[--cwd <project>]', summary: 'Serve codz to AI agents and editors over the Model Context Protocol (stdio)', flags: [], notes: ['Every command becomes a tool (api add → api_add). Tools that edit code return a diff and a plan id; the apply tool applies it. Resources: codz://project and codz://commands.'] },
     { group: 'Setup', cmd: 'completion', usage: 'bash|zsh|fish', summary: 'Print the shell completion script', flags: [], args: 'shell' },
     { group: 'Starters (online)', cmd: 'new', usage: '[name] --template <id[@version]|folder>', summary: 'Create a project from a ready-made starter: from the catalog (free or bought) or a template folder', flags: ['template', 'org', 'dir', 'set', 'framework', 'state', 'router', 'http', 'cached', 'no-steps', 'dry-run', 'plan', 'yes', 'y'], notes: ['Shows every file and step first, then creates the folder in one step; codz undo inside the new project removes it again while it is unchanged. Catalog starters are checked against the signed catalog, and template scripts never run. Next: cd <name> && codz init.', 'This and the other starter commands are the only ones that use the network, and only to reach the starter catalog.'] },
     { group: 'Starters (online)', cmd: 'starters', sub: 'list', usage: '[--framework flutter] [--free] [--owned]', summary: 'Starters in the catalog: id, latest version, framework, price, api add support', flags: ['framework', 'state', 'router', 'http', 'owned', 'free', 'refresh', 'cached'] },

package/dist/core/modelGroup.js

@@ -0,0 +1,180 @@
+// One file per top-level model: nested models a change creates go into the
+// file of the model that uses them (order.dart holds Order, Customer,
+// OrderItem), instead of one file each. A nested model that several top-level
+// models use keeps its own file. Only files the change creates are touched;
+// imports of the merged files in the other planned files point at the main
+// file instead.
+//
+// Turn it off with --split, or modelFiles: split in codz.config.yaml.
+import { join, posix } from 'node:path';
+import { exists } from "./fsutil.js";
+export const modelLangOf = (adapterId) => (adapterId === 'flutter' ? 'dart' : adapterId === 'android' ? 'kt' : adapterId === 'ios' ? 'swift' : 'ts');
+const EXT = { ts: /\.tsx?$/, dart: /\.dart$/, kt: /\.kt$/, swift: /\.swift$/ };
+const DECL = {
+    ts: /^export\s+(?:interface|type)\s+(\w+)/gm,
+    dart: /^(?:abstract\s+|sealed\s+|final\s+)*class\s+(\w+)/gm,
+    kt: /^(?:@\w+(?:\([^)]*\))?\s*)*data\s+class\s+(\w+)/gm,
+    swift: /^(?:public\s+)?struct\s+(\w+)/gm,
+};
+/** The file's leading package/import/part lines, and the rest. */
+function splitHeader(text, lang) {
+    const lines = text.split('\n');
+    const isHead = (l) => (lang === 'ts' ? /^import\s/.test(l) : lang === 'dart' ? /^(import|part|export|library)\s/.test(l) : lang === 'kt' ? /^(package|import)\s/.test(l) : /^import\s/.test(l));
+    let i = 0;
+    const header = [];
+    while (i < lines.length && (isHead(lines[i]) || lines[i].trim() === '')) {
+        if (lines[i].trim())
+            header.push(lines[i]);
+        i++;
+    }
+    return { header, body: lines.slice(i).join('\n').replace(/\s+$/, '') };
+}
+const stem = (f) => posix.basename(f).replace(/\.[^.]+$/, '');
+const importTarget = (l) => /['"]([^'"]+)['"]/.exec(l)?.[1];
+const targetStem = (t) => posix.basename(t).replace(/\.(dart|ts|tsx|js)$/, '').replace(/\.(g|freezed)$/, '');
+/** Is this a file of models the project keeps models in? */
+function inModelsFolder(f, map) {
+    const c = map.conventions;
+    return Boolean((c.modelsFolder && f.startsWith(`${c.modelsFolder}/`)) || (c.modelsFile && f === c.modelsFile));
+}
+/**
+ * Groups the new model files of a planned change (--model-dir has already set
+ * modelsFolder for this run).
+ */
+export function groupNewModels(root, files, map, lang, split = false) {
+    if (split || map.conventions.modelFiles === 'split' || (lang === 'ts' && map.conventions.modelsLayout === 'single'))
+        return files;
+    // New model files and the models each declares.
+    const declared = new Map();
+    for (const [f, t] of files) {
+        if (!EXT[lang].test(f) || /(^|\/)index\.ts$/.test(f) || exists(join(root, f)) || !inModelsFolder(f, map))
+            continue;
+        const names = [...t.matchAll(DECL[lang])].map((m) => m[1]).filter((n) => !n.startsWith('_'));
+        if (names.length)
+            declared.set(f, names);
+    }
+    if (declared.size < 2)
+        return files;
+    const fileOf = new Map();
+    for (const [f, ns] of declared)
+        for (const n of ns)
+            fileOf.set(n, f);
+    // Which new files each new file uses.
+    const uses = new Map();
+    for (const f of declared.keys()) {
+        const body = splitHeader(files.get(f), lang).body;
+        const own = new Set(declared.get(f));
+        const used = new Set();
+        for (const [n, g] of fileOf)
+            if (g !== f && !own.has(n) && new RegExp(`\\b${n}\\b`).test(body))
+                used.add(g);
+        uses.set(f, used);
+    }
+    const usedBy = new Map();
+    for (const [f, us] of uses)
+        for (const u of us)
+            usedBy.set(u, (usedBy.get(u) ?? new Set()).add(f));
+    // Top-level: new files no other new file uses.
+    const tops = [...declared.keys()].filter((f) => !usedBy.has(f));
+    const reach = new Map();
+    for (const t of tops) {
+        const seen = new Set();
+        const stack = [...(uses.get(t) ?? [])];
+        while (stack.length) {
+            const f = stack.pop();
+            if (seen.has(f) || tops.includes(f))
+                continue;
+            seen.add(f);
+            stack.push(...(uses.get(f) ?? []));
+        }
+        for (const f of seen)
+            reach.set(f, (reach.get(f) ?? new Set()).add(t));
+    }
+    // Each nested file reached by exactly one top-level file goes into it.
+    const into = new Map();
+    for (const [f, owners] of reach)
+        if (owners.size === 1)
+            into.set(f, [...owners][0]);
+    if (!into.size)
+        return files;
+    const groups = new Map();
+    for (const [f, main] of into)
+        groups.set(main, [...(groups.get(main) ?? []), f]);
+    // Keep the order the models were planned in.
+    const order = [...files.keys()];
+    for (const list of groups.values())
+        list.sort((a, b) => order.indexOf(a) - order.indexOf(b));
+    const out = new Map(files);
+    const mergedStem = new Map(); // merged file stem → main file stem
+    for (const [main, nested] of groups) {
+        const head = splitHeader(out.get(main), lang);
+        const header = [...head.header];
+        const bodies = [head.body];
+        const nestedStems = new Set(nested.map(stem));
+        for (const f of nested) {
+            const part = splitHeader(out.get(f), lang);
+            for (const l of part.header)
+                if (!/^(package|part)\s/.test(l) && !header.includes(l))
+                    header.push(l);
+            bodies.push(part.body);
+            out.delete(f);
+            mergedStem.set(stem(f), stem(main));
+        }
+        const kept = header.filter((l) => /^part\s/.test(l) || !nestedStems.has(targetStem(importTarget(l) ?? '')) || !importTarget(l));
+        const pkg = kept.filter((l) => /^package\s/.test(l));
+        let imports = kept.filter((l) => /^(import|export|library)\s/.test(l));
+        if (lang === 'kt')
+            imports = [...new Set(imports)].sort();
+        const parts = kept.filter((l) => /^part\s/.test(l));
+        const top = [pkg, imports, parts].filter((g) => g.length).map((g) => g.join('\n')).join('\n\n');
+        out.set(main, `${top ? `${top}\n\n` : ''}${bodies.join('\n\n')}\n`);
+    }
+    // Other planned files: imports of a merged file point at its main file; a models index stops exporting it.
+    for (const [f, t] of out) {
+        const lines = t.split('\n');
+        let changed = false;
+        const seen = new Set();
+        const next = [];
+        for (const l of lines) {
+            const target = /^(import|export)\s/.test(l) ? importTarget(l) : undefined;
+            const s = target ? targetStem(target) : '';
+            if (target && mergedStem.has(s) && !/\.(g|freezed)\.dart$/.test(target)) {
+                changed = true;
+                if (/(^|\/)index\.ts$/.test(f) && /^export\s+\*/.test(l))
+                    continue;
+                const repl = l.replace(target, target.replace(new RegExp(`${s}(\\.(?:dart|ts|tsx|js))?$`), `${mergedStem.get(s)}$1`));
+                const key = repl.replace(/\s+/g, ' ');
+                if (lang === 'dart' && seen.has(key))
+                    continue;
+                seen.add(key);
+                next.push(repl);
+                continue;
+            }
+            if (target)
+                seen.add(l.replace(/\s+/g, ' '));
+            next.push(l);
+        }
+        if (!changed)
+            continue;
+        // A file that imported two merged files now imports the main file twice.
+        const once = new Set();
+        out.set(f, next.filter((l) => !/^import\s/.test(l) || (once.has(l.trim()) ? false : (once.add(l.trim()), true))).join('\n'));
+    }
+    return out;
+}
+/** groupNewModels for a whole plan: generated-code records follow their model into its new file. */
+export function groupPlanned(root, files, generated, map, lang, split = false) {
+    const out = groupNewModels(root, files, map, lang, split);
+    if (out === files)
+        return { files, generated };
+    const declares = (t, sym) => new RegExp(`\\b(?:interface|type|class|struct)\\s+${sym}\\b`).test(t);
+    return {
+        files: out,
+        generated: generated.map((g) => {
+            if (out.has(g.file) || exists(join(root, g.file)))
+                return g;
+            const home = [...out].find(([, t]) => declares(t, g.symbol))?.[0];
+            return home ? { ...g, file: home } : g;
+        }),
+    };
+}

package/dist/core/validateConfig.js

@@ -14,6 +14,7 @@ const FRAMEWORKS = ['nextjs', 'flutter', 'react-native', 'react', 'android', 'io
 /** Allowed values for keys that take one of a few words. Empty is always allowed (= detect). */
 export const ALLOWED = {
     nextjs: {
+        modelFiles: ['grouped', 'split'],
         apiFileNaming: ['kebab', 'camel', 'pascal', 'snake'],
         modelFileNaming: ['kebab', 'camel', 'pascal', 'snake'],
         apiFileResource: ['plural', 'singular'],
@@ -26,6 +27,7 @@ export const ALLOWED = {
         dataFetching: ['react-query', 'none'],
     },
     'react-native': {
+        modelFiles: ['grouped', 'split'],
         apiFileNaming: ['kebab', 'camel', 'pascal', 'snake'],
         modelFileNaming: ['kebab', 'camel', 'pascal', 'snake'],
         apiFileResource: ['plural', 'singular'],
@@ -40,6 +42,7 @@ export const ALLOWED = {
         router: ['react-navigation', 'expo-router', 'none'],
     },
     react: {
+        modelFiles: ['grouped', 'split'],
         apiFileNaming: ['kebab', 'camel', 'pascal', 'snake'],
         modelFileNaming: ['kebab', 'camel', 'pascal', 'snake'],
         apiFileResource: ['plural', 'singular'],
@@ -55,11 +58,13 @@ export const ALLOWED = {
         routerStyle: ['jsx', 'data'],
     },
     ios: {
+        modelFiles: ['grouped', 'split'],
         ui: ['swiftui', 'uikit'],
         fileSync: ['synchronized', 'groups'],
         indent: ['2', '4'],
     },
     android: {
+        modelFiles: ['grouped', 'split'],
         http: ['retrofit', 'ktor', 'none'],
         serialization: ['kotlinx', 'moshi', 'gson'],
         di: ['hilt', 'koin', 'manual', 'none'],
@@ -67,6 +72,7 @@ export const ALLOWED = {
         indent: ['2', '4'],
     },
     flutter: {
+        modelFiles: ['grouped', 'split'],
         http: ['dio', 'http'],
         serialization: ['manual', 'json_serializable', 'freezed'],
         freezedClass: ['abstract', 'plain'],

package/dist/skills/androidUi.js

@@ -23,6 +23,7 @@ import { camel, kebab, pascal, words } from "../input/naming.js";
 import { responseShape, titleField } from "./screen.js";
 import { prefillFor } from "./prefill.js";
 import { planViewsRoute, planViewsScreen } from "./androidViews.js";
+import { detectPaging, namedPagingArgs, PAGE_SIZE, pagingSummary, pagingWarnings } from "./paging.js";
 /** A Kotlin `fun name(...)`: its parameters and return type. */
 export function kotlinFun(text, name) {
     const m = new RegExp(`((?:^[ \\t]*(?:/\\*\\*(?:(?!\\*/)[^])*\\*/|//[^\\n]*|@\\w+(?:\\([^\\n]*\\))?)[ \\t]*\\n)*)[ \\t]*(?:suspend\\s+)?fun\\s+${name}\\s*\\(`, 'm').exec(text);
@@ -237,7 +238,6 @@ export function planAndroidScreen(root, map, opts) {
         if (x.read(f) !== null)
             throw new ToolError('route_exists', `${f} already exists.`);
     const pkg = packageOf(x.srcDir, screensDir);
-    const uiState = ensureUiState(x, screensDir);
     const T = a.returnType;
     const shape = responseShape(T, map);
     const model = shape.model;
@@ -248,6 +248,103 @@ export function planAndroidScreen(root, map, opts) {
         const v = p.name.replace(/`/g, '');
         return /^(Int|Long)$/.test(p.type) ? `${v}.to${p.type}()` : v;
     });
+    if (opts.paginate || opts.search) {
+        const paging = androidPaging(a, shape, opts, T);
+        const item = /^List<(.+)>\??$/.exec(T)?.[1] ?? 'Any';
+        const routeNamed = required.map((p, i) => `${p.name} = ${args[i]}`);
+        x.files.set(vmFile, pagedViewModel(x, a, n.vm, pkg, params, routeNamed, inj, item, paging, modelImports));
+        x.summary.push(`Create ${vmFile}: ${n.vm} with items, loading, error${paging.search || paging.clientSearch ? ', query' : ''}${paging.paginate ? ', hasMore' : ''}, calling ${a.iface}.${a.ep.name}()`);
+        const tf = titleField(model);
+        const searchable = Boolean(paging.search || paging.clientSearch);
+        const pg = paging.paginate;
+        const reset = pg ? 'reset = true' : '';
+        const stringFields = paging.searchFields.map((f) => (model?.fields.find((m) => m.name === f)?.nullable ? `${access('item', f)}.orEmpty()` : access('item', f)));
+        const screen = [
+            `package ${pkg}`,
+            '',
+            '@Composable',
+            `fun ${n.screen}(viewModel: ${n.vm} = ${inj.screenDefault}) {`,
+            '    val s by viewModel.state.collectAsState()',
+            ...(pg
+                ? [
+                    '    val listState = rememberLazyListState()',
+                    '    // Near the end of the list: ask for the next page.',
+                    '    val nearEnd by remember {',
+                    '        derivedStateOf {',
+                    '            val last = listState.layoutInfo.visibleItemsInfo.lastOrNull()?.index ?: 0',
+                    '            last >= listState.layoutInfo.totalItemsCount - 3',
+                    '        }',
+                    '    }',
+                    '    LaunchedEffect(nearEnd, s.items.size) {',
+                    '        if (nearEnd) viewModel.load()',
+                    '    }',
+                ]
+                : []),
+            `    val shown = ${paging.clientSearch ? `if (s.query.isBlank()) s.items else s.items.filter { item -> listOf(${stringFields.join(', ')}).any { it.contains(s.query.trim(), ignoreCase = true) } }` : 's.items'}`,
+            '    val error = s.error',
+            '    Scaffold { padding ->',
+            '        Column(Modifier.fillMaxSize().padding(padding)) {',
+            ...(searchable ? ['            OutlinedTextField(', '                value = s.query,', '                onValueChange = viewModel::search,', '                placeholder = { Text("Search") },', '                singleLine = true,', '                modifier = Modifier.fillMaxWidth().padding(12.dp),', '            )'] : []),
+            '            Box(Modifier.fillMaxSize()) {',
+            '                when {',
+            '                    s.items.isEmpty() && s.loading -> CircularProgressIndicator(Modifier.align(Alignment.Center))',
+            '                    s.items.isEmpty() && error != null -> Column(Modifier.align(Alignment.Center).padding(16.dp), horizontalAlignment = Alignment.CenterHorizontally) {',
+            '                        Text(error, color = MaterialTheme.colorScheme.error)',
+            `                        Button(onClick = { viewModel.load(${reset}) }) { Text("Retry") }`,
+            '                    }',
+            `                    shown.isEmpty() && !s.loading -> Text(${searchable ? 'if (s.query.isBlank()) "Nothing here yet." else "No matches."' : '"Nothing here yet."'}, Modifier.align(Alignment.Center))`,
+            `                    else -> LazyColumn(Modifier.fillMaxSize()${pg ? ', state = listState' : ''}) {`,
+            '                        items(shown) { item ->',
+            `                            Text(${tf ? `${access('item', tf)}.toString()` : 'item.toString()'}, Modifier.fillMaxWidth().padding(16.dp))`,
+            '                            HorizontalDivider()',
+            '                        }',
+            ...(pg
+                ? [
+                    '                        if (s.loading) {',
+                    '                            item { Box(Modifier.fillMaxWidth().padding(16.dp), contentAlignment = Alignment.Center) { CircularProgressIndicator() } }',
+                    '                        } else if (error != null) {',
+                    '                            item { TextButton(onClick = { viewModel.load() }, modifier = Modifier.fillMaxWidth()) { Text("Retry") } }',
+                    '                        }',
+                ]
+                : []),
+            '                    }',
+            '                }',
+            '            }',
+            '        }',
+            '    }',
+            '}',
+            '',
+        ].join('\n');
+        const composeImports = [
+            'androidx.compose.foundation.layout.Box',
+            'androidx.compose.foundation.layout.Column',
+            'androidx.compose.foundation.layout.fillMaxSize',
+            'androidx.compose.foundation.layout.fillMaxWidth',
+            'androidx.compose.foundation.layout.padding',
+            'androidx.compose.foundation.lazy.LazyColumn',
+            'androidx.compose.foundation.lazy.items',
+            'androidx.compose.material3.Button',
+            'androidx.compose.material3.CircularProgressIndicator',
+            'androidx.compose.material3.HorizontalDivider',
+            'androidx.compose.material3.MaterialTheme',
+            'androidx.compose.material3.Scaffold',
+            'androidx.compose.material3.Text',
+            'androidx.compose.runtime.Composable',
+            'androidx.compose.runtime.collectAsState',
+            'androidx.compose.runtime.getValue',
+            'androidx.compose.ui.Alignment',
+            'androidx.compose.ui.Modifier',
+            'androidx.compose.ui.unit.dp',
+            ...(searchable ? ['androidx.compose.material3.OutlinedTextField'] : []),
+            ...(pg ? ['androidx.compose.foundation.lazy.rememberLazyListState', 'androidx.compose.material3.TextButton', 'androidx.compose.runtime.LaunchedEffect', 'androidx.compose.runtime.derivedStateOf', 'androidx.compose.runtime.remember'] : []),
+        ];
+        x.files.set(screenFile, addKotlinImports(screen, [...composeImports, ...inj.screenImports], pkg));
+        x.summary.push(`Create ${screenFile}: ${n.screen} lists them and ${pagingSummary(paging)}`);
+        x.warnings.push(...pagingWarnings(paging));
+        registerRoute(x, route, `${n.screen}()`, `${pkg}.${n.screen}`, params, false);
+        return finish(x, 'screen add', navHint(route, params));
+    }
+    const uiState = ensureUiState(x, screensDir);
     // ViewModel.
     x.files.set(vmFile, dataViewModel(x, a, n.vm, pkg, params, args, inj, uiState, T, modelImports));
     x.summary.push(`Create ${vmFile}: ${n.vm} loads ${a.iface}.${a.ep.name}()${params.length ? ` with ${params.join(', ')} from the route` : ''}`);
@@ -455,6 +552,75 @@ function planAndroidForm(x, opts, a) {
     registerRoute(x, route, `${n.screen}()`, `${pkg}.${n.screen}`, params, false);
     return finish(x, 'screen add', navHint(route, params));
 }
+/** Paging for a Kotlin list endpoint. */
+export function androidPaging(a, shape, opts, T) {
+    if (!shape.list)
+        throw new ToolError('screen_not_list', `${a.ep.name}() returns ${T}, not a list; --paginate and --search are for list screens.`);
+    return detectPaging(a.params.filter((p) => p.annotation !== 'Body').map((p) => ({ name: p.name.replace(/`/g, ''), type: p.type })), { paginate: opts.paginate, search: opts.search, modelStringFields: (shape.model?.fields ?? []).filter((f) => f.type === 'String').map((f) => f.name), titleField: titleField(shape.model) });
+}
+/** The ViewModel of a paged or searchable list (Compose and Views share it): one state, and load() / search(). A new search or refresh cancels the request still running. */
+export function pagedViewModel(x, a, vmName, pkg, params, routeNamed, inj, item, p, modelImports) {
+    const stateName = `${vmName.replace(/ViewModel$/, '')}ListState`;
+    const searchable = Boolean(p.search || p.clientSearch);
+    const pg = p.paginate;
+    const first = p.page?.mode === 'offset' ? '0' : '1';
+    const call = [...routeNamed, ...namedPagingArgs(p, { page: pg ? 'next' : undefined, search: p.search ? '_state.value.query.trim().ifBlank { null }' : undefined }, ' = ', 'PAGE_SIZE')].join(', ');
+    const vm = [
+        `package ${pkg}`,
+        '',
+        ...(pg && p.size ? [`private const val PAGE_SIZE = ${PAGE_SIZE}`, ''] : []),
+        `data class ${stateName}(`,
+        `    val items: List<${item}> = emptyList(),`,
+        '    val loading: Boolean = false,',
+        '    val error: String? = null,',
+        ...(pg ? ['    val hasMore: Boolean = true,'] : []),
+        ...(searchable ? ['    val query: String = "",'] : []),
+        ')',
+        '',
+        ...inj.header,
+        ...params.map((x) => `    private val ${x}: String = checkNotNull(savedStateHandle["${x}"])`),
+        ...(params.length ? [''] : []),
+        `    private val _state = MutableStateFlow(${stateName}())`,
+        `    val state: StateFlow<${stateName}> = _state.asStateFlow()`,
+        ...(pg && p.page.mode === 'page' ? ['    private var page = 0'] : []),
+        '    private var job: Job? = null',
+        ...(p.search ? ['    private var searchJob: Job? = null'] : []),
+        '',
+        '    init {',
+        `        load(${pg ? 'reset = true' : ''})`,
+        '    }',
+        '',
+        `    /** Loads ${pg ? 'the first page again (reset) or the next one' : 'the list'}. */`,
+        `    fun load(${pg ? 'reset: Boolean = false' : ''}) {`,
+        ...(pg ? ['        val now = _state.value', '        if (!reset && (now.loading || !now.hasMore)) return'] : []),
+        '        job?.cancel()',
+        '        job = viewModelScope.launch {',
+        '            _state.update { it.copy(loading = true, error = null) }',
+        '            try {',
+        ...(pg ? [`                val next = if (reset) ${first} else ${p.page.mode === 'offset' ? '_state.value.items.size' : 'page + 1'}`] : []),
+        `                val rows = api.${a.ep.name}(${call})`,
+        ...(pg && p.page.mode === 'page' ? ['                page = next'] : []),
+        pg
+            ? `                _state.update { it.copy(items = if (reset) rows else it.items + rows, hasMore = ${p.size ? 'rows.size == PAGE_SIZE' : 'rows.isNotEmpty()'}, loading = false) }`
+            : '                _state.update { it.copy(items = rows, loading = false) }',
+        '            } catch (e: CancellationException) {',
+        '                throw e',
+        '            } catch (e: Exception) {',
+        '                _state.update { it.copy(loading = false, error = e.message ?: "Something went wrong") }',
+        '            }',
+        '        }',
+        '    }',
+        ...(p.search
+            ? ['', '    /** Searches after a short pause in typing. */', '    fun search(text: String) {', '        _state.update { it.copy(query = text) }', '        searchJob?.cancel()', '        searchJob = viewModelScope.launch {', '            delay(400)', `            load(${pg ? 'reset = true' : ''})`, '        }', '    }']
+            : p.clientSearch
+                ? ['', '    fun search(text: String) {', '        _state.update { it.copy(query = text) }', '    }']
+                : []),
+        ...inj.companion,
+        '}',
+        '',
+    ].join('\n');
+    return addKotlinImports(vm, ['androidx.lifecycle.ViewModel', 'androidx.lifecycle.viewModelScope', 'kotlinx.coroutines.CancellationException', 'kotlinx.coroutines.Job', 'kotlinx.coroutines.flow.MutableStateFlow', 'kotlinx.coroutines.flow.StateFlow', 'kotlinx.coroutines.flow.asStateFlow', 'kotlinx.coroutines.flow.update', 'kotlinx.coroutines.launch', ...(p.search ? ['kotlinx.coroutines.delay'] : []), a.ifaceClass, ...modelImports, ...inj.imports], pkg);
+}
 /** The ViewModel of a data screen (Compose and Views share it): loads the endpoint into StateFlow<UiState<T>>. */
 export function dataViewModel(x, a, vmName, pkg, params, args, inj, uiState, T, modelImports) {
     const vm = [