crosspack 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 446cc8ee80c8c72227611451283314f75a8c9a276e915cecd416c72269e10d7a
-  data.tar.gz: f6186516867c2dbb74871991d33b9eb3e24ab79c627ad32dd169bf8b0be78611
+  metadata.gz: 8d03bbc2ce62c3f8cc511df1f4e9ade332adc838a361e2730154c4d9b94403a3
+  data.tar.gz: 8b3785216051ef0e2c926e9feb4a61d8473286fb3ba1a6b91d4ac19cf0969e88
 SHA512:
-  metadata.gz: 1208559fef0f7a26b62b375d4ca90578fd52668cb30862f4ba9245e3402f6b4f0e512ef4b0029eea5072328c2818e21f9d3f5ebd584edfd286b34abc9a977fa3
-  data.tar.gz: 6902bf1a81aa6ecaecc8fead2fed2886e80f948957e8bead59be6cba6ec9710d22457bed4e7ffb9e8b793e956baf764aab0a0c7ff584eb7ed13c81f23f4e3add
+  metadata.gz: 5372d580eb8e5730c13f1fffcd08c626e272ae436dc8f0d53a9a504e398f750d25948e29e8741c138044b3a2981f2082aa73e1ca418eaa0f399988ce56cf3d94
+  data.tar.gz: 63de5f8eafe2856831605c1e667c3d2ed32a65b29c405eb8ebf854c7792616e3fa2b7370ba963cd8d78e7aa9a02edec9ed14458a61e9d4f204772856abfba6f9

data/CHANGELOG.md

@@ -5,6 +5,71 @@ 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.7.0] - 2026-09-13
+
+### Added
+- Host-only commands: `crosspack run` builds for the current host (the same
+  stage `crosspack build <host target>` runs) and then launches the main
+  binary straight from `builds/` — the first `package.executables` entry,
+  not the package. Arguments after `--` are passed to the app
+  (`crosspack run -- --dev`); the app's exit code is propagated.
+- `crosspack install` launches this host's package with its system
+  installer: the newest package in `crosspacks/<host target>/` goes to
+  `xdg-open` (deb/rpm), `msiexec /i` (MSI) or `open` (macOS dmg/.app);
+  for arch crosspack generates only a PKGBUILD, so it points at
+  `makepkg -si`.
+- crosspack.yml `run:` / `install:` sections: per-host launch-command
+  overrides using the same host selectors as `build.deps` (distro id,
+  ID_LIKE, os, `"*"`), with the `{{path}}` placeholder (the built binary
+  for run, the package file for install) plus the usual build facts.
+  Default without a `run:` section: execute the binary directly (a macOS
+  `.app` bundle is `open`ed).
+
+[0.7.0]: https://github.com/OrelSokolov/crosspack/releases/tag/v0.7.0
+
+## [0.6.2] - 2026-09-13
+
+### Added
+- Colored CLI output via the new `colorize` runtime dependency: success
+  messages green, errors red, validation warnings yellow (the `ok`/`MISSING`
+  statuses in the deps report included). Colors apply only to a TTY and
+  respect `NO_COLOR`, so piped and logged output stays plain.
+- The gem now ships `logo.png` in its files.
+
+## [0.6.1] - 2026-09-13
+
+### Fixed
+- `crosspack deps` no longer dumps a Ruby backtrace when the (detected or
+  given) target has no matrix entry — it aborts with the plain message, now
+  with an actionable hint (pass a declared target or extend artifacts.to).
+- `crosspack --version` (bare, also `-v`) prints the gem version instead of
+  demanding an argument; `--version X` keeps overriding the build/pack
+  version.
+
+[0.6.2]: https://github.com/OrelSokolov/crosspack/releases/tag/v0.6.2
+[0.6.1]: https://github.com/OrelSokolov/crosspack/releases/tag/v0.6.1
+
+## [0.6.0] - 2026-09-13
+
+### Added
+- Host target default: `crosspack deps` / `build` / `pack` invoked without a
+  target run for the current host — `macos`, `windows-11.0` or the distro
+  family + version from `/etc/os-release` (unknown distro ids fall back to
+  the first known `ID_LIKE` token; unrecognizable hosts ask for an explicit
+  target).
+- Per-target payload names: `package.payload` entries may now be written as a
+  mapping `common key -> {target selector -> real file name}` instead of a
+  flat list. The key is the common name (used verbatim on every target
+  unless overridden); selectors are an exact target (`windows-11.0`), a
+  family (`windows`) or `"*"` (exact target wins, then family, then `"*"`).
+  An entry with a selector map applies only to targets it covers, so one
+  payload lists `app`/`app.exe`, `.so` libraries and Windows DLLs together —
+  each target resolves to the files its build actually produced. The flat
+  list form remains valid (same name everywhere). `executables` keeps naming
+  common keys and resolves per target at pack time.
+
+[0.6.0]: https://github.com/OrelSokolov/crosspack/releases/tag/v0.6.0
+
 ## [0.5.1] - 2026-09-13
 
 ### Fixed

data/README.md

@@ -22,14 +22,24 @@ crosspack build ubuntu-24.04
 crosspack pack ubuntu-24.04
 ```
 
-## crosspack.yml — one file, three sections
+The target may be omitted — the stage commands then run for the current
+host: `macos`, `windows-11.0` or the distro family + version from
+`/etc/os-release` (unknown ids fall back to the first known `ID_LIKE`
+token):
+
+```
+crosspack deps && crosspack build && crosspack pack
+```
+
+## crosspack.yml — one file, three sections + two host hooks
 
 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.
+resolved to concrete packages per distro). Two optional hooks — `run:` and
+`install:` — override the host-only launch commands. The shared name/version
+feed the build section, the name feeds the package section; each section
+keeps its own schema.
 
 ```yaml
 name: myapp
