server-studio 1.0.1 → 1.1.0

package/README.md

@@ -25,19 +25,20 @@ Node.js is the only requirement. No npm install inside the app, no Electron, no
 
 ## Install
 
-Installing the package only puts the `server-studio` command on your PATH. Setting up the app and
-the skill is a second, explicit step, because it writes outside the package. Either of these works:
-
 ```bash
-npx server-studio install
+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
-npm install -g server-studio && server-studio install
+npx server-studio install
 ```
 
-Running `server-studio` with no arguments does the same thing as `server-studio install`, so if you
-installed globally and typed the bare command, you are already set up.
+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**
 
@@ -154,6 +155,22 @@ node ~/.claude/skills/server-studio/register-server.js \
 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.
@@ -165,7 +182,8 @@ have anything you care about.
 
 **The app**, a dashboard served at `127.0.0.1:4587`.
 
-**The Claude Code skill**, so Claude can register servers for you.
+**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. 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,

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.1",
+  "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",

package/scripts/postinstall.js

@@ -1,25 +1,39 @@
 #!/usr/bin/env node
-// npm only puts the command on PATH. Setting up the app and the skill writes outside
-// the package, so it stays an explicit step rather than a silent side effect of install.
-// This just makes sure nobody is left wondering why nothing appeared.
+// 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');
 
-// Quiet in CI, and quiet while developing this repo itself.
-if (process.env.CI) process.exit(0);
-if (process.env.INIT_CWD && path.resolve(process.env.INIT_CWD) === path.resolve(__dirname, '..')) {
+function skip(why) {
+  if (process.env.SERVER_STUDIO_DEBUG) console.log('server-studio: skipped setup (' + why + ')');
   process.exit(0);
 }
-// npx runs the command straight after installing, so the hint would be noise.
-if ((process.env.npm_command === 'exec') || /_npx/.test(__dirname)) process.exit(0);
-
-console.log(`
-Server Studio: the command is installed, but nothing is set up yet.
 
-Finish with:
-  server-studio install
+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');
+}
 
-That adds the app and the Claude Code skill. See what it will do first with:
-  server-studio install --dry-run
-`);
+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);