@patricksardinha/agentkit-cli 0.1.0

package/src/types/inquirer.d.ts

@@ -0,0 +1,36 @@
+declare module 'inquirer' {
+  export interface QuestionBase {
+    type: string
+    name: string
+    message: string
+    default?: unknown
+    choices?: unknown[]
+    validate?: (input: unknown) => boolean | string | Promise<boolean | string>
+  }
+
+  export interface ConfirmQuestion extends QuestionBase {
+    type: 'confirm'
+    default?: boolean
+  }
+
+  export interface InputQuestion extends QuestionBase {
+    type: 'input'
+    default?: string
+  }
+
+  export interface ListQuestion extends QuestionBase {
+    type: 'list'
+    choices: string[]
+    default?: string
+  }
+
+  export type Question = ConfirmQuestion | InputQuestion | ListQuestion
+
+  export interface Inquirer {
+    prompt<T extends Record<string, unknown>>(questions: Question[]): Promise<T>
+    createPromptModule(): (questions: Question[]) => Promise<Record<string, unknown>>
+  }
+
+  const inquirer: Inquirer
+  export default inquirer
+}

package/src/utils/agentParser.ts

@@ -0,0 +1,67 @@
+import type { Agent } from '../types/agent.js'
+
+export function toSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[·•&]/g, ' ')
+    .replace(/[^\w\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+function getFieldValue(lines: string[], pattern: RegExp): string {
+  for (const line of lines) {
+    const m = line.match(pattern)
+    if (m) return (m[1] ?? '').trim()
+  }
+  return ''
+}
+
+export function extractAgentsFromWorkflow(content: string): Agent[] {
+  const agents: Agent[] = []
+
+  // Split into blocks starting with "### Agent N"
+  const blocks = content
+    .split(/(?=^### Agent \d)/m)
+    .filter((b) => /^### Agent \d/.test(b.trimStart()))
+
+  for (const block of blocks) {
+    const lines = block.split('\n')
+
+    const headerMatch = lines[0].match(/^### Agent (\d+)\s*[·•]\s*(.+)$/)
+    if (!headerMatch) continue
+
+    const number = parseInt(headerMatch[1], 10)
+    const name = headerMatch[2].trim()
+    const fullName = `Agent ${number} · ${name}`
+    const slug = toSlug(name)
+
+    const scope = getFieldValue(lines, /Périmètre\s*:\s*(.+)/)
+    const criterion = getFieldValue(lines, /Critère[s]?\s*:\s*(.+)/)
+
+    // Outputs: may be inline or multi-line (indented "- item")
+    const outputs: string[] = []
+    const produitIdx = lines.findIndex((l) => /Produit\s*:/.test(l))
+    if (produitIdx !== -1) {
+      const inlineVal = (lines[produitIdx].match(/Produit\s*:\s*(.+)/)?.[1] ?? '').trim()
+      if (inlineVal) {
+        outputs.push(inlineVal)
+      } else {
+        for (let i = produitIdx + 1; i < lines.length; i++) {
+          const line = lines[i]
+          if (/^\s+[-]/.test(line)) {
+            outputs.push(line.trim().replace(/^-\s*/, ''))
+          } else if (line.trim() !== '' && !/^\s/.test(line)) {
+            break
+          }
+        }
+      }
+    }
+
+    agents.push({ number, name, fullName, slug, scope, outputs, criterion })
+  }
+
+  return agents
+}

package/src/utils/blueprintParser.ts

@@ -0,0 +1,28 @@
+export interface BlueprintFeature {
+  name: string
+  items: string[]
+}
+
+export function parseBlueprint(content: string): BlueprintFeature[] {
+  const features: BlueprintFeature[] = []
+
+  // Locate all ## headings (not # or ###)
+  const sectionRegex = /^## (.+)$/gm
+  const sections: Array<{ name: string; start: number }> = []
+  let m: RegExpExecArray | null
+  while ((m = sectionRegex.exec(content)) !== null) {
+    sections.push({ name: m[1].trim(), start: m.index })
+  }
+
+  for (let i = 0; i < sections.length; i++) {
+    const section = sections[i]
+    const end = i + 1 < sections.length ? sections[i + 1].start : content.length
+    const body = content.slice(section.start, end)
+
+    const items = [...body.matchAll(/^[-*]\s+(.+)$/gm)].map((r) => r[1].trim())
+
+    features.push({ name: section.name, items })
+  }
+
+  return features
+}

package/src/utils/logger.ts

@@ -0,0 +1,16 @@
+import chalk from 'chalk'
+
+export const logger = {
+  info: (message: string): void => {
+    process.stdout.write(chalk.blue('ℹ') + ' ' + message + '\n')
+  },
+  success: (message: string): void => {
+    process.stdout.write(chalk.green('✔') + ' ' + message + '\n')
+  },
+  warn: (message: string): void => {
+    process.stdout.write(chalk.yellow('⚠') + ' ' + message + '\n')
+  },
+  error: (message: string): void => {
+    process.stderr.write(chalk.red('✖') + ' ' + message + '\n')
+  },
+}

package/tests/commands/add.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, afterEach } from 'vitest'
+import { addFeatureToProject } from '../../src/commands/add.js'
+import { readFile, rm, mkdtemp, writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+const INITIAL_WORKFLOW = `# Agent Workflow — my-project
+
+## Stack détectée
+Framework: react | Language: typescript
+
+## Agents
+
+### Agent 1 · Components
+Périmètre : composants UI réutilisables
+Produit   : src/components/
+Critère   : npm test
+
+### Agent 2 · State & Hooks
+Périmètre : state management
+Produit   : src/hooks/
+Critère   : npm test
+`
+
+let tempDir = ''
+
+afterEach(async () => {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true })
+    tempDir = ''
+  }
+})
+
+async function setupProject(workflowContent = INITIAL_WORKFLOW): Promise<string> {
+  tempDir = await mkdtemp(join(tmpdir(), 'agentkit-add-test-'))
+  await writeFile(join(tempDir, 'AGENT_WORKFLOW.md'), workflowContent, 'utf-8')
+  await writeFile(join(tempDir, 'PLAYBOOK.md'), '# PLAYBOOK placeholder\n', 'utf-8')
+  return tempDir
+}
+
+describe('addFeatureToProject', () => {
+  it('appends a new agent block to AGENT_WORKFLOW.md', async () => {
+    const dir = await setupProject()
+    await addFeatureToProject('Add user authentication', dir)
+
+    const workflow = await readFile(join(dir, 'AGENT_WORKFLOW.md'), 'utf-8')
+    expect(workflow).toContain('Agent 3 · User Authentication')
+    expect(workflow).toContain('Add user authentication')
+  })
+
+  it('assigns the correct next agent number', async () => {
+    const dir = await setupProject()
+    const result = await addFeatureToProject('Add dark mode', dir)
+
+    expect(result.agent.number).toBe(3)
+  })
+
+  it('derives a title-cased name from the description', async () => {
+    const dir = await setupProject()
+    const result = await addFeatureToProject('Add payment integration with Stripe', dir)
+
+    expect(result.agent.name).toBe('Payment Integration With Stripe')
+    expect(result.agent.slug).toBe('payment-integration-with-stripe')
+  })
+
+  it('strips common action prefixes from the agent name', async () => {
+    const dir = await setupProject()
+    const r1 = await addFeatureToProject('implement search functionality', dir)
+    expect(r1.agent.name).toBe('Search Functionality')
+
+    const dir2 = await setupProject()
+    const r2 = await addFeatureToProject('create admin dashboard', dir2)
+    expect(r2.agent.name).toBe('Admin Dashboard')
+  })
+
+  it('creates the agent skills folder with skills.md and context.md', async () => {
+    const dir = await setupProject()
+    const result = await addFeatureToProject('Add notifications', dir)
+
+    const skillsContent = await readFile(
+      join(result.agentDirPath, 'skills.md'),
+      'utf-8',
+    )
+    const contextContent = await readFile(
+      join(result.agentDirPath, 'context.md'),
+      'utf-8',
+    )
+
+    expect(skillsContent).toContain(result.agent.fullName)
+    expect(contextContent).toContain('Add notifications')
+  })
+
+  it('regenerates PLAYBOOK.md with all agents including the new one', async () => {
+    const dir = await setupProject()
+    await addFeatureToProject('Add analytics dashboard', dir)
+
+    const playbook = await readFile(join(dir, 'PLAYBOOK.md'), 'utf-8')
+    expect(playbook).toContain('Agent 1 · Components')
+    expect(playbook).toContain('Agent 2 · State & Hooks')
+    expect(playbook).toContain('Agent 3 · Analytics Dashboard')
+  })
+
+  it('reads project name from package.json when available', async () => {
+    const dir = await setupProject()
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({ name: 'my-custom-app' }),
+      'utf-8',
+    )
+    await addFeatureToProject('Add search', dir)
+
+    const playbook = await readFile(join(dir, 'PLAYBOOK.md'), 'utf-8')
+    expect(playbook).toContain('my-custom-app')
+  })
+
+  it('throws an error when AGENT_WORKFLOW.md is missing', async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'agentkit-add-test-'))
+    await expect(addFeatureToProject('Add feature', tempDir)).rejects.toThrow(
+      'AGENT_WORKFLOW.md introuvable',
+    )
+  })
+
+  it('works on a project with no existing agents', async () => {
+    const dir = await setupProject('# Agent Workflow\n\n## Agents\n')
+    const result = await addFeatureToProject('Add first feature', dir)
+
+    expect(result.agent.number).toBe(1)
+    expect(result.agent.name).toBe('First Feature')
+  })
+})

