propr-cli 0.8.4 → 0.8.6

package/README.md

@@ -60,6 +60,42 @@ and exits nonzero when required local stack prerequisites are missing. Scripts
 or shell integrations that invoked bare `propr` to print help text should call
 `propr --help` instead.
 
+## Hosted UI Tunnel
+
+ProPR Connect can provision a managed Cloudflare Tunnel so the hosted UI at
+`https://app.propr.dev` can reach your local stack's API. Run the one-time setup
+command shown in ProPR Connect from your initialized stack directory:
+
+```bash
+npm install -g propr-cli@latest
+propr tunnel setup --token <connector-token> --url https://t-<id>.propr.dev --start
+```
+
+Connect-managed tunnels require `propr-cli` 0.8.6 or newer. The setup command
+writes the tunnel token, instance id, hosted UI origin, public API URL, and
+OAuth callback URL to the stack `.env`, records tunnel mode as enabled, and with
+`--start` starts or recreates the stack so the API picks up the hosted URLs
+immediately. If you have only the instance id, `--instance-id <id>` derives the
+same public URL.
+
+The public tunnel origin is always a bare `https://t-<id>.propr.dev` URL; ProPR
+routes only `/api/*` and `/socket.io/*` through it, and the root URL
+intentionally returns 404. The hosted UI itself stays on `https://app.propr.dev`
+and calls the API through the per-instance tunnel host.
+
+Useful follow-up commands:
+
+```bash
+propr tunnel verify      # check cloudflared + /api/status, /, /socket.io/
+propr tunnel off         # stop only the sidecar; token/env values stay in .env
+propr tunnel on          # restart the sidecar later
+```
+
+`propr tunnel off` intentionally leaves the Connect-written `.env` values in
+place. If you are switching the same stack back to a local or custom self-hosted
+UI, remove or replace `PROPR_UI_PUBLIC_API_URL`, `API_PUBLIC_URL`,
+`FRONTEND_URL`, and `GH_OAUTH_CALLBACK_URL` before restarting.
+
 ## Repository Setup
 
 Use `propr init` from a repository root to scaffold `.propr` setup files used by agent execution containers.

package/dist/assets/.env.example

@@ -0,0 +1,183 @@
+# GitHub App Configuration
+GH_APP_ID=your_app_id
+GH_PRIVATE_KEY_PATH=./path/to/your-app-private-key.pem
+GH_INSTALLATION_ID=your_installation_id
+
+# Host path to the GitHub App private key (.pem). Recommended when running via
+# the `propr` CLI or launcher: the key is bind-mounted (read-only) into the app
+# containers and GH_PRIVATE_KEY_PATH above is overridden to point at it, so you
+# can keep the key anywhere on the host instead of staging it under data/.
+# Must be an absolute host path (no '~').
+# HOST_GH_PRIVATE_KEY=/home/your-user/propr/app-private-key.pem
+
+# GitHub auth: token relay (shared-app path) — ALTERNATIVE to the App private key
+# above. When PROPR_GH_RELAY_URL is set, the backend fetches short-lived
+# installation tokens from a vendor-run relay instead of minting them from a
+# private key, so you don't need to hold the shared App's key. You still set
+# GH_INSTALLATION_ID (which installation), but GH_PRIVATE_KEY_PATH /
+# HOST_GH_PRIVATE_KEY are not required in relay mode.
+#   PROPR_GH_RELAY_URL   — https URL of the relay (http only allowed for localhost)
+#   PROPR_GH_RELAY_TOKEN — the durable relay credential issued for your install
+# PROPR_GH_RELAY_URL=https://relay.propr.dev
+# PROPR_GH_RELAY_TOKEN=your_relay_token
+# Optional: force a mode explicitly instead of inferring (app | relay | demo).
+# GH_AUTH_MODE=relay
+
+# Logging Configuration
+LOG_LEVEL=info
+NODE_ENV=development
+
+# Daemon Configuration
+GITHUB_REPOS_TO_MONITOR=owner/repo1,owner/repo2
+POLLING_INTERVAL_MS=60000
+
+# Config Repository (for dynamic repository management)
+CONFIG_REPO=https://github.com/integry/gitfix-config.git
+
+# Issue Detection Configuration
+PRIMARY_PROCESSING_LABELS=AI,propr
+PR_LABEL=propr
+
+# Redis Configuration
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+
+# Queue Configuration
+GITHUB_ISSUE_QUEUE_NAME=github-issue-processor
+WORKER_CONCURRENCY=2
+COMMENT_BATCH_DELAY_MS=3000
+
+# Webhook Configuration
+# Webhooks are received by the dashboard API service (port 4000)
+ENABLE_GITHUB_WEBHOOKS=false
+GH_WEBHOOK_SECRET=your-webhook-secret
+
+# System Task Authorization
+# Secret used to sign system task requests (e.g., revert operations)
+# Generate with: openssl rand -hex 32
+SYSTEM_TASK_SECRET=
+# Maximum age (ms) for signed system task tokens. Increase if jobs frequently expire
+# due to queue backlog or worker downtime. Defaults to 7200000 (2 hours).
+# SYSTEM_TASK_TOKEN_MAX_AGE_MS=7200000
+
+# Worker Configuration
+
+# PR Comment Monitoring Configuration
+GITHUB_BOT_USERNAME=your_bot_username
+GITHUB_USER_WHITELIST=
+GITHUB_USER_BLACKLIST=
+PR_FOLLOWUP_TRIGGER_KEYWORDS=!propr
+
+# Git Configuration
+GIT_CLONES_BASE_PATH=/tmp/git-processor/clones
+GIT_WORKTREES_BASE_PATH=/tmp/git-processor/worktrees
+GIT_DEFAULT_BRANCH=main
+GIT_SHALLOW_CLONE_DEPTH=
+
+# Claude Code Configuration
+CLAUDE_DOCKER_IMAGE=propr/agent-claude:latest
+# Must be an absolute path — do NOT use ~ or ${HOME} (neither is expanded in
+# .env files parsed by Node or in Docker bind mounts).
+# CLAUDE_CONFIG_PATH=/home/your-user/.claude
+CLAUDE_CONFIG_PATH=
+CLAUDE_MAX_TURNS=10
+CLAUDE_TIMEOUT_MS=300000
+CODEX_TIMEOUT_MS=3600000
+
+# Antigravity Configuration
+ANTIGRAVITY_TIMEOUT_MS=300000
+
+# OpenCode Configuration
+OPENCODE_TIMEOUT_MS=3600000
+# Launcher credential mount paths (required when using docker/launcher).
+# HOST_OPENCODE_XDG_DIR points to the XDG config directory
+# (/home/your-user/.config/opencode)
+# and takes precedence over HOST_OPENCODE_DIR.
+# HOST_OPENCODE_DIR is accepted as a fallback alias for HOST_OPENCODE_XDG_DIR.
+# HOST_OPENCODE_LEGACY_DIR points to the legacy /home/your-user/.opencode directory.
+# The saved agent configPath still controls the runtime mount; the launcher
+# sets OPENCODE_CONFIG_PATH only as the default path for worker/API processes.
+# HOST_OPENCODE_DATA_DIR points to normal opencode auth data
+# (/home/your-user/.local/share/opencode). Set it for launcher deployments
+# so normal `opencode auth login` credentials are visible to spawned OpenCode
+# agent containers and can refresh auth metadata when required.
+# HOST_OPENCODE_XDG_DIR=/home/your-user/.config/opencode
+# HOST_OPENCODE_DIR=/home/your-user/.config/opencode
+# HOST_OPENCODE_LEGACY_DIR=/home/your-user/.opencode
+# HOST_OPENCODE_DATA_DIR=/home/your-user/.local/share/opencode
+
+# --- Mistral Vibe Configuration (only required when using a Vibe agent) ---
+# Must be an absolute path — do NOT use ~ or ${HOME} (see CLAUDE_CONFIG_PATH note).
+# VIBE_CONFIG_PATH=/home/your-user/.vibe
+# Used when VIBE_CONFIG_PATH does not provide credentials.
+# MISTRAL_API_KEY=
+VIBE_MAX_TURNS=1000
+VIBE_TIMEOUT_MS=3600000
+# Production launcher only — host paths for mounting agent credential directories
+# into containers. Omit any HOST_*_DIR to skip mounts for that agent.
+# All HOST_*_DIR values MUST be absolute paths (no ~ or relative paths).
+# HOST_CLAUDE_DIR=/home/your-user/.claude
+# HOST_CODEX_DIR=/home/your-user/.codex
+# HOST_ANTIGRAVITY_DIR=/home/your-user/.antigravity
+# HOST_VIBE_DIR=/home/your-user/.vibe
+# Required for Vibe Docker-outside-Docker: prompt files must be written to a
+# host-visible directory so spawned agent containers can bind-mount them.
+# Both should reference the same host path.
+# NOTE: These are required whenever Vibe agents are used with the launcher
+# (i.e. when MISTRAL_API_KEY is set), not only when HOST_VIBE_DIR is set.
+# Create the directory before starting: mkdir -p /tmp/propr-vibe-prompts
+# VIBE_PROMPT_CACHE_DIR=/tmp/propr-vibe-prompts
+# HOST_VIBE_PROMPT_CACHE_DIR=/tmp/propr-vibe-prompts
+
+# Dashboard API Configuration
+DASHBOARD_API_PORT=4000
+# Required in normal and demo mode for auth redirects.
+FRONTEND_URL=http://localhost:5173
+# Optional comma-separated redirect hosts for auth preview flows.
+# Entries are exact host matches by default. Prefix with "." or "*." only for
+# parent domains where every subdomain is trusted, for example .preview.example.com.
+# FRONTEND_URL is exact-only; COOKIE_DOMAIN allows subdomains when it starts with ".".
+# AUTH_REDIRECT_ALLOWED_HOSTS=preview.example.com
+
+# GitHub OAuth Configuration
+GH_OAUTH_CLIENT_ID=your_github_oauth_client_id
+GH_OAUTH_CLIENT_SECRET=your_github_oauth_client_secret
+GH_OAUTH_CALLBACK_URL=http://localhost:4000/api/auth/github/callback
+SESSION_SECRET=your-session-secret-here
+
+# Bearer Token Authentication (CLI)
+# Set to 'false' to disable Bearer token auth and only allow session-based login
+ENABLE_BEARER_AUTH=true
+
+# Demo Mode
+# Set to 'true' or '1' to allow read-only access without GitHub OAuth and block all mutating API requests.
+# Public demo deployments should use a curated config/database.
+PROPR_DEMO_MODE=false
+
+# --- SQLite Database ---
+# Path to SQLite database file (will be created if it doesn't exist)
+DB_FILENAME=./data/propr.sqlite
+
+# --- PR Preview Environment ---
+# Path to staging .env file (provides base configuration for PR previews)
+# PR-specific values (ports, API URLs) are passed as inline overrides
+STAGING_ENV_FILE=/path/to/staging/.env
+
+# Path to staging database file for seeding PR preview environments
+STAGING_DB_PATH=/path/to/staging/data/propr.sqlite
+
+# Enable preview environment routing (routes webhooks to PR preview instances)
+ENABLE_PREVIEW_ROUTING=false
+
+# The ProPR repository in 'owner/repo' format. Label events from this repo
+# trigger processor assignment changes. Defaults to 'integry/propr'.
+PROPR_REPO=integry/propr
+
+# The label that designates a ProPR PR as the active processor for webhook routing.
+# When this label is added to a ProPR repo PR, that PR's preview instance becomes
+# the active processor. Defaults to 'preview-env'.
+PROCESSOR_LABEL=preview-env
+
+# Host address for forwarding webhooks to PR preview instances.
+# Defaults to 'http://host.docker.internal' for Docker environments.
+# HOST_GATEWAY_ADDRESS=http://host.docker.internal

