update skills

Author: skulidropek

.codex/skills/effect-ts-guide/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: effect-ts-guide
+description: Teach and apply Effect-TS practices (effect, @effect/schema, @effect/platform) for architecture, typed errors, Layers, dependency injection, resource safety, testing, and migration from async/await/Promise. Use when a user asks how to use Effect, requests best practices, wants to refactor to Effect, or needs mapping from platform modules to Node/Bun/Browser APIs.
+---
+
+# Effect TS Guide
+
+## Overview
+
+Use this skill to teach Effect-TS fundamentals and best practices, then apply them to user code and architecture questions.
+
+## Teaching workflow
+
+1. Clarify context: runtime (node/bun/browser), goal (new app, refactor, review), and constraints.
+2. Separate core vs shell: identify pure domain logic vs effects and boundaries.
+3. Model errors and dependencies: define tagged error types and Context.Tag service interfaces.
+4. Compose with Effect: use pipe/Effect.gen, typed errors, and Layer provisioning.
+5. Validate inputs at boundaries with @effect/schema before entering core.
+6. Explain resource safety: acquireRelease, scoped lifetimes, and clean finalizers.
+7. Provide minimal, runnable examples tailored to the user context.
+8. If the user asks for version-specific or "latest" details, verify with official docs before answering.
+
+## Core practices (short list)
+
+- Use Effect for all side effects; keep core functions pure and total.
+- Avoid async/await, raw Promise chains, and try/catch in application logic.
+- Use Context.Tag + Layer for dependency injection and testability.
+- Use tagged error unions and Match.exhaustive for total handling.
+- Decode unknown at the boundary with @effect/schema; never leak unknown into core.
+- Use Effect.acquireRelease/Effect.scoped for resource safety.
+- Use @effect/platform services instead of host APIs (fetch, fs, child_process, etc.).
+
+## References
+
+- Read `references/best-practices.md` for the extended checklist and examples.
+- Read `references/platform-map.md` when comparing @effect/platform to Node/Bun/Browser APIs.

.codex/skills/effect-ts-guide/references/best-practices.md

@@ -0,0 +1,71 @@
+# Effect-TS Best Practices (concise)
+
+## Design principles
+
+- Keep core logic pure; isolate IO in a thin shell.
+- Model errors explicitly with tagged unions; avoid exceptions.
+- Prefer immutable data and total functions.
+
+## Composition
+
+- Use pipe + Effect.flatMap/map or Effect.gen for sequential flows.
+- Interop with Promise only at boundaries via Effect.try/Effect.tryPromise.
+- Use Match.exhaustive for union handling; avoid switch in domain logic.
+
+## Dependency injection
+
+- Define services with Context.Tag and small interfaces.
+- Provide live layers at runtime; provide test layers in unit tests.
+- Keep service interfaces free of concrete implementations and globals.
+
+## Boundary validation
+
+- Accept unknown at the boundary only.
+- Decode with @effect/schema and pass validated types into core.
+- Fail fast on invalid input; keep validation errors typed.
+
+## Resource safety
+
+- Use Effect.acquireRelease for resources (connections, files, locks).
+- Use Effect.scoped to control lifetimes and ensure finalizers run.
+
+## Platform usage
+
+- Use @effect/platform services instead of host APIs:
+  - HttpClient/HttpServer for HTTP
+  - FileSystem/Path for files and paths
+  - Command/Terminal for CLI and processes
+  - KeyValueStore for local storage-like needs
+
+## Runtime and entrypoints
+
+- Use Effect.runMain (or platform runtime helpers) for application entry.
+- Use Logger/PlatformLogger for structured logging.
+
+## Testing
+
+- Write tests as Effects; provide test layers/mocks.
+- Use TestClock/Ref for deterministic time and state.
+- Use property-based tests for invariants when appropriate.
+
+## Minimal example (service + layer)
+
+```ts
+import { Context, Effect, Layer, pipe } from "effect"
+
+class Clock extends Context.Tag("Clock")<Clock, {
+  readonly nowMillis: Effect.Effect<number, never>
+}>() {}
+
+const ClockLive = Layer.succeed(Clock, {
+  nowMillis: Effect.sync(() => Date.now())
+})
+
+const program = pipe(
+  Clock,
+  Effect.flatMap((clock) => clock.nowMillis),
+  Effect.map((ms) => ({ now: ms }))
+)
+
+const main = Effect.provide(program, ClockLive)
+```

.codex/skills/effect-ts-guide/references/platform-map.md

@@ -0,0 +1,41 @@
+# @effect/platform map (what it replaces)
+
+## Core idea
+
+- @effect/platform provides platform-neutral service interfaces and Layers.
+- It does not monkey-patch globals; you must provide a platform layer.
+
+## Implementation packages
+
+- Node: @effect/platform-node
+- Bun: @effect/platform-bun
+- Browser: @effect/platform-browser
+
+## Common mappings
+
+- FileSystem -> node:fs / fs.promises / Bun file APIs
+- Path -> node:path / Bun path / Deno path
+- Command (+ CommandExecutor) -> child_process.spawn/exec / Deno.Command / Bun.spawn
+- Terminal -> process.stdin/stdout / readline
+- KeyValueStore -> Map / localStorage / file-backed KV
+- PlatformConfigProvider -> dotenv + process.env + file tree config
+- PlatformLogger -> console + file logging
+- Runtime/runMain -> manual main + process signal handling
+
+## HTTP stack
+
+- HttpClient -> fetch / undici / axios
+- FetchHttpClient -> fetch implementation
+- HttpServer/HttpRouter/HttpMiddleware -> node:http + express/fastify/koa
+- HttpApi/OpenApi -> manual route + schema + OpenAPI toolchain
+
+## Sockets and workers
+
+- Socket/SocketServer -> net / ws / WebSocket
+- Worker/WorkerRunner -> worker_threads / Web Workers
+
+## Data and utilities
+
+- Headers/Cookies/Multipart/Etag -> manual header/cookie parsing or third-party middleware
+- Url/UrlParams -> URL / URLSearchParams
+- Ndjson/MsgPack -> ad-hoc codecs or third-party libs