@liuyoumi/codex-history 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.0 - 2026-05-27
+
+Initial release candidate.
+
+### Added
+
+- `doctor` command for local Codex data model checks.
+- `list` command for local conversation discovery.
+- `list --grep` filtering for displayed title, id, and cwd matching.
+- `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.
+- SQLite cleanup for supported Codex stores.
+- JSON and JSONL state cleanup for supported Codex files.
+- Rollout jsonl and shell snapshot deletion.
+- WAL checkpointing after SQLite mutation.
+- Post-purge verification with non-zero exit on remaining supported references.
+- Fixture-based tests that do not read or modify a real `~/.codex`.
+
+### Notes
+
+- v0.1.0 is macOS-first.
+- Server-side deletion is not supported or claimed.
+- Physical secure erase from SSDs, APFS snapshots, or Time Machine backups is not supported.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liuyoumi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# codex-history
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+A small CLI for finding and removing local Codex conversation history.
+
+`codex-history` works on local Codex data files on your machine. It lists conversations using the same short titles shown by Codex when available, lets you narrow the list with `--grep`, and deletes one resolved conversation only after confirmation.
+
+## Install
+
+```bash
+npm install -g @liuyoumi/codex-history
+```
+
+Or run it without installing:
+
+```bash
+npx @liuyoumi/codex-history doctor
+```
+
+## Supported Platforms
+
+- macOS: verified for v0.1
+- Windows/Linux: not verified yet
+
+## Quick Start
+
+```bash
+codex-history doctor
+codex-history list
+codex-history list --grep "Astro"
+codex-history purge 019e6885
+```
+
+`purge` prints the resolved conversation and asks you to type the standard short id before it deletes anything:
+
+```text
+About to purge this local Codex conversation:
+
+title: Implement Astro blog visual audit
+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.
+Type 019e6885 to confirm:
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `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. |
+
+### `doctor`
+
+Check whether the local Codex data layout is supported by this version.
+
+```bash
+codex-history doctor
+```
+
+Run this first after installing, or after a Codex update. If the local data layout is not supported, destructive commands fail closed instead of guessing how to delete.
+
+### `list`
+
+List local Codex conversations.
+
+```bash
+codex-history list
+codex-history list --grep "Astro"
+codex-history list --limit 20
+codex-history list --pretty=medium
+codex-history list --pretty=full
+```
+
+Default output is one line per conversation:
+
+```text
+019e6885  Implement Astro blog visual audit
+019e6874  Review Astro blog visual plan
+```
+
+`--grep` filters by displayed title, thread id, and cwd. It does not search or print prompt bodies.
+
+Use the short id shown by `list`, or paste a full thread id, when running `purge`.
+
+By default, `list` shows non-archived conversations. Use `--archived` for archived conversations only, or `--all` for both archived and non-archived conversations.
+
+Wrap grep text in quotes when it contains spaces:
+
+```bash
+codex-history list --grep "Astro blog"
+```
+
+`--pretty` formats:
+
+- `oneline`: short id and title
+- `medium`: full id, updated time, and cwd
+- `full`: `medium` plus created time, archive state, and rollout path
+
+When `list` runs in an interactive terminal without `--limit`, output is sent through the system pager. Piped or redirected output skips the pager automatically.
+
+### `purge`
+
+Remove one local Codex conversation by full id or unique short id prefix.
+
+```bash
+codex-history purge 019e6885
+```
+
+For scripts or non-interactive shells, use `--force`:
+
+```bash
+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.
+
+## Options
+
+```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.
+- Color is enabled only in interactive terminals and respects `NO_COLOR`.
+
+## Safety
+
+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
+
+This tool only changes local Codex data. It does not delete server-side OpenAI/Codex records, OS backups, terminal scrollback, crash reports, or user-created transcript copies.
+
+## Q&A
+
+### Does this delete server-side Codex data?
+
+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.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,173 @@
+# codex-history
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+一个用来查找并删除本地 Codex 对话历史的小型命令行工具。
+
+`codex-history` 只处理你机器上的本地 Codex 数据。它会尽量使用 Codex 对话列表里显示的短标题，支持用 `--grep` 缩小范围，并且只会在你确认目标后删除一条明确解析出来的对话。
+
+## 安装
+
+```bash
+npm install -g @liuyoumi/codex-history
+```
+
+也可以不安装直接运行：
+
+```bash
+npx @liuyoumi/codex-history doctor
+```
+
+## 支持平台
+
+- macOS：v0.1 已验证
+- Windows/Linux：暂未验证
+
+## 快速开始
+
+```bash
+codex-history doctor
+codex-history list
+codex-history list --grep "Astro"
+codex-history purge 019e6885
+```
+
+`purge` 会先展示解析到的对话信息，并要求你输入标准短 id，确认后才会删除：
+
+```text
+About to purge this local Codex conversation:
+
+title: 实施 Astro 博客视觉审计工具
+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.
+Type 019e6885 to confirm:
+```
+
+## 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `codex-history doctor` | 检查当前本地 Codex 数据结构是否受支持。 |
+| `codex-history list` | 列出本地对话。 |
+| `codex-history list --grep <keyword>` | 按标题、id 或 cwd 过滤对话。 |
+| `codex-history purge <id>` | 确认后删除一条解析到的本地对话。 |
+
+### `doctor`
+
+检查当前本地 Codex 数据结构是否被这个版本支持。
+
+```bash
+codex-history doctor
+```
+
+建议安装后先跑一次；Codex 更新后也可以再跑一次。如果当前数据结构不受支持，删除命令会拒绝执行，而不是猜测应该怎么删。
+
+### `list`
+
+列出本地 Codex 对话。
+
+```bash
+codex-history list
+codex-history list --grep "Astro"
+codex-history list --limit 20
+codex-history list --pretty=medium
+codex-history list --pretty=full
+```
+
+默认是一行一条：
+
+```text
+019e6885  实施 Astro 博客视觉审计工具
+019e6874  评审 Astro 博客视觉方案
+```
+
+`--grep` 会按显示标题、线程 id、cwd 过滤。它不会搜索或输出对话正文。
+
+执行 `purge` 时，可以使用 `list` 里显示的短 id，也可以粘贴完整 thread id。
+
+默认情况下，`list` 只显示未归档对话。使用 `--archived` 只看已归档对话，使用 `--all` 同时查看已归档和未归档对话。
+
+如果 grep 关键词里有空格，请加引号：
+
+```bash
+codex-history list --grep "Astro 博客"
+```
+
+`--pretty` 支持：
+
+- `oneline`：短 id 和标题
+- `medium`：完整 id、更新时间、cwd
+- `full`：在 `medium` 基础上增加创建时间、归档状态、rollout 路径
+
+在交互式终端里，如果 `list` 没有加 `--limit`，输出会进入系统分页器。管道或重定向输出会自动跳过分页器。
+
+### `purge`
+
+通过完整 id 或唯一短 id 前缀删除一条本地 Codex 对话。
+
+```bash
+codex-history purge 019e6885
+```
+
+脚本或非交互环境可以使用 `--force`：
+
+```bash
+codex-history purge 019e6885 --force
+```
+
+`--force` 只跳过交互式短 id 确认，不会跳过数据结构校验、强制备份、active thread 保护和删除后的验证。
+
+## 选项
+
+```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`，因为交互确认只适合文本模式。
+- 颜色只会在交互式终端中启用，并遵守 `NO_COLOR`。
+
+## 安全机制
+
+删除前，`codex-history` 会：
+
+- 校验当前 Codex 本地数据结构是否受支持
+- 将目标解析到唯一一条对话
+- 在可检测时拒绝删除当前 active thread
+- 在 `~/.codex-history/backups` 下创建强制备份
+- 从受支持的本地 Codex 数据中移除已知引用
+- 删除后扫描受支持的数据存储，确认目标引用已经移除
+
+这个工具只处理本地 Codex 数据。它不会删除 OpenAI/Codex 服务端记录、系统备份、终端滚动历史、崩溃报告，或你手动保存过的对话副本。
+
+## Q&A
+
+### 会删除 Codex 服务端数据吗？
+
+不会。它只修改你机器上受支持的本地文件。
+
+### 备份在哪里？
+
+备份会写入 `~/.codex-history/backups`。
+
+### 删除后还能恢复吗？
+
+工具会在删除前创建备份，但 v0.1 还没有自动恢复命令。请把 `purge` 当作破坏性操作对待。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## 许可证
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node