@robhowley/pi-structured-return 0.1.0 → 1.0.2

package/README.md

@@ -34,15 +34,65 @@ Tokens counted with `cl100k_base` (tiktoken). Linter output is more compact than
 - `minitest-text` (parses default minitest output — no flags or reporters needed)
 - `junit-xml` (JUnit XML — covers pytest `--junitxml`, Gradle, Maven, Jest with `jest-junit`, Go with `go-junit-report`, and any other tool that emits the JUnit XML schema)
 
+## Before / after
+
+**Raw pytest output (446 tokens):** *(pytest does have a JSON mode — but piping raw `--json-report` output to the model is noisier than the default formatter, not cleaner. The parser reads the JSON and extracts only what matters.)*
+```
+============================= test session starts ==============================
+platform darwin -- Python 3.14.2, pytest-9.0.2
+collecting ... collected 3 items
+
+test_math.py::test_adds_two_numbers_correctly PASSED                     [ 33%]
+test_math.py::test_multiplies_two_numbers_correctly FAILED               [ 66%]
+test_math.py::test_does_not_divide_by_zero FAILED                        [100%]
+
+=================================== FAILURES ===================================
+____________________ test_multiplies_two_numbers_correctly _____________________
+
+    def test_multiplies_two_numbers_correctly():
+>       assert 3 * 4 == 99
+E       assert (3 * 4) == 99
+
+test_math.py:5: AssertionError
+_________________________ test_does_not_divide_by_zero _________________________
+
+    def test_does_not_divide_by_zero():
+>       result = 1 / 0
+                 ^^^^^
+E       ZeroDivisionError: division by zero
+
+test_math.py:8: ZeroDivisionError
+=========================== short test summary info ============================
+FAILED test_math.py::test_multiplies_two_numbers_correctly
+FAILED test_math.py::test_does_not_divide_by_zero - ZeroDivisionError: ...
+========================= 2 failed, 1 passed in 0.01s ==========================
+```
+
+**Structured result returned to the model (59 tokens):**
+```
+pytest test_math.py --json-report ... → cwd: project
+2 failed, 1 passed
+  test_math.py  AssertionError: assert (3 * 4) == 99
+  test_math.py  ZeroDivisionError: division by zero
+```
+
+## How it works
+
+1. The agent runs commands through `structured_return` instead of `bash`.
+2. Full output is captured and stored as a log.
+3. A parser converts noisy CLI output into a compact structured result. If no parser matches, the last 200 lines and the log path are returned as a fallback.
+4. The agent receives the structured result in context — signal only, no noise.
+5. The full log is always available on disk for both the agent and humans to inspect.
+
 ## Agentic loops
 
 The token table above measures a single run. In an agentic loop the cost compounds — every tool result accumulates in context for the life of the task.
 
-This applies to any loop: fixing a failing test suite, implementing a feature end-to-end, working through a migration, performance tuning execution times. The agent runs a command, reads the result, makes a change, runs it again. Each iteration adds another tool result to the window. With a noisy CLI that means paying for the same verbose boilerplate on every pass, and the agent has to hold all of it to reason about what changed.
+This applies to any loop: fixing a failing test suite, implementing a feature end-to-end, working through a migration, performance tuning execution times. The agent runs a command, reads the result, makes a change, runs it again. Each iteration adds another tool result to the context window. With a noisy CLI that means paying for the same verbose boilerplate every time.
 
-A parser converts each result to a one- or two-line signal. Over 15 iterations, the difference isn't 80 tokens vs 15 tokens — it's 1,200 tokens vs 225, on a single command, for a single task.
+A parser reduces each run to a one- or two-line signal. Over 15 iterations the difference isn't 80 tokens vs 15 tokens — it's 1,200 tokens vs 225 for a single command in a single task.
 
-## Project-local extension
+## Extending with project-local parsers
 
 Built-in parsers cover common tools. For everything else — internal CLIs, custom test runners, proprietary lint tools — add a `.pi/structured-return.json` to your project root.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robhowley/pi-structured-return",
