Fix bin/publish: copy docs.dist from project root

Fix bin/publish: use correct .env path for rspade_system
Fix bin/publish script: prevent grep exit code 1 from terminating script

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

app/RSpade/resource/DebugProxy/src/http/auth.ts

@@ -0,0 +1,142 @@
+import * as fs from 'fs/promises';
+import * as crypto from 'crypto';
+import * as path from 'path';
+import { Request, Response, NextFunction } from 'express';
+import { Logger } from '../utils/logger';
+import { Config } from '../utils/config';
+
+interface AuthSession {
+    client_key: string;
+    server_key: string;
+    created_at: number;
+    workspace_path: string;
+}
+
+export class AuthValidator {
+    private logger: Logger;
+    private sessionsCache: Map<string, AuthSession> = new Map();
+
+    constructor() {
+        this.logger = new Logger('AuthValidator');
+    }
+
+    public async validateWebSocketAuth(sessionId: string, signature: string): Promise<boolean> {
+        try {
+            const session = await this.loadSession(sessionId);
+            if (!session) {
+                this.logger.warn(`Session not found: ${sessionId}`);
+                return false;
+            }
+
+            // For WebSocket, we'll validate a simple signature
+            // In production, this should include timestamp and nonce
+            const expectedSignature = crypto
+                .createHmac('sha256', session.server_key)
+                .update(sessionId)
+                .digest('hex');
+
+            return signature === expectedSignature;
+        } catch (error) {
+            this.logger.error('WebSocket auth validation failed:', error);
+            return false;
+        }
+    }
+
+    public authMiddleware() {
+        return async (req: Request, res: Response, next: NextFunction) => {
+            const sessionId = req.headers['x-session-id'] as string;
+            const signature = req.headers['x-auth-signature'] as string;
+            const timestamp = req.headers['x-timestamp'] as string;
+
+            if (!sessionId || !signature || !timestamp) {
+                res.status(401).json({
+                    error: 'Missing authentication headers',
+                    code: 401
+                });
+                return;
+            }
+
+            try {
+                const session = await this.loadSession(sessionId);
+                if (!session) {
+                    res.status(401).json({
+                        error: 'Session not found',
+                        code: 401,
+                        recoverable: true,
+                        recovery: 'Create new session via POST /_ide/service/auth/create'
+                    });
+                    return;
+                }
+
+                // Validate signature
+                const method = req.method;
+                const path = req.path;
+                const body = JSON.stringify(req.body || {});
+
+                const signatureBase = `${method}\n${path}\n${timestamp}\n${body}`;
+                const expectedSignature = crypto
+                    .createHmac('sha256', session.server_key)
+                    .update(signatureBase)
+                    .digest('hex');
+
+                if (signature !== expectedSignature) {
+                    this.logger.warn('Invalid signature for session:', sessionId);
+                    res.status(401).json({
+                        error: 'Invalid signature',
+                        code: 401
+                    });
+                    return;
+                }
+
+                // Check timestamp to prevent replay attacks (5 minute window)
+                const requestTime = parseInt(timestamp, 10);
+                const currentTime = Math.floor(Date.now() / 1000);
+                if (Math.abs(currentTime - requestTime) > 300) {
+                    res.status(401).json({
+                        error: 'Request timestamp expired',
+                        code: 401
+                    });
+                    return;
+                }
+
+                // Attach session to request for use in routes
+                (req as any).session = session;
+                (req as any).sessionId = sessionId;
+                next();
+            } catch (error) {
+                this.logger.error('Auth middleware error:', error);
+                res.status(500).json({
+                    error: 'Authentication error',
+                    code: 500
+                });
+            }
+        };
+    }
+
+    private async loadSession(sessionId: string): Promise<AuthSession | null> {
+        // Check cache first
+        if (this.sessionsCache.has(sessionId)) {
+            return this.sessionsCache.get(sessionId)!;
+        }
+
+        try {
+            const sessionPath = path.join(Config.AUTH_SESSION_PATH, `auth-${sessionId}.json`);
+            const data = await fs.readFile(sessionPath, 'utf8');
+            const session = JSON.parse(data) as AuthSession;
+
+            // Cache the session
+            this.sessionsCache.set(sessionId, session);
+
+            return session;
+        } catch (error) {
+            if ((error as any).code === 'ENOENT') {
+                return null; // Session file doesn't exist
+            }
+            throw error;
+        }
+    }
+
+    public clearCache(): void {
+        this.sessionsCache.clear();
+    }
+}

app/RSpade/resource/DebugProxy/src/http/websocket.ts

@@ -0,0 +1,202 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import * as http from 'http';
+import { Logger } from '../utils/logger';
+import { AuthValidator } from './auth';
+
+export interface WebSocketMessage {
+    type: string;
+    data?: any;
+    timestamp?: number;
+}
+
+export class WebSocketHandler {
+    private wss: WebSocketServer | null = null;
+    private logger: Logger;
+    private clients: Map<string, WebSocket> = new Map();
+    private authValidator: AuthValidator;
+
+    constructor(authValidator: AuthValidator) {
+        this.logger = new Logger('WebSocketHandler');
+        this.authValidator = authValidator;
+    }
+
+    public initialize(server: http.Server): void {
+        this.wss = new WebSocketServer({
+            noServer: true,
+            path: '/_ide/debug/ws'
+        });
+
+        // Handle upgrade requests
+        server.on('upgrade', async (request, socket, head) => {
+            this.logger.info(`WebSocket upgrade request: ${request.url}`);
+
+            // Only handle our specific path
+            if (request.url !== '/_ide/debug/ws') {
+                socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+                socket.destroy();
+                return;
+            }
+
+            // Accept all connections - auth will be done via first message
+            this.wss!.handleUpgrade(request, socket, head, (ws) => {
+                this.wss!.emit('connection', ws, request);
+            });
+        });
+
+        // Handle new connections
+        this.wss.on('connection', (ws: WebSocket, _request: http.IncomingMessage) => {
+            this.logger.info(`WebSocket client connected (awaiting auth)`);
+
+            let sessionId: string | null = null;
+            let authenticated = false;
+
+            // Handle incoming messages
+            ws.on('message', async (data) => {
+                try {
+                    const message = JSON.parse(data.toString()) as WebSocketMessage;
+
+                    // First message must be auth
+                    if (!authenticated) {
+                        if (message.type !== 'auth') {
+                            this.logger.warn('First message was not auth, closing connection');
+                            ws.close(1008, 'Authentication required');
+                            return;
+                        }
+
+                        sessionId = message.data?.sessionId;
+                        const signature = message.data?.signature;
+
+                        if (!sessionId || !signature) {
+                            this.logger.warn('Missing auth credentials');
+                            ws.close(1008, 'Invalid authentication');
+                            return;
+                        }
+
+                        const isValid = await this.authValidator.validateWebSocketAuth(sessionId, signature);
+                        if (!isValid) {
+                            this.logger.warn(`Invalid auth for session: ${sessionId}`);
+                            ws.close(1008, 'Authentication failed');
+                            return;
+                        }
+
+                        authenticated = true;
+                        this.clients.set(sessionId, ws);
+                        this.logger.info(`Client authenticated: ${sessionId}`);
+
+                        // Send welcome message
+                        this.sendMessage(ws, {
+                            type: 'welcome',
+                            data: {
+                                message: 'Authenticated successfully',
+                                sessionId: sessionId,
+                                timestamp: Date.now()
+                            }
+                        });
+                        return;
+                    }
+
+                    // Handle regular messages after auth
+                    this.handleMessage(ws, sessionId!, message);
+                } catch (error) {
+                    this.logger.error('Failed to parse WebSocket message:', error);
+                    this.sendMessage(ws, {
+                        type: 'error',
+                        data: { message: 'Invalid message format' }
+                    });
+                }
+            });
+
+            // Handle pong frames
+            ws.on('pong', () => {
+                if (sessionId) {
+                    this.logger.debug(`Pong received from ${sessionId}`);
+                }
+            });
+
+            // Handle disconnection
+            ws.on('close', () => {
+                if (sessionId) {
+                    this.logger.info(`WebSocket client disconnected: ${sessionId}`);
+                    this.clients.delete(sessionId);
+                }
+            });
+
+            // Handle errors
+            ws.on('error', (error) => {
+                if (sessionId) {
+                    this.logger.error(`WebSocket error for ${sessionId}:`, error);
+                    this.clients.delete(sessionId);
+                }
+            });
+        });
+
+        // Start heartbeat
+        this.startHeartbeat();
+    }
+
+    private handleMessage(ws: WebSocket, sessionId: string, message: WebSocketMessage): void {
+        this.logger.debug(`Message from ${sessionId}: ${message.type}`);
+
+        switch (message.type) {
+            case 'ping':
+                // Respond to ping with pong
+                this.sendMessage(ws, {
+                    type: 'pong',
+                    data: {
+                        originalData: message.data,
+                        timestamp: Date.now()
+                    }
+                });
+                break;
+
+            case 'hello':
+                // Handle hello message
+                this.sendMessage(ws, {
+                    type: 'hello_response',
+                    data: {
+                        message: `Hello ${message.data?.name || 'client'}! Pong from debug proxy`,
+                        timestamp: Date.now()
+                    }
+                });
+                break;
+
+            default:
+                this.logger.warn(`Unknown message type: ${message.type}`);
+                this.sendMessage(ws, {
+                    type: 'error',
+                    data: { message: `Unknown message type: ${message.type}` }
+                });
+        }
+    }
+
+    private sendMessage(ws: WebSocket, message: WebSocketMessage): void {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(message));
+        }
+    }
+
+    private startHeartbeat(): void {
+        setInterval(() => {
+            this.clients.forEach((ws, sessionId) => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.ping();
+                } else {
+                    this.clients.delete(sessionId);
+                }
+            });
+        }, 30000); // 30 second heartbeat
+    }
+
+    public broadcast(message: WebSocketMessage): void {
+        this.clients.forEach((ws) => {
+            this.sendMessage(ws, message);
+        });
+    }
+
+    public sendToSession(sessionId: string, message: WebSocketMessage): void {
+        const ws = this.clients.get(sessionId);
+        if (ws) {
+            this.sendMessage(ws, message);
+        }
+    }
+}

app/RSpade/resource/DebugProxy/src/server.ts

@@ -0,0 +1,151 @@
+import express, { Request, Response } from 'express';
+import * as http from 'http';
+import { Config } from './utils/config';
+import { Logger } from './utils/logger';
+import { WebSocketHandler } from './http/websocket';
+import { AuthValidator } from './http/auth';
+
+class DebugProxyServer {
+    private app: express.Application;
+    private server: http.Server | null = null;
+    private logger: Logger;
+    private isShuttingDown: boolean = false;
+    private wsHandler: WebSocketHandler;
+    private authValidator: AuthValidator;
+
+    constructor() {
+        this.logger = new Logger('DebugProxyServer');
+        this.app = express();
+        this.authValidator = new AuthValidator();
+        this.wsHandler = new WebSocketHandler(this.authValidator);
+        this.setupMiddleware();
+        this.setupRoutes();
+        this.setupShutdownHandlers();
+    }
+
+    private setupMiddleware(): void {
+        // Parse JSON bodies
+        this.app.use(express.json());
+
+        // Request logging
+        this.app.use((req, _res, next) => {
+            this.logger.info(`${req.method} ${req.path}`);
+            next();
+        });
+    }
+
+    private setupRoutes(): void {
+        // Public endpoints (no auth)
+        this.app.get('/_ide/debug/status', (_req: Request, res: Response) => {
+            res.json({
+                status: 'healthy',
+                service: 'rspade-debug-proxy',
+                version: '1.0.0',
+                uptime: process.uptime(),
+                memory: process.memoryUsage()
+            });
+        });
+
+        // Ping endpoint for basic connectivity test
+        this.app.get('/_ide/debug/ping', (_req: Request, res: Response) => {
+            res.json({ pong: true });
+        });
+
+        // Authenticated endpoints
+        this.app.use('/_ide/debug/api', this.authValidator.authMiddleware());
+
+        this.app.post('/_ide/debug/api/test', (req: Request, res: Response) => {
+            const sessionId = (req as any).sessionId;
+            res.json({
+                success: true,
+                message: 'Authenticated successfully',
+                sessionId: sessionId
+            });
+        });
+
+        // 404 handler
+        this.app.use((req: Request, res: Response) => {
+            res.status(404).json({
+                error: 'Not Found',
+                path: req.path
+            });
+        });
+
+        // Error handler
+        this.app.use((err: Error, _req: Request, res: Response, _next: Function) => {
+            this.logger.error('Request error:', err);
+            res.status(500).json({
+                error: 'Internal Server Error',
+                message: err.message
+            });
+        });
+    }
+
+    private setupShutdownHandlers(): void {
+        const shutdown = async (signal: string) => {
+            if (this.isShuttingDown) {
+                return;
+            }
+            this.isShuttingDown = true;
+
+            this.logger.info(`Received ${signal}, starting graceful shutdown...`);
+
+            // Close HTTP server
+            if (this.server) {
+                this.server.close(() => {
+                    this.logger.info('HTTP server closed');
+                });
+            }
+
+            // Give connections time to close
+            setTimeout(() => {
+                this.logger.info('Shutdown complete');
+                process.exit(0);
+            }, 5000);
+        };
+
+        process.on('SIGTERM', () => shutdown('SIGTERM'));
+        process.on('SIGINT', () => shutdown('SIGINT'));
+    }
+
+    public async start(): Promise<void> {
+        const port = Config.HTTP_PORT;
+
+        return new Promise((resolve, reject) => {
+            this.server = this.app.listen(port, () => {
+                this.logger.info(`Debug proxy service started on port ${port}`);
+                this.logger.info(`Status endpoint: http://localhost:${port}/_ide/debug/status`);
+                this.logger.info(`WebSocket endpoint: ws://localhost:${port}/_ide/debug/ws`);
+
+                // Initialize WebSocket handler
+                this.wsHandler.initialize(this.server!);
+                this.logger.info('WebSocket handler initialized');
+
+                resolve();
+            });
+
+            this.server.on('error', (error: Error) => {
+                this.logger.error('Failed to start server:', error);
+                reject(error);
+            });
+        });
+    }
+}
+
+// Main entry point
+async function main() {
+    const server = new DebugProxyServer();
+
+    try {
+        await server.start();
+    } catch (error) {
+        console.error('Failed to start debug proxy:', error);
+        process.exit(1);
+    }
+}
+
+// Start the server
+main().catch(error => {
+    console.error('Uncaught error:', error);
+    process.exit(1);
+});

app/RSpade/resource/DebugProxy/src/utils/config.ts

@@ -0,0 +1,32 @@
+import { LogLevel } from './logger';
+
+export class Config {
+    // HTTP Server
+    public static readonly HTTP_PORT = parseInt(process.env.DEBUG_PROXY_PORT || '9080', 10);
+
+    // DBGp Server
+    public static readonly DBGP_PORT = parseInt(process.env.DBGP_PORT || '9003', 10);
+
+    // Paths
+    public static readonly AUTH_SESSION_PATH = process.env.AUTH_SESSION_PATH || '/var/www/html/storage/rsx-ide-bridge';
+
+    // Logging
+    public static readonly LOG_LEVEL = Config.parseLogLevel(process.env.LOG_LEVEL || 'INFO');
+
+    // Session Management
+    public static readonly SESSION_TIMEOUT_MS = parseInt(process.env.SESSION_TIMEOUT_MS || '3600000', 10); // 1 hour default
+
+    // Server Info
+    public static readonly SERVICE_NAME = 'rspade-debug-proxy';
+    public static readonly SERVICE_VERSION = '1.0.0';
+
+    private static parseLogLevel(level: string): LogLevel {
+        switch (level.toUpperCase()) {
+            case 'ERROR': return LogLevel.ERROR;
+            case 'WARN': return LogLevel.WARN;
+            case 'INFO': return LogLevel.INFO;
+            case 'DEBUG': return LogLevel.DEBUG;
+            default: return LogLevel.INFO;
+        }
+    }
+}

app/RSpade/resource/DebugProxy/src/utils/logger.ts

@@ -0,0 +1,56 @@
+export enum LogLevel {
+    ERROR = 0,
+    WARN = 1,
+    INFO = 2,
+    DEBUG = 3
+}
+
+export class Logger {
+    private context: string;
+    private static logLevel: LogLevel = LogLevel.INFO;
+
+    constructor(context: string) {
+        this.context = context;
+    }
+
+    private log(level: LogLevel, message: string, ...args: any[]): void {
+        if (level > Logger.logLevel) {
+            return;
+        }
+
+        const timestamp = new Date().toISOString();
+        const levelStr = LogLevel[level];
+        const prefix = `[${timestamp}] [${levelStr}] [${this.context}]`;
+
+        switch (level) {
+            case LogLevel.ERROR:
+                console.error(prefix, message, ...args);
+                break;
+            case LogLevel.WARN:
+                console.warn(prefix, message, ...args);
+                break;
+            default:
+                console.log(prefix, message, ...args);
+        }
+    }
+
+    public error(message: string, ...args: any[]): void {
+        this.log(LogLevel.ERROR, message, ...args);
+    }
+
+    public warn(message: string, ...args: any[]): void {
+        this.log(LogLevel.WARN, message, ...args);
+    }
+
+    public info(message: string, ...args: any[]): void {
+        this.log(LogLevel.INFO, message, ...args);
+    }
+
+    public debug(message: string, ...args: any[]): void {
+        this.log(LogLevel.DEBUG, message, ...args);
+    }
+
+    public static setLogLevel(level: LogLevel): void {
+        Logger.logLevel = level;
+    }
+}