fb-slides 0.7.0 → 0.9.0

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.
@@ -200,10 +223,11 @@ export const dev = async (config, runtimeDir, reload) => {
       const editor = editorUrl ? { url: editorUrl, root: config.root, sources: now.demoSources } : null;
       return renderIndex(now, runtimeDir, editor ? { editor } : {});
     },
-    // Editing a slide in the browser saves it back into its .md — dev only,
-    // which is what makes the edit button appear at all (the runtime probes
-    // /api/editable). Build and preview never mount this.
-    api: createEditApi(config.decksPath),
+    // Editing a slide in the browser saves it back into its .md, and dropping
+    // a file on the deck puts it in assets/ — dev only, which is what makes the
+    // edit button appear at all (the runtime probes /api/editable). Build and
+    // preview never mount this.
+    api: createEditApi(config.decksPath, { dir: config.assetsDir, path: config.assetsPath }),
     generated: {
       [`/${REVEAL_THEME_URL}`]: async () => {
         const now = await current();
@@ -217,13 +241,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/edit.mjs

@@ -11,6 +11,7 @@
 //   POST /api/slide               → { op?, file, index, expected, source }
 //     op 'save' (default) replaces the slide, 'add' inserts a new one right
 //     after it, 'delete' removes it — separator and all.
+//   /api/assets                   → dropping a file into assets/ (assets.mjs)
 //
 // The slide boundaries are computed here with the same split deck.js uses, so
 // the index the browser counted is the index this file finds. The splice
@@ -21,6 +22,8 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve, sep } from 'node:path';
 
+import { createAssetApi } from './assets.mjs';
+
 // Kept in step with deck.js: front matter comes off first, then slides split on
 // `---` lines, are trimmed, and empty segments are dropped.
 const FRONT_MATTER = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
@@ -78,7 +81,11 @@ const readBody = (req, limit = 1024 * 1024) =>
 // the request arrives same-origin under a name that is not ours.
 const LOCAL_HOST = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
 
-export const createEditApi = (decksPath) => {
+// `assets` is `{ dir, path }` — the folder a dropped file lands in. Without it
+// the drawer keeps its editing, and says so in the probe, but drops nothing.
+export const createEditApi = (decksPath, assets = null) => {
+  const assetApi = assets ? createAssetApi(assets) : null;
+
   const deckFile = (name) => {
     if (typeof name !== 'string' || !FILE_NAME.test(name) || name.startsWith('.')) return null;
     const target = resolve(decksPath, name);
@@ -88,7 +95,13 @@ export const createEditApi = (decksPath) => {
   return async (req, res, pathname) => {
     if (!LOCAL_HOST.test(req.headers.host ?? '')) return json(res, 403, { error: 'forbidden' });
 
-    if (pathname === '/api/editable') return json(res, 200, { editable: true });
+    if (pathname === '/api/editable') {
+      return json(res, 200, { editable: true, assets: assetApi ? assets.dir : null });
+    }
+
+    if (pathname === '/api/assets') {
+      return assetApi ? assetApi(req, res) : json(res, 404, { error: 'not found' });
+    }
 
     if (pathname !== '/api/slide') return json(res, 404, { error: 'not found' });
 

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.9.0",
   "type": "module",
   "description": "Markdown-driven reveal.js decks: live demo embeds, annotation, mermaid, and a zero-config dev server",
   "keywords": [