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

package/bin/create-puredesktop-app.mjs

@@ -1,55 +1,43 @@
 #!/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 = '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 }
-}
+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]
 
-function parseArgs(argv) {
-  const positional = []
-  const options = {
-    name: '',
-    slug: '',
-    port: 5300,
-    ui: `${DEFAULT_UI}@${DEFAULT_UI_VERSION}`,
-  }
+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)
+  --manifest-json-base64 <base64>
+                     Structured plugin.json manifest draft for app-builder use
+  --agents-md-base64 <base64>
+                     Structured agents.md content for app-builder use
+
+Examples:
+  npm create @puredesktop/app@latest my-tool
+  npm create @puredesktop/app@latest my-tool -- --name "My Tool" --slug mytool --port 5310
+`)
+}
+
+function parseArgs(argv) {
+  const positional = []
+  const options = {
+    name: '',
+    slug: '',
+    port: 5300,
+    manifestJsonBase64: '',
+    agentsMdBase64: '',
+  }
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i]
@@ -65,14 +53,18 @@ 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
-      continue
-    }
+    if (arg === '--port') {
+      options.port = Number(argv[++i])
+      continue
+    }
+    if (arg === '--manifest-json-base64') {
+      options.manifestJsonBase64 = argv[++i] ?? ''
+      continue
+    }
+    if (arg === '--agents-md-base64') {
+      options.agentsMdBase64 = argv[++i] ?? ''
+      continue
+    }
     if (arg.startsWith('-')) {
       console.error(`Unknown option: ${arg}`)
       usage()
@@ -97,15 +89,223 @@ function slugify(value) {
     .replace(/^-+|-+$/g, '')
 }
 
-function titleCaseFromSlug(slug) {
+function titleCaseFromSlug(slug) {
   return slug
     .split('-')
     .filter(Boolean)
     .map(part => part.charAt(0).toUpperCase() + part.slice(1))
     .join(' ')
-}
-
-function copyTemplate(srcDir, destDir, vars) {
+}
+
+function decodeBase64Utf8(value, label) {
+  if (!isBase64(value)) {
+    console.error(`${label} must be valid base64`)
+    process.exit(1)
+  }
+  try {
+    return Buffer.from(value, 'base64').toString('utf8')
+  } catch (error) {
+    console.error(`${label} must be valid base64: ${errorMessage(error)}`)
+    process.exit(1)
+  }
+}
+
+function readStructuredManifest(value, port) {
+  const text = decodeBase64Utf8(value, '--manifest-json-base64')
+  let manifest
+  try {
+    manifest = JSON.parse(text)
+  } catch (error) {
+    console.error(`--manifest-json-base64 must decode to JSON: ${errorMessage(error)}`)
+    process.exit(1)
+  }
+  return normalizeStructuredManifest(manifest, port)
+}
+
+function normalizeStructuredManifest(manifest, port) {
+  if (!isPlainObject(manifest)) {
+    console.error('--manifest-json-base64 must decode to a manifest object')
+    process.exit(1)
+  }
+  if (manifest.schemaVersion !== 1) {
+    console.error('manifest.schemaVersion must be 1')
+    process.exit(1)
+  }
+  const id = requiredString(manifest.id, 'manifest.id')
+  const name = requiredString(manifest.name, 'manifest.name')
+  if (!isPlainObject(manifest.app)) {
+    console.error('manifest.app is required')
+    process.exit(1)
+  }
+  const appSlug = requiredString(manifest.app.slug, 'manifest.app.slug')
+  const appName = requiredString(manifest.app.name, 'manifest.app.name')
+  if (slugify(appSlug) !== appSlug) {
+    console.error('manifest.app.slug must use lowercase letters, numbers, and hyphens')
+    process.exit(1)
+  }
+
+  return stripUndefinedProperties({
+    ...manifest,
+    id,
+    name,
+    entrypoint: {
+      kind: 'dev-url',
+      url: `http://localhost:${port}`,
+    },
+    app: stripUndefinedProperties({
+      ...manifest.app,
+      slug: appSlug,
+      name: appName,
+      entrypoint: undefined,
+    }),
+  })
+}
+
+function readStructuredAgentsMd(value) {
+  const text = decodeBase64Utf8(value, '--agents-md-base64')
+  if (!text.trim()) {
+    console.error('--agents-md-base64 must decode to non-empty agents.md content')
+    process.exit(1)
+  }
+  return text.endsWith('\n') ? text : `${text}\n`
+}
+
+function requiredString(value, label) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (!text) {
+    console.error(`${label} is required`)
+    process.exit(1)
+  }
+  return text
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isBase64(value) {
+  if (typeof value !== 'string' || !value.trim()) return false
+  const normalized = value.trim()
+  if (!/^[A-Za-z0-9+/]+={0,2}$/u.test(normalized)) return false
+  if (normalized.length % 4 !== 0) return false
+  return Buffer.from(normalized, 'base64').toString('base64') === normalized
+}
+
+function stripUndefinedProperties(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined),
+  )
+}
+
+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)
     const destName = entry.name.replace(/\.tpl$/u, '')
@@ -119,15 +319,30 @@ function copyTemplate(srcDir, destDir, vars) {
     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)
+}
+
+const { targetDir, options } = parseArgs(process.argv.slice(2))
+const structuredManifest = options.manifestJsonBase64
+  ? readStructuredManifest(options.manifestJsonBase64, options.port)
+  : null
+const structuredAgentsMd = options.agentsMdBase64
+  ? readStructuredAgentsMd(options.agentsMdBase64)
+  : null
+const dirName = targetDir
+const structuredSlug = structuredManifest?.app.slug ?? ''
+const structuredTitle = structuredManifest?.app.name ?? ''
+if (structuredManifest && options.slug && options.slug !== structuredSlug) {
+  console.error('--slug must match manifest.app.slug when --manifest-json-base64 is used')
+  process.exit(1)
+}
+if (structuredManifest && options.name && options.name !== structuredTitle) {
+  console.error('--name must match manifest.app.name when --manifest-json-base64 is used')
+  process.exit(1)
+}
+const slug = structuredSlug || options.slug || slugify(dirName) || 'my-app'
+const title = structuredTitle || options.name || titleCaseFromSlug(slug) || 'My App'
+const pluginId = structuredManifest?.id ?? slug
+const outDir = resolve(process.cwd(), dirName)
 
 if (existsSync(outDir)) {
   console.error(`Target already exists: ${outDir}`)
@@ -139,18 +354,34 @@ 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)
-
-console.log(`
-Created ${title} at ${outDir}
+copyTemplate(TEMPLATE_DIR, outDir, vars)
+
+if (structuredManifest) {
+  writeFileSync(
+    join(outDir, 'plugin.json'),
+    `${JSON.stringify(structuredManifest, null, 2)}\n`,
+  )
+}
+
+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}
 
   cd ${dirName}
   npm install
@@ -161,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": "1.0.0-beta.2",
-  "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",