create-coline-app 2.1.1 → 2.3.0

package/AGENTS.md

@@ -0,0 +1,62 @@
+# create-coline-app package agent guide
+
+This package owns the external developer experience: the `create-coline-app`
+scaffold and the `coline-app push/dev` CLI. The template is a tested public
+contract, not illustrative pseudocode.
+
+## Source of truth
+
+- `src/scaffold.ts` copies `templates/backendless` and replaces app
+  placeholders.
+- `src/push.ts` bundles `app.config.ts`, extracts the manifest, and collects
+  `main.tsx` plus app `.ts`, `.tsx`, and `.css` source for React surfaces.
+- `templates/backendless/AGENTS.md` is the primary guidance delivered to
+  every generated app.
+- `templates/backendless/.agents/skills/` contains the reusable task skill
+  discovered by OpenCode/Codex-style agents.
+
+## Non-negotiable scaffold contract
+
+After a clean `npx create-coline-app app && cd app && npm install`, the project
+must have a working backend example, a working React starter, accurate agent
+guidance, and tests that do not need the Coline product repository or a running
+Coline server.
+
+Keep these versions aligned in one release:
+
+- `@colineapp/sdk` — logic, manifest, capabilities, tree UI, test workspace
+- `@colineapp/ui` — React provider, hooks, components, stylesheet
+- `@colineapp/app-runtime` — transitive guest/host bridge dependency
+- `create-coline-app` — scaffold and push/dev CLI
+
+When any public API changes, update the package README, package `AGENTS.md`,
+template `AGENTS.md`, template skill, template dependencies, and the focused
+smoke test together.
+
+## Agent-safety rules
+
+- A generated app must be self-describing. Agents should not need to inspect
+  `/Users/radin/coline-app`, a worktree, or private first-party apps.
+- Do not make the template point at local workspace packages or private URLs.
+- Do not claim a dependency is “already wired” unless it is in the generated
+  `package.json` and exercised by the template.
+- Do not add a React example without the `main.tsx` entry, React peer packages,
+  CSS export, and a manifest surface that references it.
+- Keep external hosting, network, auth, and database claims explicit. The
+  default app is hosted and backendless.
+
+## Verification
+
+- Run `pnpm --filter create-coline-app typecheck` and
+  `pnpm --filter create-coline-app test`.
+- The CLI tests must assert placeholder replacement, exact package dependency
+  wiring, the React starter's presence, and that the app config bundles against
+  the real SDK source.
+- Never use a checked-in private app as the only proof that a public scaffold
+  works. Add the smallest self-contained fixture instead.
+
+## Release hygiene
+
+The package publishes `bin`, `src`, `templates`, `README.md`, `AGENTS.md`, and
+`LICENSE`. Bump the CLI version when the template contract changes. Publish
+the three runtime libraries first, then publish this CLI with matching ranges.

package/README.md

@@ -9,9 +9,10 @@ cd my-app && npm install && npm test
 
 Two binaries ship from this package:
 
-- **`create-coline-app <dir>`** — scaffolds a backendless app: a
-  `defineApp` config with a Kairo tool, a file type with tree surfaces,
-  a hosted home surface, and tests against `@colineapp/sdk/testing`.
+- **`create-coline-app <dir>`** — scaffolds a self-contained backendless app:
+  a `defineApp` config with a Kairo tool, a file type with tree surfaces, a
+  working React home using `@colineapp/ui`, mobile/tree fallback rendering,
+  agent guidance, and tests against `@colineapp/sdk/testing`.
 - **`coline-app push | dev`** — builds the logic bundle with esbuild,
   extracts the manifest through the two-artifact model (plan §6.2),
   collects client source when the manifest declares react surfaces, and
@@ -20,3 +21,8 @@ Two binaries ship from this package:
 
 The CLI never builds tier-2 client bundles itself — it ships source and
 Coline's reviewed build pipeline produces the bundle.
+
+The generated project includes `AGENTS.md` and
+`.agents/skills/coline-app-development/SKILL.md`. Those files are deliberately
+specific to the installed public packages so coding agents can work without
+reading Coline's private product repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-coline-app",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Scaffold, push, and iterate on Coline Apps.",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "src",
     "templates",
     "README.md",
