geekbot-cli 0.1.0

package/src/schemas/user.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+
+/** Full user object (standups, polls, teams) -- API returns snake_case here */
+export const FullUserSchema = z.object({
+	id: z.string(),
+	role: z.enum(["admin", "billing_admin", "member"]),
+	email: z.string(),
+	username: z.string(),
+	realname: z.string().nullable(),
+	profile_img: z.string(),
+});
+
+export type FullUser = z.output<typeof FullUserSchema>;
+
+/** Compact user object (report members) -- API returns camelCase profileImg */
+const CompactUserRawSchema = z.object({
+	id: z.string(),
+	username: z.string(),
+	realname: z.string().nullable(),
+	profileImg: z.string(),
+});
+
+export const CompactUserSchema = CompactUserRawSchema.transform((raw) => ({
+	id: raw.id,
+	username: raw.username,
+	realname: raw.realname,
+	profile_img: raw.profileImg, // NORM-01: camelCase -> snake_case
+}));
+
+export type CompactUser = z.output<typeof CompactUserSchema>;
+
+/** Extended user from GET /v1/me response - has extra fields beyond FullUser */
+export const MeUserSchema = z.object({
+	id: z.string(),
+	username: z.string(),
+	realname: z.string().nullable(),
+	firstname: z.string(),
+	email: z.string(),
+	profile_img: z.string(),
+	timezone: z.string(),
+	is_admin: z.boolean(),
+	is_billing_admin: z.boolean(),
+	role: z.enum(["admin", "billing_admin", "member"]),
+});
+export type MeUser = z.output<typeof MeUserSchema>;
+
+/** GET /v1/me returns nested {user, team} */
+export const MeResponseSchema = z.object({
+	user: MeUserSchema,
+	team: z.object({
+		id: z.number(),
+		name: z.string(),
+	}),
+});
+export type MeResponse = z.output<typeof MeResponseSchema>;
+
+/** Single team in GET /v1/me/teams response */
+export const MeTeamSchema = z.object({
+	id: z.number(),
+	name: z.string(),
+	is_admin: z.boolean(),
+	standup_count: z.number(),
+});
+export type MeTeam = z.output<typeof MeTeamSchema>;
+
+/** GET /v1/me/teams returns {teams: [...]} */
+export const MeTeamsResponseSchema = z.object({
+	teams: z.array(MeTeamSchema),
+});
+export type MeTeamsResponse = z.output<typeof MeTeamsResponseSchema>;

package/src/types.ts

@@ -0,0 +1,30 @@
+export interface ErrorObject {
+	code: string; // machine-readable: "standup_not_found"
+	message: string; // human-readable
+	retryable: boolean;
+	suggestion: string | null;
+}
+
+export interface MetadataObject {
+	timestamp: string; // ISO 8601
+	[key: string]: unknown;
+}
+
+export interface OutputEnvelope<T> {
+	ok: boolean;
+	data: T | null;
+	error: ErrorObject | null;
+	metadata: MetadataObject;
+}
+
+export interface SuccessEnvelope<T> extends OutputEnvelope<T> {
+	ok: true;
+	data: T;
+	error: null;
+}
+
+export interface FailureEnvelope extends OutputEnvelope<null> {
+	ok: false;
+	data: null;
+	error: ErrorObject;
+}

package/src/utils/constants.ts

@@ -0,0 +1,24 @@
+import packageJson from "../../package.json";
+import { CliError } from "../errors/cli-error.ts";
+import { ExitCode } from "../errors/exit-codes.ts";
+
+export const APP_NAME = "geekbot";
+export const APP_VERSION: string = packageJson.version;
+
+export function resolveApiBaseUrl(envValue?: string): string {
+	if (envValue === undefined) {
+		return "https://api.geekbot.com";
+	}
+	if (!envValue.startsWith("https://")) {
+		throw new CliError(
+			"GEEKBOT_API_BASE_URL must use HTTPS to prevent API key exfiltration.",
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			"Set GEEKBOT_API_BASE_URL to an https:// URL.",
+		);
+	}
+	return envValue;
+}
+
+export const API_BASE_URL = resolveApiBaseUrl(process.env.GEEKBOT_API_BASE_URL);

package/src/utils/input-parsers.ts

