viveworker 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# viveworker
+
+`viveworker` brings Codex Desktop to your iPhone.
+
+When Codex needs an approval, asks whether to implement a plan, wants you to choose from options, or finishes a task while you are away from your desk, `viveworker` keeps all of that within reach on your phone. Instead of breaking your rhythm, it helps you keep vivecoding going from anywhere in your home or office.
+
+Think of it as a local companion for Codex on your Mac:
+your Mac keeps building, and your iPhone keeps you in the loop.
+
+## Why It Feels Good
+
+With `viveworker`, you can:
+
+- approve or reject actions the moment Codex asks
+- respond to `Implement this plan?` without walking back to your desk
+- answer multiple-choice questions quickly from your phone
+- review completions and jump back into the latest thread
+- get a Home Screen notification when Codex needs you
+
+The point is simple:
+keep Codex moving, keep context close, and keep your momentum.
+
+## Best Fit
+
+`viveworker` works best with:
+
+- Mac + iPhone
+- the same Wi-Fi or LAN
+- a trusted local network
+- the Home Screen web app with Web Push enabled
+
+It gets even more fun with a Mac mini.
+Leave Codex running on a small always-on machine, and `viveworker` starts to feel like a local coding appliance: your Mac mini keeps building in the background while your iPhone handles approvals, plan checks, questions, and follow-up replies from anywhere in your home or office.
+
+`viveworker` is designed for local use only.
+It is not intended for Internet exposure.
+
+## Mac mini Ideas
+
+`viveworker` pairs especially well with a Mac mini.
+
+You can use it as:
+
+- an always-on Codex station that stays running in the background
+- a way to keep approvals and plan checks moving even when you are away from your desk
+- a lightweight monitor for long-running coding or research tasks, where your iPhone only surfaces what needs your attention
+- a small local AI appliance for your home or office
+- a quick way to review a completion and send “do this next” back into the latest thread from your phone
+
+## Quick Start
+
+For the full experience, start here:
+
+```bash
+npx viveworker setup --install-mkcert
+```
+
+If `mkcert` is already installed and trusted on your Mac, plain setup is enough:
+
+```bash
+npx viveworker setup
+```
+
+By default, `viveworker` uses port `8810`.
+If that port is already in use, choose another one:
+
+```bash
+npx viveworker setup --port 8820
+```
+
+## Recommended Setup Path
+
+`viveworker` enables Web Push by default. The recommended first-time flow is:
+
+1. Run `npx viveworker setup --install-mkcert` on your Mac
+2. If macOS asks, allow the local CA install
+3. On your iPhone, open the printed `rootCA.pem` URL
+4. Install the certificate profile and trust it in iPhone certificate trust settings
+5. Open the printed pairing URL in Safari
+6. Pair your iPhone with the code if needed
+7. Add `viveworker` to your Home Screen
+8. Open the Home Screen app
+9. In `Settings`, tap `Enable Notifications`
+10. Tap `Send Test Notification` to verify delivery
+
+During setup, `viveworker` prints:
+
+- a `.local` URL
+- a fallback IP-based URL
+- a `rootCA.pem` download URL
+- a short-lived pairing code
+- a pairing URL
+- a pairing QR code
+
+After setup:
+
+- use the Home Screen app for daily use
+- use the pairing URL only for first-time setup or when you intentionally add another device
+- keep using the Home Screen app if you want notifications to work reliably
+
+## Common Commands
+
+Use these commands most often:
+
+- `npx viveworker setup`
+  create or refresh the local setup, generate pairing info, and start the app
+- `npx viveworker start`
+  start `viveworker` again using the saved config
+- `npx viveworker stop`
+  stop the local background service
+- `npx viveworker status`
+  show the current app URL, launchd/background status, and health
+- `npx viveworker doctor`
+  diagnose local setup problems when something is not working
+- `npx viveworker setup --pair`
+  generate a fresh one-time pairing code and pairing URL for adding another device
+
+Useful options:
+
+- `--port <n>` if `8810` is already in use
+- `--install-mkcert` to automate the local certificate setup
+- `--disable-web-push` only if you intentionally do not want notifications
+
+`--pair` reissues only the short-lived pairing code and pairing URL.
+It does not change the main app URL, port, session secret, TLS, or Web Push settings.
+Use it only when you want to add another trusted iPhone or browser.
+
+## Questions and Limits
+
+- Multiple-choice questions are handled as a single item
+- Up to 5 questions are shown per page
+- 6 or more questions are split across multiple pages
+- Answers are submitted together on the final page
+- Questions that include `Other` or free text must be answered on your Mac
+
+## Security Model
+
+- use `viveworker` only on a trusted LAN
+- do not expose it directly to the Internet
+- if you lose a paired device, revoke it from `Settings > Devices`
+- use `setup --pair` only when you want to add another trusted device
+
+## Optional `ntfy`
+
+`ntfy` is optional.
+
+Start with `viveworker` and Web Push first.
+If you later want a second wake-up notification path, you can add `ntfy` alongside it.
+
+## Troubleshooting
+
+- If the `.local` URL does not open, use the printed IP-based URL
+- If pairing has expired, run `npx viveworker setup --pair`
+- If notifications do not appear, make sure you opened the Home Screen app, not just a Safari tab
+- If Web Push is enabled, make sure you are opening the HTTPS URL
+- If you are stuck, run:
+
+```bash
+npx viveworker status
+npx viveworker doctor
+```
+
+## Notes
+
+- `viveworker` stays local and runs on your Mac on the same LAN
+- Web Push still depends on the browser/platform push service
+- `--install-mkcert` can automate the Mac-side `mkcert` install and `mkcert -install`
+- macOS may still show an administrator prompt while installing the local CA
+- iPhone trust is still manual: you need to trust the local CA profile on the device
+- Web Push supports approvals, plans, multiple-choice questions, and completions
+
+## Roadmap
+
+Planned next steps include:
+
+- Android support
+- Windows support
+- image attachment support from mobile

