@patricksardinha/agentkit-cli 0.6.0 → 0.7.0

package/src/commands/init.ts

@@ -9,6 +9,7 @@ import { generateClaudeMd } from '../generators/claudeMdGenerator.js'
 import { generateWorkflow } from '../generators/workflowGenerator.js'
 import { generatePlaybook } from '../generators/playbookGenerator.js'
 import { generateSkills } from '../generators/skillsGenerator.js'
+import { generateReadme } from '../generators/readmeGenerator.js'
 import { extractAgentsFromWorkflow } from '../utils/agentParser.js'
 import { logger } from '../utils/logger.js'
 import type { StackInfo } from '../detectors/stackDetector.js'
@@ -112,6 +113,7 @@ export function registerInit(program: Command): void {
       const claudeMdPath = join(cwd, 'CLAUDE.md')
       const workflowPath = join(cwd, 'AGENT_WORKFLOW.md')
       const playbookPath = join(cwd, 'PLAYBOOK.md')
+      const readmePath = join(cwd, 'README.md')
 
       // Resolve project name from package.json or directory name
       let projectName = basename(cwd)
@@ -162,11 +164,23 @@ export function registerInit(program: Command): void {
       await writeFile(workflowPath, workflowContent, 'utf-8')
       await writeFile(playbookPath, playbookContent, 'utf-8')
       await generateSkills(agents, cwd)
+
+      const readmeExists = await fileExists(readmePath)
+      if (!readmeExists) {
+        const readmeContent = generateReadme({ projectName, blueprintContent, stack: resolvedStack })
+        await writeFile(readmePath, readmeContent, 'utf-8')
+      }
+
       genSpinner.succeed('Fichiers générés')
 
       logger.success('CLAUDE.md         → créé')
       logger.success('AGENT_WORKFLOW.md  → créé')
       logger.success('PLAYBOOK.md        → créé')
       logger.success(`agents/           → ${agents.length} dossier(s) créé(s)`)
+      if (readmeExists) {
+        logger.warn('README.md already exists — skipped (not overwritten)')
+      } else {
+        logger.success('README.md         → créé')
+      }
     })
 }

package/src/generators/readmeGenerator.ts

