Edit a proposal through the API; oh proposal edit, comment and create -F 739a763a558c

- **Edit a proposal and comment on one from `oh` (#76).** `PATCH /api/v1/repos/{owner}/{name}/proposals/{n}` changes the title or description, for the author or a maintainer as on the page; `oh proposal edit N [-t] [-b | -F FILE]`, `oh proposal comment N -b/-F`, and `oh proposal create -F FILE` ("-" reads stdin).

/// `PATCH /repos/{o}/{n}/proposals/{number}`: what is given changes,

/// the rest stays (oxygenhub#76).

#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct ProposalEdit {

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub title: Option<String>,

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub body: Option<String>,

}

        .route("/repos/{owner}/{name}/proposals/{number}", get(proposal).patch(edit_proposal))

/// `PATCH /repos/{o}/{n}/proposals/{number}`: change the title or body,

/// keeping what is not given; the author or a maintainer, as on the page

/// (oxygenhub#76). The target is changed on the page, which re-projects.

async fn edit_proposal(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name, number)): Path<(String, String, i64)>,

    Json(body): Json<hub_api::ProposalEdit>,

) -> Result<Json<Proposal>, ApiError> {

    let c = caller(&app, &headers).await?;

    let me = c.require("proposals:write").or_else(|_| c.require("repo:write"))?.clone();

    let (repo, row, role) = reach(&app, &c, &owner, &name, Access::Read).await?;

    let p = db::proposals::get(&app.db, row.id, number).await?.ok_or_else(|| not_found("no such proposal"))?;

    if Some(me.id) != p.author_id && role < Role::Maintain {

        return Err(ApiError(StatusCode::FORBIDDEN, "only the proposal's author or a maintainer can edit it".into()));

    }

    let title = match body.title.as_deref().map(str::trim) {

        Some("") => return Err(ApiError(StatusCode::BAD_REQUEST, "a proposal needs a title".into())),

        Some(t) => t,

        None => p.title.as_str(),

    };

    let text = body.body.as_deref().map(str::trim).unwrap_or(&p.body);

    db::proposals::edit(&app.db, p.id, title, text, &p.target).await?;

    db::proposals::add_event(&app.db, p.id, &me.username, "edited", "").await.ok();

    let p = db::proposals::get(&app.db, row.id, number).await?.ok_or_else(|| not_found("no such proposal"))?;

    let source_url = match p.source_repo_id {

        Some(id) => db::repos::get_by_id(&app.db, id).await?.map(|r| format!("{}/{}", app.config.base_url(), r.slug())),

        None => None,

    };

    let loaded = crate::web::proposals::load(&app, &repo, p).await?;

    let v = crate::web::proposals::verdict(&app, &loaded, row.id).await?;

    Ok(Json(crate::web::proposals::to_api(&app, &owner, &name, &loaded, &v, source_url).await))

}

    // oxygenhub#76: a proposal's title and description are edited through

    // the API by its author or a maintainer; what is not given stays.

    let edit = |token: &str, number: i64, body: &str| {

        let (app, token, body) = (app.clone(), token.to_string(), body.to_string());

        async move { api(&app, "PATCH", &format!("/api/v1/repos/andy/demo/proposals/{number}"), Some(&token), Some(&body)).await }

    };

    let (st, v) = edit(&bob_rw, 2, r#"{"body":"8 of 8, not 9 of 9"}"#).await;

    assert_eq!(st, StatusCode::OK, "{v}");

    assert_eq!((v["title"].as_str(), v["body"].as_str()), (Some("Feat"), Some("8 of 8, not 9 of 9")), "{v}");

    let (st, v) = edit(&andy_pw, 2, r#"{"title":"Feat, renamed"}"#).await;

    assert_eq!(st, StatusCode::OK, "a maintainer edits another's proposal: {v}");

    assert_eq!((v["title"].as_str(), v["body"].as_str()), (Some("Feat, renamed"), Some("8 of 8, not 9 of 9")));

    assert_eq!(edit(&bob_rw, 2, r#"{"title":"  "}"#).await.0, StatusCode::BAD_REQUEST, "a title is required");

    assert_eq!(edit(&bob_rw, 99, r#"{"body":"x"}"#).await.0, StatusCode::NOT_FOUND);

    // Andy's own proposal: Bob, a writer but not a maintainer, cannot edit it.

    let (st, v) = api(

        app,

        "POST",

        "/api/v1/repos/andy/demo/proposals",

        Some(&andy_pw),

        Some(r#"{"title":"Andy's","target":"main","source":"feature/1-one"}"#),

    )

    .await;

    assert_eq!(st, StatusCode::CREATED, "{v}");

    let n = v["number"].as_i64().unwrap();

    assert_eq!(edit(&bob_rw, n, r#"{"body":"mine now"}"#).await.0, StatusCode::FORBIDDEN);

    assert_eq!(edit(&andy_ro, 2, r#"{"body":"x"}"#).await.0, StatusCode::FORBIDDEN, "a read-only token cannot edit");

        /// Read the body from a file ("-" for stdin)

        #[arg(long, short = 'F', conflicts_with = "body")]

        body_file: Option<String>,

    },

    /// Change a proposal's title or description (its author or a maintainer)

    Edit {

        number: i64,

        #[arg(long, short)]

        title: Option<String>,

        #[arg(long, short)]

        body: Option<String>,

        /// Read the body from a file ("-" for stdin)

        #[arg(long, short = 'F', conflicts_with = "body")]

        body_file: Option<String>,

    /// Comment on a proposal's conversation

    Comment {

        number: i64,

        #[arg(long, short)]

        body: Option<String>,

        /// Read the comment from a file ("-" for stdin)

        #[arg(long, short = 'F', conflicts_with = "body")]

        body_file: Option<String>,

    },

        ProposalCmd::Create { title, body, body_file, from, into, draft } => {

            let new = NewProposal { title, body: body_of(body, body_file)?, target, source: from, draft };

        }

        ProposalCmd::Edit { number, title, body, body_file } => {

            let body = match (&body, &body_file) {

                (None, None) => None,

                _ => Some(body_of(body, body_file)?),

            };

            if title.is_none() && body.is_none() {

                bail!("say what to change: --title, --body or --body-file");

            }

            let edit = hub_api::ProposalEdit { title, body };

            let p: Proposal = c.send("PATCH", &format!("{base}/proposals/{number}"), &edit)?;

            if json {

                println!("{}", serde_json::to_string(&p)?);

            } else {

                println!("{} edited #{} {}", ui::ok("✔"), p.number, ui::dim(&p.url));

            }

        }

        ProposalCmd::Comment { number, body, body_file } => {

            let body = body_of(body, body_file)?;

            if body.trim().is_empty() {

                bail!("give the comment with --body or --body-file");

            }

            c.send_text("POST", &format!("{base}/proposals/{number}/comments"), &NewComment { body, path: None, line: None })?;

            println!("{} commented on #{number}", ui::ok("✔"));

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses (an unknown route too), cursor pagination (`?after=`), ETags on cacheable resources, and rate limits per token. Resources mirror the pages: `/repos/{owner}/{name}`, `/bookmarks`, `/changes/{hash}`, `/tree/{ref}/{path}`, `/file/{ref}/{path}`, `/blame`, `/history`, `/compare`, `/conflicts`, `/proposals` (`?state=open|draft|landed|closed|all`, open ones and drafts by default; a source bookmark may hold `/`, and `owner/name:bookmark` naming the repository itself is its own bookmark), `/proposals/{n}/comments|reviews|checks|files`, `PATCH /proposals/{n}` (the title and description, for its author or a maintainer; what is not given stays), `POST /proposals/{n}/land` (repo:write: what the Land button does, `409` with the blockers when it cannot; a landed proposal keeps the changes it landed and reports `landed` with who, how (`web`, or `api (token NAME)`) and when, which its event, the audit log and the push record also say, adding when nobody approved), `/proposals/{n}/content/{base|head}/{path}` (a changed file's bytes in the target's state or the projected state, for editor diff views), `/issues` (creating an issue can set its labels, assignees and milestone; `PATCH /issues/{n}` edits the title and body for the author or triage, and replaces labels, assignees or the milestone for triage, recording each on the timeline; unknown names are refused before anything changes), `/labels` (`POST` creates or changes one, `DELETE /labels/{name}` removes it; triage), `/milestones`, `/releases` (`PATCH /releases/{tag}` changes the title, notes or prerelease flag, repo:write), `/tags`, `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/notifications` (the caller's inbox and unread count; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/orgs/{name}`, `/checks/{state}` (the checks on a state, named by its hash, by its heads joined with `+`, by the one head of a single-head state, or by a bookmark), `/checks/required` (`GET`, and `PUT` of the whole list by a repository admin: the checks a proposal needs, passed, to land), `/projects/{owner}` (list, create) and `/projects/{owner}/{n}` (the board as the caller may see it, `PATCH` for title, description, privacy and closing, `/cards` to add a reference or note to a column named by id or name, `/cards/{id}` to move or remove one; `repo:write` and the page's rights to change), `/flow/runs` (`GET`: runs newest first, `?before=N&limit=`; `POST {"bookmark"}` or `{"change"}`, repo:write: run a bookmark's current state, the default bookmark when none is named, or one change's state), `/flow/runs/{n}` (a run with its jobs), `/flow/runs/{n}/jobs/{job}/log` (`?after=seq&limit=`) and `/flow/runs/{n}/rerun` (repo:write: a finished run again), both answering `201 {"number", "url"}` or `409` with why nothing started, `/search`. A change's author carries the account its key is linked to, or `null` and a `note` saying the key is not linked and where its owner links it (the change page shows a "key not linked" tag, with a link to Settings → Keys for signed-in viewers). Shapes reuse `oxy --json` shapes wherever one exists (change, status, blame, diff) so tools written against the CLI work against the hub. `crates/hub-api` holds the types with `serde` derives and is what the runner and the VS Code extension will link.