@illusoryai/pi-framer 0.1.0

package/extensions/framer.ts

@@ -0,0 +1,397 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+const PROJECT_URL = process.env.FRAMER_PROJECT_URL;
+const API_KEY = process.env.FRAMER_API_KEY;
+
+export default function (pi: ExtensionAPI) {
+  if (!PROJECT_URL || !API_KEY) {
+    return; // Framer not configured — skip silently
+  }
+
+  let framer: any = null;
+
+  async function getFramer(): Promise<any> {
+    if (framer) return framer;
+    const { connect } = await import("framer-api");
+    framer = await connect(PROJECT_URL!, API_KEY!);
+    return framer;
+  }
+
+  // Disconnect on session shutdown
+  pi.on("session_shutdown", async () => {
+    if (framer) {
+      try {
+        await framer.disconnect();
+      } catch {}
+      framer = null;
+    }
+  });
+
+  // --- Helpers ---
+
+  async function getCollectionByName(f: any, name: string) {
+    const collections = await f.getCollections();
+    return (
+      collections.find(
+        (c: any) =>
+          c.name?.toLowerCase() === name.toLowerCase() ||
+          c.id === name
+      ) || collections[0]
+    );
+  }
+
+  function extractFieldValue(entry: any, full = false): any {
+    if (!entry || typeof entry !== "object") return entry;
+    if (entry.type === "image" && entry.value?.url) return entry.value.url;
+    if (entry.type === "formattedText" && entry.value) {
+      if (full) return entry.value; // Return full HTML
+      const text = entry.value.replace(/<[^>]+>/g, "");
+      return text.length > 200 ? text.substring(0, 200) + "..." : text;
+    }
+    if ("value" in entry) return entry.value;
+    return entry;
+  }
+
+  function buildFieldData(
+    fields: any[],
+    assignments: string[]
+  ): Record<string, any> {
+    const data: Record<string, any> = {};
+    for (const assign of assignments) {
+      const eqIdx = assign.indexOf("=");
+      if (eqIdx === -1) continue;
+      const key = assign.substring(0, eqIdx).trim();
+      const val = assign.substring(eqIdx + 1).trim();
+
+      // Find field by name or ID
+      const field = fields.find(
+        (f: any) =>
+          f.name?.toLowerCase() === key.toLowerCase() || f.id === key
+      );
+      if (!field) continue;
+
+      const fieldId = field.id;
+      switch (field.type) {
+        case "boolean":
+          data[fieldId] = { type: "boolean", value: val === "true" };
+          break;
+        case "date":
+          data[fieldId] = { type: "date", value: new Date(val).toISOString() };
+          break;
+        case "number":
+          data[fieldId] = { type: "number", value: Number(val) };
+          break;
+        default:
+          data[fieldId] = {
+            type: "string",
+            value: val,
+            valueByLocale: {},
+          };
+      }
+    }
+    return data;
+  }
+
+  // --- Command handlers ---
+
+  async function handleInfo() {
+    const f = await getFramer();
+    const info = await f.getProjectInfo();
+    return JSON.stringify(info, null, 2);
+  }
+
+  async function handleCollections() {
+    const f = await getFramer();
+    const collections = await f.getCollections();
+    const result = collections.map((c: any) => ({
+      name: c.name,
+      id: c.id,
+      managedBy: c.managedBy,
+      slugField: c.slugFieldName,
+    }));
+    return JSON.stringify(result, null, 2);
+  }
+
+  async function handleSchema(collectionName: string) {
+    const f = await getFramer();
+    const col = await getCollectionByName(f, collectionName);
+    if (!col) return "Collection not found";
+    const fields = await col.getFields();
+    const result = fields.map((field: any) => ({
+      id: field.id,
+      name: field.name,
+      type: field.type,
+    }));
+    return `Collection: ${col.name} (${col.id})\nSlug field: ${col.slugFieldName}\n\n${JSON.stringify(result, null, 2)}`;
+  }
+
+  async function handleItems(collectionName: string) {
+    const f = await getFramer();
+    const col = await getCollectionByName(f, collectionName);
+    if (!col) return "Collection not found";
+    const fields = await col.getFields();
+    const items = await col.getItems();
+
+    const fieldMap: Record<string, string> = {};
+    for (const field of fields) fieldMap[field.id] = field.name;
+
+    // Find title field
+    const titleField = fields.find(
+      (field: any) =>
+        field.name?.toLowerCase() === "title" ||
+        field.name?.toLowerCase() === "name"
+    );
+
+    const result = items.map((item: any) => {
+      const title = titleField
+        ? extractFieldValue(item.fieldData?.[titleField.id])
+        : item.slug;
+      return {
+        id: item.id,
+        slug: item.slug,
+        draft: item.draft,
+        title,
+      };
+    });
+    return `${items.length} items in ${col.name}:\n\n${JSON.stringify(result, null, 2)}`;
+  }
+
+  async function handleItem(slugOrId: string) {
+    const f = await getFramer();
+    const collections = await f.getCollections();
+
+    for (const col of collections) {
+      const fields = await col.getFields();
+      const items = await col.getItems();
+      const fieldMap: Record<string, string> = {};
+      for (const field of fields) fieldMap[field.id] = field.name;
+
+      const item = items.find(
+        (i: any) => i.slug === slugOrId || i.id === slugOrId
+      );
+      if (!item) continue;
+
+      const data: Record<string, any> = {
+        id: item.id,
+        slug: item.slug,
+        draft: item.draft,
+        collection: col.name,
+      };
+
+      for (const [fieldId, value] of Object.entries(item.fieldData || {})) {
+        const fieldName = fieldMap[fieldId] || fieldId;
+        data[fieldName] = extractFieldValue(value, true);
+      }
+
+      return JSON.stringify(data, null, 2);
+    }
+    return `Item not found: ${slugOrId}`;
+  }
+
+  async function handleUpdate(args: string) {
+    const parts = args.split(/\s+/);
+    const slugOrId = parts[0];
+    const assignments = parts.slice(1);
+
+    if (!slugOrId || assignments.length === 0) {
+      return "Usage: update <slug-or-id> field1=value1 field2=value2";
+    }
+
+    const f = await getFramer();
+    const collections = await f.getCollections();
+
+    for (const col of collections) {
+      const fields = await col.getFields();
+      const items = await col.getItems();
+      const item = items.find(
+        (i: any) => i.slug === slugOrId || i.id === slugOrId
+      );
+      if (!item) continue;
+
+      const fieldData = buildFieldData(fields, assignments);
+      if (Object.keys(fieldData).length === 0) {
+        return `No valid fields found. Available: ${fields.map((f: any) => f.name).join(", ")}`;
+      }
+
+      const updated = await item.setAttributes({ fieldData });
+      return `Updated ${slugOrId}:\n${JSON.stringify(fieldData, null, 2)}`;
+    }
+    return `Item not found: ${slugOrId}`;
+  }
+
+  async function handleCreate(args: string) {
+    // Parse: create <collection> field1=value1 field2=value2
+    const parts = args.split(/\s+/);
+    const collectionName = parts[0];
+    const assignments = parts.slice(1);
+
+    if (!collectionName) {
+      return "Usage: create <collection> field1=value1 field2=value2";
+    }
+
+    const f = await getFramer();
+    const col = await getCollectionByName(f, collectionName);
+    if (!col) return "Collection not found";
+
+    const fields = await col.getFields();
+    const fieldData = buildFieldData(fields, assignments);
+
+    // Extract slug if provided
+    const slugAssign = assignments.find((a) =>
+      a.toLowerCase().startsWith("slug=")
+    );
+    const slug = slugAssign ? slugAssign.split("=")[1] : undefined;
+
+    const newItem: any = { fieldData, draft: false };
+    if (slug) newItem.slug = slug;
+
+    await col.addItems([newItem]);
+    return `Created item in ${col.name}${slug ? ` with slug: ${slug}` : ""}`;
+  }
+
+  async function handlePublish() {
+    const f = await getFramer();
+    const result = await f.publish();
+    return JSON.stringify(result, null, 2);
+  }
+
+  async function handleDeploy(deploymentId: string) {
+    if (!deploymentId) return "Usage: deploy <deployment-id>";
+    const f = await getFramer();
+    const result = await f.deploy(deploymentId);
+    return JSON.stringify(result, null, 2);
+  }
+
+  async function handleChanges() {
+    const f = await getFramer();
+    const changes = await f.getChangedPaths();
+    const contributors = await f.getChangeContributors();
+    return JSON.stringify({ changes, contributors }, null, 2);
+  }
+
+  async function handleCode(args?: string) {
+    const f = await getFramer();
+    if (!args) {
+      const code = await f.getCustomCode();
+      return JSON.stringify(code, null, 2);
+    }
+    // Set custom code: code <location> <html>
+    const [location, ...rest] = args.split(/\s+/);
+    const html = rest.join(" ");
+    const validLocations = ["headStart", "headEnd", "bodyStart", "bodyEnd"];
+    if (!validLocations.includes(location)) {
+      return `Invalid location. Use: ${validLocations.join(", ")}`;
+    }
+    await f.setCustomCode({ [location]: { html, disabled: false } });
+    return `Custom code set at ${location}`;
+  }
+
+  async function handlePublishDeploy() {
+    const f = await getFramer();
+    const pubResult = await f.publish();
+    const deploymentId = pubResult.deployment?.id;
+    if (!deploymentId) return "Publish failed — no deployment ID returned";
+    const deployResult = await f.deploy(deploymentId);
+    return `Published and deployed!\n\nPublish: ${JSON.stringify(pubResult, null, 2)}\n\nDeploy: ${JSON.stringify(deployResult, null, 2)}`;
+  }
+
+  // --- Register tool ---
+
+  pi.registerTool({
+    name: "framer",
+    label: "Framer CMS",
+    description:
+      "Manage Framer site via Server API. CMS operations, publishing, and custom code.\n\n" +
+      "Commands:\n" +
+      "  info                          — Project info\n" +
+      "  collections                   — List all CMS collections\n" +
+      "  schema <collection>           — Collection field schema\n" +
+      "  items <collection>            — List items (title, slug, draft)\n" +
+      "  item <slug-or-id>             — Full item details\n" +
+      "  update <slug-or-id> field=val — Update item fields\n" +
+      "  create <collection> field=val — Create new item\n" +
+      "  publish                       — Create preview deployment\n" +
+      "  deploy <deployment-id>        — Promote to production\n" +
+      "  ship                          — Publish + deploy in one step\n" +
+      "  changes                       — Pending changes + contributors\n" +
+      "  code                          — Get custom code\n" +
+      "  code <location> <html>        — Set custom code (headStart|headEnd|bodyStart|bodyEnd)",
+    parameters: Type.Object({
+      command: Type.String({
+        description:
+          'Framer command, e.g. \'items Blog\', \'update my-post-slug "Small Description"="New description"\'',
+      }),
+    }),
+    async execute(_toolCallId, params, _signal) {
+      try {
+        const cmd = params.command.trim();
+        const spaceIdx = cmd.indexOf(" ");
+        const action = spaceIdx === -1 ? cmd : cmd.substring(0, spaceIdx);
+        const args = spaceIdx === -1 ? "" : cmd.substring(spaceIdx + 1).trim();
+
+        let result: string;
+
+        switch (action.toLowerCase()) {
+          case "info":
+            result = await handleInfo();
+            break;
+          case "collections":
+            result = await handleCollections();
+            break;
+          case "schema":
+            result = await handleSchema(args || "Blog");
+            break;
+          case "items":
+            result = await handleItems(args || "Blog");
+            break;
+          case "item":
+            result = await handleItem(args);
+            break;
+          case "update":
+            result = await handleUpdate(args);
+            break;
+          case "create":
+            result = await handleCreate(args);
+            break;
+          case "publish":
+            result = await handlePublish();
+            break;
+          case "deploy":
+            result = await handleDeploy(args);
+            break;
+          case "ship":
+            result = await handlePublishDeploy();
+            break;
+          case "changes":
+            result = await handleChanges();
+            break;
+          case "code":
+            result = await handleCode(args || undefined);
+            break;
+          default:
+            result = `Unknown command: ${action}. Use: info, collections, schema, items, item, update, create, publish, deploy, ship, changes, code`;
+        }
+
+        return {
+          content: [{ type: "text", text: result }],
+          details: { command: params.command },
+        };
+      } catch (err: any) {
+        // Reset connection on error
+        if (
+          err.message?.includes("closed") ||
+          err.message?.includes("disconnect")
+        ) {
+          framer = null;
+        }
+        return {
+          content: [
+            { type: "text", text: `Error: ${err.message || String(err)}` },
+          ],
+          isError: true,
+        };
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@illusoryai/pi-framer",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": "extensions",
+    "skills": "skills"
+  },
+  "dependencies": {
+    "framer-api": "^0.2.4"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*"
+  }
+}

package/skills/framer-cms/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: framer-cms
+description: Manage Framer CMS content, publish deployments, and automate blog operations via the framer tool. Use when creating/editing blog posts, publishing site changes, or managing CMS collections.
+allowed-tools: framer, read, bash
+---
+
+# Framer CMS Operations
+
+**Use this when:** Creating or editing blog posts, publishing site changes, managing CMS collections, or automating content workflows.
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `framer info` | Project info |
+| `framer collections` | List all CMS collections |
+| `framer schema Blog` | Blog collection field schema |
+| `framer items Blog` | List all blog posts (title, slug, draft) |
+| `framer item <slug>` | Full item details |
+| `framer update <slug> field=value` | Update item fields |
+| `framer create Blog field=value` | Create new blog post |
+| `framer ship` | Publish + deploy to production in one step |
+| `framer changes` | Show pending changes |
+| `framer code` | Get/set custom code injection |
+
+## Blog Collection Schema
+
+| Field | ID | Type |
+|-------|----|------|
+| Category | `V20PYwhSX` | string ("Guide" or "Insight") |
+| Title | `RdldGed5b` | string |
+| Small Description | `gZduoeUwm` | string (meta description) |
+| Date | `oErJVDjg0` | date |
+| Image | `wYf3IKXhH` | image |
+| Featured | `BESrV0imp` | boolean |
+| Author | `ifzqi5HZI` | string |
+| Content | `JG8gJablh` | formattedText (HTML) |
+
+## Common Workflows
+
+### Edit a blog post's meta description
+
+```
+framer update ai-web-scraping-mobile-proxies "Small Description"="New meta description here"
+```
+
+### Create a new blog post
+
+```
+framer create Blog Title="My New Post" "Small Description"="Post summary" Category=Guide Author="Josiah Richards" Date=2026-02-14 slug=my-new-post
+```
+
+### Publish and deploy changes
+
+```
+framer ship
+```
+
+This runs `publish()` (creates preview) then `deploy(id)` (promotes to www.illusory.io).
+
+### After publishing: regenerate llms.txt
+
+```bash
+bun run scripts/generate-llms.ts
+```
+
+Add curated overrides in `workers/illusory-edge/llms-config.json` for correct titles/descriptions.
+
+## Architecture Notes
+
+- **WebSocket SDK** — `framer-api` connects via persistent WebSocket, not REST
+- **Connection lifecycle** — extension connects on first use, disconnects on session shutdown
+- **No transactions** — handle partial failures; CMS updates are immediate
+- **Publishing** — CMS changes are NOT live until `ship` (or `publish` + `deploy`)
+- **Custom domain** — deploys update `www.illusory.io` via Framer's CDN
+- **Worker origin** — currently `smart-let-525421.framer.app`