Build the CLI command tree and text/JSON output contract #3

New issue

Closed

opened 2026-09-03 14:22:17 +00:00 by JayKobe6k · 0 comments

JayKobe6k commented

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

Owner

Goal

Implement the CLI shell as a thin adapter over the typed application services.

CLI contract

Add a root-level, global --format <text|json> option; default to text.
Define the index new, index update, query lineage, and query search {value,function,struct,enum} command tree.
Put --index <index-selector> on query so every query subcommand shares it.
Parse into dedicated CLI argument structs, then convert immediately into application request types.
Centralize text rendering and JSON serialization instead of formatting inside command handlers.
Keep stdout machine-clean in JSON mode. Send diagnostics/progress to stderr and define a structured JSON error envelope.
Define stable exit statuses for success, invalid arguments/selectors, unavailable indexes, indexing failures, query failures, and internal failures.

Initial handlers may return a typed unavailable-operation error until their application service lands; they must not contain placeholder domain logic.

Acceptance criteria

Help output documents every command and global option.
--format works before or after a subcommand where supported by the parser.
JSON success and error output round-trip through a parser and never includes progress text.
Text output is concise and human-readable.
CLI parser/dispatch tests do not require LadybugDB or libclang.
Invalid enum values and malformed numeric arguments fail before service invocation.

Dependencies

Depends on #2 for application request and response types.

## Goal Implement the CLI shell as a thin adapter over the typed application services. ## CLI contract - Add a root-level, global `--format <text|json>` option; default to `text`. - Define the `index new`, `index update`, `query lineage`, and `query search {value,function,struct,enum}` command tree. - Put `--index <index-selector>` on `query` so every query subcommand shares it. - Parse into dedicated CLI argument structs, then convert immediately into application request types. - Centralize text rendering and JSON serialization instead of formatting inside command handlers. - Keep stdout machine-clean in JSON mode. Send diagnostics/progress to stderr and define a structured JSON error envelope. - Define stable exit statuses for success, invalid arguments/selectors, unavailable indexes, indexing failures, query failures, and internal failures. Initial handlers may return a typed unavailable-operation error until their application service lands; they must not contain placeholder domain logic. ## Acceptance criteria - Help output documents every command and global option. - `--format` works before or after a subcommand where supported by the parser. - JSON success and error output round-trip through a parser and never includes progress text. - Text output is concise and human-readable. - CLI parser/dispatch tests do not require LadybugDB or libclang. - Invalid enum values and malformed numeric arguments fail before service invocation. ## Dependencies Depends on #2 for application request and response types.

JayKobe6k added this to the CLI + Core MVP milestone

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

JayKobe6k added the

type/foundation

area/cli

labels

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

JayKobe6k referenced this issue

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

Implement index new project indexing and atomic publication #8

JayKobe6k referenced this issue

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