@puredesktop/create-app 2.1.0 → 2.1.2

package/template/docs/agent.md

@@ -0,0 +1,58 @@
+# App Agent
+
+Every generated app has an app-scoped assistant that runs in the shell agent
+drawer. The app does not render its own agent chat UI by default.
+
+## Source Files
+
+- `agents.md`: app-scoped assistant prompt.
+- `plugin.json` `app.agents.tools`: tool schemas exposed to the agent.
+- `src/agents/*`: generated app-owned tool catalog and handlers when tools
+  exist.
+- `src/hooks/useAppAgentTools.ts`: generated runtime registration hook when
+  tools exist.
+
+## How The Agent Uses App Tools
+
+1. The shell reads `plugin.json` and includes declared app tools in the app
+   agent's available tools.
+2. The app iframe loads and registers runtime handlers with
+   `usePlatformAgentTools`.
+3. The agent calls a declared tool during a shell-managed session.
+4. The shell routes the invocation to the app iframe.
+5. The app handler returns compact text or JSON.
+6. The bridge helper completes the tool call back to the shell.
+7. The shell resumes the agent session.
+
+The app owns the handler implementation. The shell owns session state,
+approvals, routing, and completion.
+
+When `plugin.json` contains `app.agents.tools`, the create-app generator writes
+the initial catalog, handler map, and registration hook. The generated handlers
+return explicit not-implemented tool errors until the app replaces them with real
+domain behavior.
+
+## agents.md
+
+Keep `agents.md` grounded in the app's real UI and data. Mention the app's work
+objects, read-first workflow, write safety rules, and expected concise output.
+
+Example:
+
+```md
+# {{APP_TITLE}} Agent
+
+You are the app-scoped assistant for {{APP_TITLE}}.
+
+Help the user understand, review, and act on the work inside this app. Stay
+grounded in the app UI and data. Prefer concise answers, concrete next actions,
+and safe tool use.
+```
+
+## Approval Policy
+
+Set `requiresApproval` on each manifest tool. Read-only inspection tools usually
+set `false`. Destructive, external-effect, or broad write tools set `true`.
+
+The shell drawer displays approvals and resumes the same session after the user
+approves or rejects.

package/template/docs/app-lifecycle.md

@@ -0,0 +1,60 @@
+# App Lifecycle
+
+A PureDesktop app is loaded into an iframe by the shell. The shell discovers the
+app from `plugin.json`, opens a workspace tab, loads the entrypoint URL or built
+static bundle, then establishes the bridge handshake with the iframe.
+
+## Registration To Render
+
+1. The shell scans installed app folders for `plugin.json`.
+2. The catalog creates one app entry from `plugin.json` `app.slug`.
+3. Opening the app creates a workspace tab.
+4. The tab renders the app entrypoint in an iframe.
+5. The iframe starts React from `src/main.tsx`.
+6. `src/App.tsx` calls `usePlatformBridge()`.
+7. The bridge client sends a handshake to the shell parent window.
+8. The shell replies with `ready` metadata, including `pluginId`, `appSlug`,
+   allowed method names, theme CSS, and optional viewport resource.
+9. The app boot hook loads app settings and other startup data.
+10. The app renders inside `AppFrame`.
+
+## App.tsx Contract
+
+`src/App.tsx` is the orchestration boundary. Keep it thin:
+
+- call `usePlatformBridge()`;
+- allow standalone browser dev mode when needed;
+- call the app boot hook after the bridge is ready;
+- render loading and error states inside `AppFrame`;
+- render the app shell inside `AppFrame` after boot succeeds.
+
+The template already follows this shape.
+
+## Viewport Resources
+
+When the shell opens a file or app resource into a tab, the bridge ready metadata
+can include:
+
+```ts
+{
+  viewport: {
+    tabId: string
+    resource: { path: string; name: string; kind: string } | null
+  }
+}
+```
+
+File-centric apps use `usePlatformViewportResource(ready, meta)` from the bridge
+React helpers. This handles cold opens and warm `resource.open` events without
+duplicating event wiring in screens.
+
+## Standalone Dev
+
+The template supports browser-only development with:
+
+```ts
+window.parent === window
+```
+
+Standalone mode is for UI iteration. Production app behavior runs inside the
+shell iframe and uses shell bridge permissions.

package/template/docs/bridge/README.md

