Board columns by API and oh, newest-run watch, close with a comment (closes #366, closes #367, closes #368) 306aec1839aa

## Unreleased

- **A board's columns from the API and `oh` (#366):** `POST /projects/{owner}/{n}/columns` adds one at the right, `PATCH …/columns/{column}` (by id or name) renames it or moves it to a `position`, and `DELETE` removes it, its cards going to the first remaining column; each answers the board. `oh project column add|rename|move|remove BOARD …` (`move --to N`, counting from 1 at the left, `--left`, `--right`), so a sprint column is renamed without the web page.

- **`oh run watch` and `oh run view` take the newest run (#367):** with no number they follow or show the newest run, or the newest of `--bookmark NAME`, so the run a push just started needs no lookup.

- **`oh issue close` and `reopen` say why (#368):** `-b`, `-F` and `--attach` post a comment first, in the same command.

/// `POST /projects/{owner}/{n}/columns` (#366): a column at the right.

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

pub struct NewColumn {

    pub name: String,

}

/// `PATCH /projects/{owner}/{n}/columns/{column}` (#366): rename it, move

/// it to `position` (0 is the leftmost; past the end is the rightmost), or

/// both. What is not given stays.

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

pub struct ColumnEdit {

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

    pub name: Option<String>,

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

    pub position: Option<i64>,

}

        ("NewColumn", schemars::schema_for!(NewColumn)),

        ("ColumnEdit", schemars::schema_for!(ColumnEdit)),

        .route("/projects/{owner}/{number}/columns", post(projects::add_column))

        .route("/projects/{owner}/{number}/columns/{column}", axum::routing::patch(projects::edit_column).delete(projects::remove_column))

    board_of(&app, &c, &owner, number).await

}

/// A board's columns as `GET /projects/{owner}/{n}` gives them, for the

/// column calls to answer with (#366).

async fn board_of(app: &Shared, c: &Caller, owner: &str, number: i64) -> Result<Json<Board>, ApiError> {

    let (_, p) = visible(app, c, owner, number).await?;

    let (columns, _) = wp::board_columns(app, c.account.as_ref(), owner, &p, false).await?;

    Ok(Json(Board {

        project: project_of(app, &p),

        columns: columns

            .iter()

            .map(|col| ProjectColumn { id: col.column.id, name: col.column.name.clone(), cards: col.cards.iter().map(card_of).collect() })

            .collect(),

    }))

}

/// A column's name: trimmed, 1 to 40 characters, as the board page has it.

fn column_name(name: &str) -> Result<&str, ApiError> {

    let name = name.trim();

    if name.is_empty() || name.chars().count() > 40 {

        return Err(ApiError(StatusCode::BAD_REQUEST, "a column has a name of 1 to 40 characters".into()));

    }

    Ok(name)

}

/// `POST /projects/{owner}/{n}/columns` (#366): add a column at the right;

/// answers the board.

pub async fn add_column(

    State(app): State<Shared>,

    headers: HeaderMap,

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

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

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

    let (c, p) = changeable(&app, &headers, &owner, number, false).await?;

    let name = column_name(&body.name)?;

    if pdb::columns(&app.db, p.id).await?.iter().any(|col| col.name.eq_ignore_ascii_case(name)) {

        return Err(ApiError(StatusCode::CONFLICT, format!("the board has a column {name} already")));

    }

    pdb::add_column(&app.db, p.id, name).await?;

    board_of(&app, &c, &owner, number).await

}

/// `PATCH /projects/{owner}/{n}/columns/{column}` (#366): rename or move a

/// column named by id or name; answers the board.

pub async fn edit_column(

    State(app): State<Shared>,

    headers: HeaderMap,

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

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

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

    let (c, p) = changeable(&app, &headers, &owner, number, false).await?;

    let col = named_column(&app, p.id, &spec).await?;

    if body.name.is_none() && body.position.is_none() {

        return Err(ApiError(StatusCode::BAD_REQUEST, "say what to change: name or position".into()));

    }

    if let Some(name) = body.name.as_deref() {

        let name = column_name(name)?;

        let others = pdb::columns(&app.db, p.id).await?;

        if others.iter().any(|o| o.id != col.id && o.name.eq_ignore_ascii_case(name)) {

            return Err(ApiError(StatusCode::CONFLICT, format!("the board has a column {name} already")));

        }

        pdb::rename_column(&app.db, p.id, col.id, name).await?;

    }

    if let Some(pos) = body.position {

        pdb::place_column(&app.db, p.id, col.id, pos).await?;

    }

    board_of(&app, &c, &owner, number).await

}

/// `DELETE /projects/{owner}/{n}/columns/{column}` (#366): its cards go to

/// the first remaining column; a board keeps at least one. Answers the board.

pub async fn remove_column(

    State(app): State<Shared>,

    headers: HeaderMap,

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

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

    let (c, p) = changeable(&app, &headers, &owner, number, false).await?;

    let col = named_column(&app, p.id, &spec).await?;

    if !pdb::remove_column(&app.db, p.id, col.id).await? {

        return Err(ApiError(StatusCode::CONFLICT, "a board keeps at least one column".into()));

    }

    board_of(&app, &c, &owner, number).await

}

/// A column named by id or name, or 404.

async fn named_column(app: &Shared, project_id: i64, spec: &str) -> Result<pdb::Column, ApiError> {

    let cols = pdb::columns(&app.db, project_id).await?;

    cols.into_iter()

        .find(|c| c.id.to_string() == spec.trim() || c.name.eq_ignore_ascii_case(spec.trim()))

        .ok_or_else(|| ApiError(StatusCode::NOT_FOUND, format!("no column {spec}")))

/// Move a column to `position` (0 the leftmost; past the end the rightmost).

pub async fn place_column(pool: &Pool, project_id: i64, column_id: i64, position: i64) -> sqlx::Result<()> {

    let cols = columns(pool, project_id).await?;

    let Some(i) = cols.iter().position(|c| c.id == column_id) else { return Ok(()) };

    let mut ids: Vec<i64> = cols.iter().map(|c| c.id).collect();

    let id = ids.remove(i);

    ids.insert((position.max(0) as usize).min(ids.len()), id);

    for (pos, id) in ids.iter().enumerate() {

        sqlx::query("UPDATE project_columns SET position = $1 WHERE id = $2").bind(pos as i64).bind(id).execute(pool).await?;

    }

    touch(pool, project_id).await

}

    // Columns by API (#366): add, rename, move, remove; answers are the board.

    let col_names = |v: &serde_json::Value| -> Vec<String> {

        v["columns"].as_array().unwrap().iter().map(|c| c["name"].as_str().unwrap().to_string()).collect()

    };

    let (st, v) = api(app, "POST", "/api/v1/projects/andy/1/columns", Some(&a), Some(r#"{"name":"Sprint 1"}"#)).await;

    assert_eq!((st, col_names(&v)), (StatusCode::OK, vec!["Backlog".to_string(), "Doing".into(), "Done".into(), "Sprint 1".into()]), "{v}");

    assert_eq!(api(app, "POST", "/api/v1/projects/andy/1/columns", Some(&a), Some(r#"{"name":"sprint 1"}"#)).await.0, StatusCode::CONFLICT);

    assert_eq!(api(app, "POST", "/api/v1/projects/andy/1/columns", Some(&a), Some(r#"{"name":"  "}"#)).await.0, StatusCode::BAD_REQUEST);

    assert_eq!(api(app, "POST", "/api/v1/projects/andy/1/columns", Some(&b), Some(r#"{"name":"Mine"}"#)).await.0, StatusCode::FORBIDDEN);

    let (st, v) =

        api(app, "PATCH", "/api/v1/projects/andy/1/columns/Sprint%201", Some(&a), Some(r#"{"name":"Sprint 2","position":0}"#)).await;

    assert_eq!((st, col_names(&v)), (StatusCode::OK, vec!["Sprint 2".to_string(), "Backlog".into(), "Doing".into(), "Done".into()]), "{v}");

    let sprint = v["columns"][0]["id"].as_i64().unwrap();

    let (_, v) = api(app, "PATCH", &format!("/api/v1/projects/andy/1/columns/{sprint}"), Some(&a), Some(r#"{"position":99}"#)).await;

    assert_eq!(col_names(&v).last().map(String::as_str), Some("Sprint 2"));

    assert_eq!(api(app, "PATCH", "/api/v1/projects/andy/1/columns/Sprint%202", Some(&a), Some("{}")).await.0, StatusCode::BAD_REQUEST);

    assert_eq!(

        api(app, "PATCH", "/api/v1/projects/andy/1/columns/Sprint%202", Some(&a), Some(r#"{"name":"done"}"#)).await.0,

        StatusCode::CONFLICT

    );

    assert_eq!(

        api(app, "PATCH", "/api/v1/projects/andy/1/columns/nope", Some(&a), Some(r#"{"position":0}"#)).await.0,

        StatusCode::NOT_FOUND

    );

    let (st, v) = api(app, "DELETE", "/api/v1/projects/andy/1/columns/Sprint%202", Some(&a), None).await;

    assert_eq!((st, col_names(&v)), (StatusCode::OK, vec!["Backlog".to_string(), "Doing".into(), "Done".into()]), "{v}");

    /// Close an issue, with an optional comment saying why

        #[command(flatten)]

        comment: StateComment,

    /// Reopen an issue, with an optional comment saying why

    Reopen {

        number: i64,

        #[command(flatten)]

        comment: StateComment,

    },

    },

    /// A board's columns: add, rename, move, remove (#366)

    Column {

        #[command(subcommand)]

        cmd: ColumnCmd,

    },

}

#[derive(Subcommand)]

enum ColumnCmd {

    /// Add a column at the right

    Add {

        /// The board

        number: i64,

        name: String,

    /// Rename a column (by name or id)

    Rename {

        /// The board

        number: i64,

        column: String,

        /// Its new name

        to: String,

    },

    /// Move a column: --to POSITION (1 is the leftmost), --left or --right

    Move {

        /// The board

        number: i64,

        column: String,

        /// Its place, counting from 1 at the left

        #[arg(long, conflicts_with_all = ["left", "right"], required_unless_present_any = ["left", "right"])]

        to: Option<i64>,

        /// One place to the left

        #[arg(long, conflicts_with = "right")]

        left: bool,

        /// One place to the right

        #[arg(long)]

        right: bool,

    },

    /// Remove a column; its cards go to the first remaining one

    Remove {

        /// The board

        number: i64,

        column: String,

    },

    /// A run and its jobs (default: the newest run)

        /// The run (default: the newest, or the newest of --bookmark)

        number: Option<i64>,

        /// With no number: the newest run of this bookmark

        #[arg(long, conflicts_with = "number")]

        bookmark: Option<String>,

    /// Follow a run until it finishes (default: the newest run); exit 1 unless it passes

    Watch {

        /// The run (default: the newest, or the newest of --bookmark) (#367)

        number: Option<i64>,

        /// With no number: the newest run of this bookmark

        #[arg(long, conflicts_with = "number")]

        bookmark: Option<String>,

    },

        IssueCmd::Close { number, reason, comment } => {

            comment.post(c, &base, &format!("{base}/issues/{number}/comments"))?;

        IssueCmd::Reopen { number, comment } => {

            comment.post(c, &base, &format!("{base}/issues/{number}/comments"))?;

}

/// A comment to post with a close or reopen (#368): saying why, in the

/// same command.

#[derive(clap::Args)]

struct StateComment {

    /// Say why, as a comment posted first

    #[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>,

    /// Attach a file to the comment (repeatable)

    #[arg(long, short = 'a', value_name = "FILE")]

    attach: Vec<std::path::PathBuf>,

}

impl StateComment {

    fn post(self, c: &Client, base: &str, path: &str) -> Result<()> {

        if self.body.is_none() && self.body_file.is_none() && self.attach.is_empty() {

            return Ok(());

        }

        let body = with_attachments(c, base, body_of(self.body, self.body_file)?, &self.attach)?;

        if !body.trim().is_empty() {

            c.send_text("POST", path, &NewComment { body, path: None, line: None })?;

        }

        Ok(())

    }

}

/// `number`, or the newest run (of `bookmark`, when given): what a push

/// just started is what one usually wants to follow (#367).

fn run_or_newest(c: &Client, base: &str, number: Option<i64>, bookmark: Option<&str>) -> Result<i64> {

    if let Some(n) = number {

        return Ok(n);

    }

    let runs: Vec<FlowRun> = c.get(&format!("{base}/flow/runs?limit=100"))?;

    runs.iter().filter(|r| bookmark.is_none_or(|b| r.bookmark == b)).map(|r| r.number).max().with_context(|| match bookmark {

        Some(b) => format!("no runs of {b} among the latest 100"),

        None => "no runs yet".to_string(),

    })

        RunCmd::View { number, bookmark, timings } => {

            let number = run_or_newest(c, &base, number, bookmark.as_deref())?;

        RunCmd::Watch { number, bookmark } => {

            let number = run_or_newest(c, &base, number, bookmark.as_deref())?;

            return watch(c, &base, number, json);

        }

            }

        }

        ProjectCmd::Column { cmd } => {

            let col_path = |number: i64, column: &str| format!("{base}/{number}/columns/{}", enc(column));

            let (number, b, what): (i64, hub_api::Board, String) = match cmd {

                ColumnCmd::Add { number, name } => {

                    let b = c.send("POST", &format!("{base}/{number}/columns"), &hub_api::NewColumn { name: name.clone() })?;

                    (number, b, format!("added column {name}"))

                }

                ColumnCmd::Rename { number, column, to } => {

                    let edit = hub_api::ColumnEdit { name: Some(to.clone()), position: None };

                    (number, c.send("PATCH", &col_path(number, &column), &edit)?, format!("renamed column {column} to {to}"))

                }

                ColumnCmd::Move { number, column, to, left, right } => {

                    let position = match to {

                        Some(n) => n - 1,

                        None => {

                            let now: hub_api::Board = c.get(&format!("{base}/{number}"))?;

                            let at = now

                                .columns

                                .iter()

                                .position(|col| col.id.to_string() == column || col.name.eq_ignore_ascii_case(&column))

                                .with_context(|| format!("no column {column} on board {number}"))?

                                as i64;

                            if left {

                                (at - 1).max(0)

                            } else {

                                debug_assert!(right);

                                at + 1

                            }

                        }

                    };

                    let edit = hub_api::ColumnEdit { name: None, position: Some(position) };

                    (number, c.send("PATCH", &col_path(number, &column), &edit)?, format!("moved column {column}"))

                }

                ColumnCmd::Remove { number, column } => {

                    (number, c.send("DELETE", &col_path(number, &column), &serde_json::json!({}))?, format!("removed column {column}"))

                }

            };

            if json {

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

            } else {

                let order: Vec<&str> = b.columns.iter().map(|col| col.name.as_str()).collect();

                println!("{} {what} on board {number}: {}", ui::ok("✔"), ui::dim(&order.join(" · ")));

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses (an unknown route, or a known one with the wrong method, 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/{ref}` (`?path=`, `?offset=&limit=`, or `?r=REVSET` for the changes a revset selects, evaluated under a two-second budget and answering 400 when it does not parse or goes past it; Oxygen's docs/revset_query_language.md), `/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, and `labels`, the whole set by name, for triage; 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` (`POST` creates one or changes the description and due date of the one with that title, `PATCH /milestones/{title}` changes title, description, due date or state; triage), `/releases` (`PATCH /releases/{tag}` changes the title, notes or prerelease flag, repo:write), `/tags` (`POST` creates one, repo:write; `DELETE /tags/{tag}` withdraws one, a maintainer, `409` while a release uses it; §9), `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/user/repos` (the caller's own, organisations' and collaborations, `?affiliation=&after=&limit=`, #302), `/user/orgs`, `/user/sky` (Your sky's data, the dashboard backdrop's: the caller's repositories and their events of the last 30 days as `[repo, kind, at_ms, n]`, for the Android app; oxygenhub-android#23; `/repos/{owner}/{name}/sky` gives one repository's, its pages' backdrop), `/user/issues` (the open issues assigned to the caller, in repositories it can see, newest-updated first, each with its repository and address; #359), `/user/flow/runs` (the newest Flow runs of the caller's repositories, each with its repository and jobs, `?before=MS&limit=`; oxygenhub-android#26), `/user/starter?owner=X` and `/repos/{owner}/{name}/starter` (#347: the assistants a new repository under X may ask, and, `POST {"description", "assistant"}` by its admin, an assistant's draft of an empty repository's starting files, committed in the background as the caller, the hub signing as their delegate; `GET` says `running`, `done` with the change and files, or `failed` with why), `/notifications` (the caller's inbox and unread count, each with its repository, reason, thread and label, #305; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/users/{name}/drops` and `/drops` (§4.5), `/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, and `owner` to transfer it to an owner the caller may make boards under (#125: it takes the next number there, and its old address redirects), `/cards` to list them by column or add a reference or note to a column named by id or name, `/cards/{id}` to move or remove one, `POST /columns` (`{"name"}`, at the right), `PATCH /columns/{column}` (by id or name: `{"name", "position"}`, 0 the leftmost) and `DELETE /columns/{column}` (its cards to the first remaining column; a board keeps one) for its columns, each answering the board (#366), `POST /cards/move` (#289: `{"from", "column", "except", "state", "dry_run"}`) to move a column's cards at once, but those `except` names (card ids or issue and proposal references) and, given `state`, only those whose issue or proposal is in one, all or none and audited once, answering what moved and what was kept; `POST /cards/archive` (#293: `{"from", "older_days", "except", "state", "dry_run"}`, the same selection and an age) to archive them, `GET /cards?archived=true` to list the archived ones (each with `archived_ms`) and `POST /cards/{id}/restore` to put one back; cards carry their `labels` and `assignees`; `repo:write` and the page's rights to change), `/coverage` and `/tests` (a bookmark's coverage and JUnit test reports from Flow jobs, newest first, `?bookmark=&limit=`), `POST /coverage` (repo:write, #136: `{"bookmark"}` or `{"change"}` and `content`, an LCOV, Cobertura or JaCoCo report measured off the hub, kept for that state as uploaded by the caller, shown "uploaded by NAME" wherever a run number would be, and setting no check; `oh coverage upload FILE`), `/coverage/{id}` (a report with its files) and `/tests/{id}` (a report with its cases, `?status=failed` for the failed and errored ones), `/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; with `"jobs": [NAME..]` only those jobs and what they depend on, each one a manual run starts, else `409` naming the ones it does (#130); `oh run start --job NAME`), `/flow/runs/{n}` (a run with its jobs, each with its timings: `queued_ms`, `ready_ms`, the `phases` its runner reported (image, prepare, run, finish, in milliseconds) and its peak disk and memory; #348, `oh run view N --timings`), `/flow/runs/{n}/jobs/{job}/log` (`?after=seq&limit=`), `/flow/runs/{n}/jobs/{job}/reports` and `/flow/runs/{n}/jobs/{job}/report` (`?name=`; with its files, and `…/report/{path}` one file as published, sandboxed) and `/reports` (`?bookmark=`: the newest run of each) and `/reports/{name}` (`?id=` or `?bookmark=`; `…/files/{path}`): the reports Flow jobs publish (#348, docs/reports.md §6; `oh run report N JOB`, `oh report`) and `/flow/runs/{n}/rerun` (repo:write: a finished run again), both answering `201 {"number", "url"}` or `409` with why nothing started, `/flow/runs/{n}/jobs/{job}/rerun` (repo:write, oxygenflow#31: that job of a finished run again, in the same run, with the jobs that depend on it; what it depends on keeps its result, so a flaky test reruns without its build; their logs, artifacts and reports go, their checks return to queued and the run is running again; `{"queued": N}`, or `409` while the run is live or for a job it lacks; RE-RUN THIS JOB on the run page, `oh run rerun N --job NAME`), `/flow/runs/{n}/cancel` (repo:write: a run still going ends as `cancelled`, its running jobs stopped when their runner next reports; `409` when it had already ended; a push to a bookmark cancels the push runs of it still going), `/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; `via` names the delegate (an agent) that signed for the author when one did, with the delegation's scope and expiry and whether it has since been revoked, and the pages show the same as an `agent` badge, a `via` row under the author on the change page, and a count under the author in Contributors (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.