Milestones over the API, and oh milestone 5ea4872f23e8

/// `POST /repos/{o}/{n}/milestones`: create a milestone, or change the

/// description and due date of the one with that title (triage).

pub struct NewMilestone {

    pub title: String,

    #[serde(default)]

    pub description: String,

    /// `YYYY-MM-DD`, UTC; absent for no due date.

    #[serde(default)]

    pub due: Option<String>,

}

/// `PATCH /repos/{o}/{n}/milestones/{title}`: only the fields given change

/// (triage).

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

pub struct MilestoneEdit {

    #[serde(default)]

    pub title: Option<String>,

    #[serde(default)]

    pub description: Option<String>,

    /// `YYYY-MM-DD`; the empty string clears the due date.

    #[serde(default)]

    pub due: Option<String>,

    /// `open` or `closed`.

    #[serde(default)]

    pub state: Option<String>,

}

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

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

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

        .route("/repos/{owner}/{name}/milestones", get(milestones).post(create_milestone))

        .route("/repos/{owner}/{name}/milestones/{title}", axum::routing::patch(edit_milestone))

fn milestone_of(m: db::issues::Milestone, open: i64, closed: i64) -> Milestone {

    Milestone { title: m.title, description: m.description, due_ms: m.due_ms, state: m.state, open, closed }

}

/// A due date as `YYYY-MM-DD` (UTC midnight), or the empty string for none.

fn due_ms_of(due: &str) -> Result<Option<i64>, ApiError> {

    let due = due.trim();

    if due.is_empty() {

        return Ok(None);

    }

    time::Date::parse(due, &time::macros::format_description!("[year]-[month]-[day]"))

        .map(|d| Some(d.midnight().assume_utc().unix_timestamp() * 1000))

        .map_err(|_| ApiError(StatusCode::BAD_REQUEST, format!("due {due:?} is not YYYY-MM-DD")))

}

async fn triage_for_milestones(app: &Shared, headers: &HeaderMap, owner: &str, name: &str) -> Result<db::repos::RepoRow, ApiError> {

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

    c.require("issues:write").or_else(|_| c.require("repo:write"))?;

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

    if role < Role::Triage {

        return Err(forbidden("milestones need triage access"));

    }

    Ok(row)

}

/// `POST /repos/{o}/{n}/milestones` (triage, oxygenhub#91): create a

/// milestone, or change the description and due date of the one with

/// that title.

async fn create_milestone(

    State(app): State<Shared>,

    headers: HeaderMap,

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

    Json(body): Json<NewMilestone>,

) -> Result<(StatusCode, Json<Milestone>), ApiError> {

    let row = triage_for_milestones(&app, &headers, &owner, &name).await?;

    let title = body.title.trim();

    if title.is_empty() || title.len() > 100 {

        return Err(ApiError(StatusCode::BAD_REQUEST, "a milestone has a title of 1 to 100 characters".into()));

    }

    let due_ms = due_ms_of(body.due.as_deref().unwrap_or(""))?;

    let m = db::issues::upsert_milestone(&app.db, row.id, title, body.description.trim(), due_ms).await?;

    let (open, closed) = db::issues::milestone_counts(&app.db, m.id).await?;

    Ok((StatusCode::CREATED, Json(milestone_of(m, open, closed))))

}

/// `PATCH /repos/{o}/{n}/milestones/{title}` (triage): title,

/// description, due date and state; what is not given stays.

async fn edit_milestone(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name, title)): Path<(String, String, String)>,

    Json(body): Json<MilestoneEdit>,

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

    let row = triage_for_milestones(&app, &headers, &owner, &name).await?;

    let m = db::issues::milestones(&app.db, row.id)

        .await?

        .into_iter()

        .find(|m| m.title == title)

        .ok_or_else(|| not_found("no such milestone"))?;

    let new_title = body.title.as_deref().map(str::trim).unwrap_or(&m.title);

    if new_title.is_empty() || new_title.len() > 100 {

        return Err(ApiError(StatusCode::BAD_REQUEST, "a milestone has a title of 1 to 100 characters".into()));

    }

    let due_ms = match body.due.as_deref() {

        Some(d) => due_ms_of(d)?,

        None => m.due_ms,

    };

    let description = body.description.as_deref().map(str::trim).unwrap_or(&m.description);

    if body.title.is_some() || body.description.is_some() || body.due.is_some() {

        db::issues::update_milestone(&app.db, m.id, new_title, description, due_ms).await?;

    }

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

        match state {

            "open" | "closed" => db::issues::set_milestone_state(&app.db, m.id, state).await?,

            other => return Err(ApiError(StatusCode::BAD_REQUEST, format!("state {other:?} is open or closed"))),

        }

    }

    let fresh = db::issues::milestone(&app.db, m.id).await?.ok_or_else(|| not_found("no such milestone"))?;

    let (open, closed) = db::issues::milestone_counts(&app.db, fresh.id).await?;

    Ok(Json(milestone_of(fresh, open, closed)))

}

