docs(site): coverage matrix as a themed Angular page (not a raw markdown link)

Ports the coverage-matrix artifact into the doc site as a first-class page at the site theme (violet / GitHub-dark, CSS vars, Material icons) instead of linking to docs/coverage.md raw. Data refreshed to the current state: Windows datapath + single-label DNS (getaddrinfo via .plug/NRPT) validated end-to-end; SYSTEM service coded (no-admin + multicluster groundwork); PID recycle-guard. Wired into the sidebar + header nav with a /coverage route; build + runtime verified in the dev server.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: hhfrancois

docs/src/app/app.component.html

@@ -16,7 +16,7 @@ <h1>plug</h1>
           <mat-icon>menu_book</mat-icon>
           README
         </a>
-        <a href="https://github.com/softwarity/plug/blob/main/docs/coverage.md" target="_blank" rel="noopener" class="nav-button">
+        <a [routerLink]="'/coverage'" class="nav-button">
           <mat-icon>table_chart</mat-icon>
           Coverage
         </a>

docs/src/app/app.component.ts

@@ -27,6 +27,7 @@ export class AppComponent {
     { path: '/profiles', label: 'Profiles & versions', icon: 'settings' },
     { path: '/agent', label: 'Agent & deployment', icon: 'dns' },
     { path: '/security', label: 'Security model', icon: 'shield' },
+    { path: '/coverage', label: 'Coverage matrix', icon: 'table_chart' },
     { path: '/roadmap', label: 'Roadmap', icon: 'map' },
   ];
 }

docs/src/app/app.routes.ts

@@ -26,5 +26,9 @@ export const routes: Routes = [
     path: 'roadmap',
     loadComponent: () => import('./pages/roadmap.component').then((m) => m.RoadmapComponent),
   },
+  {
+    path: 'coverage',
+    loadComponent: () => import('./pages/coverage.component').then((m) => m.CoverageComponent),
+  },
   { path: '**', redirectTo: '' },
 ];

docs/src/app/pages/coverage.component.ts

@@ -0,0 +1,258 @@
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+
+type St = 'ok' | 'warn' | 'no' | 'na';
+
+interface Row {
+  feat: string;
+  os?: St[]; // [Linux, macOS, Windows] for OS sections
+  st?: St; // single status for flat sections
+  note?: string;
+  sub?: boolean;
+}
+interface Section {
+  title: string;
+  flat?: boolean;
+  rows: Row[];
+}
+interface Hole {
+  sev: 'no' | 'warn';
+  t: string;
+  d: string;
+}
+
+@Component({
+  selector: 'app-coverage',
+  imports: [RouterLink],
+  preserveWhitespaces: true,
+  styles: [
+    `
+      .lead { max-width: 66ch; }
+      .snap { font-family: 'Courier New', Consolas, monospace; font-size: 0.8rem; color: var(--text-muted); margin: 4px 0 0; }
+
+      .legend { display: flex; flex-wrap: wrap; gap: 16px; margin: 18px 0 6px; font-size: 0.82rem; }
+      .legend span { display: inline-flex; align-items: center; gap: 7px; color: var(--text-muted); }
+      .dot { width: 15px; height: 15px; border-radius: 50%; display: inline-grid; place-items: center;
+             font-size: 10px; font-weight: 700; color: #0d1117; }
+      .d-ok { background: var(--cov-ok); } .d-warn { background: var(--cov-warn); }
+      .d-no { background: var(--cov-no); } .d-na { background: var(--cov-na); color: var(--text-primary); }
+
+      .holes { display: grid; grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); gap: 12px; margin: 12px 0 8px; }
+      .hole { background: var(--bg-secondary); border: 1px solid var(--border-color); border-radius: 10px;
+              padding: 14px 16px; position: relative; overflow: hidden; }
+      .hole::before { content: ''; position: absolute; left: 0; top: 0; bottom: 0; width: 3px; background: var(--sev); }
+      .hole .n { font-family: 'Courier New', Consolas, monospace; font-size: 0.7rem; color: var(--text-muted); }
+      .hole .t { font-weight: 600; margin: 3px 0 6px; color: var(--text-primary); font-size: 0.92rem; }
+      .hole .d { font-size: 0.83rem; color: var(--text-secondary); line-height: 1.45; }
+
+      section.cov { margin-top: 30px; }
+      .s-title { font-size: 0.82rem; letter-spacing: 0.12em; text-transform: uppercase; color: var(--accent-purple);
+                 margin: 0 0 10px; display: flex; align-items: center; gap: 12px; font-weight: 600; }
+      .s-title::after { content: ''; flex: 1; height: 1px; background: var(--border-color); }
+
+      .scroll { overflow-x: auto; border: 1px solid var(--border-color); border-radius: 10px; }
+      table.cov { border-collapse: collapse; width: 100%; min-width: 640px; margin: 0; font-size: 0.88rem; }
+      table.cov th, table.cov td { padding: 9px 13px; border-bottom: 1px solid var(--border-color); text-align: left; vertical-align: middle; }
+      table.cov tbody tr:last-child td { border-bottom: none; }
+      table.cov thead th { background: var(--bg-secondary); font-size: 0.7rem; letter-spacing: 0.06em;
+                           text-transform: uppercase; color: var(--text-muted); font-weight: 600; }
+      table.cov th.c, table.cov td.c { text-align: center; width: 92px; }
+      td.feat { font-family: 'Courier New', Consolas, monospace; font-size: 0.83rem; color: var(--text-primary); white-space: nowrap; }
+      td.feat.sub { color: var(--text-secondary); padding-left: 22px; position: relative; }
+      td.feat.sub::before { content: '↳'; position: absolute; left: 8px; color: var(--text-muted); }
+      td.note { color: var(--text-secondary); font-size: 0.83rem; white-space: normal; }
+      table.cov tbody tr:hover td { background: rgba(163, 113, 247, 0.05); }
+
+      .cell { display: inline-grid; place-items: center; width: 26px; height: 26px; border-radius: 7px;
+              font-family: 'Courier New', Consolas, monospace; font-weight: 700; font-size: 0.95rem; }
+      .st-ok .cell { background: rgba(63, 185, 80, 0.14); color: var(--cov-ok); }
+      .st-warn .cell { background: rgba(210, 153, 34, 0.16); color: var(--cov-warn); }
+      .st-no .cell { background: rgba(248, 81, 73, 0.15); color: var(--cov-no); }
+      .st-na .cell { background: rgba(139, 148, 158, 0.12); color: var(--cov-na); }
+
+      :host { --cov-ok: #3fb950; --cov-warn: var(--accent-yellow); --cov-no: var(--accent-red); --cov-na: var(--text-muted); }
+    `,
+  ],
+  template: `
+    <h2>Coverage matrix</h2>
+    <p class="lead">
+      What works where, and where the holes are — features × OS. One process run
+      <strong>as if it were inside the cluster</strong>, via a userspace TUN over an SSH tunnel.
+    </p>
+    <p class="snap">snapshot {{ snapshot }} · Windows datapath validated end-to-end, SYSTEM service coded</p>
+
+    <div class="legend">
+      <span><i class="dot d-ok">✓</i> works (proven at runtime)</span>
+      <span><i class="dot d-warn">!</i> coded / partial — not yet e2e-validated</span>
+      <span><i class="dot d-no">✕</i> not yet</span>
+      <span><i class="dot d-na">–</i> n/a by design</span>
+    </div>
+
+    <h3>Biggest holes — priority order</h3>
+    <div class="holes">
+      @for (h of holes; track h.t; let i = $index) {
+        <div class="hole" [style.--sev]="h.sev === 'no' ? 'var(--cov-no)' : 'var(--cov-warn)'">
+          <div class="n">0{{ i + 1 }}</div>
+          <div class="t">{{ h.t }}</div>
+          <div class="d">{{ h.d }}</div>
+        </div>
+      }
+    </div>
+
+    @for (sec of sections; track sec.title) {
+      <section class="cov">
+        <h3 class="s-title">{{ sec.title }}</h3>
+        <div class="scroll">
+          <table class="cov">
+            <thead>
+              @if (sec.flat) {
+                <tr><th>Item</th><th class="c">Support</th><th>Notes</th></tr>
+              } @else {
+                <tr>
+                  <th>Feature</th>
+                  @for (o of os; track o) { <th class="c">{{ o }}</th> }
+                  <th>Notes</th>
+                </tr>
+              }
+            </thead>
+            <tbody>
+              @for (r of sec.rows; track r.feat) {
+                <tr>
+                  <td class="feat" [class.sub]="r.sub" [innerHTML]="r.feat"></td>
+                  @if (sec.flat) {
+                    <td class="c st-{{ r.st }}"><span class="cell">{{ glyph(r.st!) }}</span></td>
+                  } @else {
+                    @for (s of r.os!; track $index) {
+                      <td class="c st-{{ s }}"><span class="cell">{{ glyph(s) }}</span></td>
+                    }
+                  }
+                  <td class="note" [innerHTML]="r.note || ''"></td>
+                </tr>
+              }
+            </tbody>
+          </table>
+        </div>
+      </section>
+    }
+
+    <div class="callout">
+      <strong>Read this alongside the code.</strong> The Windows datapath (WinTUN + name resolution)
+      is proven on a real machine; the SYSTEM service that removes the per-run admin and enables
+      multicluster is written and build-validated on all three OSes but not yet runtime-validated —
+      see <a href="https://github.com/softwarity/plug/blob/main/docs/windows-service.md" target="_blank" rel="noopener">docs/windows-service.md</a>
+      and the <a routerLink="/roadmap">roadmap</a>.
+    </div>
+  `,
+})
+export class CoverageComponent {
+  protected readonly snapshot = '2026-07-08';
+  protected readonly os = ['Linux', 'macOS', 'Windows'];
+
+  protected glyph(s: St): string {
+    return { ok: '✓', warn: '!', no: '✕', na: '–' }[s];
+  }
+
+  protected readonly holes: Hole[] = [
+    {
+      sev: 'warn',
+      t: 'Windows SYSTEM service — runtime',
+      d: 'The service (no-admin + multicluster) is written and build-validated on all three OSes. Needs a real Windows run: SCM lifecycle, service ACL for non-admin start, session-0 DNS.',
+    },
+    {
+      sev: 'warn',
+      t: 'Windows e2e in CI',
+      d: 'Lock down install + service + name resolution (getaddrinfo) with an all-Windows-container e2e on a hosted runner; the full protocol grid needs a self-hosted (WSL2) runner.',
+    },
+    {
+      sev: 'warn',
+      t: 'Windows real-app + VPN',
+      d: 'A plain cluster is now proven end-to-end on Windows. Corporate-VPN behaviour and self-heal there are still unproven.',
+    },
+    {
+      sev: 'warn',
+      t: 'self-update on Linux',
+      d: 'Loses file-caps on update (pre-existing). macOS already re-applies its setuid bit.',
+    },
+  ];
+
+  protected readonly sections: Section[] = [
+    {
+      title: 'Install & privilege',
+      rows: [
+        { feat: 'Install from the cluster (one-liner)', os: ['ok', 'ok', 'ok'], note: '<code>install | sh</code> · <code>install-windows | powershell</code> (Git Bash: <code>PLUG_HOST=</code>)' },
+        { feat: 'No sudo/admin to install', os: ['ok', 'ok', 'ok'], note: 'binaries + PATH; one UAC only to create the service' },
+        { feat: 'One-time privilege grant at install', os: ['ok', 'ok', 'warn'], note: 'setcap · setuid helper · SCM service (coded)' },
+        { feat: '<b>plug &lt;cmd&gt;</b> without sudo/admin', os: ['ok', 'ok', 'warn'], note: 'Windows: via the service (coded) → no admin; else falls back to an elevated terminal' },
+        { feat: 'Child runs as you (privilege drop)', os: ['ok', 'ok', 'na'], note: "caps don't cross exec · Credential drop · service is SYSTEM" },
+        { feat: 'self-update preserves privilege', os: ['warn', 'ok', 'na'], note: 'setcap lost on update · macOS re-applies setuid' },
+        { feat: 'Pre-create profile at install', os: ['ok', 'ok', 'ok'], note: 'reads host/port off the live ssh' },
+        { feat: 'Uninstall', os: ['ok', 'ok', 'warn'], note: 'unix covered; Windows path unverified' },
+      ],
+    },
+    {
+      title: 'Data path',
+      rows: [
+        { feat: 'Userspace TUN (IP-layer capture)', os: ['ok', 'ok', 'ok'], note: '/dev/net/tun · utun · WinTUN' },
+        { feat: 'Cluster-name DNS (real apps)', os: ['ok', 'ok', 'ok'], note: 'private resolv.conf · scutil store · WinTUN search-suffix + NRPT' },
+        { feat: 'Single-label name via <code>getaddrinfo</code>', os: ['ok', 'ok', 'ok'], note: 'the real app path; Windows needs the <code>.plug</code> search suffix to issue a DNS query' },
+        { feat: 'Works under a corporate VPN', os: ['ok', 'ok', 'warn'], note: 'macOS proven w/ GlobalProtect; Windows unproven' },
+        { feat: 'Every runtime (Node/JVM/Py/Go/gRPC)', os: ['ok', 'ok', 'ok'], note: 'IP-level capture, socket never touched' },
+        { feat: 'Native selftest (datapath proof)', os: ['ok', 'ok', 'ok'], note: 'green on all three in CI' },
+        { feat: 'e2e protocol matrix (8 protos × 4 langs)', os: ['ok', 'na', 'na'], note: 'Docker→Linux; mac/win via native selftest (Windows e2e planned)' },
+        { feat: 'Split-horizon (short→cluster, FQDN→direct)', os: ['ok', 'ok', 'ok'], note: '+ <code>PLUG_DIRECT</code> overrides' },
+        { feat: 'Self-heal (VPN / sleep / agent restart)', os: ['ok', 'ok', 'warn'], note: 'keepalive+reconnect; Windows unproven' },
+      ],
+    },
+    {
+      title: 'Daemon / persistence',
+      rows: [
+        { feat: 'Persistent global datapath', os: ['na', 'ok', 'warn'], note: 'Linux autonomous · macOS daemon · Windows SCM service (coded)' },
+        { feat: 'Survives process restarts', os: ['ok', 'ok', 'warn'], note: 'per-launch · daemon · service (coded)' },
+        { feat: 'Graft (multi-process, same cluster)', os: ['ok', 'ok', 'warn'], note: 'flock leader/graft · service is the single owner' },
+        { feat: '<b>plug down</b>', os: ['na', 'ok', 'warn'], note: 'stops the daemon (macOS) / service (Windows, coded)' },
+      ],
+    },
+    {
+      title: 'Multicluster — different clusters at once',
+      rows: [
+        { feat: 'Simultaneous different clusters', os: ['ok', 'ok', 'warn'], note: 'Linux mount-ns · <b>macOS validated e2e</b> · Windows service (coded)' },
+        { feat: 'PID-at-connect attribution', os: ['na', 'ok', 'warn'], note: '<code>multiDial</code> shared; macOS proven on 2 live clusters · Windows service coded' },
+        { feat: 'ppidOf', os: ['ok', 'ok', 'warn'], note: '/proc · ps · ToolHelp (coded, unit-tested)', sub: true },
+        { feat: 'pidForLocalPort', os: ['ok', 'ok', 'warn'], note: '/proc/net · lsof · GetExtendedTcpTable (coded, unit-tested)', sub: true },
+        { feat: 'procStart (recycle guard)', os: ['ok', 'ok', 'warn'], note: 'ps lstart · /proc stat · GetProcessTimes — rejects a reused PID', sub: true },
+        { feat: 'N-tunnel global daemon', os: ['na', 'ok', 'warn'], note: 'macOS done + validated · Windows = SCM service (coded)' },
+      ],
+    },
+    {
+      title: 'Profiles & CLI',
+      rows: [
+        { feat: 'Profiles ~/.plug/*.conf', os: ['ok', 'ok', 'ok'], note: 'create by naming · ls · rm · rn/mv · test' },
+        { feat: '-p profile / --host / --port / env', os: ['ok', 'ok', 'ok'], note: 'env = <code>$PLUG_HOST $PLUG_PORT</code>' },
+        { feat: 'Launcher versions (per-cluster)', os: ['ok', 'ok', 'ok'], note: 'versions · self-update · <code>.exe</code> + wintun.dll handled on Windows' },
+        { feat: 'Host-key TOFU pin', os: ['ok', 'ok', 'ok'], note: 'localhost skipped; pin chowned (macOS)' },
+        { feat: 'Port-forward escape hatch (forward=)', os: ['ok', 'ok', 'ok'], note: 'rewrites an env var to a local port' },
+      ],
+    },
+    {
+      title: 'Agent deployment',
+      flat: true,
+      rows: [
+        { feat: 'Docker Compose / Swarm', st: 'ok', note: 'agent image joins the stack network' },
+        { feat: 'Kubernetes — NodePort', st: 'ok', note: '<code>deploy/plug-k8s.yaml</code>, --port 32222' },
+        { feat: 'Kubernetes — kubectl port-forward', st: 'ok', note: 'zero exposed port, API-server RBAC' },
+        { feat: 'Cross-namespace', st: 'ok', note: 'via FQDN <code>svc.othernamespace</code>' },
+        { feat: 'kubectl exec transport', st: 'no', note: 'dropped — port-forward already covers it' },
+      ],
+    },
+    {
+      title: 'Design limits (all OS)',
+      flat: true,
+      rows: [
+        { feat: 'UDP / QUIC / ping', st: 'no', note: 'TCP only (SSH tunnel); most clients fall back to TCP' },
+        { feat: 'IPv6 literal (hard-coded)', st: 'no', note: 'fake IPs are IPv4; by-name cluster service is fine' },
+        { feat: 'Root / helper required', st: 'na', note: 'by design — the price of covering every runtime' },
+        { feat: 'Authentication', st: 'na', note: 'none by design — trusted dev clusters only' },
+      ],
+    },
+  ];
+}