paneful 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# Paneful
+
+A browser-based terminal multiplexer. Tmux-style pane management, project workspaces, and a CLI that spawns into a running instance.
+
+## Install
+
+```bash
+npm i -g paneful
+```
+
+Or run without installing:
+
+```bash
+npx paneful
+```
+
+## Usage
+
+### Start the server
+
+```bash
+paneful              # Start server and open browser
+paneful --port 8080  # Use a specific port
+```
+
+### Spawn projects from anywhere
+
+```bash
+cd ~/my-project
+paneful --spawn      # Adds project to running instance
+```
+
+### Manage projects
+
+```bash
+paneful --list              # List all projects
+paneful --kill my-project   # Kill a project by name
+```
+
+## Keyboard Shortcuts
+
+| Shortcut          | Action                          |
+| ----------------- | ------------------------------- |
+| `Cmd+N`           | New pane (vertical split)       |
+| `Cmd+Shift+N`     | New pane (horizontal split)     |
+| `Cmd+W`           | Close focused pane              |
+| `Cmd+1-9`         | Focus pane by index             |
+| `Cmd+Arrow`       | Move focus to adjacent pane     |
+| `Cmd+Shift+Arrow` | Swap focused pane with adjacent |
+| `Cmd+D`           | Toggle sidebar                  |
+| `Cmd+T`           | Cycle through layout presets    |
+| `Cmd+R`           | Auto reorganize panes           |
+
+## Layout Presets
+
+- **Columns** — side by side, equal widths
+- **Rows** — stacked, equal heights
+- **Main + Stack** — 60% left, rest stacked right
+- **Main + Row** — 60% top, rest side by side bottom
+- **Grid** — approximate square grid
+
+## Development
+
+```bash
+npm install && cd web && pnpm install && cd ..
+
+# Dev server (Vite frontend + Node.js backend, hot reload)
+npm run dev
+
+# Production build
+npm run build
+
+# Run locally
+npm start
+```
+
+Vite dev server proxies `/ws` and `/api` to `localhost:3000`. Open `http://localhost:5173` or use Chrome in app mode for full keyboard shortcut support:
+
+```bash
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --app=http://localhost:5173
+```
+
+## Architecture
+
+- **Backend**: Node.js (Express + node-pty + ws)
+- **Frontend**: React + TypeScript + xterm.js + Zustand + Tailwind CSS
+- **Protocol**: JSON over a single WebSocket connection
+- **Distribution**: npm package (`npx paneful`)
+
+## Requirements
+
+- Node.js 18+
+- macOS or Linux

package/dist/server/browser.js

