@cellapp/cli 0.1.0 → 0.2.1

package/package.json

@@ -1,14 +1,33 @@
 {
   "name": "@cellapp/cli",
-  "version": "0.1.0",
-  "description": "CellApp static application deployment CLI and Agent Skill",
+  "version": "0.2.1",
+  "description": "Cellapp static application deployment CLI and Agent Skill",
   "type": "module",
   "license": "MIT",
-  "publishConfig": {"access": "public", "registry": "https://registry.npmjs.org/"},
-  "workspaces": ["packages/cli", "packages/shared"],
-  "engines": {"node": ">=22.12.0"},
-  "bin": {"cellapp": "dist/packages/cli/src/main.js", "ohmyapp": "dist/packages/cli/src/main.js"},
-  "files": ["dist/packages", "skills/cellapp-deploy", "README.md", "LICENSE", "NOTICE"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "workspaces": [
+    "packages/cli",
+    "packages/shared"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "cellapp": "dist/packages/cli/src/main.js",
+    "ohmyapp": "dist/packages/cli/src/main.js"
+  },
+  "files": [
+    "dist/packages",
+    "skills/cellapp-deploy",
+    "!skills/cellapp-deploy/examples/**/node_modules",
+    "!skills/cellapp-deploy/examples/**/dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/skills/cellapp-deploy/SKILL.md

@@ -1,22 +1,47 @@
 ---
 name: cellapp-deploy
-description: Publish or update a static HTML site or frontend tool on CellApp using local builds, device authorization, and an app-specific share key. Use when the user asks to deploy to CellApp; does not host backends or synchronize app data.
+description: Build and publish a static Cellapp frontend, manage its PostgreSQL tables and row policies, and connect supported supabase-js CRUD without an application backend.
 ---
 
-# Deploy a static application
+# Develop and deploy a Cellapp application
 
-Use the installed `cellapp` CLI. Installing this Skill does not install the CLI; if it is unavailable, tell the user to install the CellApp CLI using the public repository README. Do not substitute another hosting provider or invent a control URL. The control origin comes from the user's configuration, `CELLAPP_ORIGIN`, or an existing `cellapp.json`. Existing `ohmyapp.json` and `OHMYAPP_ORIGIN` are supported during migration.
+Use the installed `cellapp` CLI. Installing this Skill does not install the CLI; if it is unavailable, direct the user to the public repository README. Use an origin supplied by the user, existing project configuration, or `CELLAPP_ORIGIN` when present; otherwise the CLI defaults to `https://console.cellapp.ai`. Preserve `ohmyapp.json` and `OHMYAPP_ORIGIN` migration behavior. Do not invent another origin or store a credential in the project.
 
-Inspect the project's existing build command and static output directory. Reuse `cellapp.json` for updates. For a plain HTML directory, omit the build command. If the output directory or build command is ambiguous, ask only for the missing setting. A backend, SSR server, secret-dependent API, or database cannot be deployed with this skill; explain the static-export requirement before attempting publication.
+## Inspect
 
-Run `cellapp deploy --project <project> --output <output-directory> --build <existing-build-command> --origin <control-origin>`, omitting `--build` for plain HTML. Add `--spa` only when client-side page routing requires index fallback. Quote all paths and commands for the shell in use. Run user project builds under the agent's normal execution permissions.
+Read `cellapp.json`, the existing build command, static output directory, and `cellapp.data.json` if present. Reuse the application association on updates. For plain HTML omit the build command. Ask only for an ambiguous output or build setting. Cellapp hosts static frontend code; do not deploy SSR, a custom server, private service key, direct PostgreSQL credential, or arbitrary SQL. Bundled frontend values are readable by admitted visitors.
 
-The CLI starts device authorization automatically when no credential exists. Show the user the verification link and matching code, and keep the command running while they approve in a browser. Do not request account passwords or copy the deployment token into the conversation. Authorization denial/expiry stops the flow; let the user initiate another attempt.
+## Choose an application reference
 
-Only report deployment success after the CLI returns `status: published`. Return the application URL and the initial app-specific share key to the requesting owner. For updates, report that the existing share key remains valid. Never put a key into a URL, repository, issue, or unrelated message. The key grants access to the application; it grants no management permissions.
+The display name may repeat. Every owner has one public user slug (`namespace` in the API and CLI), and application slugs are unique inside it. On the first deployment a new owner may choose `--namespace <user-slug>`; each new app may choose `--slug <app-slug>`. Both use lowercase ASCII letters, digits and hyphens and start with a letter. The user slug needs at least three characters, reserved names such as `accounts`, `cloud`, `login` and `app` are unavailable, and `{app-slug}-{user-slug}` must fit one 63-character DNS label. Without choices, Cellapp assigns a privacy-preserving user slug and an application slug derived from the display name, adding a suffix on collision. Existing owners must reuse their established user slug for CLI creation. The console can update either slug after creation. The returned URL uses `{app-slug}-{user-slug}.<apps-domain>`; prior addresses remain assigned to the original app. The `@user-slug/app-slug` share link redirects to the current host. Never treat a slug or display name as an authorization identity; app access and tables remain bound to the immutable app ID.
 
-On a transient upload/network error, retry the same deploy command once: saved pending metadata reuses the deployment operation. Stop after another failure and report the specific error. A version conflict requires refreshing the intended version before starting a new deployment; do not silently overwrite a concurrent update. For quota errors explain the configured limit and recovery action, without purchasing services or deleting apps automatically.
+## Plan, apply, and verify tables
 
-App management commands are `cellapp apps`, `cellapp reset-key <app-id>`, `cellapp delete <app-id>`, `cellapp login`, and `cellapp logout`. Resetting a key invalidates existing sessions. Use reset or delete only when requested; do not reset keys as an invisible retry strategy. If a first deployment's key is lost, explain that the owner can explicitly reset it.
+The versioned, non-secret [`cellapp.data.json`](examples/notes/cellapp.data.json) manifest defines tables, columns, primary keys, indexes and operation policies. Types: `text`, `uuid`, `bigint`, `boolean`, `timestamptz`, `jsonb`. Policy modes: `none` (default), `all-admitted-users`, `own-rows`. The `own-rows` mode needs a non-null text `ownerColumn`; reads and writes are checked against the signed application user ID. Every table needs a primary key. No SQL, function, trigger, database password or provider identity belongs in the manifest. Table names are scoped to the app: an app may define `users` without touching platform users or another app's `users`. This is ordinary app data, not the platform identity source. Keep names unique within one app; `rpc` is reserved for the unsupported PostgREST route, PostgreSQL system column names are unavailable, and generated index names must not collide with table names. Check these rules with `data plan` before applying.
 
-Explain the relevant first-deployment limits briefly: frontend code and bundled values are readable by authorized visitors; never bundle private API credentials. Browser local data is not synchronized between devices. The service hosts static content only, with no user backend or offline Service Worker support.
+A new project needs its first static deployment to create the application association in `cellapp.json`. Build and deploy the frontend once, then use the linked app and configured origin to apply the data manifest. Do not report the table-dependent page as ready until verification succeeds:
+
+```sh
+cellapp data status --project <project>
+cellapp data plan --project <project>
+cellapp data apply --project <project>
+cellapp data verify --project <project>
+```
+
+The first manifest version is `1`; increase by exactly one. Inspect the plan and data version separately from the static release. Identical retries are safe; changed content at an applied version conflicts. For a table or column drop, set `allowDestructive: true` in the manifest and pass `--allow-destructive` to `data apply` after reviewing the plan and backup implications. After a timeout, run status and verify, then retry the same manifest if needed. Do not create a new version for a retry. Adding a non-null column to a populated table fails and rolls back; use a nullable column in this initial subset.
+
+New tables and operations deny frontend access until granted. Apply with an owner credential. Verify an allowed operation and a denied cross-user or ungranted operation before handing out the app URL. Distinguish database-only tests from real browser and PostgREST acceptance. The application database is separate from control data and other apps; application code gets no database password.
+
+## Connect the static frontend
+
+Use `@supabase/supabase-js@2.117.3` for the declared table subset. Initialize `createClient(window.location.origin, 'cellapp-public', {auth: {autoRefreshToken: false, persistSession: false, detectSessionInUrl: false}})`. The publishable string is non-secret and grants nothing. Cellapp checks the logged-in user's host-only app session and admission on each request. Fetch `/_cellapp/me` with same-origin credentials for the stable app-scoped ID; never expose or derive a global Cellapp ID. See the [runnable notes demo](examples/notes/README.md), which includes its build, manifest, and browser CRUD page.
+
+Use only `.from(table).select(columns)`, `.insert(values)`, `.update(values)`, `.delete()`, `.eq()`, `.order()`, `.range()` and `.select()` after a write for returned rows. Handle `{data,error}` and 401/403 states visibly. Supabase Auth, Realtime, Storage, RPC, Edge Functions, joins, arbitrary filters, direct database access, and custom application servers are outside this release. The gateway ignores client authorization/profile headers. A public app admits any signed-in Cellapp user, while tables still require policies. A restricted app requires owner approval or access-key redemption after login.
+
+## Publish and report
+
+Run `cellapp deploy --project <project> --output <output-directory> --build <existing-build-command>` (optionally adding `--namespace` and `--slug` on the first deployment), omitting `--build` for plain HTML. Add `--spa` only for client-side routes. The CLI performs device authorization when needed; provide the verification link and code, keep the command running, and never request account passwords. Report publication only after `status: published`. Report data version/verification and static release separately, then provide the app URL.
+
+The first deployment returns an access key once. Give it only to the requesting owner; never put it in a URL, repository, issue or project state. Old keys can be redeemed only after platform login. `cellapp reset-key <app-id>` rotates future redemption; existing user grants remain active. Revoke an individual grant in the owner console. Use reset or delete only when requested. A lost initial key can be explicitly rotated.
+
+On transient upload/network failure, retry the same deploy command once: pending project metadata reuses the operation. Stop after another failure and report the error. A release version conflict needs review. If creation reports `app_data_not_ready`, keep `cellapp.json`, inspect `cellapp data status --project <project>` and retry `cellapp data reconcile --project <project>` after the platform data service is healthy; then retry deploy. Do not switch slugs or delete the app to work around this error. For an app created by an older CLI without `cellapp.json`, run `cellapp link <app-id> --project <project> --output <output-directory>` using an ID verified in `cellapp apps`. The CLI keeps the initial access key only in its private credential directory until publication; never copy it into project files. For data errors use `data status` and `data verify`; do not claim a table-dependent frontend is ready while its data API is unready. Browser local-only state does not synchronize between devices; managed table data does.

package/skills/cellapp-deploy/examples/notes/README.md

@@ -0,0 +1,21 @@
+# Cellapp 笔记 Demo
+
+这是一个可以直接发布的静态前端。Cellapp 管理登录身份、应用数据库和访问控制；浏览器用 `supabase-js` 读写 `notes` 表。每位已获准访问应用的用户只能看到自己的笔记。无需自建服务端、Supabase 项目或数据库密码。
+
+## 运行
+
+需要 Node.js 22.12+、已安装并登录的 `cellapp` CLI，以及一个可用的 Cellapp 环境。先设置 `CELLAPP_ORIGIN` 为控制台 HTTPS 地址。
+
+```sh
+cd <本示例目录>
+npm ci
+npm run build
+cellapp deploy --project . --output dist --name "Notes demo" --slug notes-demo
+cellapp data plan --project .
+cellapp data apply --project .
+cellapp data verify --project .
+```
+
+首次部署可加 `--namespace <你的空间名>` 自选命名空间；未指定时 Cellapp 生成与平台用户 ID 无关的空间名。示例中的 `--slug notes-demo` 在同一空间内必须唯一。应用显示名可以重名，控制台提供 `@空间名/notes-demo` 分享链接，原应用 ID 地址保持稳定。首次部署会创建应用及项目关联，然后 `data apply` 在独立应用数据库中建表并授予当前应用的表操作权限。首次发布返回的访问密钥只交给所有者，不要存入项目文件。打开部署返回的应用地址，完成 Cellapp 登录；受限应用还需授权访问。页面可新增、查看、编辑、删除笔记；“Run CRUD” 会依次执行创建、读取、更新和删除，并显示结果。第一次打开前应完成 `data verify`，确认 `ready: true`。
+
+`cellapp.data.json` 声明表、主键、索引及 `own-rows` 策略。[`notes.ts`](notes.ts) 只用支持的 `supabase-js` 表级操作和 `/_cellapp/me` 应用内身份；`cellapp-public` 是非秘密标识，不授予任何数据权限。构建产物仅包含静态前端，不包含 CLI 凭证、访问密钥或数据库连接串。

package/skills/cellapp-deploy/examples/notes/app.ts

@@ -0,0 +1,115 @@
+import { addNote, currentAppUser, deleteNote, listNotes, updateNote } from './notes.js';
+
+const form = document.querySelector<HTMLFormElement>('#create-form')!;
+const input = document.querySelector<HTMLInputElement>('#note-body')!;
+const notes = document.querySelector<HTMLUListElement>('#notes')!;
+const identity = document.querySelector<HTMLElement>('#identity')!;
+const status = document.querySelector<HTMLElement>('#status')!;
+const check = document.querySelector<HTMLButtonElement>('#crud')!;
+
+function report(message: string, error = false): void {
+  status.textContent = message;
+  status.classList.toggle('error', error);
+}
+
+function failure(error: unknown): void {
+  report(error instanceof Error ? error.message : String(error), true);
+}
+
+async function refresh(): Promise<void> {
+  const rows = await listNotes();
+  notes.replaceChildren();
+  if (!rows?.length) {
+    const empty = document.createElement('li');
+    empty.textContent = '还没有笔记。';
+    notes.append(empty);
+    return;
+  }
+  for (const row of rows) {
+    const item = document.createElement('li');
+    const body = document.createElement('span');
+    body.textContent = row.body;
+    const actions = document.createElement('div');
+    const edit = document.createElement('button');
+    edit.type = 'button';
+    edit.className = 'secondary';
+    edit.textContent = '编辑';
+    edit.setAttribute('aria-label', `编辑笔记 ${row.body}`);
+    edit.addEventListener('click', async () => {
+      const next = prompt('修改笔记', row.body);
+      if (next === null || !next.trim()) return;
+      edit.disabled = true;
+      try {
+        await updateNote(row.id, next.trim());
+        await refresh();
+        report('笔记已更新');
+      } catch (error) { failure(error); }
+      finally { edit.disabled = false; }
+    });
+    const remove = document.createElement('button');
+    remove.type = 'button';
+    remove.className = 'secondary';
+    remove.textContent = '删除';
+    remove.setAttribute('aria-label', `删除笔记 ${row.body}`);
+    remove.addEventListener('click', async () => {
+      remove.disabled = true;
+      try {
+        await deleteNote(row.id);
+        await refresh();
+        report('笔记已删除');
+      } catch (error) { failure(error); }
+      finally { remove.disabled = false; }
+    });
+    actions.append(edit, remove);
+    item.append(body, actions);
+    notes.append(item);
+  }
+}
+
+form.addEventListener('submit', async event => {
+  event.preventDefault();
+  const body = input.value.trim();
+  if (!body) return;
+  const save = form.querySelector<HTMLButtonElement>('button')!;
+  save.disabled = true;
+  try {
+    await addNote(body);
+    input.value = '';
+    await refresh();
+    report('笔记已保存');
+  } catch (error) { failure(error); }
+  finally { save.disabled = false; }
+});
+
+check.addEventListener('click', async () => {
+  check.disabled = true;
+  const marker = `CRUD ${crypto.randomUUID()}`;
+  try {
+    const inserted = await addNote(marker);
+    if (inserted?.length !== 1) throw new Error('创建后未返回笔记');
+    const row = inserted[0]!;
+    const selected = await listNotes();
+    if (!selected?.some(note => note.id === row.id && note.body === marker)) throw new Error('未读到刚创建的笔记');
+    const changed = await updateNote(row.id, marker + ' updated');
+    if (changed?.[0]?.body !== marker + ' updated') throw new Error('更新后的内容不一致');
+    await deleteNote(row.id);
+    const remaining = await listNotes();
+    if (remaining?.some(note => note.id === row.id)) throw new Error('删除后仍能读到笔记');
+    await refresh();
+    report('CRUD passed');
+  } catch (error) { failure(error); }
+  finally { check.disabled = false; }
+});
+
+void (async () => {
+  try {
+    const user = await currentAppUser();
+    document.body.dataset.user = user;
+    identity.textContent = `当前应用用户：${user.slice(0, 8)}…`;
+    await refresh();
+    report('应用数据库已连接');
+  } catch (error) {
+    identity.textContent = '无法连接应用数据库';
+    failure(error);
+  }
+})();

package/skills/cellapp-deploy/examples/notes/cellapp.data.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "tables": [
+    {
+      "name": "notes",
+      "columns": [
+        {"name": "id", "type": "uuid"},
+        {"name": "owner_id", "type": "text"},
+        {"name": "body", "type": "text"}
+      ],
+      "primaryKey": ["id"],
+      "indexes": [{"columns": ["owner_id"]}],
+      "policies": {
+        "select": "own-rows",
+        "insert": "own-rows",
+        "update": "own-rows",
+        "delete": "own-rows",
+        "ownerColumn": "owner_id"
+      }
+    }
+  ]
+}

package/skills/cellapp-deploy/examples/notes/index.html

@@ -0,0 +1,40 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Cellapp 笔记 Demo</title>
+  <style>
+    :root { font-family: system-ui, sans-serif; color: #1c2b25; background: #f4f7f3; }
+    body { max-width: 720px; margin: 40px auto; padding: 0 20px; }
+    main { background: white; padding: 28px; border: 1px solid #d9e5dc; border-radius: 16px; box-shadow: 0 8px 32px #1536230d; }
+    h1 { margin: 0 0 8px; }
+    p { line-height: 1.5; }
+    form { display: flex; gap: 8px; margin: 20px 0; }
+    input { flex: 1; min-width: 0; padding: 10px; border: 1px solid #adbfaf; border-radius: 8px; font: inherit; }
+    button { padding: 9px 14px; border: 0; border-radius: 8px; color: white; background: #21684a; font: inherit; cursor: pointer; }
+    button:disabled { opacity: .55; cursor: wait; }
+    button.secondary { color: #21684a; background: #e5f0e8; }
+    li { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 12px 0; border-top: 1px solid #e7eee7; }
+    li span { overflow-wrap: anywhere; }
+    li div { display: flex; gap: 8px; flex: none; }
+    #status { min-height: 1.5em; color: #345446; }
+    #status.error { color: #a22828; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Notes app</h1>
+    <p>使用 Cellapp 登录身份保存笔记。每位用户只能读写自己的记录。</p>
+    <p id="identity">正在连接应用数据库…</p>
+    <form id="create-form">
+      <input id="note-body" aria-label="笔记内容" maxlength="2000" required placeholder="写一条笔记">
+      <button type="submit">保存笔记</button>
+    </form>
+    <p id="status" role="status" aria-live="polite"></p>
+    <ul id="notes"></ul>
+    <button id="crud" class="secondary" type="button">Run CRUD</button>
+  </main>
+  <script type="module" src="/app.js"></script>
+</body>
+</html>

package/skills/cellapp-deploy/examples/notes/notes.ts

@@ -0,0 +1,37 @@
+import { createClient } from '@supabase/supabase-js';
+
+const client = createClient(window.location.origin, 'cellapp-public', {
+  auth: { autoRefreshToken: false, persistSession: false, detectSessionInUrl: false },
+});
+
+export async function currentAppUser(): Promise<string> {
+  const response = await fetch('/_cellapp/me', { credentials: 'same-origin' });
+  if (!response.ok) throw new Error(response.status === 401 ? 'Sign in to Cellapp' : 'Application access required');
+  const value: unknown = await response.json();
+  if (!value || typeof value !== 'object' || !('id' in value) || typeof value.id !== 'string') throw new Error('Invalid application identity');
+  return value.id;
+}
+
+export async function addNote(body: string) {
+  const ownerId = await currentAppUser();
+  const result = await client.from('notes').insert({ id: crypto.randomUUID(), owner_id: ownerId, body }).select('id,body');
+  if (result.error) throw result.error;
+  return result.data;
+}
+
+export async function listNotes() {
+  const result = await client.from('notes').select('id,body').order('id').range(0, 49);
+  if (result.error) throw result.error;
+  return result.data;
+}
+
+export async function updateNote(id: string, body: string) {
+  const result = await client.from('notes').update({ body }).eq('id', id).select('id,body');
+  if (result.error) throw result.error;
+  return result.data;
+}
+
+export async function deleteNote(id: string) {
+  const result = await client.from('notes').delete().eq('id', id);
+  if (result.error) throw result.error;
+}