@emeryld/manager 0.3.3 → 0.4.1

package/README.md

@@ -1,44 +1,42 @@
 # @emeryld/manager
 
-Interactive release helper for pnpm monorepos. Install it as a local dev dependency, then run `pnpm manager-cli` (or call a `scripts.manager-cli` alias) from your workspace root to walk through selecting packages, running updates/tests/builds, and publishing.
-
-## Installation
-
-1. Ensure your workspace has a `packages/` directory (or configure one via `packages.mjs`).
-2. Add the manager to your dev dependencies so its CLI and helpers are hoisted into the consuming repo:
-   ```sh
-   pnpm add -D @emeryld/manager
-   ```
-3. Include a script in your `package.json` so you can invoke it consistently:
-   ```json
-   {
-     "scripts": {
-       "manager-cli": "manager-cli"
-     }
-   }
-   ```
-4. Run `pnpm install` to fetch `ts-node`, `semver`, and other runtime deps.
-
-## Running the CLI
-
-- Always run `pnpm manager-cli` (or `pnpm run manager-cli`) from the **workspace root** where your `packages/` folder lives. The manager operates against the workspace you are in, not the package that ships the tool.
-- Each TypeScript helper script registers the bundled `ts-node/esm` loader with the exact script path, so the CLI works even from pnpm workspaces that hoist dependencies.
-- To avoid the warning/error you saw earlier, make sure:
-  - the workspace has `packages/` (or a configured manifest) so `loadPackages()` can find targets,
-  - `pnpm install` has already written `ts-node` into `node_modules`,
-  - you execute the CLI from the workspace that owns those packages.
-
-## Testing the loader registration
-
-Run `pnpm test` to ensure the helper CLI always generates a `--import data:text...` snippet that registers `ts-node/esm.mjs` with **the actual script file path**. This guards against regressions that would make Node reject the loader and crash before the interactive menu appears.
-
-## Package creator variants
-
-Use `Create package` inside the CLI to scaffold a starter workspace package (the flow auto-installs deps and builds when a `build` script exists). Templates:
-
-- **rrr contract** – Shared RRRoutes registry and socket config for server/client packages. Exported registry lives in `src/index.ts`.
-- **rrr server** – Express + RRRoutes API wired to the contract placeholder, `dev` via ts-node, `.env.example` included.
-- **rrr client** – Backend-agnostic RRRoutes client helper with React Query setup in `src/index.ts`.
-- **empty package** – Minimal TypeScript library with build/typecheck scripts.
-- **dockerized service** – Express health API with Dockerfile, .dockerignore, and Docker helper scripts (`docker:build`, `docker:up`, `docker:logs`, `docker:stop`, `docker:clean`) powered by `docker-cli-js`.
-- **full stack service (api + web)** – Express API + Vite React client, unified build/start, Dockerfile + helper scripts (same `docker:*` commands as above).
+Dev dependency built for Codex agents: scaffold RRRoutes packages, read the generated structure, and ship changes without rebuilding boilerplate. Install it in a pnpm workspace and call `pnpm manager-cli` from the workspace root.
+
+## Quick start (agents)
+- Install: `pnpm add -D @emeryld/manager`
+- Add a script: `"manager-cli": "manager-cli"` in the workspace `package.json`
+- Discover templates fast: `pnpm manager-cli templates` (alias `pnpm manager-cli create --list`)
+- Scaffold without prompts:  
+  `pnpm manager-cli create --variant rrr-server --dir packages/api --name @scope/api --contract @scope/contract --skip-install`
+- Prefer prompts: `pnpm manager-cli create` and follow the menu
+- After scaffolding, open the new package `README.md` for variant-specific scripts and usage
+
+## Templates at a glance
+| id | default dir | summary | key files |
+| --- | --- | --- | --- |
+| rrr-contract | `packages/rrr-contract` | Shared RRRoutes contract + sockets for clients/servers | `src/index.ts`, `README.md` |
+| rrr-server | `packages/rrr-server` | Express + RRRoutes API wired to a contract import | `src/index.ts`, `.env.example`, `README.md` |
+| rrr-client | `packages/rrr-client` | React Query-ready RRRoutes client bound to a contract import | `src/index.ts`, `README.md` |
+| rrr-empty | `packages/rrr-empty` | Minimal TypeScript package with lint/format/test wiring | `src/index.ts`, `README.md` |
+| rrr-docker | `packages/rrr-docker` | Express service with Dockerfile + helper CLI | `src/index.ts`, `scripts/docker.ts`, `Dockerfile`, `README.md` |
+| rrr-fullstack | `rrrfull-stack` | pnpm workspace with contract, server, client, and docker helper | root `package.json`, `pnpm-workspace.yaml`, `packages/*` |
+
+Use `pnpm manager-cli create --describe <variant>` to print the scripts, key files, and notes for any template before scaffolding.
+
+## Create command reference
+- `pnpm manager-cli create --list` — show templates
+- `pnpm manager-cli create --describe rrr-server` — see scripts/files/notes for one template
+- `pnpm manager-cli create --variant rrr-client --dir packages/web-client --name @scope/web-client` — scaffold directly (adds `--contract <id>` for server/client)
+- `--skip-install` / `--skip-build` — bypass post-create steps when you want to install/build later
+
+## Release helper (existing packages)
+- Run from the workspace root where `packages/` lives.
+- `pnpm manager-cli` launches an interactive menu: pick packages, then run update → test → build → publish (or any single step).
+- Non-interactive publish: `pnpm manager-cli <pkg|all> --non-interactive --bump patch` (see CLI prompts for flags like `--sync` and `--tag`).
+
+## Notes
+- Each helper script registers the bundled `ts-node/esm` loader with the correct path so the CLI works even when dependencies are hoisted.
+- The create flow runs `pnpm install` and `pnpm run build` when a build script exists; skip with `--skip-install`/`--skip-build` if you want to control timing.
+
+## Tests
+- `pnpm test` verifies the helper CLI loader registration.

