More source --> connector cleanup

Author: KrisBraun

.changeset/connector-handle-replies.md

@@ -0,0 +1,7 @@
+---
+"@plotday/twister": minor
+---
+
+Removed: `addContacts()` from Plot tool public API (contacts are created implicitly through thread/note creation)
+Changed: `ContactAccess` enum now only has `Read` — `Write` removed from public API
+Added: `handleReplies` static property on Connector class (replaces Plot tool options for defaultMention)

.changeset/rename-source-to-connector-cli.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": patch
+---
+
+Changed: Renamed `--source` CLI flag to `--connector` in `plot create` command to match SDK naming

connectors/AGENTS.md

@@ -111,7 +111,6 @@ import {
   type Channel,
 } from "@plotday/twister/tools/integrations";
 import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
-import { ContactAccess, Plot } from "@plotday/twister/tools/plot";
 import { Tasks } from "@plotday/twister/tools/tasks";
 
 type SyncState = {
@@ -126,6 +125,7 @@ export class MyConnector extends Connector<MyConnector> {
   static readonly PROVIDER = AuthProvider.Linear; // Use appropriate provider
   static readonly SCOPES = ["read", "write"];
   static readonly Options: SyncToolOptions;
+  static readonly handleReplies = true; // Enable @-mentions on replies to synced threads
   declare readonly Options: SyncToolOptions;
 
   // 2. Declare dependencies
@@ -143,7 +143,6 @@ export class MyConnector extends Connector<MyConnector> {
       network: build(Network, { urls: ["https://api.example.com/*"] }),
       callbacks: build(Callbacks),
       tasks: build(Tasks),
-      plot: build(Plot, { contact: { access: ContactAccess.Write } }),
     };
   }
 
@@ -798,20 +797,16 @@ async onNoteCreated(note: Note): Promise<void> {
 
 ### Default Mention on Replies
 
-Connectors with bidirectional sync should set `thread.defaultMention: true` in their Plot tool options so replies to synced threads automatically mention the connector:
+Connectors with bidirectional sync should set `static readonly handleReplies = true` so replies to synced threads automatically mention the connector:
 
 ```typescript
-plot: build(Plot, {
-  thread: {
-    access: ThreadAccess.Create,
-    defaultMention: true,  // Replies to synced threads mention this connector by default
-    updated: this.onThreadUpdated,
-  },
-  note: { created: this.onNoteCreated },
-}),
+export class MyConnector extends Connector<MyConnector> {
+  static readonly handleReplies = true;  // Replies to synced threads mention this connector by default
+  // ...
+}
 ```
 
-Without this, users must manually toggle the connector's mention chip on each reply. Connectors that don't process replies (e.g., read-only calendar sync) should NOT set this flag.
+Without this, the connector cannot be @-mentioned at all. Connectors that don't process replies (e.g., read-only calendar sync) should NOT set this flag.
 
 ## Contacts Pattern
 
@@ -837,10 +832,7 @@ const activity: NewActivityWithNotes = {
 };
 ```
 
-Declare `ContactAccess.Write` in build:
-```typescript
-plot: build(Plot, { contact: { access: ContactAccess.Write } }),
-```
+Contacts are created implicitly when saving threads/links via `integrations.saveLink()` — no explicit `addContacts()` call or `ContactAccess.Write` permission is needed.
 
 ## Buffer Declaration
 
@@ -875,7 +867,8 @@ After creating a new connector, add it to `pnpm-workspace.yaml` if not already c
 - [ ] Extend `Connector<YourConnector>`
 - [ ] Declare `static readonly PROVIDER`, `static readonly SCOPES`
 - [ ] Declare `static readonly Options: SyncToolOptions` and `declare readonly Options: SyncToolOptions`
-- [ ] Declare all dependencies in `build()`: Integrations, Network, Callbacks, Tasks, Plot
+- [ ] Declare all dependencies in `build()`: Integrations, Network, Callbacks, Tasks
+- [ ] Set `static readonly handleReplies = true` if the connector supports bidirectional sync
 - [ ] Implement `getChannels()`, `onChannelEnabled()`, `onChannelDisabled()`
 - [ ] Convert parent callbacks to tokens with `createFromParent()` — **never pass functions to `this.callback()`**
 - [ ] Store callback tokens with `this.set()`, retrieve with `this.get<Callback>()`

connectors/github/src/github.ts

@@ -17,7 +17,6 @@ import {
   type Channel,
 } from "@plotday/twister/tools/integrations";
 import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
-import { Plot } from "@plotday/twister/tools/plot";
 import { Tasks } from "@plotday/twister/tools/tasks";
 import {
   startPRBatchSync,
@@ -103,6 +102,7 @@ type GitHubRepo = {
 export class GitHub extends Connector<GitHub> {
   static readonly PROVIDER = AuthProvider.GitHub;
   static readonly SCOPES = ["repo"];
+  static readonly handleReplies = true;
 
   readonly provider = AuthProvider.GitHub;
   readonly scopes = GitHub.SCOPES;
@@ -153,10 +153,6 @@ export class GitHub extends Connector<GitHub> {
       integrations: build(Integrations),
       network: build(Network, { urls: ["https://api.github.com/*"] }),
       tasks: build(Tasks),
-      plot: build(Plot, {
-        thread: { defaultMention: true },
-        note: { defaultMention: true },
-      }),
     };
   }
 

connectors/gmail/src/gmail.ts

@@ -8,7 +8,7 @@ import {
   Integrations,
 } from "@plotday/twister/tools/integrations";
 import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
-import { Plot } from "@plotday/twister/tools/plot";
+
 
 import {
   GmailApi,
@@ -45,6 +45,7 @@ type MessageSyncOptions = {
  */
 export class Gmail extends Connector<Gmail> {
   static readonly PROVIDER = AuthProvider.Google;
+  static readonly handleReplies = true;
   static readonly SCOPES = [
     "https://www.googleapis.com/auth/gmail.readonly",
     "https://www.googleapis.com/auth/gmail.modify",
@@ -68,9 +69,6 @@ export class Gmail extends Connector<Gmail> {
       network: build(Network, {
         urls: ["https://gmail.googleapis.com/gmail/v1/*"],
       }),
-      plot: build(Plot, {
-        thread: { defaultMention: true },
-      }),
     };
   }
 

connectors/jira/src/jira.ts

@@ -17,7 +17,6 @@ import {
   type Channel,
 } from "@plotday/twister/tools/integrations";
 import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
-import { Plot } from "@plotday/twister/tools/plot";
 import { Tasks } from "@plotday/twister/tools/tasks";
 
 type Project = {
@@ -47,6 +46,7 @@ type SyncState = {
 export class Jira extends Connector<Jira> {
   static readonly PROVIDER = AuthProvider.Atlassian;
   static readonly SCOPES = ["read:jira-work", "write:jira-work", "read:jira-user"];
+  static readonly handleReplies = true;
 
   readonly provider = AuthProvider.Atlassian;
   readonly scopes = Jira.SCOPES;
@@ -69,10 +69,6 @@ export class Jira extends Connector<Jira> {
       integrations: build(Integrations),
       network: build(Network, { urls: ["https://*.atlassian.net/*"] }),
       tasks: build(Tasks),
-      plot: build(Plot, {
-        thread: { defaultMention: true },
-        note: { defaultMention: true },
-      }),
     };
   }
 

connectors/linear/src/linear.ts

@@ -25,7 +25,6 @@ import {
   type Channel,
 } from "@plotday/twister/tools/integrations";
 import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
-import { Plot } from "@plotday/twister/tools/plot";
 import { Tasks } from "@plotday/twister/tools/tasks";
 
 type Project = {
@@ -70,6 +69,7 @@ type ViewerInfo = {
 export class Linear extends Connector<Linear> {
   static readonly PROVIDER = AuthProvider.Linear;
   static readonly SCOPES = ["read", "write", "admin"];
+  static readonly handleReplies = true;
 
   readonly provider = AuthProvider.Linear;
   readonly scopes = Linear.SCOPES;
@@ -93,10 +93,6 @@ export class Linear extends Connector<Linear> {
       integrations: build(Integrations),
       network: build(Network, { urls: ["https://api.linear.app/*"] }),
       tasks: build(Tasks),
-      plot: build(Plot, {
-        thread: { defaultMention: true },
-        note: { defaultMention: true },
-      }),
     };
   }
 

connectors/slack/src/slack.ts

@@ -10,7 +10,7 @@ import {
   type Channel,
 } from "@plotday/twister/tools/integrations";
 import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
-import { Plot } from "@plotday/twister/tools/plot";
+
 
 type MessageChannel = {
   id: string;
@@ -61,6 +61,7 @@ import {
  */
 export class Slack extends Connector<Slack> {
   static readonly PROVIDER = AuthProvider.Slack;
+  static readonly handleReplies = true;
   static readonly SCOPES = [
     "channels:history",
     "channels:read",
@@ -81,9 +82,6 @@ export class Slack extends Connector<Slack> {
     return {
       integrations: build(Integrations),
       network: build(Network, { urls: ["https://slack.com/api/*"] }),
-      plot: build(Plot, {
-        thread: { defaultMention: true },
-      }),
     };
   }
 

twister/cli/commands/create.ts

@@ -10,12 +10,12 @@ interface CreateOptions {
   dir?: string;
   name?: string;
   displayName?: string;
-  source?: boolean;
+  connector?: boolean;
 }
 
 export async function createCommand(options: CreateOptions) {
-  const isSource = !!options.source;
-  out.header(isSource ? "Create a new Plot connector" : "Create a new Plot twist");
+  const isConnector = !!options.connector;
+  out.header(isConnector ? "Create a new Plot connector" : "Create a new Plot twist");
 
   let response: { name: string; displayName: string };
 
@@ -96,7 +96,7 @@ export async function createCommand(options: CreateOptions) {
   const plotTwistId = crypto.randomUUID();
 
   // Create package.json
-  const packageName = isSource ? `@plotday/connector-${response.name}` : response.name;
+  const packageName = isConnector ? `@plotday/connector-${response.name}` : response.name;
   const packageJson: any = {
     name: packageName,
     displayName: response.displayName || response.name,
@@ -130,7 +130,7 @@ export async function createCommand(options: CreateOptions) {
     JSON.stringify(tsconfigJson, null, 2) + "\n"
   );
 
-  const sourceTemplate = `import { Connector, type ToolBuilder } from "@plotday/twister";
+  const connectorTemplate = `import { Connector, type ToolBuilder } from "@plotday/twister";
 import {
   AuthProvider,
   type AuthToken,
@@ -190,7 +190,7 @@ export default class MyTwist extends Twist<MyTwist> {
 
   fs.writeFileSync(
     path.join(twistPath, "src", "index.ts"),
-    isSource ? sourceTemplate : twistTemplate
+    isConnector ? connectorTemplate : twistTemplate
   );
 
   // Detect and use appropriate package manager

twister/cli/index.ts

@@ -55,7 +55,7 @@ program
   .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")
-  .option("--source", "Create a connector instead of a twist")
+  .option("--connector", "Create a connector instead of a twist")
   .action(createCommand);
 
 // Top-level lint command