-  "version": "0.1.0",
+  "version": "1.0.2",
   "description": "Structured command execution for Pi agents: compact results for the model, full logs for humans.",
   "license": "MIT",
   "repository": {
@@ -43,7 +43,7 @@
     "lint": "eslint 'extensions/structured-return/src/**/*.ts'",
     "format:check": "prettier --check 'extensions/structured-return/src/**/*.ts'",
     "format": "prettier --write 'extensions/structured-return/src/**/*.ts'",
-    "prepare": "husky"
+    "prepare": "node -e \"if (process.env.CI || process.env.GITHUB_ACTIONS) process.exit(0)\" || husky"
   },
   "dependencies": {
     "fast-xml-parser": "^5.4.1"

package/extensions/structured-return/examples/.pi/machine-readable.json

@@ -1,18 +0,0 @@
-{
-  "parsers": [
-    {
-      "id": "acme-junit",
-      "match": {
-        "argvIncludes": ["acme", "test"]
-      },
-      "parseAs": "junit-xml"
-    },
-    {
-      "id": "foo-json",
-      "match": {
-        "argvIncludes": ["foo-cli", "check"]
-      },
-      "module": "parsers/foo-cli.js"
-    }
-  ]
-}

package/extensions/structured-return/examples/.pi/parsers/foo-cli.ts

@@ -1,25 +0,0 @@
-import fs from "node:fs";
-import type { RunContext } from "../../../src/types.js";
-
-type FooError = { id?: string; file?: string; line?: number; message?: string };
-type FooResult = { ok: boolean; errors?: FooError[] };
-
-export default {
-  id: "foo-json",
-  async parse(ctx: RunContext) {
-    const stdout = fs.readFileSync(ctx.stdoutPath, "utf8");
-    const data = JSON.parse(stdout) as FooResult;
-    return {
-      tool: "foo-cli",
-      status: data.ok ? "pass" : "fail",
-      summary: data.ok ? "foo-cli passed" : `${data.errors?.length ?? 0} foo-cli errors`,
-      failures: (data.errors ?? []).map((e: FooError, i: number) => ({
-        id: e.id ?? `error-${i + 1}`,
-        file: e.file,
-        line: e.line,
-        message: e.message,
-      })),
-      logPath: ctx.logPath,
-    };
-  },
-};

package/extensions/structured-return/src/.tmp/vitest-report.xml

@@ -1,55 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<testsuites name="vitest tests" tests="21" failures="0" errors="0" time="0.014556541">
-    <testsuite name="index.test.ts" timestamp="2026-03-16T17:34:52.759Z" hostname="Roberts-MBP" tests="9" failures="0" errors="0" skipped="0" time="0.002309">
-        <testcase classname="index.test.ts" name="stripCdPrefix &gt; strips cd /path &amp;&amp; prefix" time="0.000854833">
-        </testcase>
-        <testcase classname="index.test.ts" name="stripCdPrefix &gt; leaves commands without cd unchanged" time="0.000108208">
-        </testcase>
-        <testcase classname="index.test.ts" name="stripCdPrefix &gt; handles paths with no trailing space variations" time="0.000063708">
-        </testcase>
-        <testcase classname="index.test.ts" name="formatResult &gt; includes cwd when set" time="0.000125458">
-        </testcase>
-        <testcase classname="index.test.ts" name="formatResult &gt; omits cwd line when not set" time="0.000084875">
-        </testcase>
-        <testcase classname="index.test.ts" name="formatResult &gt; renders relative paths in failure lines" time="0.000090792">
-        </testcase>
-        <testcase classname="index.test.ts" name="finalizeResult &gt; status error with exit code 0 flips to pass" time="0.000076667">
-        </testcase>
-        <testcase classname="index.test.ts" name="finalizeResult &gt; status error with non-zero exit code stays error" time="0.000056917">
-        </testcase>
-        <testcase classname="index.test.ts" name="finalizeResult &gt; attaches cwd to result" time="0.000058875">
-        </testcase>
-    </testsuite>
-    <testsuite name="parsers/eslint-json.test.ts" timestamp="2026-03-16T17:34:52.759Z" hostname="Roberts-MBP" tests="3" failures="0" errors="0" skipped="0" time="0.003122">
-        <testcase classname="parsers/eslint-json.test.ts" name="eslint-json parser &gt; multiple errors across multiple files → correct relative paths, correct failure count, status fail" time="0.001832041">
-        </testcase>
-        <testcase classname="parsers/eslint-json.test.ts" name="eslint-json parser &gt; no errors → empty failures, status pass" time="0.000366459">
-        </testcase>
-        <testcase classname="parsers/eslint-json.test.ts" name="eslint-json parser &gt; empty stdout → no crash, status pass" time="0.000289">
-        </testcase>
-    </testsuite>
-    <testsuite name="parsers/pytest-json-report.test.ts" timestamp="2026-03-16T17:34:52.760Z" hostname="Roberts-MBP" tests="4" failures="0" errors="0" skipped="0" time="0.003528333">
-        <testcase classname="parsers/pytest-json-report.test.ts" name="pytest-json-report parser &gt; mix of passed and failed tests → correct counts, status fail" time="0.001658708">
-        </testcase>
-        <testcase classname="parsers/pytest-json-report.test.ts" name="pytest-json-report parser &gt; all passing → status pass, summary reflects passed count" time="0.00033575">
-        </testcase>
-        <testcase classname="parsers/pytest-json-report.test.ts" name="pytest-json-report parser &gt; failed test with longrepr → first line surfaced as message" time="0.000256959">
-        </testcase>
-        <testcase classname="parsers/pytest-json-report.test.ts" name="pytest-json-report parser &gt; missing artifact file → throws" time="0.000615667">
-        </testcase>
-    </testsuite>
-    <testsuite name="parsers/ruff-json.test.ts" timestamp="2026-03-16T17:34:52.760Z" hostname="Roberts-MBP" tests="3" failures="0" errors="0" skipped="0" time="0.003317375">
-        <testcase classname="parsers/ruff-json.test.ts" name="ruff-json parser &gt; multiple errors across multiple files → correct relative paths, rule code mapped to rule, status fail" time="0.00188625">
-        </testcase>
-        <testcase classname="parsers/ruff-json.test.ts" name="ruff-json parser &gt; no errors → empty failures, status pass" time="0.000399625">
-        </testcase>
-        <testcase classname="parsers/ruff-json.test.ts" name="ruff-json parser &gt; empty stdout → no crash, status pass" time="0.00028175">
-        </testcase>
-    </testsuite>
-    <testsuite name="parsers/tail-fallback.test.ts" timestamp="2026-03-16T17:34:52.760Z" hostname="Roberts-MBP" tests="2" failures="0" errors="0" skipped="0" time="0.002279833">
-        <testcase classname="parsers/tail-fallback.test.ts" name="tail-fallback parser &gt; any command → status error, summary contains log path" time="0.001251">
-        </testcase>
-        <testcase classname="parsers/tail-fallback.test.ts" name="tail-fallback parser &gt; long stdout → tail is bounded to last 200 lines" time="0.000405417">
-        </testcase>
-    </testsuite>
-</testsuites>

package/extensions/structured-return/src/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +0,0 @@
-{"version":"4.1.0","results":[[":parsers/pytest-json-report.test.ts",{"duration":8.454000000000008,"failed":false}],[":parsers/ruff-json.test.ts",{"duration":2.925207999999998,"failed":false}],[":index.test.ts",{"duration":2.2829590000000053,"failed":false}],[":parsers/eslint-json.test.ts",{"duration":3.558458999999999,"failed":false}],[":parsers/tail-fallback.test.ts",{"duration":3.911292000000003,"failed":false}],[":parsers/vitest-json.test.ts",{"duration":7.248625000000004,"failed":false}],[":parsers/rspec-json.test.ts",{"duration":7.745584000000008,"failed":false}],[":parsers/junit-xml.test.ts",{"duration":6.386042000000003,"failed":false}],[":parsers/minitest-text.test.ts",{"duration":6.155249999999995,"failed":false}]]}