json-from-llm 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-06-05
+
+### Added
+
+- Added the `json-from-llm` CLI for shell pipelines. It reads stdin, prints the
+  extracted JSON value to stdout and supports `--expect object|array|any` plus
+  `--no-repair`.
+- Added CLI tests covering normalized stdout, top-level type selection and
+  extraction failures.
+
+## [0.1.3] - 2026-06-05
+
+### Added
+
+- Added a public reasoning-output fixture corpus covering `<think>` /
+  `<reasoning>` blocks, fenced JSON, prose wrappers, trailing commas, type
+  expectations and no-JSON failures.
+- Added tests that read the published fixture corpus and verify `tryExtractJson`
+  results.
+- Published the `fixtures/` directory in the npm package for downstream parser
+  and agent-loop tests.
+
 ## [0.1.2] - 2026-06-04
 
 ### Changed

package/README.md

@@ -9,6 +9,9 @@
 
 > Extract valid JSON from an LLM response — even when it's wrapped in reasoning/thinking tags, markdown fences or prose. **Zero dependencies.**
 
+Security posture is tracked in [docs/security-posture.md](./docs/security-posture.md),
+including CodeQL, OpenSSF Scorecard, Dependabot and branch rules.
+
 You asked for JSON. The model gave you:
 
 ````text
@@ -36,7 +39,8 @@ const data = extractJson<{ score: number }>(modelOutput);
 - **Handles the real wrappers.** Markdown fences (`json` and bare ```), conversational prose before/after, and the JSON sitting bare in the text.
 - **String-aware, never corrupts.** The scanner and the trailing-comma repair both respect string contents — a `}` or `,` inside `"a string value"` is left alone.
 - **Conservative repair.** Removes trailing commas (the most common malformation); it will never rewrite your data.
-- **Two entry points.** `extractJson` throws on failure; `tryExtractJson` returns `{ found }`.
+- **Fixture-backed edge cases.** Public fixtures cover reasoning tags, fenced JSON, prose wrappers, trailing commas, top-level type expectations and no-JSON failures.
+- **Two library entry points + CLI.** `extractJson` throws on failure; `tryExtractJson` returns `{ found }`; `json-from-llm` reads stdin for shell pipelines.
 - **Zero dependencies**, ESM + CJS, fully typed.
 
 ## Install
@@ -45,6 +49,39 @@ const data = extractJson<{ score: number }>(modelOutput);
 npm install json-from-llm
 ```
 
