@puredesktop/create-app 2.1.0 → 2.1.1

package/bin/create-puredesktop-app.mjs

@@ -1,26 +1,23 @@
 #!/usr/bin/env node
 /**
- * Scaffold an external PureScience Desktop plugin app.
+ * Scaffold an external PureDesktop plugin app.
  *
- * Published as @puredesktop/create-app → npm create @puredesktop/app@latest
+ * Published as @puredesktop/create-app -> npm create @puredesktop/app@latest
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { 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 = '2.1.0'
-
-function usage() {
-  console.log(`Usage: npm create @puredesktop/app@latest [dir] [options]
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const TEMPLATE_DIR = join(__dirname, '..', 'template')
+
+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})
   --manifest-json-base64 <base64>
                      Structured plugin.json manifest draft for app-builder use
   --agents-md-base64 <base64>
@@ -29,30 +26,15 @@ Options:
 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 = {
+`)
+}
+
+function parseArgs(argv) {
+  const positional = []
+  const options = {
     name: '',
     slug: '',
     port: 5300,
-    ui: `${DEFAULT_UI}@${DEFAULT_UI_VERSION}`,
     manifestJsonBase64: '',
     agentsMdBase64: '',
   }
@@ -71,12 +53,8 @@ function parseArgs(argv) {
       options.slug = argv[++i] ?? ''
       continue
     }
-    if (arg === '--port') {
-      options.port = Number(argv[++i])
-      continue
-    }
-    if (arg === '--ui') {
-      options.ui = argv[++i] ?? options.ui
+    if (arg === '--port') {
+      options.port = Number(argv[++i])
       continue
     }
     if (arg === '--manifest-json-base64') {
@@ -223,6 +201,110 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error)
 }
 
+function readGeneratedManifest(outDir) {
+  try {
+    return JSON.parse(readFileSync(join(outDir, 'plugin.json'), 'utf8'))
+  } catch (error) {
+    console.error(`Generated plugin.json could not be read: ${errorMessage(error)}`)
+    process.exit(1)
+  }
+}
+
+function readAgentToolNames(manifest) {
+  const tools = manifest?.app?.agents?.tools
+  if (!Array.isArray(tools)) return []
+  return tools
+    .map(tool => (typeof tool?.name === 'string' ? tool.name.trim() : ''))
+    .filter(Boolean)
+}
+
+function jsonString(value) {
+  return JSON.stringify(value)
+}
+
+function writeAgentToolScaffold(outDir, appSlug, toolNames) {
+  if (toolNames.length === 0) return
+
+  const agentsDir = join(outDir, 'src', 'agents')
+  const handlersDir = join(agentsDir, 'handlers')
+  const hooksDir = join(outDir, 'src', 'hooks')
+  mkdirSync(handlersDir, { recursive: true })
+  mkdirSync(hooksDir, { recursive: true })
+
+  writeFileSync(
+    join(agentsDir, 'catalog.ts'),
+    `export const APP_AGENT_TOOL_NAMES = ${JSON.stringify(toolNames, null, 2)} as const
+
+export const APP_AGENT_LOG_LABEL = ${jsonString(appSlug)}
+`,
+  )
+
+  const handlerEntries = toolNames
+    .map(
+      name =>
+        `  ${jsonString(name)}: async () => notImplemented(${jsonString(name)}),`,
+    )
+    .join('\n')
+
+  writeFileSync(
+    join(handlersDir, 'index.ts'),
+    `import { agentToolErrorContent } from '@puredesktop/puredesktop-ui-bridge/bridge/agentToolHelpers'
+import type { AgentToolHandler } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
+
+function notImplemented(toolName: string) {
+  return agentToolErrorContent(
+    \`Tool "\${toolName}" is declared in plugin.json but its runtime handler has not been implemented yet.\`,
+  )
+}
+
+export const appAgentHandlers = {
+${handlerEntries}
+} satisfies Record<string, AgentToolHandler>
+`,
+  )
+
+  writeFileSync(
+    join(hooksDir, 'useAppAgentTools.ts'),
+    `import { usePlatformAgentTools } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
+import { APP_AGENT_LOG_LABEL, APP_AGENT_TOOL_NAMES } from '../agents/catalog'
+import { appAgentHandlers } from '../agents/handlers'
+
+export function useAppAgentTools(ready: boolean): void {
+  usePlatformAgentTools({
+    ready,
+    tools: APP_AGENT_TOOL_NAMES,
+    logLabel: APP_AGENT_LOG_LABEL,
+    handlers: appAgentHandlers,
+  })
+}
+`,
+  )
+
+  wireAgentToolHook(outDir)
+}
+
+function wireAgentToolHook(outDir) {
+  const appPath = join(outDir, 'src', 'App.tsx')
+  const source = readFileSync(appPath, 'utf8')
+  const importPattern = /import \{ useAppBoot \} from '\.\/hooks\/useAppBoot'\r?\n/
+  const callPattern = /(  const \{ error: bridgeError, ready \} = usePlatformBridge\(\)\r?\n)/
+
+  if (!importPattern.test(source) || !callPattern.test(source)) {
+    console.error('Generated src/App.tsx does not match the agent tool scaffold insertion points.')
+    process.exit(1)
+  }
+
+  const withImport = source.replace(
+    importPattern,
+    match => `${match}import { useAppAgentTools } from './hooks/useAppAgentTools'\n`,
+  )
+  const withHook = withImport.replace(
+    callPattern,
+    (_match, line) => `${line}  useAppAgentTools(ready)\n`,
+  )
+  writeFileSync(appPath, withHook)
+}
+
 function copyTemplate(srcDir, destDir, vars) {
   for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
     const srcPath = join(srcDir, entry.name)
@@ -246,7 +328,6 @@ const structuredManifest = options.manifestJsonBase64
 const structuredAgentsMd = options.agentsMdBase64
   ? readStructuredAgentsMd(options.agentsMdBase64)
   : null
-const uiDep = uiDependencySpec(options.ui)
 const dirName = targetDir
 const structuredSlug = structuredManifest?.app.slug ?? ''
 const structuredTitle = structuredManifest?.app.name ?? ''
@@ -273,13 +354,11 @@ 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}`,
-}
+  APP_NAME: slug,
+  PLUGIN_ID: pluginId,
+  APP_PORT: String(options.port),
+  PACKAGE_NAME: `@puredesktop/${slug}`,
+}
 
 copyTemplate(TEMPLATE_DIR, outDir, vars)
 
@@ -294,8 +373,15 @@ if (structuredAgentsMd) {
   writeFileSync(join(outDir, 'agents.md'), structuredAgentsMd)
 }
 
+const generatedManifest = readGeneratedManifest(outDir)
+writeAgentToolScaffold(
+  outDir,
+  generatedManifest?.app?.slug ?? slug,
+  readAgentToolNames(generatedManifest),
+)
+
 console.log(`
-Created ${title} at ${outDir}
+Created ${title} at ${outDir}
 
   cd ${dirName}
   npm install
@@ -306,7 +392,7 @@ Before shipping:
   npm run build
   npm run puredesktop:check
 
-Register in PureScience Desktop (File → Register App…) with:
+Register in PureDesktop (File -> Register App...) with:
   entrypoint: http://localhost:${options.port}
   permissions: network, settings, agents
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@puredesktop/create-app",
-  "version": "2.1.0",
-  "description": "Scaffold a PureScience Desktop plugin app (Vite + bridge SDK)",
+  "version": "2.1.1",
+  "description": "Scaffold a PureDesktop plugin app (Vite + bridge SDK)",
   "type": "module",
   "bin": {
     "create-app": "./bin/create-puredesktop-app.mjs",

package/template/README.md

@@ -1,313 +1,56 @@
-# {{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
+# {{APP_TITLE}}
 
-```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
+Vite + React plugin app for **PureDesktop**, scaffolded with
+`@puredesktop/create-app`.
 
-Keep this structure and update values rather than inventing new fields:
+## Start
 
-```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
+```bash
+npm install
+npm run dev
 ```
 
-Register matching runtime handlers after the bridge is ready:
+The dev server runs at `http://localhost:{{APP_PORT}}`, matching
+`plugin.json`.
 
-```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'
+In PureDesktop, register the app from **File -> Register App...** with the same
+entrypoint URL.
 
-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),
-          )
-        }
-      },
-    },
-  })
+## Build
 
-  return null
-}
+```bash
+npm run typecheck
+npm run build
+npm run puredesktop:check
 ```
 
-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.
+`puredesktop:check` verifies the package facts the shell needs before
+registration: manifest shape, entrypoint, permissions, `agents.md`, build output,
+and declared app agent tools.
 
-## Platform CSS variables
+## Project Layout
 
-Theme variables are injected by PureDesktop and follow
-`--platform-<domain>-<token>`. Use these before adding app-local variables:
+- `plugin.json`: app identity, permissions, entrypoint, routing, and agent tool
+  declarations.
+- `agents.md`: app-scoped assistant prompt.
+- `src/App.tsx`: bridge and boot gates wrapped in `AppFrame`.
+- `src/bridge/platformBridge.ts`: local app bridge exports.
+- `src/hooks/useAppBoot.ts`: boot data loading after bridge readiness.
+- `src/components/AppShell.tsx`: first app-owned UI surface.
+- `docs/`: builder-facing app, bridge, agent, and tool-handler docs.
 
-```text
---platform-mode
+## Builder Docs
 
---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
+Read [docs/README.md](./docs/README.md) before changing app structure.
 
---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
+Bridge helper docs live in [docs/bridge/README.md](./docs/bridge/README.md).
 
---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
-```
+## Core Rules
 
-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`.
+- `plugin.json` `app.slug` matches `src/constants.ts` `APP_SLUG`.
+- `plugin.json` `entrypoint.url` matches the Vite dev port.
+- `app.usePureDesktopAiPanel` stays `true` for shell-owned agent UI.
+- `agents.md` stays at the package root for app-scoped sessions.
+- Bridge calls stay inside `src/bridge/platformBridge.ts` or files owned by
+  `src/bridge/`.
+- `AppFrame` wraps every `src/App.tsx` return path.

package/template/docs/README.md

@@ -0,0 +1,31 @@
+# PureDesktop App Builder Docs
+
+This folder is the builder-facing contract for generated PureDesktop apps.
+
+A generated app is a Vite + React application rendered by PureDesktop inside a
+workspace iframe. The app owns its UI, state, domain logic, and optional tool
+handlers. The shell owns discovery, tabs, bridge permissions, filesystem and OS
+services, agent sessions, and app registration.
+
+Read these in order when building or repairing an app:
+
+1. [App lifecycle](./app-lifecycle.md)
+2. [Plugin manifest](./plugin-manifest.md)
+3. [Bridge helpers](./bridge/README.md)
+4. [App agent](./agent.md)
+5. [Tool handlers](./tool-handlers.md)
+6. [UI and components](./ui-and-components.md)
+7. [Theme CSS variables](./theme-vars.md)
+
+Key files in this scaffold:
+
+- `plugin.json`: app identity, entrypoint, permissions, file routing, and agent
+  tool declarations.
+- `agents.md`: app-scoped assistant instructions used by shell agent sessions.
+- `src/App.tsx`: bridge readiness, boot loading, and `AppFrame` wrapper.
+- `src/bridge/platformBridge.ts`: local app bridge surface.
+- `src/hooks/useAppBoot.ts`: app boot data loading after the bridge is ready.
+- `src/components/AppShell.tsx`: first app-owned UI surface.
+- `scripts/validate-puredesktop-app.mjs`: registration and tool scaffold check.
+
+Use `npm run puredesktop:check` after `npm run build` before registration.