privacyfence 4.0.0a11__tar.gz

privacyfence-4.0.0a11/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# All files require review from the repository owner.
+* @andras-tkcs

privacyfence-4.0.0a11/.github/workflows/build.yml

@@ -0,0 +1,114 @@
+name: Build & Release DMG
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:   # allow manual runs from the Actions tab
+
+jobs:
+  build:
+    runs-on: macos-latest   # arm64 Apple Silicon runner
+    permissions:
+      contents: write
+    env:
+      # Name of the notarytool keychain profile created fresh on each runner
+      # by the "Import notarization credentials" step below — not a secret,
+      # just needs to match between that step and the build step.
+      NOTARIZE_PROFILE: privacyfence-ci-notary
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history + tags -- setuptools_scm needs them (see CLAUDE.md)
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install system dependencies
+        run: brew install create-dmg
+
+      - name: Install Python dependencies
+        run: pip install -e ".[dev]"
+
+      # ── Import Developer ID certificate for signing ────────────────────────
+      # Requires these GitHub secrets (Settings → Secrets and variables →
+      # Actions):
+      #   MACOS_CERTIFICATE      — base64-encoded "Developer ID Application"
+      #                            .p12 (cert + private key)  (base64 -i cert.p12 | pbcopy)
+      #   MACOS_CERTIFICATE_PWD  — the .p12 export password
+      #   SIGN_IDENTITY          — e.g. "Developer ID Application: Your Name (TEAMID)"
+      - name: Import signing certificate
+        env:
+          MACOS_CERTIFICATE: ${{ secrets.MACOS_CERTIFICATE }}
+          MACOS_CERTIFICATE_PWD: ${{ secrets.MACOS_CERTIFICATE_PWD }}
+        run: |
+          echo "$MACOS_CERTIFICATE" | base64 --decode > certificate.p12
+          security create-keychain -p "" build.keychain
+          security default-keychain -s build.keychain
+          security unlock-keychain -p "" build.keychain
+          security import certificate.p12 -k build.keychain \
+            -P "$MACOS_CERTIFICATE_PWD" -T /usr/bin/codesign
+          security set-key-partition-list -S apple-tool:,apple: -s \
+            -k "" build.keychain
+          rm certificate.p12
+
+      # ── Import notarization credentials ─────────────────────────────────────
+      # Runners are ephemeral, so the notarytool profile is (re-)registered
+      # fresh every run rather than assumed to already exist. Requires an
+      # App Store Connect API key with the "Developer" role (Users and Access
+      # → Integrations → App Store Connect API) and these GitHub secrets:
+      #   APPLE_API_KEY_P8      — base64-encoded AuthKey_<KEYID>.p8  (base64 -i AuthKey_*.p8 | pbcopy)
+      #   APPLE_API_KEY_ID      — the Key ID shown next to the key
+      #   APPLE_API_ISSUER_ID   — the Issuer ID (same for all keys on the team)
+      - name: Import notarization credentials
+        env:
+          APPLE_API_KEY_P8: ${{ secrets.APPLE_API_KEY_P8 }}
+          APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
+          APPLE_API_ISSUER_ID: ${{ secrets.APPLE_API_ISSUER_ID }}
+        run: |
+          echo "$APPLE_API_KEY_P8" | base64 --decode > apple_api_key.p8
+          xcrun notarytool store-credentials "$NOTARIZE_PROFILE" \
+            --key apple_api_key.p8 \
+            --key-id "$APPLE_API_KEY_ID" \
+            --issuer "$APPLE_API_ISSUER_ID"
+          rm apple_api_key.p8
+
+      - name: Build .app and DMG
+        env:
+          SIGN_IDENTITY: ${{ secrets.SIGN_IDENTITY }}
+          TELEGRAM_API_ID: ${{ secrets.TELEGRAM_API_ID }}
+          TELEGRAM_API_HASH: ${{ secrets.TELEGRAM_API_HASH }}
+        run: bash scripts/build_dmg.sh
+
+      - name: Upload DMG as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: PrivacyFence-dmg
+          path: dist/PrivacyFence-*.dmg
+          retention-days: 30
+
+      # Attach to the GitHub Release when triggered by a version tag. A tag
+      # ending in -beta/-rc (e.g. v3.2.0-beta) publishes as a GitHub
+      # prerelease -- update_checker.py's beta update channel reads exactly
+      # this flag off the releases list, so an unmarked tag would be
+      # invisible to it.
+      #
+      # Alongside the DMG, also attach the two org config build scripts
+      # (scripts/build_org_bundle.py and scripts/sync_room_directory.py) as
+      # their own downloadable assets. They're stdlib-only / a checked-out
+      # copy is not what IT admins are expected to go find -- unlike the
+      # rest of scripts/, these two are themselves a release output, run by
+      # org admins (not contributors) to produce/update the org_config.json
+      # bundle distributed to end users -- see their own docstrings and
+      # docs/google-cloud-setup.md, docs/slack-setup.md,
+      # docs/salesforce-setup.md, docs/atlassian-setup.md.
+      - name: Attach release assets
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/PrivacyFence-*.dmg
+            scripts/build_org_bundle.py
+            scripts/sync_room_directory.py
+          prerelease: ${{ contains(github.ref_name, '-beta') || contains(github.ref_name, '-rc') }}

