jaunt 0.2.0__tar.gz

jaunt-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+.env
+.DS_Store
+__pycache__/
+*.py[cod]
+
+**/__generated__/
+
+.agents/
+
+.venv/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.ty_cache/
+**/.jaunt/
+
+dist/
+build/
+*.egg-info/

jaunt-0.2.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: jaunt
+Version: 0.2.0
+Summary: Spec-driven code generation framework: write intent as decorated Python stubs, generate implementations and tests with LLMs.
+Project-URL: Homepage, https://github.com/creatorrr/jaunt
+Project-URL: Repository, https://github.com/creatorrr/jaunt
+Project-URL: Issues, https://github.com/creatorrr/jaunt/issues
+Keywords: cli,code-generation,developer-tools,llm,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: all
+Requires-Dist: anthropic<1,>=0.39.0; extra == 'all'
+Requires-Dist: fastmcp>=2.0.0; extra == 'all'
+Requires-Dist: openai<2,>=1.0.0; extra == 'all'
+Requires-Dist: watchfiles>=1.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1,>=0.39.0; extra == 'anthropic'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0.0; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai<2,>=1.0.0; extra == 'openai'
+Provides-Extra: watch
+Requires-Dist: watchfiles>=1.0.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# Jaunt
+
+Jaunt is a small Python library + CLI for **spec-driven code generation**:
+
+- Write implementation intent as normal Python stubs decorated with `@jaunt.magic(...)`.
+- Optionally write test intent as stubs decorated with `@jaunt.test(...)`.
+- Jaunt generates real modules under `__generated__/` using an LLM backend (OpenAI or Anthropic).
+
+## Installation
+
+```bash
+pip install jaunt[openai]      # for OpenAI
+pip install jaunt[anthropic]   # for Anthropic/Claude
+pip install jaunt[all]         # both providers
+```
+
+## Quickstart (This Repo)
+
+Prereqs: `uv` installed.
+
+```bash
+uv sync
+export OPENAI_API_KEY=...   # or ANTHROPIC_API_KEY for Claude
+uv run jaunt --version
+```
+
+See `docs-site/` for rendered docs, or `DOCS.md` for a plain-text walkthrough.
+
+All examples live under `examples/`. See `examples/README.md` for the full list.
+
+### Hackathon Demo (JWT Auth)
+
+Headline demo: **JWT auth** (the "wow gap" example: short spec, real generated glue + tests).
+
+```bash
+# Generate implementations for @jaunt.magic specs.
+uv run jaunt build --root examples/jwt_auth
+
+# Generate pytest tests for @jaunt.test specs and run them.
+PYTHONPATH=examples/jwt_auth/src uv run jaunt test --root examples/jwt_auth
+```
+
+## Eval Suite
+
+Run the built-in eval suite against your configured backend:
+
+```bash
+uv run jaunt eval
+uv run jaunt eval --model gpt-4o
+uv run jaunt eval --provider anthropic --model claude-sonnet-4-5-20250929
+```
+
+Compare explicit provider/model targets:
+
+```bash
+uv run jaunt eval --compare openai:gpt-4o anthropic:claude-sonnet-4-5-20250929
+```
+
+Eval outputs are written under `.jaunt/evals/<timestamp>/`.
+
+Prompt snapshots:
+
+```bash
+uv run pytest tests/test_prompt_snapshots.py --snapshot-update
+```
+
+## Auto-Generate PyPI Skills (Build)
+
+`jaunt build` includes a best-effort pre-build step that auto-generates “skills” for external libraries your project imports and injects them into the build prompt.
+
+What happens:
+
+- Scan `paths.source_roots` for `import ...` / `from ... import ...` (ignores stdlib, internal modules, and relative imports).
+- Resolve imports to installed PyPI distributions + versions from the current environment.
+- Ensure a skill exists per distribution at:
+  - `<project_root>/.agents/skills/<dist-normalized>/SKILL.md`
+- If missing/outdated, fetch the exact PyPI README for `<dist>==<version>` and generate `SKILL.md` using the configured LLM provider.
+- Inject the concatenated skills text into the build LLM prompt.
+
+Overwrite rules:
+
+- Jaunt only overwrites a skill if it was previously Jaunt-generated (it has a `<!-- jaunt:skill=pypi ... -->` header) and the installed version changed.
+- If the header is missing, the file is treated as user-managed and will never be overwritten.
+
+Failure mode: warnings to stderr, and the build continues without missing skills.
+
+## Docs Site (Fumadocs)
+
+The repository includes a Fumadocs (Next.js) documentation site under `docs-site/`.
+
+```bash
+cd docs-site
+npm run dev
+```
+
+## Publish to PyPI
+
+If you keep your token in `.env` as `UV_PUBLISH_TOKEN=...`, load it into your shell first:
+
+```bash
+set -a
+source .env
+set +a
+```
+
+Build and validate artifacts:
+
+```bash
+uv build
+uvx twine check dist/*
+```
+
+Upload to PyPI:
+
+```bash
+uv publish --check-url https://pypi.org/simple/
+```
+
+## Dev
+
+```bash
+uv run ruff check .
+uv run ty check
+uv run pytest
+```

jaunt-0.2.0/README.md

@@ -0,0 +1,125 @@
+# Jaunt
+
+Jaunt is a small Python library + CLI for **spec-driven code generation**:
+
+- Write implementation intent as normal Python stubs decorated with `@jaunt.magic(...)`.
+- Optionally write test intent as stubs decorated with `@jaunt.test(...)`.
+- Jaunt generates real modules under `__generated__/` using an LLM backend (OpenAI or Anthropic).
+
+## Installation
+
+```bash
+pip install jaunt[openai]      # for OpenAI
+pip install jaunt[anthropic]   # for Anthropic/Claude
+pip install jaunt[all]         # both providers
+```
+
+## Quickstart (This Repo)
+
+Prereqs: `uv` installed.
+
+```bash
+uv sync
+export OPENAI_API_KEY=...   # or ANTHROPIC_API_KEY for Claude
+uv run jaunt --version
+```
+
+See `docs-site/` for rendered docs, or `DOCS.md` for a plain-text walkthrough.
+
+All examples live under `examples/`. See `examples/README.md` for the full list.
+
+### Hackathon Demo (JWT Auth)
+
+Headline demo: **JWT auth** (the "wow gap" example: short spec, real generated glue + tests).
+
+```bash
+# Generate implementations for @jaunt.magic specs.
+uv run jaunt build --root examples/jwt_auth
+
+# Generate pytest tests for @jaunt.test specs and run them.
+PYTHONPATH=examples/jwt_auth/src uv run jaunt test --root examples/jwt_auth
+```
+
+## Eval Suite
+
+Run the built-in eval suite against your configured backend:
+
+```bash
+uv run jaunt eval
+uv run jaunt eval --model gpt-4o
+uv run jaunt eval --provider anthropic --model claude-sonnet-4-5-20250929
+```
+
+Compare explicit provider/model targets:
+
+```bash
+uv run jaunt eval --compare openai:gpt-4o anthropic:claude-sonnet-4-5-20250929
+```
+
+Eval outputs are written under `.jaunt/evals/<timestamp>/`.
+
+Prompt snapshots:
+
+```bash
+uv run pytest tests/test_prompt_snapshots.py --snapshot-update
+```
+
+## Auto-Generate PyPI Skills (Build)
+
+`jaunt build` includes a best-effort pre-build step that auto-generates “skills” for external libraries your project imports and injects them into the build prompt.
+
+What happens:
+
+- Scan `paths.source_roots` for `import ...` / `from ... import ...` (ignores stdlib, internal modules, and relative imports).
+- Resolve imports to installed PyPI distributions + versions from the current environment.
+- Ensure a skill exists per distribution at:
+  - `<project_root>/.agents/skills/<dist-normalized>/SKILL.md`
+- If missing/outdated, fetch the exact PyPI README for `<dist>==<version>` and generate `SKILL.md` using the configured LLM provider.
+- Inject the concatenated skills text into the build LLM prompt.
+
+Overwrite rules:
+
+- Jaunt only overwrites a skill if it was previously Jaunt-generated (it has a `<!-- jaunt:skill=pypi ... -->` header) and the installed version changed.
+- If the header is missing, the file is treated as user-managed and will never be overwritten.
+
+Failure mode: warnings to stderr, and the build continues without missing skills.
+
+## Docs Site (Fumadocs)
+
+The repository includes a Fumadocs (Next.js) documentation site under `docs-site/`.
+
+```bash
+cd docs-site
+npm run dev
+```
+
+## Publish to PyPI
+
+If you keep your token in `.env` as `UV_PUBLISH_TOKEN=...`, load it into your shell first:
+
+```bash
+set -a
+source .env
+set +a
+```
+
+Build and validate artifacts:
+
+```bash
+uv build
+uvx twine check dist/*
+```
+
+Upload to PyPI:
+
+```bash
+uv publish --check-url https://pypi.org/simple/
+```
+
+## Dev
+
+```bash
+uv run ruff check .
+uv run ty check
+uv run pytest
+```

