birdclaw 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,30 @@
 # CHANGELOG
 
-All notable changes to this project will be documented in this file.
+## Unreleased
+
+## 0.3.0 - 2026-05-05
+
+### Added
+
+- Add research mode for turning bookmarked Twitter threads into Markdown briefs, with shared `xurl`/`bird` tweet lookup fallback for thread expansion. Thanks @anupamchugh.
+- Add live home timeline and mention-thread sync commands so local triage can pull current `bird` context into the SQLite store.
+- Add search snippets for tweet and DM results, including deterministic DM snippets when multiple messages in a conversation match. Thanks @mvanhorn.
+- Add `--min-likes` and `--quality-reason` controls for tweet search quality filtering. Thanks @mvanhorn.
+- Store Twitter following counts on profiles and include them in JSONL backups.
+
+### Changed
+
+- Use the native TypeScript preview compiler for the `typecheck` script.
+- Refresh TypeScript and related development dependencies.
+
+### Fixed
+
+- Use the existing Twitter web cookie fallback as the final `auto` transport for block and unblock actions. Thanks @pejmanjohn.
+- Resolve the `bird` transport from `PATH` before falling back to the local development checkout. Thanks @vyctorbrzezowski.
+- Stabilize the presenter timestamp test across local time zones. Thanks @pejmanjohn.
+- Clean up the DMs route render test so CI does not leave React work running after jsdom teardown.
+- Allow Playwright e2e runs to use an alternate local port when `3000` is already occupied.
+- Replace maintainer-local documentation links with repo-relative links and align the setup docs with the Node version file. Thanks @stainlu.
 
 ## 0.2.1 - 2026-04-27
 

package/README.md

@@ -203,7 +203,7 @@ pnpm cli search tweets --liked --limit 20 --json
 pnpm cli search tweets --bookmarked --limit 20 --json
 ```
 
-### Sync likes and bookmarks
+### Sync likes, bookmarks, and home timeline
 
 `auto` tries `xurl` first, then falls back to `bird`. Use `bird` directly when the API path is unavailable for the account/token you have locally.
 
@@ -211,6 +211,8 @@ pnpm cli search tweets --bookmarked --limit 20 --json
 pnpm cli sync likes --mode auto --limit 100 --refresh --json
 pnpm cli sync bookmarks --mode auto --limit 100 --refresh --json
 pnpm cli sync bookmarks --mode bird --all --max-pages 5 --limit 100 --refresh --json
+pnpm cli sync timeline --limit 100 --refresh --json
+pnpm cli sync mention-threads --limit 30 --delay-ms 1500 --timeout-ms 15000 --json
 ```
 
 ### Export mentions for agents
@@ -257,7 +259,16 @@ Notes:
 - `actions.transport` accepts `auto`, `bird`, or `xurl`
 - `bird` mode uses your local `bird` CLI and caches its mentions output into birdclaw's canonical store
 - filters still work in `xurl` mode; filtered payloads are rebuilt from the local canonical store after sync
-- `sync likes` and `sync bookmarks` store live results in the same local timeline table, so `search tweets --liked` and `search tweets --bookmarked` work across archive and live data
+- `sync likes`, `sync bookmarks`, `sync timeline`, and `sync mention-threads` store live results in the same local timeline table, so `search tweets`, `search tweets --liked`, and `search tweets --bookmarked` work across archive and live data
+
+### Research bookmarks and threads
+
+`birdclaw research` turns bookmarked tweets into a markdown brief with local thread expansion, live ancestor lookup when needed, and extracted links/handles:
+
+```bash
+birdclaw research "codex" --limit 20 --thread-depth 10 --json
+birdclaw research --account acct_primary --out ~/research/codex.md
+```
 
 ### Search and triage DMs
 
@@ -293,7 +304,7 @@ pnpm cli unban @amelia --account acct_primary --transport bird --json
 Notes:
 
 - `ban` / `unban` accept `--transport auto|bird|xurl`
-- `auto` tries `bird` first, then falls back to `xurl` when bird fails
+- `auto` tries `bird` first, then falls back to `xurl`, then `x-web` cookie-backed block/unblock when both fail
 - forced `xurl` writes still verify through `bird status` before sqlite changes
 - Twitter still rejects pure OAuth2 block writes, so `auto` is the safe default for block/unblock
 - `blocks import` accepts newline-delimited blocklists with comments and markdown bullets
@@ -487,10 +498,10 @@ GitHub Actions runs:
 - `pnpm build`
 - `pnpm e2e`
 
