echoctl 0.1.0

package/scripts/lib/infra/markdown-store.js

@@ -0,0 +1,161 @@
+const fs = require("fs");
+const path = require("path");
+const matter = require("gray-matter");
+
+const _articleCache = new Map();
+
+function clearArticleCache(dir) {
+  if (dir) _articleCache.delete(dir);
+  else _articleCache.clear();
+}
+
+function listMarkdownFiles(dir) {
+  const files = [];
+  function walk(d) {
+    if (!fs.existsSync(d)) return;
+    for (const name of fs.readdirSync(d)) {
+      const full = path.join(d, name);
+      if (name.startsWith(".") || name === "node_modules") continue;
+      if (fs.statSync(full).isDirectory()) walk(full);
+      else if (name.endsWith(".md")) files.push(full);
+    }
+  }
+  walk(dir);
+  return files;
+}
+
+function readMarkdownFile(file) {
+  const raw = fs.readFileSync(file, "utf-8");
+  let parsed;
+  try {
+    parsed = matter(raw);
+  } catch (e) {
+    throw new Error(`${file}: YAML frontmatter parse error — ${e.message}`);
+  }
+  return { data: parsed.data, content: parsed.content, raw };
+}
+
+function loadArticles(dir, opts) {
+  const records = [];
+  const strict = opts?.strict === true;
+  if (!fs.existsSync(dir)) {
+    _articleCache.set(dir, new Map());
+    return records;
+  }
+  const files = listMarkdownFiles(dir);
+  for (const file of files) {
+    let result;
+    try {
+      result = readMarkdownFile(file);
+    } catch (e) {
+      if (strict) throw e;
+      console.error(`[markdown-store] skipping unparseable file: ${e.message}`);
+      continue;
+    }
+    if (!result.data.id || result.data.type === "annotation") continue;
+    records.push({
+      id: result.data.id,
+      data: result.data,
+      content: result.content,
+      raw: result.raw,
+      absPath: file,
+      relPath: path.relative(dir, file),
+    });
+  }
+  const byId = new Map();
+  for (const r of records) byId.set(r.id, r);
+  _articleCache.set(dir, byId);
+  return records;
+}
+
+function writeArticleFile(absPath, data, content) {
+  const markdown = matter.stringify(content, data);
+  fs.writeFileSync(absPath, markdown, "utf-8");
+  _articleCache.clear();
+}
+
+function loadArticleById(dir, id) {
+  if (!fs.existsSync(dir)) return null;
+  let byId = _articleCache.get(dir);
+  if (!byId) {
+    byId = new Map();
+    for (const file of listMarkdownFiles(dir)) {
+      let result;
+      try {
+        result = readMarkdownFile(file);
+      } catch (_) {
+        continue;
+      }
+      if (result.data.id && result.data.type !== "annotation") {
+        byId.set(result.data.id, {
+          id: result.data.id,
+          data: result.data,
+          content: result.content,
+          raw: result.raw,
+          absPath: file,
+          relPath: path.relative(dir, file),
+        });
+      }
+    }
+    _articleCache.set(dir, byId);
+  }
+  return byId.get(id) || null;
+}
+
+function loadComments(dir) {
+  const comments = [];
+  if (!fs.existsSync(dir)) return comments;
+  for (const file of listMarkdownFiles(dir)) {
+    let result;
+    try {
+      result = readMarkdownFile(file);
+    } catch (e) {
+      console.error(`[markdown-store] skipping unparseable file: ${e.message}`);
+      continue;
+    }
+    if (result.data.type === "annotation") {
+      comments.push({
+        ...result.data,
+        _file: `comments/${path.relative(dir, file)}`,
+        content: result.content,
+      });
+    }
+  }
+  return comments;
+}
+
+function indexArticles(records) {
+  const map = {};
+  for (const r of records) {
+    if (map[r.id]) {
+      console.warn(`[markdown-store] duplicate article id "${r.id}": ${r.relPath} and ${map[r.id].relPath}`);
+    }
+    map[r.id] = r;
+  }
+  return map;
+}
+
+function nextAnnotationId(dir) {
+  let max = 0;
+  for (const file of listMarkdownFiles(dir)) {
+    const name = path.basename(file);
+    const m = name.match(/^ann-(\d+)\.md$/);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return `ann-${String(max + 1).padStart(3, "0")}`;
+}
+
+module.exports = {
+  clearArticleCache,
+  listMarkdownFiles,
+  readMarkdownFile,
+  writeArticleFile,
+  loadArticles,
+  loadArticleById,
+  loadComments,
+  indexArticles,
+  nextAnnotationId,
+};

package/scripts/lib/infra/query-log.js

@@ -0,0 +1,27 @@
+const fs = require("fs");
+const path = require("path");
+
+function logPath(dirs) {
+  return path.join(dirs.indexDir, "mcp-query-log.jsonl");
+}
+
+function appendQueryLog(dirs, entry) {
+  const file = logPath(dirs);
+  if (!fs.existsSync(dirs.indexDir)) {
+    fs.mkdirSync(dirs.indexDir, { recursive: true });
+  }
+  fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+}
+
+function readRecentQueryLog(dirs, limit) {
+  const file = logPath(dirs);
+  if (!fs.existsSync(file)) return [];
+  const raw = fs.readFileSync(file, "utf-8");
+  const lines = raw.trim().split("\n").filter(Boolean);
+  const start = Math.max(0, lines.length - (limit || 50));
+  return lines.slice(start).map((line) => {
+    try { return JSON.parse(line); } catch (_) { return null; }
+  }).filter(Boolean);
+}
+
+module.exports = { appendQueryLog, readRecentQueryLog };

package/scripts/lib/infra/read-stdin.js

@@ -0,0 +1,11 @@
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => { data += chunk; });
+    process.stdin.on("end", () => { resolve(data); });
+    process.stdin.resume();
+  });
+}
+
+module.exports = { readStdin };

