49 lines · 3 KBtext/plain; charset=utf-8
The Coline App SDK: apps, tools, file types and surfaces that run inside Coline workspaces, and public websites with Coline Sites. TypeScript, with an in-memory test workspace. MIT.
| 6 | * apps/docs/content/docs/sdk/reference.mdx: |
| 7 | * |
| 8 | * pnpm --filter @colineapp/sdk exec tsx scripts/docs-reference.ts |
| 9 | */ |
| 10 | import { readFileSync } from "node:fs"; |
| 11 | import { APP_CAPABILITY_OPERATIONS, VISITOR_CAPABILITY_OPERATIONS } from "../src/capabilities/operations"; |
| 12 | import { APP_PERMISSION_V2_DESCRIPTIONS, APP_PERMISSIONS_V2 } from "../src/manifest/permissions"; |
| 13 | import { CHAT_CARD_ALLOWED_NODE_TYPES } from "../src/tree/chat-card"; |
| 14 |
| 15 | const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }; |
| 16 | const lines: string[] = []; |
| 17 |
| 18 | lines.push(`{/* Generated from @colineapp/sdk ${pkg.version} by packages/sdk/scripts/docs-reference.ts */}`, ""); |
| 19 | lines.push("## Permissions", ""); |
| 20 | lines.push( |
| 21 | "Declared in the manifest, approved by a workspace admin at install, and shown to people with exactly this wording. Every capability call needs its permission declared and granted.", |
| 22 | "", |
| 23 | ); |
| 24 | lines.push("| Permission | Shown to people as |", "| --- | --- |"); |
| 25 | for (const permission of APP_PERMISSIONS_V2) { |
| 26 | lines.push(`| \`${permission}\` | ${APP_PERMISSION_V2_DESCRIPTIONS[permission]} |`); |
| 27 | } |
| 28 |
| 29 | lines.push("", "## Capability operations", ""); |
| 30 | lines.push( |
| 31 | "Every `coline.*` call maps to one operation with one required permission and one mutation class. A tool's effect must allow the operation's class, or the call fails with `effect_ceiling_exceeded`.", |
| 32 | "", |
| 33 | ); |
| 34 | lines.push("| Operation | Mutation | Permission | Site visitors |", "| --- | --- | --- | --- |"); |
| 35 | const visitor = new Set<string>(VISITOR_CAPABILITY_OPERATIONS); |
| 36 | for (const [operation, spec] of Object.entries(APP_CAPABILITY_OPERATIONS).sort(([a], [b]) => a.localeCompare(b))) { |
| 37 | const { permission, mutation } = spec as { permission: string | null; mutation: string }; |
| 38 | lines.push(`| \`${operation}\` | ${mutation} | ${permission ? `\`${permission}\`` : "None"} | ${visitor.has(operation) ? "Yes" : ""} |`); |
| 39 | } |
| 40 |
| 41 | lines.push("", "## Chat cards", ""); |
| 42 | lines.push( |
| 43 | "Tool result cards and inline file surfaces render inside conversations, so they accept this subset of tree nodes. Home, preview and editor surfaces can use every node.", |
| 44 | "", |
| 45 | ); |
| 46 | lines.push([...CHAT_CARD_ALLOWED_NODE_TYPES].sort().map((type) => `\`${type}\``).join(", ")); |
| 47 |
| 48 | console.log(lines.join("\n")); |
| 49 |