+## CLI
+
+Pipe model output directly into the binary:
+
+```sh
+cat response.txt | npx json-from-llm
+```
+
+Example:
+
+````sh
+printf '%s\n' '<think>{draft: true}</think>```json
+{"score":8,"reason":"clear"}
+```' | npx json-from-llm
+# {"score":8,"reason":"clear"}
+````
+
+Useful flags:
+
+```sh
+# Skip an earlier array and require the first object that parses
+cat response.txt | npx json-from-llm --expect object
+
+# Disable trailing-comma repair when you want strict parsing
+cat response.txt | npx json-from-llm --no-repair
+```
+
+Exit codes:
+
+- `0` — JSON extracted and printed to stdout.
+- `1` — no matching JSON value found.
+- `2` — invalid CLI options.
+
 ## API
 
 ### `extractJson<T>(text, options?) => T`
@@ -79,6 +116,21 @@ extractJson('[1,2] then the answer {"a":1}', { expect: 'object' }); // { a: 1 }
 
 The low-level pieces (`stripReasoning`, `fencedBlocks`, `balancedSpans`, `removeTrailingCommas`) are exported too.
 
+## Fixture corpus
+
+The package includes a small public corpus under [`fixtures/`](./fixtures):
+
+- `deepseek-thinking-object.txt`
+- `gemini-reasoning-array.txt`
+- `prose-trailing-commas.txt`
+- `expect-object-skips-array.txt`
+- `no-json.txt`
+- expected `tryExtractJson` outputs under `fixtures/expected/`
+
+The tests read these files directly, so parser changes are checked against
+stable, reusable examples. The fixtures are synthetic and safe for public CI:
+they contain no prompts, secrets, user data or live provider responses.
+
 ## Related
 
 - [`tool-schema`](https://www.npmjs.com/package/tool-schema) — turn a JSON Schema into a provider tool/function schema (define the shape you then extract).

package/dist/cli.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+
+// src/repair.ts
+function removeTrailingCommas(json) {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < json.length; i++) {
+    const ch = json[i];
+    if (inString) {
+      out += ch;
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      out += ch;
+      continue;
+    }
+    if (ch === ",") {
+      let j = i + 1;
+      while (j < json.length && (json[j] === " " || json[j] === "\n" || json[j] === "\r" || json[j] === "	")) {
+        j++;
+      }
+      if (json[j] === "}" || json[j] === "]") {
+        continue;
+      }
+    }
+    out += ch;
+  }
+  return out;
+}
+
+// src/scan.ts
+function balancedSpans(text) {
+  const spans = [];
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === "{" || ch === "[") {
+      const end = matchBalanced(text, i);
+      if (end !== -1) {
+        spans.push(text.slice(i, end));
+        i = end;
+        continue;
+      }
+    }
+    i++;
+  }
+  return spans;
+}
+function matchBalanced(text, start) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+    } else if (ch === "{" || ch === "[") {
+      depth++;
+    } else if (ch === "}" || ch === "]") {
+      depth--;
+      if (depth === 0) {
+        return i + 1;
+      }
+    }
+  }
+  return -1;
+}
+
+// src/strip.ts
+var REASONING_TAGS = /<(think|thinking|reasoning|thought)>[\s\S]*?<\/\1>/gi;
+function stripReasoning(text) {
+  return text.replace(REASONING_TAGS, "");
+}
+var FENCE = /```[^\S\n]*([a-zA-Z0-9_+-]*)[^\S\n]*\n?([\s\S]*?)```/g;
+function fencedBlocks(text) {
+  const blocks = [];
+  FENCE.lastIndex = 0;
+  let match;
+  while ((match = FENCE.exec(text)) !== null) {
+    const lang = match[1].toLowerCase();
+    const content = match[2].trim();
+    if (content.length > 0 && (lang === "" || lang.includes("json"))) {
+      blocks.push(content);
+    }
+  }
+  return blocks;
+}
+
+// src/types.ts
+var JsonExtractionError = class extends Error {
+  constructor(message, text) {
+    super(message);
+    this.text = text;
+    this.name = "JsonExtractionError";
+  }
+  text;
+};
+
+// src/extract.ts
+function parseCandidate(candidate, repair) {
+  try {
+    return { ok: true, value: JSON.parse(candidate) };
+  } catch {
+  }
+  if (repair) {
+    try {
+      return { ok: true, value: JSON.parse(removeTrailingCommas(candidate)) };
+    } catch {
+    }
+  }
+  return { ok: false };
+}
+function matchesExpect(value, expect) {
+  if (expect === "any") {
+    return true;
+  }
+  if (expect === "array") {
+    return Array.isArray(value);
+  }
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function tryExtractJson(text, options = {}) {
+  if (typeof text !== "string" || text.length === 0) {
+    return { found: false };
+  }
+  const repair = options.repair ?? true;
+  const expect = options.expect ?? "any";
+  const cleaned = stripReasoning(text);
+  const candidates = [];
+  for (const block of fencedBlocks(cleaned)) {
+    candidates.push(block, ...balancedSpans(block));
+  }
+  candidates.push(...balancedSpans(cleaned));
+  for (const candidate of candidates) {
+    const parsed = parseCandidate(candidate, repair);
+    if (parsed.ok && matchesExpect(parsed.value, expect)) {
+      return { found: true, value: parsed.value };
+    }
+  }
+  return { found: false };
+}
+function extractJson(text, options = {}) {
+  const result = tryExtractJson(text, options);
+  if (!result.found) {
+    throw new JsonExtractionError(
+      "No JSON value could be extracted from the text.",
+      text
+    );
+  }
+  return result.value;
+}
+
+// src/cli.ts
+var usage = `Usage: json-from-llm [--expect object|array|any] [--no-repair]
+
+Read LLM output from stdin and print the extracted JSON value to stdout.
+
+Options:
+  --expect <type>  Require the top-level JSON value to be object, array or any.
+  --no-repair     Disable conservative trailing-comma repair.
+  -h, --help      Show this help text.
+`;
+function parseArgs(args) {
+  const config = { help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-h" || arg === "--help") {
+      config.help = true;
+      continue;
+    }
+    if (arg === "--no-repair") {
+      config.repair = false;
+      continue;
+    }
+    if (arg === "--expect") {
+      const value = args[index + 1];
+      if (value !== "object" && value !== "array" && value !== "any") {
+        return "invalid --expect value; use object, array or any";
+      }
+      config.expect = value;
+      index += 1;
+      continue;
+    }
+    return `unknown option: ${arg}`;
+  }
+  return config;
+}
+async function runCli(args, stdin, streams) {
+  const config = parseArgs(args);
+  if (typeof config === "string") {
+    streams.stderr(`json-from-llm: ${config}
+`);
+    return 2;
+  }
+  if (config.help) {
+    streams.stdout(usage);
+    return 0;
+  }
+  try {
+    const value = extractJson(stdin, config);
+    streams.stdout(`${JSON.stringify(value)}
+`);
+    return 0;
+  } catch (error) {
+    if (error instanceof JsonExtractionError) {
+      streams.stderr("json-from-llm: no JSON found\n");
+      return 1;
+    }
+    streams.stderr(
+      `json-from-llm: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    return 1;
+  }
+}
+async function readStdin() {
+  process.stdin.setEncoding("utf8");
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  return input;
+}
+function isExecutedFile(moduleUrl, argvPath) {
+  if (!argvPath) {
+    return false;
+  }
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argvPath);
+  } catch {
+    return false;
+  }
+}
+function isMain() {
+  return isExecutedFile(import.meta.url, process.argv[1]);
+}
+async function main() {
+  process.exitCode = await runCli(process.argv.slice(2), await readStdin(), {
+    stdout: (chunk) => {
+      process.stdout.write(chunk);
+    },
+    stderr: (chunk) => {
+      process.stderr.write(chunk);
+    }
+  });
+}
+if (isMain()) {
+  void main();
+}
+export {
+  isExecutedFile,
+  runCli
+};
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/repair.ts","../src/scan.ts","../src/strip.ts","../src/types.ts","../src/extract.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { realpathSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport { extractJson } from './extract.ts';\nimport { JsonExtractionError } from './types.ts';\nimport type { ExtractOptions } from './types.ts';\n\nexport interface CliStreams {\n  stdout: (chunk: string) => void;\n  stderr: (chunk: string) => void;\n}\n\ninterface CliConfig extends ExtractOptions {\n  help: boolean;\n}\n\nconst usage = `Usage: json-from-llm [--expect object|array|any] [--no-repair]\n\nRead LLM output from stdin and print the extracted JSON value to stdout.\n\nOptions:\n  --expect <type>  Require the top-level JSON value to be object, array or any.\n  --no-repair     Disable conservative trailing-comma repair.\n  -h, --help      Show this help text.\n`;\n\nfunction parseArgs(args: string[]): CliConfig | string {\n  const config: CliConfig = { help: false };\n\n  for (let index = 0; index < args.length; index += 1) {\n    const arg = args[index];\n\n    if (arg === '-h' || arg === '--help') {\n      config.help = true;\n      continue;\n    }\n\n    if (arg === '--no-repair') {\n      config.repair = false;\n      continue;\n    }\n\n    if (arg === '--expect') {\n      const value = args[index + 1];\n      if (value !== 'object' && value !== 'array' && value !== 'any') {\n        return 'invalid --expect value; use object, array or any';\n      }\n      config.expect = value;\n      index += 1;\n      continue;\n    }\n\n    return `unknown option: ${arg}`;\n  }\n\n  return config;\n}\n\nexport async function runCli(\n  args: string[],\n  stdin: string,\n  streams: CliStreams,\n): Promise<number> {\n  const config = parseArgs(args);\n\n  if (typeof config === 'string') {\n    streams.stderr(`json-from-llm: ${config}\\n`);\n    return 2;\n  }\n\n  if (config.help) {\n    streams.stdout(usage);\n    return 0;\n  }\n\n  try {\n    const value = extractJson(stdin, config);\n    streams.stdout(`${JSON.stringify(value)}\\n`);\n    return 0;\n  } catch (error) {\n    if (error instanceof JsonExtractionError) {\n      streams.stderr('json-from-llm: no JSON found\\n');\n      return 1;\n    }\n\n    streams.stderr(\n      `json-from-llm: ${error instanceof Error ? error.message : String(error)}\\n`,\n    );\n    return 1;\n  }\n}\n\nasync function readStdin(): Promise<string> {\n  process.stdin.setEncoding('utf8');\n  let input = '';\n  for await (const chunk of process.stdin) {\n    input += chunk;\n  }\n  return input;\n}\n\nexport function isExecutedFile(moduleUrl: string, argvPath?: string): boolean {\n  if (!argvPath) {\n    return false;\n  }\n\n  try {\n    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argvPath);\n  } catch {\n    return false;\n  }\n}\n\nfunction isMain(): boolean {\n  return isExecutedFile(import.meta.url, process.argv[1]);\n}\n\nasync function main(): Promise<void> {\n  process.exitCode = await runCli(process.argv.slice(2), await readStdin(), {\n    stdout: (chunk) => {\n      process.stdout.write(chunk);\n    },\n    stderr: (chunk) => {\n      process.stderr.write(chunk);\n    },\n  });\n}\n\nif (isMain()) {\n  void main();\n}\n","/**\n * Remove trailing commas (`{\"a\":1,}` → `{\"a\":1}`, `[1,2,]` → `[1,2]`), which\n * models emit frequently. String-aware: a comma inside a string value is never\n * touched, so this can only ever fix structure, never corrupt content.\n */\nexport function removeTrailingCommas(json: string): string {\n  let out = '';\n  let inString = false;\n  let escaped = false;\n\n  for (let i = 0; i < json.length; i++) {\n    const ch = json[i];\n\n    if (inString) {\n      out += ch;\n      if (escaped) {\n        escaped = false;\n      } else if (ch === '\\\\') {\n        escaped = true;\n      } else if (ch === '\"') {\n        inString = false;\n      }\n      continue;\n    }\n\n    if (ch === '\"') {\n      inString = true;\n      out += ch;\n      continue;\n    }\n\n    if (ch === ',') {\n      let j = i + 1;\n      while (\n        j < json.length &&\n        (json[j] === ' ' ||\n          json[j] === '\\n' ||\n          json[j] === '\\r' ||\n          json[j] === '\\t')\n      ) {\n        j++;\n      }\n      if (json[j] === '}' || json[j] === ']') {\n        continue; // drop the trailing comma\n      }\n    }\n\n    out += ch;\n  }\n\n  return out;\n}\n","/**\n * Find the substrings of complete, balanced JSON objects/arrays in `text`,\n * in document order. String-aware: braces and brackets inside JSON strings do\n * not affect nesting, so prose like `\"the } char\"` won't break the scan.\n */\nexport function balancedSpans(text: string): string[] {\n  const spans: string[] = [];\n  let i = 0;\n  while (i < text.length) {\n    const ch = text[i];\n    if (ch === '{' || ch === '[') {\n      const end = matchBalanced(text, i);\n      if (end !== -1) {\n        spans.push(text.slice(i, end));\n        i = end;\n        continue;\n      }\n    }\n    i++;\n  }\n  return spans;\n}\n\n/** Return the index just past the balanced value starting at `start`, or -1. */\nfunction matchBalanced(text: string, start: number): number {\n  let depth = 0;\n  let inString = false;\n  let escaped = false;\n\n  for (let i = start; i < text.length; i++) {\n    const ch = text[i];\n\n    if (inString) {\n      if (escaped) {\n        escaped = false;\n      } else if (ch === '\\\\') {\n        escaped = true;\n      } else if (ch === '\"') {\n        inString = false;\n      }\n      continue;\n    }\n\n    if (ch === '\"') {\n      inString = true;\n    } else if (ch === '{' || ch === '[') {\n      depth++;\n    } else if (ch === '}' || ch === ']') {\n      depth--;\n      if (depth === 0) {\n        return i + 1;\n      }\n    }\n  }\n\n  return -1;\n}\n","/**\n * Remove model \"thinking\" / reasoning blocks. Reasoning models (DeepSeek R1,\n * Qwen, and prompted Claude/Gemini setups) emit `<think>…</think>` or\n * `<thinking>…</thinking>` before the answer, and that text frequently contains\n * brace-laden prose that would otherwise be mistaken for the payload.\n */\nconst REASONING_TAGS = /<(think|thinking|reasoning|thought)>[\\s\\S]*?<\\/\\1>/gi;\n\nexport function stripReasoning(text: string): string {\n  return text.replace(REASONING_TAGS, '');\n}\n\n/**\n * Return the inner contents of fenced code blocks that could hold JSON: blocks\n * tagged ```json / ```jsonc / ```json5, or untagged ``` blocks. Other languages\n * (```python, ```ts) are skipped — they won't contain the answer JSON.\n */\nconst FENCE = /```[^\\S\\n]*([a-zA-Z0-9_+-]*)[^\\S\\n]*\\n?([\\s\\S]*?)```/g;\n\nexport function fencedBlocks(text: string): string[] {\n  const blocks: string[] = [];\n  FENCE.lastIndex = 0;\n  let match: RegExpExecArray | null;\n  while ((match = FENCE.exec(text)) !== null) {\n    const lang = match[1].toLowerCase();\n    const content = match[2].trim();\n    if (content.length > 0 && (lang === '' || lang.includes('json'))) {\n      blocks.push(content);\n    }\n  }\n  return blocks;\n}\n","/** Options for {@link extractJson} and {@link tryExtractJson}. */\nexport interface ExtractOptions {\n  /**\n   * Apply conservative, string-aware repairs before parsing — currently the\n   * removal of trailing commas, which models emit often. Never rewrites string\n   * contents. Default `true`.\n   */\n  repair?: boolean;\n  /**\n   * Restrict which top-level JSON value to accept: an `'object'`, an `'array'`,\n   * or `'any'` (the default).\n   */\n  expect?: 'object' | 'array' | 'any';\n}\n\n/** The result of {@link tryExtractJson}. */\nexport type ExtractResult<T> =\n  | { found: true; value: T }\n  | { found: false; value?: undefined };\n\n/** Thrown by {@link extractJson} when no JSON value can be recovered. */\nexport class JsonExtractionError extends Error {\n  constructor(\n    message: string,\n    /** The original text that no JSON could be extracted from. */\n    public readonly text: string,\n  ) {\n    super(message);\n    this.name = 'JsonExtractionError';\n  }\n}\n","import { removeTrailingCommas } from './repair.ts';\nimport { balancedSpans } from './scan.ts';\nimport { fencedBlocks, stripReasoning } from './strip.ts';\nimport { JsonExtractionError } from './types.ts';\nimport type { ExtractOptions, ExtractResult } from './types.ts';\n\nfunction parseCandidate(\n  candidate: string,\n  repair: boolean,\n): { ok: true; value: unknown } | { ok: false } {\n  try {\n    return { ok: true, value: JSON.parse(candidate) };\n  } catch {\n    // fall through to repair\n  }\n  if (repair) {\n    try {\n      return { ok: true, value: JSON.parse(removeTrailingCommas(candidate)) };\n    } catch {\n      // unrecoverable\n    }\n  }\n  return { ok: false };\n}\n\nfunction matchesExpect(\n  value: unknown,\n  expect: 'object' | 'array' | 'any',\n): boolean {\n  if (expect === 'any') {\n    return true;\n  }\n  if (expect === 'array') {\n    return Array.isArray(value);\n  }\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/**\n * Extract a JSON value from LLM output without throwing.\n *\n * Strips `<think>` / `<thinking>` reasoning blocks, prefers fenced ```json\n * code blocks, then scans for the first balanced object/array that parses\n * (applying conservative repair). Returns `{ found: false }` if nothing parses.\n *\n * @example\n * ```ts\n * const r = tryExtractJson<{ score: number }>('<think>...</think>\\n{\"score\":7}');\n * if (r.found) console.log(r.value.score); // 7\n * ```\n */\nexport function tryExtractJson<T = unknown>(\n  text: string,\n  options: ExtractOptions = {},\n): ExtractResult<T> {\n  if (typeof text !== 'string' || text.length === 0) {\n    return { found: false };\n  }\n\n  const repair = options.repair ?? true;\n  const expect = options.expect ?? 'any';\n  const cleaned = stripReasoning(text);\n\n  // Candidate substrings, highest confidence first: fenced blocks (and any\n  // balanced values inside them), then balanced values anywhere in the text.\n  const candidates: string[] = [];\n  for (const block of fencedBlocks(cleaned)) {\n    candidates.push(block, ...balancedSpans(block));\n  }\n  candidates.push(...balancedSpans(cleaned));\n\n  for (const candidate of candidates) {\n    const parsed = parseCandidate(candidate, repair);\n    if (parsed.ok && matchesExpect(parsed.value, expect)) {\n      return { found: true, value: parsed.value as T };\n    }\n  }\n  return { found: false };\n}\n\n/**\n * Extract a JSON value from LLM output, throwing {@link JsonExtractionError}\n * if none can be recovered. See {@link tryExtractJson} for the algorithm.\n */\nexport function extractJson<T = unknown>(\n  text: string,\n  options: ExtractOptions = {},\n): T {\n  const result = tryExtractJson<T>(text, options);\n  if (!result.found) {\n    throw new JsonExtractionError(\n      'No JSON value could be extracted from the text.',\n      text,\n    );\n  }\n  return result.value;\n}\n"],"mappings":"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","names":[]}

package/fixtures/README.md

@@ -0,0 +1,14 @@
+# Reasoning Output Fixture Corpus
+
+This corpus contains deterministic model-output examples that commonly break
+plain `JSON.parse`:
+
+- reasoning/thinking tags with brace-laden prose
+- fenced JSON blocks inside conversational text
+- trailing commas in otherwise valid JSON
+- competing arrays/objects when callers expect a specific top-level type
+- negative text with no recoverable JSON
+
+Each `.txt` file has a matching expected JSON file under `fixtures/expected/`.
+The fixtures are synthetic and safe for public CI: they contain no prompts,
+secrets, user data or live provider responses.

package/fixtures/deepseek-thinking-object.txt

@@ -0,0 +1,13 @@
+<think>
+The user asked for a risk score. I might draft {score: maybe 6}, but that is
+not JSON and should not be selected.
+</think>
+
+Final answer:
+```json
+{
+  "score": 8,
+  "reason": "clear evidence",
+  "tags": ["portable", "safe"]
+}
+```

package/fixtures/expect-object-skips-array.txt

@@ -0,0 +1,7 @@
+First, a quick list: ["draft", "ignore"].
+
+The object you asked for:
+{
+  "city": "Santiago",
+  "units": "metric"
+}

package/fixtures/expected/deepseek-thinking-object.json

@@ -0,0 +1,9 @@
+{
+  "found": true,
+  "expect": "object",
+  "value": {
+    "score": 8,
+    "reason": "clear evidence",
+    "tags": ["portable", "safe"]
+  }
+}

package/fixtures/expected/expect-object-skips-array.json

@@ -0,0 +1,8 @@
+{
+  "found": true,
+  "expect": "object",
+  "value": {
+    "city": "Santiago",
+    "units": "metric"
+  }
+}

package/fixtures/expected/gemini-reasoning-array.json

@@ -0,0 +1,8 @@
+{
+  "found": true,
+  "expect": "array",
+  "value": [
+    { "id": "alpha", "score": 0.91 },
+    { "id": "beta", "score": 0.72 }
+  ]
+}

package/fixtures/expected/no-json.json

@@ -0,0 +1,4 @@
+{
+  "found": false,
+  "expect": "any"
+}

package/fixtures/expected/prose-trailing-commas.json

@@ -0,0 +1,8 @@
+{
+  "found": true,
+  "expect": "object",
+  "value": {
+    "providers": ["openai", "anthropic", "gemini"],
+    "ok": true
+  }
+}

package/fixtures/gemini-reasoning-array.txt

@@ -0,0 +1,12 @@
+<reasoning>
+Need to rank the candidates. The scratch list [bad, draft] is only prose.
+</reasoning>
+
+Here is the JSON:
+
+```json
+[
+  { "id": "alpha", "score": 0.91 },
+  { "id": "beta", "score": 0.72 }
+]
+```

package/fixtures/no-json.txt

@@ -0,0 +1 @@
+I cannot produce a structured result from the supplied input.

package/fixtures/prose-trailing-commas.txt

@@ -0,0 +1,8 @@
+Sure — I normalized the provider names below.
+
+{
+  "providers": ["openai", "anthropic", "gemini",],
+  "ok": true,
+}
+
+Let me know if you want CSV too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-from-llm",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Extract valid JSON from an LLM response, even when it is wrapped in reasoning/thinking tags, markdown fences or prose. Zero dependencies.",
   "keywords": [
     "llm",
@@ -32,6 +32,9 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "json-from-llm": "dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -42,6 +45,7 @@
   },
   "files": [
     "dist",
+    "fixtures",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -67,7 +71,7 @@
     "eslint": "^10.4.1",
     "prettier": "^3.4.2",
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0",
     "vitest": "^4.1.8"
   }