jaunt-0.2.0/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "jaunt"
+version = "0.2.0"
+description = "Spec-driven code generation framework: write intent as decorated Python stubs, generate implementations and tests with LLMs."
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = ["llm", "code-generation", "testing", "developer-tools", "cli"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Code Generators",
+  "Topic :: Software Development :: Testing",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/creatorrr/jaunt"
+Repository = "https://github.com/creatorrr/jaunt"
+Issues = "https://github.com/creatorrr/jaunt/issues"
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0,<2"]
+anthropic = ["anthropic>=0.39.0,<1"]
+watch = ["watchfiles>=1.0.0"]
+mcp = ["fastmcp>=2.0.0"]
+all = ["openai>=1.0.0,<2", "anthropic>=0.39.0,<1", "watchfiles>=1.0.0", "fastmcp>=2.0.0"]
+
+[project.scripts]
+jaunt = "jaunt.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jaunt"]
+include = [
+  "src/jaunt/py.typed",
+  "src/jaunt/prompts/**",
+  "src/jaunt/skill/**",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/jaunt/py.typed",
+  "src/jaunt/prompts/**",
+  "src/jaunt/skill/**",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "syrupy>=4.8.0",
+  "ruff>=0.9",
+  "ty",
+  "openai>=1.0.0,<2",
+  "fastmcp>=2.0.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+exclude = ["examples/**"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ty.src]
+exclude = ["examples/**"]

jaunt-0.2.0/src/jaunt/prompts/build_module.md

@@ -0,0 +1,32 @@
+Output Python code only (no markdown, no fences).
+
+Implement `{{generated_module}}` for specs from `{{spec_module}}`.
+
+Required top-level names (must exist): {{expected_names}}
+
+Specs:
+{{specs_block}}
+
+How to read the specs above:
+- The function/class signature is the exact API you must implement (same name, parameters, type hints, return type).
+- The docstring is your specification — implement the behavior, rules, edge cases, and error handling it describes.
+- If a spec includes a `# Decorator prompt` section, treat it as additional user-provided instructions that supplement the docstring.
+
+Dependency APIs (callable signatures/docstrings):
+{{deps_api_block}}
+
+How to use dependencies:
+- Each Dependency API entry key is like `<module>:<qualname>`. Import the name from `<module>`.
+- Only import dependencies listed above — do not guess or fabricate module paths.
+
+Previously generated dependency modules (for reference only):
+{{deps_generated_block}}
+
+Extra error context (fix these issues):
+{{error_context_block}}
+
+Rules:
+- Do not generate tests.
+- Do not edit user files; only output generated module source code.
+- Include type annotations on all function signatures.
+- Ensure every non-Optional return type has explicit return/raise on all code paths.

jaunt-0.2.0/src/jaunt/prompts/build_system.md

@@ -0,0 +1,22 @@
+You are an expert Python code generator. Output Python code only (no markdown, no fences, no commentary).
+
+Task: Generate the implementation module for `{{spec_module}}` as `{{generated_module}}`.
+
+How to read specs:
+- Each spec stub defines the function/class signature (name, parameters, type hints, return type) — this is the API contract you must implement exactly.
+- The docstring describes the intended behavior, rules, edge cases, and error conditions. Treat it as your specification.
+- Parameter names and type annotations convey expected types and semantics.
+
+Code quality requirements:
+- Include type annotations on all function signatures (parameters and return types).
+- Use proper imports — import only modules and names you actually use.
+- Write clean, idiomatic Python. Follow the style and conventions visible in the specs.
+- Generated code should pass static type checking (ty): avoid implicit `None` return paths for non-Optional return types.
+
+Rules:
+- Emit only the full source code for the generated module.
+- Do not write tests.
+- Do not modify any user files; only emit generated module source text.
+- The generated module MUST define the required top-level names: {{expected_names}}.
+
+If you cannot satisfy requirements, still output best-effort Python code only.

jaunt-0.2.0/src/jaunt/prompts/test_module.md

@@ -0,0 +1,36 @@
+Output Python code only (no markdown, no fences).
+
+You are generating the pytest test module `{{generated_module}}` from test specs in `{{spec_module}}`.
+
+The generated module MUST define these top-level pytest test functions (do not import them): {{expected_names}}
+
+Specs:
+{{specs_block}}
+
+How to read the test specs above:
+- The docstring describes the test scenario — what to set up, what to call, and what to assert.
+- If a spec includes a `# Decorator prompt` section, treat it as additional user-provided instructions for the test.
+- The function signature (parameters, type hints) indicates whether the test needs fixtures.
+
+Dependency APIs (callable signatures/docstrings):
+{{deps_api_block}}
+
+Previously generated dependency modules (reference only):
+{{deps_generated_block}}
+
+Extra error context (fix these issues):
+{{error_context_block}}
+
+Test quality:
+- Cover the happy path (normal usage) and edge cases (boundary values, error conditions, empty inputs).
+- Write specific assertions that check concrete values — avoid bare `assert result`.
+- Use `pytest.raises` for expected exceptions.
+
+Rules:
+- Generate tests only (no production implementation).
+- Do not import from `{{generated_module}}` (that would be a circular import).
+- Do not edit user files; only output test module source code.
+- Do not guess or search for application modules like `app`, `main`, `token`, etc.
+- Import the production APIs under test from the modules listed in Dependency APIs above.
+  - Each Dependency API entry key is like `<module>:<qualname>`; import from `<module>`.
+- Do not import production APIs from the test spec module (`{{spec_module}}`); it contains only `@jaunt.test` stubs.

jaunt-0.2.0/src/jaunt/prompts/test_system.md

@@ -0,0 +1,16 @@
+You are an expert Python test generator. Output Python code only (no markdown, no fences, no commentary).
+
+Task: Generate the pytest test module `{{generated_module}}` from test specs in `{{spec_module}}`.
+
+Test quality guidelines:
+- Cover the happy path (normal/expected usage) and edge cases (boundary values, error conditions).
+- Write clear, specific assertions that verify concrete expected values — avoid bare `assert result` without checking a specific value.
+- Each test function should be self-contained and independent.
+- Use pytest idioms: `pytest.raises` for expected exceptions, parametrize where appropriate.
+
+Rules:
+- Emit only the test module source code.
+- Do not implement production/source code; tests only.
+- Do not modify any user files; only emit generated test module source text.
+- The output MUST define the required top-level pytest test functions: {{expected_names}}.
+- Do not import from `{{generated_module}}` (circular import).

jaunt-0.2.0/src/jaunt/skill/SKILL.md

@@ -0,0 +1,157 @@
+# Jaunt Skill (for AI Assistants)
+
+## 1. What Is Jaunt
+Jaunt is a workflow where humans and AI assistants write **intent** (Python spec stubs + tests), then Jaunt generates the **implementation**; humans review both the specs and the generated code, iterate, and re-run generation.
+
+## 2. Your Role As An AI Assistant
+- Help the human author, refine, and organize **spec stubs** and **test specs**.
+- Ask clarifying questions when intent is underspecified (edge cases, I/O, errors, performance).
+- Do **not** hand-write implementations for any symbol marked as “generated” (for example, `@jaunt.magic`), unless the human explicitly asks you to bypass Jaunt and accepts the tradeoff.
+
+## 3. Workflow You Should Guide
+1. Write or refine spec stubs in the user’s codebase (signatures + docstrings + type hints).
+2. Write or refine test specs (pytest-style, deterministic, no network).
+3. Run generation (typically `jaunt build`).
+4. Review the generated output together (correctness, style, safety, performance).
+5. Iterate: adjust specs/tests and regenerate.
+
+## 4. Writing Good Spec Stubs (most important)
+
+### Principles
+- **Be explicit about behavior.** Define inputs, outputs, invariants, and what “correct” means.
+- **Specify failures.** Name the exception type and the error condition (or return shape for errors).
+- **Define edge cases.** Empty inputs, `None`, boundary values, duplicates, ordering, timeouts.
+- **Constrain the solution when it matters.** Complexity, determinism, caching, stable ordering.
+- **Prefer pure logic.** Move I/O behind parameters (dependency injection) so tests stay fast and local.
+
+### Patterns
+- **Docstring as contract:** include short examples, preconditions, postconditions.
+- **Typed dependencies:** accept `Callable[...]` or protocol-like objects instead of reaching for globals.
+- **Small, composable units:** one concept per symbol.
+
+### Anti-patterns
+- Vague docstrings: “Does X” without semantics.
+- Hidden global behavior: environment variables, implicit network calls, reading files implicitly.
+- Over-constraining early: forcing implementation details that are not required by the product.
+
+### Templates
+
+#### Pure Function
+```python
+from __future__ import annotations
+
+# @jaunt.magic  (symbol is generated; do not implement by hand)
+def normalize_email(raw: str) -> str:
+    """
+    Normalize an email address for stable comparisons.
+
+    Rules:
+    - Strip surrounding whitespace.
+    - Lowercase the whole string.
+    - Must contain exactly one "@".
+
+    Errors:
+    - Raise ValueError if the input is not a valid email by these rules.
+    """
+```
+
+#### Function With Dependencies (I/O behind parameters)
+```python
+from __future__ import annotations
+
+from collections.abc import Callable
+
+# @jaunt.magic
+def get_display_name(user_id: int, fetch_user: Callable[[int], dict]) -> str:
+    """
+    Return a user's display name.
+
+    - fetch_user(user_id) returns a dict with keys: "first_name", "last_name", optional "nickname".
+    - Prefer nickname if present and non-empty.
+    - Otherwise return "first_name last_name" with single spaces.
+
+    Errors:
+    - Raise KeyError if required keys are missing.
+    """
+```
+
+#### Stateful Class
+```python
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# @jaunt.magic
+@dataclass
+class RateLimiter:
+    """
+    Token bucket limiter.
+
+    Parameters:
+    - capacity: max tokens in the bucket (>= 1)
+    - refill_per_second: tokens refilled per second (> 0)
+
+    Behavior:
+    - allow(now: float) -> bool consumes 1 token if available at time `now` and returns True.
+    - If no token is available, return False and do not go negative.
+    """
+
+    capacity: int
+    refill_per_second: float
+
+    def allow(self, now: float) -> bool:
+        """See class docstring."""
+```
+
+#### Async Function
+```python
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+# @jaunt.magic
+async def retry(
+    op: Callable[[], Awaitable[object]],
+    *,
+    attempts: int,
+    base_delay_s: float,
+) -> object:
+    """
+    Retry an async operation with exponential backoff.
+
+    - Run op() up to `attempts` times (attempts >= 1).
+    - Delay sequence: base_delay_s * (2 ** (i-1)) for retries i=1..(attempts-1).
+    - If op() succeeds, return its result.
+
+    Errors:
+    - Re-raise the last exception if all attempts fail.
+    """
+```
+
+## 5. Writing Good Test Specs
+
+### Principles
+- **Deterministic:** no network, no clock unless injected or controlled.
+- **Small and focused:** one behavioral assertion per test when practical.
+- **Prefer black-box behavior:** test the contract, not implementation details.
+- **Include negative tests:** errors and invalid input paths.
+
+### Patterns
+- Table-driven tests for edge cases.
+- Dependency injection with tiny fakes.
+- Property-like checks where helpful (idempotence, monotonicity, stability).
+
+### Anti-patterns
+- Tests that depend on file system layout or external services.
+- Snapshot tests of entire generated files (too brittle).
+
+## 6. Configuration Reference (`jaunt.toml`)
+`jaunt.toml` configures what modules to scan, where to write generated code, and which backend/settings to use. Keep it minimal and explicit; avoid hidden defaults when onboarding a repo.
+
+See `examples/jaunt.toml` for a starter template.
+
+## 7. Critical Rules
+- Never edit `__generated__/` by hand (it will be overwritten).
+- Always regenerate via the Jaunt CLI after changing specs/tests.
+- Always review generated output before shipping.
+

jaunt-0.2.0/src/jaunt/skill/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+# Public surface for skill docs as packaged resources.
+#
+# Consumers (including `jaunt skill export`) should load these via
+# `importlib.resources.files("jaunt.skill")` rather than assuming filesystem paths.
+
+__all__ = []

jaunt-0.2.0/src/jaunt/skill/cursorrules.md

@@ -0,0 +1,31 @@
+# Cursor Rules (Jaunt Skill)
+
+Copy/paste into `.cursorrules` (or keep as-is and export via `jaunt skill export`).
+
+## Identity
+You are an AI assistant collaborating with a human using Jaunt.
+
+## Core Loop
+- Write or refine **spec stubs** (signatures + docstrings + type hints).
+- Write or refine **test specs** (pytest, deterministic, no network).
+- Ask questions when intent is unclear.
+- Run or instruct: `jaunt build` to generate implementation.
+- Review generated output with the human, then iterate.
+
+## Hard Rules
+- Do not implement any symbol intended to be generated (for example, `@jaunt.magic`).
+- Never edit anything under `__generated__/`.
+- Do not introduce network calls in tests.
+- Prefer dependency injection for I/O and time (pass callables/clients/clock into spec APIs).
+
+## What To Produce
+- Spec stubs that are decision-complete: inputs, outputs, errors, edge cases, constraints.
+- Tests that encode the contract and cover negatives.
+- Minimal config updates (for `jaunt.toml`) when needed.
+
+## Spec Stub Templates
+- Pure function: describe transformation + validation + failure mode.
+- Dependency function: accept typed callables/protocols for I/O.
+- Stateful class: define invariants and method semantics.
+- Async function: define retry/backoff, cancellation expectations, error propagation.
+

jaunt-0.2.0/src/jaunt/skill/examples/basic_function_spec.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+
+# Example: a pure function spec stub.
+# In a Jaunt workflow, this function would be generated from the spec; do not implement by hand.
+#
+# @jaunt.magic
+def slugify(title: str) -> str:
+    """
+    Convert a human title to a URL-safe slug.
+
+    Requirements:
+    - Lowercase.
+    - Trim leading/trailing whitespace.
+    - Replace runs of whitespace with a single "-".
+    - Remove characters that are not ASCII letters, digits, "-" or "_".
+    - Must never produce an empty string:
+      - If nothing remains after filtering, raise ValueError.
+
+    Examples:
+    - "Hello World" -> "hello-world"
+    - "  A  B  " -> "a-b"
+    - "C++" -> "c"
+    """
+    raise NotImplementedError

jaunt-0.2.0/src/jaunt/skill/examples/class_spec.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+# Example: a stateful class spec stub.
+#
+# @jaunt.magic
+@dataclass
+class LRUCache:
+    """
+    A fixed-capacity least-recently-used cache.
+
+    Parameters:
+    - capacity: max number of items (>= 1)
+
+    Behavior:
+    - get(key) -> value | None
+      - Returns None if missing.
+      - Marks the key as most-recently-used if present.
+    - set(key, value) -> None
+      - Inserts/updates the value.
+      - If capacity is exceeded, evict the least-recently-used key.
+    - size() -> int returns the current number of keys.
+
+    Constraints:
+    - All operations should be O(1) average-case.
+    """
+
+    capacity: int
+
+    def get(self, key: str) -> object | None:
+        """See class docstring."""
+        raise NotImplementedError
+
+    def set(self, key: str, value: object) -> None:
+        """See class docstring."""
+        raise NotImplementedError
+
+    def size(self) -> int:
+        """See class docstring."""
+        raise NotImplementedError

jaunt-0.2.0/src/jaunt/skill/examples/jaunt.toml

@@ -0,0 +1,16 @@
+# Example jaunt.toml
+#
+# This is a starter template; keys will evolve with Jaunt as the MVP is implemented.
+
+[project]
+# Modules (or directories) containing spec stubs and tests for Jaunt to scan.
+roots = ["src", "tests"]
+
+[generation]
+# Where generated implementation is written.
+generated_dir = "__generated__"
+
+[backend]
+# Which generator backend to use (placeholder).
+name = "openai"
+

jaunt-0.2.0/src/jaunt/skill/examples/test_spec.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import cast
+
+import pytest
+
+# Example test specs.
+# These tests express behavior and edge cases; the implementation is generated by Jaunt.
+
+
+def test_slugify_basic() -> None:
+    # Replace this import path with your project's module after you run `jaunt build`.
+    #
+    # from myproj.__generated__.text import slugify
+    slugify = cast(Callable[[str], str], None)
+
+    assert slugify("Hello World") == "hello-world"
+
+
+def test_slugify_rejects_empty() -> None:
+    slugify = cast(Callable[[str], str], None)
+
+    with pytest.raises(ValueError):
+        slugify("!!!")