@@ -91,11 +101,27 @@ package:
   lib_dir: lib/myapp          # optional, default lib/<name>
 
   payload:                    # files from sources -> <prefix>/<lib_dir>/
-    - myapp
+    - myapp                   # flat form: the same name on every target
     - helper
     - model.onnx
 
-  executables: [myapp, helper]     # chmod 755, must be in payload
+  # Mapping form: per-target file names. The key is the common name (and the
+  # default file name); selectors are an exact target (windows-11.0), a
+  # family (windows), an os (linux — every distro family) or "*" — exact
+  # target wins, then family, then os, then "*". An entry with selectors
+  # applies only to targets it covers, so .so libraries and Windows DLLs can
+  # share one payload:
+  #
+  # payload:
+  #   myapp:
+  #     "*": myapp
+  #     windows: myapp.exe
+  #   libonnxruntime.so.1:
+  #     linux: libonnxruntime.so.1
+  #   onnxruntime.dll:
+  #     windows: onnxruntime.dll
+
+  executables: [myapp, helper]     # common keys; chmod 755, resolved per target
 
   links:                     # symlinks relative to prefix
     bin/myapp: ../lib/myapp/myapp
@@ -117,6 +143,15 @@ deps:
       fedora: { "*": [webkit2gtk4.1] }
       macos: system      # OS component
       windows: system    # preinstalled (WebView2)
+
+# host-only launch hooks (optional): same host selectors as build.deps
+run:                       # `crosspack run`: how to launch the built binary
+  hosts:
+    darwin: open build/bin/MyApp.app     # .app bundles must be opened, not exec'd
+
+install:                   # `crosspack install`: how to launch this host's package
+  hosts:
+    ubuntu: sudo apt-get install -y "{{path}}"
 ```
 
 Placeholders `{{version}}`, `{{name}}`, `{{platform}}`, `{{os}}`, `{{arch}}`
@@ -167,6 +202,10 @@ crosspack deps <target> [--check]        # verify/install build deps (--check: r
 crosspack build <target>|--all [--no-deps] [--version X]
 crosspack pack <target> [--version X]    # version defaults to the build stamp
 
+# host-only: this machine, no target argument
+crosspack run [-- --dev]                 # build for this host, then launch the main binary
+crosspack install                        # launch this host's package with its installer
+
 # inspection
 crosspack validate                       # crosspack.yml: top level + all sections
 crosspack resolve <target>               # Depends line for the target
@@ -187,6 +226,32 @@ crosspacks/fedora/41/x86_64/myapp-2026.08.31-1234.x86_64.rpm   (needs rpmbuild)
 crosspacks/arch/x86_64/PKGBUILD
 ```
 
