@liquidmetal-ai/raindrop-code 0.0.6 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidmetal-ai/raindrop-code",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "AI-powered terminal coding assistant with deep code understanding, file operations, and extensible tools",
   "keywords": [
     "ai",
@@ -35,15 +35,17 @@
   "bin": {
     "raindrop-code": "bin/raindrop-code"
   },
+  "types": "types/index.d.ts",
   "files": [
     "install.js",
     "README.md",
-    "bin/"
+    "bin/",
+    "types/"
   ],
   "optionalDependencies": {
-    "@liquidmetal-ai/raindrop-code-darwin-universal": "0.0.6",
-    "@liquidmetal-ai/raindrop-code-linux-x64": "0.0.6",
-    "@liquidmetal-ai/raindrop-code-linux-arm64": "0.0.6",
-    "@liquidmetal-ai/raindrop-code-win32-x64": "0.0.6"
+    "@liquidmetal-ai/raindrop-code-darwin-universal": "0.0.8",
+    "@liquidmetal-ai/raindrop-code-linux-x64": "0.0.8",
+    "@liquidmetal-ai/raindrop-code-linux-arm64": "0.0.8",
+    "@liquidmetal-ai/raindrop-code-win32-x64": "0.0.8"
   }
 }

package/types/bash.d.ts

@@ -0,0 +1,55 @@
+declare module '@liquidmetal-ai/raindrop-code/bash' {
+  /**
+   * Options for bash command execution
+   */
+  export interface BashOptions {
+    /** Working directory for command execution */
+    cwd?: string;
+    /** Timeout in seconds */
+    timeout?: number;
+    /** Run command in background (don't wait for completion) */
+    background?: boolean;
+  }
+
+  /**
+   * Result from bash command execution
+   */
+  export interface BashResult {
+    /** Standard output */
+    output: string;
+    /** Standard error */
+    error: string;
+    /** Exit code */
+    exitCode: number;
+    /** Whether command succeeded (exit code 0) */
+    success: boolean;
+  }
+
+  /**
+   * Execute a shell command.
+   * 
+   * @param command - Shell command to execute
+   * @param opts - Optional execution options
+   * @returns Promise resolving to execution result
+   * 
+   * @example
+   * ```typescript
+   * const result = await run('ls -la');
+   * if (result.success) {
+   *   console.log(result.output);
+   * } else {
+   *   console.error(result.error);
+   * }
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // With options
+   * const result = await run('npm test', {
+   *   cwd: './project',
+   *   timeout: 300
+   * });
+   * ```
+   */
+  export function run(command: string, opts?: BashOptions): Promise<BashResult>;
+}

package/types/control.d.ts

@@ -0,0 +1,126 @@
+declare module '@liquidmetal-ai/raindrop-code/control' {
+  /**
+   * Options for passing control to AI
+   */
+  export interface PassToAIOptions {
+    /** The prompt to send to the AI */
+    prompt: string;
+    /** Signal name to wait for from session_control tool */
+    untilSignal: string;
+    /** Timeout in seconds (default: 3600) */
+    timeout?: number;
+    /** Optional: Specific tools to enable for this AI session */
+    tools?: string[];
+    /** Optional: Specific skills to enable for this AI session */
+    skills?: string[];
+  }
+
+  /**
+   * Data returned from AI via session_control signal
+   */
+  export type SignalData = Record<string, any>;
+
+  /**
+   * Options for passing control to user
+   */
+  export interface PassToUserOptions {
+    /** Message to display to the user */
+    message: string;
+    /** Available actions for the user to choose from */
+    actions: string[];
+  }
+
+  /**
+   * Options for passing control to another coordinator
+   */
+  export interface PassToCoordinatorOptions {
+    /** Name of the coordinator to execute */
+    coordinator: string;
+    /** Input data to pass to the coordinator */
+    input: Record<string, any>;
+  }
+
+  /**
+   * Pass control to AI by sending a prompt and waiting for a signal.
+   * 
+   * The AI must use the session_control tool to send back the expected signal:
+   * ```xml
+   * <tool_use>
+   *   <name>session_control</name>
+   *   <input>
+   *     <signal>your_signal_name</signal>
+   *     <data>
+   *       <key>value</key>
+   *     </data>
+   *   </input>
+   * </tool_use>
+   * ```
+   * 
+   * @param opts - Options for the AI session
+   * @returns Promise resolving to the signal data sent by AI
+   * 
+   * @example
+   * ```typescript
+   * const result = await passToAI({
+   *   prompt: 'Analyze this code and signal when done',
+   *   untilSignal: 'analysis_complete',
+   *   timeout: 300
+   * });
+   * console.log(result.findings);
+   * ```
+   */
+  export function passToAI(opts: PassToAIOptions): Promise<SignalData>;
+
+  /**
+   * Pass control to the user for manual input/decision.
+   * 
+   * @param opts - Options for user interaction
+   * @returns Promise resolving to the user's selected action or entered text
+   * 
+   * @example
+   * ```typescript
+   * // Choice selection (default)
+   * const choice = await passToUser({
+   *   message: 'How should we proceed?',
+   *   type: 'choice',
+   *   actions: ['Continue', 'Skip', 'Abort']
+   * });
+   * if (choice === 'Abort') {
+   *   return { success: false };
+   * }
+   * 
+   * // Freeform text input
+   * const name = await passToUser({
+   *   message: 'What is your project name?',
+   *   type: 'text',
+   *   placeholder: 'my-project'
+   * });
+   * ```
+   */
+  export function passToUser(opts: PassToUserOptions): Promise<string>;
+
+  /**
+   * Pass control to another coordinator.
+   * 
+   * @param opts - Options for coordinator execution
+   * @returns Promise resolving to the coordinator's result
+   * 
+   * @example
+   * ```typescript
+   * const result = await passToCoordinator({
+   *   coordinator: 'helper-coordinator',
+   *   input: { task: 'process data' }
+   * });
+   * ```
+   */
+  export function passToCoordinator(opts: PassToCoordinatorOptions): Promise<Record<string, any>>;
+
+  /**
+   * Get the current control state.
+   * 
+   * @returns The current state ('coordinator', 'ai', or 'user')
+   */
+  export function current(): string;
+}
+tring;
+}

