Skip to content

feat(cli): add index rebuild recovery flow#143

Merged
0xjunha merged 2 commits into
mainfrom
migration-hint
May 13, 2026
Merged

feat(cli): add index rebuild recovery flow#143
0xjunha merged 2 commits into
mainfrom
migration-hint

Conversation

@0xjunha
Copy link
Copy Markdown
Owner

@0xjunha 0xjunha commented May 13, 2026

Summary

Add a guided recovery path for Darc users whose local SQLite index was created by an older CLI schema and can no longer be opened or migrated by the current CLI.

This introduces darc index --rebuild, improves rebuild recommendations across human and JSON error surfaces, makes rebuild safer around partial failures and concurrent writers, and removes leftover Windows support paths now that Darc CLI is intentionally unsupported on Windows.

Background

Darc’s sync, index, and read/query commands assume the current SQLite index schema. Users upgrading from an older CLI can have an existing index.sqlite that fails to open or migrate cleanly. For most users, rebuilding the local SQLite cache from archived sessions is cheap, but the CLI needs to recommend that only when the existing cache is actually unusable.

What Changed

darc index --rebuild

  • Added darc index --rebuild as a workspace-wide rebuild mode.
  • Rebuild indexes every configured project into the shared index.sqlite.
  • Plain darc index remains active-project scoped.
  • darc index --provider ... still works for normal indexing.
  • darc index --rebuild --provider ... is rejected because rebuild is intentionally all-provider/all-project.

Rebuild Safety

  • Rebuild writes into a temporary sibling SQLite database first.
  • The existing index.sqlite is preserved until the full rebuild succeeds.
  • Temporary rebuild files and SQLite sidecars are cleaned up.
  • Rebuild reports are normalized back to the final shared index.sqlite path after replacement.
  • Rebuild now takes the shared refresh/index lock, so it does not race with refresh, watch refreshes, or normal index writes.

User Guidance

  • Existing corrupt or unmigratable indexes now produce a clear rebuild recommendation instead of a raw SQLite failure.
  • Human command errors show:
    • the failing index path
    • a bold darc index --rebuild command
    • a note that only the local SQLite cache is deleted
    • a note that archived sessions are not deleted
    • the underlying cause when available
  • Custom roots are preserved in the recommendation, for example:
    • darc index --rebuild --root '/custom/root'
  • JSON query errors now include the same correct custom-root rebuild command.
  • Workspace query payloads now include rebuild guidance in root.issues instead of swallowing the recommendation.
  • darc index --rebuild prints a short interactive progress line before work starts:
    • Rebuilding shared index from archived sessions...

Read-Only Paths

  • Read-only index opens now also attach rebuild guidance when the existing index is corrupt or unmigratable.
  • This covers paths such as project removal dry runs and other read-only index inspections.

Windows Support

  • Added an explicit compile-time error for Darc CLI on Windows.
  • Removed Windows-specific runtime/package handling from schema audit code.
  • Removed Windows drive-root path handling from query path normalization.
  • Removed stale Windows-specific index replacement branching.

User-Facing Behavior

A user with a bad existing index.sqlite will now see actionable guidance to run darc index --rebuild only when Darc determines the cache cannot be opened or migrated.

The command rebuilds the local SQLite cache from archived sessions. It does not delete archived sessions.

Tests

Added or updated coverage for:

  • Parsing and help text for darc index --rebuild.
  • Rejecting --rebuild --provider.
  • Rebuilding all configured projects into the shared index.
  • Preserving the previous index when rebuild fails mid-run.
  • Rebuild guidance for corrupt existing SQLite databases.
  • No rebuild guidance for a missing index.
  • Read-only corrupt-index rebuild guidance.
  • Human error formatting, including bold rebuild command.
  • JSON query error formatting with custom roots.
  • Workspace query root.issues rebuild guidance.
  • Refresh/index lock behavior for rebuild.
  • SQLite sidecar cleanup.
  • Interactive rebuild progress message formatting.
  • Removed Windows platform/package branches.

Verification

  • cargo +nightly fmt
  • cargo test --workspace --all-features
  • cargo clippy --workspace --all-targets --all-features -- -D warnings -W clippy::all
  • scripts/check-linux-clippy.sh

@0xjunha 0xjunha merged commit 180a015 into main May 13, 2026
6 checks passed
@0xjunha 0xjunha deleted the migration-hint branch May 13, 2026 13:55
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