Fixes #239: Add file system events example

packages/core/README.md

@@ -7,6 +7,7 @@ Orchestrate complex, long-running coding tasks to an ephemeral cloud environment
 ## Examples
 
 - [Basic Session](./examples/basic-session/README.md)
+- [File System Events](./examples/file-system-events/README.md)
 - [Advanced Session](./examples/advanced-session/README.md)
 - [Agent Workflow](./examples/agent/README.md)
 - [Webhook Integration](./examples/webhook/README.md)

packages/core/examples/file-system-events/README.md

@@ -0,0 +1,26 @@
+# File System Events Example
+
+This example demonstrates how to use the Jules TypeScript SDK in an event-driven workflow. It uses `chokidar` to monitor local file system events (e.g., when a file is added or changed) and automatically triggers a Jules coding session.
+
+## Prerequisites
+
+- Bun installed
+- A valid `JULES_API_KEY` exported in your environment.
+
+## Running the Example
+
+1. Install dependencies from the monorepo root:
+   ```bash
+   bun install
+   ```
+2. Start the watcher:
+   ```bash
+   bun run start
+   ```
+3. Trigger a file system event by modifying a file in the watched directory (e.g., creating `watched-directory/test.txt`):
+   ```bash
+   mkdir -p watched-directory
+   touch watched-directory/test.txt
+   ```
+
+The watcher will detect the file change and automatically trigger a Jules session based on the contents of the changed file.

packages/core/examples/file-system-events/index.ts

@@ -0,0 +1,80 @@
+import { jules } from '@google/jules-sdk';
+import chokidar from 'chokidar';
+import fs from 'fs/promises';
+import path from 'path';
+
+// The directory to watch for file system events
+const WATCH_DIR = path.join(process.cwd(), 'watched-directory');
+
+// Utility to create the watched directory if it doesn't exist
+async function ensureDir(dir: string) {
+  try {
+    await fs.access(dir);
+  } catch {
+    await fs.mkdir(dir, { recursive: true });
+  }
+}
+
+async function handleFileEvent(event: string, filepath: string) {
+  console.log(`\nDetected '${event}' event on file: ${filepath}`);
+
+  try {
+    // Read the contents of the changed file
+    const content = await fs.readFile(filepath, 'utf-8');
+
+    console.log(`Initiating Jules session based on file content...`);
+
+    // Initiate a Jules session with the file content
+    const session = await jules.session({
+      prompt: `A file was ${event} in the watched directory.
+
+      File path: ${filepath}
+      File content:
+      \`\`\`
+      ${content}
+      \`\`\`
+
+      Please review the content and suggest any improvements or note what this file is about.`,
+      // Provide a default repository or adapt to your needs
+      source: { github: 'davideast/dataprompt', baseBranch: 'main' },
+    });
+
+    console.log(`Created Jules session: ${session.id}`);
+
+    // Wait for the final outcome of the session
+    const outcome = await session.result();
+    console.log(`Session finished with state: ${outcome.state}`);
+
+  } catch (error) {
+    console.error(`Error handling file event for ${filepath}:`, error);
+  }
+}
+
+async function main() {
+  await ensureDir(WATCH_DIR);
+
+  console.log(`Watching for file changes in: ${WATCH_DIR}`);
+
+  // Initialize watcher
+  // We ignore initial add events to avoid triggering sessions for existing files on startup
+  const watcher = chokidar.watch(WATCH_DIR, {
+    ignored: /(^|[\/\\])\../, // ignore dotfiles
+    persistent: true,
+    ignoreInitial: true,
+  });
+
+  // Attach event listeners
+  watcher
+    .on('add', (path) => handleFileEvent('added', path))
+    .on('change', (path) => handleFileEvent('changed', path))
+    .on('error', (error) => console.error(`Watcher error: ${error}`));
+
+  // Handle graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('Shutting down file watcher...');
+    watcher.close();
+    process.exit(0);
+  });
+}
+
+main().catch(console.error);

packages/core/examples/file-system-events/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "file-system-events",
+  "version": "1.0.0",
+  "description": "Example demonstrating how to trigger a Jules session from file system events using chokidar.",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "start": "bun run index.ts"
+  },
+  "dependencies": {
+    "@google/jules-sdk": "workspace:*",
+    "chokidar": "^5.0.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.1.8"
+  }
+}