diff --git a/CLAUDE.md b/CLAUDE.md index 70bc10d..2986d5c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,8 +5,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project status Two packages are merged to main and working: -- `@gitmarks/core` (`packages/core/`) — schemas, GitHub Contents API client with optimistic concurrency, ULID/URL helpers, pure mutation helpers, example fixtures. 59 unit tests. -- `@gitmarks/extension-chrome` (`packages/extension-chrome/`) — MV3 Chrome extension with toolbar save, two-way native-tree sync, 5-min poll, initial reconciliation. 53 unit tests + 6 Playwright e2e tests. +- `@gitmarks/core` (`packages/core/`) — schemas, GitHub Contents API client with optimistic concurrency, ULID/URL helpers (incl. opt-in tracking-param stripping), pure mutation helpers, example fixtures. 65 unit tests. +- `@gitmarks/extension-chrome` (`packages/extension-chrome/`) — MV3 Chrome extension with toolbar save, two-way native-tree sync, 5-min poll, initial reconciliation, opt-in tracking-param stripping settings flag. 97 unit tests + 4 Playwright e2e tests (2 e2e skipped pending Playwright limitation fixes — see issue history). Pending packages (in dependency order): Firefox build, web UI (read + search + tags), web UI (write + bulk ops), Safari. @@ -35,7 +35,7 @@ These are spec-level constraints; don't violate without an explicit discussion: Pure TypeScript ESM library. No browser APIs, no React. Three layers: - **Schemas** (`src/schema/`): Zod schemas for `bookmarks.json` and `tags.json`. Inferred types (`Bookmark`, `BookmarksFile`, `Tag`, `TagsFile`). -- **Primitives** (`src/url.ts`, `src/ulid.ts`): URL normalization (strip trailing slash, drop non-hashbang fragments) and ULID generation. Wrappers so call sites depend on `@gitmarks/core` not `ulid` directly. +- **Primitives** (`src/url.ts`, `src/ulid.ts`): URL normalization (strip trailing slash, drop non-hashbang fragments, optionally strip utm_*/fbclid/gclid/msclkid/mc_* tracking params via `{ stripTrackingParams: true }`) and ULID generation. Wrappers so call sites depend on `@gitmarks/core` not `ulid` directly. - **Mutations** (`src/mutate.ts`): pure functions — `addBookmark`, `updateBookmark`, `softDeleteBookmark`, `gcTombstones`. Each takes a `BookmarksFile` and `nowIso`, returns a new file. **Purity is load-bearing** — `GitHubClient.update()` replays these on conflict, so they must not close over external state. - **GitHub client** (`src/github/client.ts`): `GitHubClient` class with `read`, `readIfChanged` (ETag-conditional), `write` (create or update), `update` (read → mutate → write with 409/422 replay). DI fetch in the constructor for testability — no `msw` needed. diff --git a/README.md b/README.md index 0ed80d5..4213f99 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,8 @@ the roadmap. See `spec.md` for the full design. on the next 5-minute poll - Concurrent edits from multiple devices reconcile automatically via GitHub's file SHA + optimistic retry-replay -- 112 automated tests (unit + Playwright e2e against real Chromium) +- 162 automated tests (unit + Playwright e2e against real Chromium) +- Optional **tracking-param stripping** (utm_*, fbclid, gclid, etc.) at save time — opt-in via settings ## Packages @@ -120,10 +121,11 @@ The load-bearing invariants: - ✅ `@gitmarks/core` — schemas, GitHub client, mutations - ✅ Chrome MVP — toolbar-button save flow - ✅ Chrome native tree integration — listeners, reconcile, poll loop -- ⬜ Firefox build (`webextension-polyfill`) -- ⬜ Web UI: list / search / tag management -- ⬜ Web UI: bulk operations + trash + export -- ⬜ Safari (via `safari-web-extension-converter`) +- ✅ Tracking-param stripping (opt-in) +- ⬜ Firefox build ([#23](https://github.com/paperhurts/gitmarks/issues/23)) +- ⬜ Web UI v1: list + search + tag management ([#24](https://github.com/paperhurts/gitmarks/issues/24)) +- ⬜ Web UI v2: bulk operations + trash + export ([#25](https://github.com/paperhurts/gitmarks/issues/25)) +- ⬜ Safari ([#26](https://github.com/paperhurts/gitmarks/issues/26)) ## Files in this repo diff --git a/packages/extension-chrome/README.md b/packages/extension-chrome/README.md index 4f58cc4..8b1d12f 100644 --- a/packages/extension-chrome/README.md +++ b/packages/extension-chrome/README.md @@ -26,11 +26,15 @@ are deferred). Pin it for easy access. Read and write**. 2. Click the toolbar icon → "Set up gitmarks" → enter PAT, owner, repo, branch. -3. Click **Validate**. You should see either +3. Optionally enable **"Strip tracking parameters"** to remove `utm_*`, + `fbclid`, `gclid`, `msclkid`, and `mc_*` from saved URLs. Default off + per the spec's open-question rationale (some sites use `utm_*` for + non-tracking purposes). +4. Click **Validate**. You should see either "✓ valid PAT, repo exists, bookmarks.json found" or "✓ valid PAT, repo exists (bookmarks.json not yet created — will be on first save)". -4. Click **Save**. +5. Click **Save**. ## Manual smoke test