package/tests/detectors/fixtures/express-app/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "express-app",
+  "dependencies": {
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21"
+  }
+}

package/tests/detectors/fixtures/fastapi-app/requirements.txt

@@ -0,0 +1,3 @@
+fastapi==0.104.0
+uvicorn[standard]==0.24.0
+pydantic==2.4.2

package/tests/detectors/fixtures/nextjs-app/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "nextjs-app",
+  "dependencies": {
+    "next": "^14.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0"
+  }
+}

package/tests/detectors/fixtures/no-git/README.md

@@ -0,0 +1,2 @@
+# no-git fixture
+This directory has no .git folder — used to test gitDetector.

package/tests/detectors/fixtures/react-app/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "react-app",
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "vite": "^5.0.0"
+  }
+}

package/tests/detectors/fixtures/tauri-app/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "tauri-app",
+  "dependencies": {
+    "@tauri-apps/api": "^1.5.0"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^1.5.0",
+    "typescript": "^5.0.0"
+  }
+}

package/tests/detectors/fixtures/tauri-app/src-tauri/tauri.conf.json

@@ -0,0 +1,12 @@
+{
+  "build": {
+    "beforeDevCommand": "npm run dev",
+    "beforeBuildCommand": "npm run build",
+    "devPath": "http://localhost:5173",
+    "distDir": "../dist"
+  },
+  "package": {
+    "productName": "tauri-app",
+    "version": "0.1.0"
+  }
+}

