boringbuilder 0.1.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e20e908005e1a14c27c241b1540be57b73b7fa20f4a79513a22ce9535149fce4
+  data.tar.gz: e7b7c17cf76c2fcc852dd03765c1002bb8c32a993d3aac87b0b0561ac8e7a382
+SHA512:
+  metadata.gz: 3950b539d458467b05b258bceb0d0e5a04f1c08fbb3dc1943db5f2750200c337694459090e5318334910be42f03495f260d134044e9a61fb4c6d4806bf4e5d9e
+  data.tar.gz: a7c8ee8d4b21afa7362c5f15846f943eff9ef1009c40b3860eae2802cddac826a25c6bd12e8c182468237378630cfbb0dbb53c2d9d5d6d6a020976ca37e20537

data/AGENTS.md

@@ -0,0 +1,38 @@
+# Working on BoringBuilder
+
+Read [SOUL.md](SOUL.md) and [STYLE.md](STYLE.md) before changing the product, code, or public language.
+
+## Product shape
+
+- BoringBuilder builds any application. Rails is the first-class convention over a shared Mise-powered foundation.
+- Hanami, Rack, and other Bundler applications share the built-in Ruby foundation.
+- Other workloads use the same Mise foundation from an ordinary Ruby recipe backed by Dagger. Ruby is the extension
+  language, not an application requirement.
+- Keep `boringbuilder build` conventional and `boringbuilder init` the small escape hatch.
+- Do not introduce a Dockerfile frontend, a build YAML language, or provider-specific behavior into the build graph.
+- Local and BoringCache caches use the same declared step paths. Local and BoringCache artifact exporters receive the
+  same normalized artifact.
+
+## Engineering habits
+
+- Write clear Ruby against the current development toolchain while preserving the support contract in the gemspec
+  and CI.
+- Keep the public surface small. Prefer a plain object or method over a new abstraction.
+- Treat commands, paths, build contexts, archives, registries, and credentials as security boundaries.
+- Never commit credentials, private source, local absolute paths, generated gems, dependency directories, or
+  application-specific integration details.
+- Keep documentation human, direct, and useful to someone building their first production artifact.
+- Add focused tests for behavior changes. Run `bin/ci` before committing.
+- Run the relevant live Dagger build when changing the build, cache, runtime, or export graph.
+- Inspect the built gem and the complete diff before release work.
+- Treat these as defaults with reasons, not substitutes for repository invariants, security boundaries, or evidence.
+
+## Product checks
+
+Before handing off a change, ask:
+
+1. Does the conventional Rails path remain simple?
+2. Can a non-Ruby application still express the same idea with a small recipe?
+3. Are local and shared caching behavior understandable?
+4. Can the result be exported or published without rebuilding it differently?
+5. Is the code pleasant for the next human—or agent—to read?

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0.alpha.1 - 2026-08-27
+
+- Reintroduce BoringBuilder as a Ruby gem backed by Dagger Ruby.
+- Add a convention-driven production Rails build.
+- Support Apple Container and Docker Dagger runners.
+- Support selective directory, tar, tar.zst, OCI, Docker, runtime-load, and registry-push outputs.
+- Add local and BoringCache Artifact exporter adapters with automatic shared publication.
+- Add cache-aware custom Dagger pipeline steps backed by local mounts and optional BoringCache persistence.
+- Add a shared Mise toolchain foundation and `boringbuilder init` scaffolds for Ruby, Node, Rust, Go, and generic
+  Dagger pipelines.
+- Add a Ruby API, CLI, Rails rake tasks, tests, CI, dependency auditing, and trusted RubyGems publishing.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BoringCache
+
+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.md

