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