@jchat/addon-sdk 0.0.1 → 1.0.0-alpha.1

package/src/contracts.d.ts

@@ -0,0 +1,127 @@
+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

@@ -0,0 +1,132 @@
+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[]
+}

package/src/diagnostics.d.ts

@@ -0,0 +1,19 @@
+import type { AddonManifest } from "./contracts";
+export type AddonDiagnosticStatus = "pass" | "warning" | "error";
+export interface AddonPackageDiagnostic {
+    id: string;
+    label: string;
+    status: AddonDiagnosticStatus;
+    message: string;
+}
+export interface AddonPackageDiagnosticOptions {
+    buildDir: string;
+    manifest: AddonManifest;
+    jchatVersion: string;
+    addonSdkVersion: string;
+    productionPackage?: boolean;
+    maxBytes?: number;
+}
+export declare function createCompatibleMajorRange(version: string): string;
+export declare function diagnoseAddonPackage(options: AddonPackageDiagnosticOptions): AddonPackageDiagnostic[];
+export declare function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean;

package/src/diagnostics.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from "bun:test"
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+import {
+  createCompatibleMajorRange,
+  diagnoseAddonPackage,
+  hasAddonDiagnosticErrors
+} from "./diagnostics"
+
+describe("addon package diagnostics", () => {
+  test("accepts compatible builds with every declared file", () => {
+    const buildDir = fs.mkdtempSync(path.join(os.tmpdir(), "jchat-addon-diagnostics-"))
+    fs.writeFileSync(path.join(buildDir, "ui.js"), "export default function Addon() {}")
+    fs.writeFileSync(path.join(buildDir, "api.js"), "export default () => {}")
+
+    try {
+      const diagnostics = diagnoseAddonPackage({
+        buildDir,
+        manifest: {
+          id: "sample-addon",
+          name: "Sample addon",
+          version: "1.0.0",
+          compatibility: {
+            jchat: ">=1.0.0-alpha.0 <2.0.0",
+            addonSdk: "^1.0.0"
+          },
+          frontend: { bundle: "./ui.js", mountPoints: ["chat-toolbar"] },
+          server: { bundle: "./api.js" }
+        },
+        jchatVersion: "1.0.0-alpha.0",
+        addonSdkVersion: "1.0.0"
+      })
+
+      expect(hasAddonDiagnosticErrors(diagnostics)).toBe(false)
+      expect(diagnostics.find(({ id }) => id === "jchat")?.status).toBe("pass")
+      expect(diagnostics.find(({ id }) => id === "server-bundle")?.status).toBe("pass")
+    } finally {
+      fs.rmSync(buildDir, { recursive: true })
+    }
+  })
+
+  test("reports incompatible versions, missing files, and unsafe references", () => {
+    const buildDir = fs.mkdtempSync(path.join(os.tmpdir(), "jchat-addon-diagnostics-"))
+    try {
+      const diagnostics = diagnoseAddonPackage({
+        buildDir,
+        manifest: {
+          id: "sample-addon",
+          name: "Sample addon",
+          version: "1.0.0",
+          compatibility: { jchat: "^2.0.0", addonSdk: "^1.0.0" },
+          frontend: { bundle: "../ui.js", mountPoints: [] },
+          server: { bundle: "./missing-api.js" }
+        },
+        jchatVersion: "1.0.0-alpha.0",
+        addonSdkVersion: "1.0.0"
+      })
+
+      expect(hasAddonDiagnosticErrors(diagnostics)).toBe(true)
+      expect(diagnostics.find(({ id }) => id === "jchat")?.status).toBe("error")
+      expect(diagnostics.find(({ id }) => id === "frontend-bundle")?.status).toBe("error")
+      expect(diagnostics.find(({ id }) => id === "server-bundle")?.status).toBe("error")
+    } finally {
+      fs.rmSync(buildDir, { recursive: true })
+    }
+  })
+
+  test("creates a prerelease-compatible range for the current major", () => {
+    expect(createCompatibleMajorRange("1.0.0-alpha.0")).toBe(">=1.0.0-alpha.0 <2.0.0")
+  })
+
+  test("rejects malformed versions using Bun semver validation", () => {
+    expect(() => createCompatibleMajorRange("1.invalid.0")).toThrow(
+      "Invalid semantic version: 1.invalid.0"
+    )
+  })
+
+  test("measures the distributable archive for production package size", () => {
+    const buildDir = fs.mkdtempSync(path.join(os.tmpdir(), "jchat-addon-diagnostics-"))
+    fs.writeFileSync(path.join(buildDir, "ui.js"), "unpacked content is intentionally larger")
+    fs.writeFileSync(path.join(buildDir, "sample-addon-1.0.0.zip"), "zip")
+
+    try {
+      const diagnostics = diagnoseAddonPackage({
+        buildDir,
+        manifest: {
+          id: "sample-addon",
+          name: "Sample addon",
+          version: "1.0.0",
+          compatibility: { jchat: "^1.0.0", addonSdk: "^1.0.0" },
+          frontend: { bundle: "./ui.js", mountPoints: ["chat-toolbar"] }
+        },
+        jchatVersion: "1.0.0",
+        addonSdkVersion: "1.0.0",
+        productionPackage: true,
+        maxBytes: 3
+      })
+
+      expect(diagnostics.find(({ id }) => id === "package-size")?.status).toBe("pass")
+      expect(diagnostics.find(({ id }) => id === "production-archive")?.status).toBe("pass")
+    } finally {
+      fs.rmSync(buildDir, { recursive: true })
+    }
+  })
+})

