@clankid/cli 0.17.0

package/src/lib/http.ts

@@ -0,0 +1,138 @@
+import { CliError } from "./errors";
+
+export interface RequestOptions {
+  method?: string;
+  token?: string;
+  body?: unknown;
+  rawBody?: string;
+  headers?: Record<string, string>;
+  accept?: string;
+  contentType?: string;
+}
+
+export interface HttpResponse<T = unknown> {
+  status: number;
+  data: T;
+}
+
+export async function requestJson<T = unknown>(
+  baseUrl: string,
+  path: string,
+  options: RequestOptions = {}
+): Promise<HttpResponse<T>> {
+  const url = new URL(path, ensureTrailingSlash(baseUrl));
+  const headers = new Headers(options.headers);
+  headers.set("accept", options.accept ?? "application/json");
+
+  let body: string | undefined;
+
+  if (options.body !== undefined && options.rawBody !== undefined) {
+    throw new CliError("Request body cannot set both structured and raw payloads.");
+  }
+
+  if (options.rawBody !== undefined) {
+    headers.set("content-type", options.contentType ?? "application/json");
+    body = options.rawBody;
+  } else if (options.body !== undefined) {
+    headers.set("content-type", options.contentType ?? "application/json");
+    body = JSON.stringify(options.body);
+  }
+
+  if (options.token) {
+    headers.set("authorization", `Bearer ${options.token}`);
+  }
+
+  const response = await fetch(url, {
+    method: options.method ?? "GET",
+    headers,
+    body
+  });
+
+  const rawPayload = await response.text();
+
+  if (!response.ok) {
+    throw toCliError(response.status, parsePayload(response, rawPayload, "lenient"));
+  }
+
+  const payload = parsePayload(response, rawPayload, "strict");
+
+  return {
+    status: response.status,
+    data: payload as T
+  };
+}
+
+export async function requestJsonApi<T = unknown>(
+  baseUrl: string,
+  path: string,
+  options: RequestOptions = {}
+): Promise<HttpResponse<T>> {
+  return requestJson<T>(baseUrl, path, {
+    ...options,
+    accept: options.accept ?? "application/vnd.api+json",
+    contentType: options.contentType ?? "application/vnd.api+json"
+  });
+}
+
+function toCliError(status: number, payload: unknown): CliError {
+  const message = extractErrorMessage(payload) ?? `Request failed with status ${status}`;
+  return new CliError(message, 1);
+}
+
+function parsePayload(
+  response: Response,
+  rawPayload: string,
+  mode: "lenient" | "strict"
+): unknown {
+  const contentType = response.headers.get("content-type") ?? "";
+  const isJson = contentType.includes("json");
+
+  if (!isJson || rawPayload.length === 0) {
+    return rawPayload;
+  }
+
+  try {
+    return JSON.parse(rawPayload);
+  } catch (error) {
+    if (mode === "lenient") {
+      return rawPayload;
+    }
+
+    throw new CliError(
+      `Received invalid JSON from server: ${(error as Error).message}`
+    );
+  }
+}
+
+function extractErrorMessage(payload: unknown): string | undefined {
+  if (!payload) {
+    return undefined;
+  }
+
+  if (typeof payload === "string") {
+    return payload;
+  }
+
+  if (typeof payload !== "object") {
+    return undefined;
+  }
+
+  const record = payload as Record<string, unknown>;
+  const errors = record.errors;
+
+  if (Array.isArray(errors) && errors.length > 0 && typeof errors[0] === "object" && errors[0] !== null) {
+    const first = errors[0] as Record<string, unknown>;
+    const title = typeof first.title === "string" ? first.title : undefined;
+    const detail = typeof first.detail === "string" ? first.detail : undefined;
+    const code = typeof first.code === "string" ? first.code : undefined;
+
+    return [title, detail, code ? `code=${code}` : undefined].filter(Boolean).join(": ");
+  }
+
+  const message = typeof record.message === "string" ? record.message : undefined;
+  return message;
+}
+
+function ensureTrailingSlash(baseUrl: string): string {
+  return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+}

package/src/lib/human.ts

