@punks/cli 0.1.16 → 1.0.0

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

@@ -0,0 +1,257 @@
+# Effect-Atom Patterns Checklist
+
+Effect-Atom (`@effect-atom/atom-react`) is the standard way to handle data fetching, mutations, and server state in React components in this codebase. If new UI code is NOT using Effect-Atom, recommend adopting it.
+
+## Package & Imports
+
+```typescript
+import { Atom, AtomHttpApi, Result, Registry, RegistryContext } from "@effect-atom/atom-react"
+import { AtomRpc } from "@effect-atom/atom-react"
+import { useAtom, useAtomValue, useAtomSet, useAtomRefresh } from "@effect-atom/atom-react"
+```
+
+## 1. Use Typesafe Clients (AtomHttpApi or AtomRpc)
+
+API calls to **our own Effect HttpApi or Effect RPC backends** should go through a **typesafe client** — `AtomHttpApi.Tag` for Effect HttpApi backends or `AtomRpc.Tag` for Effect RPC backends. This gives end-to-end type safety from the server schema to the client. Raw `fetch`/`axios` is acceptable for third-party/external APIs or non-Effect backends.
+
+### HTTP API Client (AtomHttpApi)
+
+For REST-style APIs defined with `HttpApi` from `@effect/platform`:
+
+```typescript
+// Define a typesafe client bound to your API schema
+export class ApiClient extends AtomHttpApi.Tag<ApiClient>()(
+  "@myorg/web/ApiClient",
+  {
+    api: MyApi,              // Your HttpApi definition (provides full type safety)
+    httpClient: AuthClient,  // Pre-configured HTTP client with auth
+    baseUrl: API_BASE,
+  }
+) {}
+
+// Queries and mutations are fully typed from the API schema
+export const usersAtom = ApiClient.query("users", "listUsers", { ... })
+export const createUserMutation = ApiClient.mutation("users", "createUser")
+```
+
+### RPC Client (AtomRpc)
+
+For Effect RPC services — provides end-to-end type safety from server to client:
+
+```typescript
+export class UsersClient extends AtomRpc.Tag<UsersClient>()(
+  "@myorg/web/UsersClient",
+  {
+    group: UsersRpcGroup,
+    protocol: makeProtocolLayer("/rpc/users"),
+  }
+) {}
+```
+
+### What to Flag
+
+Only flag raw fetch/axios when targeting **our own Effect HttpApi or Effect RPC backends** where a typesafe client can derive types from the server schema. Calls to external APIs or non-Effect backends are fine.
+
+```typescript
+// BAD — raw fetch to our own API, no type safety
+const res = await fetch("/api/users", { method: "POST", body: JSON.stringify(data) })
+const users = await res.json() // `any` type, no validation
+
+// FINE — external third-party API, we don't control it
+const res = await fetch("https://api.stripe.com/v1/customers", { ... })
+
+// GOOD — typesafe client for our own API
+export const usersAtom = ApiClient.query("users", "listUsers", { timeToLive: "5 minutes" })
+export const createUserMutation = ApiClient.mutation("users", "createUser")
+```
+
+## 2. Query Atoms for Data Fetching
+
+Data fetching should use `AtomHttpApi.query()` or an RPC client, NOT `useState` + `useEffect` + `fetch`, and NOT React Query/SWR.
+
+```typescript
+// GOOD — query atom with TTL
+export const usersAtom = ApiClient.query("users", "listUsers", {
+  timeToLive: "5 minutes",
+})
+
+// Parameterized query — function returning atom
+export const userAtom = (userId: UserId) =>
+  ApiClient.query("users", "getUser", {
+    urlParams: { user_id: userId },
+    timeToLive: "3 minutes",
+  })
+
+// BAD — manual fetch with useState/useEffect
+const [users, setUsers] = useState([])
+const [loading, setLoading] = useState(true)
+useEffect(() => {
+  fetch("/api/users").then(res => res.json()).then(setUsers).finally(() => setLoading(false))
+}, [])
+```
+
+## 3. Mutation Atoms for Write Operations
+
+Mutations should use `AtomHttpApi.mutation()`.
+
+```typescript
+// GOOD
+export const createUserMutation = ApiClient.mutation("users", "createUser")
+export const deleteUserMutation = ApiClient.mutation("users", "deleteUser")
+
+// BAD — manual fetch POST
+const handleCreate = async () => {
+  const res = await fetch("/api/users", { method: "POST", body: JSON.stringify(data) })
+}
+```
+
+## 4. Consuming Queries — useAtomValue + Result.builder
+
+Read query results with `useAtomValue`. Render states with `Result.builder()`.
+
+```typescript
+// GOOD
+function UsersList() {
+  const result = useAtomValue(usersAtom)
+
+  return Result.builder(result)
+    .onInitialOrWaiting(() => <Loading />)
+    .onFailure((error) => <ErrorDisplay message={String(error)} />)
+    .onSuccess((response) => (
+      <ul>{response.data.map(u => <li key={u.id}>{u.name}</li>)}</ul>
+    ))
+    .render()
+}
+
+// BAD — manual state matching
+function UsersList() {
+  const result = useAtomValue(usersAtom)
+  if (result.waiting) return <Loading />
+  if (Result.isFailure(result)) return <Error />
+  return <ul>...</ul>
+}
+```
+
+## 5. Consuming Mutations — useAtom with Promise Mode
+
+Use `useAtom(mutation, { mode: "promise" })` for mutations. Derive loading from `result.waiting`, NOT `useState`.
+
+```typescript
+// GOOD
+const [result, mutate] = useAtom(createUserMutation, { mode: "promise" })
+const isLoading = result.waiting
+
+const handleSubmit = async () => {
+  try {
+    await mutate({ payload: formData })
+    onSuccess?.()
+  } catch (err) {
+    showError(err)
+  }
+}
+
+<Button disabled={isLoading}>
+  {isLoading ? "Creating..." : "Create"}
+</Button>
+
+// BAD — useState for loading
+const [isLoading, setIsLoading] = useState(false)
+const handleSubmit = async () => {
+  setIsLoading(true)
+  try { await mutate({ payload }) } finally { setIsLoading(false) }
+}
+```
+
+## 6. useAtomSet for Fire-and-Forget Mutations
+
+When you only need the mutate function without tracking result state:
+
+```typescript
+// GOOD — multiple mutations, no state tracking needed
+const setCreate = useAtomSet(createMutation, { mode: "promise" })
+const setUpdate = useAtomSet(updateMutation, { mode: "promise" })
+```
+
+## 7. Cache Invalidation — useAtomRefresh
+
+Invalidate query caches after mutations with `useAtomRefresh`. NOT manual refetch logic.
+
+```typescript
+// GOOD
+const refreshUsers = useAtomRefresh(usersAtom)
+
+const handleCreate = async () => {
+  await mutate({ payload })
+  refreshUsers() // Invalidate and refetch
+}
+
+// BAD — manual refetch state
+const [refetchKey, setRefetchKey] = useState(0)
+const handleCreate = async () => {
+  await createUser(data)
+  setRefetchKey(k => k + 1) // Force re-render
+}
+```
+
+## 8. Derived/Computed Atoms — Atom.make
+
+Combine multiple atoms into derived state with `Atom.make()`:
+
+```typescript
+// GOOD
+export const dashboardAtom = (appId: ApplicationId) => {
+  const usersAtom = chartDataAtom(appId, { metric: "users" })
+  const revenueAtom = chartDataAtom(appId, { metric: "revenue" })
+
+  return Atom.make((get) => {
+    const combined = Result.all({
+      users: get(usersAtom),
+      revenue: get(revenueAtom),
+    })
+    return Result.map(combined, ({ users, revenue }) => ({
+      totalUsers: users.total,
+      totalRevenue: revenue.total,
+    }))
+  })
+}
+```
+
+## 9. Dialog Pattern
+
+Dialogs own their mutation hooks internally. Parent passes data props and `onOpenChange`/`onSuccess` callbacks.
+
+```typescript
+// GOOD — dialog owns mutation
+function CreateUserDialog({ open, onOpenChange, organizationId }: Props) {
+  const [result, mutate] = useAtom(createUserMutation, { mode: "promise" })
+  const isLoading = result.waiting
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <form onSubmit={() => mutate({ payload: { organizationId, ...formData } })}>
+        <Button disabled={isLoading}>{isLoading ? "Creating..." : "Create"}</Button>
+      </form>
+    </Dialog>
+  )
+}
+
+// BAD — parent passes mutation handler
+function CreateUserDialog({ open, onOpenChange, onSubmit, isLoading }: Props) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <form onSubmit={onSubmit}>
+        <Button disabled={isLoading}>Create</Button>
+      </form>
+    </Dialog>
+  )
+}
+```
+
+## What to Flag
+
+- **Critical**: Raw `fetch`/`axios` calls to **our own Effect HttpApi/RPC backends** without a typesafe client (should use `AtomHttpApi` or `AtomRpc`). External APIs or non-Effect backends are fine.
+- **Critical**: `useState` + `useEffect` + `fetch` for data fetching (should use Effect-Atom query atoms)
+- **Critical**: `useState` for loading state when an atom mutation is available (`result.waiting`)
+- **Warning**: Manual if/else for result states instead of `Result.builder()`
+- **Warning**: Missing `useAtomRefresh` after mutations that affect visible queries
+- **Info**: Recommend Effect-Atom if component uses React Query, SWR, or manual fetch patterns

