fb-slides 0.7.0-rc.1 → 0.8.0

package/CHANGELOG.md

@@ -7,7 +7,31 @@ this — which makes it worth being able to see what arrived.
 Entries are written as the work lands, under **Unreleased**; the release commit
 that stamps the version renames that heading to the version and its date.
 
-## Unreleased
+## 0.8.0 — 2026-09-07
+
+- **`npm run kill` — everything the talk left running, gone.** `dev` starts more
+  than itself, and it takes its side processes down with it only when it is asked
+  politely: killed outright, or with its terminal window closed, it leaves a
+  `vite` or an `ng serve` under the npm that started it and a `code serve-web`,
+  all holding the ports the next run wants. `fb-slides kill` clears them. It goes
+  by port rather than by process tree, because the ports are the one thing
+  already written down: the deck's, `preview`'s one above it, the `url:` of every
+  `servers:` entry, and the editor's 7100–7109 — the whole walk `dev` makes when
+  something holds the first one. Whatever is listening there is named, asked to
+  stop, and made to; the npm above it exits on its own once its server is gone. A
+  `servers:` entry with no `url:` is the one thing it cannot reach. New talks get
+  the script from `create`; a talk that already exists adds
+  `"kill": "fb-slides kill"` to its `scripts`.
+
+- **`dev` says when a port is already taken.** Each `servers:` port is probed
+  before anything is spawned, so a port that answers before its demo has started
+  is a leftover from a run that did not come down cleanly — and it is named under
+  the deck's URL, where the demo servers' own banners cannot bury it, instead of
+  turning up as a slide showing yesterday's build. The deck's own port, which has
+  always failed outright rather than moved, now names the way out in the same
+  breath: ``port 4000 is already in use — `npx fb-slides kill` ``.
+
+## 0.7.0 — 2026-09-07
 
 - **A `source ↗` button on demo slides.** `editor: true` in `slides.config.js`
   starts `code serve-web` — the web server built into VS Code — alongside the
@@ -20,8 +44,10 @@ that stamps the version renames that heading to the version and its date.
   The slide's address and the one in `servers:` need not match to the character:
   the exact URL is tried first, then the origin, so a demo embedded at `#/` or
   `/tools` still finds its folder.
-  The editor's port — the deck's plus 100 — is checked before it starts, because
-  `serve-web` has no `--strictPort` and two decks are enough to collide. A built
+  The editor listens on 7100 — clear of 3000, 4200, 5173 and the rest of the band
+  the demos want, since the editor must never land on the app it exists to open —
+  and walks up from there if something holds it, because `serve-web` has no
+  `--strictPort` and would otherwise half-bind a busy port. A built
   deck never carries the button: the link is a localhost address and a path on
   your disk. `--no-editor` turns it off for one run. When the editor cannot
   start — no `code` in `PATH`, port taken — the deck comes up as usual and says

package/README.md

@@ -34,6 +34,7 @@ its `servers:` entry and its slide come out together.
 | `npm run dev` | serves the deck on :4000 and opens it |
 | `npm run build` | `dist/` — self-contained, relative URLs, works offline |
 | `npm run preview` | build, then serve the result |
+| `npm run kill` | stops the deck, the demos and the editor — whatever is left holding their ports |
 
 ## Writing
 
@@ -107,7 +108,18 @@ Vite — copied into `demo/` as it is. It is embedded by **URL**, not by folder
 **real VS Code** in a new tab — `code serve-web`, the web server built into the editor you
 already have, started alongside the deck. Nothing is installed and nothing is embedded, and
 a built deck never carries it. Run `dev` once at your desk first: VS Code downloads its
-server half on the very first use. [docs/source-code.md](docs/source-code.md).
+server half on the very first use.
+
+> **It needs VS Code on the machine running the deck.** `serve-web` is a subcommand of
+> VS Code's own CLI, so the button exists only where that CLI does: `code`, or
+> `code-insiders`, or a fork that kept it — `editor: { command: 'cursor' }`. Without it
+> nothing breaks and nothing is missing from the talk; `dev` says so under the deck's URL
+> and every demo slide comes up as it always did, minus the button. The same is true when
+> `code` is installed but not on the `PATH` of the shell you start the deck from, which an
+> IDE's built-in terminal manages on its own — name the binary outright then:
+> `editor: { command: '/usr/local/bin/code' }`.
+
+[docs/source-code.md](docs/source-code.md).
 
 ### Stepped code highlighting
 
