engrm 0.1.0

package/src/provisioning/provision.ts

@@ -0,0 +1,94 @@
+/**
+ * Provisioning: exchange a cmt_ token (or OAuth code) for cvk_ API credentials.
+ *
+ * Calls POST /v1/mem/provision on Candengo Vector.
+ * Returns everything needed to write ~/.engrm/settings.json.
+ */
+
+export const DEFAULT_CANDENGO_URL = "https://www.candengo.com";
+
+export interface ProvisionRequest {
+  /** cmt_ provisioning token from web signup */
+  token?: string;
+  /** OAuth authorization code from browser flow */
+  code?: string;
+  /** Device name for identification (e.g. "MacBook Pro") */
+  device_name?: string;
+}
+
+export interface TeamInfo {
+  id: string;
+  name: string;
+  namespace: string;
+}
+
+export interface ProvisionResponse {
+  api_key: string; // cvk_...
+  site_id: string;
+  namespace: string;
+  user_id: string;
+  user_email: string;
+  teams: TeamInfo[];
+}
+
+export class ProvisionError extends Error {
+  constructor(
+    readonly status: number,
+    readonly detail: string
+  ) {
+    super(detail);
+    this.name = "ProvisionError";
+  }
+}
+
+/**
+ * Exchange a provisioning token or OAuth code for API credentials.
+ */
+export async function provision(
+  baseUrl: string,
+  request: ProvisionRequest
+): Promise<ProvisionResponse> {
+  const url = `${baseUrl.replace(/\/$/, "")}/v1/mem/provision`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request),
+  });
+
+  if (!response.ok) {
+    let detail: string;
+    try {
+      const body = (await response.json()) as { detail?: string };
+      detail = body.detail ?? `HTTP ${response.status}`;
+    } catch {
+      detail = `HTTP ${response.status}`;
+    }
+
+    if (response.status === 401 || response.status === 403) {
+      throw new ProvisionError(
+        response.status,
+        "Invalid or expired provisioning token"
+      );
+    }
+    if (response.status === 409) {
+      throw new ProvisionError(
+        response.status,
+        "Token has already been used"
+      );
+    }
+    throw new ProvisionError(response.status, detail);
+  }
+
+  const data = (await response.json()) as ProvisionResponse;
+
+  // Validate response
+  if (!data.api_key?.startsWith("cvk_")) {
+    throw new ProvisionError(0, "Server returned invalid API key format");
+  }
+  if (!data.site_id || !data.namespace || !data.user_id) {
+    throw new ProvisionError(0, "Server returned incomplete credentials");
+  }
+
+  return data;
+}

package/src/register.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+
+// We test the internal logic by importing helpers and mocking the file paths.
+// Since register.ts uses hardcoded paths (~/.claude.json, ~/.claude/settings.json),
+// we test the JSON merge logic directly.
+
+describe("register: JSON merge logic", () => {
+  let tmpDir: string;
+  let claudeJson: string;
+  let claudeSettings: string;
+
+  beforeEach(() => {
+    tmpDir = join(tmpdir(), `engrm-register-test-${randomBytes(4).toString("hex")}`);
+    mkdirSync(tmpDir, { recursive: true });
+    mkdirSync(join(tmpDir, ".claude"), { recursive: true });
+    claudeJson = join(tmpDir, ".claude.json");
+    claudeSettings = join(tmpDir, ".claude", "settings.json");
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("creates claude.json from scratch with MCP server", () => {
+    // Simulate what registerMcpServer does
+    const config: Record<string, unknown> = {};
+    const servers: Record<string, unknown> = {};
+    servers["engrm"] = {
+      type: "stdio",
+      command: "/usr/local/bin/bun",
+      args: ["run", "/path/to/server.ts"],
+    };
+    config["mcpServers"] = servers;
+
+    writeFileSync(claudeJson, JSON.stringify(config, null, 2));
+    const result = JSON.parse(readFileSync(claudeJson, "utf-8"));
+
+    expect(result.mcpServers.engrm).toBeDefined();
+    expect(result.mcpServers.engrm.command).toBe("/usr/local/bin/bun");
+    expect(result.mcpServers.engrm.type).toBe("stdio");
+  });
+
+  it("preserves existing MCP servers when adding engrm", () => {
+    const existing = {
+      numStartups: 5,
+      mcpServers: {
+        "other-server": {
+          type: "stdio",
+          command: "node",
+          args: ["other.js"],
+        },
+      },
+    };
+    writeFileSync(claudeJson, JSON.stringify(existing));
+
+    // Read, merge, write
+    const config = JSON.parse(readFileSync(claudeJson, "utf-8"));
+    const servers = config.mcpServers ?? {};
+    servers["engrm"] = { type: "stdio", command: "bun", args: ["run", "server.ts"] };
+    config.mcpServers = servers;
+    writeFileSync(claudeJson, JSON.stringify(config, null, 2));
+
+    const result = JSON.parse(readFileSync(claudeJson, "utf-8"));
+    expect(result.numStartups).toBe(5);
+    expect(result.mcpServers["other-server"]).toBeDefined();
+    expect(result.mcpServers.engrm).toBeDefined();
+  });
+
+  it("replaces existing engrm MCP config with new paths", () => {
+    const existing = {
+      mcpServers: {
+        engrm: { type: "stdio", command: "bun", args: ["run", "/old/path/server.ts"] },
+      },
+    };
+    writeFileSync(claudeJson, JSON.stringify(existing));
+
+    const config = JSON.parse(readFileSync(claudeJson, "utf-8"));
+    config.mcpServers.engrm = { type: "stdio", command: "bun", args: ["run", "/new/path/server.ts"] };
+    writeFileSync(claudeJson, JSON.stringify(config, null, 2));
+
+    const result = JSON.parse(readFileSync(claudeJson, "utf-8"));
+    expect(result.mcpServers.engrm.args[1]).toBe("/new/path/server.ts");
+  });
+
+  it("creates hooks config from scratch", () => {
+    const settings: Record<string, unknown> = {};
+    settings["hooks"] = {
+      SessionStart: [
+        { hooks: [{ type: "command", command: "bun run /path/hooks/session-start.ts" }] },
+      ],
+      PostToolUse: [
+        {
+          matcher: "Edit|Write|Bash",
+          hooks: [{ type: "command", command: "bun run /path/hooks/post-tool-use.ts" }],
+        },
+      ],
+      Stop: [
+        { hooks: [{ type: "command", command: "bun run /path/hooks/stop.ts" }] },
+      ],
+    };
+    writeFileSync(claudeSettings, JSON.stringify(settings, null, 2));
+
+    const result = JSON.parse(readFileSync(claudeSettings, "utf-8"));
+    expect(result.hooks.SessionStart).toHaveLength(1);
+    expect(result.hooks.PostToolUse).toHaveLength(1);
+    expect(result.hooks.Stop).toHaveLength(1);
+  });
+
+  it("preserves non-engrm hooks when adding engrm hooks", () => {
+    const existing = {
+      hooks: {
+        PostToolUse: [
+          {
+            matcher: "Bash",
+            hooks: [{ type: "command", command: "/path/to/other-hook.sh" }],
+          },
+        ],
+      },
+    };
+    writeFileSync(claudeSettings, JSON.stringify(existing));
+
+    const settings = JSON.parse(readFileSync(claudeSettings, "utf-8"));
+    const hooks = settings.hooks ?? {};
+
+    // Add engrm hooks — keep others
+    const postToolUse = hooks.PostToolUse ?? [];
+    const otherHooks = postToolUse.filter(
+      (e: { hooks: { command: string }[] }) =>
+        !e.hooks?.some((h: { command: string }) => h.command.includes("engrm"))
+    );
+    hooks.PostToolUse = [
+      ...otherHooks,
+      {
+        matcher: "Edit|Write|Bash",
+        hooks: [{ type: "command", command: "bun run /path/engrm/hooks/post-tool-use.ts" }],
+      },
+    ];
+    settings.hooks = hooks;
+    writeFileSync(claudeSettings, JSON.stringify(settings, null, 2));
+
+    const result = JSON.parse(readFileSync(claudeSettings, "utf-8"));
+    expect(result.hooks.PostToolUse).toHaveLength(2);
+    expect(result.hooks.PostToolUse[0].hooks[0].command).toBe("/path/to/other-hook.sh");
+    expect(result.hooks.PostToolUse[1].hooks[0].command).toContain("engrm");
+  });
+
+  it("preserves other settings fields", () => {
+    const existing = {
+      skipDangerousModePermissionPrompt: true,
+      attribution: { commit: "", pr: "" },
+    };
+    writeFileSync(claudeSettings, JSON.stringify(existing));
+
+    const settings = JSON.parse(readFileSync(claudeSettings, "utf-8"));
+    settings.hooks = { Stop: [{ hooks: [{ type: "command", command: "test" }] }] };
+    writeFileSync(claudeSettings, JSON.stringify(settings, null, 2));
+
+    const result = JSON.parse(readFileSync(claudeSettings, "utf-8"));
+    expect(result.skipDangerousModePermissionPrompt).toBe(true);
+    expect(result.attribution).toBeDefined();
+    expect(result.hooks.Stop).toHaveLength(1);
+  });
+});

package/src/register.ts

@@ -0,0 +1,178 @@
+/**
+ * Auto-register Engrm MCP server + hooks in Claude Code config.
+ *
+ * - MCP server → ~/.claude.json (mcpServers.engrm)
+ * - Hooks → ~/.claude/settings.json (hooks.SessionStart, PostToolUse, Stop)
+ *
+ * Merges into existing config — never overwrites other servers or hooks.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+// --- Paths ---
+
+const CLAUDE_JSON = join(homedir(), ".claude.json");
+const CLAUDE_SETTINGS = join(homedir(), ".claude", "settings.json");
+
+/**
+ * Resolve the absolute path to the bun binary.
+ * Checks common locations; falls back to "bun" (assumes PATH).
+ */
+function findBun(): string {
+  const candidates = [
+    join(homedir(), ".bun", "bin", "bun"),
+    "/usr/local/bin/bun",
+    "/opt/homebrew/bin/bun",
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  // If running under bun, process.execPath is the bun binary
+  if (process.execPath && process.execPath.endsWith("bun")) {
+    return process.execPath;
+  }
+  return "bun";
+}
+
+/**
+ * Resolve the package root directory (where src/ and hooks/ live).
+ * Works both in dev (running from checkout) and when installed via npx.
+ */
+function findPackageRoot(): string {
+  // __dirname equivalent for ESM: import.meta.dir (Bun) or derive from import.meta.url
+  // This file is at src/register.ts, so package root is one level up
+  const thisDir =
+    typeof import.meta.dir === "string"
+      ? import.meta.dir
+      : dirname(new URL(import.meta.url).pathname);
+  return join(thisDir, "..");
+}
+
+// --- JSON helpers ---
+
+function readJsonFile(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // Corrupt or empty file — start fresh
+  }
+  return {};
+}
+
+function writeJsonFile(path: string, data: Record<string, unknown>): void {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+// --- MCP registration ---
+
+export function registerMcpServer(): { path: string; added: boolean } {
+  const bun = findBun();
+  const root = findPackageRoot();
+  const serverPath = join(root, "src", "server.ts");
+
+  const config = readJsonFile(CLAUDE_JSON);
+  const servers = (config["mcpServers"] ?? {}) as Record<string, unknown>;
+
+  servers["engrm"] = {
+    type: "stdio",
+    command: bun,
+    args: ["run", serverPath],
+  };
+
+  config["mcpServers"] = servers;
+  writeJsonFile(CLAUDE_JSON, config);
+
+  return { path: CLAUDE_JSON, added: true };
+}
+
+// --- Hooks registration ---
+
+interface HookEntry {
+  matcher?: string;
+  hooks: { type: string; command: string }[];
+}
+
+export function registerHooks(): { path: string; added: boolean } {
+  const bun = findBun();
+  const root = findPackageRoot();
+
+  const sessionStartCmd = `${bun} run ${join(root, "hooks", "session-start.ts")}`;
+  const postToolUseCmd = `${bun} run ${join(root, "hooks", "post-tool-use.ts")}`;
+  const stopCmd = `${bun} run ${join(root, "hooks", "stop.ts")}`;
+
+  const settings = readJsonFile(CLAUDE_SETTINGS);
+  const hooks = (settings["hooks"] ?? {}) as Record<string, HookEntry[]>;
+
+  // Replace any existing engrm hooks, preserve others
+  hooks["SessionStart"] = replaceEngrmHook(
+    hooks["SessionStart"],
+    { hooks: [{ type: "command", command: sessionStartCmd }] },
+    "session-start.ts"
+  );
+
+  hooks["PostToolUse"] = replaceEngrmHook(
+    hooks["PostToolUse"],
+    {
+      matcher: "Edit|Write|Bash",
+      hooks: [{ type: "command", command: postToolUseCmd }],
+    },
+    "post-tool-use.ts"
+  );
+
+  hooks["Stop"] = replaceEngrmHook(
+    hooks["Stop"],
+    { hooks: [{ type: "command", command: stopCmd }] },
+    "stop.ts"
+  );
+
+  settings["hooks"] = hooks;
+  writeJsonFile(CLAUDE_SETTINGS, settings);
+
+  return { path: CLAUDE_SETTINGS, added: true };
+}
+
+/**
+ * Replace any existing engrm hook entry in the array, or append.
+ * Identifies engrm hooks by checking if the command contains our hook filename.
+ */
+function replaceEngrmHook(
+  existing: HookEntry[] | undefined,
+  newEntry: HookEntry,
+  hookFilename: string
+): HookEntry[] {
+  if (!existing || !Array.isArray(existing)) return [newEntry];
+
+  const isEngrmHook = (entry: HookEntry): boolean =>
+    entry.hooks?.some(
+      (h) =>
+        h.command?.includes("engrm") || h.command?.includes(hookFilename)
+    ) ?? false;
+
+  // Remove old engrm entries, add new one
+  const others = existing.filter((e) => !isEngrmHook(e));
+  return [...others, newEntry];
+}
+
+/**
+ * Register both MCP server and hooks. Returns summary for CLI output.
+ */
+export function registerAll(): {
+  mcp: { path: string; added: boolean };
+  hooks: { path: string; added: boolean };
+} {
+  return {
+    mcp: registerMcpServer(),
+    hooks: registerHooks(),
+  };
+}