@hawkeye-xb.com/imprint-cli 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @hawkeye-xb.com/imprint-cli
+
+Installer for [Imprint](https://imprint.hawkeye-xb.com) — a long-term memory layer for AI coding tools (Claude Code, Cursor, Codex). Runs an OAuth flow in your browser, then writes the `imprint` MCP server entry into the target tool's settings file.
+
+## Quick install
+
+Tell your AI agent (or run yourself):
+
+```bash
+npx --yes @hawkeye-xb.com/imprint-cli install
+```
+
+Defaults to Claude Code (`~/.claude/settings.json`). For Cursor or Codex:
+
+```bash
+npx --yes @hawkeye-xb.com/imprint-cli install --tool cursor
+npx --yes @hawkeye-xb.com/imprint-cli install --tool codex
+```
+
+A browser opens to authorize via Logto. The CLI captures the issued Personal API Token, writes the MCP server entry without disturbing your other settings, and exits. Restart the AI tool to pick up the new server.
+
+## Commands
+
+| | |
+|---|---|
+| `imprint` | Alias for `imprint login`. |
+| `imprint login` | OAuth via browser; saves token to `~/.imprint/credentials.json` (mode `0600`). |
+| `imprint install [--tool <id>]` | Log in (if needed) and write MCP config. Tools: `claude-code` (default), `cursor`, `codex`. |
+| `imprint logout` | Forget the saved token. |
+| `imprint whoami` | Print where the credentials are stored. |
+
+## What it writes
+
+| Tool | File | Format |
+|---|---|---|
+| `claude-code` | `~/.claude/settings.json` | JSON; merges `mcpServers.imprint` without touching other entries |
+| `cursor` | `~/.cursor/mcp.json` | Same JSON merge |
+| `codex` | `~/.codex/config.toml` | TOML block bracketed by `# === imprint:begin / end ===` markers, idempotent on re-install |
+
+## Environment overrides
+
+| Variable | Purpose |
+|---|---|
+| `IMPRINT_DASHBOARD_URL` | Override the dashboard origin (default: `https://imprint.hawkeye-xb.com`). |
+| `IMPRINT_API_BASE` | Override the worker API base URL. Defaults to whatever the dashboard's `/.well-known/imprint.json` reports. |
+
+## License
+
+Elastic License 2.0 (ELv2). See repo root.

package/dist/cli.js

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/config.ts
+var config_exports = {};
+__export(config_exports, {
+  DASHBOARD_URL: () => DASHBOARD_URL,
+  credentialsPath: () => credentialsPath,
+  readCredentials: () => readCredentials,
+  removeCredentials: () => removeCredentials,
+  resolveApiBase: () => resolveApiBase,
+  writeCredentials: () => writeCredentials
+});
+import os from "os";
+import path from "path";
+import fs from "fs/promises";
+async function resolveApiBase() {
+  if (_resolvedApiBase) return _resolvedApiBase;
+  const envOverride = process.env.IMPRINT_API_BASE?.replace(/\/+$/, "");
+  if (envOverride) {
+    _resolvedApiBase = envOverride;
+    return envOverride;
+  }
+  try {
+    const url = new URL("/.well-known/imprint.json", DASHBOARD_URL + "/");
+    const res = await fetch(url, {
+      headers: { Accept: "application/json" }
+    });
+    if (res.ok) {
+      const parsed = await res.json();
+      if (typeof parsed.api_base === "string" && parsed.api_base.length > 0) {
+        _resolvedApiBase = parsed.api_base.replace(/\/+$/, "");
+        return _resolvedApiBase;
+      }
+    }
+  } catch {
+  }
+  _resolvedApiBase = HARDCODED_API_BASE_FALLBACK;
+  return _resolvedApiBase;
+}
+function credentialsPath() {
+  return CRED_FILE;
+}
+async function readCredentials() {
+  try {
+    const raw = await fs.readFile(CRED_FILE, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.token !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function writeCredentials(token, apiBase) {
+  await fs.mkdir(CRED_DIR, { recursive: true, mode: 448 });
+  const payload = {
+    token,
+    savedAt: Math.floor(Date.now() / 1e3),
+    endpoint: apiBase
+  };
+  await fs.writeFile(CRED_FILE, JSON.stringify(payload, null, 2), {
+    mode: 384
+  });
+}
+async function removeCredentials() {
+  await fs.rm(CRED_FILE, { force: true });
+}
+var DASHBOARD_URL, HARDCODED_API_BASE_FALLBACK, _resolvedApiBase, CRED_DIR, CRED_FILE;
+var init_config = __esm({
+  "src/config.ts"() {
+    "use strict";
+    DASHBOARD_URL = process.env.IMPRINT_DASHBOARD_URL?.replace(/\/+$/, "") ?? "https://imprint.hawkeye-xb.com";
+    HARDCODED_API_BASE_FALLBACK = "https://imprint-api.hawkeye-xb.com";
+    _resolvedApiBase = null;
+    CRED_DIR = path.join(os.homedir(), ".imprint");
+    CRED_FILE = path.join(CRED_DIR, "credentials.json");
+  }
+});
+
+// src/login.ts
+init_config();
+import http from "http";
+import os2 from "os";
+import crypto from "crypto";
+
+// src/utils.ts
+import { exec } from "child_process";
+import net from "net";
+async function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (addr && typeof addr === "object") {
+        const port = addr.port;
+        server.close(() => resolve(port));
+      } else {
+        reject(new Error("could not determine free port"));
+      }
+    });
+  });
+}
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? `open "${url}"` : platform === "win32" ? `start "" "${url}"` : `xdg-open "${url}"`;
+  exec(cmd, (err) => {
+    if (err) {
+    }
+  });
+}
+var SUCCESS_HTML = `<!doctype html>
+<html><head><meta charset="utf-8"><title>Imprint \u2014 authorized</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+         display: flex; align-items: center; justify-content: center;
+         height: 100vh; margin: 0; background: #f7f9fa; color: #1a1a1a; }
+  .card { background: white; padding: 2rem 3rem; border-radius: 8px;
+          border: 1px solid #e5e7eb; text-align: center; }
+  h1 { color: #007c8b; margin: 0 0 0.5rem; }
+  p { color: #666; margin: 0; }
+</style>
+<script>history.replaceState({}, "", "/")</script></head>
+<body><div class="card">
+  <h1>\u2713 Authorized</h1>
+  <p>You can close this tab. Return to your terminal.</p>
+</div></body></html>`;
+var ERROR_HTML = (msg) => `<!doctype html>
+<html><head><meta charset="utf-8"><title>Imprint \u2014 error</title></head>
+<body style="font-family: sans-serif; padding: 2rem">
+  <h1 style="color: #b91c1c">Authorization failed</h1>
+  <pre>${escapeHtml(msg)}</pre>
+</body></html>`;
+function escapeHtml(s) {
+  return s.replace(
+    /[&<>"']/g,
+    (c) => ({
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#39;"
+    })[c]
+  );
+}
+var successPage = SUCCESS_HTML;
+var errorPage = ERROR_HTML;
+
+// src/login.ts
+var TOKEN_PREFIX = "imp_";
+async function login() {
+  const port = await findFreePort();
+  const state = crypto.randomBytes(16).toString("hex");
+  const name = `${process.env.USER ?? "user"}@${os2.hostname()}`;
+  const tokenPromise = waitForCallback(port, state);
+  const url = new URL("/cli-login", DASHBOARD_URL);
+  url.searchParams.set("port", String(port));
+  url.searchParams.set("state", state);
+  url.searchParams.set("name", name);
+  console.log("\u2192 Opening browser to authorize\u2026");
+  console.log(`  If it doesn't open, visit:
+  ${url.toString()}
+`);
+  openBrowser(url.toString());
+  const token = await tokenPromise;
+  const apiBase = await resolveApiBase();
+  await writeCredentials(token, apiBase);
+  console.log(`\u2713 Logged in. Token saved.`);
+  return token;
+}
+function waitForCallback(port, expectedState) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(
+      () => {
+        server.close();
+        reject(new Error("timed out waiting for browser callback (5 min)"));
+      },
+      5 * 60 * 1e3
+    );
+    const server = http.createServer((req, res) => {
+      if (!req.url) return;
+      const host = req.headers.host ?? "";
+      if (!host.startsWith("127.0.0.1") && !host.startsWith("localhost")) {
+        res.writeHead(400);
+        res.end();
+        return;
+      }
+      const requrl = new URL(req.url, `http://localhost:${port}`);
+      if (requrl.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      const token = requrl.searchParams.get("token");
+      const state = requrl.searchParams.get("state");
+      const error = requrl.searchParams.get("error");
+      if (error) {
+        respond(res, 400, errorPage(error));
+        finish(new Error(`dashboard reported: ${error}`));
+        return;
+      }
+      if (state !== expectedState) {
+        respond(res, 400, errorPage("state mismatch \u2014 possible CSRF"));
+        finish(new Error("state mismatch in callback"));
+        return;
+      }
+      if (!token || !token.startsWith(TOKEN_PREFIX)) {
+        respond(res, 400, errorPage("missing or malformed token"));
+        finish(new Error("missing token in callback"));
+        return;
+      }
+      respond(res, 200, successPage);
+      finish(null, token);
+    });
+    server.on("error", (err) => finish(err));
+    server.listen(port, "127.0.0.1");
+    function finish(err, token) {
+      clearTimeout(timeout);
+      server.close();
+      if (err) reject(err);
+      else if (token) resolve(token);
+    }
+    function respond(res, status, body) {
+      res.writeHead(status, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(body);
+    }
+  });
+}
+
+// src/install.ts
+init_config();
+import os3 from "os";
+import path2 from "path";
+import fs2 from "fs/promises";
+var SUPPORTED = ["claude-code", "cursor", "codex"];
+async function install(args) {
+  const tool = parseTool(args);
+  let creds = await readCredentials();
+  if (!creds) {
+    console.log("No credentials found \u2014 running login first.\n");
+    await login();
+    creds = await readCredentials();
+    if (!creds) throw new Error("login completed but credentials still missing");
+  }
+  const apiBase = await resolveApiBase();
+  switch (tool) {
+    case "claude-code":
+      await installClaudeCode(creds.token, apiBase);
+      break;
+    case "cursor":
+      await installCursor(creds.token, apiBase);
+      break;
+    case "codex":
+      await installCodex(creds.token, apiBase);
+      break;
+  }
+}
+function parseTool(args) {
+  const idx = args.indexOf("--tool");
+  if (idx >= 0) {
+    const v = args[idx + 1];
+    if (!v) throw new Error("--tool requires a value");
+    if (!SUPPORTED.includes(v)) {
+      throw new Error(
+        `unsupported tool: ${v}. Supported: ${SUPPORTED.join(", ")}`
+      );
+    }
+    return v;
+  }
+  return "claude-code";
+}
+async function mergeJsonMcpServer(filePath, serverName, serverConfig) {
+  await fs2.mkdir(path2.dirname(filePath), { recursive: true });
+  let config = {};
+  try {
+    const raw = await fs2.readFile(filePath, "utf8");
+    if (raw.trim().length > 0) config = JSON.parse(raw);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+    throw new Error(`${filePath} is not a JSON object`);
+  }
+  const mcpServers = config.mcpServers ?? {};
+  mcpServers[serverName] = serverConfig;
+  config.mcpServers = mcpServers;
+  await fs2.writeFile(filePath, JSON.stringify(config, null, 2) + "\n");
+}
+async function installClaudeCode(token, apiBase) {
+  const settingsPath = path2.join(os3.homedir(), ".claude", "settings.json");
+  await mergeJsonMcpServer(settingsPath, "imprint", {
+    type: "http",
+    url: `${apiBase}/mcp`,
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  console.log(`\u2713 Claude Code: wrote mcpServers.imprint to ${settingsPath}`);
+  console.log(`  Restart Claude Code to pick up the new server.`);
+}
+async function installCursor(token, apiBase) {
+  const settingsPath = path2.join(os3.homedir(), ".cursor", "mcp.json");
+  await mergeJsonMcpServer(settingsPath, "imprint", {
+    url: `${apiBase}/mcp`,
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  console.log(`\u2713 Cursor: wrote mcpServers.imprint to ${settingsPath}`);
+  console.log(`  Reload Cursor (or its MCP server list in Settings) to pick it up.`);
+}
+var CODEX_MARK_BEGIN = "# === imprint:begin (managed \u2014 do not edit between markers) ===";
+var CODEX_MARK_END = "# === imprint:end ===";
+async function installCodex(token, apiBase) {
+  const configPath = path2.join(os3.homedir(), ".codex", "config.toml");
+  await fs2.mkdir(path2.dirname(configPath), { recursive: true });
+  let existing = "";
+  try {
+    existing = await fs2.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  const block = [
+    CODEX_MARK_BEGIN,
+    "[mcp_servers.imprint]",
+    `url = "${apiBase}/mcp"`,
+    "",
+    "[mcp_servers.imprint.headers]",
+    `Authorization = "Bearer ${token}"`,
+    CODEX_MARK_END
+  ].join("\n");
+  const startIdx = existing.indexOf(CODEX_MARK_BEGIN);
+  const endIdx = existing.indexOf(CODEX_MARK_END);
+  let next;
+  if (startIdx >= 0 && endIdx > startIdx) {
+    const before = existing.slice(0, startIdx).replace(/\s+$/, "");
+    const after = existing.slice(endIdx + CODEX_MARK_END.length).replace(/^\s+/, "");
+    next = [before, block, after].filter((s) => s.length > 0).join("\n\n");
+  } else if (existing.trim().length === 0) {
+    next = block;
+  } else {
+    next = existing.replace(/\s+$/, "") + "\n\n" + block;
+  }
+  if (!next.endsWith("\n")) next += "\n";
+  await fs2.writeFile(configPath, next);
+  console.log(`\u2713 Codex: wrote [mcp_servers.imprint] to ${configPath}`);
+  console.log(`  Restart Codex CLI to pick it up.`);
+  console.log(
+    `  Note: Codex's HTTP MCP transport support varies by version \u2014 if it doesn't appear, please report and we'll add a stdio bridge.`
+  );
+}
+
+// src/cli.ts
+var HELP = `imprint \u2014 memory layer for AI coding tools
+
+Usage:
+  imprint                       Log in (alias for "imprint login").
+  imprint login                 Authenticate via browser; saves token to ~/.imprint/credentials.json.
+  imprint install [--tool ID]   Log in (if needed) and write MCP config for the target tool.
+                                Tools: claude-code (default), cursor, codex.
+  imprint logout                Forget the saved token.
+  imprint whoami                Print where the credentials are stored.
+
+Environment overrides (for development):
+  IMPRINT_DASHBOARD_URL         Dashboard origin (default: https://imprint.hawkeye-xb.com).
+  IMPRINT_API_BASE              Worker base URL    (default: https://imprint-api.hawkeye-xb.com).
+`;
+async function main() {
+  const [, , raw, ...rest] = process.argv;
+  const cmd = raw ?? "login";
+  switch (cmd) {
+    case "login":
+      await login();
+      break;
+    case "install":
+      await install(rest);
+      break;
+    case "logout":
+      (await Promise.resolve().then(() => (init_config(), config_exports))).removeCredentials();
+      console.log("\u2713 logged out");
+      break;
+    case "whoami":
+      console.log((await Promise.resolve().then(() => (init_config(), config_exports))).credentialsPath());
+      break;
+    case "-h":
+    case "--help":
+    case "help":
+      console.log(HELP);
+      break;
+    default:
+      console.error(`Unknown command: ${cmd}
+`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(`Error: ${err.message ?? err}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hawkeye-xb.com/imprint-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Imprint CLI — long-term memory for AI coding tools (Claude Code, Cursor, Codex). Installs the imprint MCP server into your tool's settings file via a browser OAuth flow.",
+  "license": "Elastic-2.0",
+  "homepage": "https://imprint.hawkeye-xb.com",
+  "bugs": {
+    "url": "https://imprint.hawkeye-xb.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hawkeye-xb/imprint.git",
+    "directory": "apps/cli"
+  },
+  "keywords": [
+    "imprint",
+    "mcp",
+    "memory",
+    "ai",
+    "claude-code",
+    "cursor",
+    "codex"
+  ],
+  "bin": {
+    "imprint": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "pnpm build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  }
+}