@every-env/spiral-cli 0.1.0

package/src/suggestions/index.ts

@@ -0,0 +1,205 @@
+// Suggestion management commands
+// See plan: Performance review identified unbounded storage risk
+
+import { confirm } from "@inquirer/prompts";
+import ora from "ora";
+import { applyDraftPatch } from "../api";
+import { theme } from "../theme";
+import type { Suggestion } from "../types";
+import { displayInlineDiff } from "./diff";
+import { parseSuggestions } from "./parser";
+
+// LRU cache for suggestions with TTL
+const MAX_SUGGESTIONS = 50;
+const SUGGESTION_TTL_MS = 30 * 60 * 1000; // 30 minutes
+
+interface CachedSuggestion {
+  suggestion: Suggestion;
+  timestamp: number;
+}
+
+// Store pending suggestions with LRU eviction
+const suggestionCache: Map<string, CachedSuggestion> = new Map();
+
+/**
+ * Clean expired suggestions and enforce max size
+ */
+function cleanupCache(): void {
+  const now = Date.now();
+  const entries = Array.from(suggestionCache.entries());
+
+  // Remove expired
+  for (const [id, cached] of entries) {
+    if (now - cached.timestamp > SUGGESTION_TTL_MS) {
+      suggestionCache.delete(id);
+    }
+  }
+
+  // LRU eviction if over limit
+  if (suggestionCache.size > MAX_SUGGESTIONS) {
+    const sorted = entries.sort((a, b) => a[1].timestamp - b[1].timestamp);
+    const toRemove = sorted.slice(0, suggestionCache.size - MAX_SUGGESTIONS);
+    for (const [id] of toRemove) {
+      suggestionCache.delete(id);
+    }
+  }
+}
+
+/**
+ * Register suggestions from AI response content
+ */
+export function registerSuggestions(content: string): number {
+  const suggestions = parseSuggestions(content);
+  for (const sug of suggestions) {
+    suggestionCache.set(sug.id, {
+      suggestion: sug,
+      timestamp: Date.now(),
+    });
+  }
+  cleanupCache();
+  return suggestions.length;
+}
+
+/**
+ * Get a suggestion by ID
+ */
+function getSuggestion(id: string): Suggestion | undefined {
+  const cached = suggestionCache.get(id);
+  return cached?.suggestion;
+}
+
+/**
+ * List all pending suggestions
+ */
+export function listPendingSuggestions(options: { json?: boolean }): void {
+  cleanupCache();
+  const suggestions = Array.from(suggestionCache.values())
+    .map((c) => c.suggestion)
+    .filter((s) => s.status === "pending");
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, suggestions }));
+    return;
+  }
+
+  if (suggestions.length === 0) {
+    console.log(theme.dim("No pending suggestions."));
+    return;
+  }
+
+  console.log(theme.heading(`\nPending Suggestions (${suggestions.length}):\n`));
+
+  for (const sug of suggestions) {
+    console.log(`${theme.dim(sug.id)} -> draft ${theme.dim(sug.targetDraftId.slice(0, 8))}`);
+    console.log(`  ${theme.dim("Before:")} ${sug.before.slice(0, 40)}...`);
+    console.log(`  ${theme.success("After:")} ${sug.after.slice(0, 40)}...`);
+    if (sug.rationale) {
+      console.log(`  ${theme.info("Why:")} ${sug.rationale}`);
+    }
+    console.log();
+  }
+}
+
+/**
+ * Preview a suggestion with diff display
+ */
+export async function previewSuggestion(
+  suggestionId: string,
+  options: { json?: boolean },
+): Promise<void> {
+  const suggestion = getSuggestion(suggestionId);
+
+  if (!suggestion) {
+    throw new Error(`Suggestion not found: ${suggestionId}`);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, suggestion }));
+    return;
+  }
+
+  console.log(theme.heading("\nSuggestion Preview"));
+  console.log(theme.dim(`Target: draft ${suggestion.targetDraftId.slice(0, 8)}`));
+
+  if (suggestion.rationale) {
+    console.log(theme.info(`\nRationale: ${suggestion.rationale}`));
+  }
+
+  displayInlineDiff(suggestion.before, suggestion.after);
+}
+
+/**
+ * Apply a suggestion to its target draft
+ */
+export async function applySuggestion(
+  sessionId: string,
+  suggestionId: string,
+  options: { json?: boolean; force?: boolean },
+): Promise<void> {
+  const suggestion = getSuggestion(suggestionId);
+
+  if (!suggestion) {
+    throw new Error(`Suggestion not found: ${suggestionId}`);
+  }
+
+  if (suggestion.status !== "pending") {
+    throw new Error(`Suggestion already ${suggestion.status}`);
+  }
+
+  // Show preview and confirm (unless --force)
+  if (!options.force && !options.json) {
+    await previewSuggestion(suggestionId, { json: false });
+    const proceed = await confirm({
+      message: "Apply this suggestion?",
+      default: true,
+    });
+    if (!proceed) {
+      console.log(theme.dim("Cancelled."));
+      return;
+    }
+  }
+
+  const spinner = ora("Applying suggestion...").start();
+
+  try {
+    await applyDraftPatch(sessionId, suggestion.targetDraftId, [
+      {
+        type: "replace",
+        range: suggestion.range,
+        content: suggestion.after,
+      },
+    ]);
+
+    suggestion.status = "applied";
+    spinner.succeed("Suggestion applied");
+
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, suggestion }));
+    }
+  } catch (error) {
+    spinner.fail("Failed to apply suggestion");
+    throw error;
+  }
+}
+
+/**
+ * Dismiss a suggestion without applying
+ */
+export function dismissSuggestion(suggestionId: string, options: { json?: boolean }): void {
+  const suggestion = getSuggestion(suggestionId);
+
+  if (!suggestion) {
+    throw new Error(`Suggestion not found: ${suggestionId}`);
+  }
+
+  suggestion.status = "dismissed";
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, dismissed: suggestionId }));
+  } else {
+    console.log(theme.dim(`Dismissed suggestion ${suggestionId}`));
+  }
+}
+
+// Re-export parser functions
+export { hasSuggestions, parseSuggestions } from "./parser";

