sema-cli 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# Sema
+
+> **Sema — the signal between you and your agents.**
+
+Sema is a mobile control console for AI CLI workflows running on a user's Mac.
+
+The first product promise:
+
+> Use an iPhone to monitor and control AI CLI sessions running on a Mac, without managing SSH, tmux, Tailscale, or fragile mobile network reconnection by hand.
+
+## Quick Start
+
+```bash
+# Run instantly (no install):
+npx sema-cli claude
+
+# Or install globally:
+npm install -g sema-cli
+sema claude
+```
+
+Requires macOS + Node 22+ + tmux. A QR code appears in your terminal — scan it with your phone, confirm the fingerprint, and your agent can reach you on the go. End-to-end encrypted (X25519 + AES-256-GCM); the relay sees only ciphertext.
+
+## Why "Sema"
+
+From Greek **σῆμα** — *a sign, a signal* — and the root of **semantics**. The product's job is to turn an agent's raw terminal output into the one signal a human can act on in seconds. That same semantic layer is the product's technical moat (`docs/PRODUCT.md`): SSH will never do this. A *sema* is what an agent sends when it needs you.
+
+## Current Stage
+
+Stage: project kickoff.
+
+The project is not yet in product code mode. We are first setting up the operating system for Vibe Coding:
+
+- product scope
+- agent organization
+- collaboration loop
+- system architecture
+- security model
+- acceptance tests
+- Sprint 1 plan
+
+## First Milestone
+
+The first milestone is a technical slice:
+
+```text
+Mac local shell process
+-> WebSocket relay
+-> mobile web page
+-> output visible on phone
+-> phone input written back to shell
+```
+
+This milestone proves the core remote-control loop before investing in native macOS or iOS apps.
+
+## Directory Map
+
+```text
+docs/                  Project strategy, architecture, security, and process docs
+apps/mac-agent/         Future macOS local agent
+apps/mobile-pwa/        First mobile prototype
+apps/ios-app/           Future native iOS app
+services/relay-server/  Future relay service
+experiments/            Throwaway technical spikes
+ops/                    Demo, beta, launch, and user feedback artifacts
+prompts/                Reusable Vibe Coding prompts and role briefs
+```
+
+## Working Rule
+
+Every implementation task must have:
+
+1. one clear goal
+2. one owner agent
+3. one acceptance test
+4. one way to run it locally
+5. one decision log entry if it changes architecture or security
+

