diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 50d446b..b9686ee 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,6 +9,16 @@ "name": "g4b_ai", "source": "./plugins/g4b_ai", "description": "Gabor's personal Claude Code skills: workpad, research-tree, implementation-orchestration, markdown-embedded-svg" + }, + { + "name": "dioxus", + "source": "./plugins/dioxus", + "description": "Per-version Dioxus Rust UI library reference skills (currently 0.7)" + }, + { + "name": "project-uv", + "source": "./plugins/project-uv", + "description": "Detects how uv is wired into a Python project and advertises the right invocation patterns" } ] } diff --git a/plugins/dioxus/.claude-plugin/plugin.json b/plugins/dioxus/.claude-plugin/plugin.json new file mode 100644 index 0000000..ed5e56d --- /dev/null +++ b/plugins/dioxus/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "dioxus", + "version": "0.1.0", + "description": "Dioxus Rust UI library reference skills, pinned per Dioxus version (currently 0.7).", + "author": { + "name": "Gabor Körber", + "email": "gab@g4b.org" + } +} diff --git a/plugins/dioxus/README.md b/plugins/dioxus/README.md new file mode 100644 index 0000000..a2f403e --- /dev/null +++ b/plugins/dioxus/README.md @@ -0,0 +1,29 @@ +# dioxus + +Per-version reference skills for the [Dioxus](https://dioxuslabs.com/) Rust UI library. + +Dioxus has had breaking API changes across minor versions (`cx`, `Scope`, and `use_state` are gone as of 0.7), so each skill is pinned to a specific Dioxus version. Enable the one that matches your project's `Cargo.toml`. + +## Skills + +- **dioxus-0.7** — Dioxus 0.7+ API reference: components, signals, RSX, assets, routing, fullstack, hydration. + +## Install + +``` +/plugin marketplace add git@git.g4b.org:dirigence/reliquary.git +/plugin install dioxus@reliquary +``` + +Or in `.claude/settings.json`: + +```json +{ + "extraKnownMarketplaces": { + "reliquary": { + "source": { "source": "git", "url": "git@git.g4b.org:dirigence/reliquary.git" } + } + }, + "enabledPlugins": { "dioxus@reliquary": true } +} +``` diff --git a/plugins/dioxus/skills/dioxus-0.7/SKILL.md b/plugins/dioxus/skills/dioxus-0.7/SKILL.md new file mode 100644 index 0000000..e39cc09 --- /dev/null +++ b/plugins/dioxus/skills/dioxus-0.7/SKILL.md @@ -0,0 +1,270 @@ +--- +name: dioxus-0.7 +description: Use when writing or modifying Rust code that depends on Dioxus 0.7+ (`dioxus = "0.7"` in Cargo.toml, or files using `use dioxus::prelude::*`, `#[component]`, `rsx!`, `use_signal`, `use_resource`, `Router`, or server functions). Dioxus 0.7 broke the older `cx`/`Scope`/`use_state` API — apply this skill instead of relying on pre-0.7 patterns from training data. +--- + +You are an expert [0.7 Dioxus](https://dioxuslabs.com/learn/0.7) assistant. Dioxus 0.7 changes every api in dioxus. Only use this up to date documentation. `cx`, `Scope`, and `use_state` are gone + +Provide concise code examples with detailed descriptions + +# Dioxus Dependency + +You can add Dioxus to your `Cargo.toml` like this: + +```toml +[dependencies] +dioxus = { version = "0.7.0" } + +[features] +default = ["web", "webview", "server"] +web = ["dioxus/web"] +webview = ["dioxus/desktop"] +server = ["dioxus/server"] +``` + +# Launching your application + +You need to create a main function that sets up the Dioxus runtime and mounts your root component. + +```rust +use dioxus::prelude::*; + +fn main() { + dioxus::launch(App); +} + +#[component] +fn App() -> Element { + rsx! { "Hello, Dioxus!" } +} +``` + +Then serve with `dx serve`: + +```sh +curl -sSL http://dioxus.dev/install.sh | sh +dx serve +``` + +# UI with RSX + +```rust +rsx! { + div { + class: "container", // Attribute + color: "red", // Inline styles + width: if condition { "100%" }, // Conditional attributes + "Hello, Dioxus!" + } + // Prefer loops over iterators + for i in 0..5 { + div { "{i}" } // use elements or components directly in loops + } + if condition { + div { "Condition is true!" } // use elements or components directly in conditionals + } + + {children} // Expressions are wrapped in brace + {(0..5).map(|i| rsx! { span { "Item {i}" } })} // Iterators must be wrapped in braces +} +``` + +# Assets + +The asset macro can be used to link to local files to use in your project. All links start with `/` and are relative to the root of your project. + +```rust +rsx! { + img { + src: asset!("/assets/image.png"), + alt: "An image", + } +} +``` + +## Styles + +The `document::Stylesheet` component will inject the stylesheet into the `` of the document + +```rust +rsx! { + document::Stylesheet { + href: asset!("/assets/styles.css"), + } +} +``` + +# Components + +Components are the building blocks of apps + +* Component are functions annotated with the `#[component]` macro. +* The function name must start with a capital letter or contain an underscore. +* A component re-renders only under two conditions: + 1. Its props change (as determined by `PartialEq`). + 2. An internal reactive state it depends on is updated. + +```rust +#[component] +fn Input(mut value: Signal) -> Element { + rsx! { + input { + value, + oninput: move |e| { + *value.write() = e.value(); + }, + onkeydown: move |e| { + if e.key() == Key::Enter { + value.write().clear(); + } + }, + } + } +} +``` + +Each component accepts function arguments (props) + +* Props must be owned values, not references. Use `String` and `Vec` instead of `&str` or `&[T]`. +* Props must implement `PartialEq` and `Clone`. +* To make props reactive and copy, you can wrap the type in `ReadOnlySignal`. Any reactive state like memos and resources that read `ReadOnlySignal` props will automatically re-run when the prop changes. + +# State + +A signal is a wrapper around a value that automatically tracks where it's read and written. Changing a signal's value causes code that relies on the signal to rerun. + +## Local State + +The `use_signal` hook creates state that is local to a single component. You can call the signal like a function (e.g. `my_signal()`) to clone the value, or use `.read()` to get a reference. `.write()` gets a mutable reference to the value. + +Use `use_memo` to create a memoized value that recalculates when its dependencies change. Memos are useful for expensive calculations that you don't want to repeat unnecessarily. + +```rust +#[component] +fn Counter() -> Element { + let mut count = use_signal(|| 0); + let mut doubled = use_memo(move || count() * 2); // doubled will re-run when count changes because it reads the signal + + rsx! { + h1 { "Count: {count}" } // Counter will re-render when count changes because it reads the signal + h2 { "Doubled: {doubled}" } + button { + onclick: move |_| *count.write() += 1, // Writing to the signal rerenders Counter + "Increment" + } + button { + onclick: move |_| count.with_mut(|count| *count += 1), // use with_mut to mutate the signal + "Increment with with_mut" + } + } +} +``` + +## Context API + +The Context API allows you to share state down the component tree. A parent provides the state using `use_context_provider`, and any child can access it with `use_context` + +```rust +#[component] +fn App() -> Element { + let mut theme = use_signal(|| "light".to_string()); + use_context_provider(|| theme); // Provide a type to children + rsx! { Child {} } +} + +#[component] +fn Child() -> Element { + let theme = use_context::>(); // Consume the same type + rsx! { + div { + "Current theme: {theme}" + } + } +} +``` + +# Async + +For state that depends on an asynchronous operation (like a network request), Dioxus provides a hook called `use_resource`. This hook manages the lifecycle of the async task and provides the result to your component. + +* The `use_resource` hook takes an `async` closure. It re-runs this closure whenever any signals it depends on (reads) are updated +* The `Resource` object returned can be in several states when read: +1. `None` if the resource is still loading +2. `Some(value)` if the resource has successfully loaded + +```rust +let mut dog = use_resource(move || async move { + // api request +}); + +match dog() { + Some(dog_info) => rsx! { Dog { dog_info } }, + None => rsx! { "Loading..." }, +} +``` + +# Routing + +All possible routes are defined in a single Rust `enum` that derives `Routable`. Each variant represents a route and is annotated with `#[route("/path")]`. Dynamic Segments can capture parts of the URL path as parameters by using `:name` in the route string. These become fields in the enum variant. + +The `Router {}` component is the entry point that manages rendering the correct component for the current URL. + +You can use the `#[layout(NavBar)]` to create a layout shared between pages and place an `Outlet {}` inside your layout component. The child routes will be rendered in the outlet. + +```rust +#[derive(Routable, Clone, PartialEq)] +enum Route { + #[layout(NavBar)] // This will use NavBar as the layout for all routes + #[route("/")] + Home {}, + #[route("/blog/:id")] // Dynamic segment + BlogPost { id: i32 }, +} + +#[component] +fn NavBar() -> Element { + rsx! { + a { href: "/", "Home" } + Outlet {} // Renders Home or BlogPost + } +} + +#[component] +fn App() -> Element { + rsx! { Router:: {} } +} +``` + +```toml +dioxus = { version = "0.7.0", features = ["router"] } +``` + +# Fullstack + +Fullstack enables server rendering and ipc calls. It uses Cargo features (`server` and a client feature like `web`) to split the code into a server and client binaries. + +```toml +dioxus = { version = "0.7.0", features = ["fullstack"] } +``` + +## Server Functions + +Use the `#[post]` / `#[get]` macros to define an `async` function that will only run on the server. On the server, this macro generates an API endpoint. On the client, it generates a function that makes an HTTP request to that endpoint. + +```rust +#[post("/api/double/:path/&query")] +async fn double_server(number: i32, path: String, query: i32) -> Result { + tokio::time::sleep(std::time::Duration::from_secs(1)).await; + Ok(number * 2) +} +``` + +## Hydration + +Hydration is the process of making a server-rendered HTML page interactive on the client. The server sends the initial HTML, and then the client-side runs, attaches event listeners, and takes control of future rendering. + +### Errors +The initial UI rendered by the component on the client must be identical to the UI rendered on the server. + +* Use the `use_server_future` hook instead of `use_resource`. It runs the future on the server, serializes the result, and sends it to the client, ensuring the client has the data immediately for its first render. +* Any code that relies on browser-specific APIs (like accessing `localStorage`) must be run *after* hydration. Place this code inside a `use_effect` hook. diff --git a/plugins/project-uv/.claude-plugin/plugin.json b/plugins/project-uv/.claude-plugin/plugin.json new file mode 100644 index 0000000..d244462 --- /dev/null +++ b/plugins/project-uv/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "project-uv", + "version": "0.1.0", + "description": "Detects how uv (Astral) is configured in the current Python project and advertises the right invocation patterns for running scripts.", + "author": { + "name": "Gabor Körber", + "email": "gab@g4b.org" + } +} diff --git a/plugins/project-uv/README.md b/plugins/project-uv/README.md new file mode 100644 index 0000000..db64c5e --- /dev/null +++ b/plugins/project-uv/README.md @@ -0,0 +1,18 @@ +# project-uv + +Pilot skill for **context-aware project tooling detection**: when a Python project uses [uv](https://docs.astral.sh/uv/), the agent should discover *how* uv is wired up here (sync model, lockfile presence, script declarations, project layout) before running anything, rather than guessing. + +## Skills + +- **project-uv** — Activates for Python work in repos containing `pyproject.toml`. Tells the agent to probe the project layout via `scripts/probe.py` before suggesting `uv run` / `uv sync` invocations. + +## The bigger idea + +This plugin is also a **pilot for granular activation via flag files**. The long-term plan: a skill activates not just from its description, but from the presence (or absence) of marker files in the repo — `Justfile`, `pyproject.toml`, `uv.lock`, custom flags like `.reliquary/run-uv-with-just`, etc. Combined skills like `run_uv_with_just` would light up only when both signals are present. See `docs/workpad/research/` in the reliquary repo for the open question on glob negation support. + +## Install + +``` +/plugin marketplace add git@git.g4b.org:dirigence/reliquary.git +/plugin install project-uv@reliquary +``` diff --git a/plugins/project-uv/skills/project-uv/SKILL.md b/plugins/project-uv/skills/project-uv/SKILL.md new file mode 100644 index 0000000..7de8cc0 --- /dev/null +++ b/plugins/project-uv/skills/project-uv/SKILL.md @@ -0,0 +1,67 @@ +--- +name: project-uv +description: Use whenever you are about to run, install, or modify Python code in a project whose root contains a `pyproject.toml` — especially before invoking `python`, `pip`, `uv run`, or any test/lint command. Detects how uv is wired up here (project vs script mode, lockfile, declared scripts, src/ layout, tool table) and tells you the right invocation pattern *for this repo* before you guess. Trigger words: "run this script", "install this dependency", "test", "sync", any mention of `uv`, `pip`, `python -m`, or running a `.py` file. +--- + +# project-uv + +The point of this skill is to **stop guessing how to run Python in this project**. `uv` supports several distinct workflows (project-managed, script-with-inline-deps, ad-hoc venv) and the right invocation differs accordingly. Probe first, then run. + +## Activation + +This skill applies when the current project root contains a `pyproject.toml`. If there is no `pyproject.toml`, this skill is not relevant — fall back to whatever Python tooling the user already established. + +## Step 0: Probe the project + +**MANDATORY FIRST STEP** when this skill is invoked for the first time in a conversation. Run the probe script: + +```bash +uv run --no-project python ${CLAUDE_PLUGIN_ROOT}/skills/project-uv/scripts/probe.py +``` + +(Or copy `scripts/probe.py` and run it directly with any available Python — it has no dependencies.) + +The probe prints a short structured report describing: + +- whether `uv` is installed and its version +- the project mode: managed project (`[project]` table) vs PEP 723 script mode vs neither +- whether a `uv.lock` exists and is up to date +- whether `[tool.uv]` is configured, with notable keys +- declared scripts: `[project.scripts]` console entrypoints +- src layout: presence of `src/`, top-level packages +- presence of sibling tooling: `Justfile`, `Makefile`, `mise.toml`, `.python-version` + +Treat the probe output as ground truth for the rest of the conversation. Don't re-probe unless files relevant to the probe have changed. + +## Invocation rules of thumb + +Once you know the project mode, apply these defaults: + +**Managed project (`[project]` table present, optionally with `uv.lock`):** +- Sync first if `uv.lock` is out of date or `.venv` is missing: `uv sync` +- Run anything inside the env via `uv run`, e.g. `uv run pytest`, `uv run python -m mypkg.cli` +- Add deps with `uv add `, not `pip install` +- Declared console scripts are runnable as `uv run ` + +**PEP 723 inline-deps script:** +- Run with `uv run path/to/script.py` — uv will install inline deps in an ephemeral env +- Do not `uv add` to a non-project file; edit the `# /// script` block instead + +**Neither (raw `pyproject.toml` with no `[project]` and no inline deps):** +- The user probably has another build backend or only metadata. Ask before assuming. + +## Composing with other tooling + +If the probe shows a `Justfile` / `Makefile`, **prefer the recipe over the raw uv command** whenever a recipe exists for the task — that's the user's preferred entry point. Only fall through to raw `uv run` when no recipe covers it. + +If the probe shows `mise.toml` and the agent has access to `mise`, defer to mise for tool versions (Python version in particular). + +## What this skill does NOT do + +- It does not install `uv` for the user. If uv is missing, report that and stop. +- It does not modify `pyproject.toml`. Adding/removing deps is a separate, user-driven decision — surface the recommended command, let the user accept. +- It does not pick a Python version. That's `.python-version` / `mise.toml` / `[tool.uv]` territory. + +## Future granularity (pilot note) + +This skill is intentionally narrow. Companion skills like `run-uv-with-just` are planned: they would activate only when both `pyproject.toml` and `Justfile` are present, and would teach the agent the just-recipe vocabulary in this specific repo. The granularity is meant to compose, not duplicate. diff --git a/plugins/project-uv/skills/project-uv/scripts/probe.py b/plugins/project-uv/skills/project-uv/scripts/probe.py new file mode 100644 index 0000000..e3d2113 --- /dev/null +++ b/plugins/project-uv/skills/project-uv/scripts/probe.py @@ -0,0 +1,151 @@ +#!/usr/bin/env python3 +"""Probe a Python project to detect how uv is wired up. + +Run from the project root (or pass --root). Output is a short structured +report intended for an LLM agent to read before suggesting uv commands. + +No third-party dependencies; stdlib only so it can run with `uv run --no-project` +or any system Python. +""" +from __future__ import annotations + +import argparse +import os +import shutil +import subprocess +import sys +from pathlib import Path + +try: + import tomllib # Python 3.11+ +except ModuleNotFoundError: # pragma: no cover + import tomli as tomllib # type: ignore[no-redef] + + +def detect_uv() -> tuple[bool, str | None]: + uv = shutil.which("uv") + if not uv: + return False, None + try: + out = subprocess.run( + [uv, "--version"], capture_output=True, text=True, timeout=5, check=False + ) + return True, out.stdout.strip() or out.stderr.strip() or None + except Exception: + return True, None + + +def load_pyproject(root: Path) -> dict | None: + pp = root / "pyproject.toml" + if not pp.exists(): + return None + try: + return tomllib.loads(pp.read_text(encoding="utf-8")) + except Exception as e: + print(f"WARN: failed to parse pyproject.toml: {e}", file=sys.stderr) + return None + + +def detect_pep723_scripts(root: Path) -> list[str]: + hits: list[str] = [] + for py in root.glob("*.py"): + try: + head = py.read_text(encoding="utf-8", errors="replace")[:2000] + except Exception: + continue + if "# /// script" in head: + hits.append(py.name) + return hits + + +def main() -> int: + ap = argparse.ArgumentParser() + ap.add_argument("--root", default=".", help="project root (default: cwd)") + args = ap.parse_args() + root = Path(args.root).resolve() + + print(f"# project-uv probe") + print(f"root: {root}") + print() + + uv_present, uv_version = detect_uv() + print(f"uv installed: {uv_present}") + if uv_version: + print(f"uv version: {uv_version}") + print() + + pyproject = load_pyproject(root) + has_pyproject = pyproject is not None + print(f"pyproject.toml present: {has_pyproject}") + + if not has_pyproject: + scripts = detect_pep723_scripts(root) + print(f"PEP 723 inline-dep scripts at root: {scripts or 'none'}") + print("mode: no-pyproject (skill does not apply unless inline-dep scripts found)") + return 0 + + assert pyproject is not None + has_project = "project" in pyproject + tool_uv = pyproject.get("tool", {}).get("uv") + scripts_table = pyproject.get("project", {}).get("scripts", {}) if has_project else {} + + print(f"[project] table: {has_project}") + print(f"[tool.uv] table: {tool_uv is not None}") + if tool_uv: + notable = sorted(tool_uv.keys()) + print(f"[tool.uv] keys: {notable}") + print() + + lock = root / "uv.lock" + venv = root / ".venv" + print(f"uv.lock present: {lock.exists()}") + print(f".venv present: {venv.exists()}") + print() + + if scripts_table: + print("declared console scripts ([project.scripts]):") + for name, target in scripts_table.items(): + print(f" {name} -> {target}") + else: + print("declared console scripts: none") + print() + + src = root / "src" + print(f"src/ layout: {src.is_dir()}") + if src.is_dir(): + pkgs = [p.name for p in src.iterdir() if p.is_dir() and (p / "__init__.py").exists()] + print(f"src/ packages: {pkgs or 'none'}") + else: + top_pkgs = [ + p.name for p in root.iterdir() + if p.is_dir() and (p / "__init__.py").exists() and not p.name.startswith(".") + ] + print(f"top-level packages: {top_pkgs or 'none'}") + print() + + siblings = { + "Justfile": (root / "Justfile").exists() or (root / "justfile").exists() or (root / ".justfile").exists(), + "Makefile": (root / "Makefile").exists(), + "mise.toml": (root / "mise.toml").exists() or (root / ".mise.toml").exists(), + ".python-version": (root / ".python-version").exists(), + ".env": (root / ".env").exists(), + } + print("sibling tooling:") + for name, present in siblings.items(): + print(f" {name}: {present}") + print() + + if has_project and lock.exists(): + mode = "managed-project-locked" + elif has_project: + mode = "managed-project-unlocked" + elif tool_uv is not None: + mode = "uv-tool-only" + else: + mode = "metadata-only-or-other-backend" + print(f"mode: {mode}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())