cctra 0.3.0

package/src/commands/ls.ts

@@ -0,0 +1,49 @@
+// ============================================================================
+// cctra ls：列出所有 source
+// ============================================================================
+import { Command } from "commander";
+import { withConfig } from "./shared";
+import { green, dim, bold } from "../ui/format";
+import { info } from "../ui/format";
+
+export function registerLs(program: Command): void {
+  program
+    .command("ls")
+    .alias("list")
+    .description("List all subscriptions and plugins")
+    .action(() => {
+      withConfig((config) => {
+        const subs = Object.values(config.subscriptions);
+        const plugins = Object.values(config.plugins);
+
+        if (subs.length === 0 && plugins.length === 0) {
+          info("No subscriptions or plugins yet. Run `cctra add` to start.");
+          return;
+        }
+
+        if (subs.length > 0) {
+          console.log(bold("Subscriptions:"));
+          for (const [i, sub] of subs.entries()) {
+            const marker = green("*");
+            const index = dim(`${i + 1}.`);
+            const name = green(sub.name);
+            const vendorPart = sub.vendor ? ` ${dim(`[${sub.vendor}]`)}` : "";
+            const meta = ` ${dim(`(${sub.apiFormat}, ${sub.models.length} model${sub.models.length === 1 ? "" : "s"})`)}`;
+            console.log(`${marker} ${index} ${name}${vendorPart}${meta}`);
+          }
+        }
+
+        if (plugins.length > 0) {
+          if (subs.length > 0) console.log("");
+          console.log(bold("Plugins:"));
+          for (const [i, p] of plugins.entries()) {
+            const marker = p.enabled ? green("*") : " ";
+            const index = dim(`${i + 1}.`);
+            const name = p.enabled ? p.name : dim(p.name);
+            const meta = ` ${dim(`(${p.enabled ? "enabled" : "disabled"}, ${p.models.length} model${p.models.length === 1 ? "" : "s"})`)}`;
+            console.log(`${marker} ${index} ${name}${meta}`);
+          }
+        }
+      });
+    });
+}

package/src/commands/model.ts

