flingit 0.0.19 → 0.0.22

package/templates/default/skills/fling/DISCORD.md

@@ -1,15 +1,14 @@
 # Discord Skill
 
-Build Discord chatops bots with Fling. Add slash commands, send messages, handle interactions, and react to events — all from your Fling project.
+Build Discord chatops bots with Fling. Handle slash commands, send messages, handle interactions, and react to events — all from your Fling project.
 
 ## Setup
 
 Discord requires a one-time setup before use:
 
 ```bash
-npm exec fling plugin install discord    # Connect Discord account (opens browser)
-npm exec fling plugin discord add-server # Claim a server for your project
-npm exec fling push                      # Deploy code + register slash commands
+npm exec fling plugin install discord    # Connect Discord account + add bot to a server (opens browser)
+npm exec fling push                      # Deploy code
 ```
 
 Run these commands yourself — you have bash access.
@@ -20,48 +19,33 @@ Run these commands yourself — you have bash access.
 import { app } from "flingit";
 import { discord } from "flingit/plugin/discord";
 
-// 1. Define slash commands (synced to Discord on `fling push`)
-export const commands = discord.defineCommands([
-  { name: "ping", description: "Check bot latency" },
-  {
-    name: "deploy",
-    description: "Deploy a branch",
-    options: [
-      { name: "branch", type: "string", description: "Branch name", required: true }
-    ]
-  }
-]);
-
-// 2. Handle slash commands on POST /discord
-app.post("/discord", async (c) => {
-  const interaction = await discord.verifyInteraction(c);
-
-  if (interaction.data?.name === "ping") {
-    await discord.replyToInteraction(interaction, {
-      content: "Pong!",
-      ephemeral: true  // Only visible to the user who ran the command
-    });
-  }
-
-  if (interaction.data?.name === "deploy") {
-    const branch = interaction.data.options?.[0]?.value as string;
-    await discord.replyToInteraction(interaction, {
-      content: `Deploying ${branch}...`
-    });
-
-    // Do work after the initial reply...
-    const result = await runDeploy(branch);
-
-    // Send a followup message (no 3-second limit)
-    await discord.sendFollowup(interaction, {
-      content: `Deployed ${branch}: ${result}`
-    });
-  }
-
-  return c.json({ ok: true });
+// 1. Handle slash commands using onCommand(name, description, handler)
+//    Commands are auto-registered with Discord on `fling push`
+discord.onCommand("ping", "Check if the bot is alive", async (interaction) => {
+  await discord.reply(interaction, {
+    content: "Pong!",
+    ephemeral: true  // Only visible to the user who ran the command
+  });
+});
+
+discord.onCommand("deploy", "Deploy a branch", [
+  { name: "branch", type: "string", description: "Branch to deploy", required: false },
+], async (interaction, options) => {
+  const branch = options.getString("branch") ?? "main";
+  await discord.reply(interaction, {
+    content: `Deploying ${branch}...`
+  });
+
+  // Do work after the initial reply...
+  const result = await runDeploy(branch);
+
+  // Send a followup message (no 3-second limit)
+  await discord.followup(interaction, {
+    content: `Deployed ${branch}: ${result}`
+  });
 });
 
-// 3. Send messages proactively (e.g., from webhooks or cron)
+// 2. Send messages proactively (e.g., from webhooks or cron)
 app.post("/api/notify", async (c) => {
   const { channelId, text } = await c.req.json();
 
@@ -82,67 +66,82 @@ All methods are imported from `"flingit/plugin/discord"`:
 import { discord } from "flingit/plugin/discord";
 ```
 
-### discord.defineCommands(commands)
+### discord.onCommand(name, description, handler)
+### discord.onCommand(name, description, options, handler)
 
-Register slash commands. **Must be exported** as a top-level `export const commands` for `fling push` to detect them.
+Register a handler for a specific slash command. Commands are **automatically registered** with Discord when you run `fling push` — no need to use the Discord Developer Portal.
 
 ```typescript
-export const commands = discord.defineCommands([
-  { name: "status", description: "Show system status" },
-  {
-    name: "lookup",
-    description: "Look up a user",
-    options: [
-      { name: "email", type: "string", description: "User email", required: true },
-      { name: "verbose", type: "boolean", description: "Show full details" }
-    ]
-  }
-]);
+// Simple command (no parameters)
+discord.onCommand("ping", "Check if the bot is alive", async (interaction, options) => {
+  await discord.reply(interaction, "Pong!");
+});
+
+// Command with parameters — Discord shows autocomplete & validation
+discord.onCommand("deploy", "Deploy a branch", [
+  { name: "branch", type: "string", description: "Branch to deploy" },
+  { name: "force", type: "boolean", description: "Force deploy", required: false },
+], async (interaction, options) => {
+  const branch = options.getString("branch") ?? "main";
+  const force = options.getBoolean("force") ?? false;
+  await discord.reply(interaction, `Deploying ${branch}${force ? " (force)" : ""}...`);
+});
 ```
 
-**Command names:** 1-32 chars, lowercase letters, numbers, and hyphens only.
+**Supported option types:**
+
+| Type | Discord type | Value |
+|------|-------------|-------|
+| `"string"` | STRING (3) | `options.getString("name")` |
+| `"integer"` | INTEGER (4) | `options.getNumber("name")` |
+| `"boolean"` | BOOLEAN (5) | `options.getBoolean("name")` |
+| `"number"` | NUMBER (10) | `options.getNumber("name")` |
 
-**Option types:** `"string"`, `"integer"`, `"boolean"`, `"user"`, `"channel"`, `"role"`
+**Option properties:**
+- `name` — Parameter name (required)
+- `type` — One of `"string"`, `"integer"`, `"boolean"`, `"number"` (required)
+- `description` — Shown in Discord's UI (required)
+- `required` — Defaults to `true`. Set `false` for optional parameters.
+- `choices` — Enum-style choices: `[{ name: "Production", value: "prod" }, { name: "Staging", value: "staging" }]`
 
-Options can have predefined choices:
+**Choices example:**
 
 ```typescript
-{
-  name: "env",
-  type: "string",
-  description: "Target environment",
-  required: true,
-  choices: [
-    { name: "Production", value: "prod" },
-    { name: "Staging", value: "staging" }
-  ]
-}
+discord.onCommand("env", "Switch environment", [
+  {
+    name: "target",
+    type: "string",
+    description: "Target environment",
+    choices: [
+      { name: "Production", value: "prod" },
+      { name: "Staging", value: "staging" },
+      { name: "Development", value: "dev" },
+    ],
+  },
+], async (interaction, options) => {
+  const target = options.getString("target")!;
+  await discord.reply(interaction, `Switching to ${target}`);
+});
 ```
 
-### discord.verifyInteraction(c)
+The platform verifies Discord's cryptographic signature before forwarding to your code — you don't need to handle that.
 
-Parse an incoming Discord interaction from a Hono request context. Call this in your `POST /discord` handler.
+### discord.onEvent(handler)
+
+Register a fallback handler for interactions that don't match any `onCommand`. Use for advanced cases.
 
 ```typescript
-app.post("/discord", async (c) => {
-  const interaction = await discord.verifyInteraction(c);
-
-  // interaction.data.name = command name
-  // interaction.data.options = command arguments
-  // interaction.member.user = who ran the command (in servers)
-  // interaction.guild_id = which server
-  // interaction.channel_id = which channel
+discord.onEvent(async (interaction) => {
+  // Called for any interaction not handled by onCommand
 });
 ```
 
-The platform verifies Discord's cryptographic signature before forwarding to your code — you don't need to handle that.
-
-### discord.replyToInteraction(interaction, options)
+### discord.reply(interaction, options)
 
 Reply to a slash command. **Must be called within 3 seconds** of receiving the interaction.
 
 ```typescript
-await discord.replyToInteraction(interaction, {
+discord.reply(interaction, {
   content: "Hello!",              // Text content (max 2000 chars)
   ephemeral: true,                // Only visible to command user (optional)
   embeds: [{                      // Rich embeds (optional, max 10)
@@ -153,16 +152,16 @@ await discord.replyToInteraction(interaction, {
 });
 ```
 
-### discord.sendFollowup(interaction, options)
+### discord.followup(interaction, options)
 
 Send additional messages after the initial reply. No 3-second time limit.
 
 ```typescript
-await discord.replyToInteraction(interaction, { content: "Working on it..." });
+discord.reply(interaction, { content: "Working on it..." });
 
 // ... do async work ...
 
-const msg = await discord.sendFollowup(interaction, {
+const msg = await discord.followup(interaction, {
   content: "Done! Here are the results.",
   embeds: [{ title: "Results", description: resultText }]
 });
@@ -243,23 +242,21 @@ Content max: 2000 characters. Embeds max: 10 per message.
 
 ## Reading Command Options
 
-Access option values from `interaction.data.options`:
+The `options` helper provides typed accessors for command options. Declare options in the `onCommand` call so Discord shows parameter hints and validation:
 
 ```typescript
-app.post("/discord", async (c) => {
-  const interaction = await discord.verifyInteraction(c);
-
-  if (interaction.data?.name === "deploy") {
-    const options = interaction.data.options ?? [];
-    const branch = options.find(o => o.name === "branch")?.value as string;
-    const force = options.find(o => o.name === "force")?.value as boolean ?? false;
-
-    await discord.replyToInteraction(interaction, {
-      content: `Deploying ${branch}${force ? " (force)" : ""}...`
-    });
-  }
-
-  return c.json({ ok: true });
+discord.onCommand("deploy", "Deploy a branch", [
+  { name: "branch", type: "string", description: "Branch to deploy" },
+  { name: "force", type: "boolean", description: "Force deploy", required: false },
+  { name: "count", type: "integer", description: "Number of instances", required: false },
+], async (interaction, options) => {
+  const branch = options.getString("branch") ?? "main";
+  const force = options.getBoolean("force") ?? false;
+  const count = options.getNumber("count") ?? 1;
+
+  await discord.reply(interaction, {
+    content: `Deploying ${branch}${force ? " (force)" : ""} (×${count})...`
+  });
 });
 ```
 
@@ -268,9 +265,7 @@ app.post("/discord", async (c) => {
 Access who ran the command and where:
 
 ```typescript
-app.post("/discord", async (c) => {
-  const interaction = await discord.verifyInteraction(c);
-
+discord.onCommand("info", "Show context info", async (interaction) => {
   // Who ran it
   const user = interaction.member?.user;  // In servers
   // user.id, user.username
@@ -289,14 +284,12 @@ app.post("/discord", async (c) => {
 
 ```bash
 # Setup
-npm exec fling plugin install discord      # Connect Discord (OAuth)
-npm exec fling plugin discord add-server   # Claim a server
-npm exec fling plugin discord remove-server # Release a server
+npm exec fling plugin install discord      # Connect Discord (OAuth), auto-claims server
 
 # Status
 npm exec fling plugin permissions discord  # Show connection status + servers
 
-# Deployment (registers slash commands automatically)
+# Deployment
 npm exec fling push
 
 # Teardown
@@ -305,24 +298,21 @@ npm exec fling plugin remove discord       # Disconnect, release all servers
 
 ## How It Works
 
-1. **`fling plugin install discord`** opens a browser for Discord OAuth. You authorize Fling to see your servers and add the bot.
-2. **`fling plugin discord add-server`** claims a Discord server for your project. Each server can only be claimed by one project.
-3. **`export const commands = discord.defineCommands([...])`** in your code defines slash commands. `fling push` extracts them and registers them with Discord in all claimed servers.
-4. When a user runs a slash command, Discord sends it to the platform, which routes it to your worker's `POST /discord` endpoint.
-5. Your code calls `discord.verifyInteraction(c)` to parse it and `discord.replyToInteraction()` to respond.
+1. **`fling plugin install discord`** opens a browser for Discord OAuth. You authorize Fling, select a server to add the bot to, and that server is automatically claimed for your project.
+2. **`discord.onCommand(name, description, handler)`** registers a named command handler with a description.
+3. **`fling push`** bundles your code, deploys it, then automatically registers your slash commands with Discord's API for each claimed server. Commands appear instantly in Discord's slash command picker.
+4. When a user runs a slash command, Discord sends it to the platform, which routes it to your worker.
+5. Your handler receives the interaction and calls `discord.reply()` to respond.
+6. To add the bot to additional servers, re-run `fling plugin install discord` (remove and reinstall to re-OAuth), then `fling push` again to register commands in the new server.
 
 ## Important Constraints
 
 1. **Discord features only work in deployed workers** — They throw errors locally. Use `fling push` to deploy, then test in Discord.
 
-2. **Reply within 3 seconds** — `replyToInteraction()` must be called within 3 seconds. For slow operations, reply immediately with "Working..." then use `sendFollowup()` for the result.
-
-3. **Commands must be exported** — `fling push` looks for `export const commands = discord.defineCommands(...)`. If the export is missing, commands won't be registered.
-
-4. **Handle interactions at POST /discord** — The platform routes all interactions to this exact path on your worker.
+2. **Reply within 3 seconds** — `discord.reply()` must be called within 3 seconds. For slow operations, reply immediately with "Working..." then use `discord.followup()` for the result.
 
-5. **Channels must be in claimed servers** — `sendMessage()`, `editMessage()`, and `addReaction()` only work in channels belonging to servers claimed by your project.
+3. **Channels must be in claimed servers** — `sendMessage()`, `editMessage()`, and `addReaction()` only work in channels belonging to servers claimed by your project.
 
-6. **One project per server** — A Discord server can only be claimed by one Fling project at a time.
+4. **One project per server** — A Discord server can only be claimed by one Fling project at a time.
 
-7. **Plugin must be installed first** — Run `fling plugin install discord` before using any Discord features. Check with `fling plugin permissions discord`.
+5. **Plugin must be installed first** — Run `fling plugin install discord` before using any Discord features. Check with `fling plugin permissions discord`.

package/templates/default/skills/fling/SKILL.md

@@ -215,6 +215,8 @@ When the user's request is complete and working locally, offer to deploy it.  Bu
 To deploy:
 **Run `npm exec fling push` directly** - you have bash access, don't ask the user to run commands.
 
+After each deploy, tell the user what the deployed URL is.
+
 ### After First Deployment
 
 After your first `fling push`, consider asking the user if they want a custom URL.
@@ -251,7 +253,7 @@ Slugs must be:
 
 ## Security
 
-If the user does not want their app to be published because of security issues, or asks about that, offer implementing proper backend-supported security.  In particular, suggest these two auth methods first:
+If the user does not want their app to be deployed because of security issues, or asks about that, offer implementing proper backend-supported security.  In particular, suggest these two auth methods first:
 
 - Login with Google, with a filter on which emails/domains are allowed
 - Simple password-based auth, where the backend has a list of allowed passwords (hashed)
@@ -344,3 +346,7 @@ This approach:
 **For large assets:** Serve them from the frontend (`public/` folder) instead.
 
 See API.md for detailed API reference, EXAMPLES.md for common patterns, and FEEDBACK.md for collecting user feedback.
+
+## Updates
+
+When the fling CLI mentions that there is a new version available, strongly suggest to the user to update, becasue it might contain bug fixes or new features.

package/templates/default/skills/fling/SLACK.md

@@ -0,0 +1,214 @@
+# Slack Skill
+
+Build Slack chatops bots with Fling. Respond to @mentions, send messages, and react to events — all from your Fling project.
+
+## Setup
+
+Slack requires a one-time setup before use:
+
+```bash
+npm exec fling plugin install slack    # Connect Slack workspace (opens browser)
+npm exec fling push                    # Deploy code
+```
+
+Run these commands yourself — you have bash access.
+
+## Quick Reference
+
+```typescript
+import { app } from "flingit";
+import { slack } from "flingit/plugin/slack";
+
+// 1. Handle @mentions of your bot
+slack.onMention(async (event) => {
+  // Parse the mention text (remove the bot mention prefix)
+  const text = event.text.replace(/<@[A-Z0-9]+>\s*/, "").trim();
+
+  if (text.startsWith("deploy")) {
+    const branch = text.split(" ")[1] ?? "main";
+    await slack.sendMessage({
+      channelId: event.channel,
+      threadTs: event.ts,
+      text: `Deploying ${branch}...`,
+    });
+  } else {
+    await slack.sendMessage({
+      channelId: event.channel,
+      threadTs: event.ts,
+      text: "Hello! How can I help?",
+    });
+  }
+});
+
+// 2. Send messages proactively (e.g., from webhooks or cron)
+app.post("/api/notify", async (c) => {
+  const { channelId, text } = await c.req.json();
+
+  await slack.sendMessage({
+    channelId,
+    text
+  });
+
+  return c.json({ sent: true });
+});
+```
+
+## API Reference
+
+All methods are imported from `"flingit/plugin/slack"`:
+
+```typescript
+import { slack } from "flingit/plugin/slack";
+```
+
+### slack.onMention(handler)
+
+Register a handler for @mentions of your bot. Triggered when someone mentions your Fling app in a channel.
+
+```typescript
+slack.onMention(async (event) => {
+  // event.channel = which channel
+  // event.user = who mentioned the bot
+  // event.text = full mention text (includes <@BOT_ID>)
+  // event.ts = message timestamp
+  // event.thread_ts = thread timestamp (if in thread)
+
+  await slack.sendMessage({
+    channelId: event.channel,
+    threadTs: event.ts,  // Reply in thread
+    text: "Got it!",
+  });
+});
+```
+
+The platform verifies Slack's HMAC-SHA256 signature before forwarding to your code — you don't need to handle that.
+
+### slack.onEvent(handler)
+
+Register a fallback handler for raw Slack events that aren't handled by `onMention`. Use this for advanced cases.
+
+```typescript
+slack.onEvent(async (event) => {
+  console.log("Raw event:", event.type);
+});
+```
+
+### slack.sendMessage(options)
+
+Send a message to any channel. Use this for notifications, alerts, or proactive messages.
+
+```typescript
+const msg = await slack.sendMessage({
+  channelId: "C123456789",
+  text: "Deployment complete!",
+  blocks: [{
+    type: "section",
+    text: { type: "mrkdwn", text: "*Deploy Report*\nv2.1.0 is now live" }
+  }]
+});
+// Returns: { channelId, ts, text }
+```
+
+To reply in a thread:
+
+```typescript
+await slack.sendMessage({
+  channelId: "C123456789",
+  text: "Thread reply here",
+  threadTs: "1234567890.123456"  // Parent message timestamp
+});
+```
+
+### slack.editMessage(channelId, ts, options)
+
+Edit a previously sent message.
+
+```typescript
+const msg = await slack.sendMessage({
+  channelId: channel,
+  text: "Deploying..."
+});
+
+// Later, update it
+await slack.editMessage(channel, msg.ts, {
+  text: "Deploy complete!"
+});
+```
+
+### slack.addReaction(channelId, ts, emoji)
+
+Add an emoji reaction to a message.
+
+```typescript
+await slack.addReaction(channelId, ts, "white_check_mark");
+await slack.addReaction(channelId, ts, "rocket");
+```
+
+Note: Use emoji names without colons (e.g., `"thumbsup"` not `":thumbsup:"`).
+
+## Block Kit
+
+Slack uses Block Kit for rich message formatting. Common block types:
+
+```typescript
+// Section block with markdown
+{
+  type: "section",
+  text: { type: "mrkdwn", text: "*Bold* and _italic_" }
+}
+
+// Section with fields
+{
+  type: "section",
+  fields: [
+    { type: "mrkdwn", text: "*Status:*\nActive" },
+    { type: "mrkdwn", text: "*Region:*\nus-east-1" }
+  ]
+}
+
+// Divider
+{ type: "divider" }
+
+// Context (small text)
+{
+  type: "context",
+  elements: [
+    { type: "mrkdwn", text: "Deployed by <@U123> at 3:42 PM" }
+  ]
+}
+```
+
+For more block types, see the Slack Block Kit documentation.
+
+## CLI Commands
+
+```bash
+# Setup
+npm exec fling plugin install slack         # Connect Slack (OAuth), auto-claims workspace
+
+# Status
+npm exec fling plugin permissions slack     # Show connection status + workspaces
+
+# Deployment
+npm exec fling push
+
+# Teardown
+npm exec fling plugin remove slack          # Disconnect, release all workspaces
+```
+
+## How It Works
+
+1. **`fling plugin install slack`** opens a browser for Slack OAuth. You authorize the Fling app for your workspace, and it's automatically claimed for your project.
+2. **`slack.onMention(handler)`** registers a handler that receives `app_mention` events when someone @mentions your bot in a channel.
+3. The platform verifies Slack's HMAC-SHA256 signature, looks up the owning project, and forwards the event to your worker.
+4. Your handler receives the event and uses `slack.sendMessage()` to respond (typically replying in-thread).
+
+## Important Constraints
+
+1. **Slack features only work in deployed workers** — They throw errors locally. Use `fling push` to deploy, then test in Slack.
+
+2. **Mention-based interaction** — Users interact with your bot by @mentioning it in a channel. Parse the mention text to understand intent.
+
+3. **One project per workspace** — A Slack workspace can only be claimed by one Fling project at a time.
+
+4. **Plugin must be installed first** — Run `fling plugin install slack` before using any Slack features. Check with `fling plugin permissions slack`.