package/dist/create-package/index.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { stdin as input } from 'node:process';
 import { askLine, promptSingleKey } from '../prompts.js';
 import { colors, logGlobal } from '../utils/log.js';
-import { workspaceRoot } from './shared.js';
+import { SCRIPT_DESCRIPTIONS, workspaceRoot, } from './shared.js';
 import { clientVariant } from './variants/client.js';
 import { contractVariant } from './variants/contract.js';
 import { dockerVariant } from './variants/docker.js';
@@ -19,10 +19,122 @@ const VARIANTS = [
     dockerVariant,
     fullstackVariant,
 ];
+const VARIANT_LOOKUP = new Map(VARIANTS.map((variant) => [variant.id, variant]));
 function derivePackageName(targetDir) {
     const base = path.basename(targetDir) || 'rrr-package';
     return base;
 }
+function resolveVariant(key) {
+    if (!key)
+        return undefined;
+    const normalized = key.toLowerCase();
+    return (VARIANT_LOOKUP.get(normalized) ??
+        VARIANTS.find((variant) => {
+            const label = variant.label.toLowerCase();
+            const id = variant.id.toLowerCase();
+            return (id === normalized ||
+                id.replace(/^rrr-/, '') === normalized ||
+                label === normalized ||
+                label.includes(normalized));
+        }));
+}
+function printVariantList() {
+    logGlobal('Available templates', colors.magenta);
+    VARIANTS.forEach((variant) => {
+        const summary = variant.summary ? ` ${colors.dim(`– ${variant.summary}`)}` : '';
+        console.log(`- ${colors.green(variant.label)} ${colors.dim(`(${variant.id})`)} → ${colors.cyan(variant.defaultDir)}${summary}`);
+    });
+    console.log(colors.dim('Use "--describe <variant>" for details or "--variant <id> --dir <path>" to scaffold without prompts.'));
+}
+function printVariantDetails(variant) {
+    logGlobal(`${variant.label} (${variant.id})`, colors.green);
+    console.log(`  default dir: ${colors.cyan(variant.defaultDir)}`);
+    if (variant.summary) {
+        console.log(`  ${variant.summary}`);
+    }
+    if (variant.keyFiles?.length) {
+        console.log('  key files:');
+        variant.keyFiles.forEach((file) => console.log(`    - ${file}`));
+    }
+    if (variant.scripts?.length) {
+        console.log('  scripts:');
+        variant.scripts.forEach((script) => {
+            const desc = SCRIPT_DESCRIPTIONS[script];
+            const detail = desc ? colors.dim(` – ${desc}`) : '';
+            console.log(`    - ${script}${detail}`);
+        });
+    }
+    if (variant.notes?.length) {
+        console.log('  notes:');
+        variant.notes.forEach((note) => console.log(`    - ${note}`));
+    }
+}
+function parseCreateCliArgs(argv) {
+    const options = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--list' || arg === '-l' || arg === 'list' || arg === 'ls') {
+            options.list = true;
+            continue;
+        }
+        if (arg === '--describe' || arg === '-d' || arg === 'describe') {
+            options.describe = argv[++i];
+            continue;
+        }
+        if (arg === '--variant' || arg === '-v') {
+            options.variant = argv[++i];
+            continue;
+        }
+        if (arg === '--dir' || arg === '--path' || arg === '-p') {
+            options.targetDir = argv[++i];
+            continue;
+        }
+        if (arg === '--name' || arg === '-n') {
+            options.pkgName = argv[++i];
+            continue;
+        }
+        if (arg === '--contract') {
+            options.contractName = argv[++i];
+            continue;
+        }
+        if (arg === '--skip-install') {
+            options.skipInstall = true;
+            continue;
+        }
+        if (arg === '--skip-build') {
+            options.skipBuild = true;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            options.help = true;
+            continue;
+        }
+        if (!arg.startsWith('-') && !options.variant) {
+            options.variant = arg;
+        }
+    }
+    return options;
+}
+function printCreateHelp() {
+    logGlobal('Create package help', colors.magenta);
+    console.log('Usage:');
+    console.log('  pnpm manager-cli create                     # interactive prompts');
+    console.log('  pnpm manager-cli create --list              # list templates');
+    console.log('  pnpm manager-cli create --describe rrr-server');
+    console.log('  pnpm manager-cli create --variant rrr-client --dir packages/rrr-client --name @scope/client');
+    console.log('  pnpm manager-cli create --variant rrr-server --contract @scope/contract --skip-install');
+    console.log('');
+    console.log('Flags:');
+    console.log('  --list, -l          Show available templates');
+    console.log('  --describe, -d      Print details for a template');
+    console.log('  --variant, -v       Pick a template by id/label (skips variant prompt)');
+    console.log('  --dir, --path, -p   Target directory (skips path prompt)');
+    console.log('  --name, -n          Package name (skips name prompt)');
+    console.log('  --contract          Contract import to inject (server/client variants)');
+    console.log('  --skip-install      Do not run pnpm install after scaffolding');
+    console.log('  --skip-build        Skip build after scaffolding');
+    console.log('  --help, -h          Show this help');
+}
 async function ensureTargetDir(targetDir) {
     try {
         const stats = await stat(targetDir);
@@ -177,7 +289,11 @@ async function promptForTargetDir(fallback) {
     const normalized = answer || fallback;
     return path.resolve(workspaceRoot, normalized);
 }
-async function postCreateTasks(targetDir) {
+async function postCreateTasks(targetDir, options) {
+    if (options?.skipInstall) {
+        logGlobal('Skipping pnpm install (flag).', colors.dim);
+        return;
+    }
     try {
         logGlobal('Running pnpm install…', colors.cyan);
         await runCommand('pnpm', ['install'], workspaceRoot);
@@ -186,6 +302,10 @@ async function postCreateTasks(targetDir) {
         logGlobal(`pnpm install failed: ${error instanceof Error ? error.message : String(error)}`, colors.yellow);
         return;
     }
+    if (options?.skipBuild) {
+        logGlobal('Skipping build (flag).', colors.dim);
+        return;
+    }
     try {
         const pkgJsonPath = path.join(targetDir, 'package.json');
         const pkgRaw = await readFile(pkgJsonPath, 'utf8');
@@ -199,22 +319,69 @@ async function postCreateTasks(targetDir) {
         logGlobal(`Skipping build (could not read package.json): ${error instanceof Error ? error.message : String(error)}`, colors.yellow);
     }
 }
-async function gatherTarget() {
-    const variant = await promptForVariant();
-    const targetDir = await promptForTargetDir(variant.defaultDir);
+async function gatherTarget(initial = {}) {
+    const variant = initial.variant ?? (await promptForVariant());
+    const targetDir = initial.targetDir !== undefined
+        ? path.resolve(workspaceRoot, initial.targetDir)
+        : await promptForTargetDir(variant.defaultDir);
     const fallbackName = derivePackageName(targetDir);
-    const nameAnswer = await askLine(`Package name? (${fallbackName}): `);
+    const nameAnswer = initial.pkgName === undefined
+        ? await askLine(`Package name? (${fallbackName}): `)
+        : initial.pkgName;
     const pkgName = (nameAnswer || fallbackName).trim() || fallbackName;
     await ensureTargetDir(targetDir);
-    return { variant, targetDir, pkgName };
+    return {
+        variant,
+        targetDir,
+        pkgName,
+        contractName: initial.contractName,
+    };
 }
-export async function createRrrPackage() {
-    const target = await gatherTarget();
+export async function createRrrPackage(options = {}) {
+    const target = await gatherTarget(options);
     logGlobal(`Creating ${target.variant.label} in ${path.relative(workspaceRoot, target.targetDir) || '.'}`, colors.green);
     await target.variant.scaffold({
         targetDir: target.targetDir,
         pkgName: target.pkgName,
+        contractName: target.contractName ?? options.contractName,
+    });
+    await postCreateTasks(target.targetDir, {
+        skipInstall: options.skipInstall,
+        skipBuild: options.skipBuild ?? options.skipInstall,
     });
-    await postCreateTasks(target.targetDir);
     logGlobal('Scaffold complete. Install/build steps were attempted; ready to run!', colors.green);
 }
+export async function runCreatePackageCli(argv) {
+    const parsed = parseCreateCliArgs(argv);
+    if (parsed.help) {
+        printCreateHelp();
+        return;
+    }
+    if (parsed.list) {
+        printVariantList();
+        return;
+    }
+    if (parsed.describe) {
+        const variant = resolveVariant(parsed.describe);
+        if (!variant) {
+            throw new Error(`Unknown variant "${parsed.describe}". Use --list to see available templates.`);
+        }
+        printVariantDetails(variant);
+        return;
+    }
+    const variant = resolveVariant(parsed.variant);
+    if (parsed.variant && !variant) {
+        throw new Error(`Unknown variant "${parsed.variant}". Use --list to see available templates.`);
+    }
+    const targetDir = parsed.targetDir
+        ? path.resolve(workspaceRoot, parsed.targetDir)
+        : undefined;
+    await createRrrPackage({
+        variant,
+        targetDir,
+        pkgName: parsed.pkgName,
+        contractName: parsed.contractName,
+        skipInstall: parsed.skipInstall,
+        skipBuild: parsed.skipBuild ?? parsed.skipInstall,
+    });
+}

package/dist/create-package/shared.js

@@ -40,5 +40,188 @@ export function baseTsConfig(options) {
             jsx: options?.jsx,
         },
         include: options?.include ?? ['src/**/*'],
+        exclude: options?.exclude ?? ['dist', 'node_modules'],
     }, null, 2)}\n`;
 }
+export function baseEslintConfig(tsconfigPath = './tsconfig.json') {
+    return `import tseslint from 'typescript-eslint'
+import prettierPlugin from 'eslint-plugin-prettier'
+
+export default tseslint.config(
+  { ignores: ['dist', 'node_modules'] },
+  ...tseslint.configs.recommendedTypeChecked,
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      parserOptions: {
+        project: ${JSON.stringify(tsconfigPath)},
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    plugins: {
+      prettier: prettierPlugin,
+    },
+    rules: {
+      'prettier/prettier': 'error',
+      '@typescript-eslint/consistent-type-imports': 'warn',
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^ignore' },
+      ],
+    },
+  },
+)
+`;
+}
+export function basePrettierConfig() {
+    return `export default {
+  singleQuote: true,
+  semi: false,
+  trailingComma: 'all',
+  printWidth: 100,
+}
+`;
+}
+export const PRETTIER_IGNORE = ['node_modules', 'dist', '.turbo', 'coverage', '*.log'].join('\n');
+export const LINT_STAGED_CONFIG = {
+    '*.{ts,tsx}': ['eslint --fix'],
+    '*.{ts,tsx,js,jsx,json,md,css,html}': ['prettier --write'],
+};
+export const HUSKY_PRE_COMMIT = `#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm lint-staged
+`;
+export function vscodeSettings() {
+    return `${JSON.stringify({
+        'editor.defaultFormatter': 'esbenp.prettier-vscode',
+        'editor.formatOnSave': true,
+        'editor.codeActionsOnSave': {
+            'source.fixAll.eslint': true,
+        },
+        'eslint.useFlatConfig': true,
+        'eslint.validate': ['typescript', 'javascript'],
+        'files.eol': '\n',
+        'prettier.requireConfig': true,
+    }, null, 2)}\n`;
+}
+export const BASE_LINT_DEV_DEPENDENCIES = {
+    typescript: '^5.9.3',
+    eslint: '^9.12.0',
+    'eslint-plugin-prettier': '^5.2.1',
+    prettier: '^3.3.3',
+    'typescript-eslint': '^8.10.0',
+    rimraf: '^6.0.1',
+    tsx: '^4.19.0',
+    husky: '^9.1.6',
+    'lint-staged': '^15.2.10',
+    '@emeryld/manager': 'latest',
+};
+const DEFAULT_GITIGNORE_ENTRIES = [
+    'node_modules',
+    'dist',
+    '.turbo',
+    '.DS_Store',
+    '.env',
+    'coverage',
+    '*.log',
+];
+export function gitignoreFrom(entries = DEFAULT_GITIGNORE_ENTRIES) {
+    return entries.join('\n');
+}
+export function baseScripts(devCommand, extras) {
+    return {
+        dev: devCommand,
+        build: 'tsc -p tsconfig.json',
+        typecheck: 'tsc -p tsconfig.json --noEmit',
+        lint: 'eslint . --max-warnings=0',
+        'lint:fix': 'eslint . --fix',
+        'lint-staged': 'lint-staged',
+        format: 'prettier . --write',
+        'format:check': 'prettier . --check',
+        clean: 'rimraf dist .turbo coverage',
+        test: "node -e \"console.log('No tests yet')\"",
+        prepare: 'husky install || true',
+        ...extras,
+    };
+}
+export function basePackageFiles(options) {
+    return {
+        'eslint.config.js': baseEslintConfig(options?.tsconfigPath),
+        'prettier.config.js': basePrettierConfig(),
+        '.prettierignore': `${PRETTIER_IGNORE}\n`,
+        '.vscode/settings.json': vscodeSettings(),
+        '.husky/pre-commit': HUSKY_PRE_COMMIT,
+        '.gitignore': gitignoreFrom(options?.gitignoreEntries),
+    };
+}
+export const SCRIPT_DESCRIPTIONS = {
+    dev: 'Watch and rebuild on change',
+    build: 'Type-check and emit to dist/',
+    typecheck: 'Type-check only (no emit)',
+    lint: 'Run ESLint with flat config',
+    'lint:fix': 'Fix lint issues automatically',
+    'lint-staged': 'Run lint/format on staged files',
+    format: 'Format code with Prettier',
+    'format:check': 'Check formatting without writing',
+    clean: 'Remove build artifacts and caches',
+    test: 'Placeholder test script',
+    start: 'Run the built output',
+    'docker:build': 'Build docker image',
+    'docker:up': 'Build and start container',
+    'docker:dev': 'Build, start, and tail logs',
+    'docker:logs': 'Tail docker logs',
+    'docker:stop': 'Stop running container',
+    'docker:clean': 'Stop and remove container',
+    'docker:reset': 'Remove container and image',
+};
+export function buildReadme(options) {
+    const scripts = options.scripts ?? [];
+    const scriptLines = scripts.map((script) => {
+        const desc = SCRIPT_DESCRIPTIONS[script];
+        return desc ? `- \`npm run ${script}\` - ${desc}` : `- \`npm run ${script}\``;
+    });
+    const sections = [...(options.sections ?? [])];
+    if (scriptLines.length > 0) {
+        sections.push({ title: 'Scripts', lines: scriptLines });
+    }
+    const lines = [`# ${options.name}`, ''];
+    if (options.description) {
+        lines.push(options.description, '');
+    }
+    sections.forEach((section) => {
+        lines.push(`## ${section.title}`, ...section.lines, '');
+    });
+    return `${lines.join('\n').trim()}\n`;
+}
+function stripUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, value]) => value !== undefined));
+}
+export function basePackageJson(options) {
+    const applyDefaults = options.useDefaults ?? true;
+    const pkg = stripUndefined({
+        name: options.name,
+        version: options.version ?? '0.1.0',
+        private: options.private ?? true,
+        ...(applyDefaults
+            ? {
+                type: options.type ?? 'module',
+                main: options.main ?? 'dist/index.js',
+                types: options.types ?? 'dist/index.d.ts',
+                files: options.files ?? ['dist'],
+            }
+            : stripUndefined({
+                type: options.type,
+                main: options.main,
+                types: options.types,
+                files: options.files,
+            })),
+        exports: options.exports,
+        scripts: options.scripts,
+        dependencies: options.dependencies,
+        devDependencies: options.devDependencies,
+        'lint-staged': LINT_STAGED_CONFIG,
+        ...options.extraFields,
+    });
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}

