create-coline-app 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-coline-app",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Scaffold, push, and iterate on Coline Apps.",
   "type": "module",
   "bin": {

package/templates/backendless/AGENTS.md

@@ -0,0 +1,196 @@
+# AGENTS.md — building __APP_NAME__ (a Coline App)
+
+You are working on a Coline App. Everything an agent needs is in this file —
+no URLs required. The scaffold compiles, tests, and runs as-is; evolve it
+rather than starting from a blank page.
+
+## What a Coline App is
+
+A Coline App runs INSIDE a Coline workspace on Coline's hosted runtime.
+There are no servers, no database, no auth, no deploys — the platform
+provides all of it through the `coline.*` capability API:
+
+- `app.config.ts` — the ENTIRE backend: manifest + tools + file types +
+  UI handlers, bundled and executed server-side by Coline.
+- `main.tsx` (optional) — a React UI running in a locked sandbox iframe.
+  Create it only if the manifest declares a `react` tier surface.
+- `app.test.ts` — tests against an in-memory fake workspace.
+
+## Commands
+
+- `npm test` — run tests (in-memory workspace; no Coline instance needed)
+- `npm run typecheck` — strict TS; keep it clean
+- `npx coline-app dev --internal` — watch mode; every save pushes a
+  `0.0.0-dev` version that hot-swaps the live app (reload the app page)
+- `npx coline-app push --internal` — one-off push as a workspace-internal
+  app (auto-approved, private to the workspace)
+- Needs `COLINE_API_KEY` (workspace API key with `apps.write` scope) and
+  `COLINE_BASE_URL` (the Coline instance) in the environment.
+
+## The manifest (`defineApp`)
+
+```ts
+export default defineApp({
+  key: "__APP_KEY__",           // immutable, lowercase, hyphens
+  name: "__APP_NAME__",
+  description: "…",
+  permissions: [...],            // ONLY what you use — users see this list
+  hosting: { default: "coline" },// hosted runtime (no external server)
+  surfaces: { home: { tier: "tree" } }, // or { tier: "react" } with main.tsx
+  files: [...],                  // custom file types (optional)
+  tools: [...],                  // Kairo tools (optional)
+  handlers: { renderHome: async (context) => uiNode },
+});
+```
+
+### Permissions (request the minimum)
+
+| key | grants |
+| --- | --- |
+| `storage.app` | app key-value + record collections |
+| `files.read` / `files.write` | read / create workspace files |
+| `drives.app` | a private drive owned by the app |
+| `members.read` | list workspace members |
+| `search.index` / `search.query` | add to / query workspace search |
+| `notifications.write` | send notifications |
+| `ai.generate` | call Coline's AI model (200/day) |
+| `ai.tools` | expose tools to Kairo (the workspace AI) |
+| `events.emit` | publish app events |
+| `commands.register` | add command-palette commands |
+| `realtime.subscribe` | live updates in the UI |
+| `network.external` | HTTPS fetch to allowlisted hosts only |
+
+## Tools (`defineTool`) — how Kairo operates your app
+
+```ts
+const logDecision = defineTool({
+  name: "__APP_KEY__.log_decision",   // MUST be prefixed with the app key
+  description: "…",                    // what Kairo reads to pick the tool
+  input: z.object({ title: z.string().min(1) }),  // zod schema
+  effect: "write",                     // read | write | destructive | external
+  execute: async (input, context) => {
+    // context.coline — the capability client
+    // context.workspace — { id, slug, name }
+    // context.actor — who invoked it
+    return {
+      output: { id: "…" },            // structured result for the model
+      card: ui.stack([...]),           // optional rich card shown in chat
+    };
+  },
+});
+```
+
+`effect` is ENFORCED by the runtime, not a hint: a `read` tool cannot
+write. Reads auto-approve; `write` follows the session's permission mode;
+`destructive`/`external` always prompt the user. Be honest.
+
+## Storage — `coline.storage`
+
+```ts
+// Key-value
+await context.coline.storage.kv.set("settings", { theme: "auto" });
+const settings = await context.coline.storage.kv.get("settings");
+
+// Typed record collections (the main data store)
+interface Decision { title: string; status: "proposed" | "decided"; tags: string[] }
+const decisions = context.coline.storage.collection<Decision>("decisions");
+
+const rec = await decisions.insert({ title: "Use Postgres", status: "decided", tags: ["infra"] });
+await decisions.update(rec.id, { status: "proposed" });
+await decisions.get(rec.id);            // envelope | null
+await decisions.delete(rec.id);
+const { records, nextCursor } = await decisions.query({
+  where: { status: "decided" },          // exact-match on top-level fields
+  orderBy: "title", order: "asc",       // or omit for newest-first
+  limit: 50, cursor: undefined,
+});
+// Every record comes wrapped: { id, createdBy, createdAt, updatedAt, data }
+```
+
+Limits: 5,000 kv keys · 200,000 records per collection · 200 kB per value.
+`query.where` is exact-match only — filter/search in memory after querying
+when you need contains/ranges (keep result sets bounded with `limit`).
+
+## UI — two tiers
+
+### Tree tier (`ui.*` builders) — renders everywhere incl. mobile & chat cards
+
+`ui.stack(children, { direction?, gap? })` · `ui.row(children)` ·
+`ui.heading(text, { level? 1-4 })` · `ui.text(text, { tone? })` ·
+`ui.badge(text, { tone? })` · `ui.card({ title?, description?, children?, footer? })` ·
+`ui.button({ label, action, variant? })` · `ui.divider()` ·
+`ui.emptyState({ title, description? })` · `ui.fileCard({ title, fileId, action? })` ·
+`ui.table({ columns, rows })` · `ui.link({ label, href })` · `ui.image({ src, alt })`
+
+Tones: `default | muted | positive | warning | danger`.
+Actions: `actions.openFile(fileId)`, `actions.openAppHome()`,
+`actions.navigate(path)`, `actions.createFile(...)`, `actions.custom(name, payload)`.
+Chat cards (tool results) allow a validated subset — keep them simple
+(stack/heading/text/badge/table/fileCard are all safe). Max 120 nodes.
+
+### React tier (`main.tsx` + `@colineapp/ui`) — full React in a sandbox
+
+Set `surfaces: { home: { tier: "react" } }` and create `main.tsx`:
+
+```tsx
+import { createRoot } from "react-dom/client";
+import { ColineAppProvider, useColine, useColineQuery, useColineContext } from "@colineapp/ui";
+
+function Home() {
+  const coline = useColine();                       // capability client
+  const { data, isLoading, error, refetch } =      // simple async hook
+    useColineQuery(() => coline.storage.collection("decisions").query({ limit: 100 }), []);
+  // …render
+}
+
+const root = document.getElementById("root");
+if (root) createRoot(root).render(<ColineAppProvider><Home /></ColineAppProvider>);
+```
+
+Sandbox rules (enforced, not conventions):
+- NO network (`fetch` is blocked by CSP), no localStorage, no cookies.
+  ALL data flows through the `coline.*` client over the capability bridge.
+- Theme tokens follow the host automatically (dark mode included) — use
+  the CSS variables / `@colineapp/ui` components, never hardcoded colors.
+- One bundle per app: switch on `useColineContext().surface` if you have
+  multiple react surfaces.
+
+## Rate limits & budgets
+
+120 capability calls burst / 20 per second per install · `net.fetch`
+20 burst / 2 per second · `ai.generate` 200/day · 10,000 executions/day.
+Exceeding any returns a named error visible in the execution log.
+
+## Testing (`app.test.ts` pattern)
+
+```ts
+import { describe, expect, it } from "vitest";
+import { createTestWorkspace } from "@colineapp/sdk/testing";
+import app from "./app.config";
+
+it("logs a decision", async () => {
+  const workspace = createTestWorkspace(app);
+  const result = await workspace.invokeTool("__APP_KEY__.log_decision", {
+    title: "Use Postgres",
+  });
+  expect(result.card).not.toBeNull();       // result: { output, card }
+  // Also available: workspace.renderHome(), workspace.files.byType(...),
+  // workspace.renderFileSurface(...), workspace.fireSchedule(...)
+});
+```
+
+## Debugging
+
+- Tool throws → the error lands in the app's execution log (developer
+  console → your app → Executions) with the message redacted of secrets.
+- Permission denied → the manifest doesn't declare it, the user didn't
+  grant it, or the tool's `effect` is too low for the operation.
+- UI blank → check the browser console for the sandbox frame; the
+  capability bridge logs denials with reason codes.
+
+## Style rules for the UI
+
+- No eyebrow labels / kicker pills above headings. No monospace accent
+  fonts. Solid font weights (500–600).
+- Explicit loading, empty, and error states for every async view.
+- Dark mode must work — it's automatic if you use theme tokens.

