@danieljvdm/dev-kit 0.11.3 → 0.13.0

package/skills/effect-ts/references/guide-cli.md

@@ -1,107 +0,0 @@
-# Effect CLI
-
-## Overview
-
-Build scripts as small Effect programs with typed errors, platform services, and `effect/unstable/cli`. Read nearby scripts first and follow local conventions for imports, package scripts, and validation commands.
-
-Use the matching general and local guides from `effect-ts` when the CLI also
-includes domain models, reusable services, layers, typed domain errors,
-structured logging, tests, or HTTP/runtime boundary code.
-
-## Workflow
-
-1. Read nearby scripts before editing. Prefer the repo's current imports, error classes, command helper names, and package-script style.
-2. Use `effect/unstable/cli` for command shape, descriptions, help, and arguments/options.
-3. Use platform services for effects:
-   - `@effect/platform-node`: `NodeRuntime`, `NodeServices`
-   - `@effect/platform-bun`: Bun equivalent only when the project already uses it
-   - `FileSystem`, `Path`, `Console`, `Terminal`, `ChildProcess`, `Stream` from Effect/platform packages where available
-4. Keep direct `node:*`, Bun globals, `process.argv`, `process.env`, `console.*`, `fs`, `path`, and `child_process` calls inside explicit runtime adapters. Use Effect platform services throughout script logic.
-5. Model expected failures as `Schema.TaggedErrorClass` with useful `message` overrides.
-6. Keep shell execution deterministic: pass command and args as arrays to `ChildProcess.make`, set `cwd` explicitly, capture output, and fail on non-zero exit.
-7. Make interactive flows explicit and pleasant: show a short title, summarize detected state, prompt before ambiguous choices, and print the final command/action before running it.
-8. Wire the command with `CliCommand.run(command, { version: "1.0.0" }).pipe(Effect.scoped, Effect.provide(NodeServices.layer))`, then `NodeRuntime.runMain(program, { disableErrorReporting: true })`.
-9. Update `package.json` scripts to call the TypeScript script through the repo's established runner (`tsx`/`bun`) and keep runner choice consistent across scripts.
-10. Include every executable TypeScript script in one checked TypeScript project. Validate with `bun run check` or the narrow package check plus a direct `--help`/dry-run path for the new command.
-
-## Script Skeleton
-
-Use this shape unless local scripts have a better established variant:
-
-```ts
-import { NodeRuntime, NodeServices } from "@effect/platform-node";
-import { Console, Effect, Path, Schema as S, Stream } from "effect";
-import { Command as CliCommand } from "effect/unstable/cli";
-import { ChildProcess } from "effect/unstable/process";
-
-class CommandError extends S.TaggedErrorClass<CommandError>()("CommandError", {
-  command: S.String,
-  exitCode: S.Int,
-  output: S.String,
-}) {
-  override get message() {
-    return this.output.length > 0
-      ? `${this.command} exited with code ${this.exitCode}: ${this.output}`
-      : `${this.command} exited with code ${this.exitCode}`;
-  }
-}
-
-const runCommand = Effect.fn("runCommand")(function* (
-  cwd: string,
-  command: string,
-  args: ReadonlyArray<string>,
-) {
-  const formatted = [command, ...args].join(" ");
-  const child = yield* ChildProcess.make(command, args, { cwd, stderr: "pipe", stdout: "pipe" });
-  const [output, exitCode] = yield* Effect.all([
-    Stream.mkString(Stream.decodeText(child.all)),
-    child.exitCode,
-  ]);
-  const trimmed = output.trim();
-
-  if (exitCode !== 0) {
-    return yield* new CommandError({ command: formatted, exitCode, output: trimmed });
-  }
-
-  return trimmed;
-});
-
-const main = Effect.gen(function* () {
-  yield* Console.log("Doing work...");
-});
-
-const command = CliCommand.make("script-name", {}, () => main).pipe(
-  CliCommand.withDescription("Describe what the script does."),
-);
-
-const program = CliCommand.run(command, { version: "1.0.0" }).pipe(
-  Effect.scoped,
-  Effect.provide(NodeServices.layer),
-);
-
-NodeRuntime.runMain(program, { disableErrorReporting: true });
-```
-
-## CLI Design Rules
-
-- Prefer named options over environment variables for normal user input. Keep environment variables only for CI or stable machine-local overrides.
-- Prefer deterministic auto-detection when there is exactly one valid candidate; prompt or fail clearly when there are zero or many.
-- Print normal interactive UI/status lines to stdout with `Console.log`; use stderr for real errors or for commands that intentionally reserve stdout for machine-readable output.
-- For visually nicer output, use simple ASCII structure that degrades well in CI: title lines, aligned labels, and short bullet lists. Avoid decorative Unicode unless the file already uses it.
-- Use `CliCommand.withDescription` and ensure `--help` explains the happy path and escape hatches.
-- Add a dry-run or help path for scripts that would start long-running servers or device builds.
-- Decode structured JSON input with `Schema.fromJsonString(Model)` so parsing
-  and validation share one schema-owned boundary.
-
-## Validation
-
-Run the narrowest meaningful checks:
-
-- Confirm that every TypeScript entrypoint named by `package.json` belongs to
-  one checked TypeScript project.
-- The repository's root `check` or typecheck script when the entrypoint belongs
-  to the root project.
-- Package-level `bun run check` when the script lives under an app/package and is included in that TS config.
-- The command's `--help` path.
-- A dry-run or harmless invalid-input path that loads the entrypoint and
-  exercises parsing and environment discovery.

