feat(up): --to <tag> pin/downgrade + document stable rollback

8sync-dev · 8sync-dev · commit bbac11bae950 · 2026-05-23T23:58:08.000+07:00
`8sync up --to v0.6.10` downloads that specific release asset instead
of latest. Enables: (a) reproducible deployment across team machines,
(b) explicit rollback after a regression, (c) the recommended
'restore HyDE-only stable baseline' recipe.

selfup::install_tag(tag) shares the same atomic-replace flow as
run_self_update (curl → /tmp → chmod 755 → rename). Strips/adds 'v'
prefix so both 'v0.6.10' and '0.6.10' work.

docs/known-issues.md now leads with the stable rollback recipe so any
user landing on the doc sees:

  8sync up --to v0.6.10 &amp;&amp; 8sync setup --reset-shells

v0.6.11.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/cli"]
 
 [workspace.package]
-version = "0.6.10"
+version = "0.6.11"
 edition = "2021"
 license = "MIT"
 authors = ["8sync-dev <8sync.dev.1111@gmail.com>"]
diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs
@@ -50,7 +50,7 @@ enum Cmd {
 
     /// Full update: 8sync + omp + system pkgs (pacman/AUR) + rustup + flatpak. See `8sync up -h`.
     #[command(alias = "update")]
-    Up,
+    Up(verbs::up::Args),
 
     /// Health-check; report what's installed and what's missing
     Doctor,
@@ -102,7 +102,7 @@ fn main() -> Result<()> {
     let cli = Cli::parse();
     if !matches!(
         cli.cmd,
-        Some(Cmd::Up) | Some(Cmd::Setup(_)) | Some(Cmd::Help)
+        Some(Cmd::Up(_)) | Some(Cmd::Setup(_)) | Some(Cmd::Help)
     ) {
         verbs::selfup::auto_check_notice();
     }
@@ -112,7 +112,7 @@ fn main() -> Result<()> {
             Ok(())
         }
         Some(Cmd::Setup(a))   => verbs::setup::run(a),
-        Some(Cmd::Up)         => verbs::up::run(),
+        Some(Cmd::Up(a))      => verbs::up::run(a),
         Some(Cmd::Doctor)     => verbs::doctor::run(),
         Some(Cmd::Here(a))    => verbs::here::run(a),
         Some(Cmd::Ai(a))      => verbs::ai::run(a),
diff --git a/crates/cli/src/verbs/selfup.rs b/crates/cli/src/verbs/selfup.rs
@@ -130,3 +130,33 @@ pub fn run_self_update(force: bool) -> Result<bool> {
     ui::ok(&format!("installed {} → {}", tag, bin_dst.display()));
     Ok(true)
 }
+
+/// Install a specific tag (e.g. `v0.6.10`). Used by `8sync up --to <tag>`
+/// for reproducibility / explicit downgrade.
+pub fn install_tag(tag: &str) -> Result<bool> {
+    ui::step(&format!("Self-update → pinned tag {}", tag));
+    let tag = tag.strip_prefix('v').map(|t| format!("v{}", t)).unwrap_or_else(|| format!("v{}", tag));
+    let asset_url = format!(
+        "https://github.com/{}/{}/releases/download/{}/{}{}{}",
+        REPO_OWNER, REPO_NAME, tag, ASSET_PREFIX, tag, ASSET_SUFFIX
+    );
+    let bin_dst = dirs::home_dir()
+        .ok_or_else(|| anyhow!("no home dir"))?
+        .join(".local/bin/8sync");
+    std::fs::create_dir_all(bin_dst.parent().unwrap())?;
+    let tmp = bin_dst.with_extension(format!("new.{}", std::process::id()));
+    ui::info(&format!("$ curl -fsSL --max-time 120 -o {} {}", tmp.display(), asset_url));
+    let status = Command::new("curl")
+        .args(["-fsSL", "--max-time", "120", "-o", tmp.to_str().unwrap(), &asset_url])
+        .status()?;
+    if !status.success() {
+        let _ = std::fs::remove_file(&tmp);
+        bail!("download failed: {}", asset_url);
+    }
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(&tmp, std::fs::Permissions::from_mode(0o755))?;
+    std::fs::rename(&tmp, &bin_dst)?;
+    let _ = std::fs::write(last_seen_tag_file(), &tag);
+    ui::ok(&format!("installed {} → {}", tag, bin_dst.display()));
+    Ok(true)
+}
diff --git a/crates/cli/src/verbs/up.rs b/crates/cli/src/verbs/up.rs
@@ -1,16 +1,37 @@
-// `8sync up` — update the 8sync binary from the latest GitHub Release.
+// `8sync up` — update the 8sync binary from a GitHub Release.
 //
-// Decoupled from omp on purpose: omp self-updates via `omp update` (or its
-// own installer). Touching it here would silently change a runtime the user
-// is actively in the middle of a chat with. System pkgs (pacman/AUR) are
-// untouched too — user runs `paru -Syu` on their own schedule.
+// Default: pull the latest tag. With `--to <tag>` pin a specific release
+// for reproducibility / downgrade (e.g. `8sync up --to v0.6.10` to roll
+// every machine to the known-stable HyDE-only baseline).
+//
+// Decoupled from omp on purpose: omp self-updates via `omp update`. System
+// pkgs (pacman/AUR) untouched — user runs `paru -Syu` on their own schedule.
 
 use anyhow::Result;
+use clap::Args as ClapArgs;
+
 use crate::{ui, verbs::selfup};
 
-pub fn run() -> Result<()> {
+#[derive(ClapArgs, Debug)]
+#[command(
+    after_help = indoc::indoc! {"
+        EXAMPLES
+          8sync up                       update to the latest GitHub Release
+          8sync up --to v0.6.10          pin/downgrade to a specific tag
+    "}
+)]
+pub struct Args {
+    /// Pin to a specific release tag (e.g. `v0.6.10`). Default: latest.
+    #[arg(long, value_name = "TAG")]
+    pub to: Option<String>,
+}
+
+pub fn run(a: Args) -> Result<()> {
     ui::header("8sync up");
-    let updated = selfup::run_self_update(true)?;
+    let updated = match a.to {
+        Some(tag) => selfup::install_tag(&tag)?,
+        None      => selfup::run_self_update(true)?,
+    };
     if updated {
         ui::info("done — re-run any 8sync command to pick up the new binary");
     }
diff --git a/docs/known-issues.md b/docs/known-issues.md
@@ -1,3 +1,31 @@
+# 🛟 Stable baseline rollback (any user, any time)
+
+The known-stable baseline is **v0.6.10+ on HyDE-only, no overlay**. To
+return any machine to this state regardless of what was attempted before:
+
+```sh
+# Already have 8sync
+8sync up --to v0.6.10
+8sync setup --reset-shells
+
+# Add --purge-packages to also pacman -Rns caelestia-shell, quickshell, aubio
+8sync setup --reset-shells --purge-packages
+```
+
+Fresh install (no 8sync yet):
+
+```sh
+curl -fsSL -o ~/.local/bin/8sync \
+  https://github.com/8-Sync-Dev/su-code/releases/download/v0.6.10/8sync-v0.6.10-linux-x86_64 \
+  && chmod +x ~/.local/bin/8sync \
+  && 8sync setup --reset-shells
+```
+
+`--reset-shells` is idempotent: safe to re-run; safe on a machine that
+never had end-4 / caelestia installed in the first place.
+
+---
+
 # Known issues & resolutions
 
 Living log of HyDE / Caelestia / end-4 conflicts we've hit and the fix that
