Repository navigation

Rename repograph to zerograph and migrate existing installs - #177

Merged

devmaxxx merged 9 commits into

mainfrom

refactor/rename-to-zerograph

Oct 14, 2026

Merged

Rename repograph to zerograph and migrate existing installs#177
devmaxxx merged 9 commits into
mainfrom
refactor/rename-to-zerograph

devmaxxx commented Oct 14, 2026 •

edited

Loading

Owner

Summary

Renames the crate, binary, npm packages, CLI text and docs from repograph to zerograph, and migrates what an existing install left behind. Stacked on #176 (both touch src/store.rs); retarget to main once it merges.

Migration

Store: .repograph/ is read in place until the first write, which renames it to .zerograph/ (one rename, nothing copied or deleted). A symlink at either name is refused. If both exist, .zerograph/ is the store and .repograph/ is left alone. A rename lost to another process uses the winner's directory.
Project file: zerograph.toml, else repograph.toml; messages name the file actually read, and zerograph model rewrites that file.
Machine config: ~/.config/zerograph/, else the old directory; both trust lists are read, new trusts go to the new one. A notice names an old config a new one shadows.
Model cache: the old ~/.cache/repograph/<leaf> is reused in place, so nothing is downloaded again.
Environment: ZEROGRAPH_* wins when set; otherwise REPOGRAPH_* is read, and errors name the variable read.
install-agent: replaces the old stanza, hook entries, git-hook block and repograph MCP entry rather than adding a second copy; the old MCP entry goes only after the new one is registered.
npm: the launcher keeps a repograph bin alias.

Upgrade caveat: stop any old repograph serve, watch or MCP session and replace every old binary before the first write — an old process would recreate .repograph/ after the move. docs/install.md says so.

Repository URLs still point at github.com/devmaxxx/repograph until the GitHub repo is renamed after merge.

Test plan

cargo test — 1567 passed, 0 failed
cargo clippy --all-targets -- -D warnings
node --test agent/hook.test.mjs, bench/probe Python tests, bash -n on changed scripts
New tests: store read in place, move on first write, both present, symlink at either name, racing writers, end-to-end tests/rename.rs; config, trust, cache and env fallbacks; install-agent replacing old blocks, idempotent second run
Windows CI: the in-place fallback when the rename is refused

Base automatically changed from fix/untrusted-store to main

October 14, 2026 09:43

devmaxxx added this to the 0.6.0 milestone

devmaxxx added 9 commits

October 14, 2026 11:46


          refactor!: rename the crate, binary and every user-facing name to zer…

93cd2ab

…ograph

The crate, the binary, the npm packages, the store directory, the
project config file, the machine config and cache paths, the
environment variables, the install-agent hook, marker blocks and MCP
server, and every message, help text and current doc now say
zerograph.

The launcher package keeps `repograph` as a second bin pointing at the
same script, so a script written against the old name still runs, and
CI checks both names report the same version. Links to the GitHub
repository keep its current URL until the repository itself is
renamed. Historical records (bench results, plans, ADRs, history) keep
the name they were written under.

BREAKING CHANGE: the binary is `zerograph`, the store is `.zerograph/`,
the config file is `zerograph.toml` and the environment variables are
`ZEROGRAPH_*`. Readers of the old names follow in the next commits.


          feat(env): read every REPOGRAPH_ variable while its ZEROGRAPH_ name i…

52197a6

…s unset

One helper, `env`/`env_os`, reads `ZEROGRAPH_<name>` and falls back to
`REPOGRAPH_<name>`, and every environment switch in the binary and the
agent hook goes through it, so a shell profile, CI file or bench script
written before the rename keeps working. The new name wins as soon as
it is set at all, even to an empty value.

Tests clear both names wherever they cleared one, so a developer's
shell that still exports the old names cannot leak into them.


          feat(store): read a .repograph store in place and move it on the firs…

66e0c36

…t write

A repository built before the rename keeps its store under
`.repograph/`. Rebuilding it, and re-embedding it, is the cost an
upgrade must not charge, so:

- Readers resolve the directory on every call: `.zerograph` when
  anything stands there, else `.repograph` when it exists, else
  `.zerograph`. A read that misses in `.repograph` because a writer
  moved it meanwhile is retried once under the new name.
- `ensure_dir`, and so every write and the writer lock, moves
  `.repograph` to `.zerograph` with one rename in the same parent:
  never a copy, never a delete. A rename that loses to another
  process uses the `.zerograph` that process left; one Windows refuses
  because a file inside is open writes in place and is retried later.
- Both names are refused when either is a symlink, before and after
  the move; the O_NOFOLLOW opens are unchanged.
- With both present, `.zerograph` is the store and `.repograph` is
  never written, moved over or removed.

The serve socket, the background log and `dump`'s metadata follow the
resolved directory, `serve` settles the store before it binds, and
`changes`, the default skip globs and the agent hook all know both
names.


          feat(config): read repograph.toml, the old machine config and model c…

