An assistant drafts a new repository's starting files; your Flow runs over the API; 0.9.13 (closes #347, refs andymccall/oxygenhub-android#26) 3d086bc3d69b

//! A new repository's starting files, drafted by an assistant (#347): the

//! person creating it describes what they want, an assistant set up for the

//! owner (the site's, or the organisation's) answers with files, and the

//! hub commits them to the empty repository's default bookmark, authored by

//! that person and signed by the hub as their delegate, as a web edit is.

//! The change says which assistant drafted it and what was asked. It runs

//! in the background, since a model may take longer than a proxied request

//! may last; its state is kept here until the hub restarts.

use crate::assistants::{self, Assistant, Available, Scope};

use crate::db::{self, Pool};

use crate::repos::RepoName;

use crate::Shared;

use oxy_core::repo::FileEdit;

use std::collections::HashMap;

use std::path::PathBuf;

use std::sync::{LazyLock, Mutex};

/// The most a description may say.

pub const MAX_DESCRIPTION: usize = 4000;

/// The most files a starter may have, the largest one and all of them.

pub const MAX_FILES: usize = 40;

pub const MAX_FILE: usize = 64 * 1024;

pub const MAX_TOTAL: usize = 256 * 1024;

/// The assistants a new repository under `owner` may ask: the site's, and

/// the organisation's when `owner` is one, as its repositories would see.

pub async fn assistants_for(pool: &Pool, owner: &str) -> sqlx::Result<Vec<Available>> {

    let scope = match db::accounts::org_by_name(pool, owner).await? {

        Some(org) => Scope::Org(org.id),

        None => Scope::Site,

    };

    Ok(assistants::available(pool, scope, owner).await?.into_iter().filter(Available::on).collect())

}

/// Where a repository's starter stands.

#[derive(Clone, Debug, PartialEq, Eq)]

pub enum State {

    Running { assistant: String },

    Done { assistant: String, change: String, files: Vec<String> },

    Failed { assistant: String, error: String },

}

static STATES: LazyLock<Mutex<HashMap<PathBuf, State>>> = LazyLock::new(|| Mutex::new(HashMap::new()));

fn key(app: &Shared, name: &RepoName) -> PathBuf {

    app.repos.dir(name)

}

/// The starter of `name` on this hub, if one was asked for since it started.

pub fn state(app: &Shared, name: &RepoName) -> Option<State> {

    STATES.lock().unwrap_or_else(|p| p.into_inner()).get(&key(app, name)).cloned()

}

fn set(app: &Shared, name: &RepoName, s: State) {

    STATES.lock().unwrap_or_else(|p| p.into_inner()).insert(key(app, name), s);

}

/// What the assistant is told: what to write and the one shape to answer in.

pub fn system_prompt(a: &Assistant, site: &str, owner_prompts: &str) -> String {

    let mut s = format!(

        "You are {name}, an AI assistant writing the first files of a new repository on {site}, an OxygenHub site, \

         for the person who just created it; they read, change and own everything you write. \

         Make a small, working starting point for what they describe: a README.md saying what it is and how to build, \

         run and test it; the build files the language's own tools expect; a minimal source layout; and a first test \

         where the ecosystem has a convention. No secrets, no placeholder credentials, no binary files, nothing \

         generated (lock files, build output). At most {MAX_FILES} files.\n\n\

         Answer with files only, each written as\n\n\

         <<<FILE path/from/the/repository/root>>>\n\

         the file's whole content\n\

         <<<END>>>\n\n\

         with nothing before the first file and nothing after the last.",

        name = a.name

    );

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

        s.push_str("\n\n");

        s.push_str(owner_prompts.trim());

    }

    s

}

/// The files an answer holds, checked: relative paths without `..`, text,

/// within the limits. `Err` says what was wrong, for the person who asked.

