@agent-native/core 0.37.2 → 0.38.0

package/src/templates/workspace-core/.agents/skills/extensions/references/api.md

@@ -0,0 +1,285 @@
+# Extension API Reference
+
+This is the exhaustive reference for the helpers and globals injected into
+every extension iframe, plus the back-compat naming table. For the model +
+when-to-use overview, see `../SKILL.md`. For worked HTML examples, see
+`examples.md`.
+
+## Accessing app data
+
+Extensions can call the host app's actions and API endpoints directly. The
+iframe shares the session cookie, so authentication is automatic.
+
+### `appAction(name, params)` — Call app actions
+
+Call any action defined in the app's `actions/` directory. Actions are
+auto-mounted at `/_agent-native/actions/:name`.
+
+```html
+<div
+  x-data="{ emails: [], loading: true }"
+  x-init="
+  appAction('list-emails', { view: 'inbox', limit: 10 })
+    .then(d => { emails = d.emails || d; loading = false })
+    .catch(e => { console.error(e); loading = false })
+"
+>
+  <h2 class="text-lg font-semibold mb-4">My Inbox</h2>
+  <template x-for="email in emails" :key="email.id">
+    <div class="rounded-lg border p-3 mb-2">
+      <p class="font-medium text-sm" x-text="email.subject"></p>
+      <p
+        class="text-xs text-muted-foreground"
+        x-text="email.from?.name || email.from?.email"
+      ></p>
+    </div>
+  </template>
+</div>
+```
+
+### `appFetch(path, options)` — Call allowed framework endpoints
+
+General-purpose fetch to allowed framework endpoints (for example,
+`/_agent-native/application-state/navigation`). Automatically adds credentials
+and JSON content type. Template `/api/*` routes are intentionally blocked by
+the extension bridge; use `appAction(name, params)` for app data instead.
+
+```javascript
+// Read application state
+const nav = await appFetch("/_agent-native/application-state/navigation");
+
+// Call a framework route
+const nav = await appFetch("/_agent-native/application-state/navigation");
+```
+
+### `dbQuery(sql)` — Read from the app's database
+
+Run a read-only SELECT query against the app's SQL database. Results are
+auto-scoped to the current user/org.
+
+```html
+<div
+  x-data="{ rows: [] }"
+  x-init="
+  dbQuery('SELECT id, name FROM tools ORDER BY created_at DESC LIMIT 10')
+    .then(d => rows = d.rows || d)
+"
+>
+  <template x-for="row in rows" :key="row.id">
+    <div class="border-b p-2 text-sm" x-text="row.name"></div>
+  </template>
+</div>
+```
+
+> The physical SQL table is still named `tools` (and `tool_data`,
+> `tool_shares`) for back-compat. The Drizzle exports are `extensions`,
+> `extensionData`, and `extensionShares` — use those when you query via the
+> ORM. When writing raw SQL inside an extension (as above), use the
+> physical names.
+
+### `dbExec(sql)` — Write to the app's database
+
+Run an INSERT, UPDATE, or DELETE statement. Writes are auto-scoped to the
+current user/org, and `owner_email` / `org_id` are auto-injected on INSERT.
+
+```javascript
+// Insert a new record
+await dbExec(
+  "INSERT INTO notes (id, title, body) VALUES ('abc', 'My Note', 'Hello world')",
+);
+
+// Update an existing record
+await dbExec("UPDATE notes SET title = 'Updated Title' WHERE id = 'abc'");
+```
+
+### All helpers summary
+
+| Helper                                           | Use for                                                  | Example                                                                                                          |
+| ------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `appAction(name, params)`                        | Call app actions (CRUD, queries)                         | `appAction('list-emails', { view: 'inbox' })`                                                                    |
+| `appFetch(path, options)`                        | Call allowed framework endpoints                         | `appFetch('/_agent-native/application-state/navigation')`                                                        |
+| `dbQuery(sql)`                                   | Read from the app's SQL database                         | `dbQuery('SELECT * FROM notes LIMIT 10')`                                                                        |
+| `dbExec(sql)`                                    | Write to the app's SQL database                          | `dbExec("INSERT INTO notes ...")`                                                                                |
+| `extensionFetch(url, options)`                   | Call external APIs via proxy (alias `toolFetch`)         | `extensionFetch('https://api.github.com/user', { headers: { 'Authorization': 'Bearer ${keys.GITHUB_TOKEN}' } })` |
+| `extensionData.set(collection, id, data, opts?)` | Save an item to extension storage (alias `toolData.set`) | `extensionData.set('todos', 'todo-1', { title: 'Buy milk' })`                                                    |
+| `extensionData.list(collection, opts?)`          | List items in a collection                               | `extensionData.list('todos', { scope: 'all' })`                                                                  |
+| `extensionData.get(collection, id, opts?)`       | Get a single item by id                                  | `extensionData.get('todos', 'todo-1')`                                                                           |
+| `extensionData.remove(collection, id, opts?)`    | Delete an item                                           | `extensionData.remove('todos', 'todo-1')`                                                                        |
+
+## Persisting Custom Data
+
+Extensions have a built-in key-value store via `extensionData` (legacy alias:
+`toolData`). Each extension gets its own isolated storage, organized into
+collections. Every method accepts an optional `{ scope }` option:
+
+- `'user'` (default) — private to the current user
+- `'org'` — visible to everyone in the user's org
+- `'all'` (list/get only) — returns both user and org items
+
+```javascript
+// Save a private item (default scope: 'user')
+await extensionData.set("todos", "todo-1", { title: "Buy milk", done: false });
+
+// Save an org-shared item
+await extensionData.set(
+  "todos",
+  "team-todo-1",
+  { title: "Ship v2", done: false },
+  { scope: "org" },
+);
+
+// List user items (default)
+const myTodos = await extensionData.list("todos");
+
+// List org items
+const orgTodos = await extensionData.list("todos", { scope: "org" });
+
+// List both user + org items
+const allTodos = await extensionData.list("todos", { scope: "all" });
+// Returns: [{ id, toolId, collection, data (JSON string), ownerEmail, scope, orgId, createdAt, updatedAt }]
+// (the row column is still named `toolId` for back-compat — it's the extension id)
+
+// Parse the JSON data
+const parsed = allTodos.map((t) => ({
+  ...JSON.parse(t.data),
+  id: t.id,
+  scope: t.scope,
+}));
+
+// Get/delete with scope
+const item = await extensionData.get("todos", "team-todo-1", { scope: "org" });
+await extensionData.remove("todos", "team-todo-1", { scope: "org" });
+```
+
+Data is scoped per-extension. User-scoped items are private per-user;
+org-scoped items are shared across the org. Any org member can read,
+update, or delete org-scoped items. **Prefer `extensionData` over raw
+`dbExec` for extension-specific persistence** — it handles table creation,
+scoping, and upserts automatically.
+
+## Using `extensionFetch()` for API calls
+
+`extensionFetch()` (legacy alias `toolFetch()`) is a drop-in replacement for
+`fetch()` that proxies requests through the server. The server injects
+secret values before the request leaves.
+
+```javascript
+// Basic GET
+const res = await extensionFetch("https://api.example.com/data");
+const data = await res.json();
+
+// With secret injection
+const res = await extensionFetch("https://api.openai.com/v1/models", {
+  headers: {
+    Authorization: "Bearer ${keys.OPENAI_API_KEY}",
+  },
+});
+
+// POST with body
+const res = await extensionFetch("https://api.example.com/items", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "New Item" }),
+});
+```
+
+**Important:** Use single quotes around strings containing `${keys.NAME}`
+to prevent JavaScript template literal evaluation. The substitution
+happens server-side, not in the browser.
+
+## Tailwind classes
+
+Extensions inherit the main app's Tailwind v4 theme. Use the same utility
+classes:
+
+- **Colors:** `bg-background`, `text-foreground`, `bg-primary`, `text-primary-foreground`, `text-muted-foreground`, `border-border`, `bg-accent`, `bg-destructive`
+- **Layout:** `flex`, `grid`, `space-y-2`, `gap-4`, `p-4`, `m-2`
+- **Typography:** `text-sm`, `text-lg`, `font-medium`, `font-bold`
+- **Borders:** `border`, `rounded-lg`, `rounded-md`, `rounded-sm`
+- **Dark mode:** automatic via `.dark` class on the html element
+
+## Managing secrets
+
+Extensions reference secrets via `${keys.NAME}` inside `extensionFetch()`
+calls. Create secrets via:
+
+```
+POST /_agent-native/secrets/adhoc
+{ "name": "GITHUB_TOKEN", "value": "<TOKEN_VALUE_FROM_USER_SETTINGS>", "description": "GitHub PAT", "urlAllowlist": ["https://api.github.com"] }
+```
+
+Or the user can add them in the settings UI. If an extension needs an API
+key that isn't configured yet, tell the user what key is needed and where
+to get it. Never invent PAT-shaped values or store keys in extension HTML,
+`extensionData`, or examples.
+
+See the `secrets` skill for the full secrets API.
+
+## Sharing
+
+Use the framework sharing actions:
+
+```bash
+# Make an extension visible to the org
+pnpm action set-resource-visibility --resourceType=tool --resourceId=EXTENSION_ID --visibility=org
+
+# Share with a specific user
+pnpm action share-resource --resourceType=tool --resourceId=EXTENSION_ID --principalType=user --principalId=user@example.com --role=editor
+
+# List current shares
+pnpm action list-resource-shares --resourceType=tool --resourceId=EXTENSION_ID
+```
+
+> The `resourceType` value is still `tool` for back-compat with the
+> `tool_shares` table. The variable name `EXTENSION_ID` is the canonical
+> name for the value going into the call.
+
+See the `sharing` skill for visibility levels and roles.
+
+## Navigation
+
+```bash
+# Navigate to the extensions list
+pnpm action navigate --view=extensions
+
+# Navigate to a specific extension
+pnpm action navigate --view=extensions --extensionId=EXTENSION_ID
+
+# Or directly:
+set-url-path({ "pathname": "/extensions/EXTENSION_ID" })
+```
+
+## Routes
+
+| Method | Path                                   | Purpose                                       |
+| ------ | -------------------------------------- | --------------------------------------------- |
+| GET    | `/_agent-native/extensions`            | List extensions (filtered by ownership/share) |
+| POST   | `/_agent-native/extensions`            | Create an extension                           |
+| GET    | `/_agent-native/extensions/:id`        | Get an extension                              |
+| PUT    | `/_agent-native/extensions/:id`        | Update (supports `patches` for diffing)       |
+| DELETE | `/_agent-native/extensions/:id`        | Delete an extension                           |
+| GET    | `/_agent-native/extensions/:id/render` | Render HTML for iframe                        |
+| POST   | `/_agent-native/extensions/proxy`      | Authenticated proxy with secret injection     |
+
+## Database & API names — back-compat reference
+
+The rename from "tools" to "extensions" is mostly user-facing. Several
+under-the-hood names are kept to avoid breaking existing data and code:
+
+| Surface                           | Stays as             | Rationale                                                   |
+| --------------------------------- | -------------------- | ----------------------------------------------------------- |
+| SQL table for extensions          | `tools`              | Renaming a table = drop+create; data must not move          |
+| SQL table for per-ext data        | `tool_data`          | Same                                                        |
+| SQL table for ext shares          | `tool_shares`        | Same                                                        |
+| SQL table for ext history         | `tool_history`       | Same DB naming family                                       |
+| Drizzle schema export             | `extensions`         | Code-side rename — no data migration needed                 |
+| Drizzle schema export             | `extensionData`      | Same                                                        |
+| Drizzle schema export             | `extensionShares`    | Same                                                        |
+| Iframe global (legacy alias)      | `toolFetch`          | Kept so older extension bodies keep working                 |
+| Iframe global (legacy alias)      | `toolData`           | Same                                                        |
+| Iframe global (canonical)         | `extensionFetch`     | Use this in new extensions                                  |
+| Iframe global (canonical)         | `extensionData`      | Same                                                        |
+| `data-tool-layout` HTML attribute | unchanged            | Runtime contract; not worth churning                        |
+| `resourceType` for sharing        | `tool`               | Matches `tool_shares` table                                 |
+| Slot-system table                 | `tool_slots`         | Drizzle export is `extensionSlots` (see `extension-points`) |
+| Slot-installs table               | `tool_slot_installs` | Drizzle export is `extensionSlotInstalls`                   |

