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..d80f2d4 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,48 @@ 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. - let authToken = readHelpbaseAuthToken() - if (isInteractive && source.kind !== "skip" && !authToken && !isByokMode()) { + // 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. + // `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 + ) { 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 +216,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 +224,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 @@ -262,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") { @@ -397,12 +429,33 @@ 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. + // + // 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 || + !!readHelpbaseAuthToken() || + !!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` + @@ -614,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) @@ -627,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"}.`)