Port surviving design questions from the pico-package spec repo

The pico-package repo was the spec written a day before this implementation
started; it never shared history with it and stopped in Feb 2025. Most of it
is superseded by README.md and the notes here, but a few questions were only
ever recorded there, and its README had diverged into two versions -- one
local and uncommitted, one edited in the Gitea web UI.

Adds, as open questions: the missing GitLab/Gitea snippet providers; why
test_method is blocked behind signing; the spec's answer that a picopackage
holds text, not necessarily code; and the name collision on source_url, which
the pinning proposal wants for a third distinct meaning.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Dan Milne
2026-09-20 11:03:23 +10:00
co-authored by Claude Opus 5
parent d6419e9a31
commit f3557a1ec0
+29
View File
@@ -193,3 +193,32 @@ prompt injection in comments, aimed at the reviewer, is an expected attack.
language-agnostic. language-agnostic.
- **Unknown metadata keys** are preserved verbatim on rewrite (see - **Unknown metadata keys** are preserved verbatim on rewrite (see
`Metadata#extra`), so optional spec fields survive a tool that predates them. `Metadata#extra`), so optional spec fields survive a tool that predates them.
- **Snippet-hosting providers.** `Provider::PROVIDERS` covers GitHub Gist and
OpenGist; GitLab and Gitea snippets have no provider, so they fall through to
`DefaultProvider` and only work if the pasted URL already points at raw
content. Gitea matters now that picopackage itself is hosted on one. A Gitea
snippet is `https://<host>/snippets/<id>` → `…/snippets/<id>/raw`; GitLab is
`https://gitlab.com/(-/)?snippets/<id>` → `…/snippets/<id>/raw`. They sit on
opposite sides of the `handles_url?` contract: GitLab is a fixed host, so it
can answer `true` by pattern like `GithubGistProvider`, while a self-hosted
Gitea can be any domain and has to answer `:maybe` and prove itself by
fetching, like `OpenGistProvider`.
- **`test_method`.** `test_url` is carried in `Metadata`; `test_method` (the
name of a test defined inside the payload itself) was in the original spec and
never implemented. It only earns its place if `ppkg` can actually run it,
which means executing upstream code — so it's blocked behind the signing work
above, not just unimplemented.
- **Is a picopackage necessarily code?** The spec repo answered this and the
answer never made it here: “a scheme for sharing text content, often source
code… to track a single file of text”, packaging “code or configuration or
data”. So the scope is text, not code. Nothing in the tool assumes otherwise,
but nothing states it either, and it decides two things downstream: the
comment-style table above, and `test_url`/`test_method`, which only mean
anything for the code case.
- **`source_url` is an overloaded name.** The pinning proposal above wants
`source_url` for an immutable revision pointer. The spec repo already used
that name for something else — there, `url` was the human-readable page and
`source_url` the optional direct/raw link “if `url` isn’t parsable”, which is
the job `Provider` now does by resolution rather than by metadata. If pinning
is implemented under that name, it is a third meaning for the same key; worth
picking a fresh one (`pinned_url`, `revision_url`) instead.