Skip to content

TTHW squeeze: parallel install, 3-key BYOK truth, README Quick Start inversion - #8

Merged
Codehagen merged 8 commits into
mainfrom
tthw-squeeze-2026-04-17
Apr 18, 2026
Merged

Codehagen merged 8 commits into
mainfrom
tthw-squeeze-2026-04-17

Conversation

@Codehagen

@Codehagen Codehagen commented Apr 18, 2026 •

Copy link
Copy Markdown
Owner

Summary

Lands the 6 fixes from /plan-devex-review on BYOK onboarding (2026-04-17). Target TTHW: Champion tier (<2 min) for the no-key YC founder persona. Expected post-merge: scaffolder ~1:30, helpbase context path ~0:55.

  • Parallel install + LLM in the scaffolder — biggest single TTHW win (~30-60s saved per first run).
  • Collapsed 3-way auth prompt to a single confirm — removes persona-irrelevant noise.
  • Three-key BYOK truth across README, guides/byok.mdx, error messages, --help text, and inline-auth logic — the docs used to claim Gateway-only even after Anthropic/OpenAI direct shipped.
  • README Quick Start inversion — leads with helpbase login + helpbase context . (the <90s path) instead of the scaffolder.
  • inline-auth fix — isByokMode() is now the source of truth; ANTHROPIC_API_KEY / OPENAI_API_KEY users no longer see a pointless login prompt.
  • Device-flow poll interval drops from 2s to 1s (RFC 8628 compliant).

Commits

  • 8e6dd08 feat(scaffolder): parallel install + single-confirm auth prompt
  • dc25907 fix(cli): inline-auth uses isByokMode; device-flow poll interval 1s
  • 4a52869 docs(byok): kill stale Gateway-only framing; lead Quick Start with context

Each commit is independently reviewable.

Test plan

  • pnpm typecheck — 5/5 green
  • pnpm build — 4/4 green
  • pnpm test — 726/726 green across scaffolder / shared / web / mcp / cli (excluding 2 pre-existing env-bleed tests in cli that read the dev machine's real ~/.helpbase/auth.json — CI uses a clean env with HELPBASE_SMOKE_TOKEN so they pass there)
  • pnpm sync:templates — registry + scaffolder template copies of byok.mdx re-synced
  • Manual: npx create-helpbase /tmp/tthw-probe --source ./some/repo — observe install + generation running in parallel; install finishes in background while LLM call is in flight
  • Manual: ANTHROPIC_API_KEY=sk-ant-test helpbase context . — no spurious hosted-login prompt; routes direct
  • Manual: helpbase login — polling spinner ticks at 1s instead of 2s after "Waiting for browser approval…"
  • Staging check: visit helpbase.dev/docs/guides/byok after merge + deploy — new 3-key table renders

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Added support for direct Anthropic and OpenAI API keys as alternatives to Vercel AI Gateway in BYOK mode.
    • Improved device authentication polling speed.
  • Documentation

    • Updated guides and help text to reflect multi-provider key support with clear precedence rules.
    • Clarified authentication flow with "magic-link device flow" branding; emphasized free tier with no card required.
    • Updated README with explicit platform support (macOS/Linux/Windows) and Node 20+ requirement.
  • Chores

    • Optimized scaffolder dependency installation to run concurrently with content generation.

Codehagen and others added 3 commits April 18, 2026 00:08
Squeezes ~30-60s off first-run TTHW by running `<pkgManager> install` in
the background alongside the LLM generation call instead of serially
after it. Install captures stdout/stderr into buffers so it doesn't
clobber the spinner that the generation phase owns.

Collapses the 3-way auth prompt (Log in / BYOK paste / Skip) to a single
confirm("Log in to helpbase free?"). The no-key founder persona always
picked Log in; the BYOK paste option was cognitive noise. BYOK users
still route via env var — the scaffolder now detects any of
AI_GATEWAY_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY via isByokMode()
and skips the prompt entirely in that case (not just Gateway).

Drops the now-unused writeAiGatewayKey helper + its test.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
inline-auth.ts only checked AI_GATEWAY_API_KEY when deciding to skip the
hosted-login prompt. Users with only ANTHROPIC_API_KEY or OPENAI_API_KEY
set would see a pointless "sign in?" prompt even though the downstream
callLlm* path already bypasses the proxy via isByokMode(). Source of
truth is now isByokMode() from @workspace/shared/llm, so the prompt and
the actual LLM routing agree.

auth-device.ts default polling interval drops from 2s to 1s. RFC 8628
says `interval` is the minimum between polls, not a target, so 1s is
spec-compliant and cuts ~1s of perceived wait after the user clicks
Authorize in the browser. Server-supplied interval still wins. The
"slow_down" RFC branch still adds +5s per the spec.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ntext

The BYOK feature expanded from AI_GATEWAY_API_KEY only to three keys
(ANTHROPIC_API_KEY, OPENAI_API_KEY, AI_GATEWAY_API_KEY) but the prose
surfaces kept saying "use your own Vercel AI Gateway key." Trust signal
off — the docs lied about what the tool does.

Rewrites apps/web/content/guides/byok.mdx into a "three ways to skip the
hosted proxy" reference with per-provider examples (Anthropic direct,
OpenAI direct, Gateway for multi-provider). Syncs to the registry +
scaffolder-template copies.

Pulls one source-of-truth byokHint() helper in llm-errors-cli.ts so the
three LLM-failure paths (quota, global cap, network) name all three keys
in lockstep. Touches the matching stale hints in generate.ts,
context.ts, and sync.ts — the --help text and the MissingApiKey
fallback now reference login AND all three BYOK keys, not just Gateway.

README Quick Start inversion: the <90s path (`helpbase login` + `helpbase
context .`) is now the primary entry point. The scaffolder moves to a
secondary "Scaffold a full Next.js help-center site" heading for users
who want a deployable site, not just `.helpbase/` MDX in an existing
repo. The scaffolder note now mentions all three BYOK keys too.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@vercel

vercel Bot commented Apr 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
helpbase Ready Ready Preview, Comment Apr 18, 2026 6:44am

Request Review

@coderabbitai

coderabbitai Bot commented Apr 18, 2026 •

Copy link
Copy Markdown

Warning

Rate limit exceeded

@Codehagen has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 24 minutes and 50 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 24 minutes and 50 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 94f0ef96-b88c-4eb8-b6b7-b7ab484ad0a7

📥 Commits

Reviewing files that changed from the base of the PR and between 4a52869 and 6472719.

📒 Files selected for processing (21)
  • .linkcheckignore
  • README.md
  • apps/web/app/(main)/errors/[code]/page.tsx
  • apps/web/app/(main)/waitlist/page.tsx
  • apps/web/content/guides/sync-in-5-minutes.mdx
  • apps/web/public/r/helpbase-workflow.json
  • package.json
  • packages/cli/src/commands/generate.ts
  • packages/cli/src/commands/sync.ts
  • packages/create-helpbase/HELPBASE.md.template
  • packages/create-helpbase/src/index.ts
  • packages/create-helpbase/templates/HELPBASE.md
  • packages/create-helpbase/templates/content/guides/sync-in-5-minutes.mdx
  • packages/shared/src/__tests__/llm-errors.test.ts
  • packages/shared/src/__tests__/llm.test.ts
  • packages/shared/src/llm-wire.ts
  • packages/shared/src/llm.ts
  • registry/helpbase-workflow/README.md
  • registry/helpbase/content/guides/sync-in-5-minutes.mdx
  • scripts/check-links.sh
  • scripts/sync-templates.mjs
📝 Walkthrough

Walkthrough

This PR expands BYOK (Bring Your Own Key) authentication to support three provider environment variables—AI_GATEWAY_API_KEY, ANTHROPIC_API_KEY, and OPENAI_API_KEY—with precedence-based selection (first found wins). It removes single-key persistence logic, updates CLI commands and documentation, adjusts auth detection, and introduces concurrent dependency installation in the scaffolder.

Changes

Cohort / File(s) Summary
Documentation & Guides
README.md, apps/web/content/guides/byok.mdx, packages/create-helpbase/templates/content/guides/byok.mdx, registry/helpbase/content/guides/byok.mdx
Reframed BYOK from single AI_GATEWAY_API_KEY to three-key support with precedence routing. Updated platform requirements, login guidance, and added direct Anthropic/OpenAI sections. Updated README Quick Start and scaffolder instructions to reflect free hosted login + alternative BYOK flows.
CLI Command Help & Error Messages
packages/cli/src/commands/context.ts, packages/cli/src/commands/generate.ts, packages/cli/src/commands/sync.ts
Updated authentication guidance across commands to advertise helpbase login (free, 500k tokens/day) alongside multi-key BYOK options (ANTHROPIC_API_KEY, OPENAI_API_KEY, AI_GATEWAY_API_KEY). Changed error messaging from single-key focus to "no BYOK key set" with multi-option instructions.
Auth Library Updates
packages/cli/src/lib/inline-auth.ts, packages/cli/src/lib/auth-device.ts
Updated BYOK-mode detection in inline-auth.ts to check all three environment variables via isByokMode() instead of only AI_GATEWAY_API_KEY. Adjusted device-flow polling interval from 2s to 1s default in auth-device.ts.
Error Handling Helper
packages/cli/src/lib/llm-errors-cli.ts
Introduced shared byokHint() helper returning unified "bring your own key" message listing all three supported keys. Updated quota/network error fixes to use the shared hint instead of single-key guidance.
Scaffolder Auth & Installation
packages/create-helpbase/src/index.ts, packages/create-helpbase/src/env-local.ts
Removed writeAiGatewayKey() function and its caller, eliminating per-project key persistence. Refactored auth flow to prompt for free login confirmation only when no session and no BYOK env vars exist. Introduced concurrent background npm install during generation instead of sequential execution.
Test Cleanup
packages/create-helpbase/test/env-local.unit.test.ts
Removed entire test suite for deleted writeAiGatewayKey() function (51 lines, including three test cases for .env.local file creation and mutation).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Poem

🐰 Three keys now hop where one did roam,
Gateway, Anthropic, OpenAI—pick your home!
Auth flows simpler, docs all new,
We install while you wait—fast as morning dew! 🚀

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 21.43% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title directly summarizes the three main changes: parallel install optimization, multi-key BYOK support, and README restructuring prioritizing the quick-start path.
Description check ✅ Passed The description provides a clear summary of changes and addresses most template sections, though testing checkboxes and smoke-test evidence are incomplete.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch tthw-squeeze-2026-04-17

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)
packages/cli/src/commands/sync.ts (1)

66-67: ⚠️ Potential issue | 🟡 Minor

Stale addHelpText contradicts the PR's three-key BYOK message.

helpbase sync --help still reads "Set AI_GATEWAY_API_KEY first — https://vercel.com/ai-gateway", while the error copy (lines 163-167) and demo-mode next-step (line 376) were correctly updated to the three-key + helpbase login framing. Users hitting --help will see the old guidance.

🛠️ Suggested fix — align with context.ts / generate.ts
-Set AI_GATEWAY_API_KEY first — https://vercel.com/ai-gateway
+Auth: run ${pc.cyan("helpbase login")} (free, 500k tokens/day)
+  OR export one of ${pc.cyan("ANTHROPIC_API_KEY")} / ${pc.cyan("OPENAI_API_KEY")} / ${pc.cyan("AI_GATEWAY_API_KEY")}
+  (BYOK — first key found wins)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/cli/src/commands/sync.ts` around lines 66 - 67, Update the stale
help text added by addHelpText in the sync command so it matches the PR's
three-key BYOK + login guidance used elsewhere (e.g. context.ts/generate.ts);
locate the addHelpText call in packages/cli/src/commands/sync.ts and replace the
single-line "Set AI_GATEWAY_API_KEY first — https://vercel.com/ai-gateway"
message with the same three-key + `helpbase login` phrasing used in the error
copy and demo-mode next-step so --help shows the current guidance.
packages/cli/src/commands/context.ts (1)

117-128: ⚠️ Potential issue | 🟡 Minor

Stale single-key hint in GatewayError fix copy.

This fallback still tells users to "Check your AI_GATEWAY_API_KEY is valid", which contradicts the PR-wide three-key BYOK framing and will mislead users who are on BYOK via ANTHROPIC_API_KEY / OPENAI_API_KEY. Note that toCliLlmError on line 100 already handles GatewayError via the shared gatewayError() helper in llm-errors-cli.ts (which is BYOK-agnostic), so this second branch is also dead code when the error is a GatewayError (it's caught and rethrown as HelpbaseError above on line 103).

🛠️ Suggested fix

Since toCliLlmError already translates GatewayError, consider removing this branch entirely:

-      if (err instanceof GatewayError) {
-        throw new HelpbaseError({
-          code: "E_NETWORK",
-          problem: "The LLM gateway call failed.",
-          cause: err.message,
-          fix: [
-            "Retry in a moment — transient gateway errors are common.",
-            "Check your AI_GATEWAY_API_KEY is valid.",
-            "Try --model anthropic/claude-sonnet-4.6 to switch providers.",
-          ],
-        })
-      }
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/cli/src/commands/context.ts` around lines 117 - 128, The
GatewayError handling branch that throws a HelpbaseError in context.ts is stale
and duplicates/contradicts the BYOK-agnostic translation already performed by
toCliLlmError (which uses gatewayError in llm-errors-cli.ts); remove the entire
if (err instanceof GatewayError) { ... } branch (the throw of HelpbaseError) so
GatewayError is only handled by toCliLlmError/gatewayError and no misleading
single-key API hint remains.
packages/create-helpbase/src/index.ts (1)