pub fn parse_files(answer: &str) -> Result<Vec<(String, String)>, String> {

    let mut files: Vec<(String, String)> = vec![];

    let mut current: Option<(String, Vec<&str>)> = None;

    for line in answer.lines() {

        let t = line.trim_end();

        if let Some((path, body)) = current.as_mut() {

            if t.trim() == "<<<END>>>" {

                let path = std::mem::take(path);

                let content = body.join("\n") + "\n";

                current = None;

                files.push((path, content));

            } else {

                body.push(line);

            }

            continue;

        }

        if let Some(rest) = t.trim().strip_prefix("<<<FILE ") {

            let path = rest.strip_suffix(">>>").ok_or_else(|| format!("a file line is not closed with >>>: {t:?}"))?.trim();

            current = Some((path.to_string(), vec![]));

        }

    }

    if let Some((path, _)) = current {

        return Err(format!("the answer stopped inside {path:?} (no <<<END>>>)"));

    }

    if files.is_empty() {

        return Err("the assistant answered without any files".into());

    }

    if files.len() > MAX_FILES {

        return Err(format!("the assistant wrote {} files; a starter has at most {MAX_FILES}", files.len()));

    }

    let mut total = 0;

    let mut seen = std::collections::BTreeSet::new();

    for (path, content) in &files {

        check_path(path)?;

        if !seen.insert(path.clone()) {

            return Err(format!("the assistant wrote {path} twice"));

        }

        if content.len() > MAX_FILE {

            return Err(format!("{path} is {} bytes; a starter's files are at most {MAX_FILE}", content.len()));

        }

        if content.contains('\0') {

            return Err(format!("{path} is not text"));

        }

        total += content.len();

    }

    if total > MAX_TOTAL {

        return Err(format!("the starter is {total} bytes; at most {MAX_TOTAL}"));

    }

    Ok(files)

}

fn check_path(path: &str) -> Result<(), String> {

    let bad = |why: &str| Err(format!("the path {path:?} {why}"));

    if path.is_empty() || path.len() > 200 {

        return bad("is empty or longer than 200 characters");

    }

    if path.starts_with('/') || path.contains('\\') || path.contains(':') {

        return bad("is not relative to the repository's root");

    }

    for part in path.split('/') {

        if part.is_empty() || part == "." || part == ".." {

            return bad("has an empty, . or .. part");

        }

        if part.eq_ignore_ascii_case(".oxy") {

            return bad("is inside the repository's own metadata");

        }

        if part.chars().any(char::is_control) {

            return bad("has a control character");

        }

    }

    Ok(())

}

/// Whether `name`'s default bookmark holds nothing yet.

pub async fn is_empty(app: &Shared, name: &RepoName, bookmark: &str) -> Result<bool, String> {

    let b = bookmark.to_string();

    app.repos

        .read(name, move |r, _| {

            let view = r.view()?;

            Ok(match view.bookmarks.get(&b) {

                None => true,

                Some(st) => r.store().get_state(st)?.heads.is_empty(),

            })

        })

        .await

        .map_err(|e| e.to_string())

}

/// Ask `a` for `row`'s starting files in the background, for `by`, and

/// commit them; [`state`] follows it.

pub fn start(app: Shared, row: db::repos::RepoRow, by: db::accounts::Account, a: Assistant, description: String) {

    let Some(name) = RepoName::new(&row.owner, &row.name) else { return };

    set(&app, &name, State::Running { assistant: a.name.clone() });

    tokio::spawn(async move {

        let outcome = run(&app, &row, &by, &a, &description).await;

        let s = match outcome {

            Ok((change, files)) => State::Done { assistant: a.name.clone(), change, files },

            Err(error) => {

                tracing::warn!("starter for {}/{}: {error}", row.owner, row.name);

                State::Failed { assistant: a.name.clone(), error }

            }

        };

        set(&app, &name, s);

    });

}

