@databricks/appkit 0.17.0 → 0.19.0

package/dist/plugins/files/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","names":["manifest","files"],"sources":["../../../src/plugins/files/plugin.ts"],"sourcesContent":["import { Readable } from \"node:stream\";\nimport { ApiError } from \"@databricks/sdk-experimental\";\nimport type express from \"express\";\nimport type { IAppRouter, PluginExecutionSettings } from \"shared\";\nimport {\n  contentTypeFromPath,\n  FilesConnector,\n  isSafeInlineContentType,\n  validateCustomContentTypes,\n} from \"../../connectors/files\";\nimport { getWorkspaceClient, isInUserContext } from \"../../context\";\nimport { AuthenticationError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest, ResourceRequirement } from \"../../registry\";\nimport { ResourceType } from \"../../registry\";\nimport {\n  FILES_DOWNLOAD_DEFAULTS,\n  FILES_MAX_UPLOAD_SIZE,\n  FILES_READ_DEFAULTS,\n  FILES_WRITE_DEFAULTS,\n} from \"./defaults\";\nimport { parentDirectory, sanitizeFilename } from \"./helpers\";\nimport manifest from \"./manifest.json\";\nimport type {\n  DownloadResponse,\n  FilesExport,\n  IFilesConfig,\n  VolumeAPI,\n  VolumeConfig,\n  VolumeHandle,\n} from \"./types\";\n\nconst logger = createLogger(\"files\");\n\nexport class FilesPlugin extends Plugin {\n  name = \"files\";\n\n  /** Plugin manifest declaring metadata and resource requirements. */\n  static manifest = manifest as PluginManifest;\n  protected static description = \"Files plugin for Databricks file operations\";\n  protected declare config: IFilesConfig;\n\n  private volumeConnectors: Record<string, FilesConnector> = {};\n  private volumeConfigs: Record<string, VolumeConfig> = {};\n  private volumeKeys: string[] = [];\n\n  /**\n   * Scans `process.env` for `DATABRICKS_VOLUME_*` keys and merges them with\n   * any explicitly configured volumes. Explicit config wins for per-volume\n   * overrides; auto-discovered volumes get default `{}` config.\n   */\n  static discoverVolumes(config: IFilesConfig): Record<string, VolumeConfig> {\n    const explicit = config.volumes ?? {};\n    const discovered: Record<string, VolumeConfig> = {};\n\n    const prefix = \"DATABRICKS_VOLUME_\";\n    for (const key of Object.keys(process.env)) {\n      if (!key.startsWith(prefix)) continue;\n      const suffix = key.slice(prefix.length);\n      if (!suffix) continue;\n      if (!process.env[key]) continue;\n      const volumeKey = suffix.toLowerCase();\n      if (!(volumeKey in explicit)) {\n        discovered[volumeKey] = {};\n      }\n    }\n\n    return { ...discovered, ...explicit };\n  }\n\n  /**\n   * Generates resource requirements dynamically from discovered + configured volumes.\n   * Each volume key maps to a `DATABRICKS_VOLUME_{KEY_UPPERCASE}` env var.\n   */\n  static getResourceRequirements(config: IFilesConfig): ResourceRequirement[] {\n    const volumes = FilesPlugin.discoverVolumes(config);\n    return Object.keys(volumes).map((key) => ({\n      type: ResourceType.VOLUME,\n      alias: `volume-${key}`,\n      resourceKey: `volume-${key}`,\n      description: `Unity Catalog Volume for \"${key}\" file storage`,\n      permission: \"WRITE_VOLUME\",\n      fields: {\n        path: {\n          env: `DATABRICKS_VOLUME_${key.toUpperCase()}`,\n          description: `Volume path for \"${key}\" (e.g. /Volumes/catalog/schema/volume_name)`,\n        },\n      },\n      required: true,\n    }));\n  }\n\n  /**\n   * Warns when a method is called without a user context (i.e. as service principal).\n   * OBO access via `asUser(req)` is strongly recommended.\n   */\n  private warnIfNoUserContext(volumeKey: string, method: string): void {\n    if (!isInUserContext()) {\n      logger.warn(\n        `app.files(\"${volumeKey}\").${method}() called without user context (service principal). ` +\n          `Please use OBO instead: app.files(\"${volumeKey}\").asUser(req).${method}()`,\n      );\n    }\n  }\n\n  /**\n   * Throws when a method is called without a user context (i.e. as service principal).\n   * OBO access via `asUser(req)` is enforced for now.\n   */\n  private throwIfNoUserContext(volumeKey: string, method: string): void {\n    if (!isInUserContext()) {\n      throw new Error(\n        `app.files(\"${volumeKey}\").${method}() called without user context (service principal). Use OBO instead: app.files(\"${volumeKey}\").asUser(req).${method}()`,\n      );\n    }\n  }\n\n  constructor(config: IFilesConfig) {\n    super(config);\n    this.config = config;\n\n    if (config.customContentTypes) {\n      validateCustomContentTypes(config.customContentTypes);\n    }\n\n    const volumes = FilesPlugin.discoverVolumes(config);\n    this.volumeKeys = Object.keys(volumes);\n\n    for (const key of this.volumeKeys) {\n      const volumeCfg = volumes[key];\n      const envVar = `DATABRICKS_VOLUME_${key.toUpperCase()}`;\n      const volumePath = process.env[envVar];\n\n      // Merge per-volume config with plugin-level defaults\n      const mergedConfig: VolumeConfig = {\n        maxUploadSize: volumeCfg.maxUploadSize ?? config.maxUploadSize,\n        customContentTypes:\n          volumeCfg.customContentTypes ?? config.customContentTypes,\n      };\n      this.volumeConfigs[key] = mergedConfig;\n\n      this.volumeConnectors[key] = new FilesConnector({\n        defaultVolume: volumePath,\n        timeout: config.timeout,\n        telemetry: config.telemetry,\n        customContentTypes: mergedConfig.customContentTypes,\n      });\n    }\n  }\n\n  /**\n   * Creates a VolumeAPI for a specific volume key.\n   * Each method warns if called outside a user context (service principal).\n   */\n  protected createVolumeAPI(volumeKey: string): VolumeAPI {\n    const connector = this.volumeConnectors[volumeKey];\n    return {\n      list: (directoryPath?: string) => {\n        this.throwIfNoUserContext(volumeKey, `list`);\n        return connector.list(getWorkspaceClient(), directoryPath);\n      },\n      read: (filePath: string, options?: { maxSize?: number }) => {\n        this.throwIfNoUserContext(volumeKey, `read`);\n        return connector.read(getWorkspaceClient(), filePath, options);\n      },\n      download: (filePath: string): Promise<DownloadResponse> => {\n        this.throwIfNoUserContext(volumeKey, `download`);\n        return connector.download(getWorkspaceClient(), filePath);\n      },\n      exists: (filePath: string) => {\n        this.throwIfNoUserContext(volumeKey, `exists`);\n        return connector.exists(getWorkspaceClient(), filePath);\n      },\n      metadata: (filePath: string) => {\n        this.throwIfNoUserContext(volumeKey, `metadata`);\n        return connector.metadata(getWorkspaceClient(), filePath);\n      },\n      upload: (\n        filePath: string,\n        contents: ReadableStream | Buffer | string,\n        options?: { overwrite?: boolean },\n      ) => {\n        this.throwIfNoUserContext(volumeKey, `upload`);\n        return connector.upload(\n          getWorkspaceClient(),\n          filePath,\n          contents,\n          options,\n        );\n      },\n      createDirectory: (directoryPath: string) => {\n        this.throwIfNoUserContext(volumeKey, `createDirectory`);\n        return connector.createDirectory(getWorkspaceClient(), directoryPath);\n      },\n      delete: (filePath: string) => {\n        this.throwIfNoUserContext(volumeKey, `delete`);\n        return connector.delete(getWorkspaceClient(), filePath);\n      },\n      preview: (filePath: string) => {\n        this.throwIfNoUserContext(volumeKey, `preview`);\n        return connector.preview(getWorkspaceClient(), filePath);\n      },\n    };\n  }\n\n  injectRoutes(router: IAppRouter) {\n    this.route(router, {\n      name: \"volumes\",\n      method: \"get\",\n      path: \"/volumes\",\n      handler: async (_req: express.Request, res: express.Response) => {\n        res.json({ volumes: this.volumeKeys });\n      },\n    });\n\n    this.route(router, {\n      name: \"list\",\n      method: \"get\",\n      path: \"/:volumeKey/list\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleList(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"read\",\n      method: \"get\",\n      path: \"/:volumeKey/read\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleRead(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"download\",\n      method: \"get\",\n      path: \"/:volumeKey/download\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleDownload(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"raw\",\n      method: \"get\",\n      path: \"/:volumeKey/raw\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleRaw(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"exists\",\n      method: \"get\",\n      path: \"/:volumeKey/exists\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleExists(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"metadata\",\n      method: \"get\",\n      path: \"/:volumeKey/metadata\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleMetadata(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"preview\",\n      method: \"get\",\n      path: \"/:volumeKey/preview\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handlePreview(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"upload\",\n      method: \"post\",\n      path: \"/:volumeKey/upload\",\n      skipBodyParsing: true,\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleUpload(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"mkdir\",\n      method: \"post\",\n      path: \"/:volumeKey/mkdir\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleMkdir(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"delete\",\n      method: \"delete\",\n      path: \"/:volumeKey\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleDelete(req, res, connector, volumeKey);\n      },\n    });\n  }\n\n  /**\n   * Resolve `:volumeKey` from the request. Returns the connector and key,\n   * or sends a 404 and returns `{ connector: undefined }`.\n   */\n  private _resolveVolume(\n    req: express.Request,\n    res: express.Response,\n  ):\n    | { connector: FilesConnector; volumeKey: string }\n    | { connector: undefined; volumeKey: undefined } {\n    const volumeKey = req.params.volumeKey;\n    const connector = this.volumeConnectors[volumeKey];\n    if (!connector) {\n      const safeKey = volumeKey.replace(/[^a-zA-Z0-9_-]/g, \"\");\n      res.status(404).json({\n        error: `Unknown volume \"${safeKey}\"`,\n        plugin: this.name,\n      });\n      return { connector: undefined, volumeKey: undefined };\n    }\n    return { connector, volumeKey };\n  }\n\n  /**\n   * Validate a file/directory path from user input.\n   * Returns `true` if valid, or an error message string if invalid.\n   */\n  private _isValidPath(path: string | undefined): true | string {\n    if (!path) return \"path is required\";\n    if (path.length > 4096)\n      return `path exceeds maximum length of 4096 characters (got ${path.length})`;\n    if (path.includes(\"\\0\")) return \"path must not contain null bytes\";\n    return true;\n  }\n\n  private _readSettings(\n    cacheKey: (string | number | object)[],\n  ): PluginExecutionSettings {\n    return {\n      default: {\n        ...FILES_READ_DEFAULTS,\n        cache: { ...FILES_READ_DEFAULTS.cache, cacheKey },\n      },\n    };\n  }\n\n  /**\n   * Invalidate cached list entries for a directory after a write operation.\n   * Uses the same cache-key format as `_handleList`: resolved path for\n   * subdirectories, `\"__root__\"` for the volume root.\n   */\n  private _invalidateListCache(\n    volumeKey: string,\n    parentPath: string,\n    userId: string,\n    connector: FilesConnector,\n  ): void {\n    const parent = parentDirectory(parentPath);\n    const cachePathSegment = parent\n      ? connector.resolvePath(parent)\n      : \"__root__\";\n    const listKey = this.cache.generateKey(\n      [`files:${volumeKey}:list`, cachePathSegment],\n      userId,\n    );\n    this.cache.delete(listKey);\n  }\n\n  private _handleApiError(\n    res: express.Response,\n    error: unknown,\n    fallbackMessage: string,\n  ): void {\n    if (error instanceof AuthenticationError) {\n      res.status(401).json({\n        error: error.message,\n        plugin: this.name,\n      });\n      return;\n    }\n    if (error instanceof ApiError) {\n      const status = error.statusCode ?? 500;\n      if (status >= 400 && status < 500) {\n        res.status(status).json({\n          error: error.message,\n          statusCode: status,\n          plugin: this.name,\n        });\n        return;\n      }\n      logger.error(\"Upstream server error in %s: %O\", this.name, error);\n      res.status(500).json({ error: fallbackMessage, plugin: this.name });\n      return;\n    }\n    logger.error(\"Unhandled error in %s: %O\", this.name, error);\n    res.status(500).json({ error: fallbackMessage, plugin: this.name });\n  }\n\n  private async _handleList(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string | undefined;\n\n    try {\n      const userPlugin = this.asUser(req);\n      const result = await userPlugin.execute(\n        async () => {\n          this.warnIfNoUserContext(volumeKey, `list`);\n          return connector.list(getWorkspaceClient(), path);\n        },\n        this._readSettings([\n          `files:${volumeKey}:list`,\n          path ? connector.resolvePath(path) : \"__root__\",\n        ]),\n      );\n\n      if (result === undefined) {\n        res.status(500).json({ error: \"List failed\", plugin: this.name });\n        return;\n      }\n      res.json(result);\n    } catch (error) {\n      this._handleApiError(res, error, \"List failed\");\n    }\n  }\n\n  private async _handleRead(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    try {\n      const userPlugin = this.asUser(req);\n      const result = await userPlugin.execute(\n        async () => {\n          this.warnIfNoUserContext(volumeKey, `read`);\n          return connector.read(getWorkspaceClient(), path);\n        },\n        this._readSettings([\n          `files:${volumeKey}:read`,\n          connector.resolvePath(path),\n        ]),\n      );\n\n      if (result === undefined) {\n        res.status(500).json({ error: \"Read failed\", plugin: this.name });\n        return;\n      }\n      res.type(\"text/plain\").send(result);\n    } catch (error) {\n      this._handleApiError(res, error, \"Read failed\");\n    }\n  }\n\n  private async _handleDownload(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    return this._serveFile(req, res, connector, volumeKey, {\n      mode: \"download\",\n    });\n  }\n\n  private async _handleRaw(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    return this._serveFile(req, res, connector, volumeKey, {\n      mode: \"raw\",\n    });\n  }\n\n  /**\n   * Shared handler for `/download` and `/raw` endpoints.\n   * - `download`: always forces `Content-Disposition: attachment`.\n   * - `raw`: adds CSP sandbox; forces attachment only for unsafe content types.\n   */\n  private async _serveFile(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n    opts: { mode: \"download\" | \"raw\" },\n  ): Promise<void> {\n    const path = req.query.path as string;\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    const label = opts.mode === \"download\" ? \"Download\" : \"Raw fetch\";\n    const volumeCfg = this.volumeConfigs[volumeKey];\n\n    try {\n      const userPlugin = this.asUser(req);\n      const settings: PluginExecutionSettings = {\n        default: FILES_DOWNLOAD_DEFAULTS,\n      };\n      const response = await userPlugin.execute(async () => {\n        this.warnIfNoUserContext(volumeKey, `download`);\n        return connector.download(getWorkspaceClient(), path);\n      }, settings);\n\n      if (response === undefined) {\n        res.status(500).json({ error: `${label} failed`, plugin: this.name });\n        return;\n      }\n\n      const resolvedType = contentTypeFromPath(\n        path,\n        undefined,\n        volumeCfg.customContentTypes,\n      );\n      const fileName = sanitizeFilename(path.split(\"/\").pop() ?? \"download\");\n\n      res.setHeader(\"Content-Type\", resolvedType);\n      res.setHeader(\"X-Content-Type-Options\", \"nosniff\");\n\n      if (opts.mode === \"raw\") {\n        res.setHeader(\"Content-Security-Policy\", \"sandbox\");\n        if (!isSafeInlineContentType(resolvedType)) {\n          res.setHeader(\n            \"Content-Disposition\",\n            `attachment; filename=\"${fileName}\"`,\n          );\n        }\n      } else {\n        res.setHeader(\n          \"Content-Disposition\",\n          `attachment; filename=\"${fileName}\"`,\n        );\n      }\n\n      if (response.contents) {\n        const nodeStream = Readable.fromWeb(\n          response.contents as import(\"node:stream/web\").ReadableStream,\n        );\n        nodeStream.on(\"error\", (err) => {\n          logger.error(\"Stream error during %s: %O\", opts.mode, err);\n          if (!res.headersSent) {\n            res\n              .status(500)\n              .json({ error: `${label} failed`, plugin: this.name });\n          } else {\n            res.destroy();\n          }\n        });\n        nodeStream.pipe(res);\n      } else {\n        res.end();\n      }\n    } catch (error) {\n      this._handleApiError(res, error, `${label} failed`);\n    }\n  }\n\n  private async _handleExists(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    try {\n      const userPlugin = this.asUser(req);\n      const result = await userPlugin.execute(\n        async () => {\n          this.warnIfNoUserContext(volumeKey, `exists`);\n          return connector.exists(getWorkspaceClient(), path);\n        },\n        this._readSettings([\n          `files:${volumeKey}:exists`,\n          connector.resolvePath(path),\n        ]),\n      );\n\n      if (result === undefined) {\n        res\n          .status(500)\n          .json({ error: \"Exists check failed\", plugin: this.name });\n        return;\n      }\n      res.json({ exists: result });\n    } catch (error) {\n      this._handleApiError(res, error, \"Exists check failed\");\n    }\n  }\n\n  private async _handleMetadata(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    try {\n      const userPlugin = this.asUser(req);\n      const result = await userPlugin.execute(\n        async () => {\n          this.warnIfNoUserContext(volumeKey, `metadata`);\n          return connector.metadata(getWorkspaceClient(), path);\n        },\n        this._readSettings([\n          `files:${volumeKey}:metadata`,\n          connector.resolvePath(path),\n        ]),\n      );\n\n      if (result === undefined) {\n        res\n          .status(500)\n          .json({ error: \"Metadata fetch failed\", plugin: this.name });\n        return;\n      }\n      res.json(result);\n    } catch (error) {\n      this._handleApiError(res, error, \"Metadata fetch failed\");\n    }\n  }\n\n  private async _handlePreview(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    try {\n      const userPlugin = this.asUser(req);\n      const result = await userPlugin.execute(\n        async () => {\n          this.warnIfNoUserContext(volumeKey, `preview`);\n          return connector.preview(getWorkspaceClient(), path);\n        },\n        this._readSettings([\n          `files:${volumeKey}:preview`,\n          connector.resolvePath(path),\n        ]),\n      );\n\n      if (result === undefined) {\n        res.status(500).json({ error: \"Preview failed\", plugin: this.name });\n        return;\n      }\n      res.json(result);\n    } catch (error) {\n      this._handleApiError(res, error, \"Preview failed\");\n    }\n  }\n\n  private async _handleUpload(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    const volumeCfg = this.volumeConfigs[volumeKey];\n    const maxSize = volumeCfg.maxUploadSize ?? FILES_MAX_UPLOAD_SIZE;\n    const rawContentLength = req.headers[\"content-length\"];\n    const contentLength = rawContentLength\n      ? parseInt(rawContentLength, 10)\n      : undefined;\n\n    if (\n      contentLength !== undefined &&\n      !Number.isNaN(contentLength) &&\n      contentLength > maxSize\n    ) {\n      res.status(413).json({\n        error: `File size (${contentLength} bytes) exceeds maximum allowed size (${maxSize} bytes).`,\n        plugin: this.name,\n      });\n      return;\n    }\n\n    logger.debug(req, \"Upload started: volume=%s path=%s\", volumeKey, path);\n\n    try {\n      const rawStream: ReadableStream<Uint8Array> = Readable.toWeb(req);\n\n      let bytesReceived = 0;\n      const webStream = rawStream.pipeThrough(\n        new TransformStream<Uint8Array, Uint8Array>({\n          transform(chunk, controller) {\n            bytesReceived += chunk.byteLength;\n            if (bytesReceived > maxSize) {\n              controller.error(\n                new Error(\n                  `Upload stream exceeds maximum allowed size (${maxSize} bytes)`,\n                ),\n              );\n              return;\n            }\n            controller.enqueue(chunk);\n          },\n        }),\n      );\n\n      logger.debug(\n        req,\n        \"Upload body received: volume=%s path=%s, size=%d bytes\",\n        volumeKey,\n        path,\n        contentLength ?? 0,\n      );\n      const userPlugin = this.asUser(req);\n      const settings: PluginExecutionSettings = {\n        default: FILES_WRITE_DEFAULTS,\n      };\n      const result = await this.trackWrite(() =>\n        userPlugin.execute(async () => {\n          this.warnIfNoUserContext(volumeKey, `upload`);\n          await connector.upload(getWorkspaceClient(), path, webStream);\n          return { success: true as const };\n        }, settings),\n      );\n\n      this._invalidateListCache(\n        volumeKey,\n        path,\n        this.resolveUserId(req),\n        connector,\n      );\n\n      if (result === undefined) {\n        logger.error(\n          req,\n          \"Upload failed: volume=%s path=%s, size=%d bytes\",\n          volumeKey,\n          path,\n          contentLength ?? 0,\n        );\n        res.status(500).json({ error: \"Upload failed\", plugin: this.name });\n        return;\n      }\n\n      logger.debug(req, \"Upload complete: volume=%s path=%s\", volumeKey, path);\n      res.json(result);\n    } catch (error) {\n      if (\n        error instanceof Error &&\n        error.message.includes(\"exceeds maximum allowed size\")\n      ) {\n        res.status(413).json({ error: error.message, plugin: this.name });\n        return;\n      }\n      this._handleApiError(res, error, \"Upload failed\");\n    }\n  }\n\n  private async _handleMkdir(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const dirPath =\n      typeof req.body?.path === \"string\" ? req.body.path : undefined;\n    const valid = this._isValidPath(dirPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    try {\n      const userPlugin = this.asUser(req);\n      const settings: PluginExecutionSettings = {\n        default: FILES_WRITE_DEFAULTS,\n      };\n      const result = await this.trackWrite(() =>\n        userPlugin.execute(async () => {\n          this.warnIfNoUserContext(volumeKey, `createDirectory`);\n          await connector.createDirectory(getWorkspaceClient(), dirPath);\n          return { success: true as const };\n        }, settings),\n      );\n\n      this._invalidateListCache(\n        volumeKey,\n        dirPath,\n        this.resolveUserId(req),\n        connector,\n      );\n\n      if (result === undefined) {\n        res\n          .status(500)\n          .json({ error: \"Create directory failed\", plugin: this.name });\n        return;\n      }\n\n      res.json(result);\n    } catch (error) {\n      this._handleApiError(res, error, \"Create directory failed\");\n    }\n  }\n\n  private async _handleDelete(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const rawPath = req.query.path as string | undefined;\n    const valid = this._isValidPath(rawPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n    const path = rawPath as string;\n\n    try {\n      const userPlugin = this.asUser(req);\n      const settings: PluginExecutionSettings = {\n        default: FILES_WRITE_DEFAULTS,\n      };\n      const result = await this.trackWrite(() =>\n        userPlugin.execute(async () => {\n          this.warnIfNoUserContext(volumeKey, `delete`);\n          await connector.delete(getWorkspaceClient(), path);\n          return { success: true as const };\n        }, settings),\n      );\n\n      this._invalidateListCache(\n        volumeKey,\n        path,\n        this.resolveUserId(req),\n        connector,\n      );\n\n      if (result === undefined) {\n        res.status(500).json({ error: \"Delete failed\", plugin: this.name });\n        return;\n      }\n\n      res.json(result);\n    } catch (error) {\n      this._handleApiError(res, error, \"Delete failed\");\n    }\n  }\n\n  private inflightWrites = 0;\n\n  private trackWrite<T>(fn: () => Promise<T>): Promise<T> {\n    this.inflightWrites++;\n    return fn().finally(() => {\n      this.inflightWrites--;\n    });\n  }\n\n  async shutdown(): Promise<void> {\n    // Wait up to 10 seconds for in-flight write operations to finish\n    const deadline = Date.now() + 10_000;\n    while (this.inflightWrites > 0 && Date.now() < deadline) {\n      logger.info(\n        \"Waiting for %d in-flight write(s) to complete before shutdown…\",\n        this.inflightWrites,\n      );\n      await new Promise((resolve) => setTimeout(resolve, 500));\n    }\n    if (this.inflightWrites > 0) {\n      logger.warn(\n        \"Shutdown deadline reached with %d in-flight write(s) still pending.\",\n        this.inflightWrites,\n      );\n    }\n    this.streamManager.abortAll();\n  }\n\n  /**\n   * Returns the programmatic API for the Files plugin.\n   * Callable with a volume key to get a volume-scoped handle.\n   *\n   * @example\n   * ```ts\n   * // OBO access (recommended)\n   * appKit.files(\"uploads\").asUser(req).list()\n   *\n   * // Service principal access (logs a warning)\n   * appKit.files(\"uploads\").list()\n   * ```\n   */\n  exports(): FilesExport {\n    const resolveVolume = (volumeKey: string): VolumeHandle => {\n      if (!this.volumeKeys.includes(volumeKey)) {\n        throw new Error(\n          `Unknown volume \"${volumeKey}\". Available volumes: ${this.volumeKeys.join(\", \")}`,\n        );\n      }\n\n      // Service principal API — each method logs a warning recommending OBO\n      const spApi = this.createVolumeAPI(volumeKey);\n\n      return {\n        ...spApi,\n        asUser: (req: import(\"express\").Request) => {\n          const userPlugin = this.asUser(req) as FilesPlugin;\n          return userPlugin.createVolumeAPI(volumeKey);\n        },\n      };\n    };\n\n    const filesExport = ((volumeKey: string) =>\n      resolveVolume(volumeKey)) as FilesExport;\n    filesExport.volume = resolveVolume;\n\n    return filesExport;\n  }\n}\n\n/**\n * @internal\n */\nexport const files = toPlugin(FilesPlugin);\n"],"mappings":"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"}

package/dist/plugins/files/types.d.ts

@@ -0,0 +1,105 @@
+import { BasePluginConfig, IAppRequest } from "../../shared/src/plugin.js";
+import "../../shared/src/index.js";
+import { files } from "@databricks/sdk-experimental";
+
+//#region src/plugins/files/types.d.ts
+/**
+ * Per-volume configuration options.
+ */
+interface VolumeConfig {
+  /** Maximum upload size in bytes for this volume. Inherits from plugin-level `maxUploadSize` if not set. */
+  maxUploadSize?: number;
+  /** Map of file extensions to MIME types for this volume. Inherits from plugin-level `customContentTypes` if not set. */
+  customContentTypes?: Record<string, string>;
+}
+/**
+ * User-facing API for a single volume.
+ * Prefer OBO access via `app.files("volumeKey").asUser(req).list()`.
+ */
+interface VolumeAPI {
+  list(directoryPath?: string): Promise<DirectoryEntry[]>;
+  read(filePath: string, options?: {
+    maxSize?: number;
+  }): Promise<string>;
+  download(filePath: string): Promise<DownloadResponse>;
+  exists(filePath: string): Promise<boolean>;
+  metadata(filePath: string): Promise<FileMetadata>;
+  upload(filePath: string, contents: ReadableStream | Buffer | string, options?: {
+    overwrite?: boolean;
+  }): Promise<void>;
+  createDirectory(directoryPath: string): Promise<void>;
+  delete(filePath: string): Promise<void>;
+  preview(filePath: string): Promise<FilePreview>;
+}
+/**
+ * Configuration for the Files plugin.
+ */
+interface IFilesConfig extends BasePluginConfig {
+  /** Operation timeout in milliseconds. Overrides the per-tier defaults. */
+  timeout?: number;
+  /** Named volumes to expose. Each key becomes a volume accessor (e.g. `uploads`, `exports`). */
+  volumes?: Record<string, VolumeConfig>;
+  /** Map of file extensions to MIME types that takes priority over the built-in extension map. */
+  customContentTypes?: Record<string, string>;
+  /** Maximum upload size in bytes. Defaults to 5 GB (Databricks Files API v2 limit). */
+  maxUploadSize?: number;
+}
+/** A single entry returned when listing a directory. Re-exported from `@databricks/sdk-experimental`. */
+type DirectoryEntry = files.DirectoryEntry;
+/** Response object for file downloads containing a readable stream. Re-exported from `@databricks/sdk-experimental`. */
+type DownloadResponse = files.DownloadResponse;
+/**
+ * Metadata for a file stored in a Unity Catalog volume.
+ */
+interface FileMetadata {
+  /** File size in bytes. */
+  contentLength: number | undefined;
+  /** MIME content type of the file. */
+  contentType: string | undefined;
+  /** ISO 8601 timestamp of the last modification. */
+  lastModified: string | undefined;
+}
+/**
+ * Preview information for a file, extending {@link FileMetadata} with content hints.
+ */
+interface FilePreview extends FileMetadata {
+  /** First portion of text content, or `null` for non-text files. */
+  textPreview: string | null;
+  /** Whether the file is detected as a text format. */
+  isText: boolean;
+  /** Whether the file is detected as an image format. */
+  isImage: boolean;
+}
+/**
+ * Volume handle returned by `app.files("volumeKey")`.
+ *
+ * - `asUser(req)` — executes on behalf of the user (recommended).
+ * - Direct methods (e.g. `.list()`) — execute as the service principal (logs a warning encouraging OBO).
+ */
+type VolumeHandle = VolumeAPI & {
+  asUser: (req: IAppRequest) => VolumeAPI;
+};
+/**
+ * The public API shape of the files plugin.
+ * Callable to select a volume, with a `.volume()` alias.
+ *
+ * @example
+ * ```ts
+ * // OBO access (recommended)
+ * appKit.files("uploads").asUser(req).list()
+ *
+ * // Service principal access (logs a warning)
+ * appKit.files("uploads").list()
+ *
+ * // Named accessor
+ * const vol = appKit.files.volume("uploads")
+ * await vol.asUser(req).list()
+ * ```
+ */
+interface FilesExport {
+  (volumeKey: string): VolumeHandle;
+  volume: (volumeKey: string) => VolumeHandle;
+}
+//#endregion
+export { DirectoryEntry, DownloadResponse, FileMetadata, FilePreview, FilesExport, IFilesConfig, VolumeAPI, VolumeConfig, VolumeHandle };
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/files/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/plugins/files/types.ts"],"mappings":";;;;;;;;UAMiB,YAAA;EAAY;EAE3B,aAAA;EAE2B;EAA3B,kBAAA,GAAqB,MAAA;AAAA;;;;AAOvB;UAAiB,SAAA;EACf,IAAA,CAAK,aAAA,YAAyB,OAAA,CAAQ,cAAA;EACtC,IAAA,CAAK,QAAA,UAAkB,OAAA;IAAY,OAAA;EAAA,IAAqB,OAAA;EACxD,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,gBAAA;EACpC,MAAA,CAAO,QAAA,WAAmB,OAAA;EAC1B,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,YAAA;EACpC,MAAA,CACE,QAAA,UACA,QAAA,EAAU,cAAA,GAAiB,MAAA,WAC3B,OAAA;IAAY,SAAA;EAAA,IACX,OAAA;EACH,eAAA,CAAgB,aAAA,WAAwB,OAAA;EACxC,MAAA,CAAO,QAAA,WAAmB,OAAA;EAC1B,OAAA,CAAQ,QAAA,WAAmB,OAAA,CAAQ,WAAA;AAAA;;;;UAMpB,YAAA,SAAqB,gBAAA;EAlBpC;EAoBA,OAAA;EApB8B;EAsB9B,OAAA,GAAU,MAAA,SAAe,YAAA;EArBzB;EAuBA,kBAAA,GAAqB,MAAA;EAvBc;EAyBnC,aAAA;AAAA;;KAIU,cAAA,GAAiB,KAAA,CAAM,cAAA;;KAGvB,gBAAA,GAAmB,KAAA,CAAM,gBAAA;;;;UAKpB,YAAA;EAlCN;EAoCT,aAAA;EApCoC;EAsCpC,WAAA;EApCE;EAsCF,YAAA;AAAA;;;;UAMe,WAAA,SAAoB,YAAA;EAxCnC;EA0CA,WAAA;EA1CwC;EA4CxC,MAAA;EA3CO;EA6CP,OAAA;AAAA;;;;;;AAtCF;KA+CY,YAAA,GAAe,SAAA;EACzB,MAAA,GAAS,GAAA,EAAK,WAAA,KAAgB,SAAA;AAAA;;;;;;;;;;;;;;;;AApChC;;UAwDiB,WAAA;EAAA,CACd,SAAA,WAAoB,YAAA;EACrB,MAAA,GAAS,SAAA,aAAsB,YAAA;AAAA"}

