werktools 0.1.0__tar.gz

werktools-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,72 @@
+---
+name: Bug report
+about: Report a reproducible defect in WERKHub (the local, governed MCP control plane)
+title: "bug: <short summary>"
+labels: [bug, triage]
+assignees: []
+---
+
+<!--
+For a security vulnerability, DO NOT open a public issue.
+Use GitHub private vulnerability reporting (Security > Report a vulnerability)
+and see SECURITY.md. This keeps the fail-closed trust boundary intact.
+-->
+
+## Summary
+
+A clear, one-sentence description of the defect and the observed wrong behavior.
+
+## Surface
+
+Which WERKHub surface is affected (check all that apply):
+
+- [ ] CLI (`werktools hub ...`)
+- [ ] MCP server (`hub serve`)
+- [ ] Dashboard (`hub doctor` / `hub dashboard`)
+- [ ] Policy / classification (gating, allowlist, approval tokens)
+- [ ] Ledger / evidence chain
+- [ ] Other (describe below)
+
+## Steps to reproduce
+
+A minimal, deterministic, offline reproduction (no network, no real keys).
+
+```text
+1.
+2.
+3.
+```
+
+## Expected behavior
+
+What you expected to happen. If this involves a guardrail (deny-by-default,
+fail-closed, approval-gated, ledgered), state the invariant you expected to hold.
+
+## Actual behavior
+
+What actually happened. Paste the exact envelope / error output. Redact any
+secrets and personal paths before pasting.
+
+```text
+<output>
+```
+
+## Environment
+
+- WERKHub version: <e.g. 0.2.0> (`werktools --version` / pyproject)
+- Python version: <e.g. 3.10 / 3.11 / 3.12>
+- OS: <e.g. Windows 11 / Ubuntu 22.04>
+- Install extras: <core only / [server] / [yaml] / [worker] / [all]>
+
+## Impact
+
+- [ ] Guardrail bypass or fail-open behavior (security-relevant — consider private reporting instead)
+- [ ] Data loss / ledger integrity
+- [ ] Crash / unhandled error
+- [ ] Incorrect result, no integrity impact
+- [ ] Cosmetic / docs
+
+## Additional context
+
+Logs, ledger excerpts (redacted), or links. Confirm no secrets or personal
+paths are present in anything you paste.

werktools-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,17 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability (private)
+    url: https://github.com/Shuwajaja/WERKHub/security/advisories/new
+    about: >-
+      Do NOT open a public issue for security problems. Use GitHub private
+      vulnerability reporting. See SECURITY.md for the threat model and scope.
+  - name: Questions & discussion
+    url: https://github.com/Shuwajaja/WERKHub/discussions
+    about: >-
+      Ask usage questions, share ideas, or discuss design before filing a
+      feature request. Keep bug reports and feature requests in the issue tracker.
+  - name: Contributing guide
+    url: https://github.com/Shuwajaja/WERKHub/blob/main/CONTRIBUTING.md
+    about: >-
+      Read the local gate (ruff, mypy, hub doctor invariants, offline tests)
+      and hard guardrails before opening a pull request.

werktools-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,46 @@
+---
+name: Feature request
+about: Propose a capability or change for WERKHub that respects the governed, fail-closed core
+title: "feat: <short summary>"
+labels: [enhancement, triage]
+assignees: []
+---
+
+## Problem
+
+What problem are you trying to solve? Describe the situation and who it affects.
+Lead with the pain, not the solution.
+
+## Proposed change
+
+What you would like WERKHub to do. Be concrete about the surface (CLI, MCP
+server, dashboard, policy, ledger) and the expected behavior.
+
+## Why it belongs in WERKHub
+
+WERKHub is the local, governed MCP control plane: browse, connect, and
+supervise agent MCP extensions, deny-by-default and everything ledgered.
+Explain how this proposal fits that scope rather than expanding it elsewhere.
+
+## Guardrail check
+
+Confirm the proposal is compatible with the project's hard invariants:
+
+- [ ] Keeps the core **stdlib-only** (`dependencies = []`); any new dependency
+      lives behind an optional extra and is imported inside function bodies, not
+      at module scope in the core.
+- [ ] **No daemon / background network** added to the core; long-lived loops
+      stay in the serve/dashboard entry points only.
+- [ ] **Fail-closed**: new write/destructive paths are gated (approval token)
+      and unknown profiles/tools/scopes still deny.
+- [ ] **Ledgered**: new state-changing actions emit a tamper-evident event.
+- [ ] Testable **offline and deterministically** (no network, no real keys).
+
+## Alternatives considered
+
+Other approaches you weighed and why you rejected them.
+
+## Additional context
+
+Mockups, links, prior art, or related issues. Note any new event names or
+policy scopes the change would introduce.

