softschema 0.1.2__tar.gz → 0.1.4__tar.gz

{softschema-0.1.2 → softschema-0.1.4}/.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+# Node / TypeScript
+node_modules/
+
 # Distribution / packaging
 .Python
 build/
@@ -223,3 +226,6 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# TS bundled doc/skill resources (generated at build by copy-resources)
+packages/typescript/resources/

{softschema-0.1.2 → softschema-0.1.4}/AGENTS.md

@@ -9,11 +9,21 @@ Start here:
 - [Softschema Spec](docs/softschema-spec.md): exact language-neutral artifact format.
 - [Movie page example](examples/movie_page/README.md): complete Python-backed example.
 
-For implementer reference (only when changing the Python package itself):
+softschema ships two interchangeable implementations with the same CLI and library
+surface: Python/Pydantic (`softschema`, `softschema-py`) and TypeScript/Zod
+(`softschema`, `softschema-ts`). They are held to exact behavioral parity: same flags,
+same canonical JSON Schema sidecar, same validation results, so authoring an artifact is
+identical regardless of which you run.
+
+For implementer reference (only when changing a package itself):
 
 - [Python Package Design](docs/softschema-python-design.md): module layout, CLI surface,
   validation layers, and ADR-style decisions.
-  Skip when only authoring or validating artifacts.
+- [TypeScript Package Design](docs/softschema-typescript-design.md): the Zod port and
+  the Python↔TypeScript API parity table.
+- When changing behavior, follow the parity development process (golden-first, then port
+  to both) in [docs/development.md](docs/development.md).
+  Skip all of this when only authoring or validating artifacts.
 
 Key rules:
 
@@ -53,10 +63,6 @@ Documentation rules:
 - Include the standard documentation footer in repo docs.
   Do not add it to authored softschema example artifacts.
 
-<!-- This document follows common-doc-guidelines.md.
-See github.com/jlevy/practical-prose and review guidelines before editing.
--->
-
 <!-- BEGIN TBD INTEGRATION format=f04 surface=agents-md -->
 ## tbd
 