package/tests/detectors/gitDetector.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+import { isGitRepo } from '../../src/detectors/gitDetector.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const projectRoot = join(__dirname, '..', '..')
+const noGitDir = join(__dirname, 'fixtures', 'no-git')
+const nonExistentDir = join(__dirname, 'fixtures', 'nonexistent-xyz')
+
+describe('isGitRepo', () => {
+  it('returns true for the project root (which is a git repo)', async () => {
+    const result = await isGitRepo(projectRoot)
+    expect(result).toBe(true)
+  })
+
+  it('returns false for a directory without .git', async () => {
+    const result = await isGitRepo(noGitDir)
+    expect(result).toBe(false)
+  })
+
+  it('returns false for a non-existent path', async () => {
+    const result = await isGitRepo(nonExistentDir)
+    expect(result).toBe(false)
+  })
+})

package/tests/detectors/stackDetector.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+import { detectStack } from '../../src/detectors/stackDetector.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixturesDir = join(__dirname, 'fixtures')
+
+describe('detectStack', () => {
+  it('detects React', async () => {
+    const result = await detectStack(join(fixturesDir, 'react-app'))
+    expect(result.framework).toBe('react')
+    expect(result.language).toBe('javascript')
+    expect(result.hasTypeScript).toBe(false)
+  })
+
+  it('detects Next.js (priority over React)', async () => {
+    const result = await detectStack(join(fixturesDir, 'nextjs-app'))
+    expect(result.framework).toBe('nextjs')
+    expect(result.hasTypeScript).toBe(true)
+    expect(result.language).toBe('typescript')
+  })
+
+  it('detects Tauri via @tauri-apps/api and src-tauri/', async () => {
+    const result = await detectStack(join(fixturesDir, 'tauri-app'))
+    expect(result.framework).toBe('tauri')
+    expect(result.hasTypeScript).toBe(true)
+  })
+
+  it('detects FastAPI (Python)', async () => {
+    const result = await detectStack(join(fixturesDir, 'fastapi-app'))
+    expect(result.framework).toBe('fastapi')
+    expect(result.language).toBe('python')
+    expect(result.hasTypeScript).toBe(false)
+  })
+
+  it('detects Express', async () => {
+    const result = await detectStack(join(fixturesDir, 'express-app'))
+    expect(result.framework).toBe('express')
+    expect(result.language).toBe('javascript')
+  })
+
+  it('returns unknown for a directory with no recognizable files', async () => {
+    const result = await detectStack(join(fixturesDir, 'no-git'))
+    expect(result.framework).toBe('unknown')
+    expect(result.language).toBe('unknown')
+  })
+})

