feat: Rework turbo ls to use query internals and add turbo query ls shorthand (#12424)

## Summary

- **Refactors `turbo ls`** to execute GraphQL queries through the
`QueryServer` instead of directly querying the package graph. This keeps
`ls` in sync with `turbo query` semantics and eliminates duplicate
querying logic.
- **Adds `turbo query ls`** as a new shorthand subcommand with the same
flags as `turbo ls` (`--filter`, `--affected`, `--output`, positional
packages).
- **Documents `turbo query ls`** in the query reference page.

## How it works

`ls::run()` now accepts a `&dyn QueryServer` and uses it to execute two
types of GraphQL queries:
- `{ packages { items { name path } length } }` for listing packages
- `{ package(name: "...") { ... tasks, allDependencies, allDependents
... } }` for package details

Filter/affected flags still flow through `RunBuilder` via `Opts` — the
filtered package set is captured before the `Run` is wrapped as `Arc<dyn
QueryRun>`, then used to filter the GraphQL results.

`turbo query ls` is handled early in `query::run()` (before the
general-purpose query Run is constructed) since it needs its own Run
with filter opts.

Closes #11144
Closes #10869

Author: anthonyshew

apps/docs/content/docs/reference/query.mdx

@@ -41,6 +41,66 @@ turbo query query.gql
 
 Shorthands generate GraphQL queries for common operations so you don't need to write them by hand. The JSON output is identical to what you'd get from a raw query.
 
+### `ls`
+
+List packages in your monorepo. This is a shorthand for a `packages` query, equivalent to `turbo ls`.
+
+```bash title="Terminal"
+turbo query ls [packages] [flags]
+```
+
+With no arguments, lists all packages:
+
+```bash title="Terminal"
+turbo query ls
+```
+
+```json title="Output"
+{
+  "packageManager": "npm",
+  "packages": {
+    "count": 3,
+    "items": [
+      { "name": "docs", "path": "apps/docs" },
+      { "name": "ui", "path": "packages/ui" },
+      { "name": "web", "path": "apps/web" }
+    ]
+  }
+}
+```
+
+When passed package names, returns detailed information including tasks, dependencies, and dependents:
+
+```bash title="Terminal"
+turbo query ls web
+```
+
+#### `--filter` (`-F`)
+
+Use pnpm-style package selectors to narrow the package list. Same syntax as [`turbo run --filter`](/docs/reference/command-line-reference/run#--filter).
+
+```bash title="Terminal"
+turbo query ls --filter=web...
+turbo query ls -F my-app...
+```
+
+#### `--affected`
+
+Show only packages affected by changes between the current branch and `main`. Cannot be combined with `--filter`.
+
+```bash title="Terminal"
+turbo query ls --affected
+```
+
+#### `--output`
+
+Control the output format. Defaults to `pretty` (human-readable).
+
+```bash title="Terminal"
+turbo query ls --output json
+turbo query ls --output pretty
+```
+
 ### `affected`
 
 Check which packages or tasks are affected by changes between two git refs.

crates/turborepo-lib/src/cli/mod.rs

@@ -886,6 +886,28 @@ pub enum QuerySubcommand {
     /// Check which packages or tasks are affected by changes between two git
     /// refs
     Affected(AffectedArgs),
+    /// List packages in your monorepo (shorthand for a packages query)
+    Ls(LsArgs),
+}
+
+#[derive(clap::Args, Clone, Debug, PartialEq)]
+pub struct LsArgs {
+    /// Show only packages that are affected by changes between
+    /// the current branch and `main`
+    #[clap(long, group = "scope-filter-group")]
+    pub affected: bool,
+    /// Use the given selector to specify package(s) to act as
+    /// entry points. The syntax mirrors pnpm's syntax, and
+    /// additional documentation and examples can be found in
+    /// turbo's documentation https://turborepo.dev/docs/reference/command-line-reference/run#--filter
+    #[clap(short = 'F', long, group = "scope-filter-group")]
+    pub filter: Vec<String>,
+    /// Get insight into a specific package, such as
+    /// its dependencies and tasks
+    pub packages: Vec<String>,
+    /// Output format
+    #[clap(long, value_enum)]
+    pub output: Option<OutputFormat>,
 }
 
 #[derive(clap::Args, Clone, Debug, PartialEq)]
@@ -1636,14 +1658,17 @@ async fn run_main(
         Command::Ls {
             packages, output, ..
         } => {
+            let Some(ref query_server) = query_server else {
+                return Err(error::Error::QueryNotAvailable);
+            };
             let event = CommandEventBuilder::new("info").with_parent(&root_telemetry);
 
             event.track_call();
             let output = *output;
             let packages = packages.clone();
             let base = CommandBase::new(cli_args, repo_root, version, color_config)?;
             event.track_ui_mode(base.opts.run_opts.ui_mode);
-            ls::run(base, packages, event, output).await?;
+            ls::run(base, packages, event, output, query_server.as_ref()).await?;
 
             Ok(0)
         }