@synapta/skills 0.1.0 → 0.1.2

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/AGENTS.md

@@ -0,0 +1,89 @@
+<!-- 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: go.mod — CI-sourced commands are most reliable
+
+<!-- AGENTS-GENERATED:START commands -->
+| Task | Command | ~Time |
+|------|---------|-------|
+| Typecheck | go build -v ./... | ~15s |
+| Format | gofmt -w . | ~5s |
+| Test (single) | go test -v -race | ~2s |
+| Test (all) | go test -v -race -short ./... | ~30s |
+| Build | go build -v ./... | ~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 -->
+```
+internal/        → internal packages (not exported)
+```
+<!-- AGENTS-GENERATED:END filemap -->
+
+## Golden Samples (follow these patterns)
+<!-- AGENTS-GENERATED:START golden-samples -->
+| For | Reference | Key patterns |
+|-----|-----------|--------------|
+| Entrypoint | `main.go` | standard patterns |
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+## Heuristics (quick decisions)
+<!-- AGENTS-GENERATED:START heuristics -->
+| When | Do |
+|------|-----|
+| Adding package | Internal → `internal/`, Public → `pkg/` |
+| 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 Go 1.22 conventions and idioms
+
+### 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 go.sum without go.mod changes
+
+## Index of scoped AGENTS.md
+<!-- AGENTS-GENERATED:START scope-index -->
+- `./internal/web/AGENTS.md` — Frontend application (TypeScript/React/Vue)
+<!-- AGENTS-GENERATED:END scope-index -->
+
+## When instructions conflict
+The nearest `AGENTS.md` wins. Explicit user prompts override files.
+- For Go-specific patterns, defer to language idioms and standard library conventions

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/go.mod

@@ -0,0 +1,2 @@
+module example.com/go-app
+go 1.22

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/internal/web/AGENTS.md

@@ -0,0 +1,90 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2026-02-04 -->
+
+# AGENTS.md — web
+
+<!-- AGENTS-GENERATED:START overview -->
+## Overview
+Frontend application (TypeScript/React/Vue)
+<!-- AGENTS-GENERATED:END overview -->
+
+<!-- AGENTS-GENERATED:START filemap -->
+## Key Files
+| File | Purpose |
+|------|---------|
+| `internal/web/src/Sidebar.tsx` | (add description) |
+| `internal/web/src/App.tsx` | (add description) |
+| `internal/web/src/Button.tsx` | (add description) |
+| `internal/web/src/Header.tsx` | (add description) |
+| `internal/web/src/Footer.tsx` | (add description) |
+<!-- AGENTS-GENERATED:END filemap -->
+
+<!-- AGENTS-GENERATED:START golden-samples -->
+## Golden Samples (follow these patterns)
+| Pattern | Reference |
+|---------|-----------|
+| Standard implementation | `internal/web/src/Sidebar.tsx` |
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+<!-- AGENTS-GENERATED:START setup -->
+## Setup & environment
+- Framework: react
+- Package manager: npm
+- Environment variables: See .env.example
+<!-- AGENTS-GENERATED:END setup -->
+
+<!-- AGENTS-GENERATED:START commands -->
+## Build & tests
+- Install: `npm install`
+- Typecheck: `npx tsc --noEmit`
+- Lint: `npx eslint .`
+- Format: `npx prettier --write .`
+- Test: `npm test`
+- Build: `npm run build`
+- Dev server: `npm run dev`
+<!-- AGENTS-GENERATED:END commands -->
+
+<!-- AGENTS-GENERATED:START code-style -->
+## Code style & conventions
+- Follow tsconfig.json compiler options
+- Use functional components with hooks
+- Naming: `camelCase` for variables/functions, `PascalCase` for components
+- File naming: `ComponentName.tsx`, `utilityName.ts`
+- Imports: group and sort (external, internal, types)
+- Avoid class components
+<!-- AGENTS-GENERATED:END code-style -->
+
+<!-- AGENTS-GENERATED:START security -->
+## Security & safety
+- Sanitize user inputs before rendering
+- Raw HTML rendering only with sanitized content (use DOMPurify)
+- Validate environment variables at build time
+- Never expose secrets in client-side code
+- Use HTTPS for all API calls
+- Implement CSP headers
+- WCAG 2.2 AA accessibility compliance
+<!-- AGENTS-GENERATED:END security -->
+
+<!-- AGENTS-GENERATED:START checklist -->
+## PR/commit checklist
+- [ ] Tests pass: `npm test`
+- [ ] TypeScript compiles: `npx tsc --noEmit`
+- [ ] Lint clean: `npx eslint .`
+- [ ] Formatted: `npx prettier --write .`
+- [ ] Accessibility: keyboard navigation works, ARIA labels present
+- [ ] Responsive: tested on mobile, tablet, desktop
+- [ ] Performance: no unnecessary re-renders
+<!-- 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 React documentation: https://react.dev
+- Review TypeScript handbook: https://www.typescriptlang.org/docs/
+- Check root AGENTS.md for project-wide conventions
+- Review existing components for patterns
+<!-- AGENTS-GENERATED:END help -->

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/internal/web/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "internal-web",
+    "private": true,
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "test": "vitest"
+    },
+    "dependencies": {
+        "react": "^18.2.0",
+        "react-dom": "^18.2.0"
+    },
+    "devDependencies": {
+        "vite": "^8.0.8",
+        "vitest": "^1.0.0"
+    }
+}

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/internal/web/src/App.tsx

@@ -0,0 +1 @@
+export default function App() { return <div>App</div>; }

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/internal/web/src/Button.tsx

@@ -0,0 +1 @@
+export default function Button() { return <div>Button</div>; }

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/internal/web/src/Footer.tsx

@@ -0,0 +1 @@
+export default function Footer() { return <div>Footer</div>; }

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/internal/web/src/Header.tsx

@@ -0,0 +1 @@
+export default function Header() { return <div>Header</div>; }

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/internal/web/src/Sidebar.tsx

@@ -0,0 +1 @@
+export default function Sidebar() { return <div>Sidebar</div>; }

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/main.go

@@ -0,0 +1,7 @@
+package main
+
+import "fmt"
+
+func main() {
+    fmt.Println("Hello from Go backend")
+}

package/skills/repo-bootstrap/references/examples/go-with-internal-web-tsx/package.json

@@ -0,0 +1,12 @@
+{
+    "name": "frontend",
+    "scripts": {
+        "build": "vite build",
+        "test": "vitest"
+    },
+    "devDependencies": {
+        "react": "^18.0.0",
+        "vite": "^8.0.8",
+        "vitest": "^1.0.0"
+    }
+}

package/skills/repo-bootstrap/references/examples/ldap-selfservice/AGENTS.md

@@ -0,0 +1,70 @@
+<!-- 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: go.mod — CI-sourced commands are most reliable
+
+<!-- AGENTS-GENERATED:START commands -->
+| Task | Command | ~Time |
+|------|---------|-------|
+| Typecheck | go build -v ./... | ~15s |
+| Format | gofmt -w . | ~5s |
+| Test (single) | go test -v -race | ~2s |
+| Test (all) | go test -v -race -short ./... | ~30s |
+| Build | go build -v ./... | ~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
+
+## Heuristics (quick decisions)
+<!-- AGENTS-GENERATED:START heuristics -->
+| When | Do |
+|------|-----|
+| Adding package | Internal → `internal/`, Public → `pkg/` |
+| 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 Go 1.25 conventions and idioms
+
+### 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 go.sum without go.mod changes
+
+## When instructions conflict
+The nearest `AGENTS.md` wins. Explicit user prompts override files.
+- For Go-specific patterns, defer to language idioms and standard library conventions

