@emeryld/manager 0.3.3 → 0.4.0

package/README.md

@@ -32,13 +32,27 @@ Interactive release helper for pnpm monorepos. Install it as a local dev depende
 
 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).
+## Package creator overview
+
+Use `Create package` inside the CLI to scaffold starter packages. The flow will prompt for a variant, target path, and package name, then generate the files and attempt `pnpm install` and `pnpm run build` when a build script exists.
+
+### How to scaffold
+- From the workspace root, run `pnpm manager-cli` → choose `Create package`.
+- Pick a variant, confirm the target directory, and override the package name if desired.
+- After scaffolding, the new package’s README covers variant-specific details and scripts.
+
+### Variant quick view
+
+| Variant | Default dir | Purpose | Key scripts |
+| --- | --- | --- | --- |
+| rrr contract | `packages/rrr-contract` | Shared RRRoutes contract registry and socket config | `dev`, `build`, `typecheck`, `lint`, `format` |
+| rrr server | `packages/rrr-server` | Express + RRRoutes API wired to a contract import | `dev`, `build`, `start`, `lint`, `format` |
+| rrr client | `packages/rrr-client` | RRRoutes client helpers + React Query setup | `dev`, `build`, `lint`, `format` |
+| empty package | `packages/rrr-empty` | Minimal TypeScript starter | `dev`, `build`, `lint`, `format` |
+| dockerized service | `packages/rrr-docker` | Express service with Dockerfile and helper CLI | `dev`, `build`, `start`, `docker:*` |
+| full stack stack | `rrrfull-stack` | Workspace with contract + server + client + docker | `dev`, `build`, `lint`, `docker:*` (root scripts orchestrate) |
+
+### Common scripts and helpers
+- `dev` (watch), `build`, `typecheck`, `lint`/`lint:fix`, `format`/`format:check`, `clean`, `test` are scaffolded where relevant.
+- Docker-focused variants expose `docker:build`, `docker:up`, `docker:dev`, `docker:logs`, `docker:stop`, `docker:clean`, `docker:reset`.
+- Husky + lint-staged and ESLint/Prettier configs are included in every package for consistent DX.

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),
+    };
+}
+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,6 @@
-import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+import { BASE_LINT_DEV_DEPENDENCIES, basePackageFiles, basePackageJson, buildReadme, baseScripts, baseTsConfig, writeFileIfMissing, } from '../shared.js';
 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,42 +18,65 @@ 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) {
+    const scriptsForReadme = [
+        'dev',
+        'build',
+        'typecheck',
+        'lint',
+        'lint:fix',
+        'format',
+        'format:check',
+        'clean',
+        'test',
+    ];
     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: scriptsForReadme,
+            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 = {
@@ -61,7 +84,8 @@ export const clientVariant = {
     label: 'rrr client',
     defaultDir: 'packages/rrr-client',
     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);

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

@@ -1,5 +1,5 @@
-import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
-const CONTRACT_TS = `import { defineSocketEvents, finalize, resource } from '@emeryld/rrroutes-contract'
+import { BASE_LINT_DEV_DEPENDENCIES, basePackageFiles, basePackageJson, buildReadme, baseScripts, baseTsConfig, writeFileIfMissing, } from '../shared.js';
+export const CONTRACT_TS = `import { defineSocketEvents, finalize, resource } from '@emeryld/rrroutes-contract'
 import { z } from 'zod'
 
 const routes = resource('/api')
@@ -70,45 +70,64 @@ export const socketEvents = sockets.events
 export type AppRegistry = typeof registry
 `;
 function contractPackageJson(name) {
-    return `${JSON.stringify({
+    return basePackageJson({
         name,
-        version: '0.1.0',
         private: false,
-        type: 'module',
-        main: 'dist/index.js',
-        types: 'dist/index.d.ts',
         exports: {
             '.': {
                 types: './dist/index.d.ts',
                 import: './dist/index.js',
             },
         },
-        files: ['dist'],
-        scripts: {
-            build: 'tsc -p tsconfig.json',
-            typecheck: 'tsc -p tsconfig.json --noEmit',
-        },
+        scripts: baseScripts('tsx watch src/index.ts'),
         dependencies: {
             '@emeryld/rrroutes-contract': '^2.5.2',
             zod: '^4.2.1',
         },
         devDependencies: {
-            typescript: '^5.9.3',
+            ...BASE_LINT_DEV_DEPENDENCIES,
         },
-    }, null, 2)}\n`;
+    });
 }
 function contractFiles(pkgName) {
+    const scriptsForReadme = [
+        'dev',
+        'build',
+        'typecheck',
+        'lint',
+        'lint:fix',
+        'format',
+        'format:check',
+        'clean',
+        'test',
+    ];
     return {
         'package.json': contractPackageJson(pkgName),
         'tsconfig.json': baseTsConfig(),
+        ...basePackageFiles(),
         'src/index.ts': CONTRACT_TS,
-        'README.md': `# ${pkgName}
-
-Contract package scaffolded by manager-cli.
-- edit src/index.ts to add routes and socket events
-- build with \`npm run build\`
-- import the registry in your server/client packages
-`,
+        'README.md': buildReadme({
+            name: pkgName,
+            description: 'Contract package scaffolded by manager-cli.',
+            scripts: scriptsForReadme,
+            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: [
+                        '- Edit `src/index.ts` to add routes and socket events.',
+                        '- Import and share the generated registry in server/client packages.',
+                    ],
+                },
+            ],
+        }),
     };
 }
 export const contractVariant = {

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

@@ -1,38 +1,30 @@
-import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+import { BASE_LINT_DEV_DEPENDENCIES, basePackageFiles, basePackageJson, buildReadme, baseScripts, baseTsConfig, writeFileIfMissing, } from '../shared.js';
 function dockerPackageJson(name) {
-    return `${JSON.stringify({
+    return basePackageJson({
         name,
-        version: '0.1.0',
-        private: true,
-        type: 'module',
-        main: 'dist/index.js',
-        types: 'dist/index.d.ts',
-        files: ['dist'],
-        scripts: {
-            dev: 'tsx watch src/index.ts',
-            build: 'tsc -p tsconfig.json',
-            typecheck: 'tsc -p tsconfig.json --noEmit',
+        scripts: baseScripts('tsx watch src/index.ts', {
             start: 'node dist/index.js',
             'docker:cli': 'tsx scripts/docker.ts',
             'docker:build': 'npm run docker:cli -- build',
             'docker:up': 'npm run docker:cli -- up',
+            'docker:dev': 'npm run docker:cli -- dev',
             'docker:logs': 'npm run docker:cli -- logs',
             'docker:stop': 'npm run docker:cli -- stop',
             'docker:clean': 'npm run docker:cli -- clean',
-        },
+            'docker:reset': 'npm run docker:cli -- reset',
+        }),
         dependencies: {
             cors: '^2.8.5',
             express: '^5.1.0',
         },
         devDependencies: {
+            ...BASE_LINT_DEV_DEPENDENCIES,
             '@types/cors': '^2.8.5',
             '@types/express': '^5.0.6',
             '@types/node': '^24.10.2',
             'docker-cli-js': '^3.0.9',
-            tsx: '^4.19.0',
-            typescript: '^5.9.3',
         },
-    }, null, 2)}\n`;
+    });
 }
 function dockerIndexTs() {
     return `import express from 'express'
@@ -85,20 +77,65 @@ CMD ["node", "dist/index.js"]
 `;
 }
 function dockerFiles(pkgName) {
+    const scriptsForReadme = [
+        'dev',
+        'build',
+        'typecheck',
+        'lint',
+        'lint:fix',
+        'format',
+        'format:check',
+        'clean',
+        'test',
+        'start',
+        'docker:build',
+        'docker:up',
+        'docker:dev',
+        'docker:logs',
+        'docker:stop',
+        'docker:clean',
+        'docker:reset',
+    ];
     return {
         'package.json': dockerPackageJson(pkgName),
         'tsconfig.json': baseTsConfig({ types: ['node'] }),
         'src/index.ts': dockerIndexTs(),
         'scripts/docker.ts': dockerCliScript(pkgName),
         '.dockerignore': DOCKER_DOCKERIGNORE,
+        ...basePackageFiles(),
         Dockerfile: dockerDockerfile(),
-        'README.md': `# ${pkgName}
-
-Dockerized service scaffolded by manager-cli.
-- develop locally with \`npm run dev\`
-- build with \`npm run build\` and start with \`npm start\`
-- docker helper: \`npm run docker:up\` (build + run), \`npm run docker:logs\`, \`npm run docker:stop\`
-`,
+        'README.md': buildReadme({
+            name: pkgName,
+            description: 'Dockerized service scaffolded by manager-cli.',
+            scripts: scriptsForReadme,
+            sections: [
+                {
+                    title: 'Getting Started',
+                    lines: [
+                        '- Install deps: `npm install` (or `pnpm install`)',
+                        '- Local dev: `npm run dev`',
+                        '- Build output: `npm run build`',
+                        '- Start built app: `npm start`',
+                    ],
+                },
+                {
+                    title: 'Docker Helpers',
+                    lines: [
+                        '- Build image: `npm run docker:build`',
+                        '- Build + run detached: `npm run docker:up`',
+                        '- Build + run + tail logs: `npm run docker:dev`',
+                        '- Tail logs: `npm run docker:logs`',
+                        '- Stop container: `npm run docker:stop`',
+                        '- Clean container: `npm run docker:clean`',
+                        '- Reset container/image: `npm run docker:reset`',
+                    ],
+                },
+                {
+                    title: 'Environment',
+                    lines: ['- `PORT` sets the exposed port (default 3000).'],
+                },
+            ],
+        }),
     };
 }
 function dockerCliScript(pkgName) {
@@ -126,32 +163,50 @@ async function main() {
     await docker.command(\`build -t \${image} .\`)
     return docker.command(\`run -d --rm -p \${port}:\${port} --name \${container} \${image}\`)
   }
+  if (command === 'dev') {
+    await docker.command(\`build -t \${image} .\`)
+    await docker.command(\`run -d --rm -p \${port}:\${port} --name \${container} \${image}\`)
+    return docker.command(\`logs -f \${container}\`)
+  }
   if (command === 'run') {
     return docker.command(\`run -d --rm -p \${port}:\${port} --name \${container} \${image}\`)
   }
   if (command === 'logs') return docker.command(\`logs -f \${container}\`)
   if (command === 'stop') return docker.command(\`stop \${container}\`)
   if (command === 'clean') {
-    try {
-      await docker.command(\`rm -f \${container}\`)
-    } catch (error) {
-      console.warn(String(error))
-    }
+    await safe(() => docker.command(\`stop \${container}\`))
+    await safe(() => docker.command(\`rm -f \${container}\`))
+    return
+  }
+  if (command === 'reset') {
+    await safe(() => docker.command(\`stop \${container}\`))
+    await safe(() => docker.command(\`rm -f \${container}\`))
+    await safe(() => docker.command(\`rmi -f \${image}\`))
     return
   }
   return printHelp()
 }
 
+async function safe(run: () => Promise<unknown>) {
+  try {
+    await run()
+  } catch (error) {
+    console.warn(String(error))
+  }
+}
+
 function printHelp() {
   console.log(
     [
       'Docker helper commands:',
       '  build   -> docker build -t ${pkgName}:latest .',
       '  up      -> build then run in detached mode',
+      '  dev     -> build, run, and tail logs',
       '  run     -> run existing image detached',
       '  logs    -> docker logs -f <container>',
       '  stop    -> docker stop <container>',
-      '  clean   -> docker rm -f <container>',
+      '  clean   -> docker stop/rm <container>',
+      '  reset   -> clean container and remove image',
     ].join('\\n'),
   )
 }

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

@@ -1,33 +1,49 @@
-import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+import { BASE_LINT_DEV_DEPENDENCIES, basePackageFiles, basePackageJson, buildReadme, baseScripts, baseTsConfig, writeFileIfMissing, } from '../shared.js';
 function emptyPackageJson(name) {
-    return `${JSON.stringify({
+    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'),
         devDependencies: {
-            typescript: '^5.9.3',
+            ...BASE_LINT_DEV_DEPENDENCIES,
         },
-    }, null, 2)}\n`;
+    });
 }
 function emptyFiles(pkgName) {
+    const scriptsForReadme = [
+        'dev',
+        'build',
+        'typecheck',
+        'lint',
+        'lint:fix',
+        'format',
+        'format:check',
+        'clean',
+        'test',
+    ];
     return {
         'package.json': emptyPackageJson(pkgName),
         'tsconfig.json': baseTsConfig({ types: ['node'] }),
+        ...basePackageFiles(),
         'src/index.ts': "export const hello = 'world'\n",
-        'README.md': `# ${pkgName}
-
-Empty package scaffolded by manager-cli.
-- edit src/index.ts to start coding
-- build with \`npm run build\`
-`,
+        'README.md': buildReadme({
+            name: pkgName,
+            description: 'Empty package scaffolded by manager-cli.',
+            scripts: scriptsForReadme,
+            sections: [
+                {
+                    title: 'Getting Started',
+                    lines: [
+                        '- Install deps: `npm install` (or `pnpm install`)',
+                        '- Start dev mode: `npm run dev`',
+                        '- Build output: `npm run build`',
+                    ],
+                },
+                {
+                    title: 'Notes',
+                    lines: ['- Edit `src/index.ts` to start coding.'],
+                },
+            ],
+        }),
     };
 }
 export const emptyVariant = {

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

@@ -1,219 +1,65 @@
-import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
-function fullstackPackageJson(name) {
-    return `${JSON.stringify({
-        name,
-        version: '0.1.0',
+import path from 'node:path';
+import { BASE_LINT_DEV_DEPENDENCIES, basePackageFiles, basePackageJson, baseTsConfig, writeFileIfMissing, } from '../shared.js';
+import { clientVariant } from './client.js';
+import { serverVariant } from './server.js';
+import { dockerVariant } from './docker.js';
+import { contractVariant } from './contract.js';
+function deriveNames(baseName) {
+    const normalized = baseName.trim();
+    return {
+        contract: `@${normalized}/contract`,
+        server: `@${normalized}/server`,
+        client: `@${normalized}/client`,
+        docker: `${normalized}-docker`,
+    };
+}
+function deriveDirs(rootDir, baseName) {
+    const packagesRoot = path.join(rootDir, 'packages');
+    return {
+        root: rootDir,
+        packagesRoot,
+        contract: path.join(packagesRoot, `${baseName}-contract`),
+        server: path.join(packagesRoot, `${baseName}-server`),
+        client: path.join(packagesRoot, `${baseName}-client`),
+        docker: path.join(packagesRoot, `${baseName}-docker`),
+    };
+}
+function rootPackageJson(baseName) {
+    const dockerPackageDir = `packages/${baseName}-docker`;
+    return basePackageJson({
+        name: `${baseName}-stack`,
         private: true,
-        type: 'module',
-        main: 'dist/server/index.js',
-        files: ['dist'],
+        useDefaults: false,
         scripts: {
-            dev: 'concurrently "npm:dev:server" "npm:dev:client"',
-            'dev:server': 'tsx watch src/server/index.ts',
-            'dev:client': 'vite --host --port 5173',
-            build: 'npm run build:server && npm run build:client',
-            'build:server': 'tsc -p tsconfig.server.json',
-            'build:client': 'vite build',
-            start: 'node dist/server/index.js',
-            typecheck: 'tsc -p tsconfig.json --noEmit',
-            'docker:cli': 'tsx scripts/docker.ts',
-            'docker:build': 'npm run docker:cli -- build',
-            'docker:up': 'npm run docker:cli -- up',
-            'docker:logs': 'npm run docker:cli -- logs',
-            'docker:stop': 'npm run docker:cli -- stop',
-            'docker:clean': 'npm run docker:cli -- clean',
-            'db:up': 'docker compose up -d db',
-            'db:down': 'docker compose down',
-        },
-        dependencies: {
-            '@emeryld/rrroutes-client': '^2.5.3',
-            '@emeryld/rrroutes-contract': '^2.5.2',
-            '@emeryld/rrroutes-server': '^2.4.1',
-            '@tanstack/react-query': '^5.90.12',
-            cors: '^2.8.5',
-            express: '^5.1.0',
-            pg: '^8.13.1',
-            react: '^18.3.1',
-            'react-dom': '^18.3.1',
-            zod: '^4.2.1',
+            setup: 'pnpm install && pnpm exec husky install',
+            dev: 'pnpm -r dev --parallel --if-present',
+            build: 'pnpm -r build',
+            typecheck: 'pnpm -r typecheck',
+            lint: 'pnpm -r lint --if-present',
+            'lint:fix': 'pnpm -r lint:fix --if-present',
+            'lint-staged': 'lint-staged',
+            format: 'pnpm -r format --if-present',
+            'format:check': 'pnpm -r format:check --if-present',
+            test: 'pnpm -r test --if-present',
+            clean: 'pnpm -r clean --if-present && rimraf node_modules .turbo coverage',
+            prepare: 'husky install || true',
+            'docker:up': `pnpm -C ${dockerPackageDir} run docker:up`,
+            'docker:dev': `pnpm -C ${dockerPackageDir} run docker:dev`,
+            'docker:logs': `pnpm -C ${dockerPackageDir} run docker:logs`,
+            'docker:stop': `pnpm -C ${dockerPackageDir} run docker:stop`,
+            'docker:reset': `pnpm -C ${dockerPackageDir} run docker:reset`,
         },
-        devDependencies: {
-            '@types/express': '^5.0.6',
-            '@types/node': '^24.10.2',
-            '@types/react': '^18.3.27',
-            '@types/react-dom': '^18.3.7',
-            '@types/pg': '^8.11.10',
-            '@vitejs/plugin-react': '^4.3.4',
-            concurrently: '^8.2.0',
-            'docker-cli-js': '^3.0.9',
-            tsx: '^4.19.0',
-            typescript: '^5.9.3',
-            vite: '^6.4.1',
+        devDependencies: { ...BASE_LINT_DEV_DEPENDENCIES },
+        extraFields: {
+            workspaces: ['packages/*'],
         },
-    }, null, 2)}\n`;
+    });
 }
