codz-cli 0.0.0-stage → 0.1.0

package/dist/core/commands.js

@@ -0,0 +1,239 @@
+// Every command and flag codz accepts, in one table. Help, per-command
+// help, shell completion, the flag parser (which flags take a value, which
+// repeat), unknown-flag errors and docs/COMMANDS.md are all generated from it,
+// so they cannot drift apart. A test checks that every command the CLI
+// handles is listed here.
+export const FLAGS = {
+    // Global
+    json: { desc: 'Machine-readable output on stdout (for scripts and AI agents)' },
+    cwd: { value: '<folder>', desc: 'Run as if started in <folder>', path: true },
+    root: { value: '<folder>', desc: 'Project root (monorepos: which project)', path: true },
+    'no-color': { desc: 'Plain output' },
+    help: { desc: 'Show help (for one command: codz <command> --help)' },
+    h: { desc: 'Same as --help' },
+    version: { desc: 'Print the version' },
+    v: { desc: 'Same as --version' },
+    // Change options
+    'dry-run': { desc: 'Show the diff only' },
+    plan: { desc: 'Save the diff as a plan and print its id (apply later with codz apply)' },
+    yes: { desc: 'Apply without asking' },
+    y: { desc: 'Same as --yes' },
+    'allow-dirty': { desc: 'Apply even if git has uncommitted changes' },
+    'no-format': { desc: "Do not run the project's formatter" },
+    'no-verify': { desc: "Do not run the project's analyzer after applying" },
+    commit: { desc: 'Commit the applied files' },
+    'commit-message': { value: '<text>', desc: 'Message for --commit (default: one from the summary)' },
+    open: { desc: 'Open the diff in $EDITOR before asking' },
+    // api add input and options
+    curl: { value: "'<curl command>'", desc: 'A cURL command; secrets in it are removed, never written' },
+    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' },
+    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' },
+    path: { value: '</users/{id}>', desc: 'Path parameters (api add), route path (screen/route add), or a path filter (import/sync)' },
+    'model-name': { value: '<Name>', desc: 'Name the response model yourself' },
+    'no-unwrap': { desc: 'Keep a {"data": ...} envelope instead of returning data' },
+    into: { value: '<module>', desc: "Call the endpoint from that module's controller (GetX)" },
+    // import / sync
+    tag: { value: '<tag>', desc: 'Only operations with this tag (folder in Postman, host in HAR)', repeat: true },
+    only: { value: '<name>', desc: 'Only these operations (import), or only these checks (doctor)', repeat: true },
+    max: { value: '<n>', desc: 'Import at most n operations' },
+    list: { desc: 'Show what would be imported and stop' },
+    'base-url': { value: '<url>', desc: "The API's base URL (setup), or only HAR requests under it (import/sync)" },
+    'include-errors': { desc: 'HAR: keep failed (non-2xx) responses' },
+    'skip-conflicts': { desc: 'Import what works and report endpoints that cannot be added' },
+    add: { desc: 'Also add operations the project does not have yet' },
+    remove: { desc: 'Also delete endpoints the spec no longer has' },
+    check: { desc: 'Report drift without writing; exit 1 when out of sync' },
+    // module / wire / screen / route
+    api: { value: '<endpoint>', desc: 'Endpoint to load (repeat for several in module add)', repeat: true },
+    initial: { desc: 'Make it the first screen' },
+    'no-load': { desc: 'Do not call the load method from onInit' },
+    form: { desc: "A form that sends the endpoint's request body (POST, PUT, PATCH)" },
+    // feature add
+    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' },
+    // 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 },
+    'fail-on': { value: '<breaking|warning|any|none>', desc: 'Exit 1 at this level (default breaking)', choices: ['breaking', 'warning', 'any', 'none'] },
+    // auth add
+    'login-path': { value: '</auth/login>', desc: 'Sign-in endpoint: POST { email, password }, answers with the token (default /auth/login)' },
+    'me-path': { value: '</auth/me>', desc: 'Endpoint that returns the signed-in user (default /auth/me)' },
+    'logout-path': { value: '</auth/logout>', desc: 'Sign-out endpoint, called on sign out (default /auth/logout)' },
+    'refresh-path': { value: '</auth/refresh>', desc: 'Refresh endpoint: POST { refreshToken }; with it a 401 tries one refresh first (Flutter, React Native)' },
+    'token-field': { value: '<name>', desc: 'Field of the login answer with the token (default token)' },
+    'refresh-field': { value: '<name>', desc: 'Field with the refresh token (default refreshToken)' },
+    public: { value: '</about>', desc: 'Next.js: a page that stays public (besides /login)', repeat: true },
+    // mock / test
+    all: { desc: 'Every endpoint (mock add, test add), or every plan (plans clean)' },
+    'keep-values': { desc: "Write --sample values exactly as given (no secret or personal-data scrubbing)" },
+    // locale
+    from: { value: '<lang>', desc: 'Language to copy keys from (default: the default language)' },
+    value: { value: 'lang="text"', desc: 'Text for one more language; repeat for several', repeat: true },
+    // setup / init
+    architecture: { value: '<id>', desc: 'Flutter: getx, riverpod, bloc, get_it. Next.js: fetch-helper, plain-fetch. React Native and React: fetch-helper, axios, axios-react-query. Android: retrofit-hilt, retrofit-koin, retrofit. iOS: urlsession' },
+    // create
+    type: { value: '<type>', desc: 'Project type: flutter, nextjs, react-native, android', choices: ['flutter', 'nextjs', 'react-native', 'android'] },
+    flavor: { value: '<expo|bare>', desc: 'React Native: Expo (default) or the React Native CLI', choices: ['expo', 'bare'] },
+    org: { value: '<com.example>', desc: 'Organization in reverse-domain form, for app ids (default com.example)' },
+    tailwind: { desc: 'Next.js: use Tailwind CSS' },
+    primary: { value: '<#rrggbb>', desc: "The theme's primary color" },
+    offline: { desc: "Do not run the platform's creator; write codz's minimal project" },
+    'no-install': { desc: 'Do not install dependencies' },
+    'no-git': { desc: 'Do not run git init' },
+    // doctor
+    strict: { desc: 'Exit 1 on warnings too' },
+    setup: { desc: 'Check that codz can run here: Node, git, config, formatter, analyzer' },
+    fix: { desc: 'Repair what is safe as one previewed change; list the rest' },
+    // explain / undo / config
+    rescan: { desc: 'Scan again instead of using the cached project map' },
+    force: { desc: 'Do it even when codz would normally refuse (see the command)' },
+    to: { value: '<id>', desc: 'Undo every change back to and including <id>' },
+    // codz new and the starter catalog
+    template: { value: '<id[@version]|folder>', desc: 'The starter: a catalog id (pin a version with @x.y.z) or a template folder' },
+    set: { value: '<key=value>', desc: "Answer one of the starter's questions; repeat for more", repeat: true },
+    dir: { value: '<folder>', desc: 'Parent folder for the new project (default: the current folder)', path: true },
+    framework: { value: '<name>', desc: 'Only starters for this framework', choices: ['flutter', 'nextjs', 'react-native', 'android'] },
+    state: { value: '<name>', desc: 'Only starters with this state management (riverpod, get_it, ...)' },
+    router: { value: '<name>', desc: 'Only starters with this router (go_router, ...)' },
+    http: { value: '<name>', desc: 'Only starters with this HTTP client (dio, fetch, ...)' },
+    cached: { desc: 'Use only starters and the catalog already downloaded on this machine (no network)' },
+    'no-steps': { desc: 'Skip the setup steps after creating (flutter pub get, dart format, npm install)' },
+    owned: { desc: 'Only starters your account owns (and free ones)' },
+    free: { desc: 'Only free starters' },
+    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' },
+};
+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'];
+export const COMMAND_LIST = [
+    { group: 'Start', cmd: 'create', usage: '[name] [--type <type>] [--architecture <id>]', summary: 'Create a new project and set it up: pick the type, architecture, name and options, then codz runs the platform creator and applies the architecture', flags: ['type', 'architecture', 'base-url', 'org', 'tailwind', 'flavor', 'primary', 'offline', 'no-install', 'no-git', 'dry-run', 'yes', 'y'], notes: ['Asks for anything not given as an option. Architectures: Flutter riverpod, getx, bloc, get_it, none; Next.js fetch-helper, plain-fetch, none; React Native fetch-helper, axios-react-query, axios, none (--flavor expo or bare); Android retrofit-hilt, retrofit-koin, retrofit, none (Kotlin, Jetpack Compose, version catalog). Without the platform creator (flutter, npx) or with --offline, codz writes a minimal project itself; Android always uses the built-in template (the Android Studio Empty Activity project plus Navigation Compose).'] },
+    { 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: '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' },
+    { group: 'Endpoints', cmd: 'api', sub: 'rename', usage: '<endpoint> <newName>', summary: 'Rename an endpoint and its call sites', flags: [], change: true, args: 'endpoint' },
+    { 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: '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: '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: '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: '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: [] },
+    { group: 'Screens and app', cmd: 'templates', sub: 'init', usage: '[id...]', summary: "Start custom templates from files that reproduce codz's output", flags: [], change: true, args: 'template' },
+    { group: 'Health', cmd: 'report', usage: '[--json]', summary: 'Usage summary for beta feedback: commands run, changes applied and undone, errors; no code, file names or URLs', flags: [], notes: ['Built from .codz/history.json and .codz/events.jsonl, which stay on this machine. CODZ_NO_EVENTS=1 stops recording commands.'] },
+    { group: 'Health', cmd: 'doctor', usage: '[--only locales,api,urls,models] [--strict] [--fix] [--setup]', summary: 'Check locales, unhandled API errors, untyped responses, hardcoded URLs and unused models', flags: ['only', 'strict', 'fix', 'setup', 'force'], change: true, notes: ['Exit 1 on errors (--strict: on warnings too). --fix repairs what is safe (missing locale keys, base-URL literals, unused models) as one previewed change. --setup checks Node, git, the config, the formatter and the analyzer instead.'] },
+    { group: 'Health', cmd: 'check', usage: '', summary: 'CI gate: config check + doctor; exit 1 on any error or warning', flags: [] },
+    { group: 'Setup', cmd: 'config', sub: 'show', usage: '', summary: 'The conventions codz uses, and where each came from', flags: [] },
+    { 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'] },
+    { group: 'Starters (online)', cmd: 'starters', sub: 'show', usage: '<id>[@version]', summary: 'One starter: what it includes beyond codz create, tested SDKs, license, versions', flags: ['refresh', 'cached'] },
+    { group: 'Starters (online)', cmd: 'starters', sub: 'cache', usage: '[--clear]', summary: 'Starters downloaded on this machine (--clear deletes them)', flags: ['clear'] },
+    { group: 'Starters (online)', cmd: 'login', usage: '[--no-browser]', summary: 'Log in to the starter catalog (prints a code to approve in the browser); needed only for paid starters', flags: ['no-browser'], notes: ['The token is kept in ~/.codz/auth.json, readable only by you. In CI, set CODZ_TOKEN instead.'] },
+    { group: 'Starters (online)', cmd: 'logout', usage: '', summary: 'Log out: delete the token here and revoke it on the server', flags: [] },
+    { group: 'Starters (online)', cmd: 'whoami', usage: '', summary: 'The logged-in account and the starters it owns', flags: [] },
+    { group: 'Changes', cmd: 'plans', sub: 'list', usage: '', summary: 'Plans saved with --plan: ready, applied or stale', flags: [] },
+    { group: 'Changes', cmd: 'plans', sub: 'show', usage: '<id>', summary: "One plan's summary and diff", flags: [], args: 'plan' },
+    { group: 'Changes', cmd: 'plans', sub: 'clean', usage: '[--all]', summary: 'Delete applied and stale plans (--all: every plan)', flags: ['all'] },
+    { group: 'Changes', cmd: 'apply', usage: '<plan-id>', summary: 'Apply a plan saved with --plan, exactly as previewed', flags: ['allow-dirty', 'no-format', 'no-verify', 'commit', 'commit-message'], args: 'plan' },
+    { group: 'Changes', cmd: 'undo', usage: '[--to <id>] [--force]', summary: 'Revert the last applied change (or every change back to <id>)', flags: ['to', 'force', 'yes', 'y'] },
+    { group: 'Changes', cmd: 'history', usage: '[show <id>]', summary: "List applied changes, or show one change's files and diff", flags: [] },
+];
+export const HISTORY_SUBS = ['show'];
+/** The commands that take subcommands, and those subcommands. */
+export function subcommands(cmd) {
+    return COMMAND_LIST.filter((c) => c.cmd === cmd && c.sub).map((c) => c.sub);
+}
+export function findCommand(cmd, sub) {
+    return COMMAND_LIST.find((c) => c.cmd === cmd && c.sub === sub) ?? COMMAND_LIST.find((c) => c.cmd === cmd && !c.sub) ?? (sub === undefined ? COMMAND_LIST.find((c) => c.cmd === cmd) : undefined);
+}
+/** Flags a command accepts, including global and change options. */
+export function allowedFlags(spec) {
+    return [...new Set([...spec.flags, ...(spec.change ? CHANGE_FLAGS : []), ...GLOBAL_FLAGS])];
+}
+export const BOOLEAN_FLAGS = new Set(Object.entries(FLAGS).filter(([, f]) => !f.value).map(([n]) => n));
+export const REPEATABLE_FLAGS = new Set(Object.entries(FLAGS).filter(([, f]) => f.repeat).map(([n]) => n));
+const flagLabel = (n) => `--${n}${FLAGS[n]?.value ? ` ${FLAGS[n].value}` : ''}`;
+const line = (left, right, width = 46) => (left.length < width ? `  ${left.padEnd(width)} ${right}` : `  ${left}\n  ${' '.repeat(width)} ${right}`);
+export function renderHelp(version, configFile) {
+    const groups = [...new Set(COMMAND_LIST.map((c) => c.group))];
+    const out = [`codz ${version}: understands your project, then changes it the same way every time.`, '', 'Usage: codz <command> [options]   (codz <command> --help for its options)'];
+    for (const g of groups) {
+        out.push('', g);
+        for (const c of COMMAND_LIST.filter((x) => x.group === g))
+            out.push(line(`codz ${c.cmd}${c.sub ? ` ${c.sub}` : ''}${c.usage ? ` ${c.usage}` : ''}`, c.summary.replace('codz.config.yaml', configFile)));
+    }
+    out.push('', 'Change options (commands that edit code)');
+    for (const f of CHANGE_FLAGS.filter((n) => n !== 'y'))
+        out.push(line(flagLabel(f), FLAGS[f].desc, 24));
+    out.push('', 'Global');
+    for (const f of GLOBAL_FLAGS.filter((n) => !['h', 'v'].includes(n)))
+        out.push(line(flagLabel(f), FLAGS[f].desc, 24));
+    return out.join('\n') + '\n';
+}
+export function renderCommandHelp(spec) {
+    const name = `codz ${spec.cmd}${spec.sub ? ` ${spec.sub}` : ''}`;
+    const out = [`${name}${spec.usage ? ` ${spec.usage}` : ''}`, '', spec.summary];
+    const own = spec.flags.filter((f) => !CHANGE_FLAGS.includes(f) && !GLOBAL_FLAGS.includes(f));
+    if (own.length) {
+        out.push('', 'Options');
+        for (const f of own)
+            out.push(line(flagLabel(f), FLAGS[f].desc, 28));
+    }
+    for (const n of spec.notes ?? [])
+        out.push('', n);
+    if (spec.change)
+        out.push('', `Change options: ${CHANGE_FLAGS.filter((n) => n !== 'y').map((f) => `--${f}`).join(', ')}`);
+    out.push(`Global: ${GLOBAL_FLAGS.filter((n) => !['h', 'v'].includes(n)).map((f) => `--${f}`).join(', ')}`);
+    return out.join('\n') + '\n';
+}
+/** docs/COMMANDS.md. */
+export function renderMarkdown(version) {
+    const out = ['# codz commands', '', `Generated from \`src/core/commands.ts\` (codz ${version}). Do not edit by hand; run \`npm run docs\`.`, ''];
+    for (const g of [...new Set(COMMAND_LIST.map((c) => c.group))]) {
+        out.push(`## ${g}`, '');
+        for (const c of COMMAND_LIST.filter((x) => x.group === g)) {
+            out.push(`### \`codz ${c.cmd}${c.sub ? ` ${c.sub}` : ''}${c.usage ? ` ${c.usage}` : ''}\``, '', c.summary + '.', '');
+            for (const n of c.notes ?? [])
+                out.push(n, '');
+            const own = c.flags.filter((f) => !CHANGE_FLAGS.includes(f) && !GLOBAL_FLAGS.includes(f));
+            if (own.length) {
+                out.push('| Option | |', '| --- | --- |');
+                for (const f of own)
+                    out.push(`| \`${flagLabel(f).replace(/\|/g, '\\|')}\` | ${FLAGS[f].desc.replace(/\|/g, '\\|')}${FLAGS[f].repeat ? ' (repeatable)' : ''} |`);
+                out.push('');
+            }
+            if (c.change)
+                out.push('Accepts the change options.', '');
+        }
+    }
+    out.push('## Change options', '', '| Option | |', '| --- | --- |');
+    for (const f of CHANGE_FLAGS)
+        out.push(`| \`${flagLabel(f)}\` | ${FLAGS[f].desc} |`);
+    out.push('', '## Global options', '', '| Option | |', '| --- | --- |');
+    for (const f of GLOBAL_FLAGS)
+        out.push(`| \`${flagLabel(f)}\` | ${FLAGS[f].desc} |`);
+    return out.join('\n') + '\n';
+}

package/dist/core/config.js

@@ -0,0 +1,45 @@
+// codz.config.yaml: the only file codz asks you to commit. It holds the
+// conventions you confirmed, which override what the scanner detects.
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readText } from "./fsutil.js";
+import { ToolError } from "./types.js";
+import { parse, stringify } from "./yaml.js";
+export const CONFIG_FILE = 'codz.config.yaml';
+export function loadConfig(root) {
+    const text = readText(join(root, CONFIG_FILE));
+    if (text == null)
+        return { conventions: {}, exists: false };
+    let data;
+    try {
+        data = parse(text);
+    }
+    catch (e) {
+        throw new ToolError('bad_config', e.message, 'Fix that line, or see every problem with: codz config check');
+    }
+    const conventions = {};
+    const raw = data.conventions;
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        for (const [k, v] of Object.entries(raw))
+            if (typeof v === 'string' && v !== '')
+                conventions[k] = v;
+    }
+    const framework = typeof data.framework === 'string' ? data.framework : undefined;
+    return { framework, conventions, exists: true };
+}
+export function renderConfig(framework, conventions, descriptions) {
+    const header = [
+        '# codz configuration. Commit this file.',
+        '# Values below were detected by `codz init` (or chosen in `codz setup`).',
+        '# Correct any that are wrong: codz always uses these values instead of guessing again.',
+        '',
+    ].join('\n');
+    const comments = {};
+    for (const [k, d] of Object.entries(descriptions))
+        comments[`conventions.${k}`] = d;
+    const body = { framework, conventions: { ...conventions } };
+    return header + stringify(body, comments);
+}
+export function writeConfig(root, framework, conventions, descriptions) {
+    writeFileSync(join(root, CONFIG_FILE), renderConfig(framework, conventions, descriptions));
+}