@@ -294,7 +306,7 @@ export default {
     { name: 'angular demo', cwd: 'demo/app', command: 'npm', args: ['start', '--', '--port', '4200'] },
   ],
 
-  editor: true,                  // a `source ↗` button on every demo slide
+  editor: true,                  // a `source ↗` button on every demo slide (needs VS Code)
 
   port: 4000,
   open: true,
@@ -314,9 +326,52 @@ Copying a real Angular or Vite app into `demo/` and wiring it up — including t
 Vite needs so a busy port fails instead of moving:
 [docs/framework-demos.md](docs/framework-demos.md).
 
-`editor: true` is a side process of the same kind, and fails the same way — a missing
-`code` in PATH, a port already taken, and you get a warning and demo slides without their
-`source ↗` button: [docs/source-code.md](docs/source-code.md).
+`editor: true` is a side process of the same kind, and fails the same way: no VS Code on
+the machine, or no `code` on the PATH of the shell that started the deck, and you get a
+warning under the deck's URL and demo slides without their `source ↗` button. It listens on
+7100, clear of the ports the demos want, and walks up from there if something holds it:
+[docs/source-code.md](docs/source-code.md).
+
+### When something survives
+
+`dev` starts more than itself, and it takes its side processes down with it — as long as it
+is asked politely. Killed outright, or with its terminal window closed, it leaves them: a
+`vite` or an `ng serve` under the npm that started it, `code serve-web`, all still holding
+the ports the next run wants.
+
+```bash
+npm run kill
+```
+
+It reads the ports out of this file — the deck's, `preview`'s one above it, the `url:` of
+every `servers:` entry, the editor's 7100–7109 — and stops whatever is listening on them,
+naming each one before it goes:
+
+```
+  ✗ 4000  deck           node …/bin/fb-slides.mjs dev (39190)
+  ✗ 4200  angular demo   ng serve (39212)
+  ✗ 7100  editor         …/Visual Studio Code.app/… (32669)
+
+  3 processes stopped.
+```
+
+Going by port rather than by process tree is what makes it work at all after the deck is
+gone: the port is the thing already written down, and the process holding it is the one in
+the way. The npm above it exits on its own once its server is stopped.
+
+A `servers:` entry with no `url:` is the one thing it cannot reach — that key is how the
+config says where the demo answers.
+
+`dev` also looks before it leaps: a port a `servers:` entry is about to use that is *already*
+answering is a leftover from a previous run, and it says so under the deck's URL rather than
+letting you find out from a demo slide showing yesterday's build.
+
+```
+  kill test
+  → http://localhost:4010/
+  ⚠  4201 is already in use — angular-hello from an earlier run?
+     That server is not this deck's: `npx fb-slides kill` frees the ports it uses.
+```
 
 ## Theming
 

package/bin/fb-slides.mjs

@@ -6,6 +6,7 @@
 //   fb-slides dev            serve it, open it
 //   fb-slides build          dist/, self-contained
 //   fb-slides preview        build, then serve dist/
+//   fb-slides kill           stop whatever `dev` left running
 // ---------------------------------------------------------------------------
 
 import { createRequire } from 'node:module';
@@ -38,6 +39,7 @@ const HELP = `
                                                                 [--no-servers] [--no-editor]
   fb-slides build             build dist/                       [--out dir] [--watch]
   fb-slides preview           build, then serve the result      [--port n]
+  fb-slides kill              stop the deck, the demos and the editor
 
   Run from a folder holding decks/*.md. slides.config.js is optional.
 `;
@@ -79,6 +81,11 @@ const run = async () => {
     return void (await dev(config, RUNTIME, reload));
   }
 
+  if (command === 'kill') {
+    const { kill } = await import('../lib/kill.mjs');
+    return void (await kill(config));
+  }
+
   if (command === 'build') {
     const { build, buildWatch } = await import('../lib/build.mjs');
     return void (await (flag('watch') ? buildWatch(config, RUNTIME) : build(config, RUNTIME)));

package/docs/framework-demos.md

@@ -158,6 +158,26 @@ only on the machine running the app. A framework demo is for presenting live. If
 has to stand on its own on the web, point that slide at a deployed URL — the marker takes
 any `http(s)` address.
 
+## When one outlives the deck
+
+`dev` kills the processes it spawned, but the process it spawned is npm and the one holding
+4200 is npm's child — and when the deck itself is killed outright, or its terminal window
+closed, no handler runs at all. What is left is a dev server nobody can see, on the port the
+next run needs.
+
+```bash
+npm run kill
+```
+
+Every port in `servers:` — that is what `url:` is read for — plus the deck's and the
+editor's, and whatever is listening there is stopped. A demo declared without a `url:` is
+the one this cannot reach.
+
+And `dev` warns rather than leaving you to it: it probes each `servers:` port before
+spawning anything, so a port that answers *before* its demo has started is reported under
+the deck's URL. Otherwise the demo's own dev server fails, or moves one port along, and the
+slide keeps showing the run you thought you had stopped.
+
 ## Removing one
 
 Three things, all yours: the folder, the `servers:` entry, the slide. Delete them and

package/docs/source-code.md

@@ -8,6 +8,12 @@ is `code serve-web` — the web server built into the VS Code on the machine
 running the talk — pointed at the demo's folder. The file tree, the search, the
 terminal, the extensions, the keybindings: the editor, in a tab.
 
+Which is also the one requirement: **VS Code has to be installed on the machine
+running the deck**, because `serve-web` is a subcommand of its CLI and nothing
+here reimplements it. A fork that kept the CLI does as well —
+`editor: { command: 'cursor' }`. On a machine without one the deck is unchanged
+except for the button, and `dev` says why under its own URL.
+
 ## Turning it on
 
 ```js
@@ -17,13 +23,13 @@ export default {
 };
 ```
 
-That is the whole configuration. `dev` starts it alongside the deck, on the
-deck's port plus 100, and every demo slide grows the link.
+That is the whole configuration. `dev` starts it alongside the deck, on port
+7100, and every demo slide grows the link.
 
 ```
 $ npm run dev
 
-  ↑ code serve-web → http://localhost:4100/
+  ↑ code serve-web → http://localhost:7100/
 
   My Talk
   → http://localhost:4000/
@@ -32,10 +38,11 @@ $ npm run dev
 Both defaults move if they have to:
 
 ```js
-editor: { port: 5000, command: 'code-insiders' },
+editor: { port: 7300, command: 'code-insiders' },
 ```
 
-`command` is a name in PATH. `code-insiders` and `cursor` answer `serve-web`
+`command` is a name in PATH, or a path to the binary when the shell you start
+the deck from does not carry it. `code-insiders` and `cursor` answer `serve-web`
 too; whatever you name has to be a VS Code CLI, because that subcommand is what
 this uses.
 
@@ -49,28 +56,30 @@ Start `dev` once at your desk after turning the key on. That is the whole
 precaution, and it is why `editor:` is off in a fresh deck rather than on.
 
 If `code` is not in PATH at all, the deck says so and carries on without the
-button:
+button — see [When no slide has one](#when-no-slide-has-one) below.
 
-```
-⚠  code is not in PATH — the demo slides get no source button.
-   In VS Code: Shell Command: Install 'code' command in PATH.
-```
+## Why 7100
 
-## When the port is taken
+Because the demos own everything below it. 3000 is Next's default, 4200 is
+`ng serve`'s, 5173 and 5174 are Vite's, 6006 is Storybook's, 8080 is everyone's.
+The editor landing on the very app it exists to open is the one collision that
+must not happen — and since `dev` starts the demo servers first, the editor is
+the one that would lose.
 
-The default is the deck's port plus 100, and **two decks are enough to collide**:
-one on 4000 puts its editor on 4100, which is a perfectly ordinary port for the
-second deck to be on.
+It is not derived from the deck's port for the same reason: a deck on 4100 would
+put its editor on 4200, which is `ng serve` waiting to happen.
 
 `code serve-web` does not fail on a busy port the way the deck server does — a
 process holding the IPv6 side leaves the IPv4 side free, both bind, and
 `localhost` in the browser then lands on whichever the resolver picked. That is
 the failure you find out about on stage. So the port is checked before the
-editor is started, and a taken one is a message rather than a wrong tab:
+editor starts, and a taken one moves the editor along: 7101, 7102, up to ten
+tries. Nobody types this address — the page is handed it — so a different number
+costs nothing. Only ten taken ports in a row is a message:
 
 ```
-⚠  port 4100 is in use — no source button.
-   Free it, or give the editor another one: `editor: { port: n }`.
+⚠  source ↗ off: ports 7100–7109 are all in use.
+   Give the editor one of its own: `editor: { port: n }`.
 ```
 
 ## Where a slide's code is found
@@ -150,6 +159,15 @@ editor: { command: '/usr/local/bin/code' },
   table above is read from `servers:` as written in the config, so it still
   works when none of those servers were started.
 
+## When it outlives the deck
+
+`serve-web` is a side process, and it goes down with the deck — unless the deck goes down
+the hard way, killed outright or with its terminal window closed. Then it stays up, on
+7100, invisible, and the next run finds the port taken and walks past it to 7101.
+
+`npm run kill` sweeps the whole walk, 7100 through 7109, along with the deck's port and the
+demos'. Worth knowing before wondering why the editor is on a different port every day.
+
 ## It is your real filesystem
 
 The editor opens the actual folder, with write access, as an editor does. Saving

package/lib/config.mjs

@@ -21,19 +21,42 @@ const AUTO_STATIC = ['assets', 'demo', 'public', 'images', 'img'];
 // Never served, never published — heavy, private, or generated.
 export const ALWAYS_EXCLUDED = ['node_modules', '.git', '.angular', '.next', '.cache', '.DS_Store'];
 
+// The editor's port. A fixed number rather than one derived from the deck's,
+// because the band under 6000 belongs to the demos: 3000 is Next's, 4200 is
+// `ng serve`'s, 5173 and 5174 are Vite's, 8080 is everyone's. An editor that
+// lands on the app it exists to open is the one collision that must not happen
+// — and `dev` starts the demo servers first, so it would be the editor that
+// loses. Two decks at once are handled by walking up from here instead.
+const EDITOR_PORT = 7100;
+
+// How far up from there `dev` walks when something already holds it, and so how
+// far `kill` has to sweep to be sure it caught the editor of an earlier run.
+export const EDITOR_PORT_TRIES = 10;
+
 // `editor: true` turns the source button on with the defaults; `{ port, command }`
-// changes them; leaving the key out is no button at all. The port follows the
-// deck's so two talks open at once do not fight over it, and the command is a
-// name in PATH — `code-insiders` and `cursor` answer `serve-web` too.
-const editorSpec = (value, deckPort) => {
+// changes them; leaving the key out is no button at all. The command is a name in
+// PATH — `code-insiders` and `cursor` answer `serve-web` too — or a path, for a
+// shell whose PATH does not carry the editor.
+const editorSpec = (value) => {
   if (!value) return null;
   const user = value === true ? {} : value;
   return {
     command: user.command ?? 'code',
-    port: Number(user.port ?? deckPort + 100),
+    port: Number(user.port ?? EDITOR_PORT),
   };
 };
 
+// The port a `servers:` entry answers on, read out of its `url:`. Both `dev`
+// (is something already sitting there?) and `kill` (what do I stop?) ask this.
+export const portOf = (url) => {
+  try {
+    const { port, protocol } = new URL(url);
+    return Number(port || (protocol === 'https:' ? 443 : 80));
+  } catch {
+    return null;
+  }
+};
+
 export const findConfigFile = (root) => CONFIG_FILES.map((name) => join(root, name)).find(existsSync) ?? null;
 
 const importConfig = async (file) => {
@@ -109,7 +132,7 @@ export const loadConfig = async (root = process.cwd(), overrides = {}) => {
   // `--no-editor` is its own flag rather than a part of `--no-servers`: that one
   // is for skipping a demo's dev server, and a demo that is not running is
   // exactly when you want to be able to open its code.
-  config.editor = overrides.editor === false ? null : editorSpec(user.editor, config.port);
+  config.editor = overrides.editor === false ? null : editorSpec(user.editor);
   // The folder behind each demo embedded by URL, taken from `servers:` as the
   // project wrote it rather than from the list `dev` will start: `--no-servers`
   // empties that one, and a demo that is not running is exactly when its code is

package/lib/dev.mjs

@@ -11,7 +11,7 @@ import { connect } from 'node:net';
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
-import { assertUsable } from './config.mjs';
+import { EDITOR_PORT_TRIES, assertUsable, portOf } from './config.mjs';
 import { createEditApi } from './edit.mjs';
 import { createDeckServer, listen } from './server.mjs';
 import { renderIndex } from './render.mjs';
@@ -55,6 +55,26 @@ const startSideServer = (spec, root, children) => {
   });
 };
 
+// A port that answers before the deck has started anything is almost always the
+// same demo from a run that did not come down cleanly — `dev` kills what it
+// spawned, but a deck killed outright, or with its terminal window closed, kills
+// nothing. The demo's own dev server then either fails or quietly moves one port
+// along, and the slide embedding the old URL shows yesterday's build: the kind of
+// thing that costs ten minutes to work out, and you find it on stage. Probed
+// before anything is spawned, so whatever answers is certainly not ours.
+const leftovers = async (servers) => {
+  const withPorts = servers.map((spec) => ({ spec, port: portOf(spec.url) })).filter((each) => each.port);
+  const taken = await Promise.all(withPorts.map((each) => portInUse(each.port)));
+  const busy = withPorts.filter((_, i) => taken[i]);
+  if (!busy.length) return [];
+  return [
+    ...busy.map(
+      ({ spec, port }) => `⚠  ${port} is already in use — ${spec.name ?? spec.cwd} from an earlier run?`,
+    ),
+    'That server is not this deck\'s: `npx fb-slides kill` frees the ports it uses.',
+  ];
+};
+
 // ---------------------------------------------------------------------------
 // The source-code editor. `code serve-web` is VS Code's own web server, shipped
 // inside the editor the presenter already has: no dependency is added here, and
@@ -66,9 +86,7 @@ const startSideServer = (spec, root, children) => {
 // `serve-web` has no --strictPort, and it does not fail on a taken port the way
 // the deck server does: another process holding the IPv6 side leaves the IPv4
 // side free, both bind, and `localhost` in the browser then lands on whichever
-// the resolver picked. Two fb-slides decks are enough to arrange that — one on
-// 4000 puts its editor on 4100, which is a perfectly ordinary port for the
-// second deck. So ask first, and say which port to use instead.
+// the resolver picked — the failure you find out about on stage. So ask first.
 const portInUse = (port) =>
   Promise.all(
     ['127.0.0.1', '::1'].map(
@@ -86,6 +104,16 @@ const portInUse = (port) =>
     ),
   ).then((answers) => answers.some(Boolean));
 
+// A second deck, or anything else already sitting there, moves the editor along
+// rather than turning it off: nobody types this address — the page is handed it.
+// How far it walks is in config.mjs, because `kill` sweeps the same range.
+const freePort = async (start) => {
+  for (let port = start; port < start + EDITOR_PORT_TRIES; port += 1) {
+    if (!(await portInUse(port))) return port;
+  }
+  return null;
+};
+
 const hasCommand = (command) =>
   new Promise((done) => {
     const probe = spawn(command, ['--version'], { stdio: 'ignore' });
@@ -108,16 +136,17 @@ const startEditor = async (spec, children) => {
     };
   }
 
-  if (await portInUse(spec.port)) {
+  const port = await freePort(spec.port);
+  if (port === null) {
     return {
       note: [
-        `⚠  source ↗ off: port ${spec.port} is in use.`,
-        `Free it, or give the editor another one: \`editor: { port: n }\`.`,
+        `⚠  source ↗ off: ports ${spec.port}–${spec.port + EDITOR_PORT_TRIES - 1} are all in use.`,
+        `Give the editor one of its own: \`editor: { port: n }\`.`,
       ],
     };
   }
 