@@ -0,0 +1,131 @@
+# BoringBuilder
+
+[![CI](https://github.com/boringcache/builder/actions/workflows/ci.yml/badge.svg)](https://github.com/boringcache/builder/actions/workflows/ci.yml)
+
+BoringBuilder turns application source into deployable artifacts and container images with
+[Dagger](https://dagger.io). Rails is the first-class path, and every application can use the same
+[Mise-powered](https://mise.jdx.dev/) toolchain from a small
+[Dagger Ruby](https://github.com/boringcache/dagger_ruby) recipe. Local builds use Dagger's cache; shared builds use
+[BoringCache](https://boringcache.com) without changing the recipe.
+
+![Generate and build a Node application with BoringBuilder](.github/assets/boringbuilder-demo.gif)
+
+## Getting started
+
+BoringBuilder itself runs on Ruby, but the application being built does not need to. Dagger runs through
+[Apple Container](https://docs.dagger.io/reference/container-runtimes/apple-container/) on supported Macs,
+Docker on Linux or macOS, or an existing Dagger engine on a Linux VM.
+
+Install the builder and run it from an application root:
+
+```sh
+gem install boringbuilder --version "~> 0.1.0.alpha"
+boringbuilder doctor
+boringbuilder build
+```
+
+Rails and other Ruby applications can keep the builder in their bundle:
+
+```sh
+bundle add boringbuilder --version "~> 0.1.0.alpha"
+bundle exec boringbuilder build
+```
+
+The default build produces a zstd-compressed artifact with normalized archive metadata. Without shared credentials
+it is written under `dist/`. BoringBuilder automatically:
+
+1. loads `config/boringbuilder.rb` when present;
+2. runs its custom Dagger Ruby recipe for any application; or
+3. uses the built-in Mise-powered Ruby pipeline when a `Gemfile` is present.
+
+The built-in pipeline reads the Ruby toolchain from `mise.toml`, `.mise.toml`, `.tool-versions`, `.ruby-version`, or
+`Gemfile`, then `Gemfile.lock`. It installs the selected toolchain with Mise inside the Dagger build. Generated
+recipes use that same foundation for Node, Rust, Go, or any other tool available through Mise.
+
+A root `Gemfile` identifies a Ruby application. Rails receives asset, Bootsnap, entrypoint, and `/up` health-check
+conventions. Hanami, Rack, and `Procfile` applications receive production commands without pretending to be Rails.
+
+Non-Ruby applications provide the few commands that make their build distinctive; BoringBuilder does not guess a
+package manager or production output. Generate a detected Node, Rust, Go, Ruby, or generic starting point when
+needed:
+
+```sh
+boringbuilder init
+boringbuilder build
+```
+
+The generated Ruby stays small: `pipeline.mise` prepares the tools and source, while `pipeline.run` persists declared
+dependency caches locally or through BoringCache. Builds print clean, numbered application steps while Dagger's
+internal graph stays out of the way.
+
+See [Building applications](docs/building.md) for the generated recipes and the complete pipeline API.
+
+Command-line options remain explicit overrides:
+
+```sh
+boringbuilder build --runtime apple
+boringbuilder build --runtime docker --platform linux/arm64
+```
+
+Rails applications can also use the included task:
+
+```sh
+bin/rails boringbuilder:build
+```
+
+## Caching
+
+Every build uses the selected Dagger engine's local cache. When BoringCache credentials and a workspace are present,
+shared BoringCache entries replace the corresponding local mounts for Mise, Bundler, and declared custom pipeline
+caches across fresh engines and CI runners.
+
+See [Caching](docs/caching.md) for custom cached steps and restore-only builds.
+
+## Artifacts and images
+
+The default `tar.zst` output is intended for atomic filesystem deployers such as BoringDeploy. Without shared
+credentials it is written under `dist/`. With BoringCache save credentials it is published as a shared BoringCache
+Artifact instead; pass `--output` when a local copy is also wanted.
+
+The same build can produce or publish a container image:
+
+```sh
+boringbuilder build --output dist/app.tar.zst
+boringbuilder build --format oci --output dist/app.oci.tar
+boringbuilder build --format docker --output dist/app.docker.tar
+boringbuilder build --push ghcr.io/acme/app:latest
+```
+
+Application-specific filesystem layouts live in ordinary Ruby:
+
+```ruby
+# config/boringbuilder.rb
+BoringBuilder.configure do |config|
+  config.artifact.directory("/app", at: "/opt/my-app/current")
+end
+```
+
+See [Artifacts and images](docs/artifacts.md) for directory selection, OCI and Docker archives, registry publishing,
+and the Ruby API.
+
+## Documentation
+
+- [Building applications](docs/building.md)
+- [Artifacts and images](docs/artifacts.md)
+- [Caching](docs/caching.md)
+- [Project soul](SOUL.md)
+- [Code and writing style](STYLE.md)
+- [Agent guide](AGENTS.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+
+## Development
+
+```sh
+mise install
+bin/setup
+bin/ci
+```
+
+The checked-in toolchain is the development default. The gemspec and CI define the supported Ruby range.

data/SECURITY.md

@@ -0,0 +1,25 @@
+# Security
+
+## Supported versions
+
+Security fixes are applied to the latest published release. During the alpha, upgrade to the newest prerelease before
+reporting a problem.
+
+## Report a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Email
+[security@boringcache.com](mailto:security@boringcache.com) or use
+[GitHub private vulnerability reporting](https://github.com/boringcache/builder/security/advisories/new).
+
+Include the affected version, impact, reproduction steps, and any suggested mitigation. Do not include credentials,
+private source code, or registry tokens unless the maintainers provide a secure channel.
+
+## Build boundaries
+
+BoringBuilder sends the selected project context to a local Dagger Engine. `.gitignore` and the built-in source
+exclusions reduce accidental context, but users remain responsible for excluding secrets from the project and image.
+Registry authentication is handled by the selected runtime and Dagger; BoringBuilder does not accept credentials on
+the command line.
+
+`config/boringbuilder.rb` and files passed with `--config` are executable Ruby loaded on the host. Review recipes
+before building source you do not trust.

data/SOUL.md

@@ -0,0 +1,40 @@
+# The soul of BoringBuilder
+
+Building an application should feel calm.
+
+BoringBuilder exists for people who like the way Ruby and Rails make difficult work feel ordinary. They want a
+production build without learning another configuration language, maintaining a pile of shell scripts, or giving up
+control to a black box.
+
+The goal is the ease of a buildpack with the clarity of a program. Dagger provides the build graph. Ruby makes that
+graph readable. BoringBuilder adds strong conventions for the work most applications have in common.
+
+## What we believe
+
+- `boringbuilder build` should be enough for a conventional Rails application.
+- Rails is the first-class path, not the limit of the product.
+- Any application can own a small Ruby recipe when its build needs are different.
+- Mise should give every application the same predictable toolchain foundation without making developers think
+  about toolchain plumbing.
+- A build should produce the same useful result as a filesystem artifact, OCI image, or Docker image.
+- Caching should be automatic, close to the step that uses it, and easy to understand.
+- Local builds should stay local. Shared BoringCache credentials should make the same steps portable across fresh
+  machines and CI runners.
+- Secrets belong in secret channels, never command lines, images, archives, plans, or logs.
+
+## Our taste
+
+We prefer a small amount of ordinary Ruby over a large amount of YAML. We choose conventions that solve a real
+production build, then leave an honest extension point for applications that are different. We would rather add one
+clear method than invent a framework around a possibility.
+
+Errors should tell a tired person what happened and what to do next. Defaults should be safe. Generated files should
+be short enough to understand in one sitting. Public documentation should sound like one human helping another.
+
+## The human reason
+
+The human behind BoringBuilder was tired of build tooling asking people to choose between convenience and control.
+They should not have to. A build can be simple, programmatic, fast, repeatable, and owned by the application at the
+same time.
+
+That is the standard: Rails-shaped happiness, buildpack-shaped ease, and Dagger-shaped control.

data/STYLE.md

@@ -0,0 +1,33 @@
+# BoringBuilder style
+
+Code should feel like a clear explanation of the build it performs. These are defaults with reasons, not laws. When
+the code, security boundary, or user experience calls for something different, make that choice visible.
+
+## Ruby
+
+- Write ordinary, readable Ruby. Prefer a small object or method over a framework made for a possibility.
+- Arrange a class so its public story reads from top to bottom: class methods, public initialization and entry points,
+  supporting public methods, then private implementation.
+- Keep methods close to invocation order when that makes the flow easier to follow.
+- Prefer expanded conditionals when both branches matter. Use an early return near the start of a method when it
+  removes an exceptional or invalid case.
+- Reserve a bang method for a meaningful counterpart without a bang.
+- Follow RuboCop for mechanical style. The configuration is the executable baseline shared by editors and CI.
+
+## Product language
+
+- Describe BoringBuilder as an application builder. Rails is the first-class convention, not the boundary.
+- Lead with the command and the outcome. Explain Dagger, Mise, caching, or exporters only when they help someone make
+  the next decision.
+- Write errors and documentation for a tired human. Be direct, specific, and calm.
+
+## Changes
+
+- Find the closest existing shape before introducing a new one.
+- Keep provider details behind cache and exporter adapters. Keep build recipes ordinary Dagger Ruby over the shared
+  Mise foundation.
+- Surface invariants from CI, security policy, the gemspec, and public APIs; do not restate version promises in prose
+  where they can quietly go stale.
+- Test the behavior at its narrowest boundary, then run `bin/ci`. Changes to the Dagger graph also need a live build.
+- Before calling a change done, attack the diff: look for accidental complexity, secret exposure, private paths,
+  generated files, misleading examples, and behavior that was only mocked.

data/docs/artifacts.md

@@ -0,0 +1,106 @@
+# Artifacts and images
+
+BoringBuilder exports a directory, tar archive, reproducible zstd tar archive, OCI image archive, or Docker image
+archive. It can also publish artifacts to BoringCache, load an image into the selected runtime, or publish an image
+to a registry.
+
+## Export destinations
+
+The default exporter is automatic:
+
+- with a BoringCache save token and workspace, publish a shared BoringCache Artifact;
+- otherwise, write the artifact under `dist/`;
+- when `--output` is explicit, always keep that local copy as well.
+
+Override the destination when needed:
+
+```sh
+bundle exec boringbuilder build --exporter local
+bundle exec boringbuilder build --exporter boringcache --artifact-name web-production
+bundle exec boringbuilder build --json
+```
+
+The BoringCache exporter uploads directly from the Dagger graph and returns a ready Artifact ID. It does not stage
+the build through a host directory. Exporters are small Ruby adapters around the same normalized build asset, so a
+future repository backend does not change the build pipeline or artifact model.
+
+## Filesystem artifacts
+
+The default format is `tar.zst`. The built-in Ruby pipeline selects the application (`/rails` for Rails or `/app`
+for other Ruby applications), `/usr/local`, and `/mise`. A custom pipeline selects the complete container root
+unless the application narrows it.
+
+```sh
+bundle exec boringbuilder build --format directory --output dist/rootfs
+bundle exec boringbuilder build --format tar --output dist/app.tar
+bundle exec boringbuilder build --format tar.zst --output dist/app.tar.zst
+```
+
+A directory export replaces its destination. Archive exports replace the destination file.
+
+Tar exports normalize ordering, timestamps, and ownership so an unchanged build produces the same archive.
+
+Select or remap container paths with repeatable options:
+
+```sh
+bundle exec boringbuilder build \
+  --path /rails=/opt/my-app/current \
+  --path /usr/local/bundle=/opt/my-app/current/vendor/bundle \
+  --file /usr/local/bin/mise=/usr/local/bin/mise \
+  --host-path ../release-metadata=/opt/my-app/release-metadata \
+  --format tar.zst \
+  --output dist/my-app-snapshot.tar.zst
+```
+
+`--host-path` is explicit and requires a destination. It adds release metadata without widening the Docker build
+context.
+
+For a reusable layout, put the same choices in `config/boringbuilder.rb`:
+
+```ruby
+BoringBuilder.configure do |config|
+  config.artifact.directory("/rails", at: "/opt/my-app/current")
+  config.artifact.directory("/usr/local/bundle", at: "/opt/my-app/current/vendor/bundle")
+  config.artifact.file("/usr/local/bin/mise")
+  config.artifact.host_path("../release-metadata", at: "/opt/my-app/release-metadata")
+end
+```
+
+## Container images
+
+Create portable image archives:
+
+```sh
+bundle exec boringbuilder build --format oci --output dist/app.oci.tar
+bundle exec boringbuilder build --format docker --output dist/app.docker.tar
+```
+
+Load or publish the same built image:
+
+```sh
+bundle exec boringbuilder build --load my-app:latest
+bundle exec boringbuilder build --push ghcr.io/acme/my-app:latest
+```
+
+Pass `--output` as well when both a local archive and a loaded or published image are required. Registry credentials
+are owned by Dagger and the selected runtime; BoringBuilder does not accept them as command-line values.
+
+## Ruby API
+
+Applications and deployment tools can use the same configuration directly:
+
+```ruby
+result = BoringBuilder.build(
+  root: Rails.root,
+  runtime: :docker,
+  platform: "linux/arm64",
+  format: :tar_zst,
+  output: Rails.root.join("dist/app.tar.zst")
+) do |config|
+  config.artifact.directory("/rails", at: "/opt/my-app/current")
+  config.artifact.directory("/usr/local/bundle", at: "/opt/my-app/current/vendor/bundle")
+end
+
+puts result.path
+puts result.artifact_id
+```

data/docs/building.md

@@ -0,0 +1,175 @@
+# Building applications
+
+BoringBuilder resolves one production build for an application, then executes it through Dagger. Run commands from
+the application root unless a project directory is passed explicitly.
+
+```sh
+bundle exec boringbuilder build
+bundle exec boringbuilder build /path/to/application
+```
+
+## Build resolution
+
+BoringBuilder chooses one pipeline:
+
+1. the custom Dagger Ruby pipeline in `config/boringbuilder.rb`, when configured;
+2. otherwise, the built-in Ruby pipeline.
+
+An application recipe can also tune the built-in pipeline and define its artifact layout. Command-line options
+override those settings for a one-off build.
+
+```sh
+bundle exec boringbuilder build --config config/release.rb
+bundle exec boringbuilder build --no-config
+```
+
+Applications with `package.json` must provide a custom pipeline. BoringBuilder does not guess which JavaScript
+runtime or package manager an application uses.
+
+## Generate a recipe
+
+Run `init` when an application needs a custom pipeline or checked-in overrides:
+
+```sh
+boringbuilder init
+```
+
+BoringBuilder detects a conventional Ruby, Node, Rust, or Go project and writes `config/boringbuilder.rb`. An
+unrecognized project receives a small generic Dagger recipe. Select a starting point explicitly when detection is
+not enough:
+
+```sh
+boringbuilder init --template node
+boringbuilder init --template rust
+boringbuilder init --template go
+boringbuilder init --template generic
+```
+
+The generated file is ordinary Ruby using BoringBuilder's Mise toolchain, Dagger containers, and cache/export
+conventions. It is a starting point owned by the application, not generated state or a separate configuration
+language. Recipes execute as Ruby on the host, so review them before building source you do not trust. `init` refuses
+to replace an existing recipe; pass `--force` only when replacement is intentional.
+
+## Built-in Rails and Ruby pipeline
+
+The built-in pipeline:
+
+- reads the Ruby version from `mise.toml`, `.mise.toml`, `.tool-versions`, `.ruby-version`, `Gemfile`, or
+  `Gemfile.lock`;
+- installs the toolchain with Mise and locked production gems with separate persistent caches;
+- separates build packages from the runtime image;
+- places the application under a non-root user; and
+- leaves runtime secrets out of the image and exported artifact.
+
+`mise.toml` (or `.mise.toml`) is read from its `[tools]` section using the conventional exact string form:
+
+```toml
+[tools]
+ruby = "4.0.6"
+```
+
+The project file is copied into the build so its Ruby version and Mise settings are respected. The built-in path
+installs Ruby only; custom pipelines can install any additional tools. When no Mise file is present, BoringBuilder
+generates the minimal Ruby declaration from the other version sources.
+
+## Framework conventions
+
+A root `Gemfile` selects the Ruby builder. Rails applications are detected by `config/application.rb` and receive
+asset, Bootsnap, entrypoint, Thruster, port, and `/up` health-check conventions.
+
+Hanami applications are detected by `config/app.rb` and use the production Puma configuration when present. Rack
+applications are detected by `config.ru`. For any Ruby application, a `web:` entry in `Procfile` takes precedence.
+Applications without a detected process still build a complete artifact; set a command in the recipe when producing
+a directly runnable image:
+
+```ruby
+BoringBuilder.configure do |config|
+  config.command = %w[bundle exec sidekiq]
+  config.port = 3000
+end
+```
+
+Add application-specific Debian packages without replacing the built-in pipeline:
+
+```ruby
+BoringBuilder.configure do |config|
+  config.build_packages += %w[libsodium-dev]
+  config.runtime_packages += %w[libsodium23]
+  config.build_environment["REDIS_URL"] = "redis://127.0.0.1:6379/0"
+end
+```
+
+`build_environment` is for non-secret values needed while compiling. Use Dagger secrets in a custom pipeline for
+sensitive build inputs.
+
+Use a custom pipeline when the application needs JavaScript package installation, unusual system packages, a
+different operating-system foundation, or is not a Ruby application.
+
+## Mise-powered application pipeline
+
+For any application outside the built-in conventions, keep the build definition in Ruby. A recipe block receives a
+small pipeline object and returns the final Dagger container:
+
+```ruby
+# config/boringbuilder.rb
+BoringBuilder.configure do |config|
+  config.artifact.directory("/app/dist", at: "/app")
+
+  config.pipeline do |pipeline|
+    app = pipeline.mise(tools: { node: "24" }, workdir: "/app")
+
+    app = pipeline.run(
+      app,
+      %w[npm ci],
+      cache: "npm-downloads",
+      at: "/root/.npm/_cacache",
+      workdir: "/app",
+      name: "Install dependencies"
+    )
+
+    pipeline.exec(app, %w[npm run build], name: "Build application")
+  end
+end
+```
+
+`pipeline.mise` prepares the requested tools and application source in a Dagger container. Project versions in
+`mise.toml`, `.mise.toml`, or `.tool-versions` override recipe fallbacks, and `mise.lock` is respected when present.
+Any tool in the [Mise registry](https://mise.jdx.dev/registry.html) can use the same shape.
+
+`pipeline.run` persists the declared path in the local Dagger engine or through BoringCache when shared credentials
+are present. `pipeline.exec` runs an ordinary named command. Both execute as real Dagger boundaries and show the
+command's output beneath their numbered build step. Use a hash to cache several paths in one step. See
+[Caching](caching.md) for both modes.
+
+Both helpers return ordinary Dagger Ruby containers and use the same artifact and image exporters as the built-in
+build. `pipeline.container` remains available when an application needs a different foundation.
+
+## Container runtime
+
+`auto` prefers Apple Container on supported Apple silicon Macs and Docker elsewhere. A configured Dagger session can
+point at an engine on a Linux VM without changing the build. Select a local runtime explicitly in CI and other
+reproducible environments:
+
+```sh
+bundle exec boringbuilder doctor --runtime apple
+bundle exec boringbuilder build --runtime apple
+bundle exec boringbuilder build --runtime docker
+```
+
+Start Apple Container with `container system start`, or start the Docker daemon before selecting Docker. An existing
+Dagger session or custom runner is used without probing the host runtime.
+
+Dagger CLI and Engine versions must match the version required by Dagger Ruby. `boringbuilder doctor` checks that
+contract before a build; pointing a different CLI at the expected Engine image is not an equivalent setup.
+
+## Build options
+
+Target a deployment platform or inspect the resolved plan without building:
+
+```sh
+bundle exec boringbuilder build --platform linux/arm64
+bundle exec boringbuilder build --command "bundle exec puma -C config/puma.rb" --port 3000
+bundle exec boringbuilder build --dry-run
+```
+
+Run `bundle exec boringbuilder build --help` for the complete command reference.

data/docs/caching.md

@@ -0,0 +1,53 @@
+# Caching
+
+BoringBuilder has two cache paths. The build command and pipeline stay the same for both.
+
+## Local cache
+
+Without BoringCache credentials, Dagger stores its content-addressed build graph plus BoringBuilder's named cache
+mounts in the selected engine. Repeated builds on a persistent developer or CI engine reuse them automatically.
+
+This cache belongs to that Dagger engine. A fresh ephemeral runner starts cold unless it connects to a persistent
+Dagger engine or uses the shared mode below.
+
+## Shared cache with BoringCache
+
+Shared cache turns on when BoringBuilder finds both:
+
+- `BORINGCACHE_RESTORE_TOKEN` or `BORINGCACHE_SAVE_TOKEN`; and
+- `BORINGCACHE_DEFAULT_WORKSPACE`, `BORINGCACHE_WORKSPACE`, or a project `.boringcache.toml` with its workspace.
+
+The built-in Ruby pipeline then runs both `mise install` and `bundle install` through `boringcache run`. Tokens are
+Dagger secrets and are not written to the resulting image or artifact. A restore token without a save token selects
+read-only mode.
+
+BoringCache persists those directories across fresh engines and runners. When shared caching is enabled it owns the
+declared cache directories for that step; Dagger still reuses the rest of its local build graph. Selecting one owner
+avoids overlapping mount and restore semantics. Restore, command execution, and save all happen inside the Dagger
+container, with no host staging copy.
+
+## Custom application steps
+
+Custom application recipes use the same cache primitive as the built-in Mise and Bundler steps:
+
+```ruby
+app = pipeline.run(
+  app,
+  %w[bundle exec rake compile],
+  cache: {
+    "compile" => "/app/tmp/cache",
+    "downloads" => "/app/tmp/downloads"
+  },
+  name: "Compile application"
+)
+```
+
+Each hash key names a stable cache and each value is the directory visible to the command. With BoringCache
+credentials those names and paths are restored and saved remotely. Without credentials, Dagger mounts named local
+volumes at the same paths. Manual cache paths are removed after the command so dependency stores do not leak into
+an image or artifact; copy any required build output elsewhere inside the cached command. Pass the single-cache
+shorthand with `entry: "bundler"` (or another built-in/project entry) when BoringCache should use that existing
+entry definition.
+
+Cache persistence stays inside the Dagger step. Wrapping `boringbuilder build` with a host-side Docker or cache
+command cannot see Dagger's named cache volumes, so BoringBuilder intentionally has no Dockerfile frontend.

data/exe/boringbuilder

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "boringbuilder"
+
+exit BoringBuilder::CLI.start(ARGV)