package/experiments/spike-shell-stream/bin/analytics.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+/**
+ * Sema Analytics CLI
+ *
+ * Reads event data from data/events.jsonl and waitlist from data/waitlist.jsonl,
+ * outputs usage statistics to the terminal.
+ *
+ * Usage:
+ *   node bin/analytics.js           # All-time stats
+ *   node bin/analytics.js --days 7  # Last N days
+ *   node bin/analytics.js --raw     # Raw JSONL output
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const DATA_DIR = path.join(__dirname, "../../../data");
+const EVENTS_FILE = path.join(DATA_DIR, "events.jsonl");
+const WAITLIST_FILE = path.join(DATA_DIR, "waitlist.jsonl");
+
+// Parse CLI args
+const args = process.argv.slice(2);
+const daysArg = args.indexOf("--days");
+const daysFilter = daysArg !== -1 ? Number(args[daysArg + 1]) : null;
+const rawMode = args.includes("--raw");
+
+function readJsonl(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8").trim();
+    if (!raw) return [];
+    return raw.split("\n").map(line => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+// Read data
+let events = readJsonl(EVENTS_FILE);
+const waitlist = readJsonl(WAITLIST_FILE);
+
+// Apply date filter
+if (daysFilter) {
+  const cutoff = new Date(Date.now() - daysFilter * 24 * 60 * 60 * 1000).toISOString();
+  events = events.filter(e => e.t >= cutoff);
+}
+
+// Raw mode
+if (rawMode) {
+  console.log(JSON.stringify({ events, waitlist }, null, 2));
+  process.exit(0);
+}
+
+// --- Aggregate ---
+
+function count(type, filter) {
+  return events.filter(e => e.type === type && (!filter || filter(e))).length;
+}
+
+const sessionCreated = count("session.created");
+const sessionCleaned = count("session.cleaned");
+const pairCompleted = count("pair.completed");
+const pairFailed = count("pair.failed");
+const alertTotal = count("alert.sent");
+const alertSmart = count("alert.sent", e => e.kind === "smart_alert");
+const alertIdle = alertTotal - alertSmart;
+const keyExchanges = count("key_exchange.completed");
+const macConnects = count("ws.connected", e => e.role === "mac");
+const mobileConnects = count("ws.connected", e => e.role === "mobile");
+const disconnections = events.filter(e => e.type === "ws.disconnected" && e.durationMs);
+
+// Connection duration stats
+let avgDurationMin = 0;
+let maxDurationMin = 0;
+if (disconnections.length) {
+  const durations = disconnections.map(e => e.durationMs);
+  avgDurationMin = Math.round(durations.reduce((a, b) => a + b, 0) / durations.length / 60000);
+  maxDurationMin = Math.round(Math.max(...durations) / 60000);
+}
+
+// Session lifetime stats
+const cleanedSessions = events.filter(e => e.type === "session.cleaned" && e.lifetimeMs);
+let avgLifetimeMin = 0;
+if (cleanedSessions.length) {
+  const lifetimes = cleanedSessions.map(e => e.lifetimeMs);
+  avgLifetimeMin = Math.round(lifetimes.reduce((a, b) => a + b, 0) / lifetimes.length / 60000);
+}
+
+// Daily breakdown
+const byDay = {};
+for (const e of events) {
+  const day = e.t.slice(0, 10);
+  if (!byDay[day]) byDay[day] = { sessions: 0, pairs: 0, alerts: 0 };
+  if (e.type === "session.created") byDay[day].sessions++;
+  if (e.type === "pair.completed") byDay[day].pairs++;
+  if (e.type === "alert.sent") byDay[day].alerts++;
+}
+
+// Hourly distribution (when do users connect?)
+const byHour = new Array(24).fill(0);
+for (const e of events) {
+  if (e.type === "ws.connected") {
+    const hour = new Date(e.t).getHours();
+    byHour[hour]++;
+  }
+}
+
+// Pair success rate
+const pairTotal = pairCompleted + pairFailed;
+const pairSuccessRate = pairTotal > 0 ? Math.round((pairCompleted / pairTotal) * 100) : 0;
+
+// Waitlist pricing distribution
+const pricingDist = {};
+for (const w of waitlist) {
+  const p = w.pricing || "unspecified";
+  pricingDist[p] = (pricingDist[p] || 0) + 1;
+}
+
+// --- Output ---
+
+const period = daysFilter ? `Last ${daysFilter} days` : "All time";
+const eventRange = events.length
+  ? `${events[0].t.slice(0, 10)} → ${events[events.length - 1].t.slice(0, 10)}`
+  : "No events yet";
+
+console.log("");
+console.log("╔══════════════════════════════════════════╗");
+console.log("║        Sema Analytics             ║");
+console.log("╚══════════════════════════════════════════╝");
+console.log("");
+console.log(`  Period: ${period} (${eventRange})`);
+console.log(`  Total events: ${events.length}`);
+console.log("");
+
+console.log("  ─── Sessions ───");
+console.log(`  Created:    ${sessionCreated}`);
+console.log(`  Cleaned:    ${sessionCleaned}`);
+if (cleanedSessions.length) {
+  console.log(`  Avg lifetime: ${avgLifetimeMin} min`);
+}
+console.log("");
+
+console.log("  ─── Pairing ───");
+console.log(`  Completed:  ${pairCompleted}`);
+console.log(`  Failed:     ${pairFailed}`);
+if (pairTotal > 0) {
+  console.log(`  Success rate: ${pairSuccessRate}%`);
+}
+console.log("");
+
+console.log("  ─── Alerts ───");
+console.log(`  Total:      ${alertTotal}`);
+console.log(`  Smart:      ${alertSmart}`);
+console.log(`  Idle:       ${alertIdle}`);
+console.log("");
+
+console.log("  ─── Connections ───");
+console.log(`  Mac:        ${macConnects}`);
+console.log(`  Mobile:     ${mobileConnects}`);
+if (disconnections.length) {
+  console.log(`  Avg duration: ${avgDurationMin} min`);
+  console.log(`  Max duration: ${maxDurationMin} min`);
+}
+console.log(`  Key exchanges: ${keyExchanges}`);
+console.log("");
+
+if (waitlist.length) {
+  console.log("  ─── Waitlist ───");
+  console.log(`  Signups:    ${waitlist.length}`);
+  if (Object.keys(pricingDist).length) {
+    console.log("  Pricing preferences:");
+    for (const [price, cnt] of Object.entries(pricingDist).sort((a, b) => b[1] - a[1])) {
+      console.log(`    ${price.padEnd(16)} ${cnt}`);
+    }
+  }
+  console.log("");
+}
+
+if (Object.keys(byDay).length > 0) {
+  console.log("  ─── Daily Breakdown ───");
+  console.log("  Date        Sessions  Pairs  Alerts");
+  const sortedDays = Object.entries(byDay).sort((a, b) => b[0].localeCompare(a[0]));
+  for (const [day, d] of sortedDays.slice(0, 14)) {
+    console.log(`  ${day}  ${String(d.sessions).padStart(8)}  ${String(d.pairs).padStart(5)}  ${String(d.alerts).padStart(6)}`);
+  }
+  console.log("");
+}
+
+// Peak hours
+const peakHours = byHour
+  .map((count, hour) => ({ hour, count }))
+  .filter(h => h.count > 0)
+  .sort((a, b) => b.count - a.count);
+
+if (peakHours.length) {
+  console.log("  ─── Peak Hours ───");
+  for (const h of peakHours.slice(0, 5)) {
+    const label = `${String(h.hour).padStart(2, "0")}:00`;
+    const bar = "█".repeat(Math.min(h.count, 30));
+    console.log(`  ${label}  ${bar} ${h.count}`);
+  }
+  console.log("");
+}
+
+if (events.length === 0) {
+  console.log("  No events recorded yet.");
+  console.log("  Start the relay and create a session to generate events.");
+  console.log("");
+}

package/experiments/spike-shell-stream/bin/sema.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+
+/**
+ * Sema CLI — Public relay mode
+ *
+ * Usage:
+ *   sema claude                  # Start Claude Code with public relay
+ *   sema claude codex            # Multi-agent
+ *   sema --local claude          # Local relay mode (same as start.js)
+ *   RELAY_URL=https://my-relay.com sema claude   # Custom relay
+ */
+
+const { fork } = require("node:child_process");
+const http = require("node:http");
+const https = require("node:https");
+const path = require("node:path");
+
+const { generateKeyPair, exportPublicKey, exportPrivateKey } = require(
+  path.join(__dirname, "../shared/crypto"),
+);
+
+// --- Config ---
+
+// Default public relay — deployed on Railway (see docs/DEPLOY.md).
+// Override per-run with: SEMA_RELAY=https://<other-relay> sema claude
+const DEFAULT_RELAY_HTTP = process.env.SEMA_RELAY || "https://sema-relay.up.railway.app";
+const args = process.argv.slice(2);
+const USE_LOCAL = args.includes("--local");
+
+if (USE_LOCAL) {
+  // Delegate to local mode (starts relay + agent together)
+  const filteredArgs = args.filter((a) => a !== "--local");
+  process.argv = [process.argv[0], process.argv[1], ...filteredArgs];
+  require("./start.js");
+  return;
+}
+
+const RELAY_HTTP = (process.env.SEMA_RELAY || DEFAULT_RELAY_HTTP).replace(/\/$/, "");
+const RELAY_WS = RELAY_HTTP.replace(/^http:/, "ws:").replace(/^https:/, "wss:") + "/ws";
+
+const SPIKE_DIR = path.resolve(__dirname, "..");
+const AGENT_SCRIPT = path.join(SPIKE_DIR, "mac-agent/agent.js");
+
+// CLI arguments: one or more commands to run (e.g., "claude", "claude codex")
+const COMMANDS = args.filter((a) => !a.startsWith("--"));
+const commands = COMMANDS.length > 0 ? COMMANDS : [null]; // [null] = default shell
+
+const agentProcesses = [];
+let shuttingDown = false;
+
+// --- HTTP helpers (support both http and https) ---
+
+function getLib(urlString) {
+  return new URL(urlString).protocol === "https:" ? https : http;
+}
+
+function httpGet(urlString) {
+  return new Promise((resolve, reject) => {
+    const lib = getLib(urlString);
+    const req = lib.get(urlString, { timeout: 5000 }, (res) => {
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () =>
+        resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString() }),
+      );
+    });
+    req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error("timeout"));
+    });
+  });
+}
+
+function httpPost(urlString, body = null) {
+  return new Promise((resolve, reject) => {
+    const parsedUrl = new URL(urlString);
+    const lib = getLib(urlString);
+    const payload = body ? JSON.stringify(body) : null;
+    const req = lib.request(
+      {
+        hostname: parsedUrl.hostname,
+        port: parsedUrl.port || (parsedUrl.protocol === "https:" ? 443 : 80),
+        path: parsedUrl.pathname,
+        method: "POST",
+        timeout: 10000,
+        headers: payload
+          ? { "content-type": "application/json", "content-length": Buffer.byteLength(payload) }
+          : {},
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          try {
+            resolve({
+              status: res.statusCode,
+              data: JSON.parse(Buffer.concat(chunks).toString()),
+            });
+          } catch {
+            reject(new Error("Invalid JSON from relay"));
+          }
+        });
+      },
+    );
+    req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error("timeout"));
+    });
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+// --- Agent management ---
+
+function startAgent(sessionId, macToken, macPrivateKey, macPublicKey, command) {
+  const label = command || "shell";
+  const env = {
+    ...process.env,
+    SESSION_ID: sessionId,
+    SESSION_TOKEN: macToken,
+    RELAY_URL: RELAY_WS,
+    MAC_PRIVATE_KEY: macPrivateKey,
+    MAC_PUBLIC_KEY: macPublicKey,
+  };
+
+  if (command) {
+    env.CLI_COMMAND = command;
+  }
+
+  const agent = fork(AGENT_SCRIPT, [], {
+    env,
+    stdio: "pipe",
+  });
+
+  agent.stdout.on("data", (data) => {
+    const msg = data.toString().trim();
+    if (msg) console.log(`  [${label}] ${msg.replace(/^\[mac-agent\] /, "")}`);
+  });
+
+  agent.stderr.on("data", (data) => {
+    const msg = data.toString().trim();
+    if (msg) console.error(`  [${label}:err] ${msg}`);
+  });
+
+  agent.on("exit", (code) => {
+    if (!shuttingDown) {
+      console.log(`\n[start] Agent "${label}" exited (code: ${code || 0}).`);
+      const idx = agentProcesses.findIndex((a) => a.process === agent);
+      if (idx >= 0) agentProcesses.splice(idx, 1);
+      if (agentProcesses.length === 0) {
+        console.log("[start] All agents exited. Shutting down.");
+        cleanup();
+        process.exit(code || 0);
+      }
+    }
+  });
+
+  return agent;
+}
+
+// --- Cleanup ---
+
+function cleanup() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+
+  for (const { process: agent } of agentProcesses) {
+    if (agent && !agent.killed) agent.kill("SIGTERM");
+  }
+
+  setTimeout(() => {
+    for (const { process: agent } of agentProcesses) {
+      if (agent && !agent.killed) agent.kill("SIGKILL");
+    }
+  }, 3000);
+}
+
+process.on("SIGINT", () => {
+  console.log("\n[start] Shutting down...");
+  cleanup();
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  cleanup();
+  process.exit(0);
+});
+
+process.on("uncaughtException", (err) => {
+  console.error(`\n\x1b[31m[start] Uncaught error: ${err.message}\x1b[0m`);
+  cleanup();
+  process.exit(1);
+});
+
+// --- Display ---
+
+function displayInfo(sessionInfos) {
+  const qrcode = require("qrcode-terminal");
+  const pairUrl = `${RELAY_HTTP}/pair?code=${sessionInfos[0].code}`;
+
+  console.log("");
+  console.log("┌─────────────────────────────────────┐");
+  if (sessionInfos.length === 1) {
+    console.log("│     \x1b[1;32mSema Session Ready\x1b[0m       │");
+  } else {
+    console.log(`│   \x1b[1;32mSema — ${sessionInfos.length} Agents Ready\x1b[0m      │`);
+  }
+  console.log("└─────────────────────────────────────┘");
+  console.log("");
+
+  qrcode.generate(pairUrl, { small: true }, (qr) => {
+    console.log(qr);
+    console.log("");
+    console.log(`  \x1b[2mScan with phone camera, or visit:\x1b[0m`);
+    console.log(`  \x1b[1;36m${pairUrl}\x1b[0m`);
+    console.log("");
+
+    if (sessionInfos.length > 1) {
+      console.log("  Sessions:");
+    }
+    for (let i = 0; i < sessionInfos.length; i++) {
+      const info = sessionInfos[i];
+      const prefix = sessionInfos.length > 1 ? `  ${i + 1}. ` : "  ";
+      const label = info.label.padEnd(12);
+      console.log(`${prefix}\x1b[1m${label}\x1b[0m Code: \x1b[1;36m${info.code}\x1b[0m`);
+    }
+    console.log("");
+    console.log(`  \x1b[2mRelay: ${RELAY_HTTP}\x1b[0m`);
+    console.log("  \x1b[2mPress Ctrl+C to stop.\x1b[0m");
+    console.log("");
+  });
+}
+
+// --- Main ---
+
+async function main() {
+  console.log("");
+  console.log("  \x1b[1mSema\x1b[0m");
+  console.log("");
+
+  // 1. Check relay health
+  console.log(`[start] Connecting to relay at ${RELAY_HTTP}...`);
+  try {
+    const res = await httpGet(`${RELAY_HTTP}/health`);
+    if (res.status !== 200) throw new Error(`Relay returned HTTP ${res.status}`);
+  } catch (err) {
+    console.error(`\x1b[31m✗ Cannot reach relay at ${RELAY_HTTP}\x1b[0m`);
+    console.error(`  ${err.message}`);
+    console.error("");
+    console.error("  Options:");
+    console.error("  • Check your internet connection");
+    console.error("  • Set SEMA_RELAY=<url> for a custom relay");
+    console.error("  • Use --local to run a local relay instead");
+    console.error("");
+    process.exit(1);
+  }
+  console.log("[start] Relay is reachable.");
+
+  // 2. Create sessions + start agents
+  const sessionInfos = [];
+
+  for (const command of commands) {
+    const label = command || "shell";
+
+    // Generate E2E keypair
+    console.log(`[start] Generating keys for ${label}...`);
+    const keyPair = generateKeyPair();
+    const macPublicKey = exportPublicKey(keyPair.publicKey);
+    const macPrivateKey = exportPrivateKey(keyPair.privateKey);
+
+    // Create session on public relay
+    console.log(`[start] Creating session for ${label}...`);
+    let sessionData;
+    try {
+      const res = await httpPost(`${RELAY_HTTP}/api/sessions`, {
+        macPublicKey,
+        command: command || null,
+      });
+      if (res.status !== 201) {
+        throw new Error(res.data.error || `HTTP ${res.status}`);
+      }
+      sessionData = res.data;
+    } catch (err) {
+      console.error(`\x1b[31m✗ Failed to create session for ${label}: ${err.message}\x1b[0m`);
+      cleanup();
+      process.exit(1);
+    }
+
+    sessionInfos.push({
+      label,
+      code: sessionData.code,
+      sessionId: sessionData.sessionId,
+    });
+
+    // Start agent
+    const agent = startAgent(
+      sessionData.sessionId,
+      sessionData.macToken,
+      macPrivateKey,
+      macPublicKey,
+      command,
+    );
+    agentProcesses.push({
+      process: agent,
+      command,
+      label,
+      sessionId: sessionData.sessionId,
+    });
+  }
+
+  // 3. Display QR + session info
+  displayInfo(sessionInfos);
+}
+
+main().catch((err) => {
+  console.error(`\x1b[31m✗ ${err.message}\x1b[0m`);
+  cleanup();
+  process.exit(1);
+});