mirror of
https://github.com/rohitg00/skillkit.git
synced 2026-11-19 02:13:58 +00:00
Compare commits
5
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6eb06f647d | ||
|
|
2d094fdd71 | ||
|
|
e9b5c647e2 | ||
|
|
8a51c73f2a | ||
|
|
db277fedbc |
@@ -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
|
||||
|
||||
@@ -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));
|
||||
|
||||
@@ -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> {
|
||||
|
||||
@@ -53,3 +53,4 @@ export {
|
||||
ManifestInstallCommand,
|
||||
ManifestGenerateCommand,
|
||||
} from './manifest.js';
|
||||
export { PrimerCommand } from './primer.js';
|
||||
|
||||
@@ -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`));
|
||||
}
|
||||
}
|
||||
@@ -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');
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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, '&')
|
||||
.replace(/</g, '<')
|
||||
.replace(/>/g, '>')
|
||||
.replace(/"/g, '"')
|
||||
.replace(/'/g, ''');
|
||||
}
|
||||
|
||||
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;
|
||||
}
|
||||
@@ -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';
|
||||
@@ -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'],
|
||||
},
|
||||
};
|
||||
Reference in New Issue
Block a user