buddy-workbench 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# DevBuddy Workbench
+
+A minimal local workbench. Express serves both the interface and API, and manages local project scripts.
+
+## Run
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+Open `http://localhost:3100`. To use another port, run `PORT=4000 npm start`. Startup attempts to stop any process currently using the selected port.
+
+## UI development
+
+The UI is an independent React + Vite project in `ui/`, built with Ant Design. Run `npm run build` to build it, then run `npm start` to start Express. For UI development, use `npm run dev` in one terminal and `npm run dev:ui` in another; Vite proxies API and plugin requests to Express.
+
+## Plugins
+
+Create a manifest at `plugins/<plugin-name>/plugin.json` to add an item to the sidebar:
+
+```json
+{ "name": "My feature", "icon": "✦", "view": "view.html" }
+```
+
+Plugins are discovered automatically. `view` points to an HTML fragment in the plugin directory. See `plugins/example`; place your HTML, scripts, and styles in an isolated plugin folder. Add API routes as needed for server-side capabilities.
+
+## Scripts and logs
+
+Each service can have multiple named scripts. Run, stop, and view the last 1,000 lines of output for each script from the launcher. Logs are retained in memory until the workbench is restarted and refresh in the browser every second while the log window is open.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "buddy-workbench",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "buddy-workbench": "./server.js"
+  },
+  "files": [
+    "server.js",
+    "server/",
+    "ui/dist/",
+    "plugins/"
+  ],
+  "scripts": {
+    "start": "exec node server.js",
+    "dev": "node --watch server.js",
+    "build": "npm --prefix ui run build",
+    "dev:ui": "npm --prefix ui run dev",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "express": "^5.1.0"
+  }
+}

package/plugins/example/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "Example plugin",
+  "icon": "▦",
+  "view": "view.html"
+}

package/plugins/example/view.html

@@ -0,0 +1,5 @@
+<div class="empty">
+  <div>▦</div>
+  <h2>Example plugin</h2>
+  <p>Replace this file with the HTML view for your feature.</p>
+</div>

package/server/config.js

@@ -0,0 +1,14 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const root = dirname(dirname(fileURLToPath(import.meta.url)));
+export const paths = {
+  launchers: join(root, 'data', 'launchers.json'),
+  portHistory: join(root, 'data', 'port-history.json'),
+  groupTasks: join(root, 'data', 'group-tasks.json'),
+  settings: join(root, 'data', 'settings.json'),
+  shutdownLog: join(root, 'data', 'shutdown.log'),
+  clipboardDir: join(root, 'data', 'clipboard'),
+  plugins: join(root, 'plugins'),
+  ui: join(root, 'ui', 'dist')
+};

package/server/lib/free-port.js

@@ -0,0 +1,27 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function portPids(port) {
+  const { stdout } = await execFileAsync('lsof', ['-ti', `:${port}`]);
+  return [...new Set(stdout.trim().split(/\s+/).filter(Boolean))];
+}
+
+export async function freePort(port) {
+  try {
+    if (process.platform === 'win32') {
+      const { stdout } = await execFileAsync('netstat', ['-ano', '-p', 'tcp']);
+      const pids = [...stdout.matchAll(new RegExp(`:${port}\\s+.*?LISTENING\\s+(\\d+)`, 'g'))].map((match) => match[1]);
+      await Promise.all([...new Set(pids)].map((pid) => execFileAsync('taskkill', ['/F', '/PID', pid])));
+    } else {
+      const pids = await portPids(port);
+      await Promise.all(pids.map((pid) => execFileAsync('kill', ['-TERM', pid])));
+      await wait(1800);
+      await Promise.all((await portPids(port)).map((pid) => execFileAsync('kill', ['-KILL', pid])));
+    }
+  } catch (error) {
+    if (error.code !== 1) console.warn(`Could not fully free port ${port}:`, error.message);
+  }
+}

package/server/repositories/group-tasks.js

@@ -0,0 +1,6 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { paths } from '../config.js';
+
+export function listGroupTasks() { try { return existsSync(paths.groupTasks) ? JSON.parse(readFileSync(paths.groupTasks, 'utf8')) : []; } catch { return []; } }
+export function saveGroupTasks(tasks) { mkdirSync(dirname(paths.groupTasks), { recursive: true }); writeFileSync(paths.groupTasks, JSON.stringify(tasks, null, 2)); }

