quor 0.1.0__tar.gz

quor-0.1.0/.github/workflows/canary.yml

@@ -0,0 +1,108 @@
+name: Canary — Claude Code Compatibility
+
+# Runs weekly to catch Anthropic changing the Claude Code hook format before
+# users do. Also triggerable manually for immediate spot-checks.
+
+on:
+  schedule:
+    - cron: '0 8 * * 1'  # Every Monday at 08:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  canary:
+    name: Hook compatibility — Claude Code latest
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Set up Node.js (for Claude Code)
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+
+      - name: Install Claude Code (latest, unpinned)
+        # Not pinned intentionally — the canary exists to catch Anthropic
+        # changing hook format in a new release before our users hit it.
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Record Claude Code version
+        run: |
+          echo "## Claude Code version" >> $GITHUB_STEP_SUMMARY
+          npm ls -g @anthropic-ai/claude-code --json 2>/dev/null \
+            | python3 -c "import sys,json; d=json.load(sys.stdin); print(list(d.get('dependencies',{}).values())[0].get('version','unknown'))" \
+            || echo "version unavailable" >> $GITHUB_STEP_SUMMARY
+
+      - name: Install Quor from source
+        run: pip install -e ".[dev]"
+
+      - name: Install test plugin fixture
+        run: pip install -e ./tests/fixtures/test_plugin
+
+      - name: Verify hook responds to current Claude Code PreToolUse format
+        # Send the JSON format Claude Code actually sends via PreToolUse hook,
+        # verify the response is valid JSON with the expected command rewrite.
+        run: |
+          PAYLOAD='{"tool_name":"Bash","tool_input":{"command":"git status"}}'
+          RESULT=$(echo "$PAYLOAD" | python -m quor hook claude)
+          echo "Hook response: $RESULT"
+
+          # Verify: response is valid JSON and command is rewritten
+          echo "$RESULT" | python3 - <<'EOF'
+          import sys, json
+          try:
+              d = json.load(sys.stdin)
+          except json.JSONDecodeError as e:
+              print(f"FAIL: hook response is not valid JSON: {e}", file=sys.stderr)
+              sys.exit(1)
+          cmd = d.get("tool_input", {}).get("command", "")
+          if "quor git status" not in cmd:
+              print(f"FAIL: expected 'quor git status' in command, got {cmd!r}", file=sys.stderr)
+              sys.exit(1)
+          print(f"OK: command rewritten to {cmd!r}")
+          EOF
+
+      - name: Verify hook preserves extra JSON fields
+        # Claude Code may add extra fields to the payload; Quor must not drop them.
+        run: |
+          PAYLOAD='{"tool_name":"Bash","tool_input":{"command":"git status"},"session_id":"abc123","extra_field":"preserved"}'
+          RESULT=$(echo "$PAYLOAD" | python -m quor hook claude)
+          echo "$RESULT" | python3 - <<'EOF'
+          import sys, json
+          d = json.load(sys.stdin)
+          if d.get("session_id") != "abc123":
+              print("FAIL: extra fields were dropped by the hook", file=sys.stderr)
+              sys.exit(1)
+          if d.get("extra_field") != "preserved":
+              print("FAIL: extra_field was dropped by the hook", file=sys.stderr)
+              sys.exit(1)
+          print("OK: extra JSON fields preserved")
+          EOF
+
+      - name: Verify quor init --claude writes valid settings.json
+        run: |
+          mkdir -p /tmp/canary-claude
+          python -m quor init --claude --yes --settings-path /tmp/canary-claude/settings.json
+          python3 -c "
+          import json, sys
+          with open('/tmp/canary-claude/settings.json') as f:
+              d = json.load(f)
+          hooks = d.get('hooks', {}).get('PreToolUse', [])
+          if not any('claude-hook.ps1' in str(h) for entry in hooks for h in entry.get('hooks', [])):
+              print('FAIL: hook not found in settings.json', file=sys.stderr)
+              sys.exit(1)
+          print('OK: hook registered in settings.json')
+          "
+
+      - name: Run full test suite
+        # The canary also proves Quor's test suite passes against the latest
+        # Claude Code version (package installed above).
+        run: pytest tests/ -q --tb=short -x

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

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install project with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Install test plugin fixture
+        run: pip install -e ./tests/fixtures/test_plugin
+
+      - name: Lint — ruff
+        run: ruff check quor/ tests/
+
+      - name: Type check — mypy
+        run: mypy quor/
+
+      - name: Tests
+        run: pytest tests/ --cov=quor --cov-report=term-missing

quor-0.1.0/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,84 @@
+name: Publish to TestPyPI
+
+# Manual dry-run publish used to validate packaging/publishing before tagging
+# a real release. Trigger from the Actions tab, supplying the version you
+# expect to publish (must match pyproject.toml).
+#
+# Mirrors release.yml's build/verify/publish structure as closely as possible
+# so a TestPyPI dry run exercises the same path the real release will use.
+# Independent of release.yml — does not touch the tag-triggered real-PyPI
+# release path.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Expected version to publish (must match pyproject.toml, e.g. 0.1.0)'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tooling
+        run: pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Verify distribution metadata
+        run: twine check dist/*
+
+      - name: Verify input version matches package version
+        run: |
+          INPUT_VERSION="${{ inputs.version }}"
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$INPUT_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Input version ($INPUT_VERSION) does not match pyproject.toml version ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Input version $INPUT_VERSION matches package version $PKG_VERSION"
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 30
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Check TestPyPI token is configured
+        run: |
+          if [ -z "${{ secrets.TEST_PYPI_API_TOKEN }}" ]; then
+            echo "::error::TEST_PYPI_API_TOKEN is not set for the 'testpypi' environment. Configure it under Settings > Environments > testpypi before this job can publish."
+            exit 1
+          fi
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          repository-url: https://test.pypi.org/legacy/

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

@@ -0,0 +1,101 @@
+name: Release
+
+# Triggered by pushing a version tag, e.g.: git tag v0.1.0 && git push origin v0.1.0
+#
+# Builds wheel + sdist, verifies them, attaches them to a GitHub Release,
+# and (only if a PYPI_API_TOKEN secret is configured for the `pypi` GitHub
+# environment) publishes to PyPI. Without that secret configured, the
+# publish job runs and fails fast at the "Check PyPI token is configured"
+# step rather than silently skipping — so a maintainer always gets a clear
+# signal instead of a false "success".
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build and verify distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tooling
+        run: pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Verify distribution metadata
+        run: twine check dist/*
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) does not match pyproject.toml version ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Tag $GITHUB_REF_NAME matches package version $PKG_VERSION"
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 30
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: false
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Check PyPI token is configured
+        run: |
+          if [ -z "${{ secrets.PYPI_API_TOKEN }}" ]; then
+            echo "::error::PYPI_API_TOKEN is not set for the 'pypi' environment. Configure it under Settings > Environments > pypi before this job can publish. Skipping publish for this run."
+            exit 1
+          fi
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

quor-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.python-version
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# Distribution / packaging
+*.whl
+*.tar.gz
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

quor-0.1.0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to Quor are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] — Internal Alpha
+
+First public-quality release. Quor is a rule-based command-output
+optimization and context-compression layer for AI coding assistants: it
+runs your command, captures the output, and applies a deterministic,
+fail-open filtering pipeline before the output reaches the assistant's
+context window.
+
+### Core pipeline (Phases 0-6)
+
+- **ContentMask pipeline** — the `KEEP` / `COMPRESS` / `PROTECT` line-level
+  decision model that every compression stage operates on. `PROTECT` is
+  immutable once set: no later stage can downgrade it (ADR-003, "Core
+  Abstraction — ContentMask").
+- **Five built-in compression stages** — `remove_ansi`, `strip_lines`,
+  `deduplicate_consecutive`, `group_repeated`, `max_tokens`.
+- **Five built-in filters** — `git`, `pytest`, `build` (mypy/ruff), `cat`,
+  and a generic ANSI+truncation fallback, each with inline TOML tests.
+- **Three-tier filter registry** — project > user > built-in precedence
+  (ADR "Filter Registry — Three-Tier Lookup").
+- **Command rewriter and classifier** — quote-aware shell lexer, rule-based
+  command classification, 100+ fixture-driven tests.
+- **Claude Code hook adapter** — intercepts the `PreToolUse` hook, rewrites
+  the command to route through Quor, preserves every extra JSON field
+  Claude Code sends.
+- **SQLite + JSONL dual tracking** — background-thread writes, WAL mode,
+  never blocks the hook path (ADR "Persistence — Dual (SQLite + JSONL)").
+- **Six CLI commands** — `init --claude`, `validate`, `explain`, `gain`,
+  `verify`, `doctor` — plus the `schema` utility command for the filter
+  JSON Schema. Both `quor` and `qr` are registered entry points.
+
+### Plugin Infrastructure (Phase 8)
+
+- Public `Plugin` Protocol (`quor.plugins.base`) — `@runtime_checkable`,
+  versioned via `QUOR_PLUGIN_API_VERSION`, lifecycle-managed
+  (`initialize` / `execute` / `shutdown`).
+- `PluginRegistry` — three-tier registration (project > user > builtin),
+  deterministic execution order, fully fail-open execution.
+- Deliberately kept separate from the existing `StageHandler` Protocol:
+  `StageHandler` is TOML-configurable, line-level, stateless compression;
+  `Plugin` is Python-coded, lifecycle-managed middleware for telemetry,
+  policy, and routing (ADR "Plugin Architecture — Two-Tier Separation").
+
+### Plugin Discovery & Loading (Phase 9)
+
+- Entry-point discovery for both `quor.compression_stage` and `quor.plugin`
+  groups via `importlib.metadata`, with a package-set-hash-invalidated
+  local cache.
+- `api_version` compatibility check accepts any version `<= QUOR_PLUGIN_API_VERSION`
+  and rejects only newer ones — plugins built against an older API keep
+  working as the API evolves.
+- `file://` escape hatch for loading a local `StageHandler` during
+  development without packaging it.
+- `quor doctor` plugin diagnostics: lists discovered stages and plugins
+  (including each plugin's declared version), and flags load failures.
+  Tier is deliberately not reported for entry-point-discovered plugins —
+  `importlib.metadata` carries no signal that maps to project/user/builtin,
+  so this is a documented scope boundary, not a bug (see DECISIONS.md,
+  ADR "Plugin Architecture — Two-Tier Separation").
+- End-to-end fail-open verification: a real (non-mock) plugin that raises
+  during `execute()` is driven through the actual dispatcher, confirming
+  the exception is isolated, a warning is emitted, and the hook still
+  returns valid output.
+
+### Release Hardening
+
+A dedicated pass to close reliability gaps before packaging:
+
+- Eliminated the last local-machine dependency in the test suite (CLI
+  tests previously read the developer's real `~/.claude/settings.json`);
+  all tests now inject an isolated settings path.
+- `ruff` and `mypy` are exact-pinned in dev dependencies; `pytest`/`pytest-cov`
+  use bounded ranges. CI now lints `tests/` as well as `quor/` (ADR
+  "Release Hardening — Dev Tooling Version Policy & CI Lint Scope").
+- Removed `ExitCode.PLUGIN_ERROR` as dead code — every `PluginError` is
+  caught internally by Quor's fail-open contract and never reaches a
+  process exit code.
+- Python compatibility verified by actually running the full suite (ruff,
+  mypy, pytest) on Python 3.11, 3.13, and 3.14 in isolated virtual
+  environments, not just static review.
+
+### Testing
+
+- **605 tests passing**, `ruff` and `mypy` clean on both `quor/` and
+  `tests/`.
+- ≥80% coverage on `quor/pipeline/`, `quor/filters/`, and `quor/rewrite/`
+  (93% overall).
+- Dedicated chaos/fail-open suite: corrupted TOML, malformed hook JSON,
+  permission errors, hook timeout, pathological regex (ReDoS) — all
+  degrade to the original, unfiltered output rather than crashing or
+  losing data.
+- Error-safety snapshot tests across all 7 built-in filters, confirming
+  failure-relevant lines are never removed.
+- CI on `windows-latest` and `ubuntu-latest`; a weekly canary workflow
+  installs unpinned `@anthropic-ai/claude-code` to catch upstream hook
+  format changes before users do.
+
+### Known limitations
+
+- The `AUDIT` / `OPTIMIZE` / `SIMULATE` operating-mode system is
+  display-only in this release — `quor doctor` and `quor gain` show the
+  configured mode, but the dispatcher does not yet branch on it. This is
+  an intentional, scoped roadmap item (see PROJECT_STATUS.md), not a bug.
+- Not yet published to PyPI.
+
+[0.1.0]: https://github.com/priyanshup/Quor/releases/tag/v0.1.0

quor-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,69 @@
+# 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, 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:
+
+- 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 for mistakes, and learning from them
+- Focusing on what is best for the community, not just the individual
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and unwelcome sexual attention
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+Technical disagreements are settled by evidence — benchmark results, test
+cases, and precedent in `docs/final/DECISIONS.md` — not by persistence or
+volume. See `CONTRIBUTING.md` for how design and review decisions are made.
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our
+standards of acceptable behavior and will take appropriate and fair
+corrective action in response to any behavior deemed inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces (issues, pull
+requests, discussions) and also applies when an individual is officially
+representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers by opening a confidential report via GitHub
+(see the repository's Security & Conduct contact in `SECURITY.md`), or by
+emailing the maintainer listed in the repository's commit history. All
+complaints will be reviewed and investigated promptly and fairly.
+
+This project does not yet have a dedicated conduct-response team — as a
+pre-1.0, single-maintainer project, reports are currently handled directly
+by the project owner. This will be revisited as the contributor base grows.
+
+## 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.
+
+[homepage]: https://www.contributor-covenant.org