summaryrefslogtreecommitdiff
path: root/plugins/code-modernization/hooks/register.ts
diff options
context:
space:
mode:
authorClaude <noreply@anthropic.com>2026-11-06 00:54:48 +0000
committerClaude <noreply@anthropic.com>2026-11-06 00:54:48 +0000
commit7aba3deae3ff17d032c37e07d2929d1426b34278 (patch)
tree9c482f9acda1599bd2f9bed95a6a46b75e634e80 /plugins/code-modernization/hooks/register.ts
parent5472f5f56e0070feeeb464318b316714fe3e9105 (diff)
parentb8331dd69ab3e132bbf8cd6e89b5d8c1747e21b1 (diff)
Merge remote-tracking branch 'origin/main' into add-plugin/xcodeadd-plugin/xcode
Diffstat (limited to 'plugins/code-modernization/hooks/register.ts')
-rw-r--r--plugins/code-modernization/hooks/register.ts1298
1 files changed, 1298 insertions, 0 deletions
diff --git a/plugins/code-modernization/hooks/register.ts b/plugins/code-modernization/hooks/register.ts
new file mode 100644
index 00000000..cbb5cbd3
--- /dev/null
+++ b/plugins/code-modernization/hooks/register.ts
@@ -0,0 +1,1298 @@
+import type { EngineInterface, On, PluginOptions, ResultOf } from 'claude-code'
+
+import { lineOf, missingPathOf, noteCall, noteDone, noteFailure, prune, subjectOf, tallyOf } from './fleet/fleet'
+import type { Host, OpenResult } from './host'
+import { paint, tilesOf, type TouchKind } from './map/estate'
+import { absOf, baseName, isUnder, join, norm, relTo } from './paths'
+import { keysOfUnit, unitOfPath } from './reader/estate-model'
+import { readOrNull } from './reader/fs'
+import type { TestTotals } from './reader/modernized'
+import { oneLineOf, readSnapshot, REVIEWS_FILE } from './reader/progress'
+import type { ReviewVerdict } from './reader/progress'
+import { nodeOfFile } from './reader/topology'
+import { decide, ledgerJson, ledgerMarkdown, nextUnreviewed, queueOf, undecide, type DeckScope } from './review/deck'
+import { mergeLedger, parseLedger } from './review/ledger'
+import { signBrief } from './sign'
+import {
+ newActivity,
+ newState,
+ PANE_ID,
+ PLUGIN_NAME,
+ RASTER_KEY,
+ SIGN_ID,
+ type FinishedCall,
+ type State,
+} from './state'
+import { readTestRun, TEST_COMMAND } from './tests-run'
+import { deckView, signView } from './views/deck'
+import { headerRowsOf, legendRowsOf, nextRowsOf, paneView, planOf, showBar, type Kit } from './views/pane'
+import { plain } from './text'
+import { xrayOf } from './xray/xray'
+
+const REFRESH_DEBOUNCE_MS = 450
+/** While a fleet of agents is writing, a read of everything on disk is due this often, not after every call. */
+const REFRESH_BUSY_MS = 2500
+const FRAME_MS = 140
+const CLOCK_MS = 1000
+const POLL_MS = 20_000
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit'])
+const QUIET_TOOLS = new Set(['Read', 'Glob', 'Grep', 'LS', 'WebFetch', 'WebSearch', 'TodoWrite', 'ToolSearch'])
+const PARENT_TOOLS = new Set(['Agent', 'Task', 'Workflow'])
+const STEP = /\/(?:[\w-]+:)?(modernize-[a-z-]+)\b[^\n]*/
+
+const nowMs = (): number => Date.now()
+
+/** A cell count as the engine reports it, made safe to do layout arithmetic on. */
+const wholeOf = (value: unknown): number =>
+ typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0
+
+/**
+ * Binds a Host from `$`. Declared in this file, each member spelled
+ * `$.noun.event(...)`, so the engine reads what the module calls off its source.
+ */
+function hostOf($: EngineInterface): Host {
+ return {
+ fs: {
+ read: path => $.fs.read(path),
+ write: (path, text) => $.fs.write(path, text),
+ list: path => $.fs.list(path),
+ exists: path => $.fs.exists(path),
+ stat: path => $.fs.stat(path),
+ },
+ now: () => $.clock.now(),
+ after: (ms, fn) => $.clock.after(ms, fn),
+ every: (ms, fn) => $.clock.every(ms, fn),
+ storeGet: key => $.store.get(key),
+ storeSet: (key, value) => $.store.set(key, value),
+ invalidate: () => $.ui.invalidate('ui.render'),
+ blit: args => $.ui.blit(args),
+ status: text => $.ui.status(text),
+ toast: (text, timeoutMs) => $.ui.toast(text, timeoutMs !== undefined ? { timeoutMs } : undefined),
+ log: text => $.ui.log(text),
+ openPane: pane => $.ui.open(pane) as Promise<OpenResult>,
+ closePane: pane => $.ui.close(pane),
+ registerCommand: spec => $.command.register(spec),
+ fillPrompt: input => $.prompt.fill(input),
+ submitPrompt: input => $.prompt.submit(input),
+ abortTurn: turnId => $.turn.abort({ turnId }),
+ }
+}
+
+/**
+ * `fs` with every relative path rooted at `cwd`: the artifacts live under the
+ * session's working directory, wherever the process itself happens to stand.
+ */
+function rootedAt(fs: Host['fs'], cwd: string): Host['fs'] {
+ return {
+ read: path => fs.read(absOf(cwd, path)),
+ write: (path, text) => fs.write(absOf(cwd, path), text),
+ list: path => fs.list(absOf(cwd, path)),
+ exists: path => fs.exists(absOf(cwd, path)),
+ stat: path => fs.stat(absOf(cwd, path)),
+ }
+}
+
+/**
+ * Registers the plugin's live hooks: the pane and its estate map, x-ray
+ * reads, the rule review deck, the fleet view and the sign-off dialog.
+ * `session.start` binds the engine; every hook after
+ * it works over that binding and one state object.
+ *
+ * @param on the engine's registrar
+ * @param raw the plugin's options as the settings hold them
+ */
+export function register(on: On, raw: PluginOptions) {
+ const state: State = newState(raw)
+
+ // ---------------------------------------------------------------- reading
+
+ async function refresh(host: Host): Promise<void> {
+ if (state.isRefreshing) {
+ state.isRefreshQueued = true
+
+ return
+ }
+
+ state.isRefreshing = true
+
+ try {
+ const snapshot = await readSnapshot(host.fs, state.cache, {
+ ...((state.pickedSystem ?? state.options.system) !== '' && { system: state.pickedSystem ?? state.options.system }),
+ commandPrefix: state.options.commandPrefix,
+ legacyDir: state.options.legacyDir,
+ track: state.options.track,
+ writtenUnits: state.writtenUnits,
+ observed: state.observed,
+ nowMs: nowMs(),
+ })
+
+ // The pane opens by itself once there is modernization to show: the first artifact under analysis/,
+ // not only a legacy system that has not been touched.
+ const isFirstSight = snapshot !== null && snapshot.hasAnalysis && state.snapshot?.hasAnalysis !== true
+
+ state.snapshot = snapshot
+ state.readError = null
+
+ if (isFirstSight) {
+ maybeAutoOpen()
+ }
+
+ if (snapshot !== null) {
+ if (!state.deck.isOpen) {
+ state.deck.ledger = snapshot.reviews
+ }
+
+ // The pane says all of this already, and so does the bar that stands where it was while it is hidden. The
+ // pinned line is for a person who turned the pane off. A workspace that holds a legacy system and nothing
+ // yet under analysis/ has no modernization to report.
+ host.status(state.pane.isOpen || !snapshot.hasAnalysis || state.options.panel !== 'off' ? undefined : oneLineOf(snapshot))
+ }
+
+ if (state.estate !== null) {
+ state.estate = { ...state.estate, tiles: [] }
+ }
+ } catch (error) {
+ state.readError = error instanceof Error ? error.message : String(error)
+ } finally {
+ state.isRefreshing = false
+ host.invalidate()
+
+ if (state.isRefreshQueued) {
+ state.isRefreshQueued = false
+ scheduleRefresh(host)
+ }
+ }
+ }
+
+ function scheduleRefresh(host: Host): void {
+ // A read is already due, and it will see everything written so far. Pushing it out with every call would starve
+ // it for as long as agents keep writing, and the map would show nothing of a fan-out until it was over.
+ if (state.timers.has('refresh')) {
+ return
+ }
+
+ const isBusy = tallyOf(state.fleet, nowMs()).active >= 3
+
+ state.timers.set(
+ 'refresh',
+ host.after(isBusy ? REFRESH_BUSY_MS : REFRESH_DEBOUNCE_MS, () => {
+ state.timers.delete('refresh')
+ void refresh(host)
+ }),
+ )
+ }
+
+ // ------------------------------------------------------------- animation
+
+ function frameOf(): { cells: string; isAnimating: boolean } | null {
+ const estate = state.estate
+
+ if (estate === null || state.snapshot === null) {
+ return null
+ }
+
+ const painted = paint(estate.tiles, estate.columns, estate.rows, state.touches, nowMs())
+
+ return { cells: painted.cells, isAnimating: painted.isAnimating }
+ }
+
+ function animate(host: Host): void {
+ if (state.timers.has('frames') || !state.pane.isOpen) {
+ return
+ }
+
+ state.timers.set(
+ 'frames',
+ host.every(FRAME_MS, () => {
+ const estate = state.estate
+ const frame = frameOf()
+
+ if (estate === null || frame === null || !state.pane.isOpen) {
+ state.timers.get('frames')?.cancel()
+ state.timers.delete('frames')
+
+ return
+ }
+
+ void host
+ .blit({
+ requestId: PANE_ID,
+ key: RASTER_KEY,
+ cells: frame.cells,
+ columns: estate.columns,
+ rows: estate.rows,
+ })
+ .then(result => {
+ // Said once: a refused repaint means the map is stale, which is worth knowing.
+ if (result.deny !== undefined && !state.timers.has('blit-refused')) {
+ state.timers.set('blit-refused', host.after(60_000, () => state.timers.delete('blit-refused')))
+ host.log(`estate map: repaint refused (${result.deny})`)
+ }
+ })
+ .catch(() => undefined)
+
+ if (!frame.isAnimating) {
+ state.timers.get('frames')?.cancel()
+ state.timers.delete('frames')
+ }
+ }),
+ )
+ }
+
+ function touch(host: Host, nodeId: string, kind: TouchKind): void {
+ const held = state.touches.get(nodeId)
+
+ // A write outranks a read that is still fading.
+ if (held !== undefined && held.kind === 'write' && kind === 'read' && nowMs() - held.atMs < 1200) {
+ return
+ }
+
+ state.touches.set(nodeId, { atMs: nowMs(), kind })
+ animate(host)
+ }
+
+ /** The estate unit ids a tool call's paths and command text name, with how each was touched. */
+ function nodesTouched(tool: string, args: Readonly<Record<string, unknown>>): { id: string; kind: TouchKind }[] {
+ const snapshot = state.snapshot
+ const estate = snapshot?.estate
+
+ if (snapshot === null || estate === null || estate === undefined) {
+ return []
+ }
+
+ const legacyRoot = join(state.options.legacyDir, snapshot.system)
+ const modernRoot = join('modernized', snapshot.system)
+ const upliftRoot = join('modernized', `${snapshot.system}-uplifted`)
+ const out = new Map<string, TouchKind>()
+ const kind: TouchKind = WRITE_TOOLS.has(tool) ? 'write' : 'read'
+
+ const take = (path: string, how: TouchKind) => {
+ const rel = relTo(state.cwd, path)
+
+ if (rel === null) {
+ return
+ }
+
+ if (isUnder(rel, legacyRoot) && rel !== legacyRoot) {
+ const unit = unitOfPath(estate, snapshot.topology, rel.slice(legacyRoot.length + 1))
+
+ if (unit !== null) {
+ out.set(unit.id, how)
+ }
+ } else if (isUnder(rel, upliftRoot) && rel !== upliftRoot) {
+ // An uplift's working copy has the legacy tree's own layout, so the same path names the same unit.
+ const unit = unitOfPath(estate, snapshot.topology, rel.slice(upliftRoot.length + 1))
+
+ if (unit !== null) {
+ out.set(unit.id, how)
+
+ // An edit that keeps a file's size is invisible to the size comparison; a write seen here is not.
+ if (how === 'write') {
+ state.writtenUnits.add(unit.id)
+ }
+ }
+ } else if (isUnder(rel, modernRoot) && rel !== modernRoot) {
+ const dir = (rel.slice(modernRoot.length + 1).split('/')[0] ?? '').toLowerCase()
+
+ const unit = estate.units.find(candidate => keysOfUnit(candidate).some(key => key.toLowerCase() === dir))
+
+ if (unit !== undefined) {
+ out.set(unit.id, how === 'read' ? 'read' : 'write')
+ }
+ }
+ }
+
+ for (const key of ['file_path', 'path', 'notebook_path']) {
+ const value = args[key]
+
+ if (typeof value === 'string') {
+ take(value, kind)
+ }
+ }
+
+ const command = typeof args.command === 'string' ? args.command : ''
+
+ if (command !== '') {
+ const paths = command.match(/(?:\.{0,2}\/)?[\w.@~+-]+(?:\/[\w.@~+-]+)+/g) ?? []
+ const writes = /(?:>|\btee\b|\bsed\s+-i|\bmv\b|\bcp\b|\brm\b|\bpatch\b|\bgit\s+(?:apply|checkout|restore))/.test(command)
+
+ for (const path of paths.slice(0, 24)) {
+ const rel = relTo(state.cwd, path) ?? ''
+
+ take(path, writes && (isUnder(rel, modernRoot) || isUnder(rel, upliftRoot)) ? 'write' : 'read')
+ }
+ }
+
+ return [...out.entries()].map(([id, how]) => ({ id, kind: how }))
+ }
+
+ /** The module a shell command's text names by path, of those the pane knows: the longest path wins. */
+ function moduleOfCommand(command: string): string | null {
+ const snapshot = state.snapshot
+
+ if (snapshot === null) {
+ return null
+ }
+
+ const upliftRoot = join('modernized', `${snapshot.system}-uplifted`)
+
+ const candidates = [
+ ...snapshot.modules.map(module => module.path),
+ ...(snapshot.track === 'uplift'
+ ? (snapshot.estate?.units ?? []).flatMap(unit => (unit.dir !== undefined && unit.dir !== '' ? [join(upliftRoot, unit.dir)] : []))
+ : []),
+ ].sort((a, b) => b.length - a.length)
+
+ const escaped = (path: string) => path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+ return (
+ candidates.find(path => new RegExp(`(?:^|[\\s'"=:@])(?:\\./)?${escaped(path)}(?=[\\s/'"]|$)`).test(command)) ?? null
+ )
+ }
+
+ // ------------------------------------------------------------------ deck
+
+ async function openDeck(host: Host, scope: DeckScope, filter: string): Promise<string> {
+ const snapshot = state.snapshot
+
+ if (snapshot === null || snapshot.rules === null) {
+ return 'No BUSINESS_RULES.md to review yet. Run the extract-rules command first.'
+ }
+
+ const queue = queueOf(snapshot.rules, scope, filter)
+
+ state.deck = {
+ isOpen: true,
+ scope,
+ filter,
+ queue,
+ ledger: snapshot.reviews,
+ edits: new Map(),
+ index: nextUnreviewed(queue, snapshot.reviews, 0),
+ source: null,
+ isSourceShown: false,
+ }
+
+ // The deck draws in the band above the prompt: nothing to open, only to draw.
+ host.invalidate()
+
+ return queue.length === 0
+ ? 'Nothing to review under that scope.'
+ : `Reviewing ${queue.length} rule${queue.length === 1 ? '' : 's'}.`
+ }
+
+ async function saveLedger(host: Host): Promise<void> {
+ const system = state.snapshot?.system
+
+ if (system === undefined) {
+ return
+ }
+
+ // The review command writes this file too: what it added while the deck was open is kept, this session's decisions go on top.
+ const onDisk = parseLedger(await readOrNull(host.fs, join('analysis', system, REVIEWS_FILE)))
+ const merged = mergeLedger(onDisk, state.deck.edits)
+
+ state.deck.ledger = merged
+ await host.fs.write(join('analysis', system, REVIEWS_FILE), ledgerJson(system, merged))
+ await host.fs.write(join('analysis', system, 'RULE_REVIEWS.md'), ledgerMarkdown(system, merged))
+ scheduleRefresh(host)
+ }
+
+ async function loadSource(host: Host): Promise<void> {
+ const rule = state.deck.queue[state.deck.index]
+ const snapshot = state.snapshot
+ const citation = rule?.citations[0]
+
+ if (rule === undefined || snapshot === null || citation === undefined) {
+ return
+ }
+
+ const legacyRoot = join(state.options.legacyDir, snapshot.system)
+ const written = norm(citation.path)
+
+ // A citation comes from a file in the analysis tree: it names a file inside the code, never a way out of it.
+ if (written.startsWith('/') || /^[A-Za-z]:/.test(written) || written.split('/').includes('..')) {
+ return
+ }
+ const viaMap = snapshot.topology !== null ? nodeOfFile(snapshot.topology, written)?.file : undefined
+
+ const candidates = [
+ written,
+ join(legacyRoot, written),
+ ...(viaMap !== undefined ? [join(legacyRoot, viaMap)] : []),
+ ]
+
+ for (const path of candidates) {
+ const text = await readOrNull(host.fs, path)
+
+ if (text === null) {
+ continue
+ }
+
+ const lines = text.split('\n')
+ // From the cited line itself: in a short band every row of lead-in costs a row of the rule's own code.
+ const from = Math.max(1, citation.from)
+ const to = Math.min(lines.length, Math.max(citation.to + 2, from + 11), from + 39)
+
+ state.deck.source = {
+ ruleId: rule.id,
+ path,
+ startLine: from,
+ text: lines
+ .slice(from - 1, to)
+ .join('\n')
+ .replace(/[^\x09\x0a\x20-\x7e -￿]/g, ' ')
+ .slice(0, 9000),
+ }
+
+ return
+ }
+
+ state.deck.source = { ruleId: rule.id, path: written, startLine: citation.from, text: '(source file not found)' }
+ }
+
+ const deckActionsOf = (host: Host) => ({
+ decide: (verdict: ReviewVerdict) => {
+ const rule = state.deck.queue[state.deck.index]
+
+ if (rule === undefined) {
+ return
+ }
+
+ state.deck.ledger = decide(state.deck.ledger, rule, verdict, new Date(nowMs()).toISOString())
+ state.deck.edits.set(rule.id, state.deck.ledger[rule.id] ?? null)
+ state.deck.index = nextUnreviewed(state.deck.queue, state.deck.ledger, state.deck.index + 1)
+ state.deck.isSourceShown = false
+ void saveLedger(host).catch(() => undefined)
+ host.invalidate()
+ },
+ undo: () => {
+ const rule = state.deck.queue[state.deck.index]
+
+ if (rule !== undefined) {
+ state.deck.ledger = undecide(state.deck.ledger, rule.id)
+ state.deck.edits.set(rule.id, null)
+ void saveLedger(host).catch(() => undefined)
+ host.invalidate()
+ }
+ },
+ prev: () => {
+ const size = state.deck.queue.length
+
+ state.deck.index = size === 0 ? 0 : (state.deck.index - 1 + size) % size
+ state.deck.isSourceShown = false
+ host.invalidate()
+ },
+ next: () => {
+ const size = state.deck.queue.length
+
+ state.deck.index = size === 0 ? 0 : (state.deck.index + 1) % size
+ state.deck.isSourceShown = false
+ host.invalidate()
+ },
+ source: () => {
+ state.deck.isSourceShown = !state.deck.isSourceShown
+
+ if (state.deck.isSourceShown) {
+ void loadSource(host).then(() => host.invalidate())
+ }
+
+ host.invalidate()
+ },
+ close: () => {
+ state.deck.isOpen = false
+ host.invalidate()
+ },
+ })
+
+ // ------------------------------------------------------------------ sign
+
+ async function openSign(host: Host, name = ''): Promise<string> {
+ const snapshot = state.snapshot
+
+ if (snapshot === null || snapshot.brief === null) {
+ return 'There is no brief to sign yet. Run the brief command first.'
+ }
+
+ if (snapshot.brief.approval.isSigned) {
+ return `The brief is already signed${snapshot.brief.approval.by !== undefined ? ` by ${snapshot.brief.approval.by}` : ''}.`
+ }
+
+ if (state.activity.isWorking) {
+ return 'Wait for the running turn to finish before signing.'
+ }
+
+ state.sign = { isOpen: true, name: name !== '' ? name : state.sign.name, covers: 'phase-1', error: null }
+
+ await host.openPane({
+ id: SIGN_ID,
+ title: 'Sign the brief',
+ focus: true,
+ closeOnEscape: true,
+ holdToasts: true,
+ rows: 12,
+ })
+
+ host.invalidate()
+
+ return ''
+ }
+
+ const signActionsOf = (host: Host) => ({
+ name: (value: string) => {
+ state.sign.name = value
+ },
+ covers: (value: 'phase-1' | 'full') => {
+ state.sign.covers = value
+ host.invalidate()
+ },
+ cancel: () => {
+ state.sign.isOpen = false
+ void host.closePane({ id: SIGN_ID }).catch(() => undefined)
+ },
+ sign: () => {
+ void (async () => {
+ const system = state.snapshot?.system
+ const name = state.sign.name.trim()
+
+ if (system === undefined) {
+ return
+ }
+
+ if (name === '') {
+ state.sign.error = 'Type the approver\'s name first.'
+ host.invalidate()
+
+ return
+ }
+
+ if (state.activity.isWorking) {
+ state.sign.error = 'A turn is running; sign once it has finished.'
+ host.invalidate()
+
+ return
+ }
+
+ const path = join('analysis', system, 'MODERNIZATION_BRIEF.md')
+ const text = await readOrNull(host.fs, path)
+ const signed = text !== null ? signBrief(text, name, new Date(nowMs()).toISOString().slice(0, 10), state.sign.covers) : null
+
+ if (signed === null) {
+ state.sign.error = 'The brief has no approval block to sign.'
+ host.invalidate()
+
+ return
+ }
+
+ await host.fs.write(path, signed)
+ state.sign.isOpen = false
+ await host.closePane({ id: SIGN_ID }).catch(() => undefined)
+ host.log(`brief signed by ${name} (${state.sign.covers === 'full' ? 'full plan' : 'Phase 1 only'})`)
+ await refresh(host)
+ })()
+ },
+ })
+
+ // ------------------------------------------------------------------ pane
+
+ /**
+ * Opens the pane. Opened unasked on a terminal too narrow to dock a pane, the engine holds it undrawn: it is not open to
+ * the person, so the bar with the show button stays where it was, and pressing that button (the person asking) seats
+ * the pane at any width.
+ */
+ async function openPane(host: Host): Promise<{ isPlaced: boolean; reason: string }> {
+ const result: OpenResult = await host.openPane({ id: PANE_ID, title: 'Modernization' })
+ const isPlaced = result === undefined || result.isPlaced !== false
+
+ state.pane.isOpen = isPlaced
+ state.pane.isWaiting = !isPlaced
+ state.pane.isClosedByPerson = false
+ void refresh(host)
+
+ return { isPlaced, reason: result !== undefined && result.reason !== undefined ? result.reason : '' }
+ }
+
+ const paneActionsOf = (host: Host) => ({
+ system: () => {
+ const systems = state.snapshot?.systems ?? []
+ const current = state.snapshot?.system
+
+ if (systems.length < 2 || current === undefined) {
+ return
+ }
+
+ // A different system is a different estate, a different brief and a different set of lit tiles.
+ state.pickedSystem = systems[(systems.indexOf(current) + 1) % systems.length] ?? current
+ state.touches.clear()
+ state.writtenUnits.clear()
+ state.estate = null
+ void refresh(host)
+ },
+ next: () => {
+ const next = state.snapshot?.next
+
+ if (next === null || next === undefined || next.isByHand) {
+ return
+ }
+
+ void host
+ .fillPrompt({ text: next.text })
+ .then(result => {
+ if (!result.isFilled) {
+ host.toast(`Next: ${next.text}`, 8000)
+ }
+ })
+ .catch(() => undefined)
+ },
+ review: () => {
+ void openDeck(host, 'flagged', '').catch(() => undefined)
+ },
+ sign: () => {
+ void openSign(host)
+ .then(message => {
+ if (message !== '') {
+ host.toast(message, 6000)
+ }
+ })
+ .catch(() => undefined)
+ },
+ close: () => {
+ state.pane.isOpen = false
+ state.pane.isWaiting = false
+ state.pane.isClosedByPerson = true
+ void host.closePane({ id: PANE_ID }).catch(() => undefined)
+ },
+ stop: () => {
+ const turnId = state.activity.turnId
+
+ if (turnId !== null) {
+ void host.abortTurn(turnId).catch(() => undefined)
+ }
+ },
+ })
+
+ /**
+ * Opens the pane by itself once there is something to show, the person has not closed it, and
+ * the layout docks panes (the fullscreen layout). What the layout is comes from whichever render
+ * last said: not every build draws every site, so each render hook reports what it saw.
+ */
+ function maybeAutoOpen(viewport?: { columns?: number; isFullscreen?: boolean }): void {
+ state.viewport.columns = viewport?.columns ?? state.viewport.columns
+ state.viewport.isFullscreen = viewport?.isFullscreen ?? state.viewport.isFullscreen
+
+ const host = state.host
+
+ const shouldOpen =
+ host !== null &&
+ state.options.panel === 'auto' &&
+ !state.pane.isOpen &&
+ !state.pane.isWaiting &&
+ !state.pane.isClosedByPerson &&
+ !state.timers.has('auto-open') &&
+ state.snapshot !== null &&
+ state.snapshot.hasAnalysis &&
+ state.viewport.isFullscreen === true
+
+ if (shouldOpen && host !== null) {
+ // Opened from a timer: a render hook only draws.
+ state.timers.set(
+ 'auto-open',
+ host.after(50, () => {
+ state.timers.delete('auto-open')
+ void openPane(host).catch(() => undefined)
+ }),
+ )
+ }
+ }
+
+ // ------------------------------------------------------------- lifecycle
+
+ on('session.start', async ($, e, next) => {
+ const bound = hostOf($)
+ const host: Host = { ...bound, fs: rootedAt(bound.fs, e.cwd) }
+
+ state.host = host
+ state.cwd = e.cwd
+
+ for (const timer of state.timers.values()) {
+ timer.cancel()
+ }
+
+ state.timers.clear()
+
+ await Promise.all([
+ host
+ .registerCommand({
+ name: 'modernize-panel',
+ description: 'Show or hide the modernization progress pane and estate map',
+ argumentHint: '[open|close|json]',
+ immediate: true,
+ })
+ .catch(() => undefined),
+ host
+ .registerCommand({
+ name: 'modernize-review-pane',
+ description: 'Review business rules one card at a time in the pane: confirm, wrong, or discuss',
+ argumentHint: '[flagged|p0|all] [filter]',
+ })
+ .catch(() => undefined),
+ host
+ .registerCommand({
+ name: 'modernize-sign',
+ description: 'Sign the modernization brief\'s approval block (a person\'s action)',
+ argumentHint: '[approver name, role]',
+ })
+ .catch(() => undefined),
+ ])
+
+ await refresh(host)
+
+ state.timers.set(
+ 'clock',
+ host.every(CLOCK_MS, () => {
+ if (state.pane.isOpen && (state.activity.isWorking || state.activity.running.size > 0)) {
+ host.invalidate()
+ }
+ }),
+ )
+
+ state.timers.set(
+ 'poll',
+ host.every(POLL_MS, () => {
+ if (state.pane.isOpen && !state.activity.isWorking) {
+ scheduleRefresh(host)
+ }
+ }),
+ )
+
+ return next(e)
+ })
+
+ on('ui.render', { component: 'PromptHint' }, ($, e, next) => {
+ if (e.surface === 'terminal') {
+ maybeAutoOpen(e.viewport)
+ }
+
+ return next(e)
+ })
+
+ on('ui.render', { component: 'AbovePrompt' }, ($, e, next) => {
+ const host = state.host
+
+ if (e.surface === 'terminal') {
+ // Not every build reports `isFullscreen`. The band's `maxRows` tells the same fact: under the
+ // fullscreen layout it is what the bottom slot has left; otherwise it is the terminal's height.
+ const rows = e.viewport?.rows
+ const inferred = rows !== undefined && e.props.maxRows > 0 ? e.props.maxRows < rows : undefined
+
+ maybeAutoOpen({
+ ...(e.viewport?.columns !== undefined && { columns: e.viewport.columns }),
+ ...((e.viewport?.isFullscreen ?? inferred) !== undefined && {
+ isFullscreen: e.viewport?.isFullscreen ?? inferred,
+ }),
+ })
+ }
+
+ // A survey holds the band first; the deck waits behind it.
+ if (host === null || e.props.hasSurvey || e.surface !== 'terminal') {
+ return next(e)
+ }
+
+ const table = $.ui.resolve(e)
+
+ // With no deck open, a hidden pane leaves one row and a button to bring it back: the pane is
+ // always one press away, on a terminal too narrow to open it unasked as well as on a wide one.
+ if (!state.deck.isOpen) {
+ const snapshot = state.snapshot
+
+ if (state.options.panel === 'off' || state.pane.isOpen || snapshot === null || !snapshot.hasAnalysis) {
+ return next(e)
+ }
+
+ return showBar(
+ { Box: table.Box, Text: table.Text, Button: table.Button },
+ oneLineOf(snapshot),
+ e.props.bodyColumns,
+ () => {
+ void openPane(host)
+ .then(result => {
+ if (!result.isPlaced) {
+ host.toast(`The pane could not be shown: ${result.reason}`, 8000)
+ }
+ })
+ .catch(() => undefined)
+ },
+ )
+ }
+
+ return deckView(
+ { Box: table.Box, Text: table.Text, Button: table.Button, Code: table.Code },
+ state.deck,
+ e.props.bodyColumns,
+ e.props.maxRows,
+ deckActionsOf(host),
+ )
+ })
+
+ on('ui.render', { component: 'Pane' }, async ($, e, next) => {
+ const host = state.host
+
+ if (host === null || (e.requestId !== PANE_ID && e.requestId !== SIGN_ID)) {
+ return next(e)
+ }
+
+ const table = $.ui.resolve(e)
+ const kit: Kit = {
+ Box: table.Box,
+ Text: table.Text,
+ Button: table.Button,
+ ...('Raster' in table && { Raster: table.Raster }),
+ ...('Code' in table && { Code: table.Code }),
+ ...('Input' in table && { Input: table.Input }),
+ ...('Select' in table && { Select: table.Select }),
+ }
+
+ const columns = Math.max(24, wholeOf(e.props.bodyColumns) - 1)
+
+ if (e.requestId === SIGN_ID) {
+ return signView(
+ kit,
+ state.sign,
+ state.snapshot?.system ?? '',
+ state.snapshot?.brief?.openQuestions ?? 0,
+ columns,
+ signActionsOf(host),
+ )
+ }
+
+ // A squeezed pane (a dialog or another panel has its rows) can report a body of no rows at all.
+ const rows = wholeOf(e.props.scroll.bodyRows)
+
+ state.pane.isOpen = true
+ state.pane.isWaiting = false
+ state.pane.bodyColumns = columns
+ state.pane.bodyRows = rows
+ state.pane.placement = e.props.placement
+
+ const snapshot = state.snapshot
+
+ const plan = planOf(rows, e.props.placement, {
+ phases: snapshot?.brief?.phases.length ?? 0,
+ modules: snapshot?.modules.length ?? 0,
+ attention:
+ (snapshot?.attention.length ?? 0) +
+ [...state.fleet.signatures.values()].filter(signature => signature.agents.size >= 3).length,
+ hasMap: snapshot !== null && snapshot.estate !== null && kit.Raster !== undefined,
+ headerRows: headerRowsOf(snapshot, columns),
+ nextRows: nextRowsOf(snapshot, state, columns),
+ legendRows: legendRowsOf(snapshot, columns),
+ })
+
+ let estate: { cells: string; columns: number; rows: number; tiles: State['estate'] extends infer T ? (T extends { tiles: infer U } ? U : never) : never } | null = null
+
+ // The plan sheds the map first when the body is too short; a Raster of no rows is refused.
+ if (snapshot !== null && snapshot.estate !== null && kit.Raster !== undefined && plan.estate >= 1 && columns >= 1) {
+ const mapRows = Math.min(256, plan.estate)
+ const held = state.estate
+
+ const tiles =
+ held !== null && held.columns === columns && held.rows === mapRows && held.tiles.length > 0
+ ? held.tiles
+ : tilesOf(snapshot, columns, mapRows)
+
+ state.estate = { tiles, columns, rows: mapRows, isMounted: true }
+
+ const painted = paint(tiles, columns, mapRows, state.touches, nowMs())
+
+ estate = { cells: painted.cells, columns, rows: mapRows, tiles }
+
+ if (painted.isAnimating) {
+ animate(host)
+ }
+ } else {
+ // No map drawn: nothing for the frame timer to repaint.
+ state.estate = null
+ }
+
+ return paneView(
+ kit,
+ state,
+ { columns, rows, placement: e.props.placement, nowMs: nowMs(), estate, plan },
+ paneActionsOf(host),
+ )
+ })
+
+ on('ui.close', async ($, e, next) => {
+ const result = await next(e)
+
+ if (result.deny !== undefined) {
+ return result
+ }
+
+ if (e.id === PANE_ID) {
+ state.pane.isOpen = false
+ state.pane.isWaiting = false
+ state.pane.isClosedByPerson = e.origin.kind === 'person' || state.pane.isClosedByPerson
+
+ if (state.estate !== null) {
+ state.estate.isMounted = false
+ }
+ } else if (e.id === SIGN_ID) {
+ state.sign.isOpen = false
+ }
+
+ return result
+ })
+
+ // -------------------------------------------------------------- commands
+
+ on('command.run', { command: 'modernize-panel' }, async ($, e, next) => {
+ const host = state.host
+
+ if (host === null) {
+ return next(e)
+ }
+
+ state.viewport.isFullscreen = e.presentation.isFullscreen
+ state.viewport.columns = e.presentation.columns
+
+ const arg = e.args.trim().toLowerCase()
+
+ if (arg === 'json') {
+ await refresh(host)
+
+ const snapshot = state.snapshot
+
+ return {
+ text:
+ snapshot === null
+ ? 'no system under analysis/'
+ : `\`\`\`json\n${JSON.stringify(
+ {
+ system: snapshot.system,
+ stages: snapshot.stages.map(stage => ({ key: stage.key, done: stage.isDone, detail: stage.detail })),
+ brief: snapshot.brief && {
+ target: snapshot.brief.target,
+ approval: snapshot.brief.approval,
+ phases: snapshot.brief.phases.map(phase => ({
+ number: phase.number,
+ title: phase.title,
+ size: phase.size,
+ modules: phase.modules,
+ criteria: phase.criteria.length,
+ ticked: phase.criteria.filter(criterion => criterion.isTicked).length,
+ })),
+ },
+ modules: snapshot.modules.map(module => ({
+ dir: module.dir,
+ state: module.state,
+ tests: module.tests,
+ reviewDate: module.reviewDate,
+ })),
+ proof:
+ snapshot.verification === null
+ ? null
+ : {
+ overall: snapshot.verification.overall,
+ modules: [...snapshot.proofs].map(([name, proof]) => ({ name, state: proof.state, verdict: proof.verdict ?? null, reason: proof.reason })),
+ },
+ totals: snapshot.totals,
+ percent: snapshot.percent,
+ attention: snapshot.attention,
+ next: snapshot.next,
+ },
+ null,
+ 2,
+ )}\n\`\`\``,
+ }
+ }
+
+ const wantsClose = arg === 'close' || (arg === '' && state.pane.isOpen)
+
+ if (wantsClose) {
+ state.pane.isOpen = false
+ state.pane.isWaiting = false
+ state.pane.isClosedByPerson = true
+ await host.closePane({ id: PANE_ID }).catch(() => undefined)
+
+ return { text: 'Modernization pane hidden' }
+ }
+
+ const opened = await openPane(host)
+
+ return { text: opened.isPlaced ? 'Modernization pane shown' : `The pane could not be shown: ${opened.reason}` }
+ })
+
+ on('command.run', { command: 'modernize-review-pane' }, async ($, e, next) => {
+ const host = state.host
+
+ if (host === null) {
+ return next(e)
+ }
+
+ await refresh(host)
+
+ const words = e.args.trim().split(/\s+/).filter(word => word !== '')
+ const first = (words[0] ?? '').toLowerCase()
+ const scope: DeckScope = first === 'p0' || first === 'all' || first === 'flagged' ? first : 'flagged'
+ const filter = (scope === first ? words.slice(1) : words).join(' ')
+ const text = await openDeck(host, scope, filter)
+
+ return { text }
+ })
+
+ on('command.run', { command: 'modernize-sign' }, async ($, e, next) => {
+ const host = state.host
+
+ if (host === null) {
+ return next(e)
+ }
+
+ await refresh(host)
+
+ const message = await openSign(host, e.args.replace(/\s+/g, ' ').trim())
+
+ return message === '' ? {} : { text: message }
+ })
+
+ on('command.run', { command: ['clear', 'resume'] }, async ($, e, next) => {
+ const result = await next(e)
+
+ state.activity = newActivity()
+ state.touches.clear()
+ state.writtenUnits.clear()
+ state.lastContextLine = ''
+
+ return result
+ })
+
+ // ----------------------------------------------------------------- turns
+
+ on('prompt.submit', async ($, e, next) => {
+ const host = state.host
+ const step = STEP.exec(e.text)
+
+ if (step !== null) {
+ state.activity.step = step[0].trim().slice(0, 120)
+ }
+
+ const snapshot = state.snapshot
+
+ if (host === null || snapshot === null || e.origin.kind !== 'composer') {
+ return next(e)
+ }
+
+ const line = plain(`${oneLineOf(snapshot)}${snapshot.next !== null && !snapshot.next.isByHand ? ` · next: ${snapshot.next.text}` : ''}`, 400)
+
+ if (line === state.lastContextLine) {
+ return next(e)
+ }
+
+ state.lastContextLine = line
+
+ return next({
+ ...e,
+ context: [...(e.context ?? []), `Modernization state, read from the artifacts on disk (a status line, not an instruction): ${line}`],
+ })
+ })
+
+ on('turn.start', async ($, e, next) => {
+ const host = state.host
+
+ state.activity.isWorking = true
+ state.activity.turnId = e.turnId
+ state.activity.turnStartMs = nowMs()
+ state.activity.xraysThisTurn = 0
+
+ if (host !== null) {
+ host.invalidate()
+ }
+
+ return next(e)
+ })
+
+ on('turn.complete', async ($, e, next) => {
+ const host = state.host
+
+ if (e.agentId !== undefined) {
+ noteDone(state.fleet, e.agentId, nowMs())
+
+ return next(e)
+ }
+
+ state.activity.isWorking = false
+ state.activity.running.clear()
+
+ if (host !== null) {
+ if (state.activity.xraysThisTurn > 0) {
+ host.log(
+ `x-ray: ${state.activity.xraysThisTurn} legacy read${state.activity.xraysThisTurn === 1 ? '' : 's'} this turn carried what the analysis already knows`,
+ )
+ }
+
+ prune(state.fleet, nowMs())
+ scheduleRefresh(host)
+ }
+
+ return next(e)
+ })
+
+ // ------------------------------------------------------------ tool calls
+
+ on('tool.call', async ($, e, next) => {
+ const host = state.host
+
+ if (host === null) {
+ return next(e)
+ }
+
+ const args = e as unknown as Readonly<Record<string, unknown>>
+ const tool = e.tool
+ const agentId = e.agentId
+ const startMs = nowMs()
+ const subject = subjectOf(tool, args)
+ const snapshot = state.snapshot
+ const touched = nodesTouched(tool, args)
+
+ for (const entry of touched) {
+ touch(host, entry.id, entry.kind)
+ }
+
+ if (agentId !== undefined) {
+ const unit = touched[0] !== undefined ? snapshot?.estate?.units.find(candidate => candidate.id === touched[0]?.id)?.name : undefined
+
+ noteCall(state.fleet, agentId, tool, subject, startMs, unit)
+ }
+
+ state.activity.running.set(e.tool_use_id, {
+ id: e.tool_use_id,
+ tool,
+ subject,
+ startMs,
+ ...(agentId !== undefined && { agentId }),
+ })
+
+ const path = typeof args.file_path === 'string' ? args.file_path : typeof args.notebook_path === 'string' ? args.notebook_path : undefined
+ const rel = path !== undefined ? relTo(state.cwd, path) : null
+
+ let result: ResultOf['tool.call'] | undefined
+ let note: string | undefined
+
+ try {
+ result = await next(e)
+
+ if (result.deny !== undefined) {
+ return result
+ }
+
+ const extra: string[] = []
+ const isError = result.isError === true
+ const text = typeof result.text === 'string' ? result.text : ''
+
+ if (isError && agentId !== undefined) {
+ // What the call was aimed at is half of the cause: the path as the agent gave it, else the command's head.
+ const missing = missingPathOf(text)
+ const example = rel ?? (missing !== undefined ? (relTo(state.cwd, missing) ?? missing) : subject)
+ const signature = noteFailure(state.fleet, agentId, text, nowMs(), example)
+
+ if (signature !== null) {
+ const line = lineOf(signature)
+
+ host.toast(`Fleet: ${line}`, 9000)
+ host.log(`fleet: ${line}. One cause across agents usually belongs in the playbook, not in each agent.`)
+ }
+ }
+
+ if (tool === 'Read' && !isError && state.options.isXrayOn && snapshot !== null && rel !== null) {
+ const legacyRoot = join(state.options.legacyDir, snapshot.system)
+
+ if (isUnder(rel, legacyRoot) && rel !== legacyRoot) {
+ const xray = xrayOf(snapshot, {
+ fileRel: rel.slice(legacyRoot.length + 1),
+ ...(typeof args.offset === 'number' && { offset: args.offset }),
+ ...(typeof args.limit === 'number' && { limit: args.limit }),
+ })
+
+ if (xray !== null) {
+ extra.push(xray.text)
+ note = xray.summary.replace(/^x-ray [^:]+: /, 'x-ray ')
+ state.activity.xrays += 1
+
+ if (agentId === undefined) {
+ state.activity.xraysThisTurn += 1
+ }
+ }
+ }
+ }
+
+ // A citation in the analysis is relative to the legacy system's root, and an agent handed one
+ // often reads it from the workspace root. Say where the file is rather than let it search.
+ if (tool === 'Read' && isError && state.options.isXrayOn && snapshot !== null && rel !== null && /does not exist/i.test(text)) {
+ const legacyRoot = join(state.options.legacyDir, snapshot.system)
+ const candidate = join(legacyRoot, rel)
+
+ // Only a plain path is echoed back: the note is read by the model, and a name is text from the legacy tree.
+ if (plain(rel, 300) === rel && !isUnder(rel, state.options.legacyDir) && (await host.fs.exists(candidate))) {
+ extra.push(
+ `There is no ${rel} in the workspace, but ${candidate} exists. Paths cited under analysis/${snapshot.system}/ are relative to ${legacyRoot}/.`,
+ )
+ note = 'x-ray: the path exists under the legacy root'
+ }
+ }
+
+ if ((tool === 'Bash' || tool === 'PowerShell') && typeof args.command === 'string' && TEST_COMMAND.test(args.command)) {
+ const run = readTestRun(text)
+
+ if (run !== null) {
+ note = `${run.executed} executed${run.skipped > 0 ? `, ${run.skipped} skipped` : ''}${run.failed > 0 ? `, ${run.failed} failed` : ''}`
+
+ // A run in a module's own directory is its result even where its runner left no report file behind.
+ const home = moduleOfCommand(args.command)
+
+ if (home !== null && run.executed + run.skipped > 0) {
+ const seen: TestTotals = { tests: run.executed + run.skipped, failures: run.failed, errors: 0, skipped: run.skipped, reports: 1 }
+
+ state.observed.set(home, seen)
+ }
+ }
+ }
+
+ return extra.length > 0 ? { ...result, context: [...(result.context ?? []), ...extra] } : result
+ } finally {
+ const ms = nowMs() - startMs
+
+ state.activity.running.delete(e.tool_use_id)
+
+ if (agentId === undefined) {
+ const finished: FinishedCall = {
+ tool,
+ subject,
+ isOk: result !== undefined && result.deny === undefined && result.isError !== true,
+ ms,
+ ...(note !== undefined && { note }),
+ }
+
+ state.activity.finished = [...state.activity.finished, finished].slice(-8)
+ }
+
+ if (!QUIET_TOOLS.has(tool) || tool === 'Read') {
+ const wrote = WRITE_TOOLS.has(tool) || tool === 'Bash' || tool === 'PowerShell' || PARENT_TOOLS.has(tool)
+
+ if (wrote) {
+ // A write may have changed the working copy: the next read lists it afresh.
+ for (const key of [...state.cache.keys()]) {
+ if (key.startsWith('changed:')) {
+ state.cache.delete(key)
+ }
+ }
+
+ scheduleRefresh(host)
+ } else if (state.pane.isOpen) {
+ host.invalidate()
+ }
+ }
+ }
+ })
+}
+
+export { PLUGIN_NAME }