package/server/repositories/launchers.js

@@ -0,0 +1,19 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { paths } from '../config.js';
+
+function normalize(launcher) {
+  const scripts = launcher.scripts || [{ id: 'default', name: 'Default', command: launcher.command || '', startCommand: true }];
+  const startCommand = typeof launcher.startCommand === 'string' ? launcher.startCommand : scripts.find((script) => script.startCommand)?.name || '';
+  return { ...launcher, groupName: typeof launcher.groupName === 'string' ? launcher.groupName : '', executor: typeof launcher.executor === 'string' && launcher.executor.trim() ? launcher.executor.trim() : 'npm', startCommand, scripts: scripts.map(({ startCommand: _legacyStartCommand, ...script }) => script) };
+}
+
+export function listLaunchers() {
+  if (!existsSync(paths.launchers)) return [];
+  try { return JSON.parse(readFileSync(paths.launchers, 'utf8')).map(normalize); } catch { return []; }
+}
+
+export function saveLaunchers(launchers) {
+  mkdirSync(dirname(paths.launchers), { recursive: true });
+  writeFileSync(paths.launchers, JSON.stringify(launchers, null, 2));
+}

package/server/repositories/port-history.js

@@ -0,0 +1,16 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { paths } from '../config.js';
+
+export function listPortHistory() {
+  if (!existsSync(paths.portHistory)) return [];
+  try {
+    const records = JSON.parse(readFileSync(paths.portHistory, 'utf8'));
+    return Array.isArray(records) ? records.filter((item) => Number.isInteger(item?.port) && item.port > 0 && item.port <= 65535) : [];
+  } catch { return []; }
+}
+
+export function savePortHistory(records) {
+  mkdirSync(dirname(paths.portHistory), { recursive: true });
+  writeFileSync(paths.portHistory, JSON.stringify(records, null, 2));
+}

package/server/repositories/settings.js

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { paths } from '../config.js';
+
+export function readSettings() {
+  if (!existsSync(paths.settings)) return {};
+  try { return JSON.parse(readFileSync(paths.settings, 'utf8')); } catch { return {}; }
+}
+
+export function settingsStatus() {
+  const settings = readSettings();
+  return {
+    domain: typeof settings.domain === 'string' ? settings.domain : '',
+    bitbucketTokenConfigured: Boolean(settings.bitbucketAccessToken),
+    jiraTokenConfigured: Boolean(settings.jiraAccessToken),
+    confluenceTokenConfigured: Boolean(settings.confluenceAccessToken)
+  };
+}
+
+export function saveDomain(domain) {
+  const settings = readSettings();
+  if (domain) settings.domain = domain;
+  else delete settings.domain;
+  mkdirSync(dirname(paths.settings), { recursive: true });
+  writeFileSync(paths.settings, JSON.stringify(settings, null, 2), { mode: 0o600 });
+  return settingsStatus();
+}
+
+const accessTokenFields = {
+  bitbucket: 'bitbucketAccessToken',
+  jira: 'jiraAccessToken',
+  confluence: 'confluenceAccessToken'
+};
+
+export function saveAccessToken(service, token) {
+  const field = accessTokenFields[service];
+  if (!field) throw new Error('Unsupported token service.');
+  const settings = readSettings();
+  if (token) settings[field] = token;
+  else delete settings[field];
+  mkdirSync(dirname(paths.settings), { recursive: true });
+  writeFileSync(paths.settings, JSON.stringify(settings, null, 2), { mode: 0o600 });
+  return settingsStatus();
+}

package/server/routes/clipboard.js

