@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/effect/effect-recoverable-actions/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: effect-recoverable-actions
+description: |
+  Apply Effect-specific recoverability guidance on top of backend-recoverable-actions.
+  Use when an Effect backend flow chains dependent operations, especially DB writes
+  plus external calls, and needs transaction, retry, rollback, compensation, or
+  failure-path testing strategy. Do not use for simple single-step reads or writes.
+---
+
+# Effect Recoverable Actions
+
+Use this skill with `$backend-recoverable-actions`, `$effect-backend-structure`, and `$effect-best-practices`.
+
+The agnostic skill owns the recovery model:
+
+- step classification
+- transaction boundaries
+- retry scope
+- compensation and durable repair
+- failure-path testing
+
+This skill adds the Effect-specific primitives and testing expectations.
+
+## 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-recoverable-actions` plus its strategy and test matrices.
+4. Run `effect-solutions show error-handling` and `effect-solutions show testing`.
+5. Check local `opensrc` source when transaction, retry, accumulation, or control-flow behavior matters.
+6. Enumerate the action steps in order.
+7. Choose the failure strategy before writing code.
+8. Add failure-path `@effect/vitest` tests before considering the action complete.
+
+## Effect Hard Rules
+
+- DB-only multi-write groups should use `SqlClient.withTransaction(...)`.
+- Standardize on action-level transaction wrapping. Do not invent custom transaction plumbing in feature code.
+- Treat nested transaction/savepoint behavior as background knowledge, not the default authoring model.
+- Cross-system flows cannot pretend DB rollback will undo auth providers, email, queues, or other external writes.
+- Retries must be explicit and step-local through `retry` or `retryOrElse`.
+- Prefer `catchTag` / `catchTags` for selective recovery.
+- Prefer `when`, `unless`, `match`, and `matchEffect` when the control-flow choice carries recovery meaning.
+- Use `partition`, `validateAll`, or `Effect.all(..., { mode: ... })` only for preflight, batch validation, or deliberately parallel collection phases.
+- Use typed yieldable errors with `Schema.TaggedError` for recoverable failures.
+- `acquireUseRelease` and `ensuring` are cleanup/finalization primitives, not substitutes for business rollback.
+- Do not teach `Effect.withExecutionPlan` as default recoverability guidance while it is experimental.
+
+## References
+
+- `references/source-backed-primitives.md` for exact Effect surfaces
+- `references/strategy-matrix.md` for Effect-specific strategy examples
+- `references/test-matrix.md` for Effect-specific test expectations
+- `references/flow-examples.md` for generic Effect flow examples
+
+## Output Checklist
+
+- `$backend-recoverable-actions` was applied
+- each step boundary has an explicit strategy
+- DB-only multi-write groups use one transaction boundary
+- cross-system steps have a compensation or durable repair story
+- retries are narrow, explicit, and only for transient idempotent steps
+- expected recoverable failures stay typed
+- failure-path tests cover the chosen recovery model
+- no silent partial-write risk remains undocumented

package/dist/skills/frameworks/effect/effect-recoverable-actions/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Effect Recoverable Actions"
+  short_description: "Recoverable multi-step Effect action flows"
+  default_prompt: "Use $backend-recoverable-actions alongside $effect-recoverable-actions for Effect backend flows that chain multiple dependent operations and need explicit transaction, retry, rollback, compensation, or failure-path testing strategy."

package/dist/skills/frameworks/effect/effect-recoverable-actions/references/flow-examples.md

