run-opossum

name	run-opossum
description	Build, install, run and drive the opossum CLI. Use when asked to run opossum, start it, try a command, smoke test it, reproduce CLI behaviour, verify a change works end to end, or run its tests.

opossum is a zero-dependency Python CLI that rewrites an awesome list's README.md in place. There is no server, no UI and nothing to screenshot: what you observe is the exit code, the stdout, and how the markdown file changed. Drive all three with .claude/skills/run-opossum/driver.py, which builds a throwaway list in a temp directory and runs the real binary against it.

Prerequisites

None. No system packages were needed in this container — python3 -m venv worked out of the box, and opossum has no runtime dependencies (standard library only, Python 3.9+).

Setup

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/opossum --version
# → opossum 0.1.0

.venv/ is already gitignored. The editable install points at the source tree, so edits to opossum/*.py take effect with no reinstall.

You can skip setup entirely. The driver falls back to python3 -m opossum (with PYTHONPATH set to the repo) when no opossum is on PATH, so it runs against a bare clone.

Run (agent path)

python3 .claude/skills/run-opossum/driver.py
# → driving: /usr/local/bin/python3 -m opossum
#   list:    /tmp/opossum-drive-w3rblpml/README.md
#
#   ok — 29 checks passed

Against the installed binary, with the model exercised directly too:

python3 .claude/skills/run-opossum/driver.py --bin .venv/bin/opossum --library
# → library ok: 2 entries, 3 sections
#   ok — 30 checks passed

flag	what it does
(none)	Full CLI lifecycle: init, rm, section add, add ×2, dry run, fmt/toc/lint --check, damage-and-repair, ls --json, stats
--bin PATH	Which opossum to drive. Default: opossum on PATH, else python3 -m opossum
--library	Import the model and edit a document without the CLI — the layer most changes touch
--network	Also run the link checker against a reachable and a 404 URL
--keep	Leave the scratch list on disk and print its path, so you can poke it by hand

The driver asserts exit codes and file content, so it catches behaviour the test suite would not. Breaking alphabetical insertion in edit.py, for instance, produces:

FAILED — 3 of 29 checks:
  a new entry was not inserted in alphabetical position
  `opossum lint --strict` exited 1, expected 0 — 0 error(s), 1 warning(s)

To poke a real list yourself:

python3 .claude/skills/run-opossum/driver.py --keep
# → kept: /tmp/opossum-drive-i8gxj03c
cd /tmp/opossum-drive-i8gxj03c && /home/user/opossum/.venv/bin/opossum ls

Driving one command by hand

Every command walks up from the working directory to find README.md, so work inside a list directory (or pass --path):

OPOSSUM=$PWD/.venv/bin/opossum
cd "$(mktemp -d)"
$OPOSSUM init "Awesome Possums" --description "Everything about possums."
$OPOSSUM add "Alpha" https://alpha.example -d "The first one."
$OPOSSUM lint
# → no issues found

Exit codes are the contract: 0 clean, 1 the check failed (lint errors, fmt --check needs changes, broken links), 2 you asked for something impossible (unknown section, duplicate URL, missing file).

Run (human path)

Same binary, no driver: opossum init, opossum add …, opossum lint. See README.md for the full command reference. Nothing is interactive and nothing long-running, so there is no process to stop.

Test

python3 -m unittest discover
# → Ran 131 tests in 1.218s / OK

python3 tools/check.py --fuzz 500
# → all 4 checks passed in 4.3s

tools/check.py is the project's real gate (tests + corpus + fuzzing + its own end-to-end CLI run). The driver here is complementary: the gate proves the invariants hold, the driver proves the installed command behaves.

Gotchas

• opossum lint inside this repo lints opossum's own README and exits 1 with 2 error(s), 3 warning(s). That is correct behaviour, not a bug: the project README is not an awesome list, and the command walks up from the working directory to the nearest README.md. Always cd into a scratch list before trying commands by hand. This trap is why the driver builds its own list in a temp directory.
• opossum check cannot succeed in this container. The egress proxy refuses most hosts, so the scaffolded https://example.com entry returns Tunnel connection failed: 403 Forbidden and the command reports 0/1 links ok and exits 1. The link checker is fine — the network is filtered. pypi.org and raw.githubusercontent.com are reachable, which is what driver.py --network uses to test it positively (200 vs 404).
• --fetch and enrich silently degrade here. api.github.com is blocked, so opossum add <repo-url> --fetch prints warning: could not read owner/repo from GitHub, then still adds the entry using the repo name from the URL and no description. Exit code stays 0. Do not read that as the fetch feature being broken.
• A relative --bin needs the driver's resolution. Commands run with the scratch list as their working directory, so --bin .venv/bin/opossum is resolved to an absolute path first. Passing a relative path to any other tool that runs commands elsewhere will fail with FileNotFoundError.
• python3 -m opossum needs PYTHONPATH when its working directory is not the repo. The driver sets it; if you invoke the module yourself from a list directory, export PYTHONPATH=/home/user/opossum or use the venv binary.

Troubleshooting

• FileNotFoundError: '.venv/bin/opossum' from the driver: you passed a relative --bin to an older copy of the driver, or the venv does not exist. Run the Setup block, or drop --bin to use the python3 -m opossum fallback.
• no README.md was written — did 'opossum init' run?: the driver could not execute the binary at all. Check --bin points at something runnable; with no --bin, confirm python3 -c "import opossum" works from the repo.
• error: no README.md found, pass one with --path: you ran a command outside any list directory and above any README.md. cd into the list.
• pip install -e . says "does not appear to be a Python project": you ran it from the wrong directory. It needs the repo root, where pyproject.toml is.