@compilr-dev/sdk 0.2.4 → 0.2.6

package/dist/project-generator/templates/compilr-md-import.js

@@ -0,0 +1,241 @@
+/**
+ * COMPILR.md Template Generator for Imported Projects
+ *
+ * Generates the AI assistant context file for existing projects that are being imported.
+ * Different from the new project template - acknowledges existing codebase structure.
+ */
+export function generateCompilrMdForImport(config) {
+    const techStackSection = generateTechStackSection(config);
+    const structureSection = generateStructureSection(config);
+    return `# COMPILR.md
+
+This file provides guidance to AI coding assistants when working with this project.
+
+---
+
+## Project Overview
+
+**Project:** ${config.displayName}
+${config.description ? `**Description:** ${config.description}` : '*Add a description for this project*'}
+
+**Workflow:** ${config.workflowMode === 'guided' ? 'Guided (structured step-by-step workflow)' : 'Flexible (user-driven, exploratory)'}
+
+---
+
+${techStackSection}
+
+---
+
+${structureSection}
+
+---
+
+## Project Data (Database-Backed)
+
+This project uses compilr's database for tracking. Use these tools to access project data:
+
+| Data Type | Read Tool | Write Tool |
+|-----------|-----------|------------|
+| Work Items (Backlog) | \`workitem_query\` | \`workitem_add\`, \`workitem_update\` |
+| Project Documents | \`project_document_get\`, \`project_document_list\` | \`project_document_add\` |
+| Anchors (Context) | \`anchor_list\` | \`anchor_add\`, \`anchor_remove\` |
+
+**Important:** Use database tools for project metadata. Explore the existing codebase for implementation details.
+
+---
+
+## Development Commands
+
+\`\`\`bash
+${generateDevCommands(config)}
+\`\`\`
+
+---
+
+## Notes for AI Assistants
+
+1. **This is an existing codebase** - Explore the code structure before making changes
+2. **Respect existing patterns** - Follow the conventions already established in this project
+3. **Use database tools** to query backlog, documents, and anchors (project metadata)
+4. **Check the backlog** with \`workitem_query\` before starting new work
+5. **Read existing code** to understand the architecture before adding features
+
+---
+
+*Generated by compilr on ${new Date().toISOString().split('T')[0]}*
+`;
+}
+function generateTechStackSection(config) {
+    const { detected } = config;
+    if (!detected.language) {
+        return `## Tech Stack
+
+*Tech stack not auto-detected. Update this section with your project's technologies.*
+
+| Component | Technology | Notes |
+|-----------|------------|-------|
+| Language  | TBD        |       |
+| Framework | TBD        |       |
+| Database  | TBD        |       |`;
+    }
+    const languageLabel = getLanguageLabel(detected.language);
+    const frameworkLabel = detected.framework
+        ? getFrameworkLabel(detected.framework)
+        : 'Not detected';
+    const packageManagerLabel = detected.packageManager ?? 'Not detected';
+    return `## Tech Stack
+
+*Auto-detected from project files. Update as needed.*
+
+| Component | Technology | Notes |
+|-----------|------------|-------|
+| Language  | ${languageLabel} | Detected |
+| Framework | ${frameworkLabel} | ${detected.framework ? 'Detected' : 'Update this'} |
+| Package Manager | ${packageManagerLabel} | ${detected.packageManager ? 'Detected' : 'Update this'} |
+| Database  | *Not detected* | Update this |`;
+}
+function generateStructureSection(config) {
+    const { detected } = config;
+    // Provide guidance based on detected language
+    const languageHints = {
+        node: `- \`src/\` - Source code
+- \`package.json\` - Dependencies and scripts
+- \`tsconfig.json\` - TypeScript configuration (if TypeScript)`,
+        python: `- \`src/\` or project module - Source code
+- \`pyproject.toml\` / \`requirements.txt\` - Dependencies
+- \`tests/\` - Test files`,
+        go: `- Go modules structure
+- \`go.mod\` - Module definition
+- \`cmd/\` - Main applications (if present)
+- \`internal/\` - Private packages (if present)`,
+        rust: `- \`src/\` - Source code
+- \`Cargo.toml\` - Dependencies and project config
+- \`target/\` - Build output (gitignored)`,
+        default: `*Explore the project to understand its structure.*`,
+    };
+    const hint = detected.language
+        ? (languageHints[detected.language] ?? languageHints.default)
+        : languageHints.default;
+    return `## Project Structure
+
+*This is an existing codebase. Key locations:*
+
+${hint}
+
+**Tip:** Use \`glob\` and \`read_file\` tools to explore the codebase structure.`;
+}
+function generateDevCommands(config) {
+    const { detected } = config;
+    const commands = {
+        node: `# Install dependencies
+npm install
+
+# Development
+npm run dev
+
+# Build
+npm run build
+
+# Test
+npm test`,
+        pnpm: `# Install dependencies
+pnpm install
+
+# Development
+pnpm dev
+
+# Build
+pnpm build
+
+# Test
+pnpm test`,
+        yarn: `# Install dependencies
+yarn install
+
+# Development
+yarn dev
+
+# Build
+yarn build
+
+# Test
+yarn test`,
+        python: `# Install dependencies (adjust for your package manager)
+pip install -r requirements.txt
+# or: poetry install
+# or: pdm install
+
+# Run application
+python -m ${config.name.replace(/-/g, '_')}
+
+# Test
+pytest`,
+        go: `# Download dependencies
+go mod download
+
+# Build
+go build ./...
+
+# Test
+go test ./...
+
+# Run (adjust for your main package)
+go run ./cmd/${config.name}`,
+        rust: `# Build
+cargo build
+
+# Run
+cargo run
+
+# Test
+cargo test`,
+        default: `# Update these commands for your project
+# npm run dev
+# npm run build
+# npm test`,
+    };
+    if (detected.packageManager === 'pnpm')
+        return commands.pnpm;
+    if (detected.packageManager === 'yarn')
+        return commands.yarn;
+    if (detected.language)
+        return commands[detected.language] ?? commands.default;
+    return commands.default;
+}
+function getLanguageLabel(language) {
+    const labels = {
+        node: 'Node.js / TypeScript',
+        go: 'Go',
+        python: 'Python',
+        rust: 'Rust',
+        java: 'Java',
+        kotlin: 'Kotlin',
+        php: 'PHP',
+        ruby: 'Ruby',
+        dotnet: '.NET (C#/F#)',
+    };
+    return labels[language] ?? language;
+}
+function getFrameworkLabel(framework) {
+    const labels = {
+        react: 'React',
+        vue: 'Vue.js',
+        svelte: 'Svelte',
+        angular: 'Angular',
+        next: 'Next.js',
+        nuxt: 'Nuxt.js',
+        express: 'Express.js',
+        fastify: 'Fastify',
+        koa: 'Koa',
+        hono: 'Hono',
+        electron: 'Electron',
+        fastapi: 'FastAPI',
+        django: 'Django',
+        flask: 'Flask',
+        rails: 'Ruby on Rails',
+        sinatra: 'Sinatra',
+        laravel: 'Laravel',
+        symfony: 'Symfony',
+    };
+    return labels[framework] ?? framework;
+}

