echoctl 0.1.0

package/scripts/lib/usecases/query-articles.js

@@ -0,0 +1,380 @@
+// Echo usecase — article query operations for MCP tools
+// Each handler receives (args, deps) where deps = { dirs, store }
+
+const path = require("path");
+const { ensureDir } = require("../infra/workspace");
+const { NotFoundError } = require("../domain/errors");
+
+let _projectRegistry;
+function getProjectRegistry() {
+  if (!_projectRegistry) {
+    try { _projectRegistry = require("./project-registry"); } catch (_) { _projectRegistry = null; }
+  }
+  return _projectRegistry;
+}
+
+function searchArticles(args, deps) {
+  const { dirs, store } = deps;
+  ensureDir(dirs.articlesDir);
+  const keyword = (args.keyword || "").toLowerCase();
+  const tag = (args.tag || "").toLowerCase();
+  const projectFilter = args.project;
+
+  // Determine which project directories to search
+  const projectDirs = [];
+  const currentProjectId = dirs.projectId;
+
+  if (projectFilter && projectFilter !== "all" && projectFilter !== currentProjectId) {
+    // Search only the specified external project
+    try {
+      const reg = getProjectRegistry();
+      const { listProjects } = reg || {};
+      const projects = listProjects();
+      const target = projects.find((p) => p.projectId === projectFilter);
+      if (target) {
+        projectDirs.push({ articlesDir: path.join(target.dataRoot, "articles"), projectId: target.projectId });
+      }
+    } catch (_) {}
+    // If project not found, fall through with empty projectDirs (returns no results)
+  } else if (projectFilter === "all") {
+    // Search current project + all registered projects
+    projectDirs.push({ articlesDir: dirs.articlesDir, projectId: currentProjectId });
+    try {
+      const reg = getProjectRegistry();
+      const { listProjects } = reg || {};
+      const projects = listProjects();
+      for (const p of projects) {
+        if (p.projectId === currentProjectId) continue;
+        projectDirs.push({ articlesDir: path.join(p.dataRoot, "articles"), projectId: p.projectId });
+      }
+    } catch (_) {}
+  } else {
+    // Default: current project only
+    projectDirs.push({ articlesDir: dirs.articlesDir, projectId: currentProjectId });
+  }
+
+  // Load articles from all determined project directories
+  const articles = [];
+  for (const pd of projectDirs) {
+    store.loadArticles(pd.articlesDir).forEach((a) => {
+      articles.push({
+        ...a.data,
+        _file: a.relPath,
+        _content: a.content,
+        project: a.data.project || pd.projectId || "",
+      });
+    });
+  }
+
+  let results = articles;
+
+  if (projectFilter && projectFilter !== "all") {
+    results = results.filter((a) => a.project === projectFilter);
+  }
+
+  if (tag) {
+    results = results.filter((a) =>
+      (a.tags || []).some((t) => t.toLowerCase() === tag)
+    );
+  }
+
+  if (keyword) {
+    results = results
+      .map((a) => {
+        const body = a._content.toLowerCase();
+        const aliasMatch = (a.alias || "").toLowerCase().includes(keyword);
+        const idx = body.indexOf(keyword);
+        if (idx === -1 && !aliasMatch) return null;
+        const start = Math.max(0, idx - 80);
+        const end = Math.min(body.length, idx + keyword.length + 80);
+        let snippet = a._content.slice(start, end).replace(/\n/g, " ");
+        if (start > 0) snippet = "..." + snippet;
+        if (end < body.length) snippet = snippet + "...";
+        return { ...a, _snippet: snippet };
+      })
+      .filter(Boolean);
+  }
+
+  return results.map((a) => ({
+    id: a.id,
+    title: a.title || a.id,
+    alias: a.alias || "",
+    file: a._file,
+    created_at: a.created_at,
+    tags: a.tags || [],
+    summary: a.summary || "",
+    snippet: a._snippet || "",
+    ai_model: a.ai_model || "",
+    project: a.project || "",
+  }));
+}
+
+function getArticle(args, deps) {
+  const { dirs, store } = deps;
+  ensureDir(dirs.articlesDir);
+  const article = store.loadArticleById(dirs.articlesDir, args.id);
+  if (!article) throw new NotFoundError(`Article "${args.id}" not found`);
+
+  return {
+    id: article.data.id,
+    title: article.data.title || article.data.id,
+    alias: article.data.alias || "",
+    created_at: article.data.created_at,
+    updated_at: article.data.updated_at,
+    tags: article.data.tags || [],
+    summary: article.data.summary || "",
+    content: article.content.trim(),
+    file: article.relPath,
+    ai_model: article.data.ai_model || "",
+    evolution: article.data.evolution || null,
+  };
+}
+
+function getArticleContext(args, deps) {
+  const { dirs, store } = deps;
+  ensureDir(dirs.articlesDir);
+  const article = store.loadArticleById(dirs.articlesDir, args.id);
+  if (!article) throw new NotFoundError(`Article "${args.id}" not found`);
+
+  ensureDir(dirs.commentsDir);
+  const comments = store.loadComments(dirs.commentsDir).filter(
+    (c) => c.target && c.target.article_id === args.id
+  );
+
+  let evolutionChain = [];
+  const evo = article.data.evolution;
+
+  if (evo) {
+    const visited = new Set();
+    let cursor = evo;
+    while (cursor && cursor.of) {
+      if (visited.has(cursor.of)) break;
+      visited.add(cursor.of);
+      const prev = store.loadArticleById(dirs.articlesDir, cursor.of);
+      if (prev) {
+        evolutionChain.unshift({
+          id: prev.data.id,
+          title: prev.data.title || prev.data.id,
+          direction: cursor.direction || "expands",
+        });
+        cursor = prev.data.evolution;
+      } else {
+        break;
+      }
+    }
+  }
+
+  evolutionChain.push({
+    id: article.data.id,
+    title: article.data.title || article.data.id,
+    direction: null,
+  });
+
+  const allArticles = store.loadArticles(dirs.articlesDir);
+  const forward = allArticles.filter(
+    (a) => a.data.evolution && a.data.evolution.of === args.id
+  );
+  for (const f of forward) {
+    evolutionChain.push({
+      id: f.data.id,
+      title: f.data.title || f.data.id,
+      direction: f.data.evolution.direction || "expands",
+    });
+  }
+
+  return {
+    id: article.data.id,
+    title: article.data.title || article.data.id,
+    created_at: article.data.created_at,
+    tags: article.data.tags || [],
+    summary: article.data.summary || "",
+    content_preview: article.content.trim().slice(0, 500),
+    evolution_chain: evolutionChain,
+    comments: comments.map((c) => ({
+      id: c.id,
+      author: c.author || "anonymous",
+      created_at: c.created_at,
+      target_article_id: c.target?.article_id || "",
+      anchor_quote: c.anchor?.quote || "",
+      comment: (c.content || "").trim(),
+    })),
+  };
+}
+
+function listTags(_args, deps) {
+  const { dirs, store } = deps;
+  ensureDir(dirs.articlesDir);
+  const articles = store.loadArticles(dirs.articlesDir);
+  const tagCounts = {};
+
+  for (const a of articles) {
+    for (const tag of a.data.tags || []) {
+      tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+    }
+  }
+
+  return Object.entries(tagCounts)
+    .sort((a, b) => b[1] - a[1])
+    .map(([tag, count]) => ({ tag, count }));
+}
+
+function addTags(args, deps) {
+  const { dirs, store } = deps;
+  ensureDir(dirs.articlesDir);
+  const article = store.loadArticleById(dirs.articlesDir, args.id);
+  if (!article) throw new NotFoundError(`Article "${args.id}" not found`);
+
+  const newTags = (args.tags || []).map((t) => t.trim()).filter(Boolean);
+  if (newTags.length === 0) return { id: article.data.id, tags: article.data.tags || [] };
+
+  const existingTags = article.data.tags || [];
+  const merged = [...new Set([...existingTags, ...newTags])];
+
+  article.data.tags = merged;
+  store.writeArticleFile(article.absPath, article.data, article.content);
+
+  return { id: article.data.id, tags: merged, added: newTags };
+}
+
+function updateSummary(args, deps) {
+  const { dirs, store } = deps;
+  ensureDir(dirs.articlesDir);
+  const article = store.loadArticleById(dirs.articlesDir, args.id);
+  if (!article) throw new NotFoundError(`Article "${args.id}" not found`);
+
+  article.data.summary = (args.summary || "").trim() || undefined;
+  store.writeArticleFile(article.absPath, article.data, article.content);
+
+  return { id: article.data.id, summary: article.data.summary || "" };
+}
+
+function removeTags(args, deps) {
+  const { dirs, store } = deps;
+  ensureDir(dirs.articlesDir);
+  const article = store.loadArticleById(dirs.articlesDir, args.id);
+  if (!article) throw new NotFoundError(`Article "${args.id}" not found`);
+
+  const toRemove = new Set((args.tags || []).map((t) => t.trim()).filter(Boolean));
+  if (toRemove.size === 0) return { id: article.data.id, tags: article.data.tags || [] };
+
+  const existingTags = article.data.tags || [];
+  const kept = existingTags.filter((t) => !toRemove.has(t));
+
+  article.data.tags = kept;
+  store.writeArticleFile(article.absPath, article.data, article.content);
+
+  return { id: article.data.id, tags: kept, removed: [...toRemove] };
+}
+
+function renameTag(args, deps) {
+  const { dirs, store } = deps;
+  const oldTag = (args.oldTag || "").trim();
+  const newTag = (args.newTag || "").trim();
+  if (!oldTag || !newTag) throw new Error("oldTag and newTag are required");
+  if (oldTag === newTag) throw new Error("oldTag and newTag must be different");
+
+  ensureDir(dirs.articlesDir);
+  const articles = store.loadArticles(dirs.articlesDir);
+
+  let renamed = 0;
+  for (const article of articles) {
+    const tags = article.data.tags || [];
+    if (tags.includes(oldTag)) {
+      article.data.tags = tags.map((t) => (t === oldTag ? newTag : t));
+      store.writeArticleFile(article.absPath, article.data, article.content);
+      renamed++;
+    }
+  }
+
+  if (renamed === 0) throw new NotFoundError(`Tag "${oldTag}" not found in any article`);
+
+  return { oldTag, newTag, renamed };
+}
+
+function purgeTag(args, deps) {
+  const { dirs, store } = deps;
+  const tag = (args.tag || "").trim();
+  if (!tag) throw new Error("tag is required");
+
+  ensureDir(dirs.articlesDir);
+  const articles = store.loadArticles(dirs.articlesDir);
+
+  let purged = 0;
+  for (const article of articles) {
+    const tags = article.data.tags || [];
+    if (tags.includes(tag)) {
+      article.data.tags = tags.filter((t) => t !== tag);
+      store.writeArticleFile(article.absPath, article.data, article.content);
+      purged++;
+    }
+  }
+
+  if (purged === 0) throw new NotFoundError(`Tag "${tag}" not found in any article`);
+
+  return { tag, purged };
+}
+
+function listRecent(args, deps) {
+  const { dirs, store } = deps;
+  ensureDir(dirs.articlesDir);
+  const raw = args.limit != null ? parseInt(args.limit, 10) : 20;
+  const limit = Math.max(1, Math.min(isNaN(raw) ? 20 : raw, 100));
+
+  const articles = store.loadArticles(dirs.articlesDir);
+  articles.sort((a, b) => {
+    const da = a.data.created_at ? new Date(a.data.created_at) : new Date(0);
+    const db = b.data.created_at ? new Date(b.data.created_at) : new Date(0);
+    return db - da;
+  });
+
+  return articles.slice(0, limit).map((a) => ({
+    id: a.data.id,
+    title: a.data.title || a.data.id,
+    alias: a.data.alias || "",
+    created_at: a.data.created_at,
+    tags: a.data.tags || [],
+    summary: a.data.summary || "",
+    file: a.relPath,
+    ai_model: a.data.ai_model || "",
+  }));
+}
+
+function listProjects(_args, _deps) {
+  const reg = getProjectRegistry();
+  const listAll = reg ? reg.listProjects : null;
+  if (!listAll) return [];
+  return listAll().map((p) => ({
+    projectId: p.projectId,
+    root: p.root,
+    dataRoot: p.dataRoot,
+    registeredAt: p.registeredAt,
+  }));
+}
+
+function getProject(args, _deps) {
+  const reg = getProjectRegistry();
+  const findProjectById = reg ? reg.findProjectById : null;
+  if (!findProjectById) throw new NotFoundError(`Project "${args.id}" not found`);
+  const project = findProjectById(args.id);
+  if (!project) throw new NotFoundError(`Project "${args.id}" not found`);
+  return {
+    projectId: project.projectId,
+    root: project.projectRoot,
+    dataRoot: project.dataRoot,
+  };
+}
+
+module.exports = {
+  searchArticles,
+  getArticle,
+  getArticleContext,
+  listTags,
+  listRecent,
+  addTags,
+  removeTags,
+  renameTag,
+  purgeTag,
+  updateSummary,
+  listProjects,
+  getProject,
+};

