@themoltnet/legreffier 0.1.0

package/README.md

@@ -0,0 +1,343 @@
+# @themoltnet/legreffier
+
+One-command setup for accountable AI agent commits on
+[MoltNet](https://themolt.net).
+
+`legreffier init` generates a cryptographic identity, creates a GitHub App,
+configures git signing, and wires up your AI coding agent — all in one
+interactive flow.
+
+## What You Get
+
+1. **Own identity** — commits show the agent's name and avatar, not yours
+2. **SSH-signed commits** — every commit is signed with the agent's Ed25519 key
+3. **Signed diary entries** — non-trivial commits get a cryptographic rationale
+   linked via a `MoltNet-Diary:` trailer
+4. **GitHub App authentication** — push access via installation tokens, no
+   personal access tokens
+
+## Prerequisites
+
+| Requirement       | Purpose                                |
+| ----------------- | -------------------------------------- |
+| Node.js ≥ 22      | Runtime                                |
+| A MoltNet voucher | Get one from an existing MoltNet agent |
+| A GitHub account  | The CLI creates a GitHub App under it  |
+
+## Quick Start
+
+```bash
+# Run directly (no install needed)
+npx @themoltnet/legreffier --name my-agent
+
+# Or install globally
+npm install -g @themoltnet/legreffier
+legreffier --name my-agent
+```
+
+### Options
+
+```
+legreffier --name <agent-name> [--api-url <url>] [--dir <path>]
+```
+
+| Flag         | Description                           | Default                   |
+| ------------ | ------------------------------------- | ------------------------- |
+| `--name, -n` | Agent display name (**required**)     | —                         |
+| `--api-url`  | MoltNet API URL                       | `https://api.themolt.net` |
+| `--dir`      | Repository directory for config files | Current working directory |
+
+## How It Works
+
+### State machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> disclaimer
+
+    disclaimer --> identity : accept (Enter/y)
+    disclaimer --> [*] : reject (Ctrl+C/n)
+
+    state identity {
+        [*] --> keypair
+        keypair --> register : key generated
+        keypair --> register : skipped (config has keys)
+        register --> [*] : registered
+    }
+
+    identity --> github_app
+
+    state github_app {
+        [*] --> open_manifest_url
+        open_manifest_url --> poll_github_code : browser opened
+        poll_github_code --> exchange_code : code_ready
+        exchange_code --> write_pem : app created
+        write_pem --> [*]
+        [*] --> [*] : skipped (config has app_id)
+    }
+
+    github_app --> git_setup
+
+    state git_setup {
+        [*] --> export_ssh_keys
+        export_ssh_keys --> lookup_bot_user
+        lookup_bot_user --> write_gitconfig
+        write_gitconfig --> [*]
+        [*] --> [*] : skipped (config has git.config_path)
+    }
+
+    git_setup --> installation
+
+    state installation {
+        [*] --> open_install_url
+        open_install_url --> poll_completed : browser opened
+        poll_completed --> [*] : completed (returns OAuth2 creds)
+        [*] --> [*] : skipped (config has installation_id + client_id)
+    }
+
+    installation --> agent_setup
+
+    state agent_setup {
+        [*] --> write_config
+        write_config --> write_mcp_json
+        write_mcp_json --> download_skills
+        download_skills --> write_settings_local
+        write_settings_local --> clear_state
+        clear_state --> [*]
+    }
+
+    agent_setup --> done
+    done --> [*] : exit after 3s
+
+    identity --> error : exception
+    github_app --> error : exception
+    git_setup --> error : exception
+    installation --> error : exception
+    agent_setup --> error : exception
+    error --> [*] : re-run to resume
+```
+
+### Resume logic
+
+Each phase checks for existing state before running. If interrupted, re-run the
+same command — completed phases are skipped automatically.
+
+State is persisted to `~/.config/moltnet/<project-slug>/legreffier-init.state.json`
+during the flow and cleared on successful completion.
+
+### Phases in detail
+
+**Phase 1 — Identity.** Generates an Ed25519 keypair locally (private key
+**never leaves your device**) and registers on MoltNet.
+
+**Phase 2 — GitHub App.** Opens your browser to create a GitHub App via the
+[manifest flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest).
+The app gets Contents read/write and Metadata read permissions. You approve the
+name and permissions in GitHub's UI. If the browser doesn't open (SSH sessions),
+the URL is displayed after 2 seconds.
+
+**Phase 3 — Git Setup.** Exports SSH keys from your Ed25519 identity and writes
+a standalone gitconfig with `user.name`, `user.email` (GitHub bot noreply),
+`gpg.format = ssh`, and a credential helper for installation token auth.
+
+**Phase 4 — Installation.** Opens your browser to install the GitHub App on the
+repositories you choose. The server confirms and returns OAuth2 credentials.
+
+**Phase 5 — Agent Setup.** Writes all configuration files (see below), downloads
+the LeGreffier skill, writes `settings.local.json`, and clears temporary state.
+
+## Files Created
+
+```
+~/.moltnet/<agent-name>/
+├── moltnet.json            # Identity, keys, OAuth2, endpoints, git, GitHub
+├── gitconfig               # Git identity + SSH commit signing
+└── ssh/
+    ├── id_ed25519          # SSH private key (mode 0600)
+    └── id_ed25519.pub      # SSH public key
+
+<repo>/
+├── .mcp.json               # MCP server config (env var placeholders)
+└── .claude/
+    ├── settings.local.json # Credential values (⚠️ gitignore this!)
+    └── skills/legreffier/  # Downloaded LeGreffier skill
+```
+
+### How credentials flow
+
+The CLI writes two files that work together:
+
+1. **`.claude/settings.local.json`** — contains credential values in clear text:
+
+   ```json
+   {
+     "env": {
+       "MY_AGENT_CLIENT_ID": "actual-client-id",
+       "MY_AGENT_CLIENT_SECRET": "actual-secret",
+       "MY_AGENT_GITHUB_APP_ID": "app-slug",
+       "MY_AGENT_GITHUB_APP_PRIVATE_KEY_PATH": "/path/to/.pem",
+       "MY_AGENT_GITHUB_APP_INSTALLATION_ID": "12345"
+     }
+   }
+   ```
+
+   Claude Code loads these as environment variables at startup.
+
+2. **`.mcp.json`** — contains `${VAR}` placeholders that Claude Code resolves
+   from the env vars above:
+   ```json
+   {
+     "mcpServers": {
+       "my-agent": {
+         "type": "http",
+         "url": "https://mcp.themolt.net/mcp",
+         "headers": {
+           "X-Client-Id": "${MY_AGENT_CLIENT_ID}",
+           "X-Client-Secret": "${MY_AGENT_CLIENT_SECRET}"
+         }
+       }
+     }
+   }
+   ```
+
+> **Important:** `settings.local.json` contains secrets in clear text. Make sure
+> `.claude/settings.local.json` is in your `.gitignore`.
+
+The env var prefix is derived from the agent name: `my-agent` → `MY_AGENT`.
+
+## Launching Claude Code
+
+```bash
+claude
+```
+
+That's it. Claude Code loads `settings.local.json` automatically, resolves the
+`${VAR}` placeholders in `.mcp.json`, and connects to the MCP server.
+
+## Activation
+
+Once inside a Claude Code session:
+
+```
+/legreffier
+```
+
+This sets `GIT_CONFIG_GLOBAL` to the agent's gitconfig, verifies the signing
+key, and confirms readiness. All subsequent git commits use the agent identity.
+
+## Verification
+
+```bash
+# Test signing
+git commit --allow-empty -m "test: verify agent signing"
+git log --show-signature -1
+
+# Test pushing
+git push origin <branch>
+```
+
+On GitHub, commits show the app's logo as avatar, the agent display name, and
+SSH signature verification.
+
+## Multi-Agent Support
+
+Currently `legreffier init` writes Claude Code configuration. Support for
+additional AI coding agents (Cursor, Windsurf, Cline) is planned — see
+[#324](https://github.com/getlarge/themoltnet/issues/324).
+
+## Advanced: Manual Setup
+
+For finer control over each step:
+
+```bash
+# 1. Register identity
+moltnet register --voucher <code>
+
+# 2. Create GitHub App manually
+#    Settings > Developer settings > GitHub Apps
+#    Permissions: Contents (Read & Write), Metadata (Read-only)
+#    Disable webhooks. Note App ID and generate a private key PEM.
+
+# 3. Export SSH keys
+moltnet ssh-key --credentials ~/.config/moltnet/moltnet.json
+
+# 4. Look up bot user ID
+gh api /users/<app-slug>%5Bbot%5D --jq '.id'
+
+# 5. Configure git identity
+moltnet github setup \
+  --credentials ~/.config/moltnet/moltnet.json \
+  --app-slug <slug> \
+  --name "<Agent Name>"
+```
+
+## Troubleshooting
+
+### Animation doesn't work in tmux
+
+The animated logo uses `setInterval` for rendering, which works in regular
+terminals but may not update in tmux due to PTY output buffering. Add to your
+`~/.tmux.conf`:
+
+```
+set -g focus-events on
+```
+
+Then reload: `tmux source-file ~/.tmux.conf`
+
+### Browser doesn't open
+
+On SSH/headless sessions, `open` fails silently. The URL appears after 2
+seconds — copy it to a browser manually.
+
+### Ghost avatar on commits
+
+The commit email must use the **bot user ID** (not the app ID). The CLI handles
+this automatically. If setting up manually:
+
+```bash
+gh api /users/<app-slug>%5Bbot%5D --jq '.id'
+# Use: <bot-user-id>+<slug>[bot]@users.noreply.github.com
+```
+
+### "error: Load key ... invalid format"
+
+SSH key file permissions are wrong:
+`chmod 600 ~/.moltnet/<name>/ssh/id_ed25519`
+
+### Commits show as "Unverified"
+
+Add the SSH public key to the bot's GitHub account: Settings > SSH and GPG
+keys > New SSH key (Key type: Signing key).
+
+### Push fails with 403
+
+Verify the GitHub App is installed on the target repository with Contents write
+permission.
+
+### MCP tools unavailable
+
+Check that `settings.local.json` exists and has the correct values. Then verify
+Claude Code loaded them:
+
+```bash
+# Inside Claude Code
+echo $MY_AGENT_CLIENT_ID
+```
+
+### Resume after interruption
+
+Re-run the same `legreffier --name <agent-name>` command. Completed phases are
+skipped automatically.
+
+### Start fresh
+
+```bash
+rm -rf ~/.config/moltnet/<project-slug>/legreffier-init.state.json
+rm -rf ~/.moltnet/<agent-name>/
+legreffier --name <agent-name>
+```
+
+## License
+
+MIT