swallo 0.1.0__tar.gz

swallo-0.1.0/.github/workflows/bench.yml

@@ -0,0 +1,48 @@
+name: Statistical Performance Benchmarks
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Run once a week at midnight UTC on Sundays
+    - cron: '0 0 * * 0'
+
+permissions:
+  contents: read
+
+jobs:
+  benchmarks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev,tokens] psutil pyperf pytest-benchmark
+
+      - name: Run deterministic benchmarks and verify
+        run: |
+          python -m benchmarks.deterministic.runner
+          swallo bench verify benchmarks/results/deterministic.json
+
+      - name: Run statistical benchmarks
+        run: |
+          python -m benchmarks.perf.runner
+
+      - name: Upload benchmark results artifact
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
+        with:
+          name: perf-benchmark-results
+          path: benchmarks/results/perf/
+          retention-days: 30
+
+      - name: Runner Noise Disclaimer
+        run: |
+          echo "Note: GitHub Actions hosted runners share virtualized hardware with variable noisy neighbors."
+          echo "These benchmark numbers are indicative of order-of-magnitude performance and not absolute."

swallo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,134 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-types:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev,sign,mcp]"
+
+      - name: Run Ruff check
+        run: python -m ruff check src tests
+
+      - name: Run Mypy strict
+        run: python -m mypy src/swallo
+
+  test-matrix:
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.experimental || false }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+        include:
+          - python-version: "3.14"
+            experimental: true
+          - python-version: "3.15"
+            experimental: true
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Install dependencies with dev and sign extras
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev,sign]"
+
+      - name: Run Pytest test suite with coverage
+        run: python -m pytest --cov=swallo --cov-report=xml --cov-report=term
+
+  core-only:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Install core package only (no extras)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .
+
+      - name: Verify zero non-standard runtime dependencies & zero warnings
+        run: |
+          python -W error -c "import swallo; print('swallo version:', swallo.__version__)"
+          python -c "import sys; assert 'cryptography' not in sys.modules; assert 'tiktoken' not in sys.modules; assert 'mcp' not in sys.modules; print('Verified core runtime dependency isolation')"
+
+      - name: Run core tests with pytest
+        run: |
+          python -m pip install pytest hypothesis
+          python -m pytest
+
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Install audit tools
+        run: |
+          python -m pip install --upgrade pip "setuptools>=84.1.0"
+          python -m pip install pip-audit bandit .
+
+      - name: Run pip-audit vulnerability scan
+        run: python -m pip_audit
+
+      - name: Run Bandit AST security scan
+        run: python -m bandit -r src/swallo -ll -q
+
+  build-and-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Build package and check distribution metadata
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*

swallo-0.1.0/.github/workflows/clean-install.yml

