feat: drive cross-compiled matrix packages with matrix/build subcommands

Reconcile the three naming systems for a matrix binary (Rust triple, CI
runner, Node process.platform-process.arch stage dir) in a built-in target
registry, so the tool — not hand-edited YAML — owns the mapping that decides
whether an install can find the published binary.

- config: enrich Target with triple/runner/stage_as/ext/cross (registry-filled
  from name/arch) and add per-package bin_name/compress fields.
- add `otf-release matrix` (emit the GH matrix JSON from release.toml) and
  `otf-release build --package --target` (cross-compile one target, then brotli-
  stage it at bin/<stage_as>/<bin><ext>[.br]).
- init: regenerate the matrix workflow as a dynamic matrix-<pkg> -> build-<pkg>
  -> publish DAG that calls the new subcommands; no more `# edit me` target list
  or untemplated build command. Publish merges each target's artifact back into
  .artifacts/<pkg> before packing.
- publish: refuse a matrix package whose per-platform binaries were not staged,
  replacing the removed private:true guard.
- npm: publish prereleases under their dist-tag (1.2.3-dev.x -> --tag dev);
  unify the auth secret to NPM_TOKEN across the release and snapshot workflows.
- docs + CHANGELOG updated for the new flow.

Author: Thanga-Ganapathy

CHANGELOG.md

@@ -8,14 +8,34 @@ adheres to [Semantic Versioning](https://semver.org/). Work in progress lives un
 
 ## [Unreleased]
 
+### Added
+- **matrix/build commands** — Added `otf-release matrix` (emits the GitHub Actions build matrix
+  from `release.toml`) and `otf-release build --package --target` (cross-compiles one target and
+  stages its binary). The generated matrix workflow now drives both, so cross-compiled binary
+  packages build and publish with no hand-edited YAML.
+- **target registry** — `[[package.targets]]` now reconciles the Rust triple, the CI runner, and
+  the Node `process.platform-process.arch` stage directory (`stage_as`), plus `ext`/`cross`. A
+  hand-written file may list just `name`/`arch`; the built-in registry fills the rest. Added
+  per-package `bin_name` and `compress` (brotli) fields.
+
 ### Changed
+- **init** — The matrix workflow is regenerated as a dynamic `matrix-<pkg>` → `build-<pkg>` →
+  `publish` DAG that calls `otf-release matrix`/`build`, removing the `# edit me` target list and
+  the untemplated build command. Staged binaries land at `bin/<platform>-<arch>/<bin>[.br]`, the
+  exact path an npm package's install-time resolver reads.
 - **init** — Removed snapshot tag prompting and `snapshot.yml` generation from the setup flow;
   snapshot releases remain available through the dedicated `snapshot` command.
 - **changelog config** — Added `changelog_scope` with strict root-level or per-package changelog
   modes, updated `init` to ask only where release notes are maintained, and made package-scope
   GitHub Release bodies combine notes from all configured package changelogs.
 
 ### Fixed
+- **publish** — A `matrix` publish-mode package is now refused if its per-platform binaries were
+  not staged under `--artifacts-dir`, replacing the removed `private:true` guard so a binary-less
+  package can never reach the registry.
+- **npm adapter** — A prerelease version publishes under its own dist-tag (`1.2.3-dev.<hash>` →
+  `--tag dev`) instead of `latest`.
+- **init** — Unified the npm auth secret to `NPM_TOKEN` across the release and snapshot workflows.
 - **publish** — Made tag creation and GitHub Release creation idempotent so interrupted publish
   runs can be resumed without failing on already-created remote state.
 - **cargo adapter** — Treated missing `cargo info` package results as unpublished and aligned the

Cargo.lock

@@ -35,7 +35,9 @@ cargo install --git https://github.com/Open-Tech-Foundation/release
 | --- | --- | --- |
 | `otf-release init` | ✅ Supported | Interactive setup. Writes `release.toml` and `.github/workflows/release.yml`. |
 | `otf-release version` | ✅ Supported | Interactive local release flow. Use `--dry-run` to preview the plan without writing files, and `--first-release` when a package has no prior matching tag. |
-| `otf-release publish` | ✅ Supported | CI-oriented publish flow. Publishes in dependency order, skips already-published versions, creates `name@version` tags, and creates package releases from notes. |
+| `otf-release publish` | ✅ Supported | CI-oriented publish flow. Publishes in dependency order, skips already-published versions, creates `name@version` tags, and creates package releases from notes. Refuses to publish a matrix package whose per-platform binaries weren't staged. |
+| `otf-release matrix` | ✅ Supported | CI helper. Prints the GitHub Actions build matrix (JSON) for a matrix package from `release.toml`, so `release.yml` never carries a hand-maintained target list. |
+| `otf-release build` | ✅ Supported | CI helper. Builds one matrix target (`--package`/`--target`), cross-compiling as needed, and stages the binary at `bin/<platform>-<arch>/<bin>[.br]` for publish. |
 | `otf-release snapshot` | 🧪 Experimental | Creates hash-based prerelease versions such as `1.2.3-snapshot.a1b2c3d` and publishes them from CI. |
 | `otf-release config` | ✅ Supported | Interactive editor for hooks, ecosystems, package build fields, generic package fields, provider, snapshot tag, changelog scope/strategy, and GitHub Release notes. |
 | `otf-release upgrade` | ◐ Partial | Regenerates `release.yml` from the current `release.toml`. |

README.md

@@ -248,18 +248,30 @@ impl Adapter for NpmAdapter {
                 .with_context(|| format!("staging assets for {}", pkg.name))?;
         }
 
-        let out = self.runner.run(
-            "npm",
-            &["publish", "--access", "public", "--no-workspaces"],
-            pkg_dir,
-        )?;
+        // A prerelease version (e.g. a `1.2.3-dev.<hash>` snapshot) must publish under its own
+        // dist-tag, never `latest`, so an automated snapshot never becomes the default install.
+        let mut args = vec!["publish", "--access", "public", "--no-workspaces"];
+        let tag = dist_tag(&pkg.version);
+        if let Some(tag) = &tag {
+            args.push("--tag");
+            args.push(tag);
+        }
+        let out = self.runner.run("npm", &args, pkg_dir)?;
         if !out.success {
             bail!("`npm publish` for {} failed:\n{}", pkg.name, out.stderr);
         }
         Ok(())
     }
 }
 
