@llm4ts/shell 2.32.0 → 2.34.0

package/kits/port/packs/scala-ts/patterns/pitfalls-scala-ts.md

@@ -0,0 +1,21 @@
+---
+title: Scala/ZIO → TypeScript/Effect pitfalls — alike on the page, different at runtime
+matches: .
+tags: port, scala, zio, effect
+---
+1. **Type parameter order.** `ZIO[R, E, A]` is `Effect<A, E, R>`: a mechanical
+   copy of the parameter list silently swaps the requirement and the value.
+2. **Equality.** `==` on a case class compares structure; `===` on an object
+   compares identity. Use `Equal.equals` or compare fields.
+3. **Laziness.** A Scala `lazy val` or by-name parameter evaluates once or on
+   demand; a TypeScript expression evaluates where it is written. Wrap in a
+   thunk or `Effect.suspend`.
+4. **Option.get and head.** Scala throws; TypeScript yields `undefined` and
+   carries on. Make the absence a typed failure.
+5. **Integer division and overflow.** Scala `Int` wraps at 32 bits and `/`
+   truncates; JavaScript numbers are doubles. Use `Math.trunc` and check
+   ranges where the source relied on `Int`.
+6. **String formatting and `toString`.** A Scala `toString` on a case class
+   prints its fields; the TypeScript default prints `[object Object]`.
+7. **Implicit conversions and givens.** They vanish in the port; every one is
+   an explicit call or a service the draft must name.

package/kits/port/packs/scala-ts/prompts/porting.md

@@ -0,0 +1,64 @@
+You are translating one Scala 3 / ZIO 2 file to TypeScript with Effect 4.
+Read this whole document before writing any code. The first pass is a
+**draft** `.ts` beside the `.scala`, same basename, that captures the logic
+faithfully; it does **not** need to type-check. The compile pass makes it
+type-check module by module.
+
+## Ground rules
+
+- Same module, same names (camelCase for values, PascalCase for types), same
+  order of declarations, same control flow. Reviewers diff the two files side
+  by side.
+- Use Effect 4 as the repository uses it: `Effect.gen` for sequencing,
+  `Effect.fn` for named reusable operations, `Context.Service` and `Layer` for
+  replaceable dependencies, `Schema.Class` / `Schema.TaggedClass` for data,
+  `Schema.TaggedError` for expected failures. Never `any`, never an unchecked
+  cast, never a global `Error` as a domain error.
+- Relative imports use `.ts` extensions; a module imports a contract, never a
+  sibling's internals.
+- Leave `// TODO(port): <reason>` for anything you cannot translate
+  confidently. Do not guess.
+- Do not translate build definitions, sbt plugins or Scala-only tooling;
+  note them as `// SKIPPED(port): <what>`.
+
+## Type map
+
+| Scala / ZIO                          | TypeScript / Effect                            |
+| ------------------------------------ | ---------------------------------------------- |
+| `ZIO[R, E, A]`                       | `Effect.Effect<A, E, R>` (note the order)      |
+| `UIO[A]` / `Task[A]`                 | `Effect.Effect<A>` / `Effect.Effect<A, UnknownException>` |
+| `ZStream[R, E, A]`                   | `Stream.Stream<A, E, R>`                       |
+| `ZLayer[RIn, E, ROut]`               | `Layer.Layer<ROut, E, RIn>`                    |
+| `trait Service` + `ZIO.service`      | `Context.Service` class + `yield* Service`     |
+| `case class`                         | `Schema.Class`                                 |
+| `enum` / sealed trait ADT            | `Schema.Union` of `Schema.TaggedClass`         |
+| `Option[A]`                          | optional property / `A \| undefined`           |
+| `Either[E, A]`                       | `Result` or `Effect.Effect<A, E>`              |
+| `Chunk[A]`                           | `ReadonlyArray<A>`                             |
+| `Ref[A]`, `Queue[A]`, `Hub[A]`       | `Ref`, `Queue`, `PubSub`                       |
+| `Scope` / `acquireRelease`           | `Scope` / `Effect.acquireRelease`              |
+| `Schedule`                           | `Schedule`                                     |
+| zio-json codecs                      | `Schema` with `Schema.fromJsonString`          |
+| ZIO Test `spec` / `test`             | `@effect/vitest` `describe` / `it.effect`      |
+| `for` comprehension                  | `Effect.gen(function* () { … })`               |
+
+## Idiom map
+
+- `ZIO.attempt(…)` → `Effect.try(…)`; `ZIO.fail(E)` → `Effect.fail(E)`; `.orDie` → `Effect.orDie`.
+- `.provide(layer)` / `.provideSome` → `Effect.provide(layer)`; layer composition order follows `Layer.provide`.
+- `.catchSome { case e: X => … }` → `Effect.catchTag("X", …)`.
+- `zio.Duration` → `Duration` from effect; `ZIO.sleep` → `Effect.sleep`.
+- Implicit parameters and givens become explicit arguments or services.
+- `==` on case classes is structural; TypeScript needs `Equal.equals` or a field-by-field compare.
+
+## Output format
+
+End the file with the trailer the flow reads:
+
+```ts
+// PORT STATUS
+// source: <path>.scala
+// confidence: high | medium | low
+// todos: <count of TODO(port)>
+// notes: <one line>
+```

