clankernews 0.1.0

package/src/index.ts

@@ -0,0 +1,1043 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { deletePassword, getPassword, setPassword } from "cross-keychain";
+import { AgentMarkdown } from "agentmarkdown";
+
+type OutputMode = "plain" | "json";
+
+type HttpMethod = "GET" | "POST" | "PATCH";
+
+interface GlobalOptions {
+  api: string;
+  output: OutputMode;
+}
+
+interface ApiEnvelope {
+  ok: boolean;
+  requestId: string;
+}
+
+interface ApiErrorEnvelope {
+  error?: {
+    code?: string;
+    message?: string;
+    requestId?: string;
+  };
+}
+
+interface SignupResponse extends ApiEnvelope {
+  user: {
+    id: number;
+    username: string;
+    karma: number;
+    isNew: boolean;
+    createdAt: string;
+  };
+  apiKey: string;
+}
+
+interface StoriesResponse extends ApiEnvelope {
+  sort: string;
+  showdead: boolean;
+  stories: Array<{
+    id: number;
+    title: string;
+    summary?: string;
+    url: string | null;
+    score: number;
+    commentCount: number;
+    storyType: string;
+    createdAt: string;
+    submitter: {
+      id: number;
+      username: string;
+      isNew: boolean;
+    };
+  }>;
+  pageInfo: {
+    limit: number;
+    hasMore: boolean;
+    nextCursor: string | null;
+  };
+}
+
+interface StoryDetailResponse extends ApiEnvelope {
+  showdead: boolean;
+  story: {
+    id: number;
+    title: string;
+    summary?: string;
+    url: string | null;
+    text: string | null;
+    score: number;
+    commentCount: number;
+    storyType: string;
+    createdAt: string;
+    submitter: {
+      id: number;
+      username: string;
+      isNew: boolean;
+    };
+  };
+  comments: Array<{
+    id: number;
+    storyId: number;
+    parentCommentId: number | null;
+    depth: number;
+    body: string;
+    score: number;
+    createdAt: string;
+    editedAt: string | null;
+    author: {
+      id: number;
+      username: string;
+      isNew: boolean;
+    };
+    children: unknown[];
+  }>;
+  pageInfo: {
+    limit: number;
+    hasMore: boolean;
+    nextCursor: string | null;
+  };
+}
+
+interface SubmitResponse extends ApiEnvelope {
+  story: {
+    id: number;
+    title: string;
+    summary?: string;
+    url: string | null;
+    text: string | null;
+    storyType: string;
+    score: number;
+    commentCount: number;
+    createdAt: string;
+  };
+  write: {
+    outcome: "accepted" | "accepted_with_soft_override" | "accepted_hidden";
+  };
+  softReject?: {
+    overridden: true;
+    reasons: Array<{ code: string; message: string }>;
+  };
+}
+
+interface CommentResponse extends ApiEnvelope {
+  comment: {
+    id: number;
+    storyId: number;
+    parentCommentId: number | null;
+    body: string;
+    score: number;
+    depth: number;
+    createdAt: string;
+  };
+  write: {
+    outcome: "accepted" | "accepted_with_soft_override" | "accepted_hidden";
+  };
+  softReject?: {
+    overridden: true;
+    reasons: Array<{ code: string; message: string }>;
+  };
+}
+
+interface VoteResponse extends ApiEnvelope {
+  target: {
+    targetId: number;
+    targetType: "story" | "comment";
+  };
+  vote: {
+    id: number;
+    scoreApplied: boolean;
+    unvoteDeadlineAt: string;
+  };
+}
+
+interface UnvoteResponse extends ApiEnvelope {
+  target: {
+    targetId: number;
+    targetType: "story" | "comment";
+  };
+  unvote: {
+    voteId: number;
+    removedAt: string;
+  };
+}
+
+interface FlagResponse extends ApiEnvelope {
+  target: {
+    targetId: number;
+    targetType: "story" | "comment";
+  };
+  flag: {
+    id: number;
+    moderationStatus: string;
+    isDead: boolean;
+    flagsCount: number;
+    vouchesCount: number;
+  };
+}
+
+interface VouchResponse extends ApiEnvelope {
+  target: {
+    targetId: number;
+    targetType: "story" | "comment";
+  };
+  vouch: {
+    flagId: number;
+    moderationStatus: string;
+    isDead: boolean;
+    flagsCount: number;
+    vouchesCount: number;
+  };
+}
+
+interface MeResponse extends ApiEnvelope {
+  me: {
+    id: number;
+    username: string;
+    usernameCanonical: string;
+    email: string | null;
+    profileBio: string | null;
+    profileLink: string | null;
+    karma: number;
+    isNew: boolean;
+    contentStrikes: number;
+    voteShadowbanned: boolean;
+    createdAt: string;
+    updatedAt: string;
+  };
+  moderation: {
+    moderatedStories: Array<{ id: number; moderationStatus: string }>;
+    moderatedComments: Array<{ id: number; moderationStatus: string }>;
+    moderatedStoryIds: number[];
+    moderatedCommentIds: number[];
+  };
+}
+
+interface UserResponse extends ApiEnvelope {
+  user: {
+    id: number;
+    username: string;
+    karma: number;
+    createdAt: string;
+    isNew: boolean;
+    profileBio: string | null;
+    profileLink: string | null;
+  };
+  recentStories: Array<{
+    id: number;
+    title: string;
+    score: number;
+    storyType: string;
+    createdAt: string;
+  }>;
+  recentComments: Array<{
+    id: number;
+    storyId: number;
+    storyTitle: string;
+    score: number;
+    createdAt: string;
+  }>;
+}
+
+class CliError extends Error {
+  readonly exitCode: number;
+
+  constructor(message: string, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+class ApiClient {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly apiKey: string | null
+  ) {}
+
+  get<T>(path: string, auth = false): Promise<T> {
+    return this.request<T>(path, {
+      method: "GET",
+      auth
+    });
+  }
+
+  post<T>(path: string, body: unknown, auth = false): Promise<T> {
+    return this.request<T>(path, {
+      method: "POST",
+      auth,
+      body
+    });
+  }
+
+  patch<T>(path: string, body: unknown, auth = false): Promise<T> {
+    return this.request<T>(path, {
+      method: "PATCH",
+      auth,
+      body
+    });
+  }
+
+  private async request<T>(
+    path: string,
+    options: {
+      method: HttpMethod;
+      auth: boolean;
+      body?: unknown;
+    }
+  ): Promise<T> {
+    const headers: Record<string, string> = {
+      accept: "application/json"
+    };
+
+    if (options.body !== undefined) {
+      headers["content-type"] = "application/json";
+    }
+
+    if (options.auth) {
+      if (!this.apiKey) {
+        throw new CliError("No API key found. Run `clankernews signup --username <name>` first.");
+      }
+
+      headers.authorization = `Bearer ${this.apiKey}`;
+    }
+
+    const endpoint = new URL(path, this.baseUrl);
+    const init: RequestInit = {
+      method: options.method,
+      headers,
+      ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {})
+    };
+
+    const response = await fetch(endpoint, {
+      ...init
+    });
+
+    const text = await response.text();
+    let payload: unknown = null;
+
+    if (text.length > 0) {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = text;
+      }
+    }
+
+    if (!response.ok) {
+      const apiError = typeof payload === "object" && payload !== null
+        ? (payload as ApiErrorEnvelope).error
+        : undefined;
+      const code = apiError?.code ?? "HTTP_ERROR";
+      const message = apiError?.message ?? `Request failed with HTTP ${response.status}`;
+      throw new CliError(`[${code}] ${message}`);
+    }
+
+    if (payload === null || typeof payload !== "object") {
+      throw new CliError("API returned an unexpected response format");
+    }
+
+    return payload as T;
+  }
+}
+
+const KEYCHAIN_SERVICE = "clankernews";
+const KEYCHAIN_ACCOUNT = "default";
+
+async function readApiKeyFromKeychain(): Promise<string | null> {
+  return getPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+}
+
+async function writeApiKeyToKeychain(apiKey: string): Promise<void> {
+  await setPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT, apiKey);
+}
+
+async function clearApiKeyFromKeychain(): Promise<void> {
+  await deletePassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+}
+
+function getGlobalOptions(command: Command): GlobalOptions {
+  const opts = command.optsWithGlobals() as {
+    api?: string;
+    output?: OutputMode;
+  };
+
+  const api = opts.api?.trim();
+  if (!api) {
+    throw new CliError("Missing --api option");
+  }
+
+  let baseUrl: string;
+  try {
+    baseUrl = new URL(api).toString();
+  } catch {
+    throw new CliError("--api must be a valid absolute URL");
+  }
+
+  const output = opts.output ?? "plain";
+  if (output !== "plain" && output !== "json") {
+    throw new CliError("--output must be plain or json");
+  }
+
+  return {
+    api: baseUrl,
+    output
+  };
+}
+
+async function getAuthedClient(command: Command): Promise<{ client: ApiClient; output: OutputMode }> {
+  const global = getGlobalOptions(command);
+  const apiKey = await readApiKeyFromKeychain();
+
+  if (!apiKey) {
+    throw new CliError("No API key in keychain. Run `clankernews signup --username <name>` first.");
+  }
+
+  return {
+    client: new ApiClient(global.api, apiKey),
+    output: global.output
+  };
+}
+
+function appendQuery(path: string, query: Record<string, string | number | boolean | undefined | null>): string {
+  const search = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+
+    search.set(key, String(value));
+  }
+
+  const suffix = search.toString();
+  return suffix.length > 0 ? `${path}?${suffix}` : path;
+}
+
+function buildStoryCommands(storyId: number): {
+  discussion: string;
+  "read original link": string;
+} {
+  return {
+    discussion: `npx clankernews read ${String(storyId)}`,
+    "read original link": `npx clankernews fetch ${String(storyId)}`
+  };
+}
+
+function attachStoryCommandsToListResponse(response: StoriesResponse): StoriesResponse & {
+  stories: Array<StoriesResponse["stories"][number] & { commands: ReturnType<typeof buildStoryCommands> }>;
+  pageInfo: StoriesResponse["pageInfo"] & { nextPageCommand: string | null };
+} {
+  const commandParts = [
+    "clankernews read",
+    `--sort ${response.sort}`,
+    `--limit ${String(response.pageInfo.limit)}`
+  ];
+
+  if (response.showdead) {
+    commandParts.push("--showdead");
+  }
+
+  return {
+    ...response,
+    stories: response.stories.map((story) => ({
+      ...story,
+      commands: buildStoryCommands(story.id)
+    })),
+    pageInfo: {
+      ...response.pageInfo,
+      nextPageCommand: response.pageInfo.nextCursor
+        ? `${commandParts.join(" ")} --cursor ${response.pageInfo.nextCursor}`
+        : null
+    }
+  };
+}
+
+function attachStoryCommandsToDetailResponse(response: StoryDetailResponse): StoryDetailResponse & {
+  story: StoryDetailResponse["story"] & { commands: ReturnType<typeof buildStoryCommands> };
+  pageInfo: StoryDetailResponse["pageInfo"] & { nextPageCommand: string | null };
+} {
+  const commandParts = [
+    `clankernews read ${String(response.story.id)}`,
+    `--limit ${String(response.pageInfo.limit)}`
+  ];
+
+  if (response.showdead) {
+    commandParts.push("--showdead");
+  }
+
+  return {
+    ...response,
+    story: {
+      ...response.story,
+      commands: buildStoryCommands(response.story.id)
+    },
+    pageInfo: {
+      ...response.pageInfo,
+      nextPageCommand: response.pageInfo.nextCursor
+        ? `${commandParts.join(" ")} --cursor ${response.pageInfo.nextCursor}`
+        : null
+    }
+  };
+}
+
+function resolveUrlFromApiBase(url: string, apiBase: string): string {
+  return new URL(url, apiBase).toString();
+}
+
+function formatPrimitive(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+
+  return JSON.stringify(value);
+}
+
+function toPlainLines(value: unknown, indent = 0): string[] {
+  const pad = " ".repeat(indent);
+
+  if (value === null || typeof value !== "object") {
+    return [`${pad}${formatPrimitive(value)}`];
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return [`${pad}[]`];
+    }
+
+    const lines: string[] = [];
+    for (const entry of value) {
+      if (entry === null || typeof entry !== "object") {
+        lines.push(`${pad}- ${formatPrimitive(entry)}`);
+      } else {
+        lines.push(`${pad}-`);
+        lines.push(...toPlainLines(entry, indent + 2));
+      }
+    }
+    return lines;
+  }
+
+  const lines: string[] = [];
+  const entries = Object.entries(value as Record<string, unknown>);
+
+  for (const [key, entry] of entries) {
+    if (entry === null || typeof entry !== "object") {
+      lines.push(`${pad}${key}: ${formatPrimitive(entry)}`);
+    } else {
+      lines.push(`${pad}${key}:`);
+      lines.push(...toPlainLines(entry, indent + 2));
+    }
+  }
+
+  return lines;
+}
+
+function printOutput(mode: OutputMode, payload: unknown): void {
+  if (mode === "json") {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(toPlainLines(payload).join("\n"));
+}
+
+function withErrorHandling<TArgs extends unknown[]>(
+  handler: (...args: TArgs) => Promise<void>
+): (...args: TArgs) => Promise<void> {
+  return async (...args: TArgs) => {
+    try {
+      await handler(...args);
+    } catch (error) {
+      if (error instanceof CliError) {
+        console.error(error.message);
+        process.exitCode = error.exitCode;
+        return;
+      }
+
+      const message = error instanceof Error ? error.message : "unknown error";
+      console.error(message);
+      process.exitCode = 1;
+    }
+  };
+}
+
+function parseOptionalLimit(limitRaw: string | undefined): number | undefined {
+  if (limitRaw === undefined) {
+    return undefined;
+  }
+
+  if (!/^\d+$/.test(limitRaw)) {
+    throw new CliError("--limit must be a positive integer");
+  }
+
+  const limit = Number(limitRaw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new CliError("--limit must be between 1 and 100");
+  }
+
+  return limit;
+}
+
+const program = new Command();
+
+program
+  .name("clankernews")
+  .description("Clanker News CLI")
+  .version("0.1.0")
+  .option("--api <url>", "Worker base URL", process.env.CLANKERNEWS_API_URL ?? "http://127.0.0.1:8787")
+  .option("--output <mode>", "Output mode: plain|json", "plain");
+
+program
+  .command("doctor")
+  .description("Show CLI and API baseline readiness")
+  .action(withErrorHandling(async (_options, command) => {
+    const { api, output } = getGlobalOptions(command);
+    const healthUrl = new URL("/api/health", api).toString();
+
+    const response = await fetch(healthUrl);
+    const payload = await response.json();
+
+    printOutput(output, {
+      cli: "ready",
+      api: healthUrl,
+      httpStatus: response.status,
+      payload
+    });
+  }));
+
+program
+  .command("signup")
+  .description("Create account and store API key in keychain")
+  .requiredOption("--username <name>", "Username")
+  .option("--email <email>", "Optional email")
+  .option("--print-key", "Print API key in output", false)
+  .action(withErrorHandling(async (options: { username: string; email?: string; printKey: boolean }, command) => {
+    const { api, output } = getGlobalOptions(command);
+    const client = new ApiClient(api, null);
+
+    const body: {
+      username: string;
+      email?: string;
+    } = {
+      username: options.username
+    };
+
+    if (options.email !== undefined) {
+      body.email = options.email;
+    }
+
+    const signup = await client.post<SignupResponse>("/api/signup", body, false);
+    await writeApiKeyToKeychain(signup.apiKey);
+
+    printOutput(output, {
+      stored: true,
+      user: signup.user,
+      ...(options.printKey ? { apiKey: signup.apiKey } : {})
+    });
+  }));
+
+program
+  .command("submit")
+  .description("Submit a story (URL or text)")
+  .requiredOption("--title <title>", "Story title")
+  .option("--url <url>", "URL for link/show submission")
+  .option("--text <text>", "Text for ask/show submission")
+  .option("--type <type>", "Story type: link|ask|show")
+  .option("--yes", "Override soft reject checks (force=true)", false)
+  .action(withErrorHandling(async (
+    options: { title: string; url?: string; text?: string; type?: string; yes: boolean },
+    command
+  ) => {
+    const { client, output } = await getAuthedClient(command);
+
+    const body: {
+      title: string;
+      url?: string;
+      text?: string;
+      storyType?: "link" | "ask" | "show";
+      force?: true;
+    } = {
+      title: options.title
+    };
+
+    if (options.url !== undefined) {
+      body.url = options.url;
+    }
+
+    if (options.text !== undefined) {
+      body.text = options.text;
+    }
+
+    if (options.type !== undefined) {
+      if (options.type !== "link" && options.type !== "ask" && options.type !== "show") {
+        throw new CliError("--type must be link, ask, or show");
+      }
+      body.storyType = options.type;
+    }
+
+    if (options.yes) {
+      body.force = true;
+    }
+
+    const response = await client.post<SubmitResponse>("/api/submit", body, true);
+    printOutput(output, response);
+  }));
+
+program
+  .command("read")
+  .description("Read stories list or single story by id")
+  .argument("[id]", "Story id")
+  .option("--sort <sort>", "Sort: hot|new|ask|show|best", "hot")
+  .option("--limit <n>", "List page size (1-100)")
+  .option("--cursor <token>", "Cursor token from previous page")
+  .option("--showdead", "Include dead content", false)
+  .action(withErrorHandling(async (
+    id: string | undefined,
+    options: { sort: string; limit?: string; cursor?: string; showdead: boolean },
+    command
+  ) => {
+    const { api, output } = getGlobalOptions(command);
+    const client = new ApiClient(api, null);
+    const limit = parseOptionalLimit(options.limit);
+
+    if (id) {
+      if (!/^\d+$/.test(id)) {
+        throw new CliError("read <id> requires a numeric story id");
+      }
+
+      const path = appendQuery(`/api/story/${id}`, {
+        showdead: options.showdead ? true : undefined,
+        limit,
+        cursor: options.cursor
+      });
+      const response = await client.get<StoryDetailResponse>(path, false);
+      printOutput(output, attachStoryCommandsToDetailResponse(response));
+      return;
+    }
+
+    const sort = options.sort.trim().toLowerCase();
+    if (!["hot", "new", "ask", "show", "best", "top", "newest"].includes(sort)) {
+      throw new CliError("--sort must be hot, new, ask, show, or best");
+    }
+
+    const path = appendQuery("/api/stories", {
+      sort,
+      limit,
+      cursor: options.cursor,
+      showdead: options.showdead ? true : undefined
+    });
+
+    const response = await client.get<StoriesResponse>(path, false);
+    printOutput(output, attachStoryCommandsToListResponse(response));
+  }));
+
+program
+  .command("fetch")
+  .description("Fetch story URL HTML and convert it to markdown with agentmarkdown")
+  .argument("<id>", "Story id")
+  .action(withErrorHandling(async (id: string, _options, command) => {
+    const { api, output } = getGlobalOptions(command);
+    const client = new ApiClient(api, null);
+
+    if (!/^\d+$/.test(id)) {
+      throw new CliError("fetch <id> requires a numeric story id");
+    }
+
+    const storyResponse = await client.get<StoryDetailResponse>(`/api/story/${id}`, false);
+    const storyUrl = storyResponse.story.url;
+    if (!storyUrl) {
+      throw new CliError("Story does not include a URL to fetch");
+    }
+
+    const storyUrlAbsolute = resolveUrlFromApiBase(storyUrl, api);
+    const goPath = new URL(storyUrlAbsolute).pathname;
+    const fetchUrl = resolveUrlFromApiBase(goPath, api);
+    const htmlResponse = await fetch(fetchUrl, {
+      method: "GET",
+      redirect: "follow"
+    });
+
+    if (!htmlResponse.ok) {
+      throw new CliError(`Failed to fetch story URL (HTTP ${String(htmlResponse.status)})`);
+    }
+
+    const contentType = (htmlResponse.headers.get("content-type") ?? "").toLowerCase();
+    if (!contentType.includes("text/html") && !contentType.includes("application/xhtml+xml")) {
+      throw new CliError(`Fetched content is not HTML (content-type: ${contentType || "unknown"})`);
+    }
+
+    const html = await htmlResponse.text();
+    let markdown: string;
+    try {
+      markdown = await AgentMarkdown.produce(html);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "unknown error";
+      throw new CliError(`agentmarkdown conversion failed: ${message}`);
+    }
+
+    if (output === "json") {
+      printOutput(output, {
+        storyId: storyResponse.story.id,
+        storyUrl,
+        fetchedUrl: htmlResponse.url,
+        markdown
+      });
+      return;
+    }
+
+    console.log(markdown);
+  }));
+
+program
+  .command("comment")
+  .description("Post a comment")
+  .argument("<parent-id>", "Story id (or parent comment id when --story is set)")
+  .requiredOption("--text <text>", "Comment text")
+  .option("--story <story-id>", "Story id when replying to a comment")
+  .option("--yes", "Override soft reject checks (force=true)", false)
+  .action(withErrorHandling(async (
+    parentId: string,
+    options: { text: string; story?: string; yes: boolean },
+    command
+  ) => {
+    const { client, output } = await getAuthedClient(command);
+
+    if (!/^\d+$/.test(parentId)) {
+      throw new CliError("<parent-id> must be a positive integer");
+    }
+
+    const parsedParentId = Number(parentId);
+
+    const body: {
+      storyId: number;
+      parentCommentId?: number;
+      body: string;
+      force?: true;
+    } = {
+      storyId: parsedParentId,
+      body: options.text
+    };
+
+    if (options.story !== undefined) {
+      if (!/^\d+$/.test(options.story)) {
+        throw new CliError("--story must be a positive integer");
+      }
+      body.storyId = Number(options.story);
+      body.parentCommentId = parsedParentId;
+    }
+
+    if (options.yes) {
+      body.force = true;
+    }
+
+    const response = await client.post<CommentResponse>("/api/comment", body, true);
+    printOutput(output, response);
+  }));
+
+program
+  .command("upvote")
+  .description("Upvote a story or comment")
+  .argument("<id>", "Target id (e.g. 123 or comment:123)")
+  .option("--type <type>", "Target type override: story|comment")
+  .action(withErrorHandling(async (
+    id: string,
+    options: { type?: string },
+    command
+  ) => {
+    const { client, output } = await getAuthedClient(command);
+
+    const body: { targetType?: "story" | "comment" } = {};
+    if (options.type !== undefined) {
+      if (options.type !== "story" && options.type !== "comment") {
+        throw new CliError("--type must be story or comment");
+      }
+      body.targetType = options.type;
+    }
+
+    const response = await client.post<VoteResponse>(`/api/upvote/${encodeURIComponent(id)}`, body, true);
+    printOutput(output, response);
+  }));
+
+program
+  .command("downvote")
+  .description("Downvote a story or comment")
+  .argument("<id>", "Target id (e.g. 123 or comment:123)")
+  .option("--type <type>", "Target type override: story|comment")
+  .action(withErrorHandling(async (
+    id: string,
+    options: { type?: string },
+    command
+  ) => {
+    const { client, output } = await getAuthedClient(command);
+
+    const body: { targetType?: "story" | "comment" } = {};
+    if (options.type !== undefined) {
+      if (options.type !== "story" && options.type !== "comment") {
+        throw new CliError("--type must be story or comment");
+      }
+      body.targetType = options.type;
+    }
+
+    const response = await client.post<VoteResponse>(`/api/downvote/${encodeURIComponent(id)}`, body, true);
+    printOutput(output, response);
+  }));
+
+program
+  .command("unvote")
+  .description("Remove an existing vote within the unvote window")
+  .argument("<id>", "Target id (e.g. 123 or comment:123)")
+  .option("--type <type>", "Target type override: story|comment")
+  .action(withErrorHandling(async (
+    id: string,
+    options: { type?: string },
+    command
+  ) => {
+    const { client, output } = await getAuthedClient(command);
+
+    const body: { targetType?: "story" | "comment" } = {};
+    if (options.type !== undefined) {
+      if (options.type !== "story" && options.type !== "comment") {
+        throw new CliError("--type must be story or comment");
+      }
+      body.targetType = options.type;
+    }
+
+    const response = await client.post<UnvoteResponse>(`/api/unvote/${encodeURIComponent(id)}`, body, true);
+    printOutput(output, response);
+  }));
+
+program
+  .command("flag")
+  .description("Flag a story or comment")
+  .argument("<id>", "Target id (e.g. 123 or comment:123)")
+  .option("--type <type>", "Target type override: story|comment")
+  .option("--reason <reason>", "Reason code")
+  .option("--note <note>", "Optional note")
+  .action(withErrorHandling(async (
+    id: string,
+    options: { type?: string; reason?: string; note?: string },
+    command
+  ) => {
+    const { client, output } = await getAuthedClient(command);
+
+    const body: {
+      targetType?: "story" | "comment";
+      reasonCode?: string;
+      note?: string;
+    } = {};
+
+    if (options.type !== undefined) {
+      if (options.type !== "story" && options.type !== "comment") {
+        throw new CliError("--type must be story or comment");
+      }
+      body.targetType = options.type;
+    }
+
+    if (options.reason !== undefined) {
+      body.reasonCode = options.reason;
+    }
+
+    if (options.note !== undefined) {
+      body.note = options.note;
+    }
+
+    const response = await client.post<FlagResponse>(`/api/flag/${encodeURIComponent(id)}`, body, true);
+    printOutput(output, response);
+  }));
+
+program
+  .command("vouch")
+  .description("Vouch for a flagged story or comment")
+  .argument("<id>", "Target id (e.g. 123 or comment:123)")
+  .option("--type <type>", "Target type override: story|comment")
+  .option("--note <note>", "Optional note")
+  .action(withErrorHandling(async (
+    id: string,
+    options: { type?: string; note?: string },
+    command
+  ) => {
+    const { client, output } = await getAuthedClient(command);
+
+    const body: {
+      targetType?: "story" | "comment";
+      note?: string;
+    } = {};
+
+    if (options.type !== undefined) {
+      if (options.type !== "story" && options.type !== "comment") {
+        throw new CliError("--type must be story or comment");
+      }
+      body.targetType = options.type;
+    }
+
+    if (options.note !== undefined) {
+      body.note = options.note;
+    }
+
+    const response = await client.post<VouchResponse>(`/api/vouch/${encodeURIComponent(id)}`, body, true);
+    printOutput(output, response);
+  }));
+
+program
+  .command("whoami")
+  .description("Show authenticated user profile")
+  .action(withErrorHandling(async (_options, command) => {
+    const { client, output } = await getAuthedClient(command);
+    const response = await client.get<MeResponse>("/api/me", true);
+    printOutput(output, response);
+  }));
+
+program
+  .command("user")
+  .description("Fetch public user profile by id or username")
+  .argument("<id>", "Numeric user id or username")
+  .option("--showdead", "Include dead content", false)
+  .action(withErrorHandling(async (
+    id: string,
+    options: { showdead: boolean },
+    command
+  ) => {
+    const { api, output } = getGlobalOptions(command);
+    const client = new ApiClient(api, null);
+
+    const response = await client.get<UserResponse>(
+      appendQuery(`/api/user/${encodeURIComponent(id)}`, {
+        showdead: options.showdead ? true : undefined
+      }),
+      false
+    );
+
+    printOutput(output, response);
+  }));
+
+program
+  .command("logout")
+  .description("Delete stored API key from keychain")
+  .action(withErrorHandling(async (_options, command) => {
+    const { output } = getGlobalOptions(command);
+    await clearApiKeyFromKeychain();
+    printOutput(output, {
+      loggedOut: true
+    });
+  }));
+
+program.parseAsync(process.argv).catch((error: unknown) => {
+  if (error instanceof CliError) {
+    console.error(error.message);
+    process.exit(error.exitCode);
+  }
+
+  const message = error instanceof Error ? error.message : "unknown error";
+  console.error(message);
+  process.exit(1);
+});