Generate manifest-backed assets in Amber V2 web apps

.github/ISSUE_TEMPLATE/release-checklist.md

@@ -24,6 +24,8 @@ assignees: []
 - [ ] Run `gh workflow run release.yml --repo amberframework/amber_cli --ref <branch> -f ref=<branch>`
 - [ ] Confirm `Build darwin-arm64` passed
 - [ ] Confirm `Build linux-x86_64` passed
+- [ ] Confirm `Build linux-arm64` passed
+- [ ] Record Windows x86-64 generated-app compile status (compatibility signal; not a beta gate)
 
 ## Publish
 
@@ -46,8 +48,11 @@ assignees: []
 - [ ] macOS binaries do not link to `openssl@1.1`
 - [ ] `amber new smoke_app --type web -y --no-deps`
 - [ ] Generated app pins the reviewed Amber version and ECR template
-- [ ] `shards install`, app specs, and app build pass
-- [ ] Built app starts and serves `/` plus `/css/app.css`
+- [ ] Generated app pins the reviewed Asset Pipeline revision; no placeholder pins remain
+- [ ] `shards install`, `amber assets build`, `amber assets check`, app specs, and app build pass
+- [ ] Built app serves `/` plus its manifest-rendered CSS, JavaScript, SVG, and favicon URLs
+- [ ] Fingerprinted responses prove SRI, MIME, immutable caching, `nosniff`, and gzip negotiation
+- [ ] CSS contains the rewritten fingerprinted image URL; no raw `public/css` or `public/js` entry remains
 
 ## Post Release
 

.github/workflows/build.yml

@@ -83,6 +83,7 @@ jobs:
         ! otool -L amber amber-lsp | grep -F 'openssl@1.1'
 
     - name: Smoke test generated Amber V2 web app
+      # Exercise the exact framework and asset releases emitted by the template.
       run: scripts/smoke_generated_web.sh ./amber
 
     - name: Upload build artifacts

.github/workflows/platform-compile.yml

@@ -27,6 +27,7 @@ jobs:
         run: crystal build src/amber_cli.cr --no-debug -o amber
 
       - name: Compile generated Amber V2 web app
+        # Exercise the exact framework and asset releases emitted by the template.
         run: scripts/smoke_generated_web.sh ./amber
 
   windows-x86-64:
@@ -57,4 +58,5 @@ jobs:
 
       - name: Compile generated Amber V2 web app
         shell: pwsh
+        # Exercise the exact framework and asset releases emitted by the template.
         run: scripts/smoke_generated_web.ps1 ./amber.exe

.github/workflows/release.yml

@@ -179,11 +179,3 @@ jobs:
         repository: amberframework/homebrew-amber_cli
         event-type: release-published
         client-payload: '{"version": "${{ github.event.release.tag_name }}"}'
-
-    - name: Dispatch to hyphen tap (homebrew-amber-cli)
-      uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4
-      with:
-        token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
-        repository: amberframework/homebrew-amber-cli
-        event-type: release-published
-        client-payload: '{"version": "${{ github.event.release.tag_name }}"}'

README.md

