@mks2508/coolify-mks-cli-mcp 0.5.0 → 0.6.1

package/src/tools/index.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Tools barrel export.
+ *
+ * @module
+ */
+
+export { coolifyTools } from "./definitions.js";
+export { handleToolCall } from "./handlers.js";

package/src/trace.ts

@@ -0,0 +1,116 @@
+/**
+ * Operation tracing system.
+ *
+ * Provides step-by-step tracing for all operations across CLI, MCP, and SDK.
+ * - **CLI mode**: Logs to stderr with chalk colors (no spinners in trace)
+ * - **MCP mode**: Collects steps silently, returns in response
+ * - **SDK mode**: Fires callback if provided, otherwise collects
+ *
+ * @module
+ */
+
+/**
+ * A single trace step.
+ */
+export interface ITraceStep {
+  /** Timestamp */
+  ts: string;
+  /** Step label */
+  step: string;
+  /** Duration in ms (filled after completion) */
+  durationMs?: number;
+  /** Optional detail */
+  detail?: string;
+}
+
+/**
+ * Complete operation trace.
+ */
+export interface IOperationTrace {
+  /** Operation name */
+  operation: string;
+  /** All steps */
+  steps: ITraceStep[];
+  /** Total duration */
+  totalMs: number;
+  /** Whether operation succeeded */
+  success: boolean;
+  /** Error message if failed */
+  error?: string;
+}
+
+/**
+ * Callback for real-time trace updates.
+ */
+export type TraceCallback = (step: string, detail?: string) => void;
+
+/** Detect if running as MCP server (stdout is the transport). */
+export function isMcpMode(): boolean {
+  // MCP servers communicate over stdout — if we're piped, assume MCP
+  return !process.stdout.isTTY;
+}
+
+/**
+ * Operation tracer that collects steps.
+ */
+export class OperationTracer {
+  private steps: ITraceStep[] = [];
+  private startTime: number;
+  private stepStart: number;
+  private onStep?: TraceCallback;
+
+  constructor(
+    public readonly operation: string,
+    onStep?: TraceCallback,
+  ) {
+    this.startTime = Date.now();
+    this.stepStart = this.startTime;
+    this.onStep = onStep;
+  }
+
+  /**
+   * Records a trace step.
+   *
+   * @param step - Step description
+   * @param detail - Optional detail
+   */
+  step(step: string, detail?: string): void {
+    const now = Date.now();
+    const traceStep: ITraceStep = {
+      ts: new Date(now).toISOString(),
+      step,
+      durationMs: now - this.stepStart,
+      detail,
+    };
+    this.steps.push(traceStep);
+    this.stepStart = now;
+
+    // Fire callback for real-time updates
+    this.onStep?.(step, detail);
+
+    // In TTY (CLI) mode, log to stderr so it doesn't pollute MCP stdout
+    if (process.stderr.isTTY) {
+      const prefix = `\x1b[90m[${this.operation}]\x1b[0m`;
+      const elapsed = `\x1b[33m${traceStep.durationMs}ms\x1b[0m`;
+      const detailStr = detail ? ` \x1b[90m(${detail})\x1b[0m` : "";
+      process.stderr.write(`${prefix} ${step} ${elapsed}${detailStr}\n`);
+    }
+  }
+
+  /**
+   * Finalizes the trace.
+   *
+   * @param success - Whether operation succeeded
+   * @param error - Error message if failed
+   * @returns Complete operation trace
+   */
+  finish(success: boolean, error?: string): IOperationTrace {
+    return {
+      operation: this.operation,
+      steps: this.steps,
+      totalMs: Date.now() - this.startTime,
+      success,
+      error,
+    };
+  }
+}

package/src/utils/format.ts

@@ -6,8 +6,8 @@
  * @module
  */
 
