@jchat/addon-sdk 1.0.0-alpha.3 → 1.0.0-alpha.31

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`, `@jchat/addon-sdk/ui` (components, icons & toast), `@jchat/addon-sdk/state` (atomic state), and `@jchat/addon-sdk/server`.
+   - NEVER import private internal monorepo packages (`@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/ui"`.
+   - 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/ui"
+
+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/ui"
+
+// 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/src/tailwind.css

@@ -0,0 +1 @@
+@import "@jchat/ui/tailwind.css";

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"]
+}