oh project: boards from the command line; GET .../cards 17a3a84b00d1

/// A known route asked with a method it does not take: a problem body

/// rather than axum's empty 405 (oxygenhub#115).

async fn wrong_method(method: axum::http::Method, uri: axum::http::Uri) -> ApiError {

    ApiError(StatusCode::METHOD_NOT_ALLOWED, format!("{} is an API route, but not for {method}", uri.path()))

}

        .route("/projects/{owner}/{number}/cards", get(projects::cards).post(projects::add_card))

        // Last: it applies to the routes registered before it.

        .method_not_allowed_fallback(wrong_method)

/// `GET /projects/{owner}/{n}/cards`: the cards by column, as the board

/// has them.

pub async fn cards(

    State(app): State<Shared>,

    headers: HeaderMap,

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

) -> Result<Json<Vec<ProjectColumn>>, ApiError> {

    Ok(Json(board(State(app), headers, Path((owner, number))).await?.0.columns))

}

    // The cards by column (#115), and a wrong method answers with a body.

    let (st, cols) = api(app, "GET", "/api/v1/projects/andy/1/cards", None, None).await;

    assert_eq!(st, StatusCode::OK);

    assert_eq!(cols, board["columns"]);

    let (st, v) = api(app, "PUT", "/api/v1/projects/andy/1/cards", Some(&a), Some("{}")).await;

    assert_eq!(st, StatusCode::METHOD_NOT_ALLOWED);

    assert!(v["detail"].as_str().unwrap().contains("not for PUT"), "{v}");

    /// Project boards of the repository's owner (or --owner): list,

    /// create, view, and cards

    Project {

        #[command(subcommand)]

        cmd: ProjectCmd,

        /// A user or organisation other than the repository's owner

        #[arg(long, global = true)]

        owner: Option<String>,

    },

        /// Also put it on this board of the repository's owner

        #[arg(long, short)]

        project: Option<i64>,

        /// The board's column for it, by name (default: the first)

        #[arg(long, requires = "project")]

        column: Option<String>,

}

#[derive(Subcommand)]

enum ProjectCmd {

    /// The owner's boards

    List,

    /// One board: its columns and cards

    View { number: i64 },

    /// Create a board (owner, or an organisation's members)

    Create {

        title: String,

        #[arg(long, short, default_value = "")]

        description: String,

        /// Only the owner (or the organisation's members) can see it

        #[arg(long)]

        private: bool,

    },

    /// Close a board

    Close { number: i64 },

    /// Reopen a board

    Reopen { number: i64 },

    /// Cards on a board: add, move, remove

    Card {

        #[command(subcommand)]

        cmd: CardCmd,

    },

enum CardCmd {

    /// Put an issue or proposal on a board (`12` or `#12` in this

    /// repository, `name#12` or `owner/name#12` in another of the owner's),

    /// or a note with --note

    Add {

        number: i64,

        /// The issue or proposal; a number means this repository's

        reference: Option<String>,

        /// A note card instead

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

        note: Option<String>,

        /// The column, by name or id (default: the first)

        #[arg(long, short)]

        column: Option<String>,

    },

    /// Move a card to another column (by name or id)

    Move {

        number: i64,

        card: i64,

        #[arg(long, short)]

        column: String,

    },

    /// Take a card off a board

    Remove { number: i64, card: i64 },

}

#[derive(Subcommand)]

        Cmd::Project { cmd, owner } => project(&c, &t, cmd, owner, json),

        IssueCmd::Create { title, body, body_file, label, project, column } => {

            }

            if let Some(n) = project {

                let card = hub_api::NewCard { column, reference: format!("{}#{}", t.name, i.number), note: String::new() };

                let added: hub_api::ProjectCard = c.send("POST", &format!("/projects/{}/{n}/cards", t.owner), &card)?;

                if !json {

                    println!("{} on project {n} as card {}", ui::ok("✔"), added.id);

                }

        }

    }

    Ok(0)

}

