feat(cli): add pic routes + pic admins subcommands

Closes the audit's Critical "operator can't deploy a serverless endpoint
end-to-end from the CLI" finding. Two new subcommand families bring the
CLI coverage from 14 commands to ~25:

- pic routes {ls, create, rm, check, match}: full route CRUD plus the
  dry-run conflict checker and the URL matcher already exposed by the
  dashboard. The create form accepts --path-kind, --host-kind, and
  --dispatch (sync|async) so async routes can finally be created
  headlessly. The ls output adds a dispatch column.

- pic admins {ls, create, show, set, rm}: per-instance admin user
  management. Create reads passwords from stdin via --password - so
  shell history never sees the cleartext. Set is a JSON-Merge-Patch
  shape that lets operators deactivate accounts or rotate roles
  without touching the dashboard.

Six new ignored integration tests follow the established #[ignore]
pattern (DATABASE_URL gates them). They cover the happy-path round
trip, the async-dispatch persistence path, the password-required
error path, and the capability gate (a Member sees HTTP 403). All
pass against the local dev stack with PICLOUD_DEV_MODE=true +
PICLOUD_DEV_INSECURE_KEY=i-understand-this-is-insecure.

The `pic members` and `pic domains` subcommands the audit mentioned
are deferred — the apps_api shape may shift in v1.2 with per-app
roles and rebuilding the CLI surface twice would be churn.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

crates/picloud-cli/tests/admins.rs

@@ -0,0 +1,140 @@
+//! `pic admins` smoke tests. Verifies the CRUD round trip and the
+//! capability gate (a Member account can't list/create admins).
+
+use predicates::prelude::*;
+
+use crate::common;
+use crate::common::cleanup::UserGuard;
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn create_show_list_patch_remove_round_trip() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let username = common::unique_username("rtadm");
+
+    // Create — password piped via stdin.
+    let out = common::pic_as(&env)
+        .args([
+            "admins",
+            "create",
+            &username,
+            "--password",
+            "-",
+            "--instance-role",
+            "admin",
+            "--email",
+            "admin@example.test",
+        ])
+        .write_stdin("pw-from-stdin\n")
+        .output()
+        .expect("admins create");
+    assert!(out.status.success(), "admins create failed: {out:?}");
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    let id = stdout
+        .lines()
+        .find_map(|l| l.strip_prefix("id"))
+        .map(|s| s.trim().to_string())
+        .expect("id field in admins create output");
+    let _guard = UserGuard::new(&env.url, &env.token, &id);
+
+    // List — our new admin appears with the right role.
+    let out = common::pic_as(&env)
+        .args(["admins", "ls"])
+        .output()
+        .expect("admins ls");
+    assert!(out.status.success(), "admins ls failed: {out:?}");
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    let header = stdout.lines().next().expect("header");
+    assert_eq!(
+        common::cells(header),
+        vec![
+            "id",
+            "username",
+            "role",
+            "active",
+            "email",
+            "created_at",
+            "last_login_at"
+        ]
+    );
+    let row = stdout
+        .lines()
+        .skip(1)
+        .map(common::cells)
+        .find(|c| c.get(1).copied() == Some(username.as_str()))
+        .unwrap_or_else(|| panic!("{username} missing from admins ls: {stdout}"));
+    assert_eq!(row[2], "admin");
+    assert_eq!(row[3], "true");
+
+    // Show — KvBlock includes the username row.
+    common::pic_as(&env)
+        .args(["admins", "show", &id])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(&username));
+
+    // Patch — deactivate.
+    common::pic_as(&env)
+        .args(["admins", "set", &id, "--active", "false"])
+        .assert()
+        .success();
+
+    // Patch result echoes is_active=false.
+    let out = common::pic_as(&env)
+        .args(["admins", "show", &id])
+        .output()
+        .expect("admins show after patch");
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(
+        stdout
+            .lines()
+            .any(|l| l.starts_with("is_active") && l.trim_end().ends_with("false")),
+        "patch should have deactivated: {stdout}"
+    );
+
+    // Remove.
+    common::pic_as(&env)
+        .args(["admins", "rm", &id])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(format!("Deleted admin {id}")));
+}
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn create_without_password_errors() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let username = common::unique_username("nopw");
+
+    common::pic_as(&env)
+        .args(["admins", "create", &username])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("missing --password"));
+}
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn member_cannot_list_admins() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let admin_env = common::admin_env(fx);
+    let m = common::member::member_user(fx, &common::unique_username("nomgmt"));
+    let member_env = common::custom_env(&fx.url, &m.token);
+    common::seed_credentials(&member_env, &m.username);
+
+    common::pic_as(&member_env)
+        .args(["admins", "ls"])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("HTTP 403"));
+    // Belt and suspenders so the unused `admin_env` doesn't warn.
+    let _ = admin_env;
+}