package/scripts/lib/infra/workspace.js

@@ -0,0 +1,93 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const DEFAULT_WORKSPACE = path.join(os.homedir(), ".echo-workspace");
+
+function expandHome(value, homeDir = os.homedir()) {
+  return String(value).replace(/^~(?=$|\/)/, homeDir);
+}
+
+function resolveEchoHomePath(opts = {}) {
+  const env = opts.env || process.env;
+  const homeDir = opts.homeDir || os.homedir();
+  if (env.ECHO_HOME) {
+    return expandHome(env.ECHO_HOME, homeDir);
+  }
+  return path.join(homeDir, ".echo-workspace");
+}
+
+function projectIdFromPath(projectPath) {
+  const base = path.basename(path.resolve(projectPath));
+  return base
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "project";
+}
+
+function resolveProjectDataRoot(projectPath, opts = {}) {
+  const echoHome = opts.echoHome || resolveEchoHomePath(opts);
+  const projectId = opts.projectId || projectIdFromPath(projectPath);
+  return path.join(echoHome, "projects", projectId);
+}
+
+function resolveWorkspacePath(opts = {}) {
+  const env = opts.env || process.env;
+  const homeDir = opts.homeDir || os.homedir();
+  const defaultWorkspace = opts.defaultWorkspace || resolveEchoHomePath({ env, homeDir });
+  const readConfig = opts.readConfig || ((configPath) => fs.readFileSync(configPath, "utf-8"));
+
+  if (env.ECHO_WORKSPACE) {
+    return expandHome(env.ECHO_WORKSPACE, homeDir);
+  }
+
+  const configPath = path.join(defaultWorkspace, "echo.json");
+  try {
+    const raw = readConfig(configPath);
+    const config = JSON.parse(raw);
+    if (config.workspace) {
+      return expandHome(config.workspace, homeDir);
+    }
+  } catch (_) {}
+
+  return defaultWorkspace;
+}
+
+function resolveWorkspace() {
+  return resolveWorkspacePath();
+}
+
+function getConfig() {
+  const configPath = path.join(resolveWorkspace(), "echo.json");
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  } catch (_) {
+    return {};
+  }
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+const ws = resolveWorkspace();
+
+module.exports = {
+  resolveWorkspace,
+  resolveWorkspacePath,
+  resolveEchoHomePath,
+  resolveProjectDataRoot,
+  projectIdFromPath,
+  expandHome,
+  getConfig,
+  ensureDir,
+  DEFAULT_WORKSPACE,
+  workspaceRoot: ws,
+  articlesDir: path.join(ws, "articles"),
+  commentsDir: path.join(ws, "comments"),
+  bufferDir: path.join(ws, "session-buffer"),
+  indexDir: path.join(ws, "index"),
+  configPath: path.join(ws, "echo.json"),
+};

