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
2 changes: 1 addition & 1 deletion .github/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ This directory contains the GitHub Actions workflows for the Amber CLI project,
## Caching Strategy

The workflows use GitHub Actions caching to speed up builds:
- **Shard cache**: Caches `~/.cache/shards` and `./lib` based on `shard.lock` hash
- **Shard cache**: Caches `~/.cache/shards` based on `shard.lock` hash. `./lib` stays out of it, because Minecart stops on a shard in `lib/` that `shard.lock` does not pin, and an older cache can restore one
- **OS-specific**: Separate caches for each operating system

## Usage
Expand Down
1 change: 0 additions & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,6 @@ jobs:
with:
path: |
~/.cache/shards
./lib
key: ${{ runner.os }}-shards-${{ hashFiles('shard.lock') }}
restore-keys: |
${{ runner.os }}-shards-
Expand Down
2 changes: 0 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,6 @@ jobs:
with:
path: |
~/.cache/shards
./lib
key: ${{ runner.os }}-shards-${{ hashFiles('shard.lock') }}
restore-keys: |
${{ runner.os }}-shards-
Expand Down Expand Up @@ -124,7 +123,6 @@ jobs:
with:
path: |
~/.cache/shards
./lib
key: ${{ runner.os }}-shards-${{ hashFiles('shard.lock') }}
restore-keys: |
${{ runner.os }}-shards-
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,6 @@ Thumbs.db
/dist/

# The CLI is a distributed executable; commit shard.lock for reproducible builds.

