@meginhufr/brua-cli 0.1.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@meginhufr/brua-cli",
+  "version": "0.1.0",
+  "description": "Brua from the command line and CI: push images and animations into change sets, and read what the current release serves.",
+  "author": "Meginhufr AS <hello@brua.dev> (https://brua.dev)",
+  "license": "MIT",
+  "homepage": "https://brua.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Meginhufr/brua-cli.git",
+    "directory": "cli"
+  },
+  "type": "module",
+  "bin": {
+    "brua": "./src/brua.ts"
+  },
+  "files": [
+    "src",
+    "openapi.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "check": "tsc -p .",
+    "test": "tsc -p . && node --test test/",
+    "generate": "curl -sf ${BRUA_API_URL:-http://localhost:7800}/swagger/v1/swagger.json -o openapi.json && openapi-typescript openapi.json -o src/openapi.d.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "openapi-typescript": "7.9.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/api.ts

@@ -0,0 +1,153 @@
+// Brua's API from a system's point of view: a key, a project, and the operations the CLI uses, each named by its
+// method and path in the public document (openapi.json, types in openapi.d.ts), so the two are checked against
+// each other by the compiler and test/contract.test.ts.
+import type { components, paths } from "./openapi.d.ts";
+
+export type Schemas = components["schemas"];
+export type AssetResponse = Schemas["AssetResponse"];
+export type AssetVersion = Schemas["AssetVersionDto"];
+export type AssetDetail = Schemas["AssetDetailDto"];
+export type ChangeSet = Schemas["ChangeSetDto"];
+export type ErrorBody = Schemas["ErrorDto"];
+export type Project = Schemas["ProjectDto"];
+export type SourceUpload = Schemas["SourceUploadDto"];
+export type CreateAsset = Schemas["CreateAssetRequest"];
+export type CreateVersion = Schemas["CreateVersionRequest"];
+
+type Method = "get" | "post" | "put" | "delete";
+
+export const operations = {
+  project: ["get", "/v1/projects/{project}"],
+  listAssets: ["get", "/v1/projects/{project}/assets"],
+  createAsset: ["post", "/v1/projects/{project}/assets"],
+  versions: ["get", "/v1/projects/{project}/assets/{id}/versions"],
+  createVersion: ["post", "/v1/projects/{project}/assets/{id}/versions"],
+  version: ["get", "/v1/projects/{project}/assets/{id}/versions/{version}"],
+  uploadUrl: ["post", "/v1/projects/{project}/assets/{id}/versions/{version}/slots/{slot}/upload-url"],
+  complete: ["post", "/v1/projects/{project}/assets/{id}/versions/{version}/slots/{slot}/complete"],
+  submitVersion: ["post", "/v1/projects/{project}/assets/{id}/versions/{version}/submit"],
+  get: ["get", "/v1/projects/{project}/assets/{id}"],
+  changeSets: ["get", "/v1/projects/{project}/change-sets"],
+  createChangeSet: ["post", "/v1/projects/{project}/change-sets"],
+  submitChangeSet: ["post", "/v1/projects/{project}/change-sets/{id}/submit"],
+} as const satisfies Record<string, readonly [Method, keyof paths]>;
+
+export interface Settings {
+  /** The API, such as https://api.brua.dev. */
+  url: string;
+  /** A project API key. Pushing takes assets:write; reading, and finding change sets by name, delivery:read. */
+  key: string;
+  project: string;
+}
+
+/** What the API answered when it refused: the status and the error body, with its code and what it is about. */
+export class BruaError extends Error {
+  readonly status: number;
+  readonly body: ErrorBody | undefined;
+
+  constructor(status: number, body: ErrorBody | undefined, message: string) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+
+  get code(): string | undefined {
+    return this.body?.error;
+  }
+}
+
+export class Api {
+  readonly settings: Settings;
+
+  constructor(settings: Settings) {
+    this.settings = { ...settings, url: settings.url.replace(/\/+$/, "") };
+  }
+
+  project(): Promise<Project> {
+    return this.request("project", {});
+  }
+
+  listAssets(): Promise<Schemas["AssetSummaryDto"][]> {
+    return this.request("listAssets", {});
+  }
+
+  createAsset(body: CreateAsset): Promise<AssetVersion> {
+    return this.request("createAsset", {}, body);
+  }
+
+  versions(id: string): Promise<AssetDetail> {
+    return this.request("versions", { id });
+  }
+
+  createVersion(id: string, body: CreateVersion): Promise<AssetVersion> {
+    return this.request("createVersion", { id }, body);
+  }
+
+  version(id: string, version: number): Promise<AssetVersion> {
+    return this.request("version", { id, version });
+  }
+
+  uploadUrl(id: string, version: number, slot: string): Promise<SourceUpload> {
+    return this.request("uploadUrl", { id, version, slot });
+  }
+
+  complete(id: string, version: number, slot: string): Promise<AssetVersion> {
+    return this.request("complete", { id, version, slot });
+  }
+
+  submitVersion(id: string, version: number, changeSet?: string): Promise<ChangeSet> {
+    return this.request("submitVersion", { id, version }, { changeSet: changeSet ?? null });
+  }
+
+  get(id: string, lang?: string): Promise<AssetResponse> {
+    return this.request("get", { id }, undefined, lang ? { "Accept-Language": lang } : {});
+  }
+
+  changeSets(): Promise<ChangeSet[]> {
+    return this.request("changeSets", {});
+  }
+
+  createChangeSet(name: string): Promise<ChangeSet> {
+    return this.request("createChangeSet", {}, { name });
+  }
+
+  submitChangeSet(id: string): Promise<ChangeSet> {
+    return this.request("submitChangeSet", { id });
+  }
+
+  private async request<T>(
+    operation: keyof typeof operations,
+    params: Record<string, string | number>,
+    body?: unknown,
+    headers: Record<string, string> = {},
+  ): Promise<T> {
+    const [method, template] = operations[operation];
+    const path = template.replace(/\{(\w+)\}/g, (_, name: string) =>
+      encodeURIComponent(name === "project" ? this.settings.project : String(params[name])));
+    const response = await fetch(`${this.settings.url}${path}`, {
+      method: method.toUpperCase(),
+      headers: {
+        "X-Api-Key": this.settings.key,
+        Accept: "application/json",
+        ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+        ...headers,
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      let error: ErrorBody | undefined;
+      try { error = JSON.parse(text); } catch { /* not JSON */ }
+      throw new BruaError(response.status, error, describe(response.status, error, `${method.toUpperCase()} ${path}`));
+    }
+    return (text ? JSON.parse(text) : undefined) as T;
+  }
+}
+
+function describe(status: number, error: ErrorBody | undefined, call: string): string {
+  if (status === 401) return "The API key was refused: set BRUA_API_KEY to a key of the project.";
+  if (status === 403 && !error) return `The key may not do this (${call}): a push needs the scope assets:write, reading needs delivery:read.`;
+  if (!error) return `${call} answered ${status}.`;
+  const fields = error.errors ? Object.entries(error.errors).map(([field, messages]) => `${field}: ${messages.join(" ")}`).join("; ") : "";
+  return `${error.error}${error.id ? ` (${error.id})` : ""}${fields ? `: ${fields}` : ""}`;
+}

package/src/args.ts

@@ -0,0 +1,70 @@
+// The command line, parsed: a command, its positional arguments and its flags. Flags are --name value,
+// --name=value, --name alone (true), --no-name (false), and a flag given twice keeps both values.
+
+export interface Parsed {
+  command: string | undefined;
+  positionals: string[];
+  flags: Map<string, string[]>;
+}
+
+export function parseArgs(argv: string[]): Parsed {
+  const parsed: Parsed = { command: undefined, positionals: [], flags: new Map() };
+  const add = (name: string, value: string) => parsed.flags.set(name, [...(parsed.flags.get(name) ?? []), value]);
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      if (parsed.command === undefined) parsed.command = arg;
+      else parsed.positionals.push(arg);
+      continue;
+    }
+    const body = arg.slice(2);
+    const equals = body.indexOf("=");
+    if (equals >= 0) {
+      add(body.slice(0, equals), body.slice(equals + 1));
+    } else if (body.startsWith("no-")) {
+      add(body.slice(3), "false");
+    } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+      add(body, argv[++i]);
+    } else {
+      add(body, "true");
+    }
+  }
+  return parsed;
+}
+
+/** The flag's last value, or undefined. */
+export function flag(parsed: Parsed, name: string): string | undefined {
+  const values = parsed.flags.get(name);
+  return values?.[values.length - 1];
+}
+
+/** Every value the flag was given. */
+export function flags(parsed: Parsed, name: string): string[] {
+  return parsed.flags.get(name) ?? [];
+}
+
+export function boolFlag(parsed: Parsed, name: string, fallback: boolean): boolean {
+  const value = flag(parsed, name);
+  return value === undefined ? fallback : value !== "false";
+}
+
+export function numberFlag(parsed: Parsed, name: string): number | undefined {
+  const value = flag(parsed, name);
+  if (value === undefined) return undefined;
+  const n = Number(value);
+  if (!Number.isFinite(n)) throw new Error(`--${name} takes a number, not "${value}".`);
+  return n;
+}
+
+/** "nb=Rødt ullpledd" pairs, from repeated flags or lines, as an object. */
+export function pairs(values: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const value of values.flatMap((v) => v.split("\n"))) {
+    const line = value.trim();
+    if (!line) continue;
+    const equals = line.indexOf("=");
+    if (equals <= 0) throw new Error(`Expected name=value, got "${line}".`);
+    result[line.slice(0, equals).trim()] = line.slice(equals + 1).trim();
+  }
+  return result;
+}

package/src/brua.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// Brua from the command line: push sources into change sets, and read what the API says. Runs on Node 24 or later.
+import { basename, extname } from "node:path";
+import { boolFlag, flag, flags, numberFlag, pairs, parseArgs, type Parsed } from "./args.ts";
+import { Api, BruaError, type ChangeSet } from "./api.ts";
+import { push } from "./push.ts";
+import { pull, type Language } from "./pull.ts";
+
+const HELP = `brua: images and animations into Brua, and out again.
+
+  brua push <file> [--id hero] [--alt nb="Rødt ullpledd" --alt en="Red blanket"] [--change-set "Spring campaign"]
+  brua push --id gift-icon --preset fixed --width 64 --height 64 --color-schemes any-dark \\
+            --slot any.still.source=icon.png --slot dark.still.source=icon-dark.png
+  brua pull src/brua/assets.ts     the released asset ids as a source file: .ts, .swift, .kt, .cs or .json
+  brua get <id> [--lang nb]        what the current release serves, as the delivery API's JSON
+  brua versions <id>               the asset's versions and their status
+  brua change-sets                 the project's change sets
+  brua submit <change set>         sends a change set for review, by name or id
+  brua project                     the project's name and languages
+
+Settings, as flags or environment: --api-url (BRUA_API_URL, default https://api.brua.dev), --key (BRUA_API_KEY),
+--project (BRUA_PROJECT). A push needs a key with assets:write; reading, and change sets by name, delivery:read.
+
+push: the asset is created on first push and gets a new version after that. Either way the flags say which files the
+version has (--preset flexible, fixed or animated, within the asset's sizing; --width and --height for fixed and
+animated; --color-schemes any, any-dark or both; --languages none, optional or required; --scales single or individual;
+--still-fit match or fill; --decorative), copied from the version before when left out. Alt text comes from --alt, --alt-file, or
+hero.alt.json beside hero.jpg. The version goes into the change set named by --change-set (opened when there is none),
+or into a new one; --no-wait uploads and stops, --no-submit waits but leaves it out of change sets. --json prints the
+result as JSON.
+
+pull: writes the project's released asset ids as constants named in camel case (gift-icon becomes giftIcon), so a
+missing asset is a compile error. --language typescript, swift, kotlin, csharp or json when the extension doesn't say;
+--namespace for the Kotlin package or C# namespace; --all includes assets with no release yet; --check writes nothing
+and exits 1 when the file is out of date, for CI.`;
+
+async function main(argv: string[]): Promise<void> {
+  const parsed = parseArgs(argv);
+  const json = boolFlag(parsed, "json", false);
+  const out = (value: unknown, text: () => string) => console.log(json ? JSON.stringify(value, null, 2) : text());
+
+  switch (parsed.command) {
+    case undefined:
+    case "help":
+      console.log(HELP);
+      return;
+
+    case "push": {
+      const api = client(parsed);
+      const file = parsed.positionals[0];
+      const slots = pairs(flags(parsed, "slot"));
+      const id = flag(parsed, "id") ?? (file ? idFrom(file) : undefined);
+      if (!id) throw new Error("Give --id, or a file to name the asset after.");
+      const result = await push(api, {
+        id,
+        file,
+        slots,
+        preset: flag(parsed, "preset"),
+        alt: pairs(flags(parsed, "alt")),
+        altFile: flag(parsed, "alt-file"),
+        decorative: flag(parsed, "decorative") === undefined ? undefined : boolFlag(parsed, "decorative", false),
+        width: numberFlag(parsed, "width"),
+        height: numberFlag(parsed, "height"),
+        colorSchemes: flag(parsed, "color-schemes"),
+        stillFit: flag(parsed, "still-fit"),
+        languages: flag(parsed, "languages"),
+        scales: flag(parsed, "scales"),
+        changeSet: flag(parsed, "change-set"),
+        wait: boolFlag(parsed, "wait", true),
+        submit: boolFlag(parsed, "submit", true),
+        log: json ? undefined : (line) => console.log(line),
+      });
+      if (json) console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    case "pull": {
+      const result = await pull(client(parsed), {
+        out: positional(parsed, "the file to write, such as src/brua/assets.ts"),
+        language: flag(parsed, "language") as Language | undefined,
+        namespace: flag(parsed, "namespace"),
+        all: boolFlag(parsed, "all", false),
+        check: boolFlag(parsed, "check", false),
+      });
+      const count = `${result.count} ${result.count === 1 ? "asset" : "assets"}`;
+      if (result.changed && boolFlag(parsed, "check", false)) {
+        out(result, () => `${result.file} is out of date: run brua pull ${result.file}.`);
+        process.exitCode = 1;
+      } else {
+        out(result, () => result.changed ? `Wrote ${count} to ${result.file}.` : `${result.file} is up to date (${count}).`);
+      }
+      return;
+    }
+
+    case "get": {
+      const id = positional(parsed, "the asset's id");
+      const asset = await client(parsed).get(id, flag(parsed, "lang"));
+      console.log(JSON.stringify(asset, null, 2));
+      return;
+    }
+
+    case "versions": {
+      const id = positional(parsed, "the asset's id");
+      const detail = await client(parsed).versions(id);
+      out(detail, () => [
+        `${detail.id}${detail.library ? `, in the library ${detail.library}` : ""}${detail.liveVersion ? `, version ${detail.liveVersion} in prod` : ", not released"}`,
+        ...detail.versions.map((v) => `  v${v.version}  ${v.status.toLowerCase().padEnd(10)} ${v.preset.padEnd(9)} ${v.width && v.height ? `${v.width}×${v.height}` : ""}${v.failureCode ? `  ${v.failureCode}` : ""}`),
+      ].join("\n"));
+      return;
+    }
+
+    case "change-sets": {
+      const changeSets = await client(parsed).changeSets();
+      out(changeSets, () => changeSets.length === 0 ? "No change sets." : changeSets.map(line).join("\n"));
+      return;
+    }
+
+    case "submit": {
+      const api = client(parsed);
+      const wanted = positional(parsed, "the change set's name or id");
+      const target = /^[0-9a-f-]{36}$/i.test(wanted) ? { id: wanted }
+        : (await api.changeSets()).find((c) => c.status === "open" && c.name === wanted)
+          ?? (() => { throw new Error(`No open change set named "${wanted}".`); })();
+      const submitted = await api.submitChangeSet(target.id);
+      out(submitted, () => `"${submitted.name}" is in review (${submitted.id}).`);
+      return;
+    }
+
+    case "project": {
+      const project = await client(parsed).project();
+      out(project, () => `${project.name} (${project.slug}): languages ${project.languages.join(", ")}`);
+      return;
+    }
+
+    default:
+      throw new Error(`Unknown command "${parsed.command}". Run brua help.`);
+  }
+}
+
+function client(parsed: Parsed): Api {
+  const key = flag(parsed, "key") ?? process.env.BRUA_API_KEY;
+  const project = flag(parsed, "project") ?? process.env.BRUA_PROJECT;
+  if (!key) throw new Error("No API key: set BRUA_API_KEY or pass --key.");
+  if (!project) throw new Error("No project: set BRUA_PROJECT or pass --project.");
+  return new Api({ url: flag(parsed, "api-url") ?? process.env.BRUA_API_URL ?? "https://api.brua.dev", key, project });
+}
+
+function positional(parsed: Parsed, what: string): string {
+  const value = parsed.positionals[0];
+  if (!value) throw new Error(`Give ${what}.`);
+  return value;
+}
+
+/** An asset id from a file name: hero-image.JPG becomes hero-image. */
+function idFrom(file: string): string {
+  return basename(file, extname(file)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+function line(changeSet: ChangeSet): string {
+  const count = changeSet.changes.length;
+  return `${changeSet.status.padEnd(9)} ${changeSet.name}  ${count} ${count === 1 ? "asset" : "assets"}  ${changeSet.id}`;
+}
+
+main(process.argv.slice(2)).catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`brua: ${message}`);
+  process.exit(error instanceof BruaError && error.status === 401 ? 2 : 1);
+});