@aisystemresources/emdee 0.1.1 → 0.2.0

package/src/cli/auth.ts

@@ -0,0 +1,215 @@
+// SPRINT-091: CLI auth — PKCE loopback OAuth against emdee.tech.
+//
+// Follows RFC 8252 (OAuth 2.0 for native apps) + dynamic client registration
+// via /oauth/register (matches Codex + Claude Code patterns already in use).
+// Credentials land in ~/.config/emdee/credentials.json at 0600.
+//
+// Token has a 30-day TTL and there is no refresh grant on the server today,
+// so credentials are simple: access_token + client_id + host + saved_at. When
+// a token expires, the CLI surfaces `run 'emdee login'` — same UX as Codex.
+
+import { createHash, randomBytes } from "node:crypto";
+import { readFile, writeFile, mkdir, unlink, chmod, stat } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+
+const CREDS_DIR = path.join(os.homedir(), ".config", "emdee");
+const CREDS_PATH = path.join(CREDS_DIR, "credentials.json");
+export const DEFAULT_HOST = process.env.EMDEE_CLOUD_URL ?? "https://emdee.tech";
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+export interface Credentials {
+  access_token: string;
+  client_id: string;
+  host: string;
+  saved_at: number;
+}
+
+export class NeedsLoginError extends Error {
+  constructor(message = "Run `emdee login` first.") {
+    super(message);
+    this.name = "NeedsLoginError";
+  }
+}
+
+// PKCE helpers per RFC 7636.
+function base64url(buf: Buffer): string {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+
+// File I/O ------------------------------------------------------------------
+
+export async function loadCreds(): Promise<Credentials | null> {
+  try {
+    const text = await readFile(CREDS_PATH, "utf8");
+    return JSON.parse(text) as Credentials;
+  } catch {
+    return null;
+  }
+}
+
+async function saveCreds(creds: Credentials): Promise<void> {
+  await mkdir(CREDS_DIR, { recursive: true });
+  await writeFile(CREDS_PATH, JSON.stringify(creds, null, 2), "utf8");
+  await chmod(CREDS_PATH, 0o600);
+}
+
+export async function deleteCreds(): Promise<boolean> {
+  try {
+    await stat(CREDS_PATH);
+    await unlink(CREDS_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Browser open (best-effort per platform) -----------------------------------
+
+function openBrowser(url: string): void {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+  try {
+    spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
+  } catch {
+    // Best-effort — user can copy the URL if this fails.
+  }
+}
+
+// Dynamic client registration ----------------------------------------------
+
+async function registerClient(host: string, redirectUri: string): Promise<string> {
+  const res = await fetch(`${host}/oauth/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: `emdee-cli (${os.hostname()})`,
+      redirect_uris: [redirectUri],
+    }),
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`oauth register failed: ${res.status} ${body}`);
+  }
+  const body = (await res.json()) as { client_id: string };
+  return body.client_id;
+}
+
+// Main login flow ----------------------------------------------------------
+
+export async function login(host: string = DEFAULT_HOST): Promise<Credentials> {
+  const { verifier, challenge } = generatePkce();
+  const state = base64url(randomBytes(16));
+
+  // 1. Bind loopback server on an OS-assigned port so we know the redirect_uri
+  //    BEFORE we register the client + open the browser.
+  let capturedCode: string | null = null;
+  let capturedState: string | null = null;
+  const server: Server = createServer((req, res) => {
+    if (!req.url) return;
+    const u = new URL(req.url, "http://localhost");
+    if (u.pathname !== "/callback") {
+      res.statusCode = 404;
+      res.end();
+      return;
+    }
+    capturedCode = u.searchParams.get("code");
+    capturedState = u.searchParams.get("state");
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.end(
+      `<!doctype html><html><body style="font-family:system-ui;padding:2em;text-align:center"><h2>${capturedCode ? "Login complete" : "Login failed"}</h2><p>You can close this tab and return to the terminal.</p></body></html>`
+    );
+    // Give the browser a beat to render the response before shutting the socket.
+    setTimeout(() => server.close(), 100);
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const port = (server.address() as { port: number }).port;
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  // 2. Register a fresh client for this login (matches Codex's per-session pattern).
+  const clientId = await registerClient(host, redirectUri);
+
+  // 3. Open browser to authorize.
+  const authorizeUrl = new URL(`${host}/oauth/authorize`);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("client_id", clientId);
+  authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("scope", "mcp");
+  const authUrl = authorizeUrl.toString();
+  console.error(`Opening browser to authorize:\n${authUrl}\n`);
+  openBrowser(authUrl);
+
+  // 4. Wait for callback (or timeout).
+  const code = await new Promise<string>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error("Login timed out. Retry with `emdee login`."));
+    }, LOGIN_TIMEOUT_MS);
+    server.on("close", () => {
+      clearTimeout(timer);
+      if (!capturedCode) return reject(new Error("Login was cancelled."));
+      if (capturedState !== state) return reject(new Error("State mismatch — possible CSRF, aborted."));
+      resolve(capturedCode);
+    });
+  });
+
+  // 5. Exchange the code for an access token.
+  const tokenRes = await fetch(`${host}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: clientId,
+      code_verifier: verifier,
+    }).toString(),
+  });
+  if (!tokenRes.ok) {
+    const body = await tokenRes.text().catch(() => "");
+    throw new Error(`token exchange failed: ${tokenRes.status} ${body}`);
+  }
+  const tokenBody = (await tokenRes.json()) as { access_token: string };
+
+  const creds: Credentials = {
+    access_token: tokenBody.access_token,
+    client_id: clientId,
+    host,
+    saved_at: Date.now(),
+  };
+  await saveCreds(creds);
+  return creds;
+}
+
+// Whoami — hits the new /api/whoami endpoint --------------------------------
+
+export interface WhoamiPayload {
+  namespace: string;
+  email: string | null;
+}
+
+export async function whoami(creds: Credentials): Promise<WhoamiPayload> {
+  const res = await fetch(`${creds.host}/api/whoami`, {
+    headers: { Authorization: `Bearer ${creds.access_token}` },
+  });
+  if (res.status === 401) throw new NeedsLoginError();
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`whoami failed: ${res.status} ${body}`);
+  }
+  return (await res.json()) as WhoamiPayload;
+}

