Skip to content

feat(cli): rename helpbase context to helpbase ingest (CLI DX v2, PR-A of 2) - #9

Merged
Codehagen merged 4 commits into
mainfrom
cli-dx-ingest-rename
Apr 18, 2026
Merged

Codehagen merged 4 commits into
mainfrom
cli-dx-ingest-rename

Conversation

@Codehagen

@Codehagen Codehagen commented Apr 18, 2026 •

Copy link
Copy Markdown
Owner

Summary

context named a domain, not an action. ingest names what the command actually 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.

This is PR-A of 2 for the CLI DX v2 plan:

  • PR-A (this one) — command rename + deprecation shim (~low risk, ships first)
  • PR-B (next) — login auto-provisions docs-<6hex>.helpbase.dev at login time, schema migration, middleware hardening, cleanup cron

Plan context: /plan-devex-review → /plan-eng-review → codex outside voice → /review.
Decisions locked in project_cli_dx_v2_decisions.md memory.

What changed

CLI surface:

  • New canonical command helpbase ingest [repo] — takes over what context did.
  • helpbase context is now a deprecation shim mirroring the full option surface via applyIngestOptions, printing a one-line stderr warning (suppressed under --json / --quiet), forwarding to runIngestAction unchanged.
  • ingest leads --help Get started + "Most common"; context falls into auto-generated "Other" with [deprecated] tag so existing-script users still see the migration path.
  • Telemetry normalized: when the user invokes helpbase context, telemetry now emits command: "ingest" + optional alias: "context" so dashboards keep metric continuity across the rename while still surfacing alias-adoption rate.

Tests (new):

  • Parity test — introspects both Command instances and asserts ingestCommand.options + _args match contextCommand. Catches a future dev adding a flag directly to ingest.ts instead of inside applyIngestOptions.
  • Deprecation shim tests (4 new in ingest.test.ts): help banner flags deprecation, stderr warning fires, suppressed under --quiet, suppressed under --json, --dry-run forwards identically.
  • "Other" group visibility test — context appears in the auto group with [deprecated] so stale-script users discover the migration path.
  • Hermeticity fix in ingest.test.ts + doctor.test.ts — tests now override HOME + USERPROFILE + HELPBASE_TOKEN so 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:

  • 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.
  • E_CONTEXT_* error-code prefix kept intentionally — names the pipeline domain, not the command. Explanatory block comment added in context-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:

  1. refactor(cli): move context.ts to ingest.ts (pure rename) — zero-content git mv so git log --follow ingest.ts traces through the rename.
  2. 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 locally
  • pnpm -r typecheck — clean across 8 workspaces
  • pnpm --filter helpbase docs:cli:check — docs/cli.md up to date
  • Smoke test from a clean /tmp directory:
    • node packages/cli/dist/index.js ingest --help shows full option surface
    • node packages/cli/dist/index.js context --help shows [deprecated] banner + same options
    • node packages/cli/dist/index.js context /tmp/does-not-exist prints stderr deprecation warning + E_CONTEXT_REPO_PATH
    • node packages/cli/dist/index.js context --quiet /tmp/does-not-exist prints no deprecation warning
  • git blame packages/cli/src/commands/ingest.ts attributes line 150+ to the original feat(context) commit (not the rename)
  • CodeRabbit PR review passes

Review trail

  • /plan-devex-review 2026-04-18 — command rename + reservation plan
  • /plan-eng-review 2026-04-18 — architecture review + codex outside voice
  • /review 2026-04-18 — pre-landing: 15 specialist findings, all addressed

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Renamed CLI command from helpbase context to helpbase ingest as the primary tool for synthesizing documentation from code repositories
    • helpbase context remains available as a deprecated alias with backward compatibility and deprecation warning
  • Documentation

    • Updated all examples and references throughout guides and README to reflect the new helpbase ingest command
  • Chores

    • Updated CI workflows, evaluation tooling, and test configurations

Codehagen and others added 2 commits April 18, 2026 09:53
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>
@vercel

vercel Bot commented Apr 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
helpbase Ready Ready Preview, Comment Apr 18, 2026 8:40am

Request Review

@coderabbitai

coderabbitai Bot commented Apr 18, 2026 •

Copy link
Copy Markdown

Warning

Rate limit exceeded

@Codehagen has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 17 minutes and 46 seconds before requesting another review.

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 @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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 configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a14a9ae5-56eb-4632-8447-530881b8911b

📥 Commits

Reviewing files that changed from the base of the PR and between 1321bc6 and 67e094a.