package/scripts/lib/interfaces/mcp/server.js

@@ -0,0 +1,151 @@
+// Echo MCP server — JSON-RPC 2.0 transport + dispatcher
+// Business logic: usecases/query-articles.js
+// Tool schemas: interfaces/mcp/tools.js
+// Errors: domain/errors.js
+
+const readline = require("readline");
+const { TOOLS, TOOL_HANDLERS } = require("./tools");
+const { NotFoundError } = require("../../domain/errors");
+const { resolveDataDirs } = require("../../infra/echo-paths");
+const { mcpServerInfo } = require("../../cli/names");
+
+// --- JSON-RPC 2.0 ---
+
+function jsonRpcError(id, code, message) {
+  return {
+    jsonrpc: "2.0",
+    id: id === undefined ? null : id,
+    error: { code, message },
+  };
+}
+
+function jsonRpcResult(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function send(response) {
+  process.stdout.write(JSON.stringify(response) + "\n");
+}
+
+const SERVER_INFO = mcpServerInfo;
+const CAPABILITIES = { tools: {} };
+
+// --- Request dispatcher ---
+
+function createHandleRequest(deps) {
+  return function handleRequest(msg) {
+    const { id, method, params } = msg;
+
+    switch (method) {
+      case "initialize":
+        return jsonRpcResult(id, {
+          protocolVersion: "2024-11-05",
+          capabilities: CAPABILITIES,
+          serverInfo: SERVER_INFO,
+        });
+
+      case "notifications/initialized":
+        return null;
+
+      case "tools/list":
+        return jsonRpcResult(id, { tools: TOOLS });
+
+      case "tools/call": {
+        const toolName = params?.name;
+        const handler = TOOL_HANDLERS[toolName];
+        if (!handler) {
+          return jsonRpcError(id, -32601, `Unknown tool: ${toolName}`);
+        }
+        const t0 = Date.now();
+        try {
+          const result = handler(params?.arguments || {}, deps);
+          const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+          try {
+            const { appendQueryLog } = require("../../infra/query-log");
+            appendQueryLog(deps.dirs, {
+              time: new Date().toISOString(),
+              tool: toolName,
+              args: params?.arguments || {},
+              ok: true,
+              result_count: Array.isArray(result) ? result.length : 1,
+              duration_ms: Date.now() - t0,
+            });
+          } catch (_) {}
+          return jsonRpcResult(id, { content: [{ type: "text", text }] });
+        } catch (err) {
+          try {
+            const { appendQueryLog } = require("../../infra/query-log");
+            appendQueryLog(deps.dirs, {
+              time: new Date().toISOString(),
+              tool: toolName,
+              args: params?.arguments || {},
+              ok: false,
+              result_count: 0,
+              duration_ms: Date.now() - t0,
+            });
+          } catch (_) {}
+          if (err instanceof NotFoundError) {
+            return jsonRpcError(id, -32002, err.message);
+          }
+          return jsonRpcError(id, -32000, `Tool error: ${err.message}`);
+        }
+      }
+
+      case "ping":
+        return jsonRpcResult(id, {});
+
+      default:
+        if (id !== undefined) {
+          return jsonRpcError(id, -32601, `Method not found: ${method}`);
+        }
+        return null;
+    }
+  };
+}
+
+// --- Stdio transport ---
+
+function start(deps = {}) {
+  console.log = (...args) => console.error(...args);
+  console.warn = (...args) => console.error(...args);
+  console.info = (...args) => console.error(...args);
+
+  const dirs = deps.dirs || (deps.pathResolver ? deps.pathResolver({}) : resolveDataDirs());
+  const store = deps.store || require("../../infra/markdown-store");
+
+  const handleRequest = createHandleRequest({ dirs, store });
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
+
+  rl.on("line", (line) => {
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      send(jsonRpcError(null, -32700, "Parse error"));
+      return;
+    }
+
+    if (msg == null || typeof msg !== "object" || Array.isArray(msg)) {
+      send(jsonRpcError(null, -32600, "Invalid Request"));
+      return;
+    }
+
+    try {
+      const response = handleRequest(msg);
+      if (response) send(response);
+    } catch (err) {
+      send(jsonRpcError(msg.id !== undefined ? msg.id : null, -32603, "Internal error"));
+    }
+  });
+
+  rl.on("close", () => { process.exit(0); });
+
+  process.stderr.write("[echo-mcp] MCP server started\n");
+}
+
+module.exports = { start, createHandleRequest, NotFoundError };

