@avytheone/efmesh 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,41 @@ versioning — [SemVer](https://semver.org/).
 Internal development history was tracked in phases F0–F6 (SPEC.md §13);
 the first version gathers them in full.
 
+## [0.2.1] — 2026-07-16
+
+Theme: hygiene for the first stranger — the whole surface is English,
+failures explain themselves, execution is visible.
+
+- Detailed execution log (#14). `apply` and `run` now narrate their work
+  through Effect's logging system: per-model build start/finish with duration,
+  backfill batch progress (`batch n of m` with interval bounds), warn-audits
+  and promotion. Levels — **info** for lifecycle (visible by default), **warn**
+  for warn-audits/retries, **debug** for the rendered SQL and lock internals;
+  the existing `--log-level` flag sets the minimum. Every line carries
+  structured fields (`model`, `env`, `interval`) as annotations. Logs go to
+  **stderr** (stdout and `--json` stay byte-clean); a TTY gets pretty colored
+  output, a pipe/journal gets one-line logfmt with no ANSI. Embedders provide
+  their own `Logger` layer to redirect sinks and levels. Exit codes unchanged.
+- Human-readable, precise errors everywhere (#13). Every tagged error now
+  derives its `message` from its typed fields, so the culprit (model, env,
+  file, interval) and the underlying engine/system text are always present —
+  an empty `EngineError:` is constructively impossible. `EngineError` carries
+  the failing model and the engine's own message; a failing `apply` names the
+  model, quotes DuckDB/Postgres verbatim, and shows the SQL context. The CLI
+  now renders one failure screen (cause first, an actionable hint where one
+  exists) and prints the Effect fiber trace only under `--log-level debug`.
+  Exit codes (0/1/2) and `--json` shapes are unchanged. New exported error
+  `UnknownModelError` (render/lineage against a name not in the project).
+- The entire user-facing surface is English: CLI output and help, error
+  messages, `--json` string values (key names and exit codes unchanged),
+  the `init` scaffold, the hospital example data (#11). Source comments
+  and test names too (#12).
+- **Breaking:** the `apply` confirmation prompt accepts only `y`/`yes`
+  (case-insensitive); the Cyrillic tokens are no longer recognized.
+- `efmesh init` scaffold now teaches the core lifecycle: a seed feeding
+  an incremental-by-time-range model with a blocking audit and a full
+  rollup on top, runnable immediately after `init` (#11).
+
 ## [0.2.0] — 2026-07-16
 
 Theme: "operator and team" — efmesh in the hands of a non-author: the

package/README.md

@@ -211,6 +211,28 @@ changes await a human.
 
 Exit codes: `0` — success, `1` — error, `2` — "awaiting a human": the plan needs confirmation in a non-TTY (add `--yes`), or `run` hit unapplied changes. In a non-TTY, `apply` with changes and no `--yes` refuses — efmesh will not silently roll out a plan nobody has seen.
 
+## Logging
+
+`apply` and `run` narrate what they do. Logs go to **stderr** — stdout stays
+reserved for the plan screen, summaries and `--json`, which stays byte-clean.
+Levels, set by the built-in `--log-level` flag (minimum level, default `info`):
+
+- **info** — lifecycle a human watches: per-model build start/finish with
+  duration, backfill batch progress (`batch 3 of 7` with the interval bounds),
+  promotion.
+- **warn** — warn-audits (violations that do not block) and retries.
+- **debug** — the rendered SQL about to run, lock acquire/release, and other
+  internals. `--log-level debug` also prints the full fiber trace on a failure.
+
+Each line carries structured fields as annotations (`model`, `env`, `interval`,
+…). At a TTY the output is pretty and colored; piped to a file or the systemd
+journal it is one-line [logfmt](https://brandur.org/logfmt) with no ANSI, so a
+log reader (or an AI agent post-morteming a 3am tick) can group by field.
+
+Embedding efmesh as a library? Logging is Effect's `Effect.log*` — provide your
+own `Logger` layer (sink, format, minimum level) and the CLI's choices do not
+apply. Row counts are not logged: efmesh never runs an extra query just to count.
+
 ## Performance
 
 The framework overhead is negligible for any realistic project (in-memory DuckDB, `bun bench/plan-bench.ts N`):

package/README.ru.md

@@ -218,6 +218,29 @@ Exit-коды: `0` — успех, `1` — ошибка, `2` — «ждёт че
 изменения. В не-TTY `apply` с изменениями БЕЗ `--yes` не применяется —
 молча катить план, который никто не видел, efmesh отказывается.
 
+## Логирование
+
+`apply` и `run` рассказывают, что делают. Логи идут в **stderr** — stdout
+остаётся под план, сводки и `--json`, который остаётся байт-чистым JSON.
+Уровни задаёт встроенный флаг `--log-level` (минимальный уровень, по
+умолчанию `info`):
+
+- **info** — жизненный цикл, за которым следит человек: старт/финиш сборки
+  каждой модели с длительностью, прогресс бэкфила (`batch 3 of 7` с границами
+  интервала), промоушен.
+- **warn** — warn-аудиты (нарушения, которые не блокируют) и ретраи.
+- **debug** — рендер SQL перед выполнением, взятие/освобождение лока и прочие
+  внутренности. `--log-level debug` также печатает полный fiber-trace при сбое.
+
+В каждой строке структурные поля-аннотации (`model`, `env`, `interval`, …). В
+TTY вывод красивый и цветной; в файл или systemd journal — однострочный
+[logfmt](https://brandur.org/logfmt) без ANSI, чтобы читатель логов (или
+ИИ-агент, разбирающий трёхчасовой ночной тик) группировал по полям.
+
+Встраиваете efmesh как библиотеку? Логирование — это `Effect.log*`: дайте свой
+`Logger`-слой (приёмник, формат, минимальный уровень), и выбор CLI не действует.
+Число строк не логируется: efmesh не делает лишний запрос ради подсчёта.
+
 ## Перфоманс
 
 Оверхед фреймворка пренебрежим для любого реалистичного проекта (in-memory DuckDB, `bun bench/plan-bench.ts N`):

package/SPEC.md

@@ -220,7 +220,7 @@ on encountering a snapshot of another version, honestly stops
    how many intervals will be recomputed, a textual SQL diff.
 6. `efmesh apply` shows the same plan and applies it: creates physical
    tables, runs the backfill, swaps the views. *Implemented in F4: in a TTY the plan
-   is applied only after an explicit "y" (y/yes/д/да; `--yes`/`-y` skips the
+   is applied only after an explicit "y" (y/yes, case-insensitive; `--yes`/`-y` skips the
    question), exactly the shown plan is applied without recomputation; non-TTY (CI,
    pipes) proceeds without asking.*
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avytheone/efmesh",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "sqlmesh-like data transformation framework on TypeScript, Bun and Effect",
   "license": "MIT",
   "author": "Alexey Yakimanskiy",

package/src/bin.ts

@@ -1,12 +1,49 @@
 #!/usr/bin/env bun
 import { BunRuntime, BunServices } from "@effect/platform-bun"
-import { Effect } from "effect"
+import { Cause, Effect, Logger } from "effect"
 import { Command } from "effect/unstable/cli"
-import { rootCommand } from "./cli.ts"
+import { renderFailure, rootCommand, wantsTrace } from "./cli.ts"
 import { version } from "../package.json"
 
+// Logging (#14) goes to STDERR so `--json` stdout stays byte-clean — a contract
+// for CI and agents. A human at a stderr TTY gets colored pretty output; a pipe,
+// log file or the systemd journal gets plain one-line logfmt with no ANSI, which
+// the fields (model=, env=, interval=) make machine-readable. The minimum level
+// is Info by default (lifecycle visible during apply/run); the CLI's built-in
+// `--log-level` flag lowers it to debug (SQL, lock internals) or raises it. An
+// embedder wanting different sinks/levels provides its own Logger layer instead.
+const loggerLayer = Logger.layer([
+  process.stderr.isTTY === true
+    ? Logger.consolePretty({ stderr: true })
+    : Logger.withConsoleError(Logger.formatLogFmt),
+])
+
+// One central failure screen (#13): catch every cause here and render it
+// ourselves (cause first, one screen, fiber trace only under --log-level
+// debug) instead of letting runMain dump a pretty cause over an empty message.
+// Interrupts (Ctrl+C) are not failures — leave them to the default teardown.
+// The exit code stays a frozen contract: a rendered failure is 1, unless a
+// command already claimed 2 ("awaiting a human") before failing.
+const debug = wantsTrace(process.argv)
+
+// Interrupt with nothing failed/died — Ctrl+C during a clean wait: not a
+// failure to render, hand it back to the default teardown.
+const isInterruptOnly = (cause: Cause.Cause<unknown>): boolean =>
+  !Cause.hasFails(cause) && Cause.interruptors(cause).size > 0
+
 rootCommand.pipe(
   Command.run({ version }),
+  Effect.catchCause((cause) =>
+    isInterruptOnly(cause)
+      ? Effect.failCause(cause)
+      : Effect.sync(() => {
+          process.stderr.write(`${renderFailure(cause, { debug })}\n`)
+          if (process.exitCode === undefined || process.exitCode === 0) {
+            process.exitCode = 1
+          }
+        }),
+  ),
+  Effect.provide(loggerLayer),
   Effect.provide(BunServices.layer),
   BunRuntime.runMain,
 )