where-am-i

1import type { EngineInterface, Register } from 'claude-code'
2
3import { describe, hostKind, hostLabel, movesCheckout, nudge, ownerRepo, parseRemotes, parseRules, shortPath } from './place'
4import type { Place, RepoInfo } from './place'
5
6const git = async ($: EngineInterface, cwd: string, args: string[]): Promise<string> => {
7  try {
8    const r = await $.process.run(['git', ...args], { cwd, timeoutMs: 5000 })
9    return r.exitCode === 0 ? r.stdout.trim() : ''
10  } catch {
11    return ''
12  }
13}
14
15async function readRepo($: EngineInterface, cwd: string): Promise<RepoInfo | undefined> {
16  const top = await git($, cwd, ['rev-parse', '--show-toplevel'])
17  if (!top) return undefined
18  const [branch, gitDir, common, remotesText] = await Promise.all([
19    git($, cwd, ['rev-parse', '--abbrev-ref', 'HEAD']),
20    git($, cwd, ['rev-parse', '--absolute-git-dir']),
21    git($, cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']),
22    git($, cwd, ['remote', '-v']),
23  ])
24  const remotes = parseRemotes(remotesText)
25  const origin = remotes.origin ? ownerRepo(remotes.origin) : null
26  const upstream = remotes.upstream ? ownerRepo(remotes.upstream) : null
27  return {
28    name: origin?.name ?? upstream?.name ?? top.split('/').pop() ?? top,
29    branch: branch === 'HEAD' ? 'detached' : branch || '?',
30    ...(origin ? { origin: origin.owner } : {}),
31    ...(upstream ? { upstream: upstream.owner } : {}),
32    isWorktree: !!gitDir && !!common && gitDir !== common,
33  }
34}
35
36// Kept per load: a reload re-reads the place at start.
37let place: Place | null = null
38let host = ''
39let kind: Place['kind'] = 'linux'
40let hostRules: [string, string][] = []
41const said = new Set<string>()
42
43async function refresh($: EngineInterface): Promise<Place> {
44  const cwd = await $.session.cwd()
45  const repo = await readRepo($, cwd)
46  place = { kind, host, label: hostLabel(kind, host, hostRules), cwd, ...(repo ? { repo } : {}) }
47  $.ui.status(describe(place))
48  return place
49}
50
51export const register: Register = (on, options) => {
52  hostRules = parseRules(options.hosts as readonly string[] | undefined)
53  const homes = parseRules(options.homes as readonly string[] | undefined)
54  const targets = ((options.containerTargets as readonly string[] | undefined) ?? []).map(String)
55
56  on('session.start', async ($, e, next) => {
57    const started = await next(e)
58    try {
59      const [uname, name, isDocker] = await Promise.all([
60        $.process.run(['uname', '-s'], { timeoutMs: 3000 }).then(r => r.stdout.trim()).catch(() => ''),
61        $.process.run(['hostname'], { timeoutMs: 3000 }).then(r => r.stdout.trim()).catch(() => ''),
62        $.fs.exists('/.dockerenv').catch(() => false),
63      ])
64      host = name || 'unknown'
65      kind = hostKind(uname, isDocker === true)
66      await $.command.register({ name: 'where', description: 'Show which machine, folder, repo, branch and remotes this session runs in' })
67      await refresh($)
68    } catch {
69      // The status line is a nicety; a failure here changes nothing else.
70    }
71    return started
72  })
73
74  on('command.run', { command: 'where' }, async $ => {
75    const p = await refresh($)
76    const cwd = p.cwd
77    const remotes = parseRemotes(await git($, cwd, ['remote', '-v']))
78    const lines = [
79      `host     ${p.label} (${p.host}, ${p.kind})`,
80      `folder   ${shortPath(cwd)}`,
81      ...(p.repo
82        ? [
83            `repo     ${p.repo.name} on ${p.repo.branch}${p.repo.isWorktree ? ' (a worktree)' : ''}`,
84            ...Object.entries(remotes).map(([n, u]) => `remote   ${n.padEnd(9)}${u}`),
85          ]
86        : ['repo     (not a git checkout)']),
87    ]
88    return { text: lines.join('\n') }
89  })
90
91  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
92    const r = await next(e)
93    const command = String(e.command ?? '')
94    if (movesCheckout(command)) await refresh($).catch(() => undefined)
95    if (!place || r.deny !== undefined) return r
96    const n = nudge(place, command, homes, targets)
97    // Once per kind per load: a nudge, not a nag.
98    if (!n || said.has(n.kind)) return r
99    said.add(n.kind)
100    $.ui.toast(n.note.replace(/^where-am-i: /, '').split('. ')[0] + '.')
101    return { ...r, context: [...(r.context ?? []), n.note] }
102  }).catch(($, e, next) => next(e))
103}
104

1// Pure logic for where-am-i: what kind of host this is, how to describe the
2// repo, and when a command deserves a nudge.
3
4export type HostKind = 'mac' | 'container' | 'linux'
5
6export type Place = {
7  kind: HostKind
8  host: string
9  label: string
10  cwd: string
11  repo?: RepoInfo
12}
13
14export type RepoInfo = {
15  /** Repo name, from origin's URL or the folder. */
16  name: string
17  branch: string
18  /** owner of origin (davidcoulson) and of upstream (tinkerologie), when present. */
19  origin?: string
20  upstream?: string
21  isWorktree: boolean
22}
23
24/** `pattern=value` lines into pairs; `*` and `?` globs. */
25export function parseRules(raw: readonly string[] | string | undefined): [string, string][] {
26  const list = Array.isArray(raw) ? raw : typeof raw === 'string' ? raw.split(/[,\n]/) : []
27  return list
28    .map(s => String(s).trim())
29    .filter(s => s.includes('='))
30    .map(s => [s.slice(0, s.indexOf('=')).trim(), s.slice(s.indexOf('=') + 1).trim()] as [string, string])
31    .filter(([p, v]) => p && v)
32}
33
34export const glob = (pattern: string, s: string): boolean =>
35  new RegExp('^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$', 'i').test(s)
36
37export function hostKind(uname: string, isDocker: boolean): HostKind {
38  if (/darwin/i.test(uname)) return 'mac'
39  return isDocker ? 'container' : 'linux'
40}
41
42export function hostLabel(kind: HostKind, host: string, rules: [string, string][]): string {
43  const hit = rules.find(([p]) => glob(p, host))
44  if (hit) return hit[1]
45  const short = host.replace(/\.local$/, '')
46  return kind === 'mac' ? '🍎 Mac' : kind === 'container' ? `🐳 ${short}` : `🐧 ${short}`
47}
48
49/** owner/name from a git remote URL (ssh or https); null when it isn't one. */
50export function ownerRepo(url: string): { owner: string; name: string } | null {
51  const m = url.trim().match(/[:/]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/)
52  return m && m[1] && m[2] ? { owner: m[1], name: m[2] } : null
53}
54
55/** `git remote -v` output into name → url (fetch lines). */
56export function parseRemotes(text: string): Record<string, string> {
57  const out: Record<string, string> = {}
58  for (const line of text.split('\n')) {
59    const m = line.match(/^(\S+)\s+(\S+)\s+\((fetch|push)\)/)
60    if (m && m[1] && m[2] && !out[m[1]]) out[m[1]] = m[2]
61  }
62  return out
63}
64
65export function describe(p: Place): string {
66  const parts = [p.label]
67  if (p.repo) {
68    const r = p.repo
69    let repo = `${r.name} · ${r.branch}`
70    if (r.isWorktree) repo += ' (worktree)'
71    parts.push(repo)
72    if (r.upstream && r.origin && r.upstream !== r.origin) parts.push(`fork of ${r.upstream}`)
73  } else {
74    parts.push(shortPath(p.cwd))
75  }
76  return parts.join(' · ')
77}
78
79export const shortPath = (path: string): string =>
80  path.replace(/^\/Users\/[^/]+/, '~').replace(/^\/home\/[^/]+/, '~').replace(/^~\/Library\/Application Support\/Claude\/scratch-workspaces\/.*\/(scratch-[^/]+)/, 'scratch/$1')
81
82const DEV = /(^|[\s;&|(])(make\s+(test|check|lint)|go\s+(test|vet|build)|pytest|\.venv\/bin\/pytest|script\/(test|setup|hassfest)|ruff\s|mypy\s|npm\s+(test|run)|pnpm\s|uv\s+run)/
83
84export const isDevCommand = (command: string): boolean => DEV.test(command)
85
86/** The container or Unraid word a remote command on the Mac names, or null. */
87export function sshTarget(command: string, targets: readonly string[]): string | null {
88  const m = command.match(/(^|[\s;&|(])(ssh|scp|rsync|sftp)\s+([^\n;&|]*)/)
89  if (!m || !m[3]) return null
90  const rest = m[3]
91  return targets.find(t => t && new RegExp(`(^|[\\s@:/])${t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[\\s:/])`, 'i').test(rest)) ?? null
92}
93
94export function homeFor(repo: string | undefined, rules: [string, string][]): HostKind | undefined {
95  if (!repo) return undefined
96  const v = rules.find(([p]) => glob(p, repo))?.[1]?.toLowerCase()
97  return v === 'mac' || v === 'container' ? v : undefined
98}
99
100/** The note Claude reads after the command, or null when the command is fine here. */
101export function nudge(p: Place, command: string, homes: [string, string][], targets: readonly string[]): { kind: string; note: string } | null {
102  if (p.kind === 'mac') {
103    const t = sshTarget(command, targets)
104    if (t)
105      return {
106        kind: `ssh:${t}`,
107        note:
108          `where-am-i: this session runs on the Mac (${p.host}), and that command reaches ${t}. ` +
109          `Work on the Unraid host or in the claude-code dev container belongs in a session on the "UnRAID" SSH connection (folder ~/dev), ` +
110          `where the keys and host keys are set up. If it failed with "Host key verification failed" or a permission denial, ` +
111          `stop and ask David to move the work there (or propose a side session there) instead of working around it.`,
112      }
113  }
114  const home = homeFor(p.repo?.name, homes)
115  if (home && home !== p.kind && p.kind !== 'linux' && isDevCommand(command))
116    return {
117      kind: `dev:${p.repo?.name}`,
118      note:
119        `where-am-i: ${p.repo?.name} is developed ${home === 'container' ? 'in the claude-code container (UnRAID SSH connection, ~/dev)' : 'on the Mac'}, ` +
120        `but this session runs ${p.kind === 'mac' ? 'on the Mac' : 'in the container'} (${shortPath(p.cwd)}). ` +
121        `This checkout may be stale or lack the environment (venv, CLAUDE.local.md, keys). Say so to David before relying on results from here.`,
122    }
123  return null
124}
125
126/** Whether a command may have moved the checkout (branch or folder). */
127export const movesCheckout = (command: string): boolean => /\bgit\s+(checkout|switch|worktree|clone|rebase|merge|pull)\b|(^|[\s;&|])cd\s/.test(command)
128