isomorphic-jj 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,205 @@
 # Changelog
 
+## 0.2.0 — 2026-09-02
+
+The first `@johnhenry/isomorphic-jj` release since 0.1.0, and the first
+scoped release to carry the audit fixes from PR #19 below — **the published
+0.1.0 tarball on npm predates #19** and does not include them.
+
+### Fixed (PR #19 — audit findings)
+
+Fixes all 8 findings from a bug-hunt audit of the storage/operation-log,
+undo/redo, revset, and Git-push layers:
+
+- **Same-process storage locking.** `Storage.appendLine()`/`write()` did
+  read-then-write with no lock, so concurrent same-process calls (e.g. a
+  user command racing `BackgroundOps`'s autosnapshot) could silently drop an
+  entry. Added a path-keyed in-process async mutex (`src/utils/mutex.js`)
+  that serializes the full critical section for both methods. Scoped to
+  same-process concurrency per the audit's guidance; cross-process locking
+  is a follow-up.
+- **`undo()` now reverts in-place content mutations.** Previously it never
+  restored `ChangeGraph`/tag mutations made in place. `describe()` now
+  snapshots the affected `ChangeGraph` node before mutating it (mirroring
+  the existing `fileSnapshot` pattern), and `undo()` restores it.
+  `operations.revert()` now also diffs/restores `tags`, not just
+  `bookmarks`.
+- **Ambiguous change-id prefixes now throw `AMBIGUOUS_ID`.** `show()`
+  previously resolved an ambiguous prefix silently to the first match; it
+  now throws `AMBIGUOUS_ID` listing all matches.
+- **`push()` surfaces categorized error codes.** Previously all per-ref
+  errors were swallowed into a bare ref name. Rejected refs now carry a
+  categorized `code` (`AUTH_FAILED`/`NETWORK_ERROR`/`NON_FAST_FORWARD`/
+  `OTHER`) and `reason` so callers can tell an auth failure apart from a
+  non-fast-forward rejection instead of guessing.
+- **Conflict-marker newline fix.** Markers could fuse content onto boundary
+  markers when content lacked a trailing newline; now forces a newline
+  separator for non-empty content.
+- **Atomic protobuf writes.** `jj-operation-store.js`, `jj-view-store.js`,
+  and `jj-tree-state.js` risked a truncated/undecodable file on a mid-write
+  crash. Now route through a shared `atomicWriteFile()` temp+rename helper
+  (`src/utils/atomic-write.js`).
+- **Weak temp-file naming fixed alongside storage locking** by adding a
+  random suffix, so two concurrent writes can't collide on the same temp
+  filename.
+- **Open-ended revset ranges** (`..b`, `a..`, `::`) failed with a
+  misleading "invalid IDs" error; they now delegate to the existing
+  `ancestors()`/`descendants()`/`all()` implementations.
+
+Closes #11–#18. See [PR #19](https://github.com/johnhenry/isomorphic-jj/pull/19).
+
+### CI (PR #20)
+
+- Dropped macOS from the test matrix — hosted macOS runners are scarce/slow
+  to schedule and this is a pure-JS library with no native code path; Linux
+  + Windows already cover realistic cross-platform risk. See
+  [PR #20](https://github.com/johnhenry/isomorphic-jj/pull/20).
+
+### Documentation overhaul: examples suite
+
+- **New `examples/` directory: 12 numbered, runnable examples** covering the
+  core loop (init/describe/new/log), stable-ID stacked changes, history
+  editing (split/squash/abandon/duplicate), branching and merging (including
+  `new({ parents })` for true merge changes), first-class conflicts, revsets,
+  bookmarks + tags (with the v0.44 `tag.track()` surface), Git interop,
+  configuration layers, undo/oplog/time travel, the `file.*` namespace, and
+  browser usage. Each example runs in a temp directory, cleans up after
+  itself, and *asserts* what it demonstrates, so the set doubles as a smoke
+  test. `npm run examples` runs the loop; `npm run example:NN` runs one.
+- **Example 08 exercises real `git.clone()`/`git.push()`/`git.fetch()` with
+  zero network**: it builds a bare fixture repo with the git CLI and serves
+  it on 127.0.0.1 through `git http-backend` (buffering request bodies so
+  CGI gets a `CONTENT_LENGTH` — isomorphic-git sends chunked bodies). Skips
+  cleanly where the git CLI is unavailable.
+- **CI**: the test workflow now runs the examples loop as a smoke step on
+  one matrix leg (ubuntu-latest / Node 22), deliberately a different leg
+  than the coverage gate.
+- Companion docs for the site (opensource.johnhenry.me) were written from
+  this repo's README/API/MIGRATION/CONFIGURATION material in the same pass;
+  behavioral quirks the examples surfaced (e.g. `file()` matching snapshots
+  rather than modifications, duration revsets needing committer timestamps,
+  `init()` after `git.clone()` re-rooting `refs/heads/main`) are documented
+  there rather than papered over.
+
+### Publishing
+
+- `@johnhenry/isomorphic-jj@0.2.0` is published from `main`. A final
+  unscoped bridge release, `isomorphic-jj@1.8.0` (same code as this
+  release), will follow so existing unscoped installs get one more version
+  pointing at the new package before the unscoped name is deprecated.
+
+## 0.1.0 — Track jj through v0.44
+
+Jujutsu shipped v0.44.0 (2026-08-05) since isomorphic-jj's last parity pass
+(v1.5.0/README, which tracked jj through v0.43). This release closes the gap
+for the parts of v0.43–v0.44 that are in scope for a headless, browser-safe
+reimplementation of jj's model — a library, not the `jj` CLI's terminal UX or
+its Rust process/Git-plumbing internals.
+
+### Added
+
+- **`tag.track({ name, remote })` / `tag.untrack({ name })`** — jj v0.44 made
+  tags remote-trackable the same way bookmarks already were, and added `jj
+  tag track`/`untrack` to manage that per-tag. `TagStore` now persists
+  tracking state (`{ remote, remoteName }` per local tag name) the same way
+  `BookmarkStore` already did for bookmarks, and `tag.list()` includes a
+  `tracking: { remote, ref }` field once a tag is tracked. The on-disk
+  `tags.json` format gained a `{ tags, tracked }` envelope; the old flat
+  `{ name: changeId }` format is still read for backward compatibility.
+- **`builtin_log()` revset function** — jj v0.44 added `builtin_log()` as an
+  alias for the revset the built-in `jj log` uses by default, so a custom
+  `revsets.log` config can extend it instead of duplicating it. isomorphic-jj's
+  `log()` has always defaulted to `all()` when no revset is given, so
+  `builtin_log()` is wired to the same set and can be composed like any other
+  revset function (`builtin_log() & mine()`).
+- **`file.search({ ..., nameOnly: true })`** — jj v0.44 changed `jj file
+  search`'s default CLI output to print every matched *line* (prefixed with
+  its file path), moving the old "just the file paths" behavior behind a new
+  `--name-only` flag. isomorphic-jj's `file.search()` already returned
+  structured per-line matches (`{ path, lineNumber, line }`) — that was
+  already the new default — so the only gap was the old, path-only shape;
+  `{ nameOnly: true }` now returns a deduplicated `string[]` of matching
+  paths, matching `--name-only`.
+
+### Changed
+
+- **`git_refs()` / `git_head()` revsets are now documented as deprecated.**
+  Upstream jj deprecated both in favor of `bookmarks()`/`tags()`/`@`, then
+  removed them outright in jj v0.43 (calling them in real jj now errors).
+  isomorphic-jj keeps them working — removing a function outright is a
+  breaking API change this pass didn't want to force on existing callers
+  unilaterally — but they're no longer listed in the revset engine's
+  "did you mean" suggestion text, and their JSDoc now calls out the upstream
+  removal and recommends `bookmarks()`/`tags()`/`@` instead. See "Not
+  changed" below for the case for a harder break in a future major version.
+
+### Testing
+
+1714 tests passing (was 1701); lint (0 errors), format:check, typecheck, and
+build all still green.
+
+### Not changed (needs a human design call)
+
+jj v0.43–v0.44 included several changes this pass deliberately left alone:
+
+- **`jj run`** (v0.43 new command, gained `--passthrough`/`--ignore-changes`/
+  `--ignore-errors`/oldest-first-ordering in v0.44) — runs an arbitrary
+  subprocess against each revision's own private working copy. isomorphic-jj
+  doesn't shell out to anything and has to keep working in browsers with no
+  process/filesystem access; "run a command" doesn't have an isomorphic
+  equivalent. Adding it would mean either a Node-only stub (inconsistent with
+  the rest of the API surface) or scope-creeping into a job-runner. Flagging
+  for a maintainer decision rather than guessing.
+- **Auto-importing remote tags/bookmarks during `git.fetch()`.** jj v0.44's
+  headline change is that `jj git fetch` now fetches tags the same way it
+  fetches bookmarks — as `<name>@<remote>`, auto-tracked by default. Wiring
+  that up properly for tags would need `git.fetch()` to actually populate
+  `TagStore`'s (and, by the same logic, `BookmarkStore`'s) remote-tracking
+  state from the fetched refs. Investigating this surfaced a **pre-existing**
+  gap: `git.fetch()` already doesn't call `bookmarks.setRemote()` for fetched
+  bookmarks today, even though `BookmarkStore.setRemote()`/`getRemote()` have
+  existed since v0.4 — remote ref sync was never wired all the way through at
+  the fetch call site. Building tag-fetch-tracking on top of that gap would
+  mean either (a) fixing the older bookmark gap too as a drive-by, our
+  papering over an inconsistency where tags "worked" and bookmarks didn't, or
+  (b) building a second, tag-only special case. Both are judgment calls
+  about a real architectural gap, not a mechanical port of one version's
+  changelog — left for a maintainer to decide. `tag.track()`/`untrack()`
+  (added this pass) at least let callers record and query tracking intent by
+  hand in the meantime.
+- **`jj git clone --tag=PATTERN` / `--fetch-tags` removal.** Real jj replaced
+  `--fetch-tags=all|none|included` with `--tag=PATTERN` in v0.44. isojj's
+  `git.clone()`/`git.fetch()` never exposed CLI-shaped `--fetch-tags` flags in
+  the first place (just a boolean `noTags`), so there's no removed flag to
+  mirror; a `PATTERN`-based tag filter for clone/fetch would be new surface
+  area tied to the fetch-tracking gap above.
+- **`jj git push --allow-conflicts`.** Real jj normally refuses to push
+  commits containing conflicts unless this flag is passed. isojj's
+  `git.push()` doesn't currently check for conflicts before pushing at all —
+  there's no existing guard to add a bypass flag for. Adding the guard itself
+  (and then the bypass) is more surface area than a one-version parity pass.
+- **CLI argument parsing "last occurrence wins" (v0.44).** Checked
+  `bin/isojj.js`'s `parseArgs()`: it already stores each `--flag` into a
+  plain object keyed by flag name, so repeating a flag already naturally
+  overwrites the earlier value with no error — this was already jj v0.44's
+  new behavior by construction. No change needed.
+- **`try(expr, fallback...)` template function, `jj workspace list` root
+  display, `diff.stat.max-bar-width`, `colors.crossed-out`, Gerrit/config-gc/
+  `/etc/jj` config-discovery changes.** These are jj's template engine and
+  terminal/config-file layers, which isomorphic-jj's CLI (a thin, generic
+  API-argument passthrough — see `bin/isojj.js`) doesn't attempt to replicate
+  1:1 for any command. Out of scope for this pass; noted here for
+  completeness of the v0.43/v0.44 diff.
+
+## 0.0.0
+
+- **Renamed: `isomorphic-jj` is now `@johnhenry/isomorphic-jj`, restarted at 0.0.0.** Same library, same API — a new address and era, not a maturity signal (1.7.0 lineage).
+
+  ```sh
+  npm install @johnhenry/isomorphic-jj
+  ```
+
+
 All notable changes to isomorphic-jj are documented here. The project tracks the
 [Jujutsu (jj)](https://github.com/jj-vcs/jj) CLI; each release notes the upstream
 jj version whose semantics it targets.
@@ -171,7 +371,9 @@ adds a batch of revset functions and commands, and cleans up the toolchain.
 - `forks()` — changes with more than one child.
 - `first_parent(x)` / `first_ancestors(x)` — first-parent navigation (jj v0.32).
 - `fork_point(x)` — youngest common ancestor of a set (jj v0.32).
-- `merge_point(x)` — youngest common descendant of a set.
+- `merge_point(x)` — youngest common descendant of a set (implemented ahead of
+  upstream; jj stabilized its own `merge_point()` in v0.44 with matching
+  semantics — "the point where multiple branches merge").
 - `exactly(x, n)` — the set, but errors unless it has exactly `n` elements (jj v0.34).
 - `present(x)` — evaluate without erroring on unknown symbols.
 - `coalesce(a, b, …)` — the first argument that resolves to a non-empty set.

package/README.md

@@ -1,11 +1,20 @@
-# isomorphic-jj
+# @johnhenry/isomorphic-jj
 
-[![npm version](https://img.shields.io/npm/v/isomorphic-jj.svg)](https://www.npmjs.com/package/isomorphic-jj)
-[![test coverage](https://img.shields.io/badge/tests-1701%20passing-brightgreen.svg)](https://github.com/johnhenry/isomorphic-jj)
-[![license](https://img.shields.io/npm/l/isomorphic-jj.svg)](LICENSE)
+> **This package has moved to `@johnhenry/isomorphic-jj`.** This is the final release under the old name.
 
 > **Jujutsu version control for JavaScript**—stable change IDs, fearless undo, and no staging area. Works in Node.js and browsers.
 
+Full documentation: [opensource.johnhenry.me/isomorphic-jj](https://opensource.johnhenry.me/isomorphic-jj/)
+
+> Previously published as `isomorphic-jj` (final release 1.8.0, deprecated in
+> favor of this package). Renamed to `@johnhenry/isomorphic-jj` and restarted
+> at 0.0.0 on import into the @johnhenry family — a new address and era, not
+> a maturity signal.
+
+[![npm version](https://img.shields.io/npm/v/%40johnhenry%2Fisomorphic-jj.svg)](https://www.npmjs.com/package/@johnhenry/isomorphic-jj)
+[![CI](https://github.com/johnhenry/isomorphic-jj/actions/workflows/test.yml/badge.svg)](https://github.com/johnhenry/isomorphic-jj/actions/workflows/test.yml)
+[![license](https://img.shields.io/npm/l/%40johnhenry%2Fisomorphic-jj.svg)](LICENSE)
+
 **What makes it different:**
 - 🎯 **Stable change IDs** that survive rebases/squashes
 - ↩️  **Complete undo** for any operation (not just commits)
@@ -14,7 +23,7 @@
 - 🌐 **True isomorphic**—same API in Node, browsers, and Web Workers
 
 ```javascript
-import { createJJ } from 'isomorphic-jj';
+import { createJJ } from '@johnhenry/isomorphic-jj';
 import git from 'isomorphic-git';
 import fs from 'fs';
 
@@ -30,6 +39,60 @@ await jj.undo();
 
 ---
 
+## Try it in 60 seconds
+
+### CLI
+
+Every method is reachable from the `isojj` CLI (`bin/isojj.js`). Run it with
+`npx`, or install it globally (`npm i -g @johnhenry/isomorphic-jj`) and call
+`isojj` directly:
+
+```bash
+npx @johnhenry/isomorphic-jj init
+echo "# hello" > README.md
+npx @johnhenry/isomorphic-jj describe -m "Initial commit"
+npx @johnhenry/isomorphic-jj new -m "Add a feature"
+npx @johnhenry/isomorphic-jj log
+```
+
+```
+Change History:
+
+  cb7b4e93fd23  Add a feature
+             You  9/2/2026, 7:20:30 AM
+
+  a2f6f5af8107  Initial commit
+             You  9/2/2026, 7:20:30 AM
+```
+
+Run `npx @johnhenry/isomorphic-jj --help` for the full command list.
+
+### Node.js
+
+```javascript
+import { createJJ } from '@johnhenry/isomorphic-jj';
+import fs from 'fs';
+
+const jj = await createJJ({ fs, dir: './my-repo' });
+await jj.init({ userName: 'You', userEmail: 'you@example.com' });
+await jj.write({ path: 'README.md', data: '# hello\n' });
+await jj.describe({ message: 'Initial commit' });
+console.log(await jj.log({ limit: 5 }));
+```
+
+### Browser
+
+```javascript
+import { createJJ } from '@johnhenry/isomorphic-jj';
+import { createBrowserFS } from '@johnhenry/isomorphic-jj/browser';
+
+const fs = createBrowserFS({ name: 'my-repo' });
+const jj = await createJJ({ fs, dir: '/repo' });
+// Same API as Node from here on — see examples/12-browser.mjs.
+```
+
+---
+
 ## Quick Start
 
 **Coming from isomorphic-git?** Read the [Migration Guide](./MIGRATION_FROM_ISOMORPHIC_GIT.md) to see how isomorphic-jj simplifies your JavaScript version control workflow.
@@ -42,6 +105,43 @@ This showcases all 17 feature categories (including v1.0 enhancements) in ~3 sec
 
 ---
 
+## Examples
+
+The [`examples/`](./examples) directory has 12 numbered, runnable, self-asserting
+scripts — each creates a repo in a temp dir, demonstrates one area, and cleans
+up after itself. Run one with `npm run example:01` (etc.), or the whole set
+(the same loop CI runs) with:
+
+```bash
+npm run examples
+```
+
+| # | What it shows |
+|---|----------------|
+| [01](./examples/01-init-commit-log.mjs) | The core loop: init → write → `describe()` → `new()` → `log()` |
+| [02](./examples/02-stacked-changes.mjs) | Stable change IDs across a 3-layer stack; `edit()`+`amend()` a bottom layer |
+| [03](./examples/03-history-editing.mjs) | `split()`, `squash({ into })`, `abandon()`/`unabandon()`, `duplicate()` |
+| [04](./examples/04-branching-and-merging.mjs) | Diverging without branches; content merge vs. true merge changes |
+| [05](./examples/05-conflicts.mjs) | First-class conflicts: dry-run preview, `conflicts.list()`/`resolve()` |
+| [06](./examples/06-revsets.mjs) | The revset query language, end to end |
+| [07](./examples/07-bookmarks-and-tags.mjs) | Bookmarks, tags, and remote tracking |
+| [08](./examples/08-git-interop.mjs) | Real `git.clone()`/`push()`/`fetch()` against a local fixture, zero network |
+| [09](./examples/09-config.mjs) | Config layers: persisted, programmatic, deep-merge, reset |
+| [10](./examples/10-undo-and-oplog.mjs) | `undo()`/`redo()`, `operations.at()` time travel, `obslog()` |
+| [11](./examples/11-file-operations.mjs) | The `file.*` namespace: historical `show()`, `annotate()`, `search()` |
+| [12](./examples/12-browser.mjs) | Browser usage (IndexedDB fs, persistence, CORS proxy) as a reference |
+
+See [`examples/README.md`](./examples/README.md) for details and conventions.
+
+Three fuller example applications live under [`example/`](./example) — each
+exercises the library from a different angle and documents the bugs it found:
+
+- [`jj-review-tool`](./example/jj-review-tool) — a code-review CLI built on stacked changes and bookmarks.
+- [`jj-storage-server`](./example/jj-storage-server) — a REST API using isomorphic-jj as a versioned document store.
+- [`jj-wiki`](./example/jj-wiki) — a collaborative wiki exercising workspaces and conflict resolution.
+
+---
+
 ## What's New in v1.0
 
 isomorphic-jj v1.0 achieves **complete JJ CLI semantic compatibility** while maintaining 100% backward compatibility:
@@ -76,6 +176,7 @@ isomorphic-jj v1.0 now implements virtually all commonly-used JJ CLI commands:
 - **`git.remote.*`** - Complete remote management (list, add, remove, rename, setUrl)
 - **`bookmark.rename()`** - Rename bookmarks
 - **`bookmark.track/untrack/forget()`** - Remote bookmark management
+- **`tag.track/untrack()`** - Remote tag management (jj v0.44)
 - **`config.*`** - Configuration management (get, set, list)
 - **`diff()`** - Show file differences between revisions
 - **`next()` / `prev()`** - Navigate between parent/child revisions
@@ -85,10 +186,10 @@ isomorphic-jj v1.0 now implements virtually all commonly-used JJ CLI commands:
 - **`operations.show/diff/restore()`** - Advanced operation log features
 - **`remote.*`** - Convenience aliases for git operations (push, fetch, add)
 
-See [JJ_CLI_PARITY.md](./JJ_CLI_PARITY.md) for complete feature comparison.
+See [ROADMAP.md](./ROADMAP.md) for the release-by-release feature comparison and what's still planned.
 
 ### Testing & Quality
-- **1701 tests** passing — ~97% statement / 91% branch coverage (v1.0–v1.7)
+- **1730 tests** passing — ~97% statement / 91% branch coverage
 - **100% backward compatible** - All existing code continues to work
 - **Zero breaking changes** - Deprecated features show warnings but still function
 
@@ -97,7 +198,7 @@ See [JJ_CLI_PARITY.md](./JJ_CLI_PARITY.md) for complete feature comparison.
 ### Installation
 
 ```bash
-npm install isomorphic-jj isomorphic-git
+npm install @johnhenry/isomorphic-jj isomorphic-git
 ```
 
 For browsers, also install:
@@ -108,7 +209,7 @@ npm install @isomorphic-git/lightning-fs
 ### Basic Workflow
 
 ```javascript
-import { createJJ } from 'isomorphic-jj';
+import { createJJ } from '@johnhenry/isomorphic-jj';
 import git from 'isomorphic-git';
 import fs from 'fs';
 import http from 'isomorphic-git/http/node';
@@ -147,8 +248,8 @@ console.log(log);
 ### Browser Usage
 
 ```javascript
-import { createJJ } from 'isomorphic-jj';
-import { createBrowserFS } from 'isomorphic-jj/browser';
+import { createJJ } from '@johnhenry/isomorphic-jj';
+import { createBrowserFS } from '@johnhenry/isomorphic-jj/browser';
 import git from 'isomorphic-git';
 import http from 'isomorphic-git/http/web';
 
@@ -494,7 +595,7 @@ await jj.undo();
 Merge drivers enable smart merging of structured files like JSON, package.json, and YAML:
 
 ```javascript
-import { jsonDriver, packageJsonDriver, yamlDriver, markdownDriver } from 'isomorphic-jj';
+import { jsonDriver, packageJsonDriver, yamlDriver, markdownDriver } from '@johnhenry/isomorphic-jj';
 
 // Register merge drivers for different file types
 jj.mergeDrivers.register({
@@ -625,7 +726,7 @@ const bookmarks = await jj.bookmark.list();
 ### Browser Support
 
 ```javascript
-import { createBrowserFS, requestPersistentStorage } from 'isomorphic-jj/browser';
+import { createBrowserFS, requestPersistentStorage } from '@johnhenry/isomorphic-jj/browser';
 
 // Request persistent storage (prevents eviction)
 const persistent = await requestPersistentStorage();
@@ -634,14 +735,14 @@ const persistent = await requestPersistentStorage();
 const fs = createBrowserFS({ backend: 'idb', name: 'my-repo' });
 
 // Check browser capabilities
-import { detectCapabilities } from 'isomorphic-jj/browser';
+import { detectCapabilities } from '@johnhenry/isomorphic-jj/browser';
 const caps = detectCapabilities();
 if (caps.indexedDB && caps.serviceWorker) {
   // Enable offline support
 }
 
 // Get storage quota
-import { getStorageQuota } from 'isomorphic-jj/browser';
+import { getStorageQuota } from '@johnhenry/isomorphic-jj/browser';
 const quota = await getStorageQuota();
 console.log(`Using ${quota.percentage}% of available storage`);
 ```
@@ -794,7 +895,7 @@ Full API documentation available in [TypeScript definitions](./src/types.d.ts).
 ### Main Interface
 
 ```typescript
-import { createJJ, type JJ, type CreateJJOptions } from 'isomorphic-jj';
+import { createJJ, type JJ, type CreateJJOptions } from '@johnhenry/isomorphic-jj';
 
 const jj: JJ = await createJJ(options: CreateJJOptions);
 ```
@@ -898,10 +999,10 @@ repo/
 
 ## Project Status
 
-**Current Version**: v1.7.0
-**Test Coverage**: 1701 tests, ~97% statements / 91% branches
-**JJ CLI parity**: tracks Jujutsu through v0.43
-**Status**: Ready for experimentation and prototyping
+**Current Version**: 0.2.0 (`@johnhenry/isomorphic-jj`; same library/API lineage as the old `isomorphic-jj`, which reached v1.7.0 before the rename — see the provenance note at the top of this file)
+**Test Coverage**: 1730 tests passing, ~97% statements / 91% branches
+**JJ CLI parity**: tracks Jujutsu through v0.44
+**Status**: Actively developed; broad JJ CLI semantic parity, used in the examples/apps in this repo and in [JJHub](#related-projects). Not yet 1.0 — API surface can still shift; pin a version and read the CHANGELOG before upgrading.
 
 **Completed:**
 - ✅ v0.1: Core JJ experience (stable IDs, undo, bookmarks, revsets)
@@ -911,6 +1012,8 @@ repo/
 - ✅ v0.5: Custom merge drivers, enhanced revsets (time-based, graph analytics), conflict resolution enhancements
 - ✅ v1.0: Full JJ CLI semantic parity, complete `file.*`/`operations.*`/`git.*` namespaces
 - ✅ v1.5: Parity refresh tracking jj through **v0.43** — new revsets (`change_id`, `commit_id`, `subject`, `author_name`/`email`, `committer*`, `signed`, `divergent`, `merges`, `forks`, `first_parent`, `first_ancestors`, `fork_point`, `merge_point`, `exactly`, `present`, `coalesce`, `remote_tags`, `ancestors(x, depth)`), working `tags()`/`remote_tags()` revsets, and new commands: `revert()`, `redo()`, `sign()`/`unsign()`, `file.search()`, `bookmark.advance()`, `tag.set()`. See [CHANGELOG.md](./CHANGELOG.md).
+- ✅ 0.1.0 (post-rename): Parity refresh tracking jj through **v0.44** — `tag.track()`/`tag.untrack()`, the `builtin_log()` revset alias, and `file.search({ nameOnly: true })`; `git_refs()`/`git_head()` documented as deprecated (jj removed both in v0.43). See [CHANGELOG.md](./CHANGELOG.md) for what was deliberately left for a maintainer call (`jj run`, fetch-time remote tag/bookmark import).
+- ✅ 0.2.0: Storage-layer audit fixes — same-process storage locking, `undo()` reverting in-place graph/tag mutations, ambiguous change-id detection, categorized `push()` error codes, a conflict-marker newline fix, atomic protobuf writes, and open-ended revset ranges (`..b`, `a..`, `::`). See [CHANGELOG.md](./CHANGELOG.md).
 
 See [ROADMAP.md](./ROADMAP.md) for detailed plans, and [CHANGELOG.md](./CHANGELOG.md) for the release history.
 
@@ -982,7 +1085,7 @@ A: Yes! Colocated repos expose normal Git commits. Git users never see JJ metada
 A: Comparable to isomorphic-git for Git operations. JJ metadata (JSON) is fast in Node, acceptable in browsers. Large histories need pagination.
 
 **Q: Does this support all JJ features?**
-A: Not yet. We're at v0.4. See [ROADMAP.md](./ROADMAP.md) for planned features.
+A: Broad semantic parity (tracks Jujutsu through v0.44), not every CLI/UX detail — it's a library, not a terminal UI. See [ROADMAP.md](./ROADMAP.md) for what's planned and what's deliberately out of scope.
 
 **Q: Can I migrate my Git repo?**
 A: Yes! `jj.git.init()` works on existing Git repositories.
@@ -994,6 +1097,16 @@ A: JJ's model genuinely improves common workflows—stable change IDs, fearless
 
 ## Related Projects
 
+### JJHub
+
+[JJHub](https://jjhub.erisera.com) is a Jujutsu-native overlay on GitHub, built
+on this library (it uses `createJJ` directly): stable change IDs and stacked
+PRs on top of your existing GitHub repos, platform-wide undo, and an MCP
+server so coding agents get the same fearless-undo, no-staging-area workflow.
+Install the CLI with `npm i -g jjhub`.
+
+### Others
+
 - [isomorphic-git](https://isomorphic-git.org/) - Pure JS Git implementation (our foundation)
 - [Jujutsu](https://jj-vcs.github.io/jj/) - The original JJ version control system
 - [simple-git](https://github.com/steveukx/git-js) - Git wrapper for Node.js
@@ -1013,5 +1126,3 @@ Built on the shoulders of:
 - [isomorphic-git](https://github.com/isomorphic-git/isomorphic-git) by William Hilton
 - [Jujutsu](https://github.com/martinvonz/jj) by Martin von Zweigbergk
 - The Git and JavaScript communities
-
-**Status**: v1.0.0 | **Tests**: 371 passing | **Ready for**: Production use

package/bin/isojj.js

@@ -24,6 +24,7 @@ const BOOLEAN_FLAGS = new Set([
   'noTags',
   'allowNew',
   'preserveSnapshot',
+  'nameOnly',
 ]);
 
 /** Coerce a raw flag-value string to a real boolean when it looks like one. */
@@ -179,7 +180,7 @@ History editing:
 Files:
   file.list [--revision <id>]   List tracked files
   file.show <path>              Show file contents
-  file.search --pattern <re>    Search file contents        (jj file search)
+  file.search --pattern <re> [--nameOnly]   Search file contents (jj file search)
   file.annotate --path <p>      Blame-style annotation
 
 Bookmarks & tags:
@@ -188,6 +189,8 @@ Bookmarks & tags:
   bookmark.list
   tag.set --name <n> --changeId <id>       Create or move a tag
   tag.list
+  tag.track --name <n> [--remote <r>]      Track a remote tag (jj v0.44)
+  tag.untrack --name <n>                   Stop tracking a remote tag
 
 Signing:
   sign [--revision <id>] [--backend ssh --key <k>]