geekbot-cli 0.1.0

package/src/cli/commands/poll.ts

@@ -0,0 +1,91 @@
+import { Command } from "commander";
+import { handleError } from "../../errors/error-handler.ts";
+import {
+	handlePollCreate,
+	handlePollGet,
+	handlePollList,
+	handlePollVotes,
+} from "../../handlers/poll-handlers.ts";
+import { getGlobalOptions } from "../globals.ts";
+
+export function createPollCommand(): Command {
+	const poll = new Command("poll").description("Manage polls (Slack teams only)");
+
+	poll
+		.command("list")
+		.description("List all polls")
+		.addHelpText("after", "\nExamples:\n  geekbot poll list")
+		.action(async function (this: Command) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				await handlePollList(globalOpts);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	poll
+		.command("get")
+		.description("Get a poll by ID")
+		.argument("<id>", "Poll ID (numeric)")
+		.addHelpText("after", "\nExamples:\n  geekbot poll get 456")
+		.action(async function (this: Command, id: string) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				await handlePollGet(id, globalOpts);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	poll
+		.command("create")
+		.description("Create a new poll")
+		.requiredOption("--name <name>", "Poll name")
+		.requiredOption("--channel <channel>", "Slack channel")
+		.requiredOption("--question <text>", "Poll question text")
+		.requiredOption("--choices <json>", "Choices as JSON array of strings")
+		.addHelpText(
+			"after",
+			'\nExamples:\n  geekbot poll create --name "Lunch" --channel "#team" --question "Where?" --choices \'["Pizza", "Sushi"]\'',
+		)
+		.action(async function (this: Command) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handlePollCreate(
+					{
+						name: opts.name,
+						channel: opts.channel,
+						question: opts.question,
+						choices: opts.choices,
+					},
+					globalOpts,
+				);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	poll
+		.command("votes")
+		.description("Get voting results for a poll")
+		.argument("<id>", "Poll ID (numeric)")
+		.option("--after <date>", "Votes after date")
+		.option("--before <date>", "Votes before date")
+		.addHelpText(
+			"after",
+			"\nExamples:\n  geekbot poll votes 456\n  geekbot poll votes 456 --after 2024-01-01",
+		)
+		.action(async function (this: Command, id: string) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handlePollVotes(id, { after: opts.after, before: opts.before }, globalOpts);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	return poll;
+}

package/src/cli/commands/report.ts

@@ -0,0 +1,66 @@
+import { Command } from "commander";
+import { handleError } from "../../errors/error-handler.ts";
+import { handleReportCreate, handleReportList } from "../../handlers/report-handlers.ts";
+import { getGlobalOptions } from "../globals.ts";
+
+export function createReportCommand(): Command {
+	const report = new Command("report").description("Manage reports");
+
+	report
+		.command("list")
+		.description("List reports with optional filters")
+		.option("--standup-id <id>", "Filter by standup ID")
+		.option("--user-id <id>", "Filter by user ID")
+		.option("--before <date>", "Reports before date (ISO 8601 or unix timestamp)")
+		.option("--after <date>", "Reports after date (ISO 8601 or unix timestamp)")
+		.option("--limit <n>", "Max number of reports to return")
+		.addHelpText(
+			"after",
+			"\nExamples:\n  geekbot report list --standup-id 123\n  geekbot report list --standup-id 123 --limit 10\n  geekbot report list --after 2024-01-01",
+		)
+		.action(async function (this: Command) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handleReportList(
+					{
+						standupId: opts.standupId,
+						userId: opts.userId,
+						before: opts.before,
+						after: opts.after,
+						limit: opts.limit,
+					},
+					globalOpts,
+				);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	report
+		.command("create")
+		.description("Submit a report for a standup")
+		.requiredOption("--standup-id <id>", "Standup ID to report on")
+		.requiredOption("--answers <json>", 'Answers as JSON object: {"question_id": "answer", ...}')
+		.addHelpText(
+			"after",
+			'\nExamples:\n  geekbot report create --standup-id 123 --answers \'{"101": "Done feature X", "102": "Working on Y"}\'',
+		)
+		.action(async function (this: Command) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handleReportCreate(
+					{
+						standupId: opts.standupId,
+						answers: opts.answers,
+					},
+					globalOpts,
+				);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	return report;
+}

package/src/cli/commands/standup.ts

@@ -0,0 +1,234 @@
+import { Command } from "commander";
+import { handleError } from "../../errors/error-handler.ts";
+import {
+	handleStandupCreate,
+	handleStandupDelete,
+	handleStandupDuplicate,
+	handleStandupGet,
+	handleStandupList,
+	handleStandupReplace,
+	handleStandupStart,
+	handleStandupUpdate,
+} from "../../handlers/standup-handlers.ts";
+import { getGlobalOptions } from "../globals.ts";
+
+export function createStandupCommand(): Command {
+	const standup = new Command("standup").description("Manage standups");
+
+	standup
+		.command("list")
+		.description("List standups you participate in")
+		.option("--admin", "Include all team standups (admin only)")
+		.option("--brief", "Show only id, name, channel, time, timezone, and days")
+		.option("--name <name>", "Filter by name (case-insensitive substring match)")
+		.option("--channel <channel>", "Filter by channel (case-insensitive substring match)")
+		.option("--mine", "Show only standups you are a member of")
+		.option("--member <id>", "Filter by member user ID")
+		.option("--limit <n>", "Max number of standups to return")
+		.addHelpText(
+			"after",
+			'\nExamples:\n  geekbot standup list\n  geekbot standup list --admin\n  geekbot standup list --brief\n  geekbot standup list --brief --limit 10\n  geekbot standup list --name "daily"\n  geekbot standup list --channel "#status"\n  geekbot standup list --mine --brief\n  geekbot standup list --member "UHNM44125" --brief',
+		)
+		.action(async function (this: Command) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handleStandupList(
+					{
+						admin: opts.admin,
+						brief: opts.brief,
+						name: opts.name,
+						channel: opts.channel,
+						mine: opts.mine,
+						member: opts.member,
+						limit: opts.limit,
+					},
+					globalOpts,
+				);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	standup
+		.command("get")
+		.description("Get a standup by ID")
+		.argument("<id>", "Standup ID (numeric)")
+		.addHelpText("after", "\nExamples:\n  geekbot standup get 123")
+		.action(async function (this: Command, id: string) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				await handleStandupGet(id, globalOpts);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	standup
+		.command("create")
+		.description("Create a new standup")
+		.requiredOption("--name <name>", "Standup name")
+		.requiredOption("--channel <channel>", "Slack channel name")
+		.option("--time <time>", "Time in HH:MM 24-hour format (default: 10:00)")
+		.option("--timezone <tz>", "IANA timezone")
+		.option("--days <days>", "Comma-separated days (default: Mon-Fri)")
+		.requiredOption("--questions <json>", "Questions as JSON array")
+		.option("--users <ids>", "Comma-separated user IDs")
+		.option("--wait-time <minutes>", "Minutes between users")
+		.addHelpText(
+			"after",
+			'\nExamples:\n  geekbot standup create --name "Daily" --channel "#engineering"\n  geekbot standup create --name "Weekly" --channel "#team" --days "Mon" --time "09:00"',
+		)
+		.action(async function (this: Command) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handleStandupCreate(
+					{
+						name: opts.name,
+						channel: opts.channel,
+						time: opts.time,
+						timezone: opts.timezone,
+						days: opts.days,
+						questions: opts.questions,
+						users: opts.users,
+						waitTime: opts.waitTime,
+					},
+					globalOpts,
+				);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	standup
+		.command("update")
+		.description("Partially update a standup (PATCH)")
+		.argument("<id>", "Standup ID (numeric)")
+		.option("--name <name>", "New standup name")
+		.option("--channel <channel>", "New channel")
+		.option("--time <time>", "New time (HH:MM)")
+		.option("--timezone <tz>", "New timezone")
+		.option("--days <days>", "New days (comma-separated)")
+		.option("--questions <json>", "Questions as JSON array")
+		.option("--users <ids>", "Comma-separated user IDs")
+		.option("--wait-time <minutes>", "New wait time in minutes")
+		.addHelpText(
+			"after",
+			'\nExamples:\n  geekbot standup update 123 --name "Updated Daily"\n  geekbot standup update 123 --time "14:00" --days "Mon,Wed,Fri"\n  geekbot standup update 123 --questions \'["What did you do?","Any blockers?"]\'',
+		)
+		.action(async function (this: Command, id: string) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handleStandupUpdate(
+					id,
+					{
+						name: opts.name,
+						channel: opts.channel,
+						time: opts.time,
+						timezone: opts.timezone,
+						days: opts.days,
+						questions: opts.questions,
+						users: opts.users,
+						waitTime: opts.waitTime,
+					},
+					globalOpts,
+				);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	standup
+		.command("replace")
+		.description("Fully replace a standup (PUT)")
+		.argument("<id>", "Standup ID (numeric)")
+		.requiredOption("--name <name>", "Standup name")
+		.requiredOption("--channel <channel>", "Slack channel")
+		.option("--time <time>", "Time (HH:MM)", "10:00")
+		.option("--timezone <tz>", "Timezone", "UTC")
+		.option("--days <days>", "Days (comma-separated)", "Mon,Tue,Wed,Thu,Fri")
+		.option("--questions <json>", "Questions as JSON array")
+		.option("--users <ids>", "User IDs (comma-separated)")
+		.option("--wait-time <minutes>", "Wait time in minutes")
+		.addHelpText(
+			"after",
+			'\nExamples:\n  geekbot standup replace 123 --name "New Daily" --channel "#general"',
+		)
+		.action(async function (this: Command, id: string) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handleStandupReplace(
+					id,
+					{
+						name: opts.name,
+						channel: opts.channel,
+						time: opts.time,
+						timezone: opts.timezone,
+						days: opts.days,
+						questions: opts.questions,
+						users: opts.users,
+						waitTime: opts.waitTime,
+					},
+					globalOpts,
+				);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	standup
+		.command("delete")
+		.description("Delete a standup")
+		.argument("<id>", "Standup ID (numeric)")
+		.option("--yes", "Confirm deletion (required)")
+		.addHelpText("after", "\nExamples:\n  geekbot standup delete 123 --yes")
+		.action(async function (this: Command, id: string) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handleStandupDelete(id, { yes: opts.yes }, globalOpts);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	standup
+		.command("duplicate")
+		.description("Duplicate an existing standup")
+		.argument("<id>", "Standup ID to duplicate (numeric)")
+		.requiredOption("--name <name>", "Name for the new standup")
+		.addHelpText("after", '\nExamples:\n  geekbot standup duplicate 123 --name "Copy of Daily"')
+		.action(async function (this: Command, id: string) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handleStandupDuplicate(id, { name: opts.name }, globalOpts);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	standup
+		.command("start")
+		.description("Trigger a standup immediately")
+		.argument("<id>", "Standup ID (numeric)")
+		.option("--users <ids>", "Comma-separated user IDs (omit for all)")
+		.addHelpText(
+			"after",
+			'\nExamples:\n  geekbot standup start 123\n  geekbot standup start 123 --users "U123,U456"',
+		)
+		.action(async function (this: Command, id: string) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				const opts = this.opts();
+				await handleStandupStart(id, { users: opts.users }, globalOpts);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	return standup;
+}

package/src/cli/commands/team.ts

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import { handleError } from "../../errors/error-handler.ts";
+import { handleTeamList, handleTeamSearch } from "../../handlers/team-handlers.ts";
+import { getGlobalOptions } from "../globals.ts";
+
+export function createTeamCommand(): Command {
+	const team = new Command("team").description("View team information");
+
+	team
+		.command("list")
+		.description("List all teams with members")
+		.addHelpText("after", "\nExamples:\n  geekbot team list")
+		.action(async function (this: Command) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				await handleTeamList(globalOpts);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	team
+		.command("search")
+		.description("Search team members by name, username, or email")
+		.argument("<query>", "Search term (case-insensitive substring match)")
+		.addHelpText(
+			"after",
+			'\nExamples:\n  geekbot team search jenny\n  geekbot team search "smith"\n  geekbot team search @example.com',
+		)
+		.action(async function (this: Command, query: string) {
+			const globalOpts = getGlobalOptions(this);
+			try {
+				await handleTeamSearch(query, globalOpts);
+			} catch (error) {
+				handleError(error, globalOpts.debug);
+			}
+		});
+
+	return team;
+}

package/src/cli/globals.ts

@@ -0,0 +1,31 @@
+import { type Command, Option } from "commander";
+
+export interface GlobalOptions {
+	apiKey?: string;
+	output: "json";
+	debug: boolean;
+}
+
+/**
+ * Add global options to the root program.
+ * These are inherited by all subcommands via optsWithGlobals().
+ */
+export function addGlobalOptions(program: Command): void {
+	program
+		.option("--api-key <key>", "Geekbot API key (overrides GEEKBOT_API_KEY env var)")
+		.addOption(new Option("--output <format>", "Output format").choices(["json"]).default("json"))
+		.option("--debug", "Show debug output on stderr", false);
+}
+
+/**
+ * Extract global options from a command's optsWithGlobals().
+ * Call this from any action handler.
+ */
+export function getGlobalOptions(cmd: Command): GlobalOptions {
+	const opts = cmd.optsWithGlobals();
+	return {
+		apiKey: opts.apiKey,
+		output: "json",
+		debug: opts.debug === true,
+	};
+}

package/src/cli/index.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env bun
+import { Command, CommanderError } from "commander";
+import { CliError } from "../errors/cli-error.ts";
+import { handleError } from "../errors/error-handler.ts";
+import { ExitCode } from "../errors/exit-codes.ts";
+import { APP_NAME, APP_VERSION } from "../utils/constants.ts";
+import { createAuthCommand } from "./commands/auth.ts";
+import { createMeCommand } from "./commands/me.ts";
+import { createPollCommand } from "./commands/poll.ts";
+import { createReportCommand } from "./commands/report.ts";
+import { createStandupCommand } from "./commands/standup.ts";
+import { createTeamCommand } from "./commands/team.ts";
+import { addGlobalOptions } from "./globals.ts";
+
+// Recursively apply exitOverride to all subcommands so Commander throws
+// CommanderError instead of calling process.exit() on usage errors.
+function applyExitOverride(cmd: Command): void {
+	for (const sub of cmd.commands) {
+		sub.exitOverride();
+		applyExitOverride(sub);
+	}
+}
+
+/**
+ * Create and configure the CLI program with all commands, options,
+ * exitOverride, and configureOutput wiring. Returns the fully configured
+ * Commander program instance without calling parseAsync.
+ */
+export function createProgram(): Command {
+	const program = new Command()
+		.name(APP_NAME)
+		.version(APP_VERSION, "-v, --version")
+		.description("Geekbot CLI -- manage standups, reports, and polls for AI agents and humans")
+		.exitOverride();
+
+	// Route Commander.js error output to stderr (Pitfall 4)
+	program.configureOutput({
+		writeOut: (str) => process.stderr.write(str),
+		writeErr: (str) => process.stderr.write(str),
+		outputError: (str, write) => write(str),
+	});
+
+	// Add global flags
+	addGlobalOptions(program);
+
+	// Register resource subcommands (noun-verb pattern: CLI-01)
+	program.addCommand(createStandupCommand());
+	program.addCommand(createReportCommand());
+	program.addCommand(createPollCommand());
+	program.addCommand(createAuthCommand());
+	program.addCommand(createMeCommand());
+	program.addCommand(createTeamCommand());
+
+	applyExitOverride(program);
+
+	return program;
+}
+
+/**
+ * Parse argv and handle errors from Commander and action handlers.
+ * Exported for testing; the entrypoint calls this automatically.
+ */
+export async function main(program: Command, argv: string[] = process.argv): Promise<void> {
+	try {
+		await program.parseAsync(argv);
+	} catch (error) {
+		const opts = program.opts();
+		if (error instanceof CommanderError) {
+			// Map Commander usage errors (missing args, unknown options, etc.)
+			// to CliError with ExitCode.USAGE so they go through the JSON envelope.
+			// Preserve Commander's exitCode 0 for --help/--version (not an error).
+			if (error.exitCode === 0) {
+				process.exit(0);
+			}
+			const usageError = new CliError(
+				error.message,
+				"usage_error",
+				ExitCode.USAGE,
+				false,
+				"Run with --help for usage information",
+			);
+			handleError(usageError, opts.debug === true);
+		} else {
+			handleError(error, opts.debug === true);
+		}
+	}
+}
+
+// Run when executed as the CLI entrypoint (not when imported for testing).
+// import.meta.main is true in Bun when this file is the entrypoint.
+if (import.meta.main) {
+	const program = createProgram();
+	main(program);
+}

package/src/errors/cli-error.ts

@@ -0,0 +1,16 @@
+import type { ExitCodeValue } from "./exit-codes.ts";
+
+export class CliError extends Error {
+	public override readonly name = "CliError";
+
+	constructor(
+		message: string,
+		public readonly code: string,
+		public readonly exitCode: ExitCodeValue,
+		public readonly retryable: boolean = false,
+		public readonly suggestion?: string,
+		public readonly context?: Record<string, unknown>,
+	) {
+		super(message);
+	}
+}

package/src/errors/error-handler.ts

@@ -0,0 +1,63 @@
+import { ZodError } from "zod";
+import { failure } from "../output/envelope.ts";
+import { writeOutput } from "../output/formatter.ts";
+import { CliError } from "./cli-error.ts";
+import { ExitCode } from "./exit-codes.ts";
+
+function formatZodMessage(error: ZodError): string {
+	return error.issues
+		.map((issue) => {
+			const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+			return `${path}: ${issue.message}`;
+		})
+		.join("; ");
+}
+
+export function handleError(error: unknown, debug: boolean = false): never {
+	if (error instanceof ZodError) {
+		writeOutput(
+			failure({
+				code: "schema_validation_error",
+				message: `Unexpected API response: ${formatZodMessage(error)}`,
+				retryable: false,
+				suggestion:
+					"The API returned data in an unexpected format. The API may have changed or there may be a version mismatch.",
+			}),
+		);
+
+		if (debug) {
+			process.stderr.write(`[debug] ZodError issues: ${JSON.stringify(error.issues)}\n`);
+		}
+
+		process.exit(ExitCode.API_ERROR);
+	}
+
+	if (error instanceof CliError) {
+		writeOutput(
+			failure({
+				code: error.code,
+				message: error.message,
+				retryable: error.retryable,
+				suggestion: error.suggestion ?? null,
+			}),
+		);
+
+		if (debug && error.context) {
+			process.stderr.write(`[debug] Error context: ${JSON.stringify(error.context)}\n`);
+		}
+
+		process.exit(error.exitCode);
+	}
+
+	// Unknown/unexpected error
+	writeOutput(
+		failure({
+			code: "internal_error",
+			message: error instanceof Error ? error.message : String(error),
+			retryable: false,
+			suggestion: "This is an unexpected error. Please report it.",
+		}),
+	);
+
+	process.exit(ExitCode.GENERAL);
+}

package/src/errors/exit-codes.ts

@@ -0,0 +1,14 @@
+export const ExitCode = {
+	SUCCESS: 0,
+	GENERAL: 1,
+	USAGE: 2,
+	NOT_FOUND: 3,
+	AUTH: 4,
+	FORBIDDEN: 5,
+	VALIDATION: 6,
+	NETWORK: 7,
+	CONFLICT: 8,
+	API_ERROR: 9,
+} as const;
+
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];