package/launchd/io.viveworker.app.plist.example

@@ -0,0 +1,39 @@
+<?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">
+<plist version="1.0">
+  <dict>
+    <!--
+      This file is only for manual launchd setups.
+      Most users should run `npx viveworker setup`, which generates the real LaunchAgent automatically.
+    -->
+    <key>Label</key>
+    <string>io.viveworker.app</string>
+
+    <key>ProgramArguments</key>
+    <array>
+      <string>/ABSOLUTE/PATH/TO/node</string>
+      <string>/ABSOLUTE/PATH/TO/viveworker/scripts/viveworker-bridge.mjs</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>/ABSOLUTE/PATH/TO/viveworker</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+      <key>VIVEWORKER_ENV_FILE</key>
+      <string>/ABSOLUTE/PATH/TO/.viveworker/config.env</string>
+    </dict>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/ABSOLUTE/PATH/TO/.viveworker/logs/viveworker.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/ABSOLUTE/PATH/TO/.viveworker/logs/viveworker.log</string>
+  </dict>
+</plist>

package/ntfy/docker-compose.yml.example

@@ -0,0 +1,10 @@
+services:
+  ntfy:
+    image: binwiederhier/ntfy:latest
+    restart: unless-stopped
+    command: serve
+    ports:
+      - "8080:80"
+    volumes:
+      - ./server.yml:/etc/ntfy/server.yml:ro
+      - ../.ntfy-data:/var/lib/ntfy

package/ntfy/server.yml.example