package/scripts/lib/interfaces/mcp/tools.js

@@ -0,0 +1,152 @@
+// Echo MCP tool definitions — schema-only, no business logic
+
+const {
+  searchArticles,
+  getArticle,
+  getArticleContext,
+  listTags,
+  listRecent,
+  addTags,
+  removeTags,
+  renameTag,
+  purgeTag,
+  listProjects,
+  getProject,
+} = require("../../usecases/query-articles");
+
+const TOOLS = [
+  {
+    name: "search_articles",
+    description: "Full-text search across Echo articles. Supports keyword search in body text and tag filtering.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        keyword: { type: "string", description: "Keyword to search in article body (case-insensitive)" },
+        tag: { type: "string", description: "Filter by tag (case-insensitive)" },
+        project: { type: "string", description: "Filter by project ID, or 'all' for all projects" },
+      },
+    },
+  },
+  {
+    name: "get_article",
+    description: "Retrieve a single article by its ID with full content.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Article ID (e.g., article-ai-dialogue)" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "get_article_context",
+    description: "Get article with its comments, evolution chain, and metadata. Use this when exploring how ideas connect across articles.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Article ID" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "list_tags",
+    description: "List all tags in the Echo workspace with usage counts.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "list_recent",
+    description: "List recently created articles, ordered by creation date.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", description: "Maximum number of articles to return (default: 20, max: 100)" },
+      },
+    },
+  },
+  {
+    name: "list_projects",
+    description: "List all registered Echo projects with their root paths and registration dates.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "get_project",
+    description: "Get details of a single registered Echo project by its ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Project ID (e.g., mynote, echo-notes)" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "add_tags",
+    description: "Add one or more tags to an article. Tags are written back to the markdown file's YAML frontmatter. Duplicate tags are ignored.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Article ID" },
+        tags: { type: "array", items: { type: "string" }, description: "Tags to add to the article" },
+      },
+      required: ["id", "tags"],
+    },
+  },
+  {
+    name: "remove_tags",
+    description: "Remove one or more tags from an article. Tags are written back to the markdown file's YAML frontmatter. Non-existent tags are silently ignored.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Article ID" },
+        tags: { type: "array", items: { type: "string" }, description: "Tags to remove from the article" },
+      },
+      required: ["id", "tags"],
+    },
+  },
+  {
+    name: "rename_tag",
+    description: "Rename a tag across all articles that have it. All occurrences of the old tag in article frontmatter are replaced with the new tag.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        oldTag: { type: "string", description: "Current tag name to rename" },
+        newTag: { type: "string", description: "New tag name" },
+      },
+      required: ["oldTag", "newTag"],
+    },
+  },
+  {
+    name: "purge_tag",
+    description: "Permanently remove a tag from all articles. The tag is deleted from every article's frontmatter.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tag: { type: "string", description: "Tag to remove from all articles" },
+      },
+      required: ["tag"],
+    },
+  },
+];
+
+const TOOL_HANDLERS = {
+  search_articles: searchArticles,
+  get_article: getArticle,
+  get_article_context: getArticleContext,
+  list_tags: listTags,
+  list_recent: listRecent,
+  list_projects: listProjects,
+  get_project: getProject,
+  add_tags: addTags,
+  remove_tags: removeTags,
+  rename_tag: renameTag,
+  purge_tag: purgeTag,
+};
+
+module.exports = { TOOLS, TOOL_HANDLERS };

