typedstandards 0.1.0__tar.gz

typedstandards-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# The vendored CLI, written by hatch_build.py at every wheel or editable build.
+/src/typedstandards/_vendor/
+/node_modules/
+/dist/
+/build/
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/

typedstandards-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.0 — 2026-10-04
+
+- `sign`, `withdraw`, `attest`, `view` and `verify`: pass-throughs to `@typedstandards/cli` 0.2.0,
+  vendored into the wheel at build time and run as a child process with the inherited environment.
+  Each returns the CLI's stdout parsed as JSON.
+- A Node locator: `TYPEDSTANDARDS_NODE`, then `node` on `PATH`; floor 20.19.0.
+- Exit codes 1 to 4 raise `VerificationError`, `UsageError`, `SeedError` and `InternalError`, under
+  `CliError`; a missing or old Node raises `NodeLocatorError`.
+- `verify` drops a bundle's top-level `trustRegistry` before the CLI sees it (typedstandards#136).
+- `CLI_VERSION = "0.2.0"` and `cli_version()`.
+- `pin(url)`: fetches once and returns the bytes with a `queries[]` retrieval entry (`url`,
+  `sha256`, `bytes`, `httpStatus`, `fetchedAt`; `rowsUpdatedAt` and `datasetId` for a portal
+  resource); `save=` writes both.
+- `badge_cell`: the verifier badge as a notebook's first cell, or a `mo.md` cell's source; no hash
+  and no time in the cell.
+- `comparison_cell`: the spec §8.7.4 comparison cell, appended as the last cell; values must be
+  literals.
+- `sidecar`: `<artifact file name>.record.yaml` from `view`'s output, without `package` and
+  `trustRegistry`.
+- `show`: HTML for Jupyter (`_repr_html_`) or Marimo (`mo.Html`) from a record and its
+  `verify --json` result.
+- `badge_cell` no longer reads a URL's host and port as a time: `https://192.168.1.10:8080/…` is
+  accepted. A date or time in the URL's path, query or fragment (as written or percent-encoded) or
+  in a fact is refused.
+- README: only the calls that run the CLI need Node (the five commands, `cli_version()`, and
+  `show` without a result); its links are absolute, so they resolve on the PyPI page.

