@pinchpass/cli 1.0.6 → 1.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @pinchpass/cli
+
+One-time **E2E-encrypted** secret request links for AI agents.
+
+Generate a temporary HTTP server with a single-use encrypted form for
+collecting sensitive values (API keys, tokens, passwords) — locally or over
+the internet via a built-in bore.pub tunnel. **The relay never sees the
+secret**: encryption happens in the browser, and the decryption key lives only
+in the URL fragment.
+
+## Install
+
+```sh
+npm i -g @pinchpass/cli
+```
+
+The install downloads the prebuilt `pinchpass` binary for your platform to
+`~/.local/bin` (or finds an existing install).
+
+## Pi (pi.dev)
+
+This package is a native [Pi](https://pi.dev) package:
+
+```sh
+pi install npm:@pinchpass/cli
+```
+
+That registers:
+
+- **`request_secret` tool** — two collection modes:
+  - `via: "modal"` (default in the TUI): a Pi dialog collects each secret
+    directly into `.env` — the value never reaches the LLM, never enters the
+    transcript, and no server is started. Cancelable with `Esc`.
+  - `via: "link"`: spawns the CLI, streams the one-time E2E-encrypted link to
+    the user immediately, blocks until they submit or the TTL expires.
+  - `via` defaults to `"auto"`: modal in the TUI, link everywhere else.
+- **`pinchpass` skill** — full usage guidance for the model.
+
+The binary is resolved from `PATH`, `~/.local/bin`, `~/.openclaw/bin`, and
+`~/.pi/bin` — no PATH configuration required (not needed for the modal mode).
+
+## OpenClaw
+
+Installed as a plugin, it registers the same `request_secret` tool. Note that
+the OpenClaw path executes the CLI in the foreground: keep the exec timeout
+longer than the TTL, or the link dies with the exec session.
+
+## CLI
+
+```sh
+pinchpass request <secret-name>... [flags]
+```
+
+| Flag       | Default   | Description                             |
+|------------|-----------|-----------------------------------------|
+| `-tunnel`  | false     | Open a bore.pub tunnel for a public URL |
+| `-note`    | —         | Description shown on the form           |
+| `-out`     | `.env`    | Output .env file path                   |
+| `-ttl`     | 30        | Minutes until the link expires          |
+| `-port`    | random    | Local port to bind                      |
+| `-json`    | false     | Machine-readable JSON output            |
+
+## License
+
+MIT

package/dist/index.js

@@ -1,5 +1,470 @@
-import { tool } from "@opencode-ai/plugin/tool";
-export default async ({ $ }) => {
+import { Type } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { spawn } from "node:child_process";
+import { accessSync, constants, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+/** Small figlet "small" font rendering of PINCHPASS. */
+const PINCHPASS_ART = "  ___ ___ _  _  ___ _  _ ___  _   ___ ___ \n" +
+    " | _ \\_ _| \\| |/ __| || | _ \\/_\\ / __/ __|\n" +
+    " |  _/| || .` | (__| __ |  _/ _ \\\\__ \\__ \\\n" +
+    " |_| |___|_|\\_|\\___|_||_|_|/_/ \\_\\___/___/";
+/** Extra directories where the postinstall script may have placed the binary. */
+const FALLBACK_DIRS = [
+    join(homedir(), ".local", "bin"),
+    join(homedir(), ".openclaw", "bin"),
+    join(homedir(), ".pi", "bin"),
+];
+function findBinary() {
+    const name = process.platform === "win32" ? "pinchpass.exe" : "pinchpass";
+    const sep = process.platform === "win32" ? ";" : ":";
+    const dirs = [...(process.env.PATH ?? "").split(sep).filter(Boolean), ...FALLBACK_DIRS];
+    for (const dir of dirs) {
+        try {
+            const candidate = join(dir, name);
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // keep looking
+        }
+    }
+    return null;
+}
+const BINARY_MISSING = `The pinchpass binary is not installed. Install it with one of:
+
+  npm i -g @pinchpass/cli      # downloads the prebuilt binary for your platform
+  go install github.com/rubybear-lgtm/pinchpass@latest
+
+Then try request_secret again.`;
+/** Pull complete JSON objects out of a (possibly pretty-printed) stream. */
+function takeJsonBlobs(text) {
+    const blobs = [];
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (c === "\\")
+                escaped = true;
+            else if (c === '"')
+                inString = false;
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            continue;
+        }
+        if (c === "{") {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (c === "}") {
+            depth--;
+            if (depth === 0 && start >= 0) {
+                try {
+                    blobs.push(JSON.parse(text.slice(start, i + 1)));
+                }
+                catch {
+                    // skip malformed output
+                }
+                start = -1;
+            }
+        }
+    }
+    return { blobs, rest: start >= 0 ? text.slice(start) : "" };
+}
+/** Shell-escape a value for a double-quoted .env line (mirrors store.go). */
+function escapeEnvValue(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`");
+}
+/** Write/update a single KEY="value" line in a .env file (mirrors store.go). */
+function writeEnvKey(path, key, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const line = `${key}="${escapeEnvValue(value)}"`;
+    let existing = "";
+    try {
+        existing = readFileSync(path, "utf8");
+    }
+    catch {
+        // new file
+    }
+    const out = [];
+    let replaced = false;
+    for (const l of existing.split("\n")) {
+        const t = l.trim();
+        if (t === "")
+            continue;
+        if (t.startsWith(key + "=")) {
+            out.push(line);
+            replaced = true;
+        }
+        else {
+            out.push(l);
+        }
+    }
+    if (!replaced)
+        out.push(line);
+    writeFileSync(path, out.join("\n") + "\n", { mode: 0o600 });
+}
+/**
+ * Branded masked secret dialog (Pi TUI overlay). The value is rendered as
+ * bullets, never echoed, and submitted straight to the caller.
+ */
+async function promptSecretTUI(ctx, name, note, signal) {
+    return ctx.ui.custom((tui, theme, _kb, done) => {
+        let value = "";
+        let alive = true;
+        const finish = (v) => {
+            if (!alive)
+                return;
+            alive = false;
+            if (signal)
+                signal.removeEventListener("abort", onAbort);
+            done(v);
+        };
+        const onAbort = () => finish(undefined);
+        if (signal) {
+            if (signal.aborted) {
+                onAbort();
+            }
+            else {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+        }
+        const comp = {
+            focused: true,
+            handleInput(data) {
+                if (!alive)
+                    return;
+                // Ignore escape sequences (arrows etc.) as a whole chunk.
+                if (data.startsWith("\u001b["))
+                    return;
+                if (data === "\u001b") {
+                    finish(undefined);
+                    return;
+                }
+                for (const ch of data) {
+                    if (ch === "\r" || ch === "\n") {
+                        finish(value);
+                        return;
+                    }
+                    if (ch === "\u0003") {
+                        finish(undefined);
+                        return;
+                    }
+                    if (ch === "\u007f" || ch === "\b") {
+                        value = value.slice(0, -1);
+                    }
+                    else if (ch >= " " && ch !== "\u007f") {
+                        value += ch;
+                    }
+                }
+                tui.requestRender(true);
+            },
+            invalidate() { },
+            render(width) {
+                const art = PINCHPASS_ART.split("\n");
+                const boxW = Math.min(width - 6, 46);
+                const pad = Math.max(0, Math.floor((width - boxW) / 2));
+                const lines = [];
+                lines.push("");
+                for (const a of art) {
+                    lines.push(" ".repeat(pad) + theme.fg("muted", a));
+                }
+                lines.push(" ".repeat(pad) + theme.fg("toolTitle", theme.bold(`  🔐  ${name}`)));
+                if (note)
+                    lines.push(" ".repeat(pad) + theme.fg("dim", `      ${note}`));
+                lines.push("");
+                const dots = Math.min(value.length, boxW - 8);
+                const mask = "•".repeat(dots);
+                const cursor = value.length < boxW - 8 ? "█" : "";
+                const inner = "  " + mask + cursor + " ".repeat(Math.max(0, boxW - 4 - dots - (cursor ? 1 : 0)));
+                lines.push(" ".repeat(pad) + theme.fg("borderAccent", "┌" + "─".repeat(boxW - 2) + "┐"));
+                lines.push(" ".repeat(pad) +
+                    theme.fg("borderAccent", "│") +
+                    theme.fg("accent", inner) +
+                    theme.fg("borderAccent", "│"));
+                lines.push(" ".repeat(pad) + theme.fg("borderAccent", "└" + "─".repeat(boxW - 2) + "┘"));
+                lines.push("");
+                lines.push(" ".repeat(pad) +
+                    theme.fg("dim", "enter submit") +
+                    theme.fg("muted", "    esc cancel"));
+                return lines;
+            },
+        };
+        return comp;
+    }, {
+        overlay: true,
+        overlayOptions: { width: "60%", minWidth: 54, maxHeight: "65%" },
+    });
+}
+/**
+ * Collect secrets directly in the Pi UI via modal dialogs. The value goes
+ * straight from the user's keyboard into the .env file — it is never sent to
+ * the LLM, never enters the session transcript, and no server is started.
+ */
+async function collectViaModal(ctx, params, signal) {
+    const outPath = resolve(ctx.cwd, params.out ?? ".env");
+    const saved = [];
+    for (const name of params.names) {
+        const value = ctx.mode === "tui"
+            ? await promptSecretTUI(ctx, name, params.note ?? "", signal)
+            : await ctx.ui.input(`Enter ${name}`, params.note ?? `Secret value for ${name}`, {
+                signal,
+            });
+        if (value === undefined) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Secret request cancelled — ${name} not provided.${saved.length ? ` (${saved.join(", ")} already saved)` : ""} No further secrets were collected.`,
+                    },
+                ],
+                details: { success: false, names: params.names, saved, aborted: true },
+            };
+        }
+        const trimmed = value.trim();
+        if (!trimmed) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Secret request cancelled — ${name} was empty.${saved.length ? ` (${saved.join(", ")} already saved)` : ""}`,
+                    },
+                ],
+                details: { success: false, names: params.names, saved, aborted: true },
+            };
+        }
+        writeEnvKey(outPath, name, trimmed);
+        saved.push(name);
+    }
+    return {
+        content: [
+            { type: "text", text: `✅ Secrets collected via Pi modal: ${saved.join(", ")}\nSaved to ${outPath}` },
+        ],
+        details: {
+            success: true,
+            names: saved,
+            message: "Secrets collected via Pi modal.",
+            url: undefined,
+            out: outPath,
+            aborted: false,
+        },
+    };
+}
+function buildArgs(params) {
+    const args = ["request", ...params.names, "-json"];
+    if (params.tunnel)
+        args.push("-tunnel");
+    if (params.note)
+        args.push("-note", params.note);
+    if (typeof params.ttl === "number")
+        args.push("-ttl", String(params.ttl));
+    if (params.out)
+        args.push("-out", params.out);
+    return args;
+}
+/* ------------------------------------------------------------------ */
+/* Pi native tool                                                      */
+/* ------------------------------------------------------------------ */
+function registerPiTool(pi) {
+    pi.registerTool({
+        name: "request_secret",
+        label: "Request Secret",
+        description: "Collect sensitive values (API keys, tokens, passwords, connection strings) from the user. " +
+            "With via='modal' (default in the Pi TUI) a dialog collects each value directly into the .env file — the value never reaches the LLM. " +
+            "With via='link' it starts a local pinchpass server and streams a one-time E2E-encrypted link to the user immediately, blocking until they submit or the TTL expires. " +
+            "On success the secrets are saved to the .env file and this tool returns the result.",
+        promptSnippet: "Collect secrets from the user through an encrypted one-time link or a Pi modal",
+        promptGuidelines: [
+            "Use request_secret when you need an API key, token, or password from the user — never ask them to paste secrets directly into chat.",
+            "request_secret streams the link (or shows the modal) to the user immediately; wait for its result before continuing.",
+            "Use request_secret with tunnel: true when the user is not on the same machine as this agent.",
+            "Use request_secret with via: 'link' to force the encrypted browser link, or via: 'modal' to force the Pi dialog.",
+        ],
+        parameters: Type.Object({
+            names: Type.Array(Type.String({ description: "Secret name(s) to collect, e.g. ['GEMINI_API_KEY']" }), {
+                minItems: 1,
+                description: "Secret name(s) to collect",
+            }),
+            tunnel: Type.Optional(Type.Boolean({ description: "Create a public URL via bore.pub tunnel (default: false)" })),
+            note: Type.Optional(Type.String({ description: "Description shown on the form to help the user" })),
+            ttl: Type.Optional(Type.Number({ description: "Minutes until the link expires (default: 30)" })),
+            out: Type.Optional(Type.String({ description: "Output .env file path (default: .env in the working directory)" })),
+            via: Type.Optional(StringEnum(["auto", "modal", "link"], {
+                description: "How to collect: 'modal' prompts in the Pi UI, 'link' generates the encrypted browser link, 'auto' picks modal in the TUI and link elsewhere (default: auto)",
+            })),
+        }),
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            const via = params.via ?? "auto";
+            const useModal = via === "modal" || (via === "auto" && ctx.mode === "tui");
+            if (useModal) {
+                if (!ctx.hasUI) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Modal collection is unavailable here (no interactive UI in this mode). Call request_secret again with via: 'link' to use the encrypted browser link.",
+                            },
+                        ],
+                        details: { success: false, names: params.names, error: "no-ui" },
+                    };
+                }
+                return collectViaModal(ctx, params, signal);
+            }
+            const binary = findBinary();
+            if (!binary) {
+                throw new Error(BINARY_MISSING);
+            }
+            const child = spawn(binary, buildArgs(params), {
+                cwd: ctx.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            let buffer = "";
+            let stderr = "";
+            const blobs = [];
+            const onAbort = () => {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    // already gone
+                }
+            };
+            if (signal)
+                signal.addEventListener("abort", onAbort, { once: true });
+            try {
+                const exitCode = await new Promise((resolve, reject) => {
+                    child.stdout.on("data", (chunk) => {
+                        buffer += chunk.toString("utf8");
+                        const { blobs: found, rest } = takeJsonBlobs(buffer);
+                        buffer = rest;
+                        for (const blob of found) {
+                            blobs.push(blob);
+                            const b = blob;
+                            if (b.url) {
+                                const ttlNote = b.message ? ` (${b.message})` : "";
+                                onUpdate?.({
+                                    content: [
+                                        {
+                                            type: "text",
+                                            text: `🔗 One-time E2E-encrypted secret request link${ttlNote}:\n${b.url}\n\nAsk the user to open it and submit ${(b.names ?? []).join(", ") || "the secret"}.`,
+                                        },
+                                    ],
+                                    details: { url: b.url, port: b.port, names: b.names ?? [] },
+                                });
+                            }
+                        }
+                    });
+                    child.stderr.on("data", (chunk) => {
+                        stderr += chunk.toString("utf8");
+                    });
+                    child.on("error", (err) => reject(err));
+                    child.on("close", (code) => resolve(code));
+                });
+                if (signal?.aborted) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Secret request cancelled (${params.names.join(", ")}). No value was saved.`,
+                            },
+                        ],
+                        details: { success: false, names: params.names, aborted: true },
+                    };
+                }
+                const firstBlob = blobs[0];
+                const lastBlob = blobs[blobs.length - 1];
+                if (!lastBlob) {
+                    throw new Error(`pinchpass exited without JSON output (code ${exitCode}).${stderr ? `\n${stderr}` : ""}`);
+                }
+                const success = lastBlob.success === true;
+                const lines = success
+                    ? [`✅ Secrets collected: ${(lastBlob.names ?? params.names).join(", ")}`]
+                    : [`❌ ${lastBlob.message ?? "Secret request failed."}`];
+                if (firstBlob?.url)
+                    lines.push(`Link: ${firstBlob.url}`);
+                if (success)
+                    lines.push(`Saved to ${params.out ?? ".env"} in ${ctx.cwd}`);
+                return {
+                    content: [{ type: "text", text: lines.join("\n") }],
+                    details: {
+                        success,
+                        names: lastBlob.names ?? params.names,
+                        url: firstBlob?.url,
+                        message: lastBlob.message,
+                        port: lastBlob.port,
+                        out: resolve(ctx.cwd, params.out ?? ".env"),
+                        aborted: false,
+                    },
+                };
+            }
+            finally {
+                if (signal)
+                    signal.removeEventListener("abort", onAbort);
+            }
+        },
+        /* Pretty TUI rendering: call line, result card. */
+        renderCall(args, theme) {
+            const names = (args.names ?? []).join(", ");
+            const via = args.via ?? "auto";
+            let text = theme.fg("accent", "🔐 ") +
+                theme.fg("toolTitle", theme.bold("pinchpass")) +
+                theme.fg("dim", " · ") +
+                theme.fg("accent", names);
+            if (args.tunnel)
+                text += theme.fg("dim", " · tunnel");
+            text += theme.fg("muted", ` · ${via}`);
+            return new Text(text, 0, 0);
+        },
+        renderResult(result, options, theme) {
+            if (options.isPartial) {
+                return new Text(theme.fg("warning", "⏳ Waiting for the user to submit…"), 0, 0);
+            }
+            const details = (result.details ?? {});
+            const success = details.success === true;
+            const aborted = details.aborted === true;
+            const names = (details.names ?? []).join(", ");
+            const bg = success ? "toolSuccessBg" : aborted ? "toolPendingBg" : "toolErrorBg";
+            const box = new Box(1, 1, (t) => theme.bg(bg, t));
+            const statusColor = success ? "success" : aborted ? "warning" : "error";
+            const head = success
+                ? "✅  Secrets collected"
+                : aborted
+                    ? "✋  Cancelled"
+                    : `❌  ${details.message ?? "Failed"}`;
+            box.addChild(new Text(theme.fg("toolTitle", theme.bold(head))));
+            if (names)
+                box.addChild(new Text(theme.fg(statusColor, `     ${names}`)));
+            if (options.expanded) {
+                box.addChild(new Text(""));
+                if (details.url)
+                    box.addChild(new Text(theme.fg("dim", `     Link: ${details.url}`)));
+                if (details.out)
+                    box.addChild(new Text(theme.fg("dim", `     Saved to: ${details.out}`)));
+                if (details.message)
+                    box.addChild(new Text(theme.fg("muted", `     ${details.message}`)));
+                box.addChild(new Text(""));
+                for (const line of PINCHPASS_ART.split("\n")) {
+                    box.addChild(new Text(theme.fg("muted", `     ${line}`)));
+                }
+            }
+            return box;
+        },
+    });
+}
+/* ------------------------------------------------------------------ */
+/* OpenClaw plugin (backward compatible)                               */
+/* ------------------------------------------------------------------ */
+async function registerOpenClawTool(api) {
+    const { tool } = await import("@opencode-ai/plugin/tool");
     return {
         tool: {
             request_secret: tool({
@@ -16,17 +481,12 @@ export default async ({ $ }) => {
                         .boolean()
                         .optional()
                         .describe("Create a public URL via bore.pub tunnel (default: false)"),
-                    note: tool.schema
-                        .string()
-                        .optional()
-                        .describe("Description shown on the form to help the user"),
-                    ttl: tool.schema
-                        .number()
-                        .optional()
-                        .describe("Minutes until the link expires (default: 30)"),
+                    note: tool.schema.string().optional().describe("Description shown on the form to help the user"),
+                    ttl: tool.schema.number().optional().describe("Minutes until the link expires (default: 30)"),
                 },
                 async execute(args) {
-                    const pieces = ["pinchpass", "request", ...args.names, "-json"];
+                    const binary = findBinary() ?? "pinchpass";
+                    const pieces = [binary, "request", ...args.names, "-json"];
                     if (args.tunnel)
                         pieces.push("-tunnel");
                     if (args.note)
@@ -34,18 +494,27 @@ export default async ({ $ }) => {
                     if (args.ttl)
                         pieces.push("-ttl", String(args.ttl));
                     try {
-                        const result = await $.raw(pieces);
-                        return result.stdout || result.text || String(result);
+                        const result = await api.$.raw(pieces);
+                        return result?.stdout ||
+                            result?.text ||
+                            String(result);
                     }
                     catch (err) {
                         const msg = err instanceof Error ? err.message : String(err);
-                        const stderr = err && typeof err === "object" && "stderr" in err
-                            ? err.stderr
-                            : "";
+                        const stderr = err && typeof err === "object" && "stderr" in err ? err.stderr : "";
                         return `Failed: ${msg}${stderr ? "\n" + stderr : ""}`;
                     }
                 },
             }),
         },
     };
-};
+}
+export default async function (api) {
+    const pi = api;
+    if (pi && typeof pi.registerTool === "function") {
+        registerPiTool(pi);
+        return;
+    }
+    // OpenClaw plugin contract: default export receives `{ $ }` and returns `{ tool }`.
+    return registerOpenClawTool((api ?? {}));
+}

