portmind-monorepo 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-06
+
+### Added
+- Monorepo scaffold (`packages/core`, `packages/cli`) with pnpm workspaces, shared TypeScript config, and Biome for lint/format.
+- `@portmind/core`: `PortEntry` data shape and `PortmindConfig` schema with built-in defaults, matching the spec exactly (AI opt-in and off by default, explicit AI field allowlist).
+- `@portmind/core`: real port scanner (Phase 1) - `lsof`-based TCP/UDP listening socket discovery with process enrichment (cmdline, cwd, start time via `ps` and `lsof -d cwd`), deduplicated across dual-stack/duplicate file descriptors.
+- `@portmind/cli`: `portmind list` now runs a real scan and renders a table or `--json`, with working `--range`, `--docker-only`, and `--unusual` filters.
+- Vitest test suite: `DEFAULT_CONFIG` invariants, `lsof` field-output parsing (mocked, no real sockets required), socket deduplication, table rendering, and an end-to-end CLI smoke test.
+- README and this CHANGELOG.
+- MIT `LICENSE`, and publish-ready `package.json` metadata (description, keywords, repository, author, `publishConfig.access: public` for both scoped packages) for an eventual `pnpm publish` of `@portmind/core` and `@portmind/cli`.
+
+### Changed
+- Upgraded all dependencies to latest major versions: `typescript` 7.0.2, `vitest` 5.0.0, `commander` 15.0.0, `better-sqlite3` 13.0.3, `@types/node` 26.4.1, `@types/better-sqlite3` 9.6.0. Added explicit `vite`/`esbuild` devDependencies to satisfy vitest 5's peer requirements. Required adding `"types": ["node"]` to the base tsconfig since TypeScript 7 no longer auto-includes `@types/node`.
+
+### Known limitations
+- Docker cross-reference, IANA known-port lookup, local history/"usual" detection, and risk flags are not implemented yet (Phases 3-6 of the build plan) - those fields on `PortEntry` are currently always `null`/empty/`true`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Petri Sandholm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# portmind
+
+[![npm version](https://img.shields.io/npm/v/%40portmind%2Fcli.svg)](https://www.npmjs.com/package/@portmind/cli)
+[![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.
+
+> The npm badge above will show "not found" until `@portmind/cli` is actually published. Nothing in this repo has been published yet.
+
+## Status
+
+**Working today:**
+- `portmind list` runs a real scan (`lsof`-based) of TCP and UDP listening sockets on macOS/Linux
+- 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`
+
+**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`.
+
+See [CHANGELOG.md](./CHANGELOG.md) for a dated record of what shipped when.
+
+## Requirements
+
+- Node.js 22+
+- pnpm 9+
+- macOS or Linux — `lsof` must be on `$PATH` (this is the only scan backend implemented so far; Linux's `ss` is not wired up yet despite being mentioned in the original design)
+- Docker CLI (`docker`) optional — not yet used, but scans are designed to degrade gracefully once Docker cross-referencing is added
+
+## Install (development)
+
+```bash
+pnpm install
+pnpm build
+```
+
+There's no published package yet, so there's nothing to `npm install -g`. Run the CLI directly from this repo:
+
+```bash
+node packages/cli/dist/index.js list
+```
+
+## Usage
+
+```bash
+portmind list                    # full table, all listening ports on localhost
+portmind list --range 3000-9000  # filter by port range
+portmind list --docker-only      # only Docker-backed ports (no-op until Docker cross-reference ships)
+portmind list --unusual          # only ports flagged unusual or risky (no-op until history/risk flags ship)
+portmind list --json             # machine-readable output for scripting/CI
+```
+
+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
+```
+
+**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`.
+
+## 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.
+
+## 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):
+
+```yaml
+scan:
+  interval_seconds: 5
+  include_udp: true
+  docker: true
+  ssh_hosts: []
+
+known_ports:
+  source: iana              # iana | custom | both
+  custom_db_path: null
+  refresh_days: 30
+
+history:
+  enabled: true
+  db_path: ~/.portmind/portmind.db
+  retention_days: 180
+
+risk_rules:
+  flag_bound_all_interfaces: true
+  flag_unsigned_binary: true     # macOS only, no-op elsewhere
+  flag_no_known_service: true
+
+ai:
+  enabled: false                  # opt-in, off by default
+  provider: anthropic             # anthropic | openai | none
+  model: claude-sonnet-4-6
+  trigger: manual
+  fields_sent:                    # explicit allowlist - nothing outside this list is ever sent
+    - process_name
+    - cmdline
+    - port
+    - protocol
+    - docker_image
+  cmdline_sanitization: true
+
+output:
+  default_format: table           # table | json
+  color: auto                     # auto | always | never
+
+logging:
+  level: info                     # debug | info | warn | error
+  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.
+
+## Architecture
+
+```
+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
+└── ai/     # optional AI deep-search plugin — not started
+```
+
+`core` has zero UI and zero AI dependencies. `cli`, `tui`, and `web` are meant to be thin renderers over the same `PortEntry[]` shape — no duplicated scanning logic between them.
+
+## Next steps
+
+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`
+
+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.
+
+## Development
+
+```bash
+pnpm test     # run all package test suites (Vitest)
+pnpm lint     # Biome check
+pnpm format   # Biome format --write
+```
+
+Tests live in each package's `tests/` directory, not alongside source.
+
+## License
+
+[MIT](./LICENSE)

package/biome.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "organizeImports": { "enabled": true },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  },
+  "files": {
+    "ignore": ["dist/**", "node_modules/**", "data/iana-cache.json"]
+  }
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "portmind-monorepo",
+  "version": "0.1.0",
+  "description": "portmind - local-first port scanning, enrichment and history tool",
+  "packageManager": "pnpm@9.0.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "pnpm -r build",
+    "test": "pnpm -r test",
+    "lint": "biome check .",
+    "format": "biome format --write ."
+  }
+}

package/packages/cli/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@portmind/cli",
+  "version": "0.1.0",
+  "description": "Local-first CLI 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",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "author": "Petri Sandholm",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "portmind": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@portmind/core": "workspace:*",
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "esbuild": "^0.28.2",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.2",
+    "vitest": "^5.0.0"
+  }
+}