package/dist/project-generator/templates/compilr-md.d.ts

@@ -0,0 +1,7 @@
+/**
+ * COMPILR.md Template Generator
+ *
+ * Generates the AI assistant context file.
+ */
+import type { ProjectConfig } from '../types.js';
+export declare function generateCompilrMd(config: ProjectConfig): string;

package/dist/project-generator/templates/compilr-md.js

@@ -0,0 +1,141 @@
+/**
+ * COMPILR.md Template Generator
+ *
+ * Generates the AI assistant context file.
+ */
+export function generateCompilrMd(config) {
+    const techStackSection = generateTechStackSection(config);
+    const codingStandardsSection = generateCodingStandardsSection(config);
+    return `# COMPILR.md
+
+This file provides guidance to AI coding assistants when working with this project.
+
+---
+
+## Project Overview
+
+**Project:** ${config.name}
+**Description:** ${config.description}
+
+---
+
+${techStackSection}
+
+---
+
+${codingStandardsSection}
+
+---
+
+## Project Data (Database-Backed)
+
+This project uses compilr's database for tracking. Use these tools to access project data:
+
+| Data Type | Read Tool | Write Tool |
+|-----------|-----------|------------|
+| Work Items (Backlog) | \`workitem_query\` | \`workitem_add\`, \`workitem_update\` |
+| Project Documents | \`project_document_get\`, \`project_document_list\` | \`project_document_add\` |
+| Anchors (Context) | \`anchor_list\` | \`anchor_add\`, \`anchor_remove\` |
+
+**Important:** Always use database tools instead of exploring the filesystem for project data.
+
+---
+
+## Development Commands
+
+\`\`\`bash
+npm run dev         # Start development server
+npm run build       # Production build
+npm run lint        # Lint code
+npm run test        # Run tests
+\`\`\`
+
+---
+
+## Notes for AI Assistants
+
+1. **Use database tools** to query backlog, documents, and anchors (not filesystem)
+2. **Check the backlog** with \`workitem_query\` before starting new work
+3. **Follow coding standards** defined in this project
+4. **Document decisions** when making architectural choices
+
+---
+
+*Last Updated: ${new Date().toISOString().split('T')[0]}*
+`;
+}
+function generateTechStackSection(config) {
+    if (config.techStack === 'custom') {
+        return `## Tech Stack
+
+*To be configured - update this section with your chosen technologies*
+
+| Component | Technology | Notes |
+|-----------|------------|-------|
+| Frontend  | TBD        |       |
+| Backend   | TBD        |       |
+| Database  | TBD        |       |
+| Hosting   | TBD        |       |`;
+    }
+    const stacks = {
+        'react-node-pg': `## Tech Stack
+
+| Component | Technology | Notes |
+|-----------|------------|-------|
+| Frontend  | React 18 + Vite | TypeScript, modern React |
+| Backend   | Node.js + Express | TypeScript, REST API |
+| Database  | PostgreSQL | Relational, ACID compliant |
+| ORM       | Prisma | Type-safe database access |`,
+        'react-python-pg': `## Tech Stack
+
+| Component | Technology | Notes |
+|-----------|------------|-------|
+| Frontend  | React 18 + Vite | TypeScript, modern React |
+| Backend   | Python + FastAPI | Async, auto-docs |
+| Database  | PostgreSQL | Relational, ACID compliant |
+| ORM       | SQLAlchemy | Python ORM |`,
+        'vue-node-pg': `## Tech Stack
+
+| Component | Technology | Notes |
+|-----------|------------|-------|
+| Frontend  | Vue 3 + Vite | TypeScript, Composition API |
+| Backend   | Node.js + Express | TypeScript, REST API |
+| Database  | PostgreSQL | Relational, ACID compliant |
+| ORM       | Prisma | Type-safe database access |`,
+    };
+    return stacks[config.techStack] ?? stacks['react-node-pg'];
+}
+function generateCodingStandardsSection(config) {
+    if (config.codingStandards === 'custom') {
+        return `## Coding Standards
+
+*To be configured - update this section with your coding standards*
+
+See ${config.repoPattern === 'single' ? '`.compilr/architecture/coding-standards.md`' : '`02-architecture/coding-standards.md`'} for details.`;
+    }
+    const standards = config.codingStandards === 'strict'
+        ? `## Coding Standards
+
+**Preset:** TypeScript Strict
+
+- TypeScript strict mode enabled
+- ESLint + Prettier configured
+- Conventional commits required
+- No \`any\` types allowed
+- Explicit return types required
+- Comprehensive error handling
+
+See ${config.repoPattern === 'single' ? '`.compilr/architecture/coding-standards.md`' : '`02-architecture/coding-standards.md`'} for full details.`
+        : `## Coding Standards
+
+**Preset:** TypeScript Relaxed
+
+- TypeScript with relaxed settings
+- ESLint + Prettier configured
+- Conventional commits encouraged
+- \`any\` types discouraged but allowed
+- Implicit return types allowed
+
+See ${config.repoPattern === 'single' ? '`.compilr/architecture/coding-standards.md`' : '`02-architecture/coding-standards.md`'} for full details.`;
+    return standards;
+}

