fabi/PiCloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(cli): collections manifest + ls + journeys; rename to kv::shared_collection (§11.6 C5)

Browse Source 
Finish the §11.6 KV slice: declarative authoring, read-only inspection, the
runtime journey, and docs — plus a forced SDK-name fix.

- SDK name: `shared` is a Rhai RESERVED keyword, so `kv::shared(...)` is a parse
  error. Renamed the handle constructor to `kv::shared_collection(...)`
  (keeps the user's "shared" intent; unambiguous). Updated everywhere.
- CLI manifest: `collections = [...]` on `[group]` only (ManifestApp has no such
  field + deny_unknown_fields → an app manifest carrying it is a hard error);
  Manifest::collections() accessor; build_bundle emits it.
- plan/apply: a `collection` row group in `pic plan`; created/deleted counts in
  the apply summary; collections threaded through PlanDto/NodePlanDto/
  ApplyReportDto.
- read-only `pic collections ls --group` → GET /admin/groups/{id}/collections
  (viewer+), backed by ApplyService::collection_report + CollectionInfo.
- journey: a group declares `catalog`; app A writes, app B (same subtree) reads
  it back; a sibling-subtree app gets CollectionNotShared; `collections ls` +
  re-apply NoOp. Full suite 114/114.
- docs: groups-and-project-tool §11.6 (KV-only MVP shipped + deferrals),
  sdk-shape.md (the shared-collection handle + trust model), CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-06-29 22:26:43 +02:00
parent b79d8ef47d
commit 0973344515
19 changed files with 398 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
crates/executor-core/src/sdk/kv.rs
View File

@@ -42,7 +42,7 @@ pub struct KvHandle {
cx: Arc<SdkCallCx>,
}
/// §11.6 shared-collection handle, returned by `kv::shared(name)`. A distinct
/// §11.6 shared-collection handle, returned by `kv::shared_collection(name)`. A distinct
/// Rhai type from `KvHandle` so the method set can diverge (e.g. shared
/// collections never grow triggers) and a script's choice of private-vs-shared
/// scope is explicit. Routes through the `GroupKvService`, which resolves the
@@ -58,7 +58,7 @@ pub(super) fn register(engine: &mut RhaiEngine, services: &Services, cx: Arc<Sdk
let kv_service = services.kv.clone();
let group_kv_service = services.group_kv.clone();
// `kv::collection(name)` / `kv::shared(name)` — both constructors live in
// `kv::collection(name)` / `kv::shared_collection(name)` — both constructors live in
// the `kv` static module so the script-visible calls are `kv::collection`
// and `kv::shared`.
let mut module = Module::new();
@@ -83,10 +83,10 @@ pub(super) fn register(engine: &mut RhaiEngine, services: &Services, cx: Arc<Sdk
let group_kv_service = group_kv_service.clone();
let cx = cx.clone();
module.set_native_fn(
"shared",
"shared_collection",
move |name: &str| -> Result<GroupKvHandle, Box<EvalAltResult>> {
if name.is_empty() {
return Err("kv::shared name must not be empty".into());
return Err("kv::shared_collection name must not be empty".into());
}
Ok(GroupKvHandle {
collection: name.to_string(),

2
crates/manager-core/migrations/0052_group_collections.sql
View File

@@ -2,7 +2,7 @@
--
-- A row marks a collection NAME at a node as group-SHARED: every app in the
-- owning group's subtree may read it (and, with an authenticated editor+,
-- write it) via the explicit `kv::shared("name")` SDK handle. Resolution is
-- write it) via the explicit `kv::shared_collection("name")` SDK handle. Resolution is
-- nearest-ancestor-group-wins, walking the reading app's chain — that ancestry
-- walk is the isolation boundary (a foreign app's chain never contains the
-- owning group, so the name simply does not resolve). See docs §11.6.

24
crates/manager-core/src/apply_api.rs
View File

@@ -17,8 +17,8 @@ use serde_json::json;
use crate::app_repo::AppRepository;
use crate::apply_service::{
ApplyError, ApplyOwner, ApplyReport, ApplyService, Bundle, BundleTrigger, ExtensionPointInfo,
NodeKind, PlanResult, TreeBundle, TreePlanResult,
ApplyError, ApplyOwner, ApplyReport, ApplyService, Bundle, BundleTrigger, CollectionInfo,
ExtensionPointInfo, NodeKind, PlanResult, TreeBundle, TreePlanResult,
};
use crate::authz::{require, AuthzDenied, Capability};
use crate::group_repo::GroupRepository;
@@ -40,9 +40,29 @@ pub fn apply_router(service: ApplyService) -> Router {
"/groups/{id}/extension-points",
get(group_extension_points_handler),
)
.route("/groups/{id}/collections", get(group_collections_handler))
.with_state(service)
}
/// Read-only §11.6 shared-collection report for a group: its own declared
/// shared KV collection names. Viewer-tier read.
async fn group_collections_handler(
State(svc): State<ApplyService>,
Extension(principal): Extension<Principal>,
Path(id_or_slug): Path<String>,
) -> Result<Json<Vec<CollectionInfo>>, ApplyError> {
let group_id = resolve_group_id(svc.groups.as_ref(), &id_or_slug).await?;
require(
svc.authz.as_ref(),
&principal,
Capability::GroupScriptsRead(group_id),
)
.await
.map_err(map_authz)?;
let report = svc.collection_report(ApplyOwner::Group(group_id)).await?;
Ok(Json(report))
}
/// Read-only §5.5 extension-point report for an app: every EP visible on its
/// chain, each with `declared_here` + resolved `provider`. Viewer-tier read.
async fn app_extension_points_handler(

24
crates/manager-core/src/apply_service.rs
View File

@@ -437,6 +437,12 @@ pub struct ExtensionPointInfo {
pub provider: Option<String>,
}
/// One row of the read-only §11.6 shared-collection report.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CollectionInfo {
pub name: String,
}
// ----------------------------------------------------------------------------
// Errors
// ----------------------------------------------------------------------------
@@ -1772,6 +1778,24 @@ impl ApplyService {
}
}
/// Read-only §11.6 shared-collection report for a node: the shared KV
/// collection names declared directly at it. Group-only in practice (the
/// CLI rejects app-declared collections); an app node returns its own
/// (degenerate) declarations, if any. Backs `pic collections ls`.
pub async fn collection_report(
&self,
owner: ApplyOwner,
) -> Result<Vec<CollectionInfo>, ApplyError> {
let names =
crate::group_collection_repo::list_for_owner(&self.pool, owner.as_script_owner())
.await
.map_err(|e| ApplyError::Backend(e.to_string()))?;
Ok(names
.into_iter()
.map(|name| CollectionInfo { name })
.collect())
}
/// §5.5 no-provider plan check (app nodes only). Every extension point
/// visible to the app — declared in this bundle or inherited from an
/// ancestor — must have a provider: a module of that name the app provides

2
crates/manager-core/src/group_kv_service.rs
View File

@@ -1,6 +1,6 @@
//! `GroupKvServiceImpl` — wires `GroupKvRepo` + the group-collection registry
//! underneath the `picloud_shared::GroupKvService` trait that scripts reach via
//! the `kv::shared("name")` Rhai handle (§11.6).
//! the `kv::shared_collection("name")` Rhai handle (§11.6).
//!
//! Layers added over the raw repo:
//!

28
crates/picloud-cli/src/client.rs
View File

@@ -1332,6 +1332,26 @@ impl Client {
.await?;
decode(resp).await
}
/// `GET /api/v1/admin/groups/{ident}/collections` (§11.6). Group-only —
/// shared collections are declared on groups.
pub async fn collections_list(&self, group_ident: &str) -> Result<Vec<CollectionInfoDto>> {
let ident = seg(group_ident);
let resp = self
.request(
Method::GET,
&format!("/api/v1/admin/groups/{ident}/collections"),
)
.send()
.await?;
decode(resp).await
}
}
/// One row of the §11.6 shared-collection report.
#[derive(Debug, Deserialize)]
pub struct CollectionInfoDto {
pub name: String,
}
// ---------- DTOs (CLI-local, wire-shape-matched) ----------
@@ -1351,6 +1371,8 @@ pub struct PlanDto {
pub vars: Vec<ChangeDto>,
#[serde(default)]
pub extension_points: Vec<ChangeDto>,
#[serde(default)]
pub collections: Vec<ChangeDto>,
/// Fingerprint of the live state this plan was computed against; carried
/// in `.picloud/` and replayed to `apply` for the bound-plan check.
#[serde(default)]
@@ -1391,6 +1413,8 @@ pub struct NodePlanDto {
pub vars: Vec<ChangeDto>,
#[serde(default)]
pub extension_points: Vec<ChangeDto>,
#[serde(default)]
pub collections: Vec<ChangeDto>,
}
/// Response of `POST .../apply`: counts of what changed.
@@ -1423,6 +1447,10 @@ pub struct ApplyReportDto {
#[serde(default)]
pub extension_points_deleted: u32,
#[serde(default)]
pub collections_created: u32,
#[serde(default)]
pub collections_deleted: u32,
#[serde(default)]
pub warnings: Vec<String>,
}

14
crates/picloud-cli/src/cmds/apply.rs
View File

@@ -91,6 +91,13 @@ pub async fn run(
"+{} -{}",
report.extension_points_created, report.extension_points_deleted
),
)
.field(
"collections",
format!(
"+{} -{}",
report.collections_created, report.collections_deleted
),
);
for w in &report.warnings {
block.field("warning", w.clone());
@@ -165,6 +172,13 @@ pub async fn run_tree(
"+{} -{}",
report.extension_points_created, report.extension_points_deleted
),
)
.field(
"collections",
format!(
"+{} -{}",
report.collections_created, report.collections_deleted
),
);
for w in &report.warnings {
block.field("warning", w.clone());

23
crates/picloud-cli/src/cmds/collections.rs Normal file
View File

@@ -0,0 +1,23 @@
//! `pic collections ls --group <g>` — read-only view of a group's §11.6 shared
//! KV collections. Group-only (shared collections are owned by groups);
//! authoring is declarative via the `[group]` manifest `collections = [...]`.
//! Scripts read/write them with `kv::shared_collection("name")`.
use anyhow::Result;
use crate::client::Client;
use crate::config;
use crate::output::{OutputMode, Table};
pub async fn ls(group: &str, mode: OutputMode) -> Result<()> {
let creds = config::resolve()?;
let client = Client::from_creds(&creds)?;
let items = client.collections_list(group).await?;
let mut table = Table::new(["name"]);
for c in &items {
table.row([c.name.clone()]);
}
table.print(mode);
Ok(())
}

1
crates/picloud-cli/src/cmds/mod.rs
View File

@@ -3,6 +3,7 @@ pub mod api_keys;
pub mod apply;
pub mod apps;
pub mod apps_domains;
pub mod collections;
pub mod config;
pub mod dead_letters;
pub mod extension_points;

7
crates/picloud-cli/src/cmds/plan.rs
View File

@@ -64,13 +64,14 @@ fn render_tree(plan: &TreePlanDto, mode: OutputMode) {
let mut table = Table::new(["node", "kind", "op", "resource", "detail"]);
for n in &plan.nodes {
let node = format!("{}:{}", n.kind, n.slug);
let groups: [(&str, &Vec<ChangeDto>); 6] = [
let groups: [(&str, &Vec<ChangeDto>); 7] = [
("script", &n.scripts),
("route", &n.routes),
("trigger", &n.triggers),
("secret", &n.secrets),
("var", &n.vars),
("extension_point", &n.extension_points),
("collection", &n.collections),
];
for (rk, changes) in groups {
for c in changes {
@@ -162,6 +163,7 @@ pub fn build_bundle(manifest: &Manifest, base_dir: &Path) -> Result<Value> {
"secrets": manifest.secrets.names,
"vars": vars,
"extension_points": manifest.extension_points(),
"collections": manifest.collections(),
}))
}
@@ -176,13 +178,14 @@ fn tagged(kind: &str, spec: impl Serialize) -> Result<Value> {
fn render(plan: &PlanDto, mode: OutputMode) {
let mut table = Table::new(["kind", "op", "resource", "detail"]);
let groups: [(&str, &Vec<ChangeDto>); 6] = [
let groups: [(&str, &Vec<ChangeDto>); 7] = [
("script", &plan.scripts),
("route", &plan.routes),
("trigger", &plan.triggers),
("secret", &plan.secrets),
("var", &plan.vars),
("extension_point", &plan.extension_points),
("collection", &plan.collections),
];
for (kind, changes) in groups {
for c in changes {

22
crates/picloud-cli/src/main.rs
View File

@@ -162,6 +162,15 @@ enum Cmd {
cmd: ExtensionPointsCmd,
},
/// Shared group collections (§11.6) — read-only view of the KV collection
/// names a group offers as cross-app-shared. Authored declaratively via the
/// `[group]` manifest `collections = [...]`; scripts read/write them with
/// `kv::shared_collection("name")`.
Collections {
#[command(subcommand)]
cmd: CollectionsCmd,
},
/// Files inspection — list a collection's blobs, download bytes, or
/// delete a file. Read + delete only; writes go through scripts.
Files {
@@ -558,6 +567,16 @@ enum ExtensionPointsCmd {
},
}
#[derive(Subcommand)]
enum CollectionsCmd {
/// List the shared collections a group declares (§11.6). Group-only —
/// shared collections are owned by groups, not apps.
Ls {
#[arg(long)]
group: String,
},
}
#[derive(Subcommand)]
enum ScriptsCmd {
/// List scripts. With `--app`, scoped to one app; with `--group`, a
@@ -1985,6 +2004,9 @@ async fn main() -> ExitCode {
Cmd::ExtensionPoints {
cmd: ExtensionPointsCmd::Ls { app, group },
} => cmds::extension_points::ls(app.as_deref(), group.as_deref(), mode).await,
Cmd::Collections {
cmd: CollectionsCmd::Ls { group },
} => cmds::collections::ls(&group, mode).await,
Cmd::Files {
cmd:
FilesCmd::Ls {

18
crates/picloud-cli/src/manifest.rs
View File

@@ -111,6 +111,17 @@ impl Manifest {
}
}
/// This node's declared shared group-collection names (§11.6). Authored on
/// `[group]` nodes only — an `[app]` manifest carrying `collections` is a
/// hard parse error (`ManifestApp` has no such field + `deny_unknown_fields`).
#[must_use]
pub fn collections(&self) -> &[String] {
match &self.group {
Some(g) => &g.collections,
None => &[],
}
}
/// Load and parse the manifest at `path`.
pub fn load(path: &Path) -> Result<Self> {
let body =
@@ -238,6 +249,13 @@ pub struct ManifestGroup {
/// See [`ManifestApp::extension_points`]. A key of the `[group]` table.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub extension_points: Vec<String>,
/// `collections = ["catalog", …]` (§11.6) — shared KV collection names this
/// group offers as cross-app-shared (read by any app in the subtree,
/// written by an authenticated editor+). Group-only: there is no
/// `collections` key on `[app]`. The data lives in `group_kv_entries`;
/// pruning a name removes the declaration, not the data.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub collections: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]

1
crates/picloud-cli/tests/cli.rs
View File

@@ -18,6 +18,7 @@ mod api_keys;
mod apply;
mod apps;
mod auth;
mod collections;
mod config;
mod dead_letters;
mod email_queue;

187
crates/picloud-cli/tests/collections.rs Normal file
View File

@@ -0,0 +1,187 @@
//! §11.6 shared group collections, end to end via `pic`:
//! * a group declares a shared KV collection `catalog`; two apps under it
//! share one store — an authenticated write in app A is read back in app B
//! (cross-app data sharing, the deliberate inverse of per-app isolation),
//! * an app under a SIBLING group naming `catalog` gets CollectionNotShared
//! (the ancestry walk is the isolation boundary),
//! * `pic collections ls --group` lists the declared name; re-plan is NoOp.
//!
//! The anonymous-write-fails-closed half of the trust model is unit-tested in
//! `group_kv_service` (a journey invoke always carries the admin principal).
use std::fs;
use tempfile::TempDir;
use crate::common;
use crate::common::cleanup::{AppGuard, GroupGuard};
fn manifest_dir() -> TempDir {
let dir = TempDir::new().expect("tempdir");
fs::create_dir_all(dir.path().join("scripts")).expect("scripts dir");
dir
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[test]
fn shared_collection_is_read_write_across_the_subtree() {
let Some(fx) = common::fixture_or_skip() else {
return;
};
let env = common::admin_env(fx);
let group = common::unique_slug("coll-grp");
let sibling = common::unique_slug("coll-sib");
let app_a = common::unique_slug("coll-a");
let app_b = common::unique_slug("coll-b");
let foreign = common::unique_slug("coll-f");
let _g = GroupGuard::new(&env.url, &env.token, &group);
let _gs = GroupGuard::new(&env.url, &env.token, &sibling);
common::pic_as(&env)
.args(["groups", "create", &group])
.assert()
.success();
common::pic_as(&env)
.args(["groups", "create", &sibling])
.assert()
.success();
// The group declares `catalog` a shared collection (declarative apply).
let dir = manifest_dir();
let gmanifest =
format!("[group]\nslug = \"{group}\"\nname = \"Coll\"\n\ncollections = [\"catalog\"]\n");
let gpath = dir.path().join("group.toml");
fs::write(&gpath, &gmanifest).unwrap();
common::pic_as(&env)
.args(["apply", "--file"])
.arg(&gpath)
.assert()
.success();
// `collections ls --group` shows the declared name.
let ls = String::from_utf8(
common::pic_as(&env)
.args(["collections", "ls", "--group", &group])
.output()
.unwrap()
.stdout,
)
.unwrap();
assert!(
ls.contains("catalog"),
"ls should list the collection:\n{ls}"
);
// Re-apply is a no-op (the marker already exists).
common::pic_as(&env)
.args(["apply", "--file"])
.arg(&gpath)
.assert()
.success();
// Two apps under the group; one under a sibling group.
let _a = AppGuard::new(&env.url, &env.token, &app_a);
let _b = AppGuard::new(&env.url, &env.token, &app_b);
let _f = AppGuard::new(&env.url, &env.token, &foreign);
common::pic_as(&env)
.args(["apps", "create", &app_a, "--group", &group])
.assert()
.success();
common::pic_as(&env)
.args(["apps", "create", &app_b, "--group", &group])
.assert()
.success();
common::pic_as(&env)
.args(["apps", "create", &foreign, "--group", &sibling])
.assert()
.success();
// App A writes to the shared collection (authenticated invoke → admin
// principal, so the editor+ write gate is satisfied).
fs::write(
dir.path().join("scripts/writer.rhai"),
r#"kv::shared_collection("catalog").set("sku-1", #{ price: 9 }); "ok""#,
)
.unwrap();
common::pic_as(&env)
.args(["scripts", "deploy"])
.arg(dir.path().join("scripts/writer.rhai"))
.args(["--app", &app_a, "--name", "writer"])
.assert()
.success();
let writer_id = app_script_id(&env, &app_a, "writer");
common::pic_as(&env)
.args(["scripts", "invoke", &writer_id])
.assert()
.success();
// App B reads the SAME store back — cross-app sharing.
fs::write(
dir.path().join("scripts/reader.rhai"),
r#"kv::shared_collection("catalog").get("sku-1")"#,
)
.unwrap();
common::pic_as(&env)
.args(["scripts", "deploy"])
.arg(dir.path().join("scripts/reader.rhai"))
.args(["--app", &app_b, "--name", "reader"])
.assert()
.success();
let reader_id = app_script_id(&env, &app_b, "reader");
assert_eq!(
invoke_body(&env, &reader_id),
serde_json::json!({ "price": 9 }),
"an app in the subtree reads what another app wrote to the shared collection"
);
// The foreign app (sibling subtree) names `catalog` but it does not resolve
// on its chain — CollectionNotShared. The invoke fails.
fs::write(
dir.path().join("scripts/foreign.rhai"),
r#"kv::shared_collection("catalog").get("sku-1")"#,
)
.unwrap();
common::pic_as(&env)
.args(["scripts", "deploy"])
.arg(dir.path().join("scripts/foreign.rhai"))
.args(["--app", &foreign, "--name", "peek"])
.assert()
.success();
let foreign_id = app_script_id(&env, &foreign, "peek");
let out = common::pic_as(&env)
.args(["scripts", "invoke", &foreign_id])
.output()
.expect("invoke");
assert!(
!out.status.success(),
"a foreign app must not resolve another subtree's shared collection"
);
}
/// Id of the named script in an app (`pic scripts ls --app <a>`).
fn app_script_id(env: &common::TestEnv, app: &str, name: &str) -> String {
let ls = common::pic_as(env)
.args(["scripts", "ls", "--app", app])
.output()
.expect("scripts ls");
let table = String::from_utf8(ls.stdout).unwrap();
table
.lines()
.map(common::cells)
.find(|c| c.get(2) == Some(&name))
.and_then(|c| c.first().map(|s| (*s).to_string()))
.unwrap_or_else(|| panic!("script `{name}` not found:\n{table}"))
}
fn invoke_body(env: &common::TestEnv, id: &str) -> serde_json::Value {
let out = common::pic_as(env)
.args(["scripts", "invoke", id])
.output()
.expect("scripts invoke");
assert!(
out.status.success(),
"invoke failed: {}",
String::from_utf8_lossy(&out.stderr)
);
serde_json::from_slice(&out.stdout).expect("invoke body is JSON")
}

2
crates/shared/src/group_kv.rs
View File

@@ -1,7 +1,7 @@
//! `GroupKvService` — the §11.6 shared group-collection KV contract.
//!
//! The cross-app-sharing counterpart to [`crate::KvService`]. A script reaches
//! it via the explicit `kv::shared("name")` handle (distinct from the
//! it via the explicit `kv::shared_collection("name")` handle (distinct from the
//! app-private `kv::collection("name")`). Unlike `KvService`, the *owner* of
//! the data is not `cx.app_id`: the impl resolves the **owning group** by
//! walking the calling app's ancestor chain for the nearest group that declares

2
crates/shared/src/services.rs
View File

@@ -116,7 +116,7 @@ pub struct Services {
pub vars: Arc<dyn VarsService>,
/// Shared cross-app group collections (§11.6). Scripts get
/// `kv::shared(name)` — read/write KV scoped to the nearest ancestor
/// `kv::shared_collection(name)` — read/write KV scoped to the nearest ancestor
/// group that declares the collection shared. Backed by Postgres in the
/// picloud binary (wired via [`Services::with_group_kv`]); defaults to
/// `NoopGroupKvService` so test bundles that don't exercise sharing build