Skip to content

Commit cb8dbf3

Browse files
tellahoCarl
andauthored
feat(plugins): add descriptions and categories to plugins (#1145)
Signed-off-by: Taylor Ho <[email protected]> Co-authored-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
1 parent 0d05e21 commit cb8dbf3

41 files changed

Lines changed: 860 additions & 114 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -254,7 +254,8 @@ to exercise component reuse and contribution lifecycle.
254254
## Plugin contract
255255

256256
`src/bundled/channels` is a bundled example. External projects have `manifest.json`
257-
(`id`, `name`, `apiVersion: 1`) and an entry point exporting
257+
(`id`, `name`, `apiVersion: 1`, and optional `description`/`discovery`) and an entry
258+
point exporting
258259
`apply(ctx)`. `ctx` is a Cordis context. External JSX plugins export
259260
`inject = ["react", "pages"]` and obtain `const React = ctx.react` inside `apply`, then call
260261
`ctx.pages.register({ id, title, component })` to contribute a page. A plugin may register

‎crates/plugin-manager/src/lib.rs‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,22 @@ pub struct Manifest {
2828
pub name: String,
2929
pub api_version: u32,
3030
#[serde(default, skip_serializing_if = "Option::is_none")]
31+
pub description: Option<String>,
32+
#[serde(default, skip_serializing_if = "Option::is_none")]
33+
pub discovery: Option<Discovery>,
34+
#[serde(default, skip_serializing_if = "Option::is_none")]
3135
pub host: Option<HostGrants>,
3236
}
37+
/// Display-only metadata is deliberately forward-compatible. Unknown fields are
38+
/// ignored so adding a discovery hint does not make a plugin unloadable.
39+
#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
40+
#[serde(rename_all = "camelCase")]
41+
pub struct Discovery {
42+
#[serde(default, skip_serializing_if = "Option::is_none")]
43+
pub category: Option<String>,
44+
#[serde(default, skip_serializing_if = "Vec::is_empty")]
45+
pub tags: Vec<String>,
46+
}
3347
#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
3448
#[serde(rename_all = "camelCase", deny_unknown_fields)]
3549
pub struct HostGrants {
@@ -94,9 +108,41 @@ impl Manifest {
94108
if self.name.trim().is_empty() || self.name.len() > 80 {
95109
return Err("Name must contain 1–80 bytes of text".into());
96110
}
111+
if self
112+
.description
113+
.as_ref()
114+
.is_some_and(|description| description.trim().is_empty() || description.len() > 280)
115+
{
116+
return Err("Description must contain 1–280 bytes of text".into());
117+
}
97118
if self.api_version != 1 {
98119
return Err("Only page plugin API version 1 is supported".into());
99120
}
121+
if let Some(discovery) = &self.discovery {
122+
if let Some(category) = &discovery.category {
123+
valid_id(category)?;
124+
}
125+
if discovery.tags.len() > 16 {
126+
return Err("Too many discovery tags".into());
127+
}
128+
let mut tags = std::collections::HashSet::new();
129+
for tag in &discovery.tags {
130+
if tag.trim().is_empty() || tag.len() > 80 || tag.chars().any(char::is_control) {
131+
return Err(
132+
"Discovery tags must contain 1–80 bytes of text without control characters"
133+
.into(),
134+
);
135+
}
136+
let key = tag
137+
.split_whitespace()
138+
.collect::<Vec<_>>()
139+
.join(" ")
140+
.to_lowercase();
141+
if !tags.insert(key) {
142+
return Err("Duplicate discovery tag".into());
143+
}
144+
}
145+
}
100146
if let Some(host) = &self.host {
101147
if host.commands.len() > 16
102148
|| host.network_origins.len() > 16
@@ -1303,6 +1349,123 @@ mod tests {
13031349
}
13041350
}
13051351

1352+
#[test]
1353+
fn validates_discovery_metadata_and_old_manifests() {
1354+
let old: Manifest =
1355+
serde_json::from_str(r#"{"id":"example.page","name":"Example","apiVersion":1}"#)
1356+
.unwrap();
1357+
assert_eq!(old.description, None);
1358+
assert_eq!(old.discovery, None);
1359+
assert!(old.validate().is_ok());
1360+
assert_eq!(
1361+
serde_json::to_value(&old).unwrap(),
1362+
serde_json::json!({"id":"example.page","name":"Example","apiVersion":1})
1363+
);
1364+
1365+
let manifest = serde_json::json!({
1366+
"id": "example.page",
1367+
"name": "Example",
1368+
"apiVersion": 1,
1369+
"description": "Reconcile invoices without leaving Buzz.",
1370+
"discovery": {
1371+
"category": "finance",
1372+
"tags": ["accounting", "invoices"],
1373+
"futureDisplayHint": true
1374+
}
1375+
});
1376+
let parsed: Manifest = serde_json::from_value(manifest).unwrap();
1377+
assert!(parsed.validate().is_ok());
1378+
assert_eq!(
1379+
parsed.description.as_deref(),
1380+
Some("Reconcile invoices without leaving Buzz.")
1381+
);
1382+
assert_eq!(
1383+
parsed.discovery.as_ref().unwrap().category.as_deref(),
1384+
Some("finance")
1385+
);
1386+
assert_eq!(
1387+
parsed.discovery.as_ref().unwrap().tags,
1388+
["accounting", "invoices"]
1389+
);
1390+
assert!(!serde_json::to_string(&parsed)
1391+
.unwrap()
1392+
.contains("futureDisplayHint"));
1393+
1394+
for description in ["".into(), " ".into(), "x".repeat(281)] {
1395+
let mut invalid = parsed.clone();
1396+
invalid.description = Some(description);
1397+
assert!(invalid.validate().is_err());
1398+
}
1399+
for category in ["", "Finance", "finance_tools"] {
1400+
let mut invalid = parsed.clone();
1401+
invalid.discovery.as_mut().unwrap().category = Some(category.into());
1402+
assert!(invalid.validate().is_err());
1403+
}
1404+
let mut duplicate = parsed.clone();
1405+
duplicate.discovery.as_mut().unwrap().tags = vec!["finance".into(), "finance".into()];
1406+
assert!(duplicate.validate().is_err());
1407+
let mut too_many = parsed.clone();
1408+
too_many.discovery.as_mut().unwrap().tags =
1409+
(0..17).map(|index| format!("tag-{index}")).collect();
1410+
assert!(too_many.validate().is_err());
1411+
1412+
let unknown_top_level = serde_json::json!({
1413+
"id": "example.page",
1414+
"name": "Example",
1415+
"apiVersion": 1,
1416+
"futureSecurityField": true
1417+
});
1418+
assert!(serde_json::from_value::<Manifest>(unknown_top_level).is_err());
1419+
}
1420+
1421+
#[test]
1422+
fn discovery_tags_accept_readable_text_and_preserve_display_spelling() {
1423+
let text = serde_json::json!({
1424+
"id": "example.page", "name": "Example", "apiVersion": 1,
1425+
"discovery": {
1426+
"category": "finance",
1427+
"tags": ["Programming Language", " Café Tools ", "编程", "C++", "🛠️"]
1428+
}
1429+
});
1430+
let manifest: Manifest = serde_json::from_value(text.clone()).unwrap();
1431+
assert!(manifest.validate().is_ok());
1432+
assert_eq!(serde_json::to_value(&manifest).unwrap(), text);
1433+
let bytes = artifact_from_text(&text.to_string(), "export const code = 1".into()).unwrap();
1434+
let artifact: super::Artifact = serde_json::from_slice(&bytes).unwrap();
1435+
assert_eq!(artifact.manifest, manifest);
1436+
1437+
for tag in ["x".repeat(80), "é".repeat(40)] {
1438+
let mut valid = manifest.clone();
1439+
valid.discovery.as_mut().unwrap().tags = vec![tag];
1440+
assert!(valid.validate().is_ok());
1441+
}
1442+
for tag in [
1443+
"".into(),
1444+
" ".into(),
1445+
"\u{a0}".into(),
1446+
"x".repeat(81),
1447+
"é".repeat(41),
1448+
"Programming\nLanguage".into(),
1449+
"Programming\tLanguage".into(),
1450+
"Bad\0Tag".into(),
1451+
"Bad\u{7f}Tag".into(),
1452+
] {
1453+
let mut invalid = manifest.clone();
1454+
invalid.discovery.as_mut().unwrap().tags = vec![tag];
1455+
assert!(invalid.validate().is_err());
1456+
}
1457+
for pair in [
1458+
["Programming Language", "programming language"],
1459+
["Programming Language", " Programming Language "],
1460+
["Programming Language", "Programming\u{a0}Language"],
1461+
["Café", "CAFÉ"],
1462+
] {
1463+
let mut duplicate = manifest.clone();
1464+
duplicate.discovery.as_mut().unwrap().tags = pair.map(String::from).to_vec();
1465+
assert!(duplicate.validate().is_err());
1466+
}
1467+
}
1468+
13061469
#[test]
13071470
fn validates_host_declarations_and_old_manifests() {
13081471
let old: Manifest =

‎crates/plugin-manager/src/main.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,8 @@ fn init(directory: &Path, id: &str, name: &str) -> Result<()> {
172172
id: id.into(),
173173
name: name.into(),
174174
api_version: 1,
175+
description: None,
176+
discovery: None,
175177
host: None,
176178
};
177179
manifest.validate()?;

‎docs/plugin-architecture.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -510,7 +510,42 @@ external JSX plugins declare `inject = ["react"]` to use the shared instance. Th
510510
constructs its module loader and execution adapter internally, observes configuration,
511511
and selects the desired plugins (including enabled flags and safe mode).
512512

513-
Plugins can declare host access in `manifest.json`:
513+
Plugin manifests may include display-only discovery metadata:
514+
515+
```json
516+
{
517+
"id": "example.invoices",
518+
"name": "Invoices",
519+
"apiVersion": 1,
520+
"description": "Reconcile invoices without leaving Buzz.",
521+
"discovery": {
522+
"category": "finance",
523+
"tags": ["Accounting", "Invoice Management"]
524+
}
525+
}
526+
```
527+
528+
Descriptions contain 1–280 UTF-8 bytes. Category values use the same stable
529+
lowercase identifier syntax as plugin IDs. Tags are readable plain text, such as
530+
`"Programming Language"`, with 1–80 UTF-8 bytes per tag and at most 16 tags. Blank
531+
tags and control characters (including tabs and newlines) are rejected. Duplicate
532+
comparison trims and collapses Unicode whitespace to a single space, then applies
533+
Unicode lowercasing; `"Programming Language"` and `" programming language "`
534+
are duplicates. The original spelling, casing, and spacing are preserved for
535+
display and serialization. This comparison does not perform Unicode canonical
536+
normalization or full Unicode case folding.
537+
Categories are open slugs: a host may give recognized categories first-class
538+
labels and group unrecognized values under Other, but an unrecognized category
539+
does not invalidate a plugin. Tags carry open-ended search terms. Neither field
540+
grants capabilities, asserts provenance, or describes runtime state. The
541+
`discovery` object accepts unknown display hints for forward compatibility;
542+
security-bearing manifest fields remain strict.
543+
544+
Hosts released before these metadata fields were introduced reject `description`
545+
and `discovery` as unknown manifest keys. Publishers targeting those hosts must
546+
omit both fields; using slug tags does not make them compatible.
547+
548+
Plugins can separately declare host access in `manifest.json`:
514549

515550
```json
516551
{

‎src/app/Settings.module.css‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,34 @@
9393
gap: var(--space-4);
9494
padding-block: var(--space-3) var(--space-2);
9595
}
96+
97+
.pluginCategoryTitle {
98+
display: inline-flex;
99+
align-items: center;
100+
flex-wrap: wrap;
101+
gap: var(--space-2);
102+
@apply text-body-lg;
103+
font-weight: var(--type-weight-medium);
104+
}
105+
106+
.pluginCount {
107+
display: inline-flex;
108+
align-items: center;
109+
justify-content: center;
110+
min-inline-size: var(--space-6);
111+
padding: var(--space-half) var(--space-2);
112+
border-radius: var(--radius-capsule);
113+
background: var(--surface-inverse);
114+
color: var(--text-inverse);
115+
@apply text-caption;
116+
}
117+
118+
.pluginControls {
119+
display: flex;
120+
align-items: center;
121+
gap: var(--space-2);
122+
}
123+
96124
.settingsGroupTitle {
97125
margin: 0 0 var(--space-1);
98126
padding-inline: var(--space-2);

0 commit comments

Comments
 (0)