feat(cli): display onboarding guidance on zero-topic empty vaults

[Kuldeep2822k]

Summary

• Adds clear, actionable onboarding guidance when 0 topics are discovered in dashboard, plan, progress, and next commands
• Directs new users to palee adopt and palee roadmap --from instead of showing empty stat screens or blank outputs
• Adds comprehensive unit test coverage verifying empty vault behavior across all 4 commands

Quality & Invariant Verification

• Verified against empty and populated test vaults
• Clean TypeScript compilation with tsc --noEmit
• ESLint checks passing with 0 warnings
• All 90 unit/integration tests passing

[greptile-apps]

Kuldeep2822k has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[coderabbitai]

Warning

Review limit reached

@Kuldeep2822k, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 47 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Free

Run ID: 1dc48bc9-a112-492e-a040-8681e49d8cb0

📥 Commits

Reviewing files that changed from the base of the PR and between 8d78f2b and af0fc4c.

📒 Files selected for processing (7)

• src/cli/dashboard.ts
• src/cli/next.ts
• src/cli/onboarding.ts
• src/cli/plan.ts
• src/cli/progress.ts
• src/storage/vault-walker.ts
• test/storage-walker.test.ts

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Free

Run ID: f1e9b9fb-a982-4b5f-9c43-5950bf9c8e99

📥 Commits

Reviewing files that changed from the base of the PR and between d68b208 and 8d78f2b.

📒 Files selected for processing (6)

• src/cli/dashboard.ts
• src/cli/next.ts
• src/cli/onboarding.ts
• src/cli/plan.ts
• src/cli/progress.ts
• test/cli-commands.test.ts

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added onboarding guidance when the configured vault is empty, including options to adopt an existing note or import a curriculum roadmap.
  • Dashboard, planning, progress, and next-step commands now provide actionable guidance when no topics are available.

• Bug Fixes

  • Commands now clearly report missing vault paths and exit with an appropriate error status.
  • Improved command completion behavior after successful execution.

Walkthrough

The four CLI commands now validate vault paths, show shared onboarding guidance when no topics exist, and return normally after successful execution. Tests cover onboarding output, successful exits, and missing-vault errors.

Changes

Empty-vault CLI behavior

Layer / File(s)	Summary
Shared onboarding utility src/cli/onboarding.ts	Adds printEmptyVaultOnboarding(), which prints commands for adopting an existing note or importing a curriculum roadmap.
Command validation and empty-vault flows src/cli/dashboard.ts, src/cli/next.ts, src/cli/plan.ts, src/cli/progress.ts, test/cli-commands.test.ts	The commands validate the configured vault path and exit with status 2 when it is missing. Empty vaults display shared onboarding guidance. Successful paths return normally. Tests cover all four commands.
Estimated code review effort: 3 (Moderate)	~20 minutes

Merge Risk: ⚪ Minimal · up to 8d78f

This change adds onboarding guidance for empty vaults across four CLI commands without introducing an actionable merge-blocking risk; it is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CLICommand
  participant VaultPath
  participant TopicScanner
  participant OnboardingUtility
  CLICommand->>VaultPath: Validate configured path
  alt Path is missing
    VaultPath-->>CLICommand: Path not found
    CLICommand-->>CLICommand: Exit with status 2
  else Path exists
    CLICommand->>TopicScanner: Scan vault
    TopicScanner-->>CLICommand: Return topics
    alt No topics found
      CLICommand->>OnboardingUtility: Print empty-vault guidance
      OnboardingUtility-->>CLICommand: Return
    else Topics found
      CLICommand-->>CLICommand: Continue processing
    end
  end

Loading

Poem

I hop through the vault where the new notes should grow,
Empty paths now explain which next steps to show.
Four commands speak clearly, then return with care,
Missing paths raise errors instead of thin air.
— A helpful rabbit 🐇

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

CLI: show onboarding guidance when vault has zero topics

✨ Enhancement 🧪 Tests 🕐 20-40 Minutes

AI Description

• Print onboarding steps when no topics exist across dashboard/plan/progress/next.
• Exit early to avoid blank/empty-state outputs in new-user vaults.
• Add unit tests covering empty-vault behavior for all four commands.

Diagram

