@robhowley/pi-structured-return 0.1.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@robhowley/pi-structured-return",
+  "version": "0.1.0",
+  "description": "Structured command execution for Pi agents: compact results for the model, full logs for humans.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/robhowley/pi-structured-return"
+  },
+  "homepage": "https://github.com/robhowley/pi-structured-return",
+  "bugs": {
+    "url": "https://github.com/robhowley/pi-structured-return/issues"
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "extensions",
+    "skills",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "lint-staged": {
+    "extensions/structured-return/src/**/*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/structured-return/src/index.ts"
+    ],
+    "skills": [
+      "./skills/structured-return"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p extensions/structured-return/tsconfig.json",
+    "test": "vitest run --config extensions/structured-return/vitest.config.ts",
+    "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"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.4.1"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "^0.34.0",
+    "eslint": "^9.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.1.0"
+  }
+}

package/skills/structured-return/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: structured-return
+description: Choose compact, machine-readable commands across common test, lint, build, and log workflows. Use when raw terminal output would be noisy and the agent should prefer json, junit/xml, porcelain, quiet, no-pretty, or narrow-scope command forms.
+---
+
+# structured-return
+
+Prefer better output at the source.
+
+## What structured_return does
+
+`structured_return` is a tool — use it instead of `bash` for lint, test, and build commands. It runs the command, stores the full log, and returns a compact parsed result to the model. When a parser matches, only the signal (failures, errors, summary) comes back into context. When no parser matches, it falls back to the last 200 lines of output plus a log path — still better than dumping everything into context via `bash`.
+
+## Rules
+
+1. Before running any lint, test, or build command, check for project-defined scripts (`package.json`, `Makefile`, `pyproject.toml`, etc.). If a script exists for the task, inspect it to identify the underlying tool and the scope/paths it uses. Then invoke that tool directly with machine-readable flags and the same scope — rather than running through the script wrapper.
+2. Use `structured_return` instead of `bash` for lint, test, and build commands. For tools with a built-in parser, use the command form shown in the examples below. For tools without one, use known machine-readable flags (`--json`, `--format json`, `--message-format=json`, `--console=plain`, `--porcelain`, etc.) and let the tail fallback handle the result.
+3. Otherwise prefer quiet, plain, no-color, and narrow-scope modes.
+4. Prefer file/test-specific runs before full-suite runs.
+5. Prefer bounded log reads over full log dumps.
+6. Do not invent flags. Use known patterns from examples below or your own knowledge of the tool.
+7. When using `structured_return`, pass explicit parser hints when known.
+8. If a repo defines project-local parser mappings in `.pi/structured-return.json`, prefer those mappings.
+
+## Examples
+
+### pytest
+- `structured_return({ command: "pytest [any pytest args] --json-report --json-report-file=.tmp/pytest-report.json", parseAs: "pytest-json-report", artifactPaths: [".tmp/pytest-report.json"] })` — append the json-report flags to whatever pytest invocation is needed; scope, filters, markers, etc. go in `[any pytest args]`
+- `structured_return({ command: "pytest -q" })` — fallback when json-report is unavailable
+
+### ruff check
+- `structured_return({ command: "ruff check [any ruff args] --output-format=json", parseAs: "ruff-json" })` — scope, selects, ignores, etc. go in `[any ruff args]`
+
+### ruff format
+- `ruff format --check .` (no structured_return — json output not supported)
+
+### vitest
+- `structured_return({ command: "vitest run [any vitest args] --reporter=json", parseAs: "vitest-json" })` — file paths, filters, etc. go in `[any vitest args]`
+
+### eslint
+- `structured_return({ command: "eslint [any eslint args] -f json", parseAs: "eslint-json" })` — paths, configs, rules, etc. go in `[any eslint args]`
+
+### rspec
+- `structured_return({ command: "bundle exec rspec [any rspec args] --format json", parseAs: "rspec-json" })` — `--format json` is required; without it output is not parseable
+
+### minitest
+- `structured_return({ command: "ruby [any minitest args]", parseAs: "minitest-text" })` — no format flags needed; works with plain ruby invocation
+
+### junit-xml
+JUnit XML is the de facto standard output format across the JVM ecosystem and many others — Maven, Gradle, pytest (`--junitxml`), Go (`go-junit-report`), .NET (`--logger trx` with conversion), Jest (`jest-junit`), and more. If a tool can emit JUnit XML, `junit-xml` covers it without a custom parser.
+
+- `structured_return({ command: "[tool] [args] --junitxml=.tmp/report.xml", parseAs: "junit-xml", artifactPaths: [".tmp/report.xml"] })` — pytest, nose2, and others that write to a file
+- `structured_return({ command: "gradle test", parseAs: "junit-xml", artifactPaths: ["build/test-results/test/TEST-*.xml"] })` — Gradle writes one XML per test class; pass all matching paths
+- `structured_return({ command: "mvn test", parseAs: "junit-xml", artifactPaths: ["target/surefire-reports/TEST-*.xml"] })` — Maven surefire same pattern
+
+#### Swift / XCTest (Swift Package Manager)
+
+`swift test` has native JUnit XML output via `--xunit-output` (Swift 5.7+). Use this for all SPM projects — no third-party reporter needed.
+
+- `structured_return({ command: "swift test --xunit-output .tmp/report.xml", parseAs: "junit-xml", artifactPaths: [".tmp/report.xml"] })` — full test suite
+- `structured_return({ command: "swift test --filter MathTests --xunit-output .tmp/report.xml", parseAs: "junit-xml", artifactPaths: [".tmp/report.xml"] })` — single test target or test case; `--filter` accepts a target name, class name, or `ClassName/testMethodName`
+
+#### Swift / XCTest (Xcode projects)
+
+`xcodebuild` output is high-volume and not directly parseable. Pipe through `xcbeautify` (install with `brew install xcbeautify`) to get JUnit XML:
+
+- `structured_return({ command: "xcodebuild test -scheme [scheme] -destination '[destination]' 2>&1 | xcbeautify --report junit --output .tmp", parseAs: "junit-xml", artifactPaths: [".tmp/report.junit.xml"] })` — xcbeautify writes `report.junit.xml` into the `--output` directory; run `xcodebuild -showdestinations -scheme [scheme]` first to find the correct `[destination]` string for the project