softschema 0.1.2__tar.gz → 0.1.3__tar.gz

{softschema-0.1.2 → softschema-0.1.3}/.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.3}/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:
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softschema
-Version: 0.1.2
+Version: 0.1.3
 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,7 +22,8 @@ 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
@@ -131,14 +132,41 @@ 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 (byte-identical, with an equal `schema_sha256`
+fingerprint); 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](docs/publishing.md) for the synchronized release.
+
 ## Example Artifact Shape
 
 The default shape is Markdown with YAML frontmatter.
@@ -216,7 +244,7 @@ from the audience; IMDb users give it 8.6 out of 10 across more than 850,000 vot
 | Source | Score | Count |
 | --- | ---: | ---: |
 | Rotten Tomatoes Critics | 96% Tomatometer | 225 reviews |
-| Rotten Tomatoes Audience | 96% Popcornmeter | — |
+| Rotten Tomatoes Audience | 96% Popcornmeter | n/a |
 | IMDb | 8.6 / 10 | 850,000+ votes |
 ```
 
@@ -304,52 +332,91 @@ 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.
 
 ```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 bootstrap pointers
+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 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.3}/README.md

@@ -104,14 +104,41 @@ 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 (byte-identical, with an equal `schema_sha256`
+fingerprint); 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](docs/publishing.md) for the synchronized release.
+
 ## Example Artifact Shape
 
 The default shape is Markdown with YAML frontmatter.
@@ -189,7 +216,7 @@ from the audience; IMDb users give it 8.6 out of 10 across more than 850,000 vot
 | Source | Score | Count |
 | --- | ---: | ---: |
 | Rotten Tomatoes Critics | 96% Tomatometer | 225 reviews |
-| Rotten Tomatoes Audience | 96% Popcornmeter | — |
+| Rotten Tomatoes Audience | 96% Popcornmeter | n/a |
 | IMDb | 8.6 / 10 | 850,000+ votes |
 ```
 
@@ -277,52 +304,91 @@ 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.
 
 ```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 bootstrap pointers
+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 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.3}/docs/development.md

@@ -3,12 +3,16 @@
 First-time setup of `uv` and Python is covered in [Installation](installation.md).
 Release workflow and PyPI steps are covered in [Publishing](publishing.md).
 
-Set up the repo:
+Set up the repo (Python deps, Node tooling for hooks, and the git hooks themselves):
 
 ```bash
-uv sync --all-extras
+make install        # uv sync --all-extras + npm install (lefthook)
+make hooks-install  # install the lefthook pre-commit hooks
 ```
 
+`make install` alone (or `uv sync --all-extras`) is enough to run tests and builds;
+`make hooks-install` additionally wires up the pre-commit hooks described below.
+
 Common workflows:
 
 ```bash
@@ -31,6 +35,37 @@ uv build
 
 The Python package is built from `packages/python/src/softschema`.
 
+### Git hooks (this repo)
+
+Hooks are managed by [lefthook](https://lefthook.dev) (`lefthook.yml`), installed with
+`make hooks-install`. The `pre-commit` hook formats staged changes so commits stay
+clean:
+
+- **Markdown:** delegates to `make format` (pinned `flowmark-rs` and
+  `softschema generate`); the single source of truth, the same command you run locally.
+- **Python:** `ruff format` and `ruff check --fix` on staged `*.py`.
+- **TypeScript:** `biome check --write` on staged files in `packages/typescript`.
+
+Bypass for an emergency commit with `git commit --no-verify` (avoid in PRs).
+flowmark runs across the whole tree (it honors `.flowmarkignore` only relative to its
+target arg), so staging any `*.md` reformats all Markdown; this is fast and idempotent.
+
+## TypeScript Package
+
+The TypeScript/Zod package lives in `packages/typescript` and builds with bun (bunup and
+biome). Set it up and run its checks:
+
+```bash
+cd packages/typescript
+bun install --frozen-lockfile
+bun run check       # biome lint, tsc --noEmit, bun test (+ coverage gate)
+bun run build       # copy-resources + bunup → dist/
+```
+
+It publishes to npm as `softschema` (the same name as the PyPI package) and exposes the
+CLI as both `softschema` and `softschema-ts`. The two packages **release together under
+one version number**; see [Publishing](publishing.md).
+
 Documentation changes should follow `common-doc-guidelines.md`
 (github.com/jlevy/practical-prose).
 Keep the README short, keep conceptual guidance in `docs/softschema-guide.md`, and keep
@@ -132,6 +167,42 @@ repos:
 Adapt the paths and the `--model` / `--contract` / `--out` arguments to each schema in
 your repository.
 
+## Keeping Python and TypeScript in Parity
+
+softschema ships two implementations, Python/Pydantic (`softschema`) and TypeScript/Zod
+(`softschema`, `softschema-ts`), held to **exact behavioral parity**: equivalent CLI
+inputs/outputs/flags and library APIs, the same canonical JSON Schema sidecar
+(byte-identical, equal `schema_sha256`), and the same engine-neutral validation results.
+Only idiomatic surface differs (snake_case ↔ camelCase, Pydantic ↔ Zod).
+
+When you change any behavior, follow this loop so the two never drift:
+
+1. **Golden first.** Write or update the shared scenario in `tests/golden/scenarios/`
+   (neutral, runs on both) or `tests/golden/scenarios-{py,ts}/` (per-language
+   invocation, identical output) **before** touching code.
+2. **Implement in Python**, then `uv run pytest` and
+   `SOFTSCHEMA_IMPL=py bash tests/golden/run.sh`.
+3. **Port to TypeScript**, then `bun test` (in `packages/typescript`) and
+   `SOFTSCHEMA_IMPL=ts bash tests/golden/run.sh`.
+4. **Both green and conformance.** Both golden runs and the cross-implementation
+   conformance test (the Zod and Pydantic compilers produce an identical canonical
+   sidecar) pass in CI.
+
+The parity invariants, and where each is enforced:
+
+| Invariant | Enforced by |
+| --- | --- |
+| Canonical schema (equal `schema_sha256`) | `compile` and the KitchenSink conformance test (`packages/typescript/test/conformance.test.ts`) and `examples/parity/` |
+| Engine-neutral structural errors | shared message templates (`errors`), the golden corpus |
+| Byte-identical neutral CLI output | the shared golden corpus (run twice via `SOFTSCHEMA_IMPL`) |
+| Equal flag/command surface | per-impl and neutral golden scenarios |
+| Bundled docs/skill resolve from the package | the standalone test (`packages/typescript/test/standalone.test.ts`) |
+| Skill mirrors never go stale | the mirror drift test (`tests/test_skill_mirror_drift.py`) |
+
+Semantic invariants that JSON Schema cannot express (Pydantic validators ↔ Zod
+refinements) are implementation-specific by design and tested per-language, not in the
+shared corpus.
+
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.
 -->