package/scripts/lib/mcp-server.js

@@ -0,0 +1,3 @@
+// Backward-compat re-export — new code should require interfaces/mcp/server directly
+const server = require("./interfaces/mcp/server");
+module.exports = server;

package/scripts/lib/usecases/aggregate-all-projects.js

@@ -0,0 +1,45 @@
+/**
+ * aggregate-all-projects — return data directories for all registered projects.
+ *
+ * Used by run-pipeline (npm run all) and build-docs (loadAllArticlesAndComments).
+ */
+const path = require("path");
+const {
+  resolveEchoHomePath,
+  resolveProjectDataRoot,
+} = require("../infra/workspace");
+
+/**
+ * @param {{ echoHome?: string }} [opts]
+ * @returns {Array<{ projectId: string, root: string, dataRoot: string, articlesDir: string, commentsDir: string, bufferDir: string, indexDir: string }>}
+ */
+function aggregateAllProjects(opts = {}) {
+  const echoHome = opts.echoHome || resolveEchoHomePath(opts);
+  let projects = [];
+
+  try {
+    const { listProjects } = require("./project-registry");
+    projects = listProjects(echoHome);
+  } catch (e) {
+    console.error("[echo] aggregateAllProjects: failed to load project registry:", e.message);
+  }
+
+  const sources = [];
+
+  for (const p of projects) {
+    const dataRoot = p.dataRoot || resolveProjectDataRoot(p.root, { echoHome, projectId: p.projectId });
+    sources.push({
+      projectId: p.projectId,
+      root: p.root,
+      dataRoot,
+      articlesDir: path.join(dataRoot, "articles"),
+      commentsDir: path.join(dataRoot, "comments"),
+      bufferDir: path.join(dataRoot, "session-buffer"),
+      indexDir: path.join(dataRoot, "index"),
+    });
+  }
+
+  return sources;
+}
+
+module.exports = { aggregateAllProjects };

package/scripts/lib/usecases/convert-buffer.js

@@ -0,0 +1,43 @@
+const path = require("path");
+const ef = require("../domain/echo-format");
+
+function parseBuffer(raw) {
+  const turns = [];
+  let currentTurn = null;
+
+  for (const line of raw.split("\n")) {
+    const turnMatch = line.match(ef.TURN_MARKER_REGEX);
+    if (turnMatch) {
+      if (currentTurn) turns.push(currentTurn);
+      currentTurn = {
+        id: turnMatch[1],
+        speaker: turnMatch[2],
+        reply_to: turnMatch[3] || null,
+        content: "",
+      };
+      continue;
+    }
+    if (currentTurn) currentTurn.content += line + "\n";
+  }
+  if (currentTurn) turns.push(currentTurn);
+  for (const t of turns) t.content = t.content.trimEnd();
+  return { raw, turns };
+}
+
+function buildArticle(bufferFile, turns, opts = {}) {
+  const sessionName = path.basename(bufferFile, ".md");
+  const dateStr = ef.extractSessionDate(sessionName);
+  const id = sessionName.startsWith("session-") ? sessionName : `session-${sessionName}`;
+
+  const article = ef.createArticle({
+    id,
+    created_at: `${dateStr}T00:00:00+08:00`,
+    alias: ef.inferTitle(turns),
+    turns,
+    project: opts.project,
+  });
+
+  return { id, article: ef.toMarkdown(article), title: article.title, alias: article.alias, turnCount: article.turns.length };
+}
+
+module.exports = { parseBuffer, buildArticle };