package/packages/cli/src/index.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { DEFAULT_CONFIG, scanPorts, type PortEntry } from "@portmind/core";
+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");
+
+interface ListOptions {
+  range?: string;
+  dockerOnly?: boolean;
+  unusual?: boolean;
+  json?: boolean;
+}
+
+program
+  .command("list")
+  .description("List all listening ports on localhost")
+  .option("--range <range>", "filter by port range, e.g. 3000-9000")
+  .option("--docker-only", "only show Docker-backed ports")
+  .option("--unusual", "only show ports flagged unusual or risky")
+  .option("--json", "output machine-readable JSON")
+  .action(async (options: ListOptions) => {
+    try {
+      const range = parseRange(options.range);
+      let entries = await scanPorts({ includeUdp: DEFAULT_CONFIG.scan.includeUdp });
+
+      if (range) {
+        entries = entries.filter((e) => e.port >= range.min && e.port <= range.max);
+      }
+      if (options.dockerOnly) {
+        entries = entries.filter((e) => e.docker !== null);
+      }
+      if (options.unusual) {
+        entries = entries.filter((e) => !e.history.usual || e.riskFlags.length > 0);
+      }
+
+      entries.sort((a, b) => a.port - b.port);
+
+      if (options.json) {
+        console.log(JSON.stringify(entries satisfies PortEntry[], null, 2));
+      } else {
+        console.log(renderTable(entries));
+      }
+    } catch (error) {
+      console.error(`portmind list: scan failed - ${(error as Error).message}`);
+      process.exitCode = 1;
+    }
+  });
+
+function parseRange(range: string | undefined): { min: number; max: number } | null {
+  if (!range) return null;
+  const match = range.match(/^(\d+)-(\d+)$/);
+  if (!match) {
+    throw new Error(`invalid --range "${range}", expected format like 3000-9000`);
+  }
+  const min = Number.parseInt(match[1] as string, 10);
+  const max = Number.parseInt(match[2] as string, 10);
+  if (min > max) {
+    throw new Error(`invalid --range "${range}", min must be <= max`);
+  }
+  return { min, max };
+}
+
+program.parseAsync(process.argv);

