pi-inspect 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.6.0
+
+### Breaking changes
+
+- The server listens on `127.0.0.1` only. To reach it from another machine, start it with `--host 0.0.0.0`.
+
+### Features
+
+- **New dashboard.** A keyboard-first tree of tools, commands, skills, and the system prompt, in light and dark mode.
+- **Server options.** `--port` (`0` picks a free port), `--host`, `--open`, `--no-open`, and `--session`.
+- **pi-kanban pane.** `GET /api/companion` and the embed theme handshake let the pi-kanban board show pi-inspect in a pane, in the board's colors.
+- The snapshot records the model from pi's current context.
+
+### Fixes
+
+- `pi -p` with pi-inspect loaded exits when the prompt is done.
+
+### Security
+
+- The API answers only to local host names, and refuses `POST` requests from other origins.
+
+### Other
+
+- Express 5, without chokidar. The browser opener loads only when it is needed.
+- Snapshot files are written atomically.
+- `node:test` suites for the store, routes, flags, and server.

package/README.md

@@ -31,6 +31,37 @@ Then use `/inspect start | stop | restart | status | open | list | snapshot` fro
 
 State is driven entirely through the `?session=` URL param — share or refresh URLs to pin views. The in-page picker also writes to the URL.
 
+A session is captured when it starts with pi-inspect loaded. If you open a session that was never captured, the picker marks it "not captured". Run `/inspect snapshot` in that session to capture it.
+
+The theme follows your system setting until you toggle it with `t`.
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `j` / `k`, arrows | Next / previous row. Moving onto an item shows it. |
+| `g` / `G` | First / last row |
+| `l` / `h` | Expand a group / collapse it or go to the parent |
+| `Enter` | Open the row (toggle a group) |
+| `e` | Expand or collapse all |
+| `/` | Search by name or source |
+| `0`–`5` | Kind: all, context, tools, commands, prompts, skills |
+| `s` | Pick a session |
+| `o` | Open the item's file in your editor |
+| `c` | Copy the item's path |
+| `r` | Refresh |
+| `t` | Toggle light and dark |
+| `Esc` | Close the item, or leave an input |
+| `?` | Show all keys |
+
+## Sharing a snapshot
+
+Click the share button in the topbar to copy a self-contained link of the current snapshot. The snapshot is `deflate-raw` compressed and base64url-encoded into the URL hash (`#s=…`) — no server, no upload, no account.
+
+Recipients open the link on the hosted static dashboard at **https://nikiforovall.blog/pi-inspect/** and see the exact same tools / commands / skills / system prompt. The page makes no network requests; everything is in the URL.
+
+Heads up: the link includes the system prompt and `cwd`. Don't share secrets you wouldn't paste in chat.
+
 ## What it captures
 
 - **Tools** — name, description, parameter schema, source
@@ -38,8 +69,39 @@ State is driven entirely through the `?session=` URL param — share or refresh
 - **System prompt** — full text injected on init, split into system / user `AGENTS.md` / project `AGENTS.md` sections
 - **Session meta** — cwd, model, sessionId, sessionName, captured timestamp
 
-Snapshots live at `~/.pi/agent/inspect/snapshots/<sessionId>.json`.
+Snapshots live at `<agentDir>/inspect/snapshots/<sessionId>.json`. The agent dir is `PI_CODING_AGENT_DIR`, or `~/.pi/agent` when it is not set, as in pi.
+
+## Server options
 
-## Port
+| Flag | Env var | What it does |
+| --- | --- | --- |
+| `--port <n>` | `PORT` | Port. Default `5462`. `0` picks a free port. The server prints the URL it listens on. |
+| `--host <addr>` | | Listen address. Default `127.0.0.1`. |
+| `--open` | | Open the dashboard in the browser |
+| `--no-open` | | Do not open the browser, also when `--open` is given |
+| `--session <id>` | | The session to open with `--open` |
+
+A flag wins over its env var.
+
+The server refuses `POST` requests whose `Origin` is not its own, so other web pages cannot delete snapshots or change settings. The API also answers only to `localhost`, `127.0.0.1`, `[::1]` and the `--host` name, which blocks DNS-rebinding pages. With `--host 0.0.0.0` or `::` the API answers to every host name.
+
+## Embedding
+
+A host such as the pi-kanban board can run the dashboard as a companion and frame it:
+
+- `GET /api/companion` returns `{ name, version, session }`. `session` is the page for one session, `/?session={id}`.
+- Add `embed=1` to the query of the framed URL. The dashboard then posts `{ type: 'pi-companion:ready' }` to its parent.
+- The parent answers with `{ type: 'pi-companion:theme', mode, colors }`, and sends it again when its theme changes. `mode` is `light` or `dark`. `colors` holds `bgDeep`, `bgSurface`, `bgElevated`, `bgHover`, `border`, `textPrimary`, `textSecondary`, `textTertiary`, `textMuted`, `accent`, `accentText`, `success`, `warning`, and `error`, each a CSS color.
+
+In embed mode the theme toggle and the GitHub link are hidden, and the theme is not saved. The page uses no browser dialogs, so it works in a sandboxed frame without `allow-modals`.
+
+## Development
+
+```sh
+npm install
+npm test                        # node:test: snapshot store, routes, flags, server spawn, watcher
+npm run typecheck:extensions    # type-checks extensions/inspect.ts against pi's types
+node server.js --port 0 --no-open
+```
 