@@ -0,0 +1,95 @@
+// ============================================================================
+// cctra model <subcommand>：管理订阅的模型
+// add / ls / rm / rename
+// ============================================================================
+import { Command } from "commander";
+import * as p from "@clack/prompts";
+import { withConfig } from "./shared";
+import { checkCancel } from "../ui/prompts";
+import { success, error as errorOut } from "../ui/format";
+
+export function registerModel(program: Command): void {
+  const model = program.command("model").description("Manage models in a subscription");
+
+  // cctra model add <sub>
+  model
+    .command("add <sub>")
+    .description("Add a model to a subscription")
+    .action(async (sub: string) => {
+      try {
+        const id = checkCancel(await p.text({ message: "Model ID (upstream):", validate: (v) => !v?.trim() ? "Required" : undefined }));
+        const aliasRaw = checkCancel(await p.text({ message: "Alias (optional):", defaultValue: "" }));
+        const alias = aliasRaw.trim() || undefined;
+        withConfig((config) => {
+          if (!config.subscriptions[sub]) throw new Error(`Subscription "${sub}" not found.`);
+          const s = config.subscriptions[sub]!;
+          if (s.models.find((m) => m.id === id)) throw new Error(`Model "${id}" already exists.`);
+          s.models.push({ id, alias });
+          s.updatedAt = Date.now();
+        });
+        success(`Added model "${id}".`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // cctra model ls <sub>
+  model
+    .command("ls <sub>")
+    .description("List models in a subscription")
+    .action((sub: string) => {
+      withConfig((config) => {
+        if (!config.subscriptions[sub]) {
+          errorOut(`Subscription "${sub}" not found.`);
+          return;
+        }
+        for (const m of config.subscriptions[sub]!.models) {
+          const alias = m.alias ? ` (alias: ${m.alias})` : "";
+          console.log(`- ${m.id}${alias}`);
+        }
+      });
+    });
+
+  // cctra model rm <sub> <id-or-alias>
+  model
+    .command("rm <sub> <model>")
+    .description("Remove a model from a subscription")
+    .action((sub: string, model: string) => {
+      try {
+        withConfig((config) => {
+          if (!config.subscriptions[sub]) throw new Error(`Subscription "${sub}" not found.`);
+          const s = config.subscriptions[sub]!;
+          const idx = s.models.findIndex((m) => m.id === model || m.alias === model);
+          if (idx < 0) throw new Error(`Model "${model}" not found.`);
+          s.models.splice(idx, 1);
+          s.updatedAt = Date.now();
+        });
+        success(`Removed model "${model}".`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // cctra model rename <sub> <model> <new-alias>
+  model
+    .command("rename <sub> <model> <newAlias>")
+    .description("Set/change alias of a model")
+    .action((sub: string, model: string, newAlias: string) => {
+      try {
+        withConfig((config) => {
+          if (!config.subscriptions[sub]) throw new Error(`Subscription "${sub}" not found.`);
+          const s = config.subscriptions[sub]!;
+          const m = s.models.find((m) => m.id === model || m.alias === model);
+          if (!m) throw new Error(`Model "${model}" not found.`);
+          m.alias = newAlias.trim() || undefined;
+          s.updatedAt = Date.now();
+        });
+        success(`Updated alias.`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/plugin.ts

@@ -0,0 +1,167 @@
+// ============================================================================
+// cctra plugin <subcommand>：管理插件
+// add / ls / show / enable / disable / rm
+// ============================================================================
+import { Command } from "commander";
+import * as p from "@clack/prompts";
+import { existsSync, statSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { withConfig } from "./shared";
+import { checkCancel } from "../ui/prompts";
+import { success, error as errorOut, warn, info, dim } from "../ui/format";
+import { addPlugin, updatePlugin, removePlugin } from "../core/config";
+import { loadPlugin, clearPluginCache } from "../plugin/loader";
+import type { PluginConfig } from "../types";
+
+export function registerPlugin(program: Command): void {
+  const plugin = program.command("plugin").description("Manage local-path plugins");
+
+  // cctra plugin add <name> <path>
+  plugin
+    .command("add <name> <path>")
+    .description("Add a local-path plugin")
+    .action(async (name: string, path: string) => {
+      try {
+        // 验证文件存在
+        if (!existsSync(path)) {
+          errorOut(`File not found: ${path}`);
+          return;
+        }
+
+        // 计算 sha256
+        const content = readFileSync(path);
+        const sha256 = createHash("sha256").update(content).digest("hex");
+        const sizeKB = (statSync(path).size / 1024).toFixed(1);
+
+        // 警告 + 确认
+        warn("Plugin is arbitrary JavaScript. Loading gives it full process permissions.");
+        console.log(`  ${dim("Path:")}     ${path}`);
+        console.log(`  ${dim("Size:")}     ${sizeKB} KB`);
+        console.log(`  ${dim("SHA-256:")}  ${sha256}`);
+        const ok = checkCancel(
+          await p.confirm({ message: "Continue?", initialValue: false }),
+        );
+        if (!ok) return;
+
+        // 配置（这里先用空对象，v1 不做交互式 schema 推断）
+        const configRaw = checkCancel(
+          await p.text({ message: "Plugin config (JSON, optional):", defaultValue: "{}", validate: (v) => {
+            if (!v) return undefined;
+            try { JSON.parse(v); return undefined; } catch { return "Invalid JSON"; }
+          }}),
+        );
+        const config = JSON.parse(configRaw) as Record<string, unknown>;
+
+        // 尝试 import 一下确认合法
+        const tempPlugin: PluginConfig = {
+          kind: "plugin",
+          name,
+          path,
+          config,
+          enabled: true,
+          models: [],
+        };
+        const instance = await loadPlugin(tempPlugin, withConfig((c) => c));
+        if (!instance) {
+          errorOut(`Plugin failed to load. Check the file's syntax.`);
+          return;
+        }
+        // 拉模型列表
+        let models: { id: string; alias?: string }[] = [];
+        if (instance.listModels) {
+          try {
+            const { makePluginContext } = await import("../plugin/host");
+            const ctx = makePluginContext(name, config);
+            models = (await instance.listModels(ctx)).map((m) => ({ id: m.id, alias: m.alias }));
+          } catch (e) {
+            warn(`listModels() failed: ${(e as Error).message}`);
+          }
+        }
+        tempPlugin.models = models;
+
+        withConfig((c) => {
+          if (c.plugins[name]) updatePlugin(c, tempPlugin);
+          else addPlugin(c, tempPlugin);
+        });
+        success(`Added plugin "${name}" with ${models.length} model(s).`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // cctra plugin ls
+  plugin
+    .command("ls")
+    .description("List installed plugins")
+    .action(() => {
+      withConfig((config) => {
+        const plugins = Object.values(config.plugins);
+        if (plugins.length === 0) {
+          info("No plugins installed. Try `cctra plugin add <name> <path>`.");
+          return;
+        }
+        for (const p of plugins) {
+          const status = p.enabled ? "✓ enabled" : "✗ disabled";
+          console.log(`- ${p.name}  ${dim(`(${p.models.length} model${p.models.length === 1 ? "" : "s"}, ${status})`)}`);
+          console.log(`    ${dim("path:")} ${p.path}`);
+        }
+      });
+    });
+
+  // cctra plugin show <name>
+  plugin
+    .command("show <name>")
+    .description("Show plugin details")
+    .action((name: string) => {
+      withConfig((config) => {
+        const p = config.plugins[name];
+        if (!p) { errorOut(`Plugin "${name}" not found.`); return; }
+        console.log(`${p.name}  ${dim(`(${p.enabled ? "enabled" : "disabled"})`)}`);
+        console.log(`  ${dim("path:")}    ${p.path}`);
+        console.log(`  ${dim("config:")}  ${JSON.stringify(p.config)}`);
+        console.log(`  ${dim("models:")}`);
+        for (const m of p.models) {
+          const alias = m.alias ? ` (alias: ${m.alias})` : "";
+          console.log(`    - ${m.id}${alias}`);
+        }
+      });
+    });
+
+  // cctra plugin enable / disable <name>
+  plugin
+    .command("enable <name>")
+    .description("Enable a plugin")
+    .action((name: string) => {
+      withConfig((config) => {
+        if (!config.plugins[name]) throw new Error(`Plugin "${name}" not found.`);
+        config.plugins[name]!.enabled = true;
+      });
+      clearPluginCache();
+      success(`Enabled "${name}".`);
+    });
+
+  plugin
+    .command("disable <name>")
+    .description("Disable a plugin")
+    .action((name: string) => {
+      withConfig((config) => {
+        if (!config.plugins[name]) throw new Error(`Plugin "${name}" not found.`);
+        config.plugins[name]!.enabled = false;
+      });
+      clearPluginCache();
+      success(`Disabled "${name}".`);
+    });
+
+  // cctra plugin rm <name>
+  plugin
+    .command("rm <name>")
+    .description("Remove a plugin (does not delete the .js file)")
+    .action((name: string) => {
+      withConfig((config) => {
+        if (!config.plugins[name]) throw new Error(`Plugin "${name}" not found.`);
+        removePlugin(config, name);
+      });
+      success(`Removed plugin "${name}".`);
+    });
+}

package/src/commands/rename.ts

@@ -0,0 +1,33 @@
+// ============================================================================
+// cctra rename <old> <new>：重命名订阅
+// ============================================================================
+import { Command } from "commander";
+import { withConfig } from "./shared";
+import { success, error as errorOut } from "../ui/format";
+
+export function registerRename(program: Command): void {
+  program
+    .command("rename <old> <new>")
+    .description("Rename a subscription")
+    .action((oldName: string, newName: string) => {
+      try {
+        withConfig((config) => {
+          const normalized = newName.trim().toLowerCase();
+          if (!/^[a-z0-9][a-z0-9-]*$/.test(normalized)) {
+            throw new Error('New name must be kebab-case: lowercase letters, digits, hyphens.');
+          }
+          if (!config.subscriptions[oldName]) throw new Error(`Subscription "${oldName}" not found.`);
+          if (config.subscriptions[normalized]) throw new Error(`"${normalized}" already exists.`);
+          const sub = config.subscriptions[oldName]!;
+          sub.name = normalized;
+          sub.updatedAt = Date.now();
+          config.subscriptions[normalized] = sub;
+          delete config.subscriptions[oldName];
+        });
+        success(`Renamed to "${newName}".`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/rm.ts

@@ -0,0 +1,37 @@
+// ============================================================================
+// cctra rm <name>：删除订阅或插件
+// ============================================================================
+import { Command } from "commander";
+import * as p from "@clack/prompts";
+import { withConfig } from "./shared";
+import { removeSubscription, removePlugin } from "../core/config";
+import { checkCancel } from "../ui/prompts";
+import { success, error as errorOut } from "../ui/format";
+
+export function registerRm(program: Command): void {
+  program
+    .command("rm <name>")
+    .alias("remove")
+    .description("Remove a subscription or plugin")
+    .action(async (name: string) => {
+      try {
+        const ok = checkCancel(
+          await p.confirm({
+            message: `Delete "${name}"?`,
+            initialValue: false,
+          }),
+        );
+        if (!ok) return;
+
+        withConfig((config) => {
+          if (config.subscriptions[name]) removeSubscription(config, name);
+          else if (config.plugins[name]) removePlugin(config, name);
+          else throw new Error(`Not found: "${name}"`);
+        });
+        success(`Removed "${name}".`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/serve.ts

@@ -0,0 +1,29 @@
+// ============================================================================
+// cctra serve [--port N]：前台跑 HTTP server
+// ============================================================================
+import { Command } from "commander";
+import { startServer } from "../server/serve";
+
+export function registerServe(program: Command): void {
+  program
+    .command("serve")
+    .description("Run the HTTP server in the foreground")
+    .option("-p, --port <port>", "Override port (default from config)")
+    .action(async (opts: { port?: string }) => {
+      const port = opts.port ? parseInt(opts.port, 10) : undefined;
+      // 启动信息由 server/serve.ts 里的 logger.info 负责（写 stderr + daemon.log），
+      // 不要再 console.log 一行 —— 终端会看到重复
+      const handle = startServer(port);
+      // 不退出
+      process.on("SIGINT", () => {
+        handle.stop();
+        process.exit(0);
+      });
+      process.on("SIGTERM", () => {
+        handle.stop();
+        process.exit(0);
+      });
+      // 永久 hang
+      await new Promise(() => {});
+    });
+}

package/src/commands/shared.ts

@@ -0,0 +1,14 @@
+// ============================================================================
+// 共享工具：读/写 config 的 helper
+// ============================================================================
+import { loadConfigFile, saveConfigFile } from "../core/config";
+import { ensureCctraDir } from "../utils/paths";
+import type { Config } from "../types";
+
+export function withConfig<T>(fn: (config: Config) => T): T {
+  ensureCctraDir();
+  const config = loadConfigFile();
+  const result = fn(config);
+  saveConfigFile(config);
+  return result;
+}

package/src/commands/show.ts

@@ -0,0 +1,46 @@
+// ============================================================================
+// cctra show <name>：显示订阅/插件详情
+// ============================================================================
+import { Command } from "commander";
+import { withConfig } from "./shared";
+import { maskToken } from "../ui/prompts";
+import { bold, dim, info } from "../ui/format";
+import { getSource, isSubscription, isPlugin } from "../core/source";
+
+export function registerShow(program: Command): void {
+  program
+    .command("show <name>")
+    .description("Show details of a subscription or plugin")
+    .action((name: string) => {
+      withConfig((config) => {
+        const s = getSource(config, name);
+        if (!s) {
+          info(`Not found: "${name}"`);
+          return;
+        }
+
+        console.log(bold(`${s.name}`) + `  ${dim(`(${s.kind})`)}`);
+        if (isSubscription(s)) {
+          if (s.vendor) {
+            console.log(`  ${dim("vendor:")}    ${s.vendor}`);
+          }
+          console.log(`  ${dim("endpoint:")}  ${s.endpoint}`);
+          console.log(`  ${dim("token:")}     ${maskToken(s.token)}`);
+          console.log(`  ${dim("format:")}    ${s.apiFormat}`);
+        } else if (isPlugin(s)) {
+          console.log(`  ${dim("path:")}      ${s.path}`);
+          console.log(`  ${dim("enabled:")}   ${s.enabled}`);
+          console.log(`  ${dim("config:")}    ${JSON.stringify(s.config)}`);
+        }
+        console.log(`  ${dim("models:")}`);
+        if (s.models.length === 0) {
+          console.log(`    ${dim("(none)")}`);
+        } else {
+          for (const m of s.models) {
+            const alias = m.alias ? ` ${dim(`(alias: ${m.alias})`)}` : "";
+            console.log(`    - ${m.id}${alias}`);
+          }
+        }
+      });
+    });
+}

package/src/commands/tier.ts

@@ -0,0 +1,91 @@
+// ============================================================================
+// cctra tier <subcommand>：管理 tier 映射
+// set / ls / show / rm
+// ============================================================================
+import { Command } from "commander";
+import { withConfig } from "./shared";
+import { success, error as errorOut, info, dim, bold } from "../ui/format";
+import { setTier, removeTier } from "../core/config";
+import { BUILTIN_TIERS } from "../types";
+
+export function registerTier(program: Command): void {
+  const tier = program.command("tier").description("Manage tier model mappings");
+
+  // cctra tier set <name> <target>
+  tier
+    .command("set <name> <target>")
+    .description("Set/update a tier mapping (e.g. `cctra tier set cctra-pro my-sub/model-x`)")
+    .action((name: string, target: string) => {
+      try {
+        withConfig((config) => {
+          setTier(config, { name, target, description: config.tiers[name]?.description });
+        });
+        success(`Mapped ${name} → ${target}.`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // cctra tier ls
+  tier
+    .command("ls")
+    .description("List all tier mappings")
+    .action(() => {
+      withConfig((config) => {
+        const all = Object.values(config.tiers);
+        const builtinSet = new Set<string>(BUILTIN_TIERS);
+        const builtin = all.filter((t) => builtinSet.has(t.name));
+        const custom = all.filter((t) => !builtinSet.has(t.name));
+
+        console.log(bold("Built-in tiers:"));
+        for (const t of builtin) {
+          const target = t.target || dim("(not mapped)");
+          console.log(`  ${t.name.padEnd(15)} → ${target}  ${dim(t.description ?? "")}`);
+        }
+
+        if (custom.length > 0) {
+          console.log("");
+          console.log(bold("Custom tiers:"));
+          for (const t of custom) {
+            const target = t.target || dim("(not mapped)");
+            console.log(`  ${t.name.padEnd(15)} → ${target}  ${dim(t.description ?? "")}`);
+          }
+        }
+
+        if (builtin.length + custom.length === 0) {
+          info("No tiers configured.");
+        }
+      });
+    });
+
+  // cctra tier show <name>
+  tier
+    .command("show <name>")
+    .description("Show a tier's current target")
+    .action((name: string) => {
+      withConfig((config) => {
+        const t = config.tiers[name];
+        if (!t) { errorOut(`Tier "${name}" not found.`); return; }
+        const target = t.target || dim("(not mapped)");
+        console.log(`${name} → ${target}`);
+        if (t.description) console.log(dim(t.description));
+      });
+    });
+
+  // cctra tier rm <name>
+  tier
+    .command("rm <name>")
+    .description("Unmap a tier (built-ins keep the name, just clear target)")
+    .action((name: string) => {
+      try {
+        withConfig((config) => {
+          removeTier(config, name);
+        });
+        success(`Unmapped ${name}.`);
+      } catch (e) {
+        errorOut((e as Error).message);
+        process.exit(1);
+      }
+    });
+}

package/src/convert/common/content-blocks.ts

@@ -0,0 +1,29 @@
+import type { CanonicalContentBlock } from "../../canonical/types";
+
+// ============================================================================
+// Content Block 工具函数
+// ============================================================================
+
+/** 把字符串或 block 数组统一成 block 数组（便于遍历） */
+export function ensureBlocks(content: string | CanonicalContentBlock[]): CanonicalContentBlock[] {
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  return content;
+}
+
+/** 提取所有文本块（用于 Anthropic 风格的 system prompt 简化） */
+export function extractText(blocks: CanonicalContentBlock[]): string {
+  return blocks
+    .filter((b): b is { type: "text"; text: string } => b.type === "text")
+    .map((b) => b.text)
+    .join("");
+}
+
+/** 判断 block 是否是 tool_use */
+export function isToolUse(b: CanonicalContentBlock): b is { type: "tool_use"; id: string; name: string; input: unknown } {
+  return b.type === "tool_use";
+}
+
+/** 判断 block 是否是 tool_result */
+export function isToolResult(b: CanonicalContentBlock): b is { type: "tool_result"; toolUseId: string; content: string | CanonicalContentBlock[]; isError?: boolean } {
+  return b.type === "tool_result";
+}

package/src/convert/common/extras.ts

@@ -0,0 +1,38 @@
+// ============================================================================
+// Per-protocol extras helpers
+// 在 inbound 时把已知字段剥离，剩余未识别字段塞进对应协议桶
+// 在 outbound 时按目标协议把桶 spread 回对象
+// ============================================================================
+import type { ProtocolExtras } from "../../canonical/types";
+
+/** 把 obj 中 knownKeys 之外的字段剥出来，组成对应协议的 extras 桶 */
+export function splitKnownAndExtras<T extends Record<string, unknown>>(
+  obj: T,
+  knownKeys: ReadonlySet<keyof T>,
+  protocol: keyof ProtocolExtras,
+): { known: T; extras: ProtocolExtras } {
+  const known = {} as T;
+  const extrasBag: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (knownKeys.has(k as keyof T)) {
+      (known as Record<string, unknown>)[k] = v;
+    } else {
+      extrasBag[k] = v;
+    }
+  }
+  const extras: ProtocolExtras = {};
+  if (Object.keys(extrasBag).length > 0) {
+    extras[protocol] = extrasBag;
+  }
+  return { known, extras };
+}
+
+/** 把 extras 中目标协议桶的字段 spread 进 target；防御性：target 已知字段优先 */
+export function mergeExtras<T extends Record<string, unknown>>(
+  target: T,
+  extras: ProtocolExtras | undefined,
+  protocol: keyof ProtocolExtras,
+): T {
+  if (!extras?.[protocol]) return target;
+  return { ...target, ...extras[protocol] } as T;
+}

package/src/convert/common/reasoning.ts

@@ -0,0 +1,19 @@
+import type { CanonicalContentBlock } from "../../canonical/types";
+
+// 处理 reasoning/thinking 块的辅助
+// Anthropic 的 thinking block 有 signature，cc-switch 的 thinking_rectifier 模式下
+// 我们只在 signature 存在时回传，避免浪费 token
+
+export function stripThinkingContent(blocks: CanonicalContentBlock[]): CanonicalContentBlock[] {
+  return blocks.map((b) => {
+    if (b.type === "thinking") {
+      // 只保留 signature（如果有），去掉 thinking 内容
+      return { type: "thinking", thinking: "", signature: b.signature };
+    }
+    return b;
+  });
+}
+
+export function hasThinkingSignature(blocks: CanonicalContentBlock[]): boolean {
+  return blocks.some((b) => b.type === "thinking" && b.signature);
+}

package/src/convert/common/system-prompt.ts

@@ -0,0 +1,15 @@
+import type { CanonicalRequest, CanonicalContentBlock } from "../../canonical/types";
+import { ensureBlocks, extractText } from "./content-blocks";
+
+/** 把 Canonical 顶级 system 转成字符串（用于 OpenAI Chat 的 messages[0].role=system） */
+export function systemToString(system: CanonicalRequest["system"]): string | undefined {
+  if (system === undefined) return undefined;
+  if (typeof system === "string") return system;
+  return extractText(ensureBlocks(system));
+}
+
+/** 把字符串 system 转成 Canonical 顶级 system（block 形式） */
+export function stringToSystem(s: string | undefined): CanonicalContentBlock[] | undefined {
+  if (!s) return undefined;
+  return [{ type: "text", text: s }];
+}