@@ -0,0 +1,199 @@
+import type { StackInfo } from '../detectors/stackDetector.js'
+
+export interface ReadmeInput {
+  projectName: string
+  blueprintContent?: string
+  stack: StackInfo
+}
+
+function extractSection(content: string, heading: string): string {
+  const regex = new RegExp(`##\\s+${heading}\\s*\\n([\\s\\S]*?)(?=\\n##\\s|$)`)
+  const match = regex.exec(content)
+  return match ? match[1].trim() : ''
+}
+
+function stackLabel(stack: StackInfo): string {
+  switch (stack.framework) {
+    case 'react':   return 'React + Vite'
+    case 'nextjs':  return 'Next.js'
+    case 'tauri':   return 'Tauri v2'
+    case 'fastapi': return 'FastAPI'
+    case 'express': return 'Express'
+    case 'node':    return 'Node.js'
+    default:        return 'Unknown'
+  }
+}
+
+function gettingStarted(stack: StackInfo): string {
+  switch (stack.framework) {
+    case 'tauri':
+      return `\`\`\`bash
+npm install
+npm run tauri:dev   # development (hot reload)
+npm run tauri:build # production bundle
+\`\`\``
+    case 'react':
+      return `\`\`\`bash
+npm install
+npm run dev   # development server
+npm run build # production build
+\`\`\``
+    case 'nextjs':
+      return `\`\`\`bash
+npm install
+npm run dev   # development server (http://localhost:3000)
+npm run build # production build
+\`\`\``
+    case 'fastapi':
+      return `\`\`\`bash
+pip install -r requirements.txt
+uvicorn main:app --reload
+\`\`\``
+    case 'express':
+    case 'node':
+      return `\`\`\`bash
+npm install
+npm start
+\`\`\``
+    default:
+      return `\`\`\`bash
+npm install
+npm run dev
+\`\`\``
+  }
+}
+
+function projectStructure(stack: StackInfo): string {
+  switch (stack.framework) {
+    case 'react':
+      return `\`\`\`
+src/
+  components/   ← UI components (PascalCase)
+  hooks/        ← custom hooks (prefix: use*)
+  pages/        ← page-level components
+  utils/        ← shared helpers
+\`\`\``
+    case 'nextjs':
+      return `\`\`\`
+src/
+  app/          ← App Router pages and layouts
+  components/   ← shared UI components
+  lib/          ← server utilities, db clients
+  utils/        ← shared helpers
+\`\`\``
+    case 'tauri':
+      return `\`\`\`
+src/            ← frontend (${stack.hasTypeScript ? 'TypeScript' : 'JavaScript'})
+  components/
+  utils/
+src-tauri/      ← Rust backend
+  src/
+    main.rs     ← Tauri entry point
+    commands.rs ← Tauri commands (IPC)
+  tauri.conf.json
+\`\`\``
+    case 'fastapi':
+      return `\`\`\`
+app/
+  main.py       ← FastAPI app entry point
+  routers/      ← API route groups
+  models/       ← Pydantic models
+  services/     ← business logic
+  dependencies/ ← FastAPI dependencies (DI)
+tests/          ← pytest tests
+\`\`\``
+    case 'express':
+      return `\`\`\`
+src/
+  routes/       ← Express routers (one per domain)
+  controllers/  ← request handlers
+  services/     ← business logic
+  middleware/   ← Express middleware
+  utils/        ← shared helpers
+\`\`\``
+    case 'node':
+      return `\`\`\`
+src/
+  index.ts      ← entry point
+  lib/          ← core library code
+  utils/        ← shared helpers
+\`\`\``
+    default:
+      return `\`\`\`
+src/            ← source files
+\`\`\``
+  }
+}
+
+function stackTable(stack: StackInfo, blueprintConstraints: string): string {
+  const lang = stack.language === 'python' ? 'Python' : stack.hasTypeScript ? 'TypeScript' : 'JavaScript'
+  const rows: [string, string][] = [
+    ['Framework', stackLabel(stack)],
+    ['Language', lang],
+  ]
+  if (stack.extras.includes('prisma')) rows.push(['Database', 'Prisma ORM'])
+  if (stack.extras.includes('tailwind')) rows.push(['Styling', 'Tailwind CSS'])
+  if (stack.extras.includes('testing')) rows.push(['Testing', 'Vitest / Jest'])
+
+  const header = '| Technology | Details |\n|---|---|'
+  const rowLines = rows.map(([k, v]) => `| **${k}** | ${v} |`).join('\n')
+
+  let table = `${header}\n${rowLines}`
+
+  if (blueprintConstraints) {
+    table += `\n\n**Tech constraints (from blueprint)**:\n${blueprintConstraints}`
+  }
+
+  return table
+}
+
+export function generateReadme({ projectName, blueprintContent, stack }: ReadmeInput): string {
+  const goal = blueprintContent ? extractSection(blueprintContent, 'Goal') : ''
+  const features = blueprintContent ? extractSection(blueprintContent, 'Features') : ''
+  const techConstraints = blueprintContent
+    ? extractSection(blueprintContent, 'Tech constraints')
+    : ''
+
+  const tagline = goal
+    ? goal.split('\n')[0].replace(/^[-*>]\s*/, '')
+    : `A ${stackLabel(stack)} project.`
+
+  const overview = goal
+    ? goal
+    : `This project was scaffolded with [AgentKit](https://www.npmjs.com/package/@patricksardinha/agentkit-cli).`
+
+  const featuresSection = features
+    ? features
+    : '_Features will be described here._'
+
+  return `# ${projectName}
+
+> ${tagline}
+
+## Overview
+
+${overview}
+
+## Tech Stack
+
+${stackTable(stack, techConstraints)}
+
+## Getting Started
+
+${gettingStarted(stack)}
+
+## Features
+
+${featuresSection}
+
+## Project Structure
+
+${projectStructure(stack)}
+
+## Built with AgentKit
+
+This project was scaffolded with [AgentKit](https://www.npmjs.com/package/@patricksardinha/agentkit-cli) — a CLI that generates AI-native agent workflows for Claude Code.
+
+Read \`PLAYBOOK.md\` to understand the agent workflow that built this project.
+`
+}

