vibeshare-live 0.1.0 → 0.2.0

package/docs/spec.md

@@ -0,0 +1,61 @@
+# vibeshare — spec
+
+Status: DRAFT (Opus-authored) · 2026-07-25 · depends on `@vibe/core` + vibelive
+Identity: vibeshare.stream (available $4/yr — its OWN domain, not vibe.live) · CLI + npm + MCP
+Prior art: traces.com (but open source, CLI-first) · Happy (slopus/happy) transport
+
+## What it is
+Share your **live** agent coding session by URL. The distribution layer on top of
+**vibelive** (the multiplayer engine): a link that lets people **spectate read-only**
+or be **invited into the live multiplayer session**.
+
+## Relationship to vibelive
+- **vibelive** = the engine (transport, presence, cursors, chat, write-arbitration).
+- **vibeshare** = the URL/identity/access layer: create a shareable link, set access
+  policy, let viewers request to join → hands off into vibelive.
+- A spectator is a vibelive participant with read-only + no cursor-write; "join"
+  promotes them to a full participant. vibeshare owns the *link + gate*, vibelive
+  owns the *session*.
+
+## The flow
+1. `vibeshare` in your terminal → generates `vibeshare.io/s/<id>` (its own domain).
+2. Access policy: **spectate** (read-only) ↔ **invite** (can join to collaborate);
+   expiry (1h / 24h / until I stop); optional passphrase.
+3. Recipients open the URL → read-only live view of your terminal (agent output
+   streams via vibelive's ordered-log channel). "Request to join" → host approves →
+   promoted into the live session.
+
+## Local-first / transport (inherits vibelive §1-2)
+Session streamed **peer-to-peer / via a dumb e2e-encrypted relay** — the relay
+forwards opaque blobs, **nothing readable stored on a server**, relay self-hostable.
+Badge: "● p2p · e2e · nothing stored on a server". `share:session` consent grant
+required (§4). Spectator-heavy sharing = pub/sub fan-out tier (scales to the vibelive
+1,000 spectator target).
+
+## Access / safety
+- Link is a capability URL (unguessable id); passphrase optional second factor.
+- Read-only spectators genuinely can't write (enforced server-of-record = host, not
+  UI-only) — same write-arbitration invariant as vibelive §4.
+- Revoke link / kick viewer / lock to invite-only, live.
+- Expiry auto-tears down the relay subscription.
+
+## Surfaces
+- **CLI:** `vibeshare [--spectate|--invite] [--expire 1h] [--pass]` → prints URL ·
+  `vibeshare stop` · `vibeshare viewers` (see/kick/approve).
+- **npm:** `createShare({session, access, expiry})` → `{url, revoke}`.
+- **MCP:** `vibeshare.create`, `vibeshare.viewers` — agent can offer "share this
+  session?"
+- **Web spectator view:** the URL target — a minimal read-only vibelive client
+  (self-contained, no install for viewers).
+
+## Cross-harness
+Wraps whatever agent vibelive is hosting (Claude Code / Codex / Cursor / Gemini /
+Grok / pi / Kimi / …). Harness-agnostic via vibelive.
+
+## Open questions
+- Web spectator client hosting: served from the self-hostable relay, or a static
+  page + relay data channel? Prefer static page (any host / IPFS) + e2e relay data,
+  so "open source, self-host everything" holds.
+- Public/discoverable shares (a directory of live sessions) vs link-only — v0 =
+  link-only (privacy default); discovery opt-in later.
+- Recording a shared session to replay (→ vibemovie handoff) — v2.

package/package.json

@@ -1,38 +1,56 @@
 {
   "name": "vibeshare-live",
-  "version": "0.1.0",
-  "description": "Share your live agent coding session by URL — spectate read-only or invite into the vibelive multiplayer engine. Open source, CLI-first, e2e p2p. Local-first.",
-  "type": "module",
+  "version": "0.2.0",
+  "description": "Share your live agent coding session by URL — spectate read-only or invite into the session. Local-first: runs on your machine, nothing readable leaves without consent. Part of the Vibe Suite.",
   "license": "MIT",
-  "author": "Pooria Arab",
-  "bin": { "vibeshare": "./dist/cli.js" },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "vibeshare": "./dist/cli.js",
+    "vibeshare-mcp": "./dist/mcp.js"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts src/mcp.ts --format esm --dts --clean",
+    "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@pooriaarab/vibe-core": "^0.1.0",
-    "vibelive-cli": "^0.1.0",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "ws": "^8.16.0"
+    "@pooriaarab/vibe-core": "^0.2.0",
+    "vibelive": "^0.2.0"
   },
   "devDependencies": {
-    "@types/node": "^20.11.0",
-    "@types/ws": "^8.5.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.4.0",
-    "vitest": "^1.6.0"
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
   },
-  "homepage": "https://github.com/pooriaarab/vibeshare#readme",
-  "repository": { "type": "git", "url": "git+https://github.com/pooriaarab/vibeshare.git" },
-  "bugs": { "url": "https://github.com/pooriaarab/vibeshare/issues" },
-  "keywords": ["vibe-suite", "vibeshare", "claude-code", "codex", "multiplayer", "cli", "mcp", "share", "local-first"],
-  "publishConfig": { "access": "public" },
-  "engines": { "node": ">=18" }
+  "keywords": [
+    "vibe-suite",
+    "pair-programming",
+    "live-share",
+    "agentic-coding",
+    "cli",
+    "mcp",
+    "local-first"
+  ]
 }

package/dist/chunk-5OLI3WTU.js

@@ -1,233 +0,0 @@
-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/share-CoX608sF.d.ts

@@ -1,188 +0,0 @@
-import { ControlState, WriteArbiter, RelayHandle } from 'vibelive-cli';
-import { ConsentLedger } from '@pooriaarab/vibe-core';
-
-/**
- * The access gate — the correctness-critical piece of vibeshare.
- *
- * Background (docs/spec.md · "Access / safety"): a shared link carries an access
- * policy. **Spectators** are read-only: they see the live agent output stream but
- * can never drive the wrapped agent. **Invite** viewers may be promoted to a full
- * vibelive participant (request control → drive).
- *
- * The invariant vibeshare adds on top of vibelive:
- *
- *   > A spectator NEVER obtains the write token.
- *
- * We do NOT enforce this in the UI only. We enforce it by never letting a
- * spectator reach the write-arbitration state machine: the gate swallows their
- * `requestControl` and returns `null` (denied) without touching the arbiter, so a
- * spectator is never the driver and never enters the FIFO queue. The same
- * `WriteArbiter` vibelive uses to guarantee "never two concurrent writers" is the
- * witness we assert against (see `src/access.test.ts`): after a spectator request,
- * `arbiter.isDriver(spectatorId) === false` and the queue does not contain them.
- *
- * This module is pure logic over an injected arbiter — no IO, no network — so the
- * invariant is fully unit-testable.
- */
-
-/** Who a share link lets its holders do. */
-type AccessMode = 'spectate' | 'invite';
-/** Default access when a share is created without an explicit policy. */
-declare const DEFAULT_ACCESS: AccessMode;
-/** The role a particular viewer currently holds inside a share. */
-type ViewerRole = 'spectator' | 'participant';
-/** Denial reasons surfaced to callers / tests. */
-type DenialReason = 'spectator' | 'not-promoted' | 'unknown';
-/** Result of a (possibly-denied) control request. */
-type ControlRequestResult = {
-    readonly ok: true;
-    readonly state: ControlState;
-} | {
-    readonly ok: false;
-    readonly reason: DenialReason;
-};
-interface AccessGateOptions {
-    /** The real vibelive write-arbiter the gate mediates. */
-    readonly arbiter: WriteArbiter;
-    /** The share's access policy. */
-    readonly access?: AccessMode;
-    /**
-     * Optional passphrase. When set, `verifyPassphrase` must pass before a viewer is
-     * admitted at all (a second factor on top of the capability URL).
-     */
-    readonly passphrase?: string;
-}
-/**
- * The access gate. Owns the per-viewer role bookkeeping and mediates every write
- * request through the injected vibelive {@link WriteArbiter}. Stateless w.r.t. the
- * network — the CLI/MCP wire viewers in and call `requestControl`/`approve`.
- */
-interface AccessGate {
-    /** This share's access policy. */
-    readonly access: AccessMode;
-    /** True iff a passphrase is required to join this share. */
-    readonly hasPassphrase: boolean;
-    /** Admit a new viewer (recorded at the share's default role). Idempotent. */
-    admit(viewer: {
-        readonly id: string;
-        readonly name: string;
-    }, passphrase?: string): boolean;
-    /** Remove a viewer (e.g. on disconnect / kick). Releases the token if they hold it. */
-    remove(viewerId: string): void;
-    /** True iff this viewer id is known to the gate. */
-    has(viewerId: string): boolean;
-    /** This viewer's current role, or `undefined` if unknown. */
-    role(viewerId: string): ViewerRole | undefined;
-    /**
-     * Promote an invite viewer into a full participant (eligible to drive).
-     * Only meaningful under `access: 'invite'`. Returns false if the viewer is
-     * unknown or the share is spectate-only.
-     */
-    promote(viewerId: string): boolean;
-    /**
-     * Request the write token on behalf of a viewer.
-     *
-     * - Spectators (any share) → denied (`reason: 'spectator'`), arbiter untouched.
-     * - Invite viewers not yet promoted → denied (`reason: 'not-promoted'`).
-     * - Promoted invite viewers → forwards to the arbiter and returns its snapshot.
-     *
-     * This is the single chokepoint that upholds "a spectator never obtains the
-     * write token" against the real vibelive arbiter.
-     */
-    requestControl(viewerId: string): ControlRequestResult;
-}
-declare function createAccessGate(options: AccessGateOptions): AccessGate;
-
-/**
- * The share orchestrator — the public library surface.
- *
- * vibeshare is the URL/access layer ON TOP of vibelive's engine: it does not
- * reimplement transport. {@link createShare} takes an already-running vibelive
- * relay (the host's local/LAN ws server) and mints a capability URL + access gate
- * + expiry around it. Spectators connect to the relay as ordinary vibelive
- * participants (they get the ordered output fan-out) but the access gate ensures
- * they can never drive the wrapped agent.
- *
- * Consent: vibeshare gates fanning session output off the host machine behind the
- * `share:session` scope from `@pooriaarab/vibe-core`. `createShare` refuses to
- * mint a share unless that grant is present (the CLI grants it; a bare library
- * caller must too), which is the same local-first enforcement vibelive uses.
- */
-
-/** The consent scope that gates sharing a session off the host machine. */
-declare const SHARE_SESSION_SCOPE = "share:session";
-/** Expiry specification: a preset, or a raw duration in milliseconds. */
-type ExpirySpec = '1h' | '24h' | number;
-/**
- * Parse an expiry spec into a duration in milliseconds, or `null` for "never".
- *
- * Pure and total — unit-tested directly. `undefined` → never expires.
- */
-declare function parseExpiry(spec: ExpirySpec | undefined): number | null;
-/** A viewer of a share, derived from the live vibelive roster + the access gate. */
-interface Viewer {
-    readonly id: string;
-    readonly name: string;
-    /** Current role — spectators can't drive; participants can. */
-    readonly role: ViewerRole;
-    readonly joinedAt: number;
-}
-/** A snapshot of a share's audience. */
-interface ViewerRoster {
-    readonly viewers: readonly Viewer[];
-    /** Invite viewers awaiting host promotion (join requests). */
-    readonly pending: readonly Viewer[];
-}
-/** Why a share tore down. Surfaced via {@link ShareOptions.onRevoke}. */
-type RevokeReason = 'manual' | 'expired';
-interface ShareOptions {
-    /** The running vibelive relay whose session is being shared. */
-    readonly session: RelayHandle;
-    /** Access policy for link holders. Defaults to spectate (read-only). */
-    readonly access?: AccessMode;
-    /** Optional expiry (auto-revokes the share after this elapses). */
-    readonly expiry?: ExpirySpec;
-    /** Optional passphrase — a second factor on top of the capability URL. */
-    readonly passphrase?: string;
-    /**
-     * Optional explicit consent ledger. Defaults to the relay's own ledger, which
-     * vibelive seeds with `share:session` granted. If you pass a different ledger it
-     * must hold the grant or `createShare` throws.
-     */
-    readonly consent?: ConsentLedger;
-    /** Called exactly once when the share tears down (manual revoke or expiry). */
-    readonly onRevoke?: (reason: RevokeReason) => void;
-}
-interface ShareHandle {
-    /** The unguessable capability id backing this share. */
-    readonly id: string;
-    /** The human-facing share URL (`https://vibeshare.stream/s/<id>`). */
-    readonly url: string;
-    /** This share's access policy. */
-    readonly access: AccessMode;
-    /** True once revoked (manually or by expiry). */
-    readonly revoked: boolean;
-    /** The underlying access gate (exposed for tests + advanced callers). */
-    readonly gate: AccessGate;
-    /** The local/LAN relay URL viewers actually connect over. */
-    readonly relayUrl: string;
-    /** Live audience snapshot: connected viewers + pending join requests. */
-    viewers(): ViewerRoster;
-    /**
-     * Promote a pending invite viewer into a participant (lets them request control).
-     * Invite shares only. Returns false if unknown / spectate share.
-     */
-    approve(viewerId: string): boolean;
-    /** Remove a viewer (disconnect handling / kick). Releases the token if held. */
-    removeViewer(viewerId: string): void;
-    /** Tear down the share: clear the expiry timer and close the vibelive relay. */
-    revoke(): Promise<void>;
-}
-/** Error thrown when consent for `share:session` has not been granted. */
-declare class ConsentError extends Error {
-    constructor();
-}
-declare const HOST_PARTICIPANT_NAME = "host";
-declare function createShare(options: ShareOptions): ShareHandle;
-
-export { type AccessMode as A, ConsentError as C, DEFAULT_ACCESS as D, type ExpirySpec as E, HOST_PARTICIPANT_NAME as H, type RevokeReason as R, SHARE_SESSION_SCOPE as S, type Viewer as V, type AccessGate as a, type AccessGateOptions as b, type ControlRequestResult as c, type DenialReason as d, type ShareHandle as e, type ShareOptions as f, type ViewerRole as g, type ViewerRoster as h, createAccessGate as i, createShare as j, parseExpiry as p };