pi-creel 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# pi-creel
+
+`request_secret` for the pi coding agent — capture an API key into a local
+`.env` **without it ever entering the chat/context**.
+
+When the model needs a secret, it calls `request_secret` instead of asking the
+user to paste one into the transcript. The tool opens a masked
+`tmux display-popup` running the [`creel`](https://tackle.tools) binary; the
+user pastes once, and the value goes straight from the popup into the target
+`.env`. The pi process — and therefore the model — receives only a status token
+(`added` / `updated` / `cancelled` / `error`), never the value.
+
+## Tool
+
+`request_secret(name, dest?)`
+
+- `name` — the environment-variable name, e.g. `OPENAI_API_KEY`.
+- `dest` — path to the `.env` (relative to cwd), default `.env`.
+
+## Requirements
+
+- A tmux session (`$TMUX`). Without one the tool fails fast and asks the user to
+  paste manually.
+- The `creel` binary on `PATH` (installed via the tackle family download /
+  kempt). Without it the tool returns an actionable error.
+
+## How the value stays out of context
+
+`creel` does the masked read, the `.env` upsert (atomic, `chmod 600`), and the
+gitignore check inside the popup. It writes only a one-word status token to a
+temp file that this extension polls. The seam between the two —
+`creel <NAME> --dest <PATH> --status-file <FILE>` — carries a name, a
+destination, and a token, and nothing else. The same seam lets other harnesses
+(Claude Code / Cursor, via a future `creel mcp`) reuse the identical capture
+core.
+
+## Design
+
+Pure pieces (schema, popup command, token→reply mapping) live in `capture.ts`;
+`index.ts` is thin, injectable pi/tmux/fs wiring — the same split as `pi-wakeup`.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-creel",
+  "version": "0.1.0",
+  "description": "request_secret for the pi coding agent: capture an API key into a local .env via a tmux popup (the creel tool) so it never enters the chat/context.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schuettc/pi-extensions.git",
+    "directory": "packages/pi-creel"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "secret",
+    "api-key",
+    "dotenv"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test src/*.test.ts"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "typescript": "^5.6.0"
+  }
+}

package/src/capture.test.ts

@@ -0,0 +1,35 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { validName, creelCommand, tokenToText } from "./capture.ts";
+
+test("validName accepts env identifiers and rejects the rest", () => {
+  for (const s of ["A", "OPENAI_API_KEY", "_x", "a1_b2"]) {
+    assert.equal(validName(s), true, s);
+  }
+  for (const s of ["", "1ABC", "A-B", "A B", "A.B", "$X"]) {
+    assert.equal(validName(s), false, s);
+  }
+});
+
+test("creelCommand single-quotes its arguments", () => {
+  assert.equal(
+    creelCommand("OPENAI_API_KEY", ".env", "/tmp/creel-status-abc"),
+    "creel 'OPENAI_API_KEY' --dest '.env' --status-file '/tmp/creel-status-abc'",
+  );
+});
+
+test("creelCommand neutralizes a quote in the destination", () => {
+  const cmd = creelCommand("K", "a'b/.env", "/tmp/s");
+  assert.equal(cmd, "creel 'K' --dest 'a'\\''b/.env' --status-file '/tmp/s'");
+});
+
+test("tokenToText maps every outcome and never echoes a value", () => {
+  assert.match(tokenToText("added", "OPENAI_API_KEY", ".env"), /Added OPENAI_API_KEY to \.env/);
+  assert.match(tokenToText("updated", "OPENAI_API_KEY", ".env"), /Updated OPENAI_API_KEY in \.env/);
+  assert.match(tokenToText("cancelled", "K", ".env"), /cancelled/i);
+  assert.match(tokenToText("error:dest-outside-cwd", "K", ".env"), /Could not store K: dest-outside-cwd/);
+  assert.match(tokenToText(undefined, "K", ".env"), /Timed out/);
+  assert.match(tokenToText("", "K", ".env"), /Timed out/);
+  assert.match(tokenToText("weird", "K", ".env"), /unexpected status \(weird\)/);
+});

package/src/capture.ts

@@ -0,0 +1,62 @@
+// Pure pieces of the request_secret tool: parameter schema, env-var name
+// validation, the popup command string, and the status-token -> reply mapping.
+// None of these ever see the captured value — creel writes it straight to the
+// .env, and this layer only ever handles a name, a destination, and a token.
+
+export const REQUEST_SECRET_PARAMS = {
+  type: "object",
+  properties: {
+    name: {
+      type: "string",
+      description:
+        "The environment-variable name to store the secret under, e.g. OPENAI_API_KEY.",
+    },
+    dest: {
+      type: "string",
+      description:
+        "Path to the .env file to write, relative to the working directory. Defaults to .env.",
+    },
+  },
+  required: ["name"],
+} as const;
+
+// ValidName mirrors the Go creel.ValidName: a legal env-var name.
+export function validName(s: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(s);
+}
+
+function shq(s: string): string {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+// creelCommand is the sh command tmux display-popup runs. name/dest/status are
+// single-quoted; the popup's creel writes the value to dest and the token to
+// status.
+export function creelCommand(name: string, dest: string, statusFile: string): string {
+  return `creel ${shq(name)} --dest ${shq(dest)} --status-file ${shq(statusFile)}`;
+}
+
+// tokenToText maps creel's status token to the reply the model sees. It never
+// includes the secret — only the outcome.
+export function tokenToText(
+  token: string | undefined,
+  name: string,
+  dest: string,
+): string {
+  if (token === undefined || token === "") {
+    return `Timed out waiting for the creel popup; nothing was recorded for ${name}.`;
+  }
+  switch (token) {
+    case "added":
+      return `Added ${name} to ${dest} (chmod 600). The value was not shown here.`;
+    case "updated":
+      return `Updated ${name} in ${dest}. The value was not shown here.`;
+    case "cancelled":
+      return `Capture cancelled; nothing was written for ${name}.`;
+    default:
+      if (token.startsWith("error:")) {
+        return `Could not store ${name}: ${token.slice("error:".length)}.`;
+      }
+      return `Capture finished with an unexpected status (${token}).`;
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,94 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { createCreel, type Deps } from "./index.ts";
+import type { TmuxContext } from "./tmux.ts";
+
+type Registered = {
+  name: string;
+  execute: (id: string, params: any) => Promise<{ content: { text: string }[] }>;
+};
+
+function harness(deps: Deps): Registered {
+  let reg: Registered | undefined;
+  const pi = {
+    registerTool(def: Registered) {
+      reg = def;
+    },
+  };
+  createCreel(pi, deps);
+  if (!reg) throw new Error("tool not registered");
+  return reg;
+}
+
+const tmux: TmuxContext = { socket: "proj-x", pane: "%1" };
+const okDeps = (overrides: Partial<Deps> = {}): Deps => ({
+  resolveTmux: () => tmux,
+  creelOnPath: () => true,
+  spawnPopup: () => {},
+  waitForToken: async () => "added",
+  tmpStatusPath: () => "/tmp/creel-status-test",
+  ...overrides,
+});
+
+async function run(reg: Registered, params: any): Promise<string> {
+  const out = await reg.execute("id", params);
+  return out.content[0].text;
+}
+
+test("registers request_secret", () => {
+  const reg = harness(okDeps());
+  assert.equal(reg.name, "request_secret");
+});
+
+test("rejects an invalid name before touching tmux", async () => {
+  let spawned = false;
+  const reg = harness(okDeps({ spawnPopup: () => { spawned = true; } }));
+  const text = await run(reg, { name: "BAD-NAME" });
+  assert.match(text, /not a valid environment-variable name/);
+  assert.equal(spawned, false);
+});
+
+test("fails fast when not in tmux", async () => {
+  const reg = harness(okDeps({ resolveTmux: () => undefined }));
+  const text = await run(reg, { name: "OPENAI_API_KEY" });
+  assert.match(text, /needs a tmux session/);
+});
+
+test("fails when creel is not on PATH", async () => {
+  const reg = harness(okDeps({ creelOnPath: () => false }));
+  const text = await run(reg, { name: "OPENAI_API_KEY" });
+  assert.match(text, /'creel' binary was not found/);
+});
+
+test("passes name and default dest to the popup and maps the token", async () => {
+  let gotCommand = "";
+  const reg = harness(
+    okDeps({
+      spawnPopup: (_t, command) => { gotCommand = command; },
+      waitForToken: async () => "updated",
+    }),
+  );
+  const text = await run(reg, { name: "OPENAI_API_KEY" });
+  assert.match(gotCommand, /creel 'OPENAI_API_KEY' --dest '\.env' --status-file/);
+  assert.match(text, /Updated OPENAI_API_KEY in \.env/);
+});
+
+test("honors a custom dest", async () => {
+  let gotCommand = "";
+  const reg = harness(okDeps({ spawnPopup: (_t, c) => { gotCommand = c; } }));
+  await run(reg, { name: "K", dest: "config/.env" });
+  assert.match(gotCommand, /--dest 'config\/\.env'/);
+});
+
+test("reports a timeout when no token arrives", async () => {
+  const reg = harness(okDeps({ waitForToken: async () => undefined }));
+  const text = await run(reg, { name: "K" });
+  assert.match(text, /Timed out/);
+});
+
+test("surfaces a creel error token", async () => {
+  const reg = harness(okDeps({ waitForToken: async () => "error:dest-outside-cwd" }));
+  const text = await run(reg, { name: "K", dest: "../x.env" });
+  assert.match(text, /Could not store K: dest-outside-cwd/);
+});

package/src/index.ts

@@ -0,0 +1,151 @@
+// pi-creel — the request_secret tool.
+//
+// When the model needs an API key it calls request_secret instead of asking
+// the user to paste it into chat. This wiring resolves tmux, opens a
+// display-popup running the creel binary, and waits for creel to write a
+// status token to a temp file. The captured value goes straight from the popup
+// into the target .env; this process — and therefore the model's context —
+// only ever sees the token (added / updated / cancelled / error), never the
+// value.
+//
+// The pure pieces (schema, command string, token mapping) live in capture.ts;
+// this file is the thin, injectable pi/tmux/fs wiring, in the same split
+// pi-wakeup and guardrails use.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { resolveTmux, type TmuxContext } from "./tmux.ts";
+import {
+  REQUEST_SECRET_PARAMS,
+  creelCommand,
+  tokenToText,
+  validName,
+} from "./capture.ts";
+
+const POPUP_WIDTH = "64";
+const POPUP_HEIGHT = "14";
+const TOKEN_TIMEOUT_MS = 120_000;
+const POLL_INTERVAL_MS = 150;
+
+export type Deps = {
+  resolveTmux?: (env: NodeJS.ProcessEnv) => TmuxContext | undefined;
+  creelOnPath?: () => boolean;
+  spawnPopup?: (tmux: TmuxContext, command: string) => void;
+  waitForToken?: (statusPath: string, timeoutMs: number) => Promise<string | undefined>;
+  tmpStatusPath?: () => string;
+};
+
+function defaultCreelOnPath(): boolean {
+  try {
+    execFileSync("creel", ["version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultSpawnPopup(tmux: TmuxContext, command: string): void {
+  // display-popup returns immediately (the popup runs detached on the server),
+  // so completion is observed out-of-band via the status file.
+  execFileSync(
+    "tmux",
+    [
+      "-L", tmux.socket,
+      "display-popup",
+      "-t", tmux.pane,
+      "-E",
+      "-w", POPUP_WIDTH,
+      "-h", POPUP_HEIGHT,
+      "-T", " creel · request_secret ",
+      command,
+    ],
+    { stdio: "ignore" },
+  );
+}
+
+async function defaultWaitForToken(
+  statusPath: string,
+  timeoutMs: number,
+): Promise<string | undefined> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (existsSync(statusPath)) {
+      const raw = readFileSync(statusPath, "utf-8");
+      // creel writes "<token>\n" in a single write; wait for the newline so we
+      // never read a half-written token.
+      if (raw.endsWith("\n")) return raw.trim();
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  return undefined;
+}
+
+function defaultTmpStatusPath(): string {
+  return join(tmpdir(), `creel-status-${randomUUID()}`);
+}
+
+function reply(text: string) {
+  return { content: [{ type: "text", text }] };
+}
+
+export function createCreel(pi: any, deps: Deps = {}): void {
+  const resolve = deps.resolveTmux ?? resolveTmux;
+  const onPath = deps.creelOnPath ?? defaultCreelOnPath;
+  const spawn = deps.spawnPopup ?? defaultSpawnPopup;
+  const wait = deps.waitForToken ?? defaultWaitForToken;
+  const tmpPath = deps.tmpStatusPath ?? defaultTmpStatusPath;
+
+  pi.registerTool({
+    name: "request_secret",
+    label: "Request Secret",
+    description:
+      "Capture an API key or secret from the user without it entering the chat. Opens a masked tmux popup (the creel tool); the user pastes once and the value is written straight into a local .env. Call this whenever you would otherwise ask the user to paste a key — you receive only a confirmation (added/updated), never the value. Requires a tmux session and the 'creel' binary on PATH.",
+    promptSnippet:
+      "request_secret(name, dest?) — need an API key/secret? Capture it into a .env via a popup instead of asking the user to paste it into chat.",
+    parameters: REQUEST_SECRET_PARAMS,
+    async execute(_id: string, params: { name?: string; dest?: string }) {
+      const name = typeof params?.name === "string" ? params.name : "";
+      const dest = typeof params?.dest === "string" && params.dest ? params.dest : ".env";
+
+      if (!validName(name)) {
+        return reply(`"${name}" is not a valid environment-variable name; nothing captured.`);
+      }
+
+      const tmux = resolve(process.env);
+      if (!tmux) {
+        return reply(
+          "request_secret needs a tmux session and none is attached. Ask the user to paste the key manually, or run pi under tmux.",
+        );
+      }
+      if (!onPath()) {
+        return reply(
+          "The 'creel' binary was not found on PATH. Install the tackle 'creel' tool, then retry.",
+        );
+      }
+
+      const statusPath = tmpPath();
+      try {
+        spawn(tmux, creelCommand(name, dest, statusPath));
+        const token = await wait(statusPath, TOKEN_TIMEOUT_MS);
+        return reply(tokenToText(token, name, dest));
+      } catch (error) {
+        return reply(`Failed to run the creel popup: ${String(error)}`);
+      } finally {
+        try {
+          rmSync(statusPath, { force: true });
+        } catch {
+          // best-effort cleanup
+        }
+      }
+    },
+  });
+}
+
+export default function (pi: any) {
+  createCreel(pi);
+}

package/src/tmux.ts

@@ -0,0 +1,23 @@
+// tmux context resolution, mirrored from pi-harness. Duplicated rather than
+// cross-imported so pi-creel stays a standalone package (the same choice the
+// other packages in this monorepo make).
+
+export type TmuxContext = {
+  socket: string;
+  pane: string;
+};
+
+// $TMUX is "<socket-path>,<pid>,<session>". The socket NAME is the basename of
+// the first field; tmux is addressed as `tmux -L <name>`.
+export function resolveTmux(
+  env: NodeJS.ProcessEnv = process.env,
+): TmuxContext | undefined {
+  const tmuxEnv = env.TMUX;
+  const pane = env.TMUX_PANE;
+  if (!tmuxEnv || !pane) return undefined;
+  const socketPath = tmuxEnv.split(",")[0];
+  if (!socketPath) return undefined;
+  const socket = socketPath.slice(socketPath.lastIndexOf("/") + 1);
+  if (!socket) return undefined;
+  return { socket, pane };
+}