echoctl 0.1.0

package/scripts/lib/usecases/discover-claude-imports.js

@@ -0,0 +1,80 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+const { resolveEchoHomePath } = require("../infra/workspace");
+const { findProjectById } = require("./project-registry");
+const { loadManifest } = require("../import/manifest");
+const { scanProjectDir } = require("../import/providers/claude-code");
+
+function claudeProjectDirName(projectPath) {
+  return "-" + path.resolve(projectPath).slice(1).split(path.sep).join("-");
+}
+
+function discoverClaudeImportCandidates(projectId, opts = {}) {
+  const echoHome = opts.echoHome || resolveEchoHomePath(opts);
+  const project = findProjectById(projectId, { echoHome });
+  if (!project) throw new Error(`Project "${projectId}" not found.`);
+
+  const claudeProjectsDir = opts.claudeProjectsDir || path.join(os.homedir(), ".claude", "projects");
+  const dirName = claudeProjectDirName(project.projectRoot);
+  const projectDir = path.join(claudeProjectsDir, dirName);
+
+  if (!fs.existsSync(projectDir)) {
+    return {
+      projectId,
+      provider: "claude-code",
+      projectDir,
+      summary: { total: 0, new: 0, updated: 0, skipped: 0 },
+      candidates: [],
+    };
+  }
+
+  const sessions = scanProjectDir(projectDir);
+  const manifestPath = path.join(echoHome, "import-manifest.json");
+  const manifest = loadManifest(manifestPath);
+
+  const candidates = [];
+  const summary = { total: 0, new: 0, updated: 0, skipped: 0 };
+
+  for (const s of sessions) {
+    summary.total++;
+    const fileHash = crypto.createHash("sha256")
+      .update(fs.readFileSync(s.filePath, "utf-8"))
+      .digest("hex");
+
+    const existing = manifest.imports && manifest.imports[s.sessionId];
+    let status = "new";
+    let articleId = `session-${s.sessionId.slice(0, 8)}`;
+
+    if (existing) {
+      if (existing.fileHash === fileHash) {
+        status = "skipped";
+        articleId = existing.articleId;
+      } else {
+        status = "updated";
+        articleId = existing.articleId;
+      }
+    }
+
+    candidates.push({
+      sessionId: s.sessionId,
+      filePath: s.filePath,
+      status,
+      articleId,
+      turnCount: s.turnCount,
+      mtime: (() => {
+        try { return fs.statSync(s.filePath).mtime.toISOString(); } catch (_) { return ""; }
+      })(),
+      fileHash,
+    });
+
+    if (status === "new") summary.new++;
+    else if (status === "updated") summary.updated++;
+    else summary.skipped++;
+  }
+
+  return { projectId, provider: "claude-code", projectDir, summary, candidates };
+}
+
+module.exports = { discoverClaudeImportCandidates, claudeProjectDirName };

package/scripts/lib/usecases/import-claude-project.js