@@ -0,0 +1,154 @@
+# Effect Flow Examples
+
+Use these generic flow shapes as grounding examples.
+
+## Role Change
+
+Shape:
+
+- preflight membership lookup and role checks
+- external auth-provider role mutation
+- local audit insert
+- optional local notification insert
+
+Risk:
+
+- if the local DB write fails after the auth-provider mutation, the external state already changed
+
+Guidance:
+
+- do not pretend DB rollback covers the auth provider
+- force an explicit compensation or durable repair story
+- keep expected recoverable failures typed
+
+## Member Lifecycle Update
+
+Shape:
+
+- preflight member lookup and guard checks
+- member active-state update
+- session revocation
+
+Risk:
+
+- if later durable work fails, the lifecycle transition can partially apply
+
+Guidance:
+
+- make the transaction and step-boundary story explicit
+- default to one transaction boundary for DB-only multi-write groups
+
+## Bootstrap and Resolve
+
+Shape:
+
+- resolve session
+- resolve active member
+- maybe activate an organization
+- maybe bootstrap an organization
+- follow-up identity resolution
+
+Risk:
+
+- bootstrap-related work can succeed and later resolution can still fail or return incomplete state
+
+Guidance:
+
+- make recoverable bootstrap sequencing explicit
+- separate preflight, external mutation, and follow-up resolution steps
+- preserve clear failure semantics rather than silently collapsing distinct states
+
+## Canonical DB-Only Shape
+
+Use this as the default shape for a recoverable DB-only multi-step Effect action:
+
+```ts
+import { SqlClient } from "@effect/sql"
+import * as Effect from "effect/Effect"
+
+export const performAction = Effect.fn("Feature.performAction")(function* (input: Input) {
+  const sql = yield* SqlClient.SqlClient
+  const repoA = yield* RepoA
+  const repoB = yield* RepoB
+
+  // 1. Preflight before the durable mutation group starts.
+  const state = yield* repoA.loadPreflight(input.id)
+  if (!state) {
+    return yield* new EntityNotFoundError({ id: input.id, message: "Entity not found." })
+  }
+
+  // 2. Keep the commit path sequential and inside one transaction boundary.
+  return yield* sql.withTransaction(
+    Effect.gen(function* () {
+      yield* repoA.writeStepOne(...)
+      yield* repoB.writeStepTwo(...)
+      return yield* repoA.loadResult(...)
+    }),
+  )
+})
+```
+
+Default test shape:
+
+- unit test with fake repos/services to inject failure at each step
+- integration test proving the DB transaction actually rolls back on later failure
+- explicit assertion for the compensation or repair path when external work is involved
+
+## Canonical Cross-System Shape
+
+Use this as the default shape for an Effect action that touches DB, an auth provider, and email:
+
+```ts
+import { SqlClient } from "@effect/sql"
+import * as Effect from "effect/Effect"
+
+export const performCrossSystemAction = Effect.fn("Feature.performCrossSystemAction")(
+  function* (input: Input) {
+    const sql = yield* SqlClient.SqlClient
+    const repo = yield* Repo
+    const authClient = yield* AuthClient
+    const emailClient = yield* EmailClient
+
+    // 1. Preflight before any durable mutation starts.
+    const state = yield* repo.loadPreflight(input.id)
+    if (!state) {
+      return yield* new EntityNotFoundError({ id: input.id, message: "Entity not found." })
+    }
+
+    // 2. Keep local durable writes atomic.
+    const committed = yield* sql.withTransaction(
+      Effect.gen(function* () {
+        yield* repo.insertAuditRow(...)
+        yield* repo.insertRepairMarker(...)
+        return yield* repo.loadCommittedState(...)
+      }),
+    )
+
+    // 3. External writes are outside DB rollback. Handle them explicitly.
+    yield* authClient.updateMemberRole(...).pipe(
+      Effect.catchTag("AuthProviderOperationError", (error) =>
+        Effect.fail(
+          new CrossSystemRepairRequiredError({
+            message: "Local state committed but auth-provider sync failed.",
+            cause: error.message,
+          }),
+        ),
+      ),
+    )
+
+    // 4. Email delivery needs its own explicit policy.
+    yield* emailClient.send(...).pipe(
+      Effect.catchTag("EmailSendError", () => repo.markEmailRepairRequired(committed.id)),
+    )
+
+    return committed
+  },
+)
+```
+
+What this example is teaching:
+
+- one DB transaction for local atomic writes
+- no claim that DB rollback undoes auth-provider or email work
+- explicit typed failure or repair state for auth-provider sync failure
+- explicit delivery policy for email instead of pretending it is transactional

package/dist/skills/frameworks/effect/effect-recoverable-actions/references/source-backed-primitives.md

@@ -0,0 +1,104 @@
+# Source-Backed Primitives
+
+Use local `opensrc` source to verify these Effect recoverability primitives.
+
+## Transactions
+
+- `@effect/sql` exposes `SqlClient.withTransaction(...)`.
+- `SqlClient.withTransaction(...)` widens the error channel with `SqlError`.
+- The internal SQL client implementation uses begin / commit / rollback and nested savepoints through `TransactionConnection`.
+- The `sql-drizzle` tests show Drizzle queries participate in the transaction and roll back on failure.
+- Those guarantees apply to work that stays inside the transaction-aware Effect/SQL context. Work escaped into plain promises or remote callbacks needs separate care.
+
+Implication for Effect backends:
+
+- teach action-level transaction wrapping
+- do not teach manual savepoint orchestration as the primary authoring model
+- remember that transaction wrappers can change the action error type
+
+## Yieldable typed errors
+
+- `Cause.YieldableError` is explicitly yieldable in `Effect.gen`.
+- `Schema.TaggedError` extends a yieldable error base.
+
+Implication for Effect backends:
+
+- recoverable action-flow failures should stay typed
+- typed yieldable errors are valid directly inside generator flows
+
+## Recovery operators
+
+These are present in `Effect` source and are fair game for this skill:
+
+- `catchTag`
+- `catchTags`
+- `retry`
+- `retryOrElse`
+
+Implication for Effect backends:
+
+- prefer selective typed recovery over generic `catchAll`
+- keep retries narrow and explicit
+
+## Control flow
+
+These are present in `Effect` source:
+
+- `when`
+- `unless`
+- `match`
+- `matchEffect`
+
+Implication for Effect backends:
+
+- use them when the control-flow choice carries recovery meaning
+- keep commit-path sequencing obvious
+
+## Error accumulation and parallel behavior
+
+These are present in `Effect` source:
+
+- `partition`
+- `validateAll`
+- `Effect.all` with default / `either` / `validate` modes
+- `parallelErrors`
+
+Important source-backed semantics:
+
+- `Effect.all` short-circuits by default
+- `Effect.all(..., { mode: "either" })` runs all effects and returns `Either` results
+- `Effect.all(..., { mode: "validate" })` runs all effects and returns accumulated `Option` failures
+- `validateAll` accumulates failures but loses successes if any failures exist
+- `partition` keeps both failures and successes
+
+Practical choice in Effect backends:
+
+- use `validateAll` when you want "all successes or the full set of failures" in a preflight phase
+- use `partition` when you need successes and failures kept separately
+- use `Effect.all(..., { mode: "either" | "validate" })` when the work is naturally concurrent and the per-branch result shape matters
+
+Implication for Effect backends:
+
+- use these in preflight, batch validation, or deliberate parallel collection phases
+- do not hide commit-path mutation semantics behind them
+
+## Cleanup vs rollback
+
+These are present in `Effect` source:
+
+- `acquireUseRelease`
+- `ensuring`
+
+Implication for Effect backends:
+
+- they are cleanup/finalization primitives
+- they are not automatic business rollback or compensation
+
+## Adjacent but out of scope
+
+- `Effect.withExecutionPlan` exists, but source marks it experimental
+
+Implication for Effect backends:
+
+- mention only as adjacent background
+- do not teach it as the default project recoverability model in v1

