@framers/agentos-ext-cloud-cloudflare-pages 0.1.0

package/src/index.ts

@@ -0,0 +1,129 @@
+// @ts-nocheck
+/**
+ * @fileoverview Cloudflare Pages & Workers Extension for AgentOS.
+ *
+ * Provides 4 tools for deploying Pages projects, managing DNS records,
+ * and deploying Worker scripts via the Cloudflare API v4.
+ *
+ * @module @framers/agentos-ext-cloud-cloudflare-pages
+ */
+
+import { CloudflareService } from './CloudflareService.js';
+import type { CloudflareConfig } from './CloudflareService.js';
+import { CfDeployPagesTool } from './tools/deploy.js';
+import { CfListProjectsTool } from './tools/listProjects.js';
+import { CfConfigureDnsTool } from './tools/configureDns.js';
+import { CfCreateWorkerTool } from './tools/createWorker.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface CloudflarePagesOptions {
+  apiToken?: string;
+  accountId?: string;
+  secrets?: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Secret Resolution
+// ---------------------------------------------------------------------------
+
+function resolveConfig(opts: CloudflarePagesOptions, secrets: Record<string, string>): CloudflareConfig {
+  return {
+    apiToken:
+      opts.apiToken ?? secrets['cloudflare.apiToken']
+      ?? process.env.CLOUDFLARE_API_TOKEN ?? '',
+    accountId:
+      opts.accountId ?? secrets['cloudflare.accountId']
+      ?? process.env.CLOUDFLARE_ACCOUNT_ID ?? '',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Extension Context
+// ---------------------------------------------------------------------------
+
+export interface ExtensionContext {
+  options?: Record<string, unknown>;
+  secrets?: Record<string, string>;
+  getSecret?: (key: string) => string | undefined;
+  logger?: { info: (msg: string) => void };
+}
+
+export interface ExtensionPack {
+  name: string;
+  version: string;
+  descriptors: Array<{ id: string; kind: string; priority?: number; payload: unknown }>;
+  onActivate?: () => Promise<void>;
+  onDeactivate?: () => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createExtensionPack(context: ExtensionContext): ExtensionPack {
+  const opts = (context.options ?? {}) as CloudflarePagesOptions;
+  const secrets = opts.secrets ?? context.secrets ?? {};
+  const config = resolveConfig(opts, secrets);
+
+  const service = new CloudflareService(config);
+
+  const deployTool = new CfDeployPagesTool(service);
+  const listProjectsTool = new CfListProjectsTool(service);
+  const configureDnsTool = new CfConfigureDnsTool(service);
+  const createWorkerTool = new CfCreateWorkerTool(service);
+
+  return {
+    name: '@framers/agentos-ext-cloud-cloudflare-pages',
+    version: '0.1.0',
+    descriptors: [
+      { id: 'cfDeployPages', kind: 'tool', priority: 40, payload: deployTool },
+      { id: 'cfListProjects', kind: 'tool', priority: 40, payload: listProjectsTool },
+      { id: 'cfConfigureDns', kind: 'tool', priority: 40, payload: configureDnsTool },
+      { id: 'cfCreateWorker', kind: 'tool', priority: 40, payload: createWorkerTool },
+    ],
+    onActivate: async () => {
+      if (!config.apiToken) {
+        throw new Error(
+          'Cloudflare: no API token provided. Set CLOUDFLARE_API_TOKEN environment variable, '
+          + 'or provide it via secrets["cloudflare.apiToken"].',
+        );
+      }
+      if (!config.accountId) {
+        throw new Error(
+          'Cloudflare: no Account ID provided. Set CLOUDFLARE_ACCOUNT_ID environment variable, '
+          + 'or provide it via secrets["cloudflare.accountId"].',
+        );
+      }
+      await service.initialize();
+    },
+    onDeactivate: async () => {
+      await service.shutdown();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { CloudflareService } from './CloudflareService.js';
+export type {
+  CloudflareConfig,
+  CloudflarePagesProject,
+  CloudflareDeployment,
+  CloudflareDnsRecord,
+  CloudflareZone,
+  CloudflareWorker,
+  DeployPagesResult,
+  CreatePagesProjectOptions,
+  DeployWorkerOptions,
+} from './CloudflareService.js';
+export { CfDeployPagesTool } from './tools/deploy.js';
+export { CfListProjectsTool } from './tools/listProjects.js';
+export { CfConfigureDnsTool } from './tools/configureDns.js';
+export { CfCreateWorkerTool } from './tools/createWorker.js';
+
+export default createExtensionPack;

package/src/tools/configureDns.ts

@@ -0,0 +1,130 @@
+// @ts-nocheck
+/**
+ * @fileoverview CfConfigureDnsTool — manage DNS records on a Cloudflare zone.
+ */
+
+import type { CloudflareService, CloudflareDnsRecord } from '../CloudflareService.js';
+
+export interface ConfigureDnsInput {
+  domain: string;
+  action?: 'add' | 'remove' | 'list' | 'update';
+  recordType?: 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX';
+  name?: string;
+  content?: string;
+  ttl?: number;
+  proxied?: boolean;
+  priority?: number;
+  comment?: string;
+  recordId?: string;
+}
+
+export class CfConfigureDnsTool {
+  readonly id = 'cfConfigureDns';
+  readonly name = 'cfConfigureDns';
+  readonly displayName = 'Configure DNS Records';
+  readonly description = 'Manage DNS records (A, AAAA, CNAME, TXT, MX) on a Cloudflare zone. Supports adding, removing, listing, and updating records. Automatically looks up the zone ID from the domain name.';
+  readonly category = 'cloud';
+  readonly version = '0.1.0';
+  readonly hasSideEffects = true;
+
+  readonly inputSchema = {
+    type: 'object' as const,
+    properties: {
+      domain: { type: 'string', description: 'Root domain for the Cloudflare zone (e.g. "example.com")' },
+      action: { type: 'string', enum: ['add', 'remove', 'list', 'update'], description: 'Action to perform (default: list)' },
+      recordType: { type: 'string', enum: ['A', 'AAAA', 'CNAME', 'TXT', 'MX'], description: 'DNS record type (required for add/update)' },
+      name: { type: 'string', description: 'Record name / hostname (e.g. "www", "@", "api.example.com")' },
+      content: { type: 'string', description: 'Record value (IP address, hostname, or text content)' },
+      ttl: { type: 'number', description: 'TTL in seconds (1 = auto, default: 1)' },
+      proxied: { type: 'boolean', description: 'Whether to proxy through Cloudflare (default: false)' },
+      priority: { type: 'number', description: 'Priority for MX records' },
+      comment: { type: 'string', description: 'Optional comment for the record' },
+      recordId: { type: 'string', description: 'Record ID (required for update/remove actions)' },
+    },
+    required: ['domain'],
+  };
+
+  constructor(private service: CloudflareService) {}
+
+  async execute(args: ConfigureDnsInput): Promise<{
+    success: boolean;
+    data?: CloudflareDnsRecord | CloudflareDnsRecord[] | { message: string };
+    error?: string;
+  }> {
+    try {
+      const action = args.action ?? 'list';
+
+      // Look up zone ID from domain
+      const zone = await this.service.getZoneByDomain(args.domain);
+
+      switch (action) {
+        case 'add': {
+          if (!args.recordType || !args.name || !args.content) {
+            return {
+              success: false,
+              error: 'recordType, name, and content are required for the "add" action.',
+            };
+          }
+
+          const record = await this.service.createDnsRecord(zone.id, {
+            type: args.recordType,
+            name: args.name,
+            content: args.content,
+            ttl: args.ttl,
+            proxied: args.proxied,
+            priority: args.priority,
+            comment: args.comment,
+          });
+
+          return { success: true, data: record };
+        }
+
+        case 'remove': {
+          if (!args.recordId) {
+            return {
+              success: false,
+              error: 'recordId is required for the "remove" action. Use action "list" first to find the record ID.',
+            };
+          }
+
+          await this.service.deleteDnsRecord(zone.id, args.recordId);
+          return { success: true, data: { message: `DNS record ${args.recordId} deleted.` } };
+        }
+
+        case 'update': {
+          if (!args.recordId) {
+            return {
+              success: false,
+              error: 'recordId is required for the "update" action. Use action "list" first to find the record ID.',
+            };
+          }
+
+          const updatePayload: Record<string, unknown> = {};
+          if (args.recordType) updatePayload.type = args.recordType;
+          if (args.name) updatePayload.name = args.name;
+          if (args.content) updatePayload.content = args.content;
+          if (args.ttl !== undefined) updatePayload.ttl = args.ttl;
+          if (args.proxied !== undefined) updatePayload.proxied = args.proxied;
+          if (args.priority !== undefined) updatePayload.priority = args.priority;
+          if (args.comment !== undefined) updatePayload.comment = args.comment;
+
+          const updated = await this.service.updateDnsRecord(zone.id, args.recordId, updatePayload);
+          return { success: true, data: updated };
+        }
+
+        case 'list': {
+          const records = await this.service.listDnsRecords(zone.id, {
+            type: args.recordType,
+            name: args.name,
+          });
+          return { success: true, data: records };
+        }
+
+        default:
+          return { success: false, error: `Unknown action: ${action}` };
+      }
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    }
+  }
+}

package/src/tools/createWorker.ts

@@ -0,0 +1,58 @@
+// @ts-nocheck
+/**
+ * @fileoverview CfCreateWorkerTool — deploy a Cloudflare Worker script.
+ */
+
+import type { CloudflareService, CloudflareWorker } from '../CloudflareService.js';
+
+export interface CreateWorkerInput {
+  name: string;
+  script: string;
+  routes?: string[];
+  compatibilityDate?: string;
+  bindings?: Record<string, string>;
+}
+
+export class CfCreateWorkerTool {
+  readonly id = 'cfCreateWorker';
+  readonly name = 'cfCreateWorker';
+  readonly displayName = 'Deploy Cloudflare Worker';
+  readonly description = 'Deploy a Cloudflare Worker script to the edge. Supports ES modules format, route patterns, compatibility dates, and environment variable bindings. Workers run on Cloudflare\'s global network with sub-millisecond cold starts.';
+  readonly category = 'cloud';
+  readonly version = '0.1.0';
+  readonly hasSideEffects = true;
+
+  readonly inputSchema = {
+    type: 'object' as const,
+    properties: {
+      name: { type: 'string', description: 'Worker script name (used as the identifier, e.g. "my-api-worker")' },
+      script: { type: 'string', description: 'JavaScript or TypeScript source code for the Worker (ES modules format with default export)' },
+      routes: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Route patterns to bind the Worker to (e.g. ["example.com/api/*", "*.example.com/webhook"])',
+      },
+      compatibilityDate: { type: 'string', description: 'Workers runtime compatibility date (e.g. "2024-01-01", default: "2024-01-01")' },
+      bindings: { type: 'object', description: 'Environment variable bindings as key-value pairs' },
+    },
+    required: ['name', 'script'],
+  };
+
+  constructor(private service: CloudflareService) {}
+
+  async execute(args: CreateWorkerInput): Promise<{ success: boolean; data?: CloudflareWorker; error?: string }> {
+    try {
+      const worker = await this.service.deployWorker({
+        name: args.name,
+        script: args.script,
+        routes: args.routes,
+        compatibilityDate: args.compatibilityDate,
+        bindings: args.bindings,
+      });
+
+      return { success: true, data: worker };
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    }
+  }
+}

package/src/tools/deploy.ts

@@ -0,0 +1,56 @@
+// @ts-nocheck
+/**
+ * @fileoverview CfDeployPagesTool — deploy a Cloudflare Pages project from a Git repository.
+ */
+
+import type { CloudflareService, DeployPagesResult } from '../CloudflareService.js';
+
+export interface CfDeployPagesInput {
+  gitUrl: string;
+  projectName?: string;
+  productionBranch?: string;
+  buildCommand?: string;
+  buildOutputDirectory?: string;
+  envVars?: Record<string, string>;
+}
+
+export class CfDeployPagesTool {
+  readonly id = 'cfDeployPages';
+  readonly name = 'cfDeployPages';
+  readonly displayName = 'Deploy Cloudflare Pages';
+  readonly description = 'Deploy a project to Cloudflare Pages from a Git repository URL. Creates the project if it does not exist. Supports static sites, Next.js, Astro, SvelteKit, Remix, and other full-stack frameworks with automatic build configuration.';
+  readonly category = 'cloud';
+  readonly version = '0.1.0';
+  readonly hasSideEffects = true;
+
+  readonly inputSchema = {
+    type: 'object' as const,
+    properties: {
+      gitUrl: { type: 'string', description: 'Git repository URL (e.g. "https://github.com/user/repo")' },
+      projectName: { type: 'string', description: 'Pages project name (auto-generated from repo name if omitted)' },
+      productionBranch: { type: 'string', description: 'Production branch name (default: "main")' },
+      buildCommand: { type: 'string', description: 'Build command override (e.g. "npm run build")' },
+      buildOutputDirectory: { type: 'string', description: 'Build output directory (e.g. "dist", "build", ".next")' },
+      envVars: { type: 'object', description: 'Environment variables to set on the project (key-value pairs)' },
+    },
+    required: ['gitUrl'],
+  };
+
+  constructor(private service: CloudflareService) {}
+
+  async execute(args: CfDeployPagesInput): Promise<{ success: boolean; data?: DeployPagesResult; error?: string }> {
+    try {
+      const result = await this.service.deployFromGit({
+        gitUrl: args.gitUrl,
+        productionBranch: args.productionBranch,
+        buildCommand: args.buildCommand,
+        buildOutputDirectory: args.buildOutputDirectory,
+        envVars: args.envVars,
+      });
+
+      return { success: true, data: result };
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    }
+  }
+}

package/src/tools/listProjects.ts

@@ -0,0 +1,35 @@
+// @ts-nocheck
+/**
+ * @fileoverview CfListProjectsTool — list all Cloudflare Pages projects.
+ */
+
+import type { CloudflareService, CloudflarePagesProject } from '../CloudflareService.js';
+
+export class CfListProjectsTool {
+  readonly id = 'cfListProjects';
+  readonly name = 'cfListProjects';
+  readonly displayName = 'List Pages Projects';
+  readonly description = 'List all Cloudflare Pages projects in the connected account. Shows project name, subdomain, production branch, linked Git repo, and latest deployment status.';
+  readonly category = 'cloud';
+  readonly version = '0.1.0';
+  readonly hasSideEffects = false;
+
+  readonly inputSchema = {
+    type: 'object' as const,
+    properties: {
+      limit: { type: 'number', description: 'Maximum number of projects to return (default: 25, max: 100)' },
+    },
+    required: [] as string[],
+  };
+
+  constructor(private service: CloudflareService) {}
+
+  async execute(args: { limit?: number }): Promise<{ success: boolean; data?: CloudflarePagesProject[]; error?: string }> {
+    try {
+      const projects = await this.service.listProjects(args.limit ?? 25);
+      return { success: true, data: projects };
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    }
+  }
+}