+    "AGENTS.md",
     "LICENSE"
   ],
   "dependencies": {

package/src/cli.test.ts

@@ -48,8 +48,21 @@ describe("runCreate", () => {
     expect(config).not.toContain("__APP_KEY__");
     const packageJson = JSON.parse(await readFile(join(dir, "package.json"), "utf8")) as {
       name: string;
+      dependencies: Record<string, string>;
+      devDependencies: Record<string, string>;
     };
     expect(packageJson.name).toBe("team-crm");
+    expect(packageJson.dependencies["@colineapp/sdk"]).toBe("^0.3.1");
+    expect(packageJson.dependencies["@colineapp/ui"]).toBe("^0.3.1");
+    expect(packageJson.dependencies.react).toBe("^19.0.0");
+    expect(packageJson.dependencies["react-dom"]).toBe("^19.0.0");
+    expect(packageJson.devDependencies["create-coline-app"]).toBe("^2.3.0");
+    await expect(readFile(join(dir, "main.tsx"), "utf8")).resolves.toContain(
+      "ColineAppProvider",
+    );
+    await expect(
+      readFile(join(dir, ".agents/skills/coline-app-development/SKILL.md"), "utf8"),
+    ).resolves.toContain("Do not inspect");
     await expect(readFile(join(dir, ".gitignore"), "utf8")).resolves.toContain("node_modules");
   });
 
@@ -97,4 +110,39 @@ describe("runCreate", () => {
     expect(imported.default.manifest.key).toBe("smoke-app");
     expect(imported.default.manifest.tools[0]?.name).toBe("smoke-app.create_note");
   });
+
+  it("contains a React starter that bundles against the public UI packages", async () => {
+    const dir = await scaffoldTemp("react-smoke");
+    const packagesRoot = resolve(__dirname, "..", "..");
+    const sdkRoot = join(packagesRoot, "sdk");
+    const runtimeRoot = join(packagesRoot, "app-runtime");
+    const uiRoot = join(packagesRoot, "coline-ui");
+    const sdkRequire = createRequire(join(sdkRoot, "package.json"));
+    const uiRequire = createRequire(join(uiRoot, "package.json"));
+    const result = await build({
+      entryPoints: [join(dir, "main.tsx")],
+      bundle: true,
+      write: false,
+      format: "iife",
+      platform: "browser",
+      target: "es2022",
+      jsx: "automatic",
+      logLevel: "silent",
+      absWorkingDir: packagesRoot,
+      nodePaths: [resolve(packagesRoot, "..", "node_modules")],
+      alias: {
+        "@colineapp/sdk/v2": join(sdkRoot, "src", "v2.ts"),
+        "@colineapp/app-runtime": join(runtimeRoot, "src", "index.ts"),
+        "@colineapp/ui": join(uiRoot, "src", "index.ts"),
+        "@colineapp/ui/styles.css": join(uiRoot, "src", "styles", "base.css"),
+        react: uiRequire.resolve("react"),
+        "react-dom": uiRequire.resolve("react-dom"),
+        "react-dom/client": uiRequire.resolve("react-dom/client"),
+        "react/jsx-runtime": uiRequire.resolve("react/jsx-runtime"),
+        "zod/v4": sdkRequire.resolve("zod/v4"),
+      },
+      loader: { ".css": "empty" },
+    });
+    expect(result.outputFiles?.[0]?.text).toBeTruthy();
+  });
 });

