simple-skills-manager 1.0.1

package/tests/smoke.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# simple-skills-manager smoke test.
+#
+# Exercises, with no external model and no untrusted network calls:
+#   1. both transports end-to-end: discovery, grouping, script flagging,
+#      hidden skills, strict rejections, symlink fail-closed; frontmatter
+#      subset; validation invariants; config round-trips (starter with the
+#      seeded store root, upsert/remove, settings fallback, loud failure on
+#      a corrupt file); the registered-tool execute path (lazy scan at first
+#      call, success, scan reuse, fail-closed content drift); scan budget
+#      and maxSkills enforcement; native mirror computation
+#   2. managed discovery through Pi's normal extension loading, from the
+#      single config file at $PI_CODING_AGENT_DIR/simple-skills-manager.json:
+#      tool + command registration, per-entry isolation, native-tool
+#      preservation, and lazy registration (a tool registers while its root
+#      directory does not exist)
+#   3. first run: a fresh agent dir gets a starter config (seeded with the
+#      store root) and the store directory auto-created, and registers no
+#      skill tools
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+extension_root="$(cd "$here/.." && pwd -P)"
+pi_bin="${PI_BIN:-$(command -v pi)}"
+node_bin="${NODE_BIN:-$(command -v node)}"
+[[ -n "$pi_bin" ]] || { echo "pi binary not found" >&2; exit 1; }
+[[ -n "$node_bin" ]] || { echo "node binary not found" >&2; exit 1; }
+
+temp="$(mktemp -d)"
+cleanup() { rm -rf "$temp"; }
+trap cleanup EXIT
+
+wait_for_file() {
+  local file="$1" label="$2"
+  for _ in $(seq 1 300); do
+    [[ -s "$file" ]] && return 0
+    sleep 0.1
+  done
+  echo "Timed out waiting for $label" >&2
+  return 1
+}
+
+# ---------------------------------------------------------------------------
+# Phase 1: the client/scanner bridge, driven by an extension via -e.
+# ---------------------------------------------------------------------------
+result="$temp/client-result.json"
+( cd "$temp" && printf '%s\n' '{"type":"get_commands"}' && sleep 4 ) | env \
+  PI_CODING_AGENT_DIR="$temp/client-agent" \
+  PI_SKILL_FIXTURES="$here/fixtures" \
+  PI_SKILL_RESULT="$result" \
+  "$pi_bin" -e "$here/smoke-extension.ts" --mode rpc --session "$temp/client-session.jsonl" \
+  >"$temp/client-rpc.out" 2>"$temp/client-rpc.err"
+wait_for_file "$result" "client smoke result"
+
+"$node_bin" -e '
+const fs = require("fs");
+const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+const fail = () => { console.error(value); process.exit(1); };
+if (!value.ok) fail();
+for (const key of ["skillsDir", "singleSkill", "strictRejections", "symlinkRoots", "snapshotFile", "copyBudget"]) {
+  if (value.scans?.[key] !== true) fail();
+}
+for (const key of ["roundTrip", "storeSeed", "settingsFallback", "loudFailure"]) {
+  if (value.roundtrip?.[key] !== true) fail();
+}
+const exec = value.executor;
+if (!exec || exec.lazyRejected !== true || exec.callOk !== true || exec.driftRejected !== true) fail();
+if (value.autoAdoption !== true) fail();
+for (const key of ["frontmatter", "validation", "nameInvariants", "malformedManifestSafety", "cacheMaxSkillsHonored", "nativeMirror", "treeBuilder"]) {
+  if (value.regressions?.[key] !== true) fail();
+}
+' "$result"
+
+# ---------------------------------------------------------------------------
+# Phase 2: managed discovery through Pi's normal resource path, from the
+# single-file config. A malformed entry must not block a valid one, and a
+# root that does not exist yet must still register its tool (laziness).
+# ---------------------------------------------------------------------------
+agent="$temp/managed-agent"
+mkdir -p "$agent/extensions"
+cp -a "$extension_root" "$agent/extensions/simple-skills-manager"
+
+# The store root lives at $agent/managed-skills; copy one fixture skill in.
+mkdir -p "$agent/managed-skills"
+cp -a "$here/fixtures/skills-dir/plain" "$agent/managed-skills/plain"
+
+# The manifest fingerprint must equal fingerprint() in config.ts:
+# sha256 over { name, transport, path }.
+fingerprint_store="$("$node_bin" -e '
+const crypto = require("crypto");
+const identity = { name: "store", transport: "skills-dir", path: process.argv[1] };
+process.stdout.write(crypto.createHash("sha256").update(JSON.stringify(identity)).digest("hex"));
+' "$agent/managed-skills")"
+content_hash="$("$node_bin" -e '
+const crypto = require("crypto");
+const bytes = require("fs").readFileSync(process.argv[1]);
+process.stdout.write(crypto.createHash("sha256").update(bytes).digest("hex"));
+' "$agent/managed-skills/plain/SKILL.md")"
+ghost_path="$temp/ghost-root"
+ghost_fingerprint="$("$node_bin" -e '
+const crypto = require("crypto");
+const identity = { name: "ghost", transport: "skills-dir", path: process.argv[1] };
+process.stdout.write(crypto.createHash("sha256").update(JSON.stringify(identity)).digest("hex"));
+' "$ghost_path")"
+
+cat >"$agent/simple-skills-manager.json" <<EOF
+{
+  "version": 1,
+  "settings": {"maxSkills": 50},
+  "registrar": [
+    {
+      "name": "store",
+      "store": true,
+      "enabled": true,
+      "transport": "skills-dir",
+      "path": "$agent/managed-skills",
+      "connection": "lazy",
+      "skills": {"mode": "selected", "include": ["plain-skill"]},
+      "manifest": {
+        "version": 1,
+        "fingerprint": "$fingerprint_store",
+        "scannedAt": "fixture",
+        "skills": [{
+          "name": "plain-skill",
+          "description": "A plain fixture skill with no extras. Use when testing skill scanning.",
+          "dirPath": "plain",
+          "contentHash": "$content_hash",
+          "fileCount": 1,
+          "executableScripts": []
+        }]
+      }
+    },
+    {
+      "name": "ghost",
+      "enabled": true,
+      "transport": "skills-dir",
+      "path": "$ghost_path",
+      "connection": "lazy",
+      "skills": {"mode": "selected", "include": ["phantom"]},
+      "manifest": {
+        "version": 1,
+        "fingerprint": "$ghost_fingerprint",
+        "scannedAt": "fixture",
+        "skills": [{
+          "name": "phantom",
+          "description": "A ghost skill whose root directory does not exist yet.",
+          "dirPath": "phantom",
+          "contentHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "fileCount": 1,
+          "executableScripts": []
+        }]
+      }
+    },
+    {"name": "broken", "enabled": true, "transport": "skills-dir"}
+  ]
+}
+EOF
+
+# The probe cannot rely on session_start handler ordering across extensions,
+# so it polls in the background instead of blocking startup.
+cat >"$agent/extensions/zz-skills-smoke-probe.ts" <<'EOF'
+import { writeFile } from "node:fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function probe(pi: ExtensionAPI): void {
+    pi.on("session_start", async () => {
+        const output = process.env.PI_SKILL_TOOL_RESULT;
+        if (!output) return;
+        const deadline = Date.now() + 10_000;
+        void (async () => {
+            while (Date.now() < deadline) {
+                const names = pi.getAllTools().map((tool) => tool.name);
+                if (names.includes("skill_store__plain-skill") && names.includes("skill_ghost__phantom")) {
+                    const commands = pi.getCommands().map((command) => ({ name: command.name, source: command.source }));
+                    await writeFile(output, JSON.stringify({ tools: names, commands }));
+                    return;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 50));
+            }
+            const commands = pi.getCommands().map((command) => ({ name: command.name, source: command.source }));
+            await writeFile(output, JSON.stringify({ tools: pi.getAllTools().map((tool) => tool.name), commands }));
+        })();
+    });
+}
+EOF
+
+tools_result="$temp/tools-result.json"
+( cd "$temp" && printf '%s\n' '{"type":"get_commands"}' && sleep 3 ) | env \
+  PI_CODING_AGENT_DIR="$agent" \
+  PI_SKILL_TOOL_RESULT="$tools_result" \
+  "$pi_bin" --mode rpc --session "$temp/managed-session.jsonl" \
+  >"$temp/managed-rpc.out" 2>"$temp/managed-rpc.err"
+wait_for_file "$tools_result" "managed tool registration result"
+
+"$node_bin" -e '
+const fs = require("fs");
+const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+const fail = (why) => { console.error(why, value); process.exit(1); };
+for (const name of ["read", "bash", "edit", "write", "grep", "find", "ls", "skill_store__plain-skill", "skill_ghost__phantom"]) {
+  if (!value.tools.includes(name)) fail(`missing tool: ${name}`);
+}
+if (value.tools.some((name) => name.startsWith("skill_broken__"))) fail("malformed entry should not register tools");
+// Our skill:<name> commands are registered as extension commands and shadow
+// the native skill namespace (extension commands dispatch first).
+for (const name of ["skill:plain-skill", "skill:phantom", "skills-manager"]) {
+  const command = value.commands.find((entry) => entry.name === name);
+  if (!command) fail(`missing command: ${name}`);
+  if (command.source !== "extension") fail(`command ${name} has source ${command.source}`);
+}
+' "$tools_result"
+
+# Lazy registration: the ghost root directory never existed, yet its tool was
+# registered — proving nothing is scanned merely because pi starts.
+[[ ! -e "$ghost_path" ]] || { echo "ghost root unexpectedly exists" >&2; exit 1; }
+
+# ---------------------------------------------------------------------------
+# Phase 3: first run — a fresh agent dir with no config file must get a
+# starter config (seeded with the store root) and the store directory,
+# register no skill tools, and not crash.
+# ---------------------------------------------------------------------------
+fresh="$temp/fresh-agent"
+mkdir -p "$fresh/extensions"
+cp -a "$extension_root" "$fresh/extensions/simple-skills-manager"
+
+( cd "$temp" && printf '%s\n' '{"type":"get_commands"}' && sleep 3 ) | env \
+  PI_CODING_AGENT_DIR="$fresh" \
+  "$pi_bin" --mode rpc --session "$temp/fresh-session.jsonl" \
+  >"$temp/fresh-rpc.out" 2>"$temp/fresh-rpc.err"
+
+[[ -s "$fresh/simple-skills-manager.json" ]] || { echo "first run did not create the starter config" >&2; exit 1; }
+[[ -d "$fresh/managed-skills" ]] || { echo "first run did not create the store directory" >&2; exit 1; }
+"$node_bin" -e '
+const fs = require("fs");
+const raw = fs.readFileSync(process.argv[1], "utf8");
+const parsed = JSON.parse(raw.replace(/(^|\s)\/\/.*$/gm, "$1").replace(/\/\*[\s\S]*?\*\//g, ""));
+if (parsed.version !== 1 || !Array.isArray(parsed.registrar) || parsed.registrar.length !== 1) {
+  console.error("starter config has wrong shape", parsed);
+  process.exit(1);
+}
+const store = parsed.registrar[0];
+if (store.name !== "store" || store.store !== true || store.enabled !== false || store.transport !== "skills-dir") {
+  console.error("starter store root has wrong shape", store);
+  process.exit(1);
+}
+' "$fresh/simple-skills-manager.json"
+
+echo "Skills smoke test passed: both transports, strict rejections, config round-trips, fail-closed drift, native mirroring, single-file discovery, per-entry isolation, command shadowing, lazy registration, native-tool preservation, and first-run starter creation."

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "types": ["node"]
+  },
+  "include": ["*.ts", "tests/*.ts"],
+  "paths": {
+    "@earendil-works/pi-coding-agent": ["/home/msav/.local/lib/node_modules/@earendil-works/pi-coding-agent/dist/index.d.ts"],
+    "@earendil-works/pi-tui": ["/home/msav/.local/lib/node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui/dist/index.d.ts"],
+    "typebox": ["/home/msav/.local/lib/node_modules/@earendil-works/pi-coding-agent/node_modules/typebox/dist/index.d.ts"]
+  }
+}

