# homura

Real Ruby + real Sinatra on Cloudflare Workers via Opal.

Repository: https://github.com/kazuph/homura
Live docs: https://homura.kazu-san.workers.dev/docs
Live llms.txt: https://homura.kazu-san.workers.dev/llms.txt
Live demo: https://homura.kazu-san.workers.dev

## Published gems

- opal-homura
  - Patched Opal fork for this stack.
  - Keep `require 'opal'`.

- homura-runtime
  - Core runtime, Rack adapter, Workers bindings, build pipeline.
  - Owns `cloudflare-workers-build`.

- sinatra-homura
  - Sinatra integration layer.
  - Owns `cloudflare-workers-new` and `cloudflare-workers-erb-compile`.
  - Includes JWT / Scheduled / Queue helpers.

- sequel-d1
  - Sequel adapter for Cloudflare D1.
  - Owns `cloudflare-workers-migrate`.

## Install order

1. opal-homura
2. homura-runtime
3. sinatra-homura
4. sequel-d1 (optional)

## Minimal Gemfile

```ruby
source 'https://rubygems.org'

gem 'opal-homura', '= 1.8.3.rc1', require: 'opal'
gem 'homura-runtime', '~> 0.1'
gem 'sinatra-homura', '~> 0.1'
gem 'sequel-d1', '~> 0.1' # optional
```

## Minimal flow

1. Create or scaffold a Sinatra app.
2. Build with `bundle exec cloudflare-workers-build`.
3. Set `wrangler.toml` `main = "build/worker.entrypoint.mjs"`.
4. Deploy with Wrangler.

## Minimal Sinatra + D1 example

```ruby
require 'sinatra/cloudflare_workers'
require 'sequel'

class App < Sinatra::Base
  get '/users' do
    db = Sequel.connect(adapter: :d1, d1: env['cloudflare.DB'])
    content_type 'application/json'
    db[:users].all.__await__.to_json
  end
end

run App
```

## Key docs

- /docs
- /docs/quick-start
- /docs/runtime
- /docs/sinatra
- /docs/sequel-d1
- /docs/architecture

## Important gotchas

- Prefer the published names `homura-runtime` and `sinatra-homura`. Older internal docs may still mention `cloudflare-workers-runtime` or `sinatra-cloudflare-workers`.
- In async Sinatra routes on this stack, `halt` / `throw :halt` is unsafe across async boundaries. Return a value or `[status, body]` instead.
- Workers bindings are exposed through Rack env keys such as `env['cloudflare.DB']`, `env['cloudflare.KV']`, `env['cloudflare.BUCKET']`, and `env['cloudflare.AI']`.
- `Sequel::Dataset#all` resolves asynchronously on Workers, so examples often need `.__await__`.

## Agent skill

Installable skill in this repo:

- skills/homura-workers-gems

Install examples:

```bash
gh skill install kazuph/homura homura-workers-gems --agent github-copilot --scope user
npx skills add kazuph/homura --skill homura-workers-gems -a claude-code
```