create-coline-app 2.2.0 → 2.5.0

package/templates/backendless/AGENTS.md

@@ -1,196 +1,81 @@
-# 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>);
+# Building __APP_NAME__
+
+Use the installed public packages, this project, and its examples. Do not inspect
+the private Coline product repository to discover app APIs. User instructions
+and the product's existing design take precedence over starter preferences.
+
+## Start here
+
+- `app.config.ts`: hosted manifest, permissions, tools, file types, tree fallbacks.
+- `main.tsx`: sandboxed React home/editor inside `ColineAppProvider`.
+- `app.css`: app styling. Tailwind v4 and ordinary CSS compile automatically.
+- `preview.seed.ts`: disposable local fixtures; never imported by production entries.
+- `examples/`: working UI references with local state, not persistent business data.
+- `app.test.ts`: logic tests using the public in-memory workspace.
+
+For UI work, read `.agents/skills/coline-ui-design/SKILL.md`, choose the closest
+example, then use `.agents/skills/coline-ui-review/SKILL.md` to finish. These
+experimental skills are plain Markdown: follow them even if your agent has no
+skill loader. Development details: `.agents/skills/coline-app-development/SKILL.md`.
+
+## Working loop
+
+```sh
+npm install
+npm test
+npm run check
+npm run preview
+# Other working screen references:
+npm run preview -- --pattern triage
+npm run preview -- --pattern board
+npm run preview -- --pattern settings
+# Install Chromium once for captures:
+npx playwright install chromium
+npm run screenshots
 ```
 
-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.
+Preview uses simulated data, requires no credentials, resets on reload, and
+reloads when source changes. Theme and state selectors expose ready, empty,
+error, loading, and permission-denied states. Screenshots and a mechanical
+browser report go in `.coline/screenshots`. Inspect the pictures and exercise
+controls: passing checks cannot prove that a UI looks good.
+Stop only the preview terminal session/PID you started; never kill processes by
+a shared name. The screenshot command cleans up its own server.
+
+`npm run dev -- --internal` and `npm run push -- --internal` upload to Coline.
+They need `COLINE_API_KEY` with `apps.write`; `COLINE_BASE_URL` selects the host.
+Use these when publishing is in the user's scope. Local preview is not proof of
+hosted authorization, persistence, multiplayer, delivery, or performance.
+
+## Build with the public contract
+
+Use `@colineapp/sdk/v2`, `@colineapp/sdk/testing`, and `@colineapp/ui`.
+Import UI styles, then `./app.css`. Use complete utility class strings;
+`bg-${tone}` cannot be discovered by Tailwind. Use a fixed class map instead.
+The CLI bundles installed browser-compatible dependencies, CSS, and inline
+assets; there is no separate CSS command. Do not import preview fixtures into
+`main.tsx` or `app.config.ts`.
+
+Use `useColine()` for capabilities. `useColineQuery(loader, deps)` provides
+bounded loading/error/refetch for files and other reads. For collaborative
+records use `useLiveCollection`; it owns optimistic updates, version checks,
+reconciliation, and subscriptions. Catch mutation rejections, show recovery,
+and never retry a conflicting write blindly. Check installed declarations for
+query operators and method arguments; do not guess APIs.
+
+Store documents as files and structured app data in install-private collections.
+Use `expectedVersion` when saving a document. Record access policies enforce
+workspace/readers/writers on the server; hiding a button is not authorization.
+Native tasks/calendar/messages/references and shared files require explicit
+permissions and retain the invoking user's access. Render handlers/previews are
+read-only; interactive home/editor capabilities can write within grants.
+
+Prefix tools with the app key, validate input with `zod/v4`, and declare honest
+effects. UI can call `coline.tools.invoke` to share a tool with Kairo. Tree
+handlers use `ui.*`; chat cards use the restricted chat subset. Use tree mobile
+fallbacks where declared; a narrow browser preview does not prove native mobile.
+
+No direct API routes, credentials, cookies, or localStorage in the sandbox.
+External calls use `coline.net.fetch` and declared allowlists. Keep React state
+for transient UI, not as a substitute for saved records. Do not imply CRDT text
+editing, durable offline queues, presence, or public hosting from live records.

package/templates/backendless/CLAUDE.md

@@ -1,5 +1 @@
-# 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.
+Read AGENTS.md before working. It contains the public SDK contract, local preview commands, and links to the bundled experimental UI skills.

package/templates/backendless/README.md

@@ -1,38 +1,33 @@
 # __APP_NAME__
 
-A backendless Coline App. The logic in `app.config.ts` runs on Coline's
-hosted runtime — no servers to deploy.
-
-## Develop
+A Coline App with a working notes home, editor, tool, and tree fallback.
 
 ```sh
 npm install
-npm test          # runs against the in-memory test workspace
+npm test
+npm run check
+npm run preview
 ```
 
-## Push to Coline
-
-Create a workspace API key with the `apps.write` scope in
-**Workspace Settings → API**, then:
+Preview runs locally with disposable fixtures, no account or API key. Try its
+light/dark themes and ready/empty/error/loading/permission states. Source edits
+reload the preview. `preview.seed.ts` defines local fixtures.
 
-```sh
-export COLINE_API_KEY=col_ws_...
-npm run push
-```
+For other layouts, run `npm run preview -- --pattern triage`, `board`, or
+`settings`. Copy and adapt the examples to your product, then connect their local
+state to SDK data. `app.css` supports ordinary CSS and automatically compiled
+Tailwind utilities.
 
