@plotday/twister 0.20.0

package/bin/index.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const twist_logs_1 = require("./commands/twist-logs");
+const build_1 = require("./commands/build");
+const create_1 = require("./commands/create");
+const deploy_1 = require("./commands/deploy");
+const generate_1 = require("./commands/generate");
+const lint_1 = require("./commands/lint");
+const login_1 = require("./commands/login");
+const priority_create_1 = require("./commands/priority-create");
+const priority_list_1 = require("./commands/priority-list");
+const output_1 = require("./utils/output");
+// Get the version from package.json
+const packageJsonPath = (0, path_1.join)(__dirname, "..", "package.json");
+const packageJson = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, "utf-8"));
+const version = packageJson.version;
+// Display CLI header
+(0, output_1.cliHeader)(version);
+const program = new commander_1.Command();
+program
+    .name("plot")
+    .description("CLI tool for building and deploying Plot twists")
+    .version(version)
+    .addOption(new commander_1.Option("--api-url <url>", "API endpoint URL")
+    .default(process.env.PLOT_API_URL || "https://api.plot.day")
+    .hideHelp())
+    .addOption(new commander_1.Option("--site-url <url>", "Site endpoint URL")
+    .default(process.env.PLOT_SITE_URL || "https://plot.day")
+    .hideHelp());
+// Top-level login command
+program
+    .command("login")
+    .description("Authenticate with Plot to generate an API token")
+    .action(function () {
+    const opts = this.optsWithGlobals();
+    return (0, login_1.loginCommand)(opts);
+});
+// Top-level create command
+program
+    .command("create")
+    .description("Create a new Plot twist")
+    .option("-d, --dir <directory>", "Directory to create the twist in")
+    .option("-n, --name <name>", "Package name (kebab-case)")
+    .option("--display-name <displayName>", "Display name for the twist")
+    .action(create_1.createCommand);
+// Top-level lint command
+program
+    .command("lint")
+    .description("Check for build or lint errors")
+    .option("-d, --dir <directory>", "Twist directory to lint", process.cwd())
+    .action(lint_1.lintCommand);
+// Top-level build command
+program
+    .command("build")
+    .description("Bundle the twist without deploying")
+    .option("-d, --dir <directory>", "Twist directory to build", process.cwd())
+    .action(build_1.buildCommand);
+// Top-level generate command
+program
+    .command("generate")
+    .description("Generate twist code from a spec file")
+    .option("-d, --dir <directory>", "Twist directory to generate in", process.cwd())
+    .option("--spec <file>", "Spec file to generate from (defaults to plot-twist.md)")
+    .option("--id <twistId>", "Twist ID")
+    .option("--deploy-token <token>", "Authentication token")
+    .action(function () {
+    const opts = this.optsWithGlobals();
+    return (0, generate_1.generateCommand)(opts);
+});
+// Top-level deploy command
+program
+    .command("deploy")
+    .description("Bundle and deploy the twist")
+    .option("-d, --dir <directory>", "Twist directory to deploy", process.cwd())
+    .option("--id <twistId>", "Twist ID for deployment")
+    .option("--deploy-token <token>", "Authentication token for deployment")
+    .option("--name <name>", "Twist name")
+    .option("--description <description>", "Twist description")
+    .option("--dry-run", "Validate without deploying")
+    .option("-e, --environment <env>", "Deployment environment (personal, private, review)", "personal")
+    .action(function () {
+    const opts = this.optsWithGlobals();
+    return (0, deploy_1.deployCommand)(opts);
+});
+// Top-level logs command
+program
+    .command("logs [twist-id]")
+    .description("Stream real-time logs from a twist")
+    .option("-d, --dir <directory>", "Twist directory", process.cwd())
+    .option("--id <twistId>", "Twist ID")
+    .option("-e, --environment <env>", "Twist environment (personal, private, review)", "personal")
+    .option("--deploy-token <token>", "Authentication token")
+    .action(function (twistId) {
+    const opts = this.optsWithGlobals();
+    return (0, twist_logs_1.twistLogsCommand)({
+        twistId,
+        id: opts.id,
+        dir: opts.dir,
+        environment: opts.environment,
+        deployToken: opts.deployToken,
+        apiUrl: opts.apiUrl,
+    });
+});
+// Priority subcommand group
+const priority = program
+    .command("priority")
+    .description("Manage Plot priorities");
+priority
+    .command("create")
+    .description("Create a new priority")
+    .option("--name <name>", "Priority name")
+    .option("--parent-id <parentId>", "Parent priority ID")
+    .action(function () {
+    const opts = this.optsWithGlobals();
+    return (0, priority_create_1.priorityCreateCommand)(opts);
+});
+priority
+    .command("list")
+    .description("List all your priorities")
+    .action(function () {
+    const opts = this.optsWithGlobals();
+    return (0, priority_list_1.priorityListCommand)(opts);
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/bin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../cli/index.ts"],"names":[],"mappings":"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"}

package/bin/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/bin/plot.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// This is a wrapper that runs the compiled CLI
+require('./index.js');

package/bin/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/bin/templates/CLAUDE.template.md

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