@zenalexa/unicli 0.218.1 → 0.220.0

package/src/adapters/twitter/quote.ts

@@ -0,0 +1,332 @@
+/**
+ * @owner   src/adapters/twitter/quote.ts
+ * @does    Register agent-facing Twitter quote-tweet composer automation implemented with site-specific safety checks.
+ * @needs   Logged-in x.com browser session, exact tweet URL scoping, optional image upload bridge.
+ * @feeds   surface coverage ledger and Twitter quote workflows with attachment guardrails.
+ * @breaks  X composer DOM drift or unverified quote-card rendering can post the wrong content.
+ */
+
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, extname, join, resolve } from "node:path";
+import { cli, Strategy } from "../../registry.js";
+import type { AdapterArg } from "../../types.js";
+import {
+  buildTwitterArticleScopeSource,
+  parseTwitterTweetUrl,
+} from "./tweet-url.js";
+
+const COMPOSER_FILE_INPUT_SELECTOR =
+  'input[type="file"][data-testid="fileInput"]';
+const SUPPORTED_IMAGE_EXTENSIONS = new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".webp",
+]);
+const MAX_IMAGE_SIZE_BYTES = 20 * 1024 * 1024;
+const CONTENT_TYPE_TO_EXTENSION: Record<string, string> = {
+  "image/jpeg": ".jpg",
+  "image/jpg": ".jpg",
+  "image/png": ".png",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+};
+
+interface QuoteBrowserPage {
+  goto: (url: string, opts?: Record<string, unknown>) => Promise<unknown>;
+  wait: (args: unknown) => Promise<unknown>;
+  evaluate: (script: string) => Promise<unknown>;
+  setFileInput?: (selector: string, files: string[]) => Promise<unknown>;
+}
+
+interface DownloadedImage {
+  absPath: string;
+  cleanupDir: string;
+}
+
+export function buildQuoteComposerUrl(value: unknown): string {
+  const parsed = parseTwitterTweetUrl(value);
+  return `https://x.com/compose/post?url=${encodeURIComponent(parsed.url)}`;
+}
+
+function normalizeHomePath(value: string): string {
+  return value.replace(/^~(?=$|\/)/, homedir());
+}
+
+export function resolveTwitterImagePath(value: unknown): string {
+  const raw = String(value ?? "").trim();
+  if (!raw) throw new Error("twitter quote image path cannot be empty.");
+  const absPath = resolve(normalizeHomePath(raw));
+  if (!existsSync(absPath))
+    throw new Error(`Image file not found: ${absPath}.`);
+  const ext = extname(absPath).toLowerCase();
+  if (!SUPPORTED_IMAGE_EXTENSIONS.has(ext)) {
+    throw new Error(
+      `Unsupported image format "${ext}". Supported: jpg, jpeg, png, gif, webp.`,
+    );
+  }
+  const size = statSync(absPath).size;
+  if (size > MAX_IMAGE_SIZE_BYTES) {
+    throw new Error(
+      `Image too large: ${(size / 1024 / 1024).toFixed(1)} MB (max 20 MB).`,
+    );
+  }
+  return absPath;
+}
+
+export function resolveRemoteImageExtension(
+  url: string,
+  contentType: string | null,
+): string {
+  const normalizedContentType = String(contentType ?? "")
+    .split(";")[0]
+    .trim()
+    .toLowerCase();
+  const fromContentType = CONTENT_TYPE_TO_EXTENSION[normalizedContentType];
+  if (fromContentType) return fromContentType;
+  const fromPath = extname(new URL(url).pathname).toLowerCase();
+  if (SUPPORTED_IMAGE_EXTENSIONS.has(fromPath)) return fromPath;
+  throw new Error(
+    `Unsupported remote image format "${normalizedContentType || "unknown"}". Supported: jpg, jpeg, png, gif, webp.`,
+  );
+}
+
+export async function downloadTwitterImage(
+  value: unknown,
+): Promise<DownloadedImage> {
+  const raw = String(value ?? "").trim();
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`Invalid image URL: ${raw}.`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(`Unsupported image URL protocol: ${parsed.protocol}.`);
+  }
+  const response = await fetch(parsed.toString());
+  if (!response.ok)
+    throw new Error(`Image download failed: HTTP ${response.status}.`);
+  const contentLength = Number(response.headers.get("content-length") || "0");
+  if (contentLength > MAX_IMAGE_SIZE_BYTES) {
+    throw new Error(
+      `Image too large: ${(contentLength / 1024 / 1024).toFixed(1)} MB (max 20 MB).`,
+    );
+  }
+  const ext = resolveRemoteImageExtension(
+    parsed.toString(),
+    response.headers.get("content-type"),
+  );
+  const cleanupDir = mkdtempSync(join(tmpdir(), "unicli-twitter-quote-"));
+  const absPath = join(cleanupDir, `image${ext}`);
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (buffer.byteLength > MAX_IMAGE_SIZE_BYTES) {
+    rmSync(cleanupDir, { recursive: true, force: true });
+    throw new Error(
+      `Image too large: ${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB (max 20 MB).`,
+    );
+  }
+  writeFileSync(absPath, buffer);
+  return { absPath, cleanupDir };
+}
+
+function mimeTypeForImage(absPath: string): string {
+  const ext = extname(absPath).toLowerCase();
+  if (ext === ".png") return "image/png";
+  if (ext === ".gif") return "image/gif";
+  if (ext === ".webp") return "image/webp";
+  return "image/jpeg";
+}
+
+async function attachComposerImage(
+  page: QuoteBrowserPage,
+  absImagePath: string,
+): Promise<void> {
+  let uploaded = false;
+  if (page.setFileInput) {
+    try {
+      await page.setFileInput(COMPOSER_FILE_INPUT_SELECTOR, [absImagePath]);
+      uploaded = true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!/unknown action|not supported/i.test(message)) {
+        throw new Error(`Image upload failed: ${message}`);
+      }
+    }
+  }
+  if (!uploaded) {
+    const base64 = readFileSync(absImagePath).toString("base64");
+    const upload = (await page.evaluate(`
+      (() => {
+        const input = document.querySelector(${JSON.stringify(COMPOSER_FILE_INPUT_SELECTOR)});
+        if (!input) return { ok: false, error: 'No file input found on page' };
+        const binary = atob(${JSON.stringify(base64)});
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+        const transfer = new DataTransfer();
+        const blob = new Blob([bytes], { type: ${JSON.stringify(mimeTypeForImage(absImagePath))} });
+        transfer.items.add(new File([blob], ${JSON.stringify(basename(absImagePath))}, { type: ${JSON.stringify(mimeTypeForImage(absImagePath))} }));
+        Object.defineProperty(input, 'files', { value: transfer.files, writable: false });
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        return { ok: true };
+      })()
+    `)) as { ok?: boolean; error?: string };
+    if (!upload?.ok) {
+      throw new Error(
+        `Image upload failed: ${upload?.error ?? "unknown error"}.`,
+      );
+    }
+  }
+  await page.wait(2);
+  const uploadState = (await page.evaluate(`
+    (() => {
+      const previewCount = document.querySelectorAll(
+        '[data-testid="attachments"] img, [data-testid="attachments"] video, [data-testid="tweetPhoto"]'
+      ).length;
+      const hasMedia = previewCount > 0
+        || !!document.querySelector('[data-testid="attachments"]')
+        || !!Array.from(document.querySelectorAll('button,[role="button"]')).find((el) =>
+          /remove media|remove image|remove/i.test((el.getAttribute('aria-label') || '') + ' ' + (el.textContent || ''))
+        );
+      return { ok: hasMedia, previewCount };
+    })()
+  `)) as { ok?: boolean; previewCount?: number };
+  if (!uploadState?.ok)
+    throw new Error("Image upload failed: preview did not appear.");
+}
+
+export function buildQuoteSubmitScript(text: string, tweetId: string): string {
+  return `(async () => {
+    try {
+      ${buildTwitterArticleScopeSource(tweetId)}
+      const visible = (el) => !!el && (el.offsetParent !== null || el.getClientRects().length > 0);
+      const boxes = Array.from(document.querySelectorAll('[data-testid="tweetTextarea_0"]'));
+      const box = boxes.find(visible) || boxes[0];
+      if (!box) return { ok: false, message: 'Could not find the quote composer text area. Are you logged in?' };
+      box.focus();
+      const textToInsert = ${JSON.stringify(text)};
+      if (!document.execCommand('insertText', false, textToInsert)) {
+        const transfer = new DataTransfer();
+        transfer.setData('text/plain', textToInsert);
+        box.dispatchEvent(new ClipboardEvent('paste', { clipboardData: transfer, bubbles: true, cancelable: true }));
+      }
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      let hasQuoteCard = false;
+      for (let i = 0; i < 20; i += 1) {
+        hasQuoteCard = __twHasLinkToTarget(document);
+        if (hasQuoteCard) break;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      if (!hasQuoteCard) return { ok: false, message: 'Quote target did not render in the composer. The source tweet may be deleted or restricted.' };
+      const buttons = Array.from(document.querySelectorAll('[data-testid="tweetButton"], [data-testid="tweetButtonInline"]'));
+      const button = buttons.find((el) => visible(el) && !el.disabled && el.getAttribute('aria-disabled') !== 'true');
+      if (!button) return { ok: false, message: 'Tweet button is disabled or not found.' };
+      button.click();
+      const normalize = (value) => String(value || '').replace(/\\u00a0/g, ' ').replace(/\\s+/g, ' ').trim();
+      const expectedText = normalize(textToInsert);
+      for (let i = 0; i < 30; i += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        const alerts = Array.from(document.querySelectorAll('[role="alert"], [data-testid="toast"]')).filter(visible);
+        const success = alerts.find((el) => /sent|posted|your post was sent|your tweet was sent/i.test(el.textContent || ''));
+        if (success) return { ok: true, message: 'Quote tweet posted successfully.' };
+        const failure = alerts.find((el) => /failed|error|try again|not sent|could not/i.test(el.textContent || ''));
+        if (failure) return { ok: false, message: (failure.textContent || 'Quote tweet failed to post.').trim() };
+        const visibleBoxes = Array.from(document.querySelectorAll('[data-testid="tweetTextarea_0"]')).filter(visible);
+        const composerStillHasText = visibleBoxes.some((node) => normalize(node.innerText || node.textContent || '').includes(expectedText));
+        if (!composerStillHasText) return { ok: true, message: 'Quote tweet posted successfully.' };
+      }
+      return { ok: false, message: 'Quote tweet submission did not complete before timeout.' };
+    } catch (error) {
+      return { ok: false, message: String(error?.message || error) };
+    }
+  })()`;
+}
+
+const quoteArgs: AdapterArg[] = [
+  {
+    name: "url",
+    type: "str",
+    required: true,
+    positional: true,
+    description: "Tweet URL to quote",
+    format: "uri",
+  },
+  {
+    name: "text",
+    type: "str",
+    required: true,
+    positional: true,
+    description: "Quote text",
+  },
+  { name: "image", type: "str", description: "Optional local image path" },
+  { name: "image-url", type: "str", description: "Optional remote image URL" },
+];
+
+cli({
+  site: "twitter",
+  name: "quote",
+  description: "Quote-tweet a specific tweet with text and optional image",
+  domain: "x.com",
+  strategy: Strategy.UI,
+  browser: true,
+  args: quoteArgs,
+  columns: ["status", "message", "text"],
+  func: async (page, kwargs) => {
+    if (!page || typeof page !== "object") {
+      throw new Error("Browser session required for twitter quote.");
+    }
+    if (kwargs.image && kwargs["image-url"]) {
+      throw new Error("Use either --image or --image-url, not both.");
+    }
+    const browserPage = page as QuoteBrowserPage;
+    const target = parseTwitterTweetUrl(kwargs.url);
+    const text = String(kwargs.text ?? "").trim();
+    if (!text) throw new Error("twitter quote text cannot be empty.");
+    let localImagePath: string | undefined;
+    let cleanupDir: string | undefined;
+    try {
+      if (kwargs.image) {
+        localImagePath = resolveTwitterImagePath(kwargs.image);
+      } else if (kwargs["image-url"]) {
+        const downloaded = await downloadTwitterImage(kwargs["image-url"]);
+        localImagePath = downloaded.absPath;
+        cleanupDir = downloaded.cleanupDir;
+      }
+      await browserPage.goto(buildQuoteComposerUrl(target.url), {
+        waitUntil: "load",
+        settleMs: 2500,
+      });
+      await browserPage.wait({
+        selector: '[data-testid="tweetTextarea_0"]',
+        timeout: 15,
+      });
+      if (localImagePath)
+        await attachComposerImage(browserPage, localImagePath);
+      const result = (await browserPage.evaluate(
+        buildQuoteSubmitScript(text, target.id),
+      )) as { ok?: boolean; message?: string };
+      if (result.ok) await browserPage.wait(3);
+      return [
+        {
+          status: result.ok ? "success" : "failed",
+          message: result.message || "",
+          text,
+          ...(kwargs.image ? { image: kwargs.image } : {}),
+          ...(kwargs["image-url"] ? { "image-url": kwargs["image-url"] } : {}),
+        },
+      ];
+    } finally {
+      if (cleanupDir) rmSync(cleanupDir, { recursive: true, force: true });
+    }
+  },
+});