-import Table from 'cli-table3'
-import chalk from 'chalk'
+import Table from "cli-table3";
+import chalk from "chalk";
 
 /**
  * Gets the terminal width.
@@ -15,7 +15,7 @@ import chalk from 'chalk'
  * @returns Terminal column count
  */
 function getTerminalWidth(): number {
-  return process.stdout.columns || 80
+  return process.stdout.columns || 80;
 }
 
 /**
@@ -26,12 +26,12 @@ function getTerminalWidth(): number {
  * @returns Configured Table instance
  */
 export function createTable(headers: string[], colWidths?: number[]) {
-  const columns = getTerminalWidth()
+  const columns = getTerminalWidth();
 
   return new Table({
     head: headers.map((h) => chalk.cyan(h)),
     colWidths: colWidths || calculateColumnWidths(columns, headers.length),
-  })
+  });
 }
 
 /**
@@ -41,11 +41,14 @@ export function createTable(headers: string[], colWidths?: number[]) {
  * @param numColumns - Number of columns
  * @returns Array of column widths
  */
-function calculateColumnWidths(totalWidth: number, numColumns: number): number[] {
-  const padding = 4
-  const availableWidth = totalWidth - padding * numColumns
-  const colWidth = Math.floor(availableWidth / numColumns)
-  return Array(numColumns).fill(colWidth)
+function calculateColumnWidths(
+  totalWidth: number,
+  numColumns: number,
+): number[] {
+  const padding = 4;
+  const availableWidth = totalWidth - padding * numColumns;
+  const colWidth = Math.floor(availableWidth / numColumns);
+  return Array(numColumns).fill(colWidth);
 }
 
 /**
@@ -56,15 +59,15 @@ function calculateColumnWidths(totalWidth: number, numColumns: number): number[]
  */
 export function formatStatus(status: string): string {
   const statusMap: Record<string, string> = {
-    running: chalk.green('● Running'),
-    'running:unknown': chalk.green('● Running'),
-    stopped: chalk.red('○ Stopped'),
-    'restarting': chalk.yellow('◐ Restarting'),
-    error: chalk.red('✗ Error'),
-    deploying: chalk.yellow('◐ Deploying'),
-  }
+    running: chalk.green("● Running"),
+    "running:unknown": chalk.green("● Running"),
+    stopped: chalk.red("○ Stopped"),
+    restarting: chalk.yellow("◐ Restarting"),
+    error: chalk.red("✗ Error"),
+    deploying: chalk.yellow("◐ Deploying"),
+  };
 
-  return statusMap[status] || status
+  return statusMap[status] || status;
 }
 
 /**
@@ -74,13 +77,13 @@ export function formatStatus(status: string): string {
  * @returns Formatted string with unit
  */
 export function formatBytes(bytes: number): string {
-  const units = ['B', 'KB', 'MB', 'GB', 'TB']
-  let i = 0
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let i = 0;
   while (bytes >= 1024 && i < units.length - 1) {
-    bytes /= 1024
-    i++
+    bytes /= 1024;
+    i++;
   }
-  return `${bytes.toFixed(1)} ${units[i]}`
+  return `${bytes.toFixed(1)} ${units[i]}`;
 }
 
 /**
@@ -90,15 +93,15 @@ export function formatBytes(bytes: number): string {
  * @returns Relative time string
  */
 export function formatRelativeTime(timestamp: string): string {
-  const date = new Date(timestamp)
-  const now = new Date()
-  const diffMs = now.getTime() - date.getTime()
-  const diffMins = Math.floor(diffMs / 60000)
-  const diffHours = Math.floor(diffMs / 3600000)
-  const diffDays = Math.floor(diffMs / 86400000)
+  const date = new Date(timestamp);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
 
-  if (diffMins < 1) return 'just now'
-  if (diffMins < 60) return `${diffMins}m ago`
-  if (diffHours < 24) return `${diffHours}h ago`
-  return `${diffDays}d ago`
+  if (diffMins < 1) return "just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  return `${diffDays}d ago`;
 }