package/src/cli/read-commands.ts

@@ -1,17 +1,240 @@
+// SPRINT-091 chunks 1+3: CLI read verbs.
+//
+// Two flavours of reads:
+//   - Bytes-only: `list`, `drift-batch` — legacy verbs, print raw text
+//   - Structured: `get-doc`, `get-summary`, `get-neighbors`, `get-context`,
+//     `search`, `read-doc-section`, `list-summary-drift` — table-driven
+//     dispatcher entries. Each takes --remote (routes cloud), --format
+//     (text|json, default text where available), and prints unwrapped payload.
+//
+// Structured reads share the dispatcher with writes' shape so the surface
+// stays consistent, but their `formatOutput` collapses the MCP envelope by
+// default (users want the actual body, not JSON metadata).
+
 import path from "node:path";
-import { parseArgs } from "node:util";
+import { parseArgs, type ParseArgsConfig } from "node:util";
 import { buildIndex } from "../core/indexer";
+import { callTool, unwrapText } from "./remote-client";
+import { NeedsLoginError } from "./auth";
+import type { ToolContext } from "../lib/mcp/tools/types";
+import { getDoc } from "../lib/mcp/tools/get_doc";
+import { getSummary } from "../lib/mcp/tools/get_summary";
+import { getNeighbors } from "../lib/mcp/tools/get_neighbors";
+import { getContext } from "../lib/mcp/tools/get_context";
+import { search } from "../lib/mcp/tools/search";
+import { readDocSection } from "../lib/mcp/tools/read_doc_section";
+import { listDocs } from "../lib/mcp/tools/list_docs";
+import { listSummaryDrift } from "../lib/mcp/tools/list_summary_drift";
 
 const docsDir = path.resolve(process.env.EMDEE_DOCS ?? path.join(process.cwd(), "docs"));
 