@@ -0,0 +1,28 @@
+# Trusted-LAN ntfy setup for viveworker notifications.
+# Use HTTP like this only on a Wi-Fi/LAN you trust.
+# If you want remote access or stronger transport security, put ntfy behind HTTPS.
+
+# This URL must exactly match the Default Server you configure in the mobile app.
+base-url: "http://YOUR-MAC-IP-OR-HOSTNAME:8080"
+
+# The container listens on port 80 internally; Docker maps 8080 -> 80.
+listen-http: ":80"
+
+# Persistent cache is required so iPhone can fetch message contents after a poll request.
+cache-file: "/var/lib/ntfy/cache.db"
+
+# User, ACL, and token database. Created automatically if it does not exist.
+auth-file: "/var/lib/ntfy/auth.db"
+auth-default-access: "deny-all"
+
+# Login is handy for debugging, but self-signup should stay off on a private instance.
+enable-login: true
+enable-signup: false
+
+# Needed for near-instant iPhone delivery on a self-hosted server.
+# Only a poll request is forwarded upstream, not your real message body.
+upstream-base-url: "https://ntfy.sh"
+
+# Production-safe defaults: do not log message bodies.
+log-level: "info"
+log-format: "json"

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "viveworker",
+  "version": "0.1.0",
+  "description": "A local iPhone companion for Codex Desktop approvals, plans, questions, and completions.",
+  "type": "module",
+  "bin": {
+    "viveworker": "./scripts/viveworker.mjs"
+  },
+  "files": [
+    "scripts/viveworker.mjs",
+    "scripts/viveworker-bridge.mjs",
+    "scripts/lib",
+    "web",
+    "README.md",
+    "viveworker.env.example",
+    "launchd/io.viveworker.app.plist.example",
+    "ntfy/server.yml.example",
+    "ntfy/docker-compose.yml.example"
+  ],
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "web-push": "^3.6.7"
+  }
+}

package/scripts/lib/markdown-render.mjs