package/packages/cli/src/renderTable.ts

@@ -0,0 +1,34 @@
+import type { PortEntry } from "@portmind/core";
+
+const COLUMNS = ["PORT", "PROTO", "PROCESS", "PID", "DOCKER", "USUAL", "NOTE"] as const;
+
+export function renderTable(entries: PortEntry[]): string {
+  if (entries.length === 0) {
+    return "No listening ports found.";
+  }
+
+  const rows = entries.map((entry) => [
+    String(entry.port),
+    entry.protocol,
+    entry.processName ?? "-",
+    entry.pid !== null ? String(entry.pid) : "-",
+    entry.docker?.containerName ?? "-",
+    entry.history.usual ? "yes" : "NO",
+    noteFor(entry),
+  ]);
+
+  const widths = COLUMNS.map((col, i) =>
+    Math.max(col.length, ...rows.map((row) => (row[i] ?? "").length)),
+  );
+
+  const formatRow = (cells: string[]) =>
+    cells.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  ").trimEnd();
+
+  return [formatRow([...COLUMNS]), ...rows.map(formatRow)].join("\n");
+}
+
+function noteFor(entry: PortEntry): string {
+  if (entry.knownService) return entry.knownService.description;
+  if (entry.cwd) return entry.cwd;
+  return "-";
+}

package/packages/cli/tests/cli.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const cliEntry = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "dist", "index.js");
+
+describe("portmind list (real scan, end to end)", () => {
+  it("exits 0 and prints a table with a PORT header", () => {
+    const output = execFileSync("node", [cliEntry, "list"], { encoding: "utf-8" });
+    expect(output).toContain("PORT");
+  });
+
+  it("--json produces valid JSON matching the PortEntry shape", () => {
+    const output = execFileSync("node", [cliEntry, "list", "--json"], { encoding: "utf-8" });
+    const parsed = JSON.parse(output);
+    expect(Array.isArray(parsed)).toBe(true);
+    if (parsed.length > 0) {
+      expect(parsed[0]).toHaveProperty("port");
+      expect(parsed[0]).toHaveProperty("protocol");
+    }
+  });
+
+  it("rejects a malformed --range", () => {
+    expect(() => execFileSync("node", [cliEntry, "list", "--range", "bogus"], { stdio: "pipe" })).toThrow();
+  });
+});

package/packages/cli/tests/renderTable.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import type { PortEntry } from "@portmind/core";
+import { renderTable } from "../src/renderTable.js";
+
+function makeEntry(overrides: Partial<PortEntry> = {}): PortEntry {
+  return {
+    host: "localhost",
+    port: 3000,
+    protocol: "tcp",
+    bindAddress: "127.0.0.1",
+    pid: 41822,
+    processName: "node",
+    cmdline: "node server.js",
+    cwd: "~/Projects/react-dashboard",
+    startedAt: null,
+    docker: null,
+    knownService: null,
+    history: { usual: true, observationCount: 5, firstSeen: null, usualOccupant: null },
+    riskFlags: [],
+    aiExplanation: null,
+    ...overrides,
+  };
+}
+
+describe("renderTable", () => {
+  it("reports no listening ports when the list is empty", () => {
+    expect(renderTable([])).toBe("No listening ports found.");
+  });
+
+  it("includes the header and each port's core fields", () => {
+    const output = renderTable([makeEntry()]);
+    expect(output).toContain("PORT");
+    expect(output).toContain("3000");
+    expect(output).toContain("node");
+    expect(output).toContain("41822");
+  });
+
+  it("flags unusual entries as NO instead of yes", () => {
+    const output = renderTable([makeEntry({ history: { usual: false, observationCount: 1, firstSeen: null, usualOccupant: "node" } })]);
+    expect(output).toContain("NO");
+  });
+
+  it("shows the docker container name when present", () => {
+    const output = renderTable([
+      makeEntry({ docker: { containerId: "abc123", containerName: "pg-container", image: "postgres:16" } }),
+    ]);
+    expect(output).toContain("pg-container");
+  });
+});

