@compilr-dev/sdk 0.2.5 → 0.2.7

package/dist/project-generator/templates/coding-standards.js

@@ -0,0 +1,299 @@
+/**
+ * Coding Standards Template Generator
+ *
+ * Generates the coding standards documentation.
+ */
+export function generateCodingStandardsMd(config) {
+    if (config.codingStandards === 'custom') {
+        return generateCustomTemplate(config);
+    }
+    return config.codingStandards === 'strict'
+        ? generateStrictTemplate(config)
+        : generateRelaxedTemplate(config);
+}
+function generateCustomTemplate(config) {
+    return `# Coding Standards - ${config.name}
+
+*Configure your coding standards here*
+
+---
+
+## TypeScript Configuration
+
+\`\`\`json
+// tsconfig.json - customize as needed
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "strict": true,  // Adjust based on preference
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+\`\`\`
+
+---
+
+## Linting
+
+*Add your ESLint configuration*
+
+---
+
+## Formatting
+
+*Add your Prettier configuration*
+
+---
+
+## Git Workflow
+
+*Define your branching strategy and commit conventions*
+
+---
+
+## Code Review
+
+*Define your code review process*
+
+---
+
+*Last Updated: ${new Date().toISOString().split('T')[0]}*
+`;
+}
+function generateStrictTemplate(config) {
+    return `# Coding Standards - ${config.name}
+
+**Preset:** TypeScript Strict
+
+---
+
+## TypeScript Configuration
+
+\`\`\`json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  }
+}
+\`\`\`
+
+---
+
+## ESLint Configuration
+
+\`\`\`javascript
+// eslint.config.js
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/explicit-function-return-type': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/prefer-readonly': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+    },
+  }
+);
+\`\`\`
+
+---
+
+## Prettier Configuration
+
+\`\`\`json
+// .prettierrc
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}
+\`\`\`
+
+---
+
+## Git Workflow
+
+### Branch Naming
+
+\`\`\`
+feat/feature-name     # New features
+fix/bug-description   # Bug fixes
+docs/update-area      # Documentation
+refactor/area         # Code refactoring
+\`\`\`
+
+### Commit Messages (Conventional Commits)
+
+\`\`\`
+feat: add user authentication
+fix: resolve login redirect issue
+docs: update API documentation
+refactor: simplify database queries
+test: add unit tests for auth module
+chore: update dependencies
+\`\`\`
+
+---
+
+## Code Review Checklist
+
+Before merging, verify:
+
+- [ ] All tests pass
+- [ ] No TypeScript errors
+- [ ] ESLint passes with no errors
+- [ ] Code follows project patterns
+- [ ] Documentation updated if needed
+- [ ] No sensitive data in commits
+
+---
+
+## File Organization
+
+\`\`\`
+src/
+├── components/      # UI components
+├── features/        # Feature modules
+├── lib/             # Shared utilities
+├── hooks/           # Custom hooks
+├── types/           # TypeScript types
+└── index.ts         # Entry point
+\`\`\`
+
+---
+
+*Last Updated: ${new Date().toISOString().split('T')[0]}*
+`;
+}
+function generateRelaxedTemplate(config) {
+    return `# Coding Standards - ${config.name}
+
+**Preset:** TypeScript Relaxed
+
+---
+
+## TypeScript Configuration
+
+\`\`\`json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "sourceMap": true
+  }
+}
+\`\`\`
+
+---
+
+## ESLint Configuration
+
+\`\`\`javascript
+// eslint.config.js
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  }
+);
+\`\`\`
+
+---
+
+## Prettier Configuration
+
+\`\`\`json
+// .prettierrc
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}
+\`\`\`
+
+---
+
+## Git Workflow
+
+### Commit Messages
+
+Use descriptive commit messages. Conventional commits encouraged but not required:
+
+\`\`\`
+feat: add user authentication
+fix: resolve login redirect issue
+Update README
+\`\`\`
+
+---
+
+## Code Review
+
+- Tests should pass before merging
+- No TypeScript errors
+- Code should be readable
+
+---
+
+*Last Updated: ${new Date().toISOString().split('T')[0]}*
+`;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+import type { ImportProjectConfig } from '../types.js';
+export declare function generateCompilrMdForImport(config: ImportProjectConfig): string;

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;