octarin-cli 0.2.0

package/dist/login.js

@@ -0,0 +1,209 @@
+/**
+ * `octarin login` — device-code browser flow for per-user CLI auth.
+ *
+ * The repo (team) install committed `OCTARIN_PROJECT=<org/project>` in the
+ * project's `.octarin.env`. This command turns that public slug into a
+ * per-user, per-device ingest key without ever passing a shared secret around:
+ *
+ *   1. POST /v1/devices/start { project, device_label } → get a `device_code`
+ *      + verification URL.
+ *   2. Open the URL in the user's browser; they sign in (Supabase Google SSO)
+ *      and click "Authorize this machine."
+ *   3. Poll /v1/devices/{code}/poll every ~2s. First poll after approval
+ *      returns the minted plaintext (exactly once — see service.ts).
+ *   4. Write the plaintext to `~/.octarin/octarin.env` (chmod 600) so the
+ *      capture hooks pick it up.
+ *
+ * The CLI never reads or writes a shared team key; revocation is one DB row.
+ */
+import { promises as fs } from "node:fs";
+import { hostname, userInfo } from "node:os";
+import { spawn } from "node:child_process";
+import { CliError, resolveBaseUrl } from "./client.js";
+import { logErr } from "./output.js";
+import { flagStr } from "./args.js";
+import { findRepoProjectFile, mergeUserEnv, parseEnvFile } from "./envfile.js";
+/**
+ * Anonymous POST/GET helper for the device endpoints — login is what mints the
+ * key, so we have nothing to send in `Authorization`. Errors map the gateway's
+ * `{ error: { code, message } }` envelope to a friendly `CliError`.
+ */
+async function deviceFetch(baseUrl, path, init) {
+    const url = `${baseUrl}${path}`;
+    let resp;
+    try {
+        resp = await fetch(url, {
+            ...init,
+            headers: { "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;
+    if (text) {
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // non-JSON body falls through to status handling below
+        }
+    }
+    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;
+}
+// ──────────────────────────────── project resolution ─────────────────────────
+/**
+ * Resolve the project identifier ("org/project" or a UUID) the user wants to
+ * authorize for. Precedence: `--project` > `$OCTARIN_PROJECT` > the
+ * `.octarin/project` walked up from CWD.
+ */
+async function resolveProject(projectFlag) {
+    if (projectFlag)
+        return projectFlag;
+    const fromEnv = process.env.OCTARIN_PROJECT;
+    if (fromEnv)
+        return fromEnv;
+    const envPath = await findRepoProjectFile(process.cwd());
+    if (envPath) {
+        const parsed = parseEnvFile(await fs.readFile(envPath, "utf8"));
+        if (parsed.OCTARIN_PROJECT)
+            return parsed.OCTARIN_PROJECT;
+    }
+    throw new CliError("No project. Run inside a repo whose `.octarin/project` carries OCTARIN_PROJECT, " +
+        "or pass `--project <org/project>`.", 2);
+}
+// ──────────────────────────────── browser open ───────────────────────────────
+/**
+ * Open `url` in the user's default browser, best-effort. Detached + ignored
+ * stdio so we don't hang waiting on the browser process. Failures (no DISPLAY,
+ * SSH session, headless box) are logged but never throw — the user can still
+ * paste the URL manually.
+ */
+function openInBrowser(url) {
+    const platform = process.platform;
+    let cmd;
+    let args;
+    if (platform === "darwin") {
+        cmd = "open";
+        args = [url];
+    }
+    else if (platform === "win32") {
+        cmd = "cmd";
+        args = ["/c", "start", "", url];
+    }
+    else {
+        cmd = "xdg-open";
+        args = [url];
+    }
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => {
+            logErr(`(could not auto-open the browser; please open this URL manually: ${url})`);
+        });
+        child.unref();
+    }
+    catch {
+        logErr(`(could not auto-open the browser; please open this URL manually: ${url})`);
+    }
+}
+// ──────────────────────────────── command ────────────────────────────────────
+const LOGIN_HELP = `octarin login — device-code browser flow
+
+USAGE
+  octarin login [--project <slug>] [--device-label <name>]
+
+OPTIONS
+  --project <slug>      Project to authorize for ("org/project" or a UUID).
+                        Defaults to OCTARIN_PROJECT or the repo-root .octarin.env.
+  --device-label <s>    Human label shown on the Authorize page.
+                        Default: "<user>@<hostname>".
+  --base-url <url>      API base URL. Or set OCTARIN_BASE_URL.
+  --port <port>         Override the port (self-host parity).
+  -h, --help            Show this help.
+
+WHAT IT DOES
+  1. Asks the Octarin API for a device code.
+  2. Opens https://octarin.ai/devices/<code> in your browser.
+  3. You sign in, see what you're authorizing, and click "Authorize this machine".
+  4. The CLI receives a per-user ingest key and writes it to
+     ~/.octarin/octarin.env (mode 600). The Cursor/Claude/Codex capture hooks
+     pick it up on the next session.
+
+  Nothing is committed to git; the key is unique to you + this machine and can
+  be revoked from Octarin without affecting your teammates.
+`;
+/**
+ * `octarin login` — device-code handshake. Polls every 2s until the user
+ * approves (or the row times out), then writes the minted key to disk.
+ */
+export async function cmdLogin(positionals, flags) {
+    void positionals; // login takes no positionals
+    if (flags.help === true) {
+        logErr(LOGIN_HELP);
+        return;
+    }
+    const projectFlag = flagStr(flags, "project");
+    const labelFlag = flagStr(flags, "device-label");
+    const project = await resolveProject(projectFlag);
+    const deviceLabel = labelFlag || `${userInfo().username}@${hostname()}`.slice(0, 200);
+    const baseUrl = resolveBaseUrl({
+        baseUrl: flagStr(flags, "base-url"),
+        port: flagStr(flags, "port"),
+    });
+    // 1. /start
+    logErr(`> authorizing this machine for project: ${project}`);
+    const start = await deviceFetch(baseUrl, "/v1/devices/start", {
+        method: "POST",
+        body: JSON.stringify({ project, device_label: deviceLabel }),
+    });
+    logErr("");
+    logErr(`  Open this URL in your browser to authorize:`);
+    logErr(`    ${start.verification_url}`);
+    logErr("");
+    openInBrowser(start.verification_url);
+    // 2. /poll every 2s until terminal.
+    const deadline = Date.now() + start.expires_in * 1000;
+    let lastStatus = "pending";
+    let waitedDots = 0;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 2000));
+        const poll = await deviceFetch(baseUrl, `/v1/devices/${encodeURIComponent(start.device_code)}/poll`, { method: "POST" });
+        if (poll.status === "pending") {
+            // Light progress feedback so the user knows we're alive.
+            if (waitedDots % 5 === 0)
+                process.stderr.write(".");
+            waitedDots++;
+            lastStatus = poll.status;
+            continue;
+        }
+        if (poll.status === "approved" && poll.api_key) {
+            process.stderr.write("\n");
+            const projectSlug = poll.project?.public_slug || project;
+            const path = await mergeUserEnv({ OCTARIN_API_KEY: poll.api_key, OCTARIN_PROJECT: projectSlug }, "# Octarin per-user capture credentials. Written by `octarin login`.");
+            logErr(`✓ Authorized as ${poll.user_email}.`);
+            logErr(`  Wrote ${path} (mode 600, key ${poll.key_prefix}…).`);
+            logErr("  Cursor / Claude Code / Codex sessions in this repo now stream to Octarin.");
+            return;
+        }
+        // Anything else is terminal: denied, expired, or 'collected' (another
+        // poller already grabbed the key — shouldn't happen in single-CLI use).
+        process.stderr.write("\n");
+        lastStatus = poll.status;
+        break;
+    }
+    if (lastStatus === "denied") {
+        throw new CliError("Authorization was denied. Re-run `octarin login` when ready.", 1);
+    }
+    if (lastStatus === "collected") {
+        throw new CliError("Authorization was already collected by another CLI session. Re-run `octarin login`.", 1);
+    }
+    throw new CliError("Authorization timed out. Re-run `octarin login` and approve within ~10 minutes.", 1);
+}

