crosspack 0.2.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b365ad4ba6ab874d40dec1ef153ab18104f329ee6ebb7a638a27267089eb7c43
-  data.tar.gz: c8b0eef099fecc0f97f7964560e093812fe50e7627bb5a092bfadcbf8322f668
+  metadata.gz: 4f1b1bcc611377577384101685763d88198c0b27dc9323a8370fda526b7440d8
+  data.tar.gz: b3c121e02cfebbcfe8112bd4597f2009b35aecee53019a0c51aa2bb791f51007
 SHA512:
-  metadata.gz: 7c3d441c8d44206115a24ca0668843781b97631fdf3064a933d51709735911153861057bd0efa81b99406d4276b7c92b70993f12905b6e4ac6e9012b39db1f1d
-  data.tar.gz: d5bc914e071fd1be81b6cd1703b3120ce3d260a2a94188bba34b3b13f8e672f271d24c985642f43005fde6dbefc4dca542f67b74b213631eba071958e7e02a1f
+  metadata.gz: 2f69bb73a73517c21764f8e9bd7c31436f2d6a8615b437ea7912c06e4790a353c8952b7d4834c5a883352773fedb00ee73786689a3864a51e95f6835760aa003
+  data.tar.gz: df5e860abc414316410211b72fdf22d82f18a95cc211fa37d9316503625ae5fbffee86fa6a66f959a15f3a3a4cc44661d6dac05b002c2c1b6e438923dbc71d41

data/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-09-13
+
+### Breaking
+- One config file: `build.yaml`, `package.yaml` and `deps.yaml` are merged
+  into a single `crosspack.yml` with `build:` / `package:` / `deps:`
+  sections and a shared top-level `name:` (plus optional `version:`, the
+  build version scheme). The three old files are no longer read — move each
+  file's body under its section, hoist `name`/`version` to the top. No
+  migration path is provided (0.4.0 was never published beyond local gem
+  builds).
+- CLI: `-f/--file` now points at crosspack.yml (default `./crosspack.yml`);
+  the `--package` and `--build` flags are gone.
+- Library API: `Crosspack.pack` takes `config:` (a Config or a path to
+  crosspack.yml); `Crossbuild.build` accepts a Config, a path or a ready
+  BuildManifest; the manifest classes no longer read files —
+  `Manifest.load` / `PackageManifest.load` / `BuildManifest.load` are gone,
+  `Crosspack::Config.load` is the single loader.
+
+### Added
+- `Crosspack::Config`: top-level validation (name required once, version
+  scheme, unknown keys) with the shared name/version injected into the
+  build section and the name into the package section; each section keeps
+  its own schema and path-pointing error messages.
+
+## [0.4.0] - 2026-09-13
+
+### Breaking
+- The separate `crossbuild` executable is gone: one command, one staged
+  pipeline — `crosspack deps <target>` → `crosspack build <target>` →
+  `crosspack pack <target>`. The former crossbuild commands moved under
+  `crosspack` (validate/matrix/version gained build.yaml coverage; the gem
+  now installs only the `crosspack` binary).
+- build.yaml `deps:` schema: host rules are now mappings with per-system
+  `verify` and `install` commands instead of a global `check:` plus a
+  bare command string. The 0.3.0 schema was never released outside the
+  local gem build, so no migration path is provided.
+- `crosspack pack <target>` takes the target as a positional argument
+  (the old `--target` flag is gone) and `--version` is now optional: it
+  defaults to the version stamped by the build stage.
+
+### Added
+- Stage pipeline with gating: `crosspack build <target>` resolves the
+  matrix entry distributing to that target, runs the deps stage first,
+  and fans artifacts out into that target's builds/ directory only;
+  `crosspack pack <target>` refuses to run before the build stage
+  ("Build stage not done for target ... — Run: crosspack build <target>").
+- The build stage stamps `.crosspack-build` (version) into every
+  `builds/<target>/` directory; `crosspack pack` reads it as the default
+  package version.
+- deps.yaml schema versioning: an optional top-level `version:` (default
+  1). A deps.yaml declaring a newer schema than this crosspack is
+  rejected at load time with an upgrade hint; the key is reserved and no
+  longer parsed as a canonical dependency name.
+- deps: rules may be verify-only (no install command) — presence is
+  checked, and a missing dependency reports which `install:` to add.
+
+## [0.3.0] - 2026-09-13
+
+### Added
+- build.yaml `deps:` section: build dependencies with per-host install
+  commands (e.g. `ubuntu: sudo apt-get install -y imagemagick`, `windows:
+  winget install ...`, or any project script). Host selectors resolve in
+  order: distro id from `/etc/os-release`, `ID_LIKE` tokens, os, `"*"`.
+- `crossbuild deps` command: doctor + install of the deps: dependencies;
+  `--check` reports presence only and exits 1 when something is missing.
+- `crossbuild build` now verifies/installs deps: dependencies before the
+  matrix entries; `--no-deps` skips the pass.
+- `crossbuild matrix` lists how each deps: entry resolves on this host.
+
 ## [0.2.1] - 2026-09-11
 
 ### Fixed