@@ -0,0 +1,84 @@
+# Platform Bridge Helpers
+
+The bridge is the app iframe's RPC channel to the PureDesktop shell.
+
+The generated app runs in an iframe. It cannot call shell internals directly.
+Instead, app code imports helpers from `src/bridge/platformBridge.ts`. That
+local bridge module wraps the package bridge client from
+`@puredesktop/puredesktop-ui-bridge`.
+
+## Runtime Boundary
+
+```text
+App iframe -> bridge helper -> postMessage -> shell renderer -> shell handler
+```
+
+The shell validates the app origin, method name, and `plugin.json` permissions
+before running a handler.
+
+## Ready Handshake
+
+`src/App.tsx` uses `usePlatformBridge()` to wait for the shell:
+
+```ts
+const { ready, error, meta } = usePlatformBridge()
+```
+
+The shell ready payload includes:
+
+- `pluginId`: plugin package identity.
+- `appSlug`: app API scope.
+- `methods`: bridge methods available in this shell.
+- `theme`: injected theme CSS.
+- `viewport`: optional tab resource opened into the app.
+
+Call bridge helpers after `ready` is true. The template boot hook follows that
+pattern.
+
+## Local Bridge Module
+
+`src/bridge/platformBridge.ts` is the app's bridge boundary. Components and
+feature code import from that local file:
+
+```ts
+import { fetchAppSettings, networkFetch } from '../bridge/platformBridge'
+```
+
+Keep request-shape knowledge in this bridge folder. Component code calls
+domain-named helpers.
+
+`platformBridge.ts` is both the exported app bridge surface and the place for
+app-owned bridge wrappers. Package bridge helpers are imported as local bindings
+first, then re-exported for app code. App-specific wrappers in this file should
+call those local bindings.
+
+## Helper Domains
+
+- [Dialog](./dialog.md)
+- [Filesystem](./fs.md)
+- [Network](./network.md)
+- [Settings](./settings.md)
+- [Storage](./storage.md)
+
+## Permissions
+
+Bridge calls are gated by top-level `plugin.json` `permissions`.
+
+| Permission | Helper domains |
+| --- | --- |
+| `settings` | settings and preferences |
+| `filesystem` | filesystem, dialogs, storage, file routing |
+| `network` | network requests and OAuth-style flows |
+| `render` | print and render helpers |
+| `assets` | asset library helpers |
+| `agents` | agent sessions, agent tools, credentials |
+
+## Events
+
+The bridge also delivers shell events into the iframe. Common app events include
+theme changes, viewport resource opens, render progress, filesystem watch
+changes, agent run events, and app tool invocations.
+
+Use the package React hooks when they exist. For example,
+`usePlatformViewportResource(ready, meta)` handles file opens without manual
+event wiring.

package/template/docs/bridge/dialog.md

@@ -0,0 +1,56 @@
+# Dialog
+
+Permission: `filesystem`
+
+Dialog helpers open shell-native file and folder pickers.
+
+Import from the generated app bridge:
+
+```ts
+import {
+  openPlatformFileDialog,
+  openPlatformFolderDialog,
+  openPlatformImageDialog,
+  savePlatformFolderDialog,
+} from '../../src/bridge/platformBridge'
+```
+
+## openPlatformFolderDialog
+
+Opens a folder picker.
+
+```ts
+const folderPath = await openPlatformFolderDialog()
+```
+
+Returns the selected absolute folder path, or `null` when cancelled.
+
+## savePlatformFolderDialog
+
+Opens a folder picker configured for choosing a parent directory.
+
+```ts
+const parentPath = await savePlatformFolderDialog()
+```
+
+Returns the selected absolute folder path, or `null` when cancelled.
+
+## openPlatformImageDialog
+
+Opens an image file picker.
+
+```ts
+const imagePath = await openPlatformImageDialog()
+```
+
+Returns the selected absolute image path, or `null` when cancelled.
+
+## openPlatformFileDialog
+
+Opens a text/document file picker.
+
+```ts
+const filePath = await openPlatformFileDialog()
+```
+
+Returns the selected absolute file path, or `null` when cancelled.

package/template/docs/bridge/fs.md