package/dist/skills/frameworks/effect/effect-recoverable-actions/references/strategy-matrix.md

@@ -0,0 +1,34 @@
+# Strategy Matrix
+
+Use this table to choose the recovery model before writing code.
+
+| Flow shape | Default strategy | Notes |
+| --- | --- | --- |
+| DB read + DB write + DB write | One `SqlClient.withTransaction(...)` around the action-local DB mutation group | Keep commit-path sequencing explicit. |
+| DB write + DB write inside nested helpers | One outer `SqlClient.withTransaction(...)` | Effect SQL internals support nested savepoints; author code at the action boundary, not with manual savepoints. |
+| DB + Better Auth mutation | Compensation or durable repair path | DB rollback does not undo Better Auth state. |
+| DB + Better Auth + email | DB transaction only for local writes, then explicit compensation / repair for Better Auth, plus an explicit delivery policy for email | Do not imply a single rollback boundary across all three systems. |
+| DB + email / queue / third-party side effect | Explicit commit boundary plus post-commit recovery story | Decide whether the side effect is best-effort, compensatable, or must create repairable operator state. |
+| Preflight validation over many items | `validateAll`, `partition`, or `Effect.all(..., { mode: "validate" | "either" })` | Use before the commit path, not during it. |
+| Parallel validation or read-only fan-out | `Effect.all` with explicit concurrency, optionally `parallelErrors` | Be explicit about whether you want short-circuiting, `either`, `validate`, or collected parallel errors. |
+| Commit path orchestration | Sequential by default | Introduce concurrency only when the failure semantics stay safe and obvious. |
+
+## Classification guide
+
+- `preflight`
+  Validation, lookups, and checks that can fail before any durable mutation starts.
+- `transactional-db`
+  DB writes that must commit or roll back together.
+- `retryable transient integration`
+  External call with explicit transient failure handling and safe retry semantics.
+- `compensation-required external`
+  External write that cannot be covered by DB rollback.
+- `post-commit follow-up`
+  Side effect that happens after the main durable state transition and therefore needs an explicit repair story if it fails.
+
+## Approval heuristics
+
+- If all durable mutations are in the same DB boundary, use one transaction.
+- If any step mutates external state, write down the compensation or repair story before implementation.
+- If a retry changes business semantics or risks duplicates, do not retry the whole pipeline.
+- If a collection helper hides which steps are concurrent or fail-fast, prefer explicit sequential composition in the commit path.

package/dist/skills/frameworks/effect/effect-recoverable-actions/references/test-matrix.md

@@ -0,0 +1,36 @@
+# Test Matrix
+
+Every multi-step mutating action needs failure-path coverage, not only happy-path coverage.
+
+## Required scenarios
+
+- later DB step fails and earlier DB writes are rolled back
+- nested DB helper usage still preserves the outer transaction boundary
+- external step succeeds and a later local step fails, triggering compensation or leaving a deliberate repairable state
+- transient retryable integration step retries only that step
+- non-retryable integration failure surfaces once as a typed error
+- preflight accumulation returns the intended set of validation failures
+- intentionally parallel validation or read fan-out uses the right collection primitive and expected error semantics
+- simple one-step actions are not over-engineered with unnecessary orchestration machinery
+
+## Unit-level expectations
+
+- fake leaf services and repos should make each failure point injectable
+- tests should assert which step ran and which step did not
+- tests should prove the chosen retry / compensation / transaction story, not just the final error message
+
+## Integration-level expectations
+
+- verify DB rollback behavior with live layers when the flow relies on transactions
+- verify that public router/action behavior exposes typed expected failures correctly
+- verify that recoverable degraded states are observable when compensation is impossible
+
+## Review checklist
+
+When reviewing a new multi-step action, ask:
+
+- where is the transaction boundary
+- what external writes escape the DB boundary
+- what is the retry scope
+- what is the compensation or repair path
+- which tests prove the story