diff --git a/HANDOFF.md b/HANDOFF.md index 5888957..b6057e6 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -1,6 +1,6 @@ # ArchNest — Handoff Notes -Status snapshot as of **2026-06-20**. Written so a fresh AI session (or human) can pick this up with zero prior context. Branch names rotate every session — always run `git branch --show-current` and work on a fresh feature branch off `main` (recent branches have used a `kiro/` naming pattern). +Status snapshot as of **2026-06-21**. Written so a fresh AI session (or human) can pick this up with zero prior context. Branch names rotate every session — always run `git branch --show-current` and work on a fresh feature branch off `main` (recent branches have used a `kiro/` or `claude/` naming pattern). ## TL;DR @@ -12,8 +12,17 @@ Since then, **Docker container visibility/management was expanded** (shipped, de - **Persistent SSH terminal sessions** (PR #30) — terminals stay connected across in-app page navigation. - **Docker-over-SSH management** + **Docker push-agent monitoring** (PR #31) — see the "Docker: three ways" section below. -### → NEXT TASK for the picking-up agent: the **Mesh Prerequisite Gate** -This is **designed but NOT built**. Full design + the 4 open decisions are in **`docs/mesh-prerequisite-gate.md`** — read it first. It requires a NetBird mesh to be configured/tested/verified before the rest of the app can be configured. **The hard part is lockout-safety** (a failed mesh test must never lock the admin out). **Do not start coding until the user answers DECIDE A–D in that doc** (escape-hatch behavior, what "verified" means, member behavior, and crucially whether to default the gate OFF so it doesn't immediately gate the live production instance). Use `AskUserQuestion`. +**The Mesh Prerequisite Gate is now built and shipped** (no longer the open task): NetBird-mesh-required-before-config, with universal CIDR-based verification (not NetBird-specific), a routed-mesh/VPC-peering reachability fallback, and a dedicated "Mesh" section in Settings to configure/test it. Defaults OFF, so it does not lock the live instance. Commits: `46d95fc` (gate), `0409159` (universal CIDR check), `800072f` (routed-mesh fallback), `4a4a5a0` (Settings UI) — all merged to `main`. + +Most recently (this session, real user dogfooding rather than a planned feature): walked the user through replacing a broken/insecure Docker-TCP-API integration attempt with a working **SSH Host** integration to a real VM ("Portainer VM," running Portainer + a test container), confirmed Docker-over-SSH container management works end to end, and added supporting UX: +- **Docker setup-script hint in Settings** (commit `628187b`, branch `claude/youthful-cerf-ibvxfb`, **pushed but NOT YET merged to `main`** — user explicitly deferred merging once already; revisit with the user before merging) — when editing a Docker (`type: 'docker'`) integration's `baseUrl`, Settings now renders a copyable systemd-override + `curl` verification script scoped to that exact host/port, so users don't have to hand-derive the remote-API-enablement steps themselves. +- **Help page expansion** (commit `36a79ab`, same branch, pushed) — every page entry in `src/pages/Help.tsx` now has at least one real-world example callout (icon + optional label + scenario text), plus a "New here? Start in this order" quick-start card above the grid, aimed at first-time users who don't yet know which page does what. + +### → NEXT TASK for the picking-up agent +No new feature is queued. Pick up from here: +1. **Decide with the user whether to merge `claude/youthful-cerf-ibvxfb` into `main`.** It contains the Docker setup-script hint (`628187b`) and the Help page expansion (`36a79ab`), both already build-clean (`npm run build` passes). Nothing else is blocking it. +2. **Ask the user if removing the unused Docker API integration (the one superseded by the SSH Host setup) is done** — this was a live-instance UI action on their end, not something done via this repo's code. +3. Otherwise, check with the user for the next priority — there is no pending design doc or half-built feature waiting right now (mesh gate and Docker UX work above are both fully shipped or ready-to-merge). ## Standing rules (read before doing anything) @@ -66,6 +75,9 @@ See `TERMIX_MIGRATION.md` for the phase-by-phase record of the original feature 11. **Settings UX fixes** — secret fields show a "· saved" indicator instead of appearing blank/deleted after reload (`secretKeys: string[]` on the integration serializer); SSH host cards default-collapsed if already configured; SSH private-key/cert fields support file upload to avoid paste corruption. 12. **Persistent terminal sessions** (PR #30) — SSH terminal tabs/panes stay connected when you navigate to other pages and back. See `src/lib/TerminalSessionContext.tsx`. 13. **Docker-over-SSH + agent monitoring** (PR #31) — two new ways to see/manage Docker without exposing the Engine TCP socket. See "Docker: three ways" below. +14. **Mesh Prerequisite Gate** (`46d95fc`, `0409159`, `800072f`, `4a4a5a0`) — requires a verified mesh network (universal CIDR check, not NetBird-specific, with a routed-mesh/VPC-peering fallback) before the app can be configured; defaults OFF; configurable/testable from a dedicated Settings → Mesh section. +15. **Docker integration setup-script hint** (`628187b`, on `claude/youthful-cerf-ibvxfb`, not yet merged) — Settings shows a host-specific systemd-override + curl script when configuring a Docker (`type: 'docker'`) integration's `baseUrl`, so enabling the remote Engine API doesn't require looking up the steps elsewhere. +16. **Help page expansion** (`36a79ab`, same branch) — quick-start ordering card + real-world example callouts per page, for first-time users. ## Docker: three ways (PR #31) @@ -122,6 +134,6 @@ Moved to **`ROADMAP.md`** ("Known non-blocking stubs"). Summary: the Infrastruct 1. Read this file, then `ROADMAP.md` (deferred/tiered work), then `docs/` (subsystem design docs — `docker-agent-monitoring.md`, `mesh-prerequisite-gate.md`), then `TERMIX_MIGRATION.md` for feature-level history, then skim `git log --oneline -30`. 2. Frontend: prefer `npm run build` (`tsc -b && vite build`) over a plain `tsc --noEmit` (stricter, catches more). Backend: `npx tsc --noEmit -p .` from `backend/`. Both must pass before any commit. -3. **The next planned feature is the Mesh Prerequisite Gate** — designed in `docs/mesh-prerequisite-gate.md`, NOT built. It has open decisions (A–D) that **must be answered by the user before coding** (especially DECIDE D: defaulting the gate OFF so it doesn't lock the live production instance). Auth Phases 1-3 are done; Phase 4 SSO is a deferred paid AWS add-on (`ROADMAP.md`). +3. **The Mesh Prerequisite Gate is built and shipped** (Settings → Mesh; defaults OFF). **There is no other planned feature queued right now** — check the "→ NEXT TASK" section above first (merge decision on `claude/youthful-cerf-ibvxfb`), then ask the user for the next priority. Auth Phases 1-3 are done; Phase 4 SSO is a deferred paid AWS add-on (`ROADMAP.md`). 4. If asked to add a feature, follow existing patterns: integration adapters in `backend/src/integrations/`, SSH-backed engines in `backend/src/ssh/`, one route file per feature in `backend/src/routes/`, one `api.ts` entry + page component per frontend feature. Subsystem-level work gets a `docs/` design doc first. 5. For anything ambiguous in scope, use `AskUserQuestion` rather than guessing — that's how the auth phases, the Docker agent tiering, and the mesh-gate decisions were all scoped. diff --git a/README.md b/README.md index 4b842fb..27cb045 100644 --- a/README.md +++ b/README.md @@ -30,15 +30,16 @@ backend routes are built and working — there is no pending/on-hold page. Auth is feature-complete for self-hosted (Phases 1-3: user menu wiring, password/sessions/login-log, multi-user roles with a 10-seat cap); Phase 4 (Authentik SSO) is **deferred to a paid AWS add-on** — see `ROADMAP.md`. -Recently shipped: persistent terminal sessions across navigation, and Docker +Recently shipped: persistent terminal sessions across navigation, Docker container visibility/management three ways (Engine TCP API, `docker` CLI over -SSH, and a read-only push agent — see `docs/docker-agent-monitoring.md`). +SSH, and a read-only push agent — see `docs/docker-agent-monitoring.md`), and +the **Mesh Prerequisite Gate** — a universal CIDR-based mesh-verification +requirement (with a routed-mesh/VPC-peering fallback, not NetBird-specific), +configurable from Settings → Mesh and defaulting OFF so it can't lock the live +instance. -The **next planned feature is the Mesh Prerequisite Gate** — requiring a -verified NetBird mesh before the app can be configured. It is **designed but -not built** (`docs/mesh-prerequisite-gate.md`) and has open decisions that need -the user's sign-off before coding (notably defaulting it OFF so it can't lock -the live instance). See `HANDOFF.md` for where to resume. +There is no feature currently in progress. See `HANDOFF.md` for the latest +status and next steps. If you're a fresh AI session: read this file, then `HANDOFF.md` (current task state + standing workflow rules), then `design-decisions.md` (visual