232 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 | files: { |
| 42 | byType( |
| 43 | typeKey: string, |
| 44 | ): Array<{ fileId: string; name: string; document: Record<string, unknown> }>; |
| 45 | all(): Array<{ fileId: string; name: string; typeKey: string }>; |
| 46 | }; |
| 47 | invokeTool(name: string, input: unknown): Promise<InvokeToolResult>; |
| 48 | renderHome(): Promise<ColineUiNode>; |
| 49 | renderFileSurface( |
| 50 | surface: "editor" | "preview" | "inline", |
| 51 | file: { fileId: string; name: string; typeKey: string; version?: number }, |
| 52 | document?: Record<string, unknown>, |
| 53 | ): Promise<ColineUiNode>; |
| 54 | fireSchedule(scheduleId: string, at?: Date): Promise<void>; |
| 55 | } |
| 56 |
| 57 | export function createTestWorkspace( |
| 58 | app: ColineAppV2, |
| 59 | options: TestWorkspaceOptions = {}, |
| 60 | ): TestWorkspace { |
| 61 | const state = new TestWorkspaceState(); |
| 62 | const resolved = { |
| 63 | workspaceId: options.workspaceId ?? "ws_test", |
| 64 | workspaceSlug: options.workspaceSlug ?? "test-workspace", |
| 65 | workspaceName: options.workspaceName ?? "Test Workspace", |
| 66 | appKey: options.appKey ?? app.manifest.key, |
| 67 | installId: options.installId ?? "inst_test", |
| 68 | }; |
| 69 | const members: ColineMemberSummary[] = (options.members ?? [{ userId: "user_test" }]).map( |
| 70 | (member) => ({ |
| 71 | userId: member.userId, |
| 72 | email: member.email ?? `${member.userId}@example.com`, |
| 73 | handle: member.handle ?? member.userId, |
| 74 | firstName: member.firstName ?? "Test", |
| 75 | lastName: member.lastName ?? "User", |
| 76 | avatarUrl: member.avatarUrl ?? null, |
| 77 | }), |
| 78 | ); |
| 79 | const actorUserId = members[0]?.userId ?? "user_test"; |
| 80 |
| 81 | function capabilities(effect: ToolEffect, interactive = false, appPrincipal = false) { |
| 82 | const raw = createFakeCapabilities(state, { |
| 83 | ...resolved, |
| 84 | members, |
| 85 | actor: appPrincipal ? { kind: "app" } : { kind: "user", userId: actorUserId }, |
| 86 | onNetFetch: options.onNetFetch, |
| 87 | onAiGenerate: options.onAiGenerate, |
| 88 | pickers: options.pickers ?? {}, |
| 89 | }); |
| 90 | return guardTestCapabilities( |
| 91 | raw, |
| 92 | { |
| 93 | manifestPermissions: app.manifest.permissions, |
| 94 | grantedPermissions: options.grantedPermissions ?? app.manifest.permissions, |
| 95 | effectCeiling: effect, |
| 96 | }, |
| 97 | { interactive, appPrincipal }, |
| 98 | ); |
| 99 | } |
| 100 | const coline = capabilities("read"); |
| 101 |
| 102 | const base = { |
| 103 | coline, |
| 104 | workspace: { |
| 105 | workspaceId: resolved.workspaceId, |
| 106 | workspaceSlug: resolved.workspaceSlug, |
| 107 | workspaceName: resolved.workspaceName, |
| 108 | }, |
| 109 | app: { appKey: resolved.appKey, installId: resolved.installId }, |
| 110 | }; |
| 111 |
| 112 | const workspace: TestWorkspace = { |
| 113 | state, |
| 114 | client: (surface = "home") => { |
| 115 | const client = capabilities(surface === "preview" ? "read" : "destructive", true); |
| 116 | return { |
| 117 | ...client, |
| 118 | tools: { |
| 119 | invoke: async (name, input = {}) => { |
| 120 | const { createCapabilityGate } = await import("../capabilities/gate"); |
| 121 | createCapabilityGate({ |
| 122 | manifestPermissions: app.manifest.permissions, |
| 123 | grantedPermissions: options.grantedPermissions ?? app.manifest.permissions, |
| 124 | effectCeiling: surface === "preview" ? "read" : "destructive", |
| 125 | }).assert("tools.invoke"); |
| 126 | const result = await workspace.invokeTool(name, input); |
| 127 | return { output: result.output, ...(result.card ? { card: result.card } : {}) }; |
| 128 | }, |
| 129 | }, |
| 130 | }; |
| 131 | }, |
| 132 | files: { |
| 133 | byType: (typeKey) => |
| 134 | state |
| 135 | .filesByType(typeKey) |
| 136 | .map((file) => ({ fileId: file.fileId, name: file.name, document: file.document })), |
| 137 | all: () => |
| 138 | [...state.files.values()] |
| 139 | .filter((file) => !file.trashed) |
| 140 | .map((file) => ({ fileId: file.fileId, name: file.name, typeKey: file.typeKey })), |
| 141 | }, |
| 142 |
| 143 | async invokeTool(name, input) { |
| 144 | const tool = app.runtime.tools.get(name); |
| 145 | if (!tool) { |
| 146 | throw new Error(`App "${app.manifest.key}" does not define tool "${name}".`); |
| 147 | } |
| 148 | const parsed = tool.input.safeParse(input); |
| 149 | if (!parsed.success) { |
| 150 | throw new Error( |
| 151 | `Tool input is invalid: ${parsed.error.issues |
| 152 | .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`) |
| 153 | .join("; ")}`, |
| 154 | ); |
| 155 | } |
| 156 | const result: ColineToolResult = await tool.execute(parsed.data as never, { |
| 157 | ...base, |
| 158 | coline: capabilities(tool.effect), |
| 159 | actor: { kind: "user", userId: actorUserId }, |
| 160 | }); |
| 161 | let card: ColineUiNode | null = null; |
| 162 | if (result.card) { |
| 163 | const validation = validateChatCardTree(result.card); |
| 164 | if (!validation.ok) { |
| 165 | throw new Error(`Tool card rejected: ${validation.reason}`); |
| 166 | } |
| 167 | card = result.card; |
| 168 | } |
| 169 | return { output: result.output, card }; |
| 170 | }, |
| 171 |
| 172 | async renderHome() { |
| 173 | if (!app.runtime.renderHome) { |
| 174 | throw new Error(`App "${app.manifest.key}" has no tree home handler.`); |
| 175 | } |
| 176 | const context: ColineHomeRenderContextV2 = { |
| 177 | ...base, |
| 178 | actor: { kind: "user", userId: actorUserId }, |
| 179 | }; |
| 180 | return app.runtime.renderHome(context); |
| 181 | }, |
| 182 |
| 183 | async renderFileSurface(surface, file, document = {}) { |
| 184 | const runtime = app.runtime.fileTypes.get(file.typeKey); |
| 185 | const handler = |
| 186 | surface === "editor" |
| 187 | ? runtime?.renderEditor |
| 188 | : surface === "preview" |
| 189 | ? runtime?.renderPreview |
| 190 | : runtime?.renderInline; |
| 191 | if (!handler) { |
| 192 | throw new Error(`File type "${file.typeKey}" has no ${surface} handler.`); |
| 193 | } |
| 194 | const context: ColineFileRenderContextV2 = { |
| 195 | ...base, |
| 196 | actor: { kind: "user", userId: actorUserId }, |
| 197 | file: { version: 1, ...file }, |
| 198 | document, |
| 199 | }; |
| 200 | const tree = await handler(context); |
| 201 | if (surface === "inline") { |
| 202 | const validation = validateChatCardTree(tree); |
| 203 | if (!validation.ok) { |
| 204 | throw new Error(`Inline surface rejected: ${validation.reason}`); |
| 205 | } |
| 206 | } |
| 207 | return tree; |
| 208 | }, |
| 209 |
| 210 | async fireSchedule(scheduleId, at = new Date()) { |
| 211 | if (!app.runtime.onSchedule) { |
| 212 | throw new Error(`App "${app.manifest.key}" has no schedule handler.`); |
| 213 | } |
| 214 | const declared = app.manifest.triggers.schedules.find( |
| 215 | (schedule) => schedule.id === scheduleId, |
| 216 | ); |
| 217 | if (!declared) { |
| 218 | throw new Error(`Schedule "${scheduleId}" is not declared in the manifest.`); |
| 219 | } |
| 220 | const context: ColineScheduleContextV2 = { |
| 221 | coline: capabilities("write", false, true), |
| 222 | workspace: base.workspace, |
| 223 | app: base.app, |
| 224 | scheduleId, |
| 225 | firedAt: at.toISOString(), |
| 226 | }; |
| 227 | await app.runtime.onSchedule(context); |
| 228 | }, |
| 229 | }; |
| 230 | return workspace; |
| 231 | } |
| 232 |