outputs

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { OutputFile, OutputsView } from '../types'
5import { ago, fit, isOutput, isScanned, joined, MOST_DEPTH, MOST_FOLDERS, nativePath, newestFirst, openers, outputFile, windowsFolder } from './files'
6
7const PANE = 'outputs'
8const TITLE = 'Outputs'
9/** The settings dialog's command and its gear's key (ADR-0007). mod-settings takes the press; the gear's onPress is the fallback. */
10const SETTINGS = 'mod-settings'
11/** A scan after a tool call is skipped when the last one was this recent. */
12const SCAN_GAP_MS = 2_000
13/** The most rows of each kind the pane draws. */
14const MOST_ROWS = 20
15
16const EMPTY: OutputsView = { since: 0, files: [], isCut: false, isOtherOpen: false, error: '' }
17const view = atom({ plugin: 'outputs', key: 'view' } as const, EMPTY)
18
19// Dies with the module on a reload, which only brings the next scan forward.
20let lastScanAt = 0
21
22// Each mod carries its own copy (ADR-0001): a session shown on no surface is headless.
23async function isShown($: EngineInterface): Promise<boolean> {
24  return (await $.session.surfaces()).length > 0
25}
26
27function report($: EngineInterface): (error: unknown) => void {
28  return error => $.ui.toast(`Outputs: ${error instanceof Error ? error.message : String(error)}`)
29}
30
31async function isWindows($: EngineInterface): Promise<boolean> {
32  return (await $.env.get('OS')) === 'Windows_NT'
33}
34
35/** Lists the files under the project folder changed since the session began, folder by folder, within a bound. */
36async function scan($: EngineInterface): Promise<void> {
37  const { since } = await read($, view)
38  if (since === 0) return
39  lastScanAt = await $.clock.now()
40  const root = await $.session.cwd()
41  const found: OutputFile[] = []
42  const waiting: { folder: string; depth: number }[] = [{ folder: '', depth: 0 }]
43  let listed = 0
44  let error = ''
45  let isTooDeep = false
46  for (let next = waiting.shift(); next !== undefined && listed < MOST_FOLDERS; next = waiting.shift()) {
47    const { folder, depth } = next
48    listed += 1
49    const entries = await $.fs.list(folder === '' ? root : `${root}/${folder}`).catch((caught: unknown) => {
50      // The project folder itself unreadable is worth saying; one folder inside it is passed over.
51      if (folder === '') error = `Could not list the project folder: ${caught instanceof Error ? caught.message : String(caught)}`
52      return []
53    })
54    for (const entry of entries) {
55      if (isOutput(entry, since)) found.push(outputFile(root, folder, entry))
56      else if (isScanned(entry)) {
57        if (depth < MOST_DEPTH) waiting.push({ folder: joined(folder, entry.name), depth: depth + 1 })
58        else isTooDeep = true
59      }
60    }
61  }
62  const isCut = waiting.length > 0 || isTooDeep
63  await update($, view, (current): OutputsView => ({ ...current, files: newestFirst(found), isCut, error }))
64}
65
66/**
67 * Opens the file with its own application, or says it could not: when the file is gone since the scan, or
68 * when no opener both started and, where its exit code is trusted, exited 0.
69 */
70async function openFile($: EngineInterface, file: OutputFile): Promise<void> {
71  // A network location is not looked at; the openers try it as they would any file.
72  if (await $.fs.exists(file.path).catch(() => true)) {
73    const windows = (await isWindows($)) ? windowsFolder(await $.env.get('SystemRoot')) : undefined
74    for (const { argv, isExitTrusted } of openers(file.path, windows)) {
75      const run = await $.process.run(argv).catch(() => undefined)
76      if (run !== undefined && (run.exitCode === 0 || !isExitTrusted)) return
77    }
78  }
79  $.ui.toast(`Outputs: could not open ${file.name}`)
80}
81
82async function copyPath($: EngineInterface, file: OutputFile): Promise<void> {
83  const copied = await $.ui.copy({ text: nativePath(file.path, await isWindows($)) })
84  $.ui.toast(copied.isCopied ? `Copied the path of ${file.name}.` : `Could not copy: ${copied.reason}`)
85}
86
87/** Whether mod-settings is installed: the gear shows only then. A command list that cannot be read shows none. */
88async function isSettingsInstalled($: EngineInterface): Promise<boolean> {
89  return (await $.command.list().catch(() => [])).some(command => command.name === SETTINGS)
90}
91
92export const register: Register = on => {
93  on('session.start', async ($, e, next) => {
94    const started = await next(e)
95    await $.command.register({ name: 'outputs', description: 'Open the Outputs pane: the files this session has made or changed' })
96    // A reload starts the module again within one session: the session's own start time stands.
97    const now = await $.clock.now()
98    await update($, view, (current): OutputsView => (current.since === 0 ? { ...current, since: now } : current))
99    return started
100  })
101
102  // The tools that can write a file; a shell tool's name depends on the machine.
103  on('tool.call', { tool: /^(Write|Edit|NotebookEdit|Bash|PowerShell)$/ }, async ($, e, next) => {
104    const called = await next(e)
105    // Awaited: work left running when a hook returns is dropped with its dispatch.
106    const isDue = (await $.clock.now().catch(() => 0)) - lastScanAt >= SCAN_GAP_MS
107    if (isDue && (await isShown($).catch(() => false))) await scan($).catch(() => undefined)
108    return called
109  })
110
111  on('turn.complete', async ($, e, next) => {
112    const done = await next(e)
113    if (e.agentId === undefined && (await isShown($).catch(() => false))) await scan($).catch(() => undefined)
114    return done
115  })
116
117  on('command.run', { command: 'outputs' }, async $ => {
118    // Asked, the pane comes in front of the others and takes the keyboard, which Esc hands back.
119    await $.ui.open({ id: PANE, title: TITLE, focus: true })
120    await scan($).catch(report($))
121    return { text: 'Outputs pane opened.' }
122  })
123
124  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
125    const { Box, Text, Button } = $.ui.resolve(e)
126    const hasSettings = await isSettingsInstalled($)
127    const current = await read($, view)
128    const now = await $.clock.now()
129    const width = Math.max(16, e.props.bodyColumns)
130    const room = width - 1
131    const documents = current.files.filter(file => file.isDocument)
132    const others = current.files.filter(file => !file.isDocument)
133
134    const rows = (files: readonly OutputFile[], prefix: string) =>
135      files.slice(0, MOST_ROWS).map((file, index) => (
136        <Box key={`${prefix}-row-${index}`} flexDirection="column">
137          <Button key={`${prefix}-open-${index}`} plain label={fit(file.name, room)} onPress={() => void openFile($, file).catch(report($))} />
138          <Box flexDirection="row" columnGap={2}>
139            <Text dimColor wrap="truncate-end">  {file.folder === '' ? '' : `${fit(file.folder, Math.max(8, room - 24))} · `}{ago(now - file.mtimeMs)}</Text>
140            <Button
141              key={`${prefix}-copy-${index}`}
142              plain
143              dimColor
144              hotkey={prefix === 'doc' && index === 0 ? 'c' : undefined}
145              label="copy path"
146              onPress={() => void copyPath($, file).catch(report($))}
147            />
148          </Box>
149        </Box>
150      ))
151
152    return (
153      <Box flexDirection="column" width={width}>
154        <Box flexDirection="row" justifyContent="space-between">
155          <Text bold>{TITLE}</Text>
156          <Box flexDirection="row" columnGap={1}>
157            <Button key="refresh" plain dimColor hotkey="r" label="refresh" onPress={() => void scan($).catch(report($))} />
158            {hasSettings && <Button key={SETTINGS} plain dimColor label="⚙️" onPress={() => void $.command.run({ command: SETTINGS }).catch(report($))} />}
159          </Box>
160        </Box>
161        {current.error !== '' && <Text color="red" wrap="wrap">{current.error}</Text>}
162        {current.files.length === 0 && current.error === '' && (
163          <Text dimColor wrap="wrap">Nothing made or changed in this folder since the session began.</Text>
164        )}
165        {rows(documents, 'doc')}
166        {documents.length > MOST_ROWS && <Text dimColor>{`+${documents.length - MOST_ROWS} more`}</Text>}
167        {others.length > 0 && (
168          <Box flexDirection="column" marginTop={documents.length > 0 ? 1 : 0}>
169            <Button
170              key="other"
171              plain
172              dimColor
173              hotkey="o"
174              label={`${others.length} other file${others.length === 1 ? '' : 's'} ${current.isOtherOpen ? '(hide)' : '(show)'}`}
175              onPress={() => void update($, view, (held): OutputsView => ({ ...held, isOtherOpen: !held.isOtherOpen })).catch(report($))}
176            />
177            {current.isOtherOpen && rows(others, 'other')}
178          </Box>
179        )}
180        {current.isCut && <Text dimColor wrap="wrap">This folder is large: only part of it was looked through.</Text>}
181      </Box>
182    )
183  })
184}
185

1import type { OutputFile } from '../types'
2
3/** One entry of a folder, as `$.fs.list` gives it. */
4export type Entry = { name: string; kind: 'file' | 'dir' | 'other'; mtimeMs: number; isLink: boolean }
5
6/** The most folders one scan lists, so a huge project folder cannot stall the session. */
7export const MOST_FOLDERS = 300
8export const MOST_DEPTH = 6
9/** The most files the pane keeps. */
10export const MOST_FILES = 60
11
12const DOCUMENTS = new Set(['docx', 'doc', 'docm', 'dotx', 'xlsx', 'xlsm', 'xls', 'pptx', 'ppt', 'pdf', 'md', 'html', 'htm', 'txt'])
13const SKIPPED_FOLDERS = new Set(['node_modules', '__pycache__', 'venv'])
14
15export function isDocument(name: string): boolean {
16  return DOCUMENTS.has(/\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase() ?? '')
17}
18
19/** Whether a scan goes into the folder: not a hidden one (`.git`), nor one of dependencies. */
20export function isScanned(entry: Entry): boolean {
21  return entry.kind === 'dir' && !entry.isLink && !entry.name.startsWith('.') && !SKIPPED_FOLDERS.has(entry.name)
22}
23
24/** Whether the entry is a file to list: changed since `since`, and not the lock file Office leaves beside an open one. */
25export function isOutput(entry: Entry, since: number): boolean {
26  return entry.kind === 'file' && entry.mtimeMs >= since && !entry.name.startsWith('~$')
27}
28
29export function joined(folder: string, name: string): string {
30  return folder === '' ? name : `${folder}/${name}`
31}
32
33/** The file as the pane keeps it, from its folder under the project folder `root`. */
34export function outputFile(root: string, folder: string, entry: Entry): OutputFile {
35  const base = root.replace(/[\\/]+$/, '')
36  return { path: `${base}/${joined(folder, entry.name)}`, name: entry.name, folder, mtimeMs: entry.mtimeMs, isDocument: isDocument(entry.name) }
37}
38
39/** Newest first, the first `MOST_FILES`. */
40export function newestFirst(files: readonly OutputFile[]): OutputFile[] {
41  return [...files].sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, MOST_FILES)
42}
43
44/** A process that opens a file with its own application, and whether its exit code tells an open from a failure. */
45export type Opener = { argv: string[]; isExitTrusted: boolean }
46
47/** The Windows folder from `SystemRoot`, taken only as an absolute folder on a drive; else `C:\Windows`. */
48export function windowsFolder(systemRoot: string | undefined): string {
49  const trimmed = (systemRoot ?? '').replace(/\\+$/, '')
50  return /^[A-Za-z]:\\[^"<>|?*]*$/.test(trimmed) ? trimmed : 'C:\\Windows'
51}
52
53/**
54 * The processes that open a file with its own application, tried in turn: on Windows (`windows`, its
55 * Windows folder) explorer.exe with the path as its one argument, so no shell reads the name; else `open`,
56 * then `xdg-open`. explorer.exe is named by its full path in the Windows folder, so no other explorer.exe
57 * on PATH runs in its place, and its exit code is not trusted: it can exit 1 when it opened the file.
58 */
59export function openers(path: string, windows: string | undefined): Opener[] {
60  if (windows !== undefined) return [{ argv: [`${windows}\\explorer.exe`, path.replace(/\//g, '\\')], isExitTrusted: false }]
61  return [
62    { argv: ['open', path], isExitTrusted: true },
63    { argv: ['xdg-open', path], isExitTrusted: true },
64  ]
65}
66
67/** The path as the clipboard takes it: with the machine's own separator. */
68export function nativePath(path: string, isWindows: boolean): string {
69  return isWindows ? path.replace(/\//g, '\\') : path
70}
71
72export function fit(line: string, max: number): string {
73  const chars = Array.from(line)
74  return chars.length <= max ? line : `${chars.slice(0, Math.max(1, max - 1)).join('')}…`
75}
76
77export function ago(ms: number): string {
78  const minutes = Math.floor(ms / 60_000)
79  if (minutes < 1) return 'just now'
80  return minutes < 60 ? `${minutes} min ago` : `${Math.floor(minutes / 60)} h ago`
81}
82

1/** One file made or changed since the session began. */
2export type OutputFile = {
3  /** The file's full path, as the application that opens it takes it. */
4  path: string
5  name: string
6  /** Its folder under the project folder, with forward slashes; '' for the project folder itself. */
7  folder: string
8  mtimeMs: number
9  /** True for what a person reads (Word, Excel, PowerPoint, PDF, Markdown, HTML, text); false for scripts, images and data. */
10  isDocument: boolean
11}
12
13export type OutputsView = {
14  /** When the session began: files changed before it are not listed. 0 until the first start. */
15  since: number
16  files: OutputFile[]
17  /** True when the scan stopped at its bound, so the list may be short. */
18  isCut: boolean
19  isOtherOpen: boolean
20  error: string
21}
22
23declare module 'claude-code' {
24  interface PluginState {
25    outputs: { view: OutputsView }
26  }
27}
28