package/dist/plugins/genie/genie.d.ts

@@ -11,8 +11,7 @@ import express from "express";
 
 //#region src/plugins/genie/genie.d.ts
 declare class GeniePlugin extends Plugin {
-  name: string;
-  static manifest: PluginManifest;
+  static manifest: PluginManifest<"genie">;
   protected static description: string;
   protected config: IGenieConfig;
   private readonly genieConnector;

package/dist/plugins/genie/genie.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"genie.d.ts","names":[],"sources":["../../../src/plugins/genie/genie.ts"],"mappings":";;;;;;;;;;;;cAmBa,WAAA,SAAoB,MAAA;EAC/B,IAAA;EAAA,OAEO,QAAA,EAAuB,cAAA;EAAA,iBAEb,WAAA;EAAA,UAEC,MAAA,EAAQ,YAAA;EAAA,iBAET,cAAA;cAEL,MAAA,EAAQ,YAAA;EAAA,QAYZ,aAAA;EAAA,QAKA,cAAA;EAIR,YAAA,CAAa,MAAA,EAAQ,UAAA;EAoBf,kBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EAwDG,sBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EAgDG,eAAA,CACJ,KAAA,UACA,cAAA,WACC,OAAA,CAAQ,gCAAA;EArIU;;;;EAyJd,WAAA,CACL,KAAA,UACA,OAAA,UACA,cAAA,WACA,OAAA;IAAY,OAAA;EAAA,IACX,cAAA,CAAe,gBAAA;EAgBZ,QAAA,CAAA,GAAY,OAAA;EAIlB,OAAA,CAAA;iCAxBe,OAAA,UACE,cAAA,WACQ,OAAA;MACX,OAAA;IAAA,MACX,cAAA,CAAe,gBAAA;qCA3BH,cAAA,aAEZ,OAAA,CAAQ,gCAAA;EAAA;AAAA;;;;cAwDA,KAAA,EAAK,QAAA,QAAA,WAAA,EAAA,YAAA"}
+{"version":3,"file":"genie.d.ts","names":[],"sources":["../../../src/plugins/genie/genie.ts"],"mappings":";;;;;;;;;;;;cAmBa,WAAA,SAAoB,MAAA;EAAA,OACxB,QAAA,EAAuB,cAAA;EAAA,iBAEb,WAAA;EAAA,UAEC,MAAA,EAAQ,YAAA;EAAA,iBAET,cAAA;cAEL,MAAA,EAAQ,YAAA;EAAA,QAYZ,aAAA;EAAA,QAKA,cAAA;EAIR,YAAA,CAAa,MAAA,EAAQ,UAAA;EAoBf,kBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EAwDG,sBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EAgDG,eAAA,CACJ,KAAA,UACA,cAAA,WACC,OAAA,CAAQ,gCAAA;EA1JS;;;;EA8Kb,WAAA,CACL,KAAA,UACA,OAAA,UACA,cAAA,WACA,OAAA;IAAY,OAAA;EAAA,IACX,cAAA,CAAe,gBAAA;EAgBZ,QAAA,CAAA,GAAY,OAAA;EAIlB,OAAA,CAAA;iCAxBe,OAAA,UACE,cAAA,WACQ,OAAA;MACX,OAAA;IAAA,MACX,cAAA,CAAe,gBAAA;qCA3BH,cAAA,aAEZ,OAAA,CAAQ,gCAAA;EAAA;AAAA;;;;cAwDA,KAAA,EAAK,QAAA,QAAA,WAAA,EAAA,YAAA"}

package/dist/plugins/genie/genie.js

