246 lines · 8 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.
| ColineScheduleContextV2, |
| 6 | ColineToolResult, |
| 7 | } from "../define/types"; |
| 8 | import type { ColineUiNode } from "../tree/tree"; |
| 9 | import { validateChatCardTree } from "../tree/chat-card"; |
| 10 | import { |
| 11 | TestWorkspaceState, |
| 12 | createFakeCapabilities, |
| 13 | type TestWorkspaceOptions, |
| 14 | } from "./fake-capabilities"; |
| 15 | import { guardTestCapabilities } from "./guarded-capabilities"; |
| 16 | import type { ToolEffect } from "../manifest/effect"; |
| 17 | import type { ColineCapabilities, ColineMemberSummary } from "../capabilities/types"; |
| 18 |
| 19 | /** |
| 20 | * `createTestWorkspace` (plan §14.2): a fake workspace + runtime for app |
| 21 | * tests. Invoke tools, render surfaces, and fire schedules exactly the |
| 22 | * way the platform does — input parsed through the tool's schema, cards |
| 23 | * validated against the chat subset, render contexts read-shaped — then |
| 24 | * assert on the inspectable state. |
| 25 | * |
| 26 | * ```ts |
| 27 | * const ws = createTestWorkspace(app); |
| 28 | * const result = await ws.invokeTool("crm.create_contact", { name: "Sarah" }); |
| 29 | * expect(ws.files.byType("crm.contact")).toHaveLength(1); |
| 30 | * ``` |
| 31 | */ |
| 32 |
| 33 | export interface InvokeToolResult { |
| 34 | output: unknown; |
| 35 | card: ColineUiNode | null; |
| 36 | } |
| 37 |
| 38 | export interface TestWorkspace { |
| 39 | state: TestWorkspaceState; |
| 40 | client(surface?: "home" | "editor" | "preview"): ColineCapabilities; |
| 41 | clientAs(userId: string, surface?: "home" | "editor" | "preview"): ColineCapabilities; |
| 42 | files: { |
| 43 | byType( |
| 44 | typeKey: string, |
| 45 | ): Array<{ fileId: string; name: string; document: Record<string, unknown> }>; |
| 46 | all(): Array<{ fileId: string; name: string; typeKey: string }>; |
| 47 | }; |
| 48 | invokeTool(name: string, input: unknown, userId?: string): Promise<InvokeToolResult>; |
| 49 | renderHome(): Promise<ColineUiNode>; |
| 50 | renderFileSurface( |
| 51 | surface: "editor" | "preview" | "inline", |
| 52 | file: { fileId: string; name: string; typeKey: string; version?: number }, |
| 53 | document?: Record<string, unknown>, |
| 54 | ): Promise<ColineUiNode>; |
| 55 | fireSchedule(scheduleId: string, at?: Date): Promise<void>; |
| 56 | } |
| 57 |
| 58 | export function createTestWorkspace( |
| 59 | app: ColineAppV2, |
| 60 | options: TestWorkspaceOptions = {}, |
| 61 | ): TestWorkspace { |
| 62 | const state = new TestWorkspaceState(); |
| 63 | const resolved = { |
| 64 | workspaceId: options.workspaceId ?? "ws_test", |
| 65 | workspaceSlug: options.workspaceSlug ?? "test-workspace", |
| 66 | workspaceName: options.workspaceName ?? "Test Workspace", |
| 67 | appKey: options.appKey ?? app.manifest.key, |
| 68 | installId: options.installId ?? "inst_test", |
| 69 | }; |
| 70 | const members: ColineMemberSummary[] = (options.members ?? [{ userId: "user_test" }]).map( |
| 71 | (member) => ({ |
| 72 | userId: member.userId, |
| 73 | email: member.email ?? `${member.userId}@example.com`, |
| 74 | handle: member.handle ?? member.userId, |
| 75 | firstName: member.firstName ?? "Test", |
| 76 | lastName: member.lastName ?? "User", |
| 77 | avatarUrl: member.avatarUrl ?? null, |
| 78 | }), |
| 79 | ); |
| 80 | const actorUserId = members[0]?.userId ?? "user_test"; |
| 81 |
| 82 | function capabilities( |
| 83 | effect: ToolEffect, |
| 84 | interactive = false, |
| 85 | appPrincipal = false, |
| 86 | userId = actorUserId, |
| 87 | ) { |
| 88 | if (!appPrincipal && !members.some((member) => member.userId === userId)) |
| 89 | throw Object.assign(new Error("Actor is not a member."), { code: "actor_not_member" }); |
| 90 | const raw = createFakeCapabilities(state, { |
| 91 | ...resolved, |
| 92 | members, |
| 93 | actor: appPrincipal ? { kind: "app" } : { kind: "user", userId }, |
| 94 | onNetFetch: options.onNetFetch, |
| 95 | onAiGenerate: options.onAiGenerate, |
| 96 | pickers: options.pickers ?? {}, |
| 97 | }); |
| 98 | return guardTestCapabilities( |
| 99 | raw, |
| 100 | { |
| 101 | manifestPermissions: app.manifest.permissions, |
| 102 | grantedPermissions: options.grantedPermissions ?? app.manifest.permissions, |
| 103 | effectCeiling: effect, |
| 104 | }, |
| 105 | { interactive, appPrincipal }, |
| 106 | ); |
| 107 | } |
| 108 | const coline = capabilities("read"); |
| 109 |
| 110 | const base = { |
| 111 | coline, |
| 112 | workspace: { |
| 113 | workspaceId: resolved.workspaceId, |
| 114 | workspaceSlug: resolved.workspaceSlug, |
| 115 | workspaceName: resolved.workspaceName, |
| 116 | }, |
| 117 | app: { appKey: resolved.appKey, installId: resolved.installId }, |
| 118 | }; |
| 119 |
| 120 | const workspace: TestWorkspace = { |
| 121 | state, |
| 122 | client: (surface = "home") => workspace.clientAs(actorUserId, surface), |
| 123 | clientAs: (userId, surface = "home") => { |
| 124 | const client = capabilities( |
| 125 | surface === "preview" ? "read" : "destructive", |
| 126 | true, |
| 127 | false, |
| 128 | userId, |
| 129 | ); |
| 130 | return { |
| 131 | ...client, |
| 132 | tools: { |
| 133 | invoke: async (name, input = {}) => { |
| 134 | const { createCapabilityGate } = await import("../capabilities/gate"); |
| 135 | createCapabilityGate({ |
| 136 | manifestPermissions: app.manifest.permissions, |
| 137 | grantedPermissions: options.grantedPermissions ?? app.manifest.permissions, |
| 138 | effectCeiling: surface === "preview" ? "read" : "destructive", |
| 139 | }).assert("tools.invoke"); |
| 140 | const result = await workspace.invokeTool(name, input, userId); |
| 141 | return { output: result.output, ...(result.card ? { card: result.card } : {}) }; |
| 142 | }, |
| 143 | }, |
| 144 | }; |
| 145 | }, |
| 146 | files: { |
| 147 | byType: (typeKey) => |
| 148 | state |
| 149 | .filesByType(typeKey) |
| 150 | .map((file) => ({ fileId: file.fileId, name: file.name, document: file.document })), |
| 151 | all: () => |
| 152 | [...state.files.values()] |
| 153 | .filter((file) => !file.trashed) |
| 154 | .map((file) => ({ fileId: file.fileId, name: file.name, typeKey: file.typeKey })), |
| 155 | }, |
| 156 |
| 157 | async invokeTool(name, input, userId = actorUserId) { |
| 158 | const tool = app.runtime.tools.get(name); |
| 159 | if (!tool) { |
| 160 | throw new Error(`App "${app.manifest.key}" does not define tool "${name}".`); |
| 161 | } |
| 162 | const parsed = tool.input.safeParse(input); |
| 163 | if (!parsed.success) { |
| 164 | throw new Error( |
| 165 | `Tool input is invalid: ${parsed.error.issues |
| 166 | .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`) |
| 167 | .join("; ")}`, |
| 168 | ); |
| 169 | } |
| 170 | const result: ColineToolResult = await tool.execute(parsed.data as never, { |
| 171 | ...base, |
| 172 | coline: capabilities(tool.effect, false, false, userId), |
| 173 | actor: { kind: "user", userId }, |
| 174 | }); |
| 175 | let card: ColineUiNode | null = null; |
| 176 | if (result.card) { |
| 177 | const validation = validateChatCardTree(result.card); |
| 178 | if (!validation.ok) { |
| 179 | throw new Error(`Tool card rejected: ${validation.reason}`); |
| 180 | } |
| 181 | card = result.card; |
| 182 | } |
| 183 | return { output: result.output, card }; |
| 184 | }, |
| 185 |
| 186 | async renderHome() { |
| 187 | if (!app.runtime.renderHome) { |
| 188 | throw new Error(`App "${app.manifest.key}" has no tree home handler.`); |
| 189 | } |
| 190 | const context: ColineHomeRenderContextV2 = { |
| 191 | ...base, |
| 192 | actor: { kind: "user", userId: actorUserId }, |
| 193 | }; |
| 194 | return app.runtime.renderHome(context); |
| 195 | }, |
| 196 |
| 197 | async renderFileSurface(surface, file, document = {}) { |
| 198 | const runtime = app.runtime.fileTypes.get(file.typeKey); |
| 199 | const handler = |
| 200 | surface === "editor" |
| 201 | ? runtime?.renderEditor |
| 202 | : surface === "preview" |
| 203 | ? runtime?.renderPreview |
| 204 | : runtime?.renderInline; |
| 205 | if (!handler) { |
| 206 | throw new Error(`File type "${file.typeKey}" has no ${surface} handler.`); |
| 207 | } |
| 208 | const context: ColineFileRenderContextV2 = { |
| 209 | ...base, |
| 210 | actor: { kind: "user", userId: actorUserId }, |
| 211 | file: { version: 1, ...file }, |
| 212 | document, |
| 213 | }; |
| 214 | const tree = await handler(context); |
| 215 | if (surface === "inline") { |
| 216 | const validation = validateChatCardTree(tree); |
| 217 | if (!validation.ok) { |
| 218 | throw new Error(`Inline surface rejected: ${validation.reason}`); |
| 219 | } |
| 220 | } |
| 221 | return tree; |
| 222 | }, |
| 223 |
| 224 | async fireSchedule(scheduleId, at = new Date()) { |
| 225 | if (!app.runtime.onSchedule) { |
| 226 | throw new Error(`App "${app.manifest.key}" has no schedule handler.`); |
| 227 | } |
| 228 | const declared = app.manifest.triggers.schedules.find( |
| 229 | (schedule) => schedule.id === scheduleId, |
| 230 | ); |
| 231 | if (!declared) { |
| 232 | throw new Error(`Schedule "${scheduleId}" is not declared in the manifest.`); |
| 233 | } |
| 234 | const context: ColineScheduleContextV2 = { |
| 235 | coline: capabilities("write", false, true), |
| 236 | workspace: base.workspace, |
| 237 | app: base.app, |
| 238 | scheduleId, |
| 239 | firedAt: at.toISOString(), |
| 240 | }; |
| 241 | await app.runtime.onSchedule(context); |
| 242 | }, |
| 243 | }; |
| 244 | return workspace; |
| 245 | } |
| 246 |