-Workflow: [ci.yml](/Users/steipete/Projects/birdclaw/.github/workflows/ci.yml)
+Workflow: [ci.yml](.github/workflows/ci.yml)
 
 ## Docs
 
-- [spec.md](/Users/steipete/Projects/birdclaw/docs/spec.md)
-- [cli.md](/Users/steipete/Projects/birdclaw/docs/cli.md)
-- [data-architecture.md](/Users/steipete/Projects/birdclaw/docs/data-architecture.md)
+- [spec.md](docs/spec.md)
+- [cli.md](docs/cli.md)
+- [data-architecture.md](docs/data-architecture.md)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "birdclaw",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"description": "Local Twitter memory in SQLite for archives, DMs, likes, bookmarks, and moderation",
 	"homepage": "https://github.com/steipete/birdclaw#readme",
 	"license": "MIT",
@@ -53,22 +53,22 @@
 		"@tailwindcss/vite": "^4.2.4",
 		"@tanstack/devtools-vite": "0.6.0",
 		"@tanstack/react-devtools": "0.10.2",
-		"@tanstack/react-router": "1.168.24",
+		"@tanstack/react-router": "1.169.1",
 		"@tanstack/react-router-devtools": "1.166.13",
 		"@tanstack/react-router-ssr-query": "1.166.12",
-		"@tanstack/react-start": "1.167.49",
-		"@tanstack/router-plugin": "^1.167.27",
+		"@tanstack/react-start": "1.167.61",
+		"@tanstack/router-plugin": "^1.167.32",
 		"@vitejs/plugin-react": "^6.0.1",
 		"better-sqlite3": "^12.9.0",
 		"commander": "^14.0.3",
-		"kysely": "^0.28.16",
-		"lucide-react": "^1.11.0",
+		"kysely": "^0.28.17",
+		"lucide-react": "^1.14.0",
 		"react": "^19.2.5",
 		"react-dom": "^19.2.5",
 		"tailwindcss": "^4.2.4",
 		"tsx": "^4.21.0",
 		"vite": "^8.0.10",
-		"zod": "^4.3.6"
+		"zod": "^4.4.2"
 	},
 	"devDependencies": {
 		"@playwright/test": "^1.59.1",
@@ -80,10 +80,11 @@
 		"@types/node": "^25.6.0",
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
+		"@typescript/native-preview": "7.0.0-dev.20260505.1",
 		"@vitest/coverage-v8": "^4.1.5",
-		"jsdom": "^29.1.0",
-		"oxfmt": "^0.46.0",
-		"oxlint": "^1.61.0",
+		"jsdom": "^29.1.1",
+		"oxfmt": "^0.47.0",
+		"oxlint": "^1.62.0",
 		"typescript": "^6.0.3",
 		"vitest": "^4.1.5"
 	},

package/playwright.config.ts

@@ -2,6 +2,8 @@ import path from "node:path";
 import { defineConfig, devices } from "@playwright/test";
 
 const testHome = path.join(process.cwd(), ".playwright-home");
+const port = process.env.BIRDCLAW_PLAYWRIGHT_PORT ?? "3000";
+const baseURL = `http://127.0.0.1:${port}`;
 
 export default defineConfig({
 	testDir: "./playwright",
@@ -9,7 +11,7 @@ export default defineConfig({
 	retries: 0,
 	workers: 1,
 	use: {
-		baseURL: "http://127.0.0.1:3000",
+		baseURL,
 		trace: "on-first-retry",
 	},
 	projects: [
@@ -20,10 +22,11 @@ export default defineConfig({
 	],
 	webServer: {
 		command: "node ./scripts/start-test-server.mjs",
-		url: "http://127.0.0.1:3000",
+		url: baseURL,
 		reuseExistingServer: false,
 		timeout: 120000,
 		env: {
+			BIRDCLAW_PLAYWRIGHT_PORT: port,
 			BIRDCLAW_HOME: testHome,
 			BIRDCLAW_DISABLE_LIVE_WRITES: "1",
 		},

package/src/cli.ts

@@ -29,6 +29,7 @@ import {
 } from "#/lib/config";
 import { syncDirectMessagesViaCachedBird } from "#/lib/dms-live";
 import { listInboxItems, scoreInbox } from "#/lib/inbox";
+import { syncMentionThreads } from "#/lib/mention-threads-live";
 import { exportMentionItems } from "#/lib/mentions-export";
 import {
 	exportMentionsViaCachedBird,
@@ -36,6 +37,7 @@ import {
 } from "#/lib/mentions-live";
 import { hydrateProfilesFromX } from "#/lib/profile-hydration";
 import { inspectProfileReplies } from "#/lib/profile-replies";
+import { runResearchMode } from "#/lib/research";
 import {
 	createDmReply,
 	createPost,
@@ -48,6 +50,7 @@ import {
 	syncTimelineCollection,
 	type TimelineCollectionMode,
 } from "#/lib/timeline-collections-live";
+import { syncHomeTimeline } from "#/lib/timeline-live";
 
 const program = new Command();
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -63,6 +66,35 @@ function print(data: unknown, asJson: boolean) {
 	console.log(data);
 }
 
+function printError(error: string) {
+	console.error(JSON.stringify({ error }));
+}
+
+function parseNonNegativeIntegerOption(
+	value: string | undefined,
+	option: string,
+) {
+	if (value === undefined) {
+		return undefined;
+	}
+
+	const trimmed = value.trim();
+	if (!/^\d+$/.test(trimmed)) {
+		printError(`${option} must be a non-negative integer`);
+		process.exitCode = 1;
+		return undefined;
+	}
+
+	const parsed = Number.parseInt(trimmed, 10);
+	if (!Number.isSafeInteger(parsed)) {
+		printError(`${option} must be a non-negative integer`);
+		process.exitCode = 1;
+		return undefined;
+	}
+
+	return parsed;
+}
+
 function resolveActionOptions(options: { transport?: string }) {
 	return {
 		transport: options.transport as ActionsTransport | undefined,
@@ -171,10 +203,23 @@ searchCommand
 	.option("--until <date>", "Include tweets created before this date")
 	.option("--originals-only", "Exclude authored replies that start with @")
 	.option("--hide-low-quality", "Hide RTs, tiny replies, and link-only noise")
+	.option(
+		"--min-likes <n>",
+		"Override the low-quality like threshold (default 50)",
+	)
+	.option("--quality-reason", "Include qualityReason on each row")
 	.option("--liked", "Only liked tweets")
 	.option("--bookmarked", "Only bookmarked tweets")
 	.option("--limit <n>", "Limit results", "20")
 	.action(async (query, options) => {
+		const minLikes = parseNonNegativeIntegerOption(
+			options.minLikes,
+			"--min-likes",
+		);
+		if (options.minLikes !== undefined && minLikes === undefined) {
+			return;
+		}
+
 		await autoUpdateBeforeRead();
 		const replyFilter = options.replied
 			? "replied"
@@ -189,6 +234,8 @@ searchCommand
 			until: options.until,
 			includeReplies: !options.originalsOnly,
 			qualityFilter: options.hideLowQuality ? "summary" : "all",
+			lowQualityThreshold: minLikes,
+			includeQualityReason: Boolean(options.qualityReason),
 			likedOnly: Boolean(options.liked),
 			bookmarkedOnly: Boolean(options.bookmarked),
 			limit: Number(options.limit),
@@ -236,6 +283,28 @@ searchCommand
 		print(items, program.opts().json ?? false);
 	});
 
+program
+	.command("research [query]")
+	.description("Build a markdown research brief from bookmarked threads")
+	.option("--account <accountId>", "Account id")
+	.option("--limit <n>", "Seed bookmark limit", "20")
+	.option("--thread-depth <n>", "Maximum ancestor walk depth", "10")
+	.option("--out <path>", "Write the markdown brief to a file")
+	.action(async (query, options) => {
+		await autoUpdateBeforeRead();
+		const report = await runResearchMode({
+			account: options.account,
+			query,
+			limit: Number(options.limit),
+			maxThreadDepth: Number(options.threadDepth),
+			outPath: options.out,
+		});
+		print(
+			program.opts().json ? report : report.markdown,
+			program.opts().json ?? false,
+		);
+	});
+
 const mentionsCommand = program
 	.command("mentions")
 	.description("Export local mention tweets for scripts and agents");
@@ -325,6 +394,50 @@ const syncCommand = program
 	.command("sync")
 	.description("Refresh live Twitter collections into the local store");
 
+syncCommand
+	.command("timeline")
+	.description("Refresh live home timeline through bird")
+	.option("--account <accountId>", "Account id")
+	.option("--limit <n>", "Result limit", "100")
+	.option("--for-you", 'Fetch "For You" instead of chronological Following')
+	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+	.option("--refresh", "Bypass live-cache freshness window")
+	.action(async (options) => {
+		const result = await syncHomeTimeline({
+			account: options.account,
+			limit: Number(options.limit),
+			following: !options.forYou,
+			refresh: Boolean(options.refresh),
+			cacheTtlMs: Number(options.cacheTtl) * 1000,
+		});
+		await autoSyncAfterWrite();
+		print(result, true);
+	});
+
+syncCommand
+	.command("mention-threads")
+	.description(
+		"Fetch tweet conversation context for recent mentions through bird",
+	)
+	.option("--account <accountId>", "Account id")
+	.option("--limit <n>", "Recent mentions to inspect", "30")
+	.option("--delay-ms <n>", "Delay between thread fetches", "1500")
+	.option("--timeout-ms <n>", "Per-thread timeout", "15000")
+	.option("--all", "Fetch all retrievable thread pages")
+	.option("--max-pages <n>", "Stop after N pages")
+	.action(async (options) => {
+		const result = await syncMentionThreads({
+			account: options.account,
+			limit: Number(options.limit),
+			delayMs: Number(options.delayMs),
+			timeoutMs: Number(options.timeoutMs),
+			all: Boolean(options.all),
+			maxPages: options.maxPages ? Number(options.maxPages) : undefined,
+		});
+		await autoSyncAfterWrite();
+		print(result, true);
+	});
+
 for (const kind of ["likes", "bookmarks"] as const) {
 	syncCommand
 		.command(kind)

package/src/lib/actions-transport.ts

@@ -9,7 +9,9 @@ import { type ActionsTransport, resolveActionsTransport } from "./config";
 import type {
 	ModerationAction,
 	ModerationActionTransportResult,
+	ModerationTransportKind,
 } from "./types";
+import { blockUserViaXWeb, unblockUserViaXWeb } from "./x-web";
 import {
 	blockUserViaXurl,
 	lookupAuthenticatedUser,
@@ -27,7 +29,7 @@ interface RunActionParams {
 	transport?: string;
 }
 
-function normalizeFailure(transport: "bird" | "xurl", output: string) {
+function normalizeFailure(transport: ModerationTransportKind, output: string) {
 	return `${transport}: ${output}`;
 }
 
@@ -133,6 +135,37 @@ async function runXurlAction(
 	};
 }
 
+async function runXWebAction(
+	action: ModerationAction,
+	targetUserId?: string,
+): Promise<ActionTransportResult> {
+	if (action !== "block" && action !== "unblock") {
+		return {
+			ok: false,
+			output: `x-web does not support ${action}`,
+			transport: "x-web",
+		};
+	}
+
+	if (!targetUserId) {
+		return {
+			ok: false,
+			output: "missing target user id for x-web transport",
+			transport: "x-web",
+		};
+	}
+
+	const result =
+		action === "block"
+			? await blockUserViaXWeb(targetUserId)
+			: await unblockUserViaXWeb(targetUserId);
+
+	return {
+		...result,
+		transport: "x-web",
+	};
+}
+
 export async function runModerationAction({
 	action,
 	query,
@@ -160,6 +193,30 @@ export async function runModerationAction({
 		};
 	}
 
+	if (action === "block" || action === "unblock") {
+		const xWebResult = await runXWebAction(action, targetUserId);
+		if (xWebResult.ok) {
+			return {
+				...xWebResult,
+				output: [
+					xWebResult.output,
+					`falling back after ${normalizeFailure("bird", birdResult.output)}`,
+					`falling back after ${normalizeFailure("xurl", xurlResult.output)}`,
+				].join("\n"),
+			};
+		}
+
+		return {
+			ok: false,
+			output: [
+				normalizeFailure("bird", birdResult.output),
+				normalizeFailure("xurl", xurlResult.output),
+				normalizeFailure("x-web", xWebResult.output),
+			].join("\n"),
+			transport: xWebResult.transport,
+		};
+	}
+
 	return {
 		ok: false,
 		output: [

package/src/lib/archive-import.ts

@@ -476,6 +476,7 @@ export async function importArchive(
 			displayName: string;
 			bio: string;
 			followersCount: number;
+			followingCount: number;
 			avatarHue: number;
 			createdAt: string;
 		}
@@ -500,6 +501,7 @@ export async function importArchive(
 		displayName: accountPayload.displayName,
 		bio: accountPayload.bio,
 		followersCount: 0,
+		followingCount: 0,
 		avatarHue: 18,
 		createdAt: accountPayload.createdAt,
 	};
@@ -583,6 +585,7 @@ export async function importArchive(
 							conversationName || `Group DM ${externalParticipantIds.length}`,
 						bio: `Group DM with ${externalParticipantIds.length} participants`,
 						followersCount: 0,
+						followingCount: 0,
 						avatarHue: 220,
 						createdAt: accountPayload.createdAt,
 					});
@@ -598,6 +601,7 @@ export async function importArchive(
 						displayName: inferred.displayName,
 						bio: `Imported from archive user ${otherUserId}`,
 						followersCount: 0,
+						followingCount: 0,
 						avatarHue: 210,
 						createdAt: accountPayload.createdAt,
 					});
@@ -626,6 +630,7 @@ export async function importArchive(
 								displayName: inferred.displayName,
 								bio: `Imported from archive user ${senderId}`,
 								followersCount: 0,
+								followingCount: 0,
 								avatarHue: 240,
 								createdAt: accountPayload.createdAt,
 							});
@@ -745,6 +750,7 @@ export async function importArchive(
 			displayName: "Unknown",
 			bio: "Imported from archive collection metadata",
 			followersCount: 0,
+			followingCount: 0,
 			avatarHue: 210,
 			createdAt: accountPayload.createdAt,
 		});
@@ -758,8 +764,8 @@ export async function importArchive(
     values (?, ?, ?, ?, ?, 1, ?)
   `);
 	const insertProfile = db.prepare(`
-    insert into profiles (id, handle, display_name, bio, followers_count, avatar_hue, avatar_url, created_at)
-    values (?, ?, ?, ?, ?, ?, ?, ?)
+    insert into profiles (id, handle, display_name, bio, followers_count, following_count, avatar_hue, avatar_url, created_at)
+    values (?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
 	const insertTweet = db.prepare(`
     insert into tweets (
@@ -811,6 +817,7 @@ export async function importArchive(
 				profile.displayName,
 				profile.bio,
 				profile.followersCount,
+				profile.followingCount,
 				profile.avatarHue,
 				null,
 				profile.createdAt,

package/src/lib/backup.ts

@@ -188,7 +188,7 @@ function getExportRowSets(db: Database.Database) {
 			rows: rowsForQuery(
 				db,
 				`
-        select id, handle, display_name, bio, followers_count, avatar_hue, avatar_url, created_at
+        select id, handle, display_name, bio, followers_count, following_count, avatar_hue, avatar_url, created_at
         from profiles
         order by id
         `,
@@ -1002,13 +1002,14 @@ export async function importBackup({
 			db,
 			`
       insert into profiles (
-        id, handle, display_name, bio, followers_count, avatar_hue, avatar_url, created_at
-      ) values (?, ?, ?, ?, ?, ?, ?, ?)
+        id, handle, display_name, bio, followers_count, following_count, avatar_hue, avatar_url, created_at
+      ) values (?, ?, ?, ?, ?, coalesce(?, 0), ?, ?, ?)
       on conflict(id) do update set
         handle = coalesce(nullif(excluded.handle, ''), profiles.handle),
         display_name = coalesce(nullif(excluded.display_name, ''), profiles.display_name),
         bio = coalesce(nullif(excluded.bio, ''), profiles.bio),
         followers_count = max(profiles.followers_count, excluded.followers_count),
+        following_count = max(profiles.following_count, excluded.following_count),
         avatar_hue = case when profiles.avatar_hue = 0 then excluded.avatar_hue else profiles.avatar_hue end,
         avatar_url = coalesce(excluded.avatar_url, profiles.avatar_url),
         created_at = min(profiles.created_at, excluded.created_at)
@@ -1020,6 +1021,7 @@ export async function importBackup({
 				"display_name",
 				"bio",
 				"followers_count",
+				"following_count",
 				"avatar_hue",
 				"avatar_url",
 				"created_at",

package/src/lib/bird-actions.ts

@@ -80,6 +80,7 @@ function toBirdLookupUser(payload: Record<string, unknown>): XurlMentionUser {
 	}
 
 	const followersCount = Number(user.followersCount ?? 0);
+	const followingCount = Number(user.followingCount);
 	return {
 		id,
 		name:
@@ -95,6 +96,9 @@ function toBirdLookupUser(payload: Record<string, unknown>): XurlMentionUser {
 				: undefined,
 		public_metrics: {
 			followers_count: Number.isFinite(followersCount) ? followersCount : 0,
+			...(Number.isFinite(followingCount)
+				? { following_count: followingCount }
+				: {}),
 		},
 		created_at: typeof user.createdAt === "string" ? user.createdAt : undefined,
 	};