privacyfence-4.0.0a11/.github/workflows/publish-pypi.yml

@@ -0,0 +1,93 @@
+name: Publish to PyPI
+
+# Same trigger as build.yml (see CLAUDE.md's "Releasing" section) -- one tag
+# push does everything: builds and signs the DMG (build.yml) *and* builds
+# and publishes the sdist/wheel (this workflow), with no separate step.
+#
+# Publishing itself uses PyPI's OIDC "Trusted Publisher" flow
+# (pypa/gh-action-pypi-publish), not a stored API token: GitHub mints a
+# short-lived OIDC token for the job (permissions: id-token: write below),
+# and PyPI/TestPyPI trade it for a one-shot upload credential themselves.
+# There is no long-lived secret anywhere for this workflow to leak. Before
+# this workflow can publish for the first time, a maintainer has to
+# register it as a Trusted Publisher on both test.pypi.org and pypi.org --
+# see CLAUDE.md.
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:   # rerun by hand, e.g. after a failed publish -- point it
+                        # at a tagged commit, or the build carries a local
+                        # version segment (+g<sha>) that both indexes reject
+
+# Restrictive default for GITHUB_TOKEN, per CodeQL's actions/missing-workflow-
+# permissions check -- only `build` actually inherits this (it checks out the
+# repo); the two publish jobs below declare their own narrower job-level
+# `permissions:` (id-token: write only, no contents access at all), which
+# replaces this default for them rather than adding to it.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest   # pure Python sdist/wheel -- no macOS-only step needed
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history + tags -- setuptools_scm needs them (see CLAUDE.md)
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Build sdist and wheel
+        run: |
+          pip install --upgrade pip build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pypi-dist
+          path: dist/
+
+  # Always published first -- rehearses the real upload (same files, same
+  # metadata) against TestPyPI before anything reaches the real index.
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi   # must match the Environment name on TestPyPI's
+                             # Trusted Publisher entry, if one was set there
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: pypi-dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true   # lets a rerun after a partial failure succeed
+                                 # without erroring on files TestPyPI already has
+
+  # Gated behind the TestPyPI job above, and behind the "pypi" GitHub
+  # Environment's own protection rules if any are configured (e.g. a
+  # required reviewer) -- see CLAUDE.md for setting that up.
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi   # must match the Environment name on PyPI's own
+                         # Trusted Publisher entry, if one was set there
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: pypi-dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

privacyfence-4.0.0a11/.github/workflows/tests.yml

