cli.mjs

#!/usr/bin/env node
// Observer config-as-code CLI — apply/export an Observer config document
// through the public API. Zero runtime dependencies (Node built-in fetch + fs).
//
//   observer apply  -f observer.yaml [--dry-run] [--prune]
//   observer export [--all] [--format yaml] [-o observer.yaml]
//   observer --version | --help
//
// Env:
//   OBSERVER_API_URL   base URL (default https://use.observer)
//   OBSERVER_API_KEY   obs_pub_… key with write:config / read:config
//
// Exit codes: 0 ok · 1 validation failure / error · 2 usage error.

import { readFileSync, writeFileSync } from "node:fs";
import pkg from "./package.json" with { type: "json" };

export const VERSION = pkg.version;

// Canonical API host, matching the OpenAPI spec and the docs. The legacy
// https://api.use.observer host still serves the same API, so an
// OBSERVER_API_URL pinned to it keeps working.
export const DEFAULT_API_URL = "https://use.observer";

// Base URL for API calls: OBSERVER_API_URL when set (any host, including the
// legacy api. one), else the default. Trailing slashes are dropped so the
// `${base}/api/v1/...` join never doubles them.
export function resolveBaseUrl(envValue) {
  const v = envValue == null || envValue === "" ? DEFAULT_API_URL : envValue;
  return v.replace(/\/+$/, "");
}

// Pure arg parser. Never throws / exits — collects unrecognized tokens into
// `unknown` so main() can reject them. Flags that consume a value refuse to
// swallow a following flag (so `apply -f --dry-run` is a usage error, not a
// readFileSync('--dry-run') ENOENT). `-` is the explicit stdin marker.
export function parseArgs(argv) {
  const a = { cmd: argv[0], file: null, out: null, dryRun: false, prune: false, all: false, format: "json", unknown: [] };
  for (let i = 1; i < argv.length; i++) {
    const t = argv[i];
    if (t === "-f" || t === "--file" || t === "-o" || t === "--out" || t === "--format") {
      const v = argv[i + 1];
      if (v === undefined || (v.startsWith("-") && v !== "-")) {
        a.unknown.push(`${t} (missing value)`);
        continue;
      }
      i++;
      if (t === "-f" || t === "--file") a.file = v;
      else if (t === "-o" || t === "--out") a.out = v;
      else a.format = v;
    } else if (t === "--dry-run") a.dryRun = true;
    else if (t === "--prune") a.prune = true;
    else if (t === "--all") a.all = true;
    else if (t === "-" || !t.startsWith("-")) {
      if (!a.file) a.file = t;
      else a.unknown.push(t);
    } else a.unknown.push(t);
  }
  return a;
}

// A failed request (any non-2xx) as one readable block: the RFC 7807 title,
// status and detail, the per-item `errors` when there are any, and when to
// retry for a 429. Pure (testable). `res` is { status, statusText }.
export function formatProblem(res, json) {
  const status = res?.status ?? 0;
  const p = json && typeof json === "object" ? json : null;
  const title = p?.title ?? (res?.statusText || "request failed");
  const lines = [`Error ${status}: ${title}${p?.detail ? ` — ${p.detail}` : ""}`];
  if (Array.isArray(p?.errors)) for (const e of p.errors) lines.push(`  ✗ ${e.path}: ${e.message}`);
  if (status === 429) {
    const after = p?.retry_after ?? res?.retryAfter;
    if (after != null && after !== "") lines.push(`Rate limited: retry after ${after}s.`);
  }
  if (p?.upgrade?.url) lines.push(`Upgrade${p.upgrade.label ? ` to ${p.upgrade.label}` : ""}: ${p.upgrade.url}`);
  return lines.join("\n");
}

// The output for an apply response: the plan / result on success, the config
// validation errors on a 422 config_invalid, and the problem otherwise (a 403
// or 429 is not a validation failure and must not read as "Applied: 0").
export function formatApplyResponse(res, json) {
  if (res?.ok) return formatResult(json);
  if (res?.status === 422 && json?.title === "config_invalid") return formatResult(json);
  return formatProblem(res, json);
}

// Human-readable rendering of an apply response. Pure (testable).
export function formatResult(json) {
  if (!json) return "no response";
  // Non-fatal server warnings (e.g. an unmanaged top-level key like
  // `incidents`) are appended to both the error and the plan/apply output.
  const warnings = Array.isArray(json.warnings) && json.warnings.length
    ? `\nWarnings:\n${json.warnings.map((w) => `  ! ${w.path}: ${w.message}`).join("\n")}`
    : "";
  if (json.errors) {
    const lines = json.errors.map((e) => `  ✗ ${e.path}: ${e.message}`);
    return `Config invalid (${json.errors.length} error${json.errors.length === 1 ? "" : "s"}):\n${lines.join("\n")}${warnings}`;
  }
  const s = json.summary ?? {};
  // `referenced`: existing metrics the document names without defining them
  // (never created or changed), reported by servers that support references.
  const head = `${json.dry_run ? "Plan" : "Applied"}: ${s.created ?? 0} created, ${s.updated ?? 0} updated, ${s.unchanged ?? 0} unchanged${s.pruned ? `, ${s.pruned} pruned` : ""}${s.referenced ? `, ${s.referenced} existing referenced` : ""}`;
  const detail = [];
  for (const [bucket, items] of Object.entries(json.diff ?? {})) {
    for (const it of items) {
      if (it.action === "unchanged") continue;
      const sym = it.action === "create" ? "+" : it.action === "prune" ? "-" : "~";
      detail.push(`  ${sym} ${bucket.replace(/s$/, "")} ${it.key}`);
    }
  }
  return (detail.length ? `${head}\n${detail.join("\n")}` : head) + warnings;
}

const HELP = `observer ${VERSION} — Observer config-as-code CLI

Usage:
  observer apply  -f <file> [--dry-run] [--prune]            apply (or plan) a config document
  observer export [--all] [--format yaml|json] [-o <file>]   dump current config
  observer --version                                         print version
  observer --help                                            print this help

Environment:
  OBSERVER_API_URL   API base URL (default ${DEFAULT_API_URL})
  OBSERVER_API_KEY   obs_pub_… key with write:config / read:config

Exit codes: 0 ok · 1 validation/error · 2 usage error.`;

function env(name, fallback) {
  const v = process.env[name];
  return v == null || v === "" ? fallback : v;
}

// version/help are only honored as the LEADING token. Matching them anywhere
// in argv would let `observer apply -f prod.yaml --version` print the version
// and exit 0 WITHOUT applying — a silent no-op apply that reads as success.
const isVersionToken = (t) => t === "version" || t === "--version" || t === "-v";
const isHelpToken = (t) => t === "help" || t === "--help" || t === "-h";

export async function main(argv = process.argv.slice(2)) {
  const first = argv[0];
  if (isVersionToken(first)) {
    console.log(VERSION);
    process.exit(0);
  }
  if (argv.length === 0) {
    console.log(HELP);
    process.exit(2);
  }
  if (isHelpToken(first)) {
    console.log(HELP);
    process.exit(0);
  }

  const args = parseArgs(argv);
  if (args.unknown.length) {
    console.error(`unrecognized argument(s): ${args.unknown.join(", ")}\n`);
    console.error(HELP);
    process.exit(2);
  }

  const base = resolveBaseUrl(process.env.OBSERVER_API_URL);
  const key = env("OBSERVER_API_KEY");
  if (!key) {
    console.error("OBSERVER_API_KEY is not set");
    process.exit(2);
  }
  const authHeaders = { Authorization: `Bearer ${key}` };

  if (args.cmd === "apply") {
    const body = readFileSync(args.file && args.file !== "-" ? args.file : 0, "utf8"); // file, or stdin for none or "-"
    const qs = new URLSearchParams();
    if (args.dryRun) qs.set("dryRun", "true");
    if (args.prune) qs.set("prune", "true");
    const res = await fetch(`${base}/api/v1/config/apply?${qs}`, {
      method: "POST",
      headers: { ...authHeaders, "Content-Type": "text/yaml" },
      body,
    });
    const json = await res.json().catch(() => null);
    const out = formatApplyResponse({ ok: res.ok, status: res.status, statusText: res.statusText, retryAfter: res.headers.get("retry-after") }, json);
    // Plans and validation errors go to stdout as before; other failures
    // (auth, plan, rate limit, server) to stderr.
    if (res.ok || json?.title === "config_invalid") console.log(out);
    else console.error(out);
    process.exit(res.ok ? 0 : 1);
  }

  if (args.cmd === "export") {
    const qs = new URLSearchParams();
    if (args.all) qs.set("all", "true");
    qs.set("format", args.format === "yaml" ? "yaml" : "json");
    const res = await fetch(`${base}/api/v1/config/export?${qs}`, { headers: authHeaders });
    if (!res.ok) {
      const json = await res.json().catch(() => null);
      console.error(`export failed. ${formatProblem({ status: res.status, statusText: res.statusText, retryAfter: res.headers.get("retry-after") }, json)}`);
      process.exit(1);
    }
    const text = args.format === "yaml" ? await res.text() : JSON.stringify(await res.json(), null, 2);
    if (args.out) writeFileSync(args.out, text);
    else process.stdout.write(text.endsWith("\n") ? text : text + "\n");
    process.exit(0);
  }

  console.error(`unknown command: ${args.cmd}\n`);
  console.error(HELP);
  process.exit(2);
}

// Only run when invoked directly as `node cli.mjs` (so tests can import the pure
// helpers). The compiled binary + npx entry is bin.mjs, which calls main().
if (import.meta.url === `file://${process.argv[1]}`) main();