@yannelli/paseo-linear-plugin 1.0.0 → 1.1.0-alpha.0

package/shared/agent-tools.ts

@@ -0,0 +1,157 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { IDENTIFIER } from "./agent-hooks";
+import type { IssueDetail } from "./linear";
+
+// The plugin's MCP server for agents started from an issue. It gives them Linear tools for
+// their issue tree and a way to start Paseo agents on its sub-issues. The daemon hosts it on
+// 127.0.0.1, and each agent gets its own bearer token.
+
+export const TOOLS_SERVER = "linear";
+/** Children get only the Linear tools, so agents never start agents of their own. */
+export const LINEAR_TOOLS = ["read_issue", "edit_issue"] as const;
+export const AGENT_TOOLS = ["start_agent", "wait_agent"] as const;
+
+export const McpHttpServerSchema = z.object({
+  type: z.literal("http"),
+  url: z.string().min(1),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+export const ToolPolicySchema = z.object({
+  preapproved: z.array(z.object({ kind: z.literal("mcp"), server: z.string(), tool: z.string() })),
+});
+
+/** The config of an agent that start_agent starts. */
+export const AgentConfigSchema = z.object({
+  provider: z.string().min(1),
+  thinkingOptionId: z.string().optional(),
+  modeId: z.string().optional(),
+});
+export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+
+/** The agent the user chose for a sub-issue, and its name for prompts and replies. */
+export const AssignmentSchema = z.object({ config: AgentConfigSchema, label: z.string() });
+export type Assignment = z.infer<typeof AssignmentSchema>;
+
+export const ToolScopeSchema = z.object({
+  /** The issue the launch started from. The tools reach it and its sub-issues. */
+  root: z.string().regex(IDENTIFIER),
+  /** The issue this agent works on, the default for read_issue and edit_issue. */
+  home: z.string().regex(IDENTIFIER),
+  /** The Paseo project whose Linear key loaded the issue. */
+  keyScope: z.string().nullable(),
+  workspaceId: z.string().min(1),
+  /** The Paseo project the agent runs in. Its settings turn the tools on and off. */
+  projectId: z.string().nullable().optional(),
+  /** The agent config that started agents copy. */
+  config: AgentConfigSchema,
+  /** Agents the user chose for sub-issues, by issue key. start_agent uses them. */
+  assignments: z.record(z.string(), AssignmentSchema).optional(),
+});
+export type ToolScope = z.infer<typeof ToolScopeSchema>;
+
+export const agentToolsRpc = defineRpc({
+  name: "linear.agent.tools",
+  input: ToolScopeSchema,
+  output: z.object({
+    /** Goes in the agent's labels, so a tool call can find the agent that made it. */
+    grantId: z.string(),
+    server: McpHttpServerSchema,
+    toolPolicy: ToolPolicySchema,
+  }),
+});
+
+export function toolPolicy(tools: readonly string[]): z.infer<typeof ToolPolicySchema> {
+  return { preapproved: tools.map((tool) => ({ kind: "mcp" as const, server: TOOLS_SERVER, tool })) };
+}
+
+const IssueKey = z.string().regex(IDENTIFIER);
+
+export const ReadIssueInput = z.object({
+  issue: IssueKey.optional().describe("Issue key, such as ENG-12. The default is the issue you work on."),
+});
+
+export const EditIssueInput = z.object({
+  issue: IssueKey.optional().describe("Issue key, such as ENG-12. The default is the issue you work on."),
+  old_text: z
+    .string()
+    .describe("Exact text of the description to replace. It must occur one time. Use an empty string to add new_text at the end."),
+  new_text: z.string().describe("The text that replaces old_text."),
+});
+
+export const StartAgentInput = z.object({
+  issue: IssueKey.describe("Key of the sub-issue the agent works on."),
+  title: z.string().min(1).max(120).describe("Short title. Start it with the issue key."),
+  prompt: z.string().min(1).describe("The full task. The agent does not see your conversation."),
+  thinking: z
+    .string()
+    .optional()
+    .describe("Thinking option of the agent's model, such as low, medium, or high. The default is yours."),
+});
+
+export const WaitAgentInput = z.object({
+  agent_id: z.string().min(1),
+  timeout_seconds: z.number().int().min(1).max(600).default(50),
+});
+
+/** Replaces the one place where old text occurs. Empty old text adds the new text at the end. */
+export function editText(body: string, oldText: string, newText: string): { body: string } | { error: string } {
+  if (oldText === "") return { body: body.trimEnd() ? `${body.trimEnd()}\n\n${newText}` : newText };
+  const first = body.indexOf(oldText);
+  if (first < 0) return { error: "old_text is not in the description. Read the issue again, because it can change." };
+  if (body.indexOf(oldText, first + 1) >= 0) {
+    return { error: "old_text occurs more than one time. Add nearby lines so that it occurs one time." };
+  }
+  return { body: body.slice(0, first) + newText + body.slice(first + oldText.length) };
+}
+
+/** Counts Markdown task list items, so a reply can say how many are done. */
+export function taskCount(body: string): { done: number; total: number } {
+  const items = [...body.matchAll(/^\s*[-*+] \[([ xX])\]/gm)];
+  return { done: items.filter((item) => item[1] !== " ").length, total: items.length };
+}
+
+/** The issue as text for read_issue. */
+export function issueText(issue: IssueDetail): string {
+  const tasks = taskCount(issue.description ?? "");
+  const lines = [
+    `${issue.identifier}: ${issue.title}`,
+    `Status: ${issue.state.name}`,
+    `URL: ${issue.url}`,
+    tasks.total > 0 ? `Task list: ${tasks.done} of ${tasks.total} checked` : null,
+    "",
+    "Description:",
+    issue.description?.trim() || "(empty)",
+  ];
+  if (issue.children.length > 0) {
+    lines.push("", "Sub-issues:");
+    for (const child of issue.children) lines.push(`- ${child.identifier} [${child.state.name}]: ${child.title}`);
+  }
+  return lines.filter((line) => line !== null).join("\n");
+}
+
+/** Opens the prompt of an agent that start_agent makes. */
+export function childBrief(key: string, root: string, edits = true): string {
+  const parent = key.toUpperCase() === root.toUpperCase() ? "" : `, a sub-issue of ${root}`;
+  const lines = [`You work on Linear issue ${key}${parent}. Start your first reply with "${key}:".`];
+  if (edits) {
+    lines.push(
+      `Use the ${TOOLS_SERVER} MCP tools: read_issue shows the issue, and edit_issue changes its description.`,
+      "Check off each task list item you finish by replacing `- [ ]` with `- [x]`. Do not post comments.",
+    );
+  } else {
+    lines.push(`Use the ${TOOLS_SERVER} MCP tool read_issue to read the issue. Do not change the issue or post comments.`);
+  }
+  return lines.join("\n");
+}
+
+/** The assignment for a sub-issue key, in any letter case. */
+export function assignmentFor(assignments: ToolScope["assignments"], key: string): Assignment | null {
+  if (!assignments) return null;
+  const wanted = key.toUpperCase();
+  for (const [entry, assignment] of Object.entries(assignments)) {
+    if (entry.toUpperCase() === wanted) return assignment;
+  }
+  return null;
+}

package/shared/custom-icon.ts

@@ -0,0 +1,188 @@
+import { z } from "zod";
+
+// The user's own plugin icon. The web app draws it as an image, which never runs scripts or
+// loads files; the checks below also refuse such content. Paint recolors every visible pixel,
+// and Solid fills shapes that only have an outline.
+
+export const ICON_PAINTS = ["original", "theme", "accent", "linear", "custom"] as const;
+export type IconPaint = (typeof ICON_PAINTS)[number];
+
+/** Linear's brand indigo, the plugin's own color. */
+export const LINEAR_INDIGO = "#5E6AD2";
+export const MAX_SVG_LENGTH = 64_000;
+export const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+/** Paseo draws panel tabs, the new tab menu, and Command Center with Lucide names only. */
+export const BUILT_IN_ICON = "SquareKanban";
+export const MENU_ICONS: readonly { name: string; label: string }[] = [
+  { name: BUILT_IN_ICON, label: "Board (default)" },
+  ...[
+    ["Kanban", "Kanban"],
+    ["LayoutGrid", "Grid"],
+    ["ListTodo", "To-do list"],
+    ["ClipboardList", "Clipboard"],
+    ["CircleDot", "Circle dot"],
+    ["Target", "Target"],
+    ["Zap", "Lightning"],
+    ["Rocket", "Rocket"],
+    ["Star", "Star"],
+    ["Hexagon", "Hexagon"],
+    ["Triangle", "Triangle"],
+    ["Diamond", "Diamond"],
+    ["Box", "Box"],
+    ["Layers", "Layers"],
+    ["Compass", "Compass"],
+    ["Flag", "Flag"],
+    ["Bookmark", "Bookmark"],
+    ["Ticket", "Ticket"],
+    ["Bug", "Bug"],
+    ["Sparkles", "Sparkles"],
+    ["Bot", "Bot"],
+    ["Gem", "Gem"],
+    ["Flame", "Flame"],
+    ["Shapes", "Shapes"],
+    ["Orbit", "Orbit"],
+    ["Workflow", "Workflow"],
+    ["Puzzle", "Puzzle"],
+    ["Atom", "Atom"],
+    ["Command", "Command"],
+  ].map(([name = "", label = ""]) => ({ name, label })),
+];
+const LUCIDE_NAME = /^[A-Z][A-Za-z0-9]*$/;
+
+export const IconSettingsSchema = z.object({
+  /** Checked SVG markup. Empty uses the built-in icon. */
+  svg: z.string().max(MAX_SVG_LENGTH).default(""),
+  paint: z.enum(ICON_PAINTS).default("original"),
+  /** The color of the custom paint. */
+  color: z.string().regex(HEX_COLOR).default(LINEAR_INDIGO),
+  /** Fill shapes that only have an outline. */
+  solid: z.boolean().default(false),
+  /** The Lucide icon for panel tabs, the new tab menu, and Command Center. */
+  menu: z.string().regex(LUCIDE_NAME).default(BUILT_IN_ICON),
+});
+export type IconSettings = z.infer<typeof IconSettingsSchema>;
+
+const BLOCKED: readonly (readonly [RegExp, string])[] = [
+  [/<!DOCTYPE|<!ENTITY/i, "The SVG has a DOCTYPE or entities. Export it again without them."],
+  [/<script[\s>/]/i, "The SVG has a script. Use an SVG with shapes only."],
+  [/<foreignObject[\s>/]/i, "The SVG has HTML content. Use an SVG with shapes only."],
+  [/<[^>]*\son[a-z]+\s*=/i, "The SVG has event handlers. Use an SVG with shapes only."],
+  [/[\s:]href\s*=\s*["']\s*(?!#)/i, "The SVG links to other files or images. Use an SVG that has all its shapes inside."],
+  [/url\(\s*["']?\s*(?!#)/i, "The SVG uses files outside it. Use an SVG that has all its shapes inside."],
+  [/@import/i, "The SVG imports styles from another file."],
+];
+
+const ROOT_TAG = /^<svg\b[^>]*>/i;
+const NUMBER = String.raw`(-?[\d.]+(?:e[-+]?\d+)?)`;
+const VIEW_BOX = new RegExp(String.raw`\sviewBox\s*=\s*["']\s*${NUMBER}[\s,]+${NUMBER}[\s,]+${NUMBER}[\s,]+${NUMBER}\s*["']`, "i");
+
+const attribute = (tag: string, name: string) =>
+  new RegExp(String.raw`\s${name}\s*=\s*["']([^"']*)["']`, "i").exec(tag)?.[1]?.trim() ?? null;
+const withoutAttribute = (tag: string, name: string) =>
+  tag.replace(new RegExp(String.raw`\s${name}\s*=\s*(?:"[^"]*"|'[^']*')`, "gi"), "");
+
+/** The root's viewBox as x, y, width, and height, or null without a usable one. */
+export function viewBoxOf(svg: string): [number, number, number, number] | null {
+  const root = ROOT_TAG.exec(svg)?.[0] ?? "";
+  const box = VIEW_BOX.exec(root)?.slice(1, 5).map(Number);
+  if (!box || box.some((value) => !Number.isFinite(value))) return null;
+  const [x = 0, y = 0, width = 0, height = 0] = box;
+  return width > 0 && height > 0 ? [x, y, width, height] : null;
+}
+
+/** Checks pasted or uploaded SVG and returns it ready to save, or why it cannot be used. */
+export function parseIconSvg(text: string): { svg: string } | { error: string } {
+  const svg = text
+    .replace(/^\uFEFF/, "")
+    .replace(/<\?[\s\S]*?\?>/g, "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .trim();
+  if (!svg) return { error: "Paste SVG markup or choose an SVG file." };
+  if (svg.length > MAX_SVG_LENGTH) {
+    return { error: `The SVG is too large. Use one under ${Math.round(MAX_SVG_LENGTH / 1000)} KB.` };
+  }
+  if (!/^<svg[\s>]/i.test(svg) || !/<\/svg>$/i.test(svg)) {
+    return { error: "This is not an SVG. It must start with <svg and end with </svg>." };
+  }
+  for (const [pattern, error] of BLOCKED) if (pattern.test(svg)) return { error };
+  const root = ROOT_TAG.exec(svg)?.[0] ?? "";
+  let next = root;
+  if (!viewBoxOf(svg)) {
+    const width = Number(/^([\d.]+)(?:px)?$/.exec(attribute(root, "width") ?? "")?.[1]);
+    const height = Number(/^([\d.]+)(?:px)?$/.exec(attribute(root, "height") ?? "")?.[1]);
+    if (!(width > 0 && height > 0)) return { error: "The SVG needs a viewBox, or a width and height in pixels." };
+    next = withoutAttribute(next, "viewBox").replace(/^<svg/i, `<svg viewBox="0 0 ${width} ${height}"`);
+  }
+  // The image scales to its box from the viewBox, so a fixed size would only crop it.
+  next = withoutAttribute(withoutAttribute(next, "width"), "height");
+  if (!/\sxmlns\s*=/.test(next)) next = next.replace(/^<svg/i, '<svg xmlns="http://www.w3.org/2000/svg"');
+  return { svg: next + svg.slice(root.length) };
+}
+
+/** Keeps a color inside an attribute value; anything else becomes gray. */
+export function safeColor(color: string): string {
+  return /^[#a-z0-9(),.%\s-]+$/i.test(color) ? color.trim() : "#888888";
+}
+
+const FILL_NONE = /(?<![\w-])(fill\s*:\s*)none\b/gi;
+
+/** Fills shapes that only have an outline, with their stroke color or the icon color. */
+export function fillOutlines(svg: string): string {
+  const tags = svg.replace(/<([a-z][\w:.-]*)(\s[^>]*?)?(\/?)>/gi, (tag, name: string, attrs: string | undefined, close: string) => {
+    if (!attrs) return tag;
+    const stroke = attribute(attrs, "stroke") ?? /(?<![\w-])stroke\s*:\s*([^;"']+)/i.exec(attrs)?.[1]?.trim();
+    const fill = stroke && stroke !== "none" ? stroke : "currentColor";
+    const next = attrs.replace(/(\sfill\s*=\s*["'])\s*none\s*(["'])/gi, `$1${fill}$2`).replace(FILL_NONE, `$1${fill}`);
+    return `<${name}${next}${close}>`;
+  });
+  return tags.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi, (_all, open: string, css: string, end: string) =>
+    `${open}${css.replace(FILL_NONE, "$1currentColor")}${end}`,
+  );
+}
+
+const TINT_ID = "paseo-linear-tint";
+
+/** Paints every visible pixel one color and keeps its transparency. */
+export function tint(svg: string, color: string): string {
+  const [x, y, width, height] = viewBoxOf(svg) ?? [0, 0, 24, 24];
+  const filter =
+    `<filter id="${TINT_ID}" filterUnits="userSpaceOnUse" x="${x - width}" y="${y - height}" width="${width * 3}" height="${height * 3}" color-interpolation-filters="sRGB">` +
+    `<feFlood flood-color="${safeColor(color)}"/><feComposite in2="SourceAlpha" operator="in"/></filter>`;
+  return svg
+    .replace(ROOT_TAG, (root) => `${root}<defs>${filter}</defs><g filter="url(#${TINT_ID})">`)
+    .replace(/<\/svg>$/i, "</g></svg>");
+}
+
+export interface IconLook {
+  /** The color `currentColor` takes: the color Paseo gives the icon. */
+  ink: string;
+  /** One color for the whole icon, or null to keep its colors. */
+  paint: string | null;
+  solid: boolean;
+}
+
+/** The SVG to draw for saved markup, or null when it no longer passes the checks. */
+export function iconMarkup(saved: string, look: IconLook): string | null {
+  const parsed = parseIconSvg(saved);
+  if ("error" in parsed) return null;
+  const filled = look.solid ? fillOutlines(parsed.svg) : parsed.svg;
+  const inked = filled.replace(/currentColor/gi, safeColor(look.ink));
+  return look.paint ? tint(inked, look.paint) : inked;
+}
+
+/** The one color a paint gives, or null for the icon's own colors. */
+export function paintColor(icon: IconSettings, colors: { ink: string; accent: string }): string | null {
+  switch (icon.paint) {
+    case "original":
+      return null;
+    case "theme":
+      return colors.ink;
+    case "accent":
+      return colors.accent;
+    case "linear":
+      return LINEAR_INDIGO;
+    case "custom":
+      return icon.color;
+  }
+}

package/shared/knowledge.ts

@@ -0,0 +1,255 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+// Project knowledge: what the daemon learns about a project's files without an agent. It is
+// kept on disk, so explore and setup prompts, ticket-text maps, and Linear Live can use it.
+
+export const AREA_KINDS = ["service", "package", "folder"] as const;
+export type AreaKind = (typeof AREA_KINDS)[number];
+
+export const AreaSchema = z.object({
+  /** Folder with a trailing slash; "" is the repository root. */
+  path: z.string(),
+  name: z.string(),
+  kind: z.enum(AREA_KINDS),
+  /** What the folder holds, from its name, such as "backend" or "tests"; "" when unknown. */
+  role: z.string(),
+  /** Files that define it, such as package.json or Dockerfile. */
+  manifests: z.array(z.string()),
+  /** Files under the folder, at any depth. */
+  files: z.number(),
+  languages: z.array(z.string()),
+  /** One line from the setup agent; "" until it writes one. */
+  summary: z.string(),
+});
+export type Area = z.infer<typeof AreaSchema>;
+
+/** The part of an area the app needs to label files. */
+export const AreaRefSchema = AreaSchema.pick({
+  path: true,
+  name: true,
+  kind: true,
+  role: true,
+  summary: true,
+});
+export type AreaRef = z.infer<typeof AreaRefSchema>;
+
+const CountSchema = z.object({ name: z.string(), files: z.number() });
+
+export const ProjectKnowledgeSchema = z.object({
+  projectId: z.string(),
+  rootPath: z.string(),
+  inspectedAt: z.string(),
+  source: z.enum(["git", "walk"]),
+  /** Repo-relative file paths, sorted, at most MAX_KNOWLEDGE_FILES. */
+  files: z.array(z.string()),
+  fileCount: z.number(),
+  truncated: z.boolean(),
+  areas: z.array(AreaSchema),
+  languages: z.array(CountSchema),
+  /** Files that guide agents and contributors, such as AGENTS.md and CI workflows. */
+  guides: z.array(z.string()),
+  /** Commands the repository defines, such as "npm run check". */
+  commands: z.array(z.string()),
+  /** One line from the setup agent about the project; "" until it writes one. */
+  summary: z.string(),
+  summarizedAt: z.string().nullable(),
+});
+export type ProjectKnowledge = z.infer<typeof ProjectKnowledgeSchema>;
+
+/** What the app gets: everything but the file list, plus file counts per top folder. */
+export const ProjectBriefSchema = ProjectKnowledgeSchema.omit({ files: true }).extend({
+  folders: z.array(CountSchema),
+});
+export type ProjectBrief = z.infer<typeof ProjectBriefSchema>;
+
+export const MAX_KNOWLEDGE_FILES = 20_000;
+export const MAX_RESOLVE_PATHS = 200;
+
+/** Saved knowledge of a project; the daemon inspects the project first when it has none. */
+export const knowledgeGetRpc = defineRpc({
+  name: "linear.knowledge.get",
+  input: z.object({ projectId: z.string().min(1) }),
+  output: z.object({ knowledge: ProjectBriefSchema }),
+});
+
+export const knowledgeInspectRpc = defineRpc({
+  name: "linear.knowledge.inspect",
+  input: z.object({ projectId: z.string().min(1) }),
+  output: z.object({ knowledge: ProjectBriefSchema }),
+});
+
+/** The areas of an agent's project, and ticket paths matched to the project's real files. */
+export const liveProjectRpc = defineRpc({
+  name: "linear.live.project",
+  input: z.object({
+    agentId: z.string().min(1),
+    paths: z.array(z.string()).max(MAX_RESOLVE_PATHS),
+  }),
+  output: z.object({
+    areas: z.array(AreaRefSchema),
+    resolved: z.array(z.object({ from: z.string(), to: z.string() })),
+  }),
+});
+
+export function toAreaRef(area: Area): AreaRef {
+  return { path: area.path, name: area.name, kind: area.kind, role: area.role, summary: area.summary };
+}
+
+/** The deepest area whose folder holds the path. */
+export function areaOf<A extends { path: string }>(path: string, areas: readonly A[]): A | null {
+  let best: A | null = null;
+  for (const area of areas) {
+    if (path.startsWith(area.path) && (!best || area.path.length > best.path.length)) best = area;
+  }
+  return best;
+}
+
+/** Such as "billing-api · service", "server · backend", or "docs". */
+export function areaLabel(area: AreaRef): string {
+  const what = area.role || (area.kind === "folder" ? "" : area.kind);
+  return what && what.toLowerCase() !== area.name.toLowerCase() ? `${area.name} · ${what}` : area.name;
+}
+
+function topFolder(path: string): string {
+  const index = path.indexOf("/");
+  return index < 0 ? "./" : path.slice(0, index + 1);
+}
+
+/** File counts per top folder; "./" counts files at the root. */
+export function topFolders(files: readonly string[]): { name: string; files: number }[] {
+  const counts = new Map<string, number>();
+  for (const file of files) counts.set(topFolder(file), (counts.get(topFolder(file)) ?? 0) + 1);
+  return [...counts]
+    .map(([name, count]) => ({ name, files: count }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Where an off-map file is: its area, or its top folder when the project has no knowledge. */
+export function whereLabel(path: string, areas: readonly AreaRef[]): string {
+  const area = areaOf(path, areas);
+  return area && area.path !== "" ? areaLabel(area) : topFolder(path);
+}
+
+/** Folders to the given depth with their file counts, indented, for prompts. */
+export function folderLines(files: readonly string[], depth = 2, limit = 60): string[] {
+  const counts = new Map<string, number>();
+  for (const file of files) {
+    const parts = file.split("/").slice(0, -1);
+    for (let level = 1; level <= Math.min(depth, parts.length); level += 1) {
+      const dir = `${parts.slice(0, level).join("/")}/`;
+      counts.set(dir, (counts.get(dir) ?? 0) + 1);
+    }
+  }
+  const dirs = [...counts.keys()].sort();
+  if (dirs.length > limit && depth > 1) return folderLines(files, depth - 1, limit);
+  const lines = dirs.slice(0, limit).map((dir) => {
+    const indent = "  ".repeat(dir.split("/").length - 2);
+    return `${indent}${dir} (${counts.get(dir)})`;
+  });
+  if (dirs.length > limit) lines.push(`... ${dirs.length - limit} more folders`);
+  return lines;
+}
+
+function countLine(entries: readonly { name: string; files: number }[]): string {
+  return entries.map((entry) => `${entry.name} ${entry.files}`).join(", ");
+}
+
+/** The project map an agent prompt starts from. Empty without knowledge. */
+export function knowledgeLines(knowledge: ProjectKnowledge | null): string[] {
+  if (!knowledge) return [];
+  const source = knowledge.source === "git" ? "git ls-files" : "a folder walk";
+  const lines = [
+    `Project map from the plugin's inspection (${knowledge.inspectedAt}, by ${source}). Start from`,
+    "it instead of listing the whole repository; files may have changed since.",
+  ];
+  if (knowledge.summary) lines.push(`- Project: ${knowledge.summary}`);
+  const truncated = knowledge.truncated ? ", list truncated" : "";
+  lines.push(`- ${knowledge.fileCount} files${truncated}. Languages: ${countLine(knowledge.languages) || "unknown"}.`);
+  if (knowledge.guides.length > 0) lines.push(`- Guides: ${knowledge.guides.join(", ")}`);
+  if (knowledge.commands.length > 0) lines.push(`- Commands: ${knowledge.commands.join(", ")}`);
+  if (knowledge.areas.length > 0) {
+    lines.push("Areas (services, packages, and main folders):");
+    for (const area of knowledge.areas) {
+      const manifests = area.manifests.length > 0 ? ` [${area.manifests.join(", ")}]` : "";
+      const languages = area.languages.length > 0 ? `, ${area.languages.join("/")}` : "";
+      const summary = area.summary ? `: ${area.summary}` : "";
+      const files = `${area.files} ${area.files === 1 ? "file" : "files"}`;
+      lines.push(`- ${area.path || "./"} ${areaLabel(area)}${manifests}, ${files}${languages}${summary}`);
+    }
+  }
+  lines.push("Folders (file count):", ...folderLines(knowledge.files));
+  return lines;
+}
+
+function byName(files: readonly string[]): Map<string, string[]> {
+  const index = new Map<string, string[]>();
+  for (const file of files) {
+    const name = file.slice(file.lastIndexOf("/") + 1);
+    const known = index.get(name);
+    if (known) known.push(file);
+    else index.set(name, [file]);
+  }
+  return index;
+}
+
+function dirsOf(files: readonly string[]): Set<string> {
+  const dirs = new Set<string>();
+  for (const file of files) {
+    let index = file.indexOf("/");
+    while (index >= 0) {
+      dirs.add(file.slice(0, index + 1));
+      index = file.indexOf("/", index + 1);
+    }
+  }
+  return dirs;
+}
+
+/** Ticket paths matched to real files: "linear.ts" to "server/linear.ts" when only one fits. */
+export function resolvePaths(paths: readonly string[], files: readonly string[]): Map<string, string> {
+  const known = new Set(files);
+  const names = byName(files);
+  let dirs: Set<string> | null = null;
+  const resolved = new Map<string, string>();
+  for (const path of paths) {
+    let matches: string[];
+    if (path.endsWith("/")) {
+      dirs ??= dirsOf(files);
+      if (dirs.has(path)) continue;
+      matches = [...dirs].filter((dir) => dir.endsWith(`/${path}`));
+    } else {
+      if (known.has(path)) continue;
+      const name = path.slice(path.lastIndexOf("/") + 1);
+      matches = (names.get(name) ?? []).filter((file) => file === name || file.endsWith(`/${path}`));
+    }
+    if (matches.length === 1 && matches[0]) resolved.set(path, matches[0]);
+  }
+  return resolved;
+}
+
+const KINDS_SAID = "(?:service|package|app|module|library|lib|worker|folder|directory|dir)";
+
+function escapeRegex(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function aliases(area: AreaRef): string[] {
+  const folder = area.path.replace(/\/$/, "").split("/").pop() ?? "";
+  return [...new Set([area.name, folder])].filter((alias) => alias.length >= 3);
+}
+
+// A service or package counts when its name appears; a plain folder only when the text says
+// "the docs folder" or similar, since folder names like "server" are common words.
+function mentions(text: string, alias: string, plain: boolean): boolean {
+  const word = `(?:^|[^\\w@/.-])${escapeRegex(alias)}(?![\\w@/-])`;
+  if (plain && alias.length >= 4 && new RegExp(word, "i").test(text)) return true;
+  return new RegExp(`${word}\\s+${KINDS_SAID}\\b`, "i").test(text);
+}
+
+/** Areas the text names, other than the whole repository. */
+export function areasIn(text: string, areas: readonly AreaRef[]): AreaRef[] {
+  return areas.filter(
+    (area) =>
+      area.path !== "" && aliases(area).some((alias) => mentions(text, alias, area.kind !== "folder")),
+  );
+}