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

package/shared/settings.ts

@@ -1,5 +1,6 @@
-import { defineSettings } from "@getpaseo/plugin";
+import { defineRpc, defineSettings } from "@getpaseo/plugin";
 import { z } from "zod";
+import { IconSettingsSchema } from "./custom-icon";
 
 export const AGENT_ACTIONS = ["implement", "review"] as const;
 export type AgentAction = (typeof AGENT_ACTIONS)[number];
@@ -12,6 +13,53 @@ const ActionOverrideSchema = z.object({
   text: z.string().default(""),
 });
 
+/** Extra instructions the launch adds to the prompt. Saved per project. */
+export const GuidanceSchema = z.object({
+  /** Keep Linear current: todos with sub-issue keys, and comments when a Linear tool exists. */
+  updateLinear: z.boolean().default(false),
+  /** Subagents state the issue key they work on. Claude agents also get a hook that tells them. */
+  subagentKeys: z.boolean().default(false),
+  /** Hand work to Paseo agents on the same provider, with thinking that fits the task. */
+  paseoSubagents: z.boolean().default(false),
+});
+export type Guidance = z.infer<typeof GuidanceSchema>;
+export const GUIDANCE_KEYS = ["updateLinear", "subagentKeys", "paseoSubagents"] as const;
+
+export const ISOLATIONS = ["worktree", "workspace"] as const;
+export type Isolation = (typeof ISOLATIONS)[number];
+
+/** The most agents the agent limit setting offers; 0 means no limit. */
+export const MAX_AGENTS_LIMIT = 16;
+const AgentLimit = z.number().int().min(0).max(MAX_AGENTS_LIMIT);
+
+/** The plugin's linear MCP server, and the agents its start_agent tool starts. */
+export const ToolSettingsSchema = z.object({
+  /** Agents started from an issue get the linear MCP server when their options need it. */
+  enabled: z.boolean().default(true),
+  /** The edit_issue tool, which changes issue descriptions. */
+  allowEdits: z.boolean().default(true),
+  /** The launch page offers an agent for each sub-issue. */
+  assignAgents: z.boolean().default(true),
+  /** Agents that one launch may run at the same time with start_agent; 0 has no limit. */
+  maxAgents: AgentLimit.default(0),
+});
+export type ToolSettings = z.infer<typeof ToolSettingsSchema>;
+
+/** A project's own values. A missing value follows the setting for all projects. */
+export const ProjectOverridesSchema = z.object({
+  provider: z.string().optional(),
+  isolation: z.enum(ISOLATIONS).optional(),
+  includeComments: z.boolean().optional(),
+  moveToStarted: z.boolean().optional(),
+  assignToMe: z.boolean().optional(),
+  syncTodos: z.boolean().optional(),
+  tools: z.boolean().optional(),
+  allowEdits: z.boolean().optional(),
+  assignAgents: z.boolean().optional(),
+  maxAgents: AgentLimit.optional(),
+});
+export type ProjectOverrides = z.infer<typeof ProjectOverridesSchema>;
+
 export const ProjectConfigSchema = z.object({
   projectId: z.string(),
   displayName: z.string(),
@@ -21,11 +69,23 @@ export const ProjectConfigSchema = z.object({
   steps: z.array(z.string()).default([]),
   implement: ActionOverrideSchema.prefault({}),
   review: ActionOverrideSchema.prefault({}),
+  guidance: GuidanceSchema.prefault({}),
+  overrides: ProjectOverridesSchema.prefault({}),
 });
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
 
-export const ISOLATIONS = ["worktree", "workspace"] as const;
-export type Isolation = (typeof ISOLATIONS)[number];
+/** Settings with a project's guidance saved, adding the project when it has no entry yet. */
+export function withProjectGuidance(
+  values: LinearSettings,
+  project: { projectId: string; displayName: string; rootPath: string },
+  guidance: Guidance,
+): LinearSettings {
+  const known = values.projects.find((entry) => entry.projectId === project.projectId);
+  return { ...values, projects: upsertProject(values, { ...(known ?? emptyProjectConfig(project)), guidance }) };
+}
+
+export const MAPPING_MODES = ["semantic", "explore"] as const;
+export type MappingMode = (typeof MAPPING_MODES)[number];
 
 export const linearSettings = defineSettings({
   id: "linear",
@@ -45,12 +105,62 @@ 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(""),
+        /** Thinking option of the explore model; empty is the model's default. */
+        exploreEffort: z.string().default(""),
+        syncTodos: z.boolean().default(false),
+        issuesCollapsed: z.boolean().default(false),
+      })
+      .prefault({}),
+    tools: ToolSettingsSchema.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([]),
+    /** The icon of pills and other plugin places: built-in or the user's SVG. */
+    icon: IconSettingsSchema.prefault({}),
   }),
 });
 
 export type LinearSettings = z.output<typeof linearSettings.schema>;
 