package/types/files.d.ts

@@ -0,0 +1,118 @@
+declare module '@liquidmetal-ai/raindrop-code/files' {
+  /**
+   * Read a file's contents as a string.
+   * Paths are resolved relative to the working directory.
+   * 
+   * @param path - Path to the file (relative or absolute)
+   * @returns Promise resolving to file contents
+   * 
+   * @example
+   * ```typescript
+   * const content = await read('config.json');
+   * ```
+   */
+  export function read(path: string): Promise<string>;
+
+  /**
+   * Write content to a file.
+   * Creates parent directories if needed.
+   * 
+   * @param path - Path to the file (relative or absolute)
+   * @param content - Content to write
+   * @returns Promise resolving when write completes
+   * 
+   * @example
+   * ```typescript
+   * await write('output.txt', 'Hello, world!');
+   * ```
+   */
+  export function write(path: string, content: string): Promise<void>;
+
+  /**
+   * Append content to a file.
+   * Creates the file if it doesn't exist.
+   * 
+   * @param path - Path to the file (relative or absolute)
+   * @param content - Content to append
+   * @returns Promise resolving when append completes
+   * 
+   * @example
+   * ```typescript
+   * await append('log.txt', 'New log entry\n');
+   * ```
+   */
+  export function append(path: string, content: string): Promise<void>;
+
+  /**
+   * Read a JSON file and parse it.
+   * 
+   * @param path - Path to the JSON file
+   * @returns Promise resolving to parsed JSON object
+   * 
+   * @example
+   * ```typescript
+   * const config = await readJSON('config.json');
+   * console.log(config.version);
+   * ```
+   */
+  export function readJSON(path: string): Promise<Record<string, any>>;
+
+  /**
+   * Write data to a JSON file with pretty formatting.
+   * Creates parent directories if needed.
+   * 
+   * @param path - Path to the JSON file
+   * @param data - Data to write
+   * @returns Promise resolving when write completes
+   * 
+   * @example
+   * ```typescript
+   * await writeJSON('data.json', { results: [1, 2, 3] });
+   * ```
+   */
+  export function writeJSON(path: string, data: Record<string, any>): Promise<void>;
+
+  /**
+   * Check if a file or directory exists.
+   * 
+   * @param path - Path to check
+   * @returns Promise resolving to true if exists, false otherwise
+   * 
+   * @example
+   * ```typescript
+   * if (await exists('config.json')) {
+   *   const config = await readJSON('config.json');
+   * }
+   * ```
+   */
+  export function exists(path: string): Promise<boolean>;
+
+  /**
+   * List contents of a directory.
+   * 
+   * @param path - Path to directory
+   * @returns Promise resolving to array of file/directory names
+   * 
+   * @example
+   * ```typescript
+   * const files = await list('src/');
+   * for (const file of files) {
+   *   console.log(file);
+   * }
+   * ```
+   */
+  export function list(path: string): Promise<string[]>;
+
+  /**
+   * Delete a file.
+   * 
+   * @param path - Path to file
+   * @returns Promise resolving when deletion completes
+   * 
+   * @example
+   * ```typescript
+   * await del('temp.txt');
+   * ```
+   */
+  export function del(path: string): Promise<void>;
+}

