@puredesktop/create-app 2.1.7 → 2.1.9

package/bin/create-puredesktop-app.mjs

@@ -18,13 +18,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
-
-Examples:
-  npm create @puredesktop/app@latest my-tool
+  --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,12 @@ Examples:
 function parseArgs(argv) {
   const positional = []
   const options = {
-    name: '',
-    slug: '',
-    port: 5300,
-    manifestJsonBase64: '',
-    agentsMdBase64: '',
-  }
+    name: '',
+    slug: '',
+    port: 5300,
+    manifestJsonFile: '',
+    agentsMdFile: '',
+  }
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i]
@@ -57,14 +57,14 @@ function parseArgs(argv) {
       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 === '--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()
@@ -97,36 +97,27 @@ function titleCaseFromSlug(slug) {
     .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)
-  }
+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)
@@ -161,14 +152,31 @@ function normalizeStructuredManifest(manifest, port) {
   })
 }
 
-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 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() : ''
@@ -183,15 +191,7 @@ 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) {
+function stripUndefinedProperties(value) {
   return Object.fromEntries(
     Object.entries(value).filter(([, entry]) => entry !== undefined),
   )
@@ -321,24 +321,24 @@ function copyTemplate(srcDir, destDir, vars) {
   }
 }
 
-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 { 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 --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 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
@@ -394,7 +394,8 @@ Before shipping:
 
 Register in PureDesktop (File -> Register App...) with:
   entrypoint: http://localhost:${options.port}
-  permissions: network, settings, agents
+  permissions: network, settings, filesystem, agents
 
-Build your UI in src/components/AppShell.tsx.
-`)
+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.
+`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puredesktop/create-app",
-  "version": "2.1.7",
+  "version": "2.1.9",
   "description": "Scaffold a PureDesktop plugin app (Vite + bridge SDK)",
   "type": "module",
   "bin": {

package/template/README.md

@@ -36,7 +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`: first app-owned UI surface.
+- `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

@@ -14,8 +14,9 @@ Read these in order when building or repairing an app:
 3. [Bridge helpers](./bridge/README.md)
 4. [App agent](./agent.md)
 5. [Tool handlers](./tool-handlers.md)
-6. [UI and components](./ui-and-components.md)
-7. [Theme CSS variables](./theme-vars.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)
 
 Key files in this scaffold:
 
@@ -25,7 +26,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`: first app-owned UI surface.
+- `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.

package/template/docs/howtos/adding-agent-tool.md

@@ -0,0 +1,106 @@
+# Adding An App Agent Tool
+
+App agent tools are a three-file contract. A tool is not available until the
+manifest, registration catalog, and runtime handler all contain the same name.
+
+## Edit Sequence
+
+1. Add the tool declaration to `plugin.json` under `app.agents.tools`.
+   Include a clear `description`, an `inputSchema`, and `requiresApproval`.
+   Set `requiresApproval: true` for writes that mutate app data, files,
+   external services, or broad app state.
+
+2. Add the same tool name to `src/agents/catalog.ts`.
+   `APP_AGENT_TOOL_NAMES` is the list registered with the shell at runtime. Keep
+   it in the same order as `plugin.json` `app.agents.tools`.
+
+3. Add the same tool name to `src/agents/handlers/index.ts`.
+   Implement the handler with app-owned state or domain helpers. Return compact
+   JSON for reads and a short result for writes. Return
+   `agentToolErrorContent(message)` for invalid input the assistant can correct.
+
+4. Update `agents.md` when the app assistant needs to know when or how to use
+   the tool.
+
+5. Run checks:
+
+   ```bash
+   npm run typecheck
+   npm run build
+   npm run puredesktop:check
+   ```
+
+During dev mode, `npm run typecheck` is enough to catch TypeScript errors, but
+`npm run puredesktop:check` only proves the final package after `npm run build`
+refreshes `dist`.
+
+## Existing Tool Scaffold
+
+For apps that already have tools, these files already exist:
+
+```text
+src/
+  agents/
+    catalog.ts
+    handlers/
+      index.ts
+  hooks/
+    useAppAgentTools.ts
+```
+
+Only edit `plugin.json`, `src/agents/catalog.ts`,
+`src/agents/handlers/index.ts`, and optionally `agents.md`.
+
+## First Tool In An App
+
+If `src/agents/` does not exist, create the scaffold:
+
+```ts
+// src/agents/catalog.ts
+export const APP_AGENT_TOOL_NAMES = ['listItems'] as const
+
+export const APP_AGENT_LOG_LABEL = '{{APP_SLUG}}'
+```
+
+```ts
+// src/agents/handlers/index.ts
+import { agentToolErrorContent } from '@puredesktop/puredesktop-ui-bridge/bridge/agentToolHelpers'
+import type { AgentToolHandler } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
+
+const listItems: AgentToolHandler = async () => {
+  return agentToolErrorContent('listItems is not implemented yet.')
+}
+
+export const appAgentHandlers = {
+  listItems,
+} satisfies Record<string, AgentToolHandler>
+```
+
+```ts
+// src/hooks/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,
+  })
+}
+```
+
+Then wire the hook in `src/App.tsx` immediately after `usePlatformBridge()`:
+
+```ts
+const { error: bridgeError, ready } = usePlatformBridge()
+useAppAgentTools(ready)
+```
+
+## Common Failure
+
+Do not update only `plugin.json` and the handler. If `APP_AGENT_TOOL_NAMES`
+does not include the new tool, the iframe never registers it with the shell. The
+assistant will see a declared tool that the running app cannot handle.

package/template/docs/howtos/persisting-app-state.md

@@ -0,0 +1,242 @@
+# Persisting App State
+
+PureDesktop apps persist non-document state through UI bridge helpers. This
+state is app-owned: the app defines the TypeScript type, default value, parser,
+and update commands.
+
+## State Surfaces
+
+| State | Helper | Permission |
+| --- | --- | --- |
+| Small app preferences | `usePlatformAppSettings` | `settings` |
+| Internal JSON records | `usePlatformJsonStore` | `filesystem` |
+
+Use document lifecycle APIs for user-visible documents, drafts, recents, rename,
+duplicate, and open/save workflows.
+
+## Generated App Wiring
+
+The generated app already has the bridge readiness boundary:
+
+- `src/App.tsx` calls `usePlatformBridge()` and receives `ready`.
+- `src/App.tsx` calls `useAppBoot(ready || standaloneDev)`.
+- `src/hooks/useAppBoot.ts` loads startup settings through the app bridge.
+- `src/components/AppShell.tsx` receives boot data as props.
+
+Use that structure instead of adding bridge calls inside components.
+
+When state is read once at startup, `useAppBoot` can load it and pass it down.
+When state can change while the app is open, create a dedicated hook in
+`src/hooks/` that calls the platform helper and exposes typed commands.
+
+## Add Editable App Settings
+
+1. Create or reuse the domain folder under `src/lib/<domain>/`.
+2. Define the settings type, default value, and parser in that domain folder.
+3. Create `src/hooks/use<Domain>Settings.ts`.
+4. Inside that hook, call `usePlatformAppSettings`.
+5. Pass `APP_SLUG` and the bridge `ready` value to the hook.
+6. Return typed settings plus app-specific command functions.
+7. Components call those command functions; they do not build settings patches.
+
+Hook shape:
+
+```text
+use real domain settings type
+call usePlatformAppSettings with APP_SLUG, ready, default settings, parser
+return settings, loading, error
+return field-specific commands that call patchSettings
+```
+
+Field-specific commands own the settings patch. Components call the command; they
+do not assemble the patch object.
+
+## Add An Internal JSON Store
+
+1. Add `filesystem` to `plugin.json`.
+2. Create or reuse the domain folder under `src/lib/<domain>/`.
+3. Define the store type, empty value, parser, and pure update helpers in that
+   domain folder.
+4. Create `src/hooks/use<Domain>Store.ts`.
+5. Inside that hook, call `usePlatformJsonStore`.
+6. Use a file name that includes `APP_SLUG` and the real persisted record name.
+7. Return typed store state plus app-specific command functions.
+8. Components call those command functions; they do not edit raw JSON objects.
+
+Hook shape:
+
+```text
+use real domain store type
+call usePlatformJsonStore with APP_SLUG, ready, file name, empty store, parser
+return store, loading, saving, error
+return domain commands that call updateValue with pure update functions
+```
+
+Domain commands own the store update. Components call the command; they do not
+edit raw JSON objects. Store update functions must return new store objects.
+
+## App Settings
+
+Import:
+
+```ts
+import { usePlatformAppSettings } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAppSettings'
+```
+
+Use for small app preferences such as current mode, sorting, filtering, and
+lightweight options.
+
+Options:
+
+```ts
+{
+  appSlug: string | null
+  enabled?: boolean
+  initialSettings?: TSettings
+  parse?: (value: Record<string, unknown>) => TSettings
+}
+```
+
+Returns:
+
+```ts
+{
+  settings: TSettings
+  loading: boolean
+  error: Error | null
+  patchSettings: (patch: Record<string, unknown>) => Promise<TSettings>
+  reload: () => void
+}
+```
+
+Behavior:
+
+- loads through `settings.app.get`;
+- saves through `settings.app.update`;
+- `patchSettings` shallow-merges the patch in shell preferences;
+- the shell stores app settings under the current app slug;
+- the app parser converts persisted `Record<string, unknown>` into the app's
+  typed settings object.
+
+App ownership:
+
+- keep the settings type in app code;
+- keep defaults and parsing in app code;
+- expose typed settings and typed commands to components;
+- use app settings for preferences, not large record collections.
+
+## JSON Store
+
+Import:
+
+```ts
+import { usePlatformJsonStore } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformJsonStore'
+```
+
+Use for internal app records that are larger than settings and are not
+user-visible documents.
+
+Options:
+
+```ts
+{
+  appSlug: string | null
+  fileName: `${string}.json` | null
+  initialValue: TValue
+  enabled?: boolean
+  parse?: (value: unknown) => TValue
+}
+```
+
+Returns:
+
+```ts
+{
+  value: TValue
+  path: string | null
+  loading: boolean
+  saving: boolean
+  error: Error | null
+  saveValue: (next: TValue) => Promise<TValue>
+  updateValue: (updater: (current: TValue) => TValue) => Promise<TValue>
+  reload: () => void
+}
+```
+
+Behavior:
+
+- loads through `storage.readJson`;
+- saves through `storage.writeJson`;
+- missing files load as `initialValue`;
+- saved values replace the full JSON value;
+- `updateValue` queues writes and applies each updater to the latest in-memory
+  value;
+- `fileName` must be a single `.json` file name;
+- the JSON file is stored in the shell-managed appdata folder.
+
+App ownership:
+
+- include `filesystem` in `plugin.json`;
+- keep the store type in app code;
+- keep defaults, parsing, and pure update functions in app code;
+- use an app-prefixed file name with the real persisted record name;
+- expose typed state and typed commands to components;
+- never mutate the current store object in place.
+
+## File Shape
+
+Use one `src/lib/<domain>/` folder per persisted domain. Do not put types,
+defaults, parsing, pure updates, platform hooks, and UI in one file.
+
+```text
+src/
+  hooks/
+    use<Domain>Settings.ts
+    use<Domain>Store.ts
+  lib/
+    <domain>/
+      types.ts
+      defaults.ts
+      parse.ts
+      updates.ts
+      index.ts
+  components/
+```
+
+Responsibilities:
+
+- `types.ts` exports the persisted domain types.
+- `defaults.ts` exports default settings or empty store values.
+- `parse.ts` converts unknown persisted values into valid domain state.
+- `updates.ts` contains pure functions that return new state objects.
+- `index.ts` re-exports the domain pieces used outside the folder.
+- `src/hooks/use<Domain>Settings.ts` calls `usePlatformAppSettings`.
+- `src/hooks/use<Domain>Store.ts` calls `usePlatformJsonStore`.
+- components import the app-owned hooks and render state.
+
+Split a file when it starts owning more than one responsibility. The hook should
+not define the domain model. Components should not parse persisted data. Pure
+update functions should not call platform helpers.
+
+## Verification
+
+Run:
+
+```bash
+npm run typecheck
+npm run build
+npm run puredesktop:check
+```
+
+Source checks:
+
+- app settings state has a domain settings type, default value, parser, and
+  hook;
+- JSON store state has a domain store type, empty value, parser, pure update
+  helpers, and hook;
+- components import the app-owned hooks instead of platform persistence helpers;
+- `usePlatformJsonStore` is only imported from app-owned hooks;
+- apps using `usePlatformJsonStore` include `filesystem` in `plugin.json`;
+- JSON store file names include `APP_SLUG` and the real persisted record name;
+- JSON store update functions return new objects instead of mutating existing
+  state.

package/template/docs/plugin-manifest.md

@@ -10,7 +10,7 @@ agent tools.
   "schemaVersion": 1,
   "id": "{{PLUGIN_ID}}",
   "name": "{{APP_TITLE}}",
-  "permissions": ["network", "settings", "agents"],
+  "permissions": ["network", "settings", "filesystem", "agents"],
   "entrypoint": {
     "kind": "dev-url",
     "url": "http://localhost:{{APP_PORT}}"