Compare commits

...
Author SHA1 Message Date
Rohit Ghumare 6eb06f647d fix(agents): getAllAdapters returns correct agent types
Fixed getAllAdapters() to return the correct agent type from the
record keys instead of relying on adapter.type property, which
was returning 'universal' for all UniversalAdapter instances.

This fixes the E2E test that checks for all 32 agents in init --list
output (cline, codebuddy, commandcode, etc. were showing as 'universal').
2026-01-29 19:19:35 +00:00
Rohit Ghumare 2d094fdd71 feat(primer): support multi-format output rendering
Refactored generateContent to properly respect the format field
instead of always producing Markdown output.

- Added FormatRenderer interface with format-specific implementations
- Created renderers for markdown, mdc, json, xml formats
- JSON format generates structured data via generateJsonContent()
- MDC format includes YAML frontmatter via wrap() method
- XML format properly escapes content with escapeXml()
- Updated all section generators to accept and use the renderer
2026-01-29 19:07:59 +00:00
Rohit Ghumare e9b5c647e2 fix: additional CodeRabbit review fixes for primer
- Fix Python detection to use correct source file (pyproject.toml, requirements.txt, or setup.py)
- Escape regex special characters in glob pattern matching (e.g., *.module.css)
- Derive ALL_AGENTS from AGENT_CONFIG to avoid divergence
- Map agent config format to template format based on file extension
2026-01-29 18:45:43 +00:00
Rohit Ghumare 8a51c73f2a fix: address CodeRabbit PR review issues for primer
- Fix OS-agnostic path handling in analyzer using path.relative() and path.sep
- Prevent output collisions when multiple agents produce same filename
- Add defensive check in test before accessing generated[0]
- Remove duplicate projectPath parameter in CLI primer command
- Use PackageManager enum instead of z.string() for type safety
- Detect monorepos before src-based layout to prevent misclassification
- Document --output and --json flags in README examples
2026-01-29 18:34:06 +00:00
Rohit Ghumare db277fedbc feat: add skillkit primer command for AI instruction generation
New feature that analyzes codebases and generates AI instruction files
for all 32 supported agents (inspired by pierceboggan/primer).

## New Module: packages/core/src/primer/
- types.ts: Zod schemas and TypeScript interfaces
- analyzer.ts: Codebase analysis (languages, frameworks, conventions)
- generator.ts: Agent-specific instruction file generation
- index.ts: Barrel exports
- __tests__/primer.test.ts: 15 comprehensive tests

## CLI Command: skillkit primer
- --agent/-a: Generate for specific agents
- --all-agents/-A: Generate for all 32 agents
- --output/-o: Custom output directory
- --dry-run/-n: Preview without writing
- --analyze-only: Show analysis only
- --verbose/-v: Detailed output
- --json/-j: JSON output

