@puredesktop/create-app 2.1.5 → 2.1.6

package/bin/create-puredesktop-app.mjs

@@ -1,43 +1,43 @@
 #!/usr/bin/env node
 /**
- * Scaffold an external PureDesktop 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 { 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')
-
-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)
-  --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: '',
-  }
+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)
+  --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]
@@ -53,18 +53,18 @@ function parseArgs(argv) {
       options.slug = argv[++i] ?? ''
       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 === '--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()
@@ -89,223 +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 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) {
+}
+
+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, '')
@@ -319,30 +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 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)
+}
+
+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}`)
@@ -354,47 +354,47 @@ mkdirSync(outDir, { recursive: true })
 const vars = {
   APP_TITLE: title,
   APP_SLUG: slug,
-  APP_NAME: slug,
-  PLUGIN_ID: pluginId,
-  APP_PORT: String(options.port),
-  PACKAGE_NAME: `@puredesktop/${slug}`,
-}
-
-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
-  npm run dev
-
-Before shipping:
+  APP_NAME: slug,
+  PLUGIN_ID: pluginId,
+  APP_PORT: String(options.port),
+  PACKAGE_NAME: `@puredesktop/${slug}`,
+}
+
+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
+  npm run dev
+
+Before shipping:
   npm run typecheck
-  npm run build
-  npm run puredesktop:check
+  npm run build
+  npm run puredesktop:check
 
-Register in PureDesktop (File -> Register App...) with:
+Register in PureDesktop (File -> Register App...) with:
   entrypoint: http://localhost:${options.port}
-  permissions: network, settings, agents
+  permissions: network, settings, agents
 
 Build your UI in src/components/AppShell.tsx.
 `)