picoruby-cloudflare-template 0.1.0.rc1 → 0.1.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0514b3333048a221efffa3fa803528f1c2aafac2c14b4f545cfb59484c67ac11
-  data.tar.gz: b5db10ca44c30093aee69c5675055432e89c2761ed70279d518104408fda9c1b
+  metadata.gz: c224b29b75ac222a183233c6af8022623d9530324e9028a76a1056278f07437b
+  data.tar.gz: a5199135545e2927b66465fb436e846260e3303587140f498c82d341f0f9ce0d
 SHA512:
-  metadata.gz: 7c0531c2e85494b47656f0b621de96bde954776951aa4ede77d8f0ce682ec8328cee3d220ffb6015002e0cbffb933326cc37292e37759b9672d36dd5cc572b77
-  data.tar.gz: e99ef3c75479ee721aa68698a72366a4d8b278385b5d663505bf8214636f5faced03e5cc5ad1cc1abad5f40d29db31df7fe7ada861ac190e362e9c98461b76f4
+  metadata.gz: db0e353a8dc1e2a0fddd8c8d82bd12ee605416d4b3bde95a0b536991bd4b33a9843a5d99364f865e4afc679b57fa2282cc5b1ec3d2fcce7e578b694a05e30cef
+  data.tar.gz: fafcf2e5bb8a86065991b0dc388ab9521729ae2a692f458734e824a66ac9a3748c46ab8ff28f6fbb83c87c7eed4caa85c3548c3ba35c5f8337717caac10c1918

data/README.ja.md

