attestari 0.0.0-stage → 2.9.1

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# attestari
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Attestari Protect hook: the one file each agent (Claude Code first) runs itself.
+
+- `dist/hook.js` is the whole hook. It is built from `src/` by esbuild, committed, and has no runtime
+  dependency: it requires only Node's own modules (`node:fs`, `node:path`, `node:os`, and the like).
+- Build: `npm install && npm run build`. Test: `npm test` (builds, then runs `node --test` on the built file).
+  Type check: `npm run check`.
+- `node dist/hook.js status` prints each agent folder under `~/.attestari/`; every unbuilt subcommand exits 2.
+- Built for Claude Code: `pair --code <code>`, `claude-code session-start` (resolves the configured servers of its
+  folder and starts the check-in detached), `claude-code refresh` (the check-in: the policy, the events,
+  and the agent's own `deniedMcpServers` entries) and `claude-code pre-tool-use` (decides each MCP call, and starts the
+  refresh when the last check-in is over an hour old). `ATTESTARI_ACCOUNTS_URL` points the hook at another accounts
+  service only on loopback (`127.0.0.1`, `::1`, `localhost`: the tests' local server); any other address is ignored
+  with one line on stderr.
+- What it resolves: `npx`/`bunx`/`pnpx`/`pnpm dlx`/`yarn dlx` an npm package, `uvx`/`pipx run` a PyPI package, a URL a
+  remote, any other command (`docker`, `node file.js`, an executable) a local tool. A registry runner whose package
+  it cannot name (an alias, a git, tarball, file or URL spec, a second package, `${PKG}`, or any flag but `-y`,
+  `--yes`, `-q`, `--quiet`, `-p`/`--package`, uvx's `--from`, `--python` and `-p` (python) and pipx's `--spec`) is left out of the resolution,
+  reported to nobody, and denied as not checked, never a local tool; stderr says "its package could not be named"
+  with the key.
+- What it keeps, under `~/.attestari/claude-code/`: `token`, `secret` (the key of a local tool's hash), `policy.json`
+  and `policy.etag`, `resolved/<folder>.json` and `written/<folder>.json` (per working folder: `<folder>` is the first
+  16 hexadecimal characters of the SHA-256 of the session's `cwd`; the resolution holds the folder's path, and both
+  are dropped at a check-in once the folder is gone or its resolution was not rewritten by a session start for 30
+  days, its deny entries taken back when it was read whole), `sessions/<session_id>` (the folder a session
+  started in, its id and path, written at SessionStart; pruned after 30 days at a check-in), `events.jsonl`, and the
+  times `checked_in_at`, `refresh_started_at` (with the refresh's process id) and `next_refresh_at`. A call is decided
+  by the `resolved/` file of its session's start folder (the call's `cwd` follows Claude's `cd`; it is used only when
+  the session has no file); the check-in reports the union of them all, a key launching different packages in two folders
+  once per folder as `<key>/<8 hex of the folder's hash>`. `refresh --cwd <folder>` resolves that folder first when
+  it has no file yet. A check-in answered 401 `invalid_token` (the agent was removed) deletes `token`, `policy.json`
+  and `policy.etag`, so every MCP call is then denied until the agent is paired again; the deny entries are written
+  only when `~/.claude/settings.json` is unchanged between the reading and the rename.
+- The build also copies `dist/hook.js` to `plugins/attestari/hooks/hook.js`, the Claude Code plugin's copy (the
+  marketplace is `plugins/`); `test/build.test.mjs` refuses a difference, and CI refuses a committed copy older than
+  the build. `pair` installs the plugin when `claude` is on the PATH (`claude plugin marketplace add
+  attestari-ai/plugins`, then `claude plugin install attestari@attestari --scope user`; `ATTESTARI_MARKETPLACE` names
+  another marketplace, such as a local `plugins/` folder) and otherwise prints the two commands. What the hook reads
+  and writes on a computer: `docs/app.attestari.ai/hook.md`.
+- The build also makes `dist/gateway.js` (from `src/gateway-main.ts`; not committed itself, but copied byte for byte to
+  `extension/server/gateway.js`, which is, and packed into `attestari.mcpb` by `npm run pack:extension`): the Claude
+  Desktop extension's gateway (M2.5), one MCP server on stdio that starts the child servers it is given, in the home
+  folder, and relays them under `<key>__`, with its own `attestari_status` tool. Run with no argument (as Claude
+  Desktop runs it) it first runs a provisional plan from the policy held (no network call before `initialize` is
+  answered), then pairs by `ATTESTARI_INSTALL_CODE`, checks in as `Claude Desktop`, decides from the policy which
+  servers of `~/.attestari/claude-desktop/servers.json` to start (`desktop.ts`), and checks in again hourly, stopping
+  and starting children as the policy moves; `checkin.ts` is the check-in it makes (session.ts's refresh without the
+  Claude Code parts; session.ts keeps its own copy so `dist/hook.js` does not move). `--servers <file>` runs it on a
+  `{servers, refused, notice}` file instead, bypassing the policy, and only with `ATTESTARI_GATEWAY_UNSAFE_FILE=1` and
+  a loopback `ATTESTARI_ACCOUNTS_URL` (the tests'; the same condition holds for `ATTESTARI_GATEWAY_REFRESH_MS`). Once
+  paired it moves Claude Desktop's own servers (`claude_desktop_config.json`'s `mcpServers`) into `servers.json` when
+  `ATTESTARI_MOVE_SERVERS` is `"true"`, with a dated backup beside the config, and puts them back when it is `"false"`
+  (`adapters/claude-desktop.ts`). What it reads, sends and writes: `docs/app.attestari.ai/hook.md`,
+  "Claude Desktop".
+- The sources, the tests and the built file are LF everywhere.