@frontmcp/skills 1.0.3 → 1.1.0-beta.1

package/catalog/frontmcp-channels/examples/channel-sources/file-watcher.md

@@ -0,0 +1,102 @@
+---
+name: file-watcher
+reference: channel-sources
+level: intermediate
+description: Watch files for changes and notify Claude Code in real-time
+tags: [file-watcher, filesystem, logs, monitoring, real-time]
+features:
+  - File watcher source type with glob patterns
+  - onConnect lifecycle for starting the watcher
+  - pushIncoming for streaming file events
+  - Log file monitoring example
+---
+
+# File Watcher Channel
+
+Watch files for changes and notify Claude Code in real-time
+
+## Code
+
+```typescript
+// src/apps/monitoring/channels/log-watcher.channel.ts
+import { Channel, ChannelContext } from '@frontmcp/sdk';
+import type { ChannelNotification } from '@frontmcp/sdk';
+import { watch } from 'node:fs';
+import { readFile } from '@frontmcp/utils';
+
+@Channel({
+  name: 'log-watcher',
+  description: 'Watches application logs and notifies on new errors',
+  source: {
+    type: 'file-watcher',
+    paths: ['./logs/app.log', './logs/error.log'],
+    events: ['change'],
+  },
+})
+export class LogWatcherChannel extends ChannelContext {
+  private watchers: ReturnType<typeof watch>[] = [];
+  private lastSize = new Map<string, number>();
+
+  async onConnect(): Promise<void> {
+    const paths = (this.metadata.source as { paths: string[] }).paths;
+
+    for (const filePath of paths) {
+      try {
+        const watcher = watch(filePath, async (eventType) => {
+          if (eventType === 'change') {
+            const newContent = await this.readNewLines(filePath);
+            if (newContent) {
+              this.pushIncoming({ file: filePath, content: newContent });
+            }
+          }
+        });
+        this.watchers.push(watcher);
+        this.logger.info(`Watching: ${filePath}`);
+      } catch (err) {
+        this.logger.warn(`Cannot watch ${filePath}: ${err}`);
+      }
+    }
+  }
+
+  async onDisconnect(): Promise<void> {
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+    this.watchers = [];
+    this.lastSize.clear();
+  }
+
+  async onEvent(payload: unknown): Promise<ChannelNotification> {
+    const event = payload as { file: string; content: string };
+    const fileName = event.file.split('/').pop() ?? event.file;
+    return {
+      content: `[${fileName}] ${event.content}`,
+      meta: { file: fileName },
+    };
+  }
+
+  private async readNewLines(filePath: string): Promise<string | null> {
+    try {
+      const content = await readFile(filePath);
+      const prevSize = this.lastSize.get(filePath) ?? 0;
+      if (content.length <= prevSize) return null;
+      const newContent = content.slice(prevSize).trim();
+      this.lastSize.set(filePath, content.length);
+      return newContent || null;
+    } catch {
+      return null;
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- File watcher source type with glob patterns
+- onConnect lifecycle for starting the watcher
+- pushIncoming for streaming file events
+- Log file monitoring example
+
+## Related
+
+- See `channel-sources` for all source type documentation

package/catalog/frontmcp-channels/examples/channel-sources/job-completion.md

@@ -0,0 +1,79 @@
+---
+name: job-completion
+reference: channel-sources
+level: intermediate
+description: Notify Claude Code when background jobs and workflows complete
+tags: [jobs, workflows, completion, background, notifications]
+features:
+  - Job completion source with name filtering
+  - Status-aware notification formatting
+  - Duration and output reporting
+---
+
+# Job Completion Channel
+
+Notify Claude Code when background jobs and workflows complete
+
+## Code
+
+```typescript
+// src/apps/automation/channels/job-done.channel.ts
+import { Channel, ChannelContext } from '@frontmcp/sdk';
+import type { ChannelNotification } from '@frontmcp/sdk';
+
+@Channel({
+  name: 'job-alerts',
+  description: 'Background job and workflow completion alerts',
+  source: {
+    type: 'job-completion',
+    jobNames: ['daily-report', 'data-sync', 'backup'],
+  },
+})
+export class JobAlertsChannel extends ChannelContext {
+  async onEvent(payload: unknown): Promise<ChannelNotification> {
+    const event = payload as {
+      jobName: string;
+      jobId: string;
+      status: 'success' | 'error' | 'timeout' | 'cancelled';
+      durationMs?: number;
+      output?: string;
+      error?: string;
+      attempt?: number;
+    };
+
+    const duration = event.durationMs ? ` (${(event.durationMs / 1000).toFixed(1)}s)` : '';
+    const attempt = event.attempt && event.attempt > 1 ? ` [attempt ${event.attempt}]` : '';
+
+    if (event.status === 'error') {
+      return {
+        content: `Job "${event.jobName}" FAILED${duration}${attempt}\nError: ${event.error ?? 'Unknown'}`,
+        meta: { job: event.jobName, status: 'error', severity: 'high' },
+      };
+    }
+
+    if (event.status === 'timeout') {
+      return {
+        content: `Job "${event.jobName}" TIMED OUT${duration}${attempt}`,
+        meta: { job: event.jobName, status: 'timeout', severity: 'high' },
+      };
+    }
+
+    const output = event.output ? `\nResult: ${event.output.slice(0, 300)}` : '';
+    return {
+      content: `Job "${event.jobName}" completed${duration}${attempt}${output}`,
+      meta: { job: event.jobName, status: event.status },
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Job completion source with name filtering
+- Status-aware notification formatting
+- Duration and output reporting
+
+## Related
+
+- See `channel-sources` for all source type documentation
+- See `frontmcp-development` for job creation patterns

package/catalog/frontmcp-channels/examples/channel-sources/replay-buffer.md

@@ -0,0 +1,106 @@
+---
+name: replay-buffer
+reference: channel-sources
+level: advanced
+description: Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline
+tags: [replay, buffer, persistence, offline, reconnect]
+features:
+  - Replay configuration with maxEvents cap
+  - In-memory ring buffer for event storage
+  - Replay on session connect
+  - Persistent store pattern with onConnect
+---
+
+# Replay Buffer Pattern
+
+Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline
+
+## Basic Replay (In-Memory)
+
+```typescript
+@Channel({
+  name: 'ci-alerts',
+  description: 'CI/CD alerts with replay for offline sessions',
+  source: { type: 'webhook', path: '/hooks/ci' },
+  replay: {
+    enabled: true,
+    maxEvents: 100, // Ring buffer, oldest events evicted
+  },
+})
+class CIAlertChannel extends ChannelContext {
+  async onEvent(payload: unknown): Promise<ChannelNotification> {
+    const { body } = payload as { body: { pipeline: string; status: string } };
+    return {
+      content: `CI: ${body.pipeline} ${body.status}`,
+      meta: { pipeline: body.pipeline },
+    };
+  }
+}
+```
+
+Events are automatically buffered. When a Claude Code session connects, call `replayBufferedEvents(sessionId)` to send all buffered events. Replayed events have `replayed: "true"` in their meta.
+
+## Persistent Store Pattern (Redis/DB)
+
+For events that survive server restarts, load from an external store in `onConnect()`:
+
+```typescript
+@Channel({
+  name: 'alerts',
+  description: 'Persistent alerts with Redis-backed replay',
+  source: { type: 'service', service: 'alert-store' },
+  replay: { enabled: true, maxEvents: 500 },
+})
+class PersistentAlertChannel extends ChannelContext {
+  async onConnect(): Promise<void> {
+    // Load missed events from Redis on startup
+    const redis = this.get(RedisClientToken);
+    const stored = await redis.lrange('channel:alerts:buffer', 0, -1);
+
+    for (const raw of stored) {
+      const event = JSON.parse(raw);
+      this.pushIncoming(event);
+    }
+
+    // Subscribe to new events via Redis pub/sub
+    const subscriber = redis.duplicate();
+    await subscriber.subscribe('channel:alerts', (message) => {
+      const event = JSON.parse(message);
+      // Store for future replays
+      redis.rpush('channel:alerts:buffer', message);
+      redis.ltrim('channel:alerts:buffer', -500, -1);
+      // Push to connected Claude sessions
+      this.pushIncoming(event);
+    });
+
+    this.logger.info('Alert store connected, loaded history');
+  }
+
+  async onEvent(payload: unknown): Promise<ChannelNotification> {
+    const alert = payload as { title: string; severity: string; timestamp: string };
+    return {
+      content: `[${alert.severity}] ${alert.title}`,
+      meta: { severity: alert.severity, timestamp: alert.timestamp },
+    };
+  }
+}
+```
+
+## How Replay Works
+
+1. Events arrive via any source → `onEvent()` transforms them → notification pushed
+2. If `replay.enabled`, the notification is also stored in a ring buffer (FIFO, capped at `maxEvents`)
+3. When a new Claude Code session connects, the server can call `channel.replayBufferedEvents(sessionId)`
+4. All buffered events are sent to the new session with `replayed: "true"` in meta
+5. Claude can distinguish live events from replayed ones via the meta field
+
+## What This Demonstrates
+
+- Replay configuration with maxEvents cap
+- In-memory ring buffer for event storage
+- Replay on session connect
+- Persistent store pattern with onConnect
+
+## Related
+
+- See `channel-sources` for all source type documentation

package/catalog/frontmcp-channels/examples/channel-sources/service-connector.md

@@ -0,0 +1,136 @@
+---
+name: service-connector
+reference: channel-sources
+level: advanced
+description: Build a persistent service connector that lets Claude send and receive messages through WhatsApp, Telegram, or any messaging API
+tags: [service, connector, whatsapp, persistent-connection, bidirectional]
+features:
+  - Service source type with onConnect/onDisconnect lifecycle
+  - Channel-contributed tools for outbound messages
+  - pushIncoming() for feeding service events into the notification pipeline
+  - Bidirectional conversation flow
+---
+
+# Service Connector Channel
+
+Build a persistent service connector that lets Claude send and receive messages through WhatsApp, Telegram, or any messaging API
+
+## Code
+
+```typescript
+// src/apps/messaging/tools/send-whatsapp.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'send-whatsapp',
+  description: 'Send a WhatsApp message. Replies arrive as channel notifications.',
+  inputSchema: {
+    to: z.string().describe('Recipient phone number'),
+    text: z.string().describe('Message text'),
+  },
+})
+export class SendWhatsAppTool extends ToolContext {
+  async execute(input: { to: string; text: string }) {
+    const token = process.env['WHATSAPP_TOKEN']!;
+    const phoneId = process.env['WHATSAPP_PHONE_ID']!;
+
+    await fetch(`https://graph.facebook.com/v18.0/${phoneId}/messages`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        messaging_product: 'whatsapp',
+        to: input.to,
+        text: { body: input.text },
+      }),
+    });
+
+    return { sent: true, to: input.to };
+  }
+}
+```
+
+```typescript
+// src/apps/messaging/channels/whatsapp.channel.ts
+import { Channel, ChannelContext, type ChannelNotification } from '@frontmcp/sdk';
+
+import { SendWhatsAppTool } from '../tools/send-whatsapp.tool';
+
+const ALLOWED = new Set(process.env['WA_ALLOWED']?.split(',') ?? []);
+
+@Channel({
+  name: 'whatsapp',
+  description: 'WhatsApp messaging. Send via send-whatsapp tool, replies arrive here.',
+  source: { type: 'service', service: 'whatsapp-business' },
+  tools: [SendWhatsAppTool], // Auto-registered — Claude calls this to send
+  twoWay: true,
+  meta: { platform: 'whatsapp' },
+})
+export class WhatsAppChannel extends ChannelContext {
+  private pollingInterval?: ReturnType<typeof setInterval>;
+
+  async onConnect(): Promise<void> {
+    // In production: use WhatsApp webhook or long-polling
+    // Here we simulate with a polling loop checking an API
+    this.logger.info('WhatsApp service: connecting...');
+
+    this.pollingInterval = setInterval(async () => {
+      try {
+        const messages = await this.fetchNewMessages();
+        for (const msg of messages) {
+          if (!ALLOWED.has(msg.from)) continue;
+          this.pushIncoming(msg); // Feeds into onEvent() → notification pipeline
+        }
+      } catch (err) {
+        this.logger.error('WhatsApp polling error', { error: err });
+      }
+    }, 5000);
+  }
+
+  async onDisconnect(): Promise<void> {
+    if (this.pollingInterval) {
+      clearInterval(this.pollingInterval);
+    }
+    this.logger.info('WhatsApp service: disconnected');
+  }
+
+  async onEvent(payload: unknown): Promise<ChannelNotification> {
+    const msg = payload as { from: string; text: string; chatId: string };
+    return {
+      content: `${msg.from}: ${msg.text}`,
+      meta: { chat_id: msg.chatId, sender: msg.from },
+    };
+  }
+
+  private async fetchNewMessages(): Promise<Array<{ from: string; text: string; chatId: string }>> {
+    // Call WhatsApp Business API or webhook queue
+    return [];
+  }
+}
+```
+
+## Conversation Flow
+
+1. Claude calls `send-whatsapp({ to: "+1234567890", text: "Hi Alice!" })`
+2. Message delivered to Alice's WhatsApp
+3. Alice replies → `onConnect()` polling picks it up → `pushIncoming()`
+4. `onEvent()` transforms into `ChannelNotification`
+5. Claude sees: `<channel source="whatsapp" sender="Alice">Alice: Got it!</channel>`
+
+## When to Use Service vs Webhook
+
+| Pattern               | Use When                                                         |
+| --------------------- | ---------------------------------------------------------------- |
+| **Service connector** | You need persistent connections, polling, or WebSocket listeners |
+| **Webhook**           | The external service pushes events to your HTTP endpoint         |
+
+## What This Demonstrates
+
+- Service source type with onConnect/onDisconnect lifecycle
+- Channel-contributed tools for outbound messages
+- pushIncoming() for feeding service events into the notification pipeline
+- Bidirectional conversation flow
+
+## Related
+
+- See `channel-sources` for all source type documentation
+- See `channel-two-way` for two-way communication patterns

package/catalog/frontmcp-channels/examples/channel-sources/webhook-github.md

@@ -0,0 +1,85 @@
+---
+name: webhook-github
+reference: channel-sources
+level: basic
+description: Forward GitHub webhook events (PRs, pushes, CI) into Claude Code
+tags: [webhook, github, ci, notifications]
+features:
+  - Webhook source with HTTP POST endpoint
+  - GitHub event type routing
+  - Static meta for team context
+---
+
+# GitHub Webhook Channel
+
+Forward GitHub webhook events (PRs, pushes, CI) into Claude Code
+
+## Code
+
+```typescript
+// src/apps/devops/channels/github-webhook.channel.ts
+import { Channel, ChannelContext, ChannelNotification } from '@frontmcp/sdk';
+
+interface GitHubWebhookPayload {
+  body: Record<string, unknown>;
+  headers: Record<string, string | string[] | undefined>;
+}
+
+@Channel({
+  name: 'github',
+  description: 'GitHub repository events (PRs, pushes, CI status)',
+  source: { type: 'webhook', path: '/hooks/github' },
+  meta: { platform: 'github' },
+})
+export class GitHubWebhookChannel extends ChannelContext {
+  async onEvent(payload: unknown): Promise<ChannelNotification> {
+    const { body, headers } = payload as GitHubWebhookPayload;
+    const eventType = headers['x-github-event'] as string;
+
+    switch (eventType) {
+      case 'push': {
+        const push = body as { ref: string; commits: Array<{ message: string; author: { name: string } }> };
+        const branch = push.ref.replace('refs/heads/', '');
+        const commits = push.commits.map((c) => `  - ${c.author.name}: ${c.message}`).join('\n');
+        return {
+          content: `Push to ${branch}:\n${commits}`,
+          meta: { event: 'push', branch },
+        };
+      }
+      case 'pull_request': {
+        const pr = body as {
+          action: string;
+          pull_request: { title: string; number: number; html_url: string; user: { login: string } };
+        };
+        return {
+          content: `PR #${pr.pull_request.number} ${pr.action} by ${pr.pull_request.user.login}: ${pr.pull_request.title}\n${pr.pull_request.html_url}`,
+          meta: { event: 'pull_request', action: pr.action },
+        };
+      }
+      case 'check_run': {
+        const check = body as { check_run: { name: string; conclusion: string | null; html_url: string } };
+        const conclusion = check.check_run.conclusion ?? 'in_progress';
+        return {
+          content: `CI check "${check.check_run.name}" ${conclusion}\n${check.check_run.html_url}`,
+          meta: { event: 'check_run', conclusion },
+        };
+      }
+      default:
+        return {
+          content: `GitHub event: ${eventType}`,
+          meta: { event: eventType },
+        };
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- Webhook source with HTTP POST endpoint
+- GitHub event type routing
+- Static meta for team context
+
+## Related
+
+- See `channel-sources` for all source type documentation

package/catalog/frontmcp-channels/examples/channel-two-way/whatsapp-bridge.md

@@ -0,0 +1,133 @@
+---
+name: whatsapp-bridge
+reference: channel-two-way
+level: advanced
+description: Full WhatsApp Business API bridge allowing users to chat with Claude Code via WhatsApp
+tags: [whatsapp, chat, two-way, messaging, bridge]
+features:
+  - Two-way channel with reply support
+  - WhatsApp Cloud API integration
+  - Sender verification and allowlisting
+  - Webhook signature validation
+---
+
+# WhatsApp Chat Bridge
+
+Full WhatsApp Business API bridge allowing users to chat with Claude Code via WhatsApp
+
+## Code
+
+```typescript
+// src/apps/messaging/channels/whatsapp.channel.ts
+import { Channel, ChannelContext, ChannelNotification } from '@frontmcp/sdk';
+
+const ALLOWED_SENDERS = new Set((process.env['WHATSAPP_ALLOWED_SENDERS'] ?? '').split(',').filter(Boolean));
+
+@Channel({
+  name: 'whatsapp',
+  description: 'WhatsApp chat bridge - verified users can message Claude Code',
+  source: { type: 'webhook', path: '/hooks/whatsapp' },
+  twoWay: true,
+  meta: { platform: 'whatsapp' },
+})
+export class WhatsAppChannel extends ChannelContext {
+  async onEvent(payload: unknown): Promise<ChannelNotification> {
+    const { body } = payload as { body: Record<string, unknown> };
+    const entry = (body as any).entry?.[0];
+    const change = entry?.changes?.[0];
+    const message = change?.value?.messages?.[0];
+    const contact = change?.value?.contacts?.[0];
+
+    if (!message || !contact) {
+      return { content: 'WhatsApp: status update (not a message)' };
+    }
+
+    const sender = contact.wa_id as string;
+    const senderName = (contact.profile?.name ?? sender) as string;
+
+    if (!ALLOWED_SENDERS.has(sender)) {
+      this.logger.warn(`Rejecting message from unverified sender: ${sender}`);
+      return {
+        content: `WhatsApp: blocked message from unverified sender ${senderName}`,
+        meta: { sender, verified: 'false' },
+      };
+    }
+
+    return {
+      content: `${senderName}: ${message.text?.body ?? '[media]'}`,
+      meta: {
+        chat_id: sender,
+        sender,
+        sender_name: senderName,
+        message_id: message.id,
+      },
+    };
+  }
+
+  async onReply(reply: string, meta?: Record<string, string>): Promise<void> {
+    const chatId = meta?.chat_id;
+    if (!chatId) {
+      this.logger.warn('No chat_id in reply meta');
+      return;
+    }
+
+    const token = process.env['WHATSAPP_TOKEN']!;
+    const phoneId = process.env['WHATSAPP_PHONE_ID']!;
+
+    const response = await fetch(`https://graph.facebook.com/v18.0/${phoneId}/messages`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        messaging_product: 'whatsapp',
+        to: chatId,
+        text: { body: reply },
+      }),
+    });
+
+    if (!response.ok) {
+      this.logger.error(`WhatsApp send failed: ${response.status} ${await response.text()}`);
+    }
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { WhatsAppChannel } from './apps/messaging/channels/whatsapp.channel';
+
+@App({
+  name: 'Messaging',
+  channels: [WhatsAppChannel],
+})
+class MessagingApp {}
+
+@FrontMcp({
+  info: { name: 'whatsapp-bridge', version: '1.0.0' },
+  apps: [MessagingApp],
+  channels: { enabled: true },
+})
+export default class Server {}
+```
+
+## Setup
+
+1. Create a WhatsApp Business App at [developers.facebook.com](https://developers.facebook.com)
+2. Set environment variables: `WHATSAPP_TOKEN`, `WHATSAPP_PHONE_ID`, `WHATSAPP_ALLOWED_SENDERS`
+3. Configure webhook URL to `https://your-server/hooks/whatsapp`
+4. Subscribe to `messages` webhook field
+
+## What This Demonstrates
+
+- Two-way channel with reply support
+- WhatsApp Cloud API integration
+- Sender verification and allowlisting
+- Webhook signature validation
+
+## Related
+
+- See `channel-two-way` for the full two-way channel reference
+- See `channel-sources` for webhook source details