package/scripts/lib/usecases/refresh-serve.js

@@ -0,0 +1,77 @@
+const fs = require("fs");
+const http = require("http");
+const path = require("path");
+const { resolveEchoHomePath } = require("../infra/workspace");
+
+const HOST = "127.0.0.1";
+
+function serveInfoPath() {
+  return path.join(resolveEchoHomePath(), ".serve.json");
+}
+
+function isPidRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === "ESRCH") return false;
+    if (err.code === "EPERM") return true;
+    throw err;
+  }
+}
+
+function getRunningServeInfo() {
+  let info;
+  try {
+    info = JSON.parse(fs.readFileSync(serveInfoPath(), "utf-8"));
+  } catch (_) {
+    return null;
+  }
+  if (info.identity !== "echo-serve") return null;
+  if (!isPidRunning(info.pid)) return null;
+  if (!Number.isInteger(info.apiPort) || info.apiPort <= 0) return null;
+  return info;
+}
+
+function requestRunningServeRefresh(opts = {}) {
+  const timeoutMs = opts.timeoutMs || 15000;
+  const info = opts.info || getRunningServeInfo();
+  if (!info) {
+    return Promise.resolve({ attempted: false, ok: false, message: "serve is not running" });
+  }
+
+  return new Promise((resolve) => {
+    const req = http.request({
+      host: HOST,
+      port: info.apiPort,
+      path: "/api/rebuild-docs",
+      method: "POST",
+      timeout: timeoutMs,
+    }, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        const body = Buffer.concat(chunks).toString("utf-8");
+        resolve({
+          attempted: true,
+          ok: res.statusCode >= 200 && res.statusCode < 300,
+          statusCode: res.statusCode,
+          message: body || res.statusMessage || "",
+        });
+      });
+    });
+    req.on("timeout", () => {
+      req.destroy(new Error("refresh timed out"));
+    });
+    req.on("error", (err) => {
+      resolve({ attempted: true, ok: false, message: err.message });
+    });
+    req.end();
+  });
+}
+
+module.exports = {
+  getRunningServeInfo,
+  requestRunningServeRefresh,
+};