## Features
- Detects: languages, frameworks, package managers, libraries
- Analyzes: project structure, code conventions, CI/CD, Docker
- Generates: CLAUDE.md, .cursorrules, copilot-instructions.md, etc.
2026-01-29 13:36:00 +00:00
11 changed files with 2219 additions and 3 deletions
+17
View File
@@ -313,6 +313,23 @@ skillkit context init # Initialize project context
skillkit context sync # Sync context to agents
```
### AI Instruction Generation (Primer)
Generate AI instruction files for all 32 supported agents based on your codebase analysis:
```bash
skillkit primer # Analyze codebase, generate for detected agents
skillkit primer --all-agents # Generate for all 32 agents
skillkit primer --agent claude-code,cursor # Specific agents only
skillkit primer --dry-run # Preview without writing files
skillkit primer --analyze-only # Only show codebase analysis
skillkit primer --output ./instructions # Write to custom directory
skillkit primer --json # Output analysis as JSON (for scripting)
skillkit primer --json --analyze-only # Machine-readable analysis
```
Inspired by [primer](https://github.com/pierceboggan/primer) but extended for all SkillKit agents.
### Custom AI Sub-Agents
```bash
+2 -1
View File
@@ -48,7 +48,6 @@ import {
AgentTranslateCommand,
AgentSyncCommand,
AgentValidateCommand,
// New commands (Phase 21)
CheckCommand,
FindCommand,
ManifestCommand,
@@ -57,6 +56,7 @@ import {
ManifestRemoveCommand,
ManifestInstallCommand,
ManifestGenerateCommand,
PrimerCommand,
} from '@skillkit/cli';
const __filename = fileURLToPath(import.meta.url);
@@ -127,5 +127,6 @@ cli.register(ManifestAddCommand);
cli.register(ManifestRemoveCommand);
cli.register(ManifestInstallCommand);
cli.register(ManifestGenerateCommand);
cli.register(PrimerCommand);
cli.runExit(process.argv.slice(2));
+10 -2
View File
@@ -81,8 +81,16 @@ export function getAdapter(type: AgentType): AgentAdapter {
return adapters[type];
}
export function getAllAdapters(): AgentAdapter[] {
return Object.values(adapters);
export interface AgentAdapterWithType extends AgentAdapter {
readonly agentType: AgentType;
}
export function getAllAdapters(): AgentAdapterWithType[] {
return Object.entries(adapters).map(([type, adapter]) => ({
...adapter,
type: type as AgentType,
agentType: type as AgentType,
}));
}
export async function detectAgent(): Promise<AgentType> {
+1
View File
@@ -53,3 +53,4 @@ export {
ManifestInstallCommand,
ManifestGenerateCommand,
} from './manifest.js';
export { PrimerCommand } from './primer.js';
+362
View File
@@ -0,0 +1,362 @@
import { Command, Option } from 'clipanion';
import { resolve } from 'node:path';
import chalk from 'chalk';
import {
type AgentType,
AgentType as AgentTypeSchema,
generatePrimer,
analyzePrimer,
AGENT_CONFIG,
} from '@skillkit/core';
export class PrimerCommand extends Command {
static override paths = [['primer']];
static override usage = Command.Usage({
description: 'Analyze codebase and generate AI instruction files for agents',
details: `
The primer command analyzes your codebase to detect languages, frameworks,
patterns, and conventions, then generates customized instruction files
for AI coding agents.
By default, it generates instructions for detected agents in your project.
Use --all-agents to generate for all 32 supported agents.
Inspired by github.com/pierceboggan/primer but extended for all SkillKit agents.
`,
examples: [
['Generate for detected agents', '$0 primer'],
['Generate for all 32 agents', '$0 primer --all-agents'],
['Generate for specific agents', '$0 primer --agent claude-code,cursor,github-copilot'],
['Custom output directory', '$0 primer --output ./instructions'],
['Preview without writing files', '$0 primer --dry-run'],
['Only show analysis', '$0 primer --analyze-only'],
['Verbose output', '$0 primer --verbose'],
],
});
agent = Option.String('--agent,-a', {
description: 'Comma-separated list of agents to generate for',
});
allAgents = Option.Boolean('--all-agents,-A', false, {
description: 'Generate for all 32 supported agents',
});
output = Option.String('--output,-o', {
description: 'Output directory for generated files',
});
dryRun = Option.Boolean('--dry-run,-n', false, {
description: 'Preview what would be generated without writing files',
});
analyzeOnly = Option.Boolean('--analyze-only', false, {
description: 'Only show codebase analysis, do not generate files',
});
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Show detailed output',
});
includeExamples = Option.Boolean('--examples', false, {
description: 'Include code examples in generated instructions',
});
json = Option.Boolean('--json,-j', false, {
description: 'Output analysis in JSON format',
});
directory = Option.String('--dir,-d', {
description: 'Project directory to analyze (default: current directory)',
});
async execute(): Promise<number> {
const projectPath = resolve(this.directory || process.cwd());
if (this.analyzeOnly) {
return this.runAnalysis(projectPath);
}
return this.runGenerate(projectPath);
}
private async runAnalysis(projectPath: string): Promise<number> {
console.log(chalk.cyan('Analyzing codebase...\n'));
try {
const analysis = analyzePrimer(projectPath);
if (this.json) {
console.log(JSON.stringify(analysis, null, 2));
return 0;
}
this.printAnalysis(analysis);
return 0;
} catch (error) {
console.error(chalk.red('Analysis failed:'), error instanceof Error ? error.message : error);
return 1;
}
}
private async runGenerate(projectPath: string): Promise<number> {
const agents = this.parseAgents();
console.log(chalk.cyan('Analyzing codebase and generating AI instructions...\n'));
try {
const result = generatePrimer(projectPath, {
agents,
allAgents: this.allAgents,
outputDir: this.output ? resolve(this.output) : undefined,
dryRun: this.dryRun,
verbose: this.verbose,
includeExamples: this.includeExamples,
});
if (this.verbose) {
this.printAnalysis(result.analysis);
console.log();
}
if (result.generated.length === 0) {
console.log(chalk.yellow('No instruction files generated.'));
if (result.errors.length > 0) {
for (const error of result.errors) {
console.log(chalk.red(` Error: ${error}`));
}
}
return 1;
}
console.log(chalk.bold('Generated Instruction Files:\n'));
for (const instruction of result.generated) {
const status = this.dryRun ? chalk.yellow('(dry-run)') : chalk.green('created');
console.log(` ${chalk.green('●')} ${chalk.bold(instruction.agent)}`);
console.log(` ${chalk.gray(instruction.filepath)} ${status}`);
}
console.log();
if (result.warnings.length > 0) {
console.log(chalk.yellow('Warnings:'));
for (const warning of result.warnings) {
console.log(` ${chalk.yellow('⚠')} ${warning}`);
}
console.log();
}
if (result.errors.length > 0) {
console.log(chalk.red('Errors:'));
for (const error of result.errors) {
console.log(` ${chalk.red('✗')} ${error}`);
}
console.log();
}
const summary = this.dryRun
? `Would generate ${result.generated.length} instruction file(s)`
: `Generated ${result.generated.length} instruction file(s)`;
console.log(chalk.bold(summary));
if (this.dryRun) {
console.log(chalk.gray('\n(Dry run - no files were written)'));
}
return result.success ? 0 : 1;
} catch (error) {
console.error(chalk.red('Generation failed:'), error instanceof Error ? error.message : error);
return 1;
}
}
private parseAgents(): AgentType[] | undefined {
if (!this.agent) return undefined;
const agents: AgentType[] = [];
const parts = this.agent.split(',').map(s => s.trim());
for (const part of parts) {
const result = AgentTypeSchema.safeParse(part);
if (result.success) {
agents.push(result.data);
} else {
console.warn(chalk.yellow(`Unknown agent: ${part}`));
}
}
return agents.length > 0 ? agents : undefined;
}
private printAnalysis(analysis: ReturnType<typeof analyzePrimer>): void {
const { project, languages, packageManagers, stack, structure, conventions, ci, docker, buildCommands, importantFiles } = analysis;
console.log(chalk.bold('Project Information'));
console.log(` Name: ${chalk.cyan(project.name)}`);
if (project.description) {
console.log(` Description: ${project.description}`);
}
if (project.type) {
console.log(` Type: ${project.type}`);
}
if (project.version) {
console.log(` Version: ${project.version}`);
}
console.log();
if (languages.length > 0) {
console.log(chalk.bold('Languages'));
for (const lang of languages) {
const version = lang.version ? ` (${lang.version})` : '';
console.log(` ${chalk.green('●')} ${lang.name}${version}`);
}
console.log();
}
if (packageManagers.length > 0) {
console.log(chalk.bold('Package Managers'));
console.log(` ${chalk.cyan(packageManagers.join(', '))}`);
console.log();
}
if (stack.frameworks.length > 0) {
console.log(chalk.bold('Frameworks'));
for (const fw of stack.frameworks) {
const version = fw.version ? ` (${fw.version})` : '';
console.log(` ${chalk.green('●')} ${fw.name}${version}`);
}
console.log();
}
if (stack.libraries.length > 0) {
console.log(chalk.bold('Libraries'));
for (const lib of stack.libraries.slice(0, 10)) {
const version = lib.version ? ` (${lib.version})` : '';
console.log(` ${chalk.green('●')} ${lib.name}${version}`);
}
if (stack.libraries.length > 10) {
console.log(` ${chalk.gray(`...and ${stack.libraries.length - 10} more`)}`);
}
console.log();
}
if (stack.styling.length > 0) {
console.log(chalk.bold('Styling'));
for (const style of stack.styling) {
console.log(` ${chalk.green('●')} ${style.name}`);
}
console.log();
}
if (stack.testing.length > 0) {
console.log(chalk.bold('Testing'));
for (const test of stack.testing) {
console.log(` ${chalk.green('●')} ${test.name}`);
}
console.log();
}
if (stack.databases.length > 0) {
console.log(chalk.bold('Databases'));
for (const db of stack.databases) {
console.log(` ${chalk.green('●')} ${db.name}`);
}
console.log();
}
if (structure) {
console.log(chalk.bold('Project Structure'));
if (structure.type) {
console.log(` Type: ${structure.type}`);
}
if (structure.srcDir) {
console.log(` Source: ${structure.srcDir}/`);
}
if (structure.testDir) {
console.log(` Tests: ${structure.testDir}/`);
}
if (structure.hasWorkspaces) {
console.log(` Monorepo: Yes`);
if (structure.workspaces) {
console.log(` Workspaces: ${structure.workspaces.join(', ')}`);
}
}
console.log();
}
if (conventions && Object.keys(conventions).some(k => conventions[k as keyof typeof conventions] !== undefined)) {
console.log(chalk.bold('Code Conventions'));
if (conventions.indentation) {
console.log(` Indentation: ${conventions.indentation}`);
}
if (conventions.quotes) {
console.log(` Quotes: ${conventions.quotes}`);
}
if (conventions.semicolons !== undefined) {
console.log(` Semicolons: ${conventions.semicolons ? 'yes' : 'no'}`);
}
if (conventions.trailingCommas) {
console.log(` Trailing Commas: ${conventions.trailingCommas}`);
}
console.log();
}
if (ci && ci.hasCI) {
console.log(chalk.bold('CI/CD'));
console.log(` Provider: ${ci.provider}`);
if (ci.hasCD) {
console.log(` Deployment: Yes`);
}
console.log();
}
if (docker && (docker.hasDockerfile || docker.hasCompose)) {
console.log(chalk.bold('Docker'));
if (docker.hasDockerfile) {
console.log(` Dockerfile: Yes`);
if (docker.baseImage) {
console.log(` Base Image: ${docker.baseImage}`);
}
}
if (docker.hasCompose) {
console.log(` Docker Compose: Yes`);
}
console.log();
}
if (buildCommands && Object.keys(buildCommands).some(k => buildCommands[k as keyof typeof buildCommands])) {
console.log(chalk.bold('Build Commands'));
if (buildCommands.install) {
console.log(` Install: ${chalk.gray(buildCommands.install)}`);
}
if (buildCommands.dev) {
console.log(` Dev: ${chalk.gray(buildCommands.dev)}`);
}
if (buildCommands.build) {
console.log(` Build: ${chalk.gray(buildCommands.build)}`);
}
if (buildCommands.test) {
console.log(` Test: ${chalk.gray(buildCommands.test)}`);
}
console.log();
}
if (importantFiles.length > 0 && this.verbose) {
console.log(chalk.bold('Important Files'));
for (const file of importantFiles.slice(0, 15)) {
console.log(` ${chalk.gray(file)}`);
}
if (importantFiles.length > 15) {
console.log(` ${chalk.gray(`...and ${importantFiles.length - 15} more`)}`);
}
console.log();
}
console.log(chalk.bold('Available Agents'));
console.log(chalk.gray(` Use --all-agents to generate for all ${Object.keys(AGENT_CONFIG).length} agents`));
console.log(chalk.gray(` Use --agent <name> to generate for specific agents`));
}
}
+3
View File
@@ -77,3 +77,6 @@ export * from './skill-translator.js';
export * from './manifest/index.js';
export * from './quality/index.js';
// Primer (AI Instruction Generator)
export * from './primer/index.js';
@@ -0,0 +1,199 @@
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { PrimerAnalyzer, analyzePrimer } from '../analyzer.js';
import { PrimerGenerator, generatePrimer } from '../generator.js';
const TEST_DIR = join(tmpdir(), 'skillkit-primer-test-' + Date.now());
describe('Primer', () => {
beforeAll(() => {
mkdirSync(TEST_DIR, { recursive: true });
writeFileSync(
join(TEST_DIR, 'package.json'),
JSON.stringify({
name: 'test-project',
version: '1.0.0',
description: 'A test project',
scripts: {
build: 'tsc',
test: 'vitest',
lint: 'eslint .',
},
dependencies: {
react: '^18.0.0',
next: '^14.0.0',
},
devDependencies: {
typescript: '^5.0.0',
tailwindcss: '^3.0.0',
vitest: '^1.0.0',
eslint: '^8.0.0',
prettier: '^3.0.0',
},
})
);
writeFileSync(join(TEST_DIR, 'tsconfig.json'), JSON.stringify({ compilerOptions: {} }));
mkdirSync(join(TEST_DIR, 'src'), { recursive: true });
writeFileSync(join(TEST_DIR, 'src', 'index.ts'), 'export const hello = "world";');
mkdirSync(join(TEST_DIR, '.github', 'workflows'), { recursive: true });
writeFileSync(join(TEST_DIR, '.github', 'workflows', 'ci.yml'), 'name: CI');
writeFileSync(join(TEST_DIR, 'pnpm-lock.yaml'), '');
});
afterAll(() => {
if (existsSync(TEST_DIR)) {
rmSync(TEST_DIR, { recursive: true, force: true });
}
});
describe('PrimerAnalyzer', () => {
it('should detect project info', () => {
const analyzer = new PrimerAnalyzer(TEST_DIR);
const analysis = analyzer.analyze();
expect(analysis.project.name).toBe('test-project');
expect(analysis.project.version).toBe('1.0.0');
expect(analysis.project.description).toBe('A test project');
});
it('should detect languages', () => {
const analysis = analyzePrimer(TEST_DIR);
const typescript = analysis.languages.find(l => l.name === 'typescript');
expect(typescript).toBeDefined();
expect(typescript?.version).toBe('5.0.0');
});
it('should detect package managers', () => {
const analysis = analyzePrimer(TEST_DIR);
expect(analysis.packageManagers).toContain('pnpm');
});
it('should detect frameworks', () => {
const analysis = analyzePrimer(TEST_DIR);
const react = analysis.stack.frameworks.find(f => f.name === 'react');
const nextjs = analysis.stack.frameworks.find(f => f.name === 'nextjs');
expect(react).toBeDefined();
expect(nextjs).toBeDefined();
});
it('should detect styling', () => {
const analysis = analyzePrimer(TEST_DIR);
const tailwind = analysis.stack.styling.find(s => s.name === 'tailwindcss');
expect(tailwind).toBeDefined();
});
it('should detect testing', () => {
const analysis = analyzePrimer(TEST_DIR);
const vitest = analysis.stack.testing.find(t => t.name === 'vitest');
expect(vitest).toBeDefined();
});
it('should detect tools', () => {
const analysis = analyzePrimer(TEST_DIR);
const eslint = analysis.stack.tools.find(t => t.name === 'eslint');
const prettier = analysis.stack.tools.find(t => t.name === 'prettier');
expect(eslint).toBeDefined();
expect(prettier).toBeDefined();
});
it('should detect CI config', () => {
const analysis = analyzePrimer(TEST_DIR);
expect(analysis.ci?.hasCI).toBe(true);
expect(analysis.ci?.provider).toBe('github-actions');
});
it('should detect project structure', () => {
const analysis = analyzePrimer(TEST_DIR);
expect(analysis.structure?.type).toBe('src-based');
expect(analysis.structure?.srcDir).toBe('src');
});
it('should extract build commands', () => {
const analysis = analyzePrimer(TEST_DIR);
expect(analysis.buildCommands?.build).toBe('pnpm build');
expect(analysis.buildCommands?.test).toBe('pnpm test');
expect(analysis.buildCommands?.lint).toBe('pnpm lint');
});
});
describe('PrimerGenerator', () => {
it('should generate instruction files for detected agents', () => {
const result = generatePrimer(TEST_DIR, { dryRun: true });
expect(result.success).toBe(true);
expect(result.generated.length).toBeGreaterThan(0);
expect(result.errors.length).toBe(0);
});
it('should generate for specific agents', () => {
const result = generatePrimer(TEST_DIR, {
agents: ['claude-code', 'cursor'],
dryRun: true,
});
expect(result.success).toBe(true);
expect(result.generated.length).toBe(2);
const agents = result.generated.map(g => g.agent);
expect(agents).toContain('claude-code');
expect(agents).toContain('cursor');
});
it('should analyze only when requested', () => {
const result = generatePrimer(TEST_DIR, { analyzeOnly: true });
expect(result.success).toBe(true);
expect(result.generated.length).toBe(0);
expect(result.analysis).toBeDefined();
expect(result.analysis.project.name).toBe('test-project');
});
it('should generate content with correct sections', () => {
const result = generatePrimer(TEST_DIR, {
agents: ['claude-code'],
dryRun: true,
});
expect(result.success).toBe(true);
expect(result.generated.length).toBeGreaterThan(0);
const instruction = result.generated[0];
expect(instruction.content).toContain('# test-project');
expect(instruction.content).toContain('## Technology Stack');
expect(instruction.content).toContain('## Development Commands');
expect(instruction.content).toContain('## Development Guidelines');
});
it('should respect output directory option', () => {
const outputDir = join(TEST_DIR, 'output');
mkdirSync(outputDir, { recursive: true });
const result = generatePrimer(TEST_DIR, {
agents: ['claude-code'],
outputDir,
dryRun: true,
});
expect(result.success).toBe(true);
expect(result.generated[0].filepath).toContain('output');
});
});
});
+658
View File
@@ -0,0 +1,658 @@
import { existsSync, readFileSync, readdirSync } from 'node:fs';
import { join, basename, relative, sep } from 'node:path';
import type {
PrimerAnalysis,
PackageManager,
CodeConvention,
ProjectStructure,
CIConfig,
EnvConfig,
DockerConfig,
} from './types.js';
import { ProjectDetector } from '../context/detector.js';
import type { Detection } from '../context/types.js';
const PACKAGE_MANAGER_FILES: Record<string, PackageManager> = {
'package-lock.json': 'npm',
'pnpm-lock.yaml': 'pnpm',
'yarn.lock': 'yarn',
'bun.lockb': 'bun',
'requirements.txt': 'pip',
'Pipfile.lock': 'pip',
'poetry.lock': 'poetry',
'uv.lock': 'uv',
'Cargo.lock': 'cargo',
'go.sum': 'go',
'pom.xml': 'maven',
'build.gradle': 'gradle',
'build.gradle.kts': 'gradle',
'composer.lock': 'composer',
'Gemfile.lock': 'bundler',
'Podfile.lock': 'cocoapods',
'Package.resolved': 'swift-package-manager',
'packages.lock.json': 'nuget',
};
const CI_CONFIG_FILES: Record<string, CIConfig['provider']> = {
'.github/workflows': 'github-actions',
'.gitlab-ci.yml': 'gitlab-ci',
'.circleci/config.yml': 'circleci',
'Jenkinsfile': 'jenkins',
'.travis.yml': 'travis',
'azure-pipelines.yml': 'azure-pipelines',
};
const IMPORTANT_CONFIG_FILES = [
'package.json',
'tsconfig.json',
'pyproject.toml',
'Cargo.toml',
'go.mod',
'.eslintrc.js',
'.eslintrc.json',
'eslint.config.js',
'.prettierrc',
'prettier.config.js',
'biome.json',
'tailwind.config.js',
'tailwind.config.ts',
'vite.config.ts',
'next.config.js',
'next.config.mjs',
'webpack.config.js',
'rollup.config.js',
'turbo.json',
'nx.json',
'jest.config.js',
'vitest.config.ts',
'playwright.config.ts',
'.env.example',
'docker-compose.yml',
'Dockerfile',
];
export class PrimerAnalyzer {
private projectPath: string;
private packageJson: Record<string, unknown> | null = null;
private files: Set<string> = new Set();
constructor(projectPath: string) {
this.projectPath = projectPath;
}
analyze(): PrimerAnalysis {
this.loadPackageJson();
this.scanFiles();
const detector = new ProjectDetector(this.projectPath);
const stack = detector.analyze();
const patterns = detector.detectPatterns();
const analysis: PrimerAnalysis = {
project: this.getProjectInfo(),
languages: this.detectLanguages(),
packageManagers: this.detectPackageManagers(),
stack,
patterns,
structure: this.detectProjectStructure(),
conventions: this.detectCodeConventions(),
ci: this.detectCIConfig(),
env: this.detectEnvConfig(),
docker: this.detectDockerConfig(),
buildCommands: this.extractBuildCommands(),
importantFiles: this.findImportantFiles(),
codebaseSize: this.estimateCodebaseSize(),
};
return analysis;
}
private loadPackageJson(): void {
const packageJsonPath = join(this.projectPath, 'package.json');
if (existsSync(packageJsonPath)) {
try {
const content = readFileSync(packageJsonPath, 'utf-8');
this.packageJson = JSON.parse(content);
} catch {
this.packageJson = null;
}
}
}
private scanFiles(maxDepth = 3): void {
const scan = (dir: string, depth: number) => {
if (depth > maxDepth) return;
try {
const entries = readdirSync(dir, { withFileTypes: true });
for (const entry of entries) {
const fullPath = join(dir, entry.name);
const relativePath = relative(this.projectPath, fullPath);
if (entry.name.startsWith('.') && entry.name !== '.github' && entry.name !== '.env.example') {
if (!entry.isDirectory()) {
this.files.add(relativePath);
}
continue;
}
if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build' || entry.name === '.git') {
continue;
}
this.files.add(relativePath);
if (entry.isDirectory()) {
scan(fullPath, depth + 1);
}
}
} catch {
// Ignore permission errors
}
};
scan(this.projectPath, 0);
}
private getProjectInfo(): PrimerAnalysis['project'] {
const info: PrimerAnalysis['project'] = {
name: basename(this.projectPath),
};
if (this.packageJson) {
if (typeof this.packageJson.name === 'string') {
info.name = this.packageJson.name;
}
if (typeof this.packageJson.description === 'string') {
info.description = this.packageJson.description;
}
if (typeof this.packageJson.version === 'string') {
info.version = this.packageJson.version;
}
if (typeof this.packageJson.license === 'string') {
info.license = this.packageJson.license;
}
const repo = this.packageJson.repository;
if (typeof repo === 'string') {
info.repository = repo;
} else if (repo && typeof repo === 'object' && 'url' in repo) {
info.repository = String(repo.url);
}
}
const pyprojectPath = join(this.projectPath, 'pyproject.toml');
if (!this.packageJson && existsSync(pyprojectPath)) {
try {
const content = readFileSync(pyprojectPath, 'utf-8');
const nameMatch = content.match(/name\s*=\s*["']([^"']+)["']/);
const versionMatch = content.match(/version\s*=\s*["']([^"']+)["']/);
const descMatch = content.match(/description\s*=\s*["']([^"']+)["']/);
if (nameMatch) info.name = nameMatch[1];
if (versionMatch) info.version = versionMatch[1];
if (descMatch) info.description = descMatch[1];
} catch {
// Ignore
}
}
const cargoPath = join(this.projectPath, 'Cargo.toml');
if (!this.packageJson && existsSync(cargoPath)) {
try {
const content = readFileSync(cargoPath, 'utf-8');
const nameMatch = content.match(/name\s*=\s*["']([^"']+)["']/);
const versionMatch = content.match(/version\s*=\s*["']([^"']+)["']/);
const descMatch = content.match(/description\s*=\s*["']([^"']+)["']/);
if (nameMatch) info.name = nameMatch[1];
if (versionMatch) info.version = versionMatch[1];
if (descMatch) info.description = descMatch[1];
} catch {
// Ignore
}
}
const detector = new ProjectDetector(this.projectPath);
info.type = detector.detectProjectType();
return info;
}
private detectLanguages(): Detection[] {
const languages: Detection[] = [];
if (this.hasFile('tsconfig.json')) {
const version = this.getDepVersion('typescript');
languages.push({
name: 'typescript',
version,
confidence: 100,
source: 'tsconfig.json',
});
}
if (this.packageJson && !this.hasFile('tsconfig.json')) {
languages.push({
name: 'javascript',
confidence: 90,
source: 'package.json',
});
}
if (this.hasFile('pyproject.toml') || this.hasFile('requirements.txt') || this.hasFile('setup.py')) {
const source = this.hasFile('pyproject.toml')
? 'pyproject.toml'
: this.hasFile('requirements.txt')
? 'requirements.txt'
: 'setup.py';
languages.push({
name: 'python',
confidence: 100,
source,
});
}
if (this.hasFile('go.mod')) {
languages.push({
name: 'go',
confidence: 100,
source: 'go.mod',
});
}
if (this.hasFile('Cargo.toml')) {
languages.push({
name: 'rust',
confidence: 100,
source: 'Cargo.toml',
});
}
if (this.hasFile('pom.xml') || this.hasFile('build.gradle') || this.hasFile('build.gradle.kts')) {
languages.push({
name: 'java',
confidence: 100,
source: 'pom.xml',
});
}
if (this.hasFile('Package.swift')) {
languages.push({
name: 'swift',
confidence: 100,
source: 'Package.swift',
});
}
if (this.hasFile('Gemfile')) {
languages.push({
name: 'ruby',
confidence: 100,
source: 'Gemfile',
});
}
if (this.hasFile('composer.json')) {
languages.push({
name: 'php',
confidence: 100,
source: 'composer.json',
});
}
return languages;
}
private detectPackageManagers(): PackageManager[] {
const managers: Set<PackageManager> = new Set();
for (const [file, manager] of Object.entries(PACKAGE_MANAGER_FILES)) {
if (this.hasFile(file)) {
managers.add(manager);
}
}
if (this.packageJson) {
const packageManager = this.packageJson.packageManager;
if (typeof packageManager === 'string') {
const match = packageManager.match(/^(npm|pnpm|yarn|bun)@/);
if (match && ['npm', 'pnpm', 'yarn', 'bun'].includes(match[1])) {
managers.add(match[1] as PackageManager);
}
}
}
return Array.from(managers);
}
private detectProjectStructure(): ProjectStructure {
const structure: ProjectStructure = {
hasWorkspaces: false,
};
if (this.hasFile('packages') || this.hasFile('apps')) {
structure.type = 'monorepo';
} else if (this.hasFile('src')) {
structure.type = 'src-based';
structure.srcDir = 'src';
} else if (this.hasFile('lib')) {
structure.type = 'src-based';
structure.srcDir = 'lib';
} else {
structure.type = 'flat';
}
if (this.hasFile('tests') || this.hasFile('test') || this.hasFile('__tests__')) {
structure.testDir = this.hasFile('tests') ? 'tests' : this.hasFile('test') ? 'test' : '__tests__';
}
if (this.hasFile('docs') || this.hasFile('documentation')) {
structure.docsDir = this.hasFile('docs') ? 'docs' : 'documentation';
}
if (this.packageJson) {
const workspaces = this.packageJson.workspaces;
if (Array.isArray(workspaces)) {
structure.hasWorkspaces = true;
structure.workspaces = workspaces.filter(w => typeof w === 'string') as string[];
structure.type = 'monorepo';
} else if (workspaces && typeof workspaces === 'object' && 'packages' in workspaces) {
structure.hasWorkspaces = true;
structure.workspaces = (workspaces.packages as string[]) || [];
structure.type = 'monorepo';
}
}
if (this.hasFile('pnpm-workspace.yaml')) {
structure.hasWorkspaces = true;
structure.type = 'monorepo';
}
if (this.hasFile('turbo.json') || this.hasFile('nx.json')) {
structure.type = 'monorepo';
}
return structure;
}
private detectCodeConventions(): CodeConvention {
const conventions: CodeConvention = {};
const prettierConfig = this.readConfigFile([
'.prettierrc',
'.prettierrc.json',
'prettier.config.js',
]);
const biomeConfig = this.readConfigFile(['biome.json']);
if (prettierConfig) {
try {
const config = typeof prettierConfig === 'string' ? JSON.parse(prettierConfig) : prettierConfig;
if ('semi' in config) conventions.semicolons = config.semi;
if ('singleQuote' in config) conventions.quotes = config.singleQuote ? 'single' : 'double';
if ('tabWidth' in config) {
conventions.indentation = config.useTabs ? 'tabs' : `spaces-${config.tabWidth}` as 'spaces-2' | 'spaces-4';
}
if ('trailingComma' in config) conventions.trailingCommas = config.trailingComma;
if ('printWidth' in config) conventions.maxLineLength = config.printWidth;
} catch {
// Ignore parse errors
}
}
if (biomeConfig) {
try {
const config = typeof biomeConfig === 'string' ? JSON.parse(biomeConfig) : biomeConfig;
const formatter = config.formatter || {};
const js = config.javascript?.formatter || {};
if (formatter.indentStyle) conventions.indentation = formatter.indentStyle === 'tab' ? 'tabs' : 'spaces-2';
if (formatter.lineWidth) conventions.maxLineLength = formatter.lineWidth;
if (js.quoteStyle) conventions.quotes = js.quoteStyle;
if (js.semicolons) conventions.semicolons = js.semicolons !== 'asNeeded';
if (js.trailingCommas) conventions.trailingCommas = js.trailingCommas;
} catch {
// Ignore parse errors
}
}
if (this.hasFile('tsconfig.json')) {
try {
const tsconfigPath = join(this.projectPath, 'tsconfig.json');
const content = readFileSync(tsconfigPath, 'utf-8');
const tsconfig = JSON.parse(content.replace(/\/\/.*$/gm, '').replace(/,\s*}/g, '}'));
const paths = tsconfig.compilerOptions?.paths;
if (paths && Object.keys(paths).some(k => k.startsWith('@'))) {
conventions.namingStyle = 'camelCase';
}
} catch {
// Ignore
}
}
return conventions;
}
private detectCIConfig(): CIConfig {
const ci: CIConfig = {
hasCI: false,
hasCD: false,
};
for (const [file, provider] of Object.entries(CI_CONFIG_FILES)) {
if (this.hasFile(file)) {
ci.hasCI = true;
ci.provider = provider;
ci.configFile = file;
break;
}
}
if (this.hasFile('.github/workflows')) {
ci.hasCI = true;
ci.provider = 'github-actions';
ci.configFile = '.github/workflows';
try {
const workflowsDir = join(this.projectPath, '.github/workflows');
const workflows = readdirSync(workflowsDir);
const deployWorkflows = workflows.filter(f =>
f.includes('deploy') || f.includes('release') || f.includes('publish')
);
if (deployWorkflows.length > 0) {
ci.hasCD = true;
}
} catch {
// Ignore
}
}
return ci;
}
private detectEnvConfig(): EnvConfig {
const env: EnvConfig = {
hasEnvFile: false,
hasEnvExample: false,
};
env.hasEnvFile = this.hasFile('.env');
env.hasEnvExample = this.hasFile('.env.example') || this.hasFile('.env.template') || this.hasFile('.env.sample');
if (env.hasEnvExample) {
const envExamplePath = join(
this.projectPath,
this.hasFile('.env.example') ? '.env.example' : this.hasFile('.env.template') ? '.env.template' : '.env.sample'
);
try {
const content = readFileSync(envExamplePath, 'utf-8');
const variables = content
.split('\n')
.filter(line => line.trim() && !line.startsWith('#'))
.map(line => line.split('=')[0].trim())
.filter(v => v);
env.envVariables = variables;
} catch {
// Ignore
}
}
return env;
}
private detectDockerConfig(): DockerConfig {
const docker: DockerConfig = {
hasDockerfile: false,
hasCompose: false,
};
docker.hasDockerfile = this.hasFile('Dockerfile');
docker.hasCompose = this.hasFile('docker-compose.yml') || this.hasFile('docker-compose.yaml') || this.hasFile('compose.yml');
if (docker.hasDockerfile) {
try {
const dockerfilePath = join(this.projectPath, 'Dockerfile');
const content = readFileSync(dockerfilePath, 'utf-8');
const fromMatch = content.match(/^FROM\s+(\S+)/m);
if (fromMatch) {
docker.baseImage = fromMatch[1];
}
} catch {
// Ignore
}
}
return docker;
}
private extractBuildCommands(): PrimerAnalysis['buildCommands'] {
const commands: PrimerAnalysis['buildCommands'] = {};
if (this.packageJson && this.packageJson.scripts) {
const scripts = this.packageJson.scripts as Record<string, string>;
if (scripts.build) commands.build = this.getRunCommand('build');
if (scripts.test) commands.test = this.getRunCommand('test');
if (scripts.lint) commands.lint = this.getRunCommand('lint');
if (scripts.format) commands.format = this.getRunCommand('format');
if (scripts.dev) commands.dev = this.getRunCommand('dev');
if (scripts.start) commands.start = this.getRunCommand('start');
}
const packageManagers = this.detectPackageManagers();
if (!commands.install) {
if (packageManagers.includes('pnpm')) {
commands.install = 'pnpm install';
} else if (packageManagers.includes('yarn')) {
commands.install = 'yarn install';
} else if (packageManagers.includes('bun')) {
commands.install = 'bun install';
} else if (packageManagers.includes('npm')) {
commands.install = 'npm install';
} else if (packageManagers.includes('pip') || packageManagers.includes('poetry') || packageManagers.includes('uv')) {
if (packageManagers.includes('poetry')) {
commands.install = 'poetry install';
} else if (packageManagers.includes('uv')) {
commands.install = 'uv sync';
} else {
commands.install = 'pip install -r requirements.txt';
}
} else if (packageManagers.includes('cargo')) {
commands.install = 'cargo build';
} else if (packageManagers.includes('go')) {
commands.install = 'go mod download';
}
}
return commands;
}
private findImportantFiles(): string[] {
const important: string[] = [];
for (const file of IMPORTANT_CONFIG_FILES) {
if (this.hasFile(file)) {
important.push(file);
}
}
if (this.hasFile('README.md')) {
important.push('README.md');
}
if (this.hasFile('CONTRIBUTING.md')) {
important.push('CONTRIBUTING.md');
}
if (this.hasFile('LICENSE') || this.hasFile('LICENSE.md')) {
important.push(this.hasFile('LICENSE') ? 'LICENSE' : 'LICENSE.md');
}
return important;
}
private estimateCodebaseSize(): PrimerAnalysis['codebaseSize'] {
let files = 0;
let directories = 0;
for (const file of this.files) {
if (file.includes(sep)) {
directories++;
}
files++;
}
return {
files,
directories: Math.floor(directories / 3),
};
}
private hasFile(name: string): boolean {
if (name.includes('*')) {
const regex = new RegExp(
name.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
);
for (const file of this.files) {
if (regex.test(file)) return true;
}
return false;
}
return this.files.has(name) || existsSync(join(this.projectPath, name));
}
private getDepVersion(dep: string): string | undefined {
if (!this.packageJson) return undefined;
const deps = this.packageJson.dependencies as Record<string, string> | undefined;
const devDeps = this.packageJson.devDependencies as Record<string, string> | undefined;
const version = deps?.[dep] || devDeps?.[dep];
return version?.replace(/^[\^~>=<]+/, '');
}
private getRunCommand(script: string): string {
const packageManagers = this.detectPackageManagers();
if (packageManagers.includes('pnpm')) {
return `pnpm ${script}`;
} else if (packageManagers.includes('yarn')) {
return `yarn ${script}`;
} else if (packageManagers.includes('bun')) {
return `bun run ${script}`;
}
return `npm run ${script}`;
}
private readConfigFile(files: string[]): unknown | null {
for (const file of files) {
const filePath = join(this.projectPath, file);
if (existsSync(filePath)) {
try {
const content = readFileSync(filePath, 'utf-8');
if (file.endsWith('.json')) {
return JSON.parse(content);
}
return content;
} catch {
// Ignore
}
}
}
return null;
}
}
export function analyzePrimer(projectPath: string): PrimerAnalysis {
const analyzer = new PrimerAnalyzer(projectPath);
return analyzer.analyze();
}
+734
View File
@@ -0,0 +1,734 @@
import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
import { join, dirname } from 'node:path';
import type { AgentType } from '../types.js';
import { AGENT_CONFIG, type AgentDirectoryConfig } from '../agent-config.js';
import type {
PrimerAnalysis,
PrimerOptions,
PrimerResult,
GeneratedInstruction,
AgentInstructionTemplate,
} from './types.js';
import { AGENT_INSTRUCTION_TEMPLATES } from './types.js';
import { analyzePrimer } from './analyzer.js';
const ALL_AGENTS: AgentType[] = Object.keys(AGENT_CONFIG) as AgentType[];
type OutputFormat = 'markdown' | 'mdc' | 'json' | 'xml';
interface FormatRenderer {
h1(text: string): string;
h2(text: string): string;
h3(text: string): string;
bold(text: string): string;
code(text: string): string;
codeBlock(code: string, lang?: string): string;
list(items: string[]): string;
keyValue(key: string, value: string): string;
paragraph(text: string): string;
separator(): string;
wrap(content: string, metadata?: Record<string, unknown>): string;
}
const markdownRenderer: FormatRenderer = {
h1: (text) => `# ${text}`,
h2: (text) => `## ${text}`,
h3: (text) => `### ${text}`,
bold: (text) => `**${text}**`,
code: (text) => `\`${text}\``,
codeBlock: (code, lang = '') => `\`\`\`${lang}\n${code}\n\`\`\``,
list: (items) => items.map(item => `- ${item}`).join('\n'),
keyValue: (key, value) => `**${key}:** ${value}`,
paragraph: (text) => text,
separator: () => '',
wrap: (content) => content,
};
const mdcRenderer: FormatRenderer = {
h1: (text) => `# ${text}`,
h2: (text) => `## ${text}`,
h3: (text) => `### ${text}`,
bold: (text) => `**${text}**`,
code: (text) => `\`${text}\``,
codeBlock: (code, lang = '') => `\`\`\`${lang}\n${code}\n\`\`\``,
list: (items) => items.map(item => `- ${item}`).join('\n'),
keyValue: (key, value) => `**${key}:** ${value}`,
paragraph: (text) => text,
separator: () => '',
wrap: (content, metadata) => {
if (metadata && Object.keys(metadata).length > 0) {
const yaml = Object.entries(metadata)
.map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
.join('\n');
return `---\n${yaml}\n---\n\n${content}`;
}
return content;
},
};
const jsonRenderer: FormatRenderer = {
h1: (text) => text,
h2: (text) => text,
h3: (text) => text,
bold: (text) => text,
code: (text) => text,
codeBlock: (code) => code,
list: (items) => items.join(', '),
keyValue: (key, value) => `${key}: ${value}`,
paragraph: (text) => text,
separator: () => '',
wrap: (content, metadata) => {
try {
const data = { ...metadata, content };
return JSON.stringify(data, null, 2);
} catch {
return content;
}
},
};
const xmlRenderer: FormatRenderer = {
h1: (text) => `<h1>${escapeXml(text)}</h1>`,
h2: (text) => `<h2>${escapeXml(text)}</h2>`,
h3: (text) => `<h3>${escapeXml(text)}</h3>`,
bold: (text) => `<strong>${escapeXml(text)}</strong>`,
code: (text) => `<code>${escapeXml(text)}</code>`,
codeBlock: (code, lang = '') => `<pre${lang ? ` lang="${lang}"` : ''}><code>${escapeXml(code)}</code></pre>`,
list: (items) => `<ul>\n${items.map(item => ` <li>${escapeXml(item)}</li>`).join('\n')}\n</ul>`,
keyValue: (key, value) => `<dt>${escapeXml(key)}</dt><dd>${escapeXml(value)}</dd>`,
paragraph: (text) => `<p>${escapeXml(text)}</p>`,
separator: () => '',
wrap: (content, metadata) => {
const attrs = metadata
? Object.entries(metadata).map(([k, v]) => `${k}="${escapeXml(String(v))}"`).join(' ')
: '';
return `<?xml version="1.0" encoding="UTF-8"?>\n<instructions${attrs ? ' ' + attrs : ''}>\n${content}\n</instructions>`;
},
};
function escapeXml(text: string): string {
return text
.replace(/&/g, '&amp;')
.replace(/</g, '&lt;')
.replace(/>/g, '&gt;')
.replace(/"/g, '&quot;')
.replace(/'/g, '&apos;');
}
function getRenderer(format: OutputFormat): FormatRenderer {
switch (format) {
case 'mdc':
return mdcRenderer;
case 'json':
return jsonRenderer;
case 'xml':
return xmlRenderer;
default:
return markdownRenderer;
}
}
export class PrimerGenerator {
private projectPath: string;
private options: PrimerOptions;
private analysis: PrimerAnalysis | null = null;
constructor(projectPath: string, options: PrimerOptions = {}) {
this.projectPath = projectPath;
this.options = options;
}
generate(): PrimerResult {
const warnings: string[] = [];
const errors: string[] = [];
const generated: GeneratedInstruction[] = [];
const seenPaths = new Map<string, string>();
this.analysis = analyzePrimer(this.projectPath);
if (this.options.analyzeOnly) {
return {
success: true,
analysis: this.analysis,
generated: [],
warnings,
errors,
};
}
const targetAgents = this.getTargetAgents();
for (const agent of targetAgents) {
try {
const instruction = this.generateForAgent(agent);
if (instruction) {
const existingAgent = seenPaths.get(instruction.filepath);
if (existingAgent) {
warnings.push(
`Skipping ${agent}: output path "${instruction.filename}" already used by ${existingAgent}`
);
continue;
}
seenPaths.set(instruction.filepath, agent);
if (!this.options.dryRun) {
this.writeInstruction(instruction);
}
generated.push(instruction);
}
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
errors.push(`Failed to generate for ${agent}: ${message}`);
}
}
return {
success: errors.length === 0,
analysis: this.analysis,
generated,
warnings,
errors,
};
}
private getTargetAgents(): AgentType[] {
if (this.options.allAgents) {
return ALL_AGENTS;
}
if (this.options.agents && this.options.agents.length > 0) {
return this.options.agents;
}
return this.detectInstalledAgents();
}
private detectInstalledAgents(): AgentType[] {
const detected: AgentType[] = [];
for (const [agent, config] of Object.entries(AGENT_CONFIG)) {
const configPath = join(this.projectPath, config.configFile);
const skillsPath = join(this.projectPath, config.skillsDir);
if (existsSync(configPath) || existsSync(skillsPath)) {
detected.push(agent as AgentType);
}
if (config.altSkillsDirs) {
for (const altDir of config.altSkillsDirs) {
if (existsSync(join(this.projectPath, altDir))) {
if (!detected.includes(agent as AgentType)) {
detected.push(agent as AgentType);
}
break;
}
}
}
}
if (detected.length === 0) {
detected.push('claude-code', 'cursor', 'github-copilot');
}
return detected;
}
private generateForAgent(agent: AgentType): GeneratedInstruction | null {
if (!this.analysis) return null;
const config = AGENT_CONFIG[agent];
const template = AGENT_INSTRUCTION_TEMPLATES[agent] || this.getDefaultTemplate(agent, config);
const content = this.generateContent(template);
const outputDir = this.options.outputDir || this.projectPath;
const filepath = join(outputDir, template.filename);
return {
agent,
filename: template.filename,
filepath,
content,
format: template.format,
};
}
private getDefaultTemplate(agent: AgentType, config: AgentDirectoryConfig): AgentInstructionTemplate {
const formatMap: Record<string, OutputFormat> = {
'.md': 'markdown',
'.json': 'json',
'.mdc': 'mdc',
'.xml': 'xml',
};
const ext = config.configFile.includes('.')
? '.' + config.configFile.split('.').pop()
: '.md';
const format = formatMap[ext] || 'markdown';
return {
agent,
filename: config.configFile,
format,
sectionOrder: ['overview', 'stack', 'commands', 'conventions', 'structure', 'guidelines'],
};
}
private generateContent(template: AgentInstructionTemplate): string {
if (!this.analysis) return '';
const format = template.format as OutputFormat;
const renderer = getRenderer(format);
if (format === 'json') {
return this.generateJsonContent(template);
}
const sections: string[] = [];
for (const section of template.sectionOrder) {
const content = this.generateSection(section, template, renderer);
if (content) {
sections.push(content);
}
}
let result = sections.join('\n\n');
if (template.header) {
result = template.header + '\n\n' + result;
}
if (template.footer) {
result = result + '\n\n' + template.footer;
}
if (this.options.customInstructions) {
result += '\n\n' + renderer.h2('Custom Instructions') + '\n\n' + this.options.customInstructions;
}
const metadata = format === 'mdc' ? {
title: this.analysis.project.name,
type: this.analysis.project.type,
generated: new Date().toISOString(),
} : undefined;
return renderer.wrap(result, metadata);
}
private generateJsonContent(template: AgentInstructionTemplate): string {
if (!this.analysis) return '{}';
const data: Record<string, unknown> = {
project: this.analysis.project,
languages: this.analysis.languages.map(l => l.name),
packageManagers: this.analysis.packageManagers,
stack: {
frameworks: this.analysis.stack.frameworks.map(f => ({ name: f.name, version: f.version })),
libraries: this.analysis.stack.libraries.map(l => ({ name: l.name, version: l.version })),
styling: this.analysis.stack.styling.map(s => s.name),
testing: this.analysis.stack.testing.map(t => t.name),
databases: this.analysis.stack.databases.map(d => d.name),
},
commands: this.analysis.buildCommands,
conventions: this.analysis.conventions,
structure: this.analysis.structure,
importantFiles: this.analysis.importantFiles,
generated: {
agent: template.agent,
timestamp: new Date().toISOString(),
},
};
if (this.options.customInstructions) {
data.customInstructions = this.options.customInstructions;
}
return JSON.stringify(data, null, 2);
}
private generateSection(section: string, template: AgentInstructionTemplate, renderer: FormatRenderer): string {
if (!this.analysis) return '';
switch (section) {
case 'overview':
return this.generateOverviewSection(renderer);
case 'stack':
return this.generateStackSection(renderer);
case 'commands':
return this.generateCommandsSection(renderer);
case 'conventions':
return this.generateConventionsSection(renderer);
case 'structure':
return this.generateStructureSection(renderer);
case 'guidelines':
return this.generateGuidelinesSection(template.agent, renderer);
default:
return '';
}
}
private generateOverviewSection(renderer: FormatRenderer): string {
if (!this.analysis) return '';
const { project, languages } = this.analysis;
const lines: string[] = [];
lines.push(renderer.h1(project.name));
lines.push('');
if (project.description) {
lines.push(renderer.paragraph(project.description));
lines.push('');
}
if (project.type) {
lines.push(renderer.keyValue('Project Type', this.formatProjectType(project.type)));
}
if (languages.length > 0) {
const langNames = languages.map(l => this.capitalize(l.name)).join(', ');
lines.push(renderer.keyValue('Languages', langNames));
}
if (project.version) {
lines.push(renderer.keyValue('Version', project.version));
}
return lines.join('\n');
}
private generateStackSection(renderer: FormatRenderer): string {
if (!this.analysis) return '';
const { stack, packageManagers } = this.analysis;
const lines: string[] = [];
lines.push(renderer.h2('Technology Stack'));
lines.push('');
if (stack.frameworks.length > 0) {
lines.push(renderer.h3('Frameworks'));
const items = stack.frameworks.map(fw => {
const version = fw.version ? ` (${fw.version})` : '';
return `${this.capitalize(fw.name)}${version}`;
});
lines.push(renderer.list(items));
lines.push('');
}
if (stack.libraries.length > 0) {
lines.push(renderer.h3('Libraries'));
const items = stack.libraries.map(lib => {
const version = lib.version ? ` (${lib.version})` : '';
return `${this.capitalize(lib.name)}${version}`;
});
lines.push(renderer.list(items));
lines.push('');
}
if (stack.styling.length > 0) {
lines.push(renderer.h3('Styling'));
lines.push(renderer.list(stack.styling.map(s => this.capitalize(s.name))));
lines.push('');
}
if (stack.testing.length > 0) {
lines.push(renderer.h3('Testing'));
lines.push(renderer.list(stack.testing.map(t => this.capitalize(t.name))));
lines.push('');
}
if (stack.databases.length > 0) {
lines.push(renderer.h3('Databases'));
lines.push(renderer.list(stack.databases.map(d => this.capitalize(d.name))));
lines.push('');
}
if (packageManagers.length > 0) {
lines.push(renderer.h3('Package Manager'));
lines.push(renderer.list([packageManagers.map(pm => this.capitalize(pm)).join(', ')]));
lines.push('');
}
return lines.join('\n');
}
private generateCommandsSection(renderer: FormatRenderer): string {
if (!this.analysis || !this.analysis.buildCommands) return '';
const { buildCommands } = this.analysis;
const lines: string[] = [];
const commands: string[] = [];
lines.push(renderer.h2('Development Commands'));
lines.push('');
if (buildCommands.install) {
commands.push(`# Install dependencies`);
commands.push(buildCommands.install);
commands.push('');
}
if (buildCommands.dev) {
commands.push(`# Start development server`);
commands.push(buildCommands.dev);
commands.push('');
}
if (buildCommands.build) {
commands.push(`# Build for production`);
commands.push(buildCommands.build);
commands.push('');
}
if (buildCommands.test) {
commands.push(`# Run tests`);
commands.push(buildCommands.test);
commands.push('');
}
if (buildCommands.lint) {
commands.push(`# Run linter`);
commands.push(buildCommands.lint);
commands.push('');
}
if (buildCommands.format) {
commands.push(`# Format code`);
commands.push(buildCommands.format);
}
lines.push(renderer.codeBlock(commands.join('\n'), 'bash'));
return lines.join('\n');
}
private generateConventionsSection(renderer: FormatRenderer): string {
if (!this.analysis) return '';
const { conventions, patterns } = this.analysis;
const lines: string[] = [];
lines.push(renderer.h2('Code Conventions'));
lines.push('');
if (conventions) {
const items: string[] = [];
if (conventions.indentation) {
items.push(`${renderer.bold('Indentation:')} ${conventions.indentation}`);
}
if (conventions.quotes) {
items.push(`${renderer.bold('Quotes:')} ${conventions.quotes}`);
}
if (conventions.semicolons !== undefined) {
items.push(`${renderer.bold('Semicolons:')} ${conventions.semicolons ? 'required' : 'omitted'}`);
}
if (conventions.trailingCommas) {
items.push(`${renderer.bold('Trailing Commas:')} ${conventions.trailingCommas}`);
}
if (conventions.maxLineLength) {
items.push(`${renderer.bold('Max Line Length:')} ${conventions.maxLineLength}`);
}
if (items.length > 0) {
lines.push(renderer.list(items));
}
}
if (patterns) {
lines.push('');
lines.push(renderer.h3('Patterns'));
const items: string[] = [];
if (patterns.components) {
items.push(`${renderer.bold('Components:')} ${patterns.components}`);
}
if (patterns.stateManagement) {
items.push(`${renderer.bold('State Management:')} ${patterns.stateManagement}`);
}
if (patterns.apiStyle) {
items.push(`${renderer.bold('API Style:')} ${patterns.apiStyle}`);
}
if (patterns.styling) {
items.push(`${renderer.bold('Styling:')} ${patterns.styling}`);
}
if (patterns.testing) {
items.push(`${renderer.bold('Testing:')} ${patterns.testing}`);
}
if (patterns.linting) {
items.push(`${renderer.bold('Linting:')} ${patterns.linting}`);
}
if (patterns.formatting) {
items.push(`${renderer.bold('Formatting:')} ${patterns.formatting}`);
}
if (items.length > 0) {
lines.push(renderer.list(items));
}
}
return lines.join('\n');
}
private generateStructureSection(renderer: FormatRenderer): string {
if (!this.analysis) return '';
const { structure, importantFiles } = this.analysis;
const lines: string[] = [];
lines.push(renderer.h2('Project Structure'));
lines.push('');
if (structure) {
if (structure.type) {
lines.push(renderer.keyValue('Structure Type', structure.type));
}
if (structure.srcDir) {
lines.push(renderer.keyValue('Source Directory', renderer.code(`${structure.srcDir}/`)));
}
if (structure.testDir) {
lines.push(renderer.keyValue('Test Directory', renderer.code(`${structure.testDir}/`)));
}
if (structure.hasWorkspaces && structure.workspaces) {
lines.push(renderer.keyValue('Workspaces', structure.workspaces.join(', ')));
}
lines.push('');
}
if (importantFiles.length > 0) {
lines.push(renderer.h3('Important Files'));
lines.push(renderer.list(importantFiles.slice(0, 15).map(f => renderer.code(f))));
}
return lines.join('\n');
}
private generateGuidelinesSection(_agent: AgentType, renderer: FormatRenderer): string {
if (!this.analysis) return '';
const { stack, patterns } = this.analysis;
const lines: string[] = [];
lines.push(renderer.h2('Development Guidelines'));
lines.push('');
const hasReact = stack.frameworks.some(f => f.name === 'react' || f.name === 'nextjs');
const hasVue = stack.frameworks.some(f => f.name === 'vue' || f.name === 'nuxt');
const hasTypeScript = this.analysis.languages.some(l => l.name === 'typescript');
const hasTailwind = stack.styling.some(s => s.name === 'tailwindcss');
const hasPrisma = stack.databases.some(d => d.name === 'prisma');
const hasZod = stack.libraries.some(l => l.name === 'zod');
if (hasTypeScript) {
lines.push(renderer.h3('TypeScript'));
lines.push(renderer.list([
'Use strict TypeScript with proper type annotations',
'Prefer `interface` for object types, `type` for unions/intersections',
'Avoid `any` - use `unknown` when type is uncertain',
]));
lines.push('');
}
if (hasReact) {
lines.push(renderer.h3('React'));
const reactItems = [
'Use functional components with hooks',
'Prefer composition over inheritance',
'Keep components small and focused',
];
if (patterns?.stateManagement) {
reactItems.push(`Use ${patterns.stateManagement} for state management`);
}
lines.push(renderer.list(reactItems));
lines.push('');
}
if (hasVue) {
lines.push(renderer.h3('Vue'));
lines.push(renderer.list([
'Use Composition API with `<script setup>`',
'Keep components small and focused',
]));
lines.push('');
}
if (hasTailwind) {
lines.push(renderer.h3('Styling'));
lines.push(renderer.list([
'Use Tailwind CSS utility classes',
'Follow mobile-first responsive design',
'Extract repeated patterns to components',
]));
lines.push('');
}
if (hasPrisma) {
lines.push(renderer.h3('Database'));
lines.push(renderer.list([
'Use Prisma for database operations',
'Keep database queries in dedicated service files',
'Use transactions for related operations',
]));
lines.push('');
}
if (hasZod) {
lines.push(renderer.h3('Validation'));
lines.push(renderer.list([
'Use Zod for runtime validation',
'Define schemas alongside types',
]));
lines.push('');
}
lines.push(renderer.h3('General'));
lines.push(renderer.list([
'Follow existing code patterns and conventions',
'Write clear, self-documenting code',
'Keep functions small and focused',
'Add tests for new functionality',
]));
return lines.join('\n');
}
private writeInstruction(instruction: GeneratedInstruction): void {
const dir = dirname(instruction.filepath);
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
writeFileSync(instruction.filepath, instruction.content, 'utf-8');
}
private formatProjectType(type: string): string {
const typeMap: Record<string, string> = {
'web-app': 'Web Application',
'api': 'API / Backend',
'cli': 'CLI Tool',
'library': 'Library / Package',
'mobile': 'Mobile Application',
'desktop': 'Desktop Application',
'unknown': 'Project',
};
return typeMap[type] || type;
}
private capitalize(str: string): string {
return str.charAt(0).toUpperCase() + str.slice(1);
}
}
export function generatePrimer(projectPath: string, options: PrimerOptions = {}): PrimerResult {
const generator = new PrimerGenerator(projectPath, options);
return generator.generate();
}
export function generatePrimerForAgent(
projectPath: string,
agent: AgentType,
options: Omit<PrimerOptions, 'agents' | 'allAgents'> = {}
): PrimerResult {
return generatePrimer(projectPath, { ...options, agents: [agent] });
}
export function analyzeForPrimer(projectPath: string): PrimerAnalysis {
const generator = new PrimerGenerator(projectPath, { analyzeOnly: true });
const result = generator.generate();
return result.analysis;
}
+27
View File
@@ -0,0 +1,27 @@
export {
type PrimerLanguage,
type PackageManager,
type CodeConvention,
type ProjectStructure,
type CIConfig,
type EnvConfig,
type DockerConfig,
type PrimerAnalysis,
type PrimerOptions,
type GeneratedInstruction,
type PrimerResult,
type AgentInstructionTemplate,
AGENT_INSTRUCTION_TEMPLATES,
} from './types.js';
export {
PrimerAnalyzer,
analyzePrimer,
} from './analyzer.js';
export {
PrimerGenerator,
generatePrimer,
generatePrimerForAgent,
analyzeForPrimer,
} from './generator.js';
+206
View File
@@ -0,0 +1,206 @@
import { z } from 'zod';
import type { AgentType } from '../types.js';
import { ProjectStack, ProjectPatterns, Detection } from '../context/types.js';
export const PrimerLanguage = z.enum([
'typescript',
'javascript',
'python',
'go',
'rust',
'java',
'kotlin',
'swift',
'ruby',
'php',
'csharp',
'cpp',
]);
export type PrimerLanguage = z.infer<typeof PrimerLanguage>;
export const PackageManager = z.enum([
'npm',
'pnpm',
'yarn',
'bun',
'pip',
'poetry',
'uv',
'cargo',
'go',
'maven',
'gradle',
'composer',
'bundler',
'cocoapods',
'swift-package-manager',
'nuget',
]);
export type PackageManager = z.infer<typeof PackageManager>;
export const CodeConvention = z.object({
namingStyle: z.enum(['camelCase', 'snake_case', 'PascalCase', 'kebab-case']).optional(),
indentation: z.enum(['tabs', 'spaces-2', 'spaces-4']).optional(),
quotes: z.enum(['single', 'double']).optional(),
semicolons: z.boolean().optional(),
trailingCommas: z.enum(['none', 'es5', 'all']).optional(),
maxLineLength: z.number().optional(),
});
export type CodeConvention = z.infer<typeof CodeConvention>;
export const ProjectStructure = z.object({
type: z.enum(['flat', 'src-based', 'monorepo', 'packages']).optional(),
srcDir: z.string().optional(),
testDir: z.string().optional(),
docsDir: z.string().optional(),
configDir: z.string().optional(),
hasWorkspaces: z.boolean().default(false),
workspaces: z.array(z.string()).optional(),
});
export type ProjectStructure = z.infer<typeof ProjectStructure>;
export const CIConfig = z.object({
provider: z.enum(['github-actions', 'gitlab-ci', 'circleci', 'jenkins', 'travis', 'azure-pipelines']).optional(),
hasCI: z.boolean().default(false),
hasCD: z.boolean().default(false),
configFile: z.string().optional(),
});
export type CIConfig = z.infer<typeof CIConfig>;
export const EnvConfig = z.object({
hasEnvFile: z.boolean().default(false),
hasEnvExample: z.boolean().default(false),
envVariables: z.array(z.string()).optional(),
});
export type EnvConfig = z.infer<typeof EnvConfig>;
export const DockerConfig = z.object({
hasDockerfile: z.boolean().default(false),
hasCompose: z.boolean().default(false),
baseImage: z.string().optional(),
});
export type DockerConfig = z.infer<typeof DockerConfig>;
export const PrimerAnalysis = z.object({
project: z.object({
name: z.string(),
description: z.string().optional(),
version: z.string().optional(),
type: z.string().optional(),
license: z.string().optional(),
repository: z.string().optional(),
}),
languages: z.array(Detection).default([]),
packageManagers: z.array(PackageManager).default([]),
stack: ProjectStack,
patterns: ProjectPatterns.optional(),
structure: ProjectStructure.optional(),
conventions: CodeConvention.optional(),
ci: CIConfig.optional(),
env: EnvConfig.optional(),
docker: DockerConfig.optional(),
buildCommands: z.object({
install: z.string().optional(),
build: z.string().optional(),
test: z.string().optional(),
lint: z.string().optional(),
format: z.string().optional(),
dev: z.string().optional(),
start: z.string().optional(),
}).optional(),
importantFiles: z.array(z.string()).default([]),
codebaseSize: z.object({
files: z.number().optional(),
lines: z.number().optional(),
directories: z.number().optional(),
}).optional(),
});
export type PrimerAnalysis = z.infer<typeof PrimerAnalysis>;
export interface PrimerOptions {
projectPath?: string;
agents?: AgentType[];
allAgents?: boolean;
outputDir?: string;
dryRun?: boolean;
analyzeOnly?: boolean;
verbose?: boolean;
includeExamples?: boolean;
customInstructions?: string;
}
export interface GeneratedInstruction {
agent: AgentType;
filename: string;
filepath: string;
content: string;
format: 'markdown' | 'json' | 'mdc' | 'xml';
}
export interface PrimerResult {
success: boolean;
analysis: PrimerAnalysis;
generated: GeneratedInstruction[];
warnings: string[];
errors: string[];
}
export interface AgentInstructionTemplate {
agent: AgentType;
filename: string;
format: 'markdown' | 'json' | 'mdc' | 'xml';
header?: string;
footer?: string;
sectionOrder: string[];
}
export const AGENT_INSTRUCTION_TEMPLATES: Record<string, AgentInstructionTemplate> = {
'claude-code': {
agent: 'claude-code',
filename: 'CLAUDE.md',
format: 'markdown',
sectionOrder: ['overview', 'stack', 'commands', 'conventions', 'structure', 'guidelines'],
},
'cursor': {
agent: 'cursor',
filename: '.cursorrules',
format: 'markdown',
sectionOrder: ['overview', 'stack', 'conventions', 'guidelines'],
},
'github-copilot': {
agent: 'github-copilot',
filename: '.github/copilot-instructions.md',
format: 'markdown',
sectionOrder: ['overview', 'stack', 'commands', 'conventions', 'structure', 'guidelines'],
},
'codex': {
agent: 'codex',
filename: 'AGENTS.md',
format: 'markdown',
sectionOrder: ['overview', 'stack', 'commands', 'conventions', 'structure', 'guidelines'],
},
'gemini-cli': {
agent: 'gemini-cli',
filename: 'GEMINI.md',
format: 'markdown',
sectionOrder: ['overview', 'stack', 'commands', 'conventions', 'structure', 'guidelines'],
},
'windsurf': {
agent: 'windsurf',
filename: '.windsurfrules',
format: 'markdown',
sectionOrder: ['overview', 'stack', 'conventions', 'guidelines'],
},
'opencode': {
agent: 'opencode',
filename: 'AGENTS.md',
format: 'markdown',
sectionOrder: ['overview', 'stack', 'commands', 'conventions', 'structure', 'guidelines'],
},
'trae': {
agent: 'trae',
filename: '.trae/rules/project_rules.md',
format: 'markdown',
sectionOrder: ['overview', 'stack', 'commands', 'conventions', 'guidelines'],
},
};