package/kits/port/packs/scala-ts/reviewers/effect-fidelity.md

@@ -0,0 +1,13 @@
+---
+files: \.ts$
+---
+Review a TypeScript draft against the rulebook as a port reviewer would, with
+the Scala source in mind: the diff is the draft. Report as findings: a method,
+field or case the source has that the draft lacks; `any`, an unchecked cast, a
+namespace, or a global `Error` in an error channel; a service without a layer
+where the source had a `ZLayer`; a relative import without a `.ts` extension;
+a case class turned into a plain interface where a `Schema.Class` belongs;
+`ZIO[R, E, A]` order kept as `Effect<R, E, A>`; a `for` comprehension turned
+into nested callbacks where `Effect.gen` was the answer; a guessed translation
+where a `TODO(port)` was honest. Do not report imports that cannot resolve
+yet: the compile pass owns those.

package/kits/port/packs/zig-rust/pack.md

@@ -0,0 +1,43 @@
+# Pack: zig-rust
+
+source: zig
+sources: .*\.zig$
+exclude: (^|/)(zig-out|zig-cache|\.zig-cache|node_modules|vendor)/
+target: {{dir}}/{{base}}.rs
+comment: //
+specs-dir: docs/port
+features-dir: docs/port/features
+
+## Gates
+
+- check: cargo check --workspace
+
+## Diagnostics
+
+- command: cargo check --workspace --message-format=json
+- format: cargo
+
+## Ledger
+
+- unit: ^\s+(\w+):\s*(?:\?\*|\*|\[\]|\[\*\])
+- classes: OWNED, SHARED, BORROW_PARAM, BORROW_FIELD, STATIC, JSC_BORROW, BACKREF, INTRUSIVE, FFI, ARENA, UNKNOWN
+- question: Who owns the memory this pointer or slice field points at, and how long does it live? The Rust type follows from the class (OWNED → Box/Vec, BORROW_* → a reference with a lifetime, SHARED → Rc/Arc, FFI → a raw pointer).
+
+## Differential
+
+- tests: ^test/.*\.test\.(ts|js)$
+- legacy: scripts/legacy-test.sh {{file}}
+- target: scripts/target-test.sh {{file}}
+- timeout: 60
+
+## Audit
+
+- dimensions: error model, allocator threading, collections and strings, comptime carry-over, pointer and ownership idioms, API shape, what not to translate
+
+## Review rules
+
+Every `unsafe` block carries a `// SAFETY: <why>` comment, and no new
+`unsafe` appears outside FFI. A `TODO(port): <reason>` marker is the right
+answer where the translation is uncertain; a guess is not. `anyhow`,
+`tokio`, `rayon`, `async fn` and `std::fs`/`std::net`/`std::process` are
+findings: the rulebook forbids them.

package/kits/port/packs/zig-rust/patterns/pitfalls-zig-rust.md

@@ -0,0 +1,22 @@
+---
+title: Zig → Rust pitfalls — syntactically alike, semantically different
+matches: .
+tags: port, zig, rust
+---
+The regressions the Bun port shipped (May 2026) were code that reads the same
+in both languages and does something different. Check for each:
+
+1. **Asserts with side effects.** Zig's `std.debug.assert(f())` always calls
+   `f` in every build; Rust's `debug_assert!(f())` erases the call in release.
+   Keep the call, assert the result.
+2. **Slice casts on odd lengths.** The Zig helper truncated a `[]u8` to the
+   element size; `bytemuck::cast_slice` panics on a remainder. Truncate first.
+3. **Bounds checks kept.** Zig ReleaseFast dropped them; Rust release keeps
+   them, so a latent off-by-one the Zig never hit is reachable. Treat an
+   index panic as a real bug in the source's logic, not as noise.
+4. **Comptime format strings.** `comptime` string assembly happened once at
+   build time; a runtime `format!` per call changes both cost and, where
+   markers are rewritten, the bytes. Use a macro or a `const`.
+5. **Placeholder constants.** A value "to be threaded through later" becomes
+   a different limit in the port. Every `TODO(port)` placeholder is listed in
+   the trailer and closed in the compile pass.

package/kits/port/packs/zig-rust/prompts/porting.md

