@raidou/pi-pm-subagents 0.1.1

package/src/ui/review-pager.ts

@@ -0,0 +1,146 @@
+import {
+  type ExtensionContext,
+  getMarkdownTheme,
+} from '@earendil-works/pi-coding-agent'
+import { Markdown, matchesKey } from '@earendil-works/pi-tui'
+
+import { truncateText } from '../utils/truncate.js'
+import { BorderView } from './border-view.js'
+import { ScrollView } from './scroll-view.js'
+
+const VIEWPORT_HEIGHT_PCT = 80
+const OVERLAY_WIDTH_PCT = '90%'
+
+export interface ReviewChoice {
+  readonly id: string
+  readonly label: string
+  readonly action: () => Promise<void> | void
+}
+
+export interface ReviewPagerOptions {
+  readonly title: string
+  readonly plan: string
+  readonly choices: readonly ReviewChoice[]
+}
+
+export function renderReviewPager(
+  ctx: ExtensionContext,
+  options: ReviewPagerOptions,
+): Promise<string | undefined> {
+  return ctx.ui.custom<string | undefined>(
+    (tui, theme, _keybindings, done) => {
+      const { title, plan, choices } = options
+      const chromeLines = choices.length + 3
+      let selected = 0
+      const markdown = new Markdown(plan, 0, 0, getMarkdownTheme())
+
+      const scroll = new ScrollView(tui, theme, {
+        child: markdown,
+        viewportHeight: () =>
+          Math.max(
+            3,
+            Math.floor((tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100) -
+              chromeLines -
+              3,
+          ),
+      })
+
+      const component = {
+        render(width: number) {
+          const rows = scroll.render(width)
+          return [
+            theme.fg('accent', theme.bold(title)),
+            ...rows,
+            theme.fg('muted', '─'.repeat(width)),
+            ...choices.map((choice, index) =>
+              index === selected
+                ? theme.fg('accent', `→ ${choice.label}`)
+                : `  ${choice.label}`,
+            ),
+            theme.fg('muted', '─'.repeat(width)),
+            this.footerLine(width),
+          ]
+        },
+        footerLine(width: number) {
+          const th = theme
+          const sep = th.fg('dim', ' · ')
+          const keys: [string, string][] = []
+          keys.push(
+            ['↑↓', 'select'],
+            [`1-${choices.length}`, 'jump'],
+            ['j/k line', 'line'],
+            ['u/d ␣', 'PageUp/Dn page'],
+            ['g/G', 'Home/End jump'],
+            ['Enter', 'confirm'],
+            ['q/esc', 'cancel'],
+          )
+          return truncateText(
+            keys
+              .map(
+                ([key, desc]) =>
+                  `${th.fg('syntaxKeyword', key)} ${th.fg('success', desc)}`,
+              )
+              .join(sep),
+            width,
+          )
+        },
+        handleInput(data: string) {
+          const index = /^[1-9]$/.test(data) ? Number(data) - 1 : -1
+          if (index >= 0 && choices[index] !== undefined) {
+            done(choices[index].id)
+            return
+          }
+          if (matchesKey(data, 'up')) {
+            selected = Math.max(0, selected - 1)
+            tui.requestRender()
+            return
+          }
+          if (matchesKey(data, 'down')) {
+            selected = Math.min(choices.length - 1, selected + 1)
+            tui.requestRender()
+            return
+          }
+          if (matchesKey(data, 'enter')) {
+            const chosen = choices[selected]
+            if (chosen) done(chosen.id)
+            return
+          }
+          if (matchesKey(data, 'escape') || data === 'q') {
+            done(undefined)
+            return
+          }
+          scroll.handleInput(data)
+        },
+        invalidate() {
+          scroll.invalidate()
+        },
+      }
+
+      return new BorderView(theme, { child: component })
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: 'center',
+        width: OVERLAY_WIDTH_PCT,
+        maxHeight: `${VIEWPORT_HEIGHT_PCT}%`,
+      },
+    },
+  )
+}
+
+export async function askHowToProceed(
+  ctx: ExtensionContext,
+  options: ReviewPagerOptions,
+): Promise<void> {
+  ctx.ui.setWorkingVisible(false)
+  try {
+    const choiceId = await renderReviewPager(ctx, options)
+    const choice = options.choices.find((c) => c.id === choiceId)
+    if (choice) {
+      await choice.action()
+    }
+  } finally {
+    ctx.ui.setWorkingVisible(true)
+  }
+}

package/src/ui/scroll-view.test.ts

