sources

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { SourcesView } from '../types'
5import { fullPath, grouped, isAllowed, named, normal, parseRequest, reached, refusal, shown, USAGE, withSource } from './paths'
6import type { Reach } from './paths'
7
8const PANE = 'sources'
9const TITLE = 'Sources'
10/** The settings dialog's command and its gear's key (ADR-0007). mod-settings takes the press; the gear's onPress is the fallback. */
11const SETTINGS = 'mod-settings'
12/** The most files a group lists before it counts the rest. */
13const MOST_ROWS = 8
14
15const EMPTY: SourcesView = { sources: [], isLocked: false, allowed: [] }
16const view = atom({ plugin: 'sources', key: 'view' } as const, EMPTY)
17
18// Each mod carries its own copy (ADR-0001): a session shown on no surface is headless.
19async function isShown($: EngineInterface): Promise<boolean> {
20  return (await $.session.surfaces()).length > 0
21}
22
23function report($: EngineInterface): (error: unknown) => void {
24  return error => $.ui.toast(`Sources: ${error instanceof Error ? error.message : String(error)}`)
25}
26
27/** Where a full path lands, symlinks and junctions followed, when it exists and can be looked at; else the path as folded. */
28async function landed($: EngineInterface, path: string): Promise<string> {
29  const stat = await $.fs.stat(path, { resolve: true }).catch(() => undefined)
30  return normal(stat?.realPath ?? path)
31}
32
33/**
34 * The first place the call reaches outside the project folder and the allowed folders, or undefined when
35 * all are inside. Each place is compared where it lands; each folder both as folded and where it lands,
36 * so a place not there yet still counts as inside a folder that is itself a link.
37 */
38async function outside($: EngineInterface, reach: Reach, folders: readonly string[]): Promise<string | undefined> {
39  if (reach.kind === 'unplaced') return reach.spelling
40  const bounds = (await Promise.all(folders.map(async folder => [normal(folder), await landed($, normal(folder))]))).flat()
41  for (const place of reach.places) {
42    const real = await landed($, place)
43    if (!isAllowed(real, bounds)) return real
44  }
45  return undefined
46}
47
48/** Whether mod-settings is installed: the gear shows only then. A command list that cannot be read shows none. */
49async function isSettingsInstalled($: EngineInterface): Promise<boolean> {
50  return (await $.command.list().catch(() => [])).some(command => command.name === SETTINGS)
51}
52
53export const register: Register = on => {
54  on('session.start', async ($, e, next) => {
55    const started = await next(e)
56    await $.command.register({ name: 'sources', description: 'Open the Sources pane: the files read this session. allow <path> lets reads into a folder while the lock is on' })
57    return started
58  })
59
60  // Matched by pattern: which read tools a session has depends on the machine.
61  on('tool.call', { tool: /^(Read|Grep|Glob)$/ }, async ($, e, next) => {
62    // Quiet in a headless session: nothing is refused and nothing is kept.
63    if (!(await isShown($).catch(() => false))) return next(e)
64    const cwd = await $.session.cwd()
65    const path = fullPath(named(e), cwd)
66    const current = await read($, view)
67    if (current.isLocked) {
68      const refused = await outside($, reached(e.tool, e, cwd), [cwd, ...current.allowed])
69      if (refused !== undefined) return { deny: refusal(refused) }
70    }
71    const called = await next(e)
72    if (called.deny === undefined) {
73      const at = await $.clock.now()
74      await update($, view, (held): SourcesView => ({ ...held, sources: withSource(held.sources, path, at) })).catch(() => undefined)
75    }
76    return called
77  })
78
79  on('command.run', { command: 'sources' }, async ($, e) => {
80    const request = parseRequest(e.args)
81    if (request.kind === 'usage') return { text: USAGE }
82    if (request.kind === 'allowed') {
83      const { allowed } = await read($, view)
84      return { text: allowed.length === 0 ? 'No folder outside the project folder is allowed.' : `Allowed besides the project folder:\n${allowed.join('\n')}` }
85    }
86    if (request.kind === 'allow') {
87      const folder = fullPath(request.path, await $.session.cwd())
88      await update($, view, (held): SourcesView => ({
89        ...held,
90        allowed: held.allowed.some(each => each.toLowerCase() === folder.toLowerCase()) ? held.allowed : [...held.allowed, folder],
91      }))
92      return { text: `Reads are allowed in ${folder} for this session.` }
93    }
94    // Asked, the pane comes in front of the others and takes the keyboard, which Esc hands back.
95    await $.ui.open({ id: PANE, title: TITLE, focus: true })
96    return { text: 'Sources pane opened.' }
97  })
98
99  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
100    const { Box, Text, Button } = $.ui.resolve(e)
101    const hasSettings = await isSettingsInstalled($)
102    const current = await read($, view)
103    const cwd = normal(await $.session.cwd())
104    const width = Math.max(16, e.props.bodyColumns)
105    const room = width - 3
106    const groups = grouped(current.sources, cwd)
107
108    return (
109      <Box flexDirection="column" width={width}>
110        <Box flexDirection="row" justifyContent="space-between">
111          <Text bold={current.isLocked} color={current.isLocked ? 'yellow' : undefined}>
112            {current.isLocked ? 'Reads: this folder only' : 'Reads: anywhere'}
113          </Text>
114          <Box flexDirection="row" columnGap={1}>
115            <Button
116              key="lock"
117              plain
118              dimColor
119              hotkey="l"
120              label={current.isLocked ? 'unlock' : 'lock'}
121              onPress={() => void update($, view, (held): SourcesView => ({ ...held, isLocked: !held.isLocked })).catch(report($))}
122            />
123            {hasSettings && <Button key={SETTINGS} plain dimColor label="⚙️" onPress={() => void $.command.run({ command: SETTINGS }).catch(report($))} />}
124          </Box>
125        </Box>
126        {current.isLocked && current.allowed.map((folder, index) => (
127          <Text key={`allowed-${index}`} dimColor wrap="truncate-start">{`  also ${folder}`}</Text>
128        ))}
129        {groups.length === 0 && <Text dimColor wrap="wrap">Nothing read yet this session.</Text>}
130        {groups.map((group, at) => (
131          <Box key={`group-${at}`} flexDirection="column" marginTop={1}>
132            <Text key={`group-title-${at}`} bold wrap="truncate-start">{`${group.label}  ${group.sources.length}`}</Text>
133            {group.sources.slice(0, MOST_ROWS).map((source, index) => (
134              <Text key={`source-${at}-${index}`} dimColor>{`  ${shown(source.path, group.isProject ? cwd : group.label, room)}`}</Text>
135            ))}
136            {group.sources.length > MOST_ROWS && <Text dimColor>{`  +${group.sources.length - MOST_ROWS} more`}</Text>}
137          </Box>
138        ))}
139      </Box>
140    )
141  })
142}
143

1import type { Source } from '../types'
2
3/** The most sources the pane keeps. */
4export const MOST_SOURCES = 300
5
6export type Group = { label: string; isProject: boolean; sources: Source[] }
7
8/** What `/sources` was asked to do, read from everything typed after the name. */
9export type Request = { kind: 'open' } | { kind: 'allowed' } | { kind: 'allow'; path: string } | { kind: 'usage' }
10
11export const USAGE = 'Usage: /sources, /sources allow, /sources allow <path>'
12
13/**
14 * The path with forward slashes, its `.` and `..` segments folded and no trailing slash, so two spellings
15 * of a place compare equal. A `..` at a drive, share or root stays there, as the file system has it;
16 * one at the start of a relative path is kept.
17 */
18export function normal(path: string): string {
19  const slashed = path.replace(/\\/g, '/')
20  const [, head = '', rest = ''] = /^(\/\/[^/]+\/[^/]+|[A-Za-z]:(?=\/|$)|\/?)(.*)$/.exec(slashed) ?? []
21  const parts: string[] = []
22  for (const part of rest.split('/')) {
23    if (part === '' || part === '.') continue
24    if (part !== '..') parts.push(part)
25    else if (parts.length > 0 && parts[parts.length - 1] !== '..') parts.pop()
26    else if (head === '') parts.push(part)
27  }
28  const body = parts.join('/')
29  if (head === '') return body === '' ? '.' : body
30  // A bare drive or the root keeps its slash; a share has none of its own.
31  if (head.startsWith('//')) return body === '' ? head : `${head}/${body}`
32  return head === '/' ? `/${body}` : `${head}/${body}`
33}
34
35function isAbsolute(path: string): boolean {
36  return /^([A-Za-z]:[\\/]|[\\/])/.test(path)
37}
38
39/**
40 * Whether the tool reads the path from somewhere its spelling does not say: `~` is the home folder to it,
41 * and `D:x` is relative to that drive's own current folder.
42 */
43function isUnplaceable(path: string): boolean {
44  return /^~\w*(?:[\\/]|$)/.test(path) || /^[A-Za-z]:(?![\\/])/.test(path)
45}
46
47/** The full path of what a tool named, which may be given from the project folder, with its `.` and `..` folded. */
48export function fullPath(path: string, cwd: string): string {
49  return normal(isAbsolute(path) ? path : `${cwd}/${path}`)
50}
51
52/** Whether `path` is the folder or lies inside it, once both are folded. Letter case is passed over, as Windows does. */
53export function isUnder(path: string, folder: string): boolean {
54  const inner = normal(path).toLowerCase()
55  const outer = normal(folder).toLowerCase()
56  return inner === outer || inner.startsWith(outer.endsWith('/') ? outer : `${outer}/`)
57}
58
59/** Whether `path` is one of the folders or lies inside one. */
60export function isAllowed(path: string, folders: readonly string[]): boolean {
61  return folders.some(folder => isUnder(path, folder))
62}
63
64/** What a read tool's call names: a file for Read, the folder searched for Grep and Glob (the project folder when none is given). */
65export function named(input: object): string {
66  const { file_path: file, path } = input as { file_path?: unknown; path?: unknown }
67  if (typeof file === 'string') return file
68  return typeof path === 'string' ? path : '.'
69}
70
71/** Where a read tool's call reaches: full paths, or the spelling no folder bounds. */
72export type Reach = { kind: 'places'; places: string[] } | { kind: 'unplaced'; spelling: string }
73
74/**
75 * The places a read tool's call reaches, each a full path: the file Read names; for Grep and Glob, the folder
76 * searched and, for Glob's `pattern` or Grep's `glob`, the folder before its first wildcard (the whole
77 * pattern when it has none). Grep's own
78 * `pattern` is a regex, not a path. A spelling no folder bounds is given back instead: `~`, `D:x`, or a `..`
79 * after a wildcard or among braces.
80 */
81export function reached(tool: string, input: object, cwd: string): Reach {
82  const { pattern, glob } = input as { pattern?: unknown; glob?: unknown }
83  const filter = tool === 'Glob' ? pattern : tool === 'Grep' ? glob : undefined
84  const spellings = [named(input), ...(typeof filter === 'string' ? [filter] : [])]
85  const unplaced = spellings.find(isUnplaceable)
86  if (unplaced !== undefined) return { kind: 'unplaced', spelling: unplaced }
87  const [searched = '.', ...filters] = spellings
88  const folder = fullPath(searched, cwd)
89  const places = [folder]
90  for (const each of filters) {
91    const slashed = each.replace(/\\/g, '/')
92    const parts = slashed.split('/')
93    const wild = parts.findIndex(part => /[*?[\]{}]/.test(part))
94    const literal = wild === -1 ? parts : parts.slice(0, wild)
95    if (wild !== -1 && parts.slice(wild).some(part => /(?:^|[{,])\.\.(?:$|[},])/.test(part))) return { kind: 'unplaced', spelling: each }
96    // A pattern that starts at the root keeps it.
97    places.push(fullPath(literal.join('/') || (slashed.startsWith('/') ? '/' : '.'), folder))
98  }
99  return { kind: 'places', places }
100}
101
102/** Where a path outside the project folder came from: its drive or share with its first two folders. */
103export function rootOf(path: string): string {
104  const clean = normal(path)
105  const [, head = '', rest = ''] = /^([A-Za-z]:|\/\/[^/]+\/[^/]+|)\/?(.*)$/.exec(clean) ?? []
106  // The last part is the file itself.
107  const folders = rest.split('/').slice(0, -1).slice(0, 2)
108  return `${head}/${folders.join('/')}`.replace(/\/$/, '') || '/'
109}
110
111/** The sources with `path` newest, each path once, within the bound. */
112export function withSource(sources: readonly Source[], path: string, at: number): Source[] {
113  const key = path.toLowerCase()
114  return [{ path, at }, ...sources.filter(held => held.path.toLowerCase() !== key)].slice(0, MOST_SOURCES)
115}
116
117/** The project folder's group first, then each other root in the order it was last read. */
118export function grouped(sources: readonly Source[], cwd: string): Group[] {
119  const groups = new Map<string, Group>()
120  const project: Group = { label: 'This folder', isProject: true, sources: [] }
121  for (const source of sources) {
122    if (isUnder(source.path, cwd)) {
123      project.sources.push(source)
124      continue
125    }
126    const label = rootOf(source.path)
127    const group = groups.get(label.toLowerCase()) ?? { label, isProject: false, sources: [] }
128    group.sources.push(source)
129    groups.set(label.toLowerCase(), group)
130  }
131  return [...(project.sources.length > 0 ? [project] : []), ...groups.values()]
132}
133
134/** The path as a group's line shows it: without the group's own folder, cut from the front to fit. */
135export function shown(path: string, folder: string, max: number): string {
136  const inner = isUnder(path, folder) && normal(path).length > normal(folder).length ? normal(path).slice(normal(folder).replace(/\/$/, '').length + 1) : normal(path)
137  const chars = Array.from(inner)
138  return chars.length <= max ? inner : `…${chars.slice(chars.length - Math.max(1, max - 1)).join('')}`
139}
140
141export function parseRequest(args: string): Request {
142  const trimmed = args.trim()
143  if (trimmed === '') return { kind: 'open' }
144  const [, verb = '', rest = ''] = /^(\S+)\s*(.*)$/.exec(trimmed) ?? []
145  if (verb !== 'allow') return { kind: 'usage' }
146  const path = (/^"(.*)"$/.exec(rest) ?? /^'(.*)'$/.exec(rest))?.[1] ?? rest
147  return path === '' ? { kind: 'allowed' } : { kind: 'allow', path }
148}
149
150/** Why a read outside the allowed folders is refused, for the model to pass on. */
151export function refusal(path: string): string {
152  return `sources: reads are kept to the project folder while the lock is on, and ${path} is outside it. The person can allow a folder with /sources allow <path>, or turn the lock off with l in the Sources pane.`
153}
154

1/** One file read or folder searched: its full path with forward slashes, and when it was last read. */
2export type Source = { path: string; at: number }
3
4export type SourcesView = {
5  /** Newest first, each path once. */
6  sources: Source[]
7  /** True while reads are kept to the project folder and the allowed folders. */
8  isLocked: boolean
9  /** Folders outside the project folder that the person allowed for this session. */
10  allowed: string[]
11}
12
13declare module 'claude-code' {
14  interface PluginState {
15    sources: { view: SourcesView }
16  }
17}
18