create-coline-app 2.2.0 → 2.5.0

package/AGENTS.md

@@ -0,0 +1,86 @@
+# 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` — guest/host bridge; direct scaffold dev dependency for local preview
+- `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`, `assets`, `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.
+
+## SDK 0.4 / CLI 2.4 workflow
+
+Run `coline-app check` before pushing: it checks types, the manifest, hosted logic,
+and the React bundle without uploading. `dev --internal` updates one development
+version; install it in the workspace and reload after changes. The CLI bundles
+from the app's installed dependencies and preserves imported CSS and inline assets.
+CLI 2.5 compiles app-specific Tailwind v4 and ordinary CSS automatically.
+Import UI styles, then app.css; use complete class names. Local `preview` uses
+the public test workspace and sandbox bridge, requires no credentials, and can
+capture light/dark/mobile/error states with `--screenshots <directory>`.
+
+The starter includes a React home and editor, tree mobile fallback, and a tool.
+Use `coline.tools.invoke` or `actions.invokeTool` to run the same declared tool
+from UI that Kairo runs. Save with `expectedVersion` to detect concurrent edits.
+Homes/editors can write within grants; previews and server render handlers cannot.
+`createTestWorkspace(app).client()` tests the interactive contract and
+`grantedPermissions` simulates revoked consent.
+
+New `tasks`, `calendar`, `messages`, and `references` capabilities require their
+explicit manifest permissions and retain the invoking user's workspace access.
+Use `files.list({ scope: "workspace" })` for shared files; document writes stay
+with the owning app. Collections are install-private. Code integration and a
+native mobile React runtime are separate work.

package/README.md

@@ -1,6 +1,6 @@
 # create-coline-app
 
-Scaffold, push, and iterate on Coline Apps.
+Scaffold, push, and iterate on apps for the Coline App Store.
 
 ```sh
 npx create-coline-app my-app
@@ -9,14 +9,67 @@ 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
+  bundles installed client dependencies and CSS 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.
+The CLI bundles the client locally. Coline validates, rebuilds, and hashes the
+uploaded artifact before serving it in the sandbox.
+
+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.
+
+## SDK 0.4 / CLI 2.5 workflow
+
+Run `coline-app check` before pushing: it checks types, the manifest, hosted logic,
+and the React bundle without uploading. `dev --internal` updates one development
+version; install it in the workspace and reload after changes. The CLI bundles
+from the app's installed dependencies and preserves imported CSS and inline assets.
+App-specific Tailwind v4 utilities compile automatically with CLI 2.5. Import
+`@colineapp/ui/styles.css` and then `./app.css`; use complete class names.
+
+The starter includes a React home and editor, tree mobile fallback, and a tool.
+Use `coline.tools.invoke` or `actions.invokeTool` to run the same declared tool
+from UI that Kairo runs. Save with `expectedVersion` to detect concurrent edits.
+Homes/editors can write within grants; previews and server render handlers cannot.
+`createTestWorkspace(app).client()` tests the interactive contract and
+`grantedPermissions` simulates revoked consent.
+
+New `tasks`, `calendar`, `messages`, and `references` capabilities require their
+explicit manifest permissions and retain the invoking user's workspace access.
+Use `files.list({ scope: "workspace" })` for shared files; document writes stay
+with the owning app. Collections are install-private. Code integration and a
+native mobile React runtime are separate work.
+
+## Agent UI workflow (experimental)
+
+Generated apps include original Coline-specific development, design, and review
+skills under `.agents/skills`, plus plain `AGENTS.md` and a `CLAUDE.md` pointer.
+The UI examples cover a request queue/detail panel, editorial board, and settings.
+Their state is local: adapt the layout, then connect the real SDK capabilities.
+
+```sh
+npm run preview                           # local notes app with seeded data
+npm run preview -- --pattern triage        # also board / settings
+npx playwright install chromium            # once, for screenshot capture
+npm run screenshots                       # .coline/screenshots/report.json
+```
+
+Preview binds a random loopback port and uses the published SDK test workspace
+and real sandbox bridge. It does not need credentials or upload anything.
+Theme/state controls and live source reload make iteration cheap. `preview.seed.ts`
+can seed capabilities without importing fixtures into the production entry.
+
+The screenshot command captures light/dark × desktop/mobile × five states and
+reports browser errors, page overflow, and unlabelled fields. It exits nonzero
+on those issues. Inspect images and exercise interactions before calling the UI
+finished. This is not a visual-quality score or a hosted authorization, realtime,
+or performance test. Models without image/tool support need human visual review.

package/assets/preview-host.ts

@@ -0,0 +1,130 @@
+// Compiled for the local preview host only. It never enters an uploaded app bundle.
+import { createHostBridge } from "@colineapp/app-runtime";
+import { createTestWorkspace } from "@colineapp/sdk/testing";
+import app from "coline-preview-app";
+import { seed } from "coline-preview-seed";
+
+const params = new URLSearchParams(location.search);
+const mode = params.get("state") ?? "ready";
+const dark = params.get("theme") === "dark";
+const workspace = createTestWorkspace(app);
+if (mode !== "empty") await seed(workspace);
+const coline = workspace.client();
+const frame = document.querySelector<HTMLIFrameElement>("iframe")!;
+let bridge: ReturnType<typeof createHostBridge> | null = null;
+let fileId: string | null = null;
+const notify = (message: string) => {
+  document.querySelector<HTMLOutputElement>("#notice")!.textContent = message;
+};
+async function mount() {
+  bridge?.dispose();
+  const stored = fileId ? workspace.state.files.get(fileId) : null;
+  bridge = createHostBridge({
+    frame,
+    context: {
+      surface: stored ? "editor" : "home",
+      workspace: {
+        workspaceId: "ws_test",
+        workspaceSlug: "test-workspace",
+        workspaceName: "Preview workspace",
+      },
+      app: { appKey: app.manifest.key, installId: "inst_test" },
+      actor: { userId: "user_test" },
+      file: stored
+        ? {
+            fileId: stored.fileId,
+            name: stored.name,
+            typeKey: stored.typeKey,
+            version: stored.version,
+          }
+        : null,
+      document: stored?.document ?? null,
+    },
+    theme: {},
+    colorScheme: dark ? "dark" : "light",
+    manifestPermissions: app.manifest.permissions,
+    grantedPermissions: mode === "denied" ? [] : app.manifest.permissions,
+    effectCeiling: "destructive",
+    delegate: {
+      async callCapability(operation, args) {
+        if (mode === "loading") return new Promise(() => undefined);
+        if (mode === "error")
+          throw Object.assign(
+            new Error("Preview: simulate a failed request. Offer a recovery action."),
+            { code: "preview_error" },
+          );
+        const parts = operation.split(".");
+        let target: unknown = coline;
+        if (operation.startsWith("storage.records.")) {
+          target = coline.storage.collection(String(args[0]));
+          args = args.slice(1);
+          parts.splice(0, 2);
+        }
+        for (const part of parts.slice(0, -1)) target = (target as Record<string, unknown>)[part];
+        const method = (target as Record<string, unknown>)[parts.at(-1)!];
+        if (typeof method !== "function")
+          throw new Error(`Preview does not implement ${operation}.`);
+        return Reflect.apply(method, target, args);
+      },
+      async showPicker(picker, options) {
+        if (picker === "confirm") return confirm(String(options.title ?? "Confirm"));
+        const items =
+          picker === "file"
+            ? [...workspace.state.files.values()].map((file) => ({
+                id: file.fileId,
+                label: file.name,
+              }))
+            : [{ id: "user_test", label: "Preview user" }];
+        const selected = prompt(
+          `${String(options.title ?? `Choose ${picker}`)}\n${items.map((item) => `${item.id}: ${item.label}`).join("\n")}`,
+        );
+        if (!selected) return null;
+        if (!items.some((item) => item.id === selected))
+          throw new Error("Select one of the listed IDs.");
+        return picker === "file" ? { fileId: selected } : { userId: selected };
+      },
+      onNavigate(intent, payload) {
+        if (intent === "openFile") {
+          fileId = String(payload.fileId);
+          void mount();
+        } else if (intent === "openAppHome") {
+          fileId = null;
+          void mount();
+        } else
+          notify(
+            `Navigation requested: ${String(payload.href ?? intent)} (not opened from preview).`,
+          );
+      },
+      onResize() {},
+      onToast: notify,
+      onReady() {
+        frame.dataset.ready = "true";
+      },
+    },
+  });
+  frame.removeAttribute("data-ready");
+  frame.src = `/app?${params}&generation=${Date.now()}`;
+}
+window.addEventListener("message", (event) => bridge?.handleMessage(event));
+workspace.state.realtimeListeners.set(
+  "coline.records.changed",
+  new Set([(message) => bridge?.pushRealtimeEvent(message.event, message.data)]),
+);
+await mount();
+for (const select of document.querySelectorAll<HTMLSelectElement>("select[data-param]")) {
+  select.value = params.get(select.dataset.param!) ?? select.value;
+  select.onchange = () => {
+    params.set(select.dataset.param!, select.value);
+    location.search = params.toString();
+  };
+}
+let revision: string | null = null;
+setInterval(() => {
+  void fetch("/revision")
+    .then((response) => response.text())
+    .then((value) => {
+      if (revision !== null && value !== revision) location.reload();
+      revision = value;
+    })
+    .catch(() => notify("Preview server stopped."));
+}, 700);

package/bin/_run.mjs

@@ -2,7 +2,7 @@
 // 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 { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -10,7 +10,16 @@ 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 sourceFiles = (await readdir(join(packageRoot, "src")))
+    .filter((name) => name.endsWith(".ts"))
+    .sort();
+  const source = (
+    await Promise.all(
+      sourceFiles.map(
+        async (name) => name + (await readFile(join(packageRoot, "src", name), "utf8")),
+      ),
+    )
+  ).join("\n");
   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(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-coline-app",
-  "version": "2.2.0",
-  "description": "Scaffold, push, and iterate on Coline Apps.",
+  "version": "2.5.0",
+  "description": "Scaffold, push, and iterate on apps for the Coline App Store.",
   "type": "module",
   "bin": {
     "create-coline-app": "./bin/create-coline-app.mjs",
@@ -12,10 +12,15 @@
     "src",
     "templates",
     "README.md",
-    "LICENSE"
+    "AGENTS.md",
+    "LICENSE",
+    "assets"
   ],
   "dependencies": {
-    "esbuild": "^0.25.0"
+    "esbuild": "^0.25.0",
+    "@tailwindcss/postcss": "^4.3.0",
+    "postcss": "^8.5.6",
+    "playwright": "^1.58.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/src/check.ts

@@ -0,0 +1,46 @@
+import { resolve, join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { argValue } from "./args";
+import { buildLogicBundle, extractManifest } from "./push";
+import { buildClientSource } from "./client-build";
+
+/** Check the actual upload artifacts without credentials or a workspace mutation. */
+export async function checkApp(
+  dir: string,
+): Promise<{ appKey: string; logicBytes: number; clientBytes: number }> {
+  const packageJson = JSON.parse(await readFile(join(dir, "package.json"), "utf8")) as {
+    devDependencies?: Record<string, string>;
+  };
+  if (packageJson.devDependencies?.typescript) {
+    const code = await new Promise<number | null>((resolveExit, reject) => {
+      const child = spawn(
+        process.execPath,
+        [join(dir, "node_modules/typescript/bin/tsc"), "--noEmit"],
+        { cwd: dir, stdio: "inherit" },
+      );
+      child.on("error", reject);
+      child.on("exit", resolveExit);
+    });
+    if (code !== 0) throw new Error("Typecheck failed. Fix the errors above before pushing.");
+  }
+  const logic = await buildLogicBundle(dir);
+  const manifest = await extractManifest(logic);
+  const hasReact = [
+    ...Object.values(manifest.surfaces ?? {}),
+    ...manifest.files.flatMap((file) => Object.values(file.surfaces ?? {})),
+  ].some((surface) => surface?.tier === "react");
+  const client = hasReact ? await buildClientSource(dir) : null;
+  return {
+    appKey: manifest.key,
+    logicBytes: Buffer.byteLength(logic),
+    clientBytes: client ? Buffer.byteLength(client.files[client.entry] ?? "") : 0,
+  };
+}
+export async function runCheck(argv: string[]): Promise<number> {
+  const result = await checkApp(resolve(argValue(argv, "--dir") ?? "."));
+  console.log(
+    `${result.appKey}: typecheck and bundles passed (${result.logicBytes} bytes logic, ${result.clientBytes} bytes client). No upload.`,
+  );
+  return 0;
+}

package/src/cli.test.ts

@@ -48,8 +48,32 @@ 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.4.0");
+    expect(packageJson.dependencies["@colineapp/ui"]).toBe("^0.4.0");
+    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.5.0");
+    const main = await readFile(join(dir, "main.tsx"), "utf8");
+    expect(main).toContain("ColineAppProvider");
+    expect(main).toContain("AppPage");
+    expect(main).toContain('import "./app.css"');
+    const generatedFiles = [
+      "README.md",
+      "AGENTS.md",
+      ".agents/skills/coline-app-development/SKILL.md",
+    ];
+    for (const file of generatedFiles) {
+      await expect(readFile(join(dir, file), "utf8")).resolves.not.toContain(
+        "/Users/radin/coline-app",
+      );
+    }
+    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 +121,134 @@ 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();
+  });
+});
+
+describe("client artifacts", () => {
+  it("keeps application CSS and installed dependencies in the uploaded artifact", async () => {
+    const { mkdir } = await import("node:fs/promises");
+    const { buildClientSource } = await import("./client-build");
+    const dir = await mkdtemp(join(tmpdir(), "cca-css-"));
+    cleanups.push(dir);
+    await mkdir(join(dir, "node_modules", "my-chart"), { recursive: true });
+    await writeFile(
+      join(dir, "node_modules/my-chart/package.json"),
+      JSON.stringify({ name: "my-chart", main: "index.js" }),
+    );
+    await writeFile(
+      join(dir, "node_modules/my-chart/index.js"),
+      'export const label = "Chart loaded";',
+    );
+    await writeFile(
+      join(dir, "main.tsx"),
+      'import { label } from "my-chart"; import "./app.css"; document.body.textContent = label;',
+    );
+    await writeFile(join(dir, "app.css"), ".custom-panel { color: rgb(12, 34, 56); }");
+    const source = await buildClientSource(dir);
+    expect(source.entry).toBe("client.js");
+    expect(source.files[source.entry]).toContain("Chart loaded");
+    expect(source.files[source.entry]).toContain("custom-panel");
+    expect(source.files[source.entry]).toContain("document.head.append");
+  });
+});
+
+describe("local preview boundary", () => {
+  it("serves only local preview routes and closes its watcher", async () => {
+    const { startPreview } = await import("./preview");
+    const { request } = await import("node:http");
+    const dir = await scaffoldTemp("preview-boundary");
+    const preview = await startPreview(dir);
+    try {
+      const html = await fetch(preview.origin).then((response) => response.text());
+      expect(html).toContain('sandbox="allow-scripts allow-forms"');
+      expect(
+        await fetch(`${preview.origin}/app.config.ts`).then((response) => response.status),
+      ).toBe(404);
+      const status = await new Promise<number | undefined>((done, reject) => {
+        const req = request(
+          preview.origin,
+          { headers: { host: "external.example" } },
+          (response) => {
+            response.resume();
+            done(response.statusCode);
+          },
+        );
+        req.on("error", reject);
+        req.end();
+      });
+      expect(status).toBe(403);
+      await expect(startPreview(dir, { pattern: "../../secrets" })).rejects.toThrow(
+        "Pattern must be",
+      );
+    } finally {
+      await preview.close();
+    }
+  });
+});
+
+describe("app utility compilation", () => {
+  it("generates a new utility from app source and resolves nested CSS assets", async () => {
+    const { mkdir, symlink } = await import("node:fs/promises");
+    const { dirname } = await import("node:path");
+    const { buildClientSource } = await import("./client-build");
+    const dir = await mkdtemp(join(tmpdir(), "cca-tailwind-"));
+    cleanups.push(dir);
+    await mkdir(join(dir, "node_modules"));
+    await mkdir(join(dir, "styles"));
+    const cliRequire = createRequire(import.meta.url);
+    const cssRequire = createRequire(cliRequire.resolve("@tailwindcss/postcss"));
+    await symlink(
+      dirname(cssRequire.resolve("tailwindcss/package.json")),
+      join(dir, "node_modules/tailwindcss"),
+    );
+    await writeFile(
+      join(dir, "main.tsx"),
+      'import "./styles/app.css"; document.body.className = "w-[317px]";',
+    );
+    await writeFile(
+      join(dir, "styles/app.css"),
+      '@import "tailwindcss"; .image { background-image: url("./mark.svg"); }',
+    );
+    await writeFile(
+      join(dir, "styles/mark.svg"),
+      '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"/>',
+    );
+    const source = await buildClientSource(dir);
+    expect(source.files[source.entry]).toContain("317px");
+    expect(source.files[source.entry]).toContain("data:image/svg+xml");
+  });
 });