@@ -0,0 +1,89 @@
+const fs = require("fs");
+const path = require("path");
+
+const { resolveEchoHomePath } = require("../infra/workspace");
+const { findProjectById } = require("./project-registry");
+const { discoverClaudeImportCandidates } = require("./discover-claude-imports");
+const provider = require("../import/providers/claude-code");
+const mf = require("../import/manifest");
+
+function importClaudeProject(projectId, opts = {}) {
+  const echoHome = opts.echoHome || resolveEchoHomePath(opts);
+  const project = findProjectById(projectId, { echoHome });
+  if (!project) throw new Error(`Project "${projectId}" not found.`);
+
+  const discovery = discoverClaudeImportCandidates(projectId, {
+    echoHome,
+    claudeProjectsDir: opts.claudeProjectsDir,
+  });
+  const selected = opts.sessionIds ? new Set(opts.sessionIds) : null;
+  const candidates = discovery.candidates.filter((entry) => {
+    if (entry.status === "skipped") return false;
+    return !selected || selected.has(entry.sessionId);
+  });
+
+  const articlesDir = path.join(project.dataRoot, "articles");
+  const manifestPath = path.join(echoHome, "import-manifest.json");
+  const manifest = mf.loadManifest(manifestPath);
+  const result = {
+    ok: true,
+    projectId,
+    provider: "claude-code",
+    projectDir: discovery.projectDir,
+    total: discovery.summary.total,
+    candidates: candidates.length,
+    imported: 0,
+    skipped: 0,
+    lowQuality: 0,
+    failed: 0,
+    articlesDir,
+    importedArticles: [],
+  };
+
+  for (const entry of candidates) {
+    const articleId = `session-${entry.sessionId.slice(0, 8)}`;
+    const articlePath = path.join(articlesDir, `${articleId}.md`);
+
+    if (fs.existsSync(articlePath)) {
+      if (entry.status === "updated") {
+        mf.recordImport(manifest, entry.sessionId, articleId, entry.fileHash, { provider: "claude-code" });
+      }
+      result.skipped++;
+      continue;
+    }
+
+    try {
+      const turns = provider.readSessionTurns(entry.filePath);
+      const classification = provider.classifySession(turns);
+      if (!classification.isMeaningful) {
+        mf.recordImport(manifest, entry.sessionId, `skipped-${entry.sessionId.slice(0, 8)}`, entry.fileHash, {
+          provider: "claude-code",
+          skipped: true,
+          reason: classification.reason,
+        });
+        result.skipped++;
+        result.lowQuality++;
+        continue;
+      }
+
+      const metadata = provider.extractMetadata(turns);
+      const markdown = provider.toEchoArticle(turns, metadata, {
+        sessionId: entry.sessionId,
+        project: projectId,
+      });
+
+      fs.mkdirSync(path.dirname(articlePath), { recursive: true });
+      fs.writeFileSync(articlePath, markdown);
+      mf.recordImport(manifest, entry.sessionId, articleId, entry.fileHash, { provider: "claude-code" });
+      result.imported++;
+      result.importedArticles.push({ articleId, articlePath });
+    } catch (_) {
+      result.failed++;
+    }
+  }
+
+  mf.saveManifest(manifest, manifestPath);
+  return result;
+}
+
+module.exports = { importClaudeProject };

package/scripts/lib/usecases/init-workspace.js

@@ -0,0 +1,52 @@
+const path = require("path");
+const fs = require("fs");
+const { resolveWorkspace, ensureDir } = require("../infra/workspace");
+
+function initWorkspace() {
+  const ws = resolveWorkspace();
+  const configPath = path.join(ws, "echo.json");
+
+  const subdirs = ["articles", "comments", "session-buffer", "index"];
+  const created = [];
+  const skipped = [];
+
+  // Create workspace root
+  ensureDir(ws);
+
+  // Create subdirectories
+  for (const d of subdirs) {
+    const full = path.join(ws, d);
+    if (!fs.existsSync(full)) {
+      ensureDir(full);
+      created.push(d);
+    } else {
+      skipped.push(d);
+    }
+  }
+
+  // Write echo.json if missing; if malformed, warn and overwrite
+  let configAction = "skipped";
+  if (fs.existsSync(configPath)) {
+    try {
+      JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    } catch (_) {
+      configAction = "replaced";
+      writeDefaultConfig(configPath, ws);
+    }
+  } else {
+    configAction = "created";
+    writeDefaultConfig(configPath, ws);
+  }
+
+  return { workspace: ws, created, skipped, configAction };
+}
+
+function writeDefaultConfig(configPath, ws) {
+  const relative = ws.startsWith(process.env.HOME || "") ? ws.replace(process.env.HOME || "", "~") : ws;
+  fs.writeFileSync(configPath, JSON.stringify({
+    workspace: relative,
+    capture_enabled: true,
+  }, null, 2) + "\n");
+}
+
+module.exports = { initWorkspace };

package/scripts/lib/usecases/install-claude-hook.js