fn project_line(p: &hub_api::Project) -> String {

    let glyph = if p.closed { ui::dim("▢") } else { ui::ok("▣") };

    let private = if p.public { "" } else { " · private" };

    format!("{glyph} {} {}  {}", ui::dim(&p.number.to_string()), p.title, ui::dim(&format!("updated {}{private}", ui::ago(p.updated_ms))))

}

fn project(c: &Client, t: &Target, cmd: ProjectCmd, owner: Option<String>, json: bool) -> Result<i32> {

    let owner = match owner {

        Some(o) => o,

        None => t.repo()?.0.to_string(),

    };

    let base = format!("/projects/{}", enc(&owner));

    let state = |number: i64, closed: bool, verb: &str| -> Result<()> {

        let p: hub_api::Project =

            c.send("PATCH", &format!("{base}/{number}"), &hub_api::ProjectEdit { closed: Some(closed), ..Default::default() })?;

        if json {

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

        } else {

            println!("{} {verb} project {} {}", ui::ok("✔"), p.number, p.title);

        }

        Ok(())

    };

    match cmd {

        ProjectCmd::List => {

            if json {

                println!("{}", c.get_text(&base)?);

                return Ok(0);

            }

            let list: Vec<hub_api::Project> = c.get(&base)?;

            if list.is_empty() {

                println!("{}", ui::dim(&format!("No projects for {owner}: oh project create TITLE")));

            }

            for p in &list {

                println!("{}", project_line(p));

            }

        }

        ProjectCmd::View { number } => {

            let path = format!("{base}/{number}");

            if json {

                println!("{}", c.get_text(&path)?);

                return Ok(0);

            }

            let b: hub_api::Board = c.get(&path)?;

            println!("{}", project_line(&b.project));

            if !b.project.description.is_empty() {

                println!("{}", b.project.description);

            }

            for col in &b.columns {

                println!();

                println!("{} {}", ui::strong(&col.name), ui::dim(&format!("{} · column {}", col.cards.len(), col.id)));

                if col.cards.is_empty() {

                    println!("  {}", ui::dim("(empty)"));

                }

                for card in &col.cards {

                    let what = if card.reference.is_empty() { ui::dim("note") } else { card.reference.clone() };

                    let st = if card.state.is_empty() { String::new() } else { format!(" {}", ui::dim(&card.state)) };

                    println!("  {} {what}{st}  {}", ui::dim(&format!("{:>4}", card.id)), card.title);

                }

            }

            println!("{}", ui::dim(&format!("\n{}", b.project.url)));

        }

        ProjectCmd::Create { title, description, private } => {

            let p: hub_api::Project = c.send("POST", &base, &hub_api::NewProject { title, description, private })?;

            if json {

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

            } else {

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

            }

        }

        ProjectCmd::Close { number } => state(number, true, "closed")?,

        ProjectCmd::Reopen { number } => state(number, false, "reopened")?,

        ProjectCmd::Card { cmd: CardCmd::Add { number, reference, note, column } } => {

            // The hub names a card's issue as `repo#N` among the owner's

            // repositories.

            let reference = match reference {

                None => String::new(),

                Some(r) if r.contains('#') && !r.starts_with('#') => match r.split_once('/') {

                    Some((o, rest)) if o == owner => rest.to_string(),

                    Some(_) => bail!("{r}: a project holds only {owner}'s issues and proposals"),

                    None => r,

                },

                Some(r) => {

                    let n = r.trim_start_matches('#');

                    if n.parse::<i64>().is_err() {

                        bail!("{r}: give an issue or proposal number, or NAME#N");

                    }

                    format!("{}#{n}", t.repo()?.1)

                }

            };

            let note = note.unwrap_or_default();

            if reference.is_empty() && note.is_empty() {

                bail!("say what to add: an issue or proposal (12, #12, owner/name#12) or --note TEXT");

            }

            let card: hub_api::ProjectCard =

                c.send("POST", &format!("{base}/{number}/cards"), &hub_api::NewCard { column, reference, note })?;

            if json {

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

            } else {

                println!("{} card {} {}", ui::ok("✔"), card.id, if card.reference.is_empty() { &card.title } else { &card.reference });

            }

        }

        ProjectCmd::Card { cmd: CardCmd::Move { number, card, column } } => {

            c.send_text("PATCH", &format!("{base}/{number}/cards/{card}"), &hub_api::CardMove { column: column.clone() })?;

            println!("{} card {card} moved to {column}", ui::ok("✔"));

        }

        ProjectCmd::Card { cmd: CardCmd::Remove { number, card } } => {

            c.send_text("DELETE", &format!("{base}/{number}/cards/{card}"), &serde_json::json!({}))?;

            println!("{} card {card} removed", ui::ok("✔"));

    // Project boards (#115): create, an issue straight onto a column, a

    // note, view, move, remove.

    let (code, out, err) = oh(w, &[], &["project", "create", "Roadmap", "-d", "Next up"]).await;

    assert_eq!(code, 0, "{err}");

    assert!(out.contains("project 1 Roadmap"), "{out}");

    let (code, out, err) = oh(w, &[], &["issue", "create", "--title", "Plan it", "--project", "1", "--column", "doing"]).await;

    assert_eq!(code, 0, "{err}");

    assert!(out.contains("opened #2") && out.contains("on project 1"), "{out}");

    let (code, _, err) = oh(w, &[], &["project", "card", "add", "1", "--note", "Write docs"]).await;

    assert_eq!(code, 0, "{err}");

    let (code, out, err) = oh(w, &[], &["project", "view", "1", "--plain"]).await;

    assert_eq!(code, 0, "{err}");

    assert!(out.contains("Doing") && out.contains("andy/demo#2") && out.contains("Plan it") && out.contains("Write docs"), "{out}");

    let (_, out, _) = oh(w, &[], &["project", "view", "1", "--json"]).await;

    let board: serde_json::Value = serde_json::from_str(&out).unwrap();

    let card = board["columns"][1]["cards"][0]["id"].as_i64().unwrap().to_string();

    let (code, out, err) = oh(w, &[], &["project", "card", "move", "1", &card, "--column", "Done"]).await;

    assert_eq!(code, 0, "{err}");

    assert!(out.contains("moved to Done"), "{out}");

    let (_, out, _) = oh(w, &[], &["project", "view", "1", "--json"]).await;

    let board: serde_json::Value = serde_json::from_str(&out).unwrap();

    assert_eq!(board["columns"][2]["cards"][0]["reference"], "andy/demo#2");

    let (code, _, err) = oh(w, &[], &["project", "card", "add", "1", "2"]).await;

    assert_ne!(code, 0);

    assert!(err.contains("already on this project"), "{err}");

    let (code, _, err) = oh(w, &[], &["project", "card", "remove", "1", &card]).await;

    assert_eq!(code, 0, "{err}");

    let (_, out, _) = oh(w, &[], &["project", "list", "--plain"]).await;

    assert!(out.contains("Roadmap"), "{out}");

    let (code, out, _) = oh(w, &[], &["project", "close", "1"]).await;

    assert_eq!(code, 0);

    assert!(out.contains("closed project 1"), "{out}");

| `oh issue create -t TITLE [-b BODY \| -F FILE] [-l LABEL]… [-p N [--column NAME]]` | Open an issue; `-p` also puts it on the owner's project N |

| `oh project list`, `oh project view N`, `oh project create TITLE [-d DESC] [--private]`, `oh project close\|reopen N` | The repository owner's project boards (`--owner NAME` for another's) |

| `oh project card add N REF [-c COLUMN]`, `oh project card add N --note TEXT`, `oh project card move N CARD -c COLUMN`, `oh project card remove N CARD` | Cards: REF is `12` or `#12` here, or `name#12` in another of the owner's repositories; a column by name or id |

- Also still to come: reviews, project columns as commands, runner management (oxygenhub#41), and shell completions.

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`, `/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 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; `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, `/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.