echoctl 0.1.0

package/scripts/cli/commands/status.js

@@ -0,0 +1,11 @@
+function run(args) {
+  const json = args.includes("--json");
+  const langIdx = args.indexOf("--lang");
+  const lang = langIdx !== -1 ? args[langIdx + 1] : (process.env.ECHO_LANG || null);
+  const { collectStatus } = require("../../lib/usecases/status-collector");
+  const { formatStatus } = require("../../lib/i18n/format");
+  const model = collectStatus();
+  console.log(formatStatus(model, { json, lang }));
+}
+
+module.exports = run;

package/scripts/cli/commands/stop.js

@@ -0,0 +1,136 @@
+function run(args) {
+    (async () => {
+      const {
+        readServeInfo,
+        clearServeInfo,
+        findServeProcessCandidates,
+        isValidPositivePid,
+        verifyProcessIdentity,
+      } = require("../../serve");
+
+      function childPidsFrom(info) {
+        return [
+          ...(Array.isArray(info.childPids) ? info.childPids : []),
+          info.vitepressPid,
+        ].filter((pid, index, arr) => isValidPositivePid(pid) && pid !== info.pid && arr.indexOf(pid) === index);
+      }
+
+      function signalPid(pid, signal = "SIGTERM") {
+        try {
+          process.kill(pid, signal);
+          return true;
+        } catch (err) {
+          if (err.code === "ESRCH") return false;
+          throw err;
+        }
+      }
+
+      function stopExtraPids(pids) {
+        const stopped = [];
+        for (const pid of pids) {
+          if (signalPid(pid)) stopped.push(pid);
+        }
+        return stopped;
+      }
+
+      let info;
+      try {
+        info = readServeInfo();
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        clearServeInfo();
+        process.exit(1);
+      }
+      if (!info) {
+        const candidates = findServeProcessCandidates();
+        if (candidates.length === 0) {
+          console.log("No running serve instance found.");
+          process.exit(0);
+        }
+        const stopped = stopExtraPids(candidates.map((p) => p.pid));
+        if (stopped.length > 0) {
+          console.log(`No serve state found, but stopped orphaned Echo process(es): ${stopped.join(", ")}.`);
+        } else {
+          console.log("No running serve instance found.");
+        }
+        clearServeInfo();
+        process.exit(0);
+      }
+
+      const pid = info.pid;
+      if (!isValidPositivePid(pid)) {
+        console.error(`Error: invalid pid in serve state: ${JSON.stringify(info)}. Cleaning up.`);
+        clearServeInfo();
+        process.exit(1);
+      }
+
+      // Verify the pid is alive, owned by us, and is an echo serve process
+      try {
+        process.kill(pid, 0);
+      } catch (err) {
+        if (err.code === "ESRCH") {
+          console.log(`Process ${pid} is no longer running.`);
+          const stopped = stopExtraPids(childPidsFrom(info));
+          if (stopped.length > 0) console.log(`Stopped child process(es): ${stopped.join(", ")}.`);
+          clearServeInfo();
+          process.exit(0);
+        }
+        if (err.code === "EPERM") {
+          console.error(`Error: process ${pid} belongs to another user. Cannot stop.`);
+          process.exit(1);
+        }
+        throw err;
+      }
+
+      if (!verifyProcessIdentity(info)) {
+        console.error(`Error: process ${pid} is not an echo serve. PID may have been reused. State file preserved — check manually.`);
+        process.exit(1);
+      }
+
+      // Send SIGTERM — handle race where process exits between check and signal
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch (err) {
+        if (err.code === "ESRCH") {
+          console.log(`Process ${pid} already exited.`);
+          clearServeInfo();
+          process.exit(0);
+        }
+        throw err;
+      }
+      console.log(`Sent SIGTERM to serve (pid ${pid}, API port ${info.apiPort}, docs port ${info.docsPort}).`);
+
+      // Poll for exit (2s timeout, 100ms intervals)
+      const POLL_MS = 2000;
+      const INTERVAL_MS = 100;
+      const startTime = Date.now();
+      let exited = false;
+      while (Date.now() - startTime < POLL_MS) {
+        await new Promise((r) => setTimeout(r, INTERVAL_MS));
+        try {
+          process.kill(pid, 0);
+        } catch (err) {
+          if (err.code === "ESRCH") {
+            exited = true;
+            break;
+          }
+          throw err;
+        }
+      }
+
+      if (exited) {
+        const stopped = stopExtraPids(childPidsFrom(info));
+        if (stopped.length > 0) console.log(`Stopped child process(es): ${stopped.join(", ")}.`);
+        console.log(`Serve stopped (pid ${pid}).`);
+        clearServeInfo();
+      } else {
+        console.error(`Warning: SIGTERM sent but process ${pid} is still running. State file preserved — check the process manually.`);
+        process.exit(1);
+      }
+    })().catch((err) => {
+      console.error(`Failed to stop serve: ${err.message}`);
+      process.exit(1);
+    });
+}
+
+module.exports = run;

package/scripts/cli/commands/tag.js

@@ -0,0 +1,89 @@
+const { commandFor } = require("../../lib/cli/names");
+
+function run(args) {
+    const { resolveDataDirs } = require("../../lib/infra/echo-paths");
+    const store = require("../../lib/infra/markdown-store");
+    const { listTags, addTags, removeTags, renameTag, purgeTag } = require("../../lib/usecases/query-articles");
+    const dirs = resolveDataDirs();
+    const deps = { dirs, store };
+    const sub = args[1];
+
+    if (sub === "list") {
+      const tags = listTags({}, deps);
+      if (tags.length === 0) {
+        console.log("No tags found.");
+      } else {
+        console.log(`${"Tag".padEnd(30)} Usage`);
+        console.log("-".repeat(42));
+        for (const { tag, count } of tags) {
+          console.log(`${tag.padEnd(30)} ${count}`);
+        }
+      }
+    } else if (sub === "add") {
+      const articleId = args[2];
+      const tags = args.slice(3);
+      if (!articleId || tags.length === 0) {
+        console.error(`Usage: ${commandFor(["tag", "add", "<article-id>", "<tag1>", "[tag2...]"])}`);
+        process.exit(1);
+      }
+      try {
+        const result = addTags({ id: articleId, tags }, deps);
+        console.log(`Article: ${result.id}`);
+        console.log(`Tags:   ${result.tags.join(", ")}`);
+        console.log(`Added:  ${result.added.join(", ")}`);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    } else if (sub === "remove") {
+      const articleId = args[2];
+      const tags = args.slice(3);
+      if (!articleId || tags.length === 0) {
+        console.error(`Usage: ${commandFor(["tag", "remove", "<article-id>", "<tag1>", "[tag2...]"])}`);
+        process.exit(1);
+      }
+      try {
+        const result = removeTags({ id: articleId, tags }, deps);
+        console.log(`Article: ${result.id}`);
+        console.log(`Tags:    ${result.tags.join(", ") || "(none)"}`);
+        console.log(`Removed: ${result.removed.join(", ")}`);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    } else if (sub === "rename") {
+      const oldTag = args[2];
+      const newTag = args[3];
+      if (!oldTag || !newTag) {
+        console.error(`Usage: ${commandFor(["tag", "rename", "<old-tag>", "<new-tag>"])}`);
+        process.exit(1);
+      }
+      try {
+        const result = renameTag({ oldTag, newTag }, deps);
+        console.log(`Renamed: ${result.oldTag} → ${result.newTag}`);
+        console.log(`Updated: ${result.renamed} article(s)`);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    } else if (sub === "purge") {
+      const tag = args[2];
+      if (!tag) {
+        console.error(`Usage: ${commandFor(["tag", "purge", "<tag>"])}`);
+        process.exit(1);
+      }
+      try {
+        const result = purgeTag({ tag }, deps);
+        console.log(`Purged:  ${result.tag}`);
+        console.log(`Removed: from ${result.purged} article(s)`);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    } else {
+      console.error(`Usage: ${commandFor(["tag", "list|add|remove|rename|purge"])}`);
+      process.exit(1);
+    }
+}
+
+module.exports = run;

package/scripts/cli/echoctl.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+const { USAGE } = require("./commands/constants");
+
+const commands = {
+  status:     require("./commands/status"),
+  hook:       require("./commands/hook"),
+  init:       require("./commands/init"),
+  project:    require("./commands/project"),
+  doctor:     require("./commands/doctor"),
+  migrate:    require("./commands/migrate"),
+  refresh:    require("./commands/refresh"),
+  all:        require("./commands/pipeline"),
+  convert:    require("./commands/pipeline"),
+  validate:   require("./commands/pipeline"),
+  resolve:    require("./commands/pipeline"),
+  search:     require("./commands/search"),
+  mcp:        require("./commands/mcp"),
+  import:     require("./commands/import_cmd"),
+  serve:      require("./commands/serve"),
+  stop:       require("./commands/stop"),
+  capture:    require("./commands/capture"),
+  tag:        require("./commands/tag"),
+};
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+if (cmd === "--version" || cmd === "-v" || cmd === "-V") {
+  const { version } = require("../../package.json");
+  console.log(version);
+  process.exit(0);
+}
+
+if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+if (commands[cmd]) {
+  commands[cmd](args);
+} else {
+  console.log(USAGE);
+  process.exit(cmd ? 1 : 0);
+}

package/scripts/convert.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const { ensureDir } = require("./lib/infra/workspace");
+const { resolveDataDirs } = require("./lib/infra/echo-paths");
+const { parseBuffer, buildArticle } = require("./lib/usecases/convert-buffer");
+
+function runConvert(opts = {}) {
+  const dirs = opts.dirs || resolveDataDirs();
+  const { bufferDir, articlesDir } = dirs;
+
+  ensureDir(articlesDir);
+  ensureDir(bufferDir);
+
+  const bufferFiles = fs.readdirSync(bufferDir)
+    .filter((f) => f.startsWith("session-") && f.endsWith(".md"))
+    .sort();
+
+  const files = [];
+
+  if (bufferFiles.length === 0) {
+    if (!opts.silent) console.log("No buffer files to convert.");
+    return { files, bufferDir, articlesDir };
+  }
+
+  for (const bf of bufferFiles) {
+    const bufferPath = path.join(bufferDir, bf);
+    const raw = fs.readFileSync(bufferPath, "utf-8");
+    const { turns } = parseBuffer(raw);
+    if (turns.length === 0) { console.log(`${bf}: empty — skipped`); continue; }
+
+    const { id, article, title, turnCount } = buildArticle(bf, turns, { project: dirs.projectId });
+    const articlePath = path.join(articlesDir, `${id}.md`);
+
+    if (fs.existsSync(articlePath)) {
+      const existingTurns = (fs.readFileSync(articlePath, "utf-8").match(/<!-- turn:/g) || []).length;
+      if (existingTurns === turnCount) {
+        if (!opts.silent) console.log(`${id}.md: unchanged (${turnCount} turns) — skipped`);
+        continue;
+      }
+    }
+
+    fs.writeFileSync(articlePath, article);
+    console.log(`${id}.md: created (${turnCount} turns) — "${title}"`);
+    files.push({ id, title, turnCount });
+  }
+
+  return { files, bufferDir, articlesDir };
+}
+
+if (require.main === module) {
+  runConvert();
+}
+
+module.exports = { runConvert };

package/scripts/import-sessions.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { ensureDir } = require("./lib/infra/workspace");
+const { resolveDataDirs } = require("./lib/infra/echo-paths");
+const ef = require("./lib/domain/echo-format");
+
+// ---- helpers ----
+
+function isSystemNoise(text) {
+  if (!text || !text.trim()) return true;
+  const t = text.trim();
+  if (t.startsWith("Base directory for this skill:")) return true;
+  if (t.startsWith("<!-- AUTO-GENERATED")) return true;
+  if (/^```bash\n_UPD=/.test(t)) return true;
+  if (t.startsWith("<local-command-caveat>")) return true;
+  if (t.startsWith("<command-name>")) return true;
+  if (t.startsWith("<command-message>")) return true;
+  if (t.startsWith("<command-args>")) return true;
+  if (t.startsWith("<local-command-stdout>")) return true;
+  if (t.length > 3000) return true;
+  return false;
+}
+
+function cleanUserMessage(content) {
+  if (typeof content === "string") return content.trim();
+  if (Array.isArray(content)) {
+    return content
+      .filter((b) => b.type === "text")
+      .map((b) => b.text || "")
+      .join(" ")
+      .trim();
+  }
+  return "";
+}
+
+function cleanAssistantBlocks(blocks) {
+  if (!Array.isArray(blocks)) return [];
+  const out = [];
+  for (const b of blocks) {
+    if (b.type === "text" && b.text) {
+      out.push({ type: "text", content: b.text.trim() });
+    } else if (b.type === "tool_use") {
+      out.push({ type: "tool", content: `[调用工具: ${b.name}]` });
+    }
+  }
+  const merged = [];
+  for (const item of out) {
+    if (item.type === "text" && merged.length > 0 && merged[merged.length - 1].type === "text") {
+      merged[merged.length - 1].content += "\n\n" + item.content;
+    } else {
+      merged.push(item);
+    }
+  }
+  return merged;
+}
+
+function formatDate(isoStr) {
+  return isoStr.slice(0, 10);
+}
+
+function parseSession(filePath) {
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const lines = raw.trim().split("\n");
+
+  const events = [];
+  for (const line of lines) {
+    try { events.push(JSON.parse(line)); } catch (_) {}
+  }
+
+  const turns = [];
+  let pendingUser = null;
+  let pendingAssistantBlocks = [];
+  let models = new Set();
+  let firstTs = null;
+  let lastTs = null;
+
+  function flushAssistant() {
+    if (pendingAssistantBlocks.length === 0) return;
+    const cleaned = cleanAssistantBlocks(pendingAssistantBlocks);
+    const text = cleaned.map((c) => c.content).join("\n\n").trim();
+    if (text) turns.push({ speaker: "ai", content: text });
+    pendingAssistantBlocks = [];
+  }
+
+  function flushUser() {
+    if (pendingUser !== null) {
+      turns.push({ speaker: "vincent", content: pendingUser });
+      pendingUser = null;
+    }
+  }
+
+  for (const ev of events) {
+    if (ev.timestamp) {
+      if (!firstTs) firstTs = ev.timestamp;
+      lastTs = ev.timestamp;
+    }
+
+    if (ev.type === "user") {
+      const text = cleanUserMessage(ev.message?.content || "");
+      if (text && !isSystemNoise(text)) {
+        flushAssistant();
+        flushUser();
+        pendingUser = text;
+      }
+    } else if (ev.type === "assistant") {
+      const msg = ev.message || {};
+      const blocks = msg.content || [];
+      const model = msg.model || "";
+      if (model && model !== "<synthetic>") models.add(model);
+      for (const b of blocks) {
+        pendingAssistantBlocks.push(b);
+      }
+    }
+  }
+
+  flushAssistant();
+  flushUser();
+
+  return { turns, models: [...models], firstTs, lastTs };
+}
+
+function buildArticle(sessionId, turns, models, firstTs, opts = {}) {
+  const date = firstTs ? formatDate(firstTs) : "unknown-date";
+  const id = `session-${sessionId.slice(0, 8)}`;
+  const dateStr = `${date}T00:00:00+08:00`;
+
+  const speakers = {
+    human: { id: "vincent", role: "human" },
+    ai: { id: "ai", role: "ai", model: models[0] || "unknown" },
+  };
+
+  const article = ef.createArticle({
+    id,
+    created_at: dateStr,
+    alias: ef.inferTitle(turns),
+    source_session: sessionId,
+    turns,
+    speakers,
+    project: opts.project,
+  });
+
+  return { id, article: ef.toMarkdown(article), title: article.title, alias: article.alias, turnCount: article.turns.length };
+}
+
+function runImportSessions(opts = {}) {
+  const dirs = opts.dirs || resolveDataDirs();
+  const { articlesDir } = dirs;
+
+  const PROJECT = opts.project || process.argv[2] || "-Users-vincenthuang-myNote";
+  const SESSIONS_DIR = path.join(os.homedir(), ".claude", "projects", PROJECT);
+  const MIN_REAL_TURNS = opts.minTurns || 2;
+
+  // Resolve project ID from cwd
+  let importProject = dirs.projectId;
+  if (!importProject) {
+    try {
+      const { findProjectForPath } = require("./lib/usecases/project-registry");
+      const project = findProjectForPath(opts.cwd || process.cwd());
+      if (project) importProject = project.projectId;
+    } catch (_) {}
+  }
+
+  ensureDir(articlesDir);
+
+  if (!fs.existsSync(SESSIONS_DIR)) {
+    console.error(`Sessions directory not found: ${SESSIONS_DIR}`);
+    process.exit(1);
+  }
+
+  const files = fs.readdirSync(SESSIONS_DIR)
+    .filter((f) => f.endsWith(".jsonl"))
+    .sort();
+
+  console.log(`Scanning ${files.length} session files in ${SESSIONS_DIR}...\n`);
+
+  let imported = 0;
+  let skipped = 0;
+
+  for (const file of files) {
+    const filePath = path.join(SESSIONS_DIR, file);
+    const sessionId = path.basename(file, ".jsonl");
+
+    try {
+      const { turns, models, firstTs } = parseSession(filePath);
+      const realTurns = turns.filter((t) => t.speaker === "vincent").length;
+
+      if (realTurns < MIN_REAL_TURNS) {
+        skipped++;
+        continue;
+      }
+
+      const { id, article, title, turnCount } = buildArticle(sessionId, turns, models, firstTs, { project: importProject });
+      const articlePath = path.join(articlesDir, `${id}.md`);
+
+      fs.writeFileSync(articlePath, article);
+      console.log(`${id}.md ← ${sessionId} (${turnCount} turns, ${models.length} models) — "${title}"`);
+      imported++;
+    } catch (err) {
+      console.error(`${sessionId}: ERROR — ${err.message}`);
+    }
+  }
+
+  console.log(`\nDone: ${imported} imported, ${skipped} skipped.`);
+  return { imported, skipped };
+}
+
+if (require.main === module) {
+  runImportSessions();
+}
+
+module.exports = { runImportSessions };

package/scripts/index.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const { ensureDir } = require("./lib/infra/workspace");
+const { resolveDataDirs } = require("./lib/infra/echo-paths");
+const store = require("./lib/infra/markdown-store");
+
+function runIndex(opts = {}) {
+  const dirs = opts.dirs || resolveDataDirs();
+  const { articlesDir, commentsDir } = dirs;
+
+  ensureDir(articlesDir);
+  ensureDir(commentsDir);
+
+  const comments = store.loadComments(commentsDir).sort(
+    (a, b) => String(a.created_at).localeCompare(String(b.created_at))
+  );
+
+  const articles = store.indexArticles(store.loadArticles(articlesDir));
+
+  function buildCommentList(articleId) {
+    const articleComments = comments.filter(
+      (c) => c.target?.article_id === articleId
+    );
+    if (articleComments.length === 0) return "<!-- ECHO_COMMENTS_START -->\n\n<!-- ECHO_COMMENTS_END -->";
+
+    const lines = ["<!-- ECHO_COMMENTS_START -->", "", "## 评论区", ""];
+    for (const c of articleComments) {
+      const quote = c.anchor?.quote || c.id;
+      const author = c.author;
+      const d = new Date(c.created_at);
+      const date = isNaN(d.getTime()) ? String(c.created_at || "").slice(0, 10)
+        : d.toISOString().slice(0, 10);
+      let line = `- [${quote}](${c._file}) — ${author} · ${date}`;
+
+      const ofList = c.evolution?.of || [];
+      if (ofList.length > 0) {
+        const targets = ofList.map((tid) => {
+          const t = comments.find((x) => x.id === tid);
+          const tQuote = t?.anchor?.quote || tid;
+          const tFile = t?._file || "";
+          return `["${tQuote}"](${tFile})`;
+        });
+        line += " → " + targets.join(", ");
+      }
+      lines.push(line);
+    }
+    lines.push("", "<!-- ECHO_COMMENTS_END -->");
+    return lines.join("\n");
+  }
+
+  const updated = [];
+
+  for (const [id, article] of Object.entries(articles)) {
+    const commentSection = buildCommentList(id);
+    const filePath = article.absPath;
+    const raw = fs.readFileSync(filePath, "utf-8");
+
+    let newRaw;
+    const startMarker = "<!-- ECHO_COMMENTS_START -->";
+    const endMarker = "<!-- ECHO_COMMENTS_END -->";
+    const legacyMarker = "<!-- ECHO:COMMENT_LIST -->";
+
+    if (raw.includes(startMarker) && raw.includes(endMarker)) {
+      newRaw = raw.replace(
+        new RegExp(startMarker + "[\\s\\S]*" + endMarker, "g"),
+        commentSection
+      );
+      console.log(`${article.relPath}: re-indexed (${comments.filter((c) => c.target?.article_id === id).length} comments)`);
+    } else if (raw.includes(legacyMarker)) {
+      newRaw = raw.replace(legacyMarker, commentSection);
+      console.log(`${article.relPath}: first index (${comments.filter((c) => c.target?.article_id === id).length} comments)`);
+    } else {
+      newRaw = raw.trimEnd() + "\n\n" + commentSection + "\n";
+      console.log(`${article.relPath}: appended (${comments.filter((c) => c.target?.article_id === id).length} comments)`);
+    }
+
+    if (newRaw === raw) {
+      console.log(`${article.relPath}: unchanged — skipped`);
+    } else {
+      fs.writeFileSync(filePath, newRaw);
+      updated.push(article.relPath);
+    }
+  }
+
+  return { updated, articleCount: Object.keys(articles).length, commentCount: comments.length };
+}
+
+if (require.main === module) {
+  runIndex();
+}
+
+module.exports = { runIndex };

package/scripts/lib/cli/names.js

@@ -0,0 +1,33 @@
+// Central CLI naming configuration — single source of truth for all command names.
+// Usage: require("../cli/names") — then use commandFor(...) for output, isKnownCliCommand() for detection.
+
+const cliNames = {
+  canonicalName: "echoctl",
+  legacyNames: ["echo-mcp"],
+};
+
+const mcpServerInfo = {
+  name: "echo-mcp",
+  version: "0.2.0",
+};
+
+function commandFor(args) {
+  return [cliNames.canonicalName, ...args].join(" ");
+}
+
+function allCliNames() {
+  return [cliNames.canonicalName, ...cliNames.legacyNames];
+}
+
+function isKnownCliCommand(command) {
+  if (typeof command !== "string") return false;
+  return allCliNames().some((name) => command === name || command.startsWith(`${name} `));
+}
+
+module.exports = {
+  cliNames,
+  mcpServerInfo,
+  commandFor,
+  allCliNames,
+  isKnownCliCommand,
+};