@@ -0,0 +1,139 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { commandFor, isKnownCliCommand } = require("../cli/names");
+
+const SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
+
+function hookEntry(command) {
+  return { matcher: "", hooks: [{ type: "command", command }] };
+}
+
+const DESIRED_HOOKS = {
+  UserPromptSubmit: [hookEntry(commandFor(["hook", "capture"]))],
+  Stop: [hookEntry(commandFor(["hook", "capture"]))],
+  StopFailure: [hookEntry(commandFor(["hook", "capture"]))],
+  SessionStart: [hookEntry(commandFor(["hook", "status"]))],
+};
+
+function readSettings() {
+  if (!fs.existsSync(SETTINGS_PATH)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(SETTINGS_PATH, "utf-8"));
+  } catch (_) {
+    return {};
+  }
+}
+
+function extractCommand(entry, matches = () => true) {
+  // New format: { matcher: "", hooks: [{ type: "command", command: "..." }] }
+  if (Array.isArray(entry.hooks)) {
+    const hook = entry.hooks.find(
+      (h) => typeof h.command === "string" && matches(h.command)
+    );
+    if (hook) return hook.command;
+  }
+  // Old format: { command: "..." }
+  if (typeof entry.command === "string" && matches(entry.command)) return entry.command;
+  return null;
+}
+
+function isOldCommandEntry(entry) {
+  return typeof entry.command === "string" && !Array.isArray(entry.hooks);
+}
+
+// Returns true when two CLI commands differ only in binary name (echoctl vs echo-mcp)
+// and share the same subcommand args, e.g. "echo-mcp hook capture" ~ "echoctl hook capture".
+function isSameCliSubcommand(existingCmd, desiredCmd) {
+  if (existingCmd === desiredCmd) return true;
+  if (!isKnownCliCommand(existingCmd)) return false;
+  const existingArgs = existingCmd.split(" ").slice(1).join(" ");
+  const desiredArgs = desiredCmd.split(" ").slice(1).join(" ");
+  return existingArgs === desiredArgs;
+}
+
+function installClaudeHook({ write }) {
+  const current = readSettings();
+  const hooks = current.hooks || {};
+
+  const toAdd = [];
+  const alreadyInstalled = [];
+  const legacy = [];
+
+  // Detect legacy .sh commands AND already-installed CLI hooks across all hook events
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      const cmd = extractCommand(entry, (command) => command.includes(".sh"));
+      if (cmd && cmd.includes(".sh")) {
+        legacy.push({ event, command: cmd });
+      }
+      // Also detect already-installed echoctl/echo-mcp hooks via isKnownCliCommand
+      const cliCmd = extractCommand(entry, (command) => isKnownCliCommand(command));
+      if (cliCmd && isKnownCliCommand(cliCmd)) {
+        // Known CLI hook found — will be recognised by upsert logic below
+      }
+    }
+  }
+
+  // Upsert desired hooks
+  for (const [event, desiredEntries] of Object.entries(DESIRED_HOOKS)) {
+    const raw = hooks[event];
+    const existing = Array.isArray(raw) ? raw : [];
+
+    if (!hooks[event]) hooks[event] = [];
+    else if (!Array.isArray(hooks[event])) hooks[event] = [];
+
+    for (const desired of desiredEntries) {
+      const desiredCmd = desired.hooks[0].command;
+      const found = existing.find(
+        (e) => {
+          const cmd = extractCommand(e, (command) => command === desiredCmd);
+          if (cmd === desiredCmd) return true;
+          const cmdAny = extractCommand(e, (command) => isKnownCliCommand(command));
+          if (cmdAny && isKnownCliCommand(cmdAny) && isSameCliSubcommand(cmdAny, desiredCmd)) return true;
+          return false;
+        }
+      );
+      if (found) {
+        alreadyInstalled.push({ event, command: desiredCmd });
+        if (isOldCommandEntry(found)) {
+          Object.assign(found, desired);
+        }
+      } else {
+        toAdd.push({ event, command: desiredCmd });
+      }
+    }
+
+    if (!hooks[event]) hooks[event] = [];
+    for (const desired of desiredEntries) {
+      const desiredCmd = desired.hooks[0].command;
+      const found = hooks[event].find(
+        (e) => {
+          const cmd = extractCommand(e, (command) => command === desiredCmd);
+          if (cmd === desiredCmd) return true;
+          const cmdAny = extractCommand(e, (command) => isKnownCliCommand(command));
+          if (cmdAny && isKnownCliCommand(cmdAny) && isSameCliSubcommand(cmdAny, desiredCmd)) return true;
+          return false;
+        }
+      );
+      if (!found) {
+        hooks[event].push(desired);
+      }
+    }
+  }
+
+  if (write) {
+    current.hooks = hooks;
+    const settingsDir = path.dirname(SETTINGS_PATH);
+    if (!fs.existsSync(settingsDir)) fs.mkdirSync(settingsDir, { recursive: true });
+    const tmp = SETTINGS_PATH + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(current, null, 2) + "\n");
+    fs.renameSync(tmp, SETTINGS_PATH);
+    return { written: true, toAdd, alreadyInstalled, legacy };
+  }
+
+  return { written: false, toAdd, alreadyInstalled, legacy };
+}
+
+module.exports = { installClaudeHook, DESIRED_HOOKS, SETTINGS_PATH };

