@synapta/skills 0.1.0 → 0.1.2

package/skills/repo-bootstrap/references/examples/express-api-ts/src/AGENTS.md

@@ -0,0 +1,91 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2026-02-05 -->
+
+# AGENTS.md — src
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+Backend services (TypeScript/Node.js)
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+| File | Purpose |
+|------|---------|
+| `src/config.ts` | (add description) |
+| `src/routes/health.ts` | Add database connectivity check here |
+| `src/routes/users.ts` | (add description) |
+| `src/index.ts` | Middleware |
+| `src/utils/logger.ts` | (add description) |
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+| Pattern | Reference |
+|---------|-----------|
+| Standard implementation | `src/controllers/userController.ts` |
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+- Install: `pnpm install`
+- Node version: >=20.0.0
+- Package manager: pnpm
+- Environment variables: See .env or .env.example
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+- Typecheck (project-wide): `pnpm typecheck`
+- Format: `pnpm format`
+- Lint: `pnpm lint`
+- Test: `pnpm test`
+- Build: `pnpm build`
+- Dev server: `pnpm dev`
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Use TypeScript strict mode (`strict: true` in tsconfig)
+- No `any` without explicit justification comment
+- Prefer `interface` over `type` for object shapes
+- Naming: `camelCase` for functions/vars, `PascalCase` for classes/types
+- Async/await over raw Promises
+- Prefer `const` over `let`, never use `var`
+- Destructure objects and arrays when appropriate
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Validate all user inputs (use zod or similar)
+- Parameterized queries only (no string concatenation)
+- Never use dynamic code execution with user data
+- Sensitive data: never log or expose in errors
+- Environment: use dotenv, never hardcode secrets
+- CORS: configure explicitly, no wildcard in production
+- Rate limiting: implement for public endpoints
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] Tests pass: `pnpm test`
+- [ ] Type check clean: `pnpm typecheck`
+- [ ] Lint clean: `pnpm lint`
+- [ ] Formatted: `pnpm format`
+- [ ] No `any` types without justification
+- [ ] API endpoints have validation
+- [ ] Error responses don't leak internals
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check Node.js docs: https://nodejs.org/docs
+- TypeScript handbook: https://www.typescriptlang.org/docs
+- Review existing patterns in this codebase
+- Check root AGENTS.md for project-wide conventions
+<!-- AGENTS-GENERATED:END help -->

package/skills/repo-bootstrap/references/examples/express-api-ts/src/config.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+const envSchema = z.object({
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  DATABASE_URL: z.string().url().optional(),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  JWT_SECRET: z.string().min(32).optional(),
+  CORS_ORIGIN: z.string().url().optional(),
+});
+
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+  console.error('Invalid environment variables:', parsed.error.flatten().fieldErrors);
+  process.exit(1);
+}
+
+export const config = {
+  port: parsed.data.PORT,
+  nodeEnv: parsed.data.NODE_ENV,
+  databaseUrl: parsed.data.DATABASE_URL,
+  logLevel: parsed.data.LOG_LEVEL,
+  jwtSecret: parsed.data.JWT_SECRET,
+  corsOrigin: parsed.data.CORS_ORIGIN,
+  isDev: parsed.data.NODE_ENV === 'development',
+  isProd: parsed.data.NODE_ENV === 'production',
+} as const;

package/skills/repo-bootstrap/references/examples/express-api-ts/src/controllers/userController.ts

@@ -0,0 +1,74 @@
+import type { Request, Response, NextFunction } from 'express';
+import { z } from 'zod';
+import { AppError } from '../utils/errors.js';
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+});
+
+const updateUserSchema = createUserSchema.partial();
+
+// In-memory store for demo purposes
+const users = new Map<string, { id: string; email: string; name: string }>();
+
+export class UserController {
+  getAll = async (_req: Request, res: Response): Promise<void> => {
+    const allUsers = Array.from(users.values());
+    res.json({ data: allUsers });
+  };
+
+  getById = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const user = users.get(req.params.id ?? '');
+    if (!user) {
+      next(new AppError('User not found', 404));
+      return;
+    }
+    res.json({ data: user });
+  };
+
+  create = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const parsed = createUserSchema.safeParse(req.body);
+    if (!parsed.success) {
+      next(new AppError('Validation failed', 400, parsed.error.flatten()));
+      return;
+    }
+
+    const id = crypto.randomUUID();
+    const user = { id, ...parsed.data };
+    users.set(id, user);
+
+    res.status(201).json({ data: user });
+  };
+
+  update = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const id = req.params.id ?? '';
+    const existing = users.get(id);
+    if (!existing) {
+      next(new AppError('User not found', 404));
+      return;
+    }
+
+    const parsed = updateUserSchema.safeParse(req.body);
+    if (!parsed.success) {
+      next(new AppError('Validation failed', 400, parsed.error.flatten()));
+      return;
+    }
+
+    const updated = { ...existing, ...parsed.data };
+    users.set(id, updated);
+
+    res.json({ data: updated });
+  };
+
+  delete = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const id = req.params.id ?? '';
+    if (!users.has(id)) {
+      next(new AppError('User not found', 404));
+      return;
+    }
+
+    users.delete(id);
+    res.status(204).send();
+  };
+}