# Lookup cache the specs write
.luna/
17 changes: 9 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,16 @@
[![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.9`
creates the supported Amber `2.0.0-beta.9` ECR web application and includes
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
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).

Amber V2 is a beta. The release-gated path is a web application on Apple
Silicon macOS, x86_64 Linux, or ARM64 Linux. Windows x86-64 passes the complete
generated-app smoke in CI, but has no release archive yet. See
generated-app smoke in CI, but has no release archive yet, and its `shard.lock`
checksums differ from those written on macOS and Linux. See
[Generator support](docs/GENERATOR_SUPPORT.md) before relying
on authentication, API-resource, or native output.

Expand Down Expand Up @@ -41,13 +42,13 @@ are selected by the installed core catalog, not pinned by this tap.

### Direct release archive

The CLI `2.0.9` release has `darwin-arm64`, `linux-x86_64`, and
The CLI `2.0.10` 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.9
version=v2.0.10
platform=darwin-arm64
asset="amber_cli-${platform}.tar.gz"

Expand Down Expand Up @@ -78,7 +79,7 @@ amber watch
```

`amber new` runs Minecart by default. It writes exact root dependency pins,
a `shard.lock` with Git tree checksums, `.minecart-policy.yml`, and `.claude/`
a `shard.lock` with SHA-256 checksums, `.minecart-policy.yml`, and `.claude/`
assistant files, plus each dependency's guides, then installs the Claude Code and Codex hooks and prints an
`amber doctor` summary. Commit the generated files. With `--no-deps`, the first
Minecart install and assistant setup are deliberately deferred; run `minecart
Expand All @@ -89,8 +90,8 @@ 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.9` by commit
(`34a93352eaa89501d24e2b9ff90b058209a22720`), with its git tree (`f1e7332d02229aec58ab5303ade7fc6c9d14fcee`) checked in `shard.lock`
- Amber from `amberframework/amber`, pinned to `2.0.0-beta.10` by commit
(`d291e0930dd22b14a2d10f75a9de063abb0e64e4`), with its checksum (`sha256-v2:8d354db3b41625db0362162a34836fe10a8b11a378f3837d34cc6bbcece1cb94`) 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,
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.9.tar.gz` archive, verify its sidecar checksum, and compare
`amber_cli-source-2.0.10.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
12 changes: 7 additions & 5 deletions docs/BETA_WEB_APP.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# Amber V2 Beta Web App

This guide is the consumer smoke test for Amber CLI `2.0.9` and Amber
`2.0.0-beta.9`. 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.
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,
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.

## 1. Verify the toolchain

Expand All @@ -12,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.9 or
Crystal must be at least 1.20 and earlier than 2.0. Amber CLI must be 2.0.10 or
newer.

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

The dependency must be `amberframework/amber` at commit
`34a93352eaa89501d24e2b9ff90b058209a22720` (`v2.0.0-beta.9`); the
`d291e0930dd22b14a2d10f75a9de063abb0e64e4` (`v2.0.0-beta.10`); the
template must be `ecr`, the database must be `sqlite`, and the model layer must
be `grant`. `shard.yml` must include Grant, Asset Pipeline, and
`crystal-sqlite3`, but it must not include Gemma, Slang, PostgreSQL, or MySQL
Expand Down
20 changes: 10 additions & 10 deletions docs/ONBOARDING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

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.9, Amber 2.0.0-beta.9 and Minecart
2025.11.25.8 on Apple Silicon macOS and Linux.
from the first edit. It covers Amber CLI 2.0.10, Amber 2.0.0-beta.10 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.9, Amber 2.0.0-beta.9 and Minecart
| `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.9 | The framework, its rule pack and its guides | Pinned in each new app |
| Amber 2.0.0-beta.10 | 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,9 +36,9 @@ HOMEBREW_NO_AUTO_UPDATE=1 brew install amberframework/amber_cli/amber_cli
Check the result:

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

### Optional: the Crystal Alpha compiler
Expand All @@ -61,7 +61,7 @@ cd my_app
amber doctor
```

`amber new` pins every dependency, writes a `shard.lock` with Git tree checksums,
`amber new` pins every dependency, writes a `shard.lock` with SHA-256 checksums,
installs the assistant guides and connects Claude Code and Codex to `amber-lsp`.
SQLite is the default database, and it needs no server. Pass `-d pg` or `-d mysql`
to choose another.
Expand Down Expand Up @@ -187,14 +187,14 @@ Pin the release's commit and move the lock:
dependencies:
amber:
github: amberframework/amber
commit: 34a93352eaa89501d24e2b9ff90b058209a22720 # v2.0.0-beta.9
commit: d291e0930dd22b14a2d10f75a9de063abb0e64e4 # v2.0.0-beta.10
```

```bash
minecart update amber
grep -A2 '^ amber:' shard.lock # checksum: git-tree:f1e7332d02229aec58ab5303ade7fc6c9d14fcee
grep -A2 '^ amber:' shard.lock # checksum: sha256-v2:8d354db3b41625db0362162a34836fe10a8b11a378f3837d34cc6bbcece1cb94
amber setup:agent
```

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

## 1. Framework prerequisite

1. Confirm the published `v2.0.0-beta.9` prerelease has its source archive and
1. Confirm the published `v2.0.0-beta.10` 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.9`.
1. Confirm `shard.yml` and `AmberCLI::VERSION` both say `2.0.10`.
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 Git tree checksum for every dependency, and has assistant
has a Minecart SHA-256 checksum for every dependency, and has assistant
files.
4. On macOS, x86-64 Linux, and ARM64 Linux, run `minecart install --frozen`; run
`amber assets build` and `amber assets check`; run app specs; build and start
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.9`, publish the release, and wait for the binary and source
8. Tag `v2.0.10`, 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
11 changes: 6 additions & 5 deletions scripts/check_beta_contract.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,14 @@ 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.9"
test "$shard_version" = "2.0.10"
test "$cli_version" = "$shard_version"

grep -F 'github: amberframework/amber' src/amber_cli/commands/new_command.cr
grep -F 'commit: 34a93352eaa89501d24e2b9ff90b058209a22720 # v2.0.0-beta.9' src/amber_cli/commands/new_command.cr
grep -F 'COMMIT = "34a93352eaa89501d24e2b9ff90b058209a22720"' src/amber_cli/amber_release.cr
grep -F 'TREE = "f1e7332d02229aec58ab5303ade7fc6c9d14fcee"' src/amber_cli/amber_release.cr
grep -F 'commit: d291e0930dd22b14a2d10f75a9de063abb0e64e4 # v2.0.0-beta.10' src/amber_cli/commands/new_command.cr
grep -F 'COMMIT = "d291e0930dd22b14a2d10f75a9de063abb0e64e4"' src/amber_cli/amber_release.cr
grep -F 'TREE = "fb4574c6b15b60357abd43ed0a1a8d7a0957e574"' src/amber_cli/amber_release.cr
grep -F 'CHECKSUM = "sha256-v2:8d354db3b41625db0362162a34836fe10a8b11a378f3837d34cc6bbcece1cb94"' 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
Expand All @@ -19,7 +20,7 @@ grep -F 'version: 0.37.1' src/amber_cli/commands/new_command.cr
grep -F 'github: amberframework/asset_pipeline' src/amber_cli/templates/app/shard.yml.ecr
grep -F 'version: 0.37.1' src/amber_cli/templates/app/shard.yml.ecr
grep -F 'github: amberframework/amber' src/amber_cli/generators/native_app.cr
grep -F 'commit: 34a93352eaa89501d24e2b9ff90b058209a22720 # v2.0.0-beta.9' 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 '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 Down
6 changes: 3 additions & 3 deletions scripts/install_pinned_minecart.ps1
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
$ErrorActionPreference = "Stop"

$minecartCommit = "0ffac921c68774ea143aeaa83c369d0a38c2d3e5"
$minecartTree = "f0e8a69bffe22afd0cee9b24994bde629384f093"
$minecartCommit = "ec4ec4d4434a92308f99de11ac907fc8a21e7a79"
$minecartTree = "dd6c0d1cfdfe1c1b78dd515a3117088b31416f2e"
$installRoot = Join-Path $env:RUNNER_TEMP "amber-pinned-minecart"

New-Item -ItemType Directory -Force $installRoot | Out-Null
Expand All @@ -24,7 +24,7 @@ try {
& crystal build src/shards.cr -o bin/minecart.exe
if ($LASTEXITCODE -ne 0) { throw "Minecart build failed" }
$minecartVersion = (& ./bin/minecart.exe --version).Trim()
if ($minecartVersion -notlike "Minecart 2025.11.25.8*") {
if ($minecartVersion -notlike "Minecart 2025.11.25.9*") {
throw "Built Minecart version did not match the pin: $minecartVersion"
}
} finally {
Expand Down
10 changes: 5 additions & 5 deletions scripts/install_pinned_minecart.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@
set -euo pipefail

# The source commit is verified by its Git tree before it can run the web smoke.
minecart_commit=0ffac921c68774ea143aeaa83c369d0a38c2d3e5
minecart_tree=f0e8a69bffe22afd0cee9b24994bde629384f093
minecart_commit=ec4ec4d4434a92308f99de11ac907fc8a21e7a79
minecart_tree=dd6c0d1cfdfe1c1b78dd515a3117088b31416f2e
minecart_repository="${MINECART_SOURCE_REPOSITORY:-https://github.com/crimson-knight/shards.git}"
minecart_source_ref="${MINECART_SOURCE_REF:-refs/tags/v2025.11.25.8}"
minecart_source_ref="${MINECART_SOURCE_REF:-refs/tags/v2025.11.25.9}"
install_root="${RUNNER_TEMP:-${TMPDIR:-/tmp}}/amber-pinned-minecart"

mkdir -p "$install_root"
Expand All @@ -27,8 +27,8 @@ fi
make -C "$install_root" bin/minecart bin/shards-alpha CRYSTAL="$CRYSTAL"
test -x "$install_root/bin/minecart"
test -x "$install_root/bin/shards-alpha"
"$install_root/bin/minecart" --version | grep -F "Minecart 2025.11.25.8"
"$install_root/bin/shards-alpha" --version | grep -F "Minecart 2025.11.25.8"
"$install_root/bin/minecart" --version | grep -F "Minecart 2025.11.25.9"
"$install_root/bin/shards-alpha" --version | grep -F "Minecart 2025.11.25.9"

if [[ -n "${GITHUB_PATH:-}" ]]; then
echo "$install_root/bin" >> "$GITHUB_PATH"
Expand Down
15 changes: 6 additions & 9 deletions scripts/smoke_generated_web.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ $amberConfig = [System.IO.File]::ReadAllText($amberConfigPath)
if (-not $manifest.Contains("github: amberframework/amber")) {
throw "Generated shard.yml does not include Amber"
}
if (-not $manifest.Contains("commit: 34a93352eaa89501d24e2b9ff90b058209a22720 # v2.0.0-beta.9")) {
if (-not $manifest.Contains("commit: d291e0930dd22b14a2d10f75a9de063abb0e64e4 # v2.0.0-beta.10")) {
throw "Generated shard.yml does not pin the supported Amber beta"
}
if (-not $manifest.Contains("github: crimson-knight/grant")) {
Expand Down Expand Up @@ -74,7 +74,7 @@ if (-not $amberConfig.Contains("database: sqlite") -or -not $amberConfig.Contain

if ($FrameworkCommit) {
$releasedRepository = " github: amberframework/amber"
$releasedFramework = " commit: 34a93352eaa89501d24e2b9ff90b058209a22720 # v2.0.0-beta.9"
$releasedFramework = " commit: d291e0930dd22b14a2d10f75a9de063abb0e64e4 # v2.0.0-beta.10"
if (-not $manifest.Contains($releasedRepository)) {
throw "Generated shard.yml does not contain the expected Amber repository"
}
Expand Down Expand Up @@ -103,11 +103,11 @@ try {
$lock = [System.IO.File]::ReadAllText((Join-Path $appPath "shard.lock"))
$entries = @([regex]::Split($lock, '(?m)^(?= [A-Za-z0-9_-]+:\r?$)') | Where-Object { $_ -match '^ [A-Za-z0-9_-]+:' })
if ($entries.Count -eq 0) {
throw "Minecart lock is missing a git-tree checksum for a dependency"
throw "Minecart lock is missing a checksum for a dependency"
}
foreach ($entry in $entries) {
if ([regex]::Matches($entry, '(?m)^ checksum: git-tree:[0-9a-f]{40}\r?$').Count -ne 1) {
throw "Minecart lock is missing a git-tree checksum for a dependency"
if ([regex]::Matches($entry, '(?m)^ checksum: sha256-v2:[0-9a-f]{64}\r?$').Count -ne 1) {
throw "Minecart lock is missing a checksum for a dependency"
}
}
$amberEntry = $entries | Where-Object { $_ -match '^ amber:' } | Select-Object -First 1
Expand All @@ -118,7 +118,7 @@ try {
$expectedAmberCommit = $FrameworkCommit
$expectedAmberGit = "https://github.com/$FrameworkRepository.git"
} else {
$expectedAmberCommit = "34a93352eaa89501d24e2b9ff90b058209a22720"
$expectedAmberCommit = "d291e0930dd22b14a2d10f75a9de063abb0e64e4"
$expectedAmberGit = "https://github.com/amberframework/amber.git"
}
if ($amberEntry -notmatch "(?m)^ git: $([regex]::Escape($expectedAmberGit))\r?$") {
Expand All @@ -127,9 +127,6 @@ try {
if ($amberEntry -notmatch "(?m)^ version: \S+\+git\.commit\.$expectedAmberCommit\r?$") {
throw "Minecart locked Amber at a commit other than $expectedAmberCommit"
}
if (-not $FrameworkCommit -and $amberEntry -notmatch '(?m)^ checksum: git-tree:f1e7332d02229aec58ab5303ade7fc6c9d14fcee\r?$') {
throw "Minecart locked Amber with a tree other than f1e7332d02229aec58ab5303ade7fc6c9d14fcee"
}
Invoke-Checked -Command $cliPath -Arguments @("assets", "build")
Invoke-Checked -Command $cliPath -Arguments @("assets", "check")

Expand Down
Loading
Loading