Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -178,3 +178,72 @@ jobs:
else
echo "No integration tests found, skipping..."
fi

# The app `amber new` generates (SQLite, Grant, asset_pipeline) links no
# regex engine, before and after a scaffold adds a Grant model. The stock
# tarballs link PCRE2 statically, so the check reads symbols as well as
# libraries, and a control program that uses Regex must show them.
generated-app-linkage:
name: Generated app links no PCRE2 on ${{ matrix.os }}
runs-on: ${{ matrix.os }}
needs: test
strategy:
fail-fast: false
matrix:
include:
- os: ubuntu-24.04
crystal_version: 1.22.2
crystal_tarball: crystal-1.22.2-1-linux-x86_64-bundled.tar.gz
crystal_sha256: 0dc5c3ff1b5710c3981e207a6241fc06cc28fadb6622d5fdb21999adf1ca2309
- os: macos-15
crystal_version: 1.22.2
crystal_tarball: crystal-1.22.2-1-darwin-universal.tar.gz
crystal_sha256: 9c73ddd00aa8c9bf9f8fdc5aebdde99a92a63c2e2539b8ad5f9b8a27813ddc6f

steps:
- name: Checkout code
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
persist-credentials: false

- name: Install the generated app's system libraries (Linux)
if: runner.os == 'Linux'
run: |
sudo apt-get update
sudo apt-get install -y libsqlite3-dev libyaml-dev libssl-dev libgmp-dev zlib1g-dev

- name: Install the generated app's system libraries (macOS)
if: runner.os == 'macOS'
run: brew install libyaml gmp

- name: Install Crystal ${{ matrix.crystal_version }} (sha256-verified)
env:
CRYSTAL_TARBALL: ${{ matrix.crystal_tarball }}
CRYSTAL_SHA256: ${{ matrix.crystal_sha256 }}
CRYSTAL_VERSION: ${{ matrix.crystal_version }}
run: |
set -euo pipefail
archive="$RUNNER_TEMP/$CRYSTAL_TARBALL"
curl -fsSL --retry 3 -o "$archive" \
"https://github.com/crystal-lang/crystal/releases/download/$CRYSTAL_VERSION/$CRYSTAL_TARBALL"
echo "$CRYSTAL_SHA256 $archive" | shasum -a 256 -c -
tar -xzf "$archive" -C "$RUNNER_TEMP"
crystal_root="$RUNNER_TEMP/crystal-$CRYSTAL_VERSION-1"
# The macOS tarball keeps shards only in embedded/bin, and Minecart runs shards
# for postinstall scripts. Each GITHUB_PATH line goes in front, so bin/ wins.
if [[ -d "$crystal_root/embedded/bin" ]]; then
echo "$crystal_root/embedded/bin" >> "$GITHUB_PATH"
fi
echo "$crystal_root/bin" >> "$GITHUB_PATH"

- name: Build pinned Minecart
run: scripts/install_pinned_minecart.sh

- name: Install dependencies
run: minecart install --frozen --skip-ai-docs

- name: Compile CLI
run: crystal build src/amber_cli.cr --no-debug -o amber