-Versions land in your developer console in draft state. Use
-`npm run dev` to watch the project and push on every change.
+For browser captures, install Chromium once with `npx playwright install chromium`,
+then run `npm run screenshots`. Inspect `.coline/screenshots` and its report.
+This catches browser errors, overflow, and missing form labels; visual quality
+and interactions still need review.
 
-## Grow the app
+Read [AGENTS.md](AGENTS.md) for the SDK contract and bundled experimental design,
+development, and review skills. They work as plain instructions with any agent;
+models with limited visual or tool abilities may need human review.
 
-- Add Kairo tools with `defineTool` — declare the honest `effect`
-  (`read` / `write` / `destructive` / `external`); the runtime enforces
-  it as a capability ceiling.
-- Add file types with `defineFileType` — tree previews render everywhere
-  Coline shows files, including mobile and Kairo chat.
-- Add a React editor by setting a file surface to
-  `{ tier: "react", entry: "main.tsx" }` and creating `main.tsx`.
-- Store app-private data with `coline.storage.kv` and
-  `coline.storage.collection(name)`.
-- Call external APIs with `coline.net.fetch` after declaring
-  `network.external` hosts in the manifest.
+To upload, set `COLINE_API_KEY` (workspace key with `apps.write`) and optionally
+`COLINE_BASE_URL`, then run `npm run push -- --internal`. `npm run dev -- --internal`
+watches and updates a development version. Local preview does not test production
+persistence, authorization, multiplayer, or deployment.

package/templates/backendless/app.config.ts

@@ -1,7 +1,7 @@
 import { z } from "zod/v4";
 import { actions, defineApp, defineFileType, defineTool, ui } from "@colineapp/sdk/v2";
 
-// __APP_NAME__ — a backendless Coline App. Everything here runs on
+// __APP_NAME__ — a hosted, backendless Coline App. Everything here runs on
 // Coline's hosted runtime: no servers, no deploys. `coline-app push`
 // uploads this file as the logic bundle and main.tsx as client source.
 
@@ -11,16 +11,14 @@ const noteFileType = defineFileType({
     name: "__APP_NAME__ Note",
     indexable: true,
     surfaces: {
+      editor: { tier: "react", entry: "main.tsx" },
       preview: { tier: "tree" },
       inline: { tier: "tree" },
     },
   },
   runtime: {
     renderPreview: (context) =>
-      ui.stack([
-        ui.heading(context.file.name),
-        ui.text(String(context.document.body ?? "")),
-      ]),
+      ui.stack([ui.heading(context.file.name), ui.text(String(context.document.body ?? ""))]),
     renderInline: (context) => ui.text(context.file.name),
     index: {
       title: (document) => String(document.title ?? "Untitled note"),
@@ -41,7 +39,7 @@ const createNote = defineTool({
     const file = await context.coline.files.create({
       typeKey: "__APP_KEY__.note",
       name: input.title,
-      document: { body: input.body },
+      document: { title: input.title, body: input.body },
     });
     return {
       output: { fileId: file.fileId },
@@ -57,15 +55,19 @@ export default defineApp({
   key: "__APP_KEY__",
   name: "__APP_NAME__",
   description: "A starter Coline App.",
-  permissions: ["files.read", "files.write", "storage.app", "ai.tools"],
+  permissions: ["files.read", "files.write", "storage.app", "ai.tools", "drives.app"],
   hosting: { default: "coline" },
   surfaces: {
-    home: { tier: "tree" },
+    home: {
+      tier: "react",
+      entry: "main.tsx",
+      mobile: { tier: "tree" },
+    },
   },
   files: [noteFileType],
   tools: [createNote],
   handlers: {
-    // The starter home screen — replace this with your app's real UI.
+    // The mobile/tree fallback. The React home lives in main.tsx.
     renderHome: async (context) => {
       const { files } = await context.coline.files.list({
         typeKey: "__APP_KEY__.note",
@@ -73,9 +75,15 @@ export default defineApp({
       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.button("New note", {
+            action: actions.invokeTool("__APP_KEY__.create_note", { title: "Untitled note" }),
           }),
+          ui.text(
+            "Edit app.config.ts and save — dev mode updates this app; reload to see changes.",
+            {
+              tone: "muted",
+            },
+          ),
           ui.card({
             title: "Try the example tool",
             description:

package/templates/backendless/app.css

@@ -0,0 +1,84 @@
+/* Compiled automatically by check, preview, dev, and push. Use complete class names. */
+@import "tailwindcss";
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --radius-3xl: calc(var(--radius) + 12px);
+  --radius-4xl: calc(var(--radius) + 16px);
+}
+
+body {
+  margin: 0;
+}
+.note-editor {
+  display: grid;
+  gap: 24px;
+}
+.note-editor label {
+  display: grid;
+  gap: 8px;
+  font-size: 13px;
+  font-weight: 500;
+}
+.note-editor textarea {
+  min-height: 340px;
+  line-height: 1.7;
+}
+.example-meta {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--muted-foreground);
+  font-size: 12px;
+}
+.example-select {
+  border: 1px solid var(--border);
+  background: var(--background);
+  color: var(--foreground);
+  border-radius: 6px;
+  padding: 7px 9px;
+  font: inherit;
+  max-width: 100%;
+}
+.example-field {
+  display: grid;
+  gap: 8px;
+  font-size: 13px;
+}
+.example-description {
+  font-size: 13px;
+  line-height: 1.7;
+  color: var(--muted-foreground);
+}
+
+.coline-settings-fields .example-toggle {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+.example-description {
+  margin: 12px 0 18px;
+}