fix first release preflight flag

Author: Thanga-Ganapathy

README.md

@@ -65,7 +65,6 @@ cargo install --git https://github.com/Open-Tech-Foundation/release
 
 | Gap | Impact |
 | --- | --- |
-| `--first-release` is not wired through the version flow yet. | First-release ergonomics are still stricter than the CLI help implies. |
 | `publish` lifecycle hooks run per adapter, not once per full command. | Polyglot repos may run global `pre_publish` / `post_publish` hooks more than intended. |
 | `snapshot` is experimental. | Multi-adapter semantics, generated notes, rollback expectations, and workflow polish need more hardening. |
 | Generated `release.yml` still needs stronger validation. | It is useful scaffolding, but complex monorepos may need hand edits. |

crates/cli/tests/e2e.rs

@@ -155,6 +155,7 @@ fn version_then_publish_ships_exactly_the_computed_bumps() {
     git(root, &["add", "-A"]);
     git(root, &["commit", "-q", "-m", "init"]);
     git(root, &["branch", "-M", "main"]);
+    git(root, &["tag", "@x/core@1.0.0"]);
     git(root, &["tag", "@x/sdk@1.0.0"]);
 
     let remote = tempfile::tempdir().unwrap();

crates/cli/tests/version_flow.rs

@@ -12,11 +12,11 @@ use anyhow::Result;
 
 use otf_release_adapters::npm::{CommandOutput, CommandRunner, NpmAdapter};
 use otf_release_core::adapter::{Bump, Pkg};
+use otf_release_core::config::ReleaseConfig;
 use otf_release_core::forge::Forge;
 use otf_release_core::git::GitRepo;
 use otf_release_core::prompt::Prompt;
 use otf_release_core::version::{orchestrate, VersionOptions};
-use otf_release_core::config::ReleaseConfig;
 
 /// Every `npm` invocation "succeeds" (the version flow only calls `update_lockfile`).
 struct OkRunner;
@@ -118,7 +118,7 @@ fn write_workspace(root: &Path) {
     );
 }
 