package/dist/output.js

@@ -0,0 +1,56 @@
+/**
+ * Output helpers — strict stdout/stderr separation for agent-friendly piping.
+ *
+ * Contract (mirrors Laminar's `lmnr-cli`): *structured* output (the actual
+ * query result / schema, as JSON or a rendered table) goes to **stdout**;
+ * *everything else* — progress, hints, warnings, errors — goes to **stderr**.
+ * That way `octarin sql query "..." --json | jq` receives clean JSON on stdout
+ * with no log noise, and a non-zero exit code signals failure to the caller.
+ */
+/** Write a line to stderr (human/progress/diagnostic messages). */
+export function logErr(message) {
+    process.stderr.write(message + "\n");
+}
+/** Write structured output to stdout (the machine-readable result). */
+export function out(text) {
+    process.stdout.write(text + "\n");
+}
+/** Pretty-print a value as indented JSON to stdout. */
+export function outJson(value) {
+    out(JSON.stringify(value, null, 2));
+}
+/**
+ * Render rows as a monospace ASCII table to stdout.
+ *
+ * `columns` are the header names; `rows` are arrays aligned to them. Cells are
+ * stringified (null → "" , objects → compact JSON) and each column is padded to
+ * its widest cell. Designed for human reading in a terminal — use `--json` for
+ * anything a program will parse.
+ */
+export function outTable(columns, rows) {
+    if (columns.length === 0) {
+        out("(no columns)");
+        return;
+    }
+    const cells = rows.map((r) => r.map(formatCell));
+    const widths = columns.map((c, i) => Math.max(c.length, ...cells.map((row) => (row[i] ?? "").length), 0));
+    const sep = "+" + widths.map((w) => "-".repeat(w + 2)).join("+") + "+";
+    const renderRow = (vals) => "| " + vals.map((v, i) => v.padEnd(widths[i])).join(" | ") + " |";
+    out(sep);
+    out(renderRow(columns));
+    out(sep);
+    for (const row of cells) {
+        // Pad short rows so the table stays rectangular.
+        const padded = columns.map((_, i) => row[i] ?? "");
+        out(renderRow(padded));
+    }
+    out(sep);
+}
+/** Stringify a single cell value for the ASCII table. */
+function formatCell(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "octarin-cli",
+  "version": "0.2.0",
+  "description": "Octarin's per-user CLI: install AI-coding capture (`octarin init` / `init-repo`), authorize a machine (`octarin login`), and run scoped read-only SQL over your own data. Never holds database credentials.",
+  "keywords": [
+    "octarin",
+    "sql",
+    "cli",
+    "observability",
+    "llm",
+    "analytics",
+    "agent"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "octarin": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "copy-assets": "node scripts/copy-assets.mjs",
+    "build": "npm run copy-assets && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.11.0"
+  }
+}