@plotday/twister 0.20.0

package/bin/utils/token.js

@@ -0,0 +1,75 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGlobalTokenPath = getGlobalTokenPath;
+exports.getToken = getToken;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * Get the path to the global token file.
+ *
+ * @returns The path to the global token file
+ */
+function getGlobalTokenPath() {
+    const homeDir = os.homedir();
+    if (process.platform === "win32") {
+        // Windows: Use APPDATA
+        const appData = process.env.APPDATA || path.join(homeDir, "AppData", "Roaming");
+        return path.join(appData, "plot", "token");
+    }
+    else {
+        // Unix-like: Use ~/.config/plot/token
+        return path.join(homeDir, ".config", "plot", "token");
+    }
+}
+/**
+ * Read the authentication token from the global token file.
+ *
+ * @returns The token string if found, null otherwise
+ */
+async function getToken() {
+    const globalTokenPath = getGlobalTokenPath();
+    if (fs.existsSync(globalTokenPath)) {
+        try {
+            return fs.readFileSync(globalTokenPath, "utf-8").trim();
+        }
+        catch (error) {
+            console.warn(`Warning: Failed to read global token file: ${globalTokenPath}`);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=token.js.map

package/bin/utils/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../cli/utils/token.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AASA,gDAUC;AAOD,4BAYC;AAtCD,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAE7B;;;;GAIG;AACH,SAAgB,kBAAkB;IAChC,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,uBAAuB;QACvB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAChF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,sCAAsC;QACtC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,QAAQ;IAC5B,MAAM,eAAe,GAAG,kBAAkB,EAAE,CAAC;IAC7C,IAAI,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAC1D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CACV,8CAA8C,eAAe,EAAE,CAChE,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/cli/templates/AGENTS.template.md

@@ -0,0 +1,403 @@
+# Twist Implementation Guide for LLMs
+
+This document provides context for AI assistants generating or modifying twists.
+
+## Architecture Overview
+
+Plot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.
+
+### Runtime Environment
+
+**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:
+
+- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.
+- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)
+- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`
+- **Break long operations**: Split large operations into smaller batches that can be processed independently
+- **Store intermediate state**: Use the Store tool to persist state between batches
+- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations
+
+## twist Structure Pattern
+
+```typescript
+import {
+  type Activity,
+  twist,
+  type Priority,
+  type ToolBuilder,
+} from "@plotday/twister";
+import { Plot } from "@plotday/twister/tools/plot";
+
+export default class MyTwist extends twist<MyTwist> {
+  build(build: ToolBuilder) {
+    return {
+      plot: build(Plot),
+    };
+  }
+
+  async activate(priority: Pick<Priority, "id">) {
+    // Called when twist is enabled for a priority
+    // Common actions: request auth, create setup activities
+  }
+
+  async activity(activity: Activity) {
+    // Called when an activity is routed to this twist
+    // Common actions: process external events, update activities
+  }
+}
+```
+
+## Tool System
+
+### Accessing Tools
+
+All tools are declared in the `build` method:
+
+```typescript
+build(build: ToolBuilder) {
+  return {
+    toolName: build(ToolClass),
+  };
+}
+```
+
+All `build()` calls must occur in the `build` method as they are used for dependency analysis.
+
+IMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.
+
+### Built-in Tools (Always Available)
+
+For complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.
+
+**Quick reference - Available tools:**
+
+- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)
+- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)
+  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)
+- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)
+- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)
+- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)
+- `@plotday/twister/tools/integrations` - OAuth2 authentication flows
+- `@plotday/twister/tools/network` - HTTP access permissions and webhook management
+- `@plotday/twister/tools/twists` - Manage other Twists
+
+**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.
+
+### External Tools (Add to package.json)
+
+Add tool dependencies to `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@plotday/twister": "workspace:^",
+    "@plotday/tool-google-calendar": "workspace:^"
+  }
+}
+```
+
+#### Common External Tools
+
+- `@plotday/tool-google-calendar`: Google Calendar integration
+- `@plotday/tool-outlook-calendar`: Outlook Calendar integration
+- `@plotday/tool-google-contacts`: Google Contacts integration
+
+## Lifecycle Methods
+
+### activate(priority: Pick<Priority, "id">)
+
+Called when the twist is enabled for a priority. Common patterns:
+
+**Request Authentication:**
+
+```typescript
+async activate(_priority: Pick<Priority, "id">) {
+  const authLink = await this.tools.externalTool.requestAuth(
+    this.onAuthComplete,
+    "google"
+  );
+
+  await this.tools.plot.createActivity({
+    type: ActivityType.Task,
+    title: "Connect your account",
+    links: [authLink],
+  });
+}
+```
+
+**Store Parent Activity for Later:**
+
+```typescript
+const activity = await this.tools.plot.createActivity({
+  type: ActivityType.Task,
+  title: "Setup",
+});
+
+await this.set("setup_activity_id", activity.id);
+```
+
+### activity(activity: Activity)
+
+Called when an activity is routed to the twist. Common patterns:
+
+**Create Activities from External Events:**
+
+```typescript
+async activity(activity: Activity) {
+  await this.tools.plot.createActivity(activity);
+}
+```
+
+**Update Based on User Action:**
+
+```typescript
+async activity(activity: Activity) {
+  if (activity.completed) {
+    await this.handleCompletion(activity);
+  }
+}
+```
+
+## Activity Links
+
+Activity links enable user interaction:
+
+```typescript
+import { type ActivityLink, ActivityLinkType } from "@plotday/twister";
+
+// URL link
+const urlLink: ActivityLink = {
+  title: "Open website",
+  type: ActivityLinkType.url,
+  url: "https://example.com",
+};
+
+// Callback link (uses Callbacks tool)
+const token = await this.callback(this.onLinkClicked, "context");
+const callbackLink: ActivityLink = {
+  title: "Click me",
+  type: ActivityLinkType.callback,
+  token: token,
+};
+
+// Add to activity
+await this.tools.plot.createActivity({
+  type: ActivityType.Task,
+  title: "Task with links",
+  links: [urlLink, callbackLink],
+});
+```
+
+## Authentication Pattern
+
+Common pattern for OAuth authentication:
+
+```typescript
+async activate(_priority: Pick<Priority, "id">) {
+  // Request auth link from tool with callback
+  const authLink = await this.tools.googleTool.requestAuth(
+    this.onAuthComplete,
+    "google"
+  );
+
+  // Create activity with auth link
+  const activity = await this.tools.plot.createActivity({
+    type: ActivityType.Task,
+    title: "Connect Google account",
+    links: [authLink],
+  });
+
+  // Store for later use
+  await this.set("auth_activity_id", activity.id);
+}
+
+async onAuthComplete(authResult: { authToken: string }, provider: string) {
+  // Store auth token
+  await this.set(`${provider}_auth`, authResult.authToken);
+
+  // Continue setup flow
+  await this.setupSyncOptions(authResult.authToken);
+}
+```
+
+## Sync Pattern
+
+Pattern for syncing external data with callbacks:
+
+```typescript
+async startSync(calendarId: string): Promise<void> {
+  const authToken = await this.get<string>("auth_token");
+
+  await this.tools.calendarTool.startSync(
+    authToken,
+    calendarId,
+    this.handleEvent,
+    calendarId
+  );
+}
+
+async handleEvent(activity: Activity, calendarId: string): Promise<void> {
+  // Process incoming event from external service
+  await this.tools.plot.createActivity(activity);
+}
+
+async stopSync(calendarId: string): Promise<void> {
+  const authToken = await this.get<string>("auth_token");
+  await this.tools.calendarTool.stopSync(authToken, calendarId);
+}
+```
+
+## Calendar Selection Pattern
+
+Pattern for letting users select from multiple calendars/accounts:
+
+```typescript
+private async createCalendarSelectionActivity(
+  provider: string,
+  calendars: Calendar[],
+  authToken: string
+): Promise<void> {
+  const links: ActivityLink[] = [];
+
+  for (const calendar of calendars) {
+    const token = await this.callback(
+      this.onCalendarSelected,
+      provider,
+      calendar.id,
+      calendar.name,
+      authToken
+    );
+
+    links.push({
+      title: `📅 ${calendar.name}${calendar.primary ? " (Primary)" : ""}`,
+      type: ActivityLinkType.callback,
+      token: token,
+    });
+  }
+
+  await this.tools.plot.createActivity({
+    type: ActivityType.Note,
+    title: "Which calendars would you like to connect?",
+    links,
+  });
+}
+
+async onCalendarSelected(
+  link: ActivityLink,
+  provider: string,
+  calendarId: string,
+  calendarName: string,
+  authToken: string
+): Promise<void> {
+  // Start sync for selected calendar
+  await this.tools.tool.startSync(
+    authToken,
+    calendarId,
+    this.handleEvent,
+    provider,
+    calendarId
+  );
+}
+```
+
+## Batch Processing Pattern
+
+**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.
+
+### Key Principles
+
+1. **Store state between batches**: Use the Store tool to persist progress
+2. **Queue next batch**: Use the Run tool to schedule the next chunk
+3. **Clean up when done**: Delete stored state after completion
+4. **Handle failures**: Store enough state to resume if a batch fails
+
+### Example Implementation
+
+```typescript
+async startSync(resourceId: string): Promise<void> {
+  // Initialize state in Store (persists between executions)
+  await this.set(`sync_state_${resourceId}`, {
+    nextPageToken: null,
+    batchNumber: 1,
+    itemsProcessed: 0,
+  });
+
+  // Queue first batch using runTask method
+  const callback = await this.callback(this.syncBatch, resourceId);
+  await this.runTask(callback);
+}
+
+async syncBatch(args: any, resourceId: string): Promise<void> {
+  // Load state from Store (set by previous execution)
+  const state = await this.get(`sync_state_${resourceId}`);
+
+  // Process one batch (keep under time limit)
+  const result = await this.fetchBatch(state.nextPageToken);
+
+  // Process results
+  for (const item of result.items) {
+    await this.tools.plot.createActivity(item);
+  }
+
+  if (result.nextPageToken) {
+    // Update state in Store for next batch
+    await this.set(`sync_state_${resourceId}`, {
+      nextPageToken: result.nextPageToken,
+      batchNumber: state.batchNumber + 1,
+      itemsProcessed: state.itemsProcessed + result.items.length,
+    });
+
+    // Queue next batch (runs in new execution context)
+    const nextCallback = await this.callback(this.syncBatch, resourceId);
+    await this.runTask(nextCallback);
+  } else {
+    // Cleanup when complete
+    await this.clear(`sync_state_${resourceId}`);
+
+    // Optionally notify user of completion
+    await this.tools.plot.createActivity({
+      type: ActivityType.Note,
+      note: `Sync complete: ${state.itemsProcessed + result.items.length} items processed`,
+    });
+  }
+}
+```
+
+## Error Handling
+
+Always handle errors gracefully and communicate them to users:
+
+```typescript
+try {
+  await this.externalOperation();
+} catch (error) {
+  console.error("Operation failed:", error);
+
+  await this.tools.plot.createActivity({
+    type: ActivityType.Note,
+    note: `Failed to complete operation: ${error.message}`,
+  });
+}
+```
+
+## Common Pitfalls
+
+- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.
+- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \`activity\` call. Be sure to check the \`changes === null\` and/or \`activity.author.id !== this.id\` to avoid re-processing.
+- Most activity should be `type = ActivityType.Note` with a `title` and `note`, and no `start` or `end`. This represents a typical message. `start` and `end` should only be used for a note if it should be displayed for a specific date or time, such as a birthday.
+- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.
+- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.
+- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.
+- **Store auth tokens** - Don't re-request authentication unnecessarily.
+- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.
+- **Handle missing auth gracefully** - Check for stored auth before operations.
+
+## Testing
+
+Before deploying, verify:
+
+1. Linting passes: `{{packageManager}} lint`
+2. All dependencies are in package.json
+3. Authentication flow works end-to-end
+4. Batch operations handle pagination correctly
+5. Error cases are handled gracefully

package/cli/templates/CLAUDE.template.md

@@ -0,0 +1 @@
+@AGENTS.md

package/cli/templates/README.template.md

@@ -0,0 +1,189 @@
+# {{displayName}} twist
+
+A Plot twist that [describe what your twist does].
+
+## Quick Start
+
+```bash
+# Install dependencies
+{{packageManager}} install
+
+# Lint your code
+{{packageManager}} lint
+
+# Deploy to Plot
+{{packageManager}} deploy
+```
+
+## Development
+
+### Project Structure
+
+```
+.
+├── src/
+│   └── index.ts      # Main twist implementation
+├── package.json      # twist metadata and dependencies
+├── tsconfig.json     # TypeScript configuration
+└── README.md         # This file
+```
+
+### twist Lifecycle
+
+Your twist implements two key lifecycle methods:
+
+#### `activate(priority: Pick<Priority, "id">)`
+
+Called when the twist is enabled for a priority. This is where you typically:
+- Request authentication from external services
+- Create initial setup activities
+- Initialize twist state
+
+#### `activity(activity: Activity)`
+
+Called when an activity is routed to this twist. Use this to:
+- Process incoming activities
+- Create new activities based on external events
+- Update existing activities
+
+### Using Tools
+
+Twists access functionality through tools. Declare tools in the `build` method:
+
+```typescript
+build(build: ToolBuilder) {
+  return {
+    plot: build(Plot),
+  };
+}
+// Store, Tasks, and Callbacks methods are available directly via this
+```
+
+#### Built-in Tools
+
+- **Plot**: Create, update, and delete activities
+- **Store**: Persist data across twist invocations
+- **Integrations**: Request OAuth authentication from external services
+- **Tasks**: Queue background tasks and batch operations
+- **Callbacks**: Create persistent function references for webhooks
+- **Network**: HTTP access permissions and webhook management
+
+#### External Tools
+
+Add external tool dependencies to `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@plotday/twister": "workspace:^",
+    "@plotday/tool-google-calendar": "workspace:^"
+  }
+}
+```
+
+Then use them in your twist:
+
+```typescript
+import GoogleCalendarTool from "@plotday/tool-google-calendar";
+
+build(build: ToolBuilder) {
+  return {
+    googleCalendar: build(GoogleCalendarTool),
+  };
+}
+```
+
+### Activity Types
+
+Plot supports three activity types:
+
+- **ActivityType.Note**: Information without actionable requirements
+- **ActivityType.Task**: Actionable items that can be completed
+- **ActivityType.Event**: Scheduled occurrences with start/end times
+
+### State Management
+
+Use Store methods (available directly on twist and Tool classes) to persist data across twist invocations:
+
+```typescript
+// Save state
+await this.set("sync_token", token);
+
+// Load state
+const token = await this.get<string>("sync_token");
+```
+
+**Important**: twist instances are ephemeral. Always use Store methods for data that needs to persist.
+
+### Runtime Limitations
+
+**Important**: All twist and tool functions are executed in a sandboxed, ephemeral environment with limited resources:
+
+- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.
+- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)
+- **Use the Tasks tool**: Queue separate chunks of work with `this.run(callback)`
+- **Break long operations**: Split large operations into smaller batches that can be processed independently
+- **Store intermediate state**: Use the Store tool to persist state between batches
+- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations
+
+#### Pattern for Long-Running Operations
+
+```typescript
+async startSync(calendarId: string): Promise<void> {
+  // Initialize state in Store (persists between executions)
+  await this.set(`sync_state_${calendarId}`, {
+    nextPageToken: null,
+    batchNumber: 1,
+  });
+
+  // Queue first batch using run method
+  const callback = await this.callback("syncBatch", { calendarId });
+  await this.run(callback);
+}
+
+async syncBatch(args: any, context: { calendarId: string }): Promise<void> {
+  // Load state from Store
+  const state = await this.get(`sync_state_${calendarId}`);
+
+  // Process one batch
+  const result = await processBatch(state.nextPageToken);
+
+  if (result.hasMore) {
+    // Update state and queue next batch
+    await this.set(`sync_state_${context.calendarId}`, {
+      nextPageToken: result.nextPageToken,
+      batchNumber: state.batchNumber + 1,
+    });
+
+    const nextCallback = await this.callback("syncBatch", context);
+    await this.run(nextCallback);
+  } else {
+    // Cleanup when done
+    await this.clear(`sync_state_${context.calendarId}`);
+  }
+}
+```
+
+## Testing
+
+Test your twist locally before deploying:
+
+```bash
+# Run linter
+{{packageManager}} lint
+
+# Deploy to your Plot account
+{{packageManager}} deploy
+```
+
+## Resources
+
+- [Plot twist Builder Documentation](https://github.com/plotday/plot)
+- [twist Examples](https://github.com/plotday/plot/tree/main/libs/twist/examples)
+- [Tool Documentation](https://github.com/plotday/plot/tree/main/libs/twist/tools)
+
+## Support
+
+For help or questions:
+- Open an issue on GitHub
+- Contact support@plot.day