@lumen-ops/plugin-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zaidhaan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @lumen-ops/plugin-sdk
+
+Type definitions for [Lumen](https://github.com/zaidhaan/lumen) plugins.
+
+This package contains only types — no runtime code. Import it in your plugin for a typed `LumenPlugin` contract.
+
+## Install
+
+```bash
+npm install --save-dev @lumen-ops/plugin-sdk
+# or
+bun add -d @lumen-ops/plugin-sdk
+```
+
+Declare it as a peer dependency in published plugins:
+
+```json
+"peerDependencies": {
+  "@lumen-ops/plugin-sdk": "^1.0.0"
+}
+```
+
+## Usage
+
+```typescript
+import type { LumenPlugin } from "@lumen-ops/plugin-sdk"
+
+const plugin: LumenPlugin = {
+    name: "my-plugin",
+    description: "Does something useful",
+    configSchema: [
+        { key: "webhookUrl", label: "Webhook URL", type: "secret", required: true },
+    ],
+    hooks: {
+        "task:completed": async (ctx, { task, prUrl }) => {
+            const url = ctx.config.webhookUrl as string
+            if (!url) return
+            await ctx.http(url, {
+                method: "POST",
+                body: JSON.stringify({ text: `${task.issueKey} done — ${prUrl}` }),
+            })
+        },
+    },
+}
+
+export default plugin
+```
+
+## Versioning
+
+`@lumen-ops/plugin-sdk` is versioned independently of Lumen. Minor versions (`1.x`) add new hook types or context properties and are backwards-compatible. Major versions change existing interfaces and are rare.
+
+See [docs/plugins.md](../../docs/plugins.md) for the full guide including self-hosting, Docker setup, and all hook/interceptor types.

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+export interface Task {
+    id: string;
+    projectId: string;
+    issueKey: string;
+    issueTitle: string;
+    issueDescription: string | null;
+    issueType: string;
+    repositoryId: string | null;
+    baseBranch: string | null;
+    workBranch: string | null;
+    status: "pending" | "running" | "awaiting_approval" | "awaiting_feedback" | "merging" | "complete" | "failed";
+    flow: "direct" | "planned";
+    assignedUserId: string | null;
+    approvedByUserId: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface User {
+    id: string;
+    name: string;
+    email: string;
+    role: "admin" | "developer" | "collaborator" | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface Project {
+    id: string;
+    organizationId: string;
+    name: string;
+    trackerProjectKey: string;
+    defaultFlow: "direct" | "planned";
+    createdAt: Date;
+}
+export interface Run {
+    id: string;
+    taskId: string;
+    iterationId: string | null;
+    type: "plan" | "implement";
+    status: "queued" | "running" | "success" | "failed" | "cancelled";
+    harnessType: string;
+    executionBackend: string;
+    executionRef: string | null;
+    input: Record<string, unknown> | null;
+    output: Record<string, unknown> | null;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    createdAt: Date;
+}
+export interface Iteration {
+    id: string;
+    taskId: string;
+    /** 1-based sequence number within the task */
+    number: number;
+    /** Amendment feedback that triggered this iteration; null for iteration 1 */
+    feedback: string | null;
+    createdAt: Date;
+}
+export interface Artifact {
+    id: string;
+    taskId: string;
+    iterationId: string | null;
+    runId: string | null;
+    key: string;
+    value: string;
+    label: string | null;
+    type: "url" | "text" | "number" | "image";
+    createdAt: Date;
+}
+export type HookPayloads = {
+    "task:created": {
+        task: Task;
+    };
+    "task:assigned": {
+        task: Task;
+        assignee: User;
+    };
+    "task:planning": {
+        task: Task;
+    };
+    "task:plan-ready": {
+        task: Task;
+        plan: string;
+    };
+    "task:plan-approved": {
+        task: Task;
+        plan: string;
+    };
+    "task:plan-rejected": {
+        task: Task;
+        feedback: string;
+    };
+    "task:implementing": {
+        task: Task;
+    };
+    "task:awaiting_feedback": {
+        task: Task;
+        prUrl: string;
+        iterationNumber: number;
+    };
+    "task:amendment_requested": {
+        task: Task;
+        feedback: string;
+        iterationNumber: number;
+    };
+    "task:merging": {
+        task: Task;
+        prUrl: string;
+    };
+    "task:complete": {
+        task: Task;
+        prUrl: string;
+    };
+    "task:failed": {
+        task: Task;
+        error: string;
+    };
+};
+export type InterceptorPayloads = {
+    "plan:before-dispatch": {
+        task: Task;
+        prompt: string;
+    };
+    "implement:before-dispatch": {
+        task: Task;
+        plan: string | undefined;
+        prompt: string;
+    };
+    "amendment:before-dispatch": {
+        task: Task;
+        feedback: string;
+        prompt: string;
+    };
+};
+export type InterceptorResult<K extends keyof InterceptorPayloads> = Pick<InterceptorPayloads[K], "prompt">;
+export interface PluginContext {
+    tasks: {
+        get(id: string): Promise<Task>;
+        list(filters?: {
+            projectId?: string;
+            status?: Task["status"];
+        }): Promise<Task[]>;
+    };
+    projects: {
+        get(id: string): Promise<Project>;
+        list(): Promise<Project[]>;
+    };
+    runs: {
+        get(id: string): Promise<Run>;
+        listForTask(taskId: string): Promise<Run[]>;
+    };
+    iterations: {
+        get(id: string): Promise<Iteration>;
+        listForTask(taskId: string): Promise<Iteration[]>;
+    };
+    artifacts: {
+        listForTask(taskId: string): Promise<Artifact[]>;
+        listForIteration(iterationId: string): Promise<Artifact[]>;
+    };
+    http: typeof globalThis.fetch;
+    logger: {
+        info(msg: string, data?: Record<string, unknown>): void;
+        warn(msg: string, data?: Record<string, unknown>): void;
+        error(msg: string, data?: Record<string, unknown>): void;
+    };
+    /** Values from installed_plugin.config for this plugin */
+    config: Readonly<Record<string, unknown>>;
+}
+export interface PluginConfigField {
+    key: string;
+    label: string;
+    type: "string" | "secret" | "boolean" | "number" | "select";
+    /** Literal string options for "select" fields — inferred as a union when using definePlugin */
+    options?: readonly string[];
+    required?: boolean;
+    description?: string;
+}
+type FieldValueType<F extends PluginConfigField> = F["type"] extends "boolean" ? boolean : F["type"] extends "number" ? number : F["type"] extends "select" ? F["options"] extends readonly string[] ? F["options"][number] : string : string;
+type ConfigFromSchema<Fields extends readonly PluginConfigField[]> = {
+    [F in Fields[number] as F["key"]]: F["required"] extends true ? FieldValueType<F> : FieldValueType<F> | undefined;
+};
+/** PluginContext with config narrowed to the type inferred from configSchema */
+type TypedPluginContext<Config extends Record<string, unknown>> = Omit<PluginContext, "config"> & {
+    config: Readonly<Config>;
+};
+export interface LumenPlugin {
+    name: string;
+    version?: string;
+    description?: string;
+    configSchema?: PluginConfigField[];
+    hooks?: {
+        [K in keyof HookPayloads]?: (ctx: PluginContext, payload: HookPayloads[K]) => Promise<void>;
+    };
+    intercept?: {
+        [K in keyof InterceptorPayloads]?: (ctx: PluginContext, payload: InterceptorPayloads[K]) => Promise<InterceptorResult<K>>;
+    };
+    routes?: (app: any) => any;
+    ui?: Record<string, unknown>;
+}
+type PluginDefinition<Config extends Record<string, unknown>> = Omit<LumenPlugin, "hooks" | "intercept"> & {
+    hooks?: {
+        [K in keyof HookPayloads]?: (ctx: TypedPluginContext<Config>, payload: HookPayloads[K]) => Promise<void>;
+    };
+    intercept?: {
+        [K in keyof InterceptorPayloads]?: (ctx: TypedPluginContext<Config>, payload: InterceptorPayloads[K]) => Promise<InterceptorResult<K>>;
+    };
+};
+export declare function definePlugin<const Fields extends readonly PluginConfigField[]>(plugin: {
+    configSchema: Fields;
+} & PluginDefinition<ConfigFromSchema<Fields>>): LumenPlugin;
+export declare function definePlugin(plugin: LumenPlugin): LumenPlugin;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// Simplified entity types exposed to plugins.
+export function definePlugin(plugin) {
+    return plugin;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@lumen-ops/plugin-sdk",
+  "version": "0.2.0",
+  "description": "Type definitions for Lumen plugins",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "elysia": ">=1.2"
+  },
+  "peerDependenciesMeta": {
+    "elysia": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,214 @@
+// Simplified entity types exposed to plugins.
+
+export interface Task {
+    id: string
+    projectId: string
+    issueKey: string
+    issueTitle: string
+    issueDescription: string | null
+    issueType: string
+    repositoryId: string | null
+    baseBranch: string | null
+    workBranch: string | null
+    status: "pending" | "running" | "awaiting_approval" | "awaiting_feedback" | "merging" | "complete" | "failed"
+    flow: "direct" | "planned"
+    assignedUserId: string | null
+    approvedByUserId: string | null
+    metadata: Record<string, unknown> | null
+    createdAt: Date
+    updatedAt: Date
+}
+
+export interface User {
+    id: string
+    name: string
+    email: string
+    role: "admin" | "developer" | "collaborator" | null
+    createdAt: Date
+    updatedAt: Date
+}
+
+export interface Project {
+    id: string
+    organizationId: string
+    name: string
+    trackerProjectKey: string
+    defaultFlow: "direct" | "planned"
+    createdAt: Date
+}
+
+export interface Run {
+    id: string
+    taskId: string
+    iterationId: string | null
+    type: "plan" | "implement"
+    status: "queued" | "running" | "success" | "failed" | "cancelled"
+    harnessType: string
+    executionBackend: string
+    executionRef: string | null
+    input: Record<string, unknown> | null
+    output: Record<string, unknown> | null
+    startedAt: Date | null
+    completedAt: Date | null
+    createdAt: Date
+}
+
+export interface Iteration {
+    id: string
+    taskId: string
+    /** 1-based sequence number within the task */
+    number: number
+    /** Amendment feedback that triggered this iteration; null for iteration 1 */
+    feedback: string | null
+    createdAt: Date
+}
+
+export interface Artifact {
+    id: string
+    taskId: string
+    iterationId: string | null
+    runId: string | null
+    key: string
+    value: string
+    label: string | null
+    type: "url" | "text" | "number" | "image"
+    createdAt: Date
+}
+
+// Hook payloads
+
+export type HookPayloads = {
+    "task:created": { task: Task }
+    "task:assigned": { task: Task; assignee: User }
+    // Emitted when a plan run is dispatched (task status is "running")
+    "task:planning": { task: Task }
+    "task:plan-ready": { task: Task; plan: string }
+    "task:plan-approved": { task: Task; plan: string }
+    "task:plan-rejected": { task: Task; feedback: string }
+    // Emitted when an implement run is dispatched (task status is "running")
+    "task:implementing": { task: Task }
+    // Emitted when an implement run succeeds and the PR is ready for feedback
+    "task:awaiting_feedback": { task: Task; prUrl: string; iterationNumber: number }
+    // Emitted when an amendment is requested, triggering a new iteration
+    "task:amendment_requested": { task: Task; feedback: string; iterationNumber: number }
+    // Emitted when a merge is triggered
+    "task:merging": { task: Task; prUrl: string }
+    // Emitted when the task is fully complete (PR merged)
+    "task:complete": { task: Task; prUrl: string }
+    "task:failed": { task: Task; error: string }
+}
+
+// Interceptor payloads - return value modifies what gets dispatched
+
+export type InterceptorPayloads = {
+    "plan:before-dispatch": { task: Task; prompt: string }
+    "implement:before-dispatch": { task: Task; plan: string | undefined; prompt: string }
+    "amendment:before-dispatch": { task: Task; feedback: string; prompt: string }
+}
+
+export type InterceptorResult<K extends keyof InterceptorPayloads> = Pick<InterceptorPayloads[K], "prompt">
+
+// Plugin context - interface-only access to Lumen data
+
+export interface PluginContext {
+    tasks: {
+        get(id: string): Promise<Task>
+        list(filters?: { projectId?: string; status?: Task["status"] }): Promise<Task[]>
+    }
+    projects: {
+        get(id: string): Promise<Project>
+        list(): Promise<Project[]>
+    }
+    runs: {
+        get(id: string): Promise<Run>
+        listForTask(taskId: string): Promise<Run[]>
+    }
+    iterations: {
+        get(id: string): Promise<Iteration>
+        listForTask(taskId: string): Promise<Iteration[]>
+    }
+    artifacts: {
+        listForTask(taskId: string): Promise<Artifact[]>
+        listForIteration(iterationId: string): Promise<Artifact[]>
+    }
+    http: typeof globalThis.fetch
+    logger: {
+        info(msg: string, data?: Record<string, unknown>): void
+        warn(msg: string, data?: Record<string, unknown>): void
+        error(msg: string, data?: Record<string, unknown>): void
+    }
+    /** Values from installed_plugin.config for this plugin */
+    config: Readonly<Record<string, unknown>>
+}
+
+// Config schema - drives the admin UI config form
+
+export interface PluginConfigField {
+    key: string
+    label: string
+    type: "string" | "secret" | "boolean" | "number" | "select"
+    /** Literal string options for "select" fields — inferred as a union when using definePlugin */
+    options?: readonly string[]
+    required?: boolean
+    description?: string
+}
+
+// Config type inference from schema
+
+type FieldValueType<F extends PluginConfigField> = F["type"] extends "boolean"
+    ? boolean
+    : F["type"] extends "number"
+      ? number
+      : F["type"] extends "select"
+        ? F["options"] extends readonly string[]
+            ? F["options"][number]
+            : string
+        : string
+
+type ConfigFromSchema<Fields extends readonly PluginConfigField[]> = {
+    [F in Fields[number] as F["key"]]: F["required"] extends true ? FieldValueType<F> : FieldValueType<F> | undefined
+}
+
+/** PluginContext with config narrowed to the type inferred from configSchema */
+type TypedPluginContext<Config extends Record<string, unknown>> = Omit<PluginContext, "config"> & {
+    config: Readonly<Config>
+}
+
+export interface LumenPlugin {
+    name: string
+    version?: string
+    description?: string
+    configSchema?: PluginConfigField[]
+    hooks?: {
+        [K in keyof HookPayloads]?: (ctx: PluginContext, payload: HookPayloads[K]) => Promise<void>
+    }
+    intercept?: {
+        [K in keyof InterceptorPayloads]?: (
+            ctx: PluginContext,
+            payload: InterceptorPayloads[K],
+        ) => Promise<InterceptorResult<K>>
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    routes?: (app: any) => any
+    ui?: Record<string, unknown>
+}
+
+type PluginDefinition<Config extends Record<string, unknown>> = Omit<LumenPlugin, "hooks" | "intercept"> & {
+    hooks?: {
+        [K in keyof HookPayloads]?: (ctx: TypedPluginContext<Config>, payload: HookPayloads[K]) => Promise<void>
+    }
+    intercept?: {
+        [K in keyof InterceptorPayloads]?: (
+            ctx: TypedPluginContext<Config>,
+            payload: InterceptorPayloads[K],
+        ) => Promise<InterceptorResult<K>>
+    }
+}
+
+export function definePlugin<const Fields extends readonly PluginConfigField[]>(
+    plugin: { configSchema: Fields } & PluginDefinition<ConfigFromSchema<Fields>>,
+): LumenPlugin
+export function definePlugin(plugin: LumenPlugin): LumenPlugin
+export function definePlugin(plugin: unknown): LumenPlugin {
+    return plugin as LumenPlugin
+}