+/// The npm dist-tag for a version: a prerelease's leading identifier (`1.2.3-dev.abc` → `dev`,
+/// `2.0.0-beta.1` → `beta`), or `None` for a normal release (which publishes under `latest`).
+fn dist_tag(version: &str) -> Option<String> {
+    let pre = version.split_once('-')?.1;
+    let id = pre.split('.').next().unwrap_or(pre);
+    (!id.is_empty()).then(|| id.to_string())
+}
+
 fn skip_reason(manifest: &Manifest) -> Result<Option<String>> {
     let json = manifest.json_value()?;
     let missing_name = json.get("name").and_then(Value::as_str).is_none();
@@ -598,6 +610,36 @@ mod tests {
         assert_eq!(calls[0].2, PathBuf::from("/repo/packages/a"));
     }
 
+    #[test]
+    fn prerelease_publishes_under_its_dist_tag() {
+        let fake = FakeRunner::new(true, "", "");
+        let adapter = NpmAdapter::with_runner("/repo", Box::new(fake.clone()));
+        let mut pkg = dummy_pkg("@x/a", "/repo/packages/a/package.json");
+        pkg.version = "1.2.3-dev.abc1234".to_string();
+
+        adapter.publish(&pkg, None).unwrap();
+        let calls = fake.calls.lock().unwrap();
+        assert_eq!(
+            calls[0].1,
+            [
+                "publish",
+                "--access",
+                "public",
+                "--no-workspaces",
+                "--tag",
+                "dev"
+            ]
+        );
+    }
+
+    #[test]
+    fn dist_tag_only_for_prereleases() {
+        assert_eq!(dist_tag("1.2.3"), None);
+        assert_eq!(dist_tag("1.2.3-dev.abc"), Some("dev".to_string()));
+        assert_eq!(dist_tag("2.0.0-beta.1"), Some("beta".to_string()));
+        assert_eq!(dist_tag("2.0.0-rc"), Some("rc".to_string()));
+    }
+
     #[test]
     fn reformat_range_preserves_operator() {
         assert_eq!(reformat_range("^1.0.0", "2.0.0"), "^2.0.0");

crates/adapters/src/npm/mod.rs

@@ -128,6 +128,21 @@ enum Command {
     },
     /// Edit release.toml interactively.
     Config,
+    /// CI: print the GitHub Actions build matrix (JSON) for a matrix package from release.toml.
+    Matrix {
+        /// Which matrix package to emit for (required when more than one exists).
+        #[arg(long)]
+        package: Option<String>,
+    },
+    /// CI: build one matrix target and stage its binary under `.artifacts/`.
+    Build {
+        /// The matrix package to build.
+        #[arg(long)]
+        package: String,
+        /// The target as `name/arch` (e.g. linux/aarch64).
+        #[arg(long)]
+        target: String,
+    },
     /// Non-interactive, CI: automated ephemeral release via short git hashes.
     Snapshot,
     /// Update otf-release to the latest version.
@@ -177,6 +192,19 @@ fn run() -> Result<()> {
             otf_release_core::config_cmd::orchestrate(&root)?;
             Ok(())
         }
+        Command::Matrix { package } => {
+            let config = ReleaseConfig::load(&root)?;
+            println!(
+                "{}",
+                otf_release_core::matrix::matrix_json(&config, package.as_deref())?
+            );
+            Ok(())
+        }
+        Command::Build { package, target } => {
+            let config = ReleaseConfig::load(&root)?;
+            otf_release_core::build::run(&config, &root, &package, &target)?;
+            Ok(())
+        }
         Command::Snapshot => {
             let config = ReleaseConfig::load(&root)?;
             let factory = CliAdapterFactory {
@@ -232,6 +260,8 @@ fn run() -> Result<()> {
             // build-only packages ship via the GitHub Release the workflow creates, never a
             // registry — so `publish` skips them.
             let skip = config.build_only_names();
+            // matrix packages must have their per-platform binaries staged before they publish.
+            let require_staged = config.matrix_publish_names();
             let adapters: Vec<Box<dyn Adapter>> = config
                 .adapters
                 .iter()
@@ -247,6 +277,7 @@ fn run() -> Result<()> {
                     dry_run,
                     tag_format: config.tag_format.clone(),
                     skip,
+                    require_staged,
                     changelog_scope: config.changelog_scope.clone(),
                 },
                 &config.hooks,

crates/cli/src/main.rs

@@ -452,3 +452,51 @@ fn multi_adapter_publish_runs_hooks_once_for_the_whole_command() {
     assert_eq!(a.published.borrow().as_slice(), ["a@1.0.0".to_string()]);
     assert_eq!(b.published.borrow().as_slice(), ["b@1.0.0".to_string()]);
 }
+
+/// A matrix publish-mode package must never reach the registry without its per-platform binaries.
+/// With the package named in `require_staged` and no staged tree under `--artifacts-dir`, publish
+/// must hard-fail instead of shipping a binary-less, broken package.
+#[test]
+fn matrix_package_without_staged_binaries_is_refused() {
+    let tmp = tempfile::tempdir().unwrap();
+    let root = tmp.path();
+    write(
+        root.join("package.json"),
+        r#"{ "name": "root", "private": true, "workspaces": ["packages/*"] }"#,
+    );
+    write(
+        root.join("packages/wc/package.json"),
+        "{\n  \"name\": \"@x/wc\",\n  \"version\": \"1.0.0\"\n}\n",
+    );
+    write(
+        root.join("packages/wc/CHANGELOG.md"),
+        "# Changelog\n\n## [1.0.0] - 2024-01-01\n- notes\n",
+    );
+
+    let runner = PubRunner::new(&[]);
+    let adapter = NpmAdapter::with_runner(root, Box::new(runner.clone()));
+    let git = FakeGit::default();
+    let forge = FakeForge::default();
+    let hooks = otf_release_core::config::Hooks::default();
+    let hook_runner = otf_release_core::hooks::fakes::FakeHookRunner::new();
+
+    // An artifacts dir that exists but holds nothing for @x/wc.
+    let artifacts = root.join(".artifacts");
+    fs::create_dir_all(&artifacts).unwrap();
+
+    let opts = PublishOptions {
+        tag_format: "{name}@{version}".to_string(),
+        artifacts_dir: Some(artifacts),
+        require_staged: vec!["@x/wc".to_string()],
+        ..PublishOptions::default()
+    };
+
+    let err = orchestrate(&adapter, &git, &forge, root, &opts, &hooks, &hook_runner).unwrap_err();
+    assert!(
+        err.to_string().contains("binary-less"),
+        "expected a binary-less refusal, got: {err}"
+    );
+    // Nothing was published, tagged, or released.
+    assert!(runner.publish_log.lock().unwrap().is_empty());
+    assert!(git.tags.borrow().is_empty());
+}

crates/cli/tests/publish_flow.rs

@@ -15,6 +15,8 @@ serde.workspace = true
 toml.workspace = true
 inquire.workspace = true
 ratatui.workspace = true
+brotli = "7"
+glob = "0.3"
 
 [dev-dependencies]
 tempfile = "3"