@ohmaseclaro/fleetwatch 0.1.0

package/.env.example

@@ -0,0 +1,25 @@
+# fleetwatch configuration
+# Copy to .env (project root) or ~/.config/fleetwatch/.env
+
+# ─── ngrok tunnel (on by default) ─────────────────────────────────────────
+# Get a free authtoken at https://dashboard.ngrok.com/get-started/your-authtoken
+NGROK_AUTHTOKEN=
+
+# Set to 1 to disable the tunnel entirely (LAN-only access).
+# NGROK_DISABLED=1
+
+# ─── Password protection (off by default) ─────────────────────────────────
+# When set, every device must enter this password before connecting.
+# Recommended if ngrok is enabled. Stored in memory as a bcrypt hash only.
+# PASSWORD=correct horse battery staple
+
+# ─── JWT signing secret (auto-generated if not set) ───────────────────────
+# Override only if you want JWTs to survive config wipes. 48+ random chars.
+# JWT_SECRET=
+
+# ─── npm publish (release script only — not used by the running daemon) ───
+# Get an Automation or "bypass 2FA" Granular token at
+#   https://www.npmjs.com/settings/~/tokens
+# `npm publish` (and `./scripts/release.sh`) read this via the project's
+# .npmrc to authenticate without an interactive 2FA prompt.
+# NPM_TOKEN=npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Augusto Claro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# fleetwatch
+
+> Watch every Claude Code, Cowork, and Cursor session from your phone — live.
+
+A single command starts a local daemon that tails your AI coding agent
+transcripts and serves a mobile-friendly web UI. Pair your phone via QR code
+or open it from anywhere via a free ngrok tunnel.
+
+```bash
+npx @ohmaseclaro/fleetwatch
+# or install globally:
+npm install -g @ohmaseclaro/fleetwatch && fleetwatch
+```
+
+## What it does
+
+- **Tracks Claude Code, Cowork, and Cursor** automatically — discovers data
+  in standard locations and falls back to a bounded filesystem search if
+  you've installed in a non-standard place.
+- **Mobile-first PWA** — open the URL on your phone, add to home screen,
+  watch sessions live as they run on your desktop.
+- **Source tabs with icons** — filter to Claude, Cowork, Cursor, or All.
+  Each row shows status (running / awaiting / errored / idle) with a
+  colored stripe on the left edge for in-flight sessions.
+- **Image attachments** — screenshots from the screenshot tool, user-pasted
+  images, render inline with a tap-to-zoom lightbox.
+- **Session info modal** — tap (i) on any session to see the full transcript
+  path, project, git branch, session ID, file size, with copy-to-clipboard.
+- **Auto-tunnel via ngrok** — works on any network when you have a free
+  authtoken; auto-picks it up from your existing `~/.../ngrok.yml` if you've
+  run `ngrok config add-authtoken …` before.
+- **Optional password** — set `PASSWORD=…` in `.env` to require a password
+  before any device can connect. Bcrypt-hashed in memory, never on disk.
+- **Read-only** — never writes to source data; opens DBs read-only; never
+  follows symlinks during discovery.
+
+## Quick start
+
+```bash
+# Install globally
+npm install -g @ohmaseclaro/fleetwatch
+
+# Run — auto-discovers Claude / Cursor data, prints QR code
+fleetwatch
+```
+
+Scan the QR with your phone. You're done.
+
+### First-time ngrok (optional but recommended)
+
+For access from anywhere (cellular, coffee shops, etc.) you'll need a free
+ngrok authtoken:
+
+1. Sign up: <https://dashboard.ngrok.com/signup>
+2. Copy your authtoken: <https://dashboard.ngrok.com/get-started/your-authtoken>
+3. `fleetwatch --ngrok-authtoken <your-token>` (persisted for future runs)
+
+Or set `NGROK_AUTHTOKEN=…` in `.env`. Or — if you've already run
+`ngrok config add-authtoken …` — fleetwatch picks it up automatically.
+
+## Configuration
+
+All optional. Defaults work out of the box.
+
+| Env var | Description |
+|---|---|
+| `NGROK_AUTHTOKEN` | ngrok free-tier authtoken. Required for the public tunnel. |
+| `NGROK_DISABLED=1` | Skip the ngrok tunnel even if a token is available. |
+| `CURSOR_DISABLED=1` | Skip the Cursor provider entirely. |
+| `PASSWORD` | Optional password — devices must enter it to connect. Bcrypt-hashed in memory only. |
+| `JWT_SECRET` | JWT signing secret (auto-generated + persisted otherwise). |
+| `CLAUDE_PROJECTS_DIR` | Override Claude Code projects dir. |
+| `COWORK_DIR` | Override Cowork sessions dir. |
+| `CLAUDE_HISTORY_FILE` | Override `history.jsonl` path. |
+| `CURSOR_DB_PATH` | Override Cursor `state.vscdb` path. |
+
+`.env` files are read from `./.env` and `~/.config/fleetwatch/.env`
+(in that order; shell env always wins).
+
+## CLI
+
+```
+fleetwatch [options]
+
+  --port, -p <port>       Port to listen on (default 7878)
+  --host <host>           Bind address (default 0.0.0.0)
+  --quiet, -q             Suppress QR / banner output
+  --ngrok-authtoken <t>   ngrok authtoken (persisted to config)
+  --no-ngrok              Disable ngrok for THIS run only (ephemeral)
+  --ngrok                 Force-enable ngrok, overriding stored config
+  --reset-ngrok           Clear the persisted "ngrok disabled" flag
+  --no-cursor             Skip the Cursor IDE provider
+  --help, -h              Show help
+```
+
+## Providers
+
+Out of the box:
+
+| Provider | Source data |
+|---|---|
+| **Claude Code** | `~/.claude/projects/*.jsonl` (the CLI agent) |
+| **Cowork** | `~/Library/Application Support/Claude/local-agent-mode-sessions/.../*.jsonl` |
+| **Cursor** | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` |
+
+Discovery is robust — each provider tries the default location, then an
+ordered list of OS-specific alternatives, then a bounded filesystem search
+under known app-data dirs (`~/.config/`, `~/Library/Application Support/`),
+with a mandatory `verify()` predicate that opens the candidate and
+confirms it's actually that provider's data (so VSCode's `state.vscdb`
+never gets mistaken for Cursor's).
+
+Adding a new provider (Aider, Continue, anything else) is small — extend
+`BaseProvider`, declare a `DiscoverySpec`, implement `onStart` /
+`backfillSession`. See [docs/ADD_A_PROVIDER.md](docs/ADD_A_PROVIDER.md).
+
+## Security
+
+- All connections require either the pairing token (in the QR URL) or a
+  successful login via password (if `PASSWORD` is set).
+- After login, the client gets a 30-day JWT; the pairing token is no
+  longer used.
+- WebSocket connections authenticate via JWT.
+- Image attachments served from an authed endpoint with content-addressed
+  hashes — no enumeration possible.
+- No telemetry. No external calls (except ngrok if enabled).
+
+## Development
+
+```bash
+git clone https://github.com/ohmaseclaro/fleetwatch
+cd fleetwatch
+npm install
+npm run dev:web      # Vite HMR on :5173
+npm run dev:server   # daemon with watch on :7878 (separate terminal)
+```
+
+Production build:
+
+```bash
+npm run build        # web → dist/web, server → dist/server
+npm start            # run the compiled daemon
+```
+
+## Releasing
+
+```bash
+npm run release        # bumps version, builds, publishes, tags
+```
+
+See [scripts/release.sh](scripts/release.sh) for details, or
+[docs/PUBLISHING.md](docs/PUBLISHING.md) for first-time setup.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/server/attachmentStore.js

@@ -0,0 +1,68 @@
+/**
+ * In-memory store for image attachments extracted from agent JSONL files.
+ *
+ * Why a store instead of just passing base64 over the WebSocket?
+ *  - Photos can be 3–5 MB; our WS payload cap is 1 MB
+ *  - We don't want to re-transmit the same image on every list refresh
+ *  - HTTP fetch gives us caching + range support for free
+ *
+ * Strategy: dedupe by sha256, LRU evict to keep memory bounded, serve via
+ * authed HTTP endpoint. Lives only in process memory — never persisted.
+ */
+import { createHash } from "node:crypto";
+/** Hard cap on total cached bytes; oldest entries get evicted first. */
+const MAX_TOTAL_BYTES = 200 * 1024 * 1024; // 200 MB
+/** Skip any single attachment larger than this — base64 round-trip protection. */
+const MAX_SINGLE_BYTES = 20 * 1024 * 1024; // 20 MB
+export class AttachmentStore {
+    entries = new Map();
+    totalBytes = 0;
+    /**
+     * Store an attachment and return its content-addressed hash. Returns null
+     * if the attachment is too large to keep.
+     */
+    put(buffer, mediaType) {
+        if (buffer.byteLength > MAX_SINGLE_BYTES)
+            return null;
+        const hash = createHash("sha256").update(buffer).digest("hex").slice(0, 32);
+        // Dedupe: if we already have this hash, just refresh the LRU timestamp.
+        const existing = this.entries.get(hash);
+        if (existing) {
+            existing.lastAccess = Date.now();
+            return hash;
+        }
+        this.entries.set(hash, {
+            buffer,
+            mediaType,
+            sizeBytes: buffer.byteLength,
+            lastAccess: Date.now(),
+        });
+        this.totalBytes += buffer.byteLength;
+        this.evictIfNeeded();
+        return hash;
+    }
+    get(hash) {
+        const entry = this.entries.get(hash);
+        if (!entry)
+            return null;
+        entry.lastAccess = Date.now();
+        return entry;
+    }
+    /** Drop oldest-accessed entries until under the byte cap. */
+    evictIfNeeded() {
+        if (this.totalBytes <= MAX_TOTAL_BYTES)
+            return;
+        const sorted = Array.from(this.entries.entries()).sort((a, b) => a[1].lastAccess - b[1].lastAccess);
+        while (this.totalBytes > MAX_TOTAL_BYTES && sorted.length > 0) {
+            const [hash, entry] = sorted.shift();
+            this.entries.delete(hash);
+            this.totalBytes -= entry.sizeBytes;
+        }
+    }
+    stats() {
+        return { count: this.entries.size, bytes: this.totalBytes };
+    }
+}
+/** Module-level singleton — one store per daemon process. */
+export const attachmentStore = new AttachmentStore();
+//# sourceMappingURL=attachmentStore.js.map

package/dist/server/auth.js

@@ -0,0 +1,88 @@
+/**
+ * Authentication: optional bcrypt-hashed password + JWT issuance for ongoing
+ * access. State is in-memory only — the password hash never touches disk.
+ *
+ * Two modes:
+ *   - No password (default): /api/login with a valid pairing token issues a JWT.
+ *   - Password set in env:   /api/login with a valid password issues a JWT.
+ *                            (Pairing token alone is not enough.)
+ *
+ * The JWT is the long-lived credential the client uses for all subsequent
+ * requests (WS + HTTP). 30-day expiry by default.
+ */
+import bcrypt from "bcryptjs";
+import jwt from "jsonwebtoken";
+let state = null;
+export function initAuth(opts) {
+    const passwordHash = opts.password
+        ? bcrypt.hashSync(opts.password, 10)
+        : null;
+    state = {
+        passwordHash,
+        jwtSecret: opts.jwtSecret,
+        jwtExpiresIn: opts.jwtExpiresIn ?? "30d",
+        pairingToken: opts.pairingToken,
+    };
+}
+/** Update the pairing token (e.g. after rotation) without re-initializing. */
+export function setPairingToken(token) {
+    if (state)
+        state.pairingToken = token;
+}
+/** Update the password (e.g. set/clear via Settings UI). */
+export function setPassword(plaintext) {
+    if (!state)
+        throw new Error("auth not initialized");
+    state.passwordHash = plaintext ? bcrypt.hashSync(plaintext, 10) : null;
+}
+export function isPasswordRequired() {
+    return !!state?.passwordHash;
+}
+export async function verifyPassword(plaintext) {
+    if (!state?.passwordHash)
+        return false;
+    return bcrypt.compare(plaintext, state.passwordHash);
+}
+export function verifyPairingToken(token) {
+    if (!state || !token)
+        return false;
+    return token === state.pairingToken;
+}
+export function issueJwt(subject = "user") {
+    if (!state)
+        throw new Error("auth not initialized");
+    const token = jwt.sign({ sub: subject }, state.jwtSecret, {
+        expiresIn: state.jwtExpiresIn,
+    });
+    const decoded = jwt.decode(token);
+    return {
+        token,
+        expiresAt: decoded ? decoded.exp * 1000 : Date.now() + 30 * 24 * 3600_000,
+    };
+}
+export function verifyJwt(token) {
+    if (!state || !token)
+        return null;
+    try {
+        return jwt.verify(token, state.jwtSecret);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Unified auth check used by HTTP + WS routes.
+ * Accepts a JWT (preferred) OR the pairing token (when password is not required).
+ * Returns true if authorized.
+ */
+export function isAuthorized(token) {
+    if (!token)
+        return false;
+    if (verifyJwt(token))
+        return true;
+    // Pairing token alone is only enough when no password is configured.
+    if (!isPasswordRequired() && verifyPairingToken(token))
+        return true;
+    return false;
+}
+//# sourceMappingURL=auth.js.map

package/dist/server/env.js

@@ -0,0 +1,43 @@
+/**
+ * Load .env files. Priority (first match per key wins — dotenv's
+ * "don't clobber existing" semantics):
+ *
+ *   1. process.env (already set in shell)
+ *   2. ./.env in current working directory
+ *   3. ~/.config/fleetwatch/.env
+ *   4. ~/.config/claude-watcher/.env (legacy from the rename — auto-picked up)
+ *
+ * Shell env > project .env > user-global .env. Ship defaults in your global
+ * file and override per-project.
+ */
+import path from "node:path";
+import os from "node:os";
+import { existsSync } from "node:fs";
+import dotenv from "dotenv";
+let loaded = false;
+export function loadEnv() {
+    if (loaded)
+        return;
+    loaded = true;
+    const cwdEnv = path.join(process.cwd(), ".env");
+    const globalEnv = path.join(os.homedir(), ".config", "fleetwatch", ".env");
+    const legacyGlobalEnv = path.join(os.homedir(), ".config", "claude-watcher", ".env");
+    // dotenv.config({ override: false }) → don't overwrite already-set vars
+    if (existsSync(cwdEnv))
+        dotenv.config({ path: cwdEnv, override: false });
+    if (existsSync(globalEnv))
+        dotenv.config({ path: globalEnv, override: false });
+    if (existsSync(legacyGlobalEnv))
+        dotenv.config({ path: legacyGlobalEnv, override: false });
+}
+export function envFlag(name) {
+    const v = process.env[name];
+    if (!v)
+        return false;
+    return v === "1" || v.toLowerCase() === "true" || v.toLowerCase() === "yes";
+}
+export function envString(name) {
+    const v = process.env[name];
+    return v && v.length > 0 ? v : undefined;
+}
+//# sourceMappingURL=env.js.map