data/README.md

@@ -1,53 +1,122 @@
 # crosspack
 
 Cross-platform build **and** pack toolchain for Wails-style desktop apps,
-shipped as one gem with two cooperating commands:
+shipped as one gem, one command, one config file and a staged pipeline:
 
-- **`crossbuild`** — runs the build steps of a project from a small
-  `build.yaml` matrix and fans the produced artifacts out into the
-  per-target tree `builds/<family>[/<version>]/<arch>/`.
-- **`crosspack`** — turns that compiled tree into native packages
-  (deb / rpm / PKGBUILD / WiX / app bundle) for any target
-  distro × version × arch, driven by two small manifests.
+```
+crosspack deps <target>     # verify/install the build host's dependencies
+crosspack build <target>    # compile the target's matrix entry into builds/
+crosspack pack <target>     # package builds/<target> as a native package
+```
 
-The two commands share the same target vocabulary (`Crosspack::Target`),
-so the build tree and the pack tree never drift apart. Build and pack
-stay cleanly separated: `crossbuild` never packages, `crosspack` never
-compiles — feed the output of one straight into the other:
+Every stage is keyed by the same target vocabulary — `debian-12`,
+`ubuntu-24.04`, `fedora-41`, `arch`, `macos`, `windows-11.0` — and gated by
+the previous one: `build` refuses to start before the deps stage passes, and
+`pack` refuses to run before `build` filled `builds/<target>/`. The build
+stage also stamps the version into the tree, so `pack` normally needs no
+`--version`:
 
 ```
-crossbuild build                          # builds/ tree
-crosspack pack --target debian-12 --version 2026.08.31-33837
+crosspack deps ubuntu-24.04
+crosspack build ubuntu-24.04
+crosspack pack ubuntu-24.04
 ```
 
-## crossbuild: build.yaml
+## crosspack.yml — one file, three sections
+
+The top level carries the shared facts — `name` (required once) and the
+optional `version` scheme — and three sections: `build:` (what and where to
+build), `package:` (what and how to pack) and `deps:` (runtime dependencies
+resolved to concrete packages per distro). The shared name/version feed the
+build section, the name feeds the package section; each section keeps its
+own schema.
 
 ```yaml
 name: myapp
 version: calver            # calver | git-tag | env:VAR | any literal string
-output: builds             # default builds; mirrors package.yaml `sources`
-
-matrix:
-  - build: linux/amd64     # os/arch this entry builds on (arch may be "any")
-    env:                   # extra env for the steps of this entry
-      CGO_ENABLED: "1"
-    steps:                 # shell commands, run from the project root
-      - wails build -platform linux/amd64 -ldflags "-X myapp/internal/app.appVersion={{version}}"
-      - cargo build --release -p helper --locked
-    artifacts:
-      from: build/bin      # what got built
-      include: [myapp, helper, "*.onnx", "*.so*"]   # default: ["*"]
-      to: [ubuntu-22.04, ubuntu-24.04, debian-12, debian-13]
-      mode: symlink        # symlink | copy, default symlink
-
-  - id: windows            # defaults to the build platform string
-    build: windows/amd64
-    steps:
-      - wails build -platform windows/amd64 -ldflags "-X ...={{version}}"
-    artifacts:
-      from: build/bin
-      include: [myapp.exe]
-      to: [windows-11.0]
+
+build:
+  output: builds           # default builds; mirrors package `sources`
+
+  deps:                    # build dependencies, per-host verify/install
+    imagemagick:
+      hosts:               # first selector matching this host wins
+        ubuntu:
+          verify: dpkg -s imagemagick
+          install: sudo apt-get install -y imagemagick
+        darwin:
+          verify: magick -version
+          install: brew install imagemagick
+        windows:
+          verify: where magick
+          install: winget install -e --id ImageMagick.ImageMagick
+        "*":               # any command — package manager or a project script
+          install: ./scripts/install-imagemagick.sh
+
+  matrix:
+    - build: linux/amd64   # os/arch this entry builds on (arch may be "any")
+      env:                 # extra env for the steps of this entry
+        CGO_ENABLED: "1"
+      steps:               # shell commands, run from the project root
+        - wails build -platform linux/amd64 -ldflags "-X myapp/internal/app.appVersion={{version}}"
+        - cargo build --release -p helper --locked
+      artifacts:
+        from: build/bin    # what got built
+        include: [myapp, helper, "*.onnx", "*.so*"]   # default: ["*"]
+        to: [ubuntu-22.04, ubuntu-24.04, debian-12, debian-13]
+        mode: symlink      # symlink | copy, default symlink
+
+    - id: windows          # defaults to the build platform string
+      build: windows/amd64
+      steps:
+        - wails build -platform windows/amd64 -ldflags "-X ...={{version}}"
+      artifacts:
+        from: build/bin
+        include: [myapp.exe]
+        to: [windows-11.0]
+
+package:
+  maintainer: Your Name <you@example.com>
+  summary: MyApp - cross-platform desktop application   # optional
+  description: |-
+    MyApp - cross-platform desktop application.
+    Bundles helper binaries and model assets alongside the GUI...
+  license: Proprietary       # optional, default Proprietary
+  section: utils             # optional, deb only
+
+  sources: builds             # compiled artifacts tree written by the build
+                              # stage: builds/<family>/<version>/<arch>/ —
+                              # pack without a matching build dir fails honestly
+  prefix: usr/local           # install prefix inside the package
+  lib_dir: lib/myapp          # optional, default lib/<name>
+
+  payload:                    # files from sources -> <prefix>/<lib_dir>/
+    - myapp
+    - helper
+    - model.onnx
+
+  executables: [myapp, helper]     # chmod 755, must be in payload
+
+  links:                     # symlinks relative to prefix
+    bin/myapp: ../lib/myapp/myapp
+
+  desktop:                   # optional, .desktop generated
+    name: MyApp
+    comment: Cross-platform desktop application
+    categories: Utility;Audio
+
+  icon: build/appicon.png    # optional, -> <prefix>/share/pixmaps/<name>.png
+
+deps:
+  # canonical dependency names resolved to concrete packages per distro
+  # family/version; an optional `version:` declares the deps schema version
+  webkit2gtk:
+    targets:
+      debian:
+        "12": [libwebkit2gtk-4.1-0, libwebkit2gtk-4.0-37]  # deb: a | b
+      fedora: { "*": [webkit2gtk4.1] }
+      macos: system      # OS component
+      windows: system    # preinstalled (WebView2)
 ```
 
 Placeholders `{{version}}`, `{{name}}`, `{{platform}}`, `{{os}}`, `{{arch}}`