package/packages/cli/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["tests", "dist"]
+}

package/packages/core/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@portmind/core",
+  "version": "0.1.0",
+  "description": "portmind core - scanning, enrichment, data model, config, history. No UI, no AI dependency.",
+  "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",
+    "directory": "packages/core"
+  },
+  "license": "MIT",
+  "author": "Petri Sandholm",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "better-sqlite3": "^13.0.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.4.1",
+    "esbuild": "^0.28.2",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.2",
+    "vitest": "^5.0.0"
+  }
+}

package/packages/core/src/config.ts

@@ -0,0 +1,93 @@
+/**
+ * Config schema and built-in defaults. Resolution order (lowest to highest
+ * precedence): these defaults -> ~/.portmind/config.yaml -> ./.portmind.yaml.
+ * Loader/merge logic lands in a later phase; this module only defines the
+ * shape so every other module can depend on a stable, typed config.
+ */
+export interface PortmindConfig {
+  scan: {
+    intervalSeconds: number;
+    includeUdp: boolean;
+    docker: boolean;
+    sshHosts: SshHostConfig[];
+  };
+  knownPorts: {
+    source: "iana" | "custom" | "both";
+    customDbPath: string | null;
+    refreshDays: number;
+  };
+  history: {
+    enabled: boolean;
+    dbPath: string;
+    retentionDays: number;
+  };
+  riskRules: {
+    flagBoundAllInterfaces: boolean;
+    flagUnsignedBinary: boolean;
+    flagNoKnownService: boolean;
+  };
+  ai: {
+    enabled: boolean;
+    provider: "anthropic" | "openai" | "none";
+    model: string;
+    trigger: "manual";
+    fieldsSent: AiField[];
+    cmdlineSanitization: boolean;
+  };
+  output: {
+    defaultFormat: "table" | "json";
+    color: "auto" | "always" | "never";
+  };
+  logging: {
+    level: "debug" | "info" | "warn" | "error";
+    auditLog: boolean;
+  };
+}
+
+export interface SshHostConfig {
+  name: string;
+  host: string;
+  user: string;
+}
+
+export type AiField = "process_name" | "cmdline" | "port" | "protocol" | "docker_image";
+
+export const DEFAULT_CONFIG: PortmindConfig = {
+  scan: {
+    intervalSeconds: 5,
+    includeUdp: true,
+    docker: true,
+    sshHosts: [],
+  },
+  knownPorts: {
+    source: "iana",
+    customDbPath: null,
+    refreshDays: 30,
+  },
+  history: {
+    enabled: true,
+    dbPath: "~/.portmind/portmind.db",
+    retentionDays: 180,
+  },
+  riskRules: {
+    flagBoundAllInterfaces: true,
+    flagUnsignedBinary: true,
+    flagNoKnownService: true,
+  },
+  ai: {
+    enabled: false,
+    provider: "anthropic",
+    model: "claude-sonnet-4-6",
+    trigger: "manual",
+    fieldsSent: ["process_name", "cmdline", "port", "protocol", "docker_image"],
+    cmdlineSanitization: true,
+  },
+  output: {
+    defaultFormat: "table",
+    color: "auto",
+  },
+  logging: {
+    level: "info",
+    auditLog: false,
+  },
+};

package/packages/core/src/index.ts

@@ -0,0 +1,4 @@
+export type { PortEntry, RiskFlag } from "./types.js";
+export type { PortmindConfig, SshHostConfig, AiField } from "./config.js";
+export { DEFAULT_CONFIG } from "./config.js";
+export { scanPorts, type ScanOptions } from "./scan/index.js";

package/packages/core/src/scan/enrichProcess.ts