package/templates/backendless/CLAUDE.md

@@ -0,0 +1,5 @@
+# Claude Instructions
+
+Read and follow [`AGENTS.md`](./AGENTS.md) — it contains the complete
+Coline App contract: capabilities, tools, storage, UI builders, sandbox
+rules, limits, and testing patterns.

package/templates/backendless/app.config.ts

@@ -65,27 +65,43 @@ export default defineApp({
   files: [noteFileType],
   tools: [createNote],
   handlers: {
+    // The starter home screen — replace this with your app's real UI.
     renderHome: async (context) => {
       const { files } = await context.coline.files.list({
         typeKey: "__APP_KEY__.note",
       });
-      return ui.stack([
-        ui.heading("__APP_NAME__"),
-        files.length === 0
-          ? ui.emptyState({
-              title: "No notes yet",
-              description: "Ask Kairo to create one.",
-            })
-          : ui.stack(
-              files.map((file) =>
-                ui.fileCard({
-                  title: file.name,
-                  fileId: file.fileId,
-                  action: actions.openFile(file.fileId),
-                }),
-              ),
-            ),
-      ]);
+      return ui.stack(
+        [
+          ui.heading("__APP_NAME__ is running", { level: 1 }),
+          ui.text("Edit app.config.ts and save — dev mode hot-swaps this screen instantly.", {
+            tone: "muted",
+          }),
+          ui.card({
+            title: "Try the example tool",
+            description:
+              "This starter ships one Kairo tool and one file type. Ask Kairo: “create a note called Hello”.",
+            children:
+              files.length === 0
+                ? [ui.text("Notes it creates will show up here.", { tone: "muted" })]
+                : files.map((file) =>
+                    ui.fileCard({
+                      title: file.name,
+                      fileId: file.fileId,
+                      action: actions.openFile(file.fileId),
+                    }),
+                  ),
+          }),
+          ui.card({
+            title: "Where things live",
+            children: [
+              ui.text("app.config.ts — manifest, tools, file types, this screen"),
+              ui.text("app.test.ts — tests against an in-memory workspace"),
+              ui.text("Docs: /developers/docs · API reference: /developers/docs/reference"),
+            ],
+          }),
+        ],
+        { gap: "lg" },
+      );
     },
   },
 });