@puredesktop/create-app 2.1.8 → 2.1.10

package/bin/create-puredesktop-app.mjs

@@ -4,12 +4,9 @@
  *
  * Published as @puredesktop/create-app -> npm create @puredesktop/app@latest
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { scaffoldAppFromFiles } from '../lib/scaffold.mjs'
 
-const __dirname = dirname(fileURLToPath(import.meta.url))
-const TEMPLATE_DIR = join(__dirname, '..', 'template')
+class UsageError extends Error {}
 
 function usage() {
   console.log(`Usage: npm create @puredesktop/app@latest [dir] [options]
@@ -18,10 +15,13 @@ 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
+  --target-path <path>
+                     Scaffold into this path instead of [dir]
+  --allow-existing   Allow target path to already exist
+  --manifest-json-file <path>
+                     Read structured plugin.json manifest draft from a file
+  --agents-md-file <path>
+                     Read structured agents.md content from a file
 
 Examples:
   npm create @puredesktop/app@latest my-tool
@@ -32,11 +32,13 @@ Examples:
 function parseArgs(argv) {
   const positional = []
   const options = {
+    agentsMdFile: '',
+    allowExisting: false,
+    manifestJsonFile: '',
     name: '',
-    slug: '',
     port: 5300,
-    manifestJsonBase64: '',
-    agentsMdBase64: '',
+    slug: '',
+    targetPath: '',
   }
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -57,333 +59,43 @@ function parseArgs(argv) {
       options.port = Number(argv[++i])
       continue
     }
-    if (arg === '--manifest-json-base64') {
-      options.manifestJsonBase64 = argv[++i] ?? ''
+    if (arg === '--target-path') {
+      options.targetPath = argv[++i] ?? ''
+      continue
+    }
+    if (arg === '--allow-existing') {
+      options.allowExisting = true
+      continue
+    }
+    if (arg === '--manifest-json-file') {
+      options.manifestJsonFile = argv[++i] ?? ''
       continue
     }
-    if (arg === '--agents-md-base64') {
-      options.agentsMdBase64 = argv[++i] ?? ''
+    if (arg === '--agents-md-file') {
+      options.agentsMdFile = argv[++i] ?? ''
       continue
     }
     if (arg.startsWith('-')) {
-      console.error(`Unknown option: ${arg}`)
-      usage()
-      process.exit(1)
+      throw new UsageError(`Unknown option: ${arg}`)
     }
     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 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)
+  if (options.targetPath && positional.length > 0) {
+    throw new UsageError('Pass either [dir] or --target-path, not both')
   }
-  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)
+  return {
+    options,
+    targetDir: options.targetPath || positional[0] || 'puredesktop-app',
   }
 }
 
-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, '')
-    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 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}`)
-  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),
-  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(`
+function printSuccess({ outDir, port, targetDir, title }) {
+  console.log(`
 Created ${title} at ${outDir}
 
-  cd ${dirName}
+  cd ${targetDir}
   npm install
   npm run dev
 
@@ -393,9 +105,29 @@ Before shipping:
   npm run puredesktop:check
 
 Register in PureDesktop (File -> Register App...) with:
-  entrypoint: http://localhost:${options.port}
-  permissions: network, settings, filesystem, agents
+  entrypoint: http://localhost:${port}
+  permissions: network, settings, filesystem, agents
 
-Build product surfaces in src/components, workflow hooks in src/hooks, and domain logic in src/lib.
-Keep src/App.tsx and src/components/AppShell.tsx thin.
-`)
+Build product surfaces in src/components, workflow hooks in src/hooks, and domain logic in src/lib.
+Keep src/App.tsx and src/components/AppShell.tsx thin.
+`)
+}
+
+try {
+  const { options, targetDir } = parseArgs(process.argv.slice(2))
+  const result = scaffoldAppFromFiles({
+    agentsMdFile: options.agentsMdFile,
+    allowExisting: options.allowExisting,
+    manifestJsonFile: options.manifestJsonFile,
+    name: options.name,
+    port: options.port,
+    slug: options.slug,
+    targetDir,
+  })
+
+  printSuccess(result)
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error))
+  if (error instanceof UsageError) usage()
+  process.exit(1)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puredesktop/create-app",
-  "version": "2.1.8",
+  "version": "2.1.10",
   "description": "Scaffold a PureDesktop plugin app (Vite + bridge SDK)",
   "type": "module",
   "bin": {
@@ -9,10 +9,11 @@
   },
   "files": [
     "bin",
+    "lib",
     "template"
   ],
   "publishConfig": {
-    "access": "restricted",
+    "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "engines": {

package/template/README.md

@@ -36,9 +36,9 @@ and declared app agent tools.
 - `src/App.tsx`: bridge and boot gates wrapped in `AppFrame`.
 - `src/bridge/platformBridge.ts`: local app bridge exports.
 - `src/hooks/useAppBoot.ts`: boot data loading after bridge readiness.
-- `src/components/AppShell.tsx`: thin app-owned composition root.
-- `src/components/StarterWorkspace.tsx`: temporary starter screen to replace
-  when the first product surface exists.
+- `src/components/AppShell.tsx`: thin app-owned composition root.
+- `src/components/StarterWorkspace.tsx`: temporary starter screen to replace
+  when the first product surface exists.
 - `docs/`: builder-facing app, bridge, agent, and tool-handler docs.
 
 ## Builder Docs

package/template/docs/README.md

@@ -13,10 +13,11 @@ Read these in order when building or repairing an app:
 2. [Plugin manifest](./plugin-manifest.md)
 3. [Bridge helpers](./bridge/README.md)
 4. [App agent](./agent.md)
-5. [Tool handlers](./tool-handlers.md)
+5. [Tool handlers](./tool-handlers.md)
 6. [Adding an app agent tool](./howtos/adding-agent-tool.md)
-7. [UI and components](./ui-and-components.md)
-8. [Theme CSS variables](./theme-vars.md)
+7. [UI and components](./ui-and-components.md)
+8. [Using the document editor](./howtos/using-document-editor.md)
+9. [Theme CSS variables](./theme-vars.md)
 
 Key files in this scaffold:
 
@@ -26,11 +27,11 @@ Key files in this scaffold:
 - `src/App.tsx`: bridge readiness, boot loading, and `AppFrame` wrapper.
 - `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`: thin app-owned composition root.
-- `src/components/StarterWorkspace.tsx`: temporary starter screen to replace
-  when the first product surface exists.
-- `src/lib/starterWorkspace.ts`: starter data/helper example showing where
-  reusable non-rendering logic belongs.
+- `src/components/AppShell.tsx`: thin app-owned composition root.
+- `src/components/StarterWorkspace.tsx`: temporary starter screen to replace
+  when the first product surface exists.
+- `src/lib/starterWorkspace.ts`: starter data/helper example showing where
+  reusable non-rendering logic belongs.
 - `scripts/validate-puredesktop-app.mjs`: registration and tool scaffold check.
 
 Use `npm run puredesktop:check` after `npm run build` before registration.