@puredesktop/create-app 1.0.0-beta.1 → 2.1.0

package/template/README.md

@@ -1,30 +1,313 @@
-# {{APP_TITLE}}
-
-Vite + React plugin app for **PureScience Desktop**, scaffolded with `@puredesktop/create-app`.
-
-## Dev in the shell
-
-1. `npm install`
-2. `npm run dev` — serves at `http://localhost:{{APP_PORT}}` (must match `plugin.json`)
-3. In PureScience Desktop: **File → Register App…**
-   - Entrypoint URL: `http://localhost:{{APP_PORT}}`
-   - Permissions: **Network**, **Settings**
-
-## Dev in the browser (optional)
-
-Open the Vite URL directly. The app runs in standalone dev mode without the shell bridge.
-
+# {{APP_TITLE}}
+
+Vite + React plugin app for **PureScience Desktop**, scaffolded with `@puredesktop/create-app`.
+
+## Dev in the shell
+
+1. `npm install`
+2. `npm run dev` — serves at `http://localhost:{{APP_PORT}}` (must match `plugin.json`)
+3. In PureScience Desktop: **File → Register App…**
+   - Entrypoint URL: `http://localhost:{{APP_PORT}}`
+   - Permissions: **Network**, **Settings**, **Agents**
+
+## Dev in the browser (optional)
+
+Open the Vite URL directly. The app runs in standalone dev mode without the shell bridge.
+
 ## Build & deploy
 
 ```bash
+npm run typecheck
 npm run build
+npm run puredesktop:check
 ```
 
 Deploy the `dist/` folder to HTTPS, then register that URL in PureScience Desktop.
 
+Run `npm run puredesktop:check` after every production build. It checks the
+same package facts PureScience Desktop needs before registration:
+
+- `plugin.json` is valid and has the required app identity fields.
+- non-local URL entrypoints include the `network` permission.
+- `dist/` exists.
+- `agents.md` is matched by the `agents` permission.
+- `app.usePureDesktopAiPanel` is `true`.
+- `package.json` has the required scripts and dependencies.
+- declared `app.agents.tools` have names, descriptions, schemas, source
+  handlers, and built output.
+
 ## Project layout
 
 - `src/App.tsx` — bridge + boot gates, always wraps `AppFrame`
 - `src/components/AppShell.tsx` — your UI starts here
 - `src/bridge/platformBridge.ts` — only file that calls `bridge.call`
 - `plugin.json` — catalog metadata and dev entrypoint port
+- `agents.md` — app-scoped assistant prompt used by PureDesktop agent sessions
+
+## PureDesktop app rules
+
+Every generated app must keep these files aligned:
+
+- `plugin.json` `app.slug` must match `src/constants.ts`.
+- `plugin.json` `entrypoint.url` must match the Vite dev port.
+- `plugin.json` `app.usePureDesktopAiPanel` must stay `true` for now. The
+  shell PureDesktop AI panel owns the agent UI.
+- `agents.md` must exist at the package root for app-scoped sessions.
+- `plugin.json` `permissions` must include every bridge capability the app uses:
+  `settings` for app settings, `filesystem` for files/storage/dialog/catalog
+  file opens, `network` for hosted URLs and network/OAuth/vision calls,
+  `assets` for asset library calls, `render` for print/render calls, and
+  `agents` for agent sessions, tools, credentials, context, or screen capture.
+- Keep all direct `bridge.call(...)` usage inside `src/bridge/platformBridge.ts`
+  or a local bridge helper owned by that folder.
+- Keep `AppFrame` around every return path in `src/App.tsx`, including loading
+  and error states.
+
+## Required package.json shape
+
+Keep these scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "puredesktop:check": "node scripts/validate-puredesktop-app.mjs"
+  }
+}
+```
+
+Keep these runtime dependencies:
+
+- `@puredesktop/puredesktop-ui-bridge`
+- `react`
+- `react-dom`
+- `styled-components`
+
+Keep these dev dependencies:
+
+- `@vitejs/plugin-react-swc`
+- `typescript`
+- `vite`
+
+## Required plugin.json shape
+
+Keep this structure and update values rather than inventing new fields:
+
+```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 PureScience Desktop.",
+    "usePureDesktopAiPanel": true
+  }
+}
+```
+
+When the app exposes tools to its app agent, add tool schemas under
+`app.agents.tools` and keep the top-level `agents` permission:
+
+```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
+        }
+      ]
+    }
+  }
+}
+```
+
+## Required app agent
+
+Every app has an app agent:
+
+1. Keep `agents` in top-level `plugin.json` permissions.
+2. Keep root-level `agents.md` next to `plugin.json`.
+3. Keep `app.usePureDesktopAiPanel` set to `true`.
+4. Run `npm run typecheck`, `npm run build`, and `npm run puredesktop:check`.
+
+Add tool handlers when the manifest declares `app.agents.tools`.
+
+Create a stable tool-name catalog:
+
+```ts
+// src/agents/catalog.ts
+export const APP_AGENT_TOOL_NAMES = ['listItems'] as const
+```
+
+Register matching runtime handlers after the bridge is ready:
+
+```tsx
+import { usePlatformAgentTools } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
+import {
+  agentToolErrorContent,
+  formatAgentToolJson,
+  readAgentToolStringArg,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/agentToolHelpers'
+import { APP_AGENT_TOOL_NAMES } from './agents/catalog'
+
+function AppAgentTools({ ready }: { ready: boolean }) {
+  usePlatformAgentTools({
+    ready,
+    tools: APP_AGENT_TOOL_NAMES,
+    handlers: {
+      async listItems(ctx) {
+        const status = readAgentToolStringArg(ctx.arguments, 'status')
+        try {
+          return {
+            content: formatAgentToolJson({
+              items: [],
+              status: status || null,
+            }),
+          }
+        } catch (error) {
+          return agentToolErrorContent(
+            error instanceof Error ? error.message : String(error),
+          )
+        }
+      },
+    },
+  })
+
+  return null
+}
+```
+
+Manifest tool names and handler names must match exactly. Read tools should
+return compact JSON with stable ids. Write tools should validate exact targets,
+reject ambiguous edits, and return a concise JSON result. Destructive or
+external-effect tools should use `requiresApproval: true`.
+
+## Design baseline
+
+Build quiet, dense, legible work software. Make the main work object visible
+quickly and directly actionable. Use platform components and `--platform-*`
+CSS variables before adding local styling. Keep one source of truth for each
+object and avoid persistent chrome that competes with the work.
+
+## Platform CSS variables
+
+Theme variables are injected by PureDesktop and follow
+`--platform-<domain>-<token>`. Use these before adding app-local variables:
+
+```text
+--platform-mode
+
+--platform-colors-bg
+--platform-colors-surface
+--platform-colors-surface-hover
+--platform-colors-surface-active
+--platform-colors-elevated
+--platform-colors-text
+--platform-colors-text-secondary
+--platform-colors-text-disabled
+--platform-colors-text-inverse
+--platform-colors-accent
+--platform-colors-accent-hover
+--platform-colors-accent-muted
+--platform-colors-border
+--platform-colors-border-strong
+--platform-colors-divider
+--platform-colors-danger
+--platform-colors-text-danger
+--platform-colors-warning
+--platform-colors-success
+--platform-colors-info
+--platform-colors-semantic-blue
+--platform-colors-semantic-blue-text
+--platform-colors-semantic-blue-muted
+--platform-colors-semantic-blue-border
+--platform-colors-semantic-orange
+--platform-colors-semantic-orange-text
+--platform-colors-semantic-orange-muted
+--platform-colors-semantic-orange-border
+--platform-colors-semantic-green
+--platform-colors-semantic-green-text
+--platform-colors-semantic-green-muted
+--platform-colors-semantic-green-border
+--platform-colors-semantic-red
+--platform-colors-semantic-red-text
+--platform-colors-semantic-red-muted
+--platform-colors-semantic-red-border
+--platform-colors-focus
+--platform-colors-selection
+--platform-colors-app-viewport
+--platform-colors-chrome-titlebar
+--platform-colors-chrome-tab-strip
+
+--platform-typography-font-family
+--platform-typography-font-family-content
+--platform-typography-font-family-mono
+--platform-typography-font-size-base
+--platform-typography-font-size-xs
+--platform-typography-font-size-sm
+--platform-typography-font-size-lg
+--platform-typography-font-size-xl
+--platform-typography-line-height-base
+--platform-typography-line-height-tight
+--platform-typography-font-weight-normal
+--platform-typography-font-weight-medium
+--platform-typography-font-weight-bold
+
+--platform-spacing-xs
+--platform-spacing-sm
+--platform-spacing-md
+--platform-spacing-lg
+--platform-spacing-xl
+--platform-spacing-xxl
+
+--platform-radius-sm
+--platform-radius-md
+--platform-radius-lg
+--platform-radius-full
+
+--platform-shadow-sm
+--platform-shadow-md
+--platform-shadow-lg
+
+--platform-transition-fast
+--platform-transition-base
+--platform-transition-slow
+
+--platform-z-index-zi-app-base
+--platform-z-index-zi-app-sidebar
+--platform-z-index-zi-app-chrome
+--platform-z-index-zi-app-viewport-toolbar
+--platform-z-index-zi-app-menus
+--platform-z-index-zi-app-toast
+--platform-z-index-zi-app-modal
+```
+
+Use the plural `--platform-colors-*` prefix for colors. Do not create
+`--platform-color-*` variables. App-specific variables should use an app prefix,
+for example `--my-app-accent`.

package/template/agents.md

@@ -0,0 +1,11 @@
+# {{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.
+
+When tools are available, use read-only tools before write tools. Ask for
+confirmation before destructive or external-effect changes unless the tool
+policy already requires approval.

package/template/gitignore.tpl

@@ -1,5 +1,5 @@
-.gitignore
-node_modules
-dist
-.env
-.npmrc
+.gitignore
+node_modules
+dist
+.env
+.npmrc

package/template/index.html

@@ -1,12 +1,12 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>{{APP_TITLE}}</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_TITLE}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -1,25 +1,26 @@
-{
-  "name": "{{PACKAGE_NAME}}",
-  "private": true,
-  "version": "0.1.0",
-  "type": "module",
+{
+  "name": "{{PACKAGE_NAME}}",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "puredesktop:check": "node scripts/validate-puredesktop-app.mjs"
   },
-  "dependencies": {
-    "{{UI_PACKAGE_NAME}}": "{{UI_PACKAGE_VERSION}}",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
-    "styled-components": "^6.1.18"
-  },
-  "devDependencies": {
-    "@swc/plugin-styled-components": "^12.9.0",
-    "@types/react": "^19.1.6",
-    "@types/react-dom": "^19.1.5",
-    "@vitejs/plugin-react-swc": "^3.10.2",
-    "typescript": "^5.8.3",
-    "vite": "^6.3.5"
-  }
-}
+  "dependencies": {
+    "{{UI_PACKAGE_NAME}}": "{{UI_PACKAGE_VERSION}}",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "styled-components": "^6.1.18"
+  },
+  "devDependencies": {
+    "@swc/plugin-styled-components": "^12.9.0",
+    "@types/react": "^19.1.6",
+    "@types/react-dom": "^19.1.5",
+    "@vitejs/plugin-react-swc": "^3.10.2",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5"
+  }
+}

package/template/plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "id": "{{PLUGIN_ID}}",
   "name": "{{APP_TITLE}}",
-  "permissions": ["network", "settings"],
+  "permissions": ["network", "settings", "agents"],
   "entrypoint": {
     "kind": "dev-url",
     "url": "http://localhost:{{APP_PORT}}"
@@ -14,6 +14,7 @@
     "navigationLabel": "{{APP_TITLE}}",
     "productName": "pure.{{APP_SLUG}}",
     "kind": "{{APP_SLUG}}",
-    "description": "{{APP_TITLE}} — built with PureScience Desktop."
+    "description": "{{APP_TITLE}} - built with PureScience Desktop.",
+    "usePureDesktopAiPanel": true
   }
 }