@geohar/pi-cribsheet 0.0.0

package/dist/sharedserver-resolve.js

@@ -0,0 +1,188 @@
+// Resolve the `sharedserver` binary, fetching it when none is usable.
+//
+// VENDORED FILE. This is copied byte-identical into the consuming OpenCode plugins
+// (cribsheet, svg-mcp) by their scripts/sync-vendored.sh, so the drift check is a plain
+// diff. There is no way to share it as a dependency without coupling their versions to
+// sharedserver's — see plugins/claude/bin/sharedserver for the same reasoning on the
+// shell side. Edit it HERE; consumers re-sync.
+//
+// Everything repo-specific arrives through ResolveConfig rather than being hardcoded,
+// mirroring bin/sharedserver.conf.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Oldest release these plugins are correct against: 0.5.0 added the PID-reuse guard,
+ *  without which a recycled client PID can hold a server open indefinitely. */
+const HARDCODED_FLOOR = "0.5.0";
+const CANDIDATE_BINARIES = [
+    "sharedserver",
+    join(homedir(), ".cargo", "bin", "sharedserver"),
+    join(homedir(), ".local", "bin", "sharedserver"),
+    "/usr/local/bin/sharedserver",
+    "/opt/homebrew/bin/sharedserver",
+];
+function parseVersion(text) {
+    const m = text.match(/(\d+)\.(\d+)\.(\d+)/);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+function gte(a, b) {
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    return true;
+}
+function versionOf(candidate, env) {
+    const r = spawnSync(candidate, ["--version"], { env });
+    if (r.error)
+        return undefined;
+    return parseVersion(`${r.stdout?.toString() ?? ""}${r.stderr?.toString() ?? ""}`);
+}
+/** Synchronous sleep — this path runs before anything can be awaited, so the lock wait
+ *  cannot use timers. Atomics.wait blocks without spinning. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** First sharedserver found at ANY version, or undefined. */
+function probeAny(override, env) {
+    const candidates = [override, env.SHAREDSERVER_BIN, ...CANDIDATE_BINARIES].filter((v) => typeof v === "string" && v.length > 0);
+    for (const candidate of candidates) {
+        if (candidate.includes("/")) {
+            if (existsSync(candidate))
+                return candidate;
+            continue;
+        }
+        // Presence is "spawn did not fail", NOT "exited 0" — a build that rejects some
+        // flag is still present.
+        if (!spawnSync(candidate, ["--version"], { stdio: "ignore", env }).error)
+            return candidate;
+    }
+    return undefined;
+}
+/** Download and run the cargo-dist installer, then re-probe. */
+function installPinned(cfg, url, what, env, log, toast) {
+    // The SAME lock directory as the shell shim — cross-client coordination, so a
+    // Claude session and an OpenCode session starting together do not race.
+    const lockdir = join(env.TMPDIR || "/tmp", ".sharedserver-install.lock");
+    let haveLock = false;
+    try {
+        mkdirSync(lockdir);
+        haveLock = true;
+    }
+    catch {
+        const deadline = Date.now() + 20_000;
+        while (existsSync(lockdir) && Date.now() < deadline)
+            sleepSync(250);
+        const after = probeAny(undefined, env);
+        if (after)
+            return after;
+        try {
+            mkdirSync(lockdir);
+            haveLock = true;
+        }
+        catch {
+            log?.("warn", `${cfg.label}: another process is installing sharedserver and did not finish; remove the stale lock if this persists: ${lockdir}`);
+            return undefined;
+        }
+    }
+    try {
+        // Re-probe under the lock: the winner may have finished while we waited.
+        const already = probeAny(undefined, env);
+        const floor = parseVersion(cfg.minVersion ?? HARDCODED_FLOOR);
+        if (already) {
+            const v = versionOf(already, env);
+            if (v && floor && gte(v, floor))
+                return already;
+        }
+        // Download to a file, then run it. `curl … | sh` would report success on a 404,
+        // since a pipeline's status is sh's; spawnSync uses no shell, so this is exact.
+        const script = join(lockdir, "installer.sh");
+        const dl = spawnSync("curl", ["--proto", "=https", "--tlsv1.2", "-LsSf", url, "-o", script], { env });
+        if (dl.error || dl.status !== 0) {
+            const msg = `${cfg.label}: could not download the sharedserver installer (${what})`;
+            log?.("warn", msg);
+            toast?.("warning", msg);
+            return undefined;
+        }
+        if (!existsSync(script) || statSync(script).size === 0) {
+            log?.("warn", `${cfg.label}: the downloaded sharedserver installer was empty`);
+            return undefined;
+        }
+        // cargo-dist embeds the expected sha256 but looks up only `sha256sum` and SKIPS
+        // verification when missing — i.e. always, on macOS. Give it one (identical
+        // output) rather than execute an unverified binary.
+        let runEnv = env;
+        if (spawnSync("sh", ["-c", "command -v sha256sum"], { stdio: "ignore" }).status !== 0) {
+            if (spawnSync("sh", ["-c", "command -v shasum"], { stdio: "ignore" }).status !== 0) {
+                log?.("warn", `${cfg.label}: refusing to install sharedserver — no sha256sum or shasum to verify the download`);
+                return undefined;
+            }
+            writeFileSync(join(lockdir, "sha256sum"), '#!/bin/sh\nexec shasum -a 256 "$@"\n', { mode: 0o755 });
+            runEnv = { ...env, PATH: `${lockdir}:${env.PATH ?? ""}` };
+        }
+        const run = spawnSync("sh", [script], { env: runEnv, stdio: "ignore" });
+        if (run.error || run.status !== 0) {
+            log?.("warn", `${cfg.label}: the sharedserver installer ran but failed`);
+            return undefined;
+        }
+        return probeAny(undefined, env);
+    }
+    finally {
+        if (haveLock) {
+            try {
+                rmSync(lockdir, { recursive: true, force: true });
+            }
+            catch {
+                /* best effort — a leaked lock costs the next run its bounded wait */
+            }
+        }
+    }
+}
+/** Resolve the sharedserver binary, fetching a release when nothing usable is present.
+ *
+ *  Behaviourally identical to plugins/claude/bin/sharedserver — same ladder, floor,
+ *  lock and degrade-rather-than-die fallback, so a user running both clients gets the
+ *  same answer to "which sharedserver am I on, and why". */
+export function resolveSharedserver(cfg, override, env, log, toast) {
+    const label = cfg.label ?? "sharedserver";
+    const minVersion = cfg.minVersion ?? cfg.pkgVersion ?? HARDCODED_FLOOR;
+    const url = cfg.installerUrl ??
+        (cfg.pkgVersion
+            ? `https://github.com/georgeharker/sharedserver/releases/download/v${cfg.pkgVersion}/sharedserver-installer.sh`
+            : "https://github.com/georgeharker/sharedserver/releases/latest/download/sharedserver-installer.sh");
+    const what = cfg.installerUrl || !cfg.pkgVersion ? "the latest release" : `v${cfg.pkgVersion}`;
+    const resolved = { ...cfg, label, minVersion };
+    const floor = parseVersion(minVersion);
+    // An explicit binary / SHAREDSERVER_BIN is never second-guessed: the user named a
+    // specific one, so quietly downloading a different one is the wrong answer.
+    const explicit = override ?? env.SHAREDSERVER_BIN;
+    if (explicit) {
+        const present = explicit.includes("/")
+            ? existsSync(explicit)
+            : !spawnSync(explicit, ["--version"], { stdio: "ignore", env }).error;
+        if (present) {
+            const v = versionOf(explicit, env);
+            if (v && floor && !gte(v, floor)) {
+                const msg = `${label}: sharedserver at ${explicit} is ${v.join(".")}; this plugin expects >= ${minVersion}. Using it anyway because you set it explicitly.`;
+                log?.("warn", msg);
+                toast?.("warning", msg);
+            }
+            return explicit;
+        }
+    }
+    const found = probeAny(override, env);
+    if (found) {
+        const v = versionOf(found, env);
+        if (v && floor && gte(v, floor))
+            return found;
+        // Too old: fetch, but remember this one — if the download fails we would rather
+        // run the old binary than nothing.
+        const msg = `${label}: sharedserver at ${found} is ${v?.join(".") ?? "an unknown version"}; this plugin expects >= ${minVersion}. Fetching ${what}. To keep your own build, set SHAREDSERVER_BIN=${found}`;
+        log?.("warn", msg);
+        toast?.("warning", msg);
+        return installPinned(resolved, url, what, env, log, toast) ?? found;
+    }
+    log?.("info", `${label}: no usable sharedserver found; fetching ${what} (one time). This needs no Rust toolchain.`);
+    return installPinned(resolved, url, what, env, log, toast);
+}
+//# sourceMappingURL=sharedserver-resolve.js.map

package/dist/sharedserver-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedserver-resolve.js","sourceRoot":"","sources":["../src/sharedserver-resolve.ts"],"names":[],"mappings":"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"}

package/instructions.txt

@@ -0,0 +1,140 @@
+# Memory (cribsheet)
+
+<!-- Canonical reach-for-crib directive. Copy into your global
+     $CLAUDE_CONFIG_DIR/CLAUDE.md, or let a cribsheet plugin inject it each session
+     (the plugins symlink this file). It directs *approach*; the MCP tool
+     descriptions carry the mechanics. -->
+
+Five rules. Each fires on a **cue you can catch yourself in the middle of**, not on
+a topic you have to remember to think about. That's deliberate: you will not remember
+to "consult memory" — but you can notice your own hand reaching for `grep`.
+
+Rules 4 and 5 are the ones you will walk past most, because their cues don't feel like
+actions: settling a design question and writing a todo list both feel like *thinking*,
+not like *reaching for a tool*. Watch for them anyway.
+
+### 1. About to grep? That's the cue.
+
+`grep` / `rg` / `Glob`, or opening a file to see what it does, is a **stop sign, not
+an action**. At that exact moment:
+
+| your next move was | do this instead |
+|---|---|
+| grep for a symbol — by name, or by hunch | `code_lookup "what it does, in your own words"` — answers by intent, across files |
+| open the file to understand a symbol | `code_dossier <symbol>` — signature, description, callers, callees, references, in one call |
+| chain greps to trace a caller | `code_xref` / `code_graph` |
+| *(repo isn't indexed)* | `project_index` — one call, and the **expected first step**, not a dead end |
+
+grep is the **fallback for when the index misses**. It is never the opening move.
+There is no shortcut around indexing; the utility *is* the index.
+
+**Catch yourself:** if you've read three files to answer one question, this rule
+already fired and you walked past it. Stop where you are, `code_lookup`, redo it.
+
+### 2. About to answer from your own knowledge? Look it up first.
+
+Cue: you're about to explain a project, a past decision, or a convention — or open a
+codebase cold. `lookup` / `apropos` **before** you answer, not after. What's stored may
+be more current than what you'd reconstruct, and *you can't tell which from the inside*:
+a confident reconstruction feels exactly like a correct one.
+
+### 3. Just understood something? Store it before you move on.
+
+Cue: the "ah, *that's* why" moment — a convention, a gotcha, a contract. The
+moment passes; the note has to be written inside it. `lookup` first, then `append`/`edit`
+over creating a near-duplicate.
+
+**Not a decision, and not a task.** Those have their own verbs — rules 4 and 5. If what
+you just understood is *why we chose this*, `note_store` is the wrong verb: it takes the
+prose and silently drops the edges, which were the part worth keeping.
+
+Writes need an explicit `project=` — they do **not** inherit your current project. Name
+the project the fact is *about*: the repo you're in, or `default` (or that tool's own
+project) for cross-cutting knowledge like a CLI or editor convention. Say where it landed.
+To pin a hard-won insight about a symbol: `code_append <symbol> "…"`.
+
+### 4. Just settled a question — or about to explain why? Use the decision graph.
+
+Cue: a design question stopped being open. "Chunks are keyed by X." "Writes must name
+their project." It's the moment the arguing stops — and it feels like you merely
+*finished thinking*, which is exactly why this rule gets walked past.
+
+Decisions have their **own verbs**. Use those, not `note_*`: a note holds the prose,
+but only the facet knows what a decision rests on, what rests on it, and what your
+change just invalidated. That last part is the whole point.
+
+| your next move was | do this instead |
+|---|---|
+| a question just got settled, and it has consequences | `design_add <title> <rationale>` with `--dep` on what it builds on |
+| the new decision *replaces* an existing one | `design_supersede` — a second `design_add` leaves both standing and both findable |
+| explain *why* it's built this way | `design_lookup "<query>"` **before** reconstructing it from the code — hits flag stale decisions |
+| read / cite a decision | `design_read <ref>` — body **plus** deps, dependents, and whether either moved |
+| change a decision, or code that implements one | `design_check` **first** — then `design_edit`/`design_append`, whose result lists what you just tainted |
+| propose an architecture change | `design_tree` (or `--dependents`) — see what rests on it before you move it |
+
+- **Adding is SILENT — so check what it lands next to.** `design_add` seeds its
+  `checked` state from its deps as they read right now, so a new decision is
+  born verified and nothing gains taint just because it appeared. The graph will
+  hold two decisions that flatly contradict each other and never say a word: it
+  tracks the edges you declared, not agreement. So `design_lookup` the area
+  first, and read the `similar` list the result hands back. Restates an existing
+  decision → `design_append`/`design_edit` **that one**. Replaces it →
+  `design_supersede`. Changes the ground under other work → `design_check`,
+  which is the only verb that answers "what did I just break".
+- **A dep is a promise**: *if that changes, reconsider this.* A plain note can't
+  make that promise; the graph can. Every edge checks — there is no "just for
+  reference" edge that lets an origin change silently.
+- **Each stale decision** comes back with the chain explaining *why*, what kind of
+  change did it, when, and the verb to run. After reconsidering, `design_reaffirm`
+  marks it current. Taint means *a dep moved*, not *you were wrong* — reaffirming
+  is the cheap, normal ending, so don't treat it as a crisis. When it genuinely no
+  longer holds, `design_supersede`.
+- **A hit marked `tainted`** is a decision whose ground shifted and nobody
+  re-read. Don't quietly reason from it — `design_read` it first.
+
+**Catch yourself:** if you've just written a paragraph explaining why something is
+built the way it is, you either read that out of the graph or you owe it to the
+graph. Same for "let's go with X" — that's a `design_add`, not a sentence.
+
+### 5. About to write a todo list — in a file, in chat, or in your head? That's the cue.
+
+`plan_add` instead. An in-chat list dies with the chat and a list in your head dies
+with the context window; a plan item outlives both. One call takes the whole batch,
+and deps can point at earlier items in the same batch.
+
+- **`plan_lookup` before you add — it may already be planned.** Another session,
+  or another agent, may have written the item you're about to write. An item
+  that duplicates a `done` one is louder than a duplicate: either the work
+  regressed or you've mis-scoped this, and both are worth knowing *before* a
+  second entry exists.
+- **`--dep` the DECISION an item rests on, not just the items before it.** Deps
+  mix, and they block differently: a **plan** dep blocks until it's done; a
+  **design** dep blocks while it's *tainted*; a **note** dep never blocks. So an
+  item that declares the decision it implements drops out of `plan_next` the
+  moment that decision's ground moves — the work stops looking actionable
+  exactly when it stops being safe to do. That is the plan facet's version of
+  "check it didn't break", and it is the only one that fires without you asking.
+- **`plan_status` as you go, not at the end** — `in-progress` is a *claim* other
+  agents can see, and marking one `done` tells you what it just unblocked.
+- **`plan_next` is the "where was I" call** — run it when you pick work back up, and
+  any future session (yours or another agent's) gets exactly what's actionable now.
+
+**Catch yourself:** if you've just typed "first I'll… then I'll…", or reached for a
+scratch todo list, this rule already fired.
+
+### Importing a doc (either facet)
+
+Asked to capture a DESIGN.md, a spec, or a plan file? `design_import` / `plan_import`
+that doc, then follow the procedure it returns. They run no model and write nothing —
+they hand you the doc's exact citable sections, what already draws on it, and the
+steps. *You* read and judge. Each entry cites the **section** it came from
+(`--source "DESIGN.md#10.3 Fusion"`, never the whole file), so a later edit to that
+passage re-checks exactly what was drawn from it. Extracted decisions land
+`proposed`: they gate work and taint nothing until a human confirms them with
+`design_promote`.
+
+<!-- Project selection for *reads*: code tools act on ONE current project — set it once
+     with `use_project <name>`, or it's inferred from `project_path` on your first code
+     call; reads then need no project args. To read a *different* project you must name it
+     (`project=` / `project_path=`). `project_path` means "which repo I mean" — it is not
+     your shell cwd. -->

package/mcp.json.example

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "cribsheet": {
+      "url": "http://127.0.0.1:7732/mcp"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@geohar/pi-cribsheet",
+    "version": "0.0.0",
+    "description": "Pi extension: run the crib (cribsheet) memory + code-index MCP server via sharedserver, inject the reach-for-crib directive, and ship the /crib recall command. Pairs with pi-mcp-adapter.",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "pi": {
+        "extensions": [
+            "./src/index.ts"
+        ]
+    },
+    "files": [
+        "src",
+        "dist",
+        "instructions.txt",
+        "mcp.json.example",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "clean": "rm -rf dist",
+        "typecheck": "tsc --noEmit",
+        "prepack": "node -e \"require('fs').copyFileSync('../../CLAUDE.md.example', './instructions.txt')\"",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "keywords": [
+        "pi",
+        "pi-extension",
+        "pi-mono",
+        "mcp",
+        "cribsheet",
+        "crib",
+        "memory",
+        "sharedserver",
+        "extension"
+    ],
+    "author": "George Harker <george@georgeharker.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/georgeharker/cribsheet.git",
+        "directory": "plugins/pi"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "typescript": "^5.6.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}