-`5462` — override via `PORT` env var.
+Set `PI_CODING_AGENT_DIR` to point the server at another agent dir, for example a dev one.

package/extensions/inspect.ts

@@ -3,6 +3,7 @@ import {
 	mkdirSync,
 	readdirSync,
 	readFileSync,
+	realpathSync,
 	renameSync,
 	statSync,
 	unlinkSync,
@@ -11,7 +12,6 @@ import {
 	type FSWatcher,
 } from "node:fs";
 import { createConnection } from "node:net";
-import { homedir } from "node:os";
 import {
 	dirname,
 	join as joinPath,
@@ -22,6 +22,9 @@ import { fileURLToPath } from "node:url";
 import {
 	DefaultPackageManager,
 	type ExtensionAPI,
+	type ExtensionContext,
+	getAgentDir,
+	type PackageSource,
 	parseFrontmatter,
 	type ResolvedResource,
 	SettingsManager,
@@ -31,7 +34,8 @@ const extDir = fileURLToPath(new URL(".", import.meta.url));
 const port = 5462;
 const url = `http://localhost:${port}`;
 
-const INSPECT_DIR = joinPath(homedir(), ".pi", "agent", "inspect");
+const AGENT_DIR = getAgentDir();
+const INSPECT_DIR = joinPath(AGENT_DIR, "inspect");
 const SNAP_DIR = joinPath(INSPECT_DIR, "snapshots");
 const INDEX_PATH = joinPath(SNAP_DIR, "index.json");
 const REQ_DIR = joinPath(INSPECT_DIR, "requests");
@@ -107,9 +111,16 @@ function readIndex(): IndexEntry[] {
 	}
 }
 
+// The dashboard server watches SNAP_DIR and reads files on change, so it must never see a half-written one.
+function writeJsonAtomic(file: string, value: unknown): void {
+	mkdirSync(dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.tmp`;
+	writeFileSync(tmp, JSON.stringify(value, null, 2), "utf8");
+	renameSync(tmp, file);
+}
+
 function writeIndex(entries: IndexEntry[]): void {
-	mkdirSync(SNAP_DIR, { recursive: true });
-	writeFileSync(INDEX_PATH, JSON.stringify({ sessions: entries }, null, 2), "utf8");
+	writeJsonAtomic(INDEX_PATH, { sessions: entries });
 }
 
 function upsertIndex(entry: IndexEntry): void {
@@ -119,8 +130,7 @@ function upsertIndex(entry: IndexEntry): void {
 }
 
 function writeSnapshot(id: string, snapshot: unknown): void {
-	mkdirSync(SNAP_DIR, { recursive: true });
-	writeFileSync(joinPath(SNAP_DIR, `${sanitize(id)}.json`), JSON.stringify(snapshot, null, 2), "utf8");
+	writeJsonAtomic(joinPath(SNAP_DIR, `${sanitize(id)}.json`), snapshot);
 }
 
 type DisabledKind = "command" | "prompt" | "skill" | "extension" | "theme";
@@ -139,7 +149,6 @@ type DisabledItem = {
 	baseDir: string;
 };
 
-const AGENT_DIR = joinPath(homedir(), ".pi", "agent");
 const SETTINGS_PATH = joinPath(AGENT_DIR, "settings.json");
 
 type ResourceKind = "skills" | "prompts" | "extensions" | "themes";
@@ -308,22 +317,15 @@ async function processToggleRequest(req: ToggleRequest, sessionCwd: string): Pro
 		const baseDir = md.baseDir ?? dirname(target.path);
 		const pattern = relativePath(baseDir, target.path);
 		const settings = scope === "project" ? sm.getProjectSettings() : sm.getGlobalSettings();
-		const packages = [...(settings.packages ?? [])];
+		const packages: PackageSource[] = [...(settings.packages ?? [])];
 		const idx = packages.findIndex((p) => (typeof p === "string" ? p : p.source) === md.source);
 		if (idx < 0) throw new Error(`package not found in settings: ${md.source}`);
-		let pkg = packages[idx];
-		if (typeof pkg === "string") {
-			pkg = { source: pkg };
-			packages[idx] = pkg;
-		}
-		const arrayKey = req.resourceKind as keyof typeof pkg & ("extensions" | "skills" | "prompts" | "themes");
-		const current = ((pkg as any)[arrayKey] as string[] | undefined) ?? [];
-		const updated = applyPattern(current, pattern, enabled);
-		(pkg as any)[arrayKey] = updated.length > 0 ? updated : undefined;
-		const hasFilters = (["extensions", "skills", "prompts", "themes"] as const).some(
-			(k) => (pkg as any)[k] !== undefined,
-		);
-		if (!hasFilters) packages[idx] = (pkg as any).source;
+		const found = packages[idx];
+		const pkg = typeof found === "string" ? { source: found } : { ...found };
+		const updated = applyPattern(pkg[req.resourceKind] ?? [], pattern, enabled);
+		pkg[req.resourceKind] = updated.length > 0 ? updated : undefined;
+		const hasFilters = RESOURCE_KINDS.some((k) => pkg[k] !== undefined);
+		packages[idx] = hasFilters ? pkg : pkg.source;
 		if (scope === "project") sm.setProjectPackages(packages);
 		else sm.setPackages(packages);
 		await sm.flush();
@@ -334,19 +336,18 @@ async function processToggleRequest(req: ToggleRequest, sessionCwd: string): Pro
 	const baseDir = scope === "project" ? joinPath(sessionCwd, ".pi") : AGENT_DIR;
 	const pattern = relativePath(baseDir, target.path);
 	const settings = scope === "project" ? sm.getProjectSettings() : sm.getGlobalSettings();
-	const current = ((settings as any)[req.resourceKind] as string[] | undefined) ?? [];
-	const updated = applyPattern(current, pattern, enabled);
-	const setters: Record<ResourceKind, { user: string; project: string }> = {
-		skills:     { user: "setSkillPaths",          project: "setProjectSkillPaths" },
-		prompts:    { user: "setPromptTemplatePaths", project: "setProjectPromptTemplatePaths" },
-		extensions: { user: "setExtensionPaths",      project: "setProjectExtensionPaths" },
-		themes:     { user: "setThemePaths",          project: "setProjectThemePaths" },
+	const updated = applyPattern(settings[req.resourceKind] ?? [], pattern, enabled);
+	const setters: Record<ResourceKind, Record<DisabledScope, (paths: string[]) => void>> = {
+		skills:     { user: (p) => sm.setSkillPaths(p),          project: (p) => sm.setProjectSkillPaths(p) },
+		prompts:    { user: (p) => sm.setPromptTemplatePaths(p), project: (p) => sm.setProjectPromptTemplatePaths(p) },
+		extensions: { user: (p) => sm.setExtensionPaths(p),      project: (p) => sm.setProjectExtensionPaths(p) },
+		themes:     { user: (p) => sm.setThemePaths(p),          project: (p) => sm.setProjectThemePaths(p) },
 	};
-	(sm as any)[setters[req.resourceKind][scope]](updated);
+	setters[req.resourceKind][scope](updated);
 	await sm.flush();
 }
 
-let lastCtx: any = null;
+let lastCtx: ExtensionContext | null = null;
 let reqWatcher: FSWatcher | null = null;
 const recentlyHandled = new Set<string>();
 
@@ -365,7 +366,7 @@ async function handleRequestFile(full: string): Promise<void> {
 		return;
 	}
 
-	const cwd = lastCtx?.sessionManager?.getCwd?.() ?? process.cwd();
+	const cwd = lastCtx?.sessionManager.getCwd() ?? process.cwd();
 	try {
 		await processToggleRequest(req, cwd);
 		try { unlinkSync(full); } catch {}
@@ -391,7 +392,8 @@ function setupRequestWatcher(): void {
 	} catch {}
 	if (reqWatcher) return;
 	try {
-		reqWatcher = fsWatch(REQ_DIR, (_event, filename) => {
+		// libuv aborts the process on an event under a Windows 8.3 short path, so watch the long form.
+		reqWatcher = fsWatch(realpathSync.native(REQ_DIR), (_event, filename) => {
 			if (!filename) return;
 			const name = String(filename);
 			if (!name.endsWith(".json") || name.endsWith(".err.json")) return;
@@ -399,31 +401,27 @@ function setupRequestWatcher(): void {
 			try { statSync(full); } catch { return; }
 			void handleRequestFile(full);
 		});
+		// A live watcher keeps the event loop alive, so `pi -p` would never exit.
+		reqWatcher.unref();
 	} catch (e: any) {
 		console.warn(`pi-inspect: request watcher failed: ${e?.message ?? e}`);
 	}
 }
 
-async function captureSnapshot(ctx: any): Promise<{ id: string; entry: IndexEntry } | null> {
+async function captureSnapshot(ctx: ExtensionContext): Promise<{ id: string; entry: IndexEntry } | null> {
 	const sm = ctx.sessionManager;
-	const id = sm?.getSessionId?.();
-	if (!id) return null;
-	const cwd = sm?.getCwd?.() ?? null;
-	const name = sm?.getSessionName?.() ?? null;
-	const model = ctx.getModel?.()?.id ?? null;
-	const systemPrompt = typeof ctx.getSystemPrompt === "function" ? ctx.getSystemPrompt() : null;
-	const pi = piRef as any;
-	const commands = typeof pi?.getCommands === "function" ? pi.getCommands() : [];
-	const tools = typeof pi?.getAllTools === "function" ? pi.getAllTools() : [];
-	const activeTools = typeof pi?.getActiveTools === "function" ? pi.getActiveTools() : [];
+	const id = sm.getSessionId();
+	if (!id || !piRef) return null;
+	const cwd = sm.getCwd() ?? null;
+	const name = sm.getSessionName() ?? null;
+	const model = ctx.model?.id ?? null;
+	const systemPrompt = ctx.getSystemPrompt();
+	const commands = piRef.getCommands();
+	const tools = piRef.getAllTools();
+	const activeTools = piRef.getActiveTools();
 	const activePaths = new Set<string>();
-	for (const c of commands) {
-		const p = c?.sourceInfo?.path;
-		if (typeof p === "string") activePaths.add(p.replace(/\\/g, "/").toLowerCase());
-	}
-	for (const t of tools) {
-		const p = t?.sourceInfo?.path;
-		if (typeof p === "string") activePaths.add(p.replace(/\\/g, "/").toLowerCase());
+	for (const { sourceInfo } of [...commands, ...tools]) {
+		if (sourceInfo?.path) activePaths.add(sourceInfo.path.replace(/\\/g, "/").toLowerCase());
 	}
 	const { disabled: disabledItems, pending: pendingItems } = await discoverFromPackages(cwd, activePaths);
 	const capturedAt = Date.now();
@@ -442,8 +440,8 @@ async function startServer(notify: (m: string, l?: "info" | "error") => void): P
 	if (await probePort(port)) return true;
 	lastStderr = "";
 	const serverPath = resolvePath(extDir, "..", "server.js");
-	child = spawn(process.execPath, [serverPath], {
-		env: { ...process.env, PORT: String(port) },
+	child = spawn(process.execPath, [serverPath, "--port", String(port), "--no-open"], {
+		env: { ...process.env, PI_CODING_AGENT_DIR: AGENT_DIR },
 		stdio: ["ignore", "ignore", "pipe"],
 		detached: true,
 		windowsHide: true,
@@ -508,6 +506,10 @@ export default function inspectExtension(pi: ExtensionAPI) {
 		lastCtx = ctx;
 		await captureSnapshot(ctx);
 	});
+	pi.on("session_shutdown", () => {
+		reqWatcher?.close();
+		reqWatcher = null;
+	});
 
 	pi.registerCommand("inspect", {
 		description:

package/lib/agent-dir.js

@@ -0,0 +1,18 @@
+'use strict';
+const os = require('node:os');
+const path = require('node:path');
+
+// Same rule as pi's getAgentDir: PI_CODING_AGENT_DIR with ~ expanded, else ~/.pi/agent.
+function agentDir(env = process.env) {
+  const dir = env.PI_CODING_AGENT_DIR;
+  if (!dir) return path.join(os.homedir(), '.pi', 'agent');
+  if (dir === '~') return os.homedir();
+  if (/^~[\\/]/.test(dir)) return path.join(os.homedir(), dir.slice(2));
+  return path.resolve(dir);
+}
+
+function inspectDir(env = process.env) {
+  return path.join(agentDir(env), 'inspect');
+}
+
+module.exports = { agentDir, inspectDir };

package/lib/app.js

@@ -0,0 +1,144 @@
+'use strict';
+const express = require('express');
+const fs = require('node:fs');
+const path = require('node:path');
+const githubSource = require('./github-source');
+const { openInEditor } = require('./editor');
+const { writeJsonAtomic } = require('./snapshot');
+const pkg = require('../package.json');
+
+const PUBLIC_DIR = path.join(__dirname, '..', 'public');
+const RESOURCE_KINDS = ['skills', 'prompts', 'extensions', 'themes'];
+
+// Path template a host such as the pi-kanban board fills in to open one session.
+const SESSION_PATH = '/?session={id}';
+
+function collectSourceRoots(snap) {
+  const roots = new Set();
+  for (const x of [...(snap.tools ?? []), ...(snap.commands ?? [])]) {
+    const baseDir = x?.sourceInfo?.baseDir;
+    if (typeof baseDir === 'string' && baseDir) roots.add(baseDir);
+  }
+  return [...roots];
+}
+
+const LOOPBACK_NAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+const ANY_ADDRESS = new Set(['0.0.0.0', '::', '[::]']);
+
+// A DNS-rebinding page reaches the server under its own host name, where its origin checks pass.
+// Serve the API only to loopback names and the listen address, unless the server listens on every address.
+function hostAllowlist(listenHost) {
+  return (req, res, next) => {
+    if (ANY_ADDRESS.has(listenHost) || LOOPBACK_NAMES.has(req.hostname) || req.hostname === listenHost) return next();
+    res.status(403).json({ ok: false, error: 'host not allowed' });
+  };
+}
+
+// The routes change files or open programs, so a web page on another origin must not reach them.
+// Browsers always send Origin on POST; tools such as the extension's fetch send none.
+function sameOriginOnly(req, res, next) {
+  const origin = req.get('origin');
+  if (origin) {
+    let host = null;
+    try { host = new URL(origin).host; } catch {}
+    if (host !== req.get('host')) return res.status(403).json({ ok: false, error: 'cross-origin request refused' });
+  }
+  next();
+}
+
+function createApp({ store, inspectDir, host = '127.0.0.1', openEditor = openInEditor, resolveGithub = githubSource.resolveMany }) {
+  const app = express();
+  app.disable('x-powered-by');
+  app.use('/api', hostAllowlist(host));
+  app.use(express.json({ limit: '1mb' }));
+  app.post('/api/*splat', sameOriginOnly);
+
+  const sseClients = new Set();
+  function broadcast(event, data) {
+    const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const c of sseClients) c.write(payload);
+  }
+
+  app.get('/api/version', (_req, res) => {
+    res.json({ name: pkg.name, version: pkg.version });
+  });
+
+  app.get('/api/companion', (_req, res) => {
+    res.json({ name: pkg.name, version: pkg.version, session: SESSION_PATH });
+  });
+
+  app.get('/api/sessions', async (_req, res) => {
+    res.json({ sessions: await store.listSessions() });
+  });
+
+  app.post('/api/sessions/cleanup', async (req, res) => {
+    const keep = req.body?.keep;
+    if (!keep || typeof keep !== 'string') return res.status(400).json({ ok: false, error: 'missing keep' });
+    res.json({ ok: true, ...(await store.keepOnly(keep)) });
+  });
+
+  const githubMemo = new Map();
+  app.get('/api/introspect', async (req, res) => {
+    const sid = typeof req.query.session === 'string' && req.query.session ? req.query.session : null;
+    const snap = sid ? await store.readSnapshot(sid) : await store.readLatestSnapshot();
+    if (!snap) return res.status(404).json({ error: 'no snapshot found', sessionId: sid });
+    let githubSources = snap.sessionId ? githubMemo.get(snap.sessionId) : null;
+    if (!githubSources) {
+      githubSources = await resolveGithub(collectSourceRoots(snap));
+      if (snap.sessionId) githubMemo.set(snap.sessionId, githubSources);
+    }
+    res.json({ ...snap, githubSources });
+  });
+
+  app.post('/api/open', (req, res) => {
+    const target = req.body?.path;
+    if (!target || typeof target !== 'string') return res.status(400).json({ ok: false, error: 'missing path' });
+    const file = path.normalize(target);
+    if (!fs.existsSync(file)) return res.status(404).json({ ok: false, error: `path not found: ${file}` });
+    res.json({ ok: true, editor: openEditor(file), path: file });
+  });
+
+  // The extension in the live pi session applies the request; see setupRequestWatcher in extensions/inspect.ts.
+  app.post('/api/toggle', async (req, res) => {
+    const { action, resourceKind, path: target, scope } = req.body || {};
+    if (action !== 'enable' && action !== 'disable') return res.status(400).json({ ok: false, error: 'action must be enable or disable' });
+    if (!RESOURCE_KINDS.includes(resourceKind)) return res.status(400).json({ ok: false, error: 'invalid resourceKind' });
+    if (!target || typeof target !== 'string') return res.status(400).json({ ok: false, error: 'missing path' });
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    await writeJsonAtomic(path.join(inspectDir, 'requests', `${id}.json`), {
+      id, ts: Date.now(), action, resourceKind, path: target, scope: scope === 'project' ? 'project' : 'user',
+    });
+    res.json({ ok: true, id });
+  });
+
+  app.post('/api/focus', (req, res) => {
+    const session = typeof req.body?.session === 'string' ? req.body.session : null;
+    const delivered = sseClients.size;
+    if (delivered) broadcast('navigate', { session });
+    res.json({ delivered });
+  });
+
+  app.get('/api/events', (req, res) => {
+    res.set({ 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+    res.flushHeaders();
+    res.write(': hello\n\n');
+    sseClients.add(res);
+    req.on('close', () => sseClients.delete(res));
+  });
+
+  app.use('/api', (_req, res) => res.status(404).json({ error: 'not found' }));
+  app.use(express.static(PUBLIC_DIR));
+
+  app.use((err, _req, res, _next) => {
+    res.status(err.status || 500).json({ ok: false, error: err.message });
+  });
+
+  function closeClients() {
+    for (const c of sseClients) c.end();
+    sseClients.clear();
+  }
+
+  return { app, broadcast, closeClients };
+}
+
+module.exports = { createApp, SESSION_PATH };

package/lib/args.js

@@ -0,0 +1,30 @@
+'use strict';
+const { parseArgs } = require('node:util');
+
+const DEFAULT_PORT = 5462;
+const DEFAULT_HOST = '127.0.0.1';
+
+// Throws on unknown flags or a bad port; the caller prints the message and exits 1.
+function parseOptions(argv, env = process.env) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      port: { type: 'string' },
+      host: { type: 'string' },
+      open: { type: 'boolean' },
+      'no-open': { type: 'boolean' },
+      session: { type: 'string' },
+    },
+  });
+  const rawPort = values.port ?? (env.PORT || String(DEFAULT_PORT));
+  const port = /^\d+$/.test(rawPort) ? Number(rawPort) : NaN;
+  if (!(port >= 0 && port <= 65535)) throw new Error(`invalid port: ${rawPort}`);
+  return {
+    port,
+    host: values.host || DEFAULT_HOST,
+    open: Boolean(values.open && !values['no-open']),
+    session: values.session ?? null,
+  };
+}
+
+module.exports = { parseOptions };

package/lib/editor.js

@@ -0,0 +1,26 @@
+'use strict';
+const { spawn } = require('node:child_process');
+
+function editorCommand(env = process.env) {
+  return env.EDITOR || env.VISUAL || (process.platform === 'win32' ? 'code' : 'vi');
+}
+
+// Detached, so closing the dashboard server leaves the editor open.
+function openInEditor(file, env = process.env) {
+  const editor = editorCommand(env);
+  const isWin = process.platform === 'win32';
+  const [cmd, ...rest] = editor.split(/\s+/);
+  const args = [...rest, file];
+  // `code` is a .cmd shim on Windows, which only runs through a shell.
+  const child = spawn(cmd, isWin ? args.map((a) => `"${String(a).replace(/"/g, '\\"')}"`) : args, {
+    detached: true,
+    stdio: 'ignore',
+    shell: isWin,
+    windowsVerbatimArguments: isWin,
+  });
+  child.on('error', (err) => console.warn(`pi-inspect: open failed: ${err.message}`));
+  child.unref();
+  return editor;
+}
+
+module.exports = { openInEditor };