package/src/suggestions/parser.ts

@@ -0,0 +1,83 @@
+// Suggestion parser with type-safe JSON handling
+// See plan: TypeScript review identified need for type guards
+
+import type { Suggestion } from "../types";
+
+// Suggestion syntax in AI responses:
+// ```suggestion[target=draft-id]
+// {"before": "old text", "after": "new text", "rationale": "why"}
+// ```
+
+const SUGGESTION_REGEX = /```suggestion\[target=([^\]]+)\]\n([\s\S]*?)```/g;
+
+// TYPESCRIPT: Type guard for safe JSON parsing
+interface SuggestionPayload {
+  before?: string;
+  after?: string;
+  rationale?: string;
+  range?: [number, number];
+}
+
+function isSuggestionPayload(value: unknown): value is SuggestionPayload {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (!("before" in value) || typeof (value as SuggestionPayload).before === "string") &&
+    (!("after" in value) || typeof (value as SuggestionPayload).after === "string")
+  );
+}
+
+/**
+ * Parse suggestions from AI response content
+ */
+export function parseSuggestions(content: string): Suggestion[] {
+  const suggestions: Suggestion[] = [];
+  // Create fresh regex each call to avoid state issues with global flag
+  const regex = new RegExp(SUGGESTION_REGEX.source, "g");
+  let match: RegExpExecArray | null = regex.exec(content);
+
+  while (match !== null) {
+    const targetDraftId = match[1];
+    const jsonContent = match[2]?.trim();
+
+    // Guard against undefined captures
+    if (!targetDraftId || !jsonContent) continue;
+
+    try {
+      const parsed: unknown = JSON.parse(jsonContent);
+
+      // TYPESCRIPT: Validate shape before use
+      if (!isSuggestionPayload(parsed)) {
+        if (process.env.DEBUG) {
+          console.debug("Invalid suggestion format");
+        }
+        continue;
+      }
+
+      suggestions.push({
+        id: `sug-${Date.now()}-${suggestions.length}`,
+        targetDraftId,
+        before: parsed.before ?? "",
+        after: parsed.after ?? "",
+        rationale: parsed.rationale,
+        range: parsed.range,
+        status: "pending",
+      });
+    } catch {
+      // Skip malformed suggestions
+      if (process.env.DEBUG) {
+        console.debug("Skipping malformed suggestion:", jsonContent.slice(0, 100));
+      }
+    }
+    match = regex.exec(content);
+  }
+
+  return suggestions;
+}
+
+/**
+ * Check if content contains suggestions
+ */
+export function hasSuggestions(content: string): boolean {
+  return new RegExp(SUGGESTION_REGEX.source).test(content);
+}

