subroutine 0.1.2__tar.gz → 0.1.3__tar.gz

{subroutine-0.1.2 → subroutine-0.1.3}/.github/workflows/ci.yml

@@ -29,11 +29,11 @@ jobs:
       # Full history and tags, because the release check compares this commit's migration
       # head against the one at the most recent tag. A shallow clone has neither, and the
       # check would find no previous tag and cheerfully pass every time.
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip
@@ -67,14 +67,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           # Tags, because the version is derived from them (`SR#234`). A shallow clone makes
           # the build warn and produce `0.1.dev1+g…` rather than fail, so this job would
           # install a package quietly claiming to be a version nobody released.
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip
@@ -102,9 +102,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: "22"
 
@@ -143,14 +143,14 @@ jobs:
           --health-retries 10
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           # Tags, because the version is derived from them (`SR#234`). A shallow clone makes
           # the build warn and produce `0.1.dev1+g…` rather than fail, so this job would
           # install a package quietly claiming to be a version nobody released.
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -177,14 +177,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           # Tags, because the version is derived from them (`SR#234`). A shallow clone makes
           # the build warn and produce `0.1.dev1+g…` rather than fail, so this job would
           # install a package quietly claiming to be a version nobody released.
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip

{subroutine-0.1.2 → subroutine-0.1.3}/.github/workflows/release.yml

@@ -51,14 +51,14 @@ jobs:
           --health-retries 10
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           # Tags, because the version is derived from them (`SR#234`). A shallow clone makes
           # the build warn and produce `0.1.dev1+g…` rather than fail, so this job would
           # install a package quietly claiming to be a version nobody released.
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip
@@ -83,11 +83,11 @@ jobs:
     steps:
       # Full history and tags: `check_release_notes.py` compares this commit's migration head
       # against the head at the previous tag, and a shallow clone has neither.
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
@@ -137,7 +137,7 @@ jobs:
       - name: Release notes
         run: python scripts/check_release_notes.py
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -159,7 +159,7 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -186,7 +186,7 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{subroutine-0.1.2 → subroutine-0.1.3}/CHANGELOG.md

