octarin-cli 0.2.0

package/assets/repo-template/dot-cursor/hooks/lib/canonical.js

@@ -0,0 +1,240 @@
+/**
+ * canonical.js — map Cursor hook payloads to Octarin canonical IngestEvents.
+ *
+ * Cursor fires a separate process per hook event (beforeSubmitPrompt,
+ * afterAgentResponse, afterFileEdit, stop, ...), so each event becomes its own
+ * IngestEvent carrying one span. All events for a conversation share a
+ * deterministic trace_id (derived from `conversation_id`) so the backend rolls
+ * them into a single trace. Shape: backend/app/schema/canonical.py::IngestEvent.
+ */
+
+import { SOURCE, truncate, nowIso, userRef, deterministicTraceId } from "./utils.js";
+
+function repoFromRoots(roots) {
+  if (!Array.isArray(roots) || roots.length === 0) return null;
+  const r = String(roots[0]);
+  return r.split("/").filter(Boolean).pop() || null;
+}
+
+/** Wrap one span into a full IngestEvent for the given conversation. */
+function envelope(input, span, model) {
+  const conv = input.conversation_id || input.generation_id || "cursor-session";
+  return {
+    trace_id: deterministicTraceId(conv),
+    source: SOURCE,
+    session_id: input.conversation_id || null,
+    // Prefer the signed-in email Cursor puts on the event; else resolve a real
+    // identity (git / OS user) rather than an opaque machine hash.
+    user_ref: (input.user_email || "").trim() || userRef(),
+    repo: repoFromRoots(input.workspace_roots),
+    model: model || input.model || null,
+    spans: [span],
+    start_time: span.start_time,
+    end_time: span.end_time,
+  };
+}
+
+function baseSpan(spanId, name, spanType) {
+  const ts = nowIso();
+  return {
+    span_id: spanId,
+    parent_span_id: null,
+    name,
+    span_type: spanType,
+    start_time: ts,
+    end_time: ts,
+    status: "ok",
+    attributes: {},
+  };
+}
+
+function spanId(input, suffix) {
+  const conv = input.conversation_id || "conv";
+  const gen = input.generation_id || Date.now();
+  return `${conv}:${gen}:${suffix}`;
+}
+
+/**
+ * Cursor `afterAgentResponse` carries the model output.
+ *
+ * TOKEN USAGE: as of Cursor 1.7 NO hook event exposes per-turn token usage —
+ * the documented `afterAgentResponse` fields are only `text` (+ the shared
+ * envelope: conversation_id, generation_id, model, workspace_roots,
+ * transcript_path, ...). There is no `usage`, `input_tokens`, or `output_tokens`
+ * anywhere in the hook payload, so these spans legitimately carry 0 tokens (not
+ * a capture bug). The lookup below stays defensive against several possible
+ * field shapes so we transparently pick usage up IF a future Cursor version
+ * starts emitting it — but we never fabricate counts when it is absent.
+ * (`preCompact.context_tokens` is context-window utilisation, not billable
+ * usage, so we deliberately do not treat it as tokens.)
+ */
+function fromAfterAgentResponse(input) {
+  const span = baseSpan(spanId(input, "gen"), "Cursor agent response", "llm");
+  span.model = input.model || null;
+  span.input = truncate(input.prompt || "");
+  span.output = truncate(input.text || "");
+  const usage = input.usage || input.token_usage || input.tokens || {};
+  span.input_tokens = Number(usage.input_tokens || usage.prompt_tokens || 0) || 0;
+  span.output_tokens = Number(usage.output_tokens || usage.completion_tokens || 0) || 0;
+  span.cache_read_tokens =
+    Number(usage.cache_read_input_tokens || usage.cached_input_tokens || 0) || 0;
+  span.cache_write_tokens =
+    Number(usage.cache_creation_input_tokens || usage.cache_write_tokens || 0) || 0;
+  span.total_tokens =
+    Number(usage.total_tokens || 0) || span.input_tokens + span.output_tokens;
+  span.attributes = {
+    generation_id: input.generation_id,
+    hook: "afterAgentResponse",
+    // Flag when Cursor supplied no usage so the gap is visible downstream
+    // rather than looking like a silently-dropped count.
+    usage_available: Object.keys(usage).length > 0,
+  };
+  return envelope(input, span, input.model);
+}
+
+/** `beforeSubmitPrompt` records the user turn (no tokens yet). */
+function fromBeforeSubmitPrompt(input) {
+  const span = baseSpan(spanId(input, "prompt"), "Cursor user prompt", "agent");
+  span.input = truncate(input.prompt || "");
+  span.attributes = {
+    generation_id: input.generation_id,
+    attachment_count: (input.attachments || []).length,
+    hook: "beforeSubmitPrompt",
+  };
+  return envelope(input, span, input.model);
+}
+
+function asText(v) {
+  if (v == null) return "";
+  return typeof v === "string" ? v : JSON.stringify(v);
+}
+
+/**
+ * Tool span id keyed on Cursor's `tool_use_id` (unique per call) so multiple
+ * tools in ONE turn don't collide on the same id and get deduped to one (the
+ * old `afterFileEdit` keyed on conversation:generation, so 3 edits in a turn
+ * overwrote each other). Falls back to a per-call unique when absent.
+ */
+function toolSpanId(input) {
+  const conv = input.conversation_id || "conv";
+  return `${conv}:tool:${input.tool_use_id || input.generation_id || Date.now()}`;
+}
+
+/**
+ * `postToolUse` — the GENERIC post-tool hook; fires for EVERY tool (edit, shell,
+ * read, MCP, ...) with its result. Replaces the per-tool afterFileEdit /
+ * afterShellExecution / afterMCPExecution (which would double-count).
+ */
+function fromPostToolUse(input) {
+  const tool = input.tool_name || "tool";
+  const span = baseSpan(toolSpanId(input), tool, "tool");
+  span.input = truncate(asText(input.tool_input));
+  span.output = truncate(asText(input.tool_output));
+  span.attributes = {
+    tool_name: tool,
+    tool_use_id: input.tool_use_id,
+    duration_ms: input.duration,
+    hook: "postToolUse",
+  };
+  return envelope(input, span, input.model);
+}
+
+/** `postToolUseFailure` — a tool that errored; this is what powers a real
+ *  Cursor error rate (status=error, failure_type, is_interrupt). */
+function fromPostToolUseFailure(input) {
+  const tool = input.tool_name || "tool";
+  const span = baseSpan(toolSpanId(input), tool, "tool");
+  span.status = "error";
+  span.error_message = input.error_message || input.failure_type || "tool failed";
+  span.input = truncate(asText(input.tool_input));
+  span.attributes = {
+    tool_name: tool,
+    tool_use_id: input.tool_use_id,
+    failure_type: input.failure_type,
+    is_interrupt: input.is_interrupt,
+    duration_ms: input.duration,
+    hook: "postToolUseFailure",
+  };
+  return envelope(input, span, input.model);
+}
+
+/** `sessionStart` — explicit session boundary (identity rides the envelope). */
+function fromSessionStart(input) {
+  const span = baseSpan(spanId(input, "session-start"), "Cursor session start", "agent");
+  span.attributes = {
+    session_id: input.session_id,
+    is_background_agent: input.is_background_agent,
+    composer_mode: input.composer_mode,
+    hook: "sessionStart",
+  };
+  return envelope(input, span, input.model);
+}
+
+/** `sessionEnd` — richer close than `stop`: final status + reason + duration. */
+function fromSessionEnd(input) {
+  const span = baseSpan(spanId(input, "session-end"), "Cursor session end", "agent");
+  span.status = input.final_status === "error" ? "error" : "ok";
+  if (span.status === "error") span.error_message = input.error_message || "session error";
+  span.attributes = {
+    session_id: input.session_id,
+    reason: input.reason,
+    final_status: input.final_status,
+    duration_ms: input.duration_ms,
+    hook: "sessionEnd",
+  };
+  return envelope(input, span, input.model);
+}
+
+/**
+ * `preCompact` — context-window compaction signal. NOTE: `context_tokens` here
+ * is context UTILISATION, not billable usage, so it is deliberately NOT mapped
+ * to span tokens (no Cursor hook exposes real usage).
+ */
+function fromPreCompact(input) {
+  const span = baseSpan(
+    spanId(input, `compact-${input.message_count || 0}`),
+    "Context compaction",
+    "agent",
+  );
+  span.attributes = {
+    hook: "preCompact",
+    trigger: input.trigger,
+    context_usage_percent: input.context_usage_percent,
+    context_tokens: input.context_tokens,
+    context_window_size: input.context_window_size,
+    message_count: input.message_count,
+    messages_to_compact: input.messages_to_compact,
+    is_first_compaction: input.is_first_compaction,
+  };
+  return envelope(input, span, input.model);
+}
+
+/** `stop` records task completion + status. */
+function fromStop(input) {
+  const span = baseSpan(spanId(input, "stop"), "Cursor agent stopped", "agent");
+  span.status = input.status === "error" ? "error" : "ok";
+  if (input.status === "error") span.error_message = "agent error";
+  span.attributes = { status: input.status, loop_count: input.loop_count, hook: "stop" };
+  return envelope(input, span, input.model);
+}
+
+const BUILDERS = {
+  sessionStart: fromSessionStart,
+  beforeSubmitPrompt: fromBeforeSubmitPrompt,
+  afterAgentResponse: fromAfterAgentResponse,
+  postToolUse: fromPostToolUse,
+  postToolUseFailure: fromPostToolUseFailure,
+  preCompact: fromPreCompact,
+  stop: fromStop,
+  sessionEnd: fromSessionEnd,
+};
+
+/**
+ * Build an IngestEvent for a Cursor hook event, or null if this event carries
+ * nothing worth sending. `hookName` falls back to `input.hook_event_name`.
+ */
+export function buildEvent(hookName, input) {
+  const name = hookName || input.hook_event_name;
+  const builder = BUILDERS[name];
+  return builder ? builder(input) : null;
+}