package/dist/assets/env.example.txt

@@ -31,6 +31,9 @@ GITHUB_EVENT_INTAKE_MODE=routing_websocket
 # only need them below to point at a self-hosted relay.
 # PROPR_ROUTING_URL=wss://webhook.propr.dev
 # PROPR_GH_RELAY_URL=https://webhook.propr.dev/v1
+# Optional transport keepalive override. The default is 300000 ms (5 minutes);
+# lower it only if a network path closes otherwise-healthy WebSockets too quickly.
+# PROPR_ROUTING_WS_PING_INTERVAL_MS=300000
 # Per-install secrets — left commented so an unedited copy is not mistaken for a
 # configured relay. Run `propr relay enroll` to fill these in, or uncomment and set
 # them by hand. (Active placeholder values here could make intake/auth mode look
@@ -42,6 +45,70 @@ GITHUB_EVENT_INTAKE_MODE=routing_websocket
 # are set, so you normally do not need this.
 # GH_AUTH_MODE=relay
 
+# --- Hosted UI tunnel (v1, optional) -----------------------------------------
+# Expose this local stack's API to the hosted control plane at
+# https://app.propr.dev through a Cloudflare Tunnel, so you can drive a
+# locally-running stack from the hosted UI. The tunnel publishes the API
+# container (only /api/* and /socket.io/* are routed; the root URL returns 404);
+# the UI bundle is served by app.propr.dev, not through the tunnel. Cloudflare
+# forwards the tunnel to the Docker-internal http://api:4000, NOT host port 4000,
+# so the published host port is irrelevant to the tunnel and cannot conflict with
+# it. Off by default; local development is unaffected (API_PUBLIC_URL /
+# FRONTEND_URL keep their localhost defaults below).
+#
+# Normal setup is CLI-first: ProPR Connect shows a one-time command such as
+# `propr tunnel setup --token ... --url https://<id>.proxy.propr.dev --start`.
+# Run that from this stack directory so the CLI writes these values and restarts
+# the stack for you. The variables below are documented as a fallback for older
+# CLI versions, manual recovery, or auditing what the setup command persists.
+#
+# Enable the tunnel:
+#   PROPR_UI_TUNNEL_TOKEN   — Cloudflare Tunnel token; required to start. Setting it
+#                             enables the tunnel by default, so the next `propr start`
+#                             brings up the sidecar (unless you ran `propr tunnel off`).
+#                             WARNING: this is a LIVE Cloudflare credential — anyone
+#                             with it can route traffic through your tunnel. Do not
+#                             commit, log, or share it; keep it in this .env only.
+#   PROPR_UI_TUNNEL_ENABLED — explicitly enable the tunnel (`true`/`1`). A token is
+#                             STILL required — `propr check` fails if this is set
+#                             without PROPR_UI_TUNNEL_TOKEN. Redundant when a token
+#                             is set, since a token alone already enables the tunnel
+#   PROPR_INSTANCE_ID       — this stack's instance id; must be a valid DNS label
+#                             (letters, digits, hyphens; 1-63 chars). Derives the
+#                             public URL https://<id>.proxy.propr.dev when no
+#                             explicit URL is set
+#   PROPR_UI_PUBLIC_API_URL — explicit public API URL the hosted UI talks to (overrides the derived one)
+#   PROPR_CLOUDFLARED_IMAGE — cloudflared image (default: cloudflare/cloudflared:2024.12.2,
+#                             a pinned tag; override only if you need a different build)
+# PROPR_UI_TUNNEL_TOKEN=your_cloudflare_tunnel_token
+# PROPR_INSTANCE_ID=abc123
+# PROPR_UI_PUBLIC_API_URL=https://abc123.proxy.propr.dev
+# PROPR_CLOUDFLARED_IMAGE=cloudflare/cloudflared:2024.12.2
+#
+# Why `.proxy.propr.dev`: each enabled stack is published under a per-instance
+# hostname `<PROPR_INSTANCE_ID>.proxy.propr.dev`. The hosted UI at
+# https://app.propr.dev discovers and reaches your stack's API through that
+# single shared suffix, without you owning or registering a domain.
+#
+# Browser origin vs API host — they are DIFFERENT and must be set accordingly.
+# The browser loads the UI from app.propr.dev; the API, Socket.IO, OAuth
+# callback, and session cookie all live on the proxy host. In tunnel mode
+# FRONTEND_URL, API_PUBLIC_URL, and GH_OAUTH_CALLBACK_URL are derived
+# automatically (FRONTEND_URL -> https://app.propr.dev, API_PUBLIC_URL -> the
+# proxy host, GH_OAUTH_CALLBACK_URL -> <proxy host>/api/auth/github/callback);
+# set them only to override. You must still register the callback URL — derived
+# or explicit — in your GitHub OAuth App.
+# FRONTEND_URL=https://app.propr.dev
+# API_PUBLIC_URL=https://abc123.proxy.propr.dev
+# GH_OAUTH_CALLBACK_URL=https://abc123.proxy.propr.dev/api/auth/github/callback
+#
+# COOKIE_DOMAIN: leave UNSET for v1. The session cookie is host-only on the
+# single `<id>.proxy.propr.dev` host — correct because that host and
+# app.propr.dev share the propr.dev registrable domain (same-site). Setting
+# COOKIE_DOMAIN (e.g. `.proxy.propr.dev`) would scope the cookie across every
+# instance's subdomain and is not supported for v1 proxy sessions.
+# COOKIE_DOMAIN=
+
 # Logging Configuration
 LOG_LEVEL=info
 NODE_ENV=development
@@ -191,8 +258,21 @@ VIBE_TIMEOUT_MS=3600000
 
 # Dashboard API Configuration
 DASHBOARD_API_PORT=4000
-# Required in normal and demo mode for auth redirects.
-FRONTEND_URL=http://localhost:5173
+# Browser origin: required in normal and demo mode for CORS and auth redirects.
+# Defaults to http://localhost:5173 when unset. In hosted UI tunnel mode this is
+# derived automatically as the hosted UI origin (https://app.propr.dev) — NOT the
+# proxy host — so leave it COMMENTED to let derivation win. An uncommented value
+# here always overrides the derived origin (set one only to force a custom
+# origin). See the "Hosted UI tunnel" section above.
+# FRONTEND_URL=http://localhost:5173
+# Public URL the API is reached at (auth redirects, attachment links, cookie
+# security). Defaults to http://localhost:4000 when unset; set it to the
+# https://<id>.proxy.propr.dev host when the hosted UI tunnel is enabled.
+# API_PUBLIC_URL=http://localhost:4000
+# Session cookie domain. Leave UNSET for v1 — including hosted UI tunnel proxy
+# sessions, which run on a single <id>.proxy.propr.dev host (see the tunnel
+# section above). Only set it for a custom multi-subdomain deployment.
+# COOKIE_DOMAIN=
 # Optional comma-separated redirect hosts for auth preview flows.
 # Entries are exact host matches by default. Prefix with "." or "*." only for
 # parent domains where every subdomain is trusted, for example .preview.example.com.
