echoctl 0.1.0

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

@@ -0,0 +1,104 @@
+/**
+ * run-pipeline — orchestrates the full Echo data pipeline.
+ *
+ * Usage:
+ *   const { runPipeline } = require("./usecases/run-pipeline");
+ *   runPipeline();                                    // current project only
+ *   runPipeline({ allProjects: true });               // all registered projects
+ *   runPipeline({ steps: ["convert", "validate"] });
+ */
+
+const { resolveDataDirs } = require("../infra/echo-paths");
+
+function runOneProject(dirs, steps, opts) {
+  const results = {};
+
+  for (const step of steps) {
+    try {
+      switch (step) {
+        case "convert": {
+          console.log(`[echo] convert — buffer -> articles (${dirs.projectId || "default"})\n`);
+          const { runConvert } = require("../../convert");
+          const r = runConvert({ dirs, cwd: opts.cwd, silent: opts.silent });
+          results.convert = { success: true, files: r.files.length };
+          console.log("");
+          break;
+        }
+        case "validate": {
+          console.log(`[echo] validate — check articles + comments (${dirs.projectId || "default"})\n`);
+          const { runValidate } = require("../../validate");
+          const r = runValidate({ dirs, cwd: opts.cwd });
+          results.validate = r;
+          if (!r.success) {
+            console.error(`\n[echo] Pipeline stopped: validate failed with ${r.errors.length} error(s).`);
+            return { ...results, _halted: true };
+          }
+          console.log("");
+          break;
+        }
+        case "index": {
+          console.log(`[echo] index — generate comment sections (${dirs.projectId || "default"})\n`);
+          const { runIndex } = require("../../index");
+          const r = runIndex({ dirs, cwd: opts.cwd });
+          results.index = { success: true, updated: r.updated.length, articleCount: r.articleCount, commentCount: r.commentCount };
+          console.log("");
+          break;
+        }
+        case "resolve": {
+          console.log(`[echo] resolve — verify annotation anchors (${dirs.projectId || "default"})\n`);
+          const { runResolve } = require("../../resolve");
+          const r = runResolve({ dirs, cwd: opts.cwd });
+          results.resolve = r;
+          if (r.broken > 0) {
+            console.error(`\n[echo] Pipeline stopped: resolve found ${r.broken} broken anchor(s).`);
+            return { ...results, _halted: true };
+          }
+          console.log("");
+          break;
+        }
+        default:
+          throw new Error(`Unknown pipeline step: ${step}`);
+      }
+    } catch (err) {
+      console.error(`\n[echo] Pipeline stopped: ${step} threw an error.`);
+      console.error(`  ${err.message}`);
+      results[step] = { success: false, error: err.message };
+      return { ...results, _halted: true };
+    }
+  }
+
+  return results;
+}
+
+function runPipeline(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const steps = opts.steps || ["convert", "validate", "index", "resolve"];
+
+  if (opts.allProjects) {
+    const { aggregateAllProjects } = require("./aggregate-all-projects");
+    const sources = aggregateAllProjects();
+    const allResults = {};
+
+    for (const src of sources) {
+      const dirs = {
+        articlesDir: src.articlesDir,
+        commentsDir: src.commentsDir,
+        bufferDir: src.bufferDir,
+        indexDir: src.indexDir,
+        projectId: src.projectId,
+        projectRoot: src.root,
+      };
+      const result = runOneProject(dirs, steps, opts);
+      allResults[src.projectId] = result;
+      if (result._halted) return allResults;
+      delete result._halted;
+    }
+
+    return allResults;
+  }
+
+  const dirs = opts.dirs || resolveDataDirs({ cwd });
+  return runOneProject(dirs, steps, opts);
+}
+
+module.exports = { runPipeline };

package/scripts/lib/usecases/snapshot-manifest.js

@@ -0,0 +1,48 @@
+const fs = require("fs");
+const path = require("path");
+
+function manifestPath(dataRoot) {
+  return path.join(dataRoot, "snapshots.json");
+}
+
+function loadManifest(dataRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath(dataRoot), "utf-8"));
+  } catch (err) {
+    if (err.code === "ENOENT") return { sessions: {} };
+    throw err;
+  }
+}
+
+function saveManifest(dataRoot, manifest) {
+  const p = manifestPath(dataRoot);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = p + ".tmp-" + Date.now();
+  fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+  fs.renameSync(tmp, p);
+}
+
+function recordSnapshot(dataRoot, sessionId, articleId, turnCount) {
+  const manifest = loadManifest(dataRoot);
+  if (!manifest.sessions[sessionId]) {
+    manifest.sessions[sessionId] = { latestArticleId: null, versions: [] };
+  }
+  const entry = manifest.sessions[sessionId];
+  const nextVersion = entry.versions.length + 1;
+  entry.versions.push({
+    version: nextVersion,
+    articleId,
+    publishedAt: new Date().toISOString(),
+    turnCount,
+  });
+  entry.latestArticleId = articleId;
+  saveManifest(dataRoot, manifest);
+  return { version: nextVersion, latest: true };
+}
+
+function getSnapshotInfo(dataRoot, sessionId) {
+  const manifest = loadManifest(dataRoot);
+  return manifest.sessions[sessionId] || null;
+}
+
+module.exports = { loadManifest, saveManifest, recordSnapshot, getSnapshotInfo };

package/scripts/lib/usecases/status-collector.js

@@ -0,0 +1,142 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { resolveEchoHomePath } = require("../infra/workspace");
+const { isCaptureEnabled } = require("../infra/config");
+const { findProjectForPath } = require("./project-registry");
+const { cliNames } = require("../cli/names");
+const { scanLegacyCandidates } = require("./legacy-candidates");
+const { discoverClaudeImportCandidates } = require("./discover-claude-imports");
+
+function serveInfoFile() {
+  return path.join(resolveEchoHomePath(), ".serve.json");
+}
+
+function readServeInfo() {
+  try {
+    return JSON.parse(fs.readFileSync(serveInfoFile(), "utf-8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+function isPidRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+
+function extractHookCommand(entry) {
+  if (Array.isArray(entry.hooks)) {
+    const h = entry.hooks.find((h) => typeof h.command === "string");
+    if (h) return h.command;
+  }
+  if (typeof entry.command === "string") return entry.command;
+  return null;
+}
+
+function checkHookInstalled() {
+  const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    const hooks = settings.hooks || {};
+    for (const event of ["SessionStart", "UserPromptSubmit", "Stop", "StopFailure"]) {
+      const entries = hooks[event] || [];
+      const has = entries.some((e) => {
+        const cmd = extractHookCommand(e);
+        return cmd && (cmd.includes("echoctl") || cmd.includes("echo-mcp"));
+      });
+      if (!has) return false;
+    }
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function countMdFiles(dir) {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.endsWith(".md")).length;
+  } catch (_) {
+    return 0;
+  }
+}
+
+function collectStatus(opts = {}) {
+  const echoHome = resolveEchoHomePath(opts);
+  const serveInfo = readServeInfo();
+  const serveRunning = serveInfo ? isPidRunning(serveInfo.pid) : false;
+  const project = findProjectForPath(process.cwd(), { echoHome });
+  const TOOLS = require("../interfaces/mcp/tools").TOOLS;
+
+  let legacyBuffers = 0;
+  let legacyCandidates = 0;
+  try {
+    const legacyDir = path.join(echoHome, "session-buffer");
+    if (fs.existsSync(legacyDir)) {
+      legacyBuffers = fs.readdirSync(legacyDir).filter((f) => f.endsWith(".md")).length;
+    }
+    if (project) {
+      const result = scanLegacyCandidates(project.projectId, { echoHome });
+      legacyCandidates = result.candidates.length;
+    }
+  } catch (_) {}
+
+  let transcripts = null;
+  let transcriptNew = 0;
+  let transcriptUpdated = 0;
+  if (project) {
+    try {
+      const r = discoverClaudeImportCandidates(project.projectId, { echoHome });
+      transcripts = { provider: r.provider, projectDir: r.projectDir, ...r.summary };
+      transcriptNew = r.summary.new;
+      transcriptUpdated = r.summary.updated;
+    } catch (_) {}
+  }
+
+  return {
+    serve: {
+      running: serveRunning,
+      docsUrl: (serveRunning && serveInfo) ? `http://127.0.0.1:${serveInfo.docsPort}/` : null,
+      apiUrl: (serveRunning && serveInfo) ? `http://127.0.0.1:${serveInfo.apiPort}/` : null,
+      pid: serveInfo ? serveInfo.pid : null,
+      logFile: path.join(echoHome, ".serve.log"),
+    },
+    capture: { enabled: isCaptureEnabled() },
+    hook: { provider: "claude", installed: checkHookInstalled() },
+    project: project ? {
+      registered: true, projectId: project.projectId,
+      root: project.projectRoot, dataRoot: project.dataRoot,
+    } : {
+      registered: false, projectId: null, root: null, dataRoot: null,
+    },
+    data: project ? {
+      liveBuffers: countMdFiles(path.join(project.dataRoot, "session-buffer")),
+      articles: countMdFiles(path.join(project.dataRoot, "articles")),
+      comments: countMdFiles(path.join(project.dataRoot, "comments")),
+    } : { liveBuffers: 0, articles: 0, comments: 0 },
+    legacy: { buffers: legacyBuffers, currentProjectCandidates: legacyCandidates },
+    transcripts,
+    mcp: {
+      command: cliNames.canonicalName, args: ["mcp"], toolCount: TOOLS.length,
+    },
+    nextActions: [
+      ...(serveRunning && serveInfo && serveInfo.docsPort
+        ? [{ kind: "open_docs", label: "Open Docs", url: `http://127.0.0.1:${serveInfo.docsPort}/` }]
+        : []),
+      ...(legacyCandidates > 0
+        ? [{ kind: "review_legacy", label: "Review legacy candidates" }]
+        : []),
+      ...(transcriptNew > 0 || transcriptUpdated > 0
+        ? [{ kind: "review_transcripts", label: "Review unimported Claude transcripts" }]
+        : []),
+    ],
+    _meta: { echoHome, collectedAt: new Date().toISOString() },
+  };
+}
+
+module.exports = { collectStatus };

package/scripts/lib/usecases/strip-comments.js

@@ -0,0 +1,7 @@
+function stripCommentSections(text) {
+  return text
+    .replace(/<!-- ECHO_COMMENTS_START -->[\s\S]*?<!-- ECHO_COMMENTS_END -->\n*/g, "")
+    .replace(/<!-- ECHO:COMMENT_LIST -->\n*/g, "");
+}
+
+module.exports = { stripCommentSections };

package/scripts/lib/usecases/write-comment.js

@@ -0,0 +1,122 @@
+const fs = require("fs");
+const path = require("path");
+const matter = require("gray-matter");
+
+const { stripCommentSections } = require("./strip-comments");
+const anchor = require("../domain/anchor");
+
+function writeComment(opts) {
+  const { articleId, quote, comment, author, scope, dirs, store } = opts;
+  const evKind = opts.evolutionKind || "null";
+  const evOf = opts.evolutionOf || [];
+  const finalStatus = opts.status || "open";
+
+  const { articlesDir, commentsDir } = dirs;
+  const authorName = author || "vincent";
+
+  // Load article
+  const loaded = store.loadArticleById(articlesDir, articleId);
+  if (!loaded) {
+    const err = new Error(`Article "${articleId}" not found.`);
+    err.availableArticles = store.loadArticles(articlesDir).map((a) => ({ id: a.id, relPath: a.relPath }));
+    throw err;
+  }
+
+  const body = stripCommentSections(loaded.content);
+  const d = new Date();
+  const off = -d.getTimezoneOffset();
+  const sign = off >= 0 ? "+" : "-";
+  const pad = (n) => String(Math.abs(n)).padStart(2, "0");
+  const now = d.getFullYear() + "-" +
+    pad(d.getMonth() + 1) + "-" +
+    pad(d.getDate()) + "T" +
+    pad(d.getHours()) + ":" +
+    pad(d.getMinutes()) + ":" +
+    pad(d.getSeconds()) +
+    sign + pad(Math.floor(Math.abs(off) / 60)) + ":" + pad(Math.abs(off) % 60);
+  const newId = store.nextAnnotationId(commentsDir);
+
+  if (scope === "article") {
+    const frontmatter = {
+      id: newId,
+      type: "annotation",
+      target: { article_id: articleId, path: loaded.relPath },
+      anchor: { kind: "article" },
+      author: authorName,
+      created_at: now,
+      updated_at: now,
+      status: finalStatus,
+      tags: [],
+      evolution: { of: evOf, kind: evKind },
+    };
+    const fileContent = matter.stringify(comment.trim(), frontmatter);
+
+    if (!fs.existsSync(commentsDir)) fs.mkdirSync(commentsDir, { recursive: true });
+    const outPath = path.join(commentsDir, `${newId}.md`);
+    fs.writeFileSync(outPath, fileContent);
+    return { id: newId, articleId, scope: "article" };
+  }
+
+  // Inline comment: quote required, resolve anchor
+  if (!quote) {
+    throw new Error("quote is required for inline comments (or set scope: 'article')");
+  }
+
+  // Resolve anchor position
+  let positions;
+  if (opts.prefix && opts.suffix && opts.occurrence) {
+    // Use caller-provided anchor data, validate it
+    const resolved = anchor.resolveAnchor(
+      { anchor: { quote: opts.quote, prefix: opts.prefix, suffix: opts.suffix, line_hint: opts.lineHint } },
+      body
+    );
+    if (resolved.status === "broken") {
+      throw new Error(`Anchor invalid: ${resolved.reason}`);
+    }
+    positions = [resolved.position];
+  } else {
+    // Auto-discover
+    const searchBody = anchor.stripInlineFormatting(body);
+    const searchQuote = anchor.stripInlineFormatting(quote);
+    positions = anchor.findAllPositions(searchBody, searchQuote);
+
+    if (positions.length === 0) {
+      throw new Error(`Quote not found in article "${articleId}".`);
+    }
+  }
+
+  const chosen = positions[(opts.occurrence || 1) - 1] || positions[0];
+  const occurrenceIdx = positions.indexOf(chosen);
+
+  // Compute anchor metadata
+  const searchBody = anchor.stripInlineFormatting(body);
+  const searchQuote = anchor.stripInlineFormatting(quote);
+  const prefixRaw = searchBody.slice(Math.max(0, chosen.index - 100), chosen.index).trim();
+  const suffixRaw = searchBody.slice(chosen.index + searchQuote.length, chosen.index + searchQuote.length + 100).trim();
+
+  const frontmatter = {
+    id: newId,
+    type: "annotation",
+    target: { article_id: articleId, path: loaded.relPath },
+    anchor: { quote, prefix: prefixRaw, suffix: suffixRaw, occurrence: occurrenceIdx + 1, line_hint: chosen.line },
+    author: authorName,
+    created_at: now,
+    updated_at: now,
+    status: finalStatus,
+    tags: [],
+    evolution: { of: evOf, kind: evKind },
+  };
+  const fileContent = matter.stringify(comment.trim(), frontmatter);
+
+  if (!fs.existsSync(commentsDir)) fs.mkdirSync(commentsDir, { recursive: true });
+  const outPath = path.join(commentsDir, `${newId}.md`);
+
+  if (fs.existsSync(outPath)) {
+    throw new Error(`${newId}.md already exists in comments directory.`);
+  }
+
+  fs.writeFileSync(outPath, fileContent);
+  return { id: newId, articleId, scope: "inline" };
+}
+
+module.exports = { writeComment };

package/scripts/resolve.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+const { ensureDir } = require("./lib/infra/workspace");
+const { resolveDataDirs } = require("./lib/infra/echo-paths");
+const store = require("./lib/infra/markdown-store");
+const { resolveAnchor } = require("./lib/domain/anchor");
+const { stripCommentSections } = require("./lib/usecases/strip-comments");
+
+function runResolve(opts = {}) {
+  const dirs = opts.dirs || resolveDataDirs();
+  const { articlesDir, commentsDir } = dirs;
+
+  ensureDir(articlesDir);
+  ensureDir(commentsDir);
+
+  const articles = {};
+  for (const [id, a] of Object.entries(store.indexArticles(store.loadArticles(articlesDir)))) {
+    articles[id] = { data: a.data, body: stripCommentSections(a.content), file: a.relPath };
+  }
+
+  const comments = store.loadComments(commentsDir);
+
+  let ok = 0;
+  let broken = 0;
+  let needsReview = 0;
+  let ambiguous = 0;
+
+  for (const c of comments) {
+    const articleId = c.target?.article_id;
+    if (!articleId || !articles[articleId]) {
+      console.log(`${c._file}: SKIP — article "${articleId}" not found`);
+      continue;
+    }
+
+    const result = resolveAnchor(c, articles[articleId].body);
+
+    switch (result.status) {
+      case "ok":
+        ok++;
+        break;
+      case "broken":
+        broken++;
+        console.log(`${c._file}: BROKEN — ${result.reason}`);
+        break;
+      case "needs_review":
+        needsReview++;
+        console.log(`${c._file}: NEEDS_REVIEW — ${result.reason} (guessed line ${result.position?.line})`);
+        break;
+      case "ambiguous":
+        ambiguous++;
+        console.log(`${c._file}: AMBIGUOUS — ${result.reason}`);
+        break;
+    }
+  }
+
+  console.log(`\n${ok} ok, ${broken} broken, ${needsReview} needs_review, ${ambiguous} ambiguous`);
+
+  return { ok, broken, needsReview, ambiguous };
+}
+
+if (require.main === module) {
+  const result = runResolve();
+  process.exit(result.broken > 0 ? 1 : 0);
+}
+
+module.exports = { runResolve };

package/scripts/search.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+const { ensureDir } = require("./lib/infra/workspace");
+const { resolveDataDirs } = require("./lib/infra/echo-paths");
+const store = require("./lib/infra/markdown-store");
+
+function runSearch(opts = {}) {
+  const dirs = opts.dirs || resolveDataDirs();
+  const { articlesDir } = dirs;
+
+  ensureDir(articlesDir);
+
+  const keyword = opts.keyword || "";
+  const tag = opts.tag || "";
+
+  if (!keyword && !tag) {
+    if (!opts.silent) {
+      console.log("Usage: npm run search -- --keyword <text> [--tag <tag>]");
+      console.log("  --keyword, -k   Full-text search in article body");
+      console.log("  --tag, -t       Filter by tag");
+    }
+    return { results: [], count: 0 };
+  }
+
+  const articles = store.loadArticles(articlesDir).map((a) => ({
+    ...a.data,
+    _file: a.relPath,
+    _content: a.content,
+  }));
+
+  let results = articles;
+
+  if (tag) {
+    const tagLower = tag.toLowerCase();
+    results = results.filter((a) =>
+      (a.tags || []).some((t) => t.toLowerCase() === tagLower)
+    );
+  }
+
+  if (keyword) {
+    const kw = keyword.toLowerCase();
+    results = results
+      .map((a) => {
+        const body = a._content.toLowerCase();
+        const aliasMatch = (a.alias || "").toLowerCase().includes(kw);
+        const idx = body.indexOf(kw);
+        if (idx === -1 && !aliasMatch) return null;
+        const start = Math.max(0, idx - 40);
+        const end = Math.min(body.length, idx + kw.length + 40);
+        let snippet = a._content.slice(start, end).replace(/\n/g, " ");
+        if (start > 0) snippet = "..." + snippet;
+        if (end < body.length) snippet = snippet + "...";
+        return { ...a, alias: a.alias || "", _snippet: snippet };
+      })
+      .filter(Boolean);
+  }
+
+  if (!keyword) {
+    results = results.map((a) => ({ ...a, alias: a.alias || "" }));
+  }
+
+  return { results, count: results.length };
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const opts = { keyword: "", tag: "" };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--keyword" || args[i] === "-k") opts.keyword = args[++i] || "";
+    else if (args[i] === "--tag" || args[i] === "-t") opts.tag = args[++i] || "";
+  }
+
+  const result = runSearch(opts);
+
+  if (!opts.keyword && !opts.tag) {
+    process.exit(0);
+  }
+
+  if (result.count === 0) {
+    const filters = [];
+    if (opts.keyword) filters.push(`keyword="${opts.keyword}"`);
+    if (opts.tag) filters.push(`tag="${opts.tag}"`);
+    console.log(`No results for ${filters.join(", ")}.`);
+    process.exit(0);
+  }
+
+  console.log(`${result.count} result(s):\n`);
+  for (const a of result.results) {
+    const ca = a.created_at;
+    const d = ca instanceof Date ? ca.toISOString().slice(0, 10) : String(ca || "").slice(0, 10);
+    console.log(`  ${a.title || a.id}`);
+    console.log(`  ${a._file}  ·  ${d}`);
+    if (a._snippet) console.log(`  > ${a._snippet}`);
+    if (a.tags && a.tags.length) console.log(`  tags: ${a.tags.join(", ")}`);
+    console.log();
+  }
+}
+
+module.exports = { runSearch };