Files
poli0981andClaude Opus 5.5 acad57acf4 docs: v1.3.0 is on Firefox Add-ons too — all three stores live
Firefox Add-ons approved the first version. The owner reported it on
2026-11-21. AMO's public API shows the add-on public, version 1.3.0,
Firefox 140 or later, slug "bookmarkmagic". Both the slug URL and the
gecko-id URL the About link uses answer 200.

- README: the Firefox install row links the listing, with an AMO version
  badge beside the Chrome Web Store and Edge ones.
- docs/00: the Type line, the 1.3.0 status (live on all three stores), §9
  (gecko id, slug, listing), §10 item 21 done and item 24 done. Item 23's
  automation state was re-checked and is unchanged: firefox-add-ons still
  does not exist.
- docs/13 §8 and store/listing.*.md: the licence to pick is "GNU General
  Public License v3.0 or later". AMO offers "v3.0 only" beside it, and that
  is what the listing ended up with (GPL-3.0-only, per the API) — the docs
  only said "v3.0". Item 21 keeps it open, along with the empty support site.
- docs/15 and CLAUDE.md: Firefox Add-ons live; 1.3.0 is on all three.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 22:54:53 +07:00

17 KiB
Raw Permalink Blame History

CLAUDE.md — Build Instructions (BookmarkMagic)

A Chrome MV3 extension — and since v1.3.0 a Firefox one, and on Edge Add-ons — for offline bookmark import/export/edit. This file is the entry point; the docs/ suite is the specification. When code and docs disagree, docs win — or stop and ask.

⚠️ This is shipped software

BookmarkMagic is published on the Chrome Web Store and has real users (v1.0.0 live by 2026-08-03; v1.0.1 live, confirmed on the listing 2026-10-28; v1.1.0 live, confirmed on the listing 2026-11-06; v1.2.0 live, confirmed on the listing 2026-11-10; v1.2.1 released on GitHub 2026-11-10, never submitted on its own; v1.3.0 — Firefox and Edge, 1.2.1 included — released on GitHub and submitted to all three stores 2026-11-18, live on Edge Add-ons and the Chrome Web Store 2026-11-19 and on Firefox Add-ons by 2026-11-21). Phases 0–9 are complete; since 2026-11-18 the project is in maintenance mode — /MAINTENANCE.md is the policy (Phase 10 below). That changes the rules of the game:

  • New work must fit /MAINTENANCE.md: dependency and security updates, major platform upgrades, bug/UI/UX/accessibility/translation fixes, and features only when they are on docs/15's roadmap or genuinely needed. A feature that is not on the roadmap needs a decision-log row before code.
  • Every change now reaches installed users through a store review. It needs a semver bump, a CHANGELOG.md entry and an update submission — 13 §1b.
  • Breaking something is no longer a local cost. The 1.0.0 → 1.0.x upgrade over an existing profile (11 §5) is the one test whose failure hits every user at once.
  • Bumping LEGAL_VERSION re-shows the first-run gate to everybody. It is a deliberate, documented act (14 §2), never a side effect.
  • Read docs/15's build-progress table and decision log before planning anything; docs/00 §10 is the live open-items list.

Doc index (read 00–02 fully before writing any code)

Doc Contents
docs/00_PROJECT_OVERVIEW.md Vision, scope, non-goals, naming ⚠, manual action items
docs/01_TECH_STACK.md Pinned versions, rejected deps, npm scripts
docs/02_ARCHITECTURE.md Layout, layer rules, data model, routing, error strategy
docs/03_DATA_FLOW.md Import/export/edit pipelines, state machine
docs/04_FILE_FORMATS.md Netscape HTML / BM JSON / CSV / Markdown specs
docs/05_ALGORITHMS.md Parser walk, normalize, dedupe, diff, write queue
docs/06_UI.md Tokens, layouts per tab, component inventory, a11y (§5 is the spec behind /ACCESSIBILITY.md)
docs/07_I18N.md chrome.i18n vs runtime store split, EN/VI/JA rules
docs/08_MV3_COMPLIANCE.md Manifest, permissions (bookmarks+storage ONLY), CWS rules; Firefox §9, Edge §10
docs/09_SECURITY_PRIVACY.md Threat model T1–T8, secure-coding bans
docs/10_CODING_STANDARDS.md Size limits, tsconfig, biome.json, knip.json, conventions
docs/11_TESTING.md Coverage gates, fixtures, suites, manual QA
docs/12_CI_CD.md Ops-repo caller stubs, release automation
docs/13_RELEASE_PUBLISHING.md Store runbook + listing copy
docs/14_LEGAL_GATE.md Gate spec + legal file drafts
docs/15_ROADMAP.md Version plan, never-list, decision log