package/assets/repo-template/dot-cursor/hooks/lib/utils.js

@@ -0,0 +1,196 @@
+/**
+ * utils.js — tiny stdlib helpers for the Cursor -> Octarin capture hook.
+ *
+ * Zero npm dependencies: stdin reading, a raw `https`/`http` POST with a hard
+ * timeout, a real-identity user_ref (git email / OS user), and a deterministic UUID5 (matching the
+ * backend's trace-id namespace). Everything here is fail-open friendly — the
+ * caller decides what to do on rejection.
+ */
+
+import fs from "node:fs";
+import https from "node:https";
+import http from "node:http";
+import crypto from "node:crypto";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+
+export const SOURCE = "cursor";
+export const MAX_TEXT = 20000;
+export const HTTP_TIMEOUT_MS = 5000;
+// Same namespace as backend deterministic_trace_id so retries de-duplicate.
+const TRACE_NAMESPACE = "6f8d2c1e-9a3b-4f5e-8c7d-1a2b3c4d5e6f";
+
+export function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", () => {
+      try {
+        resolve(data.trim() ? JSON.parse(data) : {});
+      } catch {
+        resolve({});
+      }
+    });
+    process.stdin.on("error", () => resolve({}));
+  });
+}
+
+export function truncate(text) {
+  if (typeof text !== "string") return text == null ? "" : String(text);
+  return text.length <= MAX_TEXT ? text : text.slice(0, MAX_TEXT);
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+/** The committing git identity, or "" if git isn't configured here. */
+function gitEmail() {
+  try {
+    return execFileSync("git", ["config", "user.email"], {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Resolve the engineer's real identity for attribution.
+ *
+ * Priority: an explicit OCTARIN_USER override → the git user.email → the OS
+ * username. We attribute to a real person (matching backfill.py + the per-user
+ * ingest key) rather than an opaque per-machine hash, so the dashboard shows who
+ * actually did the work. When a per-user key is present the server overrides
+ * this with the key owner anyway; a real identity here is what ANONYMOUS
+ * (slug-only) sends rely on. Cursor exposes no signed-in account email locally,
+ * so git is the best available signal (the backend prefers the event's
+ * user_email when Cursor supplies one).
+ */
+export function userRef() {
+  const env = (process.env.OCTARIN_USER || "").trim();
+  if (env) return env;
+  const email = gitEmail();
+  if (email) return email;
+  return os.userInfo().username || "unknown";
+}
+
+/** RFC-4122 v5 UUID from (namespace, name) — matches Python's uuid.uuid5. */
+export function uuid5(name) {
+  const ns = Buffer.from(TRACE_NAMESPACE.replace(/-/g, ""), "hex");
+  const hash = crypto.createHash("sha1").update(Buffer.concat([ns, Buffer.from(name, "utf8")])).digest();
+  const bytes = hash.subarray(0, 16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function deterministicTraceId(sourceTraceId) {
+  return uuid5(`${SOURCE}:${sourceTraceId}`);
+}
+
+/**
+ * Fire-and-forget POST of an IngestEvent. Resolves true on 2xx, false otherwise.
+ * Never throws — the hook must stay fail-open.
+ *
+ * Two auth modes (same as the Python hook):
+ *  - Bearer: ``OCTARIN_API_KEY`` set → ``Authorization: Bearer …``.
+ *  - Slug-only: only ``OCTARIN_PROJECT`` set → ``X-Octarin-Project: <slug>``
+ *    header + the slug embedded in the body. Server enforces the project's
+ *    ``allow_anonymous_ingest`` policy. On a ``auth_required`` 401 we print
+ *    the one-time ``login.sh`` hint via the same marker mechanism the
+ *    Python hook uses.
+ */
+export function postEvent(event) {
+  return new Promise((resolve) => {
+    let url = process.env.OCTARIN_INGEST_URL;
+    if (!url) {
+      const base = (process.env.OCTARIN_API_BASE || "").replace(/\/+$/, "");
+      if (!base) return resolve(false);
+      url = `${base}/v1/ingest`;
+    }
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return resolve(false);
+    }
+    const apiKey = process.env.OCTARIN_API_KEY || "";
+    const project = (process.env.OCTARIN_PROJECT || "").trim();
+
+    // Embed `project` in the body for slug-auth (the server reads it from
+    // EITHER the body or the X-Octarin-Project header). No-op when a Bearer
+    // is present.
+    const payload = { ...event };
+    if (project && payload.project == null) payload.project = project;
+
+    const body = Buffer.from(JSON.stringify(payload), "utf8");
+    const headers = { "Content-Type": "application/json", "Content-Length": body.length };
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+    else if (project) headers["X-Octarin-Project"] = project;
+
+    const lib = parsed.protocol === "http:" ? http : https;
+    const req = lib.request(
+      {
+        method: "POST",
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === "http:" ? 80 : 443),
+        path: parsed.pathname + parsed.search,
+        headers,
+        timeout: HTTP_TIMEOUT_MS,
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          const ok = res.statusCode >= 200 && res.statusCode < 300;
+          // Strict-auth signal from the server — print the bootstrap hint once.
+          if (!ok && res.statusCode === 401 && project && !apiKey) {
+            try {
+              const body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+              if (body && body.error && body.error.code === "auth_required") {
+                notifyAuthRequiredOnce(project);
+              }
+            } catch {
+              // ignore parse errors — hook stays fail-open
+            }
+          }
+          resolve(ok);
+        });
+      },
+    );
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Print the one-time stderr hint when the project requires per-user auth.
+ * Marker file at ~/.octarin/hint.<sha12> so we don't re-print on every event.
+ */
+function notifyAuthRequiredOnce(project) {
+  try {
+    const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
+    const dir = `${home}/.octarin`;
+    fs.mkdirSync(dir, { recursive: true });
+    const sha = crypto.createHash("sha256").update(project).digest("hex").slice(0, 12);
+    const marker = `${dir}/auth_hint.${sha}`;
+    if (fs.existsSync(marker)) return;
+    fs.writeFileSync(marker, "");
+  } catch {
+    // fall through — better to nag once-a-session than to spam
+  }
+  process.stderr.write(
+    `[octarin] project '${project}' now requires per-user auth. Run once to authorize:\n` +
+      "[octarin]   curl -fsSL https://octarin.ai/hooks/login.sh | bash\n",
+  );
+}

package/assets/repo-template/dot-cursor/hooks/run.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Wrapper that runs the Octarin Cursor capture hook (hook-handler.js).
+#
+# Mirrors the Claude/Codex wrappers so all three agents load config the same way:
+# source the committed team config (.octarin/project — carries OCTARIN_PROJECT +
+# OCTARIN_INGEST_URL) FIRST, then the per-user key from ~/.octarin/octarin.env
+# (written by `octarin login`), then exec node so Cursor's stdin payload passes
+# straight through. Plain `bash` (no login shell) keeps per-event latency low —
+# postToolUse fires on every tool call. Fails open: any problem exits 0 so Cursor
+# is never blocked.
+
+set +e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." 2>/dev/null && pwd)"
+
+# Committed team config — gives the ingest URL + project slug. Subdir path, so it
+# never matches the `*.env` rule in common .gitignore patterns.
+for envfile in "$PROJECT_ROOT/.octarin/project" "$PWD/.octarin/project"; do
+  if [ -n "$envfile" ] && [ -f "$envfile" ]; then
+    set -a
+    # shellcheck disable=SC1090
+    . "$envfile"
+    set +a
+    break
+  fi
+done
+
+# Per-user key from `octarin login` (only if the team config didn't already set one).
+if [ -z "${OCTARIN_API_KEY:-}" ] && [ -f "$HOME/.octarin/octarin.env" ]; then
+  set -a
+  # shellcheck disable=SC1090,SC1091
+  . "$HOME/.octarin/octarin.env"
+  set +a
+fi
+
+if command -v node >/dev/null 2>&1; then
+  exec node "$SCRIPT_DIR/hook-handler.js"
+fi
+
+exit 0

package/assets/repo-template/dot-cursor/hooks.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "command": "bash .cursor/hooks/run.sh" }],
+    "beforeSubmitPrompt": [{ "command": "bash .cursor/hooks/run.sh" }],
+    "afterAgentResponse": [{ "command": "bash .cursor/hooks/run.sh" }],
+    "postToolUse": [{ "command": "bash .cursor/hooks/run.sh" }],
+    "postToolUseFailure": [{ "command": "bash .cursor/hooks/run.sh" }],
+    "preCompact": [{ "command": "bash .cursor/hooks/run.sh" }],
+    "stop": [{ "command": "bash .cursor/hooks/run.sh" }],
+    "sessionEnd": [{ "command": "bash .cursor/hooks/run.sh" }]
+  }
+}

package/dist/args.js

@@ -0,0 +1,85 @@
+/**
+ * Tiny zero-dependency argv parser.
+ *
+ * Splits a raw argv tail into positional arguments and a flag map. Supports
+ * `--flag value`, `--flag=value`, and boolean `--flag` (no value), plus the
+ * universal `-h` / `--help`. Keeping this in-house avoids any runtime dependency
+ * (the package ships zero deps), which matters for `npx` cold-start time.
+ *
+ * Known value-taking flags are declared so `--json` (boolean) and
+ * `--limit 100` (value) are disambiguated without guessing.
+ */
+/** Flags that consume the following token as their value. */
+const VALUE_FLAGS = new Set([
+    "api-key",
+    "base-url",
+    "port",
+    "limit",
+    // init / init-repo / login
+    "key",
+    "url",
+    "tools",
+    "backfill",
+    "project",
+    "device-label",
+]);
+/** Boolean flags that never consume a value. */
+const BOOL_FLAGS = new Set(["json", "help"]);
+/** Map of short aliases to their long-flag names. */
+const ALIASES = { h: "help" };
+/** Parse an argv tail (after the node + script entries) into positionals+flags. */
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--") {
+            // Everything after `--` is positional.
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (token.startsWith("--")) {
+            const body = token.slice(2);
+            const eq = body.indexOf("=");
+            if (eq !== -1) {
+                flags[body.slice(0, eq)] = body.slice(eq + 1);
+                continue;
+            }
+            if (BOOL_FLAGS.has(body)) {
+                flags[body] = true;
+                continue;
+            }
+            if (VALUE_FLAGS.has(body)) {
+                const next = argv[i + 1];
+                if (next === undefined || next.startsWith("-")) {
+                    // Missing value — record empty so the command can error clearly.
+                    flags[body] = "";
+                }
+                else {
+                    flags[body] = next;
+                    i++;
+                }
+                continue;
+            }
+            // Unknown long flag: treat as boolean (the command validates).
+            flags[body] = true;
+            continue;
+        }
+        if (token.startsWith("-") && token.length > 1) {
+            const name = ALIASES[token.slice(1)] ?? token.slice(1);
+            flags[name] = true;
+            continue;
+        }
+        positionals.push(token);
+    }
+    return { positionals, flags };
+}
+/** Read a flag as a string, or undefined if absent/boolean. */
+export function flagStr(flags, name) {
+    const v = flags[name];
+    return typeof v === "string" ? v : undefined;
+}
+/** Read a flag as a boolean. */
+export function flagBool(flags, name) {
+    return flags[name] === true;
+}

package/dist/assets.js

@@ -0,0 +1,28 @@
+/**
+ * Locate the bundled capture-client assets shipped inside this package.
+ *
+ * `copy-assets.mjs` stages ../clients into ./assets at build time, and
+ * package.json's "files" ships that directory. At runtime the compiled entry
+ * lives at dist/index.js, so assets sit one level up, at <package>/assets.
+ * Resolving relative to import.meta.url (not cwd) keeps `npx octarin-cli` working
+ * regardless of where the user invoked it.
+ */
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Absolute path to the bundled assets directory. */
+export function assetsDir() {
+    const here = dirname(fileURLToPath(import.meta.url)); // <package>/dist
+    return resolve(here, "..", "assets");
+}
+/** Absolute path to a file/dir within the bundled assets. */
+export function assetPath(...parts) {
+    return resolve(assetsDir(), ...parts);
+}
+/** Throw a clear error if the assets weren't bundled (e.g. ran tsc without copy-assets). */
+export function assertAssets() {
+    const dir = assetsDir();
+    if (!existsSync(resolve(dir, "backfill.py"))) {
+        throw new Error(`Bundled assets missing at ${dir}. This is a packaging bug — please re-install octarin.`);
+    }
+}