package/dist/create-package/variants/client.js

@@ -1,6 +1,17 @@
-import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+import { BASE_LINT_DEV_DEPENDENCIES, basePackageFiles, basePackageJson, buildReadme, baseScripts, baseTsConfig, writeFileIfMissing, } from '../shared.js';
+const CLIENT_SCRIPTS = [
+    'dev',
+    'build',
+    'typecheck',
+    'lint',
+    'lint:fix',
+    'format',
+    'format:check',
+    'clean',
+    'test',
+];
 const CONTRACT_IMPORT_PLACEHOLDER = '@your-scope/contract';
-function clientIndexTs(contractImport) {
+export function clientIndexTs(contractImport) {
     return `import { QueryClient } from '@tanstack/react-query'
 import { createRouteClient } from '@emeryld/rrroutes-client'
 import { registry } from '${contractImport}'
@@ -18,50 +29,70 @@ export const healthGet = routeClient.build(registry.byKey['GET /api/health'])
 export const healthPost = routeClient.build(registry.byKey['POST /api/health'])
 `;
 }
-function clientPackageJson(name) {
-    return `${JSON.stringify({
+export function clientPackageJson(name, contractName = CONTRACT_IMPORT_PLACEHOLDER) {
+    return basePackageJson({
         name,
-        version: '0.1.0',
-        private: true,
-        type: 'module',
-        main: 'dist/index.js',
-        types: 'dist/index.d.ts',
-        files: ['dist'],
-        scripts: {
-            build: 'tsc -p tsconfig.json',
-            typecheck: 'tsc -p tsconfig.json --noEmit',
-        },
+        scripts: baseScripts('tsx watch src/index.ts'),
         dependencies: {
+            [contractName]: 'workspace:*',
             '@emeryld/rrroutes-client': '^2.5.3',
-            '@emeryld/rrroutes-contract': '^2.5.2',
             '@tanstack/react-query': '^5.90.12',
             'socket.io-client': '^4.8.3',
         },
         devDependencies: {
+            ...BASE_LINT_DEV_DEPENDENCIES,
             '@types/node': '^24.10.2',
-            typescript: '^5.9.3',
         },
-    }, null, 2)}\n`;
+    });
 }
 function clientFiles(pkgName, contractImport) {
     return {
-        'package.json': clientPackageJson(pkgName),
+        'package.json': clientPackageJson(pkgName, contractImport),
         'tsconfig.json': baseTsConfig({ lib: ['ES2020', 'DOM'], types: ['node'] }),
+        ...basePackageFiles(),
         'src/index.ts': clientIndexTs(contractImport),
-        'README.md': `# ${pkgName}
-
-Starter RRRoutes client scaffold.
-- update the contract import in src/index.ts if needed (${contractImport})
-- the generated QueryClient is exported from src/index.ts
-`,
+        'README.md': buildReadme({
+            name: pkgName,
+            description: 'Starter RRRoutes client scaffold.',
+            scripts: CLIENT_SCRIPTS,
+            sections: [
+                {
+                    title: 'Getting Started',
+                    lines: [
+                        '- Install deps: `npm install` (or `pnpm install`)',
+                        '- Start dev mode: `npm run dev`',
+                        '- Build output: `npm run build`',
+                    ],
+                },
+                {
+                    title: 'Usage',
+                    lines: [
+                        `- Update the contract import in \`src/index.ts\` if needed (${contractImport}).`,
+                        '- Use the exported `queryClient` and built route clients from `src/index.ts`.',
+                    ],
+                },
+                {
+                    title: 'Environment',
+                    lines: ['- `RRR_API_URL` (optional) sets the API base URL (default http://localhost:4000).'],
+                },
+            ],
+        }),
     };
 }
 export const clientVariant = {
     id: 'rrr-client',
     label: 'rrr client',
     defaultDir: 'packages/rrr-client',
+    summary: 'React Query-ready RRRoutes client bound to a shared contract import.',
+    keyFiles: ['src/index.ts', 'README.md'],
+    scripts: CLIENT_SCRIPTS,
+    notes: [
+        'Set the contract import via --contract or by editing src/index.ts.',
+        'Exports query client + typed route builders to plug into React apps.',
+    ],
     async scaffold(ctx) {
-        const files = clientFiles(ctx.pkgName, CONTRACT_IMPORT_PLACEHOLDER);
+        const contractImport = ctx.contractName ?? CONTRACT_IMPORT_PLACEHOLDER;
+        const files = clientFiles(ctx.pkgName, contractImport);
         for (const [relative, contents] of Object.entries(files)) {
             // eslint-disable-next-line no-await-in-loop
             await writeFileIfMissing(ctx.targetDir, relative, contents);