Closes #56.

Summary

Split jspod into a library and a CLI shell so host programs can embed jspod in-process instead of spawning the CLI as a child.

• lib/start.js — exports start(options) returning a handle { url, port, host, root, ready, exit, stop }. Pod-startup logic only: no process.exit, no banner, no signal handlers.
• lib/index.js — barrel export ({ start, formatUrl }).
• index.js — thin CLI shell. argv parsing, banner, install subcommand, SIGINT/SIGTERM handlers that call handle.stop() then process.exit. Behaviour identical to pre-refactor CLI.
• package.json — main + exports map point at lib/index.js; bin stays at index.js. lib/ added to files.

API shape

import { start } from 'jspod';

const pod = await start({
  port: 5444,        // requested; may shift up if busy (findFreePort)
  host: 'localhost',
  root: './pod-data',
  auth: true,
  open: false,       // CLI defaults this to true; lib defaults to false
  bootstrap: true,
  // also: multiuser, git, browser ('folder'|'json'), provisionKeys, mcp
});

console.log(pod.url);           // 'http://localhost:5444'
console.log(pod.port);          // actual port
await pod.ready;                // true once GET / responds
const { code, signal } = await pod.stop();   // graceful SIGTERM, idempotent

Errors throw (invalid port, no free port in range, etc.) rather than calling process.exit. The ready promise rejects if JSS fails to come up; exit resolves when the underlying JSS child exits for any reason (so callers can react).

Why a stop() method and not just signals?

A library must not install signal handlers — the host program owns those. stop() lets the host bind its own SIGINT/lifecycle hooks and explicitly tear down the pod when it's ready. The CLI shell binds SIGINT/SIGTERM and calls handle.stop() from inside them, preserving the prior CLI behaviour.

Bootstrap-spawn fix

The first-run "install default bundle" path used to spawn process.execPath, [process.argv[1], 'install', ...]. Under library use, process.argv[1] is the host program — that would fail. Now resolved via import.meta.url to the CLI script in the same package.

Smoke tests

• CLI: node index.js --port 5455 --no-bootstrap → banner, JSS spawn, ready, GET / 200, SIGINT triggers the graceful shutdown handler, JSS gets SIGTERM, exits 0, prints "Goodbye!".
• API direct: start({ port:5456, root, open:false, bootstrap:false }) → ready resolves true, fetch(pod.url) returns 200, stop() returns { code:0, signal:null }, second stop() is idempotent.
• Bare specifier: file: install of this branch into a temp package, then import { start } from 'jspod' → exports { formatUrl, start } as expected.

Downstream

solid-desktop currently spawns jspod as a child process (with ELECTRON_RUN_AS_NODE=1 plumbing and a manual readiness probe). With this merged, that collapses to:

const pod = await start({ port, root: ROOT, open: false });
mainWindow.loadURL(pod.url);
app.on('before-quit', () => pod.stop());

Separate PR — out of scope for this one.

Out of scope

• Streaming logs / structured events beyond ready/exit/stop — can add a log option or event emitter incrementally as consumers ask.
• jspod install as a library function — kept CLI-only for now; can be lifted later.
• API stability commitments (0.0.x ≠ stable).

Test plan

• npx jspod on a clean checkout — banner, ready, browser opens
• npx jspod install chrome (with a running pod) — unchanged
• import { start } from 'jspod' from a host program — handle works, stop terminates JSS
• Ctrl+C against the CLI — graceful shutdown, exit 0