typedstandards-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Storey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typedstandards-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: typedstandards
+Version: 0.1.0
+Summary: Sign, withdraw, attest to, build views of and verify Typed Standards records from Python, through @typedstandards/cli as a child process.
+Project-URL: Homepage, https://github.com/npstorey/typedstandards-python
+Project-URL: Issues, https://github.com/npstorey/typedstandards-python/issues
+Author: Nathan Storey
+License-Expression: MIT
+License-File: LICENSE
+Keywords: notebook,provenance,signing,typed-standards,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# typedstandards
+
+Sign, withdraw, attest to, build views of and verify [Typed Standards](https://typedstandards.org)
+records from Python. The package drives
+[`@typedstandards/cli`](https://www.npmjs.com/package/@typedstandards/cli) 0.2.0 as a child
+process. It holds no key, reads no signing seed, and computes none of the format's hashes: the CLI
+does all of the format's work.
+
+## Install
+
+```sh
+pip install typedstandards        # or: uv add typedstandards
+```
+
+The wheel carries the CLI and its dependencies (vendored at build time from this repository's
+`package-lock.json`), so installing needs nothing from npm. Running needs Node.js: the wrapper and
+the CLI need Node 20.19 or later, and a `@typedstandards/host-core` site build needs Node 22 or
+later.
+
+The wrapper looks for Node in this order:
+
+1. `TYPEDSTANDARDS_NODE`, when set: the path (or name on `PATH`) of a Node binary;
+2. `node` on `PATH`.
+
+Only the calls that run the CLI need Node: `sign`, `withdraw`, `attest`, `view`, `verify`,
+`cli_version()`, and `show` without a precomputed result. With no Node, or one older than 20.19.0,
+each of those raises `typedstandards.NodeLocatorError`, whose message names the floor and
+`TYPEDSTANDARDS_NODE`. `pin`, `badge_cell`, `comparison_cell`, `sidecar` and
+`show(record, result)` run without Node.
+
+Linux and macOS are tested. Windows is untested.
+
+## The signing key
+
+The CLI reads the signing seed (the standard base64 of a 32-byte Ed25519 seed) from one environment
+variable, `TYPEDSTANDARDS_SIGNING_SEED_B64`, and from nowhere else. The wrapper never reads it: it
+starts the CLI with the environment it inherited, and passes no environment of its own. Set the
+variable from a secret store for the process that signs, for example:
+
+```sh
+op run --env-file=signing.env -- jupyter lab
+```
+
+where `signing.env` maps `TYPEDSTANDARDS_SIGNING_SEED_B64` to a secret reference. Make a new seed
+with:
+
+```sh
+openssl rand -base64 32
+```
+
+Only `sign`, `withdraw` and `attest` need it; `view` and `verify` do not.
+
+## Use
+
+```python
+import typedstandards as ts
+
+signed = ts.sign(
+    {
+        "type": "content/analysis/v1",
+        "producerProfile": "scripted-recomputation/example",
+        "captureMethod": "script-run",
+        "prompt": "Recompute the summary table.",
+        "promptVisibility": "full_text",
+        "queries": [],
+        "dataSources": [],
+        "cost": {"model": "none"},
+        "skillMetadata": {},
+        "trace": {},
+        "signer": {"bindingTier": "pseudonymous", "displayName": "Example analyst"},
+    },
+    output_file="analysis.ipynb",
+)  # signed inline under raw-bytes/v1
+
+bundle = ts.view(signed, visibility="public", title="Example analysis")
+result = ts.verify(bundle)  # {ok, nodeId, failures, checks, lifecycle}
+```
+
+Each function returns the CLI's stdout parsed as JSON. An input may be a mapping (sent to the CLI
+as JSON on standard input) or the path of a JSON file.
+
+| Function | CLI command | Returns |
+|---|---|---|
+| `sign(input, *, output_file=None, output_url=None, content_type=None)` | `sign` | `{package, envelopeHash, signature}` |
+| `withdraw(input)` | `withdraw` | `{node, nodeId, signature}` |
+| `attest(input)` | `attest` | `{node, nodeId, signature}` |
+| `view(signed, *, visibility, attestations=(), trust_registry_url=None, package_url=None, title=None)` | `view` | the commitment view, package inline |
+| `verify(input, *, blobs=(), full=True)` | `verify` (`--json` when `full`) | `{ok, nodeId, failures, checks, lifecycle}` |
+
+`view` writes the mappings it is given to temporary files, removed before it returns. The CLI's
+[README](https://github.com/npstorey/typedstandards/tree/main/packages/cli#readme) describes each
+command's inputs. What the CLI prints on stderr when it succeeds (attention readings, such as an
+offline `registry_unavailable`) is logged at INFO on the `typedstandards` logger.
+
+`typedstandards.CLI_VERSION` is the version of the vendored CLI (`"0.2.0"`), and
+`typedstandards.cli_version()` asks the vendored CLI for it.
+
+### Errors
+
+A non-zero exit raises a subclass of `typedstandards.CliError`, which carries `exit_code`, `stderr`
+(the CLI's standard error) and `command`:
+
+| Exit | Exception | Meaning |
+|---|---|---|
+| 1 | `VerificationError` | a record, or the CLI's own result, did not verify; for `verify`, `.document` is the `{ok: false, ...}` verdict |
+| 2 | `UsageError` | an argument or an input is wrong |
+| 3 | `SeedError` | the seed's variable is missing or malformed |
+| 4 | `InternalError` | an internal error in the CLI |
+
+### Verifying a served bundle
+
+`@typedstandards/host-core` inlines a top-level `trustRegistry` in every bundle it serves under a
+registry, and CLI 0.2.0's `verify` refuses that key
+([typedstandards#136](https://github.com/npstorey/typedstandards/issues/136)). Until the wrapper
+pins a CLI that accepts it, `verify` drops a bundle's top-level `trustRegistry` before the CLI
+sees the bundle, and changes nothing else. A test pins that the CLI receives the same document
+minus that one key.
+
+## Notebook helpers
+
+Five helpers arrange and render around the CLI. None of them computes one of the format's hashes,
+reads the seed, or verifies anything itself.
+
+```python
+import io
+import pandas as pd
+import typedstandards as ts
+
+# Before signing: pin each input, and add the reader's badge and the comparison cell.
+content, entry = ts.pin("https://data.example.org/resource/abcd-1234.csv", licence="CC-BY-4.0")
+frame = pd.read_csv(io.BytesIO(content))
+
+ts.badge_cell(
+    "https://records.example.org/bundles/analysis.bundle.json",
+    capture_method="script-run",
+    notebook="analysis.ipynb",
+)
+ts.comparison_cell(
+    "analysis.ipynb",
+    {"rows": 1204, "mean_fare": 13.75},
+    recompute="recompute_key_metrics()",
+    captured_at="2026-10-03T12:00:00Z",
+)
+
+# Sign (record is an envelope input like the one under Use), then serve and show.
+signed = ts.sign({**record, "queries": [entry]}, output_file="analysis.ipynb")
+bundle = ts.view(signed, visibility="public", title="Example analysis")
+ts.sidecar(bundle, "analysis.ipynb")  # writes analysis.ipynb.record.yaml
+ts.show(bundle)  # in Jupyter; ts.show(bundle, marimo=True) in Marimo
+```
+
+- **`pin(url, *, licence=None, dataset_id=None, portal_metadata=None, save=None, ...)`** fetches
+  `url` once and returns `Pinned(content, entry)`: the response body, and a retrieval entry for
+  the record's `queries[]` with `url`, `sha256` (of the body), `bytes`, `httpStatus` and
+  `fetchedAt` (ISO 8601 UTC) under `arguments`. A URL shaped like an open-data portal resource
+  (`…/resource/<id>[.ext]` or `…/api/views/<id>/rows.<ext>`, `<id>` being `xxxx-xxxx`) gets a
+  second request to `<origin>/api/views/<id>`, and the entry gains the portal's `rowsUpdatedAt`
+  (epoch seconds) and `datasetId`. A response that is not 2xx raises. `save=` writes the bytes
+  to that path and the entry to `<path>.pin.json`. The SHA-256 is the one digest the package
+  computes: a signed assertion in `queries[]` that no check recomputes.
+- **`badge_cell(bundle_url, *, capture_method, notebook=None, host=None, marimo=False)`** writes
+  the verifier badge, linked to `https://typedstandards.org/verify?url=<the bundle URL,
+  percent-encoded>` as `@typedstandards/host-core` writes it, above a two-row table (the host and
+  the capture method). With `notebook`, it is inserted as the notebook's first cell (id
+  `typedstandards-badge` on nbformat 4.5). With `marimo=True`, it returns the source of a
+  `mo.md(...)` cell to paste into the app. The cell is written before signing and is part of the
+  signed bytes, so it names no hash and no time; a URL or value holding a 64-hex string, a date or
+  a time is refused. The URL's host and port are not read as a time (`192.168.1.10:8080` is
+  accepted).
+- **`comparison_cell(notebook, values, *, recompute, captured_at)`** appends the comparison cell
+  of spec §8.7.4 as the last cell (id `typedstandards-comparison`): the values as Python literals,
+  `current = <recompute>`, and a loop that prints each delta. Values are `None`, `bool`, `int`,
+  finite `float`, `str`, and lists and str-keyed dicts of those; anything else is refused.
+- **`sidecar(view, artifact, *, directory=None)`** writes the commitment view as YAML (spec
+  §8.8.3) beside the artifact: every field `view` printed except the inline `package` and a
+  served bundle's `trustRegistry`, which are not §8.8.1 fields. The file is named
+  `<artifact's file name>.record.yaml`, extension kept (`analysis.ipynb.record.yaml`): the spec's
+  `<artifact-basename>` does not say whether the extension stays, and keeping it is the POSIX
+  basename and cannot collide when two artifacts share a stem (`analysis.ipynb` beside
+  `analysis.py`).
+- **`show(record, result=None, *, role_path=("role",), marimo=False)`** renders a record (what
+  `view` or `sign` printed) with its `verify --json` result: the type, the role, the signer,
+  the hash, `createdAt`, the `vcsRef` (marked as asserted and not fetched), the status with its
+  reason or successor, one line per check, and a sentence saying that verification does not say
+  the analysis is correct. Without `result` it runs `verify`. In Jupyter it returns an object
+  with `_repr_html_`; with `marimo=True`, `mo.Html`. The role is a signed assertion the signer
+  made, read from the package's `extensions` at `role_path` (by default `extensions["role"]`, a
+  string or a list of strings); `show` labels it as the signer's and checks nothing about it.
+
+The notebook helpers edit the notebook as JSON, splicing the new cell into `cells` so every
+other byte of the file stays as written. `httpx` is imported only inside `pin`, PyYAML only
+inside `sidecar`, and `marimo` only inside a Marimo call; `IPython`, `marimo` and `nbformat`
+are not dependencies.
+
+## Versions
+
+Each wrapper release pins one CLI version exactly. A CLI upgrade reaches users as a wrapper release
+that moves the pin.
+
+## Development
+
+See [CLAUDE.md](https://github.com/npstorey/typedstandards-python/blob/main/CLAUDE.md) for the development loop and the checks CI runs.
+
+## License
+
+MIT. The wheel also carries each vendored npm package's own licence file: five are MIT, and
+`canonicalize` is Apache-2.0.

typedstandards-0.1.0/README.md

@@ -0,0 +1,207 @@
+# typedstandards
+
+Sign, withdraw, attest to, build views of and verify [Typed Standards](https://typedstandards.org)
+records from Python. The package drives
+[`@typedstandards/cli`](https://www.npmjs.com/package/@typedstandards/cli) 0.2.0 as a child
+process. It holds no key, reads no signing seed, and computes none of the format's hashes: the CLI
+does all of the format's work.
+
+## Install
+
+```sh
+pip install typedstandards        # or: uv add typedstandards
+```
+
+The wheel carries the CLI and its dependencies (vendored at build time from this repository's
+`package-lock.json`), so installing needs nothing from npm. Running needs Node.js: the wrapper and
+the CLI need Node 20.19 or later, and a `@typedstandards/host-core` site build needs Node 22 or
+later.
+
+The wrapper looks for Node in this order:
+
+1. `TYPEDSTANDARDS_NODE`, when set: the path (or name on `PATH`) of a Node binary;
+2. `node` on `PATH`.
+
+Only the calls that run the CLI need Node: `sign`, `withdraw`, `attest`, `view`, `verify`,
+`cli_version()`, and `show` without a precomputed result. With no Node, or one older than 20.19.0,
+each of those raises `typedstandards.NodeLocatorError`, whose message names the floor and
+`TYPEDSTANDARDS_NODE`. `pin`, `badge_cell`, `comparison_cell`, `sidecar` and
+`show(record, result)` run without Node.
+
+Linux and macOS are tested. Windows is untested.
+
+## The signing key
+
+The CLI reads the signing seed (the standard base64 of a 32-byte Ed25519 seed) from one environment
+variable, `TYPEDSTANDARDS_SIGNING_SEED_B64`, and from nowhere else. The wrapper never reads it: it
+starts the CLI with the environment it inherited, and passes no environment of its own. Set the
+variable from a secret store for the process that signs, for example:
+
+```sh
+op run --env-file=signing.env -- jupyter lab
+```
+
+where `signing.env` maps `TYPEDSTANDARDS_SIGNING_SEED_B64` to a secret reference. Make a new seed
+with:
+
+```sh
+openssl rand -base64 32
+```
+
+Only `sign`, `withdraw` and `attest` need it; `view` and `verify` do not.
+
+## Use
+
+```python
+import typedstandards as ts
+
+signed = ts.sign(
+    {
+        "type": "content/analysis/v1",
+        "producerProfile": "scripted-recomputation/example",
+        "captureMethod": "script-run",
+        "prompt": "Recompute the summary table.",
+        "promptVisibility": "full_text",
+        "queries": [],
+        "dataSources": [],
+        "cost": {"model": "none"},
+        "skillMetadata": {},
+        "trace": {},
+        "signer": {"bindingTier": "pseudonymous", "displayName": "Example analyst"},
+    },
+    output_file="analysis.ipynb",
+)  # signed inline under raw-bytes/v1
+
+bundle = ts.view(signed, visibility="public", title="Example analysis")
+result = ts.verify(bundle)  # {ok, nodeId, failures, checks, lifecycle}
+```
+
+Each function returns the CLI's stdout parsed as JSON. An input may be a mapping (sent to the CLI
+as JSON on standard input) or the path of a JSON file.
+
+| Function | CLI command | Returns |
+|---|---|---|
+| `sign(input, *, output_file=None, output_url=None, content_type=None)` | `sign` | `{package, envelopeHash, signature}` |
+| `withdraw(input)` | `withdraw` | `{node, nodeId, signature}` |
+| `attest(input)` | `attest` | `{node, nodeId, signature}` |
+| `view(signed, *, visibility, attestations=(), trust_registry_url=None, package_url=None, title=None)` | `view` | the commitment view, package inline |
+| `verify(input, *, blobs=(), full=True)` | `verify` (`--json` when `full`) | `{ok, nodeId, failures, checks, lifecycle}` |
+
+`view` writes the mappings it is given to temporary files, removed before it returns. The CLI's
+[README](https://github.com/npstorey/typedstandards/tree/main/packages/cli#readme) describes each
+command's inputs. What the CLI prints on stderr when it succeeds (attention readings, such as an
+offline `registry_unavailable`) is logged at INFO on the `typedstandards` logger.
+
+`typedstandards.CLI_VERSION` is the version of the vendored CLI (`"0.2.0"`), and
+`typedstandards.cli_version()` asks the vendored CLI for it.
+
+### Errors
+
+A non-zero exit raises a subclass of `typedstandards.CliError`, which carries `exit_code`, `stderr`
+(the CLI's standard error) and `command`:
+
+| Exit | Exception | Meaning |
+|---|---|---|
+| 1 | `VerificationError` | a record, or the CLI's own result, did not verify; for `verify`, `.document` is the `{ok: false, ...}` verdict |
+| 2 | `UsageError` | an argument or an input is wrong |
+| 3 | `SeedError` | the seed's variable is missing or malformed |
+| 4 | `InternalError` | an internal error in the CLI |
+
+### Verifying a served bundle
+
+`@typedstandards/host-core` inlines a top-level `trustRegistry` in every bundle it serves under a
+registry, and CLI 0.2.0's `verify` refuses that key
+([typedstandards#136](https://github.com/npstorey/typedstandards/issues/136)). Until the wrapper
+pins a CLI that accepts it, `verify` drops a bundle's top-level `trustRegistry` before the CLI
+sees the bundle, and changes nothing else. A test pins that the CLI receives the same document
+minus that one key.
+
+## Notebook helpers
+
+Five helpers arrange and render around the CLI. None of them computes one of the format's hashes,
+reads the seed, or verifies anything itself.
+
+```python
+import io
+import pandas as pd
+import typedstandards as ts
+
+# Before signing: pin each input, and add the reader's badge and the comparison cell.
+content, entry = ts.pin("https://data.example.org/resource/abcd-1234.csv", licence="CC-BY-4.0")
+frame = pd.read_csv(io.BytesIO(content))
+
+ts.badge_cell(
+    "https://records.example.org/bundles/analysis.bundle.json",
+    capture_method="script-run",
+    notebook="analysis.ipynb",
+)
+ts.comparison_cell(
+    "analysis.ipynb",
+    {"rows": 1204, "mean_fare": 13.75},
+    recompute="recompute_key_metrics()",
+    captured_at="2026-10-03T12:00:00Z",
+)
+
+# Sign (record is an envelope input like the one under Use), then serve and show.
+signed = ts.sign({**record, "queries": [entry]}, output_file="analysis.ipynb")
+bundle = ts.view(signed, visibility="public", title="Example analysis")
+ts.sidecar(bundle, "analysis.ipynb")  # writes analysis.ipynb.record.yaml
+ts.show(bundle)  # in Jupyter; ts.show(bundle, marimo=True) in Marimo
+```
+
+- **`pin(url, *, licence=None, dataset_id=None, portal_metadata=None, save=None, ...)`** fetches
+  `url` once and returns `Pinned(content, entry)`: the response body, and a retrieval entry for
+  the record's `queries[]` with `url`, `sha256` (of the body), `bytes`, `httpStatus` and
+  `fetchedAt` (ISO 8601 UTC) under `arguments`. A URL shaped like an open-data portal resource
+  (`…/resource/<id>[.ext]` or `…/api/views/<id>/rows.<ext>`, `<id>` being `xxxx-xxxx`) gets a
+  second request to `<origin>/api/views/<id>`, and the entry gains the portal's `rowsUpdatedAt`
+  (epoch seconds) and `datasetId`. A response that is not 2xx raises. `save=` writes the bytes
+  to that path and the entry to `<path>.pin.json`. The SHA-256 is the one digest the package
+  computes: a signed assertion in `queries[]` that no check recomputes.
+- **`badge_cell(bundle_url, *, capture_method, notebook=None, host=None, marimo=False)`** writes
+  the verifier badge, linked to `https://typedstandards.org/verify?url=<the bundle URL,
+  percent-encoded>` as `@typedstandards/host-core` writes it, above a two-row table (the host and
+  the capture method). With `notebook`, it is inserted as the notebook's first cell (id
+  `typedstandards-badge` on nbformat 4.5). With `marimo=True`, it returns the source of a
+  `mo.md(...)` cell to paste into the app. The cell is written before signing and is part of the
+  signed bytes, so it names no hash and no time; a URL or value holding a 64-hex string, a date or
+  a time is refused. The URL's host and port are not read as a time (`192.168.1.10:8080` is
+  accepted).
+- **`comparison_cell(notebook, values, *, recompute, captured_at)`** appends the comparison cell
+  of spec §8.7.4 as the last cell (id `typedstandards-comparison`): the values as Python literals,
+  `current = <recompute>`, and a loop that prints each delta. Values are `None`, `bool`, `int`,
+  finite `float`, `str`, and lists and str-keyed dicts of those; anything else is refused.
+- **`sidecar(view, artifact, *, directory=None)`** writes the commitment view as YAML (spec
+  §8.8.3) beside the artifact: every field `view` printed except the inline `package` and a
+  served bundle's `trustRegistry`, which are not §8.8.1 fields. The file is named
+  `<artifact's file name>.record.yaml`, extension kept (`analysis.ipynb.record.yaml`): the spec's
+  `<artifact-basename>` does not say whether the extension stays, and keeping it is the POSIX
+  basename and cannot collide when two artifacts share a stem (`analysis.ipynb` beside
+  `analysis.py`).
+- **`show(record, result=None, *, role_path=("role",), marimo=False)`** renders a record (what
+  `view` or `sign` printed) with its `verify --json` result: the type, the role, the signer,
+  the hash, `createdAt`, the `vcsRef` (marked as asserted and not fetched), the status with its
+  reason or successor, one line per check, and a sentence saying that verification does not say
+  the analysis is correct. Without `result` it runs `verify`. In Jupyter it returns an object
+  with `_repr_html_`; with `marimo=True`, `mo.Html`. The role is a signed assertion the signer
+  made, read from the package's `extensions` at `role_path` (by default `extensions["role"]`, a
+  string or a list of strings); `show` labels it as the signer's and checks nothing about it.
+
+The notebook helpers edit the notebook as JSON, splicing the new cell into `cells` so every
+other byte of the file stays as written. `httpx` is imported only inside `pin`, PyYAML only
+inside `sidecar`, and `marimo` only inside a Marimo call; `IPython`, `marimo` and `nbformat`
+are not dependencies.
+
+## Versions
+
+Each wrapper release pins one CLI version exactly. A CLI upgrade reaches users as a wrapper release
+that moves the pin.
+
+## Development
+
+See [CLAUDE.md](https://github.com/npstorey/typedstandards-python/blob/main/CLAUDE.md) for the development loop and the checks CI runs.
+
+## License
+
+MIT. The wheel also carries each vendored npm package's own licence file: five are MIT, and
+`canonicalize` is Apache-2.0.

typedstandards-0.1.0/hatch_build.py

@@ -0,0 +1,62 @@
+"""Vendor @typedstandards/cli into the wheel (G0 D1 = A).
+
+At every wheel build, standard or editable, this hook copies ``package.json`` and
+``package-lock.json`` into ``src/typedstandards/_vendor/`` and runs
+``npm ci --omit=dev --ignore-scripts`` there. The resulting ``node_modules`` tree, with
+each package's own licence file, ships inside the wheel, so an installed wheel needs Node
+and nothing from npm. An editable install (``uv sync``) runs the same hook, so tests drive
+the same tree a user gets.
+
+Building needs ``npm`` on ``PATH`` and the npm registry; installing the wheel needs neither.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+VENDOR = Path("src") / "typedstandards" / "_vendor"
+LICENCE_NAMES = ("LICENSE", "LICENSE.md", "LICENSE.txt", "LICENCE", "LICENCE.md", "LICENCE.txt")
+
+
+class VendorCliHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if self.target_name != "wheel":
+            return
+        root = Path(self.root)
+        vendor = root / VENDOR
+        npm = shutil.which("npm")
+        if npm is None:
+            raise RuntimeError(
+                "building typedstandards needs npm on PATH: the build vendors @typedstandards/cli "
+                "with `npm ci --omit=dev --ignore-scripts` (installing the built wheel does not)"
+            )
+        if vendor.exists():
+            shutil.rmtree(vendor)
+        vendor.mkdir(parents=True)
+        for name in ("package.json", "package-lock.json"):
+            shutil.copyfile(root / name, vendor / name)
+        self.app.display_info(f"vendoring @typedstandards/cli: npm ci --omit=dev --ignore-scripts in {VENDOR}")
+        subprocess.run(
+            [npm, "ci", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund"],
+            cwd=vendor,
+            check=True,
+        )
+        modules = vendor / "node_modules"
+        # npm's .bin holds symlinks, which a wheel cannot carry; the wrapper runs the CLI's
+        # entry file with node, never through .bin.
+        shutil.rmtree(modules / ".bin", ignore_errors=True)
+        lock = json.loads((vendor / "package-lock.json").read_text(encoding="utf-8"))
+        for key in lock["packages"]:
+            if not key:
+                continue
+            package_dir = vendor / key
+            if not any((package_dir / name).is_file() for name in LICENCE_NAMES):
+                raise RuntimeError(f"{key} ships no licence file; the wheel must carry each vendored package's licence")

typedstandards-0.1.0/package-lock.json

@@ -0,0 +1,96 @@
+{
+  "name": "typedstandards-python-vendored-cli",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "typedstandards-python-vendored-cli",
+      "license": "MIT",
+      "dependencies": {
+        "@typedstandards/cli": "0.2.0"
+      }
+    },
+    "node_modules/@noble/curves": {
+      "version": "2.4.0",
+      "resolved": "https://registry.npmjs.org/@noble/curves/-/curves-2.4.0.tgz",
+      "integrity": "sha512-P4/62zrgfH33CneE3Dn4WhJVA22YUU0eR51wKIan4NVRvwsA0YnPTwWGpNbpuacSujmSFLvyzpyuR30+fbq2Ew==",
+      "license": "MIT",
+      "dependencies": {
+        "@noble/hashes": "2.4.0"
+      },
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@noble/hashes": {
+      "version": "2.4.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-2.4.0.tgz",
+      "integrity": "sha512-X5XaVWZIBCT7HHZGm5I7ZQXDwLG+bGXuSrMQAW+7Zvl87h1kmc1ZB1VSRJcpUfoUrGQp4Fkoxm5kZ+Ms+aW+eA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@typedstandards/cli": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/@typedstandards/cli/-/cli-0.2.0.tgz",
+      "integrity": "sha512-hCoB8f8wmKDPZ3LtYRvahohmSvtAlFt6F5y4rI4aH9aDrdpuLeUBzcSmgx7A+9N5+i5T5POInty+O+uCTOalfg==",
+      "license": "MIT",
+      "dependencies": {
+        "@typedstandards/produce-core": "^0.8.0",
+        "@typedstandards/verify-core": "^0.13.0"
+      },
+      "bin": {
+        "typedstandards": "dist/bin/main.js"
+      },
+      "engines": {
+        "node": ">=20.19"
+      }
+    },
+    "node_modules/@typedstandards/produce-core": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/@typedstandards/produce-core/-/produce-core-0.8.0.tgz",
+      "integrity": "sha512-5d5xYi3XdfHEFERJ4K7/gtPUwpxhIzzEQqZI9/dYrlBZJQqFgarARVRXUbbHXaPO+1PQ3gFY/1nHjBEw6sD5Gg==",
+      "license": "MIT",
+      "dependencies": {
+        "@noble/curves": "^2.2.0",
+        "@typedstandards/verify-core": "^0.13.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@typedstandards/verify-core": {
+      "version": "0.13.0",
+      "resolved": "https://registry.npmjs.org/@typedstandards/verify-core/-/verify-core-0.13.0.tgz",
+      "integrity": "sha512-//bMjEiJH0+zSJg6LT3nEjQnFelbpOHPuD6T1ITygLeuS6QMFU1DChB+hFW8QLzxL02UhiUFwoCiLoOVcE2Aew==",
+      "license": "MIT",
+      "dependencies": {
+        "@noble/curves": "^2.2.0",
+        "@noble/hashes": "^2.2.0",
+        "canonicalize": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/canonicalize": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/canonicalize/-/canonicalize-3.0.0.tgz",
+      "integrity": "sha512-yYLfHyDMIXRyRqsKBRLX023riFLpXY2YOfdtqKXZRZy9qsfOJ9U+4F9YZL7MEzL5+ziN2x2nlBvY/Voi3EBljA==",
+      "license": "Apache-2.0",
+      "bin": {
+        "canonicalize": "bin/canonicalize.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}

typedstandards-0.1.0/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "typedstandards-python-vendored-cli",
+  "private": true,
+  "description": "The CLI the typedstandards wheel vendors. The hatchling build hook (hatch_build.py) runs npm ci --omit=dev --ignore-scripts against this file and package-lock.json, and ships the tree inside the wheel.",
+  "license": "MIT",
+  "dependencies": {
+    "@typedstandards/cli": "0.2.0"
+  }
+}