+### Host-only commands: run and install
+
+`run` and `install` apply to the current host only — the build target *is*
+the run target, so they take no target argument. `crosspack run` runs the
+build stage for this host (same as `crosspack build <host target>`), then
+launches the first `package.executables` binary straight from `builds/` —
+the binary, not the package. Everything after `--` goes to the app:
+
+```
+crosspack run -- --dev
+```
+
+`crosspack install` takes the newest package packed for this host in
+`crosspacks/` and hands it to the system installer. Defaults: `xdg-open`
+for deb/rpm (opens GNOME Software/installer), `msiexec /i` for the MSI,
+`open` for a macOS dmg/.app; for arch crosspack only generates a PKGBUILD,
+so it points you at `makepkg -si` instead.
+
+Both are per-system by nature, so each accepts a `hosts:` override with the
+same selectors as `build.deps` (distro id, `ID_LIKE`, os, `"*"` — first
+match wins). Commands support the `{{path}}` placeholder (the binary in
+`builds/` for run, the package file for install) plus the usual
+`{{name}}`/`{{version}}`/`{{os}}`/`{{arch}}` facts; quote values that start
+with `{{` (YAML flow indicators). Without a `run:` section the binary is
+executed directly, except a macOS `.app` bundle which is `open`ed.
+
 ## Library
 
 ```ruby

data/exe/crosspack

@@ -12,25 +12,50 @@ rescue LoadError
 end
 
 def abort_with(message)
-  warn message
+  warn Crosspack::Colors.red(message)
   exit 1
 end
 
+# Validate reports line by line: valid → green, invalid → red, warnings → yellow.
+def colorized_report(text)
+  text.lines.map do |line|
+    chomped = line.chomp
+    colored =
+      if chomped.include?('is invalid')
+        Crosspack::Colors.red(chomped)
+      elsif chomped.include?('is valid')
+        Crosspack::Colors.green(chomped)
+      elsif chomped.strip.start_with?('⚠')
+        Crosspack::Colors.yellow(chomped)
+      end
+    colored ? "#{colored}\n" : line
+  end.join
+end
+
 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 }
+
+# `crosspack --version` (also bare -v) prints the gem version like any other
+# CLI; with a value the flag stays the build/pack version override.
+if ARGV.size == 1 && %w[--version -v].include?(ARGV.first)
+  puts "crosspack #{Crosspack::VERSION}"
+  exit
+end
 parser = OptionParser.new do |opts|
   opts.banner = "crosspack #{Crosspack::VERSION} — staged pipeline: deps → build → pack\n" \
                 "Usage: crosspack <command> [options]\n" \
-                "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" \
+                "Stages:   deps [<target>] [--check]      verify/install build deps (default: this host)\n" \
+                "          build [<target>]|--all          compile into builds/ (default: this host)\n" \
+                "          pack [<target>] [--version X]   package builds/<target> (default: this host; version from the build stamp)\n" \
+                "Host:     run [-- <app args>]            build for this host, then launch the main binary\n" \
+                "          install                         launch this host's package with its installer\n" \
                 'Commands: validate, resolve, matrix, version, targets'
 
   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', 'override the version for build/pack') { |v| options[:version] = v }
+  opts.on('--version VERSION', 'override the version for build/pack; a bare `crosspack --version` prints the gem version') { |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 (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 }
@@ -79,6 +104,19 @@ def entry_for_target!(manifest, target, host_os, host_arch)
   end
 
   entry
+rescue Crossbuild::Error => e
+  abort_with e.message
+end
+
+# Stage commands (deps/build/pack) run for the current host when no target
+# is given: macos, windows-11.0 or the distro from /etc/os-release.
+def host_target!(command)
+  raw = Crosspack::Target.host_string
+  abort_with "Could not detect this host's target — pass one explicitly: crosspack #{command} <target> " \
+             '(families: ubuntu-24.04, debian-12, fedora-41, arch, macos, windows-11.0)' if raw.nil?
+
+  puts "→ no target given; using this host's target: #{raw}"
+  raw
 end
 
 case command
@@ -86,11 +124,15 @@ when 'validate'
   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
-  puts build_manifest.error_report
-  ok = config.valid? && deps_manifest.valid? && pkg.valid? && build_manifest.valid?
+  puts colorized_report(config.error_report)
+  puts colorized_report(deps_manifest.error_report)
+  puts colorized_report(pkg.error_report)
+  puts colorized_report(build_manifest.error_report)
+  [config.run_manifest, config.install_manifest].each do |m|
+    puts colorized_report(m.error_report) if m.present?
+  end
+  ok = config.valid? && deps_manifest.valid? && pkg.valid? && build_manifest.valid? &&
+       config.run_manifest.valid? && config.install_manifest.valid?
   exit(ok ? 0 : 1)
 when 'matrix'
   deps_manifest = config.deps_manifest
@@ -131,12 +173,12 @@ when 'version'
     abort_with e.message
   end
 when 'deps'
-  abort_with 'Specify a target: crosspack deps debian-12 (see crosspack --help)' unless positional
+  target_str = positional || host_target!('deps')
   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
+    entry_for_target!(build_manifest, target_str, Crossbuild::Platform.os, Crossbuild::Platform.arch)
+    installer = Crossbuild::DepInstaller.new(build_manifest, root: options[:root])
     if options[:check_only]
       installer.check_all
       puts "deps on this host:\n#{installer.report}"
@@ -146,15 +188,14 @@ when 'deps'
   rescue Crossbuild::Error => e
     abort_with e.message
   end
-  puts "deps ready:\n#{installer.report}"
+  puts Crosspack::Colors.green("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
+    target = positional || host_target!('build')
   end
   begin
     result = Crossbuild::Builder.new(build_manifest, root: options[:root],
@@ -163,12 +204,12 @@ when 'build'
   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 Crosspack::Colors.green("\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: crosspack pack debian-12' unless positional
+  target_str = positional || host_target!('pack')
   begin
-    target = Crosspack::Target.parse(positional, arch: options[:arch])
+    target = Crosspack::Target.parse(target_str, arch: options[:arch])
     path = Crosspack.pack(
       config: config,
       target: target,
@@ -177,11 +218,37 @@ when 'pack'
       output_base: options[:output_base] || 'crosspacks'
     )
   rescue Crosspack::Target::Error => e
-    abort_with "Invalid target #{positional.inspect}: #{e.message}"
+    abort_with "Invalid target #{target_str.inspect}: #{e.message}"
   rescue Crosspack::InvalidManifestError, Crosspack::ResolveError, Crosspack::BuildError => e
     abort_with e.message
   end
-  puts "📦 #{path}"
+  puts Crosspack::Colors.green("📦 #{path}")
+when 'run', 'install'
+  # Host-only commands: no target argument; anything after `--` goes to the
+  # launched process (crosspack run -- --dev).
+  if positional
+    abort_with "crosspack #{command} works only for the current host — no target argument " \
+               "(other targets make no sense here)"
+  end
+  args = ARGV.dup
+  args.shift if args.first == '--'
+  begin
+    status =
+      if command == 'run'
+        Crosspack::Launcher.run(
+          config, root: options[:root], args: args,
+          output_base: options[:output_base], version: options[:version], deps: !options[:no_deps]
+        )
+      else
+        Crosspack::Launcher.install(
+          config, root: options[:root], args: args,
+          output_base: options[:output_base] || 'crosspacks'
+        )
+      end
+  rescue Crosspack::InvalidManifestError, Crosspack::BuildError, Crossbuild::Error => e
+    abort_with e.message
+  end
+  exit(status) unless status.zero?
 when 'targets'
   # What can actually be packed: builds tree + resolvable deps per target.
   pkg = config.package_manifest
@@ -189,5 +256,5 @@ when 'targets'
   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: deps, build, pack, validate, resolve, matrix, version, targets"
+  abort_with "Unknown command #{command.inspect}. Available: deps, build, pack, run, install, validate, resolve, matrix, version, targets"
 end

data/lib/crossbuild/build_manifest.rb

@@ -143,7 +143,8 @@ module Crossbuild
       if matches.empty?
         raise Error,
               "no matrix entry distributes to target #{raw.inspect}; " \
-              "declared targets: #{declared.join(', ')}"
+              "declared targets: #{declared.join(', ')}. Pass one of them explicitly, " \
+              "or add #{raw.inspect} to the entry's artifacts.to in crosspack.yml"
       end
       if matches.size > 1
         raise Error,

data/lib/crossbuild/dep_installer.rb

@@ -53,8 +53,10 @@ module Crossbuild
       return '  (no deps declared)' if @manifest.deps.empty?
 
       (@statuses || check_all).map do |s|
+        state = format('%-8s', s.installed ? 'ok' : 'MISSING')
+        state = Crosspack::Colors.public_send(s.installed ? :green : :red, state)
         format('  %-20s %-8s %-8s %s',
-               s.dep, s.installed ? 'ok' : 'MISSING', s.selector, s.command)
+               s.dep, state, s.selector, s.command)
       end.join("\n")
     end
 

data/lib/crosspack/colors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'colorize'
+
+module Crosspack
+  # CLI message coloring (green = success, red = errors, yellow = warnings),
+  # powered by the colorize gem. Colors are turned off automatically when the
+  # output is not a TTY or NO_COLOR is set, so piped and logged output stays
+  # clean.
+  module Colors
+    class << self
+      attr_writer :enabled
+
+      def enabled?
+        return @enabled unless @enabled.nil?
+
+        ENV['NO_COLOR'].nil? && ($stdout.tty? || $stderr.tty?)
+      end
+
+      def red(text)
+        enabled? ? text.to_s.colorize(:red) : text
+      end
+
+      def green(text)
+        enabled? ? text.to_s.colorize(:green) : text
+      end
+
+      def yellow(text)
+        enabled? ? text.to_s.colorize(:yellow) : text
+      end
+    end
+  end
+end

data/lib/crosspack/command_manifest.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Crosspack
+  # Parses and validates the optional run:/install: sections of crosspack.yml.
+  # Both map host selectors (the same vocabulary as the deps: rules of the
+  # build: section: distro id from os-release, ID_LIKE token, os name, "*")
+  # to a shell command with {{path}} and the usual build facts:
+  #
+  #   run:
+  #     hosts:
+  #       darwin: open build/bin/MyApp.app
+  #       "*": "{{path}} --dev"
+  #
+  # A section is optional; when absent the host-only default applies
+  # (see Launcher).
+  class CommandManifest
+    SECTION_KEYS = %w[hosts].freeze
+    # A host selector: "*" or a distro id / ID_LIKE token / os name —
+    # the same vocabulary as the deps: rules of the build: section.
+    SELECTOR_RE = /\A(\*|[a-z0-9][a-z0-9+._-]*)\z/i.freeze
+
+    attr_reader :path, :section, :errors, :warnings
+
+    def initialize(path, raw, section)
+      @path = path
+      @section = section
+      @raw = raw
+      @hosts = {}
+      @errors = []
+      @warnings = []
+      validate
+    end
+
+    def present?
+      !@raw.nil?
+    end
+
+    def valid?
+      @errors.empty?
+    end
+
+    # The command for the given host selectors (see Crossbuild::Platform
+    # .selectors), first match wins; nil when nothing applies.
+    def command_for(selectors)
+      selectors.each { |s| return @hosts[s] if @hosts.key?(s) }
+      nil
+    end
+
+    def error_report
+      return "#{@path}: the #{@section}: section is absent — defaults apply" unless present?
+
+      lines = ["#{@path}: the #{@section}: section is #{@errors.empty? ? 'valid' : "invalid (#{@errors.size} errors)"}:"]
+      @errors.each { |e| lines << "  ✗ #{e}" }
+      @warnings.each { |w| lines << "  ⚠ #{w}" }
+      lines.join("\n")
+    end
+
+    def validate!
+      return self if valid?
+
+      raise InvalidManifestError, error_report
+    end
+
+    private
+
+    def validate
+      return unless present?
+
+      unless @raw.is_a?(Hash) && !@raw.empty?
+        @errors << Issue.new("#{@section}", "must be a non-empty mapping with the key: hosts; expected:\n" \
+                                            "    #{@section}:\n" \
+                                            "      hosts:\n" \
+                                            "        ubuntu: #{@section == 'install' ? 'xdg-open {{path}}' : '{{path}} --dev'}")
+        return
+      end
+      check_unknown_keys
+
+      hosts = @raw['hosts']
+      return unless hosts
+
+      unless hosts.is_a?(Hash) && !hosts.empty?
+        @errors << Issue.new("#{@section}.hosts", 'must be a non-empty mapping of host selector -> shell command')
+        return
+      end
+
+      hosts.each do |selector, command|
+        validate_rule(selector.to_s, command)
+      end
+    end
+
+    def check_unknown_keys
+      @raw.keys.map(&:to_s).each do |key|
+        next if SECTION_KEYS.include?(key)
+
+        @errors << Issue.new("#{@section}.#{key}", "unknown key; allowed: #{SECTION_KEYS.join(', ')}")
+      end
+    end
+
+    def validate_rule(selector, command)
+      path = "#{@section}.hosts.#{selector}"
+      unless selector =~ SELECTOR_RE
+        @errors << Issue.new(path, "invalid host selector (expected a distro id, os name or \"*\")")
+        return
+      end
+      unless command.is_a?(String) && !command.strip.empty?
+        @errors << Issue.new(path, 'must be a non-empty shell command')
+      end
+      @hosts[selector] = command if command.is_a?(String) && !command.strip.empty?
+    end
+  end
+end

data/lib/crosspack/config.rb

@@ -15,7 +15,7 @@ module Crosspack
   # happens per section, not per file.
   class Config
     DEFAULT_PATH = 'crosspack.yml'
-    TOP_LEVEL_KEYS = %w[name version build package deps].freeze
+    TOP_LEVEL_KEYS = %w[name version build package deps run install].freeze
     NAME_RE = /\A[a-z0-9][a-z0-9+._-]*\z/i.freeze
 
     attr_reader :path, :errors, :warnings
@@ -81,6 +81,15 @@ module Crosspack
       @deps_manifest ||= Manifest.new(@path, deps_section)
     end
 
+    # The optional run:/install: sections (host-only launch commands).
+    def run_manifest
+      @run_manifest ||= CommandManifest.new(@path, @raw['run'], 'run')
+    end
+
+    def install_manifest
+      @install_manifest ||= CommandManifest.new(@path, @raw['install'], 'install')
+    end
+
     private
 
     def validate
@@ -124,7 +133,7 @@ module Crosspack
     end
 
     def check_section_types
-      %w[build package deps].each do |key|
+      %w[build package deps run install].each do |key|
         next unless @raw.key?(key) && !@raw[key].is_a?(Hash)
 
         @errors << Issue.new(key, 'must be a mapping')

data/lib/crosspack/launcher.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Crosspack
+  # Host-only launch commands: `crosspack run` (build the host target, then
+  # launch the application's main binary) and `crosspack install` (launch the
+  # package packed for this host). Both resolve the current host target, so
+  # they take no target argument and are meaningless on any other system.
+  #
+  # Commands may be overridden per host in crosspack.yml (run:/install:
+  # sections, selectors like the deps: rules of build:); placeholders:
+  # {{path}} plus the usual facts ({{name}}, {{version}}, {{os}}, {{arch}}).
+  # Defaults when nothing is configured:
+  #   run:     darwin + .app bundle -> `open {{path}}`, otherwise {{path}}
+  #   install: deb/rpm -> xdg-open, msi -> msiexec /i, dmg/.app -> open
+  class Launcher
+    class Error < BuildError; end
+
+    # Builds the host target first (the same stage `crosspack build` runs),
+    # then launches the first package.executables binary from builds/.
+    # Returns the launched process's exit code.
+    def self.run(config, root: Dir.pwd, args: [], output_base: nil, version: nil,
+                 deps: true, host_string: nil, host_os: Crossbuild::Platform.os,
+                 host_arch: Crossbuild::Platform.arch, selectors: Crossbuild::Platform.selectors)
+      config = Config.coerce(config, root: root)
+      target = host_target('run', host_string, host_arch)
+      pkg = validated_package(config)
+      build_manifest = config.build_manifest
+      build_manifest.validate!
+
+      Crossbuild::Builder.new(build_manifest, root: root, output_base: output_base,
+                                            version: version, deps: deps,
+                                            host_os: host_os, host_arch: host_arch)
+                         .run(target: target.to_s)
+
+      exe = pkg.executables_for(target).first
+      if exe.nil?
+        raise Error,
+              'run: the package: section does not name the binary to launch — ' \
+              "add executables: [#{pkg.name}] to it (the first entry is what `crosspack run` launches)"
+      end
+
+      path = File.join(File.expand_path(target.output_dir(pkg.sources, target.format), root), exe)
+      unless File.exist?(path)
+        raise Error,
+              "run: expected the built binary at #{path}, but it is not there — " \
+              'does the build step really produce it? Check package.executables against the build output'
+      end
+
+      command = config.run_manifest.command_for(selectors) || default_run_command(path, host_os)
+      execute(command, path: path, pkg: pkg, target: target, root: root, args: args)
+    end
+
+    # Finds the package packed for this host in crosspacks/ and launches it
+    # with the system installer. Returns the launched process's exit code.
+    def self.install(config, root: Dir.pwd, args: [], output_base: 'crosspacks',
+                     host_string: nil, host_os: Crossbuild::Platform.os,
+                     host_arch: Crossbuild::Platform.arch, selectors: Crossbuild::Platform.selectors)
+      config = Config.coerce(config, root: root)
+      target = host_target('install', host_string, host_arch)
+      pkg = validated_package(config)
+
+      command = config.install_manifest.command_for(selectors)
+      raise Error, pkgbuild_hint(target, root, output_base) if command.nil? && target.format == :pkgbuild
+
+      # {{path}} resolves to the package file (for arch: the PKGBUILD dir).
+      path = target.format == :pkgbuild ? packed_dir(target, root, output_base)
+                                        : package_file(target, pkg, root, output_base)
+      command ||= default_install_command(target.format)
+
+      execute(command, path: path, pkg: pkg, target: target, root: root, args: args)
+    end
+
+    # -- defaults ------------------------------------------------------------
+
+    # A macOS .app bundle must be opened, not exec'd; plain binaries and
+    # Windows exes run directly.
+    def self.default_run_command(path, host_os)
+      host_os == :darwin && File.directory?(path) ? 'open {{path}}' : '{{path}}'
+    end
+
+    def self.default_install_command(format)
+      case format
+      when :deb, :rpm   then 'xdg-open {{path}}'
+      when :winget      then 'msiexec /i {{path}}'
+      when :cask        then 'open {{path}}'
+      else
+        raise Error, "install: no default installer command for format #{format.inspect} — " \
+                     'add an install: section with hosts: rules to crosspack.yml'
+      end
+    end
+
+    # -- internals -----------------------------------------------------------
+
+    class << self
+      private
+
+      # "this host's target" — the same detection the stage commands use.
+      def host_target(command, host_string, host_arch)
+        raw = host_string || Target.host_string
+        if raw.nil?
+          raise Error,
+                "Could not detect this host's target — crosspack #{command} runs only on this host " \
+                '(families: ubuntu-24.04, debian-12, fedora-41, arch, macos, windows-11.0)'
+        end
+
+        Target.parse(raw, arch: host_arch)
+      end
+
+      def validated_package(config)
+        pkg = config.package_manifest
+        pkg.validate!
+        pkg
+      end
+
+      def packed_dir(target, root, output_base)
+        File.expand_path(target.output_dir(output_base, target.format), root)
+      end
+
+      # The packed tree must exist before any installer runs — even with a
+      # custom command (its {{path}} resolves into this directory).
+      def check_packed_dir(target, root, output_base)
+        dir = packed_dir(target, root, output_base)
+        return if File.directory?(dir)
+
+        raise Error,
+              "Pack stage not done for target #{target}: expected a packed package in #{dir}.\n" \
+              "Run: crosspack pack #{target}"
+      end
+
+      # The single package file this host's installer should receive.
+      def package_file(target, pkg, root, output_base)
+        check_packed_dir(target, root, output_base)
+        dir = packed_dir(target, root, output_base)
+        file =
+          case target.format
+          when :deb    then newest(dir, '*.deb')
+          when :rpm    then newest(dir, '*.rpm')
+          when :winget then newest(dir, '*.msi')
+          when :cask   then newest(dir, '*.dmg') || app_bundle(dir, pkg.name)
+          end
+
+        if file.nil?
+          raise winget_sources_hint(dir) if target.format == :winget && Dir[File.join(dir, '*.wxs')].any?
+
+          raise Error,
+                "No package for target #{target} in #{dir} — the pack stage produced nothing this " \
+                "command recognizes.\nRun: crosspack pack #{target}"
+        end
+        file
+      end
+
+      def newest(dir, pattern)
+        Dir[File.join(dir, pattern)].max_by { |f| File.mtime(f) }
+      end
+
+      def app_bundle(dir, name)
+        app = File.join(dir, "#{name}.app")
+        File.directory?(app) ? app : nil
+      end
+
+      def winget_sources_hint(dir)
+        'install: the pack stage produced only WiX sources (.wxs) — build the MSI first, ' \
+          "see #{File.join(dir, 'BUILD-MSI.txt')}"
+      end
+
+      def pkgbuild_hint(target, root, output_base)
+        "install: packing for #{target} generates a PKGBUILD, not a built package — " \
+          "install it yourself:\n  cd #{packed_dir(target, root, output_base)} && makepkg -si\n" \
+          'or add an install: section with hosts: rules to crosspack.yml'
+      end
+
+      # Expands the {{...}} placeholders, appends extra CLI args and runs the
+      # command from the project root, passing the child's exit code through.
+      def execute(command, path:, pkg:, target:, root:, args:)
+        vars = {
+          name: pkg.name,
+          version: Builds.version_for(target, File.expand_path(pkg.sources, root)).to_s,
+          os: target.family.to_s,
+          arch: Crossbuild::Platform.display_arch(target.arch == :any ? :x86_64 : target.arch),
+          platform: target.to_s,
+          path: path
+        }
+        command = Crossbuild::Runner.new(root: root, vars: vars).interpolate(command)
+        command = "#{command} #{args.join(' ')}" unless args.empty?
+
+        puts "▶ #{command}"
+        result = system(command, chdir: root)
+        raise Error, "launch failed (command not found): #{command}" if result.nil?
+
+        $?.exitstatus || 0
+      end
+    end
+  end
+end

data/lib/crosspack/package_manifest.rb

@@ -5,10 +5,25 @@ module Crosspack
   # WHAT and HOW to pack — payload, executables, symlinks, desktop entry,
   # icon. Compilation is not crosspack's business; artifacts are picked from
   # `sources` as-is.
+  #
+  # Payload entries may carry per-target file names: the key is the common
+  # name (used verbatim everywhere unless a selector map says otherwise),
+  # and each selector (exact target "windows-11.0", family "windows" or "*")
+  # maps to the real file name that target's build produces. An entry with a
+  # selector map applies only to targets it covers — a Windows build dir has
+  # no .so libraries and vice versa.
   class PackageManifest
     REQUIRED = %w[maintainer description sources prefix payload].freeze
     OPTIONAL = %w[name summary license section lib_dir executables links desktop icon].freeze
 
+    # Payload selectors may name an os in addition to a family: every distro
+    # family packs a linux target, so "linux:" covers deb/rpm/PKGBUILD
+    # without enumerating them (macos and windows are their own families).
+    OS_BY_FAMILY = Hash.new('linux').merge(macos: 'macos', windows: 'windows').freeze
+
+    # One payload file: its common key plus the per-target name overrides.
+    PayloadFile = Struct.new(:key, :names, keyword_init: true)
+
     attr_reader :path, :data, :errors, :warnings
 
     def initialize(path, raw)
@@ -17,6 +32,7 @@ module Crosspack
       @raw = raw
       @errors = []
       @warnings = []
+      @payload_entries = []
       validate
     end
 
@@ -72,14 +88,40 @@ module Crosspack
       @data['prefix']
     end
 
+    # Common keys of the payload entries (the executables list and links
+    # reference these); use payload_for(target) for the real file names.
     def payload
-      Array(@data['payload'])
+      @payload_entries.map(&:key)
+    end
+
+    # Real file names the given target's package carries. Every entry
+    # resolves through its selector map — exact target string, then family,
+    # then "*"; entries without a map use their key on every target; entries
+    # whose selectors do not cover the target are skipped.
+    def payload_for(target)
+      @payload_entries.filter_map { |entry| resolve_entry(entry, target) }
     end
 
     def executables
       Array(@data['executables'])
     end
 
+    # Executable file names for the target. The executables list names
+    # common payload keys; they resolve to the target's real file names.
+    def executables_for(target)
+      executables.map do |key|
+        entry = @payload_entries.find { |e| e.key == key }
+        resolved = entry && resolve_entry(entry, target)
+        if resolved.nil?
+          raise InvalidManifestError,
+                "executables: #{key.inspect} resolves to no file for target #{target} — " \
+                'its payload entry has no name for that target'
+        end
+
+        resolved
+      end
+    end
+
     def summary
       @data['summary'] || description.lines.map(&:chomp).reject(&:empty?).first || name
     end
@@ -153,17 +195,91 @@ module Crosspack
       value = @data['payload']
       return if value.nil? # already reported as missing
 
-      unless value.is_a?(Array) && !value.empty?
-        @errors << Issue.new('payload', 'must be a non-empty list of artifact files from sources')
-        return
+      @payload_entries =
+        if value.is_a?(Array)
+          validate_payload_list(value)
+        elsif value.is_a?(Hash)
+          validate_payload_map(value)
+        else
+          @errors << Issue.new('payload', 'must be a non-empty list of artifact files or a mapping: key -> {target -> real file name}')
+          []
+        end
+      return unless @payload_entries.empty?
+
+      @errors << Issue.new('payload', 'must name at least one artifact file from sources')
+    end
+
+    # Legacy/simple form: a flat list — every name applies to every target.
+    def validate_payload_list(value)
+      value.each_with_index.with_object([]) do |(item, i), entries|
+        if item.is_a?(String) && !item.strip.empty? && !item.start_with?('/')
+          entries << PayloadFile.new(key: item, names: {})
+        else
+          @errors << Issue.new("payload[#{i}]", 'file name must be a non-empty relative string (no leading "/")')
+        end
       end
-      value.each_with_index do |item, i|
-        next if item.is_a?(String) && !item.strip.empty? && !item.start_with?('/')
+    end
 
-        @errors << Issue.new("payload[#{i}]", 'file name must be a non-empty relative string (no leading "/")')
+    # Mapping form: common key -> null (key everywhere) or a selector map
+    # (exact target / family / "*") of real file names per target.
+    def validate_payload_map(value)
+      value.each_with_object([]) do |(key, names), entries|
+        if !key.is_a?(String) || key.strip.empty? || key.start_with?('/')
+          @errors << Issue.new("payload.#{key.inspect}", 'must be a non-empty relative file name (no leading "/")')
+          next
+        end
+        if names.nil? || names == {}
+          entries << PayloadFile.new(key: key, names: {})
+          next
+        end
+        unless names.is_a?(Hash)
+          @errors << Issue.new("payload.#{key}", 'must be null or a mapping of target selector -> real file name')
+          next
+        end
+
+        resolved = {}
+        entry_valid = true
+        names.each do |selector, name|
+          unless valid_selector?(selector)
+            @errors << Issue.new("payload.#{key}.#{selector}",
+                                 "unknown target selector (allowed: \"*\", an os (linux) or a family " \
+                                 "(#{Target::FAMILIES.join(', ')}), optionally with a version, e.g. windows-11.0)")
+            entry_valid = false
+            next
+          end
+          if !name.is_a?(String) || name.strip.empty? || name.start_with?('/')
+            @errors << Issue.new("payload.#{key}.#{selector}", 'file name must be a non-empty relative string (no leading "/")')
+            entry_valid = false
+            next
+          end
+          resolved[selector] = name
+        end
+        entries << PayloadFile.new(key: key, names: resolved) if entry_valid
       end
     end
 
+    def valid_selector?(selector)
+      return true if selector == '*'
+      return true if selector == 'linux' # the one os selector (macos/windows are families)
+
+      Target.parse(selector.to_s)
+      true
+    rescue Target::Error
+      false
+    end
+
+    # Exact target string ("windows-11.0") wins over the family ("windows"),
+    # then the os ("linux"), then "*"; an entry without a map carries its
+    # key on every target.
+    def resolve_entry(entry, target)
+      return entry.key if entry.names.empty?
+
+      entry.names[target.to_s] ||
+        entry.names[target.family.to_s] ||
+        entry.names[OS_BY_FAMILY[target.family]] ||
+        entry.names['*']
+    end
+
     def validate_executables
       value = @data['executables']
       return if value.nil?

data/lib/crosspack/packer.rb

@@ -96,7 +96,7 @@ module Crosspack
       end
 
       lib_dst = File.join(@pkg.prefix, @pkg.lib_dir)
-      files = @pkg.payload.to_h { |n| [File.join(src_dir, n), File.join(lib_dst, n)] }
+      files = @pkg.payload_for(@target).to_h { |n| [File.join(src_dir, n), File.join(lib_dst, n)] }
 
       if @pkg.icon
         icon_src = File.expand_path(@pkg.icon, @root)
@@ -110,7 +110,7 @@ module Crosspack
       end
 
       symlinks = @pkg.links.to_h { |link, target| [File.join(@pkg.prefix, link), target] }
-      executables = @pkg.executables.map { |exe| File.join(lib_dst, exe) }
+      executables = @pkg.executables_for(@target).map { |exe| File.join(lib_dst, exe) }
 
       { files: files, symlinks: symlinks, executables: executables,
         src_dir: src_dir, lib_dst: lib_dst }
@@ -192,7 +192,7 @@ module Crosspack
         depends: resolved_depends(:pkgbuild),
         arch: [@target.package_arch(:pkgbuild)],
         # PKGBUILD sources are archive-relative names, not local paths.
-        files: @pkg.payload.to_h { |n| [n, File.join(@pkg_data[:lib_dst], n)] },
+        files: @pkg.payload_for(@target).to_h { |n| [n, File.join(@pkg_data[:lib_dst], n)] },
         symlinks: @pkg_data[:symlinks],
         executables: @pkg_data[:executables],
         source: ["#{@pkg.name}-#{version}.tar.gz"],
@@ -213,7 +213,7 @@ module Crosspack
     def pack_windows
       output = File.join(@target.output_dir(@output_base, :winget),
                          "#{@pkg.name}-#{Builders::Wix.msi_version(@version)}.msi")
-      files = @pkg.payload.to_h { |n| [File.join(@pkg_data[:src_dir], n), n] }
+      files = @pkg.payload_for(@target).to_h { |n| [File.join(@pkg_data[:src_dir], n), n] }
       Builders::Wix.build(
         name: @pkg.name,
         version: @version,
@@ -228,13 +228,13 @@ module Crosspack
     # macOS: .app bundle staging; DMG itself requires a Mac (hdiutil).
     def pack_macos
       output_dir = @target.output_dir(@output_base, :cask)
-      files = @pkg.payload.to_h { |n| [File.join(@pkg_data[:src_dir], n), n] }
+      files = @pkg.payload_for(@target).to_h { |n| [File.join(@pkg_data[:src_dir], n), n] }
       Builders::AppDir.build(
         name: @pkg.name,
         version: @version,
         summary: @pkg.summary,
         files: files,
-        executables: @pkg.executables,
+        executables: @pkg.executables_for(@target),
         output: output_dir
       )
     end

data/lib/crosspack/target.rb

@@ -55,6 +55,45 @@ module Crosspack
       new(family_sym, version, norm_arch)
     end
 
+    # The target of the machine crosspack runs on, for stage commands invoked
+    # without an explicit target: "macos", "windows-11.0" or the distro
+    # family + version from the os-release file ("ubuntu-24.04",
+    # "debian-12", "fedora-41", "arch"). Unknown distro ids fall back to the
+    # first ID_LIKE token that names a family. Returns nil when the host is
+    # not recognizable — the CLI then asks for an explicit target.
+    # Windows defaults to the 11.0 target vocabulary (10 is EOL); pass a
+    # target explicitly when packing for another release.
+    def self.host_string(ruby_platform: RUBY_PLATFORM, release_path: '/etc/os-release')
+      case ruby_platform
+      when /darwin/ then 'macos'
+      when /mingw|mswin|cygwin/i then 'windows-11.0'
+      when /linux/
+        facts = host_os_release(release_path)
+        family = ([facts['ID']] + facts['ID_LIKE'].to_s.split)
+                   .filter_map { |id| id.to_s.to_sym if id }
+                   .find { |f| FAMILIES.include?(f) }
+        return nil if family.nil?
+
+        version = facts['VERSION_ID'].to_s
+        return family.to_s if VERSIONLESS_FAMILIES.include?(family) ||
+                               OPTIONAL_VERSION_FAMILIES.include?(family)
+        return nil if version.empty? # e.g. Debian sid: no pin-able version
+
+        "#{family}-#{version}"
+      end
+    end
+
+    def self.host_os_release(path)
+      File.read(path).each_line.with_object({}) do |line, facts|
+        key, value = line.split('=', 2)
+        next if value.nil?
+
+        facts[key.strip] = value.strip.delete_prefix('"').delete_suffix('"')
+      end
+    rescue Errno::ENOENT
+      {}
+    end
+
     def initialize(family, version = nil, arch = :x86_64)
       @family = family.to_sym
       @version = version && version.to_s

data/lib/crosspack/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Crosspack
-  VERSION = '0.5.1'
+  VERSION = '0.7.0'
 end

data/lib/crosspack.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 require_relative 'crosspack/version'
+
+module Crosspack
+  # A stage failed (deps/build/pack/launch). Defined before the requires:
+  # launcher.rb subclasses it at load time.
+  class BuildError < StandardError; end
+end
+
+require_relative 'crosspack/colors'
 require_relative 'crosspack/target'
 require_relative 'crosspack/manifest'
+require_relative 'crosspack/command_manifest'
 require_relative 'crosspack/package_manifest'
 require_relative 'crosspack/config'
 require_relative 'crosspack/resolver'
 require_relative 'crosspack/matrix'
 require_relative 'crosspack/builds'
 require_relative 'crosspack/packer'
+require_relative 'crosspack/launcher'
 require_relative 'crosspack/builders/deb'
 require_relative 'crosspack/builders/rpm'
 require_relative 'crosspack/builders/pkgbuild'
@@ -29,7 +39,6 @@ module Crosspack
   #   files:       { source_path => destination_inside_package (no leading /) }
   #   symlinks:    { link_path_inside_package => link_target }
   #   executables: [destination paths to chmod 0755]
-  class BuildError < StandardError; end
 
   # Convenience wrapper: Crosspack.pack(config: 'crosspack.yml',
   # target: Target.parse('debian-12'), version: '1.0-1')

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: crosspack
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Oleg Orlov
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-13 00:00:00.000000000 Z
-dependencies: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: 'One command, one config file, one target vocabulary: crosspack deps
   <target> verifies and installs the build host dependencies, crosspack build <target>
   runs the crosspack.yml build matrix entry and fans artifacts into builds/, crosspack
@@ -43,7 +56,10 @@ files:
 - lib/crosspack/builders/rpm.rb
 - lib/crosspack/builders/wix.rb
 - lib/crosspack/builds.rb
+- lib/crosspack/colors.rb
+- lib/crosspack/command_manifest.rb
 - lib/crosspack/config.rb
+- lib/crosspack/launcher.rb
 - lib/crosspack/manifest.rb
 - lib/crosspack/matrix.rb
 - lib/crosspack/package_manifest.rb
@@ -51,13 +67,13 @@ files:
 - lib/crosspack/resolver.rb
 - lib/crosspack/target.rb
 - lib/crosspack/version.rb
+- logo.png
 homepage: https://github.com/OrelSokolov/crosspack
 licenses:
 - Nonstandard
 metadata:
   source_code_uri: https://github.com/OrelSokolov/crosspack
   changelog_uri: https://github.com/OrelSokolov/crosspack/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -72,8 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: 'One config (crosspack.yml), staged pipeline: deps → build → pack native
   packages (deb/rpm/PKGBUILD/winget/cask)'