codz-cli 0.1.2 → 0.1.8

package/docs/COMMANDS.md

@@ -1,6 +1,6 @@
 # codz commands
 
-Generated from `src/core/commands.ts` (codz 0.1.0). Do not edit by hand; run `npm run docs`.
+Generated from `src/core/commands.ts` (codz 0.1.8). Do not edit by hand; run `npm run docs`.
 
 ## Start
 
@@ -74,6 +74,8 @@ Input: --curl, --url, --clipboard, or a cURL command or URL pasted on stdin, opt
 | `--no-unwrap` | Keep a {"data": ...} envelope instead of returning data |
 | `--into <module>` | Call the endpoint from that module's controller (GetX) |
 | `--no-load` | Do not call the load method from onInit |
+| `--model-dir <folder>` | 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 |
+| `--split` | One file per model, instead of nested models in the file of the model that uses them |
 
 Accepts the change options.
 
@@ -92,6 +94,8 @@ Add every endpoint from an OpenAPI 3, Swagger 2, Postman or HAR file.
 | `--base-url <url>` | The API's base URL (setup), or only HAR requests under it (import/sync) |
 | `--include-errors` | HAR: keep failed (non-2xx) responses |
 | `--skip-conflicts` | Import what works and report endpoints that cannot be added |
+| `--model-dir <folder>` | 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 |
+| `--split` | One file per model, instead of nested models in the file of the model that uses them |
 
 Accepts the change options.
 
@@ -107,6 +111,8 @@ Bring endpoints in line with an API spec: update changed ones, report breaking c
 | `--tag <tag>` | Only operations with this tag (folder in Postman, host in HAR) (repeatable) |
 | `--path </users/{id}>` | Path parameters (api add), route path (screen/route add), or a path filter (import/sync) |
 | `--base-url <url>` | The API's base URL (setup), or only HAR requests under it (import/sync) |
+| `--model-dir <folder>` | 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 |
+| `--split` | One file per model, instead of nested models in the file of the model that uses them |
 
 Accepts the change options.
 
@@ -170,6 +176,58 @@ Every endpoint: method, path, function, response, file.
 
 One endpoint: signature, models, every place that uses it.
 
+### `codz model <Name> --from-clipboard | --sample <file.json>`
+
+A model (and its nested models) from JSON, without an endpoint.
+
+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.
+
+| Option | |
+| --- | --- |
+| `--from-clipboard` | Read the JSON from the clipboard |
+| `--sample <file.json>` | Response sample; repeat for several samples (repeatable) |
+| `--model-dir <folder>` | 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 |
+| `--no-unwrap` | Keep a {"data": ...} envelope instead of returning data |
+| `--force` | Do it even when codz would normally refuse (see the command) |
+| `--split` | One file per model, instead of nested models in the file of the model that uses them |
+
+Accepts the change options.
+
+### `codz field add <Model> <name:type> [...]`
+
+Add a field to a model, in every place the model spells it.
+
+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.
+
+Accepts the change options.
+
+### `codz field remove <Model> <field> [...]`
+
+Remove a field from a model and list the lines that still use it.
+
+Accepts the change options.
+
+### `codz mock serve [--spec <file>] [--port 4010] [--delay 300] [--items 5] [--scenario normal] [--lan]`
+
+A local fake API with sample data, so screens show data before the backend exists.
+
+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.
+
+| Option | |
+| --- | --- |
+| `--spec <file>` | OpenAPI, Swagger, Postman or HAR file to take the endpoints from |
+| `--port <n>` | Port for the mock API (default 4010) |
+| `--delay <ms>` | Wait before each answer, so loading states show (default 300) |
+| `--items <n>` | Items in each list to start with (default 5) |
+| `--scenario <name>` | How the mock answers at the start; switch live at /__codz |
+| `--lan` | Listen on your network too, for a phone on the same Wi-Fi (default: this computer only) |
+
 ### `codz mock add <endpoint>... | --all`
 
 Mock responses for building screens before the backend.
@@ -199,7 +257,42 @@ Accepts the change options.
 
 ## Screens and app
 
