@justscale/core 0.1.0

package/dist/cluster/scheduled-task/factory.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ScheduledTask Route Factory
+ *
+ * Creates the ScheduledTask route factory for defining scheduled task handlers.
+ *
+ * @example
+ * ```typescript
+ * import { createController } from '../../index.js'
+ * import { ScheduledTask } from '@justscale/cluster/scheduled-task'
+ *
+ * const ProcessController = createController({
+ *   inject: { executor: ProcessExecutor },
+ *   routes: ({ deps }) => ({
+ *     processDelay: ScheduledTask('process', 'delay')
+ *       .payload(z.object({
+ *         instanceId: z.string(),
+ *         branchId: z.string().optional(),
+ *       }))
+ *       .handle(async ({ payload, deps }) => {
+ *         await deps.executor.resume(payload.instanceId, payload.branchId)
+ *       }),
+ *   }),
+ * })
+ * ```
+ */
+import type { ScheduledTaskContext, ScheduledTaskRouteBuilder } from './types.js';
+/**
+ * ScheduledTask route factory.
+ *
+ * Creates a route builder for handling scheduled tasks.
+ *
+ * @param namespace - Task namespace (e.g., 'process', 'email')
+ * @param type - Task type within namespace (e.g., 'delay', 'reminder')
+ *
+ * @example Builder pattern with payload schema
+ * ```typescript
+ * ScheduledTask('email', 'reminder')
+ *   .payload(z.object({ userId: z.string() }))
+ *   .use(ctx => ({ logger: createLogger('email') }))
+ *   .handle(async ({ payload, logger }) => {
+ *     await sendReminderEmail(payload.userId)
+ *   })
+ * ```
+ *
+ * @example With guards
+ * ```typescript
+ * ScheduledTask('order', 'timeout')
+ *   .payload(z.object({ orderId: z.string() }))
+ *   .guard(async ({ task }) => {
+ *     // Skip if task is too old
+ *     return Date.now() - task.dueAt.getTime() < 60_000
+ *   })
+ *   .handle(async ({ payload }) => {
+ *     await cancelOrder(payload.orderId)
+ *   })
+ * ```
+ */
+export declare function ScheduledTask(namespace: string, type: string): ScheduledTaskRouteBuilder<Record<string, unknown>, unknown, ScheduledTaskContext<Record<string, unknown>, unknown>>;
+declare module '@justscale/core' {
+    interface SupportedMethods {
+        SCHEDULED_TASK: {
+            transport: 'scheduled-task';
+        };
+    }
+}
+declare module '@justscale/core/plugin' {
+    interface SupportedMethods {
+        SCHEDULED_TASK: {
+            transport: 'scheduled-task';
+        };
+    }
+    interface RouteFactories<TDeps> {
+        ScheduledTask(namespace: string, type: string): ScheduledTaskRouteBuilder<TDeps, unknown, ScheduledTaskContext<TDeps, unknown>>;
+    }
+}
+//# sourceMappingURL=factory.d.ts.map

package/dist/cluster/scheduled-task/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/cluster/scheduled-task/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EACV,oBAAoB,EACpB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,yBAAyB,CAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,OAAO,EACP,oBAAoB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CACvD,CAEA;AAMD,OAAO,QAAQ,iBAAiB,CAAC;IAC/B,UAAU,gBAAgB;QACxB,cAAc,EAAE;YAAE,SAAS,EAAE,gBAAgB,CAAA;SAAE,CAAA;KAChD;CACF;AAED,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,gBAAgB;QACxB,cAAc,EAAE;YAAE,SAAS,EAAE,gBAAgB,CAAA;SAAE,CAAA;KAChD;IAED,UAAU,cAAc,CAAC,KAAK;QAC5B,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAA;KACnF;CACF"}

package/dist/cluster/scheduled-task/factory.js

