geekbot-cli 0.1.0

package/src/errors/not-found-helper.ts

@@ -0,0 +1,86 @@
+import type { HttpClient } from "../http/client.ts";
+
+/**
+ * Resource types that support not-found suggestions.
+ * Each maps to a list endpoint and a display formatter.
+ */
+export type ResourceType = "standup" | "poll";
+
+interface ResourceListItem {
+	id: number;
+	name: string;
+}
+
+/**
+ * Extract items with id+name from an unknown API response array.
+ * Shared across all resource types since the shape is identical.
+ */
+function extractItems(data: unknown): ResourceListItem[] {
+	if (!Array.isArray(data)) return [];
+	return data
+		.filter(
+			(item): item is { id: number; name: string } =>
+				typeof item === "object" &&
+				item !== null &&
+				typeof item.id === "number" &&
+				typeof item.name === "string",
+		)
+		.map(({ id, name }) => ({ id, name }));
+}
+
+/**
+ * Resource type configurations for fetching alternatives.
+ * Maps each resource to its list endpoint and how to extract id+name.
+ */
+const RESOURCE_CONFIG: Record<
+	ResourceType,
+	{
+		listPath: string;
+		extractItems: (data: unknown) => ResourceListItem[];
+	}
+> = {
+	standup: { listPath: "/v1/standups", extractItems },
+	poll: { listPath: "/v1/polls", extractItems },
+};
+
+/**
+ * Build a suggestion string for a 404 error by fetching and listing
+ * available alternatives for the given resource type.
+ *
+ * Returns a suggestion string like:
+ *   "Available standups: 123 (Daily Standup), 456 (Weekly Review). Run `geekbot standup list` to see all."
+ *
+ * Returns null if the list fetch fails or returns no items.
+ * Silently catches errors so a failed suggestion never blocks the main error flow.
+ *
+ * @param client - An authenticated HttpClient
+ * @param resourceType - The type of resource that was not found
+ * @param maxItems - Maximum number of alternatives to show (default: 5)
+ */
+export async function buildNotFoundSuggestion(
+	client: HttpClient,
+	resourceType: ResourceType,
+	maxItems = 5,
+): Promise<string | null> {
+	const config = RESOURCE_CONFIG[resourceType];
+	if (!config) return null;
+
+	try {
+		const rawData = await client.get<unknown>(config.listPath);
+		const items = config.extractItems(rawData);
+
+		if (items.length === 0) {
+			return `No ${resourceType}s found. Run \`geekbot ${resourceType} create\` to create one.`;
+		}
+
+		const shown = items.slice(0, maxItems);
+		const formatted = shown.map((item) => `${item.id} (${item.name})`).join(", ");
+		const suffix = items.length > maxItems ? ` and ${items.length - maxItems} more` : "";
+
+		return `Available ${resourceType}s: ${formatted}${suffix}. Run \`geekbot ${resourceType} list\` to see all.`;
+	} catch {
+		// Suggestion is best-effort. If the list fetch fails (e.g., auth issues),
+		// return null and let the original 404 error propagate without a suggestion.
+		return null;
+	}
+}

package/src/handlers/auth-handlers.ts

