birdclaw 0.2.1 → 0.4.0

package/src/lib/bird.ts

@@ -1,10 +1,15 @@
 import { execFile } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { promisify } from "node:util";
 import { getBirdCommand } from "./config";
 import type {
 	XurlMentionData,
 	XurlMentionsResponse,
 	XurlMentionUser,
+	XurlReferencedTweet,
+	XurlTweetsResponse,
 } from "./types";
 
 const execFileAsync = promisify(execFile);
@@ -28,7 +33,9 @@ interface BirdTweetItem {
 	retweetCount?: number;
 	likeCount?: number;
 	conversationId?: string;
-	inReplyToStatusId?: string;
+	inReplyToStatusId?: string | null;
+	quotedStatusId?: string | null;
+	quotedTweet?: { id?: string | null } | null;
 	author?: BirdTweetAuthor;
 	authorId?: string;
 	media?: BirdTweetMedia[];
@@ -66,6 +73,31 @@ export interface BirdDmsResponse {
 	events: BirdDmEvent[];
 }
 
+interface BirdUserOverviewPayload {
+	user?: {
+		id?: string;
+		username?: string;
+		name?: string;
+		description?: string;
+		location?: string;
+		url?: string;
+		verified?: boolean;
+		verifiedType?: string;
+		verified_type?: string;
+		followersCount?: number;
+		followingCount?: number;
+		profileImageUrl?: string;
+		createdAt?: string;
+		entities?: Record<string, unknown>;
+		affiliation?: Record<string, unknown>;
+	};
+}
+
+interface BirdProfilesPayload {
+	users?: NonNullable<BirdUserOverviewPayload["user"]>[];
+	errors?: Array<{ target?: string; error?: string }>;
+}
+
 function toIsoTimestamp(value: string) {
 	const parsed = new Date(value);
 	if (Number.isNaN(parsed.getTime())) {
@@ -140,6 +172,51 @@ function parseBirdJson(stdout: string) {
 	}
 }
 
+function formatBirdCommandError(error: unknown, birdCommand: string) {
+	if (
+		error instanceof Error &&
+		"code" in error &&
+		(error as { code?: unknown }).code === "ENOENT"
+	) {
+		return new Error(
+			`bird CLI not found at ${birdCommand}. Install @steipete/bird or set BIRDCLAW_BIRD_COMMAND / mentions.birdCommand to a valid bird binary.`,
+		);
+	}
+
+	return error;
+}
+
+function isUnsupportedBirdOptionError(error: unknown, option: string) {
+	if (!error || typeof error !== "object") {
+		return false;
+	}
+	const text = [
+		error instanceof Error ? error.message : "",
+		"stderr" in error && typeof error.stderr === "string" ? error.stderr : "",
+		"stdout" in error && typeof error.stdout === "string" ? error.stdout : "",
+	].join("\n");
+	return text.includes(option) && /unknown option|error:/i.test(text);
+}
+
+async function runBirdJsonCommand(args: string[], timeoutMs?: number) {
+	const tempDir = mkdtempSync(join(tmpdir(), "birdclaw-bird-"));
+	const stdoutPath = join(tempDir, "stdout.json");
+	const birdCommand = getBirdCommand();
+	try {
+		const shellScript = 'out="$1"; shift; exec "$@" > "$out"';
+		await execFileAsync(
+			"/bin/bash",
+			["-lc", shellScript, "birdclaw-bird", stdoutPath, birdCommand, ...args],
+			{ maxBuffer: BIRD_JSON_MAX_BUFFER_BYTES, timeout: timeoutMs },
+		);
+		return readFileSync(stdoutPath, "utf8");
+	} catch (error) {
+		throw formatBirdCommandError(error, birdCommand);
+	} finally {
+		rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+
 function getBirdTweetItems(payload: unknown, command: string) {
 	if (Array.isArray(payload)) {
 		return payload as BirdTweetItem[];
@@ -156,6 +233,17 @@ function getBirdTweetItems(payload: unknown, command: string) {
 	throw new Error(`bird ${command} returned unexpected JSON`);
 }
 
+function getBirdTweetItem(payload: unknown, command: string) {
+	if (payload && typeof payload === "object") {
+		const record = payload as { id?: unknown };
+		if (typeof record.id === "string" && record.id.length > 0) {
+			return payload as BirdTweetItem;
+		}
+	}
+
+	throw new Error(`bird ${command} returned unexpected JSON`);
+}
+
 function toMediaEntities(media: BirdTweetMedia[] | undefined) {
 	if (!Array.isArray(media) || media.length === 0) {
 		return undefined;
@@ -175,6 +263,25 @@ function toMediaEntities(media: BirdTweetMedia[] | undefined) {
 	};
 }
 
+function toReferencedTweets(item: BirdTweetItem) {
+	const references: XurlReferencedTweet[] = [];
+	if (typeof item.inReplyToStatusId === "string" && item.inReplyToStatusId) {
+		references.push({ type: "replied_to", id: item.inReplyToStatusId });
+	}
+
+	const quotedTweetId =
+		typeof item.quotedStatusId === "string" && item.quotedStatusId
+			? item.quotedStatusId
+			: typeof item.quotedTweet?.id === "string" && item.quotedTweet.id
+				? item.quotedTweet.id
+				: null;
+	if (quotedTweetId) {
+		references.push({ type: "quoted", id: quotedTweetId });
+	}
+
+	return references.length > 0 ? references : undefined;
+}
+
 function normalizeBirdTweets(items: BirdTweetItem[]): XurlMentionsResponse {
 	const users = new Map<string, XurlMentionUser>();
 	const data = items.map((item): XurlMentionData => {
@@ -196,6 +303,7 @@ function normalizeBirdTweets(items: BirdTweetItem[]): XurlMentionsResponse {
 			created_at: toIsoTimestamp(item.createdAt),
 			conversation_id: item.conversationId ?? item.id,
 			entities: toMediaEntities(item.media),
+			referenced_tweets: toReferencedTweets(item),
 			public_metrics: {
 				reply_count: Number(item.replyCount ?? 0),
 				retweet_count: Number(item.retweetCount ?? 0),
@@ -224,12 +332,12 @@ export async function listMentionsViaBird({
 }: {
 	maxResults: number;
 }): Promise<XurlMentionsResponse> {
-	const birdCommand = getBirdCommand();
-	const { stdout } = await execFileAsync(
-		birdCommand,
-		["mentions", "-n", String(maxResults), "--json"],
-		{ maxBuffer: BIRD_JSON_MAX_BUFFER_BYTES },
-	);
+	const stdout = await runBirdJsonCommand([
+		"mentions",
+		"-n",
+		String(maxResults),
+		"--json",
+	]);
 	const payload = parseBirdJson(stdout);
 
 	return normalizeBirdTweets(getBirdTweetItems(payload, "mentions"));
@@ -246,7 +354,6 @@ async function listTweetsViaBirdCommand({
 	all?: boolean;
 	maxPages?: number;
 }): Promise<XurlMentionsResponse> {
-	const birdCommand = getBirdCommand();
 	const args = [command, "-n", String(maxResults), "--json"];
 	if (all) {
 		args.push("--all");
@@ -254,9 +361,7 @@ async function listTweetsViaBirdCommand({
 	if (maxPages !== undefined) {
 		args.push("--max-pages", String(maxPages));
 	}
-	const { stdout } = await execFileAsync(birdCommand, args, {
-		maxBuffer: BIRD_JSON_MAX_BUFFER_BYTES,
-	});
+	const stdout = await runBirdJsonCommand(args);
 	const payload = parseBirdJson(stdout);
 
 	return normalizeBirdTweets(getBirdTweetItems(payload, command));
@@ -296,17 +401,75 @@ export async function listBookmarkedTweetsViaBird({
 	});
 }
 
+export async function lookupTweetsByIdsViaBird(
+	ids: string[],
+): Promise<XurlTweetsResponse> {
+	if (ids.length === 0) {
+		return { data: [] };
+	}
+
+	const tweets = await Promise.all(
+		ids.map(async (id) => {
+			const stdout = await runBirdJsonCommand(["read", id, "--json"]);
+			return getBirdTweetItem(parseBirdJson(stdout), "read");
+		}),
+	);
+
+	return normalizeBirdTweets(tweets);
+}
+
+export async function listHomeTimelineViaBird({
+	maxResults,
+	following = true,
+}: {
+	maxResults: number;
+	following?: boolean;
+}): Promise<XurlMentionsResponse> {
+	const args = ["home", "-n", String(maxResults), "--json"];
+	if (following) {
+		args.push("--following");
+	}
+	const stdout = await runBirdJsonCommand(args);
+	const payload = parseBirdJson(stdout);
+
+	return normalizeBirdTweets(getBirdTweetItems(payload, "home"));
+}
+
+export async function listThreadViaBird({
+	tweetId,
+	all,
+	maxPages,
+	timeoutMs,
+}: {
+	tweetId: string;
+	all?: boolean;
+	maxPages?: number;
+	timeoutMs?: number;
+}): Promise<XurlMentionsResponse> {
+	const args = ["thread", tweetId, "--json"];
+	if (all) {
+		args.push("--all");
+	}
+	if (maxPages !== undefined) {
+		args.push("--max-pages", String(maxPages));
+	}
+	const stdout = await runBirdJsonCommand(args, timeoutMs);
+	const payload = parseBirdJson(stdout);
+
+	return normalizeBirdTweets(getBirdTweetItems(payload, "thread"));
+}
+
 export async function listDirectMessagesViaBird({
 	maxResults,
 }: {
 	maxResults: number;
 }): Promise<BirdDmsResponse> {
-	const birdCommand = getBirdCommand();
-	const { stdout } = await execFileAsync(
-		birdCommand,
-		["dms", "-n", String(maxResults), "--json"],
-		{ maxBuffer: BIRD_JSON_MAX_BUFFER_BYTES },
-	);
+	const stdout = await runBirdJsonCommand([
+		"dms",
+		"-n",
+		String(maxResults),
+		"--json",
+	]);
 	const payload = parseBirdJson(stdout);
 	if (
 		!payload ||
@@ -320,3 +483,155 @@ export async function listDirectMessagesViaBird({
 
 	return payload as BirdDmsResponse;
 }
+
+export async function lookupProfileViaBird(
+	usernameOrId: string,
+): Promise<XurlMentionUser | null> {
+	const target = usernameOrId.trim().replace(/^@/, "");
+	if (!target) {
+		return null;
+	}
+
+	let stdout: string;
+	try {
+		stdout = await runBirdJsonCommand([
+			"user",
+			target,
+			"--json",
+			"--profile-only",
+		]);
+	} catch (error) {
+		if (!isUnsupportedBirdOptionError(error, "--profile-only")) {
+			throw error;
+		}
+		stdout = await runBirdJsonCommand([
+			"user",
+			target,
+			"--json",
+			"--count",
+			"1",
+		]);
+	}
+	const payload = parseBirdJson(stdout) as BirdUserOverviewPayload;
+	return toXurlMentionUser(payload.user);
+}
+
+function toXurlMentionUser(
+	user: BirdUserOverviewPayload["user"],
+): XurlMentionUser | null {
+	if (!user?.id || !user.username) {
+		return null;
+	}
+
+	return {
+		id: String(user.id),
+		username: String(user.username).replace(/^@/, ""),
+		name: String(user.name ?? user.username),
+		description:
+			typeof user.description === "string" ? user.description : undefined,
+		location: typeof user.location === "string" ? user.location : undefined,
+		url: typeof user.url === "string" ? user.url : undefined,
+		verified: typeof user.verified === "boolean" ? user.verified : undefined,
+		verified_type:
+			typeof user.verifiedType === "string"
+				? user.verifiedType
+				: typeof user.verified_type === "string"
+					? user.verified_type
+					: undefined,
+		profile_image_url:
+			typeof user.profileImageUrl === "string"
+				? user.profileImageUrl
+				: undefined,
+		entities:
+			user.entities && typeof user.entities === "object"
+				? user.entities
+				: undefined,
+		affiliation:
+			user.affiliation && typeof user.affiliation === "object"
+				? user.affiliation
+				: undefined,
+		created_at: typeof user.createdAt === "string" ? user.createdAt : undefined,
+		public_metrics: {
+			followers_count: Number(user.followersCount ?? 0),
+			following_count: Number(user.followingCount ?? 0),
+		},
+	};
+}
+
+export async function lookupProfilesViaBird(
+	usernameOrIds: string[],
+): Promise<
+	Array<{ target: string; user: XurlMentionUser | null; error?: string }>
+> {
+	const targets = Array.from(
+		new Set(
+			usernameOrIds
+				.map((target) => target.trim().replace(/^@/, ""))
+				.filter((target) => target.length > 0),
+		),
+	);
+	if (targets.length === 0) {
+		return [];
+	}
+
+	try {
+		const stdout = await runBirdJsonCommand(["profiles", ...targets, "--json"]);
+		const payload = parseBirdJson(stdout) as BirdProfilesPayload;
+		const users = (payload.users ?? [])
+			.map(toXurlMentionUser)
+			.filter((user): user is XurlMentionUser => Boolean(user));
+		const byTarget = new Map<string, XurlMentionUser>();
+		for (const user of users) {
+			byTarget.set(String(user.id), user);
+			byTarget.set(user.username.toLowerCase(), user);
+		}
+		const errors = new Map(
+			(payload.errors ?? []).map((item) => [
+				String(item.target ?? "")
+					.replace(/^@/, "")
+					.toLowerCase(),
+				item.error ?? "Unknown error",
+			]),
+		);
+		return targets.map((target) => ({
+			target,
+			user: byTarget.get(target.toLowerCase()) ?? null,
+			...(errors.has(target.toLowerCase())
+				? { error: errors.get(target.toLowerCase()) }
+				: {}),
+		}));
+	} catch (error) {
+		if (!isUnsupportedBirdOptionError(error, "profiles")) {
+			throw error;
+		}
+		return Promise.all(
+			targets.map(async (target) => {
+				try {
+					return { target, user: await lookupProfileViaBird(target) };
+				} catch (lookupError) {
+					return {
+						target,
+						user: null,
+						error:
+							lookupError instanceof Error
+								? lookupError.message
+								: String(lookupError),
+					};
+				}
+			}),
+		);
+	}
+}
+
+export const __test__ = {
+	toIsoTimestamp,
+	escapeJsonStringControlChars,
+	parseBirdJson,
+	formatBirdCommandError,
+	isUnsupportedBirdOptionError,
+	getBirdTweetItems,
+	getBirdTweetItem,
+	toMediaEntities,
+	toReferencedTweets,
+	normalizeBirdTweets,
+};

package/src/lib/blocks.ts

@@ -1,4 +1,4 @@
-import type Database from "better-sqlite3";
+import type { Database } from "./sqlite";
 import { getNativeDb } from "./db";
 import {
 	getAccountHandle,
@@ -16,7 +16,7 @@ function remoteBlockSyncDisabled() {
 }
 
 function upsertRemoteBlock(
-	db: Database.Database,
+	db: Database,
 	accountId: string,
 	profileId: string,
 	blockedAt: string,
@@ -33,7 +33,7 @@ function upsertRemoteBlock(
 }
 
 function pruneRemoteBlocks(
-	db: Database.Database,
+	db: Database,
 	accountId: string,
 	profileIds: string[],
 ) {

package/src/lib/bookmark-sync-job.ts

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
-import type Database from "better-sqlite3";
+import type { Database } from "./sqlite";
 import { maybeAutoSyncBackup, type BackupAutoUpdateResult } from "./backup";
 import { ensureBirdclawDirs, getBirdclawPaths } from "./config";
 import { getNativeDb } from "./db";
@@ -31,7 +31,7 @@ export interface BookmarkSyncJobOptions {
 	cacheTtlMs?: number;
 	logPath?: string;
 	lockPath?: string;
-	db?: Database.Database;
+	db?: Database;
 }
 
 export interface BookmarkSyncAuditEntry {
@@ -117,7 +117,7 @@ export function getDefaultBookmarkSyncLockPath() {
 	return path.join(getBirdclawPaths().rootDir, "locks", "bookmarks-sync.lock");
 }
 
-function countBookmarks(db: Database.Database) {
+function countBookmarks(db: Database) {
 	const row = db
 		.prepare("select count(*) as count from tweet_collections where kind = ?")
 		.get("bookmarks") as { count: number };

package/src/lib/config.ts

@@ -1,4 +1,10 @@
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import {
+	accessSync,
+	constants,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+} from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
@@ -128,6 +134,28 @@ export function resolveActionsTransport(
 	return "auto";
 }
 
+function findCommandOnPath(command: string) {
+	const pathValue = process.env.PATH;
+	if (!pathValue) {
+		return undefined;
+	}
+
+	for (const directory of pathValue.split(path.delimiter)) {
+		if (!directory) {
+			continue;
+		}
+		const candidate = path.join(directory, command);
+		try {
+			accessSync(candidate, constants.X_OK);
+			return candidate;
+		} catch {
+			continue;
+		}
+	}
+
+	return undefined;
+}
+
 export function getBirdCommand() {
 	const envCommand = process.env.BIRDCLAW_BIRD_COMMAND?.trim();
 	if (envCommand) {
@@ -139,6 +167,11 @@ export function getBirdCommand() {
 		return configuredCommand;
 	}
 
+	const pathCommand = findCommandOnPath("bird");
+	if (pathCommand) {
+		return pathCommand;
+	}
+
 	return path.join(os.homedir(), "Projects", "bird", "bird");
 }