-### `codz screen add <name> --api <endpoint> [--path /x/:id] [--form]`
+### `codz assets`
+
+Typed names for images, icons and fonts, kept in step with the files; lists unused ones.
+
+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.
+
+Accepts the change options.
+
+### `codz env add <name> --base-url <url>`
+
+Add an API environment (staging, qa, ...) the app can run against.
+
+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.
+
+| Option | |
+| --- | --- |
+| `--base-url <url>` | The API's base URL (setup), or only HAR requests under it (import/sync) |
+| `--force` | Do it even when codz would normally refuse (see the command) |
+
+Accepts the change options.
+
+### `codz env list`
+
+The API environments and their base URLs.
+
+### `codz env use <name>`
+
+Switch the app to an environment (React Native CLI, Android, iOS).
+
+Accepts the change options.
+
+### `codz screen add <name> --api <endpoint> [--path /x/:id] [--paginate] [--search] [--form]`
 
 A working screen (route, page, the call, loading, error, data), or a form with --form.
 
@@ -211,6 +304,8 @@ Android: a Compose screen plus a ViewModel (Hilt, Koin or the service locator) w
 | `--path </users/{id}>` | Path parameters (api add), route path (screen/route add), or a path filter (import/sync) |
 | `--initial` | Make it the first screen |
 | `--form` | A form that sends the endpoint's request body (POST, PUT, PATCH) |
+| `--paginate` | List screens: load page after page as you scroll (the endpoint needs a page or offset parameter) |
+| `--search` | List screens: a search box (on the server with a q/search parameter, otherwise over the loaded items) |
 
 Accepts the change options.
 
@@ -250,6 +345,8 @@ Everything is planned in a private copy of the project and shown as one diff: on
 | `--no-tests` | Do not generate tests |
 | `--skip-conflicts` | Import what works and report endpoints that cannot be added |
 | `--no-install` | Do not install dependencies |
+| `--model-dir <folder>` | 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 |
+| `--split` | One file per model, instead of nested models in the file of the model that uses them |
 
 Accepts the change options.
 
@@ -299,6 +396,16 @@ Add a language: copies every key from the default one.
 
 Accepts the change options.
 
+### `codz locale extract [files...]`
+
+Move the text in screens into the locale files and read it back.
+
+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.
+
+Accepts the change options.
+
 ### `codz locale key <key> "<text>" [--value hi="..."]`
 
 Add a text key to every language file.
@@ -380,12 +487,6 @@ Accepts the change options.
 
 Find problems in codz.config.yaml (exit 1 on errors).
 
-### `codz mcp [--cwd <project>]`
-
-Serve codz to AI agents and editors over the Model Context Protocol (stdio).
-
-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.
-
 ### `codz completion bash|zsh|fish`
 
 Print the shell completion script.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codz-cli",
-  "version": "0.1.2",
+  "version": "0.1.8",
   "description": "CLI that adds API models, screens, routes and tests to Flutter, Next.js, React Native, Android and iOS apps in your project's own style, from OpenAPI or cURL.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "typescript": "^5.8.0"
   },
   "license": "MIT",
-  "author": "pradeep817",
+  "author": "codz-dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pradeep817/codz.git"
@@ -53,7 +53,6 @@
     "react",
     "android",
     "ios",
-    "swiftui",
-    "mcp"
+    "swiftui"
   ]
 }

package/dist/skills/mcp.js