@@ -23,7 +23,7 @@ emsdkから切り替える場合は、`emsdk_env.sh`を読み込まないシェ
 
 ```sh
 bundle install
-bundle exec ruby exe/picoruby-cloudflare new ../my-worker --gem-path "$PWD"
+bundle exec ruby exe/picoruby-cloudflare new ../my-worker --bindings --gem-path "$PWD"
 cd ../my-worker
 bundle install
 npm install
@@ -42,17 +42,23 @@ PicoRubyはsubmodule初期化済みのチェックアウトを指定します。
 上流のシェルコマンド展開の制限により、ビルド用パスでは空白やシェル特殊文字を拒否します。
 
 配布gemを試す場合は `gem build picoruby-cloudflare-template.gemspec`、
-`gem install ./picoruby-cloudflare-template-0.1.0.rc1.gem` の後、
+`gem install ./picoruby-cloudflare-template-0.1.0.rc2.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` です。
+このリリース候補版を公開した後は `gem install picoruby-cloudflare-template --pre --version 0.1.0.rc2` でインストールできます。
+`VERSION` とRubyGemsのメタデータ上のバージョンは、どちらも `0.1.0.rc2` です。
 
 ## 生成物とビルド設定
 
-`new PATH [--name NAME] [--gem-path PATH]` はGemfile、Rakefile、build_config.rb、最小Rackアプリのapp.rb、
+`new PATH [--bindings] [--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はアプリ側でコミットしてください。
 
+`--bindings` を付けると、KV・Queue・Accessのユーザー情報取得例をapp.rbとwrangler.jsoncへ追加します。
+`/access` の例には `CF_ACCESS_TEAM` と `CF_Authorization` Cookieが必要です。
+同時に生成する `.picoruby-cloudflare-template.json` は、この2つの管理対象例のハッシュを記録します。
+今後対応bindingが増えた版では、`picoruby-cloudflare bindings PROJECT` を実行すると例を再生成できます。
+再生成は書き込み前に管理対象をすべて検査し、いずれかを編集済みなら何も変更せず停止します。その場合は手動で差分をマージしてください。
+
 ```ruby
 require "picoruby/cloudflare/build"
 
@@ -85,9 +91,10 @@ Sinatra等のフレームワークはアプリ側で追加します。ABI固有
 revision属性のデフォルトはこのgemに組み込まれた値です。`nil` を代入するとデフォルトに戻ります。
 取得先の選択で `PICORUBY_WORKER_WASM_GEM_DIR` / `MRUBY_RACK_GEM_DIR` は参照せず、`worker:` / `rack:` 引数も受け取りません。
 
-既定のWorker revisionは `e6235bca616dbd4cec619cc0141facdea59a5541`、
-Rackは `05ba46eb0ab490a624a5f2dcb33249670933ff6b` に固定しています。
-revisionがリモート未公開の場合はローカル指定が必要です。gem公開前に、新規チェックアウトから固定revisionを取得できることも確認してください。
+既定のWorker取得先は `67aaa676d8247beaf19cbbeaeecb78115e490529` に固定しています。
+Rackは `30802024e263a0dde1f3a8467e648a70625adfd4` に固定しています。
+再現可能な依存関係が必要な場合は、Worker revisionをタグまたはcommit SHAで上書きしてください。
+gem公開前には、新規チェックアウトから両方の固定取得先を取得できることを確認します。
 
 `worker_export` に渡す相対パスは `project_root` 基準（省略時はbuild_configのディレクトリ）です。
 生成されたRakefileはPicoRubyのRakeを別プロセスで実行し、ビルドをアプリ内の `.picoruby-build/` に分離します。
@@ -113,7 +120,7 @@ generated/worker/
 Ruby/C・HAL・共通JS bridgeは実行時ライブラリが、このgemはテンプレート・CrossBuild DSL・export処理・薄いcreateWorkerエントリを所有します。
 共通JSとregistry生成スクリプトは、Wasmをビルドした**同じmrbgemチェックアウト**からコピーします。
 現在の取得場所は `spike/src/` と `spike/scripts/` です。別コピーの実装をこのgemで管理しません。
-レイアウト変更時はexporterと固定revisionを一緒に更新します。
+レイアウト変更時はexporterと設定済みWorker refを一緒に更新します。
 
 `createWorker` はリクエストごとにVMを生成・破棄し、異なるリクエストのenvを共有しません。
 低レベルの `createRuntime` / `dispatch` / `closeRuntime` も再exportします。
@@ -140,6 +147,38 @@ token = ENV["API_TOKEN"]
 ```
 
 Queueは現行APIに合わせてUTF-8文字列送信のみです。secretは.dev.varsまたは `wrangler secret put` で管理し、Gitへ追加しないでください。
+
+AccessにはRackミドルウェア `Rack::Cloudflare::Access`（`Cloudflare::Access` の別名）を使います。
+
+```ruby
+app = Rack::Builder.new do
+  use Rack::Cloudflare::Access, team: "my-team"
+  run lambda { |env|
+    identity = env["cloudflare.identity"]
+    [200, { "content-type" => "text/plain" }, [identity.email]]
+  }
+end
+Rackup::Handler::CloudflareWorker.run(app)
+```
+
+`team:` を省略すると、リクエストのWorker環境から `CF_ACCESS_TEAM` を読みます。
+値は `<team>.cloudflareaccess.com` のteam部分です。
+AccessはHTTPのユーザー情報取得APIなので、KV・Queueのようなリソースbindingは不要です。
+ミドルウェアがCookieからidentityを取得・デコードし、`env["cloudflare.identity"]` に設定してから後続アプリを呼びます。
+identityには `email`・`user_uuid`・`raw_data` があります。
+`Cloudflare::Access.get_identity(token, team: "my-team")` で直接取得することもできます。
+HTTP処理には汎用の `Cloudflare.fetch(url, method:, headers:, body:)` を使い、
+`status`・`headers`・UTF-8の `body` を返します（最大1 MiB、タイムアウト10秒、リダイレクトなし）。
+JWT署名・アプリケーションのaudienceをローカル検証する機能は含みません。
+アプリをAccessで保護し、トークン検証は[Cloudflareの説明](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/application-token/)に従って行ってください。
+ミドルウェアはteam未設定・不正なら503、Cookieなし・不正・Accessの401/403なら401、
+通信・レスポンスの異常なら502を返し、後続アプリを呼びません。
+生成例では `/access` だけにミドルウェアを適用し、他のサンプル経路は公開のままです。
+
+Access対応はWorkerの `67aaa676d8247beaf19cbbeaeecb78115e490529` とmruby-rackの
+`30802024e263a0dde1f3a8467e648a70625adfd4` に反映済みで、このテンプレートは標準でそれらを使用します。
+ローカルmrbgem checkoutの指定は不要です。
+
 `npm run dev` / `npm run deploy` ではWranglerのcustom buildがRakeを実行します。
 `build.watch_dir` はapp.rbとbuild_config.rbです。Rubyファイルを増やしたときは監視対象も更新してください。
 

data/README.md

@@ -23,7 +23,7 @@ Then run the following from this repository:
 
 ```sh
 bundle install
-bundle exec ruby exe/picoruby-cloudflare new ../my-worker --gem-path "$PWD"
+bundle exec ruby exe/picoruby-cloudflare new ../my-worker --bindings --gem-path "$PWD"
 cd ../my-worker
 bundle install
 npm install
@@ -42,17 +42,23 @@ The build also checks that the Emscripten version is supported. Use a Node.js ve
 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
+`gem install ./picoruby-cloudflare-template-0.1.0.rc2.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`.
+After this release candidate is published, install it with `gem install picoruby-cloudflare-template --pre --version 0.1.0.rc2`.
+`VERSION` and the RubyGems metadata version are both `0.1.0.rc2`.
 
 ## 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,
+`new PATH [--bindings] [--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.
 
+Pass `--bindings` to include KV, Queue and Access identity examples in app.rb and wrangler.jsonc.
+The `/access` example requires `CF_ACCESS_TEAM` and a `CF_Authorization` cookie.
+The generated `.picoruby-cloudflare-template.json` records hashes of those two managed examples.
+Run `picoruby-cloudflare bindings PROJECT` with a future template version to refresh them as supported bindings expand.
+Regeneration checks every managed file before writing and changes nothing if either was edited; merge those changes manually instead.
+
 ```ruby
 require "picoruby/cloudflare/build"
 
@@ -85,9 +91,10 @@ A directory takes precedence over its revision, and relative directory paths are
 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.
+The default Worker source is pinned to `67aaa676d8247beaf19cbbeaeecb78115e490529`.
+Rack is pinned to `30802024e263a0dde1f3a8467e648a70625adfd4`.
+Override the Worker revision with a tag or commit SHA when a reproducible dependency is required.
+Before publishing this gem, verify that a fresh checkout can fetch both pinned sources.
 
 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.
@@ -113,7 +120,7 @@ generated/worker/
 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.
+If that layout changes, update the exporter and configured Worker ref 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.
@@ -140,6 +147,38 @@ 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.
+
+Access uses Rack middleware `Rack::Cloudflare::Access` (an alias of `Cloudflare::Access`):
+
+```ruby
+app = Rack::Builder.new do
+  use Rack::Cloudflare::Access, team: "my-team"
+  run lambda { |env|
+    identity = env["cloudflare.identity"]
+    [200, { "content-type" => "text/plain" }, [identity.email]]
+  }
+end
+Rackup::Handler::CloudflareWorker.run(app)
+```
+
+Omit `team:` to read `CF_ACCESS_TEAM` from the request's Worker environment.
+Use the prefix of `<team>.cloudflareaccess.com`, not the full URL.
+Access is an HTTP identity API, so it needs no KV/Queue-style resource binding.
+Before calling the application, the middleware reads the authorization cookie, fetches and decodes
+the identity, and stores an `AccessIdentity` (`email`, `user_uuid`, `raw_data`) in the Rack env.
+The helper `Cloudflare::Access.get_identity(token, team: "my-team")` is also available.
+It uses the generic `Cloudflare.fetch(url, method:, headers:, body:)` wrapper, which returns
+`status`, `headers` and a buffered UTF-8 `body` (up to 1 MiB, ten-second timeout, no redirects).
+Identity lookup does not locally validate JWT signatures or application audience. Protect the application with Access and validate
+tokens as described in the [Cloudflare documentation](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/application-token/).
+The middleware returns 503 for missing/invalid configuration, 401 for a missing/invalid cookie
+or an Access 401/403 response, and 502 for upstream/protocol failures, without calling the application.
+The generated example applies middleware only to `/access`; other example routes remain public.
+
+Access support is included in Worker commit `67aaa676d8247beaf19cbbeaeecb78115e490529` and mruby-rack commit
+`30802024e263a0dde1f3a8467e648a70625adfd4`, which this template uses by default.
+No local mrbgem checkout overrides are required.
+
 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.
 

data/lib/picoruby/cloudflare/build.rb

@@ -8,11 +8,11 @@ end
 
 module Picoruby::Cloudflare::Template
   module CrossBuild
-    WORKER_REVISION = "e6235bca616dbd4cec619cc0141facdea59a5541".freeze
-    RACK_REVISION = "05ba46eb0ab490a624a5f2dcb33249670933ff6b".freeze
+    WORKER_REVISION = "67aaa676d8247beaf19cbbeaeecb78115e490529".freeze
+    RACK_REVISION = "30802024e263a0dde1f3a8467e648a70625adfd4".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-numeric-ext mruby-object-ext mruby-pack 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

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

@@ -6,12 +6,17 @@ require_relative "project"
 
 module Picoruby::Cloudflare::Template
   class CLI
+    BOLD_GREEN = "\e[1;32m"
+    CYAN = "\e[36m"
+    RESET = "\e[0m"
+
     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)
+        new PATH [--bindings]  Generate a PicoRuby Cloudflare Worker project
+        bindings PROJECT      Add or refresh KV, Queue and Access examples
+        doctor [PROJECT]       Check local Worker build prerequisites (default: current directory)
 
       Options:
         -h, --help        Show this help
@@ -29,7 +34,8 @@ module Picoruby::Cloudflare::Template
 
       options = {}
       parser = OptionParser.new do |opts|
-        opts.banner = "Usage: picoruby-cloudflare new PATH [--name NAME] [--gem-path PATH]\n       picoruby-cloudflare doctor [PROJECT]"
+        opts.banner = "Usage: picoruby-cloudflare new PATH [--bindings] [--name NAME] [--gem-path PATH]\n       picoruby-cloudflare bindings PROJECT\n       picoruby-cloudflare doctor [PROJECT]"
+        opts.on("--bindings", "Generate KV, Queue and Access examples") { options[:bindings] = true }
         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
@@ -37,8 +43,28 @@ module Picoruby::Cloudflare::Template
       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"
+        destination = argv.first
+        path = Generator.new(destination, **options).generate do |file|
+          out.puts "    #{style("generate", BOLD_GREEN, out)}  #{File.join(destination, file)}"
+        end
+        out.puts "\nCreated #{path}\nNext:"
+        out.puts "  #{style("cd #{path}", CYAN, out)}"
+        out.puts "  # On macOS (see README for PATH setup):"
+        out.puts "  #{style("brew install emscripten", CYAN, out)}"
+        out.puts "  #{style("bundle install", CYAN, out)}"
+        out.puts "  #{style("npm install", CYAN, out)}"
+        out.puts "  # Set PICORUBY_ROOT, then:"
+        out.puts "  #{style("bundle exec rake doctor", CYAN, out)}"
+        out.puts "  #{style("npm run dev", CYAN, out)}"
+      when "bindings"
+        raise Error, parser.to_s unless argv.length == 1 && options.empty?
+        destination = argv.first
+        path = BindingsGenerator.new(destination).generate do |status, file|
+          out.puts "    #{style(status, BOLD_GREEN, out)}  #{File.join(destination, file)}"
+        end
+        out.puts "\nBindings ready in #{path}"
+        out.puts "  #{style("cd #{path}", CYAN, out)}"
+        out.puts "  #{style("bundle exec rake", CYAN, out)}"
       when "doctor"
         raise Error, parser.to_s unless argv.length <= 1 && options.empty?
         Project.new(root: argv.first || Dir.pwd).doctor(out: out)
@@ -50,5 +76,10 @@ module Picoruby::Cloudflare::Template
       err.puts e.message
       1
     end
+
+    def self.style(text, escape, out)
+      return text unless out.respond_to?(:tty?) && out.tty?
+      "#{escape}#{text}#{RESET}"
+    end
   end
 end

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

@@ -1,18 +1,25 @@
 # frozen_string_literal: true
 
 require "erb"
+require "digest"
 require "fileutils"
+require "json"
+require "tempfile"
 require_relative "../template"
 
 module Picoruby::Cloudflare::Template
   class Generator
     TEMPLATES = File.expand_path("../../../../templates", __dir__)
+    BINDINGS_MANIFEST = ".picoruby-cloudflare-template.json"
+    BINDINGS_FILES = %w[app.rb wrangler.jsonc].freeze
+    BINDINGS_FEATURES = %w[kv queue access].freeze
 
-    def initialize(destination, name: nil, gem_path: nil)
+    def initialize(destination, name: nil, gem_path: nil, bindings: false)
       @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/)
+      @bindings = bindings
+      unless @name.is_a?(String) && @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"))
@@ -25,11 +32,7 @@ module Picoruby::Cloudflare::Template
         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
+      files = rendered_files
       raise Error, "Project templates are missing from the installed gem" if files.empty?
       FileUtils.mkdir_p(File.dirname(@destination))
       Dir.mkdir(@destination)
@@ -37,8 +40,111 @@ module Picoruby::Cloudflare::Template
         path = File.join(@destination, relative)
         FileUtils.mkdir_p(File.dirname(path))
         File.write(path, content)
+        yield relative if block_given?
+      end
+      @destination
+    end
+
+    def rendered_files
+      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
+      if @bindings
+        hashes = BINDINGS_FILES.to_h { [_1, Digest::SHA256.hexdigest(files.fetch(_1))] }
+        files[BINDINGS_MANIFEST] = JSON.pretty_generate({
+          format_version: 1, generator_version: VERSION,
+          features: BINDINGS_FEATURES, files: hashes,
+        }) + "\n"
+      end
+      files
+    end
+  end
+
+  class BindingsGenerator
+    def initialize(destination)
+      @destination = File.expand_path(destination)
+    end
+
+    def generate
+      unless File.directory?(@destination) && !File.symlink?(@destination)
+        raise Error, "Bindings target must be an existing project directory: #{@destination}"
+      end
+      package = read_json("package.json", "Generated project package.json is missing or invalid")
+      name = package["name"]
+      desired = Generator.new(@destination, name: name, bindings: true).rendered_files
+      base = Generator.new(@destination, name: name).rendered_files
+      previous = load_manifest
+      changes = []
+      conflicts = []
+
+      Generator::BINDINGS_FILES.each do |relative|
+        path = File.join(@destination, relative)
+        current = read_regular_file(path, relative)
+        wanted = desired.fetch(relative)
+        previous_hash = previous&.dig("files", relative)
+        safe = current == wanted || Digest::SHA256.hexdigest(current) == previous_hash || (!previous && current == base.fetch(relative))
+        conflicts << relative unless safe
+        changes << [relative, wanted, current == wanted ? :identical : :update]
+      end
+      unless conflicts.empty?
+        raise Error, "Bindings regeneration conflicts with modified files: #{conflicts.join(', ')}; no files changed"
+      end
+
+      manifest = Generator::BINDINGS_MANIFEST
+      manifest_path = File.join(@destination, manifest)
+      current_manifest = File.file?(manifest_path) && !File.symlink?(manifest_path) ? File.binread(manifest_path) : nil
+      manifest_status = if current_manifest.nil?
+        :generate
+      elsif current_manifest == desired.fetch(manifest)
+        :identical
+      else
+        :update
+      end
+      changes << [manifest, desired.fetch(manifest), manifest_status]
+      changes.each do |relative, content, status|
+        write(relative, content) unless status == :identical
+        yield status, relative if block_given?
       end
       @destination
     end
+
+    private
+
+    def load_manifest
+      path = File.join(@destination, Generator::BINDINGS_MANIFEST)
+      raise Error, "Bindings manifest must be a regular file" if File.symlink?(path)
+      return unless File.exist?(path)
+      raise Error, "Bindings manifest must be a regular file" unless File.file?(path)
+      data = JSON.parse(File.read(path))
+      unless data["format_version"] == 1 && data["files"].is_a?(Hash)
+        raise Error, "Bindings manifest has an unsupported format"
+      end
+      data
+    rescue JSON::ParserError
+      raise Error, "Bindings manifest is invalid JSON"
+    end
+
+    def read_json(relative, message)
+      JSON.parse(read_regular_file(File.join(@destination, relative), relative))
+    rescue JSON::ParserError
+      raise Error, message
+    end
+
+    def read_regular_file(path, relative)
+      raise Error, "Generated project file is missing or unsafe: #{relative}" unless File.file?(path) && !File.symlink?(path)
+      File.binread(path)
+    end
+
+    def write(relative, content)
+      path = File.join(@destination, relative)
+      Tempfile.create(["bindings", ".tmp"], @destination) do |temp|
+        temp.binmode
+        temp.write(content)
+        temp.close
+        File.rename(temp.path, path)
+      end
+    end
   end
 end

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

@@ -3,7 +3,7 @@
 module Picoruby
   module Cloudflare
     module Template
-      VERSION = "0.1.0.rc1"
+      VERSION = "0.1.0.rc2"
     end
   end
 end

data/templates/project/README.md.erb

@@ -33,12 +33,12 @@ 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
+Calling without a block is also supported. Both directory attributes default to `nil`, which selects the GitHub sources
+configured by the template gem. Override those refs 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.
+environment variables. The Worker source is pinned by the template gem; see its README for the current revision.
 
 `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;
@@ -49,6 +49,25 @@ 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`.
 
+If this project was generated with `--bindings`, app.rb exposes `/kv`, `/queue` and `/access`
+examples and `.picoruby-cloudflare-template.json` tracks their generated state.
+Run `picoruby-cloudflare bindings .` with a newer template to refresh unedited
+binding examples. The command refuses to overwrite an edited app.rb or wrangler.jsonc.
+
+For `/access`, set `CF_ACCESS_TEAM` to your team name (not its URL) in Wrangler vars
+or .dev.vars, and send a `CF_Authorization` cookie issued by Access.
+`Rack::Cloudflare::Access.new(app, team: "my-team")` is Rack middleware.
+Omit `team:` to read `CF_ACCESS_TEAM` from the Worker environment.
+Before calling the app, it stores the decoded identity in `env["cloudflare.identity"]`,
+with `email`, `user_uuid` and `raw_data`. The generated example wraps only `/access`.
+The helper `Cloudflare::Access.get_identity(token, team: "my-team")` calls
+`Cloudflare.fetch` from Ruby. Missing/invalid configuration returns 503; missing/invalid
+cookies and Access 401/403 responses return 401; upstream/protocol failures return 502.
+Failures do not call the downstream app. This does not locally validate JWT signatures or audience.
+Protect your application with Access and follow Cloudflare's token validation guidance.
+The default Worker and mruby-rack revisions include Access, cookie parsing and
+middleware keyword forwarding. No local mrbgem checkout overrides are required.
+
 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.
 

data/templates/project/app.rb.erb

@@ -1,10 +1,41 @@
-class App
-  def self.call(env)
+app = lambda do |env|
+  begin
+<% if @bindings -%>
+    value = case env["PATH_INFO"]
+    when "/kv"
+      kv = Cloudflare::KV.from_env(env, "CACHE_KV")
+      kv.put("greeting", "Hello from Cloudflare KV!", ttl: 60)
+      kv.get("greeting")
+    when "/queue"
+      Cloudflare::Queue.from_env(env, "EVENTS").send("Hello from PicoRuby!")
+      "Message sent to Cloudflare Queue!"
+    when "/access"
+      identity = env["cloudflare.identity"]
+      identity.email || "Access identity has no email"
+    else
+      ENV["GREETING"] || "Hello from PicoRuby on Cloudflare!"
+    end
+    [200, { "content-type" => "text/plain; charset=utf-8" }, [value + "\n"]]
+<% else -%>
     # 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 -%>
+  rescue
+    [500, { "content-type" => "text/plain; charset=utf-8" }, ["Internal Server Error\n"]]
   end
 end
 
-Rackup::Handler::CloudflareWorker.run(App)
+<% if @bindings -%>
+# Apply Access middleware to the identity example.
+access_app = Rack::Builder.new do
+  use Rack::Cloudflare::Access
+  run app
+end
+Rackup::Handler::CloudflareWorker.run(lambda do |env|
+  env["PATH_INFO"] == "/access" ? access_app.call(env) : app.call(env)
+end)
+<% else -%>
+Rackup::Handler::CloudflareWorker.run(app)
+<% end -%>

data/templates/project/build_config.rb.erb

@@ -5,7 +5,7 @@ MRuby::CrossBuild.new("worker") do |conf|
     # 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.picoruby_cloudflare_worker_wasm_revision = "<git ref>"
     # cf.mruby_rack_mgem_revision = "<commit SHA>"
   end
 

data/templates/project/wrangler.jsonc.erb

@@ -10,9 +10,25 @@
   "rules": [
     { "type": "Data", "globs": ["**/*.bin"], "fallthrough": true }
   ],
+<% if @bindings -%>
+  "kv_namespaces": [
+    { "binding": "CACHE_KV" }
+  ],
+  "queues": {
+    "producers": [
+      { "binding": "EVENTS", "queue": "events" }
+    ]
+  },
+<% end -%>
   "vars": {
+<% if @bindings -%>
+    // Set your team name (the prefix of <team>.cloudflareaccess.com).
+    "CF_ACCESS_TEAM": "",
+<% end -%>
     "GREETING": "Hello from PicoRuby on Cloudflare!"
   }
+<% unless @bindings -%>
   // Add kv_namespaces / queues.producers here, then rebuild.
+<% end -%>
   // Keep secrets out of this file; use .dev.vars and wrangler secret put.
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: picoruby-cloudflare-template
 version: !ruby/object:Gem::Version
-  version: 0.1.0.rc1
+  version: 0.1.0.rc2
 platform: ruby
 authors:
 - Uchio Kondo