+type ToolFn = (ctx: ToolContext, args: Record<string, unknown>) => Promise<unknown>;
+
+interface ReadVerb {
+  toolName: string;
+  toolFn: ToolFn;
+  parse: ParseArgsConfig["options"];
+  buildArgs: (values: Record<string, string | boolean | undefined>) => Record<string, unknown>;
+}
+
+const COMMON = {
+  remote: { type: "boolean" },
+  format: { type: "string" },
+  json: { type: "boolean" },
+} as const;
+
+function asString(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+function optionalString(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+const READ_VERBS: Record<string, ReadVerb> = {
+  "get-doc": {
+    toolName: "get_doc",
+    toolFn: getDoc as unknown as ToolFn,
+    parse: {
+      ...COMMON,
+      path: { type: "string" },
+      full: { type: "boolean" },
+      "expected-hash": { type: "string" },
+    },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = { path: asString(v.path) };
+      if (v.full) args.full = true;
+      if (v.format === "text") args.format = "text";
+      const expected = optionalString(v["expected-hash"]);
+      if (expected) args.expected_content_hash = expected;
+      return args;
+    },
+  },
+  "get-summary": {
+    toolName: "get_summary",
+    toolFn: getSummary as unknown as ToolFn,
+    parse: { ...COMMON, path: { type: "string" } },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = { path: asString(v.path) };
+      if (v.format === "text") args.format = "text";
+      return args;
+    },
+  },
+  "get-neighbors": {
+    toolName: "get_neighbors",
+    toolFn: getNeighbors as unknown as ToolFn,
+    parse: { ...COMMON, path: { type: "string" } },
+    buildArgs: (v) => ({ path: asString(v.path) }),
+  },
+  "get-context": {
+    toolName: "get_context",
+    toolFn: getContext as unknown as ToolFn,
+    parse: {
+      ...COMMON,
+      path: { type: "string" },
+      hops: { type: "string" },
+      "budget-tokens": { type: "string" },
+      "include-full": { type: "boolean" },
+      "include-associates": { type: "boolean" },
+      "expected-hash": { type: "string" },
+    },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = { path: asString(v.path) };
+      const hops = optionalString(v.hops);
+      if (hops) args.hops = Number(hops);
+      const budget = optionalString(v["budget-tokens"]);
+      if (budget) args.budget_tokens = Number(budget);
+      if (v["include-full"] === true) args.include_full = true;
+      if (v["include-associates"] === true) args.include_associates = true;
+      const expected = optionalString(v["expected-hash"]);
+      if (expected) args.expected_content_hash = expected;
+      return args;
+    },
+  },
+  search: {
+    toolName: "search",
+    toolFn: search as unknown as ToolFn,
+    parse: { ...COMMON, query: { type: "string" }, limit: { type: "string" } },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = { query: asString(v.query) };
+      const limit = optionalString(v.limit);
+      if (limit) args.limit = Number(limit);
+      return args;
+    },
+  },
+  "read-doc-section": {
+    toolName: "read_doc_section",
+    toolFn: readDocSection as unknown as ToolFn,
+    parse: {
+      ...COMMON,
+      path: { type: "string" },
+      "section-id": { type: "string" },
+      heading: { type: "string" },
+      "expected-hash": { type: "string" },
+    },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = { path: asString(v.path) };
+      const sid = optionalString(v["section-id"]);
+      if (sid) args.section_id = sid;
+      const heading = optionalString(v.heading);
+      if (heading) args.heading = heading;
+      const expected = optionalString(v["expected-hash"]);
+      if (expected) args.expected_content_hash = expected;
+      return args;
+    },
+  },
+  "list-docs": {
+    toolName: "list_docs",
+    toolFn: listDocs as unknown as ToolFn,
+    parse: { ...COMMON, prefix: { type: "string" } },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = {};
+      if (v.format === "text") args.format = "text";
+      return args;
+    },
+  },
+  "list-summary-drift": {
+    toolName: "list_summary_drift",
+    toolFn: listSummaryDrift as unknown as ToolFn,
+    parse: {
+      ...COMMON,
+      prefix: { type: "string" },
+      limit: { type: "string" },
+      offset: { type: "string" },
+    },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = {};
+      const prefix = optionalString(v.prefix);
+      if (prefix) args.prefix = prefix;
+      const limit = optionalString(v.limit);
+      if (limit) args.limit = Number(limit);
+      const offset = optionalString(v.offset);
+      if (offset) args.offset = Number(offset);
+      if (v.format === "text") args.format = "text";
+      return args;
+    },
+  },
+};
+
+function formatReadOutput(result: unknown, wantJson: boolean): string {
+  // Structured reads: default to unwrapped MCP text (already-parsed JSON or
+  // raw text); --json gives the parsed JSON representation.
+  const withContent = result as { content?: Array<{ type: string; text?: string }> };
+  const text = withContent.content?.[0]?.text;
+  if (typeof text !== "string") return JSON.stringify(result, null, 2);
+  if (wantJson) {
+    try {
+      return JSON.stringify(JSON.parse(text), null, 2);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+async function runStructuredRead(verbName: string, argv: string[]): Promise<void> {
+  const spec = READ_VERBS[verbName];
+  if (!spec) throw new Error(`unknown read verb: ${verbName}`);
+  const { values: raw } = parseArgs({ args: argv, options: spec.parse, strict: true });
+  const values = raw as unknown as Record<string, string | boolean | undefined>;
+  const args = spec.buildArgs(values);
+  const remote = Boolean(values.remote);
+  const wantJson = Boolean(values.json);
+
+  const result = remote
+    ? await callTool(spec.toolName, args)
+    : await spec.toolFn({ mode: "local", docsDir }, args);
+
+  const output = formatReadOutput(result, wantJson);
+  process.stdout.write(output + (output.endsWith("\n") ? "" : "\n"));
+}
+
+// -------- legacy simple verbs (list, drift-batch) ---------
+
 async function cmdList(argv: string[]): Promise<void> {
   const { values } = parseArgs({
     args: argv,
-    options: { prefix: { type: "string" } },
+    options: {
+      prefix: { type: "string" },
+      remote: { type: "boolean" },
+    },
     strict: true,
   });
-  const idx = await buildIndex(docsDir);
   const prefix = values.prefix ?? "";
+  if (values.remote) {
+    const args: Record<string, unknown> = { format: "text" };
+    if (prefix) args.prefix = prefix;
+    const result = await callTool("list_docs", args);
+    const text = unwrapText(result);
+    if (prefix) {
+      for (const line of text.split("\n")) {
+        if (line.startsWith(prefix)) process.stdout.write(line + "\n");
+      }
+    } else {
+      process.stdout.write(text + (text.endsWith("\n") ? "" : "\n"));
+    }
+    return;
+  }
+  const idx = await buildIndex(docsDir);
   for (const d of idx.docs) {
     if (!prefix || d.path.startsWith(prefix)) process.stdout.write(d.path + "\n");
   }
@@ -24,11 +247,20 @@ async function cmdDriftBatch(argv: string[]): Promise<void> {
       limit: { type: "string", default: "10" },
       offset: { type: "string", default: "0" },
       prefix: { type: "string" },
+      remote: { type: "boolean" },
     },
     strict: true,
   });
   const limit = Math.max(1, Number(values.limit) | 0);
   const offset = Math.max(0, Number(values.offset) | 0);
+  if (values.remote) {
+    const args: Record<string, unknown> = { limit, offset };
+    if (values.prefix) args.prefix = values.prefix;
+    const result = await callTool("list_summary_drift", args);
+    const text = unwrapText(result);
+    process.stdout.write(text + (text.endsWith("\n") ? "" : "\n"));
+    return;
+  }
   const idx = await buildIndex(docsDir);
   const filtered = idx.docs
     .filter((d) => !values.prefix || d.path.startsWith(values.prefix))
@@ -44,21 +276,19 @@ async function cmdDriftBatch(argv: string[]): Promise<void> {
 const [, , sub, ...rest] = process.argv;
 
 async function main(): Promise<void> {
-  switch (sub) {
-    case "list":
-      await cmdList(rest);
-      return;
-    case "drift-batch":
-      await cmdDriftBatch(rest);
-      return;
-    default:
-      process.stderr.write(`unknown subcommand: ${sub ?? "(none)"}\n`);
-      process.stderr.write(`usage: emdee <list|drift-batch> [--prefix P] [--limit N] [--offset K]\n`);
-      process.exit(1);
-  }
+  if (sub === "list") return cmdList(rest);
+  if (sub === "drift-batch") return cmdDriftBatch(rest);
+  if (sub && READ_VERBS[sub]) return runStructuredRead(sub, rest);
+  process.stderr.write(`unknown read subcommand: ${sub ?? "(none)"}\n`);
+  process.stderr.write(`verbs: list, drift-batch, ${Object.keys(READ_VERBS).join(", ")}\n`);
+  process.exit(1);
 }
 
 main().catch((err) => {
+  if (err instanceof NeedsLoginError) {
+    process.stderr.write(`${err.message}\n`);
+    process.exit(1);
+  }
   process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
   process.exit(1);
 });

package/src/cli/remote-client.ts

@@ -0,0 +1,74 @@
+// SPRINT-091: thin wrapper around POST /api/mcp for CLI --remote commands.
+//
+// Every call routes through the same JSON-RPC surface claude.ai uses, so we
+// inherit auth + rate limits + logging for free. The MCP SDK's tool response
+// envelope (`content: [{type: "text", text: "..."}]`) unwraps here — CLI
+// verbs receive the already-parsed JSON so they can print it plain.
+
+import { loadCreds, NeedsLoginError, type Credentials } from "./auth";
+import { randomUUID } from "node:crypto";
+
+export interface RemoteResult {
+  content?: Array<{ type: string; text?: string }>;
+  isError?: boolean;
+  [k: string]: unknown;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string;
+  result?: RemoteResult;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+/**
+ * Invoke an MCP tool over HTTP against the user's authenticated vault.
+ * Throws NeedsLoginError if no creds or token is rejected.
+ */
+export async function callTool(
+  name: string,
+  args: Record<string, unknown>,
+  credsOverride?: Credentials,
+): Promise<RemoteResult> {
+  const creds = credsOverride ?? (await loadCreds());
+  if (!creds) throw new NeedsLoginError();
+
+  const res = await fetch(`${creds.host}/api/mcp`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Accept": "application/json, text/event-stream",
+      Authorization: `Bearer ${creds.access_token}`,
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: randomUUID(),
+      method: "tools/call",
+      params: { name, arguments: args },
+    }),
+  });
+
+  if (res.status === 401) throw new NeedsLoginError("Access token was rejected. Run `emdee login` again.");
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`remote call failed: ${res.status} ${body}`);
+  }
+
+  const body = (await res.json()) as JsonRpcResponse;
+  if (body.error) throw new Error(`remote tool error: ${body.error.message}`);
+  if (!body.result) throw new Error("remote call returned no result");
+  return body.result;
+}
+
+/**
+ * Convenience: unwrap the MCP text envelope back to a string. Tools that
+ * return JSON encode it inside `content[0].text`; tools that return plain
+ * text put it there directly. Callers decide whether to JSON.parse.
+ */
+export function unwrapText(result: RemoteResult): string {
+  const first = result.content?.[0];
+  if (!first || first.type !== "text" || typeof first.text !== "string") {
+    return JSON.stringify(result);
+  }
+  return first.text;
+}

