octarin-cli 0.2.0

package/dist/client.js

@@ -0,0 +1,105 @@
+/**
+ * HTTP client for the Octarin SQL gateway.
+ *
+ * Resolves auth + base URL from flags/env, then calls `POST /v1/sql/query` and
+ * `GET /v1/sql/schema` with the API key as a Bearer token. The CLI holds ONLY
+ * the API key — never ClickHouse credentials; all scoping/safety is server-side.
+ *
+ * Errors map the gateway's JSON envelope (`{ "error": { code, message } }`) to a
+ * thrown `CliError` so the command layer can print a clean message to stderr and
+ * exit non-zero.
+ */
+/** A user-facing error carrying a process exit code. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}
+const DEFAULT_BASE_URL = "https://api.octarin.ai";
+/**
+ * Resolve the base URL from explicit flag, env, or the default.
+ *
+ * Precedence: `--base-url` > `OCTARIN_BASE_URL` > `https://api.octarin.ai`. A
+ * `--port` flag (self-host parity) rewrites the port of whichever base URL won,
+ * defaulting its host to `http://localhost` when no base URL was given.
+ */
+export function resolveBaseUrl(opts) {
+    let base = opts.baseUrl || process.env.OCTARIN_BASE_URL || DEFAULT_BASE_URL;
+    if (opts.port) {
+        // If only a port was provided (no explicit base), assume local self-host.
+        if (!opts.baseUrl && !process.env.OCTARIN_BASE_URL) {
+            base = `http://localhost:${opts.port}`;
+        }
+        else {
+            const u = new URL(base);
+            u.port = opts.port;
+            base = u.origin;
+        }
+    }
+    return base.replace(/\/+$/, "");
+}
+/**
+ * Resolve the API key from explicit flag or env, or throw a clear `CliError`.
+ *
+ * Precedence: `--api-key` > `OCTARIN_API_KEY`.
+ */
+export function resolveApiKey(apiKeyFlag) {
+    const key = apiKeyFlag || process.env.OCTARIN_API_KEY;
+    if (!key) {
+        throw new CliError("No API key. Set OCTARIN_API_KEY or pass --api-key <oct_...>.", 2);
+    }
+    return key;
+}
+/** Perform a request to the gateway and parse its JSON, mapping errors. */
+async function request(cfg, path, init) {
+    const url = `${cfg.baseUrl}${path}`;
+    let resp;
+    try {
+        resp = await fetch(url, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${cfg.apiKey}`,
+                "Content-Type": "application/json",
+                ...(init.headers || {}),
+            },
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new CliError(`Could not reach ${url}: ${detail}`, 1);
+    }
+    const text = await resp.text();
+    let body = undefined;
+    if (text) {
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // Non-JSON body (e.g. a proxy 502 page). Fall through to status handling.
+        }
+    }
+    if (!resp.ok) {
+        const envelope = body;
+        const msg = envelope?.error?.message || text || `HTTP ${resp.status}`;
+        const code = envelope?.error?.code;
+        throw new CliError(`Request failed (${resp.status}${code ? ` ${code}` : ""}): ${msg}`, 1);
+    }
+    return body;
+}
+/** POST a SELECT to `/v1/sql/query`. */
+export function runQuery(cfg, query, limit) {
+    const payload = { query };
+    if (limit !== undefined)
+        payload.limit = limit;
+    return request(cfg, "/v1/sql/query", {
+        method: "POST",
+        body: JSON.stringify(payload),
+    });
+}
+/** GET the queryable schema from `/v1/sql/schema`. */
+export function getSchema(cfg) {
+    return request(cfg, "/v1/sql/schema", { method: "GET" });
+}

package/dist/envfile.js

@@ -0,0 +1,94 @@
+/**
+ * Shared helpers for the per-user credentials file at `~/.octarin/octarin.env`.
+ *
+ * Both `octarin init` (writes the ingest key from the dashboard) and
+ * `octarin login` (writes a device-code key) land here, and each capture hook
+ * sources it when `OCTARIN_API_KEY` isn't already in the environment. Keeping
+ * the parser + writer in one place means the two commands can't drift on
+ * format, mode bits, or merge behaviour.
+ */
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve as resolvePath } from "node:path";
+/** Absolute path to the per-user credentials file. */
+export function userEnvPath() {
+    return resolvePath(homedir(), ".octarin", "octarin.env");
+}
+/**
+ * Parse a `.env`-style file ("KEY=value" lines, '#' comments) into a record.
+ * Doesn't handle quoting / multi-line values — the files we read here only ever
+ * carry plain KEY=value (written by us or by `repo-install`'s descendants).
+ */
+export function parseEnvFile(text) {
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq < 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        const val = line.slice(eq + 1).trim();
+        if (key)
+            out[key] = val;
+    }
+    return out;
+}
+/**
+ * Merge the given KEY=value pairs into `~/.octarin/octarin.env` (mode 600),
+ * preserving any keys already present. Returns the path written.
+ *
+ * Merging (rather than clobbering) matters because `init` and `login` write
+ * overlapping-but-not-identical sets — e.g. `init` sets OCTARIN_INGEST_URL +
+ * OCTARIN_API_KEY, `login` sets OCTARIN_API_KEY + OCTARIN_PROJECT. Re-running
+ * either must not drop the other's keys.
+ */
+export async function mergeUserEnv(updates, header = "# Octarin capture credentials. Do not commit.") {
+    const path = userEnvPath();
+    await fs.mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    let existing = {};
+    try {
+        existing = parseEnvFile(await fs.readFile(path, "utf8"));
+    }
+    catch {
+        // first run — no prior file
+    }
+    const merged = { ...existing, ...updates };
+    const lines = [
+        header,
+        ...Object.entries(merged).map(([k, v]) => `${k}=${v}`),
+        "",
+    ];
+    await fs.writeFile(path, lines.join("\n"), { mode: 0o600 });
+    // writeFile honours `mode` only on create; chmod explicitly so a pre-existing
+    // file is also locked down.
+    await fs.chmod(path, 0o600);
+    return path;
+}
+/**
+ * Walk up from `start` looking for `.octarin/project` (the file committed by the
+ * team install — a subdir path, never matched by the *.env rule in common
+ * .gitignore patterns). Stops at the filesystem root or at `$HOME`. Returns
+ * `null` if none is found.
+ */
+export async function findRepoProjectFile(start) {
+    const home = homedir();
+    let dir = start;
+    while (true) {
+        const candidate = resolvePath(dir, ".octarin/project");
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch {
+            // fall through
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null; // hit the root
+        if (parent === home)
+            return null; // don't escape past the user's home
+        dir = parent;
+    }
+}

package/dist/index.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * `octarin` — a thin, agent-friendly CLI over the Octarin SQL gateway.
+ *
+ * Two commands today, mirroring `lmnr-cli`'s stable noun-verb surface:
+ *   octarin sql query "<SELECT ...>" [--json] [--limit N]
+ *   octarin sql schema [--json]
+ *
+ * Auth: `OCTARIN_API_KEY` env var or `--api-key`. Base URL: `https://api.octarin.ai`
+ * by default, overridable with `--base-url` / `OCTARIN_BASE_URL` (and `--port`
+ * for self-host parity). The CLI holds only the API key — never DB credentials;
+ * the server enforces read-only access, the table allowlist, and tenant scoping.
+ *
+ * I/O contract (so `--json | jq` pipes cleanly): structured results on stdout,
+ * all human/progress/error messages on stderr, non-zero exit on failure.
+ */
+import { flagBool, flagStr, parseArgs } from "./args.js";
+import { CliError, getSchema, resolveApiKey, resolveBaseUrl, runQuery, } from "./client.js";
+import { cmdLogin } from "./login.js";
+import { cmdInit } from "./init.js";
+import { cmdInitRepo } from "./init_repo.js";
+import { logErr, outJson, outTable } from "./output.js";
+const VERSION = "0.2.0";
+const ROOT_HELP = `octarin — per-user CLI for Octarin AI-usage analytics
+
+USAGE
+  octarin <command> [subcommand] [args] [options]
+
+COMMANDS
+  init <oct_key>             Install AI-coding capture on THIS machine (personal).
+                             Sets up Claude Code / Cursor / Codex hooks and
+                             streams your sessions to your Octarin workspace.
+  init-repo <org/project>    Commit shared capture config to a repo (team), so
+                             every teammate streams on clone. Opens a PR.
+  login                      Authorize this machine via a browser sign-in.
+                             Writes ~/.octarin/octarin.env so capture hooks
+                             pick up your per-user ingest key.
+  sql query "<SELECT ...>"   Run a read-only SELECT against your octarin.* tables
+  sql schema                 List the queryable tables and their columns
+
+GLOBAL OPTIONS
+  --api-key <key>     Octarin API key (oct_...). Or set OCTARIN_API_KEY.
+                      (Not used by \`octarin login\` — that's how you GET a key.)
+  --base-url <url>    API base URL. Or set OCTARIN_BASE_URL.
+                      Default: https://api.octarin.ai
+  --port <port>       Override the port (self-host parity).
+  --json              Emit machine-readable JSON on stdout (pipe to jq).
+  -h, --help          Show help.
+  --version           Show the CLI version.
+
+EXAMPLES
+  octarin init oct_xxx                              # personal capture install
+  octarin init-repo nace/default                    # team install (opens a PR)
+  octarin login                                     # per-user auth (team installs)
+  octarin sql schema
+  octarin sql query "SELECT model, count() FROM spans GROUP BY model"
+`;
+const SQL_HELP = `octarin sql — query your own Octarin data (read-only)
+
+USAGE
+  octarin sql query "<SELECT ...>" [--json] [--limit N]
+  octarin sql schema [--json]
+
+OPTIONS
+  --limit N           Max rows to return (server caps at 10000).
+  --json              Emit JSON on stdout instead of a table.
+  --api-key <key>     Octarin API key (oct_...). Or set OCTARIN_API_KEY.
+  --base-url <url>    API base URL. Or set OCTARIN_BASE_URL.
+  --port <port>       Override the port (self-host parity).
+  -h, --help          Show this help.
+
+NOTES
+  Only a single read-only SELECT over your octarin.* tables is allowed
+  (spans, traces, session_insights, span_vectors, events). The server enforces
+  the table allowlist and scopes every result to your organization's projects.
+`;
+/** Build the client config (auth + base URL) from parsed flags. */
+function buildConfig(flags) {
+    const apiKey = resolveApiKey(flagStr(flags, "api-key"));
+    const baseUrl = resolveBaseUrl({
+        baseUrl: flagStr(flags, "base-url"),
+        port: flagStr(flags, "port"),
+    });
+    return { apiKey, baseUrl };
+}
+/** `octarin sql query "<SELECT>"` */
+async function cmdSqlQuery(positionals, flags) {
+    const query = positionals[0];
+    if (!query) {
+        throw new CliError('Missing query. Usage: octarin sql query "<SELECT ...>"', 2);
+    }
+    let limit;
+    const limitStr = flagStr(flags, "limit");
+    if (limitStr !== undefined) {
+        const n = Number(limitStr);
+        if (!Number.isInteger(n) || n < 1) {
+            throw new CliError(`--limit must be a positive integer, got "${limitStr}".`, 2);
+        }
+        limit = n;
+    }
+    const cfg = buildConfig(flags);
+    logErr(`> querying ${cfg.baseUrl} ...`);
+    const result = await runQuery(cfg, query, limit);
+    if (flagBool(flags, "json")) {
+        outJson(result);
+    }
+    else {
+        outTable(result.columns, result.rows);
+        logErr(`(${result.row_count} row${result.row_count === 1 ? "" : "s"})`);
+    }
+}
+/** `octarin sql schema` */
+async function cmdSqlSchema(flags) {
+    const cfg = buildConfig(flags);
+    logErr(`> fetching schema from ${cfg.baseUrl} ...`);
+    const schema = await getSchema(cfg);
+    if (flagBool(flags, "json")) {
+        outJson(schema);
+        return;
+    }
+    // Human-readable: one block per table.
+    for (const table of schema.tables) {
+        outTable(["column", "type"], table.columns.map((c) => [c.name, c.type]));
+        logErr(`  ${table.qualified_name} — ${table.columns.length} columns\n`);
+    }
+}
+/** Dispatch the `sql` command group. */
+async function cmdSql(positionals, flags) {
+    const sub = positionals[0];
+    const rest = positionals.slice(1);
+    if (flagBool(flags, "help") || !sub) {
+        logErr(SQL_HELP);
+        if (!sub)
+            throw new CliError("Missing subcommand (query | schema).", 2);
+        return;
+    }
+    switch (sub) {
+        case "query":
+            return cmdSqlQuery(rest, flags);
+        case "schema":
+            return cmdSqlSchema(flags);
+        default:
+            logErr(SQL_HELP);
+            throw new CliError(`Unknown sql subcommand: ${sub}`, 2);
+    }
+}
+/** Entry point: parse argv, route to a command, map errors to exit codes. */
+async function main() {
+    const { positionals, flags } = parseArgs(process.argv.slice(2));
+    if (flags.version === true) {
+        // Version is structured-ish output; print to stdout.
+        process.stdout.write(VERSION + "\n");
+        return;
+    }
+    const command = positionals[0];
+    const rest = positionals.slice(1);
+    if (!command || (flagBool(flags, "help") && !command)) {
+        logErr(ROOT_HELP);
+        if (!command)
+            process.exit(2);
+        return;
+    }
+    switch (command) {
+        case "init":
+            await cmdInit(rest, flags);
+            break;
+        case "init-repo":
+            await cmdInitRepo(rest, flags);
+            break;
+        case "login":
+            await cmdLogin(rest, flags);
+            break;
+        case "sql":
+            await cmdSql(rest, flags);
+            break;
+        case "help":
+            logErr(ROOT_HELP);
+            break;
+        default:
+            logErr(ROOT_HELP);
+            throw new CliError(`Unknown command: ${command}`, 2);
+    }
+}
+main().catch((err) => {
+    if (err instanceof CliError) {
+        logErr(`error: ${err.message}`);
+        process.exit(err.exitCode);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    logErr(`error: ${message}`);
+    process.exit(1);
+});