create-coline-app 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coline
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# create-coline-app
+
+Scaffold, push, and iterate on Coline Apps.
+
+```sh
+npx create-coline-app my-app
+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`.
+- **`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
+  uploads to `POST /api/v1/apps/{key}/versions` with a workspace API key
+  (`apps.write` scope). `dev` watches and re-pushes stamped versions.
+
+The CLI never builds tier-2 client bundles itself — it ships source and
+Coline's reviewed build pipeline produces the bundle.

package/bin/_run.mjs

@@ -0,0 +1,52 @@
+// Bin shim: bundles the strict-TS CLI source with esbuild on first run,
+// caches it inside the package, and dispatches to the named entrypoint.
+import { build } from "esbuild";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+async function ensureCliBundle() {
+  const entry = join(packageRoot, "src", "cli.ts");
+  const source = await readFile(entry, "utf8");
+  const stamp = createHash("sha256").update(source).digest("hex").slice(0, 16);
+  const outFile = join(packageRoot, ".cache", `cli.${stamp}.mjs`);
+  const exists = await stat(outFile).then(
+    () => true,
+    () => false,
+  );
+  if (!exists) {
+    const result = await build({
+      entryPoints: [entry],
+      bundle: true,
+      write: false,
+      format: "esm",
+      platform: "node",
+      target: "node20",
+      packages: "external",
+      logLevel: "silent",
+    });
+    await mkdir(dirname(outFile), { recursive: true });
+    await writeFile(outFile, result.outputFiles[0].text, "utf8");
+  }
+  return pathToFileURL(outFile).href;
+}
+
+export async function runFromBin(entrypoint) {
+  const moduleUrl = await ensureCliBundle();
+  const cli = await import(moduleUrl);
+  const run = cli[entrypoint];
+  if (typeof run !== "function") {
+    console.error(`CLI entrypoint "${entrypoint}" not found.`);
+    process.exit(1);
+  }
+  try {
+    const code = await run(process.argv.slice(2));
+    process.exit(typeof code === "number" ? code : 0);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/bin/coline-app.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runFromBin } from "./_run.mjs";
+
+await runFromBin("runColineApp");

package/bin/create-coline-app.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runFromBin } from "./_run.mjs";
+
+await runFromBin("runCreate");

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "create-coline-app",
+  "version": "2.0.0",
+  "description": "Scaffold, push, and iterate on Coline Apps.",
+  "type": "module",
+  "bin": {
+    "create-coline-app": "./bin/create-coline-app.mjs",
+    "coline-app": "./bin/coline-app.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ColineApp/coline-app.git",
+    "directory": "packages/create-coline-app"
+  },
+  "homepage": "https://coline.app/developers/docs",
+  "keywords": [
+    "coline",
+    "apps",
+    "cli",
+    "scaffold",
+    "create"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/args.ts

@@ -0,0 +1,12 @@
+export function argValue(argv: readonly string[], flag: string): string | null {
+  const index = argv.indexOf(flag);
+  if (index < 0) {
+    return null;
+  }
+  const value = argv[index + 1];
+  return value !== undefined && !value.startsWith("--") ? value : null;
+}
+
+export function hasFlag(argv: readonly string[], flag: string): boolean {
+  return argv.includes(flag);
+}

package/src/cli.test.ts

@@ -0,0 +1,100 @@
+import { build } from "esbuild";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import { argValue, hasFlag } from "./args";
+import { runCreate } from "./scaffold";
+
+const cleanups: string[] = [];
+
+afterEach(async () => {
+  for (const dir of cleanups.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+async function scaffoldTemp(name: string): Promise<string> {
+  const parent = await mkdtemp(join(tmpdir(), "cca-test-"));
+  cleanups.push(parent);
+  const previousCwd = process.cwd();
+  process.chdir(parent);
+  try {
+    const code = await runCreate([name]);
+    expect(code).toBe(0);
+  } finally {
+    process.chdir(previousCwd);
+  }
+  return join(parent, name);
+}
+
+describe("args", () => {
+  it("reads flag values and ignores flag-shaped values", () => {
+    expect(argValue(["--dir", "apps/x"], "--dir")).toBe("apps/x");
+    expect(argValue(["--dir", "--other"], "--dir")).toBeNull();
+    expect(argValue([], "--dir")).toBeNull();
+    expect(hasFlag(["--watch"], "--watch")).toBe(true);
+  });
+});
+
+describe("runCreate", () => {
+  it("scaffolds with placeholders replaced and gitignore restored", async () => {
+    const dir = await scaffoldTemp("team-crm");
+    const config = await readFile(join(dir, "app.config.ts"), "utf8");
+    expect(config).toContain('key: "team-crm"');
+    expect(config).toContain('"team-crm.note"');
+    expect(config).not.toContain("__APP_KEY__");
+    const packageJson = JSON.parse(await readFile(join(dir, "package.json"), "utf8")) as {
+      name: string;
+    };
+    expect(packageJson.name).toBe("team-crm");
+    await expect(readFile(join(dir, ".gitignore"), "utf8")).resolves.toContain("node_modules");
+  });
+
+  it("refuses to scaffold over a non-empty directory", async () => {
+    const dir = await scaffoldTemp("first");
+    const previousCwd = process.cwd();
+    process.chdir(resolve(dir, ".."));
+    try {
+      await expect(runCreate(["first"])).resolves.toBe(1);
+    } finally {
+      process.chdir(previousCwd);
+    }
+  });
+
+  it("produces an app config that builds against the real SDK", async () => {
+    const dir = await scaffoldTemp("smoke-app");
+    const sdkRoot = resolve(__dirname, "..", "..", "sdk");
+    const sdkRequire = createRequire(join(sdkRoot, "package.json"));
+    const result = await build({
+      entryPoints: [join(dir, "app.config.ts")],
+      bundle: true,
+      write: false,
+      format: "esm",
+      platform: "neutral",
+      target: "es2022",
+      logLevel: "silent",
+      absWorkingDir: resolve(__dirname, ".."),
+      alias: {
+        "@colineapp/sdk/v2": join(sdkRoot, "src", "v2.ts"),
+        "zod/v4": sdkRequire.resolve("zod/v4"),
+      },
+      mainFields: ["module", "main"],
+      conditions: ["import", "default"],
+    });
+    const bundleText = result.outputFiles?.[0]?.text;
+    expect(bundleText).toBeTruthy();
+
+    const out = await mkdtemp(join(tmpdir(), "cca-bundle-"));
+    cleanups.push(out);
+    const bundlePath = join(out, "app.mjs");
+    await writeFile(bundlePath, bundleText ?? "", "utf8");
+    const imported = (await import(pathToFileURL(bundlePath).href)) as {
+      default: { manifest: { key: string; tools: Array<{ name: string }> } };
+    };
+    expect(imported.default.manifest.key).toBe("smoke-app");
+    expect(imported.default.manifest.tools[0]?.name).toBe("smoke-app.create_note");
+  });
+});

package/src/cli.ts

@@ -0,0 +1,41 @@
+import { runCreate as create } from "./scaffold";
+import { runDev } from "./dev";
+import { runPush } from "./push";
+
+const COLINE_APP_HELP = `coline-app — push and iterate on Coline Apps.
+
+Usage:
+  coline-app push [options]     Build and upload a new app version
+  coline-app dev [options]      Watch the project and re-push on change
+
+Options:
+  --dir <path>        App project directory (default: current directory)
+  --base-url <url>    Coline instance URL (default: $COLINE_BASE_URL or https://coline.app)
+  --api-key <key>     Workspace API key with the apps.write scope (default: $COLINE_API_KEY)
+  --version <semver>  Version to publish (default: package.json version, then a dev stamp)
+
+The API key is created in Workspace Settings → API. Pushed versions land
+in your developer console in draft review state; pin them from there
+while iterating.`;
+
+export async function runCreate(argv: string[]): Promise<number> {
+  return create(argv);
+}
+
+export async function runColineApp(argv: string[]): Promise<number> {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case "push":
+      return runPush(rest);
+    case "dev":
+      return runDev(rest);
+    case "help":
+    case "--help":
+    case undefined:
+      console.log(COLINE_APP_HELP);
+      return command === undefined ? 1 : 0;
+    default:
+      console.error(`Unknown command "${command}".\n\n${COLINE_APP_HELP}`);
+      return 1;
+  }
+}

package/src/dev.ts

@@ -0,0 +1,63 @@
+import { watch } from "node:fs";
+import { join } from "node:path";
+import { pushAppVersion, resolvePushConfig } from "./push";
+
+const DEBOUNCE_MS = 400;
+
+export async function runDev(argv: string[]): Promise<number> {
+  const config = resolvePushConfig(argv);
+  console.log(`Watching ${config.dir} — every change pushes a new dev version.`);
+
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let pushing = false;
+  let dirty = false;
+
+  async function pushOnce(): Promise<void> {
+    if (pushing) {
+      dirty = true;
+      return;
+    }
+    pushing = true;
+    try {
+      const result = await pushAppVersion({
+        ...config,
+        version: `0.0.${Math.floor(Date.now() / 1000)}`,
+      });
+      console.log(`[${new Date().toLocaleTimeString()}] pushed ${result.appKey}@${result.version}`);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+    } finally {
+      pushing = false;
+      if (dirty) {
+        dirty = false;
+        void pushOnce();
+      }
+    }
+  }
+
+  const watcher = watch(config.dir, { recursive: true }, (_event, fileName) => {
+    if (!fileName) {
+      return;
+    }
+    if (
+      fileName.includes("node_modules") ||
+      fileName.includes(".git") ||
+      fileName.includes(join(".cache", ""))
+    ) {
+      return;
+    }
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => void pushOnce(), DEBOUNCE_MS);
+  });
+
+  await pushOnce();
+
+  return new Promise<number>((resolvePromise) => {
+    process.on("SIGINT", () => {
+      watcher.close();
+      resolvePromise(0);
+    });
+  });
+}

package/src/push.ts

@@ -0,0 +1,215 @@
+import { build } from "esbuild";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tmpdir } from "node:os";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { argValue } from "./args";
+
+interface ManifestSummary {
+  key: string;
+  name: string;
+  surfaces: Record<string, { tier?: string } | undefined>;
+  files: Array<{ surfaces?: Record<string, { tier?: string } | undefined> }>;
+}
+
+export interface PushConfig {
+  dir: string;
+  baseUrl: string;
+  apiKey: string;
+  version: string | null;
+}
+
+export interface PushResult {
+  appKey: string;
+  version: string;
+  appId: string;
+  versionId: string;
+}
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".css"]);
+const IGNORED_DIRECTORIES = new Set(["node_modules", "dist", ".git", ".cache", ".coline"]);
+
+export function resolvePushConfig(argv: readonly string[]): PushConfig {
+  const apiKey = argValue(argv, "--api-key") ?? process.env.COLINE_API_KEY ?? null;
+  if (!apiKey) {
+    throw new Error(
+      "An API key is required. Pass --api-key or set COLINE_API_KEY. " +
+        "Create one with the apps.write scope in Workspace Settings → API.",
+    );
+  }
+  return {
+    dir: resolve(process.cwd(), argValue(argv, "--dir") ?? "."),
+    baseUrl: (
+      argValue(argv, "--base-url") ??
+      process.env.COLINE_BASE_URL ??
+      "https://coline.app"
+    ).replace(/\/+$/, ""),
+    apiKey,
+    version: argValue(argv, "--version"),
+  };
+}
+
+async function buildLogicBundle(appDir: string): Promise<string> {
+  const result = await build({
+    entryPoints: [join(appDir, "app.config.ts")],
+    bundle: true,
+    write: false,
+    format: "esm",
+    platform: "browser",
+    target: "es2022",
+    minify: true,
+    absWorkingDir: appDir,
+    define: { "process.env.NODE_ENV": '"production"' },
+    logLevel: "silent",
+  });
+  const output = result.outputFiles?.[0]?.text;
+  if (!output) {
+    throw new Error("Logic bundle build produced no output.");
+  }
+  return output;
+}
+
+/**
+ * Extract the serializable manifest by importing the app's own bundle
+ * (plan §6.2 two-artifact model). The app's SDK version travels inside
+ * the bundle, so the CLI never needs to agree with it.
+ */
+async function extractManifest(logicBundleJs: string): Promise<ManifestSummary> {
+  const dir = await mkdtemp(join(tmpdir(), "coline-app-"));
+  const bundlePath = join(dir, "app.config.mjs");
+  try {
+    await writeFile(bundlePath, logicBundleJs, "utf8");
+    const imported = (await import(pathToFileURL(bundlePath).href)) as {
+      default?: { manifest?: unknown };
+    };
+    const manifest = imported.default?.manifest;
+    if (!manifest || typeof manifest !== "object") {
+      throw new Error(
+        "app.config.ts must default-export defineApp(...); no manifest was found.",
+      );
+    }
+    return JSON.parse(JSON.stringify(manifest)) as ManifestSummary;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+function manifestHasReactSurfaces(manifest: ManifestSummary): boolean {
+  const tiers = [
+    ...Object.values(manifest.surfaces ?? {}).map((surface) => surface?.tier),
+    ...(manifest.files ?? []).flatMap((file) =>
+      Object.values(file.surfaces ?? {}).map((surface) => surface?.tier),
+    ),
+  ];
+  return tiers.includes("react");
+}
+
+async function collectClientSource(
+  appDir: string,
+): Promise<{ entry: string; files: Record<string, string> } | null> {
+  const entry = "main.tsx";
+  const entryExists = await stat(join(appDir, entry)).then(
+    (item) => item.isFile(),
+    () => false,
+  );
+  if (!entryExists) {
+    return null;
+  }
+
+  const files: Record<string, string> = {};
+  async function walk(dir: string): Promise<void> {
+    for (const item of await readdir(dir, { withFileTypes: true })) {
+      if (item.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(item.name)) {
+          await walk(join(dir, item.name));
+        }
+        continue;
+      }
+      const extension = item.name.slice(item.name.lastIndexOf("."));
+      if (!SOURCE_EXTENSIONS.has(extension) || item.name.endsWith(".test.ts")) {
+        continue;
+      }
+      const filePath = join(dir, item.name);
+      files[relative(appDir, filePath)] = await readFile(filePath, "utf8");
+    }
+  }
+  await walk(appDir);
+  return { entry, files };
+}
+
+async function resolveVersion(appDir: string, explicit: string | null): Promise<string> {
+  if (explicit) {
+    return explicit;
+  }
+  const packageJson = await readFile(join(appDir, "package.json"), "utf8").catch(() => null);
+  if (packageJson) {
+    const parsed = JSON.parse(packageJson) as { version?: string };
+    if (parsed.version && parsed.version !== "0.0.0") {
+      return parsed.version;
+    }
+  }
+  return `0.0.${Math.floor(Date.now() / 1000)}`;
+}
+
+export async function pushAppVersion(config: PushConfig): Promise<PushResult> {
+  const logicBundleJs = await buildLogicBundle(config.dir);
+  const manifest = await extractManifest(logicBundleJs);
+  const version = await resolveVersion(config.dir, config.version);
+  const clientSource = manifestHasReactSurfaces(manifest)
+    ? await collectClientSource(config.dir)
+    : null;
+
+  if (manifestHasReactSurfaces(manifest) && !clientSource) {
+    throw new Error(
+      "The manifest declares react surfaces but no main.tsx client entry was found.",
+    );
+  }
+
+  const response = await fetch(
+    `${config.baseUrl}/api/v1/apps/${encodeURIComponent(manifest.key)}/versions`,
+    {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${config.apiKey}`,
+      },
+      body: JSON.stringify({
+        protocolVersion: 2,
+        version,
+        manifest,
+        logicBundleJs,
+        clientSource,
+      }),
+    },
+  );
+
+  const payload = (await response.json().catch(() => null)) as {
+    data?: { appId: string; versionId: string };
+    error?: { code: string; message: string };
+  } | null;
+
+  if (!response.ok || !payload?.data) {
+    const detail = payload?.error
+      ? `${payload.error.code}: ${payload.error.message}`
+      : `HTTP ${response.status}`;
+    throw new Error(`Push failed — ${detail}`);
+  }
+
+  return {
+    appKey: manifest.key,
+    version,
+    appId: payload.data.appId,
+    versionId: payload.data.versionId,
+  };
+}
+
+export async function runPush(argv: string[]): Promise<number> {
+  const config = resolvePushConfig(argv);
+  const result = await pushAppVersion(config);
+  console.log(
+    `Pushed ${result.appKey}@${result.version} (version ${result.versionId}).\n` +
+      "The version is in draft review state — pin or submit it from the developer console.",
+  );
+  return 0;
+}

package/src/scaffold.ts

@@ -0,0 +1,88 @@
+import { cp, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATE_ROOT = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "templates");
+
+function toAppKey(input: string): string {
+  const key = input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!/^[a-z][a-z0-9-]{1,63}$/.test(key)) {
+    throw new Error(`Cannot derive a valid app key from "${input}".`);
+  }
+  return key;
+}
+
+function toAppName(key: string): string {
+  return key
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+async function walkFiles(dir: string, prefix = ""): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...(await walkFiles(join(dir, entry.name), relative)));
+    } else {
+      files.push(relative);
+    }
+  }
+  return files;
+}
+
+export async function runCreate(argv: string[]): Promise<number> {
+  const target = argv.find((arg) => !arg.startsWith("--"));
+  if (!target) {
+    console.log("Usage: create-coline-app <directory>");
+    return 1;
+  }
+
+  const targetDir = resolve(process.cwd(), target);
+  const appKey = toAppKey(target.split("/").pop() ?? target);
+  const appName = toAppName(appKey);
+  const templateDir = join(TEMPLATE_ROOT, "backendless");
+
+  const existing = await readdir(targetDir).catch(() => null);
+  if (existing && existing.length > 0) {
+    console.error(`Directory "${target}" already exists and is not empty.`);
+    return 1;
+  }
+
+  await mkdir(targetDir, { recursive: true });
+  await cp(templateDir, targetDir, { recursive: true });
+
+  // npm strips .gitignore from published packages; templates ship gitignore.
+  const shippedGitignore = join(targetDir, "gitignore");
+  await rename(shippedGitignore, join(targetDir, ".gitignore")).catch(() => undefined);
+
+  for (const relative of await walkFiles(targetDir)) {
+    const filePath = join(targetDir, relative);
+    const content = await readFile(filePath, "utf8");
+    if (content.includes("__APP_KEY__") || content.includes("__APP_NAME__")) {
+      await writeFile(
+        filePath,
+        content.replaceAll("__APP_KEY__", appKey).replaceAll("__APP_NAME__", appName),
+        "utf8",
+      );
+    }
+  }
+
+  console.log(`Created ${appName} (${appKey}) in ${target}.
+
+Next steps:
+  cd ${target}
+  npm install
+  npm test
+
+Then create a workspace API key with the apps.write scope in
+Workspace Settings → API, and push your first version:
+  export COLINE_API_KEY=col_ws_...
+  npx coline-app push`);
+  return 0;
+}

package/templates/backendless/README.md

@@ -0,0 +1,38 @@
+# __APP_NAME__
+
+A backendless Coline App. The logic in `app.config.ts` runs on Coline's
+hosted runtime — no servers to deploy.
+
+## Develop
+
+```sh
+npm install
+npm test          # runs against the in-memory test workspace
+```
+
+## Push to Coline
+
+Create a workspace API key with the `apps.write` scope in
+**Workspace Settings → API**, then:
+
+```sh
+export COLINE_API_KEY=col_ws_...
+npm run push
+```
+
+Versions land in your developer console in draft state. Use
+`npm run dev` to watch the project and push on every change.
+
+## Grow the app
+
+- 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.

package/templates/backendless/app.config.ts

@@ -0,0 +1,91 @@
+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
+// Coline's hosted runtime: no servers, no deploys. `coline-app push`
+// uploads this file as the logic bundle and main.tsx as client source.
+
+const noteFileType = defineFileType({
+  metadata: {
+    typeKey: "__APP_KEY__.note",
+    name: "__APP_NAME__ Note",
+    indexable: true,
+    surfaces: {
+      preview: { tier: "tree" },
+      inline: { tier: "tree" },
+    },
+  },
+  runtime: {
+    renderPreview: (context) =>
+      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"),
+      body: (document) => String(document.body ?? ""),
+    },
+  },
+});
+
+const createNote = defineTool({
+  name: "__APP_KEY__.create_note",
+  description: "Create a note with a title and body.",
+  input: z.object({
+    title: z.string().min(1),
+    body: z.string().default(""),
+  }),
+  effect: "write",
+  execute: async (input, context) => {
+    const file = await context.coline.files.create({
+      typeKey: "__APP_KEY__.note",
+      name: input.title,
+      document: { body: input.body },
+    });
+    return {
+      output: { fileId: file.fileId },
+      card: ui.stack([
+        ui.text(`Created “${input.title}”.`),
+        ui.reference({ kind: "file", id: file.fileId }),
+      ]),
+    };
+  },
+});
+
+export default defineApp({
+  key: "__APP_KEY__",
+  name: "__APP_NAME__",
+  description: "A starter Coline App.",
+  permissions: ["files.read", "files.write", "storage.app", "ai.tools"],
+  hosting: { default: "coline" },
+  surfaces: {
+    home: { tier: "tree" },
+  },
+  files: [noteFileType],
+  tools: [createNote],
+  handlers: {
+    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),
+                }),
+              ),
+            ),
+      ]);
+    },
+  },
+});

package/templates/backendless/app.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { createTestWorkspace } from "@colineapp/sdk/testing";
+import app from "./app.config";
+
+describe("__APP_NAME__", () => {
+  it("creates a note through the Kairo tool", async () => {
+    const workspace = createTestWorkspace(app);
+    const result = await workspace.invokeTool("__APP_KEY__.create_note", {
+      title: "Hello",
+      body: "First note.",
+    });
+    expect(result.card).not.toBeNull();
+    expect(workspace.files.byType("__APP_KEY__.note")).toHaveLength(1);
+  });
+
+  it("renders the home surface", async () => {
+    const workspace = createTestWorkspace(app);
+    await workspace.invokeTool("__APP_KEY__.create_note", { title: "Hello" });
+    const tree = await workspace.renderHome();
+    expect(JSON.stringify(tree)).toContain("Hello");
+  });
+});

package/templates/backendless/gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.cache
+.coline

package/templates/backendless/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "__APP_KEY__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "push": "coline-app push",
+    "dev": "coline-app dev"
+  },
+  "dependencies": {
+    "@colineapp/sdk": "^0.2.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "create-coline-app": "^2.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  }
+}

package/templates/backendless/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}