@every-env/spiral-cli 0.1.0

package/src/api.ts

@@ -0,0 +1,520 @@
+import { type EventSourceMessage, createParser } from "eventsource-parser";
+import { getAuthToken, sanitizeError } from "./auth";
+import {
+  ApiError,
+  type Conversation,
+  type Draft,
+  type DraftVersion,
+  type Message,
+  NetworkError,
+  type PatchOperation,
+  type ToolCall,
+  type Workspace,
+  type WritingStyle,
+} from "./types";
+
+// Use dev server in development, production backend otherwise
+const API_BASE =
+  process.env.SPIRAL_API_URL ||
+  (process.env.NODE_ENV === "development"
+    ? "http://localhost:8000"
+    : "https://spiral-next-backend-production.up.railway.app");
+
+const HEARTBEAT_TIMEOUT_MS = 20_000; // 20s (backend pings every 15s)
+const MAX_MESSAGE_LENGTH = 100_000; // Security: limit input size
+
+export interface StreamCallbacks {
+  onChunk: (chunk: string) => void;
+  onThinking: (thought: string) => void;
+  onToolCall: (tool: ToolCall) => void;
+  onSessionName: (name: string) => void;
+  onRetry: (info: { attempt: number; max: number; message: string }) => void;
+  onModelDowngrade: (from: string, to: string) => void;
+  onComplete: (sessionId: string) => void;
+  onError: (error: Error) => void;
+}
+
+/**
+ * Validate session ID format to prevent SSRF
+ * @security Reject malformed session IDs
+ */
+function isValidSessionId(id: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id);
+}
+
+export interface StreamChatOptions {
+  attachments?: Array<{ name: string; content: string; type: "text" | "binary" }>;
+  notes?: Array<{ content: string; feedback?: string }>;
+}
+
+/**
+ * Stream chat response from Spiral API
+ * @param signal AbortSignal for cancellation
+ */
+export async function streamChat(
+  message: string,
+  sessionId: string | null,
+  callbacks: StreamCallbacks,
+  signal?: AbortSignal,
+  options?: StreamChatOptions,
+): Promise<void> {
+  // Security: Validate inputs
+  if (message.length > MAX_MESSAGE_LENGTH) {
+    throw new ApiError(`Message too long (max ${MAX_MESSAGE_LENGTH} chars)`, 400);
+  }
+  if (sessionId && !isValidSessionId(sessionId)) {
+    throw new ApiError("Invalid session ID format", 400);
+  }
+
+  const token = await getAuthToken();
+
+  const formData = new FormData();
+  formData.append("user_message", message);
+  if (sessionId) {
+    formData.append("session_id", sessionId);
+  }
+
+  // Add file attachments
+  if (options?.attachments && options.attachments.length > 0) {
+    for (const attachment of options.attachments) {
+      const content =
+        attachment.type === "binary"
+          ? Buffer.from(attachment.content, "base64")
+          : attachment.content;
+      const blob = new Blob([content], {
+        type: attachment.type === "text" ? "text/plain" : "application/octet-stream",
+      });
+      formData.append("files", blob, attachment.name);
+    }
+  }
+
+  // Add notes/scratchpad
+  if (options?.notes && options.notes.length > 0) {
+    formData.append("notes", JSON.stringify(options.notes));
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(`${API_BASE}/api/v1/team/stream`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "text/event-stream",
+      },
+      body: formData,
+      signal,
+    });
+  } catch (error) {
+    if (signal?.aborted) return;
+    throw new NetworkError(`Connection failed: ${(error as Error).message}`);
+  }
+
+  // Parse error response body for better error messages
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => "");
+    let errorMessage = `API error: ${response.status}`;
+    try {
+      const errorJson = JSON.parse(errorText);
+      errorMessage = errorJson.detail?.message || errorJson.detail || errorMessage;
+    } catch {
+      /* use default message */
+    }
+    if (process.env.DEBUG) {
+      console.debug("API error response:", {
+        status: response.status,
+        url: `${API_BASE}/api/v1/team/stream`,
+        errorText: errorText.substring(0, 200),
+      });
+    }
+    throw new ApiError(sanitizeError(new Error(errorMessage), token), response.status, errorText);
+  }
+
+  // Performance: Use array accumulation (O(n) vs O(n²) string concat)
+  let currentSessionId = sessionId || "";
+  let lastHeartbeat = Date.now();
+
+  // Heartbeat timeout detection
+  const heartbeatCheck = setInterval(() => {
+    if (Date.now() - lastHeartbeat > HEARTBEAT_TIMEOUT_MS) {
+      clearInterval(heartbeatCheck);
+      callbacks.onError(new NetworkError("Stream timeout: no heartbeat received"));
+    }
+  }, 5000);
+
+  const parser = createParser({
+    onEvent(event: EventSourceMessage) {
+      lastHeartbeat = Date.now(); // Reset heartbeat on any event
+
+      if (event.data === "[DONE]") {
+        return;
+      }
+
+      try {
+        const data = JSON.parse(event.data);
+
+        // Handle ALL event types from the SSE spec
+        switch (event.event) {
+          // Content events
+          case "RunResponseContent":
+          case "RunResponse":
+            if (data.content) callbacks.onChunk(data.content);
+            if (data.thinking) callbacks.onThinking(data.thinking);
+            if (data.reasoning_content) callbacks.onThinking(data.reasoning_content);
+            break;
+
+          // Session events
+          case "RunStarted":
+            currentSessionId = data.run_id || data.session_id || currentSessionId;
+            break;
+          case "SessionName":
+            callbacks.onSessionName(data.content || data.name || data.session_name);
+            break;
+
+          // Tool events
+          case "ToolCallStarted":
+            if (data.tools) {
+              for (const tool of data.tools) {
+                callbacks.onToolCall({ ...tool, status: "started" });
+              }
+            } else if (data.tool) {
+              const toolName = typeof data.tool === "string" ? data.tool : data.tool.tool_name;
+              callbacks.onToolCall({ tool_name: toolName, status: "started" });
+            }
+            break;
+          case "ToolCallArgumentsDelta":
+            callbacks.onToolCall({
+              tool_name: data.tool_name || "unknown",
+              tool_call_id: data.tool_call_id,
+              status: "arguments_delta",
+            });
+            break;
+          case "ToolCallArgumentsDone":
+            callbacks.onToolCall({
+              tool_name: data.tool_name || "unknown",
+              tool_call_id: data.tool_call_id,
+              status: "arguments_done",
+            });
+            break;
+          case "ToolCallCompleted":
+            if (data.tools) {
+              for (const tool of data.tools) {
+                callbacks.onToolCall({ ...tool, status: "completed" });
+              }
+            } else if (data.tool) {
+              const toolName = typeof data.tool === "string" ? data.tool : data.tool.tool_name;
+              callbacks.onToolCall({ tool_name: toolName, status: "completed" });
+            }
+            break;
+
+          // Completion
+          case "RunCompleted":
+            callbacks.onComplete(currentSessionId);
+            break;
+
+          // Handoff notification (agent switching)
+          case "HandoffNotification":
+            if (process.env.DEBUG) {
+              console.debug(`Agent handoff: ${data.from_agent} → ${data.to_agent}`);
+            }
+            break;
+
+          // Error handling events
+          case "retry_started":
+          case "retry_attempt":
+            try {
+              const retryData = typeof data.content === "string" ? JSON.parse(data.content) : data;
+              callbacks.onRetry({
+                attempt: retryData.retry_attempt || 1,
+                max: retryData.max_retries || 3,
+                message: retryData.message || "Retrying...",
+              });
+            } catch {
+              callbacks.onRetry({ attempt: 1, max: 3, message: "Retrying..." });
+            }
+            break;
+          case "retry_failed":
+            callbacks.onError(new ApiError(data.message || data.content || "Retry failed", 500));
+            break;
+          case "model_downgrade":
+            try {
+              const downgradeData =
+                typeof data.content === "string" ? JSON.parse(data.content) : data;
+              callbacks.onModelDowngrade(
+                downgradeData.from_model || "unknown",
+                downgradeData.to_model || "unknown",
+              );
+            } catch {
+              callbacks.onModelDowngrade("unknown", "unknown");
+            }
+            break;
+          case "Error":
+            callbacks.onError(
+              new ApiError(data.content || "Unknown error", data.status_code || 500),
+            );
+            break;
+        }
+      } catch (_parseError) {
+        // Log parse errors in debug mode (don't silently swallow)
+        if (process.env.DEBUG) {
+          console.debug("Skipping non-JSON SSE event:", event.data?.substring(0, 100));
+        }
+      }
+    },
+    onComment() {
+      lastHeartbeat = Date.now(); // Pings appear as comments
+    },
+    onError(error) {
+      if (process.env.DEBUG) {
+        console.debug("SSE parse error:", error);
+      }
+    },
+  });
+
+  const reader = response.body?.getReader();
+  if (!reader) throw new NetworkError("No response body");
+
+  const decoder = new TextDecoder();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (signal?.aborted) break;
+      parser.feed(decoder.decode(value, { stream: true }));
+    }
+  } finally {
+    clearInterval(heartbeatCheck);
+    reader.releaseLock();
+    parser.reset(); // Clear internal buffers (per performance review)
+  }
+}
+
+/**
+ * Fetch conversations list
+ * @note Uses /conversations not /sessions (architecture review fix)
+ */
+export async function fetchConversations(): Promise<Conversation[]> {
+  const token = await getAuthToken();
+
+  const response = await fetch(`${API_BASE}/api/v1/conversations`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+
+  if (!response.ok) {
+    throw new ApiError(`Failed to fetch conversations: ${response.status}`, response.status);
+  }
+
+  const data = await response.json();
+  return data.sessions || [];
+}
+
+/**
+ * Fetch conversation messages
+ */
+export async function fetchMessages(conversationId: string): Promise<Message[]> {
+  if (!isValidSessionId(conversationId)) {
+    throw new ApiError("Invalid conversation ID format", 400);
+  }
+
+  const token = await getAuthToken();
+
+  const response = await fetch(
+    `${API_BASE}/api/v1/conversations/${encodeURIComponent(conversationId)}/messages`,
+    { headers: { Authorization: `Bearer ${token}` } },
+  );
+
+  if (!response.ok) {
+    throw new ApiError(`Failed to fetch messages: ${response.status}`, response.status);
+  }
+
+  const data = await response.json();
+  return data.messages || [];
+}
+
+/**
+ * Get the current API base URL (for debugging)
+ */
+export function getApiBaseUrl(): string {
+  return API_BASE;
+}
+
+// ============================================================================
+// Draft API Methods
+// ============================================================================
+
+/**
+ * Fetch all drafts for a session
+ */
+export async function fetchSessionDrafts(sessionId: string): Promise<Draft[]> {
+  if (!isValidSessionId(sessionId)) {
+    throw new ApiError("Invalid session ID format", 400);
+  }
+  const token = await getAuthToken();
+  const response = await fetch(`${API_BASE}/api/v1/sessions/${sessionId}/drafts`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!response.ok) {
+    throw new ApiError(`Failed to fetch drafts: ${response.status}`, response.status);
+  }
+  const data = await response.json();
+  // Backend returns array directly, not wrapped in {drafts: ...}
+  return Array.isArray(data) ? data : data.drafts || [];
+}
+
+/**
+ * Fetch a single draft with full content
+ */
+export async function fetchDraft(sessionId: string, draftId: string): Promise<Draft> {
+  if (!isValidSessionId(sessionId)) {
+    throw new ApiError("Invalid session ID format", 400);
+  }
+  const token = await getAuthToken();
+  const response = await fetch(
+    `${API_BASE}/api/v1/sessions/${sessionId}/drafts/${draftId}/nodes?mode=full`,
+    { headers: { Authorization: `Bearer ${token}` } },
+  );
+  if (!response.ok) {
+    throw new ApiError(`Failed to fetch draft: ${response.status}`, response.status);
+  }
+  return response.json();
+}
+
+/**
+ * Update draft content
+ */
+export async function updateDraft(
+  sessionId: string,
+  draftId: string,
+  content: string,
+  title?: string,
+): Promise<Draft> {
+  if (!isValidSessionId(sessionId)) {
+    throw new ApiError("Invalid session ID format", 400);
+  }
+  const token = await getAuthToken();
+  const response = await fetch(`${API_BASE}/api/v1/sessions/${sessionId}/drafts/${draftId}`, {
+    method: "PUT",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ content, title }),
+  });
+  if (!response.ok) {
+    throw new ApiError(`Failed to update draft: ${response.status}`, response.status);
+  }
+  return response.json();
+}
+
+/**
+ * Fetch draft version history
+ */
+export async function fetchDraftVersions(
+  sessionId: string,
+  draftId: string,
+): Promise<DraftVersion[]> {
+  if (!isValidSessionId(sessionId)) {
+    throw new ApiError("Invalid session ID format", 400);
+  }
+  const token = await getAuthToken();
+  const response = await fetch(
+    `${API_BASE}/api/v1/sessions/${sessionId}/drafts/${draftId}/versions`,
+    { headers: { Authorization: `Bearer ${token}` } },
+  );
+  if (!response.ok) {
+    throw new ApiError(`Failed to fetch versions: ${response.status}`, response.status);
+  }
+  const data = await response.json();
+  return data.versions || [];
+}
+
+/**
+ * Restore a draft to a specific version
+ */
+export async function restoreDraftVersion(
+  sessionId: string,
+  draftId: string,
+  versionId: string,
+): Promise<Draft> {
+  if (!isValidSessionId(sessionId)) {
+    throw new ApiError("Invalid session ID format", 400);
+  }
+  const token = await getAuthToken();
+  const response = await fetch(
+    `${API_BASE}/api/v1/sessions/${sessionId}/drafts/${draftId}/restore/${versionId}`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+    },
+  );
+  if (!response.ok) {
+    throw new ApiError(`Failed to restore version: ${response.status}`, response.status);
+  }
+  return response.json();
+}
+
+/**
+ * Apply patch operations to a draft
+ */
+export async function applyDraftPatch(
+  sessionId: string,
+  draftId: string,
+  operations: PatchOperation[],
+): Promise<Draft> {
+  if (!isValidSessionId(sessionId)) {
+    throw new ApiError("Invalid session ID format", 400);
+  }
+  const token = await getAuthToken();
+  const response = await fetch(
+    `${API_BASE}/api/v1/sessions/${sessionId}/drafts/${draftId}/apply-patch`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ operations }),
+    },
+  );
+  if (!response.ok) {
+    throw new ApiError(`Failed to apply patch: ${response.status}`, response.status);
+  }
+  return response.json();
+}
+
+// ============================================================================
+// Writing Styles API
+// ============================================================================
+
+/**
+ * Fetch all writing styles
+ */
+export async function fetchWritingStyles(): Promise<WritingStyle[]> {
+  const token = await getAuthToken();
+  const response = await fetch(`${API_BASE}/api/v1/writing-styles/`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!response.ok) {
+    throw new ApiError(`Failed to fetch writing styles: ${response.status}`, response.status);
+  }
+  const data = await response.json();
+  return data.styles || data || [];
+}
+
+// ============================================================================
+// Workspaces API
+// ============================================================================
+
+/**
+ * Fetch all workspaces
+ */
+export async function fetchWorkspaces(): Promise<Workspace[]> {
+  const token = await getAuthToken();
+  const response = await fetch(`${API_BASE}/api/v1/workspaces/`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!response.ok) {
+    throw new ApiError(`Failed to fetch workspaces: ${response.status}`, response.status);
+  }
+  const data = await response.json();
+  return data.workspaces || data || [];
+}

