@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/ui/streaming.js

@@ -0,0 +1,137 @@
+/**
+ * Streaming Text Display
+ *
+ * Utilities for displaying streaming LLM responses in the terminal
+ */
+import { ui } from '../wizard/ui';
+/**
+ * StreamingDisplay handles real-time text output from LLM responses
+ */
+export class StreamingDisplay {
+    options;
+    buffer = '';
+    lineStarted = false;
+    cursorInterval;
+    constructor(options = {}) {
+        this.options = {
+            prefix: options.prefix || '',
+            prefixColor: options.prefixColor || 'blue',
+            showCursor: options.showCursor ?? true,
+            cursorChar: options.cursorChar || '|',
+        };
+    }
+    /**
+     * Start a new streaming response
+     */
+    start() {
+        this.buffer = '';
+        this.lineStarted = false;
+        // Print the prefix
+        if (this.options.prefix) {
+            ui.write(ui.color(this.options.prefix, this.options.prefixColor));
+        }
+        this.lineStarted = true;
+        // Start cursor blink if enabled
+        if (this.options.showCursor) {
+            this.startCursor();
+        }
+    }
+    /**
+     * Append text to the streaming display
+     */
+    append(text) {
+        // Stop cursor while writing
+        this.stopCursor();
+        // Handle newlines in the text
+        const lines = text.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (i > 0) {
+                // This is after a newline
+                ui.print(''); // End current line
+                this.lineStarted = false;
+            }
+            if (line) {
+                if (!this.lineStarted) {
+                    // Add indentation for continuation lines
+                    ui.write('  '); // Indent to align with prefix
+                    this.lineStarted = true;
+                }
+                ui.write(line);
+            }
+            this.buffer += (i > 0 ? '\n' : '') + line;
+        }
+        // Restart cursor
+        if (this.options.showCursor) {
+            this.startCursor();
+        }
+    }
+    /**
+     * Complete the streaming display
+     */
+    complete() {
+        this.stopCursor();
+        // Ensure we end on a new line
+        if (this.lineStarted) {
+            ui.print('');
+        }
+        return this.buffer;
+    }
+    /**
+     * Handle an error during streaming
+     */
+    error(message) {
+        this.stopCursor();
+        if (this.lineStarted) {
+            ui.print('');
+        }
+        ui.error(message);
+    }
+    startCursor() {
+        if (this.cursorInterval) {
+            return;
+        }
+        let visible = true;
+        this.cursorInterval = setInterval(() => {
+            if (visible) {
+                ui.write(ui.dim(this.options.cursorChar));
+            }
+            else {
+                // Backspace to remove cursor
+                ui.write('\b \b');
+            }
+            visible = !visible;
+        }, 500);
+    }
+    stopCursor() {
+        if (this.cursorInterval) {
+            clearInterval(this.cursorInterval);
+            this.cursorInterval = undefined;
+            // Clear any remaining cursor character
+            ui.write('\b \b');
+        }
+    }
+}
+/**
+ * Simple streaming helper for one-off usage
+ */
+export async function displayStreaming(generator, options = {}) {
+    const display = new StreamingDisplay(options);
+    display.start();
+    try {
+        for await (const chunk of generator) {
+            if (chunk.type === 'content' && chunk.content) {
+                display.append(chunk.content);
+            }
+            else if (chunk.type === 'error') {
+                display.error(chunk.message || 'Unknown error');
+                return '';
+            }
+        }
+        return display.complete();
+    }
+    catch (error) {
+        display.error(error instanceof Error ? error.message : 'Streaming failed');
+        return '';
+    }
+}

package/dist/src/ui/theme.js

@@ -0,0 +1,78 @@
+/**
+ * Theme system for Nimbus TUI.
+ *
+ * Provides named color themes (dark, light) that can be switched at runtime.
+ * Components should import `activeTheme` and use its color properties instead
+ * of hardcoding color strings.
+ *
+ * Theme preference is persisted to ~/.nimbus/config.yaml.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+// ---------------------------------------------------------------------------
+// Built-in themes
+// ---------------------------------------------------------------------------
+export const THEMES = {
+    dark: {
+        name: 'dark',
+        primary: 'cyan',
+        secondary: 'blue',
+        success: 'green',
+        warning: 'yellow',
+        error: 'red',
+        muted: 'gray',
+        border: 'gray',
+    },
+    light: {
+        name: 'light',
+        primary: 'blue',
+        secondary: 'magenta',
+        success: 'green',
+        warning: 'yellow',
+        error: 'red',
+        muted: 'gray',
+        border: 'white',
+    },
+};
+// ---------------------------------------------------------------------------
+// Active theme (mutable singleton)
+// ---------------------------------------------------------------------------
+export let activeTheme = THEMES.dark;
+/**
+ * Switch the active theme by name.
+ * Falls back to `dark` if the name is not recognized.
+ * Persists the chosen theme name to ~/.nimbus/config.yaml.
+ */
+export function setTheme(name) {
+    activeTheme = THEMES[name] ?? THEMES.dark;
+    // Persist to config file
+    try {
+        const configDir = path.join(os.homedir(), '.nimbus');
+        const configFile = path.join(configDir, 'config.yaml');
+        fs.mkdirSync(configDir, { recursive: true });
+        let config = '';
+        try {
+            config = fs.readFileSync(configFile, 'utf-8');
+        }
+        catch {
+            /* new file */
+        }
+        if (config.includes('theme:')) {
+            config = config.replace(/^theme:.*$/m, `theme: ${name}`);
+        }
+        else {
+            config = config ? `${config.trim()}\ntheme: ${name}\n` : `theme: ${name}\n`;
+        }
+        fs.writeFileSync(configFile, config, 'utf-8');
+    }
+    catch {
+        /* ignore FS errors */
+    }
+}
+/**
+ * List all available theme names.
+ */
+export function listThemes() {
+    return Object.keys(THEMES);
+}

package/dist/src/ui/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared types for Nimbus TUI components.
+ *
+ * These interfaces are consumed by every Ink component in the UI layer and by
+ * the orchestration logic that feeds data into the rendering tree.
+ */
+export {};

package/dist/src/utils/analytics.js

@@ -0,0 +1,61 @@
+/**
+ * PostHog Analytics Integration
+ *
+ * Lightweight analytics wrapper that sends events to PostHog.
+ * Operates as a complete no-op when POSTHOG_API_KEY is not set.
+ */
+export class Analytics {
+    apiKey;
+    host;
+    constructor() {
+        this.apiKey = process.env.POSTHOG_API_KEY;
+        this.host = process.env.POSTHOG_HOST || 'https://app.posthog.com';
+    }
+    get enabled() {
+        return !!this.apiKey;
+    }
+    async trackEvent(event, properties) {
+        if (!this.enabled) {
+            return;
+        }
+        try {
+            await fetch(`${this.host}/capture/`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    api_key: this.apiKey,
+                    event,
+                    properties: {
+                        ...properties,
+                        timestamp: new Date().toISOString(),
+                    },
+                    distinct_id: properties?.userId || 'anonymous',
+                }),
+            });
+        }
+        catch {
+            // Fire-and-forget -- never throw from analytics
+        }
+    }
+    async identifyUser(userId, properties) {
+        if (!this.enabled) {
+            return;
+        }
+        try {
+            await fetch(`${this.host}/capture/`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    api_key: this.apiKey,
+                    event: '$identify',
+                    distinct_id: userId,
+                    properties,
+                }),
+            });
+        }
+        catch {
+            // Fire-and-forget
+        }
+    }
+}
+export const analytics = new Analytics();

package/dist/src/utils/cost-warning.js

@@ -0,0 +1,25 @@
+/**
+ * Cost Warning Utility
+ *
+ * Shows informational cost warnings before destructive operations.
+ * Best-effort: silently skips on any failure.
+ */
+import { ui } from '../wizard/ui';
+import { CostEstimator } from '../commands/cost/estimator';
+/**
+ * Show an informational cost warning before a destructive operation.
+ * Calls CostEstimator.estimateDirectory() and displays the estimated
+ * monthly cost impact as a negative value (savings from destroying).
+ * Wrapped in try/catch — never throws.
+ */
+export async function showDestructionCostWarning(directory) {
+    try {
+        const estimate = await CostEstimator.estimateDirectory(directory);
+        if (estimate.totalMonthlyCost > 0) {
+            ui.warning(`Estimated monthly cost impact: -$${estimate.totalMonthlyCost.toFixed(2)}/month`);
+        }
+    }
+    catch {
+        // Best-effort — silently skip if estimation fails
+    }
+}

package/dist/src/utils/env.js

@@ -0,0 +1,42 @@
+import { ConfigurationError } from './errors';
+export function getEnv(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined) {
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+        throw new ConfigurationError(`Environment variable ${key} is required but not set`, 'nimbus', {
+            key,
+        });
+    }
+    return value;
+}
+export function getEnvOptional(key) {
+    return process.env[key];
+}
+export function getEnvNumber(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined) {
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+        throw new ConfigurationError(`Environment variable ${key} is required but not set`, 'nimbus', {
+            key,
+        });
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        throw new ConfigurationError(`Environment variable ${key} must be a valid number`, 'nimbus', {
+            key,
+            value,
+        });
+    }
+    return parsed;
+}
+export function getEnvBoolean(key, defaultValue = false) {
+    const value = process.env[key];
+    if (value === undefined) {
+        return defaultValue;
+    }
+    return value.toLowerCase() === 'true' || value === '1';
+}

package/dist/src/utils/errors.js

@@ -0,0 +1,54 @@
+/**
+ * Base Nimbus Error
+ */
+export class NimbusError extends Error {
+    code;
+    service;
+    timestamp;
+    details;
+    constructor(message, code, service, details) {
+        super(message);
+        this.name = 'NimbusError';
+        this.code = code;
+        this.service = service;
+        this.timestamp = new Date().toISOString();
+        this.details = details;
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            service: this.service,
+            timestamp: this.timestamp,
+            details: this.details,
+            stack: this.stack,
+        };
+    }
+}
+export class ValidationError extends NimbusError {
+    constructor(message, service, details) {
+        super(message, 'VALIDATION_ERROR', service, details);
+        this.name = 'ValidationError';
+    }
+}
+export class ServiceUnavailableError extends NimbusError {
+    constructor(serviceName, details) {
+        super(`Service ${serviceName} is unavailable`, 'SERVICE_UNAVAILABLE', 'nimbus', details);
+        this.name = 'ServiceUnavailableError';
+    }
+}
+export class TimeoutError extends NimbusError {
+    constructor(operation, service, timeoutMs) {
+        super(`Operation ${operation} timed out after ${timeoutMs}ms`, 'TIMEOUT_ERROR', service, {
+            operation,
+            timeoutMs,
+        });
+        this.name = 'TimeoutError';
+    }
+}
+export class ConfigurationError extends NimbusError {
+    constructor(message, service, details) {
+        super(message, 'CONFIGURATION_ERROR', service, details);
+        this.name = 'ConfigurationError';
+    }
+}

package/dist/src/utils/event-bus.js

@@ -0,0 +1,22 @@
+import { EventEmitter } from 'node:events';
+class NimbusEventBus {
+    emitter = new EventEmitter();
+    constructor() {
+        this.emitter.setMaxListeners(50);
+    }
+    publish(event) {
+        this.emitter.emit(event.type, event);
+        this.emitter.emit('*', event);
+    }
+    subscribe(eventType, handler) {
+        this.emitter.on(eventType, handler);
+        return () => this.emitter.off(eventType, handler);
+    }
+    once(eventType, handler) {
+        this.emitter.once(eventType, handler);
+    }
+    removeAllListeners(eventType) {
+        this.emitter.removeAllListeners(eventType);
+    }
+}
+export const eventBus = new NimbusEventBus();

package/dist/src/utils/index.js

@@ -0,0 +1,16 @@
+// Logger
+export { logger, Logger } from './logger';
+// Errors
+export * from './errors';
+// Validation
+export * from './validation';
+// Environment helpers
+export * from './env';
+// Service authentication
+export * from './service-auth';
+// Rate limiting
+export * from './rate-limiter';
+// Event bus
+export * from './event-bus';
+// Analytics (PostHog)
+export * from './analytics';

package/dist/src/utils/logger.js

@@ -0,0 +1,150 @@
+const SENSITIVE_KEYS = new Set([
+    'password',
+    'passwordhash',
+    'password_hash',
+    'secret',
+    'secretkey',
+    'secret_key',
+    'clientsecret',
+    'client_secret',
+    'token',
+    'apikey',
+    'api_key',
+    'api-key',
+    'authorization',
+    'credentials',
+    'credential',
+    'accesstoken',
+    'access_token',
+    'refreshtoken',
+    'refresh_token',
+    'privatekey',
+    'private_key',
+    'signingkey',
+    'signing_key',
+    'encryptionkey',
+    'encryption_key',
+    'bearer',
+    'auth',
+    'authtoken',
+    'auth_token',
+    'sessiontoken',
+    'session_token',
+    'jwt',
+    'jwttoken',
+    'jwt_token',
+]);
+const REDACTED = '[REDACTED]';
+function sanitize(value, seen = new WeakSet()) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    if (typeof value !== 'object') {
+        return value;
+    }
+    const obj = value;
+    if (seen.has(obj)) {
+        return '[Circular]';
+    }
+    seen.add(obj);
+    if (obj instanceof Date) {
+        return obj.toISOString();
+    }
+    if (obj instanceof Map) {
+        return sanitize(Object.fromEntries(obj), seen);
+    }
+    if (obj instanceof Set) {
+        return sanitize([...obj], seen);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(item => sanitize(item, seen));
+    }
+    const sanitized = {};
+    for (const key of Object.keys(obj)) {
+        if (SENSITIVE_KEYS.has(key.toLowerCase())) {
+            sanitized[key] = REDACTED;
+        }
+        else {
+            sanitized[key] = sanitize(obj[key], seen);
+        }
+    }
+    return sanitized;
+}
+// Patterns to redact in error messages/stacks (connection strings, URLs with creds, etc.)
+const SENSITIVE_PATTERNS = [
+    /(?<=:\/\/[^:]+:)[^@]+(?=@)/g, // URL password: protocol://user:PASSWORD@host
+    /(?<=password[=:])\s*\S+/gi, // password=VALUE or password: VALUE
+    /(?<=secret[=:])\s*\S+/gi, // secret=VALUE or secret: VALUE
+    /(?<=token[=:])\s*\S+/gi, // token=VALUE or token: VALUE
+    /(?<=apikey[=:])\s*\S+/gi, // apiKey=VALUE or apikey: VALUE
+    /(?<=authorization[=:])\s*\S+/gi, // authorization=VALUE
+];
+function sanitizeString(str) {
+    let result = str;
+    for (const pattern of SENSITIVE_PATTERNS) {
+        result = result.replace(pattern, REDACTED);
+    }
+    return result;
+}
+function safeContext(context) {
+    if (context instanceof Error) {
+        const errorText = context.stack ?? context.message;
+        return sanitizeString(errorText);
+    }
+    return JSON.stringify(sanitize(context));
+}
+/**
+ * Simple logger implementation
+ */
+class Logger {
+    level;
+    levels = ['debug', 'info', 'warn', 'error'];
+    constructor(level = 'info') {
+        this.level = level;
+    }
+    shouldLog(level) {
+        return this.levels.indexOf(level) >= this.levels.indexOf(this.level);
+    }
+    debug(message, context) {
+        if (this.shouldLog('debug')) {
+            const line = this.format('debug', message, context);
+            console.log(line);
+        }
+    }
+    info(message, context) {
+        if (this.shouldLog('info')) {
+            const line = this.format('info', message, context);
+            console.log(line);
+        }
+    }
+    warn(message, context) {
+        if (this.shouldLog('warn')) {
+            const line = this.format('warn', message, context);
+            console.warn(line);
+        }
+    }
+    error(message, context) {
+        if (this.shouldLog('error')) {
+            const line = this.format('error', message, context);
+            console.error(line);
+        }
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    format(level, message, context) {
+        const timestamp = new Date().toISOString();
+        const levelStr = level.toUpperCase().padEnd(5);
+        if (context === undefined) {
+            return `[${timestamp}] [${levelStr}] ${message}`;
+        }
+        return `[${timestamp}] [${levelStr}] ${message} ${safeContext(context)}`;
+    }
+}
+// Export singleton instance
+export const logger = new Logger(process.env.LOG_LEVEL || 'info');
+// Export Logger class for testing
+export { Logger };

package/dist/src/utils/rate-limiter.js

@@ -0,0 +1,90 @@
+import { logger } from './logger';
+export class SimpleRateLimiter {
+    requestsPerMinute;
+    burstSize;
+    buckets;
+    cleanupInterval;
+    constructor(options) {
+        this.requestsPerMinute = options.requestsPerMinute;
+        this.burstSize = options.burstSize || options.requestsPerMinute;
+        this.buckets = new Map();
+        this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+        if (this.cleanupInterval &&
+            typeof this.cleanupInterval === 'object' &&
+            'unref' in this.cleanupInterval) {
+            this.cleanupInterval.unref();
+        }
+    }
+    tryAcquire(clientId = 'default') {
+        const now = Date.now();
+        let bucket = this.buckets.get(clientId);
+        if (!bucket) {
+            bucket = { tokens: this.burstSize, lastRefill: now };
+            this.buckets.set(clientId, bucket);
+        }
+        const elapsed = now - bucket.lastRefill;
+        const refill = (elapsed / 60_000) * this.requestsPerMinute;
+        bucket.tokens = Math.min(this.burstSize, bucket.tokens + refill);
+        bucket.lastRefill = now;
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            return true;
+        }
+        return false;
+    }
+    getRemainingRequests(clientId = 'default') {
+        const bucket = this.buckets.get(clientId);
+        if (!bucket) {
+            return this.burstSize;
+        }
+        const elapsed = Date.now() - bucket.lastRefill;
+        const refill = (elapsed / 60_000) * this.requestsPerMinute;
+        return Math.min(this.burstSize, Math.floor(bucket.tokens + refill));
+    }
+    cleanup() {
+        const cutoff = Date.now() - 120_000;
+        for (const [clientId, bucket] of this.buckets) {
+            if (bucket.lastRefill < cutoff) {
+                this.buckets.delete(clientId);
+            }
+        }
+    }
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+}
+function getClientIp(req) {
+    const forwarded = req.headers.get('x-forwarded-for');
+    if (forwarded) {
+        return forwarded.split(',')[0].trim();
+    }
+    const realIp = req.headers.get('x-real-ip');
+    if (realIp) {
+        return realIp;
+    }
+    return 'unknown';
+}
+export function rateLimitMiddleware(limiter) {
+    return (req) => {
+        const url = new URL(req.url);
+        if (url.pathname === '/health') {
+            return null;
+        }
+        const clientIp = getClientIp(req);
+        if (!limiter.tryAcquire(clientIp)) {
+            logger.warn(`Rate limited client ${clientIp} on ${url.pathname}`);
+            const retryAfter = Math.ceil(60 / limiter.getRemainingRequests(clientIp) || 60);
+            return new Response(JSON.stringify({ success: false, error: 'Too Many Requests' }), {
+                status: 429,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Retry-After': String(retryAfter),
+                },
+            });
+        }
+        return null;
+    };
+}