ai-dev-maintenance 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ai-dev-maintenance contributors
+
+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.ja.md

@@ -0,0 +1,94 @@
+# ai-dev-maintenance
+
+AI開発ツールのローカル状態で増えたディスク使用量を、安全に診断・回収するためのCLIです。
+
+v1はmacOS専用です。CodexのSQLiteログDBに対するWAL回収を中心に、セッション履歴を触らないことを最優先にしています。
+
+`doctor` は、ローカルに伏せ字済みの診断レポートを書くだけです。`fix --safe --yes` は、Codexログデータを含む可能性がある非公開のローカルバックアップを作成してから、SQLiteのWAL領域を整理します。ログ本文の表示、アップロード、ログ削除、セッション履歴の書き換え、trigger追加、設定変更は行いません。
+
+## 使い方
+
+```bash
+npm exec --ignore-scripts ai-dev-maintenance@0.1.0 -- doctor --show-paths
+```
+
+2. 最新レポートを確認:
+
+```bash
+npm exec --ignore-scripts ai-dev-maintenance@0.1.0 -- report --latest
+```
+
+3. 出力で安全と表示された場合だけ実行:
+
+```bash
+npm exec --ignore-scripts ai-dev-maintenance@0.1.0 -- fix --safe --yes
+```
+
+`npm exec` はCLI起動前にnpm registryからpackageを取得する場合があります。CLI起動後、このツールはネットワーク通信を行いません。
+
+最初は `doctor` だけを実行してください。`doctor` は `<home>/.ai-dev-maintenance/reports` に伏せ字済みレポートを書き込みます。レポート確認後に `fix --safe --yes` を実行します。
+
+## コマンド
+
+```bash
+ai-dev-maintenance doctor [--json] [--show-paths]
+ai-dev-maintenance fix --safe --yes
+ai-dev-maintenance report --latest [--show-paths]
+```
+
+## 安全方針
+
+- `doctor` は原本DBをSQLite接続として開きません。
+- `doctor` はツール用データディレクトリに伏せ字済みローカルレポートを書き込みます。
+- v1の `doctor` はprivate log DB bytesを複製しないため、SQLite本文検査をスキップします。
+- `fix --safe --yes` はデフォルトのCodex `logs_2.sqlite` とSQLite補助ファイルだけを対象にします。
+- Codex processが動いている場合、対象DBを開いているprocessがある場合、open-handle確認ができない場合はblockします。
+- SQLite起動には `file:` URI modeを使い、plain database pathを使いません。
+- session、Claude data、Codex config、DB rows、schema、triggerは変更しません。
+- レポートはデフォルトで伏せ字済みです。
+
+## `fix --safe` が行うこと
+
+できること:
+
+- 検証済みbackupを作る
+- Codex log DBのWAL checkpoint/truncateを行う
+- WAL bytesのbefore/afterを表示する
+
+やらないこと:
+
+- log削除
+- full `VACUUM`
+- DBファイル置換
+- trigger追加
+- session履歴編集
+- backup自動復元
+
+伏せ字済みレポートには、対象カテゴリ、存在有無、ファイルサイズ、コマンド状態、回収量などの高レベル情報だけを残します。ローカルマシン固有の識別子、コマンドの生出力、絶対パスは保存・表示しません。`--show-paths` でも伏せ字済みパスだけを表示します。
+
+## 緊急時 / 上級者向け
+
+バックアップ検証だけを行うコマンドがあります。
+
+```bash
+ai-dev-maintenance restore validate --backup <path>
+```
+
+これは検証だけです。復旧手順を理解し、AI開発ツールをすべて閉じている場合を除き、DBファイルを移動・コピー・置換しないでください。
+
+## 開発
+
+```bash
+corepack pnpm install
+corepack pnpm run verify
+corepack pnpm run build
+```
+
+runtime dependencyとinstall-time package lifecycle scriptはありません。
+
+## ローカルデータ
+
+伏せ字済み診断レポートは `<home>/.ai-dev-maintenance/reports` に保存されます。
+このレポートは小さく、Codexのセッション、他AIツールのセッション、バックアップは含みません。
+
+v1では手動ワイルドカード削除の手順を公開しません。将来cleanupコマンドを追加する場合は、削除前にapp data directoryの安全性を検証し、ツール所有のレポートファイルだけを対象にします。

package/README.md

@@ -0,0 +1,124 @@
+# ai-dev-maintenance
+
+Safely diagnose and reclaim local disk usage created by AI coding tool state.
+
+The first release is intentionally small. It focuses on macOS, redacted reports, and safe reclaim of a Codex SQLite log database WAL file.
+
+`doctor` only writes a local redacted report. `fix --safe --yes` creates a private local backup that may contain Codex log data, then truncates SQLite WAL storage. It does not upload data, print log contents, delete logs, rewrite session history, install database triggers, or change tool configuration.
+
+## Install-Free Usage
+
+1. Diagnose only:
+
+```bash
+npm exec --ignore-scripts ai-dev-maintenance@0.1.0 -- doctor --show-paths
+```
+
+2. Review the latest report:
+
+```bash
+npm exec --ignore-scripts ai-dev-maintenance@0.1.0 -- report --latest
+```
+
+3. Only if the output says it is safe:
+
+```bash
+npm exec --ignore-scripts ai-dev-maintenance@0.1.0 -- fix --safe --yes
+```
+
+Use the pinned version above when you want repeatable behavior. The npm `latest` tag is convenient after you trust the release channel.
+
+`npm exec` may download the package from the npm registry before the CLI starts. After the CLI starts, this tool performs no network calls.
+
+Start with `doctor`. It writes a redacted local report under `<home>/.ai-dev-maintenance/reports`. Review that report before running `fix --safe --yes`.
+
+## Commands
+
+```bash
+ai-dev-maintenance doctor [--json] [--show-paths]
+ai-dev-maintenance fix --safe --yes
+ai-dev-maintenance report --latest [--show-paths]
+```
+
+## Safety Guarantees
+
+- `doctor` does not open the source database as a SQLite connection.
+- `doctor` writes a redacted local report under the tool data directory.
+- `doctor` skips SQLite content inspection in v1 to avoid copying private log database bytes.
+- `fix --safe --yes` targets only the default Codex `logs_2.sqlite` database and its SQLite sidecar files.
+- `fix --safe` blocks when a known Codex process is running, any process has the target database open, or open-handle checks are unavailable.
+- SQLite commands use safe SQLite file URLs instead of passing plain database paths.
+- The tool does not edit sessions, Claude data, Codex config, database rows, schema, or triggers.
+- Reports are redacted by default.
+
+## What `fix --safe` Can Change
+
+It can:
+
+- create a verified private local backup under the tool data directory;
+- run WAL checkpoint/truncate on the Codex log database;
+- report WAL bytes before and after cleanup.
+
+It cannot:
+
+- delete logs;
+- shrink the main database with full `VACUUM`;
+- replace the database file;
+- install triggers;
+- edit session history;
+- restore a backup automatically.
+
+## Expected Output
+
+The saved report includes:
+
+- `status`
+- `blockedReasons`
+- `beforeWalBytes`
+- `afterWalBytes`
+- `reclaimedBytes`
+- `nextSafeAction`
+
+See `examples/sample-report.json` for a redacted example.
+
+Redacted reports keep high-level target categories, existence flags, file sizes, command status, and reclaim metrics. They remove raw local-machine identifiers, raw command output, and absolute local paths. `--show-paths` prints only redacted report paths.
+
+Human-readable output includes:
+
+- whether it is safe to run `fix --safe`;
+- what changed in the current command;
+- where the redacted report was saved;
+- the command to review the latest report.
+
+## Emergency / Advanced Only
+
+Backup validation is available for recovery planning:
+
+```bash
+ai-dev-maintenance restore validate --backup <path>
+```
+
+This only validates a backup. Do not move, copy, or replace database files unless you are following a recovery guide and all AI coding tools are closed.
+
+## Platform Support
+
+v1 supports macOS only. Other platforms exit before touching macOS-specific paths.
+
+## Development
+
+```bash
+corepack pnpm install
+corepack pnpm run verify
+corepack pnpm run build
+```
+
+The package has no runtime dependencies and no install-time package lifecycle scripts.
+
+Before npm publishing, set real `repository`, `bugs`, and `homepage` metadata in `package.json`. Local pre-public CI can use `release:check:prepublic`, but `prepublishOnly` intentionally fails until real public repository metadata exists.
+
+## Local Data
+
+Redacted maintenance reports are stored under `<home>/.ai-dev-maintenance/reports`.
+They are intentionally small and do not contain Codex sessions, other AI tool sessions, or backups.
+
+v1 does not publish a manual wildcard cleanup recipe. A future cleanup command should validate the app data directory before deleting any tool-owned report files.

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes target the latest published minor version.
+
+## Reporting a Vulnerability
+
+Please open a private security advisory in the public repository once available. If private advisories are not enabled yet, do not open a public issue with sensitive material; use a minimal public issue asking for a private contact path.
+
+Do not include private session content, logs, tokens, browser data, or machine-specific absolute paths in reports. Use redacted output whenever possible.
+
+We aim to acknowledge actionable vulnerability reports within 7 days.
+
+## Data Handling
+
+The CLI is designed to operate locally. It does not upload diagnostic data. Reports are redacted by default. v1 has no unredacted report output mode.

package/dist/cli.d.ts

@@ -0,0 +1,40 @@
+type ReportStatus = 'ok' | 'partial' | 'blocked' | 'unsupported' | 'error';
+type MaintenanceReport = {
+    schemaVersion: 1;
+    toolVersion: string;
+    generatedAt: string;
+    command: string;
+    status: ReportStatus;
+    redacted: true;
+    target: {
+        kind: 'default-codex-log-db' | 'unknown';
+        pathCategory: string;
+    };
+    findings: Record<string, unknown>;
+    metrics: Record<string, unknown>;
+    blockedReasons: string[];
+    nextSafeAction?: string;
+};
+
+declare function runDoctor(options?: {
+    json?: boolean;
+    showPaths?: boolean;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    report: MaintenanceReport;
+    reportPath?: string;
+}>;
+
+type CliResult = {
+    exitCode: number;
+    output: string;
+};
+declare function runCli(argv?: string[]): Promise<CliResult>;
+declare function renderReport(report: Awaited<ReturnType<typeof runDoctor>>['report'], reportPath?: string, showPaths?: boolean): string;
+
+declare function fixSafeConfirmationError(args: string[]): string | undefined;
+declare function isDirectCliInvocation(moduleUrl: string, argv1: string | undefined): boolean;
+declare function formatCliError(error: unknown): string;
+
+export { fixSafeConfirmationError, formatCliError, isDirectCliInvocation, renderReport, runCli };