@@ -0,0 +1,112 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:   # allow manual runs from the Actions tab
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    # macOS-only project (rumps/PyObjC, real Unix-socket/osascript-backed
+    # tests) — must run on the same platform the app actually ships for.
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history + tags -- setuptools_scm needs them (see CLAUDE.md)
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        run: pip install -e ".[test]"
+
+      - name: Install shim dependencies
+        run: npm ci
+        working-directory: mcpb/shim
+
+      # mcpb/shim/'s own suite (daemon discovery/launch, the stdio<->
+      # Streamable HTTP proxy — see docs/https-connector-refactor-plan.md
+      # §12, D11) runs against mcpb/shim/src/*.ts directly via tsx. It's the
+      # only Node suite left in this repo since P5 retired the bridge.
+      - name: Run shim test suite
+        run: npm test
+        working-directory: mcpb/shim
+
+      - name: Type-check shim
+        run: npm run typecheck
+        working-directory: mcpb/shim
+
+      # tests/integration/test_shim_mcp_contract.py spawns the real built
+      # shim.js against a real /mcp endpoint, so it needs to be built before
+      # pytest runs (the test builds it lazily on a cache miss too, but
+      # building here keeps that cost out of the timed test step and fails
+      # fast on a build error instead of a confusing test skip).
+      - name: Build shim
+        run: npm run build
+        working-directory: mcpb/shim
+
+      # Plain `pytest` already fails the step (non-zero exit) on the first
+      # failing test — no extra flags needed to enforce a 100% pass rate.
+      # pytest-timeout (configured in pyproject.toml) also fails any test
+      # that hangs, so a stuck test can't stall the job indefinitely. The
+      # coverage report here is informational only — nothing gates on it.
+      - name: Run test suite (100% pass rate required)
+        run: pytest -v --cov=src/privacyfence --cov-report=term-missing
+
+  test-linux:
+    # The platform-independent subset, starting at P1 (see
+    # docs/https-connector-refactor-plan.md §12 and
+    # docs/testing-policy.md §1): everything under web/, web_approval_ui.py,
+    # card_builder.py, and approval_icons.py has no AppKit/PyObjC dependency
+    # at all, and is what keeps P10's eventual cross-platform claim honest
+    # rather than aspirational. This does not replace the macOS job above --
+    # that one still covers the full suite, including everything genuinely
+    # macOS-only, and is what a PR needs to pass to merge.
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history + tags -- setuptools_scm needs them (see CLAUDE.md)
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      # rumps/pyobjc-framework-* carry a `sys_platform == 'darwin'` marker
+      # (pyproject.toml), so this installs everything else -- the AppKit-only
+      # dependencies are simply absent here, same as on any non-macOS
+      # PrivacyFence deployment.
+      - name: Install dependencies
+        run: pip install -e ".[test]"
+
+      # --ignore the handful of test modules that import an AppKit-tainted
+      # module (approval_popup.py, approval_window.py, dialog_window.py,
+      # menu_bar.py) directly at module scope, so their absence on this
+      # platform is a real ImportError rather than something a skip marker
+      # could catch -- see docs/testing-policy.md §1 for the reasoning and
+      # the parallel case (test_settings_window.py) that *does* defer its
+      # AppKit import far enough to skip cleanly here instead. tests/
+      # integration/ is excluded too -- most of it drives the real Node
+      # shim, out of scope for this job (covered on the macOS job instead);
+      # test_mcp_daemon_contract.py itself needs no Node and could run
+      # here, but stays grouped with the rest of the directory for
+      # simplicity rather than special-cased out of this ignore.
+      - name: Run the platform-independent test subset
+        run: >
+          pytest tests/unit -v
+          --ignore=tests/unit/test_approval_popup.py
+          --ignore=tests/unit/test_approval_window.py
+          --ignore=tests/unit/test_dialog_window.py
+          --ignore=tests/unit/test_menu_bar.py

