feat: Add restore command and enhance UX with improved error handling (v0.5.1)

New features:
- kc restore command for recovering snapshots from trash
- Typo suggestions for unknown commands (edit distance algorithm)
- --no-header and --machine options for list command

Security improvements:
- Terminal escape sequence protection with input sanitization
- DoS protection in edit distance algorithm (length limits)
- Enhanced input validation with detailed error messages

UX enhancements:
- Detailed error messages with specific reasons and examples
- Similar ID suggestions when snapshots not found
- Parallel processing for restore operations (batched)
- Machine-readable TSV output format

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: tsutomu-n

README.ja.md

@@ -37,6 +37,9 @@ Kodama Claude は **人間の意思決定ログ** を外部に構造化して保
 curl -fsSL https://github.com/tsutomu-n/kodama-claude/releases/latest/download/install.sh | bash
 ```
 
+> 📌 **重要**: インストールやアップデート時、既存のスナップショットやデータは**完全に保持されます**。  
+> データは `~/.local/share/kodama-claude/` に保存され、バイナリ更新時には一切触れられません。
+
 **自動処理内容:**
 - 古いバージョン（v0.1.0、v0.2.0）を自動検出・削除
 - アーキテクチャに適したバイナリをダウンロード
@@ -172,6 +175,7 @@ kc list     # 保存済みスナップショットを一覧表示（v0.4.1+）
 # スナップショット管理（v0.5.0+）
 kc show     # スナップショットの詳細表示
 kc delete   # スナップショットの安全な削除（ゴミ箱機能付き）
+kc restore  # ゴミ箱から復元（v0.5.1+）
 kc search   # スナップショット全文検索
 
 # メンテナンス
@@ -388,6 +392,8 @@ kc delete --list-trash
 
 # ゴミ箱から復元
 kc delete --restore abc123
+# または復元専用コマンド（v0.5.1+）
+kc restore abc123
 
 # ゴミ箱を空にする
 kc delete --empty-trash
@@ -417,7 +423,7 @@ $ kc delete c4d56789  # 部分IDで指定
 ✅ スナップショット 'c4d56789...' をゴミ箱に移動しました
 
 # 3. 間違えて削除した場合は復元可能
-$ kc delete --restore c4d56789
+$ kc restore c4d56789
 ✅ スナップショット 'c4d56789...' をゴミ箱から復元しました
 
 # 4. 1週間以上前の作業用スナップショットを一括削除
@@ -791,6 +797,9 @@ A: 単一バイナリ配布、高速起動、開発体験が良いから。
 **Q: VS Code と統合できるか？**  
 A: エディタ非依存。どのエディタでも使える。
 
+**Q: インストール/アップデート時にスナップショットは削除されますか？**  
+A: いいえ。Kodama Claudeは設計上、インストールやアップデート時にユーザーデータに一切触れません。すべてのスナップショットは `~/.local/share/kodama-claude/` に安全に保存され、バイナリ更新の影響を受けません。データ削除には `kc uninstall --remove-all` の明示的なコマンドが必要です。
+
 **Q: 複数マシンでスナップショットを同期できるか？**  
 A: `~/.local/share/kodama-claude` を Git で管理するか、シンボリックリンクを使う。
 

README.md

@@ -20,6 +20,9 @@ Kodama stores **human decision logs** in structured format. When `/clear` erases
 curl -fsSL https://github.com/tsutomu-n/kodama-claude/releases/latest/download/install.sh | bash
 ```
 
+> 📌 **Important**: Your snapshots and data are **fully preserved** during installation or updates.  
+> Data stored in `~/.local/share/kodama-claude/` is never touched during binary updates.
+
 **What it does:**
 - Automatically detects and removes old versions (v0.1.0, v0.2.0)
 - Downloads correct binary for your architecture
@@ -109,6 +112,7 @@ kc list     # List saved snapshots (v0.4.1+)
 # Snapshot Management (v0.5.0+)
 kc show     # Display detailed snapshot information
 kc delete   # Safe snapshot deletion (with trash/restore)
+kc restore  # Restore from trash (v0.5.1+)
 kc search   # Full-text search across snapshots
 
 # Maintenance
@@ -643,6 +647,9 @@ A: `kc go` uses `claude -c -p "<context>"` to inject, then `claude --continue` t
 **Q: Why no token percentages?**  
 A: Claude doesn't reliably expose this. We use heuristic-based 4-value status (🟢/🟡/🔴/❓) instead.
 
+**Q: Are my snapshots deleted during installation/updates?**  
+A: No. Kodama Claude is designed to never touch user data during installation or updates. All snapshots are safely stored in `~/.local/share/kodama-claude/` and are unaffected by binary updates. Data deletion requires explicit commands like `kc uninstall --remove-all`.
+
 **Q: Why use snapshots instead of Git?**  
 A: Git and snapshots are complementary:
 

bin/kc.ts

@@ -116,6 +116,8 @@ program
   .option("-t, --tags <tags>", "Filter by tags (comma/space separated)")
   .option("--sort <field>", "Sort by: date (default), title, size", "date")
   .option("--reverse", "Reverse sort order")
+  .option("--no-header", "Omit header for script usage")
+  .option("--machine", "Machine-readable TSV output")
   .action(async (options) => {
     const { list } = await import("../src/commands/list");
     await list({
@@ -129,7 +131,9 @@ program
       thisWeek: options.thisWeek,
       tags: options.tags,
       sort: options.sort,
-      reverse: options.reverse
+      reverse: options.reverse,
+      noHeader: options.noHeader,
+      machine: options.machine
     });
   });
 
@@ -204,5 +208,82 @@ program
     });
   });
 
+// Restore command (restore from trash)
+program
+  .command("restore")
+  .description("Restore snapshots from trash")
+  .argument("<snapshot-ids...>", "Snapshot IDs to restore from trash")
+  .option("-v, --verbose", "Show detailed restoration information")
+  .option("--dry-run", "Show what would be restored without restoring")
+  .action(async (snapshotIds, options) => {
+    const { restore } = await import("../src/commands/restore");
+    await restore(snapshotIds, {
+      verbose: options.verbose,
+      dryRun: options.dryRun
+    });
+  });
+
+// Handle unknown commands with suggestions
+program.on('command:*', function (operands) {
+  const unknownCommand = String(operands[0] || '').slice(0, 50); // Limit length for DoS protection
+  const availableCommands = ['go', 'save', 'status', 'uninstall', 'restart', 'tags', 'resume', 'list', 'show', 'delete', 'search', 'restore'];
+  
+  // Calculate edit distance for suggestions with DoS protection
+  function editDistance(a: string, b: string): number {
+    // DoS protection: limit string lengths
+    const maxLen = 20;
+    a = a.slice(0, maxLen);
+    b = b.slice(0, maxLen);
+    
+    // Early return for same strings
+    if (a === b) return 0;
+    
+    // Early return if length difference is too large
+    if (Math.abs(a.length - b.length) > 3) return 999;
+    
+    const dp = Array(a.length + 1).fill(null).map(() => Array(b.length + 1).fill(0));
+    
+    for (let i = 0; i <= a.length; i++) dp[i][0] = i;
+    for (let j = 0; j <= b.length; j++) dp[0][j] = j;
+    
+    for (let i = 1; i <= a.length; i++) {
+      for (let j = 1; j <= b.length; j++) {
+        if (a[i - 1] === b[j - 1]) {
+          dp[i][j] = dp[i - 1][j - 1];
+        } else {
+          dp[i][j] = Math.min(
+            dp[i - 1][j] + 1,    // deletion
+            dp[i][j - 1] + 1,    // insertion
+            dp[i - 1][j - 1] + 1  // substitution
+          );
+        }
+      }
+    }
+    return dp[a.length][b.length];
+  }
+  
+  // Find similar commands (edit distance <= 2)
+  const suggestions = availableCommands
+    .map(cmd => ({ cmd, distance: editDistance(unknownCommand, cmd) }))
+    .filter(({ distance }) => distance <= 2)
+    .sort((a, b) => a.distance - b.distance)
+    .map(({ cmd }) => cmd)
+    .slice(0, 3);
+  
+  // Sanitize command name in error output
+  const { sanitizeForOutput } = require("../src/utils/sanitize");
+  console.error(`❌ Error: Unknown command '${sanitizeForOutput(unknownCommand)}'`);
+  
+  if (suggestions.length > 0) {
+    console.error("💡 Did you mean:");
+    suggestions.forEach(cmd => console.error(`   • kc ${cmd}`));
+  } else {
+    console.error("💡 Available commands: " + availableCommands.join(', '));
+  }
+  
+  console.error("\n📖 Use 'kc --help' to see all available commands");
+  process.exit(1);
+});
+
 // Parse and execute
 program.parse();

docs/en/getting-started.md

@@ -148,6 +148,9 @@ Copy and paste this one line:
 curl -fsSL https://github.com/tsutomu-n/kodama-claude/releases/latest/download/install.sh | bash
 ```
 
+> 📌 **Important**: Your snapshots and data are **fully preserved** during installation or updates.  
+> Data stored in `~/.local/share/kodama-claude/` is never touched during binary updates.
+
 What happens:
 1. Downloads the installer
 2. Gets the right version for your computer

docs/ja/getting-started.md

@@ -25,6 +25,9 @@
 curl -fsSL https://github.com/tsutomu-n/kodama-claude/releases/latest/download/install.sh | bash
 ```
 
+> 📌 **重要**: インストールや更新時、**スナップショットとデータは完全に保護されます**。  
+> `~/.local/share/kodama-claude/` に保存されたデータは、バイナリ更新時に一切触れられません。
+
 このコマンドは：
 - 古いバージョンを自動検出・削除
 - アーキテクチャに合ったバイナリをダウンロード

src/commands/delete.ts

@@ -174,7 +174,18 @@ async function findSnapshotsByIds(snapshotDir: string, snapshotIds: string[]): P
         inputId.includes('\\') ||
         inputId.length < 4 ||
         inputId.length > 100) {
-      throw new Error(`Invalid snapshot ID: ${inputId}. Must be 4-100 characters without path components.`);
+      let errorMsg = `Snapshot ID '${inputId}' is invalid.`;
+      if (inputId.length < 4) {
+        errorMsg += ` Reason: Too short (minimum 4 characters required for safety to prevent accidental matches).`;
+      }
+      if (inputId.includes('..') || inputId.includes('/') || inputId.includes('\\')) {
+        errorMsg += ` Reason: Contains path separators (security restriction).`;
+      }
+      if (inputId.length > 100) {
+        errorMsg += ` Reason: Too long (maximum 100 characters).`;
+      }
+      errorMsg += ` Examples of valid IDs: abc123, test-2024, feature_login`;
+      throw new Error(errorMsg);
     }
 
     // Find matching files
@@ -190,11 +201,25 @@ async function findSnapshotsByIds(snapshotDir: string, snapshotIds: string[]): P
     }
 
     if (matchingFiles.length === 0) {
-      throw new Error(`No snapshot found matching ID: ${inputId}`);
+      // Suggest similar IDs if any exist
+      const similarIds = allFiles
+        .map(f => f.replace(".json", ""))
+        .filter(id => id.toLowerCase().includes(inputId.toLowerCase()) || 
+                     inputId.toLowerCase().includes(id.toLowerCase().slice(0, 4)))
+        .slice(0, 3);
+      
+      let errorMsg = `No snapshot found matching ID: ${inputId}`;
+      if (similarIds.length > 0) {
+        errorMsg += `. Did you mean: ${similarIds.join(', ')}?`;
+      } else {
+        errorMsg += `. Use 'kc list' to see available snapshots.`;
+      }
+      throw new Error(errorMsg);
     }
 
     if (matchingFiles.length > 1) {
-      throw new Error(`Multiple snapshots match ID '${inputId}': ${matchingFiles.map(f => f.replace('.json', '')).join(', ')}`);
+      const matches = matchingFiles.map(f => f.replace('.json', '')).join(', ');
+      throw new Error(`Multiple snapshots match ID '${inputId}' (${matchingFiles.length} found): ${matches}. Use a more specific ID to avoid ambiguity. Example: try '${matchingFiles[0].replace('.json', '').slice(0, Math.min(8, matchingFiles[0].length - 5))}'`);
     }
 
     const fileName = matchingFiles[0];

src/commands/list.ts

@@ -21,6 +21,8 @@ interface ListOptions {
   tags?: string;
   sort?: string;
   reverse?: boolean;
+  noHeader?: boolean;
+  machine?: boolean; // Machine-readable output (TSV format)
 }
 
 export async function list(options: ListOptions = {}): Promise<void> {
@@ -36,7 +38,9 @@ export async function list(options: ListOptions = {}): Promise<void> {
     thisWeek = false,
     tags,
     sort = "date",
-    reverse = false 
+    reverse = false,
+    noHeader = false,
+    machine = false
   } = options;
 
   try {
@@ -164,8 +168,23 @@ export async function list(options: ListOptions = {}): Promise<void> {
     // Output results
     if (json) {
       console.log(JSON.stringify({ snapshots }, null, 2));
+    } else if (machine) {
+      // Machine-readable TSV format
+      if (!noHeader) {
+        console.log("ID\tTitle\tTimestamp\tStep\tTags");
+      }
+      
+      snapshots.forEach((snap) => {
+        const safeTitle = (snap.title || "Untitled").replace(/[\x00-\x1F\x7F\t]/g, " ");
+        const safeTags = snap.tags ? snap.tags.join(",") : "";
+        const safeStep = snap.step || "";
+        
+        console.log(`${snap.id}\t${safeTitle}\t${snap.timestamp}\t${safeStep}\t${safeTags}`);
+      });
     } else {
-      console.log(`📚 Recent Snapshots (showing ${snapshots.length}/${files.length}):\n`);
+      if (!noHeader) {
+        console.log(`📚 Recent Snapshots (showing ${snapshots.length}/${files.length}):\n`);
+      }
 
       snapshots.forEach((snap, index) => {
         const date = new Date(snap.timestamp);
@@ -174,30 +193,36 @@ export async function list(options: ListOptions = {}): Promise<void> {
 
         // Security: Escape potential control characters in title
         const safeTitle = (snap.title || "Untitled").replace(/[\x00-\x1F\x7F]/g, "");
-        console.log(`${index + 1}. ${safeTitle}`);
-        console.log(`   📅 ${formattedDate} (${timeAgo})`);
-        
-        if (snap.step) {
-          console.log(`   📊 Step: ${snap.step}`);
-        }
 
-        if (snap.tags && snap.tags.length > 0) {
-          // Security: Escape tags and limit display
-          const safeTags = snap.tags
-            .map(t => String(t).replace(/[\x00-\x1F\x7F]/g, ""))
-            .join(", ");
-          console.log(`   🏷️  Tags: ${safeTags}`);
-        }
-        
-        if (verbose) {
-          console.log(`   🆔 ID: ${snap.id}`);
-          console.log(`   📁 File: ${snap.file}`);
+        if (noHeader) {
+          // Simple format for --no-header: just ID and title
+          console.log(`${snap.id} ${safeTitle}`);
+        } else {
+          console.log(`${index + 1}. ${safeTitle}`);
+          console.log(`   📅 ${formattedDate} (${timeAgo})`);
+          
+          if (snap.step) {
+            console.log(`   📊 Step: ${snap.step}`);
+          }
+          
+          if (snap.tags && snap.tags.length > 0) {
+            // Security: Escape tags and limit display
+            const safeTags = snap.tags
+              .map(t => String(t).replace(/[\x00-\x1F\x7F]/g, ""))
+              .join(", ");
+            console.log(`   🏷️  Tags: ${safeTags}`);
+          }
+          
+          if (verbose) {
+            console.log(`   🆔 ID: ${snap.id}`);
+            console.log(`   📁 File: ${snap.file}`);
+          }
+          
+          console.log("");
         }
-        
-        console.log("");
       });
 
-      if (files.length > limit) {
+      if (files.length > limit && !noHeader) {
         console.log(`💡 Showing ${limit} of ${files.length} snapshots. Use --limit to see more.`);
       }
     }