package/package.json

@@ -1,27 +1,54 @@
 {
   "name": "@pinchpass/cli",
-  "version": "1.0.6",
-  "description": "One-time E2E-encrypted secret request links for OpenClaw agents",
+  "version": "1.1.0",
+  "description": "One-time E2E-encrypted secret request links — native for Pi and OpenClaw agents",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rubybear-lgtm/PinchPass.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pinchpass",
+    "secrets",
+    "api-key",
+    "e2e-encryption",
+    "openclaw"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "files": [
     "dist",
-    "SKILL.md",
+    "skills",
     "openclaw.plugin.json",
-    "scripts"
+    "scripts",
+    "README.md"
   ],
+  "pi": {
+    "extensions": ["./dist/index.js"],
+    "skills": ["./skills"]
+  },
   "openclaw": {
     "extensions": ["./dist/index.js"]
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node scripts/copy-skill.js",
     "postinstall": "node scripts/install-binary.js",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.16.2"
   },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
   "devDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "^1.3.7",
     "typescript": "^5.9.0"
   },
   "publishConfig": {

package/scripts/copy-skill.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Copies the canonical universal skill from the repo root
+ * (skills/pinchpass/SKILL.md) into the package (skills/pinchpass/SKILL.md)
+ * so the Pi package ships the exact same skill as skills.sh.
+ */
+import { copyFileSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(here, "..");
+const repoRoot = join(packageRoot, "..", "..");
+
+const src = join(repoRoot, "skills", "pinchpass", "SKILL.md");
+const dest = join(packageRoot, "skills", "pinchpass", "SKILL.md");
+
+mkdirSync(dirname(dest), { recursive: true });
+copyFileSync(src, dest);
+console.log(`Copied skill → ${dest}`);

package/scripts/install-binary.js

@@ -1,34 +1,86 @@
 #!/usr/bin/env node
-
+/**
+ * Downloads the prebuilt pinchpass binary for the current platform.
+ *
+ * Install locations (first hit wins):
+ *   1. If `pinchpass` is already on PATH, nothing to do.
+ *   2. If it already exists in a known install dir, nothing to do.
+ *   3. Install to ~/.local/bin (universal user bin — the PinchPass Pi
+ *      extension and OpenClaw plugin both find it there without PATH changes).
+ *
+ * The Pi extension resolves the binary from PATH, then from
+ * ~/.local/bin, ~/.openclaw/bin, and ~/.pi/bin — so PATH is never required.
+ */
 import { execSync } from "child_process";
-import { existsSync, mkdirSync, writeFileSync, chmodSync } from "fs";
-import { homedir, platform } from "os";
+import { chmodSync, existsSync, mkdirSync, statSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 
 const VERSION = "latest";
 const REPO = "rubybear-lgtm/PinchPass";
 
+/** Real pinchpass binaries are multi-MB; "installed" stubs are tiny (e.g. a failed curl). */
+const MIN_VALID_BYTES = 100 * 1024;
+
+function isValidBinary(path) {
+  try {
+    return statSync(path).size >= MIN_VALID_BYTES;
+  } catch {
+    return false;
+  }
+}
+
 function detectBinary() {
   const arch = process.arch === "arm64" ? "arm64" : "amd64";
-  const osMap = {
-    darwin: "darwin",
-    linux: "linux",
-    win32: "windows",
-  };
+  const osMap = { darwin: "darwin", linux: "linux", win32: "windows" };
   const plat = osMap[process.platform];
   if (!plat) throw new Error(`Unsupported platform: ${process.platform}`);
   return { name: `pinchpass-${plat}-${arch}`, plat, arch };
 }
 
+function onPath(name) {
+  try {
+    const found = execSync(
+      process.platform === "win32" ? `where ${name}` : `which ${name}`,
+      { stdio: ["ignore", "pipe", "ignore"], shell: true },
+    )
+      .toString()
+      .trim()
+      .split(/\r?\n/)[0];
+    return found || null;
+  } catch {
+    return null;
+  }
+}
+
 async function install() {
   const { name } = detectBinary();
-  const installDir = `${homedir()}/.openclaw/bin`;
-  const dest = `${installDir}/pinchpass`;
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const knownDirs = [
+    join(homedir(), ".local", "bin"),
+    join(homedir(), ".openclaw", "bin"),
+    join(homedir(), ".pi", "bin"),
+  ];
 
-  if (existsSync(dest)) {
-    console.log(`pinchpass already installed at ${dest}`);
+  // 1. Already on PATH?
+  const onPathLocation = onPath(`pinchpass${exe}`);
+  if (onPathLocation && isValidBinary(onPathLocation)) {
+    console.log(`pinchpass already available on PATH at ${onPathLocation}`);
     return;
   }
 
+  // 2. Already installed in a known dir? (skip broken stubs from failed downloads)
+  for (const dir of knownDirs) {
+    const candidate = join(dir, `pinchpass${exe}`);
+    if (existsSync(candidate) && isValidBinary(candidate)) {
+      console.log(`pinchpass already installed at ${candidate}`);
+      return;
+    }
+  }
+
+  // 3. Install to ~/.local/bin (universal user bin).
+  const installDir = join(homedir(), ".local", "bin");
+  const dest = join(installDir, `pinchpass${exe}`);
   const url =
     VERSION === "latest"
       ? `https://github.com/${REPO}/releases/latest/download/${name}`
@@ -37,22 +89,19 @@ async function install() {
   console.log(`Downloading pinchpass from ${url}...`);
 
   mkdirSync(installDir, { recursive: true });
-
-  if (process.platform === "win32") {
-    execSync(`curl -sL "${url}" -o "${dest}.exe"`, { stdio: "inherit" });
-  } else {
-    execSync(`curl -sL "${url}" -o "${dest}"`, { stdio: "inherit" });
-    chmodSync(dest, 0o755);
-  }
+  execSync(`curl -sL "${url}" -o "${dest}"`, { stdio: "inherit" });
+  if (process.platform !== "win32") chmodSync(dest, 0o755);
 
   console.log(`Installed pinchpass to ${dest}`);
-  console.log(`Add ${installDir} to your PATH if not already present.`);
+  const onPathNow = onPath(`pinchpass${exe}`);
+  if (!onPathNow) {
+    console.log(`Add ${installDir} to your PATH if you want to use the CLI directly.`);
+    console.log("(The PinchPass Pi extension and OpenClaw plugin find the binary without PATH changes.)");
+  }
 }
 
 install().catch((err) => {
   console.error(`Failed to install pinchpass binary: ${err.message}`);
-  console.log(
-    `To build from source: cd pinchpass-plugin && go build -o pinchpass .`
-  );
+  console.log(`To build from source: cd pinchpass && go build -o pinchpass .`);
   process.exit(1);
 });

package/skills/pinchpass/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: pinchpass
+description: "Collect sensitive values (API keys, tokens, passwords, credentials) from the user via a one-time E2E-encrypted link. Use when you need a secret the user hasn't provided, when populating a .env file with credentials, or when the user says they need to give you a key/token/password. "
+---
+
+Securely collect sensitive values from users with end-to-end encryption. The
+relay server never sees the plaintext — encryption happens in the browser, and
+the decryption key lives only in the URL fragment (never sent to the server).
+
+## When to use
+
+- An agent needs a value it does not have (API key, token, password, etc.)
+- The user says "I need to give you a secret" or "where do I put my key?"
+- A `.env` file needs to be populated with credentials
+
+Do **not** use for non-sensitive plaintext — there is no reason to go through
+E2E encryption for a public value. Just ask the user to paste it directly.
+
+## Install
+
+Check that `pinchpass` is available:
+
+```bash
+which pinchpass
+```
+
+If missing, install it (pick one):
+
+```bash
+# Pi (native package — registers the request_secret tool and this skill)
+pi install npm:@pinchpass/cli
+```
+
+```bash
+# Any agent (npm — downloads the prebuilt binary)
+npm i -g @pinchpass/cli
+```
+
+```bash
+# From source (requires Go 1.25+)
+go install github.com/rubybear-lgtm/pinchpass@latest
+```
+
+```bash
+# Prebuilt binary — pick the right platform/arch from:
+# https://github.com/rubybear-lgtm/PinchPass/releases
+curl -sL https://github.com/rubybear-lgtm/PinchPass/releases/latest/download/pinchpass-darwin-arm64 -o /usr/local/bin/pinchpass
+chmod +x /usr/local/bin/pinchpass
+```
+
+## Usage
+
+Always use `-json` mode so you can parse the output programmatically.
+
+```bash
+pinchpass request <secret-name>... [flags]
+```
+
+Bare `pinchpass <name>` also works (auto-detects missing subcommand).
+
+### Collect a single secret
+
+```bash
+pinchpass request SECRET_NAME -json
+```
+
+### Collect multiple secrets at once
+
+```bash
+pinchpass request KEY_A KEY_B KEY_C -json
+```
+
+### Create a public link via tunnel
+
+```bash
+pinchpass request SECRET_NAME -tunnel -json
+```
+
+Use `-tunnel` when the user is not on the same machine (the default binds to
+`127.0.0.1` only).
+
+### All flags
+
+| Flag           | Default       | Description                              |
+|----------------|---------------|------------------------------------------|
+| `-tunnel`      | false         | Open a bore.pub tunnel for a public URL  |
+| `-note`        | —             | Description shown on the form            |
+| `-out`         | `.env`        | Output .env file path                    |
+| `-ttl`         | 30            | Minutes until the link expires           |
+| `-port`        | random        | Local port to bind                       |
+| `-listen-addr` | `127.0.0.1`   | Address to listen on                     |
+| `-json`        | false         | Machine-readable JSON output             |
+
+## Pi-native tool
+
+On Pi, the `@pinchpass/cli` package registers a **`request_secret`** tool with
+two collection modes (`via` param):
+
+- **`modal`** (default in the interactive TUI): a Pi dialog collects each
+  secret directly into the `.env` file. The value goes straight from the
+  user's keyboard to disk — never to the LLM, never into the transcript, no
+  server, no network. Cancelable with `Esc`.
+- **`link`**: spawns the CLI, streams the one-time E2E-encrypted browser link
+  to the user immediately, blocks until submit/TTL. Use when the user is not
+  in the same Pi session (remote, tunneled, or RPC clients without a dialog
+  handler).
+
+`via` defaults to `auto`: modal in the TUI, link elsewhere. Prefer the tool on
+Pi; use the CLI workflow below on other agents.
+
+## Workflow
+
+1. Run `pinchpass request <name>... -json` in the background.
+2. Parse the first JSON blob from stdout — it contains the `url` field.
+3. Present the URL to the user and tell them to open it in a browser.
+4. Wait for the process to exit (it blocks until the user submits or TTL expires).
+5. Parse the second JSON blob — `success: true` means the value was saved to `.env`.
+
+### JSON output
+
+Two JSON objects are printed to stdout, one before waiting and one after:
+
+**Before waiting:**
+```json
+{"success": true, "names": ["SECRET_NAME"], "url": "http://...", "port": 12345, "message": "..."}
+```
+
+**After completion:**
+```json
+{"success": true, "names": ["SECRET_NAME"], "port": 12345, "message": "Secrets provisioned successfully."}
+```
+
+If `success` is false, the request timed out — no value was saved.
+
+### Workflow example
+
+```bash
+# Collect an API key via public tunnel
+pinchpass request API_KEY -tunnel -json
+# → Prints link object with url field
+# → Agent gives url to user
+# → Agent waits for result
+# → On completion, value in .env
+```
+
+## Important behavior
+
+- **Blocking + exec timeouts**: `pinchpass` blocks until the user submits or
+  TTL expires. If your agent's shell/exec tool has a command timeout (e.g.
+  OpenClaw's `exec` tool defaults to 1800s), it **will kill pinchpass** when
+  the timeout fires — and the bore tunnel dies with it, making the link return
+  "Connection refused." You MUST disable or raise the exec timeout so it
+  exceeds the TTL. Agent-specific guidance:
+  - **OpenClaw**: pass `timeout: 0` in the exec tool call (disables the exec
+    process timeout), and use `background: true` (or `yieldMs`) so you can
+    present the URL from the first JSON blob while pinchpass waits. Poll the
+    process or watch for the `.env` file to appear.
+  - **Claude Code / opencode**: use `run_in_background` / background bash. The
+    background session is not subject to the foreground command timeout.
+  - **Other agents**: if the agent has no background/timeout-free mode, run
+    pinchpass detached: `setsid nohup pinchpass request NAME -tunnel -json
+    > /tmp/pinchpass.json 2>&1 &` then read `/tmp/pinchpass.json` for the URL.
+    The process survives the agent's exec session. Check for the `.env` file
+    or poll `ps` to detect completion.
+- **One-time use**: after the first submission, the token is consumed. A second
+  POST returns 404. If it fails, generate a new link.
+- **TTL expiry**: the server shuts down after the TTL. Exit code is 1. Generate
+  a new link with a longer `-ttl` if needed. Keep the TTL shorter than the exec
+  timeout so pinchpass exits on its own before the agent can kill it.
+- **Shell escaping**: values in `.env` are shell-escaped (`\`, `"`, `$`, `` ` ``).
+  Existing keys are overwritten in place.
+- **No tunnel**: without `-tunnel`, the link is only reachable on
+  `127.0.0.1:<port>`. Use for local-only workflows or when the user is on the
+  same machine.
+- **bore.pub unreachable**: tunnel startup fails if bore.pub is down. Fall back
+  to local mode or retry.

package/SKILL.md

@@ -1,81 +0,0 @@
----
-name: pinchpass
-description: Generate one-time E2E-encrypted secret request links via pinchpass. Use when an agent needs to collect API keys, tokens, passwords, connection strings, or any sensitive value from the user. Trigger on keywords: API key, secret, token, credentials, password, .env.
-version: 1.0.0
-homepage: https://github.com/rubybear-lgtm/PinchPass
-metadata: { "openclaw": { "requires": { "bins": ["pinchpass"] } } }
----
-
-# pinchpass
-
-Securely collect sensitive values from users with end-to-end encryption. The
-relay never sees the secret — encryption happens in the browser, the key lives
-only in the URL fragment.
-
-## When to use
-
-- An agent needs a value it does not have (API key, token, password, etc.)
-- The user says "I need to give you a secret" or "where do I put my key?"
-- A `.env` file needs to be populated with credentials
-
-Do **not** use for non-sensitive plaintext — there is no reason to go through
-E2E encryption for a public value.
-
-## CLI
-
-```bash
-pinchpass request <secret-name>... [flags]
-```
-
-Bare `pinchpass <name>` also works (auto-detects missing subcommand).
-
-### Flags
-
-| Flag          | Default       | Description                              |
-|---------------|---------------|------------------------------------------|
-| `-tunnel`     | false         | Open a bore.pub tunnel for a public URL  |
-| `-note`       | —             | Description shown on the form            |
-| `-out`        | `.env`        | Output .env file path                    |
-| `-ttl`        | 30            | Minutes until the link expires           |
-| `-port`       | random        | Local port to bind                       |
-| `-listen-addr`| `127.0.0.1`   | Address to listen on                     |
-| `-json`       | false         | Machine-readable JSON output             |
-
-## Workflow
-
-1. Run `pinchpass request <name> -json` to get a link
-2. Give the link to the user (the fragment `#k=<hex>` is the decryption key)
-3. User opens the link in a browser, fills in the value, submits
-4. Server waits for the submission or TTL expiry
-5. On success, the value is decrypted and written to `.env`
-
-### JSON output mode
-
-Use `-json` for machine parsing. The JSON is printed twice:
-- **Before waiting**: `{ "success": true, "url": "...", "port": N }`
-- **After completion**: `{ "success": true/false, "names": [...], "message": "..." }`
-
-## Workflow example
-
-```bash
-# Collect an API key via public tunnel
-pinchpass request GEMINI_API_KEY -tunnel -json
-# → Prints link object with url field
-# → Agent gives url to user
-# → Agent waits for result
-# → On completion, value in .env
-```
-
-## Edge cases
-
-- **One-time use**: after the first POST, the token is consumed. Retry
-  generates a 404. If it fails, generate a new link.
-- **TTL expiry**: server shuts down after the TTL. No value is saved and exit
-  code is 1. Generate a new link with a longer `-ttl` if needed.
-- **No tunnel**: without `-tunnel`, the link is only reachable on
-  `127.0.0.1:<port>`. Use for local-only workflows or when the user is on the
-  same machine.
-- **Bore.pub unreachable**: tunnel startup fails if bore.pub is down. Fall
-  back to local mode or retry.
-- **Shell escaping**: values written to `.env` are shell-escaped for `\`,
-  `"`, `$`, and backtick.