@brika/plugin 0.3.1

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@brika/plugin",
+  "version": "0.3.1",
+  "description": "Core plugin runtime types and port compatibility for BRIKA",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brikalabs/brika.git",
+    "directory": "packages/plugin"
+  },
+  "keywords": ["brika", "plugin", "types"],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@brika/type-system": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9"
+  }
+}

package/src/__tests__/plugin.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'bun:test';
+import { arePortTypesCompatible } from '..';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// arePortTypesCompatible
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('arePortTypesCompatible', () => {
+  test('generic/undefined types are always compatible', () => {
+    expect(arePortTypesCompatible(undefined, 'string')).toBe(true);
+    expect(arePortTypesCompatible('string', undefined)).toBe(true);
+    expect(arePortTypesCompatible(undefined, undefined)).toBe(true);
+    expect(arePortTypesCompatible('any', 'number')).toBe(true);
+    expect(arePortTypesCompatible('unknown', 'boolean')).toBe(true);
+    expect(arePortTypesCompatible('generic', 'string')).toBe(true);
+    expect(arePortTypesCompatible('generic-foo', 'number')).toBe(true);
+  });
+
+  test('exact type matches', () => {
+    expect(arePortTypesCompatible('string', 'string')).toBe(true);
+    expect(arePortTypesCompatible('number', 'number')).toBe(true);
+    expect(arePortTypesCompatible('boolean', 'boolean')).toBe(true);
+  });
+
+  test('case-insensitive matching', () => {
+    expect(arePortTypesCompatible('String', 'string')).toBe(true);
+    expect(arePortTypesCompatible('NUMBER', 'number')).toBe(true);
+  });
+
+  test('number family compatibility', () => {
+    expect(arePortTypesCompatible('number', 'integer')).toBe(true);
+    expect(arePortTypesCompatible('integer', 'float')).toBe(true);
+    expect(arePortTypesCompatible('float', 'double')).toBe(true);
+    expect(arePortTypesCompatible('double', 'number')).toBe(true);
+  });
+
+  test('string accepts primitives', () => {
+    expect(arePortTypesCompatible('number', 'string')).toBe(true);
+    expect(arePortTypesCompatible('integer', 'string')).toBe(true);
+    expect(arePortTypesCompatible('boolean', 'string')).toBe(true);
+  });
+
+  test('string does not accept non-primitives', () => {
+    expect(arePortTypesCompatible('object', 'string')).toBe(false);
+  });
+
+  test('object/json family compatibility', () => {
+    expect(arePortTypesCompatible('object', 'json')).toBe(true);
+    expect(arePortTypesCompatible('json', 'record')).toBe(true);
+    expect(arePortTypesCompatible('record', 'object')).toBe(true);
+  });
+
+  test('array compatibility checks base types', () => {
+    expect(arePortTypesCompatible('number[]', 'number[]')).toBe(true);
+    expect(arePortTypesCompatible('number[]', 'integer[]')).toBe(true);
+    expect(arePortTypesCompatible('string[]', 'number[]')).toBe(false);
+  });
+
+  test('incompatible types are rejected', () => {
+    expect(arePortTypesCompatible('string', 'number')).toBe(false);
+    expect(arePortTypesCompatible('boolean', 'number')).toBe(false);
+    expect(arePortTypesCompatible('string', 'boolean')).toBe(false);
+  });
+});

package/src/index.ts

