feat(deploy): Dockerfile, compose, systemd unit + implementation notes

Multi-stage image: build with dev deps, run node dist/index.js on node:20-slim
with production deps only, as the unprivileged node user, data in a /data
volume. Inside the container the server binds 0.0.0.0 (a loopback bind is
unreachable through a published port); docker-compose.yml restores the
default localhost-only posture by publishing on 127.0.0.1:4280 — widening it
plus TREEMAP_TOKEN is a deliberate act. Containers have no OS Trash, so the
image is documented as scan-and-analyze. deploy/treemap.service is a
hardened systemd sample with StateDirectory-managed app data.

Docker is not installed on this machine, so `docker build` itself could not
run here; the runtime recipe was proven directly instead — dist + public +
`npm ci --omit=dev` staged clean served /api/system, /api/capabilities and
the UI. IMPLEMENTATION_NOTES.md records that, the R2 cookie decision, the
two new dependencies, and every design choice of the upgrade.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Prithvi-Web

.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+dist
+release
+build/gdu
+gdu
+.git
+*.log
+docs
+tests
+electron

Dockerfile

@@ -0,0 +1,39 @@
+# TreeMap server image — multi-stage: compile with dev deps, run on a slim
+# Node 20 base with production deps only.
+#
+# Inside the container the server binds 0.0.0.0 (a 127.0.0.1 bind would be
+# unreachable through the published port); docker-compose.yml maps it to
+# 127.0.0.1 on the HOST by default, so out of the box the app stays
+# localhost-only — the same posture as running it directly. Widen the port
+# mapping and set TREEMAP_TOKEN when you actually want remote access.
+#
+# A container has no OS Trash and no display: treat this profile as
+# scan-and-analyze (mount data read-only); destructive actions belong to the
+# desktop app or a host-run server.
+
+# ---- build: dev deps + tsc ----
+FROM node:20-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+
+# ---- runtime: production deps only ----
+FROM node:20-slim
+ENV NODE_ENV=production \
+    HOST=0.0.0.0 \
+    PORT=4280 \
+    TREEMAP_DATA_DIR=/data \
+    TREEMAP_NO_GDU=1
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+COPY --from=build /app/dist ./dist
+COPY public ./public
+RUN mkdir -p /data && chown node:node /data
+USER node
+VOLUME /data
+EXPOSE 4280
+CMD ["node", "dist/index.js"]

IMPLEMENTATION_NOTES.md

@@ -0,0 +1,80 @@
+# Implementation notes — agent-native upgrade
+
+Decisions, dependencies and deviations from the agent-upgrade master prompt.
+Everything else is documented user-facing in `AGENTS.md`, `GET
+/api/capabilities` and `GET /api/openapi.json`.
+
+## The R2 decision: how the browser UI stays authorized under TREEMAP_TOKEN
+
+**Approach: server-side session cookie, set when the UI page is served.**
+When `TREEMAP_TOKEN` is set, `GET /` (or `/index.html`) responds with an
+`HttpOnly; SameSite=Strict` cookie carrying the token, and the `/api` auth
+middleware accepts either `Authorization: Bearer <token>` or that cookie.
+
+Why this and not the alternatives:
+
+- The frontend is frozen (R1): its literal `fetch('/api/…')` calls and
+  `new EventSource('/api/…')` cannot be taught to send headers — and
+  `EventSource` *cannot* send custom headers at all, so header-only auth
+  would silently kill every SSE stream the UI depends on. Cookies ride along
+  on both automatically.
+- A "same-origin requests are exempt" rule would trust `Origin`/`Referer`
+  headers, which any non-browser client can forge — that's an auth bypass,
+  not an exemption.
+
+Threat model (stated plainly, also in AGENTS.md): the token gates API access
+for non-browser clients, and `SameSite=Strict` + CORS-off blocks cross-site
+browser attacks; anyone who can load the UI page itself gets a session. If
+the port is exposed beyond localhost, front it with a reverse proxy that
+authenticates page loads and terminates TLS.
+
+## New dependencies (and why so few)
+
+- `@modelcontextprotocol/sdk` — the official MCP implementation; hand-rolling
+  the protocol would be invented risk. Runtime dep (the MCP server runs from
+  `dist/` with production deps only).
+- `zod` — peer dependency of the SDK and the input-validation layer for the
+  MCP tools' schemas.
+- **CORS is implemented in-tree** (`src/middleware/cors.ts`): the policy is a
+  handful of headers; the MIT `cors` package would add a dependency for no
+  behavior we need.
+- **Zero frontend dependencies added**; `public/index.html` is untouched.
+
+## Design choices worth knowing
+
+- `prepareOffload` was extracted from `startOffload` (same file, byte-same
+  checks) so dry-run and real-run share one source of truth; `startOffload`
+  accepts the prepared plan back to avoid planning twice.
+- The agent policy (`agent-policy.json`) is **deliberately not writable via
+  the API** — a policy an agent could rewrite for itself would be theatre.
+  `GET /api/policy` shows the resolved policy and the file path; the human
+  edits the file.
+- MCP `scan_path` accepts either `path` (start) or `scanId` (keep waiting) —
+  the polling pattern for scans that outlive one tool-call timeout. The same
+  pattern applies to `find_duplicates` and `offload` (via `jobId`).
+- MCP tool responses skip MCP `outputSchema`: the structured payloads are
+  typed against `src/models/types.ts` at compile time, which keeps one source
+  of truth instead of a second, silently-driftable schema layer.
+- Audit entries record refusals too (`outcome: "refused"`, with the policy
+  code) — an agent probing the rails leaves a trace.
+- In the container the server binds `0.0.0.0` (a 127.0.0.1 bind is
+  unreachable through a published port); `docker-compose.yml` restores the
+  localhost-only posture by publishing on `127.0.0.1:4280` — widen the
+  mapping and set `TREEMAP_TOKEN` deliberately for remote use. Containers
+  have no OS Trash, so the container profile is scan-and-analyze; the compose
+  file suggests read-only data mounts.
+
+## Deviations from the prompt
+
+- **Phase 6 gate (`docker build`) could not be executed on this machine:
+  Docker is not installed.** Everything Docker would validate short of the
+  image layer itself was proven directly: the exact runtime recipe
+  (`package.json` + `npm ci --omit=dev` + `dist/` + `public/` +
+  `node dist/index.js`) was staged in a clean directory and served
+  `/api/system`, `/api/capabilities` and the UI correctly with production
+  dependencies only. Run `docker build .` on a Docker-equipped machine (or
+  CI) to close the loop.
+- No other deviations: every existing endpoint's response shape is unchanged
+  (golden + contract suites), and with all new env vars unset the server's
+  behavior is byte-identical to before (explicit tests assert the historical
+  shapes and header-free responses).

deploy/treemap.service

@@ -0,0 +1,45 @@
+# TreeMap as a systemd service (sample).
+#
+# Install:
+#   sudo useradd --system --home /var/lib/treemap --shell /usr/sbin/nologin treemap
+#   sudo mkdir -p /opt/treemap && sudo cp -r dist public package.json package-lock.json /opt/treemap/
+#   cd /opt/treemap && sudo npm ci --omit=dev
+#   sudo cp deploy/treemap.service /etc/systemd/system/treemap.service
+#   sudo systemctl daemon-reload && sudo systemctl enable --now treemap
+#
+# Default posture: binds 127.0.0.1 — reachable only from the machine itself.
+# For remote access set HOST=0.0.0.0 AND TREEMAP_TOKEN in
+# /etc/treemap/env (see AGENTS.md for the threat model), ideally behind a
+# TLS-terminating reverse proxy.
+
+[Unit]
+Description=TreeMap disk-space visualizer
+Documentation=https://github.com/Prithvi-Web/TreeMap-Disk-Visualizer
+After=network.target
+
+[Service]
+Type=simple
+User=treemap
+Group=treemap
+WorkingDirectory=/opt/treemap
+ExecStart=/usr/bin/node /opt/treemap/dist/index.js
+Restart=on-failure
+RestartSec=5
+
+Environment=NODE_ENV=production
+Environment=HOST=127.0.0.1
+Environment=PORT=4280
+# Snapshots, settings, audit log and policy live here (created by systemd):
+Environment=TREEMAP_DATA_DIR=/var/lib/treemap
+StateDirectory=treemap
+# Optional secrets (TREEMAP_TOKEN=…, TREEMAP_ALLOWED_ORIGINS=…):
+EnvironmentFile=-/etc/treemap/env
+
+# Hardening
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ProtectHome=read-only
+
+[Install]
+WantedBy=multi-user.target

docker-compose.yml

@@ -0,0 +1,25 @@
+# TreeMap server — `docker compose up -d`, then open http://127.0.0.1:4280
+#
+# Default posture matches running the app directly: the port is published on
+# 127.0.0.1 only, so nothing outside this machine can reach it. To expose it
+# beyond localhost, change the mapping to "4280:4280" AND set TREEMAP_TOKEN
+# (see AGENTS.md for the full server profile and its threat model).
+services:
+  treemap:
+    build: .
+    container_name: treemap
+    ports:
+      - "127.0.0.1:4280:4280"
+    volumes:
+      - treemap-data:/data
+      # Mount whatever you want to analyze. Read-only is the honest mode for
+      # a container: there is no OS Trash in here, so treat it as
+      # scan-and-analyze and do destructive cleanups from the desktop app.
+      # - /home/you:/scan/home:ro
+    # environment:
+    #   TREEMAP_TOKEN: change-me-long-random          # bearer auth for /api
+    #   TREEMAP_ALLOWED_ORIGINS: https://tools.example.com
+    restart: unless-stopped
+
+volumes:
+  treemap-data: