ai-dev-starter 0.0.0-stage → 1.0.0

package/scripts/detector.js

@@ -0,0 +1,405 @@
+/**
+ * detector.js - Project Context Detector for ai-dev-starter
+ * 
+ * Inspects a repository to detect tech stack, frameworks, test setups,
+ * database usage, directories, and development commands.
+ * Zero external dependencies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function safeReadJson(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+  } catch {
+    // Malformed JSON or read error
+  }
+  return null;
+}
+
+function safeReadFile(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      return fs.readFileSync(filePath, 'utf8');
+    }
+  } catch {}
+  return '';
+}
+
+function dirExists(dirPath) {
+  try {
+    return fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect project metadata and architecture
+ */
+function detectProjectContext(projectRoot) {
+  const context = {
+    projectName: path.basename(projectRoot) || 'Unknown Project',
+    version: '1.0.0',
+    description: '',
+    repository: '',
+    backendLanguage: '',
+    backendFramework: '',
+    backendVersion: '',
+    frontendLanguage: '',
+    frontendFramework: 'none',
+    styling: '',
+    databases: [],
+    architecturePattern: 'Modular / Layered',
+    layers: [],
+    keyDirectories: [],
+    commands: {
+      install: '',
+      dev_server: '',
+      build: '',
+      test: '',
+      lint: '',
+      migrate: '',
+    },
+    testFramework: '',
+    testDirectory: 'tests',
+    reportLanguage: 'fa',
+    severityThreshold: 'P2',
+    constraints: [],
+  };
+
+  // 1. Detect Composer (PHP / Laravel / Symfony)
+  const composerJsonPath = path.join(projectRoot, 'composer.json');
+  const composer = safeReadJson(composerJsonPath);
+  if (composer) {
+    if (composer.name) context.projectName = composer.name.split('/').pop() || context.projectName;
+    if (composer.description) context.description = composer.description;
+    context.backendLanguage = 'php';
+
+    const req = { ...(composer.require || {}), ...(composer['require-dev'] || {}) };
+
+    if (req['laravel/framework']) {
+      context.backendFramework = 'laravel';
+      context.backendVersion = req['laravel/framework'];
+      context.architecturePattern = 'MVC (Laravel)';
+      context.commands.dev_server = 'php artisan serve';
+      context.commands.migrate = 'php artisan migrate';
+      context.databases.push({ type: 'mysql / postgresql', orm: 'eloquent' });
+    } else if (req['symfony/framework-bundle'] || req['symfony/symfony']) {
+      context.backendFramework = 'symfony';
+      context.architecturePattern = 'MVC (Symfony)';
+      context.commands.dev_server = 'symfony server:start';
+      context.databases.push({ type: 'relational', orm: 'doctrine' });
+    } else {
+      context.backendFramework = 'custom-php';
+    }
+
+    // Testing in PHP
+    if (req['pestphp/pest']) {
+      context.testFramework = 'pest';
+      context.commands.test = 'vendor/bin/pest';
+    } else if (req['phpunit/phpunit']) {
+      context.testFramework = 'phpunit';
+      context.commands.test = context.backendFramework === 'laravel' ? 'php artisan test' : 'vendor/bin/phpunit';
+    }
+
+    context.commands.install = context.commands.install ? context.commands.install + ' && composer install' : 'composer install';
+  }
+
+  // 2. Detect Package.json (Node.js / React / Next.js / Vue / Angular / TypeScript)
+  const pkgJsonPath = path.join(projectRoot, 'package.json');
+  const pkg = safeReadJson(pkgJsonPath);
+  if (pkg) {
+    if (!composer && pkg.name) context.projectName = pkg.name;
+    if (!context.description && pkg.description) context.description = pkg.description;
+    if (pkg.version) context.version = pkg.version;
+
+    const allDeps = {
+      ...(pkg.dependencies || {}),
+      ...(pkg.devDependencies || {}),
+    };
+
+    const hasTs = Boolean(allDeps['typescript'] || fs.existsSync(path.join(projectRoot, 'tsconfig.json')));
+
+    // Framework detection
+    if (allDeps['next']) {
+      context.frontendFramework = 'next';
+      context.frontendLanguage = hasTs ? 'typescript' : 'javascript';
+      if (!context.backendFramework) {
+        context.backendFramework = 'nextjs-api';
+        context.backendLanguage = hasTs ? 'typescript' : 'javascript';
+      }
+      context.architecturePattern = dirExists(path.join(projectRoot, 'src', 'app')) || dirExists(path.join(projectRoot, 'app'))
+        ? 'Next.js App Router'
+        : 'Next.js Pages Router';
+    } else if (allDeps['react']) {
+      context.frontendFramework = 'react';
+      context.frontendLanguage = hasTs ? 'typescript' : 'javascript';
+    } else if (allDeps['vue']) {
+      context.frontendFramework = 'vue';
+      context.frontendLanguage = hasTs ? 'typescript' : 'javascript';
+    } else if (allDeps['@angular/core']) {
+      context.frontendFramework = 'angular';
+      context.frontendLanguage = 'typescript';
+    }
+
+    // Backend Node detection if not PHP
+    if (!context.backendFramework) {
+      if (allDeps['@nestjs/core']) {
+        context.backendFramework = 'nestjs';
+        context.backendLanguage = 'typescript';
+        context.architecturePattern = 'Modular / Dependency Injection (NestJS)';
+      } else if (allDeps['express']) {
+        context.backendFramework = 'express';
+        context.backendLanguage = hasTs ? 'typescript' : 'javascript';
+      } else if (allDeps['fastify']) {
+        context.backendFramework = 'fastify';
+        context.backendLanguage = hasTs ? 'typescript' : 'javascript';
+      } else if (allDeps['koa']) {
+        context.backendFramework = 'koa';
+        context.backendLanguage = hasTs ? 'typescript' : 'javascript';
+      }
+    }
+
+    // Styling
+    if (allDeps['tailwindcss'] || fs.existsSync(path.join(projectRoot, 'tailwind.config.js')) || fs.existsSync(path.join(projectRoot, 'tailwind.config.ts'))) {
+      context.styling = 'tailwind';
+    } else if (allDeps['styled-components']) {
+      context.styling = 'styled-components';
+    } else if (allDeps['@mui/material'] || allDeps['@material-ui/core']) {
+      context.styling = 'material-ui';
+    }
+
+    // Database / ORM in Node
+    if (allDeps['prisma'] || allDeps['@prisma/client']) {
+      context.databases.push({ type: 'relational / mongodb', orm: 'prisma' });
+      if (!context.commands.migrate) context.commands.migrate = 'npx prisma migrate dev';
+    }
+    if (allDeps['typeorm']) {
+      context.databases.push({ type: 'relational', orm: 'typeorm' });
+    }
+    if (allDeps['drizzle-orm']) {
+      context.databases.push({ type: 'relational', orm: 'drizzle' });
+    }
+    if (allDeps['mongoose']) {
+      context.databases.push({ type: 'mongodb', orm: 'mongoose' });
+    }
+
+    // Testing framework
+    if (allDeps['vitest']) {
+      context.testFramework = context.testFramework || 'vitest';
+      context.commands.test = context.commands.test || 'npx vitest run';
+    } else if (allDeps['jest']) {
+      context.testFramework = context.testFramework || 'jest';
+      context.commands.test = context.commands.test || 'npm test';
+    }
+
+    // Scripts extraction
+    const scripts = pkg.scripts || {};
+    if (scripts.dev) context.commands.dev_server = context.commands.dev_server || 'npm run dev';
+    else if (scripts.start) context.commands.dev_server = context.commands.dev_server || 'npm start';
+
+    if (scripts.build) context.commands.build = 'npm run build';
+    if (scripts.test) context.commands.test = context.commands.test || 'npm test';
+    if (scripts.lint) context.commands.lint = 'npm run lint';
+
+    context.commands.install = context.commands.install ? context.commands.install + ' && npm install' : 'npm install';
+  }
+
+  // 3. Detect Python (Django / FastAPI / Flask)
+  const pyproject = safeReadFile(path.join(projectRoot, 'pyproject.toml'));
+  const reqTxt = safeReadFile(path.join(projectRoot, 'requirements.txt'));
+  const pyContent = pyproject + '\n' + reqTxt;
+  if (pyContent.trim()) {
+    if (!context.backendLanguage) {
+      context.backendLanguage = 'python';
+      if (/fastapi/i.test(pyContent)) {
+        context.backendFramework = 'fastapi';
+        context.commands.dev_server = 'uvicorn main:app --reload';
+      } else if (/django/i.test(pyContent)) {
+        context.backendFramework = 'django';
+        context.architecturePattern = 'MVT (Django)';
+        context.commands.dev_server = 'python manage.py runserver';
+        context.commands.migrate = 'python manage.py migrate';
+        context.databases.push({ type: 'relational', orm: 'django-orm' });
+      } else if (/flask/i.test(pyContent)) {
+        context.backendFramework = 'flask';
+        context.commands.dev_server = 'flask run';
+      }
+
+      if (/pytest/i.test(pyContent) || fs.existsSync(path.join(projectRoot, 'pytest.ini'))) {
+        context.testFramework = 'pytest';
+        context.commands.test = 'pytest';
+      }
+      context.commands.install = context.commands.install || 'pip install -r requirements.txt';
+    }
+  }
+
+  // 4. Inspect Directory Structure for Layers & Key Dirs
+  const candidateDirs = [
+    { path: 'app/Http/Controllers', layer: 'Controllers (HTTP Layer)' },
+    { path: 'app/Services', layer: 'Services (Business Logic)' },
+    { path: 'app/Models', layer: 'Models (Data Access)' },
+    { path: 'database/migrations', layer: 'Database Migrations' },
+    { path: 'routes', layer: 'Routing' },
+    { path: 'src/app', layer: 'Next.js App Router Pages & APIs' },
+    { path: 'src/components', layer: 'UI Components' },
+    { path: 'src/services', layer: 'Frontend / API Services' },
+    { path: 'src/hooks', layer: 'Custom React Hooks' },
+    { path: 'src/controllers', layer: 'Controllers' },
+    { path: 'src/models', layer: 'Data Models' },
+    { path: 'tests', layer: 'Automated Tests' },
+    { path: '__tests__', layer: 'Automated Tests' },
+  ];
+
+  for (const c of candidateDirs) {
+    if (dirExists(path.join(projectRoot, c.path))) {
+      context.layers.push({ name: c.layer, path: c.path });
+      context.keyDirectories.push({ path: c.path, purpose: c.layer });
+    }
+  }
+
+  // Fallback defaults if empty
+  if (!context.commands.test) {
+    context.commands.test = 'echo "No test runner configured"';
+  }
+  if (!context.commands.install) {
+    context.commands.install = 'echo "No package manager detected"';
+  }
+
+  return context;
+}
+
+/**
+ * Generate formatted Markdown for .agents/project-context.md
+ */
+function renderProjectContextMarkdown(ctx) {
+  const dbLines = ctx.databases.length > 0
+    ? ctx.databases.map(d => `  - type: "${d.type}"\n    orm: "${d.orm}"`).join('\n')
+    : `  - type: "unknown"\n    orm: "unknown"`;
+
+  const layerLines = ctx.layers.length > 0
+    ? ctx.layers.map(l => `  - name: "${l.name}"\n    path: "${l.path}"`).join('\n')
+    : `  - name: "Core"\n    path: "src/"`;
+
+  const keyDirLines = ctx.keyDirectories.length > 0
+    ? ctx.keyDirectories.map(k => `  - path: "${k.path}"\n    purpose: "${k.purpose}"`).join('\n')
+    : `  - path: "src/"\n    purpose: "Source files"`;
+
+  return `# Project Context
+
+> **Instructions for the AI agent:** Read this file first when starting any task in this project.
+> Do NOT overwrite this file without user permission.
+> Generated automatically by \`ai-dev-starter init\`.
+
+---
+
+## Project Identity
+
+\`\`\`yaml
+project_name: "${ctx.projectName}"
+version: "${ctx.version}"
+description: "${ctx.description || 'Application codebase'}"
+repository: "${ctx.repository || 'local'}"
+\`\`\`
+
+---
+
+## Tech Stack
+
+\`\`\`yaml
+# Backend
+backend_language: "${ctx.backendLanguage || 'not-specified'}"
+backend_framework: "${ctx.backendFramework || 'not-specified'}"
+backend_version: "${ctx.backendVersion || ''}"
+
+# Frontend
+frontend_framework: "${ctx.frontendFramework}"
+frontend_language: "${ctx.frontendLanguage || 'not-specified'}"
+styling: "${ctx.styling || 'not-specified'}"
+
+# Database
+databases:
+${dbLines}
+
+# Infrastructure
+hosting: "unknown"
+containerized: ${fs.existsSync(path.join(ctx.projectRoot || '', 'Dockerfile')) || fs.existsSync(path.join(ctx.projectRoot || '', 'docker-compose.yml'))}
+ci_cd: "${dirExists(path.join(ctx.projectRoot || '', '.github', 'workflows')) ? 'GitHub Actions' : 'none'}"
+\`\`\`
+
+---
+
+## Architecture
+
+\`\`\`yaml
+pattern: "${ctx.architecturePattern}"
+layers:
+${layerLines}
+
+key_directories:
+${keyDirLines}
+\`\`\`
+
+---
+
+## Development Commands
+
+\`\`\`yaml
+install: "${ctx.commands.install}"
+dev_server: "${ctx.commands.dev_server}"
+build: "${ctx.commands.build}"
+test: "${ctx.commands.test}"
+lint: "${ctx.commands.lint}"
+migrate: "${ctx.commands.migrate}"
+\`\`\`
+
+---
+
+## Testing Setup
+
+\`\`\`yaml
+backend_test_framework: "${ctx.testFramework || 'unknown'}"
+test_directory: "${ctx.testDirectory}"
+integration_tests: false
+e2e_tests: false
+coverage_target: 80
+\`\`\`
+
+---
+
+## Review and Report Settings
+
+\`\`\`yaml
+report_language: "${ctx.reportLanguage}"       # fa = Persian (Farsi), en = English
+severity_threshold: "${ctx.severityThreshold}"    # Minimum severity to include in reports (P0, P1, P2, P3)
+\`\`\`
+
+---
+
+## Important Constraints
+
+\`\`\`yaml
+# Safety constraints enforced across all AI workflows
+never_do:
+  - "Never commit or push directly to git"
+  - "Never run destructive migrations in production"
+  - "Never expose environment credentials or secrets"
+  - "Never make edits outside the user-requested scope"
+\`\`\`
+
+---
+
+## Project Notes
+
+<!-- Add any additional context the AI should know about this project. -->
+`;
+}
+
+module.exports = {
+  detectProjectContext,
+  renderProjectContextMarkdown,
+};