package/tests/generators/readmeGenerator.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect } from 'vitest'
+import { generateReadme } from '../../src/generators/readmeGenerator.js'
+import type { StackInfo } from '../../src/detectors/stackDetector.js'
+
+function makeStack(
+  framework: StackInfo['framework'],
+  opts: Partial<Omit<StackInfo, 'framework'>> = {},
+): StackInfo {
+  return {
+    framework,
+    language: framework === 'fastapi' ? 'python' : opts.hasTypeScript ? 'typescript' : 'javascript',
+    hasTypeScript: opts.hasTypeScript ?? false,
+    extras: opts.extras ?? [],
+    ...opts,
+  }
+}
+
+const sampleBlueprint = `# My Awesome App
+
+## Goal
+A desktop app for logging development sessions with local AI search.
+
+## Features
+- Session logging with timestamps
+- Weekly summary reports
+- Natural language search via Ollama
+
+## Tech constraints
+- Tauri v2, all local, no cloud
+- Ollama for AI, no external API keys
+`
+
+// ─── Project name ─────────────────────────────────────────────────────────────
+
+describe('generateReadme — project name', () => {
+  it('contains the project name in the title', () => {
+    const result = generateReadme({ projectName: 'my-project', stack: makeStack('react') })
+    expect(result).toContain('# my-project')
+  })
+
+  it('contains the project name when blueprint is present', () => {
+    const result = generateReadme({
+      projectName: 'devlog-desktop',
+      blueprintContent: sampleBlueprint,
+      stack: makeStack('tauri', { hasTypeScript: true }),
+    })
+    expect(result).toContain('# devlog-desktop')
+  })
+})
+
+// ─── Built with AgentKit ──────────────────────────────────────────────────────
+
+describe('generateReadme — Built with AgentKit section', () => {
+  it('always contains the Built with AgentKit section', () => {
+    for (const framework of ['react', 'nextjs', 'tauri', 'fastapi', 'express', 'node', 'unknown'] as StackInfo['framework'][]) {
+      const result = generateReadme({ projectName: 'test', stack: makeStack(framework) })
+      expect(result).toContain('Built with AgentKit')
+    }
+  })
+
+  it('contains the npmjs link', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('react') })
+    expect(result).toContain('https://www.npmjs.com/package/@patricksardinha/agentkit-cli')
+  })
+
+  it('contains the PLAYBOOK.md one-liner', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('react') })
+    expect(result).toContain('PLAYBOOK.md')
+  })
+})
+
+// ─── Getting Started — commands per stack ─────────────────────────────────────
+
+describe('generateReadme — Getting Started commands', () => {
+  it('Tauri: contains tauri:dev and tauri:build', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('tauri', { hasTypeScript: true }) })
+    expect(result).toContain('npm run tauri:dev')
+    expect(result).toContain('npm run tauri:build')
+  })
+
+  it('React: contains npm run dev and npm run build', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('react') })
+    expect(result).toContain('npm run dev')
+    expect(result).toContain('npm run build')
+    expect(result).not.toContain('tauri')
+  })
+
+  it('Next.js: contains npm run dev and npm run build', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('nextjs') })
+    expect(result).toContain('npm run dev')
+    expect(result).toContain('npm run build')
+  })
+
+  it('FastAPI: contains pip install and uvicorn', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('fastapi') })
+    expect(result).toContain('pip install -r requirements.txt')
+    expect(result).toContain('uvicorn main:app --reload')
+  })
+
+  it('Express: contains npm install and npm start', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('express') })
+    expect(result).toContain('npm install')
+    expect(result).toContain('npm start')
+  })
+
+  it('Node.js: contains npm install and npm start', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('node') })
+    expect(result).toContain('npm install')
+    expect(result).toContain('npm start')
+  })
+
+  it('Unknown: contains npm install and npm run dev', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('unknown') })
+    expect(result).toContain('npm install')
+    expect(result).toContain('npm run dev')
+  })
+})
+
+// ─── Blueprint: Goal extraction ───────────────────────────────────────────────
+
+describe('generateReadme — Goal extraction from blueprint', () => {
+  it('uses the Goal section as the tagline when blueprint is present', () => {
+    const result = generateReadme({
+      projectName: 'devlog',
+      blueprintContent: sampleBlueprint,
+      stack: makeStack('tauri', { hasTypeScript: true }),
+    })
+    expect(result).toContain('A desktop app for logging development sessions')
+  })
+
+  it('uses a generic tagline when no blueprint is provided', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('react') })
+    expect(result).toContain('React + Vite')
+  })
+
+  it('includes Goal content in the Overview section', () => {
+    const result = generateReadme({
+      projectName: 'devlog',
+      blueprintContent: sampleBlueprint,
+      stack: makeStack('tauri', { hasTypeScript: true }),
+    })
+    expect(result).toContain('## Overview')
+    expect(result).toContain('A desktop app for logging development sessions')
+  })
+})
+
+// ─── Blueprint: Features extraction ──────────────────────────────────────────
+
+describe('generateReadme — Features extraction from blueprint', () => {
+  it('extracts Features section from blueprint', () => {
+    const result = generateReadme({
+      projectName: 'devlog',
+      blueprintContent: sampleBlueprint,
+      stack: makeStack('tauri', { hasTypeScript: true }),
+    })
+    expect(result).toContain('## Features')
+    expect(result).toContain('Session logging with timestamps')
+    expect(result).toContain('Weekly summary reports')
+    expect(result).toContain('Natural language search via Ollama')
+  })
+
+  it('uses placeholder when no blueprint is provided', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('react') })
+    expect(result).toContain('## Features')
+    expect(result).toContain('Features will be described here')
+  })
+
+  it('includes tech constraints from blueprint in the Tech Stack section', () => {
+    const result = generateReadme({
+      projectName: 'devlog',
+      blueprintContent: sampleBlueprint,
+      stack: makeStack('tauri', { hasTypeScript: true }),
+    })
+    expect(result).toContain('Tauri v2, all local, no cloud')
+  })
+})
+
+// ─── Project structure ────────────────────────────────────────────────────────
+
+describe('generateReadme — Project Structure section', () => {
+  it('always contains the Project Structure section', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('react') })
+    expect(result).toContain('## Project Structure')
+  })
+
+  it('React structure contains src/components/', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('react') })
+    expect(result).toContain('components/')
+  })
+
+  it('Tauri structure mentions src-tauri/', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('tauri', { hasTypeScript: true }) })
+    expect(result).toContain('src-tauri/')
+  })
+
+  it('FastAPI structure mentions app/routers/', () => {
+    const result = generateReadme({ projectName: 'test', stack: makeStack('fastapi') })
+    expect(result).toContain('routers/')
+  })
+})