diff --git a/.agents/skills/rep/SKILL.md b/.agents/skills/rep/SKILL.md new file mode 100644 index 0000000..6607ce2 --- /dev/null +++ b/.agents/skills/rep/SKILL.md @@ -0,0 +1,131 @@ +```markdown +# rep Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This TypeScript monorepo follows a structured development approach with automated release management, comprehensive CI/CD workflows, and a CLI-focused architecture. The codebase emphasizes conventional commits, automated documentation generation, and gateway-based functionality with strong testing practices using Vitest. + +## Coding Conventions + +### File Naming +- Use **camelCase** for all TypeScript files +- Test files follow the pattern `*.test.ts` +- Documentation uses `.mdx` extension in `docs/src/content/` + +### Import/Export Style +```typescript +// Use relative imports +import { someFunction } from './utils/helper' +import { ConfigType } from '../types/config' + +// Use named exports +export { processCommand } from './commands' +export type { CommandOptions } from './types' +``` + +### Commit Messages +Follow conventional commit format: +``` +feat: add new CLI command for gateway management +fix: resolve dependency resolution issue +chore: update package versions across workspace +``` +- Average commit message length: ~68 characters +- Use prefixes: `feat`, `chore`, `fix` + +## Workflows + +### Automated Release +**Trigger:** When ready to create a new release +**Command:** `/release` + +1. Update version numbers in `.release-please-manifest.json` +2. Generate or update `CHANGELOG.md` files for each affected package +3. Bump version numbers in all relevant `package.json` files +4. Commit changes with message format: `chore(main): release` +5. Let release-please bot handle tagging and GitHub release creation + +### CI Workflow Optimization +**Trigger:** When build processes need improvement or workflow issues arise +**Command:** `/fix-ci` + +1. Review current workflow trigger conditions in `.github/workflows/*.yml` +2. Update job dependencies and execution conditions +3. Modify workflow steps for better performance +4. Update branch targeting or event triggers +5. Test workflow changes on feature branch before merging + +### Documentation Update +**Trigger:** When updating content, SEO, or site structure +**Command:** `/update-docs` + +1. Modify relevant `.mdx` files in `docs/src/content/docs/` +2. Update meta tags, titles, and descriptions for SEO +3. Modify `docs/astro.config.mjs` if structural changes needed +4. Regenerate Astro content modules and data store +5. Preview changes locally before committing + +### Package Dependency Update +**Trigger:** When updating dependencies or aligning package versions +**Command:** `/update-deps` + +1. Update version numbers in affected `package.json` files +2. Run `pnpm install` to regenerate `pnpm-lock.yaml` +3. Update cross-package dependency references +4. Run tests to verify compatibility: `pnpm test` +5. Update example projects if they depend on changed packages + +### CLI Feature Enhancement +**Trigger:** When implementing new CLI commands or fixing existing functionality +**Command:** `/enhance-cli` + +1. Implement changes in `cli/src/**/*.ts` files +2. Add or update corresponding tests in `cli/src/**/__tests__/*.ts` +3. Update CLI documentation in `docs/src/content/docs/reference/cli.mdx` +4. Update any related configuration files +5. Test CLI functionality manually and via automated tests + +### Gateway Configuration Update +**Trigger:** When updating gateway versions or fixing gateway integration +**Command:** `/update-gateway` + +1. Update gateway version references in relevant files +2. Modify `cli/scripts/postinstall.js` for binary handling +3. Update Docker configurations if gateway affects containerization +4. Update CLI gateway integration code +5. Test gateway functionality across different environments + +## Testing Patterns + +### Test Structure +```typescript +// Use Vitest framework +import { describe, it, expect } from 'vitest' +import { functionToTest } from '../src/module' + +describe('Module Name', () => { + it('should handle expected input correctly', () => { + const result = functionToTest('input') + expect(result).toBe('expected output') + }) +}) +``` + +### File Organization +- Place tests in `__tests__` directories within source folders +- Use descriptive test file names: `commandProcessor.test.ts` +- Group related tests using `describe` blocks + +## Commands + +| Command | Purpose | +|---------|---------| +| `/release` | Trigger automated release process with version bumps and changelog generation | +| `/fix-ci` | Optimize GitHub Actions workflows and fix CI/CD issues | +| `/update-docs` | Update documentation content and site configuration | +| `/update-deps` | Update package dependencies across the monorepo | +| `/enhance-cli` | Add or improve CLI functionality with tests and documentation | +| `/update-gateway` | Update gateway configuration and integration | +``` \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4323d57 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,382 @@ +# AGENTS.md — Agent context for REP (Runtime Environment Protocol) + +## Project Identity + +**Name:** REP — Runtime Environment Protocol +**Organisation:** Ruach Tech (`github.com/ruachtech`) +**Author:** Olamide Adebayo +**License:** Spec documents under CC BY 4.0, code under Apache 2.0 +**Status:** v0.1.x released — gateway `v0.1.2`, npm packages `v0.1.3`. CI/CD pipeline operational. Spec status: Active. + +--- + +## What This Project Is + +REP is an open specification and reference implementation for injecting environment variables into browser-hosted applications **at container runtime** rather than at build time. It solves the fundamental contradiction that containers should be environment-agnostic artifacts, but frontend builds bake in environment-specific config via static string replacement (`process.env.*`, `import.meta.env.*`). + +REP introduces: +1. A **three-tier security classification** (PUBLIC / SENSITIVE / SERVER) via naming convention +2. **AES-256-GCM encryption** for sensitive variables +3. **HMAC-SHA256 integrity verification** + SRI hashing on every payload +4. **Automatic secret detection guardrails** (Shannon entropy, known key format matching) +5. **Hot config reload** via Server-Sent Events (optional) +6. A **lightweight Go gateway binary** (~3–5MB, zero dependencies, `FROM scratch` compatible) +7. A **zero-dependency TypeScript SDK** (~1.5KB gzipped) with synchronous access for public vars + +--- + +## File Structure + +``` +rep/ +├── .github/workflows/ +│ ├── gateway.yml # Go CI (vet, test, build) — path-filtered with status gate +│ ├── sdk.yml # TypeScript packages CI — path-filtered with status gate +│ ├── docs.yml # Docs build + Cloudflare deploy — path-filtered with status gate +│ └── release-sdk.yml # Release workflow (npm + GoReleaser + Docker) +│ +├── package.json # Monorepo root (pnpm 9.0.0, private) +├── pnpm-workspace.yaml # Workspace: sdk, cli, adapters/*, codemod, examples/* +├── pnpm-lock.yaml +├── release-please-config.json # Release-please config for all packages +├── .release-please-manifest.json # Per-package version tracker +├── .gitignore +├── CONTRIBUTING.md +├── README.md +├── LICENSE +│ +├── spec/ +│ ├── REP-RFC-0001.md # Core protocol specification (14 sections) +│ ├── SECURITY-MODEL.md # Threat model, 7 threat analyses +│ └── INTEGRATION-GUIDE.md # Framework patterns, CI/CD, K8s, migration +│ +├── schema/ +│ ├── rep-payload.schema.json +│ └── rep-manifest.schema.json +│ +├── gateway/ # Go reference implementation (zero deps) +│ ├── .goreleaser.yml # Multi-platform release config +│ ├── Dockerfile # Multi-stage, FROM scratch final +│ ├── Makefile +│ ├── VERSION # "0.1.2" +│ ├── go.mod # Go 1.24.5, zero external deps +│ ├── cmd/rep-gateway/ +│ │ └── main.go # Entrypoint: flags, signals, graceful shutdown +│ ├── internal/ +│ │ ├── config/ +│ │ │ ├── config.go # CLI flag + env var parsing (REP_GATEWAY_*) +│ │ │ ├── classify.go # Reads REP_* vars → PUBLIC/SENSITIVE/SERVER +│ │ │ ├── envfile.go # .env file parsing +│ │ │ └── *_test.go +│ │ ├── crypto/ +│ │ │ ├── crypto.go # AES-256-GCM, HMAC-SHA256, SRI hash +│ │ │ ├── session_key.go # /rep/session-key: rate limiting, single-use, CORS +│ │ │ └── *_test.go +│ │ ├── guardrails/ +│ │ │ ├── guardrails.go # Secret detection: entropy, known formats +│ │ │ └── guardrails_test.go +│ │ ├── health/ +│ │ │ ├── health.go # /rep/health endpoint +│ │ │ └── health_test.go +│ │ ├── hotreload/ +│ │ │ ├── hotreload.go # /rep/changes SSE hub +│ │ │ └── hotreload_test.go +│ │ ├── inject/ +│ │ │ ├── inject.go # HTML injection middleware (mutex-protected, compression-aware) +│ │ │ └── inject_test.go +│ │ ├── manifest/ +│ │ │ ├── manifest.go # Hand-rolled YAML subset parser (zero deps) +│ │ │ └── manifest_test.go +│ │ └── server/ +│ │ ├── server.go # Orchestrator: startup, proxy/embedded modes, reload +│ │ └── server_test.go +│ ├── pkg/payload/ +│ │ ├── payload.go # Payload builder: JSON +