package/src/theme.ts

@@ -0,0 +1,23 @@
+import chalk from "chalk";
+
+export const theme = {
+  error: chalk.bold.red,
+  warning: chalk.hex("#FFA500"),
+  success: chalk.green,
+  info: chalk.blue,
+  dim: chalk.dim,
+  heading: chalk.bold.cyan,
+  code: chalk.yellow,
+  user: chalk.blue,
+  assistant: chalk.green,
+  thinking: chalk.dim.italic,
+};
+
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  GENERAL_ERROR: 1,
+  AUTH_ERROR: 2,
+  API_ERROR: 3,
+  NETWORK_ERROR: 4,
+  INVALID_ARGS: 5,
+} as const;

package/src/tools/renderer.ts

@@ -0,0 +1,104 @@
+// Tool call visualization with spinner management
+import type { Ora } from "ora";
+import ora from "ora";
+import { theme } from "../theme";
+import type { ToolCallUpdate } from "../types";
+
+// Tool icons for visual identification
+const TOOL_ICONS: Record<string, string> = {
+  search_web: "S",
+  read_file: "R",
+  create_draft: "D",
+  replace_draft_content: "E",
+  analyze: "A",
+  default: "T",
+};
+
+// Track active tool spinners
+const toolSpinners: Map<string, Ora> = new Map();
+
+/**
+ * Render tool call start
+ */
+export function renderToolStart(callId: string, toolName: string): void {
+  const icon = TOOL_ICONS[toolName] || TOOL_ICONS.default;
+  const spinner = ora({
+    text: `[${icon}] ${toolName}`,
+    prefixText: theme.dim(`[${callId.slice(0, 6)}]`),
+  }).start();
+  toolSpinners.set(callId, spinner);
+}
+
+/**
+ * Render tool call completion
+ */
+export function renderToolComplete(
+  callId: string,
+  toolName: string,
+  result?: unknown,
+  error?: string,
+): void {
+  const spinner = toolSpinners.get(callId);
+  const icon = TOOL_ICONS[toolName] || TOOL_ICONS.default;
+
+  if (error) {
+    spinner?.fail(`[${icon}] ${toolName}: ${theme.error(error.slice(0, 50))}`);
+  } else {
+    const summary = formatResultSummary(result);
+    spinner?.succeed(`[${icon}] ${toolName}${summary ? `: ${summary}` : ""}`);
+  }
+
+  toolSpinners.delete(callId);
+}
+
+/**
+ * Handle tool call update event
+ */
+export function handleToolCallUpdate(update: ToolCallUpdate): void {
+  switch (update.status) {
+    case "started":
+      renderToolStart(update.callId, update.toolName);
+      break;
+    case "completed":
+      renderToolComplete(update.callId, update.toolName, update.result);
+      break;
+    case "error":
+      renderToolComplete(update.callId, update.toolName, undefined, update.error);
+      break;
+    case "arguments_delta":
+    case "arguments_done":
+      // Update spinner text if needed
+      {
+        const spinner = toolSpinners.get(update.callId);
+        if (spinner) {
+          const icon = TOOL_ICONS[update.toolName] || TOOL_ICONS.default;
+          spinner.text = `[${icon}] ${update.toolName}...`;
+        }
+      }
+      break;
+  }
+}
+
+/**
+ * Format result for summary display
+ */
+function formatResultSummary(result: unknown): string {
+  if (!result) return "";
+  if (typeof result === "string") return result.slice(0, 50);
+  if (Array.isArray(result)) return `${result.length} items`;
+  if (typeof result === "object") {
+    const keys = Object.keys(result);
+    return `{${keys.slice(0, 3).join(", ")}${keys.length > 3 ? "..." : ""}}`;
+  }
+  return String(result).slice(0, 50);
+}
+
+/**
+ * Clean up all active tool spinners
+ */
+export function cleanupToolSpinners(): void {
+  for (const spinner of toolSpinners.values()) {
+    spinner.stop();
+  }
+  toolSpinners.clear();
+}