@@ -0,0 +1,95 @@
+# Filesystem
+
+Permission: `filesystem`
+
+Filesystem helpers read, write, list, rename, delete, and preview files through
+the shell.
+
+Import from the generated app bridge:
+
+```ts
+import {
+  createPlatformFolder,
+  deletePlatformFile,
+  listPlatformFiles,
+  readPlatformTextFile,
+  renamePlatformFile,
+  writePlatformTextFile,
+} from '../../src/bridge/platformBridge'
+```
+
+## listPlatformFiles
+
+Lists a folder.
+
+```ts
+const listing = await listPlatformFiles('/absolute/folder')
+```
+
+Returns:
+
+- `rootPath`: listed folder path.
+- `parentPath`: parent folder path or `null`.
+- `entries`: file and folder entries with `path`, `name`, `kind`, size,
+  modified time, MIME type, extension, and directory flag.
+
+## readPlatformTextFile
+
+Reads a text file.
+
+```ts
+const content = await readPlatformTextFile('/absolute/file.md')
+```
+
+Returns the file contents as a string.
+
+## writePlatformTextFile
+
+Writes a text file.
+
+```ts
+await writePlatformTextFile('/absolute/file.md', '# Notes\n')
+```
+
+Returns `{ ok: true }`.
+
+## createPlatformFolder
+
+Creates a folder under a parent directory.
+
+```ts
+const folder = await createPlatformFolder('/absolute/parent', 'Project')
+```
+
+Returns `{ path }` for the created folder.
+
+## renamePlatformFile
+
+Renames a file or folder within its current parent directory.
+
+```ts
+const renamed = await renamePlatformFile('/absolute/file.md', 'renamed.md')
+```
+
+Returns `{ path }` for the renamed path.
+
+## deletePlatformFile
+
+Deletes a file or folder.
+
+```ts
+await deletePlatformFile('/absolute/file.md')
+await deletePlatformFile('/absolute/folder', true)
+```
+
+Pass `true` for recursive folder deletion. Returns `{ ok: true }`.
+
+## Preview And Binary Helpers
+
+The same domain also exports:
+
+- `readPlatformFilePreview(path, maxBytes?)`
+- `readPlatformFilePreviewUrl(path)`
+- `readPlatformFileBinary(path, maxBytes?)`
+- `readPlatformFileBinaryDataUrl(path, maxBytes?)`
+- `writePlatformFileBinary(path, base64)`

package/template/docs/bridge/network.md

@@ -0,0 +1,38 @@
+# Network
+
+Permission: `network`
+
+Use `networkFetch` for HTTP(S) requests through the shell.
+
+Import from the generated app bridge:
+
+```ts
+import { networkFetch } from '../../src/bridge/platformBridge'
+```
+
+Example:
+
+```ts
+const response = await networkFetch({
+  url: 'https://example.com/api/items',
+  method: 'GET',
+})
+
+if (!response.ok) {
+  throw new Error(`Request failed with ${response.status}`)
+}
+```
+
+Request fields:
+
+- `url`: HTTP or HTTPS URL.
+- `method`: optional, defaults to `GET`.
+- `headers`: optional string map.
+- `body`: optional string.
+
+Response fields:
+
+- `status`: HTTP status code.
+- `ok`: `true` for 2xx responses.
+- `headers`: response headers as a string map.
+- `body`: response body as text.

package/template/docs/bridge/settings.md

@@ -0,0 +1,63 @@
+# Settings
+
+Permission: `settings`
+
+Settings helpers read and update user preferences through the shell. App
+settings are stored inside user preferences under the current app's slug.
+
+Import from the generated app bridge:
+
+```ts
+import {
+  getPlatformAppSettings,
+  getPlatformPreferences,
+  patchPlatformPreferences,
+  updatePlatformAppSettings,
+} from '../../src/bridge/platformBridge'
+```
+
+## getPlatformAppSettings
+
+Reads settings for the current app slug.
+
+```ts
+const settings = await getPlatformAppSettings(APP_SLUG)
+```
+
+The shell allows plugin frames to access only their own app settings.
+
+## updatePlatformAppSettings
+
+Patches settings for the current app slug.
+
+```ts
+const next = await updatePlatformAppSettings({
+  appSlug: APP_SLUG,
+  patch: { workspacePath: '/absolute/folder' },
+})
+```
+
+Returns the merged app settings object.
+
+## getPlatformPreferences
+
+Reads shell user preferences.
+
+```ts
+const prefs = await getPlatformPreferences()
+```
+
+Common fields include the working directory, theme, app settings, user profile,
+and agent defaults.
+
+## patchPlatformPreferences
+
+Patches shell user preferences.
+
+```ts
+const next = await patchPlatformPreferences({
+  theme: 'dark',
+})
+```
+
+Returns the merged user preferences object.

