birdclaw 0.5.1 → 0.7.0

package/src/lib/bird-actions.ts

@@ -1,10 +1,22 @@
-import { runBirdCommand } from "./bird-command";
+import { Effect } from "effect";
+import {
+	BirdCommandExecutionError,
+	runBirdCommandEffect,
+} from "./bird-command";
+import { runEffectPromise } from "./effect-runtime";
 import type { XurlMentionUser } from "./types";
 
 function liveWritesDisabled() {
 	return process.env.BIRDCLAW_DISABLE_LIVE_WRITES === "1";
 }
 
+function e2eFakeLiveWritesEnabled() {
+	return (
+		process.env.BIRDCLAW_E2E === "1" &&
+		process.env.BIRDCLAW_E2E_FAKE_LIVE_WRITES === "1"
+	);
+}
+
 function stripAnsi(value: string) {
 	// ANSI escape parsing needs a constructor to avoid literal control characters.
 	return value.replace(new RegExp("\\u001b\\[[0-9;]*m", "g"), "");
@@ -14,6 +26,9 @@ function formatExecError(error: unknown, fallback: string) {
 	if (!(error instanceof Error)) {
 		return fallback;
 	}
+	if (error instanceof BirdCommandExecutionError && error.useFallbackMessage) {
+		return fallback;
+	}
 
 	const parts = [error.message];
 	if (
@@ -38,18 +53,43 @@ function normalizeOutput(stdout?: string, stderr?: string) {
 	return stripAnsi(stdout || stderr || "ok").trim();
 }
 
-async function runBirdJsonCommand(args: string[]) {
-	const { stdout } = await runBirdCommand(args);
-	return JSON.parse(stripAnsi(stdout)) as Record<string, unknown>;
+function toError(error: unknown) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+
+function runBirdJsonCommandEffect(args: string[]) {
+	return Effect.gen(function* () {
+		const { stdout } = yield* runBirdCommandEffect(args);
+		return yield* Effect.try({
+			try: () => JSON.parse(stripAnsi(stdout)) as Record<string, unknown>,
+			catch: toError,
+		});
+	});
 }
 
-export async function readBirdStatusViaBird(query: string) {
-	try {
-		const payload = await runBirdJsonCommand(["status", query, "--json"]);
-		return payload;
-	} catch {
-		return null;
+function safeBirdProfileArg(query: string) {
+	const normalized = query.trim().replace(/^@/, "");
+	if (
+		/^\d{1,30}$/.test(normalized) ||
+		/^[A-Za-z0-9_]{1,15}$/.test(normalized)
+	) {
+		return normalized;
 	}
+	throw new Error("Invalid bird profile query");
+}
+
+export function readBirdStatusViaBirdEffect(query: string) {
+	return Effect.gen(function* () {
+		const safeQuery = yield* Effect.try({
+			try: () => safeBirdProfileArg(query),
+			catch: toError,
+		});
+		return yield* runBirdJsonCommandEffect(["status", safeQuery, "--json"]);
+	}).pipe(Effect.catchAll(() => Effect.succeed(null)));
+}
+
+export function readBirdStatusViaBird(query: string) {
+	return runEffectPromise(readBirdStatusViaBirdEffect(query));
 }
 
 function toBirdLookupUser(payload: Record<string, unknown>): XurlMentionUser {
@@ -112,22 +152,31 @@ function toBirdLookupUser(payload: Record<string, unknown>): XurlMentionUser {
 	};
 }
 
-export async function lookupProfileViaBird(query: string) {
-	try {
-		const payload = await runBirdJsonCommand([
+export function lookupProfileViaBirdEffect(query: string) {
+	return Effect.gen(function* () {
+		const safeQuery = yield* Effect.try({
+			try: () => safeBirdProfileArg(query),
+			catch: toError,
+		});
+		const payload = yield* runBirdJsonCommandEffect([
 			"user",
-			query,
+			safeQuery,
 			"-n",
 			"1",
 			"--json",
 		]);
-		return toBirdLookupUser(payload);
-	} catch {
-		return null;
-	}
+		return yield* Effect.try({
+			try: () => toBirdLookupUser(payload),
+			catch: toError,
+		});
+	}).pipe(Effect.catchAll(() => Effect.succeed(null)));
 }
 
-async function runVerifiedBirdMutation({
+export function lookupProfileViaBird(query: string) {
+	return runEffectPromise(lookupProfileViaBirdEffect(query));
+}
+
+function runVerifiedBirdMutationEffect({
 	action,
 	query,
 	verifyField,
@@ -138,45 +187,62 @@ async function runVerifiedBirdMutation({
 	verifyField: "blocking" | "muting";
 	expectedValue: boolean;
 }) {
-	if (liveWritesDisabled()) {
-		return { ok: true, output: "live writes disabled" };
-	}
+	return Effect.gen(function* () {
+		const safeQuery = yield* Effect.try({
+			try: () => safeBirdProfileArg(query),
+			catch: toError,
+		});
+		if (liveWritesDisabled()) {
+			if (e2eFakeLiveWritesEnabled()) {
+				return { ok: true, output: "e2e fake live write" };
+			}
+			return { ok: false, output: "live writes disabled" };
+		}
 
-	let baseOutput = "";
-	try {
-		const { stdout, stderr } = await runBirdCommand([action, query]);
-		baseOutput = normalizeOutput(stdout, stderr);
-	} catch (error) {
-		return {
-			ok: false,
-			output: formatExecError(error, `bird ${action} failed`),
-		};
-	}
+		const mutationResult = yield* runBirdCommandEffect([
+			action,
+			safeQuery,
+		]).pipe(
+			Effect.map(({ stdout, stderr }) => ({
+				ok: true as const,
+				output: normalizeOutput(stdout, stderr),
+			})),
+			Effect.catchAll((error) =>
+				Effect.succeed({
+					ok: false as const,
+					output: formatExecError(error, `bird ${action} failed`),
+				}),
+			),
+		);
+		if (!mutationResult.ok) {
+			return mutationResult;
+		}
 
-	const status = await readBirdStatusViaBird(query);
-	if (!status || typeof status[verifyField] !== "boolean") {
-		return {
-			ok: false,
-			output: `${baseOutput}; bird status verify unavailable`,
-		};
-	}
+		const status = yield* readBirdStatusViaBirdEffect(query);
+		if (!status || typeof status[verifyField] !== "boolean") {
+			return {
+				ok: false,
+				output: `${mutationResult.output}; bird status verify unavailable`,
+			};
+		}
+
+		const actualValue = Boolean(status[verifyField]);
+		if (actualValue !== expectedValue) {
+			return {
+				ok: false,
+				output: `${mutationResult.output}; bird status verify ${verifyField}=${String(actualValue)}`,
+			};
+		}
 
-	const actualValue = Boolean(status[verifyField]);
-	if (actualValue !== expectedValue) {
 		return {
-			ok: false,
-			output: `${baseOutput}; bird status verify ${verifyField}=${String(actualValue)}`,
+			ok: true,
+			output: `${mutationResult.output}; verified ${verifyField}=${String(actualValue)}`,
 		};
-	}
-
-	return {
-		ok: true,
-		output: `${baseOutput}; verified ${verifyField}=${String(actualValue)}`,
-	};
+	});
 }
 
-export async function blockUserViaBird(query: string) {
-	return runVerifiedBirdMutation({
+export function blockUserViaBirdEffect(query: string) {
+	return runVerifiedBirdMutationEffect({
 		action: "block",
 		query,
 		verifyField: "blocking",
@@ -184,8 +250,12 @@ export async function blockUserViaBird(query: string) {
 	});
 }
 
-export async function unblockUserViaBird(query: string) {
-	return runVerifiedBirdMutation({
+export function blockUserViaBird(query: string) {
+	return runEffectPromise(blockUserViaBirdEffect(query));
+}
+
+export function unblockUserViaBirdEffect(query: string) {
+	return runVerifiedBirdMutationEffect({
 		action: "unblock",
 		query,
 		verifyField: "blocking",
@@ -193,8 +263,12 @@ export async function unblockUserViaBird(query: string) {
 	});
 }
 
-export async function muteUserViaBird(query: string) {
-	return runVerifiedBirdMutation({
+export function unblockUserViaBird(query: string) {
+	return runEffectPromise(unblockUserViaBirdEffect(query));
+}
+
+export function muteUserViaBirdEffect(query: string) {
+	return runVerifiedBirdMutationEffect({
 		action: "mute",
 		query,
 		verifyField: "muting",
@@ -202,11 +276,19 @@ export async function muteUserViaBird(query: string) {
 	});
 }
 
-export async function unmuteUserViaBird(query: string) {
-	return runVerifiedBirdMutation({
+export function muteUserViaBird(query: string) {
+	return runEffectPromise(muteUserViaBirdEffect(query));
+}
+
+export function unmuteUserViaBirdEffect(query: string) {
+	return runVerifiedBirdMutationEffect({
 		action: "unmute",
 		query,
 		verifyField: "muting",
 		expectedValue: false,
 	});
 }
+
+export function unmuteUserViaBird(query: string) {
+	return runEffectPromise(unmuteUserViaBirdEffect(query));
+}

package/src/lib/bird-command.ts

@@ -3,10 +3,30 @@ import type { ExecFileOptions } from "node:child_process";
 import { access } from "node:fs/promises";
 import { constants } from "node:fs";
 import { promisify } from "node:util";
+import { Data, Effect } from "effect";
 import { getBirdCommand } from "./config";
+import { runEffectPromise } from "./effect-runtime";
 
 const execFileAsync = promisify(execFile);
 
+export class BirdCommandUnavailableError extends Data.TaggedError(
+	"BirdCommandUnavailableError",
+)<{
+	readonly message: string;
+	readonly command: string;
+	readonly cause?: unknown;
+}> {}
+
+export class BirdCommandExecutionError extends Data.TaggedError(
+	"BirdCommandExecutionError",
+)<{
+	readonly message: string;
+	readonly stdout?: string;
+	readonly stderr?: string;
+	readonly useFallbackMessage?: boolean;
+	readonly cause?: unknown;
+}> {}
+
 function isPathCommand(command: string) {
 	return command.includes("/") || command.startsWith(".");
 }
@@ -18,40 +38,93 @@ function formatBirdInstallHint(command: string) {
 	].join("\n");
 }
 
-async function assertBirdCommandAvailable(command: string) {
-	if (!isPathCommand(command)) {
-		return;
+function isUnavailableExecError(error: unknown) {
+	return (
+		error &&
+		typeof error === "object" &&
+		"code" in error &&
+		(error.code === "ENOENT" || error.code === "EACCES")
+	);
+}
+
+function execFailureFromCause(command: string, cause: unknown) {
+	if (isUnavailableExecError(cause)) {
+		return new BirdCommandUnavailableError({
+			message: formatBirdInstallHint(command),
+			command,
+			cause,
+		});
 	}
+	if (cause instanceof Error) {
+		const output = cause as Error & {
+			stdout?: unknown;
+			stderr?: unknown;
+		};
+		return new BirdCommandExecutionError({
+			message: cause.message,
+			stdout: typeof output.stdout === "string" ? output.stdout : undefined,
+			stderr: typeof output.stderr === "string" ? output.stderr : undefined,
+			cause,
+		});
+	}
+	return new BirdCommandExecutionError({
+		message: "",
+		useFallbackMessage: true,
+		cause,
+	});
+}
 
-	try {
-		await access(command, constants.X_OK);
-	} catch {
-		throw new Error(formatBirdInstallHint(command));
+function assertBirdCommandAvailableEffect(command: string) {
+	if (!isPathCommand(command)) {
+		return Effect.void;
 	}
+
+	return Effect.tryPromise({
+		try: () => Promise.resolve(access(command, constants.X_OK)),
+		catch: (cause) =>
+			new BirdCommandUnavailableError({
+				message: formatBirdInstallHint(command),
+				command,
+				cause,
+			}),
+	}).pipe(Effect.asVoid);
 }
 
-export async function runBirdCommand(
+function getBirdCommandEffect() {
+	return Effect.try({
+		try: () => getBirdCommand(),
+		catch: (cause) =>
+			cause instanceof Error ? cause : new Error(String(cause)),
+	});
+}
+
+export function runBirdCommandEffect(
 	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);
+): Effect.Effect<
+	{ stdout: string; stderr: string },
+	BirdCommandExecutionError | BirdCommandUnavailableError | Error
+> {
+	return Effect.gen(function* () {
+		const birdCommand = yield* getBirdCommandEffect();
+		yield* assertBirdCommandAvailableEffect(birdCommand);
+
+		const result = yield* Effect.tryPromise({
+			try: () =>
+				Promise.resolve(
+					options === undefined
+						? execFileAsync(birdCommand, args)
+						: execFileAsync(birdCommand, args, options),
+				),
+			catch: (cause) => execFailureFromCause(birdCommand, cause),
+		});
 		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;
-	}
+	});
+}
+
+export function runBirdCommand(
+	args: string[],
+	options?: ExecFileOptions,
+): Promise<{ stdout: string; stderr: string }> {
+	return runEffectPromise(runBirdCommandEffect(args, options));
 }