@@ -0,0 +1,61 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+export function openBrowser(port) {
+    const url = `http://localhost:${port}`;
+    console.log(`Opening browser at ${url}`);
+    if (tryChromeAppMode(url))
+        return;
+    // Fallback: open normally
+    console.log('No Chromium-based browser found for app mode, falling back to default browser');
+    import('open').then(({ default: open }) => {
+        open(url).catch((e) => {
+            console.warn('Failed to open browser:', e.message);
+        });
+    });
+    console.error("Tip: Install as a PWA (browser menu > 'Install Paneful') for full keyboard shortcut support");
+}
+function tryChromeAppMode(url) {
+    const appArg = `--app=${url}`;
+    if (process.platform === 'darwin') {
+        const browsers = [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+            '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+            '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+            '/Applications/Arc.app/Contents/MacOS/Arc',
+        ];
+        for (const browser of browsers) {
+            if (fs.existsSync(browser)) {
+                execFile(browser, [appArg], (err) => {
+                    if (err)
+                        console.warn(`Failed to launch ${browser}:`, err.message);
+                });
+                console.log(`Opened in app mode via ${browser}`);
+                return true;
+            }
+        }
+    }
+    else if (process.platform === 'linux') {
+        const browsers = [
+            'google-chrome',
+            'google-chrome-stable',
+            'chromium',
+            'chromium-browser',
+            'microsoft-edge',
+            'brave-browser',
+        ];
+        for (const browser of browsers) {
+            try {
+                execFile(browser, [appArg], (err) => {
+                    if (err) { /* browser not found or failed */ }
+                });
+                console.log(`Opened in app mode via ${browser}`);
+                return true;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return false;
+}

package/dist/server/index.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import express from 'express';
+import { execFile } from 'node:child_process';
+import { v4 as uuidv4 } from 'uuid';
+import { PtyManager } from './pty-manager.js';
+import { ProjectStore } from './project-store.js';
+import { WsHandler } from './ws-handler.js';
+import { startIpcListener, sendIpcCommand } from './ipc.js';
+import { openBrowser } from './browser.js';
+// ── Paths ──
+function dataDir() {
+    const dir = path.join(os.homedir(), '.paneful');
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function lockfilePath() {
+    return path.join(dataDir(), 'paneful.lock');
+}
+function socketPath() {
+    return path.join(dataDir(), 'paneful.sock');
+}
+function readLockfile() {
+    const p = lockfilePath();
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const content = fs.readFileSync(p, 'utf-8');
+        const lines = content.trim().split('\n');
+        if (lines.length < 2)
+            return null;
+        const pid = parseInt(lines[0], 10);
+        const port = parseInt(lines[1], 10);
+        if (isNaN(pid) || isNaN(port))
+            return null;
+        return { pid, port };
+    }
+    catch {
+        return null;
+    }
+}
+function writeLockfile(pid, port) {
+    fs.writeFileSync(lockfilePath(), `${pid}\n${port}`);
+}
+function removeLockfile() {
+    try {
+        fs.unlinkSync(lockfilePath());
+    }
+    catch { /* ok */ }
+    try {
+        fs.unlinkSync(socketPath());
+    }
+    catch { /* ok */ }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── CLI handlers ──
+async function handleSpawn() {
+    const cwd = process.cwd();
+    const name = path.basename(cwd) || 'project';
+    const lock = readLockfile();
+    if (lock && isProcessAlive(lock.pid)) {
+        try {
+            const resp = await sendIpcCommand(socketPath(), { command: 'spawn', cwd, name });
+            if (resp.status === 'ok') {
+                console.log(`Project '${name}' spawned in paneful`);
+            }
+            else {
+                console.error('Error:', resp.message);
+                process.exit(1);
+            }
+        }
+        catch (e) {
+            console.error('Failed to connect:', e.message);
+            process.exit(1);
+        }
+    }
+    else {
+        console.error('Paneful is not running. Start it with: paneful');
+        process.exit(1);
+    }
+}
+async function handleList() {
+    const lock = readLockfile();
+    if (lock && isProcessAlive(lock.pid)) {
+        try {
+            const resp = await sendIpcCommand(socketPath(), { command: 'list' });
+            if (resp.status === 'ok') {
+                const data = resp.data;
+                if (data && data.length > 0) {
+                    console.log(data);
+                }
+                else {
+                    console.log('No projects');
+                }
+            }
+            else {
+                console.error('Error:', resp.message);
+                process.exit(1);
+            }
+        }
+        catch (e) {
+            console.error('Failed to connect:', e.message);
+            process.exit(1);
+        }
+    }
+    else {
+        console.log('Paneful is not running');
+    }
+}
+async function handleKill(name) {
+    const lock = readLockfile();
+    if (lock && isProcessAlive(lock.pid)) {
+        try {
+            const resp = await sendIpcCommand(socketPath(), { command: 'kill', name });
+            if (resp.status === 'ok') {
+                console.log(`Project '${name}' killed`);
+            }
+            else {
+                console.error('Error:', resp.message);
+                process.exit(1);
+            }
+        }
+        catch (e) {
+            console.error('Failed to connect:', e.message);
+            process.exit(1);
+        }
+    }
+    else {
+        console.error('Paneful is not running');
+        process.exit(1);
+    }
+}
+// ── Server ──
+function startServer(devMode, port) {
+    const app = express();
+    app.use(express.json());
+    const ptyManager = new PtyManager();
+    const projectStore = new ProjectStore(dataDir());
+    // API routes
+    app.get('/api/projects', (_req, res) => {
+        res.json(projectStore.list());
+    });
+    app.post('/api/projects', (req, res) => {
+        const { id, name = 'Unnamed', cwd = '/' } = req.body;
+        const projectId = id || uuidv4();
+        const project = { id: projectId, name, cwd, terminal_ids: [] };
+        projectStore.create(project);
+        res.status(201).json(project);
+    });
+    app.delete('/api/projects/:id', (req, res) => {
+        ptyManager.killProject(req.params.id);
+        projectStore.remove(req.params.id);
+        res.status(204).end();
+    });
+    app.post('/api/projects/:id/kill', (req, res) => {
+        const killed = ptyManager.killProject(req.params.id);
+        res.json({ killed: killed.length });
+    });
+    // Resolve a dropped file's full path using OS file index (Spotlight on macOS)
+    app.post('/api/resolve-path', (req, res) => {
+        const { name, size, lastModified } = req.body;
+        if (!name) {
+            res.status(400).json({ error: 'name required' });
+            return;
+        }
+        const findBest = (candidates) => {
+            if (candidates.length === 0)
+                return null;
+            if (candidates.length === 1)
+                return candidates[0];
+            // Score candidates: exact size + mtime match wins, then size-only, then most recent
+            let best = null;
+            for (const candidate of candidates) {
+                try {
+                    const stat = fs.statSync(candidate);
+                    let score = 0;
+                    if (size && stat.size === size)
+                        score += 10;
+                    if (lastModified && Math.abs(stat.mtimeMs - lastModified) < 2000)
+                        score += 5;
+                    // Exclude node_modules and hidden dirs to prefer "real" files
+                    if (!candidate.includes('node_modules') && !candidate.includes('/.'))
+                        score += 1;
+                    if (!best || score > best.score || (score === best.score && stat.mtimeMs > best.mtime)) {
+                        best = { path: candidate, score, mtime: stat.mtimeMs };
+                    }
+                }
+                catch { /* skip inaccessible */ }
+            }
+            return best?.path ?? candidates[0];
+        };
+        if (process.platform === 'darwin') {
+            execFile('mdfind', [`kMDItemFSName == '${name.replace(/'/g, "\\'")}'`], (err, stdout) => {
+                if (err) {
+                    res.json({ path: null });
+                    return;
+                }
+                const candidates = stdout.trim().split('\n').filter(Boolean);
+                res.json({ path: findBest(candidates) });
+            });
+        }
+        else {
+            execFile('locate', ['-l', '20', '-b', `\\${name}`], (err, stdout) => {
+                if (err) {
+                    res.json({ path: null });
+                    return;
+                }
+                const candidates = stdout.trim().split('\n').filter(Boolean);
+                res.json({ path: findBest(candidates) });
+            });
+        }
+    });
+    // Serve static frontend (production only)
+    if (!devMode) {
+        // In production dist: dist/server/index.js -> dist/web/ is sibling
+        const webDir = path.resolve(import.meta.dirname, '..', 'web');
+        if (fs.existsSync(webDir)) {
+            app.use(express.static(webDir));
+            // SPA fallback
+            app.get('*', (_req, res) => {
+                res.sendFile(path.join(webDir, 'index.html'));
+            });
+        }
+    }
+    const server = http.createServer(app);
+    // WebSocket handler
+    const wsHandler = new WsHandler(server, ptyManager, projectStore);
+    // IPC listener
+    const ipcServer = startIpcListener(socketPath(), ptyManager, projectStore, wsHandler);
+    server.listen(port, '127.0.0.1', () => {
+        const addr = server.address();
+        const actualPort = typeof addr === 'object' && addr ? addr.port : port;
+        writeLockfile(process.pid, actualPort);
+        console.log(`Paneful running on http://localhost:${actualPort}`);
+        if (!devMode) {
+            openBrowser(actualPort);
+        }
+    });
+    // Graceful shutdown
+    const shutdown = () => {
+        console.log('Shutting down...');
+        ptyManager.killAll();
+        removeLockfile();
+        ipcServer.close();
+        server.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+// ── CLI ──
+program
+    .name('paneful')
+    .description('Browser-based terminal multiplexer')
+    .option('--spawn', 'Spawn a new project in the current directory')
+    .option('--list', 'List all projects')
+    .option('--kill <name>', 'Kill a project by name')
+    .option('--dev', 'Run in development mode (proxy to Vite dev server)')
+    .option('--port <number>', 'Port to listen on (default: random available)', parseInt)
+    .action(async (opts) => {
+    if (opts.list) {
+        await handleList();
+        return;
+    }
+    if (opts.kill) {
+        await handleKill(opts.kill);
+        return;
+    }
+    if (opts.spawn) {
+        await handleSpawn();
+        return;
+    }
+    // Default: start server (or open browser if already running)
+    const lock = readLockfile();
+    if (lock && isProcessAlive(lock.pid)) {
+        console.log(`Paneful already running on port ${lock.port}`);
+        openBrowser(lock.port);
+        return;
+    }
+    if (lock) {
+        removeLockfile();
+    }
+    startServer(opts.dev || false, opts.port || 0);
+});
+program.parse();

package/dist/server/ipc.js

@@ -0,0 +1,96 @@
+import net from 'node:net';
+import fs from 'node:fs';
+import { v4 as uuidv4 } from 'uuid';
+import { newProject } from './project-store.js';
+export function startIpcListener(socketPath, ptyManager, projectStore, wsHandler) {
+    // Remove stale socket file
+    try {
+        fs.unlinkSync(socketPath);
+    }
+    catch { /* doesn't exist */ }
+    const server = net.createServer((conn) => {
+        let buffer = '';
+        conn.on('data', (chunk) => {
+            buffer += chunk.toString();
+            const newlineIdx = buffer.indexOf('\n');
+            if (newlineIdx === -1)
+                return;
+            const line = buffer.slice(0, newlineIdx).trim();
+            buffer = buffer.slice(newlineIdx + 1);
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                const resp = { status: 'error', message: 'Invalid request' };
+                conn.write(JSON.stringify(resp) + '\n');
+                conn.end();
+                return;
+            }
+            const response = handleIpcRequest(request, ptyManager, projectStore, wsHandler);
+            conn.write(JSON.stringify(response) + '\n');
+            conn.end();
+        });
+        conn.on('error', () => { });
+    });
+    server.listen(socketPath, () => {
+        console.log(`IPC listener started at ${socketPath}`);
+    });
+    return server;
+}
+function handleIpcRequest(request, ptyManager, projectStore, wsHandler) {
+    switch (request.command) {
+        case 'spawn': {
+            const id = uuidv4();
+            const project = newProject(id, request.name, request.cwd);
+            projectStore.create(project);
+            // Notify the frontend
+            wsHandler.send({
+                type: 'project:spawned',
+                projectId: id,
+                name: request.name,
+                cwd: request.cwd,
+            });
+            return { status: 'ok' };
+        }
+        case 'list': {
+            const projects = projectStore.list();
+            const lines = projects.map((p) => `${p.name} (${p.cwd}) - ${p.terminal_ids.length} terminals`);
+            return { status: 'ok', data: lines.join('\n') };
+        }
+        case 'kill': {
+            const project = projectStore.findByName(request.name);
+            if (project) {
+                ptyManager.killProject(project.id);
+                projectStore.remove(project.id);
+                return { status: 'ok' };
+            }
+            return { status: 'error', message: `Project '${request.name}' not found` };
+        }
+    }
+}
+export async function sendIpcCommand(socketPath, request) {
+    return new Promise((resolve, reject) => {
+        const client = net.createConnection(socketPath, () => {
+            client.write(JSON.stringify(request) + '\n');
+        });
+        let buffer = '';
+        client.on('data', (chunk) => {
+            buffer += chunk.toString();
+            const newlineIdx = buffer.indexOf('\n');
+            if (newlineIdx !== -1) {
+                const line = buffer.slice(0, newlineIdx).trim();
+                try {
+                    resolve(JSON.parse(line));
+                }
+                catch {
+                    reject(new Error('Invalid IPC response'));
+                }
+                client.end();
+            }
+        });
+        client.on('error', (err) => {
+            reject(new Error(`Failed to connect to paneful: ${err.message}`));
+        });
+    });
+}

package/dist/server/project-store.js

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export class ProjectStore {
+    projects;
+    filePath;
+    constructor(dataDir) {
+        this.filePath = path.join(dataDir, 'projects.json');
+        this.projects = new Map();
+        if (fs.existsSync(this.filePath)) {
+            try {
+                const contents = fs.readFileSync(this.filePath, 'utf-8');
+                const list = JSON.parse(contents);
+                for (const p of list) {
+                    this.projects.set(p.id, p);
+                }
+            }
+            catch {
+                // Corrupted file, start fresh
+            }
+        }
+    }
+    create(project) {
+        this.projects.set(project.id, project);
+        this.persist();
+    }
+    remove(projectId) {
+        const project = this.projects.get(projectId);
+        if (project) {
+            this.projects.delete(projectId);
+            this.persist();
+        }
+        return project;
+    }
+    get(projectId) {
+        return this.projects.get(projectId);
+    }
+    list() {
+        return Array.from(this.projects.values());
+    }
+    findByName(name) {
+        for (const p of this.projects.values()) {
+            if (p.name === name)
+                return p;
+        }
+        return undefined;
+    }
+    addTerminal(projectId, terminalId) {
+        const project = this.projects.get(projectId);
+        if (project && !project.terminal_ids.includes(terminalId)) {
+            project.terminal_ids.push(terminalId);
+            this.persist();
+        }
+    }
+    removeTerminal(projectId, terminalId) {
+        const project = this.projects.get(projectId);
+        if (project) {
+            project.terminal_ids = project.terminal_ids.filter(id => id !== terminalId);
+            this.persist();
+        }
+    }
+    getTerminalIds(projectId) {
+        return this.projects.get(projectId)?.terminal_ids ?? [];
+    }
+    persist() {
+        const list = Array.from(this.projects.values());
+        try {
+            const dir = path.dirname(this.filePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(this.filePath, JSON.stringify(list, null, 2));
+        }
+        catch {
+            console.error('Failed to persist projects');
+        }
+    }
+}
+export function newProject(id, name, cwd) {
+    return { id, name, cwd, terminal_ids: [] };
+}

package/dist/server/pty-manager.js

@@ -0,0 +1,75 @@
+import * as pty from 'node-pty';
+import os from 'node:os';
+export class PtyManager {
+    sessions = new Map();
+    spawn(terminalId, projectId, cwd, onOutput, onExit) {
+        const shell = process.env.SHELL || (os.platform() === 'win32' ? 'powershell.exe' : '/bin/bash');
+        // Filter out undefined values from process.env before spreading
+        const env = {};
+        for (const [k, v] of Object.entries(process.env)) {
+            if (v !== undefined)
+                env[k] = v;
+        }
+        env.TERM = 'xterm-256color';
+        env.LANG = 'en_US.UTF-8';
+        env.LC_ALL = 'en_US.UTF-8';
+        const proc = pty.spawn(shell, [], {
+            name: 'xterm-256color',
+            cols: 80,
+            rows: 24,
+            cwd,
+            env,
+        });
+        proc.onData((data) => {
+            onOutput(terminalId, data);
+        });
+        proc.onExit(({ exitCode }) => {
+            this.sessions.delete(terminalId);
+            onExit(terminalId, exitCode);
+        });
+        this.sessions.set(terminalId, { process: proc, projectId });
+    }
+    write(terminalId, data) {
+        const managed = this.sessions.get(terminalId);
+        if (managed) {
+            managed.process.write(data);
+        }
+    }
+    resize(terminalId, cols, rows) {
+        const managed = this.sessions.get(terminalId);
+        if (managed) {
+            managed.process.resize(cols, rows);
+        }
+    }
+    kill(terminalId) {
+        const managed = this.sessions.get(terminalId);
+        if (managed) {
+            managed.process.kill();
+            this.sessions.delete(terminalId);
+            return managed.projectId;
+        }
+        return undefined;
+    }
+    killProject(projectId) {
+        const killed = [];
+        for (const [id, managed] of this.sessions) {
+            if (managed.projectId === projectId) {
+                managed.process.kill();
+                killed.push(id);
+            }
+        }
+        for (const id of killed) {
+            this.sessions.delete(id);
+        }
+        return killed;
+    }
+    killAll() {
+        for (const [, managed] of this.sessions) {
+            managed.process.kill();
+        }
+        this.sessions.clear();
+    }
+    terminalExists(terminalId) {
+        return this.sessions.has(terminalId);
+    }
+}