package/dist/skills/frameworks/effect/effect-authoring/references/effect-primitives.md

@@ -0,0 +1,144 @@
+# Effect Primitives Checklist
+
+## 1. Effect Array/HashMap Over Native
+
+Use `Array` from `effect` for functional array operations in Effect code. Use `HashMap` for key-value lookups instead of plain objects or `Map`.
+
+```typescript
+// GOOD
+import { Array, HashMap } from "effect"
+const ids = Array.map(items, (item) => item.id)
+const lookup = HashMap.fromIterable(items.map((i) => [i.id, i]))
+
+// BAD
+const ids = items.map((item) => item.id) // native .map in Effect service code
+```
+
+## 2. Effect.forEach Over For Loops
+
+Any loop body that performs an Effect must use `Effect.forEach`. Supports `concurrency` option for parallel execution.
+
+```typescript
+// GOOD
+yield* Effect.forEach(users, (user) => sendNotification(user), { concurrency: 5 })
+
+// BAD
+for (const user of users) {
+  yield* sendNotification(user)
+}
+```
+
+## 3. Match Over Switch Statements
+
+All `switch` statements on discriminated unions or string literals should use `Match.value()` or `Match.type<T>()` with `Match.exhaustive`.
+
+```typescript
+// GOOD
+import { Match } from "effect"
+const result = Match.value(platform).pipe(
+  Match.when("IOS", () => "ios" as const),
+  Match.when("ANDROID", () => "android" as const),
+  Match.exhaustive
+)
+
+// BAD
+switch (platform) {
+  case "IOS": return "ios"
+  case "ANDROID": return "android"
+}
+```
+
+## 4. Option Over Optional Chaining
+
+In Effect services and domain types, prefer `Option<T>` over `T | null | undefined`. Use `Option.match`, `Option.map`, `Option.getOrElse` instead of `?.` chains.
+
+```typescript
+// GOOD
+import { Option } from "effect"
+const name = Option.match(user.displayName, {
+  onNone: () => "Anonymous",
+  onSome: (name) => name
+})
+
+// BAD
+const name = user?.displayName ?? "Anonymous" // in Effect service code
+```
+
+Note: `?.` is acceptable in React components and non-Effect utility code. Flag it only in Effect services/repositories/handlers.
+
+## 5. Effect Schema Over Zod/Manual Validation
+
+All runtime validation should use `Schema` from `effect`. No Zod imports. No manual `typeof`/`instanceof` guards for data parsing.
+
+```typescript
+// GOOD
+import { Schema } from "effect"
+const UserInput = Schema.Struct({
+  name: Schema.String,
+  email: Schema.String.pipe(Schema.pattern(/@/)),
+})
+
+// BAD
+import { z } from "zod"
+const UserInput = z.object({ name: z.string() })
+```
+
+## 6. Layer.provide Not Effect.provide
+
+Dependencies should be composed via `Layer` in service definitions and layer files, not via `Effect.provide` at call sites. Exception: final runner/test boundaries and infrastructure bindings in entry points.
+
+Keep requirements visible. If a function needs a repository, client, flag service, clock, config, or runtime binding, that need should appear as an Effect environment requirement or an `Effect.Service` dependency until a layer provides it.
+
+```typescript
+// GOOD
+export class MyService extends Effect.Service<MyService>()("MyService", {
+  dependencies: [DepA.Default, DepB.Default],
+  effect: Effect.gen(function* () { ... })
+}) {}
+
+// Also GOOD (Layer.provide chain)
+const MainLayer = ServiceA.Default.pipe(
+  Layer.provideMerge(ServiceB.Default),
+  Layer.provide(Database)
+)
+
+// BAD (providing at call site)
+const result = yield* myEffect.pipe(Effect.provide(someLayer))
+```
+
+## 7. No try/catch
+
+Everything uses Effect error channel. No `try { } catch { }` blocks in Effect code.
+
+```typescript
+// GOOD
+yield* Effect.tryPromise({
+  try: () => fetch(url),
+  catch: (e) => new FetchError({ cause: e })
+})
+
+// BAD
+try {
+  const res = await fetch(url)
+} catch (e) {
+  throw new Error("fetch failed")
+}
+```
+
+## 8. No Promise-Based Code
+
+Service methods return `Effect`, not `Promise`. No `async/await` in Effect service implementations.
+
+```typescript
+// GOOD
+const fetchUser = Effect.fn("fetchUser")(function* (id: UserId) {
+  const user = yield* userRepo.findById(id)
+  return user
+})
+
+// BAD
+const fetchUser = async (id: string) => {
+  const user = await userRepo.findById(id)
+  return user
+}
+```

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

