@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/effect/effect-authoring/references/test-patterns.md

@@ -0,0 +1,146 @@
+# Test Patterns Checklist
+
+## 1. Use @effect/vitest
+
+Always import from `@effect/vitest`, never plain `vitest`. It re-exports all standard vitest functions.
+
+```typescript
+// GOOD
+import { it, describe, expect } from "@effect/vitest"
+
+// BAD
+import { it, describe, expect } from "vitest"
+```
+
+## 2. it.layer() for Test Setup
+
+Use `it.layer(TestLayer)((it) => { ... })` for providing test dependencies. Never use `beforeAll`/`afterAll` for Effect service setup.
+
+```typescript
+// GOOD
+const TestLayer = Layer.mergeAll(DatabaseTest, ServiceTest)
+
+it.layer(TestLayer)((it) => {
+  describe("findById", () => {
+    it.scoped("returns project when found", () =>
+      Effect.gen(function* () {
+        const service = yield* MyService
+        // ...
+      })
+    )
+  })
+})
+
+// BAD
+let service: MyService
+beforeAll(async () => {
+  service = await setupService()
+})
+afterAll(async () => {
+  await teardown()
+})
+```
+
+## 3. it.scoped for Individual Tests
+
+Inside an `it.layer()` block, use `it.scoped` for tests that need automatic resource cleanup.
+
+```typescript
+// GOOD
+it.scoped("creates and cleans up", () =>
+  Effect.gen(function* () {
+    const org = yield* createTestOrganization()
+    // org cleanup happens automatically via scope
+  })
+)
+```
+
+## 4. Effect.either for Error Testing
+
+Use `Effect.either` + `Either.isLeft()` to test error cases. Never use try/catch or `.catch()`.
+
+```typescript
+// GOOD
+it.scoped("fails for invalid id", () =>
+  Effect.gen(function* () {
+    const result = yield* service.findById(invalidId).pipe(Effect.either)
+    expect(Either.isLeft(result)).toBe(true)
+    if (Either.isLeft(result)) {
+      expect(result.left._tag).toBe("ResourceNotFound")
+    }
+  })
+)
+
+// BAD
+it("fails for invalid id", async () => {
+  try {
+    await service.findById(invalidId)
+    fail("should have thrown")
+  } catch (e) {
+    expect(e).toBeInstanceOf(NotFoundError)
+  }
+})
+```
+
+## 5. Factory Functions for Test Data
+
+Use factory functions from `test/testFactories.ts` or local helpers. Don't inline large object literals.
+
+```typescript
+// GOOD
+const org = yield* createTestOrganization()
+const app = yield* createTestApplication(org.id)
+const paywall = yield* createTestPaywall(app.id)
+
+// BAD
+const org = { id: 1, name: "test", createdAt: new Date(), ... }
+```
+
+## 6. it.scoped.each for Parameterized Tests
+
+Use `.each` for testing multiple cases with the same logic.
+
+```typescript
+// GOOD
+it.scoped.each([
+  { platform: "ios", expected: "IOS" },
+  { platform: "android", expected: "ANDROID" },
+])("maps $platform correctly", ({ platform, expected }) =>
+  Effect.gen(function* () {
+    const result = yield* mapPlatform(platform)
+    expect(result).toBe(expected)
+  })
+)
+```
+
+## 7. Test Layer Composition
+
+Use `DefaultWithoutDependencies` or `.Default.pipe(Layer.provide(...))` for test layers. Replace dependencies by providing alternate layers, not by mocking imports.
+
+```typescript
+// GOOD
+const TestLayer = MyService.Default.pipe(
+  Layer.provide(MockRepository.Test),
+  Layer.provide(DatabaseTest)
+)
+
+// Also GOOD
+const TestLayer = Layer.mergeAll(
+  MyService.Default,
+  MockRepository.Test
+).pipe(Layer.provide(DatabaseTest))
+```
+
+```typescript
+// BAD
+vi.mock("../repositories/user", () => ({ findById: vi.fn() }))
+```
+
+## 8. Coverage Assessment
+
+When reviewing, check:
+- New service methods have corresponding test cases
+- Error paths are tested (not just happy path)
+- Edge cases are covered (empty arrays, null values, boundary conditions)
+- New error types are tested with `Effect.either` pattern
+- Both success and failure scenarios for each public method