227-227: ⚠️ Potential issue | 🟠 Major

Don’t start the dev server after a failed install.

When the background install fails, this prints a manual-install note but still runs <pkgManager> dev afterward. That will usually fail immediately with missing dependencies and bury the actionable recovery message.

🐛 Proposed fix
   let generationSucceeded = false
+  let installSucceeded = opts.install === false

   if (opts.install !== false) {
     s.start(`Finishing ${pkgManager} install...`)
     const installResult = await installPromise
     if (installResult.success) {
+      installSucceeded = true
       s.stop("Dependencies installed!")
     } else {
+      installSucceeded = false
       s.stop(pc.yellow("Failed to install dependencies."))
       note(
         `Run ${pc.cyan(`cd ${projectName as string} && ${pkgManager} install`)} manually.\n` +
         `  Reason: ${installResult.reason}`,
         "Manual install needed",
       )
     }
   }
-  if (opts.install !== false && opts.open !== false) {
+  if (opts.install !== false && installSucceeded && opts.open !== false) {
     await startDevServerWithAutoOpen(pkgManager, projectDir)
   }

Also applies to: 257-269, 306-307

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/create-helpbase/src/index.ts` at line 227, The code sets
generationSucceeded = false but still starts the dev server after a failed
background install; update the install/launch flow so generationSucceeded is set
to true only after installDependencies (or the function that performs the
background install) completes successfully, and add a guard before invoking the
dev server command (the code that runs `${pkgManager} dev` or the function that
spawns/execs the dev process) to skip launching when generationSucceeded is
false; apply the same guard to the other places mentioned (the blocks around the
code at the sections referenced 257-269 and 306-307) so the manual-install
recovery message is not buried by a failing dev start.
🧹 Nitpick comments (1)
apps/web/content/guides/byok.mdx (1)

1-152: Duplicate of template guide — keep them in sync.

This file is byte-identical in intent to packages/create-helpbase/templates/content/guides/byok.mdx. Same verification note about the whoami output on lines 121-123 applies here. Consider a lint/check or a generator that prevents these two sources from drifting; a future BYOK env-var change will otherwise need to be remembered in two places.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@apps/web/content/guides/byok.mdx` around lines 1 - 152, The byok.mdx guide
("Bring your own key (BYOK)") is duplicated between the app content and the
template (both byok.mdx) and can drift; add a deterministic sync check to CI (or
a small verification script) that compares the two byok.mdx sources and fails
the build if they differ, or replace the duplicate with a
generated/single-source approach; ensure the check targets the byok.mdx content
including the "whoami" verification note so future edits must update the
template or the single source rather than leaving them divergent.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/create-helpbase/src/index.ts`:
- Around line 617-621: The spawn call that creates the background installer
(const child = spawn(pkgManager, ["install"], { cwd: projectDir, stdio:
["ignore","pipe","pipe"], timeout: 120000 })) can fail on Windows because .cmd
shims require a shell; update the options to set shell: true when
process.platform === "win32" and include windowsHide: true to suppress the
console window, leaving cwd, stdio and timeout unchanged so the install still
runs in the background; reference the existing pkgManager, projectDir and child
variables when making this change.

In `@README.md`:
- Around line 138-141: Update the README to consistently reflect that BYOK
accepts ANTHROPIC_API_KEY, OPENAI_API_KEY, or AI_GATEWAY_API_KEY (first-found)
instead of only "AI Gateway"; search for references to "AI Gateway", "one env
var", `AI_GATEWAY_API_KEY`/`ai-gateway-key` (notably the later sections
referenced) and change wording to either list the three supported env vars or
explicitly state when a feature is Gateway-only (e.g., config-file persistence)
and keep those Gateway-only callouts next to the feature; ensure examples and
docs mention all three env var names (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
`AI_GATEWAY_API_KEY`) and clarify which features are exclusive to the AI
Gateway.

In `@registry/helpbase/content/guides/byok.mdx`:
- Around line 22-34: Update the BYOK guide language so it clarifies that BYOK
prevents helpbase.dev from seeing prompts but that AI_GATEWAY_API_KEY does not
route "provider-direct" — it routes via the Vercel AI Gateway as an
intermediary; edit the header sentence ("You want zero helpbase.dev
round-trips.") and the env var table description for AI_GATEWAY_API_KEY to
explicitly state that AI_GATEWAY routes through Vercel AI Gateway (not directly
to the provider) and keep the precedence note (`AI_GATEWAY_API_KEY` >
`ANTHROPIC_API_KEY` > `OPENAI_API_KEY`) and the ANTHROPIC/OPENAI rows unchanged;
apply the same clarification to the duplicate wording around lines 36-42 so both
occurrences consistently state BYOK bypasses helpbase but may still pass through
intermediaries like Vercel AI Gateway.

---

Outside diff comments:
In `@packages/cli/src/commands/context.ts`:
- Around line 117-128: The GatewayError handling branch that throws a
HelpbaseError in context.ts is stale and duplicates/contradicts the
BYOK-agnostic translation already performed by toCliLlmError (which uses
gatewayError in llm-errors-cli.ts); remove the entire if (err instanceof
GatewayError) { ... } branch (the throw of HelpbaseError) so GatewayError is
only handled by toCliLlmError/gatewayError and no misleading single-key API hint
remains.

In `@packages/cli/src/commands/sync.ts`:
- Around line 66-67: Update the stale help text added by addHelpText in the sync
command so it matches the PR's three-key BYOK + login guidance used elsewhere
(e.g. context.ts/generate.ts); locate the addHelpText call in
packages/cli/src/commands/sync.ts and replace the single-line "Set
AI_GATEWAY_API_KEY first — https://vercel.com/ai-gateway" message with the same
three-key + `helpbase login` phrasing used in the error copy and demo-mode
next-step so --help shows the current guidance.

In `@packages/create-helpbase/src/index.ts`:
- Line 227: The code sets generationSucceeded = false but still starts the dev
server after a failed background install; update the install/launch flow so
generationSucceeded is set to true only after installDependencies (or the
function that performs the background install) completes successfully, and add a
guard before invoking the dev server command (the code that runs `${pkgManager}
dev` or the function that spawns/execs the dev process) to skip launching when
generationSucceeded is false; apply the same guard to the other places mentioned
(the blocks around the code at the sections referenced 257-269 and 306-307) so
the manual-install recovery message is not buried by a failing dev start.

---

Nitpick comments:
In `@apps/web/content/guides/byok.mdx`:
- Around line 1-152: The byok.mdx guide ("Bring your own key (BYOK)") is
duplicated between the app content and the template (both byok.mdx) and can
drift; add a deterministic sync check to CI (or a small verification script)
that compares the two byok.mdx sources and fails the build if they differ, or
replace the duplicate with a generated/single-source approach; ensure the check
targets the byok.mdx content including the "whoami" verification note so future
edits must update the template or the single source rather than leaving them
divergent.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5fdb98e4-ac4d-47da-a8fd-b2cdeee3203e

📥 Commits

Reviewing files that changed from the base of the PR and between c942fb6 and 4a52869.

📒 Files selected for processing (13)
  • README.md
  • apps/web/content/guides/byok.mdx
  • packages/cli/src/commands/context.ts
  • packages/cli/src/commands/generate.ts
  • packages/cli/src/commands/sync.ts
  • packages/cli/src/lib/auth-device.ts
  • packages/cli/src/lib/inline-auth.ts
  • packages/cli/src/lib/llm-errors-cli.ts
  • packages/create-helpbase/src/env-local.ts
  • packages/create-helpbase/src/index.ts
  • packages/create-helpbase/templates/content/guides/byok.mdx
  • packages/create-helpbase/test/env-local.unit.test.ts
  • registry/helpbase/content/guides/byok.mdx
💤 Files with no reviewable changes (2)
  • packages/create-helpbase/src/env-local.ts
  • packages/create-helpbase/test/env-local.unit.test.ts

Comment on lines +617 to +621
const child = spawn(pkgManager, ["install"], {
cwd: projectDir,
stdio: ["ignore", "pipe", "pipe"],
timeout: 120000,
})

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

Node.js child_process.spawn Windows .cmd npm shell option official documentation

💡 Result:

In Node.js child_process.spawn on Windows, to execute .cmd or .bat files (including npm scripts via npm.cmd), set the shell option to true. This spawns cmd.exe (via process.env.ComSpec) to run the command, as .cmd/.bat files require a shell and are not directly executable. Official documentation states: "On Windows, however, .bat and .cmd files are not executable on their own without a terminal, and therefore cannot be launched using child_process.execFile. When running on Windows, .bat and .cmd files can be invoked using child_process.spawn with the shell option set..." Example for npm: const { spawn } = require('node:child_process'); const npmProcess = spawn('npm', ['--version'], { shell: true }); Note: Using shell: true has security risks if passing unsanitized input (shell injection). It's marked as not recommended in recent docs (DEP0190), prefer spawning cmd.exe directly: spawn('cmd.exe', ['/c', 'npm', '--version']). Recent change (post CVE-2024-27980 fix in Node.js 18.20.2+, 20.12.2+, etc.): Direct spawn of .cmd/.bat without shell: true now throws EINVAL for security; must use shell: true explicitly.

Citations:


🏁 Script executed:

# First, let's look at the actual code at the specified lines
head -625 packages/create-helpbase/src/index.ts | tail -15

Repository: Codehagen/helpbase

Length of output: 579


🏁 Script executed:

# Check the Node.js version requirements in package.json
cat packages/create-helpbase/package.json | grep -A 5 '"engines"'

Repository: Codehagen/helpbase

Length of output: 44


🏁 Script executed:

# Search for all spawn calls in the file to see if there are similar patterns
rg "spawn\(" packages/create-helpbase/src/index.ts -A 3

Repository: Codehagen/helpbase

Length of output: 592


🏁 Script executed:

# Check root package.json for engines
cat package.json | jq '.engines' 2>/dev/null || grep -A 2 '"engines"' package.json

Repository: Codehagen/helpbase

Length of output: 99


🏁 Script executed:

# Also check if there's an .nvmrc or similar
cat .nvmrc 2>/dev/null || cat .node-version 2>/dev/null || echo "No version file found"

Repository: Codehagen/helpbase

Length of output: 83


🏁 Script executed:

# Let's look at the context around each spawn call to understand what they do
rg "spawn\(" packages/create-helpbase/src/index.ts -B 2 -A 5 | head -60

Repository: Codehagen/helpbase

Length of output: 1129


Use a Windows-safe spawn path for package-manager commands.

On Windows with Node.js 20.19.0+ and 22.12.0+ (which this project targets), .cmd package manager shims require either shell: true or explicit spawning of cmd.exe. Without it, the spawn call will fail with EINVAL, breaking the background install feature for Windows users.

Add the shell option conditionally for Windows and use windowsHide to suppress the console window:

Proposed fix
+    const useShell = process.platform === "win32"
     const child = spawn(pkgManager, ["install"], {
       cwd: projectDir,
       stdio: ["ignore", "pipe", "pipe"],
       timeout: 120000,
+      shell: useShell,
+      windowsHide: true,
     })
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
const child = spawn(pkgManager, ["install"], {
cwd: projectDir,
stdio: ["ignore", "pipe", "pipe"],
timeout: 120000,
})
const useShell = process.platform === "win32"
const child = spawn(pkgManager, ["install"], {
cwd: projectDir,
stdio: ["ignore", "pipe", "pipe"],
timeout: 120000,
shell: useShell,
windowsHide: true,
})
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/create-helpbase/src/index.ts` around lines 617 - 621, The spawn call
that creates the background installer (const child = spawn(pkgManager,
["install"], { cwd: projectDir, stdio: ["ignore","pipe","pipe"], timeout: 120000
})) can fail on Windows because .cmd shims require a shell; update the options
to set shell: true when process.platform === "win32" and include windowsHide:
true to suppress the console window, leaving cwd, stdio and timeout unchanged so
the install still runs in the background; reference the existing pkgManager,
projectDir and child variables when making this change.

Comment thread README.md Resolved
Comment on lines +22 to +34
- **You want zero helpbase.dev round-trips.** Every BYOK call goes direct to
your provider. helpbase never sees your prompts.

## How it works
## Three keys, any one works

Set `AI_GATEWAY_API_KEY` in your environment. That's it. The CLI detects it
and bypasses the helpbase proxy for every LLM call:
Set whichever one you already have. First key found wins; precedence is
`AI_GATEWAY_API_KEY` > `ANTHROPIC_API_KEY` > `OPENAI_API_KEY`.

```bash
export AI_GATEWAY_API_KEY=vck_live_...
helpbase generate --url https://docs.example.com
```
| Env var | Routes to | Use when |
|---|---|---|
| `ANTHROPIC_API_KEY` | `@ai-sdk/anthropic` direct | You already have an Anthropic key. Pair with `--model anthropic/<id>`. |
| `OPENAI_API_KEY` | `@ai-sdk/openai` direct | You already have an OpenAI key. Pair with `--model openai/<id>`. |
| `AI_GATEWAY_API_KEY` | [Vercel AI Gateway](https://vercel.com/ai-gateway) | You want one key to route any provider (Anthropic, OpenAI, Google, etc.) with one bill. |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Clarify that AI Gateway is not provider-direct.

This page says every BYOK call goes “direct to your provider,” but AI_GATEWAY_API_KEY routes through Vercel AI Gateway. For privacy-sensitive workflows, the distinction matters: BYOK bypasses helpbase, not necessarily every intermediary.

📝 Proposed wording
-- **You want zero helpbase.dev round-trips.** Every BYOK call goes direct to
-  your provider. helpbase never sees your prompts.
+- **You want zero helpbase.dev round-trips.** BYOK bypasses helpbase.dev:
+  Anthropic/OpenAI keys call those providers directly; AI Gateway keys route
+  through Vercel AI Gateway. helpbase never sees your prompts.
-│ helpbase CLI     │─────► Vercel AI SDK direct ─────► your provider
-│                  │                                    (your key, your bill)
+│ helpbase CLI     │─────► Vercel AI SDK ─────► Anthropic/OpenAI direct
+│                  │                 └───────► Vercel AI Gateway ─────► provider
+│                  │                            (your key, your bill)

Also applies to: 36-42

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@registry/helpbase/content/guides/byok.mdx` around lines 22 - 34, Update the
BYOK guide language so it clarifies that BYOK prevents helpbase.dev from seeing
prompts but that AI_GATEWAY_API_KEY does not route "provider-direct" — it routes
via the Vercel AI Gateway as an intermediary; edit the header sentence ("You
want zero helpbase.dev round-trips.") and the env var table description for
AI_GATEWAY_API_KEY to explicitly state that AI_GATEWAY routes through Vercel AI
Gateway (not directly to the provider) and keep the precedence note
(`AI_GATEWAY_API_KEY` > `ANTHROPIC_API_KEY` > `OPENAI_API_KEY`) and the
ANTHROPIC/OPENAI rows unchanged; apply the same clarification to the duplicate
wording around lines 36-42 so both occurrences consistently state BYOK bypasses
helpbase but may still pass through intermediaries like Vercel AI Gateway.

Two follow-ups from the /devex-review audit of the live site:

1) apps/web/app/(main)/errors/[code]/page.tsx had 8 stale Gateway-only
   hints across 5 error codes (e-missing-api-key, e-auth-required,
   e-quota-exceeded, e-global-cap, e-llm-network, e-llm-gateway). The
   CLI-side copy was updated in #8; these web-rendered pages at
   helpbase.dev/errors/<code> still said "export AI_GATEWAY_API_KEY=..."
   as the only BYOK option. Rewrote each to the 3-key pattern matching
   llm-errors-cli.ts.

2) /docs/byok was a 404 everywhere. The live guide lives at /guides/byok.
   Nine surfaces (README, waitlist page, sync guide, CLI error hints,
   workflow README, BYOK_DOCS_URL const) pointed at the broken URL —
   every link a new user followed was dead. Updated BYOK_DOCS_URL in
   shared/llm-wire.ts as the source of truth, plus all hardcoded strings
   that didn't flow through it. Test fixtures updated for consistency.

Ran pnpm sync:templates + pnpm registry:build so the scaffolder template
+ registry JSON pick up the fixed sync-in-5-minutes.mdx copy and the
workflow README change. 654/654 tests green across shared/cli/scaffolder/web
(excluding 2 pre-existing env-bleed cli tests unrelated to this change).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Greps the repo for `https://helpbase.dev/<path>` URLs and HEAD-checks
each. Fails on 4xx (broken), treats 401/403/405 as OK (auth-gated or
method-gated endpoints are still real), warns on 5xx/timeouts.

Exclusions cut noise: test dirs (negative-test fixtures point at fake
URLs), planning docs (*_PLAN.md / *_PROMPT.md), CHANGELOG.md, lockfiles.
Scheme-ful URLs only — bare `helpbase.dev` in comments isn't a clickable
link.

Not wired into CI yet — run manually with `pnpm check:links`. Would have
caught the 9 broken `/docs/byok` references fixed in the previous commit.

First run on main surfaces 9 real 404s not yet fixed: `/docs` (README
Demo link), `/docs/cli` (HELPBASE.md template — ships to users),
`/docs/troubleshooting#*` (generate.ts error hints ×5), `/account/tokens`
(README), plus one bare `/errors` const and a magic-link placeholder.
Left for a follow-up so this commit stays scoped.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ships the follow-up cleanup hinted at in the previous commit. Every fix
targets a URL that a real user would click (README badges, CLI error
hints, HELPBASE.md in scaffolded projects), not a cosmetic one.

- README.md:20 — Demo badge pointed at /docs (404). Now points at
  /getting-started/introduction (200), which is the canonical "what
  helpbase is" article for a first-time visitor.
- README.md:295 — "Tokens are issued from helpbase.dev/account/tokens"
  was aspirational (the web dashboard isn't built yet). Replaced with
  the real workflow: helpbase login + jq the access_token out of
  ~/.helpbase/auth.json, set as HELPBASE_TOKEN secret in CI.
- HELPBASE.md.template + synced template — "Full reference at
  helpbase.dev/docs/cli" → /cli/commands (200). This file ships into
  every scaffolded project, so the broken link was in every new user's
  repo.
- packages/cli/src/commands/generate.ts — 7 stale /docs/troubleshooting#*
  URLs in error messages. 4 had matching /errors/e-* pages (remapped:
  #bad-frontmatter → e-invalid-frontmatter, #gateway-errors →
  e-llm-gateway). 3 were generic catchalls with no matching page
  (printRepoError, printScrapeError, generic printGenerateError) — the
  "Docs:" line is removed; the error already has Reason + Fix.
- packages/create-helpbase/src/index.ts:297 — scaffolder outro banner's
  "Docs: helpbase.dev/docs" → /getting-started/introduction.
- scripts/sync-templates.mjs:435 — the DEFAULT_HELPBASE_MD generator
  (fallback when no .template file exists) had the same /docs reference.

Tooling additions:
- scripts/check-links.sh now treats 429 (rate-limited) as "exists" and
  supports a .linkcheckignore file for known-template-base URLs.
- .linkcheckignore lists 3 known false positives: ERROR_DOC_BASE const
  (template base, never linked directly) and two magic-link verify
  placeholder strings (illustrative prompt text + React Email preview
  fixture).

Post-fix: 22/22 links pass, 0 broken. Was 9 broken two commits ago.
Typecheck green. Shared (152/152) and scaffolder (31/31) tests green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
/review caught it: the .linkcheckignore filter was building a pipe-joined
regex union and only escaping [, ], ., ^, $, * — leaving ?, =, +, {, },
|, (, ) as regex metacharacters. URLs with query strings like
`/verify?token=` matched nothing in the ignore list, so they leaked past
the filter and only appeared as "exists" because helpbase.dev rate-limited
(429) those probes, which /check-links treats as PASS.

If the server stopped rate-limiting, those URLs would resurface as FAIL.
Silent fragility in what's supposed to be a correctness gate.

Fix: `printf '%s\n' "${URLS[@]}" | grep -F -x -v -f <ignore>` — fixed
strings, exact line, invert match. URLs with any metacharacter now match
literally. Confirmed with a debug run: 22 → 20 checked after the fix
(the two magic-link placeholders now filtered properly instead of passing
on rate-limit luck).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CI caught it: removing the `Docs:` line from printRepoError,
printScrapeError, and the generic printGenerateError catchall broke
`generate.test.ts:48` and `cli.integration.test.ts:84`, both of which
enforce the "every error has problem / cause / fix / docs" contract.

Restored the line. Now points at https://helpbase.dev/cli/commands (200,
confirmed by check-links) — the CLI command reference is a useful landing
spot for a user hit with a generic scrape / repo-read / generate error.
Was pointing at /docs/troubleshooting#generate-errors, which 404ed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@Codehagen
Codehagen merged commit 0224492 into main Apr 18, 2026
5 checks passed
@Codehagen
Codehagen deleted the tthw-squeeze-2026-04-17 branch April 18, 2026 06:47
Codehagen added a commit that referenced this pull request Apr 18, 2026
Cut the 0.6.0 release. Bundles:
- deploy --preview + smart-prompt + auto-retry (#11)
- slug reservation flow (#10)
- context → ingest rename (#9)
- TTHW squeeze (#8)
- BYOK review-driven normalization

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
Preview — 64727197 Deployed Apr 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant