@cleocode/lafs 1.8.0

package/dist/src/mviProjection.js

@@ -0,0 +1,116 @@
+/**
+ * Project an envelope to the declared MVI verbosity level.
+ * - 'minimal': Only fields required for agent control flow
+ * - 'standard': All commonly useful fields (current default behavior)
+ * - 'full': Complete echo-back including request parameters
+ * - 'custom': No projection (controlled by _fields)
+ */
+export function projectEnvelope(envelope, mviLevel) {
+    const level = mviLevel ?? envelope._meta.mvi ?? 'standard';
+    switch (level) {
+        case 'minimal':
+            return projectMinimal(envelope);
+        case 'standard':
+            return projectStandard(envelope);
+        case 'full':
+        case 'custom':
+            return envelope;
+    }
+}
+function projectMinimal(env) {
+    const result = {
+        success: env.success,
+        _meta: projectMetaMinimal(env._meta),
+    };
+    if (env.success) {
+        result.result = env.result;
+    }
+    else if (env.error) {
+        result.error = projectErrorMinimal(env.error);
+    }
+    if (env._extensions && Object.keys(env._extensions).length > 0) {
+        result._extensions = env._extensions;
+    }
+    return result;
+}
+function projectStandard(env) {
+    const result = {
+        $schema: env.$schema,
+        success: env.success,
+        _meta: projectMetaStandard(env._meta),
+    };
+    if (env.success) {
+        result.result = env.result;
+    }
+    else {
+        result.result = null;
+        if (env.error) {
+            result.error = env.error;
+        }
+    }
+    if (env.page) {
+        result.page = env.page;
+    }
+    if (env._extensions && Object.keys(env._extensions).length > 0) {
+        result._extensions = env._extensions;
+    }
+    return result;
+}
+function projectMetaMinimal(meta) {
+    const m = meta;
+    const projected = {
+        requestId: m.requestId,
+        contextVersion: m.contextVersion,
+    };
+    if (m.sessionId)
+        projected.sessionId = m.sessionId;
+    if (m.warnings?.length)
+        projected.warnings = m.warnings;
+    if (m._tokenEstimate)
+        projected._tokenEstimate = m._tokenEstimate;
+    return projected;
+}
+function projectMetaStandard(meta) {
+    const m = meta;
+    const projected = {
+        timestamp: m.timestamp,
+        operation: m.operation,
+        requestId: m.requestId,
+        mvi: m.mvi,
+        contextVersion: m.contextVersion,
+    };
+    if (m.sessionId)
+        projected.sessionId = m.sessionId;
+    if (m.warnings?.length)
+        projected.warnings = m.warnings;
+    if (m._tokenEstimate)
+        projected._tokenEstimate = m._tokenEstimate;
+    return projected;
+}
+function projectErrorMinimal(error) {
+    const e = error;
+    const projected = {
+        code: e.code,
+    };
+    if (e.agentAction) {
+        projected.agentAction = e.agentAction;
+    }
+    if (e.retryAfterMs !== null && e.retryAfterMs !== undefined) {
+        projected.retryAfterMs = e.retryAfterMs;
+    }
+    if (e.details && Object.keys(e.details).length > 0) {
+        projected.details = e.details;
+    }
+    if (e.escalationRequired !== undefined) {
+        projected.escalationRequired = e.escalationRequired;
+    }
+    return projected;
+}
+/**
+ * Estimate token count for a projected envelope.
+ * Uses simple heuristic: 1 token per ~4 characters of JSON.
+ */
+export function estimateProjectedTokens(projected) {
+    const json = JSON.stringify(projected);
+    return Math.ceil(json.length / 4);
+}