@@ -12,6 +12,22 @@ The point of it is that you can *plan* a database upgrade instead of meeting one
 through installing something. See [docs/hosting.md](docs/hosting.md#upgrading) for what the
 upgrade involves.
 
+## 0.1.3 — 2026-08-02
+
+### Fixed
+
+- **The first install line no longer fails on the machine most people have.** `pip install
+  subroutine` outside a virtualenv is refused by Debian, Ubuntu and Fedora — PEP 668's
+  `externally-managed-environment` — and that was the first command in this README, the first
+  on the PyPI page, and the first thing anybody read. It is now `uv tool install subroutine`
+  or `pipx install subroutine`: they work on those systems, they put `subroutine` on your
+  `PATH` where an editor or an agent can launch it, and pipx is what Debian's own error
+  message tells you to use.
+
+  **This corrects the note at the end of 0.1.2 below**, which said `pip install subroutine`
+  remained right if you were only going to type commands yourself. That holds inside a
+  virtualenv you have activated, and nowhere else — which is not what it implied.
+
 ## 0.1.2 — 2026-08-02
 
 No migration notice: the schema head has not moved since 0.1.0. Nothing in the package itself

{subroutine-0.1.2 → subroutine-0.1.3}/CONTRIBUTING.md

@@ -16,6 +16,10 @@ That will change once the shape has settled, and this file will say so when it d
 - **Telling us it does not fit.** If you tried it and stopped, we would rather know why than
   not. An issue saying "I wanted X and there was no way to do it" is worth more than a guess.
 
+**A vulnerability is the exception, and please treat it as one.** An issue is public from the
+moment it is filed, so it is the one report that must not start there —
+[SECURITY.md](SECURITY.md) says where it should go instead.
+
 The rest of this file is kept for two reasons: an unsolicited pull request still needs the
 licence agreement below if it is ever taken, and the conventions are worth having if you are
 reading the code to decide whether to trust it.

{subroutine-0.1.2 → subroutine-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subroutine
-Version: 0.1.2
+Version: 0.1.3
 Summary: Project management for people and agents, in equal measure.
 Project-URL: Homepage, https://github.com/simonholliday/subroutine
 Project-URL: Issues, https://github.com/simonholliday/subroutine/issues
@@ -73,7 +73,7 @@ Three things you might want. Pick one; they compose.
 **A to-do list on your own machine.** Nothing to configure.
 
 ```console
-$ pip install subroutine
+$ uv tool install subroutine    # or: pipx install subroutine
 $ subroutine init
 $ subroutine add "Call the dentist before Sunday"
 $ subroutine today
@@ -84,7 +84,7 @@ practice — it keeps the backlog, records what it did, and adopts Subroutine in
 are already working on. **You never have to learn the CLI.**
 
 ```console
-$ uv tool install subroutine    # or pipx — your editor starts it, so it must be on your PATH
+$ uv tool install subroutine    # or: pipx install subroutine
 $ claude plugin marketplace add simonholliday/subroutine
 $ claude plugin install subroutine@subroutine
 ```
@@ -119,16 +119,20 @@ commands and `subroutine explain dates` covers the ideas behind them.
 Python 3.11+ and thirteen dependencies. Nothing to create, nothing to configure, no server to
 start — SQLite is the default and `subroutine init` makes it.
 
-`pip install subroutine` is fine if you are only going to type commands yourself. **If an
-editor or an agent is going to launch it, install it as a tool instead** — that is what puts
-`subroutine` on your `PATH`, where something other than your shell can find it:
+**Install it as a tool**, because that is what it is — an application, not a library. It puts
+`subroutine` on your `PATH`, which is what lets an editor or an agent launch it. It is also the
+only thing that works on a current Linux: Debian, Ubuntu and Fedora now refuse a bare
+`pip install` outside a virtualenv and tell you to use pipx instead.
 
 ```console
 $ uv tool install subroutine
 $ pipx install subroutine        # the same thing, if you have pipx rather than uv
 ```
 
-PostgreSQL when you outgrow SQLite — the extra goes on whichever of the three you used:
+`pip install subroutine` is still right *inside* a virtualenv you have activated — embedding it
+in something else, or working on it.
+
+PostgreSQL when you outgrow SQLite — the extra goes on whichever you used:
 
 ```console
 $ uv tool install "subroutine[postgres]"
@@ -352,6 +356,8 @@ Named plainly, because a tool that overstates itself wastes your afternoon:
 - **[docs/errors.md](docs/errors.md)** — every error code the API can return. Generated from
   the registry, so it cannot drift from the code.
 - **`GET /v1/docs/agent`** — the guide an agent should read first, written for that reader.
+- **[SECURITY.md](SECURITY.md)** — how to report a vulnerability privately, and what is in
+  scope. Not through an issue: an issue is public from the moment it is filed.
 
 The full specification — data model, API, permissions and agent design — is written but
 not yet published. It lands here once the API has settled enough to be worth reading.

{subroutine-0.1.2 → subroutine-0.1.3}/README.md

@@ -28,7 +28,7 @@ Three things you might want. Pick one; they compose.
 **A to-do list on your own machine.** Nothing to configure.
 
 ```console
-$ pip install subroutine
+$ uv tool install subroutine    # or: pipx install subroutine
 $ subroutine init
 $ subroutine add "Call the dentist before Sunday"
 $ subroutine today
@@ -39,7 +39,7 @@ practice — it keeps the backlog, records what it did, and adopts Subroutine in
 are already working on. **You never have to learn the CLI.**
 
 ```console
-$ uv tool install subroutine    # or pipx — your editor starts it, so it must be on your PATH
+$ uv tool install subroutine    # or: pipx install subroutine
 $ claude plugin marketplace add simonholliday/subroutine
 $ claude plugin install subroutine@subroutine
 ```
@@ -74,16 +74,20 @@ commands and `subroutine explain dates` covers the ideas behind them.
 Python 3.11+ and thirteen dependencies. Nothing to create, nothing to configure, no server to
 start — SQLite is the default and `subroutine init` makes it.
 
-`pip install subroutine` is fine if you are only going to type commands yourself. **If an
-editor or an agent is going to launch it, install it as a tool instead** — that is what puts
-`subroutine` on your `PATH`, where something other than your shell can find it:
+**Install it as a tool**, because that is what it is — an application, not a library. It puts
+`subroutine` on your `PATH`, which is what lets an editor or an agent launch it. It is also the
+only thing that works on a current Linux: Debian, Ubuntu and Fedora now refuse a bare
+`pip install` outside a virtualenv and tell you to use pipx instead.
 
 ```console
 $ uv tool install subroutine
 $ pipx install subroutine        # the same thing, if you have pipx rather than uv
 ```
 
-PostgreSQL when you outgrow SQLite — the extra goes on whichever of the three you used:
+`pip install subroutine` is still right *inside* a virtualenv you have activated — embedding it
+in something else, or working on it.
+
+PostgreSQL when you outgrow SQLite — the extra goes on whichever you used:
 
 ```console
 $ uv tool install "subroutine[postgres]"
@@ -307,6 +311,8 @@ Named plainly, because a tool that overstates itself wastes your afternoon:
 - **[docs/errors.md](docs/errors.md)** — every error code the API can return. Generated from
   the registry, so it cannot drift from the code.
 - **`GET /v1/docs/agent`** — the guide an agent should read first, written for that reader.
+- **[SECURITY.md](SECURITY.md)** — how to report a vulnerability privately, and what is in
+  scope. Not through an issue: an issue is public from the moment it is filed.
 
 The full specification — data model, API, permissions and agent design — is written but
 not yet published. It lands here once the API has settled enough to be worth reading.

subroutine-0.1.3/SECURITY.md

@@ -0,0 +1,74 @@
+# Security
+
+## Reporting a vulnerability
+
+**Please do not open an issue.** An issue is public from the moment it is filed, which for a
+vulnerability is the one thing that must not happen first.
+
+Use **[GitHub's private vulnerability reporting](https://github.com/simonholliday/subroutine/security/advisories/new)**
+— the *Report a vulnerability* button on the Security tab. It is private between you and the
+maintainer, it needs no email address on either side, and it keeps the whole conversation with
+the eventual advisory.
+
+If that is not available to you, write to **simon.holliday@protonmail.com** with `Subroutine` in
+the subject.
+
+**What helps:** the version (`subroutine --version`), whether it was reached over the HTTP API
+or the CLI, and the smallest sequence that shows the problem. A proof of concept is welcome and
+not required — a clear description of the flaw is worth more than a working exploit.
+
+## What to expect
+
+Subroutine is maintained by one person, so these are honest intentions rather than a
+service-level agreement:
+
+- **An acknowledgement within a few days.** If you have heard nothing in a week, assume it went
+  astray and send a reminder.
+- **An assessment, and the reasoning.** If it turns out not to be a vulnerability you will be
+  told why, rather than left waiting.
+- **Credit in the advisory** unless you would rather not be named.
+
+Please give a reasonable window before disclosing publicly. If a fix is taking longer than you
+think reasonable, say so — a deadline you have stated is easier to work to than one nobody
+mentioned.
+
+## What is in scope
+
+The code in this repository, and the current release on PyPI.
+
+Things that are worth reporting even though they may look like design decisions, because the
+boundary is exactly where mistakes hide:
+
+- **A credential doing more than it should.** A token that is wider than the person who issued
+  it, or that survives something meant to end it.
+- **Reading or writing across a boundary** — another workspace, a private project, another
+  user's items.
+- **Anything that reaches the database or the filesystem through an input** that was not
+  supposed to.
+- **A refusal that discloses.** "Forbidden" where the answer should be "not found" tells a
+  stranger something exists; the API is written to avoid that and a place it does not is a bug.
+
+## What is not
+
+- **Anything requiring an account you were given.** A member of a workspace can read that
+  workspace; that is the product working.
+- **`serve` bound to a wider interface with `--insecure`.** It refuses without TLS in front of
+  it and says why; overriding that is a deliberate act.
+- **A self-hosted instance's own configuration** — file permissions, a database on a shared
+  volume, a reverse proxy that terminates TLS and forwards over a network you do not trust.
+- **Dependency advisories with no reachable path here.** Do report one if you can show the path.
+
+## Supported versions
+
+**The most recent release**, which is the only version that gets a fix. Subroutine is `0.x`: it
+is early, the surface is still moving, and pretending to maintain several lines at once would be
+a promise nobody could keep. Upgrading is `uv tool upgrade subroutine` or `pipx upgrade
+subroutine` — whichever you installed it with — and then `subroutine upgrade` for the database.
+
+## One thing this project cannot do for you
+
+**Subroutine authenticates with bearer tokens and stores their SHA-256 hashes.** A token is
+shown once, at creation, and is unrecoverable afterwards by design. Nothing here can tell you
+what a token was, and nobody who has the database can either — but anybody who can *read* an
+instance's database can read every item in it. The database is a secret. `docs/hosting.md` says
+where it should live and what should be backing it up.

{subroutine-0.1.2 → subroutine-0.1.3}/plugins/subroutine/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "subroutine",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Project management for people and agents, in equal measure. Wires this session to a Subroutine instance and carries the working practice for using it well.",
   "author": {
     "name": "Simon Holliday",

subroutine-0.1.3/scripts/release.py

@@ -0,0 +1,198 @@
+"""Cut a release — one version, written everywhere it has to appear. Item ``#239``.
+
+**The number is a judgement and stays a human's.** Nothing here guesses whether a change is a
+patch or a minor; what it removes is the chance to decide 0.1.3 and then say it in only some of
+the places. ``#234`` took ``pyproject.toml`` out of that list by deriving the package version
+from the tag. Three remain and every one has to agree on a single commit:
+
+1. the git tag, which is what the package version is built from;
+2. ``plugin.json``, which Claude Code reads straight from a clone with no build step, so
+   nothing can derive it;
+3. the changelog heading, which is how a person finds out what they are upgrading into.
+
+**Two of the first three releases needed a corrective commit for exactly this** — 0.1.0's
+changelog still said *Unreleased*, and 0.1.2 was tagged with the manifest reading 0.1.1, which
+CI refused. Neither was carelessness; both were one step in a sequence somebody was holding in
+their head.
+
+**It refuses rather than repairs.** A dirty tree, a tag that exists, a version that goes
+backwards and a changelog with nothing unreleased in it are all reasons to stop and let a
+person look, because each means the release is not the thing they think it is.
+
+**It never pushes.** Publishing is outward-facing and belongs to whoever owns the repository;
+this stops at a commit and a tag, and prints the two commands that finish the job.
+"""
+
+import argparse
+import datetime
+import json
+import pathlib
+import re
+import subprocess
+import sys
+
+#: The repository, resolved from this file rather than from the working directory — the script
+#: is run from wherever somebody happens to be standing.
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+
+#: The two files that carry a version. The changelog's heading and the plugin's manifest; the
+#: tag is made rather than written, and `pyproject.toml` no longer has one at all (`#234`).
+CHANGELOG = ROOT / "CHANGELOG.md"
+PLUGIN = ROOT / "plugins" / "subroutine" / ".claude-plugin" / "plugin.json"
+
+#: What a version may look like. Deliberately narrow: three numbers, optionally a pre-release
+#: suffix. A tag is not the place to discover that somebody typed `v0.1.3` or `0.1` — the first
+#: would produce `vv0.1.3` and the second a version PyPI sorts in a way nobody expects.
+VERSION = re.compile(r"^\d+\.\d+\.\d+(?:[-.][0-9A-Za-z.]+)?$")
+
+#: The heading this promotes. **An `Unreleased` section has to already exist**, which is the
+#: point rather than a limitation: it means the changelog was written while the work was fresh,
+#: by whoever did it, instead of at the moment of release by whoever is in a hurry. The
+#: changelog's own preamble already describes the file this way.
+UNRELEASED = re.compile(r"^##\s+Unreleased\b.*$", re.IGNORECASE | re.MULTILINE)
+
+
+def main (argv: list[str] | None = None) -> int:
+	"""Write ``version`` into every place a release names itself, then commit and tag it."""
+
+	parsed = _arguments(argv)
+	version = parsed.version
+
+	if not VERSION.match(version):
+		return _refuse(f"{version!r} is not a version. Write it as 1.2.3, with no leading 'v'.")
+
+	problem = _reasons_to_stop(version)
+
+	if problem is not None:
+		return _refuse(problem)
+
+	on = parsed.date or datetime.date.today().isoformat()
+	changelog = UNRELEASED.sub(f"## {version} — {on}", CHANGELOG.read_text(encoding="utf-8"), 1)
+
+	if parsed.dry_run:
+		print(f"Would release {version} ({on}):")
+		print(f"  {CHANGELOG.name}: the Unreleased heading becomes '## {version} — {on}'")
+		print(f"  {PLUGIN.name}: version becomes {version}")
+		print(f"  commit both, then tag v{version}")
+
+		return 0
+
+	CHANGELOG.write_text(changelog, encoding="utf-8")
+	_write_plugin_version(version)
+
+	# **`check_release_notes.py` is deliberately not run here.** It compares this commit's
+	# migration head against the head at the most recent tag — which is the same comparison CI
+	# makes on every push to main, against the same previous tag. So a missing migration notice
+	# is already refused before anybody reaches this script, and running it again would couple
+	# two scripts for an answer that has been available since the commit that moved the head.
+	_git("add", str(CHANGELOG), str(PLUGIN))
+	_git("commit", "-m", f"Release {version}", "-m", f"See CHANGELOG.md for what {version} contains.")
+	_git("tag", "-a", f"v{version}", "-m", f"Subroutine {version}")
+
+	print(f"Committed and tagged v{version}. Nothing has been pushed. To publish:")
+	print("  git push")
+	print(f"  git push origin v{version}")
+
+	return 0
+
+
+def _arguments (argv: list[str] | None) -> argparse.Namespace:
+	"""Read the version to cut, and the two options that exist for testing it."""
+
+	parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+	parser.add_argument("version", help="the release, as 1.2.3, with no leading 'v'")
+	parser.add_argument(
+		"--dry-run", action="store_true", help="say what would change and touch nothing"
+	)
+
+	# Passed in rather than always read off the clock, so a test can assert the heading it
+	# expects instead of building today's date twice and comparing a program to itself.
+	parser.add_argument("--date", help="the date to stamp, as YYYY-MM-DD. Defaults to today.")
+
+	return parser.parse_args(argv)
+
+
+def _reasons_to_stop (version: str) -> str | None:
+	"""Return why this release must not be cut, or ``None`` if there is no reason."""
+
+	if _git("status", "--porcelain").strip():
+		return "the working tree has changes. Commit or stash them, so the tag names a state."
+
+	if _git("tag", "--list", f"v{version}").strip():
+		return f"v{version} already exists. A released version is never re-cut — choose the next one."
+
+	if not UNRELEASED.search(CHANGELOG.read_text(encoding="utf-8")):
+		return (
+			f"{CHANGELOG.name} has no '## Unreleased' section, so this release would say "
+			f"nothing about itself. Write what changed under one, then cut it."
+		)
+
+	latest = _latest_version()
+	proposed = _ordered(version)
+	previous = _ordered(latest) if latest is not None else None
+
+	# **Only when both parse as plain numbers.** A pre-release suffix makes ordering a question
+	# with more than one defensible answer, and guessing it here would refuse a release
+	# somebody meant. Refusing what is unambiguously backwards is the whole value.
+	if proposed is not None and previous is not None and proposed <= previous:
+		return f"{version} is not ahead of {latest}, the most recent tag."
+
+	return None
+
+
+def _ordered (version: str) -> tuple[int, ...] | None:
+	"""Return a version as numbers for comparison, or ``None`` if it is not purely numeric."""
+
+	parts = version.split(".")
+
+	if len(parts) != 3 or not all(part.isdigit() for part in parts):
+		return None
+
+	return tuple(int(part) for part in parts)
+
+
+def _latest_version () -> str | None:
+	"""Return the newest release tag with its ``v`` removed, or ``None`` on a repository with none."""
+
+	found = subprocess.run(
+		["git", "describe", "--tags", "--abbrev=0", "--match", "v*"],
+		cwd=ROOT, capture_output=True, text=True, check=False,
+	)
+
+	if found.returncode != 0 or not found.stdout.strip():
+		return None
+
+	return found.stdout.strip().removeprefix("v")
+
+
+def _write_plugin_version (version: str) -> None:
+	"""Set the plugin manifest's version, leaving every other key and the formatting alone.
+
+	Rewritten through ``json`` rather than by pattern, because a manifest that stops being
+	valid JSON is one nobody can install and the failure arrives at a stranger.
+	"""
+
+	manifest = json.loads(PLUGIN.read_text(encoding="utf-8"))
+	manifest["version"] = version
+
+	PLUGIN.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+
+def _git (*arguments: str) -> str:
+	"""Run one git command in the repository and return its output, raising if it fails."""
+
+	return subprocess.run(
+		["git", *arguments], cwd=ROOT, capture_output=True, text=True, check=True
+	).stdout
+
+
+def _refuse (message: str) -> int:
+	"""Say why the release is not being cut, and exit non-zero."""
+
+	print(f"Not releasing: {message}", file=sys.stderr)
+
+	return 1
+
+
+if __name__ == "__main__":
+	raise SystemExit(main())