- name: Check what the generated app links
run: scripts/check_generated_app_linkage.sh ./amber "$RUNNER_TEMP/generated-app-linkage"
14 changes: 8 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
[![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.10`
creates the supported Amber `2.0.0-beta.10` ECR web application and includes
Amber CLI is the standalone command-line companion for Amber V2. CLI `2.0.11`
creates the supported Amber `2.0.0-beta.11` ECR web application and includes
development, generator, database, and LSP tooling. Its agent tooling also
works in plain Crystal apps and shards; see
[Agent tooling](#agent-tooling-for-any-crystal-project).
Expand Down Expand Up @@ -42,13 +42,13 @@ are selected by the installed core catalog, not pinned by this tap.

### Direct release archive

The CLI `2.0.10` release has `darwin-arm64`, `linux-x86_64`, and
The CLI `2.0.11` release has `darwin-arm64`, `linux-x86_64`, and
`linux-arm64` binary archives. A direct archive does not install Minecart or
the native dependencies, so Homebrew is the beginner path. Windows x86-64 has
no release archive.

```bash
version=v2.0.10
version=v2.0.11
platform=darwin-arm64
asset="amber_cli-${platform}.tar.gz"

Expand Down Expand Up @@ -90,13 +90,15 @@ 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.10` by commit
(`d775841a0af43bf512f1c9b704906fccdf8863f7`), with its checksum (`sha256-v2:e1099a4f7a25db316b2abdf80f999a2753a0fcc056834f3abe6d9b5a88ae945d`) checked in `shard.lock`
- Amber from `amberframework/amber`, pinned to `2.0.0-beta.11` by commit
(`f987f1bb19b789f8f14b000b6ee00ed496fe6cbb`), with its checksum (`sha256-v2:732bd8a19fed53e2e8ef0ee768dab03466abf502324d55de5f81961ac75456fa`) checked in `shard.lock`
- ECR views (Slang and Kilt are not supported in Amber V2)
- typed development, test, and production YAML
- 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 `v0.24.0` and asset_pipeline `v0.38.0`, pinned by commit and checked
in `shard.lock` the same way, so the built app links no PCRE2
- Grant ORM, Micrate-powered migration commands, and the selected database driver
- SQLite by default, so the first persisted feature needs no database server

Expand Down
2 changes: 1 addition & 1 deletion RELEASE_SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ Publishing the release triggers the automated flow:
3. package the tagged source and publish its archive and checksum

Before pushing the tap commit, download the published
`amber_cli-source-2.0.10.tar.gz` archive, verify its sidecar checksum, and compare
`amber_cli-source-2.0.11.tar.gz` archive, verify its sidecar checksum, and compare
its SHA-256 with `Formula/amber_cli.rb`. The CI-generated gzip archive can
have different bytes from a local archive of the same commit, so update the
formula to the published asset hash when they differ. Then run the tap smoke
Expand Down
8 changes: 4 additions & 4 deletions docs/BETA_WEB_APP.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Amber V2 Beta Web App

This guide is the consumer smoke test for Amber CLI `2.0.10` and Amber
`2.0.0-beta.10`. It is expected to pass on Apple Silicon macOS, x86_64 Linux,
This guide is the consumer smoke test for Amber CLI `2.0.11` and Amber
`2.0.0-beta.11`. It is expected to pass on Apple Silicon macOS, x86_64 Linux,
and ARM64 Linux. Windows x86-64 runs the complete generated-app smoke in CI. A
`shard.lock` written on Windows records different `sha256-v2:` values from one
written on macOS or Linux, so a team on both needs a lock for each.
Expand All @@ -14,7 +14,7 @@ minecart --version
amber --version
```

Crystal must be at least 1.20 and earlier than 2.0. Amber CLI must be 2.0.10 or
Crystal must be at least 1.20 and earlier than 2.0. Amber CLI must be 2.0.11 or
newer.

## 2. Generate the web app
Expand All @@ -35,7 +35,7 @@ grep -E '^(template|database|model):' .amber.yml
```

The dependency must be `amberframework/amber` at commit
`d775841a0af43bf512f1c9b704906fccdf8863f7` (`2.0.0-beta.10` on `v2-dev`); the
`f987f1bb19b789f8f14b000b6ee00ed496fe6cbb` (`v2.0.0-beta.11`); the
template must be `ecr`, the database must be `sqlite`, and the model layer must
be `grant`. `shard.yml` must include Grant and Asset Pipeline pinned by commit,
and no database driver shard unless you selected MySQL. Grant ships its own
Expand Down
24 changes: 15 additions & 9 deletions docs/ONBOARDING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This page takes a new developer from a bare machine to an Amber V2 app with
checksum-verified dependencies, and with editor and coding-assistant rules active
from the first edit. It covers Amber CLI 2.0.10, Amber 2.0.0-beta.10 and Minecart
from the first edit. It covers Amber CLI 2.0.11, Amber 2.0.0-beta.11 and Minecart
2025.11.25.9 on Apple Silicon macOS and Linux.

## What you get
Expand All @@ -13,7 +13,7 @@ from the first edit. It covers Amber CLI 2.0.10, Amber 2.0.0-beta.10 and Minecar
| `amber-lsp` | Language server, API lookup and rule checks | Same formula |
| `minecart` | Installs dependencies and verifies their checksums | Dependency of the formula |
| Crystal | Compiles the app | Dependency of the formula |
| Amber 2.0.0-beta.10 | The framework, its rule pack and its guides | Pinned in each new app |
| Amber 2.0.0-beta.11 | The framework, its rule pack and its guides | Pinned in each new app |
| Grant | The ORM and its tenancy rule pack | Pinned in each new app |
| Asset Pipeline | CSS, JavaScript and image assets | Pinned in each new app |
| micrate | Database migrations | Built into `amber database` |
Expand All @@ -36,8 +36,8 @@ HOMEBREW_NO_AUTO_UPDATE=1 brew install amberframework/amber_cli/amber_cli
Check the result:

```bash
amber --version # Amber CLI v2.0.10
amber-lsp --version # amber-lsp 1.0.0 (amber_cli 2.0.10, ...)
amber --version # Amber CLI v2.0.11
amber-lsp --version # amber-lsp 1.0.0 (amber_cli 2.0.11, ...)
minecart --version # Minecart 2025.11.25.9
```

Expand Down Expand Up @@ -185,18 +185,24 @@ end

## Upgrade an existing app

Pin the release's commit and move the lock:
Pin the release commits and move the lock:

```yaml
dependencies:
amber:
github: amberframework/amber
commit: d775841a0af43bf512f1c9b704906fccdf8863f7 # 2.0.0-beta.10 on v2-dev
commit: f987f1bb19b789f8f14b000b6ee00ed496fe6cbb # v2.0.0-beta.11
grant:
github: crimson-knight/grant
commit: 7bb4b9d45e74c490e6f3ad80cef8cc1cebd5b889 # v0.24.0
asset_pipeline:
github: amberframework/asset_pipeline
commit: 73c89c3417a5282d9ac4179b283bcc660b7f898a # v0.38.0
```

```bash
minecart update amber
grep -A3 '^ amber:' shard.lock # checksum: sha256-v2:e1099a4f7a25db316b2abdf80f999a2753a0fcc056834f3abe6d9b5a88ae945d
minecart update amber grant asset_pipeline
grep -A3 '^ amber:' shard.lock # checksum: sha256-v2:732bd8a19fed53e2e8ef0ee768dab03466abf502324d55de5f81961ac75456fa
amber setup:agent
```

Expand All @@ -205,4 +211,4 @@ notice about them. Minecart 2025.11.25.9 stops on a folder in `lib/` that
`shard.lock` does not pin, and names it. Remove that folder and install again.

Then read the
[beta.10 release notes](https://github.com/amberframework/amber/blob/v2.0.0-beta.10/RELEASE_NOTES_V2_BETA10.md).
[beta.11 release notes](https://github.com/amberframework/amber/blob/v2.0.0-beta.11/RELEASE_NOTES_V2_BETA11.md).
6 changes: 3 additions & 3 deletions docs/RELEASE_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@ Homebrew formula pins Amber and Minecart source archives and checksums.

## 1. Framework prerequisite

1. Confirm the published `v2.0.0-beta.10` prerelease has its source archive and
1. Confirm the published `v2.0.0-beta.11` prerelease has its source archive and
checksum and matches the generated app's exact framework pin.
2. Check the framework's migration and support-matrix links.

## 2. CLI release

1. Confirm `shard.yml` and `AmberCLI::VERSION` both say `2.0.10`.
1. Confirm `shard.yml` and `AmberCLI::VERSION` both say `2.0.11`.
2. Generate a web app and verify it pins the framework prerelease.
3. Verify the generated app pins the reviewed Asset Pipeline release exactly,
has a Minecart SHA-256 checksum for every dependency, and has assistant
Expand All @@ -27,7 +27,7 @@ Homebrew formula pins Amber and Minecart source archives and checksums.
7. Confirm the Windows x86-64 generated app passes its full CI smoke, including
launch and asset probes. This is a generated-app release gate, with no
Windows archive yet.
8. Tag `v2.0.10`, publish the release, and wait for the binary and source
8. Tag `v2.0.11`, publish the release, and wait for the binary and source
archives and checksum files to upload. Compare the published source archive
hash with the reviewed Homebrew formula before pushing the tap.

Expand Down
24 changes: 16 additions & 8 deletions scripts/check_beta_contract.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,30 @@ set -euo pipefail

shard_version="$(awk '/^version:/ { print $2; exit }' shard.yml)"
cli_version="$(sed -n 's/.*VERSION = "\([^"]*\)".*/\1/p' src/amber_cli.cr | head -1)"
test "$shard_version" = "2.0.10"
test "$shard_version" = "2.0.11"
test "$cli_version" = "$shard_version"

grep -F 'github: amberframework/amber' src/amber_cli/commands/new_command.cr
grep -F 'commit: #{AmberRelease::COMMIT} # #{AmberRelease::VERSION} on v2-dev' src/amber_cli/commands/new_command.cr
grep -F 'COMMIT = "d775841a0af43bf512f1c9b704906fccdf8863f7"' src/amber_cli/amber_release.cr
grep -F 'TREE = "e06f26daef02a30e91114b2c71224920e0c097de"' src/amber_cli/amber_release.cr
grep -F 'CHECKSUM = "sha256-v2:e1099a4f7a25db316b2abdf80f999a2753a0fcc056834f3abe6d9b5a88ae945d"' src/amber_cli/amber_release.cr
grep -F 'commit: #{AmberRelease::COMMIT} # v#{AmberRelease::VERSION}' src/amber_cli/commands/new_command.cr
grep -F 'COMMIT = "f987f1bb19b789f8f14b000b6ee00ed496fe6cbb"' src/amber_cli/amber_release.cr
grep -F 'TREE = "fc2433e6cf3b55fc779977cc70b1270c7910c920"' src/amber_cli/amber_release.cr
grep -F 'CHECKSUM = "sha256-v2:732bd8a19fed53e2e8ef0ee768dab03466abf502324d55de5f81961ac75456fa"' src/amber_cli/amber_release.cr
grep -F 'template: ecr' src/amber_cli/commands/new_command.cr
grep -F 'model: grant' src/amber_cli/commands/new_command.cr
grep -F 'database: #{database}' src/amber_cli/commands/new_command.cr
grep -F 'github: crimson-knight/grant' src/amber_cli/commands/new_command.cr
grep -F 'github: amberframework/asset_pipeline' src/amber_cli/commands/new_command.cr
grep -F 'commit: ac630a4c948080bf45e9b1e66451c48da9a69349 # 0.37.1' src/amber_cli/commands/new_command.cr
grep -F 'commit: #{GrantRelease::COMMIT} # v#{GrantRelease::VERSION}' src/amber_cli/commands/new_command.cr
grep -F 'commit: #{AssetPipelineRelease::COMMIT} # v#{AssetPipelineRelease::VERSION}' src/amber_cli/commands/new_command.cr
grep -F 'COMMIT = "7bb4b9d45e74c490e6f3ad80cef8cc1cebd5b889"' src/amber_cli/pinned_releases.cr
grep -F 'CHECKSUM = "sha256-v2:0c295bd9da92146c5482c63326adb402b24e33c152af86025a27f9da1a086f51"' src/amber_cli/pinned_releases.cr
grep -F 'COMMIT = "73c89c3417a5282d9ac4179b283bcc660b7f898a"' src/amber_cli/pinned_releases.cr
grep -F 'CHECKSUM = "sha256-v2:80ea8ac95943a3c5be438e68c2ef2f00d9b9783f0787fcd67ef346f135d9510c"' src/amber_cli/pinned_releases.cr
grep -F 'commit: 7bb4b9d45e74c490e6f3ad80cef8cc1cebd5b889 # v0.24.0' src/amber_cli/templates/app/shard.yml.ecr
grep -F 'github: amberframework/asset_pipeline' src/amber_cli/templates/app/shard.yml.ecr
grep -F 'commit: ac630a4c948080bf45e9b1e66451c48da9a69349 # 0.37.1' src/amber_cli/templates/app/shard.yml.ecr
grep -F 'commit: 73c89c3417a5282d9ac4179b283bcc660b7f898a # v0.38.0' src/amber_cli/templates/app/shard.yml.ecr
grep -F 'github: amberframework/amber' src/amber_cli/generators/native_app.cr
grep -F 'commit: d291e0930dd22b14a2d10f75a9de063abb0e64e4 # v2.0.0-beta.10' src/amber_cli/generators/native_app.cr
grep -F 'commit: f987f1bb19b789f8f14b000b6ee00ed496fe6cbb # v2.0.0-beta.11' src/amber_cli/generators/native_app.cr
grep -F 'version: ~> 0.37.1' src/amber_cli/generators/native_app.cr
if grep -F 'branch:' src/amber_cli/generators/native_app.cr; then
echo "native app template contains a mutable dependency branch" >&2
Expand All @@ -43,6 +49,8 @@ if grep -F '# schema = #{class_name}Schema.new(data)' src/amber_cli/commands/g
fi

grep -F 'scripts/smoke_generated_web.sh ./amber' .github/workflows/release.yml
test -x scripts/check_generated_app_linkage.sh
grep -F 'scripts/check_generated_app_linkage.sh ./amber' .github/workflows/ci.yml
if grep -R -F 'AMBER_CANDIDATE_FRAMEWORK' .github/workflows; then
echo "CI workflows must test the published framework emitted by the template" >&2
exit 1
Expand Down
Loading
Loading