codz-cli 0.1.2 → 0.1.8

package/README.md

@@ -105,7 +105,7 @@ cd shop_app && codz init                     # then api add, screen add, ... as
 - **Data only.** A starter is files plus a manifest. It never runs its own scripts; codz runs only `flutter create`, `flutter pub get`, `dart format` and `npm install --ignore-scripts`, with arguments it builds itself from typed answers.
 - **Strict reading.** The archive reader accepts regular files and folders only. Links, devices, `..`, absolute paths, Windows reserved names, case or Unicode clashes, and oversized or bomb archives stop it before anything is written.
 - **One step, and undoable.** The preview lists every file and step. The project is built in a temporary folder and moved into place in one rename. `codz undo` inside the new project removes it again while you have not changed it; files from `pub get`, `npm install` and `codz init` do not count as changes.
-- **Plans and agents.** `--plan` (or `--json` without `--yes`) saves a plan, and `codz apply <id>` creates exactly that. From MCP, `new` only plans, `login` is not a tool, and a paid starter has to be downloaded once by a person first.
+- **Plans and agents.** `--plan` (or `--json` without `--yes`) saves a plan, and `codz apply <id>` creates exactly that. When an AI agent runs codz (`CODZ_MCP=1`), a paid starter has to be downloaded once by a person first.
 - **Offline.** `--cached` uses only what is already downloaded. In CI, set `CODZ_TOKEN` instead of logging in.
 
 The catalog is served by the separate codz store project (accounts, purchases, `codz login`); until a release points at it, `new` works with template folders or `CODZ_REGISTRY`. Starter sources live in `starters/`, and `scripts/starters.ts` checks, packs and signs them (see starters/README.md).
@@ -200,6 +200,42 @@ codz api remove deleteUser                       # remove it; lists callers that
 
 `api rename` and `api remove` find uses with your project's own TypeScript compiler when `typescript` is installed in it (it is in almost every Next.js project), so a local variable or parameter that happens to share the name, an object key, or another file's own function with that name is never touched. Without it, codz falls back to its text scanner (`CODZ_NO_AST=1` forces the fallback).
 
+### A model from JSON: codz model
+
+```bash
+codz model Order --from-clipboard              # copy a response or object, then run this
+codz model Order --sample order.json
+curl -s https://api.example.com/orders/1 | codz model Order
+```
+
+Writes the model and a class for each nested object (`Order`, `Customer`, `OrderItem`), in the project's own style, with no endpoint. They all go in one file, the main model's (`order.dart`, `Order.kt`, `order.ts`), so a long response does not scatter a dozen files; `--split` gives each class its own file. A nested model the project already has is reused, not copied. A list gives the model of its items, `{"data": ...}` is unwrapped (`--no-unwrap` keeps it), and pasted text around the JSON (a `response:` label, code fences) is ignored. An existing model is never overwritten unless you pass `--force`; to add one field, use `codz field add`.
+
+### One file per model
+
+`model`, `api add`, `api import`, `api sync` and `feature add` put nested models in the file of the model that uses them: an order response gives `order.dart` (or `Order.kt`, `order.ts`, `Order.swift`) holding `Order`, `Customer` and `OrderItem`, not three files. A nested model that several top-level models use (an `Address` used by both `Order` and `User` in a spec) keeps its own file, and models the project already has stay where they are. For one file per model, pass `--split`, or set it for good with `codz config set modelFiles split`.
+
+### Choosing the model folder: --model-dir
+
+New models go into the project's models folder (`modelsFolder` in `codz.config.yaml`, which `codz init` detects). For a feature-first project where each feature keeps its own models, choose the folder for one command:
+
+```bash
+codz model Order --from-clipboard --model-dir lib/features/orders/models
+codz api add --url https://api.example.com/v1/carts/1 --sample cart.json --model-dir lib/features/cart/models
+codz feature add orders --spec api.yaml --model-dir src/features/orders/types
+```
+
+`--model-dir` works with `model`, `api add`, `api import`, `api sync` and `feature add`, and lasts for that one command. Imports point at the new folder, and Kotlin models get the matching `package` line. Existing models keep their place, so a nested model that already exists elsewhere is reused, not copied. To change the folder for good: `codz config set modelsFolder lib/features/orders/models`.
+
+### One field at a time: field add
+
+```bash
+codz field add Product rating:double? tags:string[]   # the backend added two fields
+codz field add Order created_at:date category:Category
+codz field remove Product legacy_code                  # and lists the lines that still use it
+```
+
+The name is the JSON key; codz writes the property name your models use (`created_at` becomes `createdAt` in Dart, Kotlin and Swift). Types: `string`, `int`, `double`, `bool`, `date`, `any`, a model in the project, or a list (`string[]`, `list<Category>`); end with `?` for an optional field. Only the field's own lines change, in every place the model spells it: the TypeScript interface; the Dart constructor, `fromJson`, field and `toJson` (or the freezed factory, with `@JsonKey` for snake_case keys); the Kotlin data class parameter with your serializer's annotation; the Swift property and its `CodingKeys` case. Everything else in the file, including code you wrote, stays as it is. Then it lists the files that use the model, so you can show the field where it belongs, and `codz mock serve` fills it with sample data straight away.
+
 ### Other stacks
 
 codz writes in the style the project already uses:
