@justscale/core 0.1.0

package/dist/cluster/server.js

@@ -0,0 +1,290 @@
+/**
+ * Cluster server - listens for incoming connections and dispatches protocol messages.
+ * Method handlers are registered by plugins.
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { EventEmitter } from 'node:events';
+import { createServer } from 'node:net';
+import { setInMap } from '../index.js';
+import { Methods, ErrorCodes, createResponse, createErrorResponse, createStream, isRequest, isStream, } from './protocol.js';
+import { SocketTransport, getSocketPath, cleanupSocket, getPeerCredentials, } from './transport.js';
+export class ClusterServer extends EventEmitter {
+    server = null;
+    socketPath;
+    connections = new Set();
+    handlers = new Map();
+    app;
+    /** Pending prompt responses: requestId -> (promptId -> resolver) */
+    pendingPrompts = new Map();
+    /** Maps transport to the set of request IDs it owns */
+    transportRequests = new Map();
+    promptCounter = 0;
+    constructor(options = {}) {
+        super();
+        this.socketPath = options.socketPath ?? getSocketPath(options.appRoot ?? process.cwd());
+        // Register built-in handlers
+        this.registerBuiltinHandlers();
+    }
+    /**
+     * Attach a JustScale app for CLI command execution.
+     */
+    attachApp(app) {
+        this.app = app;
+        return this;
+    }
+    /**
+     * Register a method handler.
+     */
+    handle(method, handler) {
+        this.handlers.set(method, handler);
+        return this;
+    }
+    /**
+     * Start listening for connections.
+     */
+    async listen() {
+        if (this.server) {
+            throw new Error('Server already listening');
+        }
+        // Clean up existing socket
+        cleanupSocket(this.socketPath);
+        return new Promise((resolve, reject) => {
+            this.server = createServer((socket) => {
+                this.handleConnection(socket);
+            });
+            this.server.on('error', (error) => {
+                this.emit('error', error);
+                reject(error);
+            });
+            this.server.listen(this.socketPath, () => {
+                this.emit('listening', this.socketPath);
+                resolve(this.socketPath);
+            });
+        });
+    }
+    /**
+     * Stop the server.
+     */
+    async close() {
+        // Close all connections
+        const closePromises = [...this.connections].map((t) => t.close());
+        await Promise.all(closePromises);
+        this.connections.clear();
+        // Close server
+        if (this.server) {
+            await new Promise((resolve) => {
+                this.server.close(() => resolve());
+            });
+            this.server = null;
+        }
+        // Clean up socket file
+        cleanupSocket(this.socketPath);
+        this.emit('close');
+    }
+    /**
+     * Get the socket path.
+     */
+    get path() {
+        return this.socketPath;
+    }
+    /**
+     * Check if listening.
+     */
+    get listening() {
+        return this.server?.listening ?? false;
+    }
+    handleConnection(socket) {
+        // Get peer credentials for auth
+        const creds = getPeerCredentials(socket);
+        const transport = new SocketTransport({
+            socket,
+            auth: creds ? { type: 'socket', ...creds } : { type: 'socket' },
+        });
+        this.connections.add(transport);
+        this.emit('connection', transport);
+        transport.on('message', (message) => {
+            this.handleMessage(message, transport);
+        });
+        transport.on('error', (error) => {
+            this.emit('error', error);
+        });
+        transport.on('close', () => {
+            this.connections.delete(transport);
+            // Reject all pending prompt resolvers for this transport
+            const requestIds = this.transportRequests.get(transport);
+            if (requestIds) {
+                for (const reqId of requestIds) {
+                    const resolvers = this.pendingPrompts.get(reqId);
+                    if (resolvers) {
+                        for (const [, reject] of resolvers) {
+                            reject({ cancelled: true, value: null });
+                        }
+                        this.pendingPrompts.delete(reqId);
+                    }
+                }
+                this.transportRequests.delete(transport);
+            }
+        });
+    }
+    async handleMessage(message, transport) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (isStream(message) && message.channel === 'prompt_response' && message.id) {
+                const requestPrompts = this.pendingPrompts.get(message.id);
+                if (requestPrompts) {
+                    const data = message.data;
+                    const resolver = requestPrompts.get(data.promptId);
+                    if (resolver) {
+                        resolver(data);
+                        requestPrompts.delete(data.promptId);
+                    }
+                }
+                return;
+            }
+            if (!isRequest(message)) {
+                return;
+            }
+            const { id, method, params } = message;
+            if (!id) {
+                return;
+            }
+            const handler = this.handlers.get(method);
+            if (!handler) {
+                await transport.send(createErrorResponse(id, ErrorCodes.METHOD_NOT_FOUND, `Unknown method: ${method}`));
+                return;
+            }
+            const promptResolvers = new Map();
+            const _ = __addDisposableResource(env_1, setInMap(this.pendingPrompts, id, promptResolvers), false);
+            let reqSet = this.transportRequests.get(transport);
+            if (!reqSet) {
+                reqSet = new Set();
+                this.transportRequests.set(transport, reqSet);
+            }
+            reqSet.add(id);
+            const __ = __addDisposableResource(env_1, {
+                [Symbol.dispose]() {
+                    reqSet.delete(id);
+                },
+            }, false);
+            const context = {
+                transport,
+                app: this.app,
+                server: this,
+                stream: async (channel, data, done) => {
+                    await transport.send(createStream(id, channel, data, done));
+                },
+                prompt: async (type, promptMessage, options) => {
+                    const promptId = `p${++this.promptCounter}`;
+                    // Send prompt request to client
+                    const promptRequest = {
+                        promptId,
+                        promptType: type,
+                        message: promptMessage,
+                        defaultValue: options?.defaultValue,
+                        choices: options?.choices,
+                    };
+                    await transport.send(createStream(id, 'prompt', promptRequest));
+                    // Wait for response using promise
+                    const response = await new Promise((resolve) => {
+                        promptResolvers.set(promptId, resolve);
+                    });
+                    if (response.cancelled) {
+                        return null;
+                    }
+                    return response.value;
+                },
+            };
+            try {
+                const result = await handler(params, context);
+                await transport.send(createResponse(id, result));
+            }
+            catch (error) {
+                const errMessage = error instanceof Error ? error.message : String(error);
+                await transport.send(createErrorResponse(id, ErrorCodes.INTERNAL_ERROR, errMessage));
+            }
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    registerBuiltinHandlers() {
+        this.handle(Methods.SYSTEM_HEALTH, async () => {
+            return {
+                status: 'healthy',
+                uptime: process.uptime(),
+                memory: process.memoryUsage(),
+            };
+        });
+        this.handle(Methods.SYSTEM_INFO, async () => {
+            return {
+                node: process.version,
+                platform: process.platform,
+                arch: process.arch,
+                pid: process.pid,
+                cwd: process.cwd(),
+            };
+        });
+    }
+}
+/**
+ * Create a cluster server.
+ */
+export function createClusterServer(options) {
+    return new ClusterServer(options);
+}
+//# sourceMappingURL=server.js.map

