@puredesktop/create-app 2.1.1 → 2.1.3

package/bin/create-puredesktop-app.mjs

@@ -388,7 +388,7 @@ Created ${title} at ${outDir}
   npm run dev
 
 Before shipping:
-  npm run typecheck
+  npm run typecheck
   npm run build
   npm run puredesktop:check
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puredesktop/create-app",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Scaffold a PureDesktop plugin app (Vite + bridge SDK)",
   "type": "module",
   "bin": {

package/template/README.md

@@ -19,14 +19,14 @@ entrypoint URL.
 ## Build
 
 ```bash
-npm run typecheck
+npm run typecheck
 npm run build
 npm run puredesktop:check
 ```
 
-`puredesktop:check` verifies the package facts the shell needs before
-registration: manifest shape, entrypoint, permissions, `agents.md`, build output,
-and declared app agent tools.
+`puredesktop:check` verifies the package facts the shell needs before
+registration: manifest shape, entrypoint, permissions, `agents.md`, build output,
+and declared app agent tools.
 
 ## Project Layout
 

package/template/docs/README.md

@@ -26,6 +26,6 @@ Key files in this scaffold:
 - `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.
+- `scripts/validate-puredesktop-app.mjs`: registration and tool scaffold check.
 
 Use `npm run puredesktop:check` after `npm run build` before registration.

package/template/docs/bridge/README.md

@@ -47,6 +47,11 @@ 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)

package/template/docs/plugin-manifest.md

@@ -98,11 +98,11 @@ registration in the iframe executes the tool.
 Run:
 
 ```bash
-npm run typecheck
+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.
+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.

package/template/docs/tool-handlers.md

@@ -106,8 +106,8 @@ state set `requiresApproval: true` unless the action is intentionally safe.
 
 ## Validation
 
-`npm run puredesktop:check` verifies declared tool names appear in source and in
-the built output. For generated tool scaffolds, it also verifies:
+`npm run puredesktop:check` verifies declared tool names appear in source and in
+the built output. For generated tool scaffolds, it also verifies:
 
 - `src/agents/catalog.ts` exports `APP_AGENT_TOOL_NAMES`;
 - every manifest tool name appears in the catalog;

package/template/package.json

@@ -10,7 +10,7 @@
     "puredesktop:check": "node scripts/validate-puredesktop-app.mjs"
   },
   "dependencies": {
-    "@puredesktop/puredesktop-ui-bridge": "2.1.1",
+    "@puredesktop/puredesktop-ui-bridge": "2.1.3",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "styled-components": "^6.1.18"

package/template/scripts/validate-puredesktop-app.mjs

@@ -1,342 +1,342 @@
-#!/usr/bin/env node
-import { existsSync } from 'node:fs'
-import { readFile, readdir, stat } from 'node:fs/promises'
-import { join } from 'node:path'
-
-const ROOT = process.cwd()
-const MANIFEST_FILE = 'plugin.json'
-const PACKAGE_FILE = 'package.json'
-const TEXT_FILE_RE = /\.(cjs|css|html|js|json|jsx|mjs|ts|tsx|txt)$/i
-
-const errors = []
-const warnings = []
-const info = []
-
-const manifest = await readManifest()
-const packageJson = await readPackageJson()
-const distPath = join(ROOT, 'dist')
-
-if (packageJson) {
-  validatePackageJson(packageJson)
-}
-
-if (manifest) {
-  validateManifest(manifest)
-}
-
-if (await isDirectory(distPath)) {
-  info.push('dist folder is present for static registration.')
-} else {
-  errors.push('dist folder is required before the app can be registered. Run npm run build first.')
-}
-
-if (await isFile(join(ROOT, 'agents.md'))) {
-  info.push('agents.md is present.')
-} else {
-  errors.push('agents.md is required for every PureDesktop app.')
-}
-
-if (manifest?.permissions?.includes('agents')) {
-  info.push('agents permission is enabled.')
-} else {
-  errors.push('plugin.json must include the agents permission.')
-}
-
-if (manifest?.app?.usePureDesktopAiPanel === true) {
-  info.push('app.usePureDesktopAiPanel is true.')
-} else {
-  errors.push('plugin.json app.usePureDesktopAiPanel must be true for now.')
-}
-
-if (manifest) {
-  await validateAgentTools(manifest, distPath)
-}
-
-for (const message of info) console.log(`ok: ${message}`)
-for (const message of warnings) console.warn(`warn: ${message}`)
-for (const message of errors) console.error(`error: ${message}`)
-
-if (errors.length > 0) {
-  console.error(`\nPureDesktop app validation failed with ${errors.length} error${errors.length === 1 ? '' : 's'}.`)
-  process.exit(1)
-}
-
-console.log('\nPureDesktop app validation passed.')
-
-async function readManifest() {
-  return readJsonFile(MANIFEST_FILE)
-}
-
-async function readPackageJson() {
-  return readJsonFile(PACKAGE_FILE)
-}
-
-async function readJsonFile(fileName) {
-  const filePath = join(ROOT, fileName)
-  if (!existsSync(filePath)) {
-    errors.push(`${fileName} is missing.`)
-    return null
-  }
-  try {
-    return JSON.parse(await readFile(filePath, 'utf8'))
-  } catch (error) {
-    errors.push(`${fileName} could not be read: ${errorMessage(error)}`)
-    return null
-  }
-}
-
-function validatePackageJson(pkg) {
-  const scripts = isPlainObject(pkg.scripts) ? pkg.scripts : {}
-  requirePackageScript(scripts, 'dev')
-  requirePackageScript(scripts, 'build')
-  requirePackageScript(scripts, 'typecheck')
-  requirePackageScript(scripts, 'puredesktop:check')
-
-  const dependencies = isPlainObject(pkg.dependencies) ? pkg.dependencies : {}
-  requirePackageDependency(dependencies, '@puredesktop/puredesktop-ui-bridge')
-  requirePackageDependency(dependencies, 'react')
-  requirePackageDependency(dependencies, 'react-dom')
-  requirePackageDependency(dependencies, 'styled-components')
-
-  const devDependencies = isPlainObject(pkg.devDependencies) ? pkg.devDependencies : {}
-  requirePackageDependency(devDependencies, '@vitejs/plugin-react-swc')
-  requirePackageDependency(devDependencies, 'typescript')
-  requirePackageDependency(devDependencies, 'vite')
-
-  if (errors.length === 0) info.push('package.json has the required PureDesktop scripts and dependencies.')
-}
-
-function requirePackageScript(scripts, name) {
-  if (!nonEmptyString(scripts[name])) {
-    errors.push(`package.json scripts.${name} is required.`)
-  }
-}
-
-function requirePackageDependency(dependencies, name) {
-  if (!nonEmptyString(dependencies[name])) {
-    errors.push(`package.json must include ${name}.`)
-  }
-}
-
-function validateManifest(manifest) {
-  if (manifest.schemaVersion !== 1) errors.push('schemaVersion must be 1.')
-  if (!nonEmptyString(manifest.id)) errors.push('id is required.')
-  if (!nonEmptyString(manifest.name)) errors.push('name is required.')
-  if (!isPlainObject(manifest.app)) {
-    errors.push('app is required.')
-    return
-  }
-  if (!nonEmptyString(manifest.app.slug)) errors.push('app.slug is required.')
-  if (!nonEmptyString(manifest.app.name)) errors.push('app.name is required.')
-
-  const permissions = Array.isArray(manifest.permissions) ? manifest.permissions : []
-  validateEntrypoint(manifest.entrypoint ?? manifest.app.entrypoint, permissions)
-
-  if (errors.length === 0) info.push('plugin.json is valid.')
-}
-
-function validateEntrypoint(entrypoint, permissions) {
-  if (!isPlainObject(entrypoint)) {
-    errors.push('entrypoint is required.')
-    return
-  }
-  if (entrypoint.kind === 'dev-url') {
-    if (!nonEmptyString(entrypoint.url)) {
-      errors.push('entrypoint.url is required for dev-url.')
-      return
-    }
-    let url
-    try {
-      url = new URL(entrypoint.url)
-    } catch {
-      errors.push('entrypoint.url must be a valid http or https URL.')
-      return
-    }
-    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-      errors.push('entrypoint.url must use http or https.')
-    }
-    if (!isLocalHost(url.hostname) && !permissions.includes('network')) {
-      errors.push('Non-local entrypoint URLs require the network permission.')
-    }
-    return
-  }
-  if (entrypoint.kind === 'built-static') {
-    if (!safeRelativeDir(entrypoint.dir)) {
-      errors.push('built-static entrypoint.dir must be a safe relative directory.')
-    }
-    if (entrypoint.dir !== 'dist') {
-      warnings.push(`PureDesktop registration packages usually use built-static dir "dist" instead of "${entrypoint.dir}".`)
-    }
-    return
-  }
-  errors.push(`Unsupported entrypoint kind: ${String(entrypoint.kind ?? '') || '(missing)'}.`)
-}
-
-async function validateAgentTools(manifest, distPath) {
-  const tools = manifest.app?.agents?.tools ?? []
-  if (!Array.isArray(tools) || tools.length === 0) {
-    info.push('No app agent tools declared.')
-    return
-  }
-
-  if (!manifest.permissions?.includes('agents')) {
-    errors.push('app.agents.tools is declared, so plugin.json must include the agents permission.')
-  }
-
-  const toolNames = new Set()
-  tools.forEach((tool, index) => {
-    const label = `app.agents.tools[${index}]`
-    const name = typeof tool?.name === 'string' ? tool.name.trim() : ''
-    if (!name) {
-      errors.push(`${label}.name is required.`)
-      return
-    }
-    if (toolNames.has(name)) errors.push(`Duplicate app agent tool name: ${name}.`)
-    toolNames.add(name)
-    if (!tool.description?.trim()) errors.push(`${label}.description is required.`)
-    if (!isPlainObject(tool.inputSchema)) errors.push(`${label}.inputSchema must be an object.`)
-  })
-
-  if (toolNames.size === 0) return
-
-  const manifestToolNames = [...toolNames]
-  await validateAgentToolScaffold(manifestToolNames)
-
-  const sourceText = await readProjectText(join(ROOT, 'src'))
-  const distText = await readProjectText(distPath)
-  const registrationHints = ['usePlatformAgentTools', 'registerAgentTools', 'agents.tools.register']
-  if (!registrationHints.some(hint => sourceText.includes(hint))) {
-    errors.push('Declared app agent tools must be registered in source with usePlatformAgentTools or agents.tools.register.')
-  }
-
-  for (const toolName of manifestToolNames) {
-    if (!sourceText.includes(toolName)) {
-      errors.push(`Declared app agent tool "${toolName}" was not found in source files.`)
-    }
-    if (!distText.includes(toolName)) {
-      errors.push(`Declared app agent tool "${toolName}" was not found in the built dist output.`)
-    }
-  }
-
-  if (!errors.some(error => error.includes('app agent tool'))) {
-    info.push(`Verified ${toolNames.size} app agent tool${toolNames.size === 1 ? '' : 's'} in source and dist.`)
-  }
-}
-
-async function validateAgentToolScaffold(toolNames) {
-  const catalogPath = join(ROOT, 'src', 'agents', 'catalog.ts')
-  const handlersPath = join(ROOT, 'src', 'agents', 'handlers', 'index.ts')
-  const hookPath = join(ROOT, 'src', 'hooks', 'useAppAgentTools.ts')
-  const appPath = join(ROOT, 'src', 'App.tsx')
-
-  const catalogText = await readRequiredText(
-    catalogPath,
-    'Declared app agent tools require src/agents/catalog.ts.',
-  )
-  const handlersText = await readRequiredText(
-    handlersPath,
-    'Declared app agent tools require src/agents/handlers/index.ts.',
-  )
-  const hookText = await readRequiredText(
-    hookPath,
-    'Declared app agent tools require src/hooks/useAppAgentTools.ts.',
-  )
-  const appText = await readRequiredText(
-    appPath,
-    'Declared app agent tools require src/App.tsx.',
-  )
-
-  if (!catalogText || !handlersText || !hookText || !appText) return
-
-  if (!catalogText.includes('APP_AGENT_TOOL_NAMES')) {
-    errors.push('src/agents/catalog.ts must export APP_AGENT_TOOL_NAMES.')
-  }
-  if (!handlersText.includes('appAgentHandlers')) {
-    errors.push('src/agents/handlers/index.ts must export appAgentHandlers.')
-  }
-  if (!hookText.includes('usePlatformAgentTools')) {
-    errors.push('src/hooks/useAppAgentTools.ts must call usePlatformAgentTools.')
-  }
-  if (!hookText.includes('APP_AGENT_TOOL_NAMES')) {
-    errors.push('src/hooks/useAppAgentTools.ts must register APP_AGENT_TOOL_NAMES.')
-  }
-  if (!appText.includes('useAppAgentTools(ready)')) {
-    errors.push('src/App.tsx must call useAppAgentTools(ready).')
-  }
-
-  for (const toolName of toolNames) {
-    if (!catalogText.includes(toolName)) {
-      errors.push(`src/agents/catalog.ts is missing app agent tool "${toolName}".`)
-    }
-    if (!handlersText.includes(toolName)) {
-      errors.push(`src/agents/handlers/index.ts is missing app agent tool "${toolName}".`)
-    }
-  }
-}
-
-async function readRequiredText(path, message) {
-  if (!(await isFile(path))) {
-    errors.push(message)
-    return ''
-  }
-  return readFile(path, 'utf8').catch(error => {
-    errors.push(`${message} ${errorMessage(error)}`)
-    return ''
-  })
-}
-
-async function readProjectText(root) {
-  const chunks = []
-  await collectText(root, chunks)
-  return chunks.join('\n')
-}
-
-async function collectText(path, chunks) {
-  const stats = await stat(path).catch(() => null)
-  if (!stats) return
-  if (stats.isFile()) {
-    if (!TEXT_FILE_RE.test(path)) return
-    chunks.push(await readFile(path, 'utf8').catch(() => ''))
-    return
-  }
-  if (!stats.isDirectory()) return
-  const entries = await readdir(path, { withFileTypes: true }).catch(() => [])
-  for (const entry of entries) {
-    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
-    await collectText(join(path, entry.name), chunks)
-  }
-}
-
-async function isFile(path) {
-  return stat(path)
-    .then(stats => stats.isFile())
-    .catch(() => false)
-}
-
-async function isDirectory(path) {
-  return stat(path)
-    .then(stats => stats.isDirectory())
-    .catch(() => false)
-}
-
-function nonEmptyString(value) {
-  return typeof value === 'string' && value.trim().length > 0
-}
-
-function isPlainObject(value) {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
-}
-
-function isLocalHost(hostname) {
-  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'
-}
-
-function safeRelativeDir(value) {
-  if (!nonEmptyString(value)) return false
-  const normalized = value.replaceAll('\\', '/')
-  return !normalized.startsWith('/') && !normalized.includes('..')
-}
-
-function errorMessage(error) {
-  return error instanceof Error ? error.message : String(error)
-}
+#!/usr/bin/env node
+import { existsSync } from 'node:fs'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const ROOT = process.cwd()
+const MANIFEST_FILE = 'plugin.json'
+const PACKAGE_FILE = 'package.json'
+const TEXT_FILE_RE = /\.(cjs|css|html|js|json|jsx|mjs|ts|tsx|txt)$/i
+
+const errors = []
+const warnings = []
+const info = []
+
+const manifest = await readManifest()
+const packageJson = await readPackageJson()
+const distPath = join(ROOT, 'dist')
+
+if (packageJson) {
+  validatePackageJson(packageJson)
+}
+
+if (manifest) {
+  validateManifest(manifest)
+}
+
+if (await isDirectory(distPath)) {
+  info.push('dist folder is present for static registration.')
+} else {
+  errors.push('dist folder is required before the app can be registered. Run npm run build first.')
+}
+
+if (await isFile(join(ROOT, 'agents.md'))) {
+  info.push('agents.md is present.')
+} else {
+  errors.push('agents.md is required for every PureDesktop app.')
+}
+
+if (manifest?.permissions?.includes('agents')) {
+  info.push('agents permission is enabled.')
+} else {
+  errors.push('plugin.json must include the agents permission.')
+}
+
+if (manifest?.app?.usePureDesktopAiPanel === true) {
+  info.push('app.usePureDesktopAiPanel is true.')
+} else {
+  errors.push('plugin.json app.usePureDesktopAiPanel must be true for now.')
+}
+
+if (manifest) {
+  await validateAgentTools(manifest, distPath)
+}
+
+for (const message of info) console.log(`ok: ${message}`)
+for (const message of warnings) console.warn(`warn: ${message}`)
+for (const message of errors) console.error(`error: ${message}`)
+
+if (errors.length > 0) {
+  console.error(`\nPureDesktop app validation failed with ${errors.length} error${errors.length === 1 ? '' : 's'}.`)
+  process.exit(1)
+}
+
+console.log('\nPureDesktop app validation passed.')
+
+async function readManifest() {
+  return readJsonFile(MANIFEST_FILE)
+}
+
+async function readPackageJson() {
+  return readJsonFile(PACKAGE_FILE)
+}
+
+async function readJsonFile(fileName) {
+  const filePath = join(ROOT, fileName)
+  if (!existsSync(filePath)) {
+    errors.push(`${fileName} is missing.`)
+    return null
+  }
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'))
+  } catch (error) {
+    errors.push(`${fileName} could not be read: ${errorMessage(error)}`)
+    return null
+  }
+}
+
+function validatePackageJson(pkg) {
+  const scripts = isPlainObject(pkg.scripts) ? pkg.scripts : {}
+  requirePackageScript(scripts, 'dev')
+  requirePackageScript(scripts, 'build')
+  requirePackageScript(scripts, 'typecheck')
+  requirePackageScript(scripts, 'puredesktop:check')
+
+  const dependencies = isPlainObject(pkg.dependencies) ? pkg.dependencies : {}
+  requirePackageDependency(dependencies, '@puredesktop/puredesktop-ui-bridge')
+  requirePackageDependency(dependencies, 'react')
+  requirePackageDependency(dependencies, 'react-dom')
+  requirePackageDependency(dependencies, 'styled-components')
+
+  const devDependencies = isPlainObject(pkg.devDependencies) ? pkg.devDependencies : {}
+  requirePackageDependency(devDependencies, '@vitejs/plugin-react-swc')
+  requirePackageDependency(devDependencies, 'typescript')
+  requirePackageDependency(devDependencies, 'vite')
+
+  if (errors.length === 0) info.push('package.json has the required PureDesktop scripts and dependencies.')
+}
+
+function requirePackageScript(scripts, name) {
+  if (!nonEmptyString(scripts[name])) {
+    errors.push(`package.json scripts.${name} is required.`)
+  }
+}
+
+function requirePackageDependency(dependencies, name) {
+  if (!nonEmptyString(dependencies[name])) {
+    errors.push(`package.json must include ${name}.`)
+  }
+}
+
+function validateManifest(manifest) {
+  if (manifest.schemaVersion !== 1) errors.push('schemaVersion must be 1.')
+  if (!nonEmptyString(manifest.id)) errors.push('id is required.')
+  if (!nonEmptyString(manifest.name)) errors.push('name is required.')
+  if (!isPlainObject(manifest.app)) {
+    errors.push('app is required.')
+    return
+  }
+  if (!nonEmptyString(manifest.app.slug)) errors.push('app.slug is required.')
+  if (!nonEmptyString(manifest.app.name)) errors.push('app.name is required.')
+
+  const permissions = Array.isArray(manifest.permissions) ? manifest.permissions : []
+  validateEntrypoint(manifest.entrypoint ?? manifest.app.entrypoint, permissions)
+
+  if (errors.length === 0) info.push('plugin.json is valid.')
+}
+
+function validateEntrypoint(entrypoint, permissions) {
+  if (!isPlainObject(entrypoint)) {
+    errors.push('entrypoint is required.')
+    return
+  }
+  if (entrypoint.kind === 'dev-url') {
+    if (!nonEmptyString(entrypoint.url)) {
+      errors.push('entrypoint.url is required for dev-url.')
+      return
+    }
+    let url
+    try {
+      url = new URL(entrypoint.url)
+    } catch {
+      errors.push('entrypoint.url must be a valid http or https URL.')
+      return
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      errors.push('entrypoint.url must use http or https.')
+    }
+    if (!isLocalHost(url.hostname) && !permissions.includes('network')) {
+      errors.push('Non-local entrypoint URLs require the network permission.')
+    }
+    return
+  }
+  if (entrypoint.kind === 'built-static') {
+    if (!safeRelativeDir(entrypoint.dir)) {
+      errors.push('built-static entrypoint.dir must be a safe relative directory.')
+    }
+    if (entrypoint.dir !== 'dist') {
+      warnings.push(`PureDesktop registration packages usually use built-static dir "dist" instead of "${entrypoint.dir}".`)
+    }
+    return
+  }
+  errors.push(`Unsupported entrypoint kind: ${String(entrypoint.kind ?? '') || '(missing)'}.`)
+}
+
+async function validateAgentTools(manifest, distPath) {
+  const tools = manifest.app?.agents?.tools ?? []
+  if (!Array.isArray(tools) || tools.length === 0) {
+    info.push('No app agent tools declared.')
+    return
+  }
+
+  if (!manifest.permissions?.includes('agents')) {
+    errors.push('app.agents.tools is declared, so plugin.json must include the agents permission.')
+  }
+
+  const toolNames = new Set()
+  tools.forEach((tool, index) => {
+    const label = `app.agents.tools[${index}]`
+    const name = typeof tool?.name === 'string' ? tool.name.trim() : ''
+    if (!name) {
+      errors.push(`${label}.name is required.`)
+      return
+    }
+    if (toolNames.has(name)) errors.push(`Duplicate app agent tool name: ${name}.`)
+    toolNames.add(name)
+    if (!tool.description?.trim()) errors.push(`${label}.description is required.`)
+    if (!isPlainObject(tool.inputSchema)) errors.push(`${label}.inputSchema must be an object.`)
+  })
+
+  if (toolNames.size === 0) return
+
+  const manifestToolNames = [...toolNames]
+  await validateAgentToolScaffold(manifestToolNames)
+
+  const sourceText = await readProjectText(join(ROOT, 'src'))
+  const distText = await readProjectText(distPath)
+  const registrationHints = ['usePlatformAgentTools', 'registerAgentTools', 'agents.tools.register']
+  if (!registrationHints.some(hint => sourceText.includes(hint))) {
+    errors.push('Declared app agent tools must be registered in source with usePlatformAgentTools or agents.tools.register.')
+  }
+
+  for (const toolName of manifestToolNames) {
+    if (!sourceText.includes(toolName)) {
+      errors.push(`Declared app agent tool "${toolName}" was not found in source files.`)
+    }
+    if (!distText.includes(toolName)) {
+      errors.push(`Declared app agent tool "${toolName}" was not found in the built dist output.`)
+    }
+  }
+
+  if (!errors.some(error => error.includes('app agent tool'))) {
+    info.push(`Verified ${toolNames.size} app agent tool${toolNames.size === 1 ? '' : 's'} in source and dist.`)
+  }
+}
+
+async function validateAgentToolScaffold(toolNames) {
+  const catalogPath = join(ROOT, 'src', 'agents', 'catalog.ts')
+  const handlersPath = join(ROOT, 'src', 'agents', 'handlers', 'index.ts')
+  const hookPath = join(ROOT, 'src', 'hooks', 'useAppAgentTools.ts')
+  const appPath = join(ROOT, 'src', 'App.tsx')
+
+  const catalogText = await readRequiredText(
+    catalogPath,
+    'Declared app agent tools require src/agents/catalog.ts.',
+  )
+  const handlersText = await readRequiredText(
+    handlersPath,
+    'Declared app agent tools require src/agents/handlers/index.ts.',
+  )
+  const hookText = await readRequiredText(
+    hookPath,
+    'Declared app agent tools require src/hooks/useAppAgentTools.ts.',
+  )
+  const appText = await readRequiredText(
+    appPath,
+    'Declared app agent tools require src/App.tsx.',
+  )
+
+  if (!catalogText || !handlersText || !hookText || !appText) return
+
+  if (!catalogText.includes('APP_AGENT_TOOL_NAMES')) {
+    errors.push('src/agents/catalog.ts must export APP_AGENT_TOOL_NAMES.')
+  }
+  if (!handlersText.includes('appAgentHandlers')) {
+    errors.push('src/agents/handlers/index.ts must export appAgentHandlers.')
+  }
+  if (!hookText.includes('usePlatformAgentTools')) {
+    errors.push('src/hooks/useAppAgentTools.ts must call usePlatformAgentTools.')
+  }
+  if (!hookText.includes('APP_AGENT_TOOL_NAMES')) {
+    errors.push('src/hooks/useAppAgentTools.ts must register APP_AGENT_TOOL_NAMES.')
+  }
+  if (!appText.includes('useAppAgentTools(ready)')) {
+    errors.push('src/App.tsx must call useAppAgentTools(ready).')
+  }
+
+  for (const toolName of toolNames) {
+    if (!catalogText.includes(toolName)) {
+      errors.push(`src/agents/catalog.ts is missing app agent tool "${toolName}".`)
+    }
+    if (!handlersText.includes(toolName)) {
+      errors.push(`src/agents/handlers/index.ts is missing app agent tool "${toolName}".`)
+    }
+  }
+}
+
+async function readRequiredText(path, message) {
+  if (!(await isFile(path))) {
+    errors.push(message)
+    return ''
+  }
+  return readFile(path, 'utf8').catch(error => {
+    errors.push(`${message} ${errorMessage(error)}`)
+    return ''
+  })
+}
+
+async function readProjectText(root) {
+  const chunks = []
+  await collectText(root, chunks)
+  return chunks.join('\n')
+}
+
+async function collectText(path, chunks) {
+  const stats = await stat(path).catch(() => null)
+  if (!stats) return
+  if (stats.isFile()) {
+    if (!TEXT_FILE_RE.test(path)) return
+    chunks.push(await readFile(path, 'utf8').catch(() => ''))
+    return
+  }
+  if (!stats.isDirectory()) return
+  const entries = await readdir(path, { withFileTypes: true }).catch(() => [])
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+    await collectText(join(path, entry.name), chunks)
+  }
+}
+
+async function isFile(path) {
+  return stat(path)
+    .then(stats => stats.isFile())
+    .catch(() => false)
+}
+
+async function isDirectory(path) {
+  return stat(path)
+    .then(stats => stats.isDirectory())
+    .catch(() => false)
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isLocalHost(hostname) {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'
+}
+
+function safeRelativeDir(value) {
+  if (!nonEmptyString(value)) return false
+  const normalized = value.replaceAll('\\', '/')
+  return !normalized.startsWith('/') && !normalized.includes('..')
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error)
+}