@@ -1,175 +0,0 @@
-// codz mcp: a Model Context Protocol server on stdio, so AI agents and
-// editors can call codz as tools.
-//
-// Every command in the command table becomes a tool (api add → api_add) whose
-// input is its options plus the positional arguments. Tools run the codz
-// CLI itself with --json, in the project folder, so they behave exactly like
-// the command line. Commands that edit code never write: they return the diff
-// and a plan id, and the `apply` tool applies that plan exactly as shown.
-//
-// Resources: codz://project (what codz knows about the project) and
-// codz://commands (every command and option, as markdown).
-import { spawnSync } from 'node:child_process';
-import { createInterface } from 'node:readline';
-import { fileURLToPath } from 'node:url';
-import { CHANGE_FLAGS, COMMAND_LIST, FLAGS, GLOBAL_FLAGS, renderMarkdown } from "../core/commands.js";
-const PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05'];
-/** Commands that make no sense as tools: they need a terminal, or set up codz itself. */
-const NOT_TOOLS = new Set(['completion', 'init', 'mcp', 'login', 'logout']);
-export function toolName(spec) {
-    return `${spec.cmd}${spec.sub ? `_${spec.sub}` : ''}`.replace(/-/g, '_');
-}
-export function mcpTools() {
-    const tools = [];
-    for (const spec of COMMAND_LIST) {
-        if (NOT_TOOLS.has(spec.cmd))
-            continue;
-        const properties = {};
-        if (spec.usage.replace(/\[?--[^\]]*\]?/g, '').trim())
-            properties.args = { type: 'array', items: { type: 'string' }, description: `Positional arguments: ${spec.usage}` };
-        for (const f of spec.flags) {
-            if (CHANGE_FLAGS.includes(f) || GLOBAL_FLAGS.includes(f) || f.length === 1)
-                continue;
-            const def = FLAGS[f];
-            const description = def.desc + (def.choices ? ` (${def.choices.join(', ')})` : '');
-            properties[f] = def.value ? (def.repeat ? { type: 'array', items: { type: 'string' }, description } : { type: 'string', description }) : { type: 'boolean', description };
-        }
-        if (spec.cmd === 'apply') {
-            properties['allow-dirty'] = { type: 'boolean', description: FLAGS['allow-dirty'].desc };
-            properties['no-verify'] = { type: 'boolean', description: FLAGS['no-verify'].desc };
-        }
-        const writes = spec.change && !(spec.cmd === 'doctor');
-        tools.push({
-            name: toolName(spec),
-            description: `${spec.summary}.${writes || spec.cmd === 'new' ? ' Returns the diff and a plan id; nothing is written until you call apply with that id.' : ''}${spec.cmd === 'new' ? ' Paid starters are never downloaded from here: the user downloads one once in a terminal (codz new or starters show), then it can be planned.' : ''}${spec.cmd === 'doctor' ? ' With fix: true it returns a plan to apply instead of reporting.' : ''}${spec.notes?.length ? ` ${spec.notes.join(' ')}` : ''}`,
-            inputSchema: { type: 'object', properties, additionalProperties: false },
-            spec,
-        });
-    }
-    return tools;
-}
-/** The CLI arguments for a tool call. Change commands always get --plan, so a tool never writes by itself. */
-export function cliArgs(tool, input) {
-    const { spec } = tool;
-    const out = [spec.cmd, ...(spec.sub ? [spec.sub] : [])];
-    const args = Array.isArray(input.args) ? input.args.map(String) : [];
-    // A positional argument that looks like an option (--cwd, --yes, --force, --root) would let a tool call widen what it
-    // may do. Options only come through the schema's named properties, which are checked below.
-    const flagLike = args.find((a) => a.startsWith('-'));
-    if (flagLike)
-        throw new Error(`Positional arguments cannot start with "-" (got "${flagLike.slice(0, 40)}"); pass options as named properties.`);
-    out.push(...args);
-    for (const [k, v] of Object.entries(input)) {
-        if (k === 'args' || v === undefined || v === null || v === false)
-            continue;
-        if (!(k in tool.inputSchema.properties))
-            throw new Error(`Unknown argument "${k}" for ${tool.name}.`);
-        if (v === true)
-            out.push(`--${k}`);
-        else if (Array.isArray(v))
-            for (const x of v)
-                out.push(`--${k}`, String(x));
-        else
-            out.push(`--${k}`, String(v));
-    }
-    // codz new only ever plans from an agent; a person applies (and a paid starter must already be downloaded).
-    if (spec.cmd === 'new')
-        out.push('--plan');
-    if (spec.change && spec.cmd !== 'apply' && !(spec.cmd === 'doctor' && input.fix !== true) && !(spec.cmd === 'api' && spec.sub === 'sync' && input.check === true))
-        out.push('--plan');
-    out.push('--json', '--no-color');
-    return out;
-}
-const BIN = fileURLToPath(new URL('../../bin/codz.js', import.meta.url));
-function runCli(args, cwd) {
-    const r = spawnSync(process.execPath, [BIN, ...args], { cwd, encoding: 'utf8', input: '', env: { ...process.env, NO_COLOR: '1', CODZ_MCP: '1' }, maxBuffer: 64 * 1024 * 1024, timeout: 120_000 });
-    return { code: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
-}
-/** Handles one message; returns the response, or null for notifications. */
-export function handleMessage(msg, cwd, version, tools = mcpTools()) {
-    const reply = (result) => ({ jsonrpc: '2.0', id: msg.id, result });
-    const fail = (code, message) => ({ jsonrpc: '2.0', id: msg.id, error: { code, message } });
-    if (msg.id === undefined)
-        return null; // notifications (initialized, cancelled) need no answer
-    switch (msg.method) {
-        case 'initialize': {
-            const asked = String(msg.params?.protocolVersion ?? '');
-            return reply({
-                protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0],
-                capabilities: { tools: { listChanged: false }, resources: { listChanged: false } },
-                serverInfo: { name: 'codz', version },
-                instructions: 'codz understands this Next.js or Flutter project and changes it deterministically. Start with explain. Tools that edit code return a diff and a planId; review it, then call apply with the planId. Use dry runs freely: nothing is written until apply.',
-            });
-        }
-        case 'ping':
-            return reply({});
-        case 'tools/list':
-            return reply({ tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
-        case 'tools/call': {
-            const tool = tools.find((t) => t.name === msg.params?.name);
-            if (!tool)
-                return fail(-32602, `Unknown tool: ${String(msg.params?.name)}`);
-            let args;
-            try {
-                args = cliArgs(tool, msg.params?.arguments ?? {});
-            }
-            catch (e) {
-                return reply({ content: [{ type: 'text', text: e.message }], isError: true });
-            }
-            const r = runCli(args, cwd);
-            let isError = r.code !== 0;
-            let text = r.stdout.trim();
-            try {
-                const json = JSON.parse(text);
-                // A failed check (exit 1) is still a useful answer; only {"ok": false} is an error.
-                isError = json.ok === false;
-                text = JSON.stringify(json, null, 2);
-            }
-            catch {
-                text = [text, r.stderr.trim()].filter(Boolean).join('\n') || `codz exited with code ${r.code}`;
-            }
-            return reply({ content: [{ type: 'text', text }], isError });
-        }
-        case 'resources/list':
-            return reply({
-                resources: [
-                    { uri: 'codz://project', name: 'Project map', description: 'Framework, conventions, endpoints, models, routes and locales codz found', mimeType: 'application/json' },
-                    { uri: 'codz://commands', name: 'codz commands', description: 'Every command and option', mimeType: 'text/markdown' },
-                ],
-            });
-        case 'resources/read': {
-            const uri = String(msg.params?.uri ?? '');
-            if (uri === 'codz://commands')
-                return reply({ contents: [{ uri, mimeType: 'text/markdown', text: renderMarkdown(version) }] });
-            if (uri === 'codz://project') {
-                const r = runCli(['explain', '--json', '--no-color'], cwd);
-                return reply({ contents: [{ uri, mimeType: 'application/json', text: r.stdout.trim() || r.stderr.trim() }] });
-            }
-            return fail(-32002, `Unknown resource: ${uri}`);
-        }
-        default:
-            return fail(-32601, `Method not found: ${msg.method}`);
-    }
-}
-/** Runs the server until stdin closes. Logs go to stderr; stdout carries only protocol messages. */
-export function serveMcp(cwd, version) {
-    const tools = mcpTools();
-    process.stderr.write(`codz mcp: serving ${tools.length} tools for ${cwd}\n`);
-    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
-    rl.on('line', (line) => {
-        if (!line.trim())
-            return;
-        let msg;
-        try {
-            msg = JSON.parse(line);
-        }
-        catch {
-            process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) + '\n');
-            return;
-        }
-        const res = handleMessage(msg, cwd, version, tools);
-        if (res)
-            process.stdout.write(JSON.stringify(res) + '\n');
-    });
-    return new Promise((resolve) => rl.on('close', () => resolve(0)));
-}