package/skills/repo-bootstrap/references/examples/ldap-selfservice/go.mod

@@ -0,0 +1,3 @@
+module example.com/ldap-selfservice
+
+go 1.25

package/skills/repo-bootstrap/references/examples/ldap-selfservice/internal-AGENTS.md

@@ -0,0 +1,371 @@
+# Go Backend Services
+
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+
+**Scope**: Go backend packages in `internal/` directory
+
+**See also**: [../AGENTS.md](../AGENTS.md) for global standards, [web/AGENTS.md](web/AGENTS.md) for frontend
+
+## Overview
+
+Backend services for LDAP selfservice password change/reset functionality. Organized as internal Go packages:
+
+- **email/**: SMTP email service for password reset tokens
+- **options/**: Configuration management from environment variables
+- **ratelimit/**: IP-based rate limiting (3 req/hour default)
+- **resettoken/**: Cryptographic token generation and validation
+- **rpc/**: JSON-RPC 2.0 API handlers (password change/reset)
+- **validators/**: Password policy validation logic
+- **web/**: HTTP server setup, static assets, routing (see [web/AGENTS.md](web/AGENTS.md))
+
+## Setup/Environment
+
+**Required environment variables** (configure in `.env.local`):
+
+```bash
+# LDAP connection
+LDAP_URL=ldaps://ldap.example.com:636
+LDAP_USER_BASE_DN=ou=users,dc=example,dc=com
+LDAP_BIND_DN=cn=admin,dc=example,dc=com
+LDAP_BIND_PASSWORD=secret
+
+# Email for password reset
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=noreply@example.com
+SMTP_PASSWORD=secret
+SMTP_FROM=noreply@example.com
+APP_BASE_URL=https://passwd.example.com
+
+# Rate limiting (optional)
+RATE_LIMIT_REQUESTS=3
+RATE_LIMIT_WINDOW=1h
+
+# Token expiry (optional)
+TOKEN_EXPIRY_DURATION=1h
+```
+
+**Go toolchain**: Requires Go 1.25+ (specified in `go.mod`)
+
+**Key dependencies**:
+
+- `github.com/gofiber/fiber/v2` - HTTP server
+- `github.com/netresearch/simple-ldap-go` - LDAP client
+- `github.com/testcontainers/testcontainers-go` - Integration testing
+- `github.com/joho/godotenv` - Environment loading
+
+## Build & Tests
+
+```bash
+# Development
+go run .                      # Start server with hot-reload (via pnpm go:dev)
+go build -v ./...             # Compile all packages
+go test -v ./...              # Run all tests with verbose output
+
+# Specific package testing
+go test ./internal/validators/...    # Test password validators
+go test ./internal/ratelimit/...     # Test rate limiter
+go test ./internal/resettoken/...    # Test token generation
+go test -run TestSpecificFunction    # Run specific test
+
+# Integration tests (uses testcontainers)
+go test -v ./internal/email/...      # Requires Docker for MailHog container
+
+# Coverage
+go test -cover ./...                 # Coverage summary
+go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out
+
+# Build optimized binary
+CGO_ENABLED=0 go build -ldflags="-w -s" -o ldap-passwd
+```
+
+**CI validation** (from `.github/workflows/check.yml`):
+
+```bash
+go mod download
+go build -v ./...
+go test -v ./...
+```
+
+## Code Style
+
+**Go Standards**:
+
+- Use `go fmt` (automatic via Prettier with go-template plugin)
+- Follow [Effective Go](https://go.dev/doc/effective_go)
+- Package-level documentation comments required
+- Exported functions must have doc comments
+
+**Project Conventions**:
+
+- Internal packages only: No public API outside this project
+- Error wrapping with context: `fmt.Errorf("context: %w", err)`
+- Use structured logging (consider adding in future)
+- Prefer explicit over implicit
+- Use interfaces for testability (see `email/service.go`)
+
+**Naming**:
+
+- `internal/package/file.go` - implementation
+- `internal/package/file_test.go` - tests
+- Descriptive variable names (not `x`, `y`, `tmp`)
+- No stuttering: `email.Service`, not `email.EmailService`
+
+**Error Handling**:
+
+```go
+// ✅ Good: wrap with context
+if err != nil {
+    return fmt.Errorf("failed to connect LDAP at %s: %w", config.URL, err)
+}
+
+// ❌ Bad: lose context
+if err != nil {
+    return err
+}
+
+// ❌ Worse: ignore
+conn, _ := ldap.Dial(url)
+```
+
+**Testing**:
+
+- Table-driven tests preferred
+- Use testcontainers for external dependencies (LDAP, SMTP)
+- Test files colocated with code: `validators/validate_test.go`
+- Descriptive test names: `TestPasswordValidation_RequiresMinimumLength`
+
+## Security
+
+**LDAP Security**:
+
+- Always use LDAPS in production (`ldaps://` URLs)
+- Bind credentials in environment, never hardcoded
+- Validate user input before LDAP queries (prevent injection)
+- Use `simple-ldap-go` helpers to avoid raw LDAP filter construction
+
+**Password Security**:
+
+- Never log passwords (plain or hashed)
+- No password storage - passwords go directly to LDAP
+- Passwords only in memory during request lifetime
+- HTTPS required for transport security
+
+**Token Security**:
+
+- Cryptographic random tokens (see `resettoken/token.go`)
+- Configurable expiry (default 1h)
+- Single-use tokens (invalidated after use)
+- No token storage in logs or metrics
+
+**Rate Limiting**:
+
+- IP-based limits: 3 requests/hour default
+- Configurable via `RATE_LIMIT_*` env vars
+- In-memory store (consider Redis for multi-instance)
+- Apply to both change and reset endpoints
+
+**Input Validation**:
+
+- Strict validation on all user inputs (see `validators/`)
+- Reject malformed requests early
+- Validate email format, username format, password policies
+- No HTML/script injection vectors
+
+## PR/Commit Checklist
+
+**Before committing Go code**:
+
+- [ ] Run `go fmt ./...` (or `pnpm prettier --write .`)
+- [ ] Run `go vet ./...` (static analysis)
+- [ ] Run `go test ./...` (all tests pass)
+- [ ] Run `go build` (compilation check)
+- [ ] Update package doc comments if API changed
+- [ ] Add/update tests for new functionality
+- [ ] Check for sensitive data in logs
+- [ ] Verify error messages provide useful context
+
+**Testing requirements**:
+
+- New features must have tests
+- Bug fixes must have regression tests
+- Aim for ≥80% coverage on changed packages
+- Integration tests for external dependencies
+
+**Documentation**:
+
+- Update package doc comments (godoc)
+- Update [docs/api-reference.md](../docs/api-reference.md) for RPC changes
+- Update [docs/development-guide.md](../docs/development-guide.md) for new setup steps
+- Update environment variable examples in `.env` and docs
+
+## Good vs Bad Examples
+
+**✅ Good: Type-safe configuration**
+
+```go
+type Config struct {
+    LDAPURL      string `env:"LDAP_URL" validate:"required,url"`
+    BindDN       string `env:"LDAP_BIND_DN" validate:"required"`
+    BindPassword string `env:"LDAP_BIND_PASSWORD" validate:"required"`
+}
+
+func LoadConfig() (*Config, error) {
+    var cfg Config
+    if err := env.Parse(&cfg); err != nil {
+        return nil, fmt.Errorf("parse config: %w", err)
+    }
+    return &cfg, nil
+}
+```
+
+**❌ Bad: Unsafe configuration**
+
+```go
+func LoadConfig() *Config {
+    return &Config{
+        LDAPURL: os.Getenv("LDAP_URL"),  // ❌ no validation, may be empty
+    }
+}
+```
+
+**✅ Good: Table-driven tests**
+
+```go
+func TestPasswordValidation(t *testing.T) {
+    tests := []struct {
+        name     string
+        password string
+        policy   PasswordPolicy
+        wantErr  bool
+    }{
+        {"valid password", "Test123!", PasswordPolicy{MinLength: 8}, false},
+        {"too short", "Ab1!", PasswordPolicy{MinLength: 8}, true},
+        {"no numbers", "TestTest", PasswordPolicy{RequireNumbers: true}, true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            err := ValidatePassword(tt.password, tt.policy)
+            if (err != nil) != tt.wantErr {
+                t.Errorf("got error %v, wantErr %v", err, tt.wantErr)
+            }
+        })
+    }
+}
+```
+
+**❌ Bad: Non-descriptive tests**
+
+```go
+func TestPassword(t *testing.T) {
+    err := ValidatePassword("test")  // ❌ what policy? what's expected?
+    if err == nil {
+        t.Fail()
+    }
+}
+```
+
+**✅ Good: Interface for testability**
+
+```go
+type EmailService interface {
+    SendResetToken(ctx context.Context, to, token string) error
+}
+
+type SMTPService struct {
+    host string
+    port int
+}
+
+func (s *SMTPService) SendResetToken(ctx context.Context, to, token string) error {
+    // real implementation
+}
+
+// In tests, use mock implementation
+type MockEmailService struct {
+    SendFunc func(ctx context.Context, to, token string) error
+}
+```
+
+**❌ Bad: Hard-to-test concrete dependency**
+
+```go
+func ResetPassword(username string) error {
+    service := NewSMTPService()  // ❌ hardcoded, can't mock
+    return service.SendEmail(...)
+}
+```
+
+## When Stuck
+
+**Go-specific issues**:
+
+1. **Module issues**: `go mod tidy` to clean dependencies
+2. **Import errors**: Check `go.mod` requires correct versions
+3. **Test failures**: `go test -v ./... -run FailingTest` for verbose output
+4. **LDAP connection**: Verify `LDAP_URL` format and network access
+5. **Email testing**: Ensure Docker running for testcontainers (MailHog)
+6. **Rate limit testing**: Tests may fail if system time incorrect
+
+**Debugging**:
+
+```bash
+# Verbose test output
+go test -v ./internal/package/...
+
+# Run specific test
+go test -run TestName ./internal/package/
+
+# Race detector (for concurrency issues)
+go test -race ./...
+
+# Build with debug info
+go build -gcflags="all=-N -l"
+```
+
+**Common pitfalls**:
+
+- **Nil pointer dereference**: Check error returns before using values
+- **Context cancellation**: Always respect `context.Context` in long operations
+- **Resource leaks**: Defer `Close()` calls immediately after acquiring resources
+- **Goroutine leaks**: Ensure all goroutines can exit
+- **Time zones**: Use `time.UTC` for consistency
+
+## Package-Specific Notes
+
+### email/
+
+- Uses testcontainers for integration tests
+- MailHog container spins up automatically in tests
+- Mock `EmailService` interface for unit tests in other packages
+
+### options/
+
+- Configuration loaded from environment via `godotenv`
+- Validation happens at startup (fail-fast)
+- See `.env.local.example` for required variables
+
+### ratelimit/
+
+- In-memory store (map with mutex)
+- Consider Redis for multi-instance deployments
+- Tests use fixed time.Now for deterministic results
+
+### resettoken/
+
+- Crypto/rand for token generation (never math/rand)
+- Base64 URL encoding (safe for URLs)
+- Store tokens server-side with expiry
+
+### rpc/
+
+- JSON-RPC 2.0 specification compliance
+- Error codes defined in [docs/api-reference.md](../docs/api-reference.md)
+- Request validation before processing
+
+### validators/
+
+- Pure functions (no side effects)
+- Configurable policies from environment
+- Clear error messages for user feedback