package/skills/repo-bootstrap/references/examples/express-api-ts/src/index.ts

@@ -0,0 +1,26 @@
+import express from 'express';
+import { config } from './config.js';
+import { logger } from './utils/logger.js';
+import { errorHandler } from './middleware/errorHandler.js';
+import { requestLogger } from './middleware/requestLogger.js';
+import { userRoutes } from './routes/users.js';
+import { healthRoutes } from './routes/health.js';
+
+const app = express();
+
+// Middleware
+app.use(express.json());
+app.use(requestLogger);
+
+// Routes
+app.use('/api/users', userRoutes);
+app.use('/health', healthRoutes);
+
+// Error handling (must be last)
+app.use(errorHandler);
+
+app.listen(config.port, () => {
+  logger.info(`Server running on port ${config.port}`);
+});
+
+export { app };

package/skills/repo-bootstrap/references/examples/express-api-ts/src/middleware/errorHandler.ts

@@ -0,0 +1,45 @@
+import type { Request, Response, NextFunction } from 'express';
+import { AppError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+import { config } from '../config.js';
+
+interface ErrorResponse {
+  error: {
+    message: string;
+    code?: string;
+    details?: unknown;
+    stack?: string;
+  };
+}
+
+export function errorHandler(
+  err: Error,
+  _req: Request,
+  res: Response<ErrorResponse>,
+  _next: NextFunction
+): void {
+  logger.error('Request error', { error: err.message, stack: err.stack });
+
+  if (err instanceof AppError) {
+    res.status(err.statusCode).json({
+      error: {
+        message: err.message,
+        code: err.code,
+        details: err.details,
+      },
+    });
+    return;
+  }
+
+  // Unknown error - don't leak internals in production
+  const message = config.isProd ? 'Internal server error' : err.message;
+  const response: ErrorResponse = {
+    error: { message },
+  };
+
+  if (!config.isProd) {
+    response.error.stack = err.stack;
+  }
+
+  res.status(500).json(response);
+}

package/skills/repo-bootstrap/references/examples/express-api-ts/src/middleware/requestLogger.ts

@@ -0,0 +1,18 @@
+import type { Request, Response, NextFunction } from 'express';
+import { logger } from '../utils/logger.js';
+
+export function requestLogger(req: Request, res: Response, next: NextFunction): void {
+  const start = Date.now();
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    logger.info('Request completed', {
+      method: req.method,
+      path: req.path,
+      status: res.statusCode,
+      duration: `${duration}ms`,
+    });
+  });
+
+  next();
+}

package/skills/repo-bootstrap/references/examples/express-api-ts/src/routes/health.ts

@@ -0,0 +1,18 @@
+import { Router, type Request, type Response } from 'express';
+
+const router = Router();
+
+router.get('/', (_req: Request, res: Response) => {
+  res.json({
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),
+  });
+});
+
+router.get('/ready', (_req: Request, res: Response) => {
+  // Add database connectivity check here
+  res.json({ ready: true });
+});
+
+export { router as healthRoutes };

package/skills/repo-bootstrap/references/examples/express-api-ts/src/routes/users.ts

@@ -0,0 +1,13 @@
+import { Router } from 'express';
+import { UserController } from '../controllers/userController.js';
+
+const router = Router();
+const controller = new UserController();
+
+router.get('/', controller.getAll);
+router.get('/:id', controller.getById);
+router.post('/', controller.create);
+router.put('/:id', controller.update);
+router.delete('/:id', controller.delete);
+
+export { router as userRoutes };

package/skills/repo-bootstrap/references/examples/express-api-ts/src/utils/errors.ts

@@ -0,0 +1,40 @@
+export class AppError extends Error {
+  public readonly statusCode: number;
+  public readonly code?: string;
+  public readonly details?: unknown;
+
+  constructor(message: string, statusCode: number = 500, details?: unknown, code?: string) {
+    super(message);
+    this.name = 'AppError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+
+    // Maintain proper stack trace
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  static badRequest(message: string, details?: unknown): AppError {
+    return new AppError(message, 400, details, 'BAD_REQUEST');
+  }
+
+  static unauthorized(message = 'Unauthorized'): AppError {
+    return new AppError(message, 401, undefined, 'UNAUTHORIZED');
+  }
+
+  static forbidden(message = 'Forbidden'): AppError {
+    return new AppError(message, 403, undefined, 'FORBIDDEN');
+  }
+
+  static notFound(resource = 'Resource'): AppError {
+    return new AppError(`${resource} not found`, 404, undefined, 'NOT_FOUND');
+  }
+
+  static conflict(message: string): AppError {
+    return new AppError(message, 409, undefined, 'CONFLICT');
+  }
+
+  static internal(message = 'Internal server error'): AppError {
+    return new AppError(message, 500, undefined, 'INTERNAL_ERROR');
+  }
+}

package/skills/repo-bootstrap/references/examples/express-api-ts/src/utils/logger.ts

@@ -0,0 +1,14 @@
+import winston from 'winston';
+import { config } from '../config.js';
+
+export const logger = winston.createLogger({
+  level: config.logLevel,
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    config.isDev
+      ? winston.format.combine(winston.format.colorize(), winston.format.simple())
+      : winston.format.json()
+  ),
+  transports: [new winston.transports.Console()],
+});

package/skills/repo-bootstrap/references/examples/express-api-ts/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/skills/repo-bootstrap/references/examples/fastapi-app/.env.example

@@ -0,0 +1,19 @@
+# Application Settings
+APP_NAME=fastapi-app
+APP_ENV=development
+DEBUG=true
+
+# Server Configuration
+HOST=0.0.0.0
+PORT=8000
+WORKERS=1
+
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/fastapi_app
+
+# Security
+SECRET_KEY=your-secret-key-change-in-production
+API_KEY=your-api-key
+
+# External Services
+REDIS_URL=redis://localhost:6379/0

package/skills/repo-bootstrap/references/examples/fastapi-app/AGENTS.md

@@ -0,0 +1,92 @@
+<!-- FOR AI AGENTS - Human readability is a side effect, not a goal -->
+<!-- Managed by agent: keep sections and order; edit content, not structure -->
+<!-- Last updated: 2026-02-05 | Last verified: never -->
+
+# AGENTS.md
+
+**Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only.
+
+## Commands (unverified)
+> Source: pyproject.toml — CI-sourced commands are most reliable
+
+<!-- AGENTS-GENERATED:START commands -->
+| Task | Command | ~Time |
+|------|---------|-------|
+| Typecheck | mypy . | ~15s |
+| Lint | ruff check . | ~10s |
+| Format | ruff format . | ~5s |
+| Test (single) | pytest | ~2s |
+| Test (all) | pytest | ~30s |
+<!-- AGENTS-GENERATED:END commands -->
+
+> If commands fail, verify against Makefile/package.json/composer.json or ask user to update.
+
+## Workflow
+1. **Before coding**: Read nearest `AGENTS.md` + check Golden Samples for the area you're touching
+2. **After each change**: Run the smallest relevant check (lint → typecheck → single test)
+3. **Before committing**: Run full test suite if changes affect >2 files or touch shared code
+
+## File Map
+<!-- AGENTS-GENERATED:START filemap -->
+```
+src/             → application source code
+```
+<!-- AGENTS-GENERATED:END filemap -->
+
+## Golden Samples (follow these patterns)
+<!-- AGENTS-GENERATED:START golden-samples -->
+| For | Reference | Key patterns |
+|-----|-----------|--------------|
+| Entrypoint | `src/main.py` |  (async) |
+| Service | `src/services/item_service.py` |  (class) |
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+## Heuristics (quick decisions)
+<!-- AGENTS-GENERATED:START heuristics -->
+| When | Do |
+|------|-----|
+| Adding dependency | Update `pyproject.toml` |
+| Adding env var | Add to `.env.example` first |
+| Committing | Use Conventional Commits (feat:, fix:, docs:, etc.) |
+| Merging PRs | Squash and merge |
+| Adding dependency | Ask first - we minimize deps |
+| Unsure about pattern | Check Golden Samples above |
+<!-- AGENTS-GENERATED:END heuristics -->
+
+## Repository Settings
+<!-- AGENTS-GENERATED:START repo-settings -->
+- **Default branch:** `main`
+- **Merge strategy:** squash, merge, rebase
+<!-- AGENTS-GENERATED:END repo-settings -->
+
+## Boundaries
+
+### Always Do
+- Run pre-commit checks before committing
+- Add tests for new code paths
+- Use conventional commit format: `type(scope): subject`
+- Follow PEP 8 style guide and Python >=3.11 features
+
+### Ask First
+- Adding new dependencies
+- Modifying CI/CD configuration
+- Changing public API signatures
+- Running full e2e test suites
+- Repo-wide refactoring or rewrites
+
+### Never Do
+- Commit secrets, credentials, or sensitive data
+- Modify vendor/, node_modules/, or generated files
+- Push directly to main/master branch
+- Delete migration files or schema changes
+- Commit requirements.txt without pyproject.toml changes
+- Use print() for logging in production code
+
+## Index of scoped AGENTS.md
+<!-- AGENTS-GENERATED:START scope-index -->
+- `./src/AGENTS.md` — Backend services (Python)
+<!-- AGENTS-GENERATED:END scope-index -->
+
+## When instructions conflict
+The nearest `AGENTS.md` wins. Explicit user prompts override files.
+- For Python-specific patterns, follow PEP 8 and project tooling (ruff/black)

package/skills/repo-bootstrap/references/examples/fastapi-app/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "fastapi-app"
+version = "0.1.0"
+description = "Example FastAPI application for AGENTS.md generator testing"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Test Author", email = "test@example.com" }
+]
+dependencies = [
+    "fastapi>=0.109.0",
+    "uvicorn[standard]>=0.27.0",
+    "pydantic>=2.5.0",
+    "pydantic-settings>=2.1.0",
+    "sqlalchemy>=2.0.25",
+    "alembic>=1.13.0",
+    "httpx>=0.26.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.1.14",
+    "mypy>=1.8.0",
+    "pre-commit>=3.6.0",
+]
+
+[project.scripts]
+serve = "src.main:run"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["src"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = ["uvicorn.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-v --cov=src --cov-report=term-missing"
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]

package/skills/repo-bootstrap/references/examples/fastapi-app/src/AGENTS.md

@@ -0,0 +1,85 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2026-02-05 -->
+
+# AGENTS.md — src
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+Backend services (Python)
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+| File | Purpose |
+|------|---------|
+| `src/config.py` | Application |
+| `src/__init__.py` | (add description) |
+| `src/services/__init__.py` | (add description) |
+| `src/services/item_service.py` | (add description) |
+| `src/services/user_service.py` | (add description) |
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+| Pattern | Reference |
+|---------|-----------|
+| Standard implementation | `src/services/item_service.py` |
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+- Install: `pip install -e .`
+- Python version: >=3.11
+- Package manager: uv
+- Environment variables: See .env or .env.example
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+- Typecheck: `mypy .`
+- Format: `ruff format .`
+- Lint: `ruff check .`
+- Test: `pytest`
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Follow PEP 8 style guide
+- Use type hints for all function signatures
+- Naming: `snake_case` for functions/variables, `PascalCase` for classes
+- Docstrings: Google style, required for public APIs
+- Imports: group by stdlib, third-party, local (use isort)
+- Modern Python: prefer `|` over `Union`, `list` over `List`
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Validate and sanitize all user inputs
+- Use parameterized queries for database access
+- Never use dynamic code execution with untrusted data
+- Sensitive data: never log or expose in errors
+- File paths: validate and use `pathlib` for path operations
+- Subprocess: use list args, avoid shell=True with user input
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] Tests pass: `pytest`
+- [ ] Type check clean: `mypy .`
+- [ ] Lint clean: `ruff check .`
+- [ ] Formatted: `ruff format .`
+- [ ] Public functions have docstrings
+<!-- AGENTS-GENERATED:END checklist -->
+
+<!-- AGENTS-GENERATED:START examples -->
+## Patterns to Follow
+> **Prefer looking at real code in this repo over generic examples.**
+> See **Golden Samples** section above for files that demonstrate correct patterns.
+<!-- AGENTS-GENERATED:END examples -->
+
+<!-- AGENTS-GENERATED:START help -->
+## When stuck
+- Check Python documentation: https://docs.python.org
+- Review existing patterns in this codebase
+- Check root AGENTS.md for project-wide conventions
+- Use `python -m pydoc <module>` for stdlib help
+<!-- AGENTS-GENERATED:END help -->