package/skills/effect-ts/references/guide-datetime.md

@@ -1,72 +0,0 @@
-# Effect DateTime
-
-Prefer Effect `DateTime` over vanilla JavaScript `Date` for application logic. Keep `Date` as an interoperability type at external boundaries, not the domain model.
-
-## Workflow
-
-1. Inspect the installed `effect` version and `DateTime` source before relying on exact signatures. DateTime APIs are version-sensitive.
-2. Identify whether each value represents an absolute instant, a wall-clock time in a named zone, or only a calendar date. Do not silently collapse these meanings.
-3. Decode external strings, numbers, and `Date` objects at the boundary. Use `Schema.DateTimeUtc`, `Schema.DateTimeUtcFromString`, `Schema.DateTimeUtcFromMillis`, `Schema.DateTimeUtcFromDate`, or `Schema.DateTimeZoned` as appropriate.
-4. Keep domain values as `DateTime.Utc` by default. Use `DateTime.Zoned` when calendar operations or presentation must retain an IANA time zone.
-5. Use `DateTime.now` inside Effect programs so the current time comes from the `Clock` service. Reserve `DateTime.nowUnsafe()` and `Date.now()` for explicit synchronous host boundaries.
-6. Perform comparisons, arithmetic, rounding, and formatting with `DateTime` operations, then convert to `Date` or epoch milliseconds only when an external API requires them.
-7. Test time-dependent behavior with `it.effect` and `TestClock`; advance virtual time instead of sleeping or consulting the live clock.
-
-## Construction and boundaries
-
-- Prefer safe decoding for untrusted input. `DateTime.make` and zoned constructors return `Option`; Schema decoders produce structured parse failures.
-- Use `DateTime.makeUnsafe` only for literals and values already validated by the program. Do not turn user input into defects.
-- Prefer explicit ISO 8601 strings with offsets at wire boundaries. Avoid implementation-dependent or locale-formatted date strings.
-- Do not invent a midnight instant for a genuinely date-only value such as a birthday. Preserve a validated `YYYY-MM-DD` or a domain-specific year/month/day structure until an actual time and zone are chosen.
-- Use `DateTime.makeZonedFromString` or `Schema.DateTimeZoned` when a serialized value must preserve its zone.
-- Use `DateTime.toDateUtc`, `DateTime.toEpochMillis`, and `DateTime.fromDateUnsafe` only at interop boundaries.
-
-```ts
-import { DateTime, Effect, Schema } from "effect";
-
-const Timestamp = Schema.DateTimeUtcFromString;
-
-const expiresAt = DateTime.makeUnsafe("2030-01-01T00:00:00Z");
-
-const isExpired = Effect.gen(function* () {
-  const now = yield* DateTime.now;
-  return DateTime.isLessThanOrEqualTo(expiresAt, now);
-});
-```
-
-## Instants, zones, and arithmetic
-
-- Treat `DateTime.Utc` as an instant without retained zone information. Treat `DateTime.Zoned` as the same kind of instant plus a zone used for wall-clock parts, formatting, and zone-aware transformations.
-- Use `DateTime.setZone` or `setZoneNamed` to view the same instant in another zone. When constructing from local wall-clock parts, use `makeZoned` with `adjustForTimeZone: true` and choose a deliberate `disambiguation` policy for DST gaps and repeated times.
-- Use `DateTime.addDuration` and `subtractDuration` for elapsed time. Use `DateTime.add` and `subtract` for calendar arithmetic such as days, months, and years; these operations account for a zoned value's calendar rules.
-- Use `DateTime.startOf`, `endOf`, or `nearest` rather than hand-editing fields. State `weekStartsOn` when week boundaries are domain-sensitive.
-- Use `DateTime.Order`, `Equivalence`, `min`, `max`, `between`, and comparison helpers rather than comparing formatted strings or mutable `Date` objects.
-- Use `formatIso` for UTC interchange, `formatIsoZoned` when preserving a zone, and `format` / `formatIntl` for presentation. Do not persist locale-formatted output.
-
-## Current time and tests
-
-Code that asks what time it is must remain clock-driven:
-
-```ts
-import { assert, it } from "@effect/vitest";
-import { DateTime, Duration, Effect } from "effect";
-import { TestClock } from "effect/testing";
-
-it.effect("expires after an hour", () =>
-  Effect.gen(function* () {
-    yield* TestClock.setTime(DateTime.toEpochMillis(DateTime.makeUnsafe("2030-01-01T00:00:00Z")));
-    const startedAt = yield* DateTime.now;
-
-    yield* TestClock.adjust("1 hour");
-    const now = yield* DateTime.now;
-
-    assert.strictEqual(Duration.toMillis(DateTime.distance(startedAt, now)), 60 * 60 * 1000);
-  }),
-);
-```
-
-`@effect/vitest` supplies `TestClock` to `it.effect`. Fork work that sleeps, times out, retries, or follows a schedule before advancing the clock. Use `it.live` only when a test intentionally needs real time.
-
-## Completion check
-
-Confirm that domain code uses `DateTime`, untrusted inputs are decoded, UTC versus zoned intent is explicit, DST behavior is deliberate, elapsed and calendar arithmetic are not confused, serialization is stable, and time-dependent tests use `TestClock` without wall-clock sleeps.