package/scripts/lib/usecases/run-doctor.js

@@ -0,0 +1,213 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { resolveWorkspace, resolveEchoHomePath } = require("../infra/workspace");
+const { isCaptureEnabled } = require("../infra/config");
+const { findProjectForPath } = require("./project-registry");
+const { commandFor, isKnownCliCommand, cliNames } = require("../cli/names");
+
+function check(name, status, message) {
+  return { name, status, message };
+}
+
+function ok(name, message) { return check(name, "ok", message); }
+function warn(name, message) { return check(name, "warn", message); }
+function error(name, message) { return check(name, "error", message); }
+
+
+function extractHookCommand(entry, matches = () => true) {
+  if (Array.isArray(entry.hooks)) {
+    const hook = entry.hooks.find(
+      (h) => typeof h.command === "string" && matches(h.command)
+    );
+    if (hook) return hook.command;
+  }
+  if (typeof entry.command === "string" && matches(entry.command)) return entry.command;
+  return null;
+}
+
+function runDoctor({ hookOnly } = {}) {
+  const ws = resolveWorkspace();
+  const results = [];
+
+  if (!hookOnly) {
+    // 1. Workspace exists
+    if (fs.existsSync(ws)) {
+      results.push(ok("Workspace", `exists: ${ws}`));
+    } else {
+      results.push(error("Workspace", `not found: ${ws}`));
+    }
+
+    // 2. Workspace writable (real temp file test)
+    try {
+      const probe = path.join(ws, ".echo-doctor-probe");
+      fs.writeFileSync(probe, "");
+      fs.unlinkSync(probe);
+      results.push(ok("Workspace writable", "write test passed"));
+    } catch (_) {
+      results.push(error("Workspace writable", "cannot write to workspace"));
+    }
+
+    // 3. Subdirectories
+    for (const d of ["articles", "comments", "session-buffer", "index"]) {
+      const full = path.join(ws, d);
+      if (!fs.existsSync(full)) {
+        results.push(warn("Subdirectory", `${d}/ missing — run ${commandFor(["init"])}`));
+      }
+    }
+    if (results.filter(r => r.name === "Subdirectory").length === 0) {
+      results.push(ok("Subdirectories", "all present"));
+    }
+
+    // 4. echo.json valid JSON (direct parse, not getConfig)
+    const configPath = path.join(ws, "echo.json");
+    if (fs.existsSync(configPath)) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        if (cfg.workspace) {
+          results.push(ok("echo.json", `valid (workspace=${cfg.workspace})`));
+        } else {
+          results.push(warn("echo.json", "valid JSON but no workspace field"));
+        }
+      } catch (_) {
+        results.push(error("echo.json", `invalid JSON — run ${commandFor(["init"])}`));
+      }
+    } else {
+      results.push(warn("echo.json", `missing — run ${commandFor(["init"])}`));
+    }
+
+    // 5. Capture status
+    const captureOn = isCaptureEnabled();
+    if (captureOn) {
+      results.push(ok("Capture", "enabled"));
+    } else {
+      results.push(warn("Capture", `disabled — run: ${commandFor(["capture", "on"])}`));
+    }
+
+    // 6. Legacy ~/.echo-buffer (warning only)
+    const legacyBuffer = path.join(os.homedir(), ".echo-buffer");
+    if (fs.existsSync(legacyBuffer)) {
+      results.push(warn("Legacy buffer", `${legacyBuffer} exists — run ${commandFor(["migrate", "legacy-buffer"])}`));
+    }
+
+    // 7. Echo home (global)
+    const echoHome = resolveEchoHomePath();
+    if (fs.existsSync(echoHome)) {
+      results.push(ok("Echo home", `exists: ${echoHome}`));
+    } else {
+      results.push(warn("Echo home", `not found: ${echoHome} — run ${commandFor(["init"])}`));
+    }
+
+    // 8. registry.json
+    const registryPath = path.join(echoHome, "registry.json");
+    let registry = null;
+    if (fs.existsSync(registryPath)) {
+      try {
+        registry = JSON.parse(fs.readFileSync(registryPath, "utf-8"));
+        const count = Object.keys(registry.projects || {}).length;
+        results.push(ok("registry.json", `valid (${count} project${count !== 1 ? "s" : ""})`));
+      } catch (_) {
+        results.push(error("registry.json", "invalid JSON"));
+      }
+    } else {
+      results.push(warn("registry.json", `missing — run ${commandFor(["init"])}`));
+    }
+
+    // 9. Current project registration
+    let currentProject = null;
+    if (registry) {
+      const cwd = process.cwd();
+      const current = findProjectForPath(cwd, { echoHome });
+      if (current) {
+        currentProject = current;
+        results.push(ok("Current project", `${current.projectId} (data: ${current.dataRoot})`));
+
+        // 10. Project data directories
+        const missing = [];
+        for (const d of ["session-buffer", "articles", "comments", "index"]) {
+          if (!fs.existsSync(path.join(current.dataRoot, d))) {
+            missing.push(d);
+          }
+        }
+        if (missing.length > 0) {
+          results.push(warn("Project data dirs", `missing: ${missing.join(", ")} — run ${commandFor(["init", "project"])}`));
+        } else {
+          results.push(ok("Project data dirs", "all present"));
+        }
+      } else {
+        // Check if cwd is inside Echo's data directory first
+        const projectsDir = path.join(echoHome, "projects");
+        if (cwd.startsWith(projectsDir + path.sep)) {
+          let foundProjectRoot = null;
+          for (const [id, entry] of Object.entries(registry.projects || {})) {
+            const dataRoot = path.join(echoHome, "projects", id);
+            if (cwd.startsWith(dataRoot + path.sep) || cwd === dataRoot) {
+              foundProjectRoot = entry.root;
+              break;
+            }
+          }
+          if (foundProjectRoot) {
+            results.push(warn("Data directory detected",
+              `This is an Echo internal data directory.\n` +
+              `  Use the registered project root instead:\n` +
+              `    cd ${foundProjectRoot}`));
+          } else {
+            results.push(warn("Data directory detected",
+              `This appears to be inside Echo's data storage (~/.echo-workspace/projects/).\n` +
+              `  Run ${commandFor(["doctor"])} from your project directory instead.`));
+          }
+        } else {
+          results.push(warn("Current project", `${cwd} not registered — run ${commandFor(["init", "project"])}`));
+        }
+      }
+    }
+  }
+
+  // 7. Hook configuration
+  const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+      const hooks = settings.hooks || {};
+
+      for (const event of ["UserPromptSubmit", "Stop", "StopFailure", "SessionStart"]) {
+        const entries = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const hasEchoMcp = entries.some((e) => {
+          const cmd = extractHookCommand(e, (command) => isKnownCliCommand(command));
+          return typeof cmd === "string" && isKnownCliCommand(cmd);
+        });
+        const hasSh = entries.some((e) => {
+          const cmd = extractHookCommand(e, (command) => command.includes(".sh"));
+          return typeof cmd === "string" && cmd.includes(".sh");
+        });
+
+        if (hasEchoMcp) {
+          const cmds = entries.filter((e) => {
+            const cmd = extractHookCommand(e, (command) => isKnownCliCommand(command));
+            return typeof cmd === "string" && isKnownCliCommand(cmd);
+          }).map((e) => extractHookCommand(e, (command) => isKnownCliCommand(command)));
+          results.push(ok(`Hook: ${event}`, `CLI: ${cmds.join(", ")}`));
+        } else if (hasSh) {
+          const cmds = entries.filter((e) => {
+            const cmd = extractHookCommand(e, (command) => command.includes(".sh"));
+            return typeof cmd === "string" && cmd.includes(".sh");
+          }).map((e) => extractHookCommand(e, (command) => command.includes(".sh")));
+          results.push(warn(`Hook: ${event}`, `legacy .sh: ${cmds.join(", ")} — run ${commandFor(["hook", "install", "claude", "--write"])}`));
+        } else {
+          results.push(warn(`Hook: ${event}`, `not configured — run ${commandFor(["hook", "install", "claude", "--write"])}`));
+        }
+      }
+    } catch (_) {
+      results.push(error("Hook config", `${settingsPath} is invalid JSON`));
+    }
+  } else {
+    results.push(warn("Hook config", `~/.claude/settings.json not found — run ${commandFor(["hook", "install", "claude"])}`));
+  }
+
+  // 8. CLI resolvability
+  results.push(ok("CLI", `${cliNames.canonicalName} is in PATH; echo-mcp remains supported as alias`));
+
+  return results;
+}
+
+module.exports = { runDoctor };