ssh-portfolio/PLAN.md

SSH Portfolio Development Plan

This roadmap is based on the requested product: an anonymous, self-hostable SSH portfolio with modular pages, optional owner access, chat, notifications, live presence, and an owner-challenge Pong game.

Current state

The repository already has a working MVP with:

• Anonymous SSH none authentication.
• Optional signed public-key authentication for administrator mode.
• Modular page files in src/pages/ and command files in src/commands/.
• Configurable persona, colors, ports, and page content.
• Full-screen terminal page rendering, prompt editing, history, paste handling, and resize-aware headers.
• Live connected-user count.
• Visitor-to-visitor/owner chat broadcast.
• Owner presence based on an active admin SSH session.
• A localhost notification companion using newline-delimited JSON.
• PM2 deployment support.
• SQLite persistence for a moderated bulletin board and server-owned game leaderboards.
• ASCII Flappy and Pong commands, including bot play and a simple online Pong waiting queue.

The following items are incomplete, partial, or not implemented yet.

Phase 1 — MVP hardening

Priority: high

Configuration and page authoring

• Make page modules the single source of truth; clearly label the legacy config.pages content fallback.
• Add a page template such as src/pages/_template.js with comments and examples.
• Add page metadata: navigation order, aliases, visibility, required role, and short description.
• Add an optional data/-backed content mode for users who prefer editing JSON/Markdown instead of JavaScript.
• Validate configuration at startup and provide actionable errors for invalid colors, ports, keys, and page modules.

Terminal correctness

• Add automated tests for ANSI output, narrow terminals, resize events, history, paste, backspace, and simultaneous notifications.
• Handle terminal capability differences: color support, Unicode box-drawing fallback, and non-PTY ssh host command execution.
• Improve wide-character/emoji width calculation so boxes remain aligned with international text.
• Add graceful handling for disconnects, half-open sockets, and server shutdown.

Security and abuse controls

• Add per-IP connection limits, maximum concurrent sessions, idle timeouts, and chat rate limits.
• Bound input length and notification payload size.
• Add optional allow/deny lists and a configurable maintenance/read-only mode.
• Keep anonymous access enabled by default, but document isolation with a dedicated OS user/container.
• Add structured audit logs for admin authentication, admin commands, announcements, and rejected connections.

Phase 2 — Owner/admin experience

Priority: high

• Add an admin home/dashboard page showing connected users, owner presence, notification-client status, uptime, and recent activity.
• Add persistent admin commands for editing persona fields, themes, and page content with confirmation prompts.
• Add preview <page> and reload flows that preserve the current session cleanly.
• Add safe file writes with atomic replace, backups, and validation before applying edits.
• Add an admin-only user/session management view: list sessions, disconnect a session, mute a visitor, and ban an IP temporarily.
• Support multiple admin keys with labels and optional per-key roles.
• Add a documented admin page/command extension point for custom owner tools.

Phase 3 — Chat and notification system

Priority: high

SSH chat

• Add nicknames that are sanitized and scoped to each session.
• Add /who, /me, /mute, /unmute, and owner-direct-message semantics.
• Add moderation hooks, profanity filtering, message length limits, cooldowns, and a bounded in-memory history.
• Show clear owner availability and delivery status without claiming a message was read.

Companion client

• Add reconnect/backoff and graceful shutdown.
• Add OS notifications through adapters for Linux (notify-send), macOS, and Windows.
• Add a small configuration file for server address, forwarded port, notification preferences, and filtering.
• Authenticate the notification socket with a local secret or Unix socket option.
• Add optional reply support so the owner can answer from the companion client.
• Document SSH port forwarding and remote-owner deployment.

Phase 4 — Pong owner challenge

Priority: medium, bonus feature

• Add a modular pong command/page and a small terminal game engine independent of SSH transport.
• Only offer “challenge owner” when an admin session is online; otherwise offer practice mode against an AI.
• Create a matchmaking state machine: waiting, accepted, active, finished, abandoned, and timed out.
• Render the board using the negotiated terminal width/height and provide keyboard controls plus help text.
• Prevent game traffic from corrupting chat or prompt redraws.
• Add owner accept/decline controls and a configurable challenge cooldown.
• Add scores, best-of rounds, spectator mode, and optional persistent leaderboards.
• Test game state deterministically without requiring an SSH connection.

Phase 5 — Extensibility and “cool stuff”

Priority: medium/low

• Replace manual registries with a documented plugin loader while retaining explicit imports for predictable deployments.
• Add page transitions, an optional animated home banner, and a no-animation accessibility setting.
• Add portfolio utilities: downloadable resume, project detail pages, skills timeline, now page, guestbook, and RSS/Atom feed display.
• Add external integrations through opt-in adapters: GitHub projects, blog posts, uptime, weather, and currently-playing media.
• Add a tiny read-only HTTP status/health endpoint for monitoring.
• Add localization support and configurable date/time formatting.
• Add themes as reusable palettes, including high-contrast and monochrome presets.
• Add easter eggs and safe mini-games that do not require owner presence.

Phase 6 — Packaging and operations

Priority: medium

• Add a Dockerfile and Compose example with a non-root runtime user and persistent data volume.
• Add a PM2 ecosystem file with environment overrides, log paths, watch mode, and startup instructions.
• Add systemd and OpenRC examples for users who do not use PM2.
• Add health checks, log rotation guidance, and graceful zero-downtime restart documentation.
• Add CI for syntax checks, unit tests, packaging, and a smoke test that connects with an SSH client.
• Add release automation and a changelog.
• Add migration/versioning for data/config.json as the configuration schema evolves.

Suggested implementation order

1. Configuration validation, page template, tests, and terminal edge-case fixes.
2. Abuse controls and audit logging before public deployment.
3. Admin dashboard and persistent editing tools.
4. Chat moderation, notification reconnects, and OS notification adapters.
5. Pong engine and owner challenge flow.
6. Plugins, integrations, packaging, and cosmetic extras.

Definition of a production-ready release

• A fresh install can be configured without editing transport code.
• Anonymous visitors can browse pages safely from a standard SSH client.
• An owner can authenticate with a key without making authentication mandatory for visitors.
• Admin changes are validated, persisted safely, and recoverable from backups.
• Chat and notifications are rate-limited, observable, and resilient to disconnects.
• Pong cannot crash or corrupt other sessions.
• Docker/PM2/system-service deployment paths are documented and tested.