@@ -233,6 +269,68 @@ codz api diff old.yaml new.yaml --fail-on warning                    # exit 1 on
 
 Breaking: an operation removed, a response field removed or retyped, a new path parameter, a new required request field. Warning: a response field that can now be null, a removed query parameter, a retyped request field. Added operations, response fields and optional request fields are listed as additions. Inside a project each change names the endpoint function and the files and lines that use it (its callers, the screens, the model); outside a project it compares the two files only. Nothing is written except the `--report` file.
 
+### Typed asset names: codz assets
+
+```bash
+codz assets      # run again after adding or removing files
+```
+
+| Project | What it writes | Use |
+| --- | --- | --- |
+| Flutter | `lib/gen/assets.dart` with a class per folder under `assets/` (`AppImages`, `AppIcons`, `AppFonts`), and every asset folder and font family in `pubspec.yaml` | `Image.asset(AppImages.logo)` |
+| React Native | `src/assets/index.ts` with a `require()` for each file | `<Image source={images.logo} />` |
+| Next.js, Vite | `lib/assets.ts` / `src/assets.ts`: paths for `public/`, imports for Vite's `src/assets` | `<img src={publicFiles.logo} />` |
+| Android, iOS | Nothing: `R.drawable.logo` and `Image(.logo)` are already typed. codz checks resource names that would break the build | |
+
+A typo in an asset path becomes a compile error instead of a blank image. Flutter resolution folders (`2.0x/`) are left to Flutter, font weights and italics come from the file names (`Inter-BoldItalic.ttf`), and assets that no code uses are listed so you can delete them.
+
+### API environments: env add
+
+```bash
+codz env add staging --base-url https://staging.example.com
+codz env add qa --base-url https://qa.example.com
+codz env list                      # every environment and its base URL
+codz env use staging               # React Native CLI, Android, iOS: switch in the code
+```
+
+The base URL you have now becomes `default`. Each platform gets its usual mechanism:
+
+| Project | What env add writes | Run against staging |
+| --- | --- | --- |
+| Next.js | `.env.staging` with `NEXT_PUBLIC_API_URL`, `dev:staging` / `build:staging` scripts (with dotenv-cli) | `npm run dev:staging` |
+| React (Vite) | `.env.staging` with `VITE_API_URL`, scripts with `--mode staging` | `npm run dev:staging` |
+| Expo | `.env.staging` with `EXPO_PUBLIC_API_URL`, a `start:staging` script | `npm run start:staging` |
+| React Native CLI | An `API_URLS` table in `src/config/env.ts`; `APP_ENV` picks one | `codz env use staging` |
+| Flutter | `env/staging.json`; Dio reads `String.fromEnvironment('API_BASE_URL')`; a VS Code run configuration | `flutter run --dart-define-from-file=env/staging.json` |
+| Android | An `apiUrls` table in `app/build.gradle(.kts)` into `BuildConfig.BASE_URL` (build variants stay the same) | `./gradlew installDebug -PapiEnv=staging`, or `codz env use staging` |
+| iOS | `AppEnvironment.swift`, an enum the API client reads | `APP_ENV=staging` in the scheme, or `codz env use staging` |
+
+`development`, `production` and `test` need no script in Next.js (and `development`, `production` in Vite): the framework reads those files by itself. codz never writes `.env.local`. Base URLs are not secrets, so these files are meant to be committed; keep keys and tokens out of them.
+
+### Mock API server
+
+```bash
+codz mock serve                      # the project's endpoints, on http://localhost:4010
+codz mock serve --spec api.yaml      # every operation in an OpenAPI, Swagger, Postman or HAR file
+codz mock serve --lan --port 8080    # reachable from a phone on the same Wi-Fi
+codz mock serve --scenario empty     # start with empty lists (or error, unauthorized, slow, offline)
+```
+
+A local fake API, so new screens show data before the backend exists. Every endpoint answers with sample data built from its response model (5 rows per list, each a little different; `--items`, and a 300 ms delay so loading states show; `--delay 0` to skip it). A list and its items share in-memory data: a create form adds a row the list then shows, edit forms change it and delete removes it, and restarting resets everything. Paths match by their last segments, so `/v1/products` reaches `GET /products`; anything unknown gets a 404 that lists the routes. It sends CORS headers for web apps, and prints how to point your app at it (environment variable for Next.js and Vite, emulator and simulator addresses for mobile). It listens on this computer only unless you pass `--lan`, and it never makes requests of its own.
+
+**Every screen state, without touching the backend.** Open `http://localhost:4010/__codz` while the app runs:
+
+| Scenario | What the app gets | Checks |
+| --- | --- | --- |
+| `normal` | sample data | the happy path |
+| `empty` | empty lists; their items 404 | empty states |
+| `error` | 500 for every request | error messages and retry buttons |
+| `unauthorized` | 401 for every request | sign-out and token refresh |
+| `slow` | answers after 3 seconds | loading spinners, double taps |
+| `offline` | the connection drops | no-network handling |
+
+Switch for every endpoint, or set one endpoint differently (only `GET /v1/products` empty, say). The same page lists the last requests with their request and response bodies, and **Reset** brings back the starting data. Scripts and tests can switch too: `curl -X POST localhost:4010/__codz/scenario -d '{"scenario":"error","route":"GET /v1/products"}'`, `GET /__codz/state`, `POST /__codz/reset`.
+
 ### Mock responses
 
 ```bash
@@ -254,6 +352,26 @@ codz locale key cart.empty "Your cart is empty" --value hi="आपकी का
 
 Works with JSON message files (next-intl, i18next; `cart.empty` becomes a nested key), Flutter ARB files (keys become identifiers like `cartEmpty`, `{name}` placeholders get metadata) and GetX `Translations`. A GetX project without translations gets `lib/app/translations/app_translations.dart`, wired into `GetMaterialApp` with `translations:`, `locale:` and `fallbackLocale:`. Languages without a `--value` get the default text and are listed by `codz doctor` as untranslated. Only the changed keys are touched; the rest of each file keeps its formatting.
 
+
+#### Moving screen text into the locale files: locale extract
+
+```bash
+codz locale extract                                   # every screen
+codz locale extract lib/features/cart/cart_page.dart  # one file
+```
+
+Finds the text users see and replaces it with the project's lookup, in one previewed change:
+
+| Project | Before | After |
+| --- | --- | --- |
+| Flutter (ARB) | `Text('Nothing here yet')` | `Text(AppLocalizations.of(context)!.productsNothingHereYet)` |
+| Flutter (GetX) | `Text('Nothing here yet')` | `Text('products.nothingHereYet'.tr)` |
+| next-intl | `<p>Nothing here yet</p>` | `<p>{t('products.nothingHereYet')}</p>` with `useTranslations()` or `await getTranslations()` |
+| react-i18next | `placeholder="Search"` | `placeholder={t('products.search')}` with `useTranslation()` |
+| Compose | `Text("Nothing here yet")` | `Text(stringResource(R.string.products_nothing_here_yet))` and `strings.xml` |
+
+It looks at `Text(...)` and hint, label and tooltip text in Flutter, JSX text and `placeholder`, `title`, `alt`, `aria-label` in React, and `Text("...")` in Compose. Values in the text become placeholders (`'Hello $name'` → `greetingHello(name)`, `trParams`, or `%1$s`). Keys are named after the screen; text used on several screens goes under `common`, and text that already has a key reuses it. Text in conditions or built in code is left alone. In Flutter it removes `const` where the text is no longer constant, and the first time it wires `AppLocalizations` into `MaterialApp` (with `l10n.yaml` and `flutter_localizations`). SwiftUI needs none of this: Xcode collects `Text("...")` into a String Catalog by itself.
+
 ### Theme
 
 ```bash