@@ -3,14 +3,15 @@
 [![GitHub release](https://img.shields.io/github/release/amberframework/amber_cli.svg)](https://github.com/amberframework/amber_cli/releases)
 [![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://amberframework.github.io/amber_cli/)
 
-Amber CLI is the standalone command-line companion for Amber V2. CLI `2.0.4`
-creates the supported Amber `2.0.0-beta.3` ECR web application and includes
+Amber CLI is the standalone command-line companion for Amber V2. CLI `2.0.5`
+creates the supported Amber `2.0.0-beta.4` ECR web application and includes
 development, generator, database, and LSP tooling.
 
 Amber V2 is a beta. The release-gated path is a web application on Apple
-Silicon macOS or x86_64 Linux. Linux ARM64 generated-app compilation is checked
-in CI; its first direct archive will ship with the next CLI release. See [Generator support](docs/GENERATOR_SUPPORT.md)
-before relying on authentication, API-resource, or native output.
+Silicon macOS, x86_64 Linux, or ARM64 Linux. Windows x86-64 generated-app
+compilation is checked in CI for compatibility, but Windows does not block this
+beta release. See [Generator support](docs/GENERATOR_SUPPORT.md) before relying
+on authentication, API-resource, or native output.
 
 ## Install
 
@@ -31,12 +32,12 @@ the `amber_cli` formula.
 
 ### Direct release archive
 
-CLI `2.0.4` publishes `darwin-arm64`, `linux-x86_64`, and `linux-arm64`
+CLI `2.0.5` publishes `darwin-arm64`, `linux-x86_64`, and `linux-arm64`
 archives. Windows x86-64 is compiled in CI but does not yet have a release
 archive.
 
 ```bash
-version=v2.0.4
+version=v2.0.5
 platform=darwin-arm64
 asset="amber_cli-${platform}.tar.gz"
 
@@ -56,21 +57,24 @@ command with `sudo` if `/usr/local/bin` is not writable.
 ```bash
 amber new my_app --type web
 cd my_app
+amber assets check
 crystal spec
 crystal build src/my_app.cr -o bin/my_app
 amber watch
 ```
 
-`amber new` installs shards by default; pass `--no-deps` when an offline or CI
-workflow needs to run `shards install` later. Open <http://127.0.0.1:3000> and
-<http://127.0.0.1:3000/css/app.css>.
+`amber new` installs shards by default and compiles the starter assets. Pass
+`--no-deps` when an offline or CI workflow needs to run `shards install` later.
+`amber watch` recompiles assets before the application whenever an ECR template
+or a file under `app/assets/` changes. Open <http://127.0.0.1:3000>.
 
 The web template is deliberately small:
 
-- Amber from `amberframework/amber`, pinned to `2.0.0-beta.3`
+- Amber from `amberframework/amber`, pinned to `2.0.0-beta.4`
 - ECR views (Slang and Kilt are not supported in Amber V2)
 - typed development, test, and production YAML
-- branded homepage, controller spec, and static CSS/JavaScript
+- branded homepage, controller spec, and fingerprinted CSS, JavaScript, SVG,
+  font, image, and general static-file support
 - a browser-native import map with a local JavaScript module entry point
 - Grant ORM, Micrate-powered migration commands, and the selected database driver
 - SQLite by default, so the first persisted feature needs no database server
@@ -79,6 +83,39 @@ The `-d pg|mysql|sqlite` option selects the generated driver, connection, and
 development/test URLs. SQLite is the default; PostgreSQL and MySQL expect their
 respective local servers or a `DATABASE_URL`.
 
+### Static assets: source versus generated output
+
+Write application-owned files in these directories:
+
+```text
+app/assets/
+├── stylesheets/  # CSS; starter entry: app.css
+├── javascript/   # browser modules; starter entry: app.js
+├── images/       # SVG, PNG, JPEG, WebP, AVIF, and icons
+├── fonts/        # WOFF, WOFF2, TTF, and OTF
+└── files/        # PDFs, web manifests, and other downloads
+```
+
+Run the compiler after an authored asset changes outside watch mode:
+
+```bash
+amber assets build
+amber assets check
+```
+
+The build fingerprints every file into `public/assets/`, rewrites local CSS and
+JavaScript references, writes SRI and response metadata to
+`public/assets/manifest.json`, and creates deterministic gzip siblings for
+compressible files. `public/assets/` is generated and gitignored; do not edit or
+commit it. Keep stable root files such as `public/robots.txt` in `public/`.
+
+In `src/views/layouts/application.ecr`, resolve authored logical names through
+`stylesheet_link_tag`, `javascript_importmap_tag`, `image_tag`, and
+`favicon_tag`. In CSS, references are relative to that CSS source file; for
+example, `app/assets/stylesheets/app.css` uses
+`url("../images/amber-crystal.svg")`. The compiler replaces that reference with
+the image's fingerprinted URL.
+
 Create the first complete resource and its database table:
 
 ```bash
@@ -102,6 +139,8 @@ SQL migration to `db/migrations/`, and the resource route to `config/routes.cr`.
 | `amber pipelines` | Supported | Inspect configured pipelines |
 | `amber generate` | Mixed | Model, scaffold, migration, and core generators supported; auth and API preview |
 | `amber database` | Supported | Apply, roll back, inspect, redo, and seed the generated database |
+| `amber assets build` | Supported | Fingerprint `app/assets/` into generated `public/assets/` output |
+| `amber assets check` | Supported | Verify manifest, bytes, integrity, MIME, and compressed output without changing it |
 | `amber new APP --type native` | Preview | Not part of the beta platform guarantee |
 | `amber setup:lsp` | Available | Configure the bundled diagnostics LSP |
 
@@ -136,7 +175,7 @@ The release archive includes `amber-lsp`. From an Amber project:
 amber setup:lsp
 ```
 
-See the [LSP setup guide](https://github.com/amberframework/amber/blob/v2.0.0-beta.3/docs/guides/lsp-setup.md).
+See the [LSP setup guide](https://github.com/amberframework/amber/blob/v2.0.0-beta.4/docs/guides/lsp-setup.md).
 
 ## Contributing
 

RELEASE_NOTES_V2.0.5.md

@@ -0,0 +1,49 @@
+# Amber CLI 2.0.5
+
+Amber CLI 2.0.5 makes production-safe static assets part of the same supported
+Amber V2 web-app path as Grant, Micrate, and SQLite. A fresh application starts
+with editable CSS, JavaScript, SVG, and font locations; a deterministic asset
+manifest; manifest-aware ECR helpers; and browser-correct production headers.
+
+## Start a complete web app
+
+```bash
+amber new pet_tracker --type web
+cd pet_tracker
+shards install
+amber assets check
+amber generate scaffold Pet name:string:required species:string:required adopted:bool
+amber database migrate
+crystal spec
+amber watch
+```
+
+Open <http://127.0.0.1:3000/> and <http://127.0.0.1:3000/pets>. The homepage
+uses the same Amber design language as the framework site and references
+fingerprinted files from `public/assets/manifest.json`.
+
+## What changed
+
+- Added `amber assets build` for deterministic fingerprinting and
+  `amber assets check` for strict release verification.
+- Moved authored browser files to `app/assets/`; generated files under
+  `public/assets/` are ignored and may be rebuilt at any time.
+- Rewrites local CSS URLs and JavaScript module references to their
+  fingerprinted image, font, stylesheet, and module targets.
+- Generates manifest-aware stylesheet, import-map, preload, image, and favicon
+  tags, including Subresource Integrity metadata where browsers support it.
+- Rebuilds assets before application compilation in `amber watch`, including
+  file additions, changes, and deletions.
+- Boots generated applications in Unix and Windows CI and requests the real
+  HTML, CSS, JavaScript, SVG, and compressed-asset paths instead of treating a
+  successful compile as sufficient evidence.
+- Publishes CLI archives for Apple Silicon macOS, x86_64 Linux, and ARM64 Linux;
+  Windows x86_64 remains a source-build path with a release-gated app smoke.
+- Replaces the native preview generator's old personal and feature branches
+  with the canonical Amber beta, released Asset Pipeline, and exact reviewed
+  dependency revisions. Its documented `make setup` now fails visibly when
+  dependencies cannot install instead of hiding the error.
+
+Grant, SQLite, Micrate migrations, and generated HTML resource CRUD remain the
+default persistence contract from CLI 2.0.4. Native applications,
+authentication generators, and generated APIs remain preview surfaces.

RELEASE_SETUP.md

@@ -13,13 +13,14 @@ A successful release means all of the following happen without manual file editi
 5. The tap explicitly dispatches its install validation after the bot pushes the
    formula. This is required because pushes made by `GITHUB_TOKEN` do not start
    push-triggered workflows.
-6. On Apple Silicon macOS and x86_64 Linux, that validation proves a clean
+6. On Apple Silicon macOS, x86_64 Linux, and ARM64 Linux, validation proves a clean
    machine can:
    - `brew install amberframework/amber_cli/amber_cli`
    - `brew test amber_cli`
    - create the ECR web template with `amber new smoke_app --type web`
-   - install shards, run specs, and build the generated app
-   - launch the built app and request `/` plus `/css/app.css`
+   - install shards, build and verify assets, run specs, and build the generated app
+   - launch the built app and request `/` plus its manifest-rendered
+     fingerprinted CSS, JavaScript, image, and favicon URLs
 
 The fully qualified Homebrew command trusts only the `amber_cli` formula under
 Homebrew's third-party tap trust model. Do not replace it with a separate
@@ -73,7 +74,9 @@ From the CLI repo:
 
 That should produce:
 
-- `dist/amber_cli-darwin-arm64.tar.gz` or `dist/amber_cli-linux-x86_64.tar.gz`
+- `dist/amber_cli-darwin-arm64.tar.gz`,
+  `dist/amber_cli-linux-x86_64.tar.gz`, or
+  `dist/amber_cli-linux-arm64.tar.gz`
 - matching `.sha256` output
 
 ### 3. Dry-run the GitHub build matrix
@@ -114,6 +117,7 @@ In `amberframework/amber_cli`, the release workflow must be green for:
 
 - `Build darwin-arm64`
 - `Build linux-x86_64`
+- `Build linux-arm64`
 - `Upload Release Assets`
 - `Notify Homebrew Tap`
 
@@ -138,12 +142,16 @@ brew test amber_cli
 amber new smoke_app --type web -y --no-deps
 cd smoke_app
 shards install
+amber assets build
+amber assets check
 crystal spec
 crystal build src/smoke_app.cr -o bin/smoke_app
 ```
 
-It then starts the built application and probes the homepage and generated CSS.
-The macOS job also rejects binaries linked to `openssl@1.1`.
+It then starts the built application and probes the homepage plus the
+manifest-rendered CSS, JavaScript, image, and favicon URLs. It verifies asset
+MIME types, immutable cache headers, SRI, and gzip negotiation. The macOS job
+also rejects binaries linked to `openssl@1.1`.
 
 ## Manual Recovery
 
@@ -164,8 +172,8 @@ If the release build fails before the tap update:
 ## Current Packaging Direction
 
 The Homebrew tap and matching release archives are the supported install paths
-for Apple Silicon macOS and x86_64 Linux today. Other operating systems and
-architectures remain preview or contributor build-from-source targets until
-they have published artifacts and the same end-to-end release gates.
+for Apple Silicon macOS, x86_64 Linux, and ARM64 Linux today. Windows x86-64 is
+compiled in CI as a compatibility check but does not gate this beta and does not
+yet have a release archive.
 
 For eventual `homebrew/core` inclusion, we should plan for a source-building formula and a clean `brew audit --new --formula amber_cli` story. The current tap keeps release onboarding fast, while the source-build path is the more likely route for upstream Homebrew acceptance.