@@ -0,0 +1,109 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { PortEntry } from "../types.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface ProcessDetail {
+  cmdline: string;
+  startedAt: string;
+}
+
+/**
+ * Batch-enriches a set of PIDs with command line + process start time (via
+ * `ps`) and working directory (via `lsof -d cwd`). Both commands are called
+ * once per scan with a comma-separated PID list, not once per PID.
+ *
+ * Best-effort: a PID that has already exited between the scan and this call,
+ * or any command failure, is simply absent from the returned maps - callers
+ * must treat missing enrichment as "unknown", never as fatal.
+ */
+export async function enrichProcesses(
+  pids: number[],
+): Promise<{ details: Map<number, ProcessDetail>; cwds: Map<number, string> }> {
+  const uniquePids = [...new Set(pids)].filter((pid) => pid > 0 && pid <= 4194304);
+  if (uniquePids.length === 0) {
+    return { details: new Map(), cwds: new Map() };
+  }
+
+  const [details, cwds] = await Promise.all([fetchProcessDetails(uniquePids), fetchCwds(uniquePids)]);
+  return { details, cwds };
+}
+
+async function fetchProcessDetails(pids: number[]): Promise<Map<number, ProcessDetail>> {
+  const result = new Map<number, ProcessDetail>();
+  const output = await run("ps", ["-o", "pid=,lstart=,command=", "-p", pids.join(",")]);
+  if (!output) return result;
+
+  for (const line of output.split("\n")) {
+    const trimmed = line.trimStart();
+    if (trimmed.length === 0) continue;
+
+    // Format: "<pid> <weekday> <month> <day> <time> <year> <command...>"
+    const match = trimmed.match(/^(\d+)\s+(\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+(.+)$/);
+    if (!match) continue;
+
+    const [, pidStr, lstart, command] = match;
+    const pid = Number.parseInt(pidStr as string, 10);
+    const startedAt = parseLstart(lstart as string);
+    if (startedAt) {
+      result.set(pid, { cmdline: (command as string).trimEnd(), startedAt });
+    }
+  }
+
+  return result;
+}
+
+async function fetchCwds(pids: number[]): Promise<Map<number, string>> {
+  const result = new Map<number, string>();
+  const output = await run("lsof", ["-a", "-d", "cwd", "-p", pids.join(","), "-F", "pn"]);
+  if (!output) return result;
+
+  let currentPid: number | null = null;
+  for (const line of output.split("\n")) {
+    if (line.length === 0) continue;
+    const tag = line[0];
+    const value = line.slice(1);
+    if (tag === "p") {
+      currentPid = Number.parseInt(value, 10);
+    } else if (tag === "n" && currentPid !== null) {
+      result.set(currentPid, value);
+    }
+  }
+
+  return result;
+}
+
+/** Parses ps's `lstart` format ("Mon Aug 31 02:20:42 2026") into an ISO string. */
+function parseLstart(lstart: string): string | null {
+  const date = new Date(lstart);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+async function run(command: string, args: string[]): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync(command, args, { maxBuffer: 10 * 1024 * 1024 });
+    return stdout;
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException & { stdout?: string };
+    return err.stdout ?? null;
+  }
+}
+
+export function applyEnrichment(
+  entries: PortEntry[],
+  details: Map<number, ProcessDetail>,
+  cwds: Map<number, string>,
+): PortEntry[] {
+  return entries.map((entry) => {
+    if (entry.pid === null) return entry;
+    const detail = details.get(entry.pid);
+    const cwd = cwds.get(entry.pid);
+    return {
+      ...entry,
+      cmdline: detail?.cmdline ?? entry.cmdline,
+      startedAt: detail?.startedAt ?? entry.startedAt,
+      cwd: cwd ?? entry.cwd,
+    };
+  });
+}

package/packages/core/src/scan/index.ts

@@ -0,0 +1,13 @@
+import { scanLocalPorts, type ScanOptions } from "./scanner.js";
+import { enrichProcesses, applyEnrichment } from "./enrichProcess.js";
+import type { PortEntry } from "../types.js";
+
+export type { ScanOptions } from "./scanner.js";
+
+/** Full local scan: raw listening sockets + process enrichment (cmdline/cwd/startedAt). */
+export async function scanPorts(options: ScanOptions): Promise<PortEntry[]> {
+  const bare = await scanLocalPorts(options);
+  const pids = bare.map((entry) => entry.pid).filter((pid): pid is number => pid !== null);
+  const { details, cwds } = await enrichProcesses(pids);
+  return applyEnrichment(bare, details, cwds);
+}

package/packages/core/src/scan/parseLsof.ts

@@ -0,0 +1,74 @@
+/**
+ * Parses `lsof -F pcn` field output into raw listening-socket records.
+ *
+ * Field format (one token per line, no separators):
+ *   p<pid>          start of a new process block
+ *   c<command>      command name for the current pid
+ *   f<fd>           start of a new file/socket for the current pid
+ *   n<address>      address for the current file, e.g. "*:3000", "127.0.0.1:5432", "[::1]:5432"
+ *
+ * A "p" line always precedes its "c" line; a "f" line always precedes its "n" line.
+ * Verified against real `lsof -iTCP -sTCP:LISTEN -P -n -F pcn` output on macOS.
+ */
+export interface RawListeningSocket {
+  pid: number;
+  processName: string;
+  bindAddress: string;
+  port: number;
+}
+
+export function parseLsofFieldOutput(output: string): RawListeningSocket[] {
+  const sockets: RawListeningSocket[] = [];
+  let currentPid: number | null = null;
+  let currentCommand: string | null = null;
+
+  for (const line of output.split("\n")) {
+    if (line.length === 0) continue;
+    const tag = line[0];
+    const value = line.slice(1);
+
+    if (tag === "p") {
+      currentPid = Number.parseInt(value, 10);
+    } else if (tag === "c") {
+      currentCommand = value;
+    } else if (tag === "n" && currentPid !== null && currentCommand !== null) {
+      const parsed = parseAddress(value);
+      if (parsed) {
+        sockets.push({
+          pid: currentPid,
+          processName: currentCommand,
+          bindAddress: parsed.bindAddress,
+          port: parsed.port,
+        });
+      }
+    }
+  }
+
+  return sockets;
+}
+
+/**
+ * Splits an lsof address into bind address + port.
+ * Handles "*:3000" (all interfaces v4), "127.0.0.1:5432", "[::1]:5432" (IPv6),
+ * and "*:*" / bare "*" (unbound UDP socket, no real port - returns null).
+ */
+function parseAddress(raw: string): { bindAddress: string; port: number } | null {
+  const lastColon = raw.lastIndexOf(":");
+  if (lastColon === -1) return null;
+
+  const portStr = raw.slice(lastColon + 1);
+  if (portStr === "*" || portStr === "") return null;
+
+  const port = Number.parseInt(portStr, 10);
+  if (Number.isNaN(port)) return null;
+
+  let bindAddress = raw.slice(0, lastColon);
+  if (bindAddress.startsWith("[") && bindAddress.endsWith("]")) {
+    bindAddress = bindAddress.slice(1, -1);
+  }
+  if (bindAddress === "*") {
+    bindAddress = "0.0.0.0";
+  }
+
+  return { bindAddress, port };
+}

package/packages/core/src/scan/scanner.ts

@@ -0,0 +1,88 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { parseLsofFieldOutput, type RawListeningSocket } from "./parseLsof.js";
+import type { PortEntry } from "../types.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface ScanOptions {
+  includeUdp: boolean;
+}
+
+/**
+ * Runs `lsof` for TCP (and optionally UDP) listening sockets and returns
+ * bare PortEntry objects: only host/port/protocol/bindAddress/pid/processName
+ * are populated here. Process enrichment (cmdline/cwd/startedAt) is a
+ * separate step (see enrichProcess.ts) so scanning still returns partial
+ * results if enrichment for one PID fails.
+ *
+ * Never throws if `lsof` is missing or errors - returns an empty list and
+ * lets the caller decide how to report that (CLI exit code 1 per spec).
+ */
+export async function scanLocalPorts(options: ScanOptions): Promise<PortEntry[]> {
+  const sockets: (RawListeningSocket & { protocol: "tcp" | "udp" })[] = [];
+
+  const tcp = await runLsof(["-iTCP", "-sTCP:LISTEN", "-P", "-n", "-F", "pcn"]);
+  if (tcp) sockets.push(...parseLsofFieldOutput(tcp).map((s) => ({ ...s, protocol: "tcp" as const })));
+
+  if (options.includeUdp) {
+    const udp = await runLsof(["-iUDP", "-P", "-n", "-F", "pcn"]);
+    if (udp) sockets.push(...parseLsofFieldOutput(udp).map((s) => ({ ...s, protocol: "udp" as const })));
+  }
+
+  return dedupeSockets(sockets).map((socket) => toPortEntry(socket));
+}
+
+/**
+ * lsof reports one line per file descriptor, so the same logical listener
+ * (e.g. bound on both IPv4 and IPv6, or via multiple duplicated fds) shows up
+ * as several identical-looking rows. Collapse by the fields that actually
+ * distinguish one listener from another.
+ */
+export function dedupeSockets(
+  sockets: (RawListeningSocket & { protocol: "tcp" | "udp" })[],
+): (RawListeningSocket & { protocol: "tcp" | "udp" })[] {
+  const seen = new Map<string, RawListeningSocket & { protocol: "tcp" | "udp" }>();
+  for (const socket of sockets) {
+    const key = `${socket.protocol}:${socket.bindAddress}:${socket.port}:${socket.pid}`;
+    if (!seen.has(key)) seen.set(key, socket);
+  }
+  return [...seen.values()];
+}
+
+async function runLsof(args: string[]): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync("lsof", args, { maxBuffer: 10 * 1024 * 1024 });
+    return stdout;
+  } catch (error) {
+    // lsof exits non-zero when there are simply no matching sockets - that's
+    // not a failure. Only treat "binary not found" as a hard miss.
+    const err = error as NodeJS.ErrnoException & { stdout?: string };
+    if (err.code === "ENOENT") return null;
+    return err.stdout ?? null;
+  }
+}
+
+function toPortEntry(socket: RawListeningSocket & { protocol: "tcp" | "udp" }): PortEntry {
+  return {
+    host: "localhost",
+    port: socket.port,
+    protocol: socket.protocol,
+    bindAddress: socket.bindAddress,
+    pid: socket.pid,
+    processName: socket.processName,
+    cmdline: null,
+    cwd: null,
+    startedAt: null,
+    docker: null,
+    knownService: null,
+    history: {
+      usual: true,
+      observationCount: 0,
+      firstSeen: null,
+      usualOccupant: null,
+    },
+    riskFlags: [],
+    aiExplanation: null,
+  };
+}

package/packages/core/src/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Core data shape shared by every UI (CLI, TUI, web). Defined once here;
+ * cli/tui/web packages must render this type, never define their own shape.
+ */
+export interface PortEntry {
+  host: string;
+  port: number;
+  protocol: "tcp" | "udp";
+  bindAddress: string;
+  pid: number | null;
+  processName: string | null;
+  cmdline: string | null;
+  cwd: string | null;
+  startedAt: string | null;
+  docker: {
+    containerId: string;
+    containerName: string;
+    image: string;
+  } | null;
+  knownService: {
+    name: string;
+    description: string;
+    source: "iana" | "custom";
+  } | null;
+  history: {
+    usual: boolean;
+    observationCount: number;
+    firstSeen: string | null;
+    usualOccupant: string | null;
+  };
+  riskFlags: RiskFlag[];
+  aiExplanation: string | null;
+}
+
+export type RiskFlag = "bound_all_interfaces" | "unsigned_binary" | "no_known_service";

package/packages/core/tests/config.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_CONFIG } from "../src/config.js";
+
+describe("DEFAULT_CONFIG", () => {
+  it("ships with AI disabled by default", () => {
+    expect(DEFAULT_CONFIG.ai.enabled).toBe(false);
+  });
+
+  it("only allows the documented AI fields", () => {
+    const allowed = ["process_name", "cmdline", "port", "protocol", "docker_image"];
+    for (const field of DEFAULT_CONFIG.ai.fieldsSent) {
+      expect(allowed).toContain(field);
+    }
+  });
+
+  it("scans docker and udp by default", () => {
+    expect(DEFAULT_CONFIG.scan.docker).toBe(true);
+    expect(DEFAULT_CONFIG.scan.includeUdp).toBe(true);
+  });
+});