-/// Init the repo on `main`, commit, and tag sdk so it isn't treated as a first release.
+/// Init the repo on `main`, commit, and tag publishable packages so they are not first releases.
 fn init_repo(root: &Path) {
     git(root, &["init", "-q"]);
     git(root, &["config", "user.email", "t@t"]);
@@ -127,6 +127,7 @@ fn init_repo(root: &Path) {
     git(root, &["add", "-A"]);
     git(root, &["commit", "-q", "-m", "init"]);
     git(root, &["branch", "-M", "main"]);
+    git(root, &["tag", "@x/core@1.0.0"]);
     git(root, &["tag", "@x/sdk@1.0.0"]);
 }
 

crates/core/src/preflight.rs

@@ -19,12 +19,29 @@ pub struct Violation {
     pub message: String,
 }
 
+/// Preflight behavior switches supplied by the caller.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct CheckOptions {
+    /// Permit publishable packages with no prior `name@x.y.z` tag.
+    pub allow_first_release: bool,
+}
+
 /// Run the gate. `selected` is the set of package names the user chose to bump (empty when
 /// preflight runs before the prompt). Returns every violation found; an empty vec means pass.
 pub fn check(
     repo: &dyn RepoState,
     packages: &[Pkg],
     selected: &[String],
+) -> Result<Vec<Violation>> {
+    check_with_options(repo, packages, selected, CheckOptions::default())
+}
+
+/// Run the gate with explicit behavior switches.
+pub fn check_with_options(
+    repo: &dyn RepoState,
+    packages: &[Pkg],
+    selected: &[String],
+    opts: CheckOptions,
 ) -> Result<Vec<Violation>> {
     let mut violations = Vec::new();
 
@@ -39,7 +56,10 @@ pub fn check(
         let pkg_dir = pkg.manifest_path.parent().unwrap_or_else(|| Path::new("."));
 
         let violation = match repo.last_tag(&pkg.name)? {
-            // First release: a publishable package with no prior tag must have notes.
+            // First releases are explicit so accidentally untagged packages do not slip through.
+            None if !opts.allow_first_release => {
+                Some("first release requires --first-release".to_string())
+            }
             None if empty => Some("first release but [Unreleased] is empty".to_string()),
             None => None,
             Some(tag) => {
@@ -143,9 +163,9 @@ mod tests {
             pkg(d, "core", true, Some(EMPTY)), // tag + commits + empty -> commits violation
             pkg(d, "utils", true, Some(WITH_NOTES)), // tag + commits + notes -> ok
             pkg(d, "sdk", true, Some(EMPTY)),  // tag, no commits, empty, selected -> selected
-            pkg(d, "new", true, Some(EMPTY)),  // no tag, empty -> first-release violation
-            pkg(d, "newgood", true, Some(WITH_NOTES)), // no tag, notes -> ok
-            pkg(d, "miss", true, None),        // no tag, missing changelog -> first-release
+            pkg(d, "new", true, Some(EMPTY)),  // no tag -> explicit first-release violation
+            pkg(d, "newgood", true, Some(WITH_NOTES)), // no tag -> explicit first-release violation
+            pkg(d, "miss", true, None),        // no tag -> explicit first-release violation
             pkg(d, "app", false, Some(EMPTY)), // private -> skipped
         ];
 
@@ -166,7 +186,7 @@ mod tests {
         let violations = check(&repo, &packages, &selected).unwrap();
         let msgs = messages(&violations);
 
-        assert_eq!(violations.len(), 4, "got: {msgs:?}");
+        assert_eq!(violations.len(), 5, "got: {msgs:?}");
         assert_eq!(
             msgs.get("core").unwrap(),
             "3 commit(s) since core@1.2.0 but [Unreleased] is empty"
@@ -177,17 +197,52 @@ mod tests {
         );
         assert_eq!(
             msgs.get("new").unwrap(),
-            "first release but [Unreleased] is empty"
+            "first release requires --first-release"
+        );
+        assert_eq!(
+            msgs.get("newgood").unwrap(),
+            "first release requires --first-release"
         );
         assert_eq!(
             msgs.get("miss").unwrap(),
-            "first release but [Unreleased] is empty"
+            "first release requires --first-release"
         );
         assert!(!msgs.contains_key("utils"));
-        assert!(!msgs.contains_key("newgood"));
         assert!(!msgs.contains_key("app"));
     }
 
+    #[test]
+    fn first_release_flag_allows_untagged_packages_but_still_requires_notes() {
+        let tmp = tempfile::tempdir().unwrap();
+        let d = tmp.path();
+        let packages = vec![
+            pkg(d, "new", true, Some(WITH_NOTES)),
+            pkg(d, "miss", true, None),
+        ];
+        let repo = FakeRepo {
+            tags: HashMap::new(),
+            counts: HashMap::new(),
+        };
+
+        let violations = check_with_options(
+            &repo,
+            &packages,
+            &[],
+            CheckOptions {
+                allow_first_release: true,
+            },
+        )
+        .unwrap();
+        let msgs = messages(&violations);
+
+        assert_eq!(violations.len(), 1, "got: {msgs:?}");
+        assert_eq!(
+            msgs.get("miss").unwrap(),
+            "first release but [Unreleased] is empty"
+        );
+        assert!(!msgs.contains_key("new"));
+    }
+
     #[test]
     fn clean_repo_has_no_violations() {
         let tmp = tempfile::tempdir().unwrap();

crates/core/src/version.rs

@@ -159,7 +159,14 @@ pub fn orchestrate_many(
         .iter()
         .flat_map(|ctx| ctx.packages.iter().cloned())
         .collect();
-    let violations = preflight::check(repo, &all_packages, &[])?;
+    let violations = preflight::check_with_options(
+        repo,
+        &all_packages,
+        &[],
+        preflight::CheckOptions {
+            allow_first_release: opts.first_release,
+        },
+    )?;
     if !violations.is_empty() {
         bail!("{}", preflight::format_violations(&violations));
     }

docs/commands/version.md

@@ -9,7 +9,7 @@ otf-release version [--dry-run] [--first-release]
 | Flag | Effect |
 | --- | --- |
 | `--dry-run` | Compute and print the plan ([summary](#5-summary--confirm)), write nothing. |
-| `--first-release` | Reserved for first-release ergonomics; currently exposed by the CLI but not wired through the flow. |
+| `--first-release` | Permit publishable packages with no prior `name@x.y.z` tag. Curated mode still requires release notes for packages you want to release. |
 
 Implemented in `crates/core/src/version.rs`.
 

docs/preflight.md

@@ -29,7 +29,8 @@ don't falsely mark a package as changed.
 | --- | --- |
 | Commits since last tag (scoped to pkg path) **but** `[Unreleased]` empty/missing | ✗ **ABORT** |
 | Selected for a bump **but** `[Unreleased]` empty | ✗ **ABORT** |
-| No last tag **and** publishable (first release) | Require `[Unreleased]` (later: explicit `--first-release`) |
+| No last tag **and** publishable (first release) without `--first-release` | ✗ **ABORT** |
+| No last tag **and** publishable with `--first-release` | Require release notes in curated mode |
 | `[Unreleased]` present **with** commits | ✓ OK |
 | Commits in a **private** package | ✓ OK — no changelog demanded |