@@ -0,0 +1,64 @@
+/**
+ * ScheduledTask Route Factory
+ *
+ * Creates the ScheduledTask route factory for defining scheduled task handlers.
+ *
+ * @example
+ * ```typescript
+ * import { createController } from '../../index.js'
+ * import { ScheduledTask } from '@justscale/cluster/scheduled-task'
+ *
+ * const ProcessController = createController({
+ *   inject: { executor: ProcessExecutor },
+ *   routes: ({ deps }) => ({
+ *     processDelay: ScheduledTask('process', 'delay')
+ *       .payload(z.object({
+ *         instanceId: z.string(),
+ *         branchId: z.string().optional(),
+ *       }))
+ *       .handle(async ({ payload, deps }) => {
+ *         await deps.executor.resume(payload.instanceId, payload.branchId)
+ *       }),
+ *   }),
+ * })
+ * ```
+ */
+import { registerRouteFactory } from '../../index.js';
+import { createScheduledTaskRouteBuilder } from './builder.js';
+/**
+ * ScheduledTask route factory.
+ *
+ * Creates a route builder for handling scheduled tasks.
+ *
+ * @param namespace - Task namespace (e.g., 'process', 'email')
+ * @param type - Task type within namespace (e.g., 'delay', 'reminder')
+ *
+ * @example Builder pattern with payload schema
+ * ```typescript
+ * ScheduledTask('email', 'reminder')
+ *   .payload(z.object({ userId: z.string() }))
+ *   .use(ctx => ({ logger: createLogger('email') }))
+ *   .handle(async ({ payload, logger }) => {
+ *     await sendReminderEmail(payload.userId)
+ *   })
+ * ```
+ *
+ * @example With guards
+ * ```typescript
+ * ScheduledTask('order', 'timeout')
+ *   .payload(z.object({ orderId: z.string() }))
+ *   .guard(async ({ task }) => {
+ *     // Skip if task is too old
+ *     return Date.now() - task.dueAt.getTime() < 60_000
+ *   })
+ *   .handle(async ({ payload }) => {
+ *     await cancelOrder(payload.orderId)
+ *   })
+ * ```
+ */
+export function ScheduledTask(namespace, type) {
+    return createScheduledTaskRouteBuilder(namespace, type);
+}
+// Register the factory for use in controllers
+registerRouteFactory('ScheduledTask', ScheduledTask);
+//# sourceMappingURL=factory.js.map

package/dist/cluster/scheduled-task/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/cluster/scheduled-task/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAM/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAiB,EACjB,IAAY;IAMZ,OAAO,+BAA+B,CAAmC,SAAS,EAAE,IAAI,CAAC,CAAC;AAC5F,CAAC;AAED,8CAA8C;AAC9C,oBAAoB,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC"}

package/dist/cluster/scheduled-task/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @justscale/cluster/scheduled-task
+ *
+ * Route factory for handling scheduled tasks in controllers.
+ * Auto-registers as a transport plugin - tasks are processed when cluster.serve() is called.
+ *
+ * @example
+ * ```typescript
+ * import { createController } from '../../index.js'
+ * import { createClusterBuilder } from '@justscale/cluster'
+ * import { ScheduledTask } from '@justscale/cluster/scheduled-task'
+ * import { InMemoryScheduledTaskRepository } from '../../models/index.js'
+ * import { z } from 'zod'
+ *
+ * const TaskController = createController({
+ *   routes: () => ({
+ *     processDelay: ScheduledTask('process', 'delay')
+ *       .payload(z.object({
+ *         instanceId: z.string(),
+ *         branchId: z.string().optional(),
+ *       }))
+ *       .handle(async ({ payload }) => {
+ *         await resumeProcess(payload.instanceId, payload.branchId)
+ *       }),
+ *   }),
+ * })
+ *
+ * const cluster = createClusterBuilder()
+ *   .add(InMemoryScheduledTaskRepository)
+ *   .add(TaskController)
+ *   .build()
+ *
+ * // Scheduled task processing starts automatically
+ * await cluster.serve({ http: 3000 })
+ * ```
+ */
+export { ScheduledTask } from './factory.js';
+export { createScheduledTaskRouteBuilder } from './builder.js';
+export { SCHEDULED_TASK_NAMESPACE, SCHEDULED_TASK_TYPE, SCHEDULED_TASK_QUALIFIED_NAME, SCHEDULED_TASK_PAYLOAD_SCHEMA, getScheduledTaskQualifiedName, getScheduledTaskPayloadSchema, } from './builder.js';
+export type { ScheduledTaskContext, ScheduledTaskRouteDef, ScheduledTaskRouteBuilder, } from './types.js';
+export type { ScheduledTaskServeOptions } from './transport.js';
+import './transport.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cluster/scheduled-task/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cluster/scheduled-task/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,OAAO,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAG/D,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,6BAA6B,EAC7B,6BAA6B,EAC7B,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,gBAAgB,CAAC"}

