@owdproject/core 3.3.0 → 3.4.0

package/kit/authoring.ts

@@ -0,0 +1,340 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  defineNuxtModule,
+  installModule,
+  type NuxtModule,
+} from '@nuxt/kit'
+import type { Nuxt } from '@nuxt/schema'
+import { defu } from 'defu'
+
+/** Root `desktop.config.ts` helper — keep this file free of `import.meta` for jiti. */
+export function defineDesktopConfig(config: DesktopConfig) {
+  return config
+}
+
+/**
+ * Runtime validation for the object exported from `desktop.config.ts`
+ * (or legacy `owd.config.ts`).
+ */
+export function assertValidDesktopUserConfig(
+  config: unknown,
+  configFile = 'desktop.config.ts',
+): void {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(
+      `[@owdproject/core] ${configFile} must default-export a non-array object from defineDesktopConfig({ ... }).`,
+    )
+  }
+
+  const c = config as Record<string, unknown>
+
+  if (c.theme != null && typeof c.theme !== 'string') {
+    throw new Error(
+      `[@owdproject/core] ${configFile}: \`theme\` must be a string (npm package name of the theme module).`,
+    )
+  }
+
+  if (c.apps !== undefined) {
+    if (
+      !Array.isArray(c.apps) ||
+      !(c.apps as unknown[]).every((item) => typeof item === 'string')
+    ) {
+      throw new Error(
+        `[@owdproject/core] ${configFile}: \`apps\` must be an array of strings (Nuxt module package names).`,
+      )
+    }
+  }
+
+  if (c.modules !== undefined) {
+    if (
+      !Array.isArray(c.modules) ||
+      !(c.modules as unknown[]).every((item) => typeof item === 'string')
+    ) {
+      throw new Error(
+        `[@owdproject/core] ${configFile}: \`modules\` must be an array of strings (Nuxt module package names).`,
+      )
+    }
+  }
+}
+
+export const DESKTOP_CONFIG_FILENAME = 'desktop.config.ts'
+export const LEGACY_DESKTOP_CONFIG_FILENAME = 'owd.config.ts'
+
+export const LEGACY_CONFIG_DEPRECATION =
+  '[@owdproject/core] owd.config.ts is deprecated and kept only for backward compatibility; rename to desktop.config.ts (required from @owdproject/core 3.2).'
+
+export type ResolvedDesktopConfigPath = {
+  path: string
+  file: string
+  legacy: boolean
+}
+
+export function resolveDesktopConfigPath(
+  rootDir: string,
+): ResolvedDesktopConfigPath | null {
+  const desktopPath = join(rootDir, DESKTOP_CONFIG_FILENAME)
+  const legacyPath = join(rootDir, LEGACY_DESKTOP_CONFIG_FILENAME)
+  const hasDesktop = existsSync(desktopPath)
+  const hasLegacy = existsSync(legacyPath)
+
+  if (hasDesktop && hasLegacy) {
+    console.warn(
+      '[@owdproject/core] Both desktop.config.ts and owd.config.ts exist; using desktop.config.ts. Remove owd.config.ts.',
+    )
+    return { path: desktopPath, file: DESKTOP_CONFIG_FILENAME, legacy: false }
+  }
+
+  if (hasDesktop) {
+    return { path: desktopPath, file: DESKTOP_CONFIG_FILENAME, legacy: false }
+  }
+
+  if (hasLegacy) {
+    return {
+      path: legacyPath,
+      file: LEGACY_DESKTOP_CONFIG_FILENAME,
+      legacy: true,
+    }
+  }
+
+  return null
+}
+
+export function warnLegacyDesktopConfig(
+  resolved: ResolvedDesktopConfigPath | null | undefined,
+): void {
+  if (resolved?.legacy) {
+    console.warn(LEGACY_CONFIG_DEPRECATION)
+  }
+}
+
+/** Path used when creating or updating config from the CLI (always the new filename). */
+export function desktopConfigWritePath(desktopDir: string): string {
+  return join(desktopDir, DESKTOP_CONFIG_FILENAME)
+}
+
+/** Nuxt top-level option names — warn if present in desktop.config (likely misconfiguration). */
+const NUXT_OPTION_KEYS = new Set([
+  'ssr',
+  'devtools',
+  'vite',
+  'nitro',
+  'runtimeConfig',
+  'app',
+  'appConfig',
+  'css',
+  'plugins',
+  'hooks',
+  'extends',
+  'compatibilityDate',
+  'experimental',
+  'future',
+  'i18n',
+  'tailwindcss',
+  'primevue',
+])
+
+/**
+ * Warn when desktop.config.ts contains keys that look like Nuxt options.
+ * Extension keys (fs, terminal, custom app namespaces) are intentionally not validated here.
+ */
+export function warnDesktopConfigKeys(
+  config: Record<string, unknown>,
+  configFile = 'desktop.config.ts',
+): void {
+  for (const key of Object.keys(config)) {
+    if (NUXT_OPTION_KEYS.has(key)) {
+      console.warn(
+        `[@owdproject/core] ${configFile}: key "${key}" looks like a Nuxt option and is ignored for _nuxt.options. Move it to nuxt.config.ts; shell values belong under defineDesktopConfig({ systemBar, workspaces, ... }).`,
+      )
+    }
+  }
+}
+
+/**
+ * Writes a resolved extension namespace to `runtimeConfig.public.desktop[configKey]`.
+ * Used by {@link defineDesktopModule} after Nuxt merges inline options with module defaults.
+ */
+export function setDesktopExtensionConfig(
+  nuxt: Nuxt,
+  configKey: string,
+  resolved: Record<string, unknown>,
+): void {
+  const pub = (nuxt.options.runtimeConfig.public ??= {}) as {
+    desktop?: Record<string, unknown>
+  }
+  const desktop = (pub.desktop ??= {})
+  desktop[configKey] = resolved
+}
+
+/**
+ * Merges theme or module defaults into an extension namespace on `public.desktop`.
+ * User values from desktop.config win over `partial` (defu: partial fills undefined only).
+ */
+export function mergeDesktopExtensionConfig(
+  nuxt: Nuxt,
+  configKey: string,
+  partial: Record<string, unknown>,
+): void {
+  const pub = (nuxt.options.runtimeConfig.public ??= {}) as {
+    desktop?: Record<string, unknown>
+  }
+  const desktop = (pub.desktop ??= {})
+  const existing = desktop[configKey]
+  const base =
+    existing && typeof existing === 'object' && !Array.isArray(existing)
+      ? (existing as Record<string, unknown>)
+      : {}
+  desktop[configKey] = defu(partial, base)
+}
+
+type ModuleLike = {
+  meta?: { configKey?: string }
+  default?: { meta?: { configKey?: string } }
+}
+
+function readConfigKey(mod: ModuleLike | undefined): string | undefined {
+  const key = mod?.meta?.configKey ?? mod?.default?.meta?.configKey
+  return typeof key === 'string' && key.length > 0 ? key : undefined
+}
+
+async function loadModuleDescriptor(
+  modulePath: string,
+): Promise<ModuleLike | undefined> {
+  try {
+    const imported = await import(modulePath)
+    return (imported as { default?: ModuleLike }).default ?? imported
+  } catch (e: any) {
+    console.warn(`[@owdproject/core] Failed to load module descriptor for "${modulePath}":`, e.message || e)
+    return undefined
+  }
+}
+
+/**
+ * Installs a desktop theme, module, or app package.
+ * When the package exposes `meta.configKey`, passes `desktop[configKey]` to `installModule`
+ * so Nuxt merges desktop.config with module defaults.
+ */
+export async function installDesktopPackage(
+  nuxt: Nuxt,
+  modulePath: string,
+  desktop?: Record<string, unknown>,
+): Promise<void> {
+  const descriptor = await loadModuleDescriptor(modulePath)
+  const configKey = readConfigKey(descriptor)
+
+  if (configKey && desktop) {
+    const slice = desktop[configKey]
+    const inline =
+      slice && typeof slice === 'object' && !Array.isArray(slice)
+        ? (slice as Record<string, unknown>)
+        : {}
+    await installModule(modulePath, inline)
+    return
+  }
+
+  await installModule(modulePath)
+}
+
+type DesktopModuleMeta = {
+  name: string
+  configKey: string
+}
+
+type DesktopModuleDefinition = NuxtModule<
+  Record<string, unknown>,
+  Record<string, unknown>,
+  false
+> & {
+  meta: DesktopModuleMeta
+}
+
+/**
+ * Nuxt module wrapper for desktop apps and extension modules (`configKey` → desktop.config namespace).
+ * Publishes merged options to `runtimeConfig.public.desktop[configKey]` after setup runs.
+ */
+export function defineDesktopModule(
+  definition: DesktopModuleDefinition,
+): ReturnType<typeof defineNuxtModule> {
+  const configKey = definition.meta.configKey
+  if (!configKey) {
+    throw new Error(
+      '[@owdproject/core] defineDesktopModule requires meta.configKey (e.g. "terminal", "fs").',
+    )
+  }
+
+  const userSetup = definition.setup
+
+  return defineNuxtModule({
+    ...definition,
+    async setup(options, nuxt) {
+      const pub = (nuxt.options.runtimeConfig.public ??= {}) as {
+        desktop?: Record<string, unknown>
+      }
+      const desktop = (pub.desktop ??= {})
+      const userConfig = desktop[configKey]
+
+      // Merge userConfig (wins) with options (defaults / inline)
+      const merged = defu(
+        userConfig && typeof userConfig === 'object' ? userConfig : {},
+        options as Record<string, unknown>,
+      )
+
+      // Mutate options in place so userSetup receives the fully merged options
+      Object.assign(options, merged)
+
+      // Set/update the merged config on public.desktop
+      desktop[configKey] = options
+
+      if (typeof userSetup === 'function') {
+        return userSetup(options, nuxt)
+      }
+    },
+  } as NuxtModule)
+}
+
+type DesktopThemeDefinition = NuxtModule<
+  Record<string, unknown>,
+  Record<string, unknown>,
+  false
+>
+
+/**
+ * Nuxt module wrapper for desktop themes.
+ * Merges theme shell defaults into `runtimeConfig.public.desktop` (user desktop.config wins).
+ *
+ * Tailwind content for theme Vue templates is registered via
+ * `@owdproject/kit-primevue/kit/registerTailwindPath` after installing kit-primevue.
+ */
+export function defineDesktopTheme(
+  definition: DesktopThemeDefinition,
+): ReturnType<typeof defineNuxtModule> {
+  const userSetup = definition.setup
+
+  return defineNuxtModule({
+    ...definition,
+    meta: {
+      ...definition.meta,
+      configKey: 'desktop',
+    },
+    async setup(options, nuxt) {
+      const pub = (nuxt.options.runtimeConfig.public ??= {}) as {
+        desktop?: Record<string, unknown>
+      }
+      
+      // Automatically merge userConfig (pub.desktop) with theme defaults (options)
+      pub.desktop = defu(
+        (pub.desktop ?? {}) as Record<string, unknown>,
+        options as Record<string, unknown>,
+      )
+
+      // Mutate options in place so userSetup receives the fully merged options
+      Object.assign(options, pub.desktop)
+
+      if (typeof userSetup === 'function') {
+        return userSetup(options, nuxt)
+      }
+    },
+  } as NuxtModule)
+}

