[AI] Make yaml input inline-only and clarify query source options

Author: intellectronica

AGENTS.md

@@ -111,6 +111,7 @@ When asked to create commits in this repository:
 - CSV serialisation uses the selected/declared column list as the canonical header order.
 - View `order` is treated as projected column order; row sorting is driven by `sort`.
 - When no explicit columns are configured, projected columns are inferred from matched note frontmatter keys (with `file.name` first).
+- `--yaml`/`yaml` accepts inline YAML text only; file paths must use `--base`/`basePath`.
 
 ## Decision Log
 
@@ -133,3 +134,8 @@ When asked to create commits in this repository:
   - Context: Real `.base` files depend on `order` for visible columns and often use frontmatter keys containing spaces.
   - Decision: Treat `view.order` as column projection order, keep `view.sort` for row ordering, infer columns when unspecified, and resolve non-expression property names directly from note data.
   - Consequence: Query output now includes expected Base properties instead of falling back to `file.name`/`file.path` defaults.
+
+- 2026-02-18 - Inline-only YAML option semantics
+  - Context: `--yaml` overlapped with `--base` by auto-detecting file paths, which created ambiguous query source behavior.
+  - Decision: Restrict `--yaml`/`yaml` to inline YAML text and reject path-like input with guidance to use `--base`/`basePath`.
+  - Consequence: CLI and library query-source semantics are clearer and avoid accidental mode switching based on filesystem state.

README.md

@@ -43,7 +43,7 @@ There is one command surface; all behavior is controlled through options.
 `mdbasequery` supports three ways to provide the query definition:
 
 1. `.base` file via `--base <path>`
-2. YAML via `--yaml <string-or-path>`
+2. Inline YAML via `--yaml <yaml-text>`
 3. Flag-built query mode (`--filter`, `--select`, `--sort`, etc.)
 
 If `--base`/`--yaml` are not provided, the query is built from flags.
@@ -111,7 +111,7 @@ mdbasequery --yaml "views: [{ type: table, name: default }]" --no-strict
 | --- | --- | --- |
 | `--dir <path>` | string | Target directory to scan (default: current directory). |
 | `--base <path>` | string | Path to Obsidian-style `.base` YAML file. |
-| `--yaml <string-or-path>` | string | Inline YAML text or a path to a YAML file. |
+| `--yaml <yaml-text>` | string | Inline YAML text. |
 | `--view <name>` | string | View name to run (default: first view). |
 | `--format <json|jsonl|yaml|csv|md>` | string | Output format (default: `json`). |
 | `--out <path>` | string | Write serialized output to file instead of stdout. |
@@ -206,7 +206,7 @@ Runtime adapters:
 
 - `spec?: QuerySpec` - already parsed query spec.
 - `basePath?: string` - path to `.base` file.
-- `yaml?: string` - inline YAML or YAML path.
+- `yaml?: string` - inline YAML text.
 - `view?: string` - selected view name.
 - `dir?: string` - vault root directory.
 - `strict?: boolean` - strict symbol/function behavior (default true).

src/cli.ts

@@ -30,7 +30,7 @@ const HELP_TEXT = `mdbasequery [options]
 Core options:
   --dir <path>                target directory (default .)
   --base <path>               load .base YAML file
-  --yaml <string-or-path>     inline YAML query or path to YAML file
+  --yaml <yaml-text>          inline YAML query text
   --view <name>               choose view by name (default first view)
   --format <fmt>              json|jsonl|yaml|csv|md (default json)
   --out <path>                write output to file

src/query.ts

@@ -33,8 +33,7 @@ async function loadSpec(
     const yamlInput = options.yaml;
 
     if (await adapter.exists(yamlInput)) {
-      const content = await adapter.readTextFile(yamlInput);
-      return parseBaseYaml(content);
+      throw new Error("--yaml expects inline YAML text; use basePath/--base for file paths");
     }
 
     return parseBaseYaml(yamlInput);

tests/cli.test.ts

@@ -45,6 +45,15 @@ describe("cli integration", () => {
     expect(result.stdout).toContain("Alpha");
   });
 
+  test("rejects file path passed to --yaml", () => {
+    const yamlPath = resolve(fixturesRoot, "queries/basic.base");
+    const result = runCli(["--yaml", yamlPath, "--dir", vaultDir, "--format", "json"]);
+
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain("--yaml expects inline YAML text");
+    expect(result.stderr).toContain("--base");
+  });
+
   test("--view selection and output destination", () => {
     const basePath = resolve(fixturesRoot, "queries/grouped.base");
     const tempDir = mkdtempSync(resolve(tmpdir(), "mdbasequery-"));

tests/phase0-smoke.test.ts

@@ -23,6 +23,15 @@ views:
     expect(serialized).toContain("rows");
   });
 
+  test("queryBase rejects yaml file paths", async () => {
+    await expect(
+      queryBase({
+        dir: resolve(fixturesRoot, "vaults/basic"),
+        yaml: resolve(fixturesRoot, "queries/basic.base"),
+      }),
+    ).rejects.toThrow("--yaml expects inline YAML text");
+  });
+
   test("CLI help works", () => {
     const output = spawnSync("bun", ["run", "src/cli.ts", "--help"], {
       cwd: repoRoot,