@@ -0,0 +1,67 @@
+You are translating one Zig file to Rust. Read this whole document before
+writing any code. The goal of the first pass is a **draft** `.rs` beside the
+`.zig`, same basename, that captures the logic faithfully; it does **not**
+need to compile. The compile pass makes it compile crate by crate.
+
+## Ground rules
+
+- Write the `.rs` in the same directory as the `.zig`, same basename. Do not
+  invent crate layouts; put the file where the source is.
+- Match the Zig's structure: same `fn` names (snake_case), same field order,
+  same control flow. Reviewers diff `.zig` and `.rs` side by side.
+- No `tokio`, `rayon`, `hyper`, `async-trait`, `futures`. No `std::fs`,
+  `std::net`, `std::process`: the code base owns its event loop and
+  syscalls. No `async fn`.
+- `unsafe` is fine where the Zig was already unsafe. Annotate every block
+  with `// SAFETY: <why>`.
+- Leave `// TODO(port): <reason>` for anything you cannot translate
+  confidently. Do not guess: flagging is better than wrong code.
+- Leave `// PERF(port): <zig idiom>` wherever the Zig used a
+  performance-specific idiom, for the profiling pass.
+- Do not translate tests, build scripts or comptime-only helpers that exist
+  to drive the Zig build; note them as `// SKIPPED(port): <what>`.
+
+## Type map
+
+| Zig                       | Rust                                  |
+| ------------------------- | ------------------------------------- |
+| `[]const u8`              | `&[u8]` (or `&str` only when the Zig guarantees UTF-8) |
+| `[]u8` owned              | `Vec<u8>`                             |
+| `?T`                      | `Option<T>`                           |
+| `anyerror!T`, `E!T`       | `Result<T, Error>` with the crate's error enum, never `anyhow` |
+| `*T`                      | `&mut T` or `*mut T` per the lifetime table |
+| `*const T`                | `&T` or `*const T` per the lifetime table |
+| `std.ArrayList(T)`        | `Vec<T>`                              |
+| `std.StringHashMap(V)`    | `HashMap<Vec<u8>, V>` (the crate's hasher) |
+| `comptime T: type`        | a generic parameter or a trait        |
+| `switch` on tagged union  | `match` on an enum with data          |
+| `defer`                   | a scope guard or `Drop`               |
+| `errdefer`                | explicit cleanup on the `Err` path    |
+
+## Idiom map
+
+- Allocator parameters: delete them outside the AST crates; the Rust side
+  allocates through the type's own methods.
+- `std.debug.assert(expr)` where `expr` has side effects: keep the side
+  effect, assert the value (`debug_assert!` erases the call).
+- Casting slices (`@ptrCast`, `@alignCast`) on odd lengths: the Zig helper
+  truncated; `bytemuck::cast_slice` panics. Truncate explicitly.
+- Bounds checks the Zig dropped in ReleaseFast stay in Rust; do not
+  "optimise" with `get_unchecked` in the draft.
+- `comptime` format strings and string builders become macros or
+  `const` arrays, never runtime strings assembled per call.
+
+## Output format
+
+End the file with the trailer the flow reads:
+
+```rust
+// PORT STATUS
+// source: <path>.zig
+// confidence: high | medium | low
+// todos: <count of TODO(port)>
+// notes: <one line>
+```
+
+`confidence: low` means "the logic is probably wrong; re-read the Zig in the
+compile pass".

package/kits/port/packs/zig-rust/reviewers/port-fidelity.md

@@ -0,0 +1,13 @@
+---
+files: \.rs$
+---
+Review a Rust draft against the rulebook as a port reviewer would, with the
+Zig source in mind: the diff is the draft. Report as findings: a function,
+field or branch the source has that the draft lacks (dropped logic); a
+`pub fn deinit(&mut self)` where `impl Drop` is the rulebook's answer;
+`anyhow::Error` or `Box<dyn Error>` where the crate's error enum belongs;
+a bare `as` narrowing cast; an `unsafe` block without a `// SAFETY:` line;
+`async fn`, `tokio`, `rayon`, `std::fs`, `std::net` or `std::process`; a
+`debug_assert!` whose argument had a side effect in the source; a guessed
+translation where a `TODO(port)` was the honest answer. Do not report imports
+that cannot resolve yet or lifetimes: the compile pass owns those.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.32.0",
+  "version": "2.34.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0",
     "@effect/platform-node-shared": "4.0.0",
-    "@llm4ts/core": "2.32.0",
-    "@llm4ts/flow": "2.32.0",
-    "@llm4ts/runner": "2.32.0"
+    "@llm4ts/core": "2.34.0",
+    "@llm4ts/flow": "2.34.0",
+    "@llm4ts/runner": "2.34.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"