graph TD
  D["dashboard.ts"] --> Z{ "0 topics?" } --> O["Onboarding guidance"] --> X(("Exit 0"))
  P["plan.ts"] --> Z --> O --> X
  R["progress.ts"] --> Z --> O --> X
  N["next.ts"] --> Z --> O --> X
  V[("Vault files")] --> D
  V --> P
  V --> R
  V --> N
  subgraph Legend
    direction LR
    _cmd["Command"] ~~~ _dec{"Decision"} ~~~ _out["Output"] ~~~ _exit(("Process exit")) ~~~ _db[("Vault")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Centralize onboarding empty-state helper

• ➕ Eliminates repeated strings/formatting across commands
• ➕ Ensures future edits keep messaging consistent
• ➕ Enables reuse in future commands (e.g., search/list)
• ➖ Slight indirection for simple CLI output
• ➖ Requires choosing a shared location/API for CLI utilities

2. Return control instead of calling process.exit in commands

• ➕ Improves testability and composability (callers decide exit behavior)
• ➕ Avoids potential issues in embedded/programmable CLI usage
• ➖ May require refactoring the command runner to handle return codes consistently
• ➖ More changes than needed for this UX improvement

3. Add a dedicated `palee init` / onboarding command and point to it

• ➕ Single canonical onboarding entrypoint
• ➕ Can evolve into an interactive setup flow
• ➖ Adds new surface area and maintenance
• ➖ Doesn’t directly solve current empty-output confusion unless all commands link to it

Recommendation: Current approach is pragmatic and user-friendly, but the repeated onboarding block across four commands is a good candidate for a shared helper/constant to prevent drift. If CLI architecture permits, consider a follow-up to replace direct process.exit(0) with returning an exit code and letting the top-level runner exit, improving composability and tests.

Files changed (5) +72 / -11

Enhancement (4) +46 / -2

dashboard.tsPrint onboarding guidance when dashboard finds zero topics +10/-0

Print onboarding guidance when dashboard finds zero topics

• Adds an early guard that detects an empty topic list, prints actionable onboarding instructions (adopt/import roadmap), and exits successfully before rendering stats.

src/cli/dashboard.ts

next.tsDetect empty vault in next command and show onboarding instructions +12/-0

Detect empty vault in next command and show onboarding instructions

• Tracks total discovered topics separately from due topics. When zero topics exist, prints onboarding guidance and exits 0 before emitting "No topics due" messaging.

src/cli/next.ts

plan.tsShow onboarding guidance for empty vaults in plan output +13/-2

Show onboarding guidance for empty vaults in plan output

• Adds an empty-vault check after printing the plan header, prints onboarding guidance, and exits. Moves ready-topic computation to occur only when topics exist.

src/cli/plan.ts

progress.tsAdd empty-vault onboarding message for progress (no topic filter) +11/-0

Add empty-vault onboarding message for progress (no topic filter)

• When no topics are found and no specific topic is requested, prints the progress header plus onboarding guidance and exits successfully.

src/cli/progress.ts

Tests (1) +26 / -9

cli-commands.test.tsAdd coverage for empty-vault onboarding behavior across CLI commands +26/-9

Add coverage for empty-vault onboarding behavior across CLI commands

• Replaces the prior dashboard-only empty vault assertion with a combined test that runs dashboard/plan/progress/next against an empty vault and verifies the onboarding messaging is shown.

test/cli-commands.test.ts

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Unreadable vault shown empty ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new empty-vault onboarding paths treat “0 topics” as a successful empty state, but walkVault can
return an empty list when the vault directory can’t be read (missing/permission denied), causing the
CLI to print onboarding guidance and exit 0 instead of reporting an error. This can mislead users
and automation by hiding configuration/environment problems as a normal empty vault.

Code

src/cli/next.ts[R62-65]

+    if (totalTopics === 0) {
+      console.log('No topics found in vault.\n');
+      console.log('To get started:');
+      console.log('  • Adopt an existing note:');

Relevance

●●● Strong

Likely viewed as real correctness bug: unreadable/missing vault shouldn’t be treated as normal empty
state.

PR-#7

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

walkVault swallows directory-read failures and returns no files; the new empty-vault onboarding
branch triggers on “0 topics” and exits 0, so an unreadable/missing vault is reported as an empty
vault instead of an error.

src/storage/vault-walker.ts[32-38]
src/cli/next.ts[62-70]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`walkVault()` silently returns an empty list when it cannot read the configured vault directory. With the new “0 topics” onboarding branch, this turns vault I/O failures (missing directory / permission denied) into a successful exit with onboarding text.

## Issue Context
`config set-vault` validates the path at set time, but the directory can later be deleted or become unreadable. The CLI should distinguish “scan succeeded and found 0 topics” from “scan could not run.”

## Fix Focus Areas
- src/cli/next.ts[24-70]
- src/cli/dashboard.ts[22-72]
- src/cli/plan.ts[22-78]
- src/cli/progress.ts[25-66]
- src/storage/vault-walker.ts[32-38]

## Suggested fix
- Before calling `walkVault`, explicitly validate `vaultPath` exists, is a directory, and is readable (e.g., `fs.statSync` + `fs.accessSync(vaultPath, fs.constants.R_OK)`), and exit non-zero with a clear error if not.
- Alternatively (or additionally), change `walkVault` so the *root* directory read failure throws (or returns an error) instead of being silently treated as empty; keep silent skipping for subdirectories if desired.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Duplicated onboarding copy ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The same onboarding guidance block is duplicated across four command handlers, increasing the chance
the messages drift over time or get updated inconsistently. This makes future changes riskier and
more error-prone.

Code

src/cli/plan.ts[R70-73]

+    if (topics.size === 0) {
+      console.log('No topics found in vault.\n');
+      console.log('To get started:');
+      console.log('  • Adopt an existing note:');

Relevance

●● Moderate

Refactor to dedupe copy is subjective/scope-expanding; without precedent, acceptance is uncertain.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The identical “No topics found… adopt… roadmap --from …” message sequence appears in each of the
four modified commands.

src/cli/dashboard.ts[64-72]
src/cli/next.ts[62-70]
src/cli/plan.ts[70-78]
src/cli/progress.ts[57-66]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The empty-vault onboarding guidance is copy-pasted across `dashboard`, `next`, `plan`, and `progress`. This duplication increases maintenance cost and risks inconsistent messaging.

## Issue Context
Tests now assert parts of this output, so keeping a single source of truth helps avoid subtle inconsistencies.

## Fix Focus Areas
- src/cli/dashboard.ts[64-72]
- src/cli/next.ts[62-70]
- src/cli/plan.ts[70-78]
- src/cli/progress.ts[57-66]

## Suggested fix
- Create a small helper like `src/cli/empty-vault.ts` exporting `printEmptyVaultOnboarding()`.
- Have each command call the helper and then return/exit.
- Keep the tests as-is (they should continue passing) since output stays identical, just centrally defined.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. process.exit may drop logs ✓ Resolved 🐞 Bug ☼ Reliability

Description

The new onboarding branches call process.exit(0) immediately after multiple console.log calls;
Node.js documents that process.exit() can terminate before pending stdout/stderr writes complete
when output is piped or otherwise asynchronous. This can intermittently truncate onboarding output
in non-TTY contexts (e.g., piping/CI capture).

Code

src/cli/dashboard.ts[71]

+      process.exit(0);

Relevance

●● Moderate

No close repo precedent found; avoiding process.exit for log flushing is reasonable but may be seen
as overcautious.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR adds new early process.exit(0) calls in the empty-vault onboarding paths. Node.js
documentation explicitly warns that process.exit() can end the process before pending async
stdout/stderr writes complete.

src/cli/dashboard.ts[64-72]
src/cli/next.ts[62-70]
src/cli/plan.ts[70-78]
src/cli/progress.ts[57-66]
🌐 Node docs note that calling process.exit() forces termination even if asynchronous operations (including stdout/stderr I/O) are still pending, which can truncate output.

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
In the newly-added empty-vault onboarding branches, the command calls `process.exit(0)` right after printing multiple lines. Per Node.js docs, this can cut off pending async writes to `stdout`/`stderr`.

## Issue Context
This is most observable when output is piped/redirected (non-TTY) or under certain runtime environments. The CLI entrypoint (`program.parseAsync`) will exit naturally when the handler resolves.

## Fix Focus Areas
- src/cli/dashboard.ts[64-72]
- src/cli/next.ts[62-70]
- src/cli/plan.ts[70-78]
- src/cli/progress.ts[57-66]

## Suggested fix
- Replace `process.exit(0)` in these onboarding branches with `process.exitCode = 0; return;` (or just `return;` if no further work is pending).
- Keep `process.exit(2/5)` where you truly need immediate termination, or prefer throwing errors and letting the top-level `.catch` handle exit codes consistently.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context

✅ Web pages:

  🌐 Process | Node.js v26.7.0 Documentation

  🌐 process: flush stdout/stderr upon `process.exit()`

  🌐 stdout/stderr buffering considerations

  +2 more

Review mode: ⚖️ Balanced: This is a behavioral CLI change across four commands with exit-flow and topic-detection logic, but it is not dense or broad enough to justify redundant extended review.

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[greptile-apps]

Kuldeep2822k has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[greptile-apps]

Kuldeep2822k has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.