Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(marketplace): usage cards load from data/usage_cards/ second root

rubenluetke10-beep05fa246a882b
diff --git a/jarvis/marketplace/usage_cards/loader.py b/jarvis/marketplace/usage_cards/loader.py
index 9a0c720008..07fe357578 100644
--- a/jarvis/marketplace/usage_cards/loader.py
+++ b/jarvis/marketplace/usage_cards/loader.py
@@ -14,6 +14,10 @@ from dataclasses import dataclass, field
from pathlib import Path
_CARDS_DIR = Path(__file__).parent
+# Second lookup root for cards that arrive at runtime (community marketplace
+# installs). Lives under the gitignored data/ next to plugin_catalog.json —
+# the package cannot be written on a user machine, data/ can.
+_DATA_CARDS_DIR = Path(__file__).resolve().parents[3] / "data" / "usage_cards"
def _resolve_card_path(plugin_id: str) -> Path | None:
@@ -26,15 +30,19 @@ def _resolve_card_path(plugin_id: str) -> Path | None:
``-`` -> ``_`` and ``_`` -> ``-``, and return the first existing file. The
swaps only touch ``-``/``_`` and so cannot introduce a path separator; the
caller still applies the path-traversal guard beforehand.
+
+ The bundled package directory is searched BEFORE ``data/usage_cards/`` so a
+ community card can never shadow a shipped plugin's curated keywords.
"""
- for candidate in (
- plugin_id,
- plugin_id.replace("-", "_"),
- plugin_id.replace("_", "-"),
- ):
- path = _CARDS_DIR / f"{candidate}.md"
- if path.exists():
- return path
+ for directory in (_CARDS_DIR, _DATA_CARDS_DIR):
+ for candidate in (
+ plugin_id,
+ plugin_id.replace("-", "_"),
+ plugin_id.replace("_", "-"),
+ ):
+ path = directory / f"{candidate}.md"
+ if path.exists():
+ return path
return None
@@ -83,3 +91,45 @@ def load_usage_card(plugin_id: str) -> UsageCard | None:
value = value.split(" #", 1)[0]
keywords = [k.strip() for k in value.split(",") if k.strip()]
return UsageCard(plugin_id=plugin_id, keywords=keywords, body=body.strip())
+
+
+def _guarded_data_card_path(plugin_id: str) -> Path | None:
+ """The data-root card path for ``plugin_id``, or None when the id fails
+ the same traversal guard `load_usage_card` applies."""
+ if not plugin_id or "/" in plugin_id or "\\" in plugin_id or ".." in plugin_id:
+ return None
+ return _DATA_CARDS_DIR / f"{plugin_id}.md"
+
+
+def save_usage_card(plugin_id: str, text: str) -> Path:
+ """Persist a community plugin's usage card under ``data/usage_cards/``.
+
+ Atomic write (tmp file + replace) so a crash mid-write never leaves a
+ half card that would silently change the relevance gate's vocabulary.
+ Clears the loader cache — the gate runs on the voice critical path and
+ must see the new card without a restart.
+ """
+ path = _guarded_data_card_path(plugin_id)
+ if path is None:
+ raise ValueError(f"invalid plugin id for usage card: {plugin_id!r}")
+ path.parent.mkdir(parents=True, exist_ok=True)
+ tmp = path.with_suffix(".md.tmp")
+ tmp.write_text(text, encoding="utf-8")
+ tmp.replace(path)
+ load_usage_card.cache_clear()
+ return path
+
+
+def delete_usage_card(plugin_id: str) -> None:
+ """Remove a community card from the data root (bundled cards are never
+ touched). Missing file is a no-op — uninstall must stay idempotent."""
+ path = _guarded_data_card_path(plugin_id)
+ if path is None:
+ return
+ try:
+ path.unlink(missing_ok=True)
+ except OSError:
+ # An undeletable card only means stale keywords until the next try;
+ # never let it abort an uninstall.
+ return
+ load_usage_card.cache_clear()
diff --git a/tests/unit/marketplace/test_usage_cards_data_root.py b/tests/unit/marketplace/test_usage_cards_data_root.py
new file mode 100644
index 0000000000..d07ffd9e9f
--- /dev/null
+++ b/tests/unit/marketplace/test_usage_cards_data_root.py
@@ -0,0 +1,68 @@
+"""Usage cards from the ``data/usage_cards/`` second root (community installs)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from jarvis.marketplace.usage_cards import loader
+
+
+def data_cards_dir(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ directory = tmp_path / "usage_cards"
+ monkeypatch.setattr(loader, "_DATA_CARDS_DIR", directory)
+ loader.load_usage_card.cache_clear()
+ yield directory
+ loader.load_usage_card.cache_clear()
+
+
+def test_card_loads_from_data_root(data_cards_dir: Path) -> None:
+ data_cards_dir.mkdir(parents=True)
+ (data_cards_dir / "todo-fox.md").write_text(
+ "---\nkeywords: todo, fox\n---\nUse TodoFox for tasks.",
+ encoding="utf-8",
+ )
+ card = loader.load_usage_card("todo-fox")
+ assert card is not None
+ assert card.keywords == ["todo", "fox"]
+ assert "TodoFox" in card.body
+
+
+def test_package_card_wins_over_data_card(data_cards_dir: Path) -> None:
+ """A community card must never shadow a shipped plugin's keywords."""
+ data_cards_dir.mkdir(parents=True)
+ (data_cards_dir / "github.md").write_text(
+ "---\nkeywords: hijacked\n---\nshadowed",
+ encoding="utf-8",
+ )
+ card = loader.load_usage_card("github")
+ assert card is not None
+ assert "hijacked" not in card.keywords
+
+
+def test_save_usage_card_is_atomic_and_visible(data_cards_dir: Path) -> None:
+ path = loader.save_usage_card("todo-fox", "---\nkeywords: fox\n---\nBody")
+ assert path.parent == data_cards_dir
+ assert not list(data_cards_dir.glob("*.tmp"))
+ card = loader.load_usage_card("todo-fox")
+ assert card is not None
+ assert card.keywords == ["fox"]
+
+
+def test_save_rejects_traversal_ids(data_cards_dir: Path) -> None:
+ for bad in ("../evil", "a/b", "a\\b", ""):
+ with pytest.raises(ValueError, match="invalid plugin id"):
+ loader.save_usage_card(bad, "body")
+
+
+def test_delete_usage_card_idempotent(data_cards_dir: Path) -> None:
+ loader.save_usage_card("todo-fox", "body")
+ loader.delete_usage_card("todo-fox")
+ assert loader.load_usage_card("todo-fox") is None
+ loader.delete_usage_card("todo-fox") # second delete: no error
+
+
+def test_missing_card_still_none(data_cards_dir: Path) -> None:
+ assert loader.load_usage_card("never-published") is None