@emeryld/manager 0.2.4 → 0.3.1

package/dist/create-package/index.js

@@ -0,0 +1,121 @@
+import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { askLine, promptSingleKey } from '../prompts.js';
+import { colors, logGlobal } from '../utils/log.js';
+import { workspaceRoot } from './shared.js';
+import { clientVariant } from './variants/client.js';
+import { contractVariant } from './variants/contract.js';
+import { dockerVariant } from './variants/docker.js';
+import { emptyVariant } from './variants/empty.js';
+import { fullstackVariant } from './variants/fullstack.js';
+import { serverVariant } from './variants/server.js';
+const VARIANTS = [
+    contractVariant,
+    serverVariant,
+    clientVariant,
+    emptyVariant,
+    dockerVariant,
+    fullstackVariant,
+];
+function derivePackageName(targetDir) {
+    const base = path.basename(targetDir) || 'rrr-package';
+    return base;
+}
+async function ensureTargetDir(targetDir) {
+    try {
+        const stats = await stat(targetDir);
+        if (!stats.isDirectory()) {
+            throw new Error(`Target "${targetDir}" exists and is not a directory.`);
+        }
+        const entries = await readdir(targetDir);
+        if (entries.length > 0) {
+            logGlobal(`Target ${path.relative(workspaceRoot, targetDir)} is not empty; existing files will be preserved.`, colors.yellow);
+        }
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            error.code === 'ENOENT') {
+            await mkdir(targetDir, { recursive: true });
+            return;
+        }
+        throw error;
+    }
+}
+async function runCommand(cmd, args, cwd = workspaceRoot) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            cwd,
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        child.on('exit', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${cmd} ${args.join(' ')} exited with ${code}`));
+        });
+        child.on('error', (err) => reject(err));
+    });
+}
+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;
+    });
+    return variant;
+}
+async function promptForTargetDir(fallback) {
+    const answer = await askLine(`Path for the new package? (${fallback}): `);
+    const normalized = answer || fallback;
+    return path.resolve(workspaceRoot, normalized);
+}
+async function postCreateTasks(targetDir) {
+    try {
+        logGlobal('Running pnpm install…', colors.cyan);
+        await runCommand('pnpm', ['install'], workspaceRoot);
+    }
+    catch (error) {
+        logGlobal(`pnpm install failed: ${error instanceof Error ? error.message : String(error)}`, colors.yellow);
+        return;
+    }
+    try {
+        const pkgJsonPath = path.join(targetDir, 'package.json');
+        const pkgRaw = await readFile(pkgJsonPath, 'utf8');
+        const pkg = JSON.parse(pkgRaw);
+        if (pkg.scripts?.build) {
+            logGlobal('Running pnpm run build for the new package…', colors.cyan);
+            await runCommand('pnpm', ['-C', targetDir, 'run', 'build'], workspaceRoot);
+        }
+    }
+    catch (error) {
+        logGlobal(`Skipping build (could not read package.json): ${error instanceof Error ? error.message : String(error)}`, colors.yellow);
+    }
+}
+async function gatherTarget() {
+    const variant = await promptForVariant();
+    const targetDir = await promptForTargetDir(variant.defaultDir);
+    const pkgName = derivePackageName(targetDir);
+    await ensureTargetDir(targetDir);
+    return { variant, targetDir, pkgName };
+}
+export async function createRrrPackage() {
+    const target = await gatherTarget();
+    logGlobal(`Creating ${target.variant.label} in ${path.relative(workspaceRoot, target.targetDir) || '.'}`, colors.green);
+    await target.variant.scaffold({
+        targetDir: target.targetDir,
+        pkgName: target.pkgName,
+    });
+    await postCreateTasks(target.targetDir);
+    logGlobal('Scaffold complete. Install/build steps were attempted; ready to run!', colors.green);
+}

package/dist/create-package/shared.js

@@ -0,0 +1,44 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export const workspaceRoot = process.cwd();
+export async function writeFileIfMissing(baseDir, relative, contents) {
+    const fullPath = path.join(baseDir, relative);
+    await mkdir(path.dirname(fullPath), { recursive: true });
+    try {
+        await access(fullPath);
+        const rel = path.relative(workspaceRoot, fullPath);
+        console.log(`  skipped ${rel} (already exists)`);
+        return 'skipped';
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    await writeFile(fullPath, contents, 'utf8');
+    const rel = path.relative(workspaceRoot, fullPath);
+    console.log(`  created ${rel}`);
+    return 'created';
+}
+export function baseTsConfig(options) {
+    return `${JSON.stringify({
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            outDir: options?.outDir ?? 'dist',
+            rootDir: options?.rootDir ?? 'src',
+            declaration: true,
+            sourceMap: true,
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            lib: options?.lib,
+            types: options?.types,
+            jsx: options?.jsx,
+        },
+        include: options?.include ?? ['src/**/*'],
+    }, null, 2)}\n`;
+}

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

@@ -0,0 +1,70 @@
+import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+const CONTRACT_IMPORT_PLACEHOLDER = '@your-scope/contract';
+function clientIndexTs(contractImport) {
+    return `import { QueryClient } from '@tanstack/react-query'
+import { createRouteClient } from '@emeryld/rrroutes-client'
+import { registry } from '${contractImport}'
+
+const baseUrl = process.env.RRR_API_URL ?? 'http://localhost:4000'
+export const queryClient = new QueryClient()
+
+export const routeClient = createRouteClient({
+  baseUrl,
+  queryClient,
+  environment: process.env.NODE_ENV === 'production' ? 'production' : 'development',
+})
+
+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({
+        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',
+        },
+        dependencies: {
+            '@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: {
+            '@types/node': '^24.10.2',
+            typescript: '^5.9.3',
+        },
+    }, null, 2)}\n`;
+}
+function clientFiles(pkgName, contractImport) {
+    return {
+        'package.json': clientPackageJson(pkgName),
+        'tsconfig.json': baseTsConfig({ lib: ['ES2020', 'DOM'], types: ['node'] }),
+        '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
+`,
+    };
+}
+export const clientVariant = {
+    id: 'rrr-client',
+    label: 'rrr client',
+    defaultDir: 'packages/rrr-client',
+    async scaffold(ctx) {
+        const files = clientFiles(ctx.pkgName, CONTRACT_IMPORT_PLACEHOLDER);
+        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

@@ -0,0 +1,125 @@
+import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+const CONTRACT_TS = `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'),
+          html: z.string().optional(),
+        }),
+        description: 'Basic GET health probe for uptime + docs.',
+      })
+      .post({
+        bodySchema: z.object({
+          echo: z.string().optional(),
+        }),
+        outputSchema: z.object({
+          status: z.literal('ok'),
+          received: z.string().optional(),
+        }),
+        description: 'POST health probe that echoes a payload.',
+      })
+      .done(),
+  )
+  .done()
+
+export const registry = finalize(routes)
+
+const sockets = defineSocketEvents(
+  {
+    joinMetaMessage: z.object({ room: z.string().optional() }),
+    leaveMetaMessage: z.object({ room: z.string().optional() }),
+    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:connected': {
+      message: z.object({
+        socketId: z.string(),
+        at: z.string(),
+        message: z.string(),
+      }),
+    },
+    '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 contractPackageJson(name) {
+    return `${JSON.stringify({
+        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',
+        },
+        dependencies: {
+            '@emeryld/rrroutes-contract': '^2.5.2',
+            zod: '^4.2.1',
+        },
+        devDependencies: {
+            typescript: '^5.9.3',
+        },
+    }, null, 2)}\n`;
+}
+function contractFiles(pkgName) {
+    return {
+        'package.json': contractPackageJson(pkgName),
+        'tsconfig.json': baseTsConfig(),
+        '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
+`,
+    };
+}
+export const contractVariant = {
+    id: 'rrr-contract',
+    label: 'rrr contract',
+    defaultDir: 'packages/rrr-contract',
+    async scaffold(ctx) {
+        const files = contractFiles(ctx.pkgName);
+        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/docker.js

@@ -0,0 +1,108 @@
+import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+function dockerPackageJson(name) {
+    return `${JSON.stringify({
+        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',
+            start: 'node dist/index.js',
+        },
+        dependencies: {
+            cors: '^2.8.5',
+            express: '^5.1.0',
+        },
+        devDependencies: {
+            '@types/cors': '^2.8.5',
+            '@types/express': '^5.0.6',
+            '@types/node': '^24.10.2',
+            tsx: '^4.19.0',
+            typescript: '^5.9.3',
+        },
+    }, null, 2)}\n`;
+}
+function dockerIndexTs() {
+    return `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 PORT = Number.parseInt(process.env.PORT ?? '3000', 10)
+
+app.listen(PORT, () => {
+  console.log(\`Docker-ready service listening on http://localhost:\${PORT}\`)
+})
+`;
+}
+const DOCKER_DOCKERIGNORE = `node_modules
+dist
+.git
+.env
+npm-debug.log*
+pnpm-lock.yaml
+yarn.lock
+`;
+function dockerDockerfile() {
+    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
+
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+`;
+}
+function dockerFiles(pkgName) {
+    return {
+        'package.json': dockerPackageJson(pkgName),
+        'tsconfig.json': baseTsConfig({ types: ['node'] }),
+        'src/index.ts': dockerIndexTs(),
+        '.dockerignore': DOCKER_DOCKERIGNORE,
+        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\`
+`,
+    };
+}
+export const dockerVariant = {
+    id: 'rrr-docker',
+    label: 'dockerized service',
+    defaultDir: 'packages/rrr-docker',
+    async scaffold(ctx) {
+        const files = dockerFiles(ctx.pkgName);
+        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/empty.js

@@ -0,0 +1,44 @@
+import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+function emptyPackageJson(name) {
+    return `${JSON.stringify({
+        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',
+        },
+        devDependencies: {
+            typescript: '^5.9.3',
+        },
+    }, null, 2)}\n`;
+}
+function emptyFiles(pkgName) {
+    return {
+        'package.json': emptyPackageJson(pkgName),
+        'tsconfig.json': baseTsConfig({ types: ['node'] }),
+        '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\`
+`,
+    };
+}
+export const emptyVariant = {
+    id: 'rrr-empty',
+    label: 'empty package',
+    defaultDir: 'packages/rrr-empty',
+    async scaffold(ctx) {
+        const files = emptyFiles(ctx.pkgName);
+        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/fullstack.js

@@ -0,0 +1,204 @@
+import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+function fullstackPackageJson(name) {
+    return `${JSON.stringify({
+        name,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        main: 'dist/server/index.js',
+        files: ['dist'],
+        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',
+        },
+        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',
+        },
+    }, 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}\`)
+})
+`;
+}
+const FULLSTACK_APP_TSX = `import React from 'react'
+
+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>,
+)
+`;
+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),
+        'tsconfig.json': baseTsConfig({
+            lib: ['ES2020', 'DOM'],
+            types: ['node'],
+            jsx: 'react-jsx',
+            include: ['src/**/*', 'vite.config.ts'],
+        }),
+        '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\`
+`,
+    };
+}
+export const fullstackVariant = {
+    id: 'rrr-fullstack',
+    label: 'full stack service (api + web)',
+    defaultDir: 'packages/rrr-fullstack',
+    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);
+        }
+    },
+};

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

@@ -0,0 +1,106 @@
+import { baseTsConfig, writeFileIfMissing, } from '../shared.js';
+const CONTRACT_IMPORT_PLACEHOLDER = '@your-scope/contract';
+function serverIndexTs(contractImport) {
+    return `import 'dotenv/config'
+import http from 'node:http'
+import express from 'express'
+import cors from 'cors'
+import { createRRRoute } from '@emeryld/rrroutes-server'
+import { registry } from '${contractImport}'
+
+const app = express()
+app.use(cors({ origin: '*', credentials: true }))
+app.use(express.json())
+
+app.get('/', (_req, res) => {
+  res.send('<h1>rrr server ready</h1>')
+})
+
+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 ({ ctx }) => ({
+      out: {
+        status: 'ok',
+        requestId: ctx.requestId,
+        at: new Date().toISOString(),
+      },
+    }),
+  },
+})
+
+const PORT = Number.parseInt(process.env.PORT ?? '4000', 10)
+const server = http.createServer(app)
+
+server.listen(PORT, () => {
+  console.log(\`rrr server listening on http://localhost:\${PORT}\`)
+})
+`;
+}
+function serverPackageJson(name) {
+    return `${JSON.stringify({
+        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',
+            start: 'node dist/index.js',
+        },
+        dependencies: {
+            '@emeryld/rrroutes-contract': '^2.5.2',
+            '@emeryld/rrroutes-server': '^2.4.1',
+            cors: '^2.8.5',
+            dotenv: '^16.4.5',
+            express: '^5.1.0',
+            zod: '^4.2.1',
+        },
+        devDependencies: {
+            '@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) {
+    return {
+        'package.json': serverPackageJson(pkgName),
+        'tsconfig.json': baseTsConfig({ types: ['node'] }),
+        '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
+`,
+    };
+}
+export const serverVariant = {
+    id: 'rrr-server',
+    label: 'rrr server',
+    defaultDir: 'packages/rrr-server',
+    async scaffold(ctx) {
+        const files = serverFiles(ctx.pkgName, CONTRACT_IMPORT_PLACEHOLDER);
+        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.js

@@ -0,0 +1,388 @@
+import { access, mkdir, readdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { askLine, promptSingleKey } from './prompts.js';
+import { colors, logGlobal } from './utils/log.js';
+const VARIANTS = [
+    { id: 'rrr-contract', label: 'rrr contract', defaultDir: 'packages/rrr-contract' },
+    { id: 'rrr-server', label: 'rrr server', defaultDir: 'packages/rrr-server' },
+    { id: 'rrr-client', label: 'rrr client', defaultDir: 'packages/rrr-client' },
+];
+const workspaceRoot = process.cwd();
+function derivePackageName(targetDir) {
+    const base = path.basename(targetDir) || 'rrr-package';
+    return base;
+}
+async function ensureTargetDir(targetDir) {
+    try {
+        const stats = await stat(targetDir);
+        if (!stats.isDirectory()) {
+            throw new Error(`Target "${targetDir}" exists and is not a directory.`);
+        }
+        const entries = await readdir(targetDir);
+        if (entries.length > 0) {
+            logGlobal(`Target ${path.relative(workspaceRoot, targetDir)} is not empty; existing files will be preserved.`, colors.yellow);
+        }
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            error.code === 'ENOENT') {
+            await mkdir(targetDir, { recursive: true });
+            return;
+        }
+        throw error;
+    }
+}
+async function writeFileIfMissing(baseDir, relative, contents) {
+    const fullPath = path.join(baseDir, relative);
+    await mkdir(path.dirname(fullPath), { recursive: true });
+    try {
+        await access(fullPath);
+        const rel = path.relative(workspaceRoot, fullPath);
+        console.log(`  skipped ${rel} (already exists)`);
+        return 'skipped';
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    await writeFile(fullPath, contents, 'utf8');
+    const rel = path.relative(workspaceRoot, fullPath);
+    console.log(`  created ${rel}`);
+    return 'created';
+}
+function contractIndexTs() {
+    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'),
+          html: z.string().optional(),
+        }),
+        description: 'Basic GET health probe for uptime + docs.',
+      })
+      .post({
+        bodySchema: z.object({
+          echo: z.string().optional(),
+        }),
+        outputSchema: z.object({
+          status: z.literal('ok'),
+          received: z.string().optional(),
+        }),
+        description: 'POST health probe that echoes a payload.',
+      })
+      .done(),
+  )
+  .done()
+
+export const registry = finalize(routes)
+
+const sockets = defineSocketEvents(
+  {
+    joinMetaMessage: z.object({ room: z.string().optional() }),
+    leaveMetaMessage: z.object({ room: z.string().optional() }),
+    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:connected': {
+      message: z.object({
+        socketId: z.string(),
+        at: z.string(),
+        message: z.string(),
+      }),
+    },
+    '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 serverIndexTs(contractImport) {
+    return `import 'dotenv/config'
+import http from 'node:http'
+import express from 'express'
+import cors from 'cors'
+import { createRRRoute } from '@emeryld/rrroutes-server'
+import { registry } from '${contractImport}'
+
+const app = express()
+app.use(cors({ origin: '*', credentials: true }))
+app.use(express.json())
+
+app.get('/', (_req, res) => {
+  res.send('<h1>rrr server ready</h1>')
+})
+
+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 ({ ctx }) => ({
+      out: {
+        status: 'ok',
+        requestId: ctx.requestId,
+        at: new Date().toISOString(),
+      },
+    }),
+  },
+})
+
+const PORT = Number.parseInt(process.env.PORT ?? '4000', 10)
+const server = http.createServer(app)
+
+server.listen(PORT, () => {
+  console.log(\`rrr server listening on http://localhost:\${PORT}\`)
+})
+`;
+}
+function clientIndexTs(contractImport) {
+    return `import { QueryClient } from '@tanstack/react-query'
+import { createRouteClient } from '@emeryld/rrroutes-client'
+import { registry } from '${contractImport}'
+
+const baseUrl = process.env.RRR_API_URL ?? 'http://localhost:4000'
+export const queryClient = new QueryClient()
+
+export const routeClient = createRouteClient({
+  baseUrl,
+  queryClient,
+  environment: process.env.NODE_ENV === 'production' ? 'production' : 'development',
+})
+
+export const healthGet = routeClient.build(registry.byKey['GET /api/health'])
+export const healthPost = routeClient.build(registry.byKey['POST /api/health'])
+`;
+}
+function baseTsConfig(options) {
+    return `${JSON.stringify({
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            outDir: 'dist',
+            rootDir: 'src',
+            declaration: true,
+            sourceMap: true,
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            lib: options?.lib,
+            types: options?.types,
+        },
+        include: ['src/**/*'],
+    }, null, 2)}\n`;
+}
+function contractPackageJson(name) {
+    return `${JSON.stringify({
+        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',
+        },
+        dependencies: {
+            '@emeryld/rrroutes-contract': '^2.5.2',
+            zod: '^4.2.1',
+        },
+        devDependencies: {
+            typescript: '^5.9.3',
+        },
+    }, null, 2)}\n`;
+}
+function serverPackageJson(name) {
+    return `${JSON.stringify({
+        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',
+            start: 'node dist/index.js',
+        },
+        dependencies: {
+            '@emeryld/rrroutes-contract': '^2.5.2',
+            '@emeryld/rrroutes-server': '^2.4.1',
+            cors: '^2.8.5',
+            dotenv: '^16.4.5',
+            express: '^5.1.0',
+            zod: '^4.2.1',
+        },
+        devDependencies: {
+            '@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 clientPackageJson(name) {
+    return `${JSON.stringify({
+        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',
+        },
+        dependencies: {
+            '@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: {
+            '@types/node': '^24.10.2',
+            typescript: '^5.9.3',
+        },
+    }, null, 2)}\n`;
+}
+function contractFiles(pkgName) {
+    return {
+        'package.json': contractPackageJson(pkgName),
+        'tsconfig.json': baseTsConfig(),
+        'src/index.ts': contractIndexTs(),
+        '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
+`,
+    };
+}
+function serverFiles(pkgName, contractImport) {
+    return {
+        'package.json': serverPackageJson(pkgName),
+        'tsconfig.json': baseTsConfig({ types: ['node'] }),
+        '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
+`,
+    };
+}
+function clientFiles(pkgName, contractImport) {
+    return {
+        'package.json': clientPackageJson(pkgName),
+        'tsconfig.json': baseTsConfig({ lib: ['ES2020', 'DOM'], types: ['node'] }),
+        '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
+`,
+    };
+}
+function resolveContractImport(variant) {
+    if (variant === 'rrr-contract')
+        return '';
+    return '@your-scope/contract';
+}
+async function scaffoldVariant(variant, targetDir, pkgName) {
+    const contractImport = resolveContractImport(variant);
+    let files;
+    if (variant === 'rrr-contract')
+        files = contractFiles(pkgName);
+    else if (variant === 'rrr-server')
+        files = serverFiles(pkgName, contractImport);
+    else
+        files = clientFiles(pkgName, contractImport);
+    for (const [relative, contents] of Object.entries(files)) {
+        // eslint-disable-next-line no-await-in-loop
+        await writeFileIfMissing(targetDir, relative, contents);
+    }
+}
+async function promptForVariant() {
+    const messageLines = [
+        'Pick a package template:',
+        VARIANTS.map((opt, idx) => `  [${idx + 1}] ${opt.label}`).join('\n'),
+        'Enter 1, 2, or 3: ',
+    ];
+    const message = `${messageLines.join('\n')}`;
+    const variant = await promptSingleKey(message, (key) => {
+        if (key === '1')
+            return VARIANTS[0];
+        if (key === '2')
+            return VARIANTS[1];
+        if (key === '3')
+            return VARIANTS[2];
+        return undefined;
+    });
+    return variant;
+}
+async function promptForTargetDir(fallback) {
+    const answer = await askLine(`Path for the new package? (${fallback}): `);
+    const normalized = answer || fallback;
+    return path.resolve(workspaceRoot, normalized);
+}
+export async function createRrrPackage() {
+    const variant = await promptForVariant();
+    const targetDir = await promptForTargetDir(variant.defaultDir);
+    await ensureTargetDir(targetDir);
+    const pkgName = derivePackageName(targetDir);
+    logGlobal(`Creating ${variant.label} in ${path.relative(workspaceRoot, targetDir) || '.'}`, colors.green);
+    await scaffoldVariant(variant.id, targetDir, pkgName);
+    logGlobal('Scaffold complete. Install deps and start building!', colors.green);
+}

