echoctl 0.1.0

package/scripts/lib/i18n/messages/en.js

@@ -0,0 +1,41 @@
+// English messages for Echo CLI output
+module.exports = {
+  "status.title": "Echo status",
+  "section.serve": "Serve",
+  "section.capture": "Capture",
+  "section.hook": "Claude hook",
+  "section.project": "Current project",
+  "section.data": "Data",
+  "section.legacy": "Legacy",
+  "section.mcp": "MCP",
+  "section.next": "Next",
+  "field.status": "Status",
+  "field.docs": "Docs",
+  "field.api": "API",
+  "field.pid": "PID",
+  "field.log": "Log",
+  "field.captureStatus": "Auto capture",
+  "field.hookStatus": "Claude hook",
+  "field.projectStatus": "Status",
+  "field.project": "Project",
+  "field.root": "Root",
+  "field.dataRoot": "Data",
+  "field.liveBuffers": "Live buffers",
+  "field.articles": "Articles",
+  "field.comments": "Comments",
+  "field.legacyBuffers": "Legacy buffers",
+  "field.legacyCandidates": "Current project candidates",
+  "field.config": "Config",
+  "field.tools": "Tools",
+  "value.running": "running",
+  "value.stopped": "stopped",
+  "value.on": "on",
+  "value.off": "off",
+  "value.installed": "installed",
+  "value.missing": "missing",
+  "value.registered": "registered",
+  "value.unregistered": "unregistered",
+  "value.available": "available",
+  "next.openDocs": "Open Docs",
+  "next.reviewLegacy": "Review legacy candidates in the web UI.",
+};

package/scripts/lib/i18n/messages/zh-CN.js

@@ -0,0 +1,40 @@
+module.exports = {
+  "status.title": "Echo 状态",
+  "section.serve": "服务",
+  "section.capture": "收集",
+  "section.hook": "Claude 钩子",
+  "section.project": "当前项目",
+  "section.data": "数据",
+  "section.legacy": "历史待处理",
+  "section.mcp": "AI 访问接口",
+  "section.next": "下一步",
+  "field.status": "状态",
+  "field.docs": "文档地址",
+  "field.api": "接口地址",
+  "field.pid": "进程号",
+  "field.log": "日志",
+  "field.captureStatus": "自动收集",
+  "field.hookStatus": "Claude 钩子",
+  "field.projectStatus": "状态",
+  "field.project": "项目",
+  "field.root": "根目录",
+  "field.dataRoot": "数据目录",
+  "field.liveBuffers": "实时会话缓存",
+  "field.articles": "文章",
+  "field.comments": "评论",
+  "field.legacyBuffers": "legacy 会话",
+  "field.legacyCandidates": "当前项目候选",
+  "field.config": "配置",
+  "field.tools": "工具",
+  "value.running": "运行中",
+  "value.stopped": "已停止",
+  "value.on": "开启",
+  "value.off": "关闭",
+  "value.installed": "已安装",
+  "value.missing": "未安装",
+  "value.registered": "已注册",
+  "value.unregistered": "未注册",
+  "value.available": "个可用",
+  "next.openDocs": "打开网页",
+  "next.reviewLegacy": "请在网页中确认是否迁移 legacy 会话。",
+};

package/scripts/lib/import/manifest.js