package/dist/cluster/server.js.map

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

package/dist/cluster/transport.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Transport abstraction - unified interface for Unix/TCP socket connections.
+ */
+import { EventEmitter } from 'node:events';
+import type { Socket } from 'node:net';
+import type { Message, AuthInfo, WireFormat } from './protocol.js';
+export interface TransportEvents {
+    message: [message: Message];
+    error: [error: Error];
+    close: [];
+    connect: [];
+}
+/**
+ * Abstract transport interface.
+ * Implementations handle the actual I/O.
+ */
+export interface Transport {
+    /** Send a message */
+    send(message: Message): Promise<void>;
+    /** Close the transport */
+    close(): Promise<void>;
+    /** Check if connected */
+    readonly connected: boolean;
+    /** Authentication info for this connection */
+    readonly auth: AuthInfo;
+    /** Event handlers */
+    on<K extends keyof TransportEvents>(event: K, listener: (...args: TransportEvents[K]) => void): void;
+    off<K extends keyof TransportEvents>(event: K, listener: (...args: TransportEvents[K]) => void): void;
+    once<K extends keyof TransportEvents>(event: K, listener: (...args: TransportEvents[K]) => void): void;
+}
+export interface SocketTransportOptions {
+    /** Socket instance */
+    socket: Socket;
+    /** Auth info (e.g., from SO_PEERCRED) */
+    auth?: AuthInfo;
+    /**
+     * Wire format for outgoing messages.
+     * - WIRE_FORMAT_CBOR (0x00): CBOR encoding (default, backward compatible)
+     * - WIRE_FORMAT_PROTO (0x01): Proto encoding (requires proto codec registered)
+     *
+     * Incoming messages are auto-detected regardless of this setting.
+     * Set to WIRE_FORMAT_PROTO for inter-node cluster communication.
+     * @default WIRE_FORMAT_CBOR
+     */
+    wireFormat?: WireFormat;
+}
+/**
+ * Transport implementation for Node.js sockets (Unix/TCP).
+ */
+export declare class SocketTransport extends EventEmitter implements Transport {
+    private socket;
+    private decoder;
+    private _connected;
+    private _auth;
+    private _wireFormat;
+    constructor(options: SocketTransportOptions);
+    get connected(): boolean;
+    get auth(): AuthInfo;
+    /** The wire format used for outgoing messages */
+    get wireFormat(): WireFormat;
+    send(message: Message): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Get the runtime directory for JustScale sockets.
+ */
+export declare function getSocketDir(): string;
+/**
+ * Generate a socket path for an app.
+ * Uses a hash of the app's root path for uniqueness.
+ */
+export declare function getSocketPath(appRoot: string): string;
+/**
+ * Clean up a socket file if it exists.
+ */
+export declare function cleanupSocket(socketPath: string): void;
+/**
+ * Get peer credentials from a Unix socket (SO_PEERCRED).
+ * Returns null on platforms without SO_PEERCRED or when unavailable.
+ */
+export declare function getPeerCredentials(socket: Socket): {
+    uid: number;
+    gid: number;
+    pid: number;
+} | null;
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/cluster/transport.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGnE,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5B,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACtB,KAAK,EAAE,EAAE,CAAC;IACV,OAAO,EAAE,EAAE,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,qBAAqB;IACrB,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,0BAA0B;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,qBAAqB;IACrB,EAAE,CAAC,CAAC,SAAS,MAAM,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACrG,GAAG,CAAC,CAAC,SAAS,MAAM,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACtG,IAAI,CAAC,CAAC,SAAS,MAAM,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;CACxG;AAED,MAAM,WAAW,sBAAsB;IACrC,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,YAAa,YAAW,SAAS;IACpE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,WAAW,CAAa;gBAEpB,OAAO,EAAE,sBAAsB;IAgC3C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,IAAI,IAAI,QAAQ,CAEnB;IAED,iDAAiD;IACjD,IAAI,UAAU,IAAI,UAAU,CAE3B;IAEK,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB7B;AAMD;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAYrC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAQtD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQnG"}

package/dist/cluster/transport.js

@@ -0,0 +1,138 @@
+/**
+ * Transport abstraction - unified interface for Unix/TCP socket connections.
+ */
+import { EventEmitter } from 'node:events';
+import { FrameDecoder, encodeFrameV2, WIRE_FORMAT_CBOR } from './protocol.js';
+/**
+ * Transport implementation for Node.js sockets (Unix/TCP).
+ */
+export class SocketTransport extends EventEmitter {
+    socket;
+    decoder = new FrameDecoder();
+    _connected = true;
+    _auth;
+    _wireFormat;
+    constructor(options) {
+        super();
+        this.socket = options.socket;
+        this._auth = options.auth ?? { type: 'socket' };
+        this._wireFormat = options.wireFormat ?? WIRE_FORMAT_CBOR;
+        this.socket.on('data', (data) => {
+            try {
+                const messages = this.decoder.push(new Uint8Array(data));
+                for (const message of messages) {
+                    this.emit('message', message);
+                }
+            }
+            catch (error) {
+                this.emit('error', error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        this.socket.on('error', (error) => {
+            this.emit('error', error);
+        });
+        this.socket.on('close', () => {
+            this._connected = false;
+            this.emit('close');
+        });
+        this.socket.on('connect', () => {
+            this._connected = true;
+            this.emit('connect');
+        });
+    }
+    get connected() {
+        return this._connected && !this.socket.destroyed;
+    }
+    get auth() {
+        return this._auth;
+    }
+    /** The wire format used for outgoing messages */
+    get wireFormat() {
+        return this._wireFormat;
+    }
+    async send(message) {
+        if (!this.connected) {
+            throw new Error('Transport not connected');
+        }
+        const frame = encodeFrameV2(message, this._wireFormat);
+        return new Promise((resolve, reject) => {
+            this.socket.write(frame, (error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    }
+    async close() {
+        return new Promise((resolve) => {
+            if (this.socket.destroyed) {
+                resolve();
+                return;
+            }
+            this.socket.once('close', () => resolve());
+            this.socket.end();
+            // Force destroy after timeout
+            setTimeout(() => {
+                if (!this.socket.destroyed) {
+                    this.socket.destroy();
+                }
+                resolve();
+            }, 1000);
+        });
+    }
+}
+import { join } from 'node:path';
+import { existsSync, mkdirSync, unlinkSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+/**
+ * Get the runtime directory for JustScale sockets.
+ */
+export function getSocketDir() {
+    const runtimeDir = process.env.XDG_RUNTIME_DIR;
+    const baseDir = runtimeDir
+        ? join(runtimeDir, 'justscale')
+        : join(process.env.TMPDIR || '/tmp', 'justscale');
+    // Ensure directory exists
+    if (!existsSync(baseDir)) {
+        mkdirSync(baseDir, { recursive: true, mode: 0o700 });
+    }
+    return baseDir;
+}
+/**
+ * Generate a socket path for an app.
+ * Uses a hash of the app's root path for uniqueness.
+ */
+export function getSocketPath(appRoot) {
+    const hash = createHash('sha256').update(appRoot).digest('hex').slice(0, 12);
+    return join(getSocketDir(), `app-${hash}.sock`);
+}
+/**
+ * Clean up a socket file if it exists.
+ */
+export function cleanupSocket(socketPath) {
+    try {
+        if (existsSync(socketPath)) {
+            unlinkSync(socketPath);
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+}
+/**
+ * Get peer credentials from a Unix socket (SO_PEERCRED).
+ * Returns null on platforms without SO_PEERCRED or when unavailable.
+ */
+export function getPeerCredentials(socket) {
+    try {
+        const fd = socket._handle?.fd;
+        if (fd === undefined)
+            return null;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/cluster/transport.js.map

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

package/dist/core/container-hooks.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Container lifecycle hooks - a pub-sub that lets packages react when
+ * the app has finished booting and the DI container is ready to query.
+ *
+ * Scope: process-wide. Hooks fire on every kernel `start()` in the same
+ * process, each with its own container instance.
+ */
+import type { Container } from './service.js';
+export type ContainerReadyHook = (container: Container) => void | Promise<void>;
+/**
+ * Register a hook to run after boot with the kernel's container.
+ * Fires once per `kernel.start()`.
+ */
+export declare function onContainerReady(hook: ContainerReadyHook): void;
+/**
+ * Invoke all registered hooks in registration order.
+ * @internal
+ */
+export declare function runContainerReadyHooks(container: Container): Promise<void>;
+/** @internal Test helper: clear all registered hooks between kernel runs. */
+export declare function __clearContainerReadyHooks(): void;
+//# sourceMappingURL=container-hooks.d.ts.map

package/dist/core/container-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-hooks.d.ts","sourceRoot":"","sources":["../../src/core/container-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,kBAAkB,GAAG,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAIhF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhF;AAED,6EAA6E;AAC7E,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/core/container-hooks.js

@@ -0,0 +1,29 @@
+/**
+ * Container lifecycle hooks - a pub-sub that lets packages react when
+ * the app has finished booting and the DI container is ready to query.
+ *
+ * Scope: process-wide. Hooks fire on every kernel `start()` in the same
+ * process, each with its own container instance.
+ */
+const hooks = [];
+/**
+ * Register a hook to run after boot with the kernel's container.
+ * Fires once per `kernel.start()`.
+ */
+export function onContainerReady(hook) {
+    hooks.push(hook);
+}
+/**
+ * Invoke all registered hooks in registration order.
+ * @internal
+ */
+export async function runContainerReadyHooks(container) {
+    for (const hook of hooks) {
+        await hook(container);
+    }
+}
+/** @internal Test helper: clear all registered hooks between kernel runs. */
+export function __clearContainerReadyHooks() {
+    hooks.length = 0;
+}
+//# sourceMappingURL=container-hooks.js.map

package/dist/core/container-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-hooks.js","sourceRoot":"","sources":["../../src/core/container-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,KAAK,GAAyB,EAAE,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAwB;IACvD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,SAAoB;IAC/D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,0BAA0B;IACxC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACnB,CAAC"}

package/dist/core/container-reflection.d.ts

@@ -0,0 +1,71 @@
+/**
+ * AbstractContainer - queryable reflection of the current scope.
+ *
+ * Inject to introspect what the scope contains (controllers, services).
+ * Each scope binds its own instance; sub-apps each get their own.
+ * Transport-agnostic: protocols filter by reading their own metadata off
+ * each controller instance.
+ */
+import type { ServiceToken } from './service.js';
+import type { ControllerInstance } from './controller.js';
+/**
+ * Filter for `controllers(where?)`.
+ */
+export interface ControllerWhere {
+    /**
+     * If `true`, only include controllers whose routes declare any
+     * `.guard(...)` step. If `false`, only unguarded controllers.
+     * Useful for permission auditors.
+     */
+    readonly hasGuards?: boolean;
+}
+/**
+ * Queryable container reflection. The framework provides the concrete
+ * implementation - users never implement this directly.
+ */
+export interface ContainerReflection {
+    /**
+     * Iterate controllers in this scope, optionally filtered.
+     * Iteration order is insertion order (stable across calls).
+     */
+    controllers(where?: ControllerWhere): Iterable<ControllerInstance>;
+    /**
+     * Resolve a service token in this scope. Returns `undefined` if not bound.
+     */
+    get<T>(token: ServiceToken<T>): Promise<T | undefined>;
+    /**
+     * Resolve every contribution bound to an abstract token in this scope.
+     * Empty array if none bound. Used for the contribution pattern (e.g.
+     * AbstractPrincipalProvider's multiple resolvers).
+     */
+    all<T>(token: ServiceToken<T>): Promise<ReadonlyArray<T>>;
+}
+declare const AbstractContainer_base: import("./service.js").AbstractClass<ContainerReflection>;
+/**
+ * Abstract DI token for scope reflection. Tools inject this:
+ *
+ * @example
+ * ```ts
+ * class ApiDocService extends defineService({
+ *   inject: { container: AbstractContainer },
+ *   factory: ({ container }) => ({
+ *     routes: () => [...container.controllers()],
+ *   }),
+ * }) {}
+ * ```
+ *
+ * Each compiled scope binds its own concrete implementation.
+ */
+export declare abstract class AbstractContainer extends AbstractContainer_base {
+}
+/**
+ * @internal Build a concrete ContainerReflection over a resolved app's
+ * controllers and DI container.
+ */
+export declare function createContainerReflection(args: {
+    readonly controllers: ReadonlyArray<ControllerInstance>;
+    readonly resolve: <T>(token: ServiceToken<T>) => Promise<T | undefined>;
+    readonly resolveAll?: <T>(token: ServiceToken<T>) => Promise<ReadonlyArray<T>>;
+}): ContainerReflection;
+export {};
+//# sourceMappingURL=container-reflection.d.ts.map