@terminus-ai/cli 0.0.1

package/bin/http.mjs

@@ -0,0 +1,500 @@
+/**
+ * The one HTTP client the CLI talks to Terminus through.
+ *
+ * - Where: one API base (`--api-base`, else TERMINUS_API_BASE, else the saved
+ *   login's, else production) and one token (TERMINUS_TOKEN, else the saved
+ *   login), resolved here and nowhere else.
+ * - What: every door is a template from bin/endpoints.mjs, so the CLI can only
+ *   call a door that table lists — and the table is checked against the
+ *   backend's route contract. The one exception is the app host's
+ *   passthrough in `terminus dev` (`openResponse`), which forwards an app's
+ *   own `/_terminus` requests by the app host's contract instead.
+ * - How: every request says `User-Agent: terminus-cli/<version>`; the request
+ *   has 30 s, plus time for what it uploads, to be answered, and the answer
+ *   may take as long as its bytes keep arriving; a failure keeps the
+ *   backend's `{error: {code, message, details}}` on the thrown CliError
+ *   (`status`, `apiCode`, `details`) and picks the exit code from it; and only
+ *   a request that is safe to repeat (GET, HEAD, or one carrying an
+ *   Idempotency-Key) is repeated after a transient failure, with backoff.
+ */
+
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { endpointPath } from "./endpoints.mjs";
+import { CliError, authError } from "./errors.mjs";
+
+export const DEFAULT_TERMINUS_API_BASE = "https://api.terminus.build";
+
+export const CLI_VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
+/** Every request names the client it came from; the backend records it on
+ * skill uses and in the sign-in audit. */
+export const USER_AGENT = `terminus-cli/${CLI_VERSION}`;
+
+/* ── Where the API is ───────────────────────────────────────────────────── */
+
+export function normalizeBase(value) {
+  return String(value).trim().replace(/\/+$/, "");
+}
+
+export function normalizeApiBase(value) {
+  const base = normalizeBase(value);
+  return base.endsWith("/v1") ? base : `${base}/v1`;
+}
+
+// Empty values from dotenv templates must not shadow durable credentials.
+export function presentValue(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+/** The API base a command talks to: `--api-base`, TERMINUS_API_BASE, the
+ * base the saved login was made against, or production. */
+export async function commandApiBase(flags = {}) {
+  const explicit = presentValue(flags.api_base) ?? presentValue(process.env.TERMINUS_API_BASE);
+  if (explicit) return normalizeApiBase(explicit);
+  const session = await readSession();
+  return normalizeApiBase(session?.api_base ?? DEFAULT_TERMINUS_API_BASE);
+}
+
+/* ── Who is asking ──────────────────────────────────────────────────────── */
+
+export function sessionPath() {
+  return path.join(os.homedir(), ".terminus", "session.json");
+}
+
+export async function readSession() {
+  try {
+    return JSON.parse(await readFile(sessionPath(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** A saved login is a browser device session, and it always carries its
+ * expiry. Files from older builds (an API key, or a token without an
+ * expiry) are not logins; `terminus login` replaces them. */
+export function sessionTokenIsUsable(session, now = Date.now()) {
+  const token = presentValue(session?.token);
+  if (!token || session.api_key) return false;
+  const expiresAt = Date.parse(session.expires_at ?? "");
+  return Number.isFinite(expiresAt) && expiresAt > now + 30_000;
+}
+
+/** The exit-3 error for a missing, expired, or pre-device login. */
+export function signInError(session) {
+  if (presentValue(session?.token) && session.expires_at && !session.api_key) {
+    return authError("Your login has expired. Run `terminus login` to sign in again.");
+  }
+  return authError("Not signed in. Run `terminus login` (or set TERMINUS_TOKEN for automation).");
+}
+
+/**
+ * The token a command signs its requests with: TERMINUS_TOKEN (a session
+ * token the environment supplies, for automation), else the saved login.
+ * `source` says which, and `session` is the saved login when it is that.
+ * Required and missing, it throws the exit-3 sign-in error; optional and
+ * missing, it answers null.
+ */
+export async function resolveToken({ required = true } = {}) {
+  const fromEnvironment = presentValue(process.env.TERMINUS_TOKEN);
+  if (fromEnvironment) return { token: fromEnvironment, source: "env", session: null };
+  const session = await readSession();
+  if (sessionTokenIsUsable(session)) return { token: session.token.trim(), source: "session", session };
+  if (required) throw signInError(session);
+  return null;
+}
+
+/* ── How long, and how often ────────────────────────────────────────────── */
+
+const REQUEST_TIMEOUT_MS = 30_000;
+const IDLE_TIMEOUT_MS = 30_000;
+/** The slowest connection a transfer is budgeted for. */
+const MIN_BYTES_PER_SECOND = 64 * 1024;
+const MAX_TRANSFER_TIMEOUT_MS = 30 * 60_000;
+const MAX_ATTEMPTS = 3;
+const RETRY_BASE_MS = 250;
+/** A server that asks for a longer pause than this gets it from the person. */
+const MAX_RETRY_AFTER_MS = 10_000;
+
+/** The time a transfer of `bytes` gets: 30 s, plus the bytes at 64 KiB/s. */
+export function transferTimeoutMs(bytes = 0) {
+  const extra = Math.ceil((Math.max(0, Number(bytes) || 0) / MIN_BYTES_PER_SECOND) * 1000);
+  return Math.min(REQUEST_TIMEOUT_MS + extra, MAX_TRANSFER_TIMEOUT_MS);
+}
+
+function backoffMs(attempt) {
+  const base = RETRY_BASE_MS * 2 ** (attempt - 1);
+  return Math.round(base * (0.8 + Math.random() * 0.4));
+}
+
+function retryAfterMs(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  const at = Date.parse(raw);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : null;
+}
+
+/* ── One request ────────────────────────────────────────────────────────── */
+
+const CANCELLED = Symbol("cancelled");
+const TIMED_OUT = Symbol("timed out");
+/** What makes a failure worth one more attempt, when the request is safe to
+ * repeat: `{ waitMs }` (null waits the usual backoff). */
+const TRANSIENT = Symbol("transient");
+
+/**
+ * Send one request to `url` and read its answer.
+ *
+ * `body` is a string or bytes — or a function that returns a fresh body for
+ * each attempt, for a stream. `bodyBytes` is what it carries and
+ * `expectedBytes` what the answer carries, when known: both only size the
+ * timeouts. `as` is how the answer is read: "json" (an empty answer is `{}`),
+ * "bytes", or "none". `idempotent: true` declares a request safe to repeat
+ * that is not a GET and carries no Idempotency-Key, like a content-addressed
+ * upload.
+ */
+export async function send(url, options = {}) {
+  const method = String(options.method ?? "GET").toUpperCase();
+  const headers = { "User-Agent": USER_AGENT, ...(options.headers ?? {}) };
+  const safeToRepeat = options.idempotent
+    ?? (method === "GET" || method === "HEAD"
+      || Object.keys(headers).some((name) => name.toLowerCase() === "idempotency-key"));
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await exchange(url, method, headers, options);
+    } catch (error) {
+      const transient = error?.[TRANSIENT];
+      if (!transient || !safeToRepeat || attempt >= MAX_ATTEMPTS) throw error;
+      await sleep(transient.waitMs ?? backoffMs(attempt));
+    }
+  }
+}
+
+async function exchange(url, method, headers, options) {
+  const label = options.label ?? "Terminus API";
+  const caller = options.signal;
+  if (caller?.aborted) throw new CliError(`${label} request was cancelled: ${url}`);
+  const controller = new AbortController();
+  const onCaller = () => controller.abort(CANCELLED);
+  caller?.addEventListener("abort", onCaller, { once: true });
+  const requestMs = options.timeoutMs ?? transferTimeoutMs(options.bodyBytes ?? 0);
+  let phase = "request";
+  let timer = setTimeout(() => controller.abort(TIMED_OUT), requestMs);
+  let whole = null;
+  const fail = (error) => {
+    if (controller.signal.reason === CANCELLED) {
+      return new CliError(`${label} request was cancelled: ${url}`);
+    }
+    if (controller.signal.reason === TIMED_OUT) {
+      return new CliError(
+        phase === "request"
+          ? `${label} request timed out after ${Math.round(requestMs / 1000)}s: ${url}`
+          : `${label} stopped answering ${url} partway (nothing arrived for ${IDLE_TIMEOUT_MS / 1000}s, or the answer overran its time)`,
+        { code: "unavailable" },
+      );
+    }
+    const detail = error?.cause?.code ?? error?.cause?.message ?? error?.message ?? String(error);
+    const failure = new CliError(`could not reach the ${label} (${url}): ${detail}`, { code: "unavailable" });
+    failure[TRANSIENT] = { waitMs: null };
+    return failure;
+  };
+  try {
+    let response;
+    try {
+      const body = typeof options.body === "function" ? options.body() : options.body;
+      response = await fetch(url, {
+        method,
+        headers,
+        body,
+        ...(options.duplex ? { duplex: options.duplex } : {}),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      throw fail(error);
+    }
+    clearTimeout(timer);
+    phase = "response";
+    // The answer may take as long as it keeps arriving; when its size is
+    // known, it also gets that size's transfer budget and no more.
+    const expected = Number(options.expectedBytes);
+    if (Number.isFinite(expected) && expected > 0) {
+      whole = setTimeout(() => controller.abort(TIMED_OUT), transferTimeoutMs(expected));
+    }
+    let bytes;
+    try {
+      bytes = await readAll(response, controller, () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => controller.abort(TIMED_OUT), IDLE_TIMEOUT_MS);
+      });
+    } catch (error) {
+      throw fail(error);
+    }
+    if (!response.ok) throw responseError(response.status, bytes, response.headers, label);
+    return readAs(bytes, options.as ?? "json", url, label);
+  } finally {
+    clearTimeout(timer);
+    if (whole) clearTimeout(whole);
+    caller?.removeEventListener("abort", onCaller);
+  }
+}
+
+async function readAll(response, controller, onChunk) {
+  if (!response.body) return Buffer.alloc(0);
+  const chunks = [];
+  let size = 0;
+  onChunk();
+  for await (const chunk of response.body) {
+    onChunk();
+    chunks.push(chunk);
+    size += chunk.byteLength;
+  }
+  return Buffer.concat(chunks, size);
+}
+
+function readAs(bytes, as, url, label) {
+  if (as === "bytes") return bytes;
+  if (as === "none") return undefined;
+  const text = bytes.toString("utf8");
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CliError(`the ${label} answered ${url} with something that is not JSON`);
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The CliError for a non-2xx answer, keeping what the backend said:
+ * `{error: {code, message, details?}}`. Anything else in the body (a proxy's
+ * page, say) is quoted, briefly, as the message.
+ *
+ * The exit code follows the answer: 401, `unauthorized`, or `session_ended`
+ * is "not signed in" (3); a 403 — `forbidden`, `grant_required`, a skill that
+ * is not open — is "not allowed" (77); 429 is rate limited (75); 502, 503,
+ * and 504 are Terminus being unavailable (69); anything else is an error (1).
+ */
+export function responseError(status, bytes, headers = new Headers(), label = "Terminus API") {
+  const text = Buffer.from(bytes ?? []).toString("utf8");
+  let parsed = null;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    parsed = null;
+  }
+  const envelope = isPlainObject(parsed?.error) ? parsed.error : null;
+  const apiCode = typeof envelope?.code === "string" && envelope.code ? envelope.code : undefined;
+  const details = envelope && Object.hasOwn(envelope, "details") ? envelope.details : undefined;
+  const said = typeof envelope?.message === "string" && envelope.message.trim()
+    ? envelope.message.trim()
+    : text.replace(/\s+/g, " ").trim().slice(0, 200) || `HTTP ${status}`;
+  const signedOut = status === 401 || apiCode === "unauthorized" || apiCode === "session_ended";
+  const code = signedOut
+    ? "auth"
+    : status === 403
+      ? "forbidden"
+      : status === 429
+        ? "rate_limited"
+        : status === 502 || status === 503 || status === 504
+          ? "unavailable"
+          : "error";
+  let message = `${label} returned ${status}${apiCode ? ` (${apiCode})` : ""}: ${said}`;
+  if (signedOut) {
+    message += " — your login may have expired or been revoked; run `terminus login`";
+  }
+  const wait = retryAfterMs(headers);
+  if (code === "rate_limited") {
+    message += wait ? ` (retry in ~${Math.max(1, Math.round(wait / 1000))}s)` : " (retry shortly)";
+  }
+  const error = new CliError(message, { code, status, apiCode, details });
+  if (code === "unavailable" && (wait === null || wait <= MAX_RETRY_AFTER_MS)) {
+    error[TRANSIENT] = { waitMs: wait };
+  }
+  return error;
+}
+
+/* ── An answer read as it arrives ───────────────────────────────────────── */
+
+/**
+ * Send one request and hand back its Response the moment its status and
+ * headers arrive, the body unread and the status unchecked: for an answer the
+ * caller reads as it comes — a turn's SSE frames (`Api#stream`), an icon passed
+ * on with its ETag (`Api#open`), or the app host's passthrough in `terminus
+ * dev` (bin/appdev-remote.mjs), which routes an app's own requests by the app
+ * host's contract, not bin/endpoints.mjs, and hands status, headers, and body
+ * to the page untouched.
+ *
+ * The request has `timeoutMs` (by default 30 s plus its upload) to be
+ * answered; `null` waits as long as the platform takes, whose own deadlines
+ * then answer. Reading the body is the caller's, and so is cancelling it
+ * (`signal`). Never repeated.
+ */
+export async function openResponse(url, options = {}) {
+  const method = String(options.method ?? "GET").toUpperCase();
+  const label = options.label ?? "Terminus API";
+  const caller = options.signal;
+  if (caller?.aborted) throw new CliError(`${label} request was cancelled: ${url}`);
+  const requestMs = options.timeoutMs === null
+    ? null
+    : options.timeoutMs ?? transferTimeoutMs(options.bodyBytes ?? 0);
+  const timeout = new AbortController();
+  const timer = requestMs === null ? null : setTimeout(() => timeout.abort(TIMED_OUT), requestMs);
+  try {
+    return await fetch(url, {
+      method,
+      headers: { "User-Agent": USER_AGENT, ...(options.headers ?? {}) },
+      body: options.body,
+      redirect: options.redirect ?? "follow",
+      signal: caller ? AbortSignal.any([caller, timeout.signal]) : timeout.signal,
+    });
+  } catch (error) {
+    if (caller?.aborted) throw new CliError(`${label} request was cancelled: ${url}`);
+    if (timeout.signal.aborted) {
+      throw new CliError(
+        `${label} request timed out after ${Math.round(requestMs / 1000)}s: ${url}`,
+        { code: "unavailable" },
+      );
+    }
+    const detail = error?.cause?.code ?? error?.cause?.message ?? error?.message ?? String(error);
+    throw new CliError(`could not reach the ${label} (${url}): ${detail}`, { code: "unavailable" });
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/* ── The client a command holds ─────────────────────────────────────────── */
+
+function queryString(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null) params.set(key, String(value));
+  }
+  const text = params.toString();
+  return text ? `?${text}` : "";
+}
+
+/**
+ * The Terminus API as one command sees it: a base, the token it signs with
+ * (none for anonymous reads), and the doors of bin/endpoints.mjs.
+ */
+export class Api {
+  #me = null;
+
+  constructor({ base = DEFAULT_TERMINUS_API_BASE, token = null, identity = null } = {}) {
+    this.base = normalizeApiBase(base);
+    this.token = token;
+    /** `{ source: "env" | "session", session }`, when a token was resolved. */
+    this.identity = identity;
+  }
+
+  authHeaders() {
+    return this.token ? { Authorization: `Bearer ${this.token}` } : {};
+  }
+
+  /** The account this client speaks for, read once. */
+  me() {
+    this.#me ??= this.json("GET /v1/auth/me");
+    return this.#me;
+  }
+
+  /** One door's method and absolute URL. */
+  url(template, { params, query } = {}) {
+    const { method, path: route } = endpointPath(template, params);
+    return { method, url: `${this.base.replace(/\/v1$/, "")}${route}${queryString(query)}` };
+  }
+
+  /** A door's method, URL, headers, and payload: `body` goes as JSON,
+   * `raw: { data, type }` as the bytes it is. */
+  #prepare(template, { params, query, body, raw, headers, idempotencyKey, accept }) {
+    const { method, url } = this.url(template, { params, query });
+    const payload = raw ? raw.data : body === undefined ? undefined : JSON.stringify(body);
+    return {
+      method,
+      url,
+      headers: {
+        ...(accept ? { Accept: accept } : {}),
+        ...(raw ? { "Content-Type": raw.type } : payload === undefined ? {} : { "Content-Type": "application/json" }),
+        ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+        ...this.authHeaders(),
+        ...(headers ?? {}),
+      },
+      body: payload,
+      bodyBytes: payload === undefined ? 0 : Buffer.byteLength(payload),
+    };
+  }
+
+  /**
+   * One request through a door. `body` is sent as JSON; `raw: { data, type }`
+   * sends bytes as they are. `idempotencyKey` rides the Idempotency-Key
+   * header, which also makes the request safe to repeat.
+   */
+  request(template, options = {}) {
+    const as = options.as ?? "json";
+    const prepared = this.#prepare(template, {
+      ...options,
+      accept: as === "json" ? "application/json" : "*/*",
+    });
+    return send(prepared.url, {
+      ...prepared,
+      timeoutMs: options.timeoutMs,
+      expectedBytes: options.expectedBytes,
+      signal: options.signal,
+      as,
+    });
+  }
+
+  json(template, options = {}) {
+    return this.request(template, { ...options, as: "json" });
+  }
+
+  bytes(template, options = {}) {
+    return this.request(template, { ...options, as: "bytes" });
+  }
+
+  /** One request through a door, answered the way `openResponse` answers:
+   * the Response as soon as it starts, its body unread and its status the
+   * caller's to judge (an icon's 304 is an answer, not a failure). */
+  open(template, options = {}) {
+    const prepared = this.#prepare(template, options);
+    return openResponse(prepared.url, {
+      ...prepared,
+      timeoutMs: options.timeoutMs,
+      signal: options.signal,
+    });
+  }
+
+  /** `open`, for a door whose answer is read as it arrives (a turn's SSE
+   * frames): a refusal throws the CliError `json` would, with what the
+   * backend said. */
+  async stream(template, options = {}) {
+    const response = await this.open(template, options);
+    if (response.ok) return response;
+    const bytes = Buffer.from(await response.arrayBuffer().catch(() => new ArrayBuffer(0)));
+    throw responseError(response.status, bytes, response.headers);
+  }
+}
+
+/**
+ * The client a command talks to Terminus with: its API base, and the token
+ * `auth` asks for — "required" (the default; exit 3 when nobody is signed
+ * in), "optional" (anonymous when nobody is), or "none".
+ */
+export async function connect(flags = {}, { auth = "required" } = {}) {
+  const base = await commandApiBase(flags);
+  const identity = auth === "none" ? null : await resolveToken({ required: auth === "required" });
+  return new Api({ base, token: identity?.token ?? null, identity });
+}

package/bin/lint-manifests/justbash-commands.json

@@ -0,0 +1,88 @@
+{
+  "source": "just-bash@3.2.0 getCommandNames() — the version terminus-backend's bashd pins",
+  "commands": [
+    "alias",
+    "awk",
+    "base64",
+    "basename",
+    "bash",
+    "cat",
+    "chmod",
+    "clear",
+    "column",
+    "comm",
+    "cp",
+    "cut",
+    "date",
+    "diff",
+    "dirname",
+    "du",
+    "echo",
+    "egrep",
+    "env",
+    "expand",
+    "expr",
+    "false",
+    "fgrep",
+    "file",
+    "find",
+    "fold",
+    "grep",
+    "gunzip",
+    "gzip",
+    "head",
+    "help",
+    "history",
+    "hostname",
+    "html-to-markdown",
+    "join",
+    "jq",
+    "ln",
+    "ls",
+    "md5sum",
+    "mkdir",
+    "mv",
+    "nl",
+    "od",
+    "paste",
+    "printenv",
+    "printf",
+    "pwd",
+    "readlink",
+    "rev",
+    "rg",
+    "rm",
+    "rmdir",
+    "sed",
+    "seq",
+    "sh",
+    "sha1sum",
+    "sha256sum",
+    "sleep",
+    "sort",
+    "split",
+    "sqlite3",
+    "stat",
+    "strings",
+    "tac",
+    "tail",
+    "tar",
+    "tee",
+    "time",
+    "timeout",
+    "touch",
+    "tr",
+    "tree",
+    "true",
+    "unalias",
+    "unexpand",
+    "uniq",
+    "wc",
+    "which",
+    "whoami",
+    "xan",
+    "xargs",
+    "yq",
+    "zcat"
+  ]
+}