@jhizzard/termdeck 1.8.1 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"
@@ -8,6 +8,7 @@
   "main": "packages/cli/src/index.js",
   "files": [
     "packages/cli/src/**",
+    "packages/cli/assets/**",
     "packages/cli/templates/**",
     "packages/server/src/**",
     "packages/server/share/**",

package/packages/cli/assets/supervise/com.jhizzard.termdeck-supervise.plist

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  TermDeck stack supervisor — runs termdeck-supervise.sh every 60s and at
+  login, keeping the server / Mnestra webhook / cloudflared tunnel / MCP
+  bridge alive.
+
+  Staged by `termdeck init --bridge` from the vendored package asset
+  (packages/cli/assets/supervise/) with the __TERMDECK_*__ tokens resolved
+  for this machine at stage time. Structural source of truth:
+  scripts/com.jhizzard.termdeck-supervise.plist in the repo — keep the dict
+  keys in lockstep (pinned by packages/cli/tests/init-bridge.test.js).
+
+  The wizard copies this file into ~/Library/LaunchAgents/ but NEVER loads
+  it; the operator runs:
+    launchctl load -w ~/Library/LaunchAgents/com.jhizzard.termdeck-supervise.plist
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.jhizzard.termdeck-supervise</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>__TERMDECK_SUPERVISE_SCRIPT__</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StartInterval</key>
+  <integer>60</integer>
+  <key>StandardOutPath</key>
+  <string>__TERMDECK_HOME__/.termdeck/logs/supervise.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>__TERMDECK_HOME__/.termdeck/logs/supervise.err.log</string>
+  <key>ProcessType</key>
+  <string>Background</string>
+</dict>
+</plist>

package/packages/cli/assets/supervise/termdeck-supervise.service

@@ -0,0 +1,27 @@
+# TermDeck stack supervisor — one tick of termdeck-supervise.sh.
+# Staged by `termdeck init --bridge` from the vendored package asset
+# (packages/cli/assets/supervise/) with the __TERMDECK_*__ tokens resolved
+# for this machine at stage time. Structural source of truth:
+# docs/examples/termdeck-supervise.service in the repo — keep in lockstep
+# (pinned by packages/cli/tests/init-bridge.test.js).
+#
+# Pair with termdeck-supervise.timer (60s cadence); the timer is what keeps
+# the stack alive, this unit is a single idempotent pass. The wizard copies
+# both files into ~/.config/systemd/user/ but NEVER enables them; the
+# operator runs:
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now termdeck-supervise.timer
+#   loginctl enable-linger "$(whoami)"
+#
+# Logs: journalctl --user -u termdeck-supervise.service -n 50
+#       plus the script's own ~/.termdeck/logs/supervise.log
+
+[Unit]
+Description=TermDeck stack supervisor (one idempotent tick)
+
+[Service]
+Type=oneshot
+# systemd's minimal PATH hides npm-global bins (node, mnestra, termdeck) and
+# often cloudflared — prepend the usual homes. Same pitfall as termdeck.service.
+Environment="PATH=%h/.npm-global/bin:%h/.local/bin:/usr/local/bin:/usr/bin:/bin"
+ExecStart=/bin/bash __TERMDECK_SUPERVISE_SCRIPT__

package/packages/cli/assets/supervise/termdeck-supervise.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# termdeck-supervise.sh — keep the TermDeck stack self-healing.
+#
+# Ensures (and restarts if down) the four daily-driver processes. Every check is
+# by PORT, never by process-arg path — `pgrep -f 'mcp-bridge/src/server.js'` is a
+# known false-negative because the bridge's argv is just `node src/server.js`.
+#   1. TermDeck server     :3000
+#   2. Mnestra webhook     :37778
+#   3. cloudflared tunnel  (public HTTPS → :8870; named = stable URL, quick = ephemeral)
+#   4. MCP bridge          :8870  (re-pinned to the CURRENT tunnel URL via /healthz drift check)
+#
+# Idempotent: run once to bring the stack up; run on a timer (launchd/cron) to
+# keep it up. State lives in ~/.termdeck: a STABLE operator secret + the current
+# public URL + per-component logs. A stable secret means a bridge restart never
+# silently changes the consent secret; the URL file means the bridge always
+# re-pins to wherever the tunnel currently is.
+#
+# Config (env, or ~/.termdeck/supervisor.env):
+#   TERMDECK_REPO_DIR          default: derived from this script's location
+#   TERMDECK_SECRETS_ENV       default: ~/.termdeck/secrets.env
+#   TERMDECK_TUNNEL_NAME       a named cloudflared tunnel → STABLE url (recommended once you
+#                              have a Cloudflare domain). Unset ⇒ ephemeral quick tunnel.
+#   TERMDECK_PUBLIC_HOSTNAME   the https host routed to the named tunnel (required if NAME set)
+#   TERMDECK_BRIDGE_ALLOWLIST_PROJECTS  default '*' (panels visible to web chats; still approval-gated)
+#   TERMDECK_SUPERVISE_DRY_RUN=1   log intended actions, start/kill NOTHING (safe to test live)
+set -uo pipefail
+
+STATE_DIR="${HOME}/.termdeck"
+LOG_DIR="${STATE_DIR}/logs"
+mkdir -p "$LOG_DIR"
+# Operator overrides first, then defaults.
+if [ -f "${STATE_DIR}/supervisor.env" ]; then set -a; . "${STATE_DIR}/supervisor.env"; set +a; fi
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="${TERMDECK_REPO_DIR:-$(cd "${SELF_DIR}/.." && pwd)}"
+SECRETS_ENV="${TERMDECK_SECRETS_ENV:-${STATE_DIR}/secrets.env}"
+SECRET_FILE="${STATE_DIR}/bridge-operator-secret.txt"
+URL_FILE="${STATE_DIR}/bridge-public-url.txt"
+ALLOWLIST_PROJECTS="${TERMDECK_BRIDGE_ALLOWLIST_PROJECTS:-*}"
+DRY="${TERMDECK_SUPERVISE_DRY_RUN:-0}"
+
+ts()  { date '+%Y-%m-%dT%H:%M:%S%z'; }
+log() { echo "[$(ts)] $*" | tee -a "${LOG_DIR}/supervise.log" >&2; }
+port_up() { lsof -nP -iTCP:"$1" -sTCP:LISTEN >/dev/null 2>&1; }
+would() { [ "$DRY" = "1" ]; }
+
+ensure_secret() {
+  [ -s "$SECRET_FILE" ] && return 0
+  would && { log "DRY: would generate a stable operator secret at $SECRET_FILE"; return 0; }
+  ( umask 077; openssl rand -hex 16 > "$SECRET_FILE" )
+  log "generated a stable operator secret at $SECRET_FILE"
+}
+
+start_server() {
+  port_up 3000 && return 0
+  would && { log "DRY: would START TermDeck server :3000"; return 0; }
+  log "TermDeck server :3000 DOWN — starting"
+  ( cd "$REPO_DIR" || exit 1
+    set -a; [ -f "$SECRETS_ENV" ] && . "$SECRETS_ENV"; set +a
+    nohup node packages/server/src/index.js >>"${LOG_DIR}/server.log" 2>&1 & )
+}
+
+start_webhook() {
+  port_up 37778 && return 0
+  would && { log "DRY: would START Mnestra webhook :37778"; return 0; }
+  log "Mnestra webhook :37778 DOWN — starting"
+  ( set -a; [ -f "$SECRETS_ENV" ] && . "$SECRETS_ENV"; set +a
+    MNESTRA_WEBHOOK_PORT=37778 nohup mnestra serve >>"${LOG_DIR}/mnestra.log" 2>&1 & )
+}
+
+tunnel_up() { pgrep -f 'cloudflared tunnel' >/dev/null 2>&1; }
+
+start_tunnel() {
+  if [ -n "${TERMDECK_TUNNEL_NAME:-}" ]; then
+    tunnel_up && return 0
+    would && { log "DRY: would START named tunnel '${TERMDECK_TUNNEL_NAME}'"; return 0; }
+    log "named cloudflared tunnel '${TERMDECK_TUNNEL_NAME}' DOWN — starting (stable URL)"
+    nohup cloudflared tunnel run "${TERMDECK_TUNNEL_NAME}" >>"${LOG_DIR}/cloudflared.log" 2>&1 &
+    echo "https://${TERMDECK_PUBLIC_HOSTNAME:?set TERMDECK_PUBLIC_HOSTNAME for a named tunnel}" > "$URL_FILE"
+    return 0
+  fi
+  tunnel_up && [ -s "$URL_FILE" ] && return 0
+  would && { log "DRY: would START quick tunnel + capture trycloudflare URL"; return 0; }
+  log "quick cloudflared tunnel DOWN — starting + capturing URL"
+  : > "${LOG_DIR}/cloudflared.log"
+  nohup cloudflared tunnel --url http://127.0.0.1:8870 >>"${LOG_DIR}/cloudflared.log" 2>&1 &
+  for _ in $(seq 1 40); do
+    local url; url=$(grep -oE 'https://[a-z0-9-]+\.trycloudflare\.com' "${LOG_DIR}/cloudflared.log" 2>/dev/null | head -1)
+    [ -n "$url" ] && { echo "$url" > "$URL_FILE"; log "tunnel URL captured: $url"; return 0; }
+    sleep 1
+  done
+  log "WARN: quick tunnel URL did not appear within 40s"
+}
+
+bridge_resource() {
+  curl -s --max-time 5 http://127.0.0.1:8870/healthz 2>/dev/null \
+    | sed -n 's/.*"resource":"\([^"]*\)".*/\1/p'
+}
+
+start_bridge() {
+  local pub; pub="$(cat "$URL_FILE" 2>/dev/null || true)"
+  [ -z "$pub" ] && { log "no public URL yet — skipping bridge"; return 1; }
+  local want="${pub%/}/mcp"
+  if port_up 8870; then
+    [ "$(bridge_resource)" = "$want" ] && return 0
+    would && { log "DRY: would RESTART bridge (URL drift → $want)"; return 0; }
+    log "bridge URL drift — restarting to re-pin $want"
+    lsof -nP -ti TCP:8870 -sTCP:LISTEN 2>/dev/null | xargs kill 2>/dev/null || true
+    sleep 1
+  else
+    would && { log "DRY: would START MCP bridge :8870 (url=$want)"; return 0; }
+    log "MCP bridge :8870 DOWN — starting"
+  fi
+  ensure_secret
+  ( cd "${REPO_DIR}/packages/mcp-bridge" || exit 1
+    TERMDECK_BRIDGE_PUBLIC_URL="$pub" \
+    TERMDECK_BRIDGE_OPERATOR_SECRET="$(cat "$SECRET_FILE")" \
+    MNESTRA_WEBHOOK_URL="http://localhost:37778/mnestra" \
+    TERMDECK_API_BASE="http://127.0.0.1:3000" \
+    TERMDECK_BRIDGE_ALLOWLIST_PROJECTS="$ALLOWLIST_PROJECTS" \
+    nohup node src/server.js >>"${LOG_DIR}/bridge.log" 2>&1 & )
+}
+
+# Adopt an already-running stack: if we don't yet know the public URL but the
+# bridge is already serving, learn it from /healthz (so we never spawn a second
+# tunnel over a healthy one). Recording the URL is metadata-only — safe in dry-run.
+adopt_url() {
+  [ -s "$URL_FILE" ] && return 0
+  port_up 8870 || return 0
+  local res; res="$(bridge_resource)"
+  [ -z "$res" ] && return 0
+  echo "${res%/mcp}" > "$URL_FILE"
+  log "adopted existing bridge public URL: ${res%/mcp}"
+}
+
+main() {
+  log "supervise tick (dry=$DRY) — repo=$REPO_DIR"
+  start_server
+  start_webhook
+  adopt_url
+  start_tunnel
+  start_bridge
+  log "state: server=$(port_up 3000 && echo up || echo DOWN) webhook=$(port_up 37778 && echo up || echo DOWN) bridge=$(port_up 8870 && echo up || echo DOWN) url=$(cat "$URL_FILE" 2>/dev/null || echo none)"
+}
+
+main "$@"

package/packages/cli/assets/supervise/termdeck-supervise.timer

@@ -0,0 +1,14 @@
+# 60s cadence for termdeck-supervise.service — see that unit's header for the
+# install recipe. Enable the TIMER, not the service:
+#   systemctl --user enable --now termdeck-supervise.timer
+
+[Unit]
+Description=Run the TermDeck stack supervisor every 60s
+
+[Timer]
+OnBootSec=30
+OnUnitActiveSec=60
+AccuracySec=5
+
+[Install]
+WantedBy=timers.target

package/packages/cli/src/doctor.js

@@ -346,6 +346,16 @@ async function _runSchemaCheck(opts = {}) {
   let client = optsObj._pgClient || null;
   let ownsClient = false;
   if (!client) {
+    // Sprint 75 T2 (part C): classify + warn BEFORE the connect attempt —
+    // a direct-endpoint URL on an IPv4-only host doesn't fail fast, it
+    // hangs until a pool timeout, so the warning must print first.
+    // Warn-only; fail-soft if the helper is unavailable.
+    try {
+      const urlHelper = require(path.join(SETUP_DIR, 'supabase-url'));
+      for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(secrets.DATABASE_URL))) {
+        process.stdout.write(`  ${line}\n`);
+      }
+    } catch (_e) { /* warn-only — never block the doctor pass */ }
     try {
       client = await pgRunner.connect(secrets.DATABASE_URL);
       ownsClient = true;
@@ -524,6 +534,7 @@ function renderSchemaResult(result, c) {
   if (result.connectError) {
     out.push(`  ${c.yellow('✗')} could not connect: ${result.connectError}`);
     out.push(`  ${c.dim('Check DATABASE_URL in ~/.termdeck/secrets.env, then re-run.')}`);
+    out.push(`  ${c.dim('If this host is IPv4-only and the URL is the db.<project-ref> direct endpoint, that is the cause — switch to the Shared Pooler.')}`);
     return out.join('\n');
   }
   for (const section of result.sections) {

package/packages/cli/src/index.js

@@ -5,6 +5,7 @@
 //   termdeck [--port 3000] [--no-open]
 //   termdeck init --mnestra [flags]   # Tier 2 memory setup (wired to init-mnestra.js)
 //   termdeck init --rumen  [flags]   # Tier 3 async learning deploy
+//   termdeck init --bridge [flags]   # Tier 5 web-chat bridge (named tunnel + supervisor)
 //
 // Note (Sprint 3): the `--mnestra` flag name matches the current init-mnestra.js
 // filename. When the main orchestrator completes the Mnestra → Mnestra rename
@@ -223,7 +224,7 @@ if (args[0] === 'init') {
   // silently picking the first. The `--auto` / `--mcp-supabase` flags are
   // NOT in this list — they're handled by init.js (the orchestrator) and
   // can co-exist with init.js's own flag set.
-  const MODES = ['--project', '--mnestra', '--rumen'];
+  const MODES = ['--project', '--mnestra', '--rumen', '--bridge'];
   const presentModes = MODES.filter((m) => args.slice(1).includes(m));
   if (presentModes.length > 1) {
     console.error(`[cli] init: pass only one of ${MODES.join(' | ')}; got ${presentModes.join(' + ')}`);
@@ -257,6 +258,16 @@ if (args[0] === 'init') {
     });
     return;
   }
+  // Sprint 73 T2: Tier 5 web-chat bridge wizard. MUST dispatch here, above
+  // the leading-dash catch-all below — otherwise `init --bridge` would
+  // silently route into the unified init.js orchestrator.
+  if (mode === '--bridge') {
+    run(path.join(__dirname, 'init-bridge.js'), rest).catch((err) => {
+      console.error('[cli] init --bridge failed:', err && err.stack || err);
+      process.exit(1);
+    });
+    return;
+  }
 
   // Sprint 64 T1: default (no mode) OR `--auto` / `--mcp-supabase` → route to
   // the unified orchestrator at init.js. It runs init-mnestra + init-rumen +
@@ -282,11 +293,12 @@ if (args[0] === 'init') {
     });
     return;
   }
-  console.error('Usage: termdeck init [--auto] | --mnestra | --rumen | --project <name>');
+  console.error('Usage: termdeck init [--auto] | --mnestra | --rumen | --bridge | --project <name>');
   console.error('  termdeck init                       Unified setup (Mnestra + Rumen + doctor)');
   console.error('  termdeck init --auto                Auto-provision via Supabase MCP (alias: --mcp-supabase)');
   console.error('  termdeck init --mnestra             Configure Tier 2 memory (Supabase + Mnestra)');
   console.error('  termdeck init --rumen               Deploy Tier 3 async learning (Rumen)');
+  console.error('  termdeck init --bridge              Scaffold Tier 5 web-chat bridge (named tunnel + supervisor)');
   console.error('  termdeck init --project <name>      Scaffold a new project with CLAUDE.md + orchestration docs');
   console.error('  termdeck init --help                Show full flag reference');
   process.exit(1);
@@ -388,6 +400,7 @@ for (let i = 0; i < args.length; i++) {
     termdeck --session-logs     Write per-session markdown logs to ~/.termdeck/sessions/
     termdeck init --mnestra     Configure Tier 2 memory (Supabase + Mnestra)
     termdeck init --rumen       Deploy Tier 3 async learning (Rumen)
+    termdeck init --bridge      Scaffold Tier 5 web-chat bridge (named tunnel + supervisor)
     termdeck init --project NAME  Scaffold a new project with CLAUDE.md + orchestration docs (--dry-run, --force)
     termdeck forge              Generate Claude skills from memories (experimental)
     termdeck doctor             Diagnose stack — npm versions + Supabase schema (use --no-schema to skip the DB probe)