skeleton-crew-runtime 0.1.1

package/dist/types.js

@@ -0,0 +1,93 @@
+// Core type definitions will be implemented in task 2
+// Error Classes
+/**
+ * Error thrown when validation fails for a resource
+ * @see Requirements 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
+ */
+export class ValidationError extends Error {
+    resourceType;
+    field;
+    resourceId;
+    constructor(resourceType, field, resourceId) {
+        super(`Validation failed for ${resourceType}${resourceId ? ` "${resourceId}"` : ''}: missing or invalid field "${field}"`);
+        this.resourceType = resourceType;
+        this.field = field;
+        this.resourceId = resourceId;
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Error thrown when attempting to register a duplicate resource
+ * @see Requirements 15.1, 15.2, 15.3, 15.4, 15.5
+ */
+export class DuplicateRegistrationError extends Error {
+    resourceType;
+    identifier;
+    constructor(resourceType, identifier) {
+        super(`${resourceType} with identifier "${identifier}" is already registered`);
+        this.resourceType = resourceType;
+        this.identifier = identifier;
+        this.name = 'DuplicateRegistrationError';
+    }
+}
+/**
+ * Error thrown when an action execution exceeds its timeout
+ * @see Requirements 11.1, 11.2, 11.3, 11.4, 11.5
+ */
+export class ActionTimeoutError extends Error {
+    actionId;
+    timeoutMs;
+    constructor(actionId, timeoutMs) {
+        super(`Action "${actionId}" timed out after ${timeoutMs}ms`);
+        this.actionId = actionId;
+        this.timeoutMs = timeoutMs;
+        this.name = 'ActionTimeoutError';
+    }
+}
+/**
+ * Error thrown when an action handler throws an error
+ * @see Requirements 3.1, 3.2, 3.3, 3.4, 3.5
+ */
+export class ActionExecutionError extends Error {
+    actionId;
+    cause;
+    constructor(actionId, cause) {
+        super(`Action "${actionId}" execution failed: ${cause.message}`);
+        this.actionId = actionId;
+        this.cause = cause;
+        this.name = 'ActionExecutionError';
+        this.cause = cause;
+    }
+}
+/**
+ * Default console-based logger implementation
+ * @see Requirements 7.1, 7.2, 7.3, 7.4, 7.5, 7.6
+ */
+export class ConsoleLogger {
+    debug(message, ...args) {
+        console.debug(message, ...args);
+    }
+    info(message, ...args) {
+        console.info(message, ...args);
+    }
+    warn(message, ...args) {
+        console.warn(message, ...args);
+    }
+    error(message, ...args) {
+        console.error(message, ...args);
+    }
+}
+// Runtime State Enum
+/**
+ * Runtime lifecycle states
+ * @see Requirements 16.1, 16.2, 16.3, 16.4, 16.5
+ */
+export var RuntimeState;
+(function (RuntimeState) {
+    RuntimeState["Uninitialized"] = "uninitialized";
+    RuntimeState["Initializing"] = "initializing";
+    RuntimeState["Initialized"] = "initialized";
+    RuntimeState["ShuttingDown"] = "shutting_down";
+    RuntimeState["Shutdown"] = "shutdown";
+})(RuntimeState || (RuntimeState = {}));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sDAAsD;AAEtD,gBAAgB;AAEhB;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE/B;IACA;IACA;IAHT,YACS,YAAoB,EACpB,KAAa,EACb,UAAmB;QAE1B,KAAK,CACH,yBAAyB,YAAY,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,+BAA+B,KAAK,GAAG,CACpH,CAAC;QANK,iBAAY,GAAZ,YAAY,CAAQ;QACpB,UAAK,GAAL,KAAK,CAAQ;QACb,eAAU,GAAV,UAAU,CAAS;QAK1B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAE1C;IACA;IAFT,YACS,YAAoB,EACpB,UAAkB;QAEzB,KAAK,CAAC,GAAG,YAAY,qBAAqB,UAAU,yBAAyB,CAAC,CAAC;QAHxE,iBAAY,GAAZ,YAAY,CAAQ;QACpB,eAAU,GAAV,UAAU,CAAQ;QAGzB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAElC;IACA;IAFT,YACS,QAAgB,EAChB,SAAiB;QAExB,KAAK,CAAC,WAAW,QAAQ,qBAAqB,SAAS,IAAI,CAAC,CAAC;QAHtD,aAAQ,GAAR,QAAQ,CAAQ;QAChB,cAAS,GAAT,SAAS,CAAQ;QAGxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAEpC;IACA;IAFT,YACS,QAAgB,EAChB,KAAY;QAEnB,KAAK,CAAC,WAAW,QAAQ,uBAAuB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAH1D,aAAQ,GAAR,QAAQ,CAAQ;QAChB,UAAK,GAAL,KAAK,CAAO;QAGnB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAeD;;;GAGG;AACH,MAAM,OAAO,aAAa;IACxB,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;QACvC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;QACtC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;QACtC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACjC,CAAC;IACD,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;QACvC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IAClC,CAAC;CACF;AAED,qBAAqB;AAErB;;;GAGG;AACH,MAAM,CAAN,IAAY,YAMX;AAND,WAAY,YAAY;IACtB,+CAA+B,CAAA;IAC/B,6CAA6B,CAAA;IAC7B,2CAA2B,CAAA;IAC3B,8CAA8B,CAAA;IAC9B,qCAAqB,CAAA;AACvB,CAAC,EANW,YAAY,KAAZ,YAAY,QAMvB"}

package/dist/ui-bridge.d.ts

@@ -0,0 +1,39 @@
+import { UIProvider, ScreenDefinition, Logger } from './types.js';
+/**
+ * UIBridge manages optional UI provider registration and screen rendering.
+ * Validates provider implements required methods and rejects duplicate registration.
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6, 15.1, 15.2, 15.3, 15.4, 15.5
+ */
+export declare class UIBridge {
+    private provider;
+    private logger;
+    constructor(logger: Logger);
+    /**
+     * Register a UI provider with the runtime.
+     * @throws ValidationError if provider is missing required methods
+     * @throws DuplicateRegistrationError if provider is already registered
+     * @see Requirements 9.1, 9.2, 9.4, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6, 15.1, 15.2, 15.3, 15.4, 15.5
+     */
+    setProvider(provider: UIProvider): void;
+    /**
+     * Get the registered UI provider.
+     * @returns The registered UIProvider or null if none registered
+     */
+    getProvider(): UIProvider | null;
+    /**
+     * Render a screen using the registered UI provider.
+     * @throws Error if no UI provider is registered
+     * @see Requirements 9.2
+     */
+    renderScreen(screen: ScreenDefinition): unknown;
+    /**
+     * Shutdown the UI provider by calling unmount if it exists.
+     * @see Requirements 9.5
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Clear the UI provider during shutdown.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=ui-bridge.d.ts.map

package/dist/ui-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-bridge.d.ts","sourceRoot":"","sources":["../src/ui-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAA+C,MAAM,YAAY,CAAC;AAE/G;;;;GAIG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM;IAI1B;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;IAkBvC;;;OAGG;IACH,WAAW,IAAI,UAAU,GAAG,IAAI;IAIhC;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;IAQ/C;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAY/B;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/ui-bridge.js

@@ -0,0 +1,74 @@
+import { ValidationError, DuplicateRegistrationError } from './types.js';
+/**
+ * UIBridge manages optional UI provider registration and screen rendering.
+ * Validates provider implements required methods and rejects duplicate registration.
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6, 15.1, 15.2, 15.3, 15.4, 15.5
+ */
+export class UIBridge {
+    provider = null;
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Register a UI provider with the runtime.
+     * @throws ValidationError if provider is missing required methods
+     * @throws DuplicateRegistrationError if provider is already registered
+     * @see Requirements 9.1, 9.2, 9.4, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6, 15.1, 15.2, 15.3, 15.4, 15.5
+     */
+    setProvider(provider) {
+        // Reject duplicate provider registration
+        if (this.provider !== null) {
+            throw new DuplicateRegistrationError('UIProvider', 'default');
+        }
+        // Validate provider has required methods
+        if (typeof provider.mount !== 'function') {
+            throw new ValidationError('UIProvider', 'mount');
+        }
+        if (typeof provider.renderScreen !== 'function') {
+            throw new ValidationError('UIProvider', 'renderScreen');
+        }
+        this.provider = provider;
+    }
+    /**
+     * Get the registered UI provider.
+     * @returns The registered UIProvider or null if none registered
+     */
+    getProvider() {
+        return this.provider;
+    }
+    /**
+     * Render a screen using the registered UI provider.
+     * @throws Error if no UI provider is registered
+     * @see Requirements 9.2
+     */
+    renderScreen(screen) {
+        if (this.provider === null) {
+            throw new Error('No UI provider registered');
+        }
+        return this.provider.renderScreen(screen);
+    }
+    /**
+     * Shutdown the UI provider by calling unmount if it exists.
+     * @see Requirements 9.5
+     */
+    async shutdown() {
+        if (this.provider?.unmount) {
+            try {
+                await Promise.resolve(this.provider.unmount());
+                this.logger.debug('UI provider unmounted');
+            }
+            catch (error) {
+                this.logger.error('UI provider unmount failed', error);
+            }
+        }
+        this.provider = null;
+    }
+    /**
+     * Clear the UI provider during shutdown.
+     */
+    clear() {
+        this.provider = null;
+    }
+}
+//# sourceMappingURL=ui-bridge.js.map

package/dist/ui-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-bridge.js","sourceRoot":"","sources":["../src/ui-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwC,eAAe,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE/G;;;;GAIG;AACH,MAAM,OAAO,QAAQ;IACX,QAAQ,GAAsB,IAAI,CAAC;IACnC,MAAM,CAAS;IAEvB,YAAY,MAAc;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,QAAoB;QAC9B,yCAAyC;QACzC,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC3B,MAAM,IAAI,0BAA0B,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAChE,CAAC;QAED,yCAAyC;QACzC,IAAI,OAAO,QAAQ,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACzC,MAAM,IAAI,eAAe,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,OAAO,QAAQ,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;YAChD,MAAM,IAAI,eAAe,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;QAC1D,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,MAAwB;QACnC,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;QAED,OAAO,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ;QACZ,IAAI,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC/C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;YAC7C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAC;YACzD,CAAC;QACH,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "skeleton-crew-runtime",
+  "version": "0.1.1",
+  "description": "A minimal, plugin-based application runtime for building internal tools and modular applications",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "exclude": [
+    "dist-example/"
+  ],
+  "scripts": {
+    "build": "rm -rf dist 2>&1 & tsc",
+    "build:examples": "tsc -p tsconfig.examples.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "example": "npm run build:examples && node dist-example/example/index.js",
+    "example:01": "npm run build:examples && node dist-example/example/01-plugin-system/index.js",
+    "example:02": "npm run build:examples && node dist-example/example/02-screen-registry/index.js",
+    "example:03": "npm run build:examples && node dist-example/example/03-action-engine/index.js",
+    "example:04": "npm run build:examples && node dist-example/example/04-event-bus/index.js",
+    "example:05": "npm run build:examples && node dist-example/example/05-runtime-context/index.js",
+    "tutorial:01": "npm run build:examples && node dist-example/example/tutorial/01-basic-task-plugin/index.js",
+    "tutorial:02": "npm run build:examples && node dist-example/example/tutorial/02-multiple-plugins/index.js",
+    "tutorial:03": "npm run build:examples && node dist-example/example/tutorial/03-event-communication/index.js",
+    "tutorial:04": "npm run build:examples && vite dist-example/example/tutorial/04-ui-provider-swap",
+    "tutorial:05": "npm run build:examples && node dist-example/example/tutorial/05-custom-plugin/index.js"
+  },
+  "keywords": [
+    "runtime",
+    "plugin",
+    "framework",
+    "internal-tools",
+    "modular",
+    "ui-agnostic"
+  ],
+  "author": "skcrew",
+  "email": "skeleton-crew-runtime@gmail.com",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "fast-check": "^3.15.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  },
+  "optionalDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "vite": "^5.0.0"
+  }
+}