@einsia/agent-git 0.0.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Einsia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# agit
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Built with Rust](https://img.shields.io/badge/built%20with-Rust-orange?logo=rust&logoColor=white)](https://www.rust-lang.org)
+
+Lossless version control for every agent session: publishable, resumable.
+Works with Claude Code, Codex, OpenCode, and Cursor.
+
+On disk, sessions are just JSONL files that get overwritten, compacted, and
+cleaned up at any moment. `agit` puts snapshots and versions on top of them,
+so "that conversation last Wednesday that finally cracked the bug" becomes
+something you can find, continue, and hand to a teammate.
+
+```
+agit import <session> -n <agent>   adopt an existing claude / codex / opencode / cursor session and record its first version
+agit commit <agent>                record another version (snapshot of the session's full current content)
+agit push <agent>                  publish to the hub, get a link
+agit clone <owner>/<agent>         fetch (with git history) and pick up right away; --mine creates a copy under your name
+agit upgrade                       upgrade the CLI itself to the latest release the hub announces
+```
+
+Adopting and recording the first version are one command — the in-between
+state ("linked, but unversioned") means nothing to anyone. To mark a session
+without versioning it (e.g. offline), pass `--link-only`.
+
+`agit clone` is **read-only by default**: nothing is created in your name,
+`origin` points at the source, the session is installed into your runtime and
+you can `agit commit` locally as usual. When you decide to take over, use
+`--mine` — that creates your copy on the hub, repoints `origin` at it, and
+remembers the source as `upstream`. Running `agit push` from a read-only
+checkout offers exactly that.
+
+The full command list is in `agit --help`.
+
+## Install
+
+### Users: npm
+
+```sh
+npx -y create-agit                 # one-shot: installs agit + wires skills/hooks/MCP
+# or as a global package:
+npm install -g @einsia/agent-git   # pnpm add -g @einsia/agent-git works too
+agit --version
+```
+
+Both routes install a prebuilt binary — no Rust toolchain required. npm
+picks the platform sub-package matching your `os`/`cpu`; on platforms with no
+prebuilt binary (e.g. Windows) running `agit` prints the source-build recipe.
+Details and environment variables: [`npm/README.md`](npm/README.md).
+
+pnpm (v10+) does not run dependency install scripts by default, so the
+automatic `agit setup` is skipped there — run `agit setup` once yourself
+after installing.
+
+The Linux artifact is **musl static-linked**, so no minimum glibc — the
+release pipeline runs every Linux binary inside an Alpine / Amazon Linux /
+Debian / Ubuntu container matrix before publishing.
+
+You also need **git >= 2.28** (repo init uses `git init --initial-branch`).
+Ubuntu 20.04 ships 2.25 — the installer prints a warning.
+
+> Do not install `@einsia/agentgit` (no hyphen) — that is the pre-rewrite
+> CLI; its protocol does not match this branch and it will not work.
+
+### Contributors / eager users: from source
+
+```sh
+git clone https://github.com/Einsia/agent-git
+cd agent-git
+./setup.sh
+```
+
+`setup.sh` checks the toolchain (rustc, a C compiler), builds, and installs
+the binary to `~/.local/bin/agit`. Common flags:
+
+```sh
+./setup.sh --debug      # no LTO, much faster while hacking
+./setup.sh --test       # run cargo test --lib before installing
+./setup.sh --help
+```
+
+To build a binary whose built-in hub is the staging deployment, set the build-time default
+explicitly. Runtime `AGIT_HUB_URL` and `agit config set hub.url ...` still take precedence:
+
+```sh
+AGIT_DEFAULT_HUB_URL=https://staging.agent-git.com cargo build --release --locked
+```
+
+Internal GitLab pipelines package commit-addressed `dev` and `staging` builds with this setting
+embedded. Their `agit --version` output includes the channel and source commit, and `agit upgrade`
+is disabled for them so an acceptance-test binary cannot silently turn into the public release.
+Only an existing GitHub `agit-v*` tag produces the `prod` channel. The tag push runs the Release
+workflow automatically; operators may also select the same reviewed tag through the workflow's
+manual production input to retry a failed release without creating a different artifact identity.
+
+Requires **rustc >= 1.88** and a C compiler (`rusqlite` uses the `bundled`
+feature, so sqlite's C sources are compiled during the build). The reason for
+the toolchain floor is in [`docs/01_setup.md`](docs/01_setup.md).
+
+Both paths install the same binary. npm is for "users who don't want to touch
+Rust"; `setup.sh` is for "people changing the code" and "people running
+unreleased versions".
+
+## Docs
+
+| Goal                                    | Where                                                         |
+| --------------------------------------- | ------------------------------------------------------------- |
+| Build, run the backend, sign in, debug  | [`docs/01_setup.md`](docs/01_setup.md)                        |
+| How sessions are stored locally         | [`docs/02_session_store.md`](docs/02_session_store.md)        |
+| The terminal interface for humans       | [`docs/07_tui.md`](docs/07_tui.md)                            |
+| Login / token mechanics                 | [`docs/commands/auth.md`](docs/commands/auth.md)              |
+| Local low-entropy secret filtering      | [`docs/05_global_secret_filter.md`](docs/05_global_secret_filter.md) |
+| Reversible repository secret placeholders | [`docs/06_repository_secret_dictionary.md`](docs/06_repository_secret_dictionary.md) |
+| Probed storage formats of each runtime  | [`docs/mechanism-probing/`](docs/mechanism-probing/)          |
+| npm package behavior and env vars       | [`npm/README.md`](npm/README.md)                              |
+| Release artifact naming contract        | [`.github/RELEASE_ARTIFACTS.md`](.github/RELEASE_ARTIFACTS.md) |
+
+The server (**AgentGit**) is a separate repository, deployed on its own.
+
+## Release
+
+`Cargo.toml` is the single source of the version; every npm manifest must
+agree with it (`node scripts/check-version.js` — run in CI and before
+`npm pack`). To move the version, change every spot in one shot:
+
+```sh
+node scripts/bump-version.mjs 0.1.0    # Cargo.toml + Cargo.lock + all npm manifests
+```
+
+Pushing the tag runs the whole chain — binaries first, npm right after:
+
+```sh
+git tag agit-v0.1.0 && git push origin agit-v0.1.0   # release.yml builds, smoke-tests, attaches artifacts
+```
+
+Distribution to users runs through the npm registry: each target ships as a
+platform sub-package (`@einsia/agent-git-linux-x64` and friends, gated by
+`os`/`cpu` — npm installs only the matching one), and the main
+`@einsia/agent-git` pulls them in via `optionalDependencies`. The GitHub
+Release holds the canonical tarballs plus `SHA256SUMS`
+([contract](.github/RELEASE_ARTIFACTS.md)).
+
+Publishing to npm is the **npm publish** workflow. It runs automatically
+once the Release workflow finishes green (and can be dispatched manually —
+Actions → npm publish — for retries, `next` dist-tag trials, or a `dry_run`).
+It publishes the whole family in dependency order — platform packages →
+`@einsia/agent-git` → `create-agit` — with a real global install of the main
+tarball as a preflight in between, authenticating via npm trusted publishing
+(OIDC, no stored token). The equivalent local fallback:
+
+```sh
+gh release download agit-v0.1.0 -p 'agit-*.tar.gz' -D /tmp/agit-dist
+node npm/publish.mjs /tmp/agit-dist        # platform packages → main → create-agit
+```
+
+`npm/create-agit/` is the one-shot installer behind `npx -y create-agit` — it
+depends on the main package and turns the npx cache copy into a durable
+`~/.local/bin/agit`, then wires skills/hooks/MCP via `agit setup`. There is
+deliberately no unscoped alias package: `agit` on npm belongs to an unrelated
+project, and npm's typosquat rule blocks `agent-git` for being one punctuation
+mark away from a third party's `agentgit`.
+
+The version oracle (`GET /api/cli/version` on the hub) and `agit upgrade`
+both read the npm registry; integrity verification uses the registry's
+SRI (sha512). Self-hosted hubs that pin an internal fork set
+`AGIT_BACKEND_CLI_REPO` and the whole chain reverts to the GitHub path.
+
+`@einsia/agent-git` is a fresh package name with no existing users, so the
+first release goes straight to `latest` — no need to hide in `next` first.
+(The old `@einsia/agentgit` stays put; it points at the pre-rewrite CLI.)

package/npm/README.md

@@ -0,0 +1,75 @@
+# @einsia/agent-git (npm distribution)
+
+This package ships the prebuilt **`agit`** CLI — no Rust toolchain needed.
+
+```sh
+npx -y create-agit                 # one-shot install: binary + skills/hooks/MCP
+# or as a global package:
+npm install -g @einsia/agent-git   # pnpm add -g @einsia/agent-git — same CLI
+agit --help
+```
+
+Two package names, one CLI:
+
+| Package             | Role                                                        |
+| ------------------- | ----------------------------------------------------------- |
+| `@einsia/agent-git` | the real package — shim, postinstall, platform sub-packages |
+| `create-agit`       | `npx` one-shot installer, lands `agit` in `~/.local/bin`    |
+
+> The old package `@einsia/agentgit` (no hyphen) is the pre-rewrite CLI. This
+> package is its successor, not a new version of it; there is no upgrade path
+> between the two.
+
+`agit` is a native Rust binary. This package is a thin wrapper: npm installs
+the platform sub-package matching your `os`/`cpu` via `optionalDependencies`
+(`@einsia/agent-git-linux-x64` and friends), the `agit` bin is a Node shim
+that execs that binary with argv/stdio/exit-code forwarded, and `postinstall`
+runs `agit setup` once to wire skills, hooks, MCP and AGENTS.md.
+
+pnpm (v10+) blocks dependency install scripts unless approved, so under pnpm
+the automatic `agit setup` does not run — run it once yourself after
+installing (or `pnpm approve-builds -g` and reinstall).
+
+The hub (**AgentGit**) is not in this package; it deploys separately.
+
+## Platforms with prebuilt binaries
+
+| OS    | Arch          | Platform package                  |
+| ----- | ------------- | --------------------------------- |
+| Linux | x86_64        | `@einsia/agent-git-linux-x64`     |
+| Linux | aarch64/arm64 | `@einsia/agent-git-linux-arm64`   |
+| macOS | x86_64        | `@einsia/agent-git-darwin-x64`    |
+| macOS | arm64         | `@einsia/agent-git-darwin-arm64`  |
+
+**Linux binaries are musl static-linked — no glibc floor.** Verified on Alpine,
+Amazon Linux 2 (glibc 2.26), Debian 11/12, Ubuntu 20.04–24.04, x86_64 and
+arm64. No more `libc.so.6: version 'GLIBC_2.xx' not found`.
+
+On macOS, if Node runs under Rosetta (it reports itself as x64) the installer
+detects it and installs the arm64 build.
+
+Unsupported platforms (including Windows) get no prebuilt binary: running
+`agit` prints build-from-source instructions. On WSL, the Linux binary works.
+
+## Failure behavior
+
+- Unsupported platform → the shim explains and exits 127 with the source-build
+  recipe.
+- `agit setup` failing in postinstall never blocks the install — the CLI is on
+  disk; re-run `agit setup` any time.
+
+## Environment variables
+
+| Variable         | Effect                                                              |
+| ---------------- | ------------------------------------------------------------------- |
+| `AGIT_BINARY`    | Point at an existing `agit` binary; shim and postinstall honor it.  |
+| `AGIT_SKIP_SETUP`| Skip the postinstall `agit setup` (CI, managed environments).       |
+| `AGIT_FORCE_INSTALL` | Also run postinstall inside the source checkout (CI smoke tests). |
+| `AGIT_HUB_URL`   | Point the CLI at another hub (default `https://agent-git.com`).  |
+| `AGIT_NPM_REGISTRY` | Registry `agit upgrade` downloads platform packages from.        |
+
+## Upgrading
+
+`agit upgrade` asks the hub for the latest CLI version and downloads the
+platform package tarball straight from the npm registry, verified against the
+registry's SRI (sha512) before anything is replaced.

package/npm/lib/log.js

@@ -0,0 +1,12 @@
+'use strict';
+
+// All diagnostics go to stderr: the shim forwards the real binary's stdout, and
+// the wrapper must not mix one word of its own into it. The prefix makes it
+// obvious at a glance which line the wrapper said and which agit itself said.
+const TAG = '[agit]';
+
+module.exports = {
+  info: (m) => process.stderr.write(`${TAG} ${m}\n`),
+  warn: (m) => process.stderr.write(`${TAG} warning: ${m}\n`),
+  error: (m) => process.stderr.write(`${TAG} error: ${m}\n`),
+};

package/npm/lib/platform.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+
+// The current Node runtime → platform key. The main package
+// (optionalDependencies), the npx wrapper, publish.mjs and the CLI's
+// `agit upgrade` share the same key set, and the key is the suffix of the npm
+// platform package name: @einsia/agent-git-<key>. Changing this means changing
+// release.yml's matrix, publish.mjs's mapping and upgrade.rs too.
+//
+// Linux is musl static linking: a gnu artifact built on ubuntu:24.04 locks in
+// GLIBC_2.39 and nothing starts on older distributions; musl's static-pie has
+// no interpreter, so it has no glibc floor. No win32: the release pipeline
+// produces no windows artifacts.
+const KEYS = {
+  'linux/x64': 'linux-x64',
+  'linux/arm64': 'linux-arm64',
+  'darwin/x64': 'darwin-x64',
+  'darwin/arm64': 'darwin-arm64',
+};
+
+// Platform key → Rust target triple (CI names artifact archives by triple).
+const TRIPLES = {
+  'linux-x64': 'x86_64-unknown-linux-musl',
+  'linux-arm64': 'aarch64-unknown-linux-musl',
+  'darwin-x64': 'x86_64-apple-darwin',
+  'darwin-arm64': 'aarch64-apple-darwin',
+};
+
+function packageName(key) {
+  return `@einsia/agent-git-${key}`;
+}
+
+// Under Rosetta, node reports itself as x64. sysctl.proc_translated=1 means
+// the real hardware is arm64, so installing the arm64 package avoids the
+// translation layer.
+function realArch(nodePlatform, nodeArch) {
+  const platform = nodePlatform || process.platform;
+  const arch = nodeArch || process.arch;
+  if (platform !== 'darwin' || arch !== 'x64') return arch;
+  const r = spawnSync('sysctl', ['-n', 'sysctl.proc_translated'], { encoding: 'utf8' });
+  return !r.error && r.status === 0 && (r.stdout || '').trim() === '1' ? 'arm64' : arch;
+}
+
+// Returns this machine's platform key; an unsupported platform (win32, for
+// example) returns null and the caller picks the wording.
+function packageKey(nodePlatform, nodeArch) {
+  const platform = nodePlatform || process.platform;
+  const arch = nodeArch === undefined ? realArch() : nodeArch;
+  return KEYS[`${platform}/${arch}`] || null;
+}
+
+function binaryName(nodePlatform) {
+  return (nodePlatform || process.platform) === 'win32' ? 'agit.exe' : 'agit';
+}
+
+function supportedList() {
+  return Object.values(KEYS)
+    .map((k) => `${k} (${TRIPLES[k]})`)
+    .join(', ');
+}
+
+module.exports = {
+  KEYS,
+  TRIPLES,
+  packageName,
+  packageKey,
+  realArch,
+  binaryName,
+  supportedList,
+};

package/npm/lib/resolve.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const platform = require('./platform');
+
+// Where the real binary is. Distribution is a platform subpackage
+// (@einsia/agent-git-<key>; npm installs only the one matching os/cpu), so the
+// default meaning is "find that package in the dependency tree". The resolution
+// order is deliberately fixed:
+//
+//   1. An explicit AGIT_BINARY override — the user is pointing the way and gets
+//      the last word.
+//   2. This package's bin/<agit> — placed by hand outside the publish flow (a
+//      build a volunteer is testing, for example).
+//   3. The platform subpackage's package/bin/<agit> — the normal path.
+//
+// A require that resolves nothing means npm skipped the optional dep for this
+// platform (an unsupported system).
+function resolveBinary(pkgRoot) {
+  const override = process.env.AGIT_BINARY;
+  if (override) {
+    if (!fs.existsSync(override)) {
+      throw new Error(`AGIT_BINARY points at "${override}", but there is no file there.`);
+    }
+    return override;
+  }
+
+  const local = path.join(pkgRoot, 'bin', platform.binaryName());
+  if (fs.existsSync(local)) return local;
+
+  const key = platform.packageKey();
+  if (!key) return null;
+  const name = path.join(platform.packageName(key), 'bin', platform.binaryName()).replace(/\\/g, '/');
+  // Resolve by walking node_modules up from the package root; that matches
+  // where npm installs the optional dep.
+  try {
+    return require.resolve(name, { paths: [pkgRoot] });
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { resolveBinary };

package/npm/lib/run.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const platform = require('./platform');
+const { resolveBinary } = require('./resolve');
+const log = require('./log');
+
+// Entry point for the `agit` command. Thin is deliberate: forward argv / stdio /
+// exit code, nothing else. agit gets written into scripts and hooks, so exit
+// codes and stdio pass-through are load-bearing semantics and must not change.
+function run() {
+  const pkgRoot = path.join(__dirname, '..');
+  let bin = null;
+  try {
+    bin = resolveBinary(pkgRoot);
+  } catch (e) {
+    log.error(e.message);
+    process.exit(1);
+  }
+
+  if (!bin) {
+    // npm skipped the optional dep for this os/cpu = this platform has no
+    // prebuilt artifact (win32, freebsd, ...). This block is often everything
+    // the user sees, so on its own it has to say why there is no binary and
+    // which command fixes it.
+    log.error(`no prebuilt agit binary for ${process.platform}/${process.arch}.`);
+    log.error('');
+    log.error(`prebuilt: ${platform.supportedList()}`);
+    log.error('');
+    log.error('build from source instead:');
+    log.error('  git clone https://github.com/Einsia/agent-git');
+    log.error('  cd agent-git && ./setup.sh');
+    log.error('');
+    log.error('already have a binary? AGIT_BINARY=/path/to/agit agit …');
+    // 127 is the shell's conventional code for "command not found".
+    process.exit(127);
+  }
+
+  const r = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
+  if (r.error) {
+    log.error(`failed to start ${bin}: ${r.error.message}`);
+    process.exit(1);
+  }
+  process.exit(r.status === null ? 1 : r.status);
+}
+
+module.exports = { run };

package/npm/postinstall.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// postinstall: the binary lands with the optional dep, so there is nothing to download. It
+// does two things in passing, each idempotent and neither able to block the install when it
+// fails:
+//
+// 1. Self-check that the binary really runs (an architecture mismatch, Rosetta and the like
+//    surface here rather than the first time the user types agit).
+// 2. Run `agit setup` — the product promise of "installed by default at download time":
+//    skills, hooks, MCP and AGENTS.md, all in one go. AGIT_SKIP_SETUP=1 turns it off
+//    (CI / hosted environments).
+//
+// npm displays postinstall output badly, so stay quiet: speak only when something is wrong.
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const { resolveBinary } = require('./lib/resolve');
+const log = require('./lib/log');
+
+function truthy(v) {
+  return v != null && v !== '' && v !== '0' && String(v).toLowerCase() !== 'false';
+}
+
+function main() {
+  // Whoever runs `npm install` inside the source repository is not a user: a Cargo.toml next
+  // door and no node_modules in its own path = the contributor path, and contributors go through
+  // ./setup.sh. AGIT_FORCE_INSTALL=1 bypasses this (CI smoke test).
+  const pkgRoot = path.join(__dirname);
+  const inNodeModules = pkgRoot.split(path.sep).includes('node_modules');
+  if (!truthy(process.env.AGIT_FORCE_INSTALL) &&
+      !inNodeModules && fs.existsSync(path.join(pkgRoot, '..', 'Cargo.toml'))) {
+    return;
+  }
+
+  let bin;
+  try {
+    bin = resolveBinary(pkgRoot);
+  } catch (e) {
+    log.warn(e.message);
+    return;
+  }
+  if (!bin) return; // unsupported platform: the shim gives full instructions on the next command.
+
+  const check = spawnSync(bin, ['--version'], { encoding: 'utf8' });
+  if (check.error || check.status !== 0) {
+    log.warn(`installed binary does not run: ${bin}`);
+    log.warn((check.stderr || check.error?.message || `exit ${check.status}`).trim());
+    return;
+  }
+
+  if (truthy(process.env.AGIT_SKIP_SETUP)) return;
+  const setup = spawnSync(bin, ['setup'], { stdio: 'inherit' });
+  if (setup.status !== 0) {
+    log.warn('`agit setup` did not fully succeed — re-run it any time; the CLI itself is installed.');
+  }
+}
+
+main();

package/npm/shim.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+// Entry point for the `agit` command. Staying this thin is deliberate: the real logic lives in
+// lib/run.js, and every extra line here is one more thing to keep in sync in two places.
+require('./lib/run').run();

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@einsia/agent-git",
+  "version": "0.0.9",
+  "description": "Version control for agent sessions — the agit CLI plus skills/hooks/MCP wiring for Claude Code, Codex, OpenCode and Cursor. The AgentGit hub deploys separately.",
+  "keywords": [
+    "agit",
+    "agent",
+    "git",
+    "llm",
+    "claude",
+    "claude-code",
+    "codex",
+    "opencode",
+    "cursor",
+    "session",
+    "mcp",
+    "cli"
+  ],
+  "license": "MIT",
+  "homepage": "https://agent-git.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Einsia/agent-git.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Einsia/agent-git/issues"
+  },
+  "bin": {
+    "agit": "npm/shim.js"
+  },
+  "files": [
+    "npm/shim.js",
+    "npm/postinstall.js",
+    "npm/lib/",
+    "npm/README.md",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node npm/postinstall.js",
+    "check-version": "node scripts/check-version.js",
+    "bump-version": "node scripts/bump-version.mjs",
+    "prepack": "node scripts/check-version.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@einsia/agent-git-linux-x64": "0.0.9",
+    "@einsia/agent-git-linux-arm64": "0.0.9",
+    "@einsia/agent-git-darwin-x64": "0.0.9",
+    "@einsia/agent-git-darwin-arm64": "0.0.9"
+  }
+}