@claude-transcripts/cli 0.3.0 → 0.3.2

package/dist/cli.js

@@ -29928,14 +29928,17 @@ var CLI_SPEC = {
         },
         {
           name: "--repair",
-          description: "add missing chunk docs to adopted sessions; leaves summary + events alone"
+          description: "add what an interrupted write left out of an adopted session: missing chunk docs, or a transcript that never reached S3; leaves summary + events alone"
         },
         {
           name: "--session",
           type: "string",
           description: "with --force: re-process only this session"
         },
-        { name: "--dry-run", description: "preview without writing" }
+        {
+          name: "--dry-run",
+          description: "preview without writing (reads the store, so skips are shown)"
+        }
       ],
       examples: ["backfill --dry-run", "backfill", "backfill --force --session 3f9a2c1e"]
     },
@@ -38772,6 +38775,128 @@ var import_react28 = __toESM(require_react(), 1);
 // packages/cli/src/commands/backfill.ts
 import { hostname } from "os";
 
+// packages/cli/src/api/http.ts
+import { readFileSync as readFileSync2 } from "fs";
+
+// packages/cli/src/lib/paths.ts
+import { homedir } from "os";
+import { join as join2 } from "path";
+function xdg(envVar, fallback) {
+  const v = process.env[envVar];
+  return v?.trim() ? v : fallback;
+}
+function installPaths() {
+  const home = homedir();
+  const ctHome = process.env.CT_HOME;
+  const configDir = ctHome ? join2(ctHome, "config") : join2(xdg("XDG_CONFIG_HOME", join2(home, ".config")), "claude-transcripts");
+  const dataDir = ctHome ? join2(ctHome, "data") : join2(xdg("XDG_DATA_HOME", join2(home, ".local", "share")), "claude-transcripts");
+  const binDir = ctHome ? join2(ctHome, "bin") : join2(home, ".local", "bin");
+  const claudeSettings = ctHome ? join2(ctHome, "claude", "settings.json") : join2(home, ".claude", "settings.json");
+  return {
+    configDir,
+    dataDir,
+    binDir,
+    claudeSettings,
+    hookConfig: process.env.CT_HOOK_CONFIG ?? join2(configDir, "config.json"),
+    instanceEnv: join2(configDir, "instance.env"),
+    appConfig: join2(configDir, "app.json"),
+    deployDir: join2(dataDir, "deploy"),
+    versionFile: join2(dataDir, "version")
+  };
+}
+
+// packages/cli/src/api/http.ts
+var DEFAULT_WEBAPI_PORT = "7650";
+var resolved = null;
+function base2() {
+  resolved ??= resolveWebapiUrl();
+  return resolved;
+}
+function resolveWebapiUrl() {
+  if (process.env.CT_WEBAPI_URL)
+    return process.env.CT_WEBAPI_URL.replace(/\/$/, "");
+  const host = process.env.WEBAPI_HOST || "127.0.0.1";
+  if (process.env.WEBAPI_PORT)
+    return `http://${host}:${process.env.WEBAPI_PORT}`;
+  const fromInstance = instanceWebapiUrl();
+  if (fromInstance)
+    return fromInstance;
+  return `http://${host}:${DEFAULT_WEBAPI_PORT}`;
+}
+function instanceWebapiUrl() {
+  try {
+    const raw = readFileSync2(installPaths().instanceEnv, "utf8");
+    const port = /^WEBAPI_PORT=(\d+)\s*$/m.exec(raw)?.[1];
+    if (!port)
+      return null;
+    const host = /^WEBAPI_HOST=(\S+)\s*$/m.exec(raw)?.[1] ?? "127.0.0.1";
+    return `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`;
+  } catch {
+    return null;
+  }
+}
+function setWebapiUrl(url) {
+  resolved = url.replace(/\/$/, "");
+}
+function webapiUrl() {
+  return base2();
+}
+async function customFetch(url, init) {
+  const res = await fetch(`${base2()}${url}`, init);
+  if (!res.ok) {
+    throw new Error(`${init?.method ?? "GET"} ${url} \u2192 ${res.status} ${res.statusText}${await errorDetail(res)}`);
+  }
+  const text = await res.text();
+  return text ? JSON.parse(text) : undefined;
+}
+async function errorDetail(res) {
+  try {
+    const text = (await res.text()).trim();
+    if (!text)
+      return "";
+    try {
+      const body = JSON.parse(text);
+      const msg = body.error ?? body.reason;
+      if (typeof msg === "string" && msg)
+        return `: ${msg}`;
+    } catch {}
+    return `: ${text.slice(0, 300)}`;
+  } catch {
+    return "";
+  }
+}
+async function exists(path) {
+  const res = await fetch(`${base2()}${path}`);
+  return res.ok;
+}
+async function getOrNull(path) {
+  const res = await fetch(`${base2()}${path}`);
+  if (!res.ok)
+    return null;
+  return await res.json();
+}
+async function putStream(path, filePath, contentType) {
+  const res = await fetch(`${base2()}${path}`, {
+    method: "PUT",
+    headers: { "content-type": contentType },
+    body: Bun.file(filePath).stream(),
+    duplex: "half"
+  });
+  if (!res.ok) {
+    throw new Error(`PUT ${path} \u2192 ${res.status} ${res.statusText}${await errorDetail(res)}`);
+  }
+}
+async function putRaw(path, body, contentType) {
+  const res = await fetch(`${base2()}${path}`, {
+    method: "PUT",
+    headers: { "content-type": contentType },
+    body
+  });
+  if (!res.ok) {
+    throw new Error(`PUT ${path} \u2192 ${res.status} ${res.statusText}${await errorDetail(res)}`);
+  }
+}
+
 // packages/cli/src/lib/args.ts
 function parseFlags(argv) {
   const positionals = [];
@@ -38807,10 +38932,10 @@ function strOpt(opts, key) {
 
 // packages/cli/src/lib/claude-fs.ts
 import { readdir, readFile } from "fs/promises";
-import { homedir } from "os";
-import { join as join2 } from "path";
+import { homedir as homedir2 } from "os";
+import { join as join3 } from "path";
 function defaultProjectsDir() {
-  return join2(homedir(), ".claude", "projects");
+  return join3(homedir2(), ".claude", "projects");
 }
 async function discoverTranscripts(root) {
   const out = [];
@@ -38818,12 +38943,12 @@ async function discoverTranscripts(root) {
   for (const proj of projects) {
     if (!proj.isDirectory())
       continue;
-    const dir = join2(root, proj.name);
+    const dir = join3(root, proj.name);
     const files = await readdir(dir).catch(() => []);
     for (const f of files) {
       if (!f.endsWith(".jsonl"))
         continue;
-      out.push({ path: join2(dir, f), project: proj.name, sessionId: f.replace(/\.jsonl$/, "") });
+      out.push({ path: join3(dir, f), project: proj.name, sessionId: f.replace(/\.jsonl$/, "") });
     }
   }
   return out.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
@@ -39023,124 +39148,6 @@ function safeStringify(v) {
   }
 }
 
-// packages/cli/src/api/http.ts
-import { readFileSync as readFileSync2 } from "fs";
-
-// packages/cli/src/lib/paths.ts
-import { homedir as homedir2 } from "os";
-import { join as join3 } from "path";
-function xdg(envVar, fallback) {
-  const v = process.env[envVar];
-  return v?.trim() ? v : fallback;
-}
-function installPaths() {
-  const home = homedir2();
-  const ctHome = process.env.CT_HOME;
-  const configDir = ctHome ? join3(ctHome, "config") : join3(xdg("XDG_CONFIG_HOME", join3(home, ".config")), "claude-transcripts");
-  const dataDir = ctHome ? join3(ctHome, "data") : join3(xdg("XDG_DATA_HOME", join3(home, ".local", "share")), "claude-transcripts");
-  const binDir = ctHome ? join3(ctHome, "bin") : join3(home, ".local", "bin");
-  const claudeSettings = ctHome ? join3(ctHome, "claude", "settings.json") : join3(home, ".claude", "settings.json");
-  return {
-    configDir,
-    dataDir,
-    binDir,
-    claudeSettings,
-    hookConfig: process.env.CT_HOOK_CONFIG ?? join3(configDir, "config.json"),
-    instanceEnv: join3(configDir, "instance.env"),
-    appConfig: join3(configDir, "app.json"),
-    deployDir: join3(dataDir, "deploy"),
-    versionFile: join3(dataDir, "version")
-  };
-}
-
-// packages/cli/src/api/http.ts
-var DEFAULT_WEBAPI_PORT = "7650";
-var resolved = null;
-function base2() {
-  resolved ??= resolveWebapiUrl();
-  return resolved;
-}
-function resolveWebapiUrl() {
-  if (process.env.CT_WEBAPI_URL)
-    return process.env.CT_WEBAPI_URL.replace(/\/$/, "");
-  const host = process.env.WEBAPI_HOST || "127.0.0.1";
-  if (process.env.WEBAPI_PORT)
-    return `http://${host}:${process.env.WEBAPI_PORT}`;
-  const fromInstance = instanceWebapiUrl();
-  if (fromInstance)
-    return fromInstance;
-  return `http://${host}:${DEFAULT_WEBAPI_PORT}`;
-}
-function instanceWebapiUrl() {
-  try {
-    const raw = readFileSync2(installPaths().instanceEnv, "utf8");
-    const port = /^WEBAPI_PORT=(\d+)\s*$/m.exec(raw)?.[1];
-    if (!port)
-      return null;
-    const host = /^WEBAPI_HOST=(\S+)\s*$/m.exec(raw)?.[1] ?? "127.0.0.1";
-    return `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`;
-  } catch {
-    return null;
-  }
-}
-function setWebapiUrl(url) {
-  resolved = url.replace(/\/$/, "");
-}
-function webapiUrl() {
-  return base2();
-}
-async function customFetch(url, init) {
-  const res = await fetch(`${base2()}${url}`, init);
-  if (!res.ok) {
-    throw new Error(`${init?.method ?? "GET"} ${url} \u2192 ${res.status} ${res.statusText}${await errorDetail(res)}`);
-  }
-  const text = await res.text();
-  return text ? JSON.parse(text) : undefined;
-}
-async function errorDetail(res) {
-  try {
-    const text = (await res.text()).trim();
-    if (!text)
-      return "";
-    try {
-      const body = JSON.parse(text);
-      const msg = body.error ?? body.reason;
-      if (typeof msg === "string" && msg)
-        return `: ${msg}`;
-    } catch {}
-    return `: ${text.slice(0, 300)}`;
-  } catch {
-    return "";
-  }
-}
-async function getOrNull(path) {
-  const res = await fetch(`${base2()}${path}`);
-  if (!res.ok)
-    return null;
-  return await res.json();
-}
-async function putStream(path, filePath, contentType) {
-  const res = await fetch(`${base2()}${path}`, {
-    method: "PUT",
-    headers: { "content-type": contentType },
-    body: Bun.file(filePath).stream(),
-    duplex: "half"
-  });
-  if (!res.ok) {
-    throw new Error(`PUT ${path} \u2192 ${res.status} ${res.statusText}${await errorDetail(res)}`);
-  }
-}
-async function putRaw(path, body, contentType) {
-  const res = await fetch(`${base2()}${path}`, {
-    method: "PUT",
-    headers: { "content-type": contentType },
-    body
-  });
-  if (!res.ok) {
-    throw new Error(`PUT ${path} \u2192 ${res.status} ${res.statusText}${await errorDetail(res)}`);
-  }
-}
-
 // packages/cli/src/api/generated.ts
 var getListSessionsUrl = (params) => {
   const normalizedParams = new URLSearchParams;
@@ -39324,11 +39331,41 @@ var migrateDown = async (migrateDownBody, options) => {
 // packages/cli/src/lib/sink.ts
 class DryRunSink {
   label = "dry-run";
-  async existingSession() {
-    return null;
+  blind = false;
+  reader;
+  constructor(reader) {
+    this.reader = reader;
   }
-  async hasTurns() {
-    return false;
+  reads() {
+    if (this.reader === undefined) {
+      try {
+        this.reader = new WebapiSink;
+      } catch {
+        this.reader = null;
+        this.blind = true;
+      }
+    }
+    return this.reader;
+  }
+  async ask(run, whenBlind) {
+    const r = this.reads();
+    if (!r)
+      return whenBlind;
+    try {
+      return await run(r);
+    } catch {
+      this.blind = true;
+      return whenBlind;
+    }
+  }
+  async existingSession(sessionId) {
+    return this.ask((r) => r.existingSession(sessionId), null);
+  }
+  async hasTranscriptBlob(sessionId) {
+    return this.ask((r) => r.hasTranscriptBlob(sessionId), true);
+  }
+  async hasTurns(sessionId) {
+    return this.ask((r) => r.hasTurns(sessionId), false);
   }
   async resetSession(sessionId) {
     console.log(`  [dry-run] DELETE ${sessionId}  (summary + event + chunk docs)`);
@@ -39360,6 +39397,9 @@ class WebapiSink {
     const res = await getOrNull(`/api/sessions/${encodeURIComponent(sessionId)}/turns?limit=1`);
     return (res?.turns?.length ?? 0) > 0;
   }
+  async hasTranscriptBlob(sessionId) {
+    return exists(`/api/s3/sessions/${encodeURIComponent(sessionId)}/transcript.jsonl`);
+  }
   async resetSession(sessionId) {
     const res = await resetSession(sessionId);
     return res.deleted;
@@ -39380,11 +39420,9 @@ class WebapiSink {
   }
 }
 function makeSink(opts) {
-  if (opts.dryRun)
-    return new DryRunSink;
   if (opts.webapiUrl)
     setWebapiUrl(opts.webapiUrl);
-  return new WebapiSink;
+  return opts.dryRun ? new DryRunSink : new WebapiSink;
 }
 
 // packages/cli/src/commands/backfill.ts
@@ -39394,8 +39432,9 @@ function planReingest(existing, opts) {
   if (opts.repair) {
     if (existing.status === "running")
       return { action: "skip", reason: "running" };
-    if (opts.hasTurns)
-      return { action: "skip", reason: "has-turns" };
+    if (opts.hasTurns) {
+      return opts.hasBlob === false ? { action: "repair-blob" } : { action: "skip", reason: "has-turns" };
+    }
     return { action: "repair" };
   }
   if (!opts.force)
@@ -39461,9 +39500,10 @@ async function runBackfill(argv) {
         skipped++;
         continue;
       }
-      const existing = dryRun ? null : await sink.existingSession(t.sessionId);
+      const existing = await sink.existingSession(t.sessionId);
       const hasTurns = repair && existing ? await sink.hasTurns(t.sessionId) : false;
-      const plan = planReingest(existing, { force, replaceLive, repair, hasTurns });
+      const hasBlob = hasTurns ? await sink.hasTranscriptBlob(t.sessionId) : undefined;
+      const plan = planReingest(existing, { force, replaceLive, repair, hasTurns, hasBlob });
       if (plan.action === "skip") {
         if (plan.reason === "live-record") {
           console.warn(`  ! ${t.sessionId}: skipped \u2014 recorded live. --force would delete that record and ` + "rebuild it from the transcript, losing provenance only the hook had. Pass " + "--replace-live to do that deliberately.");
@@ -39473,11 +39513,18 @@ async function runBackfill(argv) {
           console.log(`  \xB7 ${t.sessionId}: skipped \u2014 still running`);
         }
         if (plan.reason === "has-turns") {
-          console.log(`  \xB7 ${t.sessionId}: skipped \u2014 already has turn content`);
+          console.log(`  \xB7 ${t.sessionId}: skipped \u2014 already has turn content and a transcript`);
         }
         skipped++;
         continue;
       }
+      if (plan.action === "repair-blob") {
+        const jsonl = await readTranscript(t.path);
+        await sink.putTranscript(t.sessionId, new TextEncoder().encode(jsonl));
+        console.log(`  + ${t.sessionId}: re-uploaded the transcript (chunks left alone)`);
+        repaired++;
+        continue;
+      }
       if (plan.action === "repair") {
         const jsonl = await readTranscript(t.path);
         const facts = deriveSessionFacts(jsonl, { hostname: host, sessionIdHint: t.sessionId });
@@ -39507,6 +39554,9 @@ async function runBackfill(argv) {
       console.error(`  ! ${t.sessionId}: ${err.message}`);
     }
   }
+  if (sink instanceof DryRunSink && sink.blind) {
+    console.warn(`backfill: WARNING \u2014 could not read ${webapiUrl()}, so this preview assumed nothing ` + "is stored yet. A real run will skip whatever is already there; re-run the " + "preview once the webapi is reachable to see the true plan.");
+  }
   console.log(`backfill: ${written} backfilled${repaired ? `, ${repaired} repaired` : ""}` + `${reprocessed ? ` (${reprocessed} re-processed)` : ""}, ` + `${skipped} skipped${refusedLive ? ` (${refusedLive} live, not replaced)` : ""}, ` + `${failed} failed`);
   console.log("backfill: NOTE \u2014 summary + per-event markers + chunk docs reconstructed" + `${sidechains ? `; subagent sub-transcripts (${sidechains} session(s) have them) still TODO` : ""}` + " (see docs/operate/tools.md).");
   if (reprocessed && !dryRun) {
@@ -40293,6 +40343,9 @@ function makeMirrorCouch(target, onWrite) {
     },
     async putDoc(_db, id, doc, timeoutMs) {
       await send({ ...doc, _id: id }, timeoutMs ?? fallback);
+    },
+    async upsertDoc(_db, id, doc, timeoutMs) {
+      await send({ ...doc, _id: id }, timeoutMs ?? fallback);
     }
   };
 }
@@ -40328,6 +40381,9 @@ function fanOutCouch(clients) {
     },
     async putDoc(db, id, doc, timeoutMs) {
       await Promise.allSettled(clients.map((c) => c.putDoc(db, id, doc, timeoutMs)));
+    },
+    async upsertDoc(db, id, doc, timeoutMs) {
+      await Promise.allSettled(clients.map((c) => c.upsertDoc(db, id, doc, timeoutMs)));
     }
   };
 }
@@ -40403,6 +40459,39 @@ function makeDirectCouch(config, onWrite) {
       } catch {
         onWrite?.(false);
       }
+    },
+    async upsertDoc(db, id, doc, timeoutMs = 5000) {
+      const url = `${root}/${db}/${encodeURIComponent(id)}`;
+      const put = (body) => fetch(url, {
+        method: "PUT",
+        headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      try {
+        const res = await put(doc);
+        if (res.status !== 409) {
+          onWrite?.(res.ok);
+          return;
+        }
+        const current = await fetch(url, {
+          headers,
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+        if (!current.ok) {
+          onWrite?.(false);
+          return;
+        }
+        const { _rev } = await current.json();
+        if (!_rev) {
+          onWrite?.(false);
+          return;
+        }
+        const retry = await put({ ...doc, _rev });
+        onWrite?.(retry.ok);
+      } catch {
+        onWrite?.(false);
+      }
     }
   };
 }
@@ -40913,11 +41002,10 @@ var writeSummary = async (ctx) => {
     system_checks: {},
     source: "live"
   };
-  await ctx.couch.putDoc(ctx.sessionsDb, `summary:${ctx.sessionId}`, doc, 30000);
+  await ctx.couch.upsertDoc(ctx.sessionsDb, `summary:${ctx.sessionId}`, doc, 30000);
   if (ctx.blob.enabled && ctx.sessionsBucket) {
     await ctx.blob.put(ctx.sessionsBucket, `${ctx.sessionId}/summary.json`, JSON.stringify(doc), "application/json");
   }
-  ctx.counts.clear();
   ctx.targets.clear();
 };
 var uploadBlobs = async (ctx) => {
@@ -42779,7 +42867,7 @@ function tools(counts) {
 function summaryLine(s) {
   return row([
     [s.sessionId.slice(0, 8), 8],
-    [when(s.timestamp), 16],
+    [when(s.startTimestamp ?? s.timestamp), 16],
     [s.status, 10],
     [project2(s.cwd), 18],
     [num3(s.promptCount), 7],
@@ -42829,7 +42917,9 @@ async function showDetail(id, limit, json) {
     return 0;
   }
   console.log(`session ${s.sessionId}  [${s.status}]`);
-  console.log(`  started    ${s.timestamp ?? "\u2014"}`);
+  console.log(`  started    ${s.startTimestamp ?? s.timestamp ?? "\u2014"}`);
+  if (s.status === "ended")
+    console.log(`  ended      ${s.timestamp ?? "\u2014"}`);
   console.log(`  project    ${s.cwd || "\u2014"}`);
   console.log(`  model      ${s.model ?? "\u2014"}`);
   console.log(`  hostname   ${s.hostname || "\u2014"}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-transcripts/cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "Claude Transcripts CLI — browse, search, back up, and administer your self-hosted Claude Code session history.",
   "keywords": [