-  const url = `http://localhost:${spec.port}/`;
+  const url = `http://localhost:${port}/`;
   // First run downloads the server half of VS Code into ~/.vscode/cli, which is
   // a hundred megabytes and a minute — hence `stdio: 'inherit'`, so it happens
   // in front of whoever started the deck rather than silently before a talk.
@@ -127,7 +156,7 @@ const startEditor = async (spec, children) => {
     [
       'serve-web',
       '--port',
-      String(spec.port),
+      String(port),
       // No token in the URL: the slide has to be able to link straight to a
       // folder, and this listens on localhost only.
       '--without-connection-token',
@@ -144,6 +173,10 @@ const startEditor = async (spec, children) => {
   return { url };
 };
 
+// Indented under the deck's own URL: first line at the summary's margin, the
+// rest under it.
+const note = (lines) => lines.map((line, i) => (i ? `     ${line}` : `  ${line}`));
+
 // What the page is built from, read again on every request. A config with a
 // syntax error in it — the state it is in halfway through an edit — leaves the
 // last good one standing rather than serving a broken deck.
@@ -207,13 +240,15 @@ export const dev = async (config, runtimeDir, reload) => {
 
   const url = `http://localhost:${config.port}/`;
   const children = [];
+  const stale = await leftovers(config.servers);
   for (const spec of config.servers) startSideServer(spec, config.root, children);
   const editor = config.editor ? await startEditor(config.editor, children) : {};
   editorUrl = editor.url ?? null;
 
   // The last thing printed, so nothing scrolls over it.
   const summary = [``, `  ${config.title}`, `  → ${url}`];
-  if (editor.note) summary.push(...editor.note.map((line, i) => (i ? `     ${line}` : `  ${line}`)));
+  if (stale.length) summary.push(...note(stale));
+  if (editor.note) summary.push(...note(editor.note));
   console.log(summary.join('\n') + '\n');
   if (config.open) setTimeout(() => openBrowser(url), 400);
 

package/lib/kill.mjs

@@ -0,0 +1,221 @@
+// ---------------------------------------------------------------------------
+// `fb-slides kill` — everything the talk left running, gone.
+//
+// `dev` starts more than itself: a demo's own dev server, `code serve-web`. The
+// handler in dev.mjs kills the children it spawned, but the child is npm and the
+// thing holding the port is npm's child; and when the deck goes down by SIGKILL
+// or by a closed terminal window, no handler runs at all. What is left is a
+// process nobody can see holding a port the next run needs.
+//
+// So this does not chase the process tree — it goes at the ports, which are the
+// one thing already written down. `slides.config.js` declares the deck's port,
+// every demo's `url:`, and the editor's; whatever is listening there is what the
+// talk started, and killing the listener is enough — npm exits on its own once
+// the server under it is gone.
+// ---------------------------------------------------------------------------
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { EDITOR_PORT_TRIES, portOf } from './config.mjs';
+
+const run = promisify(execFile);
+
+// Returns the output, `''` when the tool ran and found nothing (lsof exits 1 on
+// an empty match), and `null` when the tool is not on this machine at all.
+const exec = async (command, args) => {
+  try {
+    const { stdout } = await run(command, args, { maxBuffer: 8 * 1024 * 1024 });
+    return stdout;
+  } catch (error) {
+    return error.code === 'ENOENT' ? null : (error.stdout ?? '');
+  }
+};
+
+// Every port the talk can be sitting on, each with the name to print for it.
+// `preview` builds and serves on the port above the deck's; the editor walks up
+// from its own when something holds it (dev.mjs), so the whole walk is fair game.
+const targets = (config) => {
+  const found = new Map();
+  const add = (port, label) => {
+    if (Number.isInteger(port) && port > 0 && port < 65536 && !found.has(port)) found.set(port, label);
+  };
+
+  add(config.port, 'deck');
+  add(config.port + 1, 'preview');
+  for (const spec of config.servers ?? []) {
+    add(portOf(spec.url), spec.name ?? spec.cwd ?? spec.command);
+  }
+  if (config.editor) {
+    for (let i = 0; i < EDITOR_PORT_TRIES; i += 1) add(config.editor.port + i, 'editor');
+  }
+  return [...found].map(([port, label]) => ({ port, label }));
+};
+
+const collect = (into, port, pid) => {
+  if (!port || !pid) return;
+  if (!into.has(port)) into.set(port, new Set());
+  into.get(port).add(pid);
+};
+
+// `-F pn` is lsof's machine-readable form: a `p<pid>` line, then an `n<address>`
+// line for each socket that process holds.
+const fromLsof = (text) => {
+  const ports = new Map();
+  let pid = null;
+  for (const line of text.split('\n')) {
+    if (line[0] === 'p') pid = Number(line.slice(1));
+    else if (line[0] === 'n') collect(ports, Number(line.match(/:(\d+)$/)?.[1]), pid);
+  }
+  return ports;
+};
+
+// `ss -tlnpH`: LISTEN … 0.0.0.0:4000 … users:(("node",pid=123,fd=20))
+const fromSs = (text) => {
+  const ports = new Map();
+  for (const line of text.split('\n')) {
+    const port = Number(line.trim().split(/\s+/)[3]?.match(/:(\d+)$/)?.[1]);
+    for (const [, pid] of line.matchAll(/pid=(\d+)/g)) collect(ports, port, Number(pid));
+  }
+  return ports;
+};
+
+// `netstat -ano -p tcp`: TCP  0.0.0.0:4000  0.0.0.0:0  LISTENING  1234
+const fromNetstat = (text) => {
+  const ports = new Map();
+  for (const line of text.split('\n')) {
+    if (!/LISTENING/i.test(line)) continue;
+    const fields = line.trim().split(/\s+/);
+    collect(ports, Number(fields[1]?.match(/:(\d+)$/)?.[1]), Number(fields[4]));
+  }
+  return ports;
+};
+
+// One call, not one per port: asking the machine what it is listening on is the
+// expensive half, and it answers about everything at once anyway.
+const listening = async () => {
+  if (process.platform === 'win32') {
+    const netstat = await exec('netstat', ['-ano', '-p', 'tcp']);
+    return netstat === null ? null : fromNetstat(netstat);
+  }
+  const lsof = await exec('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-F', 'pn']);
+  if (lsof !== null) return fromLsof(lsof);
+  const ss = await exec('ss', ['-tlnpH']);
+  return ss === null ? null : fromSs(ss);
+};
+
+const CUT = 56;
+
+// What to print next to the pid, so it is obvious this is killing the demo and
+// not something else that happens to want 3000.
+const describe = async (pids) => {
+  const names = new Map();
+  if (!pids.length) return names;
+
+  if (process.platform === 'win32') {
+    const list = (await exec('tasklist', ['/FO', 'CSV', '/NH'])) ?? '';
+    for (const line of list.split('\n')) {
+      const [, name, pid] = line.match(/^"([^"]*)","(\d+)"/) ?? [];
+      if (pid) names.set(Number(pid), name);
+    }
+    return names;
+  }
+
+  const ps = (await exec('ps', ['-o', 'pid=,command=', '-p', pids.join(',')])) ?? '';
+  for (const line of ps.split('\n')) {
+    const [, pid, command] = line.trim().match(/^(\d+)\s+(.*)$/) ?? [];
+    if (pid) names.set(Number(pid), command.length > CUT ? `${command.slice(0, CUT - 1)}…` : command);
+  }
+  return names;
+};
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // Someone else's process: still there, just not ours to signal.
+    return error.code === 'EPERM';
+  }
+};
+
+const wait = (ms) => new Promise((done) => setTimeout(done, ms));
+
+const signal = (pid, name) => {
+  try {
+    process.kill(pid, name);
+    return null;
+  } catch (error) {
+    return error.code === 'ESRCH' ? null : error.code;
+  }
+};
+
+// A range prints as a range: the editor alone is ten of these.
+const ranges = (ports) => {
+  const sorted = [...ports].sort((a, b) => a - b);
+  const out = [];
+  for (const port of sorted) {
+    const last = out[out.length - 1];
+    if (last && port === last[1] + 1) last[1] = port;
+    else out.push([port, port]);
+  }
+  return out.map(([from, to]) => (from === to ? `${from}` : `${from}–${to}`)).join(', ');
+};
+
+export const kill = async (config) => {
+  const wanted = targets(config);
+  const ports = await listening();
+
+  if (ports === null) {
+    console.log(
+      `\n  ✗ cannot look up ports: no ${process.platform === 'win32' ? 'netstat' : 'lsof or ss'} on this machine.\n`,
+    );
+    process.exitCode = 1;
+    return [];
+  }
+
+  const seen = new Set([process.pid]);
+  const hits = [];
+  for (const { port, label } of wanted) {
+    for (const pid of ports.get(port) ?? []) {
+      if (seen.has(pid)) continue;
+      seen.add(pid);
+      hits.push({ port, label, pid });
+    }
+  }
+
+  if (!hits.length) {
+    console.log(`\n  nothing to kill — ${ranges(wanted.map((t) => t.port))} are free.\n`);
+    return [];
+  }
+
+  const names = await describe(hits.map((hit) => hit.pid));
+  const width = Math.max(...hits.map((hit) => hit.label.length));
+  console.log('');
+  for (const hit of hits) {
+    console.log(`  ✗ ${String(hit.port).padEnd(5)} ${hit.label.padEnd(width)}  ${names.get(hit.pid) ?? ''} (${hit.pid})`);
+  }
+
+  // Asked first, insisted on after: a vite or an `ng serve` given the chance to
+  // put the terminal back the way it found it usually takes it.
+  const refused = [];
+  for (const hit of hits) signal(hit.pid, 'SIGTERM');
+  await wait(900);
+  for (const hit of hits) {
+    if (!alive(hit.pid)) continue;
+    const error = signal(hit.pid, 'SIGKILL');
+    if (error) refused.push({ ...hit, error });
+  }
+  await wait(200);
+
+  const left = hits.filter((hit) => alive(hit.pid));
+  if (left.length) {
+    console.log(`\n  ⚠  still up: ${left.map((hit) => hit.pid).join(', ')} — not this user's to kill?`);
+    if (refused.length) console.log(`     ${refused.map((hit) => `${hit.pid}: ${hit.error}`).join(', ')}`);
+    process.exitCode = 1;
+  }
+
+  const stopped = hits.length - left.length;
+  console.log(`\n  ${stopped} ${stopped === 1 ? 'process' : 'processes'} stopped.\n`);
+  return hits;
+};

