tegwick
ea70a59610
Section 17 already defined what a registry does when the same id@version is republished; nothing defined what a *consumer* does. That is where namespace conflict actually bites — in the catalog, after installing from two registries. Identity is now registry-scoped: an id names a package within a registry, the way a path names a file within a repository. A local-first format with no signing, no federation and no central authority cannot enforce global uniqueness, and an unenforceable guarantee is worse than none — it invites consumers to conflate two packages that merely share a name. A qualified `<registry>:<id>` reference distinguishes them, and `:` is now barred from ids so the separator stays available. Installing the same id from two registries is therefore not a conflict. The catalog is namespaced by registry and keeps both. Ownership is registry policy, not package data. An optional `registry.yaml` names a registry and records namespace claims. Those claims are explicitly descriptive — a filesystem registry cannot authenticate a publisher, and `publish` says so rather than implying it checked. Keeping the claim out of packages leaves artifacts free of unverifiable assertions of authority, and means package semantics do not change when a hosted registry appears later. Spec: 3.2 (registry-scoped identity, qualified references), 17 (immutability scoped to a registry), 20.1 and 20.2 (new), 18 (registry-manifest validation), 21 (qualified references, reserved `local` name). Reference CLI: parse_reference, check_registry_name, read_registry_manifest, registry_name, namespace_policy; registry_package_path and catalog_package_path split; resolve_installed reports ambiguity and returns the source registry; iter_catalog; `add --as`; closed-namespace warning on publish. Tests 11 -> 21. The catalog layout changed. An existing catalog is detected and reported with instructions rather than failing as "package not found". Signing, trust scoring and federation remain non-goals and were not touched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Bjefh8NUiEiahN4JLwoSKM Assistant: claude-code Assistant-Model: opus Assistant-Process: 388925@bnt-lap001 Assistant-Session: 3507023f-e0fd-4a1e-9d90-a0d4217d1502
99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# canned-prompts seed
|
|
|
|
> **Collect, reuse and share prompts and prompt templates.**
|
|
|
|
This bundle contains a first project seed for `canned-prompts`:
|
|
|
|
- [`INTENT.md`](INTENT.md) — project mission, boundaries, principles, and success criteria.
|
|
- [`CannedPromptFormat-v0.1.md`](CannedPromptFormat-v0.1.md) — experimental package-format specification.
|
|
- [`reference/`](reference/) — deliberately small Python CLI implementing the basic lifecycle.
|
|
- [`examples/pqrst-estimate/`](examples/pqrst-estimate/) — a real package that can be used to exercise the implementation.
|
|
|
|
## Try the reference implementation
|
|
|
|
```bash
|
|
cd reference
|
|
python -m venv .venv
|
|
. .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
pip install -r requirements.txt
|
|
|
|
# add the included example to your local catalog
|
|
python canned_prompts.py add ../examples/pqrst-estimate
|
|
|
|
# find and inspect it
|
|
python canned_prompts.py search pqrst
|
|
python canned_prompts.py show practice/pqrst-estimate
|
|
|
|
# see how each input and parameter resolves, and where the value came from
|
|
python canned_prompts.py resolve practice/pqrst-estimate \
|
|
--set session_summary="Implemented feature X, read unfamiliar code, added tests."
|
|
|
|
# render it
|
|
python canned_prompts.py render practice/pqrst-estimate \
|
|
--set session_summary="Implemented feature X, read unfamiliar code, added tests."
|
|
|
|
# publish it to the local filesystem registry
|
|
python canned_prompts.py publish ../examples/pqrst-estimate
|
|
|
|
# remove the local catalog if you want to simulate another machine, then install
|
|
python canned_prompts.py install practice/pqrst-estimate --version 0.1.0
|
|
```
|
|
|
|
Packages added from a path are filed under the registry name `local`; packages
|
|
installed from a registry are filed under that registry's name. `search` prints
|
|
qualified references:
|
|
|
|
```text
|
|
house:practice/pqrst-estimate@0.1.0 PQRST Estimate
|
|
local:practice/pqrst-estimate@0.1.0 PQRST Estimate
|
|
```
|
|
|
|
By default the reference tool uses:
|
|
|
|
```text
|
|
~/.canned-prompts/catalog
|
|
~/.canned-prompts/registry
|
|
```
|
|
|
|
Override them with:
|
|
|
|
```text
|
|
CANNED_PROMPTS_HOME=/some/path
|
|
```
|
|
|
|
or command-level `--catalog` / `--registry` options.
|
|
|
|
## Resolution vs rendering
|
|
|
|
The format separates the two steps (`CannedPromptFormat-v0.1.md` § 5.1).
|
|
Resolution decides a value for every input and parameter and may be
|
|
non-deterministic; rendering substitutes those values and always is. An input
|
|
may declare a default that is either a static value or a *derived* one — a
|
|
prompt that a capable consumer may run to produce the value, declared without
|
|
naming any resolver or model.
|
|
|
|
This reference tool never calls a model, so it resolves supplied values and
|
|
static defaults only, and reports anything it cannot derive instead of
|
|
rendering a prompt with a silent hole in it.
|
|
|
|
## Registries and identity
|
|
|
|
An id names a package *within a registry* (`CannedPromptFormat-v0.1.md`
|
|
§ 3.2). The same id obtained from two registries may be two different
|
|
packages, so the catalog keeps them apart and a bare id that matches more than
|
|
one is reported as ambiguous rather than guessed. Qualify it when you need to:
|
|
|
|
```bash
|
|
python canned_prompts.py render house:practice/pqrst-estimate --set ...
|
|
```
|
|
|
|
A registry may describe itself with an optional `registry.yaml` naming it and
|
|
recording which namespaces are claimed and under what policy. Those claims are
|
|
descriptive: a filesystem registry cannot authenticate a publisher, and
|
|
signing and trust scoring are explicit non-goals. Ownership lives with the
|
|
registry rather than in the package, so no package carries an unverifiable
|
|
assertion of authority.
|
|
|
|
## Deliberate limitations
|
|
|
|
This seed has no hosted registry, model execution, authentication, network access, dependency resolver, or social features. `publish` and `install` operate on a filesystem registry so that the package semantics can be tested before infrastructure is built around them.
|