Hard rules (violations = stop and ask)

  1. Permissions are exactly ["bookmarks", "storage"].
  2. Zero runtime dependencies. New dep ⇒ ask first (docs/01 §4).
  3. No fetch/network calls, no eval, no {@html}, no innerHTML writes. The canonical gate is docs/08 §3, run as npm run guard.
  4. src/lib/core/ never imports browser APIs, Svelte, or src/lib/browser.
  5. Files ≤300 lines (hard 500); functions ≤50 (hard 80).
  6. Every string user-visible ⇒ i18n key in every shipped locale — LOCALES in src/lib/i18n/resolve-locale.ts: en, vi, ja, zh-CN, ro (en is schema; the others satisfies Dict, where Dict = Localized<typeof dict> is exported from locales/en.ts). Never as const on a locale file — docs/07 §2. Romanian plural keys carry a third form, few (docs/07 §5).
  7. TypeScript strict; no any; casts need // SAFETY: comments.
  8. Conventional Commits; npm run verify green before every commit — and npm run verify:full before anything release-bearing. verify omits three gates the tag run enforces (coverage, build, check:manifest), so a core change that drops branch coverage passes locally and fails only after the tag is pushed, when gh release create may already have run.

Build phases (each ends with npm run verify green + a commit)

Phase 0 — Scaffold

npx wxt@latest init (svelte template) → apply docs/01 versions & scripts (incl. postinstall: wxt prepare), srcDir: 'src' per docs/02 §2, docs/10 configs (tsconfig/biome/knip/vitest), directory skeleton per docs/02, tokens.css per docs/06 §1, manifest per docs/08 §1, empty locale dicts per docs/07. Also land up front, because later phases link to them from the first screens: .nvmrc, .gitignore, .github/FUNDING.yml (copy from switch-every-tab-hotkey), SECURITY.md, the four legal/ drafts from docs/14 §3, scripts/guard.mjs (docs/08 §3) and scripts/gen-icons.mjs (placeholder PNGs so the manifest loads). Exit: npm run dev loads popup+manager; verify green.

Phase 1 — Core library (pure TS + tests FIRST-CLASS)

Implement src/lib/core/ per docs/04+05: model, limits, timestamps, normalize-url, detect-format, parsers (netscape-html, bm-json, csv), serializers (all four), dedupe, diff. Commit fixtures per docs/11 §2 and the full unit suites incl. round-trip + randomized trees. Exit: coverage ≥90% on core; all fixtures parse; round-trips pass.

Phase 2 — Browser layer + Import tab

src/lib/browser/ (bookmarks wrapper, write-queue + tests, storage, download, open-manager), stores, hash routing, Manager shell + TabBar, full #import flow per docs/03 §1 (DropZone → preview → options → backup → progress → report) and popup buttons. Exit: manual: import chrome fixture on fresh profile in all 3 modes; cancel works; 10k file stays responsive.

Phase 3 — Export + Edit tabs

#export per docs/03 §2 (FolderPickTree tri-state, format cards, download). #edit per docs/03 §3 + docs/06 §3.3 (TreeView CRUD, DnD + Move-to parity, search, duplicate panel, live event sync, ARIA tree keyboard nav). Exit: QA checklist items for export/edit pass; exported HTML re-imports losslessly.

Full dictionaries (en→vi→ja), language switcher, theme toggle+persistence, #settings, #about (links, donate handles per docs/14 §5, "Third-party: None"), LegalGate per docs/14 §2 — blocks #import/#export/#edit only. Exit: language/theme QA items pass; gate blocks/persists correctly.

Phase 5 — Hardening + release prep

Security pass against docs/09 T1–T8 (incl. injection fixtures manually), performance budgets docs/11 §6, CI workflows per docs/12 §2 (explicit permissions: blocks on every caller — and note the ops repo has no browser-extension-* family), CHANGELOG, README (badges, screenshots ⚠, install, privacy summary, donate), full manual QA (docs/11 §5), wxt zip clean-install test. Also carried in from the Phase 4 review:

  • ✔ About's "Changelog" link now targets CHANGELOG.md, pinned by tests/unit/links.test.ts;
  • ✔ EditTab.svelte split (589 → 459, under the hard limit). It grew back to 481, and in v1.1.0 its state and commands moved into three stores — edit-view (181 lines), edit-commands (226), edit-session (133) — and its key handling into src/lib/edit/tree-keys.ts. As of the 1.1.0 review the component is 259 lines with a 144-line script, TreeRow.svelte 276, ImportTab.svelte 266 and the Manager's App.svelte 237: every file is under the 300 target again. Extract before adding;
  • ✔ contrast tokens fixed, and tests/unit/styles/contrast.test.ts now fails the build on any text pair under 4.5:1. Two blind spots to know about: it is token-level, so it cannot see the opacity-on-text bypass it was written to catch, and its pair list is hand-maintained. Exit: ✔ v1.0.0 submitted and published.