@@ -0,0 +1,143 @@
+export type FieldValue = string | number | boolean | null | undefined;
+
+export function formatEmpty(value: FieldValue): string {
+  if (value === null || value === undefined || value === "") {
+    return "-";
+  }
+
+  return String(value);
+}
+
+export function formatTimestamp(value?: string | null): string {
+  if (!value) {
+    return "-";
+  }
+
+  const timestamp = Date.parse(value);
+
+  if (Number.isNaN(timestamp)) {
+    return value;
+  }
+
+  return formatLocalTimestamp(new Date(timestamp));
+}
+
+export function shortId(id?: string | null): string {
+  if (!id) {
+    return "-";
+  }
+
+  return id.length > 12 ? `${id.slice(0, 8)}...` : id;
+}
+
+export function renderFields(fields: Array<[label: string, value: FieldValue]>): string {
+  const visibleFields = fields.filter(([, value]) => value !== undefined);
+
+  if (visibleFields.length === 0) {
+    return "";
+  }
+
+  const labelWidth = Math.max(...visibleFields.map(([label]) => label.length));
+
+  return visibleFields
+    .map(([label, value]) => `${label.padEnd(labelWidth)}  ${formatEmpty(value)}`)
+    .join("\n");
+}
+
+export function renderSection(title: string, body: string): string {
+  const trimmed = body.trimEnd();
+
+  if (!trimmed) {
+    return "";
+  }
+
+  return `${title}\n${trimmed}`;
+}
+
+export function renderBullets(items: string[]): string {
+  if (items.length === 0) {
+    return "-";
+  }
+
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+export function indent(text: string, spaces = 2): string {
+  const prefix = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => (line ? `${prefix}${line}` : ""))
+    .join("\n");
+}
+
+export function renderBodyBlock(body: string): string {
+  const normalized = body.replace(/\r\n/g, "\n").trimEnd();
+
+  if (!normalized) {
+    return indent("(empty)");
+  }
+
+  return indent(normalized);
+}
+
+export function renderPagination(
+  nextCursor?: string | null,
+  nextCommand?: string,
+): string {
+  if (!nextCursor) {
+    return "";
+  }
+
+  return nextCommand
+    ? `More results: ${nextCommand}`
+    : `More results: --cursor ${nextCursor}`;
+}
+
+export function joinBlocks(blocks: Array<string | undefined | null | false>): string {
+  return blocks.filter(Boolean).join("\n\n");
+}
+
+export function renderTokenAction(input: {
+  title: string;
+  id?: string | null;
+  name?: string | null;
+  token?: string | null;
+  issuedAt?: string | null;
+  expiresAt?: string | null;
+}): string {
+  return joinBlocks([
+    input.title,
+    renderFields([
+      ["ID", input.id],
+      ["Name", input.name],
+      ["Token", input.token],
+      ["Issued", input.issuedAt ? formatTimestamp(input.issuedAt) : undefined],
+      ["Expires", input.expiresAt ? formatTimestamp(input.expiresAt) : undefined],
+    ]),
+  ]);
+}
+
+function formatLocalTimestamp(value: Date): string {
+  const year = value.getFullYear();
+  const month = padDatePart(value.getMonth() + 1);
+  const day = padDatePart(value.getDate());
+  const hours = padDatePart(value.getHours());
+  const minutes = padDatePart(value.getMinutes());
+  const seconds = padDatePart(value.getSeconds());
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} ${formatTimezoneOffset(value)}`;
+}
+
+function formatTimezoneOffset(value: Date): string {
+  const offsetMinutes = -value.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const absoluteMinutes = Math.abs(offsetMinutes);
+  const hours = padDatePart(Math.floor(absoluteMinutes / 60));
+  const minutes = padDatePart(absoluteMinutes % 60);
+
+  return `${sign}${hours}:${minutes}`;
+}
+
+function padDatePart(value: number): string {
+  return String(value).padStart(2, "0");
+}

package/src/lib/json-input.ts

@@ -0,0 +1,73 @@
+import { readFile } from "node:fs/promises";
+
+import { booleanFlag, stringFlag, type ParsedArgs } from "./args";
+import { CliError } from "./errors";
+import { readStdin } from "./body-input";
+
+export interface ResolveJsonInputOptions {
+  flags: ParsedArgs["flags"];
+  inlineKey: string;
+  fileKey: string;
+  stdinKey: string;
+  label: string;
+  requireObject?: boolean;
+  readFileText?: (path: string) => Promise<string>;
+  readStdinText?: () => Promise<string>;
+}
+
+export async function resolveJsonInput({
+  flags,
+  inlineKey,
+  fileKey,
+  stdinKey,
+  label,
+  requireObject = true,
+  readFileText = (path) => readFile(path, "utf8"),
+  readStdinText = () => readStdin(),
+}: ResolveJsonInputOptions): Promise<Record<string, unknown> | undefined> {
+  const inlineJson = stringFlag(flags, inlineKey);
+  const jsonFile = stringFlag(flags, fileKey);
+  const useStdin = booleanFlag(flags, stdinKey);
+  const providedCount = [
+    inlineJson !== undefined,
+    jsonFile !== undefined,
+    useStdin,
+  ].filter(Boolean).length;
+
+  if (providedCount === 0) {
+    return undefined;
+  }
+
+  if (providedCount > 1) {
+    throw new CliError(
+      `Use only one of \`--${kebab(inlineKey)}\`, \`--${kebab(fileKey)}\`, or \`--${kebab(stdinKey)}\``,
+      2,
+    );
+  }
+
+  const source =
+    inlineJson ?? (jsonFile !== undefined ? await readFileText(jsonFile) : await readStdinText());
+
+  try {
+    const value = JSON.parse(source);
+
+    if (
+      requireObject &&
+      (!value || typeof value !== "object" || Array.isArray(value))
+    ) {
+      throw new CliError(`${label} must be a JSON object`, 2);
+    }
+
+    return value as Record<string, unknown>;
+  } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
+
+    throw new CliError(`${label} must be valid JSON`, 2);
+  }
+}
+
+function kebab(value: string): string {
+  return value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}

package/src/lib/json_api.ts

@@ -0,0 +1,120 @@
+import { CliError } from "./errors";
+import type { JsonApiResource } from "../types/api";
+
+export interface JsonApiCollectionResult<TAttributes extends object> {
+  items: Array<JsonApiResource<TAttributes>>;
+  nextCursor?: string;
+  prevCursor?: string;
+  meta?: Record<string, unknown>;
+}
+
+interface JsonApiDocumentShape {
+  data: unknown;
+  links?: unknown;
+  meta?: unknown;
+}
+
+export function expectResource<TAttributes extends object>(
+  payload: unknown
+): JsonApiResource<TAttributes> {
+  const document = asJsonApiDocument(payload);
+
+  if (!isJsonApiResource<TAttributes>(document.data)) {
+    throw new CliError("Expected a JSON:API resource object in response");
+  }
+
+  return document.data;
+}
+
+export function expectCollection<TAttributes extends object>(
+  payload: unknown
+): JsonApiCollectionResult<TAttributes> {
+  const document = asJsonApiDocument(payload);
+
+  if (!Array.isArray(document.data)) {
+    throw new CliError("Expected a JSON:API collection in response");
+  }
+
+  const items = document.data.filter(isJsonApiResource<TAttributes>);
+
+  if (items.length !== document.data.length) {
+    throw new CliError("Expected a JSON:API collection in response");
+  }
+
+  return {
+    items,
+    nextCursor: extractCursor(linkValue(document.links, "next")),
+    prevCursor: extractCursor(linkValue(document.links, "prev")),
+    meta: isRecord(document.meta) ? document.meta : undefined
+  };
+}
+
+function asJsonApiDocument(
+  payload: unknown,
+): JsonApiDocumentShape {
+  if (!isRecord(payload)) {
+    throw new CliError("Expected a JSON:API document in response");
+  }
+
+  if (!("data" in payload)) {
+    throw new CliError("Expected a JSON:API document in response");
+  }
+
+  return {
+    data: payload.data,
+    links: payload.links,
+    meta: payload.meta,
+  };
+}
+
+function isJsonApiResource<TAttributes extends object>(
+  value: unknown,
+): value is JsonApiResource<TAttributes> {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  return (
+    typeof value.id === "string" &&
+    typeof value.type === "string" &&
+    isRecord(value.attributes)
+  );
+}
+
+function linkValue(
+  links: unknown,
+  key: string,
+): string | null | undefined {
+  if (!isRecord(links)) {
+    return undefined;
+  }
+
+  const value = links[key];
+
+  if (typeof value === "string" || value === null) {
+    return value;
+  }
+
+  return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function extractCursor(link: string | null | undefined): string | undefined {
+  if (!link) {
+    return undefined;
+  }
+
+  try {
+    const url = new URL(link, "http://placeholder.local");
+    return (
+      url.searchParams.get("page[after]") ??
+      url.searchParams.get("page[cursor]") ??
+      undefined
+    );
+  } catch {
+    return undefined;
+  }
+}

package/src/lib/output.ts

@@ -0,0 +1,203 @@
+import type { OutputMode } from "../types/api";
+
+export interface Io {
+  stdout: (message: string) => void;
+  stderr: (message: string) => void;
+  stdoutIsTTY?: boolean;
+  stderrIsTTY?: boolean;
+}
+
+export function defaultIo(): Io {
+  return {
+    stdout: (message) => process.stdout.write(`${message}\n`),
+    stderr: (message) => process.stderr.write(`${message}\n`),
+    stdoutIsTTY: process.stdout.isTTY,
+    stderrIsTTY: process.stderr.isTTY,
+  };
+}
+
+export function printJson(io: Io, value: unknown): void {
+  io.stdout(JSON.stringify(value, null, 2));
+}
+
+export function printValue(io: Io, outputMode: OutputMode, value: unknown): void {
+  if (outputMode === "json") {
+    printJson(io, value);
+    return;
+  }
+
+  if (typeof value === "string") {
+    io.stdout(value);
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      io.stdout("No results.");
+      return;
+    }
+
+    if (isRecordArray(value)) {
+      io.stdout(renderTable(value));
+      return;
+    }
+
+    printJson(io, value);
+    return;
+  }
+
+  if (typeof value === "object" && value !== null) {
+    io.stdout(renderRecord(value as Record<string, unknown>));
+    return;
+  }
+
+  io.stdout(formatCell(value));
+}
+
+function renderTable(rows: Record<string, unknown>[]): string {
+  const columns = collectColumns(rows);
+
+  if (columns.length === 0) {
+    return "";
+  }
+
+  const renderedRows = rows.map((row) =>
+    columns.map((column) => formatTableCell(column, row[column])),
+  );
+  const widths = columns.map((column, index) =>
+    Math.max(
+      column.length,
+      ...renderedRows.map((row) => row[index]!.length),
+    ),
+  );
+
+  return [
+    renderTableLine(columns, widths),
+    renderTableLine(widths.map((width) => "-".repeat(width)), widths),
+    ...renderedRows.map((row) => renderTableLine(row, widths)),
+  ].join("\n");
+}
+
+function renderRecord(value: Record<string, unknown>): string {
+  return Object.entries(value)
+    .map(([key, entry]) => `${key}: ${formatCell(entry)}`)
+    .join("\n");
+}
+
+function isRecordArray(value: unknown[]): value is Record<string, unknown>[] {
+  return value.every(isRecord);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatCell(value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    return value.replace(/\s+/g, " ").trim();
+  }
+
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+
+  return String(value);
+}
+
+function collectColumns(rows: Record<string, unknown>[]): string[] {
+  const columns: string[] = [];
+
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (!columns.includes(key)) {
+        columns.push(key);
+      }
+    }
+  }
+
+  return columns;
+}
+
+function formatTableCell(column: string, value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    const normalized = value.replace(/\s+/g, " ").trim();
+
+    if (isDateColumn(column)) {
+      return formatDateValue(normalized);
+    }
+
+    if (column === "body") {
+      return truncate(normalized, 30);
+    }
+
+    return normalized;
+  }
+
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+
+  return String(value);
+}
+
+function renderTableLine(cells: string[], widths: number[]): string {
+  return cells
+    .map((cell, index) => cell.padEnd(widths[index]!))
+    .join("  ")
+    .trimEnd();
+}
+
+function isDateColumn(column: string): boolean {
+  return column === "date" || column.endsWith("_at") || /At$/.test(column);
+}
+
+function formatDateValue(value: string): string {
+  const timestamp = Date.parse(value);
+
+  if (Number.isNaN(timestamp)) {
+    return value;
+  }
+
+  return formatLocalTimestamp(new Date(timestamp));
+}
+
+function truncate(value: string, maxLength: number): string {
+  if (value.length <= maxLength) {
+    return value;
+  }
+
+  return `${value.slice(0, maxLength - 3)}...`;
+}
+
+function formatLocalTimestamp(value: Date): string {
+  const year = value.getFullYear();
+  const month = padDatePart(value.getMonth() + 1);
+  const day = padDatePart(value.getDate());
+  const hours = padDatePart(value.getHours());
+  const minutes = padDatePart(value.getMinutes());
+  const seconds = padDatePart(value.getSeconds());
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} ${formatTimezoneOffset(value)}`;
+}
+
+function formatTimezoneOffset(value: Date): string {
+  const offsetMinutes = -value.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const absoluteMinutes = Math.abs(offsetMinutes);
+  const hours = padDatePart(Math.floor(absoluteMinutes / 60));
+  const minutes = padDatePart(absoluteMinutes % 60);
+
+  return `${sign}${hours}:${minutes}`;
+}
+
+function padDatePart(value: number): string {
+  return String(value).padStart(2, "0");
+}