@zenalexa/unicli 0.219.0 → 0.220.1

package/src/adapters/flathub/apps.ts

@@ -0,0 +1,254 @@
+/**
+ * @owner   src/adapters/flathub/apps.ts
+ * @does    Register agent-facing Flathub app search and detail commands.
+ * @needs   Flathub public API, AppStream id validation, bounded search limits.
+ * @feeds   surface coverage ledger, Linux app registry search rows, appstream metadata rows.
+ * @breaks  Flathub API drift, weak app id validation, or silent empty rows hide app registry data.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const API_BASE = "https://flathub.org/api/v2";
+const APP_BASE = "https://flathub.org/apps";
+const APP_ID_RE =
+  /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_][A-Za-z0-9_-]*){1,}$/;
+
+function requireNonEmpty(value: unknown, label: string): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`flathub ${label} cannot be empty.`);
+  return text;
+}
+
+export function requireFlathubLimit(value: unknown): number {
+  const raw =
+    value === undefined || value === null || value === "" ? 25 : value;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new Error("flathub limit must be an integer in [1, 100].");
+  }
+  return limit;
+}
+
+export function requireFlathubAppId(value: unknown): string {
+  const id = String(value ?? "").trim();
+  if (!id) throw new Error("flathub appId cannot be empty.");
+  if (!APP_ID_RE.test(id)) {
+    throw new Error(`flathub appId "${String(value)}" is not valid.`);
+  }
+  return id;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function numberField(value: unknown): number | null {
+  const n =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && value.trim()
+        ? Number(value)
+        : NaN;
+  return Number.isFinite(n) ? n : null;
+}
+
+function objectField(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function joinFlathubList(value: unknown, max = 10): string {
+  if (!Array.isArray(value)) return "";
+  const items = value.filter((item) => typeof item === "string" && item.trim());
+  return items.length > max
+    ? [...items.slice(0, max), `(+${items.length - max})`].join(", ")
+    : items.join(", ");
+}
+
+function timestampToDate(value: unknown): string | null {
+  const n = numberField(value);
+  if (n == null || n <= 0) return null;
+  const date = new Date(n * 1000);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString().slice(0, 10);
+}
+
+export function pickLatestFlathubRelease(value: unknown): {
+  date: string | null;
+  version: string | null;
+} {
+  if (!Array.isArray(value)) return { date: null, version: null };
+  const releases = [...(value as Array<Record<string, unknown>>)].sort(
+    (a, b) => (numberField(b.timestamp) ?? 0) - (numberField(a.timestamp) ?? 0),
+  );
+  const latest = releases[0];
+  if (!latest) return { date: null, version: null };
+  return {
+    version: stringField(latest.version) || null,
+    date: timestampToDate(latest.timestamp) ?? stringField(latest.date) ?? null,
+  };
+}
+
+export function mapFlathubSearchRows(
+  hits: Array<Record<string, unknown>>,
+  limit: number,
+): Array<Record<string, unknown>> {
+  return hits.slice(0, limit).map((hit, index) => {
+    const appId = stringField(hit.app_id);
+    return {
+      rank: index + 1,
+      appId,
+      name: stringField(hit.name),
+      summary: stringField(hit.summary),
+      developer: stringField(hit.developer_name),
+      license: stringField(hit.project_license),
+      isFreeLicense: hit.is_free_license === true,
+      mainCategories:
+        stringField(hit.main_categories) ||
+        joinFlathubList(hit.main_categories),
+      installsLastMonth: numberField(hit.installs_last_month),
+      updatedAt: timestampToDate(hit.updated_at) ?? stringField(hit.updated_at),
+      url: appId ? `${APP_BASE}/${appId}` : "",
+    };
+  });
+}
+
+export function mapFlathubAppRow(
+  appId: string,
+  body: Record<string, unknown>,
+): Record<string, unknown> {
+  const urls = objectField(body.urls);
+  const release = pickLatestFlathubRelease(body.releases);
+  return {
+    appId: stringField(body.id) || appId,
+    name: stringField(body.name),
+    summary: stringField(body.summary),
+    developer: stringField(body.developer_name),
+    license: stringField(body.project_license),
+    isFreeLicense: body.is_free_license === true,
+    isEol: body.is_eol === true,
+    categories: joinFlathubList(body.categories),
+    keywords: joinFlathubList(body.keywords, 8),
+    latestVersion: release.version,
+    latestReleaseDate: release.date,
+    homepage: stringField(urls.homepage) || null,
+    bugtracker: stringField(urls.bugtracker) || null,
+    donation: stringField(urls.donation) || null,
+    url: `${APP_BASE}/${appId}`,
+  };
+}
+
+async function fetchJson(
+  url: URL | string,
+  label: string,
+  init?: RequestInit,
+): Promise<unknown> {
+  const response = await fetch(url, {
+    ...init,
+    headers: {
+      accept: "application/json",
+      "user-agent": "unicli-flathub (https://github.com/olo-dot-io/Uni-CLI)",
+      ...(init?.headers as Record<string, string> | undefined),
+    },
+  });
+  if (response.status === 404) throw new Error(`${label} returned no result.`);
+  if (response.status === 429) throw new Error(`${label} returned HTTP 429.`);
+  if (!response.ok)
+    throw new Error(`${label} returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+cli({
+  site: "flathub",
+  name: "search",
+  description: "Search Flathub apps by keyword",
+  domain: "flathub.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Search keyword",
+    },
+    { name: "limit", type: "int", default: 25, description: "Max rows" },
+  ],
+  columns: [
+    "rank",
+    "appId",
+    "name",
+    "summary",
+    "developer",
+    "license",
+    "isFreeLicense",
+    "mainCategories",
+    "installsLastMonth",
+    "updatedAt",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const query = requireNonEmpty(kwargs.query, "query");
+    const limit = requireFlathubLimit(kwargs.limit);
+    const body = (await fetchJson(`${API_BASE}/search`, "flathub search", {
+      body: JSON.stringify({ hitsPerPage: limit, page: 1, query }),
+      headers: { "content-type": "application/json" },
+      method: "POST",
+    })) as { hits?: unknown };
+    const rows = mapFlathubSearchRows(
+      Array.isArray(body.hits)
+        ? (body.hits as Array<Record<string, unknown>>)
+        : [],
+      limit,
+    );
+    if (rows.length === 0)
+      throw new Error(`flathub search returned no rows for "${query}".`);
+    return rows;
+  },
+});
+
+cli({
+  site: "flathub",
+  name: "app",
+  description: "Fetch full Flathub appstream metadata by app id",
+  domain: "flathub.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "appId",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "AppStream id",
+    },
+  ],
+  columns: [
+    "appId",
+    "name",
+    "summary",
+    "developer",
+    "license",
+    "isFreeLicense",
+    "isEol",
+    "categories",
+    "keywords",
+    "latestVersion",
+    "latestReleaseDate",
+    "homepage",
+    "bugtracker",
+    "donation",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const appId = requireFlathubAppId(kwargs.appId);
+    const body = objectField(
+      await fetchJson(
+        `${API_BASE}/appstream/${encodeURIComponent(appId)}`,
+        "flathub app",
+      ),
+    );
+    if (!body.id)
+      throw new Error(`flathub app returned no row for "${appId}".`);
+    return [mapFlathubAppRow(appId, body)];
+  },
+});

package/src/adapters/goproxy/module.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapGoProxyModuleRow,
+  mapGoProxyVersionRows,
+  requireGoModulePath,
+  requireGoProxyLimit,
+  sortGoVersionsDescending,
+} from "./module.js";
+
+describe("goproxy agent-facing commands", () => {
+  it("validates module paths and limits", () => {
+    expect(requireGoModulePath("github.com/gin-gonic/gin")).toBe(
+      "github.com/gin-gonic/gin",
+    );
+    expect(() => requireGoModulePath("")).toThrow("module path is required");
+    expect(() => requireGoModulePath("noslash")).toThrow("not recognised");
+    expect(requireGoProxyLimit(undefined)).toBe(30);
+    expect(requireGoProxyLimit("200")).toBe(200);
+    expect(() => requireGoProxyLimit("0")).toThrow("goproxy limit must");
+  });
+
+  it("sorts Go semver tags descending", () => {
+    expect(
+      sortGoVersionsDescending(["bad", "v1.2.0-beta.1", "v1.10.0", "v1.2.0"]),
+    ).toEqual(["v1.10.0", "v1.2.0", "v1.2.0-beta.1"]);
+  });
+
+  it("maps module metadata rows", () => {
+    expect(
+      mapGoProxyModuleRow("github.com/gin-gonic/gin", {
+        Version: "v1.10.0",
+        Time: "2026-05-01T12:00:00.123Z",
+        Origin: {
+          VCS: "git",
+          URL: "https://github.com/gin-gonic/gin",
+          Hash: "abc",
+          Ref: "refs/tags/v1.10.0",
+        },
+      }),
+    ).toEqual({
+      module: "github.com/gin-gonic/gin",
+      version: "v1.10.0",
+      publishedAt: "2026-05-01T12:00:00Z",
+      vcs: "git",
+      repository: "https://github.com/gin-gonic/gin",
+      commit: "abc",
+      ref: "refs/tags/v1.10.0",
+      pkgGoDevUrl: "https://pkg.go.dev/github.com/gin-gonic/gin",
+      url: "https://proxy.golang.org/github.com/gin-gonic/gin/@latest",
+    });
+    expect(() => mapGoProxyModuleRow("github.com/x/y", {})).toThrow(
+      "returned no @latest entry",
+    );
+  });
+
+  it("maps version rows without sentinel output", () => {
+    expect(
+      mapGoProxyVersionRows("github.com/gin-gonic/gin", ["v1.0.0", "bad"], 10),
+    ).toEqual([
+      {
+        rank: 1,
+        module: "github.com/gin-gonic/gin",
+        version: "v1.0.0",
+        publishedAt: null,
+        url: "https://proxy.golang.org/github.com/gin-gonic/gin/@v/v1.0.0.info",
+      },
+    ]);
+    expect(() => mapGoProxyVersionRows("github.com/x/y", ["bad"], 10)).toThrow(
+      "no semver-shaped tags",
+    );
+  });
+});

package/src/adapters/goproxy/module.ts

@@ -0,0 +1,258 @@
+/**
+ * @owner   src/adapters/goproxy/module.ts
+ * @does    Register agent-facing Go module proxy metadata and version commands.
+ * @needs   Public proxy.golang.org GOPROXY protocol, TypeScript adapter loader, Go module path validation.
+ * @feeds   surface coverage ledger, Go package registry command surface, agent-readable module rows.
+ * @breaks  GOPROXY protocol drift, weak module path validation, or silent empty rows hide module lookup failures.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const GOPROXY_BASE = "https://proxy.golang.org";
+const MODULE_PATH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/;
+const VERSION_TAG_RE = /^v[0-9]+(\.[0-9]+)*([-+][A-Za-z0-9._-]+)?$/;
+
+interface GoProxyLatest {
+  Version?: unknown;
+  Time?: unknown;
+  Origin?: {
+    VCS?: unknown;
+    URL?: unknown;
+    Hash?: unknown;
+    Ref?: unknown;
+  };
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function trimDate(value: unknown): string | null {
+  const text = stringField(value).trim();
+  if (!text) return null;
+  const noFraction = text.replace(/\.\d+/, "");
+  return noFraction.endsWith("Z")
+    ? noFraction
+    : text.length >= 10
+      ? text.slice(0, 10)
+      : null;
+}
+
+export function requireGoModulePath(value: unknown): string {
+  const modulePath = String(value ?? "").trim();
+  if (!modulePath) throw new Error("goproxy module path is required.");
+  if (!MODULE_PATH_RE.test(modulePath) || !modulePath.includes("/")) {
+    throw new Error(
+      `goproxy module path "${String(value)}" is not recognised.`,
+    );
+  }
+  return modulePath;
+}
+
+export function requireGoProxyLimit(value: unknown, fallback = 30): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 200) {
+    throw new Error(
+      `goproxy limit must be an integer in [1, 200]. Got: ${String(value)}`,
+    );
+  }
+  return n;
+}
+
+function encodeModulePath(modulePath: string): string {
+  return modulePath.split("/").map(encodeURIComponent).join("/");
+}
+
+function parseSemver(tag: string): { numbers: number[]; pre: string } {
+  const stripped = tag.replace(/^v/, "");
+  const noBuild = stripped.split("+")[0] ?? stripped;
+  const dash = noBuild.indexOf("-");
+  const head = dash >= 0 ? noBuild.slice(0, dash) : noBuild;
+  const pre = dash >= 0 ? noBuild.slice(dash + 1) : "";
+  return {
+    numbers: head.split(".").map((part) => {
+      const n = Number.parseInt(part, 10);
+      return Number.isFinite(n) ? n : 0;
+    }),
+    pre,
+  };
+}
+
+function comparePrerelease(left: string, right: string): number {
+  const leftParts = left.split(".");
+  const rightParts = right.split(".");
+  const length = Math.max(leftParts.length, rightParts.length);
+  for (let i = 0; i < length; i += 1) {
+    const a = leftParts[i];
+    const b = rightParts[i];
+    if (a == null) return -1;
+    if (b == null) return 1;
+    const aNum = /^\d+$/.test(a);
+    const bNum = /^\d+$/.test(b);
+    if (aNum && bNum) {
+      const diff = Number(a) - Number(b);
+      if (diff !== 0) return diff;
+      continue;
+    }
+    if (aNum !== bNum) return aNum ? -1 : 1;
+    if (a !== b) return a < b ? -1 : 1;
+  }
+  return 0;
+}
+
+function compareSemver(left: string, right: string): number {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  const length = Math.max(a.numbers.length, b.numbers.length);
+  for (let i = 0; i < length; i += 1) {
+    const diff = (a.numbers[i] ?? 0) - (b.numbers[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  if (a.pre === "" && b.pre !== "") return 1;
+  if (a.pre !== "" && b.pre === "") return -1;
+  return comparePrerelease(a.pre, b.pre);
+}
+
+export function sortGoVersionsDescending(versions: string[]): string[] {
+  return versions
+    .filter((version) => VERSION_TAG_RE.test(version))
+    .sort((a, b) => compareSemver(b, a));
+}
+
+export function mapGoProxyModuleRow(
+  modulePath: string,
+  detail: GoProxyLatest,
+): Record<string, unknown> {
+  if (!detail.Version) {
+    throw new Error(
+      `proxy.golang.org returned no @latest entry for "${modulePath}".`,
+    );
+  }
+  const origin = detail.Origin ?? {};
+  const encoded = encodeModulePath(modulePath);
+  return {
+    module: modulePath,
+    version: stringField(detail.Version),
+    publishedAt: trimDate(detail.Time),
+    vcs: stringField(origin.VCS).trim(),
+    repository: stringField(origin.URL).trim(),
+    commit: stringField(origin.Hash).trim(),
+    ref: stringField(origin.Ref).trim(),
+    pkgGoDevUrl: `https://pkg.go.dev/${modulePath}`,
+    url: `${GOPROXY_BASE}/${encoded}/@latest`,
+  };
+}
+
+export function mapGoProxyVersionRows(
+  modulePath: string,
+  versions: string[],
+  limit: number,
+): Array<Record<string, unknown>> {
+  const encoded = encodeModulePath(modulePath);
+  const sorted = sortGoVersionsDescending(versions).slice(0, limit);
+  if (sorted.length === 0) {
+    throw new Error(
+      `"${modulePath}" has no semver-shaped tags on proxy.golang.org.`,
+    );
+  }
+  return sorted.map((version, index) => ({
+    rank: index + 1,
+    module: modulePath,
+    version,
+    publishedAt: null,
+    url: `${GOPROXY_BASE}/${encoded}/@v/${encodeURIComponent(version)}.info`,
+  }));
+}
+
+async function fetchGoProxy(url: string, label: string): Promise<Response> {
+  const response = await fetch(url, {
+    headers: { "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)" },
+  });
+  if (response.status === 404 || response.status === 410)
+    throw new Error(`${label} returned no result.`);
+  if (response.status === 429) throw new Error(`${label} returned HTTP 429.`);
+  if (!response.ok)
+    throw new Error(`${label} returned HTTP ${response.status}.`);
+  return response;
+}
+
+cli({
+  site: "goproxy",
+  name: "module",
+  description: "Latest version and VCS origin metadata for a Go module",
+  domain: "proxy.golang.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "module",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Go module path",
+    },
+  ],
+  columns: [
+    "module",
+    "version",
+    "publishedAt",
+    "vcs",
+    "repository",
+    "commit",
+    "ref",
+    "pkgGoDevUrl",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const modulePath = requireGoModulePath(kwargs.module);
+    const response = await fetchGoProxy(
+      `${GOPROXY_BASE}/${encodeModulePath(modulePath)}/@latest`,
+      `goproxy module ${modulePath}`,
+    );
+    return [
+      mapGoProxyModuleRow(modulePath, (await response.json()) as GoProxyLatest),
+    ];
+  },
+});
+
+cli({
+  site: "goproxy",
+  name: "versions",
+  description: "Published version tags for a Go module",
+  domain: "proxy.golang.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "module",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Go module path",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 30,
+      description: "Max rows",
+    },
+  ],
+  columns: ["rank", "module", "version", "publishedAt", "url"],
+  func: async (_page, kwargs) => {
+    const modulePath = requireGoModulePath(kwargs.module);
+    const limit = requireGoProxyLimit(kwargs.limit);
+    const response = await fetchGoProxy(
+      `${GOPROXY_BASE}/${encodeModulePath(modulePath)}/@v/list`,
+      `goproxy versions ${modulePath}`,
+    );
+    const versions = (await response.text())
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+    if (versions.length === 0) {
+      throw new Error(
+        `proxy.golang.org returned no published versions for "${modulePath}".`,
+      );
+    }
+    return mapGoProxyVersionRows(modulePath, versions, limit);
+  },
+});