package/template/src/App.tsx

@@ -1,5 +1,5 @@
-import { AppFrame } from '@puredesktop/puredesktop-ui-bridge/components/common/containers/AppFrame'
-import { EmptyState } from '@puredesktop/puredesktop-ui-bridge/components/common/feedback/EmptyState'
+import { AppFrame } from '@puredesktop/puredesktop-ui-bridge/components/common/containers/AppFrame'
+import { EmptyState } from '@puredesktop/puredesktop-ui-bridge/components/common/feedback/EmptyState'
 import { usePlatformBridge } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformBridge'
 import { AppShell } from './components/AppShell'
 import { isStandaloneDevMode } from './bridge/platformBridge'

package/template/src/bridge/platformBridge.ts

@@ -1,22 +1,14 @@
 import { bridge } from '@puredesktop/puredesktop-ui-bridge/bridge/client'
-import { getPlatformAppSettings } from '@puredesktop/puredesktop-ui-bridge/bridge/appSettings'
-import { APP_SLUG } from '../constants'
-import type { AppSettings } from '../types'
-
-export {
+import {
   getPlatformAppSettings,
   updatePlatformAppSettings,
 } from '@puredesktop/puredesktop-ui-bridge/bridge/appSettings'
-export {
+import {
   getPlatformPreferences,
   patchPlatformPreferences,
 } from '@puredesktop/puredesktop-ui-bridge/bridge/preferences'
-export {
-  networkFetch,
-  type PlatformNetworkFetchRequest,
-  type PlatformNetworkFetchResponse,
-} from '@puredesktop/puredesktop-ui-bridge/bridge/network'
-export {
+import { networkFetch } from '@puredesktop/puredesktop-ui-bridge/bridge/network'
+import {
   createPlatformFolder,
   deletePlatformFile,
   listPlatformFiles,
@@ -28,47 +20,99 @@ export {
   renamePlatformFile,
   writePlatformFileBinary,
   writePlatformTextFile,
-  type PlatformFileCreateFolderResult,
-  type PlatformFileDeleteResult,
-  type PlatformFileEntry,
-  type PlatformFileListResult,
-  type PlatformFilePreviewUrlResult,
-  type PlatformFileReadBinaryResult,
-  type PlatformFileReadPreviewResult,
-  type PlatformFileRenameResult,
-  type PlatformFileWriteResult,
 } from '@puredesktop/puredesktop-ui-bridge/bridge/fs'
-export {
+import {
   openPlatformFileDialog,
   openPlatformFolderDialog,
   openPlatformImageDialog,
   savePlatformFolderDialog,
 } from '@puredesktop/puredesktop-ui-bridge/bridge/dialog'
-export {
+import {
   readPlatformStorageJson,
   writePlatformStorageJson,
-  type PlatformStorageJsonReadResult,
-  type PlatformStorageJsonRequest,
-  type PlatformStorageJsonWriteRequest,
-  type PlatformStorageJsonWriteResult,
 } from '@puredesktop/puredesktop-ui-bridge/bridge/storage'
-export { bridge }
-
-const STANDALONE_SETTINGS_KEY = 'puredesktop:{{APP_SLUG}}:settings'
-
-export function isStandaloneDevMode(): boolean {
-  return import.meta.env.DEV && window.parent === window
-}
-
-function readStandaloneSettings(): AppSettings {
-  try {
-    const raw = window.localStorage.getItem(STANDALONE_SETTINGS_KEY)
-    return raw ? (JSON.parse(raw) as AppSettings) : {}
-  } catch {
-    return {}
-  }
-}
-
+import { APP_SLUG } from '../constants'
+import type { AppSettings } from '../types'
+import type {
+  PlatformNetworkFetchRequest,
+  PlatformNetworkFetchResponse,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/network'
+import type {
+  PlatformFileCreateFolderResult,
+  PlatformFileDeleteResult,
+  PlatformFileEntry,
+  PlatformFileListResult,
+  PlatformFilePreviewUrlResult,
+  PlatformFileReadBinaryResult,
+  PlatformFileReadPreviewResult,
+  PlatformFileRenameResult,
+  PlatformFileWriteResult,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/fs'
+import type {
+  PlatformStorageJsonReadResult,
+  PlatformStorageJsonRequest,
+  PlatformStorageJsonWriteRequest,
+  PlatformStorageJsonWriteResult,
+} from '@puredesktop/puredesktop-ui-bridge/bridge/storage'
+
+export {
+  getPlatformAppSettings,
+  updatePlatformAppSettings,
+  getPlatformPreferences,
+  patchPlatformPreferences,
+  networkFetch,
+  createPlatformFolder,
+  deletePlatformFile,
+  listPlatformFiles,
+  readPlatformFileBinary,
+  readPlatformFileBinaryDataUrl,
+  readPlatformFilePreview,
+  readPlatformFilePreviewUrl,
+  readPlatformTextFile,
+  renamePlatformFile,
+  writePlatformFileBinary,
+  writePlatformTextFile,
+  openPlatformFileDialog,
+  openPlatformFolderDialog,
+  openPlatformImageDialog,
+  savePlatformFolderDialog,
+  readPlatformStorageJson,
+  writePlatformStorageJson,
+  bridge,
+}
+export type {
+  PlatformNetworkFetchRequest,
+  PlatformNetworkFetchResponse,
+  PlatformFileCreateFolderResult,
+  PlatformFileDeleteResult,
+  PlatformFileEntry,
+  PlatformFileListResult,
+  PlatformFilePreviewUrlResult,
+  PlatformFileReadBinaryResult,
+  PlatformFileReadPreviewResult,
+  PlatformFileRenameResult,
+  PlatformFileWriteResult,
+  PlatformStorageJsonReadResult,
+  PlatformStorageJsonRequest,
+  PlatformStorageJsonWriteRequest,
+  PlatformStorageJsonWriteResult,
+}
+
+const STANDALONE_SETTINGS_KEY = 'puredesktop:{{APP_SLUG}}:settings'
+
+export function isStandaloneDevMode(): boolean {
+  return import.meta.env.DEV && window.parent === window
+}
+
+function readStandaloneSettings(): AppSettings {
+  try {
+    const raw = window.localStorage.getItem(STANDALONE_SETTINGS_KEY)
+    return raw ? (JSON.parse(raw) as AppSettings) : {}
+  } catch {
+    return {}
+  }
+}
+
 export async function fetchAppSettings(): Promise<AppSettings> {
   if (isStandaloneDevMode()) {
     return readStandaloneSettings()

package/template/src/components/AppShell.tsx

@@ -1,6 +1,6 @@
-import styled from 'styled-components'
-import { Heading } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Heading'
-import { Text } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Text'
+import styled from 'styled-components'
+import { Heading } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Heading'
+import { Text } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Text'
 import type { AppSettings } from '../types'
 
 const Root = styled.div`
@@ -22,10 +22,10 @@ export function AppShell({ settings }: AppShellProps): React.ReactElement {
       <Text>
         Start building in <code>src/components/AppShell.tsx</code>. Bridge boot
         is wired — AppFrame, settings load, and standalone browser dev all work.
-      </Text>
-      {Object.keys(settings).length > 0 ? (
-        <Text meta>Loaded {Object.keys(settings).length} setting key(s).</Text>
-      ) : null}
+      </Text>
+      {Object.keys(settings).length > 0 ? (
+        <Text meta>Loaded {Object.keys(settings).length} setting key(s).</Text>
+      ) : null}
     </Root>
   )
 }