Merge pull request #7 from selfmd/feat/dashboard-v2-handoff

feat(dashboard): add v2 dashboard handoff

Author: shmlkv

.dockerignore

@@ -0,0 +1,12 @@
+.git
+.github
+node_modules
+**/node_modules
+**/dist
+.DS_Store
+.env
+.env.*
+!.env.example
+coverage
+.tmp
+tmp

.env.example

@@ -0,0 +1,10 @@
+# Dashboard/server
+PORT=3001
+HOST=127.0.0.1
+AGENT_NAME=network-selfmd-dashboard
+L2S_DATA_DIR=/data
+
+# For Docker images, keep the image default HOST=0.0.0.0 inside the container,
+# but bind published ports to 127.0.0.1 on the host unless access is protected.
+# Do not expose the dashboard directly to the public internet.
+# Put it behind VPN, Tailscale, Cloudflare Access, or another auth layer.

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Enable pnpm
+        run: corepack enable
+      - name: Install native build dependencies
+        run: sudo apt-get update && sudo apt-get install -y python3 make g++
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build
+        run: pnpm -r build
+      - name: Test
+        run: pnpm -r test
+
+  docker-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build dashboard image
+        run: docker build -t networkselfmd-dashboard:ci .

Dockerfile

@@ -0,0 +1,22 @@
+FROM node:22-bookworm-slim
+
+WORKDIR /app
+
+RUN apt-get update   && apt-get install -y --no-install-recommends python3 make g++ ca-certificates   && rm -rf /var/lib/apt/lists/*   && corepack enable
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.json ./
+COPY packages ./packages
+
+RUN pnpm install --frozen-lockfile   && pnpm -r build   && CI=true pnpm prune --prod
+
+ENV NODE_ENV=production   PORT=3001   HOST=0.0.0.0   L2S_DATA_DIR=/data   AGENT_NAME=network-selfmd-dashboard
+
+RUN mkdir -p /data && chown -R node:node /data /app
+USER node
+
+EXPOSE 3001
+VOLUME ["/data"]
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3   CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 3001) + '/healthz').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
+
+CMD ["node", "packages/dashboard/dist/server/index.js"]

docs/deployment.md

@@ -0,0 +1,41 @@
+# Deployment
+
+The dashboard is a local network agent with a browser UI. Treat it like an operator console, not a public SaaS page.
+
+## Safety rule
+
+Do **not** expose the dashboard directly to the public internet. It can show local node identity, peers, states, and decrypted room messages for states this node has joined.
+
+Put it behind one of:
+
+- Tailscale / WireGuard / private network
+- Cloudflare Access
+- reverse proxy with authentication
+- an internal-only host
+
+## Docker
+
+```bash
+docker build -t networkselfmd-dashboard .
+
+docker run --rm \
+  -p 127.0.0.1:3001:3001 \
+  -v networkselfmd-data:/data \
+  networkselfmd-dashboard
+```
+
+Open `http://127.0.0.1:3001`.
+
+## Environment
+
+See `.env.example`.
+
+- `PORT` — HTTP port, default `3001`
+- `HOST` — bind host, default `127.0.0.1` locally; Docker sets `0.0.0.0` inside the container and the example port mapping still binds to localhost on the host
+- `L2S_DATA_DIR` — persistent agent identity/network data directory
+- `AGENT_NAME` — display name announced by the dashboard agent
+
+## Health checks
+
+- `GET /healthz` — process is alive
+- `GET /api/status` — dashboard agent/runtime status

docs/terminology.md

@@ -0,0 +1,12 @@
+# Terminology
+
+`state` is the product term; `group` is the runtime/internal protocol term; they refer to the same encrypted shared context.
+
+Public UI, docs and new CLI aliases should prefer:
+
+- `state` — a shared encrypted context
+- `public state` — a discoverable state with a `self.md` manifesto
+- `rooms` — conversational/work subspaces inside a state
+- `agents` — actors in the network
+
+Existing `group` CLI commands remain for backwards compatibility. Prefer the aliases `states`, `create-state` and `join-state` in new user-facing copy.

package.json

@@ -1,6 +1,7 @@
 {
   "name": "networkselfmd",
   "private": true,
+  "packageManager": "pnpm@10.33.2",
   "type": "module",
   "scripts": {
     "build": "pnpm -r build",

packages/cli/src/bin.ts

@@ -31,6 +31,14 @@ program
     await createGroup(opts.name);
   });
 
+program
+  .command('create-state')
+  .description('Create a new state (alias for create-group)')
+  .requiredOption('--name <name>', 'State name')
+  .action(async (opts) => {
+    await createGroup(opts.name);
+  });
+
 program
   .command('join-group')
   .description('Join an existing group')
@@ -39,6 +47,14 @@ program
     await joinGroup(groupId);
   });
 
+program
+  .command('join-state')
+  .description('Join an existing state (alias for join-group)')
+  .argument('<stateId>', 'State ID to join')
+  .action(async (stateId: string) => {
+    await joinGroup(stateId);
+  });
+
 program
   .command('chat')
   .description('Enter interactive chat')
@@ -54,6 +70,13 @@ program
     await listGroups();
   });
 
+program
+  .command('states')
+  .description('List states (alias for groups)')
+  .action(async () => {
+    await listGroups();
+  });
+
 program
   .command('peers')
   .description('List peers')

packages/dashboard/package.json

@@ -7,6 +7,7 @@
     "dev": "concurrently \"vite\" \"tsx watch src/server/index.ts\"",
     "build": "vite build && tsc -p tsconfig.json",
     "preview": "tsx src/server/index.ts",
+    "start": "node dist/server/index.js",
     "test": "vitest run"
   },
   "dependencies": {