Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ Reading public data needs no credentials. Anything else acts as whoever ran `sou

### JSON output and exit codes

Every command that reports information takes `--json`, such as `auth status`. Under `--json`, stdout holds one JSON document and nothing else, with the API's field names and RFC 3339 times; notes and progress go to stderr. Fields may be added over time, but not renamed or removed.
Every command that reports information takes `--json`: `auth status`, and `product list`, `view`, `create`, `edit` and `delete` (which print the resulting record). Under `--json`, stdout holds one JSON document and nothing else, with the API's field names and RFC 3339 times; notes and progress go to stderr. Fields may be added over time, but not renamed or removed.

A failure under `--json` is JSON too, on stderr, in the API's error shape. `field_errors` names what to fix when the API rejected the input:

Expand All @@ -279,6 +279,46 @@ Exit codes are the same for every command:

`creds` (`--format`), `auth token` (a bare token) and `api` (the API's response) already print output for machines, so they don't take `--json`. Neither does `auth login`, which signs in through the browser: `auth status --json` reports the result.

## Managing products

`source-coop product` lists, views, creates, edits and deletes products through the source.coop API (`/api/v1`), with the same rules as the web UI: the CLI checks nothing itself and shows the API's errors, field by field.

```bash
source-coop product list # public products
source-coop product list my-org --json # one account's products, as JSON
source-coop product list --format table # one row per product; tab-separated when piped
source-coop product list my-org -i # move through the products and act on them (keys below)
source-coop product view my-org/my-product # --web opens it in the browser
source-coop product view my-org/my-product -i # the product with shortcuts; without a product, pick one
source-coop product create my-org/my-product # prompts for the rest
source-coop product edit my-org/my-product --visibility unlisted
source-coop product edit -i # pick one of your account's products to edit
source-coop product delete my-org/my-product # asks you to type the name back
source-coop product delete -i # pick one of your account's products to delete
```

With `-i`, lists and products answer to keys:

| Key | In a list | On a product |
|-----|-----------|--------------|
| ↑ ↓ (`k` `j`), PgUp PgDn, Home End | move | |
| → Enter (`l`) | open the product | |
| ← Esc (`h` `q`) | quit (from search results: back to the whole list) | back to the list |
| `/` | filter by typed text (Esc clears it); among all public products, Enter searches them on the server | |
| `b` | open in the browser | open in the browser |
| `e` | | edit |
| `d` | | delete |

Editing or deleting takes opening the product first, so a stray key on a long list changes nothing. Edit and delete run exactly as `product edit` and `product delete` do, prompts included. Lists load more as you scroll, and `-i` takes the whole terminal while it runs, putting it back as it was when you leave.

`create` and `edit` take each field as a flag (`--title`, `--description`, `--visibility`, `--data-connection`), from a JSON object with `--from-file PATH` (`-` for stdin), or both, with flags winning. In a terminal, whatever is still missing is asked for, with defaults: a title made from the product ID, the data connections the account can use, and the visibilities the chosen connection allows. A description can be typed on one line, or written in your editor (`$VISUAL` or `$EDITOR`) with Ctrl+E. While `create` asks, ↑ (or ← at the start of a line, or in a list) goes back to the question before, starting from your answer there; once it has asked anything, it shows what it is about to create and asks you to confirm before sending, and ← from there goes back too. `edit` with no flags asks which fields to change and starts each from its current value. When the API rejects a field, you see why and are asked for just that field again. Without a terminal, or with `SOURCE_PROMPT_DISABLED` set, nothing is asked: the request is sent as given, and `delete` needs `--yes`.

To back out of any prompt, press Esc (or `q`) on a choice; on a text prompt that guards something irreversible, like typing a product's name to delete it, press Enter on nothing. The command stops with "Cancelled; nothing was changed."

Before asking anything, `create`, `edit` and `delete` check that you're signed in, so you don't fill in a form only to be refused. If sending your answers fails anyway (a lost connection, an expired login, a server error), they're saved as a draft: run the same command again and you're offered them back, with any flags you pass taking precedence, or pass the saved file with `--from-file`. Drafts live where your OS keeps app state, not its cache: `~/.local/state/source-coop/drafts` on Linux (`$XDG_STATE_HOME`), `~/Library/Application Support/source-coop/drafts` on macOS, and `%LocalAppData%\source-coop\drafts` on Windows. A successful send removes the draft.

Output is for people on a terminal and for scripts when piped: `list` shows each product's fields (`--format table` prints an aligned table with a header on a terminal, and tab-separated rows without one when piped); `create` and `edit` print the product's URL on stdout and their message on stderr, so `url=$(source-coop product create ...)` works.

## Credential storage

The CLI caches the login session (the Ory refresh, ID and access tokens) and the temporary STS credentials for each role, so that `creds` and API commands work without re-authenticating. The refresh token is kept in the session only: it rotates on use, so every role and every API call refreshes through it, one at a time.
Expand Down
87 changes: 75 additions & 12 deletions src/main.rs
Original file line number Diff line number Diff line change
@@ -1,22 +1,15 @@
mod api;
mod api_cmd;
mod cache;
mod draft;
mod failure;
mod oidc;
mod output;
mod session;
mod sts;
// Reusable pieces for the commands built on them (resources such as
// products, and `auth`). Parts are unused until those land; each command PR
// removes the allowances it no longer needs.
#[allow(dead_code)]
mod api;
#[allow(dead_code)]
mod draft;
#[allow(dead_code)]
mod picker;
#[allow(dead_code)]
mod product;
mod prompt;
#[allow(dead_code)]
mod session;
mod sts;
mod style;

use clap::{Parser, Subcommand, ValueEnum};
Expand Down Expand Up @@ -86,6 +79,8 @@ enum Commands {
/// Log in through the browser (now `auth login`; this name still works)
#[command(hide = true)]
Login(LoginArgs),
/// List, view, create, edit and delete products
Product(ProductArgs),
/// Make any request to the source.coop API, signed in as you
Api(ApiCommandArgs),
}
Expand Down Expand Up @@ -226,6 +221,22 @@ struct CredsArgs {
profile: String,
}

/// A command that calls the source.coop API, as whoever ran `login` (see
/// `api_token`).
#[derive(Parser)]
struct ProductArgs {
/// source.coop site URL; the API is served under its `/api/v1`
#[arg(long, global = true, env = "SOURCE_API_URL", default_value = defaults::API_URL)]
api_url: String,

/// S3 proxy URL of the environment whose login session to use
#[arg(long, global = true, env = "SOURCE_PROXY_URL", default_value = defaults::PROXY_URL)]
proxy_url: String,

#[command(subcommand)]
command: product::ProductCommand,
}

#[derive(Clone, ValueEnum)]
enum OutputFormat {
/// AWS credential_process JSON format
Expand Down Expand Up @@ -283,6 +294,24 @@ async fn main() {
fail(e, false);
}
}
Commands::Product(args) => {
let json = args.command.wants_json();
let token = api_token(&args.proxy_url, verbose).await;
let result = match api::Client::new(&args.api_url, token, verbose) {
Ok(client) => {
let mut tty = prompt::tty();
if tty.is_some() {
picker::handle_interrupts();
}
let prompter = tty.as_mut().map(|t| t as &mut dyn prompt::Prompter);
product::run(args.command, &client, &args.api_url, prompter).await
}
Err(e) => Err(e),
};
if let Err(e) = result {
fail(e, json);
}
}
Commands::Api(args) => {
let token = api_token(&args.proxy_url, verbose).await;
let result = async {
Expand Down Expand Up @@ -1343,6 +1372,40 @@ mod tests {

/// AGENTS.md: the README documents the CLI as it is, starting with every
/// command appearing in it as `source-coop <command>`.
/// The conventions in AGENTS.md that can be checked: in every resource
/// (a command with a `list`), each subcommand but `create` takes `-i`, and
/// the reads, `list` and `view`, take `--json`.
#[test]
fn resource_commands_follow_the_cli_conventions() {
fn check(cmd: &clap::Command, resources: &mut usize, problems: &mut Vec<String>) {
if cmd.find_subcommand("list").is_some() {
*resources += 1;
for sub in cmd.get_subcommands().filter(|s| s.get_name() != "help") {
let name = format!("{} {}", cmd.get_name(), sub.get_name());
let has = |short: Option<char>, long: &str| {
sub.get_arguments().any(|a| {
a.get_long() == Some(long)
&& (short.is_none() || a.get_short() == short)
})
};
if sub.get_name() != "create" && !has(Some('i'), "interactive") {
problems.push(format!("{name}: no -i/--interactive"));
}
if ["list", "view"].contains(&sub.get_name()) && !has(None, "json") {
problems.push(format!("{name}: no --json"));
}
}
}
for sub in cmd.get_subcommands() {
check(sub, resources, problems);
}
}
let (mut resources, mut problems) = (0, vec![]);
check(&Cli::command(), &mut resources, &mut problems);
assert!(resources > 0, "found no resource commands to check");
assert!(problems.is_empty(), "{problems:#?}");
}

#[test]
fn every_command_is_in_the_readme() {
let readme = include_str!("../README.md");
Expand Down
Loading
Loading