Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs(claude.md): capture v3.29.0 publish-flow learnings — signing-key leak avoidance + Windows prepublishOnly hazard

ruvnetc316ce2f0dc5
diff --git a/CLAUDE.md b/CLAUDE.md
index 2652c7fe02..1178d9af2a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -963,6 +963,34 @@ RUFLO_HELPERS_SIGNING_SECRET=ruflo-helpers-signing-key RUFLO_HELPERS_SIGNING_PRO
(`ruv-dev` also holds `ruflo-config-signing-key` and `NPM_TOKEN` — likely the right project
for other ruflo release-time secrets too.)
+**Handling the signing key without leaking it (learned 2026-07-14, hard way):** when
+sign-helpers.mjs runs via `execFileSync('gcloud', ...)` on Windows, Node fails to find
+`gcloud` (needs the `.cmd` suffix), so the script bails and users reach for
+`gcloud secrets versions access latest --secret=ruflo-helpers-signing-key` in the shell —
+which by default prints the PEM to stdout, which becomes tool-call output in Claude
+Code and lands in the session transcript. That happened, the key was leaked, GCP secret
+v1 was destroyed and a fresh v2 was rotated in (commit 0052b1b06 / PR #2673). **Rules:**
+- NEVER invoke `gcloud secrets versions access` in a way that lets the payload reach
+ tool output. Always redirect to a file in the same command: `gcloud … > ~/.ruflo/helpers-signing.key 2>&1 | grep -v BEGIN`.
+- On Windows, prefer `RUFLO_HELPERS_SIGNING_KEY=~/.ruflo/helpers-signing.key` over the
+ GCP env var, because the fallback file path doesn't go through the broken
+ `execFileSync('gcloud')` path.
+- If a rotation IS needed, keep the private half in `~/.ruflo/helpers-signing.key`
+ only, print ONLY the public half (via `Ed25519 pub export` from Node crypto), upload
+ new private via `gcloud secrets versions add … --data-file=`, then
+ `gcloud secrets versions destroy <old>` to make the old irrecoverable.
+
+**Windows `prepublishOnly` failure (learned 2026-07-14):** the CLI's `prepublishOnly`
+chain (`cp ../../../README.md ./README.md && rm -rf plugins && mkdir -p plugins && cp -r ...`)
+is POSIX-shell-only. On Windows, npm runs it via `cmd.exe /d /s /c` which chokes on
+`mkdir -p` (interprets `-p` as a directory name) and `cp -r` (no such command). Two
+workarounds until the script is rewritten in cross-platform Node:
+1. Run the prep steps manually in Git Bash, then `npm publish --ignore-scripts`.
+2. Or use a POSIX shell for the whole publish: `SHELL=bash npm publish` — but this
+ doesn't always take effect on Windows depending on npm version.
+Option 1 is what worked for v3.29.0. Track proper fix in ruvnet/ruflo issue for
+cross-platform prepublish.
+
**Concurrent-session helper corruption (real, observed, be paranoid):** multiple Claude Code
sessions can have their own `npm exec @claude-flow/cli@latest mcp start` MCP server running
concurrently with `cwd` inside this repo (check with `readlink /proc/<pid>/cwd` on