package/src/cli/skills-install.ts

@@ -0,0 +1,54 @@
+// SPRINT-094: install the EMDEE skills bundle into a Claude Code skills dir.
+//
+// Copies every .md file from the installed package's skills/ folder into
+// the target directory (default ~/.claude/skills/). Idempotent — overwrites
+// existing files. Users re-run after upgrading the package to get the
+// latest skill content.
+
+import { readdir, mkdir, copyFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_TARGET = path.join(os.homedir(), ".claude", "skills");
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const SKILLS_SRC = path.join(PKG_ROOT, "skills");
+
+async function main(): Promise<void> {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      dir: { type: "string" },
+    },
+    strict: true,
+  });
+
+  const target = values.dir ? path.resolve(values.dir) : DEFAULT_TARGET;
+  await mkdir(target, { recursive: true });
+
+  let files: string[];
+  try {
+    files = (await readdir(SKILLS_SRC)).filter((f) => f.endsWith(".md"));
+  } catch {
+    process.stderr.write(`emdee skills install: skills/ folder not found at ${SKILLS_SRC}. Reinstall the package.\n`);
+    process.exit(1);
+  }
+
+  if (files.length === 0) {
+    process.stderr.write(`emdee skills install: no .md files in ${SKILLS_SRC}.\n`);
+    process.exit(1);
+  }
+
+  for (const f of files) {
+    await copyFile(path.join(SKILLS_SRC, f), path.join(target, f));
+    process.stdout.write(`  ${f}\n`);
+  }
+  process.stdout.write(`\nInstalled ${files.length} skills to ${target}.\n`);
+  process.stdout.write("Restart Claude Code (or reload skills) to pick them up.\n");
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});