package/packages/core/tests/parseLsof.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { parseLsofFieldOutput } from "../src/scan/parseLsof.js";
+
+describe("parseLsofFieldOutput", () => {
+  it("parses IPv4 wildcard bind addresses", () => {
+    const output = "p984\ncrapportd\nf14\nn*:59095\n";
+    const result = parseLsofFieldOutput(output);
+    expect(result).toEqual([
+      { pid: 984, processName: "rapportd", bindAddress: "0.0.0.0", port: 59095 },
+    ]);
+  });
+
+  it("parses loopback bind addresses", () => {
+    const output = "p1758\ncpostgres\nf8\nn127.0.0.1:5432\n";
+    const result = parseLsofFieldOutput(output);
+    expect(result).toEqual([
+      { pid: 1758, processName: "postgres", bindAddress: "127.0.0.1", port: 5432 },
+    ]);
+  });
+
+  it("parses bracketed IPv6 bind addresses", () => {
+    const output = "p1758\ncpostgres\nf7\nn[::1]:5432\n";
+    const result = parseLsofFieldOutput(output);
+    expect(result).toEqual([{ pid: 1758, processName: "postgres", bindAddress: "::1", port: 5432 }]);
+  });
+
+  it("skips unbound sockets with no real port (UDP wildcard)", () => {
+    const output = "p996\ncidentityservicesd\nf13\nn*:*\n";
+    expect(parseLsofFieldOutput(output)).toEqual([]);
+  });
+
+  it("associates multiple sockets with the same process block", () => {
+    const output = "p1117\ncControlCenter\nf9\nn*:7000\nf11\nn*:5000\n";
+    const result = parseLsofFieldOutput(output);
+    expect(result).toHaveLength(2);
+    expect(result[0]?.port).toBe(7000);
+    expect(result[1]?.port).toBe(5000);
+  });
+
+  it("returns an empty array for empty output", () => {
+    expect(parseLsofFieldOutput("")).toEqual([]);
+  });
+});

package/packages/core/tests/scanner.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { dedupeSockets } from "../src/scan/scanner.js";
+
+describe("dedupeSockets", () => {
+  it("collapses duplicate fds for the same protocol/address/port/pid", () => {
+    const sockets = [
+      { pid: 1117, processName: "ControlCenter", bindAddress: "0.0.0.0", port: 7000, protocol: "tcp" as const },
+      { pid: 1117, processName: "ControlCenter", bindAddress: "0.0.0.0", port: 7000, protocol: "tcp" as const },
+    ];
+    expect(dedupeSockets(sockets)).toHaveLength(1);
+  });
+
+  it("keeps distinct ports for the same pid separate", () => {
+    const sockets = [
+      { pid: 1117, processName: "ControlCenter", bindAddress: "0.0.0.0", port: 7000, protocol: "tcp" as const },
+      { pid: 1117, processName: "ControlCenter", bindAddress: "0.0.0.0", port: 5000, protocol: "tcp" as const },
+    ];
+    expect(dedupeSockets(sockets)).toHaveLength(2);
+  });
+
+  it("keeps tcp and udp on the same port separate", () => {
+    const sockets = [
+      { pid: 1605, processName: "Spotify", bindAddress: "0.0.0.0", port: 57621, protocol: "tcp" as const },
+      { pid: 1605, processName: "Spotify", bindAddress: "0.0.0.0", port: 57621, protocol: "udp" as const },
+    ];
+    expect(dedupeSockets(sockets)).toHaveLength(2);
+  });
+});

package/packages/core/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["tests", "dist"]
+}

package/packages/core/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+    environment: "node",
+  },
+});

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "packages/*"

package/tsconfig.base.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "isolatedModules": true
+  }
+}