diff --git a/.agents/skills/HitAPI/SKILL.md b/.agents/skills/HitAPI/SKILL.md new file mode 100644 index 0000000..d09d7a4 --- /dev/null +++ b/.agents/skills/HitAPI/SKILL.md @@ -0,0 +1,196 @@ +```markdown +# HitAPI Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This skill teaches you the core development conventions and workflows of the HitAPI TypeScript codebase. HitAPI is a modular API project (no framework detected) with a strong emphasis on clear module boundaries, conventional commits, and robust testing. You'll learn how to add new feature modules, refactor logging, manage environment configuration, extend ingestion pipelines, and write effective unit tests, all while following the project's established coding standards. + +--- + +## Coding Conventions + +### File Naming + +- **Files:** Use `kebab-case` for all file names. + - Example: `user-service.ts`, `environment-variables.dto.ts` +- **Directories:** Organize by feature/module under `apps/api/src/modules//`. + +### Imports + +- **Relative imports** are used throughout the codebase. + - Example: + ```typescript + import { UserEntity } from './entities/user.entity'; + ``` + +### Exports + +- **Named exports** are preferred. + - Example: + ```typescript + export interface UserDto { ... } + export const USER_CONSTANT = 'user'; + ``` + +### Commit Messages + +- **Conventional commits** with prefixes: `feat`, `refactor`, `chore`, `test`, `fix`, `docs`, `build` +- **Average length:** ~57 characters + +--- + +## Workflows + +### Add New Feature Module + +**Trigger:** When you want to add a new feature area (e.g., errors, traffic) to the API +**Command:** `/new-module` + +1. Create DTO files in `apps/api/src/modules//dto/` +2. Create entity files in `apps/api/src/modules//entities/` +3. Create enums and interfaces in `apps/api/src/modules//enums/` and `interfaces/` +4. Create repository files in `apps/api/src/modules//repositories/` +5. Create service files in `apps/api/src/modules//` +6. Create controller file in `apps/api/src/modules//` +7. Create module file in `apps/api/src/modules//` +8. Update constants in `apps/api/src/common/constants/` +9. Register the module in `apps/api/src/app.module.ts` + +**Example:** +```typescript +// apps/api/src/modules/errors/errors.module.ts +import { Module } from '...'; +import { ErrorsService } from './errors.service'; +import { ErrorsController } from './errors.controller'; + +@Module({ + providers: [ErrorsService], + controllers: [ErrorsController], +}) +export class ErrorsModule {} +``` + +--- + +### Refactor Module Logging to AppLoggerService + +**Trigger:** When standardizing logging across modules using `AppLoggerService` +**Command:** `/refactor-logging` + +1. Replace NestJS `Logger` imports with `AppLoggerService` in target files +2. Inject `AppLoggerService` via constructor where needed +3. Update all logger calls to use `AppLoggerService` +4. Update or add `AppLoggerService` mocks in related test files + +**Example:** +```typescript +// Before +import { Logger } from '@nestjs/common'; +private readonly logger = new Logger(MyService.name); + +// After +import { AppLoggerService } from '../../common/logger/app-logger.service'; +constructor(private readonly logger: AppLoggerService) {} +``` + +--- + +### Add or Update Env Configuration + +**Trigger:** When introducing or modifying environment variables or related config +**Command:** `/update-env` + +1. Edit or add environment variable in `apps/api/src/config/env/dto/environment-variables.dto.ts` +2. Update related configuration files in `apps/api/src/config/*/configuration.ts` +3. Update `.env.example` and/or `.env.local.example` with the new variable +4. Update code to use the new/changed environment variable + +**Example:** +```typescript +// apps/api/src/config/env/dto/environment-variables.dto.ts +export class EnvironmentVariablesDto { + API_KEY: string; + // ... +} +``` + +--- + +### Add Ingestion Pipeline or Processor + +**Trigger:** When adding a new ingestion flow (e.g., sync-data, startup-data) +**Command:** `/new-ingestion-pipeline` + +1. Create or update DTOs in `apps/api/src/modules/ingestion/dto/` +2. Add or update processor files in `apps/api/src/modules/ingestion/processors/` +3. Update job data types in `apps/api/src/modules/ingestion/types/` +4. Update or create service/controller logic in `apps/api/src/modules/ingestion/` +5. Update module registration in `apps/api/src/modules/ingestion/ingestion.module.ts` +6. Update queue constants if needed + +**Example:** +```typescript +// apps/api/src/modules/ingestion/processors/sync-data.processor.ts +import { Process, Processor } from '...'; +@Processor('sync-data') +export class SyncDataProcessor { + @Process() + async handle(job: Job) { ... } +} +``` + +--- + +### Add or Update Unit Tests for Module Service + +**Trigger:** When adding or improving unit tests for a service +**Command:** `/add-service-tests` + +1. Create or update `.spec.ts` files in the module's `tests` directory +2. Add/expand test cases for service logic and edge cases +3. Update mocks or test utilities as needed + +**Example:** +```typescript +// apps/api/src/modules/user/tests/user.service.spec.ts +import { UserService } from '../user.service'; + +describe('UserService', () => { + it('should return user by id', async () => { + // test logic here + }); +}); +``` + +--- + +## Testing Patterns + +- **Framework:** [Jest](https://jestjs.io/) +- **Test files:** Use the `.spec.ts` suffix and are placed in `tests` directories within each module. +- **Test Example:** + ```typescript + // apps/api/src/modules/errors/tests/errors.service.spec.ts + import { ErrorsService } from '../errors.service'; + + describe('ErrorsService', () => { + it('should log error', () => { + // ... + }); + }); + ``` + +--- + +## Commands + +| Command | Purpose | +|------------------------|--------------------------------------------------------------| +| /new-module | Scaffold a new feature module | +| /refactor-logging | Migrate module logging to AppLoggerService | +| /update-env | Add or update environment variable configuration | +| /new-ingestion-pipeline| Add a new ingestion pipeline or processor | +| /add-service-tests | Add or improve unit tests for a module's service | +``` diff --git a/.agents/skills/HitAPI/agents/openai.yaml b/.agents/skills/HitAPI/agents/openai.yaml new file mode 100644 index 0000000..cd5c897 --- /dev/null +++ b/.agents/skills/HitAPI/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "HitAPI" + short_description: "Repo-specific patterns and workflows for HitAPI" + default_prompt: "Use the HitAPI repo skill to follow existing architecture, testing, and workflow conventions." +policy: + allow_implicit_invocation: true \ No newline at end of file diff --git a/.claude/commands/add-new-feature-module.md b/.claude/commands/add-new-feature-module.md new file mode 100644 index 0000000..01b5bba --- /dev/null +++ b/.claude/commands/add-new-feature-module.md @@ -0,0 +1,42 @@ +--- +name: add-new-feature-module +description: Workflow command scaffold for add-new-feature-module in HitAPI. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /add-new-feature-module + +Use this workflow when working on **add-new-feature-module** in `HitAPI`. + +## Goal + +Implements a new domain module with entities, DTOs, interfaces, repositories, service, controller, and module registration. + +## Common Files + +- `apps/api/src/modules//dto/*.ts` +- `apps/api/src/modules//entities/*.ts` +- `apps/api/src/modules//enums/*.ts` +- `apps/api/src/modules//interfaces/*.ts` +- `apps/api/src/modules//repositories/*.ts` +- `apps/api/src/modules//*.service.ts` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Create DTO files in apps/api/src/modules//dto/ +- Create entity files in apps/api/src/modules//entities/ +- Create enums and interfaces in apps/api/src/modules//enums/ and interfaces/ +- Create repository files in apps/api/src/modules//repositories/ +- Create service files in apps/api/src/modules// + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/feature-development.md b/.claude/commands/feature-development.md new file mode 100644 index 0000000..fa23ec0 --- /dev/null +++ b/.claude/commands/feature-development.md @@ -0,0 +1,39 @@ +--- +name: feature-development +description: Workflow command scaffold for feature-development in HitAPI. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /feature-development + +Use this workflow when working on **feature-development** in `HitAPI`. + +## Goal + +Standard feature implementation workflow + +## Common Files + +- `apps/api/src/common/utils/*` +- `apps/api/src/modules/request-logs/dto/*` +- `apps/api/src/*` +- `**/*.test.*` +- `**/api/**` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Add feature implementation +- Add tests for feature +- Update documentation + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/refactoring.md b/.claude/commands/refactoring.md new file mode 100644 index 0000000..d6b48dc --- /dev/null +++ b/.claude/commands/refactoring.md @@ -0,0 +1,35 @@ +--- +name: refactoring +description: Workflow command scaffold for refactoring in HitAPI. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /refactoring + +Use this workflow when working on **refactoring** in `HitAPI`. + +## Goal + +Code refactoring and cleanup workflow + +## Common Files + +- `src/**/*` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Ensure tests pass before refactor +- Refactor code structure +- Verify tests still pass + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/ecc-tools.json b/.claude/ecc-tools.json new file mode 100644 index 0000000..6a417e4 --- /dev/null +++ b/.claude/ecc-tools.json @@ -0,0 +1,261 @@ +{ + "version": "1.3", + "schemaVersion": "1.0", + "generatedBy": "ecc-tools", + "generatedAt": "2026-03-31T13:01:23.121Z", + "repo": "https://github.com/TheSolom/HitAPI", + "profiles": { + "requested": "full", + "recommended": "full", + "effective": "developer", + "requestedAlias": "full", + "recommendedAlias": "full", + "effectiveAlias": "developer" + }, + "requestedProfile": "full", + "profile": "developer", + "recommendedProfile": "full", + "effectiveProfile": "developer", + "tier": "free", + "requestedComponents": [ + "repo-baseline", + "workflow-automation", + "security-audits", + "research-tooling", + "team-rollout", + "governance-controls" + ], + "selectedComponents": [ + "repo-baseline", + "workflow-automation" + ], + "requestedAddComponents": [], + "requestedRemoveComponents": [], + "blockedRemovalComponents": [], + "tierFilteredComponents": [ + "security-audits", + "research-tooling", + "team-rollout", + "governance-controls" + ], + "requestedRootPackages": [ + "runtime-core", + "workflow-pack", + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "selectedRootPackages": [ + "runtime-core", + "workflow-pack" + ], + "requestedPackages": [ + "runtime-core", + "workflow-pack", + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "requestedAddPackages": [], + "requestedRemovePackages": [], + "selectedPackages": [ + "runtime-core", + "workflow-pack" + ], + "packages": [ + "runtime-core", + "workflow-pack" + ], + "blockedRemovalPackages": [], + "tierFilteredRootPackages": [ + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "tierFilteredPackages": [ + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "conflictingPackages": [], + "dependencyGraph": { + "runtime-core": [], + "workflow-pack": [ + "runtime-core" + ] + }, + "resolutionOrder": [ + "runtime-core", + "workflow-pack" + ], + "requestedModules": [ + "runtime-core", + "workflow-pack", + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "selectedModules": [ + "runtime-core", + "workflow-pack" + ], + "modules": [ + "runtime-core", + "workflow-pack" + ], + "managedFiles": [ + ".claude/skills/HitAPI/SKILL.md", + ".agents/skills/HitAPI/SKILL.md", + ".agents/skills/HitAPI/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/HitAPI-instincts.yaml", + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md", + ".claude/commands/add-new-feature-module.md" + ], + "packageFiles": { + "runtime-core": [ + ".claude/skills/HitAPI/SKILL.md", + ".agents/skills/HitAPI/SKILL.md", + ".agents/skills/HitAPI/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/HitAPI-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md", + ".claude/commands/add-new-feature-module.md" + ] + }, + "moduleFiles": { + "runtime-core": [ + ".claude/skills/HitAPI/SKILL.md", + ".agents/skills/HitAPI/SKILL.md", + ".agents/skills/HitAPI/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/HitAPI-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md", + ".claude/commands/add-new-feature-module.md" + ] + }, + "files": [ + { + "moduleId": "runtime-core", + "path": ".claude/skills/HitAPI/SKILL.md", + "description": "Repository-specific Claude Code skill generated from git history." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/HitAPI/SKILL.md", + "description": "Codex-facing copy of the generated repository skill." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/HitAPI/agents/openai.yaml", + "description": "Codex skill metadata so the repo skill appears cleanly in the skill interface." + }, + { + "moduleId": "runtime-core", + "path": ".claude/identity.json", + "description": "Suggested identity.json baseline derived from repository conventions." + }, + { + "moduleId": "runtime-core", + "path": ".codex/config.toml", + "description": "Repo-local Codex MCP and multi-agent baseline aligned with ECC defaults." + }, + { + "moduleId": "runtime-core", + "path": ".codex/AGENTS.md", + "description": "Codex usage guide that points at the generated repo skill and workflow bundle." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/explorer.toml", + "description": "Read-only explorer role config for Codex multi-agent work." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/reviewer.toml", + "description": "Read-only reviewer role config focused on correctness and security." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/docs-researcher.toml", + "description": "Read-only docs researcher role config for API verification." + }, + { + "moduleId": "runtime-core", + "path": ".claude/homunculus/instincts/inherited/HitAPI-instincts.yaml", + "description": "Continuous-learning instincts derived from repository patterns." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/feature-development.md", + "description": "Workflow command scaffold for feature-development." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/refactoring.md", + "description": "Workflow command scaffold for refactoring." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/add-new-feature-module.md", + "description": "Workflow command scaffold for add-new-feature-module." + } + ], + "workflows": [ + { + "command": "feature-development", + "path": ".claude/commands/feature-development.md" + }, + { + "command": "refactoring", + "path": ".claude/commands/refactoring.md" + }, + { + "command": "add-new-feature-module", + "path": ".claude/commands/add-new-feature-module.md" + } + ], + "adapters": { + "claudeCode": { + "skillPath": ".claude/skills/HitAPI/SKILL.md", + "identityPath": ".claude/identity.json", + "commandPaths": [ + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md", + ".claude/commands/add-new-feature-module.md" + ] + }, + "codex": { + "configPath": ".codex/config.toml", + "agentsGuidePath": ".codex/AGENTS.md", + "skillPath": ".agents/skills/HitAPI/SKILL.md" + } + } +} \ No newline at end of file diff --git a/.claude/homunculus/instincts/inherited/HitAPI-instincts.yaml b/.claude/homunculus/instincts/inherited/HitAPI-instincts.yaml new file mode 100644 index 0000000..bb692e2 --- /dev/null +++ b/.claude/homunculus/instincts/inherited/HitAPI-instincts.yaml @@ -0,0 +1,706 @@ +# Instincts generated from https://github.com/TheSolom/HitAPI +# Generated: 2026-03-31T13:02:35.732Z +# Version: 2.0 +# NOTE: This file supplements (does not replace) any existing curated instincts. +# High-confidence manually curated instincts should be preserved alongside these. + +--- +id: HitAPI-commit-conventional +trigger: "when writing a commit message" +confidence: 0.85 +domain: git +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Commit Conventional + +## Action + +Use conventional commit format with prefixes: feat, refactor, chore, test, fix + +## Evidence + +- 200 commits analyzed +- Detected conventional commit pattern +- Examples: feat(logging): include error stack traces and adjust log levels for production transports, refactor(ingestion): add contextual logging and traceId propagation to ingestion flows + +--- +id: HitAPI-commit-length +trigger: "when writing a commit message" +confidence: 0.6 +domain: git +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Commit Length + +## Action + +Write moderate-length commit messages (~57 characters) + +## Evidence + +- Average commit message length: 57 chars +- Based on 200 commits + +--- +id: HitAPI-naming-files +trigger: "when creating a new file" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Naming Files + +## Action + +Use kebab-case naming convention + +## Evidence + +- Analyzed file naming patterns in repository +- Dominant pattern: kebab-case + +--- +id: HitAPI-import-relative +trigger: "when importing modules" +confidence: 0.75 +domain: code-style +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Import Relative + +## Action + +Use relative imports for project files + +## Evidence + +- Import analysis shows relative import pattern +- Example: import { x } from '../lib/x' + +--- +id: HitAPI-export-style +trigger: "when exporting from a module" +confidence: 0.7 +domain: code-style +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Export Style + +## Action + +Prefer named exports + +## Evidence + +- Export pattern analysis +- Dominant style: named + +--- +id: HitAPI-arch-feature-based +trigger: "when adding a new feature" +confidence: 0.85 +domain: architecture +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Arch Feature Based + +## Action + +Create a new folder in src/features/ with all related code colocated + +## Evidence + +- Feature-based module organization detected +- Structure: src/features/[feature-name]/ + +--- +id: HitAPI-test-framework +trigger: "when writing tests" +confidence: 0.9 +domain: testing +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Test Framework + +## Action + +Use jest as the test framework + +## Evidence + +- Test framework detected: jest +- File pattern: *.spec.ts + +--- +id: HitAPI-test-naming +trigger: "when creating a test file" +confidence: 0.85 +domain: testing +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Test Naming + +## Action + +Name test files using the pattern: *.spec.ts + +## Evidence + +- File pattern: *.spec.ts +- Consistent across test files + +--- +id: HitAPI-test-types +trigger: "when planning tests for a feature" +confidence: 0.7 +domain: testing +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Test Types + +## Action + +Write unit, integration, e2e tests to match project standards + +## Evidence + +- Test types detected: unit, integration, e2e +- Coverage config: no + +--- +id: HitAPI-workflow-feature-development +trigger: "when implementing a new feature" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Workflow Feature Development + +## Action + +Follow the feature-development workflow: +1. Add feature implementation +2. Add tests for feature +3. Update documentation + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~19x per month +- Files: apps/api/src/common/utils/*, apps/api/src/modules/request-logs/dto/*, apps/api/src/* + +--- +id: HitAPI-workflow-refactoring +trigger: "when refactoring code" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Workflow Refactoring + +## Action + +Follow the refactoring workflow: +1. Ensure tests pass before refactor +2. Refactor code structure +3. Verify tests still pass + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~13x per month +- Files: src/**/* + +--- +id: HitAPI-workflow-add-new-feature-module +trigger: "when doing add new feature module" +confidence: 0.6 +domain: workflow +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Workflow Add New Feature Module + +## Action + +Follow the add-new-feature-module workflow: +1. Create DTO files in apps/api/src/modules//dto/ +2. Create entity files in apps/api/src/modules//entities/ +3. Create enums and interfaces in apps/api/src/modules//enums/ and interfaces/ +4. Create repository files in apps/api/src/modules//repositories/ +5. Create service files in apps/api/src/modules// +6. Create controller file in apps/api/src/modules// +7. Create module file in apps/api/src/modules// +8. Update constants in apps/api/src/common/constants/ +9. Register module in apps/api/src/app.module.ts + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~2x per month +- Files: apps/api/src/modules//dto/*.ts, apps/api/src/modules//entities/*.ts, apps/api/src/modules//enums/*.ts + +--- +id: HitAPI-workflow-refactor-module-logging-to-apploggerservice +trigger: "when doing refactor module logging to apploggerservice" +confidence: 0.7 +domain: workflow +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Workflow Refactor Module Logging To Apploggerservice + +## Action + +Follow the refactor-module-logging-to-apploggerservice workflow: +1. Replace NestJS Logger imports with AppLoggerService in target files +2. Inject AppLoggerService via constructor where needed +3. Update all logger calls to use AppLoggerService +4. Update or add AppLoggerService mocks in related test files + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~4x per month +- Files: apps/api/src/modules/*/*.ts, apps/api/src/bootstrap/*.ts, apps/api/src/common/filters/*.ts + +--- +id: HitAPI-workflow-add-or-update-env-configuration +trigger: "when doing add or update env configuration" +confidence: 0.6 +domain: workflow +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Workflow Add Or Update Env Configuration + +## Action + +Follow the add-or-update-env-configuration workflow: +1. Edit or add environment variable in apps/api/src/config/env/dto/environment-variables.dto.ts +2. Update related configuration files in apps/api/src/config/*/configuration.ts +3. Update .env.example and/or .env.local.example with new variable +4. Update code to use new/changed environment variable + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~2x per month +- Files: apps/api/src/config/env/dto/environment-variables.dto.ts, apps/api/src/config/*/configuration.ts, apps/api/.env.example + +--- +id: HitAPI-workflow-add-ingestion-pipeline-or-processor +trigger: "when doing add ingestion pipeline or processor" +confidence: 0.6 +domain: workflow +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Workflow Add Ingestion Pipeline Or Processor + +## Action + +Follow the add-ingestion-pipeline-or-processor workflow: +1. Create or update DTOs in apps/api/src/modules/ingestion/dto/ +2. Add or update processor files in apps/api/src/modules/ingestion/processors/ +3. Update job data types in apps/api/src/modules/ingestion/types/ +4. Update or create service/controller logic in apps/api/src/modules/ingestion/ +5. Update module registration in apps/api/src/modules/ingestion/ingestion.module.ts +6. Update queue constants if needed + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~2x per month +- Files: apps/api/src/modules/ingestion/dto/*.ts, apps/api/src/modules/ingestion/processors/*.ts, apps/api/src/modules/ingestion/types/*.ts + +--- +id: HitAPI-workflow-add-or-update-unit-tests-for-module-service +trigger: "when doing add or update unit tests for module service" +confidence: 0.6 +domain: workflow +source: repo-analysis +source_repo: https://github.com/TheSolom/HitAPI +--- + +# HitAPI Workflow Add Or Update Unit Tests For Module Service + +## Action + +Follow the add-or-update-unit-tests-for-module-service workflow: +1. Create or update .spec.ts files in the module's tests directory +2. Add/expand test cases for service logic and edge cases +3. Update mocks or test utilities as needed + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~2x per month +- Files: apps/api/src/modules/*/tests/*.spec.ts + +--- +id: hitapi-naming-files-kebab-case +trigger: "When creating a new file" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Naming Files Kebab Case + +## Action + +Name the file using kebab-case (e.g., my-feature.service.ts) + +## Evidence + +- Pattern in codeStyle.namingConventions.files +- All files in apps/api/src/modules/*/*.ts follow kebab-case + +--- +id: hitapi-naming-functions-camelCase +trigger: "When defining a new function" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Naming Functions CamelCase + +## Action + +Name the function using camelCase (e.g., getRequestLogs) + +## Evidence + +- Pattern in codeStyle.namingConventions.functions +- Functions in apps/api/src/common/utils/period.util.ts use camelCase + +--- +id: hitapi-naming-classes-pascal-case +trigger: "When defining a new class" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Naming Classes Pascal Case + +## Action + +Name the class using PascalCase (e.g., RequestLogService) + +## Evidence + +- Pattern in codeStyle.namingConventions.classes +- Classes in apps/api/src/modules/request-logs/dto/*.ts use PascalCase + +--- +id: hitapi-naming-constants-screaming-snake-case +trigger: "When defining a constant" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Naming Constants Screaming Snake Case + +## Action + +Name the constant using SCREAMING_SNAKE_CASE (e.g., REDIS_DATABASE) + +## Evidence + +- Pattern in codeStyle.namingConventions.constants +- Seen in apps/api/src/common/constants/*.constant.ts + +--- +id: hitapi-imports-relative +trigger: "When importing modules within the repo" +confidence: 0.85 +domain: code-style +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Imports Relative + +## Action + +Use relative import paths (e.g., import { X } from '../../utils/x') + +## Evidence + +- Pattern in codeStyle.importStyle +- Imports in apps/api/src/modules/request-logs/dto/get-request-log-timeline-options.dto.ts + +--- +id: hitapi-exports-named +trigger: "When exporting from a module" +confidence: 0.85 +domain: code-style +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Exports Named + +## Action + +Use named exports (e.g., export { MyService }) + +## Evidence + +- Pattern in codeStyle.exportStyle +- Seen in apps/api/src/common/utils/period.util.ts + +--- +id: hitapi-test-file-pattern +trigger: "When creating a test file" +confidence: 0.9 +domain: testing +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Test File Pattern + +## Action + +Name the file with a .spec.ts suffix (e.g., my-feature.service.spec.ts) + +## Evidence + +- Pattern in testing.filePattern +- Seen in apps/api/src/modules/*/tests/*.spec.ts + +--- +id: hitapi-test-framework-jest +trigger: "When writing tests" +confidence: 0.9 +domain: testing +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Test Framework Jest + +## Action + +Use Jest as the testing framework + +## Evidence + +- Pattern in testing.framework +- Seen in package.json and test files + +--- +id: hitapi-test-types +trigger: "When planning tests for a module" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Test Types + +## Action + +Include unit, integration, and e2e tests as appropriate + +## Evidence + +- Pattern in testing.testTypes +- Seen in test files and workflow descriptions + +--- +id: hitapi-git-conventional-commits +trigger: "When writing a commit message" +confidence: 0.95 +domain: git +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Git Conventional Commits + +## Action + +Use Conventional Commits format: (): + +## Evidence + +- Pattern in commits.type +- Examples like 'feat(logging): include error stack traces...' + +--- +id: hitapi-git-commit-prefixes +trigger: "When choosing a commit type" +confidence: 0.9 +domain: git +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Git Commit Prefixes + +## Action + +Use one of the allowed prefixes: feat, refactor, chore, test, fix, docs, build + +## Evidence + +- Pattern in commits.prefixes +- Examples in commit history + +--- +id: hitapi-git-commit-length +trigger: "When writing a commit message" +confidence: 0.7 +domain: git +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Git Commit Length + +## Action + +Keep the commit message concise, around 57 characters on average + +## Evidence + +- Pattern in commits.averageLength +- Examples in commit history + +--- +id: hitapi-workflow-add-new-feature-module +trigger: "When adding a new feature area to the API" +confidence: 0.95 +domain: workflow +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Workflow Add New Feature Module + +## Action + +Create DTOs, entities, enums, interfaces, repositories, service, controller, module file, update constants, and register module in app.module.ts + +## Evidence + +- Workflow: add-new-feature-module +- Example commit sequences and files + +--- +id: hitapi-workflow-refactor-logging-to-apploggerservice +trigger: "When standardizing logging in a module" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Workflow Refactor Logging To Apploggerservice + +## Action + +Replace NestJS Logger with AppLoggerService, update DI, logger calls, and test mocks + +## Evidence + +- Workflow: refactor-module-logging-to-apploggerservice +- Example commit sequences and files + +--- +id: hitapi-workflow-add-or-update-env-configuration +trigger: "When introducing or modifying environment variables or config" +confidence: 0.85 +domain: workflow +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Workflow Add Or Update Env Configuration + +## Action + +Update environment-variables.dto.ts, related config files, .env.example, and code usage + +## Evidence + +- Workflow: add-or-update-env-configuration +- Example commit sequences and files + +--- +id: hitapi-workflow-add-ingestion-pipeline-or-processor +trigger: "When adding a new ingestion flow to the system" +confidence: 0.85 +domain: workflow +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Workflow Add Ingestion Pipeline Or Processor + +## Action + +Create/update DTOs, processors, types, service/controller logic, module registration, and queue constants + +## Evidence + +- Workflow: add-ingestion-pipeline-or-processor +- Example commit sequences and files + +--- +id: hitapi-workflow-add-or-update-unit-tests-for-module-service +trigger: "When adding or improving unit tests for a service" +confidence: 0.8 +domain: workflow +source: repo-analysis +source_repo: TheSolom/HitAPI +--- + +# Hitapi Workflow Add Or Update Unit Tests For Module Service + +## Action + +Create/update .spec.ts files, add/expand test cases, and update mocks/utilities + +## Evidence + +- Workflow: add-or-update-unit-tests-for-module-service +- Example commit sequences and files + diff --git a/.claude/identity.json b/.claude/identity.json new file mode 100644 index 0000000..5445450 --- /dev/null +++ b/.claude/identity.json @@ -0,0 +1,14 @@ +{ + "version": "2.0", + "technicalLevel": "technical", + "preferredStyle": { + "verbosity": "minimal", + "codeComments": true, + "explanations": true + }, + "domains": [ + "typescript" + ], + "suggestedBy": "ecc-tools-repo-analysis", + "createdAt": "2026-03-31T13:02:35.732Z" +} \ No newline at end of file diff --git a/.claude/skills/HitAPI/SKILL.md b/.claude/skills/HitAPI/SKILL.md new file mode 100644 index 0000000..d09d7a4 --- /dev/null +++ b/.claude/skills/HitAPI/SKILL.md @@ -0,0 +1,196 @@ +```markdown +# HitAPI Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This skill teaches you the core development conventions and workflows of the HitAPI TypeScript codebase. HitAPI is a modular API project (no framework detected) with a strong emphasis on clear module boundaries, conventional commits, and robust testing. You'll learn how to add new feature modules, refactor logging, manage environment configuration, extend ingestion pipelines, and write effective unit tests, all while following the project's established coding standards. + +--- + +## Coding Conventions + +### File Naming + +- **Files:** Use `kebab-case` for all file names. + - Example: `user-service.ts`, `environment-variables.dto.ts` +- **Directories:** Organize by feature/module under `apps/api/src/modules//`. + +### Imports + +- **Relative imports** are used throughout the codebase. + - Example: + ```typescript + import { UserEntity } from './entities/user.entity'; + ``` + +### Exports + +- **Named exports** are preferred. + - Example: + ```typescript + export interface UserDto { ... } + export const USER_CONSTANT = 'user'; + ``` + +### Commit Messages + +- **Conventional commits** with prefixes: `feat`, `refactor`, `chore`, `test`, `fix`, `docs`, `build` +- **Average length:** ~57 characters + +--- + +## Workflows + +### Add New Feature Module + +**Trigger:** When you want to add a new feature area (e.g., errors, traffic) to the API +**Command:** `/new-module` + +1. Create DTO files in `apps/api/src/modules//dto/` +2. Create entity files in `apps/api/src/modules//entities/` +3. Create enums and interfaces in `apps/api/src/modules//enums/` and `interfaces/` +4. Create repository files in `apps/api/src/modules//repositories/` +5. Create service files in `apps/api/src/modules//` +6. Create controller file in `apps/api/src/modules//` +7. Create module file in `apps/api/src/modules//` +8. Update constants in `apps/api/src/common/constants/` +9. Register the module in `apps/api/src/app.module.ts` + +**Example:** +```typescript +// apps/api/src/modules/errors/errors.module.ts +import { Module } from '...'; +import { ErrorsService } from './errors.service'; +import { ErrorsController } from './errors.controller'; + +@Module({ + providers: [ErrorsService], + controllers: [ErrorsController], +}) +export class ErrorsModule {} +``` + +--- + +### Refactor Module Logging to AppLoggerService + +**Trigger:** When standardizing logging across modules using `AppLoggerService` +**Command:** `/refactor-logging` + +1. Replace NestJS `Logger` imports with `AppLoggerService` in target files +2. Inject `AppLoggerService` via constructor where needed +3. Update all logger calls to use `AppLoggerService` +4. Update or add `AppLoggerService` mocks in related test files + +**Example:** +```typescript +// Before +import { Logger } from '@nestjs/common'; +private readonly logger = new Logger(MyService.name); + +// After +import { AppLoggerService } from '../../common/logger/app-logger.service'; +constructor(private readonly logger: AppLoggerService) {} +``` + +--- + +### Add or Update Env Configuration + +**Trigger:** When introducing or modifying environment variables or related config +**Command:** `/update-env` + +1. Edit or add environment variable in `apps/api/src/config/env/dto/environment-variables.dto.ts` +2. Update related configuration files in `apps/api/src/config/*/configuration.ts` +3. Update `.env.example` and/or `.env.local.example` with the new variable +4. Update code to use the new/changed environment variable + +**Example:** +```typescript +// apps/api/src/config/env/dto/environment-variables.dto.ts +export class EnvironmentVariablesDto { + API_KEY: string; + // ... +} +``` + +--- + +### Add Ingestion Pipeline or Processor + +**Trigger:** When adding a new ingestion flow (e.g., sync-data, startup-data) +**Command:** `/new-ingestion-pipeline` + +1. Create or update DTOs in `apps/api/src/modules/ingestion/dto/` +2. Add or update processor files in `apps/api/src/modules/ingestion/processors/` +3. Update job data types in `apps/api/src/modules/ingestion/types/` +4. Update or create service/controller logic in `apps/api/src/modules/ingestion/` +5. Update module registration in `apps/api/src/modules/ingestion/ingestion.module.ts` +6. Update queue constants if needed + +**Example:** +```typescript +// apps/api/src/modules/ingestion/processors/sync-data.processor.ts +import { Process, Processor } from '...'; +@Processor('sync-data') +export class SyncDataProcessor { + @Process() + async handle(job: Job) { ... } +} +``` + +--- + +### Add or Update Unit Tests for Module Service + +**Trigger:** When adding or improving unit tests for a service +**Command:** `/add-service-tests` + +1. Create or update `.spec.ts` files in the module's `tests` directory +2. Add/expand test cases for service logic and edge cases +3. Update mocks or test utilities as needed + +**Example:** +```typescript +// apps/api/src/modules/user/tests/user.service.spec.ts +import { UserService } from '../user.service'; + +describe('UserService', () => { + it('should return user by id', async () => { + // test logic here + }); +}); +``` + +--- + +## Testing Patterns + +- **Framework:** [Jest](https://jestjs.io/) +- **Test files:** Use the `.spec.ts` suffix and are placed in `tests` directories within each module. +- **Test Example:** + ```typescript + // apps/api/src/modules/errors/tests/errors.service.spec.ts + import { ErrorsService } from '../errors.service'; + + describe('ErrorsService', () => { + it('should log error', () => { + // ... + }); + }); + ``` + +--- + +## Commands + +| Command | Purpose | +|------------------------|--------------------------------------------------------------| +| /new-module | Scaffold a new feature module | +| /refactor-logging | Migrate module logging to AppLoggerService | +| /update-env | Add or update environment variable configuration | +| /new-ingestion-pipeline| Add a new ingestion pipeline or processor | +| /add-service-tests | Add or improve unit tests for a module's service | +``` diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md new file mode 100644 index 0000000..1457888 --- /dev/null +++ b/.codex/AGENTS.md @@ -0,0 +1,28 @@ +# ECC for Codex CLI + +This supplements the root `AGENTS.md` with a repo-local ECC baseline. + +## Repo Skill + +- Repo-generated Codex skill: `.agents/skills/HitAPI/SKILL.md` +- Claude-facing companion skill: `.claude/skills/HitAPI/SKILL.md` +- Keep user-specific credentials and private MCPs in `~/.codex/config.toml`, not in this repo. + +## MCP Baseline + +Treat `.codex/config.toml` as the default ECC-safe baseline for work in this repository. +The generated baseline enables GitHub, Context7, Exa, Memory, Playwright, and Sequential Thinking. + +## Multi-Agent Support + +- Explorer: read-only evidence gathering +- Reviewer: correctness, security, and regression review +- Docs researcher: API and release-note verification + +## Workflow Files + +- `.claude/commands/feature-development.md` +- `.claude/commands/refactoring.md` +- `.claude/commands/add-new-feature-module.md` + +Use these workflow files as reusable task scaffolds when the detected repository workflows recur. \ No newline at end of file diff --git a/.codex/agents/docs-researcher.toml b/.codex/agents/docs-researcher.toml new file mode 100644 index 0000000..0daae57 --- /dev/null +++ b/.codex/agents/docs-researcher.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Verify APIs, framework behavior, and release-note claims against primary documentation before changes land. +Cite the exact docs or file paths that support each claim. +Do not invent undocumented behavior. +""" \ No newline at end of file diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml new file mode 100644 index 0000000..732df7a --- /dev/null +++ b/.codex/agents/explorer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Stay in exploration mode. +Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them. +Prefer targeted search and file reads over broad scans. +""" \ No newline at end of file diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 0000000..b13ed9c --- /dev/null +++ b/.codex/agents/reviewer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "high" +sandbox_mode = "read-only" + +developer_instructions = """ +Review like an owner. +Prioritize correctness, security, behavioral regressions, and missing tests. +Lead with concrete findings and avoid style-only feedback unless it hides a real bug. +""" \ No newline at end of file diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..bc1ee67 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,48 @@ +#:schema https://developers.openai.com/codex/config-schema.json + +# ECC Tools generated Codex baseline +approval_policy = "on-request" +sandbox_mode = "workspace-write" +web_search = "live" + +[mcp_servers.github] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-github"] + +[mcp_servers.context7] +command = "npx" +args = ["-y", "@upstash/context7-mcp@latest"] + +[mcp_servers.exa] +url = "https://mcp.exa.ai/mcp" + +[mcp_servers.memory] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-memory"] + +[mcp_servers.playwright] +command = "npx" +args = ["-y", "@playwright/mcp@latest", "--extension"] + +[mcp_servers.sequential-thinking] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-sequential-thinking"] + +[features] +multi_agent = true + +[agents] +max_threads = 6 +max_depth = 1 + +[agents.explorer] +description = "Read-only codebase explorer for gathering evidence before changes are proposed." +config_file = "agents/explorer.toml" + +[agents.reviewer] +description = "PR reviewer focused on correctness, security, and missing tests." +config_file = "agents/reviewer.toml" + +[agents.docs_researcher] +description = "Documentation specialist that verifies APIs, framework behavior, and release notes." +config_file = "agents/docs-researcher.toml" \ No newline at end of file