@uidu/skills 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uidu/skills",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Agent skills for the uidu SDK — installable via the open agent skills ecosystem (skills.sh).",
   "license": "MIT",
   "author": "uidu",

package/skills/uidu/SKILL.md

@@ -1,18 +1,19 @@
 ---
 name: uidu
-description: Use when building uidu-powered applications — fetching CMS pages, events, stories, donation campaigns, help center articles, or forms; rendering WYSIWYG content; or scaffolding new projects with create-uidu-app. Triggers on any task involving the uidu platform, the @uidu/client SDK, or the @uidu/react bindings.
+description: Use when building on the uidu platform — a public website or an app that runs inside uidu (a custom app in a Space or workspace); reading CMS pages, events, stories, donations, help center, forms; rendering WYSIWYG content; scaffolding projects; OR provisioning/authoring uidu content (create/update/delete) from the terminal via the @uidu/cli (`uidu`). Triggers on any task involving uidu, the @uidu/client SDK, @uidu/react bindings, or the uidu CLI.
 license: MIT
 metadata:
   author: uidu
-  version: "0.1.0"
+  version: "0.5.0"
 ---
 
 # uidu SDK
 
-The uidu SDK is a TypeScript GraphQL toolkit for building websites and apps powered by the uidu platform. It is split into two packages:
+The uidu SDK is a TypeScript GraphQL toolkit for building websites and apps powered by the uidu platform. It is split into three packages:
 
 - **`@uidu/client`** — framework-agnostic GraphQL client. Safe for server-side use (RSC, route handlers, server actions, scripts).
-- **`@uidu/react`** — React hooks (`useFields`, `useQuery`, `useForm`, `useChannel`) and components (`<PageBlocks>`, `<RichText>`).
+- **`@uidu/app-bridge`** — the browser half of a custom app: the handshake with the uidu page that frames it, and its short-lived session token. Only for apps that run inside uidu.
+- **`@uidu/react`** — React hooks (`useUiduClient`, `useQuery`, `useFields`, `toText`, `useUiduApp`) and components (`<UiduAppProvider>`, `<PageBlocks>`, `<BlockRenderer>`, `<RichText>`, `<DynamicForm>`). That list is the **complete** public surface — there is no `useForm`, `usePage` or `useChannel`; for anything else, call a `@uidu/client` function.
 
 `@uidu/api.js` is a legacy bridge package and is **deprecated** — use `@uidu/react` directly.
 
@@ -20,12 +21,13 @@ The uidu SDK is a TypeScript GraphQL toolkit for building websites and apps powe
 
 Use this skill when the user is:
 
-- Building a Next.js / Remix / Astro / React app powered by the uidu GraphQL API
+- Building a Next.js / Remix / Astro / React app powered by the uidu GraphQL API — a public site, or a **custom app** that uidu shows inside a Space or workspace to signed-in members (same stack, different auth: see the rule below)
 - Fetching CMS pages, events, blog stories, donation campaigns, or help center content
 - Rendering uidu blocks with `<PageBlocks>` and a component map
 - Rendering WYSIWYG body fields with `<RichText>`
 - Bootstrapping a new project with `create-uidu-app`
-- Asking about `@uidu/client`, `@uidu/react`, `uidu`, or the uidu GraphQL API
+- **Reading or provisioning a uidu workspace from the terminal** — the `uidu` CLI (`@uidu/cli`): `uidu login`, `uidu <entity> list|get|create|update|delete`, `uidu workspace create`
+- Asking about `@uidu/client`, `@uidu/react`, the `uidu` CLI, or the uidu GraphQL API
 
 ## Package Map
 
@@ -33,6 +35,7 @@ Use this skill when the user is:
 |---|---|---|
 | `@uidu/client` | Server-side queries (RSC, server actions, scripts) | Framework-agnostic |
 | `@uidu/react` | React hooks, providers, and components | Some hooks are client-only |
+| `@uidu/app-bridge` | An app that runs inside uidu (custom app) | Browser only; in React use `<UiduAppProvider>` |
 | `@uidu/api.js` | **Do not use for new code.** | Deprecated; re-exports `@uidu/react` |
 
 Install:
@@ -41,6 +44,148 @@ Install:
 npm install @uidu/client @uidu/react
 ```
 
+## The `uidu` CLI (`@uidu/cli`)
+
+For **reading a workspace or provisioning content from the terminal** — and for driving
+uidu as an AI agent — use the `uidu` CLI. It wraps `@uidu/client`, so it shares the same
+engine and auth model. Every command supports `--json` (machine-readable — parse this).
+
+```bash
+npx @uidu/cli --help          # or: npm i -g @uidu/cli
+uidu login                    # browser OAuth (PKCE); --password-grant + UIDU_PASSWORD for CI/agents
+uidu whoami --json
+
+# entities — uniform verbs
+uidu <entity> list [--first 50] --json
+uidu <entity> get <id> --json
+uidu <entity> create --attributes '<json>'        # or --name / --slug
+uidu <entity> update <id> --attributes '<json>'
+uidu <entity> delete <id>
+
+# CMS (project-scoped — pass --project or set UIDU_PROJECT_ID)
+uidu pages list --project <id> --json
+uidu page create --name Home --slug home --attributes '{"projectId":"<id>"}'
+
+# provisioning + scaffold
+uidu workspace create --name "Acme"
+uidu workspace credentials --json                  # api key + secret
+uidu create my-app -t events                       # delegates to create-uidu-app
+```
+
+Entities: `events, stories, donations, courses, forms, contacts, deals, employees,
+bookings, calls, campaigns, kb-collections, kb-articles, channel` (read) and
+`tasks, notes, spaces` (write-only). Not every verb exists for every entity — the CLI
+reports `does not support <verb>` when it doesn't. Config resolves **flags → env
+(`UIDU_*`) → `~/.uidu/config.json`** (written by `uidu login`).
+
+## Who the app acts for — one rule
+
+What an app *looks like* (landing page, blog, dashboard, booking tool) changes nothing.
+What changes the code is **who the request acts for**:
+
+| Operation | Auth | Where it runs |
+|---|---|---|
+| **Reads** for anyone (`get*` / `list*`, `<entity> list/get`) | `publicToken` | anywhere — server, CLI, **and the browser** |
+| **Writes** as the workspace (`create*` / `update*` / `delete*`, `<entity> create/update/delete`) | account **Bearer** (`apiKey`) | CLI and **server-side** only |
+| **Anything as the signed-in member**, inside uidu (a custom app) | session token from the host, over `@uidu/app-bridge` | **the browser only** |
+
+The write functions live in `@uidu/client`, so anything the CLI provisions you can also do
+from a Next.js server action / route handler / RSC. **Never put the account Bearer token in a
+browser client component.** Authoring mutations return a payload with an `errors` array —
+always check it (non-empty = validation failure).
+
+One app can mix the rows: public pages rendered on the server with `publicToken`, and a members'
+area that only works when uidu frames it.
+
+### Inside uidu: the third row
+
+uidu renders a custom app in a sandboxed iframe and hands it a short-lived session (5 minutes,
+refreshed by the bridge) over `postMessage`. That session is the member's: the app can do what
+that person can do, and no more. It changes five things:
+
+1. **The token only exists in the browser.** It arrives after the page loads, so a Server
+   Component or a server action never has it. Pages that show member data are `'use client'`
+   and read through the bridge-backed client. Fetching them in an RSC renders an empty page.
+2. **The token only works from the app's own origin.** uidu checks `Origin` against the origin
+   it signed the token for. Don't forward it to your own backend to call uidu from there — that
+   needs a server credential uidu doesn't issue yet.
+3. **Treat the token as opaque.** Never decode it. The expiry comes with it, the bridge refreshes
+   it, and `graphqlUrl` comes with it too: never build `https://<workspace>.uidu.org` from a slug.
+4. **Data goes in the app's own Models.** The session reaches the app's own Models, fields and
+   items through `node(id:)`, and the data-engine mutations. Everything else in the workspace comes
+   back as an error. Keep your data there rather than in a database of your own: it stays
+   searchable and permissioned in uidu.
+   `listModelItems` reads uidu's **search index**, which catches up a moment after a write:
+   after `createModelItem` / `deleteModelItem`, update your list from the mutation payload
+   instead of re-listing, or the new item is missing. And load models once per app instance
+   (memoize the promise): two concurrent `ensureModel` calls each create the model.
+5. **No cookies, no `localStorage` for shared state.** In a cross-origin iframe cookies are
+   third-party (Safari drops them). `localStorage` is this browser only. Use it only as the
+   fallback when the page is opened outside uidu (the bridge rejects `connect()` there).
+
+```tsx
+'use client'; // app/layout.tsx renders <AppProvider> around {children}
+import { useEffect, useState } from 'react';
+import { UiduAppProvider, useUiduApp } from '@uidu/react';
+import { DEFAULT_HOST_ORIGINS } from '@uidu/app-bridge';
+import {
+  createModelItem, ensureModel, listModelItems, toFieldValuesAttributes,
+  type ModelItem, type UiduClient,
+} from '@uidu/client';
+
+export function AppProvider({ children }: { children: React.ReactNode }) {
+  // https://*.uidu.org by default; add a local uidu or a custom domain
+  return <UiduAppProvider hostOrigins={[...DEFAULT_HOST_ORIGINS]}>{children}</UiduAppProvider>;
+}
+
+async function loadBookings(client: UiduClient, workspaceAppId: string) {
+  // interim: the app creates its own model on first load (install-time manifest comes later)
+  const model = await ensureModel(client, {
+    workspaceAppId,
+    name: 'Booking',
+    fields: [{ shortname: 'room', name: 'Room', kind: 'string' }],
+  });
+  await createModelItem(client, {
+    input: { attributes: { modelId: model.id, fieldValuesAttributes: toFieldValuesAttributes(model, { room: 'Blu' }) } },
+  });
+  return listModelItems(client, { modelId: model.id }); // item.fieldValuesByShortname.room
+}
+
+export function Bookings() {
+  const app = useUiduApp(); // 'connecting' | 'ready' | 'error'
+  const [items, setItems] = useState<ModelItem[]>([]);
+
+  useEffect(() => {
+    if (app.status === 'ready') loadBookings(app.client, app.context.workspaceApp.id).then(setItems);
+  }, [app]);
+
+  if (app.status === 'error') return <p>Open this app from uidu ({app.error.code})</p>; // NOT_EMBEDDED, TIMEOUT…
+  return <ul>{items.map((item) => <li key={item.id}>{item.fieldValuesByShortname?.room}</li>)}</ul>;
+}
+```
+
+`app.context` carries `user`, `space`, `workspaceApp`, `locale` and `theme`. Outside React: `connect()` from
+`@uidu/app-bridge`, then `createClient(fromBridge(bridge))` from `@uidu/client`. Start a new
+one with `npm create uidu-app@latest my-app -- -t custom-app`: it declares its Models in
+`public/uidu.app.json` and sets `frame-ancestors` so only uidu can frame it.
+
+## Working transparently
+
+The user often can't tell what you're doing when you drive the CLI. Stay legible:
+
+- **Orient first.** Before a multi-step task (especially scaffolding), say in plain words what the
+  end result is — e.g. "this creates a Next.js 16 + Tailwind project folder on your machine, wired
+  to your workspace, that you'll run at http://localhost:3000" — plus what they need (Node 20+;
+  the CLI runs via `npx`, nothing to install globally).
+- **Show which account is active first.** Run `uidu whoami --json` and state the account/workspace
+  before anything else, so it's obvious you're touching their real (prod) workspace.
+- **Echo commands.** Print the actual `uidu … --json` command before you run it, and one line on
+  why.
+- **Never write without confirming.** Reads (`* list`, `* get`, `whoami`, `credentials`) run
+  freely. Any `create` / `update` / `delete` or provisioning hits the live workspace — ask first.
+- **Summarize results.** Parse the `--json` and report what came back or what changed in plain
+  words; always surface a non-empty `errors` array instead of moving on.
+
 ## API Shape
 
 All SDK functions are **standalone functions** that take the client as the first argument. They are never namespaced as methods on the client object:
@@ -216,29 +361,103 @@ const channel = await getChannel(uidu, { id: channelId });
 
 ### Forms
 
-Forms are fetched server-side, then rendered with the `useForm` hook on the client:
+Fetch the schema server-side, render it with `<DynamicForm>`, and submit through a
+**server-side** action that calls `createFormResponse`. There is no `useForm` hook.
 
 ```tsx
-// Server: fetch form schema
+// Server: fetch the form schema
 import { getForm } from '@uidu/client';
 const form = await getForm(uidu, { id: formId });
 ```
 
 ```tsx
-// Client: render with @uidu/react
+// Client: render it
 'use client';
-import { useForm } from '@uidu/react';
+import { DynamicForm } from '@uidu/react';
+import { submitForm } from '@/lib/actions';
 
 export function ContactForm({ form }) {
-  const { register, handleSubmit, onSubmit } = useForm(uidu, { form });
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      {/* render fields by iterating form.formQuestions.edges */}
-    </form>
-  );
+  return <DynamicForm form={form} action={submitForm} />;
 }
 ```
 
+`<DynamicForm>` renders the questions itself and hands your `action` a
+`DynamicFormValues`: `{ contact?: { firstName, lastName, email }, fieldValues:
+Array<{ fieldId, questionId, value }>, formData }`. Return `{ ok: true }` or
+`{ ok: false, errors }` and it renders the right state.
+
+#### `content` is always `{ value: … }` — never a bare value
+
+This is the one rule that breaks form writes. The API stores each answer in a JSON
+`content` column and reads it back as `content['value']`. A flat scalar is **not**
+rejected loudly: the response saves with empty typed columns, and reading that field
+later throws. `FieldValueAttributes` exposes no `value` key — `content` is the only way in.
+
+```ts
+// ✅ Correct — every answer wrapped
+fieldValuesAttributes: [{ fieldId: 'f1', content: { value: 'hello@example.com' } }]
+
+// ❌ Wrong — silently loses the answer
+fieldValuesAttributes: [{ fieldId: 'f1', content: 'hello@example.com' }]
+```
+
+It holds for **every** field kind, not just strings — `{ value: 42 }`, `{ value: true }`,
+`{ value: '2026-07-27' }`, `{ value: ['gid://…', 'gid://…'] }` for `multipleSelect`,
+`{ value: <doc> }` for `richText`/`json`. And it holds for `fieldValuesAttributes`
+**wherever** it appears — on a page block, a contact, a story, a booking — not just on
+form responses.
+
+Full submit action:
+
+```ts
+// src/lib/actions.ts
+'use server';
+import { createFormResponse } from '@uidu/client';
+import type { DynamicFormValues, DynamicFormResult } from '@uidu/react';
+import { uidu } from '@/lib/uidu';
+
+export async function submitForm(
+  values: DynamicFormValues,
+): Promise<DynamicFormResult> {
+  const result = await createFormResponse(uidu, {
+    input: {
+      event: 'complete!', // omit to save as a draft
+      attributes: {
+        formId: FORM_ID,
+        fieldValuesAttributes: values.fieldValues.map((fv) => ({
+          fieldId: fv.fieldId,
+          content: { value: fv.value }, // ← wrapped
+        })),
+        contactAttributes: values.contact && {
+          email: values.contact.email,
+          contactableAttributes: {
+            kind: 'person',
+            firstName: values.contact.firstName,
+            lastName: values.contact.lastName,
+          },
+        },
+      },
+    },
+  });
+
+  if (result?.errors?.length) return { ok: false, errors: result.errors };
+  return { ok: true, meta: { id: result?.formResponse?.id } };
+}
+```
+
+Notes:
+
+- **Never put arbitrary keys in `attributes`.** Only what `FormResponseAttributes`
+  declares: `formId`, `fieldValuesAttributes`, `contactAttributes`, `contactId`,
+  `formPageId`, `completedAt`, `responsableId`, `id`. Unknown keys fail the mutation.
+- `event` lives on `input`, **not** inside `attributes`, and is a state-machine
+  transition (`'complete!'`, `'save_draft!'`) — not free text.
+- To record a timestamp, use `completedAt` on `attributes`, not a synthetic field value.
+- `createFormResponse` **returns** `{ errors, formResponse }` instead of throwing —
+  always check `errors` before treating a submit as successful.
+- Use `updateFormResponse` for multi-step or save-as-you-type flows; pass each
+  answer's existing `id` in `fieldValuesAttributes` to update it rather than add a new one.
+
 ## Rendering WYSIWYG Content
 
 All `body` fields on Event, Story, DonationCampaign, etc. are structured documents (not strings). Render them with `<RichText>` from `@uidu/react`:
@@ -253,7 +472,7 @@ The prop is `doc`, not `children`. The component handles paragraphs, headings, l
 
 ## Provider Setup (Client-Side Hooks)
 
-Server-side `await getX(...)` calls do not need a provider. For React client-side hooks (`useQuery`, `useFields`, `useForm`), wrap your app in `<UiduProvider>`:
+Server-side `await getX(...)` calls do not need a provider. For React client-side hooks (`useQuery`, `useUiduClient`), wrap your app in `<UiduProvider>`. (`useFields` and `toText` are pure functions — they work without a provider, on the server too.)
 
 ```tsx
 // app/layout.tsx
@@ -304,13 +523,12 @@ npm create uidu-app@latest my-app -- -t events
 | `events` | Event listing + `/event/[id]` detail |
 | `stories` | Blog listing + `/story/[id]` detail (magazine layout) |
 | `donations` | Campaigns listing + `/campaign/[id]` detail with progress bars |
+| `custom-app` | An app inside a uidu Space: `<UiduAppProvider>`, data in its own Models (`public/uidu.app.json`) |
 
-Every template ships with:
-- Next.js 16 App Router
-- Tailwind v4
-- A configured `src/lib/uidu.ts`
-- A server-rendered listing + dynamic detail page
-- `.env.example` with required vars (and the CLI offers to fill them in for you)
+Every template ships with Next.js 16 App Router, Tailwind v4 and an `.env.example` (the CLI
+offers to fill it in for you). The site templates add a configured `src/lib/uidu.ts` and a
+server-rendered listing + dynamic detail page; `custom-app` has no token to configure and
+reads everything in client components.
 
 ## See Also
 

package/skills/uidu/metadata.json

@@ -1,6 +1,6 @@
 {
   "name": "uidu",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "author": "uidu",
   "license": "MIT",
   "homepage": "https://docs.uidu.org",