+/** The settings that a project can change, with its own values applied. */
+export interface ProjectDefaults {
+  launch: LinearSettings["launch"];
+  syncTodos: boolean;
+  tools: ToolSettings;
+}
+
+export function projectDefaults(values: LinearSettings, projectId: string | null | undefined): ProjectDefaults {
+  const own = (projectId ? values.projects.find((entry) => entry.projectId === projectId)?.overrides : undefined) ?? {};
+  const { launch, tools } = values;
+  return {
+    launch: {
+      provider: own.provider ?? launch.provider,
+      isolation: own.isolation ?? launch.isolation,
+      includeComments: own.includeComments ?? launch.includeComments,
+      moveToStarted: own.moveToStarted ?? launch.moveToStarted,
+      assignToMe: own.assignToMe ?? launch.assignToMe,
+    },
+    syncTodos: own.syncTodos ?? values.live.syncTodos,
+    tools: {
+      enabled: own.tools ?? tools.enabled,
+      allowEdits: own.allowEdits ?? tools.allowEdits,
+      assignAgents: own.assignAgents ?? tools.assignAgents,
+      maxAgents: own.maxAgents ?? tools.maxAgents,
+    },
+  };
+}
+
 export function emptyProjectConfig(project: {
   projectId: string;
   displayName: string;
@@ -66,3 +176,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,
+});

package/shared/shell-activity.ts

