@jchat/addon-sdk 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/create-jchat-addon/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: create-jchat-addon
+description: Scaffold and initialize new JChat addons using @jchat/create-addon with correct templates, mount points, manifest configuration, and devkit sandbox setup.
+---
+
+# Create JChat Addon Skill
+
+Use this skill whenever you need to create, scaffold, or initialize a new JChat addon, whether inside the JChat monorepo or as a standalone third-party project for external developers.
+
+---
+
+## 1. Quick Start Commands
+
+### Inside the JChat Monorepo
+
+When working inside the JChat monorepo root:
+
+```bash
+# Interactive scaffolding
+bunx @jchat/create-addon <addon-id> --workspace
+
+# Non-interactive UI addon
+bunx @jchat/create-addon <addon-id> --workspace --template=ui --mount-points=chat-toolbar --name="My Addon"
+
+# Non-interactive fullstack addon (frontend UI + Elysia backend + isolated DB schema)
+bunx @jchat/create-addon <addon-id> --workspace --template=fullstack --mount-points=chat-toolbar,room-settings --name="My Fullstack Addon"
+```
+
+Monorepo addons are generated directly into the `addons/<addon-id>/` workspace directory and automatically wired into Bun workspaces.
+
+### Standalone (Third-Party Addon Developers)
+
+For third-party developers building standalone addons outside the JChat monorepo:
+
+```bash
+# Recommended command
+bun create @jchat/addon <addon-id>
+
+# Or with npx/bunx directly
+bunx @jchat/create-addon <addon-id>
+
+# With explicit flags
+bunx @jchat/create-addon <addon-id> --template=fullstack --mount-points=chat-toolbar,user-profile
+```
+
+Standalone projects generate a complete DevKit environment containing:
+
+- `addon/` — The addon source package.
+- `docker-compose.yml` — Disposable JChat development sandbox container with pre-configured PostgreSQL and Redis.
+- `scripts/devkit.ts` — Lifecycle management scripts (`bun run devkit:start`, `bun run devkit:stop`).
+
+---
+
+## 2. CLI Options & Parameters
+
+| Option           | Description                                                 | Values / Examples                                | Default                                                |
+| ---------------- | ----------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------ |
+| `<addon-id>`     | Unique identifier in kebab-case (letters, numbers, hyphens) | `gifyard`, `poll-wise`, `weather-now`            | _Required_                                             |
+| `--template`     | Architecture template                                       | `ui` or `fullstack`                              | `ui`                                                   |
+| `--mount-points` | Comma-separated UI mount locations                          | `chat-toolbar,room-settings,chat-message-action` | `chat-toolbar`                                         |
+| `--name`         | Human-readable display name                                 | `--name="Weather Widget"`                        | Capitalized `addon-id`                                 |
+| `--target`       | Destination directory                                       | `--target=addons/my-addon`                       | `<addon-id>` (or `addons/<addon-id>` if `--workspace`) |
+| `--workspace`    | Target JChat monorepo workspace dependencies                | Flag                                             | `false`                                                |
+| `--image`        | Custom JChat sandbox container image                        | `--image=jchat/devkit:local`                     | Default published sandbox image                        |
+
+---
+
+## 3. Choosing a Template
+
+### `ui` Template (Frontend Only)
+
+Select when the addon only displays UI elements, embeds content, interacts with external third-party APIs via client fetch, or executes client-side actions (e.g. inserting text or media into the message editor).
+
+- **Files generated**: `src/manifest.ts`, `src/ui.tsx`, `src/locales/*.json`, `vite.config.ts`, `package.json`.
+- **Backend required**: None.
+
+### `fullstack` Template (UI + Elysia Backend + Isolated DB)
+
+Select when the addon needs:
+
+- Custom REST endpoints or server-side webhook processing.
+- Persistent database storage (tables in PostgreSQL `addons.*` schema).
+- Real-time Redis / WebSocket event broadcasting.
+- Enforcing server-side authorization or managing secrets.
+- **Files generated**: Everything in `ui`, plus `src/server.ts`, database migrations, and backend configuration.
+
+---
+
+## 4. UI Mount Points
+
+Available mount points supported by the JChat host:
+
+- `chat-toolbar`: Action button or picker in the chat composer toolbar.
+- `chat-message-action`: Context menu action on existing chat messages.
+- `room-settings`: Custom tab or section inside Room Settings.
+- `site-settings`: Admin configuration panel for site administrators.
+- `user-profile`: Extended tab or badge inside user profile cards.
+- `sidebar-left` / `sidebar-right`: Persistent panels in chat sidebars.
+
+---
+
+## 5. Generated Workspace Structure
+
+```text
+my-addon/
+├── .agents/
+│   └── skills/
+│       └── jchat-addon-development/
+│           └── SKILL.md             # In-workspace agent development guide
+├── src/
+│   ├── manifest.ts                  # Addon definition, permissions, mount points
+│   ├── ui.tsx                       # Main React UI entry point
+│   ├── server.ts                    # ElysiaJS server entry point (fullstack only)
+│   └── locales/                     # 20 host language JSON dictionaries
+│       ├── en.json
+│       ├── ar.json
+│       ├── es.json
+│       └── ...
+├── package.json
+├── tsconfig.json
+└── vite.config.ts
+```
+
+---
+
+## 6. Verification and Validation Checklist
+
+Immediately after scaffolding an addon:
+
+1. **Check Manifest**: Verify `src/manifest.ts` contains the correct `id`, `name`, `mountPoints`, and `permissions`.
+2. **Verify Localization**: Ensure all 20 required language dictionaries exist in `src/locales/` (`bun check:translations` if in monorepo).
+3. **Run Typecheck & Build**:
+   ```bash
+   bun run typecheck
+   bun run build
+   ```
+4. **DevKit Sandbox (Standalone)**:
+   ```bash
+   bun run devkit:start
+   ```

