You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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, and needle help print concise top-level
help to stdout and exit with status 0.
Make needle --version and needle -V print needle <package-version> to
stdout and exit with status 0.
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 current VERSION constant 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-files utility 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_needle to verify
exit status, stdout, and stderr for every new spelling.
Add a brief --help and --version example to docs/DEVELOPER_SETUP.md.
Non-goals
Adding clap or 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, and needle help produce the same bounded
help text on stdout, write nothing to stderr, and exit successfully.
needle --version and needle -V produce 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 internal worker digest-files utility.
Empty input and an unknown command retain their current non-zero usage
behavior and needle: 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, and VERSION.
crates/needle-app/tests/mcp_stdio.rs — existing process-level binary test
using CARGO_BIN_EXE_needle.
Cargo.toml and crates/needle-app/Cargo.toml — package version metadata.
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.
Context
needle-appuses a small manual top-level command dispatcher. The currentusage path lists the available public commands, but
--help,-h,--version,and
-Vcurrently fall through as unknown subcommands. Usage failures arereported on stderr and exit with status
2.The package version already exists in Cargo metadata and the binary has an
existing
VERSIONconstant, but users cannot inspect the version directly fromthe 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
needle --help,needle -h, andneedle helpprint concise top-levelhelp to stdout and exit with status
0.needle --versionandneedle -Vprintneedle <package-version>tostdout and exit with status
0.env!("CARGO_PKG_VERSION"); do not introduce another hard-coded version.Reuse or replace the current
VERSIONconstant as appropriate.with a short description for each. Keep the internal
worker digest-filesutility out of general help.interfaces may change.
CARGO_BIN_EXE_needleto verifyexit status, stdout, and stderr for every new spelling.
--helpand--versionexample todocs/DEVELOPER_SETUP.md.Non-goals
clapor another argument-parsing dependency.subcommand arguments.
starting a provider process, using the network, or changing frontend code.
Acceptance criteria
needle --help,needle -h, andneedle helpproduce the same boundedhelp text on stdout, write nothing to stderr, and exit successfully.
needle --versionandneedle -Vproduce exactly one line in the formneedle <CARGO_PKG_VERSION>, write nothing to stderr, and exitsuccessfully.
write, Codex lookup, provider call, or repository mutation.
does not advertise the internal
worker digest-filesutility.behavior and
needle:error prefix.helper.
compatible.
without presenting the CLI as stable.
Starting points
crates/needle-app/src/main.rs—main,run,AppError::Usage, thetop-level command match, and
VERSION.crates/needle-app/tests/mcp_stdio.rs— existing process-level binary testusing
CARGO_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-appfrom a cleancheckout, then run the focused CLI test and app regression suite:
The implementation and tests must remain fully offline and must not require a
Codex installation or provider credential.