package/templates/backendless/.agents/skills/coline-app-development/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: coline-app-development
+description: Build and debug a Coline App using the public SDK, hosted capabilities, tree UI, and sandboxed React UI.
+---
+
+# Coline App development
+
+Use this skill for any task that changes a generated Coline App.
+
+## Start from the shipped contract
+
+Read the repository `AGENTS.md`, `app.config.ts`, `main.tsx`, `app.test.ts`,
+and `package.json`. The generated project is intentionally self-contained.
+Do not inspect `/Users/radin/coline-app`, private worktrees, first-party apps,
+or product internals to learn an app-authoring API. Use the installed package
+types, README files, and this skill.
+
+The project has two halves:
+
+- `app.config.ts` is the hosted logic bundle: manifest, permissions, tools,
+  file types, tree handlers, and capability calls.
+- `main.tsx` is the React client entry. The starter includes `@colineapp/ui`,
+  React, ReactDOM, and the CSS export; do not add a second bridge or fetch
+  data from a Coline API route.
+
+## Choose the right surface
+
+- Use `ui.*` tree nodes for previews, inline surfaces, mobile fallbacks, and
+  simple Kairo cards.
+- Use a React surface when the app needs local interaction, filtering, forms,
+  or an editor. Declare `{ tier: "react", entry: "main.tsx" }` and keep the
+  root wrapped in `<ColineAppProvider>`.
+- Use `useColine()` for capability calls and `useColineQuery()` for a bounded
+  loading/error/refetch loop. Never use `fetch`, localStorage, cookies, or
+  credentials in the sandbox.
+
+## Public SDK rules
+
+- Import logic from `@colineapp/sdk/v2` and tests from `@colineapp/sdk/testing`.
+- Prefix every tool name with the app key.
+- Validate inputs with `zod/v4` and declare honest effects (`read`, `write`,
+  `destructive`, or `external`).
+- Ask for the minimum permissions. Capability calls still require both the
+  declared permission and the tool effect ceiling.
+- Collections are typed record envelopes. `where` is exact-match on top-level
+  fields; query bounded pages and filter more complex predicates in memory.
+- Use `ui.*` for hosted handlers. Chat tool cards must stay within the
+  validated chat subset and remain small.
+
+## UI rules
+
+- Import components from `@colineapp/ui` and `@colineapp/ui/styles.css`.
+- Use the host theme tokens (`bg-background`, `text-foreground`,
+  `text-muted-foreground`, and related tokens); dark mode is supplied by the
+  host.
+- Render explicit loading, empty, and error states.
+- Keep components accessible and use the provided controls before writing
+  custom primitives.
+- Do not add a state library or network client for the first implementation.
+
+## Verify before pushing
+
+```sh
+npm run typecheck
+npm test
+```
+
+Then push with `npx coline-app dev --internal` or `npx coline-app push --internal`
+when the user has supplied `COLINE_BASE_URL` and `COLINE_API_KEY`. The local
+test workspace is the first proof; the hosted app is the second.

package/templates/backendless/AGENTS.md

