Improve cellc CLI diagnostics

Author: a19q3

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## 0.20.0-nightly - 2026-06-19
 
+- Bring `cellc` CLI discovery and direct-source diagnostics closer to Rust's
+  developer experience: top-level help now shows package commands plus direct
+  compile mode, `cellc --list` enumerates commands, unknown bare commands get
+  nearest-command suggestions, and direct parse/lex/compile errors print
+  `file:line:column` source snippets.
 - Fix numeric-width soundness by requiring exact non-literal numeric type
   equality while preserving declared integer literal widths through type
   checking and IR lowering.

Cargo.toml

@@ -27,10 +27,13 @@ repository = "https://github.com/CellScript-Labs/CellScript"
 exclude = [
     ".audit-report*.md",
     ".cap/",
+    ".codex/",
     ".gitignore",
+    ".gitmodules",
     ".playwright-mcp/",
     ".rustfmt.toml",
     ".github/",
+    "AGENTS.md",
     "BRANCHES.md",
     "README_REVIEW.md",
     "cellscript-*.png",
@@ -39,6 +42,7 @@ exclude = [
     "editors/",
     "proposals/",
     "scripts/__pycache__/",
+    "services/",
     "src/bin/",
     "tools/",
     "website/",

docs/wiki/Tutorial-01-Getting-Started.md

@@ -48,15 +48,21 @@ Or call the built binary directly:
 
 Both forms are useful. `cargo run` is convenient while developing the compiler.
 The direct binary is closer to how users call `cellc` after installation.
-The top-level help shows the legacy direct single-file compiler flags. Package
-commands have their own help pages:
+The top-level help shows both direct source mode and the package command surface.
+Package commands have their own help pages:
 
 ```bash
 ./target/debug/cellc build --help
 ./target/debug/cellc check --help
 ./target/debug/cellc init --help
 ```
 
+To list every package command without the direct source options, use:
+
+```bash
+./target/debug/cellc --list
+```
+
 ## Compile One Source File
 
 Start with `examples/token.cell`. It is small, but it already shows the main

scripts/cellscript_gate.sh

@@ -27,6 +27,16 @@ run() {
     "$@"
 }
 
+cargo_fmt_workspace() {
+    run cargo fmt \
+        --manifest-path "$ROOT_DIR/Cargo.toml" \
+        --package cellscript \
+        --package cellscript-ckb-adapter \
+        --package cellscript-wasm \
+        --package cellscript-ckb-sdk-builder-example \
+        "$@"
+}
+
 python_syntax_check() {
     python3 - "$@" <<'PY'
 import sys
@@ -574,7 +584,7 @@ run_dev_gate() {
     require_cmd python3
     require_cmd rg
 
-    run cargo fmt --all
+    cargo_fmt_workspace
     run cargo check --locked -p cellscript --all-targets
     run ./scripts/cellscript_strict_backend_audit.sh quick
     run ./scripts/cellscript_syntax_combo_audit.sh quick
@@ -593,7 +603,7 @@ run_ci_gate() {
     require_cmd npm
 
     printf '{"status":"not-generated","reason":"test suite did not reach backend shape report generation"}\n' >"$CELLSCRIPT_BACKEND_SHAPE_REPORT"
-    run cargo fmt --all --check
+    cargo_fmt_workspace --check
     run cargo test --locked -p cellscript -- --test-threads=1
     run cargo clippy --locked -p cellscript --all-targets -- -D warnings
     run ./scripts/cellscript_strict_backend_audit.sh ci
@@ -615,7 +625,7 @@ run_backend_gate() {
     require_cmd python3
     require_cmd rg
 
-    run cargo fmt --all --check
+    cargo_fmt_workspace --check
     run cargo check --locked -p cellscript --all-targets
     run cargo test --locked -p cellscript
     run cargo clippy --locked -p cellscript --all-targets -- -D warnings

src/cli/commands.rs

@@ -10657,9 +10657,13 @@ pub struct CliParser;
 
 impl CliParser {
     pub fn parse() -> Command {
+        Self::parse_matches(Self::command().get_matches())
+    }
+
+    pub fn command() -> clap::Command {
         use clap::{Arg, ArgAction, Command as ClapCommand};
 
-        let matches = ClapCommand::new("cellc")
+        ClapCommand::new("cellc")
             .version(crate::VERSION)
             .about("CellScript compiler for CKB blockchain")
             .subcommand_required(true)
@@ -11584,8 +11588,9 @@ impl CliParser {
                     .arg(Arg::new("name").long("name").required(true).value_name("NAME").help("Package name"))
                     .arg(Arg::new("source").long("source").required(true).value_name("URL").help("Source repository URL")),
             )
-            .get_matches();
+    }
 
+    fn parse_matches(matches: clap::ArgMatches) -> Command {
         match matches.subcommand() {
             Some(("build", m)) => Command::Build(BuildArgs {
                 release: m.get_flag("release"),