@@ -0,0 +1,8 @@
+import { Router } from 'express';
+import { clipboardDates, clipboardItems, clipboardOriginal, deleteClipboardItem } from '../services/clipboard-history.js';
+
+const router = Router();
+router.get('/', (req, res) => res.json({ dates: clipboardDates(), items: clipboardItems(req.query.date) }));
+router.get('/:date/:id', (req, res) => { const text = clipboardOriginal(req.params.date, req.params.id); if (text === null) return res.status(404).json({ error: 'Clipboard entry not found.' }); res.type('text/plain').send(text); });
+router.delete('/:date/:id', (req, res) => { if (!deleteClipboardItem(req.params.date, req.params.id)) return res.status(404).json({ error: 'Clipboard entry not found.' }); res.status(204).end(); });
+export default router;

package/server/routes/group-tasks.js

@@ -0,0 +1,17 @@
+import { Router } from 'express';
+import { listLaunchers } from '../repositories/launchers.js';
+import { listGroupTasks, saveGroupTasks } from '../repositories/group-tasks.js';
+import { runScript, stopScript } from '../services/process-manager.js';
+import { readPackageScripts } from '../services/package-scripts.js';
+
+const router = Router();
+function validTask(body) { const name = String(body?.name || '').trim(); const items = Array.isArray(body?.items) ? body.items.filter((item) => item?.launcherId && item?.scriptId).map((item) => ({ launcherId: item.launcherId, scriptId: item.scriptId })) : []; return name && items.length ? { name, items } : null; }
+
+router.get('/', (_req, res) => res.json(listGroupTasks()));
+router.get('/catalog', (_req, res) => res.json(listLaunchers().map((launcher) => ({ id: launcher.id, alias: launcher.alias, groupName: launcher.groupName || 'Ungrouped', scripts: [...launcher.scripts.map((script) => ({ id: script.id, name: script.name, source: 'Custom' })), ...readPackageScripts(launcher.folder).map((script) => ({ id: script.id, name: script.name, source: 'Package' }))] }))));
+router.post('/', (req, res) => { const task = validTask(req.body); if (!task) return res.status(400).json({ error: 'A name and at least one script are required.' }); const created = { id: crypto.randomUUID(), ...task }; saveGroupTasks([...listGroupTasks(), created]); res.status(201).json(created); });
+router.put('/:id', (req, res) => { const task = validTask(req.body); if (!task) return res.status(400).json({ error: 'A name and at least one script are required.' }); const tasks = listGroupTasks(); const index = tasks.findIndex((item) => item.id === req.params.id); if (index < 0) return res.status(404).json({ error: 'Group task not found.' }); const updated = { id: req.params.id, ...task }; tasks[index] = updated; saveGroupTasks(tasks); res.json(updated); });
+router.delete('/:id', (req, res) => { const tasks = listGroupTasks(); const next = tasks.filter((item) => item.id !== req.params.id); if (next.length === tasks.length) return res.status(404).json({ error: 'Group task not found.' }); saveGroupTasks(next); res.status(204).end(); });
+router.post('/:id/start', (req, res) => { const task = listGroupTasks().find((item) => item.id === req.params.id); if (!task) return res.status(404).json({ error: 'Group task not found.' }); const launchers = listLaunchers(); const results = task.items.map((item) => { const launcher = launchers.find((entry) => entry.id === item.launcherId); if (!launcher) return { ...item, error: 'Service not found.' }; const custom = launcher.scripts.find((script) => script.id === item.scriptId); const packageScript = custom ? null : readPackageScripts(launcher.folder).find((script) => script.id === item.scriptId); if (!custom && !packageScript) return { ...item, error: 'Script not found.' }; try { runScript(launcher, custom || { ...packageScript, command: `${launcher.executor} run ${packageScript.name}` }); return { ...item, ok: true }; } catch (error) { return { ...item, error: error.message }; } }); res.json({ results }); });
+router.post('/:id/stop', (req, res) => { const task = listGroupTasks().find((item) => item.id === req.params.id); if (!task) return res.status(404).json({ error: 'Group task not found.' }); const results = task.items.map((item) => { try { stopScript(item.launcherId, item.scriptId); return { ...item, ok: true }; } catch (error) { return { ...item, error: error.message }; } }); res.json({ results }); });
+export default router;

package/server/routes/launchers.js