package/scripts/lib/usecases/legacy-candidates.js

@@ -0,0 +1,134 @@
+const fs = require("fs");
+const path = require("path");
+const { resolveEchoHomePath } = require("../infra/workspace");
+const { findProjectById, listProjects } = require("./project-registry");
+
+function defaultLegacyBufferDir(echoHome) {
+  return path.join(echoHome, "session-buffer");
+}
+
+function listMarkdownFiles(dir) {
+  try {
+    return fs.readdirSync(dir)
+      .filter((name) => name.endsWith(".md"))
+      .sort();
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+function readPendingPayload(pendingDir, sessionId) {
+  const pendingFile = path.join(pendingDir, `${sessionId}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(pendingFile, "utf-8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+function claudeProjectDirName(projectPath) {
+  return "-" + path.resolve(projectPath).slice(1).split(path.sep).join("-");
+}
+
+function resolveProjectForTranscriptPath(transcriptPath, projects) {
+  if (!transcriptPath) return null;
+  for (const p of projects) {
+    if (transcriptPath.includes(claudeProjectDirName(p.root))) return p;
+  }
+  return null;
+}
+
+function resolveProjectForCwd(cwd, projects) {
+  if (!cwd) return null;
+  const resolved = path.resolve(cwd);
+  for (const p of projects) {
+    const root = path.resolve(p.root);
+    if (resolved === root || resolved.startsWith(root + path.sep)) return p;
+  }
+  return null;
+}
+
+function scanLegacyCandidates(projectId, opts = {}) {
+  const echoHome = opts.echoHome || resolveEchoHomePath(opts);
+  const sourceDir = opts.from || defaultLegacyBufferDir(echoHome);
+  const project = findProjectById(projectId, { echoHome });
+  if (!project) throw new Error(`Project "${projectId}" not found.`);
+
+  const projects = listProjects(echoHome);
+  const pendingDir = path.join(sourceDir, "pending");
+  const markdownNames = listMarkdownFiles(sourceDir);
+  const candidates = [];
+
+  // First pass: match by pending JSON evidence
+  let hasAnyHighConfidenceMatch = false;
+  for (const name of markdownNames) {
+    const sourcePath = path.join(sourceDir, name);
+    const sessionId = path.basename(name, ".md");
+    let stat;
+    try { stat = fs.statSync(sourcePath); } catch (_) { continue; }
+
+    const raw = fs.readFileSync(sourcePath, "utf-8");
+    const turnCount = (raw.match(/<!-- turn:/g) || []).length;
+    if (turnCount === 0) continue;
+
+    const pending = readPendingPayload(pendingDir, sessionId);
+    let matched = null;
+    let evidence = null;
+    let confidence = "low";
+
+    if (pending && pending.transcript_path) {
+      matched = resolveProjectForTranscriptPath(pending.transcript_path, projects);
+      if (matched) {
+        evidence = { kind: "transcript_path", projectRoot: matched.root };
+        confidence = "high";
+      }
+    }
+    if (!matched && pending && pending.cwd) {
+      matched = resolveProjectForCwd(pending.cwd, projects);
+      if (matched) {
+        evidence = { kind: "cwd", projectRoot: matched.root };
+        confidence = "high";
+      }
+    }
+    if (!matched || matched.projectId !== projectId) continue;
+
+    hasAnyHighConfidenceMatch = true;
+    candidates.push({
+      sessionId, fileName: name, sourcePath,
+      turnCount, mtime: stat.mtime.toISOString(),
+      confidence, evidence,
+    });
+  }
+
+  // Second pass: completed sessions (pending deleted) inherit medium confidence
+  // if at least one other session in the same legacy buffer matched this project
+  if (hasAnyHighConfidenceMatch) {
+    const alreadyMatched = new Set(candidates.map((c) => c.sessionId));
+    for (const name of markdownNames) {
+      const sessionId = path.basename(name, ".md");
+      if (alreadyMatched.has(sessionId)) continue;
+
+      const sourcePath = path.join(sourceDir, name);
+      let stat;
+      try { stat = fs.statSync(sourcePath); } catch (_) { continue; }
+      const raw = fs.readFileSync(sourcePath, "utf-8");
+      const turnCount = (raw.match(/<!-- turn:/g) || []).length;
+      if (turnCount === 0) continue;
+
+      const pending = readPendingPayload(pendingDir, sessionId);
+      if (pending) continue; // has pending but didn't match above — skip
+
+      candidates.push({
+        sessionId, fileName: name, sourcePath,
+        turnCount, mtime: stat.mtime.toISOString(),
+        confidence: "medium",
+        evidence: { kind: "shared_buffer", projectRoot: project.root },
+      });
+    }
+  }
+
+  return { projectId, sourceDir, candidates };
+}
+
+module.exports = { scanLegacyCandidates, defaultLegacyBufferDir };

package/scripts/lib/usecases/live-session-state.js

@@ -0,0 +1,109 @@
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+function countTurns(raw) {
+  return (String(raw || "").match(/<!-- turn:/g) || []).length;
+}
+
+function hashContent(raw) {
+  return crypto.createHash("sha256").update(String(raw || "")).digest("hex");
+}
+
+function liveStatePath(dataRoot) {
+  return path.join(dataRoot, "index", "live-state.json");
+}
+
+function readLiveState(dataRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(liveStatePath(dataRoot), "utf-8"));
+  } catch (_) {
+    return { sessions: {} };
+  }
+}
+
+function saveLiveState(dataRoot, state) {
+  const filePath = liveStatePath(dataRoot);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2));
+}
+
+function sessionStateFromFile(sessionFile, opts = {}) {
+  const sessionId = opts.sessionId || path.basename(sessionFile, ".md");
+  if (!fs.existsSync(sessionFile)) {
+    return {
+      ok: true,
+      exists: false,
+      projectId: opts.projectId || null,
+      sessionId,
+      turnCount: 0,
+      hash: null,
+      updatedAt: null,
+    };
+  }
+
+  const raw = fs.readFileSync(sessionFile, "utf-8");
+  const stat = fs.statSync(sessionFile);
+  return {
+    ok: true,
+    exists: true,
+    projectId: opts.projectId || null,
+    sessionId,
+    turnCount: countTurns(raw),
+    hash: hashContent(raw),
+    updatedAt: stat.mtime.toISOString(),
+  };
+}
+
+function writeLiveSessionState(dataRoot, sessionFile, opts = {}) {
+  const next = sessionStateFromFile(sessionFile, opts);
+  if (!next.exists) return next;
+
+  const state = readLiveState(dataRoot);
+  state.sessions = state.sessions || {};
+  state.sessions[next.sessionId] = {
+    projectId: next.projectId,
+    turnCount: next.turnCount,
+    hash: next.hash,
+    updatedAt: new Date().toISOString(),
+    sourcePath: sessionFile,
+  };
+  saveLiveState(dataRoot, state);
+
+  return {
+    ...next,
+    updatedAt: state.sessions[next.sessionId].updatedAt,
+  };
+}
+
+function getLiveSessionState(dirs, sessionId) {
+  const dataRoot = dirs.dataRoot || dirs.projectRoot || path.dirname(dirs.articlesDir);
+  const bufferDir = dirs.bufferDir || path.join(dataRoot, "session-buffer");
+  const sessionFile = path.join(bufferDir, `${sessionId}.md`);
+  const computed = sessionStateFromFile(sessionFile, {
+    projectId: dirs.projectId || null,
+    sessionId,
+  });
+
+  if (!computed.exists) return computed;
+
+  const saved = readLiveState(dataRoot).sessions?.[sessionId];
+  if (saved && saved.hash === computed.hash) {
+    return {
+      ...computed,
+      updatedAt: saved.updatedAt || computed.updatedAt,
+    };
+  }
+  return computed;
+}
+
+module.exports = {
+  countTurns,
+  hashContent,
+  liveStatePath,
+  readLiveState,
+  saveLiveState,
+  sessionStateFromFile,
+  writeLiveSessionState,
+  getLiveSessionState,
+};