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
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [create-helpbase 0.4.0] — 2026-04-18

### Added
- **Ship-it-now prompt at end of scaffold.** After `create-helpbase` finishes
scaffolding + generating articles + installing deps, the CLI now asks
"Ship it now?" with Y as the default. On Y it runs `helpbase login` (if
needed) and `helpbase deploy` inline, then prints the live URL and MCP
config block — cold TTHW from `pnpm dlx create-helpbase` to a public help
center collapses from ~3 min (scaffold → cd → login → deploy) to ~90s.
Declining falls through to today's "Run it locally" + auto-dev-server flow,
byte-for-byte. Skipped when the user picked sample content, when AI
generation failed, or when stdin is not a TTY.
- **`--deploy` / `--no-deploy` flags** for non-interactive control. `--deploy`
skips the prompt and assumes Y (CI-friendly ship with `HELPBASE_TOKEN`
set). `--no-deploy` skips the prompt and keeps today's scaffold-only
behavior. Neither flag is needed for the common interactive path.

## [helpbase 0.6.0] — 2026-04-18

### Added
Expand Down
44 changes: 19 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,36 +60,30 @@ log into.

## Quick start

Live help center in 2 minutes. See it on `localhost` first, then ship
it to your own subdomain. Works on macOS, Linux, and Windows. Requires
Node 20+.
Live help center in 90 seconds. Scaffold, answer Y, you're on the
public internet. Works on macOS, Linux, and Windows. Requires Node 20+.

```bash
# 1. Scaffold a full helpbase project — Next.js app + content + MCP config
pnpm dlx create-helpbase@latest my-docs # or: npx create-helpbase@latest my-docs
cd my-docs

# 2. See it locally — open http://localhost:3000
pnpm dev # or: npm run dev

# 3. Reserve your subdomain (browser device-flow login, free 500k tokens/day)
npx helpbase login # ↳ Reserved: docs-<hex>.helpbase.dev

# 4. Pick a vanity slug before first deploy (optional)
npx helpbase rename acme

# 5. Preview what will ship, then deploy
npx helpbase deploy --preview # show the diff, no writes
npx helpbase deploy # publish to your reserved URL
# ↳ answer Y to "Ship it now?" — logs you in + deploys inline
# ↳ prints your live URL: https://docs-<hex>.helpbase.dev
```

That's it. You've got a live docs site on `localhost` AND on your
reserved `.helpbase.dev` subdomain. Edit `content/` files, re-run
`helpbase deploy` to push updates. `helpbase deploy --preview` shows
added / updated / removed articles before you ship — silent on routine
updates, prompts before any removal lands. After first deploy the URL
is locked so existing links don't break; rename only works before that
point. Run `helpbase whoami` to see what's reserved + deployed.
That's it. Answering Y at the end runs `helpbase login` (browser
device-flow, free 500k tokens/day, no card) and `helpbase deploy`
back-to-back and prints the public URL + MCP config block. Answer `n`
to keep the classic flow: the scaffolder starts `pnpm dev` locally and
you run `helpbase login` + `helpbase deploy` yourself when ready. CI /
pipelines pass `--no-deploy` (or `--deploy` with `HELPBASE_TOKEN`) to
skip the prompt.

Edit `content/` files, re-run `helpbase deploy` to push updates.
`helpbase deploy --preview` shows added / updated / removed articles
before you ship — silent on routine updates, prompts before any
removal lands. `helpbase rename acme` claims a vanity slug
(`acme.helpbase.dev`) — only works before the first deploy; after that,
the URL is locked so existing links don't break. Run `helpbase whoami`
to see what's reserved + deployed.