package/types/git.d.ts

@@ -0,0 +1,99 @@
+declare module '@liquidmetal-ai/raindrop-code/git' {
+  /**
+   * Git repository status
+   */
+  export interface GitStatus {
+    /** List of modified files */
+    modified: string[];
+    /** List of added files */
+    added: string[];
+    /** List of deleted files */
+    deleted: string[];
+    /** List of untracked files */
+    untracked: string[];
+  }
+
+  /**
+   * Commit changes to git.
+   * Optionally add files before committing.
+   * 
+   * @param message - Commit message
+   * @param files - Optional array of files to add before committing
+   * @returns Promise resolving when commit completes
+   * 
+   * @example
+   * ```typescript
+   * await commit('Add new feature', ['src/feature.ts']);
+   * ```
+   */
+  export function commit(message: string, files?: string[]): Promise<void>;
+
+  /**
+   * Get git log entries.
+   * 
+   * @param count - Number of log entries to retrieve
+   * @returns Promise resolving to log output
+   * 
+   * @example
+   * ```typescript
+   * const log = await getLog(10);
+   * console.log(log);
+   * ```
+   */
+  export function log(count: number): Promise<string>;
+
+  /**
+   * Get git repository status.
+   * 
+   * @returns Promise resolving to status object
+   * 
+   * @example
+   * ```typescript
+   * const status = await getStatus();
+   * if (status.modified.length > 0) {
+   *   console.log('Modified files:', status.modified);
+   * }
+   * ```
+   */
+  export function status(): Promise<GitStatus>;
+
+  /**
+   * Add files to git staging area.
+   * 
+   * @param files - Array of file paths to add
+   * @returns Promise resolving when add completes
+   * 
+   * @example
+   * ```typescript
+   * await add(['src/main.ts', 'README.md']);
+   * ```
+   */
+  export function add(files: string[]): Promise<void>;
+
+  /**
+   * Get current git branch name.
+   * 
+   * @returns Promise resolving to branch name
+   * 
+   * @example
+   * ```typescript
+   * const branch = await getBranch();
+   * console.log('Current branch:', branch);
+   * ```
+   */
+  export function branch(): Promise<string>;
+
+  /**
+   * Get git diff output.
+   * 
+   * @param files - Optional array of files to diff (if empty, diffs all changes)
+   * @returns Promise resolving to diff output
+   * 
+   * @example
+   * ```typescript
+   * const diff = await getDiff(['src/main.ts']);
+   * console.log(diff);
+   * ```
+   */
+  export function diff(files?: string[]): Promise<string>;
+}

package/types/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * TypeScript definitions for Raindrop Code coordinator runtime APIs.
+ * 
+ * These modules are provided by the Raindrop Code runtime and are available
+ * when writing coordinators. They do not exist as real npm packages, but are
+ * injected at runtime by the Go coordinator executor.
+ * 
+ * @packageDocumentation
+ */
+
+// Re-export all modules for convenience
+export * from '@liquidmetal-ai/raindrop-code/control';
+export * from '@liquidmetal-ai/raindrop-code/files';
+export * from '@liquidmetal-ai/raindrop-code/git';
+export * from '@liquidmetal-ai/raindrop-code/bash';
+export * from '@liquidmetal-ai/raindrop-code/ui';
+export * from '@liquidmetal-ai/raindrop-code/log';
+export * from '@liquidmetal-ai/raindrop-code/state';
+export * from '@liquidmetal-ai/raindrop-code/runtime';
+export * from '@liquidmetal-ai/raindrop-code/resumable';

package/types/log.d.ts

