@videlic/connect 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @videlic/connect
+
+Connects your coding agent to [Videlic](https://videlic.dev). One cross-platform
+command — works the same in PowerShell, cmd, bash, and zsh:
+
+```
+npx @videlic/connect ao_your_key
+```
+
+It registers a Claude Code **Stop hook** so every finished session is sent to
+Videlic for review. No bash, no `jq`, no `curl | sh` — just the Node that Claude
+Code already ships with, so macOS, Windows, and Linux use the identical command.
+
+## What it does
+
+1. Confirms Claude Code is present (`~/.claude`).
+2. Validates your key against the Videlic API.
+3. Copies the hook to `~/.claude/videlic-hook.mjs`.
+4. Writes `~/.claude/videlic.json` (`key`, `apiUrl`, `installedAt`).
+5. Registers the hook in `~/.claude/settings.json` (idempotent — re-running
+   upgrades in place and migrates off the older shell hook).
+
+## Notes
+
+- The hook only runs when a session **ends** — nothing in the background.
+- Sessions that started **before** install are skipped (consent guard).
+- Remove it by deleting the `Stop` entry in `~/.claude/settings.json`.
+- `VIDELIC_API_URL` overrides the API endpoint (defaults to production).

package/hook.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// Managed by @videlic/connect — do not edit by hand.
+//
+// Runs as a Claude Code Stop hook (`node videlic-hook.mjs`). Reads the stop
+// event JSON on stdin, resolves the transcript, attaches git metadata, and
+// POSTs to Videlic's /v1/ingest. Cross-platform: pure Node, no bash/jq/curl.
+//
+// Resilient, like the original shell hook:
+//   • skips sessions that predate install (consent guard),
+//   • tail-truncates transcripts over 8 MB so edge gateways don't 413,
+//   • retries 5xx up to 3× with backoff; gives up on 4xx,
+//   • logs HTTP code + body to ~/.claude/videlic-hook.log on failure.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  existsSync,
+  readFileSync,
+  statSync,
+  openSync,
+  readSync,
+  closeSync,
+  appendFileSync,
+} from "node:fs";
+import { execFileSync } from "node:child_process";
+
+const claudeDir = join(homedir(), ".claude");
+const logPath = join(claudeDir, "videlic-hook.log");
+const log = (m) => {
+  try {
+    appendFileSync(logPath, `[${new Date().toISOString()}] videlic: ${m}\n`);
+  } catch {
+    /* logging is best-effort */
+  }
+};
+
+const MAX_BYTES = 8_000_000;
+
+function readConfig() {
+  const p = join(claudeDir, "videlic.json");
+  if (!existsSync(p)) return null;
+  try {
+    const cfg = JSON.parse(readFileSync(p, "utf8"));
+    return cfg?.key && cfg?.apiUrl ? cfg : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function readFirstLine(path) {
+  const fd = openSync(path, "r");
+  try {
+    const buf = Buffer.alloc(65536);
+    const n = readSync(fd, buf, 0, buf.length, 0);
+    const s = buf.toString("utf8", 0, n);
+    const nl = s.indexOf("\n");
+    return nl === -1 ? s : s.slice(0, nl);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function readTail(path, maxBytes) {
+  const size = statSync(path).size;
+  const start = Math.max(0, size - maxBytes);
+  const fd = openSync(path, "r");
+  try {
+    const buf = Buffer.alloc(size - start);
+    readSync(fd, buf, 0, buf.length, start);
+    let s = buf.toString("utf8");
+    // Drop the partial first line so the parser never sees half a JSON object.
+    if (start > 0) {
+      const nl = s.indexOf("\n");
+      if (nl !== -1) s = s.slice(nl + 1);
+    }
+    return s;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function gitMeta(cwd) {
+  const out = { branch: "", commitSha: "", repoUrl: "" };
+  if (!cwd) return out;
+  const git = (args) => {
+    try {
+      return execFileSync("git", ["-C", cwd, ...args], {
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+        .toString()
+        .trim();
+    } catch {
+      return "";
+    }
+  };
+  if (git(["rev-parse", "--is-inside-work-tree"]) === "true") {
+    out.branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+    out.commitSha = git(["rev-parse", "HEAD"]);
+    out.repoUrl = git(["config", "--get", "remote.origin.url"]);
+  }
+  return out;
+}
+
+async function main() {
+  const cfg = readConfig();
+  if (!cfg) process.exit(0); // not configured — nothing to do
+
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    log("skip: unparseable stop payload");
+    return;
+  }
+
+  const transcript = payload.transcript_path;
+  const sessionId = payload.session_id || "";
+  const cwd = payload.cwd || "";
+
+  if (!transcript || !existsSync(transcript)) {
+    log("skip: no transcript_path");
+    return;
+  }
+  const size = statSync(transcript).size;
+  if (size === 0) {
+    log("skip: empty transcript");
+    return;
+  }
+
+  // Consent guard: a chat that started before install was never opted in.
+  if (cfg.installedAt) {
+    try {
+      const ts = JSON.parse(readFirstLine(transcript))?.timestamp;
+      if (ts && new Date(ts).getTime() < new Date(cfg.installedAt).getTime()) {
+        log(`skip: pre-install session (${ts} < ${cfg.installedAt})`);
+        return;
+      }
+    } catch {
+      /* if we can't read the timestamp, fall through and send */
+    }
+  }
+
+  let sessionData;
+  let truncated = false;
+  if (size > MAX_BYTES) {
+    sessionData = readTail(transcript, MAX_BYTES);
+    truncated = true;
+    log(`truncate: ${size} -> ~${sessionData.length} bytes (tail)`);
+  } else {
+    sessionData = readFileSync(transcript, "utf8");
+  }
+
+  const { branch, commitSha, repoUrl } = gitMeta(cwd);
+
+  const body = { agent: "claude-code", sessionData };
+  if (sessionId) body.sessionFileId = sessionId;
+  if (branch) body.branch = branch;
+  if (commitSha) body.commitSha = commitSha;
+  if (repoUrl) body.repoUrl = repoUrl;
+  if (truncated) body.truncated = true;
+
+  const url = `${cfg.apiUrl.replace(/\/+$/, "")}/v1/ingest`;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    let status = 0;
+    let detail = "";
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${cfg.key}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(60_000),
+      });
+      status = res.status;
+      if (status >= 200 && status < 300) {
+        log(`ingest OK (${status})`);
+        return;
+      }
+      detail = (await res.text().catch(() => "")).slice(0, 300);
+    } catch (e) {
+      detail = String(e?.message ?? e);
+    }
+    if (status >= 400 && status < 500) {
+      log(`ingest failed ${status}: ${detail}`); // client error — don't retry
+      return;
+    }
+    log(`ingest attempt ${attempt} -> ${status || "error"} (${detail})`);
+    if (attempt < 3) await new Promise((r) => setTimeout(r, attempt * 2000));
+  }
+}
+
+main().catch((e) => {
+  log(`fatal: ${e?.message ?? e}`);
+  process.exit(0); // never break the user's session on our account
+});

package/install.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// @videlic/connect — connects your coding agent to Videlic.
+//
+// One cross-platform command (run via `npx @videlic/connect <key>`) that:
+//   1. confirms Claude Code is present (~/.claude),
+//   2. validates the key against the Videlic API,
+//   3. copies the Node Stop-hook into ~/.claude,
+//   4. writes ~/.claude/videlic.json (key + apiUrl + installedAt),
+//   5. registers the hook in ~/.claude/settings.json — idempotently, migrating
+//      off any older bash hook so it never double-fires,
+//   6. pings once so the install page flips to "All set".
+//
+// No bash, no jq, no curl | sh. Same behaviour on macOS, Windows, and Linux.
+
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  copyFileSync,
+  chmodSync,
+  unlinkSync,
+} from "node:fs";
+
+const API_URL = (process.env.VIDELIC_API_URL || "https://api.videlic.dev").replace(/\/+$/, "");
+const KEY = (process.argv[2] || process.env.VIDELIC_KEY || "").trim();
+
+const C = { reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m", green: "\x1b[32m", red: "\x1b[31m" };
+const ok = (m) => console.log(`${C.green}✓${C.reset} ${m}`);
+const fail = (m) => {
+  console.error(`${C.red}✗${C.reset} ${m}`);
+  process.exit(1);
+};
+
+console.log(`\n${C.bold}Videlic${C.reset}\n${C.dim}───────${C.reset}`);
+
+if (!KEY) fail("Missing key.\n  Usage: npx @videlic/connect ao_xxxxxxxx");
+if (!/^ao_[A-Za-z0-9]{8,}$/.test(KEY)) {
+  fail("That doesn't look like a Videlic key (expected ao_…).");
+}
+
+const claudeDir = join(homedir(), ".claude");
+if (!existsSync(claudeDir)) {
+  fail(
+    "~/.claude not found — install Claude Code first:\n" +
+      "  https://docs.anthropic.com/claude-code",
+  );
+}
+ok("Coding agent detected");
+
+// 1. Validate the key.
+try {
+  const res = await fetch(`${API_URL}/v1/ping`, {
+    headers: { Authorization: `Bearer ${KEY}` },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (res.status !== 200) {
+    fail(
+      `Key validation failed (HTTP ${res.status}).\n` +
+        "  It was likely rotated or deleted — grab a fresh one at https://videlic.dev/install",
+    );
+  }
+} catch (e) {
+  fail(`Couldn't reach Videlic (${e?.message ?? e}). Check your connection and retry.`);
+}
+ok("Key valid");
+
+// 2. Copy the Node hook + write config (the hook reads key/apiUrl/installedAt here).
+const here = dirname(fileURLToPath(import.meta.url));
+const hookDest = join(claudeDir, "videlic-hook.mjs");
+copyFileSync(join(here, "hook.mjs"), hookDest);
+
+const configPath = join(claudeDir, "videlic.json");
+writeFileSync(
+  configPath,
+  JSON.stringify({ key: KEY, apiUrl: API_URL, installedAt: new Date().toISOString() }, null, 2),
+);
+try {
+  chmodSync(configPath, 0o600);
+} catch {
+  /* best-effort (no-op on some Windows filesystems) */
+}
+ok("Hook installed");
+
+// 3. Register the Stop hook in settings.json — idempotent + migrates off any
+//    older entry (marked `videlic: true`, or any command mentioning videlic-hook,
+//    including the legacy videlic-hook.sh) so it never fires twice.
+const settingsPath = join(claudeDir, "settings.json");
+let settings = {};
+if (existsSync(settingsPath)) {
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8") || "{}");
+  } catch {
+    settings = {};
+  }
+}
+settings.hooks ??= {};
+const prevStop = Array.isArray(settings.hooks.Stop) ? settings.hooks.Stop : [];
+const command = `node "${hookDest}"`;
+const isVidelic = (entry) =>
+  entry?.videlic === true ||
+  (Array.isArray(entry?.hooks) &&
+    entry.hooks.some((h) => typeof h?.command === "string" && /videlic-hook/.test(h.command)));
+settings.hooks.Stop = [
+  ...prevStop.filter((e) => !isVidelic(e)),
+  { matcher: "", videlic: true, hooks: [{ type: "command", command }] },
+];
+writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+ok("Registered with your agent");
+
+// 4. Remove the legacy bash hook so it can't double-fire alongside the Node one.
+try {
+  const legacy = join(claudeDir, "videlic-hook.sh");
+  if (existsSync(legacy)) unlinkSync(legacy);
+} catch {
+  /* best-effort */
+}
+
+// 5. Final ping — stamps last-used so /install flips to "All set" right away.
+try {
+  await fetch(`${API_URL}/v1/ping`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${KEY}` },
+    signal: AbortSignal.timeout(10_000),
+  });
+} catch {
+  /* non-fatal */
+}
+
+console.log(
+  `\n${C.green}All set.${C.reset} Finish your next session and Videlic will post a review\n` +
+    "on the pull request that follows.\n",
+);

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@videlic/connect",
+  "version": "0.1.0",
+  "description": "Connect your coding agent to Videlic — installs a Stop hook that sends each finished session for review. Works on macOS, Windows, and Linux.",
+  "type": "module",
+  "bin": {
+    "connect": "./install.mjs"
+  },
+  "files": [
+    "install.mjs",
+    "hook.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://videlic.dev",
+  "publishConfig": {
+    "access": "public"
+  }
+}