Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<hex>.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
Expand Down
2 changes: 1 addition & 1 deletion packages/create-helpbase/package.json
Original file line number Diff line number Diff line change
@@ -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": {
Expand Down
133 changes: 95 additions & 38 deletions packages/create-helpbase/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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-<hex>.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-<hex>.helpbase.dev + 500k AI tokens/day, no card)",
initialValue: true,
})
if (isCancel(wantsLogin)) {
Expand All @@ -204,16 +216,35 @@ 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 {
// Re-read the token file — login just wrote it.
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
Expand Down Expand Up @@ -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") {
Expand Down Expand Up @@ -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 <slug>.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-<hex>.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 <slug>.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` +
Expand Down Expand Up @@ -614,9 +667,10 @@ async function runUrlGeneration(opts: {
projectDir: string
url: string
model: string
authToken?: string
spinner: ReturnType<typeof spinner>
}): Promise<boolean> {
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)
Expand All @@ -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"}.`)

Expand Down
Loading