dirsql 0.4.75__tar.gz → 0.4.77__tar.gz

{dirsql-0.4.75 → dirsql-0.4.77}/Cargo.lock

@@ -552,7 +552,7 @@ checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
 
 [[package]]
 name = "dirsql"
-version = "0.4.75"
+version = "0.4.77"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -577,6 +577,7 @@ dependencies = [
  "regex",
  "reqwest",
  "rusqlite",
+ "rustix",
  "serde",
  "serde_json",
  "shlex",
@@ -601,7 +602,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.75"
+version = "0.4.77"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.75 → dirsql-0.4.77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.75
+Version: 0.4.77
 Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

{dirsql-0.4.75 → dirsql-0.4.77}/docs/.vitepress/config.ts

@@ -65,7 +65,8 @@ export default defineConfig({
             { text: 'Keep the index across restarts', link: '/howto/persist' },
             { text: 'React to file changes', link: '/howto/react-to-changes' },
             { text: 'Write a plugin', link: '/howto/write-a-plugin' },
-            { text: 'Embed dirsql in your application', link: '/howto/embed' }
+            { text: 'Embed dirsql in your application', link: '/howto/embed' },
+            { text: 'Give your agent the dirsql skill', link: '/howto/agent-skill' }
           ]
         },
         {

dirsql-0.4.77/docs/howto/agent-skill.md

@@ -0,0 +1,64 @@
+# Give your coding agent the `dirsql` skill
+
+Your coding agent answers questions about many files by reading them one at a
+time. The `dirsql` skill teaches it to write one SQL query instead.
+
+## What it does
+
+The skill is a short `SKILL.md`. Its description tells the agent when to use
+it: counting, grouping or aggregating files, "which files are ..." by size,
+mtime or extension, pulling one field out of many JSON or frontmatter files,
+or comparing two directories. It tells the agent not to use it to read one
+known file, hunt for a literal string, or list a few names.
+
+When the skill triggers, the agent runs `dirsql context`. That prints a guide
+(usage, recipes, troubleshooting) compiled into the `dirsql` binary, so the
+agent always reads the guide for the version it is about to run. See
+[`dirsql context`](../reference/cli.md#dirsql-context).
+
+## Install
+
+```bash
+npx skills add thekevinscott/dirsql
+```
+
+This uses [`skills`](https://www.npmjs.com/package/skills), a cross-agent
+skill installer. It installs for the current project by default. Pass `-g` to
+install for your user instead, `-a <agent>` to name
+agents (repeatable), and `-y` to skip the prompts.
+
+| Scope | Skill lands in | Claude Code link |
+|---|---|---|
+| Project (default) | `.agents/skills/dirsql` | `.claude/skills/dirsql` |
+| User (`-g`) | `~/.agents/skills/dirsql` | `~/.claude/skills/dirsql` |
+
+Codex, Cursor, Gemini CLI, Amp, Cline and other agents that read
+`.agents/skills` use the shared copy directly. Agents with their own skills
+directory, such as Claude Code, get a symlink to it (`--copy` copies instead).
+`npx skills add --help` lists the rest.
+
+## Runners
+
+The skill works with whichever runner you have. Its `allowed-tools` lets the
+agent run these commands without a permission prompt:
+
+| Runner | Command the agent runs |
+|---|---|
+| `uv` | `uvx dirsql ...` |
+| `npm` | `npx -y dirsql ...` |
+| `cargo` | `dirsql ...` after `cargo install dirsql --features cli` |
+
+The grant is `Bash(uvx dirsql:*)`, `Bash(npx -y dirsql:*)` and
+`Bash(dirsql:*)`.
+
+## Check, update, remove
+
+```bash
+npx skills list        # installed skills and their agents (-g for user scope)
+npx skills update      # refresh to the latest from GitHub
+npx skills remove dirsql
+```
+
+`update` and `remove` accept `-g` for user scope and `-y` to skip prompts.
+The skill itself never needs updating to match the CLI, since the guide comes
+from the installed `dirsql`.

{dirsql-0.4.75 → dirsql-0.4.77}/docs/reference/cli.md

@@ -454,12 +454,7 @@ troubleshooting. The guide is compiled into the binary, so it describes the
 version that prints it. It takes no flags and exits `0`.
 
 The dirsql agent skill tells an agent to run this command before it writes a
-query. Install the skill into Claude Code, Codex, Cursor, Gemini CLI and
-others with:
-
-```sh
-npx skills add thekevinscott/dirsql
-```
+query; see [the skill page](../howto/agent-skill.md).
 
 ## Plugins
 

{dirsql-0.4.75 → dirsql-0.4.77}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.4.75"
+version = "0.4.77"
 # abi3 note: the `abi3-py310` pyo3 feature (below) builds ONE stable-ABI
 # `cp310-abi3` wheel per platform that loads on every CPython >= 3.10
 # (matching `pyproject.toml`'s `requires-python = ">=3.10"`), instead of

{dirsql-0.4.75 → dirsql-0.4.77}/packages/python/docs/.vitepress/config.ts

@@ -65,7 +65,8 @@ export default defineConfig({
             { text: 'Keep the index across restarts', link: '/howto/persist' },
             { text: 'React to file changes', link: '/howto/react-to-changes' },
             { text: 'Write a plugin', link: '/howto/write-a-plugin' },
-            { text: 'Embed dirsql in your application', link: '/howto/embed' }
+            { text: 'Embed dirsql in your application', link: '/howto/embed' },
+            { text: 'Give your agent the dirsql skill', link: '/howto/agent-skill' }
           ]
         },
         {

dirsql-0.4.77/packages/python/docs/howto/agent-skill.md

@@ -0,0 +1,64 @@
+# Give your coding agent the `dirsql` skill
+
+Your coding agent answers questions about many files by reading them one at a
+time. The `dirsql` skill teaches it to write one SQL query instead.
+
+## What it does
+
+The skill is a short `SKILL.md`. Its description tells the agent when to use
+it: counting, grouping or aggregating files, "which files are ..." by size,
+mtime or extension, pulling one field out of many JSON or frontmatter files,
+or comparing two directories. It tells the agent not to use it to read one
+known file, hunt for a literal string, or list a few names.
+
+When the skill triggers, the agent runs `dirsql context`. That prints a guide
+(usage, recipes, troubleshooting) compiled into the `dirsql` binary, so the
+agent always reads the guide for the version it is about to run. See
+[`dirsql context`](../reference/cli.md#dirsql-context).
+
+## Install
+
+```bash
+npx skills add thekevinscott/dirsql
+```
+
+This uses [`skills`](https://www.npmjs.com/package/skills), a cross-agent
+skill installer. It installs for the current project by default. Pass `-g` to
+install for your user instead, `-a <agent>` to name
+agents (repeatable), and `-y` to skip the prompts.
+
+| Scope | Skill lands in | Claude Code link |
+|---|---|---|
+| Project (default) | `.agents/skills/dirsql` | `.claude/skills/dirsql` |
+| User (`-g`) | `~/.agents/skills/dirsql` | `~/.claude/skills/dirsql` |
+
+Codex, Cursor, Gemini CLI, Amp, Cline and other agents that read
+`.agents/skills` use the shared copy directly. Agents with their own skills
+directory, such as Claude Code, get a symlink to it (`--copy` copies instead).
+`npx skills add --help` lists the rest.
+
+## Runners
+
+The skill works with whichever runner you have. Its `allowed-tools` lets the
+agent run these commands without a permission prompt:
+
+| Runner | Command the agent runs |
+|---|---|
+| `uv` | `uvx dirsql ...` |
+| `npm` | `npx -y dirsql ...` |
+| `cargo` | `dirsql ...` after `cargo install dirsql --features cli` |
+
+The grant is `Bash(uvx dirsql:*)`, `Bash(npx -y dirsql:*)` and
+`Bash(dirsql:*)`.
+
+## Check, update, remove
+
+```bash
+npx skills list        # installed skills and their agents (-g for user scope)
+npx skills update      # refresh to the latest from GitHub
+npx skills remove dirsql
+```
+
+`update` and `remove` accept `-g` for user scope and `-y` to skip prompts.
+The skill itself never needs updating to match the CLI, since the guide comes
+from the installed `dirsql`.

{dirsql-0.4.75/packages/rust → dirsql-0.4.77/packages/python}/docs/reference/cli.md

@@ -454,12 +454,7 @@ troubleshooting. The guide is compiled into the binary, so it describes the
 version that prints it. It takes no flags and exits `0`.
 
 The dirsql agent skill tells an agent to run this command before it writes a
-query. Install the skill into Claude Code, Codex, Cursor, Gemini CLI and
-others with:
-
-```sh
-npx skills add thekevinscott/dirsql
-```
+query; see [the skill page](../howto/agent-skill.md).
 
 ## Plugins
 

dirsql-0.4.77/packages/python/e2e-attestations/claude-1305-glob-speed.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1791292687,
+  "exit_code": 0,
+  "commit": "59f2b4249816735553d8a2270ded77fc4f9c3e2c",
+  "branch": "claude/1305-glob-speed"
+}

dirsql-0.4.77/packages/python/e2e-attestations/claude-1308-glob-speed.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1791268015,
+  "exit_code": 0,
+  "commit": "0cfba3aeec10eac3af444896624084f3432aadaf",
+  "branch": "claude/1308-glob-speed"
+}

dirsql-0.4.77/packages/python/e2e-attestations/claude-1310-glob-speed.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1791258925,
+  "exit_code": 0,
+  "commit": "a94c48568f24ccb64acd024d4b6db7f9f2897435",
+  "branch": "claude/1310-glob-speed"
+}

dirsql-0.4.77/packages/python/e2e-attestations/claude-1311-glob-speed.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1791262582,
+  "exit_code": 0,
+  "commit": "5dfbe50e4b422eddb2e849841bff78a49946de94",
+  "branch": "claude/1311-glob-speed"
+}

dirsql-0.4.77/packages/python/e2e-attestations/claude-1312-glob-speed.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1791265213,
+  "exit_code": 0,
+  "commit": "0fdecf55fbc4c3d7ca1623865ec804fdfb196979",
+  "branch": "claude/1312-glob-speed"
+}

dirsql-0.4.77/packages/python/e2e-attestations/claude-1318-lazy-stat.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/ -q --deselect tests/e2e/glob_speed_one_level_test.py",
+  "ran_at": 1791234677,
+  "exit_code": 0,
+  "commit": "3d5645d54f19c86ce3fa2ce75d9a8392450b19e4",
+  "branch": "claude/1318-lazy-stat"
+}

dirsql-0.4.77/packages/python/e2e-attestations/claude-1320-walk-speed.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/ -q --deselect tests/e2e/glob_speed_one_level_test.py",
+  "ran_at": 1791238784,
+  "exit_code": 0,
+  "commit": "da4c59800ef0c252699acc078738b1b5332dd751",
+  "branch": "claude/1320-walk-speed"
+}

