@keynv/cli 0.1.0-rc.8 → 0.1.0-rc.9

package/dist/index.js

@@ -1056,7 +1056,7 @@ var require_lib = __commonJS({
 var VERSION, AGENT;
 var init_version = __esm({
   "src/version.ts"() {
-    VERSION = "0.1.0-rc.8" ;
+    VERSION = "0.1.0-rc.9" ;
     AGENT = `keynv-cli/${VERSION}`;
   }
 });
@@ -7128,6 +7128,95 @@ var init_detect = __esm({
     KEYNV_ENV_BASENAME = ".keynv.env";
   }
 });
+function aiContextBody() {
+  return `## keynv (secrets)
+
+This project uses [keynv](https://keynv.dev) for secrets. There is a \`.keynv.env\` file at the project root containing **alias references** like \`OPENAI_API_KEY=@projectname.dev.openai-key\` \u2014 these are NOT real values, they are references to secrets stored in the keynv vault.
+
+### Mental model
+
+- **\`.keynv.env\`** \u2014 checked into git, contains aliases. Safe to read, edit, commit.
+- **Vault** \u2014 holds the real values. The \`keynv\` CLI reads it on demand.
+- **\`keynv exec -- <command>\`** \u2014 forks the command in a subprocess where the real values are injected into env vars. The parent process (where you, the AI agent, run) NEVER sees the real values.
+- **Redactor** \u2014 pipes subprocess stdout/stderr through a masker before they reach this terminal. Even if a script accidentally echoes a secret, you see \`<REDACTED:...>\` here.
+
+### What you should do
+
+When the user asks about secrets or env vars, follow this decision tree:
+
+| User intent | Run / suggest |
+|---|---|
+| "Add a new API key" / "set up a secret" | \`keynv secret create\` (interactive prompt picks project + env + key) |
+| "I have a \`.env\`, migrate it" | \`keynv init\` (you're seeing this file because that already happened) |
+| "Run the app / dev server / tests" | \`keynv exec -- <their existing command>\` (auto-loads \`.keynv.env\`) |
+| "Show me the value of X" | \`keynv secret get @alias\` \u2014 but copy to clipboard, do NOT print the value into chat / terminal |
+| "Rotate this key" | \`keynv secret rotate @alias\` |
+| "Add a new env var to the project" | Edit \`.keynv.env\` and add \`NAME=@project.env.key\` (after creating the secret with \`keynv secret create\`) |
+| "Who has access?" | \`keynv member list <project>\` |
+
+### Hard rules \u2014 do not violate
+
+1. **Never print resolved secret values** to the chat, terminal, log, or any file. The user's editor / scrollback / chat history is an attack surface.
+2. **Never write a \`.env\` file** (or any file) containing real secret values. The whole point of keynv is that those don't exist on disk.
+3. **Never edit \`.keynv.env\` to substitute resolved values for aliases.** The file should only ever contain \`@project.env.key\` references and plain non-secret literals.
+4. **Use \`keynv exec --\` to run commands that need env vars.** Don't try to load \`.keynv.env\` yourself by parsing it manually; the wrapper handles resolution + redaction + subprocess isolation.
+5. **If a tool fails with "blocked by keynv-guard" or similar**, do NOT try to work around it. Tell the user \u2014 that's a sign of a misconfiguration, not an obstacle to bypass.
+6. **Treat the alias literal (\`@project.env.key\`) as the canonical reference**, never the resolved value. When you write code, configs, or commands that need a secret, write the alias.
+
+### Quick reference
+
+\`\`\`bash
+keynv                       # interactive TUI menu (pick projects, secrets, members)
+keynv exec -- <cmd>         # run cmd with .keynv.env loaded
+keynv secret create         # walk through creating a new secret
+keynv secret list <project> # list aliases (no values)
+keynv whoami                # who am I logged in as
+keynv --help                # full command list
+\`\`\`
+
+If \`.keynv.env\` is missing or empty, the user probably hasn't run \`keynv init\` yet \u2014 suggest they do so before they paste a secret into a \`.env\`.`;
+}
+function renderKeynvBlock() {
+  return `${KEYNV_BLOCK_START}
+${aiContextBody()}
+${KEYNV_BLOCK_END}`;
+}
+function writeAiContext(rootPath) {
+  const path = join(rootPath, AGENTS_FILE_BASENAME);
+  const block = renderKeynvBlock();
+  if (!existsSync(path)) {
+    const initial = `# Agent guidance for this project
+
+${block}
+`;
+    writeFileSync(path, initial);
+    return "created";
+  }
+  const existing = readFileSync(path, "utf8");
+  const startIdx = existing.indexOf(KEYNV_BLOCK_START);
+  const endIdx = existing.indexOf(KEYNV_BLOCK_END);
+  if (startIdx >= 0 && endIdx > startIdx) {
+    const before = existing.slice(0, startIdx);
+    const after = existing.slice(endIdx + KEYNV_BLOCK_END.length);
+    const next = `${before}${block}${after}`;
+    if (next === existing) return "unchanged";
+    writeFileSync(path, next);
+    return "updated";
+  }
+  const sep = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  const trailingNewline = existing.endsWith("\n") ? "" : "\n";
+  writeFileSync(path, `${existing}${trailingNewline}${sep}${block}
+`);
+  return "appended";
+}
+var AGENTS_FILE_BASENAME, KEYNV_BLOCK_START, KEYNV_BLOCK_END;
+var init_aiContext = __esm({
+  "src/init/aiContext.ts"() {
+    AGENTS_FILE_BASENAME = "AGENTS.md";
+    KEYNV_BLOCK_START = "<!-- keynv:start -- generated by `keynv init`; safe to leave intact, will be refreshed on re-run -->";
+    KEYNV_BLOCK_END = "<!-- keynv:end -->";
+  }
+});
 
 // src/init/heuristics.ts
 function shannonEntropyBits(s) {
@@ -7675,6 +7764,14 @@ async function runInitFlow(client, opts) {
     R2.error(`Failed to write .keynv.env: ${err instanceof Error ? err.message : String(err)}`);
     return { exitCode: 1 };
   }
+  try {
+    const outcome = writeAiContext(root.path);
+    if (outcome === "created") R2.success("Wrote AGENTS.md (so AI agents understand keynv)");
+    else if (outcome === "updated") R2.success("Refreshed keynv section in AGENTS.md");
+    else if (outcome === "appended") R2.success("Appended keynv section to AGENTS.md");
+  } catch (err) {
+    R2.warn(`Could not write AGENTS.md: ${err instanceof Error ? err.message : String(err)}`);
+  }
   if (scriptWrapSelection.length > 0 && root.packageJsonScripts) {
     try {
       updatePackageJsonScripts(
@@ -7869,6 +7966,7 @@ var init_init = __esm({
     init_dist5();
     init_envFile();
     init_detect();
+    init_aiContext();
     init_heuristics();
     init_scriptWrap();
     init_cancel();
@@ -24764,7 +24862,7 @@ var require_named_placeholders = __commonJS({
         }
         return s;
       }
-      function join5(tree) {
+      function join6(tree) {
         if (tree.length === 1) {
           return tree;
         }
@@ -24790,7 +24888,7 @@ var require_named_placeholders = __commonJS({
         if (cache2 && (tree = cache2.get(query))) {
           return toArrayParams(tree, paramsObj);
         }
-        tree = join5(parse(query));
+        tree = join6(parse(query));
         if (cache2) {
           cache2.set(query, tree);
         }