package/dist/project-generator/templates/config-json.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Config JSON Template Generator
+ *
+ * Generates the .compilr/config.json file for workflow versioning and settings.
+ */
+import type { ProjectConfig } from '../types.js';
+/**
+ * Generate config.json content
+ * @param config Project configuration
+ * @param projectPath Absolute path to the project folder
+ * @param docsPath Absolute path to the docs folder (for two-repo pattern)
+ */
+export declare function generateConfigJson(config: ProjectConfig, projectPath?: string, docsPath?: string): string;

package/dist/project-generator/templates/config-json.js

@@ -0,0 +1,39 @@
+/**
+ * Config JSON Template Generator
+ *
+ * Generates the .compilr/config.json file for workflow versioning and settings.
+ */
+import { WORKFLOW_VERSION } from '../types.js';
+/**
+ * Generate config.json content
+ * @param config Project configuration
+ * @param projectPath Absolute path to the project folder
+ * @param docsPath Absolute path to the docs folder (for two-repo pattern)
+ */
+export function generateConfigJson(config, projectPath, docsPath) {
+    // Determine workflow root (where config.json lives)
+    const workflowRoot = config.repoPattern === 'two-repo' ? docsPath : projectPath;
+    const compilrConfig = {
+        version: WORKFLOW_VERSION,
+        project: {
+            name: config.name,
+            description: config.description,
+            createdAt: new Date().toISOString(),
+        },
+        paths: {
+            project: projectPath ?? '',
+            docs: config.repoPattern === 'two-repo' ? (docsPath ?? null) : null,
+            workflowRoot: workflowRoot ?? '',
+        },
+        settings: {
+            repoPattern: config.repoPattern,
+            techStack: config.techStack,
+            codingStandards: config.codingStandards,
+        },
+        sessions: {
+            count: 0,
+            lastSession: null,
+        },
+    };
+    return JSON.stringify(compilrConfig, null, 2) + '\n';
+}

package/dist/project-generator/templates/gitignore.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Gitignore Template Generator
+ *
+ * Generates a .gitignore file based on tech stack.
+ */
+import type { ProjectConfig } from '../types.js';
+export declare function generateGitignore(config: ProjectConfig): string;

package/dist/project-generator/templates/gitignore.js

@@ -0,0 +1,85 @@
+/**
+ * Gitignore Template Generator
+ *
+ * Generates a .gitignore file based on tech stack.
+ */
+export function generateGitignore(config) {
+    const common = `# Dependencies
+node_modules/
+.pnp/
+.pnp.js
+
+# Build outputs
+dist/
+build/
+*.tsbuildinfo
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+
+# Testing
+coverage/
+.nyc_output/
+
+# Cache
+.cache/
+.parcel-cache/
+`;
+    const techSpecific = getTechSpecificIgnore(config.techStack);
+    return common + '\n' + techSpecific;
+}
+function getTechSpecificIgnore(techStack) {
+    switch (techStack) {
+        case 'react-node-pg':
+        case 'vue-node-pg':
+            return `# Vite
+.vite/
+
+# Prisma
+prisma/*.db
+prisma/*.db-journal
+`;
+        case 'react-python-pg':
+            return `# Vite
+.vite/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+.venv/
+ENV/
+env/
+.eggs/
+*.egg-info/
+*.egg
+.mypy_cache/
+.pytest_cache/
+`;
+        case 'custom':
+        default:
+            return `# Add tech-specific ignores here
+`;
+    }
+}

package/dist/project-generator/templates/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Template barrel export
+ */
+export { generateCompilrMd } from './compilr-md.js';
+export { generateConfigJson } from './config-json.js';
+export { generateReadmeMd } from './readme-md.js';
+export { generateCodingStandardsMd } from './coding-standards.js';
+export { generatePackageJson } from './package-json.js';
+export { generateTsconfig } from './tsconfig.js';
+export { generateGitignore } from './gitignore.js';
+export { generateCompilrMdForImport } from './compilr-md-import.js';

package/dist/project-generator/templates/index.js

@@ -0,0 +1,11 @@
+/**
+ * Template barrel export
+ */
+export { generateCompilrMd } from './compilr-md.js';
+export { generateConfigJson } from './config-json.js';
+export { generateReadmeMd } from './readme-md.js';
+export { generateCodingStandardsMd } from './coding-standards.js';
+export { generatePackageJson } from './package-json.js';
+export { generateTsconfig } from './tsconfig.js';
+export { generateGitignore } from './gitignore.js';
+export { generateCompilrMdForImport } from './compilr-md-import.js';