@@ -0,0 +1,169 @@
+# AGENTS.md — building __APP_NAME__ (a Coline App)
+
+This is a self-contained Coline App project. Read this file before changing
+code. The public SDK, UI package, tests, and this guide are the contract; do
+not inspect the Coline product repository or private worktrees to discover how
+to build an app.
+
+## Project model
+
+Coline hosts the app logic. There is no server, database, auth flow, or deploy
+step in this project:
+
+- `app.config.ts` is the hosted logic bundle: manifest, permissions, tools,
+  file types, tree handlers, and capability calls.
+- `main.tsx` is the React client entry for the starter home surface. It runs in
+  a locked sandbox iframe and uses `@colineapp/ui`.
+- `app.test.ts` runs the logic against `createTestWorkspace`, an in-memory
+  capability fake. It does not need a Coline server.
+- `.agents/skills/coline-app-development/SKILL.md` is the detailed task
+  workflow for agents that support skills.
+
+## Commands
+
+```sh
+npm install
+npm run typecheck
+npm test
+
+# after local checks pass and the user has supplied these variables:
+npx coline-app dev --internal
+npx coline-app push --internal
+```
+
+`COLINE_BASE_URL` selects the Coline instance and `COLINE_API_KEY` must be a
+workspace API key with `apps.write`. The CLI uploads `app.config.ts` as a
+logic bundle and submits `main.tsx` plus app `.ts`, `.tsx`, and `.css` source
+when the manifest declares a React surface. It never uploads `node_modules`.
+
+## Public package contract
+
+Use only these app-facing entry points:
+
+```ts
+import { z } from "zod/v4";
+import { defineApp, defineFileType, defineTool, ui } from "@colineapp/sdk/v2";
+import { createTestWorkspace } from "@colineapp/sdk/testing";
+```
+
+For React:
+
+```tsx
+import { createRoot } from "react-dom/client";
+import { ColineAppProvider, useColine, useColineQuery } from "@colineapp/ui";
+import "@colineapp/ui/styles.css";
+```
+
+The scaffold installs the SDK, UI, React, ReactDOM, and their type packages.
+Do not replace them with private workspace paths or a second bridge.
+
+## Manifest and permissions
+
+Keep permissions minimal. Common permissions include:
+
+| Permission | Use |
+| --- | --- |
+| `storage.app` | App-private key/value and typed record collections |
+| `files.read` / `files.write` | Read or create workspace files |
+| `ai.tools` | Expose app tools to Kairo |
+| `members.read` | Read workspace member summaries |
+| `search.index` / `search.query` | Index or query workspace search |
+| `network.external` | Use `coline.net.fetch` for allowlisted hosts |
+
+Tool effects are enforced ceilings, not labels:
+
+- `read` for reads only
+- `write` for ordinary mutations
+- `destructive` for irreversible or deletion-like actions
+- `external` for outbound side effects
+
+Every tool input is a Zod schema and every tool name is prefixed with the app
+key (`__APP_KEY__.operation`).
+
+## Capability patterns
+
+```ts
+interface Decision {
+  title: string;
+  status: "proposed" | "decided";
+}
+
+const decisions = context.coline.storage.collection<Decision>("decisions");
+const created = await decisions.insert({ title: "Use Postgres", status: "decided" });
+const page = await decisions.query({
+  where: { status: "decided" },
+  orderBy: "title",
+  order: "asc",
+  limit: 50,
+});
+```
+
+Collection `where` is exact-match on top-level fields. Records are envelopes
+with the user data under `.data`. Keep pages bounded and filter contains,
+search, or range conditions in app code.
+
+File capabilities include `list`, `get`, `create`, `update`, `trash`,
+`getDocument`, and `updateDocument`. Navigation includes `openFile`,
+`openAppHome`, `navigate`, and `openReference`.
+
+## UI tiers
+
+Tree UI is native and works in previews, inline surfaces, mobile, and Kairo
+cards:
+
+```ts
+return ui.stack([
+  ui.heading("Decisions", { level: 1 }),
+  ui.text("No decisions yet.", { tone: "muted" }),
+]);
+```
+
+The starter home is React with a tree fallback for mobile:
+
+```ts
+surfaces: {
+  home: {
+    tier: "react",
+    entry: "main.tsx",
+    mobile: { tier: "tree" },
+  },
+}
+```
+
+In `main.tsx`, put the app under `ColineAppProvider`. Call capabilities only
+through `useColine()`, and use `useColineQuery(loader, deps)` for bounded
+loading/error/refetch state. The host supplies theme tokens and dark mode.
+Use classes such as `bg-background`, `text-foreground`,
+`text-muted-foreground`, and the exported UI components.
+
+Sandbox restrictions are real: no `fetch`, localStorage, cookies, credentials,
+or direct Coline API routes. External access goes through `coline.net.fetch`
+and a manifest allowlist.
+
+## Testing workflow
+
+```ts
+const workspace = createTestWorkspace(app);
+const result = await workspace.invokeTool("__APP_KEY__.create_note", {
+  title: "Hello",
+});
+expect(result.card).not.toBeNull();
+expect(workspace.files.byType("__APP_KEY__.note")).toHaveLength(1);
+const tree = await workspace.renderHome();
+```
+
+Test tools and tree handlers without a server. React client behavior is
+covered by the typecheck and the hosted dev loop after the logic tests pass.
+Keep explicit loading, empty, and error states in every async React view.
+
+## Agent boundaries
+
+- Do not read `/Users/radin/coline-app`, any `*.worktrees` directory, or
+  first-party app code to understand this public API.
+- Do not add dependencies until checking whether the installed SDK/UI already
+  provides the capability or component.
+- Do not invent signatures from a README snippet: use the installed package
+  declarations when a detail is unclear, then update this guide if the public
+  contract is missing.
+- Keep changes inside this generated app. Ask the user before changing the
+  platform or publishing packages.

package/templates/backendless/CLAUDE.md

@@ -0,0 +1,6 @@
+# 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. For app-authoring tasks, also read
+[`.agents/skills/coline-app-development/SKILL.md`](.agents/skills/coline-app-development/SKILL.md).

package/templates/backendless/README.md

@@ -1,13 +1,15 @@
 # __APP_NAME__
 
-A backendless Coline App. The logic in `app.config.ts` runs on Coline's
-hosted runtime — no servers to deploy.
+A hosted, backendless Coline App. The logic in `app.config.ts` runs on
+Coline's hosted runtime — no servers to deploy. The starter also includes a
+working React home in `main.tsx` using `@colineapp/ui`.
 
 ## Develop
 
 ```sh
 npm install
 npm test          # runs against the in-memory test workspace
+npm run typecheck  # checks app.config.ts and main.tsx
 ```
 
 ## Push to Coline