package/skills/jchat-addon-development/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: jchat-addon-development
+description: Comprehensive guide for developing JChat addons using @jchat/addon-sdk, including manifests, UI widgets, direct icon imports, Elysia backend, isolated DB schemas, and i18n.
+---
+
+# JChat Addon Development Skill
+
+Use this skill when developing, updating, or debugging JChat addons using `@jchat/addon-sdk`.
+
+---
+
+## 1. Architectural Guardrails (Non-Negotiable)
+
+1. **Import Boundaries**:
+   - Addons MUST ONLY import `@jchat/addon-sdk` and `@jchat/addon-sdk/icon`.
+   - NEVER import private internal monorepo packages (`@jchat/icon`, `@jchat/ui`, `@jchat/db`, `@jchat/shared`, etc.).
+   - Host externals (`react`, `react-dom`, `@tanstack/react-query`) are provided at runtime by the JChat host.
+2. **Icons**:
+   - Use direct imports: `import Icons from "@jchat/addon-sdk/icon"`.
+   - Never call `useIcons()` or install `lucide-react` / `react-icons` directly in the addon.
+3. **Database Isolation**:
+   - All addon tables MUST reside in the isolated `addons` PostgreSQL schema (e.g. `addons.GlimpseStories`).
+   - Never write to or alter core tables (`Users`, `Rooms`, `Messages`, `Sites`).
+4. **Real-Time Event Namespacing**:
+   - All WebSocket/Redis events MUST follow the canonical format: `addon:<addonId>:<eventName>` (e.g. `addon:pollwise:voted`).
+5. **Localization (i18n)**:
+   - All addons must support all 20 host languages:
+     `ar`, `bg`, `de`, `el`, `en`, `es`, `fr`, `he`, `hi`, `hr`, `kn`, `ml`, `nl`, `pt`, `ro`, `ru`, `ta`, `te`, `tr`, `ur`.
+   - All locale dictionaries in `src/locales/*.json` must maintain 100% key parity.
+6. **Directional Styling (RTL/LTR)**:
+   - Use Tailwind CSS logical properties (`ps-*`, `pe-*`, `ms-*`, `me-*`, `text-start`, `text-end`, `start-*`, `end-*`, `rounded-s-*`, `rounded-e-*`).
+   - Never use physical `pl-*`, `pr-*`, `ml-*`, `mr-*`, `text-left`, or `text-right`.
+
+---
+
+## 2. Manifest Contract (`src/manifest.ts`)
+
+Define addon metadata and capabilities with `defineAddonManifest`:
+
+```typescript
+import { defineAddonManifest } from "@jchat/addon-sdk"
+
+export default defineAddonManifest({
+  id: "pollwise",
+  name: "Pollwise Polls",
+  version: "1.0.0",
+  description: "Create and vote on live interactive polls in chat rooms.",
+  author: "JChat Ecosystem Team",
+  compatibility: {
+    jchat: ">=1.0.0-alpha.0 <2.0.0",
+    addonSdk: ">=1.0.0-alpha.0 <2.0.0"
+  },
+  locales: [
+    "ar",
+    "bg",
+    "de",
+    "el",
+    "en",
+    "es",
+    "fr",
+    "he",
+    "hi",
+    "hr",
+    "kn",
+    "ml",
+    "nl",
+    "pt",
+    "ro",
+    "ru",
+    "ta",
+    "te",
+    "tr",
+    "ur"
+  ],
+  defaultLocale: "en",
+  frontend: {
+    bundle: "./ui.js",
+    mountPoints: ["chat-toolbar", "room-settings"]
+  },
+  backend: {
+    bundle: "./server.js"
+  },
+  permissions: ["network", "storage"]
+})
+```
+
+---
+
+## 3. Frontend UI Development (`src/ui.tsx`)
+
+Addon UI components receive `AddonProps` and use hooks from `@jchat/addon-sdk`:
+
+```tsx
+import {
+  type AddonProps,
+  useAddonSDK,
+  useAddonQuery,
+  useAddonMutation,
+  useAddonTranslation
+} from "@jchat/addon-sdk"
+import Icons from "@jchat/addon-sdk/icon"
+
+export default function PollwiseAddon({ mountPoint, roomId }: AddonProps) {
+  const sdk = useAddonSDK()
+  const { t } = useAddonTranslation()
+
+  // 1. Data fetching via TanStack Query bridge
+  const { data: poll, isLoading } = useAddonQuery({
+    queryKey: ["poll", roomId],
+    queryFn: () => sdk.api.get<{ id: string; question: string }>(`/rooms/${roomId}/poll`)
+  })
+
+  // 2. Mutations
+  const voteMutation = useAddonMutation({
+    mutationFn: (optionId: string) => sdk.api.post(`/rooms/${roomId}/vote`, { optionId }),
+    onSuccess: () => {
+      sdk.ui.toast({
+        title: t("vote_success_title"),
+        description: t("vote_success_desc"),
+        variant: "success"
+      })
+    }
+  })
+
+  // 3. Real-time event listener
+  useEffect(() => {
+    const unsubscribe = sdk.events.on("addon:pollwise:updated", (updatedPoll) => {
+      // Handle incoming real-time payload
+    })
+    return () => unsubscribe()
+  }, [sdk])
+
+  if (isLoading) return <div>{t("loading")}</div>
+
+  return (
+    <div className="p-4 rounded-xl bg-card border border-border">
+      <div className="flex items-center gap-2 mb-3">
+        <Icons.BarChart3 className="size-5 text-primary" />
+        <h3 className="font-semibold text-foreground">{poll?.question}</h3>
+      </div>
+      <button
+        onClick={() => voteMutation.mutate("option-1")}
+        className="px-3 py-1.5 rounded-lg bg-primary text-primary-foreground hover:bg-primary/90 transition-colors"
+      >
+        {t("vote_button")}
+      </button>
+    </div>
+  )
+}
+```
+
+### Direct Icon Usage
+
+Icons are rendered directly:
+
+```tsx
+import Icons, { resolveIcon } from "@jchat/addon-sdk/icon"
+
+// Direct JSX:
+<Icons.Sparkles className="size-4 text-primary" />
+<Icons.Send className="size-5" />
+
+// Dynamic resolution:
+const DynamicIcon = resolveIcon("Smile", Icons.HelpCircle)
+<DynamicIcon className="size-4" />
+```
+
+---
+
+## 4. Backend Server Development (`src/server.ts`)
+
+Fullstack addons expose ElysiaJS routes running within the JChat server runtime:
+
+```typescript
+import { createAddonServer } from "@jchat/addon-sdk/server"
+import { t } from "elysia"
+
+export default createAddonServer("pollwise", ({ app, db, events }) => {
+  return app
+    .get("/rooms/:roomId/poll", async ({ params: { roomId } }) => {
+      // Query isolated addons schema using Kysely
+      const poll = await db
+        .selectFrom("addons.Polls")
+        .selectAll()
+        .where("roomId", "=", roomId)
+        .executeTakeFirst()
+
+      return poll ?? { message: "No active poll" }
+    })
+    .post(
+      "/rooms/:roomId/vote",
+      async ({ params: { roomId }, body, user }) => {
+        // Record vote in DB
+        await db
+          .insertInto("addons.PollVotes")
+          .values({
+            pollId: body.pollId,
+            userId: user.id,
+            optionId: body.optionId
+          })
+          .execute()
+
+        // Broadcast real-time event to room subscribers
+        await events.publish(`addon:pollwise:updated`, {
+          roomId,
+          pollId: body.pollId
+        })
+
+        return { success: true }
+      },
+      {
+        body: t.Object({
+          pollId: t.String(),
+          optionId: t.String()
+        })
+      }
+    )
+})
+```
+
+---
+
+## 5. Addon Localization (`src/locales/`)
+
+Every translatable string in the UI must use `t("key")`.
+Translations reside in `src/locales/<lang>.json` for all 20 supported languages:
+
+```json
+// src/locales/en.json
+{
+  "welcome": "Welcome to Pollwise",
+  "vote_button": "Submit Vote",
+  "vote_success_title": "Vote Recorded",
+  "vote_success_desc": "Thank you for participating."
+}
+```
+
+Validate key parity across all 20 languages:
+
+```bash
+bun check:translations
+```
+
+---
+
+## 6. Build and Verification Workflow
+
+```bash
+# 1. Typecheck the addon
+bun run typecheck
+
+# 2. Bundle the addon artifacts (frontend bundle into ui.js, backend into server.js)
+bun run build
+
+# 3. In the standalone devkit: start the disposable sandbox environment
+bun run devkit:start
+
+# 4. View sandbox logs
+bun run devkit:logs
+```

