agserver 1.0.0

package/README.md

@@ -0,0 +1,448 @@
+# AGServer
+
+AI-assisted git project browser server. Run it against any folder of git repos and connect your client app to browse code, view git history, and chat with an AI agent via `kiro-cli`.
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- `git` on PATH
+- `kiro-cli` installed and authenticated (for chat endpoints)
+
+---
+
+## Install
+
+```bash
+npm install -g agserver
+```
+
+---
+
+## Start the server
+
+```bash
+# Serve a specific folder
+agserver ~/my-projects
+
+# Custom port
+agserver ~/my-projects --port 9000
+
+# Bind to all interfaces (LAN access)
+agserver ~/my-projects --public
+
+# Provide your own API key
+agserver ~/my-projects --key my-secret-key-at-least-24-chars
+```
+
+On first run the server prints the auto-generated API key — copy it, you'll need it in your client:
+
+```
+  agserver
+  projects root : /Users/you/my-projects
+  port          : 8765
+  kiro-cli      : 1.2.3 ✓
+[agserver] running
+[agserver] host=127.0.0.1 port=8765 apiVersion=1.0.0
+[agserver] api key: <generated-key-shown-here>   ← copy this
+```
+
+---
+
+## Connecting from your client
+
+Every request to `/api/*` must include the header:
+
+```
+x-agserver-key: <your-api-key>
+```
+
+The server also returns `x-agserver-version` on every response. Check it matches your client's expected major version.
+
+### Version compatibility check (recommended)
+
+```js
+const res = await fetch('http://localhost:8765/health');
+const { apiVersion } = await res.json();
+const [serverMajor] = apiVersion.split('.');
+const [clientMajor] = CLIENT_API_VERSION.split('.');
+if (serverMajor !== clientMajor) throw new Error('AGServer version mismatch');
+```
+
+### Base client helper (JavaScript)
+
+```js
+const BASE = 'http://localhost:8765';
+const KEY  = 'your-api-key-here';
+
+async function api(path, opts = {}) {
+  const res = await fetch(`${BASE}${path}`, {
+    ...opts,
+    headers: { 'x-agserver-key': KEY, 'Content-Type': 'application/json', ...opts.headers },
+  });
+  if (!res.ok) throw new Error(`AGServer ${res.status}: ${await res.text()}`);
+  return res.json();
+}
+```
+
+---
+
+## Endpoints
+
+### GET /health
+No auth required. Use this to verify the server is reachable and check its version.
+
+```
+GET http://localhost:8765/health
+```
+
+```json
+{
+  "ok": true,
+  "apiVersion": "1.0.0",
+  "host": "127.0.0.1",
+  "port": 8765,
+  "privateIpOnly": false,
+  "time": "2026-01-01T00:00:00.000Z"
+}
+```
+
+---
+
+### GET /api/project-list
+Returns all git repos discovered one level deep under the projects root.
+
+```
+GET /api/project-list
+x-agserver-key: <key>
+```
+
+```json
+{
+  "version": 1,
+  "title": "AGClient",
+  "groups": ["All Project", "AGProject"],
+  "projects": [
+    {
+      "id": "project-myrepo",
+      "name": "myrepo",
+      "path": "myrepo",
+      "summary": "fix: login bug (main)",
+      "status": "online",
+      "lastChange": "2026-01-01",
+      "group": "AGProject",
+      "unreadCount": 3,
+      "initials": "MY",
+      "avatarColor": "#2563EB"
+    }
+  ]
+}
+```
+
+`status` is one of `"online"` | `"busy"` (uncommitted changes) | `"warning"` (merge conflicts).
+
+---
+
+### GET /api/project-branches?projectId=
+Returns branches and tags for a project.
+
+```
+GET /api/project-branches?projectId=project-myrepo
+x-agserver-key: <key>
+```
+
+```json
+{
+  "version": 1,
+  "projects": [{
+    "projectId": "project-myrepo",
+    "projectName": "myrepo",
+    "branches": [
+      {
+        "id": "branch-feat-login",
+        "name": "feat/login",
+        "brief": "Add login flow",
+        "tag": "FEAT",
+        "color": "#2563EB",
+        "icon": "alt-route",
+        "lastChange": "2 days ago",
+        "group": "active",
+        "commitCount": 4
+      }
+    ],
+    "tags": [
+      { "id": "tag-v1-0-0", "name": "v1.0.0", "lastChange": "3 weeks ago", "subject": "Release v1.0.0" }
+    ]
+  }]
+}
+```
+
+`group` is `"active"` or `"stale"` based on `AGSERVER_ACTIVE_BRANCH_DAYS` (default 30).
+
+---
+
+### GET /api/branch-workspace?projectId=&branchId=
+Returns the full workspace data for a branch — git graph, change summary, file browser config.
+
+```
+GET /api/branch-workspace?projectId=project-myrepo&branchId=branch-feat-login
+x-agserver-key: <key>
+```
+
+```json
+{
+  "version": 1,
+  "workspaces": [{
+    "projectId": "project-myrepo",
+    "branchId": "branch-feat-login",
+    "tabs": {
+      "git": { "graph": { "selectedBranch": "feat/login", "baseBranch": "main", "script": "..." } },
+      "changes": { "chips": ["All 3", "Modified 2", "New 1", "Delete 0"], "tree": [...] },
+      "chat": { "mode": "text-placeholder" },
+      "files": { "rootPath": "", "initialDepth": 2 }
+    }
+  }]
+}
+```
+
+The `git.graph.script` is a `@gitgraph/js` imperative script — pass it to a `GitgraphJS.createGitgraph` container to render the graph.
+
+---
+
+### GET /api/git/commit?projectId=&branchId=&commitId=
+Returns commit metadata and its diff tree. Use `commitId=working-tree` for uncommitted changes.
+
+```
+GET /api/git/commit?projectId=project-myrepo&branchId=branch-feat-login&commitId=abc1234
+x-agserver-key: <key>
+```
+
+```json
+{
+  "version": 1,
+  "projectId": "project-myrepo",
+  "branchId": "branch-feat-login",
+  "commit": {
+    "id": "abc1234",
+    "hash": "abc1234...",
+    "shortHash": "abc1234",
+    "subject": "fix: handle null user",
+    "author": "Jane",
+    "authoredAt": "2026-01-01",
+    "isWorkingTree": false
+  },
+  "changes": {
+    "chips": ["All 2", "Modified 2", "New 0", "Delete 0"],
+    "tree": [{ "id": "c1", "level": 0, "type": "file", "name": "auth.ts", "path": "src/auth.ts", "status": "M" }],
+    "patch": "diff --git ...",
+    "patchTruncated": false
+  }
+}
+```
+
+---
+
+### GET /api/git/commit-file?projectId=&branchId=&commitId=&path=
+Returns the content of a specific file at a commit.
+
+```
+GET /api/git/commit-file?projectId=project-myrepo&branchId=branch-feat-login&commitId=abc1234&path=src/auth.ts
+x-agserver-key: <key>
+```
+
+```json
+{
+  "path": "src/auth.ts",
+  "content": "export function login() { ... }",
+  "size": 1024,
+  "binary": false,
+  "truncated": false
+}
+```
+
+For images: `"image": true`, content is base64. For PDFs: `"pdf": true`, content is base64. For LFS pointers that can't be smudged: `"lfs": true`, content is empty.
+
+---
+
+### GET /api/git/commit-file-diff?projectId=&branchId=&commitId=&path=
+Returns the unified diff for a single file at a commit.
+
+```json
+{ "diff": "--- a/src/auth.ts\n+++ b/src/auth.ts\n...", "truncated": false }
+```
+
+---
+
+### GET /api/files/tree?projectId=&branchId=&path=&levels=
+Browse the file tree. `path` defaults to repo root, `levels` is 1–4 (default 2).
+
+```
+GET /api/files/tree?projectId=project-myrepo&branchId=branch-feat-login&path=src&levels=2
+x-agserver-key: <key>
+```
+
+```json
+{
+  "projectId": "project-myrepo",
+  "branchId": "branch-feat-login",
+  "path": "src",
+  "levels": 2,
+  "usingLiveFs": true,
+  "nodes": [
+    { "name": "components", "path": "src/components", "type": "dir", "hasChildren": true },
+    { "name": "auth.ts", "path": "src/auth.ts", "type": "file", "size": 1024, "ext": ".ts", "hasChildren": false }
+  ]
+}
+```
+
+`usingLiveFs: true` means the current checked-out branch is being served from disk. `false` means reading from git history.
+
+---
+
+### GET /api/files/content?projectId=&branchId=&path=
+Returns the content of any file in the repo.
+
+```
+GET /api/files/content?projectId=project-myrepo&branchId=branch-feat-login&path=src/auth.ts
+x-agserver-key: <key>
+```
+
+Same response shape as `commit-file`.
+
+---
+
+### GET /api/files/pdf?projectId=&branchId=&path=&commitId=
+Returns raw `application/pdf` bytes. Use directly as a PDF source URL (include the key as a query param is not supported — use a proxy or fetch + blob URL on the client).
+
+---
+
+### POST /api/chat/stream
+Streams an AI chat response via `kiro-cli`. Response is NDJSON — one JSON object per line.
+
+```
+POST /api/chat/stream
+x-agserver-key: <key>
+Content-Type: application/json
+
+{
+  "context": {
+    "projectId": "project-myrepo",
+    "branchId": "branch-feat-login",
+    "filePath": "src/auth.ts",
+    "fileContent": "...",
+    "fileDiff": "..."
+  },
+  "messages": [
+    { "role": "user", "content": "Why does login fail for null users?" }
+  ],
+  "attachments": [
+    { "path": "src/types.ts", "content": "..." }
+  ]
+}
+```
+
+Response stream (each line is a JSON object):
+```
+{"delta":"The issue is"}
+{"delta":" on line 42..."}
+{"done":true,"credits":0.003,"elapsed":"1.2s"}
+```
+
+On error:
+```
+{"error":"kiro-cli exited with code 1: ...","done":true}
+```
+
+Client reading example:
+```js
+const res = await fetch(`${BASE}/api/chat/stream`, {
+  method: 'POST',
+  headers: { 'x-agserver-key': KEY, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ context, messages, attachments }),
+});
+const reader = res.body.getReader();
+const decoder = new TextDecoder();
+let buf = '';
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  buf += decoder.decode(value, { stream: true });
+  const lines = buf.split('\n');
+  buf = lines.pop();
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const msg = JSON.parse(line);
+    if (msg.delta) process.stdout.write(msg.delta);
+    if (msg.done) console.log('\n[done]', msg);
+    if (msg.error) console.error('[error]', msg.error);
+  }
+}
+```
+
+---
+
+### POST /api/chat/message
+Same as `/api/chat/stream` but waits for the full response and returns it in one JSON object.
+
+```json
+{ "content": "The issue is on line 42...", "credits": 0.003, "elapsed": "1.2s" }
+```
+
+---
+
+### POST /api/worktrees/dispose
+Cleans up git worktrees created by chat sessions. Optionally scoped to one project.
+
+```json
+// request body (optional)
+{ "projectId": "project-myrepo" }
+
+// response
+{ "disposed": { "project-myrepo": [{ "dir": "...", "branch": "feat/login", "pushed": false }] } }
+```
+
+---
+
+## Error responses
+
+All errors follow the same shape:
+
+```json
+{ "error": "error_code", "message": "optional detail" }
+```
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `invalid_api_key` | 401 | Missing or wrong `x-agserver-key` |
+| `forbidden_remote_ip` | 403 | IP blocked by `PRIVATE_IP_ONLY` |
+| `not_found` | 404 | Unknown route |
+| `project_not_found` | 404 | `projectId` doesn't match any repo |
+| `branch_not_found` | 404 | `branchId` doesn't resolve |
+| `commit_not_found` | 404 | `commitId` not in repo |
+| `file_not_found` | 404 | Path not found at that ref |
+| `missing_project_id` | 400 | Required query param missing |
+| `path_outside_repo` | 400 | Path traversal attempt blocked |
+| `path_blocked` | 400 | Path points to an ignored directory |
+| `server_error` | 500 | Unexpected internal error |
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGSERVER_PORT` | `8765` | Listen port |
+| `AGSERVER_HOST` | `127.0.0.1` | Listen host |
+| `AGSERVER_API_KEY` | auto-generated | Auth key (min 24 chars) |
+| `AGSERVER_PROJECTS_ROOT` | cwd | Root folder scanned for git repos |
+| `AGSERVER_ALLOW_WEAK_KEY` | `0` | Set `1` to allow short keys in dev |
+| `AGSERVER_PRIVATE_IP_ONLY` | `0` | Set `1` to restrict to LAN subnet |
+| `AGSERVER_ACTIVE_BRANCH_DAYS` | `30` | Days before a branch is considered stale |
+| `AGSERVER_KIRO_CLI` | `kiro-cli` | Path to kiro-cli binary |
+
+---
+
+## Security note
+
+The chat endpoints (`/api/chat/*`) give an AI agent full tool access to your machine via `kiro-cli --trust-all-tools`. Treat your API key like a root password — never expose it in client-side code or commit it to source control.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "agserver",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "AI-assisted git project browser server — run from any folder like http-server",
+  "main": "server/index.mjs",
+  "bin": {
+    "agserver": "server/cli.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node server/cli.mjs",
+    "dev": "node --watch server/index.mjs"
+  },
+  "keywords": ["git", "kiro", "ai", "project-browser", "agserver"],
+  "license": "MIT",
+  "dependencies": {}
+}

package/schema/contract.md

@@ -0,0 +1,109 @@
+# AGServer — API Contract
+
+## Versioning
+
+API version: `1.0.0` (semver)
+
+The server advertises its version in every response via the `x-agserver-version` header.
+The `/health` endpoint also returns `apiVersion` in the JSON body.
+
+Compatibility rule: client and server are compatible if they share the same **major** version.
+The client should warn (but not block) on minor/patch mismatches.
+
+## Auth
+
+All `/api/*` endpoints require the header:
+```
+x-agserver-key: <AGSERVER_API_KEY>
+```
+
+## Endpoints
+
+### GET /health
+No auth required.
+```json
+{ "ok": true, "apiVersion": "1.0.0", "host": "...", "port": 8765, "time": "..." }
+```
+
+### GET /api/project-list
+Returns all git repos auto-discovered under `AGSERVER_PROJECTS_ROOT`.
+```json
+{ "version": 1, "title": "AGClient", "groups": ["All Project", "AGProject"], "projects": [...] }
+```
+
+### GET /api/project-branches?projectId=
+```json
+{ "version": 1, "projects": [{ "projectId", "projectName", "branches": [...], "tags": [...] }] }
+```
+
+### GET /api/branch-workspace?projectId=&branchId=
+```json
+{ "version": 1, "workspaces": [{ "projectId", "branchId", "tabs": { "git", "changes", "chat", "files" } }] }
+```
+
+### GET /api/git/commit?projectId=&branchId=&commitId=
+```json
+{ "version": 1, "projectId", "branchId", "commit": { "id", "hash", "shortHash", "subject", "author", "authoredAt", "isWorkingTree" }, "changes": { "chips", "tree", "patch", "patchTruncated" } }
+```
+
+### GET /api/git/commit-file?projectId=&branchId=&commitId=&path=
+```json
+{ "path", "content", "size", "binary", "truncated", "image?", "pdf?", "lfs?" }
+```
+
+### GET /api/git/commit-file-diff?projectId=&branchId=&commitId=&path=
+```json
+{ "diff": "...", "truncated": false }
+```
+
+### GET /api/files/tree?projectId=&branchId=&path=&levels=
+```json
+{ "projectId", "branchId", "path", "levels", "nodes": [{ "name", "path", "type", "hasChildren", "size?", "ext?", "children?" }] }
+```
+
+### GET /api/files/content?projectId=&branchId=&path=
+```json
+{ "path", "content", "size", "binary", "truncated", "image?", "pdf?", "lfs?" }
+```
+
+### GET /api/files/pdf?projectId=&branchId=&path=&commitId=
+Returns raw `application/pdf` bytes.
+
+### POST /api/chat/stream
+NDJSON stream. Each line: `{ "delta": "..." }` or `{ "done": true, "credits?", "elapsed?" }` or `{ "error": "..." }`.
+
+### POST /api/chat/message
+```json
+{ "content": "...", "credits?", "elapsed?" }
+```
+
+### POST /api/worktrees/dispose
+```json
+{ "disposed": { "<projectId>": [...] } }
+```
+
+### GET /api/project-settings?projectId=
+```json
+{ "projectId": "...", "settings": { "worktreeEnabled": false } }
+```
+
+### POST /api/project-settings?projectId=
+Body: `{ "worktreeEnabled": true }`
+```json
+{ "projectId": "...", "settings": { "worktreeEnabled": true } }
+```
+Settings are persisted in `<AGSERVER_PROJECTS_ROOT>/.agserver-settings.json`.
+By default `worktreeEnabled` is `false` — kiro-cli runs directly in the repo directory.
+Set to `true` to enable the git worktree isolation model for that project.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGSERVER_PORT` | `8765` | Listen port |
+| `AGSERVER_HOST` | `127.0.0.1` | Listen host |
+| `AGSERVER_API_KEY` | auto-generated | Auth key |
+| `AGSERVER_PROJECTS_ROOT` | `/Volumes/Agentic/AGProject` | Root dir scanned for git repos |
+| `AGSERVER_ALLOW_WEAK_KEY` | `0` | Set `1` for dev |
+| `AGSERVER_PRIVATE_IP_ONLY` | `0` | Restrict to LAN IPs |
+| `AGSERVER_ACTIVE_BRANCH_DAYS` | `30` | Days threshold for active/stale branches |

package/server/auth.mjs

@@ -0,0 +1,72 @@
+import os from 'os';
+
+export function normalizeIp(ip) {
+  if (!ip) return '';
+  if (ip.startsWith('::ffff:')) return ip.slice(7);
+  if (ip === '::1') return '127.0.0.1';
+  return ip;
+}
+
+function isPrivateIp(ip) {
+  const n = normalizeIp(ip);
+  if (!n) return false;
+  if (n === '127.0.0.1') return true;
+  if (n.startsWith('10.')) return true;
+  if (n.startsWith('192.168.')) return true;
+  if (n.startsWith('169.254.')) return true;
+  if (n.startsWith('172.')) {
+    const second = Number(n.split('.')[1] || '0');
+    return second >= 16 && second <= 31;
+  }
+  if (n === '::1') return true;
+  if (n.startsWith('fe80:') || n.startsWith('fd') || n.startsWith('fc')) return true;
+  return false;
+}
+
+export function listLanIps() {
+  const interfaces = os.networkInterfaces();
+  const ips = [];
+  Object.values(interfaces).forEach((entries) => {
+    (entries || []).forEach((entry) => {
+      if (entry.family !== 'IPv4' || entry.internal) return;
+      ips.push(entry.address);
+    });
+  });
+  return ips;
+}
+
+function sameSubnet24(a, b) {
+  const aa = a.split('.');
+  const bb = b.split('.');
+  if (aa.length !== 4 || bb.length !== 4) return false;
+  return aa[0] === bb[0] && aa[1] === bb[1] && aa[2] === bb[2];
+}
+
+function isAllowedRemoteIp(ip) {
+  const n = normalizeIp(ip);
+  if (n === '127.0.0.1') return true;
+  if (!isPrivateIp(n)) return false;
+  const localIps = listLanIps();
+  if (localIps.length === 0) return true;
+  if (n.includes(':')) return true;
+  return localIps.some((localIp) => sameSubnet24(localIp, n));
+}
+
+export function isWeakApiKey(value) {
+  return !value || value.length < 24 || value === 'chatagent-local-dev-key';
+}
+
+export function assertAuthorized(req, res, { API_KEY, PRIVATE_IP_ONLY, jsonFn }) {
+  const remote = normalizeIp(req.socket.remoteAddress || '');
+  if (PRIVATE_IP_ONLY && !isAllowedRemoteIp(remote)) {
+    jsonFn(res, 403, { error: 'forbidden_remote_ip', message: 'Request blocked: only local/private subnet clients are allowed.' });
+    return false;
+  }
+  const key = req.headers['x-agserver-key'];
+  if (key !== API_KEY) {
+    console.log(`[auth-fail] key=${key ? 'present' : 'missing'} from=${req.socket.remoteAddress} url=${req.url}`);
+    jsonFn(res, 401, { error: 'invalid_api_key', message: 'Missing or invalid API key.' });
+    return false;
+  }
+  return true;
+}