vibeshare-live 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pooria Arab
+
+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,104 @@
+# vibeshare
+
+Share your live agent coding session by URL — traces.com-style, open source, CLI-first. Spectate read-only or invite into the vibelive multiplayer engine.
+
+Part of the **Vibe Suite** — companion tools for agentic coding CLIs (Claude Code, Codex, Gemini, Grok/pi, Kimi). Ships as **CLI + npm package + MCP server**.
+
+**Local-first: runs on your own machine, no data out** (consent model in `@pooriaarab/vibe-core`).
+
+> Status: **v0** — the share/access layer over [`@pooriaarab/vibelive`](https://www.npmjs.com/package/@pooriaarab/vibelive) is implemented (CLI, library, MCP). Local/LAN, host-authoritative. E2e relay fan-out to ~1000 spectators is on the vibelive roadmap.
+
+## Install
+
+```bash
+npm install -g vibeshare-live
+# or use it inline:
+npx vibeshare-live -- claude
+```
+
+It pulls in `@pooriaarab/vibelive` (the multiplayer engine) and `@pooriaarab/vibe-core` (the consent ledger).
+
+## Quick start
+
+Host your agent and hand someone a link:
+
+```bash
+vibeshare --invite -- claude
+```
+
+You'll get back something like:
+
+```
+vibeshare — sharing claude
+  share:  https://vibeshare.stream/s/a5e3a635-0bb7-4689-973c-5fe2d7de6207
+  access: invite · no expiry
+  relay:  ws://localhost:55410
+  ● p2p · e2e · nothing stored on a server
+```
+
+Send them the `share` URL. They spectate read-only; with `--invite` they can request to join and you `/approve <id>` to let them drive. Slash commands inside the host session: `/drive` `/release` `/viewers` `/approve <id>` `/stop`.
+
+| Flag | Meaning |
+| --- | --- |
+| `--spectate` | link holders get read-only access (default) |
+| `--invite` | link holders may request to join; you approve to let them drive |
+| `--expire 1h\|24h` | auto-revoke the share after this duration |
+| `--pass <p>` | require a passphrase on top of the share URL |
+
+`vibeshare --version` · `vibeshare --help` · `vibeshare mcp`
+
+## Your own domain, not vibe.live
+
+The share URL reads `vibeshare.stream/s/<id>` — **vibeshare's own domain** (available $4/yr), not `vibe.live`. The link is a capability URL: the id is the only thing that grants access (122 bits of entropy), so it's unguessable. Optional `--pass` adds a second factor.
+
+The actual live stream runs over the local/LAN WebSocket relay that vibelive starts on your machine. The `vibeshare.stream` URL is the identity layer; the bytes flow over a self-hostable relay.
+
+## Peer-to-peer, end-to-end encrypted, nothing stored on a server
+
+The session stream runs **peer-to-peer / via a dumb e2e-encrypted relay** that forwards opaque blobs. The relay cannot decrypt anything — nothing readable is ever stored on a server, and the relay is self-hostable. This is vibelive's transport (§1–2 of its tech spec); vibeshare is the URL/access layer on top. Fanning session output off your machine is gated behind the `share:session` consent scope.
+
+## As a library
+
+```ts
+import { createHost, createRelay } from '@pooriaarab/vibelive';
+import { createShare } from 'vibeshare-live';
+
+const host = createHost({ command: ['claude'] });
+const relay = await createRelay({ port: 0, hostHandle: host, initialDriver: 'host' });
+
+const share = createShare({
+  session: relay,
+  access: 'spectate',      // 'spectate' (read-only) | 'invite' (can join to drive)
+  expiry: '1h',            // optional: '1h' | '24h' | number(ms)
+  passphrase: 'sekret',    // optional second factor
+});
+
+console.log(share.url);    // https://vibeshare.stream/s/<id>
+const { viewers, pending } = share.viewers();
+await share.revoke();      // tear down (also fires on expiry)
+```
+
+Spectators are enforced read-only at the access gate: a spectator's control request never reaches vibelive's `WriteArbiter`, so they can never obtain the write token — the same "never two concurrent writers" invariant vibelive holds, extended to the share.
+
+## As an MCP server
+
+Wire it into an agent that speaks MCP and it can offer "share this session?":
+
+```jsonc
+// .mcp.json or your client's MCP config
+{
+  "mcpServers": {
+    "vibeshare": { "command": "vibeshare", "args": ["mcp"] }
+  }
+}
+```
+
+Tools: `create_share` (host a command, mint a share URL) and `viewers` (list active shares + their audiences).
+
+## Prototype
+
+Interactive, self-contained UX prototype (no build, no network): open [`docs/prototype.html`](docs/prototype.html) in a browser.
+
+## License
+
+MIT.

package/dist/chunk-5OLI3WTU.js

@@ -0,0 +1,233 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/access.ts
+var DEFAULT_ACCESS = "spectate";
+function createAccessGate(options) {
+  const access = options.access ?? DEFAULT_ACCESS;
+  const arbiter = options.arbiter;
+  const passphrase = options.passphrase;
+  const roles = /* @__PURE__ */ new Map();
+  const hasPassphrase = typeof passphrase === "string" && passphrase.length > 0;
+  return {
+    access,
+    hasPassphrase,
+    admit({ id }, input) {
+      if (hasPassphrase && input !== passphrase) return false;
+      if (!roles.has(id)) roles.set(id, "spectator");
+      return true;
+    },
+    remove(id) {
+      roles.delete(id);
+      arbiter.leave(id);
+    },
+    has: (id) => roles.has(id),
+    role: (id) => roles.get(id),
+    promote(id) {
+      if (access !== "invite") return false;
+      if (!roles.has(id)) return false;
+      roles.set(id, "participant");
+      return true;
+    },
+    requestControl(id) {
+      const role = roles.get(id);
+      if (role === void 0) return { ok: false, reason: "unknown" };
+      if (role === "participant") {
+        const state = arbiter.requestControl(id);
+        return { ok: true, state };
+      }
+      return { ok: false, reason: access === "invite" ? "not-promoted" : "spectator" };
+    }
+  };
+}
+
+// src/url.ts
+var SHARE_ORIGIN = "https://vibeshare.stream";
+var SHARE_PATH_PREFIX = "/s/";
+function newShareId() {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (uuid) return uuid;
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function buildShareUrl(id, origin = SHARE_ORIGIN) {
+  return `${origin}${SHARE_PATH_PREFIX}${id}`;
+}
+var ShareUrlParseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ShareUrlParseError";
+  }
+};
+function parseShareUrl(url) {
+  if (typeof url !== "string" || url.length === 0) {
+    throw new ShareUrlParseError("share url must be a non-empty string");
+  }
+  const idx = url.indexOf(SHARE_PATH_PREFIX);
+  if (idx < 0) {
+    throw new ShareUrlParseError(`not a vibeshare share url (missing "${SHARE_PATH_PREFIX}"): ${url}`);
+  }
+  const tail = url.slice(idx + SHARE_PATH_PREFIX.length);
+  const end = tail.search(/[/?#]/);
+  const id = end < 0 ? tail : tail.slice(0, end);
+  if (id.length === 0) {
+    throw new ShareUrlParseError(`share url has an empty id: ${url}`);
+  }
+  return { id };
+}
+
+// src/share.ts
+import { SHARE_SESSION_SCOPE as VIBELIVE_SHARE_SCOPE } from "vibelive-cli";
+var SHARE_SESSION_SCOPE = VIBELIVE_SHARE_SCOPE;
+function parseExpiry(spec) {
+  if (spec === void 0) return null;
+  if (typeof spec === "number") {
+    if (!Number.isFinite(spec) || spec <= 0) {
+      throw new RangeError(`expiry duration must be a positive finite number (ms), got: ${spec}`);
+    }
+    return Math.floor(spec);
+  }
+  switch (spec) {
+    case "1h":
+      return 60 * 60 * 1e3;
+    case "24h":
+      return 24 * 60 * 60 * 1e3;
+    default: {
+      const exhaustive = spec;
+      throw new RangeError(`unknown expiry preset: ${String(exhaustive)}`);
+    }
+  }
+}
+var ConsentError = class extends Error {
+  constructor() {
+    super(`consent for "${SHARE_SESSION_SCOPE}" is required to share a session \u2014 grant it first`);
+    this.name = "ConsentError";
+  }
+};
+var HOST_PARTICIPANT_NAME = "host";
+function isLocalHostParticipant(p) {
+  return p.ws === void 0;
+}
+function participantName(p, fallback) {
+  return p.name && p.name.length > 0 ? p.name : fallback;
+}
+function createShare(options) {
+  const relay = options.session;
+  const consent = options.consent ?? relay.consent;
+  if (!consent.allows(SHARE_SESSION_SCOPE)) {
+    throw new ConsentError();
+  }
+  const id = newShareId();
+  const url = buildShareUrl(id);
+  const gate = createAccessGate({
+    arbiter: relay.arbiter,
+    access: options.access,
+    passphrase: options.passphrase
+  });
+  const firstSeen = /* @__PURE__ */ new Map();
+  const noteSeen = (pid) => {
+    let t = firstSeen.get(pid);
+    if (t === void 0) {
+      t = Date.now();
+      firstSeen.set(pid, t);
+    }
+    return t;
+  };
+  let revoked = false;
+  let revokeReason;
+  let expiryTimer;
+  const fireRevoke = (reason) => {
+    if (revoked) return Promise.resolve();
+    revoked = true;
+    revokeReason = reason;
+    if (expiryTimer !== void 0) {
+      clearTimeout(expiryTimer);
+      expiryTimer = void 0;
+    }
+    try {
+      options.onRevoke?.(reason);
+    } catch {
+    }
+    return relay.close().catch(() => {
+    });
+  };
+  const expiryMs = parseExpiry(options.expiry);
+  if (expiryMs !== null) {
+    expiryTimer = setTimeout(() => {
+      void fireRevoke("expired");
+    }, expiryMs);
+    expiryTimer.unref?.();
+  }
+  const toViewer = (p) => {
+    const pid = p.id;
+    if (!gate.has(pid)) {
+      gate.admit({ id: pid, name: participantName(p, pid) });
+    }
+    const role = gate.role(pid) ?? "spectator";
+    return {
+      id: pid,
+      name: participantName(p, pid),
+      role,
+      joinedAt: noteSeen(pid)
+    };
+  };
+  return {
+    id,
+    url,
+    access: gate.access,
+    gate,
+    relayUrl: relay.url,
+    get revoked() {
+      return revoked;
+    },
+    viewers() {
+      const connected = [];
+      const pending = [];
+      for (const p of relay.participants) {
+        if (isLocalHostParticipant(p)) continue;
+        const v = toViewer(p);
+        if (gate.access === "invite" && v.role !== "participant") {
+          pending.push(v);
+        } else {
+          connected.push(v);
+        }
+      }
+      return { viewers: connected, pending };
+    },
+    approve(viewerId) {
+      return gate.promote(viewerId);
+    },
+    removeViewer(viewerId) {
+      gate.remove(viewerId);
+    },
+    revoke() {
+      return fireRevoke(revokeReason === "expired" ? "expired" : "manual");
+    }
+  };
+}
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+export {
+  __export,
+  DEFAULT_ACCESS,
+  createAccessGate,
+  SHARE_ORIGIN,
+  SHARE_PATH_PREFIX,
+  newShareId,
+  buildShareUrl,
+  ShareUrlParseError,
+  parseShareUrl,
+  SHARE_SESSION_SCOPE,
+  parseExpiry,
+  ConsentError,
+  HOST_PARTICIPANT_NAME,
+  createShare,
+  VERSION
+};

package/dist/cli.d.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { A as AccessMode, E as ExpirySpec } from './share-CoX608sF.js';
+import 'vibelive-cli';
+import '@pooriaarab/vibe-core';
+
+type ParsedCommand = {
+    readonly cmd: 'help';
+} | {
+    readonly cmd: 'version';
+} | {
+    readonly cmd: 'mcp';
+} | {
+    readonly cmd: 'stop';
+} | {
+    readonly cmd: 'viewers';
+} | {
+    readonly cmd: 'host';
+    readonly command: readonly string[];
+    readonly access: AccessMode;
+    readonly expire?: ExpirySpec;
+    readonly pass?: string;
+    readonly name?: string;
+} | {
+    readonly cmd: 'error';
+    readonly message: string;
+};
+/**
+ * Parse vibeshare argv (`process.argv.slice(2)`). Pure — no IO.
+ *
+ * Everything after a bare `--` is the opaque wrapped command and is never scanned
+ * for vibeshare flags, so `vibeshare -- claude --help` wraps `claude --help`
+ * rather than printing vibeshare's own help. Both `vibeshare -- <cmd>` and the
+ * explicit `vibeshare host -- <cmd>` forms are accepted.
+ */
+declare function parseArgs(argv: readonly string[]): ParsedCommand;
+declare function printHelp(stream?: {
+    write(s: string): boolean;
+}): void;
+/** CLI entrypoint. Returns the desired exit code (does not call exit itself). */
+declare function main(argv?: readonly string[]): Promise<number>;
+
+export { main, parseArgs, printHelp };

package/dist/cli.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+import {
+  VERSION,
+  createShare
+} from "./chunk-5OLI3WTU.js";
+
+// src/cli.ts
+import { createInterface } from "readline";
+import { networkInterfaces } from "os";
+import { pathToFileURL } from "url";
+import { createHost, createRelay, SHARE_SESSION_SCOPE } from "vibelive-cli";
+var HOST_ID = "host";
+var BADGE = "\u25CF p2p \xB7 e2e \xB7 nothing stored on a server";
+var err = (message) => ({ cmd: "error", message });
+function parseArgs(argv) {
+  const dd = argv.indexOf("--");
+  const head = dd >= 0 ? argv.slice(0, dd) : [...argv];
+  const command = dd >= 0 ? argv.slice(dd + 1) : [];
+  if (head.includes("--help") || head.includes("-h")) return { cmd: "help" };
+  if (head.includes("--version") || head.includes("-v")) return { cmd: "version" };
+  const sub = head[0];
+  if (sub === "stop") return { cmd: "stop" };
+  if (sub === "viewers") return { cmd: "viewers" };
+  if (sub === "mcp") return { cmd: "mcp" };
+  if (head.length === 0 && command.length === 0) return { cmd: "help" };
+  let flagTokens;
+  if (sub === "host") {
+    flagTokens = head.slice(1);
+  } else if (sub === void 0 || sub.startsWith("-")) {
+    flagTokens = head;
+  } else {
+    return err(`unknown command: ${sub}`);
+  }
+  let access = "spectate";
+  let expire;
+  let pass;
+  let name;
+  for (let i = 0; i < flagTokens.length; i++) {
+    const t = flagTokens[i];
+    if (t === void 0) break;
+    const next = flagTokens[i + 1];
+    if (t === "--spectate") {
+      access = "spectate";
+    } else if (t === "--invite") {
+      access = "invite";
+    } else if (t === "--expire") {
+      if (next === void 0) return err("--expire requires a value (1h | 24h)");
+      if (next !== "1h" && next !== "24h") {
+        return err(`--expire must be "1h" or "24h", got: ${next}`);
+      }
+      expire = next;
+      i++;
+    } else if (t === "--pass") {
+      if (next === void 0) return err("--pass requires a value");
+      pass = next;
+      i++;
+    } else if (t === "--name") {
+      if (next === void 0) return err("--name requires a value");
+      name = next;
+      i++;
+    } else {
+      return err(`unknown flag: ${t}`);
+    }
+  }
+  if (command.length === 0) {
+    return err('vibeshare needs a command after "--", e.g. `vibeshare --invite -- claude`');
+  }
+  return { cmd: "host", command, access, expire, pass, name };
+}
+var HELP = `vibeshare ${VERSION} \u2014 share your live agent session by URL
+
+USAGE
+  vibeshare [--spectate|--invite] [--expire 1h|24h] [--pass <p>] -- <command...>
+  vibeshare host   [the flags above]                -- <command...>
+      Host a session running <command> (e.g. \`vibeshare --invite -- claude\`)
+      and print its share URL. You start as the driver.
+
+      --spectate   link holders get read-only access (default)
+      --invite     link holders may request to join; approve to let them drive
+      --expire     auto-revoke the share after 1h or 24h
+      --pass <p>   require a passphrase on top of the share URL
+      --name <s>   display name for the host participant
+
+  vibeshare stop        stop the foreground host session (also: /stop inside it)
+  vibeshare viewers     (in-foreground) list viewers / pending join requests
+  vibeshare mcp         run the vibeshare MCP server on stdio
+  vibeshare --version
+  vibeshare --help
+
+v0 is foreground, host-authoritative, local/LAN. The share URL points at your own
+domain (vibeshare.stream); the live stream runs over a self-hostable e2e relay.
+${BADGE}
+`;
+function printHelp(stream = process.stdout) {
+  stream.write(HELP);
+}
+function lanAddress() {
+  const nets = networkInterfaces();
+  for (const list of Object.values(nets)) {
+    if (!list) continue;
+    for (const n of list) {
+      if (n && n.family === "IPv4" && !n.internal) return n.address;
+    }
+  }
+  return null;
+}
+async function runHost(p) {
+  const host = createHost({ command: p.command });
+  const relay = await createRelay({
+    port: 0,
+    hostHandle: host,
+    initialDriver: HOST_ID,
+    hostParticipantName: p.name ?? HOST_ID
+  });
+  relay.consent.grant(SHARE_SESSION_SCOPE);
+  let expired = false;
+  const share = createShare({
+    session: relay,
+    access: p.access,
+    expiry: p.expire,
+    passphrase: p.pass,
+    onRevoke: (reason) => {
+      if (reason === "expired") expired = true;
+    }
+  });
+  host.onOutput((entry) => process.stdout.write(entry.text));
+  const accessLabel = p.access + (p.pass ? " \xB7 passphrase" : "") + (p.expire ? ` \xB7 expires ${p.expire}` : " \xB7 no expiry");
+  process.stderr.write(`vibeshare \u2014 sharing ${p.command.join(" ")}
+`);
+  process.stderr.write(`  share:  ${share.url}
+`);
+  process.stderr.write(`  access: ${accessLabel}
+`);
+  process.stderr.write(`  relay:  ${relay.url}
+`);
+  const lan = lanAddress();
+  if (lan) {
+    process.stderr.write(`  lan:     ws://${lan}:${relay.port}
+`);
+  }
+  process.stderr.write(`  ${BADGE}
+`);
+  process.stderr.write(
+    `  you are the driver. /release to hand off, /drive to take back, /viewers, /approve <id>, /stop to end.
+`
+  );
+  const rl = createInterface({ input: process.stdin, terminal: false });
+  const printViewers = () => {
+    const roster = share.viewers();
+    if (roster.viewers.length === 0 && roster.pending.length === 0) {
+      process.stderr.write("  (no viewers connected)\n");
+      return;
+    }
+    for (const v of roster.viewers) {
+      process.stderr.write(`  \u25CF ${v.name} [${v.role}]
+`);
+    }
+    for (const v of roster.pending) {
+      process.stderr.write(`  \u2026 ${v.name} [wants to join \u2014 /approve ${v.id}]
+`);
+    }
+  };
+  rl.on("line", (line) => {
+    if (line === "/stop" || line === "/quit") {
+      void shutdown(0);
+      return;
+    }
+    if (line === "/viewers") {
+      printViewers();
+      return;
+    }
+    if (line.startsWith("/approve ")) {
+      const id = line.slice("/approve ".length).trim();
+      const ok = share.approve(id);
+      process.stderr.write(ok ? `  promoted ${id}.
+` : `  can't promote ${id} (unknown / spectate-only).
+`);
+      return;
+    }
+    if (line === "/release") {
+      relay.localReleaseControl(HOST_ID);
+      process.stderr.write("  control released.\n");
+      return;
+    }
+    if (line === "/drive") {
+      relay.localRequestControl(HOST_ID);
+      process.stderr.write("  control requested.\n");
+      return;
+    }
+    if (relay.arbiter.isDriver(HOST_ID)) {
+      host.sendInput(`${line}
+`);
+    } else {
+      process.stderr.write("  (not the driver \u2014 /drive to take control)\n");
+    }
+  });
+  rl.on("SIGINT", () => void shutdown(0));
+  let shuttingDown = false;
+  const shutdown = async (code2) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    rl.close();
+    host.kill();
+    await share.revoke();
+    process.exit(code2);
+  };
+  process.on("SIGINT", () => void shutdown(130));
+  process.on("SIGTERM", () => void shutdown(143));
+  if (p.expire !== void 0) {
+    void promiseTrue(() => share.revoked).then(async () => {
+      if (expired) {
+        process.stderr.write("  share expired \u2014 tearing down.\n");
+        await shutdown(0);
+      }
+    });
+  }
+  const code = await host.exited;
+  await shutdown(code ?? 0);
+  return code ?? 0;
+}
+function promiseTrue(pred) {
+  return new Promise((resolve) => {
+    const tick = () => {
+      if (pred()) resolve();
+      else setTimeout(tick, 250);
+    };
+    tick();
+  });
+}
+async function runStop() {
+  process.stderr.write(
+    "vibeshare runs the host in the foreground. To stop it, switch to that terminal and\npress Ctrl+C (or type /stop). v0 does not yet daemonize or keep cross-process state.\n"
+  );
+  return 0;
+}
+async function runViewers() {
+  process.stderr.write(
+    "vibeshare runs the host in the foreground. Inside that session, type /viewers to list\nconnected viewers and pending join requests, and /approve <id> to promote one.\n"
+  );
+  return 0;
+}
+async function main(argv = process.argv.slice(2)) {
+  const parsed = parseArgs(argv);
+  switch (parsed.cmd) {
+    case "help":
+      printHelp();
+      return 0;
+    case "version":
+      process.stdout.write(`${VERSION}
+`);
+      return 0;
+    case "mcp": {
+      const { runMcpStdio } = await import("./mcp.js");
+      await runMcpStdio();
+      return 0;
+    }
+    case "stop":
+      return runStop();
+    case "viewers":
+      return runViewers();
+    case "host":
+      return runHost(parsed);
+    case "error":
+      process.stderr.write(`vibeshare: ${parsed.message}
+`);
+      printHelp(process.stderr);
+      return 2;
+  }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  void main().then((code) => process.exit(code));
+}
+export {
+  main,
+  parseArgs,
+  printHelp
+};