gsd-pi 2.3.5 → 2.3.7

package/src/resources/extensions/gsd/tests/remote-questions.test.ts

@@ -0,0 +1,155 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseSlackReply, parseDiscordResponse } from "../../remote-questions/format.ts";
+import { resolveRemoteConfig, isValidChannelId } from "../../remote-questions/config.ts";
+import { sanitizeError } from "../../remote-questions/manager.ts";
+
+test("parseSlackReply handles single-number single-question answers", () => {
+  const result = parseSlackReply("2", [{
+    id: "choice",
+    header: "Choice",
+    question: "Pick one",
+    allowMultiple: false,
+    options: [
+      { label: "Alpha", description: "A" },
+      { label: "Beta", description: "B" },
+    ],
+  }]);
+
+  assert.deepEqual(result, { answers: { choice: { answers: ["Beta"] } } });
+});
+
+test("parseSlackReply handles multiline multi-question answers", () => {
+  const result = parseSlackReply("1\ncustom note", [
+    {
+      id: "first",
+      header: "First",
+      question: "Pick one",
+      allowMultiple: false,
+      options: [
+        { label: "Alpha", description: "A" },
+        { label: "Beta", description: "B" },
+      ],
+    },
+    {
+      id: "second",
+      header: "Second",
+      question: "Explain",
+      allowMultiple: false,
+      options: [
+        { label: "Gamma", description: "G" },
+        { label: "Delta", description: "D" },
+      ],
+    },
+  ]);
+
+  assert.deepEqual(result, {
+    answers: {
+      first: { answers: ["Alpha"] },
+      second: { answers: [], user_note: "custom note" },
+    },
+  });
+});
+
+test("parseDiscordResponse handles single-question reactions", () => {
+  const result = parseDiscordResponse([{ emoji: "2️⃣", count: 1 }], null, [{
+    id: "choice",
+    header: "Choice",
+    question: "Pick one",
+    allowMultiple: false,
+    options: [
+      { label: "Alpha", description: "A" },
+      { label: "Beta", description: "B" },
+    ],
+  }]);
+
+  assert.deepEqual(result, { answers: { choice: { answers: ["Beta"] } } });
+});
+
+test("parseDiscordResponse rejects multi-question reaction parsing", () => {
+  const result = parseDiscordResponse([{ emoji: "1️⃣", count: 1 }], null, [
+    {
+      id: "first",
+      header: "First",
+      question: "Pick one",
+      allowMultiple: false,
+      options: [{ label: "Alpha", description: "A" }],
+    },
+    {
+      id: "second",
+      header: "Second",
+      question: "Pick one",
+      allowMultiple: false,
+      options: [{ label: "Beta", description: "B" }],
+    },
+  ]);
+
+  assert.match(String(result.answers.first.user_note), /single-question prompts/i);
+  assert.match(String(result.answers.second.user_note), /single-question prompts/i);
+});
+
+test("parseSlackReply truncates user_note longer than 500 chars", () => {
+  const longText = "x".repeat(600);
+  const result = parseSlackReply(longText, [{
+    id: "q1",
+    header: "Q1",
+    question: "Pick",
+    allowMultiple: false,
+    options: [{ label: "A", description: "a" }],
+  }]);
+
+  const note = result.answers.q1.user_note!;
+  assert.ok(note.length <= 502, `note should be truncated, got ${note.length} chars`);
+  assert.ok(note.endsWith("…"), "truncated note should end with ellipsis");
+});
+
+test("isValidChannelId rejects invalid Slack channel IDs", () => {
+  // Too short
+  assert.equal(isValidChannelId("slack", "C123"), false);
+  // Contains invalid chars (URL injection)
+  assert.equal(isValidChannelId("slack", "https://evil.com"), false);
+  // Lowercase
+  assert.equal(isValidChannelId("slack", "c12345678"), false);
+  // Too long
+  assert.equal(isValidChannelId("slack", "C1234567890AB"), false);
+  // Valid: 9-12 uppercase alphanumeric
+  assert.equal(isValidChannelId("slack", "C12345678"), true);
+  assert.equal(isValidChannelId("slack", "C12345678AB"), true);
+  assert.equal(isValidChannelId("slack", "C1234567890A"), true);
+});
+
+test("isValidChannelId rejects invalid Discord channel IDs", () => {
+  // Too short
+  assert.equal(isValidChannelId("discord", "12345"), false);
+  // Contains letters (not a snowflake)
+  assert.equal(isValidChannelId("discord", "abc12345678901234"), false);
+  // URL injection
+  assert.equal(isValidChannelId("discord", "https://evil.com"), false);
+  // Too long (21 digits)
+  assert.equal(isValidChannelId("discord", "123456789012345678901"), false);
+  // Valid: 17-20 digit snowflake
+  assert.equal(isValidChannelId("discord", "12345678901234567"), true);
+  assert.equal(isValidChannelId("discord", "11234567890123456789"), true);
+});
+
+test("sanitizeError strips Slack token patterns from error messages", () => {
+  assert.equal(
+    sanitizeError("Auth failed: xoxb-1234-5678-abcdef"),
+    "Auth failed: [REDACTED]",
+  );
+  assert.equal(
+    sanitizeError("Bad token xoxp-abc-def-ghi in request"),
+    "Bad token [REDACTED] in request",
+  );
+});
+
+test("sanitizeError strips long opaque secrets", () => {
+  const fakeDiscordToken = "MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.G1x2y3.abcdefghijklmnop";
+  assert.ok(!sanitizeError(`Token: ${fakeDiscordToken}`).includes(fakeDiscordToken));
+});
+
+test("sanitizeError preserves short safe messages", () => {
+  assert.equal(sanitizeError("HTTP 401: Unauthorized"), "HTTP 401: Unauthorized");
+  assert.equal(sanitizeError("Connection refused"), "Connection refused");
+});
+

package/src/resources/extensions/gsd/tests/remote-status.test.ts

@@ -0,0 +1,99 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createPromptRecord, writePromptRecord } from "../../remote-questions/store.ts";
+import { getLatestPromptSummary } from "../../remote-questions/status.ts";
+
+function withTempHome(fn: (tempHome: string) => void | Promise<void>) {
+  return async () => {
+    const savedHome = process.env.HOME;
+    const savedUserProfile = process.env.USERPROFILE;
+    const tempHome = join(tmpdir(), `gsd-remote-status-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(join(tempHome, ".gsd", "runtime", "remote-questions"), { recursive: true });
+    process.env.HOME = tempHome;
+    process.env.USERPROFILE = tempHome;
+    try {
+      await fn(tempHome);
+    } finally {
+      process.env.HOME = savedHome;
+      process.env.USERPROFILE = savedUserProfile;
+      rmSync(tempHome, { recursive: true, force: true });
+    }
+  };
+}
+
+test("getLatestPromptSummary returns latest stored prompt", withTempHome(() => {
+  const recordA = createPromptRecord({
+    id: "a-prompt",
+    channel: "slack",
+    createdAt: 1,
+    timeoutAt: 10,
+    pollIntervalMs: 5000,
+    questions: [],
+  });
+  recordA.updatedAt = 1;
+  writePromptRecord(recordA);
+
+  const recordB = createPromptRecord({
+    id: "z-prompt",
+    channel: "discord",
+    createdAt: 2,
+    timeoutAt: 10,
+    pollIntervalMs: 5000,
+    questions: [],
+  });
+  recordB.updatedAt = 2;
+  recordB.status = "answered";
+  writePromptRecord(recordB);
+
+  const latest = getLatestPromptSummary();
+  assert.equal(latest?.id, "z-prompt");
+  assert.equal(latest?.status, "answered");
+}));
+
+test("getLatestPromptSummary sorts by updatedAt, not filename", withTempHome(() => {
+  // Record with alphabetically-LAST id but OLDEST timestamp
+  const old = createPromptRecord({
+    id: "zzz-oldest",
+    channel: "slack",
+    createdAt: 1000,
+    timeoutAt: 9999,
+    pollIntervalMs: 5000,
+    questions: [],
+  });
+  old.updatedAt = 1000;
+  writePromptRecord(old);
+
+  // Record with alphabetically-FIRST id but NEWEST timestamp
+  const newest = createPromptRecord({
+    id: "aaa-newest",
+    channel: "discord",
+    createdAt: 3000,
+    timeoutAt: 9999,
+    pollIntervalMs: 5000,
+    questions: [],
+  });
+  newest.updatedAt = 3000;
+  newest.status = "answered";
+  writePromptRecord(newest);
+
+  // Record in between
+  const middle = createPromptRecord({
+    id: "mmm-middle",
+    channel: "slack",
+    createdAt: 2000,
+    timeoutAt: 9999,
+    pollIntervalMs: 5000,
+    questions: [],
+  });
+  middle.updatedAt = 2000;
+  writePromptRecord(middle);
+
+  const latest = getLatestPromptSummary();
+  // Should return "aaa-newest" (updatedAt=3000), NOT "zzz-oldest" (alphabetically last)
+  assert.equal(latest?.id, "aaa-newest", "should pick the most recently updated prompt, not the alphabetically last filename");
+  assert.equal(latest?.status, "answered");
+  assert.equal(latest?.updatedAt, 3000);
+}));

package/src/resources/extensions/gsd/worktree.ts

@@ -86,6 +86,17 @@ export function ensureSliceBranch(basePath: string, milestoneId: string, sliceId
     created = true;
   }
 
+  // Auto-commit dirty files before checkout to prevent "would be overwritten" errors.
+  // This handles cases where doctor, STATE.md rebuild, or agent work left uncommitted changes.
+  const status = runGit(basePath, ["status", "--short"]);
+  if (status.trim()) {
+    runGit(basePath, ["add", "-A"]);
+    const staged = runGit(basePath, ["diff", "--cached", "--stat"]);
+    if (staged.trim()) {
+      runGit(basePath, ["commit", "-m", `"chore: auto-commit before switching to ${branch}"`]);
+    }
+  }
+
   runGit(basePath, ["checkout", branch]);
   return created;
 }

package/src/resources/extensions/remote-questions/config.ts

@@ -0,0 +1,81 @@
+/**
+ * Remote Questions — configuration resolution and validation
+ */
+
+import { loadEffectiveGSDPreferences, type RemoteQuestionsConfig } from "../gsd/preferences.js";
+import type { RemoteChannel } from "./types.js";
+
+export interface ResolvedConfig {
+  channel: RemoteChannel;
+  channelId: string;
+  timeoutMs: number;
+  pollIntervalMs: number;
+  token: string;
+}
+
+const ENV_KEYS: Record<RemoteChannel, string> = {
+  slack: "SLACK_BOT_TOKEN",
+  discord: "DISCORD_BOT_TOKEN",
+};
+
+// Channel ID format validation — prevents SSRF if preferences are attacker-controlled
+const CHANNEL_ID_PATTERNS: Record<RemoteChannel, RegExp> = {
+  slack: /^[A-Z0-9]{9,12}$/,
+  discord: /^\d{17,20}$/,
+};
+
+const DEFAULT_TIMEOUT_MINUTES = 5;
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const MIN_TIMEOUT_MINUTES = 1;
+const MAX_TIMEOUT_MINUTES = 30;
+const MIN_POLL_INTERVAL_SECONDS = 2;
+const MAX_POLL_INTERVAL_SECONDS = 30;
+
+export function resolveRemoteConfig(): ResolvedConfig | null {
+  const prefs = loadEffectiveGSDPreferences();
+  const rq: RemoteQuestionsConfig | undefined = prefs?.preferences.remote_questions;
+  if (!rq || !rq.channel || !rq.channel_id) return null;
+  if (rq.channel !== "slack" && rq.channel !== "discord") return null;
+
+  const channelId = String(rq.channel_id);
+  if (!CHANNEL_ID_PATTERNS[rq.channel].test(channelId)) return null;
+
+  const token = process.env[ENV_KEYS[rq.channel]];
+  if (!token) return null;
+
+  const timeoutMinutes = clampNumber(rq.timeout_minutes, DEFAULT_TIMEOUT_MINUTES, MIN_TIMEOUT_MINUTES, MAX_TIMEOUT_MINUTES);
+  const pollIntervalSeconds = clampNumber(rq.poll_interval_seconds, DEFAULT_POLL_INTERVAL_SECONDS, MIN_POLL_INTERVAL_SECONDS, MAX_POLL_INTERVAL_SECONDS);
+
+  return {
+    channel: rq.channel,
+    channelId,
+    timeoutMs: timeoutMinutes * 60 * 1000,
+    pollIntervalMs: pollIntervalSeconds * 1000,
+    token,
+  };
+}
+
+export function getRemoteConfigStatus(): string {
+  const prefs = loadEffectiveGSDPreferences();
+  const rq: RemoteQuestionsConfig | undefined = prefs?.preferences.remote_questions;
+  if (!rq || !rq.channel || !rq.channel_id) return "Remote questions: not configured";
+  if (rq.channel !== "slack" && rq.channel !== "discord") return `Remote questions: unknown channel type \"${rq.channel}\"`;
+  const channelId = String(rq.channel_id);
+  if (!CHANNEL_ID_PATTERNS[rq.channel].test(channelId)) return `Remote questions: invalid ${rq.channel} channel ID format`;
+  const envVar = ENV_KEYS[rq.channel];
+  if (!process.env[envVar]) return `Remote questions: ${envVar} not set — remote questions disabled`;
+
+  const timeoutMinutes = clampNumber(rq.timeout_minutes, DEFAULT_TIMEOUT_MINUTES, MIN_TIMEOUT_MINUTES, MAX_TIMEOUT_MINUTES);
+  const pollIntervalSeconds = clampNumber(rq.poll_interval_seconds, DEFAULT_POLL_INTERVAL_SECONDS, MIN_POLL_INTERVAL_SECONDS, MAX_POLL_INTERVAL_SECONDS);
+  return `Remote questions: ${rq.channel} configured (timeout ${timeoutMinutes}m, poll ${pollIntervalSeconds}s)`;
+}
+
+export function isValidChannelId(channel: RemoteChannel, id: string): boolean {
+  return CHANNEL_ID_PATTERNS[channel].test(id);
+}
+
+function clampNumber(value: unknown, fallback: number, min: number, max: number): number {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(min, Math.min(max, n));
+}

package/src/resources/extensions/remote-questions/discord-adapter.ts

@@ -0,0 +1,128 @@
+/**
+ * Remote Questions — Discord adapter
+ */
+
+import type { ChannelAdapter, RemotePrompt, RemoteDispatchResult, RemoteAnswer, RemotePromptRef } from "./types.js";
+import { formatForDiscord, parseDiscordResponse } from "./format.js";
+
+const DISCORD_API = "https://discord.com/api/v10";
+const PER_REQUEST_TIMEOUT_MS = 15_000;
+const NUMBER_EMOJIS = ["1️⃣", "2️⃣", "3️⃣", "4️⃣", "5️⃣"];
+
+export class DiscordAdapter implements ChannelAdapter {
+  readonly name = "discord" as const;
+  private botUserId: string | null = null;
+  private readonly token: string;
+  private readonly channelId: string;
+
+  constructor(token: string, channelId: string) {
+    this.token = token;
+    this.channelId = channelId;
+  }
+
+  async validate(): Promise<void> {
+    const res = await this.discordApi("GET", "/users/@me");
+    if (!res.id) throw new Error("Discord auth failed: invalid token");
+    this.botUserId = String(res.id);
+  }
+
+  async sendPrompt(prompt: RemotePrompt): Promise<RemoteDispatchResult> {
+    const { embeds, reactionEmojis } = formatForDiscord(prompt);
+    const res = await this.discordApi("POST", `/channels/${this.channelId}/messages`, {
+      content: "**GSD needs your input** — reply to this message with your answer",
+      embeds,
+    });
+
+    if (!res.id) throw new Error(`Discord send failed: ${JSON.stringify(res)}`);
+
+    const messageId = String(res.id);
+    if (prompt.questions.length === 1) {
+      for (const emoji of reactionEmojis) {
+        try {
+          await this.discordApi("PUT", `/channels/${this.channelId}/messages/${messageId}/reactions/${encodeURIComponent(emoji)}/@me`);
+        } catch {
+          // Best-effort only
+        }
+      }
+    }
+
+    return {
+      ref: {
+        id: prompt.id,
+        channel: "discord",
+        messageId,
+        channelId: this.channelId,
+      },
+    };
+  }
+
+  async pollAnswer(prompt: RemotePrompt, ref: RemotePromptRef): Promise<RemoteAnswer | null> {
+    if (!this.botUserId) await this.validate();
+
+    if (prompt.questions.length === 1) {
+      const reactionAnswer = await this.checkReactions(prompt, ref);
+      if (reactionAnswer) return reactionAnswer;
+    }
+
+    return this.checkReplies(prompt, ref);
+  }
+
+  private async checkReactions(prompt: RemotePrompt, ref: RemotePromptRef): Promise<RemoteAnswer | null> {
+    const reactions: Array<{ emoji: string; count: number }> = [];
+    for (const emoji of NUMBER_EMOJIS) {
+      try {
+        const users = await this.discordApi("GET", `/channels/${ref.channelId}/messages/${ref.messageId}/reactions/${encodeURIComponent(emoji)}`);
+        if (Array.isArray(users)) {
+          const humanUsers = users.filter((u: { id: string }) => u.id !== this.botUserId);
+          if (humanUsers.length > 0) reactions.push({ emoji, count: humanUsers.length });
+        }
+      } catch (err) {
+        const msg = String((err as Error).message ?? "");
+        // 404 = no reactions for this emoji — expected, continue
+        if (msg.includes("HTTP 404")) continue;
+        // 401/403 = auth failure — surface to caller so it can fail the poll
+        if (msg.includes("HTTP 401") || msg.includes("HTTP 403")) throw err;
+        // Other errors (rate limit, network) — skip this emoji, best-effort
+      }
+    }
+
+    if (reactions.length === 0) return null;
+    return parseDiscordResponse(reactions, null, prompt.questions);
+  }
+
+  private async checkReplies(prompt: RemotePrompt, ref: RemotePromptRef): Promise<RemoteAnswer | null> {
+    const messages = await this.discordApi("GET", `/channels/${ref.channelId}/messages?after=${ref.messageId}&limit=10`);
+    if (!Array.isArray(messages)) return null;
+
+    const replies = messages.filter(
+      (m: { author?: { id?: string }; message_reference?: { message_id?: string }; content?: string }) =>
+        m.author?.id &&
+        m.author.id !== this.botUserId &&
+        m.message_reference?.message_id === ref.messageId &&
+        m.content,
+    );
+
+    if (replies.length === 0) return null;
+    return parseDiscordResponse([], String(replies[0].content), prompt.questions);
+  }
+
+  private async discordApi(method: string, path: string, body?: unknown): Promise<any> {
+    const headers: Record<string, string> = { Authorization: `Bot ${this.token}` };
+    const init: RequestInit = { method, headers };
+    if (body) {
+      headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+
+    init.signal = AbortSignal.timeout(PER_REQUEST_TIMEOUT_MS);
+    const response = await fetch(`${DISCORD_API}${path}`, init);
+    if (response.status === 204) return {};
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      // Limit error body length to avoid leaking verbose Discord error responses
+      const safeText = text.length > 200 ? text.slice(0, 200) + "…" : text;
+      throw new Error(`Discord API HTTP ${response.status}: ${safeText}`);
+    }
+    return response.json();
+  }
+}

package/src/resources/extensions/remote-questions/format.ts

@@ -0,0 +1,163 @@
+/**
+ * Remote Questions — payload formatting and parsing helpers
+ */
+
+import type { RemotePrompt, RemoteQuestion, RemoteAnswer } from "./types.js";
+
+export interface SlackBlock {
+  type: string;
+  text?: { type: string; text: string };
+  elements?: Array<{ type: string; text: string }>;
+}
+
+export interface DiscordEmbed {
+  title: string;
+  description: string;
+  color: number;
+  fields: Array<{ name: string; value: string; inline?: boolean }>;
+  footer?: { text: string };
+}
+
+const NUMBER_EMOJIS = ["1️⃣", "2️⃣", "3️⃣", "4️⃣", "5️⃣"];
+const MAX_USER_NOTE_LENGTH = 500;
+
+export function formatForSlack(prompt: RemotePrompt): SlackBlock[] {
+  const blocks: SlackBlock[] = [
+    {
+      type: "header",
+      text: { type: "plain_text", text: "GSD needs your input" },
+    },
+  ];
+
+  for (const q of prompt.questions) {
+    blocks.push({
+      type: "section",
+      text: { type: "mrkdwn", text: `*${q.header}*\n${q.question}` },
+    });
+
+    blocks.push({
+      type: "section",
+      text: {
+        type: "mrkdwn",
+        text: q.options.map((opt, i) => `${i + 1}. *${opt.label}* — ${opt.description}`).join("\n"),
+      },
+    });
+
+    blocks.push({
+      type: "context",
+      elements: [{
+        type: "mrkdwn",
+        text: q.allowMultiple
+          ? "Reply in thread with comma-separated numbers (`1,3`) or free text."
+          : "Reply in thread with a number (`1`) or free text.",
+      }],
+    });
+
+    blocks.push({ type: "divider" });
+  }
+
+  return blocks;
+}
+
+export function formatForDiscord(prompt: RemotePrompt): { embeds: DiscordEmbed[]; reactionEmojis: string[] } {
+  const reactionEmojis: string[] = [];
+  const embeds: DiscordEmbed[] = prompt.questions.map((q, questionIndex) => {
+    const supportsReactions = prompt.questions.length === 1;
+    const optionLines = q.options.map((opt, i) => {
+      const emoji = NUMBER_EMOJIS[i] ?? `${i + 1}.`;
+      if (supportsReactions && NUMBER_EMOJIS[i]) reactionEmojis.push(NUMBER_EMOJIS[i]);
+      return `${emoji} **${opt.label}** — ${opt.description}`;
+    });
+
+    const footerText = supportsReactions
+      ? (q.allowMultiple
+          ? "Reply with comma-separated choices (`1,3`) or react with matching numbers"
+          : "Reply with a number or react with the matching number")
+      : `Question ${questionIndex + 1}/${prompt.questions.length} — reply with one line per question or use semicolons`;
+
+    return {
+      title: q.header,
+      description: q.question,
+      color: 0x7c3aed,
+      fields: [{ name: "Options", value: optionLines.join("\n") }],
+      footer: { text: footerText },
+    };
+  });
+
+  return { embeds, reactionEmojis };
+}
+
+export function parseSlackReply(text: string, questions: RemoteQuestion[]): RemoteAnswer {
+  const answers: RemoteAnswer["answers"] = {};
+  const trimmed = text.trim();
+
+  if (questions.length === 1) {
+    answers[questions[0].id] = parseAnswerForQuestion(trimmed, questions[0]);
+    return { answers };
+  }
+
+  const parts = trimmed.includes(";")
+    ? trimmed.split(";").map((s) => s.trim()).filter(Boolean)
+    : trimmed.split("\n").map((s) => s.trim()).filter(Boolean);
+
+  for (let i = 0; i < questions.length; i++) {
+    answers[questions[i].id] = parseAnswerForQuestion(parts[i] ?? "", questions[i]);
+  }
+
+  return { answers };
+}
+
+export function parseDiscordResponse(
+  reactions: Array<{ emoji: string; count: number }>,
+  replyText: string | null,
+  questions: RemoteQuestion[],
+): RemoteAnswer {
+  if (replyText) return parseSlackReply(replyText, questions);
+
+  const answers: RemoteAnswer["answers"] = {};
+  if (questions.length !== 1) {
+    for (const q of questions) {
+      answers[q.id] = { answers: [], user_note: "Discord reactions are only supported for single-question prompts" };
+    }
+    return { answers };
+  }
+
+  const q = questions[0];
+  const picked = reactions
+    .filter((r) => NUMBER_EMOJIS.includes(r.emoji) && r.count > 0)
+    .map((r) => q.options[NUMBER_EMOJIS.indexOf(r.emoji)]?.label)
+    .filter(Boolean) as string[];
+
+  answers[q.id] = picked.length > 0
+    ? { answers: q.allowMultiple ? picked : [picked[0]] }
+    : { answers: [], user_note: "No clear response via reactions" };
+
+  return { answers };
+}
+
+function parseAnswerForQuestion(text: string, q: RemoteQuestion): { answers: string[]; user_note?: string } {
+  if (!text) return { answers: [], user_note: "No response provided" };
+
+  if (/^[\d,\s]+$/.test(text)) {
+    const nums = text
+      .split(",")
+      .map((s) => parseInt(s.trim(), 10))
+      .filter((n) => !Number.isNaN(n) && n >= 1 && n <= q.options.length);
+
+    if (nums.length > 0) {
+      const selected = nums.map((n) => q.options[n - 1].label);
+      return { answers: q.allowMultiple ? selected : [selected[0]] };
+    }
+  }
+
+  const single = parseInt(text, 10);
+  if (!Number.isNaN(single) && single >= 1 && single <= q.options.length) {
+    return { answers: [q.options[single - 1].label] };
+  }
+
+  return { answers: [], user_note: truncateNote(text) };
+}
+
+function truncateNote(text: string): string {
+  return text.length > MAX_USER_NOTE_LENGTH ? text.slice(0, MAX_USER_NOTE_LENGTH) + "…" : text;
+}