@@ -15,7 +15,6 @@ import { randomUUID } from "node:crypto";
 init_context();
 const logger = createLogger("genie");
 var GeniePlugin = class extends Plugin {
-	name = "genie";
 	static manifest = manifest_default;
 	static description = "AI/BI Genie space integration for natural language data queries";
 	genieConnector;
@@ -138,7 +137,7 @@ var GeniePlugin = class extends Plugin {
 /**
 * @internal
 */
-const genie = toPlugin(GeniePlugin, "genie");
+const genie = toPlugin(GeniePlugin);
 
 //#endregion
 export { GeniePlugin, genie };

package/dist/plugins/genie/genie.js.map

@@ -1 +1 @@
-{"version":3,"file":"genie.js","names":["manifest"],"sources":["../../../src/plugins/genie/genie.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type express from \"express\";\nimport type { IAppRouter, StreamExecutionSettings } from \"shared\";\nimport { GenieConnector } from \"../../connectors\";\nimport { getWorkspaceClient } from \"../../context\";\nimport { createLogger } from \"../../logging\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { genieStreamDefaults } from \"./defaults\";\nimport manifest from \"./manifest.json\";\nimport type {\n  GenieConversationHistoryResponse,\n  GenieSendMessageRequest,\n  GenieStreamEvent,\n  IGenieConfig,\n} from \"./types\";\n\nconst logger = createLogger(\"genie\");\n\nexport class GeniePlugin extends Plugin {\n  name = \"genie\";\n\n  static manifest = manifest as PluginManifest;\n\n  protected static description =\n    \"AI/BI Genie space integration for natural language data queries\";\n  protected declare config: IGenieConfig;\n\n  private readonly genieConnector: GenieConnector;\n\n  constructor(config: IGenieConfig) {\n    super(config);\n    this.config = {\n      ...config,\n      spaces: config.spaces ?? this.defaultSpaces(),\n    };\n    this.genieConnector = new GenieConnector({\n      timeout: this.config.timeout,\n      maxMessages: 200,\n    });\n  }\n\n  private defaultSpaces(): Record<string, string> {\n    const spaceId = process.env.DATABRICKS_GENIE_SPACE_ID;\n    return spaceId ? { default: spaceId } : {};\n  }\n\n  private resolveSpaceId(alias: string): string | null {\n    return this.config.spaces?.[alias] ?? null;\n  }\n\n  injectRoutes(router: IAppRouter) {\n    this.route(router, {\n      name: \"sendMessage\",\n      method: \"post\",\n      path: \"/:alias/messages\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this.asUser(req)._handleSendMessage(req, res);\n      },\n    });\n\n    this.route(router, {\n      name: \"getConversation\",\n      method: \"get\",\n      path: \"/:alias/conversations/:conversationId\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this.asUser(req)._handleGetConversation(req, res);\n      },\n    });\n  }\n\n  async _handleSendMessage(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { alias } = req.params;\n    const spaceId = this.resolveSpaceId(alias);\n\n    if (!spaceId) {\n      res.status(404).json({ error: `Unknown space alias: ${alias}` });\n      return;\n    }\n\n    const { content, conversationId } = req.body as GenieSendMessageRequest;\n\n    if (!content) {\n      res.status(400).json({ error: \"content is required\" });\n      return;\n    }\n\n    logger.debug(\n      \"Sending message to space %s (alias=%s, conversationId=%s)\",\n      spaceId,\n      alias,\n      conversationId ?? \"new\",\n    );\n\n    const timeout = this.config.timeout ?? 120_000;\n    const requestId =\n      (typeof req.query.requestId === \"string\" && req.query.requestId) ||\n      randomUUID();\n\n    const streamSettings: StreamExecutionSettings = {\n      ...genieStreamDefaults,\n      default: {\n        ...genieStreamDefaults.default,\n        timeout,\n      },\n      stream: {\n        ...genieStreamDefaults.stream,\n        streamId: requestId,\n      },\n    };\n\n    const workspaceClient = getWorkspaceClient();\n\n    await this.executeStream<GenieStreamEvent>(\n      res,\n      () =>\n        this.genieConnector.streamSendMessage(\n          workspaceClient,\n          spaceId,\n          content,\n          conversationId,\n          { timeout },\n        ),\n      streamSettings,\n    );\n  }\n\n  async _handleGetConversation(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { alias, conversationId } = req.params;\n    const spaceId = this.resolveSpaceId(alias);\n\n    if (!spaceId) {\n      res.status(404).json({ error: `Unknown space alias: ${alias}` });\n      return;\n    }\n\n    const includeQueryResults = req.query.includeQueryResults !== \"false\";\n    const pageToken =\n      typeof req.query.pageToken === \"string\" ? req.query.pageToken : undefined;\n    const requestId =\n      (typeof req.query.requestId === \"string\" && req.query.requestId) ||\n      randomUUID();\n\n    logger.debug(\n      \"Fetching conversation %s from space %s (alias=%s, includeQueryResults=%s, pageToken=%s)\",\n      conversationId,\n      spaceId,\n      alias,\n      includeQueryResults,\n      pageToken ?? \"none\",\n    );\n\n    const streamSettings: StreamExecutionSettings = {\n      ...genieStreamDefaults,\n      stream: {\n        ...genieStreamDefaults.stream,\n        streamId: requestId,\n      },\n    };\n\n    const workspaceClient = getWorkspaceClient();\n\n    await this.executeStream<GenieStreamEvent>(\n      res,\n      () =>\n        this.genieConnector.streamConversation(\n          workspaceClient,\n          spaceId,\n          conversationId,\n          { includeQueryResults, pageToken },\n        ),\n      streamSettings,\n    );\n  }\n\n  async getConversation(\n    alias: string,\n    conversationId: string,\n  ): Promise<GenieConversationHistoryResponse> {\n    const spaceId = this.resolveSpaceId(alias);\n\n    if (!spaceId) {\n      throw new Error(`Unknown space alias: ${alias}`);\n    }\n\n    const workspaceClient = getWorkspaceClient();\n\n    return this.genieConnector.getConversation(\n      workspaceClient,\n      spaceId,\n      conversationId,\n    );\n  }\n\n  /**\n   * Send a message and consume events as a stream (message_start, status,\n   * message_result, query_result, error).\n   */\n  async *sendMessage(\n    alias: string,\n    content: string,\n    conversationId?: string,\n    options?: { timeout?: number },\n  ): AsyncGenerator<GenieStreamEvent> {\n    const spaceId = this.resolveSpaceId(alias);\n    if (!spaceId) {\n      throw new Error(`Unknown space alias: ${alias}`);\n    }\n    const workspaceClient = getWorkspaceClient();\n    const timeout = options?.timeout ?? this.config.timeout ?? 120_000;\n    yield* this.genieConnector.streamSendMessage(\n      workspaceClient,\n      spaceId,\n      content,\n      conversationId,\n      { timeout },\n    );\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n\n  exports() {\n    return {\n      sendMessage: this.sendMessage,\n      getConversation: this.getConversation,\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const genie = toPlugin<typeof GeniePlugin, IGenieConfig, \"genie\">(\n  GeniePlugin,\n  \"genie\",\n);\n"],"mappings":"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"}
+{"version":3,"file":"genie.js","names":["manifest"],"sources":["../../../src/plugins/genie/genie.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type express from \"express\";\nimport type { IAppRouter, StreamExecutionSettings } from \"shared\";\nimport { GenieConnector } from \"../../connectors\";\nimport { getWorkspaceClient } from \"../../context\";\nimport { createLogger } from \"../../logging\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { genieStreamDefaults } from \"./defaults\";\nimport manifest from \"./manifest.json\";\nimport type {\n  GenieConversationHistoryResponse,\n  GenieSendMessageRequest,\n  GenieStreamEvent,\n  IGenieConfig,\n} from \"./types\";\n\nconst logger = createLogger(\"genie\");\n\nexport class GeniePlugin extends Plugin {\n  static manifest = manifest as PluginManifest<\"genie\">;\n\n  protected static description =\n    \"AI/BI Genie space integration for natural language data queries\";\n  protected declare config: IGenieConfig;\n\n  private readonly genieConnector: GenieConnector;\n\n  constructor(config: IGenieConfig) {\n    super(config);\n    this.config = {\n      ...config,\n      spaces: config.spaces ?? this.defaultSpaces(),\n    };\n    this.genieConnector = new GenieConnector({\n      timeout: this.config.timeout,\n      maxMessages: 200,\n    });\n  }\n\n  private defaultSpaces(): Record<string, string> {\n    const spaceId = process.env.DATABRICKS_GENIE_SPACE_ID;\n    return spaceId ? { default: spaceId } : {};\n  }\n\n  private resolveSpaceId(alias: string): string | null {\n    return this.config.spaces?.[alias] ?? null;\n  }\n\n  injectRoutes(router: IAppRouter) {\n    this.route(router, {\n      name: \"sendMessage\",\n      method: \"post\",\n      path: \"/:alias/messages\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this.asUser(req)._handleSendMessage(req, res);\n      },\n    });\n\n    this.route(router, {\n      name: \"getConversation\",\n      method: \"get\",\n      path: \"/:alias/conversations/:conversationId\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this.asUser(req)._handleGetConversation(req, res);\n      },\n    });\n  }\n\n  async _handleSendMessage(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { alias } = req.params;\n    const spaceId = this.resolveSpaceId(alias);\n\n    if (!spaceId) {\n      res.status(404).json({ error: `Unknown space alias: ${alias}` });\n      return;\n    }\n\n    const { content, conversationId } = req.body as GenieSendMessageRequest;\n\n    if (!content) {\n      res.status(400).json({ error: \"content is required\" });\n      return;\n    }\n\n    logger.debug(\n      \"Sending message to space %s (alias=%s, conversationId=%s)\",\n      spaceId,\n      alias,\n      conversationId ?? \"new\",\n    );\n\n    const timeout = this.config.timeout ?? 120_000;\n    const requestId =\n      (typeof req.query.requestId === \"string\" && req.query.requestId) ||\n      randomUUID();\n\n    const streamSettings: StreamExecutionSettings = {\n      ...genieStreamDefaults,\n      default: {\n        ...genieStreamDefaults.default,\n        timeout,\n      },\n      stream: {\n        ...genieStreamDefaults.stream,\n        streamId: requestId,\n      },\n    };\n\n    const workspaceClient = getWorkspaceClient();\n\n    await this.executeStream<GenieStreamEvent>(\n      res,\n      () =>\n        this.genieConnector.streamSendMessage(\n          workspaceClient,\n          spaceId,\n          content,\n          conversationId,\n          { timeout },\n        ),\n      streamSettings,\n    );\n  }\n\n  async _handleGetConversation(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { alias, conversationId } = req.params;\n    const spaceId = this.resolveSpaceId(alias);\n\n    if (!spaceId) {\n      res.status(404).json({ error: `Unknown space alias: ${alias}` });\n      return;\n    }\n\n    const includeQueryResults = req.query.includeQueryResults !== \"false\";\n    const pageToken =\n      typeof req.query.pageToken === \"string\" ? req.query.pageToken : undefined;\n    const requestId =\n      (typeof req.query.requestId === \"string\" && req.query.requestId) ||\n      randomUUID();\n\n    logger.debug(\n      \"Fetching conversation %s from space %s (alias=%s, includeQueryResults=%s, pageToken=%s)\",\n      conversationId,\n      spaceId,\n      alias,\n      includeQueryResults,\n      pageToken ?? \"none\",\n    );\n\n    const streamSettings: StreamExecutionSettings = {\n      ...genieStreamDefaults,\n      stream: {\n        ...genieStreamDefaults.stream,\n        streamId: requestId,\n      },\n    };\n\n    const workspaceClient = getWorkspaceClient();\n\n    await this.executeStream<GenieStreamEvent>(\n      res,\n      () =>\n        this.genieConnector.streamConversation(\n          workspaceClient,\n          spaceId,\n          conversationId,\n          { includeQueryResults, pageToken },\n        ),\n      streamSettings,\n    );\n  }\n\n  async getConversation(\n    alias: string,\n    conversationId: string,\n  ): Promise<GenieConversationHistoryResponse> {\n    const spaceId = this.resolveSpaceId(alias);\n\n    if (!spaceId) {\n      throw new Error(`Unknown space alias: ${alias}`);\n    }\n\n    const workspaceClient = getWorkspaceClient();\n\n    return this.genieConnector.getConversation(\n      workspaceClient,\n      spaceId,\n      conversationId,\n    );\n  }\n\n  /**\n   * Send a message and consume events as a stream (message_start, status,\n   * message_result, query_result, error).\n   */\n  async *sendMessage(\n    alias: string,\n    content: string,\n    conversationId?: string,\n    options?: { timeout?: number },\n  ): AsyncGenerator<GenieStreamEvent> {\n    const spaceId = this.resolveSpaceId(alias);\n    if (!spaceId) {\n      throw new Error(`Unknown space alias: ${alias}`);\n    }\n    const workspaceClient = getWorkspaceClient();\n    const timeout = options?.timeout ?? this.config.timeout ?? 120_000;\n    yield* this.genieConnector.streamSendMessage(\n      workspaceClient,\n      spaceId,\n      content,\n      conversationId,\n      { timeout },\n    );\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n\n  exports() {\n    return {\n      sendMessage: this.sendMessage,\n      getConversation: this.getConversation,\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const genie = toPlugin(GeniePlugin);\n"],"mappings":"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"}

package/dist/plugins/index.d.ts

@@ -2,6 +2,9 @@ import { GenieAttachmentResponse, GenieMessageResponse, GenieStreamEvent } from
 import { IAnalyticsConfig } from "./analytics/types.js";
 import { AnalyticsPlugin, analytics } from "./analytics/analytics.js";
 import "./analytics/index.js";
+import { DirectoryEntry, DownloadResponse, FileMetadata, FilePreview, FilesExport, IFilesConfig, VolumeAPI, VolumeConfig, VolumeHandle } from "./files/types.js";
+import { FilesPlugin, files } from "./files/plugin.js";
+import "./files/index.js";
 import { GenieConversationHistoryResponse } from "../connectors/genie/types.js";
 import { IGenieConfig } from "./genie/types.js";
 import { GeniePlugin, genie } from "./genie/genie.js";

package/dist/plugins/index.js

@@ -1,5 +1,9 @@
+import { EXTENSION_CONTENT_TYPES, FILES_MAX_READ_SIZE } from "../connectors/files/defaults.js";
 import { AnalyticsPlugin, analytics } from "./analytics/analytics.js";
 import "./analytics/index.js";
+import { FILES_DOWNLOAD_DEFAULTS, FILES_MAX_UPLOAD_SIZE, FILES_READ_DEFAULTS, FILES_WRITE_DEFAULTS } from "./files/defaults.js";
+import { FilesPlugin, files } from "./files/plugin.js";
+import "./files/index.js";
 import { GeniePlugin, genie } from "./genie/genie.js";
 import "./genie/index.js";
 import { LakebasePlugin, lakebase } from "./lakebase/lakebase.js";

package/dist/plugins/lakebase/lakebase.d.ts

@@ -28,9 +28,8 @@ import * as stream from "stream";
  * ```
  */
 declare class LakebasePlugin extends Plugin {
-  name: string;
   /** Plugin manifest declaring metadata and resource requirements */
-  static manifest: PluginManifest;
+  static manifest: PluginManifest<"lakebase">;
   protected config: ILakebaseConfig;
   private pool;
   constructor(config: ILakebaseConfig);

package/dist/plugins/lakebase/lakebase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lakebase.d.ts","names":[],"sources":["../../../src/plugins/lakebase/lakebase.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgCA;;;;;;;;;cAAa,cAAA,SAAuB,MAAA;EAClC,IAAA;;SAGO,QAAA,EAAuB,cAAA;EAAA,UAEZ,MAAA,EAAQ,eAAA;EAAA,QAClB,IAAA;cAEI,MAAA,EAAQ,eAAA;;;;;;;;EAYd,KAAA,CAAA,GAAK,OAAA;EArB6B;;;;;;;;;;;;;;;EA2ClC,KAAA,WAAgB,cAAA,OAAA,CACpB,IAAA,UACA,MAAA,eACC,OAAA,CAAQ,WAAA,CAAY,CAAA;EAFrB;;;;EAWF,qBAAA,CAAA;EAAA;;;;;;;;EAmBA,OAAA,CAAA;;sBA/BsB,cAAA,QAAc,IAAA,UACtB,MAAA,iBAEX,OAAA,CAAQ,WAAA,CAAY,CAAA;;;;;;;;;;iBAtBY,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAgExB,QAAA,EAAQ,QAAA,QAAA,cAAA,EAAA,eAAA"}
+{"version":3,"file":"lakebase.d.ts","names":[],"sources":["../../../src/plugins/lakebase/lakebase.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgCA;;;;;;;;;cAAa,cAAA,SAAuB,MAAA;EA4C/B;EAAA,OA1CI,QAAA,EAAuB,cAAA;EAAA,UAEZ,MAAA,EAAQ,eAAA;EAAA,QAClB,IAAA;cAEI,MAAA,EAAQ,eAAA;EAqCjB;;;;;;;EAzBG,KAAA,CAAA,GAAK,OAAA;EAnB6B;;;;;;;;;;;;;;;EAyClC,KAAA,WAAgB,cAAA,OAAA,CACpB,IAAA,UACA,MAAA,eACC,OAAA,CAAQ,WAAA,CAAY,CAAA;EAFrB;;;;EAWF,qBAAA,CAAA;EAAA;;;;;;;;EAmBA,OAAA,CAAA;;sBA/BsB,cAAA,QAAc,IAAA,UACtB,MAAA,iBAEX,OAAA,CAAQ,WAAA,CAAY,CAAA;;;;;;;;;;iBAtBsB,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAgElC,QAAA,EAAQ,QAAA,QAAA,cAAA,EAAA,eAAA"}

package/dist/plugins/lakebase/lakebase.js

@@ -25,7 +25,6 @@ const logger = createLogger("lakebase");
 * ```
 */
 var LakebasePlugin = class extends Plugin {
-	name = "lakebase";
 	/** Plugin manifest declaring metadata and resource requirements */
 	static manifest = manifest_default;
 	pool = null;
@@ -101,7 +100,7 @@ var LakebasePlugin = class extends Plugin {
 /**
 * @internal
 */
-const lakebase = toPlugin(LakebasePlugin, "lakebase");
+const lakebase = toPlugin(LakebasePlugin);
 
 //#endregion
 export { LakebasePlugin, lakebase };

package/dist/plugins/lakebase/lakebase.js.map

@@ -1 +1 @@
-{"version":3,"file":"lakebase.js","names":["manifest"],"sources":["../../../src/plugins/lakebase/lakebase.ts"],"sourcesContent":["import type { Pool, QueryResult, QueryResultRow } from \"pg\";\nimport {\n  createLakebasePool,\n  getLakebaseOrmConfig,\n  getLakebasePgConfig,\n  getUsernameWithApiLookup,\n} from \"../../connectors/lakebase\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport manifest from \"./manifest.json\";\nimport type { ILakebaseConfig } from \"./types\";\n\nconst logger = createLogger(\"lakebase\");\n\n/**\n * AppKit plugin for Databricks Lakebase Autoscaling.\n *\n * Wraps `@databricks/lakebase` to provide a standard `pg.Pool` with automatic\n * OAuth token refresh, integrated with AppKit's logger and OpenTelemetry setup.\n *\n * @example\n * ```ts\n * import { createApp, lakebase, server } from \"@databricks/appkit\";\n *\n * const AppKit = await createApp({\n *   plugins: [server(), lakebase()],\n * });\n *\n * const result = await AppKit.lakebase.query(\"SELECT * FROM users WHERE id = $1\", [userId]);\n * ```\n */\nexport class LakebasePlugin extends Plugin {\n  name = \"lakebase\";\n\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest;\n\n  protected declare config: ILakebaseConfig;\n  private pool: Pool | null = null;\n\n  constructor(config: ILakebaseConfig) {\n    super(config);\n    this.config = config;\n  }\n\n  /**\n   * Initializes the Lakebase connection pool.\n   * Called automatically by AppKit during the plugin setup phase.\n   *\n   * Resolves the PostgreSQL username via {@link getUsernameWithApiLookup},\n   * which tries config, env vars, and finally the Databricks workspace API.\n   */\n  async setup() {\n    const poolConfig = this.config.pool;\n    const user = await getUsernameWithApiLookup(poolConfig);\n    this.pool = createLakebasePool({ ...poolConfig, user });\n    logger.info(\"Lakebase pool initialized\");\n  }\n\n  /**\n   * Executes a parameterized SQL query against the Lakebase pool.\n   *\n   * @param text - SQL query string, using `$1`, `$2`, ... placeholders\n   * @param values - Parameter values corresponding to placeholders\n   * @returns Query result with typed rows\n   *\n   * @example\n   * ```ts\n   * const result = await AppKit.lakebase.query<{ id: number; name: string }>(\n   *   \"SELECT id, name FROM users WHERE active = $1\",\n   *   [true],\n   * );\n   * ```\n   */\n  async query<T extends QueryResultRow = any>(\n    text: string,\n    values?: unknown[],\n  ): Promise<QueryResult<T>> {\n    // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup(), which AppKit always awaits before exposing the plugin API\n    return this.pool!.query<T>(text, values);\n  }\n\n  /**\n   * Gracefully drains and closes the connection pool.\n   * Called automatically by AppKit during shutdown.\n   */\n  abortActiveOperations(): void {\n    super.abortActiveOperations();\n    if (this.pool) {\n      logger.info(\"Closing Lakebase pool\");\n      this.pool.end().catch((err) => {\n        logger.error(\"Error closing Lakebase pool: %O\", err);\n      });\n      this.pool = null;\n    }\n  }\n\n  /**\n   * Returns the plugin's public API, accessible via `AppKit.lakebase`.\n   *\n   * - `pool` — The raw `pg.Pool` instance, for use with ORMs or advanced scenarios\n   * - `query` — Convenience method for executing parameterized SQL queries\n   * - `getOrmConfig()` — Returns a config object compatible with Drizzle, TypeORM, Sequelize, etc.\n   * - `getPgConfig()` — Returns a `pg.PoolConfig` object for manual pool construction\n   */\n  exports() {\n    return {\n      // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup(), which AppKit always awaits before exposing the plugin API\n      pool: this.pool!,\n      query: this.query.bind(this),\n      getOrmConfig: () => getLakebaseOrmConfig(this.config.pool),\n      getPgConfig: () => getLakebasePgConfig(this.config.pool),\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const lakebase = toPlugin<\n  typeof LakebasePlugin,\n  ILakebaseConfig,\n  \"lakebase\"\n>(LakebasePlugin, \"lakebase\");\n"],"mappings":";;;;;;;;AAaA,MAAM,SAAS,aAAa,WAAW;;;;;;;;;;;;;;;;;;AAmBvC,IAAa,iBAAb,cAAoC,OAAO;CACzC,OAAO;;CAGP,OAAO,WAAWA;CAGlB,AAAQ,OAAoB;CAE5B,YAAY,QAAyB;AACnC,QAAM,OAAO;AACb,OAAK,SAAS;;;;;;;;;CAUhB,MAAM,QAAQ;EACZ,MAAM,aAAa,KAAK,OAAO;EAC/B,MAAM,OAAO,MAAM,yBAAyB,WAAW;AACvD,OAAK,OAAO,mBAAmB;GAAE,GAAG;GAAY;GAAM,CAAC;AACvD,SAAO,KAAK,4BAA4B;;;;;;;;;;;;;;;;;CAkB1C,MAAM,MACJ,MACA,QACyB;AAEzB,SAAO,KAAK,KAAM,MAAS,MAAM,OAAO;;;;;;CAO1C,wBAA8B;AAC5B,QAAM,uBAAuB;AAC7B,MAAI,KAAK,MAAM;AACb,UAAO,KAAK,wBAAwB;AACpC,QAAK,KAAK,KAAK,CAAC,OAAO,QAAQ;AAC7B,WAAO,MAAM,mCAAmC,IAAI;KACpD;AACF,QAAK,OAAO;;;;;;;;;;;CAYhB,UAAU;AACR,SAAO;GAEL,MAAM,KAAK;GACX,OAAO,KAAK,MAAM,KAAK,KAAK;GAC5B,oBAAoB,qBAAqB,KAAK,OAAO,KAAK;GAC1D,mBAAmB,oBAAoB,KAAK,OAAO,KAAK;GACzD;;;;;;AAOL,MAAa,WAAW,SAItB,gBAAgB,WAAW"}
+{"version":3,"file":"lakebase.js","names":["manifest"],"sources":["../../../src/plugins/lakebase/lakebase.ts"],"sourcesContent":["import type { Pool, QueryResult, QueryResultRow } from \"pg\";\nimport {\n  createLakebasePool,\n  getLakebaseOrmConfig,\n  getLakebasePgConfig,\n  getUsernameWithApiLookup,\n} from \"../../connectors/lakebase\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport manifest from \"./manifest.json\";\nimport type { ILakebaseConfig } from \"./types\";\n\nconst logger = createLogger(\"lakebase\");\n\n/**\n * AppKit plugin for Databricks Lakebase Autoscaling.\n *\n * Wraps `@databricks/lakebase` to provide a standard `pg.Pool` with automatic\n * OAuth token refresh, integrated with AppKit's logger and OpenTelemetry setup.\n *\n * @example\n * ```ts\n * import { createApp, lakebase, server } from \"@databricks/appkit\";\n *\n * const AppKit = await createApp({\n *   plugins: [server(), lakebase()],\n * });\n *\n * const result = await AppKit.lakebase.query(\"SELECT * FROM users WHERE id = $1\", [userId]);\n * ```\n */\nexport class LakebasePlugin extends Plugin {\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"lakebase\">;\n\n  protected declare config: ILakebaseConfig;\n  private pool: Pool | null = null;\n\n  constructor(config: ILakebaseConfig) {\n    super(config);\n    this.config = config;\n  }\n\n  /**\n   * Initializes the Lakebase connection pool.\n   * Called automatically by AppKit during the plugin setup phase.\n   *\n   * Resolves the PostgreSQL username via {@link getUsernameWithApiLookup},\n   * which tries config, env vars, and finally the Databricks workspace API.\n   */\n  async setup() {\n    const poolConfig = this.config.pool;\n    const user = await getUsernameWithApiLookup(poolConfig);\n    this.pool = createLakebasePool({ ...poolConfig, user });\n    logger.info(\"Lakebase pool initialized\");\n  }\n\n  /**\n   * Executes a parameterized SQL query against the Lakebase pool.\n   *\n   * @param text - SQL query string, using `$1`, `$2`, ... placeholders\n   * @param values - Parameter values corresponding to placeholders\n   * @returns Query result with typed rows\n   *\n   * @example\n   * ```ts\n   * const result = await AppKit.lakebase.query<{ id: number; name: string }>(\n   *   \"SELECT id, name FROM users WHERE active = $1\",\n   *   [true],\n   * );\n   * ```\n   */\n  async query<T extends QueryResultRow = any>(\n    text: string,\n    values?: unknown[],\n  ): Promise<QueryResult<T>> {\n    // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup(), which AppKit always awaits before exposing the plugin API\n    return this.pool!.query<T>(text, values);\n  }\n\n  /**\n   * Gracefully drains and closes the connection pool.\n   * Called automatically by AppKit during shutdown.\n   */\n  abortActiveOperations(): void {\n    super.abortActiveOperations();\n    if (this.pool) {\n      logger.info(\"Closing Lakebase pool\");\n      this.pool.end().catch((err) => {\n        logger.error(\"Error closing Lakebase pool: %O\", err);\n      });\n      this.pool = null;\n    }\n  }\n\n  /**\n   * Returns the plugin's public API, accessible via `AppKit.lakebase`.\n   *\n   * - `pool` — The raw `pg.Pool` instance, for use with ORMs or advanced scenarios\n   * - `query` — Convenience method for executing parameterized SQL queries\n   * - `getOrmConfig()` — Returns a config object compatible with Drizzle, TypeORM, Sequelize, etc.\n   * - `getPgConfig()` — Returns a `pg.PoolConfig` object for manual pool construction\n   */\n  exports() {\n    return {\n      // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup(), which AppKit always awaits before exposing the plugin API\n      pool: this.pool!,\n      query: this.query.bind(this),\n      getOrmConfig: () => getLakebaseOrmConfig(this.config.pool),\n      getPgConfig: () => getLakebasePgConfig(this.config.pool),\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const lakebase = toPlugin(LakebasePlugin);\n"],"mappings":";;;;;;;;AAaA,MAAM,SAAS,aAAa,WAAW;;;;;;;;;;;;;;;;;;AAmBvC,IAAa,iBAAb,cAAoC,OAAO;;CAEzC,OAAO,WAAWA;CAGlB,AAAQ,OAAoB;CAE5B,YAAY,QAAyB;AACnC,QAAM,OAAO;AACb,OAAK,SAAS;;;;;;;;;CAUhB,MAAM,QAAQ;EACZ,MAAM,aAAa,KAAK,OAAO;EAC/B,MAAM,OAAO,MAAM,yBAAyB,WAAW;AACvD,OAAK,OAAO,mBAAmB;GAAE,GAAG;GAAY;GAAM,CAAC;AACvD,SAAO,KAAK,4BAA4B;;;;;;;;;;;;;;;;;CAkB1C,MAAM,MACJ,MACA,QACyB;AAEzB,SAAO,KAAK,KAAM,MAAS,MAAM,OAAO;;;;;;CAO1C,wBAA8B;AAC5B,QAAM,uBAAuB;AAC7B,MAAI,KAAK,MAAM;AACb,UAAO,KAAK,wBAAwB;AACpC,QAAK,KAAK,KAAK,CAAC,OAAO,QAAQ;AAC7B,WAAO,MAAM,mCAAmC,IAAI;KACpD;AACF,QAAK,OAAO;;;;;;;;;;;CAYhB,UAAU;AACR,SAAO;GAEL,MAAM,KAAK;GACX,OAAO,KAAK,MAAM,KAAK,KAAK;GAC5B,oBAAoB,qBAAqB,KAAK,OAAO,KAAK;GAC1D,mBAAmB,oBAAoB,KAAK,OAAO,KAAK;GACzD;;;;;;AAOL,MAAa,WAAW,SAAS,eAAe"}

package/dist/plugins/server/index.d.ts

@@ -30,14 +30,14 @@ declare class ServerPlugin extends Plugin {
     port: number;
   };
   /** Plugin manifest declaring metadata and resource requirements */
-  static manifest: PluginManifest;
-  name: "server";
+  static manifest: PluginManifest<"server">;
   private serverApplication;
   private server;
   private viteDevServer?;
   private remoteTunnelController?;
   protected config: ServerConfig;
   private serverExtensions;
+  private rawBodyPaths;
   static phase: PluginPhase;
   constructor(config: ServerConfig);
   /** Setup the server plugin. */

package/dist/plugins/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/plugins/server/index.ts"],"mappings":";;;;;;;;;;;;;;;;AAoCA;;;;;;;;;cAAa,YAAA,SAAqB,MAAA;EAAA,OAClB,cAAA;;;;;EA+SO;EAAA,OAxSd,QAAA,EAAuB,cAAA;EAEvB,IAAA;EAAA,QACC,iBAAA;EAAA,QACA,MAAA;EAAA,QACA,aAAA;EAAA,QACA,sBAAA;EAAA,UACU,MAAA,EAAQ,YAAA;EAAA,QAClB,gBAAA;EAAA,OACD,KAAA,EAAO,WAAA;cAEF,MAAA,EAAQ,YAAA;EAXb;EAwBD,KAAA,CAAA,GAAK,OAAA;EAtBJ;EA6BP,SAAA,CAAA;IAAA;;;;;;gBAPW,gBAAA;EAAA;;EAcX,eAAA,CAAA;EA3BY;;;;;;;;EAuCN,KAAA,CAAA,GAAS,OAAA,CAAQ,OAAA,CAAQ,WAAA;;;;;;;;;EA8C/B,SAAA,CAAA,GAAa,MAAA;EAAA;;;;;;;EAmBb,MAAA,CAAO,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;EAqFV;;;;;;EAAA,QAtED,YAAA;EAhFiB;;;;;;EAAA,QAmHjB,aAAA;EAAA,eAmCC,cAAA;EAAA,QAaP,cAAA;EAAA,QA4BM,iBAAA;;;;;EAiDd,OAAA,CAAA;wCAhPe,OAAA,CAAQ,OAAA,CAAQ,WAAA;gBAsPf,GAAA,EAAK,OAAA,CAAQ,WAAA,2BAiBlB;qBAzNE,MAAA,EA4Nd;;;;;;;;kBA5NwB,gBAAA;IAAA;EAAA;AAAA;;;;cAyNZ,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,YAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/plugins/server/index.ts"],"mappings":";;;;;;;;;;;;;;;;AAoCA;;;;;;;;;cAAa,YAAA,SAAqB,MAAA;EAAA,OAClB,cAAA;;;;;EAqUO;EAAA,OA9Td,QAAA,EAAuB,cAAA;EAAA,QACtB,iBAAA;EAAA,QACA,MAAA;EAAA,QACA,aAAA;EAAA,QACA,sBAAA;EAAA,UACU,MAAA,EAAQ,YAAA;EAAA,QAClB,gBAAA;EAAA,QACA,YAAA;EAAA,OACD,KAAA,EAAO,WAAA;cAEF,MAAA,EAAQ,YAAA;EAVb;EAuBD,KAAA,CAAA,GAAK,OAAA;EAtBH;EA6BR,SAAA,CAAA;IAAA;;;;;;gBAPW,gBAAA;EAAA;;EAcX,eAAA,CAAA;EA3BY;;;;;;;;EAuCN,KAAA,CAAA,GAAS,OAAA,CAAQ,OAAA,CAAQ,WAAA;;;;;;;;;EA2D/B,SAAA,CAAA,GAAa,MAAA;EAAA;;;;;;;EAmBb,MAAA,CAAO,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;EA+FV;;;;;;EAAA,QAhFD,YAAA;EA7FiB;;;;;;EAAA,QA0IjB,aAAA;EAAA,eAmCC,cAAA;EAAA,QAaP,cAAA;EAAA,QA4BM,iBAAA;;;;;EAiDd,OAAA,CAAA;wCAvQe,OAAA,CAAQ,OAAA,CAAQ,WAAA;gBA6Qf,GAAA,EAAK,OAAA,CAAQ,WAAA,2BAiBlB;qBAnOE,MAAA,EAmO6B;;;;;;;;kBAnOnB,gBAAA;IAAA;EAAA;AAAA;;;;cAmOZ,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,YAAA"}

package/dist/plugins/server/index.js

@@ -42,12 +42,12 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 	};
 	/** Plugin manifest declaring metadata and resource requirements */
 	static manifest = manifest_default;
-	name = "server";
 	serverApplication;
 	server;
 	viteDevServer;
 	remoteTunnelController;
 	serverExtensions = [];
+	rawBodyPaths = /* @__PURE__ */ new Set();
 	static phase = "deferred";
 	constructor(config) {
 		super(config);
@@ -79,7 +79,11 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 	* @returns The express application.
 	*/
 	async start() {
-		this.serverApplication.use(express.json());
+		this.serverApplication.use(express.json({ type: (req) => {
+			const urlPath = req.url?.split("?")[0];
+			if (urlPath && this.rawBodyPaths.has(urlPath)) return false;
+			return (req.headers["content-type"] ?? "").includes("json");
+		} }));
 		const endpoints = await this.extendRoutes();
 		for (const extension of this.serverExtensions) extension(this.serverApplication);
 		this.remoteTunnelController = new RemoteTunnelController(this.devFileReader);
@@ -139,6 +143,7 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 				const basePath = `/api/${plugin.name}`;
 				this.serverApplication.use(basePath, router);
 				endpoints[plugin.name] = plugin.getEndpoints();
+				if (plugin.getSkipBodyParsingPaths && typeof plugin.getSkipBodyParsingPaths === "function") for (const p of plugin.getSkipBodyParsingPaths()) this.rawBodyPaths.add(p);
 			}
 		}
 		return endpoints;
@@ -232,11 +237,11 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 		};
 	}
 };