package/dist/cluster/scheduled-task/index.js

@@ -0,0 +1,45 @@
+/**
+ * @justscale/cluster/scheduled-task
+ *
+ * Route factory for handling scheduled tasks in controllers.
+ * Auto-registers as a transport plugin - tasks are processed when cluster.serve() is called.
+ *
+ * @example
+ * ```typescript
+ * import { createController } from '../../index.js'
+ * import { createClusterBuilder } from '@justscale/cluster'
+ * import { ScheduledTask } from '@justscale/cluster/scheduled-task'
+ * import { InMemoryScheduledTaskRepository } from '../../models/index.js'
+ * import { z } from 'zod'
+ *
+ * const TaskController = createController({
+ *   routes: () => ({
+ *     processDelay: ScheduledTask('process', 'delay')
+ *       .payload(z.object({
+ *         instanceId: z.string(),
+ *         branchId: z.string().optional(),
+ *       }))
+ *       .handle(async ({ payload }) => {
+ *         await resumeProcess(payload.instanceId, payload.branchId)
+ *       }),
+ *   }),
+ * })
+ *
+ * const cluster = createClusterBuilder()
+ *   .add(InMemoryScheduledTaskRepository)
+ *   .add(TaskController)
+ *   .build()
+ *
+ * // Scheduled task processing starts automatically
+ * await cluster.serve({ http: 3000 })
+ * ```
+ */
+// Factory function (registers route factory as side effect)
+export { ScheduledTask } from './factory.js';
+// Builder (for advanced use)
+export { createScheduledTaskRouteBuilder } from './builder.js';
+// Builder symbols (for route detection)
+export { SCHEDULED_TASK_NAMESPACE, SCHEDULED_TASK_TYPE, SCHEDULED_TASK_QUALIFIED_NAME, SCHEDULED_TASK_PAYLOAD_SCHEMA, getScheduledTaskQualifiedName, getScheduledTaskPayloadSchema, } from './builder.js';
+// Auto-register transport plugin (side effect import)
+import './transport.js';
+//# sourceMappingURL=index.js.map

package/dist/cluster/scheduled-task/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cluster/scheduled-task/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,4DAA4D;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,6BAA6B;AAC7B,OAAO,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAE/D,wCAAwC;AACxC,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,6BAA6B,EAC7B,6BAA6B,EAC7B,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AAYtB,sDAAsD;AACtD,OAAO,gBAAgB,CAAC"}