1b50389

…ache

- The project file is `zerograph.toml`, else a `repograph.toml` from
  before the rename. With both present the new one is read alone and a
  notice says the old one is not. `zerograph model` rewrites whichever
  file is read, so a switch never starts a second file that would leave
  the reader's settings unread. Reports and the serve config stamp name
  and watch that same file.
- The machine file is `~/.config/zerograph/config.toml` (or under
  `$XDG_CONFIG_HOME`), else the `repograph` one while no new file
  exists. Trusted models are read from both lists and new trusts are
  written to the new directory only.
- Each model cache under `~/.cache/zerograph` is used when it exists or
  when there is no `~/.cache/repograph` counterpart; otherwise the old
  one is used in place, so the rename costs no gigabyte download.


          feat(install-agent): replace what an install from before the rename left

ad972ac

Re-running `install-agent` after the rename upgrades an install made
under the old name instead of adding a second one beside it:

- The instructions stanza between `<!-- repograph:begin -->` markers is
  replaced in place; with both stanzas present the old one is removed.
- Settings entries running `repograph-hook` are dropped with the
  current one's, and the old `.claude/hooks/repograph-hook.mjs` is
  removed once the settings name the new script. A file under that
  name without the hook's debug tag, or a link, is left and named.
  Codex's copy stays: `~/.codex/hooks.json` may still run it, so the
  install says to repoint that file first.
- An MCP server registered as `repograph` is removed so every tool does
  not answer twice; when removal fails the command to run is printed.
- Git hook blocks between `# repograph:begin` markers are replaced like
  the current block, so a hook never refreshes twice.


          docs: say what an upgrade from repograph reads, moves and replaces

0c7e1a3

docs/install.md gains "Coming from repograph": the package swap and the
`repograph` command the launcher keeps, the store that moves on its
first write, the project, machine and cache fallbacks, the environment
fallback, and what re-running `install-agent` replaces. The README,
the configuration page and the npm README point at it.


          chore(bench): run the renamed binary and keep a moved store out of th…

e18b9b7

…e way

- `run-repograph.sh` and the overlay build run `target/release/zerograph`,
  and the history fixture check accepts a store under either name.
- `reset.sh` removes a `.zerograph` a renamed binary's write left in the
  test worktree before restoring the fixture's `.repograph`, which that
  directory would otherwise outrank.
- `embed.sh` removes the vectors from the store the binary will read,
  and names it when it refuses.
- The agent run keeps both store names through `git clean`, and the
  compare truth search skips both.

The fixture stays a `.repograph` store and is only read, and every
`REPOGRAPH_*` the kit exports still reaches the renamed binary.


          test(rename): describe only the store the end-to-end test moves

The project-file fallback is covered by the config unit tests, not by
this one.


          fix(rename): close the gaps the review found in the migration

e889a8d

- Messages name the project file, store directory and environment
  variable actually read, not the new name when the old one was used.
- The walker drops a root-level store under either name, so a project
  skip list that names only .repograph cannot index the moved store.
- install-agent registers zerograph before it removes the old MCP entry
  (local scope only), turns a symlinked instructions file or an
  unremovable old hook into a note instead of an abort, updates the
  stanza where an old one already sits, and leaves a file holding both
  stanzas at a fixed point.
- A notice names the old machine config once a new one shadows it.
- hook.mjs reads the store with the binary's precedence.
- Bench: reset.sh restores from whichever store the fixture holds, the
  embedder guard and the no-interception arm honour the new variable
  names, and asks are counted under both names.
- docs/install.md tells an upgrader to stop old serve, watch and MCP
  sessions and replace every old binary before the first write.

devmaxxx force-pushed the refactor/rename-to-zerograph branch from 6f8a6bc to e889a8d Compare

October 14, 2026 09:47

devmaxxx merged commit e9abd3f into main

4 checks passed

devmaxxx added a commit that referenced this pull request


          Rename repograph to zerograph and migrate existing installs (#177)

99fef8a

* refactor!: rename the crate, binary and every user-facing name to zerograph

The crate, the binary, the npm packages, the store directory, the
project config file, the machine config and cache paths, the
environment variables, the install-agent hook, marker blocks and MCP
server, and every message, help text and current doc now say
zerograph.

The launcher package keeps `repograph` as a second bin pointing at the
same script, so a script written against the old name still runs, and
CI checks both names report the same version. Links to the GitHub
repository keep its current URL until the repository itself is
renamed. Historical records (bench results, plans, ADRs, history) keep
the name they were written under.

BREAKING CHANGE: the binary is `zerograph`, the store is `.zerograph/`,
the config file is `zerograph.toml` and the environment variables are
`ZEROGRAPH_*`. Readers of the old names follow in the next commits.

* feat(env): read every REPOGRAPH_ variable while its ZEROGRAPH_ name is unset

One helper, `env`/`env_os`, reads `ZEROGRAPH_<name>` and falls back to
`REPOGRAPH_<name>`, and every environment switch in the binary and the
agent hook goes through it, so a shell profile, CI file or bench script
written before the rename keeps working. The new name wins as soon as
it is set at all, even to an empty value.

Tests clear both names wherever they cleared one, so a developer's
shell that still exports the old names cannot leak into them.

* feat(store): read a .repograph store in place and move it on the first write

A repository built before the rename keeps its store under
`.repograph/`. Rebuilding it, and re-embedding it, is the cost an
upgrade must not charge, so:

- Readers resolve the directory on every call: `.zerograph` when
  anything stands there, else `.repograph` when it exists, else
  `.zerograph`. A read that misses in `.repograph` because a writer
  moved it meanwhile is retried once under the new name.
- `ensure_dir`, and so every write and the writer lock, moves
  `.repograph` to `.zerograph` with one rename in the same parent:
  never a copy, never a delete. A rename that loses to another
  process uses the `.zerograph` that process left; one Windows refuses
  because a file inside is open writes in place and is retried later.
- Both names are refused when either is a symlink, before and after
  the move; the O_NOFOLLOW opens are unchanged.
- With both present, `.zerograph` is the store and `.repograph` is
  never written, moved over or removed.

The serve socket, the background log and `dump`'s metadata follow the
resolved directory, `serve` settles the store before it binds, and
`changes`, the default skip globs and the agent hook all know both
names.

* feat(config): read repograph.toml, the old machine config and model cache

- The project file is `zerograph.toml`, else a `repograph.toml` from
  before the rename. With both present the new one is read alone and a
  notice says the old one is not. `zerograph model` rewrites whichever
  file is read, so a switch never starts a second file that would leave
  the reader's settings unread. Reports and the serve config stamp name
  and watch that same file.
- The machine file is `~/.config/zerograph/config.toml` (or under
  `$XDG_CONFIG_HOME`), else the `repograph` one while no new file
  exists. Trusted models are read from both lists and new trusts are
  written to the new directory only.
- Each model cache under `~/.cache/zerograph` is used when it exists or
  when there is no `~/.cache/repograph` counterpart; otherwise the old
  one is used in place, so the rename costs no gigabyte download.

* feat(install-agent): replace what an install from before the rename left

Re-running `install-agent` after the rename upgrades an install made
under the old name instead of adding a second one beside it:

- The instructions stanza between `<!-- repograph:begin -->` markers is
  replaced in place; with both stanzas present the old one is removed.
- Settings entries running `repograph-hook` are dropped with the
  current one's, and the old `.claude/hooks/repograph-hook.mjs` is
  removed once the settings name the new script. A file under that
  name without the hook's debug tag, or a link, is left and named.
  Codex's copy stays: `~/.codex/hooks.json` may still run it, so the
  install says to repoint that file first.
- An MCP server registered as `repograph` is removed so every tool does
  not answer twice; when removal fails the command to run is printed.
- Git hook blocks between `# repograph:begin` markers are replaced like
  the current block, so a hook never refreshes twice.

* docs: say what an upgrade from repograph reads, moves and replaces

docs/install.md gains "Coming from repograph": the package swap and the
`repograph` command the launcher keeps, the store that moves on its
first write, the project, machine and cache fallbacks, the environment
fallback, and what re-running `install-agent` replaces. The README,
the configuration page and the npm README point at it.

* chore(bench): run the renamed binary and keep a moved store out of the way

- `run-repograph.sh` and the overlay build run `target/release/zerograph`,
  and the history fixture check accepts a store under either name.
- `reset.sh` removes a `.zerograph` a renamed binary's write left in the
  test worktree before restoring the fixture's `.repograph`, which that
  directory would otherwise outrank.
- `embed.sh` removes the vectors from the store the binary will read,
  and names it when it refuses.
- The agent run keeps both store names through `git clean`, and the
  compare truth search skips both.

The fixture stays a `.repograph` store and is only read, and every
`REPOGRAPH_*` the kit exports still reaches the renamed binary.

* test(rename): describe only the store the end-to-end test moves

The project-file fallback is covered by the config unit tests, not by
this one.

* fix(rename): close the gaps the review found in the migration

- Messages name the project file, store directory and environment
  variable actually read, not the new name when the old one was used.
- The walker drops a root-level store under either name, so a project
  skip list that names only .repograph cannot index the moved store.
- install-agent registers zerograph before it removes the old MCP entry
  (local scope only), turns a symlinked instructions file or an
  unremovable old hook into a note instead of an abort, updates the
  stanza where an old one already sits, and leaves a file holding both
  stanzas at a fixed point.
- A notice names the old machine config once a new one shadows it.
- hook.mjs reads the store with the binary's precedence.
- Bench: reset.sh restores from whichever store the fixture holds, the
  embedder guard and the no-interception arm honour the new variable
  names, and asks are counted under both names.
- docs/install.md tells an upgrader to stop old serve, watch and MCP
  sessions and replace every old binary before the first write.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet