fb-slides 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ 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.
 
+## 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`

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
@@ -153,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

@@ -29,6 +29,10 @@ export const ALWAYS_EXCLUDED = ['node_modules', '.git', '.angular', '.next', '.c
 // 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 command is a name in
 // PATH — `code-insiders` and `cursor` answer `serve-web` too — or a path, for a
@@ -42,6 +46,17 @@ const editorSpec = (value) => {
   };
 };
 
+// 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) => {

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
@@ -86,8 +106,7 @@ const portInUse = (port) =>
 
 // 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.
-const EDITOR_PORT_TRIES = 10;
-
+// 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;
@@ -154,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.
@@ -217,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",
+  "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__"