paseo-req-kit 1.9.0-beta.1 → 1.9.0-beta.3

package/paseo-plugin/client/live.ts

@@ -0,0 +1,161 @@
+// Buttons that follow Paseo's agents and workspaces (registered outside React):
+//   - a pill on every step agent of a requirement: which requirement, opens it;
+//   - a header button on every workspace that has requirements: how many need a person.
+import type { PluginButtonRegistration, PluginClientContext } from "@getpaseo/plugin/client";
+import { listRpc, type Requirement } from "../shared/contracts";
+import { inWorkspace } from "./panel";
+
+/** The step agents' labels (req-kit's runtime sets them when it starts a step). */
+const PIPELINE_LABEL = "requirement-pipeline";
+
+interface AgentLike {
+  id: string;
+  workspaceId?: string | null;
+  labels?: Record<string, string> | null;
+}
+
+interface WorkspaceLike {
+  id: string;
+  workspaceDirectory?: string;
+  projectRootPath?: string;
+}
+
+export function contributeLive(client: PluginClientContext): () => void {
+  const lifetime = new AbortController();
+  const pills = new Map<string, PluginButtonRegistration>();
+  const headers = new Map<string, PluginButtonRegistration>();
+  const workspaces = new Map<string, WorkspaceLike>();
+  let requirements: Requirement[] = [];
+
+  // ----- pills on step agents
+  const registerAgent = (agent: AgentLike) => {
+    pills.get(agent.id)?.remove();
+    pills.delete(agent.id);
+    const name = agent.labels?.[PIPELINE_LABEL];
+    if (lifetime.signal.aborted || !name || !agent.workspaceId) return;
+    pills.set(
+      agent.id,
+      client.addComposerPill({
+        id: "requirement",
+        workspaceId: agent.workspaceId,
+        agentId: agent.id,
+        button: {
+          title: `打开需求 ${name}`,
+          icon: "ClipboardList",
+          label: "需求",
+          behavior: { kind: "action", onPress: () => client.openScreen({ screenId: "requirement", params: { name } }) },
+        },
+      }),
+    );
+  };
+  void client.paseo.agents
+    .list({ subscribe: {}, signal: lifetime.signal })
+    .then(({ subscription }) => {
+      subscription.subscribe({
+        snapshot: ({ entries }) => {
+          for (const pill of pills.values()) pill.remove();
+          pills.clear();
+          for (const { agent } of entries) registerAgent(agent as AgentLike);
+        },
+        update: (message) => {
+          if (message.type !== "agent_update") return;
+          const update = message.payload;
+          if (update.kind === "remove") {
+            pills.get(update.agentId)?.remove();
+            pills.delete(update.agentId);
+          } else registerAgent(update.agent as AgentLike);
+        },
+      });
+      return undefined;
+    })
+    .catch((error: Error) => {
+      if (!lifetime.signal.aborted) console.error("[req-kit] 读取 agent 列表失败", error);
+    });
+
+  // ----- header buttons on workspaces with requirements
+  const refreshHeaders = () => {
+    for (const [id, ws] of workspaces) {
+      const mine = inWorkspace(requirements, ws.workspaceDirectory ?? ws.projectRootPath, id);
+      const existing = headers.get(id);
+      if (mine.length === 0) {
+        existing?.remove();
+        headers.delete(id);
+        continue;
+      }
+      const waiting = mine.filter((r) => r.attention).length;
+      const label = waiting > 0 ? `需求 · 待处理 ${waiting}` : `需求 ${mine.length}`;
+      if (existing) existing.update({ label });
+      else
+        headers.set(
+          id,
+          client.addHeaderButton({
+            id: "requirements",
+            workspaceId: id,
+            button: {
+              title: "这个工作区的需求",
+              icon: "ClipboardList",
+              label,
+              behavior: { kind: "action", onPress: () => client.openPanel("requirements", { workspaceId: id }) },
+            },
+          }),
+        );
+    }
+    for (const [id, button] of headers) {
+      if (!workspaces.has(id)) {
+        button.remove();
+        headers.delete(id);
+      }
+    }
+  };
+  const poll = async () => {
+    try {
+      requirements = await client.rpc(listRpc, {});
+      refreshHeaders();
+    } catch {
+      // req-kit missing or too old: the overview explains; no header buttons meanwhile.
+    }
+  };
+  let releaseWorkspaces: (() => void) | null = null;
+  void client.paseo.workspaces
+    .list({ subscribe: {} })
+    .then(({ subscription }) => {
+      // The workspace list takes no abort signal: release it here or at cleanup.
+      releaseWorkspaces = () => void subscription.release().catch(() => undefined);
+      if (lifetime.signal.aborted) {
+        releaseWorkspaces();
+        return undefined;
+      }
+      subscription.subscribe({
+        snapshot: ({ entries }) => {
+          workspaces.clear();
+          for (const ws of entries) workspaces.set(ws.id, ws as WorkspaceLike);
+          refreshHeaders();
+        },
+        update: (message) => {
+          if (message.type !== "workspace_update") return;
+          const update = message.payload as { kind: string; workspace?: WorkspaceLike; workspaceId?: string; id?: string };
+          if (update.kind === "upsert" && update.workspace) workspaces.set(update.workspace.id, update.workspace);
+          else {
+            const id = update.workspaceId ?? update.id;
+            if (id) workspaces.delete(id);
+          }
+          refreshHeaders();
+        },
+      });
+      return undefined;
+    })
+    .catch((error: Error) => {
+      if (!lifetime.signal.aborted) console.error("[req-kit] 读取工作区列表失败", error);
+    });
+  void poll();
+  const timer = setInterval(() => void poll(), 30_000);
+
+  return () => {
+    lifetime.abort();
+    releaseWorkspaces?.();
+    clearInterval(timer);
+    for (const b of [...pills.values(), ...headers.values()]) b.remove();
+    pills.clear();
+    headers.clear();
+  };
+}

package/paseo-plugin/client/markdown.tsx

@@ -0,0 +1,219 @@
+// A small Markdown renderer for the requirement documents (spec, design, report…): headings,
+// paragraphs, lists, task lists, tables, code blocks, quotes, rules, and inline bold, code and
+// links. React Native only, colors from the theme, so it reads the same on desktop, web and phones.
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import { ExternalLink } from "@getpaseo/plugin/client/ui";
+import { type ReactNode, useMemo } from "react";
+import { ScrollView, Text, View } from "react-native";
+
+type Theme = PluginHostProps["theme"];
+
+export type Block =
+  | { kind: "heading"; level: number; text: string }
+  | { kind: "paragraph"; text: string }
+  | { kind: "list"; ordered: boolean; items: Array<{ text: string; depth: number; checked: boolean | null }> }
+  | { kind: "code"; text: string }
+  | { kind: "quote"; text: string }
+  | { kind: "table"; header: string[]; rows: string[][] }
+  | { kind: "rule" };
+
+const LIST = /^(\s*)([-*+]|\d+[.)])\s+(\[[ xX]\]\s+)?(.*)$/;
+
+function cells(line: string): string[] {
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .replace(/\\\|/g, "\u0000")
+    .split("|")
+    .map((c) => c.trim().replace(/\u0000/g, "|"));
+}
+
+/** A tab-separated file (decisions.tsv, lessons.tsv) as a Markdown table. */
+export function tsvToMarkdown(tsv: string): string {
+  const rows = tsv.replace(/\r\n?/g, "\n").split("\n").filter((l) => l.trim());
+  if (rows.length === 0) return "";
+  const line = (r: string) => `| ${r.split("\t").map((c) => c.replace(/\|/g, "\\|")).join(" | ")} |`;
+  return [line(rows[0]), `|${rows[0].split("\t").map(() => " --- ").join("|")}|`, ...rows.slice(1).map(line)].join("\n");
+}
+
+/** Splits Markdown into blocks. Anything it does not recognise stays a paragraph. */
+export function parseMarkdown(source: string): Block[] {
+  const lines = source.replace(/\r\n?/g, "\n").split("\n");
+  const blocks: Block[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines.at(i)!;
+    if (!line.trim()) {
+      i++;
+      continue;
+    }
+    const fence = /^\s*(```|~~~)/.exec(line);
+    if (fence) {
+      const body: string[] = [];
+      i++;
+      while (i < lines.length && !lines.at(i)!.trim().startsWith(fence[1])) body.push(lines.at(i++)!);
+      i++;
+      blocks.push({ kind: "code", text: body.join("\n") });
+      continue;
+    }
+    const heading = /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+    if (heading) {
+      blocks.push({ kind: "heading", level: heading[1].length, text: heading[2] });
+      i++;
+      continue;
+    }
+    if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) {
+      blocks.push({ kind: "rule" });
+      i++;
+      continue;
+    }
+    if (line.trim().startsWith("|") && i + 1 < lines.length && /^\s*\|?\s*:?-{2,}/.test(lines.at(i + 1)!)) {
+      const header = cells(line);
+      const rows: string[][] = [];
+      i += 2;
+      while (i < lines.length && lines.at(i)!.trim().startsWith("|")) rows.push(cells(lines.at(i++)!));
+      blocks.push({ kind: "table", header, rows });
+      continue;
+    }
+    if (/^\s*>/.test(line)) {
+      const body: string[] = [];
+      while (i < lines.length && /^\s*>/.test(lines.at(i)!)) body.push(lines.at(i++)!.replace(/^\s*>\s?/, ""));
+      blocks.push({ kind: "quote", text: body.join("\n") });
+      continue;
+    }
+    if (LIST.test(line)) {
+      const ordered = /^\s*\d/.test(line);
+      const items: Array<{ text: string; depth: number; checked: boolean | null }> = [];
+      while (i < lines.length) {
+        const m = LIST.exec(lines.at(i)!);
+        if (m) {
+          items.push({ text: m[4], depth: Math.min(3, Math.floor(m[1].replace(/\t/g, "    ").length / 2)), checked: m[3] ? /x/i.test(m[3]) : null });
+          i++;
+        } else if (lines.at(i)!.trim() && /^\s{2,}/.test(lines.at(i)!) && items.length > 0) {
+          items.at(-1)!.text += ` ${lines.at(i++)!.trim()}`;
+        } else break;
+      }
+      blocks.push({ kind: "list", ordered, items });
+      continue;
+    }
+    const body: string[] = [];
+    while (i < lines.length && lines.at(i)!.trim() && !/^(#{1,6}\s|\s*```|\s*~~~|\s*>|\s*\|)/.test(lines.at(i)!) && !LIST.test(lines.at(i)!)) body.push(lines.at(i++)!.trim());
+    blocks.push({ kind: "paragraph", text: body.join(" ") });
+  }
+  return blocks;
+}
+
+/** Inline **bold**, `code` and [links](https://…). */
+export function inline(text: string, theme: Theme, key = "i"): ReactNode[] {
+  const out: ReactNode[] = [];
+  const pattern = /(\*\*([^*]+)\*\*|`([^`]+)`|\[([^\]]+)\]\(([^)\s]+)\))/g;
+  let last = 0;
+  let n = 0;
+  for (let m = pattern.exec(text); m; m = pattern.exec(text)) {
+    if (m.index > last) out.push(text.slice(last, m.index));
+    if (m[2] !== undefined) {
+      out.push(
+        <Text key={`${key}-${n++}`} style={{ fontWeight: "600" }}>
+          {m[2]}
+        </Text>,
+      );
+    } else if (m[3] !== undefined) {
+      out.push(
+        <Text key={`${key}-${n++}`} style={{ fontFamily: "monospace", backgroundColor: theme.colors.surface2 }}>
+          {m[3]}
+        </Text>,
+      );
+    } else if (m[5] && /^https?:\/\//.test(m[5])) {
+      out.push(
+        <ExternalLink key={`${key}-${n++}`} href={m[5]}>
+          {m[4]}
+        </ExternalLink>,
+      );
+    } else {
+      // A link to another file in the repository: show its text and where it points.
+      out.push(
+        <Text key={`${key}-${n++}`} style={{ color: theme.colors.accent }}>
+          {m[4]}
+        </Text>,
+      );
+    }
+    last = m.index + m[0].length;
+  }
+  if (last < text.length) out.push(text.slice(last));
+  return out;
+}
+
+export function Markdown({ theme, source }: { theme: Theme; source: string }) {
+  const blocks = useMemo(() => parseMarkdown(source), [source]);
+  const text = { color: theme.colors.foreground, fontSize: 14, lineHeight: 21 };
+  const muted = { color: theme.colors.foregroundMuted };
+  return (
+    <View style={{ gap: 10 }}>
+      {blocks.map((b, i) => {
+        switch (b.kind) {
+          case "heading":
+            return (
+              <Text key={i} selectable style={{ ...text, fontWeight: "600", fontSize: b.level === 1 ? 20 : b.level === 2 ? 17 : 15, marginTop: i === 0 ? 0 : 6 }}>
+                {inline(b.text, theme, `h${i}`)}
+              </Text>
+            );
+          case "paragraph":
+            return (
+              <Text key={i} selectable style={text}>
+                {inline(b.text, theme, `p${i}`)}
+              </Text>
+            );
+          case "list":
+            return (
+              <View key={i} style={{ gap: 4 }}>
+                {b.items.map((item, j) => (
+                  <View key={j} style={{ flexDirection: "row", gap: 6, paddingLeft: item.depth * 16 }}>
+                    <Text style={{ ...text, ...muted, minWidth: 16 }}>{item.checked === null ? (b.ordered ? `${j + 1}.` : "•") : item.checked ? "☑" : "☐"}</Text>
+                    <Text selectable style={{ ...text, flex: 1 }}>
+                      {inline(item.text, theme, `l${i}-${j}`)}
+                    </Text>
+                  </View>
+                ))}
+              </View>
+            );
+          case "code":
+            return (
+              <ScrollView key={i} horizontal style={{ backgroundColor: theme.colors.surface2, borderRadius: 8 }}>
+                <Text selectable style={{ ...text, fontFamily: "monospace", fontSize: 13, padding: 10 }}>
+                  {b.text}
+                </Text>
+              </ScrollView>
+            );
+          case "quote":
+            return (
+              <View key={i} style={{ borderLeftWidth: 3, borderLeftColor: theme.colors.border, paddingLeft: 10 }}>
+                <Text selectable style={{ ...text, ...muted }}>
+                  {inline(b.text, theme, `q${i}`)}
+                </Text>
+              </View>
+            );
+          case "rule":
+            return <View key={i} style={{ height: 1, backgroundColor: theme.colors.border }} />;
+          case "table":
+            return (
+              <ScrollView key={i} horizontal>
+                <View style={{ borderColor: theme.colors.border, borderWidth: 1, borderRadius: 6 }}>
+                  {[b.header, ...b.rows].map((row, r) => (
+                    <View key={r} style={{ flexDirection: "row", backgroundColor: r === 0 ? theme.colors.surface1 : undefined, borderTopWidth: r === 0 ? 0 : 1, borderTopColor: theme.colors.border }}>
+                      {b.header.map((_, c) => (
+                        <Text key={c} selectable style={{ ...text, fontSize: 13, fontWeight: r === 0 ? "600" : "400", width: 180, padding: 8 }}>
+                          {inline(row.at(c) ?? "", theme, `t${i}-${r}-${c}`)}
+                        </Text>
+                      ))}
+                    </View>
+                  ))}
+                </View>
+              </ScrollView>
+            );
+        }
+        return null;
+      })}
+    </View>
+  );
+}

package/paseo-plugin/client/overview.tsx

@@ -0,0 +1,89 @@
+// The overview: every requirement on this machine, grouped by what it needs.
+import type { PluginOpenScreenInput, PluginScreenProps } from "@getpaseo/plugin/client";
+import { ScrollView } from "@getpaseo/plugin/client/react-native";
+import { useMemo, useState } from "react";
+import { Text, View } from "react-native";
+import type { Requirement } from "../shared/contracts";
+import { useRequirements } from "./data";
+import { type Group, GROUP_LABELS, groupOf } from "./format";
+import { RequirementRow } from "./row";
+import { Button, Chip, Status, useStyles } from "./ui";
+
+export const ORDER: Group[] = ["attention", "running", "verify", "done", "other"];
+
+/** Opens a requirement's detail screen. */
+export type OpenRequirement = (item: Pick<Requirement, "repo" | "featureDir" | "title">) => void;
+
+export function RequirementGroups({
+  theme,
+  layout,
+  items,
+  open,
+}: Pick<PluginScreenProps, "theme" | "layout"> & { items: Requirement[]; open: OpenRequirement }) {
+  const s = useStyles(theme, layout.compact);
+  const [showOther, setShowOther] = useState(false);
+  const groups = useMemo(() => {
+    const map = new Map<Group, Requirement[]>();
+    for (const item of items) map.set(groupOf(item), [...(map.get(groupOf(item)) ?? []), item]);
+    return map;
+  }, [items]);
+  return (
+    <View style={{ gap: 20 }}>
+      {ORDER.filter((g) => groups.has(g)).map((g) => (
+        <View key={g} style={{ gap: 8 }}>
+          <View style={s.row}>
+            <Text style={s.heading}>
+              {GROUP_LABELS[g]}（{groups.get(g)!.length}）
+            </Text>
+            {g === "other" ? <Button theme={theme} label={showOther ? "收起" : "展开"} onPress={() => setShowOther((v) => !v)} /> : null}
+          </View>
+          {g === "other" && !showOther
+            ? null
+            : groups.get(g)!.map((item) => <RequirementRow key={item.key} theme={theme} layout={layout} item={item} onPress={() => open(item)} />)}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+/** Screens open other screens through the client context; index.client.tsx passes it in. */
+export type ScreenOpener = (input: PluginOpenScreenInput) => void;
+
+export function requirementOpener(openScreen: ScreenOpener): OpenRequirement {
+  return (item) => openScreen({ screenId: "requirement", params: { repo: item.repo, featureDir: item.featureDir, title: item.title } });
+}
+
+export function OverviewScreen(props: PluginScreenProps & { openScreen: ScreenOpener }) {
+  const { theme, layout } = props;
+  const s = useStyles(theme, layout.compact);
+  const query = useRequirements();
+  const [project, setProject] = useState<string | null>(null);
+  const items = query.data ?? [];
+  const projects = useMemo(() => [...new Set(items.map((i) => i.project))].sort(), [items]);
+  const shown = project ? items.filter((i) => i.project === project) : items;
+  const open = requirementOpener(props.openScreen);
+  return (
+    <View style={s.screen}>
+      <ScrollView contentContainerStyle={s.body}>
+        <View style={s.row}>
+          <Button theme={theme} label="使用统计" onPress={() => props.openScreen({ screenId: "stats" })} />
+        </View>
+        {projects.length > 1 ? (
+          <View style={s.row}>
+            <Chip theme={theme} label="全部项目" active={project === null} onPress={() => setProject(null)} />
+            {projects.map((p) => (
+              <Chip key={p} theme={theme} label={p} active={project === p} onPress={() => setProject(p)} />
+            ))}
+          </View>
+        ) : null}
+        <Status
+          theme={theme}
+          loading={query.isPending}
+          error={query.error}
+          empty={query.data && items.length === 0 ? "这台机器上还没有记录任何需求。在 Paseo 对话中用 /req 开始一个；1.9 之前运行过的需求，在项目目录运行 req index --rebuild。" : null}
+        />
+        <RequirementGroups theme={theme} layout={layout} items={shown} open={open} />
+      </ScrollView>
+    </View>
+  );
+}

package/paseo-plugin/client/panel.tsx

@@ -0,0 +1,56 @@
+// The panel beside a workspace: the requirements developed in it or started from it.
+import { type PluginWorkspacePanelProps, useWorkspace } from "@getpaseo/plugin/client";
+import { ScrollView } from "@getpaseo/plugin/client/react-native";
+import { useState } from "react";
+import { Text, View } from "react-native";
+import type { Requirement } from "../shared/contracts";
+import { useRequirements } from "./data";
+import { RequirementView } from "./detail";
+import { RequirementGroups } from "./overview";
+import { Button, Status, useStyles } from "./ui";
+
+/** Same directory, ignoring a trailing separator and (on Windows) case. */
+export function sameDir(a: string | null | undefined, b: string | null | undefined): boolean {
+  if (!a || !b) return false;
+  const norm = (p: string) => p.replace(/[\\/]+$/, "").replace(/\\/g, "/");
+  const x = norm(a);
+  const y = norm(b);
+  return /^[a-z]:\//i.test(x) ? x.toLowerCase() === y.toLowerCase() : x === y;
+}
+
+export function inWorkspace(items: Requirement[], directory: string | null | undefined, workspaceId?: string | null): Requirement[] {
+  return items.filter((r) => (workspaceId && r.workspaceId === workspaceId) || sameDir(r.repo, directory) || sameDir(r.sourceRepo, directory));
+}
+
+export function WorkspacePanel({ theme, layout, navigation, workspaceId }: PluginWorkspacePanelProps) {
+  const s = useStyles(theme, layout.compact);
+  const workspace = useWorkspace(workspaceId, (w) => ({ directory: w.directory, name: w.name }));
+  const query = useRequirements();
+  const [picked, setPicked] = useState<Pick<Requirement, "repo" | "featureDir"> | null>(null);
+  const items = inWorkspace(query.data ?? [], workspace?.directory, workspaceId);
+  const only = items.length === 1 ? items[0] : null;
+  const shown = picked ?? only;
+  return (
+    <View style={s.screen}>
+      <ScrollView contentContainerStyle={s.body}>
+        <Status
+          theme={theme}
+          loading={query.isPending}
+          error={query.error}
+          empty={query.data && items.length === 0 ? `${workspace?.name ?? "这个工作区"}还没有需求。在对话中用 /req 开始一个。` : null}
+        />
+        {shown ? (
+          <>
+            {picked && !only ? <Button theme={theme} label="返回列表" onPress={() => setPicked(null)} /> : null}
+            <RequirementView theme={theme} layout={layout} navigation={navigation} repo={shown.repo} featureDir={shown.featureDir} />
+          </>
+        ) : items.length > 1 ? (
+          <>
+            <Text style={s.muted}>这个工作区有 {items.length} 个需求</Text>
+            <RequirementGroups theme={theme} layout={layout} items={items} open={(item) => setPicked(item)} />
+          </>
+        ) : null}
+      </ScrollView>
+    </View>
+  );
+}

package/paseo-plugin/client/row.tsx

@@ -0,0 +1,40 @@
+// One requirement in a list: title, facts, stage, what is running, what needs a person.
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import { Pressable, Text, View } from "react-native";
+import type { Requirement } from "../shared/contracts";
+import { ago, ATTENTION_LABELS, facts } from "./format";
+import { Badge, useStyles } from "./ui";
+
+export function RequirementRow({
+  theme,
+  layout,
+  item,
+  onPress,
+}: Pick<PluginHostProps, "theme" | "layout"> & { item: Requirement; onPress(): void }) {
+  const s = useStyles(theme, layout.compact);
+  return (
+    <Pressable accessibilityRole="button" accessibilityLabel={item.title} onPress={onPress} style={s.card}>
+      <View style={s.row}>
+        <Text style={[s.text, { fontWeight: "600", flexShrink: 1 }]}>{item.title}</Text>
+        {item.attention ? (
+          <Badge theme={theme} tone={item.attention === "approval" || item.attention === "business" ? "warning" : "danger"}>
+            {ATTENTION_LABELS[item.attention]}
+          </Badge>
+        ) : item.running ? (
+          <Badge theme={theme} tone="accent">
+            运行中
+          </Badge>
+        ) : null}
+        {!item.present ? (
+          <Badge theme={theme} tone="muted">
+            目录已不在
+          </Badge>
+        ) : null}
+      </View>
+      <Text style={s.muted}>{facts(item)}</Text>
+      <Text style={s.text}>{item.stage}</Text>
+      {item.current.length > 0 ? <Text style={s.muted}>正在：{item.current.map((c) => c.title).join("、")}</Text> : null}
+      <Text style={s.muted}>更新于 {ago(item.updatedAt)}</Text>
+    </Pressable>
+  );
+}

package/paseo-plugin/client/settings.tsx

@@ -0,0 +1,90 @@
+// Settings → Plugins → req-kit: what the plugin found, read-only mode, refresh interval.
+import { type PluginSurfaceProps, type SettingsState, useSettings } from "@getpaseo/plugin/client";
+import { SettingsAction, SettingsCard, SettingsInput, SettingsRow, SettingsSection, SettingsSelect, SettingsSwitch } from "@getpaseo/plugin/client/ui";
+import { useState } from "react";
+import { Text } from "react-native";
+import { preferences } from "../shared/contracts";
+import { useKitInfo } from "./data";
+
+type Ready = Extract<SettingsState<typeof preferences.schema>, { status: "ready" }>;
+
+const REFRESH = [
+  { label: "5 秒", value: "5" },
+  { label: "10 秒", value: "10" },
+  { label: "30 秒", value: "30" },
+  { label: "1 分钟", value: "60" },
+];
+
+function Controls({ settings, theme }: { settings: Ready; theme: PluginSurfaceProps["theme"] }) {
+  const [kitHome, setKitHome] = useState(settings.values.kitHome);
+  const info = useKitInfo();
+  return (
+    <>
+      <SettingsSection title="req-kit">
+        <SettingsCard>
+          {info.data ? (
+            <>
+              <SettingsRow label="版本" hint={info.data.kitRoot}>
+                <Text style={{ color: theme.colors.foreground }}>{info.data.kitVersion}</Text>
+              </SettingsRow>
+              <SettingsRow label="支持的 Paseo" hint={`本机配置目录：${info.data.kitHome}`}>
+                <Text style={{ color: theme.colors.foreground }}>{info.data.paseo ?? "-"}</Text>
+              </SettingsRow>
+            </>
+          ) : (
+            <SettingsRow label="状态" error={info.error?.message ?? undefined} hint={info.isPending ? "正在读取…" : undefined} />
+          )}
+          <SettingsInput
+            label="req-kit 的本机配置目录"
+            hint="通常不用填：默认是运行 Paseo 的用户的 ~/.req-kit。设置了 REQ_KIT_HOME 时填那个目录。"
+            initialValue={settings.values.kitHome}
+            placeholder="~/.req-kit"
+            onChangeText={setKitHome}
+            disabled={settings.saving}
+            error={settings.saveError ?? undefined}
+          />
+          <SettingsAction
+            label="保存配置目录"
+            actionLabel="保存"
+            disabled={settings.saving || kitHome === settings.values.kitHome}
+            onPress={() => void settings.save({ ...settings.values, kitHome: kitHome.trim() }, settings.revision).then(() => info.refetch())}
+          />
+        </SettingsCard>
+      </SettingsSection>
+      <SettingsSection title="显示与操作">
+        <SettingsCard>
+          <SettingsSwitch
+            label="只读"
+            hint="只显示需求和文档，不提供确认方案、停止、继续、开始测试验证。能连上这台 daemon 的人都能看到这个插件。"
+            value={settings.values.readOnly}
+            disabled={settings.saving}
+            onValueChange={(readOnly) => void settings.save({ ...settings.values, readOnly }, settings.revision)}
+          />
+          <SettingsSelect
+            label="刷新间隔"
+            value={String(settings.values.refreshSeconds)}
+            options={REFRESH}
+            disabled={settings.saving}
+            onValueChange={(v) => void settings.save({ ...settings.values, refreshSeconds: Number(v) }, settings.revision)}
+          />
+        </SettingsCard>
+      </SettingsSection>
+    </>
+  );
+}
+
+export function SettingsScreen({ theme }: PluginSurfaceProps) {
+  const settings = useSettings(preferences);
+  if (settings.status === "loading") return <Text style={{ color: theme.colors.foregroundMuted }}>正在读取…</Text>;
+  if (settings.status !== "ready") {
+    return (
+      <SettingsSection title="设置">
+        <SettingsCard>
+          <SettingsRow label="设置读取失败" error={settings.error} />
+          <SettingsAction label="恢复默认设置" actionLabel="恢复" onPress={() => void settings.reset()} />
+        </SettingsCard>
+      </SettingsSection>
+    );
+  }
+  return <Controls settings={settings} theme={theme} />;
+}