dirsql-0.4.77/packages/python/e2e-attestations/claude-1322-walk-readdir.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/ -q --deselect tests/e2e/glob_speed_one_level_test.py",
+  "ran_at": 1791239586,
+  "exit_code": 0,
+  "commit": "5320f737098f6359ba10e35cbab508be367116bc",
+  "branch": "claude/1322-walk-readdir"
+}

dirsql-0.4.77/packages/python/e2e-attestations/claude-1325-parallel-walk.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1791242399,
+  "exit_code": 0,
+  "commit": "05c2e1ad49fa161f2538efdad2c7e42468f001a7",
+  "branch": "claude/1325-parallel-walk"
+}

dirsql-0.4.77/packages/python/e2e-attestations/claude-1326-stream-rows.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1791241697,
+  "exit_code": 0,
+  "commit": "55ef5b88f40ba4a5568f1fed86a784caf8129cd7",
+  "branch": "claude/1326-stream-rows"
+}

{dirsql-0.4.75 → dirsql-0.4.77}/packages/python/testing-conventions.toml

@@ -7,7 +7,7 @@
 # through it (#721), so every e2e case crosses it. packages/ts/napi is not: it
 # cannot reach this suite.
 [e2e]
-extra_scope = ["packages/rust/src", "packages/python/src"]
+extra_scope = ["packages/rust/src", "packages/python/src", "packages/python/tests/e2e"]
 
 # Same floor as the root file, which this lane no longer reads.
 [python.coverage]