@@ -0,0 +1,58 @@
+declare module '@liquidmetal-ai/raindrop-code/log' {
+  /**
+   * Metadata to include with log messages
+   */
+  export type LogMetadata = Record<string, any>;
+
+  /**
+   * Log an info message.
+   * 
+   * @param message - Message to log
+   * @param metadata - Optional metadata to include
+   * 
+   * @example
+   * ```typescript
+   * info('Processing started', { fileCount: 10 });
+   * ```
+   */
+  export function info(message: string, metadata?: LogMetadata): void;
+
+  /**
+   * Log a warning message.
+   * 
+   * @param message - Message to log
+   * @param metadata - Optional metadata to include
+   * 
+   * @example
+   * ```typescript
+   * warn('Deprecated API used', { api: 'oldFunction' });
+   * ```
+   */
+  export function warn(message: string, metadata?: LogMetadata): void;
+
+  /**
+   * Log an error message.
+   * 
+   * @param message - Message to log
+   * @param metadata - Optional metadata to include
+   * 
+   * @example
+   * ```typescript
+   * error('Failed to connect', { host: 'example.com', port: 443 });
+   * ```
+   */
+  export function error(message: string, metadata?: LogMetadata): void;
+
+  /**
+   * Log a debug message.
+   * 
+   * @param message - Message to log
+   * @param metadata - Optional metadata to include
+   * 
+   * @example
+   * ```typescript
+   * debug('Cache hit', { key: 'user:123', ttl: 3600 });
+   * ```
+   */
+  export function debug(message: string, metadata?: LogMetadata): void;
+}

package/types/resumable.d.ts

@@ -0,0 +1,90 @@
+declare module '@liquidmetal-ai/raindrop-code/resumable' {
+  import { SignalData } from '@liquidmetal-ai/raindrop-code/control';
+
+  /**
+   * Context provided to resumable coordinator functions.
+   * Handles automatic checkpoint management and step execution.
+   */
+  export interface ResumableContext {
+    /**
+     * Execute a named step in the coordinator workflow.
+     * Automatically handles:
+     * - Skipping already-completed steps (returns cached result)
+     * - Resuming at the current checkpoint (returns signal data)
+     * - Executing new steps (runs function, saves checkpoint and result)
+     * 
+     * @param stepName - Unique name for this step
+     * @param fn - Async function to execute for this step
+     * @returns Promise resolving to the step's result
+     * 
+     * @example
+     * ```typescript
+     * const result = await ctx.step('greeting', async () => {
+     *   return await passToAI({
+     *     prompt: 'Greet the user...',
+     *     untilSignal: 'done'
+     *   });
+     * });
+     * ```
+     */
+    step<T = any>(stepName: string, fn: () => Promise<T>): Promise<T>;
+
+    /**
+     * Check if we're resuming from a checkpoint.
+     */
+    readonly isResuming: boolean;
+
+    /**
+     * The signal name we received when resuming (if any).
+     */
+    readonly resumeSignal?: string;
+
+    /**
+     * The signal data we received when resuming (if any).
+     */
+    readonly resumeData?: SignalData;
+
+    /**
+     * The original input passed to the coordinator.
+     */
+    readonly input: Record<string, any>;
+  }
+
+  /**
+   * Coordinator function that supports resumption.
+   */
+  export type ResumableCoordinator = (ctx: ResumableContext) => Promise<any>;
+
+  /**
+   * Wraps a coordinator function to make it resumable.
+   * 
+   * The wrapped function receives a context that provides automatic
+   * checkpoint management through ctx.step(). Each step is saved to
+   * state, allowing the coordinator to resume from the last checkpoint.
+   * 
+   * @param fn - The coordinator function to wrap
+   * @returns A coordinator main function that handles resume logic
+   * 
+   * @example
+   * ```typescript
+   * export const main = resumable(async (ctx) => {
+   *   const result1 = await ctx.step('greeting', async () => {
+   *     return await passToAI({ 
+   *       prompt: 'Greet the user...', 
+   *       untilSignal: 'done' 
+   *     });
+   *   });
+   *   
+   *   const result2 = await ctx.step('analysis', async () => {
+   *     return await passToAI({ 
+   *       prompt: `Analyze: ${result1}...`, 
+   *       untilSignal: 'done' 
+   *     });
+   *   });
+   *   
+   *   return { success: true, results: [result1, result2] };
+   * });
+   * ```
+   */
+  export function resumable(fn: ResumableCoordinator): (input: Record<string, any>) => Promise<any>;
+}

package/types/runtime.d.ts

