@liuyoumi/codex-history 0.1.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.0 - 2026-05-29
+
+### Added
+
+- Allow `purge` to accept multiple thread ids or unique short id prefixes in one guarded batch.
+
+## 0.2.0 - 2026-05-29
+
+### Removed
+
+- Remove the public `--json` output mode so the CLI stays focused on human-reviewed cleanup workflows.
+
 ## 0.1.4 - 2026-05-29
 
 ### Added

package/README.en.md

@@ -51,6 +51,7 @@ codex-history doctor
 codex-history list
 codex-history list --grep "Astro"
 codex-history purge 019e6885
+codex-history purge 019e6885 019e6874
 codex-history purge-orphans
 ```
 
@@ -75,7 +76,7 @@ Type 019e6885 to confirm:
 | `codex-history doctor` | Check whether the local Codex data layout is supported. |
 | `codex-history list` | List local conversations. |
 | `codex-history list --grep <keyword>` | Filter conversations by title, id, or cwd. |
-| `codex-history purge <id>` | Remove one resolved local conversation after confirmation. |
+| `codex-history purge <id...>` | Remove one or more resolved local conversations after confirmation. |
 | `codex-history purge-orphans` | Remove orphaned local data after confirmation. |
 
 ### `doctor`
@@ -129,19 +130,23 @@ When `list` runs in an interactive terminal without `--limit`, output is sent th
 
 ### `purge`
 
-Remove one local Codex conversation by full id or unique short id prefix.
+Remove one or more local Codex conversations by full id or unique short id prefix.
 
 ```bash
 codex-history purge 019e6885
+codex-history purge 019e6885 019e6874
 ```
 
+When multiple targets are provided, the tool resolves all targets and prints a batch plan before deletion. If any id is missing, ambiguous, or active, the whole batch is refused before mutation. Interactive batch purge requires typing `purge-selected`.
+
 For scripts or non-interactive shells, use `--force`:
 
 ```bash
 codex-history purge 019e6885 --force
+codex-history purge 019e6885 019e6874 --force
 ```
 
-`--force` skips only the interactive short-id confirmation. It still keeps schema validation, active-thread protection, and post-purge verification.
+`--force` skips only interactive confirmation. It still keeps schema validation, active-thread protection, and post-purge verification.
 
 ### `purge-orphans`
 
@@ -159,7 +164,7 @@ For scripts or non-interactive shells, use `--force`:
 codex-history purge-orphans --force
 ```
 
-`--force` skips only interactive confirmation. It still keeps schema validation, active-thread protection, and post-purge verification. `purge-orphans` does not support JSON output.
+`--force` skips only interactive confirmation. It still keeps schema validation, active-thread protection, and post-purge verification.
 
 Space reporting is an estimate. After SQLite rows are deleted, database files may not shrink until Codex or another SQLite maintenance step runs vacuum.
 
@@ -167,13 +172,9 @@ Space reporting is an estimate. After SQLite rows are deleted, database files ma
 
 ```bash
 codex-history --codex-home /path/to/.codex list
-codex-history --json list --grep "Astro"
-codex-history --json purge 019e6885 --force
 ```
 
 - `--codex-home` defaults to `~/.codex`.
-- `--json` prints machine-readable output. For `purge`, JSON output requires `--force` because interactive confirmation is text-only.
-- `purge-orphans` does not support JSON output.
 - Color is enabled only in interactive terminals and respects `NO_COLOR`.
 
 ## Safety

package/README.md

@@ -51,6 +51,7 @@ codex-history doctor
 codex-history list
 codex-history list --grep "Astro"
 codex-history purge 019e6885
+codex-history purge 019e6885 019e6874
 codex-history purge-orphans
 ```
 
@@ -75,7 +76,7 @@ Type 019e6885 to confirm:
 | `codex-history doctor` | 检查当前本地 Codex 数据结构是否受支持。 |
 | `codex-history list` | 列出本地对话。 |
 | `codex-history list --grep <keyword>` | 按标题、id 或 cwd 过滤对话。 |
-| `codex-history purge <id>` | 确认后删除一条解析到的本地对话。 |
+| `codex-history purge <id...>` | 确认后删除一条或多条解析到的本地对话。 |
 | `codex-history purge-orphans` | 确认后清理本地孤儿数据。 |
 
 ### `doctor`
@@ -129,19 +130,23 @@ codex-history list --grep "Astro 博客"
 
 ### `purge`
 
-通过完整 id 或唯一短 id 前缀删除一条本地 Codex 对话。
+通过完整 id 或唯一短 id 前缀删除一条或多条本地 Codex 对话。
 
 ```bash
 codex-history purge 019e6885
+codex-history purge 019e6885 019e6874
 ```
 
+删除多个目标时，工具会先解析全部目标并展示批量计划；只要任意一个 id 不存在、不唯一，或命中 active thread，整个批量操作都会拒绝执行，不会部分删除。交互式批量删除需要输入 `purge-selected` 确认。
+
 脚本或非交互环境可以使用 `--force`：
 
 ```bash
 codex-history purge 019e6885 --force
+codex-history purge 019e6885 019e6874 --force
 ```
 
-`--force` 只跳过交互式短 id 确认，不会跳过数据结构校验、active thread 保护和删除后的验证。
+`--force` 只跳过交互确认，不会跳过数据结构校验、active thread 保护和删除后的验证。
 
 ### `purge-orphans`
 
@@ -159,7 +164,7 @@ codex-history purge-orphans
 codex-history purge-orphans --force
 ```
 
-`--force` 只跳过交互确认，不会跳过数据结构校验、active thread 保护和删除后的验证。`purge-orphans` 不支持 JSON 输出。
+`--force` 只跳过交互确认，不会跳过数据结构校验、active thread 保护和删除后的验证。
 
 空间统计是估算值。SQLite 删除记录后，数据库文件可能不会立刻缩小，直到 Codex 或其他 SQLite 维护步骤执行 vacuum。
 
@@ -167,13 +172,9 @@ codex-history purge-orphans --force
 
 ```bash
 codex-history --codex-home /path/to/.codex list
-codex-history --json list --grep "Astro"
-codex-history --json purge 019e6885 --force
 ```
 
 - `--codex-home` 默认是 `~/.codex`。
-- `--json` 输出机器可读的 JSON。`purge` 使用 JSON 输出时必须加 `--force`，因为交互确认只适合文本模式。
-- `purge-orphans` 不支持 JSON 输出。
 - 颜色只会在交互式终端中启用，并遵守 `NO_COLOR`。
 
 ## 安全机制

package/dist/cli.js

@@ -837,15 +837,47 @@ function findShellSnapshots(shellSnapshotsDir, threadId) {
 }
 
 // src/commands/purge.ts
-function planPurgeCommand(paths, threadId) {
+function planBatchPurgeCommand(paths, threadIds) {
   validateSupportedDataModel(paths);
-  const target = resolvePurgeTarget(paths, threadId);
-  return buildPurgePlan(paths, target);
+  const plans = [];
+  const seenTargets = /* @__PURE__ */ new Set();
+  const duplicateInputs = [];
+  for (const threadId of threadIds) {
+    const target = resolvePurgeTarget(paths, threadId);
+    if (seenTargets.has(target.id)) {
+      duplicateInputs.push({ input: threadId, targetId: target.id });
+      continue;
+    }
+    seenTargets.add(target.id);
+    plans.push(buildPurgePlan(paths, target));
+  }
+  return {
+    mode: "planned",
+    requestedCount: threadIds.length,
+    plans,
+    duplicateInputs
+  };
 }
 function executePurgePlanCommand(paths, plan) {
   validateSupportedDataModel(paths);
   return executePurge(paths, plan);
 }
+function executeBatchPurgePlanCommand(paths, plan) {
+  validateSupportedDataModel(paths);
+  const activeThreadChecks = plan.plans.flatMap((item) => assertThreadIsNotActive(item.target));
+  const purgeReports = plan.plans.map((item) => executePurge(paths, item, { skipActiveThreadCheck: true }));
+  const remainingReferences = purgeReports.flatMap((report) => report.verification.remainingReferences);
+  return {
+    mode: "executed",
+    plan,
+    activeThreadChecks,
+    purgeReports,
+    verification: {
+      success: remainingReferences.length === 0,
+      remainingReferences
+    }
+  };
+}
 
 // src/core/orphans.ts
 import { existsSync as existsSync10 } from "fs";
@@ -1049,11 +1081,7 @@ function executePurgeOrphansPlanCommand(paths, plan) {
 }
 
 // src/core/output.ts
-function printOutput(value, mode) {
-  if (mode === "json") {
-    console.log(JSON.stringify(value, null, 2));
-    return;
-  }
+function printOutput(value) {
   if (typeof value === "string") {
     if (value.length === 0) {
       return;
@@ -1077,7 +1105,7 @@ function shortId(id) {
 var TITLE_MAX_LENGTH = 80;
 var packageVersion = JSON.parse(readFileSync5(new URL("../package.json", import.meta.url), "utf8")).version;
 var program = new Command();
-program.name("codex-history").description("Inspect and safely purge local Codex conversation history.").version(packageVersion).option("--codex-home <path>", "Path to Codex home directory", "~/.codex").option("--json", "Print machine-readable JSON output");
+program.name("codex-history").description("Inspect and safely purge local Codex conversation history.").version(packageVersion).option("--codex-home <path>", "Path to Codex home directory", "~/.codex");
 program.command("doctor").description("Check whether the local Codex data model is supported.").action(
   () => runCommand(() => {
     const report = doctorCommand(currentPaths());
@@ -1102,25 +1130,26 @@ program.command("list").description("List local Codex conversations.").option("-
     )
   )
 );
-program.command("purge").argument("<threadId>", "Codex thread id or unique short id prefix to purge").option("--force", "Skip interactive confirmation").description("Purge one local Codex conversation after target confirmation.").action(
-  (threadId, options) => runCommand(async () => {
+program.command("purge").argument("<threadIds...>", "Codex thread id(s) or unique short id prefix(es) to purge").option("--force", "Skip interactive confirmation").description("Purge local Codex conversation(s) after target confirmation.").action(
+  (threadIds, options) => runCommand(async () => {
     const paths = currentPaths();
-    const plan = planPurgeCommand(paths, threadId);
+    const plan = planBatchPurgeCommand(paths, threadIds);
     const force = Boolean(options.force);
-    if (currentOutputModeIsJson() && !force) {
-      throw new UsageError("JSON purge output requires --force because interactive confirmation is text-only.");
+    const useBatchConfirmation = plan.requestedCount > 1;
+    if (plan.plans.length === 1 && !useBatchConfirmation) {
+      if (!force) {
+        await confirmPurge(plan.plans[0]);
+      }
+      return formatPurgeResult(executePurgePlanCommand(paths, plan.plans[0]));
     }
     if (!force) {
-      await confirmPurge(plan);
+      await confirmBatchPurge(plan);
     }
-    return formatPurgeResult(executePurgePlanCommand(paths, plan));
+    return formatBatchPurgeResult(executeBatchPurgePlanCommand(paths, plan));
   })
 );
 program.command("purge-orphans").option("--force", "Skip interactive confirmation").description("Purge orphaned local Codex data after target confirmation.").action(
   (options) => runCommand(async () => {
-    if (currentOutputModeIsJson()) {
-      throw new UsageError("purge-orphans does not support JSON output.");
-    }
     const paths = currentPaths();
     const plan = planPurgeOrphansCommand(paths);
     const force = Boolean(options.force);
@@ -1134,23 +1163,16 @@ program.command("purge-orphans").option("--force", "Skip interactive confirmatio
   })
 );
 await program.parseAsync();
-function currentOutputMode() {
-  return program.opts().json ? "json" : "text";
-}
 function currentPaths() {
   return resolvePaths(program.opts().codexHome);
 }
 async function runCommand(produce) {
   try {
-    printOutput(await produce(), currentOutputMode());
+    printOutput(await produce());
   } catch (error) {
     const exitCode = error instanceof CodexHistoryError ? error.exitCode : 1;
     const message = error instanceof Error ? error.message : String(error);
-    if (currentOutputMode() === "json") {
-      console.error(JSON.stringify({ error: message, exitCode }, null, 2));
-    } else {
-      console.error(`${colorizeError("red", "Error:")} ${message}`);
-    }
+    console.error(`${colorizeError("red", "Error:")} ${message}`);
     process.exitCode = exitCode;
   }
 }
@@ -1168,10 +1190,7 @@ function parsePretty(value) {
   throw new Error(`Expected pretty format oneline, medium, or full; got: ${value}`);
 }
 function shouldUsePager(options) {
-  return Boolean(options.limit === void 0 && process.stdout.isTTY && !currentOutputModeIsJson());
-}
-function currentOutputModeIsJson() {
-  return currentOutputMode() === "json";
+  return Boolean(options.limit === void 0 && process.stdout.isTTY);
 }
 async function confirmPurge(plan) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -1192,6 +1211,25 @@ async function confirmPurge(plan) {
     readline.close();
   }
 }
+async function confirmBatchPurge(plan) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new SafetyRefusalError("Batch purge requires an interactive terminal. Use --force to skip confirmation.");
+  }
+  const expected = "purge-selected";
+  process.stdout.write(formatBatchPurgeConfirmation(plan));
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    const answer = await readline.question(`Type ${colorize("yellow", expected)} to confirm: `);
+    if (answer.trim() !== expected) {
+      throw new SafetyRefusalError("Confirmation did not match. No local Codex data was modified.");
+    }
+  } finally {
+    readline.close();
+  }
+}
 async function confirmPurgeOrphans(plan) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     throw new SafetyRefusalError("purge-orphans requires an interactive terminal. Use --force to skip confirmation.");
@@ -1212,9 +1250,6 @@ async function confirmPurgeOrphans(plan) {
   }
 }
 function formatDoctor(report) {
-  if (currentOutputMode() === "json") {
-    return report;
-  }
   const lines = [
     `${colorize("dim", "Codex home:")} ${colorize("dim", report.codexHome)}`,
     `${colorize("dim", "Supported:")} ${report.supported ? colorize("green", "yes") : colorize("red", "no")}`,
@@ -1226,9 +1261,6 @@ function formatDoctor(report) {
   return lines.join("\n");
 }
 function formatThreads(threads, pretty = "oneline", usePager = false) {
-  if (currentOutputMode() === "json") {
-    return { count: threads.length, threads: threads.map(toPublicThread) };
-  }
   if (threads.length === 0) {
     return "No Codex conversations found.";
   }
@@ -1274,9 +1306,6 @@ function pageText(text) {
   return "";
 }
 function formatPurgeResult(result) {
-  if (currentOutputMode() === "json") {
-    return sanitizePurgeResult(result);
-  }
   const lines = [
     colorize("green", "Purge executed."),
     "",
@@ -1306,6 +1335,38 @@ function formatPurgeResult(result) {
   }
   return lines.join("\n");
 }
+function formatBatchPurgeResult(result) {
+  const sqliteChanges = aggregateBatchSqliteChanges(result);
+  const jsonChanged = result.purgeReports.flatMap((report) => report.json).filter((change) => change.changed).length;
+  const filesDeleted = result.purgeReports.flatMap((report) => report.files).filter((change) => change.deleted).length;
+  const lines = [
+    colorize("green", "Batch purge executed."),
+    "",
+    "Summary:",
+    `- Requested targets: ${result.plan.requestedCount}`,
+    `- Unique targets purged: ${result.plan.plans.length}`,
+    `- Duplicate inputs skipped: ${result.plan.duplicateInputs.length}`,
+    `- SQLite row changes: ${sqliteChanges.reduce((sum, change) => sum + change.rows, 0)}`,
+    `- JSON/JSONL file changes: ${jsonChanged}`,
+    `- Files deleted: ${filesDeleted}`,
+    "",
+    "SQLite changes:",
+    ...formatSqliteRows(sqliteChanges),
+    "",
+    `Verification: ${result.verification.success ? colorize("green", "passed") : colorize("red", "failed")}`
+  ];
+  if (result.verification.remainingReferences.length > 0) {
+    lines.push(
+      "",
+      "Remaining references:",
+      ...result.verification.remainingReferences.map(
+        (reference) => `- ${reference.store}: ${reference.path} (${reference.detail})`
+      )
+    );
+    process.exitCode = 1;
+  }
+  return lines.join("\n");
+}
 function formatPurgeOrphansPlan(plan) {
   if (!hasPurgeOrphansWork(plan)) {
     return "No orphaned local Codex data found.";
@@ -1359,6 +1420,22 @@ function formatPurgeConfirmation(plan) {
     ""
   ].join("\n");
 }
+function formatBatchPurgeConfirmation(plan) {
+  return [
+    "About to purge selected local Codex conversations:",
+    "",
+    `Requested targets: ${plan.requestedCount}`,
+    `Unique targets: ${plan.plans.length}`,
+    `Duplicate inputs skipped: ${plan.duplicateInputs.length}`,
+    "",
+    "SQLite row changes:",
+    ...formatSqliteRows(summarizePlannedSqliteRows(plan.plans)),
+    "",
+    ...formatBatchPurgeExamples(plan),
+    colorize("dim", "This cannot be undone."),
+    ""
+  ].join("\n");
+}
 function formatPurgeOrphansConfirmation(plan) {
   return [
     "About to purge orphaned local Codex data:",
@@ -1402,6 +1479,44 @@ function formatOrphanExamples(plan) {
   }
   return lines;
 }
+function formatBatchPurgeExamples(plan) {
+  const examples = plan.plans.slice(0, 5).map((item) => {
+    const target = item.target;
+    return `- ${shortId(target.id)}  ${displayTitle(target.title)}  ${colorize("dim", target.cwd)}`;
+  });
+  if (examples.length === 0) {
+    return [];
+  }
+  const lines = ["Targets:", ...examples, ""];
+  if (plan.plans.length > examples.length) {
+    lines.push(`Showing ${examples.length} of ${plan.plans.length} target(s).`, "");
+  }
+  return lines;
+}
+function summarizePlannedSqliteRows(plans) {
+  const rows = /* @__PURE__ */ new Map();
+  for (const plan of plans) {
+    for (const store of plan.stores) {
+      if (store.action !== "delete_rows" && store.store !== "state_db.agent_job_items") {
+        continue;
+      }
+      if (!store.count || store.count <= 0) {
+        continue;
+      }
+      rows.set(store.store, (rows.get(store.store) ?? 0) + store.count);
+    }
+  }
+  return [...rows.entries()].map(([store, count]) => ({ store, rows: count })).sort((a, b) => a.store.localeCompare(b.store));
+}
+function aggregateBatchSqliteChanges(result) {
+  const changes = /* @__PURE__ */ new Map();
+  for (const report of result.purgeReports) {
+    for (const change of report.sqlite) {
+      changes.set(change.store, (changes.get(change.store) ?? 0) + change.changedRows);
+    }
+  }
+  return [...changes.entries()].filter(([, rows]) => rows > 0).map(([store, rows]) => ({ store, rows })).sort((a, b) => a.store.localeCompare(b.store));
+}
 function aggregateOrphanSqliteChanges(result) {
   const changes = /* @__PURE__ */ new Map();
   for (const report of result.purgeReports) {
@@ -1473,7 +1588,7 @@ function errorColorsEnabled() {
   return streamColorsEnabled(process.stderr);
 }
 function streamColorsEnabled(stream) {
-  return !currentOutputModeIsJson() && !("NO_COLOR" in process.env) && Boolean(stream.isTTY);
+  return !("NO_COLOR" in process.env) && Boolean(stream.isTTY);
 }
 function displayTitle(title) {
   const normalized = title.trim().replaceAll(/\s+/g, " ");
@@ -1485,24 +1600,3 @@ function displayTitle(title) {
   }
   return `${normalized.slice(0, TITLE_MAX_LENGTH - 3)}...`;
 }
-function toPublicThread(thread) {
-  return {
-    id: thread.id,
-    title: displayTitle(thread.title),
-    titleTruncated: thread.title.trim().replaceAll(/\s+/g, " ").length > TITLE_MAX_LENGTH,
-    rolloutPath: thread.rolloutPath,
-    createdAtMs: thread.createdAtMs,
-    updatedAtMs: thread.updatedAtMs,
-    cwd: thread.cwd,
-    archived: thread.archived
-  };
-}
-function sanitizePurgeResult(result) {
-  return {
-    ...result,
-    plan: {
-      ...result.plan,
-      target: toPublicThread(result.plan.target)
-    }
-  };
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liuyoumi/codex-history",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "CLI for listing and safely purging local Codex conversation history",
   "type": "module",
   "bin": {