{dirsql-0.4.75 → dirsql-0.4.77}/packages/rust/Cargo.toml

@@ -6,7 +6,7 @@ description = "Ephemeral SQL index over a local directory"
 # version stays for the binding crates (publish = false). The literal
 # intentionally lags the published version: putitoutthere rewrites it to
 # the planned release version at build time and never commits it back.
-version = "0.4.75"
+version = "0.4.77"
 edition.workspace = true
 # Literal `license` (not `license.workspace = true`) because
 # putitoutthere's preflight check reads `[package].license` directly
@@ -89,6 +89,10 @@ tokio-stream = { version = "0.1", features = ["sync"], optional = true }
 toml = "0.8"
 typed-path = "0.12"
 
+# Reads a directory's names into one buffer instead of one allocation each.
+[target.'cfg(unix)'.dependencies]
+rustix = { version = "1", features = ["fs"] }
+
 [lints.rust]
 # `deny`, not `forbid`: rusqlite's API imposes five unavoidable `unsafe`
 # sites (the `load_extension` guard and four `unsafe impl VTab`/`VTabCursor`).

dirsql-0.4.77/packages/rust/docs/howto/agent-skill.md

@@ -0,0 +1,64 @@
+# Give your coding agent the `dirsql` skill
+
+Your coding agent answers questions about many files by reading them one at a
+time. The `dirsql` skill teaches it to write one SQL query instead.
+
+## What it does
+
+The skill is a short `SKILL.md`. Its description tells the agent when to use
+it: counting, grouping or aggregating files, "which files are ..." by size,
+mtime or extension, pulling one field out of many JSON or frontmatter files,
+or comparing two directories. It tells the agent not to use it to read one
+known file, hunt for a literal string, or list a few names.
+
+When the skill triggers, the agent runs `dirsql context`. That prints a guide
+(usage, recipes, troubleshooting) compiled into the `dirsql` binary, so the
+agent always reads the guide for the version it is about to run. See
+[`dirsql context`](../reference/cli.md#dirsql-context).
+
+## Install
+
+```bash
+npx skills add thekevinscott/dirsql
+```
+
+This uses [`skills`](https://www.npmjs.com/package/skills), a cross-agent
+skill installer. It installs for the current project by default. Pass `-g` to
+install for your user instead, `-a <agent>` to name
+agents (repeatable), and `-y` to skip the prompts.
+
+| Scope | Skill lands in | Claude Code link |
+|---|---|---|
+| Project (default) | `.agents/skills/dirsql` | `.claude/skills/dirsql` |
+| User (`-g`) | `~/.agents/skills/dirsql` | `~/.claude/skills/dirsql` |
+
+Codex, Cursor, Gemini CLI, Amp, Cline and other agents that read
+`.agents/skills` use the shared copy directly. Agents with their own skills
+directory, such as Claude Code, get a symlink to it (`--copy` copies instead).
+`npx skills add --help` lists the rest.
+
+## Runners
+
+The skill works with whichever runner you have. Its `allowed-tools` lets the
+agent run these commands without a permission prompt:
+
+| Runner | Command the agent runs |
+|---|---|
+| `uv` | `uvx dirsql ...` |
+| `npm` | `npx -y dirsql ...` |
+| `cargo` | `dirsql ...` after `cargo install dirsql --features cli` |
+
+The grant is `Bash(uvx dirsql:*)`, `Bash(npx -y dirsql:*)` and
+`Bash(dirsql:*)`.
+
+## Check, update, remove
+
+```bash
+npx skills list        # installed skills and their agents (-g for user scope)
+npx skills update      # refresh to the latest from GitHub
+npx skills remove dirsql
+```
+
+`update` and `remove` accept `-g` for user scope and `-y` to skip prompts.
+The skill itself never needs updating to match the CLI, since the guide comes
+from the installed `dirsql`.

{dirsql-0.4.75/packages/python → dirsql-0.4.77/packages/rust}/docs/reference/cli.md

@@ -454,12 +454,7 @@ troubleshooting. The guide is compiled into the binary, so it describes the
 version that prints it. It takes no flags and exits `0`.
 
 The dirsql agent skill tells an agent to run this command before it writes a
-query. Install the skill into Claude Code, Codex, Cursor, Gemini CLI and
-others with:
-
-```sh
-npx skills add thekevinscott/dirsql
-```
+query; see [the skill page](../howto/agent-skill.md).
 
 ## Plugins
 

{dirsql-0.4.75 → dirsql-0.4.77}/packages/rust/src/cli/execute.rs

@@ -15,7 +15,7 @@ use serde::Deserialize;
 use serde_json::Value;
 
 use super::AppState;
-use super::serialize::result_to_json;
+use super::serialize::{JsonRows, result_to_json};
 use crate::{DirSQL, DirSqlError};
 
 /// Why a query failed, classified independently of transport. The HTTP
@@ -79,6 +79,28 @@ pub async fn execute_query(
     }
 }
 
+/// [`execute_query`] for the one-shot CLI's JSON output: the same intake and
+/// errors, with the rows written as JSON while SQLite yields them. The text
+/// is the `{value}\n` the CLI printed from [`execute_query`]'s array, held
+/// until the statement ends so a failing query still prints no rows.
+pub async fn execute_query_json(
+    state: &AppState,
+    raw_body: String,
+) -> Result<Vec<u8>, QueryFailure> {
+    let sql = parse_sql_body(&raw_body)?;
+    let db = require_ready(state)?;
+    let join = tokio::task::spawn_blocking(move || {
+        db.query_each(&sql, JsonRows::new, JsonRows::row)
+            .map(JsonRows::finish)
+    })
+    .await;
+    match join {
+        Ok(Ok(text)) => Ok(text),
+        Ok(Err(err)) => Err(classify_query_error(err)),
+        Err(join_err) => Err(QueryFailure::Internal(join_err.to_string())),
+    }
+}
+
 /// Await `task`, bounded by `timeout` when one is given ([`QueryFailure::Timeout`]
 /// carrying the bound on expiry) and to completion with `None`.
 async fn run_bounded<T>(

{dirsql-0.4.75 → dirsql-0.4.77}/packages/rust/src/cli/run.rs

@@ -15,11 +15,14 @@
 //! The `dirsql` binary is a shim over [`run_cli`], so `cargo install dirsql
 //! --features cli` and every other entry path run the same code.
 
-use std::io::IsTerminal;
+use std::io::{IsTerminal, Write};
 use std::path::PathBuf;
 
 use super::{
-    AppState, ServerConfig, execute::execute_query, init::InitOptions, repl::run_repl,
+    AppState, ServerConfig,
+    execute::{execute_query, execute_query_json},
+    init::InitOptions,
+    repl::run_repl,
     serve_with_state, table,
 };
 use crate::{DirSQL, Extension, Row, Table};
@@ -336,13 +339,13 @@ pub fn run_cli(argv: Vec<String>) -> i32 {
     let code = runtime.block_on(async {
         match cli.command.take() {
             Some(Command::Init(args)) => run_init(args),
-            Some(Command::Query(args)) => run_query(args).await,
+            Some(Command::Query(args)) => run_query(args, &mut std::io::stdout()).await,
             Some(Command::Server(args)) => run_server(args).await,
             Some(Command::Context) => {
                 print!("{}", super::context::guide());
                 0
             }
-            None => run_default(cli).await,
+            None => run_default(cli, &mut std::io::stdout()).await,
         }
     });
     i32::from(code)
@@ -356,15 +359,18 @@ pub fn run_cli(argv: Vec<String>) -> i32 {
 /// The index is built **once**, before the loop, rather than per statement:
 /// no directory re-scan between statements, and the live watcher keeps it
 /// fresh across them.
-async fn run_default(cli: Cli) -> u8 {
+async fn run_default(cli: Cli, out: &mut impl Write) -> u8 {
     match cli.sql {
         Some(sql) => {
-            run_query(QueryArgs {
-                sql,
-                on_file: cli.on_file,
-                format: cli.format,
-                common: cli.common,
-            })
+            run_query(
+                QueryArgs {
+                    sql,
+                    on_file: cli.on_file,
+                    format: cli.format,
+                    common: cli.common,
+                },
+                out,
+            )
             .await
         }
         None => {
@@ -382,7 +388,7 @@ async fn run_default(cli: Cli) -> u8 {
                 // `StdinLock` is not `Send`, so it cannot cross into the
                 // blocking read; `BufReader<Stdin>` locks per call and can.
                 std::io::BufReader::new(std::io::stdin()),
-                &mut std::io::stdout(),
+                out,
                 &mut std::io::stderr(),
                 std::io::stdin().is_terminal(),
             )
@@ -393,11 +399,11 @@ async fn run_default(cli: Cli) -> u8 {
 
 /// One-shot `dirsql query`: build the index exactly as server mode would
 /// (same `load_state` / hook loading), run the SQL through the shared
-/// [`execute_query`] pipeline, print the result JSON on stdout, and exit.
+/// [`execute_query`] pipeline, write the result to `out`, and exit.
 /// Any [`QueryFailure`](super::execute::QueryFailure) prints its
 /// message — the same string the HTTP `{"error": …}` body carries — to
 /// stderr with a non-zero exit.
-async fn run_query(args: QueryArgs) -> u8 {
+async fn run_query(args: QueryArgs, out: &mut dyn Write) -> u8 {
     let parser = match resolve_on_file(&args.on_file) {
         Ok(parser) => parser,
         Err(message) => {
@@ -411,9 +417,17 @@ async fn run_query(args: QueryArgs) -> u8 {
     // natively; only the long-lived server enforces `query_timeout` (408).
     let format = args.format.resolve(std::io::stdout().is_terminal());
 
-    match execute_query(&state, query_body(&args.sql), None).await {
-        Ok(value) => {
-            print!("{}", render_rows(&value, format));
+    let printed = match format {
+        Format::Table => execute_query(&state, query_body(&args.sql), None)
+            .await
+            .map(|value| render_rows(&value, format).into_bytes()),
+        _ => execute_query_json(&state, query_body(&args.sql)).await,
+    };
+    match printed {
+        Ok(text) => {
+            // A closed pipe (`| head`) is the reader's choice, not a failure.
+            let _ = out.write_all(&text);
+            let _ = out.flush();
             0
         }
         Err(failure) => {
@@ -664,6 +678,59 @@ mod tests {
         assert_eq!(query_body("   "), r#"{"sql":"   "}"#);
     }
 
+    fn query_args(argv: &[&str]) -> QueryArgs {
+        match Cli::parse_from(argv).command {
+            Some(Command::Query(args)) => args,
+            other => panic!("expected a query subcommand, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn run_query_writes_the_rows_as_json_and_exits_zero() {
+        let mut out = Vec::new();
+        let args = query_args(&[
+            "dirsql",
+            "query",
+            "--format",
+            "json",
+            "SELECT 1 AS a, 'x' AS b",
+        ]);
+        assert_eq!(run_query(args, &mut out).await, 0);
+        assert_eq!(out, b"[{\"a\":1,\"b\":\"x\"}]\n");
+    }
+
+    #[tokio::test]
+    async fn run_query_writes_the_rows_as_a_table_when_asked() {
+        let mut out = Vec::new();
+        let args = query_args(&["dirsql", "query", "--format", "table", "SELECT 1 AS a"]);
+        assert_eq!(run_query(args, &mut out).await, 0);
+        assert_eq!(out, b"a\n-\n1\n\n1 row\n");
+    }
+
+    #[tokio::test]
+    async fn run_query_exits_one_and_writes_nothing_when_the_query_fails() {
+        let mut out = Vec::new();
+        let args = query_args(&["dirsql", "query", "--format", "json", "SELECT nope"]);
+        assert_eq!(run_query(args, &mut out).await, 1);
+        assert!(out.is_empty());
+    }
+
+    #[tokio::test]
+    async fn run_default_runs_its_sql_as_a_one_shot_query() {
+        let mut out = Vec::new();
+        let cli = Cli::parse_from(["dirsql", "--format", "json", "SELECT 1 AS a"]);
+        assert_eq!(run_default(cli, &mut out).await, 0);
+        assert_eq!(out, b"[{\"a\":1}]\n");
+    }
+
+    #[tokio::test]
+    async fn run_default_exits_one_when_its_sql_fails() {
+        let mut out = Vec::new();
+        let cli = Cli::parse_from(["dirsql", "--format", "json", "SELECT nope"]);
+        assert_eq!(run_default(cli, &mut out).await, 1);
+        assert!(out.is_empty());
+    }
+
     /// The `ConfigArgs` parsed from a `query` subcommand invocation (#609:
     /// config flags are subcommand-local, so they live on the Query variant).
     fn query_common(argv: &[&str]) -> ConfigArgs {