@@ -0,0 +1,234 @@
+import { CliError } from "../errors/cli-error.ts";
+import { ExitCode } from "../errors/exit-codes.ts";
+
+/**
+ * Parse JSON input for --questions flag.
+ * Accepts an array of strings (simple) or objects with question config (full).
+ * String items are converted to {question: text} objects.
+ */
+export function parseQuestionsInput(raw: string): Array<Record<string, unknown>> {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new CliError(
+			"Invalid JSON for --questions input.",
+			"json_parse_error",
+			ExitCode.VALIDATION,
+			false,
+			'Expected a JSON array. Example: --questions \'["What did you do?", "Any blockers?"]\'',
+		);
+	}
+
+	if (!Array.isArray(parsed)) {
+		throw new CliError(
+			"--questions input must be a JSON array.",
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			'Expected a JSON array. Example: --questions \'["What did you do?", "Any blockers?"]\'',
+		);
+	}
+
+	return parsed.map((item: unknown, index: number) => {
+		if (typeof item === "string") {
+			return { question: item };
+		}
+		if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+			const obj = item as Record<string, unknown>;
+			if ("question" in obj) {
+				if (typeof obj.question !== "string") {
+					throw new CliError(
+						`Invalid question at index ${index}. The "question" property must be a string, got ${typeof obj.question}.`,
+						"validation_error",
+						ExitCode.VALIDATION,
+						false,
+						'Expected a JSON array. Example: --questions \'["What did you do?", "Any blockers?"]\'',
+					);
+				}
+				return obj;
+			}
+			if ("text" in obj) {
+				if (typeof obj.text !== "string") {
+					throw new CliError(
+						`Invalid question at index ${index}. The "text" property must be a string, got ${typeof obj.text}.`,
+						"validation_error",
+						ExitCode.VALIDATION,
+						false,
+						'Expected a JSON array. Example: --questions \'["What did you do?", "Any blockers?"]\'',
+					);
+				}
+				const { text, ...rest } = obj;
+				return { question: text, ...rest };
+			}
+		}
+		throw new CliError(
+			`Invalid question at index ${index}. Each item must be a string or an object with a "question" or "text" property.`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			'Expected a JSON array. Example: --questions \'["What did you do?", "Any blockers?"]\'',
+		);
+	});
+}
+
+/**
+ * Parse JSON input for --answers flag.
+ * Accepts an object keyed by question ID with string values (shorthand)
+ * or {text: string} objects (full).
+ */
+export function parseAnswersInput(raw: string): Record<string, { text: string }> {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new CliError(
+			"Invalid JSON for --answers input.",
+			"json_parse_error",
+			ExitCode.VALIDATION,
+			false,
+			'Example: --answers \'{"101": "Done X", "102": "Working on Y"}\'',
+		);
+	}
+
+	if (Array.isArray(parsed) || typeof parsed !== "object" || parsed === null) {
+		throw new CliError(
+			"--answers input must be a JSON object (not an array).",
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			'Example: --answers \'{"101": "Done X", "102": "Working on Y"}\'',
+		);
+	}
+
+	const result: Record<string, { text: string }> = {};
+	for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+		if (typeof value === "string") {
+			result[key] = { text: value };
+		} else if (
+			typeof value === "object" &&
+			value !== null &&
+			!Array.isArray(value) &&
+			"text" in value &&
+			typeof (value as Record<string, unknown>).text === "string"
+		) {
+			result[key] = value as { text: string };
+		} else {
+			throw new CliError(
+				`Invalid answer for question "${key}". Each value must be a string or an object with a "text" property.`,
+				"validation_error",
+				ExitCode.VALIDATION,
+				false,
+				'Example: --answers \'{"101": "Done X", "102": "Working on Y"}\'',
+			);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Parse JSON input for --choices flag.
+ * Accepts a JSON array of 2-20 strings.
+ */
+export function parseChoicesInput(raw: string): string[] {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new CliError(
+			"Invalid JSON for --choices input.",
+			"json_parse_error",
+			ExitCode.VALIDATION,
+			false,
+			'Expected a JSON array of strings. Example: --choices \'["Pizza", "Sushi", "Tacos"]\'',
+		);
+	}
+
+	if (!Array.isArray(parsed)) {
+		throw new CliError(
+			"--choices input must be a JSON array.",
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			'Expected a JSON array of strings. Example: --choices \'["Pizza", "Sushi", "Tacos"]\'',
+		);
+	}
+
+	if (parsed.length < 2 || parsed.length > 20) {
+		throw new CliError(
+			`--choices must have 2-20 items, got ${parsed.length}.`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			"Provide between 2 and 20 choices.",
+		);
+	}
+
+	for (const [i, item] of parsed.entries()) {
+		if (typeof item !== "string") {
+			throw new CliError(
+				`Invalid choice at index ${i}: must be a string.`,
+				"validation_error",
+				ExitCode.VALIDATION,
+				false,
+				'Each choice must be a string. Example: --choices \'["Option A", "Option B"]\'',
+			);
+		}
+	}
+
+	return parsed as string[];
+}
+
+/**
+ * Parse date filter input for --before/--after flags.
+ * Accepts ISO 8601 dates (2024-01-15) or unix timestamps (1705276800).
+ */
+export function parseDateFilter(raw: string, label: string): string {
+	// If all digits, treat as unix timestamp passthrough
+	if (/^\d+$/.test(raw)) {
+		return raw;
+	}
+
+	// Enforce strict ISO 8601 date format (YYYY-MM-DD) to reject ambiguous formats
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+		throw new CliError(
+			`Invalid date for ${label}: "${raw}".`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			"Accepted formats: ISO 8601 (2024-01-15) or unix timestamp (1705276800)",
+		);
+	}
+
+	const date = new Date(raw);
+	if (Number.isNaN(date.getTime())) {
+		throw new CliError(
+			`Invalid date for ${label}: "${raw}".`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			"Accepted formats: ISO 8601 (2024-01-15) or unix timestamp (1705276800)",
+		);
+	}
+
+	// Validate that the Date object matches the input components.
+	// new Date() auto-corrects impossible dates (e.g., Feb 31 -> Mar 3),
+	// so we must check the parsed components against the original input.
+	const [inputYear, inputMonth, inputDay] = raw.split("-").map(Number);
+	if (
+		date.getUTCFullYear() !== inputYear ||
+		date.getUTCMonth() + 1 !== inputMonth ||
+		date.getUTCDate() !== inputDay
+	) {
+		throw new CliError(
+			`Invalid date for ${label}: "${raw}" is not a valid calendar date.`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			"Accepted formats: ISO 8601 (2024-01-15) or unix timestamp (1705276800)",
+		);
+	}
+
+	return String(Math.floor(date.getTime() / 1000));
+}

package/src/utils/receipt.ts

@@ -0,0 +1,94 @@
+import type { Standup } from "../schemas/standup.ts";
+
+/**
+ * Escape a string for safe inclusion in a shell command.
+ * Wraps in single quotes and escapes any embedded single quotes.
+ */
+export function shellEscape(value: string): string {
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+export type MutationOperation = "created" | "updated" | "deleted" | "duplicated" | "started";
+
+/**
+ * Build a mutation receipt with operation type and undo command.
+ */
+export function buildReceipt(
+	operation: MutationOperation,
+	undo: string | null,
+): { operation: MutationOperation; undo: string | null } {
+	return { operation, undo };
+}
+
+/**
+ * Build an undo command that reconstructs a create command from a deleted standup.
+ * Used by delete operations to provide a reversal hint in the receipt.
+ */
+export function buildDeleteUndoCommand(standup: Standup): string {
+	const parts: string[] = [
+		`geekbot standup create --name ${shellEscape(standup.name)} --channel ${shellEscape(standup.channel)}`,
+	];
+
+	if (standup.time) {
+		parts.push(`--time ${shellEscape(standup.time.slice(0, 5))}`);
+	}
+
+	if (standup.timezone) {
+		parts.push(`--timezone ${shellEscape(standup.timezone)}`);
+	}
+
+	if (standup.days.length > 0) {
+		parts.push(`--days ${shellEscape(standup.days.join(","))}`);
+	}
+
+	if (standup.wait_time > 0) {
+		parts.push(`--wait-time ${standup.wait_time}`);
+	}
+
+	if (standup.questions.length > 0) {
+		parts.push(`--questions ${shellEscape(JSON.stringify(standup.questions.map((q) => q.text)))}`);
+	}
+
+	return parts.join(" ");
+}
+
+/** Map of standup field names to CLI flag names */
+const FIELD_TO_FLAG: Record<string, string> = {
+	name: "--name",
+	channel: "--channel",
+	time: "--time",
+	timezone: "--timezone",
+	days: "--days",
+	wait_time: "--wait-time",
+};
+
+/**
+ * Build an undo command that reverts only the changed fields of an update.
+ * Uses the previous state to reconstruct the original values.
+ */
+export function buildUpdateUndoCommand(
+	id: number,
+	previousState: Standup,
+	changedFields: Record<string, unknown>,
+): string {
+	const parts: string[] = [`geekbot standup update ${id}`];
+
+	for (const key of Object.keys(changedFields)) {
+		const flag = FIELD_TO_FLAG[key];
+		if (!flag) continue;
+
+		const prevValue = previousState[key as keyof Standup];
+
+		if (key === "time" && typeof prevValue === "string") {
+			parts.push(`${flag} ${shellEscape(prevValue.slice(0, 5))}`);
+		} else if (key === "days" && Array.isArray(prevValue)) {
+			parts.push(`${flag} ${shellEscape(prevValue.join(","))}`);
+		} else if (typeof prevValue === "number") {
+			parts.push(`${flag} ${prevValue}`);
+		} else if (typeof prevValue === "string") {
+			parts.push(`${flag} ${shellEscape(prevValue)}`);
+		}
+	}
+
+	return parts.join(" ");
+}

package/src/utils/validation.ts

@@ -0,0 +1,128 @@
+import { CliError } from "../errors/cli-error.ts";
+import { ExitCode } from "../errors/exit-codes.ts";
+
+/**
+ * Validate that a string is a valid numeric ID (positive integer).
+ * Rejects before API call to give a clear local error (CLI-09).
+ */
+export function validateNumericId(value: string, label: string = "ID"): number {
+	const num = Number(value);
+	if (!Number.isSafeInteger(num) || num <= 0) {
+		throw new CliError(
+			`Invalid ${label}: "${value}". Must be a positive integer.`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			`Provide a numeric ${label}, e.g.: geekbot standup get 123`,
+		);
+	}
+	return num;
+}
+
+/**
+ * Validate time format (HH:MM in 24-hour format).
+ */
+export function validateTimeFormat(value: string): string {
+	const match = /^([01]\d|2[0-3]):([0-5]\d)$/.exec(value);
+	if (!match) {
+		throw new CliError(
+			`Invalid time format: "${value}". Expected HH:MM (24-hour).`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			'Use 24-hour format, e.g.: --time "09:30" or --time "14:00"',
+		);
+	}
+	return value;
+}
+
+/**
+ * Validate that a string is a Slack-style user ID (e.g. "UHNM44125", "U08LXSA31BJ").
+ * Slack IDs start with an uppercase letter followed by uppercase alphanumeric characters.
+ */
+export function validateSlackId(value: string, label: string = "user ID"): string {
+	if (!/^[A-Z][A-Z0-9]+$/.test(value)) {
+		throw new CliError(
+			`Invalid ${label}: "${value}". Must be a Slack-style ID (e.g. U08LXSA31BJ).`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			`Provide a Slack-style ${label}, e.g.: --user-id U08LXSA31BJ`,
+		);
+	}
+	return value;
+}
+
+/**
+ * Validate a comma-separated list of Slack-style user IDs.
+ */
+export function validateSlackIdList(value: string, label: string): string[] {
+	const parts = value.split(",");
+	const result: string[] = [];
+	for (const part of parts) {
+		result.push(validateSlackId(part.trim(), label));
+	}
+	return result;
+}
+
+/**
+ * Validate that a string is a valid non-negative integer (for wait_time etc.).
+ */
+export function validateWaitTime(value: string): number {
+	const num = Number(value);
+	if (!Number.isSafeInteger(num) || num < 0) {
+		throw new CliError(
+			`Invalid wait time: "${value}". Must be a non-negative integer.`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			`Provide a numeric value in minutes, e.g.: --wait-time 15`,
+		);
+	}
+	return num;
+}
+
+/**
+ * Validate that a string is a valid positive integer for use as a limit.
+ */
+export function validateLimit(value: string): number {
+	const num = Number(value);
+	if (!Number.isSafeInteger(num) || num < 1) {
+		throw new CliError(
+			`Invalid limit: "${value}" — must be a positive integer`,
+			"validation_error",
+			ExitCode.VALIDATION,
+			false,
+			"Example: --limit 10",
+		);
+	}
+	return num;
+}
+
+/**
+ * Validate day abbreviations (Mon, Tue, Wed, Thu, Fri, Sat, Sun).
+ */
+export function validateDayAbbreviations(values: string[]): string[] {
+	const validMap = new Map([
+		["mon", "Mon"],
+		["tue", "Tue"],
+		["wed", "Wed"],
+		["thu", "Thu"],
+		["fri", "Fri"],
+		["sat", "Sat"],
+		["sun", "Sun"],
+	]);
+	return values.map((day) => {
+		const normalized = validMap.get(day.toLowerCase());
+		if (!normalized) {
+			throw new CliError(
+				`Invalid day abbreviation: "${day}". Valid values: Mon, Tue, Wed, Thu, Fri, Sat, Sun.`,
+				"validation_error",
+				ExitCode.VALIDATION,
+				false,
+				'Use three-letter abbreviations: --days "Mon,Wed,Fri"',
+			);
+		}
+		return normalized;
+	});
+}