pi-creel 0.2.1 → 0.2.2

package/README.md

@@ -17,6 +17,23 @@ user pastes once, and the value goes straight from the popup into the target
 - `name` — the environment-variable name, e.g. `OPENAI_API_KEY`.
 - `dest` — path to the `.env` (relative to cwd), default `.env`.
 
+## Consuming the secret
+
+The value is written to `.env` mid-session, but the pi process env is frozen at
+launch, so the model can't just read `process.env.NAME`. Two supported paths,
+both of which keep the value out of the chat/context:
+
+- **`creel exec NAME[,NAME2,...] -- <command>`** runs `<command>` with each
+  value in its environment **only** — never printed, never in argv, never in an
+  error (a missing key is a hard error naming just the key). This is the
+  language-agnostic way to hand a mid-session key to a child process
+  (`creel exec OPENAI_API_KEY -- node run.mjs`).
+- **`process.env.NAME` after a relaunch**, once the new process inherits the
+  updated `.env`.
+
+The model should **not** read the `.env` itself. The `added` / `updated` reply
+from `request_secret` states this consumption path directly.
+
 ## Requirements
 
 - A tmux session (`$TMUX`). Without one the tool fails fast and asks the user to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-creel",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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",

package/src/capture.test.ts

@@ -33,3 +33,15 @@ test("tokenToText maps every outcome and never echoes a value", () => {
   assert.match(tokenToText("", "K", ".env"), /Timed out/);
   assert.match(tokenToText("weird", "K", ".env"), /unexpected status \(weird\)/);
 });
+
+test("a successful capture tells the model how to consume the secret", () => {
+  for (const token of ["added", "updated"]) {
+    const text = tokenToText(token, "TYPESAFE_API_KEY", ".env");
+    // Points at the containment path (creel exec) with the real var name...
+    assert.match(text, /creel exec TYPESAFE_API_KEY -- /);
+    // ...and the relaunch fallback...
+    assert.match(text, /process\.env\.TYPESAFE_API_KEY/);
+    // ...and steers the model away from reading the .env itself.
+    assert.match(text, /do not read|don't read/i);
+  }
+});

package/src/capture.ts

@@ -46,11 +46,18 @@ export function tokenToText(
   if (token === undefined || token === "") {
     return `Timed out waiting for the creel popup; nothing was recorded for ${name}.`;
   }
+  // howToUse tells the model the two supported ways to consume a mid-session
+  // secret without ever handling the value itself. It must never suggest
+  // reading the .env directly (the value must not enter the harness/context).
+  const howToUse =
+    ` The value was not shown here. To use it, run \`creel exec ${name} -- <command>\`` +
+    ` (that puts ${name} in the command's environment only), or read \`process.env.${name}\`` +
+    ` after a relaunch. Do not read ${dest} yourself.`;
   switch (token) {
     case "added":
-      return `Added ${name} to ${dest} (chmod 600). The value was not shown here.`;
+      return `Added ${name} to ${dest} (chmod 600).` + howToUse;
     case "updated":
-      return `Updated ${name} in ${dest}. The value was not shown here.`;
+      return `Updated ${name} in ${dest}.` + howToUse;
     case "cancelled":
       return `Capture cancelled; nothing was written for ${name}.`;
     default: