server-studio 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+Notable changes to Server Studio. Dates are release dates.
+
+## 1.2.0 — 2026-08-30
+
+### Folders replace categories
+- The sidebar lists your folders. Click one to filter, click **All servers** to go back.
+- Create, rename and delete folders. Deleting one never deletes servers, they move to **Unfiled**.
+- Move a server with the folder button on its card, by dragging the card onto a folder, or from
+  the Folder field in Edit.
+- Existing categories become folders automatically on first launch. Nothing is lost.
+- `server-studio add --folder "Name"` files a server as it registers, creating the folder if new.
+  `--category` still works as an alias.
+
+### Ports
+- Two cards on one port now show a `port clash · fix` badge. Clicking it moves one to a free port.
+- Where the dev script is one it recognises, it also writes the new port into that project's
+  `package.json`, showing the exact before and after first and keeping a backup. Anything it cannot
+  parse safely is refused rather than guessed at.
+- Saving a server on a port another card already uses offers a free one instead.
+- **Fixed:** `portOf()` only matched a port written after a colon, so a card saved as a bare `5173`
+  reported no port at all. That silently skipped both clash detection and the collision check.
+
+### Cards
+- Run and Stop are one button that follows the live status: green **Run**, red **Stop** once the
+  port answers, and a muted **Working** while it is being rechecked.
+- **Fixed:** running a server with no project folder set executed the command in your home
+  directory, failing with something confusing like `Missing script: "dev"`. It now refuses, says so
+  on the card, and opens the folder field.
+
+### Sidebar
+- The version sits under the app name. When a newer release exists it turns green and becomes a
+  one-click update.
+- A request box: send a message and an email address, both optional to use and easy to dismiss.
+  Dismissing it collapses it to a **Request a feature** button.
+- A creator credit pinned to the bottom.
+
+### Interface
+- Dialogs are in-app and match the rest of the UI, instead of the browser's own
+  "localhost:4587 says" boxes. Escape, click-outside and Enter all work, and destructive actions
+  get a red button.
+- Layout verified from 320px to 1920px with no horizontal overflow. On phones the sidebar
+  dissolves and reorders so your servers come before the request box.
+
+### Telemetry and signups
+- **Fixed:** an unreachable analytics endpoint added roughly 1.5 seconds to every install because
+  the ping held the process open. It no longer does.
+- **Fixed:** on Node 18 the request was unref'd before a socket existed, which does not propagate on
+  that version, so the delay persisted there. The socket is unref'd too.
+- Documented in the README, with `SERVER_STUDIO_NO_TELEMETRY=1` and `DO_NOT_TRACK` both honoured.
+- Signups go to the author's own list, so the bundled Cloudflare Worker keeps only anonymous counts
+  and its open write route is gone.
+
+## 1.1.1 — 2026-08-25
+
+- Documentation only. Stated precisely what CI checks about the folder picker and what it cannot.
+- No runtime change; the file list is identical to 1.1.0.
+
+## 1.1.0 — 2026-08-25
+
+- `npm install -g server-studio` now completes setup on its own. Installing as a project dependency
+  or under CI still touches nothing outside the package, and a failure prints a hint rather than
+  failing the install.
+- Added `server-studio add`, which registers a server with no AI involved, so any editor, agent or
+  script can use it. The Claude Code skill wraps this command.
+
+## 1.0.1 — 2026-08-25
+
+- Made clear that installing the package is not the whole setup.
+- **Fixed:** the path printed for the Cowork plugin pointed inside `node_modules`, which npx deletes
+  as soon as it finishes. The plugin is copied somewhere durable first.
+
+## 1.0.0 — 2026-08-20
+
+First public release.
+
+- A local dashboard for your dev servers: run, stop, open, and live port status.
+- One permanent port per project, with the rule documented per framework.
+- Ships a Claude Code skill and a Cowork plugin.
+- **Fixed before release:** the local server accepted cross-site form posts, so any page you had
+  open could have run shell commands through `/api/run`. Writes now require a JSON content type,
+  foreign origins are rejected and preflights refused.
+- Cross-platform: a macOS app bundle, plus `server-studio start` on Windows and Linux. CI opens a
+  real terminal window and the native folder picker on each platform.

package/README.md

@@ -85,7 +85,7 @@ Click **Add server**. Only the name matters, everything else can be filled in la
 |---|---|---|
 | 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` |
+| Folder | Which folder it lives in, chosen from the sidebar list | `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` |
@@ -98,19 +98,34 @@ 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 |
+| **Run / Stop** | One button that follows the live status. Green **Run** opens a terminal, `cd`s into the folder and runs the command. Once the port answers it turns into a red **Stop**, which kills whatever holds that port |
 | Open in browser | Opens the card's URL |
-| Stop | Kills whatever process is holding that port. Useful when something is stuck |
+| Move to folder | Pick a folder, or drag the card onto one in the sidebar |
 | Edit | Change any field |
 | Delete | Removes the card. Does not touch the project itself |
 
+If a card has no project folder set, **Run** refuses instead of running the command in your home
+directory, and says so on the card.
+
 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.
+folder and notes at once, so searching `wordpress` or `5181` or `vite` all find the right card.
+
+### Folders
+
+The sidebar lists your folders. Click one to see only its servers, click **All servers** to go
+back. **New folder** creates one, and the pencil beside a folder renames it, or deletes it if you
+clear the name. Deleting a folder never deletes servers, they move to **Unfiled**.
+
+A server lives in one folder. Move it with the folder button on the card, by dragging the card onto
+a folder in the sidebar, or from the Folder field in Edit.
+
+Upgrading from an older version? Categories became folders automatically the first time you open
+the dashboard, and nothing is lost.
 
 ### The one permanent port rule
 
@@ -131,6 +146,14 @@ makes a saved entry go stale. Use the strict option so it fails loudly instead:
 
 Then put that same port in both the run command and the URL on the card.
 
+**When two cards share a port**, both show a `port clash · fix` badge. Clicking it moves one of them
+to a free port. If the project's dev script is one it recognises, it also writes the new port into
+that project's `package.json`, showing you the exact before and after first and keeping a backup, so
+the card and the project stay in agreement. Anything it cannot parse safely is refused rather than
+guessed at, and only the card changes.
+
+Adding a server on a port another card already uses offers you a free one before saving.
+
 ### 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
@@ -162,15 +185,24 @@ command with no AI involved, so any tool that can run a shell command can use it
 Cursor, Copilot, Windsurf, a Makefile, a shell alias, or you:
 
 ```bash
-server-studio add --name "Portfolio Site" --cwd "$PWD" --command "npm run dev" --assign
+server-studio add --name "Portfolio Site" --cwd "$PWD" --command "npm run dev" --folder "Client work" --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.
+write the port into the project config. `--folder` files it under that folder, creating the folder if
+it does not exist yet. 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.
 
+Run `server-studio add` with no arguments for the full list of fields.
+
+### Staying up to date
+
+The version sits under the app name in the sidebar. When a newer release is on npm it turns green
+and becomes a button: click it, confirm, and the update runs in a terminal window. Restart Server
+Studio when it finishes. Your saved servers and folders are never touched by an update.
+
 ### Backups
 
 **Export** saves your whole list to `server-studio-backup.json`. **Import** loads one back.
@@ -214,6 +246,38 @@ The one step no machine can do is click a folder and confirm, so the path that r
 directory is exercised by hand rather than by CI. If Browse ever misbehaves on your system, type the
 path into the field instead. Nothing else depends on it.
 
+## Telemetry
+
+Server Studio sends one anonymous ping when it is installed and one when it launches, so
+installs can be counted. That is the whole of it.
+
+What is sent:
+
+| Field | Example | Why |
+|---|---|---|
+| A random id | `9f3c...` | Generated on your machine, stored in your data folder. Lets two launches from one machine count as one user |
+| Version | `1.2.0` | Which versions are still in use |
+| OS, arch | `darwin`, `arm64` | Which platforms to test on |
+| Node major | `22` | Which Node versions to keep supporting |
+
+What is never sent: your projects, folder paths, run commands, ports, notes, IP-derived
+location, or anything you typed into the app. There is no account and no profile.
+
+Turn it off completely, before or after installing:
+
+```bash
+export SERVER_STUDIO_NO_TELEMETRY=1
+```
+
+The standard `DO_NOT_TRACK=1` is honoured too, and nothing is sent under CI. The ping never
+blocks anything: it is fired without holding the process open, so a blocked or offline
+network costs you no time at all.
+
+The email box in the sidebar is separate and entirely opt-in. Nothing is sent from it unless
+you type an address and press send. When you do, your address and your message go to
+`mahdicreates.com`, which is the author's site, so he can reply and let you know when
+something new ships. Nothing else about you is attached.
+
 ## Your data
 
 Saved servers live in one file:
@@ -239,6 +303,19 @@ The app runs shell commands you saved, so it is deliberately locked to your own
 Treat the run command on a card the way you would treat a line you are about to paste into your own
 terminal, because that is exactly what it becomes.
 
+## Forking this
+
+Two values point at the author's own services. If you fork this, change them or your users'
+signups arrive in someone else's inbox:
+
+| What | Where | Why |
+|---|---|---|
+| `SERVER_STUDIO_SUBSCRIBE_URL` | `src/telemetry.js` | Defaults to `mahdicreates.com`. Point it at your own endpoint, or set it empty to remove the sidebar box entirely |
+| `SERVER_STUDIO_ANALYTICS_URL` | unset by default | Install counting is inert unless you set this to your own collector |
+
+The creator credit in the sidebar is ordinary MIT-licensed source. You are free to change it,
+same as any other part.
+
 ## Development
 
 ```bash
@@ -259,6 +336,10 @@ SERVER_STUDIO_DATA_DIR=/tmp/ss-test node src/server.js
 code. On macOS the installer copies it into the app bundle, so the bundle never holds a stale
 version.
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
 ## License
 
 MIT

package/bin/cli.js

@@ -6,6 +6,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const telemetry = require('../src/telemetry');
 
 const ROOT = path.join(__dirname, '..');
 const APP_NAME = 'Server Studio.app';
@@ -109,6 +110,8 @@ function install() {
     console.log('\nUsing Claude Cowork? Install the plugin by opening this file:');
     console.log('  ' + pluginFile);
   }
+
+  telemetry.ping('install'); // counts a real install (never fires on --dry-run: it returns above)
 }
 
 /* ---------- uninstall ---------- */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "server-studio",
-  "version": "1.1.1",
+  "version": "1.2.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",
@@ -31,6 +31,7 @@
     "skill",
     "plugin",
     "dist",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],

package/skill/SKILL.md

@@ -49,7 +49,7 @@ line it prints and bake that port into the project config (see the golden rule a
 node "$HOME/.claude/skills/server-studio/register-server.js" \
   --name "Project Name" \
   --project "What it's for" \
-  --category "WordPress" \
+  --folder "WordPress" \
   --cwd "/absolute/path/to/project" \
   --command "npm run dev -- --port 3001 --strictPort" \
   --url "localhost:3001" \
@@ -61,7 +61,8 @@ node "$HOME/.claude/skills/server-studio/register-server.js" \
 Field guide:
 - `--name` — short label, e.g. "Portfolio Site"
 - `--project` — the project/task it belongs to
-- `--category` — broad bucket: WordPress, Web app, Storybook, Docs, etc. (used for the filter chips)
+- `--folder` — folder name to file it under, created if it does not exist yet (shown in the sidebar).
+  `--category` still works as an alias for older callers.
 - `--cwd` — absolute project folder; the run command executes here
 - `--command` — the exact command that starts the server (this is what the Run button runs)
 - `--url` — address or bare port (`3000` works, becomes `localhost:3000`)

package/skill/register-server.js

@@ -6,7 +6,7 @@
 // No npm deps. Usage:
 //   node register-server.js --name "Portfolio Site" --project "Client redesign" \
 //        --cwd "/Users/you/Sites/portfolio" --command "npm run dev" --url "localhost:3001" \
-//        --category "WordPress" --tag "Vite" --note "admin: ninja/ninja"
+//        --folder "WordPress" --tag "Vite" --note "admin: ninja/ninja"
 //
 //   # let it pick a fresh, never-used port for a NEW project:
 //   node register-server.js --name "New Site" --cwd "/path" --command "npm run dev" --assign
@@ -29,6 +29,7 @@ const DATA_DIR = (function () {
   return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'server-studio');
 })();
 const DATA_FILE = path.join(DATA_DIR, 'data.json');
+const FOLDERS_FILE = path.join(DATA_DIR, 'folders.json');
 const BASE_PORT = 3001; // assigned ports start here and go up
 
 // ---- parse --flag "value" args ----
@@ -50,7 +51,7 @@ function portFromUrl(url) {
 const entry = {
   name: args.name || '',
   project: args.project || '',
-  category: args.category || '',
+  folder: resolveFolder(args.folder || args.category),
   cwd: args.cwd || '',
   command: args.command || '',
   url: typeof args.url === 'string' ? args.url : '',
@@ -70,6 +71,24 @@ try { data = JSON.parse(fs.readFileSync(DATA_FILE, 'utf8')) || []; } catch (e) {
 if (!Array.isArray(data)) data = [];
 
 function uid() { return 's_' + Math.random().toString(36).slice(2, 9) + Date.now().toString(36); }
+
+// The app groups by folder id. Take a folder NAME on the command line and resolve it,
+// creating the folder if it does not exist yet, so a registered server lands in the
+// right place instead of sitting unfiled.
+function resolveFolder(name) {
+  const wanted = String(name || '').trim();
+  if (!wanted) return '';
+  let folders = [];
+  try { folders = JSON.parse(fs.readFileSync(FOLDERS_FILE, 'utf8')) || []; } catch (e) { folders = []; }
+  if (!Array.isArray(folders)) folders = [];
+  const hit = folders.find(f => String(f.name || '').toLowerCase() === wanted.toLowerCase());
+  if (hit) return hit.id;
+  const f = { id: 'f_' + Math.random().toString(36).slice(2, 9), name: wanted };
+  folders.push(f);
+  try { fs.mkdirSync(DATA_DIR, { recursive: true }); fs.writeFileSync(FOLDERS_FILE, JSON.stringify(folders, null, 2)); }
+  catch (e) { return ''; }
+  return f.id;
+}
 const norm = s => String(s || '').trim().toLowerCase();
 function usedPorts(excludeId) {
   return new Set(data.filter(s => s.id !== excludeId).map(s => portFromUrl(s.url)).filter(Boolean));