@@ -30,8 +32,8 @@ Versions land in your developer console in draft state. Use
   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`.
+- The starter home is already a React surface. Keep `main.tsx` as the single
+  client entry and use `@colineapp/ui` for components, provider, and hooks.
 - Store app-private data with `coline.storage.kv` and
   `coline.storage.collection(name)`.
 - Call external APIs with `coline.net.fetch` after declaring

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.
 
@@ -60,12 +60,16 @@ export default defineApp({
   permissions: ["files.read", "files.write", "storage.app", "ai.tools"],
   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",

package/templates/backendless/main.tsx

@@ -0,0 +1,100 @@
+import { createRoot } from "react-dom/client";
+import {
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  ColineAppProvider,
+  Skeleton,
+  useColine,
+  useColineQuery,
+} from "@colineapp/ui";
+import type { ColineFileSummaryV2 } from "@colineapp/sdk/v2";
+import "@colineapp/ui/styles.css";
+
+function StarterHome() {
+  const coline = useColine();
+  const files = useColineQuery(
+    (capabilities) =>
+      capabilities.files.list({ typeKey: "__APP_KEY__.note", limit: 50 }),
+    [],
+  );
+  const notes = files.data?.files ?? [];
+
+  async function createNote(): Promise<void> {
+    const file = await coline.files.create({
+      typeKey: "__APP_KEY__.note",
+      name: "Untitled note",
+      document: { title: "Untitled note", body: "" },
+    });
+    await coline.navigation.openFile(file.fileId);
+  }
+
+  return (
+    <main className="mx-auto flex min-h-screen w-full max-w-3xl flex-col gap-6 bg-background p-6 text-foreground">
+      <header className="flex items-center justify-between gap-4">
+        <div>
+          <h1 className="text-xl font-semibold">__APP_NAME__ is running</h1>
+          <p className="mt-1 text-sm text-muted-foreground">
+            Edit app.config.ts or main.tsx and save to hot-swap this app.
+          </p>
+        </div>
+        <Button onClick={() => void createNote()}>New note</Button>
+      </header>
+
+      {files.isLoading ? (
+        <div className="flex flex-col gap-2">
+          <Skeleton className="h-16 w-full" />
+          <Skeleton className="h-16 w-full" />
+        </div>
+      ) : files.error ? (
+        <Card>
+          <CardHeader>
+            <CardTitle>Couldn&apos;t load notes</CardTitle>
+            <CardDescription>{files.error}</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Button variant="outline" onClick={files.refetch}>
+              Retry
+            </Button>
+          </CardContent>
+        </Card>
+      ) : notes.length === 0 ? (
+        <Card>
+          <CardHeader>
+            <CardTitle>Edit me</CardTitle>
+            <CardDescription>
+              This is a real React surface. Replace this starter with your app,
+              then ask Kairo to create a note called Hello.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+      ) : (
+        <div className="flex flex-col gap-2">
+          {notes.map((file: ColineFileSummaryV2) => (
+            <button
+              key={file.fileId}
+              type="button"
+              onClick={() => void coline.navigation.openFile(file.fileId)}
+              className="rounded-xl border border-border bg-card px-4 py-3 text-left hover:bg-muted/50"
+            >
+              <p className="text-sm font-medium">{file.name}</p>
+              <p className="mt-1 text-xs text-muted-foreground">Open note</p>
+            </button>
+          ))}
+        </div>
+      )}
+    </main>
+  );
+}
+
+const root = document.getElementById("root");
+if (root) {
+  createRoot(root).render(
+    <ColineAppProvider>
+      <StarterHome />
+    </ColineAppProvider>,
+  );
+}

package/templates/backendless/package.json

@@ -10,12 +10,17 @@
     "dev": "coline-app dev"
   },
   "dependencies": {
-    "@colineapp/sdk": "^0.3.0",
-    "zod": "^4.0.0"
+    "@colineapp/sdk": "^0.3.1",
+    "@colineapp/ui": "^0.3.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "create-coline-app": "^2.0.0",
-    "typescript": "^5.7.2",
-    "vitest": "^3.0.5"
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "create-coline-app": "^2.3.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4"
   }
 }