### Development setup commands Source: https://github.com/helgesverre/dev/blob/main/README.md Clones the repository and sets up a development environment. Runs just install, installs shell completions, and runs dev doctor. ```console git clone https://github.com/HelgeSverre/dev.git cd dev just install dev completions --install dev doctor ``` -------------------------------- ### Execution preamble example (text) Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Example of the execution preamble that summarizes the decisive match. It shows the command to run and the matched hint. ```text › php artisan test tests/Feature/ParticipantSyncTest.php matched: “participant” -> ParticipantSyncTest.php ``` -------------------------------- ### Generate and install shell completions with dev completions Source: https://github.com/helgesverre/dev/blob/main/README.md Generate and install shell completion scripts for Bash, Zsh, Fish, Elvish, Nushell, or PowerShell. The --install flag detects the current shell from $SHELL, respects XDG and $ZDOTDIR directories, creates the user-local completion directory, and writes the script there. It prints any shell-specific activation step; PowerShell requires the manual $PROFILE command shown above. Restart the shell after installing a completion script. ```console dev completions --install # Or generate/install a specific shell explicitly: dev completions zsh --install dev completions nushell --install dev completions bash > ~/.local/share/bash-completion/completions/dev dev completions zsh > ~/.zsh/completions/_dev dev completions fish > ~/.config/fish/completions/dev.fish dev completions elvish > ~/.config/elvish/lib/dev.elv dev completions nushell > ~/.config/nushell/completions/dev.nu dev completions powershell >> $PROFILE ``` -------------------------------- ### Explainability output example (text) Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Example output showing how query evidence and structural evidence are displayed separately for explainability. It lists each query term with its match type and points, and structural evidence with its contributing factors. ```text Query match participant -> ParticipantSyncTest.php identity/exact 100 laravel -> artisan scope/synonym 60 whatever -> no match 0 coverage: 2/3 meaningful terms Structural evidence base suitability: Laravel test 80 artisan present 15 same directory 30 ``` -------------------------------- ### dev CLI usage examples Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Example invocations of the `dev` command, covering run, test, and build intents with various targets, hints, and passthrough arguments. ```console dev run dev run ./apps/web dev run ./apps/web vite frontend dev test ./tests/Feature laravel entitlement participant dev run wibblewbale dev build rust release -- --release dev test --at tests/Feature/AuthTest.php auth -- --stop-on-failure ``` -------------------------------- ### Run dev with no arguments Source: https://github.com/helgesverre/dev/blob/main/website/index.html Runs dev without arguments to start the project. The output shows the detected command and its context. ```bash $ dev run › pnpm run dev (vite, ~/code/acme/apps/web) ``` -------------------------------- ### Install dev with cargo install Source: https://github.com/helgesverre/dev/blob/main/README.md Installs dev from the repository using Cargo. Requires Rust 1.85 or newer. ```console cargo install --git https://github.com/HelgeSverre/dev.git ``` -------------------------------- ### dev command usage examples Source: https://github.com/helgesverre/dev/blob/main/README.md Shows typical invocations of the dev command: running the default command, building a specific path, running tests with filters, and running a Laravel queue command. ```console dev run dev build ./apps/web dev test ./tests/Feature entitlement participant dev run laravel queue ``` -------------------------------- ### Define DetectorRegistration for example detector Source: https://github.com/helgesverre/dev/blob/main/docs/adding-a-detector.md Shows the DetectorRegistration entry that wires the example detector's ID, candidate sources, markers, tools, and metadata. Add this to REGISTRATIONS; registration order is not precedence and must not change results. ```rust DetectorRegistration { id: EXAMPLE, candidate_sources: &[CandidateSourceRegistration { id: EXAMPLE_SOURCE, metadata_priority: 2, default_tags: &["example"], }], synonyms: &["example", "ex"], markers: &[ProjectMarker { pattern: MarkerPattern::Exact("example.toml"), root_role: RootRole::Package, }], tools: &[EXAMPLE_PROGRAM], conventional_roots: ROOTS, cache_environment: &[], candidate_schema: 1, detector: &ExampleDetector, workspace: None, target_binders: &[], target_runners: &[], }, ``` -------------------------------- ### Execution preamble example Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Print this concise line to stderr immediately before execution. For hinted decisions, add a second dim line with the decisive match. Flush stderr before exec; --quiet suppresses the preamble, and NO_COLOR or --color never removes styling but not the text. ```text › pnpm run dev (vite, ~/code/myapp) ``` -------------------------------- ### Unix process replacement with CommandExt::exec Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Use process replacement on Unix to start the child process. If exec returns, execution failed; map common errors like ENOENT and EACCES to concise diagnostics. This preserves the terminal, signals, and exit status. ```rust use std::os::unix::process::CommandExt; let err = command.current_dir(cwd).envs(env).exec(); ``` -------------------------------- ### Run dev with various intents and queries Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Example invocations of the dev command. The last command may match an npm script named wibble-wabble, a Cargo binary, a Compose service, a Make target, or a loose executable file. dev ranks only commands constructed by deterministic detectors; fuzzy matching chooses among those commands and never invents shell syntax. ```console dev run ``` ```console dev build ./apps/web ``` ```console dev test ./tests/Feature entitlement participant ``` ```console dev run laravel queue ``` ```console dev run wibblewbale ``` -------------------------------- ### Local end-to-end inspection with non-executing mode Source: https://github.com/helgesverre/dev/blob/main/docs/adding-a-detector.md Use these commands for a local end-to-end inspection with a real fixture in a non-executing mode. Do not install the fixture's dependencies merely to make discovery pass, and do not claim execution coverage from --why or JSON output. ```console cargo run -- run --why --no-cache --at /path/to/fixture hint cargo run -- test --json --no-cache --at /path/to/fixture ``` -------------------------------- ### Suggested crate layout for dev Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Suggested directory layout for the Rust project, organized by scanning, detection, querying, scoring, caching, UI, and execution modules. Use as a starting point for structuring the crate. ```text dev/ ├── Cargo.toml ├── src/ │ ├── main.rs │ ├── cli.rs │ ├── intent.rs │ ├── candidate.rs │ ├── diagnostic.rs │ ├── registry.rs │ ├── doctor.rs │ ├── scan/ │ │ ├── mod.rs │ │ ├── roots.rs │ │ ├── index.rs │ │ ├── target_index.rs │ │ └── manifest.rs │ ├── detect/ │ │ ├── mod.rs │ │ ├── builder.rs │ │ ├── node.rs │ │ ├── cargo.rs │ │ ├── php.rs │ │ ├── go.rs │ │ ├── zig.rs │ │ ├── swift.rs │ │ ├── dart.rs │ │ ├── python.rs │ │ ├── just.rs │ │ ├── make.rs │ │ ├── docker.rs │ │ └── shell.rs │ ├── query/ │ │ ├── mod.rs │ │ ├── normalize.rs │ │ ├── matcher.rs │ │ ├── rank.rs │ │ └── synth.rs │ ├── score.rs │ ├── dedupe.rs │ ├── resolve.rs │ ├── cache/ │ │ ├── mod.rs │ │ ├── key.rs │ │ ├── shape.rs │ │ └── lock.rs │ ├── ui/ │ │ ├── picker.rs │ │ ├── why.rs │ │ ├── json.rs │ │ ├── command_display.rs │ │ └── error.rs │ ├── exec/ │ │ ├── mod.rs │ │ ├── unix.rs │ │ └── windows.rs │ └── path.rs ├── tests/ │ ├── fixtures/ │ ├── snapshots/ │ ├── cli_test.rs │ ├── detect_test.rs │ ├── query_test.rs │ ├── cache_test.rs │ └── exec_test.rs └── benches/ ├── scan.rs └── query.rs ``` -------------------------------- ### Doctor probe examples for go, zig, just, flutter Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Shows why a generic --version fallback is forbidden for doctor probes. Each tool must register an audited command probe, a bounded local-metadata reader, or presence-only reporting. Flutter's launcher is not safe because it may wait for a lock, update the SDK, or rebuild before printing. ```text go -> go version zig -> zig version just -> just --version flutter -> read SDK-local bin/cache/flutter.version.json ``` -------------------------------- ### Register detector IDs and tool constant Source: https://github.com/helgesverre/dev/blob/main/docs/adding-a-detector.md Declares the detector, candidate source, and tool IDs, plus a command tool constant for the example program. Place near corresponding constants in src/registry.rs. ```rust pub const EXAMPLE: DetectorId = DetectorId::new("example"); pub const EXAMPLE_SOURCE: CandidateSourceId = CandidateSourceId::new("example"); pub const EXAMPLE_TOOL: ToolId = ToolId::new("example"); const EXAMPLE_PROGRAM: ToolRegistration = command_tool(EXAMPLE_TOOL, "example", &["--version"]); ``` -------------------------------- ### No candidates error output Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Example error output when no candidates are found. The error includes scan scope, truncation state, manifests, relevant diagnostics, and actionable alternatives. It does not invent facts such as test counts. ```text dev: nothing runnable found for Run in ./src package root: ~/code/mylib workspace root: — scanned: 41 entries (complete) found: Cargo.toml cargo: crate `mylib` has no executable targets Try: dev test ./src dev build ./src dev run ./src --pick ``` -------------------------------- ### Uninstall dev with cargo uninstall Source: https://github.com/helgesverre/dev/blob/main/README.md Removes the dev installation. ```console cargo uninstall dev-launcher ``` -------------------------------- ### JSON output from --json flag Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Example of the JSON object emitted by the --json flag. It contains a versioned schema with invocation, scan, resolution, candidates, and diagnostics fields. The resolution status is "resolved" with reason "unique_identity_match". ```json { "schema_version": 1, "invocation": { "intent": "run", "target": "/home/h/code/app", "hints": ["wibblewbale"], "chaos": 1 }, "scan": { "package_root": "/home/h/code/app", "workspace_root": null, "scan_root": "/home/h/code/app", "structural_entries": 48, "target_entries": 12, "truncated": false }, "resolution": { "status": "resolved", "selected_candidate_id": "...", "reason": "unique_identity_match" }, "candidates": [], "diagnostics": [] } ``` -------------------------------- ### Run dev with hints for action and package Source: https://github.com/helgesverre/dev/blob/main/website/index.html Uses hints to narrow the command. The output shows the matched action and package. ```bash $ dev run billing worker › pnpm run worker (node, ~/code/acme/apps/billing) matched: “worker” → action · “billing” → package ``` -------------------------------- ### Run dev with target and hints Source: https://github.com/helgesverre/dev/blob/main/website/index.html Shows the basic usage of the dev command with a target path and hints. The output displays the selected command and its context. ```bash $ dev run ./apps/web vite frontend › pnpm run dev (vite, ~/code/acme/apps/web) ``` -------------------------------- ### Run tests, QA, and benchmarks with just Source: https://github.com/helgesverre/dev/blob/main/README.md Run the project's test suite, quality assurance checks, and benchmarks using the `just` command runner. `just qa` runs formatting checks, Clippy with warnings denied, and the nextest suite; `just bench` builds the release binary and checks performance ceilings. Doctests are intentionally not part of the project. ```console just test just qa just bench ``` -------------------------------- ### Run verification commands Source: https://github.com/helgesverre/dev/blob/main/docs/adding-a-detector.md Run these commands to verify the detector: 'just qa', 'just bench' (required for measured paths), and 'git diff --check'. Then inspect the full diff and report verification by layer. ```console just qa just bench # required for measured paths git diff --check ``` -------------------------------- ### dev CLI usage syntax Source: https://github.com/helgesverre/dev/blob/main/README.md Shows the general command-line syntax for the dev tool. Targets must be path-like (e.g., ./apps/web or ../service); other words are retrieval hints. Use -C or --at for explicit paths. ```text dev [options] [target] [hint ...] [-- passthrough ...] ``` -------------------------------- ### Minimal Detector implementation for ExampleDetector Source: https://github.com/helgesverre/dev/blob/main/docs/adding-a-detector.md Outlines a minimal manifest-backed detector. It checks the intent is Build, iterates indexed files for example.toml, and emits a candidate with build action. Use context.index.all_entries() and context.index.manifests.read() instead of direct filesystem access. This is an outline, not a substitute for verified ecosystem semantics. ```rust use std::path::Path; use crate::candidate::{Evidence, EvidenceKind, SearchDocument, SelectionPolicy}; use crate::intent::Intent; use crate::registry::{EXAMPLE_SOURCE, EXAMPLE_TOOL}; use crate::scan::IndexedFileType; use super::{CandidateBuilder, Detection, Detector, ScanCtx}; pub struct ExampleDetector; impl Detector for ExampleDetector { fn detect(&self, context: &ScanCtx<'_>) -> Detection { if context.invocation.intent != Intent::Build { return Detection::default(); } let mut output = Detection::default(); for entry in context.index.all_entries().filter(|entry| { entry.file_type == IndexedFileType::File && entry .relative_path .file_name() .is_some_and(|name| name == "example.toml") }) { let manifest = context.roots.scan_root.join(&entry.relative_path); let directory = manifest.parent().unwrap_or(Path::new(".")).to_path_buf(); let scope = entry .relative_path .parent() .filter(|path| !path.as_os_str().is_empty()) .map_or_else( || ".".to_string(), |path| path.to_string_lossy().replace(['/', '\\'], ":"), ); let description = "Builds the declared Example project"; CandidateBuilder::tool_default( EXAMPLE_SOURCE, Intent::Build, directory.clone(), "build", ) .action_key(format!("example:{scope}:build")) .tool(EXAMPLE_TOOL) .args(["build"]) .cwd(directory) .selection(SelectionPolicy::Automatic) .base_points(95) .evidence(Evidence { kind: EvidenceKind::Manifest, reason: "example.toml declares an Example project".to_owned(), points: 0, source: Some(entry.relative_path.clone()), }) .search(SearchDocument { identities: vec!["build".to_owned()], target_paths: vec![entry.relative_path.clone()], scopes: vec![scope], text: vec![description.to_owned()], ..SearchDocument::default() }) .label("Example build") .description(description) .emit(&mut output); } output } } ``` -------------------------------- ### dev [options] [target] [hint ...] [-- passthrough ...] Source: https://github.com/helgesverre/dev/blob/main/README.md The primary dev command for running, building, or testing a target. Targets must be path-like; other words are retrieval hints. Use -C or --at for explicit paths. Arguments after -- are forwarded without re-parsing. ```APIDOC ## dev [options] [target] [hint ...] [-- passthrough ...] ### Description Runs, builds, or tests a target. Targets must be path-like (e.g., `./apps/web` or `../service`). Other words are retrieval hints. Use `-C` or `--at` for explicit paths. Arguments after `--` are forwarded to the selected command without shell re-parsing. ### Method CLI ### Endpoint `dev [options] [target] [hint ...] [-- passthrough ...]` ### Parameters #### Options - **-C, --at** (string) - Optional - Explicit path to the target directory. - **--list** (flag) - Optional - List candidate commands without executing. - **--why** (flag) - Optional - Show why a candidate was selected. - **--json** (flag) - Optional - Output results in JSON format. - **--dry-run** (flag) - Optional - Show what would be executed without running. - **--chaos** (integer) - Optional - Discovery mode: 0 for declared commands only, 2 for broader bounded scan. Default is 1 (typo-tolerant). #### Positional Arguments - **target** (string) - Optional - Path-like target (e.g., `./apps/web`). - **hint** (string) - Optional - Retrieval hints for typo-tolerant matching. #### Passthrough Arguments - **--** (string) - Optional - Everything after `--` is forwarded to the selected command without re-parsing. ### Request Example ```console dev test --at ./apps/api participant ``` ### Response #### Success Response - **exit code** (integer) - 0 on success, non-zero on failure. #### Response Example ```console dev run --list dev run vite frontend --why dev test --json dev build --dry-run -- --release ``` ### Error Handling - If no target is found, an error is returned. - If `--chaos 0` is set, only declared commands are considered. - Broader discovery never permits arbitrary command generation. ``` -------------------------------- ### Run just test, detector-check, qa, and bench Source: https://github.com/helgesverre/dev/blob/main/CONTRIBUTING.md Run the project's standard development commands. Requires Rust 1.85 or newer, just, and cargo-nextest. The qa command combines formatting check, Clippy with -D warnings, and nextest; bench runs the release-mode performance suite. ```console just test # run unit and integration tests with nextest just detector-check # enforce detector registration and discovery invariants just qa # formatting check + Clippy -D warnings + nextest just bench # release-mode performance suite ``` -------------------------------- ### Run command with broad search and chaos flag Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Runs the run command with the --chaos flag and a broad search. The broad target index finds tools/legacy_importer.php, and the PHP runner creates a synthetic ExplicitHint candidate that may auto-run only if the file identity match clears the automatic quality threshold. ```console dev run --chaos 2 legacy importer ``` -------------------------------- ### Manage dev cache with list and clear Source: https://github.com/helgesverre/dev/blob/main/README.md Inspect or clear remembered picker choices for the same project shape and invocation. ```console dev cache list ``` ```console dev cache clear ``` -------------------------------- ### Execute tasks with Jake, Taskfile, and mise Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Execution commands for Jake, Taskfile, and mise facades. Jake uses the case-sensitive Jakefile, Taskfile uses standard spellings, and mise uses mise.toml variants. These commands are used to run declared project tasks. ```text jake -f -- ``` ```text task --taskfile -- ``` ```text mise run -- ``` -------------------------------- ### Inspect dev resolution with --list, --why, --json, --dry-run Source: https://github.com/helgesverre/dev/blob/main/README.md Inspect resolution without executing anything. --list shows candidates, --why explains selection, --json outputs structured data, and --dry-run previews the command. None of these flags execute the candidate. ```console dev run --list ``` ```console dev run vite frontend --why ``` ```console dev test --json ``` ```console dev build --dry-run -- --release ``` -------------------------------- ### Run Just recipe with explicit Justfile Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Executes a Just recipe using the exact discovered Justfile. The absolute path to the Justfile is required, and the recipe name follows. This command is used for running recipes after discovery, which parses the Justfile without invoking any Just commands. ```text just --justfile ``` -------------------------------- ### Inspect decision with --why Source: https://github.com/helgesverre/dev/blob/main/website/index.html Shows the `--why` flag output, which explains the decision, query match, and structural evidence. ```bash $ dev run vite --why Decision selected Vite dev server command pnpm run dev Query match vite → framework scope / exact Structural evidence vite.config.ts “dev” script in package.json pnpm-lock.yaml ``` -------------------------------- ### Package manager run command forms Source: https://github.com/helgesverre/dev/blob/main/docs/spec.md Representative command forms for running package scripts with each supported package manager. These are used for integration fixtures and must be constructed with argv arrays, not shell strings. ```text npm run