@@ -0,0 +1,47 @@
+import { Router } from 'express';
+import { listLaunchers, saveLaunchers } from '../repositories/launchers.js';
+import { runScript, runningScripts, scriptErrorLogs, scriptLogs, stopScript } from '../services/process-manager.js';
+import { readPackageScripts } from '../services/package-scripts.js';
+import { currentGitBranch } from '../services/git.js';
+
+const router = Router();
+function validLauncher(body) {
+  const { alias, folder, scripts, startCommand, groupName, executor } = body || {};
+  if (![alias, folder].every((value) => typeof value === 'string' && value.trim()) || (scripts !== undefined && !Array.isArray(scripts))) return null;
+  const normalizedScripts = (scripts || []).filter(Boolean).map((script) => ({ id: script.id || crypto.randomUUID(), name: String(script.name || '').trim(), command: String(script.command || '').trim() }));
+  if (normalizedScripts.some((script) => !script.name || !script.command)) return null;
+  const normalizedStartCommand = String(startCommand || '').trim();
+  return { alias: alias.trim(), folder: folder.trim(), groupName: String(groupName || '').trim(), executor: String(executor || 'npm').trim() || 'npm', startCommand: normalizedStartCommand, scripts: normalizedScripts };
+}
+const invalid = (res) => res.status(400).json({ error: 'Name, project folder, and any custom scripts must be complete.' });
+
+router.get('/', async (_req, res) => {
+  const launchers = listLaunchers();
+  const items = await Promise.all(launchers.map(async (launcher) => ({ ...launcher, packageScriptCount: readPackageScripts(launcher.folder).length, branch: await currentGitBranch(launcher.folder) })));
+  res.json(items);
+});
+router.post('/', (req, res) => { const config = validLauncher(req.body); if (!config) return invalid(res); const launcher = { id: crypto.randomUUID(), ...config }; const launchers = listLaunchers(); saveLaunchers([...launchers, launcher]); res.status(201).json(launcher); });
+router.put('/:id', (req, res) => { const config = validLauncher(req.body); if (!config) return invalid(res); const launchers = listLaunchers(); const index = launchers.findIndex((item) => item.id === req.params.id); if (index === -1) return res.status(404).json({ error: 'Configuration not found.' }); const launcher = { id: req.params.id, ...config }; launchers[index] = launcher; saveLaunchers(launchers); res.json(launcher); });
+router.delete('/:id', (req, res) => { const launchers = listLaunchers(); const next = launchers.filter((item) => item.id !== req.params.id); if (next.length === launchers.length) return res.status(404).json({ error: 'Configuration not found.' }); saveLaunchers(next); res.status(204).end(); });
+router.get('/running', (_req, res) => res.json(runningScripts()));
+router.post('/:id/stop', (req, res) => { try { stopScript(req.params.id, req.body?.scriptId); res.json({ ok: true }); } catch (error) { res.status(404).json({ error: error.message }); } });
+router.post('/:id/start', (req, res) => {
+  const launcher = listLaunchers().find((item) => item.id === req.params.id);
+  if (!launcher) return res.status(404).json({ error: 'Configuration not found.' });
+  const customScript = launcher.scripts.find((item) => item.name === launcher.startCommand);
+  const packageScript = customScript ? null : readPackageScripts(launcher.folder).find((item) => item.name === launcher.startCommand);
+  if (!customScript && !packageScript) return res.status(400).json({ error: 'No valid start command is configured.' });
+  try { runScript(launcher, customScript || { ...packageScript, command: `${launcher.executor} run ${packageScript.name}` }); res.json({ ok: true }); }
+  catch (error) { res.status(error.message.includes('already') ? 409 : 400).json({ error: error.message }); }
+});
+router.get('/:id/package-scripts', (req, res) => { const launcher = listLaunchers().find((item) => item.id === req.params.id); if (!launcher) return res.status(404).json({ error: 'Configuration not found.' }); res.json({ scripts: readPackageScripts(launcher.folder) }); });
+router.post('/:id/install/run', (req, res) => { const launcher = listLaunchers().find((item) => item.id === req.params.id); if (!launcher) return res.status(404).json({ error: 'Configuration not found.' }); if (!['npm', 'pnpm', 'yarn'].includes(launcher.executor)) return res.status(400).json({ error: 'Install is only available for npm, pnpm, or yarn.' }); const command = `${launcher.executor} install${launcher.executor === 'npm' ? ' --legacy-peer-deps' : ''}`; try { runScript(launcher, { id: 'install', name: 'Install', command }); res.json({ ok: true }); } catch (error) { res.status(error.message.includes('already') ? 409 : 400).json({ error: error.message }); } });
+router.post('/:id/package-scripts/:scriptName/run', (req, res) => { const launcher = listLaunchers().find((item) => item.id === req.params.id); if (!launcher) return res.status(404).json({ error: 'Configuration not found.' }); const script = readPackageScripts(launcher.folder).find((item) => item.name === req.params.scriptName); if (!script) return res.status(404).json({ error: 'Package script not found.' }); try { runScript(launcher, { ...script, command: `${launcher.executor} run ${script.name}` }); res.json({ ok: true }); } catch (error) { res.status(error.message.includes('already') ? 409 : 400).json({ error: error.message }); } });
+router.get('/:id/package-scripts/:scriptName/logs', (req, res) => { const script = readPackageScripts(listLaunchers().find((item) => item.id === req.params.id)?.folder || '').find((item) => item.name === req.params.scriptName); if (!script) return res.status(404).json({ error: 'Package script not found.' }); res.json({ log: scriptLogs(req.params.id, script.id) }); });
+router.get('/:id/package-scripts/:scriptName/logs/error', (req, res) => { const script = readPackageScripts(listLaunchers().find((item) => item.id === req.params.id)?.folder || '').find((item) => item.name === req.params.scriptName); if (!script) return res.status(404).json({ error: 'Package script not found.' }); res.json({ log: scriptErrorLogs(req.params.id, script.id) }); });
+router.get('/:id/scripts/:scriptId/logs', (req, res) => res.json({ log: scriptLogs(req.params.id, req.params.scriptId) }));
+router.get('/:id/scripts/:scriptId/logs/error', (req, res) => res.json({ log: scriptErrorLogs(req.params.id, req.params.scriptId) }));
+router.post('/:id/scripts/:scriptId/run', (req, res) => { const launcher = listLaunchers().find((item) => item.id === req.params.id); if (!launcher) return res.status(404).json({ error: 'Configuration not found.' }); const script = launcher.scripts.find((item) => item.id === req.params.scriptId); if (!script) return res.status(404).json({ error: 'Script not found.' }); try { runScript(launcher, script); res.json({ ok: true }); } catch (error) { res.status(error.message.includes('already') ? 409 : 400).json({ error: error.message }); } });
+router.post('/:id/scripts/:scriptId/stop', (req, res) => { try { stopScript(req.params.id, req.params.scriptId); res.json({ ok: true }); } catch (error) { res.status(404).json({ error: error.message }); } });
+
+export default router;

