@thevinci/web 1.0.0

package/README.md

@@ -0,0 +1,197 @@
+# <picture><source media="(prefers-color-scheme: dark)" srcset="https://github.com/jaygupta17/vinci/raw/HEAD/docs/references/badges/vinci-logo-dark.svg"><img src="https://github.com/jaygupta17/vinci/raw/HEAD/docs/references/badges/vinci-logo-light.svg" width="32" height="32" align="absmiddle" /></picture> @thevinci/web
+
+[![GitHub stars](https://img.shields.io/github/stars/jaygupta17/vinci?style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgZmlsbD0iI2YxZWNlYyIgdmlld0JveD0iMCAwIDI1NiAyNTYiPjxwYXRoIGQ9Ik0yMjkuMDYsMTA4Ljc5bC00OC43LDQyLDE0Ljg4LDYyLjc5YTguNCw4LjQsMCwwLDEtMTIuNTIsOS4xN0wxMjgsMTg5LjA5LDczLjI4LDIyMi43NGE4LjQsOC40LDAsMCwxLTEyLjUyLTkuMTdsMTQuODgtNjIuNzktNDguNy00MkE4LjQ2LDguNDYsMCwwLDEsMzEuNzMsOTRMOTUuNjQsODguOGwyNC42Mi01OS42YTguMzYsOC4zNiwwLDAsMSwxNS40OCwwbDI0LjYyLDU5LjZMMjI0LjI3LDk0QTguNDYsOC40NiwwLDAsMSwyMjkuMDYsMTA4Ljc5WiIgb3BhY2l0eT0iMC4yIj48L3BhdGg%2BPHBhdGggZD0iTTIzOS4xOCw5Ny4yNkExNi4zOCwxNi4zOCwwLDAsMCwyMjQuOTIsODZsLTU5LTQuNzZMMTQzLjE0LDI2LjE1YTE2LjM2LDE2LjM2LDAsMCwwLTMwLjI3LDBMOTAuMTEsODEuMjMsMzEuMDgsODZhMTYuNDYsMTYuNDYsMCwwLDAtOS4zNywyOC44Nmw0NSwzOC44M0w1MywyMTEuNzVhMTYuMzgsMTYuMzgsMCwwLDAsMjQuNSwxNy44MkwxMjgsMTk4LjQ5bDUwLjUzLDMxLjA4QTE2LjQsMTYuNCwwLDAsMCwyMDMsMjExLjc1bC0xMy43Ni01OC4wNyw0NS0zOC44M0ExNi40MywxNi40MywwLDAsMCwyMzkuMTgsOTcuMjZabS0xNS4zNCw1LjQ3LTQ4LjcsNDJhOCw4LDAsMCwwLTIuNTYsNy45MWwxNC44OCw2Mi44YS4zNy4zNywwLDAsMS0uMTcuNDhjLS4xOC4xNC0uMjMuMTEtLjM4LDBsLTU0LjcyLTMzLjY1YTgsOCwwLDAsMC04LjM4LDBMNjkuMDksMjE1Ljk0Yy0uMTUuMDktLjE5LjEyLS4zOCwwYS4zNy4zNywwLDAsMS0uMTctLjQ4bDE0Ljg4LTYyLjhhOCw4LDAsMCwwLTIuNTYtNy45MWwtNDguNy00MmMtLjEyLS4xLS4yMy0uMTktLjEzLS41cy4xOC0uMjcuMzMtLjI5bDYzLjkyLTUuMTZBOCw4LDAsMCwwLDEwMyw5MS44NmwyNC42Mi01OS42MWMuMDgtLjE3LjExLS4yNS4zNS0uMjVzLjI3LjA4LjM1LjI1TDE1Myw5MS44NmE4LDgsMCwwLDAsNi43NSw0LjkybDYzLjkyLDUuMTZjLjE1LDAsLjI0LDAsLjMzLjI5UzIyNCwxMDIuNjMsMjIzLjg0LDEwMi43M1oiPjwvcGF0aD48L3N2Zz4%3D&logoColor=FFFCF0&labelColor=100F0F&color=66800B)](https://github.com/jaygupta17/vinci/stargazers)
+[![GitHub release](https://img.shields.io/github/v/release/jaygupta17/vinci?style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgZmlsbD0iI2YxZWNlYyIgdmlld0JveD0iMCAwIDI1NiAyNTYiPjxwYXRoIGQ9Ik0xMjgsMTI5LjA5VjIzMmE4LDgsMCwwLDEtMy44NC0xbC04OC00OC4xOGE4LDgsMCwwLDEtNC4xNi03VjgwLjE4YTgsOCwwLDAsMSwuNy0zLjI1WiIgb3BhY2l0eT0iMC4yIj48L3BhdGg%2BPHBhdGggZD0iTTIyMy42OCw2Ni4xNSwxMzUuNjgsMThhMTUuODgsMTUuODgsMCwwLDAtMTUuMzYsMGwtODgsNDguMTdhMTYsMTYsMCwwLDAtOC4zMiwxNHY5NS42NGExNiwxNiwwLDAsMCw4LjMyLDE0bDg4LDQ4LjE3YTE1Ljg4LDE1Ljg4LDAsMCwwLDE1LjM2LDBsODgtNDguMTdhMTYsMTYsMCwwLDAsOC4zMi0xNFY4MC4xOEExNiwxNiwwLDAsMCwyMjMuNjgsNjYuMTVaTTEyOCwzMmw4MC4zNCw0NC0yOS43NywxNi4zLTgwLjM1LTQ0Wk0xMjgsMTIwLDQ3LjY2LDc2bDMzLjktMTguNTYsODAuMzQsNDRaTTQwLDkwbDgwLDQzLjc4djg1Ljc5TDQwLDE3NS44MlptMTc2LDg1Ljc4aDBsLTgwLDQzLjc5VjEzMy44MmwzMi0xNy41MVYxNTJhOCw4LDAsMCwwLDE2LDBWMTA3LjU1TDIxNiw5MHY4NS43N1oiPjwvcGF0aD48L3N2Zz4%3D&logoColor=FFFCF0&labelColor=100F0F&color=205EA6)](https://github.com/jaygupta17/vinci/releases/latest)
+[![Discord](https://img.shields.io/badge/Discord-join.svg?style=flat&labelColor=100F0F&color=8B7EC8&logo=discord&logoColor=FFFCF0)](https://discord.gg/eSSmgeX8Q)
+
+Run [OpenCode](https://opencode.ai) in your browser. Install the CLI, open `localhost:3000`, done. Works on desktop browsers, tablets, and phones as a PWA.
+
+Full project overview, screenshots, and all features: [github.com/jaygupta17/vinci](https://github.com/jaygupta17/vinci)
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jaygupta17/vinci/main/scripts/install.sh | bash
+```
+
+Or install manually: `bun add -g @thevinci/web` (or npm, pnpm, yarn).
+
+> **Prerequisites:** [OpenCode CLI](https://opencode.ai) installed, Node.js 20+.
+
+## Usage
+
+```bash
+vinci                          # Start on port 3000
+vinci --port 8080              # Custom port
+vinci --ui-password secret     # Password-protect UI
+vinci tunnel help              # Tunnel lifecycle commands
+vinci tunnel providers         # Show provider capabilities
+vinci tunnel profile add --provider cloudflare --mode managed-remote --name prod-main --hostname app.example.com --token <token>
+vinci tunnel start --profile prod-main
+vinci tunnel start --provider cloudflare --mode quick --qr
+vinci tunnel start --provider cloudflare --mode managed-local --config ~/.cloudflared/config.yml
+vinci tunnel status --all      # Show tunnel state across instances
+vinci tunnel stop --port 3000  # Stop tunnel only (server stays running)
+vinci logs                     # Follow latest instance logs
+OPENCODE_PORT=4096 OPENCODE_SKIP_START=true vinci                    # Connect to external OpenCode server
+OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true vinci  # Connect via custom host/HTTPS
+vinci stop                     # Stop server
+vinci update                   # Update to latest version
+```
+
+### Tunnel behavior notes
+
+- One active tunnel per running Vinci instance (port).
+- Starting a different tunnel mode/provider on the same instance replaces the active tunnel.
+- Replacing or stopping a tunnel revokes existing connect links and invalidates remote tunnel sessions.
+- Connect links are one-time tokens; generating a new link revokes the previous unused link.
+
+<details>
+<summary>Connect to external OpenCode server</summary>
+
+```bash
+OPENCODE_PORT=4096 OPENCODE_SKIP_START=true vinci
+OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true vinci
+```
+
+| Variable | Description |
+|----------|-------------|
+| `OPENCODE_HOST` | Full base URL of external server (overrides `OPENCODE_PORT`) |
+| `OPENCODE_PORT` | Port of external server |
+| `OPENCODE_SKIP_START` | Skip starting embedded OpenCode server |
+| `VINCI_OPENCODE_HOSTNAME` | Bind hostname for managed OpenCode server (default: `127.0.0.1`, use `0.0.0.0` for LAN/remote access — trusted networks only) |
+| `VINCI_HOST` | Bind hostname for the Vinci web server (default: `127.0.0.1`; use `0.0.0.0` for LAN/remote access — trusted networks only) |
+| `VINCI_VERBOSE_REQUEST_LOGS` | Set to `true` to log every HTTP request; disabled by default to keep user logs small |
+| `VINCI_SKIP_API_COMPRESSION` | Set to `true` to disable gzip compression for `/api/*` responses |
+| `VINCI_COMPRESS_API` | Set to `true` to force `/api/*` compression, or `false` to disable it. Desktop runtime disables API compression by default to reduce local sidecar CPU use |
+
+</details>
+
+<details>
+<summary>Bind managed OpenCode to LAN / Tailscale</summary>
+
+```bash
+VINCI_OPENCODE_HOSTNAME=0.0.0.0 vinci --port 3000
+```
+
+**Security note:** binding to `0.0.0.0` exposes the server on all network interfaces — use only on trusted networks and protect with firewall rules or `--ui-password`.
+
+</details>
+
+**Optional env vars:**
+```yaml
+environment:
+  UI_PASSWORD: your_secure_password
+  VINCI_TUNNEL_MODE: quick # quick | managed-remote | managed-local
+  VINCI_TUNNEL_PROVIDER: cloudflare
+```
+
+For `managed-remote` mode, also set:
+
+```yaml
+environment:
+  VINCI_TUNNEL_MODE: managed-remote
+  VINCI_TUNNEL_HOSTNAME: app.example.com
+  VINCI_TUNNEL_TOKEN: <token>
+```
+
+For `managed-local` mode, you can set:
+
+```yaml
+environment:
+  VINCI_TUNNEL_MODE: managed-local
+  VINCI_TUNNEL_CONFIG: /home/vinci/.cloudflared/config.yml
+```
+
+Managed-local path note: `VINCI_TUNNEL_CONFIG` must use a container path under `/home/vinci/...`. If the config file references `credentials-file`, ensure that JSON path is also mounted and reachable inside the container.
+
+**Data directory:** mount `data/` for persistent storage. Ensure permissions:
+```bash
+mkdir -p data/vinci data/opencode/share data/opencode/config data/ssh
+chown -R 1000:1000 data/
+```
+
+</details>
+
+<details>
+<summary>Background & daemon mode</summary>
+
+```bash
+vinci             # Runs in background by default
+vinci stop        # Stop background server
+```
+
+</details>
+
+<details>
+<summary>systemd service (VPN / LAN access)</summary>
+
+Use `--foreground` to keep the CLI process alive so systemd (or any other process manager) can track and restart it. Combine with `OPENCODE_HOST` to connect to an OpenCode instance running as a separate service.
+
+**`~/.config/systemd/user/opencode.service`**
+```ini
+[Unit]
+Description=OpenCode Server
+
+[Service]
+Type=simple
+ExecStart=opencode serve --port 4095
+Environment="PATH=/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin:/home/YOU/.local/bin:/home/YOU/.npm-global/bin:/usr/local/bin:/usr/bin:/bin"
+Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+> **Why set `PATH` and `SSH_AUTH_SOCK`?**
+> systemd user services start with a minimal environment — no shell profile is sourced.
+> Without an explicit `PATH`, OpenCode won't find tools installed via Homebrew, npm, or `~/.local/bin`.
+> Without `SSH_AUTH_SOCK`, git operations over SSH (push, pull, clone) will fail.
+> `%t` expands to `$XDG_RUNTIME_DIR` (e.g. `/run/user/1000`), where most SSH agents write their socket.
+
+**`~/.config/systemd/user/vinci.service`**
+```ini
+[Unit]
+Description=Vinci Web Server
+After=opencode.service
+
+[Service]
+Type=simple
+ExecStart=vinci serve --port 3000 --host 0.0.0.0 --ui-password your-password --foreground
+Environment="OPENCODE_HOST=http://localhost:4095"
+Environment="OPENCODE_SKIP_START=true"
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now opencode vinci
+```
+
+`--host 0.0.0.0` is required to listen on all interfaces (the default is `127.0.0.1`). Use `--host <ip>` or `VINCI_HOST=<ip>` to bind to a specific interface instead.
+
+</details>
+
+## What makes the web version special
+
+- **Remote access** - Cloudflare tunnel with QR onboarding. Scan from your phone, start coding.
+- **Mobile-first PWA** - optimized chat controls, keyboard-safe layouts, drag-to-reorder projects
+- **Background notifications** - know when your agent finishes, even from another tab
+- **Self-update** - update and restart from the UI, server settings stay intact
+- **Cross-tab tracking** - session activity stays in sync across browser tabs
+
+- Cloudflare tunnel access with quick, managed-remote, and managed-local modes
+- One-scan onboarding with tunnel QR + password URL helpers
+- Mobile-first experience: optimized chat controls, keyboard-safe layouts, and attachment-friendly UI
+- Background notifications plus reliable cross-tab session activity tracking
+- Built-in self-update + restart flow that keeps your server settings intact
+
+## License
+
+MIT

package/bin/cli-entry.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+function normalizeCliEntryPath(filePath, realpath = fs.realpathSync) {
+  if (typeof filePath !== 'string' || filePath.trim().length === 0) {
+    return null;
+  }
+
+  const resolvedPath = path.resolve(filePath);
+  try {
+    return realpath(resolvedPath);
+  } catch {
+    return resolvedPath;
+  }
+}
+
+function isModuleCliExecution(
+  entryPath = process.argv[1],
+  moduleUrl,
+  realpath = fs.realpathSync,
+  expectedBinName,
+) {
+  if (typeof entryPath !== 'string' || entryPath.trim().length === 0) {
+    return false;
+  }
+  if (typeof moduleUrl !== 'string' || moduleUrl.trim().length === 0) {
+    return false;
+  }
+
+  try {
+    const normalizedEntryPath = normalizeCliEntryPath(entryPath, realpath);
+    const normalizedModulePath = normalizeCliEntryPath(fileURLToPath(moduleUrl), realpath);
+    if (!normalizedEntryPath || !normalizedModulePath) {
+      return false;
+    }
+    if (pathToFileURL(normalizedEntryPath).href === pathToFileURL(normalizedModulePath).href) {
+      return true;
+    }
+
+    if (typeof expectedBinName === 'string' && expectedBinName.trim().length > 0) {
+      const parsedEntryName = path.parse(normalizedEntryPath).name.toLowerCase();
+      return parsedEntryName === expectedBinName.trim().toLowerCase();
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export {
+  normalizeCliEntryPath,
+  isModuleCliExecution,
+};

package/bin/cli-output.js

@@ -0,0 +1,145 @@
+/**
+ * CLI output formatting adapter.
+ *
+ * Wraps @clack/prompts for structured, beautiful terminal output.
+ * Custom formatters (icons, redaction) live here to isolate the
+ * formatting dependency from the rest of the CLI.
+ */
+
+import {
+  intro,
+  outro,
+  log,
+  note,
+  box,
+  progress,
+  spinner,
+  confirm,
+  select,
+  text,
+  password,
+  cancel,
+  isCancel,
+} from '@clack/prompts';
+
+// ── Provider icons ──────────────────────────────────────────────
+
+const TUNNEL_PROVIDER_ICON = {
+  cloudflare: '☁',
+};
+
+function formatProviderWithIcon(provider) {
+  if (typeof provider !== 'string' || provider.trim().length === 0) {
+    return 'unknown';
+  }
+  const normalized = provider.trim().toLowerCase();
+  const icon = TUNNEL_PROVIDER_ICON[normalized];
+  return icon ? `${icon} ${normalized}` : normalized;
+}
+
+// ── Status-aware log dispatch ───────────────────────────────────
+
+/**
+ * Print a status-tagged message using clack log primitives.
+ *
+ * @param {'success'|'warning'|'error'|'info'|'neutral'} status
+ * @param {string} message  Primary line
+ * @param {string} [detail] Optional dim secondary line appended after newline
+ */
+function logStatus(status, message, detail) {
+  const full = detail ? `${message}\n${detail}` : message;
+  switch (status) {
+    case 'success':
+      log.success(full);
+      break;
+    case 'warning':
+      log.warn(full);
+      break;
+    case 'error':
+      log.error(full);
+      break;
+    case 'info':
+    case 'neutral':
+    default:
+      log.info(full);
+      break;
+  }
+}
+
+// ── TTY detection ───────────────────────────────────────────────
+
+/**
+ * Whether both stdout and stdin are interactive TTYs.
+ * Prompts must be disabled when stdin is piped (e.g. --token-stdin).
+ */
+const isTTY = Boolean(process.stdout?.isTTY) && Boolean(process.stdin?.isTTY);
+
+function isJsonMode(options) {
+  return Boolean(options?.json);
+}
+
+function isQuietMode(options) {
+  return Boolean(options?.quiet);
+}
+
+function shouldRenderHumanOutput(options) {
+  return !isJsonMode(options) && !isQuietMode(options);
+}
+
+function canPrompt(options) {
+  return shouldRenderHumanOutput(options) && isTTY;
+}
+
+function createSpinner(options) {
+  return canPrompt(options) ? spinner() : null;
+}
+
+async function createProgress(options, config) {
+  return canPrompt(options) ? progress(config) : null;
+}
+
+function printJson(payload) {
+  const base = payload && typeof payload === 'object' && !Array.isArray(payload)
+    ? { ...payload }
+    : { data: payload };
+
+  const messages = Array.isArray(base.messages) ? base.messages : undefined;
+  const hasWarning = Boolean(messages?.some((entry) => entry?.level === 'warning'));
+  const hasError = Boolean(messages?.some((entry) => entry?.level === 'error'));
+  const normalizedStatus = base.status === 'ok' || base.status === 'warning' || base.status === 'error'
+    ? base.status
+    : (hasError ? 'error' : (hasWarning ? 'warning' : 'ok'));
+
+  const output = {
+    status: normalizedStatus,
+    ...base,
+  };
+
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+}
+
+export {
+  intro,
+  outro,
+  log,
+  note,
+  box,
+  progress,
+  spinner,
+  confirm,
+  select,
+  text,
+  password,
+  cancel,
+  isCancel,
+  isTTY,
+  isJsonMode,
+  isQuietMode,
+  shouldRenderHumanOutput,
+  canPrompt,
+  createSpinner,
+  createProgress,
+  printJson,
+  formatProviderWithIcon,
+  logStatus,
+};