birdclaw 0.8.1 → 0.8.3

package/src/cli.ts

@@ -6,6 +6,11 @@ import process from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command } from "commander";
 import { registerModerationCommands } from "#/cli-moderation";
+import { registerAnalysisCommands } from "#/cli/register-analysis";
+import { registerComposeCommands } from "#/cli/register-compose";
+import { registerGraphCommands } from "#/cli/register-graph";
+import { registerInboxCommand } from "#/cli/register-inbox";
+import { registerStorageCommands } from "#/cli/register-storage";
 import { findArchives } from "#/lib/archive-finder";
 import {
 	ARCHIVE_IMPORT_SLICES,
@@ -25,14 +30,7 @@ import {
 	parseAccountSyncSteps,
 	runAccountSyncJob,
 } from "#/lib/account-sync-job";
-import {
-	exportBackup,
-	importBackup,
-	maybeAutoSyncBackup,
-	maybeAutoUpdateBackup,
-	syncBackup,
-	validateBackup,
-} from "#/lib/backup";
+import { maybeAutoSyncBackup, maybeAutoUpdateBackup } from "#/lib/backup";
 import {
 	installBookmarkSyncLaunchAgent,
 	runBookmarkSyncJob,
@@ -42,7 +40,6 @@ import { importBlocklist } from "#/lib/blocklist";
 import {
 	type ActionsTransport,
 	ensureBirdclawDirs,
-	getBirdclawPaths,
 	resolveMentionsDataSource,
 	setActionsTransport,
 } from "#/lib/config";
@@ -51,7 +48,6 @@ import {
 	type DirectMessagesSyncMode,
 	syncDirectMessagesViaCachedBird,
 } from "#/lib/dms-live";
-import { listInboxItems, scoreInbox } from "#/lib/inbox";
 import { backfillLinkIndex, searchLinks } from "#/lib/link-index";
 import { fetchTweetMedia, formatMediaFetchResult } from "#/lib/media-fetch";
 import { syncMentionThreads } from "#/lib/mention-threads-live";
@@ -62,39 +58,12 @@ import {
 	exportMentionsViaCachedXurl,
 	syncMentions,
 } from "#/lib/mentions-live";
-import {
-	normalizeDigestLanguage,
-	streamPeriodDigest,
-	type PeriodDigestOptions,
-	type PeriodDigestPreset,
-} from "#/lib/period-digest";
-import {
-	streamProfileAnalysis,
-	type ProfileAnalysisOptions,
-} from "#/lib/profile-analysis";
-import {
-	getFollowGraphSummary,
-	listFollowEvents,
-	listMutuals,
-	listNonMutualFollowing,
-	listTopFollowers,
-	listUnfollowedSince,
-	syncFollowGraph,
-} from "#/lib/follow-graph";
+import { syncFollowGraph } from "#/lib/follow-graph";
 import { hydrateProfilesFromX } from "#/lib/profile-hydration";
 import { resolveProfilesForIds } from "#/lib/profile-resolver";
 import { inspectProfileReplies } from "#/lib/profile-replies";
-import { runResearchMode } from "#/lib/research";
-import {
-	streamSearchDiscussion,
-	type SearchDiscussionOptions,
-	type SearchDiscussionSource,
-} from "#/lib/search-discussion";
 import {
 	applyDmRequestMutationToLocalStore,
-	createDmReply,
-	createPost,
-	createTweetReply,
 	getQueryEnvelope,
 	listDmConversations,
 	listTimelineItems,
@@ -281,18 +250,6 @@ function parseDmSyncModeOption(
 	return undefined;
 }
 
-function parseDigestLiveModeOption(
-	value: string | undefined,
-): PeriodDigestOptions["liveSyncMode"] {
-	const normalized = (value ?? "xurl").trim().toLowerCase();
-	if (normalized === "auto" || normalized === "bird" || normalized === "xurl") {
-		return normalized;
-	}
-	printError("--live-mode must be auto, bird, or xurl");
-	process.exitCode = 1;
-	return undefined;
-}
-
 function parseArchiveImportSelect(value: string | undefined) {
 	if (value === undefined) {
 		return undefined;
@@ -358,316 +315,6 @@ function parseActionsTransport(value: string | undefined) {
 	return undefined;
 }
 
-function parseDigestPeriod(value: string | undefined): PeriodDigestPreset {
-	const normalized = value?.trim().toLowerCase();
-	if (normalized === "yesterday") return "yesterday";
-	if (normalized === "24h" || normalized === "day") return "24h";
-	if (normalized === "week" || normalized === "7d") return "week";
-	return "today";
-}
-
-function buildDigestOptions(
-	period: string | undefined,
-	options: {
-		account?: string;
-		includeDms?: boolean;
-		model?: string;
-		language?: string;
-		refresh?: boolean;
-		since?: string;
-		until?: string;
-		maxTweets?: string;
-		maxLinks?: string;
-		liveSync?: boolean;
-		liveMode?: string;
-	},
-): PeriodDigestOptions | null {
-	const maxTweets = parseNonNegativeIntegerOption(
-		options.maxTweets,
-		"--max-tweets",
-	);
-	if (options.maxTweets !== undefined && maxTweets === undefined) {
-		return null;
-	}
-	const maxLinks = parseNonNegativeIntegerOption(
-		options.maxLinks,
-		"--max-links",
-	);
-	if (options.maxLinks !== undefined && maxLinks === undefined) {
-		return null;
-	}
-	const liveSyncMode = parseDigestLiveModeOption(options.liveMode);
-	if (liveSyncMode === undefined) {
-		return null;
-	}
-	let language: string | undefined;
-	try {
-		language = normalizeDigestLanguage(options.language);
-	} catch (error) {
-		printError(error instanceof Error ? error.message : String(error));
-		process.exitCode = 1;
-		return null;
-	}
-	return {
-		period: parseDigestPeriod(period),
-		since: options.since,
-		until: options.until,
-		account: options.account,
-		includeDms: Boolean(options.includeDms),
-		refresh: Boolean(options.refresh),
-		model: options.model,
-		language,
-		maxTweets,
-		maxLinks,
-		liveSync: options.liveSync !== false,
-		liveSyncMode,
-	};
-}
-
-function runDigestCli(options: PeriodDigestOptions) {
-	const asJson = Boolean(program.opts().json);
-	return streamPeriodDigest(options, {
-		onDelta: asJson
-			? undefined
-			: (delta) => {
-					process.stdout.write(delta);
-				},
-	}).then((result) => {
-		if (asJson) {
-			print(result, true);
-			return;
-		}
-		if (!result.markdown.endsWith("\n")) {
-			process.stdout.write("\n");
-		}
-	});
-}
-
-function parseSearchDiscussionSource(
-	value: string | undefined,
-): SearchDiscussionSource | undefined {
-	const normalized = (value ?? "all").trim().toLowerCase();
-	if (
-		normalized === "all" ||
-		normalized === "home" ||
-		normalized === "mentions" ||
-		normalized === "authored" ||
-		normalized === "search" ||
-		normalized === "likes" ||
-		normalized === "bookmarks"
-	) {
-		return normalized;
-	}
-	printError(
-		"--source must be all, search, home, mentions, authored, likes, or bookmarks",
-	);
-	process.exitCode = 1;
-	return undefined;
-}
-
-function parseTweetSearchMode(value: string | undefined) {
-	const normalized = (value ?? "auto").trim().toLowerCase();
-	if (
-		normalized === "auto" ||
-		normalized === "bird" ||
-		normalized === "xurl" ||
-		normalized === "local"
-	) {
-		return normalized;
-	}
-	printError("--mode must be auto, bird, xurl, or local");
-	process.exitCode = 1;
-	return undefined;
-}
-
-function buildSearchDiscussionOptions(
-	query: string,
-	options: {
-		account?: string;
-		source?: string;
-		includeDms?: boolean;
-		since?: string;
-		until?: string;
-		question?: string;
-		originalsOnly?: boolean;
-		hideLowQuality?: boolean;
-		mode?: string;
-		model?: string;
-		refresh?: boolean;
-		limit?: string;
-		maxPages?: string;
-	},
-): SearchDiscussionOptions | null {
-	const source = parseSearchDiscussionSource(options.source);
-	if (!source) return null;
-	const mode = parseTweetSearchMode(options.mode);
-	if (!mode) return null;
-	const limit = parsePositiveIntegerOption(options.limit, "--limit");
-	if (options.limit !== undefined && limit === undefined) {
-		return null;
-	}
-	const maxPages = parsePositiveIntegerOption(options.maxPages, "--max-pages");
-	if (options.maxPages !== undefined && maxPages === undefined) {
-		return null;
-	}
-	return {
-		query,
-		account: options.account,
-		source,
-		includeDms: Boolean(options.includeDms),
-		since: options.since,
-		until: options.until,
-		question: options.question,
-		originalsOnly: Boolean(options.originalsOnly),
-		hideLowQuality: Boolean(options.hideLowQuality),
-		mode,
-		model: options.model,
-		refresh: Boolean(options.refresh),
-		limit,
-		maxPages,
-	};
-}
-
-function runSearchDiscussionCli(options: SearchDiscussionOptions) {
-	const asJson = Boolean(program.opts().json);
-	return streamSearchDiscussion(options, {
-		onDelta: asJson
-			? undefined
-			: (delta) => {
-					process.stdout.write(delta);
-				},
-	}).then((result) => {
-		if (asJson) {
-			print(result, true);
-			return;
-		}
-		if (!result.markdown.endsWith("\n")) {
-			process.stdout.write("\n");
-		}
-	});
-}
-
-function buildProfileAnalysisOptions(
-	handle: string,
-	options: {
-		account?: string;
-		model?: string;
-		refresh?: boolean;
-		maxTweets?: string;
-		maxPages?: string;
-		maxConversations?: string;
-		maxConversationPages?: string;
-		conversationDelayMs?: string;
-		rateLimitRetryMs?: string;
-		rateLimitRetries?: string;
-	},
-): ProfileAnalysisOptions | null {
-	const maxTweets = parsePositiveIntegerOption(
-		options.maxTweets,
-		"--max-tweets",
-	);
-	if (options.maxTweets !== undefined && maxTweets === undefined) {
-		return null;
-	}
-	const maxPages = parsePositiveIntegerOption(options.maxPages, "--max-pages");
-	if (options.maxPages !== undefined && maxPages === undefined) {
-		return null;
-	}
-	const maxConversations = parsePositiveIntegerOption(
-		options.maxConversations,
-		"--max-conversations",
-	);
-	if (
-		options.maxConversations !== undefined &&
-		maxConversations === undefined
-	) {
-		return null;
-	}
-	const maxConversationPages = parsePositiveIntegerOption(
-		options.maxConversationPages,
-		"--max-conversation-pages",
-	);
-	if (
-		options.maxConversationPages !== undefined &&
-		maxConversationPages === undefined
-	) {
-		return null;
-	}
-	const conversationDelayMs = parseNonNegativeIntegerOption(
-		options.conversationDelayMs,
-		"--conversation-delay-ms",
-	);
-	if (
-		options.conversationDelayMs !== undefined &&
-		conversationDelayMs === undefined
-	) {
-		return null;
-	}
-	const rateLimitRetryMs = parseNonNegativeIntegerOption(
-		options.rateLimitRetryMs,
-		"--rate-limit-retry-ms",
-	);
-	if (
-		options.rateLimitRetryMs !== undefined &&
-		rateLimitRetryMs === undefined
-	) {
-		return null;
-	}
-	const rateLimitMaxRetries = parseNonNegativeIntegerOption(
-		options.rateLimitRetries,
-		"--rate-limit-retries",
-	);
-	if (
-		options.rateLimitRetries !== undefined &&
-		rateLimitMaxRetries === undefined
-	) {
-		return null;
-	}
-	return {
-		handle,
-		account: options.account,
-		model: options.model,
-		refresh: Boolean(options.refresh),
-		maxTweets,
-		maxPages,
-		maxConversations,
-		maxConversationPages,
-		conversationDelayMs,
-		rateLimitRetryMs,
-		rateLimitMaxRetries,
-	};
-}
-
-function runProfileAnalysisCli(options: ProfileAnalysisOptions) {
-	const asJson = Boolean(program.opts().json);
-	return streamProfileAnalysis(options, {
-		onDelta: asJson
-			? undefined
-			: (delta) => {
-					process.stdout.write(delta);
-				},
-		onEvent: asJson
-			? undefined
-			: (event) => {
-					if (event.type === "status") {
-						process.stderr.write(
-							event.detail
-								? `${event.label}: ${event.detail}\n`
-								: `${event.label}\n`,
-						);
-					}
-				},
-	}).then((result) => {
-		if (asJson) {
-			print(result, true);
-			return;
-		}
-		if (!result.markdown.endsWith("\n")) {
-			process.stdout.write("\n");
-		}
-	});
-}
-
 async function enrichDmItems(
 	query: Parameters<typeof listDmConversations>[0],
 	options: {
@@ -1197,135 +844,15 @@ program
 		);
 	});
 
-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,
-		);
-	});
-
-program
-	.command("discuss <query>")
-	.description("Search live/local tweets and summarize the results with AI")
-	.option("--account <accountId>", "Account id")
-	.option(
-		"--source <source>",
-		"all, search, home, mentions, authored, likes, or bookmarks",
-		"search",
-	)
-	.option("--mode <mode>", "auto, bird, xurl, or local", "xurl")
-	.option("--include-dms", "Include private DM search matches")
-	.option("--since <isoDate>", "Include matches created at or after this date")
-	.option("--until <isoDate>", "Include matches created before this date")
-	.option("--question <prompt>", "Discussion question or angle")
-	.option("--originals-only", "Exclude authored replies that start with @")
-	.option("--hide-low-quality", "Hide RTs, tiny replies, and link-only noise")
-	.option("--model <model>", "OpenAI model id")
-	.option("--refresh", "Bypass the local discussion cache")
-	.option("--limit <n>", "Maximum tweet context", "20000")
-	.option("--max-pages <n>", "Maximum live search pages", "200")
-	.action(async (query, options) => {
-		await autoUpdateBeforeRead();
-		const discussionOptions = buildSearchDiscussionOptions(query, options);
-		if (!discussionOptions) return;
-		await runSearchDiscussionCli(discussionOptions);
-	});
-
-program
-	.command("profile-analyze <handle>")
-	.alias("profile-analyse")
-	.description("Backfill a profile with xurl and summarize it with AI")
-	.option("--account <accountId>", "Account id")
-	.option("--model <model>", "OpenAI model id")
-	.option("--refresh", "Bypass profile fetch and analysis caches")
-	.option("--max-tweets <n>", "Maximum profile tweets", "10000")
-	.option("--max-pages <n>", "Maximum profile timeline pages", "100")
-	.option("--max-conversations <n>", "Maximum conversations to backfill", "80")
-	.option("--max-conversation-pages <n>", "Maximum pages per conversation", "3")
-	.option(
-		"--conversation-delay-ms <n>",
-		"Delay between conversation search calls",
-	)
-	.option(
-		"--rate-limit-retry-ms <n>",
-		"Delay before retrying conversation 429s",
-	)
-	.option("--rate-limit-retries <n>", "Conversation 429 retry count")
-	.action(async (handle, options) => {
-		await autoUpdateBeforeRead();
-		const analysisOptions = buildProfileAnalysisOptions(handle, options);
-		if (!analysisOptions) return;
-		await runProfileAnalysisCli(analysisOptions);
-	});
-
-program
-	.command("today")
-	.description("Stream an AI digest of what happened today")
-	.option("--account <accountId>", "Account id")
-	.option("--include-dms", "Include private DM context")
-	.option("--model <model>", "OpenAI model id")
-	.option(
-		"--language <tag>",
-		"Report language as a Unicode locale id, e.g. zh-CN (env: BIRDCLAW_DIGEST_LANGUAGE)",
-	)
-	.option("--refresh", "Bypass the local digest cache")
-	.option("--max-tweets <n>", "Maximum tweet context", "5000")
-	.option("--max-links <n>", "Maximum linked articles", "12")
-	.option("--no-live-sync", "Use only the local database")
-	.option(
-		"--live-mode <mode>",
-		"Live timeline mode: xurl, bird, or auto",
-		"xurl",
-	)
-	.action(async (options) => {
-		await autoUpdateBeforeRead();
-		const digestOptions = buildDigestOptions("today", options);
-		if (!digestOptions) return;
-		await runDigestCli(digestOptions);
-	});
-
-program
-	.command("digest [period]")
-	.description("Stream an AI digest for today, 24h, yesterday, or week")
-	.option("--account <accountId>", "Account id")
-	.option("--include-dms", "Include private DM context")
-	.option("--since <isoDate>", "Start of explicit window")
-	.option("--until <isoDate>", "End of explicit window")
-	.option("--model <model>", "OpenAI model id")
-	.option(
-		"--language <tag>",
-		"Report language as a Unicode locale id, e.g. zh-CN (env: BIRDCLAW_DIGEST_LANGUAGE)",
-	)
-	.option("--refresh", "Bypass the local digest cache")
-	.option("--max-tweets <n>", "Maximum tweet context", "5000")
-	.option("--max-links <n>", "Maximum linked articles", "12")
-	.option("--no-live-sync", "Use only the local database")
-	.option(
-		"--live-mode <mode>",
-		"Live timeline mode: xurl, bird, or auto",
-		"xurl",
-	)
-	.action(async (period, options) => {
-		await autoUpdateBeforeRead();
-		const digestOptions = buildDigestOptions(period, options);
-		if (!digestOptions) return;
-		await runDigestCli(digestOptions);
-	});
+registerAnalysisCommands({
+	program,
+	print,
+	asJson: () => program.opts().json ?? false,
+	autoSyncAfterWrite,
+	autoUpdateBeforeRead,
+	parseNonNegativeIntegerOption,
+	parsePositiveIntegerOption,
+});
 
 const mentionsCommand = program
 	.command("mentions")
@@ -1964,7 +1491,7 @@ for (const action of ["accept", "reject", "block"] as const) {
 			...(action === "block" && options.allPages ? { allPages: true } : {}),
 		});
 		if (result.success) {
-			applyDmRequestMutationToLocalStore(conversationId, action);
+			await applyDmRequestMutationToLocalStore(conversationId, action);
 		} else {
 			process.exitCode = 1;
 		}
