@danieljvdm/dev-kit 0.11.3 → 0.12.0

package/skills/effect-ts/references/atom-tanstack-start.md

@@ -1,69 +0,0 @@
-# Effect Atom TanStack Start integration
-
-TanStack Start code is isomorphic by default, including route loaders. Treat every module used by a route as server-capable unless an explicit boundary says otherwise.
-
-## Choose an SSR strategy
-
-Use one of these models deliberately:
-
-### Client-only atom data
-
-- Put one `RegistryProvider` in the app/root component so client navigations share a registry.
-- Render atom consumers that touch browser-only APIs inside `ClientOnly` from `@tanstack/react-router`.
-- Accept that the fallback is the server-rendered state and fetching begins on the client.
-- Keep the client runtime and API service as module singletons.
-
-```tsx
-import { RegistryProvider } from "@effect/atom-react";
-import { ClientOnly } from "@tanstack/react-router";
-
-export function AppShell() {
-  return (
-    <RegistryProvider defaultIdleTTL={30_000}>
-      <ClientOnly fallback={<DashboardSkeleton />}>
-        <Dashboard />
-      </ClientOnly>
-    </RegistryProvider>
-  );
-}
-```
-
-### SSR plus hydration
-
-- Create the registry and any request-specific runtime/layers per request; never share user/auth state through a process-global registry or memo map.
-- Give decoded query atoms deterministic `serializationKey` values.
-- Mount/run the required serializable atoms on the server, dehydrate only the intended values, and pass them through the document safely.
-- Create the client registry once, then hydrate matching atom identities before descendants consume them. Use `HydrationBoundary` where the installed React adapter supports it.
-- Verify that server and client construct the same API service, family arguments, and serialization keys.
-
-Prefer framework loaders/server functions when they already own SSR data. Do not build a second atom SSR cache merely to mirror loader data; seed atoms from the loader or keep atom fetching client-only.
-
-## Focus is browser-only
-
-`Atom.windowFocusSignal` reads `window` and `document.visibilityState` when mounted. Do not mount it during SSR. Put focus-enabled consumers behind `ClientOnly`, or inject a no-op server signal and the browser signal on the client.
-
-```ts
-const project = projectAtom(projectId).pipe(
-  Atom.swr({
-    staleTime: "30 seconds",
-    revalidateOnFocus: true,
-    focusSignal: Atom.windowFocusSignal,
-  }),
-);
-```
-
-`revalidateOnFocus: true` respects `staleTime`; `"always"` forces a request on every focus signal.
-
-## In-memory limits
-
-Effect Atom's registry cache is in memory and scoped to that registry:
-
-- a new tab, hard reload, server process, or newly created provider starts another cache;
-- idle TTL evicts only unused atoms and is not a maximum-entry or byte-size bound;
-- `keepAlive` and infinite TTL can grow memory with unbounded family keys;
-- browser memory is not durable or shared across users/devices;
-- hydration transfers a snapshot, not a persistent distributed cache.
-
-For large or unbounded parameter spaces, use finite TTLs and avoid `keepAlive`. Put durable/shared caching at the HTTP, server, CDN, or database layer.
-
-Primary TanStack references: [execution model](https://tanstack.com/start/latest/docs/framework/react/guide/execution-model) and [`ClientOnly`](https://tanstack.com/router/latest/docs/api/router/clientOnlyComponent).

package/skills/effect-ts/references/atom-testing.md

@@ -1,67 +0,0 @@
-# Deterministic Effect Atom lifecycle testing
-
-Test cache policy below React first with `AtomRegistry.make()`. Add a React integration test only for provider placement, hook behavior, a browser-only SSR boundary, or hydration.
-
-Use fake timers, a request counter, controllable Effects, and explicit mounts:
-
-```ts
-const registry = AtomRegistry.make({ defaultIdleTTL: 1_000 });
-const unmount = registry.mount(queryAtom);
-const first = registry.get(queryAtom);
-
-// Advance the Effect scheduler/microtasks as required by the installed version.
-// Assert with AsyncResult predicates and request counts.
-
-unmount();
-```
-
-Avoid wall-clock sleeps. Flush Effect work with the repository's established `Effect.yieldNow`/test-clock pattern and advance the test runner's fake timers.
-
-Prefer the installed test APIs over invented helpers or matchers. The upstream Effect tests use `assert(AsyncResult.isSuccess(result))`, `Effect.runPromise(Effect.yieldNow)`, `vitest.advanceTimersByTimeAsync(...)`, and the cleanup returned by `registry.mount(atom)`.
-
-## Required scenarios
-
-### Remount reuse
-
-1. Mount and resolve the query; assert request count `1`.
-2. Unmount, advance less than idle TTL, remount the same atom identity.
-3. Assert the cached success is immediately available and no request occurs while still fresh.
-
-### Stale refresh
-
-1. Resolve once through an SWR wrapper.
-2. Advance past `staleTime` but not idle TTL.
-3. Remount or emit the injected focus signal.
-4. Assert the previous success stays available with `waiting: true`, then a second success arrives and request count becomes `2`.
-5. Also prove a fresh mount/focus does not request.
-
-### TTL eviction
-
-1. Resolve and unmount.
-2. Advance to just before TTL; assert reuse.
-3. Advance to/after TTL and flush disposal; remount.
-4. Assert `Initial`/waiting behavior and a new request.
-
-### Polling cleanup
-
-1. Mount the `Atom.withRefresh` wrapper and resolve once.
-2. Advance one interval; assert one forced refresh.
-3. Unmount and advance several intervals.
-4. Assert the counter does not change. This catches leaked timers or accidental `keepAlive`.
-
-### Mutation invalidation
-
-1. Mount list and detail queries with explicit keys.
-2. Run a successful mutation with matching keys; assert only the intended queries refresh.
-3. Run a failed mutation; assert no invalidation.
-4. Assert cleanup removes invalidation handlers after query disposal.
-
-### React Strict Mode and action ownership
-
-Use a React integration test when hook cleanup or action ownership is part of the behavior. Render the owner inside `StrictMode` and assert the development setup-cleanup replay does not write `Atom.Interrupt` or publish an interrupted failure before an explicit cancellation. When an action spans multiple requests, unmount during the sequence and prove the chosen policy: either the stable owner completes every step, or an explicit cancellation interrupts it intentionally. If the atom is shared, also prove unmounting one consumer does not cancel work still owned by another.
-
-### Aggregate stability
-
-Mount a route atom that uses `AsyncResult.all`, resolve every input, unmount, and remount inside the retention window. Assert the aggregate never returns to `Initial`. Then let one input expire and prove the aggregate reset is caused by that input, not the retained queries.
-
-For runtime/layer tests, seed `runtime.layer` through `RegistryProvider initialValues` with a deterministic test layer. This replaces network services without changing the production atom graph.

package/skills/effect-ts/references/audit-services.md

@@ -1,144 +0,0 @@
-# Auditing Effect Services
-
-Use this for an audit across a codebase, package, feature slice, or diff. Apply
-the service and test rules from the other references selected by
-`effect-ts`.
-
-## Contents
-
-- [Establish Local Rules](#1-establish-local-rules)
-- [Build The Inventory](#2-build-the-inventory)
-- [Trace Authority And Requirements](#3-trace-authority-and-requirements)
-- [Classify Each Candidate](#4-classify-each-candidate)
-- [Audit Test Strategies](#5-audit-test-strategies)
-- [Report Actionable Findings](#6-report-actionable-findings)
-
-## 1. Establish Local Rules
-
-Read the project architecture guidance, Effect conventions, pinned Effect
-version or source, and relevant version-matched examples. Record the governing
-conventions and APIs that later decisions must follow.
-
-Complete this step when the applicable project guidance and pinned source
-examples are named.
-
-## 2. Build The Inventory
-
-Enumerate source and test files, then find:
-
-- Every `Context.Service`, tag, `Layer`, `make`, `provide`, and
-  `provideService`.
-- Service-shaped interfaces or classes with effectful methods.
-- Dependencies passed through parameters, properties, constructors, callbacks,
-  options bags, or Layers.
-- Direct access to time, randomness, cryptography, IDs, configuration, HTTP,
-  persistence, registries, renderers, filesystems, runtime bindings, and
-  mutable globals.
-- Test fakes, in-memory implementations, module mocks, and hand-built
-  `Layer.succeed` values.
-- Public Effects with `unknown` or `any` error types.
-- Assertions, non-null assertions, custom type predicates, structural probes,
-  JSON parsing, Promise catch mappers, and `throw` statements.
-- Local schemas, codecs, JSON types, and runtime helpers that overlap Effect or
-  platform APIs.
-
-Record one row per discovered service or candidate:
-
-| Field         | Question                                                    |
-| ------------- | ----------------------------------------------------------- |
-| Owner         | Which module owns the capability's meaning?                 |
-| Contract      | Where are its interface and tag?                            |
-| Construction  | Does construction yield every runtime dependency?           |
-| Production    | Who owns the concrete implementation and Layer choice?      |
-| Tests         | Does it have an intentional and honest substitute strategy? |
-| Consumers     | Are capabilities yielded or drilled as values?              |
-| Requirements  | Do requirements remain visible to the composition root?     |
-| Type boundary | Who owns decoding, narrowing, and error translation?        |
-| Verdict       | Keep, deepen, relocate, merge, remove, or create?           |
-
-Build a companion type-safety inventory using
-[`guide-type-safety-and-boundaries.md`](guide-type-safety-and-boundaries.md).
-Attach each
-occurrence to its owning service or boundary and record its input provenance,
-intended type or error, and target disposition.
-
-Complete this step when every discovered service, tag, Layer, service-shaped
-candidate, and type-safety occurrence appears exactly once.
-
-## 3. Trace Authority And Requirements
-
-For each inventory row:
-
-1. Trace one caller-visible operation to every effect it performs.
-2. Mark where each dependency first appears and whether code yields it, passes
-   it, captures it, or provides it concretely.
-3. Verify that the module selecting a concrete Layer owns that implementation
-   choice.
-4. Check project-compatible Effect capabilities before recommending an
-   application wrapper.
-5. Follow every requirement to a composition root or an explicit value
-   boundary.
-
-Inspect dependency drilling, Layer arguments, dependency bags, handler-builder
-service values, inner `Effect.provide` calls, direct runtime access, and
-contracts or Layers scattered across unrelated owners.
-
-Complete this step when every capability has an unbroken path from use to its
-composition root or documented value boundary.
-
-## 4. Classify Each Candidate
-
-Apply the authority seam and deletion tests, then assign one classification:
-
-- **Built-in Effect capability** — yield the existing capability.
-- **Application-owned authority** — define a narrow port beside the operation
-  that needs it.
-- **Technology adapter** — implement an application-owned port in the adapter.
-- **Request or domain value** — keep the value explicit.
-- **Framework boundary** — contain the framework-required API in its adapter or
-  composition root.
-- **Pass-through abstraction** — fold it into the real owner.
-
-Prefer an existing owner or a merge of duplicated capabilities over a generic
-registry or dependency bag.
-
-Complete this step when every candidate has one evidence-backed classification
-and each service-or-value decision states why the alternative was rejected.
-
-## 5. Audit Test Strategies
-
-Record how tests replace or control each production service. Verify that
-exported test and in-memory Layers implement the behavior their names promise,
-and keep focused partial fixtures local to their tests.
-
-Complete this step when every production service has an intentional test
-strategy or an explicit production-only rationale.
-
-## 6. Report Actionable Findings
-
-Prioritize by correctness and requirement visibility:
-
-- **P0** — hidden authority, unsafe direct runtime access, broken or duplicated
-  capability, wrong Layer ownership, untyped expected failures, or unchecked
-  external data.
-- **P1** — repeated dependency drilling, hidden requirements, scattered service
-  ownership, manual shape discovery, unjustified assertions, custom substitutes
-  for Effect APIs, or a missing intentional test strategy.
-- **P2** — naming or co-location cleanup that should accompany a nearby
-  refactor.
-
-For each finding include:
-
-1. File, line, or symbol evidence.
-2. The hidden requirement or caller burden.
-3. The smallest target shape using the project's Effect conventions.
-4. The composition-root and test impact.
-5. The behavior and modules that should remain unchanged.
-
-End with explicit keep decisions for values, pure functions, framework
-boundaries, correctly separated ports and adapters, and request-scoped
-services.
-
-Complete the audit when every inventory row and type-safety occurrence has a
-disposition, every proposed change names its owner and target shape, and every
-proposal remains evidence-backed and scoped to observed code.