/// Change a milestone's title, description and due date.

pub async fn update_milestone(pool: &Pool, id: i64, title: &str, description: &str, due_ms: Option<i64>) -> sqlx::Result<()> {

    sqlx::query("UPDATE milestones SET title = ?, description = ?, due_ms = ? WHERE id = ?")

        .bind(title)

        .bind(description)

        .bind(due_ms)

        .bind(id)

        .execute(pool)

        .await?;

    Ok(())

}

    // oxygenhub#91: milestones over the API, for triage.

    let (st, m) = api(

        app,

        "POST",

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

        Some(&andy_t),

        Some(r#"{"title":"v1","description":"First","due":"2027-01-01"}"#),

    )

    .await;

    assert_eq!((st, m["title"].as_str(), m["state"].as_str()), (StatusCode::CREATED, Some("v1"), Some("open")), "{m}");

    assert_eq!(m["due_ms"].as_i64(), Some(1_798_761_600_000));

    assert_eq!(

        api(app, "POST", "/api/v1/repos/andy/demo/milestones", Some(&andy_t), Some(r#"{"title":"v2","due":"soon"}"#)).await.0,

        StatusCode::BAD_REQUEST

    );

    assert_eq!(

        api(app, "POST", "/api/v1/repos/andy/demo/milestones", Some(&bob_t), Some(r#"{"title":"mine"}"#)).await.0,

        StatusCode::FORBIDDEN

    );

    let (st, m) =

        api(app, "PATCH", "/api/v1/repos/andy/demo/milestones/v1", Some(&andy_t), Some(r#"{"title":"v1.0","due":"","state":"closed"}"#))

            .await;

    assert_eq!(

        (st, m["title"].as_str(), m["state"].as_str(), m["due_ms"].is_null()),

        (StatusCode::OK, Some("v1.0"), Some("closed"), true),

        "{m}"

    );

    assert_eq!(m["description"].as_str(), Some("First"), "what is not given stays");

    assert_eq!(

        api(app, "PATCH", "/api/v1/repos/andy/demo/milestones/v1", Some(&andy_t), Some(r#"{"state":"open"}"#)).await.0,

        StatusCode::NOT_FOUND,

        "renamed"

    );

    assert_eq!(

        api(app, "PATCH", "/api/v1/repos/andy/demo/milestones/v1.0", Some(&andy_t), Some(r#"{"state":"done"}"#)).await.0,

        StatusCode::BAD_REQUEST

    );

    let (_, list) = api(app, "GET", "/api/v1/repos/andy/demo/milestones", None, None).await;

    assert_eq!(list.as_array().unwrap().len(), 1);

    /// Milestones: list, create, edit, close

    Milestone {

        #[command(subcommand)]

        cmd: MilestoneCmd,

    },

#[derive(Subcommand)]

enum MilestoneCmd {

    /// The repository's milestones

    List,

    /// Create a milestone, or change the one of that title (triage)

    Create {

        title: String,

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

        description: String,

        /// Due date, YYYY-MM-DD

        #[arg(long)]

        due: Option<String>,

    },

    /// Change a milestone's title, description or due date (triage)

    Edit {

        title: String,

        #[arg(long, short)]

        rename: Option<String>,

        #[arg(long, short)]

        description: Option<String>,

        /// Due date, YYYY-MM-DD ("" for none)

        #[arg(long)]

        due: Option<String>,

    },

    /// Close a milestone

    Close { title: String },

    /// Reopen a milestone

    Reopen { title: String },

}

        Cmd::Milestone { cmd } => milestone(&c, &t, cmd, json),

        }

    }

    Ok(0)

}

fn milestone_line(m: &hub_api::Milestone) -> String {

    let glyph = if m.state == "open" { ui::ok("◆") } else { ui::dim("◇") };

    let due = m.due_ms.map(|d| format!(" · due {}", ui::ago(d))).unwrap_or_default();

    format!("{glyph} {}  {}{}", m.title, ui::dim(&format!("{} open, {} closed", m.open, m.closed)), ui::dim(&due))

}

fn milestone(c: &Client, t: &Target, cmd: MilestoneCmd, json: bool) -> Result<i32> {

    let base = t.repo_path()?;

    let edit = |title: &str, e: hub_api::MilestoneEdit, verb: &str| -> Result<()> {

        let m: hub_api::Milestone = c.send("PATCH", &format!("{base}/milestones/{}", enc(title)), &e)?;

        if json {

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

        } else {

            println!("{} {verb} milestone {}", ui::ok("✔"), m.title);

        }

        Ok(())

    };

    match cmd {

        MilestoneCmd::List => {

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

            if json {

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

                return Ok(0);

            }

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

            if list.is_empty() {

                println!("{}", ui::dim("No milestones."));

            }

            for m in &list {

                println!("{}", milestone_line(m));

            }

        }

        MilestoneCmd::Create { title, description, due } => {

            let m: hub_api::Milestone =

                c.send("POST", &format!("{base}/milestones"), &hub_api::NewMilestone { title, description, due })?;

            if json {

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

            } else {

                println!("{} milestone {}", ui::ok("✔"), m.title);

            }

        }

        MilestoneCmd::Edit { title, rename, description, due } => {

            if rename.is_none() && description.is_none() && due.is_none() {

                bail!("say what to change: --rename, --description or --due");

            }

            edit(&title, hub_api::MilestoneEdit { title: rename, description, due, state: None }, "edited")?;

        }

        MilestoneCmd::Close { title } => {

            edit(&title, hub_api::MilestoneEdit { state: Some("closed".into()), ..Default::default() }, "closed")?;

        }

        MilestoneCmd::Reopen { title } => {

            edit(&title, hub_api::MilestoneEdit { state: Some("open".into()), ..Default::default() }, "reopened")?;

| `oh milestone list`, `oh milestone create TITLE [-d DESC] [--due YYYY-MM-DD]`, `oh milestone edit TITLE [--rename T] [-d DESC] [--due D]`, `oh milestone close\|reopen TITLE` | Milestones (triage to change) |

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, 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 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 (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.

**Design notes (2026-10-04), for review before anything is built.**

- *Data.* A `workspaces` table: id, account, repository, state (ObjectRef), bookmark (nullable), workspace bookmark name (`ws/{account}/{id}`), status (`queued`, `starting`, `open`, `stopping`, `stopped`, `failed`), runner, job id, secret hash, created, last connection, stopped, and why. A workspace is a row plus one Flow job of kind `workspace`; the job's log is the editor's server log. `GET /api/v1/user/workspaces` lists the caller's; `POST /repos/{o}/{n}/workspaces {"state"|"bookmark"}` opens one; `DELETE /workspaces/{id}` stops it. Limits are per account: three open at once (configurable), and a site cap.

- *Runner side.* The runner gains a job kind beside pipeline jobs: it boots the pinned workspace rootfs (openvscode-server, `oxy`, the Oxygen VCS extension, a non-root user), mounts the state at `/workspace` through flow-casfs with a writable overlay, runs `oxy` in the microVM against a repository that fetches history lazily over the wire protocol with the job's read-only token, and opens a tunnel back to the hub (the same outbound connection the runner uses for claims) carrying the editor's HTTP and WebSocket traffic. The runner marks the job running when the editor answers on its port, and reports a heartbeat (connections open, last activity) every 30 s in place of log batches; the hub stops the workspace when the heartbeat shows no connection for the idle limit.

- *Hub side.* `/{owner}/{name}/workspace/{id}/` is a reverse proxy to that tunnel, for the owner's session only, with the workspace secret in a header the runner checks; CSRF does not apply (the editor is same-origin under the hub, and the proxy forwards only to the workspace the path names). Commits: the extension's `oxy commit` writes to the microVM's repository; `oxy push` goes to the workspace bookmark with the job token, and the hub signs the pushed changes as the account's delegate (web edits' path) if the account has delegated to the hub key with `changes,refs`; otherwise the push is refused with the recipe. The bookmark is ordinary afterwards: propose, land, or delete.

- *Security.* The microVM has no credentials but the job token (read this repository, push this workspace bookmark) and the workspace secret; the account's keys never enter it. Network egress from the microVM is off by default (as for pipeline jobs); a site setting may allow it for package installs, with the audit log recording the choice. The overlay is ephemeral and the rootfs is pinned by hash, so a workspace cannot be left altered.

- *Costs.* One microVM per open workspace: 2 vCPU and 4 GB by default, from the runner's capacity like any job, so open workspaces compete with pipeline jobs; a runner label `workspace` keeps them on runners meant for it. Idle stop at 30 minutes keeps the fleet small.

- *Open questions.* Whether the Oxygen VCS extension should talk to the microVM's `oxy` (simplest; works offline in the VM) or to the hub's API (no `oxy` in the VM, but a second code path for every operation): the first. Whether a stopped workspace's overlay should be kept for a day so an unpushed edit is not lost: probably yes, as a tarball artifact of the job, restored on reopen. Whether to allow terminals: yes, it is the point.