{softschema-0.1.2 → softschema-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softschema
-Version: 0.1.2
+Version: 0.1.4
 Summary: Soft schema conventions and validation tools for Markdown/YAML artifacts
 Project-URL: Homepage, https://github.com/jlevy/softschema
 Project-URL: Repository, https://github.com/jlevy/softschema
@@ -22,11 +22,23 @@ Requires-Python: <4.0,>=3.11
 Requires-Dist: frontmatter-format>=0.3.0
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: pydantic>=2
-Requires-Dist: pyyaml
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: strif>=3.1.0
 Description-Content-Type: text/markdown
 
 # softschema
 
+## Quick Start
+
+To set up softschema in a repository with an agent, tell the agent:
+
+> Run `uvx softschema@latest --help` (for the Python implementation) or
+> `npx softschema@latest --help` (for the Node implementation) and follow the
+> instructions to set up softschema for this repo as a skill.
+
+The help output points the agent to `skill --install`, which writes discoverable
+`SKILL.md` mirrors for Codex, Claude Code, Gemini CLI, and other coding agents.
+
 ## What Are Soft Schemas?
 
 Soft schemas are a practice for adding structure gradually to artifacts that mix
@@ -131,14 +143,42 @@ This repo is simply:
   defining soft schema file format conventions for Markdown documents with YAML
   frontmatter.
 
-- A simple [Python CLI](docs/softschema-python-design.md) that handles formatting,
-  compilation, validation, and other common workflows on soft schema-style documents.
+- A small CLI (and library) that handles formatting, compilation, validation, and other
+  common workflows on soft schema-style documents.
 
 The CLI can be used directly, as a library, or installed as a skill.
 
 For the full conceptual reference and adoption playbooks, see the
 [Softschema Guide](docs/softschema-guide.md).
 
+## Two Synchronized Implementations
+
+softschema ships **two complete, fully supported implementations** with the same CLI and
+library surface:
+
+- **Python / Pydantic**: [`softschema`](docs/softschema-python-design.md) on PyPI (run
+  as `softschema` or `softschema-py`).
+- **TypeScript / Zod**: [`softschema`](docs/softschema-typescript-design.md) on npm (run
+  as `softschema` or `softschema-ts`).
+
+The TypeScript package is a **synchronized port** of the Python one, held to **exact
+behavioral parity**: equivalent CLI inputs, outputs, and flags; equivalent library APIs;
+the same canonical JSON Schema sidecar (content-identical, with an equal `schema_sha256`
+fingerprint over its canonical JSON); and the same engine-neutral validation results.
+Only idiomatic surface details differ (snake_case ↔ camelCase, Pydantic ↔ Zod).
+Authoring or validating an artifact is identical regardless of which you run, so a team
+can adopt either runtime, or both, without divergence.
+
+The two are **maintained in lockstep**: every behavior change lands in a shared
+golden-test corpus first, then in both packages, and CI fails if their outputs or
+compiled schemas drift.
+They release together under **the same version number** on PyPI and npm.
+See
+[Keeping Python and TypeScript in Parity](docs/development.md#keeping-python-and-typescript-in-parity)
+for the development process and the parity invariants CI enforces, and
+[Publishing](https://github.com/jlevy/softschema/blob/main/docs/publishing.md) for the
+synchronized release.
+
 ## Example Artifact Shape
 
 The default shape is Markdown with YAML frontmatter.
@@ -192,39 +232,14 @@ It won the 2003 Academy Award for Best Animated Feature.
 Rotten Tomatoes shows a 96% Tomatometer from 225 critic reviews and a 96% Popcornmeter
 from the audience; IMDb users give it 8.6 out of 10 across more than 850,000 votes.
 
-## Movie Details
-
-| Field | Value |
-| --- | --- |
-| Title | Spirited Away |
-| Release year | 2001 |
-| Runtime | 125 minutes |
-| MPAA rating | PG |
-| Director | Hayao Miyazaki |
-| Genres | Animation, Adventure, Family |
-
-## Lead Cast
-
-| Actor | Character |
-| --- | --- |
-| Rumi Hiiragi | Chihiro / Sen |
-| Miyu Irino | Haku |
-| Mari Natsuki | Yubaba |
-
-## Ratings
-
-| Source | Score | Count |
-| --- | ---: | ---: |
-| Rotten Tomatoes Critics | 96% Tomatometer | 225 reviews |
-| Rotten Tomatoes Audience | 96% Popcornmeter | — |
-| IMDb | 8.6 / 10 | 850,000+ votes |
+<!-- The reader-facing body continues with prose and tables; see the full example. -->
 ```
 
 The YAML payload is authoritative; a consumer reads it.
-The Markdown body overlaps with it but is for human readers: the body’s tables mirror
-some YAML fields for the reader’s convenience, the prose adds context like the film’s
-Academy Award (which no structured field carries), and the YAML alone carries downstream
-fields such as `critic_review_count`.
+The Markdown body overlaps with it but is for human readers: the prose adds context like
+the film’s Academy Award (which no structured field carries), the YAML alone carries
+downstream fields such as `critic_review_count`, and the full example’s body mirrors
+some YAML fields as tables for the reader’s convenience.
 
 Only the `softschema` block and the chosen envelope key (`movie:` above) are
 softschema’s concern.
@@ -304,52 +319,95 @@ uv run softschema compile examples.movie_page.model:MoviePage \
   --out examples/movie_page/movie-page.schema.yaml
 ```
 
+## Try the TypeScript Package
+
+The TypeScript CLI takes the same arguments and emits byte-identical output.
+Validate the same artifact against the same language-neutral schema sidecar with a
+pinned zero-install runner:
+
+```bash
+npx softschema@latest validate examples/movie_page/spirited-away.md \
+  --schema examples/movie_page/movie-page.schema.yaml \
+  --envelope movie
+```
+
+The bundled docs and skill are served identically:
+
+```bash
+npx softschema@latest docs --list
+npx softschema@latest docs guide
+npx softschema@latest skill --brief
+```
+
+Semantic models are written in Zod instead of Pydantic; everything else (flags, result
+JSON, error records, and the compiled sidecar, down to its `schema_sha256`) matches the
+Python package exactly.
+See the [TypeScript Design](docs/softschema-typescript-design.md) doc for the Zod model
+shape and the full Python ↔ TypeScript API table.
+
 ## Use as an Agent Skill
 
-The `softschema` CLI ships as a [`SKILL.md`](https://agentskills.io) following the open
+Both packages ship the same [`SKILL.md`](https://agentskills.io) following the open
 Agent Skills standard discovered by Claude Code, Codex, Gemini CLI, Cursor, Copilot, and
 ~20 other coding agents.
 Pointing an agent at the CLI is enough to bootstrap its understanding of the soft-schema
-approach: the `--help` epilog routes it to a brief and the bundled docs.
+approach: the `--help` epilog routes it to `skill --install`, a brief, and the bundled
+docs.
 
 ```bash
-uvx softschema@0.1.2 --help            # entry point with bootstrap pointers
-uvx softschema@0.1.2 skill --brief     # ~12-line operating brief
-uvx softschema@0.1.2 docs guide        # full mental model and adoption path
+# Python:
+uvx softschema@latest --help            # entry point with skill setup pointers
+uvx softschema@latest skill --install   # install repo-local skill mirrors
+uvx softschema@latest skill --brief     # compact operating brief
+uvx softschema@latest docs guide        # full mental model and adoption path
+
+# TypeScript (same commands, same bundled docs/skill):
+npx softschema@latest --help
+npx softschema@latest skill --install
+npx softschema@latest skill --brief
+npx softschema@latest docs guide
 ```
 
-Self-install the skill into a project so any agent working in the repo finds it
-natively:
+Self-install the skill into a project so any agent working in the repo finds it natively
+(either package writes the identical mirrors):
 
 ```bash
-uvx softschema@0.1.2 skill --install
+uvx softschema@latest skill --install
+# or: npx softschema@latest skill --install
 # writes:
 #   .agents/skills/softschema/SKILL.md   (Codex, Gemini CLI, cross-agent installers)
 #   .claude/skills/softschema/SKILL.md   (Claude Code mirror)
 ```
 
-Both mirrors carry a `DO NOT EDIT` marker and the version that wrote them.
-Re-run `softschema skill --install` to refresh after upgrading the CLI.
+Both mirrors carry a `DO NOT EDIT` marker.
+Re-run `skill --install` to refresh after upgrading the CLI.
 
 ## Repository Layout
 
 ```text
-docs/                  guide, spec, Python package design, and workflow docs
+docs/                  guide, spec, package design (Python + TypeScript), and workflow docs
 examples/movie_page/   complete example with model, host integration, artifact, schema
-packages/python/       Python implementation and tests
-packages/typescript/   future TypeScript/Zod notes only
-skills/softschema/     agent-facing usage guidance
+examples/parity/       cross-language parity fixture (Pydantic + Zod compile to one schema)
+packages/python/       Python/Pydantic implementation and tests
+packages/typescript/   TypeScript/Zod implementation and tests
+skills/softschema/     agent-facing usage guidance (shared SKILL.md source)
+tests/golden/          shared CLI golden corpus, run against both implementations
 ```
 
 The root `pyproject.toml` builds the Python package from
-`packages/python/src/softschema`. This keeps the first release simple while leaving room
-for a future TypeScript package.
+`packages/python/src/softschema`; `packages/typescript` builds the npm `softschema`
+package with bun. The shared golden corpus and the cross-language conformance test keep
+the two implementations byte-for-byte in sync.
 
 ## Development and Contributing
 
 See [Development](docs/development.md) for repo setup, common commands, CI checks,
 release workflow, and pointers to the installation and publishing docs.
 
+The Python and TypeScript implementations **must be kept in exact sync**. Any behavior
+change goes through the shared golden corpus first and then lands in both packages; see
+[Keeping Python and TypeScript in Parity](docs/development.md#keeping-python-and-typescript-in-parity).
+
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.
 -->

{softschema-0.1.2 → softschema-0.1.4}/README.md

@@ -1,5 +1,16 @@
 # softschema
 
+## Quick Start
+
+To set up softschema in a repository with an agent, tell the agent:
+
+> Run `uvx softschema@latest --help` (for the Python implementation) or
+> `npx softschema@latest --help` (for the Node implementation) and follow the
+> instructions to set up softschema for this repo as a skill.
+
+The help output points the agent to `skill --install`, which writes discoverable
+`SKILL.md` mirrors for Codex, Claude Code, Gemini CLI, and other coding agents.
+
 ## What Are Soft Schemas?
 
 Soft schemas are a practice for adding structure gradually to artifacts that mix
@@ -104,14 +115,42 @@ This repo is simply:
   defining soft schema file format conventions for Markdown documents with YAML
   frontmatter.
 
-- A simple [Python CLI](docs/softschema-python-design.md) that handles formatting,
-  compilation, validation, and other common workflows on soft schema-style documents.
+- A small CLI (and library) that handles formatting, compilation, validation, and other
+  common workflows on soft schema-style documents.
 
 The CLI can be used directly, as a library, or installed as a skill.
 
 For the full conceptual reference and adoption playbooks, see the
 [Softschema Guide](docs/softschema-guide.md).
 
+## Two Synchronized Implementations
+
+softschema ships **two complete, fully supported implementations** with the same CLI and
+library surface:
+
+- **Python / Pydantic**: [`softschema`](docs/softschema-python-design.md) on PyPI (run
+  as `softschema` or `softschema-py`).
+- **TypeScript / Zod**: [`softschema`](docs/softschema-typescript-design.md) on npm (run
+  as `softschema` or `softschema-ts`).
+
+The TypeScript package is a **synchronized port** of the Python one, held to **exact
+behavioral parity**: equivalent CLI inputs, outputs, and flags; equivalent library APIs;
+the same canonical JSON Schema sidecar (content-identical, with an equal `schema_sha256`
+fingerprint over its canonical JSON); and the same engine-neutral validation results.
+Only idiomatic surface details differ (snake_case ↔ camelCase, Pydantic ↔ Zod).
+Authoring or validating an artifact is identical regardless of which you run, so a team
+can adopt either runtime, or both, without divergence.
+
+The two are **maintained in lockstep**: every behavior change lands in a shared
+golden-test corpus first, then in both packages, and CI fails if their outputs or
+compiled schemas drift.
+They release together under **the same version number** on PyPI and npm.
+See
+[Keeping Python and TypeScript in Parity](docs/development.md#keeping-python-and-typescript-in-parity)
+for the development process and the parity invariants CI enforces, and
+[Publishing](https://github.com/jlevy/softschema/blob/main/docs/publishing.md) for the
+synchronized release.
+
 ## Example Artifact Shape
 
 The default shape is Markdown with YAML frontmatter.
@@ -165,39 +204,14 @@ It won the 2003 Academy Award for Best Animated Feature.
 Rotten Tomatoes shows a 96% Tomatometer from 225 critic reviews and a 96% Popcornmeter
 from the audience; IMDb users give it 8.6 out of 10 across more than 850,000 votes.
 
-## Movie Details
-
-| Field | Value |
-| --- | --- |
-| Title | Spirited Away |
-| Release year | 2001 |
-| Runtime | 125 minutes |
-| MPAA rating | PG |
-| Director | Hayao Miyazaki |
-| Genres | Animation, Adventure, Family |
-
-## Lead Cast
-
-| Actor | Character |
-| --- | --- |
-| Rumi Hiiragi | Chihiro / Sen |
-| Miyu Irino | Haku |
-| Mari Natsuki | Yubaba |
-
-## Ratings
-
-| Source | Score | Count |
-| --- | ---: | ---: |
-| Rotten Tomatoes Critics | 96% Tomatometer | 225 reviews |
-| Rotten Tomatoes Audience | 96% Popcornmeter | — |
-| IMDb | 8.6 / 10 | 850,000+ votes |
+<!-- The reader-facing body continues with prose and tables; see the full example. -->
 ```
 
 The YAML payload is authoritative; a consumer reads it.
-The Markdown body overlaps with it but is for human readers: the body’s tables mirror
-some YAML fields for the reader’s convenience, the prose adds context like the film’s
-Academy Award (which no structured field carries), and the YAML alone carries downstream
-fields such as `critic_review_count`.
+The Markdown body overlaps with it but is for human readers: the prose adds context like
+the film’s Academy Award (which no structured field carries), the YAML alone carries
+downstream fields such as `critic_review_count`, and the full example’s body mirrors
+some YAML fields as tables for the reader’s convenience.
 
 Only the `softschema` block and the chosen envelope key (`movie:` above) are
 softschema’s concern.
@@ -277,52 +291,95 @@ uv run softschema compile examples.movie_page.model:MoviePage \
   --out examples/movie_page/movie-page.schema.yaml
 ```
 
+## Try the TypeScript Package
+
+The TypeScript CLI takes the same arguments and emits byte-identical output.
+Validate the same artifact against the same language-neutral schema sidecar with a
+pinned zero-install runner:
+
+```bash
+npx softschema@latest validate examples/movie_page/spirited-away.md \
+  --schema examples/movie_page/movie-page.schema.yaml \
+  --envelope movie
+```
+
+The bundled docs and skill are served identically:
+
+```bash
+npx softschema@latest docs --list
+npx softschema@latest docs guide
+npx softschema@latest skill --brief
+```
+
+Semantic models are written in Zod instead of Pydantic; everything else (flags, result
+JSON, error records, and the compiled sidecar, down to its `schema_sha256`) matches the
+Python package exactly.
+See the [TypeScript Design](docs/softschema-typescript-design.md) doc for the Zod model
+shape and the full Python ↔ TypeScript API table.
+
 ## Use as an Agent Skill
 
-The `softschema` CLI ships as a [`SKILL.md`](https://agentskills.io) following the open
+Both packages ship the same [`SKILL.md`](https://agentskills.io) following the open
 Agent Skills standard discovered by Claude Code, Codex, Gemini CLI, Cursor, Copilot, and
 ~20 other coding agents.
 Pointing an agent at the CLI is enough to bootstrap its understanding of the soft-schema
-approach: the `--help` epilog routes it to a brief and the bundled docs.
+approach: the `--help` epilog routes it to `skill --install`, a brief, and the bundled
+docs.
 
 ```bash
-uvx softschema@0.1.2 --help            # entry point with bootstrap pointers
-uvx softschema@0.1.2 skill --brief     # ~12-line operating brief
-uvx softschema@0.1.2 docs guide        # full mental model and adoption path
+# Python:
+uvx softschema@latest --help            # entry point with skill setup pointers
+uvx softschema@latest skill --install   # install repo-local skill mirrors
+uvx softschema@latest skill --brief     # compact operating brief
+uvx softschema@latest docs guide        # full mental model and adoption path
+
+# TypeScript (same commands, same bundled docs/skill):
+npx softschema@latest --help
+npx softschema@latest skill --install
+npx softschema@latest skill --brief
+npx softschema@latest docs guide
 ```
 
-Self-install the skill into a project so any agent working in the repo finds it
-natively:
+Self-install the skill into a project so any agent working in the repo finds it natively
+(either package writes the identical mirrors):
 
 ```bash
-uvx softschema@0.1.2 skill --install
+uvx softschema@latest skill --install
+# or: npx softschema@latest skill --install
 # writes:
 #   .agents/skills/softschema/SKILL.md   (Codex, Gemini CLI, cross-agent installers)
 #   .claude/skills/softschema/SKILL.md   (Claude Code mirror)
 ```
 
-Both mirrors carry a `DO NOT EDIT` marker and the version that wrote them.
-Re-run `softschema skill --install` to refresh after upgrading the CLI.
+Both mirrors carry a `DO NOT EDIT` marker.
+Re-run `skill --install` to refresh after upgrading the CLI.
 
 ## Repository Layout
 
 ```text
-docs/                  guide, spec, Python package design, and workflow docs
+docs/                  guide, spec, package design (Python + TypeScript), and workflow docs
 examples/movie_page/   complete example with model, host integration, artifact, schema
-packages/python/       Python implementation and tests
-packages/typescript/   future TypeScript/Zod notes only
-skills/softschema/     agent-facing usage guidance
+examples/parity/       cross-language parity fixture (Pydantic + Zod compile to one schema)
+packages/python/       Python/Pydantic implementation and tests
+packages/typescript/   TypeScript/Zod implementation and tests
+skills/softschema/     agent-facing usage guidance (shared SKILL.md source)
+tests/golden/          shared CLI golden corpus, run against both implementations
 ```
 
 The root `pyproject.toml` builds the Python package from
-`packages/python/src/softschema`. This keeps the first release simple while leaving room
-for a future TypeScript package.
+`packages/python/src/softschema`; `packages/typescript` builds the npm `softschema`
+package with bun. The shared golden corpus and the cross-language conformance test keep
+the two implementations byte-for-byte in sync.
 
 ## Development and Contributing
 
 See [Development](docs/development.md) for repo setup, common commands, CI checks,
 release workflow, and pointers to the installation and publishing docs.
 
+The Python and TypeScript implementations **must be kept in exact sync**. Any behavior
+change goes through the shared golden corpus first and then lands in both packages; see
+[Keeping Python and TypeScript in Parity](docs/development.md#keeping-python-and-typescript-in-parity).
+
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.
 -->