package/lib/server.mjs

@@ -170,7 +170,7 @@ export const listen = (server, port) =>
     server.once('error', (error) =>
       reject(
         error.code === 'EADDRINUSE'
-          ? new Error(`port ${port} is already in use — free it, or pass --port <n>`)
+          ? new Error(`port ${port} is already in use — \`npx fb-slides kill\`, or pass --port <n>`)
           : error,
       ),
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fb-slides",
-  "version": "0.7.0-rc.1",
+  "version": "0.8.0",
   "type": "module",
   "description": "Markdown-driven reveal.js decks: live demo embeds, annotation, mermaid, and a zero-config dev server",
   "keywords": [

package/templates/starter/_package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "fb-slides dev",
     "build": "fb-slides build",
-    "preview": "fb-slides preview"
+    "preview": "fb-slides preview",
+    "kill": "fb-slides kill"
   },
   "devDependencies": {
     "__PKG__": "__VERSION__"

package/templates/starter/slides.config.js

@@ -44,9 +44,10 @@ export default {
   // and nothing is embedded. Off by default because the very first run downloads
   // VS Code's server half (~100 MB) and you do not want to discover that on
   // stage: uncomment, run `dev` once at your desk, and it is cached from then on.
-  // `{ port: 4100, command: 'code' }` to change either — the default port is the
-  // deck's plus 100. `--no-editor` turns it off for one run, and a
-  // built deck never has it: the link is a localhost address and a path on disk.
+  // `{ port: 7300, command: 'code' }` to change either — the default is 7100,
+  // which is clear of the ports the demos want. `--no-editor` turns it off for
+  // one run, and a built deck never has it: the link is a localhost address and
+  // a path on disk.
   editor: true,
 
   // The corner signature. Uncomment to show it.