opencode-manager 0.3.1 → 0.4.0

package/manage_opencode_projects.py

@@ -1,93 +1,98 @@
 #!/usr/bin/env python3
-"""Launch the OpenCode metadata TUI built with OpenTUI.
+"""Launch the OpenCode metadata manager (TUI or CLI).
 
-This wrapper keeps the previous entry point name but simply shells out to the
-new Bun-powered React TUI located under ``src/opencode-tui.tsx``. Use
-``manage_opencode_projects.py -- --help`` to see the TUI's runtime help text.
+This wrapper keeps the previous entry point name but shells out to the
+Bun-powered entrypoint at ``src/bin/opencode-manager.ts``. The routing logic
+detects CLI subcommands (projects, sessions, chat, tokens) and passes them
+directly, otherwise defaults to the TUI.
+
+Usage:
+  manage_opencode_projects.py                    # Launch TUI (default)
+  manage_opencode_projects.py projects list      # CLI: list projects
+  manage_opencode_projects.py sessions list      # CLI: list sessions
+  manage_opencode_projects.py -- --help          # Show TUI help
 """
 
 from __future__ import annotations
 
-import argparse
 import shutil
 import subprocess
 import sys
 from pathlib import Path
 from typing import Sequence
 
-DEFAULT_ROOT = Path.home() / ".local" / "share" / "opencode"
+# CLI subcommands that route to the CLI module instead of TUI
+CLI_SUBCOMMANDS = frozenset({"projects", "sessions", "chat", "tokens"})
+
 PROJECT_DIR = Path(__file__).resolve().parent
 
 
-def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description="Open the interactive OpenCode metadata manager TUI",
-        epilog=(
-            "Examples:\n"
-            "  manage_opencode_projects.py\n"
-            "    Launch the TUI using the default metadata root.\n\n"
-            "  manage_opencode_projects.py --root /tmp/opencode\n"
-            "    Launch the TUI against a different storage directory.\n\n"
-            "  manage_opencode_projects.py -- --help\n"
-            "    Show the TUI's built-in CLI help output.\n"
-        ),
-    )
-    parser.add_argument(
-        "--root",
-        type=Path,
-        default=DEFAULT_ROOT,
-        help="Metadata root to inspect (defaults to ~/.local/share/opencode)",
-    )
-    parser.add_argument(
-        "--bun",
-        type=Path,
-        default=None,
-        help="Optional path to the bun executable if it's not on PATH",
-    )
-    parser.add_argument(
-        "tui_args",
-        nargs=argparse.REMAINDER,
-        help=(
-            "Additional arguments forwarded to the TUI after '--'. For example: "
-            "manage_opencode_projects.py -- --help"
-        ),
-    )
-    return parser.parse_args(argv)
-
-
-def find_bun(explicit: Path | None) -> str:
-    if explicit:
-        return str(explicit)
+def find_bun(explicit_path: str | None = None) -> str:
+    """Locate bun executable, preferring explicit path if provided."""
+    if explicit_path:
+        return explicit_path
     bun_path = shutil.which("bun")
     if bun_path:
         return bun_path
-    raise SystemExit("bun executable not found. Please install Bun to run the TUI.")
-
-
-def launch_tui(root: Path, bun_exe: str, extra_args: Sequence[str]) -> int:
-    # Normalize passthrough args: drop leading "--" if present
-    if extra_args and len(extra_args) > 0 and extra_args[0] == "--":
-        extra_args = extra_args[1:]
-    cmd = [
-        bun_exe,
-        "run",
-        "tui",
-        "--",
-        "--root",
-        str(root.expanduser()),
-    ]
-    if extra_args:
-        cmd.extend(extra_args)
+    raise SystemExit("bun executable not found. Please install Bun.")
+
+
+def is_cli_subcommand(args: Sequence[str]) -> bool:
+    """Check if the first non-flag argument is a CLI subcommand."""
+    for arg in args:
+        if arg.startswith("-"):
+            # Skip flags like --bun, --root, etc.
+            continue
+        # First positional argument determines routing
+        return arg in CLI_SUBCOMMANDS
+    return False
+
 
+def run_entrypoint(bun_exe: str, args: Sequence[str]) -> int:
+    """Run the main entrypoint with given arguments.
+    
+    The TypeScript entrypoint handles all routing internally:
+    - CLI subcommands (projects, sessions, chat, tokens) → CLI module
+    - Everything else → TUI
+    """
+    # Normalize: drop leading "--" if present (legacy passthrough syntax)
+    args_list = list(args)
+    if args_list and args_list[0] == "--":
+        args_list = args_list[1:]
+    
+    cmd = [bun_exe, "src/bin/opencode-manager.ts"] + args_list
     process = subprocess.run(cmd, cwd=PROJECT_DIR)
     return process.returncode
 
 
 def main(argv: Sequence[str] | None = None) -> int:
-    args = parse_args(argv)
-    bun_exe = find_bun(args.bun)
-    extra_args = list(args.tui_args or [])
-    return launch_tui(args.root, bun_exe, extra_args)
+    """Main entry point.
+    
+    Parses minimal wrapper-level options (--bun) and forwards everything
+    else to the TypeScript entrypoint which handles TUI/CLI routing.
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+    
+    args = list(argv)
+    bun_exe_path: str | None = None
+    
+    # Extract --bun option if present (wrapper-level option only)
+    filtered_args: list[str] = []
+    i = 0
+    while i < len(args):
+        if args[i] == "--bun" and i + 1 < len(args):
+            bun_exe_path = args[i + 1]
+            i += 2
+        elif args[i].startswith("--bun="):
+            bun_exe_path = args[i].split("=", 1)[1]
+            i += 1
+        else:
+            filtered_args.append(args[i])
+            i += 1
+    
+    bun_exe = find_bun(bun_exe_path)
+    return run_entrypoint(bun_exe, filtered_args)
 
 
 if __name__ == "__main__":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-manager",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Terminal UI for inspecting OpenCode metadata stores.",
   "type": "module",
   "license": "MIT",
@@ -20,8 +20,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "tui": "bun src/opencode-tui.tsx",
-    "dev": "bun --watch src/opencode-tui.tsx",
+    "tui": "bun src/tui/index.tsx",
+    "dev": "bun --watch src/tui/index.tsx",
+    "test": "bun test",
     "typecheck": "bunx tsc --noEmit",
     "prepublishOnly": "bun run typecheck"
   },
@@ -45,6 +46,8 @@
   "dependencies": {
     "@opentui/core": "^0.1.44",
     "@opentui/react": "^0.1.44",
+    "commander": "^12.0.0",
+    "fast-fuzzy": "^1.12.0",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/src/bin/opencode-manager.ts

@@ -1,4 +1,134 @@
 #!/usr/bin/env bun
-// Bun-native CLI entry that simply boots the TUI module.
-// Keeping this file tiny lets `bun x opencode-manager` launch instantly without extra bundling.
-import "../opencode-tui"
+/**
+ * Main CLI entrypoint for opencode-manager.
+ *
+ * Routes between TUI and CLI modes based on provided subcommands:
+ * - No subcommand → shows help
+ * - "tui" subcommand → launches TUI
+ * - CLI subcommands (projects, sessions, chat, tokens) → launches CLI
+ *
+ * Uses dynamic imports to keep initial load fast and avoid loading
+ * unused modules.
+ */
+
+// Known CLI subcommands that should route to the CLI module
+const CLI_SUBCOMMANDS = new Set([
+  "projects",
+  "sessions",
+  "chat",
+  "tokens",
+])
+
+// Subcommands that explicitly request TUI
+const TUI_SUBCOMMANDS = new Set(["tui"])
+
+// Version from package.json
+const VERSION = "0.4.0"
+
+function printHelp(): void {
+  console.log(`opencode-manager v${VERSION}
+
+Inspect and manage OpenCode metadata stores via TUI or CLI.
+
+USAGE:
+  opencode-manager [command] [options]
+
+MODES:
+  tui                       Launch interactive TUI (terminal user interface)
+  <command>                 Run CLI command (see below)
+
+CLI COMMANDS:
+  projects list             List all projects
+  projects delete           Delete a project's metadata
+
+  sessions list             List sessions (optionally filter by project)
+  sessions delete           Delete a session's metadata
+  sessions rename           Rename a session
+  sessions move             Move a session to another project
+  sessions copy             Copy a session to another project
+
+  chat list                 List messages in a session
+  chat show                 Show a specific message
+  chat search               Search chat content across sessions
+
+  tokens session            Show token usage for a session
+  tokens project            Show token usage for a project
+  tokens global             Show global token usage
+
+OPTIONS:
+  --help, -h                Show this help
+  --version, -v             Show version
+
+EXAMPLES:
+  opencode-manager tui                          # Launch TUI
+  opencode-manager projects list --format json  # List projects as JSON
+  opencode-manager sessions list --project X    # List sessions for project
+  opencode-manager chat search --query "error"  # Search chat content
+
+For detailed help on any command:
+  opencode-manager <command> --help
+  opencode-manager <command> <subcommand> --help
+`)
+}
+
+function printVersion(): void {
+  console.log(VERSION)
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2)
+  const firstArg = args[0]
+
+  // Handle no args, --help, or -h → show help
+  if (!firstArg || firstArg === "--help" || firstArg === "-h") {
+    printHelp()
+    return
+  }
+
+  // Handle --version or -v
+  if (firstArg === "--version" || firstArg === "-v") {
+    printVersion()
+    return
+  }
+
+  // Determine routing based on first argument
+  const isCliSubcommand = CLI_SUBCOMMANDS.has(firstArg)
+  const isTuiSubcommand = TUI_SUBCOMMANDS.has(firstArg)
+
+  if (isCliSubcommand) {
+    // Route to CLI module (dynamically imported)
+    // Using string path to avoid TypeScript errors before CLI module exists
+    const cliModulePath = "../cli/index"
+    try {
+      const cliModule = await import(cliModulePath)
+      if (typeof cliModule.runCLI !== "function") {
+        throw new Error("CLI module missing runCLI export")
+      }
+      await cliModule.runCLI(args)
+    } catch (error) {
+      const errCode = (error as NodeJS.ErrnoException).code
+      const errMessage = (error as Error).message
+      if (errCode === "ERR_MODULE_NOT_FOUND" || errMessage.includes("Cannot find module")) {
+        console.error(`CLI module not yet implemented. Subcommand: ${firstArg}`)
+        console.error("Run without subcommand to launch TUI, or use --help for usage.")
+        process.exit(1)
+      }
+      throw error
+    }
+  } else if (isTuiSubcommand) {
+    // Explicit TUI request - strip "tui" subcommand so TUI args parser doesn't see it
+    const tuiArgs = args.slice(1)
+    const { bootstrap } = await import("../tui/index")
+    await bootstrap(tuiArgs)
+  } else {
+    // Unknown command
+    console.error(`Unknown command: ${firstArg}\n`)
+    printHelp()
+    process.exit(1)
+  }
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/src/cli/backup.ts

@@ -0,0 +1,324 @@
+/**
+ * CLI backup utilities module.
+ *
+ * Provides helpers for backing up files and directories before
+ * destructive operations like delete.
+ */
+
+import { promises as fs } from "node:fs"
+import { basename, dirname, join, relative, resolve } from "node:path"
+import { FileOperationError } from "./errors"
+
+// ========================
+// Types
+// ========================
+
+/**
+ * Options for backup operations.
+ */
+export interface BackupOptions {
+  /** Base directory for backups. Files are copied here with structure preserved. */
+  backupDir: string
+  /** Optional prefix for backup directory name (defaults to timestamp). */
+  prefix?: string
+  /** Whether to preserve the original directory structure relative to a root. */
+  preserveStructure?: boolean
+  /** Root directory for preserving structure (paths are relative to this). */
+  structureRoot?: string
+}
+
+/**
+ * Result of a backup operation.
+ */
+export interface BackupResult {
+  /** Source paths that were backed up. */
+  sources: string[]
+  /** Destination paths where backups were created. */
+  destinations: string[]
+  /** The backup directory used (may include timestamp subdirectory). */
+  backupDir: string
+  /** Any paths that failed to backup. */
+  failed: Array<{ path: string; error: string }>
+}
+
+// ========================
+// Helpers
+// ========================
+
+/**
+ * Generate a timestamp string for backup directory names.
+ *
+ * @returns ISO-like timestamp without colons (filesystem safe)
+ */
+export function generateBackupTimestamp(): string {
+  const now = new Date()
+  // Format: YYYY-MM-DD_HH-MM-SS
+  const year = now.getFullYear()
+  const month = String(now.getMonth() + 1).padStart(2, "0")
+  const day = String(now.getDate()).padStart(2, "0")
+  const hours = String(now.getHours()).padStart(2, "0")
+  const minutes = String(now.getMinutes()).padStart(2, "0")
+  const seconds = String(now.getSeconds()).padStart(2, "0")
+  return `${year}-${month}-${day}_${hours}-${minutes}-${seconds}`
+}
+
+/**
+ * Ensure a directory exists, creating it if necessary.
+ *
+ * @param dir - Directory path to ensure
+ */
+async function ensureDir(dir: string): Promise<void> {
+  await fs.mkdir(dir, { recursive: true })
+}
+
+/**
+ * Check if a path exists.
+ *
+ * @param path - Path to check
+ * @returns true if exists, false otherwise
+ */
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await fs.access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if a path is a directory.
+ *
+ * @param path - Path to check
+ * @returns true if directory, false otherwise
+ */
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(path)
+    return stat.isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Recursively copy a directory.
+ *
+ * @param src - Source directory
+ * @param dest - Destination directory
+ */
+async function copyDir(src: string, dest: string): Promise<void> {
+  await ensureDir(dest)
+  const entries = await fs.readdir(src, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name)
+    const destPath = join(dest, entry.name)
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath)
+    } else {
+      await fs.copyFile(srcPath, destPath)
+    }
+  }
+}
+
+/**
+ * Copy a file or directory to a destination.
+ *
+ * @param src - Source path (file or directory)
+ * @param dest - Destination path
+ */
+async function copyPath(src: string, dest: string): Promise<void> {
+  if (await isDirectory(src)) {
+    await copyDir(src, dest)
+  } else {
+    // Ensure parent directory exists
+    await ensureDir(dirname(dest))
+    await fs.copyFile(src, dest)
+  }
+}
+
+// ========================
+// Main Backup Functions
+// ========================
+
+/**
+ * Copy files to a backup directory before deletion.
+ *
+ * Creates a timestamped subdirectory within backupDir to store the backups.
+ * Preserves directory structure relative to structureRoot if specified.
+ *
+ * @param paths - Array of file/directory paths to backup
+ * @param options - Backup options
+ * @returns BackupResult with details of the operation
+ *
+ * @example
+ * ```ts
+ * // Simple backup
+ * const result = await copyToBackupDir(
+ *   ["/path/to/project.json", "/path/to/session/data"],
+ *   { backupDir: "/backups" }
+ * )
+ * // Files are copied to /backups/2024-01-15_12-30-45/...
+ *
+ * // Preserve structure
+ * const result = await copyToBackupDir(
+ *   ["/data/storage/project/abc.json"],
+ *   {
+ *     backupDir: "/backups",
+ *     preserveStructure: true,
+ *     structureRoot: "/data"
+ *   }
+ * )
+ * // File is copied to /backups/2024-01-15_12-30-45/storage/project/abc.json
+ * ```
+ */
+export async function copyToBackupDir(
+  paths: string[],
+  options: BackupOptions
+): Promise<BackupResult> {
+  const { backupDir, prefix, preserveStructure, structureRoot } = options
+
+  // Validate backup directory
+  const resolvedBackupDir = resolve(backupDir)
+
+  // Create timestamped subdirectory
+  const timestamp = generateBackupTimestamp()
+  const backupSubdir = prefix
+    ? `${prefix}_${timestamp}`
+    : timestamp
+  const targetBackupDir = join(resolvedBackupDir, backupSubdir)
+
+  const result: BackupResult = {
+    sources: [],
+    destinations: [],
+    backupDir: targetBackupDir,
+    failed: [],
+  }
+
+  // If no paths, return early
+  if (paths.length === 0) {
+    return result
+  }
+
+  // Ensure backup directory exists
+  try {
+    await ensureDir(targetBackupDir)
+  } catch (error) {
+    throw new FileOperationError(
+      `Failed to create backup directory: ${targetBackupDir}`,
+      "backup"
+    )
+  }
+
+  // Copy each path
+  for (const srcPath of paths) {
+    const resolvedSrc = resolve(srcPath)
+
+    // Check if source exists
+    if (!(await pathExists(resolvedSrc))) {
+      result.failed.push({
+        path: resolvedSrc,
+        error: "Source path does not exist",
+      })
+      continue
+    }
+
+    // Determine destination path
+    let destPath: string
+    if (preserveStructure && structureRoot) {
+      // Preserve directory structure relative to root
+      const relativePath = relative(resolve(structureRoot), resolvedSrc)
+      if (relativePath.startsWith("..")) {
+        // Path is outside structureRoot, use basename
+        destPath = join(targetBackupDir, basename(resolvedSrc))
+      } else {
+        destPath = join(targetBackupDir, relativePath)
+      }
+    } else {
+      // Just use the basename
+      destPath = join(targetBackupDir, basename(resolvedSrc))
+    }
+
+    // Copy the file/directory
+    try {
+      await copyPath(resolvedSrc, destPath)
+      result.sources.push(resolvedSrc)
+      result.destinations.push(destPath)
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      result.failed.push({
+        path: resolvedSrc,
+        error: errorMessage,
+      })
+    }
+  }
+
+  return result
+}
+
+/**
+ * Get the paths that would be backed up (for dry-run display).
+ *
+ * @param paths - Source paths to backup
+ * @param options - Backup options
+ * @returns Object with source and computed destination paths
+ */
+export function previewBackupPaths(
+  paths: string[],
+  options: BackupOptions
+): { sources: string[]; destinations: string[]; backupDir: string } {
+  const { backupDir, prefix, preserveStructure, structureRoot } = options
+
+  const resolvedBackupDir = resolve(backupDir)
+  const timestamp = generateBackupTimestamp()
+  const backupSubdir = prefix ? `${prefix}_${timestamp}` : timestamp
+  const targetBackupDir = join(resolvedBackupDir, backupSubdir)
+
+  const sources: string[] = []
+  const destinations: string[] = []
+
+  for (const srcPath of paths) {
+    const resolvedSrc = resolve(srcPath)
+    sources.push(resolvedSrc)
+
+    let destPath: string
+    if (preserveStructure && structureRoot) {
+      const relativePath = relative(resolve(structureRoot), resolvedSrc)
+      if (relativePath.startsWith("..")) {
+        destPath = join(targetBackupDir, basename(resolvedSrc))
+      } else {
+        destPath = join(targetBackupDir, relativePath)
+      }
+    } else {
+      destPath = join(targetBackupDir, basename(resolvedSrc))
+    }
+    destinations.push(destPath)
+  }
+
+  return { sources, destinations, backupDir: targetBackupDir }
+}
+
+/**
+ * Format backup result for display.
+ *
+ * @param result - Backup result to format
+ * @returns Human-readable summary string
+ */
+export function formatBackupResult(result: BackupResult): string {
+  const lines: string[] = []
+
+  if (result.sources.length > 0) {
+    lines.push(`Backed up ${result.sources.length} item(s) to: ${result.backupDir}`)
+  }
+
+  if (result.failed.length > 0) {
+    lines.push(`Failed to backup ${result.failed.length} item(s):`)
+    for (const { path, error } of result.failed) {
+      lines.push(`  ${path}: ${error}`)
+    }
+  }
+
+  return lines.join("\n")
+}