getobsrv 0.3.0 → 0.4.0

package/out/shared/control.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTROL_COMMANDS = exports.CONTROL_TOKEN_BYTES = exports.CONTROL_FILE_NAME = void 0;
+exports.isControlCommand = isControlCommand;
+exports.parseControlFile = parseControlFile;
+exports.controlFileModeOk = controlFileModeOk;
+exports.tokenEqual = tokenEqual;
+exports.defaultControlFilePath = defaultControlFilePath;
+exports.presetApplyError = presetApplyError;
+exports.profileApplyError = profileApplyError;
+exports.viewModeApplyError = viewModeApplyError;
+exports.parseControlStatus = parseControlStatus;
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const presets_1 = require("./presets");
+/**
+ * The agent-control protocol shared by the main-process control server
+ * (`src/main/controlServer.ts`) and the MCP discovery client
+ * (`src/mcp/control.ts`): discovery-file shape, token comparison, command
+ * names and payload validation. Pure node — no Electron, no I/O — so
+ * everything here runs under plain node and is unit-tested in
+ * tests/unit/control.test.ts.
+ *
+ * Renderer code imports *types* from this module only; the `node:crypto`
+ * import never reaches a browser bundle.
+ *
+ * Security decisions (spec §14 "Live drive"):
+ * - The server binds 127.0.0.1 only, on an ephemeral port.
+ * - Every command — `status` included — carries the bearer token from the
+ *   discovery file. The file is mode 0600 in the app's own userData dir, so
+ *   possession already proves "same user"; a token-free status would only
+ *   leak app state to other local users for no benefit.
+ * - No command accepts file paths, JavaScript, or IPC channel names; every
+ *   payload is validated against the same tables the app itself uses.
+ */
+/** Discovery file the app writes to `app.getPath('userData')` while agent control is on. */
+exports.CONTROL_FILE_NAME = 'control.json';
+/** Bearer-token entropy; hex-encoded in the discovery file (64 chars). */
+exports.CONTROL_TOKEN_BYTES = 32;
+const TOKEN_RE = /^[0-9a-f]{64}$/;
+exports.CONTROL_COMMANDS = [
+    'status',
+    'navigate',
+    'setPreset',
+    'setProfile',
+    'setViewMode',
+    'captureVisible',
+];
+function isControlCommand(v) {
+    return typeof v === 'string' && exports.CONTROL_COMMANDS.includes(v);
+}
+const isRecord = (v) => typeof v === 'object' && v !== null;
+/**
+ * Parses a discovery file's contents. Strict: a malformed file (bad JSON,
+ * out-of-range port, a token that is not 64 hex chars) yields null — the
+ * client must treat the app as not reachable rather than send credentials
+ * derived from a file something else may have written.
+ */
+function parseControlFile(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    const { port, token } = parsed;
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    if (typeof token !== 'string' || !TOKEN_RE.test(token))
+        return null;
+    return { port, token };
+}
+/**
+ * Whether a discovery file's permission bits are acceptable: no group or
+ * other access on POSIX (the app writes it 0600). Windows has no POSIX mode
+ * bits worth reading, so everything passes there.
+ */
+function controlFileModeOk(mode, platform) {
+    if (platform === 'win32')
+        return true;
+    return (mode & 0o077) === 0;
+}
+/**
+ * Constant-time bearer-token comparison. Both sides are hashed first so
+ * `timingSafeEqual` always gets equal-length inputs — a length mismatch must
+ * not throw or short-circuit into a timing signal.
+ */
+function tokenEqual(expected, provided) {
+    if (typeof provided !== 'string')
+        return false;
+    const a = (0, node_crypto_1.createHash)('sha256').update(expected).digest();
+    const b = (0, node_crypto_1.createHash)('sha256').update(provided).digest();
+    return (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+/**
+ * Where the app's discovery file lives for a given platform, derived the way
+ * Electron derives `app.getPath('userData')` for productName "Obsrv" — the
+ * MCP server runs under plain node and cannot ask Electron.
+ */
+function defaultControlFilePath(platform, env, home) {
+    const appDir = platform === 'darwin'
+        ? (0, node_path_1.join)(home, 'Library', 'Application Support', 'Obsrv')
+        : platform === 'win32'
+            ? (0, node_path_1.join)(env['APPDATA'] ?? (0, node_path_1.join)(home, 'AppData', 'Roaming'), 'Obsrv')
+            : (0, node_path_1.join)(env['XDG_CONFIG_HOME'] ?? (0, node_path_1.join)(home, '.config'), 'Obsrv');
+    return (0, node_path_1.join)(appDir, exports.CONTROL_FILE_NAME);
+}
+const idList = (ids) => ids.join(', ');
+/**
+ * Validates a `setPreset` payload id. The custom preset is refused: it is
+ * defined by the renderer's own width/height/diagonal fields, so "apply
+ * custom" from outside would apply whatever happened to be typed there.
+ */
+function presetApplyError(id) {
+    if (typeof id !== 'string')
+        return 'setPreset payload must be { id: string }';
+    if (id === 'custom') {
+        return 'the custom preset cannot be applied remotely — it is defined by the fields in the app; pick a preset id';
+    }
+    if (!presets_1.SCREEN_PRESETS.some(p => p.id === id)) {
+        return `unknown preset "${id}" — valid ids: ${idList(presets_1.SCREEN_PRESETS.map(p => p.id))}`;
+    }
+    return null;
+}
+function profileApplyError(id) {
+    if (typeof id !== 'string')
+        return 'setProfile payload must be { id: string }';
+    if (!presets_1.PANEL_PROFILES.some(p => p.id === id)) {
+        return `unknown profile "${id}" — valid ids: ${idList(presets_1.PANEL_PROFILES.map(p => p.id))}`;
+    }
+    return null;
+}
+function viewModeApplyError(v) {
+    return v === '1:1' || v === 'fit' ? null : `setViewMode payload must be { mode: '1:1' | 'fit' }`;
+}
+/** Validates a control server `status` response on the client side. */
+function parseControlStatus(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { version, url, presetId, profileId, viewMode, mode } = raw;
+    if (typeof version !== 'string' || typeof url !== 'string')
+        return null;
+    if (typeof presetId !== 'string' || typeof profileId !== 'string')
+        return null;
+    if (viewMode !== '1:1' && viewMode !== 'fit')
+        return null;
+    if (mode !== 'url' && mode !== 'image')
+        return null;
+    return { version, url, presetId, profileId, viewMode, mode };
+}

package/out/shared/presets.js

@@ -4,7 +4,7 @@ exports.PANEL_PROFILES = exports.SCREEN_PRESETS = exports.DEFAULT_SETTINGS = exp
 exports.findPreset = findPreset;
 exports.findProfile = findProfile;
 exports.MAX_VIEWPORT = 4096;
-exports.DEFAULT_SETTINGS = { hostDiagonalInches: 27, hostNits: 500 };
+exports.DEFAULT_SETTINGS = { hostDiagonalInches: 27, hostNits: 500, agentControl: false };
 exports.SCREEN_PRESETS = [
     // Laptops — ordered largest to smallest panel, then the denser 1080p outlier.
     { id: 'laptop-768', label: '1366×768 15.6"', width: 1366, height: 768, diagonalInches: 15.6, deviceScaleFactor: 1, group: 'laptop' },

package/out/shared/url.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_URL_SCHEMES = void 0;
+exports.normalizeUrl = normalizeUrl;
+exports.urlSchemeError = urlSchemeError;
+/** `scheme:` prefix, e.g. `https:`, `about:`, `file:`. */
+const SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/** Loopback host with optional port, e.g. `localhost:5173`, `127.0.0.1/a`. */
+const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i;
+/**
+ * Turn URL-bar input into an absolute, loadable URL.
+ * Loopback is checked before the scheme test because `localhost:5173`
+ * parses as scheme `localhost` otherwise.
+ */
+function normalizeUrl(input) {
+    const s = input.trim();
+    if (s === '')
+        throw new Error('empty url');
+    if (/\s/.test(s))
+        throw new Error('invalid URL');
+    if (s.startsWith('/'))
+        return `file://${s}`;
+    if (LOOPBACK.test(s))
+        return `http://${s}`;
+    if (SCHEME.test(s))
+        return s;
+    return `https://${s}`;
+}
+/** Schemes an agent-facing entry point (MCP tool, control server) may load. */
+exports.ALLOWED_URL_SCHEMES = ['http:', 'https:', 'file:'];
+/**
+ * Rejects URLs whose explicit scheme is outside the allowlist (javascript:,
+ * data:, chrome:, …) with an actionable message, or returns null when the URL
+ * may proceed. Scheme-relative (`//host`), bare-host (`example.com/page`) and
+ * host:port (`localhost:5173`) forms pass — they normalise to http(s)
+ * downstream. Shared by the MCP tools and the agent-control server, so the
+ * app's URL bar stays the only surface that can reach another scheme.
+ */
+function urlSchemeError(url) {
+    const trimmed = url.trim();
+    const match = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+    if (!match)
+        return null; // bare host or scheme-relative
+    const scheme = `${match[1].toLowerCase()}:`;
+    if (exports.ALLOWED_URL_SCHEMES.includes(scheme))
+        return null;
+    // `localhost:5173`-style host:port, not a scheme: the "scheme" is followed
+    // by a bare port number.
+    if (/^[a-z0-9.-]+:\d+(\/|$)/i.test(trimmed))
+        return null;
+    return (`unsupported URL scheme "${scheme}" — obsrv renders ` +
+        `${exports.ALLOWED_URL_SCHEMES.map(s => `${s}//`).join(', ')} URLs only ` +
+        `(bare hosts like example.com also work; they normalise to http(s)).`);
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "getobsrv",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "See your site the way 1x screens see it",
   "main": "./out/main/index.js",
   "bin": {
-    "obsrv": "./bin/obsrv.js",
-    "obsrv-mcp": "./bin/obsrv-mcp.js"
+    "obsrv": "bin/obsrv.js",
+    "getobsrv": "bin/obsrv.js",
+    "obsrv-mcp": "bin/obsrv-mcp.js"
   },
   "author": "Opeyemi Ajagbe <auto-report@hydrogenpay.com>",
   "homepage": "https://github.com/vibesyemmy/obsrv",
@@ -16,9 +17,11 @@
     "test": "vitest run --project unit",
     "test:browser": "vitest run --project browser",
     "test:e2e": "npm run build && playwright test",
-    "dist": "npm run build && electron-builder --mac",
+    "dist": "npm run build && electron-builder --mac --publish never",
     "build:mcp": "tsc -p tsconfig.mcp.json",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "prepack": "node scripts/electron-dep.js to-prod",
+    "postpack": "node scripts/electron-dep.js to-dev"
   },
   "dependencies": {
     "@fontsource/ibm-plex-mono": "^5.3.0",

package/skills/obsrv-screens/SKILL.md

@@ -15,37 +15,43 @@ where thin fonts, 0.5px hairlines, and low-contrast grey text actually break.
 
 ## Commands
 
-Prerequisite: `npm run build` must have been run in the Obsrv repo (the CLI
-runs the built `out/`). If a snap fails with "out/main/cli.js is missing", run
-`npm run build` in `/Users/opeyemiajagbe/Documents/Projects/Obsrv` first.
+Prerequisite: none when using `npx -y getobsrv` (npm downloads everything,
+including Electron, on first run). In a local Obsrv checkout, run
+`npm install && npm run build` there first.
 
 ```bash
-OBSRV=/Users/opeyemiajagbe/Documents/Projects/Obsrv/bin/obsrv.js
+# Installed anywhere via npm (first run downloads Electron):
+OBSRV="npx -y getobsrv"
+# Or, in a local Obsrv checkout (faster, no download):
+# OBSRV="node /path/to/Obsrv/bin/obsrv.js"
 
 # One screen, one PNG (+ JSON metadata on stdout, humans on stderr):
-node $OBSRV snap http://localhost:5173 --preset laptop-768 --out shots/laptop.png
+$OBSRV snap http://localhost:5173 --preset laptop-768 --out shots/laptop.png
 
 # The recommended matrix — small laptop, budget phone, 1080p desktop:
-node $OBSRV snap http://localhost:5173 --matrix laptop-768,android-65,1080p-24 --out shots/
+$OBSRV snap http://localhost:5173 --matrix laptop-768,android-65,1080p-24 --out shots/
 
 # Worst realistic panel (cheap TN) on the small laptop:
-node $OBSRV snap http://localhost:5173 --preset laptop-768 --profile budget-tn --out shots/laptop-tn.png
+$OBSRV snap http://localhost:5173 --preset laptop-768 --profile budget-tn --out shots/laptop-tn.png
 
 # Whole page, not just the first viewport (device px cap 4096, warns if clamped):
-node $OBSRV snap http://localhost:5173 --preset laptop-768 --full-page --out shots/full.png
+$OBSRV snap http://localhost:5173 --preset laptop-768 --full-page --out shots/full.png
 
 # Numbers instead of eyeballs: 1x target vs a 2x-reference downsample, JSON to stdout:
-node $OBSRV diff http://localhost:5173 --preset laptop-768 --out-dir shots/diff
+$OBSRV diff http://localhost:5173 --preset laptop-768 --out-dir shots/diff
 ```
 
-`node $OBSRV --help` lists every preset (`1080p-24`, `laptop-768`,
+`$OBSRV --help` lists every preset (`1080p-24`, `laptop-768`,
 `android-65`, `iphone-61`, …), profile (`reference`, `office-ips`,
 `budget-tn`, `old-laptop`), and flag (`--width/--height/--dsf`, `--wait`,
 `--timeout`).
 
 If the obsrv MCP tools are connected (`obsrv_snap` / `obsrv_diff` /
 `obsrv_presets`), prefer them over shelling out — same pipeline, and the PNG
-comes back inline.
+comes back inline. If the Obsrv desktop app is open with "Agent control" on
+(toolbar toggle), snaps drive the visible window — the user watches — and
+`obsrv_drive` flips its URL/preset/profile directly; no app means the usual
+headless render.
 
 ## The loop that catches real regressions