picoruby-cloudflare-template 0.1.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0514b3333048a221efffa3fa803528f1c2aafac2c14b4f545cfb59484c67ac11
+  data.tar.gz: b5db10ca44c30093aee69c5675055432e89c2761ed70279d518104408fda9c1b
+SHA512:
+  metadata.gz: 7c0531c2e85494b47656f0b621de96bde954776951aa4ede77d8f0ce682ec8328cee3d220ffb6015002e0cbffb933326cc37292e37759b9672d36dd5cc572b77
+  data.tar.gz: e99ef3c75479ee721aa68698a72366a4d8b278385b5d663505bf8214636f5faced03e5cc5ad1cc1abad5f40d29db31df7fe7ada861ac190e362e9c98461b76f4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uchio Kondo
+
+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.

data/README.ja.md

@@ -0,0 +1,183 @@
+# picoruby-cloudflare-template
+
+[English](README.md) | 日本語
+
+PicoRuby向けCloudflare Workerプロジェクトの生成、CrossBuild設定、ローカルES module出力を担当するCRuby gemです。
+Wasm実行時には不要です。npmパッケージの公開も不要です。
+
+## クイックスタート（未公開版の開発中）
+
+macOSでは、まず[Homebrew](https://formulae.brew.sh/formula/emscripten)経由でEmscriptenをインストールします。
+
+```sh
+brew install emscripten
+export PATH="$(brew --prefix emscripten)/bin:$PATH"
+emcc --version
+```
+
+Emscripten 5.0.0以上を使用できます。5.0.7およびHomebrew版6.0.9で動作確認済みです。
+新しい版もバージョンチェックを通りますが、すべての版を検証済みという意味ではありません。
+emsdkから切り替える場合は、`emsdk_env.sh`を読み込まないシェルを使い、`EMSDK`・`EM_CONFIG`・`EM_CACHE`をunsetしてツールチェーンの混在を避けてください。
+
+続いて、このリポジトリで実行します。
+
+```sh
+bundle install
+bundle exec ruby exe/picoruby-cloudflare new ../my-worker --gem-path "$PWD"
+cd ../my-worker
+bundle install
+npm install
+
+export PICORUBY_ROOT=/path/to/picoruby
+# ビルド前に、下記の例に従ってbuild_config.rbのローカルmrbgemパスを設定
+
+bundle exec rake doctor
+bundle exec rake
+npm run dev
+```
+
+PicoRubyはsubmodule初期化済みのチェックアウトを指定します。初期化・Emscripten導入はgemでは行いません。
+`doctor` はPicoRubyの主要ファイル、emcc、emar、Node.js、jsonc-parserを確認します。
+ビルド時にはEmscriptenが対応する版かも検査します。Node.jsはWranglerがサポートする版を使用してください。
+上流のシェルコマンド展開の制限により、ビルド用パスでは空白やシェル特殊文字を拒否します。
+
+配布gemを試す場合は `gem build picoruby-cloudflare-template.gemspec`、
+`gem install ./picoruby-cloudflare-template-0.1.0.rc1.gem` の後、
+`picoruby-cloudflare new my-worker` を使えます。生成先で未公開版を解決するには `bundle install --local` を使用します。
+このリリース候補版を公開した後は `gem install picoruby-cloudflare-template --pre --version 0.1.0.rc1` でインストールできます。
+`VERSION` とRubyGemsのメタデータ上のバージョンは、どちらも `0.1.0.rc1` です。
+
+## 生成物とビルド設定
+
+`new PATH [--name NAME] [--gem-path PATH]` はGemfile、Rakefile、build_config.rb、最小Rackアプリのapp.rb、
+src/index.js、package.json、wrangler.jsonc、.gitignore、README.mdを生成します。
+生成先が存在する場合は空ディレクトリでも上書きしません。Gemfile.lockとpackage-lock.jsonはアプリ側でコミットしてください。
+
+```ruby
+require "picoruby/cloudflare/build"
+
+MRuby::CrossBuild.new("worker") do |conf|
+  conf.cloudflare_worker! do |cf|
+    # 任意: ローカルチェックアウトはrevision指定より優先されます。
+    # cf.picoruby_cloudflare_worker_wasm_mgem_dir = "/path/to/picoruby-cloudflare-worker-wasm"
+    # cf.mruby_rack_mgem_dir = "/path/to/mruby-rack"
+    # cf.picoruby_cloudflare_worker_wasm_revision = "<commit SHA>"
+    # cf.mruby_rack_mgem_revision = "<commit SHA>"
+  end
+  # conf.gem gemdir: File.join(__dir__, "vendor/my-gem")
+  conf.worker_export(
+    app: "app.rb",
+    output_dir: "generated/worker",
+    wrangler_config: "wrangler.jsonc",
+    environment: ENV["CLOUDFLARE_ENV"],
+    project_root: __dir__,
+  )
+end
+```
+
+このrequireはPicoRubyのビルドシステム読込後、build_config.rb内で行います。
+`cloudflare_worker!` はEmscripten、Wasm longjmp、Worker HAL、PicoRuby、Rackと必要なcore mrbgemを設定します。
+Sinatra等のフレームワークはアプリ側で追加します。ABI固有の最終リンク設定（JSPI export等）は実行時ライブラリが所有します。
+属性は `cloudflare_worker!` のブロック内で設定します。ブロックにはCrossBuild自身が渡され、検証やビルド設定の本処理より先に実行されます。
+ブロックなしでも呼べます。その場合は事前に属性を設定してください。`!` はビルド設定を書き換えることを示します。
+両方のディレクトリ属性はデフォルト `nil` で、その場合はrevision属性を使い、`github:` と `checksum_hash:` でgemを宣言します。
+ディレクトリ指定はrevision指定より優先され、相対ディレクトリはbuild_configのディレクトリ基準で解決します。
+revision属性のデフォルトはこのgemに組み込まれた値です。`nil` を代入するとデフォルトに戻ります。
+取得先の選択で `PICORUBY_WORKER_WASM_GEM_DIR` / `MRUBY_RACK_GEM_DIR` は参照せず、`worker:` / `rack:` 引数も受け取りません。
+
+既定のWorker revisionは `e6235bca616dbd4cec619cc0141facdea59a5541`、
+Rackは `05ba46eb0ab490a624a5f2dcb33249670933ff6b` に固定しています。
+revisionがリモート未公開の場合はローカル指定が必要です。gem公開前に、新規チェックアウトから固定revisionを取得できることも確認してください。
+
+`worker_export` に渡す相対パスは `project_root` 基準（省略時はbuild_configのディレクトリ）です。
+生成されたRakefileはPicoRubyのRakeを別プロセスで実行し、ビルドをアプリ内の `.picoruby-build/` に分離します。
+アプリはCrossBuildが解決した `mrbcfile` でコンパイルし、既存の `build/host/bin/mrbc` には依存しません。
+
+## ES module出力と責務
+
+```text
+generated/worker/
+  app.bin
+  bindings.js
+  package.json            # private: true, type: module
+  manifest.json           # generator版・Worker revision・成果物SHA256
+  runtime/
+    index.js              # createWorker({ app, bindingTypes })
+    runtime.js
+    host-bridge.js
+    picoruby-worker.js
+    picoruby-worker.wasm
+  tools/                  # binding registry生成スクリプト
+```
+
+Ruby/C・HAL・共通JS bridgeは実行時ライブラリが、このgemはテンプレート・CrossBuild DSL・export処理・薄いcreateWorkerエントリを所有します。
+共通JSとregistry生成スクリプトは、Wasmをビルドした**同じmrbgemチェックアウト**からコピーします。
+現在の取得場所は `spike/src/` と `spike/scripts/` です。別コピーの実装をこのgemで管理しません。
+レイアウト変更時はexporterと固定revisionを一緒に更新します。
+
+`createWorker` はリクエストごとにVMを生成・破棄し、異なるリクエストのenvを共有しません。
+低レベルの `createRuntime` / `dispatch` / `closeRuntime` も再exportします。
+明示的にVMを再利用した場合、同じVMへのdispatchは実行時ライブラリが直列化します。
+出力はWranglerでバンドルする前提です。Node.jsがそのまま `.wasm` / `.bin` importできるという意味ではありません。
+再配布する場合は、元のmrbgemや追加依存のライセンス条件も確認してください。
+
+アプリの再コンパイルはRakeの依存関係で判定し、exportは同じ内容なら書き直しません。
+registryは環境変更を反映するため毎回検証・生成します。元ビルドのWasmが単独で欠けた場合も再リンクします。
+ただし検証時のPicoRubyはsrc/version.cを毎回更新するため、無変更ビルドでもそのコンパイルと最終リンクが走ります。
+
+## bindings・環境・Wrangler
+
+wrangler.jsoncの `kv_namespaces` / `queues.producers` から型registryを生成します。
+JSONCのコメント・末尾カンマに対応し、不正な設定・重複名・存在しない環境はビルドエラーにします。
+varsの値やsecretはビルド成果物へ埋め込みません。
+
+```ruby
+kv = Cloudflare::KV.from_env(env, "CACHE_KV")
+kv.put("key", "value", ttl: 60)
+value = env["cloudflare.env"].CACHE_KV.get("key")
+Cloudflare::Queue.from_env(env, "EVENTS").send("created")
+token = ENV["API_TOKEN"]
+```
+
+Queueは現行APIに合わせてUTF-8文字列送信のみです。secretは.dev.varsまたは `wrangler secret put` で管理し、Gitへ追加しないでください。
+`npm run dev` / `npm run deploy` ではWranglerのcustom buildがRakeを実行します。
+`build.watch_dir` はapp.rbとbuild_config.rbです。Rubyファイルを増やしたときは監視対象も更新してください。
+
+```sh
+CLOUDFLARE_ENV=staging npm run dev
+CLOUDFLARE_ENV=staging npm run deploy
+```
+
+名前付き環境を `--env staging` だけで選ぶとcustom buildに環境名が伝わりません。
+Wranglerとexporterが同じ `CLOUDFLARE_ENV` を参照するようにしてください。
+リソースbindingは環境ごとに定義し、トップレベルから継承しません。
+
+## テスト・最小再現
+
+```sh
+bundle exec rake test
+
+PICORUBY_ROOT=/path/to/picoruby \
+PICORUBY_WORKER_WASM_GEM_DIR=/path/to/picoruby-cloudflare-worker-wasm \
+MRUBY_RACK_GEM_DIR=/path/to/mruby-rack \
+bundle exec rake test:integration
+```
+
+このテストコマンドのmrbgem環境変数は、統合テスト用ハーネスへの入力に限定しています。
+ハーネスは生成したbuild_configへディレクトリ属性を明示的に書き込み、ビルド実行前にこれらの環境変数を解除します。
+
+単体テスト: CLI、非上書き、パス検証、DSL、compiler選択、増分export、欠損Wasm復旧、コンパイル失敗時の保護。
+統合テスト: 新規生成・依存インストール・ビルド・Wrangler dry-run・ローカルHTTPとhot reload・実Wasm経由のENV/KV TTL/Queue・
+並行リクエスト間のenv分離・環境切り替え・欠損Wasm復旧。
+統合テスト用Node.jsはJSPI対応が必要です。デプロイやCloudflareリソースの作成はしません。
+調査用に、表示した一時ディレクトリへ全成果物とステップ別ログを残します。
+
+検証対象: PicoRuby `33540f66d9aba633d4d3ebd6707d5c12baebb652`、上記Worker/Rack revision、
+Ruby 4.0.5、Emscripten 5.0.7およびHomebrew版6.0.9、Node.js 26.8.1、Wrangler 4.125.0。
+compatibility dateは固定Wranglerと組み合わせて確認した `2026-08-22` を使います。
+dry-runはworkerdを起動しないため、Wrangler/dateの更新時はローカルHTTP確認も必要です。
+PicoRubyやmruby submoduleのビルドAPI変更時には統合テストを再実行してください。
+
+## ライセンス
+
+このgemは [MIT License](LICENSE) で公開しています。

data/README.md

@@ -0,0 +1,183 @@
+# picoruby-cloudflare-template
+
+English | [日本語](README.ja.md)
+
+A CRuby gem for generating PicoRuby Cloudflare Worker projects, configuring CrossBuild, and exporting local ES modules.
+It is not needed at Wasm runtime, and publishing an npm package is not required.
+
+## Quick start (before publication)
+
+On macOS, install Emscripten via [Homebrew](https://formulae.brew.sh/formula/emscripten) first:
+
+```sh
+brew install emscripten
+export PATH="$(brew --prefix emscripten)/bin:$PATH"
+emcc --version
+```
+
+Emscripten 5.0.0 or later is accepted. Versions 5.0.7 and Homebrew 6.0.9 are tested;
+accepting newer versions does not imply they have all been tested.
+If switching from emsdk, use a shell without `emsdk_env.sh` and unset `EMSDK`, `EM_CONFIG`, and `EM_CACHE` to avoid mixing toolchains.
+
+Then run the following from this repository:
+
+```sh
+bundle install
+bundle exec ruby exe/picoruby-cloudflare new ../my-worker --gem-path "$PWD"
+cd ../my-worker
+bundle install
+npm install
+
+export PICORUBY_ROOT=/path/to/picoruby
+# Set local mrbgem paths in build_config.rb as shown below before building
+
+bundle exec rake doctor
+bundle exec rake
+npm run dev
+```
+
+Use a PicoRuby checkout with its submodules initialized. This gem does not initialize submodules or install Emscripten.
+`doctor` checks key PicoRuby files, emcc, emar, Node.js, and jsonc-parser.
+The build also checks that the Emscripten version is supported. Use a Node.js version supported by Wrangler.
+Build paths containing spaces or shell metacharacters are rejected because of upstream shell command expansion limitations.
+
+To try a packaged gem, run `gem build picoruby-cloudflare-template.gemspec`, followed by
+`gem install ./picoruby-cloudflare-template-0.1.0.rc1.gem` and
+`picoruby-cloudflare new my-worker`. Use `bundle install --local` in the generated project to resolve the unpublished version.
+After this release candidate is published, install it with `gem install picoruby-cloudflare-template --pre --version 0.1.0.rc1`.
+`VERSION` and the RubyGems metadata version are both `0.1.0.rc1`.
+
+## Generated files and build configuration
+
+`new PATH [--name NAME] [--gem-path PATH]` generates a Gemfile, Rakefile, build_config.rb, a minimal Rack app in app.rb,
+src/index.js, package.json, wrangler.jsonc, .gitignore, and README.md.
+An existing destination is never overwritten, even if it is an empty directory. Commit Gemfile.lock and package-lock.json in your application repository.
+
+```ruby
+require "picoruby/cloudflare/build"
+
+MRuby::CrossBuild.new("worker") do |conf|
+  conf.cloudflare_worker! do |cf|
+    # Optional: local checkouts take precedence over revisions.
+    # cf.picoruby_cloudflare_worker_wasm_mgem_dir = "/path/to/picoruby-cloudflare-worker-wasm"
+    # cf.mruby_rack_mgem_dir = "/path/to/mruby-rack"
+    # cf.picoruby_cloudflare_worker_wasm_revision = "<commit SHA>"
+    # cf.mruby_rack_mgem_revision = "<commit SHA>"
+  end
+  # conf.gem gemdir: File.join(__dir__, "vendor/my-gem")
+  conf.worker_export(
+    app: "app.rb",
+    output_dir: "generated/worker",
+    wrangler_config: "wrangler.jsonc",
+    environment: ENV["CLOUDFLARE_ENV"],
+    project_root: __dir__,
+  )
+end
+```
+
+Place this require in build_config.rb, after PicoRuby has loaded its build system.
+`cloudflare_worker!` configures Emscripten, Wasm longjmp, the Worker HAL, PicoRuby, Rack, and the required core mrbgems.
+Add frameworks such as Sinatra in your application configuration. ABI-specific final link settings, such as JSPI exports, belong to the runtime library.
+Set the attributes in the `cloudflare_worker!` block. It receives the CrossBuild object itself and runs before validation and build setup.
+Calling without a block is also supported; in that case, set any overrides beforehand. The `!` marks its changes to the build configuration.
+Both directory attributes default to `nil`; in that case the gem is declared with `github:` and `checksum_hash:` using its revision attribute.
+A directory takes precedence over its revision, and relative directory paths are resolved against the build_config directory.
+Revision attributes default to the values bundled in this gem; assigning `nil` restores those defaults.
+Dependency source selection no longer reads `PICORUBY_WORKER_WASM_GEM_DIR` or `MRUBY_RACK_GEM_DIR`, or accepts `worker:` / `rack:` arguments.
+
+The default Worker revision is pinned to `e6235bca616dbd4cec619cc0141facdea59a5541`,
+and Rack to `05ba46eb0ab490a624a5f2dcb33249670933ff6b`.
+Use a local checkout if a revision has not been published to the remote repository. Before publishing this gem, verify that a fresh checkout can fetch the pinned revisions.
+
+Relative paths passed to `worker_export` are resolved against `project_root`, which defaults to the build_config directory.
+The generated Rakefile runs PicoRuby's Rake in a separate process and keeps build output in the application's `.picoruby-build/` directory.
+The application is compiled with the `mrbcfile` resolved by CrossBuild, without relying on an existing `build/host/bin/mrbc`.
+
+## ES module output and responsibilities
+
+```text
+generated/worker/
+  app.bin
+  bindings.js
+  package.json            # private: true, type: module
+  manifest.json           # Generator version, Worker revision, artifact SHA256 hashes
+  runtime/
+    index.js              # createWorker({ app, bindingTypes })
+    runtime.js
+    host-bridge.js
+    picoruby-worker.js
+    picoruby-worker.wasm
+  tools/                  # Binding registry generation scripts
+```
+
+The runtime library owns the Ruby/C code, HAL, and shared JS bridge. This gem owns the templates, CrossBuild DSL, export logic, and thin createWorker entry point.
+Shared JS and registry generation scripts are copied from **the same mrbgem checkout** used to build Wasm.
+Their current locations are `spike/src/` and `spike/scripts/`. This gem does not maintain a separate copy of those implementations.
+If that layout changes, update the exporter and pinned revision together.
+
+`createWorker` creates and closes a VM for each request, without sharing env between requests.
+The low-level `createRuntime` / `dispatch` / `closeRuntime` functions are also re-exported.
+If you explicitly reuse a VM, the runtime library serializes dispatches to that VM.
+The output is intended to be bundled with Wrangler; it does not make `.wasm` / `.bin` imports directly usable in Node.js.
+Check the license requirements of the original mrbgems and any additional dependencies before redistributing artifacts.
+
+Rake dependencies determine when to recompile the application, and export leaves files unchanged when their content is identical.
+The registry is validated and generated on every build to reflect environment changes. A missing Wasm file in the original build output also triggers relinking.
+However, the tested PicoRuby version rewrites src/version.c on every build, so that file is recompiled and the runtime is relinked even when nothing else has changed.
+
+## Bindings, environments, and Wrangler
+
+The type registry is generated from `kv_namespaces` / `queues.producers` in wrangler.jsonc.
+JSONC comments and trailing commas are supported. Invalid configuration, duplicate binding names, and nonexistent environments cause build errors.
+Variable values and secrets are not embedded in build artifacts.
+
+```ruby
+kv = Cloudflare::KV.from_env(env, "CACHE_KV")
+kv.put("key", "value", ttl: 60)
+value = env["cloudflare.env"].CACHE_KV.get("key")
+Cloudflare::Queue.from_env(env, "EVENTS").send("created")
+token = ENV["API_TOKEN"]
+```
+
+Queue sending currently supports UTF-8 strings only, matching the runtime API. Manage secrets through .dev.vars or `wrangler secret put`, and keep them out of Git.
+With `npm run dev` / `npm run deploy`, Wrangler's custom build runs Rake.
+`build.watch_dir` covers app.rb and build_config.rb. Update the watch list when adding Ruby files.
+
+```sh
+CLOUDFLARE_ENV=staging npm run dev
+CLOUDFLARE_ENV=staging npm run deploy
+```
+
+Selecting a named environment with only `--env staging` does not pass the environment name to the custom build.
+Make sure Wrangler and the exporter use the same `CLOUDFLARE_ENV` value.
+Define resource bindings for each environment; they are not inherited from the top-level configuration.
+
+## Tests and reproduction
+
+```sh
+bundle exec rake test
+
+PICORUBY_ROOT=/path/to/picoruby \
+PICORUBY_WORKER_WASM_GEM_DIR=/path/to/picoruby-cloudflare-worker-wasm \
+MRUBY_RACK_GEM_DIR=/path/to/mruby-rack \
+bundle exec rake test:integration
+```
+
+The mrbgem environment variables in this test command are inputs to the integration harness only.
+It writes explicit directory attributes into the generated build_config and clears those variables before invoking the build.
+
+Unit tests cover the CLI, overwrite protection, path validation, DSL, compiler selection, incremental export, missing-Wasm recovery, and preservation of bytecode after compilation failures.
+Integration tests cover project generation, dependency installation, builds, Wrangler dry-run, local HTTP and hot reload, ENV/KV TTL/Queue through actual Wasm,
+env isolation between concurrent requests, environment switching, and missing-Wasm recovery.
+Integration tests require a Node.js version with JSPI support. They do not deploy Workers or create Cloudflare resources.
+All artifacts and step-by-step logs are retained in the temporary directory printed by the test for troubleshooting.
+
+Tested with PicoRuby `33540f66d9aba633d4d3ebd6707d5c12baebb652`, the Worker/Rack revisions above,
+Ruby 4.0.5, Emscripten 5.0.7 and Homebrew Emscripten 6.0.9, Node.js 26.8.1, and Wrangler 4.125.0.
+The compatibility date is `2026-08-22`, tested with the pinned Wrangler version.
+A dry-run does not start workerd, so verify local HTTP responses when updating Wrangler or the compatibility date.
+Rerun the integration tests when PicoRuby or the mruby submodule's build API changes.
+
+## License
+
+This gem is available under the [MIT License](LICENSE).

data/exe/picoruby-cloudflare

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "picoruby/cloudflare/template/cli"
+exit Picoruby::Cloudflare::Template::CLI.run(ARGV)

data/lib/picoruby/cloudflare/build.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "template/exporter"
+
+unless defined?(MRuby::CrossBuild)
+  raise Picoruby::Cloudflare::Template::Error, "Require picoruby/cloudflare/build from a PicoRuby build_config.rb, after its build system is loaded"
+end
+
+module Picoruby::Cloudflare::Template
+  module CrossBuild
+    WORKER_REVISION = "e6235bca616dbd4cec619cc0141facdea59a5541".freeze
+    RACK_REVISION = "05ba46eb0ab490a624a5f2dcb33249670933ff6b".freeze
+    CORE_GEMS = %w[mruby-array-ext mruby-catch mruby-class-ext mruby-enum-ext
+                   mruby-hash-ext mruby-kernel-ext mruby-metaprog mruby-method
+                   mruby-numeric-ext mruby-object-ext mruby-proc-ext mruby-sprintf
+                   mruby-string-ext mruby-struct mruby-regexp].freeze
+
+    attr_accessor :picoruby_cloudflare_worker_wasm_mgem_dir, :mruby_rack_mgem_dir
+    attr_writer :picoruby_cloudflare_worker_wasm_revision, :mruby_rack_mgem_revision
+
+    def picoruby_cloudflare_worker_wasm_revision
+      @picoruby_cloudflare_worker_wasm_revision.nil? ? WORKER_REVISION : @picoruby_cloudflare_worker_wasm_revision
+    end
+
+    def mruby_rack_mgem_revision
+      @mruby_rack_mgem_revision.nil? ? RACK_REVISION : @mruby_rack_mgem_revision
+    end
+
+    def cloudflare_worker!
+      yield self if block_given?
+      raise Error, "cloudflare_worker! may only be configured once per target" if @cloudflare_configured
+      Picoruby::Cloudflare::Template.validate_build_path!(MRUBY_ROOT)
+      Picoruby::Cloudflare::Template.validate_build_path!(build_dir)
+      worker = cloudflare_gem_source(picoruby_cloudflare_worker_wasm_mgem_dir,
+        "udzura/picoruby-cloudflare-worker-wasm", picoruby_cloudflare_worker_wasm_revision)
+      rack = cloudflare_gem_source(mruby_rack_mgem_dir, "udzura/mruby-rack", mruby_rack_mgem_revision)
+      @cloudflare_configured = true
+      toolchain :clang
+      cc.command = linker.command = "emcc"
+      archiver.command = "emar"
+      [cc, linker].each { _1.flags.concat(%w[-sSUPPORT_LONGJMP=wasm -sWASM_LEGACY_EXCEPTIONS=0]) }
+      cc.defines.concat(%w[PICORB_PLATFORM_WASM PICORB_PLATFORM_CLOUDFLARE_WORKERS MRB_32BIT MRB_INT64 MRB_NO_BOXING MRB_UTF8_STRING])
+      ports :worker_wasm
+      picoruby(alloc_estalloc: false)
+      core_dir = File.join(MRUBY_ROOT, "mrbgems/picoruby-mruby/lib/mruby/mrbgems")
+      CORE_GEMS.each { gem gemdir: File.join(core_dir, _1) }
+      gem(rack)
+      target = self
+      gem(worker) do |spec|
+        # This runs during gems.setup, after all build_config DSL calls and mrbc resolution.
+        target.send(:setup_cloudflare_export, spec)
+      end
+    end
+
+    def worker_export(app:, output_dir:, wrangler_config:, environment: nil, project_root: nil)
+      raise Error, "Call cloudflare_worker! before worker_export" unless @cloudflare_configured
+      raise Error, "worker_export may only be configured once per target" if @cloudflare_export
+      config = cloudflare_build_config
+      @cloudflare_export = {
+        app: app, output_dir: output_dir, wrangler_config: wrangler_config,
+        environment: environment, project_root: project_root || File.dirname(config), config: config,
+      }
+    end
+
+    private
+
+    def cloudflare_gem_source(gem_dir, github, revision)
+      if gem_dir
+        path = File.expand_path(gem_dir, File.dirname(cloudflare_build_config))
+        { gemdir: Picoruby::Cloudflare::Template.validate_build_path!(path) }
+      else
+        raise Error, "Revision for #{github} must be a nonempty String" unless revision.is_a?(String) && !revision.empty?
+        { github: github, checksum_hash: revision }
+      end
+    end
+
+    def cloudflare_build_config
+      File.expand_path(defined?(::MRUBY_CONFIG) ? ::MRUBY_CONFIG : ENV["MRUBY_CONFIG"] || ENV.fetch("CONFIG"))
+    end
+
+    def setup_cloudflare_export(spec)
+      Exporter.new(self, spec.dir, **@cloudflare_export).define_tasks if @cloudflare_export
+    end
+  end
+end
+
+MRuby::CrossBuild.include(Picoruby::Cloudflare::Template::CrossBuild)

data/lib/picoruby/cloudflare/template/cli.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "generator"
+require_relative "project"
+
+module Picoruby::Cloudflare::Template
+  class CLI
+    HELP = <<~TEXT.freeze
+      Usage: picoruby-cloudflare COMMAND [OPTIONS]
+
+      Commands:
+        new PATH          Generate a PicoRuby Cloudflare Worker project
+        doctor [PROJECT]  Check local Worker build prerequisites (default: current directory)
+
+      Options:
+        -h, --help        Show this help
+
+      Run `picoruby-cloudflare new --help` for project generation options.
+    TEXT
+
+    def self.run(argv, out: $stdout, err: $stderr)
+      argv = argv.dup
+      command = argv.shift
+      if command.nil? || command == "-h" || command == "--help"
+        out.puts HELP
+        return 0
+      end
+
+      options = {}
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: picoruby-cloudflare new PATH [--name NAME] [--gem-path PATH]\n       picoruby-cloudflare doctor [PROJECT]"
+        opts.on("--name NAME", "Worker name (defaults to directory name)") { options[:name] = _1 }
+        opts.on("--gem-path PATH", "Use an unpublished local template gem") { options[:gem_path] = _1 }
+      end
+      parser.parse!(argv)
+      case command
+      when "new"
+        raise Error, parser.to_s unless argv.length == 1
+        path = Generator.new(argv.first, **options).generate
+        out.puts "Created #{path}\nNext: cd #{path}\n  # On macOS: brew install emscripten (see README for PATH setup)\n  bundle install\n  npm install\n  # Set PICORUBY_ROOT, then:\n  bundle exec rake doctor\n  npm run dev"
+      when "doctor"
+        raise Error, parser.to_s unless argv.length <= 1 && options.empty?
+        Project.new(root: argv.first || Dir.pwd).doctor(out: out)
+      else
+        raise Error, parser.to_s
+      end
+      0
+    rescue Error, OptionParser::ParseError => e
+      err.puts e.message
+      1
+    end
+  end
+end

data/lib/picoruby/cloudflare/template/exporter.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "open3"
+require "rake"
+require "tempfile"
+require_relative "../template"
+
+module Picoruby::Cloudflare::Template
+  class Exporter
+    include Rake::DSL
+
+    def initialize(build, gem_dir, app:, output_dir:, wrangler_config:, project_root:, config:, environment: nil)
+      @build = build
+      @gem_dir = gem_dir
+      @root = File.expand_path(project_root)
+      @app = File.expand_path(app, @root)
+      @output = File.expand_path(output_dir, @root)
+      @wrangler = File.expand_path(wrangler_config, @root)
+      @config = config
+      @environment = environment
+      unless @output.start_with?("#{@root}/") && !@output.delete_prefix("#{@root}/").split("/").include?("node_modules")
+        raise Error, "output_dir must be a subdirectory of the project, outside node_modules"
+      end
+      raise Error, "app must be outside output_dir" if @app.start_with?("#{@output}/")
+    end
+
+    def define_tasks
+      Picoruby::Cloudflare::Template.validate_build_path!(@gem_dir)
+      check_assets!
+      verify_emscripten!
+      bytecode = File.join(@output, "app.bin")
+      check_output_path!(bytecode)
+      file bytecode => [@app, @build.mrbcfile, @config, __FILE__] do
+        check_output_path!(bytecode)
+        FileUtils.mkdir_p(@output)
+        Tempfile.create(["app", ".bin"], @output) do |temp|
+          temp.close
+          sh @build.mrbcfile, "-o#{temp.path}", @app
+          File.rename(temp.path, bytecode)
+        end
+      end
+      runtime_js = File.join(@build.build_dir, "bin/picoruby-worker.js")
+      runtime_wasm = File.join(@build.build_dir, "bin/picoruby-worker.wasm")
+      # The current mrbgem emits Wasm as a side effect of linking JS. Repair a
+      # missing side output without using old artifacts or deleting the build.
+      file runtime_wasm => runtime_js do
+        Rake::Task[runtime_js].execute unless File.file?(runtime_wasm)
+        raise Error, "Linker did not produce #{runtime_wasm}" unless File.file?(runtime_wasm)
+      end
+      prepare = "cloudflare:prepare:#{@build.name}"
+      task prepare => [runtime_js, runtime_wasm, bytecode]
+      manifest = File.join(@output, "manifest.json")
+      # The task prerequisite deliberately runs export on every build: environment
+      # selection is not a file timestamp. All writes are content-aware.
+      file manifest => prepare do
+        export(runtime_js, runtime_wasm)
+      end
+      @build.products << manifest
+    end
+
+    def export(runtime_js, runtime_wasm)
+      %w[runtime.js host-bridge.js].each do |name|
+        write(File.join("runtime", name), File.binread(File.join(@gem_dir, "spike/src", name)))
+      end
+      write("runtime/picoruby-worker.js", File.binread(runtime_js))
+      write("runtime/picoruby-worker.wasm", File.binread(runtime_wasm))
+      # Keep parser and runtime from the same mrbgem checkout. Scripts are copied
+      # below the project so Node resolves its jsonc-parser dependency there.
+      %w[cloudflare-binding-registry.mjs generate-bindings.mjs].each do |name|
+        write(File.join("tools", name), File.binread(File.join(@gem_dir, "spike/scripts", name)))
+      end
+      Tempfile.create(["bindings", ".js"], @output) do |temp|
+        temp.close
+        args = ["node", File.join(@output, "tools/generate-bindings.mjs"), "--config", @wrangler, "--output", temp.path]
+        args.concat(["--env", @environment]) if @environment
+        output, status = Open3.capture2e(*args, chdir: @root)
+        raise Error, "Binding registry generation failed:\n#{output}" unless status.success?
+        write("bindings.js", File.binread(temp.path))
+      end
+      write("runtime/index.js", File.read(File.join(templates, "runtime/index.js")))
+      write("package.json", JSON.pretty_generate({ private: true, type: "module", exports: "./runtime/index.js" }) + "\n")
+      artifacts = %w[app.bin bindings.js package.json runtime/index.js runtime/runtime.js runtime/host-bridge.js runtime/picoruby-worker.js runtime/picoruby-worker.wasm]
+      write("manifest.json", JSON.pretty_generate({
+        format_version: 1, generator_version: VERSION, environment: @environment,
+        worker_revision: worker_revision,
+        sha256: artifacts.to_h { [_1, Digest::SHA256.file(File.join(@output, _1)).hexdigest] },
+      }) + "\n")
+    end
+
+    private
+
+    def templates
+      File.expand_path("../../../../templates", __dir__)
+    end
+
+    def check_assets!
+      %w[spike/src/runtime.js spike/src/host-bridge.js spike/scripts/cloudflare-binding-registry.mjs spike/scripts/generate-bindings.mjs].each do |path|
+        raise Error, "Worker mrbgem is missing export asset #{path}; use the documented runtime revision" unless File.file?(File.join(@gem_dir, path))
+      end
+    end
+
+    def verify_emscripten!
+      output, status = Open3.capture2e("emcc", "--version")
+      actual = output[/emcc.*? (\d+\.\d+\.\d+)/, 1]
+      raise Error, "Expected Emscripten >= 5.0.0, got #{actual || output.lines.first}; see README for brew install emscripten and PATH setup" unless status.success? && actual && actual.split('.').first.to_i >= 5
+    rescue Errno::ENOENT
+      raise Error, "emcc is not on PATH; on macOS, run brew install emscripten and add its bin directory to PATH (expected >= 5.0.0; see README)"
+    end
+
+    def worker_revision
+      output, status = Open3.capture2e("git", "-C", @gem_dir, "rev-parse", "HEAD")
+      status.success? ? output.strip : nil
+    end
+
+    def write(relative, content)
+      path = File.join(@output, relative)
+      check_output_path!(path)
+      return if File.file?(path) && File.binread(path) == content.b
+      FileUtils.mkdir_p(File.dirname(path))
+      Tempfile.create(["export", ".tmp"], File.dirname(path)) do |temp|
+        temp.binmode
+        temp.write(content)
+        temp.close
+        File.rename(temp.path, path)
+      end
+    end
+
+    def check_output_path!(path)
+      current = path
+      while current.start_with?("#{@root}/")
+        raise Error, "Refusing to export through a symlink: #{current}" if File.symlink?(current)
+        current = File.dirname(current)
+      end
+    end
+  end
+end

data/lib/picoruby/cloudflare/template/generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require_relative "../template"
+
+module Picoruby::Cloudflare::Template
+  class Generator
+    TEMPLATES = File.expand_path("../../../../templates", __dir__)
+
+    def initialize(destination, name: nil, gem_path: nil)
+      @destination = File.expand_path(destination)
+      @name = name || File.basename(@destination)
+      @gem_path = File.expand_path(gem_path) if gem_path
+      unless @name.match?(/\A[a-z0-9][a-z0-9-]{0,62}\z/)
+        raise Error, "Worker name must be 1–63 lowercase letters, digits or hyphens, starting with a letter or digit"
+      end
+      if @gem_path && !File.file?(File.join(@gem_path, "picoruby-cloudflare-template.gemspec"))
+        raise Error, "--gem-path must point to picoruby-cloudflare-template"
+      end
+    end
+
+    def generate
+      if File.exist?(@destination) || File.symlink?(@destination)
+        raise Error, "Destination already exists: #{@destination}; choose a new directory"
+      end
+      # Render everything before creating the project. Never overwrite an existing project.
+      files = Dir[File.join(TEMPLATES, "project", "**", "*.erb")].sort.to_h do |source|
+        relative = source.delete_prefix("#{TEMPLATES}/project/").delete_suffix(".erb")
+        relative = ".gitignore" if relative == "gitignore"
+        [relative, ERB.new(File.read(source), trim_mode: "-").result(binding)]
+      end
+      raise Error, "Project templates are missing from the installed gem" if files.empty?
+      FileUtils.mkdir_p(File.dirname(@destination))
+      Dir.mkdir(@destination)
+      files.each do |relative, content|
+        path = File.join(@destination, relative)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+      end
+      @destination
+    end
+  end
+end

data/lib/picoruby/cloudflare/template/project.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+require "rake"
+require_relative "../template"
+
+module Picoruby::Cloudflare::Template
+  class Project
+    include Rake::DSL
+    def initialize(root:)
+      @root = File.expand_path(root)
+    end
+
+    def picoruby_root
+      path = ENV["PICORUBY_ROOT"]
+      raise Error, "Set PICORUBY_ROOT to a PicoRuby checkout with initialized submodules" if path.nil? || path.empty?
+      Picoruby::Cloudflare::Template.validate_build_path!(@root)
+      Picoruby::Cloudflare::Template.validate_build_path!(File.expand_path(path, @root))
+    end
+
+    def doctor(out: $stdout)
+      root = picoruby_root
+      %w[Rakefile lib/picoruby/build.rb mrbgems/picoruby-mruby/lib/mruby/lib/mruby/build.rb mrbgems/mruby-compiler/lib/prism/include/prism.h].each do |file|
+        raise Error, "Missing #{file} in #{root}; initialize PicoRuby submodules" unless File.file?(File.join(root, file))
+      end
+      %w[emcc emar node].each do |command|
+        hint = command == "node" ? "install Node.js supported by Wrangler" : "on macOS, run brew install emscripten and add its bin directory to PATH (see README)"
+        output, status = Open3.capture2e(command, "--version")
+        raise Error, "#{command} is unavailable: #{output}; #{hint}" unless status.success?
+        out.puts output.lines.first
+      rescue Errno::ENOENT
+        raise Error, "#{command} is not on PATH; #{hint}"
+      end
+      _, status = Open3.capture2e("node", "-e", "require('jsonc-parser')", chdir: @root)
+      raise Error, "jsonc-parser is missing; run npm install in #{@root}" unless status.success?
+      out.puts "PicoRuby: #{root}\nReady (compiler version and runtime assets are checked during build)."
+      true
+    end
+
+    def build
+      config = File.join(@root, "build_config.rb")
+      raise Error, "Missing #{config}" unless File.file?(config)
+      root = picoruby_root
+      raise Error, "Missing PicoRuby Rakefile: #{root}" unless File.file?(File.join(root, "Rakefile"))
+      env = {
+        "MRUBY_CONFIG" => config, "CONFIG" => config,
+        "MRUBY_BUILD_DIR" => File.join(@root, ".picoruby-build"),
+      }
+      library = File.expand_path("../../..", __dir__)
+      command = [RbConfig.ruby, "-I", library, Gem.bin_path("rake", "rake"), "-f", File.join(root, "Rakefile"), "all"]
+      raise Error, "PicoRuby build failed" unless system(env, *command, chdir: root)
+    end
+
+    def define_tasks
+      desc "Build PicoRuby and export the Worker ES module"
+      task(:build) { build }
+      desc "Check local Worker build prerequisites"
+      task(:doctor) { doctor }
+      task default: :build
+    end
+  end
+end

data/lib/picoruby/cloudflare/template/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Picoruby
+  module Cloudflare
+    module Template
+      VERSION = "0.1.0.rc1"
+    end
+  end
+end

data/lib/picoruby/cloudflare/template.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "template/version"
+
+module Picoruby
+  module Cloudflare
+    module Template
+      class Error < StandardError; end
+
+      # The upstream mrbgem linker still interpolates build paths into a shell
+      # command. Reject whitespace and shell metacharacters before invoking it.
+      def self.validate_build_path!(path)
+        unless path.match?(%r{\A[A-Za-z0-9_./+\-]+\z})
+          raise Error, "Build paths must use ASCII letters, digits, /, _, ., + or - (upstream shell limitation): #{path}"
+        end
+        path
+      end
+    end
+  end
+end

data/sig/picoruby/cloudflare/template.rbs

@@ -0,0 +1,40 @@
+module Picoruby
+  module Cloudflare
+    module Template
+      VERSION: String
+      class Error < StandardError
+      end
+
+      def self.validate_build_path!: (String path) -> String
+
+      module CrossBuild
+        attr_accessor picoruby_cloudflare_worker_wasm_mgem_dir: String?
+        attr_accessor mruby_rack_mgem_dir: String?
+        attr_writer picoruby_cloudflare_worker_wasm_revision: String?
+        attr_writer mruby_rack_mgem_revision: String?
+        def picoruby_cloudflare_worker_wasm_revision: () -> String
+        def mruby_rack_mgem_revision: () -> String
+        def cloudflare_worker!: () ?{ (self) -> untyped } -> untyped
+        def worker_export: (app: String, output_dir: String, wrangler_config: String,
+                            ?environment: String?, ?project_root: String?) -> untyped
+      end
+
+      class Generator
+        def initialize: (String destination, ?name: String?, ?gem_path: String?) -> void
+        def generate: () -> String
+      end
+
+      class CLI
+        def self.run: (Array[String] argv, ?out: untyped, ?err: untyped) -> Integer
+      end
+
+      class Project
+        def initialize: (root: String) -> void
+        def picoruby_root: () -> String
+        def doctor: (?out: untyped) -> bool
+        def build: () -> void
+        def define_tasks: () -> untyped
+      end
+    end
+  end
+end

data/templates/project/Gemfile.erb

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem "picoruby-cloudflare-template", "~> <%= VERSION %>"<%= @gem_path ? ", path: #{@gem_path.dump}" : "" %>

data/templates/project/README.md.erb

@@ -0,0 +1,59 @@
+# <%= @name %>
+
+PicoRuby Rack application on Cloudflare Workers.
+
+1. Install Ruby >= 3.2 and Node.js (supported by Wrangler). On macOS, install Emscripten via Homebrew as shown below.
+2. Set `PICORUBY_ROOT` to a PicoRuby checkout with its submodules initialized.
+3. Run `bundle install` and `npm install`.
+4. Run `bundle exec rake doctor`, then `bundle exec rake`.
+5. Run `npm run dev`. Wrangler's custom build also runs Rake on startup and Ruby changes.
+
+```sh
+brew install emscripten
+export PATH="$(brew --prefix emscripten)/bin:$PATH"
+emcc --version
+```
+
+Emscripten 5.0.0 or later is accepted; 5.0.7 and Homebrew 6.0.9 are tested.
+Newer versions are accepted but not necessarily tested. If switching from emsdk,
+use a shell without `emsdk_env.sh` and unset `EMSDK`, `EM_CONFIG`, and `EM_CACHE`.
+
+The pinned Wrangler version is paired with compatibility date `2026-08-22`.
+Update and test them together; a dry-run alone does not start workerd.
+
+During development of the unpublished runtime, set these attributes in the
+`cloudflare_worker!` block in `build_config.rb`:
+
+```ruby
+conf.cloudflare_worker! do |cf|
+  cf.picoruby_cloudflare_worker_wasm_mgem_dir = "/path/to/picoruby-cloudflare-worker-wasm"
+  # Optional: use a local Rack checkout too.
+  cf.mruby_rack_mgem_dir = "/path/to/mruby-rack"
+end
+```
+
+The block receives the CrossBuild object itself and runs before build setup.
+Calling without a block is also supported. Both directory attributes default to `nil`, which selects GitHub sources at the
+revisions bundled in the template gem. Override those revisions in the same block using
+`cf.picoruby_cloudflare_worker_wasm_revision` and `cf.mruby_rack_mgem_revision`.
+Directory attributes take precedence over revision attributes; relative paths
+are resolved against `build_config.rb`. These sources are not selected through
+environment variables. See the template gem README for tested revisions.
+
+`build_config.rb` selects mrbgems and exports an ES module to `generated/worker/`.
+Do not edit generated files. The generated Wasm, JS and app bytecode are one unit;
+use Wrangler to bundle them, not a plain Node.js import of `src/index.js`.
+
+Configure bindings in `wrangler.jsonc`; the build regenerates `bindings.js`.
+Ruby can use `env["cloudflare.env"].CACHE_KV` or
+`Cloudflare::KV.from_env(env, "CACHE_KV")`, and similarly `Cloudflare::Queue.from_env`.
+String/JSON vars and secrets are accessible through Ruby `ENV`.
+
+Keep secrets in `.dev.vars` locally and use `npx wrangler secret put NAME` remotely.
+Never put them in `app.rb`, `build_config.rb` or committed config files.
+
+For named environments, set `CLOUDFLARE_ENV=staging npm run dev` (or `npm run deploy`)
+so Wrangler and the binding registry select the same environment. Do not select an
+environment using only `--env`; custom build processes need `CLOUDFLARE_ENV` too.
+
+Commit `Gemfile.lock` and `package-lock.json`. Deploy explicitly with `npm run deploy`.

data/templates/project/Rakefile.erb

@@ -0,0 +1,3 @@
+require "picoruby/cloudflare/template/project"
+
+Picoruby::Cloudflare::Template::Project.new(root: __dir__).define_tasks

data/templates/project/app.rb.erb

@@ -0,0 +1,10 @@
+class App
+  def self.call(env)
+    # env["cloudflare.env"].CACHE_KV and
+    # Cloudflare::KV.from_env(env, "CACHE_KV") refer to the same binding.
+    message = ENV["GREETING"] || "Hello from PicoRuby on Cloudflare!"
+    [200, { "content-type" => "text/plain; charset=utf-8" }, [message + "\n"]]
+  end
+end
+
+Rackup::Handler::CloudflareWorker.run(App)

data/templates/project/build_config.rb.erb

@@ -0,0 +1,22 @@
+require "picoruby/cloudflare/build"
+
+MRuby::CrossBuild.new("worker") do |conf|
+  conf.cloudflare_worker! do |cf|
+    # Optional overrides, applied before build setup:
+    # cf.picoruby_cloudflare_worker_wasm_mgem_dir = "vendor/picoruby-cloudflare-worker-wasm"
+    # cf.mruby_rack_mgem_dir = "vendor/mruby-rack"
+    # cf.picoruby_cloudflare_worker_wasm_revision = "<commit SHA>"
+    # cf.mruby_rack_mgem_revision = "<commit SHA>"
+  end
+
+  # Add application mrbgems here, for example:
+  # conf.gem gemdir: File.join(__dir__, "vendor/my-gem")
+
+  conf.worker_export(
+    app: "app.rb",
+    output_dir: "generated/worker",
+    wrangler_config: "wrangler.jsonc",
+    environment: ENV["CLOUDFLARE_ENV"],
+    project_root: __dir__,
+  )
+end

data/templates/project/gitignore.erb

@@ -0,0 +1,9 @@
+/.bundle/
+/.picoruby-build/
+/generated/
+/node_modules/
+/.wrangler/
+/.dev.vars
+/.dev.vars.*
+/.env
+/.env.*

data/templates/project/package.json.erb

@@ -0,0 +1,15 @@
+{
+  "name": "<%= @name %>",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "bundle exec rake build",
+    "generate:bindings": "bundle exec rake build",
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy"
+  },
+  "devDependencies": {
+    "jsonc-parser": "3.2.0",
+    "wrangler": "4.125.0"
+  }
+}

data/templates/project/src/index.js.erb

@@ -0,0 +1,5 @@
+import { createWorker } from "../generated/worker/runtime/index.js";
+import app from "../generated/worker/app.bin";
+import { cloudflareBindingTypes } from "../generated/worker/bindings.js";
+
+export default createWorker({ app, bindingTypes: cloudflareBindingTypes });

data/templates/project/wrangler.jsonc.erb

@@ -0,0 +1,18 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "<%= @name %>",
+  "main": "src/index.js",
+  "compatibility_date": "2026-08-22",
+  "build": {
+    "command": "bundle exec rake build",
+    "watch_dir": ["app.rb", "build_config.rb"]
+  },
+  "rules": [
+    { "type": "Data", "globs": ["**/*.bin"], "fallthrough": true }
+  ],
+  "vars": {
+    "GREETING": "Hello from PicoRuby on Cloudflare!"
+  }
+  // Add kv_namespaces / queues.producers here, then rebuild.
+  // Keep secrets out of this file; use .dev.vars and wrangler secret put.
+}

data/templates/runtime/index.js

@@ -0,0 +1,22 @@
+import createPicoRuby from "./picoruby-worker.js";
+import wasm from "./picoruby-worker.wasm";
+import { createCloudflareBindings, handleRequest, RequestBodyTooLargeError } from "./runtime.js";
+
+export function createWorker({ app, bindingTypes }) {
+  return {
+    async fetch(request, env) {
+      try {
+        return await handleRequest(createPicoRuby, wasm, app, request, createCloudflareBindings(env, bindingTypes));
+      } catch (error) {
+        // Do not log host error messages: upstream services may include secrets.
+        if (error instanceof RequestBodyTooLargeError) {
+          return new Response("Request body too large", { status: 413 });
+        }
+        console.error("PicoRuby Worker request failed");
+        return new Response("PicoRuby Worker runtime error", { status: 500 });
+      }
+    },
+  };
+}
+
+export { createCloudflareBindings, createRuntime, dispatch, closeRuntime } from "./runtime.js";

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: picoruby-cloudflare-template
+version: !ruby/object:Gem::Version
+  version: 0.1.0.rc1
+platform: ruby
+authors:
+- Uchio Kondo
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Generate Rack-based Cloudflare Worker projects and configure PicoRuby
+  cross builds. Export matching WebAssembly, ES modules, application bytecode, and
+  binding registries for Wrangler.
+email:
+- udzura@udzura.jp
+executables:
+- picoruby-cloudflare
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.ja.md
+- README.md
+- exe/picoruby-cloudflare
+- lib/picoruby/cloudflare/build.rb
+- lib/picoruby/cloudflare/template.rb
+- lib/picoruby/cloudflare/template/cli.rb
+- lib/picoruby/cloudflare/template/exporter.rb
+- lib/picoruby/cloudflare/template/generator.rb
+- lib/picoruby/cloudflare/template/project.rb
+- lib/picoruby/cloudflare/template/version.rb
+- sig/picoruby/cloudflare/template.rbs
+- templates/project/Gemfile.erb
+- templates/project/README.md.erb
+- templates/project/Rakefile.erb
+- templates/project/app.rb.erb
+- templates/project/build_config.rb.erb
+- templates/project/gitignore.erb
+- templates/project/package.json.erb
+- templates/project/src/index.js.erb
+- templates/project/wrangler.jsonc.erb
+- templates/runtime/index.js
+homepage: https://github.com/udzura/picoruby-cloudflare-template
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/udzura/picoruby-cloudflare-template/tree/main
+  documentation_uri: https://github.com/udzura/picoruby-cloudflare-template#readme
+  bug_tracker_uri: https://github.com/udzura/picoruby-cloudflare-template/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Generate and build PicoRuby applications for Cloudflare Workers
+test_files: []