From 6bde2c87835f155bb5930c129a3a6ee868e682f7 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 24 Oct 2026 16:48:26 +0000 Subject: [PATCH] Add read-only Lapis, Facet, and Geode skills Ship them on the existing skills input and pin Nushell from nixpkgs. Every command prints the same JSON envelope. Facet never asks for bodies, and Geode stays on a metadata allowlist. Lapis recent reads mtime_iso or mtime by name. Co-authored-by: Evan Eugene Pincham --- .github/workflows/ci.yml | 1 + README.md | 32 ++- flake.nix | 28 ++- modules/home-manager.nix | 10 +- scripts/check-skill-cli.sh | 438 +++++++++++++++++++++++++++++++++++++ skills-stub/README.md | 13 ++ skills-stub/facet/SKILL.md | 44 ++++ skills-stub/facet/facet.nu | 246 +++++++++++++++++++++ skills-stub/geode/SKILL.md | 46 ++++ skills-stub/geode/geode.nu | 224 +++++++++++++++++++ skills-stub/lapis/SKILL.md | 52 +++++ skills-stub/lapis/lapis.nu | 203 +++++++++++++++++ 12 files changed, 1328 insertions(+), 9 deletions(-) create mode 100755 scripts/check-skill-cli.sh create mode 100644 skills-stub/facet/SKILL.md create mode 100755 skills-stub/facet/facet.nu create mode 100644 skills-stub/geode/SKILL.md create mode 100755 skills-stub/geode/geode.nu create mode 100644 skills-stub/lapis/SKILL.md create mode 100755 skills-stub/lapis/lapis.nu diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a6fcc9d..ed29c88 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -88,6 +88,7 @@ jobs: test "$(nix eval --raw ".#packages.$sys.jev-router.pname")" = jev-router test "$(nix eval --raw ".#packages.$sys.cursor-agent-jev.name")" = cursor-agent-jev test "$(nix eval --raw ".#packages.$sys.grok-build-jev.name")" = grok-build-jev + test -n "$(nix eval --raw ".#packages.$sys.nushell.version")" nix eval --json ".#packages.$sys.omp-pin.meta.platforms" done diff --git a/README.md b/README.md index a8757d3..248db98 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Bezel is the supplement, not the harness. It ships the suite in one Nix flake: s | Piece | What you get | | --- | --- | -| Skills | Flake input `inputs.skills`. Each skill is a directory with `SKILL.md`. Home Manager symlinks that store path to the directory the harness already reads. | +| Skills | Flake input `inputs.skills` (`skills-stub/`). Each skill is a directory with `SKILL.md`. Lapis, Facet, and Geode default to that skill plus the CLI. Home Manager symlinks the store path to the directory the harness already reads. | | Jev | `jev-router` asks Typesafe for one policy decision and prints one JSON verdict. Shadow, the default, logs the verdict and does not block. | | Toolkit | `jev-router --catalog` prints a small tool index. `--schema NAME` prints one JSON Schema. Reading a schema does not allow the tool. `--check` is a shadow diff check. | | Cursor | `cursor-agent-jev` runs the gate, then execs `cursor-agent`. | @@ -99,6 +99,7 @@ The product name is Bezel. The repository is [VirtualMachinist/bezel](https://gi | **`jev-router`** | Node router. Asks Typesafe for a Choice and prints a JSON verdict. Loop-stop (`continue` / `stop` / `escalate`), `jev-router --check` for a shadow diff check, shadow permission catalogs, and a small tool catalog (`--catalog`, `--schema NAME`). | | **`cursor-agent-jev`** | Runs `jev-router`, then execs `cursor-agent` (`cursor-agent` must already be on `PATH`). Shadow never blocks. Active honors continue and `gate: auto` only. `--catalog` and `--schema` print and do not exec. | | **`grok-build-jev`** | Grok Build PreToolUse adapter. Calls `jev-router` and prints `defer` or `deny`. Does not install a host hook. | +| **`nushell`** | Interpreter for the Lapis, Facet, and Geode skill bodies. The version is the nixpkgs pin in `flake.lock`. | `packages.default` is `bezel`. @@ -185,7 +186,32 @@ How to run: [docs/GROK-BUILD.md](docs/GROK-BUILD.md). ## Skills -Skills are a flake input, and that input is the only skills tree Bezel installs. This repo ships `skills-stub` so the input is a valid skills tree (`*/SKILL.md`) on day one. The stub includes `bootstrap` and a shadow `check` skill (`jev-router --check`). Home Manager symlinks that store path to `~/.config/omp/agent/skills`. When you have a skills repo, change `inputs.skills.url` and the lock. Do not copy a second `skills/` tree into this overlay. +Skills are a flake input, and that input is the only skills tree Bezel installs. This repo ships them in `skills-stub/` (`inputs.skills`). Home Manager symlinks that store path to `~/.config/omp/agent/skills`. There is no second repo-root `skills/` tree. When you have a skills repo, change `inputs.skills.url` and the lock. + +The tree includes `bootstrap`, the shadow `check` skill (`jev-router --check`), and `laws`. It also includes shared read-only skills for Lapis, Facet, and Geode. + +### Agent use: skills + CLI first, MCP still shipped + +The default way for an agent to use Lapis, Facet, or Geode is the bundled skill. In this repo that directory is `skills-stub//`. After install it is `~/.config/omp/agent/skills//`. A short `SKILL.md` is what the harness reads to decide when to use it, plus a Nushell body (`nu .nu`) that calls the CLI with JSON output. Every command prints the same envelope: `{ ok, command, exit, data, error }`. + +The MCP server for each tool (`lapis mcp`, `facet mcp`, `geode mcp`) stays supported and works the same as that tool ships it. Bezel does not disable MCP. + +Why the skill is the default: + +- **Context.** An MCP server adds every tool's name, description and input schema to the model's context, often on every request, whether or not the tools are used. Many harnesses can only turn a whole server on or off. A skill costs a few dozen tokens of description until it is used. +- **Determinism.** The skill body is fixed code over a versioned JSON contract, so results are the same each time. +- **Small models.** Local models with short context windows feel the schema cost most. + +Use the MCP server when your harness defers or filters MCP tool schemas (loading them only on demand, or letting you enable single tools), or when the client has no shell. + +`programs.bezel.enable` puts the pinned Nushell on `PATH` and links the whole tree for omp. Install one skill into another harness by copying or linking `skills-stub//` into that harness's skills directory (for example `~/.agents/skills/` or `~/.claude/skills/`). + +```sh +nix build .#nushell +nu skills-stub/lapis/lapis.nu status +``` + +These three scripts are read-only. Facet never requests history bodies, blobs, `diff --bodies`, or `request run`. Geode is metadata only and refuses every other command. ## Platforms @@ -210,7 +236,7 @@ If a later release drops a platform build, `packages/omp-pin.nix` **throws** for - Jev defaults to shadow. `jev-router --check` is the shadow diff check. Empty findings are not approval. Loop-stop is shadow-first. Active `stop` and `escalate` do not exec. - The tool catalog is a small always-on index of the existing policy ids. Full schema is `jev-router --schema NAME` and is not an allow. Permission catalogs stay shadow. - `grok-build-jev` adapts those controls for Grok Build. Default modes stay shadow. The harness does not install a host hook. -- Skills ship as `skills-stub` until you change the input URL. +- Skills ship as `skills-stub`, the flake's only skills tree. Lapis, Facet, and Geode are read-only skills there: skill plus CLI is the default, and MCP remains supported. Nushell is pinned by the nixpkgs lock. - Nix packaging stays. The router stays JavaScript. ## Contributing diff --git a/flake.nix b/flake.nix index a2bd261..546d1e9 100644 --- a/flake.nix +++ b/flake.nix @@ -7,8 +7,8 @@ # missed this slice) on the last Darwin-x64-supporting pin — not a skip-as-green. nixpkgs-darwin-x64.url = "github:NixOS/nixpkgs/nixpkgs-26.05-darwin"; - # Sole skills input. Path stub until you point this at a skills repository. - # Do not add a second repo-root skills/ product tree. + # Sole skills input. Lapis, Facet, and Geode live in this tree with the + # Bezel stub skills. Do not add a second repo-root skills/ product tree. skills = { url = "path:./skills-stub"; flake = false; @@ -33,6 +33,14 @@ "x86_64-linux" ]; + # Evaluated by the skills-cli check. A repo-root skills/ directory would + # be a second product tree next to inputs.skills (skills-stub). + skillsTreeOk = + if builtins.pathExists ./skills then + throw "Do not add a repo-root skills/ tree. Ship Lapis, Facet, and Geode through inputs.skills (skills-stub)." + else + "skills-stub"; + forAllSystems = f: lib.genAttrs systems (system: f system); nixpkgsFor = system: if system == "x86_64-darwin" then nixpkgs-darwin-x64 else nixpkgs; @@ -81,6 +89,8 @@ grok-build-jev omp-runtime omp-pin + # Skill interpreter. Pinned by the nixpkgs lock, not a second input. + nushell ; default = pkgs.bezel; } @@ -667,6 +677,20 @@ echo ok >"$out" ''; + + # Lapis, Facet, and Geode skill bodies: one JSON envelope, read-only. + skills-cli = pkgs.runCommand "skills-cli" { + nativeBuildInputs = [ + pkgs.nushell + pkgs.python3 + pkgs.bash + ]; + } '' + set -eu + test "${skillsTreeOk}" = skills-stub + bash ${./scripts/check-skill-cli.sh} ${./skills-stub} + echo ok >"$out" + ''; } ); }; diff --git a/modules/home-manager.nix b/modules/home-manager.nix index 740e70b..c2ecad1 100644 --- a/modules/home-manager.nix +++ b/modules/home-manager.nix @@ -7,7 +7,8 @@ }: # Skills flake input is the sole SoT. This module only symlinks that store -# path. Do not vendor a second skills/ tree in Bezel. +# path. Do not vendor a second skills/ tree in Bezel. Nushell is on PATH so +# the Lapis, Facet, and Geode skill bodies can run. # `programs.omapi` is deprecated. It renames to `programs.bezel`. { @@ -30,9 +31,10 @@ default = lib.optional (pkgs ? jev-router) pkgs.jev-router ++ lib.optional (pkgs ? cursor-agent-jev) pkgs.cursor-agent-jev - ++ lib.optional (pkgs ? grok-build-jev) pkgs.grok-build-jev; - defaultText = lib.literalExpression "[ pkgs.jev-router pkgs.cursor-agent-jev pkgs.grok-build-jev ]"; - description = "Additional Bezel packages on PATH (jev-router, cursor-agent-jev, grok-build-jev)."; + ++ lib.optional (pkgs ? grok-build-jev) pkgs.grok-build-jev + ++ lib.optional (pkgs ? nushell) pkgs.nushell; + defaultText = lib.literalExpression "[ pkgs.jev-router pkgs.cursor-agent-jev pkgs.grok-build-jev pkgs.nushell ]"; + description = "Additional Bezel packages on PATH (jev-router, cursor-agent-jev, grok-build-jev, and the pinned Nushell used by skills)."; }; skillsSource = lib.mkOption { diff --git a/scripts/check-skill-cli.sh b/scripts/check-skill-cli.sh new file mode 100755 index 0000000..26e6ca2 --- /dev/null +++ b/scripts/check-skill-cli.sh @@ -0,0 +1,438 @@ +#!/usr/bin/env bash +# Exercise the Lapis, Facet, and Geode skill bodies against fake CLIs. +# The fakes record argv. Refused commands must not reach them. +set -euo pipefail + +script_dir=$(CDPATH= cd -- "$(dirname "$0")" && pwd) +root=$(CDPATH= cd -- "$script_dir/.." && pwd) +skills=${1:-$root/skills-stub} +nu=${NU:-nu} + +fail() { + printf 'check-skill-cli: %s\n' "$*" >&2 + exit 1 +} + +if [[ -f "$root/flake.nix" && -d "$root/skills" ]]; then + fail "repo-root skills/ is a second product tree; ship skills through skills-stub/" +fi + +command -v "$nu" >/dev/null || fail "nushell (nu) is not on PATH" +command -v python3 >/dev/null || fail "python3 is not on PATH" + +for f in \ + lapis/SKILL.md lapis/lapis.nu \ + facet/SKILL.md facet/facet.nu \ + geode/SKILL.md geode/geode.nu +do + [[ -f "$skills/$f" ]] || fail "missing $skills/$f" +done + +for skill in lapis facet geode; do + grep -q '{ ok, command, exit, data, error }' "$skills/$skill/SKILL.md" \ + || fail "$skill SKILL.md does not document the shared envelope" + grep -q "nu $skill.nu" "$skills/$skill/SKILL.md" \ + || fail "$skill SKILL.md does not call $skill.nu" +done + +if grep -nE '/(Users|home)/|localhost|@[A-Za-z0-9._-]+\.(com|dev|net)' \ + "$skills/lapis/SKILL.md" "$skills/lapis/lapis.nu" \ + "$skills/facet/SKILL.md" "$skills/facet/facet.nu" \ + "$skills/geode/SKILL.md" "$skills/geode/geode.nu" +then + fail "skill files contain a private-looking path, host, or address" +fi + +for word in \ + '"list"' '"verify"' '"vault recipients"' '"snapshot ls"' '"policy show"' \ + '"policy check"' '"audit verify"' '"custody status"' '"keyring list"' +do + grep -q "$word" "$skills/geode/geode.nu" || fail "geode allowlist missing $word" +done + +[[ "$(grep -c '\^lapis' "$skills/lapis/lapis.nu")" -eq 1 ]] || fail "lapis.nu should call lapis once" +[[ "$(grep -c '\^facet' "$skills/facet/facet.nu")" -eq 1 ]] || fail "facet.nu should call facet once" +[[ "$(grep -c '\^geode' "$skills/geode/geode.nu")" -eq 1 ]] || fail "geode.nu should call geode once" +grep -q -- '--bodies' "$skills/facet/facet.nu" || fail "facet.nu does not mention --bodies" +grep -q 'request run' "$skills/facet/facet.nu" || fail "facet.nu does not mention request run" + +work=$(mktemp -d) +trap 'rm -rf "$work"' EXIT +export HOME="$work/home" +export XDG_CONFIG_HOME="$work/xdg" +mkdir -p "$HOME" "$XDG_CONFIG_HOME" "$work/bin" +export FAKE_LOG="$work/log" +: >"$FAKE_LOG" + +cat >"$work/bin/fake-tool.py" <<'PY' +#!/usr/bin/env python3 +import os +import sys + +name = os.environ.get("FAKE_TOOL") or os.path.basename(sys.argv[0]) +args = sys.argv[1:] +log = os.environ.get("FAKE_LOG", "") +if log: + with open(log, "a", encoding="utf-8") as fh: + fh.write(name + "\t" + "\t".join(args) + "\n") + +if name == "lapis": + body = ( + '{"data":{"hits":[{"path":"notes/a.md","title":"Alpha","body":"do-not-leak-body"}]}}' + ) + if "list" in args: + body = '{"data":[{"path":"projects/a.md","title":"A"},{"path":"notes/b.md","title":"B"}]}' + elif "analytics" in args: + # Lapis 0.4.2: domain and priority sit before mtime_iso. A positional + # read would report the domain as mtime. + body = ( + '{"data":{"rows":[' + '{"path":"notes/a.md","title":"Alpha","domain":"notes","priority":1,"mtime":111,"mtime_iso":"2024-01-02T00:00:00Z"},' + '{"path":"notes/b.md","title":"Beta","domain":"notes","priority":2,"mtime":222,"mtime_iso":"2024-01-01T00:00:00Z"}' + ']}}' + ) + elif "read" in args: + body = '{"data":{"hal":{"title":"Alpha"},"body":"hello"}}' + elif "vault" in args: + body = '{"data":{"root":"vault"}}' + elif "doctor" in args: + body = '{"data":{"index":"up"}}' +elif name == "facet": + if args[:2] == ["env", "list"]: + body = '{"variables":[{"name":"TOKEN","value":"super-secret-value","note":"kept"}],"API_TOKEN":"super-secret-value"}' + elif args[:1] == ["diff"]: + body = '{"left":"aaa","right":"bbb"}' + else: + body = '{"entries":[{"id":"1","status":200}]}' +elif name == "geode": + body = '{"entries":[{"name":"alpha","size":1}]}' +else: + body = "{}" + +if "FAKE_STDOUT" in os.environ: + body = os.environ["FAKE_STDOUT"] +sys.stdout.write(body) +if body and not body.endswith("\n"): + sys.stdout.write("\n") +sys.stderr.write(os.environ.get("FAKE_STDERR", "")) +raise SystemExit(int(os.environ.get("FAKE_EXIT", "0"))) +PY +chmod +x "$work/bin/fake-tool.py" +# /bin/sh wrappers so the fakes run in a Nix sandbox without /usr/bin/env. +for tool in lapis facet geode; do + cat >"$work/bin/$tool" <"$FAKE_LOG" +} + +run() { + local out=$1 + shift + : >"$FAKE_LOG" + set +e + "$nu" "$@" >"$out" 2>"$out.err" + local rc=$? + set -e + if [[ $rc -ne 0 ]]; then + printf 'command failed (%s):' "$rc" >&2 + printf ' %q' "$@" >&2 + printf '\n' >&2 + cat "$out.err" >&2 || true + cat "$out" >&2 || true + exit 1 + fi + if [[ -s "$out.err" ]]; then + echo "stderr not empty for: $*" >&2 + cat "$out.err" >&2 + exit 1 + fi + python3 - "$out" <<'PY' +import json, sys +text = open(sys.argv[1], encoding="utf-8").read().strip() +data = json.loads(text) +keys = sorted(data) +if keys != ["command", "data", "error", "exit", "ok"]: + raise SystemExit(f"envelope keys {keys}: {text}") +if not isinstance(data["ok"], bool): + raise SystemExit("ok is not a bool") +if not isinstance(data["command"], str): + raise SystemExit("command is not a string") +if isinstance(data["exit"], bool) or not isinstance(data["exit"], int): + raise SystemExit("exit is not an int") +if data["ok"]: + if data["error"] is not None: + raise SystemExit("ok row has error") +else: + if data["data"] is not None: + raise SystemExit("error row has data") + if not isinstance(data["error"], str) or not data["error"]: + raise SystemExit("error row missing error") +PY +} + +expect() { + python3 - "$1" "$2" "$3" "$4" <<'PY' +import json, sys +data = json.loads(open(sys.argv[1], encoding="utf-8").read()) +ok = sys.argv[2] == "true" +command, code = sys.argv[3], int(sys.argv[4]) +if data["ok"] != ok or data["command"] != command or data["exit"] != code: + raise SystemExit( + f"want ok={ok} command={command} exit={code} got {data}" + ) +PY +} + +log_has() { + grep -F -- "$1" "$FAKE_LOG" >/dev/null || fail "log missing [$1]: $(cat "$FAKE_LOG")" +} + +log_lacks() { + if grep -F -- "$1" "$FAKE_LOG" >/dev/null; then + fail "log should not contain [$1]: $(cat "$FAKE_LOG")" + fi +} + +log_empty() { + if [[ -s "$FAKE_LOG" ]]; then + fail "expected no CLI call, log was: $(cat "$FAKE_LOG")" + fi +} + +unset LAPIS_VAULT || true +unset GEODE_VAULT || true +clear_fake + +# Lapis: read-only envelope, search drops bodies, vault flag order. +run "$work/out" "$skills/lapis/lapis.nu" search "phrase" --limit 5 --domain notes +expect "$work/out" true search 0 +python3 - "$work/out" <<'PY' +import json, sys +data = json.loads(open(sys.argv[1], encoding="utf-8").read()) +hits = data["data"] +if hits != [{"path": "notes/a.md", "title": "Alpha"}]: + raise SystemExit(hits) +PY +log_has $'lapis\t--json\tsearch\tphrase\t-n\t5\t--domain\tnotes' +log_lacks "--vault" +log_lacks "do-not-leak-body" +if grep -q 'do-not-leak-body' "$work/out"; then + fail "search leaked a hit body" +fi + +export LAPIS_VAULT="$work/from-env" +run "$work/out" "$skills/lapis/lapis.nu" status --vault "$work/from-flag" +expect "$work/out" true status 0 +log_has $'--vault\t'"$work/from-flag" +log_lacks "$work/from-env" +unset LAPIS_VAULT + +run "$work/out" "$skills/lapis/lapis.nu" list --prefix projects/ +expect "$work/out" true list 0 +python3 - "$work/out" <<'PY' +import json, sys +data = json.loads(open(sys.argv[1], encoding="utf-8").read()) +paths = [row["path"] for row in data["data"]] +if paths != ["projects/a.md"]: + raise SystemExit(paths) +PY + +run "$work/out" "$skills/lapis/lapis.nu" recent --limit 1 +expect "$work/out" true recent 0 +python3 - "$work/out" <<'PY' +import json, sys +data = json.loads(open(sys.argv[1], encoding="utf-8").read()) +want = [{"path": "notes/a.md", "title": "Alpha", "mtime": "2024-01-02T00:00:00Z"}] +if data["data"] != want: + raise SystemExit(data["data"]) +PY + +export FAKE_STDOUT='{"data":{"rows":[{"path":"notes/a.md","title":"Alpha","mtime":1},{"path":"notes/b.md","title":"Beta","mtime":2}]}}' +run "$work/out" "$skills/lapis/lapis.nu" recent --limit 1 +expect "$work/out" true recent 0 +python3 - "$work/out" <<'PY' +import json, sys +data = json.loads(open(sys.argv[1], encoding="utf-8").read()) +if data["data"] != [{"path": "notes/a.md", "title": "Alpha", "mtime": 1}]: + raise SystemExit(data["data"]) +PY +clear_fake + +export FAKE_EXIT=2 FAKE_STDERR="index down" FAKE_STDOUT="" +run "$work/out" "$skills/lapis/lapis.nu" doctor +expect "$work/out" false doctor 2 +python3 - "$work/out" <<'PY' +import json, sys +err = json.loads(open(sys.argv[1], encoding="utf-8").read())["error"] +if "index down" not in err: + raise SystemExit(err) +PY +clear_fake + +run "$work/out" "$skills/lapis/lapis.nu" create "note" +expect "$work/out" false create 2 +log_empty + +run "$work/out" "$skills/lapis/lapis.nu" +expect "$work/out" false "" 2 +log_empty + +# Facet: bodies, blob, and request run never reach the CLI. Env drops values. +run "$work/out" "$skills/facet/facet.nu" history coll --limit 2 --status 200 +expect "$work/out" true history 0 +log_has $'facet\thistory\tcoll\t--limit\t2\t--status\t200\t--json' +log_lacks "--bodies" +log_lacks $'\t--id' + +run "$work/out" "$skills/facet/facet.nu" history --bodies +expect "$work/out" false history 2 +log_empty + +run "$work/out" "$skills/facet/facet.nu" history --id 9 +expect "$work/out" false history 2 +log_empty + +run "$work/out" "$skills/facet/facet.nu" blob 9 +expect "$work/out" false blob 2 +log_empty + +run "$work/out" "$skills/facet/facet.nu" request run --dry-run +expect "$work/out" false request 2 +log_empty + +run "$work/out" "$skills/facet/facet.nu" replay 9 +expect "$work/out" false replay 2 +log_empty + +export FAKE_EXIT=1 FAKE_STDOUT='{"left":"aaa","right":"bbb"}' +run "$work/out" "$skills/facet/facet.nu" diff idA idB +expect "$work/out" true diff 1 +python3 - "$work/out" <<'PY' +import json, sys +data = json.loads(open(sys.argv[1], encoding="utf-8").read())["data"] +if data.get("same") is not False or data.get("left") != "aaa": + raise SystemExit(data) +PY +log_has $'facet\tdiff\tidA\tidB\t--json' +log_lacks "--bodies" +clear_fake + +run "$work/out" "$skills/facet/facet.nu" diff idA idB --bodies +expect "$work/out" false diff 2 +log_empty + +run "$work/out" "$skills/facet/facet.nu" env coll --environment dev +expect "$work/out" true env 0 +python3 - "$work/out" <<'PY' +import json, sys +raw = open(sys.argv[1], encoding="utf-8").read() +if "super-secret-value" in raw: + raise SystemExit(raw) +data = json.loads(raw)["data"] +if data["variables"] != [{"name": "TOKEN", "note": "kept"}]: + raise SystemExit(data["variables"]) +if data.get("API_TOKEN") is not None: + raise SystemExit(data["API_TOKEN"]) +if "API_TOKEN" not in data: + raise SystemExit(data) +PY +log_has $'env\tlist\tcoll\t--environment\tdev\t--json' + +run "$work/out" "$skills/facet/facet.nu" env set TOKEN +expect "$work/out" false env 2 +log_empty + +run "$work/out" "$skills/facet/facet.nu" session start +expect "$work/out" false session 2 +log_empty + +run "$work/out" "$skills/facet/facet.nu" sessions --open +expect "$work/out" true sessions 0 +log_has $'session\tlist\t--open\t--json' + +# Geode: metadata allowlist. Missing vault and every other command stay local. +run "$work/out" "$skills/geode/geode.nu" list +expect "$work/out" false list 2 +log_empty + +export GEODE_VAULT="$work/vault" +run "$work/out" "$skills/geode/geode.nu" list +expect "$work/out" true list 0 +log_has $'geode\t--output\tjson\tlist\t'"$work/vault" + +run "$work/out" "$skills/geode/geode.nu" verify +expect "$work/out" true verify 0 +log_has $'verify\t'"$work/vault"$'\t--cheap' +log_lacks "--sample" + +run "$work/out" "$skills/geode/geode.nu" verify --sample 0.05 +expect "$work/out" true verify 0 +log_has $'--sample\t0.05' +log_lacks "--cheap" + +run "$work/out" "$skills/geode/geode.nu" verify --sample -1 +expect "$work/out" false verify 2 +log_empty + +export FAKE_EXIT=3 FAKE_STDOUT='{"allow":false}' +run "$work/out" "$skills/geode/geode.nu" can alice read notes/a +expect "$work/out" true can 3 +python3 - "$work/out" <<'PY' +import json, sys +data = json.loads(open(sys.argv[1], encoding="utf-8").read()) +if data["data"] != {"allow": False}: + raise SystemExit(data) +PY +log_has $'policy\tcheck\t'"$work/vault"$'\talice\tread\tnotes/a' +clear_fake +export GEODE_VAULT="$work/vault" + +for args in \ + "cat secret" \ + "open secret" \ + "mount secret" \ + "run secret" \ + "agent secret" \ + "keygen" \ + "vault init" \ + "policy set" \ + "custody unlock" \ + "keyring add" \ + "git unlock" +do + # shellcheck disable=SC2086 + run "$work/out" "$skills/geode/geode.nu" $args + python3 - "$work/out" <<'PY' +import json, sys +data = json.loads(open(sys.argv[1], encoding="utf-8").read()) +if data["ok"] or data["exit"] != 2 or not str(data["error"]).startswith("refused:"): + raise SystemExit(data) +PY + log_empty +done + +# A missing binary is still the envelope, not a stack trace. +# Drop the fake CLI directory and keep nu, python3, and coreutils. +export PATH="${PATH#"$work/bin:"}" +unset LAPIS_VAULT || true +run "$work/out" "$skills/lapis/lapis.nu" status +expect "$work/out" false status 127 +python3 - "$work/out" <<'PY' +import json, sys +err = json.loads(open(sys.argv[1], encoding="utf-8").read())["error"] +if "lapis:" not in err: + raise SystemExit(err) +if "/home/" in err or "/Users/" in err: + raise SystemExit(err) +PY + +echo "check-skill-cli: ok" diff --git a/skills-stub/README.md b/skills-stub/README.md index 8c50887..8523f9d 100644 --- a/skills-stub/README.md +++ b/skills-stub/README.md @@ -18,5 +18,18 @@ Shipped skills: | `bootstrap` | Placeholder so the input is a valid skills directory (`*/SKILL.md`) | | `check` | Shadow Jev-first diff check (`jev-router --check`). Empty findings ≠ approval | | `laws` | Bend2 `LAWS.bend` for the bridle. The harness loads it. Bezel does not become the harness | +| `lapis` | Read-only vault search and read through `lapis --json` (`lapis.nu`) | +| `facet` | Read-only request history through `facet … --json` (`facet.nu`). No bodies, blobs, or `request run` | +| `geode` | Metadata-only custody status through `geode --output json` (`geode.nu`). Anything else is refused | + +`lapis`, `facet`, and `geode` are the default agent interface for those tools. +Each directory is a short `SKILL.md` plus one Nushell script. Every command +prints the same JSON envelope: `{ ok, command, exit, data, error }`. The +Nushell that runs them is the one pinned by this flake's nixpkgs lock. MCP +servers for those tools stay supported; this tree does not turn them off. + +Copy or link one directory into another harness's skills folder +(`~/.agents/skills/` or `~/.claude/skills/`). With Home Manager, the whole +input is already linked at `~/.config/omp/agent/skills`. See [docs/SPIKE-stanley.md](../docs/SPIKE-stanley.md). diff --git a/skills-stub/facet/SKILL.md b/skills-stub/facet/SKILL.md new file mode 100644 index 0000000..6932a0b --- /dev/null +++ b/skills-stub/facet/SKILL.md @@ -0,0 +1,44 @@ +--- +name: facet +description: > + Inspect Facet HTTP request history, sessions, pins, and stored-value + metadata through the facet CLI. Use when a task needs to know what requests + ran, their status and timing, or to compare two runs. Prefer this skill over + the facet MCP server: it adds no tool schemas to context. The MCP server + remains available. +--- + +# facet — request history skill + +Read-only. The body is the fixed script `facet.nu` next to this file. Every +wrapped command appends `--json` (facet expects it after the subcommand). +Do not reimplement the calls. + +## Commands + +```bash +nu facet.nu history [path] [--limit 20] [--request sel] [--status 200] [--session id] +nu facet.nu last [path] [--request sel] +nu facet.nu sessions [--open] +nu facet.nu session +nu facet.nu pins [path] +nu facet.nu env [path] [--environment e] # names only, never values +nu facet.nu diff [path] # hashes only +nu facet.nu doctor +``` + +Each command prints one JSON envelope: `{ ok, command, exit, data, error }`. +`diff` uses `exit` 1 to mean the runs differ (`data.same` is false); that is +still `ok: true`. + +## Not wrapped, on purpose + +`facet.nu` refuses these and does not call facet: + +- `history --bodies`, `history --id`, `blob`, `diff --bodies`: these can print + recorded request or response bodies and headers, which may carry tokens. +- `request run`, including `request run --dry-run`: a preview resolves + variables, so it can show a hydrated secret. +- `replay`, `env set`, `env delete`, `pin`, `gc --yes`, + `session start/end`: these change state or send traffic. Run them only when + a human has explicitly asked, and never pass a secret value on the command line. diff --git a/skills-stub/facet/facet.nu b/skills-stub/facet/facet.nu new file mode 100755 index 0000000..9f48255 --- /dev/null +++ b/skills-stub/facet/facet.nu @@ -0,0 +1,246 @@ +#!/usr/bin/env nu +# Fixed read-only body for the facet skill. Wraps `facet` with `--json` +# after the subcommand. +# stdout is one JSON envelope: {ok, command, exit, data, error} +# Never calls history --bodies, history --id, blob, diff --bodies, or request run. + +const BLOCKED = ["--bodies" "--id" "blob" "--dry-run"] +const OWN_FLAGS = ["--limit" "--request" "--status" "--session" "--open" "--environment"] + +def clip-error [stderr: string, stdout: string] { + let joined = ([$stderr $stdout] | str join " " | str trim) + if ($joined | is-empty) { + "command failed" + } else { + ($joined | lines | first | str substring 0..399) + } +} + +def ok-row [command: string, exit: int, data: any] { + { ok: true, command: $command, exit: $exit, data: $data, error: null } +} + +def err-row [command: string, exit: int, error: string] { + { ok: false, command: $command, exit: $exit, data: null, error: ($error | str substring 0..399) } +} + +def as-text [raw: any] { + let d = ($raw | describe) + if $d == "string" { + $raw + } else { + try { $raw | decode utf-8 } catch { "" } + } +} + +def parse-json [text: string] { + let t = ($text | str trim) + if ($t | is-empty) { + error make { msg: "empty json" } + } + $t | from json --strict +} + +def opt [flag: string, v: string] { + if $v == "" { [] } else { [$flag $v] } +} + +def pos [v: string] { + if $v == "" { [] } else { [$v] } +} + +def blocked-argv [args: list] { + let joined = ($args | str join " ") + ($args | any {|a| $a in $BLOCKED }) or ($joined | str contains "request run") or ($joined | str contains "request --dry-run") +} + +def ascii-lower [text: string] { + let pairs = [ + [A a] [B b] [C c] [D d] [E e] [F f] [G g] [H h] [I i] [J j] + [K k] [L l] [M m] [N n] [O o] [P p] [Q q] [R r] [S s] [T t] + [U u] [V v] [W w] [X x] [Y y] [Z z] + ] + $pairs | reduce --fold $text {|p, acc| + $acc | str replace --all ($p | get 0) ($p | get 1) + } +} + +def secret-key [name: string] { + let lowered = (ascii-lower $name) + $lowered in [ + value values secret token password authorization + header headers body bodies raw content cookie cookies + request_body response_body + ] +} + +def env-name-key [name: string] { + let chars = ($name | split chars) + if ($chars | is-empty) { + false + } else { + $chars | all {|c| $c =~ "[A-Z0-9_]" } + } +} + +def redact [v: any] { + let d = ($v | describe) + if ($d | str starts-with "list") or ($d | str starts-with "table") { + $v | each {|item| redact $item } + } else if ($d | str starts-with "record") { + let cols = ($v | columns | where {|c| not (secret-key $c) }) + if ($cols | is-empty) { + {} + } else { + $cols | reduce --fold {} {|c, acc| + let val = ($v | get $c) + let vd = ($val | describe) + if (env-name-key $c) and $vd == "string" { + $acc | upsert $c null + } else { + $acc | upsert $c (redact $val) + } + } + } + } else { + $v + } +} + +def with-same [parsed: any, same: bool] { + let d = ($parsed | describe) + if ($d | str starts-with "record") { + $parsed | merge { same: $same } + } else { + { same: $same, report: $parsed } + } +} + +def run-facet [command: string, args: list, ok_codes: list = [0], redact_values: bool = false, embed_same: bool = false] { + let stray = ($args | where {|a| ($a | str starts-with "-") and (not ($a in $OWN_FLAGS)) }) + if (blocked-argv $args) or (not ($stray | is-empty)) { + err-row $command 2 "refused: history bodies, blob, diff --bodies, and request run are not available from this skill" + } else { + let r = (try { + ^facet ...$args --json | complete + } catch {|e| + { stdout: "", stderr: $"facet: ($e.msg)", exit_code: 127 } + }) + let stdout = (as-text $r.stdout) + let stderr = (as-text $r.stderr) + if not ($r.exit_code in $ok_codes) { + err-row $command $r.exit_code (clip-error $stderr $stdout) + } else { + let parsed = (try { { ok: true, value: (parse-json $stdout) } } catch {|e| { ok: false, value: $e.msg } }) + if not $parsed.ok { + err-row $command 1 $"invalid json: ($parsed.value)" + } else { + let data = if $redact_values { redact $parsed.value } else { $parsed.value } + let out = if $embed_same { with-same $data ($r.exit_code == 0) } else { $data } + ok-row $command $r.exit_code $out + } + } + } +} + +def "main history" [ + path: string = "", + --limit: int = 20, + --request: string = "", + --status: string = "", + --session: string = "", + --bodies, + --id: string = "", + ...rest: string, +] { + if $bodies or $id != "" or not ($rest | is-empty) or (blocked-argv (pos $path)) { + err-row "history" 2 "refused: history bodies are not available from this skill" | to json --raw + } else if $limit < 1 { + err-row "history" 2 "limit must be >= 1" | to json --raw + } else { + let args = ( + ["history"] + ++ (pos $path) + ++ ["--limit" ($limit | into string)] + ++ (opt "--request" $request) + ++ (opt "--status" $status) + ++ (opt "--session" $session) + ) + run-facet "history" $args | to json --raw + } +} + +def "main last" [path: string = "", --request: string = "", --bodies, ...rest: string] { + if $bodies or not ($rest | is-empty) or (blocked-argv (pos $path)) { + err-row "last" 2 "refused: history bodies are not available from this skill" | to json --raw + } else { + run-facet "last" (["last"] ++ (pos $path) ++ (opt "--request" $request)) | to json --raw + } +} + +def "main sessions" [--open, ...rest: string] { + if not ($rest | is-empty) { + err-row "sessions" 2 "refused: facet skill is read-only" | to json --raw + } else { + let args = (["session" "list"] ++ (if $open { ["--open"] } else { [] })) + run-facet "sessions" $args | to json --raw + } +} + +def "main session" [id: string, ...rest: string] { + if not ($rest | is-empty) or ($id in ["start" "end" "delete" "rm"]) { + err-row "session" 2 "refused: session start/end is not available from this skill" | to json --raw + } else { + run-facet "session" ["session" "show" $id] | to json --raw + } +} + +def "main pins" [path: string = "", ...rest: string] { + if not ($rest | is-empty) or (blocked-argv (pos $path)) { + err-row "pins" 2 "refused: facet skill is read-only" | to json --raw + } else { + run-facet "pins" (["pin" "list"] ++ (pos $path)) | to json --raw + } +} + +def "main env" [path: string = "", --environment: string = "", ...rest: string] { + if not ($rest | is-empty) or ($path in ["set" "delete" "unset" "get" "add" "rm"]) { + err-row "env" 2 "refused: env values and env writes are not available from this skill" | to json --raw + } else { + run-facet "env" (["env" "list"] ++ (pos $path) ++ (opt "--environment" $environment)) [0] true | to json --raw + } +} + +def "main diff" [a: string, b: string, path: string = "", --bodies, ...rest: string] { + if $bodies or not ($rest | is-empty) or (blocked-argv [$a $b $path]) { + err-row "diff" 2 "refused: diff --bodies is not available from this skill" | to json --raw + } else { + # exit 1 means the runs differ; that is a result, not a failure + run-facet "diff" (["diff" $a $b] ++ (pos $path)) [0 1] false true | to json --raw + } +} + +def "main doctor" [...rest: string] { + if not ($rest | is-empty) { + err-row "doctor" 2 "refused: facet skill is read-only" | to json --raw + } else { + run-facet "doctor" ["doctor"] | to json --raw + } +} + +def "main blob" [...args: string] { + err-row "blob" 2 "refused: blob is not available from this skill" | to json --raw +} + +def "main request" [--dry-run, ...args: string] { + err-row "request" 2 "refused: request run is not available from this skill" | to json --raw +} + +def "main replay" [...args: string] { + err-row "replay" 2 "refused: replay is not available from this skill" | to json --raw +} + +def main [...args: string] { + let command = ($args | first | default "") + err-row $command 2 "refused: facet skill is read-only" | to json --raw +} diff --git a/skills-stub/geode/SKILL.md b/skills-stub/geode/SKILL.md new file mode 100644 index 0000000..7046b48 --- /dev/null +++ b/skills-stub/geode/SKILL.md @@ -0,0 +1,46 @@ +--- +name: geode +description: > + Check Geode vault health and metadata through the geode CLI: entry names, + integrity, recipients, snapshots, policy, audit chain, custody status. Use + when a task asks whether a vault is intact, who can open it, or what it + holds by name. This skill never reads or prints secret values. Prefer it + over the geode MCP server. The MCP server remains available. +--- + +# geode — custody status skill (metadata only) + +The body is the fixed script `geode.nu` next to this file. Every wrapped +command uses `geode --output json`. The vault path comes from the argument or +`$GEODE_VAULT`; the identity key from `$GEODE_KEY_FILE` as usual. The script +never puts the key on the command line. Do not reimplement the calls. + +## Commands + +```bash +nu geode.nu list [vault] [prefix] # entry names and sizes, no contents +nu geode.nu verify [vault] [--sample 0.05] # default --cheap +nu geode.nu recipients [vault] # recipient types and key ids (public) +nu geode.nu snapshots [vault] +nu geode.nu policy [vault] +nu geode.nu can [vault] # dry run; deny is exit 3 +nu geode.nu audit +nu geode.nu custody +nu geode.nu keyring +``` + +Each command prints one JSON envelope: `{ ok, command, exit, data, error }`. +`can` keeps `ok: true` when geode exits 3 (deny). `audit` keeps `ok: true` +when geode exits 2 (chain failed). + +## Never run from this skill + +`geode.nu` refuses anything that is not in the list above, including `cat`, +`open`, `mount`, `run`, `agent`, `keygen`, `seal`, `sign`, `vault init`, +`vault add-recipient`, `vault rotate`, `policy set`, `keyring add`, +`custody unlock/lock`, `gc`, and `git unlock`. Those read secret bytes, put +them in an environment or on disk, or change custody. They need a human, and +their output must never be pasted into notes, logs, or chat. + +Entry names can themselves be sensitive. Quote them only where the reader is +allowed to know the vault holds them. diff --git a/skills-stub/geode/geode.nu b/skills-stub/geode/geode.nu new file mode 100755 index 0000000..5f722d5 --- /dev/null +++ b/skills-stub/geode/geode.nu @@ -0,0 +1,224 @@ +#!/usr/bin/env nu +# Fixed metadata-only body for the geode skill. Wraps `geode --output json`. +# stdout is one JSON envelope: {ok, command, exit, data, error} +# Only the allowlist is passed to geode. Anything else is refused. + +const ALLOWED = [ + "list" + "verify" + "vault recipients" + "snapshot ls" + "policy show" + "policy check" + "audit verify" + "custody status" + "keyring list" +] + +def clip-error [stderr: string, stdout: string] { + let joined = ([$stderr $stdout] | str join " " | str trim) + if ($joined | is-empty) { + "command failed" + } else { + ($joined | lines | first | str substring 0..399) + } +} + +def ok-row [command: string, exit: int, data: any] { + { ok: true, command: $command, exit: $exit, data: $data, error: null } +} + +def err-row [command: string, exit: int, error: string] { + { ok: false, command: $command, exit: $exit, data: null, error: ($error | str substring 0..399) } +} + +def refused [command: string, detail: string] { + err-row $command 2 $"refused: geode skill is metadata-only ($detail)" +} + +def as-text [raw: any] { + let d = ($raw | describe) + if $d == "string" { + $raw + } else { + try { $raw | decode utf-8 } catch { "" } + } +} + +def parse-json [text: string] { + let t = ($text | str trim) + if ($t | is-empty) { + error make { msg: "empty json" } + } + $t | from json --strict +} + +def vault-path [v: string] { + if $v != "" { $v } else { $env.GEODE_VAULT? | default "" } +} + +def run-geode [ + command: string, + sub: list, + rest: list, + ok_codes: list = [0], + permit_flags: list = [], +] { + let key = ($sub | str join " ") + let flagged = ($rest | where {|a| ($a | str starts-with "-") and (not ($a in $permit_flags)) }) + if not ($key in $ALLOWED) { + refused $command $"not on the allowlist: ($key)" + } else if not ($flagged | is-empty) { + refused $command "flags are not accepted" + } else { + let argv = (["--output" "json"] ++ $sub ++ $rest) + let r = (try { + ^geode ...$argv | complete + } catch {|e| + { stdout: "", stderr: $"geode: ($e.msg)", exit_code: 127 } + }) + let stdout = (as-text $r.stdout) + let stderr = (as-text $r.stderr) + if not ($r.exit_code in $ok_codes) { + err-row $command $r.exit_code (clip-error $stderr $stdout) + } else { + let parsed = (try { { ok: true, value: (parse-json $stdout) } } catch {|e| { ok: false, value: $e.msg } }) + if not $parsed.ok { + err-row $command 1 $"invalid json: ($parsed.value)" + } else { + ok-row $command $r.exit_code $parsed.value + } + } + } +} + +def path-verb [p: string] { + $p in [ + set init add-recipient rotate add unlock lock delete rm + start end get unset cat open mount run agent keygen seal sign gc + ] +} + +def need-vault [command: string, vault: string] { + let p = (vault-path $vault) + if (path-verb $vault) { + refused $command $"($vault) is not available from this skill" + } else if $p == "" { + err-row $command 2 "no vault: pass one or set GEODE_VAULT" + } else if ($p | str starts-with "-") { + refused $command "vault path must not be a flag" + } else { + { ok: true, path: $p } + } +} + +def "main list" [vault: string = "", prefix: string = "", ...rest: string] { + if not ($rest | is-empty) { + refused "list" "extra arguments" | to json --raw + } else { + let got = (need-vault "list" $vault) + if not $got.ok { + $got | to json --raw + } else { + let rest_args = ([$got.path] ++ (if $prefix == "" { [] } else { [$prefix] })) + run-geode "list" [list] $rest_args | to json --raw + } + } +} + +def "main verify" [vault: string = "", --sample: string = "", ...rest: string] { + if not ($rest | is-empty) { + refused "verify" "extra arguments" | to json --raw + } else { + let got = (need-vault "verify" $vault) + if not $got.ok { + $got | to json --raw + } else if $sample == "" { + run-geode "verify" [verify] [$got.path "--cheap"] [0] ["--cheap"] | to json --raw + } else { + let numeric = (try { $sample | into float; true } catch {|_| false }) + if not $numeric or ($sample | str starts-with "-") { + refused "verify" "sample must be a non-negative number" | to json --raw + } else { + run-geode "verify" [verify] [$got.path "--sample" $sample] [0] ["--sample"] | to json --raw + } + } + } +} + +def "main recipients" [vault: string = "", ...rest: string] { + if not ($rest | is-empty) { + refused "recipients" "extra arguments" | to json --raw + } else { + let got = (need-vault "recipients" $vault) + if not $got.ok { $got | to json --raw } else { + run-geode "recipients" [vault recipients] [$got.path] | to json --raw + } + } +} + +def "main snapshots" [vault: string = "", ...rest: string] { + if not ($rest | is-empty) { + refused "snapshots" "extra arguments" | to json --raw + } else { + let got = (need-vault "snapshots" $vault) + if not $got.ok { $got | to json --raw } else { + run-geode "snapshots" [snapshot ls] [$got.path] | to json --raw + } + } +} + +def "main policy" [vault: string = "", ...rest: string] { + if not ($rest | is-empty) { + refused "policy" "policy set is not available from this skill" | to json --raw + } else { + let got = (need-vault "policy" $vault) + if not $got.ok { $got | to json --raw } else { + run-geode "policy" [policy show] [$got.path] | to json --raw + } + } +} + +def "main can" [principal: string, op: string, path: string, vault: string = "", ...rest: string] { + if not ($rest | is-empty) { + refused "can" "extra arguments" | to json --raw + } else if ([$principal $op $path] | any {|a| $a | str starts-with "-" }) { + refused "can" "flags are not accepted" | to json --raw + } else { + let got = (need-vault "can" $vault) + if not $got.ok { $got | to json --raw } else { + # deny exits 3; that is a result, not a failure + run-geode "can" [policy check] [$got.path $principal $op $path] [0 3] | to json --raw + } + } +} + +def "main audit" [...rest: string] { + if not ($rest | is-empty) { + refused "audit" "extra arguments" | to json --raw + } else { + # a broken chain exits 2; that is a result, not a failure + run-geode "audit" [audit verify] [] [0 2] | to json --raw + } +} + +def "main custody" [...rest: string] { + if not ($rest | is-empty) { + refused "custody" "unlock/lock is not available from this skill" | to json --raw + } else { + run-geode "custody" [custody status] [] | to json --raw + } +} + +def "main keyring" [...rest: string] { + if not ($rest | is-empty) { + refused "keyring" "keyring add is not available from this skill" | to json --raw + } else { + run-geode "keyring" [keyring list] [] | to json --raw + } +} + +def main [...args: string] { + let command = ($args | first | default "") + refused $command ($args | str join " ") | to json --raw +} diff --git a/skills-stub/lapis/SKILL.md b/skills-stub/lapis/SKILL.md new file mode 100644 index 0000000..9e8b3b2 --- /dev/null +++ b/skills-stub/lapis/SKILL.md @@ -0,0 +1,52 @@ +--- +name: lapis +description: > + Search and read a Lapis notes vault through the lapis CLI. Use when a task + needs notes, doctrine, project context, wikilink neighbors, or recent notes + from the vault. Prefer this skill over the lapis MCP server: it adds no tool + schemas to context and its body is deterministic. The MCP server remains + available. +--- + +# lapis — vault read skill + +`lapis` owns the vault and its index. This skill only reads, through the +fixed script `lapis.nu` next to this file. Never open `.lapis/` index files +directly, and do not reimplement the calls. + +## Configuration + +The vault path is resolved in this order: + +1. `--vault ` passed to any command +2. `$LAPIS_VAULT` +3. the path recorded by `lapis init` in the lapis config + +## Commands + +```bash +nu lapis.nu search "phrase" --limit 5 [--domain d] +nu lapis.nu read path/to/note.md +nu lapis.nu list [--prefix projects/] +nu lapis.nu neighbors path/to/note.md +nu lapis.nu resolve "[[Note Name]]" +nu lapis.nu recent [--limit 10] +nu lapis.nu status +nu lapis.nu doctor +``` + +Each command prints one JSON envelope: `{ ok, command, exit, data, error }`. + +- `search`: BM25 over chunks (vectors only if an embedder is configured); one hit per note. `data` is `path` and `title` only. +- `read`: frontmatter (`hal`) plus body. +- `list`: index metadata only; never walks the vault. +- `neighbors`: hop-1 wikilink edges. +- `recent`: newest first. Each row is read by name: `path`, `title`, and `mtime_iso` (Lapis 0.4.2) or `mtime` (older builds). `mtime_iso` wins when both are present. +- `status` / `doctor`: vault root and index health (`exit` 2 when the index is down). + +## Rules + +- Read before you cite: give the note path and quote the passage. +- Writes (`create`, `append`, `task`, `trash`) are refused by `lapis.nu`. + Run them only when a human has explicitly asked, and not through this skill. +- If a path is missing, start `neighbors` from a hub note rather than guessing. diff --git a/skills-stub/lapis/lapis.nu b/skills-stub/lapis/lapis.nu new file mode 100755 index 0000000..a54633c --- /dev/null +++ b/skills-stub/lapis/lapis.nu @@ -0,0 +1,203 @@ +#!/usr/bin/env nu +# Fixed read-only body for the lapis skill. Wraps `lapis --json`. +# stdout is one JSON envelope: {ok, command, exit, data, error} +# Vault: --vault, else $LAPIS_VAULT, else the lapis config default. + +def clip-error [stderr: string, stdout: string] { + let joined = ([$stderr $stdout] | str join " " | str trim) + if ($joined | is-empty) { + "command failed" + } else { + ($joined | lines | first | str substring 0..399) + } +} + +def ok-row [command: string, exit: int, data: any] { + { ok: true, command: $command, exit: $exit, data: $data, error: null } +} + +def err-row [command: string, exit: int, error: string] { + { ok: false, command: $command, exit: $exit, data: null, error: ($error | str substring 0..399) } +} + +def as-text [raw: any] { + let d = ($raw | describe) + if $d == "string" { + $raw + } else { + try { $raw | decode utf-8 } catch { "" } + } +} + +def parse-json [text: string] { + let t = ($text | str trim) + if ($t | is-empty) { + error make { msg: "empty json" } + } + $t | from json --strict +} + +def vault-args [vault: string] { + let v = if $vault != "" { $vault } else { $env.LAPIS_VAULT? | default "" } + if ($v | str starts-with "-") { + error make { msg: "vault path must not be a flag" } + } + if $v == "" { [] } else { ["--vault" $v] } +} + +def lapis-data [value: any] { + let d = ($value | describe) + if ($d | str starts-with "record") and ("data" in ($value | columns)) { + $value | get data + } else { + $value + } +} + +def run-lapis [command: string, args: list, vault: string] { + let vault_part = (try { vault-args $vault } catch {|e| $e.msg }) + if ($vault_part | describe) == "string" { + err-row $command 2 $vault_part + } else { + let argv = (["--json"] ++ $vault_part ++ $args) + let r = (try { + ^lapis ...$argv | complete + } catch {|e| + { stdout: "", stderr: $"lapis: ($e.msg)", exit_code: 127 } + }) + let stdout = (as-text $r.stdout) + let stderr = (as-text $r.stderr) + if $r.exit_code != 0 { + err-row $command $r.exit_code (clip-error $stderr $stdout) + } else { + let parsed = (try { { ok: true, value: (parse-json $stdout) } } catch {|e| { ok: false, value: $e.msg } }) + if not $parsed.ok { + err-row $command 1 $"invalid json: ($parsed.value)" + } else { + ok-row $command 0 (lapis-data $parsed.value) + } + } + } +} + +def flagish [s: string] { $s | str starts-with "-" } + +def "main search" [query: string, --limit (-n): int = 5, --domain: string = "", --vault: string = ""] { + if $limit < 1 { + err-row "search" 2 "limit must be >= 1" | to json --raw + } else if (flagish $query) or (flagish $domain) { + err-row "search" 2 "refused: lapis skill is read-only" | to json --raw + } else { + mut args = ["search" $query "-n" ($limit | into string)] + if $domain != "" { $args = ($args ++ ["--domain" $domain]) } + let row = (run-lapis "search" $args $vault) + if not $row.ok { + $row | to json --raw + } else { + let hits = (try { $row.data | get hits } catch {|err| null }) + let kind = ($hits | describe) + if not (($kind | str starts-with "list") or ($kind | str starts-with "table")) { + err-row "search" 1 "search data has no hits" | to json --raw + } else { + let slim = (try { $hits | select path title } catch {|err| null }) + if ($slim | describe) == "nothing" { + err-row "search" 1 "search hits missing path or title" | to json --raw + } else { + ok-row "search" $row.exit $slim | to json --raw + } + } + } + } +} + +def "main read" [path: string, --vault: string = ""] { + if (flagish $path) { + err-row "read" 2 "refused: lapis skill is read-only" | to json --raw + } else { + run-lapis "read" ["read" $path] $vault | to json --raw + } +} + +def "main list" [--prefix: string = "", --vault: string = ""] { + let row = (run-lapis "list" ["list"] $vault) + if not $row.ok or $prefix == "" { + $row | to json --raw + } else { + let kind = ($row.data | describe) + if not (($kind | str starts-with "list") or ($kind | str starts-with "table")) { + err-row "list" 1 "list data is not a list" | to json --raw + } else { + let filtered = ($row.data | where path starts-with $prefix) + ok-row "list" $row.exit $filtered | to json --raw + } + } +} + +def "main neighbors" [path: string, --vault: string = ""] { + if (flagish $path) { + err-row "neighbors" 2 "refused: lapis skill is read-only" | to json --raw + } else { + run-lapis "neighbors" ["neighbors" $path] $vault | to json --raw + } +} + +def "main resolve" [link: string, --vault: string = ""] { + if (flagish $link) { + err-row "resolve" 2 "refused: lapis skill is read-only" | to json --raw + } else { + run-lapis "resolve" ["resolve" $link] $vault | to json --raw + } +} + +# Lapis 0.4.2 rows are path, title, domain, priority, mtime_iso. +# Older builds are path, title, mtime. Read those fields by name. +def recent-mtime [row: record] { + let cols = ($row | columns) + if "mtime_iso" in $cols { + $row | get mtime_iso + } else if "mtime" in $cols { + $row | get mtime + } else { + error make { msg: "recent row missing mtime" } + } +} + +def "main recent" [--limit (-n): int = 10, --vault: string = ""] { + if $limit < 1 { + err-row "recent" 2 "limit must be >= 1" | to json --raw + } else { + let row = (run-lapis "recent" ["analytics" "recent"] $vault) + if not $row.ok { + $row | to json --raw + } else { + let rows = (try { $row.data | get rows } catch {|err| null }) + let shaped = (try { + $rows | first $limit | each {|r| + { + path: ($r | get path) + title: ($r | get title) + mtime: (recent-mtime $r) + } + } + } catch {|err| null }) + if ($shaped | describe) == "nothing" { + err-row "recent" 1 "recent data has no rows" | to json --raw + } else { + ok-row "recent" $row.exit $shaped | to json --raw + } + } + } +} + +def "main status" [--vault: string = ""] { + run-lapis "status" ["vault" "info"] $vault | to json --raw +} + +def "main doctor" [--vault: string = ""] { + run-lapis "doctor" ["doctor"] $vault | to json --raw +} + +def main [...args: string] { + let command = ($args | first | default "") + err-row $command 2 "refused: lapis skill is read-only" | to json --raw +}