@yannelli/paseo-linear-plugin 1.0.1 → 1.1.0-beta.0

package/shared/live.ts

@@ -0,0 +1,200 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { IssueCardSchema, WorkflowStateSchema } from "./linear";
+
+// Contracts for Linear Live, todo sync, and project setup. Agents the plugin starts for itself
+// carry their own labels so they get no pill, no sync, and no place in the linked agent list.
+
+export const MapFileSchema = z.object({
+  path: z.string().min(1),
+  /** Issue key the file belongs to: the parent or one of its sub-issues. */
+  issue: z.string().min(1),
+});
+export type MapFile = z.infer<typeof MapFileSchema>;
+
+export const IssueMapSchema = z.object({
+  identifier: z.string(),
+  source: z.enum(["semantic", "explore"]),
+  files: z.array(MapFileSchema),
+  createdAt: z.string(),
+});
+export type IssueMap = z.infer<typeof IssueMapSchema>;
+
+export const JobSchema = z.object({
+  id: z.string(),
+  status: z.enum(["running", "done", "failed"]),
+  agentId: z.string().nullable(),
+  error: z.string().nullable(),
+  startedAt: z.string(),
+});
+export type Job = z.infer<typeof JobSchema>;
+
+/** What the explore agent must return. */
+export const ExploreResultSchema = z.object({
+  files: z.array(z.object({ path: z.string().min(1), issue: z.string().min(1) })).max(200),
+});
+
+export const InitProposalSchema = z.object({
+  instructions: z.string().default(""),
+  steps: z.array(z.string()).default([]),
+  implement: z.string().default(""),
+  review: z.string().default(""),
+});
+export type InitProposal = z.infer<typeof InitProposalSchema>;
+
+export const MAX_LIST_DIRS = 40;
+export const MAX_DIR_ENTRIES = 60;
+
+export const listFilesRpc = defineRpc({
+  name: "linear.live.files",
+  input: z.object({ agentId: z.string().min(1), dirs: z.array(z.string()).max(MAX_LIST_DIRS) }),
+  output: z.object({
+    dirs: z.array(z.object({ dir: z.string(), files: z.array(z.string()), truncated: z.boolean() })),
+  }),
+});
+
+export const MAX_LINK_FILES = 200;
+
+/** Imports and other links between the files on the graph. */
+export const linksRpc = defineRpc({
+  name: "linear.live.links",
+  input: z.object({ agentId: z.string().min(1), files: z.array(z.string().min(1)).max(MAX_LINK_FILES) }),
+  output: z.object({
+    links: z.array(z.object({ from: z.string(), to: z.string(), kind: z.enum(["import", "link", "mention"]) })),
+  }),
+});
+
+export const liveMapRpc = defineRpc({
+  name: "linear.live.map",
+  input: z.object({ identifier: z.string().min(1) }),
+  output: z.object({ map: IssueMapSchema.nullable(), job: JobSchema.nullable() }),
+});
+
+export const exploreRpc = defineRpc({
+  name: "linear.live.explore",
+  input: z.object({ agentId: z.string().min(1), force: z.boolean().default(false) }),
+  output: z.object({ job: JobSchema }),
+});
+
+export const LaunchConfigSchema = z.object({
+  provider: z.string().min(1),
+  thinkingOptionId: z.string().optional(),
+  modeId: z.string().optional(),
+});
+
+// The daemon maps the files first and then starts the agent, so closing the app mid-way
+// still starts it. With a saved map, or when exploring cannot start, the agent starts now.
+export const LaunchInputSchema = z.object({
+  workspaceId: z.string().min(1),
+  identifier: z.string().min(1),
+  keyScope: z.string().nullable(),
+  agent: z.object({
+    config: LaunchConfigSchema,
+    title: z.string(),
+    prompt: z.string(),
+    labels: z.record(z.string(), z.string()),
+  }),
+  card: IssueCardSchema,
+});
+export type LaunchInput = z.infer<typeof LaunchInputSchema>;
+
+export const launchAfterExploreRpc = defineRpc({
+  name: "linear.live.launch",
+  input: LaunchInputSchema,
+  output: z.object({ agentId: z.string().nullable(), job: JobSchema }),
+});
+
+export const SyncMoveSchema = z.object({
+  identifier: z.string(),
+  from: WorkflowStateSchema,
+  to: WorkflowStateSchema,
+});
+
+export const syncNowRpc = defineRpc({
+  name: "linear.sync.now",
+  input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({ moves: z.array(SyncMoveSchema), skipped: z.string().nullable() }),
+});
+
+export const initStartRpc = defineRpc({
+  name: "linear.init.start",
+  input: z.object({ projectId: z.string().min(1), rootPath: z.string().min(1) }),
+  output: z.object({ job: JobSchema }),
+});
+
+export const initStatusRpc = defineRpc({
+  name: "linear.init.status",
+  input: z.object({ jobId: z.string().min(1) }),
+  output: z.object({ job: JobSchema.nullable(), proposal: InitProposalSchema.nullable() }),
+});
+
+const EXTENSIONS =
+  "ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|java|kt|swift|c|cc|cpp|h|hpp|cs|php|vue|svelte|css|scss|html|md|mdx|json|ya?ml|toml|sql|sh|prisma|graphql";
+const PATH = new RegExp(
+  `(?:^|[\\s\`'"(\\[])((?:[\\w@.-]+/)*[\\w@.-]+\\.(?:${EXTENSIONS}))(?=$|[\\s\`'")\\],.:;!?])`,
+  "g",
+);
+const DIRECTORY = /`((?:[\w@.-]+\/)+)`/g;
+const ISSUE_KEY = /\b[A-Z][A-Z0-9]*-\d+\b/g;
+
+export function pathsIn(text: string): string[] {
+  const found = new Set<string>();
+  for (const match of text.matchAll(PATH)) if (match[1]) found.add(match[1].replace(/^\.\//, ""));
+  for (const match of text.matchAll(DIRECTORY)) if (match[1]) found.add(match[1]);
+  return [...found].filter((path) => !/^https?:/.test(path) && !path.includes("//"));
+}
+
+export interface SemanticIssue {
+  identifier: string;
+  title: string;
+  description: string | null;
+  children: readonly { identifier: string; title: string }[];
+}
+
+// Linear sends sub-issue titles but not their descriptions, so a path in the parent's text
+// belongs to the sub-issue its line names and otherwise to the parent.
+export function semanticMap(issue: SemanticIssue, now = new Date()): IssueMap {
+  const owners = new Map<string, string>();
+  const childKeys = new Set(issue.children.map((child) => child.identifier.toUpperCase()));
+  for (const child of issue.children) {
+    for (const path of pathsIn(child.title)) owners.set(path, child.identifier);
+  }
+  const lines = `${issue.title}\n${issue.description ?? ""}`.split("\n");
+  for (const line of lines) {
+    const named = (line.match(ISSUE_KEY) ?? []).find((key) => childKeys.has(key));
+    for (const path of pathsIn(line)) {
+      if (!owners.has(path)) owners.set(path, named ?? issue.identifier);
+    }
+  }
+  return {
+    identifier: issue.identifier,
+    source: "semantic",
+    files: [...owners].map(([path, owner]) => ({ path, issue: owner })),
+    createdAt: now.toISOString(),
+  };
+}
+
+/** Parses the last JSON object in an agent reply: a fenced block, the whole text, or braces. */
+export function lastJsonObject(reply: string): unknown {
+  const fences = [...reply.matchAll(/```(?:json)?\s*\n([\s\S]*?)```/g)].reverse();
+  const candidates = [...fences.map((match) => match[1] ?? ""), reply.trim()];
+  const start = reply.indexOf("{");
+  const end = reply.lastIndexOf("}");
+  if (start >= 0 && end > start) candidates.push(reply.slice(start, end + 1));
+  for (const candidate of candidates) {
+    try {
+      const value: unknown = JSON.parse(candidate);
+      if (value && typeof value === "object" && !Array.isArray(value)) return value;
+    } catch {
+      // Not JSON; try the next candidate.
+    }
+  }
+  return null;
+}
+
+/** Directory of a repo path, with a trailing slash, or "" for the root. */
+export function dirOf(path: string): string {
+  if (path.endsWith("/")) return path;
+  const index = path.lastIndexOf("/");
+  return index < 0 ? "" : path.slice(0, index + 1);
+}

package/shared/map-model.ts

@@ -0,0 +1,192 @@
+import type { DirTouch, FileTouch } from "./activity";
+import { dirOf, type MapFile } from "./live";
+
+// The Linear Live map: predicted files and touched files grouped into folder zones, and the
+// column layout for those zones. Pure, so it runs in tests without React Native.
+
+const MAX_GHOSTS = 4;
+/** Listing chips are hidden once a zone has this many real tiles. */
+const GHOSTS_UNTIL = 6;
+
+export interface MapTile {
+  path: string;
+  name: string;
+  owner: string | null;
+  ghost: boolean;
+  onMap: boolean;
+  touch: "none" | "read" | "edited" | "created";
+  added: number;
+  removed: number;
+}
+
+export type ZoneExplored = "none" | "listed" | "searched";
+
+export interface MapZone {
+  dir: string;
+  tiles: MapTile[];
+  /** Files in the zone that are on the map. */
+  predicted: number;
+  /** Files in the zone the agent read or changed. */
+  touched: number;
+  /** Touched files that are on the map. */
+  hits: number;
+  explored: ZoneExplored;
+}
+
+export interface MapModel {
+  zones: MapZone[];
+  touched: number;
+  hits: number;
+}
+
+// Search hits alone do not count: one broad search would flood the map with off-map tiles.
+function isTouched(file: FileTouch): boolean {
+  return file.reads + file.edits > 0;
+}
+
+function touchState(file: FileTouch | undefined): MapTile["touch"] {
+  if (!file) return "none";
+  if (file.created) return "created";
+  return file.edits > 0 ? "edited" : "read";
+}
+
+interface Predictions {
+  files: ReadonlyMap<string, string>;
+  dirs: ReadonlyMap<string, string>;
+}
+
+// A map entry ending in "/" names a directory: it seeds a zone and owns the files inside.
+function predictions(files: readonly MapFile[]): Predictions {
+  const paths = new Map<string, string>();
+  const dirs = new Map<string, string>();
+  for (const file of files) {
+    const target = file.path.endsWith("/") ? dirs : paths;
+    if (!target.has(file.path)) target.set(file.path, file.issue.toUpperCase());
+  }
+  return { files: paths, dirs };
+}
+
+function ownerOf(path: string, predicted: Predictions): string | null {
+  const direct = predicted.files.get(path);
+  if (direct) return direct;
+  for (const [dir, owner] of predicted.dirs) if (path.startsWith(dir)) return owner;
+  return null;
+}
+
+/** Zone directories: predicted ones in map order, then touched ones by name. */
+export function zoneDirs(files: readonly MapFile[], touches: readonly FileTouch[]): string[] {
+  const dirs = new Set(files.map((file) => dirOf(file.path)));
+  const extra = touches.filter(isTouched).map((file) => dirOf(file.path));
+  for (const dir of [...new Set(extra)].sort()) dirs.add(dir);
+  return [...dirs];
+}
+
+// A listed folder counts for itself; a recursive search counts for every folder under it,
+// except a search of the whole repository, which would mark every zone.
+function exploredState(dir: string, dirs: readonly DirTouch[]): ZoneExplored {
+  let state: ZoneExplored = "none";
+  for (const touch of dirs) {
+    const covers = touch.path === dir || (touch.deep && touch.path !== "" && dir.startsWith(touch.path));
+    if (covers && touch.deep) return "searched";
+    if (covers) state = "listed";
+  }
+  return state;
+}
+
+export function buildMapModel(
+  files: readonly MapFile[],
+  touches: readonly FileTouch[],
+  listing: ReadonlyMap<string, readonly string[]>,
+  dirs: readonly DirTouch[] = [],
+): MapModel {
+  const predicted = predictions(files);
+  const touched = new Map(touches.filter(isTouched).map((file) => [file.path, file]));
+  const zones = zoneDirs(files, touches).map((dir): MapZone => {
+    const inZone = (path: string) => dirOf(path) === dir;
+    const real = new Set([...predicted.files.keys(), ...touched.keys()].filter(inZone));
+    const tiles = [...real].sort().map((path): MapTile => {
+      const touch = touched.get(path);
+      const owner = ownerOf(path, predicted);
+      return {
+        path,
+        name: path.slice(dir.length),
+        owner,
+        ghost: false,
+        onMap: owner !== null,
+        touch: touchState(touch),
+        added: touch?.added ?? 0,
+        removed: touch?.removed ?? 0,
+      };
+    });
+    const ghosts = (tiles.length >= GHOSTS_UNTIL ? [] : (listing.get(dir) ?? []))
+      .filter((name) => !real.has(`${dir}${name}`))
+      .slice(0, MAX_GHOSTS)
+      .map((name): MapTile => {
+        const path = `${dir}${name}`;
+        const owner = ownerOf(path, predicted);
+        const onMap = owner !== null;
+        return { path, name, owner, ghost: true, onMap, touch: "none", added: 0, removed: 0 };
+      });
+    return {
+      dir,
+      tiles: [...tiles, ...ghosts],
+      predicted: tiles.filter((tile) => tile.onMap).length,
+      touched: tiles.filter((tile) => tile.touch !== "none").length,
+      hits: tiles.filter((tile) => tile.touch !== "none" && tile.onMap).length,
+      explored: exploredState(dir, dirs),
+    };
+  });
+  let hits = 0;
+  for (const path of touched.keys()) if (ownerOf(path, predicted)) hits += 1;
+  return { zones, touched: touched.size, hits };
+}
+
+export function hitRateLine(model: MapModel): string {
+  if (model.touched === 0) return "No files touched yet";
+  const noun = model.touched === 1 ? "file" : "files";
+  return `${model.touched} ${noun} touched, ${model.hits} on the map`;
+}
+
+export const ZONE_GAP = 10;
+
+// Rough zone height from its tiles, so zones can go to the shortest column. Tiles wrap, so
+// count how many fit per row by name length.
+function zoneHeight(zone: MapZone, width: number): number {
+  const inner = Math.max(120, width - 26);
+  let rows = 1;
+  let used = 0;
+  for (const tile of zone.tiles) {
+    const tileWidth = Math.min(inner, 32 + tile.name.length * 7);
+    if (used > 0 && used + tileWidth > inner) {
+      rows += 1;
+      used = 0;
+    }
+    used += tileWidth + 6;
+  }
+  return 46 + rows * 32;
+}
+
+/**
+ * Splits zones into columns in map order. A zone in `placed` keeps its column; a new zone
+ * goes to the shortest column and is added to `placed`.
+ */
+export function masonry(
+  zones: readonly MapZone[],
+  columns: number,
+  width: number,
+  placed: Map<string, number>,
+): MapZone[][] {
+  const result: MapZone[][] = Array.from({ length: columns }, () => []);
+  const heights: number[] = Array.from({ length: columns }, () => 0);
+  const columnWidth = (width - ZONE_GAP * (columns - 1)) / columns;
+  for (const zone of zones) {
+    let column = placed.get(zone.dir);
+    if (column === undefined || column >= columns) {
+      column = heights.indexOf(Math.min(...heights));
+      placed.set(zone.dir, column);
+    }
+    result[column]?.push(zone);
+    heights[column] = (heights[column] ?? 0) + zoneHeight(zone, columnWidth) + ZONE_GAP;
+  }
+  return result;
+}

package/shared/project-setup.ts

@@ -0,0 +1,55 @@
+import type { InitProposal } from "./live";
+import type { ProjectConfig } from "./settings";
+
+// A setup proposal shows only fields that change; accepted fields append to the prompts.
+export type ProposalField = "instructions" | "steps" | "implement" | "review";
+
+export interface FieldDiff {
+  field: ProposalField;
+  label: string;
+  current: string;
+  proposed: string;
+}
+
+export function proposalDiffs(config: ProjectConfig, proposal: InitProposal): FieldDiff[] {
+  const steps = proposal.steps.map((step) => step.trim()).filter(Boolean);
+  const rows: FieldDiff[] = [
+    {
+      field: "instructions",
+      label: "Project instructions",
+      current: config.instructions.trim(),
+      proposed: proposal.instructions.trim(),
+    },
+    {
+      field: "steps",
+      label: "Project steps",
+      current: config.steps.join("\n"),
+      proposed: steps.join("\n"),
+    },
+    {
+      field: "implement",
+      label: "Implement: append to the prompt",
+      current: config.implement.mode === "default" ? "" : config.implement.text.trim(),
+      proposed: proposal.implement.trim(),
+    },
+    {
+      field: "review",
+      label: "Review: append to the prompt",
+      current: config.review.mode === "default" ? "" : config.review.text.trim(),
+      proposed: proposal.review.trim(),
+    },
+  ];
+  return rows.filter((row) => row.proposed && row.proposed !== row.current);
+}
+
+export function applyProposal(
+  proposal: InitProposal,
+  fields: ReadonlySet<ProposalField>,
+): Partial<ProjectConfig> {
+  const patch: Partial<ProjectConfig> = {};
+  if (fields.has("instructions")) patch.instructions = proposal.instructions.trim();
+  if (fields.has("steps")) patch.steps = proposal.steps.map((s) => s.trim()).filter(Boolean);
+  if (fields.has("implement")) patch.implement = { mode: "append", text: proposal.implement.trim() };
+  if (fields.has("review")) patch.review = { mode: "append", text: proposal.review.trim() };
+  return patch;
+}

package/shared/prompts.ts

@@ -1,5 +1,6 @@
 import type { IssueDetail } from "./linear";
 import type { AgentAction, LinearSettings, ProjectConfig } from "./settings";
+import { todoConventionLine } from "./todo-sync";
 
 export const DEFAULT_TEMPLATES: Record<AgentAction, string> = {
   implement: [
@@ -128,6 +129,8 @@ export function composePrompt(input: ComposePromptInput): string {
   ];
   // A template that drops {{issue}} still gets the snapshot so the agent never works blind.
   if (!/\{\{\s*issue\s*\}\}/.test(template)) sections.push(snapshot);
+  const convention = input.action === "implement" ? todoConventionLine(issue.children) : null;
+  if (convention) sections.push(convention);
   const instructions = project?.instructions.trim();
   if (instructions) sections.push(`Project instructions:\n${instructions}`);
   const steps = project?.steps.map((step) => step.trim()).filter(Boolean) ?? [];
@@ -147,4 +150,16 @@ export function agentTitle(action: AgentAction, issue: { identifier: string; tit
   return `${prefix}: ${title}`.slice(0, 120);
 }
 
-export const AGENT_LABELS = { issue: "linear.issue", action: "linear.action" } as const;
+export const AGENT_LABELS = {
+  issue: "linear.issue",
+  action: "linear.action",
+  /** The Paseo project whose Linear key loaded the issue. */
+  project: "linear.project",
+  explore: "linear.explore",
+  init: "linear.init",
+} as const;
+
+/** Agents the plugin starts for itself: explore and project setup. */
+export function isInternalAgent(labels: Readonly<Record<string, string>> | undefined): boolean {
+  return Boolean(labels?.[AGENT_LABELS.explore] || labels?.[AGENT_LABELS.init]);
+}

package/shared/settings.ts

@@ -1,4 +1,4 @@
-import { defineSettings } from "@getpaseo/plugin";
+import { defineRpc, defineSettings } from "@getpaseo/plugin";
 import { z } from "zod";
 
 export const AGENT_ACTIONS = ["implement", "review"] as const;
@@ -27,6 +27,12 @@ export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
 export const ISOLATIONS = ["worktree", "workspace"] as const;
 export type Isolation = (typeof ISOLATIONS)[number];
 
+export const MAPPING_MODES = ["semantic", "explore"] as const;
+export type MappingMode = (typeof MAPPING_MODES)[number];
+
+export const LIVE_VIEWS = ["map", "graph"] as const;
+export type LiveView = (typeof LIVE_VIEWS)[number];
+
 export const linearSettings = defineSettings({
   id: "linear",
   scope: "host",
@@ -45,6 +51,24 @@ export const linearSettings = defineSettings({
         assignToMe: z.boolean().default(true),
       })
       .prefault({}),
+    // Explore runs cost provider usage and sync writes to Linear, so both start off.
+    live: z
+      .object({
+        enabled: z.boolean().default(true),
+        mapping: z.enum(MAPPING_MODES).default("semantic"),
+        exploreProvider: z.string().default(""),
+        syncTodos: z.boolean().default(false),
+        view: z.enum(LIVE_VIEWS).default("map"),
+        issuesCollapsed: z.boolean().default(false),
+      })
+      .prefault({}),
+    // Where the plugin works: every project, minus or plus per-project switches.
+    access: z
+      .object({
+        allProjects: z.boolean().default(true),
+        projects: z.record(z.string(), z.boolean()).default({}),
+      })
+      .prefault({}),
     projects: z.array(ProjectConfigSchema).default([]),
   }),
 });
@@ -66,3 +90,35 @@ export function upsertProject(
   const others = settings.projects.filter((entry) => entry.projectId !== next.projectId);
   return [...others, next];
 }
+
+export type ProjectAccess = LinearSettings["access"];
+
+/** A project switch wins; projects without one follow the all-projects switch. */
+export function projectEnabled(access: ProjectAccess, projectId: string | null | undefined) {
+  if (!projectId) return access.allProjects;
+  return access.projects[projectId] ?? access.allProjects;
+}
+
+/** Sets one project's switch, dropping it when it matches the all-projects switch. */
+export function withProjectAccess(
+  access: ProjectAccess,
+  projectId: string,
+  enabled: boolean,
+): ProjectAccess {
+  const { [projectId]: _previous, ...others } = access.projects;
+  return {
+    ...access,
+    projects: enabled === access.allProjects ? others : { ...others, [projectId]: enabled },
+  };
+}
+
+export const AccessSchema = z.object({
+  allProjects: z.boolean(),
+  projects: z.record(z.string(), z.boolean()),
+});
+
+export const accessRpc = defineRpc({
+  name: "linear.access.get",
+  input: z.object({}),
+  output: AccessSchema,
+});