package/dist/src/problemDetails.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Core RFC 9457 Problem Details bridge.
+ * Converts LAFSError to RFC 9457-compliant Problem Details objects.
+ * Available for any transport, not just HTTP.
+ */
+import type { LAFSError } from './types.js';
+/** RFC 9457 Problem Details with LAFS extensions */
+export interface LafsProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    instance?: string;
+    retryable: boolean;
+    agentAction?: string;
+    retryAfterMs?: number;
+    escalationRequired?: boolean;
+    suggestedAction?: string;
+    docUrl?: string;
+    [key: string]: unknown;
+}
+/**
+ * Convert a LAFSError to an RFC 9457 Problem Details object.
+ * Uses the error registry for HTTP status and type URI resolution.
+ *
+ * Agent-actionable fields (agentAction, escalationRequired, suggestedAction, docUrl)
+ * are extracted from error.details if present, enabling forward-compatible extension
+ * without requiring LAFSError type changes.
+ */
+export declare function lafsErrorToProblemDetails(error: LAFSError, requestId?: string): LafsProblemDetails;
+/**
+ * Content-Type for RFC 9457 Problem Details responses.
+ */
+export declare const PROBLEM_DETAILS_CONTENT_TYPE: "application/problem+json";

package/dist/src/problemDetails.js

@@ -0,0 +1,45 @@
+import { getRegistryCode } from './errorRegistry.js';
+/**
+ * Convert a LAFSError to an RFC 9457 Problem Details object.
+ * Uses the error registry for HTTP status and type URI resolution.
+ *
+ * Agent-actionable fields (agentAction, escalationRequired, suggestedAction, docUrl)
+ * are extracted from error.details if present, enabling forward-compatible extension
+ * without requiring LAFSError type changes.
+ */
+export function lafsErrorToProblemDetails(error, requestId) {
+    const registry = getRegistryCode(error.code);
+    const pd = {
+        type: `https://lafs.dev/errors/v1/${error.code}`,
+        title: error.code,
+        status: registry?.httpStatus ?? 500,
+        detail: error.message,
+        retryable: error.retryable,
+    };
+    if (requestId)
+        pd.instance = requestId;
+    if (error.retryAfterMs != null)
+        pd.retryAfterMs = error.retryAfterMs;
+    // Map top-level agent-actionable fields
+    if (error.agentAction != null)
+        pd.agentAction = error.agentAction;
+    if (error.escalationRequired != null)
+        pd.escalationRequired = error.escalationRequired;
+    if (error.suggestedAction != null)
+        pd.suggestedAction = error.suggestedAction;
+    if (error.docUrl != null)
+        pd.docUrl = error.docUrl;
+    // Spread non-empty details as extension members
+    if (error.details && Object.keys(error.details).length > 0) {
+        for (const [key, value] of Object.entries(error.details)) {
+            if (!(key in pd)) {
+                pd[key] = value;
+            }
+        }
+    }
+    return pd;
+}
+/**
+ * Content-Type for RFC 9457 Problem Details responses.
+ */
+export const PROBLEM_DETAILS_CONTENT_TYPE = 'application/problem+json';

package/dist/src/shutdown/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * LAFS Graceful Shutdown Module
+ *
+ * Handles graceful shutdown of LAFS servers
+ */
+import { Server } from 'http';
+export interface GracefulShutdownConfig {
+    timeout?: number;
+    signals?: NodeJS.Signals[];
+    onShutdown?: () => Promise<void> | void;
+    onClose?: () => Promise<void> | void;
+}
+export interface ShutdownState {
+    isShuttingDown: boolean;
+    activeConnections: number;
+    shutdownStartTime?: Date;
+}
+/**
+ * Enable graceful shutdown for an HTTP server
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { gracefulShutdown } from '@cleocode/lafs/shutdown';
+ *
+ * const app = express();
+ * const server = app.listen(3000);
+ *
+ * gracefulShutdown(server, {
+ *   timeout: 30000,
+ *   signals: ['SIGTERM', 'SIGINT'],
+ *   onShutdown: async () => {
+ *     console.log('Shutting down...');
+ *     await db.close();
+ *   }
+ * });
+ * ```
+ */
+export declare function gracefulShutdown(server: Server, config?: GracefulShutdownConfig): void;
+/**
+ * Check if server is shutting down
+ */
+export declare function isShuttingDown(): boolean;
+/**
+ * Get shutdown state
+ */
+export declare function getShutdownState(): ShutdownState;
+/**
+ * Force immediate shutdown (emergency use only)
+ */
+export declare function forceShutdown(exitCode?: number): void;
+/**
+ * Middleware to reject requests during shutdown
+ *
+ * @example
+ * ```typescript
+ * app.use(shutdownMiddleware());
+ * ```
+ */
+export declare function shutdownMiddleware(): (req: any, res: any, next: any) => void;
+/**
+ * Wait for shutdown to complete
+ *
+ * @example
+ * ```typescript
+ * await waitForShutdown();
+ * ```
+ */
+export declare function waitForShutdown(): Promise<void>;