> **Already have a Next.js app?** Skip the scaffolder:
> `npx shadcn add https://helpbase.dev/r/help-center.json`
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.3.1",
"version": "0.4.0",
"description": "Create a beautiful, AI-powered help center in seconds",
"type": "module",
"bin": {
Expand Down
181 changes: 179 additions & 2 deletions packages/create-helpbase/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import pc from "picocolors"
import fs from "node:fs"
import os from "node:os"
import path from "node:path"
import { fileURLToPath } from "node:url"
import { execSync, spawn } from "node:child_process"
import {
planArticleWrites,
Expand All @@ -28,6 +29,27 @@ import {
SchemaGenerationError,
} from "./generate-from-repo.js"
import { emitMcpJson } from "./emit-mcp-json.js"
import { resolveShipItNow, ShipItNowRefusedError } from "./ship-it-now.js"

/**
* Read version from package.json at startup. The literal string used to be
* hardcoded and drifted every release (CLI said 0.0.1 while npm shipped
* 0.4.0). Reading from disk keeps them in sync — package.json is always
* present in the published tarball regardless of the `files` allowlist.
*/
function readPackageVersion(): string {
try {
const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url))
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { version?: string }
if (typeof pkg.version === "string" && pkg.version.length > 0) {
return pkg.version
}
} catch {
// Fall through to the sentinel below. The version string is cosmetic;
// a failure here should not crash the CLI on startup.
}
return "0.0.0-unknown"
}

interface RunOptions {
url?: string
Expand All @@ -37,6 +59,7 @@ interface RunOptions {
test?: boolean
model?: string
internal?: boolean
deploy?: boolean
}

const PROJECT_NAME_REGEX = /^[a-z0-9-]+$/
Expand All @@ -53,7 +76,7 @@ function validateProjectName(name: string): string | undefined {
const program = new Command()
.name("create-helpbase")
.description("Create a beautiful, AI-powered help center in seconds")
.version("0.0.1")
.version(readPackageVersion())
.argument("[directory]", "Directory to create the project in")
.option("--url <url>", "Generate articles from a website URL")
.option(
Expand All @@ -71,6 +94,14 @@ const program = new Command()
"--internal",
"Scaffold an internal-KB layout (handbook + runbooks + ADRs, auth-ready MCP via HELPBASE_MCP_TOKEN)",
)
.option(
"--deploy",
"Ship to helpbase cloud immediately after scaffold (skip the prompt, assume yes)",
)
.option(
"--no-deploy",
"Skip the ship-it-now prompt (scaffold only, keep today's behavior)",
)
.action(run)

program.parse()
Expand Down Expand Up @@ -269,7 +300,88 @@ async function run(directory: string | undefined, opts: RunOptions) {
}
}

// 8. Done!
// 8.5. Ship-it-now prompt (Shape A, 2026-04-18).
// If we're interactive, had real content generated, and the user
// didn't pass --no-deploy, offer to publish to helpbase cloud in
// one step. Collapses cold TTHW from ~3min → ~90s by removing the
// manual `cd` + `login` + `deploy` chain.
//
// Y path: ensure auth (spawn login if no token), then spawn
// `helpbase deploy` in the new project dir with inherited stdio.
// On success, `helpbase deploy` already prints the live URL + MCP
// config block, so we skip the "Run it locally" + "What next" +
// dev-server-auto-open tail — the user's magical moment is the
// live URL, not localhost.
//
// n path (or Y-failure): fall through to the existing local-first
// outro so nothing regresses for users who want to edit before
// shipping.
// CI detection: `isInteractive` comes from `process.stdin.isTTY`, which CI
// jobs can legitimately allocate. For the ship-it-now decision we want the
// stricter "is this a real human" check so `--deploy --source skip` in CI
// hits the non-interactive refusal path and does not drop into the N-default
// confirm. `process.env.CI` is the de-facto convention (GitHub Actions,
// CircleCI, GitLab, Travis all set it). Kept separate from `isInteractive`
// so the earlier prompts (project name, source pick, login) preserve
// today's "TTY means prompt" semantics.
const humanInteractive = isInteractive && !process.env.CI

let wantsDeploy: boolean
try {
wantsDeploy = await resolveShipItNow({
flagDeploy: opts.deploy,
sourceKind: source.kind,
isInteractive: humanInteractive,
generationSucceeded,
})
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
} catch (err) {
if (err instanceof ShipItNowRefusedError) {
cancel(err.message)
process.exit(1)
}
throw err
}

if (wantsDeploy) {
// `readHelpbaseAuthToken()` only reads ~/.helpbase/auth.json; it misses
// the `HELPBASE_TOKEN` env var (the advertised CI path). `helpbase deploy`
// itself handles the env var fine, but if we require a file-token here we
// either spawn login (blocks forever in CI without a TTY) or bail early
// before deploy ever runs. Treat the env var as a valid truthy gate; let
// the subprocess validate it at the real auth boundary.
let token =
readHelpbaseAuthToken() || process.env.HELPBASE_TOKEN?.trim() || undefined
if (!token && humanInteractive) {
const r = await runHelpbaseLogin()
if (r === "ok") token = readHelpbaseAuthToken()
}
if (!token) {
note(
`Couldn't log you in. Run ${pc.cyan(`cd ${projectName as string} && npx helpbase deploy`)} when you're ready.`,
"Ship-it-now skipped",
)
} else {
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
const deployResult = await runHelpbaseDeploy(projectDir)
if (deployResult.kind === "ok") {
outro(`${pc.green("Your help center is live!")}`)
if (source.kind === "repo" && source.tempClone) {
try {
fs.rmSync(source.tempClone, { recursive: true, force: true })
} catch {
// best-effort
}
}
return
}
note(
`${pc.dim(deployResult.errorTail)}\n\n` +
`Retry with ${pc.cyan(`cd ${projectName as string} && npx helpbase deploy`)}.`,
"Deploy failed",
)
}
}

// 9. Done!
const cdCmd = projectDir === process.cwd()
? ""
: `cd ${projectName as string}`
Expand Down Expand Up @@ -775,6 +887,71 @@ function printRepoGenerationFallbackHint(err: unknown, repoPath: string): void {
)
}

