@every-env/compound-plugin 0.5.2 → 0.8.0

package/src/converters/{claude-to-cursor.ts → claude-to-copilot.ts}

@@ -1,43 +1,63 @@
 import { formatFrontmatter } from "../utils/frontmatter"
 import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
-import type { CursorBundle, CursorCommand, CursorMcpServer, CursorRule } from "../types/cursor"
+import type {
+  CopilotAgent,
+  CopilotBundle,
+  CopilotGeneratedSkill,
+  CopilotMcpServer,
+} from "../types/copilot"
 import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
 
-export type ClaudeToCursorOptions = ClaudeToOpenCodeOptions
+export type ClaudeToCopilotOptions = ClaudeToOpenCodeOptions
 
-export function convertClaudeToCursor(
+const COPILOT_BODY_CHAR_LIMIT = 30_000
+
+export function convertClaudeToCopilot(
   plugin: ClaudePlugin,
-  _options: ClaudeToCursorOptions,
-): CursorBundle {
-  const usedRuleNames = new Set<string>()
-  const usedCommandNames = new Set<string>()
+  _options: ClaudeToCopilotOptions,
+): CopilotBundle {
+  const usedAgentNames = new Set<string>()
+  const usedSkillNames = new Set<string>()
+
+  const agents = plugin.agents.map((agent) => convertAgent(agent, usedAgentNames))
+
+  // Reserve skill names first so generated skills (from commands) don't collide
+  const skillDirs = plugin.skills.map((skill) => {
+    usedSkillNames.add(skill.name)
+    return {
+      name: skill.name,
+      sourceDir: skill.sourceDir,
+    }
+  })
 
-  const rules = plugin.agents.map((agent) => convertAgentToRule(agent, usedRuleNames))
-  const commands = plugin.commands.map((command) => convertCommand(command, usedCommandNames))
-  const skillDirs = plugin.skills.map((skill) => ({
-    name: skill.name,
-    sourceDir: skill.sourceDir,
-  }))
+  const generatedSkills = plugin.commands.map((command) =>
+    convertCommandToSkill(command, usedSkillNames),
+  )
 
-  const mcpServers = convertMcpServers(plugin.mcpServers)
+  const mcpConfig = convertMcpServers(plugin.mcpServers)
 
   if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
-    console.warn("Warning: Cursor does not support hooks. Hooks were skipped during conversion.")
+    console.warn("Warning: Copilot does not support hooks. Hooks were skipped during conversion.")
   }
 
-  return { rules, commands, skillDirs, mcpServers }
+  return { agents, generatedSkills, skillDirs, mcpConfig }
 }
 
-function convertAgentToRule(agent: ClaudeAgent, usedNames: Set<string>): CursorRule {
+function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): CopilotAgent {
   const name = uniqueName(normalizeName(agent.name), usedNames)
   const description = agent.description ?? `Converted from Claude agent ${agent.name}`
 
   const frontmatter: Record<string, unknown> = {
     description,
-    alwaysApply: false,
+    tools: ["*"],
+    infer: true,
   }
 
-  let body = transformContentForCursor(agent.body.trim())
+  if (agent.model) {
+    frontmatter.model = agent.model
+  }
+
+  let body = transformContentForCopilot(agent.body.trim())
   if (agent.capabilities && agent.capabilities.length > 0) {
     const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
     body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
@@ -46,39 +66,44 @@ function convertAgentToRule(agent: ClaudeAgent, usedNames: Set<string>): CursorR
     body = `Instructions converted from the ${agent.name} agent.`
   }
 
+  if (body.length > COPILOT_BODY_CHAR_LIMIT) {
+    console.warn(
+      `Warning: Agent "${agent.name}" body exceeds ${COPILOT_BODY_CHAR_LIMIT} characters (${body.length}). Copilot may truncate it.`,
+    )
+  }
+
   const content = formatFrontmatter(frontmatter, body)
   return { name, content }
 }
 