package/tsconfig.addon.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "JChat Addon Base",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["bun", "vite/client"]
+  },
+  "exclude": ["build", "dist", "node_modules"]
+}

package/src/contracts.d.ts

@@ -1,127 +0,0 @@
-export type AddonPermission = string;
-/**
- * Defines a single configuration field for an addon's settings panel. These are shown to site
- * admins in the Jchat dashboard.
- */
-export interface ConfigSchemaField {
-    /** Unique key used to store and retrieve the value in `getConfig` */
-    key: string;
-    /** Data type for validation and UI rendering */
-    type: "string" | "number" | "boolean";
-    /** Human-readable label shown in the settings UI */
-    label: string;
-    /** If true, the admin must provide a value before saving */
-    required?: boolean;
-    /** Whether the value is sensitive (encrypted at rest and masked in the UI) */
-    secret?: boolean;
-    /** Default value pre-filled in the settings form for new installations */
-    default?: string | number | boolean;
-}
-/** Definition of a custom permission introduced by an addon. */
-export interface AddonPermissionDefinition {
-    /** Permission identifier (recommended: `addon.<id>.<action>`) */
-    name: string;
-    /** Short, human-readable name for the permission */
-    label: string;
-    /** Detailed description of what the permission grants (shown in Rank editor) */
-    description: string;
-}
-/** Valid locations where an addon can be rendered within the Jchat layout. */
-export declare const MOUNT_POINTS: {
-    /** Top of the main chat column */
-    readonly CHAT_HEADER: "chat-header";
-    /** Below the main chat header, above messages */
-    readonly CHAT_TOOLBAR: "chat-toolbar";
-    /** The persistent right-side sidebar */
-    readonly CHAT_SIDEBAR: "chat-sidebar";
-    /** Top of the left sidebar (room list) */
-    readonly SIDEBAR_TOP: "sidebar-top";
-    /** Bottom of the left sidebar */
-    readonly SIDEBAR_BOTTOM: "sidebar-bottom";
-    /** Action list shown when clicking a user's avatar */
-    readonly USER_POPOVER_ACTIONS: "user-popover-actions";
-    /** Menu shown when right-clicking a message */
-    readonly MESSAGE_CONTEXT_MENU: "message-context-menu";
-    /** Floating overlay rendered on top of the message stream */
-    readonly MESSAGE_FEED_OVERLAY: "message-feed-overlay";
-    /** Main admin dashboard area */
-    readonly ADMIN_PANEL: "admin-panel";
-    /** User or site settings dashboard area */
-    readonly SETTINGS_PANEL: "settings-panel";
-    /** The 'plus' (+) menu in the message composer */
-    readonly CHAT_PLUS_MENU: "chat-plus-menu";
-    /** Custom tab in the emoji/gif selection panel */
-    readonly EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab";
-    /** Full-screen or modal dialog specifically for TubeScan */
-    readonly TUBESCAN_DIALOG: "tubescan-dialog";
-};
-/** Union type of all valid addon mount points. */
-export type MountPoint = (typeof MOUNT_POINTS)[keyof typeof MOUNT_POINTS];
-/**
- * The `manifest.json` schema required for every Jchat addon. This file describes how the addon is
- * identified and mounted.
- */
-export interface AddonManifest {
-    /** Unique kebab-case addon identifier (must match the folder name) */
-    id: string;
-    /** Human-readable addon name */
-    name: string;
-    /** Semver version string (e.g. `1.2.0`) */
-    version: string;
-    /** Brief summary of what the addon does */
-    description?: string;
-    /** Author name, organization, or GitHub handle */
-    author?: string;
-    /** Support or documentation URL */
-    homepage?: string;
-    /** SPDX license identifier (e.g. `MIT`) */
-    license?: string;
-    /** Host and SDK versions this directly executed plugin was built and tested against */
-    compatibility: {
-        /** Supported JChat versions as a semantic-version range, for example `^1.0.0` */
-        jchat: string;
-        /** Supported `@jchat/addon-sdk` versions as a semantic-version range */
-        addonSdk: string;
-    };
-    /** Identity of the trusted publisher that signed this package. Required when migrations exist */
-    publisher?: {
-        id: string;
-    };
-    /** Signature over the canonical archive digest. Required when migrations exist */
-    signature?: {
-        algorithm: "rsa-sha256";
-        digest: string;
-        value: string;
-    };
-    /** Configuration for the React-based frontend bundle */
-    frontend?: {
-        /** Relative path to the pre-compiled ESM bundle (created by Vite) */
-        bundle: string;
-        /** List of UI locations where this addon should be active */
-        mountPoints: MountPoint[];
-        /** Optional path to a specific UI for the settings panel */
-        settings?: string;
-        /** Additional shared packages this addon imports from the host */
-        externals?: string[];
-    };
-    /** Configuration for the server-side API bundle */
-    server?: {
-        /** Relative path to the pre-compiled server bundle */
-        bundle?: string;
-        /** List of SQL files to run (in order) to set up the addon's database tables */
-        migrations?: string[];
-        /** List of declarative JSON master-data files to apply once, in order */
-        seeds?: string[];
-    };
-    /**
-     * The minimum permission required to see or use this addon. If provided, the host gates
-     * visibility in the UI and access to all server routes.
-     */
-    accessPermission?: AddonPermission;
-    /** Full list of all permissions used by this addon for informational purposes */
-    permissions?: AddonPermission[];
-    /** Custom permissions that should be registered with the host application on installation */
-    permissionDefinitions?: AddonPermissionDefinition[];
-    /** Settings form structure shown to site admins. Values are stored encrypted per site */
-    configSchema?: ConfigSchemaField[];
-}