@@ -0,0 +1,274 @@
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replace(/&/gu, "&")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;")
+    .replace(/"/gu, "&quot;")
+    .replace(/'/gu, "&#39;");
+}
+
+function stripPresentationEnvelopeTags(markdown) {
+  return String(markdown ?? "")
+    .replace(/^\s*<\/?proposed_plan>\s*$/gimu, "")
+    .replace(/<\/?proposed_plan>/giu, "")
+    .trim();
+}
+
+function sanitizeHref(value) {
+  const text = String(value ?? "").trim();
+  if (!text) {
+    return "";
+  }
+  if (/^https?:\/\//iu.test(text) || /^mailto:/iu.test(text) || /^codex:/iu.test(text)) {
+    return text;
+  }
+  if (/^\/(?:approvals|native-approvals|completion-details)\b/u.test(text)) {
+    return text;
+  }
+  return "";
+}
+
+function parseAutoLink(text, start) {
+  const segment = text.slice(start);
+  const match = segment.match(/^(https?:\/\/[^\s<>"']+|mailto:[^\s<>"']+|codex:[^\s<>"']+)/iu);
+  if (!match) {
+    return null;
+  }
+
+  let href = match[0];
+  while (/[),.;!?]$/u.test(href)) {
+    href = href.slice(0, -1);
+  }
+
+  const sanitized = sanitizeHref(href);
+  if (!sanitized) {
+    return null;
+  }
+
+  return {
+    href: sanitized,
+    end: start + href.length,
+  };
+}
+
+function renderInline(text) {
+  let html = "";
+  let index = 0;
+
+  while (index < text.length) {
+    if (text.startsWith("**", index)) {
+      const end = text.indexOf("**", index + 2);
+      if (end > index + 2) {
+        html += `<strong>${renderInline(text.slice(index + 2, end))}</strong>`;
+        index = end + 2;
+        continue;
+      }
+    }
+
+    if (text[index] === "`") {
+      const end = text.indexOf("`", index + 1);
+      if (end > index + 1) {
+        html += `<code>${escapeHtml(text.slice(index + 1, end))}</code>`;
+        index = end + 1;
+        continue;
+      }
+    }
+
+    if (text[index] === "[") {
+      const link = parseMarkdownLink(text, index);
+      if (link) {
+        const labelHtml = renderInline(link.label);
+        const href = sanitizeHref(link.href);
+        html += href
+          ? `<a href="${escapeHtml(href)}" target="_blank" rel="noreferrer">${labelHtml}</a>`
+          : `${labelHtml} <code>${escapeHtml(link.href)}</code>`;
+        index = link.end;
+        continue;
+      }
+    }
+
+    const autoLink = parseAutoLink(text, index);
+    if (autoLink) {
+      html += `<a href="${escapeHtml(autoLink.href)}" target="_blank" rel="noreferrer">${escapeHtml(autoLink.href)}</a>`;
+      index = autoLink.end;
+      continue;
+    }
+
+    if (text[index] === "*") {
+      const end = text.indexOf("*", index + 1);
+      if (end > index + 1) {
+        const content = text.slice(index + 1, end).trim();
+        if (content) {
+          html += `<em>${renderInline(content)}</em>`;
+          index = end + 1;
+          continue;
+        }
+      }
+    }
+
+    html += escapeHtml(text[index]);
+    index += 1;
+  }
+
+  return html;
+}
+
+function parseMarkdownLink(text, start) {
+  const closeLabel = text.indexOf("]", start + 1);
+  if (closeLabel === -1 || text[closeLabel + 1] !== "(") {
+    return null;
+  }
+
+  let depth = 1;
+  let index = closeLabel + 2;
+  while (index < text.length) {
+    if (text[index] === "(") {
+      depth += 1;
+    } else if (text[index] === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return {
+          label: text.slice(start + 1, closeLabel),
+          href: text.slice(closeLabel + 2, index),
+          end: index + 1,
+        };
+      }
+    }
+    index += 1;
+  }
+
+  return null;
+}
+
+function isUnorderedList(line) {
+  return /^[-*+]\s+/u.test(line);
+}
+
+function isOrderedList(line) {
+  return /^\d+\.\s+/u.test(line);
+}
+
+function isFence(line) {
+  return /^```/u.test(line);
+}
+
+function renderList(lines, ordered) {
+  const tag = ordered ? "ol" : "ul";
+  const items = lines
+    .map((line) => line.replace(ordered ? /^\d+\.\s+/u : /^[-*+]\s+/u, ""))
+    .map((line) => `<li>${renderInline(line.trim())}</li>`)
+    .join("");
+  return `<${tag}>${items}</${tag}>`;
+}
+
+function renderBlockquote(lines) {
+  const inner = renderMarkdownHtml(lines.map((line) => line.replace(/^>\s?/u, "")).join("\n"), {
+    fallbackHtml: "<p></p>",
+  });
+  return `<blockquote>${inner}</blockquote>`;
+}
+
+function renderCodeBlock(lines) {
+  const [fence, ...rest] = lines;
+  const language = fence.replace(/^```/u, "").trim();
+  const className = language ? ` class="language-${escapeHtml(language)}"` : "";
+  return `<pre><code${className}>${escapeHtml(rest.join("\n"))}</code></pre>`;
+}
+
+function renderParagraph(lines) {
+  return `<p>${lines.map((line) => renderInline(line.trim())).join("<br>")}</p>`;
+}
+
+function parseBlocks(markdown) {
+  const lines = markdown.replace(/\r\n/gu, "\n").trim().split("\n");
+  const blocks = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const line = lines[index];
+    if (!line.trim()) {
+      index += 1;
+      continue;
+    }
+
+    if (isFence(line)) {
+      const block = [line];
+      index += 1;
+      while (index < lines.length) {
+        block.push(lines[index]);
+        if (isFence(lines[index])) {
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      blocks.push(renderCodeBlock(block));
+      continue;
+    }
+
+    const heading = line.match(/^(#{1,6})\s+(.*)$/u);
+    if (heading) {
+      const level = heading[1].length;
+      blocks.push(`<h${level}>${renderInline(heading[2].trim())}</h${level}>`);
+      index += 1;
+      continue;
+    }
+
+    if (/^(?:---|\*\*\*|___)\s*$/u.test(line)) {
+      blocks.push("<hr>");
+      index += 1;
+      continue;
+    }
+
+    if (/^>\s?/u.test(line)) {
+      const block = [];
+      while (index < lines.length && /^>\s?/u.test(lines[index])) {
+        block.push(lines[index]);
+        index += 1;
+      }
+      blocks.push(renderBlockquote(block));
+      continue;
+    }
+
+    if (isUnorderedList(line) || isOrderedList(line)) {
+      const ordered = isOrderedList(line);
+      const block = [];
+      while (index < lines.length && (ordered ? isOrderedList(lines[index]) : isUnorderedList(lines[index]))) {
+        block.push(lines[index]);
+        index += 1;
+      }
+      blocks.push(renderList(block, ordered));
+      continue;
+    }
+
+    const block = [];
+    while (index < lines.length) {
+      const current = lines[index];
+      if (!current.trim() || isFence(current) || /^(#{1,6})\s+/u.test(current) || /^>\s?/u.test(current)) {
+        break;
+      }
+      if (isUnorderedList(current) || isOrderedList(current) || /^(?:---|\*\*\*|___)\s*$/u.test(current)) {
+        break;
+      }
+      block.push(current);
+      index += 1;
+    }
+    blocks.push(renderParagraph(block));
+  }
+
+  return blocks;
+}
+
+export function renderMarkdownHtml(markdown, { fallbackHtml = "<p></p>" } = {}) {
+  const normalized = stripPresentationEnvelopeTags(markdown);
+  if (!normalized) {
+    return fallbackHtml;
+  }
+
+  const blocks = parseBlocks(normalized);
+  if (blocks.length === 0) {
+    return fallbackHtml;
+  }
+
+  return blocks.join("\n");
+}

package/scripts/lib/pairing.mjs

@@ -0,0 +1,83 @@
+import crypto from "node:crypto";
+
+export const PAIRING_TTL_MS = 15 * 60 * 1000;
+
+const PAIRING_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+
+export function isPairingExpired(expiresAtMs, now = Date.now()) {
+  const normalized = Number(expiresAtMs) || 0;
+  return normalized > 0 && now >= normalized;
+}
+
+export function shouldRotatePairing({ force = false, pairingCode = "", pairingToken = "", pairingExpiresAtMs = 0 } = {}, now = Date.now()) {
+  return Boolean(force || !pairingCode || !pairingToken || isPairingExpired(pairingExpiresAtMs, now));
+}
+
+export function generatePairingCode(length = 8) {
+  const bytes = crypto.randomBytes(length);
+  let output = "";
+  for (let index = 0; index < length; index += 1) {
+    output += PAIRING_ALPHABET[bytes[index] % PAIRING_ALPHABET.length];
+  }
+  return output;
+}
+
+export function generatePairingCredentials(now = Date.now()) {
+  return {
+    pairingCode: generatePairingCode(8),
+    pairingToken: crypto.randomBytes(18).toString("hex"),
+    pairingExpiresAtMs: now + PAIRING_TTL_MS,
+  };
+}
+
+export function upsertEnvText(rawText, updates) {
+  const text = String(rawText || "");
+  const entries = Object.entries(updates || {}).filter(([key]) => key);
+  if (entries.length === 0) {
+    return text;
+  }
+
+  const updateMap = new Map(entries.map(([key, value]) => [String(key), String(value ?? "")]));
+  const seen = new Set();
+  const output = [];
+
+  for (const rawLine of text.split(/\r?\n/u)) {
+    const line = String(rawLine);
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      output.push(line);
+      continue;
+    }
+
+    const separator = line.indexOf("=");
+    if (separator === -1) {
+      output.push(line);
+      continue;
+    }
+
+    const key = line.slice(0, separator).trim();
+    if (!updateMap.has(key)) {
+      output.push(line);
+      continue;
+    }
+
+    if (seen.has(key)) {
+      continue;
+    }
+
+    output.push(`${key}=${updateMap.get(key)}`);
+    seen.add(key);
+  }
+
+  for (const [key, value] of updateMap.entries()) {
+    if (!seen.has(key)) {
+      output.push(`${key}=${value}`);
+    }
+  }
+
+  while (output.length > 0 && output[output.length - 1] === "") {
+    output.pop();
+  }
+
+  return `${output.join("\n")}\n`;
+}