@spree/dashboard-core 0.1.0

package/src/vite/discover.ts

@@ -0,0 +1,170 @@
+import fs from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Walk a host project's `package.json` dependencies and return the names of
+ * packages that opt-in as dashboard plugins by declaring
+ * `"spree": { "dashboard": { "plugin": true } }` in their own `package.json`.
+ *
+ * Auto-discovery is what makes `pnpm add @acme/foo-plugin` a one-step
+ * install: the discovered list feeds both Tailwind source scanning and the
+ * `virtual:spree-dashboard-plugins` activation module the app entry imports
+ * (see index.ts). Plugin authors opt-in by adding the marker field; hosts
+ * never have to know it exists.
+ *
+ * Order is deterministic — the order packages appear in the host's combined
+ * `dependencies` + `devDependencies` maps. Tailwind class scanning is
+ * order-insensitive, so this only matters for the dev-mode banner's listing.
+ *
+ * The function does not throw on missing files or malformed JSON — failures
+ * are reported via the `onWarn` callback and the offending package is
+ * skipped. A missing host `package.json` returns an empty array.
+ */
+export interface DiscoverOptions {
+  /** Project root to scan. Usually Vite's `config.root`. */
+  root: string
+  /** Optional callback for per-package warnings (malformed JSON, missing dep). */
+  onWarn?: (message: string) => void
+}
+
+/** A discovered plugin plus the build-relevant fields from its marker. */
+export interface DashboardPluginManifest {
+  /** Package name, as it appears in the host's dependencies. */
+  name: string
+  /**
+   * Absolute path to the plugin's file-routes directory, when the marker
+   * declares one (`"spree": { "dashboard": { "routes": "./src/routes" } }`).
+   * Compiled into the host's route tree by `@spree/dashboard/vite`.
+   */
+  routesDir?: string
+}
+
+/**
+ * Like {@link discoverDashboardPlugins}, but returns each plugin's manifest
+ * fields. `names` restricts resolution to an explicit whitelist (the
+ * `plugins:` option) instead of walking the host's dependencies.
+ */
+export function discoverDashboardPluginManifests(
+  { root, onWarn }: DiscoverOptions,
+  names?: string[],
+): DashboardPluginManifest[] {
+  const require = createRequire(path.join(root, 'package.json'))
+  const candidates = names ?? discoverDashboardPlugins({ root, onWarn })
+
+  const manifests: DashboardPluginManifest[] = []
+  for (const name of candidates) {
+    const manifestPath = resolveManifest(name, require)
+    if (!manifestPath) {
+      manifests.push({ name })
+      continue
+    }
+    let pkg: PluginManifest
+    try {
+      pkg = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as PluginManifest
+    } catch (err) {
+      onWarn?.(`Could not parse ${manifestPath}: ${(err as Error).message}`)
+      manifests.push({ name })
+      continue
+    }
+    const routes = pkg.spree?.dashboard?.routes
+    manifests.push({
+      name,
+      routesDir: routes ? path.resolve(path.dirname(manifestPath), routes) : undefined,
+    })
+  }
+  return manifests
+}
+
+export function discoverDashboardPlugins({ root, onWarn }: DiscoverOptions): string[] {
+  const hostPkgPath = path.join(root, 'package.json')
+  if (!fs.existsSync(hostPkgPath)) return []
+
+  let hostPkg: HostManifest
+  try {
+    hostPkg = JSON.parse(fs.readFileSync(hostPkgPath, 'utf8')) as HostManifest
+  } catch (err) {
+    onWarn?.(`Could not parse ${hostPkgPath}: ${(err as Error).message}`)
+    return []
+  }
+
+  const deps = [
+    ...Object.keys(hostPkg.dependencies ?? {}),
+    ...Object.keys(hostPkg.devDependencies ?? {}),
+  ]
+
+  // Resolve from the host's own root so workspace symlinks and `pnpm`'s
+  // `.pnpm/` hoisting both work. createRequire wants a file path, not a
+  // directory, so synthesize one.
+  const require = createRequire(path.join(root, 'package.json'))
+
+  const discovered: string[] = []
+  const seen = new Set<string>()
+
+  for (const name of deps) {
+    if (seen.has(name)) continue
+    seen.add(name)
+
+    const manifestPath = resolveManifest(name, require)
+    if (!manifestPath) continue
+
+    let depPkg: PluginManifest
+    try {
+      depPkg = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as PluginManifest
+    } catch (err) {
+      onWarn?.(`Could not parse ${manifestPath}: ${(err as Error).message}`)
+      continue
+    }
+
+    if (depPkg.spree?.dashboard?.plugin === true) {
+      discovered.push(name)
+    }
+  }
+
+  return discovered
+}
+
+interface HostManifest {
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+
+interface PluginManifest {
+  spree?: {
+    dashboard?: {
+      plugin?: boolean
+      routes?: string
+    }
+  }
+}
+
+/**
+ * Resolve `<pkg>/package.json` to its filesystem path. We can't always do
+ * `require.resolve('<pkg>/package.json')` because many packages don't expose
+ * it in their `exports` map. Fall back to walking up from the resolved entry
+ * point — same pattern as the source-dir resolver in `index.ts`.
+ */
+function resolveManifest(pkg: string, require: NodeJS.Require): string | null {
+  try {
+    return require.resolve(`${pkg}/package.json`)
+  } catch {
+    // exports map didn't include package.json; walk up from the main entry.
+  }
+
+  let entry: string
+  try {
+    entry = require.resolve(pkg)
+  } catch {
+    return null
+  }
+
+  let current = path.dirname(entry.startsWith('file:') ? fileURLToPath(entry) : entry)
+  const { root } = path.parse(current)
+  while (current !== root) {
+    const candidate = path.join(current, 'package.json')
+    if (fs.existsSync(candidate)) return candidate
+    current = path.dirname(current)
+  }
+  return null
+}

package/src/vite/index.ts

@@ -0,0 +1,270 @@
+import fs from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+// Self-referencing package import (not a relative path): this entry is loaded
+// raw by Node when a host's vite.config.ts imports `@spree/dashboard-core/vite`,
+// and Node's TS type-stripping can't resolve extensionless relative specifiers.
+// The exports-map path resolves to the real file name everywhere.
+import { discoverDashboardPlugins } from '@spree/dashboard-core/vite/discover'
+import tailwindcss from '@tailwindcss/vite'
+import type { Plugin, PluginOption } from 'vite'
+
+export interface SpreeDashboardPluginOptions {
+  /**
+   * Path to the host app's CSS entry file (the one that does
+   * `@import "@spree/dashboard-ui/styles.css"`). Resolved relative to the
+   * host's project root. The plugin injects `@source` directives into this
+   * file so Tailwind v4 scans every Spree dashboard package and every
+   * dashboard plugin for class usage.
+   *
+   * Defaults to `./src/styles.css`, which fits the conventional Vite layout.
+   */
+  cssEntry?: string
+
+  /**
+   * Names of dashboard plugin packages installed in the host app. Each name
+   * must be a resolvable npm package specifier — the same string you'd pass
+   * to `import()`. The plugin resolves each one via Node module resolution
+   * and tells Tailwind v4 to scan its source files for class usage.
+   *
+   * When omitted (the typical case), the plugin auto-discovers installed
+   * dashboard plugins by walking the host's `package.json` dependencies and
+   * picking up anything that declares
+   * `"spree": { "dashboard": { "plugin": true } }`. Pass an explicit array
+   * to opt out of auto-discovery — useful for whitelisting in tightly
+   * controlled environments.
+   *
+   * Example: `['@my-store/orders-plugin', '@my-store/wishlists-plugin']`.
+   */
+  plugins?: string[]
+}
+
+/**
+ * Vite plugin that wires up a Spree dashboard's plugin system and Tailwind v4.
+ *
+ * Combines three concerns:
+ *
+ *   1. Plugin activation: serves `virtual:spree-dashboard-plugins`, a
+ *      synthesized module that side-effect-imports every dashboard plugin
+ *      (auto-discovered or whitelisted). The app entry imports it once —
+ *      after that, installing a plugin is just `pnpm add`; its
+ *      `defineDashboardPlugin` call runs without any host-code edit.
+ *
+ *   2. Source-scanning: tells Tailwind to scan `@spree/dashboard-core`,
+ *      `@spree/dashboard-ui`, and every plugin package, by injecting
+ *      `@source` directives into the host's CSS entry. Tailwind v4
+ *      doesn't scan `node_modules` by default and only accepts filesystem
+ *      paths in `@source` directives (not bare package specifiers), so we
+ *      resolve each package through Node module resolution to get an
+ *      absolute path that works under any package layout (workspace
+ *      symlinks, npm tarballs, pnpm's `.pnpm/` hoisting).
+ *
+ *   3. Tailwind itself: returns `@tailwindcss/vite` bundled alongside the
+ *      source-injection plugin, in the right order. Hosts don't add
+ *      `@tailwindcss/vite` separately.
+ *
+ * Usage from a host using the full `@spree/dashboard` app shell:
+ *
+ *     // host vite.config.ts
+ *     import { spreeDashboardPlugin } from '@spree/dashboard-core/vite'
+ *
+ *     export default defineConfig({
+ *       plugins: [
+ *         spreeDashboardPlugin(),
+ *         // … react(), TanStack Router, etc. — host owns these.
+ *       ],
+ *     })
+ *
+ *     // host src/main.tsx (once, before the router mounts)
+ *     import 'virtual:spree-dashboard-plugins'
+ *
+ * For a custom dashboard built on `@spree/dashboard-core` + `@spree/dashboard-ui`,
+ * point `cssEntry` at the host's own CSS file:
+ *
+ *     spreeDashboardPlugin({
+ *       cssEntry: './src/admin.css',
+ *       plugins: ['@my-store/vendor-portal-plugin'],  // explicit whitelist opt-out
+ *     })
+ */
+export function spreeDashboardPlugin(options: SpreeDashboardPluginOptions = {}): PluginOption[] {
+  return [dashboardTailwindSourcePlugin(options), tailwindcss()]
+}
+
+/** Module specifier hosts import to activate discovered dashboard plugins. */
+export const VIRTUAL_PLUGIN_MODULE_ID = 'virtual:spree-dashboard-plugins'
+// Rollup convention: \0 marks the resolved id as virtual so other plugins
+// (and Vite's own resolver) leave it alone.
+const RESOLVED_VIRTUAL_PLUGIN_MODULE_ID = `\0${VIRTUAL_PLUGIN_MODULE_ID}`
+
+/**
+ * Source of `virtual:spree-dashboard-plugins`: one side-effect import per
+ * activatable plugin, in discovery order. Exported for tests.
+ */
+export function generateVirtualPluginModule(packages: readonly string[]): string {
+  const header = '// generated by @spree/dashboard-core/vite — one import per dashboard plugin'
+  if (packages.length === 0) return `${header}\nexport {}\n`
+  const imports = packages.map((pkg) => `import ${JSON.stringify(pkg)}`).join('\n')
+  return `${header}\n${imports}\nexport {}\n`
+}
+
+function dashboardTailwindSourcePlugin(options: SpreeDashboardPluginOptions): Plugin {
+  const explicitPlugins = options.plugins
+  const cssEntry = options.cssEntry ?? './src/styles.css'
+
+  // Resolution root for the framework's own siblings. Wherever
+  // `@spree/dashboard-core` ends up on disk (workspace symlink, hoisted
+  // npm install, pnpm `.pnpm/` directory), `@spree/dashboard-ui` is
+  // reachable from here via Node module resolution.
+  const fromHere = createRequire(import.meta.url)
+
+  let resolvedSources: string[] = []
+  let resolvedCssEntry = ''
+  let pluginErrors: PluginError[] = []
+  let activatablePlugins: string[] = []
+
+  return {
+    name: 'spree:dashboard-tailwind-source',
+    enforce: 'pre',
+
+    configResolved(config) {
+      resolvedCssEntry = path.resolve(config.root, cssEntry).split(path.sep).join('/')
+
+      // `plugins: []` is an explicit empty whitelist; only `plugins` omitted
+      // triggers discovery. Discovery walks the host's package.json deps and
+      // returns names that opt-in via the `spree.dashboard.plugin` marker.
+      const pluginPackages =
+        explicitPlugins ??
+        discoverDashboardPlugins({
+          root: config.root,
+          onWarn: (msg) => console.warn(`[@spree/dashboard-core/vite] ${msg}`),
+        })
+
+      // Plugins are the host's dependencies, so resolve them from the host
+      // root — under pnpm's strict layout they are not necessarily reachable
+      // from dashboard-core's own location.
+      const fromHost = createRequire(path.join(config.root, 'package.json'))
+
+      pluginErrors = []
+      resolvedSources = []
+      activatablePlugins = []
+      for (const pkg of ['@spree/dashboard-core', '@spree/dashboard-ui']) {
+        const dir = resolvePackageSourceDir(pkg, fromHere)
+        if (dir) {
+          resolvedSources.push(dir)
+        } else {
+          pluginErrors.push({ pkg, kind: 'unresolved' })
+        }
+      }
+      // The app shell is optional: present when the host builds on the full
+      // `@spree/dashboard` package, absent for custom dashboards composed
+      // directly from core + ui — hence no error when unresolved.
+      const shellDir = resolvePackageSourceDir('@spree/dashboard', fromHost)
+      if (shellDir) resolvedSources.push(shellDir)
+      for (const pkg of pluginPackages) {
+        const dir = resolvePackageSourceDir(pkg, fromHost)
+        if (dir) {
+          resolvedSources.push(dir)
+          activatablePlugins.push(pkg)
+        } else {
+          // Unresolved plugins are reported via the dev overlay instead of
+          // being imported — a bare failing import would crash the dev
+          // server with a much less actionable error.
+          pluginErrors.push({ pkg, kind: 'unresolved' })
+        }
+      }
+    },
+
+    resolveId(id) {
+      if (id === VIRTUAL_PLUGIN_MODULE_ID) return RESOLVED_VIRTUAL_PLUGIN_MODULE_ID
+      return null
+    },
+
+    load(id) {
+      if (id !== RESOLVED_VIRTUAL_PLUGIN_MODULE_ID) return null
+      return generateVirtualPluginModule(activatablePlugins)
+    },
+
+    transform(code, id) {
+      const normalized = id.split('?')[0].replaceAll('\\', '/')
+      if (normalized !== resolvedCssEntry) return null
+
+      const directives = resolvedSources.map((dir) => `@source '${dir}';`).join('\n')
+
+      return {
+        code: `${code}\n\n/* injected by @spree/dashboard-core/vite */\n${directives}\n`,
+        map: null,
+      }
+    },
+
+    configureServer(server) {
+      // Surface unresolved plugins as a Vite error overlay in dev so the
+      // failure mode is loud. Without this, a missing plugin silently emits
+      // unstyled HTML when the host imports it. Sent once per client
+      // connection rather than per HTTP request.
+      if (pluginErrors.length === 0) return
+      const message = formatPluginErrorOverlay(pluginErrors)
+      server.ws.on('connection', () => {
+        server.ws.send({
+          type: 'error',
+          err: {
+            message,
+            stack: '',
+            plugin: 'spree:dashboard-tailwind-source',
+          },
+        })
+      })
+    },
+  }
+}
+
+interface PluginError {
+  pkg: string
+  kind: 'unresolved'
+}
+
+function formatPluginErrorOverlay(errors: PluginError[]): string {
+  const lines = [
+    'Spree dashboard plugin(s) could not be resolved:',
+    '',
+    ...errors.map(({ pkg }) => `  - ${pkg}`),
+    '',
+    'For each one, check:',
+    '  1. The package is installed (`pnpm add <package>`)',
+    '  2. Its package.json declares the dashboard marker:',
+    '       { "spree": { "dashboard": { "plugin": true } } }',
+    '',
+    'If you registered it explicitly via spreeDashboardPlugin({ plugins: [...] }),',
+    'verify the name matches the installed package exactly.',
+  ]
+  return lines.join('\n')
+}
+
+/**
+ * Resolve `<package>/src` on disk. Resolves the package's main entry point
+ * (defined by its `exports` map or `main` field) and walks upwards looking
+ * for `package.json` to find the package root. Avoids requiring
+ * `<pkg>/package.json` to be in the package's `exports` map — many packages,
+ * including ours, don't list it there.
+ */
+function resolvePackageSourceDir(pkg: string, require: NodeJS.Require): string | null {
+  try {
+    const entryPath = require.resolve(pkg)
+    const entryFile = entryPath.startsWith('file:') ? fileURLToPath(entryPath) : entryPath
+    const packageRoot = findPackageRoot(entryFile)
+    if (!packageRoot) return null
+    return path.join(packageRoot, 'src')
+  } catch {
+    return null
+  }
+}
+
+function findPackageRoot(fromFile: string): string | null {
+  let current = path.dirname(fromFile)
+  const { root } = path.parse(current)
+  while (current !== root) {
+    if (fs.existsSync(path.join(current, 'package.json'))) return current
+    current = path.dirname(current)
+  }
+  return null
+}