package/dist/menu.js

@@ -95,6 +95,8 @@ export function buildPackageSelectionMenu(packages, onStepComplete) {
             onStepComplete?.(step);
         },
     }));
+    if (ordered.length === 0)
+        return entries;
     entries.push({
         name: 'All packages',
         emoji: globalEmoji,

package/dist/packages.js

@@ -37,7 +37,7 @@ function deriveSubstitute(name) {
         return '';
     const segments = trimmed.split(/[@\/\-]/).filter(Boolean);
     const transformed = segments
-        .map((segment) => segment.slice(0, 2))
+        .map((segment) => segment)
         .filter(Boolean)
         .join(' ');
     return transformed || trimmed;

package/dist/publish.js

@@ -5,6 +5,8 @@ import { getOrderedPackages, loadPackages, resolvePackage } from './packages.js'
 import { releaseMultiple, releaseSingle, } from './release.js';
 import { ensureWorkingTreeCommitted } from './preflight.js';
 import { publishCliState } from './prompts.js';
+import { createRrrPackage } from './create-package/index.js';
+import { colors, logGlobal } from './utils/log.js';
 function resolveTargetsFromArg(packages, arg) {
     if (arg.toLowerCase() === 'all')
         return getOrderedPackages(packages);
@@ -89,14 +91,27 @@ function optsFromParsed(p) {
 }
 async function runPackageSelectionLoop(packages, helperArgs) {
     let argv = [...helperArgs];
+    let currentPackages = packages;
     // eslint-disable-next-line no-constant-condition
     while (true) {
         let lastStep;
         await runHelperCli({
             title: 'Pick one of the packages or all',
-            scripts: buildPackageSelectionMenu(packages, (step) => {
-                lastStep = step;
-            }),
+            scripts: [
+                ...buildPackageSelectionMenu(currentPackages, (step) => {
+                    lastStep = step;
+                }),
+                {
+                    name: 'Create package',
+                    emoji: '✨',
+                    description: 'Scaffold a new rrr package (contract/server/client)',
+                    handler: async () => {
+                        await createRrrPackage();
+                        currentPackages = await loadPackages();
+                        lastStep = 'back';
+                    },
+                },
+            ],
             argv, // pass through CLI args only once; subsequent loops rely on selection
         });
         argv = [];
@@ -108,10 +123,11 @@ async function main() {
     const cliArgs = process.argv.slice(2);
     const parsed = parseCliArgs(cliArgs);
     const packages = await loadPackages();
-    if (packages.length === 0)
-        throw new Error('No packages found in ./packages');
     // If user provided non-interactive flags, run headless path
     if (parsed.nonInteractive) {
+        if (packages.length === 0) {
+            throw new Error('No packages found in ./packages');
+        }
         publishCliState.autoConfirmAll = true;
         if (!parsed.selectionArg) {
             throw new Error('Non-interactive mode requires a package selection: <pkg> or "all".');
@@ -128,6 +144,9 @@ async function main() {
             await releaseSingle(targets[0], packages, opts);
         return;
     }
+    if (packages.length === 0) {
+        logGlobal('No packages found in ./packages. Use "Create package" to scaffold one.', colors.yellow);
+    }
     // Interactive flow (unchanged): selection menu then step menu
     if (parsed.selectionArg) {
         const targets = resolveTargetsFromArg(packages, parsed.selectionArg);

package/package.json

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