package/tests/generators/blueprintSupport.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest'
+import { parseBlueprint } from '../../src/utils/blueprintParser.js'
+import { generateClaudeMd } from '../../src/generators/claudeMdGenerator.js'
+import { generateWorkflow } from '../../src/generators/workflowGenerator.js'
+import { extractAgentsFromWorkflow } from '../../src/utils/agentParser.js'
+import type { StackInfo } from '../../src/detectors/stackDetector.js'
+
+const BLUEPRINT = `# My App Blueprint
+
+## Authentication
+- JWT tokens
+- OAuth2 with Google
+- Password reset flow
+
+## Dashboard
+- User statistics
+- Charts and graphs
+- CSV export
+
+## API
+- REST endpoints
+- Rate limiting
+- API key management
+`
+
+const REACT_STACK: StackInfo = {
+  framework: 'react',
+  language: 'typescript',
+  hasTypeScript: true,
+  extras: [],
+}
+
+describe('parseBlueprint', () => {
+  it('extracts features from ## headings', () => {
+    const features = parseBlueprint(BLUEPRINT)
+    expect(features).toHaveLength(3)
+    expect(features[0].name).toBe('Authentication')
+    expect(features[1].name).toBe('Dashboard')
+    expect(features[2].name).toBe('API')
+  })
+
+  it('extracts list items under each feature', () => {
+    const features = parseBlueprint(BLUEPRINT)
+    expect(features[0].items).toContain('JWT tokens')
+    expect(features[0].items).toContain('OAuth2 with Google')
+    expect(features[1].items).toContain('User statistics')
+    expect(features[2].items).toContain('REST endpoints')
+  })
+
+  it('returns empty array for content with no ## headings', () => {
+    expect(parseBlueprint('# Title\nSome text without sections.')).toEqual([])
+  })
+
+  it('handles features with no list items', () => {
+    const features = parseBlueprint('## Feature A\nJust prose.\n## Feature B\n- item1')
+    expect(features[0].items).toEqual([])
+    expect(features[1].items).toEqual(['item1'])
+  })
+})
+
+describe('generateClaudeMd with blueprint', () => {
+  it('returns same output as without blueprint when blueprintContent is undefined', () => {
+    expect(generateClaudeMd(REACT_STACK)).toBe(generateClaudeMd(REACT_STACK, undefined))
+  })
+
+  it('includes a Features section when blueprint is provided', () => {
+    const result = generateClaudeMd(REACT_STACK, BLUEPRINT)
+    expect(result).toContain('## Features (Blueprint)')
+    expect(result).toContain('Authentication')
+    expect(result).toContain('Dashboard')
+    expect(result).toContain('API')
+  })
+
+  it('includes blueprint sub-items', () => {
+    const result = generateClaudeMd(REACT_STACK, BLUEPRINT)
+    expect(result).toContain('JWT tokens')
+    expect(result).toContain('User statistics')
+  })
+
+  it('places Features section before Conventions', () => {
+    const result = generateClaudeMd(REACT_STACK, BLUEPRINT)
+    const featIdx = result.indexOf('## Features (Blueprint)')
+    const convIdx = result.indexOf('## Conventions')
+    expect(featIdx).toBeGreaterThan(-1)
+    expect(convIdx).toBeGreaterThan(-1)
+    expect(featIdx).toBeLessThan(convIdx)
+  })
+
+  it('still contains stack-specific content', () => {
+    const result = generateClaudeMd(REACT_STACK, BLUEPRINT)
+    expect(result).toContain('React')
+    expect(result).toContain('## Stack')
+  })
+})
+
+describe('generateWorkflow with blueprint', () => {
+  it('returns same output as without blueprint when blueprintContent is undefined', () => {
+    expect(generateWorkflow(REACT_STACK)).toBe(generateWorkflow(REACT_STACK, undefined))
+  })
+
+  it('generates one agent per blueprint feature plus a CI agent', () => {
+    const result = generateWorkflow(REACT_STACK, BLUEPRINT)
+    expect(result).toContain('Agent 1 · Authentication')
+    expect(result).toContain('Agent 2 · Dashboard')
+    expect(result).toContain('Agent 3 · API')
+    expect(result).toContain('Agent 4 · Tests & CI')
+  })
+
+  it('each agent block is parseable by extractAgentsFromWorkflow', () => {
+    const result = generateWorkflow(REACT_STACK, BLUEPRINT)
+    const agents = extractAgentsFromWorkflow(result)
+    expect(agents).toHaveLength(4)
+    expect(agents[0].name).toBe('Authentication')
+    expect(agents[0].slug).toBe('authentication')
+    expect(agents[3].name).toBe('Tests & CI')
+    expect(agents[3].slug).toBe('tests-ci')
+  })
+
+  it('includes blueprint feature items as outputs', () => {
+    const result = generateWorkflow(REACT_STACK, BLUEPRINT)
+    expect(result).toContain('JWT tokens')
+    expect(result).toContain('User statistics')
+  })
+
+  it('includes stack information in the header', () => {
+    const result = generateWorkflow(REACT_STACK, BLUEPRINT)
+    expect(result).toContain('react')
+    expect(result).toContain('typescript')
+  })
+})