package/dist/core/diff.js

@@ -0,0 +1,143 @@
+// Line-based unified diff (Myers algorithm), no dependencies.
+function splitLines(text) {
+    if (text === '')
+        return [];
+    const lines = text.replace(/\r\n/g, '\n').split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+export function diffLines(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const max = n + m;
+    const offset = max;
+    const v = new Int32Array(2 * max + 2);
+    const trace = [];
+    let found = false;
+    for (let d = 0; d <= max && !found; d++) {
+        trace.push(v.slice());
+        for (let k = -d; k <= d; k += 2) {
+            let x;
+            if (k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1]))
+                x = v[offset + k + 1];
+            else
+                x = v[offset + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[offset + k] = x;
+            if (x >= n && y >= m) {
+                found = true;
+                break;
+            }
+        }
+    }
+    // Backtrack.
+    const ops = [];
+    let x = n;
+    let y = m;
+    for (let d = trace.length - 1; d >= 0; d--) {
+        const vd = trace[d];
+        const k = x - y;
+        let prevK;
+        if (k === -d || (k !== d && vd[offset + k - 1] < vd[offset + k + 1]))
+            prevK = k + 1;
+        else
+            prevK = k - 1;
+        const prevX = vd[offset + prevK];
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            ops.push({ type: 'equal', line: a[x - 1] });
+            x--;
+            y--;
+        }
+        if (d > 0) {
+            if (x === prevX)
+                ops.push({ type: 'add', line: b[y - 1] });
+            else
+                ops.push({ type: 'del', line: a[x - 1] });
+        }
+        x = prevX;
+        y = prevY;
+    }
+    return ops.reverse();
+}
+const C = {
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+/** Returns a unified diff for one file; `before` null means a new file, `after` null a deleted one. */
+export function unifiedDiff(path, before, after, opts = {}) {
+    const ctx = opts.context ?? 3;
+    const color = opts.color ?? false;
+    const paint = (fn, s) => (color ? fn(s) : s);
+    const a = splitLines(before ?? '');
+    const b = splitLines(after ?? '');
+    const ops = diffLines(a, b);
+    if (!ops.some((o) => o.type !== 'equal'))
+        return '';
+    const header = [paint(C.bold, `--- ${before === null ? '/dev/null' : `a/${path}`}`), paint(C.bold, `+++ ${after === null ? '/dev/null' : `b/${path}`}`)];
+    const hunks = [];
+    // Group changes into hunks with context.
+    let i = 0;
+    let aLine = 1;
+    let bLine = 1;
+    const positions = [];
+    for (const op of ops) {
+        positions.push({ aLine, bLine });
+        if (op.type !== 'add')
+            aLine++;
+        if (op.type !== 'del')
+            bLine++;
+    }
+    while (i < ops.length) {
+        if (ops[i].type === 'equal') {
+            i++;
+            continue;
+        }
+        let start = Math.max(0, i - ctx);
+        let end = i;
+        // Extend the hunk while changes are within 2*ctx of each other.
+        while (end < ops.length) {
+            if (ops[end].type !== 'equal') {
+                end++;
+                continue;
+            }
+            let run = 0;
+            while (end + run < ops.length && ops[end + run].type === 'equal')
+                run++;
+            if (end + run >= ops.length || run > ctx * 2) {
+                end = Math.min(ops.length, end + Math.min(run, ctx));
+                break;
+            }
+            end += run;
+        }
+        const slice = ops.slice(start, end);
+        const aStart = positions[start].aLine;
+        const bStart = positions[start].bLine;
+        const aCount = slice.filter((o) => o.type !== 'add').length;
+        const bCount = slice.filter((o) => o.type !== 'del').length;
+        const lines = [paint(C.cyan, `@@ -${aCount === 0 ? aStart - 1 : aStart},${aCount} +${bCount === 0 ? bStart - 1 : bStart},${bCount} @@`)];
+        for (const op of slice) {
+            if (op.type === 'equal')
+                lines.push(` ${op.line}`);
+            else if (op.type === 'add')
+                lines.push(paint(C.green, `+${op.line}`));
+            else
+                lines.push(paint(C.red, `-${op.line}`));
+        }
+        hunks.push(lines.join('\n'));
+        i = end;
+        start = end;
+    }
+    return [...header, ...hunks].join('\n') + '\n';
+}
+export function diffStats(before, after) {
+    const ops = diffLines(splitLines(before ?? ''), splitLines(after ?? ''));
+    return { added: ops.filter((o) => o.type === 'add').length, removed: ops.filter((o) => o.type === 'del').length };
+}

package/dist/core/events.js

@@ -0,0 +1,41 @@
+// A local log of which codz commands ran and how they ended, for `codz
+// report` (beta feedback). It holds the command name, success or the error
+// code, and the time taken: never arguments, code, file names or URLs. It stays
+// in the project's .codz/ folder and is never sent anywhere. It is written
+// only where codz already has its .codz/ folder, and
+// CODZ_NO_EVENTS=1 turns it off.
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { TOOL_DIR } from "./cache.js";
+const MAX_EVENTS = 5000;
+const eventsFile = (root) => join(root, TOOL_DIR, 'events.jsonl');
+export function recordEvent(root, ev) {
+    if (process.env.CODZ_NO_EVENTS === '1')
+        return;
+    try {
+        // Only where codz already keeps its folder (made by the first scan or change); never a new folder.
+        if (!existsSync(join(root, TOOL_DIR)))
+            return;
+        const file = eventsFile(root);
+        appendFileSync(file, `${JSON.stringify(ev)}\n`);
+        // Keep the newest events only.
+        const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+        if (lines.length > MAX_EVENTS * 1.2)
+            writeFileSync(file, `${lines.slice(-MAX_EVENTS).join('\n')}\n`);
+    }
+    catch {
+        // The log is a convenience; it never makes a command fail.
+    }
+}
+export function readEvents(root) {
+    try {
+        return readFileSync(eventsFile(root), 'utf8')
+            .split('\n')
+            .filter(Boolean)
+            .map((l) => JSON.parse(l))
+            .filter((e) => e && typeof e.cmd === 'string');
+    }
+    catch {
+        return [];
+    }
+}

package/dist/core/fsutil.js

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+export const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.codz',
+    '.next',
+    '.dart_tool',
+    'build',
+    'dist',
+    'out',
+    '.idea',
+    '.vscode',
+    'coverage',
+    'Pods',
+    '.gradle',
+    '.turbo',
+    '.vercel',
+]);
+/** Files the operating system or editors drop into folders; never part of a project. */
+export const IGNORED_FILES = new Set(['.DS_Store', 'Thumbs.db', 'ehthumbs.db', 'desktop.ini', 'Icon\r', '.directory']);
+const isJunkFile = (name) => IGNORED_FILES.has(name) || name.startsWith('._') || name.endsWith('~') || /\.sw[po]$/.test(name);
+export function hash(content) {
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+export function toPosix(p) {
+    return p.split(sep).join('/');
+}
+export function rel(root, abs) {
+    return toPosix(relative(root, abs));
+}
+export function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function readJson(path) {
+    const text = readText(path);
+    if (text == null)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function exists(path) {
+    return existsSync(path);
+}
+/**
+ * Walks a directory and returns relative posix paths of files, sorted so scans
+ * are deterministic. `extraIgnored` lets adapters skip more folders.
+ */
+export function walk(root, start = '.', opts = {}) {
+    const out = [];
+    const ignored = new Set([...IGNORED_DIRS, ...(opts.extraIgnored ?? [])]);
+    const max = opts.maxFiles ?? 20000;
+    const base = join(root, start);
+    if (!isDir(base))
+        return out;
+    const stack = [base];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir).sort();
+        }
+        catch {
+            continue;
+        }
+        // Push directories in reverse so traversal order is alphabetical.
+        const dirs = [];
+        for (const name of entries) {
+            const abs = join(dir, name);
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (!ignored.has(name) && !name.startsWith('.'))
+                    dirs.push(abs);
+            }
+            else if (isJunkFile(name)) {
+                continue;
+            }
+            else if (!opts.exts || opts.exts.some((e) => name.endsWith(e))) {
+                out.push(rel(root, abs));
+                if (out.length >= max)
+                    return out.sort();
+            }
+        }
+        for (let i = dirs.length - 1; i >= 0; i--)
+            stack.push(dirs[i]);
+    }
+    return out.sort();
+}
+export function detectEol(text) {
+    const crlf = (text.match(/\r\n/g) ?? []).length;
+    const lf = (text.match(/\n/g) ?? []).length - crlf;
+    return crlf > lf ? '\r\n' : '\n';
+}
+/** Normalizes generated text (always \n) to the file's own line endings. */
+export function withEol(text, eol) {
+    const normalized = text.replace(/\r\n/g, '\n');
+    return eol === '\n' ? normalized : normalized.replace(/\n/g, '\r\n');
+}