package/dist/project-generator/templates/package-json.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Package JSON Template Generator
+ *
+ * Generates a basic package.json for the project.
+ */
+import type { ProjectConfig } from '../types.js';
+export declare function generatePackageJson(config: ProjectConfig): string;

package/dist/project-generator/templates/package-json.js

@@ -0,0 +1,111 @@
+/**
+ * Package JSON Template Generator
+ *
+ * Generates a basic package.json for the project.
+ */
+export function generatePackageJson(config) {
+    const pkg = getPackageTemplate(config);
+    return JSON.stringify(pkg, null, 2) + '\n';
+}
+function getPackageTemplate(config) {
+    const base = {
+        name: config.name,
+        version: '0.0.1',
+        description: config.description,
+        type: 'module',
+        scripts: {},
+        dependencies: {},
+        devDependencies: {},
+    };
+    switch (config.techStack) {
+        case 'react-node-pg':
+            return {
+                ...base,
+                scripts: {
+                    dev: 'vite',
+                    build: 'tsc && vite build',
+                    lint: 'eslint src/',
+                    preview: 'vite preview',
+                },
+                dependencies: {
+                    react: '^18.2.0',
+                    'react-dom': '^18.2.0',
+                },
+                devDependencies: {
+                    '@types/react': '^18.2.0',
+                    '@types/react-dom': '^18.2.0',
+                    '@vitejs/plugin-react': '^4.2.0',
+                    typescript: '^5.3.0',
+                    vite: '^5.0.0',
+                    ...(config.codingStandards !== 'custom'
+                        ? {
+                            eslint: '^9.0.0',
+                            '@eslint/js': '^9.0.0',
+                            'typescript-eslint': '^8.0.0',
+                            prettier: '^3.2.0',
+                        }
+                        : {}),
+                },
+            };
+        case 'vue-node-pg':
+            return {
+                ...base,
+                scripts: {
+                    dev: 'vite',
+                    build: 'vue-tsc && vite build',
+                    lint: 'eslint src/',
+                    preview: 'vite preview',
+                },
+                dependencies: {
+                    vue: '^3.4.0',
+                },
+                devDependencies: {
+                    '@vitejs/plugin-vue': '^5.0.0',
+                    typescript: '^5.3.0',
+                    'vue-tsc': '^1.8.0',
+                    vite: '^5.0.0',
+                    ...(config.codingStandards !== 'custom'
+                        ? {
+                            eslint: '^9.0.0',
+                            '@eslint/js': '^9.0.0',
+                            'typescript-eslint': '^8.0.0',
+                            prettier: '^3.2.0',
+                        }
+                        : {}),
+                },
+            };
+        case 'react-python-pg':
+            // Frontend only - Python backend has its own requirements.txt
+            return {
+                ...base,
+                scripts: {
+                    dev: 'vite',
+                    build: 'tsc && vite build',
+                    lint: 'eslint src/',
+                    preview: 'vite preview',
+                },
+                dependencies: {
+                    react: '^18.2.0',
+                    'react-dom': '^18.2.0',
+                },
+                devDependencies: {
+                    '@types/react': '^18.2.0',
+                    '@types/react-dom': '^18.2.0',
+                    '@vitejs/plugin-react': '^4.2.0',
+                    typescript: '^5.3.0',
+                    vite: '^5.0.0',
+                },
+            };
+        case 'custom':
+        default:
+            return {
+                ...base,
+                scripts: {
+                    dev: 'echo "Add your dev command"',
+                    build: 'echo "Add your build command"',
+                    lint: 'echo "Add your lint command"',
+                    test: 'echo "Add your test command"',
+                },
+            };
+    }
+}

package/dist/project-generator/templates/readme-md.d.ts

@@ -0,0 +1,7 @@
+/**
+ * README.md Template Generator
+ *
+ * Generates the project README with next steps.
+ */
+import type { ProjectConfig } from '../types.js';
+export declare function generateReadmeMd(config: ProjectConfig): string;