birdclaw 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # CHANGELOG
 
+## Unreleased
+
+## 0.5.1 - 2026-05-15
+
+### Fixed
+
+- Harden the published CLI wrapper and release checks so the packaged `birdclaw` binary avoids `tsx` CLI IPC startup and stays covered by lint, format, and smoke tests.
+- Forward shutdown signals through the published CLI and bundled web server, and include referenced script helpers in npm packages.
+- Keep the selected DM conversation visible while its thread refreshes so the reply composer no longer flashes away mid-action.
+- Send the selected web account through manual sync controls so multi-account timelines sync the intended profile.
+- Run web sync requests as background jobs with status polling so the UI no longer holds one blocking sync request open.
+- Add typed web API fetch handling and explicit DMs loading/error/empty states so failed local reads surface cleanly.
+- Add explicit web app sync controls for home timeline, mentions, likes, bookmarks, and DMs so fresh live data can be pulled without leaving the UI.
+- Refine the web app sidebar tagline and theme selector so the brand chrome reads more clearly in compact layouts.
+- Add shared web feed loading/error/empty states with timeline-shaped skeleton rows and move conversation expansion into a cached single-thread surface with hover prefetch.
+- Use the Birdclaw crab-bird mark in the web app chrome, loading states, and empty states; soften dark-mode contrast and replace text-only reply warnings with conversation/replied indicators.
+- Allow the local web app to respond when Tailscale Serve forwards requests through the `clawmac.sheep-coho.ts.net` hostname.
+- Speed up the default home timeline load on large local databases and keep malformed archived media URL entities from crashing the web timeline.
+- Preserve tweet media aspect ratios, open timeline media in an inline viewer, and suppress duplicate media URL cards.
+
 ## 0.5.0 - 2026-05-15
 
 ### Added

package/README.md

@@ -256,6 +256,10 @@ Start the app:
 birdclaw serve
 ```
 
+Use the Sync button in Home, Mentions, Likes, Bookmarks, or DMs to run the matching live sync from the web UI and then reload the local view. These controls are explicit because live reads can be slow, auth-dependent, or rate-limited.
+
+When running behind a trusted reverse proxy such as Tailscale Serve, add any extra proxy hostnames to `BIRDCLAW_ALLOWED_HOSTS`. The clawmac Tailscale hostname is allowed by default.
+
 First moderation pass:
 
 ```bash
@@ -359,6 +363,7 @@ Notes:
 - `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 authored`, `sync mentions`, `sync mention-threads`, `sync likes`, `sync bookmarks`, and `sync timeline` store live results in the canonical local store; per-account authored/home/mention/like/bookmark membership is kept as edges so shared tweets do not clobber account ownership
+- the web UI has explicit Sync buttons for home timeline, mentions, likes, bookmarks, and DMs; they call the same sync paths and then reload the local DB-backed view
 
 ### Research bookmarks and threads
 

package/bin/birdclaw.mjs

@@ -1,30 +1,69 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const require = createRequire(import.meta.url);
-const tsxCli = require.resolve("tsx/cli");
+const tsxLoader = pathToFileURL(require.resolve("tsx")).href;
 const birdclawCli = join(packageRoot, "src", "cli.ts");
 
-const result = spawnSync(
+const child = spawn(
 	process.execPath,
-	[tsxCli, birdclawCli, ...process.argv.slice(2)],
+	["--import", tsxLoader, birdclawCli, ...process.argv.slice(2)],
 	{
 		stdio: "inherit",
 		env: process.env,
+		detached: process.platform !== "win32",
 	},
 );
 
-if (result.error) {
-	console.error(result.error.message);
-	process.exit(1);
+const forwardedSignals = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+
+function removeSignalHandlers() {
+	for (const signal of forwardedSignals) {
+		process.removeListener(signal, forwardSignal);
+	}
+}
+
+function forwardSignal(signal) {
+	if (child.exitCode === null && child.signalCode === null) {
+		signalChild(signal);
+	}
+}
+
+function signalChild(signal) {
+	if (child.pid === undefined) {
+		return;
+	}
+	const targetPid = process.platform === "win32" ? child.pid : -child.pid;
+	try {
+		process.kill(targetPid, signal);
+	} catch (error) {
+		if (error?.code !== "ESRCH") {
+			throw error;
+		}
+	}
 }
 
-if (result.signal) {
-	process.kill(process.pid, result.signal);
+for (const signal of forwardedSignals) {
+	process.on(signal, forwardSignal);
 }
 
-process.exit(result.status ?? 0);
+child.on("error", (error) => {
+	removeSignalHandlers();
+	console.error(error.message);
+	process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+	removeSignalHandlers();
+
+	if (signal) {
+		process.kill(process.pid, signal);
+		return;
+	}
+
+	process.exit(code ?? 0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "birdclaw",
-	"version": "0.5.0",
+	"version": "0.5.1",
 	"description": "Local Twitter memory in SQLite for archives, DMs, likes, bookmarks, and moderation",
 	"homepage": "https://github.com/steipete/birdclaw#readme",
 	"license": "MIT",
@@ -13,6 +13,7 @@
 	},
 	"files": [
 		"bin/",
+		"scripts/",
 		"src/",
 		"!src/**/*.test.ts",
 		"!src/**/*.test.tsx",
@@ -38,13 +39,13 @@
 		"dev": "vite dev --port 3000",
 		"build": "vite build",
 		"preview": "vite preview",
-		"test": "env -u NODE_OPTIONS node ./scripts/run-vitest.mjs run",
-		"coverage": "env -u NODE_OPTIONS node ./scripts/run-vitest.mjs run --coverage",
+		"test": "node ./scripts/run-vitest.mjs run",
+		"coverage": "node ./scripts/run-vitest.mjs run --coverage",
 		"e2e": "playwright test",
 		"typecheck": "tsgo --noEmit",
-		"format": "oxfmt --write src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
-		"format:check": "oxfmt --check src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
-		"lint": "oxlint --import-plugin --node-plugin --vitest-plugin --deny-warnings -A require-mock-type-parameters -A no-control-regex src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
+		"format": "oxfmt --write bin src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
+		"format:check": "oxfmt --check bin src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
+		"lint": "oxlint --import-plugin --node-plugin --vitest-plugin --deny-warnings -A require-mock-type-parameters -A no-control-regex bin src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
 		"check": "pnpm run format:check && pnpm run lint",
 		"perf:browser": "node ./scripts/browser-perf.mjs",
 		"cli": "tsx src/cli.ts",

package/scripts/browser-perf.mjs

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { chromium } from "@playwright/test";
+import { withSanitizedNodeOptions } from "./sanitize-node-options.mjs";
+
+const DEFAULT_BASE_URL = "http://localhost:3000";
+const DEFAULT_ITERATIONS = 5;
+const READY_TIMEOUT_MS = 20_000;
+
+const SCENARIOS = {
+	home: {
+		path: "/",
+		ready: async (page) => waitForAny(page, ['[data-perf="timeline-card"]']),
+	},
+	mentions: {
+		path: "/mentions",
+		ready: async (page) => waitForAny(page, ['[data-perf="timeline-card"]']),
+	},
+	"mentions-search": {
+		path: "/mentions",
+		ready: async (page) => {
+			await page.getByPlaceholder("Search mentions").fill("peekaboo");
+			await waitForAny(page, ['[data-perf="timeline-card"]']);
+		},
+	},
+	links: {
+		path: "/links",
+		ready: async (page) =>
+			waitForAny(page, [
+				'[data-perf="link-insight-row"]',
+				"text=No links in this window.",
+			]),
+	},
+	"links-toggle": {
+		path: "/links",
+		ready: async (page) =>
+			waitForAny(page, [
+				'[data-perf="link-insight-row"]',
+				"text=No links in this window.",
+			]),
+		action: async (page) => {
+			await page.getByRole("button", { name: "videos" }).click();
+			await waitForAny(page, [
+				'[data-perf="link-insight-row"]',
+				"text=No links in this window.",
+			]);
+		},
+	},
+};
+
+function parseArgs(argv) {
+	const options = {
+		baseUrl: process.env.BIRDCLAW_PERF_URL || DEFAULT_BASE_URL,
+		iterations: DEFAULT_ITERATIONS,
+		scenarios: Object.keys(SCENARIOS),
+		json: false,
+		budgets: {},
+	};
+
+	for (const arg of argv) {
+		if (arg === "--json") {
+			options.json = true;
+		} else if (arg.startsWith("--url=")) {
+			options.baseUrl = arg.slice("--url=".length).replace(/\/$/, "");
+		} else if (arg.startsWith("--iterations=")) {
+			options.iterations = Math.max(
+				1,
+				Number.parseInt(arg.split("=")[1] ?? "", 10),
+			);
+		} else if (arg.startsWith("--scenario=")) {
+			options.scenarios = arg
+				.slice("--scenario=".length)
+				.split(",")
+				.map((value) => value.trim())
+				.filter(Boolean);
+		} else if (arg.startsWith("--budget-ready-ms=")) {
+			options.budgets.readyMs = Number(arg.split("=")[1]);
+		} else if (arg.startsWith("--budget-action-ms=")) {
+			options.budgets.actionMs = Number(arg.split("=")[1]);
+		} else if (arg.startsWith("--budget-api-p95-ms=")) {
+			options.budgets.apiP95Ms = Number(arg.split("=")[1]);
+		} else if (arg.startsWith("--budget-preview-calls=")) {
+			options.budgets.previewCalls = Number(arg.split("=")[1]);
+		}
+	}
+
+	for (const scenario of options.scenarios) {
+		if (!SCENARIOS[scenario]) {
+			throw new Error(`Unknown scenario: ${scenario}`);
+		}
+	}
+
+	return options;
+}
+
+async function isReachable(baseUrl) {
+	try {
+		const response = await fetch(baseUrl, {
+			signal: AbortSignal.timeout(1000),
+		});
+		return response.ok || response.status < 500;
+	} catch {
+		return false;
+	}
+}
+
+async function startServerIfNeeded(baseUrl) {
+	if (await isReachable(baseUrl)) {
+		return null;
+	}
+
+	const url = new URL(baseUrl);
+	const port = url.port || "3000";
+	const viteBin = path.join(
+		process.cwd(),
+		"node_modules",
+		"vite",
+		"bin",
+		"vite.js",
+	);
+	const child = spawn(
+		process.execPath,
+		[viteBin, "dev", "--port", port, "--host", "127.0.0.1"],
+		{
+			cwd: process.cwd(),
+			stdio: ["ignore", "pipe", "pipe"],
+			env: {
+				...withSanitizedNodeOptions(process.env),
+			},
+		},
+	);
+
+	const deadline = Date.now() + 30_000;
+	while (Date.now() < deadline) {
+		if (await isReachable(baseUrl)) {
+			return child;
+		}
+		await sleep(250);
+	}
+
+	child.kill("SIGTERM");
+	throw new Error(`Timed out waiting for ${baseUrl}`);
+}
+
+async function waitForAny(page, selectors) {
+	await page.waitForFunction(
+		(values) =>
+			values.some((selector) => {
+				if (selector.startsWith("text=")) {
+					return document.body.innerText.includes(selector.slice(5));
+				}
+				return Boolean(document.querySelector(selector));
+			}),
+		selectors,
+		{ timeout: READY_TIMEOUT_MS },
+	);
+}
+
+function percentile(values, point) {
+	if (values.length === 0) return 0;
+	const sorted = [...values].sort((left, right) => left - right);
+	const index = Math.min(
+		sorted.length - 1,
+		Math.ceil(sorted.length * point) - 1,
+	);
+	return sorted[index] ?? 0;
+}
+
+function median(values) {
+	return percentile(values, 0.5);
+}
+
+function round(value) {
+	return Math.round(value);
+}
+
+function apiBucket(rawUrl) {
+	const url = new URL(rawUrl);
+	if (url.pathname === "/api/link-insights") {
+		return `${url.pathname}:${url.searchParams.get("kind") ?? "unknown"}`;
+	}
+	return url.pathname;
+}
+
+function summarizeRuns(runs) {
+	const ready = runs.map((run) => run.readyMs);
+	const action = runs
+		.map((run) => run.actionMs)
+		.filter((value) => typeof value === "number");
+	const apiDurations = runs.flatMap((run) => run.apiDurationsMs);
+	return {
+		readyMedianMs: round(median(ready)),
+		readyP95Ms: round(percentile(ready, 0.95)),
+		actionMedianMs: action.length > 0 ? round(median(action)) : null,
+		actionP95Ms: action.length > 0 ? round(percentile(action, 0.95)) : null,
+		apiP95Ms: round(percentile(apiDurations, 0.95)),
+		apiCallsMedian: round(median(runs.map((run) => run.apiCalls))),
+		previewCallsMedian: round(median(runs.map((run) => run.previewCalls))),
+		rowsMedian: round(median(runs.map((run) => run.rows))),
+		previewsMedian: round(median(runs.map((run) => run.previews))),
+		endpoints: summarizeEndpoints(runs),
+	};
+}
+
+function summarizeEndpoints(runs) {
+	const totals = new Map();
+	for (const run of runs) {
+		for (const [endpoint, count] of Object.entries(run.apiEndpoints)) {
+			totals.set(endpoint, (totals.get(endpoint) ?? 0) + count);
+		}
+	}
+	return [...totals.entries()]
+		.map(([endpoint, count]) => ({
+			endpoint,
+			medianCalls: Math.round(count / runs.length),
+		}))
+		.sort((left, right) => right.medianCalls - left.medianCalls)
+		.slice(0, 8);
+}
+
+async function runScenario(browser, baseUrl, name) {
+	const scenario = SCENARIOS[name];
+	const page = await browser.newPage({
+		viewport: { width: 1474, height: 910 },
+	});
+	const requestStart = new Map();
+	const apiDurationsMs = [];
+	let apiCalls = 0;
+	let previewCalls = 0;
+	const apiEndpoints = {};
+
+	page.on("request", (request) => {
+		if (request.url().includes("/api/")) {
+			requestStart.set(request, performance.now());
+		}
+	});
+	page.on("response", (response) => {
+		const request = response.request();
+		const startedAt = requestStart.get(request);
+		if (startedAt === undefined) return;
+		requestStart.delete(request);
+		apiCalls += 1;
+		const endpoint = apiBucket(response.url());
+		apiEndpoints[endpoint] = (apiEndpoints[endpoint] ?? 0) + 1;
+		apiDurationsMs.push(performance.now() - startedAt);
+		if (response.url().includes("/api/link-preview")) {
+			previewCalls += 1;
+		}
+	});
+
+	const startedAt = performance.now();
+	await page.goto(`${baseUrl}${scenario.path}`, {
+		waitUntil: "domcontentloaded",
+	});
+	await scenario.ready(page);
+	const readyMs = performance.now() - startedAt;
+
+	let actionMs = null;
+	if (scenario.action) {
+		const actionStartedAt = performance.now();
+		await scenario.action(page);
+		actionMs = performance.now() - actionStartedAt;
+	}
+
+	await page.waitForTimeout(250);
+	const counts = await page.evaluate(() => ({
+		rows: document.querySelectorAll(
+			'[data-perf="timeline-card"], [data-perf="link-insight-row"]',
+		).length,
+		previews: document.querySelectorAll('[data-perf="link-preview-card"]')
+			.length,
+	}));
+	await page.close();
+
+	return {
+		readyMs,
+		actionMs,
+		apiCalls,
+		previewCalls,
+		apiEndpoints,
+		apiDurationsMs,
+		rows: counts.rows,
+		previews: counts.previews,
+	};
+}
+
+function budgetFailures(name, summary, budgets) {
+	const failures = [];
+	if (
+		Number.isFinite(budgets.readyMs) &&
+		summary.readyP95Ms > budgets.readyMs
+	) {
+		failures.push(
+			`${name} ready p95 ${summary.readyP95Ms}ms > ${budgets.readyMs}ms`,
+		);
+	}
+	if (
+		Number.isFinite(budgets.actionMs) &&
+		summary.actionP95Ms !== null &&
+		summary.actionP95Ms > budgets.actionMs
+	) {
+		failures.push(
+			`${name} action p95 ${summary.actionP95Ms}ms > ${budgets.actionMs}ms`,
+		);
+	}
+	if (
+		Number.isFinite(budgets.apiP95Ms) &&
+		summary.apiP95Ms > budgets.apiP95Ms
+	) {
+		failures.push(
+			`${name} api p95 ${summary.apiP95Ms}ms > ${budgets.apiP95Ms}ms`,
+		);
+	}
+	if (
+		Number.isFinite(budgets.previewCalls) &&
+		summary.previewCallsMedian > budgets.previewCalls
+	) {
+		failures.push(
+			`${name} preview calls median ${summary.previewCallsMedian} > ${budgets.previewCalls}`,
+		);
+	}
+	return failures;
+}
+
+function printHuman(results, failures) {
+	console.log("browser perf");
+	for (const result of results) {
+		const summary = result.summary;
+		console.log("");
+		console.log(`scenario: ${result.name}`);
+		console.log(`ready median: ${summary.readyMedianMs}ms`);
+		console.log(`ready p95: ${summary.readyP95Ms}ms`);
+		if (summary.actionMedianMs !== null) {
+			console.log(`action median: ${summary.actionMedianMs}ms`);
+			console.log(`action p95: ${summary.actionP95Ms}ms`);
+		}
+		console.log(`api p95: ${summary.apiP95Ms}ms`);
+		console.log(`api calls median: ${summary.apiCallsMedian}`);
+		console.log(`preview calls median: ${summary.previewCallsMedian}`);
+		console.log(`rows median: ${summary.rowsMedian}`);
+		console.log(`preview cards median: ${summary.previewsMedian}`);
+		if (summary.endpoints.length > 0) {
+			console.log("top endpoints:");
+			for (const endpoint of summary.endpoints) {
+				console.log(`- ${endpoint.endpoint}: ${endpoint.medianCalls}`);
+			}
+		}
+	}
+	if (failures.length > 0) {
+		console.log("");
+		console.log("budget failures:");
+		for (const failure of failures) {
+			console.log(`- ${failure}`);
+		}
+	}
+}
+
+async function main() {
+	const options = parseArgs(process.argv.slice(2));
+	const server = await startServerIfNeeded(options.baseUrl);
+	const browser = await chromium.launch({ headless: true });
+	const results = [];
+	const failures = [];
+
+	try {
+		for (const name of options.scenarios) {
+			await runScenario(browser, options.baseUrl, name);
+			const runs = [];
+			for (let index = 0; index < options.iterations; index += 1) {
+				runs.push(await runScenario(browser, options.baseUrl, name));
+			}
+			const summary = summarizeRuns(runs);
+			results.push({ name, summary, runs });
+			failures.push(...budgetFailures(name, summary, options.budgets));
+		}
+	} finally {
+		await browser.close();
+		if (server) {
+			server.kill("SIGTERM");
+		}
+	}
+
+	if (options.json) {
+		console.log(JSON.stringify({ results, failures }, null, 2));
+	} else {
+		printHuman(results, failures);
+	}
+
+	if (failures.length > 0) {
+		process.exitCode = 1;
+	}
+}
+
+main().catch((error) => {
+	console.error(error instanceof Error ? error.stack || error.message : error);
+	process.exit(1);
+});