Add --allowed-extensions and --append-only flags; make note writes atomic and serialized

[ErycM]

Three independent changes, one per commit, so each can be taken or dropped on its own.

1. feat: add --allowed-extensions CLI flag

Exposes PathFilters existing allowedExtensions config through the CLI, so users can permit non-default file types (.html, .csv, .json, ...) on read/write without recompiling. Additive to the built-in defaults; createServer is unchanged (server.ts injects a preconfigured PathFilter). Arg parsing is extracted into a unit-tested src/cli.ts.

2. fix: make note writes atomic and serialized

Complements #98 (which fixed the r+ length bug). writeFile still truncates-then-writes, so two gaps remain:

• Not crash-safe: a crash or a stalled network-backed mount (rclone/cloud) mid-write leaves a truncated/partial note.
• Not concurrency-safe: two overlapping write_note/patch_note calls to the same path interleave and lose each others changes.

Adds atomicWrite (write a temp sibling, then rename over the target) and withPathLock (per-path serialization). All in-place note writes go through atomicWrite; write_note/patch_note additionally run their read-modify-write under the lock.

3. feat: add --append-only flag to protect files from overwrite

Opt-in --append-only=<name,...>: for the listed basenames, write_note mode:overwrite is refused (clients must append/prepend). write_note defaults to overwrite, so an AI client that forgets the mode can wipe an append-heavy file (e.g. an operations log) with a stale-read overwrite. Off by default, so existing behavior is unchanged.

Tests

Adds src/cli.test.ts, src/atomic-write.test.ts, src/append-only.test.ts (13 tests). Full suite passes locally on Node 20 except src/shutdown.test.ts > "exits on SIGTERM", which is timing-sensitive and unrelated to these changes: its 500ms boot wait races handler registration on a slow host (verified a 2s boot exits code 0).

dist/ is intentionally not rebuilt in these commits — happy to rebuild it into the PR if you prefer.

[bitbonsai]

Hey @ErycM, thanks for putting these together. Atomic writes are especially aligned with the project's data-safety goals, and the two opt-in controls are worth reviewing too.

Could you split this into three PRs, one for allowed extensions, one for atomic serialized writes, and one for append-only protection? They have different safety and product trade-offs, and keeping them independent means each can be reviewed and merged without coupling the others.

Please rebase each on current main, include its focused tests, and rebuild dist/. For any website documentation changes, please keep the HTML and Markdown versions in sync.

[ErycM]

Done — split into three independent PRs, each rebased on current main (9748d7e), each with its own focused tests and a rebuilt dist/ in a separate chore: commit:

• feat: add --allowed-extensions CLI flag #173 — feat: add --allowed-extensions CLI flag
• fix: make note writes atomic and serialized #174 — fix: make note writes atomic and serialized
• feat: add --append-only flag to protect files from overwrite #175 — feat: add --append-only flag to protect files from overwrite

Three notes, repeated in the individual PR bodies:

• src/shutdown.test.ts > stdio server exits on SIGTERM fails on my machine on pristine main as well (the test allows 500 ms for boot; this box is slower than that under load), so it shows up as 1 failing test on all three branches. Nothing else fails.
• No website/ content changed anywhere in the split — only the root README.md, in feat: add --allowed-extensions CLI flag #173 and feat: add --append-only flag to protect files from overwrite #175 — so the HTML/Markdown dual-content rule does not come into play.
• feat: add --allowed-extensions CLI flag #173 and feat: add --append-only flag to protect files from overwrite #175 both add src/cli.ts, since each needs a unit-testable parser and neither should have to wait on the other. Whichever merges second needs a trivial rebase there; tell me the order you prefer and I will rebase immediately.

Closing this in favor of the three.