package/dist/core/git.js

@@ -0,0 +1,36 @@
+import { spawnSync } from 'node:child_process';
+export function isGitRepo(root) {
+    const r = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: root, encoding: 'utf8' });
+    return r.status === 0 && r.stdout.trim() === 'true';
+}
+/**
+ * Files with uncommitted changes under `root`, relative to `root` (not to the
+ * repository), excluding codz's own folder. Works when the project is a
+ * subfolder of a larger repository, and with renames and unusual file names.
+ */
+export function dirtyFiles(root) {
+    const prefix = spawnSync('git', ['rev-parse', '--show-prefix'], { cwd: root, encoding: 'utf8' });
+    if (prefix.status !== 0)
+        return [];
+    const sub = prefix.stdout.trim(); // "" at the repo root, "apps/web/" in a subfolder
+    const r = spawnSync('git', ['status', '--porcelain', '-z', '--untracked-files=normal', '--', '.'], { cwd: root, encoding: 'utf8' });
+    if (r.status !== 0)
+        return [];
+    const out = [];
+    const parts = r.stdout.split('\0');
+    for (let i = 0; i < parts.length; i++) {
+        const entry = parts[i];
+        if (entry.length < 4)
+            continue;
+        const status = entry.slice(0, 2);
+        const path = entry.slice(3);
+        // A rename or copy is followed by its original path; skip that.
+        if (status[0] === 'R' || status[0] === 'C')
+            i++;
+        const rel = sub && path.startsWith(sub) ? path.slice(sub.length) : path;
+        if (rel === '.codz' || rel.startsWith('.codz/'))
+            continue;
+        out.push(rel);
+    }
+    return out;
+}