@aisystemresources/emdee 0.1.2 → 0.2.0

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);
+});