Repository navigation
feat(cli): rename helpbase context to helpbase ingest (CLI DX v2, PR-A of 2) - #9
Conversation
Pure `git mv` with zero content changes so `git blame` on the new file path keeps following the history of the 700+ lines of pipeline code (citation validator, token budget, dirty-tree check, llms.txt emit, etc.). The next commit turns this `ingest.ts` into the canonical entry point and reintroduces `context.ts` as a thin deprecation shim. Splitting in two commits keeps `git log --follow` working for default blame, not just when the user passes `-C -C -C`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… v2) `context` named a domain, not an action. `ingest` names what the command does: walks your code + markdown, synthesizes cited how-tos, wires up MCP. The old `helpbase context` keeps working as a deprecation shim via `applyIngestOptions` + `runIngestAction` shared from ingest.ts, with a one-line stderr warning suppressed under `--json` / `--quiet`. Slated for removal in v0.7 so CI scripts pinned to the old name keep working through the overlap. Option surface can't drift: a new parity test in ingest.test.ts asserts `ingestCommand.options == contextCommand.options` at load time. Content + infrastructure updates: - packages/cli/src/commands/ingest.ts: canonical implementation (moved from context.ts in the previous commit), exports applyIngestOptions + runIngestAction for the shim - packages/cli/src/commands/context.ts: new ~56-line deprecation shim; calls runIngestAction unchanged - packages/cli/src/lib/help.ts: `ingest` leads Get started + "Most common"; `context` falls into auto-generated "Other" with [deprecated] tag so existing-script users still see the migration path - packages/cli/src/index.ts: normalizes telemetry so postAction for `context` emits `command: "ingest"` + `alias: "context"` — preserves metric continuity across the rename, surfaces alias adoption rate independently. TODO(v0.7) marker on the addCommand and the alias map so the three deletion sites (contextCommand registration, alias map entry, test describe block) stay greppable - packages/cli/src/lib/telemetry.ts: extends TelemetryEvent with optional `alias?: string`; omitted when not set so payload shape stays identical for non-aliased calls - packages/cli/src/commands/context-errors.ts: adds explanatory comment that the E_CONTEXT_* code prefix names the pipeline domain, not the command — stable across the v0.7 removal - README Quick Start, preview help, scaffolder next-steps + error hints, eval runner + workflow, shared/ module docstrings, and the scaffolder templates (which ship to every new project) all updated to lead with `ingest` - docs/cli.md regenerated via `pnpm docs:cli` Test updates: - 4 new tests in ingest.test.ts covering the deprecation shim: help-text banner, stderr warning fires, warning suppressed under --quiet AND --json (two drift guards), --dry-run forwards identically - Parity test asserts ingestCommand.options + _args match contextCommand — catches a future dev adding a flag directly to ingest.ts instead of inside applyIngestOptions - help.test.ts: tightened regex anchor + new test asserting context appears under "Other" (preserves discoverability) - Hermeticity fix: ingest.test.ts + doctor.test.ts now override HOME/USERPROFILE/HELPBASE_TOKEN so tests don't silently consume the developer's real ~/.helpbase/auth.json. Caught via /review: without this, "no auth" assertions passed in CI but flaked on any contributor laptop with a live session (stealth paid-LLM calls on what looked like unit tests) Also fixed (discovered during /review): - generate.ts + generate-from-repo.ts + emit-mcp-json.ts stale internal comments that referenced helpbase context - secrets.ts: user-facing "re-run helpbase context" error string (the secret-scan abort message) now says "re-run helpbase ingest" - Unused imports `ContextCitation`, `type ContextSource` in ingest.ts Tests: apps/web 120/120, create-helpbase 31/31, cli 376 passed (+3 skipped). Typecheck clean across all 8 workspaces. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 17 minutes and 46 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (14)
📝 WalkthroughWalkthroughThis PR renames the CLI command from Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (10)
packages/create-helpbase/src/index.ts (1)
709-759:⚠️ Potential issue | 🟡 MinorQuote
repoPathin copy/paste retry commands.These hints now interpolate local repo paths directly. Paths containing spaces will produce broken retry commands.
🛠️ Proposed fix
+function quoteShellArg(value: string): string { + if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value + return `'${value.replace(/'/g, `'\\''`)}'` +} + function printRepoGenerationFallbackHint(err: unknown, repoPath: string): void { + const quotedRepoPath = quoteShellArg(repoPath) if (err instanceof MissingApiKeyError) { note( `Run ${pc.cyan("helpbase login")} (free, no card) then:\n` + - ` ${pc.cyan(`helpbase ingest ${repoPath}`)}\n\n` + + ` ${pc.cyan(`helpbase ingest ${quotedRepoPath}`)}\n\n` + @@ `${err.message}\n` + `Point at a subdirectory with more focused content, or run:\n` + - ` ${pc.cyan(`helpbase ingest ${repoPath} --max-tokens 200000`)} after scaffold.`, + ` ${pc.cyan(`helpbase ingest ${quotedRepoPath} --max-tokens 200000`)} after scaffold.`, @@ `This is common on cheap models that paraphrase quoted code.\n\n` + `Retry with:\n` + - ` ${pc.cyan(`helpbase ingest ${repoPath} --model anthropic/claude-sonnet-4.6`)}\n` + + ` ${pc.cyan(`helpbase ingest ${quotedRepoPath} --model anthropic/claude-sonnet-4.6`)}\n` + @@ `Gateway error: ${err.message}\n` + - `Retry with ${pc.cyan(`helpbase ingest ${repoPath} --test`)} after scaffold to use a cheap fallback model.`, + `Retry with ${pc.cyan(`helpbase ingest ${quotedRepoPath} --test`)} after scaffold to use a cheap fallback model.`, @@ - `Run ${pc.cyan(`helpbase ingest ${repoPath}`)} later to retry.`, + `Run ${pc.cyan(`helpbase ingest ${quotedRepoPath}`)} later to retry.`,🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/create-helpbase/src/index.ts` around lines 709 - 759, In printRepoGenerationFallbackHint, the unquoted repoPath is interpolated into shell commands which breaks when paths contain spaces or quotes; fix by creating a safely quoted version (e.g. escape internal double-quotes then wrap in double quotes) and use that quotedRepoPath wherever `${repoPath}` appears in the helpbase ingest commands and examples (including the --max-tokens and --model variants) so copy/paste commands remain valid; update references in printRepoGenerationFallbackHint to use the new quotedRepoPath variable instead of raw repoPath.packages/shared/src/context-writer.ts (1)
1-14:⚠️ Potential issue | 🟡 MinorFinish renaming the rest of this comment block.
Line 2 says
helpbase ingest, but Lines 6 and 12-13 still describe this as “context” behavior.📝 Proposed doc fix
- * files. For context, regen must: + * files. For ingest, regen must: @@ - * This module does the inventory + diffing in pure code so the context + * This module does the inventory + diffing in pure code so the ingest * command's action handler reads top-to-bottom.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/shared/src/context-writer.ts` around lines 1 - 14, The top-of-file comment still refers to the old "context" name in several places; update the wording to consistently use "ingest" (e.g., change "helpbase ingest (formerly `context`)" usage examples and replace "context" mentions in lines describing behavior and "context command" to "ingest" or "ingest command") and ensure the reference to planArticleWrites (ai.ts) remains accurate; search for the tokens "context" and "context command" in this comment block and replace them with "ingest" / "ingest command" while keeping the explanations about preserving/deleting generated vs custom files intact.packages/shared/src/context-reader.ts (1)
191-195:⚠️ Potential issue | 🟡 MinorRename the stderr prefix to avoid surfacing the deprecated command.
Oversized-file warnings from
helpbase ingeststill print[helpbase-context], which undercuts the CLI rename in a user-visible path.📝 Proposed fix
- `[helpbase-context] Skipping ${rel} (${rawBuf.byteLength} bytes > ${maxBytes}B cap)\n`, + `[helpbase-ingest] Skipping ${rel} (${rawBuf.byteLength} bytes > ${maxBytes}B cap)\n`,🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/shared/src/context-reader.ts` around lines 191 - 195, The oversized-file warning still uses the old prefix "[helpbase-context]"; update the user-visible prefix to the new CLI name by replacing "[helpbase-context]" with the new prefix (e.g., "[helpbase]") in the placeholder string assigned to placeholder and in the process.stderr.write call inside the file-reading logic (the code around the placeholder variable and the process.stderr.write invocation in context-reader.ts) so the warning reflects the renamed CLI.packages/shared/src/citations.ts (1)
184-189:⚠️ Potential issue | 🟡 MinorUpdate the stale
context.tsreference.This comment still points readers to
context.ts, but the canonical implementation should now beingest.ts.📝 Proposed doc fix
- * to do with a 0-kept article (context.ts drops it entirely and writes the + * to do with a 0-kept article (ingest.ts drops it entirely and writes the🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/shared/src/citations.ts` around lines 184 - 189, The doc comment above the citation validation implementation in packages/shared/src/citations.ts (the block that begins "Validate all citations on an article...") references a stale file name `context.ts`; update that sentence to point to the canonical implementation `ingest.ts` (e.g., replace "context.ts drops it entirely" with "ingest.ts drops it entirely") so the comment accurately references the current implementation.packages/shared/src/ai-text.ts (1)
84-87:⚠️ Potential issue | 🟡 MinorStale comment wording — still references the "CLI
contextcommand".The surrounding comment was left unchanged by the rename pass. Since the consumer is now
ingest.ts(withcontext.tsas a deprecation shim), the wording should follow the same convention used elsewhere in this PR to avoid future grep-drift.-// Kept local to avoid a circular import between shared modules; these live -// in a dedicated `./secrets.ts` module that both `ai-text` (walker) and the -// CLI `context` command import from. +// Kept local to avoid a circular import between shared modules; these live +// in a dedicated `./secrets.ts` module that both `ai-text` (walker) and the +// CLI `ingest` command import from.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/shared/src/ai-text.ts` around lines 84 - 87, The comment above the import of isSecretFile in ai-text.ts is stale — it still mentions the "CLI `context` command"; update the wording to reflect the current consumer by replacing that reference with the new `ingest.ts` consumer and note that `context.ts` is now a deprecation shim so the comment reads consistently with other PR changes and prevents grep-drift (locate the import of isSecretFile and adjust its preceding comment accordingly).packages/cli/eval/questions.ts (1)
50-60:⚠️ Potential issue | 🟠 MajorUpdate expected citation target from
context.tstoingest.ts.The citation-validation and drop-doc logic lives in
packages/cli/src/commands/ingest.ts. Thecontext.tsfile is a deprecation shim that forwards torunIngestActionand is slated for removal in v0.7. A model analyzing the post-rename repo will cite the actual implementation iningest.ts, causing this question's citation validation to fail.Proposed fix
expectedCitations: [ "packages/shared/src/citations.ts", - "packages/cli/src/commands/context.ts", + "packages/cli/src/commands/ingest.ts", ],Alternatively, accept both paths during the deprecation window.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/cli/eval/questions.ts` around lines 50 - 60, Update the question with id "context-citation-validator" to reference the actual implementation file: replace "packages/cli/src/commands/context.ts" in the expectedCitations array with "packages/cli/src/commands/ingest.ts" (or include both paths during the deprecation window) so the model-cited implementation (runIngestAction / ingest.ts) satisfies the citation check; leave the other fields (expectedCitations entry for "packages/shared/src/citations.ts" and the rubric) unchanged.packages/shared/src/ai-context.ts (1)
420-432:⚠️ Potential issue | 🟡 MinorUpdate the adjacent stale
contextwording.Line 421 still says these docs are “what context just produced,” while the nearby command reference now correctly says
helpbase ingest --ask.📝 Proposed wording fix
- * that context just produced. The LLM answers against these. + * that `helpbase ingest` just produced. The LLM answers against these.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/shared/src/ai-context.ts` around lines 420 - 432, The comment text near the docs type is stale — update the phrase "that context just produced" in the block above the docs: Array<{ title: string; path: string; body: string }> (and the surrounding comment that begins "Build a prompt that answers a user question...") to reflect the current UX (e.g., reference that these are the raw MDX files used by the `helpbase ingest --ask` flow or simply remove the outdated phrasing). Edit the comment surrounding the docs definition and the "Build a prompt..." paragraph so it no longer claims the context produced them and instead accurately states that these are the raw MDX docs consumed by the `helpbase ingest --ask` command.README.md (1)
264-272:⚠️ Potential issue | 🟡 MinorAdd
helpbase ingestto the CLI reference.The README now positions
ingestas the canonical entrypoint, but the reference list still omits it. Add it here so the quick-start and command reference stay consistent.📝 Proposed README update
helpbase dev # start the Next.js dev server +helpbase ingest [repo] # synthesize cited repo docs + MCP/llms.txt helpbase generate --url <url> # generate articles from a URL helpbase audit # validate frontmatter, categories, schema helpbase new # create a new article from a template (interactive or --type/--title) helpbase --help # show all commands🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 264 - 272, The CLI reference list is missing the new canonical command; add an entry for "helpbase ingest" to the displayed commands so the quick-start and command reference match the README's guidance. Update the CLI block (near the existing commands like helpbase dev, helpbase generate, helpbase audit, helpbase new) to include a line such as "helpbase ingest # ingest content (canonical entrypoint)" so readers see the ingest command alongside the other top-level commands.packages/cli/src/commands/context-errors.ts (1)
91-95:⚠️ Potential issue | 🟡 MinorRemove the unsupported
--include-extrecovery step.
helpbase ingestdoes not register--include-ext, so this fix path sends users into an “unknown option” error. Either implement the flag or avoid documenting it here.🛠️ Proposed copy-only fix
"Check .helpbase/synthesis-report.json for per-citation drop reasons.", "If snippets were paraphrased, retry with --model anthropic/claude-sonnet-4.6.", - "If cited code files were missing from the reader, use --include-ext to widen it.", + "If cited files were skipped, make sure the relevant docs/code use supported extensions or add a README/MDX bridge file.",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/cli/src/commands/context-errors.ts` around lines 91 - 95, The recovery message array named fix in context-errors.ts includes an unsupported option "--include-ext" that causes an "unknown option" error; remove that entry from the fix array (or replace it with a valid recovery suggestion) so the recovery messages only reference actual helpbase CLI options (do not implement the flag unless you intend to add CLI support for --include-ext). Ensure you update the array where "fix: ["Check .helpbase/synthesis-report.json..." ...]" is defined to exclude the third string referencing --include-ext.packages/cli/test/ingest.test.ts (1)
198-235:⚠️ Potential issue | 🟠 MajorKeep this test hermetic by stopping at the auth boundary.
Setting a fake
AI_GATEWAY_API_KEYstill lets the subprocess attempt a real LLM/Gateway call. You can prove the reuse path skipped walking by asserting it reachesE_AUTH_REQUIREDafter loading existing docs, without any network dependency.🧪 Proposed hermetic test adjustment
- it("--reuse-existing --ask with a populated .helpbase/docs reaches the LLM call (fast path, no walk)", () => { + it("--reuse-existing --ask with a populated .helpbase/docs reaches auth without walking sources", () => { @@ - // No AI key and no source walk — the fast path goes straight to - // runLocalAsk, which needs a key. Observable behavior: we get past - // the walker (no NO_SOURCES, no REPO_PATH error) and fail at the - // LLM call with a gateway/key error, NOT at the pipeline gate. + // No AI key and no source walk — observable behavior: we get past + // the reuse gate and fail at auth, not at source walking. const result = runWithEnv( `ingest ${tmp} --reuse-existing --ask "how do I log in?"`, { - AI_GATEWAY_API_KEY: "vck_this_is_not_a_real_key_abcdefghijklmnop", + AI_GATEWAY_API_KEY: "", + ANTHROPIC_API_KEY: "", + OPENAI_API_KEY: "", + HELPBASE_TOKEN: "", }, ) - // The run should fail at the LLM boundary, not the reuse gate. + expect(result.exitCode).toBe(1) + expect(result.output).toContain("E_AUTH_REQUIRED") expect(result.output).not.toContain("E_CONTEXT_REUSE_EMPTY") expect(result.output).not.toContain("E_CONTEXT_REUSE_WITHOUT_ASK") expect(result.output).not.toContain("E_CONTEXT_NO_SOURCES") - // The Answering line proves we reached runLocalAsk's prompt stage. - expect(result.output).toContain("Answering:")🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/cli/test/ingest.test.ts` around lines 198 - 235, The test currently sets a fake AI_GATEWAY_API_KEY and asserts we reach runLocalAsk ("Answering:"), which allows a real LLM call; instead make the test hermetic by leaving AI_GATEWAY_API_KEY unset (or set to empty) when invoking runWithEnv in the spec "--reuse-existing --ask with a populated .helpbase/docs reaches the LLM call (fast path, no walk)", and replace the assertion that looks for "Answering:" with an assertion that the subprocess output contains the authentication boundary error "E_AUTH_REQUIRED" while still asserting it does not contain the reuse/walker errors; update references in this test that call runWithEnv and the expectations accordingly so the test proves reuse-path reached the auth gate without performing network calls.
🧹 Nitpick comments (1)
docs/cli.md (1)
299-299: Nit: new fenced block lacks a language identifier (MD040).The new
helpbase Othersection's fence, like the pre-existing ones, has no language tag. If you're already touching the generator to fix the anchor casing above, consider emitting```text(or similar) for all sections in the same pass to silence markdownlint repo-wide.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/cli.md` at line 299, The fenced code block added for the "helpbase Other" section is missing a language tag; update that fence from ``` to ```text (or another appropriate language) so markdownlint rule MD040 is satisfied, and update the generator that emits these sections so all similar fences are emitted with a language identifier (i.e., ensure the generator emits ```text for each section, including the "helpbase Other" block).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/cli.md`:
- Line 15: The TOC emits a fragment with an uppercase word ("#helpbase-Other")
that doesn't match GitHub's lowercase heading anchors; update the CLI doc
generator so the slug used for headings and the TOC is normalized to lowercase.
In packages/cli/scripts/generate-cli-docs.mjs (e.g., the slugify / createAnchor
/ generateTOC functions or wherever headings and TOC entries are emitted),
ensure the slugging function lowercases and consistently applies the same slug
when writing both the heading and the corresponding TOC link so the fragment
anchor matches exactly.
In `@packages/cli/src/commands/ingest.ts`:
- Around line 382-389: In the block that checks "if (opts.overwrite &&
planned.preserves.length > 0)" and currently writes to stderr and calls
process.exit(1) when "!opts.yes", replace the stderr.write + process.exit(1)
with throwing a structured HelpbaseError carrying the same user-facing message
(refusing to clobber X custom file(s) and instructing to pass --yes), and
include metadata such as the preserved count (planned.preserves.length) and a
short error code (e.g., "OVERWRITE_CONFLICT"); ensure the HelpbaseError symbol
is imported where this code lives so the command fails through the CLI’s normal
error/telemetry/finalizers instead of exiting the process.
- Around line 205-211: After calling readContextSources(repoRoot) and before any
debug output or sending content to the LLM (including writing to _prompt.txt
when --debug is set), run the secret scanning/redaction routine over the
collected source contents and either redact/omit secrets or abort ingestion if
secrets are found; update the code paths that produce debug artifacts and the
LLM submission path to use the scanned/redacted content instead of raw source
text (ensure the same pre-send scan is applied to all locations where sources
are prepared for output/submission).
- Around line 194-197: The retryCommand passed to resolveAuthOrPromptLogin drops
the repository path, so update the retryCommand to include the repo path (e.g.,
use opts.path if present, otherwise process.cwd()) before the flags; change the
string to something like `helpbase ingest ${opts.path ?? process.cwd()}
--reuse-existing --ask ${JSON.stringify(opts.ask)}` so
resolveAuthOrPromptLogin's retryCommand preserves the original repo
directory/context.
- Around line 216-217: The parsing for opts.maxTokens and opts.charsPerToken is
too permissive; change the logic around the variables maxTokens and
charsPerToken in ingest.ts to explicitly parse and validate numeric input: parse
maxTokens with Number.parseInt(opts.maxTokens, 10) and allow 0 (to disable the
gate) but reject negative values (throw or exit with a clear error), and parse
charsPerToken with Number.parseFloat(opts.charsPerToken) and reject non-positive
or NaN values; ensure any invalid input produces a user-facing error
(process.exit(1) or throw) rather than silently falling back to the default.
---
Outside diff comments:
In `@packages/cli/eval/questions.ts`:
- Around line 50-60: Update the question with id "context-citation-validator" to
reference the actual implementation file: replace
"packages/cli/src/commands/context.ts" in the expectedCitations array with
"packages/cli/src/commands/ingest.ts" (or include both paths during the
deprecation window) so the model-cited implementation (runIngestAction /
ingest.ts) satisfies the citation check; leave the other fields
(expectedCitations entry for "packages/shared/src/citations.ts" and the rubric)
unchanged.
In `@packages/cli/src/commands/context-errors.ts`:
- Around line 91-95: The recovery message array named fix in context-errors.ts
includes an unsupported option "--include-ext" that causes an "unknown option"
error; remove that entry from the fix array (or replace it with a valid recovery
suggestion) so the recovery messages only reference actual helpbase CLI options
(do not implement the flag unless you intend to add CLI support for
--include-ext). Ensure you update the array where "fix: ["Check
.helpbase/synthesis-report.json..." ...]" is defined to exclude the third string
referencing --include-ext.
In `@packages/cli/test/ingest.test.ts`:
- Around line 198-235: The test currently sets a fake AI_GATEWAY_API_KEY and
asserts we reach runLocalAsk ("Answering:"), which allows a real LLM call;
instead make the test hermetic by leaving AI_GATEWAY_API_KEY unset (or set to
empty) when invoking runWithEnv in the spec "--reuse-existing --ask with a
populated .helpbase/docs reaches the LLM call (fast path, no walk)", and replace
the assertion that looks for "Answering:" with an assertion that the subprocess
output contains the authentication boundary error "E_AUTH_REQUIRED" while still
asserting it does not contain the reuse/walker errors; update references in this
test that call runWithEnv and the expectations accordingly so the test proves
reuse-path reached the auth gate without performing network calls.
In `@packages/create-helpbase/src/index.ts`:
- Around line 709-759: In printRepoGenerationFallbackHint, the unquoted repoPath
is interpolated into shell commands which breaks when paths contain spaces or
quotes; fix by creating a safely quoted version (e.g. escape internal
double-quotes then wrap in double quotes) and use that quotedRepoPath wherever
`${repoPath}` appears in the helpbase ingest commands and examples (including
the --max-tokens and --model variants) so copy/paste commands remain valid;
update references in printRepoGenerationFallbackHint to use the new
quotedRepoPath variable instead of raw repoPath.
In `@packages/shared/src/ai-context.ts`:
- Around line 420-432: The comment text near the docs type is stale — update the
phrase "that context just produced" in the block above the docs: Array<{ title:
string; path: string; body: string }> (and the surrounding comment that begins
"Build a prompt that answers a user question...") to reflect the current UX
(e.g., reference that these are the raw MDX files used by the `helpbase ingest
--ask` flow or simply remove the outdated phrasing). Edit the comment
surrounding the docs definition and the "Build a prompt..." paragraph so it no
longer claims the context produced them and instead accurately states that these
are the raw MDX docs consumed by the `helpbase ingest --ask` command.
In `@packages/shared/src/ai-text.ts`:
- Around line 84-87: The comment above the import of isSecretFile in ai-text.ts
is stale — it still mentions the "CLI `context` command"; update the wording to
reflect the current consumer by replacing that reference with the new
`ingest.ts` consumer and note that `context.ts` is now a deprecation shim so the
comment reads consistently with other PR changes and prevents grep-drift (locate
the import of isSecretFile and adjust its preceding comment accordingly).
In `@packages/shared/src/citations.ts`:
- Around line 184-189: The doc comment above the citation validation
implementation in packages/shared/src/citations.ts (the block that begins
"Validate all citations on an article...") references a stale file name
`context.ts`; update that sentence to point to the canonical implementation
`ingest.ts` (e.g., replace "context.ts drops it entirely" with "ingest.ts drops
it entirely") so the comment accurately references the current implementation.
In `@packages/shared/src/context-reader.ts`:
- Around line 191-195: The oversized-file warning still uses the old prefix
"[helpbase-context]"; update the user-visible prefix to the new CLI name by
replacing "[helpbase-context]" with the new prefix (e.g., "[helpbase]") in the
placeholder string assigned to placeholder and in the process.stderr.write call
inside the file-reading logic (the code around the placeholder variable and the
process.stderr.write invocation in context-reader.ts) so the warning reflects
the renamed CLI.
In `@packages/shared/src/context-writer.ts`:
- Around line 1-14: The top-of-file comment still refers to the old "context"
name in several places; update the wording to consistently use "ingest" (e.g.,
change "helpbase ingest (formerly `context`)" usage examples and replace
"context" mentions in lines describing behavior and "context command" to
"ingest" or "ingest command") and ensure the reference to planArticleWrites
(ai.ts) remains accurate; search for the tokens "context" and "context command"
in this comment block and replace them with "ingest" / "ingest command" while
keeping the explanations about preserving/deleting generated vs custom files
intact.
In `@README.md`:
- Around line 264-272: The CLI reference list is missing the new canonical
command; add an entry for "helpbase ingest" to the displayed commands so the
quick-start and command reference match the README's guidance. Update the CLI
block (near the existing commands like helpbase dev, helpbase generate, helpbase
audit, helpbase new) to include a line such as "helpbase ingest #
ingest content (canonical entrypoint)" so readers see the ingest command
alongside the other top-level commands.
---
Nitpick comments:
In `@docs/cli.md`:
- Line 299: The fenced code block added for the "helpbase Other" section is
missing a language tag; update that fence from ``` to ```text (or another
appropriate language) so markdownlint rule MD040 is satisfied, and update the
generator that emits these sections so all similar fences are emitted with a
language identifier (i.e., ensure the generator emits ```text for each section,
including the "helpbase Other" block).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 72ecff97-c1c7-49ea-ae84-b9c61488f0bf
📒 Files selected for processing (31)
.github/workflows/context-eval.ymlCHANGELOG.mdREADME.mddocs/cli.mdpackages/cli/eval/README.mdpackages/cli/eval/grader.tspackages/cli/eval/questions.tspackages/cli/eval/runner.tspackages/cli/src/commands/context-errors.tspackages/cli/src/commands/context.tspackages/cli/src/commands/ingest.tspackages/cli/src/commands/preview.tspackages/cli/src/index.tspackages/cli/src/lib/help.tspackages/cli/src/lib/telemetry.tspackages/cli/test/doctor.test.tspackages/cli/test/help.test.tspackages/cli/test/ingest.test.tspackages/create-helpbase/src/emit-mcp-json.tspackages/create-helpbase/src/generate-from-repo.tspackages/create-helpbase/src/index.tspackages/create-helpbase/templates/lib/schemas.tspackages/shared/src/ai-context.tspackages/shared/src/ai-text.tspackages/shared/src/citations.tspackages/shared/src/context-reader.tspackages/shared/src/context-writer.tspackages/shared/src/llms-txt.tspackages/shared/src/schemas.tspackages/shared/src/secrets.tsregistry/helpbase/lib/schemas.ts
All 5 findings were VALID & ACTIONABLE. Four were pre-existing behaviors
that got carried from context.ts into ingest.ts verbatim; one was a new
regression the rename introduced in the docs generator.
1. docs/cli.md (new regression) — the generator regex in
generate-cli-docs.mjs matched 2-space indent, which picked up the
GROUPED-help category labels ("Get started", "Ship", ...) as if they
were commands. Result: docs/cli.md listed 6 bogus ## headings and
broken #helpbase-Other anchors instead of 20 real commands. Fix:
match 4-space indent so only actual subcommands are extracted.
Side effect: previously docs/cli.md shipped with `helpbase Get`,
`helpbase Ship`, etc. as fake command sections — those now resolve
to the real 20.
2. ingest.ts:194 — --reuse-existing retry hint dropped the repo path.
A user who ran `helpbase ingest /some/repo --reuse-existing --ask
"x"` and hit an auth error saw a retry command without the path,
so re-running would hit the wrong cwd. Include repoPathArg in the
retry command string.
3. ingest.ts:~207 (pre-LLM secret scan) — source content was only
scanned AFTER the LLM synthesized MDX. A secret hardcoded in an
eligible .ts/.py/.go file would leak into _prompt.txt under --debug,
into the LLM request body, and into the synthesis-report.json before
the post-MDX scan fired. New pre-LLM scan loop catches secrets in
source BEFORE any prompt assembly or gateway call. New error code
E_CONTEXT_SECRET_SOURCE (distinct from the MDX-scan E_CONTEXT_SECRET
so users can tell which stage caught it).
4. ingest.ts:~195 (budget validation) — --max-tokens and
--chars-per-token used `Number.parseInt(x) || default` which
silently swallowed NaN, negative, and non-numeric inputs. Worse:
a negative --max-tokens bypassed the `maxTokens > 0` gate in
generateHowtosFromRepo, letting oversized runs hit the LLM
gateway. New parseBudgetInt/parseBudgetFloat helpers validate
positivity explicitly and surface E_CONTEXT_INVALID_BUDGET with
the offending value quoted. --max-tokens 0 is still accepted
(documented behavior to disable the gate); negative values are
rejected.
5. ingest.ts:~382 (throw over exit) — the --overwrite-without-yes
path used stderr.write + process.exit(1), bypassing the CLI's
HelpbaseError formatter (which honors --json/--quiet, emits the
doc URL, and routes through the top-level handler in index.ts).
New error code E_CONTEXT_REFUSE_CLOBBER routes it through the
same channel every other CLI error uses.
Tests: 4 new in ingest.test.ts locking in the new behaviors —
negative --max-tokens, zero --chars-per-token, zero --max-tokens
(gate-disable happy path), and the pre-LLM secret scan abort.
Secret-scan test asserts the output contains the pattern NAME +
file path but NOT the secret bytes themselves (matching the scan
module's zero-leak contract).
Totals: CLI 380 passed +3 skipped (was 376/+3). Typecheck clean
across 8 workspaces. docs/cli.md regenerated — now lists 20 real
commands, not 6 group labels.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Addressed all 5 findings in
Tests: 4 new in
Totals: CLI 380/+3 skipped, web 120/120, scaffolder 31/31. Typecheck clean. Thanks @coderabbitai — 4 of these were pre-existing behaviors carried over from |
|
Tip For best results, initiate chat on the files or code changes.
All 5 findings are cleanly addressed. Thanks for the thorough summary — the "4 of these were pre-existing behaviours surfaced by the rename" note is a useful data point. If you found this review helpful, would you consider giving us a shout-out on X? Thank you for using CodeRabbit! |
`helpbase login` now reserves a `docs-<6hex>.helpbase.dev` subdomain
immediately after successful auth. TTHW for the first-deploy happy
path drops from ~3-4 min (slug prompt + confirmation) to ~90s (login
+ deploy, zero prompts). Users see a concrete URL before they've
written a single article — the magical moment the DX review chased
from /plan-devex-review 2026-04-18.
Scope — schema + 3 endpoints + middleware + landing page + MCP
gate + CLI wiring + cleanup cron. Review trail in memory at
project_cli_dx_v2_decisions.md.
Schema (applied via Supabase MCP, migration name
`slug_reservation_columns_and_first_deploy_timestamp`):
- `public.tenants` gets `deployed_at timestamptz` +
`auto_provisioned_at timestamptz` (both nullable). Existing rows
backfilled with `deployed_at = created_at` (all 3 existing tenants
pre-migration are really deployed; backfill preserves ordering).
- UNIQUE partial index on `owner_id WHERE auto_provisioned_at IS
NOT NULL AND deployed_at IS NULL` — race-safe idempotency.
- Helper index on `owner_id WHERE auto_provisioned_at IS NOT NULL`
— sargable for the reservation lookup path.
- `tenants_public` view now exposes `deployed_at` (still no
`mcp_public_token`). Added via CREATE OR REPLACE VIEW — column
appended at the end, no dependents needed drop/recreate.
- `deploy_tenant` RPC flips `deployed_at` atomically with content
insertion using COALESCE(deployed_at, NOW()) so re-deploys never
overwrite the original reservation→live timestamp. Per-deploy
history continues to live in tenant_deploys.created_at.
Server endpoints:
- `POST /api/v1/tenants/auto-provision` — idempotent mint of a new
reservation. Catches 23505 on the owner UNIQUE partial index to
re-read + return the existing row when a concurrent second call
races. Slug uses 24 bits of entropy (6 hex chars) so first-try
collisions are vanishingly rare; a single retry covers the tail,
after which we 503 with slug_exhausted (signals PRNG degradation).
- `GET /api/v1/tenants/reservation` — read-only counterpart. Returns
the row or 404. Used by login re-hydration, `whoami`, `open`.
- `PATCH /api/v1/tenants/reservation/slug` — pre-deploy rename.
Server gates on `deployed_at IS NULL` and treats the rename as
idempotent when the new slug matches the current one. Post-deploy
rename is out of scope (would need a redirect layer in proxy.ts).
- `GET /api/v1/tenants/mine` — filter `.not("deployed_at", "is",
null)` so reservations never pollute the deploy tenant picker.
Public surfaces:
- `apps/web/proxy.ts` — reserved tenants (deployed_at IS NULL)
route `/` to the new `/t/_reserved/[slug]` branded landing,
everything else to `/t/_not-found`. Every reserved-tenant
response carries `X-Robots-Tag: noindex, nofollow` so empty
`docs-*.helpbase.dev` placeholders don't get indexed.
- `apps/web/app/(tenant)/t/_reserved/[slug]/page.tsx` — new
branded "This help center isn't live yet" page. No per-slug
Supabase lookup (middleware already verified); no owner email
leakage; metadata.robots explicitly noindex/nofollow.
- `apps/web/app/(tenant)/t/[tenant]/mcp/route.ts` — returns 403
`tenant_not_deployed` on reserved tenants so MCP clients
polling a reservation URL during a user's first-deploy window
get a clean signal instead of empty search results.
CLI:
- New `packages/cli/src/lib/reservation-cache.ts` — local cache
at `~/.helpbase/reservation.json` (mode 0o600, separate from
auth.json). Avoids extending the session contract + provides a
cheap fast-path for whoami/open.
- New `packages/cli/src/lib/reservation.ts` — `ensureReservation`
(auto-provision with graceful fallback on 503) + `loadReservation`
(cache-first with server fallback).
- `packages/cli/src/commands/login.ts` — calls `ensureReservation`
after device/magic-link flow, prints the reserved URL in the
outro. Soft-fails: if the server is unreachable, login still
succeeds and `whoami`/`deploy` lazy-provision later.
- `packages/cli/src/commands/whoami.ts` — shows
`reserved: docs-abc.helpbase.dev` when user has no deployed
tenants but an active reservation.
- `packages/cli/src/commands/open.ts` — falls back to the
reservation URL when no deployed tenant exists.
- `packages/cli/src/commands/deploy.ts` — reservation-first
branch: users with no deployed tenants + no explicit --slug
deploy to their reservation with zero prompts. Clears the
reservation cache post-successful deploy so the tenant shows
up as "live" in whoami afterwards.
- `packages/cli/src/commands/rename.ts` — new command. PATCHes
the reservation slug, updates the local cache, surfaces
E_RESERVATION_MISSING / E_RESERVATION_LOCKED / E_SLUG_TAKEN
with full fix copy.
- New error codes: E_RESERVATION_MISSING, E_RESERVATION_LOCKED,
E_RESERVATION_PROVISION_FAILED.
Infrastructure:
- `apps/web/vercel.json` — new. Daily 03:00 UTC cron pointed at
`/api/cron/cleanup-reservations`.
- `apps/web/app/api/cron/cleanup-reservations/route.ts` —
Deletes reservations older than 30 days that have no
tenant_deploys history. Belt-and-suspenders: if deployed_at
somehow failed to update, the deploy history still protects
the row. Supports `?dry=true` + bearer-auth via CRON_SECRET.
Also fixed (cherry-picked from in-flight PR #9):
- Docs generator regex: match 4-space indent (command names) not
2-space (GROUP labels). Was producing bogus `## helpbase Get`
sections in docs/cli.md. Regenerated — now 20 real commands.
Tests:
- `packages/cli/test/reservation-cache.test.ts` — 7 tests covering
round-trip, corrupt JSON, missing fields, clear, override, 0o600.
- `apps/web/test/reservation-cron.test.ts` — 7 tests for the TTL
math + shadow filter predicate.
- Live DB smoke via Supabase MCP verified the UNIQUE partial index
blocks concurrent reservation INSERTs and releases after
deployed_at flips to NOT NULL.
Totals: apps/web 127/127, create-helpbase 31/31, CLI 376/+3
skipped, typecheck clean across 8 workspaces.
Known follow-ups:
- hermeticity: two pre-existing CLI tests (context.test.ts,
doctor.test.ts) still leak laptop auth state. Fixed in PR #9;
PR-B branched before that landed. Clean on CI (no auth), only
fails on contributor laptops with a live session. Will resolve
on rebase when PR #9 merges.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
All outside-diff-range items from CodeRabbit's first review. The 5 inline ones landed in dd98541; these 10 are stale comments + one live test-hermeticity hazard + the README CLI reference miss. 1. README.md:264-272 — CLI reference list now includes `helpbase ingest` alongside `helpbase dev` / `helpbase new` / etc. so the quick-start and command reference stay consistent. 2. packages/create-helpbase/src/index.ts:709-759 — retry-command hints in printRepoGenerationFallbackHint now shell-quote the repoPath argument. A user scaffolding from a path with spaces (`/Users/foo/my docs`) used to see `helpbase ingest /Users/foo/my docs` in the copy/paste hint, which breaks on the space. New `quoteShellArg` helper returns the value unchanged for safe chars, otherwise wraps in single quotes and escapes embedded quotes via the POSIX `'\''` idiom. 3. packages/shared/src/context-reader.ts:194 — oversized-file warning prefix updated from `[helpbase-context]` to `[helpbase-ingest]`. This is the one outside-diff item that was actually user-visible (prints to stderr on every run that skips a large file). 4. packages/cli/test/ingest.test.ts:280-320 — previously asserted "Answering:" with a fake `vck_...` AI_GATEWAY_API_KEY as proof the reuse-path reached runLocalAsk. Problem: a contributor with a real ANTHROPIC_API_KEY / OPENAI_API_KEY in their shell would burn real tokens on every test run (fake gateway key doesn't suppress the others). Replaced with a hermetic assertion: E_AUTH_REQUIRED after the reuse gate + source-walker gate both pass. Strictly stronger signal about where execution reached, and never touches the network. 5. packages/cli/eval/questions.ts:54-56 — expectedCitations for the `context-citation-validator` question now accepts ingest.ts OR context.ts. Before: eval would fail because Sonnet cites the canonical ingest.ts, not the deprecation shim. Both paths accepted during the v0.7 deprecation window; TODO tag marks the context.ts entry for removal when the shim is deleted. 6. packages/cli/src/commands/context-errors.ts:94 — removed the unsupported `--include-ext` fix suggestion from E_CONTEXT_NO_VALID_CITATIONS. That flag isn't registered on the command, so following the suggestion would error with "unknown option". Replaced with an actionable pointer to the supported extensions list + README-bridge workaround. 7-11. Stale comments in packages/shared/src/{ai-context,ai-text, citations,context-writer}.ts that referenced "context" in prose. All updated to reference `helpbase ingest` consistently, with "(formerly context)" footnotes where the historical context is still useful for a reader grepping pre-rename docs. Also fixed (beta-nitpick, not blocking): - packages/cli/scripts/generate-cli-docs.mjs — fenced `## helpbase <cmd>` output blocks now emit ```text instead of bare ```. Silences markdownlint MD040 on every section at once. Docs regenerated. Tests: 380 passed / +3 skipped (added no new tests — just updated the one hermetic assertion). Typecheck clean. Docs:cli:check passes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Follow-up commit
Totals: 380 passed / +3 skipped. Typecheck clean. docs:cli:check passes. Thanks @coderabbitai — the hermeticity catch on the reuse test was particularly valuable; that was a latent stealth-paid-LLM-call hazard on every contributor laptop. |
|
Tip For best results, initiate chat on the files or code changes.
All 10 findings are cleanly resolved. Thanks for the thorough commit summary — the per-finding table format makes it easy to verify coverage at a glance. |
`helpbase login` now reserves a `docs-<6hex>.helpbase.dev` subdomain
immediately after successful auth. TTHW for the first-deploy happy
path drops from ~3-4 min (slug prompt + confirmation) to ~90s (login
+ deploy, zero prompts). Users see a concrete URL before they've
written a single article — the magical moment the DX review chased
from /plan-devex-review 2026-04-18.
Scope — schema + 3 endpoints + middleware + landing page + MCP
gate + CLI wiring + cleanup cron. Review trail in memory at
project_cli_dx_v2_decisions.md.
Schema (applied via Supabase MCP, migration name
`slug_reservation_columns_and_first_deploy_timestamp`):
- `public.tenants` gets `deployed_at timestamptz` +
`auto_provisioned_at timestamptz` (both nullable). Existing rows
backfilled with `deployed_at = created_at` (all 3 existing tenants
pre-migration are really deployed; backfill preserves ordering).
- UNIQUE partial index on `owner_id WHERE auto_provisioned_at IS
NOT NULL AND deployed_at IS NULL` — race-safe idempotency.
- Helper index on `owner_id WHERE auto_provisioned_at IS NOT NULL`
— sargable for the reservation lookup path.
- `tenants_public` view now exposes `deployed_at` (still no
`mcp_public_token`). Added via CREATE OR REPLACE VIEW — column
appended at the end, no dependents needed drop/recreate.
- `deploy_tenant` RPC flips `deployed_at` atomically with content
insertion using COALESCE(deployed_at, NOW()) so re-deploys never
overwrite the original reservation→live timestamp. Per-deploy
history continues to live in tenant_deploys.created_at.
Server endpoints:
- `POST /api/v1/tenants/auto-provision` — idempotent mint of a new
reservation. Catches 23505 on the owner UNIQUE partial index to
re-read + return the existing row when a concurrent second call
races. Slug uses 24 bits of entropy (6 hex chars) so first-try
collisions are vanishingly rare; a single retry covers the tail,
after which we 503 with slug_exhausted (signals PRNG degradation).
- `GET /api/v1/tenants/reservation` — read-only counterpart. Returns
the row or 404. Used by login re-hydration, `whoami`, `open`.
- `PATCH /api/v1/tenants/reservation/slug` — pre-deploy rename.
Server gates on `deployed_at IS NULL` and treats the rename as
idempotent when the new slug matches the current one. Post-deploy
rename is out of scope (would need a redirect layer in proxy.ts).
- `GET /api/v1/tenants/mine` — filter `.not("deployed_at", "is",
null)` so reservations never pollute the deploy tenant picker.
Public surfaces:
- `apps/web/proxy.ts` — reserved tenants (deployed_at IS NULL)
route `/` to the new `/t/_reserved/[slug]` branded landing,
everything else to `/t/_not-found`. Every reserved-tenant
response carries `X-Robots-Tag: noindex, nofollow` so empty
`docs-*.helpbase.dev` placeholders don't get indexed.
- `apps/web/app/(tenant)/t/_reserved/[slug]/page.tsx` — new
branded "This help center isn't live yet" page. No per-slug
Supabase lookup (middleware already verified); no owner email
leakage; metadata.robots explicitly noindex/nofollow.
- `apps/web/app/(tenant)/t/[tenant]/mcp/route.ts` — returns 403
`tenant_not_deployed` on reserved tenants so MCP clients
polling a reservation URL during a user's first-deploy window
get a clean signal instead of empty search results.
CLI:
- New `packages/cli/src/lib/reservation-cache.ts` — local cache
at `~/.helpbase/reservation.json` (mode 0o600, separate from
auth.json). Avoids extending the session contract + provides a
cheap fast-path for whoami/open.
- New `packages/cli/src/lib/reservation.ts` — `ensureReservation`
(auto-provision with graceful fallback on 503) + `loadReservation`
(cache-first with server fallback).
- `packages/cli/src/commands/login.ts` — calls `ensureReservation`
after device/magic-link flow, prints the reserved URL in the
outro. Soft-fails: if the server is unreachable, login still
succeeds and `whoami`/`deploy` lazy-provision later.
- `packages/cli/src/commands/whoami.ts` — shows
`reserved: docs-abc.helpbase.dev` when user has no deployed
tenants but an active reservation.
- `packages/cli/src/commands/open.ts` — falls back to the
reservation URL when no deployed tenant exists.
- `packages/cli/src/commands/deploy.ts` — reservation-first
branch: users with no deployed tenants + no explicit --slug
deploy to their reservation with zero prompts. Clears the
reservation cache post-successful deploy so the tenant shows
up as "live" in whoami afterwards.
- `packages/cli/src/commands/rename.ts` — new command. PATCHes
the reservation slug, updates the local cache, surfaces
E_RESERVATION_MISSING / E_RESERVATION_LOCKED / E_SLUG_TAKEN
with full fix copy.
- New error codes: E_RESERVATION_MISSING, E_RESERVATION_LOCKED,
E_RESERVATION_PROVISION_FAILED.
Infrastructure:
- `apps/web/vercel.json` — new. Daily 03:00 UTC cron pointed at
`/api/cron/cleanup-reservations`.
- `apps/web/app/api/cron/cleanup-reservations/route.ts` —
Deletes reservations older than 30 days that have no
tenant_deploys history. Belt-and-suspenders: if deployed_at
somehow failed to update, the deploy history still protects
the row. Supports `?dry=true` + bearer-auth via CRON_SECRET.
Also fixed (cherry-picked from in-flight PR #9):
- Docs generator regex: match 4-space indent (command names) not
2-space (GROUP labels). Was producing bogus `## helpbase Get`
sections in docs/cli.md. Regenerated — now 20 real commands.
Tests:
- `packages/cli/test/reservation-cache.test.ts` — 7 tests covering
round-trip, corrupt JSON, missing fields, clear, override, 0o600.
- `apps/web/test/reservation-cron.test.ts` — 7 tests for the TTL
math + shadow filter predicate.
- Live DB smoke via Supabase MCP verified the UNIQUE partial index
blocks concurrent reservation INSERTs and releases after
deployed_at flips to NOT NULL.
Totals: apps/web 127/127, create-helpbase 31/31, CLI 376/+3
skipped, typecheck clean across 8 workspaces.
Known follow-ups:
- hermeticity: two pre-existing CLI tests (context.test.ts,
doctor.test.ts) still leak laptop auth state. Fixed in PR #9;
PR-B branched before that landed. Clean on CI (no auth), only
fails on contributor laptops with a live session. Will resolve
on rebase when PR #9 merges.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: slug reservation flow (PR-B of CLI DX v2)
`helpbase login` now reserves a `docs-<6hex>.helpbase.dev` subdomain
immediately after successful auth. TTHW for the first-deploy happy
path drops from ~3-4 min (slug prompt + confirmation) to ~90s (login
+ deploy, zero prompts). Users see a concrete URL before they've
written a single article — the magical moment the DX review chased
from /plan-devex-review 2026-04-18.
Scope — schema + 3 endpoints + middleware + landing page + MCP
gate + CLI wiring + cleanup cron. Review trail in memory at
project_cli_dx_v2_decisions.md.
Schema (applied via Supabase MCP, migration name
`slug_reservation_columns_and_first_deploy_timestamp`):
- `public.tenants` gets `deployed_at timestamptz` +
`auto_provisioned_at timestamptz` (both nullable). Existing rows
backfilled with `deployed_at = created_at` (all 3 existing tenants
pre-migration are really deployed; backfill preserves ordering).
- UNIQUE partial index on `owner_id WHERE auto_provisioned_at IS
NOT NULL AND deployed_at IS NULL` — race-safe idempotency.
- Helper index on `owner_id WHERE auto_provisioned_at IS NOT NULL`
— sargable for the reservation lookup path.
- `tenants_public` view now exposes `deployed_at` (still no
`mcp_public_token`). Added via CREATE OR REPLACE VIEW — column
appended at the end, no dependents needed drop/recreate.
- `deploy_tenant` RPC flips `deployed_at` atomically with content
insertion using COALESCE(deployed_at, NOW()) so re-deploys never
overwrite the original reservation→live timestamp. Per-deploy
history continues to live in tenant_deploys.created_at.
Server endpoints:
- `POST /api/v1/tenants/auto-provision` — idempotent mint of a new
reservation. Catches 23505 on the owner UNIQUE partial index to
re-read + return the existing row when a concurrent second call
races. Slug uses 24 bits of entropy (6 hex chars) so first-try
collisions are vanishingly rare; a single retry covers the tail,
after which we 503 with slug_exhausted (signals PRNG degradation).
- `GET /api/v1/tenants/reservation` — read-only counterpart. Returns
the row or 404. Used by login re-hydration, `whoami`, `open`.
- `PATCH /api/v1/tenants/reservation/slug` — pre-deploy rename.
Server gates on `deployed_at IS NULL` and treats the rename as
idempotent when the new slug matches the current one. Post-deploy
rename is out of scope (would need a redirect layer in proxy.ts).
- `GET /api/v1/tenants/mine` — filter `.not("deployed_at", "is",
null)` so reservations never pollute the deploy tenant picker.
Public surfaces:
- `apps/web/proxy.ts` — reserved tenants (deployed_at IS NULL)
route `/` to the new `/t/_reserved/[slug]` branded landing,
everything else to `/t/_not-found`. Every reserved-tenant
response carries `X-Robots-Tag: noindex, nofollow` so empty
`docs-*.helpbase.dev` placeholders don't get indexed.
- `apps/web/app/(tenant)/t/_reserved/[slug]/page.tsx` — new
branded "This help center isn't live yet" page. No per-slug
Supabase lookup (middleware already verified); no owner email
leakage; metadata.robots explicitly noindex/nofollow.
- `apps/web/app/(tenant)/t/[tenant]/mcp/route.ts` — returns 403
`tenant_not_deployed` on reserved tenants so MCP clients
polling a reservation URL during a user's first-deploy window
get a clean signal instead of empty search results.
CLI:
- New `packages/cli/src/lib/reservation-cache.ts` — local cache
at `~/.helpbase/reservation.json` (mode 0o600, separate from
auth.json). Avoids extending the session contract + provides a
cheap fast-path for whoami/open.
- New `packages/cli/src/lib/reservation.ts` — `ensureReservation`
(auto-provision with graceful fallback on 503) + `loadReservation`
(cache-first with server fallback).
- `packages/cli/src/commands/login.ts` — calls `ensureReservation`
after device/magic-link flow, prints the reserved URL in the
outro. Soft-fails: if the server is unreachable, login still
succeeds and `whoami`/`deploy` lazy-provision later.
- `packages/cli/src/commands/whoami.ts` — shows
`reserved: docs-abc.helpbase.dev` when user has no deployed
tenants but an active reservation.
- `packages/cli/src/commands/open.ts` — falls back to the
reservation URL when no deployed tenant exists.
- `packages/cli/src/commands/deploy.ts` — reservation-first
branch: users with no deployed tenants + no explicit --slug
deploy to their reservation with zero prompts. Clears the
reservation cache post-successful deploy so the tenant shows
up as "live" in whoami afterwards.
- `packages/cli/src/commands/rename.ts` — new command. PATCHes
the reservation slug, updates the local cache, surfaces
E_RESERVATION_MISSING / E_RESERVATION_LOCKED / E_SLUG_TAKEN
with full fix copy.
- New error codes: E_RESERVATION_MISSING, E_RESERVATION_LOCKED,
E_RESERVATION_PROVISION_FAILED.
Infrastructure:
- `apps/web/vercel.json` — new. Daily 03:00 UTC cron pointed at
`/api/cron/cleanup-reservations`.
- `apps/web/app/api/cron/cleanup-reservations/route.ts` —
Deletes reservations older than 30 days that have no
tenant_deploys history. Belt-and-suspenders: if deployed_at
somehow failed to update, the deploy history still protects
the row. Supports `?dry=true` + bearer-auth via CRON_SECRET.
Also fixed (cherry-picked from in-flight PR #9):
- Docs generator regex: match 4-space indent (command names) not
2-space (GROUP labels). Was producing bogus `## helpbase Get`
sections in docs/cli.md. Regenerated — now 20 real commands.
Tests:
- `packages/cli/test/reservation-cache.test.ts` — 7 tests covering
round-trip, corrupt JSON, missing fields, clear, override, 0o600.
- `apps/web/test/reservation-cron.test.ts` — 7 tests for the TTL
math + shadow filter predicate.
- Live DB smoke via Supabase MCP verified the UNIQUE partial index
blocks concurrent reservation INSERTs and releases after
deployed_at flips to NOT NULL.
Totals: apps/web 127/127, create-helpbase 31/31, CLI 376/+3
skipped, typecheck clean across 8 workspaces.
Known follow-ups:
- hermeticity: two pre-existing CLI tests (context.test.ts,
doctor.test.ts) still leak laptop auth state. Fixed in PR #9;
PR-B branched before that landed. Clean on CI (no auth), only
fails on contributor laptops with a live session. Will resolve
on rebase when PR #9 merges.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(pr-b): address /review adversarial findings (codex + claude)
Seven fixes from the pre-landing /review pass. Two were genuine CRITICALs
caught only by codex; the rest are HIGH+ severity issues both reviewers
surfaced. Live-DB smoke verified the orphan-prevention refactor.
## Critical (P0)
1. Vercel Cron method mismatch. The cleanup route only exported `POST`,
but Vercel Cron invokes paths with `GET`. In production the job
would have silently 405'd every night and abandoned reservations
would have accumulated forever. `route.ts` now exports both `GET`
(primary, what Vercel Cron actually sends) and `POST` (alias, for
runbook curls that default to -X POST). Both delegate to the same
`handle()` body.
2. Cron DELETE TOCTOU race → could destroy a tenant that just went
live. The old flow was: SELECT candidates → shadow-check
tenant_deploys → DELETE by ID. If a user deployed their reservation
AFTER the candidate select but BEFORE the delete, the delete had no
WHERE-clause guards and would happily wipe the live row. Fix: repeat
every predicate in the DELETE (`auto_provisioned_at IS NOT NULL`
AND `deployed_at IS NULL` AND `auto_provisioned_at < cutoff`)
so Postgres evaluates them at DELETE time, not the earlier SELECT.
Also returns `.select("id, slug")` on the delete so we can log
which rows raced and were skipped.
## High (P1)
3. Slug black hole on `deploy --slug foo` content failure. If content
validation failed AFTER `apiCreateTenant` succeeded, the tenant
row sat forever: hidden from `/mine` (filters deployed_at), invisible
to `/reservation` (filters auto_provisioned_at), untouched by
cleanup cron, slug permanently burned. User-decided fix: move
content validation to BEFORE tenant resolution so broken content
can never leave a server-side side effect. Refactor in deploy.ts
lifts the frontmatter-parse block to step 2.5 (between auth and
resolve). Live-DB smoke verified: empty content exits with "No
articles found" and zero tenant rows are created. Pre-refactor
the same flow would have INSERTed an orphan.
4. Lazy-provision fallback wasn't actually wired. The CHANGELOG +
reservation.ts docstrings both claimed `whoami` and `deploy` would
call `ensureReservation` as a fallback for users who Ctrl-C'd
login mid-auto-provision or logged in before reservations existed.
They only called `loadReservation` — no retry. Now both paths call
`ensureReservation` when `loadReservation` returns null.
5. `apiDeployTenant` response ignored. The CLI printed `tenantSlug`
captured from the reservation cache BEFORE the RPC, not the slug
the server echoed BACK from the RPC. A concurrent `helpbase rename`
in another terminal would drift the slug; the CLI would deploy
correctly (tenantId is stable) but print the wrong live URL in
the outro. Now uses `deployResult.slug || tenantSlug` for both
the summary and the MCP config snippet.
6. `loadReservation` leaked cross-account cache on network errors.
The cache-first path correctly checked `cached.userId === session.userId`,
but the remote-lookup-failed fallback returned `readCachedReservation()`
unconditionally. A shared-laptop user B who logged in over user A's
stale cache + hit a transient blip on first whoami would see A's
reservation (including MCP token) leak into their UI. Fallback now
gates on userId match.
7. `/t/_not-found` returned HTTP 200. The rewrite target rendered a
"Help center not found" page at status 200, which meant crawlers +
MCP clients + monitoring tools hitting unknown-or-reserved subdomain
paths couldn't distinguish "page doesn't exist" from "page exists and
claims not to." Now the page calls `notFound()` for a true 404.
## Medium
8. Proxy short-circuited `/mcp` on reserved subdomains before the MCP
handler's own 403 `tenant_not_deployed` response could fire. That
meant MCP clients polling a reservation URL during first-deploy
got an HTML 404 instead of structured JSON. Proxy now passes
`/mcp` + `/mcp/*` through to the tenant route even when
`deployed_at IS NULL`, keeps X-Robots-Tag for the whole set.
9. Cron batch-safety: added `.limit(500)` on the candidate SELECT to
cap memory + URL-length risk on the follow-up .in() filters. 30-day
TTL means accumulated backlog drains over multiple runs.
10. Cron dry-run flag now accepts `true`/`1`/`yes` case-insensitively
so `?dry=1` in a stressed-operator runbook doesn't accidentally
delete.
11. `rename` error translation gap: server returned `slug_invalid` +
`slug_required` 400s that fell through to raw `cancel(msg)` output
without structured fix copy. Now surfaces E_SLUG_RESERVED /
E_MISSING_FLAG with examples.
12. Auto-provision 23505 discrimination was fragile: substring-matched
on the partial-index name from the error message. Simplified to:
on ANY 23505, re-read the caller's reservation first; if found
return it (concurrent race won), else retry with a fresh slug
(slug UNIQUE collision). Two round-trips per collision instead
of one; collisions are vanishingly rare anyway.
## Review trail
- Codex adversarial (read-only): 7 findings, 2 CRITICAL. Findings 1,
2, 3, 4, 5, 6, 7, 8, 9 above are codex originals.
- Claude adversarial subagent: 22 findings, overlap on 3-5 + 8-9.
Claude caught the cache-user-id fallback + rate-limiting gaps.
- User judgment on the slug-black-hole fix shape: picked
"move validation before create" (correctness first) over
rollback-on-failure (simpler but leaky on network-during-rollback).
Totals: apps/web 127/127, create-helpbase 31/31, CLI 387/+3 skipped.
Typecheck clean across 8 workspaces. Live Supabase smoke confirmed
orphan-prevention: empty content + `deploy --slug foo` leaves zero
rows.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(pr-b): address CodeRabbit findings on PR #10
- MCP route: authenticate before checking deployed_at so unauth'd callers
can't distinguish reserved tenants from unknown slugs via the 403 shape
- whoami: gate ensureReservation fallback on tenantLookupSucceeded so a
/mine network blip doesn't mint an unwanted reservation for an account
that may already own deployed tenants
- whoami: render reservation host from reservation.liveUrl (server source
of truth) instead of hard-coding `${slug}.helpbase.dev`
- rename: force-refresh loadReservation before the same-slug short-circuit
so a stale cache can't lie to the user ("nothing to rename") when the
server knows a different slug
- rename: slug_invalid now maps to E_SLUG_INVALID (was E_SLUG_RESERVED)
- deploy: force-refresh reservation on the write path (cache-first is
fine for whoami/open; deploy pays the one round-trip)
- deploy: tighten content validation — report _category.json schema
failures and reject empty article bodies so orphan tenants can't be
created from malformed content
- _reserved landing: render host from NEXT_PUBLIC_ROOT_DOMAIN instead
of hard-coded "helpbase.dev" so staging/preview display correctly
- CHANGELOG: consolidate duplicate ### Changed sections under Unreleased
- reservation-cleanup: extract TTL constant + filterDeletable to
lib/reservation-cleanup.ts; route handler and unit tests now import
the same functions (no more shadow copy in the test file)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Summary
contextnamed a domain, not an action.ingestnames what the command actually does: walks your code + markdown, synthesizes cited how-tos, wires up MCP. The oldhelpbase contextkeeps working as a deprecation shim viaapplyIngestOptions+runIngestActionshared fromingest.ts, with a one-line stderr warning suppressed under--json/--quiet. Slated for removal in v0.7 so CI scripts pinned to the old name keep working through the overlap.This is PR-A of 2 for the CLI DX v2 plan:
docs-<6hex>.helpbase.devat login time, schema migration, middleware hardening, cleanup cronPlan context:
/plan-devex-review→/plan-eng-review→ codex outside voice →/review.Decisions locked in
project_cli_dx_v2_decisions.mdmemory.What changed
CLI surface:
helpbase ingest [repo]— takes over whatcontextdid.helpbase contextis now a deprecation shim mirroring the full option surface viaapplyIngestOptions, printing a one-line stderr warning (suppressed under--json/--quiet), forwarding torunIngestActionunchanged.ingestleads--helpGet started + "Most common";contextfalls into auto-generated "Other" with[deprecated]tag so existing-script users still see the migration path.helpbase context, telemetry now emitscommand: "ingest"+ optionalalias: "context"so dashboards keep metric continuity across the rename while still surfacing alias-adoption rate.Tests (new):
ingestCommand.options+_argsmatchcontextCommand. Catches a future dev adding a flag directly toingest.tsinstead of insideapplyIngestOptions.ingest.test.ts): help banner flags deprecation, stderr warning fires, suppressed under--quiet, suppressed under--json,--dry-runforwards identically.contextappears in the auto group with[deprecated]so stale-script users discover the migration path.ingest.test.ts+doctor.test.ts— tests now overrideHOME+USERPROFILE+HELPBASE_TOKENso they don't silently consume the developer's real~/.helpbase/auth.json(caught via/review: without it, "no auth" assertions passed in CI but flaked on any contributor laptop with a live session).Docs + propagation:
ingest.docs/cli.mdregenerated viapnpm docs:cli.E_CONTEXT_*error-code prefix kept intentionally — names the pipeline domain, not the command. Explanatory block comment added incontext-errors.ts.TODO(v0.7)deletion markers at the 3 shim sites (index.ts addCommand, ingest.test.ts describe block, telemetry alias map) so the rollout stays greppable.Commits
Two commits to preserve
git blame:refactor(cli): move context.ts to ingest.ts (pure rename)— zero-contentgit mvsogit log --follow ingest.tstraces through the rename.feat(cli): rename helpbase context to helpbase ingest— the content overlay.Test plan
pnpm -r test— 376/379 CLI + 120/120 web + 31/31 scaffolder green locallypnpm -r typecheck— clean across 8 workspacespnpm --filter helpbase docs:cli:check— docs/cli.md up to date/tmpdirectory:node packages/cli/dist/index.js ingest --helpshows full option surfacenode packages/cli/dist/index.js context --helpshows[deprecated]banner + same optionsnode packages/cli/dist/index.js context /tmp/does-not-existprints stderr deprecation warning +E_CONTEXT_REPO_PATHnode packages/cli/dist/index.js context --quiet /tmp/does-not-existprints no deprecation warninggit blame packages/cli/src/commands/ingest.tsattributes line 150+ to the originalfeat(context)commit (not the rename)Review trail
/plan-devex-review2026-04-18 — command rename + reservation plan/plan-eng-review2026-04-18 — architecture review + codex outside voice/review2026-04-18 — pre-landing: 15 specialist findings, all addressed🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
helpbase contexttohelpbase ingestas the primary tool for synthesizing documentation from code repositorieshelpbase contextremains available as a deprecated alias with backward compatibility and deprecation warningDocumentation
helpbase ingestcommandChores