@@ -298,6 +416,26 @@ One change with the route, the page, the call to the endpoint, and the loading,
 - React Native: a screen that loads the endpoint (through its TanStack Query hook when there is one) with `ActivityIndicator`, the error with Retry, and a `FlatList` or the fields; registered in the navigator, or a file under `app/` with Expo Router.
 - Android: a Compose screen and a ViewModel next to it. The ViewModel gets the Retrofit interface from Hilt (`@HiltViewModel`, `hiltViewModel()`), Koin (`viewModelOf(::X)` added to the module, `koinViewModel()`) or the service locator (a `ViewModelProvider.Factory`), reads route parameters from `SavedStateHandle` (converted to `Int` when the method wants one), and exposes `StateFlow<UiState<T>>` (`UiState.kt` with Loading, Success and Error is written once). The screen shows a spinner, the error with Retry, then a `LazyColumn` or the model's fields, and gets a `composable("orders/{id}")` entry in your `NavHost`.
 
+#### Long lists: --paginate and --search
+
+```bash
+codz screen add products --api listProducts --paginate --search
+codz screen add orders --api listOrders --search
+```
+
+`--paginate` loads 20 items at a time and the next page as you reach the end of the list. It needs the endpoint to take a page number (`page`) or an offset (`offset`, `skip`); with a page-size parameter (`limit`, `pageSize`, `per_page`) codz sends 20 and stops at a short page, otherwise it stops at an empty one. `--search` adds a search box: when the endpoint has a search parameter (`q`, `query`, `search`, `term`), the screen asks the server after a short pause in typing and starts again from the first page; otherwise it filters the items already loaded by their text fields, and says so. A new search or refresh replaces a request still loading, so an older answer never overwrites a newer one. Each screen keeps the project's own way of doing things:
+
+| Project | Paged list |
+| --- | --- |
+| Next.js | Server page: `?page=2&q=lamp` in the URL, a search form, Previous / Next links |
+| React | `useState` / `useEffect`, or `useInfiniteQuery` with TanStack Query 5; a Load more button |
+| React Native | `FlatList` with `onEndReached` and pull to refresh; `useInfiniteQuery` with TanStack Query |
+| Flutter (Riverpod, get_it) | A `StatefulWidget` that loads the next page when the end of the list is on screen |
+| Flutter (Bloc) | A Cubit with one state (items, loading, error, query, hasMore) and a `BlocBuilder` page |
+| Flutter (GetX) | The module's controller (`items`, `isLoading`, `load()`, `search()`) and an `Obx` view |
+| Android | A ViewModel with one `StateFlow` state; a `LazyColumn` (Compose) or `RecyclerView` (Views) that loads more near the end |
+| iOS | An `ObservableObject` view model; `List` with `.searchable` and a progress row that loads the next page |
+
 Only GET endpoints make a data screen. For POST, PUT and PATCH endpoints, `--form` makes a form instead:
 
 ```bash
@@ -454,20 +592,6 @@ codz api add --curl "..." --plan --json      # get the diff and a plan id
 codz apply <plan-id> --json                  # apply exactly what was shown
 ```
 