@@ -0,0 +1,156 @@
+# Error Patterns Checklist
+
+## 1. Schema.TaggedError With HTTP Annotations
+
+All errors reaching HTTP boundaries must use `Schema.TaggedError` with `HttpApiSchema.annotations`.
+
+```typescript
+// GOOD
+export class ResourceNotFound extends Schema.TaggedError<ResourceNotFound>()(
+  "@myorg/api/errors/ResourceNotFound",
+  {
+    type: Schema.optionalWith(ErrorType, { default: () => "invalid_request_error" as const }),
+    code: Schema.optionalWith(ErrorCode, { default: () => "resource_missing" as const }),
+    message: Schema.optionalWith(Schema.String, {
+      default: () => "The requested resource was not found.",
+    }),
+    param: Schema.String.pipe(Schema.optional),
+    resource_type: Schema.String.pipe(Schema.optional),
+    resource_id: Schema.String.pipe(Schema.optional),
+  },
+  HttpApiSchema.annotations({ status: 404, title: "Resource Not Found" })
+) {}
+
+// BAD
+class NotFoundError extends Error {
+  constructor(message: string) { super(message) }
+}
+```
+
+## 2. Reverse Domain Notation for Tags
+
+Error tags should use reverse domain notation matching the package structure.
+
+```typescript
+// GOOD
+"@myorg/api/errors/ResourceNotFound"
+"@myorg/subscriptions/errors/CheckoutInitiation"
+
+// BAD
+"ResourceNotFound"
+"NotFoundError"
+```
+
+## 3. Static Factory Methods
+
+Errors should have convenience constructors for common cases.
+
+```typescript
+// GOOD
+export class ResourceNotFound extends Schema.TaggedError<ResourceNotFound>()(...) {
+  static fromId(resourceType: string, id: string) {
+    return new ResourceNotFound({
+      message: `No such ${resourceType}: '${id}'`,
+      param: "id",
+      resource_type: resourceType,
+      resource_id: id,
+    })
+  }
+}
+
+export class BadRequestError extends Schema.TaggedError<BadRequestError>()(...) {
+  static invalidParam(param: string, message: string) {
+    return new BadRequestError({ code: "parameter_invalid", message, param })
+  }
+  static missingParam(param: string) {
+    return new BadRequestError({
+      code: "parameter_missing",
+      message: `Missing required parameter: ${param}`,
+      param,
+    })
+  }
+}
+```
+
+## 4. Rich Context Fields
+
+Errors must include enough context for debugging. Never lose valuable information.
+
+```typescript
+// GOOD - preserves context
+new PaymentProcessingError({
+  message: `Failed to process payment for subscription ${subscriptionId}`,
+  subscriptionId,
+  provider,
+  cause: originalError,
+})
+
+// BAD - loses info
+new PaymentProcessingError({ message: "Payment failed" })
+new Error("something went wrong")
+```
+
+## 5. catchTag/catchTags Only
+
+Never use `catchAll` or `mapError`. Always handle specific error tags.
+
+```typescript
+// GOOD
+yield* effect.pipe(
+  Effect.catchTag("DatabaseError", (e) =>
+    Effect.fail(ResourceNotFound.fromId("paywall", String(id)))
+  ),
+  Effect.catchTag("ValidationError", (e) =>
+    Effect.fail(BadRequestError.invalidParam("input", e.message))
+  )
+)
+
+// BAD
+yield* effect.pipe(
+  Effect.catchAll((e) => Effect.fail(new InternalError({ message: String(e) })))
+)
+yield* effect.pipe(
+  Effect.mapError((e) => new InternalError({ message: "failed" }))
+)
+```
+
+## 6. Explicit Error Types
+
+Error types should be specific to the domain, not generic. The error channel should tell you exactly what went wrong.
+
+```typescript
+// GOOD
+Effect<Paywall, PaywallNotFoundError | PaywallArchived | Unauthorized>
+
+// BAD
+Effect<Paywall, Error>
+Effect<Paywall, unknown>
+```
+
+## 7. Don't Catch HTTP-Annotated Errors
+
+Let errors with `HttpApiSchema.annotations` propagate to the HTTP layer for automatic status code mapping. Don't re-wrap them.
+
+```typescript
+// GOOD - let ResourceNotFound propagate
+yield* paywallRepo.findById(id)
+
+// BAD - catching and re-wrapping
+yield* paywallRepo.findById(id).pipe(
+  Effect.catchTag("ResourceNotFound", () =>
+    Effect.fail(new GenericError({ message: "not found" }))
+  )
+)
+```
+
+## 8. Fire-and-Forget for Non-Critical Operations
+
+For operations that shouldn't fail the request, use `Effect.tapError` + `Effect.ignore`:
+
+```typescript
+// GOOD
+yield* db.execute(...).pipe(
+  Effect.tapError((e) => Effect.logWarning("Failed to update", { error: e })),
+  Effect.ignore
+)
+```

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