package/standards/backend.md

@@ -0,0 +1,84 @@
+# Backend Code Standards
+
+> **Scope:** Universal backend principles. Technology-specific extensions are in project-context.md.
+> **Load:** On demand when performing backend reviews or development.
+
+---
+
+## Universal Principles
+
+### Error Handling
+- Never swallow exceptions silently (`catch {}` without logging or re-throwing).
+- Return consistent error formats from APIs (standardized error envelope).
+- Distinguish between client errors (4xx) and server errors (5xx).
+- Do not expose internal stack traces or database errors to API consumers.
+
+### Input Validation
+- Validate all input at the entry point (controller, job handler, CLI command).
+- Validate type, format, range, and length.
+- Reject unexpected fields (allowlist approach, not denylist).
+- Return specific, actionable validation error messages to the client.
+
+### Database Interactions
+- Use parameterized queries or ORM query builders. Never concatenate user input into SQL.
+- Wrap multi-step mutations in transactions.
+- Use `SELECT` with explicit column lists, not `SELECT *` in production code.
+- Add `LIMIT` to any query that could return unbounded results.
+
+### Authentication and Authorization
+- Authenticate identity before any data operation.
+- Authorize the specific action after authentication.
+- Use established, framework-provided mechanisms — do not roll custom auth.
+- Expire tokens and sessions. Implement refresh token rotation.
+
+### Logging
+- Log security-relevant events: login, logout, permission denial, data export.
+- Never log credentials, tokens, passwords, or PII.
+- Include correlation IDs for request tracing.
+
+---
+
+## PHP / Laravel Specifics
+
+### Eloquent
+- Define `$fillable` on all models. Never use `$guarded = []` in production.
+- Use eager loading (`with()`) to prevent N+1 queries.
+- Scope complex queries to dedicated query scopes or repository classes.
+- Use `firstOrFail()` / `findOrFail()` for user-facing lookups.
+
+### Services
+- One responsibility per service class.
+- Inject dependencies via constructor, not facade or static calls, in service classes.
+- Return typed results (custom response objects or typed arrays) rather than raw arrays.
+
+### Commands and Jobs
+- Validate input data before long-running operations.
+- Implement idempotency for jobs that may be retried.
+- Use `$this->fail()` explicitly when a job should not be retried.
+
+---
+
+## Node.js / TypeScript Specifics
+
+### Async
+- Use `async/await` throughout. Avoid callback style in new code.
+- Handle Promise rejections. Never leave unhandled rejections.
+- Do not block the event loop with synchronous I/O in request handlers.
+
+### Type Safety
+- Prefer `unknown` over `any` for external data.
+- Validate and narrow external data at boundaries (API responses, request bodies).
+- Use Zod, io-ts, or similar for runtime type validation.
+
+### Error Handling
+- Use `Result` types or typed error classes rather than relying on caught `Error` objects.
+- Never use `try/catch` to suppress errors — rethrow or handle explicitly.
+
+---
+
+## Python Specifics
+
+- Use type annotations (`def fn(x: int) -> str`).
+- Validate external data with Pydantic or similar.
+- Use context managers (`with`) for resource cleanup.
+- Prefer explicit error handling over broad `except Exception`.

package/standards/database.md

@@ -0,0 +1,100 @@
+# Database Standards
+
+> **Scope:** Universal database principles for relational (MySQL, PostgreSQL) and document (MongoDB) databases.
+> **Load:** On demand for database-related reviews and development.
+
+---
+
+## Schema Design
+
+### Naming Conventions
+- Table names: `snake_case`, plural nouns (`orders`, `user_profiles`).
+- Column names: `snake_case`.
+- Primary keys: `id` (auto-increment integer or UUID — be consistent).
+- Foreign keys: `{referenced_table_singular}_id` (e.g., `user_id`, `order_id`).
+- Boolean columns: `is_`, `has_`, `can_` prefix (`is_active`, `has_subscription`).
+- Timestamp columns: `created_at`, `updated_at`, `deleted_at`.
+
+### Data Integrity
+- Define foreign key constraints. Do not rely on application-level integrity alone.
+- Specify `ON DELETE` behavior explicitly (`CASCADE`, `SET NULL`, `RESTRICT`).
+- Use `NOT NULL` by default. Allow `NULL` only when absence is semantically meaningful.
+- Use appropriate column types — do not store numbers as strings or dates as strings.
+- Apply `UNIQUE` constraints at the database level for unique business identifiers.
+
+### Indexes
+- Index every foreign key column.
+- Index columns used in frequent `WHERE`, `ORDER BY`, and `JOIN` conditions.
+- Use composite indexes when queries filter on multiple columns together.
+- Do not over-index: indexes slow down writes and consume space.
+- Review the `EXPLAIN` plan for queries on large tables.
+
+---
+
+## Migrations
+
+### Rules
+- Migrations must be reversible (implement `down()` method).
+- Never modify an already-applied migration. Create a new migration.
+- Do not perform data transformations in schema migrations that could fail on large datasets — use a separate data migration or background job.
+- Never drop a column immediately after removing it from application code. Deprecate first, deploy, then drop.
+
+### Dangerous Migration Patterns
+- Adding a `NOT NULL` column without a default to a large table (table lock risk).
+- Renaming a column while application code still references the old name.
+- Dropping a table that still has application references.
+- Running heavy data updates in a migration (causes long deployment downtime).
+
+---
+
+## Query Standards
+
+### Safety
+- Never concatenate user input into SQL strings.
+- Always use parameterized queries or ORM query builders.
+- Apply row-level authorization in queries, not only at the route level.
+
+### Performance
+- Avoid `SELECT *`. Specify columns explicitly.
+- Apply `LIMIT` to all queries that could return unbounded result sets.
+- Avoid `SELECT COUNT(*)` on large tables in hot paths — use approximate counts or cache.
+- Prefer `EXISTS` over `IN` for subqueries on large sets.
+- Do not load entire result sets into memory when streaming would suffice.
+
+### Transactions
+Wrap the following in transactions:
+- Any operation that modifies 2+ related tables.
+- Financial or inventory operations.
+- Operations that must succeed atomically.
+
+```php
+// PHP / Laravel
+DB::transaction(function () {
+    // Multiple operations
+});
+```
+
+```javascript
+// Prisma (Node.js)
+await prisma.$transaction([
+    prisma.order.create({ data: orderData }),
+    prisma.inventory.update({ where: { id }, data: { stock: { decrement: qty } } }),
+]);
+```
+
+---
+
+## Soft Deletes
+
+- Use soft deletes (`deleted_at`) for user-visible records (users, orders, products).
+- Ensure soft-deleted records are excluded from all queries by default.
+- Ensure indexes account for `deleted_at IS NULL` filter where relevant.
+
+---
+
+## Sensitive Data
+
+- Never store passwords in plaintext or with weak hashing (MD5, SHA1).
+- Use bcrypt, argon2, or scrypt with appropriate cost factors.
+- Encrypt PII at rest when regulations require it.
+- Never store payment card numbers or CVVs directly — use a payment vault.

package/standards/frontend.md

@@ -0,0 +1,81 @@
+# Frontend Code Standards
+
+> **Scope:** Universal frontend principles. Technology-specific additions via project-context.md.
+> **Load:** On demand when performing frontend reviews or development.
+
+---
+
+## Universal Principles
+
+### Component Design
+- One component, one responsibility.
+- Keep components small. When a component exceeds 150 lines, consider extracting sub-components.
+- Separate presentation from business logic and data fetching.
+- Props should be the minimum necessary. Do not thread unrelated data through components.
+
+### State Management
+- Minimize global state. Prefer local component state when data is not shared.
+- Colocate state as close to its usage as possible.
+- Do not mutate state directly. Always use the framework's state setter.
+
+### Accessibility
+- All interactive elements must be keyboard accessible.
+- Images must have descriptive `alt` attributes.
+- Forms must have associated labels.
+- Color must not be the only way to convey information.
+
+### Performance
+- Lazy load routes and heavy components.
+- Do not perform expensive operations in render functions.
+- Avoid unnecessary re-renders (memoize when measurable benefit exists).
+- Paginate or virtualize long lists.
+
+### Security
+- Sanitize before inserting HTML dynamically (`dangerouslySetInnerHTML`, `v-html`, `innerHTML`).
+- Do not store sensitive data in `localStorage` or `sessionStorage`.
+- Apply Content Security Policy headers.
+- Validate data from API responses before trusting it.
+
+---
+
+## React / Next.js Specifics
+
+### Components
+- Use functional components with hooks. No class components in new code.
+- Use TypeScript interfaces for all props.
+- Use named exports, not default exports, for components.
+- Use `React.memo()` only when profiling identifies unnecessary re-renders.
+
+### Hooks
+- Follow rules of hooks (call only at top level, only in React functions).
+- Extract complex hook logic into custom hooks.
+- Include all reactive values in `useEffect` dependency arrays.
+- Clean up side effects in `useEffect` return functions.
+
+### Data Fetching
+- Use React Query / SWR / Next.js data fetching patterns — not bare `useEffect` with `fetch`.
+- Handle loading, error, and empty states explicitly.
+- Do not expose API error details to end users.
+
+### Forms
+- Use a form library (React Hook Form, Formik) for complex forms.
+- Validate both client-side (UX) and server-side (security).
+- Disable submit buttons on submission to prevent double submission.
+
+---
+
+## Vue / Nuxt Specifics
+
+- Use Composition API (not Options API) in new code.
+- Define prop types with `defineProps<Props>()` using TypeScript.
+- Avoid `v-html` unless the content is explicitly sanitized.
+- Use `defineEmits` for component events with type safety.
+
+---
+
+## General CSS / Styling
+
+- Use CSS custom properties (variables) for design tokens.
+- Prefer utility frameworks (Tailwind) or CSS Modules to avoid global CSS conflicts.
+- Do not use `!important` to work around specificity issues.
+- Test responsive layouts at defined breakpoints.