feat(cli): add --file flag to 'dispatch send' subcommand

Add the same --file <path> support that the summon (chat) command has to the
'dispatch send' subcommand. When --file is given, the file's contents are read
and attached to the message (composed via composeMessage, identical to chat).

- args.ts: add 'file' to the send ParsedCommand, make 'text' optional, parse
  --file, and require at least one of --text or --file.
- main.ts: read the file and compose the message in the send case, using the
  composed message in both the --queue and streaming branches; update USAGE.
- args.test.ts: cover --file parsing (alone, with --text, missing value) and
  update the existing send expectations + the both-missing error message.

1 files changed, 31 insertions, 2 deletions

diff --git a/packages/cli/src/args.test.ts b/packages/cli/src/args.test.ts
index 3d07c96..7a45c02 100644
--- a/packages/cli/src/args.test.ts
+++ b/packages/cli/src/args.test.ts
@@ -320,11 +320,31 @@ describe("parseArgs", () => {
 				server: "http://localhost:24203",
 				conversationId: "deadbeef",
 				text: "hi",
+				file: undefined,
+				queue: false,
+				open: false,
+			});
+		});
+
+		it("parses 'send' with --file", () => {
+			expect(parseArgs(["send", "deadbeef", "--file", "foo.txt"], { defaultServer })).toEqual({
+				kind: "send",
+				server: "http://localhost:24203",
+				conversationId: "deadbeef",
+				text: undefined,
+				file: "foo.txt",
 				queue: false,
 				open: false,
 			});
 		});
 
+		it("parses 'send' with both --text and --file", () => {
+			const result = parseArgs(["send", "deadbeef", "--text", "hi", "--file", "f.txt"], {
+				defaultServer,
+			});
+			expect(result).toMatchObject({ kind: "send", text: "hi", file: "f.txt" });
+		});
+
 		it("parses 'send' with --queue", () => {
 			const result = parseArgs(["send", "deadbeef", "--text", "hi", "--queue"], {
 				defaultServer,
@@ -334,6 +354,7 @@ describe("parseArgs", () => {
 				server: "http://localhost:24203",
 				conversationId: "deadbeef",
 				text: "hi",
+				file: undefined,
 				queue: true,
 				open: false,
 			});
@@ -348,6 +369,7 @@ describe("parseArgs", () => {
 				server: "http://localhost:24203",
 				conversationId: "deadbeef",
 				text: "hi",
+				file: undefined,
 				queue: false,
 				open: true,
 			});
@@ -363,6 +385,7 @@ describe("parseArgs", () => {
 				server: "http://localhost:24203",
 				conversationId: "deadbeef",
 				text: "hi",
+				file: undefined,
 				queue: false,
 				open: false,
 				cwd: "/tmp",
@@ -370,10 +393,10 @@ describe("parseArgs", () => {
 			});
 		});
 
-		it("requires --text", () => {
+		it("errors when --text and --file are both missing", () => {
 			const result = parseArgs(["send", "deadbeef"], { defaultServer });
 			expect(result.kind).toBe("error");
-			if (result.kind === "error") expect(result.message).toContain("--text");
+			if (result.kind === "error") expect(result.message).toContain("--text or --file");
 		});
 
 		it("requires a conversation id", () => {
@@ -386,6 +409,12 @@ describe("parseArgs", () => {
 			const result = parseArgs(["send", "deadbeef", "--text"], { defaultServer });
 			expect(result.kind).toBe("error");
 		});
+
+		it("errors when --file has no value", () => {
+			const result = parseArgs(["send", "deadbeef", "--file"], { defaultServer });
+			expect(result.kind).toBe("error");
+			if (result.kind === "error") expect(result.message).toContain("--file requires a value");
+		});
 	});
 
 	describe("open", () => {