@zenalexa/unicli 0.223.4 → 0.224.1

package/src/adapters/twitter/lists-extra.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveCommand } from "../../registry.js";
+import {
+  buildTwitterTweetExtractionScript,
+  extractTweets,
+} from "./lists-extra.js";
+import type { IPage } from "../../types.js";
+
+class FakeTwitterPage implements Partial<IPage> {
+  public readonly navigatedUrls: string[] = [];
+  public autoScrollCalls = 0;
+  private evaluateCalls = 0;
+
+  async goto(url: string): Promise<void> {
+    this.navigatedUrls.push(url);
+  }
+
+  async wait(): Promise<void> {}
+
+  async autoScroll(): Promise<void> {
+    this.autoScrollCalls += 1;
+  }
+
+  async evaluate(): Promise<unknown> {
+    this.evaluateCalls += 1;
+    if (this.evaluateCalls === 1) {
+      return {
+        url: this.navigatedUrls.at(-1),
+        title: "X",
+        text: "alice: hello",
+      };
+    }
+    return [
+      {
+        id: "1",
+        author: "alice",
+        text: "hello",
+        likes: "2",
+        retweets: "3",
+        views: "4",
+        url: "https://x.com/alice/status/1",
+      },
+    ];
+  }
+}
+
+describe("twitter user timeline commands", () => {
+  it("registers natural aliases for reading a user's tweets", () => {
+    for (const name of ["tweets", "user-tweets", "user-timeline"]) {
+      expect(resolveCommand("twitter", name)?.command.columns).toEqual([
+        "id",
+        "author",
+        "text",
+        "likes",
+        "retweets",
+        "views",
+        "url",
+      ]);
+    }
+  });
+
+  it("normalizes @handles before navigating to a user timeline", async () => {
+    // REASON: IPage is the browser boundary; this fake records navigation and
+    // returns DOM-extracted rows without mocking owned adapter code.
+    const page = new FakeTwitterPage() as IPage;
+
+    await extractTweets(page, "https://x.com/@yetone", 1, "user-tweets");
+
+    expect(page.navigatedUrls).toEqual(["https://x.com/yetone"]);
+    expect(page.autoScrollCalls).toBe(1);
+  });
+
+  it("extracts /i/status tweet links without treating i as the author", () => {
+    const article = {
+      querySelector(selector: string) {
+        if (selector === 'a[href*="/status/"]') {
+          return { getAttribute: () => "/i/status/123" };
+        }
+        if (selector === '[data-testid="User-Name"]') {
+          return { textContent: "Alice @alice" };
+        }
+        return { textContent: "" };
+      },
+      querySelectorAll(selector: string) {
+        if (selector === '[data-testid="tweetText"]') {
+          return [{ textContent: "hello" }];
+        }
+        return [];
+      },
+    };
+    const previousDocument = globalThis.document;
+    Object.defineProperty(globalThis, "document", {
+      configurable: true,
+      value: { querySelectorAll: () => [article] },
+    });
+
+    try {
+      const rows = Function(`return ${buildTwitterTweetExtractionScript(1)}`)();
+
+      expect(rows).toEqual([
+        expect.objectContaining({
+          id: "123",
+          author: "alice",
+          url: "https://x.com/i/status/123",
+        }),
+      ]);
+    } finally {
+      Object.defineProperty(globalThis, "document", {
+        configurable: true,
+        value: previousDocument,
+      });
+    }
+  });
+});

package/src/adapters/twitter/lists-extra.ts

@@ -1,27 +1,113 @@
+/**
+ * @owner   src/adapters/twitter/lists-extra.ts
+ * @does    Register browser-backed Twitter/X user timeline and list membership commands.
+ * @needs   User-owned browser session on x.com, Twitter page readability checks, shared browser DOM extraction helpers.
+ * @feeds   twitter.tweets, twitter.user-tweets, twitter.user-timeline, twitter.list-tweets, twitter.list-add, twitter.list-remove.
+ * @breaks  X/Twitter DOM or URL-shape drift can make timeline rows empty or misidentify tweet authors.
+ * @invariants User timeline commands normalize @handles and emit the standard tweet row shape.
+ * @side-effects Navigates the browser to X/Twitter profile, list, and list-management pages.
+ * @perf     Scrolls at most two viewport batches for read commands.
+ * @concurrency Browser session state is shared by the command runtime.
+ * @test     src/adapters/twitter/lists-extra.test.ts
+ * @stability stable
+ * @since    2026-05-27
+ */
+
 import { cli, Strategy } from "../../registry.js";
 import type { IPage } from "../../types.js";
 import { clickFirst, intArg, js, str } from "../_shared/browser-tools.js";
+import { socialEmptyError } from "../../social/browser-errors.js";
+import { assertTwitterReadable, gotoTwitterPage } from "./browser-state.js";
+
+const TWEET_COLUMNS = [
+  "id",
+  "author",
+  "text",
+  "likes",
+  "retweets",
+  "views",
+  "url",
+];
+
+function normalizeTwitterPageUrl(url: string): string {
+  const parsed = new URL(url);
+  const parts = parsed.pathname.split("/");
+  if (parts[1]?.startsWith("@")) {
+    parts[1] = parts[1].slice(1);
+    parsed.pathname = parts.join("/");
+  }
+  return parsed.toString().replace(/\/$/, "");
+}
+
+function twitterUserTimelineUrl(user: string): string {
+  return `https://x.com/${encodeURIComponent(user.replace(/^@/, ""))}`;
+}
 
-async function extractTweets(
+export function buildTwitterTweetExtractionScript(limit: number): string {
+  return `(() => {
+    const clean = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+    const rows = [];
+    const seen = new Set();
+    for (const article of document.querySelectorAll('article[data-testid="tweet"]')) {
+      const link = article.querySelector('a[href*="/status/"]');
+      const href = link?.getAttribute('href') || '';
+      const iStatusMatch = href.match(/^\\/i\\/status\\/(\\d+)/);
+      const userStatusMatch = href.match(/^\\/(?!i\\/status\\/)([^/?#]+)\\/status\\/(\\d+)/);
+      const id = iStatusMatch?.[1] || userStatusMatch?.[2] || '';
+      if (!id || seen.has(id)) continue;
+      seen.add(id);
+      const fallbackAuthor = clean(article.querySelector('[data-testid="User-Name"]')?.textContent || '').split('@').pop() || 'unknown';
+      const author = userStatusMatch ? decodeURIComponent(userStatusMatch[1]) : fallbackAuthor;
+      const text = Array.from(article.querySelectorAll('[data-testid="tweetText"]'))
+        .map((el) => clean(el.textContent || ''))
+        .filter(Boolean)
+        .join('\\n');
+      const metric = (name) => clean(article.querySelector('[data-testid="' + name + '"]')?.textContent || '');
+      if (!text) continue;
+      rows.push({
+        id,
+        author,
+        text,
+        likes: metric('like'),
+        retweets: metric('retweet'),
+        views: clean(article.querySelector('a[href$="/analytics"]')?.textContent || ''),
+        url: 'https://x.com' + href.split('?')[0],
+      });
+      if (rows.length >= ${js(limit)}) break;
+    }
+    return rows;
+  })()`;
+}
+
+export async function extractTweets(
   page: IPage,
   url: string,
   limit: number,
+  command: string,
 ): Promise<Record<string, unknown>[]> {
-  await page.goto(url, { settleMs: 2500 });
-  const rows = await page.evaluate(`(() => {
-    const tweets = [...document.querySelectorAll('article[data-testid="tweet"]')];
-    return tweets.map((article) => {
-      const user = article.querySelector('[data-testid="User-Name"]')?.textContent || '';
-      const text = article.querySelector('[data-testid="tweetText"]')?.textContent || '';
-      const link = [...article.querySelectorAll('a[href*="/status/"]')].pop();
-      return {
-        author: user.replace(/\\s+/g, ' ').trim(),
-        text: text.replace(/\\s+/g, ' ').trim(),
-        url: link ? new URL(link.getAttribute('href') || '', location.href).href : ''
-      };
-    }).filter((row) => row.text).slice(0, ${js(limit)});
-  })()`);
-  return Array.isArray(rows) ? (rows as Record<string, unknown>[]) : [];
+  await gotoTwitterPage(page, normalizeTwitterPageUrl(url), command);
+  await page.autoScroll({ maxScrolls: 2, delay: 1000 });
+  await assertTwitterReadable(page, command);
+  const rows = await page.evaluate(buildTwitterTweetExtractionScript(limit));
+  const parsedRows = Array.isArray(rows)
+    ? (rows as Record<string, unknown>[])
+    : [];
+  if (parsedRows.length > 0) return parsedRows;
+  throw socialEmptyError(
+    "twitter",
+    command,
+    `Twitter/X ${command} loaded no parseable tweets from ${url}.`,
+  );
+}
+
+function userTimelineFunc(command: string) {
+  return async (page: unknown, kwargs: Record<string, unknown>) =>
+    extractTweets(
+      page as IPage,
+      twitterUserTimelineUrl(str(kwargs.user)),
+      intArg(kwargs.limit, 20, 100),
+      command,
+    );
 }
 
 cli({
@@ -35,19 +121,47 @@ cli({
     { name: "user", type: "str", required: true, positional: true },
     { name: "limit", type: "int", default: 20 },
   ],
-  columns: ["author", "text", "url"],
-  func: async (page, kwargs) =>
-    extractTweets(
-      page as IPage,
-      `https://x.com/${encodeURIComponent(str(kwargs.user).replace(/^@/, ""))}`,
-      intArg(kwargs.limit, 20, 100),
-    ),
+  columns: TWEET_COLUMNS,
+  socialCapabilities: ["read", "author", "user_content"],
+  func: userTimelineFunc("tweets"),
+});
+
+cli({
+  site: "twitter",
+  name: "user-tweets",
+  description: "Read recent tweets from a Twitter/X user profile",
+  domain: "x.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: "user", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: TWEET_COLUMNS,
+  socialCapabilities: ["read", "author", "user_content"],
+  func: userTimelineFunc("user-tweets"),
+});
+
+cli({
+  site: "twitter",
+  name: "user-timeline",
+  description: "Read a Twitter/X user's tweet timeline",
+  domain: "x.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: "user", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: TWEET_COLUMNS,
+  socialCapabilities: ["read", "author", "user_content"],
+  func: userTimelineFunc("user-timeline"),
 });
 
 cli({
   site: "twitter",
   name: "list-tweets",
-  description: "Read tweets from a Twitter/X list",
+  description: "Read tweets from a Twitter/X list timeline",
   domain: "x.com",
   strategy: Strategy.COOKIE,
   browser: true,
@@ -55,13 +169,19 @@ cli({
     { name: "list", type: "str", required: true, positional: true },
     { name: "limit", type: "int", default: 20 },
   ],
-  columns: ["author", "text", "url"],
+  columns: TWEET_COLUMNS,
+  socialCapabilities: ["read", "lists", "user_content"],
   func: async (page, kwargs) => {
     const list = str(kwargs.list);
     const url = list.startsWith("http")
       ? list
       : `https://x.com/i/lists/${encodeURIComponent(list)}`;
-    return extractTweets(page as IPage, url, intArg(kwargs.limit, 20, 100));
+    return extractTweets(
+      page as IPage,
+      url,
+      intArg(kwargs.limit, 20, 100),
+      "list-tweets",
+    );
   },
 });
 

package/src/adapters/twitter/post.ts

@@ -15,6 +15,7 @@ cli({
   description: "Post a new tweet",
   domain: "x.com",
   strategy: Strategy.COOKIE,
+  socialCapabilities: ["write_post"],
   args: [
     {
       name: "text",

package/src/adapters/twitter/thread.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
 
-import { normalizeTwitterThreadRows } from "./thread.js";
+import {
+  normalizeTwitterThreadRows,
+  resolveTwitterThreadTweetId,
+} from "./thread.js";
 
 describe("normalizeTwitterThreadRows", () => {
   it("adds normalized comment hierarchy fields to thread rows", () => {
@@ -41,3 +45,23 @@ describe("normalizeTwitterThreadRows", () => {
     ]);
   });
 });
+
+describe("twitter thread and comments commands", () => {
+  it("accepts either a numeric tweet id or a Twitter/X status URL", () => {
+    expect(resolveTwitterThreadTweetId("123")).toBe("123");
+    expect(
+      resolveTwitterThreadTweetId(
+        "https://x.com/alice/status/2040254679301718161?s=20",
+      ),
+    ).toBe("2040254679301718161");
+  });
+
+  it("registers a comments command for tweet replies", () => {
+    const comments = resolveCommand("twitter", "comments")?.command;
+
+    expect(comments?.adapterArgs?.map((arg) => arg.name)).toEqual(["url"]);
+    expect(comments?.socialCapabilities).toEqual(
+      expect.arrayContaining(["comments", "comment_replies"]),
+    );
+  });
+});

package/src/adapters/twitter/thread.ts

@@ -1,14 +1,27 @@
 /**
- * Twitter thread — fetch a tweet and its conversation thread via GraphQL TweetDetail.
+ * @owner   src/adapters/twitter/thread.ts
+ * @does    Register Twitter/X tweet thread and comments commands over the GraphQL TweetDetail operation.
+ * @needs   Twitter cookie auth with ct0/auth_token, TweetDetail GraphQL operation, tweet ID or status URL input.
+ * @feeds   twitter.thread, twitter.comments, social.comments twitter.
+ * @breaks  TweetDetail query-id drift or invalid tweet target parsing returns empty comment trees.
+ * @invariants Thread rows preserve root/reply hierarchy fields over the standard tweet row shape.
+ * @side-effects Performs authenticated read requests to x.com.
+ * @perf     One GraphQL request per command invocation.
+ * @concurrency Stateless per invocation.
+ * @test     src/adapters/twitter/thread.test.ts
+ * @stability stable
+ * @since    2026-05-27
  */
 
 import { cli } from "../../registry.js";
 import { Strategy } from "../../types.js";
+import type { SocialCapability } from "../../types.js";
 import {
   twitterFetch,
   FEATURES,
   extractTweetsFromInstructions,
 } from "./client.js";
+import { parseTwitterTweetUrl } from "./tweet-url.js";
 
 const QUERY_ID = "B9_KmbkLhXt6jRwGjJrweg";
 const ENDPOINT = "TweetDetail";
@@ -40,64 +53,103 @@ export function normalizeTwitterThreadRows(
   });
 }
 
+export function resolveTwitterThreadTweetId(value: unknown): string {
+  const raw = String(value ?? "").trim();
+  if (/^\d+$/.test(raw)) return raw;
+  return parseTwitterTweetUrl(raw).id;
+}
+
+async function fetchTwitterThread(
+  tweetTarget: unknown,
+): Promise<
+  Array<TweetRow & { parent_id: string; depth: number; path: string }>
+> {
+  const tweetId = resolveTwitterThreadTweetId(tweetTarget);
+
+  const variables = {
+    focalTweetId: tweetId,
+    with_rux_injections: false,
+    includePromotedContent: false,
+    withCommunity: true,
+    withQuickPromoteEligibilityTweetFields: false,
+    withBirdwatchNotes: true,
+    withVoice: true,
+    withV2Timeline: true,
+  };
+
+  const data = (await twitterFetch(
+    ENDPOINT,
+    QUERY_ID,
+    variables,
+    FEATURES,
+  )) as Record<string, unknown>;
+
+  // Navigate: data.threaded_conversation_with_injections_v2.instructions
+  const root = data.data as Record<string, unknown> | undefined;
+  const conversation = root?.threaded_conversation_with_injections_v2 as
+    | Record<string, unknown>
+    | undefined;
+  const instructions = (conversation?.instructions as unknown[]) ?? [];
+
+  return normalizeTwitterThreadRows(
+    tweetId,
+    extractTweetsFromInstructions(instructions),
+  );
+}
+
+const THREAD_SOCIAL_CAPABILITIES: SocialCapability[] = [
+  "read",
+  "comments",
+  "comment_replies",
+];
+
+const THREAD_COLUMNS = [
+  "id",
+  "parent_id",
+  "author",
+  "text",
+  "likes",
+  "retweets",
+  "views",
+  "url",
+  "depth",
+  "path",
+];
+
 cli({
   site: "twitter",
   name: "thread",
   description: "Get a tweet and its conversation thread",
   domain: "x.com",
   strategy: Strategy.COOKIE,
-  socialCapabilities: ["read", "comments", "comment_replies"],
+  socialCapabilities: THREAD_SOCIAL_CAPABILITIES,
   args: [
     {
       name: "tweet_id",
       required: true,
       positional: true,
-      description: "Tweet ID (numeric)",
+      description: "Tweet ID or Twitter/X status URL",
     },
   ],
-  columns: [
-    "id",
-    "parent_id",
-    "author",
-    "text",
-    "likes",
-    "retweets",
-    "views",
-    "url",
-    "depth",
-    "path",
-  ],
-  func: async (_page, kwargs) => {
-    const tweetId = String(kwargs.tweet_id);
-
-    const variables = {
-      focalTweetId: tweetId,
-      with_rux_injections: false,
-      includePromotedContent: false,
-      withCommunity: true,
-      withQuickPromoteEligibilityTweetFields: false,
-      withBirdwatchNotes: true,
-      withVoice: true,
-      withV2Timeline: true,
-    };
-
-    const data = (await twitterFetch(
-      ENDPOINT,
-      QUERY_ID,
-      variables,
-      FEATURES,
-    )) as Record<string, unknown>;
-
-    // Navigate: data.threaded_conversation_with_injections_v2.instructions
-    const root = data.data as Record<string, unknown> | undefined;
-    const conversation = root?.threaded_conversation_with_injections_v2 as
-      | Record<string, unknown>
-      | undefined;
-    const instructions = (conversation?.instructions as unknown[]) ?? [];
+  columns: THREAD_COLUMNS,
+  func: async (_page, kwargs) => fetchTwitterThread(kwargs.tweet_id),
+});
 
-    return normalizeTwitterThreadRows(
-      tweetId,
-      extractTweetsFromInstructions(instructions),
-    );
-  },
+cli({
+  site: "twitter",
+  name: "comments",
+  description: "Get replies/comments for a Twitter/X tweet",
+  domain: "x.com",
+  strategy: Strategy.COOKIE,
+  socialCapabilities: THREAD_SOCIAL_CAPABILITIES,
+  args: [
+    {
+      name: "url",
+      required: true,
+      positional: true,
+      description: "Tweet ID or Twitter/X status URL",
+    },
+  ],
+  columns: THREAD_COLUMNS,
+  func: async (_page, kwargs) => fetchTwitterThread(kwargs.url),
 });