The design language that makes your AI harness better at design.
JavaScript
Keep existing skills when install cannot reach the bundle (#1138) (#1144)
Paul Bakausd0a1185c0587
diff --git a/crates/skills/src/bundle.rs b/crates/skills/src/bundle.rsindex fb66da1c8..c3a14954e 100644--- a/crates/skills/src/bundle.rs+++ b/crates/skills/src/bundle.rs@@ -353,12 +353,36 @@ fn extract_zip_from<R: Read + std::io::Seek>(reader: R, target_dir: &str, cwd: &/// both the zip and the extracted tree; any failure removes the whole/// staging dir before rethrowing. Returns the staging dir (caller removes).pub fn download_and_extract_bundle(sys: &Sys) -> Result<String, BundleError> {+ #[cfg(test)]+ if let Some(forced) = test_seam::take() {+ return forced;+ }if let Some(local) = sys.env.get("IMPECCABLE_BUNDLE_PATH").filter(|v| !v.is_empty()) {return copy_or_extract_local_bundle(sys, local).map_err(BundleError::Local);}download_remote_bundle(sys, &mut ureq_fetch, bundle_signature::trusted_keys())}+/// Lets in-crate command tests stand in for the network: the next+/// `download_and_extract_bundle` on this thread returns the forced result.+#[cfg(test)]+pub(crate) mod test_seam {+ use super::BundleError;+ use std::cell::RefCell;++ thread_local! {+ static NEXT: RefCell<Option<Result<String, BundleError>>> = const { RefCell::new(None) };+ }++ pub(crate) fn force(result: Result<String, BundleError>) {+ NEXT.with(|n| *n.borrow_mut() = Some(result));+ }++ pub(super) fn take() -> Option<Result<String, BundleError>> {+ NEXT.with(|n| n.borrow_mut().take())+ }+}+/// Why no bundle was produced. A remote failure names the step that failed,/// so a network problem never reads as a signature problem (#1138).#[derive(Debug)]@@ -376,10 +400,23 @@ pub enum BundleError {}impl BundleError {- /// A failed remote bundle, which `install` treats as fatal even over an- /// existing installation (#734).- pub fn is_remote(&self) -> bool {- !matches!(self, BundleError::Local(_))+ /// A bundle that failed authentication, which `install` treats as fatal+ /// even over an existing installation (#734). Every other failure over an+ /// existing installation (offline, a stall, an HTTP error, a full disk)+ /// leaves the installed skills as they are and exits 0 (#1138).+ pub fn is_fatal_over_existing_install(&self) -> bool {+ matches!(self, BundleError::Verify(_))+ }++ /// The failure without the "nothing was installed" advice, for the+ /// non-fatal line printed over an existing installation.+ pub fn summary(&self) -> String {+ match self {+ BundleError::Download(e) => format!("Could not download skill bundle: {e}"),+ BundleError::Verify(e) => format!("{}{e}", bundle_signature::ERROR_PREFIX),+ BundleError::Unpack(e) => format!("Could not unpack skill bundle: {e}"),+ BundleError::Local(e) => e.clone(),+ }}fn into_detail(self) -> String {@@ -1173,7 +1210,10 @@ mod tests {};let error = download_file_capped("https://example.com/b.zip", "/nonexistent/impeccable/b.zip", &mut fetch, MAX_DOWNLOAD_BYTES).unwrap_err();assert!(matches!(error, BundleError::Unpack(_)), "a failed save is not a download failure: {error}");- assert!(!BundleError::Local("Local bundle not found: x".into()).is_remote());+ assert!(!BundleError::Local("Local bundle not found: x".into()).is_fatal_over_existing_install());+ assert!(!BundleError::Download("connection refused".into()).is_fatal_over_existing_install());+ assert!(!BundleError::Unpack("disk full".into()).is_fatal_over_existing_install());+ assert!(BundleError::Verify("digest mismatch".into()).is_fatal_over_existing_install());}#[test]diff --git a/crates/skills/src/commands.rs b/crates/skills/src/commands.rsindex 6e9f5c9b5..5ceb53467 100644--- a/crates/skills/src/commands.rs+++ b/crates/skills/src/commands.rs@@ -621,12 +621,12 @@ fn install(flags: &[String], io: &mut Io) -> R<()> {match bundle::download_and_extract_bundle(&sys) {Ok(dir) => bundle_dir = Some(dir),Err(e) => {- if e.is_remote()+ if e.is_fatal_over_existing_install()|| !missing_hook_targets.is_empty() || !missing_selected_targets.is_empty() {return Err(e.into());}update_check_skipped = true;- out(io, &format!("Could not check for skill updates: {e}"));+ out(io, &format!("Could not check for skill updates: {}", e.summary()));}}}@@ -952,3 +952,112 @@ fn update(flags: &[String], io: &mut Io) -> R<()> {Err(other) => Err(other),}}++#[cfg(test)]+mod offline_install_tests {+ //! `install` over an existing installation when the bundle cannot be+ //! fetched (#1138): only an authentication failure is fatal.++ use std::collections::HashMap;+ use std::path::PathBuf;++ use crate::bundle::{test_seam, BundleError};+ use crate::engine_binary::platform_tag;+ use impeccable_common::Io;++ struct Fixture {+ root: String,+ project: String,+ env: HashMap<String, String>,+ }++ impl Drop for Fixture {+ fn drop(&mut self) {+ std::fs::remove_dir_all(&self.root).ok();+ }+ }++ fn fixture(name: &str) -> Fixture {+ let nanos = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_nanos()).unwrap_or(0);+ let root = std::env::temp_dir().join(format!("impeccable-{name}-{}-{nanos}", std::process::id())).to_string_lossy().into_owned();+ let project = format!("{root}/project");+ let home = format!("{root}/home");+ let tmp = format!("{root}/tmp");+ for d in [&project, &home, &tmp] {+ std::fs::create_dir_all(d).unwrap();+ }+ std::fs::create_dir_all(format!("{project}/.git")).unwrap();+ let env: HashMap<String, String> = [("HOME", &home), ("USERPROFILE", &home), ("TMPDIR", &tmp), ("TEMP", &tmp)]+ .into_iter()+ .map(|(k, v)| (k.to_string(), v.clone()))+ .collect();+ Fixture { root, project, env }+ }++ fn run(fx: &Fixture, extra_env: &[(&str, &str)]) -> (i32, String, String) {+ let mut env = fx.env.clone();+ for (k, v) in extra_env {+ env.insert((*k).into(), (*v).into());+ }+ let (mut io, captured) = Io::captured("", PathBuf::from(&fx.project), env);+ let args: Vec<String> = ["install", "-y", "--providers=claude", "--scope=project", "--no-hooks"].map(String::from).into();+ let code = crate::run(&args, &mut io);+ let stdout = String::from_utf8_lossy(&captured.stdout.borrow()).into_owned();+ let stderr = String::from_utf8_lossy(&captured.stderr.borrow()).into_owned();+ (code, stdout, stderr)+ }++ /// Installs from a local bundle dir, so the next run finds existing skills.+ fn install_existing(fx: &Fixture) -> Option<String> {+ let (os, arch) = platform_tag()?;+ let bundle = format!("{}/bundle", fx.root);+ let skill = format!("{bundle}/.claude/skills/impeccable");+ std::fs::create_dir_all(format!("{skill}/scripts/bin/{os}-{arch}")).unwrap();+ std::fs::write(format!("{skill}/SKILL.md"), "---\nname: impeccable\nversion: 9.9.9\n---\n# impeccable\n").unwrap();+ // A staged engine binary keeps install_engine_binaries off the network.+ std::fs::write(format!("{skill}/scripts/bin/{os}-{arch}/impeccable"), "#!/bin/sh\nexit 0\n").unwrap();+ let (code, stdout, stderr) = run(fx, &[("IMPECCABLE_BUNDLE_PATH", &bundle)]);+ assert_eq!(code, 0, "seed install failed.\nstdout:\n{stdout}\nstderr:\n{stderr}");+ Some(format!("{}/.claude/skills/impeccable/SKILL.md", fx.project))+ }++ #[test]+ fn offline_over_existing_skills_leaves_them_and_exits_zero() {+ let fx = fixture("offline-existing");+ let Some(skill_md) = install_existing(&fx) else { return };+ let before = std::fs::read(&skill_md).unwrap();++ test_seam::force(Err(BundleError::Download("Network Error: Dns Failed: resolve dns name 'impeccable.style:443'".into())));+ let (code, stdout, stderr) = run(&fx, &[]);+ assert_eq!(code, 0, "stdout:\n{stdout}\nstderr:\n{stderr}");+ assert!(stdout.contains("Could not check for skill updates: Could not download skill bundle: Network Error"), "{stdout}");+ assert!(stdout.contains("Existing skills were left unchanged."), "{stdout}");+ assert!(!stdout.contains("verify") && !stdout.contains("report it"), "{stdout}");+ assert_eq!(std::fs::read(&skill_md).unwrap(), before, "existing skill was modified");+ }++ #[test]+ fn failed_verification_over_existing_skills_is_fatal() {+ let fx = fixture("verify-existing");+ let Some(skill_md) = install_existing(&fx) else { return };+ let before = std::fs::read(&skill_md).unwrap();++ test_seam::force(Err(BundleError::Verify("ZIP digest does not match the signed release".into())));+ let (code, stdout, stderr) = run(&fx, &[]);+ assert_eq!(code, 1, "stdout:\n{stdout}\nstderr:\n{stderr}");+ assert!(stderr.contains("Install check failed: Could not verify skill bundle: ZIP digest"), "{stderr}");+ assert!(!stdout.contains("Could not check for skill updates"), "{stdout}");+ assert_eq!(std::fs::read(&skill_md).unwrap(), before, "existing skill was modified");+ }++ #[test]+ fn offline_fresh_install_fails_as_a_download() {+ let fx = fixture("offline-fresh");+ test_seam::force(Err(BundleError::Download("Network Error: Dns Failed".into())));+ let (code, stdout, stderr) = run(&fx, &[]);+ assert_eq!(code, 1, "stdout:\n{stdout}\nstderr:\n{stderr}");+ assert!(stderr.contains("Download failed: Could not download skill bundle: Network Error"), "{stderr}");+ assert!(!stderr.contains("verify"), "{stderr}");+ assert!(!std::path::Path::new(&format!("{}/.claude/skills/impeccable", fx.project)).exists());+ }+}diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.mdindex 52ba13645..f97fd8d92 100644--- a/docs/CLI-CONTRACT.md+++ b/docs/CLI-CONTRACT.md@@ -489,7 +489,7 @@ retain their local-development trust behavior. See [bundle signing](BUNDLE-SIGNIA Claude user-scope hook write also prunes obsolete Impeccable entries from the current project's `.claude/settings.local.json`, preventing a stale project hook from firing alongside the user hook.GitHub Copilot hook (`.github/hooks/impeccable.json` in the project, `bash` key): a project install keeps the bundle's portable `$(git rev-parse --show-toplevel)/.github/skills/impeccable/scripts/impeccable` command; a user-scope install rewrites it to the home launcher (`$HOME/.github/skills/impeccable/scripts/impeccable` on POSIX, the resolved profile path with forward slashes on Windows), unless the project ships its own `.github/skills/impeccable/scripts/impeccable`, whose committed portable manifest is left as is. In user scope a project manifest that names the portable path while the project has no Copilot skill does not count as installed, so a repeat install rewrites it.Every shipped `impeccable.cmd` (provider dirs, `plugin/`, `cursor-plugin/`, the dist zips) has CRLF line endings: `.gitattributes` sets `*.cmd text eol=crlf`, the build writes batch files with CRLF, and `bun run build` fails on any emitted `.cmd` with a bare LF (#1098).- Already installed (and not `--force`): `Impeccable skills are already installed (found in ${provider}/).`; compares tree hashes (`sha256` of file content with `\.(claude|cursor|...)\/skills\/` normalized to `.PROVIDER/skills/`); if differs → refresh + `Updated ${n} skill(s) to v${v}.`; missing hooks repaired; else `Skills are up to date (v${v}).` + `Run with --force to reinstall.`; offline → `Could not check for skill updates: ${msg}` + `Existing skills were left unchanged.`; ends `Done!` or the above; `exit 0`. Version read from `^version:\s*(.+)$` in installed `impeccable/SKILL.md`.+ Already installed (and not `--force`): `Impeccable skills are already installed (found in ${provider}/).`; compares tree hashes (`sha256` of file content with `\.(claude|cursor|...)\/skills\/` normalized to `.PROVIDER/skills/`); if differs → refresh + `Updated ${n} skill(s) to v${v}.`; missing hooks repaired; else `Skills are up to date (v${v}).` + `Run with --force to reinstall.`; a bundle that cannot be fetched or unpacked (offline, connect error, HTTP status, stall, size cap, a failed save) → `Could not check for skill updates: Could not download skill bundle: ${msg}` (or `Could not unpack skill bundle: ${msg}`, without the retry advice) + `Existing skills were left unchanged.`, skills untouched, exit 0, unless a selected provider or a hook manifest is missing and needs the bundle, which stays fatal; a bundle that fails verification stays fatal over an existing install too: `Install check failed: Could not verify skill bundle: ${msg}...` → exit 1 (#1138); ends `Done!` or the above; `exit 0`. Version read from `^version:\s*(.+)$` in installed `impeccable/SKILL.md`.- **update flags**: `-y|--yes`, `--force`, `--no-hooks`, scope flags as above (unknown → `Unknown update scope: ${v}. Use --project or --user.`). Resolves project vs user installs holding an `impeccable`/`*-impeccable`/`teach-impeccable` skill; none → `No impeccable skill folders found in this project or at the user level.` + `Run \`npx impeccable install\` to install first.`, exit 1; both → prompt `Update which? [project]/user: ` (non-TTY defaults project). Prints `Updating the ${label} install: ${root} (${providers})`, linked providers note, `Checking for updates...`; up to date → `Skills are up to date (vX).` [+hooks] + `Nothing else to do.`, exit 0; else `Found skills in: ...`, prompt `Update skills in N provider folder(s)? (Y/n) ` (n/no → `Aborted.` exit 0), refresh, `Updated N skill(s) to vX.`, `Done!`. Hook manifests follow install's placement: in user scope the Claude hook is `~/.claude/settings.json` and every other provider's manifest (`.cursor/hooks.json`, `.codex/hooks.json`, `.grok/hooks/impeccable.json`, ...) is the current project's, rewritten against the home skill. Hook consent is read from (and a prompt's answer written to) that same project root, so a project that declined hooks gets none from `update --user -y`. The stale-manifest repair (`repair_stale_hook_manifests`, including the retired Cursor gate) runs on those project manifests regardless of hook consent. An older `update --user` wrote non-Claude manifests under home instead; those are repaired in place too, never pruned, because a home manifest is global. When a home and a project hook (or a plugin and a project hook) both fire for one edit, the `hook` verb's event claim lets only one of them scan (see `hook`).- **link**: `--source=<path>` (default `.impeccable`), `--providers`, `--force`, `-y`. Source must contain `dist/universal/` or provider `*/skills` dirs, else `Could not find compiled skills in ${src}. Expected dist/universal/ or provider skill folders.` Prompts `Link impeccable skills into N folder(s)? (Y/n) `; creates relative dir symlinks; existing non-link skipped with warning unless `--force`; output `Linked impeccable into: ... (N linked, N already linked, N skipped).` + submodule hint.- **check**: not installed → `Impeccable is not installed in this project.` + `Run \`npx impeccable install\` to install.` exit 0; else `Checking for updates...\n` then `Skills are up to date (vX).` or `Updates available.` + `Run \`npx impeccable update\` to update.`; failure → `Could not check for updates: ${msg}` exit 1.