Skip to content

feat: improve TS/Hono architecture guidance and add Effect CLI profile#145

Merged
soulcodex merged 3 commits into
mainfrom
feat/ts-hono-effect-cli-ports-adapters
May 11, 2026
Merged

feat: improve TS/Hono architecture guidance and add Effect CLI profile#145
soulcodex merged 3 commits into
mainfrom
feat/ts-hono-effect-cli-ports-adapters

Conversation

@soulcodex
Copy link
Copy Markdown
Owner

@soulcodex soulcodex commented May 11, 2026

Why

This PR tightens our TypeScript-first guidance for API and CLI projects so generated AGENTS instructions are more consistent with hexagonal boundaries and domain-driven error handling.

The main gaps addressed were:

  • Hono usage was implicit in profiles but not represented as an explicit framework fragment with concrete controller patterns.
  • Domain logic placement rules were present but not strong enough to prevent business rules from drifting into helpers/adapters.
  • TypeScript CLI guidance lacked an Effect-based profile aligned with ports-and-adapters.
  • Error guidance did not consistently push typed, domain-specific errors and reusable IsXxxError / isXxxError helpers.
  • TypeScript runtime targets were behind the current Node LTS line.

What Changed

1) New framework fragments

  • Added agents/frameworks/hono.md
    • Class-based controllers
    • register(app: Hono)-style semantic route registration
    • Typed/validated params at the boundary
    • Centralized domain-to-HTTP error mapping
    • Middleware DI guidance: external deps are created in composition root and injected as handlers/factories
  • Added agents/frameworks/effect-cli.md
    • @effect/cli + @effect/platform-node command patterns
    • Thin command handlers as adapters
    • Composition-root layer wiring
    • Typed error-to-exit/output mapping

2) Stronger architecture and language rules

  • Updated agents/architecture/hexagonal.md
    • Added explicit rule to keep business rules cohesive and out of scattered utility functions
  • Updated agents/languages/typescript.md
    • Prefer domain/application custom errors over generic Error for business failures
    • Add/reuse isXxxError helpers for branching
    • Explicit DI rule for middleware with infra dependencies (Redis/SDK/config)
  • Updated agents/languages/go.md
    • Prefer custom domain errors for business failures
    • Add/reuse IsXxxError(err) helpers to centralize errors.Is/errors.As logic

3) New TypeScript Effect CLI profile

  • Added profiles/typescript-hexagonal-effect-cli.yaml
    • @effect/cli + @effect/platform-node
    • Hexagonal + DDD composition
    • pnpm + Node 24+

4) Hono explicitly declared in TS hexagonal backend profiles

  • Updated TypeScript hexagonal backend/fullstack profiles to include framework: hono where backend fragments are declared.

5) Node runtime alignment (TypeScript profiles)

  • Updated TypeScript profile runtime metadata from Node 22+ / Node.js 20+ to Node 24+ (current LTS line).

6) Essential docs/index updates

  • Updated docs/profiles.md to include the new TypeScript Effect CLI profile
  • Regenerated index/fragments.json

Scope Notes

  • No README.md changes (intentionally, per request).
  • This PR updates configuration guidance and profile metadata only; no runtime application code is changed.

Validation

  • just lint
  • just index

Reviewer Checklist

  • Confirm new fragments are self-contained and follow heading/size rules
  • Confirm new profile validates against profile schema
  • Confirm TS profile runtime updates are consistent across all TypeScript profiles
  • Confirm docs/profiles.md and index/fragments.json reflect the new profile/fragments

Follow-up (Optional)

  • Align Node runtime strings in mixed Go + frontend profiles to Node 24+ for full cross-profile consistency.

@soulcodex soulcodex merged commit 8108e27 into main May 11, 2026
8 checks passed
@soulcodex soulcodex deleted the feat/ts-hono-effect-cli-ports-adapters branch May 11, 2026 21:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant