@zenalexa/unicli 0.219.0 → 0.220.0

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);
+  },
+});

package/src/adapters/grok/web.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import {
+  grokHtmlToMarkdown,
+  mapGrokBubbles,
+  mapGrokSessions,
+  normalizeGrokBoolean,
+  parseGrokSessionId,
+  pickLatestGrokImages,
+} from "./web.js";
+
+const SESSION_ID = "7c4197f2-10a1-4ebb-a84a-fea89f4f1d06";
+
+function pageMock(evaluateResults: unknown[]) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn(async () => evaluateResults.shift()),
+  };
+}
+
+describe("grok agent-facing web commands", () => {
+  it("validates ids and maps helper rows", () => {
+    expect(parseGrokSessionId(SESSION_ID.toUpperCase())).toBe(SESSION_ID);
+    expect(parseGrokSessionId(`https://grok.com/c/${SESSION_ID}`)).toBe(
+      SESSION_ID,
+    );
+    expect(() => parseGrokSessionId("not-a-uuid")).toThrow("Invalid Grok");
+    expect(normalizeGrokBoolean("on")).toBe(true);
+    expect(grokHtmlToMarkdown("<p>A&nbsp;&lt;B&gt;</p>")).toBe("A <B>");
+    expect(
+      mapGrokBubbles(
+        [
+          { id: "1-user", role: "User", text: "Hi" },
+          {
+            id: "1-assistant",
+            role: "Assistant",
+            text: "Hello",
+            html: "<p>Hello&nbsp;AI</p>",
+          },
+        ],
+        true,
+      ),
+    ).toEqual([
+      { Role: "User", Text: "Hi" },
+      { Role: "Assistant", Text: "Hello AI" },
+    ]);
+    expect(mapGrokSessions([{ id: SESSION_ID, title: "" }])).toEqual([
+      {
+        Index: 1,
+        Title: "(untitled)",
+        Url: `https://grok.com/c/${SESSION_ID}`,
+      },
+    ]);
+    expect(
+      pickLatestGrokImages(
+        [[], [{ src: "https://assets.grok.com/a.jpg", w: 512, h: 512 }]],
+        1,
+      ),
+    ).toEqual([{ src: "https://assets.grok.com/a.jpg", w: 512, h: 512 }]);
+  });
+
+  it("reads current Grok messages", async () => {
+    const command = resolveCommand("grok", "read")?.command;
+    const page = pageMock([
+      "https://grok.com/",
+      [
+        { id: "1-user", role: "User", text: "Hi" },
+        { id: "1-assistant", role: "Assistant", text: "Hello" },
+      ],
+    ]);
+    const result = await command!.func!(page, {});
+    expect(result).toEqual([
+      { Role: "User", Text: "Hi" },
+      { Role: "Assistant", Text: "Hello" },
+    ]);
+  });
+
+  it("lists Grok history from the sidebar", async () => {
+    const command = resolveCommand("grok", "history")?.command;
+    const page = pageMock([
+      "https://grok.com/",
+      true,
+      [{ id: SESSION_ID, title: "Chat" }],
+    ]);
+    const result = await command!.func!(page, { limit: 20 });
+    expect(result).toEqual([
+      {
+        Index: 1,
+        Title: "Chat",
+        Url: `https://grok.com/c/${SESSION_ID}`,
+      },
+    ]);
+  });
+
+  it("rejects invalid Grok integer arguments instead of clamping", async () => {
+    const command = resolveCommand("grok", "history")?.command;
+    await expect(command!.func!(pageMock([]), { limit: 101 })).rejects.toThrow(
+      "Grok history limit must be <= 100.",
+    );
+  });
+
+  it("opens Grok detail and polls for messages", async () => {
+    const command = resolveCommand("grok", "detail")?.command;
+    const page = pageMock([
+      [{ id: "1-assistant", role: "Assistant", text: "Answer" }],
+    ]);
+    const result = await command!.func!(page, { id: SESSION_ID });
+    expect(page.goto).toHaveBeenCalledWith(`https://grok.com/c/${SESSION_ID}`, {
+      waitUntil: "load",
+      settleMs: 2500,
+    });
+    expect(result).toEqual([{ Role: "Assistant", Text: "Answer" }]);
+  });
+
+  it("sends prompts and starts new chats", async () => {
+    const sendCommand = resolveCommand("grok", "send")?.command;
+    const sendPage = pageMock(["https://grok.com/", { ok: true }]);
+    expect(await sendCommand!.func!(sendPage, { prompt: "hello" })).toEqual([
+      { Status: "sent", Prompt: "hello" },
+    ]);
+
+    const newCommand = resolveCommand("grok", "new")?.command;
+    const newPage = pageMock([]);
+    expect(await newCommand!.func!(newPage, {})).toEqual([
+      { Status: "New chat started" },
+    ]);
+    expect(newPage.goto).toHaveBeenCalledWith("https://grok.com/", {
+      waitUntil: "load",
+      settleMs: 2500,
+    });
+  });
+
+  it("reports Grok status", async () => {
+    const command = resolveCommand("grok", "status")?.command;
+    const page = pageMock([
+      `https://grok.com/c/${SESSION_ID}`,
+      true,
+      `https://grok.com/c/${SESSION_ID}`,
+      "Grok 4",
+      `https://grok.com/c/${SESSION_ID}`,
+    ]);
+    expect(await command!.func!(page, {})).toEqual([
+      {
+        Status: "Connected",
+        Login: "Yes",
+        Model: "Grok 4",
+        SessionId: SESSION_ID,
+        Url: `https://grok.com/c/${SESSION_ID}`,
+      },
+    ]);
+  });
+
+  it("returns generated Grok image rows after stable reads", async () => {
+    const command = resolveCommand("grok", "image")?.command;
+    const images = [
+      [{ src: "https://assets.grok.com/a.jpg", w: 1024, h: 1024 }],
+    ];
+    const page = pageMock([
+      "https://grok.com/",
+      [],
+      { ok: true },
+      images,
+      images,
+      images,
+    ]);
+    const result = await command!.func!(page, {
+      prompt: "draw a rocket",
+      timeout: 10,
+      count: 1,
+    });
+    expect(result).toEqual([
+      {
+        url: "https://assets.grok.com/a.jpg",
+        width: 1024,
+        height: 1024,
+        path: "",
+      },
+    ]);
+  });
+});