@puredesktop/create-app 1.0.0-beta.1 → 2.1.0

package/bin/create-puredesktop-app.mjs

@@ -1,164 +1,314 @@
 #!/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]
-
+/**
+ * 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 = '2.1.0'
+
+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})
+  --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 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 = {
+`)
+}
+
+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}`,
+    manifestJsonBase64: '',
+    agentsMdBase64: '',
   }
-
-  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] ?? ''
+
+  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 === '--port') {
-      options.port = Number(argv[++i])
+    if (arg === '--manifest-json-base64') {
+      options.manifestJsonBase64 = argv[++i] ?? ''
       continue
     }
-    if (arg === '--ui') {
-      options.ui = argv[++i] ?? options.ui
+    if (arg === '--agents-md-base64') {
+      options.agentsMdBase64 = argv[++i] ?? ''
       continue
     }
-    if (arg.startsWith('-')) {
-      console.error(`Unknown option: ${arg}`)
-      usage()
-      process.exit(1)
-    }
-    positional.push(arg)
+    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 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)
   }
 
-  if (!Number.isInteger(options.port) || options.port <= 0) {
-    console.error('--port must be a positive integer')
+  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`
+}
 
-  return { targetDir: positional[0] ?? 'puredesktop-app', options }
+function requiredString(value, label) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (!text) {
+    console.error(`${label} is required`)
+    process.exit(1)
+  }
+  return text
 }
 
-function slugify(value) {
-  return value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 }
 
-function titleCaseFromSlug(slug) {
-  return slug
-    .split('-')
-    .filter(Boolean)
-    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-    .join(' ')
+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 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)
-  }
+  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 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}`)
+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),
+  UI_PACKAGE_NAME: uiDep.name,
+  UI_PACKAGE_VERSION: uiDep.version,
+  PACKAGE_NAME: `@puredesktop/${slug}`,
+}
+
+copyTemplate(TEMPLATE_DIR, outDir, vars)
 
-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}`,
+if (structuredManifest) {
+  writeFileSync(
+    join(outDir, 'plugin.json'),
+    `${JSON.stringify(structuredManifest, null, 2)}\n`,
+  )
 }
 
-copyTemplate(TEMPLATE_DIR, outDir, vars)
+if (structuredAgentsMd) {
+  writeFileSync(join(outDir, 'agents.md'), structuredAgentsMd)
+}
 
 console.log(`
-Created ${title} at ${outDir}
-
+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.
-`)
+Before shipping:
+  npm run typecheck
+  npm run build
+  npm run puredesktop:check
+
+Register in PureScience Desktop (File → Register App…) with:
+  entrypoint: http://localhost:${options.port}
+  permissions: network, settings, agents
+
+Build your UI in src/components/AppShell.tsx.
+`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puredesktop/create-app",
-  "version": "1.0.0-beta.1",
+  "version": "2.1.0",
   "description": "Scaffold a PureScience Desktop plugin app (Vite + bridge SDK)",
   "type": "module",
   "bin": {