package/skills/effect-ts/references/guide-effect.md

@@ -1,440 +0,0 @@
-# Effect Guide
-
-This guide covers general Effect usage, including reusable function boundaries,
-Promise interop, composition, provisioning, and runtime execution.
-
-Key source areas:
-
-- `packages/effect/src/Effect.ts`
-- `packages/tools/`
-- `packages/platform-*`
-- `packages/opentelemetry/`
-- `packages/vitest/`
-
-## Mental Model
-
-`Effect<A, E, R>` is the default way to represent application work.
-
-It describes a computation that:
-
-- succeeds with `A`
-- fails with `E`
-- requires services `R`
-
-The repo consistently uses `Effect` as the main abstraction for:
-
-- business workflows
-- service methods
-- platform integrations
-- resource lifecycles
-- tests
-
-## Most Common Patterns In The Repo
-
-The dominant usage pattern is:
-
-1. use `Effect.gen` for workflows and orchestration
-2. use `Effect.fn` for reusable effectful functions
-3. use precise constructors such as `succeed`, `fail`, `sync`, `try`, and `tryPromise`
-4. use `map`, `flatMap`, and `tap` for local transformations
-5. access services in implementations and `provide*` only at edges
-6. use `acquireRelease` and `scoped` for owned resources
-7. use `catchTag` and `match` for typed recovery
-8. use `run*` only at runtime boundaries
-
-## Prefer `Effect.fn` For Reusable Operations
-
-For reusable effectful operations, prefer `Effect.fn`.
-
-```ts
-import { Effect } from "effect";
-
-const loadUser = Effect.fn("loadUser")(function* (userId: string) {
-  return { id: userId, name: "Ada" };
-});
-```
-
-Use `Effect.fn` when:
-
-- the operation is reusable
-- the operation takes parameters
-- the operation is part of business logic or a module API
-- you want consistent tracing and stack frames
-
-Do not treat `Effect.fnUntraced` as the default. If you do not want an explicit named span, use `Effect.fn` without a span name.
-
-Repo examples:
-
-- `packages/tools/utils/src/Codegen.ts`
-- `packages/tools/openapi-generator/src/OpenApiPatch.ts`
-
-## Use `Effect.gen` For Workflows
-
-Use `Effect.gen` for orchestration and sequential workflows, especially when there are multiple `yield*` steps.
-
-```ts
-const program = Effect.gen(function* () {
-  const config = yield* Config;
-  const repo = yield* UserRepo;
-  const user = yield* repo.getById("u_123");
-  return { config, user };
-});
-```
-
-Use `Effect.gen` when:
-
-- the body is a workflow
-- you are reading multiple services
-- you have branching or multiple sequential steps
-- you are implementing a layer, handler, or orchestration
-
-Repo examples:
-
-- `packages/opentelemetry/src/NodeSdk.ts`
-- `packages/tools/openapi-generator/src/OpenApiGenerator.ts`
-
-## `Effect.fn` vs `Effect.gen`
-
-Use this rule:
-
-- reusable operation: `Effect.fn`
-- inline workflow block: `Effect.gen`
-
-Good split:
-
-```ts
-const loadUser = Effect.fn("loadUser")(function* (userId: string) {
-  const repo = yield* UserRepo;
-  return yield* repo.getById(userId);
-});
-
-const program = Effect.gen(function* () {
-  const user = yield* loadUser("u_123");
-  yield* Effect.logInfo("loaded user", user);
-});
-```
-
-## `Effect.fnUntraced` Is An Escape Hatch
-
-For application and business code, `Effect.fnUntraced` is not the default.
-
-Use it only when:
-
-- the function is an internal low-level helper
-- observability is intentionally being traded away
-- there is a concrete performance or tracing reason
-
-If the only goal is to avoid an explicit named span, prefer:
-
-```ts
-const normalizeUser = Effect.fn(function* (input: string) {
-  return input.trim().toLowerCase();
-});
-```
-
-Instead of:
-
-```ts
-const normalizeUser = Effect.fnUntraced(function* (input: string) {
-  return input.trim().toLowerCase();
-});
-```
-
-## Constructor Functions
-
-The repo uses constructor functions very deliberately.
-
-### `Effect.succeed`
-
-Use for pure successful values.
-
-```ts
-const ok = Effect.succeed(42);
-```
-
-### `Effect.fail`
-
-Use for expected typed failures.
-
-```ts
-const notFound = Effect.fail(UserNotFound.make({ userId: "u_123" }));
-```
-
-### `Effect.sync`
-
-Use for synchronous side effects or pure synchronous construction that should live inside `Effect`.
-
-```ts
-const buildConfig = Effect.sync(() => ({ retries: 3 }));
-```
-
-### `Effect.try`
-
-Use for synchronous code that may throw.
-
-```ts
-import { Effect, Schema } from "effect";
-
-class ParseError extends Schema.TaggedErrorClass<ParseError>()("ParseError", {
-  cause: Schema.Defect(),
-}) {}
-
-const parseJson = (input: string) =>
-  Effect.try({
-    try: () => JSON.parse(input),
-    catch: (cause) => ParseError.make({ cause }),
-  });
-```
-
-### `Effect.tryPromise`
-
-Use for external Promise-returning APIs. Translate recoverable rejections into
-the concrete typed error owned by that integration boundary, preserving an
-opaque cause when it is diagnostically useful. Compose Effect-native APIs
-directly instead of converting them through Promise.
-
-```ts
-import { Effect, Schema } from "effect";
-
-class FetchError extends Schema.TaggedErrorClass<FetchError>()("FetchError", {
-  cause: Schema.Defect(),
-}) {}
-
-const fetchText = (url: string) =>
-  Effect.tryPromise({
-    try: () => fetch(url).then((response) => response.text()),
-    catch: (cause) => FetchError.make({ cause }),
-  });
-```
-
-Preferred rule:
-
-- pure value: `succeed`
-- expected failure: `fail`
-- synchronous non-throwing effect: `sync`
-- synchronous throwing boundary: `try`
-- Promise boundary: `tryPromise`
-
-## Local Composition
-
-The repo uses `map`, `flatMap`, and `tap` constantly for small local transformations.
-
-### `Effect.map`
-
-Use to transform successful values.
-
-```ts
-const userName = loadUser("u_123").pipe(Effect.map((user) => user.name));
-```
-
-### `Effect.flatMap`
-
-Use when the next step returns another `Effect`.
-
-```ts
-const result = loadUser("u_123").pipe(Effect.flatMap((user) => saveAudit(user.id)));
-```
-
-### `Effect.tap`
-
-Use for side effects that should preserve the main value.
-
-```ts
-const result = loadUser("u_123").pipe(
-  Effect.tap((user) => Effect.logDebug("loaded user", { userId: user.id })),
-);
-```
-
-Preferred rule:
-
-- outer workflow: `Effect.gen`
-- local transformation: `map`, `flatMap`, `tap`
-
-## Services And Provisioning
-
-Repo style is:
-
-- access services in implementation code
-- provide them at boundaries
-
-### Access services in implementations
-
-```ts
-const loadUser = Effect.fn("loadUser")(function* (userId: string) {
-  const repo = yield* UserRepo;
-  return yield* repo.getById(userId);
-});
-```
-
-or:
-
-```ts
-const loadUser = (userId: string) =>
-  Effect.service(UserRepo).pipe(Effect.flatMap((repo) => repo.getById(userId)));
-```
-
-### Provide at the edge
-
-```ts
-const program = loadUser("u_123").pipe(Effect.provide(AppLayer));
-```
-
-Use `provideService` and `provideServiceEffect` for targeted overrides, especially in tests or framework boundaries.
-
-Do not default to exporting thin accessor functions that just fetch a service and forward to one service method. Prefer real business operations or direct service usage within the owning workflow.
-
-Repo examples:
-
-- `packages/tools/utils/src/bin.ts`
-- `packages/tools/openapi-generator/test/`
-
-## Error Handling
-
-Common repo patterns:
-
-- `catchTag` for expected tagged errors
-- `match` for totalizing an effect into a value
-- `catchCause` for full-cause infra handling
-
-### `Effect.catchTag`
-
-Use for targeted typed recovery.
-
-```ts
-const safe = loadUser("u_123").pipe(Effect.catchTag("UserNotFound", () => Effect.succeed(null)));
-```
-
-### `Effect.match`
-
-Use when the caller wants a value either way.
-
-```ts
-const result = loadUser("u_123").pipe(
-  Effect.match({
-    onFailure: () => null,
-    onSuccess: (user) => user,
-  }),
-);
-```
-
-For deeper guidance, see `./references/guide-error-handling.md`.
-
-## Resource Management
-
-One of the strongest repo patterns is explicit resource ownership.
-
-### `Effect.acquireRelease`
-
-Use for resources that must be cleaned up.
-
-```ts
-const connection = Effect.acquireRelease(openConnection, (conn) => closeConnection(conn));
-```
-
-### `Effect.scoped`
-
-Use when a workflow consumes scoped resources and should tie cleanup to scope lifetime.
-
-```ts
-const program = Effect.scoped(
-  Effect.gen(function* () {
-    const conn = yield* connection;
-    return yield* conn.query("select 1");
-  }),
-);
-```
-
-Repo examples:
-
-- `packages/platform-node/`
-- `packages/opentelemetry/src/NodeSdk.ts`
-
-## SQL And Runtime Integrations
-
-When Effect already provides a domain module for a capability, prefer that module over direct raw runtime client usage in business code.
-
-Important example:
-
-- prefer Effect SQL modules from `effect/unstable/sql/*` over embedding a native SQL driver directly in domain services
-
-Why:
-
-- transactions, spans, and typed errors stay inside the Effect model
-- layering stays cleaner
-- migrations and query conventions stay consistent
-
-For SQL-specific guidance, see `./references/guide-sql.md`.
-
-## Observability
-
-The repo uses observability around meaningful boundaries, not every tiny helper.
-
-Common patterns:
-
-- `Effect.fn` for named operations
-- `Effect.withSpan` for nested span boundaries
-- `Effect.log*` for operational events
-- `Effect.track` for metrics
-
-For detailed guidance, see `./references/guide-observability.md`.
-
-## Runtime Boundaries
-
-The repo keeps `run*` APIs at true runtime boundaries.
-
-### `Effect.runPromise`
-
-Use when leaving Effect world into Promise-based hosts.
-
-### `Effect.runFork`
-
-Use for background fibers or long-running integration hooks.
-
-### `Effect.runSync`
-
-Use sparingly, mostly in specialized internals where synchrony is guaranteed.
-
-Preferred rule:
-
-- library/business code should return `Effect`
-- entrypoints and integration boundaries should run `Effect`
-- `Effect.runPromise` belongs only where a Promise-based host takes ownership
-  of the Effect program
-
-If you have multiple external entrypoints, prefer `ManagedRuntime`.
-
-## Commonly Used Effect APIs In This Repo
-
-These are the most practically important `Effect` functions to know first:
-
-- `Effect.fn`
-- `Effect.gen`
-- `Effect.succeed`
-- `Effect.fail`
-- `Effect.sync`
-- `Effect.try`
-- `Effect.tryPromise`
-- `Effect.map`
-- `Effect.flatMap`
-- `Effect.tap`
-- `Effect.service`
-- `Effect.provide`
-- `Effect.provideService`
-- `Effect.catchTag`
-- `Effect.match`
-- `Effect.acquireRelease`
-- `Effect.scoped`
-- `Effect.withSpan`
-- `Effect.logInfo`
-- `Effect.logDebug`
-- `Effect.runPromise`
-
-## Good Repo Examples To Study
-
-- `packages/tools/utils/src/Codegen.ts`
-- `packages/tools/openapi-generator/src/OpenApiPatch.ts`
-- `packages/tools/openapi-generator/src/OpenApiGenerator.ts`
-- `packages/opentelemetry/src/NodeSdk.ts`
-- `packages/opentelemetry/src/OtelTracer.ts`
-- `packages/platform-node/`
-- `packages/vitest/src/index.ts`