package/src/diagnostics.ts

@@ -0,0 +1,182 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+import type { AddonManifest } from "./contracts"
+
+export type AddonDiagnosticStatus = "pass" | "warning" | "error"
+
+export interface AddonPackageDiagnostic {
+  id: string
+  label: string
+  status: AddonDiagnosticStatus
+  message: string
+}
+
+export interface AddonPackageDiagnosticOptions {
+  buildDir: string
+  manifest: AddonManifest
+  jchatVersion: string
+  addonSdkVersion: string
+  productionPackage?: boolean
+  maxBytes?: number
+}
+
+export function createCompatibleMajorRange(version: string): string {
+  try {
+    Bun.semver.order(version, version)
+  } catch {
+    throw new Error(`Invalid semantic version: ${version}`)
+  }
+
+  const majorComponent = /^(?:v|=)?(\d+)\./.exec(version)?.[1]
+  const major = majorComponent ? Number(majorComponent) : Number.NaN
+  if (!Number.isSafeInteger(major)) throw new Error(`Invalid semantic version: ${version}`)
+
+  return `>=${version} <${major + 1}.0.0`
+}
+
+export function diagnoseAddonPackage(
+  options: AddonPackageDiagnosticOptions
+): AddonPackageDiagnostic[] {
+  const { buildDir, manifest } = options
+  const diagnostics: AddonPackageDiagnostic[] = []
+  diagnostics.push(
+    compatibilityDiagnostic(
+      "jchat",
+      "JChat compatibility",
+      options.jchatVersion,
+      manifest.compatibility?.jchat
+    ),
+    compatibilityDiagnostic(
+      "addon-sdk",
+      "Addon SDK compatibility",
+      options.addonSdkVersion,
+      manifest.compatibility?.addonSdk
+    )
+  )
+
+  const references = [
+    ["frontend-bundle", "Frontend bundle", manifest.frontend?.bundle],
+    ["server-bundle", "Server bundle", manifest.server?.bundle],
+    ...(manifest.server?.migrations ?? []).map(
+      (file) => [`migration:${file}`, `Migration ${file}`, file] as const
+    ),
+    ...(manifest.server?.seeds ?? []).map((file) => [`seed:${file}`, `Seed ${file}`, file] as const)
+  ] as const
+
+  for (const [id, label, reference] of references) {
+    if (!reference) continue
+    const file = resolveBuildFile(buildDir, reference)
+    diagnostics.push({
+      id,
+      label,
+      status: file && fs.existsSync(file) && fs.statSync(file).isFile() ? "pass" : "error",
+      message:
+        file && fs.existsSync(file) && fs.statSync(file).isFile()
+          ? reference
+          : `Missing or unsafe build file: ${reference}`
+    })
+  }
+
+  const files = listRegularFiles(buildDir)
+  const productionArchive = path.join(buildDir, `${manifest.id}-${manifest.version}.zip`)
+  const hasProductionArchive =
+    fs.existsSync(productionArchive) && fs.statSync(productionArchive).isFile()
+  const totalBytes =
+    options.productionPackage && hasProductionArchive
+      ? fs.statSync(productionArchive).size
+      : files
+          .filter((file) => file !== productionArchive)
+          .reduce((total, file) => total + fs.statSync(file).size, 0)
+  const maxBytes = options.maxBytes ?? 25 * 1024 * 1024
+  diagnostics.push({
+    id: "package-size",
+    label: "Package size",
+    status: totalBytes <= maxBytes ? "pass" : "error",
+    message: `${totalBytes} of ${maxBytes} bytes`
+  })
+
+  const sourceMaps = files.filter((file) => file.endsWith(".map"))
+  diagnostics.push({
+    id: "source-maps",
+    label: "Source maps",
+    status: options.productionPackage && sourceMaps.length ? "warning" : "pass",
+    message: sourceMaps.length ? `${sourceMaps.length} source map(s) present` : "No source maps"
+  })
+
+  const hasDatabaseFiles = Boolean(
+    manifest.server?.migrations?.length || manifest.server?.seeds?.length
+  )
+  diagnostics.push({
+    id: "database-signature",
+    label: "Database file signature",
+    status:
+      hasDatabaseFiles && options.productionPackage && !manifest.signature?.value
+        ? "error"
+        : hasDatabaseFiles && !manifest.signature?.value
+          ? "warning"
+          : "pass",
+    message:
+      hasDatabaseFiles && !manifest.signature?.value
+        ? options.productionPackage
+          ? "Production database files require a publisher signature"
+          : "Unsigned database files are allowed only in the developer sandbox"
+        : hasDatabaseFiles
+          ? "Publisher signature present"
+          : "No database files declared"
+  })
+
+  if (options.productionPackage) {
+    diagnostics.push({
+      id: "production-archive",
+      label: "Production archive",
+      status: hasProductionArchive ? "pass" : "error",
+      message: hasProductionArchive
+        ? path.basename(productionArchive)
+        : "Production archive is missing"
+    })
+  }
+
+  return diagnostics
+}
+
+export function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean {
+  return diagnostics.some(({ status }) => status === "error")
+}
+
+function compatibilityDiagnostic(
+  id: string,
+  label: string,
+  version: string,
+  range: string | undefined
+): AddonPackageDiagnostic {
+  const compatible = Boolean(range && Bun.semver.satisfies(version, range))
+  return {
+    id,
+    label,
+    status: compatible ? "pass" : "error",
+    message: range
+      ? `${version} ${compatible ? "satisfies" : "does not satisfy"} ${range}`
+      : "Compatibility range is missing"
+  }
+}
+
+function resolveBuildFile(buildDir: string, reference: string): string | null {
+  if (
+    path.isAbsolute(reference) ||
+    reference.includes("\\") ||
+    reference.split("/").includes("..")
+  ) {
+    return null
+  }
+  const target = path.resolve(buildDir, ...reference.replace(/^\.\//, "").split("/"))
+  const relative = path.relative(path.resolve(buildDir), target)
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? target : null
+}
+
+function listRegularFiles(root: string): string[] {
+  if (!fs.existsSync(root)) return []
+  return fs
+    .readdirSync(root, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => path.join(entry.parentPath, entry.name))
+}