@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/lobsters/read-domain.ts

@@ -0,0 +1,400 @@
+/**
+ * @owner   src/adapters/lobsters/read-domain.ts
+ * @does    Register agent-facing Lobsters read and domain commands.
+ * @needs   Public lobste.rs JSON endpoints, strict ids/domains, bounded comment tree rendering.
+ * @feeds   surface coverage ledger, Lobsters story readers, source-domain research workflows.
+ * @breaks  Lobsters JSON shape drift, weak tree bounds, or lossy HTML conversion degrades reads.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const LOBSTERS_BASE = "https://lobste.rs";
+const DOMAIN_PATTERN =
+  /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+
+interface LobstersComment {
+  short_id?: unknown;
+  parent_comment?: unknown;
+  comment?: unknown;
+  comment_plain?: unknown;
+  commenting_user?: unknown;
+  score?: unknown;
+  is_deleted?: unknown;
+  is_moderated?: unknown;
+}
+
+interface LobstersStory {
+  short_id?: unknown;
+  title?: unknown;
+  description?: unknown;
+  description_plain?: unknown;
+  submitter_user?: unknown;
+  score?: unknown;
+  comment_count?: unknown;
+  comments?: unknown;
+  created_at?: unknown;
+  tags?: unknown;
+  url?: unknown;
+  comments_url?: unknown;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function numberOrBlank(value: unknown): number | "" {
+  return typeof value === "number" && Number.isFinite(value) ? value : "";
+}
+
+export function requireLobstersShortId(value: unknown): string {
+  const id = String(value ?? "").trim();
+  if (!/^[a-z0-9]+$/.test(id)) {
+    throw new Error(`Invalid Lobsters short_id: ${String(value)}.`);
+  }
+  return id;
+}
+
+export function requireLobstersDomain(value: unknown): string {
+  const domain = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!domain) throw new Error("lobsters domain is required.");
+  if (!DOMAIN_PATTERN.test(domain)) {
+    throw new Error(
+      `lobsters domain "${String(value)}" is not a valid hostname.`,
+    );
+  }
+  return domain;
+}
+
+export function requireLobstersLimit(
+  value: unknown,
+  fallback: number,
+  max: number | null,
+  label: string,
+): number {
+  const raw =
+    value === undefined || value === null || value === "" ? fallback : value;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new Error(`lobsters ${label} must be a positive integer.`);
+  }
+  if (max !== null && limit > max) {
+    throw new Error(`lobsters ${label} must be <= ${max}.`);
+  }
+  return limit;
+}
+
+export function requireLobstersMinInt(
+  value: unknown,
+  fallback: number,
+  min: number,
+  label: string,
+): number {
+  const raw =
+    value === undefined || value === null || value === "" ? fallback : value;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < min) {
+    throw new Error(`lobsters ${label} must be an integer >= ${min}.`);
+  }
+  return n;
+}
+
+export function lobstersHtmlToText(value: unknown): string {
+  return String(value ?? "")
+    .replace(/<p>/gi, "\n\n")
+    .replace(/<\/p>/gi, "")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<i>(.*?)<\/i>/gi, "$1")
+    .replace(/<em>(.*?)<\/em>/gi, "$1")
+    .replace(/<strong>(.*?)<\/strong>/gi, "$1")
+    .replace(/<a[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi, "$2 ($1)")
+    .replace(/<pre><code>([\s\S]*?)<\/code><\/pre>/gi, "\n$1\n")
+    .replace(/<code>(.*?)<\/code>/gi, "`$1`")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&#x27;/g, "'")
+    .replace(/&apos;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&#x2F;/g, "/")
+    .trim();
+}
+
+function truncate(text: string, maxLength: number, suffix: string): string {
+  return text.length > maxLength
+    ? `${text.slice(0, maxLength)}${suffix}`
+    : text;
+}
+
+function indentLines(text: string, depth: number): string {
+  if (depth <= 0) return text;
+  const prefix = `${"  ".repeat(depth)}> `;
+  return text
+    .split("\n")
+    .map((line) => `${prefix}${line}`)
+    .join("\n");
+}
+
+function commentShortId(comment: LobstersComment): string {
+  return stringField(comment.short_id);
+}
+
+function commentParentId(comment: LobstersComment): string {
+  return stringField(comment.parent_comment);
+}
+
+function commentBody(comment: LobstersComment): string {
+  return (
+    stringField(comment.comment_plain) || lobstersHtmlToText(comment.comment)
+  );
+}
+
+function storyBody(story: LobstersStory): string {
+  return (
+    stringField(story.description_plain) ||
+    lobstersHtmlToText(story.description)
+  );
+}
+
+function visibleComments(story: LobstersStory): LobstersComment[] {
+  return Array.isArray(story.comments)
+    ? story.comments.filter((comment): comment is LobstersComment => {
+        return typeof comment === "object" && comment !== null;
+      })
+    : [];
+}
+
+export function buildLobstersReadRows(
+  story: LobstersStory | null | undefined,
+  options: {
+    limit: number;
+    maxDepth: number;
+    maxReplies: number;
+    maxLength: number;
+  },
+): Array<Record<string, unknown>> {
+  if (!story || !story.short_id) throw new Error("Lobsters story not found.");
+  const rows: Array<Record<string, unknown>> = [];
+  const body = truncate(
+    storyBody(story).trim(),
+    options.maxLength,
+    "\n... [truncated]",
+  );
+  const storyParts = [stringField(story.title)];
+  if (body) storyParts.push(`\n${body}`);
+  if (story.url) storyParts.push(`\n${stringField(story.url)}`);
+  rows.push({
+    type: "POST",
+    author: stringField(story.submitter_user) || "[deleted]",
+    score: numberOrNull(story.score) ?? 0,
+    text: storyParts.join("").trim(),
+  });
+
+  const children = new Map<string, LobstersComment[]>();
+  for (const comment of visibleComments(story)) {
+    const parent = commentParentId(comment);
+    const bucket = children.get(parent) ?? [];
+    bucket.push(comment);
+    children.set(parent, bucket);
+  }
+
+  function emit(comment: LobstersComment, depth: number): void {
+    if (comment.is_deleted || comment.is_moderated) return;
+    const id = commentShortId(comment);
+    rows.push({
+      type: depth === 0 ? "L0" : `L${depth}`,
+      author: stringField(comment.commenting_user) || "[deleted]",
+      score: numberOrBlank(comment.score),
+      text: indentLines(
+        truncate(commentBody(comment).trim(), options.maxLength, "..."),
+        depth,
+      ),
+    });
+    const kids = id ? (children.get(id) ?? []) : [];
+    if (depth + 1 >= options.maxDepth) {
+      if (kids.length > 0) {
+        rows.push({
+          type: `L${depth + 1}`,
+          author: "",
+          score: "",
+          text: `${"  ".repeat(depth + 1)}[+${kids.length} more replies]`,
+        });
+      }
+      return;
+    }
+    const visible = kids.slice(0, options.maxReplies);
+    for (const kid of visible) emit(kid, depth + 1);
+    const hidden = kids.length - visible.length;
+    if (hidden > 0) {
+      rows.push({
+        type: `L${depth + 1}`,
+        author: "",
+        score: "",
+        text: `${"  ".repeat(depth + 1)}[+${hidden} more replies]`,
+      });
+    }
+  }
+
+  const topLevel = children.get("") ?? [];
+  const visibleTop = topLevel.slice(0, options.limit);
+  for (const comment of visibleTop) emit(comment, 0);
+  const hiddenTop = topLevel.length - visibleTop.length;
+  if (hiddenTop > 0) {
+    rows.push({
+      type: "",
+      author: "",
+      score: "",
+      text: `[+${hiddenTop} more top-level comments]`,
+    });
+  }
+  return rows;
+}
+
+export function mapLobstersDomainRows(
+  stories: LobstersStory[],
+): Array<Record<string, unknown>> {
+  return stories.map((item, index) => ({
+    rank: index + 1,
+    id: stringField(item.short_id),
+    title: stringField(item.title),
+    score: numberOrNull(item.score),
+    author: stringField(item.submitter_user),
+    comments: numberOrNull(item.comment_count),
+    created_at: stringField(item.created_at).slice(0, 10),
+    tags: Array.isArray(item.tags) ? item.tags.map(String).join(", ") : "",
+    submission_url: stringField(item.url),
+    comments_url: stringField(item.comments_url),
+  }));
+}
+
+async function fetchLobstersJson<T>(url: string, label: string): Promise<T> {
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      "User-Agent":
+        "unicli-lobsters/1.0 (https://github.com/olo-dot-io/Uni-CLI)",
+    },
+  });
+  if (response.status === 404) throw new Error(`${label} not found.`);
+  if (!response.ok)
+    throw new Error(`Lobsters returned HTTP ${response.status} for ${label}.`);
+  return (await response.json()) as T;
+}
+
+cli({
+  site: "lobsters",
+  name: "read",
+  description: "Read a Lobste.rs story and its comment tree",
+  domain: "lobste.rs",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Lobste.rs short_id",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 25,
+      description: "Max top-level comments",
+    },
+    { name: "depth", type: "int", default: 2, description: "Max reply depth" },
+    {
+      name: "replies",
+      type: "int",
+      default: 5,
+      description: "Max replies per comment",
+    },
+    {
+      name: "max-length",
+      type: "int",
+      default: 2000,
+      description: "Max characters per comment body",
+    },
+  ],
+  columns: ["type", "author", "score", "text"],
+  func: async (_page, kwargs) => {
+    const id = requireLobstersShortId(kwargs.id);
+    const story = await fetchLobstersJson<LobstersStory>(
+      `${LOBSTERS_BASE}/s/${id}.json`,
+      `lobsters/${id}`,
+    );
+    return buildLobstersReadRows(story, {
+      limit: requireLobstersLimit(kwargs.limit, 25, null, "read limit"),
+      maxDepth: requireLobstersLimit(kwargs.depth, 2, null, "read depth"),
+      maxReplies: requireLobstersLimit(kwargs.replies, 5, null, "read replies"),
+      maxLength: requireLobstersMinInt(
+        kwargs["max-length"] ?? kwargs.maxLength,
+        2000,
+        100,
+        "read max-length",
+      ),
+    });
+  },
+});
+
+cli({
+  site: "lobsters",
+  name: "domain",
+  description: "Lobste.rs stories submitted from a specific domain",
+  domain: "lobste.rs",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    {
+      name: "domain",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Source domain",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 20,
+      description: "Number of stories",
+    },
+  ],
+  columns: [
+    "rank",
+    "id",
+    "title",
+    "score",
+    "author",
+    "comments",
+    "created_at",
+    "tags",
+    "submission_url",
+    "comments_url",
+  ],
+  func: async (_page, kwargs) => {
+    const domain = requireLobstersDomain(kwargs.domain);
+    const limit = requireLobstersLimit(kwargs.limit, 20, 25, "domain limit");
+    const stories = await fetchLobstersJson<unknown>(
+      `${LOBSTERS_BASE}/domains/${encodeURIComponent(domain)}.json`,
+      `lobsters domain ${domain}`,
+    );
+    if (!Array.isArray(stories) || stories.length === 0) {
+      throw new Error(`No Lobste.rs stories found for domain "${domain}".`);
+    }
+    return mapLobstersDomainRows(
+      stories
+        .filter(
+          (story): story is LobstersStory =>
+            typeof story === "object" && story !== null,
+        )
+        .slice(0, limit),
+    );
+  },
+});

package/src/adapters/maven/artifact.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapMavenArtifactRows,
+  parseMavenCoordinate,
+  requireMavenLimit,
+} from "./artifact.js";
+
+describe("maven agent-facing artifact command", () => {
+  it("parses coordinates and validates limits", () => {
+    expect(parseMavenCoordinate(" org.example:lib ")).toEqual({
+      groupId: "org.example",
+      artifactId: "lib",
+      version: "",
+    });
+    expect(parseMavenCoordinate("org.example:lib:1.0.0")).toEqual({
+      groupId: "org.example",
+      artifactId: "lib",
+      version: "1.0.0",
+    });
+    expect(() => parseMavenCoordinate("org.example")).toThrow(
+      "coordinate must be",
+    );
+    expect(requireMavenLimit(undefined, 20)).toBe(20);
+    expect(requireMavenLimit("200", 20)).toBe(200);
+    expect(() => requireMavenLimit("201", 20)).toThrow(
+      "limit must be an integer",
+    );
+  });
+
+  it("maps gav rows newest-first shape with published timestamp", () => {
+    expect(
+      mapMavenArtifactRows(
+        {
+          response: {
+            docs: [
+              {
+                g: "org.example",
+                a: "lib",
+                v: "1.2.3",
+                p: "jar",
+                timestamp: 1770000000000,
+                tags: ["testing", "example"],
+              },
+            ],
+          },
+        },
+        { groupId: "org.example", artifactId: "lib", version: "" },
+      ),
+    ).toEqual([
+      {
+        groupId: "org.example",
+        artifactId: "lib",
+        version: "1.2.3",
+        packaging: "jar",
+        publishedAt: "2026-02-02T02:40:00.000Z",
+        tags: "testing, example",
+        url: "https://central.sonatype.com/artifact/org.example/lib/1.2.3",
+      },
+    ]);
+    expect(() =>
+      mapMavenArtifactRows(
+        { response: { docs: [] } },
+        { groupId: "g", artifactId: "a", version: "" },
+      ),
+    ).toThrow("no published versions");
+  });
+});

package/src/adapters/maven/artifact.ts

@@ -0,0 +1,155 @@
+/**
+ * @owner   src/adapters/maven/artifact.ts
+ * @does    Register agent-facing Maven Central artifact version history command.
+ * @needs   search.maven.org Solr gav core and coordinate validation.
+ * @feeds   surface coverage ledger, JVM dependency inspection, registry command surface.
+ * @breaks  Maven coordinate parsing or Solr envelope drift hides dependency versions.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+const MAVEN_BASE = "https://search.maven.org/solrsearch/select";
+
+interface MavenDoc {
+  g?: unknown;
+  a?: unknown;
+  v?: unknown;
+  p?: unknown;
+  timestamp?: unknown;
+  tags?: unknown;
+}
+
+interface MavenBody {
+  response?: { docs?: MavenDoc[] };
+}
+
+export interface MavenCoordinate {
+  groupId: string;
+  artifactId: string;
+  version: string;
+}
+
+function stringField(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function epochMsToIso(value: unknown): string {
+  return typeof value === "number" && Number.isFinite(value)
+    ? new Date(value).toISOString()
+    : "";
+}
+
+export function requireMavenLimit(value: unknown, fallback: number): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 200) {
+    throw new Error(
+      `limit must be an integer in [1, 200]. Got: ${String(value)}`,
+    );
+  }
+  return n;
+}
+
+export function parseMavenCoordinate(value: unknown): MavenCoordinate {
+  const coordinate = String(value ?? "").trim();
+  const parts = coordinate.split(":").map((part) => part.trim());
+  if (parts.length !== 2 && parts.length !== 3) {
+    throw new Error(
+      'coordinate must be "groupId:artifactId" or "groupId:artifactId:version".',
+    );
+  }
+  const [groupId, artifactId, version = ""] = parts;
+  if (!groupId || !artifactId) {
+    throw new Error("coordinate groupId and artifactId are required.");
+  }
+  return { groupId, artifactId, version };
+}
+
+export function mapMavenArtifactRows(
+  body: MavenBody,
+  coordinate: MavenCoordinate,
+): Array<Record<string, unknown>> {
+  const docs = Array.isArray(body.response?.docs) ? body.response.docs : [];
+  if (docs.length === 0) {
+    const label = coordinate.version
+      ? `${coordinate.groupId}:${coordinate.artifactId}:${coordinate.version}`
+      : `${coordinate.groupId}:${coordinate.artifactId}`;
+    throw new Error(`Maven Central has no published versions for ${label}.`);
+  }
+  return docs.map((doc) => {
+    const version = stringField(doc.v);
+    return {
+      groupId: stringField(doc.g) || coordinate.groupId,
+      artifactId: stringField(doc.a) || coordinate.artifactId,
+      version,
+      packaging: stringField(doc.p),
+      publishedAt: epochMsToIso(doc.timestamp),
+      tags: Array.isArray(doc.tags)
+        ? doc.tags.map(stringField).filter(Boolean).join(", ")
+        : "",
+      url: version
+        ? `https://central.sonatype.com/artifact/${coordinate.groupId}/${coordinate.artifactId}/${version}`
+        : `https://central.sonatype.com/artifact/${coordinate.groupId}/${coordinate.artifactId}`,
+    };
+  });
+}
+
+async function fetchMavenJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      "User-Agent": "unicli (https://github.com/olo-dot-io/Uni-CLI)",
+      Accept: "application/json",
+    },
+  });
+  if (!response.ok)
+    throw new Error(`maven artifact returned HTTP ${response.status}.`);
+  return response.json();
+}
+
+cli({
+  site: "maven",
+  name: "artifact",
+  description: "Fetch Maven Central artifact version history",
+  domain: "search.maven.org",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "coordinate",
+      type: "str",
+      required: true,
+      positional: true,
+      description: 'Maven coordinate "groupId:artifactId[:version]"',
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 20,
+      description: "Max versions",
+    },
+  ],
+  columns: [
+    "groupId",
+    "artifactId",
+    "version",
+    "packaging",
+    "publishedAt",
+    "tags",
+    "url",
+  ],
+  func: async (_page, kwargs) => {
+    const coordinate = parseMavenCoordinate(kwargs.coordinate);
+    const limit = requireMavenLimit(kwargs.limit, 20);
+    const filters = [`g:${coordinate.groupId}`, `a:${coordinate.artifactId}`];
+    if (coordinate.version) filters.push(`v:${coordinate.version}`);
+    const params = new URLSearchParams({
+      q: filters.join(" AND "),
+      core: "gav",
+      rows: String(coordinate.version ? 1 : limit),
+      wt: "json",
+    });
+    const body = (await fetchMavenJson(
+      `${MAVEN_BASE}?${params.toString()}`,
+    )) as MavenBody;
+    return mapMavenArtifactRows(body, coordinate);
+  },
+});

package/src/adapters/mdn/search.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { mapMdnRows, requireMdnLimit, requireMdnLocale } from "./search.js";
+
+describe("mdn agent-facing search command", () => {
+  it("validates limit and locale", () => {
+    expect(requireMdnLimit(undefined)).toBe(10);
+    expect(requireMdnLimit("50")).toBe(50);
+    expect(() => requireMdnLimit("0")).toThrow("mdn limit must");
+    expect(requireMdnLocale("zh-CN")).toBe("zh-CN");
+    expect(() => requireMdnLocale("xx")).toThrow("not supported");
+  });
+
+  it("maps MDN search rows", () => {
+    expect(
+      mapMdnRows(
+        [
+          {
+            title: "Fetch API",
+            slug: "Web/API/Fetch_API",
+            locale: "",
+            summary: "  Promise-based\nHTTP requests. ",
+            mdn_url: "/en-US/docs/Web/API/Fetch_API",
+          },
+        ],
+        10,
+        "en-US",
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        title: "Fetch API",
+        slug: "Web/API/Fetch_API",
+        locale: "en-US",
+        summary: "Promise-based HTTP requests.",
+        url: "https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API",
+      },
+    ]);
+  });
+});