From 529c25a7b56f72bf73f6a547f8139b5abf5aca70 Mon Sep 17 00:00:00 2001 From: pasta Date: Wed, 30 Sep 2026 16:51:48 -0500 Subject: [PATCH 1/2] fix(cli): classify bad input as E201, explain unreadable private copies and log storage, and align --json ids and nulls QW2-076: forge-core gains InvalidInput (empty titles, bodies and label names, texts over their limit), reported as E201 instead of E204 with a dg doctor fix; a wrong passphrase on any sealed file is E303 naming the file; comment, review and thread ids are checked before any read; the SDK's raw 32-byte text is gone from id errors. QW2-077: dg ci report --log / --artifact with no storage of your own says they need --storage, not the release command's message. QW2-078: a clone whose packs are recorded only at addresses no reader follows names each place once, why it is not followed, and the reseed-to-public-storage fix instead of gateways and retries. QW2-079: E802 says check the estimate only when the prompt quotes one. QW2-080: quick start shows the [y/N] default and what name register needs; the DPNS quote is an upper bound near what bonsia charged (0.001 DASH, was 0.02). QW2-081: dg doctor names dash.storage=platform instead of calling it unset. QW2-085: dg issue view (and pr view) print assignees and milestone beside labels. QW-081 residue: ci runner list, pr checks, ci status and the remaining write results carry id beside documentId; a check run's absent detailsUrl and pending conclusion are null, not an empty string. Co-Authored-By: Claude Opus 5.5 (1M context) --- crates/dg/src/auth/mod.rs | 6 +- crates/dg/src/ci.rs | 66 +++++++++++++++-- crates/dg/src/common.rs | 38 +++++++++- crates/dg/src/context.rs | 27 ++++++- crates/dg/src/doctor.rs | 28 +++++++- crates/dg/src/fmt.rs | 80 +++++++++++++++++++++ crates/dg/src/issue.rs | 14 +++- crates/dg/src/label.rs | 1 + crates/dg/src/milestone.rs | 2 +- crates/dg/src/pr/mod.rs | 31 ++++++++ crates/dg/src/pr/state.rs | 2 +- crates/dg/src/release.rs | 4 ++ crates/dg/src/repo_settings.rs | 1 + crates/dg/src/webhook.rs | 2 + crates/forge-core/src/collab/mod.rs | 4 +- crates/forge-core/src/collab/v2.rs | 66 +++++++++++++++-- crates/forge-core/src/error.rs | 11 +++ crates/forge-core/src/platform/mod.rs | 10 ++- crates/forge-core/src/repo.rs | 6 +- crates/forge-core/src/sealed.rs | 7 +- crates/forge-core/src/storage/read.rs | 66 +++++++++++++++++ crates/forge-core/src/user_error.rs | 77 ++++++++++++++++++++ crates/forge-import/src/sealed_release.rs | 1 + crates/forge-import/src/sink.rs | 13 ++-- crates/git-remote-dash/src/helper.rs | 86 ++++++++++++++++++++++- docs/errors.md | 12 ++-- docs/guides/quick-start.md | 6 +- 27 files changed, 618 insertions(+), 49 deletions(-) diff --git a/crates/dg/src/auth/mod.rs b/crates/dg/src/auth/mod.rs index d72d06027..5fec01117 100644 --- a/crates/dg/src/auth/mod.rs +++ b/crates/dg/src/auth/mod.rs @@ -1033,8 +1033,10 @@ async fn balance(ctx: &Ctx) -> Result<()> { // name register // --------------------------------------------------------------------------------------- -/// DPNS registration cost for a non-contested name (preorder + domain), credits; an estimate. -const DPNS_ESTIMATE_CREDITS: u64 = 2_000_000_000; +/// DPNS registration cost for a non-contested name (preorder + domain), credits: an upper +/// bound. A 9-character name was charged 71,000,000 credits (0.00071 DASH) on devnet bonsia +/// (QW2-080); the old 0.02 DASH quote was 28 times that. +const DPNS_ESTIMATE_CREDITS: u64 = 100_000_000; async fn name_register(ctx: &Ctx, label: &str, master: Option<&std::path::Path>) -> Result<()> { let label = label.trim().trim_end_matches(".dash"); diff --git a/crates/dg/src/ci.rs b/crates/dg/src/ci.rs index ab0fb6fba..c1480674c 100644 --- a/crates/dg/src/ci.rs +++ b/crates/dg/src/ci.rs @@ -484,7 +484,7 @@ async fn runner_list(ctx: &Ctx, repo: &str) -> Result<()> { let r = Reader::open(ctx, repo).await?; let runners = RunnerReader::new(&r.client).list(&r.repo).await?; ctx.emit( - json!({ "count": runners.len(), "runners": runners }), + json!({ "count": runners.len(), "runners": crate::fmt::with_ids(&runners) }), || { if runners.is_empty() { println!("no runners"); @@ -544,8 +544,9 @@ fn gives_log_url(profile: &Profile) -> bool { } } -/// Refuse, before anything is uploaded, storage none of whose profiles records an https or -/// IPFS address (a plain-http or private bucket): the check run could not name the log. +/// Refuse, before anything is uploaded: no storage of your own at all (a Platform-only +/// repository and no `--storage`), or storage none of whose profiles records an https or IPFS +/// address (a plain-http or private bucket), where the check run could not name the log. fn check_log_storage(storage: Option<&str>) -> Result<()> { let (list, replicas) = match storage { Some(s) => (Some(s.to_string()), None), @@ -556,8 +557,10 @@ fn check_log_storage(storage: Option<&str>) -> Result<()> { }; let policy = StoragePolicy::from_git_values(list.as_deref(), replicas.as_deref(), None)? .resolve(&StorageProfiles::load()?)?; - if policy.external.is_empty() || policy.external.iter().any(|(_, p)| gives_log_url(p)) { - // No external storage at all: `asset_targets` explains that. + if policy.external.is_empty() { + return Err(no_log_storage(storage.is_some())); + } + if policy.external.iter().any(|(_, p)| gives_log_url(p)) { return Ok(()); } Err(UserError::new( @@ -579,6 +582,28 @@ fn check_log_storage(storage: Option<&str>) -> Result<()> { .into()) } +/// E501 for `--log` / `--artifact` with no storage of your own: they are uploaded there, never +/// to Platform. Before, this was the release command's "release not created: no storage for +/// the assets" (QW2-077). +fn no_log_storage(storage_given: bool) -> anyhow::Error { + let why = if storage_given { + "the --storage given names no storage of your own (only Platform)" + } else { + "dash.storage names none (it is unset, or platform), and no --storage was given" + }; + UserError::new( + codes::STORAGE_CONFIG, + "check run not reported: --log and --artifact need your own storage", + ) + .cause(format!( + "a check run's log and artifacts are uploaded to your own storage (an S3 bucket with an https public_url, or IPFS) and the run records their URL; {why}" + )) + .fix("pass --storage (`dg storage list` shows yours; `dg storage add …` adds one)") + .fix("or report the run without --log / --artifact") + .note("nothing was uploaded or written") + .into() +} + /// The log's https (else `ipfs://`) URL and its SHA-256, after uploading it to `storage`. async fn upload_log(path: &Path, storage: Option<&str>) -> Result<(String, [u8; 32])> { let (targets, required) = crate::release::asset_targets(storage)?; @@ -645,7 +670,9 @@ async fn report(ctx: &Ctx, a: &ReportArgs) -> Result<()> { // text once the repository's visibility says whether it is kept (a private repository's // run drops it with a warning instead). let usage = |e: forge_core::error::Error| match e { - forge_core::error::Error::Config(m) => crate::errors::usage(m), + forge_core::error::Error::Config(m) | forge_core::error::Error::InvalidInput(m) => { + crate::errors::usage(m) + } other => other.into(), }; r.for_visibility(Visibility::Private) @@ -848,7 +875,7 @@ async fn status(ctx: &Ctx, repo: &str, sha: &str) -> Result<()> { let runs = r.collab().check_runs(&r.repo, &sha).await?; let url = commit_web_url(&r.repo, &sha); ctx.emit( - json!({ "headOid": sha, "checks": runs, "url": url }), + json!({ "headOid": sha, "checks": crate::fmt::with_ids(&runs), "url": url }), || { if runs.is_empty() { println!("no checks reported for {}", &sha[..7.min(sha.len())]); @@ -887,6 +914,31 @@ async fn status(ctx: &Ctx, repo: &str, sha: &str) -> Result<()> { mod tests { use super::*; + /// QW2-077: `--log` on a Platform-only repository names the flag and the fix, not the + /// release command's "release not created". + #[test] + fn a_log_without_storage_says_it_needs_storage() { + let e = no_log_storage(false); + let u = e.downcast_ref::().unwrap(); + assert_eq!((u.code, u.exit_code()), ("E501", 5)); + assert!(u.message.starts_with("check run not reported"), "{u:?}"); + assert!(!u.message.contains("release"), "{u:?}"); + assert!( + u.cause + .as_deref() + .unwrap() + .contains("no --storage was given"), + "{u:?}" + ); + assert!(u.fix[0].contains("--storage "), "{u:?}"); + let given = no_log_storage(true); + let u = given.downcast_ref::().unwrap(); + assert!( + u.cause.as_deref().unwrap().contains("the --storage given"), + "{u:?}" + ); + } + /// QW-038: every check-run write and runner key measured on bonsia (Platform 4.2.0-beta.7, /// 2026-09-30) is at or under its quote. The flat quotes it replaces were exceeded: a /// repository's first create paid 121.9M against 85M, an update with a summary 5.5M diff --git a/crates/dg/src/common.rs b/crates/dg/src/common.rs index 3411ee8b1..bfe3f26bd 100644 --- a/crates/dg/src/common.rs +++ b/crates/dg/src/common.rs @@ -84,6 +84,25 @@ fn invalid_ref(input: &str, why: &str) -> anyhow::Error { .into() } +/// Refuse a `what` argument (a comment, review or thread id) that cannot be a document id, +/// before any read: E201 naming the argument and where the ids are listed (`listed_by`). +/// Before, `dg issue delete-comment 2` was E204 "invalid configuration" with a raw +/// "Identifier must be 32 bytes long" (QW2-076). +pub fn document_id_arg(value: &str, what: &str, listed_by: &str) -> Result<()> { + if looks_like_identity_id(value) { + return Ok(()); + } + Err(UserError::new( + codes::USAGE, + format!("{:?} is not a {what}", crate::fmt::safe(value)), + ) + .cause(format!( + "a {what} is a document id (about 44 base58 characters), not a number" + )) + .fix(format!("{listed_by} lists the ids")) + .into()) +} + /// Whether `s` is plausibly a base58 identity id (32-byte id ≈ 42-44 base58 chars, no /// `0OIl` and no `/`). Used to distinguish an identity owner from a DPNS label. fn looks_like_identity_id(s: &str) -> bool { @@ -311,11 +330,28 @@ pub async fn resolve_identity(client: &PlatformClient, who: &str, what: &str) -> #[cfg(test)] mod tests { - use super::{looks_like_identity_id, RepoRef}; + use super::{document_id_arg, looks_like_identity_id, RepoRef}; // A real testnet identity id shape (DEPLOYER). const ID: &str = "8hJmcHWTsdvkHyCrk4UgjbyugDAmE7QfuCTQXpXAc7nB"; + /// QW2-076: a number where a comment id goes is E201 naming the argument, not E204. + #[test] + fn a_document_id_argument_is_checked_before_any_read() { + assert!(document_id_arg(ID, "comment id", "`dg issue view`").is_ok()); + let e = + document_id_arg("2", "comment id", "`dg issue view --json`").unwrap_err(); + let u = e + .downcast_ref::() + .unwrap(); + assert_eq!((u.code, u.exit_code()), ("E201", 2)); + assert_eq!(u.message, "\"2\" is not a comment id"); + assert!( + u.fix[0].contains("dg issue view --json"), + "{u:?}" + ); + } + #[test] fn parses_owner_slash_name() { let r = RepoRef::parse(&format!("{ID}/my-repo")).unwrap(); diff --git a/crates/dg/src/context.rs b/crates/dg/src/context.rs index b0a78cf63..92c625b18 100644 --- a/crates/dg/src/context.rs +++ b/crates/dg/src/context.rs @@ -76,6 +76,17 @@ fn prompt_blocker(yes: bool, json: bool, stdin_tty: bool) -> Option<&'static str } } +/// The E802 fix for `prompt`: "check the estimate" only when the prompt quotes one (a DASH +/// figure); a prompt that names the write without a price (`dg collab accept`, `dg issue +/// close`) is reviewed instead (QW2-079). +fn confirm_fix(prompt: &str) -> &'static str { + if prompt.contains(" DASH") { + "check the estimate, then run the same command with --yes" + } else { + "check what it will do, then run the same command with --yes" + } +} + /// The E802 for a prompt that cannot be asked, with `cause`; callers add the fixes. fn confirmation_required(cause: String) -> UserError { UserError::new(codes::CONFIRMATION_REQUIRED, "confirmation required") @@ -481,7 +492,7 @@ impl Ctx { } if let Some(why) = prompt_blocker(self.yes, self.json, self.stdin_tty) { return Err(confirmation_required(format!("{prompt} — and {why}")) - .fix("check the estimate, then run the same command with --yes") + .fix(confirm_fix(prompt)) .into()); } eprint!("{prompt} {} ", if default_yes { "[Y/n]" } else { "[y/N]" }); @@ -557,6 +568,20 @@ impl Ctx { mod tests { use super::*; + /// QW2-079: "check the estimate" only when the prompt quotes one. + #[test] + fn the_e802_fix_mentions_an_estimate_only_when_there_is_one() { + assert!( + confirm_fix("Report build = queued? (create a check run, ~0.0013 DASH)") + .contains("estimate") + ); + let fix = confirm_fix( + "Accept membership of a/b? Its owner can then add you (one small document)", + ); + assert!(!fix.contains("estimate"), "{fix}"); + assert!(fix.contains("--yes"), "{fix}"); + } + fn config(network: &str) -> Config { Config { network: Some(network.into()), diff --git a/crates/dg/src/doctor.rs b/crates/dg/src/doctor.rs index 935a55cd6..9b5d22b2b 100644 --- a/crates/dg/src/doctor.rs +++ b/crates/dg/src/doctor.rs @@ -1150,7 +1150,7 @@ fn check_git_config(ctx: &Ctx) -> Vec { ); out.push(match policy { Err(e) => Check::fail("dash.storage", e.to_string(), "`dg storage use ` rewrites it"), - Ok(p) if p.is_platform_only() => Check::ok("dash.storage", "unset: pushes store packs on Platform"), + Ok(p) if p.is_platform_only() => Check::ok("dash.storage", platform_only_detail(storage.as_deref())), Ok(p) => match StorageProfiles::load().and_then(|profiles| p.resolve(&profiles)) { Ok(r) => Check::ok( "dash.storage", @@ -1166,6 +1166,15 @@ fn check_git_config(ctx: &Ctx) -> Vec { out } +/// The `dash.storage` row's detail for a Platform-only policy: the value as set (`platform`), +/// or `unset` when there is none (QW2-081: a repo set to `platform` read "unset"). +fn platform_only_detail(value: Option<&str>) -> String { + match value.map(str::trim).filter(|v| !v.is_empty()) { + Some(v) => format!("{v}: pushes store packs on Platform"), + None => "unset: pushes store packs on Platform".to_string(), + } +} + /// The `dash.network` row when git's network does not resolve: a `config.toml` that does /// not parse (E204, reported on its own row) is a pointer to that row; anything else is a /// bad `dash.*` value in git config. @@ -1306,6 +1315,23 @@ fn in_git_repo() -> bool { mod tests { use super::*; + /// QW2-081: a repository set to `platform` says so; only a missing value is "unset". + #[test] + fn a_platform_storage_value_is_named_not_called_unset() { + assert_eq!( + platform_only_detail(Some("platform")), + "platform: pushes store packs on Platform" + ); + assert_eq!( + platform_only_detail(None), + "unset: pushes store packs on Platform" + ); + assert_eq!( + platform_only_detail(Some(" ")), + "unset: pushes store packs on Platform" + ); + } + /// The guard `dg doctor --fix` sets lets a small push through without asking, packs on /// Platform included (its quote is an upper bound), and still asks before a megabyte. #[test] diff --git a/crates/dg/src/fmt.rs b/crates/dg/src/fmt.rs index 8d444f5be..868b3e957 100644 --- a/crates/dg/src/fmt.rs +++ b/crates/dg/src/fmt.rs @@ -145,6 +145,39 @@ fn usd_json(usd: f64) -> f64 { (usd * 1_000_000.0).round() / 1_000_000.0 } +/// The `labels:`, `assignees:` and `milestone:` lines of an issue or PR view, each only when +/// set, as `gh issue view` shows them (QW2-085: assignees were missing). `assignees` are as +/// they should print (an id, or an id with its DPNS name). +pub fn triage_lines(labels: &[&str], assignees: &[String], milestone: Option<&str>) -> Vec { + let mut out = Vec::new(); + if !labels.is_empty() { + out.push(format!("labels: {}", safe(&labels.join(", ")))); + } + if !assignees.is_empty() { + out.push(format!("assignees: {}", assignees.join(", "))); + } + if let Some(m) = milestone { + out.push(format!("milestone: {}", safe(m))); + } + out +} + +/// `rows` (records serialized as JSON objects) with `id` beside each `documentId`, as every +/// other `--json` output has it (QW-081): scripts read `id` everywhere. +pub fn with_ids(rows: &[T]) -> Value { + let mut v = serde_json::to_value(rows).unwrap_or(Value::Null); + if let Value::Array(items) = &mut v { + for item in items { + if let Value::Object(o) = item { + if let Some(id) = o.get("documentId").cloned() { + o.entry("id").or_insert(id); + } + } + } + } + v +} + /// The `--json` block for `auth balance`. pub fn balance_json(identity_id: &str, credits: u64, network: &str) -> Value { let dash = credits_to_dash(credits); @@ -192,6 +225,53 @@ pub fn event_values_note(hidden: usize, plaintext: usize) -> Option { mod tests { use super::*; + /// QW-081: every record gets `id` beside its `documentId`; one that has `id` keeps it. + #[test] + fn records_get_an_id_beside_their_document_id() { + #[derive(serde::Serialize)] + #[serde(rename_all = "camelCase")] + struct Row { + document_id: &'static str, + name: &'static str, + } + let v = with_ids(&[Row { + document_id: "D1", + name: "build", + }]); + assert_eq!( + v, + json!([{ "documentId": "D1", "id": "D1", "name": "build" }]) + ); + let kept = with_ids(&[ + json!({ "documentId": "D1", "id": "X" }), + json!({ "name": "n" }), + ]); + assert_eq!( + kept, + json!([{ "documentId": "D1", "id": "X" }, { "name": "n" }]) + ); + } + + /// QW2-085: labels, assignees and milestone, each only when set. + #[test] + fn triage_lines_show_what_is_set() { + let lines = triage_lines( + &["bug", "docs"], + &["A (alice.dash)".into(), "B".into()], + Some("v1.0"), + ); + assert_eq!( + lines, + vec![ + "labels: bug, docs", + "assignees: A (alice.dash), B", + "milestone: v1.0" + ] + ); + assert!(triage_lines(&[], &[], None).is_empty()); + assert_eq!(triage_lines(&[], &["B".into()], None), vec!["assignees: B"]); + } + /// QW-081: the `usd` of a cost carries no float noise. #[test] fn a_cost_in_usd_has_no_float_noise() { diff --git a/crates/dg/src/issue.rs b/crates/dg/src/issue.rs index cd5d926b7..488cf984a 100644 --- a/crates/dg/src/issue.rs +++ b/crates/dg/src/issue.rs @@ -417,6 +417,7 @@ async fn view(ctx: &Ctx, repo: &str, number: u64) -> Result<()> { let actors = comments.iter().map(|c| c.author.as_str()); let actors = actors.chain(events.iter().map(|e| e.actor.as_str())); let actors = actors.chain(transitions.iter().map(|t| t.actor.as_str())); + let actors = actors.chain(state.assignees.iter().map(String::as_str)); s.client .dpns_first_names(std::iter::once(author.as_str()).chain(actors)) .await @@ -458,8 +459,10 @@ async fn view(ctx: &Ctx, repo: &str, number: u64) -> Result<()> { let mark = state_word(state.open); println!("#{number} [{mark}] {}", safe(&title)); println!("author: {}", who(&author)); - if !state.labels.is_empty() { - println!("labels: {}", safe(&labels_of(&state))); + let labels: Vec<&str> = state.labels.iter().map(String::as_str).collect(); + let assignees: Vec = state.assignees.iter().map(|a| who(a)).collect(); + for line in crate::fmt::triage_lines(&labels, &assignees, meta.milestone.as_deref()) { + println!("{line}"); } if !body.is_empty() { println!("\n{}", safe(&body)); @@ -548,7 +551,12 @@ fn event_phrase(e: &Event) -> String { } /// Edit one of the signer's comments (issue or PR): its body, re-sealed in a private repo. +/// Where a comment's id is listed, for a refused comment id. +const COMMENT_IDS: &str = + "`dg issue view --json` (or `dg pr view --comments --json`)"; + async fn edit_comment(ctx: &Ctx, repo: &str, comment_id: &str, body: &str) -> Result<()> { + crate::common::document_id_arg(comment_id, "comment id", COMMENT_IDS)?; let s = Session::open_for_write(ctx, repo, "comment not edited").await?; ctx.confirm_or_cancel(&format!( "Edit comment {comment_id}? (one document replace)" @@ -580,6 +588,7 @@ async fn edit_comment(ctx: &Ctx, repo: &str, comment_id: &str, body: &str) -> Re /// Delete one of the signer's comments (QW-016): an owner-only document delete, refused before /// signing for someone else's comment. async fn delete_comment(ctx: &Ctx, repo: &str, comment_id: &str) -> Result<()> { + crate::common::document_id_arg(comment_id, "comment id", COMMENT_IDS)?; let s = Session::open_for_write(ctx, repo, "comment not deleted").await?; // Someone else's comment (or another repo's) is refused before the prompt, not after it. let there = s.collab().deletable_comment(&s.repo, comment_id).await?; @@ -633,6 +642,7 @@ async fn create(ctx: &Ctx, repo: &str, title: &str, body: &str) -> Result<()> { "status": "created", "number": created.number, "documentId": created.document_id, + "id": created.document_id, "title": title, "resumed": created.resumed, "cost": cost_json(spent, price), diff --git a/crates/dg/src/label.rs b/crates/dg/src/label.rs index 563ca3ca2..c7ee94c63 100644 --- a/crates/dg/src/label.rs +++ b/crates/dg/src/label.rs @@ -133,6 +133,7 @@ async fn define( "status": if retired { "retired" } else { "defined" }, "name": name, "documentId": id, + "id": id, }), || println!("✓ {}d label {name}", verb.to_lowercase()), ); diff --git a/crates/dg/src/milestone.rs b/crates/dg/src/milestone.rs index 3f1f907bd..061ec0661 100644 --- a/crates/dg/src/milestone.rs +++ b/crates/dg/src/milestone.rs @@ -120,7 +120,7 @@ async fn define( .define_milestone(&s.repo, title, description, due_on, closed) .await?; ctx.emit( - json!({ "status": "defined", "title": title, "closed": closed, "documentId": id }), + json!({ "status": "defined", "title": title, "closed": closed, "documentId": id, "id": id }), || { println!( "✓ milestone {title} {}", diff --git a/crates/dg/src/pr/mod.rs b/crates/dg/src/pr/mod.rs index f910b0d93..ac2576c74 100644 --- a/crates/dg/src/pr/mod.rs +++ b/crates/dg/src/pr/mod.rs @@ -46,12 +46,36 @@ use forge_core::user_error::{codes, UserError}; use crate::common::{number_arg, resolve, Reader, RepoRef, Session}; use crate::context::Ctx; use crate::fmt::{cost_json, cost_line, dash_usd_price, safe, short, transition_route_text}; + +/// Where a PR comment's id is listed, for a refused comment id. +const PR_COMMENT_IDS: &str = "`dg pr view --comments --json`"; use crate::git::{self, MergePlan}; use crate::PrCommand; /// Dispatch a `pr` subcommand. +/// Refuse a comment or review id argument that cannot be a document id, before any read +/// (QW2-076). +fn check_id_args(cmd: &PrCommand) -> Result<()> { + use crate::common::document_id_arg; + match cmd { + PrCommand::Resolve { comment_id, .. } | PrCommand::Unresolve { comment_id, .. } => { + document_id_arg(comment_id, "comment id", PR_COMMENT_IDS) + } + PrCommand::DismissReview { review_id, .. } => document_id_arg( + review_id, + "review id", + "`dg pr view --json` (`reviews[].id`)", + ), + PrCommand::Suggestion(crate::PrSuggestionCommand::Apply { comment_ids, .. }) => comment_ids + .iter() + .try_for_each(|id| document_id_arg(id, "comment id", PR_COMMENT_IDS)), + _ => Ok(()), + } +} + pub async fn run(ctx: &Ctx, cmd: &PrCommand) -> Result<()> { use crate::PrSuggestionCommand as Sg; + check_id_args(cmd)?; match cmd { PrCommand::Create(args) => create(ctx, args).await, PrCommand::List { repo, limit, state } => list(ctx, repo, *limit, *state).await, @@ -351,6 +375,7 @@ async fn create(ctx: &Ctx, args: &crate::PrCreateArgs) -> Result<()> { "status": "created", "number": created.number, "documentId": created.document_id, + "id": created.document_id, "title": title, "baseRef": base, "headRef": head_ref, @@ -855,6 +880,12 @@ async fn view(ctx: &Ctx, repo: &str, number: u64, show_comments: bool) -> Result short(&v.head), safe(&v.patch.base_ref_name) ); + let labels: Vec<&str> = v.state.labels.iter().map(String::as_str).collect(); + let assignees: Vec = v.state.assignees.iter().cloned().collect(); + let milestone = review_state.milestone.as_deref(); + for line in crate::fmt::triage_lines(&labels, &assignees, milestone) { + println!("{line}"); + } if let Some(m) = &since { println!( "! new commits since your review: you reviewed {}, the PR is at {} ({} head update{} since) — re-review with `dg pr review {repo} {number}`", diff --git a/crates/dg/src/pr/state.rs b/crates/dg/src/pr/state.rs index f468be5e2..bdc4adb8c 100644 --- a/crates/dg/src/pr/state.rs +++ b/crates/dg/src/pr/state.rs @@ -619,7 +619,7 @@ pub async fn checks(ctx: &Ctx, repo: &str, number: u64) -> Result<()> { json!({ "pr": number, "headOid": pr.view.head, - "checks": runs, + "checks": crate::fmt::with_ids(&runs), "passed": passed, "failed": failed, "pending": pending, diff --git a/crates/dg/src/release.rs b/crates/dg/src/release.rs index 7af7edef9..7a458eee4 100644 --- a/crates/dg/src/release.rs +++ b/crates/dg/src/release.rs @@ -212,6 +212,7 @@ async fn create(ctx: &Ctx, args: &ReleaseCreateArgs) -> Result<()> { "status": "created", "tag": tag, "documentId": doc_id, + "id": doc_id, "assets": input.assets.iter().map(asset_json).collect::>(), "cost": cost_json(spent, price), }), @@ -372,6 +373,7 @@ async fn create_sealed(ctx: &Ctx, args: &ReleaseCreateArgs, s: &Session) -> Resu "tag": tag, "sealed": true, "documentId": written.document_id, + "id": written.document_id, "assets": written.sealed_assets, "assetListKept": written.asset_list_kept, "assetListReused": written.asset_list_reused, @@ -457,6 +459,7 @@ async fn unpublish(ctx: &Ctx, repo: &str, tag: &str) -> Result<()> { "status": "unpublished", "tag": tag, "documentId": doc_id, + "id": doc_id, "cost": cost_json(spent, price), }), || { @@ -515,6 +518,7 @@ async fn unpublish_sealed(ctx: &Ctx, repo: &str, tag: &str, s: &Session) -> Resu "tag": tag, "sealed": true, "documentId": written.document_id, + "id": written.document_id, "warnings": written.warnings, "cost": cost_json(spent, price), }), diff --git a/crates/dg/src/repo_settings.rs b/crates/dg/src/repo_settings.rs index daf567be9..14f25c7f1 100644 --- a/crates/dg/src/repo_settings.rs +++ b/crates/dg/src/repo_settings.rs @@ -561,6 +561,7 @@ async fn set_policy(ctx: &Ctx, args: &RepoPolicySetArgs) -> Result<()> { "repo": s.repo.display(), "policy": policy_json(&next), "documentId": id, + "id": id, "note": POLICY_NOTE, "cost": cost_json(spent, price), }), diff --git a/crates/dg/src/webhook.rs b/crates/dg/src/webhook.rs index c69a06af5..5124fef40 100644 --- a/crates/dg/src/webhook.rs +++ b/crates/dg/src/webhook.rs @@ -176,6 +176,7 @@ async fn add(ctx: &Ctx, args: &AddArgs) -> Result<()> { "repo": handle.display(), "repoId": handle.id(), "documentId": document_id, + "id": document_id, "hookId": hex::encode(hook_id), "url": url, "events": events, @@ -214,6 +215,7 @@ async fn list(ctx: &Ctx, repo: &str) -> Result<()> { json!({ "hookId": h.hook_id_hex(), "documentId": h.document_id, + "id": h.document_id, "writer": h.owner_id, "createdAt": h.created_at, "url": h.url, diff --git a/crates/forge-core/src/collab/mod.rs b/crates/forge-core/src/collab/mod.rs index a9c4162f2..e8cf4d700 100644 --- a/crates/forge-core/src/collab/mod.rs +++ b/crates/forge-core/src/collab/mod.rs @@ -42,7 +42,7 @@ pub(crate) fn doc_engine<'a>( pub(crate) fn check_len(field: &str, value: &str, max: usize) -> Result<()> { let len = value.chars().count(); if len > max { - return Err(Error::Config(format!( + return Err(Error::InvalidInput(format!( "{field} too long: {len} chars (max {max})" ))); } @@ -59,7 +59,7 @@ pub(crate) fn check_text( ) -> Result<()> { check_len(field, value, max_chars)?; if value.len() > max_bytes { - return Err(Error::Config(format!( + return Err(Error::InvalidInput(format!( "{field} too long: {} bytes as UTF-8 (max {max_bytes})", value.len() ))); diff --git a/crates/forge-core/src/collab/v2.rs b/crates/forge-core/src/collab/v2.rs index b2b9e2ac0..3380642ef 100644 --- a/crates/forge-core/src/collab/v2.rs +++ b/crates/forge-core/src/collab/v2.rs @@ -527,6 +527,16 @@ impl PatchView { } } +/// An absent value `null` in JSON, not `""` (QW-081): a URL or an enum a document leaves out. +/// Free text a person typed (a title, a summary) keeps `""`. +fn empty_as_null(value: &str, s: S) -> std::result::Result { + if value.is_empty() { + s.serialize_none() + } else { + s.serialize_str(value) + } +} + /// A `checkRun` on a head: the newest by `($createdAt, $id)` per `name` ([`Collab::check_runs`]). #[derive(Debug, Clone, Serialize)] #[serde(rename_all = "camelCase")] @@ -537,9 +547,11 @@ pub struct CheckRun { pub name: String, /// `queued`, `in_progress` or `completed`. pub status: String, - /// The outcome once completed (`success`, `failure`, …); empty before. + /// The outcome once completed (`success`, `failure`, …); empty before (`null` in JSON). + #[serde(serialize_with = "empty_as_null")] pub conclusion: String, - /// A link to the run's details. + /// A link to the run's details; empty when the run gave none (`null` in JSON). + #[serde(serialize_with = "empty_as_null")] pub details_url: String, /// A short summary. pub summary: String, @@ -1205,7 +1217,9 @@ const REF_NAME_RULE: &str = "a full ref name under refs/ (such as refs/heads/mai fn check_title(title: &str) -> Result<()> { if title.trim().is_empty() { - return Err(Error::Config("a title is required".into())); + return Err(Error::InvalidInput( + "the title is empty: a title is required".into(), + )); } check_text("title", title, 256, 1024) } @@ -1555,7 +1569,9 @@ pub fn comment_props( imported: Option<&Imported>, ) -> Result> { if body.trim().is_empty() { - return Err(Error::Config("a comment needs a body".into())); + return Err(Error::InvalidInput( + "the comment is empty: a comment needs a body".into(), + )); } check_text("comment body", body, 5120, 5120)?; let mut p = BTreeMap::new(); @@ -3858,7 +3874,9 @@ impl<'a> Collab<'a> { body: &str, ) -> Result { if body.trim().is_empty() { - return Err(Error::Config("a comment needs a body".into())); + return Err(Error::InvalidInput( + "the comment is empty: a comment needs a body".into(), + )); } check_text("comment body", body, 5120, 5120)?; let collab = self.collab_contract(repo).await?; @@ -5159,7 +5177,9 @@ impl<'a> Collab<'a> { retired: bool, ) -> Result { if name.is_empty() { - return Err(Error::Config("a label needs a name".into())); + return Err(Error::InvalidInput( + "the label name is empty: a label needs a name".into(), + )); } check_len("label name", name, 30)?; check_len("label description", description, 200)?; @@ -6228,6 +6248,40 @@ mod tests { const ME: &str = "GM7ozWV1MNuAxyMnrf4JngAyGSDickvLznGi72WMp8EL"; const OTHER_REPO: &str = "9sGUjxras61DAe457iUfbJcKTfVT7qVj16PJ3xstqMKr"; + /// QW-081: a run without a details URL, or not completed yet, reads `null`, not `""`; its + /// free text (a summary) stays as written. + #[test] + fn a_check_run_absent_url_and_conclusion_are_null_in_json() { + let run = CheckRun { + document_id: "D".into(), + name: "build".into(), + status: "in_progress".into(), + conclusion: String::new(), + details_url: String::new(), + summary: String::new(), + reporter: ME.into(), + trusted: true, + started_at: None, + completed_at: None, + log_url: None, + log_sha256: None, + artifacts: Vec::new(), + created_at: 1, + }; + let v = serde_json::to_value(&run).unwrap(); + assert!(v["conclusion"].is_null(), "{v}"); + assert!(v["detailsUrl"].is_null(), "{v}"); + assert_eq!(v["summary"], ""); + let done = CheckRun { + conclusion: "success".into(), + details_url: "https://ci.example/1".into(), + ..run + }; + let v = serde_json::to_value(&done).unwrap(); + assert_eq!(v["conclusion"], "success"); + assert_eq!(v["detailsUrl"], "https://ci.example/1"); + } + fn repo_ref(visibility: Visibility) -> RepoRef { RepoRef { forge: ForgeIds::test_forge(), diff --git a/crates/forge-core/src/error.rs b/crates/forge-core/src/error.rs index 5ca71dee9..c6af6f567 100644 --- a/crates/forge-core/src/error.rs +++ b/crates/forge-core/src/error.rs @@ -100,6 +100,17 @@ pub enum Error { #[error("configuration error: {0}")] Config(String), + /// A value the caller passed in does not fit what it names (an empty title, a text over + /// its limit, a document id that is not one), refused before anything is signed. Unlike + /// [`Self::Config`] it is the command's input, not a setting: `dg` reports it as E201. + #[error("{0}")] + InvalidInput(String), + + /// A sealed file did not open: the passphrase is wrong, or the file was modified (the + /// AEAD tag failed). The caller's context names the file. + #[error("wrong passphrase, or the sealed file was modified (it failed authentication)")] + WrongPassphrase, + /// The selected network has no forge-v2 deployment (no fully registered `v2` record in /// its deployment file). Returned instead of falling back to another network's /// contracts. diff --git a/crates/forge-core/src/platform/mod.rs b/crates/forge-core/src/platform/mod.rs index 74e09177b..d143a671a 100644 --- a/crates/forge-core/src/platform/mod.rs +++ b/crates/forge-core/src/platform/mod.rs @@ -2766,8 +2766,14 @@ fn parse_address_list(addresses: &[String]) -> Result { /// Parse a base58 Platform id, mapping failures to a config error. pub(crate) fn parse_id(s: &str, what: &str) -> Result { - Identifier::from_string(s, Encoding::Base58) - .map_err(|e| Error::Config(format!("invalid {what} (expected base58): {e}"))) + // The SDK's own text ("byte length not 32 bytes error: Identifier must be 32 bytes long + // from bytes") says nothing a reader can act on (QW2-076). + Identifier::from_string(s, Encoding::Base58).map_err(|_| { + Error::Config(format!( + "invalid {what} {:?}: a Platform id is 32 bytes, written in base58 (about 44 characters)", + s.chars().take(64).collect::() + )) + }) } /// Decode a base58 Platform id (identity / contract) to its raw 32 bytes — the form an diff --git a/crates/forge-core/src/repo.rs b/crates/forge-core/src/repo.rs index 2f705cd9a..06d7fe1d6 100644 --- a/crates/forge-core/src/repo.rs +++ b/crates/forge-core/src/repo.rs @@ -3465,9 +3465,9 @@ where } } else if platform.is_empty() { return Err(Error::Io(format!( - "artifact {expected} is stored externally but its manifest records no URI this \ - client can read ({:?})", - manifest.uris + "{}: its manifest records only {}", + crate::storage::read::NO_FOLLOWED_COPY, + reader.unfollowed(&manifest.uris).join("; ") )) .into()); } diff --git a/crates/forge-core/src/sealed.rs b/crates/forge-core/src/sealed.rs index 7cbaff279..5d02cf32b 100644 --- a/crates/forge-core/src/sealed.rs +++ b/crates/forge-core/src/sealed.rs @@ -207,12 +207,7 @@ pub fn open(raw: &str, passphrase: &str) -> Result>> { }, ) .map(Zeroizing::new) - .map_err(|_| { - Error::Config( - "wrong passphrase, or the sealed file was modified (it failed authentication)" - .into(), - ) - }) + .map_err(|_| Error::WrongPassphrase) } /// The passphrase for `what`: [`PASSPHRASE_ENV`] when set, else a hidden prompt on the diff --git a/crates/forge-core/src/storage/read.rs b/crates/forge-core/src/storage/read.rs index f2c004d3d..65a2edb50 100644 --- a/crates/forge-core/src/storage/read.rs +++ b/crates/forge-core/src/storage/read.rs @@ -32,6 +32,11 @@ const RACE_WIDTH: usize = 2; /// The floor of a candidate's whole-transfer deadline (connect + body). pub const MIN_TRANSFER_DEADLINE: Duration = Duration::from_secs(120); +/// How a read that had no copy to try begins ([`PackReader::unfollowed`]): the recorded copies +/// are all ones this computer does not follow. A caller tells that case from a copy that +/// failed by this text, and gives the fix that applies (QW2-078). +pub const NO_FOLLOWED_COPY: &str = "no recorded copy is one this computer reads from"; + /// The slowest sustained rate a candidate may deliver at before its deadline cuts it off /// (1 MiB/s): a 2 GiB pack gets ~34 minutes. A host that stalls outright is cut off much /// sooner by the HTTP client's idle `read_timeout` (see [`super::http_client`]). @@ -556,6 +561,45 @@ impl PackReader { self.candidates(uris).iter().map(Candidate::place).collect() } + /// Why each of `uris` is not a copy this reader follows, one short phrase each, with the + /// place as `host[:port]` or a bucket name (no path, no scheme separator, so it survives + /// a caller's URL shortening): for a read that had no candidate at all. + pub fn unfollowed(&self, uris: &[String]) -> Vec { + uris.iter() + .map(|raw| { + let uri = Uri(raw.clone()); + match uri.scheme() { + Some(scheme @ ("https" | "http")) => { + let host = reqwest::Url::parse(raw).ok().and_then(|u| { + u.host_str().map(|h| match u.port() { + Some(p) => format!("{h}:{p}"), + None => h.to_string(), + }) + }); + let host = host.unwrap_or_else(|| "an unparseable address".into()); + let private = reqwest::Url::parse(raw) + .ok() + .and_then(|u| u.host_str().map(super::publish::is_private_host)) + .unwrap_or(false); + let why = match (scheme, private) { + (_, true) => "this machine or a private network", + ("http", false) => "plain http", + _ => "an address with credentials in it", + }; + format!("{host} ({why}: never followed from a manifest)") + } + Some("s3") => { + let bucket = uri.rest().and_then(|r| r.split('/').next()).unwrap_or(""); + format!("S3 bucket {bucket} (read only through a storage profile of yours for it)") + } + Some("ipfs") => "an IPFS copy (no read gateway configured)".to_string(), + Some(other) => format!("a {other} copy (not a kind this client reads)"), + None => "an unparseable address".to_string(), + } + }) + .collect() + } + /// Whether any candidate exists for `uris` (so the caller knows whether to bother). pub fn has_candidates(&self, uris: &[String]) -> bool { !self.candidates(uris).is_empty() @@ -914,6 +958,28 @@ mod tests { PackReader::new(vec!["https://gw1/".into(), "https://gw2".into()], &profiles) } + #[test] + fn unfollowed_copies_say_why_with_a_place_but_no_url() { + // QW2-078: the cause was a mangled list ("127.0.0.1:9000 forge-byo"). + let r = PackReader::new(Vec::new(), &StorageProfiles::default()); + let uris = [ + "http://127.0.0.1:9000/forge-byo/packs/x.pack".to_string(), + "http://files.example.org/x.pack".to_string(), + "s3://forge-byo/packs/x.pack".to_string(), + ]; + assert!(!r.has_candidates(&uris)); + let why = r.unfollowed(&uris); + assert_eq!( + why, + vec![ + "127.0.0.1:9000 (this machine or a private network: never followed from a manifest)", + "files.example.org (plain http: never followed from a manifest)", + "S3 bucket forge-byo (read only through a storage profile of yours for it)", + ] + ); + assert!(why.iter().all(|w| !w.contains("://")), "{why:?}"); + } + #[test] fn candidates_order_public_then_s3_then_gateway_race() { let r = reader(); diff --git a/crates/forge-core/src/user_error.rs b/crates/forge-core/src/user_error.rs index 7342e9aaa..fa1f050de 100644 --- a/crates/forge-core/src/user_error.rs +++ b/crates/forge-core/src/user_error.rs @@ -625,6 +625,16 @@ pub fn classify<'e>( { return UserError::storage_policy_not_met(r, ctx.goal.unwrap_or("push failed"), false); } + // A sealed file that did not open: the chain's context names which file (as typed, so + // not the lowercased text). + if layers.iter().any(|l| { + matches!( + l.downcast_ref::(), + Some(CoreError::WrongPassphrase) + ) + }) { + return wrong_passphrase(&text); + } if let Some(core) = layers .iter() .rev() @@ -733,6 +743,12 @@ fn from_core(core: &CoreError, chain: &str, ctx: &ErrorContext<'_>) -> Option identity_unreadable(msg), CoreError::Config(msg) => from_config(msg, chain, ctx), + // A command's own input (QW2-076): E201, not the E204 "invalid configuration" whose + // fix is `dg doctor`. + CoreError::InvalidInput(msg) => UserError::new(codes::USAGE, ctx.headline("invalid arguments")) + .cause(msg) + .fix("correct that value and run the command again (`--help` lists the arguments)") + .note("checked before anything was signed; nothing was written"), CoreError::Platform(msg) => return from_platform_text(msg, ctx), CoreError::User(u) => (**u).clone(), _ => return None, @@ -1362,6 +1378,19 @@ pub fn private_needs_identity(repo: &str) -> UserError { .note("public repositories are read without an identity") } +/// E303 for a sealed file whose passphrase was wrong (QW2-076: a `--runner` file was E204 with +/// a `dg doctor` fix). `chain` is the whole error text; its context layers name the file. +fn wrong_passphrase(chain: &str) -> UserError { + UserError::new( + codes::IDENTITY_UNREADABLE, + "a sealed file did not open: wrong passphrase", + ) + .cause(chain) + .fix("run it again with the passphrase that file was sealed with (typed at the prompt, or in DASH_FORGE_PASSPHRASE)") + .fix("DASH_FORGE_PASSPHRASE opens every sealed file one command reads: when two files (your key and a `--runner` or `--master` file) were sealed with different passphrases, run the command in a terminal so each is asked for") + .note("nothing was written") +} + fn identity_unreadable(msg: &str) -> UserError { // A sealed key that cannot be asked for (QW-034): the way out is the passphrase, not a // new sign-in, which costs a key registration. @@ -1990,6 +2019,54 @@ mod tests { classify([e.as_ref() as &(dyn StdError + 'static)], ctx) } + /// An error with a context layer over it, as `anyhow`'s `.context` makes one. + #[derive(Debug)] + struct Loading(CoreError); + impl std::fmt::Display for Loading { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str("loading the runner identity from /Home/Runner.json") + } + } + impl StdError for Loading { + fn source(&self) -> Option<&(dyn StdError + 'static)> { + Some(&self.0) + } + } + + #[test] + fn a_bad_input_value_is_e201_and_a_wrong_passphrase_e303_naming_the_file() { + // QW2-076: both were E204 "invalid configuration" with a `dg doctor` fix. + let issue = ErrorContext { + goal: Some("issue not created"), + repo: Some("alice/project"), + ..Default::default() + }; + let u = core_chain( + CoreError::InvalidInput("the title is empty: a title is required".into()), + &issue, + ); + assert_eq!((u.code, u.exit_code()), ("E201", 2)); + assert_eq!(u.message, "issue not created: invalid arguments"); + assert_eq!( + u.cause.as_deref(), + Some("the title is empty: a title is required") + ); + assert!(!u.fix.iter().any(|f| f.contains("doctor")), "{u:?}"); + + // The context layer names the file, as typed (not lowercased). + let outer = Loading(CoreError::WrongPassphrase); + let u = classify( + [&outer as &(dyn StdError + 'static), &outer.0], + &ErrorContext::default(), + ); + assert_eq!((u.code, u.exit_code()), ("E303", 3)); + let cause = u.cause.clone().unwrap(); + assert!(cause.contains("/Home/Runner.json"), "{cause}"); + assert!(cause.contains("wrong passphrase"), "{cause}"); + assert!(u.fix.iter().any(|f| f.contains("--runner")), "{u:?}"); + assert!(!u.fix.iter().any(|f| f.contains("doctor")), "{u:?}"); + } + const PUSH: ErrorContext<'static> = ErrorContext { goal: Some("push failed"), rejected: Some("push rejected"), diff --git a/crates/forge-import/src/sealed_release.rs b/crates/forge-import/src/sealed_release.rs index aed0b7c5b..c5d9585f6 100644 --- a/crates/forge-import/src/sealed_release.rs +++ b/crates/forge-import/src/sealed_release.rs @@ -408,6 +408,7 @@ fn release_error(e: &anyhow::Error) -> bool { matches!( e, Error::Config(_) + | Error::InvalidInput(_) | Error::User(_) | Error::Integrity | Error::DuplicateUniqueIndex(_) diff --git a/crates/forge-import/src/sink.rs b/crates/forge-import/src/sink.rs index e1ccfcf96..4a224f6db 100644 --- a/crates/forge-import/src/sink.rs +++ b/crates/forge-import/src/sink.rs @@ -339,10 +339,13 @@ fn item_error(e: &anyhow::Error) -> bool { ]; e.chain() .any(|c| match c.downcast_ref::() { - // A duplicate, or a rule of the type refusing this one document (a state move the - // target's transitions no longer allow: another client moved it first). + // A duplicate, a rule of the type refusing this one document (a state move the + // target's transitions no longer allow: another client moved it first), or a value + // of this item that does not fit (an empty title, a text over its limit). Some( - forge_core::Error::DuplicateUniqueIndex(_) | forge_core::Error::RuleRefused { .. }, + forge_core::Error::DuplicateUniqueIndex(_) + | forge_core::Error::RuleRefused { .. } + | forge_core::Error::InvalidInput(_), ) => true, Some(forge_core::Error::Config(why)) => ITEM.iter().any(|m| why.contains(m)), _ => false, @@ -361,7 +364,9 @@ fn content_error(e: &anyhow::Error) -> bool { rule, .. }) => document_type != "transition" && rule != forge_core::rules::v2::DENSE_RULE, - Some(forge_core::Error::Config(_)) => item_error(e), + Some(forge_core::Error::Config(_) | forge_core::Error::InvalidInput(_)) => { + item_error(e) + } _ => false, }) } diff --git a/crates/git-remote-dash/src/helper.rs b/crates/git-remote-dash/src/helper.rs index 4d3e7b4e9..9ebd54a3e 100644 --- a/crates/git-remote-dash/src/helper.rs +++ b/crates/git-remote-dash/src/helper.rs @@ -904,14 +904,32 @@ fn packs_unreadable( // The catalogue's wording (docs/design/ux-dx-spec.md §7.3 example 6): "clone // incomplete: 2 packs unreadable". The pack total goes in the cause. let n = unreadable.len(); - UserError::new( + let err = UserError::new( codes::PACKS_UNREADABLE, format!( "{what} incomplete: {n} {} unreadable", if n == 1 { "pack" } else { "packs" } ), - ) - .cause(format!("{n} of the repository's {total} packs: {}", cause.join("; "))) + ); + // Every copy the pusher recorded is one no reader follows (plain http, this machine, a + // private network, a bucket without a profile here): no gateway or retry helps, the copy + // has to be put somewhere readable (QW2-078). The places are said once for all the packs. + if let Some(places) = unfollowed_places(unreadable) { + return err + .cause(format!( + "{n} of the repository's {total} packs: {}: they are recorded only at {}", + forge_core::storage::read::NO_FOLLOWED_COPY, + places.join("; ") + )) + .fix(format!( + "the pusher recorded their packs only at an address other computers do not read from: from their clone they can copy them to storage with a public https address, `dg reseed {repo} --from-local --profile ` (`dg storage add … --public-url https://…` adds one)" + )) + .fix("if that host or bucket is your own storage, add a storage profile for it (`dg storage add`, with its public_url) and run it again"); + } + err.cause(format!( + "{n} of the repository's {total} packs: {}", + cause.join("; ") + )) .fix(format!( "ask a member who has the objects to run `dg reseed {repo} --from-local` inside their clone" )) @@ -919,6 +937,28 @@ fn packs_unreadable( .fix(format!("`dg storage status {repo}` shows which recorded copies answer")) } +/// When no pack had a copy this computer follows, the places their manifests record (each +/// once, in order); `None` when any pack failed some other way. +fn unfollowed_places(unreadable: &[Unreadable]) -> Option> { + const ONLY: &str = "its manifest records only "; + let mut places: Vec = Vec::new(); + for u in unreadable { + if !u + .error + .contains(forge_core::storage::read::NO_FOLLOWED_COPY) + { + return None; + } + let listed = u.error.split_once(ONLY).map_or("", |(_, rest)| rest); + for place in listed.split("; ").filter(|p| !p.is_empty()) { + if !places.iter().any(|p| p == place) { + places.push(place.to_string()); + } + } + } + (!unreadable.is_empty()).then_some(places) +} + /// The reader's "no external copy verified" text, short enough for one cause line: each /// copy's URL cut to its host (the full URLs are in `dg storage status`), without the /// generic `io error:` / `GET request failed:` layers or the gateway hint (a fix line says @@ -3081,6 +3121,46 @@ mod tests { assert!(incremental_fetch_complete(true, &filtered, &wants, || true)); } + #[test] + fn packs_recorded_only_where_no_reader_follows_get_the_move_them_fix() { + // QW2-078: reseed from the members, IPFS gateways and storage status cannot help a + // pack recorded only at a loopback address. + let private = |h: &str| Unreadable { + hash: h.repeat(64), + error: format!( + "io error: {}: its manifest records only 127.0.0.1:9000 (this machine or a \ + private network: never followed from a manifest); S3 bucket byo (read only \ + through a storage profile of yours for it)", + forge_core::storage::read::NO_FOLLOWED_COPY + ), + }; + let u = packs_unreadable("OWNER/repo", true, &[private("a"), private("b")], 3); + assert_eq!(u.code, "E503"); + assert_eq!(u.message, "clone incomplete: 2 packs unreadable"); + let cause = u.cause.clone().unwrap(); + // Each place once, for all the packs. + assert_eq!( + cause, + format!( + "2 of the repository's 3 packs: {}: they are recorded only at 127.0.0.1:9000 \ + (this machine or a private network: never followed from a manifest); S3 bucket \ + byo (read only through a storage profile of yours for it)", + forge_core::storage::read::NO_FOLLOWED_COPY + ) + ); + assert!( + u.fix[0].contains("dg reseed OWNER/repo --from-local --profile"), + "{:?}", + u.fix + ); + assert!(u.fix[1].contains("your own storage"), "{:?}", u.fix); + assert!( + !u.fix.iter().any(|f| f.contains("ipfs_gateways")), + "{:?}", + u.fix + ); + } + #[test] fn unreadable_packs_the_history_needs_are_e503_with_the_reseed_fix() { // D-403: git's "remote did not send all necessary objects" was all a user saw. diff --git a/docs/errors.md b/docs/errors.md index a2f5af7d7..e6b2e0da2 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -79,7 +79,7 @@ Fix: apply the suggestions that still fit, one by one or with `--all`, and edit ## E201 -**Invalid arguments.** The flags or arguments do not make sense together, for example `dg issue label` without exactly one of `--add` or `--remove`, or a value is not of the form the flag takes (a `--color` that is not a hex color). A command line `dg` cannot parse at all (a missing argument, an unknown flag) is E201 too: the cause quotes what is wrong, and the command's usage line follows the error block. Inside a `dash://` clone, a command that leaves out the repository uses the clone's, so `dg issue list` there is not an error. +**Invalid arguments.** The flags or arguments do not make sense together, for example `dg issue label` without exactly one of `--add` or `--remove`, or a value is not of the form the flag takes: a `--color` that is not a hex color, an empty `--title`, a text over its length limit, or a comment, review or thread id that is not a document id (`dg issue delete-comment 2`; the ids are in `dg issue view --json` and `dg pr view --comments --json`). A command line `dg` cannot parse at all (a missing argument, an unknown flag) is E201 too: the cause quotes what is wrong, and the command's usage line follows the error block. Inside a `dash://` clone, a command that leaves out the repository uses the clone's, so `dg issue list` there is not an error. Fix: see `dg --help`. @@ -141,9 +141,9 @@ Fix: pass the identity file with `--master `, or type the recovery words w ## E303 -**Identity unreadable.** The identity file or stored key is missing, unreadable, not a bridge-format identity export or `dfk1:` key, or a sealed key file could not be opened (wrong passphrase). +**Identity unreadable.** The identity file or stored key is missing, unreadable, not a bridge-format identity export or `dfk1:` key, or a sealed file could not be opened (wrong passphrase). A sealed file is your stored key, or a file a command reads besides it (`dg ci runner new --runner`, `--master`); the `cause:` line names which one. -Fix: `dg auth status` shows which key source is in use. Sign in again with `dg auth login ` or `dg auth login --mnemonic`. For a sealed file, set `DASH_FORGE_PASSPHRASE` or type the passphrase when asked. +Fix: `dg auth status` shows which key source is in use. Sign in again with `dg auth login ` or `dg auth login --mnemonic`. For a sealed file, set `DASH_FORGE_PASSPHRASE` or type the passphrase when asked. `DASH_FORGE_PASSPHRASE` is tried on every sealed file one command opens, so when your key and a `--runner` file have different passphrases, run the command in a terminal to be asked for each. Reads do not open the key: `dg auth status`, `dg auth balance`, and `dg storage status` / `dg cost audit` of a public repository work with a sealed key and no terminal (the status says the key itself was not checked). @@ -219,6 +219,8 @@ Fix: register a fresh limited key (uses the master key once): `dg auth login ` sets `dash.storage`. For an address problem, re-add the profile with a public https `--public-url` / `--public-gateway` (a bucket domain, a CDN, a named tunnel or a reverse proxy on your own domain), or record it anyway with `git push -o allow-private-uri`, `git config dash.allowPrivateUri true`, `dg storage add … --allow-private-uri`, or `--allow-private-uri` on `dg init` / `dg repo create`. See [bring your own storage](guides/bring-your-own-storage.md#public-addresses). @@ -240,6 +242,8 @@ Fix, in order: Fix: anyone whose clone still has the objects can restore the copies with `dg reseed / --from-local`, run inside that clone. If you know another IPFS gateway that has the pack, add it to `[read] ipfs_gateways` in `storage.toml` and try again. +When every copy a pack's manifest records is one no reader follows (the pusher's storage had a plain-http, loopback or private-network public address, recorded with `allow-private-uri`, or an S3 bucket with no public address), the cause says so for each copy, and neither a gateway nor a retry helps. The pusher can copy the packs to storage with a public https address from their clone: `dg reseed / --from-local --profile `. If that host or bucket is your own, add a storage profile for it and retry. + `dg release download` stops with E503 before downloading anything when none of the asset's recorded copies is one this computer reads from. A copy recorded on chain is followed only if it is a public https URL, an IPFS CID with a gateway to ask, or a bucket or host named in one of your own storage profiles. Plain http, loopback and private-network addresses are never followed just because a publisher recorded them. If the host is your own storage, add a profile whose `public_url` is it, and retry. ## E504 @@ -400,7 +404,7 @@ Fix: add your own storage (`dg storage add`, then `dg storage use`) so packs go **Confirmation required.** A cost-bearing or destructive `dg` command needs confirmation, and it cannot prompt: `--json` mode, or stdin is not a terminal. -Fix: pass `--yes` after checking the estimate (`dg cost estimate`). +Fix: pass `--yes` once you have checked what the command will do. The `cause:` line quotes the prompt, with its DASH estimate when the command prints one; `dg cost estimate` and `dg cost prices` give the rest. ## E803 diff --git a/docs/guides/quick-start.md b/docs/guides/quick-start.md index da12b3421..09dd2def4 100644 --- a/docs/guides/quick-start.md +++ b/docs/guides/quick-start.md @@ -107,7 +107,7 @@ dg auth login --network devnet --devnet-name bonsia ~/Downloads/dash-identity-`. Names work everywhere a repository address does: `forge.dashhq.org/alice/project`, `git clone dash://alice/project` and `dg … alice/project`. +Your identity id is the long base58 string, such as `8hJmcHWTsdvkHyCrk4UgjbyugDAmE7QfuCTQXpXAc7nB`. You will use it in repository addresses. A DPNS username is optional: `dg auth name register