@@ -200,9 +280,16 @@ FRONTEND_URL=http://localhost:5173
 # AUTH_REDIRECT_ALLOWED_HOSTS=preview.example.com
 
 # GitHub OAuth Configuration
+# The OAuth callback is served by the API and is derived automatically when left
+# unset: <proxy host>/api/auth/github/callback in hosted UI tunnel mode, or
+# http://localhost:4000/api/auth/github/callback for local development. Leave it
+# commented so enabling the tunnel (token/instance id) cannot leave a stale
+# localhost callback that breaks hosted OAuth — an active localhost value is used
+# as-is even in tunnel mode (the launcher only warns). Uncomment to override; then
+# register that exact URL in your GitHub OAuth App.
 GH_OAUTH_CLIENT_ID=your_github_oauth_client_id
 GH_OAUTH_CLIENT_SECRET=your_github_oauth_client_secret
-GH_OAUTH_CALLBACK_URL=http://localhost:4000/api/auth/github/callback
+# GH_OAUTH_CALLBACK_URL=http://localhost:4000/api/auth/github/callback
 SESSION_SECRET=your-session-secret-here
 
 # Bearer Token Authentication (CLI)

package/dist/commands/index.js

@@ -20,5 +20,6 @@ export { createImagesCommand } from "./imageCommands.js";
 export { createStartCommand } from "./startCommand.js";
 export { createStackStatusCommand, createStopCommand } from "./stackCommands.js";
 export { createUiCommand, createDocsCommand } from "./uiDocsCommands.js";
+export { createTunnelCommand } from "./tunnelCommand.js";
 export { createTankCommand } from "./tankCommands.js";
 export { createRelayCommand } from "./relayCommands.js";

package/dist/commands/stackCommands.js

@@ -6,7 +6,7 @@
 import { Command } from "commander";
 import { createConfigManager } from "../config/index.js";
 import { getHostConfig } from "../orchestrator/index.js";
-import { renderStatusTable } from "../orchestrator/format.js";
+import { renderStatusTable, renderTunnelSection } from "../orchestrator/format.js";
 import { printOutput } from "../utils/index.js";
 /** Creates the `status` command — local stack status. */
 export function createStackStatusCommand() {
@@ -30,10 +30,22 @@ Examples:
                 process.exit(1);
             }
             const status = orch.getStackStatus(cfg);
-            if (printOutput(status, options.json ?? false))
+            // The Cloudflare tunnel is a local managed service, so its health is part
+            // of local status. The reachability probe is best-effort with its own
+            // timeout and never throws, so it cannot fail the status command.
+            const tunnel = await orch.getTunnelStatus(cfg, status);
+            if (printOutput({ ...status, tunnel }, options.json ?? false))
                 return;
             console.log("");
             console.log(renderStatusTable(status));
+            // The tunnel is an optional service most stacks never use. Only show the
+            // human-readable Tunnel section when it is configured or enabled, so the
+            // common case isn't cluttered with an all-"no" block. (The --json output
+            // above always includes the `tunnel` key for scripted consumers.)
+            if (tunnel.configured || tunnel.enabled) {
+                console.log("");
+                console.log(renderTunnelSection(tunnel));
+            }
             console.log("");
             if (!status.running) {
                 console.log("Stack is not running. Start it with: propr start");