@@ -0,0 +1,113 @@
+# OTEL / Observability Patterns Checklist
+
+## 1. Effect.fn With Trace Names
+
+`Effect.fn` replaces the pattern where an arrow function wraps `Effect.gen`. It does NOT apply to bare `Effect.gen` calls without a wrapping function. It also does NOT apply in `.test.ts` files.
+
+```typescript
+// BAD — arrow function wrapping Effect.gen, should use Effect.fn
+const findById = (productId: ProductId) => Effect.gen(function* () {
+  // no trace name, anonymous span
+})
+
+// GOOD — Effect.fn replaces the arrow function wrapper
+const findById = Effect.fn("ProductRepository.findById")(function* (
+  productId: ProductId,
+  organizationId: OrganizationId
+) {
+  yield* Effect.annotateCurrentSpan("productId", productId)
+  // ...
+})
+
+// FINE — bare Effect.gen without wrapping function, no Effect.fn needed
+yield* Effect.gen(function* () {
+  const user = yield* UserService
+  // inline composition, not a named function
+})
+```
+
+### Naming Convention
+
+Follow `ServiceName.methodName` format consistently:
+- `UserService.findById`
+- `PaywallRepository.create`
+- `CampaignService.createTrigger`
+- `OrgResolver.resolveProjectAccess`
+
+## 2. annotateCurrentSpan With Essential Data
+
+Annotate spans with entity IDs and key business values. Don't over-annotate with internal state or step-by-step progress.
+
+```typescript
+// GOOD - essential IDs and context
+yield* Effect.annotateCurrentSpan("applicationId", applicationId)
+yield* Effect.annotateCurrentSpan("paywallId", paywallId)
+yield* Effect.annotateCurrentSpan("action", "create")
+
+// BAD - over-annotating
+yield* Effect.annotateCurrentSpan("step", "1")
+yield* Effect.annotateCurrentSpan("loopIndex", i)
+yield* Effect.annotateCurrentSpan("intermediateResult", JSON.stringify(result))
+
+// BAD - sensitive data
+yield* Effect.annotateCurrentSpan("apiKey", apiKey)
+yield* Effect.annotateCurrentSpan("userEmail", email)
+```
+
+### What to Annotate
+
+- Entity IDs (applicationId, paywallId, userId, etc.)
+- Action being performed (create, update, delete)
+- Key discriminators (platform, provider, scope)
+- Counts (itemCount, resultCount) when relevant
+
+### What NOT to Annotate
+
+- PII (emails, names, addresses)
+- Secrets (API keys, tokens)
+- Large payloads (full request/response bodies)
+- Step-by-step progress counters
+
+## 3. Structured Logging
+
+Use `Effect.log` / `Effect.logInfo` / `Effect.logWarning` / `Effect.logError` with structured data. Never use `console.log`.
+
+```typescript
+// GOOD
+yield* Effect.logInfo("Processing payment").pipe(
+  Effect.annotateLogs({ orderId, amount, provider })
+)
+
+// BAD
+console.log(`Processing payment for order ${orderId}`)
+console.log("Payment result:", result)
+```
+
+## 4. Error Spans
+
+Errors should carry enough context for debugging without needing to look at other spans. Include entity IDs and operation context in error construction.
+
+```typescript
+// GOOD
+new ResourceNotFound({
+  message: `No such paywall: '${paywallId}'`,
+  resource_type: "paywall",
+  resource_id: String(paywallId),
+})
+
+// BAD
+new ResourceNotFound({ message: "Not found" })
+```
+
+## 5. Effect.withSpan for Non-fn Contexts
+
+When `Effect.fn` isn't appropriate (inline pipelines, one-off compositions), use `Effect.withSpan`:
+
+```typescript
+// GOOD
+const result = yield* someEffect.pipe(
+  Effect.withSpan("OrgResolver.fromProject", {
+    attributes: { projectId, scope }
+  })
+)
+```