-const EXCLUDED_PLUGINS = [ServerPlugin.name];
+const EXCLUDED_PLUGINS = [ServerPlugin.manifest.name];
 /**
 * @internal
 */
-const server = toPlugin(ServerPlugin, "server");
+const server = toPlugin(ServerPlugin);
 
 //#endregion
 export { ServerPlugin, server };

package/dist/plugins/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["manifest"],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport type { Server as HTTPServer } from \"node:http\";\nimport path from \"node:path\";\nimport dotenv from \"dotenv\";\nimport express from \"express\";\nimport type { PluginPhase } from \"shared\";\nimport { ServerError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { instrumentations } from \"../../telemetry\";\nimport manifest from \"./manifest.json\";\nimport { RemoteTunnelController } from \"./remote-tunnel/remote-tunnel-controller\";\nimport { StaticServer } from \"./static-server\";\nimport type { ServerConfig } from \"./types\";\nimport { getRoutes, type PluginEndpoints, printRoutes } from \"./utils\";\nimport { ViteDevServer } from \"./vite-dev-server\";\n\ndotenv.config({ path: path.resolve(process.cwd(), \"./.env\") });\n\nconst logger = createLogger(\"server\");\n\n/**\n * Server plugin for the AppKit.\n *\n * This plugin is responsible for starting the server and serving the static files.\n * It also handles the remote tunneling for development purposes.\n *\n * @example\n * ```ts\n * createApp({\n *   plugins: [server(), telemetryExamples(), analytics({})],\n * });\n * ```\n *\n */\nexport class ServerPlugin extends Plugin {\n  public static DEFAULT_CONFIG = {\n    autoStart: true,\n    host: process.env.FLASK_RUN_HOST || \"0.0.0.0\",\n    port: Number(process.env.DATABRICKS_APP_PORT) || 8000,\n  };\n\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest;\n\n  public name = \"server\" as const;\n  private serverApplication: express.Application;\n  private server: HTTPServer | null;\n  private viteDevServer?: ViteDevServer;\n  private remoteTunnelController?: RemoteTunnelController;\n  protected declare config: ServerConfig;\n  private serverExtensions: ((app: express.Application) => void)[] = [];\n  static phase: PluginPhase = \"deferred\";\n\n  constructor(config: ServerConfig) {\n    super(config);\n    this.config = config;\n    this.serverApplication = express();\n    this.server = null;\n    this.serverExtensions = [];\n    this.telemetry.registerInstrumentations([\n      instrumentations.http,\n      instrumentations.express,\n    ]);\n  }\n\n  /** Setup the server plugin. */\n  async setup() {\n    if (this.shouldAutoStart()) {\n      await this.start();\n    }\n  }\n\n  /** Get the server configuration. */\n  getConfig() {\n    const { plugins: _plugins, ...config } = this.config;\n\n    return config;\n  }\n\n  /** Check if the server should auto start. */\n  shouldAutoStart() {\n    return this.config.autoStart;\n  }\n\n  /**\n   * Start the server.\n   *\n   * This method starts the server and sets up the frontend.\n   * It also sets up the remote tunneling if enabled.\n   *\n   * @returns The express application.\n   */\n  async start(): Promise<express.Application> {\n    this.serverApplication.use(express.json());\n\n    const endpoints = await this.extendRoutes();\n\n    for (const extension of this.serverExtensions) {\n      extension(this.serverApplication);\n    }\n\n    // register remote tunnel controller (before static/vite)\n    this.remoteTunnelController = new RemoteTunnelController(\n      this.devFileReader,\n    );\n    this.serverApplication.use(this.remoteTunnelController.middleware);\n\n    await this.setupFrontend(endpoints);\n\n    const server = this.serverApplication.listen(\n      this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port,\n      this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host,\n      () => this.logStartupInfo(),\n    );\n\n    this.server = server;\n\n    // attach server to remote tunnel controller\n    this.remoteTunnelController.setServer(server);\n\n    process.on(\"SIGTERM\", () => this._gracefulShutdown());\n    process.on(\"SIGINT\", () => this._gracefulShutdown());\n\n    if (process.env.NODE_ENV === \"development\") {\n      const allRoutes = getRoutes(this.serverApplication._router.stack);\n      printRoutes(allRoutes);\n    }\n    return this.serverApplication;\n  }\n\n  /**\n   * Get the low level node.js http server instance.\n   *\n   * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.\n   *\n   * @throws {Error} If the server is not started or autoStart is true.\n   * @returns {HTTPServer} The server instance.\n   */\n  getServer(): HTTPServer {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"get server\");\n    }\n\n    if (!this.server) {\n      throw ServerError.notStarted();\n    }\n\n    return this.server;\n  }\n\n  /**\n   * Extend the server with custom routes or middleware.\n   *\n   * @param fn - A function that receives the express application.\n   * @returns The server plugin instance for chaining.\n   * @throws {Error} If autoStart is true.\n   */\n  extend(fn: (app: express.Application) => void) {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"extend server\");\n    }\n\n    this.serverExtensions.push(fn);\n    return this;\n  }\n\n  /**\n   * Setup the routes with the plugins.\n   *\n   * This method goes through all the plugins and injects the routes into the server application.\n   * Returns a map of plugin names to their registered named endpoints.\n   */\n  private async extendRoutes(): Promise<PluginEndpoints> {\n    const endpoints: PluginEndpoints = {};\n\n    if (!this.config.plugins) return endpoints;\n\n    this.serverApplication.get(\"/health\", (_, res) => {\n      res.status(200).json({ status: \"ok\" });\n    });\n    this.registerEndpoint(\"health\", \"/health\");\n\n    for (const plugin of Object.values(this.config.plugins)) {\n      if (EXCLUDED_PLUGINS.includes(plugin.name)) continue;\n\n      if (plugin?.injectRoutes && typeof plugin.injectRoutes === \"function\") {\n        const router = express.Router();\n\n        plugin.injectRoutes(router);\n\n        const basePath = `/api/${plugin.name}`;\n        this.serverApplication.use(basePath, router);\n\n        // Collect named endpoints from the plugin\n        endpoints[plugin.name] = plugin.getEndpoints();\n      }\n    }\n\n    return endpoints;\n  }\n\n  /**\n   * Setup frontend serving based on environment:\n   * - If staticPath is explicitly provided: use static server\n   * - Dev mode (no staticPath): Vite for HMR\n   * - Production (no staticPath): Static files auto-detected\n   */\n  private async setupFrontend(endpoints: PluginEndpoints) {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n\n    // explict static path provided\n    if (hasExplicitStaticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        this.config.staticPath as string,\n        endpoints,\n      );\n      staticServer.setup();\n      return;\n    }\n\n    // auto-detection based on environment\n    if (isDev) {\n      this.viteDevServer = new ViteDevServer(this.serverApplication, endpoints);\n      await this.viteDevServer.setup();\n      return;\n    }\n\n    // auto-detection based on static path\n    const staticPath = ServerPlugin.findStaticPath();\n    if (staticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        staticPath,\n        endpoints,\n      );\n\n      staticServer.setup();\n    }\n  }\n\n  private static findStaticPath() {\n    const staticPaths = [\"dist\", \"client/dist\", \"build\", \"public\", \"out\"];\n    const cwd = process.cwd();\n    for (const p of staticPaths) {\n      const fullPath = path.resolve(cwd, p);\n      if (fs.existsSync(path.resolve(fullPath, \"index.html\"))) {\n        logger.debug(\"Static files: serving from %s\", fullPath);\n        return fullPath;\n      }\n    }\n    return undefined;\n  }\n\n  private logStartupInfo() {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n    const port = this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port;\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n\n    logger.info(\"Server running on http://%s:%d\", host, port);\n\n    if (hasExplicitStaticPath) {\n      logger.info(\"Mode: static (%s)\", this.config.staticPath);\n    } else if (isDev) {\n      logger.info(\"Mode: development (Vite HMR)\");\n    } else {\n      logger.info(\"Mode: production (static)\");\n    }\n\n    const remoteServerController = this.remoteTunnelController;\n    if (!remoteServerController) {\n      logger.debug(\"Remote tunnel: disabled (controller not initialized)\");\n    } else {\n      logger.debug(\n        \"Remote tunnel: %s; %s\",\n        remoteServerController.isAllowedByEnv() ? \"allowed\" : \"blocked\",\n        remoteServerController.isActive() ? \"active\" : \"inactive\",\n      );\n    }\n  }\n\n  private async _gracefulShutdown() {\n    logger.info(\"Starting graceful shutdown...\");\n\n    if (this.viteDevServer) {\n      await this.viteDevServer.close();\n    }\n\n    if (this.remoteTunnelController) {\n      this.remoteTunnelController.cleanup();\n    }\n\n    // 1. abort active operations from plugins\n    if (this.config.plugins) {\n      for (const plugin of Object.values(this.config.plugins)) {\n        if (plugin.abortActiveOperations) {\n          try {\n            plugin.abortActiveOperations();\n          } catch (err) {\n            logger.error(\n              \"Error aborting operations for plugin %s: %O\",\n              plugin.name,\n              err,\n            );\n          }\n        }\n      }\n    }\n\n    // 2. close the server\n    if (this.server) {\n      this.server.close(() => {\n        logger.debug(\"Server closed gracefully\");\n        process.exit(0);\n      });\n\n      // 3. timeout to force shutdown after 15 seconds\n      setTimeout(() => {\n        logger.debug(\"Force shutdown after timeout\");\n        process.exit(1);\n      }, 15000);\n    } else {\n      process.exit(0);\n    }\n  }\n\n  /**\n   * Returns the public exports for the server plugin.\n   * Exposes server management methods.\n   */\n  exports() {\n    const self = this;\n    return {\n      /** Start the server */\n      start: this.start,\n      /** Extend the server with custom routes or middleware */\n      extend(fn: (app: express.Application) => void) {\n        self.extend(fn);\n        return this;\n      },\n      /** Get the underlying HTTP server instance */\n      getServer: this.getServer,\n      /** Get the server configuration */\n      getConfig: this.getConfig,\n    };\n  }\n}\n\nconst EXCLUDED_PLUGINS = [ServerPlugin.name];\n\n/**\n * @internal\n */\nexport const server = toPlugin<typeof ServerPlugin, ServerConfig, \"server\">(\n  ServerPlugin,\n  \"server\",\n);\n\n// Export manifest and types\nexport type { ServerConfig } from \"./types\";\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["manifest"],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport type { Server as HTTPServer } from \"node:http\";\nimport path from \"node:path\";\nimport dotenv from \"dotenv\";\nimport express from \"express\";\nimport type { PluginPhase } from \"shared\";\nimport { ServerError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { instrumentations } from \"../../telemetry\";\nimport manifest from \"./manifest.json\";\nimport { RemoteTunnelController } from \"./remote-tunnel/remote-tunnel-controller\";\nimport { StaticServer } from \"./static-server\";\nimport type { ServerConfig } from \"./types\";\nimport { getRoutes, type PluginEndpoints, printRoutes } from \"./utils\";\nimport { ViteDevServer } from \"./vite-dev-server\";\n\ndotenv.config({ path: path.resolve(process.cwd(), \"./.env\") });\n\nconst logger = createLogger(\"server\");\n\n/**\n * Server plugin for the AppKit.\n *\n * This plugin is responsible for starting the server and serving the static files.\n * It also handles the remote tunneling for development purposes.\n *\n * @example\n * ```ts\n * createApp({\n *   plugins: [server(), telemetryExamples(), analytics({})],\n * });\n * ```\n *\n */\nexport class ServerPlugin extends Plugin {\n  public static DEFAULT_CONFIG = {\n    autoStart: true,\n    host: process.env.FLASK_RUN_HOST || \"0.0.0.0\",\n    port: Number(process.env.DATABRICKS_APP_PORT) || 8000,\n  };\n\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"server\">;\n  private serverApplication: express.Application;\n  private server: HTTPServer | null;\n  private viteDevServer?: ViteDevServer;\n  private remoteTunnelController?: RemoteTunnelController;\n  protected declare config: ServerConfig;\n  private serverExtensions: ((app: express.Application) => void)[] = [];\n  private rawBodyPaths: Set<string> = new Set();\n  static phase: PluginPhase = \"deferred\";\n\n  constructor(config: ServerConfig) {\n    super(config);\n    this.config = config;\n    this.serverApplication = express();\n    this.server = null;\n    this.serverExtensions = [];\n    this.telemetry.registerInstrumentations([\n      instrumentations.http,\n      instrumentations.express,\n    ]);\n  }\n\n  /** Setup the server plugin. */\n  async setup() {\n    if (this.shouldAutoStart()) {\n      await this.start();\n    }\n  }\n\n  /** Get the server configuration. */\n  getConfig() {\n    const { plugins: _plugins, ...config } = this.config;\n\n    return config;\n  }\n\n  /** Check if the server should auto start. */\n  shouldAutoStart() {\n    return this.config.autoStart;\n  }\n\n  /**\n   * Start the server.\n   *\n   * This method starts the server and sets up the frontend.\n   * It also sets up the remote tunneling if enabled.\n   *\n   * @returns The express application.\n   */\n  async start(): Promise<express.Application> {\n    this.serverApplication.use(\n      express.json({\n        type: (req) => {\n          // Skip JSON parsing for routes that declared skipBodyParsing\n          // (e.g. file uploads where the raw body must flow through).\n          // rawBodyPaths is populated by extendRoutes() below; the type\n          // callback runs per-request so the set is already filled.\n          const urlPath = req.url?.split(\"?\")[0];\n          if (urlPath && this.rawBodyPaths.has(urlPath)) return false;\n          const ct = req.headers[\"content-type\"] ?? \"\";\n          return ct.includes(\"json\");\n        },\n      }),\n    );\n\n    const endpoints = await this.extendRoutes();\n\n    for (const extension of this.serverExtensions) {\n      extension(this.serverApplication);\n    }\n\n    // register remote tunnel controller (before static/vite)\n    this.remoteTunnelController = new RemoteTunnelController(\n      this.devFileReader,\n    );\n    this.serverApplication.use(this.remoteTunnelController.middleware);\n\n    await this.setupFrontend(endpoints);\n\n    const server = this.serverApplication.listen(\n      this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port,\n      this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host,\n      () => this.logStartupInfo(),\n    );\n\n    this.server = server;\n\n    // attach server to remote tunnel controller\n    this.remoteTunnelController.setServer(server);\n\n    process.on(\"SIGTERM\", () => this._gracefulShutdown());\n    process.on(\"SIGINT\", () => this._gracefulShutdown());\n\n    if (process.env.NODE_ENV === \"development\") {\n      const allRoutes = getRoutes(this.serverApplication._router.stack);\n      printRoutes(allRoutes);\n    }\n    return this.serverApplication;\n  }\n\n  /**\n   * Get the low level node.js http server instance.\n   *\n   * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.\n   *\n   * @throws {Error} If the server is not started or autoStart is true.\n   * @returns {HTTPServer} The server instance.\n   */\n  getServer(): HTTPServer {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"get server\");\n    }\n\n    if (!this.server) {\n      throw ServerError.notStarted();\n    }\n\n    return this.server;\n  }\n\n  /**\n   * Extend the server with custom routes or middleware.\n   *\n   * @param fn - A function that receives the express application.\n   * @returns The server plugin instance for chaining.\n   * @throws {Error} If autoStart is true.\n   */\n  extend(fn: (app: express.Application) => void) {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"extend server\");\n    }\n\n    this.serverExtensions.push(fn);\n    return this;\n  }\n\n  /**\n   * Setup the routes with the plugins.\n   *\n   * This method goes through all the plugins and injects the routes into the server application.\n   * Returns a map of plugin names to their registered named endpoints.\n   */\n  private async extendRoutes(): Promise<PluginEndpoints> {\n    const endpoints: PluginEndpoints = {};\n\n    if (!this.config.plugins) return endpoints;\n\n    this.serverApplication.get(\"/health\", (_, res) => {\n      res.status(200).json({ status: \"ok\" });\n    });\n    this.registerEndpoint(\"health\", \"/health\");\n\n    for (const plugin of Object.values(this.config.plugins)) {\n      if (EXCLUDED_PLUGINS.includes(plugin.name)) continue;\n\n      if (plugin?.injectRoutes && typeof plugin.injectRoutes === \"function\") {\n        const router = express.Router();\n\n        plugin.injectRoutes(router);\n\n        const basePath = `/api/${plugin.name}`;\n        this.serverApplication.use(basePath, router);\n\n        // Collect named endpoints from the plugin\n        endpoints[plugin.name] = plugin.getEndpoints();\n\n        // Collect paths that should skip body parsing\n        if (\n          plugin.getSkipBodyParsingPaths &&\n          typeof plugin.getSkipBodyParsingPaths === \"function\"\n        ) {\n          for (const p of plugin.getSkipBodyParsingPaths()) {\n            this.rawBodyPaths.add(p);\n          }\n        }\n      }\n    }\n\n    return endpoints;\n  }\n\n  /**\n   * Setup frontend serving based on environment:\n   * - If staticPath is explicitly provided: use static server\n   * - Dev mode (no staticPath): Vite for HMR\n   * - Production (no staticPath): Static files auto-detected\n   */\n  private async setupFrontend(endpoints: PluginEndpoints) {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n\n    // explict static path provided\n    if (hasExplicitStaticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        this.config.staticPath as string,\n        endpoints,\n      );\n      staticServer.setup();\n      return;\n    }\n\n    // auto-detection based on environment\n    if (isDev) {\n      this.viteDevServer = new ViteDevServer(this.serverApplication, endpoints);\n      await this.viteDevServer.setup();\n      return;\n    }\n\n    // auto-detection based on static path\n    const staticPath = ServerPlugin.findStaticPath();\n    if (staticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        staticPath,\n        endpoints,\n      );\n\n      staticServer.setup();\n    }\n  }\n\n  private static findStaticPath() {\n    const staticPaths = [\"dist\", \"client/dist\", \"build\", \"public\", \"out\"];\n    const cwd = process.cwd();\n    for (const p of staticPaths) {\n      const fullPath = path.resolve(cwd, p);\n      if (fs.existsSync(path.resolve(fullPath, \"index.html\"))) {\n        logger.debug(\"Static files: serving from %s\", fullPath);\n        return fullPath;\n      }\n    }\n    return undefined;\n  }\n\n  private logStartupInfo() {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n    const port = this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port;\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n\n    logger.info(\"Server running on http://%s:%d\", host, port);\n\n    if (hasExplicitStaticPath) {\n      logger.info(\"Mode: static (%s)\", this.config.staticPath);\n    } else if (isDev) {\n      logger.info(\"Mode: development (Vite HMR)\");\n    } else {\n      logger.info(\"Mode: production (static)\");\n    }\n\n    const remoteServerController = this.remoteTunnelController;\n    if (!remoteServerController) {\n      logger.debug(\"Remote tunnel: disabled (controller not initialized)\");\n    } else {\n      logger.debug(\n        \"Remote tunnel: %s; %s\",\n        remoteServerController.isAllowedByEnv() ? \"allowed\" : \"blocked\",\n        remoteServerController.isActive() ? \"active\" : \"inactive\",\n      );\n    }\n  }\n\n  private async _gracefulShutdown() {\n    logger.info(\"Starting graceful shutdown...\");\n\n    if (this.viteDevServer) {\n      await this.viteDevServer.close();\n    }\n\n    if (this.remoteTunnelController) {\n      this.remoteTunnelController.cleanup();\n    }\n\n    // 1. abort active operations from plugins\n    if (this.config.plugins) {\n      for (const plugin of Object.values(this.config.plugins)) {\n        if (plugin.abortActiveOperations) {\n          try {\n            plugin.abortActiveOperations();\n          } catch (err) {\n            logger.error(\n              \"Error aborting operations for plugin %s: %O\",\n              plugin.name,\n              err,\n            );\n          }\n        }\n      }\n    }\n\n    // 2. close the server\n    if (this.server) {\n      this.server.close(() => {\n        logger.debug(\"Server closed gracefully\");\n        process.exit(0);\n      });\n\n      // 3. timeout to force shutdown after 15 seconds\n      setTimeout(() => {\n        logger.debug(\"Force shutdown after timeout\");\n        process.exit(1);\n      }, 15000);\n    } else {\n      process.exit(0);\n    }\n  }\n\n  /**\n   * Returns the public exports for the server plugin.\n   * Exposes server management methods.\n   */\n  exports() {\n    const self = this;\n    return {\n      /** Start the server */\n      start: this.start,\n      /** Extend the server with custom routes or middleware */\n      extend(fn: (app: express.Application) => void) {\n        self.extend(fn);\n        return this;\n      },\n      /** Get the underlying HTTP server instance */\n      getServer: this.getServer,\n      /** Get the server configuration */\n      getConfig: this.getConfig,\n    };\n  }\n}\n\nconst EXCLUDED_PLUGINS: string[] = [ServerPlugin.manifest.name];\n\n/**\n * @internal\n */\nexport const server = toPlugin(ServerPlugin);\n\n// Export manifest and types\nexport type { ServerConfig } from \"./types\";\n"],"mappings":"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"}

