@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/facebook/marketplace-extra.ts

@@ -0,0 +1,213 @@
+/**
+ * @owner   src/adapters/facebook/marketplace-extra.ts
+ * @does    Register agent-facing Facebook Marketplace seller listings and inbox readers.
+ * @needs   Logged-in www.facebook.com browser session with Marketplace access.
+ * @feeds   surface coverage ledger and Marketplace selling/conversation workflows.
+ * @breaks  Facebook Marketplace DOM text changes, login redirects, or unavailable Marketplace account access.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+
+interface MarketplaceListingsResult {
+  authRequired?: unknown;
+  rows?: unknown;
+}
+
+interface MarketplaceListingRow {
+  title?: unknown;
+  price?: unknown;
+  status?: unknown;
+  listed?: unknown;
+  clicks?: unknown;
+  actions?: unknown;
+}
+
+interface MarketplaceInboxRow {
+  buyer?: unknown;
+  listing?: unknown;
+  snippet?: unknown;
+  time?: unknown;
+  unread?: unknown;
+}
+
+export function requireFacebookMarketplaceLimit(value: unknown): number {
+  const limit = Number(value ?? 20);
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new Error("Facebook Marketplace limit must be a positive integer.");
+  }
+  if (limit > 100) {
+    throw new Error("Facebook Marketplace limit must be <= 100.");
+  }
+  return limit;
+}
+
+function requireBrowserPage(page: unknown, command: string): IPage {
+  if (!page || typeof page !== "object") {
+    throw new Error(`Browser session required for facebook ${command}.`);
+  }
+  return page as IPage;
+}
+
+function text(value: unknown): string {
+  return value == null ? "" : String(value);
+}
+
+function readRows(
+  result: MarketplaceListingsResult,
+  command: string,
+): unknown[] {
+  if (result?.authRequired) {
+    throw new Error(
+      `Facebook Marketplace ${command} requires an active signed-in Facebook session.`,
+    );
+  }
+  const rows = Array.isArray(result?.rows) ? result.rows : [];
+  if (!rows.length) {
+    throw new Error(
+      `No Facebook Marketplace ${command} rows were visible. Check Marketplace access for this account.`,
+    );
+  }
+  return rows;
+}
+
+function marketplaceListingsScript(): string {
+  return String.raw`(() => {
+    const clean = (value) => String(value || '').replace(/\u00a0/g, ' ').replace(/\s+/g, ' ').trim();
+    const allText = document.body?.innerText || '';
+    if (/log in|sign in/i.test(allText) && !/Marketplace/i.test(allText)) {
+      return { authRequired: true, rows: [] };
+    }
+    const lines = allText.split(/\n+/).map(clean).filter(Boolean);
+    const seen = new Set();
+    const rows = [];
+    for (let index = 1; index < lines.length; index += 1) {
+      if (!/^(?:CA\$|\$)\s*\d+/.test(lines[index])) continue;
+      const title = lines[index - 1];
+      if (!title || /^(Hide|All listings|Needs attention|Marketplace|Selling)$/i.test(title)) continue;
+      if (seen.has(title)) continue;
+      seen.add(title);
+      const windowLines = lines.slice(index, index + 12);
+      const status = windowLines.find((line) => /^(Active|Sold|Pending|Draft)$/i.test(line)) || '';
+      const listed = windowLines.find((line) => /Listed on\b/i.test(line))?.replace(/^·\s*/, '') || '';
+      const clickLine = windowLines.find((line) => /clicks? on listing/i.test(line)) || '';
+      const clickMatch = clickLine.match(/([\d,.]+)\s+clicks? on listing/i);
+      const actions = windowLines.filter((line) => /^(Mark as sold|Mark as available|Relist this item|Share|Boost listing)$/i.test(line));
+      rows.push({
+        title,
+        price: lines[index],
+        status,
+        listed,
+        clicks: clickMatch ? clickMatch[1] : '',
+        actions,
+      });
+    }
+    return { authRequired: false, rows };
+  })()`;
+}
+
+function marketplaceInboxScript(): string {
+  return String.raw`(() => {
+    const clean = (value) => String(value || '').replace(/[\u00a0\u202f]/g, ' ').replace(/\s+/g, ' ').trim();
+    const timeRe = /^(?:\d{1,2}:\d{2}\s?(?:AM|PM|am|pm|上午|下午)?|Mon|Tue|Wed|Thu|Fri|Sat|Sun|Today|Yesterday|\d+[mhdw]|\d+\s*(?:min|h|d|w))$/;
+    const allText = document.body?.innerText || '';
+    if (/log in|sign in/i.test(allText) && !/Marketplace/i.test(allText)) {
+      return { authRequired: true, rows: [] };
+    }
+    const lines = allText.split(/\n+/).map(clean).filter(Boolean);
+    const rows = [];
+    const seen = new Set();
+    const skipBuyer = /^(Marketplace|Browse all|Notifications|Inbox|Marketplace access|Buying|Selling|Create new listing|Create multiple listings|Location|Categories|Vehicles|Property Rentals|All|Pending payment|Paid|To be shipped|Shipped|Cash on delivery|Completed|Filter by label)$/i;
+    for (let index = 0; index < lines.length - 2; index += 1) {
+      const buyer = lines[index];
+      const meta = lines[index + 1];
+      if (skipBuyer.test(buyer) || !/^·\s+/.test(meta)) continue;
+      const listing = meta.replace(/^·\s*/, '');
+      if (!listing || /^Within\b/i.test(listing)) continue;
+      const snippet = lines[index + 2] || '';
+      const time = timeRe.test(lines[index + 3] || '') ? lines[index + 3] : '';
+      const key = buyer + '|' + listing;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const nearby = lines.slice(Math.max(0, index - 2), index + 5).join(' ');
+      rows.push({
+        buyer,
+        listing,
+        snippet,
+        time,
+        unread: /Unread/i.test(nearby),
+      });
+    }
+    return { authRequired: false, rows };
+  })()`;
+}
+
+cli({
+  site: "facebook",
+  name: "marketplace-listings",
+  description: "List your Facebook Marketplace seller listings",
+  domain: "www.facebook.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [{ name: "limit", type: "int", default: 20 }],
+  columns: ["index", "title", "price", "status", "listed", "clicks", "actions"],
+  func: async (page, kwargs) => {
+    const p = requireBrowserPage(page, "marketplace-listings");
+    const limit = requireFacebookMarketplaceLimit(kwargs.limit);
+    await p.goto("https://www.facebook.com/marketplace/you/selling/");
+    await p.wait(4);
+    const result = (await p.evaluate(
+      marketplaceListingsScript(),
+    )) as MarketplaceListingsResult;
+    return readRows(result, "seller listings")
+      .slice(0, limit)
+      .map((item, index) => {
+        const row = item as MarketplaceListingRow;
+        return {
+          index: index + 1,
+          title: text(row.title),
+          price: text(row.price),
+          status: text(row.status),
+          listed: text(row.listed),
+          clicks: text(row.clicks),
+          actions: Array.isArray(row.actions)
+            ? row.actions.map(text).join(", ")
+            : text(row.actions),
+        };
+      });
+  },
+});
+
+cli({
+  site: "facebook",
+  name: "marketplace-inbox",
+  description:
+    "List recent Facebook Marketplace buyer and seller conversations",
+  domain: "www.facebook.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [{ name: "limit", type: "int", default: 20 }],
+  columns: ["index", "buyer", "listing", "snippet", "time", "unread"],
+  func: async (page, kwargs) => {
+    const p = requireBrowserPage(page, "marketplace-inbox");
+    const limit = requireFacebookMarketplaceLimit(kwargs.limit);
+    await p.goto("https://www.facebook.com/marketplace/inbox/");
+    await p.wait(4);
+    const result = (await p.evaluate(
+      marketplaceInboxScript(),
+    )) as MarketplaceListingsResult;
+    return readRows(result, "inbox conversations")
+      .slice(0, limit)
+      .map((item, index) => {
+        const row = item as MarketplaceInboxRow;
+        return {
+          index: index + 1,
+          buyer: text(row.buyer),
+          listing: text(row.listing),
+          snippet: text(row.snippet),
+          time: text(row.time),
+          unread: Boolean(row.unread),
+        };
+      });
+  },
+});

package/src/adapters/flathub/apps.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import {
+  joinFlathubList,
+  mapFlathubAppRow,
+  mapFlathubSearchRows,
+  pickLatestFlathubRelease,
+  requireFlathubAppId,
+  requireFlathubLimit,
+} from "./apps.js";
+
+describe("flathub agent-facing app commands", () => {
+  it("validates limits and AppStream ids", () => {
+    expect(requireFlathubLimit(undefined)).toBe(25);
+    expect(requireFlathubLimit("100")).toBe(100);
+    expect(() => requireFlathubLimit("101")).toThrow("flathub limit must");
+    expect(requireFlathubAppId("org.mozilla.firefox")).toBe(
+      "org.mozilla.firefox",
+    );
+    expect(() => requireFlathubAppId("firefox")).toThrow("not valid");
+  });
+
+  it("joins lists and picks latest releases", () => {
+    expect(joinFlathubList(["one", "two"], 1)).toBe("one, (+1)");
+    expect(
+      pickLatestFlathubRelease([
+        { version: "1.0", timestamp: 1 },
+        { version: "2.0", timestamp: "2" },
+      ]),
+    ).toEqual({ date: "1970-01-01", version: "2.0" });
+  });
+
+  it("maps search rows", () => {
+    expect(
+      mapFlathubSearchRows(
+        [
+          {
+            app_id: "org.mozilla.firefox",
+            name: "Firefox",
+            summary: "Browser",
+            developer_name: "Mozilla",
+            project_license: "MPL-2.0",
+            is_free_license: true,
+            main_categories: "Network",
+            installs_last_month: "100",
+            updated_at: 1,
+          },
+        ],
+        25,
+      ),
+    ).toMatchObject([
+      {
+        rank: 1,
+        appId: "org.mozilla.firefox",
+        name: "Firefox",
+        isFreeLicense: true,
+        installsLastMonth: 100,
+        updatedAt: "1970-01-01",
+      },
+    ]);
+  });
+
+  it("maps app rows", () => {
+    expect(
+      mapFlathubAppRow("org.mozilla.firefox", {
+        id: "org.mozilla.firefox",
+        name: "Firefox",
+        summary: "Browser",
+        developer_name: "Mozilla",
+        project_license: "MPL-2.0",
+        is_free_license: true,
+        is_eol: false,
+        categories: ["Network", "WebBrowser"],
+        keywords: ["web", "browser"],
+        releases: [{ version: "1.0", timestamp: 1 }],
+        urls: { homepage: "https://www.mozilla.org" },
+      }),
+    ).toMatchObject({
+      appId: "org.mozilla.firefox",
+      categories: "Network, WebBrowser",
+      latestVersion: "1.0",
+      homepage: "https://www.mozilla.org",
+      url: "https://flathub.org/apps/org.mozilla.firefox",
+    });
+  });
+});

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