-### MCP server
-
-```bash
-codz mcp                 # in the project folder (or: codz mcp --cwd /path/to/project)
-```
-
-`codz mcp` serves codz over the Model Context Protocol on stdio, for AI agents and editors that support MCP. Every command becomes a tool (`api add` → `api_add`, `api sync` → `api_sync`, `doctor`, ...), with a JSON schema built from its options. Tools that edit code never write: they return the diff and a `planId`, and the `apply` tool applies that plan exactly as shown. Two resources: `codz://project` (what codz knows about the project) and `codz://commands` (every command and option).
-
-To add it to an MCP client, register a stdio server whose command is `codz` with the arguments `["mcp", "--cwd", "/path/to/project"]`. Many clients take a JSON entry like:
-
-```json
-{ "mcpServers": { "codz": { "command": "codz", "args": ["mcp", "--cwd", "/path/to/project"] } } }
-```
-
 ### VS Code extension
 
 `extensions/vscode` runs codz from the command palette: add an endpoint from a cURL command or URL, sync with a spec, show an endpoint and jump to its uses, rename, mock and test every endpoint, doctor findings in the Problems panel, undo. Every change opens as a diff first and is applied only when you click Apply. Package it with `npx @vscode/vsce package` in that folder and install the `.vsix`; see its README.
@@ -503,8 +627,7 @@ bin/codz.js         entry point
 src/cli.ts             commands and flags
 src/core/              types, cache, config and YAML reader, JSON editing, diff, change sets, git
 src/input/             cURL, paste, OpenAPI/Swagger/Postman parsing, naming, model inference
-src/core/commands.ts   the command and option table (help, completion, parser, docs, MCP tools)
-src/skills/mcp.ts      codz mcp: the Model Context Protocol server
+src/core/commands.ts   the command and option table (help, completion, parser, docs)
 src/starters/          codz new and the starter catalog (the only network code; loaded on demand)
 starters/              the internal starter templates; scripts/starters.ts publishes them
 extensions/vscode/     the VS Code extension

package/dist/adapters/common.js

@@ -65,7 +65,9 @@ export function scanLocales(root, files) {
         const d = l.file.split('/').slice(0, -1).join('/');
         byDir.set(d, [...(byDir.get(d) ?? []), l]);
     }
-    const [, chosen] = [...byDir.entries()].sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]))[0];
+    // Ties go to the shallower folder (lib/l10n over example/lib/l10n).
+    const depth = (d) => (d ? d.split('/').length : 0);
+    const [, chosen] = [...byDir.entries()].sort((a, b) => b[1].length - a[1].length || depth(a[0]) - depth(b[0]) || a[0].localeCompare(b[0]))[0];
     const languages = chosen.map((l) => l.lang).sort();
     let keyCount = 0;
     for (const l of chosen)

package/dist/adapters/flutterScan.js