@@ -1981,269 +1508,22 @@ registerModerationCommands({
 	resolveActionOptions,
 });
 
-const composeCommand = program
-	.command("compose")
-	.description("Create local/xurl actions");
-
-composeCommand
-	.command("post <text>")
-	.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);
-	});
-
-composeCommand
-	.command("reply <tweetId> <text>")
-	.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);
-	});
-
-composeCommand
-	.command("dm <conversationId> <text>")
-	.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);
-	});
-
-program
-	.command("inbox")
-	.option("--kind <kind>", "mixed, mentions, or dms", "mixed")
-	.option("--min-score <n>", "Minimum rank", "0")
-	.option("--hide-low-signal", "Hide low-signal items")
-	.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
-				: "mixed";
-		if (options.score) {
-			await scoreInbox({
-				kind,
-				limit: Number(options.limit),
-			});
-			await autoSyncAfterWrite();
-		}
-		print(
-			listInboxItems({
-				kind,
-				minScore: Number(options.minScore),
-				hideLowSignal: Boolean(options.hideLowSignal),
-				limit: Number(options.limit),
-			}),
-			program.opts().json ?? false,
-		);
-	});
-
-const graphCommand = program
-	.command("graph")
-	.description("Query the local cache-only follow graph");
-
-graphCommand
-	.command("summary")
-	.description("Summarize cached followers, following, mutuals, and snapshots")
-	.option("--account <accountId>", "Account id")
-	.action(async (options) => {
-		await autoUpdateBeforeRead();
-		print(getFollowGraphSummary({ account: options.account }), true);
-	});
-
-graphCommand
-	.command("top-followers")
-	.description("List current followers sorted by their follower count")
-	.option("--account <accountId>", "Account id")
-	.option("--limit <n>", "Limit results", "20")
-	.action(async (options) => {
-		await autoUpdateBeforeRead();
-		print(
-			listTopFollowers({
-				account: options.account,
-				limit: Number(options.limit),
-			}),
-			true,
-		);
-	});
-
-graphCommand
-	.command("unfollowed")
-	.description("List cached ended follow edges since a date")
-	.requiredOption("--date <date>", "YYYY-MM-DD or ISO timestamp")
-	.option("--account <accountId>", "Account id")
-	.option("--direction <direction>", "followers or following", "followers")
-	.option("--limit <n>", "Limit results", "100")
-	.action(async (options) => {
-		await autoUpdateBeforeRead();
-		print(
-			listUnfollowedSince({
-				account: options.account,
-				date: options.date,
-				direction:
-					options.direction === "following" ? "following" : "followers",
-				limit: Number(options.limit),
-			}),
-			true,
-		);
-	});
-
-graphCommand
-	.command("events")
-	.description("List cached append-only follow graph events")
-	.option("--account <accountId>", "Account id")
-	.option("--direction <direction>", "followers or following")
-	.option("--kind <kind>", "started or ended")
-	.option("--since <date>", "YYYY-MM-DD or ISO timestamp")
-	.option("--until <date>", "YYYY-MM-DD or ISO timestamp")
-	.option("--limit <n>", "Limit results", "100")
-	.action(async (options) => {
-		await autoUpdateBeforeRead();
-		print(
-			listFollowEvents({
-				account: options.account,
-				direction:
-					options.direction === "followers" || options.direction === "following"
-						? options.direction
-						: undefined,
-				kind:
-					options.kind === "started" || options.kind === "ended"
-						? options.kind
-						: undefined,
-				since: options.since,
-				until: options.until,
-				limit: Number(options.limit),
-			}),
-			true,
-		);
-	});
-
-graphCommand
-	.command("non-mutual-following")
-	.description("List current following who are not current followers")
-	.option("--account <accountId>", "Account id")
-	.option("--sort <mode>", "followers or handle", "followers")
-	.option("--limit <n>", "Limit results", "100")
-	.action(async (options) => {
-		await autoUpdateBeforeRead();
-		print(
-			listNonMutualFollowing({
-				account: options.account,
-				sort: options.sort === "handle" ? "handle" : "followers",
-				limit: Number(options.limit),
-			}),
-			true,
-		);
-	});
-
-graphCommand
-	.command("mutuals")
-	.description("List profiles that are both followers and following")
-	.option("--account <accountId>", "Account id")
-	.option("--limit <n>", "Limit results", "100")
-	.action(async (options) => {
-		await autoUpdateBeforeRead();
-		print(
-			listMutuals({
-				account: options.account,
-				limit: Number(options.limit),
-			}),
-			true,
-		);
-	});
-
-program
-	.command("db stats")
-	.description("Show local storage and dataset stats")
-	.action(async () => {
-		await autoUpdateBeforeRead();
-		const meta = await getQueryEnvelope();
-		const paths = getBirdclawPaths();
-		print(
-			{
-				paths,
-				stats: meta.stats,
-				transport: meta.transport,
-			},
-			program.opts().json ?? false,
-		);
-	});
-
-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);
-	});
+const commandContext = {
+	program,
+	print,
+	asJson: () => program.opts().json ?? false,
+	autoSyncAfterWrite,
+	autoUpdateBeforeRead,
+	parseNonNegativeIntegerOption,
+	parsePositiveIntegerOption,
+};
 
-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);
-	});
+registerComposeCommands(commandContext);
+registerInboxCommand(commandContext);
 
-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);
-	});
+registerGraphCommands(commandContext);
 
-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;
-		}
-	});
+registerStorageCommands(commandContext);
 
 program
 	.command("serve")