stepfork 0.1.0a2__tar.gz

stepfork-0.1.0a2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,52 @@
+name: Bug report
+description: Report a reproducible problem in Stepfork
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Do not include secrets, API keys, private
+        prompts, credentials, or sensitive trace data.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: minimal-reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Provide the smallest reproduction you can share safely.
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: input
+    id: stepfork-version
+    attributes:
+      label: Stepfork version
+      placeholder: "0.1.0.dev0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.11.9"
+    validations:
+      required: true
+  - type: input
+    id: operating-system
+    attributes:
+      label: Operating system
+      placeholder: "macOS 15, Ubuntu 24.04, Windows 11"
+    validations:
+      required: true

stepfork-0.1.0a2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/utsab345/stepfork/security/advisories/new
+    about: Report security issues privately. Do not open a public issue.
+  - name: Documentation
+    url: https://utsab345.github.io/stepfork/
+    about: Read the documentation and CLI reference before opening an issue.
+  - name: Contributing guide
+    url: https://github.com/utsab345/stepfork/blob/main/CONTRIBUTING.md
+    about: Local setup, development workflow, and pull request expectations.

stepfork-0.1.0a2/.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,32 @@
+name: Documentation issue
+description: Report unclear, incorrect, or missing documentation
+title: "[Docs]: "
+labels: ["documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for improving the docs. Do not include secrets, API keys,
+        private prompts, credentials, or sensitive trace data.
+  - type: input
+    id: location
+    attributes:
+      label: Where
+      description: URL, file path, or CLI reference section with the problem.
+      placeholder: docs/cli.md, `stepfork export` section
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is wrong or missing
+      description: Quote the text if possible and explain what is incorrect or unclear.
+    validations:
+      required: true
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested improvement
+      description: What should the documentation say or show?
+    validations:
+      required: false

stepfork-0.1.0a2/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature request
+description: Suggest an improvement for Stepfork
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement. Do not include secrets, API keys,
+        private prompts, credentials, or sensitive trace data.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem should this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed solution
+      description: What would you like Stepfork to do?
+    validations:
+      required: true
+  - type: textarea
+    id: desired-example
+    attributes:
+      label: Desired CLI/API example
+      description: Show the command or code you wish existed.
+      render: shell
+    validations:
+      required: true

stepfork-0.1.0a2/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+## Changes
+
+## Testing
+
+## Checklist
+
+- [ ] Tests added/updated
+- [ ] pytest passes
+- [ ] ruff check passes
+- [ ] ruff format check passes
+- [ ] mypy passes
+- [ ] docs updated if necessary
+- [ ] no secrets/sensitive traces included

stepfork-0.1.0a2/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --locked --python ${{ matrix.python-version }}
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: MyPy
+        run: uv run mypy
+
+      - name: Pytest
+        run: uv run pytest --cov=stepfork --cov-report=term-missing
+
+      - name: Build package
+        run: uv build

stepfork-0.1.0a2/.github/workflows/docs.yml

@@ -0,0 +1,83 @@
+name: docs
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Sync dependencies
+        run: uv sync --locked
+
+      - name: Build with MkDocs
+        run: uv run mkdocs build --strict
+
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Sync dependencies
+        run: uv sync --locked
+
+      - name: Build with MkDocs
+        run: uv run mkdocs build --strict
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

stepfork-0.1.0a2/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish
+
+# Publishes to PyPI using trusted publishing (OIDC). No API token is stored.
+#
+# This workflow runs ONLY when a GitHub Release is published. It has no
+# workflow_dispatch trigger and never runs on pushes or pull requests, so
+# untrusted code cannot reach the publishing credentials. The release tag must
+# match the version in src/stepfork/version.py exactly, or the build job fails
+# before the publish job starts.
+#
+# Prerequisites before the first publish (see docs/pypi-publishing.md):
+#   - a PyPI pending/trusted publisher for owner `utsab345`, repo `stepfork`,
+#     workflow `publish.yml`, environment `pypi`;
+#   - a GitHub environment named `pypi` (optionally with required reviewers).
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.1.0
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Validate distributions
+        run: uvx twine check dist/*
+
+      - name: Verify version matches release tag
+        run: |
+          version=$(python3 -c "import pathlib,re; print(re.search(r'__version__\\s*=\\s*\"([^\"]+)\"', pathlib.Path('src/stepfork/version.py').read_text()).group(1))")
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "${GITHUB_REF_TYPE}" != "tag" ]; then
+            echo "publish must run from a tag ref, got ${GITHUB_REF_TYPE}" >&2
+            exit 1
+          fi
+          if [ "$version" != "$tag" ]; then
+            echo "version.py ($version) does not match release tag ($tag)" >&2
+            exit 1
+          fi
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/stepfork
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

stepfork-0.1.0a2/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# MkDocs build output
+site/
+.cache/
+
+# IDEs
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Stepfork local runtime data
+.stepfork/
+
+# Temporary trace artifacts
+*.sftrace.tmp
+
+# Generated demo artifacts
+examples/booking_agent/.artifacts/
+examples/refund_agent/.artifacts/
+
+# Quickstart demo artifacts
+examples/quickstart/.artifacts/

stepfork-0.1.0a2/.python-version

@@ -0,0 +1 @@
+3.12

stepfork-0.1.0a2/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to Stepfork are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0a2] - 2026-10-09
+
+First distribution published to PyPI, using GitHub Actions trusted publishing
+(OpenID Connect) with no stored API token.
+
+### Added
+
+- PyPI packaging: install with `pip install --pre stepfork` (pre-release).
+- Minimal quickstart example (`examples/quickstart/`) with an integration test
+  that turns a failing run into a pytest regression test.
+- MkDocs documentation site (getting started, concepts, examples, CLI
+  reference, integrations, troubleshooting, record/replay/diff/export guides)
+  deployed to GitHub Pages.
+- `docs/cli.md`, `docs/integrations.md`,
+  `docs/community/early-adopter-guide.md`, and `docs/pypi-publishing.md`.
+- Trusted-publishing workflow (`.github/workflows/publish.yml`) and a docs
+  build/deploy workflow.
+- Terminal demo (`scripts/terminal-demo/`) and a workflow diagram asset.
+- `docs/examples.md` and `docs/troubleshooting.md`.
+
+### Changed
+
+- README rewritten for newcomers: quickstart, installation, CLI, and
+  troubleshooting.
+- Publishing runs only when a GitHub Release is published and its tag matches
+  `src/stepfork/version.py`; there is no manual trigger and no API token.
+- CLI help text and docstrings no longer reference internal milestones.
+
+[0.1.0a2]: https://github.com/utsab345/stepfork/releases/tag/v0.1.0a2
+
+## [0.1.0a1] - 2026-10-09
+
+Prepared for first public alpha.
+
+### Added
+
+- Second end-to-end example: `examples/refund_agent/` (buggy vs fixed refund
+  eligibility agent) with integration tests in
+  `tests/integration/test_refund_failure_to_test.py`.
+- Hypothesis property tests for the behavioral diff engine
+  (`first_difference`/`values_equal` agreement, dict key-order independence).
+- CLI error-path tests for `replay` and `export`.
+- Expanded unit coverage for storage, diffing, JSON encoding, runtime replay
+  planning, and export runtime error paths.
+- `CHANGELOG.md`, `docs/release-checklist.md`.
+- Top-level `SECURITY.md` documenting the security model and a private
+  vulnerability-reporting path.
+- `docs/releases/v0.1.0a1.md` with the public release notes.
+
+### Changed
+
+- README documents installing directly from the public GitHub repository via
+  `pip`/`uv` (`git+https://...@v0.1.0a1`); PyPI install is not offered for the
+  alpha. The conceptual quickstart is labeled as a sketch and links to the
+  runnable demos.
+
+- Version is now a single source of truth via hatchling dynamic versioning
+  (`[tool.hatch.version] path = "src/stepfork/version.py"`); bumped to
+  `0.1.0a1`.
+- `src/stepfork/export/generator.py`: docstrings interpolated into generated
+  pytest files are collapsed, escaped, and length-limited, preventing hostile
+  trace metadata from breaking out of the generated module docstring.
+- `src/stepfork/cli/inspect.py`: error output is sanitized before display,
+  matching diff, export, and replay.
+
+### Fixed
+
+- Generated pytest tests no longer allow `"""`-containing trace names or
+  entrypoints to terminate the generated docstring early (regression test:
+  `test_generated_source_escapes_hostile_trace_name_and_entrypoint`).
+- Inspect CLI surfaced unsanitized trace payloads in error messages.
+
+### Security
+
+- `docs/security.md` documents how to handle untrusted bundles: symlink
+  following, integrity not verified by default on replay/export, in-memory
+  payload loading, and redaction-at-record-time semantics.
+
+[0.1.0a1]: https://github.com/utsab345/stepfork/releases/tag/v0.1.0a1

stepfork-0.1.0a2/CODE_OF_CONDUCT.md

@@ -0,0 +1,118 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the GitHub repository maintainers. All complaints will be reviewed
+and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+Community Impact: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+Consequence: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+Community Impact: A violation through a single incident or series of actions.
+
+Consequence: A warning with consequences for continued behavior. No interaction
+with the people involved, including unsolicited interaction with those enforcing
+the Code of Conduct, for a specified period of time. This includes avoiding
+interactions in community spaces as well as external channels like social
+media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+Community Impact: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+Consequence: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+Community Impact: Demonstrating a pattern of violation of community standards,
+including sustained inappropriate behavior, harassment of an individual, or
+aggression toward or disparagement of classes of individuals.
+
+Consequence: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1,
+available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by Mozilla's code of conduct
+enforcement ladder.