Skip to content

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.rs
index 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.rs
index 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.md
index 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-SIGNI
A 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.