@emeryld/manager 0.3.2 → 0.4.0

package/README.md

@@ -31,3 +31,28 @@ Interactive release helper for pnpm monorepos. Install it as a local dev depende
 ## 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 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/index.js

@@ -202,7 +202,9 @@ async function postCreateTasks(targetDir) {
 async function gatherTarget() {
     const variant = await promptForVariant();
     const targetDir = await promptForTargetDir(variant.defaultDir);
-    const pkgName = derivePackageName(targetDir);
+    const fallbackName = derivePackageName(targetDir);
+    const nameAnswer = await askLine(`Package name? (${fallbackName}): `);
+    const pkgName = (nameAnswer || fallbackName).trim() || fallbackName;
     await ensureTargetDir(targetDir);
     return { variant, targetDir, pkgName };
 }

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,31 +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',
-            tsx: '^4.19.0',
-            typescript: '^5.9.3',
+            'docker-cli-js': '^3.0.9',
         },
-    }, null, 2)}\n`;
+    });
 }
 function dockerIndexTs() {
     return `import express from 'express'
@@ -78,22 +77,146 @@ 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\`
-- build/publish container: \`docker build -t ${pkgName}:latest .\`
-- run container: \`docker run -p 3000:3000 ${pkgName}:latest\`
-`,
+        '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) {
+    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-service'
+const port = process.env.PORT ?? '3000'
+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 === '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') {
+    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 stop/rm <container>',
+      '  reset   -> clean container and remove image',
+    ].join('\\n'),
+  )
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})
+`;
+}
 export const dockerVariant = {
     id: 'rrr-docker',
     label: 'dockerized service',

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,204 +1,129 @@
-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',
-        },
-        dependencies: {
-            cors: '^2.8.5',
-            express: '^5.1.0',
-            react: '^18.3.1',
-            'react-dom': '^18.3.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',
-            '@vitejs/plugin-react': '^4.3.4',
-            concurrently: '^8.2.0',
-            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'
-
-const app = express()
-app.use(cors({ origin: '*' }))
-app.use(express.json())
-
-app.get('/api/health', (_req, res) => {
-  res.json({ status: 'ok', at: new Date().toISOString() })
-})
-
-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}\`)
-})
-`;
+function rootPnpmWorkspace() {
+    return "packages:\n  - 'packages/*'\n";
 }
-const FULLSTACK_APP_TSX = `import React from 'react'
+function stackComposeYaml() {
+    return `services:
+  db:
+    image: postgres:15
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: rrroutes
+    ports:
+      - '5432:5432'
+    volumes:
+      - db-data:/var/lib/postgresql/data
 
-export function App() {
-  return (
-    <main style={{ fontFamily: 'Inter, system-ui, sans-serif', padding: 24 }}>
-      <h1>Full stack service</h1>
-      <p>Backend: <code>/api/health</code> responds with status + timestamp.</p>
-      <p>Edit <code>src/client/App.tsx</code> to start building.</p>
-    </main>
-  )
-}
-`;
-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>,
-)
+volumes:
+  db-data:
 `;
-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',
-  },
-})
-`;
-}
-const FULLSTACK_DOCKERIGNORE = `node_modules
-dist
-.git
-.env
-npm-debug.log*
-pnpm-lock.yaml
-yarn.lock
-`;
-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'],
+            rootDir: '.',
+            outDir: 'dist',
+            include: ['packages/**/*', 'scripts/**/*', 'src/**/*'],
         }),
-        'tsconfig.server.json': baseTsConfig({
-            types: ['node'],
-            rootDir: 'src/server',
-            outDir: 'dist/server',
-            include: ['src/server/**/*'],
-        }),
-        'vite.config.ts': fullstackViteConfig(),
-        'src/server/index.ts': fullstackServerIndexTs(),
-        '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,
-        '.dockerignore': FULLSTACK_DOCKERIGNORE,
-        Dockerfile: fullstackDockerfile(),
-        '.env.example': 'PORT=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: \`docker build -t ${pkgName}:latest .\` then \`docker run -p 8080:8080 ${pkgName}:latest\`
-`,
+        ...basePackageFiles(),
     };
+    for (const [relative, contents] of Object.entries(files)) {
+        // eslint-disable-next-line no-await-in-loop
+        await writeFileIfMissing(baseDir, relative, contents);
+    }
 }
 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.2",
+  "version": "0.4.0",
   "description": "Interactive manager for pnpm monorepos (update/test/build/publish).",
   "license": "MIT",
   "type": "module",