package/dist/cluster/scheduled-task/transport.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Transport plugin for scheduled tasks.
+ * Auto-registers on import and starts processing when cluster.serve() is called.
+ */
+/**
+ * Options for scheduled task transport.
+ */
+export interface ScheduledTaskServeOptions {
+    /** Polling interval in ms (default: 1000) */
+    pollInterval?: number;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/cluster/scheduled-task/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/cluster/scheduled-task/transport.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuCH;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB"}

package/dist/cluster/scheduled-task/transport.js

@@ -0,0 +1,146 @@
+/**
+ * Transport plugin for scheduled tasks.
+ * Auto-registers on import and starts processing when cluster.serve() is called.
+ */
+import { registerTransport, } from '../cluster.js';
+import { ScheduledTaskRepository, } from '../../models/index.js';
+import { ADAPTER_KEY } from '../../models/symbols.js';
+import { getScheduledTaskQualifiedName, getScheduledTaskPayloadSchema, } from './builder.js';
+/** Symbol to store worker state on the cluster */
+const WORKER_STATE = Symbol('scheduledTask:workerState');
+/** Read the worker state from a cluster instance. */
+function getWorkerState(cluster) {
+    return cluster?.[WORKER_STATE];
+}
+/** Set the worker state on a cluster instance. */
+function setWorkerState(cluster, state) {
+    cluster[WORKER_STATE] = state;
+}
+/**
+ * Process a single task through the route's middleware pipeline.
+ */
+async function processTask(task, entry) {
+    const { route, payloadSchema, deps } = entry;
+    // Validate payload if schema is provided
+    let payload = task.payload;
+    if (payloadSchema) {
+        const result = payloadSchema.safeParse(task.payload);
+        if (!result.success) {
+            console.error(`[ScheduledTask] Payload validation failed for task ${task[ADAPTER_KEY]}:`, result.error.flatten());
+            return; // Skip task with invalid payload
+        }
+        payload = result.data;
+    }
+    // Build context
+    const ctx = {
+        deps,
+        task,
+        payload,
+        qualifiedName: task.qualifiedName,
+    };
+    // Execute middlewares (from CompiledRoute)
+    let context = ctx;
+    for (const middleware of route.middlewares || []) {
+        if (typeof middleware === 'function') {
+            const added = await middleware(context);
+            context = { ...context, ...added };
+        }
+    }
+    // Execute guards (from CompiledRoute)
+    for (const guard of route.guards || []) {
+        if (typeof guard === 'function') {
+            const result = await guard(context);
+            if (result === false) {
+                return; // Guard rejected, skip handler
+            }
+        }
+    }
+    // Execute handler
+    await route.handler(context);
+}
+/**
+ * Scheduled task transport plugin.
+ * Auto-starts processing when cluster.serve() is called.
+ */
+const scheduledTaskTransport = {
+    name: 'scheduled-task',
+    async onServe(cluster, options) {
+        const app = cluster.app;
+        const pollInterval = options.scheduledTask?.pollInterval ?? 1000;
+        // Try to resolve the repository from the container
+        let repository;
+        try {
+            repository = await app.container.resolve(ScheduledTaskRepository);
+        }
+        catch {
+            // No repository registered - check if there are any scheduled task routes
+            const hasScheduledTaskRoutes = app.controllers.some(controller => controller.routes.some((route) => route.method === 'SCHEDULED_TASK'));
+            if (hasScheduledTaskRoutes) {
+                console.warn('[ScheduledTask] Found ScheduledTask routes but no ScheduledTaskRepository registered. ' +
+                    'Add InMemoryScheduledTaskRepository or PgScheduledTaskRepository to your cluster.');
+            }
+            return;
+        }
+        const routesByQualifiedName = new Map();
+        for (const controller of app.controllers) {
+            for (const route of controller.routes) {
+                if (route.method === 'SCHEDULED_TASK') {
+                    const qualifiedName = getScheduledTaskQualifiedName(route);
+                    const payloadSchema = getScheduledTaskPayloadSchema(route);
+                    if (qualifiedName) {
+                        routesByQualifiedName.set(qualifiedName, {
+                            route,
+                            qualifiedName,
+                            payloadSchema,
+                            deps: controller.deps,
+                        });
+                    }
+                }
+            }
+        }
+        if (routesByQualifiedName.size === 0) {
+            return; // No scheduled task routes
+        }
+        const state = {
+            running: true,
+            abortController: new AbortController(),
+            subscriptionPromises: [],
+        };
+        setWorkerState(cluster, state);
+        for (const [qualifiedName, entry] of routesByQualifiedName) {
+            const promise = (async () => {
+                try {
+                    for await (const task of repository.subscribe(qualifiedName, {
+                        signal: state.abortController?.signal,
+                        pollInterval,
+                    })) {
+                        try {
+                            await processTask(task, entry);
+                        }
+                        catch (error) {
+                            console.error(`[ScheduledTask] Error processing task ${task[ADAPTER_KEY]}:`, error);
+                        }
+                    }
+                }
+                catch (error) {
+                    if (state.running) {
+                        console.error(`[ScheduledTask] Subscription error for ${qualifiedName}:`, error);
+                    }
+                }
+            })();
+            state.subscriptionPromises.push(promise);
+        }
+        console.log(`[ScheduledTask] Started processing ${routesByQualifiedName.size} task type(s)`);
+    },
+    async onStop(cluster) {
+        const state = getWorkerState(cluster);
+        if (!state)
+            return;
+        state.running = false;
+        state.abortController?.abort();
+        await Promise.all(state.subscriptionPromises);
+        console.log('[ScheduledTask] Stopped processing');
+    },
+};
+registerTransport(scheduledTaskTransport);
+//# sourceMappingURL=transport.js.map

package/dist/cluster/scheduled-task/transport.js.map

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

package/dist/cluster/scheduled-task/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * ScheduledTask Route Types
+ *
+ * Type definitions for scheduled task routes in controllers.
+ */
+import type { Prettify } from '../../index.js';
+import type { z } from 'zod';
+import type { Persistent, ScheduledTask } from '../../models/index.js';
+/**
+ * Context passed to scheduled task handlers.
+ */
+export interface ScheduledTaskContext<TDeps = Record<string, unknown>, TPayload = unknown> {
+    /** Controller dependencies */
+    deps: TDeps;
+    /** The task being processed */
+    task: Persistent<ScheduledTask>;
+    /** Typed and validated payload from the task */
+    payload: TPayload;
+    /** The qualified name (namespace.type) */
+    qualifiedName: string;
+}
+/**
+ * Scheduled task route definition.
+ */
+export interface ScheduledTaskRouteDef<TDeps = Record<string, unknown>, TPayload = unknown> {
+    /** Route method - always 'SCHEDULED_TASK' */
+    method: 'SCHEDULED_TASK';
+    /** Path (same as qualifiedName for routing compatibility) */
+    path: string;
+    /** Task namespace (e.g., 'process', 'email') */
+    namespace: string;
+    /** Task type within namespace (e.g., 'delay', 'reminder') */
+    type: string;
+    /** Qualified name (namespace.type) */
+    qualifiedName: string;
+    /** Zod schema for payload validation (optional but recommended) */
+    payloadSchema?: z.ZodType<TPayload>;
+    /** Middleware and guards pipeline */
+    steps: {
+        type: 'use' | 'guard';
+        fn: any;
+    }[];
+    /** Response schemas */
+    responseSchemas: Map<number, any>;
+    /** The handler function */
+    handler: (ctx: ScheduledTaskContext<TDeps, TPayload>) => void | Promise<void>;
+}
+/**
+ * Builder interface for scheduled task routes.
+ *
+ * @typeParam TDeps - Controller dependencies
+ * @typeParam TPayload - Task payload type
+ * @typeParam TContext - Current context after middleware
+ */
+export interface ScheduledTaskRouteBuilder<TDeps, TPayload, TContext extends ScheduledTaskContext<TDeps, TPayload>> {
+    /**
+     * Specify the payload schema for validation.
+     * The worker will validate the task payload against this schema
+     * before calling the handler.
+     *
+     * @example
+     * ```typescript
+     * ScheduledTask('process', 'delay')
+     *   .payload(z.object({
+     *     instanceId: z.string(),
+     *     branchId: z.string().optional(),
+     *   }))
+     *   .handle(async ({ payload }) => {
+     *     // payload is typed as { instanceId: string; branchId?: string }
+     *   })
+     * ```
+     */
+    payload<TSchema extends z.ZodType>(schema: TSchema): ScheduledTaskRouteBuilder<TDeps, z.infer<TSchema>, Prettify<Omit<TContext, 'payload'> & {
+        payload: z.infer<TSchema>;
+    }>>;
+    /**
+     * Add middleware that extends the context.
+     */
+    use<TAdded extends object>(middleware: ((ctx: TContext) => TAdded | Promise<TAdded>)): ScheduledTaskRouteBuilder<TDeps, TPayload, Prettify<TContext & TAdded>>;
+    /**
+     * Add a guard that gates access to the handler.
+     */
+    guard(check: (ctx: TContext) => void | boolean | Promise<void | boolean>): ScheduledTaskRouteBuilder<TDeps, TPayload, TContext>;
+    /**
+     * Set the final handler for the task.
+     */
+    handle(handler: (ctx: TContext) => void | Promise<void>): ScheduledTaskRouteDef<TDeps, TPayload>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cluster/scheduled-task/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/cluster/scheduled-task/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,oBAAoB,CACnC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,GAAG,OAAO;IAElB,8BAA8B;IAC9B,IAAI,EAAE,KAAK,CAAA;IACX,+BAA+B;IAC/B,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,CAAA;IAC/B,gDAAgD;IAChD,OAAO,EAAE,QAAQ,CAAA;IACjB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB,CACpC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,GAAG,OAAO;IAElB,6CAA6C;IAC7C,MAAM,EAAE,gBAAgB,CAAA;IACxB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAA;IACjB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAA;IACrB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnC,qCAAqC;IACrC,KAAK,EAAE;QAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;QAAC,EAAE,EAAE,GAAG,CAAA;KAAE,EAAE,CAAA;IAC3C,uBAAuB;IACvB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACjC,2BAA2B;IAC3B,OAAO,EAAE,CAAC,GAAG,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB,CACxC,KAAK,EACL,QAAQ,EACR,QAAQ,SAAS,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC;IAEtD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,EAC/B,MAAM,EAAE,OAAO,GACd,yBAAyB,CAC1B,KAAK,EACL,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAChB,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC,CACpE,CAAA;IAED;;OAEG;IACH,GAAG,CAAC,MAAM,SAAS,MAAM,EACvB,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GACxD,yBAAyB,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAA;IAE1E;;OAEG;IACH,KAAK,CACH,KAAK,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,GACjE,yBAAyB,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;IAEvD;;OAEG;IACH,MAAM,CACJ,OAAO,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC/C,qBAAqB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;CAC1C"}

package/dist/cluster/scheduled-task/types.js

@@ -0,0 +1,7 @@
+/**
+ * ScheduledTask Route Types
+ *
+ * Type definitions for scheduled task routes in controllers.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cluster/scheduled-task/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/cluster/scheduled-task/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/cluster/server.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Cluster server - listens for incoming connections and dispatches protocol messages.
+ * Method handlers are registered by plugins.
+ */
+import { EventEmitter } from 'node:events';
+import { type App } from '../index.js';
+import { type PromptType } from './protocol.js';
+import { type Transport } from './transport.js';
+export interface ServerOptions {
+    /** Socket path (auto-generated if not provided) */
+    socketPath?: string;
+    /** App root directory for socket path generation */
+    appRoot?: string;
+}
+export interface ServerEvents {
+    listening: [path: string];
+    connection: [transport: Transport];
+    error: [error: Error];
+    close: [];
+}
+/** Method handler function */
+export type MethodHandler = (params: Record<string, unknown> | undefined, context: HandlerContext) => Promise<unknown>;
+/** Context passed to method handlers */
+export interface HandlerContext {
+    /** The transport this request came from */
+    transport: Transport;
+    /** Send a stream message */
+    stream: (channel: string, data: unknown, done?: boolean) => Promise<void>;
+    /** Request user input via the client */
+    prompt: (type: PromptType, message: string, options?: PromptOptions) => Promise<string | boolean | null>;
+    /** The JustScale app (if attached) */
+    app?: App<any>;
+    /** The cluster server instance */
+    server: ClusterServer;
+}
+export interface PromptOptions {
+    defaultValue?: string;
+    choices?: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+export declare class ClusterServer extends EventEmitter {
+    private server;
+    private socketPath;
+    private connections;
+    private handlers;
+    private app?;
+    /** Pending prompt responses: requestId -> (promptId -> resolver) */
+    private pendingPrompts;
+    /** Maps transport to the set of request IDs it owns */
+    private transportRequests;
+    private promptCounter;
+    constructor(options?: ServerOptions);
+    /**
+     * Attach a JustScale app for CLI command execution.
+     */
+    attachApp(app: App<any>): this;
+    /**
+     * Register a method handler.
+     */
+    handle(method: string, handler: MethodHandler): this;
+    /**
+     * Start listening for connections.
+     */
+    listen(): Promise<string>;
+    /**
+     * Stop the server.
+     */
+    close(): Promise<void>;
+    /**
+     * Get the socket path.
+     */
+    get path(): string;
+    /**
+     * Check if listening.
+     */
+    get listening(): boolean;
+    private handleConnection;
+    private handleMessage;
+    private registerBuiltinHandlers;
+}
+/**
+ * Create a cluster server.
+ */
+export declare function createClusterServer(options?: ServerOptions): ClusterServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/cluster/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/cluster/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAIL,KAAK,UAAU,EAQhB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,SAAS,EAIf,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1B,UAAU,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACnC,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACtB,KAAK,EAAE,EAAE,CAAC;CACX;AAED,8BAA8B;AAC9B,MAAM,MAAM,aAAa,GAAG,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,SAAS,EAAE,SAAS,CAAC;IACrB,4BAA4B;IAC5B,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,wCAAwC;IACxC,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IACzG,sCAAsC;IACtC,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,kCAAkC;IAClC,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnD;AAED,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,GAAG,CAAC,CAAW;IACvB,oEAAoE;IACpE,OAAO,CAAC,cAAc,CAA0E;IAChG,uDAAuD;IACvD,OAAO,CAAC,iBAAiB,CAAqC;IAC9D,OAAO,CAAC,aAAa,CAAK;gBAEd,OAAO,GAAE,aAAkB;IAQvC;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI;IAK9B;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI;IAKpD;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAyB/B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,OAAO,CAAC,gBAAgB;YAuCV,aAAa;IAuF3B,OAAO,CAAC,uBAAuB;CAoBhC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CAE1E"}