package/dist/registry/manifest-loader.js

@@ -36,7 +36,7 @@ function normalizeResource(r) {
 * @throws {ConfigurationError} If the manifest is missing, invalid, or has invalid resource type/permission
 */
 function getPluginManifest(plugin) {
-	const pluginName = plugin.name || "unknown";
+	const pluginName = plugin.manifest?.name || plugin.name || "unknown";
 	if (!plugin.manifest) throw new ConfigurationError(`Plugin ${pluginName} is missing a manifest. All plugins must declare a static manifest property.`);
 	const raw = plugin.manifest;
 	if (!raw.name || typeof raw.name !== "string") throw new ConfigurationError(`Plugin ${pluginName} manifest has missing or invalid 'name' field`);

package/dist/registry/manifest-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.js","names":[],"sources":["../../src/registry/manifest-loader.ts"],"sourcesContent":["import type { PluginConstructor } from \"shared\";\nimport { ConfigurationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport type {\n  PluginManifest,\n  ResourcePermission,\n  ResourceRequirement,\n} from \"./types\";\nimport { PERMISSIONS_BY_TYPE, ResourceType } from \"./types\";\n\nconst logger = createLogger(\"manifest-loader\");\n\n/** Loose resource from shared/manifest (string type and permission). */\ninterface LooseResource {\n  type: string;\n  alias: string;\n  resourceKey: string;\n  description: string;\n  permission: string;\n  fields: Record<string, { env: string; description?: string }>;\n}\n\nfunction normalizeType(s: string): ResourceType {\n  const v = Object.values(ResourceType).find((x) => x === s);\n  if (v !== undefined) return v;\n  throw new ConfigurationError(\n    `Invalid resource type: \"${s}\". Valid: ${Object.values(ResourceType).join(\", \")}`,\n  );\n}\n\nfunction normalizePermission(\n  type: ResourceType,\n  s: string,\n): ResourcePermission {\n  const allowed = PERMISSIONS_BY_TYPE[type];\n  if (allowed.includes(s as ResourcePermission)) return s as ResourcePermission;\n  throw new ConfigurationError(\n    `Invalid permission \"${s}\" for type ${type}. Valid: ${allowed.join(\", \")}`,\n  );\n}\n\nfunction normalizeResource(r: LooseResource): ResourceRequirement {\n  const type = normalizeType(r.type);\n  const permission = normalizePermission(type, r.permission);\n  return {\n    ...r,\n    type,\n    permission,\n    required: false,\n  };\n}\n\n/**\n * Loads and validates the manifest from a plugin constructor.\n * Normalizes string type/permission to strict ResourceType/ResourcePermission.\n *\n * @param plugin - The plugin constructor class\n * @returns The validated, normalized plugin manifest\n * @throws {ConfigurationError} If the manifest is missing, invalid, or has invalid resource type/permission\n */\nexport function getPluginManifest(plugin: PluginConstructor): PluginManifest {\n  const pluginName = plugin.name || \"unknown\";\n\n  if (!plugin.manifest) {\n    throw new ConfigurationError(\n      `Plugin ${pluginName} is missing a manifest. All plugins must declare a static manifest property.`,\n    );\n  }\n\n  const raw = plugin.manifest;\n\n  if (!raw.name || typeof raw.name !== \"string\") {\n    throw new ConfigurationError(\n      `Plugin ${pluginName} manifest has missing or invalid 'name' field`,\n    );\n  }\n\n  if (!raw.displayName || typeof raw.displayName !== \"string\") {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has missing or invalid 'displayName' field`,\n    );\n  }\n\n  if (!raw.description || typeof raw.description !== \"string\") {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has missing or invalid 'description' field`,\n    );\n  }\n\n  if (!raw.resources) {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest is missing 'resources' field`,\n    );\n  }\n\n  if (!Array.isArray(raw.resources.required)) {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has invalid 'resources.required' field (expected array)`,\n    );\n  }\n\n  if (\n    raw.resources.optional !== undefined &&\n    !Array.isArray(raw.resources.optional)\n  ) {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has invalid 'resources.optional' field (expected array)`,\n    );\n  }\n\n  const required = raw.resources.required.map((r) => {\n    const norm = normalizeResource(r as LooseResource);\n    const { required: _, ...rest } = norm;\n    return rest;\n  });\n  const optional = (raw.resources.optional || []).map((r) => {\n    const norm = normalizeResource(r as LooseResource);\n    const { required: _, ...rest } = norm;\n    return rest;\n  });\n\n  logger.debug(\n    \"Loaded manifest for plugin %s: %d required resources, %d optional resources\",\n    raw.name,\n    required.length,\n    optional.length,\n  );\n\n  return {\n    ...raw,\n    resources: { required, optional },\n  };\n}\n\n/**\n * Gets the resource requirements from a plugin's manifest.\n *\n * Combines required and optional resources into a single array with the\n * `required` flag set appropriately.\n *\n * @param plugin - The plugin constructor class\n * @returns Combined array of required and optional resources\n * @throws {ConfigurationError} If the plugin manifest is missing or invalid\n *\n * @example\n * ```typescript\n * const resources = getResourceRequirements(AnalyticsPlugin);\n * for (const resource of resources) {\n *   console.log(`${resource.type}: ${resource.description} (required: ${resource.required})`);\n * }\n * ```\n */\nexport function getResourceRequirements(plugin: PluginConstructor) {\n  const manifest = getPluginManifest(plugin);\n\n  const required = manifest.resources.required.map((r) => ({\n    ...r,\n    required: true,\n  }));\n  const optional = (manifest.resources.optional || []).map((r) => ({\n    ...r,\n    required: false,\n  }));\n\n  return [...required, ...optional];\n}\n\n/**\n * Validates a manifest object structure.\n *\n * @param manifest - The manifest object to validate\n * @returns true if the manifest is valid, false otherwise\n *\n * @internal\n */\nexport function isValidManifest(manifest: unknown): manifest is PluginManifest {\n  if (!manifest || typeof manifest !== \"object\") {\n    return false;\n  }\n\n  const m = manifest as Record<string, unknown>;\n\n  // Check required fields\n  if (typeof m.name !== \"string\") return false;\n  if (typeof m.displayName !== \"string\") return false;\n  if (typeof m.description !== \"string\") return false;\n\n  // Check resources structure\n  if (!m.resources || typeof m.resources !== \"object\") return false;\n\n  const resources = m.resources as Record<string, unknown>;\n  if (!Array.isArray(resources.required)) return false;\n\n  // Optional field can be missing or must be an array\n  if (resources.optional !== undefined && !Array.isArray(resources.optional)) {\n    return false;\n  }\n\n  return true;\n}\n"],"mappings":";;;;;;;aAC+C;AAS/C,MAAM,SAAS,aAAa,kBAAkB;AAY9C,SAAS,cAAc,GAAyB;CAC9C,MAAM,IAAI,OAAO,OAAO,aAAa,CAAC,MAAM,MAAM,MAAM,EAAE;AAC1D,KAAI,MAAM,OAAW,QAAO;AAC5B,OAAM,IAAI,mBACR,2BAA2B,EAAE,YAAY,OAAO,OAAO,aAAa,CAAC,KAAK,KAAK,GAChF;;AAGH,SAAS,oBACP,MACA,GACoB;CACpB,MAAM,UAAU,oBAAoB;AACpC,KAAI,QAAQ,SAAS,EAAwB,CAAE,QAAO;AACtD,OAAM,IAAI,mBACR,uBAAuB,EAAE,aAAa,KAAK,WAAW,QAAQ,KAAK,KAAK,GACzE;;AAGH,SAAS,kBAAkB,GAAuC;CAChE,MAAM,OAAO,cAAc,EAAE,KAAK;CAClC,MAAM,aAAa,oBAAoB,MAAM,EAAE,WAAW;AAC1D,QAAO;EACL,GAAG;EACH;EACA;EACA,UAAU;EACX;;;;;;;;;;AAWH,SAAgB,kBAAkB,QAA2C;CAC3E,MAAM,aAAa,OAAO,QAAQ;AAElC,KAAI,CAAC,OAAO,SACV,OAAM,IAAI,mBACR,UAAU,WAAW,8EACtB;CAGH,MAAM,MAAM,OAAO;AAEnB,KAAI,CAAC,IAAI,QAAQ,OAAO,IAAI,SAAS,SACnC,OAAM,IAAI,mBACR,UAAU,WAAW,+CACtB;AAGH,KAAI,CAAC,IAAI,eAAe,OAAO,IAAI,gBAAgB,SACjD,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,sDACpB;AAGH,KAAI,CAAC,IAAI,eAAe,OAAO,IAAI,gBAAgB,SACjD,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,sDACpB;AAGH,KAAI,CAAC,IAAI,UACP,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,wCACpB;AAGH,KAAI,CAAC,MAAM,QAAQ,IAAI,UAAU,SAAS,CACxC,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,mEACpB;AAGH,KACE,IAAI,UAAU,aAAa,UAC3B,CAAC,MAAM,QAAQ,IAAI,UAAU,SAAS,CAEtC,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,mEACpB;CAGH,MAAM,WAAW,IAAI,UAAU,SAAS,KAAK,MAAM;EAEjD,MAAM,EAAE,UAAU,GAAG,GAAG,SADX,kBAAkB,EAAmB;AAElD,SAAO;GACP;CACF,MAAM,YAAY,IAAI,UAAU,YAAY,EAAE,EAAE,KAAK,MAAM;EAEzD,MAAM,EAAE,UAAU,GAAG,GAAG,SADX,kBAAkB,EAAmB;AAElD,SAAO;GACP;AAEF,QAAO,MACL,+EACA,IAAI,MACJ,SAAS,QACT,SAAS,OACV;AAED,QAAO;EACL,GAAG;EACH,WAAW;GAAE;GAAU;GAAU;EAClC;;;;;;;;;;;;;;;;;;;;AAqBH,SAAgB,wBAAwB,QAA2B;CACjE,MAAM,WAAW,kBAAkB,OAAO;CAE1C,MAAM,WAAW,SAAS,UAAU,SAAS,KAAK,OAAO;EACvD,GAAG;EACH,UAAU;EACX,EAAE;CACH,MAAM,YAAY,SAAS,UAAU,YAAY,EAAE,EAAE,KAAK,OAAO;EAC/D,GAAG;EACH,UAAU;EACX,EAAE;AAEH,QAAO,CAAC,GAAG,UAAU,GAAG,SAAS"}
+{"version":3,"file":"manifest-loader.js","names":[],"sources":["../../src/registry/manifest-loader.ts"],"sourcesContent":["import type { PluginConstructor } from \"shared\";\nimport { ConfigurationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport type {\n  PluginManifest,\n  ResourcePermission,\n  ResourceRequirement,\n} from \"./types\";\nimport { PERMISSIONS_BY_TYPE, ResourceType } from \"./types\";\n\nconst logger = createLogger(\"manifest-loader\");\n\n/** Loose resource from shared/manifest (string type and permission). */\ninterface LooseResource {\n  type: string;\n  alias: string;\n  resourceKey: string;\n  description: string;\n  permission: string;\n  fields: Record<string, { env: string; description?: string }>;\n}\n\nfunction normalizeType(s: string): ResourceType {\n  const v = Object.values(ResourceType).find((x) => x === s);\n  if (v !== undefined) return v;\n  throw new ConfigurationError(\n    `Invalid resource type: \"${s}\". Valid: ${Object.values(ResourceType).join(\", \")}`,\n  );\n}\n\nfunction normalizePermission(\n  type: ResourceType,\n  s: string,\n): ResourcePermission {\n  const allowed = PERMISSIONS_BY_TYPE[type];\n  if (allowed.includes(s as ResourcePermission)) return s as ResourcePermission;\n  throw new ConfigurationError(\n    `Invalid permission \"${s}\" for type ${type}. Valid: ${allowed.join(\", \")}`,\n  );\n}\n\nfunction normalizeResource(r: LooseResource): ResourceRequirement {\n  const type = normalizeType(r.type);\n  const permission = normalizePermission(type, r.permission);\n  return {\n    ...r,\n    type,\n    permission,\n    required: false,\n  };\n}\n\n/**\n * Loads and validates the manifest from a plugin constructor.\n * Normalizes string type/permission to strict ResourceType/ResourcePermission.\n *\n * @param plugin - The plugin constructor class\n * @returns The validated, normalized plugin manifest\n * @throws {ConfigurationError} If the manifest is missing, invalid, or has invalid resource type/permission\n */\nexport function getPluginManifest(plugin: PluginConstructor): PluginManifest {\n  const pluginName = plugin.manifest?.name || plugin.name || \"unknown\";\n\n  if (!plugin.manifest) {\n    throw new ConfigurationError(\n      `Plugin ${pluginName} is missing a manifest. All plugins must declare a static manifest property.`,\n    );\n  }\n\n  const raw = plugin.manifest;\n\n  if (!raw.name || typeof raw.name !== \"string\") {\n    throw new ConfigurationError(\n      `Plugin ${pluginName} manifest has missing or invalid 'name' field`,\n    );\n  }\n\n  if (!raw.displayName || typeof raw.displayName !== \"string\") {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has missing or invalid 'displayName' field`,\n    );\n  }\n\n  if (!raw.description || typeof raw.description !== \"string\") {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has missing or invalid 'description' field`,\n    );\n  }\n\n  if (!raw.resources) {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest is missing 'resources' field`,\n    );\n  }\n\n  if (!Array.isArray(raw.resources.required)) {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has invalid 'resources.required' field (expected array)`,\n    );\n  }\n\n  if (\n    raw.resources.optional !== undefined &&\n    !Array.isArray(raw.resources.optional)\n  ) {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has invalid 'resources.optional' field (expected array)`,\n    );\n  }\n\n  const required = raw.resources.required.map((r) => {\n    const norm = normalizeResource(r as LooseResource);\n    const { required: _, ...rest } = norm;\n    return rest;\n  });\n  const optional = (raw.resources.optional || []).map((r) => {\n    const norm = normalizeResource(r as LooseResource);\n    const { required: _, ...rest } = norm;\n    return rest;\n  });\n\n  logger.debug(\n    \"Loaded manifest for plugin %s: %d required resources, %d optional resources\",\n    raw.name,\n    required.length,\n    optional.length,\n  );\n\n  return {\n    ...raw,\n    resources: { required, optional },\n  };\n}\n\n/**\n * Gets the resource requirements from a plugin's manifest.\n *\n * Combines required and optional resources into a single array with the\n * `required` flag set appropriately.\n *\n * @param plugin - The plugin constructor class\n * @returns Combined array of required and optional resources\n * @throws {ConfigurationError} If the plugin manifest is missing or invalid\n *\n * @example\n * ```typescript\n * const resources = getResourceRequirements(AnalyticsPlugin);\n * for (const resource of resources) {\n *   console.log(`${resource.type}: ${resource.description} (required: ${resource.required})`);\n * }\n * ```\n */\nexport function getResourceRequirements(plugin: PluginConstructor) {\n  const manifest = getPluginManifest(plugin);\n\n  const required = manifest.resources.required.map((r) => ({\n    ...r,\n    required: true,\n  }));\n  const optional = (manifest.resources.optional || []).map((r) => ({\n    ...r,\n    required: false,\n  }));\n\n  return [...required, ...optional];\n}\n\n/**\n * Validates a manifest object structure.\n *\n * @param manifest - The manifest object to validate\n * @returns true if the manifest is valid, false otherwise\n *\n * @internal\n */\nexport function isValidManifest(manifest: unknown): manifest is PluginManifest {\n  if (!manifest || typeof manifest !== \"object\") {\n    return false;\n  }\n\n  const m = manifest as Record<string, unknown>;\n\n  // Check required fields\n  if (typeof m.name !== \"string\") return false;\n  if (typeof m.displayName !== \"string\") return false;\n  if (typeof m.description !== \"string\") return false;\n\n  // Check resources structure\n  if (!m.resources || typeof m.resources !== \"object\") return false;\n\n  const resources = m.resources as Record<string, unknown>;\n  if (!Array.isArray(resources.required)) return false;\n\n  // Optional field can be missing or must be an array\n  if (resources.optional !== undefined && !Array.isArray(resources.optional)) {\n    return false;\n  }\n\n  return true;\n}\n"],"mappings":";;;;;;;aAC+C;AAS/C,MAAM,SAAS,aAAa,kBAAkB;AAY9C,SAAS,cAAc,GAAyB;CAC9C,MAAM,IAAI,OAAO,OAAO,aAAa,CAAC,MAAM,MAAM,MAAM,EAAE;AAC1D,KAAI,MAAM,OAAW,QAAO;AAC5B,OAAM,IAAI,mBACR,2BAA2B,EAAE,YAAY,OAAO,OAAO,aAAa,CAAC,KAAK,KAAK,GAChF;;AAGH,SAAS,oBACP,MACA,GACoB;CACpB,MAAM,UAAU,oBAAoB;AACpC,KAAI,QAAQ,SAAS,EAAwB,CAAE,QAAO;AACtD,OAAM,IAAI,mBACR,uBAAuB,EAAE,aAAa,KAAK,WAAW,QAAQ,KAAK,KAAK,GACzE;;AAGH,SAAS,kBAAkB,GAAuC;CAChE,MAAM,OAAO,cAAc,EAAE,KAAK;CAClC,MAAM,aAAa,oBAAoB,MAAM,EAAE,WAAW;AAC1D,QAAO;EACL,GAAG;EACH;EACA;EACA,UAAU;EACX;;;;;;;;;;AAWH,SAAgB,kBAAkB,QAA2C;CAC3E,MAAM,aAAa,OAAO,UAAU,QAAQ,OAAO,QAAQ;AAE3D,KAAI,CAAC,OAAO,SACV,OAAM,IAAI,mBACR,UAAU,WAAW,8EACtB;CAGH,MAAM,MAAM,OAAO;AAEnB,KAAI,CAAC,IAAI,QAAQ,OAAO,IAAI,SAAS,SACnC,OAAM,IAAI,mBACR,UAAU,WAAW,+CACtB;AAGH,KAAI,CAAC,IAAI,eAAe,OAAO,IAAI,gBAAgB,SACjD,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,sDACpB;AAGH,KAAI,CAAC,IAAI,eAAe,OAAO,IAAI,gBAAgB,SACjD,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,sDACpB;AAGH,KAAI,CAAC,IAAI,UACP,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,wCACpB;AAGH,KAAI,CAAC,MAAM,QAAQ,IAAI,UAAU,SAAS,CACxC,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,mEACpB;AAGH,KACE,IAAI,UAAU,aAAa,UAC3B,CAAC,MAAM,QAAQ,IAAI,UAAU,SAAS,CAEtC,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,mEACpB;CAGH,MAAM,WAAW,IAAI,UAAU,SAAS,KAAK,MAAM;EAEjD,MAAM,EAAE,UAAU,GAAG,GAAG,SADX,kBAAkB,EAAmB;AAElD,SAAO;GACP;CACF,MAAM,YAAY,IAAI,UAAU,YAAY,EAAE,EAAE,KAAK,MAAM;EAEzD,MAAM,EAAE,UAAU,GAAG,GAAG,SADX,kBAAkB,EAAmB;AAElD,SAAO;GACP;AAEF,QAAO,MACL,+EACA,IAAI,MACJ,SAAS,QACT,SAAS,OACV;AAED,QAAO;EACL,GAAG;EACH,WAAW;GAAE;GAAU;GAAU;EAClC;;;;;;;;;;;;;;;;;;;;AAqBH,SAAgB,wBAAwB,QAA2B;CACjE,MAAM,WAAW,kBAAkB,OAAO;CAE1C,MAAM,WAAW,SAAS,UAAU,SAAS,KAAK,OAAO;EACvD,GAAG;EACH,UAAU;EACX,EAAE;CACH,MAAM,YAAY,SAAS,UAAU,YAAY,EAAE,EAAE,KAAK,OAAO;EAC/D,GAAG;EACH,UAAU;EACX,EAAE;AAEH,QAAO,CAAC,GAAG,UAAU,GAAG,SAAS"}

package/dist/registry/types.d.ts

@@ -75,9 +75,9 @@ type ConfigSchema = JSONSchema7;
  * Plugin manifest that declares metadata and resource requirements.
  * Attached to plugin classes as a static property.
  */
-interface PluginManifest {
-  /** Plugin identifier (matches plugin.name) */
-  name: string;
+interface PluginManifest<TName extends string = string> {
+  /** Plugin identifier — the single source of truth for the plugin's name */
+  name: TName;
   /** Human-readable display name for UI/CLI */
   displayName: string;
   /** Brief description of what the plugin does */