docs: add CHANGELOG and README, and point About's link at the real file

CHANGELOG.md follows Keep a Changelog with the semver policy docs/12 §4
defines, and carries a marker for the human step at first release (rename
[Unreleased] to [1.0.0]).

README leads with what the project is actually for and then spends its longest
section on privacy, because that is the product's reason to exist and every
claim in it is mechanically enforced: the grep gate for network calls, the
manifest assertion for permissions, zero runtime dependencies. It also keeps
docs/13's honesty corner -- favicons, import dates, CSV flattening -- rather
than only listing what works.

src/lib/links.ts now points "Changelog" at blob/main/CHANGELOG.md instead of
the /releases placeholder it used through Phase 4, and the links test asserts
the file exists, the same way it already does for the four legal documents. A
link shipped inside the product must not 404 because someone renamed the
target.

Screenshots and the store URL are marked ⚠️ in the README -- both need a human
and neither blocks the code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-07-26 14:07:34 +07:00
1 parent 106f0ad337
commit c367680838
4 files changed
+162 -9

No files matched your search

+44
View File
@@ -0,0 +1,44 @@
# Changelog
All notable changes to BookmarkMagic are documented here.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
Per `docs/12 §4`: **patch** = fixes and translations · **minor** = features, and
any change to the permission list or the store privacy tab · **major** =
breaking format or schema changes (a BM JSON version bump).
## [Unreleased]
### Added
- Import bookmark files (Netscape HTML, BookmarkMagic JSON, CSV) with a full
preview — counts, folder depth, duplicates and warnings — before anything is
written.
- Three import modes: into a new dated folder (the default), merge into
existing folders, or replace everything. Replace downloads a JSON safety
backup first and deletes nothing until that backup is proven.
- Skip bookmarks whose URL already exists in this browser.
- Export everything, or just the folders you pick, to HTML, JSON, CSV or
Markdown.
- Edit the bookmark tree: search, rename, create folders, delete, drag & drop,
a keyboard "Move to…" with full parity, and a duplicate-finder panel.
- English, Vietnamese and Japanese, switchable in Settings independently of the
browser's own language.
- Light, dark and system themes.
- A first-run legal gate covering the EULA, licence, disclaimer and privacy
policy.
### Security
- Imported URLs are never rendered as links. Opening one goes through an
`http(s)`-only allowlist, so a `javascript:` or `data:` bookmark in a crafted
file cannot be activated from the extension.
- Parsing is bounded: 25 MB per file, 100 000 nodes, 200 levels of nesting.
- No network access of any kind at runtime, enforced by a grep gate in CI.
<!-- ⚠️ Human: on the first release, rename [Unreleased] to [1.0.0] with the
release date, and add a fresh empty [Unreleased] section above it. -->
[Unreleased]: https://github.com/poli0981/bookmarkmagic/commits/main
+107
View File
@@ -0,0 +1,107 @@
# BookmarkMagic
[![License: GPL-3.0-or-later](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE)
[![CI](https://github.com/poli0981/bookmarkmagic/actions/workflows/ci.yml/badge.svg)](https://github.com/poli0981/bookmarkmagic/actions/workflows/ci.yml)
[![CodeQL](https://github.com/poli0981/bookmarkmagic/actions/workflows/codeql.yml/badge.svg)](https://github.com/poli0981/bookmarkmagic/actions/workflows/codeql.yml)
[![Runtime dependencies: 0](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen.svg)](#privacy)
Move your bookmarks between browsers the simple way: with a file. No account,
no cloud sync, 100% offline.
A Chrome (MV3) extension for importing, exporting and editing bookmarks and
folder trees. English · Tiếng Việt · 日本語.
<!-- ⚠️ Human: add screenshots here before store submission — the manager's
import preview, the export picker, and the edit tree are the three that
matter. Icons are still generated placeholders (docs/00 §10 item 3). -->
## What it does
- **Import** HTML, JSON or CSV bookmark files, with a full preview first —
counts, folders, depth, duplicates and warnings before anything is written.
- **Choose how**: into a new dated folder (the safe default), merged into your
existing folders, or replacing everything. Replace saves a JSON safety backup
first and **deletes nothing until that backup is proven**.
- **Export** everything, or just the folders you pick, to HTML (Chrome, Edge,
Brave, Firefox, Safari, Vivaldi, Opera), JSON, CSV or Markdown.
- **Edit** the tree: search, rename, drag & drop, create folders, delete, and
find duplicate links — every action reachable from the keyboard.
## Privacy
This is the whole point of the project, so it is worth being precise.
- **No network access at all.** Not analytics, not telemetry, not update pings.
There is no server. A grep gate (`npm run guard`) fails the build if anyone
adds `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource` or `sendBeacon`.
- **Exactly two permissions**: `bookmarks` and `storage`. No host permissions,
no content scripts, no background worker. A test asserts the built manifest
against that list.
- **Zero runtime dependencies.** Nothing third-party ships in the extension.
- Settings use `chrome.storage.local`, never `storage.sync`, so even your
preferences stay off any vendor cloud.
Full policy: [`legal/PRIVACY.md`](legal/PRIVACY.md).
## Honest limitations
- Favicons cannot be imported — the bookmarks API has no favicon field.
- Imported bookmarks get today's date. Chrome does not let an extension set a
bookmark's original creation date. Your **exported** files keep the real ones.
- CSV is a flattened view: empty folders and "which folder is the toolbar" are
not preserved. Use HTML or JSON for a faithful backup.
- Markdown is share-only — BookmarkMagic cannot read it back.
## Install
From the Chrome Web Store: ⚠️ *link once the listing is live.*
From source:
```bash
npm ci && npm run build
```
Then load `.output/chrome-mv3/` at `chrome://extensions` with Developer mode on.
## Development
```bash
npm run dev
```
`npm run verify` is the gate everything else answers to — lint, type-check,
knip, the grep gate and the test suite, in that order. It must be green before
every commit.
The [`docs/`](docs/) directory is the binding specification, not notes: where
code and docs disagree, the docs win. Start with [`CLAUDE.md`](CLAUDE.md), then
`docs/00`–`docs/02`.
## Contributing
Bug reports and translation fixes are welcome via
[issues](https://github.com/poli0981/bookmarkmagic/issues). A bug report about
parsing is far more useful with a sanitized sample of the file that broke.
Security issues: please follow [`SECURITY.md`](SECURITY.md) rather than opening
a public issue.
## Support development
Entirely optional — BookmarkMagic is free software either way.
[GitHub Sponsors](https://github.com/sponsors/poli0981) ·
[Ko-fi](https://ko-fi.com/skullmute) ·
[Buy Me a Coffee](https://www.buymeacoffee.com/skullmute) ·
[Patreon](https://www.patreon.com/skullmute) ·
[PayPal](https://paypal.me/DungDang212)
## Licence
[GPL-3.0-or-later](LICENSE). Also see [`legal/EULA.md`](legal/EULA.md),
[`legal/DISCLAIMER.md`](legal/DISCLAIMER.md) and
[`legal/THIRD_PARTY_NOTICES.md`](legal/THIRD_PARTY_NOTICES.md).
Not affiliated with or endorsed by Google, Chrome, or any browser vendor.
Browser names are trademarks of their respective owners.
+1 -6
View File
@@ -17,12 +17,7 @@
export const REPO_URL = 'https://github.com/poli0981/bookmarkmagic';
export const ISSUES_URL = `${REPO_URL}/issues`;
/**
* Releases, not `blob/main/CHANGELOG.md` — the changelog is authored in Phase 5
* and the file does not exist yet. A releases page renders as a valid (empty)
* page; a missing blob is a 404 shown from inside a legal-adjacent surface.
*/
export const CHANGELOG_URL = `${REPO_URL}/releases`;
export const CHANGELOG_URL = `${REPO_URL}/blob/main/CHANGELOG.md`;
export interface LabelledLink {
labelKey: string;
+10 -3
View File
@@ -70,9 +70,16 @@ describe('outbound links', () => {
]);
});
it('avoids linking a CHANGELOG.md that does not exist yet', () => {
// Phase 5 authors it; until then the releases page is the honest target.
expect(CHANGELOG_URL.endsWith('/releases')).toBe(true);
it('links a CHANGELOG.md that actually exists', () => {
// It pointed at /releases through Phase 4 because the file did not exist.
// Same check as the legal documents: a link from inside the product must
// not 404 because someone renamed or deleted the target.
expect(CHANGELOG_URL.endsWith('/blob/main/CHANGELOG.md')).toBe(true);
expect(existsSync(join(REPO_ROOT, 'CHANGELOG.md'))).toBe(true);
});
it('links a README the badges and install steps live in', () => {
expect(existsSync(join(REPO_ROOT, 'README.md'))).toBe(true);
});
});