privacyfence-4.0.0a11/.gitignore

@@ -0,0 +1,71 @@
+# Credentials and secrets
+credentials/*
+!credentials/.gitkeep
+org/*
+.env
+*.pem
+*.key
+*.p12
+src/privacyfence/_telegram_credentials.py
+scripts/dev_env.sh
+# scripts/sync_room_directory.py's OAuth token for the admin-scoped Google
+# Cloud project it syncs the room directory from -- dev-mode data_dir() is
+# the repo root, same as the other credential paths above.
+.room_sync_token.json
+
+# User configuration (keep only the .example)
+config/settings.yaml
+config/settings.local.yaml
+
+# Local runtime caches (dev-mode data_dir() is the repo root -- see paths.py)
+resource_name_cache.json
+update_check_cache.json
+
+# QA fixture manifest (keep only the .example) -- reveals which real
+# project/space/folder/calendar/list/channel/chat a QA environment uses,
+# on which real accounts. See tests/fixtures/qa_environment.yaml.example.
+tests/fixtures/qa_environment.yaml
+
+# Claude Code
+.claude/
+
+# Lock files
+*.lock
+
+# Python
+*.pyc
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Node (mcpb/shim/)
+node_modules/
+*.tsbuildinfo
+env/
+
+# Test / coverage artifacts
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Logs
+*.log
+logs/
+
+# macOS
+.DS_Store
+*.dmg
+*.mcpb
+
+# IDE
+.idea/
+.vscode/

privacyfence-4.0.0a11/CLAUDE.md

@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+Process notes for working on PrivacyFence with Claude Code. For code/test conventions see
+[`docs/coding-and-testing-guidelines.md`](docs/coding-and-testing-guidelines.md); for contribution
+process (forking, issues, license) see [`CONTRIBUTING.md`](CONTRIBUTING.md). This file covers the
+parts of the workflow that live only in git history, not in a doc — release mechanics and branch
+hygiene.
+
+## Releasing
+
+There is no version string in the source tree and no version-bump commit. `pyproject.toml` declares
+`dynamic = ["version"]`; the real version is derived from git tags by `setuptools_scm`
+(`[tool.setuptools_scm]` in `pyproject.toml`), and `src/privacyfence/__init__.py` reads it back at
+import time via `importlib.metadata.version("privacyfence")`. This replaced the old two-file
+hand-bumped scheme (`pyproject.toml`'s `project.version` + `__init__.py`'s `__version__`, kept in
+sync by a dedicated `Bump to vX.Y.Z` commit) specifically to avoid that scheme's failure mode:
+parallel branches (see worktrees below) both claiming the same next version, one bump commit landing
+after another release already took that number (see `d929510`, "Revert version bump — will release
+together with other pending CRs", from back when that was still how it worked).
+
+**Cutting a release is a tag, not a commit.** Once `main` is at the commit you want to release, tag
+it and push the tag:
+
+```
+git tag v4.0.0            # stable
+git tag v4.0.0a13          # pre-release: a=alpha, b=beta, rc=release-candidate (PEP 440 short form)
+git push origin <tag>
+```
+
+That tag push is what `.github/workflows/build.yml` **and** `.github/workflows/publish-pypi.yml`
+both trigger on (`on: push: tags: ['v*']`) — the former builds and signs the DMG and attaches it to
+a GitHub Release, marked prerelease iff the tag contains `a`, `b`, or `rc` (`update_checker.py`'s
+beta channel reads exactly that flag); the latter builds the sdist/wheel from the same tag and
+publishes them to PyPI. Nothing else anywhere needs editing or committing first. Between tags,
+`__version__` is a `setuptools_scm`-synthesized dev version (`<next-version>.dev<n>+g<sha>`, e.g.
+`4.0.1.dev3+gabc1234`) — see `update_checker.py`'s module docstring for exactly how that's compared
+against real release tags.
+
+A checkout needs its full tag history for this to resolve correctly — a shallow clone (or a tarball
+with no `.git/` at all) falls back to `[tool.setuptools_scm]`'s `fallback_version`, a placeholder
+that's never a real shipped version. `.github/workflows/tests.yml` and `build.yml` both pass
+`fetch-depth: 0` to `actions/checkout` for exactly this reason; do the same in any new workflow that
+installs this package. `scripts/build_dmg.sh` and `scripts/build_mcpb.sh` both read the resolved
+version back via `importlib.metadata.version("privacyfence")`, so they require the package to
+already be `pip install -e .`d (both scripts' own prerequisites say so) — same as
+`PrivacyFenceApp.spec`'s `VERSION` and `src/privacyfence/__init__.py`'s `__version__` itself.
+
+`mcpb/shim/package.json`'s `version` field is **not** tied to any of this — leave it as
+`0.0.0-dev`. The shim carries no protocol version of its own to keep in sync with the daemon's (it
+has no tool-schema knowledge at all — see `mcpb/shim/src/index.ts`'s module docstring), so unlike
+the original bridge it replaced (retired at P5, see `docs/https-connector-refactor-plan.md`),
+there's nothing here for the real version to be injected into at build time. `scripts/
+build_mcpb.sh` reads the real version only to stamp the `.mcpb` manifest itself
+(`mcpb/manifest.json.tmpl`'s `__VERSION__`), not anything inside the bundled `shim.js`.
+
+### Publishing to PyPI
+
+`publish-pypi.yml` builds the sdist/wheel and publishes to **TestPyPI first, then PyPI**, gated in
+that order (`publish-pypi` job's `needs: publish-testpypi`) — a broken publish never reaches the
+real index. It authenticates with neither project via a stored API token: both use PyPI's OIDC
+**Trusted Publisher** mechanism (`pypa/gh-action-pypi-publish`, `permissions: id-token: write`),
+so GitHub mints a short-lived token for the job and PyPI/TestPyPI trade it for a one-shot upload
+credential themselves. There is no long-lived secret in this repo for either index.
+
+Before the workflow can publish for the first time, register it as a Trusted Publisher on **both**
+services — the project need not already exist there; both accept a "pending" publisher for a name
+that isn't claimed yet, and claim it on the first successful publish. Do this once per service:
+
+1. Sign in and go to `test.pypi.org/manage/account/publishing/` (repeat later, separately, on
+   `pypi.org/manage/account/publishing/` — the two are unrelated accounts/registrations even if you
+   use the same login for both).
+2. Add a pending publisher with:
+   - **PyPI Project Name**: `privacyfence`
+   - **Owner**: `andras-tkcs`
+   - **Repository name**: `privacyfence`
+   - **Workflow name**: `publish-pypi.yml`
+   - **Environment name**: `testpypi` (on TestPyPI) / `pypi` (on PyPI) — matches the `environment:`
+     each job in `publish-pypi.yml` declares. Scoping the publisher to an environment means the
+     minted OIDC token is only ever valid for that job, not any other job in this repo.
+
+Optionally, also create matching GitHub Environments (repo **Settings → Environments**) named
+`testpypi` and `pypi`. This isn't required for the OIDC exchange itself, but it's where you'd add a
+**required reviewer** on the `pypi` environment if you want a manual go/no-go checkpoint between the
+TestPyPI publish succeeding and the real PyPI publish running — the "test first" step the workflow
+already enforces via job ordering, made into an explicit approval gate rather than just a rerun-only
+safety net.
+
+`workflow_dispatch` exists for rerunning by hand (e.g. after a transient failure) — point it at a
+tagged commit. Run from an untagged commit and `setuptools_scm` produces a dev version with a local
+segment (`+g<sha>`), which both indexes reject as an upload.
+
+## Branching & PRs
+
+- Branch names are `<type>/<kebab-case-description>`. Standard types: `feature/` for new
+  functionality, `fix/` for bug fixes, `chore/` for non-functional maintenance, `tests/` for
+  test-only changes. Use `feature/`, not `feat/` — a few early branches used `feat/` before this
+  was settled; that prefix is retired, don't reintroduce it on new branches.
+- `main` is protected — all changes land via PR (`CONTRIBUTING.md`). PRs merge with a real merge
+  commit (`Merge pull request #N from <fork>/<branch>`), not squash — keep that in mind when writing
+  commit messages on a feature branch, since they survive into `main`'s history individually.
+- Definition of done for a PR is the checklist in
+  [`docs/coding-and-testing-guidelines.md` §2.7](docs/coding-and-testing-guidelines.md#27-definition-of-done-for-a-pr-touching-this-repo).
+
+## Parallel sessions & worktrees
+
+The user regularly runs multiple Claude Code sessions on this repo at once, each on a different
+task/branch. To avoid one session's checkout state (branch switches, uncommitted edits) interfering
+with another's:
+
+- Start new work in its own `git worktree` under `~/Coding/worktrees/`, not by switching branches
+  in whichever checkout happens to be open. Naming convention already in use:
+  `~/Coding/worktrees/privacyfence-<short-branch-slug>` (e.g. `privacyfence-fix-tasks-ssl`).
+- Don't reuse an existing worktree for an unrelated task — one worktree per active branch/task.

privacyfence-4.0.0a11/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to PrivacyFence
+
+## Forking
+
+You're welcome to fork PrivacyFence and build on it. If you publish a fork or
+derivative project, a brief note to the author (privacyfence@tkcs.name or
+open a GitHub issue) is appreciated — not required, just courteous. See `NOTICE`
+for details.
+
+## Pull Requests
+
+All changes to `main` go through pull requests. Direct pushes are blocked.
+
+1. Fork the repo and create a feature branch off `main`.
+2. Keep PRs focused — one logical change per PR.
+3. Describe *why* the change is needed, not just what it does.
+4. PRs require review and approval from the maintainer before merging.
+5. Before opening a PR, work through the checklist in
+   [`docs/coding-and-testing-guidelines.md` §2.7](docs/coding-and-testing-guidelines.md#27-definition-of-done-for-a-pr-touching-this-repo)
+   — it covers required test coverage and when a local QA check needs to be run and pasted into the
+   PR description. See [`docs/testing-policy.md`](docs/testing-policy.md) for which checks run in CI
+   versus which ones you run locally.
+
+## Issues
+
+Use GitHub Issues for bug reports and feature requests. Include:
+- macOS version and Python version
+- Steps to reproduce (for bugs)
+- What connector is involved, if relevant
+
+## Code Style
+
+- `src/privacyfence/` (the daemon): Python 3.11+, standard library preferred over new dependencies
+- `mcpb/shim/` (the `.mcpb`'s stdio-to-Streamable-HTTP transport proxy, D11 in
+  [`docs/https-connector-refactor-plan.md`](docs/https-connector-refactor-plan.md) — the sole way Claude
+  Desktop reaches the daemon since P5 retired the original MCP bridge): TypeScript/Node, kept as a
+  separate language from the daemon so the `.mcpb` extension ships without a bundled Python runtime;
+  carries no tool-schema knowledge, so it stays small on purpose — see its own `src/index.ts` module
+  docstring before adding anything to it
+- No comments unless the *why* is non-obvious
+- Match the surrounding code's style
+
+See [`docs/coding-and-testing-guidelines.md`](docs/coding-and-testing-guidelines.md) for the full,
+codebase-derived conventions this project follows — coding patterns, the gate's security
+invariants, and how to structure and write tests for `src/privacyfence/`.
+
+## License
+
+By submitting a pull request you agree that your contribution is licensed under
+the Apache License 2.0, the same license as this project.