@@ -63,6 +132,20 @@ builds/ubuntu/24.04/amd64/myapp -> build/bin/myapp   (symlink)
 builds/windows/11.0/x86_64/myapp.exe
 ```
 
+### Build dependencies (build.deps)
+
+`build.deps` is the host axis to the top-level `deps:` section's target
+axis: the `deps:` section declares what a *package* needs at runtime;
+`build.deps` declares what the *build host* must have. Checks differ per
+system, so every host rule carries its own commands: `verify` (presence
+probe; exit 0 = present; without it the name is looked up in PATH) and
+`install` (how to install it; may be omitted for verify-only rules).
+Selectors are tried in order: distro id from `/etc/os-release` (`ubuntu`),
+then `ID_LIKE` tokens (`debian`), then the os (`linux`, `darwin`,
+`windows`), then `"*"`. The deps stage runs verify → install → re-verify
+for every dependency; a dependency that is still missing fails the stage.
+Commands support the `{{name}}`/`{{os}}`/... placeholders.
+
 ### Version schemes
 
 | scheme        | value                                                      |
@@ -72,81 +155,27 @@ builds/windows/11.0/x86_64/myapp.exe
 | `env:VAR`     | taken from `VAR`; build fails loudly when unset            |
 | other string  | used verbatim, e.g. `version: 1.2.3`                       |
 
-### crossbuild CLI
-
-```
-crossbuild validate                       # build.yaml against the schema
-crossbuild matrix                         # entries × host buildability table
-crossbuild version                        # computed version
-crossbuild build [--target linux/amd64]   # all host-buildable entries, or one
-crossbuild targets                        # what is in builds/ ready to pack
-```
-
-`build` refuses invalid manifests with path-pointing errors, runs only the
-entries whose `build:` platform matches the host, then distributes.
-
-## crosspack: two manifests
+The whole file is validated against embedded schemas with actionable,
+path-pointing error messages; every stage refuses to run on an invalid
+config.
 
-**`package.yaml`** — what and how to pack:
-
-```yaml
-name: myapp
-maintainer: Your Name <you@example.com>
-summary: MyApp - cross-platform desktop application   # optional
-description: |-
-  MyApp - cross-platform desktop application.
-  Bundles helper binaries and model assets alongside the GUI...
-license: Proprietary       # optional, default Proprietary
-section: utils             # optional, deb only
-
-sources: builds             # compiled artifacts tree written by crossbuild:
-                            # builds/<family>/<version>/<arch>/ — pack without
-                            # a matching build directory fails honestly
-prefix: usr/local          # install prefix inside the package
-lib_dir: lib/myapp       # optional, default lib/<name>
-
-payload:                   # files from sources -> <prefix>/<lib_dir>/
-  - myapp
-  - helper
-  - model.onnx
-
-executables: [myapp, helper]     # chmod 755, must be in payload
-
-links:                     # symlinks relative to prefix
-  bin/myapp: ../lib/myapp/myapp
-
-desktop:                   # optional, .desktop generated
-  name: MyApp
-  comment: Cross-platform desktop application
-  categories: Utility;Audio
-
-icon: build/appicon.png    # optional, -> <prefix>/share/pixmaps/<name>.png
-```
-
-**`deps.yaml`** — canonical dependency names resolved to concrete packages
-per distro family/version (see the file itself for the full schema):
+## CLI
 
-```yaml
-webkit2gtk:
-  targets:
-    debian:
-      "12": [libwebkit2gtk-4.1-0, libwebkit2gtk-4.0-37]  # deb: a | b
-    fedora: { "*": [webkit2gtk4.1] }
-    macos: system      # OS component
-    windows: system    # preinstalled (WebView2)
 ```
+# staged pipeline
+crosspack deps <target> [--check]        # verify/install build deps (--check: report only)
+crosspack build <target>|--all [--no-deps] [--version X]
+crosspack pack <target> [--version X]    # version defaults to the build stamp
 
-Both files are validated against embedded schemas with actionable,
-path-pointing error messages; every builder refuses to run on an invalid
-manifest.
+# inspection
+crosspack validate                       # crosspack.yml: top level + all sections
+crosspack resolve <target>               # Depends line for the target
+crosspack matrix                         # deps x target + build matrix tables
+crosspack version                        # computed build version
+crosspack targets                        # what is in builds/ ready to pack
 
-## CLI
-
-```
-crosspack validate                       # both package.yaml and deps.yaml
-crosspack resolve --target debian-12     # Depends line for the target
-crosspack matrix                         # dependency x target table
-crosspack pack --target debian-12 --version 2026.08.31-1234 [--root .]
+# options
+-f, --file PATH                          # path to crosspack.yml (default: ./crosspack.yml)
 ```
 
 `pack` picks the builder from the target and writes to
@@ -163,27 +192,29 @@ crosspacks/arch/x86_64/PKGBUILD
 ```ruby
 require 'crosspack'   # pulls in Crossbuild too
 