-function convertCommand(command: ClaudeCommand, usedNames: Set<string>): CursorCommand {
+function convertCommandToSkill(
+  command: ClaudeCommand,
+  usedNames: Set<string>,
+): CopilotGeneratedSkill {
   const name = uniqueName(flattenCommandName(command.name), usedNames)
 
-  const sections: string[] = []
-
+  const frontmatter: Record<string, unknown> = {
+    name,
+  }
   if (command.description) {
-    sections.push(`<!-- ${command.description} -->`)
+    frontmatter.description = command.description
   }
 
+  const sections: string[] = []
+
   if (command.argumentHint) {
     sections.push(`## Arguments\n${command.argumentHint}`)
   }
 
-  const transformedBody = transformContentForCursor(command.body.trim())
+  const transformedBody = transformContentForCopilot(command.body.trim())
   sections.push(transformedBody)
 
-  const content = sections.filter(Boolean).join("\n\n").trim()
+  const body = sections.filter(Boolean).join("\n\n").trim()
+  const content = formatFrontmatter(frontmatter, body)
   return { name, content }
 }
 
-/**
- * Transform Claude Code content to Cursor-compatible content.
- *
- * 1. Task agent calls: Task agent-name(args) -> Use the agent-name skill to: args
- * 2. Slash commands: /workflows:plan -> /plan (flatten namespace)
- * 3. Path rewriting: .claude/ -> .cursor/
- * 4. Agent references: @agent-name -> the agent-name rule
- */
-export function transformContentForCursor(body: string): string {
+export function transformContentForCopilot(body: string): string {
   let result = body
 
   // 1. Transform Task agent calls
@@ -88,24 +113,25 @@ export function transformContentForCursor(body: string): string {
     return `${prefix}Use the ${skillName} skill to: ${args.trim()}`
   })
 
-  // 2. Transform slash command references (flatten namespaces)
+  // 2. Transform slash command references (replace colons with hyphens)
   const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
   result = result.replace(slashCommandPattern, (match, commandName: string) => {
     if (commandName.includes("/")) return match
     if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) return match
-    const flattened = flattenCommandName(commandName)
-    return `/${flattened}`
+    const normalized = flattenCommandName(commandName)
+    return `/${normalized}`
   })
 
-  // 3. Rewrite .claude/ paths to .cursor/
+  // 3. Rewrite .claude/ paths to .github/ and ~/.claude/ to ~/.copilot/
   result = result
-    .replace(/~\/\.claude\//g, "~/.cursor/")
-    .replace(/\.claude\//g, ".cursor/")
+    .replace(/~\/\.claude\//g, "~/.copilot/")
+    .replace(/\.claude\//g, ".github/")
 
   // 4. Transform @agent-name references
-  const agentRefPattern = /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi
+  const agentRefPattern =
+    /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi
   result = result.replace(agentRefPattern, (_match, agentName: string) => {
-    return `the ${normalizeName(agentName)} rule`
+    return `the ${normalizeName(agentName)} agent`
   })
 
   return result
@@ -113,29 +139,47 @@ export function transformContentForCursor(body: string): string {
 
 function convertMcpServers(
   servers?: Record<string, ClaudeMcpServer>,
-): Record<string, CursorMcpServer> | undefined {
+): Record<string, CopilotMcpServer> | undefined {
   if (!servers || Object.keys(servers).length === 0) return undefined
 
-  const result: Record<string, CursorMcpServer> = {}
+  const result: Record<string, CopilotMcpServer> = {}
   for (const [name, server] of Object.entries(servers)) {
-    const entry: CursorMcpServer = {}
+    const entry: CopilotMcpServer = {
+      type: server.command ? "local" : "sse",
+      tools: ["*"],
+    }
+
     if (server.command) {
       entry.command = server.command
       if (server.args && server.args.length > 0) entry.args = server.args
-      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
     } else if (server.url) {
       entry.url = server.url
       if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
     }
+
+    if (server.env && Object.keys(server.env).length > 0) {
+      entry.env = prefixEnvVars(server.env)
+    }
+
     result[name] = entry
   }
   return result
 }
 
+function prefixEnvVars(env: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith("COPILOT_MCP_")) {
+      result[key] = value
+    } else {
+      result[`COPILOT_MCP_${key}`] = value
+    }
+  }
+  return result
+}
+
 function flattenCommandName(name: string): string {
-  const colonIndex = name.lastIndexOf(":")
-  const base = colonIndex >= 0 ? name.slice(colonIndex + 1) : name
-  return normalizeName(base)
+  return normalizeName(name)
 }
 
 function normalizeName(value: string): string {

package/src/converters/claude-to-gemini.ts

@@ -0,0 +1,193 @@
+import { formatFrontmatter } from "../utils/frontmatter"
+import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
+import type { GeminiBundle, GeminiCommand, GeminiMcpServer, GeminiSkill } from "../types/gemini"
+import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
+
+export type ClaudeToGeminiOptions = ClaudeToOpenCodeOptions
+
+const GEMINI_DESCRIPTION_MAX_LENGTH = 1024
+
+export function convertClaudeToGemini(
+  plugin: ClaudePlugin,
+  _options: ClaudeToGeminiOptions,
+): GeminiBundle {
+  const usedSkillNames = new Set<string>()
+  const usedCommandNames = new Set<string>()
+
+  const skillDirs = plugin.skills.map((skill) => ({
+    name: skill.name,
+    sourceDir: skill.sourceDir,
+  }))
+
+  // Reserve skill names from pass-through skills
+  for (const skill of skillDirs) {
+    usedSkillNames.add(normalizeName(skill.name))
+  }
+
+  const generatedSkills = plugin.agents.map((agent) => convertAgentToSkill(agent, usedSkillNames))
+
+  const commands = plugin.commands.map((command) => convertCommand(command, usedCommandNames))
+
+  const mcpServers = convertMcpServers(plugin.mcpServers)
+
+  if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
+    console.warn("Warning: Gemini CLI hooks use a different format (BeforeTool/AfterTool with matchers). Hooks were skipped during conversion.")
+  }
+
+  return { generatedSkills, skillDirs, commands, mcpServers }
+}
+
+function convertAgentToSkill(agent: ClaudeAgent, usedNames: Set<string>): GeminiSkill {
+  const name = uniqueName(normalizeName(agent.name), usedNames)
+  const description = sanitizeDescription(
+    agent.description ?? `Use this skill for ${agent.name} tasks`,
+  )
+
+  const frontmatter: Record<string, unknown> = { name, description }
+
+  let body = transformContentForGemini(agent.body.trim())
+  if (agent.capabilities && agent.capabilities.length > 0) {
+    const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
+    body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
+  }
+  if (body.length === 0) {
+    body = `Instructions converted from the ${agent.name} agent.`
+  }
+
+  const content = formatFrontmatter(frontmatter, body)
+  return { name, content }
+}
+
+function convertCommand(command: ClaudeCommand, usedNames: Set<string>): GeminiCommand {
+  // Preserve namespace structure: workflows:plan -> workflows/plan
+  const commandPath = resolveCommandPath(command.name)
+  const pathKey = commandPath.join("/")
+  uniqueName(pathKey, usedNames) // Track for dedup
+
+  const description = command.description ?? `Converted from Claude command ${command.name}`
+  const transformedBody = transformContentForGemini(command.body.trim())
+
+  let prompt = transformedBody
+  if (command.argumentHint) {
+    prompt += `\n\nUser request: {{args}}`
+  }
+
+  const content = toToml(description, prompt)
+  return { name: pathKey, content }
+}
+
+/**
+ * Transform Claude Code content to Gemini-compatible content.
+ *
+ * 1. Task agent calls: Task agent-name(args) -> Use the agent-name skill to: args
+ * 2. Path rewriting: .claude/ -> .gemini/, ~/.claude/ -> ~/.gemini/
+ * 3. Agent references: @agent-name -> the agent-name skill
+ */
+export function transformContentForGemini(body: string): string {
+  let result = body
+
+  // 1. Transform Task agent calls
+  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
+  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
+    const skillName = normalizeName(agentName)
+    return `${prefix}Use the ${skillName} skill to: ${args.trim()}`
+  })
+
+  // 2. Rewrite .claude/ paths to .gemini/
+  result = result
+    .replace(/~\/\.claude\//g, "~/.gemini/")
+    .replace(/\.claude\//g, ".gemini/")
+
+  // 3. Transform @agent-name references
+  const agentRefPattern = /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi
+  result = result.replace(agentRefPattern, (_match, agentName: string) => {
+    return `the ${normalizeName(agentName)} skill`
+  })
+
+  return result
+}
+
+function convertMcpServers(
+  servers?: Record<string, ClaudeMcpServer>,
+): Record<string, GeminiMcpServer> | undefined {
+  if (!servers || Object.keys(servers).length === 0) return undefined
+
+  const result: Record<string, GeminiMcpServer> = {}
+  for (const [name, server] of Object.entries(servers)) {
+    const entry: GeminiMcpServer = {}
+    if (server.command) {
+      entry.command = server.command
+      if (server.args && server.args.length > 0) entry.args = server.args
+      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
+    } else if (server.url) {
+      entry.url = server.url
+      if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
+    }
+    result[name] = entry
+  }
+  return result
+}
+
+/**
+ * Resolve command name to path segments.
+ * workflows:plan -> ["workflows", "plan"]
+ * plan -> ["plan"]
+ */
+function resolveCommandPath(name: string): string[] {
+  return name.split(":").map((segment) => normalizeName(segment))
+}
+
+/**
+ * Serialize to TOML command format.
+ * Uses multi-line strings (""") for prompt field.
+ */
+export function toToml(description: string, prompt: string): string {
+  const lines: string[] = []
+  lines.push(`description = ${formatTomlString(description)}`)
+
+  // Use multi-line string for prompt
+  const escapedPrompt = prompt.replace(/\\/g, "\\\\").replace(/"""/g, '\\"\\"\\"')
+  lines.push(`prompt = """`)
+  lines.push(escapedPrompt)
+  lines.push(`"""`)
+
+  return lines.join("\n")
+}
+
+function formatTomlString(value: string): string {
+  return JSON.stringify(value)
+}
+
+function normalizeName(value: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) return "item"
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[\\/]+/g, "-")
+    .replace(/[:\s]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+  return normalized || "item"
+}
+
+function sanitizeDescription(value: string, maxLength = GEMINI_DESCRIPTION_MAX_LENGTH): string {
+  const normalized = value.replace(/\s+/g, " ").trim()
+  if (normalized.length <= maxLength) return normalized
+  const ellipsis = "..."
+  return normalized.slice(0, Math.max(0, maxLength - ellipsis.length)).trimEnd() + ellipsis
+}
+
+function uniqueName(base: string, used: Set<string>): string {
+  if (!used.has(base)) {
+    used.add(base)
+    return base
+  }
+  let index = 2
+  while (used.has(`${base}-${index}`)) {
+    index += 1
+  }
+  const name = `${base}-${index}`
+  used.add(name)
+  return name
+}

package/src/converters/claude-to-opencode.ts

@@ -250,8 +250,24 @@ function rewriteClaudePaths(body: string): string {
     .replace(/\.claude\//g, ".opencode/")
 }
 
+// Bare Claude family aliases used in Claude Code (e.g. `model: haiku`).
+// Update these when new model generations are released.
+const CLAUDE_FAMILY_ALIASES: Record<string, string> = {
+  haiku: "claude-haiku-4-5",
+  sonnet: "claude-sonnet-4-5",
+  opus: "claude-opus-4-6",
+}
+
 function normalizeModel(model: string): string {
   if (model.includes("/")) return model
+  if (CLAUDE_FAMILY_ALIASES[model]) {
+    const resolved = `anthropic/${CLAUDE_FAMILY_ALIASES[model]}`
+    console.warn(
+      `Warning: bare model alias "${model}" mapped to "${resolved}". ` +
+        `Update CLAUDE_FAMILY_ALIASES if a newer version is available.`,
+    )
+    return resolved
+  }
   if (/^claude-/.test(model)) return `anthropic/${model}`
   if (/^(gpt-|o1-|o3-)/.test(model)) return `openai/${model}`
   if (/^gemini-/.test(model)) return `google/${model}`

package/src/converters/claude-to-pi.ts

@@ -0,0 +1,205 @@
+import { formatFrontmatter } from "../utils/frontmatter"
+import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
+import type {
+  PiBundle,
+  PiGeneratedSkill,
+  PiMcporterConfig,
+  PiMcporterServer,
+} from "../types/pi"
+import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
+import { PI_COMPAT_EXTENSION_SOURCE } from "../templates/pi/compat-extension"
+
+export type ClaudeToPiOptions = ClaudeToOpenCodeOptions
+
+const PI_DESCRIPTION_MAX_LENGTH = 1024
+
+export function convertClaudeToPi(
+  plugin: ClaudePlugin,
+  _options: ClaudeToPiOptions,
+): PiBundle {
+  const promptNames = new Set<string>()
+  const usedSkillNames = new Set<string>(plugin.skills.map((skill) => normalizeName(skill.name)))
+
+  const prompts = plugin.commands
+    .filter((command) => !command.disableModelInvocation)
+    .map((command) => convertPrompt(command, promptNames))
+
+  const generatedSkills = plugin.agents.map((agent) => convertAgent(agent, usedSkillNames))
+
+  const extensions = [
+    {
+      name: "compound-engineering-compat.ts",
+      content: PI_COMPAT_EXTENSION_SOURCE,
+    },
+  ]
+
+  return {
+    prompts,
+    skillDirs: plugin.skills.map((skill) => ({
+      name: skill.name,
+      sourceDir: skill.sourceDir,
+    })),
+    generatedSkills,
+    extensions,
+    mcporterConfig: plugin.mcpServers ? convertMcpToMcporter(plugin.mcpServers) : undefined,
+  }
+}
+
+function convertPrompt(command: ClaudeCommand, usedNames: Set<string>) {
+  const name = uniqueName(normalizeName(command.name), usedNames)
+  const frontmatter: Record<string, unknown> = {
+    description: command.description,
+    "argument-hint": command.argumentHint,
+  }
+
+  let body = transformContentForPi(command.body)
+  body = appendCompatibilityNoteIfNeeded(body)
+
+  return {
+    name,
+    content: formatFrontmatter(frontmatter, body.trim()),
+  }
+}
+
+function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): PiGeneratedSkill {
+  const name = uniqueName(normalizeName(agent.name), usedNames)
+  const description = sanitizeDescription(
+    agent.description ?? `Converted from Claude agent ${agent.name}`,
+  )
+
+  const frontmatter: Record<string, unknown> = {
+    name,
+    description,
+  }
+
+  const sections: string[] = []
+  if (agent.capabilities && agent.capabilities.length > 0) {
+    sections.push(`## Capabilities\n${agent.capabilities.map((capability) => `- ${capability}`).join("\n")}`)
+  }
+
+  const body = [
+    ...sections,
+    agent.body.trim().length > 0
+      ? agent.body.trim()
+      : `Instructions converted from the ${agent.name} agent.`,
+  ].join("\n\n")
+
+  return {
+    name,
+    content: formatFrontmatter(frontmatter, body),
+  }
+}
+
+function transformContentForPi(body: string): string {
+  let result = body
+
+  // Task repo-research-analyst(feature_description)
+  // -> Run subagent with agent="repo-research-analyst" and task="feature_description"
+  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
+  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
+    const skillName = normalizeName(agentName)
+    const trimmedArgs = args.trim().replace(/\s+/g, " ")
+    return `${prefix}Run subagent with agent=\"${skillName}\" and task=\"${trimmedArgs}\".`
+  })
+
+  // Claude-specific tool references
+  result = result.replace(/\bAskUserQuestion\b/g, "ask_user_question")
+  result = result.replace(/\bTodoWrite\b/g, "file-based todos (todos/ + /skill:file-todos)")
+  result = result.replace(/\bTodoRead\b/g, "file-based todos (todos/ + /skill:file-todos)")
+
+  // /command-name or /workflows:command-name -> /workflows-command-name
+  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
+  result = result.replace(slashCommandPattern, (match, commandName: string) => {
+    if (commandName.includes("/")) return match
+    if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) {
+      return match
+    }
+
+    if (commandName.startsWith("skill:")) {
+      const skillName = commandName.slice("skill:".length)
+      return `/skill:${normalizeName(skillName)}`
+    }
+
+    const withoutPrefix = commandName.startsWith("prompts:")
+      ? commandName.slice("prompts:".length)
+      : commandName
+
+    return `/${normalizeName(withoutPrefix)}`
+  })
+
+  return result
+}
+
+function appendCompatibilityNoteIfNeeded(body: string): string {
+  if (!/\bmcp\b/i.test(body)) return body
+
+  const note = [
+    "",
+    "## Pi + MCPorter note",
+    "For MCP access in Pi, use MCPorter via the generated tools:",
+    "- `mcporter_list` to inspect available MCP tools",
+    "- `mcporter_call` to invoke a tool",
+    "",
+  ].join("\n")
+
+  return body + note
+}
+
+function convertMcpToMcporter(servers: Record<string, ClaudeMcpServer>): PiMcporterConfig {
+  const mcpServers: Record<string, PiMcporterServer> = {}
+
+  for (const [name, server] of Object.entries(servers)) {
+    if (server.command) {
+      mcpServers[name] = {
+        command: server.command,
+        args: server.args,
+        env: server.env,
+        headers: server.headers,
+      }
+      continue
+    }
+
+    if (server.url) {
+      mcpServers[name] = {
+        baseUrl: server.url,
+        headers: server.headers,
+      }
+    }
+  }
+
+  return { mcpServers }
+}
+
+function normalizeName(value: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) return "item"
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[\\/]+/g, "-")
+    .replace(/[:\s]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+  return normalized || "item"
+}
+
+function sanitizeDescription(value: string, maxLength = PI_DESCRIPTION_MAX_LENGTH): string {
+  const normalized = value.replace(/\s+/g, " ").trim()
+  if (normalized.length <= maxLength) return normalized
+  const ellipsis = "..."
+  return normalized.slice(0, Math.max(0, maxLength - ellipsis.length)).trimEnd() + ellipsis
+}
+
+function uniqueName(base: string, used: Set<string>): string {
+  if (!used.has(base)) {
+    used.add(base)
+    return base
+  }
+  let index = 2
+  while (used.has(`${base}-${index}`)) {
+    index += 1
+  }
+  const name = `${base}-${index}`
+  used.add(name)
+  return name
+}