async fn run(

    app: &Shared,

    row: &db::repos::RepoRow,

    by: &db::accounts::Account,

    a: &Assistant,

    description: &str,

) -> Result<(String, Vec<String>), String> {

    let name = RepoName::new(&row.owner, &row.name).ok_or("bad repository name")?;

    let signer = crate::web::edit::signer_for(app, by.id).await?;

    let scope = match db::accounts::org_by_name(&app.db, &row.owner).await.map_err(|e| e.to_string())? {

        Some(org) => Scope::Org(org.id),

        None => Scope::Site,

    };

    let mut prompts = assistants::inherited_prompts(&app.db, scope, &row.owner).await.map_err(|e| e.to_string())?;

    let own = assistants::prompt(&app.db, scope).await.map_err(|e| e.to_string())?;

    if !own.is_empty() && scope != Scope::Site {

        prompts.push((format!("the {} organisation", row.owner), own));

    } else if !own.is_empty() {

        prompts.push(("the site".to_string(), own));

    }

    let prompts: String =

        prompts.into_iter().map(|(from, text)| format!("## Instructions from {from}\n\n{text}\n")).collect::<Vec<_>>().join("\n");

    let site = app.config.base_url();

    let user = format!("The repository is {}/{}.\n\nWhat they want:\n\n{}", row.owner, row.name, description.trim());

    let answer = assistants::ask(app, a, &system_prompt(a, site, &prompts), &user, assistants::BACKGROUND_TIMEOUT).await?;

    let files = parse_files(&answer)?;

    if !is_empty(app, &name, &row.default_bookmark).await? {

        return Err("the repository has files now, so the starter was not added".into());

    }

    let paths: Vec<String> = files.iter().map(|(p, _)| p.clone()).collect();

    let edits: Vec<FileEdit> = files.into_iter().map(|(path, content)| FileEdit { path, content: Some(content.into_bytes()) }).collect();

    let short: String = description.trim().chars().take(400).collect();

    let message = format!("Starter files drafted by {} ({})\n\nAsked for by {}: {short}", a.name, a.model, by.username);

    let b = row.default_bookmark.clone();

    let done = crate::repos::edits::commit(&app.repos, &name, b.clone(), b, edits, message, signer).await.map_err(|e| e.to_string())?;

    db::accounts::audit(&app.db, Some(by), "repo.starter", &name.to_string(), &format!("{} files drafted by {}", paths.len(), a.name))

        .await

        .ok();

    Ok((done.change.to_hex(), paths))

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn an_answer_is_read_as_files_and_checked() {

        let answer = "<<<FILE README.md>>>\n# Hello\n<<<END>>>\n<<<FILE src/main.rs>>>\nfn main() {}\n<<<END>>>\n";

        let files = parse_files(answer).unwrap();

        assert_eq!(

            files,

            vec![("README.md".to_string(), "# Hello\n".to_string()), ("src/main.rs".to_string(), "fn main() {}\n".to_string())]

        );

        assert!(parse_files("Sure! Here you go.").unwrap_err().contains("without any files"));

        assert!(parse_files("<<<FILE a>>>\nx").unwrap_err().contains("no <<<END>>>"));

        for bad in ["/etc/passwd", "../up", "a//b", "C:\\x", ".oxy/config"] {

            assert!(parse_files(&format!("<<<FILE {bad}>>>\nx\n<<<END>>>")).is_err(), "{bad}");

        }

        assert!(parse_files("<<<FILE a>>>\n1\n<<<END>>>\n<<<FILE a>>>\n2\n<<<END>>>").unwrap_err().contains("twice"));

        let many: String = (0..=MAX_FILES).map(|i| format!("<<<FILE f{i}>>>\nx\n<<<END>>>\n")).collect();

        assert!(parse_files(&many).unwrap_err().contains("at most"));

        let big = format!("<<<FILE big>>>\n{}\n<<<END>>>", "x".repeat(MAX_FILE + 1));

        assert!(parse_files(&big).unwrap_err().contains("at most"));

    }

}

//! A new repository's starting files drafted by an assistant (#347): asked

//! for over the API, drafted in the background by the owner's assistant,

//! committed to the empty repository as the person who asked (the hub as

//! their delegate), never over files that are there, and refused plainly

//! when no assistant is set up or the person has not delegated to the hub.

use axum::body::Body;

use axum::http::{header, Request, StatusCode};

use http_body_util::BodyExt;

use oxy_core::repo::{IdentityScope, Repo};

use oxygenhub::config::Config;

use oxygenhub::db;

use oxygenhub::Shared;

use std::path::Path;

use tower::ServiceExt;

fn hermetic() {

    static ONCE: std::sync::Once = std::sync::Once::new();

    static DIR: std::sync::OnceLock<tempfile::TempDir> = std::sync::OnceLock::new();

    ONCE.call_once(|| {

        let d = tempfile::tempdir().unwrap();

        std::env::set_var("OXY_HOME", d.path());

        DIR.set(d).ok();

    });

}

struct Hub {

    app: Shared,

    _dir: tempfile::TempDir,

}