package/src/adapters/twitter/tweet-actions.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildTweetToggleScript,
+  buildTwitterArticleScopeSource,
+  parseTwitterTweetUrl,
+} from "./tweet-actions.js";
+
+describe("twitter agent-facing tweet actions", () => {
+  it("validates full tweet URLs and extracts ids", () => {
+    expect(parseTwitterTweetUrl("https://x.com/jack/status/20")).toEqual({
+      id: "20",
+      url: "https://x.com/jack/status/20",
+    });
+    expect(
+      parseTwitterTweetUrl("https://mobile.twitter.com/i/status/123"),
+    ).toEqual({
+      id: "123",
+      url: "https://mobile.twitter.com/i/status/123",
+    });
+    expect(() =>
+      parseTwitterTweetUrl("https://example.com/jack/status/20"),
+    ).toThrow("host");
+    expect(() => parseTwitterTweetUrl("https://x.com/jack")).toThrow(
+      "extract tweet ID",
+    );
+  });
+
+  it("builds exact tweet-scoped article lookup", () => {
+    const source = buildTwitterArticleScopeSource("123");
+    expect(source).toContain('const tweetId = "123"');
+    expect(source).toContain("findTargetArticle");
+    expect(source).toContain("__twGetStatusIdFromHref(link.href) === tweetId");
+  });
+
+  it("builds unlike script with idempotent not-liked path", () => {
+    const script = buildTweetToggleScript("unlike", "123");
+    expect(script).toContain('[data-testid="unlike"]');
+    expect(script).toContain('[data-testid="like"]');
+    expect(script).toContain("Tweet is not liked (already unliked).");
+    expect(script).toContain("Tweet successfully unliked.");
+  });
+
+  it("builds retweet and unretweet scripts with confirmation selectors", () => {
+    expect(buildTweetToggleScript("retweet", "123")).toContain(
+      '[data-testid="retweetConfirm"]',
+    );
+    expect(buildTweetToggleScript("unretweet", "123")).toContain(
+      '[data-testid="unretweetConfirm"]',
+    );
+  });
+});