@@ -135,7 +135,7 @@ export async function scan(root, configConventions) {
         const dirs = new Set(modelFiles.map(relDir));
         const inBest = modelFiles.filter((f) => relDir(f) === c.modelsFolder).length;
         if (dirs.size >= 3 && inBest * 2 < modelFiles.length) {
-            map.notes.push(`Models live in ${dirs.size} different folders, so new ones go to lib/models. Use --into <folder> or set modelsFolder in codz.config.yaml to choose.`);
+            map.notes.push(`Models live in ${dirs.size} different folders, so new ones go to lib/models. Use --model-dir <folder> or set modelsFolder in codz.config.yaml to choose.`);
             c.modelsFolder = 'lib/models';
         }
     }

package/dist/cli.js

@@ -1,11 +1,13 @@
 // codz command line. Every command supports --json for scripts and AI agents.
 import { baseUrlProblem } from "./core/safe.js";
-import { existsSync, openSync, writeFileSync } from 'node:fs';
+import { existsSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { ReadStream } from 'node:tty';
 import { dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { adapterFor } from "./adapters/index.js";
-import { loadMap, setCacheWrites } from "./core/cache.js";
+import { loadMap, setCacheWrites, setRunConventions } from "./core/cache.js";
+import { readText } from "./core/fsutil.js";
 import { applyChangeSet, changeSetJson, historyShow, loadPlan, readHistory, renderDiff, savePlan, undoLast, undoTo } from "./core/changeset.js";
 import { changeSummaryLine, commitChange, openDiffInEditor, readClipboard } from "./core/workflow.js";
 import { CONFIG_FILE, loadConfig } from "./core/config.js";
@@ -19,9 +21,13 @@ import { listApiImport, planApiImport } from "./skills/apiImport.js";
 import { planApiSync } from "./skills/apiSync.js";
 import { planTestAdd } from "./skills/testgen.js";
 import { listTemplates, planTemplatesInit } from "./skills/templatesCmd.js";
-import { serveMcp } from "./skills/mcp.js";
 import { createProject, describeCreate, PROJECT_TYPES, projectType } from "./skills/create.js";
 import { planApiRemove, planApiRename, planApiUpdate } from "./skills/apiEdit.js";
+import { planFieldAdd, planFieldRemove } from "./skills/field.js";
+import { normalizeModelDir, parseJsonText, planModel } from "./skills/model.js";
+import { listEnvs, planEnvAdd, planEnvUse } from "./skills/env.js";
+import { planLocaleExtract } from "./skills/localeExtract.js";
+import { planAssets } from "./skills/assets.js";
 import { planMockAdd } from "./skills/mock.js";
 import { planLocaleAdd, planLocaleKey } from "./skills/locale.js";
 import { planThemeSet } from "./skills/theme.js";
@@ -38,12 +44,13 @@ import { apiList, apiShow } from "./skills/apiList.js";
 import { cleanPlans, listPlans, showPlan } from "./skills/plans.js";
 import { complete, completionScript, SHELLS } from "./skills/completion.js";
 import { genericAdapter } from "./adapters/generic.js";
-import { allowedFlags, BOOLEAN_FLAGS, findCommand, FLAGS, renderCommandHelp, renderHelp, REPEATABLE_FLAGS } from "./core/commands.js";
+import { allowedFlags, BOOLEAN_FLAGS, CHANGE_FLAGS, COMMAND_LIST, findCommand, FLAGS, GLOBAL_FLAGS, renderCommandHelp, renderHelp, renderMarkdown, REPEATABLE_FLAGS } from "./core/commands.js";
 import { closest } from "./core/validateConfig.js";
 import { recordEvent } from "./core/events.js";
 import { buildReport, renderReport } from "./skills/report.js";
 import { homedir } from 'node:os';
 import { runTool } from "./core/proc.js";
+import { connectHints, MockServer, mockApiFromProject, mockApiFromSpec, SCENARIOS } from "./skills/mockServer.js";
 /** Operating-system errors that are not codz bugs, with what to do about them. */
 const SYSTEM_ERRORS = {
     ENOSPC: { code: 'disk_full', say: 'The disk is full, so codz could not write its files.', hint: 'Free some disk space and run the command again.' },
@@ -52,7 +59,15 @@ const SYSTEM_ERRORS = {
     EROFS: { code: 'read_only', say: 'This folder is on a read-only disk.', hint: 'Run codz in a writable copy of the project.' },
     EMFILE: { code: 'too_many_files', say: 'Too many files are open at once.', hint: 'Close other programs or raise the limit (ulimit -n 4096), then run the command again.' },
 };
-export const VERSION = '0.1.0';
+/** From package.json (one folder up from src/ and dist/), so --version matches what npm installed. */
+export const VERSION = (() => {
+    try {
+        return JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 export function parseArgs(argv) {
     const args = { positional: [], flags: {}, multi: {} };
     for (let i = 0; i < argv.length; i++) {
@@ -467,7 +482,7 @@ export async function main(argv) {
     const started = Date.now();
     const event = (ok, code) => {
         const [cmd, sub] = args.positional;
-        if (!cmd || ['report', 'completion', 'help', 'mcp'].includes(cmd) || args.flags.help || args.flags.version)
+        if (!cmd || ['report', 'completion', 'help'].includes(cmd) || args.flags.help || args.flags.version)
             return;
         const spec = findCommand(cmd, sub);
         const name = spec ? (spec.sub ? `${spec.cmd} ${spec.sub}` : spec.cmd) : 'unknown';
@@ -540,6 +555,18 @@ async function run(args, out) {
             return 0;
         }
     }
+    // The command table as data, for editors, completion and add-ons that call codz.
+    const optionsOf = (names) => names.map((name) => ({ name, ...FLAGS[name] }));
+    if (cmd === 'help' && flags.json) {
+        process.stdout.write(JSON.stringify({
+            version: VERSION,
+            commands: COMMAND_LIST.map((c) => ({ ...c, options: optionsOf(c.flags) })),
+            changeFlags: CHANGE_FLAGS,
+            globalFlags: GLOBAL_FLAGS,
+            markdown: renderMarkdown(VERSION),
+        }, null, 2) + '\n');
+        return 0;
+    }
     if (!cmd || flags.help || flags.h || cmd === 'help') {
         out.print(HELP);
         return cmd || flags.help || flags.h ? 0 : 1;
@@ -632,8 +659,6 @@ async function run(args, out) {
         process.stdout.write(completionScript(sub));
         return 0;
     }
-    if (cmd === 'mcp')
-        return serveMcp(root, VERSION);
     if (cmd === 'doctor' && flags.setup === true) {
         let a = genericAdapter;
         try {
@@ -692,7 +717,69 @@ async function run(args, out) {
         out.result({ ...report, failed: diffFails(report, failOn) });
         return diffFails(report, failOn) ? 1 : 0;
     }
+    // mock serve: a local fake API; with --spec it works anywhere, without a project.
+    if (cmd === 'mock' && sub === 'serve') {
+        const num = (k, def) => {
+            const v = flags[k];
+            if (v === undefined)
+                return def;
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 0)
+                throw new ToolError('bad_args', `--${k} must be a whole number, got "${v}".`);
+            return n;
+        };
+        const port = num('port', 4010);
+        let api;
+        let framework = null;
+        let map = null;
+        const hasProject = existsSync(join(root, CONFIG_FILE));
+        if (hasProject) {
+            try {
+                const a = adapterFor(root).adapter;
+                framework = a.id;
+                map = (await loadMap(root, a, loadConfig(root).conventions)).map;
+            }
+            catch {
+                framework = null;
+            }
+        }
+        if (typeof flags.spec === 'string')
+            api = mockApiFromSpec(resolve(flags.spec));
+        else if (map && framework)
+            api = mockApiFromProject(root, map, framework === 'flutter' ? 'dart' : framework === 'android' ? 'kt' : framework === 'ios' ? 'swift' : 'ts');
+        else
+            throw new ToolError('bad_args', 'No codz project here, so there are no endpoints to mock.', 'Serve an API file instead: codz mock serve --spec api.yaml (or run codz init in your app first).');
+        const lan = flags.lan === true;
+        const scenario = (typeof flags.scenario === 'string' ? flags.scenario : 'normal');
+        if (!SCENARIOS.includes(scenario))
+            throw new ToolError('bad_args', `Unknown scenario "${scenario}".`, `Choose: ${SCENARIOS.join(', ')}.`);
+        const server = new MockServer(api, { scenario, port, host: lan ? '0.0.0.0' : '127.0.0.1', delay: num('delay', 300), items: num('items', 5), log: (line) => out.print(`  ${line}`) });
+        const actual = await server.start();
+        out.print(`Mock API on http://localhost:${actual}, from ${api.source}:`);
+        for (const r of api.routes.slice(0, 40))
+            out.print(`  ${r.method.padEnd(6)} ${r.path}`);
+        if (api.routes.length > 40)
+            out.print(`  … and ${api.routes.length - 40} more`);
+        out.print('');
+        for (const h of connectHints(map, framework, actual, lan))
+            out.print(h);
+        out.print(`Switch scenarios (empty, error, unauthorized, slow, offline) and watch requests: http://localhost:${actual}/__codz`);
+        if (scenario !== 'normal')
+            out.print(`Starting in scenario: ${scenario}.`);
+        out.print('Lists, create, edit and delete share in-memory data (reset it on that page). Press Ctrl+C to stop.');
+        out.print('');
+        await new Promise((done) => {
+            process.once('SIGINT', () => done());
+            process.once('SIGTERM', () => done());
+        });
+        await server.stop();
+        return 0;
+    }
     const { adapter } = adapterFor(root);
+    if (typeof flags['model-dir'] === 'string') {
+        const dir = normalizeModelDir(flags['model-dir'], adapter.id);
+        setRunConventions({ modelsFolder: dir, ...(adapter.id === 'nextjs' || adapter.id === 'react' || adapter.id === 'react-native' ? { modelsLayout: 'per-file' } : {}) });
+    }
     switch (cmd) {
         case 'report': {
             const { map } = await loadMap(root, adapter, loadConfig(root).conventions);
@@ -710,9 +797,66 @@ async function run(args, out) {
             out.result({ map, supportedSetup: adapter.supportedSetup });
             return 0;
         }
+        case 'assets':
+            return handleChange(root, out, flags, await planAssets(root, adapter), adapter);
+        case 'env': {
+            if (sub === 'list') {
+                const envs = await listEnvs(root, adapter);
+                if (!envs.length)
+                    out.print('No API environments yet. Add one with: codz env add staging --base-url https://staging.example.com');
+                for (const e of envs)
+                    out.print(`  ${e.name.padEnd(12)} ${e.baseUrl}   (${e.where})`);
+                out.result({ environments: envs });
+                return 0;
+            }
+            if (sub === 'add')
+                return handleChange(root, out, flags, await planEnvAdd(root, adapter, positional[2], typeof flags['base-url'] === 'string' ? flags['base-url'] : undefined, { force: flags.force === true }), adapter);
+            if (sub === 'use') {
+                if (!positional[2])
+                    throw new ToolError('bad_args', 'Which environment? codz env use <name>');
+                return handleChange(root, out, flags, await planEnvUse(root, adapter, positional[2]), adapter);
+            }
+            throw new ToolError('bad_args', `Unknown command "env ${sub ?? ''}".`, 'Commands: env add <name> --base-url <url>, env list, env use <name>');
+        }
+        case 'model': {
+            const name = positional.slice(1).join(' ').trim();
+            if (!name)
+                throw new ToolError('bad_args', 'Which model? codz model <Name> --from-clipboard', 'Or: codz model Order --sample order.json');
+            let text;
+            let from;
+            if (flags['from-clipboard'] === true || flags.clipboard === true)
+                [text, from] = [readClipboard(), 'The clipboard'];
+            else if (typeof flags.sample === 'string' || args.multi.sample?.length) {
+                const file = typeof flags.sample === 'string' ? flags.sample : args.multi.sample[0];
+                const t = readText(resolve(root, file)) ?? readText(resolve(file));
+                if (t === null)
+                    throw new ToolError('no_sample', `Cannot read ${file}.`);
+                [text, from] = [t, file];
+            }
+            else {
+                text = await readStdin();
+                if (!text.trim() && process.stdin.isTTY && !out.json) {
+                    process.stderr.write('Paste the JSON, then press Ctrl-D (Ctrl-Z then Enter on Windows).\n');
+                    const chunks = [];
+                    for await (const chunk of process.stdin)
+                        chunks.push(chunk);
+                    text = Buffer.concat(chunks).toString('utf8');
+                }
+                from = 'The pasted text';
+            }
+            const cs = await planModel(root, adapter, name, parseJsonText(text, from), { noUnwrap: flags['no-unwrap'] === true, force: flags.force === true, split: flags.split === true });
+            return handleChange(root, out, flags, cs, adapter);
+        }
+        case 'field': {
+            const [model, ...rest] = positional.slice(2);
+            if ((sub !== 'add' && sub !== 'remove') || !model)
+                throw new ToolError('bad_args', `Unknown command "field ${sub ?? ''}".`, 'Usage: codz field add <Model> <name:type> ... | codz field remove <Model> <field> ...');
+            const cs = sub === 'add' ? await planFieldAdd(root, adapter, model, rest) : await planFieldRemove(root, adapter, model, rest);
+            return handleChange(root, out, flags, cs, adapter);
+        }
         case 'mock': {
             if (sub !== 'add')
-                throw new ToolError('bad_args', `Unknown command "mock ${sub ?? ''}".`, 'Usage: codz mock add <endpoint> [--sample file.json] | codz mock add --all');
+                throw new ToolError('bad_args', `Unknown command "mock ${sub ?? ''}".`, 'Usage: codz mock add <endpoint> [--sample file.json] | codz mock add --all | codz mock serve [--spec api.yaml] [--port 4010]');
             const cs = await planMockAdd(root, adapter, { endpoints: positional.slice(2), all: flags.all === true, sample: typeof flags.sample === 'string' ? flags.sample : args.multi.sample?.[0], keepValues: flags['keep-values'] === true, force: flags.force === true });
             return handleChange(root, out, flags, cs, adapter);
         }
@@ -724,6 +868,8 @@ async function run(args, out) {
                 const cs = await planLocaleAdd(root, adapter, lang, { from: typeof flags.from === 'string' ? flags.from : undefined });
                 return handleChange(root, out, flags, cs, adapter);
             }
+            if (sub === 'extract')
+                return handleChange(root, out, flags, await planLocaleExtract(root, adapter, positional.slice(2)), adapter);
             if (sub === 'key') {
                 const key = positional[2];
                 const text = positional.slice(3).join(' ');
@@ -858,7 +1004,9 @@ async function run(args, out) {
             const name = positional[2];
             if (!name)
                 throw new ToolError('bad_args', 'Which screen? Usage: codz screen add <name> --api <endpoint> [--path /orders/:id]');
-            const cs = await planScreenAdd(root, adapter, { name, api: args.multi.api?.[0], path: typeof flags.path === 'string' ? flags.path : undefined, initial: flags.initial === true, form: flags.form === true });
+            const cs = await planScreenAdd(root, adapter, { name, api: args.multi.api?.[0], path: typeof flags.path === 'string' ? flags.path : undefined, initial: flags.initial === true, form: flags.form === true, paginate: flags.paginate === true, search: flags.search === true });
+            if ((flags.paginate === true || flags.search === true) && flags.form === true)
+                throw new ToolError('bad_args', '--paginate and --search are for list screens, not --form.');
             return handleChange(root, out, flags, cs, adapter);
         }
         case 'route': {
@@ -898,6 +1046,7 @@ async function run(args, out) {
                 throw new ToolError('bad_args', 'Which feature? Usage: codz feature add <name> --spec <openapi.yaml>', 'Example: codz feature add orders --spec api.yaml');
             const split = (xs) => xs?.flatMap((x) => (typeof x === 'string' ? x.split(',') : [])).map((x) => x.trim()).filter(Boolean) ?? [];
             const r = await planFeatureAdd(root, adapter, {
+                split: flags.split === true,
                 name,
                 spec: typeof flags.spec === 'string' ? flags.spec : undefined,
                 tags: split(args.multi.tag),
@@ -1023,6 +1172,7 @@ async function run(args, out) {
                 }
                 const showProgress = !out.json && process.stderr.isTTY === true;
                 const r = await planApiImport(root, adapter, {
+                    split: flags.split === true,
                     ...importOpts,
                     onProgress: showProgress
                         ? (done, total, name) => {
@@ -1042,6 +1192,7 @@ async function run(args, out) {
                 if (flags.check === true)
                     setCacheWrites(false);
                 const r = await planApiSync(root, adapter, {
+                    split: flags.split === true,
                     file,
                     tags: split(args.multi.tag),
                     paths: split([flags.path]),
@@ -1096,6 +1247,7 @@ async function run(args, out) {
                 noUnwrap: flags['no-unwrap'] === true,
                 into: typeof flags.into === 'string' ? flags.into : undefined,
                 noLoad: flags['no-load'] === true,
+                split: flags.split === true,
             };
             if (flags.clipboard === true && !opts.curl && !opts.url)
                 opts.paste = readClipboard();

package/dist/core/cache.js

@@ -48,13 +48,19 @@ export function fingerprint(root, configText) {
     }
     return hash(parts.join('\n'));
 }
+/** Conventions set for one run from the command line (--model-dir); never cached or saved. */
+let runOverrides = {};
+export function setRunConventions(c) {
+    runOverrides = { ...c };
+}
+const withRun = (map) => (Object.keys(runOverrides).length ? { ...map, conventions: { ...map.conventions, ...runOverrides } } : map);
 export async function loadMap(root, adapter, conventions, opts = {}) {
     const cachePath = join(root, TOOL_DIR, 'cache', 'map.json');
     const configText = readText(join(root, 'codz.config.yaml')) ?? '';
     const fp = fingerprint(root, configText);
     const cached = readJson(cachePath);
     if (!opts.force && cached && cached.schema === MAP_SCHEMA_VERSION && cached.adapter === `${adapter.id}@${adapter.version}` && cached.tool === toolFingerprint() && cached.fingerprint === fp) {
-        return { map: cached.map, fromCache: true };
+        return { map: withRun(cached.map), fromCache: true };
     }
     // An old schema or adapter version is simply rebuilt, never migrated.
     const map = await adapter.scan(root, conventions);
@@ -63,7 +69,7 @@ export async function loadMap(root, adapter, conventions, opts = {}) {
         toolDir(root, 'cache');
         writeFileSync(cachePath, JSON.stringify(file, null, 2));
     }
-    return { map, fromCache: false };
+    return { map: withRun(map), fromCache: false };
 }
 export function invalidateMap(root) {
     const cachePath = join(root, TOOL_DIR, 'cache', 'map.json');