package/src/contracts.ts

@@ -1,132 +0,0 @@
-export type AddonPermission = string
-
-/**
- * Defines a single configuration field for an addon's settings panel. These are shown to site
- * admins in the Jchat dashboard.
- */
-export interface ConfigSchemaField {
-  /** Unique key used to store and retrieve the value in `getConfig` */
-  key: string
-  /** Data type for validation and UI rendering */
-  type: "string" | "number" | "boolean"
-  /** Human-readable label shown in the settings UI */
-  label: string
-  /** If true, the admin must provide a value before saving */
-  required?: boolean
-  /** Whether the value is sensitive (encrypted at rest and masked in the UI) */
-  secret?: boolean
-  /** Default value pre-filled in the settings form for new installations */
-  default?: string | number | boolean
-}
-
-/** Definition of a custom permission introduced by an addon. */
-export interface AddonPermissionDefinition {
-  /** Permission identifier (recommended: `addon.<id>.<action>`) */
-  name: string
-  /** Short, human-readable name for the permission */
-  label: string
-  /** Detailed description of what the permission grants (shown in Rank editor) */
-  description: string
-}
-
-/** Valid locations where an addon can be rendered within the Jchat layout. */
-export const MOUNT_POINTS = {
-  /** Top of the main chat column */
-  CHAT_HEADER: "chat-header",
-  /** Below the main chat header, above messages */
-  CHAT_TOOLBAR: "chat-toolbar",
-  /** The persistent right-side sidebar */
-  CHAT_SIDEBAR: "chat-sidebar",
-  /** Top of the left sidebar (room list) */
-  SIDEBAR_TOP: "sidebar-top",
-  /** Bottom of the left sidebar */
-  SIDEBAR_BOTTOM: "sidebar-bottom",
-  /** Action list shown when clicking a user's avatar */
-  USER_POPOVER_ACTIONS: "user-popover-actions",
-  /** Menu shown when right-clicking a message */
-  MESSAGE_CONTEXT_MENU: "message-context-menu",
-  /** Floating overlay rendered on top of the message stream */
-  MESSAGE_FEED_OVERLAY: "message-feed-overlay",
-  /** Main admin dashboard area */
-  ADMIN_PANEL: "admin-panel",
-  /** User or site settings dashboard area */
-  SETTINGS_PANEL: "settings-panel",
-  /** The 'plus' (+) menu in the message composer */
-  CHAT_PLUS_MENU: "chat-plus-menu",
-  /** Custom tab in the emoji/gif selection panel */
-  EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab",
-  /** Full-screen or modal dialog specifically for TubeScan */
-  TUBESCAN_DIALOG: "tubescan-dialog"
-} as const
-
-/** Union type of all valid addon mount points. */
-export type MountPoint = (typeof MOUNT_POINTS)[keyof typeof MOUNT_POINTS]
-
-/**
- * The `manifest.json` schema required for every Jchat addon. This file describes how the addon is
- * identified and mounted.
- */
-export interface AddonManifest {
-  /** Unique kebab-case addon identifier (must match the folder name) */
-  id: string
-  /** Human-readable addon name */
-  name: string
-  /** Semver version string (e.g. `1.2.0`) */
-  version: string
-  /** Brief summary of what the addon does */
-  description?: string
-  /** Author name, organization, or GitHub handle */
-  author?: string
-  /** Support or documentation URL */
-  homepage?: string
-  /** SPDX license identifier (e.g. `MIT`) */
-  license?: string
-  /** Host and SDK versions this directly executed plugin was built and tested against */
-  compatibility: {
-    /** Supported JChat versions as a semantic-version range, for example `^1.0.0` */
-    jchat: string
-    /** Supported `@jchat/addon-sdk` versions as a semantic-version range */
-    addonSdk: string
-  }
-  /** Identity of the trusted publisher that signed this package. Required when migrations exist */
-  publisher?: {
-    id: string
-  }
-  /** Signature over the canonical archive digest. Required when migrations exist */
-  signature?: {
-    algorithm: "rsa-sha256"
-    digest: string
-    value: string
-  }
-  /** Configuration for the React-based frontend bundle */
-  frontend?: {
-    /** Relative path to the pre-compiled ESM bundle (created by Vite) */
-    bundle: string
-    /** List of UI locations where this addon should be active */
-    mountPoints: MountPoint[]
-    /** Optional path to a specific UI for the settings panel */
-    settings?: string
-    /** Additional shared packages this addon imports from the host */
-    externals?: string[]
-  }
-  /** Configuration for the server-side API bundle */
-  server?: {
-    /** Relative path to the pre-compiled server bundle */
-    bundle?: string
-    /** List of SQL files to run (in order) to set up the addon's database tables */
-    migrations?: string[]
-    /** List of declarative JSON master-data files to apply once, in order */
-    seeds?: string[]
-  }
-  /**
-   * The minimum permission required to see or use this addon. If provided, the host gates
-   * visibility in the UI and access to all server routes.
-   */
-  accessPermission?: AddonPermission
-  /** Full list of all permissions used by this addon for informational purposes */
-  permissions?: AddonPermission[]
-  /** Custom permissions that should be registered with the host application on installation */
-  permissionDefinitions?: AddonPermissionDefinition[]
-  /** Settings form structure shown to site admins. Values are stored encrypted per site */
-  configSchema?: ConfigSchemaField[]
-}