dbxignore 0.3.0__tar.gz

dbxignore-0.3.0/.github/workflows/commit-check.yml

@@ -0,0 +1,23 @@
+name: commit-check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: commit-check/commit-check-action@v2.6.0
+        with:
+          message: true
+          branch: true
+          job-summary: true
+          pr-comments: true

dbxignore-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,98 @@
+name: release
+
+on:
+  push:
+    tags: ['v*']
+  # Manual dispatch lets us dry-run the build without cutting a tag.
+  # The publish jobs are tag-gated, so dispatch runs exercise build
+  # + artifact upload but skip both publish destinations.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync deps
+        run: uv sync --all-extras
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Build Windows binaries
+        # pyinstaller is a build-only tool, not a runtime or dev dep — install
+        # ephemerally for this run rather than declaring it in pyproject.toml.
+        run: uv run --with pyinstaller pyinstaller pyinstaller/dbxignore.spec
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  publish-github:
+    # GitHub Release: wheel + sdist + Windows binaries. Runs on every tag push.
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/dbxignore.exe
+            dist/dbxignored.exe
+          generate_release_notes: true
+          # When `GH_RELEASE_TOKEN` is configured as a repo secret (a PAT with
+          # `contents: write` scope belonging to the repo owner), releases are
+          # authored under the owner's GitHub identity. Falls back to the
+          # default `github.token` (author: github-actions[bot]) when the
+          # secret isn't set, so the workflow never fails because of a
+          # missing secret — it just reverts to the bot-author attribution.
+          token: ${{ secrets.GH_RELEASE_TOKEN || github.token }}
+
+  publish-pypi:
+    # PyPI via Trusted Publishing (OIDC). Gated on the `pypi` GitHub
+    # environment, which requires manual approval before the upload
+    # step runs. The id-token:write permission is scoped to this job
+    # only — least privilege.
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Strip PyInstaller outputs (PyPI gets wheel + sdist only)
+        run: rm -f dist/*.exe
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

dbxignore-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync deps
+        run: uv sync --all-extras
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Unit tests (non-Windows-only)
+        run: uv run pytest -m "not windows_only and not linux_only" -v
+
+      - name: Windows-only integration tests
+        if: runner.os == 'Windows'
+        run: uv run pytest -m windows_only -v
+
+      - name: Linux-only integration tests
+        if: runner.os == 'Linux'
+        run: uv run pytest -m linux_only -v

dbxignore-0.3.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+src/dbxignore/_version.py
+.uv/
+*.dist-info/
+__editable__*.pth
+
+# Claude Code session state (ScheduleWakeup lock files, etc.)
+.claude/

dbxignore-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# Local enforcement of the rules in cchk.toml. Install once per clone:
+#   uv tool install pre-commit
+#   pre-commit install --hook-type commit-msg --hook-type pre-push
+# After that, `git commit` and `git push` run these checks automatically.
+# CI re-runs them via commit-check-action, so local install is a convenience,
+# not a merge gate — see CLAUDE.md "Git workflow".
+
+repos:
+  - repo: https://github.com/commit-check/commit-check
+    rev: v2.6.0
+    hooks:
+      - id: check-message
+        stages: [commit-msg]
+      - id: check-branch
+        stages: [pre-push]

dbxignore-0.3.0/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to dropboxignore are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] — 2026-04-24
+
+Renames the project's owned surfaces from `dropboxignore` to `dbxignore`. The `.dropboxignore` rule-file name and the `com.dropbox.ignored` marker key are Dropbox's contracts and are **not** changed.
+
+**Upgrade path (clean break):** on an existing v0.2.x install, run `dropboxignore uninstall --purge` to clear all ignore markers and remove v0.2.x local state, then `pip install dbxignore` (or download the new binaries), then `dbxignore install`. Your `.dropboxignore` rule files carry over untouched — they are not renamed and require no edits.
+
+**GitHub repo rename:** `kiloscheffer/dropboxignore` → `kiloscheffer/dbxignore`, performed out-of-tree. GitHub auto-redirects handle all existing URLs.
+
+### Added
+
+- **Published to PyPI as `dbxignore`.** First PyPI release — install with `pip install dbxignore` or `uv pip install dbxignore`.
+- **PyPI publishing via Trusted Publishing (OIDC), gated on the `pypi` GitHub environment.** Release workflow (`.github/workflows/release.yml`) split into `build`, `publish-github`, and `publish-pypi` jobs. The PyPI upload step runs only after a required maintainer approval — single human checkpoint at the one irreversible step in the pipeline. No long-lived PyPI API token is stored as a repo secret; OIDC issues a short-lived credential scoped to this workflow and job.
+
+### Changed
+
+- **PyPI distribution name: `dropboxignore` → `dbxignore`.** **Breaking** — `pip install dropboxignore` will no longer receive updates; switch to `pip install dbxignore`.
+- **Python package directory: `src/dropboxignore/` → `src/dbxignore/`.** **Breaking** — any code that imports `dropboxignore.*` must be updated to `dbxignore.*`.
+- **CLI entry points: `dropboxignore` / `dropboxignored` → `dbxignore` / `dbxignored`.** **Breaking** — shell scripts, aliases, and Task Scheduler / systemd registrations using the old names must be recreated. Run `dropboxignore uninstall` before upgrading, then `dbxignore install` after.
+- **Logger hierarchy root: `dropboxignore` → `dbxignore`.** Affects any external log filter or handler referencing the old name (e.g. `logging.getLogger("dropboxignore")`).
+- **Environment variables: `DROPBOXIGNORE_*` → `DBXIGNORE_*`.** All public env vars (`DBXIGNORE_ROOT`, `DBXIGNORE_DEBOUNCE_RULES_MS`, `DBXIGNORE_DEBOUNCE_DIRS_MS`, `DBXIGNORE_DEBOUNCE_OTHER_MS`) are renamed. **Breaking** — old names are not read.
+- **Per-user state and log directory:**
+  - Windows: `%LOCALAPPDATA%\dropboxignore\` → `%LOCALAPPDATA%\dbxignore\`
+  - Linux: `$XDG_STATE_HOME/dropboxignore/` → `$XDG_STATE_HOME/dbxignore/` (fallback `~/.local/state/dbxignore/`)
+  - **Breaking** — existing `state.json` and `daemon.log` are not migrated automatically. `dropboxignore uninstall --purge` removes v0.2.x state as part of the recommended upgrade path.
+- **systemd user unit: `dropboxignore.service` → `dbxignore.service`.** **Breaking** — the old unit name is not recognized; `dropboxignore uninstall` must be run on v0.2.x before upgrading.
+- **Windows Task Scheduler task name: `dropboxignore` → `dbxignore`.** Same clean-break requirement.
+- **PyInstaller binaries: `dropboxignore.exe` / `dropboxignored.exe` → `dbxignore.exe` / `dbxignored.exe`.** GitHub Release assets are renamed accordingly; the PyInstaller spec is now `pyinstaller/dbxignore.spec`.
+- **GitHub Release asset names** changed to `dbxignore.exe` / `dbxignored.exe` to match the renamed entry points.
+- **README** updated throughout: install examples, CLI examples, env-var reference table, state/log paths, systemd unit name, and GitHub repo links all reflect the new `dbxignore` name. An "Upgrading from v0.2.x" section with step-by-step instructions was added.
+- **v0.2.0-era Linux legacy state-path fallback removed.** `state._legacy_linux_path()` and its transparent read fallback from `~/AppData/Local/dropboxignore/` are gone. The v0.2.0 CHANGELOG had scheduled this for v0.4; it is brought forward to v0.3 because the clean-break upgrade path (`dropboxignore uninstall --purge` before `dbxignore install`) eliminates any remaining callers. **Breaking** — anyone who skipped `uninstall --purge` on v0.2.x and had a legacy path will not have their old state read; run `dbxignore install` and let the daemon rebuild state from scratch.
+
+## [0.2.1] — 2026-04-22
+
+Maintenance release. Release-workflow hardening and project-documentation scaffolding. **No user-facing behavior changes.** Existing `.dropboxignore` rules, CLI commands, and daemon behavior are identical to v0.2.0; upgrade is a no-op for anyone running v0.2.0 today.
+
+### Added
+
+- **`workflow_dispatch` trigger on `.github/workflows/release.yml`.** The release workflow is now manually runnable via `gh workflow run release.yml` (or the GitHub Actions UI) for dry-run validation without cutting a tag. The `Publish GitHub Release` step is gated on `startsWith(github.ref, 'refs/tags/')`, so dispatch runs build + surface artifacts in the workflow run summary but don't create a Release object. Prevents the "workflow's first real exercise is the actual release" failure mode.
+- **`GH_RELEASE_TOKEN` PAT override on the Publish step.** When the repo secret `GH_RELEASE_TOKEN` is set (fine-grained PAT with `Contents: Read and write`), releases attribute to the repo owner instead of `github-actions[bot]`. Missing secret falls back to the default `GITHUB_TOKEN` via a `||` expression — zero risk of workflow breakage if the PAT isn't configured or expires.
+- **`CHANGELOG.md`** — this file. Retrospective v0.1.0 and v0.2.0 entries plus this one, following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+- **`docs/release-notes/v<X.Y.Z>.md`** convention. Hand-crafted per-release bodies override the workflow's auto-generated PR list via `gh release edit <tag> --notes-file docs/release-notes/<tag>.md` after the workflow publishes. Each release's body is versioned alongside its tag.
+
+### Documentation
+
+- **CLAUDE.md Git workflow:** new bullet documenting a pre-flight snippet that runs `commit-check` against every commit in `origin/main..HEAD`, matching CI's behavior. Prevents the "local HEAD-only check passes, intermediate commit trips CI, amend + force-push" round-trip hit on PR #12.
+- **CLAUDE.md Release:** additional bullets for `hatch-vcs`-derived versioning (no manual `pyproject.toml` bumps), the Keep a Changelog + per-version release-notes conventions, and the pre-1.0 SemVer stance (breaking changes ride MINOR bumps with explicit `**Breaking**` callouts).
+- **`docs/superpowers/plans/2026-04-22-dropboxignore-negation-polish-followups.md`:** expanded backlog — items 9–13 covering release-workflow gaps, the PyPI + rename dependency chain, and the Node.js 20 action deprecation timeline.
+
+## [0.2.0] — 2026-04-22
+
+First cross-platform release. Adds Linux support alongside the existing Windows port, plus rule-conflict detection, cross-platform CI with Conventional Commits enforcement, and significant UX + docs hardening.
+
+### Added
+
+#### Linux support
+
+- **`user.com.dropbox.ignored` xattr backend** covering files and directories. Tested on Ubuntu 22.04 / 24.04.
+- **systemd user-unit integration** — `dropboxignore install` writes `~/.config/systemd/user/dropboxignore.service`, runs `daemon-reload` + `enable --now`. `dropboxignore uninstall` is the symmetric operation.
+- **XDG-compliant paths** — `state.json` and `daemon.log` land at `$XDG_STATE_HOME/dropboxignore/` (fallback `~/.local/state/dropboxignore/`).
+- **Dual-sink logging** — records flow to both the rotating file and `sys.stderr` so systemd-journald captures them (`journalctl --user -u dropboxignore.service`).
+- **Linux root discovery** from `~/.dropbox/info.json`.
+- Graceful handling of filesystems that reject `user.*` xattrs (tmpfs without `user_xattr`, vfat, some FUSE mounts) — `OSError(errno.ENOTSUP|EOPNOTSUPP)` is treated as WARNING + continue, not a sweep abort.
+- Linux xattr operations use `follow_symlinks=False`; symlinks cannot themselves carry `user.*` xattrs (kernel restriction), handled via existing `PermissionError` arm.
+
+#### Rule-conflict detection
+
+- `.dropboxignore` negation patterns whose target lives under a directory ignored by an earlier rule (canonical case: `build/` + `!build/keep/`) are detected at rule-load time and **dropped from the active rule set**. Dropbox's ignored-folder inheritance makes such negations inert regardless of xattr state; the tool now surfaces the mismatch rather than letting users discover the failure via sync surprise.
+- Three diagnostic surfaces: daemon-log WARNING, `dropboxignore status` "rule conflicts" section, `dropboxignore explain` `[dropped]` annotation with a pointer to the masking rule.
+- Design doc: `docs/superpowers/specs/2026-04-21-dropboxignore-negation-semantics.md`.
+
+#### Configuration & escape hatches
+
+- **`DROPBOXIGNORE_ROOT` environment variable** — pre-`info.json` override for non-stock Dropbox installs. Set to an existing absolute path → that path is the sole Dropbox root. Automatically forwarded into the generated systemd unit at `dropboxignore install` time so shell-exported values survive the service boundary.
+
+#### CI & repo hygiene
+
+- **Conventional Commits + Conventional Branch enforcement** via [`commit-check-action@v2.6.0`](https://github.com/commit-check/commit-check-action) on every PR. `cchk.toml` at repo root is the single source of truth shared by the local `pre-commit` hook (commit-msg + pre-push stages) and CI.
+- Linux test leg — `pytest -m linux_only` runs on `ubuntu-latest` alongside the existing Windows leg.
+- Linux daemon smoke test with a `"watching roots:"` log-line readiness probe (inotify's strict post-`observer.schedule()` event window).
+- Real-xattr reconcile integration test and full-daemon-loop integration test.
+
+### Changed
+
+- **`dropboxignore uninstall --purge` now matches its name.** Previously cleared only ignore markers. Now also deletes `state.json`, `daemon.log` + rotated backups, the state directory itself (if empty — user-authored content preserved via `rmdir` not `rmtree`), and on Linux the systemd drop-in directory `~/.config/systemd/user/dropboxignore.service.d/`. Dropbox's sync behavior is unaffected — only our own bookkeeping is removed. **Breaking** for any automation that relied on `state.json` surviving `--purge`.
+- **`dropboxignore explain` output format** — compact relative paths (via a formatter shared with `status`) and two-space field separators. The previous `path:line: = pattern` arrow-style form is replaced; include/negation distinction is now conveyed by the leading `!` on the raw pattern text. **Breaking** for any script that parses `explain` output.
+- **`state.default_path()` on Linux migrated to XDG.** Pre-v0.2 Linux installs wrote to `~/AppData/Local/dropboxignore/` — a Windows-shaped tree inside a Linux HOME. Existing installs are read transparently from the legacy path for one release with a WARNING; the next daemon write migrates forward. Legacy fallback to be removed in v0.4.
+- **`state.user_state_dir()`** is the single source of truth for the per-user state/log directory, used by both `state.default_path()` and `daemon._log_dir()`.
+
+### Fixed
+
+- `cli.install` catches `RuntimeError` from the install backend and exits with `2` + a clean stderr message, mirroring `cli.uninstall`'s existing behavior. Previously install-backend failures escaped as raw Python tracebacks.
+- `install/linux_systemd.py` emits POSIX paths in `ExecStart` regardless of the build platform.
+
+### Documentation
+
+- README sections: Install (Linux), Configuration (with env-var reference table), Logs (with platform breakdown), State (with legacy-fallback note), Negations and Dropbox's ignore inheritance.
+- CLAUDE.md expanded: Linux-specific gotchas, rule-cache conflict invariant, Git workflow section pointing at `cchk.toml`.
+- Design specs and implementation plans for each major v0.2 arc under `docs/superpowers/`.
+
+## [0.1.0] — 2026-04-21
+
+Initial release. Windows-only.
+
+### Added
+
+- **Hierarchical `.dropboxignore` files** — drop a `.dropboxignore` at any level of a Dropbox tree; rules apply recursively from there. Supports full gitignore syntax via `pathspec`, including negations and anchored paths.
+- **NTFS Alternate Data Stream backend** — writes the `com.dropbox.ignored` ADS that Dropbox's Windows client reads to skip sync.
+- **Dual-trigger daemon** — `watchdog` observer for real-time filesystem events + hourly safety-net sweep + initial full sweep on startup (catches offline drift).
+- **Event debouncer** — coalesces bursts of related events; per-event-kind timeouts (`RULES` 100 ms, `DIR_CREATE` 0 ms, `OTHER` 500 ms), configurable via `DROPBOXIGNORE_DEBOUNCE_{RULES,DIRS,OTHER}_MS`.
+- **Case-insensitive rule matching** — NTFS-appropriate; `node_modules/` matches a directory named `Node_Modules`.
+- **Automatic Dropbox root discovery** from `%APPDATA%\Dropbox\info.json` (Personal + Business accounts).
+- **Task Scheduler integration** — `dropboxignore install` registers a user-logon trigger via `schtasks` XML; `dropboxignore uninstall` removes it.
+- **CLI commands** — `apply` (one-shot reconcile), `status` (daemon pid, last sweep, last error), `list` (print all marked paths), `explain PATH` (show matching rules), `daemon` (run in foreground), `install` / `uninstall`.
+- **`uninstall --purge` flag** — clears every ignore marker under each discovered root. (v0.2 broadens this to also remove local state.)
+- **Rotating log file** at `%LOCALAPPDATA%\dropboxignore\daemon.log` (5 MB × 4 backups).
+- **Persisted state** at `%LOCALAPPDATA%\dropboxignore\state.json` (daemon pid, sweep stats, watched roots).
+- **`.dropboxignore` protection** — the rule file itself is never marked ignored; any stray marker on one is cleared with a WARNING.
+- **PyInstaller-built standalone binaries** — `dropboxignore.exe` + `dropboxignored.exe`, published via GitHub Releases.
+- **Windows test leg** with `pytest -m windows_only` NTFS-ADS integration tests.
+
+[0.3.0]: https://github.com/kiloscheffer/dbxignore/releases/tag/v0.3.0
+[0.2.1]: https://github.com/kiloscheffer/dropboxignore/releases/tag/v0.2.1
+[0.2.0]: https://github.com/kiloscheffer/dropboxignore/releases/tag/v0.2.0
+[0.1.0]: https://github.com/kiloscheffer/dropboxignore/pull/1

dbxignore-0.3.0/CLAUDE.md

@@ -0,0 +1,85 @@
+# dbxignore
+
+Cross-platform Python utility: keeps Dropbox ignore markers (NTFS alternate data streams on Windows; `user.com.dropbox.ignored` xattrs on Linux) in sync with hierarchical `.dropboxignore` files.
+
+## Commands
+
+- `uv sync --all-extras` — install
+- `uv run pytest` — full suite; Windows adds a few ADS-integration tests via `@pytest.mark.windows_only`
+- `uv run pytest -m "not windows_only"` — portable subset (what Ubuntu CI runs)
+- `uv run pytest -W error::DeprecationWarning` — local strict mode (not enforced in CI)
+- `uv run ruff check` — lint; rules E, F, I, B, UP, SIM; line length 100
+- `dbxignore <apply|status|list|explain|daemon|install|uninstall>` — CLI console script (`cli:main`). `install` / `uninstall` register / remove the daemon with the platform's user-scoped service manager (Task Scheduler on Windows, systemd user unit on Linux). `uninstall --purge` also clears every ignore marker.
+- `dbxignored` — daemon shim (`cli:daemon_main`), launched by the installed Scheduled Task
+
+## Architecture
+
+`reconcile.reconcile_subtree(root, subdir, cache)` is the single source of truth for rule-driven marker mutations. `cli.apply`, `daemon._dispatch`, and `daemon._sweep_once` all call it — never bypass. The lone exception is `cli.uninstall --purge`, which issues an unconditional marker clear (no rule evaluation) while still honoring the `.dropboxignore`-found-marked `WARNING` contract inline.
+
+Marker I/O is platform-dispatched via `dbxignore.markers`, which at import time re-exports `is_ignored`/`set_ignored`/`clear_ignored` from `_backends/windows_ads.py` (Windows NTFS ADS) or `_backends/linux_xattr.py` (Linux `user.com.dropbox.ignored`). No other module branches on `sys.platform` for markers. `reconcile._reconcile_path` catches `OSError(errno.ENOTSUP|EOPNOTSUPP)` from the Linux backend and treats it the same way as `PermissionError` — log WARNING, append to `Report.errors`, continue the sweep.
+
+`daemon._sweep_once` fans `reconcile_subtree` out across roots via `ThreadPoolExecutor` (one worker per root). Safe because reconcile reads the cache lock-free (single-op `.get()`s) and writes per-file ignore markers on disjoint paths. `RuleCache._rules` is guarded by a `threading.RLock` — any mutation (`load_root`, `reload_file`, `remove_file`, or the stale-purge iteration in `load_root`) must go through it, otherwise the debouncer thread can race with the main-thread sweep. If you add cross-root shared state to `RuleCache` or reconcile, revisit this.
+
+`rules.RuleCache` stores one `_LoadedRules(lines, entries, mtime_ns, size)` per `.dropboxignore`. `entries` is a list of `(source_line_index, pathspec.Pattern)` pairs and is the single source of truth for both `match()` and `explain()`.
+
+`rules._load_if_changed` skips reparse when a `.dropboxignore`'s `mtime_ns` and `size` both match the cached values — that's why `_LoadedRules` carries stat fields. The sweep path (`load_root`) uses it; watchdog-driven `reload_file` bypasses it because an explicit event is authoritative.
+
+The daemon's watchdog events are classified (`_classify` → `EventKind.{RULES,DIR_CREATE,OTHER}`) and funneled through `Debouncer` before `_dispatch` runs `reconcile_subtree`. `DEFAULT_TIMEOUTS_MS` per kind is overridable via `DBXIGNORE_DEBOUNCE_{RULES,DIRS,OTHER}_MS`.
+
+`install/` is a package with `__init__.py` exposing `install_service()` / `uninstall_service()` dispatchers, plus `windows_task.py` (schtasks XML generation + invocation) and `linux_systemd.py` (writes `~/.config/systemd/user/dbxignore.service`, runs `systemctl --user daemon-reload && enable --now`). `cli.install` / `cli.uninstall` delegate only to the package dispatcher; don't call backend modules directly from the CLI layer.
+
+## Gotchas
+
+- pathspec 1.0.4: subclass `GitIgnoreSpecPattern`, not deprecated `GitWildMatchPattern`.
+- pathspec 1.0.4: `spec.check_file(path)` returns `CheckResult(include, index, file)` — use when you need pattern-level verdicts beyond a bare bool.
+- pathspec: `pattern.match_file()` is public; `pattern.regex.match` is private API.
+- pathspec: directory-only rules (`node_modules/`) require trailing `/` on the tested path string.
+- pathspec: a line with leading whitespace before `#` (e.g. `"   # indented"`) is an *active pattern*, not a comment — `rules._build_entries` detects the count mismatch and falls back to per-line reparse.
+- `_backends/windows_ads` uses `open(r"\\?\path:com.dropbox.ignored")` directly — `\\?\` prefix mandatory for >260-char paths.
+- NTFS is case-insensitive; `_CaseInsensitiveGitIgnorePattern` prepends `(?i)` to compiled regexes.
+- `.dropboxignore` files are never marked ignored — guarded in `match()` and `explain()`; `reconcile._reconcile_path` clears any ADS marker it finds on one and logs at `WARNING` (spec contract — don't silence it in a refactor).
+- `rules.match/explain` and `markers.{is,set,clear}_ignored` all require **absolute** paths and raise `ValueError` on relative ones. Resolve at the CLI/daemon boundary, never inside the cache or markers layer — `Path.resolve()` on Windows is a per-call syscall that dominated sweep wall-clock before.
+- `daemon._configured_logging()` is a context manager: it snapshots the `dbxignore` logger on enter and restores handlers/propagate/level on exit. On Linux it installs two handlers — `RotatingFileHandler(daemon.log)` plus `StreamHandler(sys.stderr)` so systemd-journald captures the same records — on Windows only the file handler. Tests that count handlers must branch on `sys.platform`. `run()` wraps its body in it, so tests that call `daemon.run()` don't need to hand-restore logger state — but if you mock it out in a test, use `contextlib.nullcontext` (see `test_daemon_singleton.py`).
+- Use `datetime.UTC`, not `timezone.utc` (ruff UP017).
+- Test helpers (`FakeMarkers`, `fake_markers` fixture, `write_file` fixture) live in `tests/conftest.py` and are auto-available to every test module.
+- Log-contract tests use `caplog.at_level(logging.WARNING, logger="dbxignore.<module>")` — narrow to the submodule that emits the log (see `tests/test_reconcile_edges.py`).
+- Windows-only tests: set `pytestmark = pytest.mark.windows_only` at module level and guard with `if sys.platform != "win32": pytest.skip(..., allow_module_level=True)` so non-Windows collection skips cleanly.
+- Daemon/sweep tests that trigger state writes: `monkeypatch.setattr(state, "default_path", lambda: tmp_path / "state.json")` redirects the persisted state off the real per-user state dir and keeps the test hermetic. Per-user state dir is `%LOCALAPPDATA%\dbxignore\` on Windows and `$XDG_STATE_HOME/dbxignore/` (fallback `~/.local/state/dbxignore/`) on Linux; the single source of truth is `state.user_state_dir()`, used by both `state.default_path()` and `daemon._log_dir()`. The v0.2-era Linux legacy-path fallback (`~/AppData/Local/dropboxignore/state.json`) was removed in v0.3 — clean-break upgrade path via `dropboxignore uninstall --purge` means no v0.2.x state survives, so the fallback had no remaining callers.
+- Root-discovery test seams, by layer: CLI tests monkeypatch `cli._discover_roots`; daemon tests monkeypatch `daemon.roots_module.discover`; `roots.discover()` unit tests use `_stage_info(monkeypatch, tmp_path, fixture_name)` which sets `APPDATA` (Windows) or `HOME` (Linux) to point at a staged `Dropbox/info.json` / `.dropbox/info.json`. Pick the layer that matches the code path under test.
+- Linux xattrs vanish silently through common operations: `cp` without `-a`, cross-filesystem `mv`, most archivers, and `vim`'s default save-via-rename. The watchdog event stream + hourly sweep are the recovery mechanism — don't add a preservation wrapper, the design intentionally leans on reconcile.
+- Linux backends use `follow_symlinks=False` on all xattr calls (mirrors `os.walk(followlinks=False)` in reconcile). A symlink marked ignored means the link itself is marked, not its target — **except** that the Linux kernel refuses `user.*` xattrs on symlinks entirely (EPERM). `set_ignored`/`clear_ignored` raise `PermissionError` on symlinks, which reconcile's existing `PermissionError` arm already handles (log + skip). `is_ignored` on a symlink returns False (ENODATA).
+- `roots.discover()` branches on `sys.platform`: `%APPDATA%\Dropbox\info.json` on Windows, `~/.dropbox/info.json` on Linux. Same JSON schema. The `_info_json_path()` helper returns `None` on unsupported platforms (raises a WARNING log); `discover()` then returns `[]`.
+- `roots.discover()` honors `DBXIGNORE_ROOT` as a pre-`info.json` escape hatch for non-stock Dropbox installs. Set to an existing absolute path → `[Path(env)]`, bypassing `info.json` (and the platform check — useful on platforms where `_info_json_path()` returns `None`). Set to a nonexistent path → WARNING + `[]`. Empty string → treated as unset. Single-root only; multi-account setups with an override have to pick one.
+- `RuleCache` runs a static conflict detector at every mutation (`load_root`, `reload_file`, `remove_file`). Negations whose literal path prefix lives under a directory matched by an earlier include rule are recorded in `_conflicts` and their `(source, line_idx)` tuple is added to `_dropped`. `match()` and reconcile ignore anything in `_dropped`; `explain()` still returns dropped matches but sets `Match.is_dropped=True` so CLI/log formatters can annotate them. Semantic reason: Dropbox's ignored-folder inheritance makes negations inert under ignored ancestors, so we don't pretend they're in effect.
+
+## Git workflow
+
+- Never commit directly to `main`. Work on a topic branch and open a PR — that's what triggers `.github/workflows/test.yml` (the platform-gated test tiers `pytest -m windows_only` and `pytest -m linux_only` **only run in CI**) and `.github/workflows/commit-check.yml` (commit-message + branch-name validation). A local `uv run pytest` can only exercise one platform, so a single green local run is not a merge gate. The PR matrix is.
+- **`cchk.toml` at repo root is the single source of truth** for allowed commit types (Conventional Commits, see `allow_commit_types`), branch types (Conventional Branch, see `allow_branch_types`), and the subject-length cap. Don't restate those lists here or elsewhere — reference the file so it can't drift. Local enforcement is optional but encouraged: `uv tool install pre-commit && pre-commit install --hook-type commit-msg --hook-type pre-push` wires the same rules at commit/push time. CI re-runs them on every PR via `commit-check/commit-check-action@v2.6.0`.
+- **Pre-flight against every commit, not just HEAD.** CI runs `commit-check` against the full `origin/main..HEAD` range; a local check that only validates the planned PR title can pass while an intermediate commit fails CI (happened on PR #12 — one commit's description starting with `--` tripped commit-check's regex). Before pushing, loop over every commit's subject:
+  ```bash
+  git log --pretty=format:'%s%n' origin/main..HEAD | while IFS= read -r msg; do
+    [ -z "$msg" ] && continue
+    printf '%s\n' "$msg" > /tmp/m.txt
+    commit-check --message --no-banner --compact /tmp/m.txt || echo "FAIL: $msg"
+  done
+  ```
+  Local green then matches CI green on the message check.
+- Branch names follow `<type>/<slug>` where `<type>` is from `cchk.toml`'s `allow_branch_types` and `<slug>` is lowercase-alphanumeric + hyphens. Note the asymmetry with commit subjects: the branch prefix `feature/` is the long form while the Conventional Commits subject tag `feat:` is the short form. Same repo, two conventions. Examples: `feature/v0.2-linux`, `fix/v0.2-followups-2-5`, `fix/v0.2-followup-1-linux-xdg-paths`.
+- Commit subjects follow Conventional Commits: `<type>(<scope>): <description>` where `<type>` is from `cchk.toml`'s `allow_commit_types`. Scope tags mirror package names or doc categories, not ticket numbers. `!` before the colon — or a `BREAKING CHANGE:` footer — signals a breaking change.
+- Split commits along revertability lines: a code change and a doc-only backlog update belong in separate commits because they could plausibly be reverted at different times. PR #4 is the template — one `feat` commit for the behavior change, one `docs` commit for the new follow-up entries.
+- If commits land on `main` locally by mistake, create the topic branch at current `HEAD` **first**, then `git reset --hard origin/main` on `main`. The branch ref preserves the commits so the reset is non-destructive. Never run the reset before the branch is created.
+- After a PR merges, `git checkout main && git pull --ff-only && git branch -d <merged-branch>` keeps the local tree clean. The GitHub-side branch is already deleted by the merge-and-delete UI; don't push a deletion for it.
+
+## Release
+
+- `.github/workflows/test.yml` runs ruff + the portable pytest subset on `ubuntu-latest` and `windows-latest` for every push/PR. The Windows leg additionally runs `pytest -m windows_only`; the Linux leg additionally runs `pytest -m linux_only`.
+- Push tag `v*` → `.github/workflows/release.yml` builds wheel + `dbxignore.exe` / `dbxignored.exe` (via `pyinstaller/dbxignore.spec`) and publishes a GitHub Release. `hatch-vcs` derives the version from the tag — no manual `pyproject.toml` bump needed.
+- `CHANGELOG.md` at repo root follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/): new entries accrue under an `[Unreleased]` heading (add it at the top when the first post-release change lands) and roll into a version heading with its release date when the tag goes out. Hand-crafted per-version release bodies live under `docs/release-notes/v<X.Y.Z>.md` for use with `gh release edit v<X.Y.Z> --notes-file docs/release-notes/v<X.Y.Z>.md` after the workflow publishes.
+- This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-1.0, breaking changes ride MINOR bumps with explicit **Breaking** callouts in the CHANGELOG — v0.2.0 introduced two (broadened `--purge`, changed `explain` format). Post-1.0, breaking changes will bump MAJOR.
+
+## Docs
+
+- Design: `docs/superpowers/specs/2026-04-20-dropboxignore-design.md`
+- Plan: `docs/superpowers/plans/2026-04-20-dropboxignore-implementation.md`
+- v0.2 product/risk follow-ups: design doc § Open questions.

dbxignore-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kilo Scheffer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dbxignore-0.3.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: dbxignore
+Version: 0.3.0
+Summary: Hierarchical .dropboxignore for Dropbox on Windows (NTFS ADS) and Linux (xattrs)
+Author: Kilo Scheffer
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: pathspec>=0.12
+Requires-Dist: psutil>=5.9
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dbxignore
+
+Hierarchical `.dropboxignore` files for Dropbox. Drop a `.dropboxignore` into any folder under your Dropbox root and matching paths get the Dropbox ignore marker set automatically — no more `node_modules/` cluttering your sync. Windows (NTFS alternate data streams) and Linux (`user.*` xattrs) supported.
+
+## Upgrading from v0.2.x
+
+The project was renamed from `dropboxignore` to `dbxignore` in v0.3.0
+(the old name collides with an unrelated 2019 PyPI project). Upgrade is
+a one-time manual step:
+
+```bash
+dropboxignore uninstall --purge   # on v0.2.x — removes state, logs, service
+pip install dbxignore              # or: uv pip install dbxignore
+dbxignore install                  # registers the new service under new names
+```
+
+Your `.dropboxignore` rule files carry over untouched — they're never
+modified by install/uninstall.
+
+## Requirements
+
+- **Windows 10/11** (NTFS), **or** a modern Linux distro with a systemd user session
+- Dropbox desktop client installed
+- Python ≥ 3.11 with [`uv`](https://docs.astral.sh/uv/). The pre-built `.exe` (Windows only) is an alternative on Windows.
+
+## Install (Windows, from source)
+
+```powershell
+uv tool install git+https://github.com/kiloscheffer/dbxignore
+dbxignore install
+```
+
+`dbxignore install` registers a Task Scheduler entry that launches the daemon (`pythonw -m dbxignore daemon`) at every user logon.
+
+## Install (Linux)
+
+Requires a systemd user session (standard on Ubuntu, Fedora, Debian, Arch, and most modern distros; WSL2 requires `systemd=true` in `/etc/wsl.conf`).
+
+```bash
+uv tool install git+https://github.com/kiloscheffer/dbxignore
+dbxignore install                    # writes systemd user unit, enables it
+systemctl --user status dbxignore.service
+```
+
+`dbxignore install` writes `~/.config/systemd/user/dbxignore.service` and runs `systemctl --user enable --now` so the daemon starts at login.
+
+For non-stock Dropbox installs, export `DBXIGNORE_ROOT` before running `dbxignore install` — the install step will read the variable from your shell environment and write a corresponding `Environment="DBXIGNORE_ROOT=..."` line into the generated unit's `[Service]` block. Without this, a shell-exported value won't reach the daemon when systemd launches it. If your Dropbox location ever changes, re-run `dbxignore install` after updating the export.
+
+To uninstall:
+
+```bash
+dbxignore uninstall                  # disables unit, removes the file
+dbxignore uninstall --purge          # clears markers, state files, logs, systemd drop-in
+```
+
+Notes:
+- Dropbox on Linux marks ignored paths with the xattr `user.com.dropbox.ignored=1`. Files on filesystems that don't support `user.*` xattrs (tmpfs without `user_xattr`, vfat, some FUSE mounts) are skipped with a `WARNING` in the daemon log — not a fatal error.
+- Several common operations strip xattrs silently: `cp` without `-a`, `mv` across filesystems, most archivers, `vim`'s default save-via-rename. The watchdog plus hourly sweep re-apply markers automatically; no action needed.
+- Linux symlinks cannot carry `user.*` xattrs (kernel restriction). A symlink matched by a rule logs one `WARNING` per sweep and is skipped. Its target is not affected.
+
+## Install (.exe)
+
+1. Download `dbxignore.exe` and `dbxignored.exe` from the latest [Release](https://github.com/kiloscheffer/dbxignore/releases).
+2. Place both in a stable directory (e.g. `%LOCALAPPDATA%\dbxignore\bin\`) and add it to your `PATH`.
+3. Run `dbxignore install`.
+
+## Platform support
+
+- **Windows 10 / 11** — first-class (v0.1). Uses NTFS Alternate Data Streams.
+- **Linux** — first-class (v0.2). Uses `user.com.dropbox.ignored` xattrs. Tested on Ubuntu 22.04 / 24.04. Requires a systemd user session.
+- **macOS** — planned for v0.3. Dropbox on macOS uses a different attribute mechanism (Apple File Provider) that requires runtime detection — not yet implemented.
+
+## `.dropboxignore` syntax
+
+Full `.gitignore` syntax via [`pathspec`](https://github.com/cpburnz/python-pathspec). Matching is case-insensitive to accommodate NTFS. A file named `.dropboxignore` is never itself ignored — it needs to sync so your other machines see the same rules.
+
+Example (put in a project root):
+
+```
+# everything javascripty
+node_modules/
+
+# Python
+__pycache__/
+.venv/
+*.egg-info/
+
+# Rust
+target/
+
+# build output
+/dist/
+/build/
+
+# except this one specific artifact we want to share
+!dist/release-notes.pdf
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `dbxignore install` / `uninstall` | Register / remove the daemon with the platform's user-scoped service manager (Task Scheduler on Windows, systemd user unit on Linux). `uninstall --purge` also clears every existing marker, removes local dbxignore state (`state.json`, `daemon.log*`, the state directory), and on Linux removes any systemd drop-in directory. Any stray marker on a `.dropboxignore` file itself is logged at `WARNING` before being cleared. |
+| `dbxignore daemon` | Run the watcher + hourly sweep in the foreground. Usually invoked by Task Scheduler. |
+| `dbxignore apply [PATH]` | One-shot reconcile of the whole Dropbox (or a subtree). |
+| `dbxignore status` | Is the daemon running? Last sweep counts, last error. |
+| `dbxignore list [PATH]` | Print every path currently bearing the ignore marker. |
+| `dbxignore explain PATH` | Which `.dropboxignore` rule (if any) matches the path? |
+
+## Behaviour
+
+- **Source of truth.** `.dropboxignore` files declare what is ignored. Removing a rule unignores the matching paths on the next reconcile. A path marked ignored via Dropbox's right-click menu but not matching any rule will be unignored.
+- **Hybrid trigger.** The daemon reacts to filesystem events in real time *and* runs an hourly safety-net sweep. If the daemon is offline, an initial sweep at the next start catches any drift.
+- **Multi-root.** Personal and Business Dropbox roots are discovered automatically from `%APPDATA%\Dropbox\info.json` (Windows) or `~/.dropbox/info.json` (Linux).
+
+### Negations and Dropbox's ignore inheritance
+
+Dropbox marks files and folders as ignored using xattrs. When a folder carries the ignore marker, Dropbox does not sync that folder or anything inside it — children inherit the ignored state regardless of whether they individually carry the marker. This matters for gitignore-style negation rules in your `.dropboxignore`.
+
+If you write a negation whose target lives under a directory ignored by an earlier rule — the canonical case is `build/` followed by `!build/keep/` — the negation cannot take effect. Dropbox will ignore `build/keep/` because `build/` is ignored, no matter what xattr we put on the child. dbxignore detects this at the moment you save the `.dropboxignore`, logs a WARNING naming both rules, and drops the conflicted negation from the active rule set.
+
+Negations that don't conflict with an ignored ancestor work normally. For example:
+
+```
+*.log
+!important.log
+```
+
+Here nothing marks a parent directory as ignored (`*.log` matches files, not dirs), so the negation works — `important.log` gets synced, the other `.log` files don't.
+
+**Limitation.** Detection uses static analysis on the rule's literal path prefix. Negations that begin with a glob (`!**/keep/`, `!*/cache/`) have no literal anchor to analyze and are accepted without conflict-check — if they land under an ignored ancestor at runtime, they silently fail to take effect. If you need guaranteed semantics, prefer negations with a literal prefix.
+
+## Configuration
+
+Environment variables read at daemon startup:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DBXIGNORE_DEBOUNCE_RULES_MS` | `100` | Debounce window for `.dropboxignore` file events. |
+| `DBXIGNORE_DEBOUNCE_DIRS_MS` | `0` | Debounce for directory-creation events (`0` = react immediately, no coalescing). |
+| `DBXIGNORE_DEBOUNCE_OTHER_MS` | `500` | Debounce for other file events. |
+| `DBXIGNORE_LOG_LEVEL` | `INFO` | Daemon log level. |
+| `DBXIGNORE_ROOT` | *(unset)* | Escape hatch for non-stock Dropbox installs: overrides `info.json` discovery and treats the given absolute path as the sole Dropbox root. If the path doesn't exist, a WARNING is logged and no roots are returned (so `dbxignore apply` exits with "No Dropbox roots found"). |
+
+Logs (rotated, 25 MB total):
+- Windows — `%LOCALAPPDATA%\dbxignore\daemon.log`.
+- Linux — two sinks, same records. The rotating file at `$XDG_STATE_HOME/dbxignore/daemon.log` (fallback `~/.local/state/dbxignore/daemon.log`) is authoritative for offline debugging and bug-report bundling; `journalctl --user -u dbxignore.service` surfaces the same records via systemd-journald for live tailing and cross-service filtering.
+
+State:
+- Windows — `%LOCALAPPDATA%\dbxignore\state.json`.
+- Linux — `$XDG_STATE_HOME/dbxignore/state.json` (fallback `~/.local/state/dbxignore/state.json`). Installs that pre-date the XDG move are read transparently from the legacy `~/AppData/Local/dbxignore/state.json` for one release, with a WARNING; the next daemon write persists to the XDG path.
+
+## License
+
+MIT — see [LICENSE](LICENSE).