package/server/routes/plugins.js

@@ -0,0 +1,6 @@
+import { Router } from 'express';
+import { listPlugins } from '../services/plugins.js';
+
+const router = Router();
+router.get('/', (_req, res) => res.json(listPlugins()));
+export default router;

package/server/routes/port-diagnostics.js

@@ -0,0 +1,25 @@
+import { Router } from 'express';
+import { killPortProcess, portDiagnostics, portProcess } from '../services/process-manager.js';
+
+const router = Router();
+
+router.get('/', async (_req, res) => {
+  try { res.json({ ports: await portDiagnostics() }); }
+  catch (error) { res.status(500).json({ error: error.message }); }
+});
+
+router.get('/:port', async (req, res) => {
+  const port = Number(req.params.port);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return res.status(400).json({ error: 'A valid port is required.' });
+  try { res.json({ process: await portProcess(port) }); }
+  catch (error) { res.status(500).json({ error: error.message }); }
+});
+
+router.post('/kill', async (req, res) => {
+  const port = Number(req.body?.port); const pid = Number(req.body?.pid);
+  if (!Number.isInteger(port) || port < 1 || port > 65535 || !Number.isInteger(pid) || pid < 1) return res.status(400).json({ error: 'A valid port and process ID are required.' });
+  try { await killPortProcess(port, pid); res.json({ ok: true }); }
+  catch (error) { res.status(404).json({ error: error.message }); }
+});
+
+export default router;