async fn hub() -> Hub {

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let mut config = Config::load(dir.path()).unwrap();

    config.registration.setup_code = "test-setup".into();

    config.registration.mode = "open".into();

    // The stand-in model is on this machine.

    config.outbound.allow = vec!["http://127.0.0.1".into()];

    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();

    let port = listener.local_addr().unwrap().port();

    config.server.base_url = format!("http://127.0.0.1:{port}");

    let app = oxygenhub::build(config).await.unwrap();

    let router = oxygenhub::router(app.clone());

    tokio::spawn(async move { axum::serve(listener, router).await.unwrap() });

    Hub { app, _dir: dir }

}

struct Res {

    status: StatusCode,

    body: String,

    cookie: Option<String>,

}

async fn send(app: &Shared, method: &str, path: &str, cookie: Option<&str>, token: Option<&str>, body: Option<(&str, String)>) -> Res {

    let mut req = Request::builder().method(method).uri(path);

    if let Some(c) = cookie {

        req = req.header(header::COOKIE, format!("oxyhub={c}"));

    }

    if let Some(t) = token {

        req = req.header(header::AUTHORIZATION, format!("Bearer {t}"));

    }

    let body = match body {

        Some((ct, b)) => {

            req = req.header(header::CONTENT_TYPE, ct);

            Body::from(b)

        }

        None => Body::empty(),

    };

    let res = oxygenhub::router(app.clone()).oneshot(req.body(body).unwrap()).await.unwrap();

    let status = res.status();

    let cookie = res

        .headers()

        .get(header::SET_COOKIE)

        .and_then(|v| v.to_str().ok())

        .and_then(|v| v.split(';').next())

        .and_then(|kv| kv.split_once('='))

        .map(|(_, v)| v.to_string());

    let bytes = res.into_body().collect().await.unwrap().to_bytes();

    Res { status, body: String::from_utf8_lossy(&bytes).into_owned(), cookie }

}

async fn post(app: &Shared, path: &str, cookie: Option<&str>, form: &str) -> Res {

    send(app, "POST", path, cookie, None, Some(("application/x-www-form-urlencoded", form.to_string()))).await

}

async fn api(app: &Shared, method: &str, path: &str, token: Option<&str>, json: Option<serde_json::Value>) -> Res {

    send(app, method, &format!("/api/v1{path}"), None, token, json.map(|j| ("application/json", j.to_string()))).await

}

async fn register(app: &Shared, user: &str) -> String {

    let r = post(

        app,

        "/register",

        None,

        &format!("username={user}&email={user}%40example.com&password=correct-horse-battery&setup=test-setup"),

    )

    .await;

    assert_eq!(r.status, StatusCode::SEE_OTHER, "{}", r.body);

    r.cookie.unwrap()

}

/// `user`'s identity, delegating to the hub's key and linked to the

/// account, as web edits need; the client checkout that holds it.

async fn delegate(app: &Shared, user: &str, work: &Path) -> Repo {

    let id = db::accounts::account_by_name(&app.db, user).await.unwrap().unwrap().id;

    let mut client = Repo::init(work).unwrap();

    client.create_identity(user, &format!("{user}@example.com"), IdentityScope::Repo).unwrap();

    client.delegate_add(app.hub_key.identity.clone(), oxy_core::identity::Scope::CHANGES | oxy_core::identity::Scope::REFS, None).unwrap();

    let key = client.config.author_key.unwrap();

    let ident = client.identity(&key).unwrap();

    db::accounts::link_identity(&app.db, id, &key.to_hex(), &ident.name, &ident.email, &ident.encode()).await.unwrap();

    client

}

/// A stand-in model: files for any request, but no files when asked to make-no-files.

async fn model() -> String {

    let router = axum::Router::new().route(

        "/v1/chat/completions",

        axum::routing::post(|axum::Json(req): axum::Json<serde_json::Value>| async move {

            let asked = req.to_string();

            let content = if asked.contains("make-no-files") {

                "Sure! I can help with that.".to_string()

            } else {

                "<<<FILE README.md>>>\n# Pong\n\nA small pong game.\n<<<END>>>\n<<<FILE src/main.rs>>>\nfn main() {}\n<<<END>>>\n"

                    .to_string()

            };

            axum::Json(serde_json::json!({ "choices": [{ "message": { "content": content } }] }))

        }),

    );

    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();

    let port = listener.local_addr().unwrap().port();

    tokio::spawn(async move { axum::serve(listener, router).await.unwrap() });

    format!("http://127.0.0.1:{port}/v1/chat/completions")

}