werktools-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,48 @@
+<!--
+WERKHub is the local, governed MCP control plane. Keep the core stdlib-only and
+fail-closed. PRs that touch policy, ledger, or approval-token paths get extra
+scrutiny. Run the full local gate before requesting review.
+-->
+
+## What & why
+
+Briefly describe the change and the problem it solves. Link the issue it closes.
+
+Closes #
+
+## Type of change
+
+- [ ] Bug fix (non-breaking)
+- [ ] New feature (non-breaking)
+- [ ] Breaking change (behavior, CLI, MCP contract, or event names)
+- [ ] Docs / chore / refactor (no behavior change)
+
+## How tested
+
+Describe the offline, deterministic verification. Note new fixtures, cassettes,
+golden files, injected clocks, or platform skip-guards.
+
+## Checklist (required)
+
+- [ ] **Tests added/updated** and pass (`pytest -q`, offline & deterministic)
+- [ ] **ruff clean** (`ruff check src/ tests/ examples/`)
+- [ ] **mypy clean** (`mypy src/werktools`)
+- [ ] **Invariants pass** (`werktools hub doctor`: `dependencies = []`, no module-scope
+      FastMCP outside allowed files, no daemon in core, unique event names)
+- [ ] **Release-hygiene clean** (`python scripts/check_release_hygiene.py --strict`)
+- [ ] **No secrets / no personal paths** committed (keys, tokens, absolute home
+      paths, machine names); redaction holds and unicode-safety passes
+
+## Guardrail impact
+
+- [ ] Core stays **stdlib-only**; any new dependency is behind an optional extra
+      and imported inside function bodies (never module-scope in the core)
+- [ ] No new daemon or background network call in the core
+- [ ] New write/destructive paths are **fail-closed** and approval-gated
+- [ ] New state-changing actions are **ledgered** (tamper-evident events)
+- [ ] Public behavior changes (CLI, MCP contract, event names) are documented
+      in `CHANGELOG.md`
+
+## Notes for the reviewer
+
+Anything reviewers should focus on, trade-offs made, or follow-ups deferred.

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

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[all]
+          pip install ruff mypy pytest
+      - name: Release-hygiene validator (strict)
+        run: python scripts/check_release_hygiene.py --strict
+      - name: Doctor (guardrail invariants)
+        run: python -c "from werktools.cli import main; import sys; sys.exit(main(['hub','doctor']))"
+      - name: Unicode safety
+        run: python scripts/check_unicode_safety.py --strict .
+      - name: Lint
+        run: ruff check src/ tests/ examples/
+      - name: Types
+        run: mypy src/werktools --ignore-missing-imports
+      - name: Tests (offline)
+        run: pytest
+
+
+  bare-install:
+    name: Bare install smoke (no extras)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install core only (no extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+      - name: Import smoke
+        run: |
+          python -c "import werktools; from werktools.envelope import ok, err; from werktools.ledger import append, read; from werktools.classify import classify_tool; from werktools.policy import decide; from werktools.profile import load_profile; from werktools.redaction import redact_payload; from werktools.catalog import CatalogCard; print('core import OK')"
+      - name: Extras guard smoke
+        run: python -m pytest tests/test_extras_matrix.py -q

werktools-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,55 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+# Allow only one concurrent deployment
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: pip install -r requirements-docs.txt
+
+      - name: Build docs
+        run: mkdocs build --strict --site-dir _site
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

werktools-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+# OPERATOR-SIGN-OFF: requires a PyPI token (or OIDC trusted publishing) and a
+# real version tag. Do not enable until the operator has set PYPI_API_TOKEN.
+# Fail-closed: refuses pre-release/rc/dev builds, requires the tag to match the
+# package version, and is gated behind a protected `pypi` environment (add
+# required reviewers in repo Settings -> Environments).
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "tag=$TAG pkg=$PKG"
+          test "$TAG" = "$PKG" || { echo "Tag $TAG != package version $PKG"; exit 1; }
+      - name: Refuse pre-release / rc / dev builds
+        run: |
+          PKG=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          case "$PKG" in
+            *rc*|*a*|*b*|*dev*|*alpha*|*beta*) echo "Refusing to publish pre-release $PKG"; exit 1 ;;
+          esac
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+      - name: Check artifacts
+        run: twine check dist/*
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

werktools-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.codex-remote-attachments/
+.deepeval/
+.werktools/
+outputs/
+
+# Secrets & local config — never commit
+.env
+.env.*
+!.env.example
+*.local.*
+*.key
+*.pem
+*.p12
+credentials.json
+secrets.*
+.mcp.json
+.venv/
+venv/
+
+# Internal launch-prep drafts (superseded by the real README/CI/SECURITY files;
+# kept locally, never published — one draft carried a personal email)
+docs/launch-drafts/
+
+# MkDocs build output (docs site)
+/site/

werktools-0.1.0/AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+Project context for AI coding agents (and humans) working on **werktools / WERKHub** —
+the local, governed MCP control plane. This file is the authoritative source of repo
+rules; see [README.md](README.md) for the full overview and [CONTRIBUTING.md](CONTRIBUTING.md)
+for setup.
+
+## What this repo is
+
+A Python package (`werktools`) that ships the WERKHub MCP gateway: a stdio MCP server, a
+local HTTP dashboard, a CLI, and local tool slices. A separate native desktop console
+lives under `desktop/`. The package core is **stdlib-only and offline-testable**.
+
+## Hard rules
+
+- **Keep the core dependency-free.** Third-party imports are allowed only inside the
+  optional extras (`server` / `worker` / `yaml`); every other sub-import must succeed with
+  zero third-party packages installed (`tests/test_extras_matrix.py` enforces this).
+- **No daemon constructs in core modules.** No extra OS threads, busy-loops, scheduled
+  async tasks, exit hooks, or threaded HTTP servers. This is machine-checked by the
+  invariants module under src/werktools/hub (its run_all check must return all-empty).
+- **Deny-by-default, fail-closed.** A tool runs only when `enforce()` returns `allow`.
+  Resolve unknown or ambiguous states to the safe option.
+- **Presence-only on secrets.** Extract env-var key *names*, never values; mask secrets
+  before anything is logged or written to the ledger.
+- **The ledger is append-only and hash-chained.** Treat JSONL events, SQLite, and the
+  ledger as the source of truth — not draft Markdown.
+- **ASCII-only in printed/logged output.** No em-dashes or curly quotes in strings the CLI
+  or ledger emit (they corrupt on legacy code pages).
+
+## Workflow
+
+Before reporting a change complete, run and pass:
+
+```
+pytest -q                                                   # the test suite
+python -m mypy src/werktools                                # types
+python -m ruff check src                                    # lint
+python -c "from werktools.hub.invariants import run_all; print(run_all())"   # invariants
+python -m werktools canon check --strict                    # repo-canon and release hygiene
+```
+
+Agents should:
+
+- inspect the existing structure before changing code;
+- prefer small, reviewable changes and add tests for new behavior;
+- update docs when behavior changes; keep generated files separate from source;
+- preserve evidence and avoid deleting files unless explicitly instructed.
+
+Agents should not:
+
+- invent missing architecture or silently rewrite unrelated files;
+- treat draft documents as production truth;
+- bypass the policy, approval, or invariant layers.
+
+## License
+
+AGPL-3.0-or-later. Contributions are accepted under the same license.

werktools-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to werktools are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - 2026-07-08
+
+Initial release of WERKHub — the local, governed MCP control plane.
+
+### Added
+
+- **MCP Bridge Server** — single FastMCP endpoint with 8 always-on bridge tools:
+  `tool_search`, `tool_describe`, `tool_call`, `profile_info`, `ledger_recent`,
+  `approval_status`, `hub_status`, `registry_search`.
+- **Policy Gate** — deny-by-default enforcement via `enforce()`; allowlist-driven
+  trust tiers (Tier-1 OCI-pinned, Security-Scanned, Community-Unverified).
+- **Approvals** — one-use token-gated install approval, argument-bound, expiring.
+- **Tamper-Evident Ledger** — hash-chained JSONL evidence log.
+- **Downstream Relay** — MCP Discovery + policy-gated forwarding to downstream servers.
+- **Process Lifecycle** — POSIX process-group spawning (`start_new_session=True`),
+  Windows Job Object bind (`KILL_ON_JOB_CLOSE`), TTL-based reaper with SIGTERM/SIGKILL
+  escalation, cross-session orphan sweep.
+- **Diagnostics** — discovery-failure classifier (`hub/diagnose.py`) with actionable
+  verdicts (single_instance, not_found, needs_auth, missing_cwd_or_file, startup_hang).
+- **Runtime Doctor** — detects Claude Code, Cursor, Windsurf, Gemini CLI, Kimi,
+  Antigravity, Codex, Goose, VS Code MCP; all invariants check (core deps, lifecycle
+  extras, event names, subprocess deferral).
+- **Local Tool Slices** — truth, mine, trace, vault, data-gate, swarm, cost, eval,
+  audit, skills, integration-gate, canon.
+- **Desktop Dashboard** — local HTTP supervisor console + Deno/Vite/React supervisor UI.

werktools-0.1.0/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "WERKHub"
+abstract: "WERKHub is a local, governed MCP control plane to browse, connect, and supervise agent MCP extensions."
+type: software
+authors:
+  - family-names: "Langner"
+    given-names: "Christian"
+repository-code: "https://github.com/ChristianLangner/WERK_HUB"
+license: AGPL-3.0-or-later
+version: 0.2.0rc2
+# date-released: YYYY-MM-DD  # TODO(operator): set the release date when publishing

werktools-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+This project adopts the **Contributor Covenant, version 2.1** as its code of conduct.
+The full, canonical text is published here:
+https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+
+## In short
+
+Everyone interacting in this project — issues, pull requests, discussions, and any
+other channel — is expected to be respectful, considerate, and professional. We want
+a welcoming, inclusive community focused on building good software together. Conduct
+that makes the community unwelcoming or unsafe for others is not acceptable.
+
+## Reporting
+
+If you experience or witness unacceptable behaviour, report it **privately** to the
+maintainers via GitHub's private vulnerability reporting
+(repository **Security → Report a vulnerability**); see [SECURITY.md](SECURITY.md).
+All reports are reviewed and handled confidentially. The maintainers are responsible
+for clarifying standards and may take appropriate, fair corrective action in response
+to any behaviour they deem inappropriate.
+
+## Scope
+
+This Code of Conduct applies within all project spaces and in public spaces when an
+individual is representing the project or its community.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1. Community Impact Guidelines and the full enforcement ladder are part of
+the canonical text linked above.

werktools-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to werktools / WERKHub
+
+WERKHub is a local, governed MCP control plane. The core stays stdlib-only
+and offline-testable. Contributions are welcome under AGPL-3.0-or-later
+(the project license — see [LICENSE](LICENSE)).
+
+## Setup
+
+```bash
+pip install -e .[all]    # core + server + yaml extras
+```
+
+## The local gate (all offline, no network, no keys)
+
+```bash
+python -c "from werktools.cli import main; import sys; sys.exit(main(['hub','doctor']))"  # guardrail invariants
+ruff check src/ tests/ examples/
+mypy src/werktools --ignore-missing-imports
+pytest -q
+```
+
+`hub doctor` enforces the hard invariants: `dependencies = []`, no
+module-scope FastMCP outside the two allowed files, no daemon in the core,
+unique event names. Keep them green.
+
+## Hard guardrails
+
+- Core stays stdlib-only; optional deps live behind extras (`[server]`,
+  `[yaml]`, `[worker]`, `[lifecycle]`) and are imported only inside function
+  bodies, never at module scope in the core.
+- No daemon in library modules. Long-lived loops live only inside the serve/
+  dashboard entry points.
+- Fail-closed policy; everything ledgered; write/destructive actions gated.
+- Tests must be offline and deterministic (fake child processes, cassettes,
+  golden fixtures, injected clocks; platform skip-guards for win/posix).
+
+## TDD
+
+Write the failing test first, confirm red, implement the minimum, confirm
+green. One focused change per commit.