pi-robot-hand 0.1.1 → 0.2.0

package/README.md

@@ -1,16 +1,46 @@
 # pi-robot-hand
 
-A [pi](https://pi.dev) extension that lets the agent hand the user a command to run themselves.
+The lazy kit for [pi](https://pi.dev): too lazy to open an IDE, too lazy to copy and paste, not lazy enough to switch off the safety net.
+
+When the agent cannot or should not run something itself (a `/reload`, a `sudo` command, an interactive login, a secret going into a config file), you still do not want to leave the conversation. pi-robot-hand moves the command or the secret to you in one keystroke and brings the result back to the agent, while the guards that keep the agent away from dangerous commands and secret files stay on:
+
+- **`robot_hand`**: the agent hands you a command. Pick where it goes: your pi prompt, the clipboard, or a new Herdr pane. The agent never runs it.
+- **`!` follow-up**: after a `!command` you type finishes, the agent reads its output and answers, without another message from you.
+- **`secret_drop`**: you type a secret into a masked dialog and apply it with a `!` command you can read. The agent never sees the value.
+
+You are the one who runs every command, so a command-guarding extension such as [cc-safety-net](https://github.com/kenryu42/cc-safety-net) keeps checking everything the agent itself runs.
+
+## Install
+
+```bash
+pi install npm:pi-robot-hand
+```
+
+The package ships three extensions and a `secret-drop` skill that teaches the agent to use `secret_drop` and to let programs consume secret files.
+
+### Upgrading from pi-secret-drop
+
+`secret_drop` used to be the separate `pi-secret-drop` package. Both packages register the same tool, which pi refuses to load, so while `pi-secret-drop` is still in your settings pi-robot-hand leaves `secret_drop` to it and shows a warning with the exact command to remove it:
+
+```bash
+pi remove npm:pi-secret-drop@0.1.6   # the source as listed in your settings
+```
+
+Protected destinations and their registry in `~/.pi/agent/secret-drop/` carry over unchanged.
+
+## `robot_hand`: hand the user a command
 
 1. The agent calls `robot_hand` with a command and a one-line reason.
-2. Pi shows an inline selector in place of the prompt, with the reason and exactly what the user would run.
-3. The user picks one:
-   - **Put it in my prompt**: a shell command lands as `! command`, a pi slash command such as `/reload` lands as-is. Pressing Enter runs it; a `!` command's output returns to the conversation.
+2. Pi shows an inline selector in place of the prompt, with the reason and exactly what you would run.
+3. You pick one:
+   - **Put it in my prompt**: a shell command lands as `! command`, a pi slash command such as `/reload` lands as-is. Pressing Enter runs it; a `!` command's output returns to the conversation and the agent answers it.
    - **Copy it to the clipboard**: the raw shell command, for another terminal.
+   - **Type it into a new Herdr pane (I press Enter)**: when pi runs inside [Herdr](https://herdr.dev), a pane opens below pi with the command on an editable line. Edit it if needed and press Enter, or Ctrl+C to cancel.
+   - **Run it in a new Herdr pane**: the same pane, with the command started at once.
    - **No, thanks**: nothing is placed.
-4. The tool returns the choice. After a prompt or clipboard hand-over the agent's turn ends, so the next move is the user's.
+4. The tool returns the choice. After a hand-over the agent's turn ends, so the next move is yours.
 
-The agent never runs the command. It suits commands the user has to run: pi slash commands, `sudo` or interactive commands, and commands a safety extension blocks for the agent.
+A Herdr pane is a real terminal, so password prompts, `sudo`, confirmations, `ssh`, and full-screen programs work there; pi's `!` has no terminal input. When the command finishes, the pane closes and its output (the last 200 lines) and exit code arrive as a message that starts the agent's next turn. Cancelling, or closing the pane yourself, also reports back.
 
 ```
  robot_hand 需要 sudo 重啟服務
@@ -20,38 +50,133 @@ The agent never runs the command. It suits commands the user has to run: pi slas
 
    ! sudo systemctl restart nginx
 
- → Put it in my prompt
+ → Type it into a new Herdr pane (I press Enter)
+   Put it in my prompt
    Copy it to the clipboard
+   Run it in a new Herdr pane
    No, thanks
 
  ↑↓ navigate  enter select  escape/ctrl+c cancel
  ──────────────────────────────────────────────
 ```
 
-## Install
-
-```bash
-pi install npm:pi-robot-hand
-```
-
-## Tool: `robot_hand`
-
 | Parameter | Description |
 |---|---|
 | `command` | The command. Shell commands go without a leading `!`; pi commands start with `/`. |
 | `reason` | One short line telling the user why, in the user's language. |
 | `kind` | `shell` (default) or `pi`. |
+| `default` | The option the selector starts on: `prompt` (default), `clipboard`, `herdr-type`, or `herdr-run`. The agent picks `herdr-type` for commands that need terminal input. An option this session cannot offer falls back along `herdr-run` → `herdr-type` → `clipboard` → `prompt`. |
+
+When the prompt already holds a draft, the prompt option says it replaces the draft. The clipboard and Herdr options appear only for shell commands in the terminal UI, and the Herdr options only inside Herdr. RPC clients get the prompt option; modes without a UI make the tool fail so the agent shows the command in chat.
+
+The Herdr pane runs a short wrapper script (zsh, or bash 4+ when zsh is missing) from a private temporary directory, which is removed when the run is reported. The command runs in a non-interactive shell, so your shell aliases and functions are not loaded.
+
+## `!` follow-up
 
-When the prompt already holds a draft, the prompt option says it replaces the draft. The clipboard option appears only for shell commands in the terminal UI. RPC clients get the prompt option; modes without a UI make the tool fail so the agent shows the command in chat.
+Pi records the output of a `!command` but does not start a turn. With pi-robot-hand, once a `!command` typed while the agent is idle finishes, the agent reads its output and answers. Pi still runs the command, so output streams live and other `user_bash` extensions keep working. `!!` commands, cancelled commands, commands typed while the agent is busy, and commands overtaken by a prompt you send meanwhile keep pi's behavior.
+
+## `secret_drop`: put a secret in without the agent seeing it
+
+1. The agent calls `secret_drop` with a destination, a placement, and the steps to get the secret.
+2. Pi opens a masked dialog that shows those steps, where the value will go, and what happens next. The user types or pastes the secret, or presses Tab to ask the agent a question instead.
+3. The value is staged in `~/.pi/agent/secret-drop/staging/` (mode 600), and pi pre-fills a `!` command in the user's prompt:
+
+   ```
+   ! node ~/.pi/agent/npm/node_modules/pi-robot-hand/dist/apply.js env ./.env DB_PASSWORD --from ~/.pi/agent/secret-drop/staging/64770-948e1cb74b5a
+   ```
+
+4. The user reviews it and presses Enter. The apply script writes the destination, deletes the staged file, and prints only a report:
+
+   ```
+   ✓ secret-drop: updated DB_PASSWORD (1 line) in ./.env (env DB_PASSWORD, mode 644) — length check passed (28 chars)
+   ```
+
+5. The tool, which has been waiting, returns that report and the agent continues.
+
+The agent never opens the destination: the user runs the write with a command they can read. That also keeps secret-guarding extensions such as [cc-safety-net](https://github.com/kenryu42/cc-safety-net) in charge of the agent's tool calls, since pi's `!` commands are the user's own.
+
+```
+╭─ Secret Drop ──────────────────────────────────────────────────────────────╮
+│ Staging database password                                                  │
+│                                                                            │
+│ How to get it                                                              │
+│ 1. Open the staging project in 1Password                                   │
+│ 2. Copy the password of the "db-staging" item                              │
+│                                                                            │
+│ Goes to  ./.env (env DB_PASSWORD)                                          │
+│ Next     Enter here stages the value. Your prompt then holds a ! command;  │
+│          press Enter on it to apply. The agent never sees the value.       │
+│                                                                            │
+│ › ••••••••••••••••••••••••••••                                             │
+│   28 chars                                                                 │
+│                                                                            │
+│ Enter stage · Tab ask a question instead · Esc cancel · Ctrl+R show/hide · │
+│ Ctrl+U clear                                                               │
+│ Stuck or unsure? Press Tab and ask; the dialog closes and the agent        │
+│ answers.                                                                   │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+Tab opens a visible question field. Enter there closes the dialog without staging anything, discards what was typed in the secret field, and returns the question to the agent, which answers and calls `secret_drop` again. When the steps do not fit the terminal, the dialog shortens them; the tool call in the chat shows them in full.
+
+### With cc-safety-net
+
+The two cover different halves of the problem:
+
+- **cc-safety-net keeps the agent out of secrets that already exist.** It blocks the agent's shell and file tools from reading `.env` files, SSH keys, `~/.aws`, and other well-known credential locations, whether or not secret_drop wrote them.
+- **secret_drop gets new secrets in without the agent seeing them.** It protects the destinations it writes, including files outside cc-safety-net's patterns such as `config.yml`, and redacts the values from tool output.
+
+They do not conflict. cc-safety-net inspects the agent's tool calls; the apply command is the user's own `!` command, so the write goes through while the agent stays blocked from reading the result.
+
+### Parameters
+
+| Parameter | Meaning |
+|---|---|
+| `label` | What the user should enter, in the user's language. |
+| `instructions` | Required. Numbered steps, in the user's language: where to go (URL or menu path), what to fill in, and what to copy. One step for a value the user already knows. |
+| `url` | The page where the user creates or finds the secret. |
+| `format` | `env`, `regex`, `file`, or `command`. Defaults to `env` when `key` is set, `command` when `command` is set, else `file`. |
+| `destination` | `env` / `regex` / `file`: target file, relative to the working directory. Missing directories are created. |
+| `key`, `quote` | `env`: variable name and quoting (`auto`, `none`, `single`, `double`). Existing `KEY=` / `export KEY=` lines are replaced, keeping trailing `# comments` and CRLF endings; otherwise the line is appended. Use `none` for files read by `docker --env-file`, which keeps quotes as part of the value. |
+| `regex`, `flags` | `regex`: replaces capture group 1, or the whole match, in an existing file. `g` replaces every match. |
+| `fileMode` | Octal permissions. New files default to `600`; existing files keep their mode. |
+| `overwrite` | `file`: allow replacing an existing destination, for rotating single-value files such as keys. Without it an existing destination is refused; with it the dialog warns in red. |
+| `command` | `command`: shell command reading the staged file `{secret}`, e.g. `ansible-vault encrypt_string --stdin-name db_password < {secret} >> vault.yml`. Stdout is discarded; stderr is shown with the value redacted when the command fails. |
+
+Writes are atomic (temp file + rename) and verified by re-reading the destination. When verification fails, the original content and mode are restored from memory (a newly created file is removed); no backup file is written, so no copy of a secret is left outside the protected destination. The staged file is overwritten and deleted after every apply attempt, and when the tool is cancelled or aborted. Staged files left by pi processes that have exited are removed at session start.
+
+### Protection after the write
+
+- **Blocked reads.** `read`, `edit`, `write`, and `grep` on a destination or the staging area are blocked. In bash, each simple command is checked on its own: it is blocked when a protected path is an argument of a command that prints, copies, or opens files (`cat`, `head`, `grep`, `sed`, `cp`, `base64`, …, also behind `sudo`, `env`, `timeout`, `xargs`), a `<` or `>` redirection target, or inside `sh -c`, `eval`, `$(…)`, or backticks. Commands that only pass the path to a consumer, such as `--env-file .env` or `test -s .env`, still run.
+- **Redaction.** Any tool result or context message containing a secret value is rewritten to `[REDACTED]`. Values are reloaded from protected destinations at session start.
+- **Registry.** Protected locations (never values) live in `~/.pi/agent/secret-drop/registry.json`. `/secret-drop` lists them; `/secret-drop forget <path>` removes one.
+
+### Limits
+
+- Requires the interactive terminal UI. In RPC, JSON, and print modes the tool fails instead of falling back to a plain-text prompt.
+- The dialog is a centered overlay, which pi-tui cannot draw over rows holding terminal images. Set `PI_ASK_USER_DISPLAY_MODE=inline` (the variable pi-ask-user reads) in the shell that launches pi to render it inline instead.
+- The bash guard parses command lines, not programs. It stops accidental reads, not a determined agent: an indirect path (a variable, a glob, a script or `python -c` that prints the file) passes through. Redaction is the second layer for that output.
+- The rename replaces the destination's inode: hard links to it break and the file becomes owned by the user who runs the apply command. Symlinks are resolved and kept.
+- A multi-line quoted `KEY="…` value is replaced on its first line only.
+- Values shorter than 4 characters are not redacted. Values applied with `format: "command"` are redacted for the rest of the session only.
+- The apply command is shown before it runs; review it, since a `command` can send the staged value anywhere.
+
+## `robot_hand` and CC Safety Net
+
+CC Safety Net 2.4.7 scans tool input for sensitive paths, so it may block `robot_hand` when the *text* of a command names one. `robot_hand` only displays the command; the user decides whether to run it.
+
+Use a CC Safety Net build containing the Pi `robot_hand` display-only exemption (the local `fix/pi-allow-display-only-tools` branch; **not** the published 2.4.7 release). It applies only to the exact Pi tool name `robot_hand`; `bash` and other tools stay protected. To check it, ask the agent to hand over a harmless command containing a dummy sensitive-path name, such as `.env.agent-8091`: the selector should open without a CC Safety Net block. Do not press Enter to run a command you do not want to execute.
 
 ## Development
 
 ```bash
 npm install
 npm run check   # tsc --noEmit
-npm test        # node --test
+npm test        # builds dist/, then node --test
 ```
 
+`lib/` holds the secret placement and write logic shared by the extension and the apply script. The extension imports it as TypeScript, so pi's `/reload` picks up an upgrade; Node caches `.js` and `.mjs` modules for the life of the process. `npm run build` compiles `lib/` to `dist/` for the apply script, which runs with plain `node` because Node does not strip TypeScript types under `node_modules`. `npm pack` and `npm publish` build first.
+
 Releases publish from GitHub Actions through npm trusted publishing: bump `version` in `package.json`, commit, and push a matching `v<version>` tag.
 
 ## License

package/dist/apply.js

@@ -0,0 +1,142 @@
+/**
+ * Apply a staged secret to its destination. The user runs this through a pi `!` command, so its
+ * output reaches the model: it reports what changed and a length check, never the value.
+ * Compiled to dist/apply.js, which the prefilled command runs with node.
+ */
+import { spawn } from "node:child_process";
+import { open, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { checkValue, describePlacement, ENV_QUOTES, validatePlacement } from "./placement.js";
+import { shellQuote } from "./shell.js";
+import { parseFileMode, readExisting, writeSecret } from "./write.js";
+const USAGE = `usage:
+  apply.js env <destination> <KEY> --from <staged> [--quote auto|none|single|double] [--mode 600]
+  apply.js regex <destination> <regex> --from <staged> [--flags g] [--mode 600]
+  apply.js file <destination> --from <staged> [--overwrite] [--mode 600]
+  apply.js exec <command using {secret}> --from <staged>`;
+/**
+ * Overwrite then delete the staged file.
+ */
+async function wipe(path) {
+    try {
+        const { size } = await stat(path);
+        const handle = await open(path, "r+");
+        try {
+            await handle.write(Buffer.alloc(size), 0, size, 0);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        // Missing or unwritable: removal below still runs.
+    }
+    await rm(path, { force: true });
+}
+function redact(value, text) {
+    return value.length > 0 ? text.split(value).join("[REDACTED]") : text;
+}
+function chars(value) {
+    return [...value].length;
+}
+/**
+ * Run a shell command with {secret} replaced by the staged file path. Stdout is discarded.
+ */
+async function runCommand(command, staged, value) {
+    if (!command.includes("{secret}"))
+        throw new Error("exec command must reference {secret}.");
+    const script = command.split("{secret}").join(shellQuote(staged));
+    const child = spawn("sh", ["-c", script], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdoutBytes = 0;
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+        stdoutBytes += chunk.length;
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+    });
+    const code = await new Promise((resolve, reject) => {
+        child.on("error", reject);
+        child.on("close", resolve);
+    });
+    if (code !== 0) {
+        const tail = redact(value, stderr).trim().split("\n").slice(-15).join("\n");
+        throw new Error(`command exited ${code}${tail ? `:\n${tail}` : ""}`);
+    }
+    const suppressed = stdoutBytes > 0 ? `; ${stdoutBytes} bytes of stdout suppressed` : "";
+    return `command exited 0 — secret delivered via {secret} (${chars(value)} chars)${suppressed}`;
+}
+async function apply(format, args, options, staged, value) {
+    if (format === "exec") {
+        if (args.length !== 1 || !args[0])
+            throw new Error(USAGE);
+        return runCommand(args[0], staged, value);
+    }
+    let placement;
+    const destination = args[0];
+    if (format === "env" && args.length === 2 && destination && args[1]) {
+        const quote = options.quote ?? "auto";
+        if (!ENV_QUOTES.includes(quote))
+            throw new Error(`Invalid quote "${quote}".`);
+        placement = { mode: "env", key: args[1], quote: quote };
+    }
+    else if (format === "regex" && args.length === 2 && destination && args[1]) {
+        placement = { mode: "regex", pattern: args[1], flags: options.flags ?? "" };
+    }
+    else if (format === "file" && args.length === 1 && destination) {
+        placement = { mode: "file" };
+    }
+    else {
+        throw new Error(USAGE);
+    }
+    const fileMode = parseFileMode(options.mode);
+    const problem = checkValue(placement, value);
+    if (problem)
+        throw new Error(problem);
+    validatePlacement(placement, await readExisting(destination), options.overwrite === true);
+    const outcome = await writeSecret(destination, placement, value, fileMode);
+    const where = `${destination} (${describePlacement(placement)}, mode ${outcome.mode.toString(8)})`;
+    return `${outcome.summary} in ${where} — length check passed (${chars(value)} chars)`;
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            from: { type: "string" },
+            quote: { type: "string" },
+            flags: { type: "string" },
+            mode: { type: "string" },
+            overwrite: { type: "boolean" },
+        },
+    });
+    const staged = values.from;
+    if (!staged) {
+        console.error(USAGE);
+        process.exitCode = 2;
+        return;
+    }
+    const [format, ...args] = positionals;
+    const resultFile = `${staged}.result`;
+    let value = "";
+    try {
+        try {
+            value = await readFile(staged, "utf8");
+        }
+        catch {
+            throw new Error("staged secret not found; it was already applied or discarded. Call secret_drop again.");
+        }
+        const message = await apply(format, args, values, staged, value);
+        await writeFile(resultFile, JSON.stringify({ ok: true, message }), { mode: 0o600 });
+        console.log(`✓ secret-drop: ${message}`);
+    }
+    catch (error) {
+        const message = redact(value, error.message);
+        await writeFile(resultFile, JSON.stringify({ ok: false, message }), { mode: 0o600 }).catch(() => undefined);
+        console.error(`✗ secret-drop: ${message}`);
+        process.exitCode = 1;
+    }
+    finally {
+        await wipe(staged);
+    }
+}
+await main();

package/dist/placement.js

@@ -0,0 +1,222 @@
+/**
+ * Pure placement logic: where a secret goes inside a file, and how to find it again.
+ */
+export const ENV_QUOTES = ["auto", "none", "single", "double"];
+const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+const SAFE_UNQUOTED = /^[A-Za-z0-9_\-.,/:@%+=]*$/;
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function envLinePattern(key) {
+    return new RegExp(`^([ \\t]*(?:export[ \\t]+)?${escapeRegExp(key)}[ \\t]*=)(.*)$`, "gm");
+}
+/**
+ * Compile the placement regex with match indices so the first capture group can be replaced.
+ */
+function compileRegex(pattern, flags) {
+    const cleaned = [...new Set(flags.replace(/d/g, ""))].join("");
+    return new RegExp(pattern, `${cleaned}d`);
+}
+/**
+ * Throw when the env key or regex is malformed. Needs no file.
+ */
+export function validateSyntax(placement) {
+    if (placement.mode === "env" && !ENV_KEY.test(placement.key)) {
+        throw new Error(`Invalid env key "${placement.key}". Use letters, digits, "_" or ".", not starting with a digit.`);
+    }
+    if (placement.mode === "regex") {
+        try {
+            compileRegex(placement.pattern, placement.flags);
+        }
+        catch (error) {
+            throw new Error(`Invalid regex: ${error.message}`);
+        }
+    }
+}
+/**
+ * Return a message when a file placement would replace an existing file without `overwrite`.
+ */
+export function checkOverwrite(placement, exists, overwrite) {
+    if (placement.mode !== "file" || !exists || overwrite)
+        return undefined;
+    return "The destination exists and file placement would replace all of it. Use env or regex to change one value; pass overwrite only for single-value files such as keys or password files.";
+}
+/**
+ * Throw when the placement cannot be applied to `existing` (undefined for a missing file).
+ */
+export function validatePlacement(placement, existing, overwrite = false) {
+    validateSyntax(placement);
+    const refused = checkOverwrite(placement, existing !== undefined, overwrite);
+    if (refused)
+        throw new Error(refused);
+    if (placement.mode !== "regex")
+        return;
+    if (existing === undefined)
+        throw new Error("regex placement needs an existing file to locate the insertion point.");
+    if (!compileRegex(placement.pattern, placement.flags).test(existing)) {
+        throw new Error(`Pattern /${placement.pattern}/${placement.flags} does not match the destination file.`);
+    }
+}
+function resolveQuote(quote, value) {
+    if (quote !== "auto")
+        return quote;
+    if (SAFE_UNQUOTED.test(value))
+        return "none";
+    return value.includes("'") ? "double" : "single";
+}
+/**
+ * Return a message when the placement cannot represent `value`, otherwise undefined.
+ */
+export function checkValue(placement, value) {
+    if (value.length === 0)
+        return "Value is empty.";
+    if (placement.mode !== "file" && /[\r\n]/.test(value))
+        return `${placement.mode} placement needs a single-line value.`;
+    if (placement.mode === "env") {
+        const q = resolveQuote(placement.quote, value);
+        if (q === "none" && !SAFE_UNQUOTED.test(value))
+            return "Value needs quoting; use quote auto, single, or double.";
+        if (q === "single" && value.includes("'"))
+            return "Value contains a single quote; use quote auto or double.";
+    }
+    return undefined;
+}
+export function encodeEnvValue(value, quote) {
+    switch (resolveQuote(quote, value)) {
+        case "none":
+            return value;
+        case "single":
+            return `'${value}'`;
+        case "double":
+            return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`")}"`;
+    }
+}
+/**
+ * Split the text after `KEY=` into the value and a trailing ` # comment` outside quotes.
+ * The comment keeps its leading whitespace; an unterminated quote yields no comment.
+ */
+export function splitEnvComment(raw) {
+    const start = raw.length - raw.trimStart().length;
+    const quote = raw[start];
+    if (quote === "'" || quote === '"') {
+        let end = start + 1;
+        while (end < raw.length && raw[end] !== quote)
+            end += quote === '"' && raw[end] === "\\" ? 2 : 1;
+        const rest = raw.slice(end + 1);
+        if (end < raw.length && /^\s*#/.test(rest))
+            return { value: raw.slice(0, end + 1), comment: rest };
+        return { value: raw, comment: "" };
+    }
+    const hash = raw.search(/\s#/);
+    return hash === -1 ? { value: raw, comment: "" } : { value: raw.slice(0, hash), comment: raw.slice(hash) };
+}
+export function decodeEnvValue(raw) {
+    const trimmed = splitEnvComment(raw).value.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'"))
+        return trimmed.slice(1, -1);
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1).replace(/\\([\\"$`])/g, "$1");
+    }
+    return trimmed;
+}
+/**
+ * Produce the new file content with the secret placed. `existing` is undefined for a new file.
+ */
+export function applyPlacement(existing, placement, value) {
+    switch (placement.mode) {
+        case "file":
+            return { content: value, summary: existing === undefined ? "created file" : "replaced file content" };
+        case "env": {
+            const encoded = encodeEnvValue(value, placement.quote);
+            const base = existing ?? "";
+            const re = envLinePattern(placement.key);
+            if (re.test(base)) {
+                re.lastIndex = 0;
+                let count = 0;
+                const content = base.replace(re, (_match, prefix, old) => {
+                    count += 1;
+                    const { comment } = splitEnvComment(old.replace(/\r$/, ""));
+                    return `${prefix}${encoded}${comment}${old.endsWith("\r") ? "\r" : ""}`;
+                });
+                return { content, summary: `updated ${placement.key} (${count} line${count === 1 ? "" : "s"})` };
+            }
+            const separator = base.length === 0 || base.endsWith("\n") ? "" : "\n";
+            return { content: `${base}${separator}${placement.key}=${encoded}\n`, summary: `appended ${placement.key}` };
+        }
+        case "regex": {
+            if (existing === undefined)
+                throw new Error("regex placement needs an existing file.");
+            const re = compileRegex(placement.pattern, placement.flags);
+            let content = "";
+            let cursor = 0;
+            let count = 0;
+            re.lastIndex = 0;
+            let match;
+            while ((match = re.exec(existing)) !== null) {
+                const span = match.indices?.[1] ?? match.indices?.[0];
+                if (!span)
+                    break;
+                content += existing.slice(cursor, span[0]) + value;
+                cursor = span[1];
+                count += 1;
+                if (!re.global)
+                    break;
+                if (match[0].length === 0)
+                    re.lastIndex += 1;
+            }
+            if (count === 0)
+                throw new Error(`Pattern /${placement.pattern}/${placement.flags} does not match the destination file.`);
+            content += existing.slice(cursor);
+            return { content, summary: `replaced ${count} regex match${count === 1 ? "" : "es"}` };
+        }
+    }
+}
+/**
+ * Check that `content` holds `value` at the placement. Used after a write.
+ */
+export function verifyPlaced(content, placement, value) {
+    if (placement.mode === "file")
+        return content === value;
+    if (placement.mode === "env")
+        return extractSecret(content, placement) === value;
+    return content.includes(value);
+}
+/**
+ * Recover the stored secret from file content, for redaction after a restart.
+ */
+export function extractSecret(content, placement) {
+    switch (placement.mode) {
+        case "file":
+            return content.length > 0 ? content : undefined;
+        case "env": {
+            let last;
+            for (const match of content.matchAll(envLinePattern(placement.key)))
+                last = decodeEnvValue(match[2] ?? "");
+            return last ? last : undefined;
+        }
+        case "regex": {
+            let re;
+            try {
+                re = compileRegex(placement.pattern, placement.flags);
+            }
+            catch {
+                return undefined;
+            }
+            const match = re.exec(content);
+            if (!match)
+                return undefined;
+            const value = match[1] ?? match[0];
+            return value.length > 0 ? value : undefined;
+        }
+    }
+}
+export function describePlacement(placement) {
+    switch (placement.mode) {
+        case "file":
+            return "whole file";
+        case "env":
+            return `env ${placement.key}`;
+        case "regex":
+            return `regex /${placement.pattern}/${placement.flags}`;
+    }
+}

package/dist/shell.js

@@ -0,0 +1,7 @@
+/**
+ * POSIX shell quoting for the commands shown to and run by the user.
+ */
+const SAFE = /^[A-Za-z0-9_\-.,/:@%+=]+$/;
+export function shellQuote(word) {
+    return SAFE.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+}

package/dist/write.js

@@ -0,0 +1,66 @@
+/**
+ * Atomic file write for a placed secret.
+ */
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { applyPlacement, verifyPlaced } from "./placement.js";
+export const DEFAULT_NEW_FILE_MODE = 0o600;
+export async function readExisting(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Replace `path` with `content` through a temp file and rename, so readers never see a partial file.
+ */
+async function atomicWrite(path, content, mode) {
+    const tmp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        await writeFile(tmp, content, { mode: 0o600, flag: "wx" });
+        await chmod(tmp, mode);
+        await rename(tmp, path);
+    }
+    catch (error) {
+        await unlink(tmp).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Place `value` into `path`, write it atomically, and re-read it with `verify`.
+ * When the check fails, the original content and mode are restored from memory (a new file is
+ * removed) and the call throws; no backup file is ever written.
+ * New files get `fileMode ?? 0600`; existing files keep their mode unless `fileMode` is given.
+ */
+export async function writeSecret(path, placement, value, fileMode, verify = verifyPlaced) {
+    const existing = await readExisting(path);
+    const { content, summary } = applyPlacement(existing, placement, value);
+    const created = existing === undefined;
+    const originalMode = created ? undefined : (await stat(path)).mode & 0o777;
+    const mode = fileMode ?? originalMode ?? DEFAULT_NEW_FILE_MODE;
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await atomicWrite(path, content, mode);
+    if (!verify(await readFile(path, "utf8"), placement, value)) {
+        if (existing === undefined || originalMode === undefined)
+            await unlink(path);
+        else
+            await atomicWrite(path, existing, originalMode);
+        throw new Error(`verification failed after writing; ${created ? "removed the new file" : "restored the original content"}.`);
+    }
+    return { bytes: Buffer.byteLength(content), created, mode, summary };
+}
+/**
+ * Parse an octal permission string such as "600".
+ */
+export function parseFileMode(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^0?[0-7]{3}$/.test(raw))
+        throw new Error(`Invalid file mode "${raw}". Use octal like "600".`);
+    return Number.parseInt(raw, 8);
+}