@@ -0,0 +1,309 @@
+import { lexShell, splitCommands, type Word } from "./shell-lexer";
+
+// Agents that read through the shell (`cat`, `sed -n`, `grep`, `ls`) touch files without a Read
+// tool call. This finds those files in a command, so Linear Live can show them. It only knows
+// common read, search, and list commands; anything else yields no paths.
+
+export interface ExploredDir {
+  /** Repo-relative folder with a trailing slash; "" is the root. */
+  path: string;
+  /** Searched recursively, not only listed. */
+  deep: boolean;
+}
+
+export interface ShellWrite {
+  path: string;
+  mode: "write" | "edit";
+}
+
+export interface ShellActivity {
+  reads: string[];
+  writes: ShellWrite[];
+  dirs: ExploredDir[];
+  pattern: string | null;
+  summary: string;
+}
+
+const KEYWORDS = new Set(["do", "then", "else", "elif", "if", "while", "until", "!", "{", "time"]);
+const WRAPPERS = new Set(["sudo", "command", "nice", "nohup", "env", "builtin", "exec"]);
+// Not named in a summary: shell setup, and filters that only shape another command's output.
+const NO_VERB = new Set(
+  "cd echo printf true false sleep export set : head tail sort uniq wc cut tr grep egrep cat xargs"
+    .split(" "),
+);
+const SUBCOMMANDS = new Set(["git", "npm", "npx", "bun", "bunx", "pnpm", "yarn", "gh", "linear"]);
+const LONG_VALUES = new Set([
+  "glob", "type", "type-not", "max-count", "context", "after-context", "before-context", "regexp",
+  "file", "max-depth", "sort", "include", "exclude", "exclude-dir", "color", "colors", "encoding",
+]);
+const READERS: Record<string, string> = {
+  cat: "", nl: "bdfhilnsvw", less: "", more: "", bat: "rlHm", tac: "", wc: "", file: "",
+  stat: "c", head: "nc", tail: "ncs", sort: "ktoS", uniq: "fs", cut: "dfcb", diff: "", cmp: "",
+  column: "st", xxd: "lsc", od: "", strings: "n", md5sum: "", sha256sum: "",
+};
+const SEARCHERS: Record<string, string> = {
+  grep: "efABCmd", egrep: "efABCmd", fgrep: "efABCmd", rg: "efABCmgtTMdj", ag: "ABCmG",
+  ack: "ABCm",
+};
+
+interface Parsed {
+  options: Set<string>;
+  values: Map<string, string[]>;
+  positionals: Word[];
+  /** Positionals after `--`. */
+  dashed: Word[];
+}
+
+function parseArgs(args: readonly Word[], shortValues: string): Parsed {
+  const parsed: Parsed = { options: new Set(), values: new Map(), positionals: [], dashed: [] };
+  const value = (name: string, text: string | undefined) => {
+    if (text !== undefined) parsed.values.set(name, [...(parsed.values.get(name) ?? []), text]);
+  };
+  let ended = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] as Word;
+    const { text } = arg;
+    if (ended) parsed.dashed.push(arg);
+    else if (text === "--") ended = true;
+    else if (text === "-" || !text.startsWith("-") || arg.dynamic) parsed.positionals.push(arg);
+    else if (text.startsWith("--")) {
+      const [name = "", inline] = text.slice(2).split(/=(.*)/s);
+      parsed.options.add(name);
+      if (inline !== undefined) value(name, inline);
+      else if (LONG_VALUES.has(name)) value(name, args[++index]?.text);
+    } else {
+      for (let at = 1; at < text.length; at += 1) {
+        const flag = text[at] as string;
+        parsed.options.add(flag);
+        if (!shortValues.includes(flag)) continue;
+        value(flag, at + 1 < text.length ? text.slice(at + 1) : args[++index]?.text);
+        break;
+      }
+    }
+  }
+  return parsed;
+}
+
+const MAX_PATTERN = 28;
+
+function hasExtension(path: string): boolean {
+  return /[^./][^/]*\.[A-Za-z0-9]+$/.test(path.split("/").pop() ?? "");
+}
+
+function shortName(path: string): string {
+  const parts = path.replace(/\/$/, "").split("/");
+  return path.endsWith("/") ? parts.slice(-2).join("/") || "the repository" : (parts.pop() ?? path);
+}
+
+function names(paths: readonly string[]): string {
+  const shown = [...new Set(paths.map(shortName))];
+  const extra = shown.length - 2;
+  return `${shown.slice(0, 2).join(", ")}${extra > 0 ? ` +${extra}` : ""}`;
+}
+
+export function parseShell(command: string, cwd: string, start = ""): ShellActivity {
+  const root = cwd.replace(/\/+$/, "");
+  const reads = new Set<string>();
+  const writes = new Map<string, ShellWrite["mode"]>();
+  const dirs = new Map<string, boolean>();
+  const verbs: string[] = [];
+  const env = new Map<string, Word[]>();
+  let pattern: string | null = null;
+  let base: string | null = start;
+
+  const resolve = (raw: string, from: string | null): string | null => {
+    let joined: string;
+    if (raw.startsWith("/")) {
+      if (raw === root || raw === `${root}/`) return "";
+      if (!raw.startsWith(`${root}/`)) return null;
+      joined = raw.slice(root.length + 1);
+    } else if (from === null || raw.startsWith("~")) return null;
+    else joined = from ? `${from}/${raw}` : raw;
+    const parts: string[] = [];
+    for (const part of joined.split("/")) {
+      if (!part || part === ".") continue;
+      if (part !== "..") parts.push(part);
+      else if (parts.pop() === undefined) return null;
+    }
+    return parts.join("/");
+  };
+  const expand = (word: Word): Word[] => {
+    if (!word.dynamic) return [word];
+    const name = /^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/.exec(word.text)?.[1];
+    return name ? (env.get(name) ?? []) : [];
+  };
+  const addDir = (path: string | null, deep: boolean) => {
+    if (path === null) return;
+    const dir = path === "" ? "" : `${path}/`;
+    dirs.set(dir, deep || (dirs.get(dir) ?? false));
+  };
+  // A glob reads from its folder; a plain word is a file, or a folder when `asDir` says so.
+  const target = (word: Word, from: string | null, asDir: (path: string) => boolean, deep = false) => {
+    if (word.globAt >= 0) {
+      const prefix = word.text.slice(0, word.globAt);
+      addDir(resolve(prefix.slice(0, prefix.lastIndexOf("/") + 1), from), deep);
+      return;
+    }
+    const path = resolve(word.text, from);
+    if (path === null) return;
+    if (path === "" || asDir(word.text)) addDir(path, deep);
+    else reads.add(path);
+  };
+  const never = () => false;
+  const noExtension = (text: string) => text.endsWith("/") || !hasExtension(text);
+
+  for (const simple of splitCommands(lexShell(command))) {
+    let words = simple.words;
+    while (words[0] && (KEYWORDS.has(words[0].text) || /^[A-Za-z_]\w*=/.test(words[0].text))) {
+      words = words.slice(1);
+    }
+    while (words[0] && WRAPPERS.has(words[0].text)) words = words.slice(1);
+    const first = words[0]?.text;
+    if (first === "for" && words[2]?.text === "in" && words[1]) {
+      env.set(words[1].text, words.slice(3).flatMap(expand));
+      continue;
+    }
+    const args = words.slice(1).flatMap(expand);
+    for (const { operator, target: file } of simple.redirects) {
+      if (file.dynamic || file.text.startsWith("/dev/")) continue;
+      const path = resolve(file.text, base);
+      if (path === null || path === "") continue;
+      if (operator === "<") reads.add(path);
+      else if (operator === ">" || operator === ">>") writes.set(path, operator === ">" ? "write" : "edit");
+    }
+    if (!first || first === "done" || first === "fi") continue;
+    let from = base;
+    let name = first.split("/").pop() ?? first;
+    let rest = args;
+    if (name === "cd" || name === "pushd") {
+      base = args[0] ? resolve(args[0].text, base) : base;
+      continue;
+    }
+    if (name === "git") {
+      const global = parseArgs(args, "Cc");
+      const at = args.findIndex((arg) => arg === global.positionals[0]);
+      for (const dir of global.values.get("C") ?? []) from = resolve(dir, base);
+      name = `git ${global.positionals[0]?.text ?? ""}`.trim();
+      rest = at < 0 ? [] : args.slice(at + 1);
+    }
+    if (!NO_VERB.has(name)) {
+      const sub = SUBCOMMANDS.has(name) ? args.find((arg) => !arg.text.startsWith("-")) : undefined;
+      verbs.push(sub ? `${name} ${sub.text}` : name);
+    }
+    if (name in READERS) {
+      for (const word of parseArgs(rest, READERS[name] ?? "").positionals) target(word, from, never);
+    } else if (name === "sed" || name === "awk" || name === "gawk" || name === "jq") {
+      const parsed = parseArgs(rest, name === "sed" ? "efl" : name === "jq" ? "" : "Ffv");
+      const scripted = parsed.options.has("e") || parsed.options.has("f");
+      const files = parsed.positionals.slice(scripted && name !== "jq" ? 0 : 1);
+      const inPlace = name === "sed" && parsed.options.has("i");
+      for (const word of files) {
+        if (/^\w+=/.test(word.text)) continue;
+        const path = resolve(word.text, from);
+        if (inPlace && path) writes.set(path, "edit");
+        else target(word, from, never);
+      }
+    } else if (name in SEARCHERS || name === "git grep") {
+      const parsed = parseArgs(rest, SEARCHERS[name] ?? "efABCm");
+      const listing = parsed.options.has("files");
+      const given = parsed.values.get("e")?.[0] ?? parsed.values.get("regexp")?.[0];
+      const explicit = given !== undefined || parsed.options.has("f") || listing;
+      const paths = [...parsed.positionals.slice(explicit ? 0 : 1), ...parsed.dashed];
+      // A grep in a pipe without files or -r filters output and searches nothing.
+      const recursive = parsed.options.has("r") || parsed.options.has("R");
+      const filter = /^[ef]?grep$/.test(name) && !recursive && paths.length === 0;
+      if (filter) continue;
+      if (!listing) pattern ??= given ?? parsed.positionals[0]?.text ?? null;
+      if (paths.length === 0) addDir(from, true);
+      for (const word of paths) target(word, from, noExtension, true);
+    } else if (name === "ls" || name === "tree" || name === "find" || name === "fd") {
+      const parsed = parseArgs(rest, name === "tree" ? "LPIo" : name === "fd" ? "etdE" : "");
+      const deep = name !== "ls" || parsed.options.has("R");
+      const expression = rest.findIndex((word) => /^[-(!]/.test(word.text));
+      let paths = parsed.positionals;
+      // find takes folders first and then an expression whose words are not paths.
+      if (name === "find") paths = expression < 0 ? rest : rest.slice(0, expression);
+      if (name === "fd") paths = paths.slice(1);
+      if (paths.length === 0) addDir(from, deep);
+      for (const word of paths) target(word, from, (text) => name !== "ls" || noExtension(text), deep);
+    } else if (/^git (show|diff|log|blame|annotate)$/.test(name)) {
+      const parsed = parseArgs(rest, "nSGL");
+      for (const word of parsed.positionals) {
+        const path = word.text.includes(":") ? word.text.slice(word.text.indexOf(":") + 1) : null;
+        if (path) target({ ...word, text: path }, from, never);
+      }
+      for (const word of parsed.dashed) target(word, from, noExtension);
+      if (name === "git blame" && parsed.dashed.length === 0) {
+        const last = parsed.positionals.at(-1);
+        if (last) target(last, from, never);
+      }
+    } else if (name === "git ls-files") {
+      const parsed = parseArgs(rest, "x");
+      const paths = [...parsed.positionals, ...parsed.dashed];
+      if (paths.length === 0) addDir(from, true);
+      for (const word of paths) target(word, from, noExtension, true);
+    } else if (name === "tee" || name === "touch") {
+      for (const word of parseArgs(rest, "").positionals) {
+        const path = resolve(word.text, from);
+        if (path) writes.set(path, name === "tee" && rest.some((w) => w.text === "-a") ? "edit" : "write");
+      }
+    } else if (name === "cp" || name === "mv") {
+      const files = parseArgs(rest, "St").positionals;
+      const destination = files.pop();
+      for (const word of files) if (name === "cp") target(word, from, never);
+      const path = destination ? resolve(destination.text, from) : null;
+      if (path && hasExtension(path)) writes.set(path, "write");
+    }
+  }
+
+  const writeList = [...writes].map(([path, mode]) => ({ path, mode }));
+  const readList = [...reads].filter((path) => !writes.has(path));
+  const dirList = [...dirs].map(([path, deep]) => ({ path, deep }));
+  const parts: string[] = [];
+  if (writeList.length > 0) parts.push(`wrote ${names(writeList.map((write) => write.path))}`);
+  if (readList.length > 0) parts.push(`read ${names(readList)}`);
+  if (pattern !== null) {
+    const scope = dirList.filter((dir) => dir.deep && dir.path !== "").map((dir) => dir.path);
+    const shown = pattern.replace(/\\\|/g, "|");
+    const short = shown.length > MAX_PATTERN ? `${shown.slice(0, MAX_PATTERN - 1)}…` : shown;
+    parts.push(`searched "${short}"${scope.length > 0 ? ` in ${names(scope)}` : ""}`);
+  } else if (parts.length === 0 && dirList.length > 0) {
+    parts.push(`listed ${names(dirList.map((dir) => dir.path || "./"))}`);
+  }
+  if (parts.length === 0 && verbs.length > 0) {
+    const shown = [...new Set(verbs)];
+    parts.push(`ran ${shown.slice(0, 2).join(", ")}${shown.length > 2 ? ` +${shown.length - 2}` : ""}`);
+  }
+  const summary = parts.slice(0, 2).join(", ") || "Ran a command";
+  return {
+    reads: readList,
+    writes: writeList,
+    dirs: dirList,
+    pattern,
+    summary: summary.charAt(0).toUpperCase() + summary.slice(1),
+  };
+}
+
+const MAX_CACHED = 500;
+const cache = new Map<string, ShellActivity>();
+
+/** parseShell with a cache: the panel derives activity again on every timeline update. */
+export function shellActivity(command: string, cwd: string, start = ""): ShellActivity {
+  const key = `${cwd}\u0000${start}\u0000${command}`;
+  const hit = cache.get(key);
+  if (hit) return hit;
+  const parsed = parseShell(command, cwd, start);
+  if (cache.size >= MAX_CACHED) cache.delete(cache.keys().next().value as string);
+  cache.set(key, parsed);
+  return parsed;
+}
+
+/** The command as shown in the feed: one line, without a leading `cd` into the agent folder. */
+export function displayCommand(command: string, cwd: string): string {
+  const root = cwd.replace(/\/+$/, "");
+  const firstLine = command.split("\n")[0] ?? command;
+  return firstLine
+    .replace(new RegExp(`^cd\\s+['"]?${root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/?['"]?\\s*&&\\s*`), "")
+    .replaceAll(`${root}/`, "")
+    .trim();
+}

package/shared/shell-lexer.ts

@@ -0,0 +1,180 @@
+// Splits a shell command into words, operators, and redirects, the way the shell would
+// before running it. Expansions are kept as text and marked, since their values are unknown.
+
+export interface Word {
+  kind: "word";
+  text: string;
+  /** Contains `$` or backtick expansion, so the shell may change the text. */
+  dynamic: boolean;
+  /** Index of the first unquoted glob character, or -1. */
+  globAt: number;
+}
+export type Token = Word | { kind: "op"; text: string } | { kind: "redirect"; text: string };
+
+function readExpansion(input: string, start: number): number {
+  const open = input[start + 1];
+  if (input[start] === "`") {
+    const end = input.indexOf("`", start + 1);
+    return end < 0 ? input.length : end + 1;
+  }
+  if (open === "(" || open === "{") {
+    const close = open === "(" ? ")" : "}";
+    let depth = 0;
+    for (let index = start + 1; index < input.length; index += 1) {
+      if (input[index] === open) depth += 1;
+      else if (input[index] === close && --depth === 0) return index + 1;
+    }
+    return input.length;
+  }
+  let index = start + 1;
+  while (index < input.length && /[A-Za-z0-9_@*#?!-]/.test(input[index] as string)) index += 1;
+  return index === start + 1 ? start + 1 : index;
+}
+
+/** Splits a command into words, operators, and redirects. Heredoc bodies are skipped. */
+export function lexShell(input: string): Token[] {
+  const tokens: Token[] = [];
+  const heredocs: { delimiter: string; strip: boolean }[] = [];
+  let text: string | null = null;
+  let dynamic = false;
+  let globAt = -1;
+  let index = 0;
+  const add = (value: string) => {
+    text = (text ?? "") + value;
+  };
+  const flush = () => {
+    if (text !== null) tokens.push({ kind: "word", text, dynamic, globAt });
+    text = null;
+    dynamic = false;
+    globAt = -1;
+  };
+  const skipHeredocs = () => {
+    for (const { delimiter, strip } of heredocs.splice(0)) {
+      while (index < input.length) {
+        const end = input.indexOf("\n", index) < 0 ? input.length : input.indexOf("\n", index);
+        const line = input.slice(index, end);
+        index = end + 1;
+        if ((strip ? line.replace(/^\t+/, "") : line) === delimiter) break;
+      }
+    }
+  };
+  while (index < input.length) {
+    const char = input[index] as string;
+    const next = input[index + 1] ?? "";
+    if (char === "\n") {
+      flush();
+      tokens.push({ kind: "op", text: ";" });
+      index += 1;
+      skipHeredocs();
+    } else if (char === " " || char === "\t" || char === "\r") {
+      flush();
+      index += 1;
+    } else if (char === "#" && text === null) {
+      while (index < input.length && input[index] !== "\n") index += 1;
+    } else if (char === "\\") {
+      if (next !== "\n") add(next);
+      index += 2;
+    } else if (char === "'") {
+      const end = input.indexOf("'", index + 1);
+      const stop = end < 0 ? input.length : end;
+      add(input.slice(index + 1, stop));
+      index = stop + 1;
+    } else if (char === '"') {
+      let value = "";
+      index += 1;
+      while (index < input.length && input[index] !== '"') {
+        const inner = input[index] as string;
+        if (inner === "\\" && '"\\$`'.includes(input[index + 1] ?? "")) {
+          value += input[index + 1];
+          index += 2;
+          continue;
+        }
+        if (inner === "$" || inner === "`") dynamic = true;
+        value += inner;
+        index += 1;
+      }
+      add(value);
+      index += 1;
+    } else if (char === "$" || char === "`") {
+      const end = readExpansion(input, index);
+      dynamic = true;
+      add(input.slice(index, end));
+      index = end;
+    } else if ((char === "&" || char === "|") && next === char) {
+      flush();
+      tokens.push({ kind: "op", text: char + char });
+      index += 2;
+    } else if (char === "&" && next === ">") {
+      flush();
+      tokens.push({ kind: "redirect", text: ">" });
+      index += input[index + 2] === ">" ? 3 : 2;
+    } else if (char === "|" || char === ";" || char === "&" || char === "(" || char === ")") {
+      flush();
+      tokens.push({ kind: "op", text: char === "|" ? "|" : ";" });
+      index += char === "|" && next === "&" ? 2 : 1;
+    } else if (char === ">" || char === "<") {
+      // A bare number before the arrow is a file descriptor, as in `2>/dev/null`.
+      if (text !== null && /^\d+$/.test(text) && !dynamic) text = null;
+      else flush();
+      if (char === "<" && next === "<" && input[index + 2] !== "<") {
+        index += 2;
+        const strip = input[index] === "-";
+        if (strip) index += 1;
+        while (input[index] === " ") index += 1;
+        let delimiter = "";
+        while (index < input.length && !/[\s;&|<>]/.test(input[index] as string)) {
+          if (!`'"\\`.includes(input[index] as string)) delimiter += input[index];
+          index += 1;
+        }
+        heredocs.push({ delimiter, strip });
+        continue;
+      }
+      let operator = char;
+      index += 1;
+      while (input[index] === "<" || (char === ">" && input[index] === ">")) {
+        operator += input[index];
+        index += 1;
+      }
+      if (input[index] === "&") {
+        index += 1;
+        while (/[0-9-]/.test(input[index] ?? "")) index += 1;
+        continue;
+      }
+      if (input[index] === "|") index += 1;
+      tokens.push({ kind: "redirect", text: operator });
+    } else {
+      if (globAt < 0 && (char === "*" || char === "?" || char === "[")) globAt = (text ?? "").length;
+      add(char);
+      index += 1;
+    }
+  }
+  flush();
+  return tokens;
+}
+
+export interface SimpleCommand {
+  words: Word[];
+  redirects: { operator: string; target: Word }[];
+}
+
+export function splitCommands(tokens: readonly Token[]): SimpleCommand[] {
+  const list: SimpleCommand[] = [];
+  let current: SimpleCommand = { words: [], redirects: [] };
+  let pending: string | null = null;
+  for (const token of tokens) {
+    if (token.kind === "op") {
+      pending = null;
+      if (current.words.length > 0 || current.redirects.length > 0) list.push(current);
+      current = { words: [], redirects: [] };
+    } else if (token.kind === "redirect") {
+      pending = token.text;
+    } else if (pending) {
+      current.redirects.push({ operator: pending, target: token });
+      pending = null;
+    } else {
+      current.words.push(token);
+    }
+  }
+  if (current.words.length > 0 || current.redirects.length > 0) list.push(current);
+  return list;
+}