vibeshare-live 0.1.0

package/dist/share-CoX608sF.d.ts

@@ -0,0 +1,188 @@
+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 };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "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",
+  "license": "MIT",
+  "author": "Pooria Arab",
+  "bin": { "vibeshare": "./dist/cli.js" },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts src/mcp.ts --format esm --dts --clean",
+    "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"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/ws": "^8.5.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.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" }
+}