@@ -0,0 +1,80 @@
+name: Clean Install Verification
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  clean-install-matrix:
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.experimental || false }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+        include:
+          - python-version: "3.14"
+            experimental: true
+          - python-version: "3.15"
+            experimental: true
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Install built wheel into isolated environment
+        shell: bash
+        run: |
+          python -m venv test-venv
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            VENV_PYTHON="test-venv/Scripts/python"
+          else
+            VENV_PYTHON="test-venv/bin/python"
+          fi
+          "$VENV_PYTHON" -m pip install --upgrade pip
+          "$VENV_PYTHON" -m pip install dist/*.whl
+
+      - name: Test zero-warning import and dependency isolation
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            VENV_PYTHON="test-venv/Scripts/python"
+          else
+            VENV_PYTHON="test-venv/bin/python"
+          fi
+          "$VENV_PYTHON" -W error -c "import swallo; print('Imported swallo v' + swallo.__version__)"
+          "$VENV_PYTHON" -c "import sys; assert 'mcp' not in sys.modules; assert 'cryptography' not in sys.modules; assert 'tiktoken' not in sys.modules; print('Verified isolation')"
+
+      - name: Verify CLI commands in temp directory
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            VENV_BIN="test-venv/Scripts"
+          else
+            VENV_BIN="test-venv/bin"
+          fi
+          export PATH="$PWD/$VENV_BIN:$PATH"
+          swallo --help
+          swallo version
+          mkdir temp_workspace
+          cd temp_workspace
+          swallo init
+          swallo doctor

swallo-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,40 @@
+name: "CodeQL Analysis"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '0 6 * * 1'
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze Code
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@9418214df1f2c4b8128c770156c409013b07d6b9 # v3.39.3
+      with:
+        languages: ${{ matrix.language }}
+        queries: security-and-quality
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@9418214df1f2c4b8128c770156c409013b07d6b9 # v3.39.3
+      with:
+        category: "/language:${{matrix.language}}"

swallo-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: Release Distribution
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution packages
+    runs-on: ubuntu-latest
+    outputs:
+      hash: ${{ steps.hash.outputs.hash }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check package metadata with twine
+        run: python -m twine check --strict dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  provenance:
+    needs: [build]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      attestations: write
+      contents: read
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
+        with:
+          name: python-package-distributions
+          path: dist
+
+      - name: Generate build provenance attestations
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: "dist/*"
+
+  publish-to-pypi:
+    name: Publish to PyPI via Trusted Publishing (OIDC)
+    needs: [build, provenance]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/swallo
+    permissions:
+      id-token: write  # Mandatory for PyPI Trusted Publishing (OIDC)
+      contents: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9
+        with:
+          name: python-package-distributions
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          packages-dir: dist/
+          attestations: true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3 # v3.0.4
+        with:
+          files: dist/*
+          generate_release_notes: true

swallo-0.1.0/.github/workflows/scorecard.yml

@@ -0,0 +1,38 @@
+name: OpenSSF Scorecard
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: '30 1 * * 6'
+  push:
+    branches: [ "main" ]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      id-token: write
+      contents: read
+      actions: read
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: "Upload SARIF results"
+        uses: github/codeql-action/upload-sarif@9418214df1f2c4b8128c770156c409013b07d6b9 # v3.39.3
+        with:
+          sarif_file: results.sarif

swallo-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Project local storage
+.swallo/
+
+# In-repo MCP configs and IDE configs (prefer user-level global config)
+.cursor/
+.cursor/mcp.json
+.vscode/
+.idea/
+.codeium/
+.mcp.json
+*.mcp.json
+.cursorrules
+.windsurfrules
+.agents/
+
+# Testing and linting caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.mustel/
+.coverage
+htmlcov/
+
+# Operating system files
+.DS_Store
+Thumbs.db

swallo-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented here. Format follows Keep a Changelog; versioning follows SemVer. The packet `schema_version` is versioned separately (see `docs/PACKET_SCHEMA.md`).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-10
+
+### Added
+- Core context handoff CLI with 23 commands: `init`, `doctor`, `prompt`, `save`, `import`, `merge`, `resolve`, `show`, `edit`, `approve`, `send`, `load`, `diff`, `list`, `status`, `log`, `staleness`, `drafts`, `breaker`, `bench`, `mcp`, `help`, `version`.
+- Zero-network runtime with content-addressed packet store in SQLite WAL mode.
+- Swallo Canonical JSON v1 serialization and SHA-256 integrity hashing without floating-point numbers.
+- Secret and PII redaction engine with decoded-variant scanning (base64, hex, URL, rot13, reverse, zero-width) and decode-bomb caps.
+- Trojan Source sanitizer neutralizing bidirectional override and Unicode tag controls (CVE-2021-42574).
+- Anti-tamper verification across event log hash chains and MAC-signed approval ledgers.
+- Model Context Protocol (MCP) server with draft quotas, per-session token bucket, and circuit breakers.
+- Adapters for Claude Code, Cursor, and Antigravity IDEs.
+- Optional passphrase-derived Ed25519 digital signatures (`[sign]` extra via cryptography).
+- Deterministic and statistical benchmark harnesses (`swallo bench run` and `swallo bench verify`) with 164-sample anti-overfitting corpus and 20-round realistic-transcript throughput suite.
+- Dual licensing under MIT and Apache-2.0 (`LICENSE-MIT` and `LICENSE-APACHE`).
+- Contributor Covenant Code of Conduct v2.1 (`CODE_OF_CONDUCT.md`).
+
+### Security
+- Defense matrix against Zip-Slip, decompression bombs, symlink escapes, path traversal, and JSON nesting limits.
+- Mandatory interactive TTY approval for context injection; no approve tools exposed to MCP agents.
+- Registered project root enforcement preventing arbitrary directory traversal or rogue MCP workspace configurations.

swallo-0.1.0/CODEOWNERS

@@ -0,0 +1,12 @@
+# Default code owner
+* @raunaknayak12
+
+# Security-sensitive modules requiring maintainer review
+src/swallo/redact/ @raunaknayak12
+src/swallo/store/ledger.py @raunaknayak12
+src/swallo/repo/paths.py @raunaknayak12
+src/swallo/render/sanitize.py @raunaknayak12
+src/swallo/capture/importers/ @raunaknayak12
+src/swallo/server/guards.py @raunaknayak12
+src/swallo/store/registry.py @raunaknayak12
+src/swallo/store/signing.py @raunaknayak12

swallo-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,127 @@
+# 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 e-mail 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 community leaders responsible for enforcement at
+**conduct@swallo.dev** (or by contacting project maintainers privately).
+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][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla-coc].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla-coc]: https://github.com/mozilla/diversity
+

swallo-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Thanks for helping. This project handles private conversation data, so changes are reviewed with extra care.
+
+## Ground rules
+
+- By contributing you agree your contributions are dual-licensed under both the MIT License and the Apache License, Version 2.0.
+- Pure Python. New runtime dependencies need a written justification (see `docs/TRD.md`, dependency policy).
+- No network access in the core. Optional features (`[remote]`) must be opt-in and off by default.
+- Never log, print or store secret or transcript text in error paths. Tests enforce this.
+- Security-sensitive modules (`redact/`, `store/ledger.py`, `repo/paths.py`, `render/sanitize.py`, `capture/importers/`, `server/guards.py`, `store/registry.py`, `store/signing.py`) require review from a code owner.
+
+## Development setup
+
+```
+git clone <repo>
+cd swallo
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check . && mypy src
+```
+
+## Pull requests
+
+1. Open an issue first for non-trivial changes.
+2. Add tests. Parsers and path handling need property-based or fuzz tests.
+3. Update docs and `CHANGELOG.md`.
+4. Schema changes need a version bump, a migrator and a fixture for the old version (`docs/PACKET_SCHEMA.md`).
+5. Benchmark or security claims in docs must match what a test actually shows.
+
+## Contributing benchmark data
+
+Only consented, redacted transcripts. See `docs/BENCHMARKS.md` and `docs/templates/ANNOTATION_GUIDE.md`. Never include real secrets or personal data.
+
+## Code of conduct
+
+Please review and adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) (Contributor Covenant v2.1). Violations can be reported to conduct@swallo.dev.