package/kit/defineDesktopApp.ts

@@ -0,0 +1,56 @@
+import { getActivePinia, setActivePinia } from 'pinia'
+import type { Pinia } from 'pinia'
+import { useApplicationManager } from '../runtime/composables/useApplicationManager'
+
+const pendingDesktopApps: ApplicationConfig[] = []
+
+let pluginPiniaInstance: Pinia | undefined
+
+/** Set by desktop-shell-init; avoids importing nuxt/app during jiti config load. */
+export function registerDesktopPluginPinia(pinia: Pinia | undefined) {
+  pluginPiniaInstance = pinia
+}
+
+function resolveActivePinia() {
+  const active = getActivePinia()
+  if (active) return active
+
+  if (pluginPiniaInstance) {
+    setActivePinia(pluginPiniaInstance)
+    return pluginPiniaInstance
+  }
+
+  return undefined
+}
+
+let isBooted = false
+
+/**
+ * Register a desktop app. Queues until Pinia is active when theme/app plugins
+ * run before shell-init (legacy published apps using synchronous setup).
+ */
+export async function defineDesktopApp(config: ApplicationConfig) {
+  if (import.meta.server) return undefined
+
+  if (isBooted && resolveActivePinia()) {
+    const applicationManager = useApplicationManager()
+    return applicationManager.defineApp(config.id, config)
+  }
+
+  pendingDesktopApps.push(config)
+  return undefined
+}
+
+export async function flushPendingDesktopApps() {
+  isBooted = true
+  if (pendingDesktopApps.length === 0) return
+
+  if (!resolveActivePinia()) return
+
+  const queue = pendingDesktopApps.splice(0, pendingDesktopApps.length)
+  const applicationManager = useApplicationManager()
+
+  for (const config of queue) {
+    await applicationManager.defineApp(config.id, config)
+  }
+}

package/module.ts

@@ -4,30 +4,53 @@ import {
   addComponentsDir,
   addImportsDir,
   installModule,
-  addPlugin
+  addPlugin,
+  resolvePath
 } from '@nuxt/kit'
 import { defu } from 'defu'
-import { assertValidDesktopUserConfig } from './runtime/utils/validateDesktopUserConfig'
 import {
+  assertValidDesktopUserConfig,
+  installDesktopPackage,
   resolveDesktopConfigPath,
+  warnDesktopConfigKeys,
   warnLegacyDesktopConfig,
-} from './runtime/utils/resolveDesktopConfigPath'
-import { splitDesktopUserConfig } from './runtime/utils/splitDesktopUserConfig'
+} from './kit/authoring'
 import pkg from './package.json'
 
 export default defineNuxtModule({
   meta: {
     name: 'desktop',
-    configKey: 'owd',
+    configKey: 'desktop',
   },
   defaults: {
     theme: '@owdproject/theme-nova',
     apps: [],
     modules: [],
   },
+  moduleDependencies: {
+    '@pinia/nuxt': {},
+    '@nuxt/fonts': {},
+    '@nuxt/icon': {
+      defaults: {
+        clientBundle: {
+          scan: true,
+          sizeLimitKb: 256,
+        },
+      },
+    },
+    '@vueuse/nuxt': {},
+    '@nuxtjs/i18n': {},
+  },
   async setup(_options, _nuxt) {
     const { resolve } = createResolver(import.meta.url)
 
+    let resolvedNanoid: string | null = null
+    try {
+      resolvedNanoid = await resolvePath('nanoid', { url: import.meta.url })
+    } catch (e) {
+      // ignore
+    }
+
     // Required for Nuxt 4 dev (playgrounds, module graphs): avoids
     // "Vite Node IPC socket path not configured" when using @nuxt/kit pipelines.
     _nuxt.options.experimental = {
@@ -52,6 +75,10 @@ export default defineNuxtModule({
 
     warnLegacyDesktopConfig(resolvedConfig)
 
+    // Nuxt dev restart + ℹ log (same as nuxt.config.ts); avoid builder:watch + restart (silent / double).
+    _nuxt.options.watch ??= []
+    _nuxt.options.watch.push(resolvedConfig.path)
+
     try {
       clientConfig = (await import(resolvedConfig.path)).default
     } catch (e) {
@@ -69,54 +96,51 @@ export default defineNuxtModule({
       clientConfig.theme = '@owdproject/theme-nova'
     }
 
-    const {
-      theme: configTheme,
-      apps: configApps,
-      modules: configModules,
-      desktopRuntime,
-    } = splitDesktopUserConfig(
-      clientConfig as Record<string, unknown>,
-      resolvedConfig.file,
-    )
-
-    clientConfig.theme = configTheme ?? clientConfig.theme
-    if (configApps) clientConfig.apps = configApps
-    if (configModules) clientConfig.modules = configModules
+    const configRecord = clientConfig as Record<string, unknown>
+    warnDesktopConfigKeys(configRecord, resolvedConfig.file)
 
-    // init desktop runtime config and define core version
-
-    _nuxt.options.runtimeConfig.public.desktop = defu(
-      desktopRuntime,
-      { coreVersion: pkg.version },
-    )
+    const desktop = defu(configRecord, { coreVersion: pkg.version }) as Record<
+      string,
+      unknown
+    > & {
+      theme?: string
+      apps?: string[]
+      modules?: string[]
+    }
 
-    // Pinia before theme/modules/apps so defineDesktopApp can use stores when
-    // published app plugins register on app:created.
-    await installModule('@pinia/nuxt')
+    _nuxt.options.runtimeConfig.public.desktop = desktop
 
     {
-      // install open web desktop theme
-
-      if (clientConfig.theme) {
-        await installModule(clientConfig.theme)
+      if (desktop.theme) {
+        try {
+          await installDesktopPackage(_nuxt, desktop.theme, desktop)
+        } catch (e) {
+          const msg = e instanceof Error ? e.message : String(e)
+          console.warn(`[@owdproject/core] Warning: Could not load theme "${desktop.theme}". Details: ${msg}`)
+        }
       }
 
-      // install open web desktop modules
-
-      if (clientConfig.modules && Array.isArray(clientConfig.modules)) {
-        for (const modulePath of clientConfig.modules) {
-          await installModule(modulePath)
+      if (Array.isArray(desktop.modules)) {
+        for (const modulePath of desktop.modules) {
+          try {
+            await installDesktopPackage(_nuxt, modulePath, desktop)
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e)
+            console.warn(`[@owdproject/core] Warning: Could not load module "${modulePath}". Details: ${msg}`)
+          }
         }
       }
 
-      // install open web desktop apps
-
-      if (clientConfig.apps && Array.isArray(clientConfig.apps)) {
-        for (const appPath of clientConfig.apps) {
-          await installModule(appPath)
+      if (Array.isArray(desktop.apps)) {
+        for (const appPath of desktop.apps) {
+          try {
+            await installDesktopPackage(_nuxt, appPath, desktop)
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e)
+            console.warn(`[@owdproject/core] Warning: Could not load app "${appPath}". Details: ${msg}`)
+          }
         }
       }
-
     }
 
     // assign runtimeConfig desktop prop to appConfig
@@ -124,71 +148,6 @@ export default defineNuxtModule({
     // via useDesktopManager
     _nuxt.options.appConfig.desktop = _nuxt.options.runtimeConfig.public.desktop
 
-    {
-      // install primevue
-
-      _nuxt.options.primevue = _nuxt.options.primevue || {}
-      _nuxt.options.primevue.options = _nuxt.options.primevue.options || {}
-      _nuxt.options.primevue.options.theme =
-        _nuxt.options.primevue.options.theme || {}
-      _nuxt.options.primevue.components =
-        _nuxt.options.primevue.components || {}
-      const include = _nuxt.options.primevue.components.include
-      if (include && include !== '*' && Array.isArray(include)) {
-        if (!include.includes('ConfirmDialog')) {
-          include.push('ConfirmDialog')
-        }
-      }
-
-      await installModule('@primevue/nuxt-module')
-    }
-
-    {
-      // install tailwind
-
-      const tailwindPaths =
-        _nuxt.options.runtimeConfig.app.owd?.tailwindPaths || []
-      tailwindPaths.push('./runtime/components/**/*.{vue,mjs,ts}') // Aggiungi sempre questo al core
-
-      _nuxt.options.tailwindcss = _nuxt.options.tailwindcss || {}
-      _nuxt.options.tailwindcss.config = _nuxt.options.tailwindcss.config || {}
-      // @ts-ignore
-      _nuxt.options.tailwindcss.config.content = tailwindPaths
-
-      await installModule('@nuxtjs/tailwindcss', {
-        viewer: false
-      })
-    }
-
-    {
-      // install @nuxt/fonts
-
-      await installModule('@nuxt/fonts')
-    }
-
-    {
-      // install @nuxt/icon
-
-      await installModule('@nuxt/icon', {
-        clientBundle: {
-          scan: true,
-          sizeLimitKb: 256
-        }
-      })
-    }
-
-    {
-      // install @vueuse/nuxt
-
-      await installModule('@vueuse/nuxt')
-    }
-
-    {
-      // install @nuxtjs/i18n
-
-      await installModule('@nuxtjs/i18n')
-    }
-
     {
       // configure scss for vite
 
@@ -199,6 +158,12 @@ export default defineNuxtModule({
         viteConfig.css.preprocessorOptions.scss = {
           api: 'modern-compiler'
         }
+
+        viteConfig.optimizeDeps = viteConfig.optimizeDeps || {}
+        viteConfig.optimizeDeps.include = viteConfig.optimizeDeps.include || []
+        if (resolvedNanoid && !viteConfig.optimizeDeps.include.includes(resolvedNanoid)) {
+          viteConfig.optimizeDeps.include.push(resolvedNanoid)
+        }
       })
     }
 
@@ -213,7 +178,7 @@ export default defineNuxtModule({
 
       addComponentsDir({
         path: resolve('./runtime/components'),
-        prefix: '',
+        prefix: 'Desktop',
         pathPrefix: false,
         global: true
       })
@@ -221,6 +186,9 @@ export default defineNuxtModule({
 
     {
       addPlugin(resolve('./runtime/plugins/resize.client.ts'))
+      addPlugin(
+        resolve('./runtime/plugins/01.desktop-shell-init.client.ts'),
+      )
       addPlugin(
         resolve('./runtime/plugins/02.desktop-register-desktop-apps.client.ts'),
       )