async fn admin_token(app: &Shared, user: &str) -> String {

    let me = db::accounts::account_by_name(&app.db, user).await.unwrap().unwrap();

    let (secret, hash) = oxygenhub::auth::new_token();

    db::accounts::create_token(&app.db, me.id, "phone", &hash, "repo:read,repo:write,repo:admin", "", None).await.unwrap();

    secret

}

async fn wait_done(app: &Shared, repo: &str, token: &str) -> serde_json::Value {

    for _ in 0..100 {

        let r = api(app, "GET", &format!("/repos/{repo}/starter"), Some(token), None).await;

        let v: serde_json::Value = serde_json::from_str(&r.body).unwrap();

        if v["status"] != "running" {

            return v;

        }

        tokio::time::sleep(std::time::Duration::from_millis(100)).await;

    }

    panic!("the starter for {repo} is still running");

}

#[tokio::test(flavor = "multi_thread")]

async fn an_assistant_drafts_an_empty_repositorys_starting_files() {

    let h = hub().await;

    let app = &h.app;

    register(app, "andy").await;

    let work = tempfile::tempdir().unwrap();

    delegate(app, "andy", work.path()).await;

    let t = admin_token(app, "andy").await;

    let r = api(app, "POST", "/repos", Some(&t), Some(serde_json::json!({ "owner": "andy", "name": "pong" }))).await;

    assert_eq!(r.status, StatusCode::CREATED, "{}", r.body);

    // No assistant yet: none offered, and asking says where to set one up.

    let r = api(app, "GET", "/user/starter?owner=andy", Some(&t), None).await;

    assert_eq!(r.body, r#"{"assistants":[]}"#);

    let ask = serde_json::json!({ "description": "A pong game in Rust" });

    let r = api(app, "POST", "/repos/andy/pong/starter", Some(&t), Some(ask.clone())).await;

    assert_eq!(r.status, StatusCode::UNPROCESSABLE_ENTITY, "{}", r.body);

    assert!(r.body.contains("no assistant is set up"), "{}", r.body);

    // The site's assistant.

    let ep = model().await;

    let body = serde_json::json!({ "name": "Helper", "endpoint": ep, "api": "chat-completions", "model": "m1" });

    let r = api(app, "POST", "/admin/assistants", Some(&t), Some(body)).await;

    assert_eq!(r.status, StatusCode::OK, "{}", r.body);

    let r = api(app, "GET", "/user/starter?owner=andy", Some(&t), None).await;

    let v: serde_json::Value = serde_json::from_str(&r.body).unwrap();

    assert_eq!((v["assistants"][0]["name"].as_str(), v["assistants"][0]["from"].as_str()), (Some("Helper"), Some("the site")), "{v}");

    // Asked: it works in the background, then the files are the repository's first change.

    let r = api(app, "POST", "/repos/andy/pong/starter", Some(&t), Some(ask.clone())).await;

    assert_eq!(r.status, StatusCode::ACCEPTED, "{}", r.body);

    let v = wait_done(app, "andy/pong", &t).await;

    assert_eq!(v["status"], "done", "{v}");

    assert_eq!(v["files"], serde_json::json!(["README.md", "src/main.rs"]));

    assert_eq!(v["assistant"], "Helper");

    let r = api(app, "GET", "/repos/andy/pong/file/main/README.md", Some(&t), None).await;

    assert!(r.body.contains("A small pong game."), "{}", r.body);

    let r = api(app, "GET", "/repos/andy/pong/history/main", Some(&t), None).await;

    assert!(r.body.contains("Starter files drafted by Helper (m1)") && r.body.contains("A pong game in Rust"), "{}", r.body);

    // Never over files that are there, and the request must say something.

    let r = api(app, "POST", "/repos/andy/pong/starter", Some(&t), Some(ask)).await;

    assert_eq!(r.status, StatusCode::CONFLICT, "{}", r.body);

    api(app, "POST", "/repos", Some(&t), Some(serde_json::json!({ "owner": "andy", "name": "empty" }))).await;

    let r = api(app, "POST", "/repos/andy/empty/starter", Some(&t), Some(serde_json::json!({ "description": "  " }))).await;

    assert_eq!(r.status, StatusCode::UNPROCESSABLE_ENTITY, "{}", r.body);

    // An answer with no files fails, saying so, and the repository stays empty.

    let r =

        api(app, "POST", "/repos/andy/empty/starter", Some(&t), Some(serde_json::json!({ "description": "make-no-files please" }))).await;

    assert_eq!(r.status, StatusCode::ACCEPTED, "{}", r.body);

    let v = wait_done(app, "andy/empty", &t).await;

    assert_eq!(v["status"], "failed", "{v}");

    assert!(v["error"].as_str().unwrap().contains("without any files"), "{v}");

    assert_eq!(api(app, "GET", "/repos/andy/empty/starter", None, None).await.status, StatusCode::OK, "readable as the repository is");

    // Someone who has not delegated to the hub is told how.

    register(app, "bob").await;

    let b = admin_token(app, "bob").await;

    assert_eq!(

        api(app, "GET", "/user/starter?owner=andy", Some(&b), None).await.body,

        r#"{"assistants":[]}"#,

        "not an owner bob creates under"

    );

    api(app, "POST", "/repos", Some(&b), Some(serde_json::json!({ "owner": "bob", "name": "game" }))).await;

    let r = api(app, "POST", "/repos/bob/game/starter", Some(&b), Some(serde_json::json!({ "description": "A game" }))).await;

    assert_eq!(r.status, StatusCode::UNPROCESSABLE_ENTITY, "{}", r.body);

    assert!(r.body.contains("delegated"), "{}", r.body);

}

## 0.9.13 (2026-10-28)

- **An assistant drafts a new repository's starting files (#347).** Creating a repository can come with a description of what it is for: `POST /api/v1/repos/OWNER/NAME/starter {"description"}` asks the owner's assistant (the site's, or the organisation's) for a small working starting point (a README, the build files, a source layout and a first test), checks what comes back (relative paths, text, at most 40 files and 256 KiB), and commits it to the empty repository's default bookmark as the person who asked, signed by the hub as their delegate, the change naming the assistant and what was asked. It runs in the background, since a model may take longer than a proxied request may last; `GET …/starter` says how it went, and `GET /api/v1/user/starter?owner=X` which assistants may be asked. Never over files that are there. The Android app's New repository uses it.

- **Your Flow runs over the API (oxygenhub-android#26).** `GET /api/v1/user/flow/runs` gives the newest runs of the repositories you belong to, each with its repository and jobs (`?before=MS` pages back), for the Android app's Flow monitor.

version = "0.9.13"

version = "0.9.13"

version = "0.9.13"

version = "0.9.13"

/// `GET /user/flow/runs` (oxygenhub-android#26): a run of one of the

/// caller's repositories, with its jobs, for a monitor across them all.

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

pub struct UserFlowRun {

    /// `owner/name`.

    pub repository: String,

    #[serde(flatten)]

    pub run: FlowRun,

}

/// `GET /user/flow/runs` query: `before` (created before, ms) pages back.

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

pub struct UserFlowRunsQuery {

    #[serde(default)]

    pub limit: Option<i64>,

    #[serde(default)]

    pub before: Option<i64>,

}

/// `GET /user/starter?owner=X` (#347): the assistants a new repository

/// under `owner` may ask for its starting files; empty when none is set up

/// or the caller cannot create there.

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

pub struct StarterAssistants {

    pub assistants: Vec<StarterAssistant>,

}

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

pub struct StarterAssistant {

    pub name: String,

    pub model: String,

    /// `the site` or `the acme organisation`.

    pub from: String,

}

/// `POST /repos/{owner}/{name}/starter`: what to make, and which assistant

/// (the first available when not given).

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

pub struct StarterRequest {

    pub description: String,

    #[serde(default)]

    pub assistant: Option<String>,

}

/// Where a repository's starter stands: `running`, `done` (with the

/// change and its files), `failed` (with why), or `none`.

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

pub struct StarterStatus {

    pub status: String,

    #[serde(default, skip_serializing_if = "String::is_empty")]

    pub assistant: String,

    #[serde(default, skip_serializing_if = "String::is_empty")]

    pub change: String,

    #[serde(default, skip_serializing_if = "Vec::is_empty")]

    pub files: Vec<String>,

    #[serde(default, skip_serializing_if = "String::is_empty")]

    pub error: String,

}

        .route("/user/starter", get(user_starter))

        .route("/user/flow/runs", get(user_flow_runs))

        .route("/repos/{owner}/{name}/starter", get(starter_status).post(start_starter))

/// `GET /user/flow/runs` (oxygenhub-android#26): the newest runs of the

/// repositories the caller belongs to and may read, each with its jobs,

/// newest first; `before` pages back by creation time.

async fn user_flow_runs(

    State(app): State<Shared>,

    headers: HeaderMap,

    Query(q): Query<hub_api::UserFlowRunsQuery>,

) -> Result<Json<Vec<hub_api::UserFlowRun>>, ApiError> {

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

    let me = c.require("repo:read")?.clone();

    let member = db::accounts::visible_repo_ids(&app.db, me.id).await?;

    let mut mine = std::collections::HashMap::new();

    for r in db::repos::list(&app.db).await? {

        if member.contains(&r.id) && auth::roles::allows(auth::roles::role_for(&app.db, Some(&me), &r).await?, Access::Read) {

            mine.insert(r.id, r);

        }

    }

    let ids: Vec<i64> = mine.keys().copied().collect();

    let limit = q.limit.unwrap_or(30).clamp(1, 100);

    let runs = db::activity::recent_runs(&app.db, &ids, q.before.unwrap_or(i64::MAX), limit).await?;

    let queue = if runs.iter().any(|r| r.live()) { db::flow::queue(&app.db).await? } else { vec![] };

    let mut out = Vec::with_capacity(runs.len());

    for run in &runs {

        let Some(row) = mine.get(&run.repo_id) else { continue };

        let jobs = db::flow::jobs(&app.db, run.id).await?;

        out.push(hub_api::UserFlowRun {

            repository: format!("{}/{}", row.owner, row.name),

            run: flow_run_of(&app, row, run, jobs, &queue),

        });

    }

    Ok(Json(out))

}

#[derive(Deserialize)]

struct StarterQuery {

    owner: String,

}

/// `GET /user/starter?owner=X` (#347): the assistants a new repository

/// under `owner` may ask for its starting files, when the caller may

/// create repositories there.

async fn user_starter(

    State(app): State<Shared>,

    headers: HeaderMap,

    Query(q): Query<StarterQuery>,

) -> Result<Json<hub_api::StarterAssistants>, ApiError> {

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

    let me = c.require("repo:read")?;

    if !auth::roles::may_create_under(&app.db, me, q.owner.trim()).await? {

        return Ok(Json(hub_api::StarterAssistants { assistants: vec![] }));

    }

    let found = crate::starter::assistants_for(&app.db, q.owner.trim()).await?;

    Ok(Json(hub_api::StarterAssistants {

        assistants: found

            .into_iter()

            .map(|a| hub_api::StarterAssistant {

                name: a.assistant.name,

                model: a.assistant.model,

                from: if a.from.is_empty() { "the site".into() } else { a.from },

            })

            .collect(),

    }))

}

fn starter_status_of(s: Option<crate::starter::State>) -> hub_api::StarterStatus {

    use crate::starter::State;

    let mut out = hub_api::StarterStatus {

        status: "none".into(),

        assistant: String::new(),

        change: String::new(),

        files: vec![],

        error: String::new(),

    };

    match s {

        None => {}

        Some(State::Running { assistant }) => (out.status, out.assistant) = ("running".into(), assistant),

        Some(State::Done { assistant, change, files }) => {

            (out.status, out.assistant, out.change, out.files) = ("done".into(), assistant, change, files)

        }

        Some(State::Failed { assistant, error }) => (out.status, out.assistant, out.error) = ("failed".into(), assistant, error),

    }

    out

}

/// `GET /repos/{owner}/{name}/starter` (#347): where its starter stands.

async fn starter_status(

    State(app): State<Shared>,

    headers: HeaderMap,

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

) -> Result<Json<hub_api::StarterStatus>, ApiError> {

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

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

    Ok(Json(starter_status_of(crate::starter::state(&app, &repo))))

}

/// `POST /repos/{owner}/{name}/starter` (#347): ask an assistant for an

/// empty repository's starting files; `202` while it works, then

/// `GET …/starter` says how it went.

async fn start_starter(

    State(app): State<Shared>,

    headers: HeaderMap,

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

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

) -> Result<(StatusCode, Json<hub_api::StarterStatus>), ApiError> {

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

    let me = c.require("repo:admin")?.clone();

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

    let description = body.description.trim();

    if description.is_empty() {

        return Err(ApiError(StatusCode::UNPROCESSABLE_ENTITY, "say what the repository is for (description)".into()));

    }

    if description.chars().count() > crate::starter::MAX_DESCRIPTION {

        return Err(ApiError(

            StatusCode::UNPROCESSABLE_ENTITY,

            format!("a description is at most {} characters", crate::starter::MAX_DESCRIPTION),

        ));

    }

    if matches!(crate::starter::state(&app, &repo), Some(crate::starter::State::Running { .. })) {

        return Err(ApiError(StatusCode::CONFLICT, "a starter is being drafted for it already".into()));

    }

    if !crate::starter::is_empty(&app, &repo, &row.default_bookmark).await.map_err(|e| ApiError(StatusCode::INTERNAL_SERVER_ERROR, e))? {

        return Err(ApiError(StatusCode::CONFLICT, "the repository has files already; a starter is only for an empty one".into()));

    }

    let available = crate::starter::assistants_for(&app.db, &row.owner).await?;

    let chosen = match body.assistant.as_deref().map(str::trim).filter(|n| !n.is_empty()) {

        Some(n) => available.into_iter().find(|a| a.assistant.name.eq_ignore_ascii_case(n)),

        None => available.into_iter().next(),

    };

    let Some(a) = chosen else {

        return Err(ApiError(

            StatusCode::UNPROCESSABLE_ENTITY,

            "no assistant is set up for this owner (Admin › Assistants, or the organisation's settings)".into(),

        ));

    };

    if let Err(why) = crate::web::edit::signer_for(&app, me.id).await {

        return Err(ApiError(StatusCode::UNPROCESSABLE_ENTITY, why));

    }

    crate::starter::start(app.clone(), row, me, a.assistant, description.to_string());

    Ok((StatusCode::ACCEPTED, Json(starter_status_of(crate::starter::state(&app, &repo)))))

}

/// The newest Flow runs of `repo_ids`, created before `before_ms`, at most

/// `limit` (oxygenhub-android#26: the app's Flow monitor).

pub async fn recent_runs(pool: &Pool, repo_ids: &[i64], before_ms: i64, limit: i64) -> sqlx::Result<Vec<super::flow::Run>> {

    sqlx::query_as(&each(

        "WITH seen(id) AS (SELECT value FROM json_each($1)) \

         SELECT * FROM flow_runs WHERE repo_id IN (SELECT id FROM seen) AND created_ms < $2 \

         ORDER BY created_ms DESC, id DESC LIMIT $3",

    ))

    .bind(ids_json(repo_ids))

    .bind(before_ms)

    .bind(limit)

    .fetch_all(pool)

    .await

}

pub mod starter;

    // Both, newest first, across andy's repositories with their jobs (oxygenhub-android#26).

    let (st, body) = call(&h.app, "GET", "/api/v1/user/flow/runs", Some("site"), None).await;

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

    let v: serde_json::Value = serde_json::from_str(&body).unwrap();

    assert_eq!(v.as_array().unwrap().len(), 2, "{v}");

    assert_eq!(

        (v[0]["repository"].as_str(), v[0]["number"].as_i64(), v[1]["number"].as_i64()),

        (Some("andy/demo"), Some(2), Some(1)),

        "{v}"

    );

    assert!(!v[0]["jobs"].as_array().unwrap().is_empty(), "with its jobs: {v}");

    let (_, body) = call(&h.app, "GET", &format!("/api/v1/user/flow/runs?before={}", v[0]["created_ms"]), Some("site"), None).await;

    let older: serde_json::Value = serde_json::from_str(&body).unwrap();

    assert!(older.as_array().unwrap().iter().all(|r| r["number"] != 2), "before pages back: {older}");

    assert_eq!(call(&h.app, "GET", "/api/v1/user/flow/runs", None, None).await.0, StatusCode::UNAUTHORIZED);

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