render-workflows-dart 0.8.2

package/CHANGELOG.md

@@ -0,0 +1,193 @@
+# Changelog
+
+## 0.8.2
+
+**Renamed to `render-workflows-dart`.** `render-dart` said neither which Render
+nor that this is about Workflows, and it reads like a Dart rendering library.
+The name now leads with the product, so a sibling for another language sits
+beside it in a registry listing rather than somewhere else in the alphabet —
+`render-workflows-rust` is the first of those.
+
+Nothing else changed.
+
+- **`render-dart` still works as a command.** The package installs two bins, so
+  an existing project's `"build": "render-dart build"` keeps running untouched.
+  Only the dependency name and the `npx` line move.
+- **`npx render-workflows-dart init`** for a new project: npx resolves a package
+  name, so first contact needs the full one.
+- **`init` removes the old dependency key** rather than adding a second one
+  beside it.
+- The old package is deprecated on npm with a pointer here. It stays
+  installable; nothing breaks the day this ships.
+
+Migrating an existing project is one line:
+
+```diff
+-    "render-dart": "^0.8.1"
++    "render-workflows-dart": "^0.8.2"
+```
+
+Also fixed: the recovery hint printed when a bridge file is missing pointed at
+`node_modules/render-dart/template/`, a directory that has not existed for
+several releases. The files ship in `runtime/`.
+
+## 0.8.1
+
+- **The built-in default is Dart 3.13.1**, was 3.13.0. It is the version an
+  unpinned project gets when no Dart is on `PATH` — which in practice means
+  every Render build — so it should not trail stable by a release.
+
+  This cannot disturb anything already deployed. A default is not an explicit
+  request, and an unexplicit request reuses whatever SDK is vendored whichever
+  version that is; only a build with no vendored SDK fetches the new one. A
+  service that wants a specific version should pin it, which since 0.8.0 works.
+
+## 0.8.0
+**The Dart version pin now pins.** `renderDart.dartVersion` existed before and
+was consulted only on the download path, so it worked on a first Render build
+and was silently ignored everywhere else: on a laptop the Dart on `PATH` always
+won, and on later Render builds whatever had been vendored first won for ever,
+because the cache key was "does the directory exist". Setting it appeared to do
+nothing, which is exactly what it did.
+
+A version asked for explicitly is now honoured wherever the build runs: if
+`PATH` holds a different one, the requested version is downloaded. The built-in
+default still defers to a local toolchain — it exists so a first build has
+something to fetch, not to override a Dart you installed on purpose.
+
+- **Three places to set it**, highest first: `--dart-version`,
+  `RENDER_DART_VERSION`, `renderDart.dartVersion`.
+- **`latest` and channel names** — `stable`, `beta`, `dev` — as well as exact
+  versions. An exact version is interpreted without touching the network, so a
+  pinned project still builds when the archive is unreachable.
+- **`render-dart dart`** reports which Dart the project will use and where it
+  comes from; **`--list`** shows what the archive offers, 176 stable releases
+  today.
+- **The vendored SDK records its version** and is replaced when the pin changes.
+- **Every build says which Dart it used**, and whether it came from `PATH`, the
+  vendored copy, or a download. That alone answers the question that prompted
+  all of this.
+- **Downloads are verified** against the archive's published SHA-256 before
+  being unpacked, hashed while streaming so it costs no extra I/O — 0.18s of CPU
+  for a 228 MB archive against roughly 30s to fetch it.
+
+Two smaller fixes, both found while documenting the above:
+
+- **`render-dart --help` exits 0.** It fell into the unknown-command branch and
+  exited 1, so a script running it defensively saw a failure.
+- **`--help` documents the precedence**, and a test asserts the order it prints
+  matches the resolver's. The help text is one long template literal that no
+  test had ever parsed — a stray backtick in it turned every command into a
+  `SyntaxError` while the whole suite still passed.
+
+## 0.7.1
+
+- Fixes a dead link on the package page. The Postgres example pointed at
+  `github.com/timmaffett/render_dart_workflow_test`, which is private and not
+  where that example lives; it is `examples/postgres` in this repo, and also
+  what `init --template postgres` scaffolds.
+- Documents `--template` in the Commands table, and `allowDartIoIn` in the
+  configuration section — both shipped in 0.7.0 without being written down.
+- The Layout section described `template/`, which 0.7.0 removed. It now lists
+  `examples/` and `runtime/`.
+
+## 0.7.0
+
+**Examples are the templates.** `examples/` holds five complete, runnable
+services, and `init` scaffolds from them:
+
+```bash
+npx render-dart init my-app --template postgres
+```
+
+`default`, `http`, `native`, `postgres` and `introspect`. Making them the same
+thing means a template that does not work is a test failure rather than a
+surprise — there is no second copy to drift.
+
+**Scaffolds carry agent guidance.** `init` writes `AGENTS.md` and a `CLAUDE.md`
+pointing at it into the project it creates. Coding agents never read
+`node_modules`, so nothing shipped inside this package reaches an agent helping
+in your project; the scaffold is the only place that text is certain to be
+seen.
+
+**`renderDart.allowDartIoIn`** exempts named directories from the `dart:io`
+guard. A local tool sitting beside a workflow — a database seeder, say — is a
+normal shape, and previously the only escape was `allowDartIo: true`, which
+switched the check off for task code too.
+
+- `template/` is gone. The two Dart bridge files live in `runtime/`, and the
+  examples carry no copies — `build` writes them when missing, which is also
+  how they stay current on upgrade.
+- README documents native tasks against WebAssembly as two routes past dart2js,
+  with measurements: V8 matches Dart AOT on integer work, so native is for
+  capability and parallelism rather than raw speed.
+
+## 0.6.0
+
+Nothing at a call site needs to know a task is native.
+
+- `@NativeTask(worker: true, idleTimeout: …, timeout: …)` — settings ride with
+  the declaration; `renderDart.native` can still override per entry.
+- A generated facade conditionally exports the implementation or the
+  process-spawning stub, so `import 'native/tools.dart'` compiles to a direct
+  call natively and a process call under dart2js. The same source works both
+  ways, which also makes native code unit-testable on the VM.
+- `NativeCall.scope(worker: false, …)` varies settings for one caller without
+  changing any signature.
+- Implementations are named `<name>_impl.dart` so the facade can take the plain
+  name; an entry that would be clobbered by its own facade is refused.
+
+## 0.5.0
+
+Native tasks, and worker mode.
+
+- Declare Dart files in `renderDart.native`, annotate top-level functions with
+  `@nativeTask`, and call them from task code. That reaches `dart:io`,
+  `dart:ffi`, isolates and packages with no web build — `postgres` among them.
+- JSONL over stdin/stdout, every message carrying an id. `print()` on the
+  native side becomes a `$log` line rather than corrupting the framing, and a
+  native `throw` arrives as a `NativeTaskException` with its real message.
+- `worker: true` keeps the executable alive between calls: 10 ms across 20
+  calls against 132 ms spawning each time, measured on Render.
+- Nothing is cross-compiled and no binary is committed — the vendored SDK
+  carries `gen_snapshot`, and Render's build host is already linux/x64.
+
+## 0.4.1
+
+`init` writes `^${version}` from its own package.json.
+
+The template carried a hardcoded `^0.1.0`, which npm reads as `<0.2.0` — so
+every project scaffolded since 0.2.0 silently installed 0.1.1, without wasm
+support, asset resolution or the node bridge. Local tarballs and explicit
+`render-dart@x.y.z` installs all hid it.
+
+## 0.4.0
+
+Tasks can reach npm packages and subprocesses.
+
+- `requireModule(id)` — dart2js output is CommonJS, so `require` is
+  module-scoped and never reaches `globalThis`. The runtime hoists one, rooted
+  at the project directory.
+- `runProcess(command, …)` — `dart:io`'s `Process` compiles under dart2js and
+  then throws. A non-zero exit is returned rather than thrown.
+
+## 0.3.0
+
+Packages that carry their own JS wasm runtime work, `rust_crypto` through
+`wasm_run` among them. Its setup looks browser-only but skips DOM injection
+when the globals are already present, which the runtime seeds.
+
+## 0.2.0
+
+Packages that load `.wasm` modules work. Dart's web asset convention
+(`packages/<name>/…`) is resolved from `.dart_tool/package_config.json`, so
+forge2d's bundled Box2D build needs no configuration.
+
+## 0.1.1
+
+Export `./package.json`.
+
+## 0.1.0
+
+Initial release: write Render Workflows tasks in Dart, compiled to JavaScript
+and registered through Render's `@renderinc/sdk`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Maffett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.