package/util.ts

@@ -0,0 +1,74 @@
+/** Shared tiny helpers used across the extension's modules. */
+
+import { rename, writeFile } from "node:fs/promises";
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Strip JSONC comments — // line comments and block comments — so the
+ *  config file can be annotated by hand. String-aware: // inside quoted
+ *  values (URLs like http://...) is preserved. */
+export function stripJsonComments(text: string): string {
+    let out = "";
+    let inString = false;
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (inString) {
+            out += c;
+            if (c === "\\" && i + 1 < text.length) {
+                out += text[i + 1];
+                i += 2;
+                continue;
+            }
+            if (c === '"') inString = false;
+            i++;
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            i++;
+            continue;
+        }
+        if (c === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n") i++;
+            continue;
+        }
+        if (c === "/" && text[i + 1] === "*") {
+            i += 2;
+            while (i + 1 < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+            i += 2;
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    return out;
+}
+
+/** Remove control characters (except \n and \t) from untrusted external text
+ *  before it is shown to the user or persisted into tool output. */
+export function sanitizeExternalText(input: string): string {
+    return input.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
+}
+
+/** A readable message from any thrown value. */
+export function errText(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+/** Render validation issues as markdown bullets. */
+export function bulletList(items: string[]): string {
+    return items.map((item) => `- ${item}`).join("\n");
+}
+
+/** Atomically write a text file (temp file + rename, mode 0600). Used for
+ *  the config and for skill files edited through the TUI, so every write is
+ *  a crash-safe replacement. */
+export async function writeFileAtomic(path: string, text: string): Promise<void> {
+    const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    await writeFile(temp, text, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await rename(temp, path);
+}