npm - @puredesktop/create-app - Versions diffs - 1.0.0-beta.1 → 1.0.0-beta.2 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/bin/create-puredesktop-app.mjs +164 -159
package/package.json +1 -1
package/template/README.md +299 -16
package/template/agents.md +11 -0
package/template/gitignore.tpl +5 -5
package/template/index.html +12 -12
package/template/package.json +22 -21
package/template/plugin.json +3 -2
package/template/scripts/validate-puredesktop-app.mjs +277 -0
package/template/src/App.tsx +49 -49
package/template/src/bridge/platformBridge.ts +31 -31
package/template/src/components/AppShell.tsx +31 -31
package/template/src/constants.ts +1 -1
package/template/src/hooks/useAppBoot.ts +45 -45
package/template/src/main.tsx +9 -9
package/template/src/types.ts +5 -5
package/template/tsconfig.json +15 -15
package/template/vite-env.d.ts +1 -1
package/template/vite.config.js +28 -28

package/template/index.html CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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
   }
 }

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

@@ -0,0 +1,277 @@
+#!/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 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 toolNames) {
+    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 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 CHANGED Viewed

@@ -1,49 +1,49 @@
-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'
-import { useAppBoot } from './hooks/useAppBoot'
-export function App(): React.ReactElement {
-  const { error: bridgeError, ready } = usePlatformBridge()
-  const standaloneDev = isStandaloneDevMode()
-  const bootReady = ready || standaloneDev
-  const { boot, bootError, booting } = useAppBoot(bootReady)
-  if (bridgeError && !standaloneDev) {
-    return (
-      <AppFrame>
-        <EmptyState
-          tone="error"
-          title="Bridge unavailable"
-          message={bridgeError.message}
-        />
-      </AppFrame>
-    )
-  }
-  if (!bootReady || !boot) {
-    return (
-      <AppFrame>
-        <EmptyState
-          tone={bootError ? 'error' : 'neutral'}
-          title={bootError ? 'Boot failed' : '{{APP_TITLE}}'}
-          message={
-            bootError
-              ? bootError.message
-              : booting
-                ? 'Loading…'
-                : 'Waiting for PureScience shell bridge…'
-          }
-        />
-      </AppFrame>
-    )
-  }
-  return (
-    <AppFrame>
-      <AppShell settings={boot.settings} />
-    </AppFrame>
-  )
-}
+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'
+import { useAppBoot } from './hooks/useAppBoot'
+export function App(): React.ReactElement {
+  const { error: bridgeError, ready } = usePlatformBridge()
+  const standaloneDev = isStandaloneDevMode()
+  const bootReady = ready || standaloneDev
+  const { boot, bootError, booting } = useAppBoot(bootReady)
+  if (bridgeError && !standaloneDev) {
+    return (
+      <AppFrame>
+        <EmptyState
+          tone="error"
+          title="Bridge unavailable"
+          message={bridgeError.message}
+        />
+      </AppFrame>
+    )
+  }
+  if (!bootReady || !boot) {
+    return (
+      <AppFrame>
+        <EmptyState
+          tone={bootError ? 'error' : 'neutral'}
+          title={bootError ? 'Boot failed' : '{{APP_TITLE}}'}
+          message={
+            bootError
+              ? bootError.message
+              : booting
+                ? 'Loading…'
+                : 'Waiting for PureScience shell bridge…'
+          }
+        />
+      </AppFrame>
+    )
+  }
+  return (
+    <AppFrame>
+      <AppShell settings={boot.settings} />
+    </AppFrame>
+  )
+}

package/template/src/bridge/platformBridge.ts CHANGED Viewed

@@ -1,31 +1,31 @@
-import { bridge } from '@puredesktop/puredesktop-ui-bridge/bridge/client'
-import { PLATFORM_BRIDGE_METHODS } from '@puredesktop/puredesktop-ui-bridge/bridge/methods'
-import { APP_SLUG } from '../constants'
-import type { AppSettings } from '../types'
-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 {}
-  }
-}
-export async function fetchAppSettings(): Promise<AppSettings> {
-  if (isStandaloneDevMode()) {
-    return readStandaloneSettings()
-  }
-  return bridge.call<AppSettings>(PLATFORM_BRIDGE_METHODS.SETTINGS_APP_GET, [
-    APP_SLUG,
-  ])
-}
+import { bridge } from '@puredesktop/puredesktop-ui-bridge/bridge/client'
+import { PLATFORM_BRIDGE_METHODS } from '@puredesktop/puredesktop-ui-bridge/bridge/methods'
+import { APP_SLUG } from '../constants'
+import type { AppSettings } from '../types'
+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 {}
+  }
+}
+export async function fetchAppSettings(): Promise<AppSettings> {
+  if (isStandaloneDevMode()) {
+    return readStandaloneSettings()
+  }
+  return bridge.call<AppSettings>(PLATFORM_BRIDGE_METHODS.SETTINGS_APP_GET, [
+    APP_SLUG,
+  ])
+}

package/template/src/components/AppShell.tsx CHANGED Viewed

@@ -1,31 +1,31 @@
-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`
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-  padding: 32px;
-  max-width: 720px;
-`
-export interface AppShellProps {
-  settings: AppSettings
-}
-export function AppShell({ settings }: AppShellProps): React.ReactElement {
-  return (
-    <Root>
-      <Heading level={1}>{{APP_TITLE}}</Heading>
-      <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}
-    </Root>
-  )
-}
+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`
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 32px;
+  max-width: 720px;
+`
+export interface AppShellProps {
+  settings: AppSettings
+}
+export function AppShell({ settings }: AppShellProps): React.ReactElement {
+  return (
+    <Root>
+      <Heading level={1}>{{APP_TITLE}}</Heading>
+      <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}
+    </Root>
+  )
+}

package/template/src/constants.ts CHANGED Viewed

	@@ -1 +1 @@
1	- export const APP_SLUG = '{{APP_SLUG}}'
1	+ export const APP_SLUG = '{{APP_SLUG}}'