@emeryld/manager 0.3.1 → 0.3.3

package/README.md

@@ -31,3 +31,14 @@ 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 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/dist/create-package/index.js

@@ -1,6 +1,7 @@
 import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 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';
@@ -59,21 +60,117 @@ async function runCommand(cmd, args, cwd = workspaceRoot) {
         child.on('error', (err) => reject(err));
     });
 }
+function formatVariantLines(variants, selected) {
+    const heading = colors.magenta('Available templates');
+    const lines = [heading];
+    variants.forEach((variant, index) => {
+        const isSelected = index === selected;
+        const pointer = isSelected ? `${colors.green('➤')} ` : '  ';
+        const numberLabel = colors.cyan(String(index + 1).padStart(2, ' '));
+        const label = isSelected ? colors.green(variant.label) : variant.label;
+        const meta = colors.dim(variant.defaultDir);
+        lines.push(`${pointer}${numberLabel}. ${label} ${meta}`);
+    });
+    lines.push('');
+    lines.push(colors.dim('Use ↑/↓ (or j/k) to move, digits (1-9,0 for 10) to pick, Enter to confirm, Esc/Ctrl+C to exit.'));
+    return lines;
+}
+function renderInteractiveList(lines, previousLineCount) {
+    if (previousLineCount > 0) {
+        process.stdout.write(`\x1b[${previousLineCount}A`);
+        process.stdout.write('\x1b[0J');
+    }
+    lines.forEach((line) => console.log(line));
+    return lines.length;
+}
 async function promptForVariant() {
-    const messageLines = [
-        'Pick a package template:',
-        VARIANTS.map((opt, idx) => `  [${idx + 1}] ${opt.label}`).join('\n'),
-        `Enter 1-${VARIANTS.length}: `,
-    ];
-    const message = `${messageLines.join('\n')}`;
-    const variant = await promptSingleKey(message, (key) => {
-        const idx = Number.parseInt(key, 10);
-        if (Number.isInteger(idx) && idx >= 1 && idx <= VARIANTS.length) {
-            return VARIANTS[idx - 1];
-        }
-        return undefined;
+    const supportsRawMode = typeof input.setRawMode === 'function' && input.isTTY;
+    if (!supportsRawMode) {
+        const fallbackMessage = [
+            'Pick a package template:',
+            VARIANTS.map((opt, idx) => `  [${idx + 1}] ${opt.label}`).join('\n'),
+            `Enter 1-${VARIANTS.length}: `,
+        ].join('\n');
+        return promptSingleKey(fallbackMessage, (key) => {
+            const idx = Number.parseInt(key, 10);
+            if (Number.isInteger(idx) && idx >= 1 && idx <= VARIANTS.length) {
+                return VARIANTS[idx - 1];
+            }
+            return undefined;
+        });
+    }
+    const wasRaw = input.isRaw;
+    if (!wasRaw) {
+        input.setRawMode(true);
+        input.resume();
+    }
+    process.stdout.write('\x1b[?25l');
+    return new Promise((resolve) => {
+        let selectedIndex = 0;
+        let renderedLines = 0;
+        const cleanup = () => {
+            if (renderedLines > 0) {
+                process.stdout.write(`\x1b[${renderedLines}A`);
+                process.stdout.write('\x1b[0J');
+                renderedLines = 0;
+            }
+            process.stdout.write('\x1b[?25h');
+            if (!wasRaw) {
+                input.setRawMode(false);
+                input.pause();
+            }
+            input.removeListener('data', onData);
+        };
+        const commitSelection = (variant) => {
+            cleanup();
+            console.log();
+            resolve(variant);
+        };
+        const render = () => {
+            const lines = formatVariantLines(VARIANTS, selectedIndex);
+            renderedLines = renderInteractiveList(lines, renderedLines);
+        };
+        const onData = (buffer) => {
+            const isArrowUp = buffer.equals(Buffer.from([0x1b, 0x5b, 0x41]));
+            const isArrowDown = buffer.equals(Buffer.from([0x1b, 0x5b, 0x42]));
+            const isCtrlC = buffer.length === 1 && buffer[0] === 0x03;
+            const isEnter = buffer.length === 1 && (buffer[0] === 0x0d || buffer[0] === 0x0a);
+            const isEscape = buffer.length === 1 && buffer[0] === 0x1b;
+            if (isCtrlC || isEscape) {
+                cleanup();
+                process.exit(1);
+            }
+            if (isArrowUp ||
+                (buffer.length === 1 && (buffer[0] === 0x6b || buffer[0] === 0x4b))) {
+                selectedIndex = (selectedIndex - 1 + VARIANTS.length) % VARIANTS.length;
+                render();
+                return;
+            }
+            if (isArrowDown ||
+                (buffer.length === 1 && (buffer[0] === 0x6a || buffer[0] === 0x4a))) {
+                selectedIndex = (selectedIndex + 1) % VARIANTS.length;
+                render();
+                return;
+            }
+            if (isEnter) {
+                commitSelection(VARIANTS[selectedIndex]);
+                return;
+            }
+            if (buffer.length === 1 && buffer[0] >= 0x30 && buffer[0] <= 0x39) {
+                const numericValue = buffer[0] === 0x30 ? 10 : buffer[0] - 0x30;
+                const idx = numericValue - 1;
+                if (idx >= 0 && idx < VARIANTS.length) {
+                    commitSelection(VARIANTS[idx]);
+                }
+                else {
+                    process.stdout.write('\x07');
+                }
+                return;
+            }
+        };
+        input.on('data', onData);
+        render();
     });
-    return variant;
 }
 async function promptForTargetDir(fallback) {
     const answer = await askLine(`Path for the new package? (${fallback}): `);
@@ -105,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/variants/docker.js

@@ -13,6 +13,12 @@ function dockerPackageJson(name) {
             build: 'tsc -p tsconfig.json',
             typecheck: 'tsc -p tsconfig.json --noEmit',
             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:logs': 'npm run docker:cli -- logs',
+            'docker:stop': 'npm run docker:cli -- stop',
+            'docker:clean': 'npm run docker:cli -- clean',
         },
         dependencies: {
             cors: '^2.8.5',
@@ -22,6 +28,7 @@ function dockerPackageJson(name) {
             '@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',
         },
@@ -82,6 +89,7 @@ function dockerFiles(pkgName) {
         'package.json': dockerPackageJson(pkgName),
         'tsconfig.json': baseTsConfig({ types: ['node'] }),
         'src/index.ts': dockerIndexTs(),
+        'scripts/docker.ts': dockerCliScript(pkgName),
         '.dockerignore': DOCKER_DOCKERIGNORE,
         Dockerfile: dockerDockerfile(),
         'README.md': `# ${pkgName}
@@ -89,11 +97,71 @@ function dockerFiles(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\`
+- docker helper: \`npm run docker:up\` (build + run), \`npm run docker:logs\`, \`npm run docker:stop\`
 `,
     };
 }
+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 === '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))
+    }
+    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 dockerVariant = {
     id: 'rrr-docker',
     label: 'dockerized service',

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

@@ -16,20 +16,36 @@ function fullstackPackageJson(name) {
             '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',
         },
         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',
@@ -41,13 +57,49 @@ function fullstackServerIndexTs() {
 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())
 
-app.get('/api/health', (_req, res) => {
-  res.json({ status: 'ok', at: new Date().toISOString() })
+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')
@@ -68,14 +120,43 @@ app.listen(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 (
-    <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>
+    <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>
   )
 }
 `;
@@ -132,6 +213,22 @@ npm-debug.log*
 pnpm-lock.yaml
 yarn.lock
 `;
+const FULLSTACK_DOCKER_COMPOSE = `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
+
+volumes:
+  db-data:
+`;
 function fullstackDockerfile() {
     return `FROM node:20-slim AS builder
 WORKDIR /app
@@ -167,29 +264,167 @@ function fullstackFiles(pkgName) {
         }),
         'tsconfig.server.json': baseTsConfig({
             types: ['node'],
-            rootDir: 'src/server',
-            outDir: 'dist/server',
-            include: ['src/server/**/*'],
+            rootDir: 'src',
+            outDir: 'dist',
+            include: ['src/server/**/*', 'src/contract/**/*'],
         }),
         '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\n',
+        '.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: \`docker build -t ${pkgName}:latest .\` then \`docker run -p 8080:8080 ${pkgName}:latest\`
+- 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)
 `,
     };
 }
+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))
+    }
+    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)',

package/package.json

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