From 2ee35deaaaccc3186462c05c6ad7072b162c532e Mon Sep 17 00:00:00 2001 From: meglerhagen Date: Sat, 18 Apr 2026 20:47:19 +0200 Subject: [PATCH 1/3] feat(create-helpbase): ship-it-now prompt at end of scaffold (Shape A) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Collapses cold TTHW from ~3 min (scaffold → cd → login → deploy) to ~90s. After install completes, prompt "Ship it to helpbase cloud? (~20 seconds)" with Y as the default. Y runs `helpbase login` (if needed) + `helpbase deploy` inline via subprocess, so the user sees the real deploy flow: preview, MCP config, live URL. N falls through to today's "Run it locally" + dev-server flow, byte-for-byte. - `--deploy` / `--no-deploy` flags for non-interactive mode - `--deploy --source skip` refuses in CI (footgun guard) and re-prompts with N-default interactively - `--version` now reads from package.json (was hardcoded 0.0.1 and drifted every release) - Deploy-failed note surfaces last output line so user doesn't scroll - 9 new unit tests for resolveShipItNow, +2 integration assertions create-helpbase 0.3.1 → 0.4.0. Design doc: Shape A (2026-04-18). Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 17 ++ README.md | 44 ++-- packages/create-helpbase/package.json | 2 +- packages/create-helpbase/src/index.ts | 164 ++++++++++++++- packages/create-helpbase/src/ship-it-now.ts | 84 ++++++++ .../test/cli.integration.test.ts | 15 +- .../test/resolve-ship-it-now.unit.test.ts | 192 ++++++++++++++++++ 7 files changed, 487 insertions(+), 31 deletions(-) create mode 100644 packages/create-helpbase/src/ship-it-now.ts create mode 100644 packages/create-helpbase/test/resolve-ship-it-now.unit.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index fa728c8..22e414e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 311884f..2e4a1ea 100644 --- a/README.md +++ b/README.md @@ -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-.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-.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` diff --git a/packages/create-helpbase/package.json b/packages/create-helpbase/package.json index 65bf417..69fe784 100644 --- a/packages/create-helpbase/package.json +++ b/packages/create-helpbase/package.json @@ -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": { diff --git a/packages/create-helpbase/src/index.ts b/packages/create-helpbase/src/index.ts index 64d98ac..3e0bbf0 100644 --- a/packages/create-helpbase/src/index.ts +++ b/packages/create-helpbase/src/index.ts @@ -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, @@ -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 @@ -37,6 +59,7 @@ interface RunOptions { test?: boolean model?: string internal?: boolean + deploy?: boolean } const PROJECT_NAME_REGEX = /^[a-z0-9-]+$/ @@ -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 ", "Generate articles from a website URL") .option( @@ -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() @@ -269,7 +300,71 @@ 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. + let wantsDeploy: boolean + try { + wantsDeploy = await resolveShipItNow({ + flagDeploy: opts.deploy, + sourceKind: source.kind, + isInteractive, + generationSucceeded, + }) + } catch (err) { + if (err instanceof ShipItNowRefusedError) { + cancel(err.message) + process.exit(1) + } + throw err + } + + if (wantsDeploy) { + let token = readHelpbaseAuthToken() + if (!token) { + 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 { + 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}` @@ -775,6 +870,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 { + 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((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 diff --git a/packages/create-helpbase/src/ship-it-now.ts b/packages/create-helpbase/src/ship-it-now.ts new file mode 100644 index 0000000..8396b47 --- /dev/null +++ b/packages/create-helpbase/src/ship-it-now.ts @@ -0,0 +1,84 @@ +import { confirm, isCancel } from "@clack/prompts" + +/** + * Thrown when `--deploy` is combined with `--source skip` in a + * non-interactive context. The caller should print this error's message + * verbatim via `cancel()` and exit 1 — the user's intent ("publish + * sample content to a real subdomain") is almost always a mistake (e.g. + * CI that uses `--source skip` as a placeholder). Exported so callers + * can match on the instance rather than error message text. + */ +export class ShipItNowRefusedError extends Error { + constructor(message: string) { + super(message) + this.name = "ShipItNowRefusedError" + } +} + +/** + * Tri-state resolver for the ship-it-now prompt (Shape A, 2026-04-18). + * Pure (no I/O beyond the clack confirm when we actually prompt), so + * smoke tests cover every branch without spawning real subprocesses. + * + * Precedence: + * 1. `--no-deploy` → no deploy. Explicit user opt-out wins over anything. + * 2. `--deploy` + `sourceKind === "skip"`: + * - non-interactive → throw ShipItNowRefusedError. Publishing sample + * content to a public subdomain from CI is almost always a + * mistake; the user has to drop one of the two flags explicitly. + * - interactive → extra confirm (initialValue: false) so the user + * re-acknowledges "yes, really publish lorem ipsum." + * 3. `--deploy` (any other source) → deploy. + * 4. `sourceKind === "skip"` (no flag) → no deploy. Sample content + * should not auto-ship. + * 5. Non-interactive (no flag, no TTY) → no deploy. Silent default + * keeps CI + piped usage on today's behavior. + * 6. AI generation failed → no deploy. Sample content remains, same + * reasoning as rule 4. + * 7. Otherwise → prompt. + * + * Lives in its own module so importing it from tests does not trigger + * the commander program.parse() side effect in src/index.ts. + */ +export async function resolveShipItNow(opts: { + flagDeploy: boolean | undefined + sourceKind: "url" | "repo" | "skip" + isInteractive: boolean + generationSucceeded: boolean + promptFn?: typeof confirm +}): Promise { + if (opts.flagDeploy === false) return false + + const prompt = opts.promptFn ?? confirm + + if (opts.flagDeploy === true) { + if (opts.sourceKind === "skip") { + if (!opts.isInteractive) { + throw new ShipItNowRefusedError( + "Refusing to publish sample content with --deploy. " + + "Either drop --source skip (use --source to generate real articles), " + + "or drop --deploy.", + ) + } + const ok = await prompt({ + message: + "Publish SAMPLE content to your public subdomain? Run with --source to generate real articles first", + initialValue: false, + }) + if (isCancel(ok)) return false + return ok === true + } + return true + } + + if (!opts.isInteractive) return false + if (opts.sourceKind === "skip") return false + if (!opts.generationSucceeded) return false + + const answer = await prompt({ + message: "Ship it to helpbase cloud? (~20 seconds)", + initialValue: true, + }) + if (isCancel(answer)) return false + return answer === true +} diff --git a/packages/create-helpbase/test/cli.integration.test.ts b/packages/create-helpbase/test/cli.integration.test.ts index 936c713..d8dd542 100644 --- a/packages/create-helpbase/test/cli.integration.test.ts +++ b/packages/create-helpbase/test/cli.integration.test.ts @@ -40,11 +40,20 @@ describe("create-helpbase CLI integration", () => { expect(output).toContain("--url") expect(output).toContain("--no-install") expect(output).toContain("--no-open") + expect(output).toContain("--deploy") + expect(output).toContain("--no-deploy") }) - it("prints version", () => { - const output = execSync(`node ${CLI} --version`, { encoding: "utf-8" }) - expect(output.trim()).toBe("0.0.1") + it("prints version from package.json (not a hardcoded string)", () => { + const output = execSync(`node ${CLI} --version`, { encoding: "utf-8" }).trim() + // Semver-ish check: at minimum MAJOR.MINOR.PATCH with digits. Guards + // against the pre-0.4.0 bug where the CLI's `.version()` literal + // drifted from package.json every release. + expect(output).toMatch(/^\d+\.\d+\.\d+/) + const pkg = JSON.parse( + fs.readFileSync(path.resolve(__dirname, "../package.json"), "utf-8"), + ) as { version: string } + expect(output).toBe(pkg.version) }) it("help text mentions directory argument", () => { diff --git a/packages/create-helpbase/test/resolve-ship-it-now.unit.test.ts b/packages/create-helpbase/test/resolve-ship-it-now.unit.test.ts new file mode 100644 index 0000000..fc405c8 --- /dev/null +++ b/packages/create-helpbase/test/resolve-ship-it-now.unit.test.ts @@ -0,0 +1,192 @@ +import { describe, it, expect, vi } from "vitest" +import { resolveShipItNow, ShipItNowRefusedError } from "../src/ship-it-now.js" + +// Stub matching clack's confirm() return. Never called when the +// precedence rules above the prompt short-circuit the decision. +const fakeConfirm = (answer: boolean | symbol) => { + return vi.fn(async () => answer) as any +} + +describe("resolveShipItNow — flag precedence", () => { + it("returns true when --deploy is passed with real content (url)", async () => { + const prompt = fakeConfirm(false) + const got = await resolveShipItNow({ + flagDeploy: true, + sourceKind: "url", + isInteractive: false, + generationSucceeded: false, + promptFn: prompt, + }) + expect(got).toBe(true) + expect(prompt).not.toHaveBeenCalled() + }) + + it("returns true when --deploy is passed with a repo source", async () => { + const prompt = fakeConfirm(false) + const got = await resolveShipItNow({ + flagDeploy: true, + sourceKind: "repo", + isInteractive: true, + generationSucceeded: true, + promptFn: prompt, + }) + expect(got).toBe(true) + expect(prompt).not.toHaveBeenCalled() + }) + + it("returns false when --no-deploy is passed (overrides everything)", async () => { + const prompt = fakeConfirm(true) + const got = await resolveShipItNow({ + flagDeploy: false, + sourceKind: "url", + isInteractive: true, + generationSucceeded: true, + promptFn: prompt, + }) + expect(got).toBe(false) + expect(prompt).not.toHaveBeenCalled() + }) +}) + +describe("resolveShipItNow — --deploy + --source skip footgun", () => { + it("throws ShipItNowRefusedError in non-interactive mode", async () => { + const prompt = fakeConfirm(true) + await expect( + resolveShipItNow({ + flagDeploy: true, + sourceKind: "skip", + isInteractive: false, + generationSucceeded: true, + promptFn: prompt, + }), + ).rejects.toBeInstanceOf(ShipItNowRefusedError) + expect(prompt).not.toHaveBeenCalled() + }) + + it("refused error message mentions both flags so user knows how to fix", async () => { + try { + await resolveShipItNow({ + flagDeploy: true, + sourceKind: "skip", + isInteractive: false, + generationSucceeded: true, + }) + expect.fail("expected throw") + } catch (err) { + expect(err).toBeInstanceOf(ShipItNowRefusedError) + expect((err as Error).message).toContain("--deploy") + expect((err as Error).message).toContain("--source") + } + }) + + it("interactive mode re-prompts with N-default, returns true on explicit Y", async () => { + const prompt = fakeConfirm(true) + const got = await resolveShipItNow({ + flagDeploy: true, + sourceKind: "skip", + isInteractive: true, + generationSucceeded: true, + promptFn: prompt, + }) + expect(got).toBe(true) + expect(prompt).toHaveBeenCalledOnce() + // Footgun-confirm should default to false (N). + const call = prompt.mock.calls[0][0] as { initialValue: boolean } + expect(call.initialValue).toBe(false) + }) + + it("interactive mode returns false when user declines sample-content publish", async () => { + const prompt = fakeConfirm(false) + const got = await resolveShipItNow({ + flagDeploy: true, + sourceKind: "skip", + isInteractive: true, + generationSucceeded: true, + promptFn: prompt, + }) + expect(got).toBe(false) + expect(prompt).toHaveBeenCalledOnce() + }) +}) + +describe("resolveShipItNow — implicit skip paths", () => { + it("returns false when source === 'skip' (sample content)", async () => { + const prompt = fakeConfirm(true) + const got = await resolveShipItNow({ + flagDeploy: undefined, + sourceKind: "skip", + isInteractive: true, + generationSucceeded: true, + promptFn: prompt, + }) + expect(got).toBe(false) + expect(prompt).not.toHaveBeenCalled() + }) + + it("returns false in non-interactive mode (no flag, no TTY)", async () => { + const prompt = fakeConfirm(true) + const got = await resolveShipItNow({ + flagDeploy: undefined, + sourceKind: "url", + isInteractive: false, + generationSucceeded: true, + promptFn: prompt, + }) + expect(got).toBe(false) + expect(prompt).not.toHaveBeenCalled() + }) + + it("returns false when AI generation failed (sample content remains)", async () => { + const prompt = fakeConfirm(true) + const got = await resolveShipItNow({ + flagDeploy: undefined, + sourceKind: "url", + isInteractive: true, + generationSucceeded: false, + promptFn: prompt, + }) + expect(got).toBe(false) + expect(prompt).not.toHaveBeenCalled() + }) +}) + +describe("resolveShipItNow — interactive prompt", () => { + it("prompts and returns true when user confirms", async () => { + const prompt = fakeConfirm(true) + const got = await resolveShipItNow({ + flagDeploy: undefined, + sourceKind: "url", + isInteractive: true, + generationSucceeded: true, + promptFn: prompt, + }) + expect(got).toBe(true) + expect(prompt).toHaveBeenCalledOnce() + }) + + it("prompts and returns false when user declines", async () => { + const prompt = fakeConfirm(false) + const got = await resolveShipItNow({ + flagDeploy: undefined, + sourceKind: "repo", + isInteractive: true, + generationSucceeded: true, + promptFn: prompt, + }) + expect(got).toBe(false) + expect(prompt).toHaveBeenCalledOnce() + }) + + it("returns false when user cancels the prompt (Ctrl-C)", async () => { + const cancelSymbol = Symbol.for("clack:cancel") + const prompt = fakeConfirm(cancelSymbol) + const got = await resolveShipItNow({ + flagDeploy: undefined, + sourceKind: "url", + isInteractive: true, + generationSucceeded: true, + promptFn: prompt, + }) + expect(got).toBe(false) + }) +}) From fe84d099922ee8fbf857a1e498a4422b318ecdba Mon Sep 17 00:00:00 2001 From: meglerhagen Date: Sat, 18 Apr 2026 20:53:14 +0200 Subject: [PATCH 2/3] fix(create-helpbase): extend ship-it-now footgun guard to AI-generation-failed case MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The guard that refuses `--deploy` + `--source skip` in non-interactive mode also needs to catch the symmetric case: `--deploy` with `generationSucceeded: false`. Both paths leave sample content on disk and publishing it to a public subdomain is almost always unintended. Non-interactive → throws ShipItNowRefusedError with a message pointing at the generation failure. Interactive → re-prompts with N-default, same pattern as the skip case. Caught by /review on this branch. Co-Authored-By: Claude Opus 4.7 (1M context) --- packages/create-helpbase/src/ship-it-now.ts | 36 +++++++++----- .../test/resolve-ship-it-now.unit.test.ts | 49 ++++++++++++++++++- 2 files changed, 71 insertions(+), 14 deletions(-) diff --git a/packages/create-helpbase/src/ship-it-now.ts b/packages/create-helpbase/src/ship-it-now.ts index 8396b47..c96f5a7 100644 --- a/packages/create-helpbase/src/ship-it-now.ts +++ b/packages/create-helpbase/src/ship-it-now.ts @@ -22,19 +22,21 @@ export class ShipItNowRefusedError extends Error { * * Precedence: * 1. `--no-deploy` → no deploy. Explicit user opt-out wins over anything. - * 2. `--deploy` + `sourceKind === "skip"`: + * 2. `--deploy` + sample content on disk (either `sourceKind === "skip"` + * OR `generationSucceeded === false`, since both leave the scaffolder's + * lorem ipsum on disk): * - non-interactive → throw ShipItNowRefusedError. Publishing sample * content to a public subdomain from CI is almost always a - * mistake; the user has to drop one of the two flags explicitly. + * mistake; the user has to drop --deploy or resolve the reason + * sample content is on disk. * - interactive → extra confirm (initialValue: false) so the user * re-acknowledges "yes, really publish lorem ipsum." - * 3. `--deploy` (any other source) → deploy. + * 3. `--deploy` (real content synthesized) → deploy. * 4. `sourceKind === "skip"` (no flag) → no deploy. Sample content * should not auto-ship. * 5. Non-interactive (no flag, no TTY) → no deploy. Silent default * keeps CI + piped usage on today's behavior. - * 6. AI generation failed → no deploy. Sample content remains, same - * reasoning as rule 4. + * 6. AI generation failed (no flag) → no deploy. Same as rule 4. * 7. Otherwise → prompt. * * Lives in its own module so importing it from tests does not trigger @@ -52,17 +54,25 @@ export async function resolveShipItNow(opts: { const prompt = opts.promptFn ?? confirm if (opts.flagDeploy === true) { - if (opts.sourceKind === "skip") { + const sampleOnDisk = opts.sourceKind === "skip" || !opts.generationSucceeded + if (sampleOnDisk) { if (!opts.isInteractive) { - throw new ShipItNowRefusedError( - "Refusing to publish sample content with --deploy. " + - "Either drop --source skip (use --source to generate real articles), " + - "or drop --deploy.", - ) + const reason = + opts.sourceKind === "skip" + ? "Refusing to publish sample content with --deploy. " + + "Either drop --source skip (use --source to generate real articles), " + + "or drop --deploy." + : "Refusing to publish with --deploy: AI generation did not succeed, " + + "so sample content is still on disk. Resolve the generation error (check API keys / network) " + + "and re-run, or drop --deploy." + throw new ShipItNowRefusedError(reason) } + const message = + opts.sourceKind === "skip" + ? "Publish SAMPLE content to your public subdomain? Run with --source to generate real articles first" + : "AI generation didn't succeed and sample content is on disk. Publish SAMPLE content anyway?" const ok = await prompt({ - message: - "Publish SAMPLE content to your public subdomain? Run with --source to generate real articles first", + message, initialValue: false, }) if (isCancel(ok)) return false diff --git a/packages/create-helpbase/test/resolve-ship-it-now.unit.test.ts b/packages/create-helpbase/test/resolve-ship-it-now.unit.test.ts index fc405c8..8afac10 100644 --- a/packages/create-helpbase/test/resolve-ship-it-now.unit.test.ts +++ b/packages/create-helpbase/test/resolve-ship-it-now.unit.test.ts @@ -14,7 +14,7 @@ describe("resolveShipItNow — flag precedence", () => { flagDeploy: true, sourceKind: "url", isInteractive: false, - generationSucceeded: false, + generationSucceeded: true, promptFn: prompt, }) expect(got).toBe(true) @@ -109,6 +109,53 @@ describe("resolveShipItNow — --deploy + --source skip footgun", () => { }) }) +describe("resolveShipItNow — --deploy + generation-failed footgun", () => { + it("throws ShipItNowRefusedError in non-interactive mode", async () => { + const prompt = fakeConfirm(true) + await expect( + resolveShipItNow({ + flagDeploy: true, + sourceKind: "url", + isInteractive: false, + generationSucceeded: false, + promptFn: prompt, + }), + ).rejects.toBeInstanceOf(ShipItNowRefusedError) + expect(prompt).not.toHaveBeenCalled() + }) + + it("error message mentions generation failure + --deploy", async () => { + try { + await resolveShipItNow({ + flagDeploy: true, + sourceKind: "repo", + isInteractive: false, + generationSucceeded: false, + }) + expect.fail("expected throw") + } catch (err) { + expect(err).toBeInstanceOf(ShipItNowRefusedError) + expect((err as Error).message).toMatch(/generation/i) + expect((err as Error).message).toContain("--deploy") + } + }) + + it("interactive mode re-prompts with N-default", async () => { + const prompt = fakeConfirm(false) + const got = await resolveShipItNow({ + flagDeploy: true, + sourceKind: "url", + isInteractive: true, + generationSucceeded: false, + promptFn: prompt, + }) + expect(got).toBe(false) + expect(prompt).toHaveBeenCalledOnce() + const call = prompt.mock.calls[0][0] as { initialValue: boolean } + expect(call.initialValue).toBe(false) + }) +}) + describe("resolveShipItNow — implicit skip paths", () => { it("returns false when source === 'skip' (sample content)", async () => { const prompt = fakeConfirm(true) From aa365db1760a6c2a4be2409f4c869c7a0c15adae Mon Sep 17 00:00:00 2001 From: meglerhagen Date: Sat, 18 Apr 2026 20:58:38 +0200 Subject: [PATCH 3/3] fix(create-helpbase): CI-aware ship-it-now + honor HELPBASE_TOKEN MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two CI-path bugs caught by CodeRabbit on PR #12: 1. `isInteractive` is `process.stdin.isTTY`, which CI jobs can allocate. That meant `--deploy --source skip` in CI with a TTY would hit the interactive N-default confirm instead of the non-interactive refuse. Added `humanInteractive = isInteractive && !process.env.CI` for the ship-it-now decision; left `isInteractive` semantics intact for the earlier project-name / source / login prompts. 2. Auth gate only read ~/.helpbase/auth.json via readHelpbaseAuthToken(), missing the advertised CI path (`HELPBASE_TOKEN` env var). That sent CI jobs with a valid env token through runHelpbaseLogin() (blocks without TTY) or straight to the "Couldn't log you in" bail. Treat the env var as a truthy gate; `helpbase deploy` validates it at the real auth boundary. Also only attempt login when humanInteractive — no point spawning an interactive flow in CI. Live-verified: `CI=true --deploy --source skip` refuses exit 1; CI with no token + bad URL skips login, hits generation-failed refuse, exit 1. Co-Authored-By: Claude Opus 4.7 (1M context) --- packages/create-helpbase/src/index.ts | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/packages/create-helpbase/src/index.ts b/packages/create-helpbase/src/index.ts index 3e0bbf0..1b7e055 100644 --- a/packages/create-helpbase/src/index.ts +++ b/packages/create-helpbase/src/index.ts @@ -316,12 +316,22 @@ async function run(directory: string | undefined, opts: RunOptions) { // 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, + isInteractive: humanInteractive, generationSucceeded, }) } catch (err) { @@ -333,8 +343,15 @@ async function run(directory: string | undefined, opts: RunOptions) { } if (wantsDeploy) { - let token = readHelpbaseAuthToken() - if (!token) { + // `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() }