Phase 6 — Post-launch stabilization → v1.0.1

The first phase written for shipped software. In order, because the docs are binding and three of the code changes need the spec to say the new thing first: docs reconciliation (this suite had frozen at "in review") → user-intake machinery (.github/ISSUE_TEMPLATE, CONTRIBUTING.md, the sanitizer — docs/15 §v1.0.x's "fixture + test per report" had no intake at all) → import failure reporting and the routing deadlock → localized #edit/#export failures and bounded search expansion → cross-tab settings/legal sync → dependency bumps and CI hardening → the About store link → cut 1.0.1. Exit: ✔ v1.0.1 tagged and released 2026-08-03, live on the store (confirmed 2026-10-28).

Phase 7 — v1.1.0: toolchain, import redesign, new formats, technical UI

Two PRs. PR-A (toolchain): Node 26, TypeScript 7 beside the TS 6 API, ES2025 with Chrome ≥ 136, SonarCloud in CI, a browser-enforced zero-network CSP, gates that cannot be talked past. PR-B (product): the import pipeline redesigned — every entry a file holds read, addresses Chrome would refuse skipped up front, Chrome's Bookmarks file and Firefox JSON backups imported, root markers so restores stop nesting, a Merge that reuses folders, a Replace that plans first and refuses an unrestorable backup; the Edit tab rebuilt around a store, with Sort A→Z, drag to reorder and batched live sync; a technical redesign of every surface; local diagnostics; a cross-tab write lock; docs and legal synced (clarifications only — LEGAL_VERSION stays 1); contact aliases per purpose. Exit: ✔ v1.1.0 tagged and released 2026-10-29 (signed tag on 9040f84, checksum-verified zip). Still human-only: the docs/11 §5 manual pass on real Chrome including the 1.0.1 → 1.1.0 upgrade over an existing profile ⚠️, then the zip uploaded to the store ⚠️.

Phase 8 — v1.2.0: Simplified Chinese and Romanian

Real installs in Chinese and Romanian browsers (CWS dashboard) made two UI languages the next minor. In order: docs first (07 gains §6 "Adding a locale") → one LOCALES list and a third plural form (few), with no new language yet → zh-CN → ro → manifest _locales, store listings, the translation form, the screenshot harness → visual sweep in both languages and an adversarial review of code and translations → 1.2.0. Both ship best-effort (TODO(review-zh), TODO(review-ro)). A Traditional Chinese browser on "Automatic" gets English. Exit: ✔ v1.2.0 tagged and released 2026-11-06 (signed tag on e2f36bc, checksum-verified zip). A finding worth keeping: on this Windows machine the process-spawning script tests time out intermittently under load (main's too), so CI — whose Windows smoke job passed — was the gate. ✔ Live on the store, confirmed on the listing 2026-11-10 (5 languages). Human-only ⚠️, still open: the native review passes, and 13 §1b step 10 — the published build installed on a clean profile — which has no recorded result for any version.

Phase 9 — v1.2.1: accessibility

The owner's keyboard-only and Narrator pass over 1.2.0 found nothing; an audit of src/ then found what such a pass cannot see. In order: dependency sync after Dependabot (the biome.json $schema and docs/01 do not move with its PRs) → docs first (06 §5) → ACCESSIBILITY.md at the repository root with its intake (issue form, PR checklist, accessibility@) → the fixes: a focus ring that was drawn in the colour of the fill under it, forced-colours support, Alt+↑/↓ to reorder (through the drag's own planDrop), focus that fell to <body> in three places, 24 px targets, an About link to the statement → adversarial review → 1.2.1. Two things to carry forward. ACCESSIBILITY.md is a public promise: a UI change that makes its key table or its known-limitations list false has to change the file in the same PR (11 §5 has the check). And the statement's goal is WCAG 2.2 AA as a goal — never write "conforms" or "compliant" without an audit to cite. The review found the first draft of the statement overclaiming in nine places ("every clickable target", "nothing times out"): check each sentence of it against the source, not against the intention. A third: code moved out of a component starts counting. SonarCloud's new-code gate (80 %) failed the first push because the live-sync wiring left EditTab for a .ts module with no test. Extracting to stay under a size limit is half the job; the test is the other half. Exit: ✔ v1.2.1 tagged and released 2026-11-10 (signed tag on d61318a, checksum-verified zip). Human-only ⚠️: the 11 §5 pass with the 1.2.0 → 1.2.1 upgrade over an existing profile, a real Windows contrast theme and a screen-reader pass over Alt+↑/↓, the zip upload, and the native review of the two new strings.

Phase 10 — maintenance mode; Firefox and Edge → v1.3.0

The owner put the project into maintenance mode and asked for the last roadmap item, the other two stores. In order: Dependabot #39–#41 and the hand sync they always need → the picomatch advisory recorded (no fix exists) → a licence gate over the lockfile (check:licenses) → the policy (/MAINTENANCE.md, a feature form that asks which kind of change it is, and triage.yml, which closes requests for something new) → Qodana (qodana-js, Ultimate) beside SonarCloud → then Firefox (AMO) and Edge: the docs first, then the port, then CI, review and 1.3.0. One thing to carry forward: triage.yml runs on pull_request_target, with a write token, for pull requests from forks. It checks out the base branch and only compares event text with constants. Never add a checkout of the pull request's head, a step that runs its code, or a ${{ }} of a title or body inside a run: line to that file. Two more, from the port. There is no Firefox in CI: the fake's Firefox flavour (11 §4) is a reading of Firefox's source, not evidence, so a change to roots, separators or move indices needs a real Firefox before an AMO upload. And every change now ships in two packages: verify:full builds and checks both (build:firefox, check:manifest -- --browser firefox), and a string that names Chrome is false in one of them. Exit: ✔ v1.3.0 tagged and released 2026-11-18 (signed tag on 80c7190, three checksum-verified packages; PR #44 merged at the reviewed head). Human-only ⚠️ (00 §10 items 19–26): the 11 §5 passes — Chrome with the 1.2.0 → 1.3.0 upgrade over an existing profile, a real Firefox 140+, Edge signed in with sync on — then the Chrome Web Store upload of 1.3.0 in place of 1.2.1, the first Firefox Add-ons version and the first Edge submission by hand, the store environments if automation is wanted, and native review. The three uploads went up 2026-11-18; Edge and the Chrome Web Store approved 2026-11-19, Firefox Add-ons by 2026-11-21 — 1.3.0 is on all three stores. An Edge copy's About link is chosen by its CRX ID (links.ts), so the listing ids in 00 §9 are code, not trivia. And since 2026-11-19 a pushed v* tag is a store submission: every *_AUTOPUBLISH variable is true, and no store environment has a required reviewer yet (00 §10 item 23 has the state). Treat a tag as an upload to users' browsers, and have the owner's go for that release before pushing one.

Working style

  • Small commits per module; tests land with (or before) implementation.
  • A git worktree needs its own npm ci and npx wxt prepare. With an empty node_modules/ packages resolve upward from the parent repo and most things appear to work, but knip reports every devDependency unused and verify fails; tsconfig.json extends ./.wxt/tsconfig.json, which wxt prepare generates. Type resolution walks up too, and it does so even after a correct npm ci. A worktree under E:\bookmarkmagic\.claude\worktrees\ inherits E:\bookmarkmagic\node_modules\@types\*, so npm run check can pass locally on types the package does not declare and CI does not have. That is exactly how a missing @types/node survived a green local verify and failed CI on the first push. A green local type-check in a worktree is weaker evidence than it looks.
  • TypeScript 7 runs beside the TS 6 API. tsc is TS 7 (@typescript/native, aliased npm:typescript@~7); the typescript package is aliased to @typescript/typescript6 for svelte-check, which needs the classic API TS 7 does not have yet. npm run check runs svelte-check (TS 6, .svelte files) and then tsc (TS 7, .ts and scripts/*.mjs). Never "fix" one by removing the other.
  • Installs run with --ignore-scripts, in CI and locally when in doubt: npm ci --ignore-scripts && npx --no-install wxt prepare. The postinstall hook only runs wxt prepare; every other package's install script is untrusted code.
  • When a browser fixture contradicts the format spec: add the fixture, make the parser tolerant, note the quirk in code + docs/04 §1.2, then continue.
  • Do not invent features not in docs; park ideas as docs/15 roadmap PRs.
  • Anything marked ⚠️ is human-only — surface it in your summary, don't fake it.
  • Every phase so far has been adversarially reviewed after implementation and every review found real defects. A green test run has never once meant "done" on this project. Budget the review.