Repository navigation
Description
Context
needle-app uses a small manual top-level command dispatcher. The current
usage path lists the available public commands, but --help, -h, --version,
and -V currently fall through as unknown subcommands. Usage failures are
reported on stderr and exit with status 2.
The package version already exists in Cargo metadata and the binary has an
existing VERSION constant, but users cannot inspect the version directly from
the command line. Adding a standard, zero-side-effect help and version surface
would make local source inspection easier and provide a bounded first Rust
contribution.
Outcome
Add successful top-level help and version commands without changing the current
manual parser, command behavior, or pre-alpha compatibility boundary.
Scope
- Make
needle --help,needle -h, andneedle helpprint concise top-level
help to stdout and exit with status0. - Make
needle --versionandneedle -Vprintneedle <package-version>to
stdout and exit with status0. - Derive the displayed version from Cargo package metadata, for example through
env!("CARGO_PKG_VERSION"); do not introduce another hard-coded version.
Reuse or replace the currentVERSIONconstant as appropriate. - List the same public top-level commands exposed by the current usage surface,
with a short description for each. Keep the internal
worker digest-filesutility out of general help. - State in the help output that Needle is a pre-alpha developer preview and that
interfaces may change. - Add process-level integration tests using
CARGO_BIN_EXE_needleto verify
exit status, stdout, and stderr for every new spelling. - Add a brief
--helpand--versionexample to
docs/DEVELOPER_SETUP.md.
Non-goals
- Adding
clapor another argument-parsing dependency. - Adding nested help for every subcommand or redesigning existing usage text.
- Changing the behavior of an empty argument list, unknown commands, or invalid
subcommand arguments. - Initializing SQLite, resolving a product data directory, checking Codex,
starting a provider process, using the network, or changing frontend code. - Claiming a stable CLI or installation interface.
Acceptance criteria
-
needle --help,needle -h, andneedle helpproduce the same bounded
help text on stdout, write nothing to stderr, and exit successfully. -
needle --versionandneedle -Vproduce exactly one line in the form
needle <CARGO_PKG_VERSION>, write nothing to stderr, and exit
successfully. - Help and version execution perform no profile initialization, SQLite
write, Codex lookup, provider call, or repository mutation. - The help text covers every command in the current public usage surface and
does not advertise the internalworker digest-filesutility. - Empty input and an unknown command retain their current non-zero usage
behavior andneedle:error prefix. - Tests execute the built binary rather than testing only a string-rendering
helper. - No new dependency is added and existing command dispatch remains
compatible. - Developer setup documentation contains working help and version examples
without presenting the CLI as stable.
Starting points
crates/needle-app/src/main.rs—main,run,AppError::Usage, the
top-level command match, andVERSION.crates/needle-app/tests/mcp_stdio.rs— existing process-level binary test
usingCARGO_BIN_EXE_needle.Cargo.tomlandcrates/needle-app/Cargo.toml— package version metadata.docs/DEVELOPER_SETUP.md— source-development command examples.
Validation
Build the embedded frontend before compiling needle-app from a clean
checkout, then run the focused CLI test and app regression suite:
cd crates/needle-app/web
npm ci
npm run build
cd ../../..
cargo fmt --all -- --check
cargo test --locked -p needle-app --test cli_surface
cargo test --locked -p needle-app
git diff --check
The implementation and tests must remain fully offline and must not require a
Codex installation or provider credential.
Activity