package/src/cli.ts

@@ -1,14 +1,21 @@
+import { runPreview } from "./preview";
+import { runCheck } from "./check";
 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.
+const COLINE_APP_HELP = `coline-app — build and publish apps for the Coline App Store.
 
 Usage:
+  coline-app preview [options]  Local simulated preview; no credentials
+  coline-app check [options]    Check types and both bundles without uploading
   coline-app push [options]     Build and upload a new app version
   coline-app dev [options]      Watch the project and re-push on change
 
 Options:
+  --pattern <name>    Preview app, triage, board, or settings
+  --screenshots <dir> Capture preview states and report browser errors/overflow
+  --port <number>     Local preview port (default: automatic)
   --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)
@@ -27,6 +34,10 @@ export async function runCreate(argv: string[]): Promise<number> {
 export async function runColineApp(argv: string[]): Promise<number> {
   const [command, ...rest] = argv;
   switch (command) {
+    case "preview":
+      return runPreview(rest);
+    case "check":
+      return runCheck(rest);
     case "push":
       return runPush(rest);
     case "dev":

package/src/client-build.ts

@@ -0,0 +1,50 @@
+import { build } from "esbuild";
+import { readFile } from "node:fs/promises";
+import postcss from "postcss";
+import tailwind from "@tailwindcss/postcss";
+import { join, relative, dirname } from "node:path";
+
+/** Bundle from the author's installed dependencies, never the private product repo. */
+export async function buildClientSource(
+  appDir: string,
+  entry = "main.tsx",
+): Promise<{ entry: string; files: Record<string, string> }> {
+  const result = await build({
+    entryPoints: [join(appDir, entry)],
+    absWorkingDir: appDir,
+    plugins: [
+      {
+        name: "coline-app-css",
+        setup(builder) {
+          builder.onLoad({ filter: /\.css$/ }, async (args) => {
+            const local = relative(appDir, args.path);
+            if (local.startsWith("..") || local.split(/[\\/]/).includes("node_modules")) return;
+            const source = await readFile(args.path, "utf8");
+            const result = await postcss([tailwind({ base: appDir })]).process(source, {
+              from: args.path,
+            });
+            return { contents: result.css, loader: "css", resolveDir: dirname(args.path) };
+          });
+        },
+      },
+    ],
+    bundle: true,
+    write: false,
+    outfile: "client.js",
+    format: "iife",
+    platform: "browser",
+    target: "es2022",
+    jsx: "automatic",
+    minify: true,
+    logLevel: "silent",
+    define: { "process.env.NODE_ENV": '"production"' },
+    loader: { ".svg": "dataurl", ".png": "dataurl", ".jpg": "dataurl", ".woff2": "dataurl" },
+  });
+  const script = result.outputFiles.find((file) => file.path.endsWith(".js"))?.text;
+  const css = result.outputFiles.find((file) => file.path.endsWith(".css"))?.text;
+  if (!script) throw new Error("Client build produced no JavaScript.");
+  const styles = css
+    ? `const style = document.createElement("style"); style.textContent = ${JSON.stringify(css)}; document.head.append(style);\n`
+    : "";
+  return { entry: "client.js", files: { "client.js": styles + script } };
+}