The design language that makes your AI harness better at design.
JavaScript
Fix: name the step that failed when a skill bundle download fails (#1138) (#1141)
Abdul Wahab5cb95eea9c96
diff --git a/crates/skills/src/bundle.rs b/crates/skills/src/bundle.rsindex 25c95a562..fb66da1c8 100644--- a/crates/skills/src/bundle.rs+++ b/crates/skills/src/bundle.rs@@ -161,41 +161,44 @@ pub fn download_file_with(dest: &str,fetch: &mut dyn FnMut(&str) -> Result<FetchResponse, String>,) -> Result<(), String> {- download_file_capped(url, dest, fetch, MAX_DOWNLOAD_BYTES)+ download_file_capped(url, dest, fetch, MAX_DOWNLOAD_BYTES).map_err(BundleError::into_detail)}+/// Failures of the request or the response body are `Download`; failures to+/// create or write `dest` are `Unpack`.fn download_file_capped(url: &str,dest: &str,fetch: &mut dyn FnMut(&str) -> Result<FetchResponse, String>,max_bytes: u64,-) -> Result<(), String> {+) -> Result<(), BundleError> {+ use BundleError::{Download, Unpack};let mut current = url.to_string();let mut hops_left = 5;loop {// JS: new URL(current) throws `Invalid URL` (a TypeError) first.- let parsed = url::Url::parse(¤t).map_err(|_| "Invalid URL".to_string())?;+ let parsed = url::Url::parse(¤t).map_err(|_| Download("Invalid URL".to_string()))?;if parsed.scheme() != "https" {- return Err("Refusing non-HTTPS URL".to_string());+ return Err(Download("Refusing non-HTTPS URL".to_string()));}- let res = fetch(¤t)?;+ let res = fetch(¤t).map_err(Download)?;if res.status >= 300 && res.status < 400 {let Some(location) = res.location else {- return Err(format!("HTTP {}", res.status));+ return Err(Download(format!("HTTP {}", res.status)));};if hops_left <= 0 {- return Err("Too many redirects".to_string());+ return Err(Download("Too many redirects".to_string()));}hops_left -= 1;// JS: new URL(location, current).hrefcurrent = parsed.join(&location)- .map_err(|_| "Invalid URL".to_string())?+ .map_err(|_| Download("Invalid URL".to_string()))?.to_string();continue;}if res.status != 200 {- return Err(format!("HTTP {}", res.status));+ return Err(Download(format!("HTTP {}", res.status)));}// JS-PARITY: the `if (!res.body) throw new Error('Empty response// body')` guard has no ureq equivalent — a response always carries a@@ -209,36 +212,45 @@ fn download_file_capped(// EEXIST comes from the `wx` open itself: JS leaves the existing// file alone and rethrows.Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {- return Err(util::node_error("open", dest, &e));+ return Err(Unpack(util::node_error("open", dest, &e)));}Err(e) => {util::rm_rf(dest);- return Err(util::node_error("open", dest, &e));+ return Err(Unpack(util::node_error("open", dest, &e)));}};// Stream at most `max_bytes` to disk; a longer response is rejected- // and the partial file removed (triage C4).- let copied = std::io::copy(&mut res.body.take(max_bytes + 1), &mut file)- .and_then(|n| {- use std::io::Write;- file.flush().map(|_| n)- });- match copied {- Ok(n) if n > max_bytes => {- drop(file);- util::rm_rf(dest);- return Err(format!(- "response too large downloading {current} (over {max_bytes} bytes)"- ));+ // and the partial file removed (triage C4). Reads and writes are+ // separate calls so a full disk is not reported as a network failure.+ use std::io::Write;+ let mut body = res.body.take(max_bytes + 1);+ let mut buffer = [0u8; 64 * 1024];+ let mut copied = 0u64;+ let result = loop {+ match body.read(&mut buffer) {+ Ok(0) => break file.flush().map_err(|e| Unpack(e.to_string())),+ Ok(n) => {+ copied += n as u64;+ if let Err(e) = file.write_all(&buffer[..n]) {+ break Err(Unpack(e.to_string()));+ }+ }+ Err(e) if e.kind() == std::io::ErrorKind::Interrupted => {}+ Err(e) => break Err(Download(e.to_string())),}- Ok(_) => {}- Err(e) => {- drop(file);- util::rm_rf(dest);- return Err(e.to_string());+ };+ let result = result.and_then(|()| {+ if copied > max_bytes {+ Err(Download(format!("response too large downloading {current} (over {max_bytes} bytes)")))+ } else {+ Ok(())}+ });+ if result.is_err() {+ drop(file);+ util::rm_rf(dest);}- return Ok(());+ return result;}}@@ -340,50 +352,101 @@ fn extract_zip_from<R: Read + std::io::Seek>(reader: R, target_dir: &str, cwd: &/// JS: downloadAndExtractBundle() after #479: a mkdtemp staging dir holds/// 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, String> {+pub fn download_and_extract_bundle(sys: &Sys) -> Result<String, BundleError> {if let Some(local) = sys.env.get("IMPECCABLE_BUNDLE_PATH").filter(|v| !v.is_empty()) {- return copy_or_extract_local_bundle(sys, local);+ return copy_or_extract_local_bundle(sys, local).map_err(BundleError::Local);}download_remote_bundle(sys, &mut ureq_fetch, bundle_signature::trusted_keys())}+/// 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)]+pub enum BundleError {+ /// Fetching the release, its signature or its ZIP failed: connect error,+ /// HTTP error status, stall, size cap.+ Download(String),+ /// The release could not be authenticated.+ Verify(String),+ /// Staging, saving, reading back or extracting the bundle on this machine failed+ /// (disk space, permissions, an entry the extractor refuses).+ Unpack(String),+ /// An `IMPECCABLE_BUNDLE_PATH` bundle could not be read.+ Local(String),+}++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(_))+ }++ fn into_detail(self) -> String {+ match self {+ BundleError::Download(e) | BundleError::Verify(e) | BundleError::Unpack(e) | BundleError::Local(e) => e,+ }+ }+}++impl std::fmt::Display for BundleError {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ const RETRY: &str = ". Nothing was installed; retry or update the CLI. If this persists, report it at https://github.com/pbakaus/impeccable/issues/new";+ match self {+ BundleError::Download(e) => write!(f, "Could not download skill bundle: {e}{RETRY}"),+ BundleError::Verify(e) => write!(f, "{}{e}{RETRY}", bundle_signature::ERROR_PREFIX),+ BundleError::Unpack(e) => write!(f, "Could not unpack skill bundle: {e}{RETRY}"),+ BundleError::Local(e) => f.write_str(e),+ }+ }+}++impl From<BundleError> for String {+ fn from(e: BundleError) -> String {+ e.to_string()+ }+}+fn download_remote_bundle(sys: &Sys,fetch: &mut dyn FnMut(&str) -> Result<FetchResponse, String>,keys: Result<TrustedKeys, String>,-) -> Result<String, String> {- keys.and_then(|keys| download_and_extract_signed_bundle(sys, fetch, &keys))- .map_err(|e| format!("{}{e}. Nothing was installed; retry or update the CLI. If this persists, report it at https://github.com/pbakaus/impeccable/issues/new", bundle_signature::ERROR_PREFIX))+) -> Result<String, BundleError> {+ download_and_extract_signed_bundle(sys, fetch, &keys.map_err(BundleError::Verify)?)}fn download_and_extract_signed_bundle(sys: &Sys,fetch: &mut dyn FnMut(&str) -> Result<FetchResponse, String>,keys: &TrustedKeys,-) -> Result<String, String> {+) -> Result<String, BundleError> {+ use BundleError::{Download, Unpack, Verify};let tmp = util::tmpdir(&sys.env);- let staging = util::mkdtemp(&jsp::join(&[&tmp, "impeccable-update-"]))?;+ let staging = util::mkdtemp(&jsp::join(&[&tmp, "impeccable-update-"])).map_err(Unpack)?;let tmp_zip = jsp::join(&[&staging, "bundle.zip"]);let tmp_signature = jsp::join(&[&staging, "bundle.sig.json"]);- let result = (|| -> Result<(), String> {+ let result = (|| -> Result<(), BundleError> {// Resolve once, then request both assets from that exact release. Never// pair a latest-version lookup with a independently changing ZIP URL.- let response = fetch(&format!("{API_BASE}/api/download/bundle/universal"))?;+ let response = fetch(&format!("{API_BASE}/api/download/bundle/universal")).map_err(Download)?;if !matches!(response.status, 301 | 302 | 303 | 307 | 308) {- return Err(format!("Expected a signed bundle release redirect (HTTP {})", response.status));+ // An error status is the server failing; any other answer is not+ // the pinned release redirect.+ let error = format!("Expected a signed bundle release redirect (HTTP {})", response.status);+ return Err(if response.status >= 400 { Download(error) } else { Verify(error) });}- let location = response.location.ok_or("Missing bundle release redirect")?;- let version = bundle_signature::release_version(&location)?;+ let location = response.location.ok_or_else(|| Verify("Missing bundle release redirect".into()))?;+ let version = bundle_signature::release_version(&location).map_err(Verify)?;download_file_capped(&format!("{location}.sig.json"), &tmp_signature, fetch, MAX_SIGNATURE_BYTES)?;- download_file_with(&location, &tmp_zip, fetch)?;- let signature = std::fs::read(&tmp_signature).map_err(|e| e.to_string())?;- let file = std::fs::File::open(&tmp_zip).map_err(|e| e.to_string())?;+ download_file_capped(&location, &tmp_zip, fetch, MAX_DOWNLOAD_BYTES)?;+ let signature = std::fs::read(&tmp_signature).map_err(|e| Unpack(e.to_string()))?;+ let file = std::fs::File::open(&tmp_zip).map_err(|e| Unpack(e.to_string()))?;let mut reader = std::io::BufReader::new(file);- bundle_signature::verify_reader(&mut reader, &signature, &version, keys)?;+ bundle_signature::verify_reader(&mut reader, &signature, &version, keys).map_err(Verify)?;// Reuse the verified file handle rather than reopening by pathname.use std::io::Seek;- reader.rewind().map_err(|e| e.to_string())?;- extract_zip_from(reader, &staging, &sys.cwd)?;+ reader.rewind().map_err(|e| Unpack(e.to_string()))?;+ extract_zip_from(reader, &staging, &sys.cwd).map_err(Unpack)?;util::rm_rf(&tmp_zip);util::rm_rf(&tmp_signature);Ok(())@@ -1029,7 +1092,7 @@ mod tests {body: Box::new(std::io::repeat(b'a')),})};- let err = download_file_capped("https://x/bundle", &dest, &mut fetch, 4096).unwrap_err();+ let err = download_file_capped("https://x/bundle", &dest, &mut fetch, 4096).unwrap_err().into_detail();assert!(err.contains("response too large"), "{err}");assert!(!std::path::Path::new(&dest).exists());let _ = std::fs::remove_dir_all(&dir);@@ -1071,8 +1134,46 @@ mod tests {panic!("A failed keyring must never reach the network");};let error = download_remote_bundle(&sys, &mut fetch, Err("Invalid compiled bundle signing keyring".into())).unwrap_err();- assert!(error.starts_with(bundle_signature::ERROR_PREFIX), "{error}");- assert!(error.contains("Invalid compiled bundle signing keyring"), "{error}");+ assert!(matches!(error, BundleError::Verify(_)), "{error}");+ assert!(error.to_string().starts_with(bundle_signature::ERROR_PREFIX), "{error}");+ assert!(error.to_string().contains("Invalid compiled bundle signing keyring"), "{error}");+ }++ #[test]+ fn transport_and_staging_failures_name_their_step() {+ let release = "https://github.com/pbakaus/impeccable/releases/download/skill-v4.2.0/universal.zip";+ struct Stalled;+ impl Read for Stalled {+ fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {+ Err(std::io::Error::new(std::io::ErrorKind::TimedOut, "no data received"))+ }+ }+ for case in ["connect", "zip-stall"] {+ let root = tmp_dir(case);+ let sys = Sys::new([("TMPDIR".into(), root.clone()), ("TEMP".into(), root.clone())].into(), root.clone());+ let mut fetch = |url: &str| -> Result<FetchResponse, String> {+ match (case, url) {+ ("connect", _) => Err("connection refused".into()),+ (_, u) if u.ends_with("/api/download/bundle/universal") => Ok(FetchResponse { status: 302, location: Some(release.into()), body: Box::new(std::io::empty()) }),+ (_, u) if u.ends_with(".sig.json") => Ok(FetchResponse { status: 200, location: None, body: Box::new(std::io::Cursor::new(b"{}".to_vec())) }),+ _ => Ok(FetchResponse { status: 200, location: None, body: Box::new(Stalled) }),+ }+ };+ let error = download_remote_bundle(&sys, &mut fetch, Ok(Default::default())).unwrap_err();+ assert!(matches!(error, BundleError::Download(_)), "{case}: {error}");+ assert!(error.to_string().starts_with("Could not download skill bundle: "), "{case}: {error}");+ util::rm_rf(&root);+ }+ let unwritable = Sys::new([("TMPDIR".into(), "/nonexistent/impeccable".into()), ("TEMP".into(), "/nonexistent/impeccable".into())].into(), "/".into());+ let mut fetch = |_: &str| -> Result<FetchResponse, String> { panic!("staging fails before any request") };+ let error = download_remote_bundle(&unwritable, &mut fetch, Ok(Default::default())).unwrap_err();+ assert!(matches!(error, BundleError::Unpack(_)), "{error}");+ let mut fetch = |_: &str| -> Result<FetchResponse, String> {+ Ok(FetchResponse { status: 200, location: None, body: Box::new(std::io::Cursor::new(b"zip".to_vec())) })+ };+ 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());}#[test]@@ -1092,10 +1193,15 @@ mod tests {};let error = download_and_extract_signed_bundle(&sys, &mut fetch, &Default::default()).unwrap_err();if matches!(status, 301 | 302 | 303 | 307 | 308) {- assert_eq!(error, "reached signature download", "HTTP {status}");+ assert!(matches!(&error, BundleError::Download(m) if m == "reached signature download"), "HTTP {status}: {error}");assert_eq!(requests, 2);} else {- assert!(error.contains("Expected a signed bundle release redirect"), "{error}");+ assert!(error.to_string().contains("Expected a signed bundle release redirect"), "{error}");+ if status >= 400 {+ assert!(matches!(error, BundleError::Download(_)), "HTTP {status}: {error}");+ } else {+ assert!(matches!(error, BundleError::Verify(_)), "HTTP {status}: {error}");+ }assert_eq!(requests, 1);}assert_eq!(std::fs::read_dir(&root).unwrap().count(), 0);@@ -1157,6 +1263,12 @@ mod tests {util::rm_rf(&staging);} else {let error = result.unwrap_err();+ if matches!(case, "missing" | "oversized" | "downgrade") {+ assert!(matches!(error, BundleError::Download(_)), "{case}: {error}");+ } else {+ assert!(matches!(error, BundleError::Verify(_)), "{case}: {error}");+ }+ let error = error.to_string();if case == "malformed-zip" {assert!(error.contains("size"), "must reject before ZIP parsing: {error}");}diff --git a/crates/skills/src/commands.rs b/crates/skills/src/commands.rsindex a1d3ba281..6e9f5c9b5 100644--- a/crates/skills/src/commands.rs+++ b/crates/skills/src/commands.rs@@ -621,9 +621,9 @@ 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.starts_with(crate::bundle_signature::ERROR_PREFIX)+ if e.is_remote()|| !missing_hook_targets.is_empty() || !missing_selected_targets.is_empty() {- return Err(e);+ return Err(e.into());}update_check_skipped = true;out(io, &format!("Could not check for skill updates: {e}"));diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.mdindex 7f228a325..52ba13645 100644--- a/docs/CLI-CONTRACT.md+++ b/docs/CLI-CONTRACT.md@@ -484,7 +484,7 @@ retain their local-development trust behavior. See [bundle signing](BUNDLE-SIGNIsorted by `id.localeCompare`.- **Flag parsing** (`getFlagValue`): `--name=value` or `--name value` (next arg not starting with `-`). Boolean flags via `includes`.- **install flags**: `--force`, `-y|--yes`, `--no-hooks`, `--providers=<list>`, scope: `--user|--home|--global` → user; `--project|--local` → project; `--scope=<v>`/`--install-scope=<v>` normalized (`u|user|home|global`→user, `p|project|local|repo`→project; unknown → error `Unknown install scope: ${v}. Use --scope=project or --scope=global.`). Project root = nearest ancestor with `.git`, else cwd. Detection: project harness dirs present in root, plus `GLOBAL_HARNESS_HINTS` under home (`.agent`, `.gemini/antigravity*`→`.agent`, `.claude`, `.codex`→`.agents`, `.cursor`, `.dsh` (resolved `$DSH_HOME`, fallback `~/.dsh`), `.gemini`, `.grok`, `.hermes`, `.kiro`, `.opencode`, opencode config dir, `.pi`, `.qoder`, `.rovodev`, `.vibe`). Targets: explicit list wins (invalid names → `Unknown provider(s): ...`); `-y` → detected project providers, else detected user providers, else DEFAULT_TARGETS; interactive → prints "Detected harnesses:" table then radio/checkbox prompts (raw-mode TTY) or line prompts (`Install target: [1] Detected only (...) [2] Customize [1]: `, `Select harnesses (comma-separated: ...)`). Scope: explicit; `-y` → project; interactive prompt `Install location` (Project/Global). Hooks: `decideHookInstall` reads `hook.consent` in config(.local).json; declined→false, accepted→true; all targets already have hook markers→true; `-y` or non-TTY→true; else prints HOOK_EXPLAINER and asks `Install the design hook? (Y/n) `, storing consent in `.impeccable/config.local.json`.- Bundle: `IMPECCABLE_BUNDLE_PATH` (dir or zip) else download `https://impeccable.style/api/download/bundle/universal` (https only, up to 5 redirects, non-200 → `HTTP ${status}`; 30 s connect timeout and a 60 s idle timeout on every read, with no cap on the whole transfer, so a slow but steady connection finishes (#1115); a stall → `no data received for 60 s downloading <url>; check the network and retry`, under the `Could not verify skill bundle: ` prefix) to `${tmpdir}/impeccable-update-${Date.now()}.zip`, extracted with `fflate.unzipSync` into `${tmpdir}/impeccable-update-${Date.now()}` (zip-slip guarded: `Refusing to extract entry outside target dir: ${entry}`). Bundle layout `<bundle>/<provider>/skills/<skill>/...`, `<bundle>/<provider>/agents/*.md`, hook manifests `<bundle>/.claude/settings.json`, `.cursor/hooks.json`, `.codex/hooks.json`, `.github/hooks/impeccable.json`, `.grok/hooks/impeccable.json`.+ Bundle: `IMPECCABLE_BUNDLE_PATH` (dir or zip) else download `https://impeccable.style/api/download/bundle/universal` (https only, up to 5 redirects, non-200 → `HTTP ${status}`; 30 s connect timeout and a 60 s idle timeout on every read, with no cap on the whole transfer, so a slow but steady connection finishes (#1115); a stall → `no data received for 60 s downloading <url>; check the network and retry`) to `${tmpdir}/impeccable-update-${Date.now()}.zip`, extracted with `fflate.unzipSync` into `${tmpdir}/impeccable-update-${Date.now()}` (zip-slip guarded: `Refusing to extract entry outside target dir: ${entry}`). Bundle layout `<bundle>/<provider>/skills/<skill>/...`, `<bundle>/<provider>/agents/*.md`, hook manifests `<bundle>/.claude/settings.json`, `.cursor/hooks.json`, `.codex/hooks.json`, `.github/hooks/impeccable.json`, `.grok/hooks/impeccable.json`. A failed remote bundle prints either `Could not download skill bundle: ${msg}` (the release lookup, signature, or ZIP request failed: connect error, HTTP status, stall, size cap), `Could not verify skill bundle: ${msg}` (keyring, release redirect or version check, signature envelope, key, signature, digest or size mismatch), or `Could not unpack skill bundle: ${msg}` (staging, saving, reading back or extracting the bundle on this machine), each followed by `. Nothing was installed; retry or update the CLI. If this persists, report it at https://github.com/pbakaus/impeccable/issues/new`.Fresh install: `stdout> \nDownloading impeccable skills...`; migrate `*-impeccable` prefixed dirs → `impeccable`; copy each skill dir (rm existing dest first; drop an in-project cross-provider symlinked skills dir); copy agents (`.github`→`.github/agents` or `~/.copilot/agents`; `.cursor`→`.cursor/agents` or `~/.cursor/agents`); write hooks (Claude project scope: `.claude/settings.local.json`, skipped when project `.claude/settings.json` already carries the marker; Claude user scope: `~/.claude/settings.json`, with obsolete Impeccable entries pruned from `~/.claude/settings.local.json`; other destinations: `.cursor/hooks.json`, `.codex/hooks.json` for `.agents`, `.github/hooks/impeccable.json`, `.grok/hooks/impeccable.json`); merged with existing JSON (`mergeHookManifests`: strips existing impeccable entries by markers `skills/impeccable/scripts/hook-probe.mjs|hook.mjs|hook-before-edit.mjs|hook-after-edit.mjs|hook-stop.mjs`, then appends fresh); invalid existing JSON → error `Existing hook manifest is not valid JSON: ${dest}. Re-run with --force to replace it.` (with `--force`, `.bak` written). Claude and Gemini user settings are never replaced wholesale when invalid. Hook command rewriting: `[ ! -f '<abs>' ] || node '<abs>'` (POSIX, single-quote-escaped) when absolute (user scope or global skill), else `[ ! -f "<rel>" ] || node "<rel>"` where rel = `${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs` (Claude), `.agents/skills/impeccable/scripts/hook.mjs` (Codex; plus `commandWindows: if exist "<p>" (node "<p>" & exit /b)`), `.cursor/skills/impeccable/scripts/hook-before-edit.mjs`; on win32 for non-Codex: `node -e "<WIN32_HOOK_GUARD_SCRIPT>" "<path>"`. Output: `Installed impeccable into: ${targets.join(', ')} (${'global'|'project'})`, optional `Installed <Provider> agents into: <path>` (+ shadow warning), `Installed hooks into: ...`, then `\nDone! Now type /impeccable init in your AI coding agent's chat (not in this terminal) to set up design context.\n`. Errors: `Download failed: ...` / `Install failed: ...` / `Nothing was installed: the bundle had no variants for ...` → exit 1.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.