-function fullstackServerIndexTs() {
-    return `import { existsSync } from 'node:fs'
-import path from 'node:path'
-import express from 'express'
-import cors from 'cors'
-import { Pool } from 'pg'
-import { createRRRoute } from '@emeryld/rrroutes-server'
-import { registry } from '../contract/index.js'
-
-const app = express()
-app.use(cors({ origin: '*' }))
-app.use(express.json())
-
-const pool = new Pool({
-  connectionString:
-    process.env.DATABASE_URL ??
-    'postgresql://postgres:postgres@localhost:5432/rrroutes',
-})
-
-const routes = createRRRoute(app, {
-  buildCtx: async () => ({
-    requestId: Math.random().toString(36).slice(2),
-  }),
-  debug:
-    process.env.NODE_ENV === 'development'
-      ? { request: true, handler: true }
-      : undefined,
-})
-
-routes.registerControllers(registry, {
-  'GET /api/health': {
-    handler: async () => {
-      let db = 'skipped'
-      try {
-        await pool.query('select 1')
-        db = 'ok'
-      } catch (error) {
-        db = 'error: ' + String(error)
-      }
-      return {
-        out: {
-          status: 'ok',
-          at: new Date().toISOString(),
-          db,
-        },
-      }
-    },
-  },
-})
-
-const clientDir = path.resolve(__dirname, '../client')
-if (existsSync(clientDir)) {
-  app.use(express.static(clientDir))
-  app.get('*', (_req, res) => {
-    res.sendFile(path.join(clientDir, 'index.html'))
-  })
-} else {
-  console.warn('Client bundle missing; run "npm run build:client" to enable static assets.')
-}
-
-const PORT = Number.parseInt(process.env.PORT ?? '8080', 10)
-
-app.listen(PORT, () => {
-  console.log(\`Full stack service running on http://localhost:\${PORT}\`)
-})
-`;
-}
-const FULLSTACK_APP_TSX = `import React from 'react'
-import { QueryClientProvider } from '@tanstack/react-query'
-import { queryClient, healthGet } from './client/api'
-
-function HealthCard() {
-  const health = healthGet.useEndpoint()
-  return (
-    <section
-      style={{
-        background: '#fff',
-        padding: 16,
-        borderRadius: 12,
-        boxShadow: '0 8px 24px rgba(12, 18, 32, 0.05)',
-        border: '1px solid #e5e7eb',
-      }}
-    >
-      <h2>Health</h2>
-      <button onClick={() => health.refetch()}>Ping API</button>
-      <pre style={{ whiteSpace: 'pre-wrap' }}>
-        {JSON.stringify(health.data ?? { note: 'Waiting for request...' }, null, 2)}
-      </pre>
-    </section>
-  )
-}
-
-export function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <main style={{ fontFamily: 'Inter, system-ui, sans-serif', padding: 24 }}>
-        <h1>Full stack service</h1>
-        <p>
-          Contract-driven API + Vite client. Health endpoint uses RRRoutes and checks the
-          Postgres connection.
-        </p>
-        <p>Edit <code>src/contract/index.ts</code> or <code>src/server/index.ts</code> to extend the API.</p>
-        <HealthCard />
-      </main>
-    </QueryClientProvider>
-  )
-}
-`;
-const FULLSTACK_MAIN_TSX = `import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { App } from './App'
-import './styles.css'
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>,
-)
-`;
-const FULLSTACK_STYLES = `:root {
-  background: radial-gradient(circle at 20% 20%, #eef2ff, #f7f8fb 45%);
-  color: #0b1021;
-}
-
-body {
-  margin: 0;
-}
-`;
-const FULLSTACK_INDEX_HTML = `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Full stack service</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/client/main.tsx"></script>
-  </body>
-</html>
-`;
-function fullstackViteConfig() {
-    return `import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-
-export default defineConfig({
-  plugins: [react()],
-  build: {
-    outDir: 'dist/client',
-  },
-})
-`;
+function rootPnpmWorkspace() {
+    return "packages:\n  - 'packages/*'\n";
 }
-const FULLSTACK_DOCKERIGNORE = `node_modules
-dist
-.git
-.env
-npm-debug.log*
-pnpm-lock.yaml
-yarn.lock
-`;
-const FULLSTACK_DOCKER_COMPOSE = `services:
+function stackComposeYaml() {
+    return `services:
   db:
     image: postgres:15
     restart: unless-stopped
@@ -229,211 +75,55 @@ const FULLSTACK_DOCKER_COMPOSE = `services:
 volumes:
   db-data:
 `;
-function fullstackDockerfile() {
-    return `FROM node:20-slim AS builder
-WORKDIR /app
-
-COPY package*.json ./
-COPY pnpm-lock.yaml* ./
-RUN npm install
-
-COPY . .
-RUN npm run build
-
-FROM node:20-slim AS runner
-WORKDIR /app
-ENV NODE_ENV=production
-
-COPY --from=builder /app/package*.json ./
-COPY --from=builder /app/node_modules ./node_modules
-COPY --from=builder /app/dist ./dist
-RUN npm prune --omit=dev || true
-
-EXPOSE 8080
-CMD ["node", "dist/server/index.js"]
-`;
 }
-function fullstackFiles(pkgName) {
-    return {
-        'package.json': fullstackPackageJson(pkgName),
+async function scaffoldRootFiles(baseDir, baseName) {
+    const files = {
+        'package.json': rootPackageJson(baseName),
+        'pnpm-workspace.yaml': rootPnpmWorkspace(),
+        'docker-compose.yml': stackComposeYaml(),
         'tsconfig.json': baseTsConfig({
-            lib: ['ES2020', 'DOM'],
-            types: ['node'],
-            jsx: 'react-jsx',
-            include: ['src/**/*', 'vite.config.ts'],
-        }),
-        'tsconfig.server.json': baseTsConfig({
-            types: ['node'],
-            rootDir: 'src',
+            rootDir: '.',
             outDir: 'dist',
-            include: ['src/server/**/*', 'src/contract/**/*'],
+            include: ['packages/**/*', 'scripts/**/*', 'src/**/*'],
         }),
-        'vite.config.ts': fullstackViteConfig(),
-        'src/contract/index.ts': fullstackContractTs(),
-        'src/server/index.ts': fullstackServerIndexTs(),
-        'src/server/env.d.ts': "declare namespace NodeJS { interface ProcessEnv { DATABASE_URL?: string; PORT?: string } }\n",
-        'src/client/api.ts': fullstackClientApi(),
-        'src/client/App.tsx': FULLSTACK_APP_TSX,
-        'src/client/main.tsx': FULLSTACK_MAIN_TSX,
-        'src/client/styles.css': FULLSTACK_STYLES,
-        'index.html': FULLSTACK_INDEX_HTML,
-        'scripts/docker.ts': fullstackDockerCliScript(pkgName),
-        '.dockerignore': FULLSTACK_DOCKERIGNORE,
-        'docker-compose.yml': FULLSTACK_DOCKER_COMPOSE,
-        Dockerfile: fullstackDockerfile(),
-        '.env.example': 'PORT=8080\nDATABASE_URL=postgresql://postgres:postgres@localhost:5432/rrroutes\nVITE_API_URL=http://localhost:8080\n',
-        'README.md': `# ${pkgName}
-
-Full stack (API + Vite web) scaffolded by manager-cli.
-- dev: \`npm run dev\` (runs API + Vite client)
-- build: \`npm run build\` (server to dist/server, client to dist/client)
-- start: \`npm start\` (serves API and static client from dist)
-- docker helper: \`npm run docker:up\` (build + run), \`npm run docker:logs\`, \`npm run docker:stop\`
-- db helper: \`npm run db:up\` to start Postgres via docker-compose (uses DATABASE_URL)
-`,
+        ...basePackageFiles(),
     };
-}
-function fullstackContractTs() {
-    return `import { defineSocketEvents, finalize, resource } from '@emeryld/rrroutes-contract'
-import { z } from 'zod'
-
-const routes = resource('/api')
-  .sub(
-    resource('health')
-      .get({
-        outputSchema: z.object({
-          status: z.literal('ok'),
-          at: z.string(),
-          db: z.string(),
-        }),
-        description: 'Health check with DB status.',
-      })
-      .done(),
-  )
-  .done()
-
-export const registry = finalize(routes)
-
-const sockets = defineSocketEvents(
-  {
-    pingPayload: z.object({
-      note: z.string().default('ping'),
-      sentAt: z.string(),
-    }),
-    pongPayload: z.object({
-      ok: z.boolean(),
-      receivedAt: z.string(),
-      echo: z.string().optional(),
-    }),
-  },
-  {
-    'health:ping': {
-      message: z.object({
-        note: z.string().default('ping'),
-      }),
-    },
-    'health:pong': {
-      message: z.object({
-        ok: z.literal(true),
-        at: z.string(),
-        echo: z.string().optional(),
-      }),
-    },
-  },
-)
-
-export const socketConfig = sockets.config
-export const socketEvents = sockets.events
-export type AppRegistry = typeof registry
-`;
-}
-function fullstackClientApi() {
-    return `import { QueryClient } from '@tanstack/react-query'
-import { createRouteClient } from '@emeryld/rrroutes-client'
-import { registry } from '../contract'
-
-const baseUrl = import.meta.env.VITE_API_URL ?? 'http://localhost:8080'
-export const queryClient = new QueryClient()
-
-export const routeClient = createRouteClient({
-  baseUrl,
-  queryClient,
-  environment: import.meta.env.MODE === 'production' ? 'production' : 'development',
-})
-
-export const healthGet = routeClient.build(registry.byKey['GET /api/health'])
-`;
-}
-function fullstackDockerCliScript(pkgName) {
-    return `#!/usr/bin/env tsx
-import { readFile } from 'node:fs/promises'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { Docker } from 'docker-cli-js'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-const pkgRaw = await readFile(path.join(__dirname, '..', 'package.json'), 'utf8')
-const pkg = JSON.parse(pkgRaw) as { name?: string }
-const image = \`\${pkg.name ?? '${pkgName}'}:latest\`
-const container =
-  (pkg.name ?? '${pkgName}').replace(/[^a-z0-9]/gi, '-').replace(/^-+|-+$/g, '') || 'rrr-fullstack'
-const port = process.env.PORT ?? '8080'
-const docker = new Docker({ spawnOptions: { stdio: 'inherit' } })
-
-async function main() {
-  const [command = 'help'] = process.argv.slice(2)
-  if (command === 'help') return printHelp()
-  if (command === 'build') return docker.command(\`build -t \${image} .\`)
-  if (command === 'up') {
-    await docker.command(\`build -t \${image} .\`)
-    return docker.command(\`run -d --rm -p \${port}:\${port} --name \${container} \${image}\`)
-  }
-  if (command === 'run') {
-    return docker.command(\`run -d --rm -p \${port}:\${port} --name \${container} \${image}\`)
-  }
-  if (command === 'logs') return docker.command(\`logs -f \${container}\`)
-  if (command === 'stop') return docker.command(\`stop \${container}\`)
-  if (command === 'clean') {
-    try {
-      await docker.command(\`rm -f \${container}\`)
-    } catch (error) {
-      console.warn(String(error))
+    for (const [relative, contents] of Object.entries(files)) {
+        // eslint-disable-next-line no-await-in-loop
+        await writeFileIfMissing(baseDir, relative, contents);
     }
-    return
-  }
-  return printHelp()
-}
-
-function printHelp() {
-  console.log(
-    [
-      'Docker helper commands:',
-      '  build   -> docker build -t ${pkgName}:latest .',
-      '  up      -> build then run in detached mode',
-      '  run     -> run existing image detached',
-      '  logs    -> docker logs -f <container>',
-      '  stop    -> docker stop <container>',
-      '  clean   -> docker rm -f <container>',
-    ].join('\\n'),
-  )
-}
-
-main().catch((err) => {
-  console.error(err)
-  process.exit(1)
-})
-`;
 }
 export const fullstackVariant = {
     id: 'rrr-fullstack',
-    label: 'full stack service (api + web)',
-    defaultDir: 'packages/rrr-fullstack',
+    label: 'rrr fullstack (contract + server + client + docker)',
+    defaultDir: 'rrrfull-stack',
     async scaffold(ctx) {
-        const files = fullstackFiles(ctx.pkgName);
-        for (const [relative, contents] of Object.entries(files)) {
-            // eslint-disable-next-line no-await-in-loop
-            await writeFileIfMissing(ctx.targetDir, relative, contents);
-        }
+        const baseName = ctx.pkgName;
+        const names = deriveNames(baseName);
+        const dirs = deriveDirs(ctx.targetDir, baseName);
+        // Root workspace files
+        await scaffoldRootFiles(dirs.root, baseName);
+        // Contract package (reuse contract variant)
+        await contractVariant.scaffold({
+            targetDir: dirs.contract,
+            pkgName: names.contract,
+        });
+        // Server package
+        await serverVariant.scaffold({
+            targetDir: dirs.server,
+            pkgName: names.server,
+            contractName: names.contract,
+        });
+        // Client package
+        await clientVariant.scaffold({
+            targetDir: dirs.client,
+            pkgName: names.client,
+            contractName: names.contract,
+        });
+        // Docker helper package (reuse docker variant)
+        await dockerVariant.scaffold({
+            targetDir: dirs.docker,
+            pkgName: names.docker,
+        });
     },
 };

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

@@ -1,6 +1,6 @@
-import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+import { BASE_LINT_DEV_DEPENDENCIES, basePackageFiles, basePackageJson, buildReadme, baseScripts, baseTsConfig, writeFileIfMissing, } from '../shared.js';
 const CONTRACT_IMPORT_PLACEHOLDER = '@your-scope/contract';
-function serverIndexTs(contractImport) {
+export function serverIndexTs(contractImport) {
     return `import 'dotenv/config'
 import http from 'node:http'
 import express from 'express'
@@ -46,23 +46,15 @@ server.listen(PORT, () => {
 })
 `;
 }
-function serverPackageJson(name) {
-    return `${JSON.stringify({
+export function serverPackageJson(name, contractName = CONTRACT_IMPORT_PLACEHOLDER) {
+    return basePackageJson({
         name,
-        version: '0.1.0',
         private: false,
-        type: 'module',
-        main: 'dist/index.js',
-        types: 'dist/index.d.ts',
-        files: ['dist'],
-        scripts: {
-            dev: 'node --loader ts-node/esm src/index.ts',
-            build: 'tsc -p tsconfig.json',
-            typecheck: 'tsc -p tsconfig.json --noEmit',
+        scripts: baseScripts('tsx watch --env-file .env src/index.ts', {
             start: 'node dist/index.js',
-        },
+        }),
         dependencies: {
-            '@emeryld/rrroutes-contract': '^2.5.2',
+            [contractName]: 'workspace:*',
             '@emeryld/rrroutes-server': '^2.4.1',
             cors: '^2.8.5',
             dotenv: '^16.4.5',
@@ -70,26 +62,59 @@ function serverPackageJson(name) {
             zod: '^4.2.1',
         },
         devDependencies: {
+            ...BASE_LINT_DEV_DEPENDENCIES,
             '@types/cors': '^2.8.5',
             '@types/express': '^5.0.6',
             '@types/node': '^24.10.2',
-            'ts-node': '^10.9.2',
-            typescript: '^5.9.3',
         },
-    }, null, 2)}\n`;
+    });
 }
 function serverFiles(pkgName, contractImport) {
+    const scriptsForReadme = [
+        'dev',
+        'build',
+        'typecheck',
+        'lint',
+        'lint:fix',
+        'format',
+        'format:check',
+        'clean',
+        'test',
+        'start',
+    ];
     return {
-        'package.json': serverPackageJson(pkgName),
+        'package.json': serverPackageJson(pkgName, contractImport),
         'tsconfig.json': baseTsConfig({ types: ['node'] }),
+        ...basePackageFiles(),
         'src/index.ts': serverIndexTs(contractImport),
         '.env.example': 'PORT=4000\n',
-        'README.md': `# ${pkgName}
-
-Starter RRRoutes server scaffold.
-- update the contract import in src/index.ts if needed (${contractImport})
-- run \`npm install\` then \`npm run dev\` to start the API
-`,
+        'README.md': buildReadme({
+            name: pkgName,
+            description: 'Starter RRRoutes server scaffold.',
+            scripts: scriptsForReadme,
+            sections: [
+                {
+                    title: 'Getting Started',
+                    lines: [
+                        '- Install deps: `npm install` (or `pnpm install`)',
+                        '- Copy `.env.example` to `.env` as needed.',
+                        '- Start dev API: `npm run dev`',
+                        '- Build output: `npm run build`',
+                    ],
+                },
+                {
+                    title: 'Usage',
+                    lines: [
+                        `- Update the contract import in \`src/index.ts\` if needed (${contractImport}).`,
+                        '- Start compiled server: `npm run start` after building.',
+                    ],
+                },
+                {
+                    title: 'Environment',
+                    lines: ['- `PORT` sets the HTTP port (default 4000).'],
+                },
+            ],
+        }),
     };
 }
 export const serverVariant = {
@@ -97,7 +122,8 @@ export const serverVariant = {
     label: 'rrr server',
     defaultDir: 'packages/rrr-server',
     async scaffold(ctx) {
-        const files = serverFiles(ctx.pkgName, CONTRACT_IMPORT_PLACEHOLDER);
+        const contractImport = ctx.contractName ?? CONTRACT_IMPORT_PLACEHOLDER;
+        const files = serverFiles(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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeryld/manager",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Interactive manager for pnpm monorepos (update/test/build/publish).",
   "license": "MIT",
   "type": "module",