portmind-monorepo 0.1.0 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,48 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-06
+
+### Added
+- `@portmind/core`: AI `explain` feature - provider abstraction for Anthropic (`/v1/messages`) and OpenAI (`/v1/chat/completions`), selected via `ai.provider` config with no code changes needed to switch; explicit field allowlist enforcement (`buildExplainPayload`, only sends fields named in `ai.fields_sent`); cmdline secret/token redaction (`sanitizeCmdline`) before anything is sent; SQLite response cache (`ai_explanations` table) keyed by `(process_name, port)` so repeat queries don't re-call the API.
+- `@portmind/cli`: `portmind explain <port>` - opt-in, requires `ai.enabled: true` and an API key in `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`; fails with a clear config error (exit code `2`) rather than doing nothing if unconfigured.
+- `@portmind/web`: `POST /api/explain` endpoint; the dashboard's "Explain with AI" button now makes a real request instead of showing a disabled placeholder.
+- Web dashboard UX fixes: sticky header (title, filter toolbar, and column labels stay pinned while scrolling a long port list) and the detail panel is now a fixed slide-in panel from the right edge with a dimmed overlay, appearing instantly regardless of scroll position, instead of a block at the bottom of the page requiring a scroll to find. The panel now shows "Service name" and "Description" as two separate labeled fields.
+- Vitest coverage: cmdline sanitization patterns, allowlist field selection, provider request-shape verification (mocked `fetch`, exact URL/headers/body per each provider's documented API), cache get/set/overwrite, and the full `explainPort` orchestration (disabled, missing key, cache hit, cache miss - all mocked).
+
+### Known limitations
+- **AI explain has not been tested against a real API key.** Every test mocks the HTTP layer; the request shapes match each provider's documented API as of this writing, but end-to-end correctness against the actual Anthropic/OpenAI services is unverified.
+- The table's DESCRIPTION column and detail panel's "Description" field only populate for ports IANA has actually registered - most macOS system/app processes (e.g. rapportd, ControlCenter, Spotify) aren't registered services, so they correctly show "-" or, for genuinely coincidental port-number matches, an unrelated IANA description for that number.
+
+## [0.3.0] - 2026-09-06
+
+### Added
+- `@portmind/core`: real IANA known-port lookup - CSV fetched and verified directly from `iana.org`, parsed into 11,394 real entries, bundled as `packages/core/data/iana-cache.json` so lookups work fully offline. `PortEntry.knownService` is now populated for any port with an official registration (e.g. `5432` -> "PostgreSQL Database", `3306` -> "MySQL").
+- `@portmind/core`: real config file loader (`configLoader.ts`) - reads and deep-merges `~/.portmind/config.yaml` (user) and `.portmind.yaml` (project) over the built-in defaults. A config file that exists but fails to parse throws `ConfigError`, mapped to CLI exit code `2`. `known_ports.source: custom|both` + `custom_db_path` let a JSON file override or extend IANA (e.g. for internal services or dev-convention ports like Redis/MongoDB that IANA doesn't register).
+- `@portmind/cli`: `portmind config show` (prints the fully resolved config as JSON) and `portmind config path` (prints both config file locations and whether each exists).
+- `portmind.config.example.yaml` at repo root - copy-and-edit starting point for either config location.
+- `scanPorts()` in `core` now takes a `knownPorts` config parameter (defaulting to `DEFAULT_CONFIG.knownPorts`), and both CLI `list` and the web server's `/api/ports` load real config via `loadConfig()` instead of using the hardcoded default - this is the actual wiring point through which config file changes take effect.
+- Vitest coverage: IANA CSV parsing (quoted fields, Reserved/Unassigned filtering, non-tcp/udp transports), known-port lookup (iana/custom/both source modes, missing custom file handling), and config loading (defaults-only, project override merge, malformed-YAML error).
+
+### Known limitations
+- `known_ports.refresh_days` is not enforced - the bundled IANA cache is a one-time snapshot (fetched 2026-09-06), not auto-refreshed.
+- `history.retention_days` and `risk_rules.*` are defined in config but not yet consumed - history and risk flags aren't implemented.
+- `logging.audit_log` is defined but nothing writes to it yet - there's no `free`/`explain` command to audit.
+
+## [0.2.0] - 2026-09-06
+
+### Added
+- `@portmind/web`: local-only web dashboard (Phase 8) - plain Node `http` server bound to `127.0.0.1`, `GET /api/ports` returning the same `PortEntry[]` JSON as `portmind list --json`, and a static vanilla HTML/JS page (no framework, no build step) with a sortable/filterable table and a row-click detail panel.
+- `@portmind/cli`: `portmind web` command (`--port`, `--no-open`) that starts the dashboard and opens the default browser.
+- Vitest coverage for the web server: page route, API route, and 404 handling.
+
+### Fixed
+- Root `package.json` (published to npm as `portmind-monorepo`) was missing `license` and `keywords` - added, along with matching metadata already present on the scoped packages.
+
+### Known limitations
+- The web dashboard's Docker-only/unusual filters have nothing to filter yet, since Docker cross-reference, history, and risk flags aren't implemented. Its "Explain with AI" button is a disabled placeholder pending Phase 9 (AI `explain`).
+- `portmind-monorepo` on npm still has no `bin` field - it is not an installable CLI. The real CLI package, `@portmind/cli`, has not been published.
+
 ## [0.1.0] - 2026-09-06
 
 ### Added

package/README.md

@@ -1,12 +1,12 @@
 # portmind
 
-[![npm version](https://img.shields.io/npm/v/%40portmind%2Fcli.svg)](https://www.npmjs.com/package/@portmind/cli)
+[![npm version](https://img.shields.io/npm/v/portmind-monorepo.svg)](https://www.npmjs.com/package/portmind-monorepo)
 [![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-Local-first CLI that scans listening ports on your machine, enriches them with process/Docker/IANA detail, remembers what *normally* runs on each port, and flags what's unusual — no cloud, no telemetry, no background AI calls.
+Local-first CLI + web dashboard that scans listening ports on your machine, enriches them with process/Docker/IANA detail, remembers what *normally* runs on each port, and flags what's unusual — no cloud, no telemetry, no background AI calls.
 
-> The npm badge above will show "not found" until `@portmind/cli` is actually published. Nothing in this repo has been published yet.
+> `portmind-monorepo` is published on npm (see the badge above), but it has no `bin` field — installing it does not give you a `portmind` command. `@portmind/cli`, the package that actually would, is not published yet.
 
 ## Status
 
@@ -15,8 +15,13 @@ Local-first CLI that scans listening ports on your machine, enriches them with p
 - Each result is enriched with process command line, working directory, and start time (`ps` + `lsof -d cwd`)
 - `--range <min-max>`, `--docker-only`, `--unusual`, and `--json` filters/output modes
 - Table and JSON output share one `PortEntry` type, defined once in `@portmind/core`
+- `portmind web` starts a local-only dashboard (`127.0.0.1`, plain HTML/JS, no framework, no build step) serving the same data as `portmind list --json` over `GET /api/ports`, with a sortable/filterable table and a row-click detail panel
+- Real known-port descriptions via the official IANA Service Name and Port Number Registry (11,394 entries bundled, fetched and verified from `iana.org` — e.g. port 5432 shows "PostgreSQL Database", not a placeholder)
+- A real, working config file loader — `~/.portmind/config.yaml` (user) and `.portmind.yaml` (project) are both read and merged over the defaults; `portmind config show`/`config path` expose the resolved result and file locations
+- `known_ports.source: custom` or `both` in config lets you point at your own JSON file to override or add service descriptions IANA doesn't have (internal services, dev conventions like Redis/MongoDB that aren't officially IANA-registered)
+- AI `explain` (opt-in, off by default) — `portmind explain <port>` and the web dashboard's "Explain with AI" button both make a real call to Anthropic or OpenAI (your choice, via `ai.provider`), sending only the explicit field allowlist (never full env vars or file contents), with cmdline secrets/tokens redacted first and results cached in SQLite so repeat queries don't re-call the API. **Not tested against a live API key** — the request-construction logic (allowlist, sanitization, exact payload shape) is unit-tested with a mocked HTTP layer, but no real call to Anthropic/OpenAI has been made to confirm end-to-end correctness.
 
-**Not implemented yet** (see [Next steps](#next-steps)): Docker cross-reference, IANA known-port descriptions, local history/"usual" detection, risk flags, `watch`/`free`/`explain`/`history`/`ssh`/`web`/`tui`/`config` commands, and the YAML config loader. Until those land, every `PortEntry.docker`, `.knownService`, and `.riskFlags` will be empty, and `.history.usual` is always `true`.
+**Not implemented yet** (see [Next steps](#next-steps)): Docker cross-reference, local history/"usual" detection, risk flags, `watch`/`free`/`history`/`ssh`/`tui` commands. Until those land, every `PortEntry.docker` and `.riskFlags` will be empty, and `.history.usual` is always `true` — so the web dashboard's Docker/unusual filters currently have nothing to filter.
 
 See [CHANGELOG.md](./CHANGELOG.md) for a dated record of what shipped when.
 
@@ -55,20 +60,47 @@ Example output:
 ```
 PORT   PROTO  PROCESS       PID     DOCKER  USUAL  NOTE
 3000   tcp    node          41822   -       yes    /Users/you/Projects/react-dashboard
-5432   tcp    postgres      1758    -       yes    /opt/homebrew/var/postgresql@14
+5432   tcp    postgres      1758    -       yes    PostgreSQL Database
 ```
 
 **Exit codes:** `0` success, `1` scan error, `2` config error.
 
-Planned commands not yet implemented: `watch`, `free`, `explain`, `history`, `ssh <host> list|check`, `web`, `tui`, `config show|path`.
+### Web dashboard
+
+```bash
+portmind web                   # starts on http://127.0.0.1:4400 and opens your browser
+portmind web --port 4401       # use a different port for the dashboard itself
+portmind web --no-open         # don't open the browser automatically
+```
+
+Why a plain server + vanilla JS instead of a framework: the dashboard is three routes (the page, `/api/ports`, `/api/explain`), it never leaves your machine except for the explicit opt-in AI call, and there's no build pipeline to maintain — consistent with the "local-first, no telemetry" design of the rest of the tool. The page polls `/api/ports` on load and on manual refresh (or a 5-second auto-refresh you opt into). Clicking a row opens a fixed panel from the right edge of the screen (with a dimmed overlay behind it) showing full detail — no scrolling required regardless of where in the table you clicked. Its "Explain with AI" button only fires `/api/explain` when clicked, never automatically.
+
+### AI explain
+
+```bash
+portmind explain 5432   # runs AI deep-search for whatever is currently on port 5432
+```
+
+Requires `ai.enabled: true` in config and an API key in the matching environment variable (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY` depending on `ai.provider` — never put the key in the config file itself). Disabled by default; both the CLI command and the web button fail with a clear config error (exit code `2` for the CLI) rather than silently doing nothing if it's not configured. Results are cached in SQLite keyed by `(process_name, port)`, so asking about the same shape of thing twice doesn't re-call the API.
+
+### Config
+
+```bash
+portmind config show   # print the fully resolved config (defaults + user + project merged), as JSON
+portmind config path   # print ~/.portmind/config.yaml and ./.portmind.yaml, and whether each exists
+```
+
+Copy [portmind.config.example.yaml](./portmind.config.example.yaml) to `~/.portmind/config.yaml` or `./.portmind.yaml` to change behavior — only the keys you include override the defaults, anything omitted falls back. Malformed YAML in a config file that exists is a hard error (exit code `2`), not silently ignored.
+
+Planned commands not yet implemented: `watch`, `free`, `history`, `ssh <host> list|check`, `tui`.
 
 ## Storage
 
-History will be stored locally in a SQLite database at `~/.portmind/portmind.db` (configurable) once the history feature (Phase 4) lands. Nothing leaves the machine unless you explicitly run `portmind explain <port>` with AI enabled in config, and even then only an explicit allowlist of fields is sent — never full environment variables or file contents.
+History will be stored locally in a SQLite database at `~/.portmind/portmind.db` (configurable) once the history feature (Phase 4) lands - the same db file already holds the `ai_explanations` cache table today. Nothing leaves the machine unless you explicitly run `portmind explain <port>` (or click "Explain with AI") with AI enabled in config, and even then only an explicit allowlist of fields is sent — never full environment variables or file contents, and cmdline values are scanned for secret/token-shaped substrings and redacted before sending.
 
 ## Configuration
 
-Not implemented yet — there is no config loader, and `~/.portmind/config.yaml` / `.portmind.yaml` are not read. The schema below is the target design (resolution order: built-in defaults → `~/.portmind/config.yaml` → `.portmind.yaml` in the current directory, each layer overriding the previous):
+Real and working. Resolution order (later overrides earlier, and only the keys you actually set are overridden - everything else falls back): built-in defaults → `~/.portmind/config.yaml` (user) → `.portmind.yaml` in the current directory (project). See [portmind.config.example.yaml](./portmind.config.example.yaml) for a copy-and-edit starting point.
 
 ```yaml
 scan:
@@ -114,7 +146,7 @@ logging:
   audit_log: false
 ```
 
-The equivalent TypeScript shape (`PortmindConfig`) and its defaults already exist in [packages/core/src/config.ts](./packages/core/src/config.ts) — only the file-loading/merge logic is missing.
+The TypeScript shape (`PortmindConfig`), its defaults, and the loader/merge logic live in [packages/core/src/config.ts](./packages/core/src/config.ts) and [packages/core/src/configLoader.ts](./packages/core/src/configLoader.ts). Not yet wired to config: `history.retention_days` (history isn't implemented), `risk_rules.*` (risk flags aren't implemented), `known_ports.refresh_days` (the bundled IANA cache doesn't auto-refresh yet - refreshing it means re-fetching the CSV and regenerating `packages/core/data/iana-cache.json`, which isn't automated).
 
 ## Architecture
 
@@ -123,7 +155,7 @@ packages/
 ├── core/   # scanning, enrichment, data model, config — no UI, no AI dependency
 ├── cli/    # table/JSON output over @portmind/core (implemented)
 ├── tui/    # live terminal dashboard — not started
-├── web/    # local HTML dashboard — not started
+├── web/    # local HTML dashboard (implemented: /api/ports + static page)
 └── ai/     # optional AI deep-search plugin — not started
 ```
 
@@ -133,16 +165,17 @@ packages/
 
 Remaining phases, in build order:
 
-1. **IANA enrichment** — fetch/cache the official IANA Service Name and Port Number Registry, populate `PortEntry.knownService`
-2. **History and "usual" detection** — SQLite `observations`/`port_fingerprints` tables, `history <port>` command
-3. **Docker cross-reference** — match `docker ps` output against scanned ports, populate `PortEntry.docker`
-4. **Risk flags** — `bound_all_interfaces`, `unsigned_binary`, `no_known_service`, each independently configurable
-5. **TUI** (`ink` or `blessed` — undecided) — live table with inline `explain`/`free`
-6. **Web dashboard** — local-only HTTP server, `/api/ports`, static HTML/JS frontend
-7. **AI `explain`** (opt-in) — provider abstraction, explicit field allowlist, response caching
-8. **SSH remote support** — `ssh_hosts` config, same `PortEntry` shape with `host` set to the remote name
-9. **Config system** — YAML loader/merge (defaults → user → project), `config show`/`config path`, audit logging for `free`/`explain`
-10. **Polish** — full `--help` text, packaging for `npm install -g @portmind/cli`
+1. **History and "usual" detection** — SQLite `observations`/`port_fingerprints` tables, `history <port>` command
+2. **Docker cross-reference** — match `docker ps` output against scanned ports, populate `PortEntry.docker`
+3. **Risk flags** — `bound_all_interfaces`, `unsigned_binary`, `no_known_service`, each independently configurable
+4. **TUI** (`ink` or `blessed` — undecided) — live table with inline `explain`/`free`
+5. **SSH remote support** — `ssh_hosts` config, same `PortEntry` shape with `host` set to the remote name
+6. **Audit logging** — log every `free`/`explain` action per `logging.audit_log`
+7. **IANA cache auto-refresh** — automate re-fetching the CSV on `known_ports.refresh_days`, rather than the current bundled-once snapshot
+8. **Polish** — full `--help` text, packaging for `npm install -g @portmind/cli`
+9. **AI explain: real end-to-end verification** — the feature is built and unit-tested with a mocked HTTP layer, but has never actually been called against Anthropic or OpenAI with a real API key. Verifying that happens whenever a key becomes available to test with.
+
+Web dashboard, IANA enrichment, the config file loader, and AI `explain` (untested end-to-end - see above) are done — see [Status](#status).
 
 Two decisions still open: TUI library (`ink` vs `blessed`), and whether `free` on a Docker-backed port needs anything beyond the interactive stop/kill/cancel prompt already agreed on.
 

package/package.json

@@ -1,7 +1,26 @@
 {
   "name": "portmind-monorepo",
-  "version": "0.1.0",
-  "description": "portmind - local-first port scanning, enrichment and history tool",
+  "version": "0.3.1",
+  "description": "Local-first CLI + web dashboard that scans listening ports, enriches them with process/Docker/IANA detail, and remembers what normally runs where.",
+  "keywords": [
+    "cli",
+    "port",
+    "port-scanner",
+    "lsof",
+    "docker",
+    "devtools",
+    "dev-server",
+    "port-conflict",
+    "eaddrinuse"
+  ],
+  "homepage": "https://github.com/psandis/portmind#readme",
+  "bugs": "https://github.com/psandis/portmind/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/psandis/portmind.git"
+  },
+  "license": "MIT",
+  "author": "Petri Sandholm",
   "packageManager": "pnpm@9.0.0",
   "engines": {
     "node": ">=22"

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portmind/cli",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "Local-first CLI that scans listening ports, enriches them with process/Docker/IANA detail, and remembers what normally runs where.",
   "keywords": [
     "cli",
@@ -41,6 +41,7 @@
   },
   "dependencies": {
     "@portmind/core": "workspace:*",
+    "@portmind/web": "workspace:*",
     "commander": "^15.0.0"
   },
   "devDependencies": {

package/packages/cli/src/index.ts

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { DEFAULT_CONFIG, scanPorts, type PortEntry } from "@portmind/core";
+import { execFile } from "node:child_process";
+import {
+  ConfigError,
+  explainPort,
+  loadConfig,
+  resolveConfigPaths,
+  scanPorts,
+  type PortEntry,
+} from "@portmind/core";
+import { createWebServer } from "@portmind/web";
 import { renderTable } from "./renderTable.js";
 
 const program = new Command();
 
-program.name("portmind").description("Local-first port scanning, enrichment and history tool").version("0.1.0");
+program.name("portmind").description("Local-first port scanning, enrichment and history tool").version("0.3.1");
 
 interface ListOptions {
   range?: string;
@@ -24,7 +33,8 @@ program
   .action(async (options: ListOptions) => {
     try {
       const range = parseRange(options.range);
-      let entries = await scanPorts({ includeUdp: DEFAULT_CONFIG.scan.includeUdp });
+      const config = await loadConfig();
+      let entries = await scanPorts({ includeUdp: config.scan.includeUdp }, config.knownPorts);
 
       if (range) {
         entries = entries.filter((e) => e.port >= range.min && e.port <= range.max);
@@ -44,8 +54,109 @@ program
         console.log(renderTable(entries));
       }
     } catch (error) {
-      console.error(`portmind list: scan failed - ${(error as Error).message}`);
-      process.exitCode = 1;
+      if (error instanceof ConfigError) {
+        console.error(`portmind list: config error - ${error.message}`);
+        process.exitCode = 2;
+      } else {
+        console.error(`portmind list: scan failed - ${(error as Error).message}`);
+        process.exitCode = 1;
+      }
+    }
+  });
+
+interface WebOptions {
+  port: string;
+  open: boolean;
+}
+
+program
+  .command("web")
+  .description("Start the local web dashboard")
+  .option("--port <port>", "port for the dashboard itself", "4400")
+  .option("--no-open", "don't open the browser automatically")
+  .action((options: WebOptions) => {
+    const port = Number.parseInt(options.port, 10);
+    if (Number.isNaN(port) || port < 1 || port > 65535) {
+      console.error(`portmind web: invalid --port "${options.port}"`);
+      process.exitCode = 2;
+      return;
+    }
+
+    createWebServer({ port });
+    const url = `http://127.0.0.1:${port}`;
+    console.log(`portmind web: dashboard running at ${url}`);
+
+    if (options.open) {
+      const opener = process.platform === "darwin" ? "open" : "xdg-open";
+      execFile(opener, [url], (error) => {
+        if (error) {
+          console.error(`portmind web: could not open browser automatically (${error.message})`);
+        }
+      });
+    }
+  });
+
+program
+  .command("explain")
+  .description("Run AI deep-search for a specific port (opt-in, requires ai.enabled: true)")
+  .argument("<port>", "port number to explain")
+  .action(async (portArg: string) => {
+    const port = Number.parseInt(portArg, 10);
+    if (Number.isNaN(port)) {
+      console.error(`portmind explain: invalid port "${portArg}"`);
+      process.exitCode = 2;
+      return;
+    }
+
+    try {
+      const resolvedConfig = await loadConfig();
+      const entries = await scanPorts({ includeUdp: resolvedConfig.scan.includeUdp }, resolvedConfig.knownPorts);
+      const entry = entries.find((e) => e.port === port);
+      if (!entry) {
+        console.error(`portmind explain: nothing is currently listening on port ${port}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const explanation = await explainPort(entry, resolvedConfig);
+      console.log(explanation);
+    } catch (error) {
+      if (error instanceof ConfigError) {
+        console.error(`portmind explain: ${error.message}`);
+        process.exitCode = 2;
+      } else {
+        console.error(`portmind explain: failed - ${(error as Error).message}`);
+        process.exitCode = 1;
+      }
+    }
+  });
+
+const config = program.command("config").description("Inspect resolved portmind configuration");
+
+config
+  .command("show")
+  .description("Print the resolved config (defaults + user + project merged)")
+  .action(async () => {
+    try {
+      const resolved = await loadConfig();
+      console.log(JSON.stringify(resolved, null, 2));
+    } catch (error) {
+      console.error(`portmind config show: ${(error as Error).message}`);
+      process.exitCode = 2;
+    }
+  });
+
+config
+  .command("path")
+  .description("Print the path(s) to the active config file(s) and whether they exist")
+  .action(async () => {
+    try {
+      const paths = await resolveConfigPaths();
+      console.log(`user:    ${paths.user}${paths.userExists ? "" : " (not found)"}`);
+      console.log(`project: ${paths.project}${paths.projectExists ? "" : " (not found)"}`);
+    } catch (error) {
+      console.error(`portmind config path: ${(error as Error).message}`);
+      process.exitCode = 2;
     }
   });