@@ -0,0 +1,46 @@
+declare module '@liquidmetal-ai/raindrop-code/runtime' {
+  /**
+   * Get the current context usage as a decimal (0.0 to 1.0).
+   * Useful for monitoring context window usage and deciding when to clear context.
+   * 
+   * @returns Context usage from 0.0 (empty) to 1.0 (full)
+   * 
+   * @example
+   * ```typescript
+   * if (contextUsage() > 0.75) {
+   *   console.log('Context usage high, consider clearing');
+   * }
+   * ```
+   */
+  export function contextUsage(): number;
+
+  /**
+   * Clear the conversation context.
+   * Removes all messages from the conversation history (system prompt is preserved).
+   * Use this in long-running coordinators to prevent context overflow.
+   * 
+   * After clearing, you may want to re-inject important context.
+   * 
+   * @returns Promise resolving when context is cleared
+   * 
+   * @example
+   * ```typescript
+   * // In a long-running loop
+   * for (const item of largeDataset) {
+   *   if (contextUsage() > 0.75) {
+   *     const summary = buildSummary();
+   *     await clearContext();
+   *     
+   *     // Re-inject summary
+   *     await passToAI({
+   *       prompt: `Context was cleared. Here's what we've done so far:\n${summary}`,
+   *       untilSignal: 'acknowledged'
+   *     });
+   *   }
+   *   
+   *   // Process item...
+   * }
+   * ```
+   */
+  export function clearContext(): Promise<void>;
+}

package/types/state.d.ts

@@ -0,0 +1,72 @@
+declare module '@liquidmetal-ai/raindrop-code/state' {
+  /**
+   * Get a value from coordinator state.
+   * Returns the default value if the key doesn't exist.
+   * 
+   * @param key - State key
+   * @param defaultValue - Default value if key doesn't exist
+   * @returns Promise resolving to the value or default
+   * 
+   * @example
+   * ```typescript
+   * const count = await get('processedCount', 0);
+   * console.log('Processed:', count);
+   * ```
+   */
+  export function get<T = any>(key: string, defaultValue: T): Promise<T>;
+
+  /**
+   * Set a value in coordinator state.
+   * State is persisted to disk and survives coordinator restarts.
+   * 
+   * @param key - State key
+   * @param value - Value to store
+   * @returns Promise resolving when state is saved
+   * 
+   * @example
+   * ```typescript
+   * await set('processedCount', 42);
+   * await set('results', { success: true, data: [...] });
+   * ```
+   */
+  export function set(key: string, value: any): Promise<void>;
+
+  /**
+   * Delete a key from coordinator state.
+   * 
+   * @param key - State key to delete
+   * @returns Promise resolving when deletion completes
+   * 
+   * @example
+   * ```typescript
+   * await del('temporaryData');
+   * ```
+   */
+  export function del(key: string): Promise<void>;
+
+  /**
+   * Clear all coordinator state.
+   * 
+   * @returns Promise resolving when state is cleared
+   * 
+   * @example
+   * ```typescript
+   * // At the start of coordinator
+   * await clear();
+   * ```
+   */
+  export function clear(): Promise<void>;
+
+  /**
+   * Get all keys in coordinator state.
+   * 
+   * @returns Promise resolving to array of keys
+   * 
+   * @example
+   * ```typescript
+   * const keys = await getKeys();
+   * console.log('State keys:', keys);
+   * ```
+   */
+  export function keys(): Promise<string[]>;
+}

package/types/ui.d.ts

@@ -0,0 +1,61 @@
+declare module '@liquidmetal-ai/raindrop-code/ui' {
+  /**
+   * Show a status message in the UI.
+   * 
+   * @param message - Status message to display
+   * 
+   * @example
+   * ```typescript
+   * showStatus('Processing data...');
+   * ```
+   */
+  export function showStatus(message: string): void;
+
+  /**
+   * Show a progress message in the UI.
+   * 
+   * @param message - Progress message to display
+   * 
+   * @example
+   * ```typescript
+   * showProgress('Step 2/5: Analyzing code...');
+   * ```
+   */
+  export function showProgress(message: string): void;
+
+  /**
+   * Show a success message in the UI.
+   * 
+   * @param message - Success message to display
+   * 
+   * @example
+   * ```typescript
+   * showSuccess('Task completed successfully!');
+   * ```
+   */
+  export function showSuccess(message: string): void;
+
+  /**
+   * Show an error message in the UI.
+   * 
+   * @param message - Error message to display
+   * 
+   * @example
+   * ```typescript
+   * showError('Failed to process file');
+   * ```
+   */
+  export function showError(message: string): void;
+
+  /**
+   * Show a warning message in the UI.
+   * 
+   * @param message - Warning message to display
+   * 
+   * @example
+   * ```typescript
+   * showWarning('Configuration file not found, using defaults');
+   * ```
+   */
+  export function showWarning(message: string): void;
+}