@@ -0,0 +1,87 @@
+const fs = require("fs");
+const path = require("path");
+
+const MANIFEST_VERSION = 1;
+
+function loadManifest(manifestPath) {
+  if (!fs.existsSync(manifestPath)) {
+    return { version: MANIFEST_VERSION, imports: {} };
+  }
+  let raw = "";
+  try {
+    raw = fs.readFileSync(manifestPath, "utf-8");
+    if (!raw.trim()) return { version: MANIFEST_VERSION, imports: {} };
+    const data = JSON.parse(raw);
+    return {
+      version: data.version || MANIFEST_VERSION,
+      imports: data.imports || {},
+    };
+  } catch (e) {
+    if (raw.trim() && raw.trim()[0] === "{") {
+      throw new Error(`corrupt manifest JSON: ${e.message}`);
+    }
+    return { version: MANIFEST_VERSION, imports: {} };
+  }
+}
+
+function saveManifest(manifest, manifestPath) {
+  const dir = path.dirname(manifestPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+}
+
+function isImported(manifest, sessionId) {
+  if (!manifest || !sessionId) return false;
+  return !!(manifest.imports && manifest.imports[sessionId]);
+}
+
+function isModified(manifest, sessionId, fileHash) {
+  if (!manifest || !sessionId) return false;
+  const entry = manifest.imports && manifest.imports[sessionId];
+  if (!entry) return false;
+  return entry.fileHash !== fileHash;
+}
+
+function recordImport(manifest, sessionId, articleId, fileHash, metadata) {
+  const existing = manifest.imports && manifest.imports[sessionId];
+  if (existing && existing.fileHash === fileHash) {
+    return { success: false, reason: "duplicate", articleId: existing.articleId };
+  }
+
+  if (!manifest.imports) manifest.imports = {};
+
+  manifest.imports[sessionId] = {
+    articleId,
+    fileHash,
+    importedAt: new Date().toISOString(),
+    ...(metadata || {}),
+  };
+
+  return { success: true, articleId };
+}
+
+function validateManifest(data) {
+  if (!data || typeof data !== "object") {
+    return { valid: false, errors: ["manifest must be an object"] };
+  }
+  if (data.version !== MANIFEST_VERSION) {
+    return { valid: false, errors: [`unsupported version: ${data.version}`] };
+  }
+  if (!data.imports || typeof data.imports !== "object") {
+    return { valid: false, errors: ["imports must be an object"] };
+  }
+  for (const [sessionId, entry] of Object.entries(data.imports)) {
+    if (!entry.articleId) {
+      return { valid: false, errors: [`import ${sessionId}: missing articleId`] };
+    }
+    if (!entry.fileHash) {
+      return { valid: false, errors: [`import ${sessionId}: missing fileHash`] };
+    }
+    if (!entry.importedAt) {
+      return { valid: false, errors: [`import ${sessionId}: missing importedAt`] };
+    }
+  }
+  return { valid: true, errors: [] };
+}
+
+module.exports = { loadManifest, saveManifest, isImported, isModified, recordImport, validateManifest };

package/scripts/lib/import/providers/claude-code.js

@@ -0,0 +1,272 @@
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { renderTurnMarker } = require("../../domain/echo-format");
+
+// ---- noise detection ----
+
+const NOISE_PATTERNS = [
+  /^Base directory for this skill:/,
+  /^<!-- AUTO-GENERATED/,
+  /^```bash\n_UPD=/,
+  /^<local-command-caveat>/,
+  /^<command-name>/,
+  /^<command-message>/,
+  /^<command-args>/,
+  /^<local-command-stdout>/,
+];
+
+function isNoise(text) {
+  if (!text || !text.trim()) return true;
+  const t = text.trim();
+  if (t.length > 3000) return true;
+  for (const p of NOISE_PATTERNS) {
+    if (p.test(t)) return true;
+  }
+  if (t.startsWith("```bash") && t.includes("_UPD=")) return true;
+  return false;
+}
+
+// ---- helpers ----
+
+function normalizeSpeaker(turn) {
+  const s = (turn.speaker || turn.role || "").toLowerCase();
+  if (s === "human" || s === "user") return "human";
+  if (s === "ai" || s === "assistant" || s === "model") return "ai";
+  return s || "unknown";
+}
+
+// ---- session reading ----
+
+function readSessionTurns(filePath) {
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const lines = raw.split("\n");
+  const turns = [];
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const msgType = entry.type;
+    const msg = entry.message || {};
+    const msgRole = msg.role || (msgType === "user" ? "user" : "assistant");
+
+    let content = "";
+    if (typeof msg.content === "string") {
+      content = msg.content;
+    } else if (Array.isArray(msg.content)) {
+      const parts = [];
+      for (const b of msg.content) {
+        if (b.type === "text" && b.text) {
+          parts.push(b.text);
+        } else if (b.type === "tool_use") {
+          parts.push(`[调用工具: ${b.name}]`);
+        }
+      }
+      content = parts.join(" ");
+    }
+
+    const toolCalls = [];
+    if (Array.isArray(msg.content)) {
+      for (const b of msg.content) {
+        if (b.type === "tool_use") {
+          toolCalls.push({ name: b.name, id: b.id });
+        }
+      }
+    }
+
+    const speaker = msgRole === "user" ? "human" : "ai";
+
+    turns.push({
+      speaker,
+      content: content.trim(),
+      toolCalls,
+      timestamp: entry.timestamp || null,
+      sessionId: entry.sessionId || null,
+      model: msg.model || null,
+    });
+  }
+
+  return turns;
+}
+
+// ---- session classification ----
+
+function classifySession(turns) {
+  const humanTurns = turns.filter((t) => normalizeSpeaker(t) === "human" && !isNoise(t.content));
+  const meaningfulTurns = turns.filter((t) => !isNoise(t.content));
+
+  if (turns.length === 0) {
+    return { isMeaningful: false, reason: "empty session", turnCount: 0, userTurnCount: 0, estimatedQuality: "low" };
+  }
+
+  if (humanTurns.length === 0) {
+    return { isMeaningful: false, reason: "no user turns", turnCount: turns.length, userTurnCount: 0, estimatedQuality: "low" };
+  }
+
+  let quality = "low";
+  const avgContentLength = meaningfulTurns.reduce((sum, t) => sum + t.content.length, 0) / Math.max(meaningfulTurns.length, 1);
+
+  if (meaningfulTurns.length >= 6 && humanTurns.length >= 3) {
+    quality = "high";
+  } else if (meaningfulTurns.length >= 4 && humanTurns.length >= 2 && avgContentLength > 50) {
+    quality = "high";
+  } else if (meaningfulTurns.length >= 4 && humanTurns.length >= 2 && avgContentLength > 25) {
+    quality = "medium";
+  }
+
+  return {
+    isMeaningful: humanTurns.length >= 2 || meaningfulTurns.length >= 4,
+    reason: humanTurns.length < 2 ? `only ${humanTurns.length} user turns` : "ok",
+    turnCount: turns.length,
+    userTurnCount: humanTurns.length,
+    estimatedQuality: quality,
+  };
+}
+
+// ---- metadata extraction ----
+
+function extractMetadata(turns) {
+  const meaningfulTurns = turns.filter((t) => !isNoise(t.content));
+  const humanTurns = meaningfulTurns.filter((t) => normalizeSpeaker(t) === "human");
+
+  let title = "";
+  if (humanTurns.length > 0) {
+    title = humanTurns[0].content.slice(0, 77);
+    if (humanTurns[0].content.length > 77) title += "...";
+  }
+
+  let date = "";
+  for (const t of turns) {
+    if (t.timestamp) {
+      date = t.timestamp;
+      break;
+    }
+  }
+
+  const seenSpeakers = new Set();
+  const participants = [];
+  for (const t of meaningfulTurns) {
+    const s = normalizeSpeaker(t);
+    if (!seenSpeakers.has(s)) {
+      seenSpeakers.add(s);
+      const p = { role: s };
+      if (s === "ai" && t.model) p.model = t.model;
+      participants.push(p);
+    }
+  }
+
+  let model = "";
+  for (const t of meaningfulTurns) {
+    if (normalizeSpeaker(t) === "ai" && t.model) {
+      model = t.model;
+      break;
+    }
+  }
+
+  return { title: title || "Untitled", date, participants, model };
+}
+
+// ---- article generation ----
+
+function toEchoArticle(turns, metadata, opts = {}) {
+  const { sessionId, alias } = opts;
+  const articleId = sessionId
+    ? `session-${sessionId.slice(0, 8)}`
+    : `session-${crypto.randomUUID().slice(0, 8)}`;
+
+  const meaningfulTurns = turns.filter((t) => !isNoise(t.content));
+  const sourceHash = crypto.createHash("sha256").update(JSON.stringify(turns)).digest("hex");
+
+  // Build YAML frontmatter
+  const lines = [];
+  lines.push("---");
+  lines.push(`id: ${articleId}`);
+  lines.push(`title: "${(metadata.title || "Untitled").replace(/"/g, '\\"')}"`);
+  if (alias) lines.push(`alias: "${alias.replace(/"/g, '\\"')}"`);
+  const dateStr = metadata.date ? metadata.date.slice(0, 10) : new Date().toISOString().slice(0, 10);
+  lines.push(`created_at: ${dateStr}`);
+  lines.push("tags: []");
+  lines.push(`summary: "${(metadata.title || "").replace(/"/g, '\\"')}"`);
+
+  if (metadata.participants && metadata.participants.length > 0) {
+    lines.push("participants:");
+    for (const p of metadata.participants) {
+      lines.push(`  - id: ${p.id || p.role}`);
+      lines.push(`    role: ${p.role}`);
+      if (p.model) lines.push(`    model: ${p.model}`);
+    }
+  }
+
+  if (metadata.model) lines.push(`ai_model: ${metadata.model}`);
+
+  lines.push("source:");
+  lines.push(`  session_id: "${sessionId || ""}"`);
+  lines.push(`  source_file_hash: "${sourceHash}"`);
+  lines.push(`  imported_at: "${new Date().toISOString()}"`);
+
+  if (opts.project) lines.push(`project: ${opts.project}`);
+
+  lines.push("---");
+  lines.push("");
+
+  // Body
+  lines.push(`# ${metadata.title || "Untitled"}`);
+  lines.push("");
+
+  let turnNum = 0;
+  for (const turn of meaningfulTurns) {
+    turnNum++;
+    const speaker = normalizeSpeaker(turn);
+    const speakerLabel = speaker === "human" ? (opts.userSpeaker || "human") : (opts.aiSpeaker || "ai");
+    const turnId = `t${String(turnNum).padStart(2, "0")}`;
+    lines.push(renderTurnMarker(turnId, speakerLabel));
+    lines.push("");
+    lines.push(turn.content);
+    lines.push("");
+  }
+
+  // Comment section markers
+  lines.push("<!-- ECHO_COMMENTS_START -->");
+  lines.push("<!-- ECHO_COMMENTS_END -->");
+
+  return lines.join("\n") + "\n";
+}
+
+// ---- project scanning ----
+
+function scanProjectDir(dirPath) {
+  if (!fs.existsSync(dirPath)) return [];
+
+  const entries = fs.readdirSync(dirPath);
+  const sessions = [];
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".jsonl")) continue;
+    const filePath = path.join(dirPath, entry);
+    let stat;
+    try { stat = fs.statSync(filePath); } catch { continue; }
+    if (!stat.isFile()) continue;
+
+    const sessionId = entry.replace(/\.jsonl$/, "");
+    const content = fs.readFileSync(filePath, "utf-8");
+    const jsonlLines = content.trim().split("\n");
+    const firstLine = jsonlLines[0] ? (() => { try { return JSON.parse(jsonlLines[0]); } catch { return null; } })() : null;
+    const lastLine = jsonlLines[jsonlLines.length - 1] ? (() => { try { return JSON.parse(jsonlLines[jsonlLines.length - 1]); } catch { return null; } })() : null;
+
+    const turnCount = jsonlLines.length;
+    const firstTurn = firstLine ? firstLine.timestamp || "" : "";
+    const lastTurn = lastLine ? lastLine.timestamp || "" : "";
+
+    sessions.push({ sessionId, filePath, turnCount, firstTurn, lastTurn });
+  }
+
+  return sessions;
+}
+
+module.exports = { scanProjectDir, readSessionTurns, classifySession, extractMetadata, toEchoArticle, isNoise };

package/scripts/lib/import/scanner.js

@@ -0,0 +1,128 @@
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const DEFAULT_EXCLUSIONS = ["claude-mem-observer-sessions", "private-tmp"];
+
+function scanClaudeProjects(claudeProjectsDir, opts = {}) {
+  const excludeList = opts.excludeDirs || opts.exclude || DEFAULT_EXCLUSIONS;
+
+  if (!fs.existsSync(claudeProjectsDir)) return [];
+
+  const entries = fs.readdirSync(claudeProjectsDir);
+  const projects = [];
+
+  for (const entry of entries) {
+    if (entry.startsWith(".")) continue;
+    if (excludeList.some((p) => entry.includes(p))) continue;
+
+    const fullPath = path.join(claudeProjectsDir, entry);
+    let stat;
+    try {
+      stat = fs.statSync(fullPath);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+
+    const fileNames = fs.readdirSync(fullPath).filter((f) => f.endsWith(".jsonl"));
+    if (fileNames.length === 0) continue;
+
+    const jsonlFiles = fileNames.map((f) => ({
+      sessionId: f.replace(/\.jsonl$/, ""),
+      fileName: f,
+      absPath: path.join(fullPath, f),
+    }));
+
+    const decoded = decodeProjectPath(entry);
+
+    projects.push({
+      dirName: entry,
+      absPath: fullPath,
+      sessionCount: jsonlFiles.length,
+      jsonlFiles,
+      decodedPath: decoded.value,
+      pathConfidence: decoded.confidence,
+    });
+  }
+
+  return projects;
+}
+
+function decodeProjectPath(dirName) {
+  if (!dirName || dirName.trim() === "") {
+    return { value: "", confidence: "inferred" };
+  }
+
+  if (!dirName.startsWith("-")) {
+    return { value: dirName, confidence: "inferred" };
+  }
+
+  const pathStr = "/" + dirName.slice(1).replace(/-/g, "/");
+
+  return { value: pathStr, confidence: "inferred" };
+}
+
+function buildImportPlan(projects, manifest, opts = {}) {
+  const maxSessionsPerProject = opts.maxSessionsPerProject || Infinity;
+  const plan = {
+    new: [],
+    updated: [],
+    skipped: [],
+    summary: { total: 0, newCount: 0, updatedCount: 0, skippedCount: 0 },
+  };
+
+  const computeHash = opts.getFileHash || ((absPath) => {
+    try {
+      const content = fs.readFileSync(absPath, "utf-8");
+      return crypto.createHash("sha256").update(content).digest("hex");
+    } catch {
+      return crypto.createHash("sha256").update(absPath).digest("hex");
+    }
+  });
+
+  for (const project of projects) {
+    const jsonlFiles = project.jsonlFiles || [];
+    let projectSessionCount = 0;
+
+    for (const jf of jsonlFiles) {
+      if (projectSessionCount >= maxSessionsPerProject) break;
+
+      const sessionId = jf.sessionId;
+      const filePath = jf.absPath;
+      const fileHash = computeHash(filePath);
+
+      const entry = {
+        sessionId,
+        filePath,
+        fileHash,
+        projectDir: project.dirName,
+        decodedPath: project.decodedPath,
+        pathConfidence: project.pathConfidence,
+        turnCount: 0,
+      };
+
+      if (manifest.imports && manifest.imports[sessionId]) {
+        const existing = manifest.imports[sessionId];
+        if (existing.fileHash === fileHash) {
+          plan.skipped.push({ ...entry, articleId: existing.articleId });
+        } else {
+          plan.updated.push({ ...entry, previousArticleId: existing.articleId });
+        }
+      } else {
+        plan.new.push(entry);
+      }
+
+      projectSessionCount++;
+    }
+  }
+
+  plan.summary.total = plan.new.length + plan.updated.length + plan.skipped.length;
+  plan.summary.newCount = plan.new.length;
+  plan.summary.updatedCount = plan.updated.length;
+  plan.summary.skippedCount = plan.skipped.length;
+
+  return plan;
+}
+
+module.exports = { scanClaudeProjects, decodeProjectPath, buildImportPlan };

package/scripts/lib/infra/config.js

@@ -0,0 +1,36 @@
+const fs = require("fs");
+const path = require("path");
+const { getConfig, resolveWorkspace } = require("./workspace");
+
+function isCaptureEnabled(env = process.env) {
+  if (env.ECHO_CAPTURE === "off") return false;
+  if (env.ECHO_CAPTURE === "on") return true;
+
+  const config = getConfig();
+  if (config.capture_enabled === false) return false;
+
+  return true;
+}
+
+function setCaptureEnabled(value) {
+  const ws = resolveWorkspace();
+  const configPath = path.join(ws, "echo.json");
+  const config = getConfig();
+  config.capture_enabled = value;
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  return { capture_enabled: value, configPath };
+}
+
+function getSpeakers(env = process.env) {
+  return {
+    user: env.ECHO_USER_SPEAKER || "vincent",
+    ai: env.ECHO_AI_SPEAKER || "ai",
+  };
+}
+
+function getAuthor() {
+  const config = getConfig();
+  return config.author || "vincent";
+}
+
+module.exports = { isCaptureEnabled, setCaptureEnabled, getSpeakers, getAuthor };

package/scripts/lib/infra/echo-paths.js

@@ -0,0 +1,44 @@
+const path = require("path");
+const {
+  resolveEchoHomePath,
+} = require("./workspace");
+
+function resolveDataDirs(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const echoHome = opts.echoHome || resolveEchoHomePath(opts);
+
+  let projectRoot = echoHome;
+  let projectId = null;
+
+  if (opts.registry) {
+    const project = opts.registry.findProjectForPath(cwd, { echoHome });
+    if (project) {
+      projectRoot = project.dataRoot;
+      projectId = project.projectId;
+    }
+  } else {
+    try {
+      const { findProjectForPath } = require("../usecases/project-registry");
+      const project = findProjectForPath(cwd, { echoHome });
+      if (project) {
+        projectRoot = project.dataRoot;
+        projectId = project.projectId;
+      }
+    } catch (err) {
+      // Only swallow MODULE_NOT_FOUND — registry may not be installed.
+      // Registry corruption or parse errors must surface.
+      if (err.code !== "MODULE_NOT_FOUND") throw err;
+    }
+  }
+
+  return {
+    articlesDir: path.join(projectRoot, "articles"),
+    commentsDir: path.join(projectRoot, "comments"),
+    bufferDir: path.join(projectRoot, "session-buffer"),
+    indexDir: path.join(projectRoot, "index"),
+    projectId,
+    projectRoot,
+  };
+}
+
+module.exports = { resolveDataDirs };