Phase 1: Move contracts to spec package and add new interface abstractions

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/core/src/index.ts

@@ -1,8 +1,24 @@
+/**
+ * @objectstack/core
+ * 
+ * Core runtime for ObjectStack microkernel architecture.
+ * Provides plugin system, dependency injection, and lifecycle management.
+ */
+
 export * from './kernel.js';
 export * from './types.js';
-export * from './contracts/http-server.js';
-export * from './contracts/data-engine.js';
-export * from './contracts/logger.js';
 export * from './logger.js';
 export * from './plugin-loader.js';
 export * from './enhanced-kernel.js';
+
+// Re-export contracts from @objectstack/spec for backward compatibility
+export type { 
+    Logger,
+    IHttpServer,
+    IHttpRequest,
+    IHttpResponse,
+    RouteHandler,
+    Middleware,
+    IDataEngine,
+    DriverInterface
+} from '@objectstack/spec/contracts';

packages/core/src/logger.ts

@@ -1,5 +1,5 @@
 import type { LoggerConfig, LogLevel } from '@objectstack/spec/system';
-import type { Logger } from './contracts/logger.js';
+import type { Logger } from '@objectstack/spec/contracts';
 
 /**
  * Universal Logger Implementation

packages/core/src/plugin-loader.ts

@@ -1,5 +1,5 @@
 import { Plugin, PluginContext } from './types.js';
-import type { Logger } from './contracts/logger.js';
+import type { Logger } from '@objectstack/spec/contracts';
 import { z } from 'zod';
 
 /**

packages/core/src/types.ts

@@ -1,5 +1,5 @@
 import { ObjectKernel } from './kernel.js';
-import type { Logger } from './contracts/logger.js';
+import type { Logger } from '@objectstack/spec/contracts';
 
 /**
  * PluginContext - Runtime context available to plugins

packages/spec/package.json

@@ -48,6 +48,10 @@
     "./ui": {
       "types": "./dist/ui/index.d.ts",
       "default": "./dist/ui/index.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts/index.d.ts",
+      "default": "./dist/contracts/index.js"
     }
   },
   "files": [

packages/spec/src/contracts/data-engine.ts

@@ -0,0 +1,73 @@
+import { 
+  DataEngineQueryOptions, 
+  DataEngineInsertOptions, 
+  DataEngineUpdateOptions, 
+  DataEngineDeleteOptions,
+  DataEngineAggregateOptions, 
+  DataEngineCountOptions,
+  DataEngineRequest,
+  QueryAST,
+  DriverOptions
+} from '../data/index.js';
+
+/**
+ * IDataEngine - Standard Data Engine Interface
+ * 
+ * Abstract interface for data persistence capabilities.
+ * Following the Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete database implementations.
+ * 
+ * Aligned with 'src/data/data-engine.zod.ts' in @objectstack/spec.
+ */
+
+export interface IDataEngine {
+  find(objectName: string, query?: DataEngineQueryOptions): Promise<any[]>;
+  findOne(objectName: string, query?: DataEngineQueryOptions): Promise<any>;
+  insert(objectName: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
+  update(objectName: string, data: any, options?: DataEngineUpdateOptions): Promise<any>;
+  delete(objectName: string, options?: DataEngineDeleteOptions): Promise<any>;
+  count(objectName: string, query?: DataEngineCountOptions): Promise<number>;
+  aggregate(objectName: string, query: DataEngineAggregateOptions): Promise<any[]>;
+  
+  /**
+   * Vector Search (AI/RAG)
+   */
+  vectorFind?(objectName: string, vector: number[], options?: { filter?: any, limit?: number, select?: string[], threshold?: number }): Promise<any[]>;
+
+  /**
+   * Batch Operations (Transactional)
+   */
+  batch?(requests: DataEngineRequest[], options?: { transaction?: boolean }): Promise<any[]>;
+
+  /**
+   * Execute raw command (Escape hatch)
+   */
+  execute?(command: any, options?: Record<string, any>): Promise<any>;
+}
+
+export interface DriverInterface {
+  name: string;
+  version: string;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  
+  find(object: string, query: QueryAST, options?: DriverOptions): Promise<any[]>;
+  findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
+  create(object: string, data: any, options?: DriverOptions): Promise<any>;
+  update(object: string, id: any, data: any, options?: DriverOptions): Promise<any>;
+  delete(object: string, id: any, options?: DriverOptions): Promise<any>;
+  
+  /**
+   * Bulk & Batch Operations
+   */
+  bulkCreate?(object: string, data: any[], options?: DriverOptions): Promise<any>;
+  updateMany?(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<any>;
+  deleteMany?(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
+
+  count?(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
+  
+  /**
+   * Raw Execution
+   */
+  execute?(command: any, params?: any, options?: DriverOptions): Promise<any>;
+}

packages/spec/src/contracts/http-server.ts

@@ -0,0 +1,140 @@
+/**
+ * IHttpServer - Standard HTTP Server Interface
+ * 
+ * Abstract interface for HTTP server capabilities.
+ * This allows plugins to interact with HTTP servers without knowing
+ * the underlying implementation (Express, Fastify, Hono, etc.).
+ * 
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete HTTP framework implementations.
+ */
+
+/**
+ * Generic HTTP Request type
+ * Abstraction over framework-specific request objects
+ */
+export interface IHttpRequest {
+    /** Request path parameters */
+    params: Record<string, string>;
+    /** Request query parameters */
+    query: Record<string, string | string[]>;
+    /** Request body */
+    body?: any;
+    /** Request headers */
+    headers: Record<string, string | string[]>;
+    /** HTTP method */
+    method: string;
+    /** Request path */
+    path: string;
+}
+
+/**
+ * Generic HTTP Response type
+ * Abstraction over framework-specific response objects
+ */
+export interface IHttpResponse {
+    /**
+     * Send a JSON response
+     * @param data - Data to send
+     */
+    json(data: any): void | Promise<void>;
+    
+    /**
+     * Send a text/html response
+     * @param data - Data to send
+     */
+    send(data: string): void | Promise<void>;
+    
+    /**
+     * Set HTTP status code
+     * @param code - HTTP status code
+     */
+    status(code: number): IHttpResponse;
+    
+    /**
+     * Set response header
+     * @param name - Header name
+     * @param value - Header value (string or array of strings for multi-value headers)
+     */
+    header(name: string, value: string | string[]): IHttpResponse;
+}
+
+/**
+ * Route handler function
+ */
+export type RouteHandler = (
+    req: IHttpRequest,
+    res: IHttpResponse
+) => void | Promise<void>;
+
+/**
+ * Middleware function
+ */
+export type Middleware = (
+    req: IHttpRequest,
+    res: IHttpResponse,
+    next: () => void | Promise<void>
+) => void | Promise<void>;
+
+/**
+ * IHttpServer - HTTP Server capability interface
+ * 
+ * Defines the contract for HTTP server implementations.
+ * Concrete implementations (Express, Fastify, Hono) should implement this interface.
+ */
+export interface IHttpServer {
+    /**
+     * Register a GET route handler
+     * @param path - Route path (e.g., '/api/users/:id')
+     * @param handler - Route handler function
+     */
+    get(path: string, handler: RouteHandler): void;
+    
+    /**
+     * Register a POST route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    post(path: string, handler: RouteHandler): void;
+    
+    /**
+     * Register a PUT route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    put(path: string, handler: RouteHandler): void;
+    
+    /**
+     * Register a DELETE route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    delete(path: string, handler: RouteHandler): void;
+    
+    /**
+     * Register a PATCH route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    patch(path: string, handler: RouteHandler): void;
+    
+    /**
+     * Register middleware
+     * @param path - Optional path to apply middleware to (if omitted, applies globally)
+     * @param handler - Middleware function
+     */
+    use(path: string | Middleware, handler?: Middleware): void;
+    
+    /**
+     * Start the HTTP server
+     * @param port - Port number to listen on
+     * @returns Promise that resolves when server is ready
+     */
+    listen(port: number): Promise<void>;
+    
+    /**
+     * Stop the HTTP server
+     * @returns Promise that resolves when server is stopped
+     */
+    close?(): Promise<void>;
+}

packages/spec/src/contracts/index.ts

@@ -0,0 +1,14 @@
+/**
+ * ObjectStack Contracts
+ * 
+ * Core interface definitions following "Protocol First" principle.
+ * All interfaces should be defined in @objectstack/spec to avoid circular dependencies.
+ */
+
+export * from './logger.js';
+export * from './data-engine.js';
+export * from './http-server.js';
+export * from './service-registry.js';
+export * from './plugin-validator.js';
+export * from './startup-orchestrator.js';
+export * from './plugin-lifecycle-events.js';

packages/spec/src/contracts/logger.ts

@@ -0,0 +1,70 @@
+/**
+ * Logger Contract
+ * 
+ * Defines the interface for logging in ObjectStack.
+ * Compatible with both browser console and structured logging systems.
+ */
+export interface Logger {
+    /**
+     * Log a debug message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    debug(message: string, meta?: Record<string, any>): void;
+
+    /**
+     * Log an informational message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    info(message: string, meta?: Record<string, any>): void;
+
+    /**
+     * Log a warning message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    warn(message: string, meta?: Record<string, any>): void;
+
+    /**
+     * Log an error message
+     * @param message - The message to log
+     * @param error - Optional error object
+     * @param meta - Optional metadata to include
+     */
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+
+    /**
+     * Log a fatal error message
+     * @param message - The message to log
+     * @param error - Optional error object
+     * @param meta - Optional metadata to include
+     */
+    fatal?(message: string, error?: Error, meta?: Record<string, any>): void;
+
+    /**
+     * Create a child logger with additional context
+     * @param context - Context to add to all logs from this child
+     */
+    child?(context: Record<string, any>): Logger;
+
+    /**
+     * Set trace context for distributed tracing
+     * @param traceId - Trace identifier
+     * @param spanId - Span identifier
+     */
+    withTrace?(traceId: string, spanId?: string): Logger;
+
+    /**
+     * Compatibility method for console.log usage
+     * @param message - The message to log
+     * @param args - Additional arguments
+     */
+    log?(message: string, ...args: any[]): void;
+
+    /**
+     * Cleanup resources (close file streams, etc.)
+     * Should be called when the logger is no longer needed
+     */
+    destroy?(): Promise<void>;
+}