Never-delete guarantee
The server (and the CLI) can’t irreparably delete anything in ~/.local-review. Writes are atomic and never
clobber another file, none of your files is ever unlinked or truncated, and projects/ is snapshotted hourly whenever it changes.
A test fails the build if any code gains a way around that.
The guarantees
Section titled “The guarantees”- Every write is atomic. A new temp file in the same directory (opened with
wx, so never over an existing file), then renamed over the target. A failed write leaves the old file as it was, and removes only its own temp file.local-review initonly creates: its rename is a no-clobber one (below), so it never replaces aproject.yaml. - Writes are operations, not files. They’re applied to a fresh read of the file, never a whole file from the browser, so a concurrent edit by an agent is kept (how). A file that isn’t valid YAML is never overwritten (HTTP 409; fix it by hand).
- No file’s contents are ever unlinked or truncated. A superseded file (after a
rebase re-match) is renamed to
*.superseded-by-<sha8>.yaml.bak, and a rename never replaces an existing file: it’s a hard link (which fails if the name is taken) followed by dropping the old name, or, on file systems without hard links, an existence check under the per-file lock. - Images are created once. An image in a project’s
assets/folder is named by its content and written create-only, so it’s never replaced, and nothing removes one. Adding the same image again is a no-op; a file under the same name with different bytes (changed by hand) is left alone and reported. - The example projects are created, never cleared. Adding them only creates files and four new git repos under
examples/(a folder left incomplete by an interrupted attempt is left alone, and the repos go to the next free name; one that another process is still building, saylocal-review exampleswhile the UI’s Add runs, is waited for and shared). “Remove examples” renames each example’sproject.yamlto a.bak(no-clobber), so it drops out of the list with all its files still there; adding them again renames it back. - Moving review data copies, then renames.
local-review movewrites each file into the other project create-only (and moves nothing if any is already there), and only then renames the original to<sha>.moved-to-<project>.yaml.bak. It takes a snapshot first (unless nothing changed since the newest one, or snapshots are off). - The service doesn’t touch your data.
local-review service installwrites its own file outside~/.local-review(a LaunchAgent in~/Library/LaunchAgents, or a systemd user unit in~/.config/systemd/user, or under$XDG_CONFIG_HOME) and only createslogs/in the data home.local-review service uninstallremoves that one file, after checking its name and directory, and nothing in~/.local-review, not even the logs. - The service’s log is rotated, and that’s the only log anything removes.
logs/service.logis what launchd or systemd appends Local Review’s output to, not your data. Past 8 MB, Local Review copies it toservice.log.1and truncates it in place (the service manager holds it open), shifting older copies down toservice.log.3; the oldest copy goes. cache/is Local Review’s own, disposable data, not yours: what git said about commits, rewritten atomically as git answers come in and never snapshotted. You can delete it any time; it’s rebuilt as needed.runtime.jsonis Local Review’s own note to itself, not yours: while it runs, its pid, port, URL and version, forlocal-review busy. It’s removed when Local Review exits, but only while it still names that process, so it can’t remove another instance’s.local-review updatewrites only its own two files in the data home:update-check.json(what npm said, written to a temporary file and renamed into place) andupdate.lock(its pid while it runs, removed when it ends, or by the nextupdateonce that pid has gone). The rest of what it changes is the global install oflocal-reviewitself, through npm. Its check that npm’s global folder is writable makes an empty directory there and removes it at once.- The only deletion of anything else in
~/.local-reviewis snapshot pruning, guarded as below.
The one thing that removes your words is you: deleting your own comment in the UI removes it from the file, as you’d expect. The previous version is in the snapshots. (An agent’s comments can’t be deleted from the UI at all.)
Snapshots
Section titled “Snapshots”When the server starts, and then every hour while it runs, it copies projects/ to backups/<timestamp>/ (with file
times preserved), but only if something changed since the newest snapshot. A snapshot is copied under a hidden
.partial-… name and renamed when complete, so every timestamped directory is a full copy. Images are hard-linked
rather than copied, since they never change (see Snapshots); pruning a
snapshot drops only its link, never the image in projects/.
It keeps the 50 most recent snapshots plus the first snapshot of each day for 30 days. Pruning only ever removes
directories directly inside backups/ whose names are snapshot timestamps (not symlinks, not anything else you put
there), and never the newest.
Restoring is copying files back by hand: see Restoring.
How it’s enforced
Section titled “How it’s enforced”All of this lives in server/safefs.ts and server/backups.ts. test/fsguard.test.ts statically scans
server/**/*.ts (and demo/lib, demo/world: the code that builds the example projects, which is allowed none of
these) and fails if any other code (or more code there) calls unlink, rm, rmdir, truncate,
writeFile, rename, copyFile/cp, or shells out to rm/mv/…. The other calls it allows are
service uninstall’s single unlink in server/service/manager.ts, and the test checks that it sits behind the check
that the file is the service’s own (local-review.server.plist or local-review-server.service, in the service
directory); and runtime.json’s write, rename and removal in server/contract/runtime-file.ts, where the test checks
that the removal is of runtime.json only, after checking its pid. update’s files in server/contract/ have theirs
too: lock.ts creates update.lock with O_EXCL and removes only it, and only once its pid is ours or gone;
update-check.ts writes a temporary file, renames it to update-check.json, and removes only that temporary file;
package-manager.ts removes only the empty directory it has just made for the writability check. rotate.ts copies,
truncates, shifts and drops only the service’s log and its numbered copies, and serve gives it only
logs/service.log. The test pins each.
Contributors: if the guard fails on your change, route the write through server/safefs.ts; don’t widen the test.