crates/picloud-cli/tests/cli.rs

@@ -13,6 +13,7 @@
 
 mod common;
 
+mod admins;
 mod api_keys;
 mod apps;
 mod auth;
@@ -20,4 +21,5 @@ mod invoke;
 mod logs;
 mod output;
 mod roles;
+mod routes;
 mod scripts;

crates/picloud-cli/tests/common/cleanup.rs

@@ -19,6 +19,10 @@ impl AppGuard {
             slug: slug.to_string(),
         }
     }
+
+    pub fn slug(&self) -> &str {
+        &self.slug
+    }
 }
 
 impl Drop for AppGuard {

crates/picloud-cli/tests/routes.rs

@@ -0,0 +1,162 @@
+//! `pic routes` smoke + edge tests. Covers the create → ls → match →
+//! rm round trip and the validation surface (unknown script id,
+//! conflict on duplicate).
+
+use predicates::prelude::*;
+
+use crate::common;
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn create_ls_match_remove_round_trip() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let (script_id, guard) = common::deploy_fixture(&env, "routes-rt", "hello.rhai");
+    let app_slug = guard.slug().to_string();
+
+    // Create — exact path, any method, sync dispatch by default.
+    common::pic_as(&env)
+        .args([
+            "routes", "create", "--script", &script_id, "--path", "/hook", "--method", "POST",
+        ])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Created route"));
+
+    // Ls — header columns and our row present.
+    let out = common::pic_as(&env)
+        .args(["routes", "ls", &script_id])
+        .output()
+        .expect("routes ls");
+    assert!(out.status.success(), "routes ls failed: {out:?}");
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    let mut lines = stdout.lines();
+    let header = lines.next().expect("header row");
+    assert_eq!(
+        common::cells(header),
+        vec![
+            "id",
+            "method",
+            "host",
+            "path_kind",
+            "path",
+            "dispatch",
+            "created_at"
+        ]
+    );
+    let row = lines
+        .map(common::cells)
+        .find(|c| c.get(4).copied() == Some("/hook"))
+        .unwrap_or_else(|| panic!("/hook row not in routes ls output: {stdout}"));
+    assert_eq!(row[1], "POST");
+    assert_eq!(row[5], "sync");
+    let route_id = row[0].to_string();
+
+    // Match — POST /hook on the app's any-host space resolves.
+    let out = common::pic_as(&env)
+        .args([
+            "routes",
+            "match",
+            "--app",
+            &app_slug,
+            "--method",
+            "POST",
+            "http://localhost/hook",
+        ])
+        .output()
+        .expect("routes match");
+    assert!(out.status.success(), "routes match failed: {out:?}");
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(
+        stdout.contains("matched") && stdout.contains("true"),
+        "match should have hit: {stdout}"
+    );
+    assert!(
+        stdout.contains(&route_id),
+        "match output should name the route id: {stdout}"
+    );
+
+    // Rm — drops the row.
+    common::pic_as(&env)
+        .args(["routes", "rm", &route_id])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(format!(
+            "Deleted route {route_id}"
+        )));
+
+    let out = common::pic_as(&env)
+        .args(["routes", "ls", &script_id])
+        .output()
+        .expect("routes ls after rm");
+    assert!(out.status.success());
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(
+        !stdout.lines().skip(1).any(|l| l.contains(&route_id)),
+        "deleted route still in ls: {stdout}"
+    );
+}
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn create_async_dispatch_is_persisted() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let (script_id, _guard) = common::deploy_fixture(&env, "routes-async", "hello.rhai");
+
+    common::pic_as(&env)
+        .args([
+            "routes",
+            "create",
+            "--script",
+            &script_id,
+            "--path",
+            "/bg",
+            "--method",
+            "POST",
+            "--dispatch",
+            "async",
+        ])
+        .assert()
+        .success();
+
+    let out = common::pic_as(&env)
+        .args(["routes", "ls", &script_id])
+        .output()
+        .expect("routes ls");
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    let row = stdout
+        .lines()
+        .skip(1)
+        .map(common::cells)
+        .find(|c| c.get(4).copied() == Some("/bg"))
+        .unwrap_or_else(|| panic!("/bg row missing: {stdout}"));
+    assert_eq!(row[5], "async", "dispatch column should be async: {row:?}");
+}
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn create_against_unknown_script_404s() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    // Bogus UUID-shaped script id so the path matcher accepts it
+    // but the script lookup 404s.
+    common::pic_as(&env)
+        .args([
+            "routes",
+            "create",
+            "--script",
+            "00000000-0000-0000-0000-000000000000",
+            "--path",
+            "/x",
+        ])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("HTTP 404"));
+}