birdclaw 0.4.1 → 0.5.0

package/src/lib/backup.ts

@@ -184,9 +184,9 @@ function getExportRowSets(db: Database) {
 			rows: rowsForQuery(
 				db,
 				`
-        select id, handle, display_name, bio, followers_count, following_count,
-          avatar_hue, avatar_url, location, url, verified_type, entities_json,
-          raw_json, created_at
+        select id, handle, display_name, bio, followers_count,
+          following_count, public_metrics_json, avatar_hue, avatar_url,
+          location, url, verified_type, entities_json, raw_json, created_at
         from profiles
         order by id
         `,
@@ -287,6 +287,31 @@ function getExportRowSets(db: Database) {
           is_replied, media_count
         from dm_messages
         order by conversation_id, created_at, id
+				`,
+			),
+		},
+		{
+			logicalName: "url_expansions",
+			rows: rowsForQuery(
+				db,
+				`
+        select short_url, expanded_url, final_url, status, expanded_tweet_id,
+          expanded_handle, title, description, image_url, site_name, error,
+          source, updated_at
+        from url_expansions
+        order by short_url
+        `,
+			),
+		},
+		{
+			logicalName: "link_occurrences",
+			rows: rowsForQuery(
+				db,
+				`
+        select source_kind, source_id, source_position, short_url, account_id,
+          conversation_id, direction, created_at
+        from link_occurrences
+        order by source_kind, source_id, source_position, short_url
         `,
 			),
 		},
@@ -331,6 +356,53 @@ function getExportRowSets(db: Database) {
         select entity_kind, entity_id, model, score, summary, reasoning, updated_at
         from ai_scores
         order by entity_kind, entity_id, model
+        `,
+			),
+		},
+		{
+			logicalName: "follow_snapshots",
+			rows: rowsForQuery(
+				db,
+				`
+        select id, account_id, direction, source, status, page_count,
+          result_count, started_at, completed_at, raw_meta_json
+        from follow_snapshots
+        order by account_id, direction, completed_at, id
+        `,
+			),
+		},
+		{
+			logicalName: "follow_snapshot_members",
+			rows: rowsForQuery(
+				db,
+				`
+        select snapshot_id, profile_id, external_user_id, position
+        from follow_snapshot_members
+        order by snapshot_id, position, profile_id
+        `,
+			),
+		},
+		{
+			logicalName: "follow_edges",
+			rows: rowsForQuery(
+				db,
+				`
+        select account_id, direction, profile_id, external_user_id, source,
+          current, first_seen_at, last_seen_at, ended_at, updated_at
+        from follow_edges
+        order by account_id, direction, profile_id
+        `,
+			),
+		},
+		{
+			logicalName: "follow_events",
+			rows: rowsForQuery(
+				db,
+				`
+        select id, account_id, direction, profile_id, external_user_id, kind,
+          event_at, snapshot_id
+        from follow_events
+        order by account_id, direction, event_at, kind, profile_id, id
         `,
 			),
 		},
@@ -393,7 +465,9 @@ function buildShards(db: Database) {
 			case "tweet_account_edges":
 				for (const row of rowSet.rows) {
 					const kind =
-						row.kind === "home" || row.kind === "mention"
+						row.kind === "home" ||
+						row.kind === "mention" ||
+						row.kind === "authored"
 							? row.kind
 							: "unknown";
 					addRows(shards, `data/timeline_edges/${kind}.jsonl`, [row]);
@@ -411,6 +485,12 @@ function buildShards(db: Database) {
 					);
 				}
 				break;
+			case "url_expansions":
+				addRows(shards, "data/links/url_expansions.jsonl", rowSet.rows);
+				break;
+			case "link_occurrences":
+				addRows(shards, "data/links/occurrences.jsonl", rowSet.rows);
+				break;
 			case "blocks":
 			case "mutes":
 				addRows(
@@ -425,6 +505,18 @@ function buildShards(db: Database) {
 			case "ai_scores":
 				addRows(shards, "data/ai_scores.jsonl", rowSet.rows);
 				break;
+			case "follow_snapshots":
+				addRows(shards, "data/follow_snapshots.jsonl", rowSet.rows);
+				break;
+			case "follow_snapshot_members":
+				addRows(shards, "data/follow_snapshot_members.jsonl", rowSet.rows);
+				break;
+			case "follow_edges":
+				addRows(shards, "data/follow_edges.jsonl", rowSet.rows);
+				break;
+			case "follow_events":
+				addRows(shards, "data/follow_events.jsonl", rowSet.rows);
+				break;
 		}
 	}
 
@@ -514,11 +606,17 @@ function computeCounts(files: BackupFileManifest[]) {
 							? "dm_conversations"
 							: second === "dms"
 								? "dm_messages"
-								: second === "moderation"
-									? third?.replace(/\.jsonl$/, "") || "moderation"
-									: second === "actions"
-										? third?.replace(/\.jsonl$/, "") || "actions"
-										: second?.replace(/\.jsonl$/, "") || "unknown";
+								: second === "links"
+									? third === "url_expansions.jsonl"
+										? "url_expansions"
+										: third === "occurrences.jsonl"
+											? "link_occurrences"
+											: "links"
+									: second === "moderation"
+										? third?.replace(/\.jsonl$/, "") || "moderation"
+										: second === "actions"
+											? third?.replace(/\.jsonl$/, "") || "actions"
+											: second?.replace(/\.jsonl$/, "") || "unknown";
 		counts[key] = (counts[key] ?? 0) + file.rows;
 	}
 	return counts;
@@ -552,11 +650,18 @@ data/collections/likes.jsonl
 data/collections/bookmarks.jsonl
 data/dms/conversations.jsonl
 data/dms/YYYY.jsonl
+data/links/url_expansions.jsonl
+data/links/occurrences.jsonl
 data/moderation/blocks.jsonl
 data/moderation/mutes.jsonl
+data/follow_snapshots.jsonl
+data/follow_snapshot_members.jsonl
+data/follow_edges.jsonl
+data/follow_events.jsonl
 \`\`\`
 
 Tweets are sharded by creation year. Collection-only tweets whose creation date is unknown live in \`data/tweets/unknown.jsonl\`. Timeline edges keep account-scoped home/mention membership separate from canonical tweet content. DMs are sharded by year and keep \`conversation_id\` in each row.
+The links shard stores expanded short URLs and their source tweet/DM occurrences so linked-tweet search can be rebuilt without re-expanding every \`t.co\` URL.
 
 Never commit live tokens, browser cookies, raw SQLite WAL/SHM sidecars, or temporary cache files here.
 `,
@@ -967,6 +1072,10 @@ function insertFtsRows(
 
 function clearBackupImportData(db: Database) {
 	db.exec(`
+    delete from follow_events;
+    delete from follow_edges;
+    delete from follow_snapshot_members;
+    delete from follow_snapshots;
     delete from ai_scores;
     delete from tweet_actions;
     delete from tweet_account_edges;
@@ -1029,6 +1138,12 @@ export async function importBackup({
 		mutes,
 		actions,
 		scores,
+		urlExpansions,
+		linkOccurrences,
+		followSnapshots,
+		followSnapshotMembers,
+		followEdges,
+		followEvents,
 	] = await Promise.all([
 		readRows((file) => file === "data/accounts.jsonl"),
 		readRows((file) => file === "data/profiles.jsonl"),
@@ -1047,6 +1162,12 @@ export async function importBackup({
 		readRows((file) => file === "data/moderation/mutes.jsonl"),
 		readRows((file) => file === "data/actions/tweet_actions.jsonl"),
 		readRows((file) => file === "data/ai_scores.jsonl"),
+		readRows((file) => file === "data/links/url_expansions.jsonl"),
+		readRows((file) => file === "data/links/occurrences.jsonl"),
+		readRows((file) => file === "data/follow_snapshots.jsonl"),
+		readRows((file) => file === "data/follow_snapshot_members.jsonl"),
+		readRows((file) => file === "data/follow_edges.jsonl"),
+		readRows((file) => file === "data/follow_events.jsonl"),
 	]);
 
 	db.transaction(() => {
@@ -1152,15 +1273,19 @@ export async function importBackup({
 			`
       insert into profiles (
         id, handle, display_name, bio, followers_count, following_count,
-        avatar_hue, avatar_url, location, url, verified_type, entities_json,
-        raw_json, created_at
-      ) values (?, ?, ?, ?, ?, coalesce(?, 0), ?, ?, ?, ?, ?, coalesce(?, '{}'), coalesce(?, '{}'), ?)
+        public_metrics_json, avatar_hue, avatar_url, location, url,
+        verified_type, entities_json, raw_json, created_at
+      ) values (?, ?, ?, ?, ?, coalesce(?, 0), coalesce(?, '{}'), ?, ?, ?, ?, ?, coalesce(?, '{}'), coalesce(?, '{}'), ?)
       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),
+        public_metrics_json = case
+          when excluded.public_metrics_json not in ('', '{}', 'null') then excluded.public_metrics_json
+          else profiles.public_metrics_json
+        end,
         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),
         location = coalesce(excluded.location, profiles.location),
@@ -1184,6 +1309,7 @@ export async function importBackup({
 				"bio",
 				"followers_count",
 				"following_count",
+				"public_metrics_json",
 				"avatar_hue",
 				"avatar_url",
 				"location",
@@ -1237,6 +1363,118 @@ export async function importBackup({
 		insertRows(
 			db,
 			`
+      insert into follow_snapshots (
+        id, account_id, direction, source, status, page_count, result_count,
+        started_at, completed_at, raw_meta_json
+      ) values (?, ?, ?, coalesce(?, 'backup'), ?, coalesce(?, 0), coalesce(?, 0), ?, ?, coalesce(?, '{}'))
+      on conflict(id) do update set
+        account_id = coalesce(nullif(excluded.account_id, ''), follow_snapshots.account_id),
+        direction = coalesce(nullif(excluded.direction, ''), follow_snapshots.direction),
+        source = coalesce(nullif(excluded.source, ''), follow_snapshots.source),
+        status = coalesce(nullif(excluded.status, ''), follow_snapshots.status),
+        page_count = max(follow_snapshots.page_count, excluded.page_count),
+        result_count = max(follow_snapshots.result_count, excluded.result_count),
+        started_at = min(follow_snapshots.started_at, excluded.started_at),
+        completed_at = max(follow_snapshots.completed_at, excluded.completed_at),
+        raw_meta_json = case
+          when excluded.raw_meta_json not in ('', '{}', 'null') then excluded.raw_meta_json
+          else follow_snapshots.raw_meta_json
+        end
+      `,
+			followSnapshots,
+			[
+				"id",
+				"account_id",
+				"direction",
+				"source",
+				"status",
+				"page_count",
+				"result_count",
+				"started_at",
+				"completed_at",
+				"raw_meta_json",
+			],
+		);
+		insertRows(
+			db,
+			`
+      insert into follow_snapshot_members (
+        snapshot_id, profile_id, external_user_id, position
+      ) values (?, ?, ?, coalesce(?, 0))
+      on conflict(snapshot_id, profile_id) do update set
+        external_user_id = coalesce(nullif(excluded.external_user_id, ''), follow_snapshot_members.external_user_id),
+        position = excluded.position
+      `,
+			followSnapshotMembers,
+			["snapshot_id", "profile_id", "external_user_id", "position"],
+		);
+		insertRows(
+			db,
+			`
+      insert into follow_edges (
+        account_id, direction, profile_id, external_user_id, source, current,
+        first_seen_at, last_seen_at, ended_at, updated_at
+      ) values (?, ?, ?, ?, coalesce(?, 'backup'), coalesce(?, 1), ?, ?, ?, ?)
+      on conflict(account_id, direction, profile_id) do update set
+        external_user_id = coalesce(nullif(excluded.external_user_id, ''), follow_edges.external_user_id),
+        source = coalesce(nullif(excluded.source, ''), follow_edges.source),
+        current = case
+          when excluded.updated_at >= follow_edges.updated_at then excluded.current
+          else follow_edges.current
+        end,
+        first_seen_at = min(follow_edges.first_seen_at, excluded.first_seen_at),
+        last_seen_at = max(follow_edges.last_seen_at, excluded.last_seen_at),
+        ended_at = case
+          when excluded.updated_at >= follow_edges.updated_at then excluded.ended_at
+          else follow_edges.ended_at
+        end,
+        updated_at = max(follow_edges.updated_at, excluded.updated_at)
+      `,
+			followEdges,
+			[
+				"account_id",
+				"direction",
+				"profile_id",
+				"external_user_id",
+				"source",
+				"current",
+				"first_seen_at",
+				"last_seen_at",
+				"ended_at",
+				"updated_at",
+			],
+		);
+		insertRows(
+			db,
+			`
+      insert into follow_events (
+        id, account_id, direction, profile_id, external_user_id, kind, event_at,
+        snapshot_id
+      ) values (?, ?, ?, ?, ?, ?, ?, ?)
+      on conflict(id) do update set
+        account_id = coalesce(nullif(excluded.account_id, ''), follow_events.account_id),
+        direction = coalesce(nullif(excluded.direction, ''), follow_events.direction),
+        profile_id = coalesce(nullif(excluded.profile_id, ''), follow_events.profile_id),
+        external_user_id = coalesce(nullif(excluded.external_user_id, ''), follow_events.external_user_id),
+        kind = coalesce(nullif(excluded.kind, ''), follow_events.kind),
+        event_at = coalesce(nullif(excluded.event_at, ''), follow_events.event_at),
+        snapshot_id = coalesce(nullif(excluded.snapshot_id, ''), follow_events.snapshot_id)
+      `,
+			followEvents,
+			[
+				"id",
+				"account_id",
+				"direction",
+				"profile_id",
+				"external_user_id",
+				"kind",
+				"event_at",
+				"snapshot_id",
+			],
+		);
+		insertRows(
+			db,
+			`
       insert into tweets (
         id, account_id, author_profile_id, kind, text, created_at, is_replied,
         reply_to_id, like_count, media_count, bookmarked, liked, entities_json,
@@ -1246,8 +1484,8 @@ export async function importBackup({
         account_id = coalesce(nullif(excluded.account_id, ''), tweets.account_id),
         author_profile_id = coalesce(nullif(excluded.author_profile_id, ''), tweets.author_profile_id),
         kind = case
-          when tweets.kind in ('home', 'mention') then tweets.kind
-          when excluded.kind in ('home', 'mention') then excluded.kind
+          when tweets.kind in ('home', 'mention', 'authored') then tweets.kind
+          when excluded.kind in ('home', 'mention', 'authored') then excluded.kind
           else coalesce(nullif(excluded.kind, ''), tweets.kind)
         end,
         text = coalesce(nullif(excluded.text, ''), tweets.text),
@@ -1409,6 +1647,70 @@ export async function importBackup({
 		insertRows(
 			db,
 			`
+      insert into url_expansions (
+        short_url, expanded_url, final_url, status, expanded_tweet_id,
+        expanded_handle, title, description, image_url, site_name, error, source,
+        updated_at
+      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      on conflict(short_url) do update set
+        expanded_url = excluded.expanded_url,
+        final_url = excluded.final_url,
+        status = excluded.status,
+        expanded_tweet_id = excluded.expanded_tweet_id,
+        expanded_handle = excluded.expanded_handle,
+        title = excluded.title,
+        description = excluded.description,
+        image_url = excluded.image_url,
+        site_name = excluded.site_name,
+        error = excluded.error,
+        source = excluded.source,
+        updated_at = excluded.updated_at
+      `,
+			urlExpansions,
+			[
+				"short_url",
+				"expanded_url",
+				"final_url",
+				"status",
+				"expanded_tweet_id",
+				"expanded_handle",
+				"title",
+				"description",
+				"image_url",
+				"site_name",
+				"error",
+				"source",
+				"updated_at",
+			],
+		);
+		insertRows(
+			db,
+			`
+      insert into link_occurrences (
+        source_kind, source_id, source_position, short_url, account_id,
+        conversation_id, direction, created_at
+      ) values (?, ?, ?, ?, ?, ?, ?, ?)
+      on conflict(source_kind, source_id, source_position, short_url) do update set
+        account_id = excluded.account_id,
+        conversation_id = excluded.conversation_id,
+        direction = excluded.direction,
+        created_at = excluded.created_at
+      `,
+			linkOccurrences,
+			[
+				"source_kind",
+				"source_id",
+				"source_position",
+				"short_url",
+				"account_id",
+				"conversation_id",
+				"direction",
+				"created_at",
+			],
+		);
+		insertRows(
+			db,
+			`
       insert into blocks (account_id, profile_id, source, created_at)
       values (?, ?, ?, ?)
       on conflict(account_id, profile_id) do update set

package/src/lib/bird-actions.ts

@@ -1,10 +1,6 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { getBirdCommand } from "./config";
+import { runBirdCommand } from "./bird-command";
 import type { XurlMentionUser } from "./types";
 
-const execFileAsync = promisify(execFile);
-
 function liveWritesDisabled() {
 	return process.env.BIRDCLAW_DISABLE_LIVE_WRITES === "1";
 }
@@ -42,11 +38,6 @@ function normalizeOutput(stdout?: string, stderr?: string) {
 	return stripAnsi(stdout || stderr || "ok").trim();
 }
 
-async function runBirdCommand(args: string[]) {
-	const birdCommand = getBirdCommand();
-	return execFileAsync(birdCommand, args);
-}
-
 async function runBirdJsonCommand(args: string[]) {
 	const { stdout } = await runBirdCommand(args);
 	return JSON.parse(stripAnsi(stdout)) as Record<string, unknown>;

package/src/lib/bird-command.ts

@@ -0,0 +1,57 @@
+import { execFile } from "node:child_process";
+import type { ExecFileOptions } from "node:child_process";
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { promisify } from "node:util";
+import { getBirdCommand } from "./config";
+
+const execFileAsync = promisify(execFile);
+
+function isPathCommand(command: string) {
+	return command.includes("/") || command.startsWith(".");
+}
+
+function formatBirdInstallHint(command: string) {
+	return [
+		`bird command unavailable: ${command}`,
+		"Install bird on PATH, set BIRDCLAW_BIRD_COMMAND, or update ~/.birdclaw/config.json mentions.birdCommand.",
+	].join("\n");
+}
+
+async function assertBirdCommandAvailable(command: string) {
+	if (!isPathCommand(command)) {
+		return;
+	}
+
+	try {
+		await access(command, constants.X_OK);
+	} catch {
+		throw new Error(formatBirdInstallHint(command));
+	}
+}
+
+export async function runBirdCommand(
+	args: string[],
+	options?: ExecFileOptions,
+): Promise<{ stdout: string; stderr: string }> {
+	const birdCommand = getBirdCommand();
+	await assertBirdCommandAvailable(birdCommand);
+
+	try {
+		const result =
+			options === undefined
+				? await execFileAsync(birdCommand, args)
+				: await execFileAsync(birdCommand, args, options);
+		return result as { stdout: string; stderr: string };
+	} catch (error) {
+		if (
+			error &&
+			typeof error === "object" &&
+			"code" in error &&
+			(error.code === "ENOENT" || error.code === "EACCES")
+		) {
+			throw new Error(formatBirdInstallHint(birdCommand));
+		}
+		throw error;
+	}
+}

package/src/lib/bird.ts

@@ -6,6 +6,7 @@ import { promisify } from "node:util";
 import { getBirdCommand } from "./config";
 import type {
 	XurlMentionData,
+	XurlFollowUsersResponse,
 	XurlMentionsResponse,
 	XurlMentionUser,
 	XurlReferencedTweet,
@@ -98,6 +99,13 @@ interface BirdProfilesPayload {
 	errors?: Array<{ target?: string; error?: string }>;
 }
 
+type BirdFollowUsersPayload =
+	| NonNullable<BirdUserOverviewPayload["user"]>[]
+	| {
+			users?: NonNullable<BirdUserOverviewPayload["user"]>[];
+			nextCursor?: string | null;
+	  };
+
 function toIsoTimestamp(value: string) {
 	const parsed = new Date(value);
 	if (Number.isNaN(parsed.getTime())) {
@@ -173,13 +181,30 @@ function parseBirdJson(stdout: string) {
 }
 
 function formatBirdCommandError(error: unknown, birdCommand: string) {
+	const text = [
+		error instanceof Error ? error.message : "",
+		error &&
+		typeof error === "object" &&
+		"stderr" in error &&
+		typeof error.stderr === "string"
+			? error.stderr
+			: "",
+		error &&
+		typeof error === "object" &&
+		"stdout" in error &&
+		typeof error.stdout === "string"
+			? error.stdout
+			: "",
+	].join("\n");
 	if (
-		error instanceof Error &&
-		"code" in error &&
-		(error as { code?: unknown }).code === "ENOENT"
+		(error instanceof Error &&
+			"code" in error &&
+			(error as { code?: unknown }).code === "ENOENT") ||
+		(/No such file or directory|command not found|cannot execute/i.test(text) &&
+			text.includes(birdCommand))
 	) {
 		return new Error(
-			`bird CLI not found at ${birdCommand}. Install @steipete/bird or set BIRDCLAW_BIRD_COMMAND / mentions.birdCommand to a valid bird binary.`,
+			`bird command unavailable: ${birdCommand}\nInstall bird on PATH, set BIRDCLAW_BIRD_COMMAND, or update ~/.birdclaw/config.json mentions.birdCommand.`,
 		);
 	}
 
@@ -206,7 +231,7 @@ async function runBirdJsonCommand(args: string[], timeoutMs?: number) {
 		const shellScript = 'out="$1"; shift; exec "$@" > "$out"';
 		await execFileAsync(
 			"/bin/bash",
-			["-lc", shellScript, "birdclaw-bird", stdoutPath, birdCommand, ...args],
+			["-c", shellScript, "birdclaw-bird", stdoutPath, birdCommand, ...args],
 			{ maxBuffer: BIRD_JSON_MAX_BUFFER_BYTES, timeout: timeoutMs },
 		);
 		return readFileSync(stdoutPath, "utf8");
@@ -435,6 +460,65 @@ export async function listHomeTimelineViaBird({
 	return normalizeBirdTweets(getBirdTweetItems(payload, "home"));
 }
 
+function normalizeBirdFollowUsers(
+	payload: unknown,
+	command: "followers" | "following",
+	maxResults: number,
+): XurlFollowUsersResponse {
+	const rawPayload = payload as BirdFollowUsersPayload;
+	const users = Array.isArray(rawPayload) ? rawPayload : rawPayload.users;
+	if (!Array.isArray(users)) {
+		throw new Error(`bird ${command} returned unexpected JSON`);
+	}
+
+	const data = users
+		.map(toXurlMentionUser)
+		.filter((user): user is XurlMentionUser => Boolean(user));
+	const nextToken =
+		!Array.isArray(rawPayload) && typeof rawPayload.nextCursor === "string"
+			? rawPayload.nextCursor
+			: null;
+
+	return {
+		data,
+		meta: {
+			result_count: data.length,
+			page_count:
+				data.length > 0 ? Math.max(1, Math.ceil(data.length / maxResults)) : 1,
+			next_token: nextToken,
+		},
+	};
+}
+
+export async function listFollowUsersViaBird({
+	direction,
+	userId,
+	maxResults,
+	all,
+	maxPages,
+}: {
+	direction: "followers" | "following";
+	userId?: string;
+	maxResults: number;
+	all?: boolean;
+	maxPages?: number;
+}): Promise<XurlFollowUsersResponse> {
+	const args = [direction, "-n", String(maxResults), "--json"];
+	if (userId) {
+		args.push("--user", userId);
+	}
+	if (all) {
+		args.push("--all");
+	}
+	if (maxPages !== undefined) {
+		args.push("--max-pages", String(maxPages));
+	}
+	const stdout = await runBirdJsonCommand(args);
+	const payload = parseBirdJson(stdout);
+
+	return normalizeBirdFollowUsers(payload, direction, maxResults);
+}
+
 export async function listThreadViaBird({
 	tweetId,
 	all,

package/src/lib/config.ts

@@ -172,7 +172,7 @@ export function getBirdCommand() {
 		return pathCommand;
 	}
 
-	return path.join(os.homedir(), "Projects", "bird", "bird");
+	return "bird";
 }
 
 export function ensureBirdclawDirs(): BirdclawPaths {