/**
* Result shape for runHelpbaseDeploy. On failure we surface the last
* non-empty output line so the "Deploy failed" note can name the cause
* without asking the user to scroll up through several screens of clack
* box-drawing. The deploy subprocess stdout/stderr is tee'd — user sees
* the live output AND we keep a rolling tail for the failure path.
*/
type DeployOutcome = { kind: "ok" } | { kind: "failed"; errorTail: string }

/**
* Spawn `helpbase deploy` in the scaffolded project dir. Stdin is
* inherited so clack prompts inside deploy still render. Stdout/stderr
* are piped + tee'd so the user sees output live AND we capture the
* trailing 500 bytes of each stream. On non-zero exit we return the
* last non-empty line of stderr (falling back to stdout) as errorTail
* so the failure note can be self-contained.
*
* Uses the same package-manager detection + `dlx`/`npx` fallback as
* runHelpbaseLogin so first-time users without a global helpbase install
* still get the binary resolved for them.
*/
async function runHelpbaseDeploy(projectDir: string): Promise<DeployOutcome> {
const pkgManager = detectPackageManager()
const [cmd, ...args] =
pkgManager === "pnpm"
? ["pnpm", "dlx", "helpbase@latest", "deploy"]
: pkgManager === "yarn"
? ["yarn", "dlx", "helpbase@latest", "deploy"]
: pkgManager === "bun"
? ["bunx", "helpbase@latest", "deploy"]
: ["npx", "-y", "helpbase@latest", "deploy"]

return new Promise<DeployOutcome>((resolve) => {
let stdoutTail = ""
let stderrTail = ""
const child = spawn(cmd, args, {
stdio: ["inherit", "pipe", "pipe"],
cwd: projectDir,
env: process.env,
})
child.stdout?.on("data", (chunk: Buffer) => {
process.stdout.write(chunk)
stdoutTail = (stdoutTail + chunk.toString()).slice(-500)
})
child.stderr?.on("data", (chunk: Buffer) => {
process.stderr.write(chunk)
stderrTail = (stderrTail + chunk.toString()).slice(-500)
})
const lastMeaningfulLine = (): string => {
const tail = (stderrTail.trim() || stdoutTail.trim())
// Strip ANSI color codes so the quoted line reads cleanly in our note.
.replace(/\x1b\[[0-9;]*m/g, "")
const lines = tail.split("\n").map((l) => l.trim()).filter(Boolean)
return lines[lines.length - 1] ?? "no error output captured"
}
child.on("exit", (code) => {
if (code === 0) resolve({ kind: "ok" })
else resolve({ kind: "failed", errorTail: lastMeaningfulLine() })
})
child.on("error", (err) =>
resolve({ kind: "failed", errorTail: err.message }),
)
})
}

/**
* Run `helpbase login` as a subprocess with stdio inherited so the user
* sees the real login prompt (email → OTP). Returns "ok" if the login
Expand Down
Loading
Loading