@@ -0,0 +1,190 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import type { TUI } from '@earendil-works/pi-tui'
+import { describe, expect, it } from 'vitest'
+
+import { ScrollView } from './scroll-view.js'
+
+const UP = '\x1b[A'
+const DOWN = '\x1b[B'
+const HOME = '\x1b[H'
+const END = '\x1b[F'
+const PAGE_UP = '\x1b[5~'
+const PAGE_DOWN = '\x1b[6~'
+const CTRL_D = '\x04'
+const CTRL_U = '\x15'
+
+const theme = {
+  fg: (color: string, text: string) => `[${color}]${text}`,
+} as unknown as Theme
+
+const makeTui = (rows = 30): TUI =>
+  ({ terminal: { rows }, requestRender: () => {} }) as unknown as TUI
+
+const flat = (lines: string[]) => lines.join('\n')
+
+const many = (n: number) => Array.from({ length: n }, (_, i) => `l${i}`)
+
+/** Build a scroll view wrapping fixed `content` with a fixed viewport height. */
+const wrap = (content: string[], viewportHeight: number, autoFollow = false) =>
+  new ScrollView(makeTui(), theme, {
+    child: { render: () => content, invalidate: () => {} },
+    viewportHeight: () => viewportHeight,
+    autoFollow,
+  })
+
+describe('ScrollView render', () => {
+  it('shows every line when content fits the viewport', () => {
+    const v = wrap(['a', 'b', 'c'], 10)
+    const out = v.render(20)
+    expect(out).toHaveLength(3)
+    expect(flat(out)).toContain('a')
+    expect(flat(out)).toContain('c')
+    expect(flat(out)).not.toContain('[muted]█')
+  })
+
+  it('caps the window at the viewport when content overflows', () => {
+    const v = wrap(many(50), 5)
+    const out = v.render(20)
+    expect(out).toHaveLength(5)
+    expect(flat(out)).toContain('l0')
+    expect(flat(out)).not.toContain('l5')
+  })
+
+  it('truncates over-wide lines to width - 2', () => {
+    const v = wrap(['x'.repeat(100)], 5)
+    const body = v.render(20).find((l) => l.includes('x'))
+    expect(body).toBeTruthy()
+    expect(body).not.toContain('x'.repeat(19))
+  })
+
+  it('exposes offset / total / viewportHeight after rendering', () => {
+    const v = wrap(many(50), 5)
+    v.render(20)
+    expect(v.total).toBe(50)
+    expect(v.viewportHeight).toBe(5)
+    expect(v.offset).toBe(0)
+  })
+})
+
+describe('ScrollView scrolling', () => {
+  it('scrolls line by line with j / k and arrows', () => {
+    const v = wrap(many(50), 5)
+    v.render(20)
+    v.handleInput('j')
+    expect(flat(v.render(20))).not.toContain('l0')
+    v.handleInput('k')
+    expect(flat(v.render(20))).toContain('l0')
+    v.handleInput(DOWN)
+    expect(flat(v.render(20))).not.toContain('l0')
+    v.handleInput(UP)
+    expect(flat(v.render(20))).toContain('l0')
+  })
+
+  it('jumps to top and bottom with g / G and home / end', () => {
+    const v = wrap(many(50), 5)
+    v.render(20)
+    v.handleInput(END)
+    expect(flat(v.render(20))).toContain('l49')
+    v.handleInput(HOME)
+    expect(flat(v.render(20))).toContain('l0')
+    v.handleInput('G')
+    expect(flat(v.render(20))).toContain('l49')
+    v.handleInput('g')
+    expect(flat(v.render(20))).toContain('l0')
+  })
+
+  it('pages with d / u, space, ctrl-d / ctrl-u and PgUp / PgDn', () => {
+    const v = wrap(many(50), 5)
+    v.render(20)
+    v.handleInput('d')
+    expect(flat(v.render(20))).not.toContain('l0')
+    v.handleInput('u')
+    expect(flat(v.render(20))).toContain('l0')
+    v.handleInput(' ')
+    expect(flat(v.render(20))).not.toContain('l0')
+    v.handleInput(CTRL_U)
+    expect(flat(v.render(20))).toContain('l0')
+    v.handleInput(CTRL_D)
+    v.handleInput(PAGE_UP)
+    expect(flat(v.render(20))).toContain('l0')
+    v.handleInput(PAGE_DOWN)
+    expect(flat(v.render(20))).not.toContain('l0')
+  })
+
+  it('clamps at both ends', () => {
+    const v = wrap(many(50), 5)
+    v.render(20)
+    v.handleInput(UP)
+    expect(v.offset).toBe(0)
+    v.handleInput('G')
+    v.handleInput('j')
+    expect(v.offset).toBe(45)
+  })
+})
+
+describe('ScrollView input forwarding', () => {
+  it('forwards non-scroll input to the child', () => {
+    const received: string[] = []
+    const v = new ScrollView(makeTui(), theme, {
+      child: {
+        render: () => [],
+        invalidate: () => {},
+        handleInput: (d: string) => {
+          received.push(d)
+        },
+      },
+      viewportHeight: () => 5,
+    })
+    v.render(20)
+    v.handleInput('z')
+    v.handleInput('\r')
+    expect(received).toEqual(['z', '\r'])
+  })
+
+  it('keeps scroll keys for itself (not forwarded)', () => {
+    const received: string[] = []
+    const v = new ScrollView(makeTui(), theme, {
+      child: {
+        render: () => many(50),
+        invalidate: () => {},
+        handleInput: (d: string) => {
+          received.push(d)
+        },
+      },
+      viewportHeight: () => 5,
+    })
+    v.render(20)
+    v.handleInput('j')
+    v.handleInput('G')
+    expect(received).toEqual([])
+    expect(v.offset).toBe(45)
+  })
+})
+
+describe('ScrollView auto-follow', () => {
+  it('pins to the latest content while following', () => {
+    const content = ['a', 'b']
+    const v = new ScrollView(makeTui(), theme, {
+      child: { render: () => content, invalidate: () => {} },
+      viewportHeight: () => 5,
+      autoFollow: true,
+    })
+    v.render(20)
+    content.splice(0, content.length, ...many(50))
+    expect(flat(v.render(20))).toContain('l49')
+  })
+
+  it('stops following once you scroll above the bottom', () => {
+    const content = many(50)
+    const v = new ScrollView(makeTui(), theme, {
+      child: { render: () => content, invalidate: () => {} },
+      viewportHeight: () => 5,
+      autoFollow: true,
+    })
+    v.render(20)
+    v.handleInput(UP)
+    v.render(20)
+    content.splice(0, content.length, ...many(80))
+    expect(flat(v.render(20))).not.toContain('l79')
+  })
+})

package/src/ui/scroll-view.ts

@@ -0,0 +1,155 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import type { Component, TUI } from '@earendil-works/pi-tui'
+import { Key, matchesKey } from '@earendil-works/pi-tui'
+
+import { truncateText } from '../utils/truncate.js'
+
+export interface ScrollViewOptions {
+  /** The content this view wraps: any pi-tui Component (Markdown, Container, …). */
+  readonly child: Component
+  /** Rows available to the scroll area — the parent reserves chrome outside. */
+  readonly viewportHeight: () => number
+  /** Pin to new content as it arrives (streaming viewers). Default false. */
+  readonly autoFollow?: boolean
+}
+
+/**
+ * A scrollable viewport that wraps a content source. Implements the pi-tui
+ * `Component` interface: {@link ScrollView} owns the offset (with auto-follow),
+ * a proportional scrollbar, and the scroll keybindings, and renders nothing
+ * but the visible window of its child plus the bar. Headers, footers, choice
+ * lists and hints live outside, in the parent component that holds this one.
+ */
+export class ScrollView implements Component {
+  #offset = 0
+  #autoFollow: boolean
+  #total = 0
+  #viewportHeight = 0
+  readonly #tui: TUI
+  readonly #theme: Theme
+  readonly #child: Component
+  readonly #viewportHeightFor: () => number
+
+  constructor(tui: TUI, theme: Theme, options: ScrollViewOptions) {
+    this.#tui = tui
+    this.#theme = theme
+    this.#child = options.child
+    this.#viewportHeightFor = options.viewportHeight
+    this.#autoFollow = options.autoFollow ?? false
+  }
+
+  /** Top-most visible line after the last render. */
+  get offset(): number {
+    return this.#offset
+  }
+
+  /** Total content lines after the last render. */
+  get total(): number {
+    return this.#total
+  }
+
+  /** Viewport height used by the last render. */
+  get viewportHeight(): number {
+    return this.#viewportHeight
+  }
+
+  render(width: number): string[] {
+    if (width < 4) return []
+    const contentWidth = Math.max(1, width - 2)
+    const lines = this.#child.render(contentWidth)
+    this.#total = lines.length
+    this.#viewportHeight = Math.max(0, this.#viewportHeightFor())
+    this.#offset = this.#clamp(this.#offset)
+    if (this.#autoFollow) this.#offset = this.#maxOffset
+
+    const rows = Math.min(
+      this.#viewportHeight,
+      Math.max(0, lines.length - this.#offset),
+    )
+    const bar = this.#column(rows)
+    const track = this.#theme.fg('dim', '│')
+    const out: string[] = []
+    for (let i = 0; i < rows; i++) {
+      const line = truncateText(
+        lines[this.#offset + i] ?? '',
+        contentWidth,
+        undefined,
+        true,
+      )
+      out.push(`${line} ${bar[i] ?? track}`)
+    }
+    return out
+  }
+
+  handleInput(data: string): void {
+    if (this.#viewportHeight === 0) return // not laid out yet
+    const before = this.#offset
+    if (matchesKey(data, Key.up) || data === 'k') this.#moveTo(this.#offset - 1)
+    else if (matchesKey(data, Key.down) || data === 'j')
+      this.#moveTo(this.#offset + 1)
+    else if (
+      data === 'u' ||
+      matchesKey(data, Key.ctrl('u')) ||
+      matchesKey(data, Key.pageUp)
+    )
+      this.#moveTo(this.#offset - this.#viewportHeight)
+    else if (
+      data === 'd' ||
+      data === ' ' ||
+      matchesKey(data, Key.ctrl('d')) ||
+      matchesKey(data, Key.pageDown)
+    )
+      this.#moveTo(this.#offset + this.#viewportHeight)
+    else if (data === 'g' || matchesKey(data, Key.home)) this.#moveTo(0)
+    else if (data === 'G' || matchesKey(data, Key.end))
+      this.#moveTo(this.#maxOffset)
+    else if (this.#child.handleInput) {
+      // non-scroll input goes to the wrapped child (it may be interactive)
+      this.#child.handleInput(data)
+      this.#tui.requestRender()
+      return
+    }
+    if (this.#offset !== before) this.#tui.requestRender()
+  }
+
+  invalidate(): void {
+    this.#child.invalidate()
+  }
+
+  get #maxOffset(): number {
+    return Math.max(0, this.#total - this.#viewportHeight)
+  }
+
+  #clamp(value: number): number {
+    return Math.max(0, Math.min(value, this.#maxOffset))
+  }
+
+  #moveTo(value: number): void {
+    this.#offset = this.#clamp(value)
+    this.#autoFollow = this.#offset >= this.#maxOffset
+  }
+
+  #column(rows: number): string[] {
+    const max = this.#maxOffset
+    const size =
+      max > 0
+        ? Math.max(
+            1,
+            Math.round(
+              (this.#viewportHeight / this.#total) * this.#viewportHeight,
+            ),
+          )
+        : 0
+    const start =
+      max > 0
+        ? Math.round((this.#offset / max) * (this.#viewportHeight - size))
+        : 0
+    const thumb = this.#theme.fg('muted', '█')
+    const track = this.#theme.fg('dim', '│')
+    const column: string[] = []
+    for (let i = 0; i < rows; i++) {
+      column.push(i >= start && i < start + size ? thumb : track)
+    }
+    return column
+  }
+}

package/src/utils/format.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+
+import { truncateToBytes } from './format.js'
+
+describe('truncateToBytes', () => {
+  const defaultSuffix = '\n\n[Output truncated.]'
+
+  it('returns original text when under byte limit', () => {
+    const text = 'Hello world'
+    const result = truncateToBytes(text, 100)
+    expect(result).toBe(text)
+  })
+
+  it('truncates text when over byte limit and adds suffix', () => {
+    const text = 'a'.repeat(100)
+    const result = truncateToBytes(text, 50)
+    const suffixBytes = Buffer.byteLength(defaultSuffix, 'utf8')
+    const budget = Math.max(0, 50 - suffixBytes)
+    expect(result.length).toBe(budget + defaultSuffix.length)
+    expect(result.endsWith(defaultSuffix)).toBe(true)
+  })
+
+  it('truncates text to budget bytes when limit is small', () => {
+    const text = 'Hello world'
+    const maxBytes = 5
+    const suffixBytes = Buffer.byteLength(defaultSuffix, 'utf8')
+    const budget = Math.max(0, maxBytes - suffixBytes)
+    const result = truncateToBytes(text, maxBytes)
+    expect(result.length).toBe(budget + defaultSuffix.length)
+    expect(result.endsWith(defaultSuffix)).toBe(true)
+  })
+
+  it('handles multibyte characters correctly', () => {
+    const text = '你好世界你好世界你好世界你好世界你好世界'
+    const maxBytes = 30
+    const suffixBytes = Buffer.byteLength(defaultSuffix, 'utf8')
+    const result = truncateToBytes(text, maxBytes)
+    expect(result.endsWith(defaultSuffix)).toBe(true)
+    const headBytes = Buffer.byteLength(
+      result.slice(0, result.length - defaultSuffix.length),
+      'utf8',
+    )
+    expect(headBytes).toBe(Math.max(0, maxBytes - suffixBytes))
+  })
+
+  it('handles mixed ASCII and multibyte characters', () => {
+    const text = 'Hello你好World你好Test你好Data'
+    const maxBytes = 20
+    const suffixBytes = Buffer.byteLength(defaultSuffix, 'utf8')
+    const result = truncateToBytes(text, maxBytes)
+    expect(result.endsWith(defaultSuffix)).toBe(true)
+    const headBytes = Buffer.byteLength(
+      result.slice(0, result.length - defaultSuffix.length),
+      'utf8',
+    )
+    expect(headBytes).toBe(Math.max(0, maxBytes - suffixBytes))
+  })
+
+  it('uses custom suffix', () => {
+    const text = 'a'.repeat(100)
+    const customSuffix = ' [truncated]'
+    const result = truncateToBytes(text, 50, customSuffix)
+    expect(result).toContain(customSuffix)
+    expect(result).not.toContain(defaultSuffix)
+  })
+
+  it('handles empty string', () => {
+    expect(truncateToBytes('', 100)).toBe('')
+  })
+
+  it('handles budget exactly zero when suffix bytes exceed limit', () => {
+    const text = 'Hello'
+    const result = truncateToBytes(text, 1)
+    expect(result).toBe(defaultSuffix)
+  })
+})

package/src/utils/format.ts

@@ -0,0 +1,67 @@
+import type { ContextUsage } from '@earendil-works/pi-coding-agent'
+import { visibleWidth } from '@earendil-works/pi-tui'
+
+import { truncateText } from './truncate.js'
+
+export function strInline(s: string): string {
+  return s.split('\n').join('⮒ ')
+}
+
+export function rightAlign(left: string, right: string, width: number): string {
+  const rightW = visibleWidth(right)
+  const maxLeft = Math.max(0, width - rightW - 1)
+  const leftClamped = truncateText(left, maxLeft)
+  const gap = Math.max(1, width - visibleWidth(leftClamped) - rightW)
+  return truncateText(leftClamped + ' '.repeat(gap) + right, width)
+}
+
+export function formatTokens(count: number): string {
+  if (count < 1000) return count.toString()
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`
+  if (count < 1000000) return `${Math.round(count / 1000)}k`
+  if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`
+  return `${Math.round(count / 1000000)}M`
+}
+
+export function formatContextUsage(usage: ContextUsage | undefined): string {
+  if (
+    usage === undefined ||
+    usage.contextWindow === 0 ||
+    usage.tokens === null
+  ) {
+    return '?'
+  }
+  return `${formatTokens(usage.tokens)}/${formatTokens(usage.contextWindow)}`
+}
+
+export function formatElapsed(item: {
+  startedAt: number
+  completedAt?: number
+}): string {
+  const end = item.completedAt ?? Date.now()
+  const ms = Math.max(0, end - item.startedAt)
+  return formatElapsedMs(ms)
+}
+
+export function formatElapsedMs(ms: number): string {
+  const seconds = Math.floor(ms / 1000)
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  const remainingSeconds = seconds % 60
+  if (minutes < 60) return `${minutes}m${remainingSeconds}s`
+  const hours = Math.floor(minutes / 60)
+  const remainingMinutes = minutes % 60
+  return `${hours}h${remainingMinutes}m${remainingSeconds}s`
+}
+
+export function truncateToBytes(
+  text: string,
+  maxBytes: number,
+  suffix = '\n\n[Output truncated.]',
+): string {
+  if (Buffer.byteLength(text, 'utf8') <= maxBytes) return text
+  const suffixBytes = Buffer.byteLength(suffix, 'utf8')
+  const budget = Math.max(0, maxBytes - suffixBytes)
+  const head = Buffer.from(text, 'utf8').subarray(0, budget).toString('utf8')
+  return `${head}${suffix}`
+}

package/src/utils/fs.ts

@@ -0,0 +1,9 @@
+import { readFile } from 'node:fs/promises'
+
+export async function readOptional(path: string): Promise<string | undefined> {
+  try {
+    return (await readFile(path, 'utf8')).trim()
+  } catch {
+    return undefined
+  }
+}