@@ -0,0 +1,159 @@
+/**
+ * @brika/plugin — core plugin types, manifests, preferences, and port compatibility.
+ *
+ * Defines the plugin system types:
+ * - Runtime Plugin representation (hub ↔ UI API contract)
+ * - Capability manifests (blocks, sparks, bricks, pages)
+ * - Preference/configuration system
+ * - Port type compatibility checking for workflow connections
+ */
+
+export * from './manifests';
+export * from './preferences';
+export * from './store';
+
+import { type TypeDescriptor, T, isCompatible } from '@brika/type-system';
+import type { BlockManifest, BrickManifest, PageManifest, SparkManifest } from './manifests';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Plugin Health & Runtime Representation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type PluginHealth =
+  | 'running'
+  | 'stopped'
+  | 'crashed'
+  | 'degraded'
+  | 'installing'
+  | 'updating'
+  | 'restarting'
+  | 'crash-loop'
+  | 'incompatible';
+
+/**
+ * Structured error with i18n support.
+ *
+ * - `key`: i18n translation key (e.g. `"plugins:errors.incompatibleVersion"`)
+ * - `params`: interpolation parameters for the key
+ * - `message`: pre-built English fallback (used in logs and when translations are unavailable)
+ */
+export interface PluginError {
+  key: string;
+  params?: Record<string, string>;
+  message: string;
+}
+
+/** Plugin representation - flattened for easy consumption */
+export interface Plugin {
+  // ─── Identity ──────────────────────────────────────────────────────────────
+  /** Short unique ID - primary identifier */
+  uid: string;
+  /** Plugin name from package.json (e.g. "@brika/blocks-builtin") */
+  name: string;
+  /** Plugin version */
+  version: string;
+
+  // ─── Metadata (inlined from package.json) ──────────────────────────────────
+  /** Human-readable display name */
+  displayName: string | null;
+  /** Human-readable description */
+  description: string | null;
+  /** Author name or object */
+  author:
+    | string
+    | {
+        name: string;
+        email?: string;
+        url?: string;
+      }
+    | null;
+  /** Homepage URL */
+  homepage: string | null;
+  /** Repository URL or object */
+  repository:
+    | string
+    | {
+        type?: string;
+        url: string;
+        directory?: string;
+      }
+    | null;
+  /** Path to icon file */
+  icon: string | null;
+  /** Keywords for search/categorization */
+  keywords: string[];
+  /** License identifier */
+  license: string | null;
+  /** Engine compatibility requirements */
+  engines: {
+    brika: string;
+  };
+
+  // ─── Installation ──────────────────────────────────────────────────────────
+  /** Plugin root directory where package.json lives */
+  rootDirectory: string;
+  /** Entry point file path (absolute) */
+  entryPoint: string;
+
+  // ─── Runtime ───────────────────────────────────────────────────────────────
+  /** Current status */
+  status: PluginHealth;
+  /** Process ID (null when stopped) */
+  pid: number | null;
+  /** Timestamp when plugin was started (null when stopped) */
+  startedAt: number | null;
+  /** Last error (structured with i18n key, params, and English fallback) */
+  lastError: PluginError | null;
+
+  // ─── Capabilities ──────────────────────────────────────────────────────────
+  /** Available blocks */
+  blocks: BlockManifest[];
+  /** Available sparks (typed events) */
+  sparks: SparkManifest[];
+  /** Available bricks (board UI) */
+  bricks: BrickManifest[];
+  /** Custom pages provided by this plugin */
+  pages: PageManifest[];
+
+  // ─── Permissions ──────────────────────────────────────────────────────────
+  /** Permissions declared by this plugin (from package.json) */
+  permissions: string[];
+  /** Permissions currently granted by the user */
+  grantedPermissions: string[];
+
+  // ─── i18n ───────────────────────────────────────────────────────────────────
+  /** Available translation locales (e.g., ["en", "fr", "fr-CH"]) */
+  locales: string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Port Type Compatibility
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if two port types are compatible for connection.
+ * Returns true if source type can flow into target type.
+ *
+ * @deprecated Use `isCompatible()` from `@brika/type-system` instead.
+ * This function delegates to the structural type checker.
+ */
+export function arePortTypesCompatible(sourceType?: string, targetType?: string): boolean {
+  return isCompatible(parseTypeName(sourceType), parseTypeName(targetType));
+}
+
+// Re-export for consumers migrating to @brika/type-system
+export { isCompatible } from '@brika/type-system';
+
+/** Parse a typeName string to a TypeDescriptor for backward compatibility */
+function parseTypeName(typeName?: string): TypeDescriptor {
+  if (!typeName) return T.generic();
+  if (typeName.startsWith('generic') || typeName === 'unknown' || typeName === 'any') return T.generic();
+  const lower = typeName.toLowerCase().trim();
+  if (lower === 'string') return T.string;
+  if (['number', 'integer', 'float', 'double'].includes(lower)) return T.number;
+  if (lower === 'boolean') return T.boolean;
+  if (lower === 'null') return T.null;
+  if (['object', 'json', 'record'].includes(lower)) return T.record(T.unknown);
+  if (lower.endsWith('[]')) return T.array(parseTypeName(lower.slice(0, -2)));
+  return T.unknown;
+}

package/src/manifests.ts

@@ -0,0 +1,87 @@
+/**
+ * Plugin manifest and capability type definitions.
+ *
+ * These types mirror the Zod schemas in @brika/schema and describe
+ * the structure of plugin capabilities in package.json.
+ */
+
+import type { PreferenceDefinition } from './preferences';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Capability Manifests (from package.json)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Block manifest from package.json */
+export interface BlockManifest {
+  id: string;
+  name?: string;
+  description?: string;
+  category?: 'trigger' | 'flow' | 'action' | 'transform';
+  icon?: string;
+  color?: string;
+}
+
+/** Spark (typed event) manifest from package.json */
+export interface SparkManifest {
+  id: string;
+  name?: string;
+  description?: string;
+}
+
+/** Brick size family */
+export type BrickFamily = 'sm' | 'md' | 'lg';
+
+/** Brick (board UI) manifest from package.json */
+export interface BrickManifest {
+  id: string;
+  name?: string;
+  description?: string;
+  category?: string;
+  icon?: string;
+  color?: string;
+  families?: BrickFamily[];
+  config?: PreferenceDefinition[];
+}
+
+/** Plugin page manifest from package.json */
+export interface PageManifest {
+  id: string;
+  icon?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Plugin Manifest (from package.json)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface PluginManifest {
+  name: string;
+  version: string;
+  description?: string;
+  author?:
+    | string
+    | {
+        name: string;
+        email?: string;
+        url?: string;
+      };
+  homepage?: string;
+  repository?:
+    | string
+    | {
+        type?: string;
+        url: string;
+        directory?: string;
+      };
+  icon?: string;
+  keywords?: string[];
+  license?: string;
+  engines?: {
+    brika?: string;
+  };
+  main?: string;
+  blocks?: BlockManifest[];
+  sparks?: SparkManifest[];
+  bricks?: BrickManifest[];
+  pages?: PageManifest[];
+  preferences?: PreferenceDefinition[];
+}

package/src/preferences.ts

@@ -0,0 +1,79 @@
+/**
+ * Plugin preference type definitions.
+ *
+ * Raycast-style configuration system for plugins.
+ * Mirrors the Zod PreferenceSchema for runtime validation.
+ */
+
+export type PreferenceType =
+  | 'text'
+  | 'password'
+  | 'checkbox'
+  | 'dropdown'
+  | 'dynamic-dropdown'
+  | 'number'
+  | 'link';
+
+export interface BasePreference {
+  name: string;
+  type: PreferenceType;
+  label?: string;
+  description?: string;
+  required?: boolean;
+}
+
+export interface TextPreference extends BasePreference {
+  type: 'text';
+  default?: string;
+}
+
+export interface PasswordPreference extends BasePreference {
+  type: 'password';
+  default?: string;
+}
+
+export interface NumberPreference extends BasePreference {
+  type: 'number';
+  default?: number;
+  min?: number;
+  max?: number;
+  step?: number;
+}
+
+export interface CheckboxPreference extends BasePreference {
+  type: 'checkbox';
+  default?: boolean;
+}
+
+export interface DropdownPreference extends BasePreference {
+  type: 'dropdown';
+  default?: string;
+  options: Array<{
+    value: string;
+  }>;
+}
+
+export interface DynamicDropdownPreference extends BasePreference {
+  type: 'dynamic-dropdown';
+  default?: string;
+  /** Options resolved server-side via plugin route GET /preferences/{name}. */
+  options?: Array<{
+    value: string;
+    label: string;
+  }>;
+}
+
+export interface LinkPreference extends BasePreference {
+  type: 'link';
+  /** URL to open. Relative paths (starting with /) resolve to plugin routes. */
+  url: string;
+}
+
+export type PreferenceDefinition =
+  | TextPreference
+  | PasswordPreference
+  | NumberPreference
+  | CheckboxPreference
+  | DropdownPreference
+  | DynamicDropdownPreference
+  | LinkPreference;

package/src/store.ts

@@ -0,0 +1,96 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Plugin Store Types — shared between hub and UI
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Plugin data from the store (combines npm + verified status + compatibility) */
+export interface StorePlugin {
+  name: string;
+  displayName?: string;
+  version: string;
+  /** Version string to pass to the installer (e.g. 'workspace:*' for local plugins) */
+  installVersion: string;
+  description: string;
+  author:
+    | string
+    | {
+        name: string;
+        email?: string;
+      };
+  keywords: string[];
+  repository?:
+    | string
+    | {
+        url: string;
+      };
+  homepage?: string;
+  license?: string;
+  engines?: {
+    brika?: string;
+  };
+  verified: boolean;
+  verifiedAt?: string;
+  featured: boolean;
+  compatible: boolean;
+  compatibilityReason?: string;
+  installed: boolean;
+  installedVersion?: string;
+  source: string;
+  npm: {
+    downloads: number;
+    publishedAt: string;
+  };
+}
+
+/** npm package data from registry API */
+export interface PluginPackageData {
+  name: string;
+  version: string;
+  displayName?: string;
+  description?: string;
+  author?:
+    | string
+    | {
+        name: string;
+        email?: string;
+      };
+  keywords?: string[];
+  repository?:
+    | string
+    | {
+        type?: string;
+        url: string;
+        directory?: string;
+      };
+  homepage?: string;
+  license?: string;
+  engines?: {
+    brika?: string;
+  };
+  date?: string;
+  links?: {
+    npm?: string;
+    homepage?: string;
+    repository?: string;
+    bugs?: string;
+  };
+  score?: {
+    final: number;
+    detail: {
+      quality: number;
+      popularity: number;
+      maintenance: number;
+    };
+  };
+}
+
+/** npm search result from registry API */
+export interface PluginSearchResult {
+  package: PluginPackageData;
+  source: string;
+  installVersion: string;
+  downloadCount: number;
+  installed: boolean;
+  installedVersion?: string;
+  compatible: boolean;
+  compatibilityReason?: string;
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src"]
+}