package/src/types/marked-terminal.d.ts

@@ -0,0 +1,31 @@
+declare module "marked-terminal" {
+  import type { MarkedExtension } from "marked";
+
+  interface MarkedTerminalOptions {
+    heading?: (text: string) => string;
+    code?: (text: string) => string;
+    codespan?: (text: string) => string;
+    blockquote?: (text: string) => string;
+    list?: (text: string) => string;
+    listitem?: (text: string) => string;
+    link?: (href: string, title: string | null, text: string) => string;
+    strong?: (text: string) => string;
+    em?: (text: string) => string;
+    del?: (text: string) => string;
+    paragraph?: (text: string) => string;
+    table?: (header: string, body: string) => string;
+    tablerow?: (content: string) => string;
+    tablecell?: (content: string, flags: unknown) => string;
+    hr?: () => string;
+    html?: (html: string) => string;
+    image?: (href: string, title: string | null, text: string) => string;
+    firstHeading?: boolean;
+    showSectionPrefix?: boolean;
+    unescape?: boolean;
+    width?: number;
+    reflowText?: boolean;
+    tab?: number;
+  }
+
+  export function markedTerminal(options?: MarkedTerminalOptions): MarkedExtension;
+}

package/src/types.ts

@@ -0,0 +1,170 @@
+// Error types for proper error handling
+export class SpiralCliError extends Error {
+  constructor(
+    message: string,
+    public readonly exitCode: number = 1,
+  ) {
+    super(message);
+    this.name = "SpiralCliError";
+  }
+}
+
+export class AuthenticationError extends SpiralCliError {
+  constructor(message: string) {
+    super(message, 2); // Exit code 2 for auth errors
+    this.name = "AuthenticationError";
+  }
+}
+
+export class ApiError extends SpiralCliError {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly body?: unknown,
+  ) {
+    super(message, 3); // Exit code 3 for API errors
+    this.name = "ApiError";
+  }
+}
+
+export class NetworkError extends SpiralCliError {
+  constructor(message: string) {
+    super(message, 4); // Exit code 4 for network errors
+    this.name = "NetworkError";
+  }
+}
+
+// SSE Event types (aligned with apps/web/src/types/sse.ts)
+export interface ToolCall {
+  tool_name: string;
+  tool_call_id?: string;
+  call_id?: string;
+  tool_args?: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+  status: "started" | "arguments_delta" | "arguments_done" | "completed";
+}
+
+export interface StreamEvent {
+  type: "content" | "thinking" | "tool_call" | "session_name" | "retry" | "complete" | "error";
+  content?: string;
+  thinking?: string;
+  toolCall?: ToolCall;
+  sessionId?: string;
+  sessionName?: string;
+  retryInfo?: { attempt: number; maxRetries: number; message: string };
+  model?: string;
+}
+
+// Output formatters for agent-native support
+export interface OutputFormatter {
+  content(text: string): void;
+  thinking(text: string): void;
+  error(error: Error): void;
+  complete(sessionId: string): void;
+}
+
+// Conversation types from API
+export interface Conversation {
+  session_id: string;
+  user_id: string;
+  session_name: string | null;
+  workspace_id: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface Message {
+  id: string;
+  role: string;
+  content: string;
+  thinking?: string;
+  created_at: string;
+  updated_at?: string;
+  is_complete?: boolean;
+  model?: string;
+  provider?: string;
+}
+
+// Draft types (from backend)
+export interface Draft {
+  id: string;
+  session_id: string;
+  user_id: string;
+  title?: string;
+  content: string;
+  content_hash: string;
+  current_version_id?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface DraftVersion {
+  id: string;
+  draft_id: string;
+  content: string;
+  content_hash: string;
+  created_by: "user" | "llm";
+  parent_version_id?: string;
+  created_at: string;
+}
+
+// Suggestion types (parsed from responses)
+export interface Suggestion {
+  id: string;
+  targetDraftId: string;
+  before: string;
+  after: string;
+  rationale?: string;
+  range?: [number, number];
+  status: "pending" | "applied" | "dismissed";
+}
+
+// Writing style types
+export interface WritingStyle {
+  id: string;
+  name: string;
+  description?: string;
+  usage_context?: string;
+  guide?: string;
+  summary?: string;
+}
+
+// Workspace types
+export interface Workspace {
+  id: string;
+  name: string;
+  icon?: string;
+  icon_color?: string;
+  description?: string;
+  workspace_type: "PERSONAL" | "TEAM";
+  owner_id: string;
+  team_id?: string;
+}
+
+// Attachment types
+export interface Attachment {
+  name: string;
+  content: string; // Text content or base64 for binary
+  type: "text" | "binary";
+  size: number;
+  mimeType?: string;
+}
+
+// Patch operation for draft updates
+export interface PatchOperation {
+  type: "replace" | "insert" | "delete";
+  range?: [number, number];
+  content?: string;
+}
+
+// Tool call update for visualization
+export interface ToolCallUpdate {
+  callId: string;
+  toolName: string;
+  status: "started" | "arguments_delta" | "arguments_done" | "completed" | "error";
+  args?: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+  formattedCalls?: string[];
+}

package/src/workspaces/index.ts

@@ -0,0 +1,55 @@
+// Workspace management
+import chalk from "chalk";
+import ora from "ora";
+import { fetchWorkspaces } from "../api";
+import { theme } from "../theme";
+
+export interface WorkspaceCommandOptions {
+  json?: boolean;
+}
+
+/**
+ * List all available workspaces
+ */
+export async function listWorkspaces(options: WorkspaceCommandOptions): Promise<void> {
+  const spinner = ora("Fetching workspaces...").start();
+
+  try {
+    const workspaces = await fetchWorkspaces();
+    spinner.succeed("Workspaces loaded");
+
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, workspaces }));
+      return;
+    }
+
+    if (workspaces.length === 0) {
+      console.log(theme.dim("No workspaces found."));
+      return;
+    }
+
+    console.log(theme.heading("\nWorkspaces:\n"));
+
+    // Group by type (case-insensitive comparison)
+    const personal = workspaces.filter((w) => w.workspace_type?.toLowerCase() === "personal");
+    const team = workspaces.filter((w) => w.workspace_type?.toLowerCase() === "team");
+
+    if (personal.length > 0) {
+      console.log(theme.info("Personal:"));
+      for (const ws of personal) {
+        console.log(`  ${theme.dim(ws.id.slice(0, 8))} ${chalk.white(ws.name)}`);
+      }
+      console.log();
+    }
+
+    if (team.length > 0) {
+      console.log(theme.info("Team:"));
+      for (const ws of team) {
+        console.log(`  ${theme.dim(ws.id.slice(0, 8))} ${chalk.white(ws.name)}`);
+      }
+    }
+  } catch (error) {
+    spinner.fail("Failed to fetch workspaces");
+    throw error;
+  }
+}