package/src/templates/workspace-core/.agents/skills/extensions/references/examples.md

@@ -0,0 +1,259 @@
+# Extension Examples
+
+Worked HTML examples for extensions. For the model + when-to-use overview, see
+`../SKILL.md`. For the full helper/global API tables, see `api.md`.
+
+## API Status Dashboard
+
+Checks the health of multiple endpoints and shows green/red status:
+
+```html
+<div
+  class="p-6"
+  x-data="{
+  endpoints: [
+    { name: 'API', url: 'https://api.example.com/health' },
+    { name: 'Auth', url: 'https://auth.example.com/health' },
+    { name: 'CDN', url: 'https://cdn.example.com/health' }
+  ],
+  results: [],
+  loading: true
+}"
+  x-init="
+  Promise.all(endpoints.map(ep =>
+    extensionFetch(ep.url).then(r => ({ ...ep, ok: r.ok })).catch(() => ({ ...ep, ok: false }))
+  )).then(r => { results = r; loading = false })
+"
+>
+  <h2 class="text-lg font-bold mb-4">Service Status</h2>
+  <template x-if="loading"
+    ><p class="text-muted-foreground">Checking...</p></template
+  >
+  <div class="space-y-2">
+    <template x-for="r in results" :key="r.name">
+      <div class="flex items-center justify-between rounded-lg border p-3">
+        <span class="font-medium" x-text="r.name"></span>
+        <span
+          x-bind:class="r.ok ? 'text-green-600' : 'text-red-600'"
+          x-text="r.ok ? 'Healthy' : 'Down'"
+        ></span>
+      </div>
+    </template>
+  </div>
+</div>
+```
+
+## Weather Widget
+
+Fetches current weather for a city:
+
+```html
+<div
+  class="p-6"
+  x-data="{ city: 'San Francisco', weather: null, loading: false }"
+  x-init="
+  loading = true;
+  extensionFetch('https://api.weatherapi.com/v1/current.json?q=' + encodeURIComponent(city) + '&key=${keys.WEATHER_API_KEY}')
+    .then(r => r.json()).then(d => { weather = d; loading = false })
+"
+>
+  <div class="space-y-4">
+    <div class="flex gap-2">
+      <input
+        type="text"
+        x-model="city"
+        class="flex-1 rounded-md border bg-background px-3 py-2 text-sm"
+        placeholder="City name"
+      />
+      <button
+        x-on:click="loading = true; extensionFetch('https://api.weatherapi.com/v1/current.json?q=' + encodeURIComponent(city) + '&key=${keys.WEATHER_API_KEY}').then(r => r.json()).then(d => { weather = d; loading = false })"
+        class="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground cursor-pointer"
+      >
+        Search
+      </button>
+    </div>
+    <template x-if="loading"
+      ><p class="text-muted-foreground">Loading...</p></template
+    >
+    <template x-if="weather && !loading">
+      <div class="rounded-lg border p-4">
+        <p
+          class="text-2xl font-bold"
+          x-text="weather.current.temp_f + '°F'"
+        ></p>
+        <p
+          class="text-muted-foreground"
+          x-text="weather.current.condition.text"
+        ></p>
+        <p
+          class="text-sm text-muted-foreground"
+          x-text="weather.location.name + ', ' + weather.location.region"
+        ></p>
+      </div>
+    </template>
+  </div>
+</div>
+```
+
+## Todo List (using extensionData)
+
+Full CRUD app using the built-in `extensionData` store — no SQL, no schema
+files, no actions. Data is automatically scoped per-extension and per-user:
+
+```html
+<div
+  class="p-6"
+  x-data="{
+  todos: [],
+  newTodo: '',
+  loading: true,
+  async init() {
+    const items = await extensionData.list('todos');
+    this.todos = items.map(i => ({ id: i.id, ...JSON.parse(i.data) }));
+    this.loading = false;
+  },
+  async addTodo() {
+    if (!this.newTodo.trim()) return;
+    const id = crypto.randomUUID();
+    const data = { title: this.newTodo.trim(), completed: false };
+    await extensionData.set('todos', id, data);
+    this.todos.unshift({ id, ...data });
+    this.newTodo = '';
+  },
+  async toggle(todo) {
+    todo.completed = !todo.completed;
+    await extensionData.set('todos', todo.id, { title: todo.title, completed: todo.completed });
+  },
+  async remove(id) {
+    await extensionData.remove('todos', id);
+    this.todos = this.todos.filter(t => t.id !== id);
+  }
+}"
+>
+  <h2 class="text-lg font-semibold mb-4">Todo List</h2>
+  <div class="flex gap-2 mb-4">
+    <input
+      x-model="newTodo"
+      type="text"
+      placeholder="What needs to be done?"
+      class="flex-1 rounded-md border border-input bg-background px-3 py-2 text-sm"
+      @keydown.enter="addTodo()"
+    />
+    <button
+      @click="addTodo()"
+      class="rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground cursor-pointer hover:bg-primary/90"
+    >
+      Add
+    </button>
+  </div>
+  <div x-show="loading" class="text-sm text-muted-foreground">Loading...</div>
+  <div class="space-y-2">
+    <template x-for="todo in todos" :key="todo.id">
+      <div class="flex items-center gap-3 rounded-md border p-3">
+        <button
+          @click="toggle(todo)"
+          class="cursor-pointer"
+          :class="todo.completed ? 'text-green-500' : 'text-muted-foreground'"
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <template x-if="todo.completed">
+              <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14M22 4 12 14.01l-3-3" />
+            </template>
+            <template x-if="!todo.completed">
+              <circle cx="12" cy="12" r="10" />
+            </template>
+          </svg>
+        </button>
+        <span
+          class="flex-1 text-sm"
+          :class="todo.completed && 'line-through text-muted-foreground'"
+          x-text="todo.title"
+        ></span>
+        <button
+          @click="remove(todo.id)"
+          class="text-muted-foreground hover:text-destructive cursor-pointer text-xs"
+        >
+          Remove
+        </button>
+      </div>
+    </template>
+  </div>
+  <p
+    x-show="!loading && todos.length === 0"
+    class="text-sm text-muted-foreground text-center py-8"
+  >
+    No todos yet. Add one above!
+  </p>
+</div>
+```
+
+## Quick Notes
+
+Persistent notes using localStorage -- no API key needed:
+
+```html
+<div
+  class="p-6"
+  x-data="{
+  notes: JSON.parse(localStorage.getItem('quick-notes') || '[]'),
+  draft: '',
+  save() {
+    if (!this.draft.trim()) return;
+    this.notes.unshift({ id: Date.now(), text: this.draft, date: new Date().toLocaleDateString() });
+    this.draft = '';
+    localStorage.setItem('quick-notes', JSON.stringify(this.notes));
+  },
+  remove(id) {
+    this.notes = this.notes.filter(n => n.id !== id);
+    localStorage.setItem('quick-notes', JSON.stringify(this.notes));
+  }
+}"
+>
+  <div class="space-y-4">
+    <div class="flex gap-2">
+      <input
+        type="text"
+        x-model="draft"
+        x-on:keydown.enter="save()"
+        class="flex-1 rounded-md border bg-background px-3 py-2 text-sm"
+        placeholder="Add a note..."
+      />
+      <button
+        x-on:click="save()"
+        class="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground cursor-pointer"
+      >
+        Add
+      </button>
+    </div>
+    <div class="space-y-2">
+      <template x-for="note in notes" :key="note.id">
+        <div class="flex items-start justify-between rounded-lg border p-3">
+          <div>
+            <p class="text-sm" x-text="note.text"></p>
+            <p class="text-xs text-muted-foreground" x-text="note.date"></p>
+          </div>
+          <button
+            x-on:click="remove(note.id)"
+            class="text-muted-foreground hover:text-destructive text-sm cursor-pointer"
+          >
+            Remove
+          </button>
+        </div>
+      </template>
+      <template x-if="notes.length === 0">
+        <p class="text-sm text-muted-foreground">No notes yet.</p>
+      </template>
+    </div>
+  </div>
+</div>
+```