package/template/docs/bridge/storage.md

@@ -0,0 +1,48 @@
+# Storage
+
+Permission: `filesystem`
+
+Storage helpers read and write JSON files in the shell-managed PureDesktop data
+folder. These helpers use the same bridge path as the exposed
+`storage.readJson` and `storage.writeJson` methods.
+
+Import from the generated app bridge:
+
+```ts
+import {
+  readPlatformStorageJson,
+  writePlatformStorageJson,
+} from '../../src/bridge/platformBridge'
+```
+
+## readPlatformStorageJson
+
+Reads an app JSON store file.
+
+```ts
+const result = await readPlatformStorageJson({
+  appSlug: APP_SLUG,
+  fileName: 'items.json',
+})
+```
+
+Returns:
+
+- `path`: resolved storage path.
+- `value`: parsed JSON value, or `null` when the file is absent.
+
+## writePlatformStorageJson
+
+Writes an app JSON store file.
+
+```ts
+await writePlatformStorageJson({
+  appSlug: APP_SLUG,
+  fileName: 'items.json',
+  value: { items: [] },
+})
+```
+
+Returns `{ path, ok: true }`.
+
+Storage file names must be file names ending with `.json`.

package/template/docs/plugin-manifest.md

@@ -0,0 +1,108 @@
+# Plugin Manifest
+
+`plugin.json` is the shell contract for discovery, permissions, routing, and app
+agent tools.
+
+## Required Shape
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "{{PLUGIN_ID}}",
+  "name": "{{APP_TITLE}}",
+  "permissions": ["network", "settings", "agents"],
+  "entrypoint": {
+    "kind": "dev-url",
+    "url": "http://localhost:{{APP_PORT}}"
+  },
+  "app": {
+    "id": "plugin.{{APP_SLUG}}",
+    "slug": "{{APP_SLUG}}",
+    "name": "{{APP_TITLE}}",
+    "navigationLabel": "{{APP_TITLE}}",
+    "productName": "pure.{{APP_SLUG}}",
+    "kind": "{{APP_SLUG}}",
+    "description": "{{APP_TITLE}} - built with PureDesktop.",
+    "usePureDesktopAiPanel": true
+  }
+}
+```
+
+`app.slug` is the API scope for settings, storage, app agent sessions, and tab
+routing. `src/constants.ts` `APP_SLUG` must match `plugin.json` `app.slug`.
+
+## Entrypoint
+
+Development apps use:
+
+```json
+{
+  "entrypoint": {
+    "kind": "dev-url",
+    "url": "http://localhost:{{APP_PORT}}"
+  }
+}
+```
+
+Built apps use a static bundle registered from `dist/`. The validator checks the
+build output before registration.
+
+## Permissions
+
+Declare every shell capability used by bridge helpers:
+
+| Permission | Enables |
+| --- | --- |
+| `settings` | `settings.*`, app settings, user preferences |
+| `filesystem` | `fs.*`, `dialog.*`, `storage.*`, file open routing |
+| `network` | `network.fetch`, hosted entrypoints, OAuth helpers |
+| `render` | document render and print helpers |
+| `assets` | asset library helpers |
+| `agents` | app agent sessions and runtime tool handlers |
+
+## App Agent Tools
+
+Declare app-owned tools under `app.agents.tools`:
+
+```json
+{
+  "app": {
+    "agents": {
+      "tools": [
+        {
+          "name": "listItems",
+          "description": "List the current items with ids, titles, status, and next action.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "description": "Optional status filter."
+              }
+            },
+            "additionalProperties": false
+          },
+          "requiresApproval": false
+        }
+      ]
+    }
+  }
+}
+```
+
+The manifest declaration exposes the tool to the shell agent. Runtime handler
+registration in the iframe executes the tool.
+
+## Validation
+
+Run:
+
+```bash
+npm run typecheck
+npm run build
+npm run puredesktop:check
+```
+
+The validator checks manifest identity, required scripts and dependencies,
+`agents.md`, `app.usePureDesktopAiPanel`, permissions, built output, and declared
+agent tool presence in source and dist.