📒 Files selected for processing (14)
  • README.md
  • docs/cli.md
  • packages/cli/eval/questions.ts
  • packages/cli/scripts/generate-cli-docs.mjs
  • packages/cli/src/commands/context-errors.ts
  • packages/cli/src/commands/ingest.ts
  • packages/cli/src/lib/errors.ts
  • packages/cli/test/ingest.test.ts
  • packages/create-helpbase/src/index.ts
  • packages/shared/src/ai-context.ts
  • packages/shared/src/ai-text.ts
  • packages/shared/src/citations.ts
  • packages/shared/src/context-reader.ts
  • packages/shared/src/context-writer.ts
📝 Walkthrough

Walkthrough

This PR renames the CLI command from helpbase context to helpbase ingest, establishing context as a deprecated alias. A new ingest.ts file implements the complete documentation synthesis functionality, while context.ts is refactored into a thin wrapper that delegates execution with a deprecation warning. Documentation, tests, and error messages are updated throughout to reference the canonical new command.

Changes

Cohort / File(s) Summary
Core Command Implementation
packages/cli/src/commands/ingest.ts, packages/cli/src/commands/context.ts
New ingest.ts (753 lines) implements full doc synthesis pipeline including repo validation, dirty-tree checks, LLM synthesis, citation handling, atomic writes, llms.txt/MCP config emission, and local --ask flow. Exports applyIngestOptions(), runIngestAction(), runIngestAction(), and resolveProjectName(). Refactored context.ts (39 new / 715 removed) becomes thin alias delegating to ingest with deprecation warning suppressed under --json/--quiet.
CLI Wiring & Telemetry
packages/cli/src/index.ts, packages/cli/src/lib/telemetry.ts, packages/cli/src/lib/help.ts
Added ingestCommand subcommand; introduced DEPRECATED_ALIASES mapping (context → ingest) with alias-aware telemetry reporting (new optional alias field in TelemetryEvent). Updated help grouping to prioritize ingest in "Get started" and "Most common" sections, auto-relegating context to "Other".
Test Suites
packages/cli/test/ingest.test.ts, packages/cli/test/help.test.ts, packages/cli/test/doctor.test.ts
Created comprehensive ingest.test.ts with option parity checks between ingestCommand and contextCommand, plus new deprecated-alias tests. Updated test infrastructure to use isolated temp HOME directories for deterministic auth/token state. Refined help assertions to verify ingest in curated sections and context in auto-generated "Other" with deprecation marker.
Error & Shared Library Updates
packages/cli/src/commands/context-errors.ts, packages/shared/src/*, packages/create-helpbase/src/*
Updated user-facing error messages, guidance, and module documentation across context-errors, ai-context, ai-text, citations, context-reader, context-writer, llms-txt, schemas, and secrets to reference helpbase ingest instead of helpbase context. Clarified that E_CONTEXT_* error codes remain stable (doc URLs use /errors/e-context-*).
Public Documentation
README.md, CHANGELOG.md, docs/cli.md, packages/cli/eval/README.md, packages/cli/eval/grader.ts, packages/cli/eval/questions.ts, packages/cli/eval/runner.ts, packages/create-helpbase/templates/lib/schemas.ts, registry/helpbase/lib/schemas.ts
Updated CLI examples and command references from helpbase context to helpbase ingest. Added CHANGELOG entry documenting rename with deprecation shim details (shim removal planned for v0.7). Updated eval harness docs and runner (execSync calls) to invoke new ingest command. Updated schema/template documentation to reflect ingest ownership of generated outputs.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Poem

🐰 A hop, skip, and rename so grand,
From context to ingest across the land,
The alias hops gently to deprecation's rest,
While ingest bounds forward, now truly the best! 🌱✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 34.48% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: renaming helpbase context to helpbase ingest as part of CLI DX v2. It is concise, specific, and accurately reflects the primary objective.
Description check ✅ Passed The PR description covers all key aspects: summary of changes, detailed CLI surface modifications, new tests added, documentation updates, commit strategy, and comprehensive test plan with smoke-test checklist.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch cli-dx-ingest-rename

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 | 🟡 Minor

Quote repoPath in 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 | 🟡 Minor

Finish 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 | 🟡 Minor

Rename the stderr prefix to avoid surfacing the deprecated command.

Oversized-file warnings from helpbase ingest still 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 | 🟡 Minor

Update the stale context.ts reference.

This comment still points readers to context.ts, but the canonical implementation should now be ingest.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 | 🟡 Minor

Stale comment wording — still references the "CLI context command".

The surrounding comment was left unchanged by the rename pass. Since the consumer is now ingest.ts (with context.ts as 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 | 🟠 Major

Update expected citation target from context.ts to ingest.ts.

The citation-validation and drop-doc logic lives in packages/cli/src/commands/ingest.ts. The context.ts file is a deprecation shim that forwards to runIngestAction and is slated for removal in v0.7. A model analyzing the post-rename repo will cite the actual implementation in ingest.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 | 🟡 Minor

Update the adjacent stale context wording.

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 | 🟡 Minor

Add helpbase ingest to the CLI reference.

The README now positions ingest as 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 | 🟡 Minor

Remove the unsupported --include-ext recovery step.

helpbase ingest does 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 | 🟠 Major

Keep this test hermetic by stopping at the auth boundary.

Setting a fake AI_GATEWAY_API_KEY still lets the subprocess attempt a real LLM/Gateway call. You can prove the reuse path skipped walking by asserting it reaches E_AUTH_REQUIRED after 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 Other section'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

📥 Commits

Reviewing files that changed from the base of the PR and between 0224492 and 1321bc6.

📒 Files selected for processing (31)
  • .github/workflows/context-eval.yml
  • CHANGELOG.md
  • README.md
  • docs/cli.md
  • packages/cli/eval/README.md
  • packages/cli/eval/grader.ts
  • packages/cli/eval/questions.ts
  • packages/cli/eval/runner.ts
  • packages/cli/src/commands/context-errors.ts
  • packages/cli/src/commands/context.ts
  • packages/cli/src/commands/ingest.ts
  • packages/cli/src/commands/preview.ts
  • packages/cli/src/index.ts
  • packages/cli/src/lib/help.ts
  • packages/cli/src/lib/telemetry.ts
  • packages/cli/test/doctor.test.ts
  • packages/cli/test/help.test.ts
  • packages/cli/test/ingest.test.ts
  • packages/create-helpbase/src/emit-mcp-json.ts
  • packages/create-helpbase/src/generate-from-repo.ts
  • packages/create-helpbase/src/index.ts
  • packages/create-helpbase/templates/lib/schemas.ts
  • packages/shared/src/ai-context.ts
  • packages/shared/src/ai-text.ts
  • packages/shared/src/citations.ts
  • packages/shared/src/context-reader.ts
  • packages/shared/src/context-writer.ts
  • packages/shared/src/llms-txt.ts
  • packages/shared/src/schemas.ts
  • packages/shared/src/secrets.ts
  • registry/helpbase/lib/schemas.ts

Comment thread docs/cli.md Resolved
Comment thread packages/cli/src/commands/ingest.ts Resolved
Comment thread packages/cli/src/commands/ingest.ts Resolved
Comment thread packages/cli/src/commands/ingest.ts Resolved
Comment thread packages/cli/src/commands/ingest.ts Resolved
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>
@Codehagen

Copy link
Copy Markdown
Owner Author

Addressed all 5 findings in dd98541:

# Finding Fix
1 docs/cli.md anchor case / group labels as commands Generator regex now matches 4-space indent — only real subcommands land in the list. Fixes latent pre-existing bug: before this, docs/cli.md listed helpbase Get, helpbase Ship, etc. as fake sections instead of the 20 real commands.
2 --reuse-existing retry hint dropped repo path ingest.ts:194 — retry command now includes repoPathArg || ".".
3 Source content not secret-scanned before --debug dump / LLM call New pre-LLM scan loop after readContextSources. New E_CONTEXT_SECRET_SOURCE code (distinct from the post-MDX E_CONTEXT_SECRET so users can tell which gate caught it).
4 parseInt(x) || default silently swallowed negative / NaN New parseBudgetInt / parseBudgetFloat helpers. --max-tokens 0 still accepted (disables gate per docs); negative or non-numeric → E_CONTEXT_INVALID_BUDGET.
5 stderr.write + process.exit(1) instead of throw HelpbaseError Replaced with throw contextError("E_CONTEXT_REFUSE_CLOBBER", ...) — goes through the same formatter + JSON/quiet honoring as every other user error.

Tests: 4 new in ingest.test.ts:

  • negative --max-tokens → E_CONTEXT_INVALID_BUDGET
  • zero --chars-per-token → E_CONTEXT_INVALID_BUDGET
  • zero --max-tokens → accepted (gate-disable happy path)
  • secret in source file → E_CONTEXT_SECRET_SOURCE before any LLM call (asserts error carries pattern name + file path but NOT the secret bytes)

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 context.ts that the rename surfaced. Good catch on each.

@coderabbitai

coderabbitai Bot commented Apr 18, 2026

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

@Codehagen — excellent execution across all five. A few highlights worth noting:

  1. Pre-LLM source scanning (E_CONTEXT_SECRET_SOURCE) — the two-gate distinction is a great UX touch; users will immediately know whether a secret was caught before any data left the machine or only after synthesis, which matters for incident triage.
  2. parseBudgetInt / parseBudgetFloat — a clean, reusable pattern. Worth keeping consistent with any future numeric flags added to the command.
  3. throw contextError(...) for clobber refusal — now honours --json/--quiet just like every other error path, which is the right call for scripted consumers.
  4. docs/cli.md regex fix — good that fixing the regression also addressed the latent pre-existing bug with fake section headers.
  5. Test coverage — the four new cases (negative budget, zero chars-per-token, zero max-tokens gate-disable, and pre-LLM secret) are exactly the right boundary conditions.

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!

Codehagen added a commit that referenced this pull request Apr 18, 2026
`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>
@Codehagen

Copy link
Copy Markdown
Owner Author

Follow-up commit 67e094a addresses the 10 outside-diff-range findings + the fenced-block language-tag nitpick. Summary:

# Area Fix
1 README.md:264-272 Added helpbase ingest to the CLI reference block.
2 packages/create-helpbase/src/index.ts:709-759 New quoteShellArg helper; wraps repoPath in every retry-copy hint so paths with spaces (/Users/foo/my docs) produce valid copy/paste.
3 packages/shared/src/context-reader.ts:194 Oversized-file stderr prefix: [helpbase-context] → [helpbase-ingest]. User-visible.
4 packages/cli/test/ingest.test.ts:280-320 Hermeticity fix: the fake vck_... key no longer suppressed a contributor's real ANTHROPIC_API_KEY. Replaced the Answering: assertion with E_AUTH_REQUIRED — stronger signal, zero network.
5 packages/cli/eval/questions.ts:54-56 expectedCitations accepts ingest.ts OR context.ts during the v0.7 deprecation window. TODO marker for cleanup.
6 packages/cli/src/commands/context-errors.ts:94 Dropped the unsupported --include-ext suggestion; pointed users to the supported extension list instead.
7-11 packages/shared/src/{ai-context,ai-text,citations,context-writer}.ts Stale prose updated to reference helpbase ingest.
Nit packages/cli/scripts/generate-cli-docs.mjs Fenced blocks now emit ```text (silences MD040 repo-wide). docs/cli.md regenerated.

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.

@coderabbitai

coderabbitai Bot commented Apr 18, 2026

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

@Codehagen — clean sweep across all ten. A few standouts worth noting:

  1. quoteShellArg (#2) — the right fix and a good general utility. Paths with spaces in retry hints are an easy footgun to overlook; wrapping every copy-paste hint means users on macOS with spaces in their home paths aren't silently broken.
  2. Hermeticity fix / E_AUTH_REQUIRED (#4) — replacing the Answering: assertion with a structured error code is strictly better: deterministic, zero-network, and it actually tests the intended contract (auth is required) rather than an incidental output string. The "stealth-paid-LLM-call hazard on every contributor laptop" framing is exactly right — that category of bug is easy to miss in review and painful to discover.
  3. Dual-accept expectedCitations (#5) — the TODO marker for v0.7 cleanup is the right bookkeeping move during the deprecation window; keeps the eval honest without forcing a premature cut.
  4. Dropped --include-ext suggestion (#6) — pointing users at the supported extension list instead of a non-existent flag is a meaningful UX improvement; bad --help suggestions erode trust faster than missing features.
  5. ```text fencing (nit) — silencing MD040 repo-wide via the generator rather than per-file suppressions is the right level to fix it.

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.

@Codehagen
Codehagen merged commit f32be13 into main Apr 18, 2026
5 checks passed
@Codehagen
Codehagen deleted the cli-dx-ingest-rename branch April 18, 2026 08:40
Codehagen added a commit that referenced this pull request Apr 18, 2026
`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>
Codehagen added a commit that referenced this pull request Apr 18, 2026
* 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>
Codehagen added a commit that referenced this pull request Apr 18, 2026
Cut the 0.6.0 release. Bundles:
- deploy --preview + smart-prompt + auto-retry (#11)
- slug reservation flow (#10)
- context → ingest rename (#9)
- TTHW squeeze (#8)
- BYOK review-driven normalization

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
Preview — 67e094ab Deployed Apr 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant