opencode-manager 0.3.1 → 0.4.0

package/src/cli/errors.ts

@@ -0,0 +1,259 @@
+/**
+ * CLI error handling module.
+ *
+ * Provides standardized error classes and exit helpers for consistent
+ * error handling across all CLI commands.
+ *
+ * Exit codes:
+ * - 0: Success
+ * - 1: General error (unspecified)
+ * - 2: Usage error (e.g., missing --yes for destructive operations)
+ * - 3: Missing resource (e.g., invalid project/session ID)
+ * - 4: File operation failure (e.g., backup failed, delete failed)
+ */
+
+import { formatErrorOutput, type OutputFormat } from "./output"
+
+// ========================
+// Exit Codes
+// ========================
+
+/**
+ * Standardized CLI exit codes.
+ */
+export const ExitCode = {
+  /** Success */
+  SUCCESS: 0,
+  /** General error (unspecified) */
+  ERROR: 1,
+  /** Usage error (e.g., missing --yes for destructive operations) */
+  USAGE_ERROR: 2,
+  /** Missing resource (e.g., invalid project/session ID) */
+  NOT_FOUND: 3,
+  /** File operation failure (e.g., backup failed, delete failed) */
+  FILE_ERROR: 4,
+} as const
+
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode]
+
+// ========================
+// Error Classes
+// ========================
+
+/**
+ * Base class for CLI errors with exit codes.
+ */
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public readonly exitCode: ExitCodeValue = ExitCode.ERROR
+  ) {
+    super(message)
+    this.name = "CLIError"
+  }
+}
+
+/**
+ * Usage error (exit code 2).
+ * Thrown when CLI usage is incorrect, such as missing required confirmation.
+ */
+export class UsageError extends CLIError {
+  constructor(message: string) {
+    super(message, ExitCode.USAGE_ERROR)
+    this.name = "UsageError"
+  }
+}
+
+/**
+ * Not found error (exit code 3).
+ * Thrown when a requested resource (project, session, message) doesn't exist.
+ */
+export class NotFoundError extends CLIError {
+  constructor(
+    message: string,
+    public readonly resourceType?: "project" | "session" | "message"
+  ) {
+    super(message, ExitCode.NOT_FOUND)
+    this.name = "NotFoundError"
+  }
+}
+
+/**
+ * File operation error (exit code 4).
+ * Thrown when a file system operation fails (backup, delete, copy, move).
+ */
+export class FileOperationError extends CLIError {
+  constructor(
+    message: string,
+    public readonly operation?: "backup" | "delete" | "copy" | "move" | "read" | "write"
+  ) {
+    super(message, ExitCode.FILE_ERROR)
+    this.name = "FileOperationError"
+  }
+}
+
+// ========================
+// Exit Helpers
+// ========================
+
+/**
+ * Exit the process with a formatted error message.
+ *
+ * @param error - Error message or Error object
+ * @param exitCode - Exit code (defaults to 1)
+ * @param format - Output format for error message
+ */
+export function exitWithError(
+  error: string | Error,
+  exitCode: ExitCodeValue = ExitCode.ERROR,
+  format: OutputFormat = "table"
+): never {
+  console.error(formatErrorOutput(error, format))
+  process.exit(exitCode)
+}
+
+/**
+ * Exit the process with a CLIError, using its exit code.
+ *
+ * @param error - CLIError instance
+ * @param format - Output format for error message
+ */
+export function exitWithCLIError(
+  error: CLIError,
+  format: OutputFormat = "table"
+): never {
+  console.error(formatErrorOutput(error, format))
+  process.exit(error.exitCode)
+}
+
+/**
+ * Exit with a usage error (exit code 2).
+ *
+ * @param message - Error message
+ * @param format - Output format
+ */
+export function exitUsageError(
+  message: string,
+  format: OutputFormat = "table"
+): never {
+  exitWithError(message, ExitCode.USAGE_ERROR, format)
+}
+
+/**
+ * Exit with a not found error (exit code 3).
+ *
+ * @param message - Error message
+ * @param format - Output format
+ */
+export function exitNotFound(
+  message: string,
+  format: OutputFormat = "table"
+): never {
+  exitWithError(message, ExitCode.NOT_FOUND, format)
+}
+
+/**
+ * Exit with a file operation error (exit code 4).
+ *
+ * @param message - Error message
+ * @param format - Output format
+ */
+export function exitFileError(
+  message: string,
+  format: OutputFormat = "table"
+): never {
+  exitWithError(message, ExitCode.FILE_ERROR, format)
+}
+
+// ========================
+// Error Handling Utilities
+// ========================
+
+/**
+ * Handle an error by exiting with the appropriate code.
+ * Recognizes CLIError subclasses and uses their exit codes.
+ *
+ * @param error - Error to handle
+ * @param format - Output format
+ */
+export function handleError(
+  error: unknown,
+  format: OutputFormat = "table"
+): never {
+  if (error instanceof CLIError) {
+    exitWithCLIError(error, format)
+  }
+
+  if (error instanceof Error) {
+    exitWithError(error.message, ExitCode.ERROR, format)
+  }
+
+  exitWithError(String(error), ExitCode.ERROR, format)
+}
+
+/**
+ * Wrap an async function to catch errors and exit appropriately.
+ * Use this to wrap command handlers.
+ *
+ * @param fn - Async function to wrap
+ * @param format - Output format for errors
+ * @returns Wrapped function that handles errors
+ */
+export function withErrorHandling<T extends unknown[]>(
+  fn: (...args: T) => Promise<void>,
+  format: OutputFormat = "table"
+): (...args: T) => Promise<void> {
+  return async (...args: T) => {
+    try {
+      await fn(...args)
+    } catch (error) {
+      handleError(error, format)
+    }
+  }
+}
+
+// ========================
+// Validation Helpers
+// ========================
+
+/**
+ * Require confirmation for destructive operations.
+ * Throws UsageError if --yes flag is not provided.
+ *
+ * @param yes - Whether --yes flag was provided
+ * @param operation - Description of the operation for error message
+ */
+export function requireConfirmation(yes: boolean, operation: string): void {
+  if (!yes) {
+    throw new UsageError(
+      `${operation} requires --yes flag to confirm. Use --dry-run to preview changes.`
+    )
+  }
+}
+
+/**
+ * Throw NotFoundError for a project.
+ *
+ * @param projectId - The project ID that wasn't found
+ */
+export function projectNotFound(projectId: string): never {
+  throw new NotFoundError(`Project not found: ${projectId}`, "project")
+}
+
+/**
+ * Throw NotFoundError for a session.
+ *
+ * @param sessionId - The session ID that wasn't found
+ */
+export function sessionNotFound(sessionId: string): never {
+  throw new NotFoundError(`Session not found: ${sessionId}`, "session")
+}
+
+/**
+ * Throw NotFoundError for a message.
+ *
+ * @param messageId - The message ID that wasn't found
+ */
+export function messageNotFound(messageId: string): never {
+  throw new NotFoundError(`Message not found: ${messageId}`, "message")
+}

package/src/cli/formatters/json.ts

@@ -0,0 +1,184 @@
+/**
+ * JSON output formatter for CLI commands.
+ *
+ * Provides standard JSON output helpers for formatting single records,
+ * arrays, and structured responses with consistent serialization.
+ */
+
+/**
+ * Options for JSON formatting.
+ */
+export interface JsonFormatOptions {
+  /** Pretty-print with indentation (default: true for TTY, false otherwise) */
+  pretty?: boolean
+  /** Indentation level for pretty printing (default: 2) */
+  indent?: number
+}
+
+/**
+ * Standard JSON response envelope for CLI output.
+ */
+export interface JsonResponse<T> {
+  /** Whether the operation was successful */
+  ok: boolean
+  /** The data payload */
+  data?: T
+  /** Error message if operation failed */
+  error?: string
+  /** Optional metadata about the response */
+  meta?: {
+    /** Total count of items (for paginated results) */
+    count?: number
+    /** Limit applied to results */
+    limit?: number
+    /** Whether results were truncated due to limit */
+    truncated?: boolean
+  }
+}
+
+/**
+ * Determine if output should be pretty-printed.
+ * Defaults to pretty for TTY, compact for piped output.
+ */
+function shouldPrettyPrint(options?: JsonFormatOptions): boolean {
+  if (options?.pretty !== undefined) {
+    return options.pretty
+  }
+  // Default: pretty for TTY, compact for pipes
+  return process.stdout.isTTY ?? false
+}
+
+/**
+ * Get the indentation string for pretty printing.
+ */
+function getIndent(options?: JsonFormatOptions): number | undefined {
+  if (!shouldPrettyPrint(options)) {
+    return undefined
+  }
+  return options?.indent ?? 2
+}
+
+/**
+ * Custom replacer function to handle special types during JSON serialization.
+ * - Converts Date objects to ISO strings
+ * - Handles undefined values
+ */
+function jsonReplacer(_key: string, value: unknown): unknown {
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+  return value
+}
+
+/**
+ * Format a single value as JSON.
+ */
+export function formatJson<T>(data: T, options?: JsonFormatOptions): string {
+  const indent = getIndent(options)
+  return JSON.stringify(data, jsonReplacer, indent)
+}
+
+/**
+ * Format an array of values as JSON.
+ */
+export function formatJsonArray<T>(data: T[], options?: JsonFormatOptions): string {
+  const indent = getIndent(options)
+  return JSON.stringify(data, jsonReplacer, indent)
+}
+
+/**
+ * Format a successful response with data.
+ */
+export function formatJsonSuccess<T>(
+  data: T,
+  meta?: JsonResponse<T>["meta"],
+  options?: JsonFormatOptions
+): string {
+  const response: JsonResponse<T> = {
+    ok: true,
+    data,
+    ...(meta && { meta }),
+  }
+  return formatJson(response, options)
+}
+
+/**
+ * Format a successful response with an array of data.
+ * Automatically populates count metadata.
+ */
+export function formatJsonArraySuccess<T>(
+  data: T[],
+  meta?: Omit<NonNullable<JsonResponse<T[]>["meta"]>, "count">,
+  options?: JsonFormatOptions
+): string {
+  const response: JsonResponse<T[]> = {
+    ok: true,
+    data,
+    meta: {
+      count: data.length,
+      ...meta,
+    },
+  }
+  return formatJson(response, options)
+}
+
+/**
+ * Format an error response.
+ */
+export function formatJsonError(
+  error: string | Error,
+  options?: JsonFormatOptions
+): string {
+  const message = error instanceof Error ? error.message : error
+  const response: JsonResponse<never> = {
+    ok: false,
+    error: message,
+  }
+  return formatJson(response, options)
+}
+
+/**
+ * Print JSON to stdout.
+ */
+export function printJson<T>(data: T, options?: JsonFormatOptions): void {
+  console.log(formatJson(data, options))
+}
+
+/**
+ * Print a JSON array to stdout.
+ */
+export function printJsonArray<T>(data: T[], options?: JsonFormatOptions): void {
+  console.log(formatJsonArray(data, options))
+}
+
+/**
+ * Print a success response to stdout.
+ */
+export function printJsonSuccess<T>(
+  data: T,
+  meta?: JsonResponse<T>["meta"],
+  options?: JsonFormatOptions
+): void {
+  console.log(formatJsonSuccess(data, meta, options))
+}
+
+/**
+ * Print a success response with array data to stdout.
+ */
+export function printJsonArraySuccess<T>(
+  data: T[],
+  meta?: Omit<NonNullable<JsonResponse<T[]>["meta"]>, "count">,
+  options?: JsonFormatOptions
+): void {
+  console.log(formatJsonArraySuccess(data, meta, options))
+}
+
+/**
+ * Print an error response to stdout.
+ */
+export function printJsonError(
+  error: string | Error,
+  options?: JsonFormatOptions
+): void {
+  console.log(formatJsonError(error, options))
+}

package/src/cli/formatters/ndjson.ts

@@ -0,0 +1,71 @@
+/**
+ * NDJSON (Newline Delimited JSON) output formatter for CLI commands.
+ *
+ * Provides streaming-friendly output with one JSON record per line.
+ * Ideal for piping to tools like `jq` or processing large datasets.
+ *
+ * @see https://github.com/ndjson/ndjson-spec
+ */
+
+/**
+ * Custom replacer function to handle special types during JSON serialization.
+ * - Converts Date objects to ISO strings
+ */
+function jsonReplacer(_key: string, value: unknown): unknown {
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+  return value
+}
+
+/**
+ * Format a single record as an NDJSON line (compact JSON with no trailing newline).
+ */
+export function formatNdjsonLine<T>(record: T): string {
+  return JSON.stringify(record, jsonReplacer)
+}
+
+/**
+ * Format an array of records as NDJSON (one JSON object per line).
+ * Each line is a complete, self-contained JSON object.
+ */
+export function formatNdjson<T>(records: T[]): string {
+  return records.map((record) => formatNdjsonLine(record)).join("\n")
+}
+
+/**
+ * Generator function to yield NDJSON lines one at a time.
+ * Useful for streaming large datasets without buffering the entire output.
+ */
+export function* streamNdjson<T>(records: Iterable<T>): Generator<string, void, unknown> {
+  for (const record of records) {
+    yield formatNdjsonLine(record)
+  }
+}
+
+/**
+ * Print a single record as an NDJSON line to stdout.
+ */
+export function printNdjsonLine<T>(record: T): void {
+  console.log(formatNdjsonLine(record))
+}
+
+/**
+ * Print an array of records as NDJSON to stdout.
+ * Each record is printed on its own line.
+ */
+export function printNdjson<T>(records: T[]): void {
+  for (const record of records) {
+    console.log(formatNdjsonLine(record))
+  }
+}
+
+/**
+ * Stream records to stdout as NDJSON.
+ * Flushes each line immediately, making it suitable for real-time output.
+ */
+export function streamPrintNdjson<T>(records: Iterable<T>): void {
+  for (const record of records) {
+    console.log(formatNdjsonLine(record))
+  }
+}