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

package/bin/create-puredesktop-app.mjs

@@ -1,164 +1,169 @@
 #!/usr/bin/env node
-/**
- * Scaffold an external PureScience Desktop plugin app.
- *
- * Published as @puredesktop/create-app → npm create @puredesktop/app@latest
- */
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-const TEMPLATE_DIR = join(__dirname, '..', 'template')
-const DEFAULT_UI = '@puredesktop/puredesktop-ui-bridge'
-const DEFAULT_UI_VERSION = '1.0.0-beta.1'
-
-function usage() {
-  console.log(`Usage: npm create @puredesktop/app@latest [dir] [options]
-
-Options:
-  --name <title>     Display name (default: derived from dir)
-  --slug <slug>      App slug for settings/bridge (default: dir name)
-  --port <number>    Dev server port in plugin.json (default: 5300)
-  --ui <spec>        UI package spec (default: ${DEFAULT_UI}@${DEFAULT_UI_VERSION})
-
-Examples:
-  npm create @puredesktop/app@latest my-tool
-  npm create @puredesktop/app@latest my-tool -- --name "My Tool" --slug mytool --port 5310
-`)
-}
-
-function uiDependencySpec(spec) {
-  if (spec.startsWith('file:')) {
-    return {
-      name: '@puredesktop/puredesktop-ui-bridge',
-      version: spec,
-    }
-  }
-  const at = spec.lastIndexOf('@')
-  if (at > 1) {
-    return { name: spec.slice(0, at), version: spec.slice(at + 1) }
-  }
-  return { name: spec, version: DEFAULT_UI_VERSION }
-}
-
-function parseArgs(argv) {
-  const positional = []
-  const options = {
-    name: '',
-    slug: '',
-    port: 5300,
-    ui: `${DEFAULT_UI}@${DEFAULT_UI_VERSION}`,
-  }
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i]
-    if (arg === '--help' || arg === '-h') {
-      usage()
-      process.exit(0)
-    }
-    if (arg === '--name') {
-      options.name = argv[++i] ?? ''
-      continue
-    }
-    if (arg === '--slug') {
-      options.slug = argv[++i] ?? ''
-      continue
-    }
-    if (arg === '--port') {
-      options.port = Number(argv[++i])
-      continue
-    }
-    if (arg === '--ui') {
-      options.ui = argv[++i] ?? options.ui
-      continue
-    }
-    if (arg.startsWith('-')) {
-      console.error(`Unknown option: ${arg}`)
-      usage()
-      process.exit(1)
-    }
-    positional.push(arg)
-  }
-
-  if (!Number.isInteger(options.port) || options.port <= 0) {
-    console.error('--port must be a positive integer')
-    process.exit(1)
-  }
-
-  return { targetDir: positional[0] ?? 'puredesktop-app', options }
-}
-
-function slugify(value) {
-  return value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-}
-
-function titleCaseFromSlug(slug) {
-  return slug
-    .split('-')
-    .filter(Boolean)
-    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-    .join(' ')
-}
-
-function copyTemplate(srcDir, destDir, vars) {
-  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
-    const srcPath = join(srcDir, entry.name)
-    const destName = entry.name.replace(/\.tpl$/u, '')
-    const destPath = join(destDir, destName)
-    if (entry.isDirectory()) {
-      mkdirSync(destPath, { recursive: true })
-      copyTemplate(srcPath, destPath, vars)
-      continue
-    }
-    const raw = readFileSync(srcPath, 'utf8')
-    const rendered = raw.replace(/\{\{(\w+)\}\}/g, (_match, key) => vars[key] ?? '')
-    writeFileSync(destPath, rendered)
-  }
-}
-
-const { targetDir, options } = parseArgs(process.argv.slice(2))
-const uiDep = uiDependencySpec(options.ui)
-const dirName = targetDir
-const slug = options.slug || slugify(dirName) || 'my-app'
-const title = options.name || titleCaseFromSlug(slug) || 'My App'
-const pluginId = slug
-const outDir = resolve(process.cwd(), dirName)
-
-if (existsSync(outDir)) {
-  console.error(`Target already exists: ${outDir}`)
-  process.exit(1)
-}
-
-mkdirSync(outDir, { recursive: true })
-
-const vars = {
-  APP_TITLE: title,
-  APP_SLUG: slug,
-  APP_NAME: slug,
-  PLUGIN_ID: pluginId,
-  APP_PORT: String(options.port),
-  UI_PACKAGE_NAME: uiDep.name,
-  UI_PACKAGE_VERSION: uiDep.version,
-  PACKAGE_NAME: `@puredesktop/${slug}`,
-}
-
-copyTemplate(TEMPLATE_DIR, outDir, vars)
-
-console.log(`
-Created ${title} at ${outDir}
-
+/**
+ * Scaffold an external PureScience Desktop plugin app.
+ *
+ * Published as @puredesktop/create-app → npm create @puredesktop/app@latest
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const TEMPLATE_DIR = join(__dirname, '..', 'template')
+const DEFAULT_UI = '@puredesktop/puredesktop-ui-bridge'
+const DEFAULT_UI_VERSION = '1.0.0-beta.2'
+
+function usage() {
+  console.log(`Usage: npm create @puredesktop/app@latest [dir] [options]
+
+Options:
+  --name <title>     Display name (default: derived from dir)
+  --slug <slug>      App slug for settings/bridge (default: dir name)
+  --port <number>    Dev server port in plugin.json (default: 5300)
+  --ui <spec>        UI package spec (default: ${DEFAULT_UI}@${DEFAULT_UI_VERSION})
+
+Examples:
+  npm create @puredesktop/app@latest my-tool
+  npm create @puredesktop/app@latest my-tool -- --name "My Tool" --slug mytool --port 5310
+`)
+}
+
+function uiDependencySpec(spec) {
+  if (spec.startsWith('file:')) {
+    return {
+      name: '@puredesktop/puredesktop-ui-bridge',
+      version: spec,
+    }
+  }
+  const at = spec.lastIndexOf('@')
+  if (at > 1) {
+    return { name: spec.slice(0, at), version: spec.slice(at + 1) }
+  }
+  return { name: spec, version: DEFAULT_UI_VERSION }
+}
+
+function parseArgs(argv) {
+  const positional = []
+  const options = {
+    name: '',
+    slug: '',
+    port: 5300,
+    ui: `${DEFAULT_UI}@${DEFAULT_UI_VERSION}`,
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--help' || arg === '-h') {
+      usage()
+      process.exit(0)
+    }
+    if (arg === '--name') {
+      options.name = argv[++i] ?? ''
+      continue
+    }
+    if (arg === '--slug') {
+      options.slug = argv[++i] ?? ''
+      continue
+    }
+    if (arg === '--port') {
+      options.port = Number(argv[++i])
+      continue
+    }
+    if (arg === '--ui') {
+      options.ui = argv[++i] ?? options.ui
+      continue
+    }
+    if (arg.startsWith('-')) {
+      console.error(`Unknown option: ${arg}`)
+      usage()
+      process.exit(1)
+    }
+    positional.push(arg)
+  }
+
+  if (!Number.isInteger(options.port) || options.port <= 0) {
+    console.error('--port must be a positive integer')
+    process.exit(1)
+  }
+
+  return { targetDir: positional[0] ?? 'puredesktop-app', options }
+}
+
+function slugify(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function titleCaseFromSlug(slug) {
+  return slug
+    .split('-')
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+function copyTemplate(srcDir, destDir, vars) {
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = join(srcDir, entry.name)
+    const destName = entry.name.replace(/\.tpl$/u, '')
+    const destPath = join(destDir, destName)
+    if (entry.isDirectory()) {
+      mkdirSync(destPath, { recursive: true })
+      copyTemplate(srcPath, destPath, vars)
+      continue
+    }
+    const raw = readFileSync(srcPath, 'utf8')
+    const rendered = raw.replace(/\{\{(\w+)\}\}/g, (_match, key) => vars[key] ?? '')
+    writeFileSync(destPath, rendered)
+  }
+}
+
+const { targetDir, options } = parseArgs(process.argv.slice(2))
+const uiDep = uiDependencySpec(options.ui)
+const dirName = targetDir
+const slug = options.slug || slugify(dirName) || 'my-app'
+const title = options.name || titleCaseFromSlug(slug) || 'My App'
+const pluginId = slug
+const outDir = resolve(process.cwd(), dirName)
+
+if (existsSync(outDir)) {
+  console.error(`Target already exists: ${outDir}`)
+  process.exit(1)
+}
+
+mkdirSync(outDir, { recursive: true })
+
+const vars = {
+  APP_TITLE: title,
+  APP_SLUG: slug,
+  APP_NAME: slug,
+  PLUGIN_ID: pluginId,
+  APP_PORT: String(options.port),
+  UI_PACKAGE_NAME: uiDep.name,
+  UI_PACKAGE_VERSION: uiDep.version,
+  PACKAGE_NAME: `@puredesktop/${slug}`,
+}
+
+copyTemplate(TEMPLATE_DIR, outDir, vars)
+
+console.log(`
+Created ${title} at ${outDir}
+
   cd ${dirName}
   npm install
   npm run dev
 
-Register in PureScience Desktop (File → Register App…) with:
-  entrypoint: http://localhost:${options.port}
-  permissions: network (+ settings if you use app settings)
-
-Build your UI in src/components/AppShell.tsx.
-`)
+Before shipping:
+  npm run typecheck
+  npm run build
+  npm run puredesktop:check
+
+Register in PureScience Desktop (File → Register App…) with:
+  entrypoint: http://localhost:${options.port}
+  permissions: network, settings, agents
+
+Build your UI in src/components/AppShell.tsx.
+`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puredesktop/create-app",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Scaffold a PureScience Desktop plugin app (Vite + bridge SDK)",
   "type": "module",
   "bin": {

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