-Crossbuild.build('build.yaml', root: Dir.pwd)            # all host entries
-Crossbuild.build('build.yaml', entry_id: 'windows')      # one entry explicitly
+Crossbuild.build('crosspack.yml', root: Dir.pwd)            # all host entries
+Crossbuild.build('crosspack.yml', target: 'ubuntu-24.04')   # the stages' build, library-level
 
 Crosspack.pack(
-  manifest: 'package.yaml', deps: 'deps.yaml',
+  config: 'crosspack.yml',
   target: Crosspack::Target.parse('debian-12', arch: 'amd64'),
-  version: '2026.08.31-1234',
+  version: nil,        # nil -> the version stamped by the build stage
   root: Dir.pwd, output_base: 'crosspacks'
 )
 ```
 
-Lower-level pieces are public too: on the build side `Crossbuild::
-BuildManifest`, `VersionScheme`, `Runner`, `Distributor`, `Matrix`,
-`Builder`, `Platform`; on the pack side `Crosspack::PackageManifest`,
-`Manifest`, `Resolver`, `Matrix`, `Target`, `Builders::*`.
+`Crosspack::Config.load('crosspack.yml')` parses and validates the file
+once and exposes the sections as manifests. Lower-level pieces are public
+too: on the build side `Crossbuild::BuildManifest`, `VersionScheme`,
+`Runner`, `Distributor`, `Matrix`, `Builder`, `DepInstaller`, `Platform`;
+on the pack side `Crosspack::PackageManifest`, `Manifest`, `Resolver`,
+`Matrix`, `Target`, `Builds`, `Builders::*`.
 
 Deb needs `dpkg-deb` (present on any Debian/Ubuntu), rpm needs
 `rpmbuild` (`sudo apt install rpm`), PKGBUILD generation needs nothing.
 The WiX builder generates `.wxs` sources (run the WiX Toolset yourself to
-get an MSI), the macOS builder stages the `.app` bundle (signing, notarization
-and .dmg creation are out of scope). Requires Ruby >= 3.2.
+get an MSI), the macOS builder stages the `.app` bundle (signing,
+notarization and .dmg creation are out of scope). Requires Ruby >= 3.2.
 
 ## Tests
 

data/exe/crosspack

@@ -5,8 +5,10 @@ require 'optparse'
 
 begin
   require 'crosspack'
+  require 'crossbuild'
 rescue LoadError
   require_relative '../lib/crosspack'
+  require_relative '../lib/crossbuild'
 end
 
 def abort_with(message)
@@ -14,21 +16,26 @@ def abort_with(message)
   exit 1
 end
 
-options = { file: 'deps.yaml', package: 'package.yaml', arch: 'amd64', format: nil,
-            version: nil, root: Dir.pwd, output_base: 'crosspacks' }
+options = { file: Crosspack::Config::DEFAULT_PATH, arch: 'amd64',
+            format: nil, version: nil, root: Dir.pwd, output_base: nil,
+            check_only: false, no_deps: false, all: false }
 parser = OptionParser.new do |opts|
-  opts.banner = "crosspack #{Crosspack::VERSION} — native package packer (deb/rpm/PKGBUILD/MSI/app)\n" \
+  opts.banner = "crosspack #{Crosspack::VERSION} — staged pipeline: deps → build → pack\n" \
                 "Usage: crosspack <command> [options]\n" \
-                'Commands: validate, resolve, matrix, pack, targets'
+                "Stages:   deps <target> [--check]      verify/install build deps for the target's host\n" \
+                "          build <target>|--all          compile the target's matrix entry into builds/\n" \
+                "          pack <target> [--version X]   package builds/<target> (version from the build stamp)\n" \
+                'Commands: validate, resolve, matrix, version, targets'
 
-  opts.on('-f', '--file PATH', 'path to deps.yaml (default: ./deps.yaml)') { |v| options[:file] = v }
-  opts.on('--package PATH', 'path to package.yaml (default: ./package.yaml)') { |v| options[:package] = v }
-  opts.on('--target TARGET', 'target: debian-12, ubuntu-24.04, fedora-41, arch, macos, windows') { |v| options[:target] = v }
+  opts.on('-f', '--file PATH', 'path to crosspack.yml (default: ./crosspack.yml)') { |v| options[:file] = v }
   opts.on('--arch ARCH', 'architecture: amd64/x86_64, arm64/aarch64 (default: amd64)') { |v| options[:arch] = v }
   opts.on('--format FORMAT', 'output format for resolve: deb, rpm, pkgbuild (default: derived from the target)') { |v| options[:format] = v.to_sym }
-  opts.on('--version VERSION', 'package version for pack (required for pack)') { |v| options[:version] = v }
+  opts.on('--version VERSION', 'override the version for build/pack') { |v| options[:version] = v }
   opts.on('--root PATH', 'project root for relative paths (default: .)') { |v| options[:root] = v }
-  opts.on('--output-base DIR', 'output directory (default: ./crosspacks)') { |v| options[:output_base] = v }
+  opts.on('--output-base DIR', 'output directory (build stage: the manifest output, default builds; pack: default ./crosspacks)') { |v| options[:output_base] = v }
+  opts.on('--check', 'with `deps`: only report presence, never install (exit 1 if missing)') { options[:check_only] = true }
+  opts.on('--no-deps', 'with `build`: skip the deps stage') { options[:no_deps] = true }
+  opts.on('--all', 'with `build`: every host-buildable matrix entry (default target selection off)') { options[:all] = true }
   opts.on('-h', '--help', 'show help') do
     puts opts
     exit
@@ -43,77 +50,144 @@ end
 command = ARGV.shift
 abort_with 'No command given. See: crosspack --help' if command.nil?
 
-# Positional file path: crosspack validate path/to/deps.yaml
-options[:file] = ARGV.shift if ARGV.first && !ARGV.first.start_with?('-')
+# Positional argument: a target for the stage commands (deps/build/pack,
+# resolve), a crosspack.yml path for validate.
+positional = ARGV.shift if ARGV.first && !ARGV.first.start_with?('-')
+
+options[:file] = positional if command == 'validate' && positional
 
 begin
-  manifest = Crosspack::Manifest.load(options[:file])
+  config = Crosspack::Config.load(File.expand_path(options[:file], options[:root]))
 rescue Crosspack::InvalidManifestError => e
   abort_with e.message
 end
 
+# validate prints the full report itself and exits by status; everything
+# else stops on a broken top level first.
+if command != 'validate'
+  abort_with config.error_report unless config.valid?
+end
+
+# The matrix entry that builds `target` — the deps/build stages operate on
+# its host platform.
+def entry_for_target!(manifest, target, host_os, host_arch)
+  entry = manifest.entry_for_target(target)
+  host = "#{host_os}/#{Crossbuild::Platform.display_arch(host_arch)}"
+  unless entry.buildable_on?(host_os, host_arch)
+    abort_with "The entry for #{target.inspect} (#{entry.id}) builds on #{entry.platform}, " \
+               "this host is #{host} — cross-compilation is not supported"
+  end
+
+  entry
+end
+
 case command
 when 'validate'
-  begin
-    pkg = Crosspack::PackageManifest.load(options[:package])
-  rescue Crosspack::InvalidManifestError => e
-    abort_with e.message
-  end
-  puts manifest.error_report
+  deps_manifest = config.deps_manifest
+  pkg = config.package_manifest
+  build_manifest = config.build_manifest
+  puts config.error_report
+  puts deps_manifest.error_report
   puts pkg.error_report
-  exit(manifest.valid? && pkg.valid? ? 0 : 1)
+  puts build_manifest.error_report
+  ok = config.valid? && deps_manifest.valid? && pkg.valid? && build_manifest.valid?
+  exit(ok ? 0 : 1)
 when 'matrix'
-  abort_with 'Schema is invalid — the matrix cannot be built. Run: crosspack validate' unless manifest.valid?
-  puts Crosspack::Matrix.new(manifest).render
-when 'resolve'
-  abort_with 'Specify a target: --target debian-12 (see crosspack --help)' unless options[:target]
-  begin
-    target = Crosspack::Target.parse(options[:target], arch: options[:arch])
-  rescue Crosspack::Target::Error => e
-    abort_with "Invalid target #{options[:target].inspect}: #{e.message}"
+  deps_manifest = config.deps_manifest
+  abort_with 'the deps: section is invalid — run: crosspack validate' unless deps_manifest.valid?
+  puts Crosspack::Matrix.new(deps_manifest).render
+  build_manifest = config.build_manifest
+  if build_manifest.valid?
+    puts "\n#{Crossbuild::Matrix.new(build_manifest).render}"
+  else
+    warn "\nnote: no valid build: section — build matrix not shown (crosspack validate)"
   end
+when 'resolve'
+  target_str = positional
+  abort_with 'Specify a target: crosspack resolve debian-12 (see crosspack --help)' unless target_str
   begin
+    manifest = config.deps_manifest
+    target = Crosspack::Target.parse(target_str, arch: options[:arch])
     resolver = Crosspack::Resolver.new(manifest)
     format = options[:format] || target.format
     result = resolver.depends(target, format: format)
+    puts "# #{target} (#{format})"
     if result.is_a?(Array)
-      puts "# #{target} (#{format})"
       result.each { |d| puts d }
     else
-      puts "# #{target} (#{format})"
       puts "Depends: #{result}"
     end
-  rescue Crosspack::ResolveError => e
-    abort_with "Failed to resolve dependencies for #{target}:\n  #{e.message}"
+  rescue Crosspack::Target::Error => e
+    abort_with "Invalid target #{target_str.inspect}: #{e.message}"
+  rescue Crosspack::InvalidManifestError, Crosspack::ResolveError => e
+    abort_with e.message
+  end
+when 'version'
+  build_manifest = config.build_manifest
+  abort_with 'the build: section is invalid — run: crosspack validate' unless build_manifest.valid?
+  begin
+    puts Crossbuild::VersionScheme.new(build_manifest.version).compute(root: options[:root])
+  rescue Crossbuild::VersionScheme::Error => e
+    abort_with e.message
+  end
+when 'deps'
+  abort_with 'Specify a target: crosspack deps debian-12 (see crosspack --help)' unless positional
+  build_manifest = config.build_manifest
+  abort_with 'the build: section is invalid — run: crosspack validate' unless build_manifest.valid?
+  entry_for_target!(build_manifest, positional, Crossbuild::Platform.os, Crossbuild::Platform.arch)
+  installer = Crossbuild::DepInstaller.new(build_manifest, root: options[:root])
+  begin
+    if options[:check_only]
+      installer.check_all
+      puts "deps on this host:\n#{installer.report}"
+      exit(installer.statuses.any? { |s| !s.installed } ? 1 : 0)
+    end
+    installer.ensure_all
+  rescue Crossbuild::Error => e
+    abort_with e.message
   end
+  puts "deps ready:\n#{installer.report}"
+when 'build'
+  build_manifest = config.build_manifest
+  abort_with 'the build: section is invalid — run: crosspack validate' unless build_manifest.valid?
+  if options[:all]
+    target = nil
+  else
+    abort_with 'Specify a target: crosspack build ubuntu-24.04 (or --all for every host-buildable entry)' unless positional
+    target = positional
+  end
+  begin
+    result = Crossbuild::Builder.new(build_manifest, root: options[:root],
+                                      output_base: options[:output_base], version: options[:version],
+                                      deps: !options[:no_deps]).run(target: target)
+  rescue Crossbuild::Error, Crosspack::InvalidManifestError => e
+    abort_with e.message
+  end
+  puts "\n📦 #{result.entries.size} entr#{result.entries.size == 1 ? 'y' : 'ies'} built, version #{result.version}"
+  puts 'Pack with: crosspack pack <target>'
 when 'pack'
-  abort_with 'Specify a target: --target debian-12 and a version: --version 1.0-1' unless options[:target] && options[:version]
+  abort_with 'Specify a target: crosspack pack debian-12' unless positional
   begin
-    target = Crosspack::Target.parse(options[:target], arch: options[:arch])
+    target = Crosspack::Target.parse(positional, arch: options[:arch])
     path = Crosspack.pack(
-      manifest: options[:package],
-      deps: options[:file],
+      config: config,
       target: target,
       version: options[:version],
       root: options[:root],
-      output_base: options[:output_base]
+      output_base: options[:output_base] || 'crosspacks'
     )
   rescue Crosspack::Target::Error => e
-    abort_with "Invalid target #{options[:target].inspect}: #{e.message}"
+    abort_with "Invalid target #{positional.inspect}: #{e.message}"
   rescue Crosspack::InvalidManifestError, Crosspack::ResolveError, Crosspack::BuildError => e
     abort_with e.message
   end
   puts "📦 #{path}"
 when 'targets'
   # What can actually be packed: builds tree + resolvable deps per target.
-  pkg_path = File.expand_path(options[:package], options[:root])
-  sources = begin
-    Crosspack::PackageManifest.load(pkg_path).sources
-  rescue Crosspack::InvalidManifestError
-    nil
-  end
+  pkg = config.package_manifest
+  sources = pkg.valid? ? pkg.sources : nil
   root = sources ? File.expand_path(sources, options[:root]) : File.join(options[:root], 'builds')
   puts Crosspack::Builds.report(root)
 else
-  abort_with "Unknown command #{command.inspect}. Available: validate, resolve, matrix, pack, targets"
+  abort_with "Unknown command #{command.inspect}. Available: deps, build, pack, validate, resolve, matrix, version, targets"
 end