package/tests/generators/claudeMdGenerator.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest'
+import { generateClaudeMd } from '../../src/generators/claudeMdGenerator.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,
+  }
+}
+
+describe('generateClaudeMd', () => {
+  it('returns a non-empty string for every supported framework', () => {
+    const frameworks: StackInfo['framework'][] = [
+      'react', 'nextjs', 'tauri', 'fastapi', 'express', 'node', 'unknown',
+    ]
+    for (const framework of frameworks) {
+      const result = generateClaudeMd(makeStack(framework))
+      expect(typeof result).toBe('string')
+      expect(result.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('React — mentions React and expected sections', () => {
+    const result = generateClaudeMd(makeStack('react'))
+    expect(result).toContain('React')
+    expect(result).toContain('## Stack')
+    expect(result).toContain('## Commands')
+    expect(result).toContain('## Conventions')
+  })
+
+  it('React — reflects TypeScript when hasTypeScript is true', () => {
+    const result = generateClaudeMd(makeStack('react', { hasTypeScript: true }))
+    expect(result).toContain('TypeScript')
+  })
+
+  it('React — reflects JavaScript when hasTypeScript is false', () => {
+    const result = generateClaudeMd(makeStack('react', { hasTypeScript: false }))
+    expect(result).toContain('JavaScript')
+  })
+
+  it('Next.js — mentions Next.js and TypeScript', () => {
+    const result = generateClaudeMd(makeStack('nextjs', { hasTypeScript: true }))
+    expect(result).toContain('Next.js')
+    expect(result).toContain('TypeScript')
+  })
+
+  it('Next.js — includes Prisma section when extra is present', () => {
+    const result = generateClaudeMd(makeStack('nextjs', { extras: ['prisma'] }))
+    expect(result).toContain('Prisma')
+  })
+
+  it('Tauri — mentions Tauri and Rust', () => {
+    const result = generateClaudeMd(makeStack('tauri', { hasTypeScript: true }))
+    expect(result).toContain('Tauri')
+    expect(result).toContain('Rust')
+  })
+
+  it('FastAPI — mentions FastAPI and Python', () => {
+    const result = generateClaudeMd(makeStack('fastapi'))
+    expect(result).toContain('FastAPI')
+    expect(result).toContain('Python')
+  })
+
+  it('Express — mentions Express', () => {
+    const result = generateClaudeMd(makeStack('express'))
+    expect(result).toContain('Express')
+  })
+
+  it('Node — mentions Node.js', () => {
+    const result = generateClaudeMd(makeStack('node'))
+    expect(result).toContain('Node.js')
+  })
+
+  it('unknown — returns a fallback string', () => {
+    const result = generateClaudeMd(makeStack('unknown'))
+    expect(typeof result).toBe('string')
+    expect(result.length).toBeGreaterThan(0)
+  })
+})