76 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 |
| 7 | ## Public entry points |
| 8 |
| 9 | - `@colineapp/sdk/v2` is the current app-authoring API: `defineApp`, |
| 10 | `defineTool`, `defineFileType`, `defineCommand`, `ui`, `actions`, manifest |
| 11 | schemas, capability types, and hosted protocol helpers. |
| 12 | - `@colineapp/sdk/testing` provides `createTestWorkspace`, the in-memory |
| 13 | capability fake used by app tests. |
| 14 | - `@colineapp/sdk` is the legacy v1 surface. Do not use it for new apps. |
| 15 |
| 16 | ## Contract map |
| 17 |
| 18 | - `src/define/` extracts and validates an app definition. |
| 19 | - `src/manifest/` defines the consented manifest: permissions, surfaces, |
| 20 | file types, tools, hosting, triggers, and commands. |
| 21 | - `src/capabilities/types.ts` is the transport-neutral `coline.*` contract. |
| 22 | - `src/tree/tree.ts` is the tree UI builder API used by hosted handlers and |
| 23 | Kairo cards. `src/tree/chat-card.ts` defines the stricter chat subset. |
| 24 | - `src/testing/` must stay behaviorally aligned with the capability types. |
| 25 |
| 26 | ## App-authoring rules |
| 27 |
| 28 | ```ts |
| 29 | import { z } from "zod/v4"; |
| 30 | import { defineApp, defineTool, ui } from "@colineapp/sdk/v2"; |
| 31 |
| 32 | const createThing = defineTool({ |
| 33 | name: "things.create_thing", |
| 34 | description: "Create a thing.", |
| 35 | input: z.object({ title: z.string().min(1) }), |
| 36 | effect: "write", |
| 37 | execute: async (input) => ({ |
| 38 | output: { title: input.title }, |
| 39 | card: ui.text(`Created ${input.title}.`), |
| 40 | }), |
| 41 | }); |
| 42 | ``` |
| 43 |
| 44 | - Tool names are app-key-prefixed (`app-key.operation`). |
| 45 | - Validate every tool input with Zod. |
| 46 | - `effect` is an enforced capability ceiling: reads are `read`, mutations are |
| 47 | `write`, destructive actions are `destructive`, and external side effects |
| 48 | are `external`. |
| 49 | - Request the minimum manifest permissions. A tool declaration does not grant |
| 50 | a capability by itself. |
| 51 | - Tree handlers return `ui.*` nodes. React surfaces use `@colineapp/ui`; the |
| 52 | SDK does not provide React components. |
| 53 | - App records are envelopes: `{ id, appId, installId, collection, |
| 54 | createdBy, createdAt, updatedAt, data }`. |
| 55 | - Collection queries support exact top-level `where`, `orderBy`, `order`, |
| 56 | `limit`, and `cursor`; contains/range filtering belongs in bounded app code. |
| 57 |
| 58 | ## Testing and changes |
| 59 |
| 60 | - Test tools with `createTestWorkspace(app).invokeTool(...)`. |
| 61 | - Assert cards with the chat-card validator and state with |
| 62 | `workspace.files`, `workspace.state`, or collection results. |
| 63 | - Run focused checks from the repository root: |
| 64 | `pnpm --filter @colineapp/sdk typecheck` and |
| 65 | `pnpm --filter @colineapp/sdk test`. |
| 66 | - When changing a public type, update the closest unit test and README example |
| 67 | in the same change. Keep v2 behavior transport-neutral. |
| 68 | - Never add a second capability client or a second tree schema. Extend the |
| 69 | canonical types and fake together. |
| 70 |
| 71 | ## Release hygiene |
| 72 |
| 73 | The package ships `dist/` plus this guide. Update the package version and |
| 74 | generated artifacts through the repository release process; never hand-edit a |
| 75 | declaration file to hide a type failure. |
| 76 |