@@ -0,0 +1,152 @@
+import { deleteKeychainKey, getKeychainKey, setKeychainKey } from "../auth/keychain.ts";
+import { resolveCredential } from "../auth/resolver.ts";
+import type { GlobalOptions } from "../cli/globals.ts";
+import { CliError } from "../errors/cli-error.ts";
+import { ExitCode } from "../errors/exit-codes.ts";
+import { createHttpClient } from "../http/client.ts";
+import { success } from "../output/envelope.ts";
+import { writeOutput } from "../output/formatter.ts";
+import { MeResponseSchema } from "../schemas/user.ts";
+
+// ── Option Interfaces ─────────────────────────────────────────────────
+
+export interface AuthSetupOptions {
+	apiKey?: string;
+}
+
+// ── Handlers ──────────────────────────────────────────────────────────
+
+/**
+ * Handle `geekbot auth setup` command.
+ * Acquires API key (flag, interactive prompt, or error),
+ * verifies it via GET /v1/me, then stores in OS keychain.
+ */
+export async function handleAuthSetup(
+	options: AuthSetupOptions,
+	globalOpts: GlobalOptions,
+): Promise<void> {
+	let key: string;
+
+	if (options.apiKey) {
+		key = options.apiKey.trim();
+	} else if (process.stdin.isTTY) {
+		const readline = await import("node:readline");
+		const { Writable } = await import("node:stream");
+		// Use a muted output stream so the API key is not echoed to the terminal
+		const mutedOutput = new Writable({
+			write(_chunk, _encoding, callback) {
+				callback();
+			},
+		});
+		const reader = readline.createInterface({
+			input: process.stdin,
+			output: mutedOutput,
+			terminal: true,
+		});
+		// Print the prompt ourselves since the muted stream swallows it
+		process.stderr.write("Enter your Geekbot API key: ");
+		key = await new Promise<string>((resolve) => {
+			reader.question("", (answer: string) => {
+				resolve(answer.trim());
+				reader.close();
+			});
+		});
+		// Print a newline after the user presses Enter (since echo is suppressed)
+		process.stderr.write("\n");
+	} else {
+		throw new CliError(
+			"Non-interactive mode requires --api-key flag.",
+			"auth_setup_non_interactive",
+			ExitCode.USAGE,
+			false,
+			"Run: geekbot auth setup --api-key YOUR_KEY",
+		);
+	}
+
+	// Verify key by calling /v1/me
+	const client = createHttpClient(key, { debug: globalOpts.debug });
+	const raw = await client.get<unknown>("/v1/me");
+	const meResponse = MeResponseSchema.parse(raw);
+
+	// Check for existing keychain key and warn
+	const existing = getKeychainKey();
+	if (existing) {
+		process.stderr.write("Replacing existing API key in keychain\n");
+	}
+
+	// Store in keychain
+	try {
+		setKeychainKey(key);
+	} catch {
+		throw new CliError(
+			"Failed to store API key in OS keychain.",
+			"keychain_unavailable",
+			ExitCode.GENERAL,
+			false,
+			'OS keychain may be unavailable. Use GEEKBOT_API_KEY environment variable instead: export GEEKBOT_API_KEY="your-key"',
+		);
+	}
+
+	writeOutput(
+		success({
+			authenticated: true,
+			username: meResponse.user.username,
+			email: meResponse.user.email,
+		}),
+	);
+}
+
+/**
+ * Handle `geekbot auth status` command.
+ * Resolves current credential, verifies it, and shows source + profile.
+ */
+export async function handleAuthStatus(globalOpts: GlobalOptions): Promise<void> {
+	try {
+		const { apiKey, source } = await resolveCredential({
+			apiKeyFlag: globalOpts.apiKey,
+		});
+		const client = createHttpClient(apiKey, { debug: globalOpts.debug });
+		const raw = await client.get<unknown>("/v1/me");
+		const meResponse = MeResponseSchema.parse(raw);
+		writeOutput(
+			success({
+				authenticated: true,
+				source,
+				username: meResponse.user.username,
+				email: meResponse.user.email,
+			}),
+		);
+	} catch (error) {
+		if (error instanceof CliError && error.code === "auth_missing") {
+			writeOutput(
+				success({
+					authenticated: false,
+					source: null,
+					username: null,
+					email: null,
+				}),
+			);
+			return;
+		}
+		throw error;
+	}
+}
+
+/**
+ * Handle `geekbot auth remove` command.
+ * Deletes API key from OS keychain.
+ */
+export async function handleAuthRemove(_globalOpts: GlobalOptions): Promise<void> {
+	try {
+		deleteKeychainKey();
+		writeOutput(success({ removed: true }));
+	} catch {
+		throw new CliError(
+			"No API key found in OS keychain to remove.",
+			"keychain_not_found",
+			ExitCode.NOT_FOUND,
+			false,
+			"Key may not be stored in the OS keychain. Check: geekbot auth status",
+		);
+	}
+}

package/src/handlers/me-handlers.ts

@@ -0,0 +1,27 @@
+import type { GlobalOptions } from "../cli/globals.ts";
+import { createAuthenticatedClient } from "../http/authenticated-client.ts";
+import { success, successList } from "../output/envelope.ts";
+import { writeOutput } from "../output/formatter.ts";
+import { MeResponseSchema, MeTeamsResponseSchema } from "../schemas/user.ts";
+
+/**
+ * Handle `geekbot me show` command.
+ * GET /v1/me returns {user, team}. We extract user portion only.
+ */
+export async function handleMeShow(globalOpts: GlobalOptions): Promise<void> {
+	const client = await createAuthenticatedClient(globalOpts);
+	const raw = await client.get<unknown>("/v1/me");
+	const meResponse = MeResponseSchema.parse(raw);
+	writeOutput(success(meResponse.user));
+}
+
+/**
+ * Handle `geekbot me teams` command.
+ * GET /v1/me/teams returns {teams: [...]}.
+ */
+export async function handleMeTeams(globalOpts: GlobalOptions): Promise<void> {
+	const client = await createAuthenticatedClient(globalOpts);
+	const raw = await client.get<unknown>("/v1/me/teams");
+	const teamsResponse = MeTeamsResponseSchema.parse(raw);
+	writeOutput(successList(teamsResponse.teams));
+}

package/src/handlers/poll-handlers.ts

@@ -0,0 +1,187 @@
+import type { GlobalOptions } from "../cli/globals.ts";
+import { CliError } from "../errors/cli-error.ts";
+import { ExitCode } from "../errors/exit-codes.ts";
+import { buildNotFoundSuggestion } from "../errors/not-found-helper.ts";
+import { createAuthenticatedClient } from "../http/authenticated-client.ts";
+import type { HttpClient } from "../http/client.ts";
+import { success, successList } from "../output/envelope.ts";
+import { writeOutput } from "../output/formatter.ts";
+import { PollListSchema, PollSchema, PollVotesResponseSchema } from "../schemas/poll.ts";
+import { parseChoicesInput, parseDateFilter } from "../utils/input-parsers.ts";
+import { buildReceipt } from "../utils/receipt.ts";
+import { validateNumericId } from "../utils/validation.ts";
+
+// ── Option Interfaces ─────────────────────────────────────────────────
+
+export interface PollCreateOptions {
+	name: string;
+	channel: string;
+	question: string;
+	choices: string;
+}
+
+export interface PollVotesOptions {
+	after?: string;
+	before?: string;
+}
+
+// ── Platform Error Helper ─────────────────────────────────────────────
+
+/**
+ * Wrap an async handler call to detect non-Slack team 404 errors on poll endpoints.
+ * The Geekbot API returns 404 for teams that don't support polls (non-Slack).
+ *
+ * Layering: handlers that target specific poll IDs nest enrichPollNotFound INSIDE
+ * this wrapper. enrichPollNotFound converts specific poll 404s to code "poll_not_found",
+ * which passes through the "not_found" check below unchanged. If enrichment returns null,
+ * the original "not_found" error propagates here and is caught as "platform_not_supported".
+ */
+async function wrapPlatformError(fn: () => Promise<void>): Promise<void> {
+	try {
+		await fn();
+	} catch (error) {
+		// Only intercept errors with code "not_found" — enriched "poll_not_found"
+		// errors from enrichPollNotFound pass through without being re-mapped.
+		if (
+			error instanceof CliError &&
+			error.code === "not_found" &&
+			error.context?.path &&
+			String(error.context.path).startsWith("/v1/polls")
+		) {
+			throw new CliError(
+				"Polls are only available for Slack teams. Your team appears to use a different platform.",
+				"platform_not_supported",
+				ExitCode.VALIDATION,
+				false,
+				"Polls require a Slack workspace. Check your team settings at geekbot.com.",
+			);
+		}
+		throw error;
+	}
+}
+
+// ── Not-Found Enrichment ──────────────────────────────────────────────
+
+/**
+ * Wrap a poll handler's async work to enrich 404 errors with suggestions.
+ * Creates the HttpClient once and passes it to the handler callback.
+ * Placed inside wrapPlatformError so platform error detection takes priority.
+ */
+async function enrichPollNotFound(
+	fn: (client: HttpClient) => Promise<void>,
+	globalOpts: GlobalOptions,
+): Promise<void> {
+	const client = await createAuthenticatedClient(globalOpts);
+	try {
+		await fn(client);
+	} catch (error) {
+		if (error instanceof CliError && error.code === "not_found") {
+			const suggestion = await buildNotFoundSuggestion(client, "poll");
+			if (suggestion) {
+				throw new CliError(
+					error.message,
+					"poll_not_found",
+					error.exitCode,
+					error.retryable,
+					suggestion,
+					error.context,
+				);
+			}
+		}
+		throw error;
+	}
+}
+
+// ── Handlers ──────────────────────────────────────────────────────────
+
+/**
+ * Handle `geekbot poll list` command.
+ * Fetches polls from GET /v1/polls.
+ */
+export async function handlePollList(globalOpts: GlobalOptions): Promise<void> {
+	await wrapPlatformError(async () => {
+		const client = await createAuthenticatedClient(globalOpts);
+
+		const raw = await client.get<unknown>("/v1/polls");
+		const polls = PollListSchema.parse(raw);
+
+		writeOutput(successList(polls));
+	});
+}
+
+/**
+ * Handle `geekbot poll get` command.
+ * Fetches a single poll by ID from GET /v1/polls/<id>.
+ */
+export async function handlePollGet(id: string, globalOpts: GlobalOptions): Promise<void> {
+	const numericId = validateNumericId(id, "poll ID");
+
+	await wrapPlatformError(async () => {
+		await enrichPollNotFound(async (client) => {
+			const raw = await client.get<unknown>(`/v1/polls/${numericId}`);
+			const poll = PollSchema.parse(raw);
+			writeOutput(success(poll));
+		}, globalOpts);
+	});
+}
+
+/**
+ * Handle `geekbot poll create` command.
+ * Creates a poll via POST /v1/polls.
+ */
+export async function handlePollCreate(
+	options: PollCreateOptions,
+	globalOpts: GlobalOptions,
+): Promise<void> {
+	await wrapPlatformError(async () => {
+		const client = await createAuthenticatedClient(globalOpts);
+
+		const choices = parseChoicesInput(options.choices);
+
+		const body = {
+			name: options.name,
+			channel: options.channel,
+			question: options.question,
+			choices,
+		};
+
+		const raw = await client.post<unknown>("/v1/polls", body);
+		const poll = PollSchema.parse(raw);
+		const receipt = buildReceipt("created", null);
+
+		writeOutput(success(poll, receipt));
+	});
+}
+
+/**
+ * Handle `geekbot poll votes` command.
+ * Fetches voting results from GET /v1/polls/<id>/votes.
+ * Maps CLI --after/--before to API from/to params.
+ */
+export async function handlePollVotes(
+	id: string,
+	options: PollVotesOptions,
+	globalOpts: GlobalOptions,
+): Promise<void> {
+	const numericId = validateNumericId(id, "poll ID");
+
+	await wrapPlatformError(async () => {
+		await enrichPollNotFound(async (client) => {
+			const params: Record<string, string> = {};
+			if (options.after) {
+				params.from = parseDateFilter(options.after, "--after");
+			}
+			if (options.before) {
+				params.to = parseDateFilter(options.before, "--before");
+			}
+
+			const raw = await client.get<unknown>(
+				`/v1/polls/${numericId}/votes`,
+				Object.keys(params).length > 0 ? params : undefined,
+			);
+			const votesResponse = PollVotesResponseSchema.parse(raw);
+
+			writeOutput(success(votesResponse));
+		}, globalOpts);
+	});
+}

package/src/handlers/report-handlers.ts

@@ -0,0 +1,87 @@
+import type { GlobalOptions } from "../cli/globals.ts";
+import { createAuthenticatedClient } from "../http/authenticated-client.ts";
+import { success, successList } from "../output/envelope.ts";
+import { writeOutput } from "../output/formatter.ts";
+import { SubmittedReportSchema, TimelineReportListSchema } from "../schemas/report.ts";
+import { parseAnswersInput, parseDateFilter } from "../utils/input-parsers.ts";
+import { buildReceipt } from "../utils/receipt.ts";
+import { validateLimit, validateNumericId, validateSlackId } from "../utils/validation.ts";
+
+export interface ReportListOptions {
+	standupId?: string;
+	userId?: string;
+	before?: string;
+	after?: string;
+	limit?: string;
+}
+
+export interface ReportCreateOptions {
+	standupId: string;
+	answers: string;
+}
+
+/**
+ * Handle `geekbot report list` command.
+ * Fetches reports from GET /v1/reports with optional query filters.
+ */
+export async function handleReportList(
+	options: ReportListOptions,
+	globalOpts: GlobalOptions,
+): Promise<void> {
+	const client = await createAuthenticatedClient(globalOpts);
+
+	const params: Record<string, string> = {};
+
+	if (options.standupId) {
+		validateNumericId(options.standupId, "standup ID");
+		params.standup_id = options.standupId;
+	}
+
+	if (options.userId) {
+		validateSlackId(options.userId, "user ID");
+		params.user_id = options.userId;
+	}
+
+	if (options.before) {
+		params.before = parseDateFilter(options.before, "--before");
+	}
+
+	if (options.after) {
+		params.after = parseDateFilter(options.after, "--after");
+	}
+
+	if (options.limit) {
+		const limitNum = validateLimit(options.limit);
+		params.limit = String(limitNum);
+	}
+
+	const raw = await client.get<unknown>("/v1/reports", params);
+	const reports = TimelineReportListSchema.parse(raw);
+
+	writeOutput(successList(reports));
+}
+
+/**
+ * Handle `geekbot report create` command.
+ * Submits a report via POST /v1/reports with standup_id and normalized answers.
+ */
+export async function handleReportCreate(
+	options: ReportCreateOptions,
+	globalOpts: GlobalOptions,
+): Promise<void> {
+	const client = await createAuthenticatedClient(globalOpts);
+
+	const numericStandupId = validateNumericId(options.standupId, "standup ID");
+	const parsedAnswers = parseAnswersInput(options.answers);
+
+	const body = {
+		standup_id: numericStandupId,
+		answers: parsedAnswers,
+	};
+
+	const raw = await client.post<unknown>("/v1/reports", body);
+	const report = SubmittedReportSchema.parse(raw);
+	const receipt = buildReceipt("created", null);
+
+	writeOutput(success(report, receipt));
+}