package/dist/skills/frameworks/effect/effect-backend-structure/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: effect-backend-structure
+description: |
+  Apply Effect-specific backend structure on top of backend-domain-structure.
+  Use when creating or changing Effect services, layers, actions, repositories,
+  transport adapters, DB integrations, test layers, or backend boilerplate in any
+  Effect backend root. Enforces visible Effect requirements, layer-provided
+  implementations, effect-solutions plus opensrc source lookup, and @effect/vitest
+  testing conventions.
+---
+
+# Effect Backend Structure
+
+Use this skill with `$backend-domain-structure` for Effect backend code.
+
+The agnostic skill owns the layer model:
+
+- `platform/`
+- `integrations/`
+- `features/*`
+- shared libraries and packages
+
+This skill adds Effect-specific services, layers, dependency visibility, source lookup, and testing rules.
+
+## Workflow
+
+1. Identify the backend root from the current repo; do not assume a monorepo path.
+2. Read the nearest relevant `AGENTS.md` files.
+3. Read `$backend-domain-structure` and `references/layout.md`.
+4. Run the relevant `effect-solutions` guides before coding.
+5. Check local `opensrc` Effect sources when docs are vague or an API surface is unfamiliar.
+6. Place code using the agnostic backend layers plus the Effect rules below.
+7. Keep transport thin and run business logic through Effects.
+8. Add or update colocated `@effect/vitest` tests with test layers for unit coverage and live layers for integration coverage.
+
+## Required Source Lookup
+
+Always consult `effect-solutions` first. Use the smallest relevant set:
+
+- `effect-solutions show services-and-layers`
+- `effect-solutions show config`
+- `effect-solutions show data-modeling`
+- `effect-solutions show error-handling`
+- `effect-solutions show testing`
+
+Use `opensrc` next when the guide is not enough:
+
+- `opensrc/repos/github.com/Effect-TS/effect/packages/effect`
+- `opensrc/repos/github.com/Effect-TS/effect/packages/sql`
+- `opensrc/repos/github.com/Effect-TS/effect/packages/sql-drizzle`
+
+For non-Effect libraries, run `opensrc path <package>` or `opensrc path owner/repo`.
+
+## Services and Layers
+
+- Use `Effect.Service` for business services, repositories, and reusable capability interfaces.
+- Use `Context.Tag` only for externally supplied runtime handles or third-party tags.
+- Declare construction dependencies in `dependencies: [Dep.Default]`.
+- Let actions consume services/repositories through Effect accessors or `yield* Service`.
+- Keep action requirements visible until a feature, app, runner, or test layer provides them.
+- Compose feature dependencies in `features/<domain>/layer.ts` or the local equivalent.
+- Compose cross-feature and infrastructure dependencies in `platform/`.
+- Use `Layer.mergeAll` for same-level composition and shallow `Layer.provide` / `Layer.provideMerge` for wiring levels together.
+- Avoid `Effect.provide` inside actions, services, repositories, and transport adapters except at the final runner/test boundary.
+
+## Effect Coding Rules
+
+- Use `Effect.fn("Domain.action")` for actions and service methods.
+- Use `Schema.TaggedError` for domain failures.
+- Use branded IDs and Effect Schema for domain models.
+- Use `Config.*` instead of reading `process.env` inside Effect code.
+- Prefer `catchTag` / `catchTags`, not `catchAll`.
+- Avoid `any`.
+
+## Testing Rules
+
+- Keep tests inside the owning feature or module.
+- Use `@effect/vitest`.
+- Unit tests provide fake leaf services/repos via test layers.
+- Integration tests use live layers and public action or transport boundaries.
+- Expose assertions through test-state tags in `tests/support`.
+- Do not add test-only methods to production services.
+- Do not use module mocks for Effect services; provide a replacement `Layer`.
+
+## Output Checklist
+
+- `$backend-domain-structure` was applied
+- relevant `effect-solutions` guides were checked
+- `opensrc` sources were checked when needed
+- dependencies stay visible as Effect requirements or service dependencies
+- implementations are supplied by layers, not hidden imports or module mocks
+- code landed in the correct backend layer
+- actions own orchestration
+- services are only reusable mechanics
+- transport is thin
+- tests follow the unit/integration split with feature-local support layers

package/dist/skills/frameworks/effect/effect-backend-structure/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Effect Backend Structure"
+  short_description: "Effect backend architecture"
+  default_prompt: "Use $backend-domain-structure alongside $effect-backend-structure to shape or bootstrap Effect backend code in any backend root; first apply agnostic backend layers, then apply Effect-specific services, layers, and testing rules."

package/dist/skills/frameworks/effect/effect-backend-structure/references/layout.md

@@ -0,0 +1,68 @@
+# Effect Backend Layout Addendum
+
+Use `$backend-domain-structure` for the shared backend layout.
+
+Inside the current Effect backend root, prefer:
+
+```text
+<backend-root>/src/
+  platform/
+    effect/
+      app.ts
+      request.ts
+    <transport>/
+      context.ts
+      run.ts
+      router.ts
+  integrations/
+    <provider>/
+      client.ts
+  features/
+    <domain>/
+      actions/
+      models/
+      repositories/
+      services/
+      errors.ts
+      layer.ts
+      router.ts
+```
+
+Dependency direction:
+
+- `platform -> features -> integrations`
+- features may depend on other features only when the domain relationship is explicit and stable
+- integrations do not import features
+
+Layer ownership:
+
+- `platform/effect/app.ts` or local equivalent composes the app-wide live layer and provides infrastructure once
+- `platform/effect/request.ts` or local equivalent builds request-scoped services and runtime context only
+- `features/<domain>/layer.ts` composes that domain's action/repository/service requirements
+- `features/<domain>/tests/support/layer.ts` provides fake leaf layers and test-state tags for unit tests
+
+Keep dependency requirements visible until one of these layer files provides them. Do not import live implementations directly inside actions, services, repositories, or transport adapters.
+
+Test layout:
+
+```text
+<backend-root>/src/features/<domain>/
+  tests/
+    support/
+      layer.ts
+    unit/
+      *.test.ts
+    integration/
+      *.test.ts
+```
+
+Testing split:
+
+- `tests/support`
+  fake leaf layers plus state tags for assertions
+- `tests/unit`
+  action and guard behavior on fake layers
+- `tests/integration`
+  live router/app behavior on real layers
+
+Do not recreate a package-root `tests/` folder unless the current repo already requires that convention.