birdclaw 0.1.1 → 0.2.1

package/src/cli.ts

@@ -8,6 +8,18 @@ import { Command } from "commander";
 import { registerModerationCommands } from "#/cli-moderation";
 import { findArchives } from "#/lib/archive-finder";
 import { importArchive } from "#/lib/archive-import";
+import {
+	exportBackup,
+	importBackup,
+	maybeAutoSyncBackup,
+	maybeAutoUpdateBackup,
+	syncBackup,
+	validateBackup,
+} from "#/lib/backup";
+import {
+	installBookmarkSyncLaunchAgent,
+	runBookmarkSyncJob,
+} from "#/lib/bookmark-sync-job";
 import { importBlocklist } from "#/lib/blocklist";
 import {
 	type ActionsTransport,
@@ -32,6 +44,10 @@ import {
 	listDmConversations,
 	listTimelineItems,
 } from "#/lib/queries";
+import {
+	syncTimelineCollection,
+	type TimelineCollectionMode,
+} from "#/lib/timeline-collections-live";
 
 const program = new Command();
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -53,9 +69,23 @@ function resolveActionOptions(options: { transport?: string }) {
 	};
 }
 
+async function autoUpdateBeforeRead() {
+	const result = await maybeAutoUpdateBackup();
+	if (!result.ok) {
+		console.error(`birdclaw backup auto-sync failed: ${result.error}`);
+	}
+}
+
+async function autoSyncAfterWrite() {
+	const result = await maybeAutoSyncBackup();
+	if (!result.ok) {
+		console.error(`birdclaw backup sync failed: ${result.error}`);
+	}
+}
+
 program
 	.name("birdclaw")
-	.description("Local-first X workspace")
+	.description("Local-first Twitter workspace")
 	.version(packageVersion.version ?? "0.0.0")
 	.option("--json", "Emit JSON output");
 
@@ -88,7 +118,7 @@ program
 
 program
 	.command("archive find")
-	.description("Find likely X/Twitter archives on disk")
+	.description("Find likely Twitter archives on disk")
 	.action(async () => {
 		const items = await findArchives();
 		print(items, program.opts().json ?? false);
@@ -100,7 +130,7 @@ const importCommand = program
 
 importCommand
 	.command("archive [archivePath]")
-	.description("Import an X/Twitter archive into the local SQLite store")
+	.description("Import a Twitter archive into the local SQLite store")
 	.action(async (archivePath) => {
 		let resolvedArchivePath = archivePath;
 		if (!resolvedArchivePath) {
@@ -115,14 +145,16 @@ importCommand
 		}
 
 		const result = await importArchive(resolvedArchivePath);
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
 importCommand
 	.command("hydrate-profiles")
-	.description("Backfill archive-imported profiles from live X metadata")
+	.description("Backfill archive-imported profiles from live Twitter metadata")
 	.action(async () => {
 		const result = await hydrateProfilesFromX();
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
@@ -139,8 +171,11 @@ 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("--liked", "Only liked tweets")
+	.option("--bookmarked", "Only bookmarked tweets")
 	.option("--limit <n>", "Limit results", "20")
-	.action((query, options) => {
+	.action(async (query, options) => {
+		await autoUpdateBeforeRead();
 		const replyFilter = options.replied
 			? "replied"
 			: options.unreplied
@@ -154,6 +189,8 @@ searchCommand
 			until: options.until,
 			includeReplies: !options.originalsOnly,
 			qualityFilter: options.hideLowQuality ? "summary" : "all",
+			likedOnly: Boolean(options.liked),
+			bookmarkedOnly: Boolean(options.bookmarked),
 			limit: Number(options.limit),
 		});
 		print(items, program.opts().json ?? false);
@@ -170,7 +207,8 @@ searchCommand
 	.option("--replied", "Only replied threads")
 	.option("--unreplied", "Only unreplied threads")
 	.option("--limit <n>", "Limit results", "20")
-	.action((query, options) => {
+	.action(async (query, options) => {
+		await autoUpdateBeforeRead();
 		const replyFilter = options.replied
 			? "replied"
 			: options.unreplied
@@ -218,6 +256,7 @@ mentionsCommand
 	)
 	.option("--limit <n>", "Limit results", "20")
 	.action(async (query, options) => {
+		await autoUpdateBeforeRead();
 		const replyFilter = options.replied
 			? "replied"
 			: options.unreplied
@@ -236,6 +275,7 @@ mentionsCommand
 				refresh: Boolean(options.refresh),
 				cacheTtlMs: Number(options.cacheTtl) * 1000,
 			});
+			await autoSyncAfterWrite();
 			print(payload, true);
 			return;
 		}
@@ -250,6 +290,7 @@ mentionsCommand
 				refresh: Boolean(options.refresh),
 				cacheTtlMs: Number(options.cacheTtl) * 1000,
 			});
+			await autoSyncAfterWrite();
 			print(payload, true);
 			return;
 		}
@@ -280,6 +321,108 @@ profilesCommand
 
 const dmsCommand = program.command("dms").description("Direct messages");
 
+const syncCommand = program
+	.command("sync")
+	.description("Refresh live Twitter collections into the local store");
+
+for (const kind of ["likes", "bookmarks"] as const) {
+	syncCommand
+		.command(kind)
+		.description(`Refresh live ${kind} through xurl or bird`)
+		.option("--account <accountId>", "Account id")
+		.option("--mode <mode>", "auto, xurl, or bird", "auto")
+		.option("--limit <n>", "Per-page/result limit", "20")
+		.option("--all", "Fetch every retrievable page")
+		.option("--max-pages <n>", "Stop after N pages when using --all")
+		.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+		.option("--refresh", "Bypass live-cache freshness window")
+		.action(async (options) => {
+			const result = await syncTimelineCollection({
+				kind,
+				account: options.account,
+				mode: options.mode as TimelineCollectionMode,
+				limit: Number(options.limit),
+				all: Boolean(options.all) || options.maxPages !== undefined,
+				maxPages: options.maxPages ? Number(options.maxPages) : undefined,
+				refresh: Boolean(options.refresh),
+				cacheTtlMs: Number(options.cacheTtl) * 1000,
+			});
+			await autoSyncAfterWrite();
+			print(result, true);
+		});
+}
+
+const jobsCommand = program
+	.command("jobs")
+	.description("Run and install background Birdclaw jobs");
+
+jobsCommand
+	.command("sync-bookmarks")
+	.description("Refresh live bookmarks and append a JSONL audit entry")
+	.option("--account <accountId>", "Account id")
+	.option("--mode <mode>", "auto, xurl, or bird", "auto")
+	.option("--limit <n>", "Per-page/result limit", "100")
+	.option("--all", "Fetch every retrievable page")
+	.option("--max-pages <n>", "Stop after N pages", "5")
+	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+	.option("--refresh", "Bypass live-cache freshness window")
+	.option("--log <path>", "Audit JSONL path")
+	.action(async (options) => {
+		const result = await runBookmarkSyncJob({
+			account: options.account,
+			mode: options.mode as TimelineCollectionMode,
+			limit: Number(options.limit),
+			all: Boolean(options.all) || options.maxPages !== undefined,
+			maxPages: options.all ? undefined : Number(options.maxPages),
+			refresh: Boolean(options.refresh),
+			cacheTtlMs: Number(options.cacheTtl) * 1000,
+			logPath: options.log,
+		});
+		print(result, true);
+		if (!result.ok) {
+			process.exitCode = 1;
+		}
+	});
+
+jobsCommand
+	.command("install-bookmarks-launchd")
+	.description("Install a LaunchAgent that runs bookmark sync every 3 hours")
+	.option("--label <label>", "LaunchAgent label")
+	.option("--interval-seconds <seconds>", "Launch interval", "10800")
+	.option("--program <path>", "birdclaw executable or command", "birdclaw")
+	.option("--mode <mode>", "auto, xurl, or bird", "auto")
+	.option("--limit <n>", "Per-page/result limit", "100")
+	.option("--all", "Fetch every retrievable page")
+	.option("--max-pages <n>", "Stop after N pages", "5")
+	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+	.option("--no-refresh", "Allow live-cache reuse")
+	.option("--log <path>", "Audit JSONL path")
+	.option("--env-file <path>", "Shell env file to source before running")
+	.option("--stdout <path>", "launchd stdout path")
+	.option("--stderr <path>", "launchd stderr path")
+	.option("--launch-agents-dir <path>", "LaunchAgents directory")
+	.option("--no-load", "Write plist without loading it")
+	.action(async (options) => {
+		const result = await installBookmarkSyncLaunchAgent({
+			label: options.label,
+			intervalSeconds: Number(options.intervalSeconds),
+			program: options.program,
+			mode: options.mode as TimelineCollectionMode,
+			limit: Number(options.limit),
+			all: Boolean(options.all) || options.maxPages !== undefined,
+			maxPages: options.all ? undefined : Number(options.maxPages),
+			refresh: options.refresh,
+			cacheTtlSeconds: Number(options.cacheTtl),
+			logPath: options.log,
+			envFile: options.envFile,
+			stdoutPath: options.stdout,
+			stderrPath: options.stderr,
+			launchAgentsDir: options.launchAgentsDir,
+			load: options.load,
+		});
+		print(result, true);
+	});
+
 dmsCommand
 	.command("list")
 	.option("--account <accountId>", "Account id")
@@ -307,6 +450,9 @@ dmsCommand
 				refresh: true,
 				cacheTtlMs: Number(options.cacheTtl) * 1000,
 			});
+			await autoSyncAfterWrite();
+		} else {
+			await autoUpdateBeforeRead();
 		}
 		const items = listDmConversations({
 			account: options.account,
@@ -344,6 +490,7 @@ dmsCommand
 			refresh: Boolean(options.refresh),
 			cacheTtlMs: Number(options.cacheTtl) * 1000,
 		});
+		await autoSyncAfterWrite();
 		print(result, true);
 	});
 
@@ -364,6 +511,7 @@ composeCommand
 	.option("--account <accountId>", "Account id", "acct_primary")
 	.action(async (text, options) => {
 		const result = await createPost(options.account, text);
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
@@ -372,6 +520,7 @@ composeCommand
 	.option("--account <accountId>", "Account id", "acct_primary")
 	.action(async (tweetId, text, options) => {
 		const result = await createTweetReply(options.account, tweetId, text);
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
@@ -380,6 +529,7 @@ composeCommand
 	.description("Reply inside an existing DM conversation")
 	.action(async (conversationId, text) => {
 		const result = await createDmReply(conversationId, text);
+		await autoSyncAfterWrite();
 		print(result, program.opts().json ?? false);
 	});
 
@@ -391,6 +541,7 @@ program
 	.option("--score", "Score top items with OpenAI before listing")
 	.option("--limit <n>", "Limit results", "20")
 	.action(async (options) => {
+		await autoUpdateBeforeRead();
 		const kind =
 			options.kind === "mentions" || options.kind === "dms"
 				? options.kind
@@ -400,6 +551,7 @@ program
 				kind,
 				limit: Number(options.limit),
 			});
+			await autoSyncAfterWrite();
 		}
 		print(
 			listInboxItems({
@@ -416,6 +568,7 @@ program
 	.command("db stats")
 	.description("Show local storage and dataset stats")
 	.action(async () => {
+		await autoUpdateBeforeRead();
 		const meta = await getQueryEnvelope();
 		const paths = getBirdclawPaths();
 		print(
@@ -428,10 +581,82 @@ program
 		);
 	});
 
+const backupCommand = program
+	.command("backup")
+	.description("Export, import, and validate Git-friendly text backups");
+
+backupCommand
+	.command("export")
+	.description("Export canonical JSONL backup shards")
+	.requiredOption("--repo <path>", "Backup repository/path")
+	.option("--commit", "Create a git commit in the backup repo")
+	.option("--push", "Push the backup repo after committing")
+	.option(
+		"--message <message>",
+		"Git commit message",
+		"archive: update birdclaw backup",
+	)
+	.option("--no-validate", "Skip post-export validation")
+	.action(async (options) => {
+		const result = await exportBackup({
+			repoPath: options.repo,
+			commit: Boolean(options.commit) || Boolean(options.push),
+			push: Boolean(options.push),
+			message: options.message,
+			validate: options.validate,
+		});
+		print(result, true);
+	});
+
+backupCommand
+	.command("import <repo>")
+	.description("Merge a canonical JSONL backup into the local SQLite store")
+	.option("--no-validate", "Skip backup validation before import")
+	.option("--replace", "Replace local portable tables instead of merging")
+	.action(async (repo, options) => {
+		const result = await importBackup({
+			repoPath: repo,
+			validate: options.validate,
+			mode: options.replace ? "replace" : "merge",
+		});
+		print(result, true);
+	});
+
+backupCommand
+	.command("sync")
+	.description("Pull, merge-import, export, commit, and push a backup repo")
+	.requiredOption("--repo <path>", "Backup repository/path")
+	.option("--remote <url>", "Git remote to clone/configure")
+	.option(
+		"--message <message>",
+		"Git commit message",
+		"archive: sync birdclaw backup",
+	)
+	.action(async (options) => {
+		const result = await syncBackup({
+			repoPath: options.repo,
+			remote: options.remote,
+			message: options.message,
+		});
+		print(result, true);
+	});
+
+backupCommand
+	.command("validate <repo>")
+	.description("Validate backup manifest, shard hashes, and JSONL rows")
+	.action(async (repo) => {
+		const result = await validateBackup(repo);
+		print(result, true);
+		if (!result.ok) {
+			process.exitCode = 1;
+		}
+	});
+
 program
 	.command("serve")
 	.description("Run the local web app")
-	.action(() => {
+	.action(async () => {
+		await autoUpdateBeforeRead();
 		const child = spawn(
 			process.execPath,
 			["node_modules/vite/bin/vite.js", "dev", "--port", "3000"],

package/src/components/AppNav.tsx

@@ -14,6 +14,8 @@ const links = [
 	{ to: "/inbox", label: "Inbox" },
 	{ to: "/", label: "Home" },
 	{ to: "/mentions", label: "Mentions" },
+	{ to: "/likes", label: "Likes" },
+	{ to: "/bookmarks", label: "Bookmarks" },
 	{ to: "/dms", label: "DMs" },
 	{ to: "/blocks", label: "Blocks" },
 ] as const;
@@ -27,7 +29,7 @@ export function AppNav() {
 		<nav className={navClass}>
 			<div>
 				<p className={eyebrowClass}>birdclaw</p>
-				<h1 className={brandMarkClass}>Quiet signal for X.</h1>
+				<h1 className={brandMarkClass}>Quiet signal for Twitter.</h1>
 			</div>
 			<div className={navLinksClass}>
 				{links.map((link) => {

package/src/components/SavedTimelineView.tsx

@@ -0,0 +1,115 @@
+import { useEffect, useMemo, useState } from "react";
+import { TimelineCard } from "#/components/TimelineCard";
+import type { QueryEnvelope, QueryResponse, TimelineItem } from "#/lib/types";
+import {
+	cx,
+	eyebrowClass,
+	feedPageClass,
+	heroControlsClass,
+	heroCopyClass,
+	heroShellClass,
+	heroTitleClass,
+	pageWrapClass,
+	textFieldClass,
+	textFieldWideClass,
+	timelineLaneClass,
+} from "#/lib/ui";
+
+interface SavedTimelineViewProps {
+	filter: "liked" | "bookmarked";
+	eyebrow: string;
+	title: string;
+	loadingLabel: string;
+	searchPlaceholder: string;
+}
+
+export function SavedTimelineView({
+	filter,
+	eyebrow,
+	title,
+	loadingLabel,
+	searchPlaceholder,
+}: SavedTimelineViewProps) {
+	const [meta, setMeta] = useState<QueryEnvelope | null>(null);
+	const [items, setItems] = useState<TimelineItem[]>([]);
+	const [search, setSearch] = useState("");
+	const [refreshTick, setRefreshTick] = useState(0);
+
+	useEffect(() => {
+		fetch("/api/status")
+			.then((response) => response.json())
+			.then((data: QueryEnvelope) => setMeta(data));
+	}, []);
+
+	useEffect(() => {
+		const url = new URL("/api/query", window.location.origin);
+		url.searchParams.set("resource", "home");
+		url.searchParams.set(filter, "true");
+		url.searchParams.set("refresh", String(refreshTick));
+		if (search.trim()) {
+			url.searchParams.set("search", search.trim());
+		}
+
+		fetch(url)
+			.then((response) => response.json())
+			.then((data: QueryResponse) => setItems(data.items as TimelineItem[]));
+	}, [filter, refreshTick, search]);
+
+	const subtitle = useMemo(() => {
+		if (!meta) {
+			return items.length > 0 ? `${items.length} visible` : loadingLabel;
+		}
+		return `${items.length} visible · ${meta.transport.statusText}`;
+	}, [items.length, loadingLabel, meta]);
+
+	async function replyToTweet(tweetId: string) {
+		const text = window.prompt("Reply text");
+		if (!text?.trim()) return;
+
+		await fetch("/api/action", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				kind: "replyTweet",
+				accountId: "acct_primary",
+				tweetId,
+				text,
+			}),
+		});
+
+		setRefreshTick((value) => value + 1);
+	}
+
+	return (
+		<main className={pageWrapClass}>
+			<div className={feedPageClass}>
+				<section className={heroShellClass}>
+					<div>
+						<p className={eyebrowClass}>{eyebrow}</p>
+						<h2 className={heroTitleClass}>{title}</h2>
+						<p className={heroCopyClass}>{subtitle}</p>
+					</div>
+					<div className={heroControlsClass}>
+						<input
+							className={cx(textFieldClass, textFieldWideClass)}
+							onChange={(event) => setSearch(event.target.value)}
+							placeholder={searchPlaceholder}
+							value={search}
+						/>
+					</div>
+				</section>
+
+				<section className={timelineLaneClass}>
+					{items.map((item) => (
+						<TimelineCard
+							key={item.id}
+							item={item}
+							onReply={replyToTweet}
+							showReplyControls={false}
+						/>
+					))}
+				</section>
+			</div>
+		</main>
+	);
+}

package/src/components/TimelineCard.tsx

@@ -34,10 +34,15 @@ function getVisibleUrlCards(item: TimelineItem) {
 export function TimelineCard({
 	item,
 	onReply,
+	showReplyControls = true,
 }: {
 	item: TimelineItem;
 	onReply: (tweetId: string) => void;
+	showReplyControls?: boolean;
 }) {
+	const canReply =
+		showReplyControls && item.kind !== "like" && item.kind !== "bookmark";
+
 	return (
 		<article className={contentCardClass}>
 			<header className={cardHeaderClass}>
@@ -62,14 +67,16 @@ export function TimelineCard({
 					</div>
 				</div>
 				<div className={metaStackClass}>
-					<span
-						className={cx(
-							pillClass,
-							item.isReplied ? pillSoftClass : pillAlertClass,
-						)}
-					>
-						{item.isReplied ? "replied" : "needs reply"}
-					</span>
+					{canReply ? (
+						<span
+							className={cx(
+								pillClass,
+								item.isReplied ? pillSoftClass : pillAlertClass,
+							)}
+						>
+							{item.isReplied ? "replied" : "needs reply"}
+						</span>
+					) : null}
 					<span className={timestampClass}>
 						{formatShortTimestamp(item.createdAt)}
 					</span>
@@ -83,9 +90,9 @@ export function TimelineCard({
 			{item.quotedTweet ? (
 				<EmbeddedTweetCard item={item.quotedTweet} label="Quoted tweet" />
 			) : null}
-			{getVisibleUrlCards(item).map((entry) => (
+			{getVisibleUrlCards(item).map((entry, index) => (
 				<a
-					key={entry.expandedUrl}
+					key={`${entry.expandedUrl}-${String(index)}`}
 					className={linkPreviewCardClass}
 					href={entry.expandedUrl}
 					rel="noreferrer"
@@ -105,13 +112,15 @@ export function TimelineCard({
 					<span>{item.bookmarked ? "bookmarked" : "not bookmarked"}</span>
 					<span>{item.accountHandle}</span>
 				</div>
-				<button
-					className={actionButtonClass}
-					onClick={() => onReply(item.id)}
-					type="button"
-				>
-					Reply
-				</button>
+				{canReply ? (
+					<button
+						className={actionButtonClass}
+						onClick={() => onReply(item.id)}
+						type="button"
+					>
+						Reply
+					</button>
+				) : null}
 			</footer>
 		</article>
 	);