@liuyoumi/codex-history 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,12 +1,24 @@
 # Changelog
 
+## 0.1.3 - 2026-05-29
+
+### Changed
+
+- Remove purge backup creation and document `purge` as a permanent local deletion flow.
+- Report the CLI version from `package.json` instead of a stale hard-coded value.
+
+### Documentation
+
+- Refresh the README cover image to show only the terminal window.
+- Add agent workflow guidance for future implementation work.
+- Clarify the boundary between `AGENTS.md` and `docs/agent-workflow.md`.
+
 ## 0.1.2 - 2026-05-28
 
 ### Documentation
 
 - Use Chinese as the default README language.
 - Add an English README translation.
-- Refresh the README cover image to focus on a single guarded `purge` command flow.
 - Add README badges and clearer macOS, Windows, and Linux support notes.
 
 ## 0.1.1 - 2026-05-28
@@ -28,7 +40,7 @@ Initial release candidate.
 - `purge <id>` execution by full id or unique short id prefix.
 - Interactive purge confirmation by typing the standard short id.
 - `purge <id> --force` for non-interactive execution.
-- Guarded purge execution with mandatory backups.
+- Guarded purge execution with explicit confirmation.
 - SQLite cleanup for supported Codex stores.
 - JSON and JSONL state cleanup for supported Codex files.
 - Rollout jsonl and shell snapshot deletion.

package/README.en.md

@@ -4,7 +4,7 @@
   <img alt="npm" src="https://img.shields.io/npm/v/@liuyoumi/codex-history?style=flat-square&color=cb9b27" />
   <img alt="platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-2ea043?style=flat-square" />
   <img alt="local only" src="https://img.shields.io/badge/local%20data-only-6e7681?style=flat-square" />
-  <img alt="backup" src="https://img.shields.io/badge/backup-before%20purge-0969da?style=flat-square" />
+  <img alt="confirm" src="https://img.shields.io/badge/confirm-before%20purge-0969da?style=flat-square" />
   <img alt="license" src="https://img.shields.io/npm/l/@liuyoumi/codex-history?style=flat-square" />
 </p>
 
@@ -34,7 +34,7 @@ npx @liuyoumi/codex-history doctor
 
 ## Supported Platforms
 
-`codex-history` has been checked on macOS, Windows, and Linux for install, `doctor`, `list` / `--grep`, and guarded `purge` workflows with confirmation and backups.
+`codex-history` has been checked on macOS, Windows, and Linux for install, `doctor`, `list` / `--grep`, and guarded `purge` workflows with confirmation.
 
 | Platform | Status |
 | --- | --- |
@@ -63,7 +63,7 @@ id: 019e6885-b5ae-7ae0-a50d-ce5f75b0ac08
 cwd: /Users/me/Projects/example
 updated: 2026-05-28T03:16:01.959Z
 
-A backup will be created before deletion.
+This cannot be undone.
 Type 019e6885 to confirm:
 ```
 
@@ -139,7 +139,7 @@ For scripts or non-interactive shells, use `--force`:
 codex-history purge 019e6885 --force
 ```
 
-`--force` skips only the interactive short-id confirmation. It still keeps schema validation, mandatory backup, active-thread protection, and post-purge verification.
+`--force` skips only the interactive short-id confirmation. It still keeps schema validation, active-thread protection, and post-purge verification.
 
 ## Options
 
@@ -160,7 +160,6 @@ Before deleting, `codex-history`:
 - validates the supported Codex data model
 - resolves the target to exactly one conversation
 - refuses the currently active thread when detectable
-- creates a mandatory backup under `~/.codex-history/backups`
 - removes known references from supported local Codex stores
 - verifies supported stores after mutation
 
@@ -174,13 +173,9 @@ If Codex Desktop is already showing the conversation you purge, quit or restart
 
 No. It only modifies supported local files on your machine.
 
-### Where are backups stored?
-
-Backups are written under `~/.codex-history/backups`.
-
 ### Can I recover a purged conversation?
 
-The tool creates a backup before deletion, but v0.1 does not include an automatic restore command. Treat `purge` as destructive.
+Not with this tool. Treat `purge` as destructive.
 
 ### Do I need to restart Codex after purging?
 

package/README.md

@@ -4,7 +4,7 @@
   <img alt="npm" src="https://img.shields.io/npm/v/@liuyoumi/codex-history?style=flat-square&color=cb9b27" />
   <img alt="platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-2ea043?style=flat-square" />
   <img alt="local only" src="https://img.shields.io/badge/local%20data-only-6e7681?style=flat-square" />
-  <img alt="backup" src="https://img.shields.io/badge/backup-before%20purge-0969da?style=flat-square" />
+  <img alt="confirm" src="https://img.shields.io/badge/confirm-before%20purge-0969da?style=flat-square" />
   <img alt="license" src="https://img.shields.io/npm/l/@liuyoumi/codex-history?style=flat-square" />
 </p>
 
@@ -34,7 +34,7 @@ npx @liuyoumi/codex-history doctor
 
 ## 支持平台
 
-`codex-history` 已在 macOS、Windows、Linux 上完成基础流程验证，包括安装、`doctor`、`list` / `--grep`，以及带确认和备份保护的 `purge`。
+`codex-history` 已在 macOS、Windows、Linux 上完成基础流程验证，包括安装、`doctor`、`list` / `--grep`，以及带确认保护的 `purge`。
 
 | 平台 | 状态 |
 | --- | --- |
@@ -63,7 +63,7 @@ id: 019e6885-b5ae-7ae0-a50d-ce5f75b0ac08
 cwd: /Users/me/Projects/example
 updated: 2026-05-28T03:16:01.959Z
 
-A backup will be created before deletion.
+This cannot be undone.
 Type 019e6885 to confirm:
 ```
 
@@ -139,7 +139,7 @@ codex-history purge 019e6885
 codex-history purge 019e6885 --force
 ```
 
-`--force` 只跳过交互式短 id 确认，不会跳过数据结构校验、强制备份、active thread 保护和删除后的验证。
+`--force` 只跳过交互式短 id 确认，不会跳过数据结构校验、active thread 保护和删除后的验证。
 
 ## 选项
 
@@ -160,7 +160,6 @@ codex-history --json purge 019e6885 --force
 - 校验当前 Codex 本地数据结构是否受支持
 - 将目标解析到唯一一条对话
 - 在可检测时拒绝删除当前 active thread
-- 在 `~/.codex-history/backups` 下创建强制备份
 - 从受支持的本地 Codex 数据中移除已知引用
 - 删除后扫描受支持的数据存储，确认目标引用已经移除
 
@@ -174,13 +173,9 @@ codex-history --json purge 019e6885 --force
 
 不会。它只修改你机器上受支持的本地文件。
 
-### 备份在哪里？
-
-备份会写入 `~/.codex-history/backups`。
-
 ### 删除后还能恢复吗？
 
-工具会在删除前创建备份，但 v0.1 还没有自动恢复命令。请把 `purge` 当作破坏性操作对待。
+不能通过这个工具恢复。请把 `purge` 当作破坏性操作对待。
 
 ### 删除后需要重启 Codex 吗？
 

package/dist/cli.js

@@ -3,11 +3,11 @@
 // src/cli.ts
 import { Command } from "commander";
 import { spawnSync } from "child_process";
+import { readFileSync as readFileSync5 } from "fs";
 import { createInterface } from "readline/promises";
 
 // src/core/schema.ts
-import { mkdirSync, readFileSync } from "fs";
-import { dirname } from "path";
+import { readFileSync } from "fs";
 
 // src/core/paths.ts
 import { existsSync } from "fs";
@@ -22,13 +22,10 @@ function expandHome(input) {
   }
   return input;
 }
-function resolvePaths(codexHomeInput, toolHomeInput) {
+function resolvePaths(codexHomeInput) {
   const codexHome = path.resolve(expandHome(codexHomeInput ?? "~/.codex"));
-  const toolHome = path.resolve(expandHome(toolHomeInput ?? process.env.CODEX_HISTORY_HOME ?? "~/.codex-history"));
   return {
     codexHome,
-    toolHome,
-    backupHome: path.join(toolHome, "backups"),
     stateDb: path.join(codexHome, "state_5.sqlite"),
     logsDb: path.join(codexHome, "logs_2.sqlite"),
     goalsDb: path.join(codexHome, "goals_1.sqlite"),
@@ -122,18 +119,15 @@ function runDoctor(paths) {
   checks.push(checkJsonFile(paths.globalState, "global_state"));
   checks.push(checkJsonFile(paths.globalStateBackup, "global_state_backup"));
   checks.push(checkJsonlFile(paths.sessionIndex, "session_index"));
-  checks.push(checkBackupHome(paths.backupHome));
   return {
     supported: !checks.some((check) => check.status === "error"),
     codexHome: paths.codexHome,
     checks
   };
 }
-function validateSupportedDataModel(paths, options = {}) {
+function validateSupportedDataModel(paths) {
   const report = runDoctor(paths);
-  const errors = report.checks.filter(
-    (check) => check.status === "error" && (options.requireBackupHome || check.name !== "backup_home")
-  );
+  const errors = report.checks.filter((check) => check.status === "error");
   if (errors.length > 0) {
     const details = errors.map((check) => `${check.name}: ${check.detail}`).join("; ");
     throw new Error(`Unsupported Codex data model: ${details}`);
@@ -255,23 +249,6 @@ function checkJsonlFile(filePath, name) {
     };
   }
 }
-function checkBackupHome(backupHome) {
-  try {
-    mkdirSync(dirname(backupHome), { recursive: true });
-    mkdirSync(backupHome, { recursive: true });
-    return {
-      name: "backup_home",
-      status: "ok",
-      detail: backupHome
-    };
-  } catch (error) {
-    return {
-      name: "backup_home",
-      status: "error",
-      detail: error instanceof Error ? error.message : String(error)
-    };
-  }
-}
 
 // src/commands/doctor.ts
 function doctorCommand(paths) {
@@ -393,7 +370,7 @@ function listCommand(paths, options = {}) {
 }
 
 // src/core/executor.ts
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync8 } from "fs";
 
 // src/safety/active-thread.ts
 import { existsSync as existsSync4, statSync } from "fs";
@@ -450,71 +427,8 @@ function assertThreadIsNotActive(target) {
   return checks;
 }
 
-// src/safety/backup.ts
-import { copyFileSync, existsSync as existsSync5, mkdirSync as mkdirSync2, statSync as statSync2, writeFileSync } from "fs";
-import path2 from "path";
-function createBackup(paths, plan) {
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(/[:.]/g, "-");
-  const backupDir = path2.join(paths.backupHome, `${timestamp}-${plan.target.id}`);
-  mkdirSync2(backupDir, { recursive: true });
-  const candidates = /* @__PURE__ */ new Set();
-  candidates.add(paths.stateDb);
-  addIfPresent(candidates, `${paths.stateDb}-wal`);
-  addIfPresent(candidates, `${paths.stateDb}-shm`);
-  addIfPresent(candidates, paths.logsDb);
-  addIfPresent(candidates, `${paths.logsDb}-wal`);
-  addIfPresent(candidates, `${paths.logsDb}-shm`);
-  addIfPresent(candidates, paths.goalsDb);
-  addIfPresent(candidates, `${paths.goalsDb}-wal`);
-  addIfPresent(candidates, `${paths.goalsDb}-shm`);
-  addIfPresent(candidates, paths.sessionIndex);
-  addIfPresent(candidates, paths.globalState);
-  addIfPresent(candidates, paths.globalStateBackup);
-  addIfPresent(candidates, plan.target.rolloutPath);
-  for (const store of plan.stores) {
-    if (store.store === "shell_snapshot") {
-      addIfPresent(candidates, store.path);
-    }
-  }
-  const entries = [];
-  for (const originalPath of candidates) {
-    if (!existsSync5(originalPath)) {
-      continue;
-    }
-    const backupPath = uniqueBackupPath(backupDir, originalPath);
-    mkdirSync2(path2.dirname(backupPath), { recursive: true });
-    copyFileSync(originalPath, backupPath);
-    const stats = statSync2(originalPath);
-    entries.push({
-      originalPath,
-      backupPath,
-      size: stats.size,
-      mtimeMs: stats.mtimeMs
-    });
-  }
-  const manifest = {
-    threadId: plan.target.id,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    backupDir,
-    entries
-  };
-  writeFileSync(path2.join(backupDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
-  return manifest;
-}
-function addIfPresent(paths, filePath) {
-  if (existsSync5(filePath)) {
-    paths.add(filePath);
-  }
-}
-function uniqueBackupPath(backupDir, originalPath) {
-  const parsed = path2.parse(originalPath);
-  const safeBase = `${parsed.name}${parsed.ext}`.replaceAll(/[^a-zA-Z0-9._-]/g, "_");
-  const hash = Buffer.from(originalPath).toString("base64url").slice(0, 12);
-  return path2.join(backupDir, `${hash}-${safeBase}`);
-}
-
 // src/safety/verify.ts
-import { existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync3 } from "fs";
 function verifyPurge(paths, plan) {
   const remainingReferences = [];
   const threadId = plan.target.id;
@@ -524,7 +438,7 @@ function verifyPurge(paths, plan) {
   checkTextFile(paths.sessionIndex, "session_index", threadId, remainingReferences);
   checkTextFile(paths.globalState, "global_state", threadId, remainingReferences);
   checkTextFile(paths.globalStateBackup, "global_state_backup", threadId, remainingReferences);
-  if (existsSync6(plan.target.rolloutPath)) {
+  if (existsSync5(plan.target.rolloutPath)) {
     remainingReferences.push({
       store: "rollout_jsonl",
       path: plan.target.rolloutPath,
@@ -532,7 +446,7 @@ function verifyPurge(paths, plan) {
     });
   }
   for (const store of plan.stores) {
-    if (store.store === "shell_snapshot" && existsSync6(store.path)) {
+    if (store.store === "shell_snapshot" && existsSync5(store.path)) {
       remainingReferences.push({
         store: "shell_snapshot",
         path: store.path,
@@ -546,7 +460,7 @@ function verifyPurge(paths, plan) {
   };
 }
 function checkSqlite(filePath, store, threadId, remainingReferences) {
-  if (!existsSync6(filePath)) {
+  if (!existsSync5(filePath)) {
     return;
   }
   const db = openReadonlyDatabase(filePath);
@@ -578,7 +492,7 @@ function checkSqlite(filePath, store, threadId, remainingReferences) {
   }
 }
 function checkTextFile(filePath, store, threadId, remainingReferences) {
-  if (!existsSync6(filePath)) {
+  if (!existsSync5(filePath)) {
     return;
   }
   const content = readFileSync3(filePath, "utf8");
@@ -592,9 +506,9 @@ function checkTextFile(filePath, store, threadId, remainingReferences) {
 }
 
 // src/stores/files.ts
-import { existsSync as existsSync7, unlinkSync } from "fs";
+import { existsSync as existsSync6, unlinkSync } from "fs";
 function deleteFileIfExists(filePath) {
-  if (!existsSync7(filePath)) {
+  if (!existsSync6(filePath)) {
     return {
       path: filePath,
       deleted: false
@@ -608,9 +522,9 @@ function deleteFileIfExists(filePath) {
 }
 
 // src/stores/json-state.ts
-import { existsSync as existsSync8, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync4, writeFileSync } from "fs";
 function removeThreadFromSessionIndex(filePath, threadId) {
-  if (!existsSync8(filePath)) {
+  if (!existsSync7(filePath)) {
     return { path: filePath, changed: false };
   }
   const original = readFileSync4(filePath, "utf8");
@@ -626,12 +540,12 @@ function removeThreadFromSessionIndex(filePath, threadId) {
 ` : "";
   const changed = next !== original;
   if (changed) {
-    writeFileSync2(filePath, next);
+    writeFileSync(filePath, next);
   }
   return { path: filePath, changed };
 }
 function removeThreadFromGlobalState(filePath, threadId) {
-  if (!existsSync8(filePath)) {
+  if (!existsSync7(filePath)) {
     return { path: filePath, changed: false };
   }
   const original = readFileSync4(filePath, "utf8");
@@ -639,7 +553,7 @@ function removeThreadFromGlobalState(filePath, threadId) {
   const nextValue = removeThreadReferences(parsed, threadId);
   const next = JSON.stringify(nextValue.value, null, 2) + "\n";
   if (nextValue.changed) {
-    writeFileSync2(filePath, next);
+    writeFileSync(filePath, next);
   }
   return {
     path: filePath,
@@ -681,7 +595,6 @@ function removeThreadReferences(value, threadId) {
 // src/core/executor.ts
 function executePurge(paths, plan) {
   const activeThreadChecks = assertThreadIsNotActive(plan.target);
-  const backup = createBackup(paths, plan);
   const sqlite = purgeSqlite(paths, plan.target.id);
   const json = [
     removeThreadFromSessionIndex(paths.sessionIndex, plan.target.id),
@@ -697,7 +610,6 @@ function executePurge(paths, plan) {
     mode: "executed",
     plan,
     activeThreadChecks,
-    backup,
     sqlite,
     json,
     files,
@@ -706,7 +618,7 @@ function executePurge(paths, plan) {
 }
 function purgeSqlite(paths, threadId) {
   const results = [];
-  if (existsSync9(paths.stateDb)) {
+  if (existsSync8(paths.stateDb)) {
     const db = openWritableDatabase(paths.stateDb);
     try {
       const transaction = db.transaction(() => {
@@ -727,7 +639,7 @@ function purgeSqlite(paths, threadId) {
       db.close();
     }
   }
-  if (existsSync9(paths.logsDb)) {
+  if (existsSync8(paths.logsDb)) {
     const db = openWritableDatabase(paths.logsDb);
     try {
       const transaction = db.transaction(() => {
@@ -738,7 +650,7 @@ function purgeSqlite(paths, threadId) {
       db.close();
     }
   }
-  if (existsSync9(paths.goalsDb)) {
+  if (existsSync8(paths.goalsDb)) {
     const db = openWritableDatabase(paths.goalsDb);
     try {
       const transaction = db.transaction(() => {
@@ -773,8 +685,8 @@ function purgeFiles(plan) {
 }
 
 // src/core/planner.ts
-import { existsSync as existsSync10, readdirSync, statSync as statSync3 } from "fs";
-import path3 from "path";
+import { existsSync as existsSync9, readdirSync, statSync as statSync2 } from "fs";
+import path2 from "path";
 function resolvePurgeTarget(paths, threadId) {
   if (!threadId.trim()) {
     throw new UsageError("Provide a thread id or unique short id prefix.");
@@ -801,7 +713,7 @@ function buildPurgePlan(paths, target) {
   for (const snapshot of findShellSnapshots(paths.shellSnapshotsDir, target.id)) {
     stores.push(planDeleteFile(snapshot, "shell_snapshot"));
   }
-  if (!existsSync10(target.rolloutPath)) {
+  if (!existsSync9(target.rolloutPath)) {
     warnings.push(`rollout file is missing: ${target.rolloutPath}`);
   }
   return {
@@ -812,7 +724,7 @@ function buildPurgePlan(paths, target) {
   };
 }
 function planStateDb(filePath, threadId) {
-  if (!existsSync10(filePath)) {
+  if (!existsSync9(filePath)) {
     return [missingStore("state_db", filePath)];
   }
   const db = openReadonlyDatabase(filePath);
@@ -845,7 +757,7 @@ function planStateDb(filePath, threadId) {
   }
 }
 function planLogsDb(filePath, threadId) {
-  if (!existsSync10(filePath)) {
+  if (!existsSync9(filePath)) {
     return [missingStore("logs_db", filePath)];
   }
   const db = openReadonlyDatabase(filePath);
@@ -856,7 +768,7 @@ function planLogsDb(filePath, threadId) {
   }
 }
 function planGoalsDb(filePath, threadId) {
-  if (!existsSync10(filePath)) {
+  if (!existsSync9(filePath)) {
     return [missingStore("goals_db", filePath)];
   }
   const db = openReadonlyDatabase(filePath);
@@ -874,7 +786,7 @@ function countTable(db, filePath, tableName, columnName, threadId, storeName) {
       path: filePath,
       action: "inspect",
       detail: `table or column unavailable: ${tableName}.${columnName}`,
-      exists: existsSync10(filePath)
+      exists: existsSync9(filePath)
     };
   }
   return countPlan(storeName ?? `state_db.${tableName}`, filePath, count, "delete matching rows");
@@ -895,7 +807,7 @@ function planRewrite(filePath, store, detail) {
     path: filePath,
     action: "rewrite",
     detail,
-    exists: existsSync10(filePath)
+    exists: existsSync9(filePath)
   };
 }
 function planDeleteFile(filePath, store) {
@@ -904,8 +816,8 @@ function planDeleteFile(filePath, store) {
     path: filePath,
     action: "delete_file",
     detail: "delete file",
-    exists: existsSync10(filePath),
-    count: existsSync10(filePath) ? statSync3(filePath).size : 0
+    exists: existsSync9(filePath),
+    count: existsSync9(filePath) ? statSync2(filePath).size : 0
   };
 }
 function missingStore(store, filePath) {
@@ -918,10 +830,10 @@ function missingStore(store, filePath) {
   };
 }
 function findShellSnapshots(shellSnapshotsDir, threadId) {
-  if (!existsSync10(shellSnapshotsDir)) {
+  if (!existsSync9(shellSnapshotsDir)) {
     return [];
   }
-  return readdirSync(shellSnapshotsDir).filter((entry) => entry.startsWith(`${threadId}.`) && entry.endsWith(".sh")).map((entry) => path3.join(shellSnapshotsDir, entry));
+  return readdirSync(shellSnapshotsDir).filter((entry) => entry.startsWith(`${threadId}.`) && entry.endsWith(".sh")).map((entry) => path2.join(shellSnapshotsDir, entry));
 }
 
 // src/commands/purge.ts
@@ -931,7 +843,7 @@ function planPurgeCommand(paths, threadId) {
   return buildPurgePlan(paths, target);
 }
 function executePurgePlanCommand(paths, plan) {
-  validateSupportedDataModel(paths, { requireBackupHome: true });
+  validateSupportedDataModel(paths);
   return executePurge(paths, plan);
 }
 
@@ -962,8 +874,9 @@ function shortId(id) {
 
 // src/cli.ts
 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("0.1.0").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").option("--json", "Print machine-readable JSON output");
 program.command("doctor").description("Check whether the local Codex data model is supported.").action(
   () => runCommand(() => {
     const report = doctorCommand(currentPaths());
@@ -1132,7 +1045,6 @@ function formatPurgeResult(result) {
     "",
     `Target: ${displayTitle(result.plan.target.title)}`,
     `Thread id: ${result.plan.target.id}`,
-    `Backup: ${colorize("dim", result.backup.backupDir)}`,
     "",
     "SQLite changes:",
     ...result.sqlite.map((change) => `- ${change.store}: ${change.changedRows} row(s)`),
@@ -1166,7 +1078,7 @@ function formatPurgeConfirmation(plan) {
     `cwd: ${colorize("dim", plan.target.cwd)}`,
     `updated: ${formatDate(plan.target.updatedAtMs)}`,
     "",
-    colorize("dim", "A backup will be created before deletion."),
+    colorize("dim", "This cannot be undone."),
     ""
   ].join("\n");
 }

package/package.json

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