@puredesktop/create-app 1.0.0-beta.1

package/bin/create-puredesktop-app.mjs

@@ -0,0 +1,164 @@
+#!/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}
+
+  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.
+`)

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@puredesktop/create-app",
+  "version": "1.0.0-beta.1",
+  "description": "Scaffold a PureScience Desktop plugin app (Vite + bridge SDK)",
+  "type": "module",
+  "bin": {
+    "create-app": "./bin/create-puredesktop-app.mjs",
+    "create-puredesktop-app": "./bin/create-puredesktop-app.mjs"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/template/README.md

@@ -0,0 +1,30 @@
+# {{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.
+
+## Build & deploy
+
+```bash
+npm run build
+```
+
+Deploy the `dist/` folder to HTTPS, then register that URL in PureScience Desktop.
+
+## 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

package/template/gitignore.tpl

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

package/template/index.html

@@ -0,0 +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>

package/template/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "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

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "id": "{{PLUGIN_ID}}",
+  "name": "{{APP_TITLE}}",
+  "permissions": ["network", "settings"],
+  "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."
+  }
+}

package/template/src/App.tsx

@@ -0,0 +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>
+  )
+}

package/template/src/bridge/platformBridge.ts

@@ -0,0 +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,
+  ])
+}

package/template/src/components/AppShell.tsx

@@ -0,0 +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>
+  )
+}

package/template/src/constants.ts

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

package/template/src/hooks/useAppBoot.ts

@@ -0,0 +1,45 @@
+import { useEffect, useState } from 'react'
+import { fetchAppSettings } from '../bridge/platformBridge'
+import type { AppBootState } from '../types'
+
+interface UseAppBootResult {
+  boot: AppBootState | null
+  bootError: Error | null
+  booting: boolean
+}
+
+export function useAppBoot(ready: boolean): UseAppBootResult {
+  const [boot, setBoot] = useState<AppBootState | null>(null)
+  const [bootError, setBootError] = useState<Error | null>(null)
+  const [booting, setBooting] = useState(false)
+
+  useEffect(() => {
+    if (!ready) return
+
+    let cancelled = false
+
+    async function load() {
+      setBooting(true)
+      setBootError(null)
+      try {
+        const settings = await fetchAppSettings()
+        if (cancelled) return
+        setBoot({ settings })
+      } catch (error) {
+        if (cancelled) return
+        setBoot(null)
+        setBootError(error instanceof Error ? error : new Error(String(error)))
+      } finally {
+        if (!cancelled) setBooting(false)
+      }
+    }
+
+    void load()
+
+    return () => {
+      cancelled = true
+    }
+  }, [ready])
+
+  return { boot, bootError, booting }
+}

package/template/src/main.tsx

@@ -0,0 +1,9 @@
+import { createRoot } from 'react-dom/client'
+import { App } from './App'
+
+const root = document.getElementById('root')
+if (!root) {
+  throw new Error('Root element #root not found')
+}
+
+createRoot(root).render(<App />)

package/template/src/types.ts

@@ -0,0 +1,5 @@
+export type AppSettings = Record<string, unknown>
+
+export interface AppBootState {
+  settings: AppSettings
+}

package/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "vite-env.d.ts"]
+}

package/template/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/template/vite.config.js

@@ -0,0 +1,28 @@
+import react from '@vitejs/plugin-react-swc'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+
+/** Keep Vite port in sync with plugin.json entrypoint.url. */
+function devServerFromManifest(metaUrl) {
+  const appDir = dirname(fileURLToPath(metaUrl))
+  const manifest = JSON.parse(readFileSync(join(appDir, 'plugin.json'), 'utf8'))
+  const url = new URL(manifest.entrypoint.url)
+  return {
+    host: url.hostname,
+    port: Number(url.port),
+    strictPort: true,
+  }
+}
+
+export default defineConfig({
+  plugins: [
+    react({
+      plugins: [
+        ['@swc/plugin-styled-components', { displayName: true, fileName: true }],
+      ],
+    }),
+  ],
+  server: devServerFromManifest(import.meta.url),
+})