package/dist/src/shutdown/index.js

@@ -0,0 +1,160 @@
+/**
+ * LAFS Graceful Shutdown Module
+ *
+ * Handles graceful shutdown of LAFS servers
+ */
+const state = {
+    isShuttingDown: false,
+    activeConnections: 0
+};
+/**
+ * Enable graceful shutdown for an HTTP server
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { gracefulShutdown } from '@cleocode/lafs/shutdown';
+ *
+ * const app = express();
+ * const server = app.listen(3000);
+ *
+ * gracefulShutdown(server, {
+ *   timeout: 30000,
+ *   signals: ['SIGTERM', 'SIGINT'],
+ *   onShutdown: async () => {
+ *     console.log('Shutting down...');
+ *     await db.close();
+ *   }
+ * });
+ * ```
+ */
+export function gracefulShutdown(server, config = {}) {
+    const { timeout = 30000, signals = ['SIGTERM', 'SIGINT'], onShutdown, onClose } = config;
+    // Track active connections
+    server.on('connection', (socket) => {
+        if (state.isShuttingDown) {
+            socket.destroy();
+            return;
+        }
+        state.activeConnections++;
+        socket.on('close', () => {
+            state.activeConnections--;
+        });
+    });
+    // Handle shutdown signals
+    signals.forEach((signal) => {
+        process.on(signal, async () => {
+            console.log(`${signal} received, starting graceful shutdown...`);
+            await performShutdown(server, timeout, onShutdown, onClose);
+        });
+    });
+    // Handle uncaught errors
+    process.on('uncaughtException', async (error) => {
+        console.error('Uncaught exception:', error);
+        await performShutdown(server, timeout, onShutdown, onClose);
+    });
+    process.on('unhandledRejection', async (reason) => {
+        console.error('Unhandled rejection:', reason);
+        await performShutdown(server, timeout, onShutdown, onClose);
+    });
+}
+async function performShutdown(server, timeout, onShutdown, onClose) {
+    if (state.isShuttingDown) {
+        console.log('Shutdown already in progress...');
+        return;
+    }
+    state.isShuttingDown = true;
+    state.shutdownStartTime = new Date();
+    try {
+        // Call user shutdown handler
+        if (onShutdown) {
+            await Promise.race([
+                onShutdown(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Shutdown timeout')), timeout))
+            ]);
+        }
+        // Stop accepting new connections
+        server.close((err) => {
+            if (err) {
+                console.error('Error closing server:', err);
+            }
+            else {
+                console.log('Server closed');
+            }
+        });
+        // Wait for active connections to close
+        const startTime = Date.now();
+        while (state.activeConnections > 0 && Date.now() - startTime < timeout) {
+            console.log(`Waiting for ${state.activeConnections} connections to close...`);
+            await sleep(1000);
+        }
+        if (state.activeConnections > 0) {
+            console.warn(`Forcing shutdown with ${state.activeConnections} active connections`);
+        }
+        // Call user close handler
+        if (onClose) {
+            await onClose();
+        }
+        console.log('Graceful shutdown complete');
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Error during shutdown:', error);
+        process.exit(1);
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Check if server is shutting down
+ */
+export function isShuttingDown() {
+    return state.isShuttingDown;
+}
+/**
+ * Get shutdown state
+ */
+export function getShutdownState() {
+    return { ...state };
+}
+/**
+ * Force immediate shutdown (emergency use only)
+ */
+export function forceShutdown(exitCode = 1) {
+    console.log('Force shutting down...');
+    process.exit(exitCode);
+}
+/**
+ * Middleware to reject requests during shutdown
+ *
+ * @example
+ * ```typescript
+ * app.use(shutdownMiddleware());
+ * ```
+ */
+export function shutdownMiddleware() {
+    return (req, res, next) => {
+        if (state.isShuttingDown) {
+            res.status(503).json({
+                error: 'Service is shutting down',
+                status: 'unavailable'
+            });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Wait for shutdown to complete
+ *
+ * @example
+ * ```typescript
+ * await waitForShutdown();
+ * ```
+ */
+export async function waitForShutdown() {
+    while (!state.isShuttingDown) {
+        await sleep(100);
+    }
+}

package/dist/src/tokenEstimator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * LAFS Token Estimator
+ *
+ * Provides character-based token estimation for LAFS envelopes and JSON payloads.
+ * Uses the approximation: 1 token ≈ 4 characters.
+ * Properly handles nested objects, arrays, Unicode graphemes, and circular references.
+ */
+export interface TokenEstimatorOptions {
+    /**
+     * Characters per token ratio (default: 4)
+     */
+    charsPerToken?: number;
+    /**
+     * Maximum depth to traverse for circular reference detection (default: 100)
+     */
+    maxDepth?: number;
+    /**
+     * Maximum string length to process for Unicode grapheme counting (default: 100000)
+     */
+    maxStringLength?: number;
+}
+/**
+ * TokenEstimator provides character-based token counting for JSON payloads.
+ *
+ * Algorithm:
+ * 1. Serialize value to JSON (handling circular refs)
+ * 2. Count Unicode graphemes (not bytes)
+ * 3. Divide by charsPerToken ratio (default 4)
+ * 4. Add overhead for structural characters
+ */
+export declare class TokenEstimator {
+    private options;
+    constructor(options?: TokenEstimatorOptions);
+    /**
+     * Estimate tokens for any JavaScript value.
+     * Handles circular references, nested objects, arrays, and Unicode.
+     *
+     * @param value - Any value to estimate
+     * @returns Estimated token count
+     */
+    estimate(value: unknown): number;
+    /**
+     * Estimate tokens from a JSON string.
+     * More efficient if you already have the JSON string.
+     *
+     * @param json - JSON string to estimate
+     * @returns Estimated token count
+     */
+    estimateJSON(json: string): number;
+    /**
+     * Internal recursive estimation with circular reference tracking.
+     */
+    private estimateWithTracking;
+    /**
+     * Estimate tokens for an array.
+     */
+    private estimateArray;
+    /**
+     * Estimate tokens for a plain object.
+     */
+    private estimateObject;
+    /**
+     * Check if a value can be safely serialized (no circular refs).
+     */
+    canSerialize(value: unknown): boolean;
+    /**
+     * Serialize value to JSON with circular reference handling.
+     * Circular refs are replaced with "[Circular]".
+     */
+    safeStringify(value: unknown): string;
+    /**
+     * Create a safe copy of a value with circular refs removed.
+     */
+    safeCopy<T>(value: T): T;
+}
+/**
+ * Global token estimator instance with default settings.
+ */
+export declare const defaultEstimator: TokenEstimator;
+/**
+ * Convenience function to estimate tokens for a value.
+ */
+export declare function estimateTokens(value: unknown, options?: TokenEstimatorOptions): number;
+/**
+ * Convenience function to estimate tokens from a JSON string.
+ */
+export declare function estimateTokensJSON(json: string, options?: TokenEstimatorOptions): number;