From bb4575db1694f917b971cd51cc2ac3d7b48b0ca6 Mon Sep 17 00:00:00 2001 From: meglerhagen Date: Sun, 19 Apr 2026 09:50:06 +0200 Subject: [PATCH 1/2] feat(create-helpbase): login-first scaffolder (funnel capture) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moves the login prompt from after-source-selection to step 1, right after project-name validation. Fires on every cold scaffold regardless of source kind — previously gated on `source.kind !== "skip"`, which meant Skip users (picking sample content) walked through the whole scaffolder without ever being asked to claim a subdomain. 100% funnel leak on that path. Reframed the prompt copy as a perk, not a gate: was: "Log in to helpbase free? (500k tokens/day, no card — 30s browser flow)" now: "Claim your free docs URL? (docs-.helpbase.dev + 500k AI tokens/day, no card)" Leading with the concrete subdomain URL converts better than the abstract "sign in" ask — founders told us as much during the first cold dogfood of 0.4.0 this morning. Other changes: - BYOK users (ANTHROPIC_API_KEY / OPENAI_API_KEY / AI_GATEWAY_API_KEY) no longer skip the prompt. Subdomain reservation is orthogonal to AI creds; BYOK users benefit from a reserved deploy target. - HELPBASE_TOKEN env var skips the prompt (CI users pre-issue tokens). - Declined-login users see `npx helpbase login` as the first line of the end-of-scaffold "What next" block so the path to a subdomain stays visible. Logged-in users don't see the redundant hint. create-helpbase 0.4.0 → 0.5.0. Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 22 ++++++ packages/create-helpbase/package.json | 2 +- packages/create-helpbase/src/index.ts | 106 +++++++++++++++++--------- 3 files changed, 94 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 22e414e..d4a3942 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [create-helpbase 0.5.0] — 2026-04-19 + +### Changed +- **Login prompt now fires at step 1, before content-source selection.** The + previous design gated login on `source.kind !== "skip"`, so users who + picked Skip walked through the whole scaffolder without ever being asked + to claim a subdomain — a 100% funnel leak on that path. Login now runs + right after project-name validation on every cold scaffold. Users who + already have a session or `HELPBASE_TOKEN` skip the prompt silently. +- **Reframed the prompt copy as a perk, not a gate.** Was: "Log in to + helpbase free? (500k tokens/day, no card — 30s browser flow)". Now: + "Claim your free docs URL? (docs-.helpbase.dev + 500k AI tokens/day, + no card)". Leading with the concrete subdomain URL converts better than + the abstract "sign in" ask. +- **BYOK users also see the login prompt.** Previously skipped entirely + when `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `AI_GATEWAY_API_KEY` was + set. The subdomain reservation is orthogonal to AI credentials; BYOK + users still benefit from a reserved deploy target. +- **"What next" block adapts to auth state.** Declined-login users now + see `npx helpbase login` as the first line of the end-of-scaffold + next-steps block; logged-in users don't see the redundant hint. + ## [create-helpbase 0.4.0] — 2026-04-18 ### Added diff --git a/packages/create-helpbase/package.json b/packages/create-helpbase/package.json index 69fe784..c9cbc64 100644 --- a/packages/create-helpbase/package.json +++ b/packages/create-helpbase/package.json @@ -1,6 +1,6 @@ { "name": "create-helpbase", - "version": "0.4.0", + "version": "0.5.0", "description": "Create a beautiful, AI-powered help center in seconds", "type": "module", "bin": { diff --git a/packages/create-helpbase/src/index.ts b/packages/create-helpbase/src/index.ts index 1b7e055..e85549c 100644 --- a/packages/create-helpbase/src/index.ts +++ b/packages/create-helpbase/src/index.ts @@ -21,7 +21,6 @@ import { } from "@workspace/shared/ai-text" import { scaffoldProject, clearSampleContent } from "./scaffold.js" import { readHelpbaseAuthToken } from "./auth.js" -import { isByokMode } from "@workspace/shared/llm" import { generateFromRepo, AllDocsDroppedError, @@ -165,35 +164,41 @@ async function run(directory: string | undefined, opts: RunOptions) { } } - // 2. Content source selection. - // Explicit select first (URL / repo / skip), then the source-specific - // input. Rationale: single-prompt heuristics on the input itself made - // `my-repo` ambiguous between "subdirectory" and "bare URL without - // scheme". Splitting into select-then-input is explicit > clever. - // If --source / --url flags are set, honor them and skip the prompt. - const source = await resolveContentSource({ - flagUrl: opts.url, - flagSource: opts.source, - isInteractive, - }) - - if (source === "cancelled") { - cancel("Setup cancelled.") - process.exit(0) - } - - // 3. Auth resolution — conditional on existing state. - // Skip entirely when the user already has a helpbase session on disk - // or any BYOK env var set (ANTHROPIC_API_KEY / OPENAI_API_KEY / - // AI_GATEWAY_API_KEY via isByokMode()). - // Otherwise offer a single confirm — the target persona (YC founder - // with no key) always picks "log in free," so a 3-way select was - // cognitive noise. BYOK users route via env var before running; - // paste-a-key was removed to cut prompt count for the common path. + // 2. Login-first funnel capture (login-first scaffolder, 2026-04-19). + // Fires BEFORE source selection on every cold scaffold. Rationale: + // the previous design gated login on `source.kind !== "skip"` which + // meant Skip users walked through the whole flow without ever + // touching auth — 100% dead-air for the funnel. Moving it forward + // captures every scaffolder run as a lead and reserves their + // `docs-.helpbase.dev` subdomain before the user has picked a + // content source. + // + // The prompt copy leads with the subdomain hook (concrete benefit + // + free-tier reassurance + 30s effort framing) rather than the + // abstract "log in" ask. Tested with founders: the concrete URL + // name converts better than "sign in to continue." + // + // Skipped when: + // - Non-interactive (CI / piped stdin): can't device-flow anyway. + // - User already has a session on disk (`readHelpbaseAuthToken()`). + // - `HELPBASE_TOKEN` env var is set: CI users pre-issue tokens; no + // point prompting them to browser-flow through a login they + // already completed server-side. + // + // BYOK users (ANTHROPIC_API_KEY / OPENAI_API_KEY / AI_GATEWAY_API_KEY) + // are NOT skipped here — they already have AI creds, but the + // subdomain reservation is orthogonal and still valuable. Declining + // ("Not now") lets them proceed; they just won't have a hosted + // target until they run `helpbase login` later. let authToken = readHelpbaseAuthToken() - if (isInteractive && source.kind !== "skip" && !authToken && !isByokMode()) { + if ( + isInteractive && + !authToken && + !process.env.HELPBASE_TOKEN?.trim() + ) { const wantsLogin = await confirm({ - message: "Log in to helpbase free? (500k tokens/day, no card — 30s browser flow)", + message: + "Claim your free docs URL? (docs-.helpbase.dev + 500k AI tokens/day, no card)", initialValue: true, }) if (isCancel(wantsLogin)) { @@ -204,7 +209,7 @@ async function run(directory: string | undefined, opts: RunOptions) { const loginResult = await runHelpbaseLogin() if (loginResult === "failed") { note( - `Couldn't run helpbase login. Falling back to sample content. Run ${pc.cyan("npx helpbase@latest login")} after scaffold to retry.`, + `Couldn't complete login. You can still scaffold + use sample content. Run ${pc.cyan("npx helpbase@latest login")} later to claim a subdomain.`, "Login skipped", ) } else { @@ -212,8 +217,27 @@ async function run(directory: string | undefined, opts: RunOptions) { authToken = readHelpbaseAuthToken() } } - // Declined → fall through with no token, generation will error with - // the MissingApiKey path and the scaffolded sample content stays. + // Declined → fall through with no token. URL/repo sources without + // BYOK will hit MissingApiKey at AI gen time and the scaffolder + // falls back to sample content. The user gets a clear hint pointing + // at `helpbase login` in the fallback message. + } + + // 3. Content source selection. + // Explicit select first (URL / repo / skip), then the source-specific + // input. Rationale: single-prompt heuristics on the input itself made + // `my-repo` ambiguous between "subdirectory" and "bare URL without + // scheme". Splitting into select-then-input is explicit > clever. + // If --source / --url flags are set, honor them and skip the prompt. + const source = await resolveContentSource({ + flagUrl: opts.url, + flagSource: opts.source, + isInteractive, + }) + + if (source === "cancelled") { + cancel("Setup cancelled.") + process.exit(0) } // 4. Scaffold the project @@ -397,12 +421,24 @@ async function run(directory: string | undefined, opts: RunOptions) { note(bootstrap, "Run it locally") - note( - `${pc.cyan("npx helpbase ingest .")} ${pc.dim("generate docs from your repo source")}\n` + - `${pc.cyan("npx helpbase deploy")} ${pc.dim("go live at .helpbase.dev")}\n` + + // "What next" adapts to auth state. If the user declined the step-1 + // login prompt (or ran non-interactively without HELPBASE_TOKEN), + // lead with `helpbase login` so the path to a subdomain is visible + // at the end of the run. Logged-in users skip the redundant hint. + const loggedIn = + !!authToken || !!process.env.HELPBASE_TOKEN?.trim() + const nextLines: string[] = [] + if (!loggedIn) { + nextLines.push( + `${pc.cyan("npx helpbase login")} ${pc.dim("claim docs-.helpbase.dev (free, no card)")}`, + ) + } + nextLines.push( + `${pc.cyan("npx helpbase ingest .")} ${pc.dim("generate docs from your repo source")}`, + `${pc.cyan("npx helpbase deploy")} ${pc.dim("go live at .helpbase.dev")}`, `${pc.cyan("npx helpbase new")} ${pc.dim("add a new article interactively")}`, - "What next", ) + note(nextLines.join("\n"), "What next") outro( `${pc.green("Your help center is ready!")}\n` + From 06bde0e4a93d30f91bd8adde9ddd46a9d538c36c Mon Sep 17 00:00:00 2001 From: meglerhagen Date: Sun, 19 Apr 2026 10:03:54 +0200 Subject: [PATCH 2/2] fix(create-helpbase): thread HELPBASE_TOKEN into AI gen + refresh auth state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two CodeRabbit findings on PR #13: CR#1 (Major): `authToken` was initialized only from ~/.helpbase/auth.json via readHelpbaseAuthToken(). When a CI user set `HELPBASE_TOKEN`, the step-1 login prompt was correctly skipped, but the env token never reached `generateArticlesFromContent` / `generateFromRepo` — AI gen failed MissingApiKey and the scaffolder silently fell back to sample content. Now: initialize with disk-OR-env, and thread the resolved token through `runUrlGeneration` (which was re-reading disk) and `runRepoGeneration` (already accepted it). CR#2 (Minor): the "What next" block computed `loggedIn` from the in-memory `authToken` variable, which stays undefined if the user declined step-1 but logged in later via the ship-it-now subprocess (that path writes the token file but doesn't mutate the outer variable). Now re-read disk when computing `loggedIn` so the redundant "run helpbase login" hint doesn't show to users who just logged in. Co-Authored-By: Claude Opus 4.7 (1M context) --- packages/create-helpbase/src/index.ts | 33 ++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/packages/create-helpbase/src/index.ts b/packages/create-helpbase/src/index.ts index e85549c..d80f2d4 100644 --- a/packages/create-helpbase/src/index.ts +++ b/packages/create-helpbase/src/index.ts @@ -190,11 +190,18 @@ async function run(directory: string | undefined, opts: RunOptions) { // subdomain reservation is orthogonal and still valuable. Declining // ("Not now") lets them proceed; they just won't have a hosted // target until they run `helpbase login` later. - let authToken = readHelpbaseAuthToken() + // `authToken` is the token threaded into AI generation calls. Prefer + // the on-disk session, fall back to HELPBASE_TOKEN so CI/non-interactive + // runs that pre-issue the env var get a working AI path without the + // interactive login. Without this, the env-var user would skip the + // prompt (good) but AI gen would still fail MissingApiKey because the + // env var was never passed to `generateArticlesFromContent` / + // `generateFromRepo`. + let authToken = + readHelpbaseAuthToken() || process.env.HELPBASE_TOKEN?.trim() || undefined if ( isInteractive && - !authToken && - !process.env.HELPBASE_TOKEN?.trim() + !authToken ) { const wantsLogin = await confirm({ message: @@ -286,6 +293,7 @@ async function run(directory: string | undefined, opts: RunOptions) { projectDir, url: source.url, model: resolveModel({ test: opts.test, modelOverride: opts.model }), + authToken, spinner: s, }) } else if (source.kind === "repo") { @@ -425,8 +433,17 @@ async function run(directory: string | undefined, opts: RunOptions) { // login prompt (or ran non-interactively without HELPBASE_TOKEN), // lead with `helpbase login` so the path to a subdomain is visible // at the end of the run. Logged-in users skip the redundant hint. + // + // Re-read the token file here rather than trusting the `authToken` + // variable — it may be stale if the user declined step 1 but later + // logged in via the ship-it-now path (which spawns `helpbase login` + // in a subprocess and writes the token file from there). Avoiding a + // redundant "run `helpbase login`" hint for someone who just did is + // the whole point. const loggedIn = - !!authToken || !!process.env.HELPBASE_TOKEN?.trim() + !!authToken || + !!readHelpbaseAuthToken() || + !!process.env.HELPBASE_TOKEN?.trim() const nextLines: string[] = [] if (!loggedIn) { nextLines.push( @@ -650,9 +667,10 @@ async function runUrlGeneration(opts: { projectDir: string url: string model: string + authToken?: string spinner: ReturnType }): Promise { - const { projectDir, url, model, spinner: s } = opts + const { projectDir, url, model, authToken, spinner: s } = opts try { s.start(`Scraping ${pc.cyan(url)}...`) const content = await scrapeUrl(url) @@ -663,7 +681,10 @@ async function runUrlGeneration(opts: { content, sourceUrl: url, model, - authToken: readHelpbaseAuthToken(), + // Use the token threaded from run() — honors HELPBASE_TOKEN env var + // for CI callers AND the step-1 login path. Re-reading disk here + // would miss the env-var case entirely. + authToken, }) s.stop(`Synthesized ${articles.length} article${articles.length === 1 ? "" : "s"}.`)