@pinchpass/cli 1.1.0 → 1.2.0

package/dist/json-stream.js

@@ -0,0 +1,48 @@
+/**
+ * Incremental parser for the CLI's `-json` output.
+ *
+ * The CLI prints two pretty-printed JSON objects (before and after waiting),
+ * so a byte stream can split them across chunks. `takeJsonBlobs` returns every
+ * complete top-level object and leaves any partial trailing object in `rest`.
+ */
+export 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 = Math.max(0, depth - 1);
+            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) : "" };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinchpass/cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "One-time E2E-encrypted secret request links — native for Pi and OpenClaw agents",
   "repository": {
     "type": "git",
@@ -24,32 +24,44 @@
     "README.md"
   ],
   "pi": {
-    "extensions": ["./dist/index.js"],
-    "skills": ["./skills"]
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/rubybear-lgtm/PinchPass/master/pinchpass.png"
   },
   "openclaw": {
-    "extensions": ["./dist/index.js"]
+    "extensions": [
+      "./dist/index.js"
+    ]
   },
   "scripts": {
     "build": "tsc && node scripts/copy-skill.js",
+    "test": "npm run build && node --test \"test/**/*.test.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": "*",
+    "@opencode-ai/plugin": "^1.16.2",
     "typebox": "*"
   },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
   "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"
+    "@earendil-works/pi-ai": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0",
+    "@opencode-ai/plugin": "^1.19.0",
+    "typebox": "^1.3.37",
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"

package/scripts/install-binary.js

@@ -1,27 +1,94 @@
 #!/usr/bin/env node
 /**
- * Downloads the prebuilt pinchpass binary for the current platform.
+ * Install or update the 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).
+ * npm runs this as a `postinstall`, so it must be idempotent and it must make
+ * `npm update -g @pinchpass/cli` actually upgrade the binary:
  *
- * The Pi extension resolves the binary from PATH, then from
- * ~/.local/bin, ~/.openclaw/bin, and ~/.pi/bin — so PATH is never required.
+ *   1. Look for an existing `pinchpass` (PATH, then the known install dirs).
+ *   2. If one already reports the package's version, do nothing.
+ *   3. Otherwise download the release asset pinned to the package version,
+ *      verify it against the release's checksums.txt, and install it to
+ *      ~/.local/bin.
+ *
+ * Set PINCHPASS_SKIP_DOWNLOAD=1 to skip the download entirely (used by CI).
  */
-import { execSync } from "child_process";
-import { chmodSync, existsSync, mkdirSync, statSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
-const VERSION = "latest";
 const REPO = "rubybear-lgtm/PinchPass";
 
-/** Real pinchpass binaries are multi-MB; "installed" stubs are tiny (e.g. a failed curl). */
+/** Real binaries are multi-MB; a failed download leaves a tiny stub behind. */
 const MIN_VALID_BYTES = 100 * 1024;
 
+const here = dirname(fileURLToPath(import.meta.url));
+
+export function packageVersion() {
+  return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version;
+}
+
+export function binaryName(platform = process.platform) {
+  return platform === "win32" ? "pinchpass.exe" : "pinchpass";
+}
+
+export function assetName(platform = process.platform, arch = process.arch) {
+  const os = { darwin: "darwin", linux: "linux", win32: "windows" }[platform];
+  if (!os) throw new Error(`Unsupported platform: ${platform}`);
+  return `pinchpass-${os}-${arch === "arm64" ? "arm64" : "amd64"}`;
+}
+
+/** Extract an x.y.z version from `pinchpass --version` output. */
+export function parseVersion(text) {
+  const match = /(?:^|\s)v?(\d+\.\d+\.\d+)(?=\s|$)/.exec(text ?? "");
+  return match ? match[1] : null;
+}
+
+/** Numeric x.y.z comparison. Returns -1, 0, or 1. */
+export function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+export function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Find the SHA-256 for `asset` in a checksums.txt body. */
+export function checksumFor(text, asset) {
+  for (const line of (text ?? "").split("\n")) {
+    const [hash, name] = line.trim().split(/\s+/);
+    if (name === asset && /^[0-9a-f]{64}$/i.test(hash)) return hash.toLowerCase();
+  }
+  return null;
+}
+
+export function knownDirs(home = homedir()) {
+  return [join(home, ".local", "bin"), join(home, ".openclaw", "bin"), join(home, ".pi", "bin")];
+}
+
+function searchDirs() {
+  const sep = process.platform === "win32" ? ";" : ":";
+  return [...(process.env.PATH ?? "").split(sep).filter(Boolean), ...knownDirs()];
+}
+
 function isValidBinary(path) {
   try {
     return statSync(path).size >= MIN_VALID_BYTES;
@@ -30,78 +97,125 @@ function isValidBinary(path) {
   }
 }
 
-function detectBinary() {
-  const arch = process.arch === "arm64" ? "arm64" : "amd64";
-  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) {
+/** Read the version a binary reports; null for pre-1.2.0 builds (no --version). */
+export function readBinaryVersion(bin) {
   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;
+    const out = execFileSync(bin, ["--version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    });
+    return parseVersion(out);
   } catch {
     return null;
   }
 }
 
-async function install() {
-  const { name } = detectBinary();
-  const exe = process.platform === "win32" ? ".exe" : "";
-  const knownDirs = [
-    join(homedir(), ".local", "bin"),
-    join(homedir(), ".openclaw", "bin"),
-    join(homedir(), ".pi", "bin"),
-  ];
-
-  // 1. Already on PATH?
-  const onPathLocation = onPath(`pinchpass${exe}`);
-  if (onPathLocation && isValidBinary(onPathLocation)) {
-    console.log(`pinchpass already available on PATH at ${onPathLocation}`);
-    return;
+export function findExisting(name, dirs = searchDirs()) {
+  for (const dir of dirs) {
+    const candidate = join(dir, name);
+    if (existsSync(candidate) && isValidBinary(candidate)) return candidate;
   }
+  return null;
+}
 
-  // 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;
+async function fetchBytes(url) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) return { ok: false, status: res.status };
+  return { ok: true, bytes: Buffer.from(await res.arrayBuffer()) };
+}
+
+/** Download the asset for `version`, falling back to `latest` if it is missing. */
+export async function downloadAsset(asset, version) {
+  const versioned = `https://github.com/${REPO}/releases/download/v${version}/${asset}`;
+  const first = await fetchBytes(versioned);
+  if (first.ok) {
+    return { bytes: first.bytes, base: versioned.slice(0, -asset.length - 1) };
+  }
+
+  const latest = `https://github.com/${REPO}/releases/latest/download/${asset}`;
+  const second = await fetchBytes(latest);
+  if (second.ok) {
+    return { bytes: second.bytes, base: latest.slice(0, -asset.length - 1), fallback: true };
+  }
+  throw new Error(`could not download ${asset} (v${version}: ${first.status}, latest: ${second.status})`);
+}
+
+/** Returns "verified", "missing", or throws on a checksum mismatch. */
+export async function verifyChecksum(asset, bytes, base) {
+  const res = await fetch(`${base}/checksums.txt`, { redirect: "follow" });
+  if (!res.ok) return "missing";
+  const expected = checksumFor(await res.text(), asset);
+  if (!expected) return "missing";
+  if (expected !== sha256(bytes)) throw new Error(`checksum mismatch for ${asset}`);
+  return "verified";
+}
+
+function writeExecutable(target, bytes) {
+  mkdirSync(dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.tmp`;
+  writeFileSync(tmp, bytes, { mode: 0o755 });
+  if (process.platform !== "win32") chmodSync(tmp, 0o755);
+  try {
+    renameSync(tmp, target);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // nothing to clean up
     }
+    throw err;
+  }
+}
+
+export async function install({ log = console.log, warn = console.warn } = {}) {
+  if (process.env.PINCHPASS_SKIP_DOWNLOAD) {
+    log("pinchpass: PINCHPASS_SKIP_DOWNLOAD set; skipping binary download");
+    return { installed: false, reason: "skipped" };
+  }
+
+  const version = packageVersion();
+  const name = binaryName();
+  const existing = findExisting(name);
+  const existingVersion = existing ? readBinaryVersion(existing) : null;
+
+  if (existing && existingVersion === version) {
+    log(`pinchpass ${version} already installed at ${existing}`);
+    return { installed: false, reason: "up-to-date", path: existing };
+  }
+
+  const asset = assetName();
+  const { bytes, base, fallback } = await downloadAsset(asset, version);
+  if (fallback) {
+    warn(`pinchpass: no release asset for v${version}; installed the latest release instead`);
   }
 
-  // 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}`
-      : `https://github.com/${REPO}/releases/download/v${VERSION}/${name}`;
-
-  console.log(`Downloading pinchpass from ${url}...`);
-
-  mkdirSync(installDir, { recursive: true });
-  execSync(`curl -sL "${url}" -o "${dest}"`, { stdio: "inherit" });
-  if (process.platform !== "win32") chmodSync(dest, 0o755);
-
-  console.log(`Installed pinchpass to ${dest}`);
-  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.)");
+  const checksum = await verifyChecksum(asset, bytes, base);
+  if (checksum !== "verified") {
+    warn(`pinchpass: checksums.txt unavailable for ${asset}; installed without verification`);
   }
+
+  const target = join(homedir(), ".local", "bin", name);
+  writeExecutable(target, bytes);
+
+  const from = existingVersion ? `v${existingVersion}` : "no previous binary";
+  log(`pinchpass: ${from} -> ${fallback ? "the latest release" : `v${version}`} at ${target}`);
+
+  if (existing && existing !== target && !knownDirs().some((dir) => existing.startsWith(dir))) {
+    warn(`pinchpass: ${existing} shadows the new binary on PATH — remove or update it`);
+  }
+  return { installed: true, version, path: target, checksum };
 }
 
-install().catch((err) => {
-  console.error(`Failed to install pinchpass binary: ${err.message}`);
-  console.log(`To build from source: cd pinchpass && go build -o pinchpass .`);
-  process.exit(1);
-});
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  install().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    // Never fail the npm install: an existing binary or `go install` still works.
+    console.warn(`pinchpass: could not install the binary — ${message}`);
+    console.warn(
+      "pinchpass: install it later with `go install github.com/rubybear-lgtm/pinchpass@latest` or `npm i -g @pinchpass/cli`",
+    );
+  });
+}

package/skills/pinchpass/SKILL.md

@@ -26,6 +26,11 @@ which pinchpass
 
 If missing, install it (pick one):
 
+```bash
+# Homebrew (macOS and Linux, via the tap)
+brew install --cask rubybear-lgtm/tap/pinchpass
+```
+
 ```bash
 # Pi (native package — registers the request_secret tool and this skill)
 pi install npm:@pinchpass/cli
@@ -37,7 +42,7 @@ npm i -g @pinchpass/cli
 ```
 
 ```bash
-# From source (requires Go 1.25+)
+# From source (requires Go 1.26+)
 go install github.com/rubybear-lgtm/pinchpass@latest
 ```
 
@@ -48,6 +53,10 @@ curl -sL https://github.com/rubybear-lgtm/PinchPass/releases/latest/download/pin
 chmod +x /usr/local/bin/pinchpass
 ```
 
+Check the build with `pinchpass --version`, and update through the channel you
+installed with — `brew upgrade --cask pinchpass`, `npm update -g @pinchpass/cli`,
+or `go install github.com/rubybear-lgtm/pinchpass@latest`.
+
 ## Usage
 
 Always use `-json` mode so you can parse the output programmatically.
@@ -99,14 +108,24 @@ 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`.
+  server, no network. Cancelable with `Esc`. `ttl` does not apply to this mode
+  and is ignored.
 - **`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.
+`via` defaults to `auto`: modal in the TUI, link elsewhere. Setting
+`tunnel: true` always uses the link, even in the TUI, because the modal cannot
+serve a remote user.
+
+**Privacy note:** in `link` mode the full URL — including the `#k=` decryption
+key fragment — is returned to the model and recorded in the transcript. Only
+`modal` keeps the secret out of the transcript entirely. Prefer `modal` when
+the user is local and the value is sensitive; use `link` when you must send a
+URL over a channel the model can see.
+
+Prefer the tool on Pi; use the CLI workflow below on other agents.
 
 ## Workflow