package/src/attachments/index.ts

@@ -0,0 +1,174 @@
+// File attachment handling with security mitigations
+// See plan: Path traversal and symlink security risks identified
+
+import { lstatSync } from "node:fs";
+import { resolve } from "node:path";
+import ora from "ora";
+import type { Attachment } from "../types";
+
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_TOTAL_SIZE = 50 * 1024 * 1024; // 50MB total
+const MAX_FILES = 5;
+
+// SECURITY: Paths that should never be accessed
+const SENSITIVE_PATHS = ["/etc", "/var", "/root", "/private"];
+const HOME = process.env.HOME || "";
+if (HOME) {
+  SENSITIVE_PATHS.push(`${HOME}/.ssh`, `${HOME}/.gnupg`, `${HOME}/.aws`);
+}
+
+// Known text file extensions
+const TEXT_EXTENSIONS = new Set([
+  ".txt",
+  ".md",
+  ".json",
+  ".yaml",
+  ".yml",
+  ".xml",
+  ".html",
+  ".css",
+  ".js",
+  ".ts",
+  ".tsx",
+  ".jsx",
+  ".py",
+  ".rb",
+  ".go",
+  ".rs",
+  ".java",
+  ".c",
+  ".cpp",
+  ".h",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".sql",
+  ".csv",
+  ".log",
+  ".env",
+  ".gitignore",
+  ".toml",
+  ".ini",
+  ".conf",
+  ".markdown",
+  ".rst",
+]);
+
+/**
+ * Validate and sanitize file path
+ * @security Prevents path traversal, blocks sensitive paths, rejects symlinks
+ */
+function sanitizePath(inputPath: string): string {
+  const resolved = resolve(inputPath);
+
+  // Block path traversal
+  if (inputPath.includes("..")) {
+    throw new Error(`Path traversal attempt: ${inputPath}`);
+  }
+
+  // Block sensitive paths
+  for (const sensitive of SENSITIVE_PATHS) {
+    if (resolved.startsWith(sensitive)) {
+      throw new Error(`Access to sensitive path denied: ${inputPath}`);
+    }
+  }
+
+  // Block symlinks (could point anywhere)
+  try {
+    const stat = lstatSync(resolved);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Symlinks not allowed: ${inputPath}`);
+    }
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+  }
+
+  return resolved;
+}
+
+/**
+ * Process file attachments for sending with messages
+ */
+export async function processAttachments(
+  filePaths: string[],
+  options: { quiet?: boolean } = {},
+): Promise<Attachment[]> {
+  if (filePaths.length > MAX_FILES) {
+    throw new Error(`Too many files. Maximum ${MAX_FILES} files allowed.`);
+  }
+
+  const spinner = options.quiet ? null : ora("Processing attachments...").start();
+  const attachments: Attachment[] = [];
+  let totalSize = 0;
+
+  for (const filePath of filePaths) {
+    // SECURITY: Sanitize path before access
+    const safePath = sanitizePath(filePath);
+    const file = Bun.file(safePath);
+
+    if (!(await file.exists())) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+
+    const size = file.size;
+
+    if (size > MAX_FILE_SIZE) {
+      throw new Error(
+        `File too large: ${filePath} (${(size / 1024 / 1024).toFixed(1)}MB). Max ${MAX_FILE_SIZE / 1024 / 1024}MB.`,
+      );
+    }
+
+    totalSize += size;
+    if (totalSize > MAX_TOTAL_SIZE) {
+      throw new Error(`Total attachment size exceeds ${MAX_TOTAL_SIZE / 1024 / 1024}MB limit.`);
+    }
+
+    const fileName = filePath.split("/").pop() || filePath;
+    const ext = `.${fileName.split(".").pop()?.toLowerCase() || ""}`;
+
+    // Determine if text or binary
+    const isText = TEXT_EXTENSIONS.has(ext);
+    const mimeType = file.type || (isText ? "text/plain" : "application/octet-stream");
+
+    if (spinner) {
+      spinner.text = `Processing ${fileName}...`;
+    }
+
+    let content: string;
+    if (isText) {
+      content = await file.text();
+    } else {
+      const buffer = await file.arrayBuffer();
+      content = Buffer.from(buffer).toString("base64");
+    }
+
+    attachments.push({
+      name: fileName,
+      content,
+      type: isText ? "text" : "binary",
+      size,
+      mimeType,
+    });
+  }
+
+  spinner?.succeed(`Processed ${attachments.length} file(s)`);
+
+  return attachments;
+}
+
+/**
+ * Format attachments summary for display
+ */
+export function formatAttachmentsSummary(attachments: Attachment[]): string {
+  if (attachments.length === 0) return "";
+
+  const totalSize = attachments.reduce((sum, a) => sum + a.size, 0);
+  const sizeStr =
+    totalSize < 1024
+      ? `${totalSize}B`
+      : totalSize < 1024 * 1024
+        ? `${(totalSize / 1024).toFixed(1)}KB`
+        : `${(totalSize / 1024 / 1024).toFixed(1)}MB`;
+
+  return `${attachments.length} file(s), ${sizeStr} total`;
+}