Make eyecite runnable via uvx

[anseljh]

Fixes

Fixes #340

Summary

This PR adds a small JSON command-line interface so eyecite can run without a persistent installation, using uvx. Among other things, this allows eyecite to be used much more easily in agent skills.

Example usages:

uvx eyecite extract "410 U.S. 113"
uvx eyecite extract < opinion.txt | jq
uvx eyecite extract -o citations.json < opinion.txt
uvx eyecite schema

The CLI is exposed through a packaged eyecite console script. It supports text arguments or stdin, file output for large results, JSON Schema discovery, --version, and documented exit behavior.

An example eyecite-extract agent skill for Claude Code and Codex is also included. The skill invokes eyecite through uvx, keeps large JSON results out of agent transcripts, and makes jq optional by documenting a Python standard-library fallback. The two skill files are ordinary, identical files rather than a symlink so they work in Windows Git checkouts. The skill notes that this remains citation extraction rather than cite-checking: an extraction does not establish that an authority exists or is good law.

This PR suggests bumping eyecite to version 2.8.0; the skill pins eyecite>=2.8,<3.

Testing includes:

• Deterministic CLI and schema tests against tests/assets/opinion.txt, which produces 170 citations across six citation types.
• A CI test that builds the wheel and invokes it through uvx.
• An optional end-to-end test that runs the skill through Claude Code, Codex, or both, and compares the result with a direct deterministic extraction.

The live agent test is opt-in rather than part of CI because it requires installed and authenticated agent CLIs, network access for the initial uvx environment, and consumes model usage.

Use uvx --from . for local testing on a checked-out repo:

uvx --from . eyecite extract "410 U.S. 113"
uvx --from . eyecite extract < tests/assets/opinion.txt | jq
uvx --from . eyecite schema | jq

AI Disclosure

• No AI tools were used to create the content of this PR.
• Parts of this PR were created with the help of an AI tool, and I have carefully reviewed all of its content and take full responsibility for it.

[github-actions]

The Eyecite Report 👁️

Gains and Losses

There were 0 gains and 0 losses.

Total citations found: base 15988, PR 15988 (net +0).

Click here to see details.

id	Gain	Loss

Time Chart

Generated Files

Base (main) Output
PR Output
Full Output CSV

[claude]

Looks good — a self-contained, well-tested addition (new eyecite/cli.py, packaging/console-script wiring, and a CI smoke test) with no changes to core citation-extraction logic.

What was reviewed: the new extract/schema CLI commands and their JSON Schema/output contract in eyecite/cli.py; the console-script and dev-dependency wiring in pyproject.toml; the uvx wheel smoke-test step added to .github/workflows/tests.yml; and the new tests/test_CliTest.py / tests/test_AgentSkillTest.py coverage. Checked and ruled out: TEXT arguments beginning with - being misparsed by argparse as an option, and sys.stdout.write() of the JSON payload lacking explicit UTF-8 handling — both are narrow edge cases (dash-prefixed citation text, non-UTF-8 locale) rather than blocking issues for this change.

Extended reasoning...

Overview

The PR adds a new, self-contained eyecite/cli.py module exposing eyecite extract and eyecite schema subcommands, wires it up as a console script and dev dependency in pyproject.toml, adds a wheel smoke-test step to CI via uvx, bumps the version to 2.8.0, documents the new workflow in README.rst/CHANGES.md, and adds two new test files plus duplicated (by design, for cross-platform reasons) agent-skill markdown files for Codex and Claude Code. None of the changes touch the core citation-extraction engine (eyecite/find.py, tokenizers, regexes, etc.) — the CLI is a thin JSON-serializing wrapper around the existing public get_citations() API.

Security risks

No auth, crypto, or permission-sensitive code is touched. The CLI reads text from an argument or stdin and either prints JSON to stdout or writes it to a file path given via -o/--output (using Path(output).write_text(...), no shell invocation, no path sanitization concerns beyond what the user explicitly requests). No network calls, no eval/exec, no shell-outs from the CLI itself. The CI addition uses uv build --wheel and uvx --from ./dist/... to smoke test the packaged wheel, which is a standard, low-risk CI pattern.

Level of scrutiny

This warrants a moderate level of scrutiny given its size (new module + packaging + CI + docs + two test files), but the surface area is narrow and self-contained: a single new file implementing two subcommands, backed by argparse, with a hand-written JSON Schema and dedicated tests (tests/test_CliTest.py) plus an opt-in end-to-end skill test (tests/test_AgentSkillTest.py, not part of default CI). I reviewed cli.py directly, the pyproject.toml/CI diffs, and confirmed the two candidate issues already surfaced by the bug-hunting pass (dash-prefixed positional argument, stdout encoding) are minor edge cases rather than correctness-blocking bugs for the stated use case.

Other factors

Test coverage for the new CLI is present and deterministic (against tests/assets/opinion.txt), and the live-agent skill test is explicitly opt-in rather than gating CI, which is a sensible choice given it requires authenticated agent CLIs. No CODEOWNERS file was found restricting these paths. No outstanding third-party review objections were visible in the provided timeline metadata.