pi-voice-input 0.1.0 → 0.1.2

package/AGENTS.md

@@ -0,0 +1,94 @@
+# AGENTS.md
+
+Development workflow for this repo.
+
+## Project
+
+- Package: `pi-voice-input`
+- GitHub: `git@github.com:tr-nc/pi-voice-input.git`
+- npm: `pi-voice-input`
+- Main extension: `extensions/voice-input.ts`
+- Current provider: VolcEngine WebSocket ASR only
+- Provider architecture should remain extensible so more ASR providers can be added later.
+
+## Secrets and local data
+
+- Never commit API keys, `.env`, recordings, logs, caches, or `node_modules`.
+- User credentials belong in `~/.pi/agent/voice-input.env`, usually written by `/voice key`.
+- Do not print or copy real API keys into commits, docs, tests, or command output.
+- The explicit VolcEngine API key URL that should be shown to users is:
+  `https://console.volcengine.com/speech/new/setting/apikeys?projectName=default`
+
+## Before committing
+
+Run from the repo root:
+
+```bash
+npm install --package-lock=false
+npx tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck --types node extensions/voice-input.ts
+PI_OFFLINE=1 pi -e ./extensions/voice-input.ts --list-models
+npm pack --dry-run
+```
+
+Check that `npm pack --dry-run` includes only publishable files, normally:
+
+```text
+.env.example
+AGENTS.md
+README.md
+extensions/voice-input.ts
+package.json
+```
+
+Clean local generated files before committing:
+
+```bash
+rm -rf node_modules package-lock.json logs recordings
+```
+
+Then check:
+
+```bash
+git status --short
+rg -n "VOLC_API_KEY=|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" \
+  --glob '!node_modules/**' --glob '!package-lock.json' . || true
+```
+
+Use conventional commit messages, for example:
+
+- `feat: add voice API key setup command`
+- `fix: handle missing recorder cleanly`
+- `docs: clarify npm installation`
+- `chore: update package metadata`
+
+## Release workflow
+
+1. Bump `package.json` version. npm versions are immutable.
+2. Validate with the commands above.
+3. Commit with a conventional commit message.
+4. Push to GitHub:
+
+```bash
+git push origin main
+```
+
+5. Publish to npm:
+
+```bash
+npm publish --access public
+```
+
+6. Update the local installed pi package and verify startup:
+
+```bash
+pi update npm:pi-voice-input
+PI_OFFLINE=1 pi --list-models
+```
+
+If testing a local checkout instead of the npm package, use:
+
+```bash
+pi -e ./extensions/voice-input.ts
+```
+
+Do not leave local development wrappers in `~/.pi/agent/extensions/voice-input.ts` when validating the npm installation path.

package/README.md

@@ -70,18 +70,24 @@ Planned provider direction:
 
 ## Configure credentials
 
-Create a config file:
+In pi, run:
 
-```bash
-mkdir -p ~/.pi/agent
-cp .env.example ~/.pi/agent/voice-input.env
-$EDITOR ~/.pi/agent/voice-input.env
+```text
+/voice key
 ```
 
-At minimum, set:
+Paste your VolcEngine Speech API key into the prompt. The extension saves it for future sessions and keeps it out of your project files.
 
-```bash
-VOLC_API_KEY=your_volcengine_speech_api_key
+The key URL is also shown inside pi when the key is missing, when you run `/voice key`, and in `/voice help`:
+
+```text
+https://console.volcengine.com/speech/new/setting/apikeys?projectName=default
+```
+
+Then verify:
+
+```text
+/voice config
 ```
 
 You can get/manage the key here:
@@ -90,18 +96,25 @@ https://console.volcengine.com/speech/new/setting/apikeys?projectName=default
 
 If `VOLC_API_KEY` is missing, the extension does not silently fail. It shows an error notification explaining:
 
-- that `VOLC_API_KEY` is missing
-- where to put it: `~/.pi/agent/voice-input.env`
-- the exact config line to add
-- the Volcengine API-key settings URL
+- that the current provider API key is missing
+- to run `/voice key`
+- the VolcEngine API-key settings URL
 - that `/voice config` can be used to verify detection
 
+Manual fallback:
+
+```bash
+mkdir -p ~/.pi/agent
+cp .env.example ~/.pi/agent/voice-input.env
+$EDITOR ~/.pi/agent/voice-input.env
+```
+
 ## Configuration reference
 
 Example:
 
 ```bash
-# Required
+# Required for the current provider. Usually set by /voice key.
 VOLC_API_KEY=your_volcengine_speech_api_key
 
 # Current provider: VolcEngine WebSocket ASR endpoint and resource
@@ -139,7 +152,7 @@ Config loading order, later values override earlier ones:
 3. current-working-directory `.env`
 4. shell environment variables
 
-Do not commit real credentials. Keep private local values in `.env` or `~/.pi/agent/voice-input.env`.
+Do not commit real credentials. Prefer `/voice key`, or keep private local values in `.env` or `~/.pi/agent/voice-input.env`.
 
 ## Usage
 
@@ -158,6 +171,8 @@ Slash commands:
 /voice cancel   # stop recording without transcribing
 /voice status   # show recorder state
 /voice config   # show effective non-secret config and whether API key is detected
+/voice key      # prompt for and save the current provider API key
+/voice help     # show setup help, including the explicit VolcEngine API key URL
 ```
 
 ## Notes

package/extensions/voice-input.ts

@@ -3,6 +3,7 @@ import { Key } from "@earendil-works/pi-tui";
 import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import {
+  chmodSync,
   closeSync,
   existsSync,
   mkdirSync,
@@ -20,6 +21,8 @@ import WebSocket from "ws";
 
 const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.resolve(EXTENSION_DIR, "..");
+const PRIVATE_CONFIG_PATH = path.join(homedir(), ".pi", "agent", "voice-input.env");
+const VOLC_API_KEY_URL = "https://console.volcengine.com/speech/new/setting/apikeys?projectName=default";
 const DEFAULT_SHORTCUT = Key.ctrlShift("r");
 
 const MSG_TYPE_CLIENT_FULL_REQUEST = 0b0001;
@@ -101,7 +104,7 @@ function parseEnvText(text: string): EnvMap {
 
 function loadEnvFiles(): EnvMap {
   const candidates = [
-    path.join(homedir(), ".pi", "agent", "voice-input.env"),
+    PRIVATE_CONFIG_PATH,
     path.join(PACKAGE_ROOT, ".env"),
     path.join(process.cwd(), ".env"),
   ];
@@ -185,6 +188,38 @@ function ensureDir(dir: string) {
   mkdirSync(dir, { recursive: true });
 }
 
+function envValue(value: string): string {
+  if (/^[A-Za-z0-9_./:@+-]*$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+
+function writePrivateEnvValue(name: string, value: string) {
+  if (/\r|\n/.test(value)) throw new Error(`${name} must be a single-line value`);
+  ensureDir(path.dirname(PRIVATE_CONFIG_PATH));
+
+  const original = existsSync(PRIVATE_CONFIG_PATH) ? readFileSync(PRIVATE_CONFIG_PATH, "utf8") : "";
+  const lines = original ? original.split(/\r?\n/) : [];
+  const replacement = `${name}=${envValue(value)}`;
+  let replaced = false;
+
+  const nextLines = lines.map((line) => {
+    if (new RegExp(`^\\s*${name}\\s*=`).test(line)) {
+      replaced = true;
+      return replacement;
+    }
+    return line;
+  });
+
+  if (!replaced) {
+    if (nextLines.length > 0 && nextLines[nextLines.length - 1] !== "") nextLines.push("");
+    nextLines.push("# Managed by pi-voice-input. You can also update this with /voice key.");
+    nextLines.push(replacement);
+  }
+
+  writeFileSync(PRIVATE_CONFIG_PATH, nextLines.join("\n").replace(/\n*$/, "\n"), { mode: 0o600 });
+  chmodSync(PRIVATE_CONFIG_PATH, 0o600);
+}
+
 function timestampForFilename(): string {
   return new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "");
 }
@@ -422,11 +457,9 @@ function parseRecordedWav(filePath: string): { pcm: Buffer; durationMs: number }
 
 function missingCredentialsMessage(): string {
   return [
-    "Missing VOLC_API_KEY for Volcengine ASR.",
-    "Create ~/.pi/agent/voice-input.env with:",
-    "  VOLC_API_KEY=your_volcengine_speech_api_key",
-    "Optional: copy .env.example from this package as a template.",
-    "API key settings: https://console.volcengine.com/speech/new/setting/apikeys?projectName=default",
+    "Missing VOLC_API_KEY for the current VolcEngine ASR provider.",
+    "Run /voice key and paste your VolcEngine Speech API key.",
+    `Get/create the key here: ${VOLC_API_KEY_URL}`,
     "Run /voice config to verify whether the key is detected.",
   ].join("\n");
 }
@@ -685,10 +718,44 @@ async function toggleRecording(ctx: ExtensionContext) {
   else await startRecording(ctx);
 }
 
+function setupHelp(config = getConfig()): string {
+  return [
+    "pi Voice Input setup:",
+    "- Current provider: VolcEngine WebSocket ASR",
+    `- API key: ${config.apiKey ? "set" : "missing"}`,
+    "- To save/update the key, run: /voice key",
+    `- Get/create a VolcEngine Speech API key here: ${VOLC_API_KEY_URL}`,
+    "- After saving the key, run: /voice config",
+  ].join("\n");
+}
+
+async function configureApiKey(ctx: ExtensionContext, providedKey = "") {
+  let apiKey = providedKey.trim();
+
+  if (!apiKey) {
+    if (!ctx.hasUI) {
+      ctx.ui.notify(`Run /voice key in interactive pi, or get a key from ${VOLC_API_KEY_URL} and set VOLC_API_KEY.`, "error");
+      return;
+    }
+    ctx.ui.notify(`Get/create a VolcEngine Speech API key here:\n${VOLC_API_KEY_URL}`, "info");
+    const current = getConfig().apiKey;
+    const placeholder = current ? "Paste a new VolcEngine API key (current key is already set)" : "Paste VOLC_API_KEY";
+    apiKey = (await ctx.ui.input("VolcEngine API key", placeholder))?.trim() ?? "";
+  }
+
+  if (!apiKey) {
+    ctx.ui.notify("API key unchanged.", "warning");
+    return;
+  }
+
+  writePrivateEnvValue("VOLC_API_KEY", apiKey);
+  ctx.ui.notify("VolcEngine API key saved for pi voice input. Run /voice config to verify it is detected.", "info");
+}
+
 function configSummary(config: VoiceConfig): string {
   return [
     "Voice input config:",
-    `- api key: ${config.apiKey ? "set" : "missing"}`,
+    `- api key: ${config.apiKey ? "set" : "missing"} (update with /voice key)`,
     `- ws url: ${config.wsUrl}`,
     `- resource id: ${config.resourceId}`,
     `- language: ${config.language || "auto"}`,
@@ -697,6 +764,8 @@ function configSummary(config: VoiceConfig): string {
     `- recordings: ${config.recordingsDir}`,
     `- state: ${config.statePath}`,
     `- shortcut: ${config.shortcut}`,
+    "Run /voice key to save/update the current provider API key.",
+    `VolcEngine API key URL: ${VOLC_API_KEY_URL}`,
     "Config files checked: ~/.pi/agent/voice-input.env, package .env, current .env; shell env overrides them.",
   ].join("\n");
 }
@@ -717,9 +786,11 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerCommand("voice", {
-    description: "Voice input: start | stop | status | toggle | cancel | config",
+    description: "Voice input: start | stop | status | toggle | cancel | config | key | help",
     handler: async (args, ctx) => {
-      const action = (args || "toggle").trim().toLowerCase();
+      const input = (args || "toggle").trim();
+      const action = (input.split(/\s+/, 1)[0] || "toggle").toLowerCase();
+      const rest = input.slice(action.length).trim();
       try {
         if (action === "start") {
           await startRecording(ctx);
@@ -743,11 +814,19 @@ export default function (pi: ExtensionAPI) {
           ctx.ui.notify(configSummary(getConfig()), "info");
           return;
         }
+        if (["key", "api-key", "apikey", "setup", "configure"].includes(action)) {
+          await configureApiKey(ctx, rest);
+          return;
+        }
+        if (["help", "doctor"].includes(action)) {
+          ctx.ui.notify(setupHelp(getConfig()), "info");
+          return;
+        }
         if (action === "toggle" || action === "") {
           await toggleRecording(ctx);
           return;
         }
-        ctx.ui.notify("Usage: /voice start | stop | status | toggle | cancel | config", "error");
+        ctx.ui.notify("Usage: /voice start | stop | status | toggle | cancel | config | key | help", "error");
       } catch (error) {
         ctx.ui.setStatus("voice-input", undefined);
         ctx.ui.notify(`Voice command error: ${error instanceof Error ? error.message : String(error)}`, "error");
@@ -756,6 +835,17 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_start", (_event, ctx) => {
-    ctx.ui.notify(`Voice input loaded: ${startupConfig.shortcut} toggles recording.`, "info");
+    if (getConfig().apiKey) {
+      ctx.ui.notify(`Voice input loaded: ${startupConfig.shortcut} toggles recording.`, "info");
+      return;
+    }
+    ctx.ui.notify(
+      [
+        `Voice input loaded: ${startupConfig.shortcut} toggles recording.`,
+        "API key is missing. Run /voice key to set it up.",
+        `Get/create a VolcEngine Speech API key here: ${VOLC_API_KEY_URL}`,
+      ].join("\n"),
+      "warning",
+    );
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-voice-input",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "provider-extensible voice input extension for pi",
   "type": "module",
   "keywords": [
@@ -23,7 +23,8 @@
   "files": [
     "extensions",
     ".env.example",
-    "README.md"
+    "README.md",
+    "AGENTS.md"
   ],
   "pi": {
     "extensions": [