@puredesktop/create-app 2.1.9 → 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,13 +15,16 @@ 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-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
+  --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
   npm create @puredesktop/app@latest my-tool -- --name "My Tool" --slug mytool --port 5310
 `)
 }
@@ -32,12 +32,14 @@ Examples:
 function parseArgs(argv) {
   const positional = []
   const options = {
-    name: '',
-    slug: '',
-    port: 5300,
-    manifestJsonFile: '',
-    agentsMdFile: '',
-  }
+    agentsMdFile: '',
+    allowExisting: false,
+    manifestJsonFile: '',
+    name: '',
+    port: 5300,
+    slug: '',
+    targetPath: '',
+  }
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i]
@@ -57,333 +59,43 @@ function parseArgs(argv) {
       options.port = Number(argv[++i])
       continue
     }
-    if (arg === '--manifest-json-file') {
-      options.manifestJsonFile = argv[++i] ?? ''
-      continue
-    }
-    if (arg === '--agents-md-file') {
-      options.agentsMdFile = argv[++i] ?? ''
-      continue
-    }
+    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-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 readStructuredManifestFile(path, port) {
-  const text = readUtf8File(path, '--manifest-json-file')
-  return readStructuredManifestText(text, port, '--manifest-json-file')
-}
-
-function readStructuredManifestText(text, port, label) {
-  let manifest
-  try {
-    manifest = JSON.parse(text)
-  } catch (error) {
-    console.error(`${label} must contain JSON: ${errorMessage(error)}`)
-    process.exit(1)
-  }
-  return normalizeStructuredManifest(manifest, port, label)
-}
-
-function normalizeStructuredManifest(manifest, port, label) {
-  if (!isPlainObject(manifest)) {
-    console.error(`${label} must contain 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 readStructuredAgentsMdFile(path) {
-  const text = readUtf8File(path, '--agents-md-file')
-  return readStructuredAgentsMdText(text, '--agents-md-file')
-}
-
-function readStructuredAgentsMdText(text, label) {
-  if (!text.trim()) {
-    console.error(`${label} must contain non-empty agents.md content`)
-    process.exit(1)
-  }
-  return text.endsWith('\n') ? text : `${text}\n`
-}
-
-function readUtf8File(path, label) {
-  if (typeof path !== 'string' || !path.trim()) {
-    console.error(`${label} requires a file path`)
-    process.exit(1)
-  }
-  try {
-    return readFileSync(resolve(path), 'utf8')
-  } catch (error) {
-    console.error(`${label} could not be read: ${errorMessage(error)}`)
-    process.exit(1)
-  }
-}
-
-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 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)
+  if (options.targetPath && positional.length > 0) {
+    throw new UsageError('Pass either [dir] or --target-path, not both')
   }
 
-  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)
+  return {
+    options,
+    targetDir: options.targetPath || positional[0] || 'puredesktop-app',
   }
 }
 
-const { targetDir, options } = parseArgs(process.argv.slice(2))
-const structuredManifest = options.manifestJsonFile
-  ? readStructuredManifestFile(options.manifestJsonFile, options.port)
-  : null
-const structuredAgentsMd = options.agentsMdFile
-  ? readStructuredAgentsMdFile(options.agentsMdFile)
-  : 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 a structured manifest is used')
-  process.exit(1)
-}
-if (structuredManifest && options.name && options.name !== structuredTitle) {
-  console.error('--name must match manifest.app.name when a structured manifest 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.
+`)
+}
+
+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,
+  })
 
-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.
-`)
+  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.9",
+  "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.