package/src/adapters/twitter/tweet-actions.ts

@@ -0,0 +1,187 @@
+/**
+ * @owner   src/adapters/twitter/tweet-actions.ts
+ * @does    Register agent-facing Twitter unlike, retweet, and unretweet URL actions.
+ * @needs   Browser session on x.com, exact tweet URL parsing, scoped article action buttons.
+ * @feeds   surface coverage ledger, Twitter write-action workflows, safe tweet-level UI actions.
+ * @breaks  X DOM test-id drift or weak tweet scoping can act on the wrong tweet.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { AdapterArg } from "../../types.js";
+import {
+  buildTwitterArticleScopeSource,
+  parseTwitterTweetUrl,
+} from "./tweet-url.js";
+
+export { buildTwitterArticleScopeSource, parseTwitterTweetUrl };
+
+type ToggleAction = "unlike" | "retweet" | "unretweet";
+
+const ACTIONS: Record<
+  ToggleAction,
+  {
+    activeTestId: string;
+    inactiveTestId: string;
+    confirmTestId: string;
+    alreadyMessage: string;
+    successMessage: string;
+    missingMessage: string;
+    mismatchMessage: string;
+    needsConfirm: boolean;
+  }
+> = {
+  unlike: {
+    activeTestId: "unlike",
+    inactiveTestId: "like",
+    confirmTestId: "",
+    alreadyMessage: "Tweet is not liked (already unliked).",
+    successMessage: "Tweet successfully unliked.",
+    missingMessage:
+      "Could not find the Unlike button on this tweet. Are you logged in?",
+    mismatchMessage:
+      "Unlike action was initiated but UI did not update as expected.",
+    needsConfirm: false,
+  },
+  retweet: {
+    activeTestId: "retweet",
+    inactiveTestId: "unretweet",
+    confirmTestId: "retweetConfirm",
+    alreadyMessage: "Tweet is already retweeted.",
+    successMessage: "Tweet successfully retweeted.",
+    missingMessage:
+      "Could not find the Retweet button on this tweet. Are you logged in?",
+    mismatchMessage:
+      "Retweet action was initiated but UI did not update as expected.",
+    needsConfirm: true,
+  },
+  unretweet: {
+    activeTestId: "unretweet",
+    inactiveTestId: "retweet",
+    confirmTestId: "unretweetConfirm",
+    alreadyMessage: "Tweet is not retweeted (already removed).",
+    successMessage: "Tweet successfully unretweeted.",
+    missingMessage:
+      "Could not find the Unretweet button on this tweet. Are you logged in?",
+    mismatchMessage:
+      "Unretweet action was initiated but UI did not update as expected.",
+    needsConfirm: true,
+  },
+};
+
+export function buildTweetToggleScript(
+  action: ToggleAction,
+  tweetId: string,
+): string {
+  const config = ACTIONS[action];
+  return `(async () => {
+    try {
+      ${buildTwitterArticleScopeSource(tweetId)}
+      let targetArticle = null;
+      let activeButton = null;
+      let inactiveButton = null;
+      for (let i = 0; i < 20; i++) {
+        targetArticle = findTargetArticle();
+        activeButton = targetArticle?.querySelector('[data-testid="${config.activeTestId}"]') || null;
+        inactiveButton = targetArticle?.querySelector('[data-testid="${config.inactiveTestId}"]') || null;
+        if (activeButton || inactiveButton) break;
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+      if (inactiveButton) return { ok: true, message: ${JSON.stringify(config.alreadyMessage)} };
+      if (!activeButton) return { ok: false, message: ${JSON.stringify(config.missingMessage)} };
+      activeButton.click();
+      ${
+        config.needsConfirm
+          ? `
+      let confirmButton = null;
+      for (let i = 0; i < 20; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        confirmButton = document.querySelector('[data-testid="${config.confirmTestId}"]');
+        if (confirmButton) break;
+      }
+      if (!confirmButton) return { ok: false, message: 'Confirmation menu item did not appear.' };
+      confirmButton.click();
+      `
+          : ""
+      }
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      const verifyArticle = findTargetArticle() || targetArticle;
+      const verifyButton = verifyArticle?.querySelector('[data-testid="${config.inactiveTestId}"]');
+      if (verifyButton) return { ok: true, message: ${JSON.stringify(config.successMessage)} };
+      return { ok: false, message: ${JSON.stringify(config.mismatchMessage)} };
+    } catch (error) {
+      return { ok: false, message: String(error?.message || error) };
+    }
+  })()`;
+}
+
+function tweetActionFunc(action: ToggleAction) {
+  return async (page: unknown, kwargs: Record<string, unknown>) => {
+    if (!page || typeof page !== "object") {
+      throw new Error(`Browser session required for twitter ${action}.`);
+    }
+    const target = parseTwitterTweetUrl(kwargs.url);
+    const browserPage = page as {
+      goto: (url: string) => Promise<unknown>;
+      wait: (args: unknown) => Promise<unknown>;
+      evaluate: (script: string) => Promise<{ ok?: boolean; message?: string }>;
+    };
+    await browserPage.goto(target.url);
+    await browserPage.wait({ selector: '[data-testid="primaryColumn"]' });
+    const result = await browserPage.evaluate(
+      buildTweetToggleScript(action, target.id),
+    );
+    if (result.ok) await browserPage.wait(2);
+    return [
+      {
+        status: result.ok ? "success" : "failed",
+        message: result.message || "",
+      },
+    ];
+  };
+}
+
+const tweetUrlArg: AdapterArg[] = [
+  {
+    name: "url",
+    type: "str",
+    required: true,
+    positional: true,
+    description: "Tweet URL",
+  },
+];
+
+cli({
+  site: "twitter",
+  name: "unlike",
+  description: "Twitter unlike a specific tweet",
+  domain: "x.com",
+  strategy: Strategy.UI,
+  browser: true,
+  args: tweetUrlArg,
+  columns: ["status", "message"],
+  func: tweetActionFunc("unlike"),
+});
+
+cli({
+  site: "twitter",
+  name: "retweet",
+  description: "Twitter retweet a specific tweet",
+  domain: "x.com",
+  strategy: Strategy.UI,
+  browser: true,
+  args: tweetUrlArg,
+  columns: ["status", "message"],
+  func: tweetActionFunc("retweet"),
+});
+
+cli({
+  site: "twitter",
+  name: "unretweet",
+  description: "Twitter unretweet a specific tweet",
+  domain: "x.com",
+  strategy: Strategy.UI,
+  browser: true,
+  args: tweetUrlArg,
+  columns: ["status", "message"],
+  func: tweetActionFunc("unretweet"),
+});

package/src/adapters/twitter/tweet-url.ts

@@ -0,0 +1,65 @@
+/**
+ * @owner   src/adapters/twitter/tweet-url.ts
+ * @does    Provide exact Twitter/X tweet URL parsing and DOM target scoping helpers implemented with site-specific safety checks.
+ * @needs   Full https Twitter/X status URLs and browser DOM roots containing status links.
+ * @feeds   Twitter write-action adapters and agent-facing quote/retweet safety checks.
+ * @breaks  Twitter URL shape drift or substring matching can target the wrong tweet.
+ */
+
+const TWEET_PATH_PATTERN = /^\/(?:[^/]+|i)\/status\/(\d+)\/?$/;
+const TWITTER_HOSTS = new Set(["x.com", "twitter.com"]);
+
+interface ParsedTweetUrl {
+  id: string;
+  url: string;
+}
+
+function isTwitterHost(hostname: string): boolean {
+  return (
+    TWITTER_HOSTS.has(hostname) ||
+    hostname.endsWith(".x.com") ||
+    hostname.endsWith(".twitter.com")
+  );
+}
+
+export function parseTwitterTweetUrl(value: unknown): ParsedTweetUrl {
+  const raw = String(value ?? "").trim();
+  if (!raw) throw new Error("twitter tweet URL cannot be empty.");
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`Invalid tweet URL: ${raw}.`);
+  }
+  const hostname = parsed.hostname.toLowerCase();
+  if (parsed.protocol !== "https:" || !isTwitterHost(hostname)) {
+    throw new Error(`Invalid tweet URL host: ${raw}.`);
+  }
+  const match = parsed.pathname.match(TWEET_PATH_PATTERN);
+  if (!match?.[1])
+    throw new Error(`Could not extract tweet ID from URL: ${raw}.`);
+  return { id: match[1], url: parsed.toString() };
+}
+
+export function buildTwitterArticleScopeSource(tweetId: string): string {
+  return `
+    const tweetId = ${JSON.stringify(tweetId)};
+    const __twTweetPathRe = /^\\/(?:[^/]+|i)\\/status\\/(\\d+)\\/?$/;
+    const __twIsTwitterHost = (hostname) => hostname === 'x.com'
+      || hostname === 'twitter.com'
+      || hostname.endsWith('.x.com')
+      || hostname.endsWith('.twitter.com');
+    const __twGetStatusIdFromHref = (href) => {
+      try {
+        const parsed = new URL(href, window.location.origin);
+        if (parsed.protocol !== 'https:' || !__twIsTwitterHost(parsed.hostname.toLowerCase())) return null;
+        return parsed.pathname.match(__twTweetPathRe)?.[1] || null;
+      } catch {
+        return null;
+      }
+    };
+    const __twHasLinkToTarget = (root) => Array.from(root.querySelectorAll('a[href*="/status/"]'))
+      .some((link) => __twGetStatusIdFromHref(link.href) === tweetId);
+    const findTargetArticle = () => Array.from(document.querySelectorAll('article')).find(__twHasLinkToTarget);
+  `;
+}

package/src/adapters/uisdc/news.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildExtractUisdcNewsJs,
+  mapUisdcNewsPayload,
+  requireNewsLimit,
+} from "./news.js";
+
+describe("uisdc agent-facing news command", () => {
+  it("validates limits and exposes selector extraction code", () => {
+    expect(requireNewsLimit(undefined)).toBe(20);
+    expect(requireNewsLimit("50")).toBe(50);
+    expect(() => requireNewsLimit("51")).toThrow("limit must be");
+    expect(buildExtractUisdcNewsJs()).toContain(".dubao-item");
+  });
+
+  it("maps extracted rows and rejects selector drift", () => {
+    expect(
+      mapUisdcNewsPayload(
+        {
+          ok: true,
+          rows: [
+            {
+              title: " Design  news ",
+              summary: " AI update ",
+              url: " https://www.uisdc.com/news/a ",
+            },
+          ],
+        },
+        1,
+      ),
+    ).toEqual([
+      {
+        rank: 1,
+        title: "Design news",
+        summary: "AI update",
+        url: "https://www.uisdc.com/news/a",
+      },
+    ]);
+    expect(() =>
+      mapUisdcNewsPayload({ ok: false, reason: "selector-missing" }, 10),
+    ).toThrow("selector drift");
+    expect(() => mapUisdcNewsPayload({ ok: true, rows: [] }, 10)).toThrow(
+      "no news rows",
+    );
+  });
+});