portmind-monorepo 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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,12 @@ 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)
 
-**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`/`explain`/`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,12 +59,31 @@ 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 two routes (the page, and `/api/ports`), it never leaves your machine, 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 expands full detail including an "Explain with AI" button that's currently a disabled placeholder, since AI `explain` (Phase 9) isn't built yet.
+
+### 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`, `explain`, `history`, `ssh <host> list|check`, `tui`.
 
 ## Storage
 
@@ -68,7 +91,7 @@ History will be stored locally in a SQLite database at `~/.portmind/portmind.db`
 
 ## 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 +137,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 +146,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 +156,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. **AI `explain`** (opt-in) — provider abstraction, explicit field allowlist, response caching (the web dashboard's "Explain with AI" button is wired up but disabled until this exists)
+6. **SSH remote support** — `ssh_hosts` config, same `PortEntry` shape with `host` set to the remote name
+7. **Audit logging** — log every `free`/`explain` action per `logging.audit_log`
+8. **IANA cache auto-refresh** — automate re-fetching the CSV on `known_ports.refresh_days`, rather than the current bundled-once snapshot
+9. **Polish** — full `--help` text, packaging for `npm install -g @portmind/cli`
+
+Web dashboard, IANA enrichment, and the config file loader (were phases 6, 1, and 11 in the original spec numbering) 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.0",
+  "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.0",
   "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,13 @@
 #!/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, 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.0");
 
 interface ListOptions {
   range?: string;
@@ -24,7 +26,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 +47,74 @@ 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})`);
+        }
+      });
+    }
+  });
+
+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;
     }
   });