Epic: Build the CLI and core indexing/query services

## Goal Deliver a typed, scriptable CLI over backend-independent ClariTree application services. The MVP creates and incrementally updates LadybugDB indexes, resolves indexes from convenient selectors, searches indexed C entities, and traverses value lineage. ## Command surface ```text claritree [--format <text|json>] index new <source> ... claritree [--format <text|json>] index update <project-path> [--index-path <path>] [--reindex] ... claritree [--format <text|json>] query --index <index-selector> lineage <value-selector> [--max-upstream-depth <n>] [--max-downstream-depth <n>] claritree [--format <text|json>] query --index <index-selector> search value ... claritree [--format <text|json>] query --index <index-selector> search function ... claritree [--format <text|json>] query --index <index-selector> search struct ... claritree [--format <text|json>] query --index <index-selector> search enum ... ``` `text` is the default for humans. `json` is stable, structured output suitable for programs. The CLI remains a thin adapter: indexing, cache resolution, search, traversal, validation, and database behavior belong to typed application/core services. Lineage uses **upstream** for producers that contribute to a value and **downstream** for consumers or derived values. This follows ClariTree's producer-to-consumer relationship direction and avoids ambiguous parent/child terminology. ## Work breakdown - [ ] #2 - [ ] #3 - [ ] #4 - [ ] #5 - [ ] #6 - [ ] #7 - [ ] #8 - [ ] #9 - [ ] #10 - [ ] #11 - [ ] #12 - [ ] #13 - [ ] #14 - [ ] #15 - [ ] #16 - [ ] #17 - [ ] #18 ## Completion criteria - A local directory and a Git origin can be indexed through the CLI. - Unchanged inputs produce a no-op incremental update; changed inputs replace only affected translation units unless `--reindex` is used. - Every query resolves a cached index or explicit database without exposing Cypher. - Text and JSON output cover successful results and actionable errors. - Search supports bounded results, nesting, deterministic ordering, and target-specific filters. - Lineage supports bounded upstream and downstream traversal from an unambiguous value handle. - Linux and Windows behavior is covered according to the project portability policy. - Complete CLI workflows have isolated end-to-end tests and user documentation.

JayKobe6k commented

2026-09-03 14:22:16 +00:00

Owner

Goal

Deliver a typed, scriptable CLI over backend-independent ClariTree application services. The MVP creates and incrementally updates LadybugDB indexes, resolves indexes from convenient selectors, searches indexed C entities, and traverses value lineage.

Command surface

claritree [--format <text|json>] index new <source> ...
claritree [--format <text|json>] index update <project-path> [--index-path <path>] [--reindex] ...
claritree [--format <text|json>] query --index <index-selector> lineage <value-selector> [--max-upstream-depth <n>] [--max-downstream-depth <n>]
claritree [--format <text|json>] query --index <index-selector> search value ...
claritree [--format <text|json>] query --index <index-selector> search function ...
claritree [--format <text|json>] query --index <index-selector> search struct ...
claritree [--format <text|json>] query --index <index-selector> search enum ...

text is the default for humans. json is stable, structured output suitable for programs. The CLI remains a thin adapter: indexing, cache resolution, search, traversal, validation, and database behavior belong to typed application/core services.

Lineage uses upstream for producers that contribute to a value and downstream for consumers or derived values. This follows ClariTree's producer-to-consumer relationship direction and avoids ambiguous parent/child terminology.

Work breakdown

Completion criteria

A local directory and a Git origin can be indexed through the CLI.
Unchanged inputs produce a no-op incremental update; changed inputs replace only affected translation units unless --reindex is used.
Every query resolves a cached index or explicit database without exposing Cypher.
Text and JSON output cover successful results and actionable errors.
Search supports bounded results, nesting, deterministic ordering, and target-specific filters.
Lineage supports bounded upstream and downstream traversal from an unambiguous value handle.
Linux and Windows behavior is covered according to the project portability policy.
Complete CLI workflows have isolated end-to-end tests and user documentation.

JayKobe6k added this to the CLI + Core MVP milestone

JayKobe6k added the

type/epic

area/cli

area/core

labels

Rows
Columns

Epic: Build the CLI and core indexing/query services #1

Goal

Command surface

Work breakdown

Completion criteria