server-studio 1.0.0 → 1.1.0

package/README.md

@@ -1,20 +1,48 @@
 # Server Studio
 
-A small dashboard for the local dev servers you actually run. Every project gets a card with
-its run command, folder and URL, so starting one is a click instead of a hunt through terminal
-history. It also keeps one permanent port per project, so a saved entry never goes stale.
+[![test](https://github.com/mehdi214designer/server-studio/actions/workflows/test.yml/badge.svg)](https://github.com/mehdi214designer/server-studio/actions/workflows/test.yml)
+[![npm](https://img.shields.io/npm/v/server-studio)](https://www.npmjs.com/package/server-studio)
+
+A small dashboard for the local dev servers you actually run.
+
+If you work on more than three or four projects, you know the routine. You want to show someone the
+staging build, and first you have to remember which folder it lives in, then whether it starts with
+`npm run dev` or `yarn start` or `php -S`, then which port it landed on last time, then why that port
+is now busy because something else grabbed it a week ago.
+
+Server Studio gives every project a card holding its folder, its run command and its URL. Click
+**Run** and it opens a real terminal window in the right directory with the right command. Click the
+URL and the browser opens. The card also shows a live dot for whether that port is currently up, so
+you can see what is running without checking.
+
+The other half is the port rule: each project keeps one permanent port that nothing else is allowed
+to take. A saved card is worthless if the port drifts, so the app hands out a unique one and you bake
+it into the project config. Six months later the card still works.
 
 Node.js is the only requirement. No npm install inside the app, no Electron, no background daemon.
 
+![Server Studio](https://raw.githubusercontent.com/mehdi214designer/server-studio/main/docs/screenshot.png)
+
 ## Install
 
-**macOS**
+```bash
+npm install -g server-studio
+```
+
+That is the whole thing. A global install sets up the app and the skill for you.
+
+If you would rather not install globally, this does the same without leaving anything behind:
 
 ```bash
 npx server-studio install
 ```
 
-That copies the app to `/Applications` and installs the Claude Code skill. Then open it from
+Installing this as a project dependency deliberately does **not** set anything up, since that would
+write outside the package on a machine that only wanted the library.
+
+**macOS**
+
+`install` copies the app to `/Applications` and installs the Claude Code skill. Then open it from
 Applications, or:
 
 ```bash
@@ -29,7 +57,7 @@ There is no app bundle to install, so run the dashboard directly:
 npx server-studio start
 ```
 
-It serves the same dashboard at `http://localhost:4587` and opens your browser. Add
+It serves the same dashboard at `http://localhost:4587` and opens your browser. Run
 `npx server-studio install --no-app` first if you also want the Claude Code skill.
 
 To remove it again:
@@ -47,16 +75,119 @@ Your saved servers are kept. Add `--purge` if you want those deleted too.
 | `--dry-run` | Print what would happen, change nothing |
 | `--purge` | Uninstall only: also delete your saved server list |
 
+## Using it
+
+### Add your first server
+
+Click **Add server**. Only the name matters, everything else can be filled in later.
+
+| Field | What it does | Example |
+|---|---|---|
+| Name | Card title, and what you search by | `Acme Dashboard` |
+| Project | A line of context for future you | `Client analytics UI` |
+| Category | Groups cards into filter tabs along the top | `Web app` |
+| Project folder | Where the run command executes. **Browse** opens a folder picker | `~/Sites/acme` |
+| Run command | Exactly what you would type to start it | `npm run dev` |
+| URL / Address | Where it serves. A bare port works and becomes `localhost:PORT` | `5181` |
+| Tag | Small label on the card, usually the stack | `Next.js` |
+| Notes | Anything you will forget | `Seed data resets on restart` |
+
+### Run, stop, open
+
+Each card has five controls:
+
+| Control | What happens |
+|---|---|
+| **Run** | Opens a terminal window, `cd`s into the folder, runs the command. Real terminal, so you see the output and can Ctrl-C it |
+| Open in browser | Opens the card's URL |
+| Stop | Kills whatever process is holding that port. Useful when something is stuck |
+| Edit | Change any field |
+| Delete | Removes the card. Does not touch the project itself |
+
+The icon inside the URL box copies the address to your clipboard.
+
+The dot next to the URL is live status: green means that port is currently accepting connections,
+red means nothing is there. It re-checks every 12 seconds, and **Refresh status** forces it.
+
+Click the star to pin a card to the top. The search box matches name, project, URL, command, tag,
+category and notes at once, so searching `wordpress` or `5181` or `vite` all find the right card.
+
+### The one permanent port rule
+
+This is the part that makes saved cards stay useful, and it needs one step from you.
+
+When you add a project, give it a port nothing else uses, then **force the dev server to always use
+that exact port**. Most tools will silently pick a different one if the port is busy, which is what
+makes a saved entry go stale. Use the strict option so it fails loudly instead:
+
+| Tool | How to pin the port |
+|---|---|
+| Vite | `server: { port: 5181, strictPort: true }` in `vite.config`, or `vite --port 5181 --strictPort` |
+| Next.js | `next dev -p 5181` |
+| Astro | `astro dev --port 5181` |
+| create-react-app | `PORT=5181 react-scripts start` |
+| Express / plain Node | `process.env.PORT || 5181` |
+| PHP | `php -S localhost:5181` |
+
+Then put that same port in both the run command and the URL on the card.
+
+### Let Claude do it for you
+
+If you installed the skill, you never have to add cards by hand. Ask Claude Code to build something
+with a dev server and it registers the project itself, picks a port no other project is using, and
+writes that port into the config with the strict flag set.
+
+You can also just ask:
+
+> save this server to Server Studio
+
+To do it manually, or from a script:
+
+```bash
+node ~/.claude/skills/server-studio/register-server.js \
+  --name "Acme Dashboard" \
+  --cwd "$PWD" \
+  --command "npm run dev" \
+  --assign
+```
+
+`--assign` picks a free port and prints it, so you know what to write into the config. Re-running it
+for a project that already exists updates the other fields but keeps the port locked, which is the
+whole point.
+
+### Using it from any editor or script
+
+The Claude skill is a convenience wrapper, not the mechanism. Registering a server is a plain
+command with no AI involved, so any tool that can run a shell command can use it. That includes
+Cursor, Copilot, Windsurf, a Makefile, a shell alias, or you:
+
+```bash
+server-studio add --name "Portfolio Site" --cwd "$PWD" --command "npm run dev" --assign
+```
+
+`--assign` picks a port nothing else uses and prints `PORT <n>`, so a script can read that line and
+write the port into the project config. Re-running for the same project updates its fields and keeps
+its port locked, which is what makes this safe to call from a build step.
+
+Run `server-studio add` with no arguments for the full list of fields.
+
+### Backups
+
+**Export** saves your whole list to `server-studio-backup.json`. **Import** loads one back.
+
+Note that Import **replaces** your entire list rather than merging into it, so export first if you
+have anything you care about.
+
 ## What's in the box
 
-**The app.** A local dashboard at `127.0.0.1:4587`. Run a server (it opens in a real terminal
-window), stop it, open its URL, reveal its folder, and see at a glance which ports are live.
+**The app**, a dashboard served at `127.0.0.1:4587`.
 
-**The Claude Code skill.** Ask Claude to build you something with a dev server and it registers the
-server for you, picking a free port and baking it into the project config so the port never drifts.
+**The Claude Code skill**, so Claude can register servers for you. It wraps
+`server-studio add`, which works on its own from any tool.
 
-**The Cowork plugin.** The same skill as a `/server-studio` command. Build it with
-`npm run build:plugin`, then open `dist/server-studio.plugin`.
+**The Cowork plugin**, the same skill as a `/server-studio` command. The installer copies it next to
+your data file and prints the path, then you open that file to install it. To rebuild it from source,
+run `npm run build:plugin`.
 
 ## Platform support
 
@@ -68,8 +199,16 @@ server for you, picking a free port and baking it into the project config so the
 | Stop a port | `lsof` + `kill` | `netstat` + `taskkill` | `lsof` + `kill` |
 | Browse for a folder | native dialog | native dialog | needs `zenity`, otherwise type the path |
 
-Windows and Linux support is written but has only been exercised on macOS, so treat the first run
-on those platforms as unproven. Bug reports welcome.
+The suite runs on macOS, Linux and Windows in CI, on Node 18 and 22. That covers the installer, the
+data paths, the dashboard, the security checks and the plugin build on all three.
+
+Opening a terminal window is tested for real too, not just in theory: CI calls it, then checks the
+command actually ran in the right folder. Linux gets a desktop from Xvfb with xterm, Windows runs it
+directly, and macOS is verified by hand since its runners have no scriptable Terminal.
+
+The one thing left uncovered is the native folder picker, because a modal dialog cannot be
+automated. Its fallback is tested, so a machine with no dialog available reports cancelled rather
+than hanging, but the dialog itself has only been opened by hand on macOS.
 
 ## Your data
 

package/bin/cli.js

@@ -139,6 +139,35 @@ function uninstall() {
   }
 }
 
+// The registration script has nothing Claude-specific in it, so it is exposed as a
+// plain command too. Any editor, agent or shell script can call this.
+function add() {
+  const { spawnSync } = require('child_process');
+  const script = path.join(ROOT, 'skill', 'register-server.js');
+  const passthrough = args.filter(a => a !== 'add');
+  if (!passthrough.length) {
+    console.log(`Add or update a server from the command line.
+
+  server-studio add --name "Portfolio Site" --cwd "$PWD" --command "npm run dev" --assign
+
+  --name       what to call it
+  --project    a line of context
+  --category   groups cards into filter tabs
+  --cwd        the project folder
+  --command    how to start it
+  --url        address or bare port; omit with --assign
+  --tag        small label, usually the stack
+  --note       anything to remember
+  --assign     pick a free port nothing else uses, and print it
+  --force      allow an existing project to move to a different port
+
+Re-running for the same project updates its fields but keeps its port locked.`);
+    return;
+  }
+  const r = spawnSync(process.execPath, [script, ...passthrough], { stdio: 'inherit' });
+  process.exit(r.status === null ? 1 : r.status);
+}
+
 function start() {
   DATA_DIR = dataDir();
   const { spawn } = require('child_process');
@@ -153,6 +182,7 @@ function help() {
 
   npx server-studio install      install the app + Claude Code skill
   npx server-studio start        run the dashboard (works on macOS, Windows and Linux)
+  npx server-studio add ...      save a server from the command line
   npx server-studio uninstall    remove them (keeps your saved servers)
 
 Options
@@ -166,5 +196,6 @@ Options
 if (cmd === 'help') help();
 else if (cmd === 'install') install();
 else if (cmd === 'start') start();
+else if (cmd === 'add') add();
 else if (cmd === 'uninstall') uninstall();
 else { console.error('unknown command: ' + cmd + '\n'); help(); process.exit(1); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "server-studio",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A tiny dashboard for your local dev servers. One click to run, stop and open them, with one permanent port per project.",
   "author": "Md Mahdi Hasan",
   "license": "MIT",
@@ -18,15 +18,17 @@
   "scripts": {
     "build:plugin": "node scripts/build-plugin.js",
     "prepack": "node scripts/build-plugin.js",
-    "test": "node scripts/test.js"
+    "test": "node scripts/test.js",
+    "test:terminal": "node scripts/test-terminal.js",
+    "postinstall": "node scripts/postinstall.js"
   },
   "files": [
     "bin",
+    "scripts/postinstall.js",
     "app",
     "src",
     "skill",
     "plugin",
-    "scripts",
     "dist",
     "README.md",
     "LICENSE"

package/scripts/postinstall.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Runs the setup automatically after `npm install -g server-studio`, so one command
+// is enough. Deliberately narrow: only a global install triggers it, because setting
+// up writes outside the package and that should never happen to someone who merely
+// pulled this in as a dependency.
+//
+// This must never fail the install. Every path exits 0.
+'use strict';
+
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function skip(why) {
+  if (process.env.SERVER_STUDIO_DEBUG) console.log('server-studio: skipped setup (' + why + ')');
+  process.exit(0);
+}
+
+if (process.env.CI) skip('CI');
+// A dependency install must not touch /Applications or ~/.claude.
+if (process.env.npm_config_global !== 'true') skip('not a global install');
+// Do not run while developing this repo itself.
+if (process.env.INIT_CWD && path.resolve(process.env.INIT_CWD) === path.resolve(__dirname, '..')) {
+  skip('local checkout');
+}
+
+try {
+  const out = execFileSync(process.execPath, [path.join(__dirname, '..', 'bin', 'cli.js'), 'install'], {
+    encoding: 'utf8',
+  });
+  console.log(out.trim());
+} catch (e) {
+  // Setup failing is not a reason for `npm install` to fail. Say so and move on.
+  console.log(
+    'server-studio: could not finish setup automatically.\n' +
+    '  Run it yourself with:  server-studio install\n' +
+    '  Reason: ' + (e && e.message ? e.message.split('\n')[0] : 'unknown')
+  );
+}
+process.exit(0);

package/src/platform.js

@@ -1,6 +1,7 @@
 // Per-OS shims. Everything the dashboard does that is not plain Node lives here.
 'use strict';
 
+const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFile, exec } = require('child_process');
@@ -46,9 +47,21 @@ function runInTerminal(cwd, command, cb) {
     ], cb);
   }
   if (WIN) {
-    // /k keeps the window open so the dev server keeps running and its output stays readable.
-    const line = (cwd ? 'cd /d "' + cwd + '" && ' : '') + command;
-    return execFile('cmd', ['/c', 'start', '', 'cmd', '/k', line], cb);
+    // The command goes into a .bat rather than onto cmd's command line. Node escapes
+    // embedded quotes as \" which cmd.exe does not accept as an escape, so passing a
+    // quoted path through `start cmd /k "..."` mangles it. A file has no such problem.
+    let bat;
+    try {
+      bat = path.join(os.tmpdir(), 'server-studio-' + Date.now() + '-' + process.pid + '.bat');
+      fs.writeFileSync(bat, [
+        '@echo off',
+        cwd ? 'cd /d "' + cwd + '"' : '',
+        command,
+      ].filter(Boolean).join('\r\n') + '\r\n');
+    } catch (e) { return cb(e); }
+    // The empty string is start's window-title argument, and /k keeps the window open
+    // so a dev server keeps running and its output stays readable.
+    return execFile('cmd', ['/c', 'start', '', 'cmd', '/k', bat], cb);
   }
   // Linux has no standard terminal, so try the common ones in turn.
   const line = (cwd ? 'cd ' + shQuote(cwd) + ' && ' : '') + command + '; exec $SHELL';

package/scripts/build-plugin.js

@@ -1,28 +0,0 @@
-#!/usr/bin/env node
-// Builds dist/server-studio.plugin from skill/ + plugin/, so the plugin copy of the
-// skill can never drift from the source in skill/.
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { execFileSync } = require('child_process');
-
-const ROOT = path.join(__dirname, '..');
-const DIST = path.join(ROOT, 'dist');
-const OUT = path.join(DIST, 'server-studio.plugin');
-
-const stage = fs.mkdtempSync(path.join(os.tmpdir(), 'ss-plugin-'));
-const skillDir = path.join(stage, 'skills', 'server-studio');
-fs.mkdirSync(skillDir, { recursive: true });
-
-fs.cpSync(path.join(ROOT, 'skill'), skillDir, { recursive: true });
-fs.cpSync(path.join(ROOT, 'plugin'), stage, { recursive: true });
-
-fs.mkdirSync(DIST, { recursive: true });
-fs.rmSync(OUT, { force: true });
-// -r zips the staged tree; the plugin format is a plain zip.
-execFileSync('zip', ['-qr', OUT, '.', '-x', '.DS_Store'], { cwd: stage });
-fs.rmSync(stage, { recursive: true, force: true });
-
-console.log('built ' + path.relative(ROOT, OUT));

package/scripts/test.js

@@ -1,125 +0,0 @@
-#!/usr/bin/env node
-// End to end check: installs into a temp folder and attacks a temp server.
-// Never touches /Applications, ~/.claude or your real server list.
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const http = require('http');
-const { execFileSync, spawn } = require('child_process');
-
-const ROOT = path.join(__dirname, '..');
-const SB = fs.mkdtempSync(path.join(os.tmpdir(), 'ss-test-'));
-const PORT = 4400 + Math.floor(process.pid % 300);
-const env = {
-  ...process.env,
-  SERVER_STUDIO_APP_DEST: path.join(SB, 'Server Studio.app'),
-  SERVER_STUDIO_SKILL_DEST: path.join(SB, 'skill'),
-  SERVER_STUDIO_DATA_DIR: path.join(SB, 'data'),
-};
-
-let failed = 0;
-function check(name, pass, detail) {
-  console.log((pass ? '  pass  ' : '  FAIL  ') + name + (detail && !pass ? '  -> ' + detail : ''));
-  if (!pass) failed++;
-}
-
-function req(opts, body) {
-  return new Promise(resolve => {
-    const r = http.request({ host: '127.0.0.1', port: PORT, ...opts }, res => {
-      let b = ''; res.on('data', c => b += c); res.on('end', () => resolve({ code: res.statusCode, body: b }));
-    });
-    r.on('error', e => resolve({ code: 0, body: String(e) }));
-    if (body) r.write(body);
-    r.end();
-  });
-}
-
-(async () => {
-  console.log('sandbox: ' + SB + '\n');
-
-  // ---- installer ----
-  execFileSync('node', [path.join(ROOT, 'bin', 'cli.js'), 'install'], { env, stdio: 'ignore' });
-  check('app installed', fs.existsSync(path.join(env.SERVER_STUDIO_APP_DEST, 'Contents', 'Resources', 'server.js')));
-  check('shared src copied into bundle', fs.existsSync(path.join(env.SERVER_STUDIO_APP_DEST, 'Contents', 'Resources', 'platform.js')));
-  check('launcher is executable', (fs.statSync(path.join(env.SERVER_STUDIO_APP_DEST, 'Contents', 'MacOS', 'ServerStudio')).mode & 0o111) !== 0);
-  check('skill installed', fs.existsSync(path.join(env.SERVER_STUDIO_SKILL_DEST, 'SKILL.md')));
-  check('empty data file created', fs.readFileSync(path.join(env.SERVER_STUDIO_DATA_DIR, 'data.json'), 'utf8').trim() === '[]');
-  // The path printed for the Cowork plugin must survive npx clearing its cache.
-  check('plugin copied out of the package', fs.existsSync(path.join(env.SERVER_STUDIO_DATA_DIR, 'server-studio.plugin')));
-
-  // Existing data must survive a reinstall.
-  fs.writeFileSync(path.join(env.SERVER_STUDIO_DATA_DIR, 'data.json'), '[{"id":"keep","name":"keep me"}]');
-  execFileSync('node', [path.join(ROOT, 'bin', 'cli.js'), 'install'], { env, stdio: 'ignore' });
-  check('reinstall keeps existing servers',
-    JSON.parse(fs.readFileSync(path.join(env.SERVER_STUDIO_DATA_DIR, 'data.json'), 'utf8'))[0].id === 'keep');
-
-  // ---- running server ----
-  const srv = spawn('node', [path.join(env.SERVER_STUDIO_APP_DEST, 'Contents', 'Resources', 'server.js')],
-    { env: { ...env, PORT: String(PORT) }, stdio: ['ignore', 'pipe', 'pipe'] });
-  const up = await new Promise(res => {
-    const t = setTimeout(() => res(false), 5000);
-    srv.stdout.on('data', d => { if (String(d).includes('running on')) { clearTimeout(t); res(true); } });
-  });
-  check('server started on its own port', up);
-
-  if (up) {
-    const marker = path.join(SB, 'pwned.txt');
-    const payload = JSON.stringify({ command: 'touch ' + marker });
-
-    const a1 = await req({ method: 'POST', path: '/api/run', headers: { 'Content-Type': 'text/plain' } }, payload);
-    check('text/plain CSRF rejected', a1.code === 415, 'got ' + a1.code);
-
-    const a2 = await req({ method: 'POST', path: '/api/run',
-      headers: { 'Content-Type': 'application/json', Origin: 'https://evil.example' } }, payload);
-    check('foreign Origin rejected', a2.code === 403, 'got ' + a2.code);
-
-    const a3 = await req({ method: 'OPTIONS', path: '/api/run', headers: { Origin: 'https://evil.example' } });
-    check('preflight refused', a3.code === 403 || a3.code === 405, 'got ' + a3.code);
-
-    const good = await req({ method: 'POST', path: '/api/servers',
-      headers: { 'Content-Type': 'application/json', Origin: 'http://localhost:' + PORT } }, '[]');
-    check('same-origin write accepted', good.code === 200, 'got ' + good.code);
-
-    await new Promise(r => setTimeout(r, 300));
-    check('no attack executed a command', !fs.existsSync(marker));
-  }
-  srv.kill();
-
-  // ---- uninstall ----
-  execFileSync('node', [path.join(ROOT, 'bin', 'cli.js'), 'uninstall'], { env, stdio: 'ignore' });
-  check('app removed', !fs.existsSync(env.SERVER_STUDIO_APP_DEST));
-  check('skill removed', !fs.existsSync(env.SERVER_STUDIO_SKILL_DEST));
-  check('saved servers kept without --purge', fs.existsSync(path.join(env.SERVER_STUDIO_DATA_DIR, 'data.json')));
-
-  execFileSync('node', [path.join(ROOT, 'bin', 'cli.js'), 'uninstall', '--purge'], { env, stdio: 'ignore' });
-  check('--purge deletes saved servers', !fs.existsSync(env.SERVER_STUDIO_DATA_DIR));
-
-  // ---- platform shims ----
-  // The real Windows and Linux behaviour cannot run here, so this only proves the
-  // module picks the right command and data path for each OS.
-  function loadPlatformAs(name) {
-    const real = process.platform;
-    Object.defineProperty(process, 'platform', { value: name, configurable: true });
-    delete require.cache[require.resolve(path.join(ROOT, 'src', 'platform.js'))];
-    const m = require(path.join(ROOT, 'src', 'platform.js'));
-    Object.defineProperty(process, 'platform', { value: real, configurable: true });
-    return m;
-  }
-  const saved = process.env.SERVER_STUDIO_DATA_DIR;
-  delete process.env.SERVER_STUDIO_DATA_DIR;
-  const win = loadPlatformAs('win32');
-  const lin = loadPlatformAs('linux');
-  const mac = loadPlatformAs('darwin');
-  check('windows data dir uses AppData', /AppData|Roaming|Server Studio/.test(win.dataDir()) && !win.dataDir().includes('Library'));
-  check('linux data dir uses .config', lin.dataDir().includes('.config'));
-  check('mac data dir uses Application Support', mac.dataDir().includes('Application Support'));
-  check('windows terminal is named Command Prompt', win.terminalName() === 'Command Prompt');
-  check('mac terminal is named Terminal', mac.terminalName() === 'Terminal');
-  if (saved) process.env.SERVER_STUDIO_DATA_DIR = saved;
-
-  fs.rmSync(SB, { recursive: true, force: true });
-  console.log('\n' + (failed ? failed + ' failed' : 'all passed'));
-  process.exit(failed ? 1 : 0);
-})();