import type { CommandHandler, HandlerContext } from '../../dispatch/dispatch' import { requirePluginPathArg } from '../plugin-cli-output' import { formatPluginDevWatchEvent, type PluginDevWatchApproval } from './plugin-dev-watch-events' import { runPluginDevWatch, type PluginDevWatchHost } from './plugin-dev-watch-loop' import { onPluginDevWatchInterrupt, waitUnlessAborted } from './plugin-dev-watch-process' import { RuntimeClientError, RuntimeRpcFailureError } from '../../runtime/connection/types' import { writeStdoutLine } from '../../output/stdout-line' import type { PluginHostListEntry } from '../../../shared/plugins/plugin-list-entry' import { CLI_BOOLEAN_FLAGS } from '../../../shared/cli/cli-argument-boundary' import { checkPluginDevFolder } from './plugin-dev-watch-check' import { pluginDevWatchConfirmFor } from './plugin-dev-watch-approval' import { pluginDevWatchShotPanel, type PluginDevWatchShotHost } from './plugin-dev-watch-shot' import { defaultPluginShotPath, resolveLocalShotPath, takePluginShotIfShown } from '../view/plugin-view' import { callPlugins, refreshDevTypes, resolveHostPluginPath, translatePluginRpcError, type DevLoadResult, type LogsResult } from '../plugin-runtime' /** The host did not answer: Orca quit, or the network to a remote server dropped. */ export class PluginHostUnreachableError extends Error {} // Why: `dev reload` rejects watch-only flags; the old `--approve` is replaced by the new one. const WATCH_ONLY_FLAGS = new Set(['check', 'shot', 'shot-panel', 'approve']) /** `orca … plugin dev watch ` → `… plugin dev reload `, so approving keeps this session. */ export function devReloadArgs(rawArgs: readonly string[]): string[] { const watch = rawArgs.findIndex((arg, index) => arg === 'watch' && rawArgs[index - 1] === 'dev') const kept: string[] = [] for (let index = 0; index < rawArgs.length; index += 1) { const arg = rawArgs[index] const name = arg.startsWith('--') ? arg.slice(2).split('=')[0] : null if (name === null || !WATCH_ONLY_FLAGS.has(name)) { kept.push(index === watch ? 'reload' : arg) continue } // Same value rule as parseArgs: a non-boolean flag takes the next token unless it is a flag. const next = rawArgs[index + 1] if ( !arg.includes('=') && !CLI_BOOLEAN_FLAGS.has(name) && next !== undefined && !next.startsWith('--') ) { index += 1 } } return kept } function approvalOf(error: unknown): PluginDevWatchApproval | null { if (!(error instanceof RuntimeClientError) || typeof error.data !== 'object' || !error.data) { return null } const data = error.data const fingerprint = 'approvalFingerprint' in data && typeof data.approvalFingerprint === 'string' ? data.approvalFingerprint : null const command = 'command' in data && typeof data.command === 'string' ? data.command : null return fingerprint && command ? { message: error.message, fingerprint, command } : null } /** Why classify before translating: any reply, even an error, proves the host is still there. */ async function pollHost(ctx: HandlerContext, method: string, params?: unknown): Promise { try { return (await ctx.client.call(method, params)).result } catch (error) { if (error instanceof RuntimeRpcFailureError) { throw translatePluginRpcError(ctx, method, error) } throw new PluginHostUnreachableError(error instanceof Error ? error.message : String(error)) } } function bindShotHost( ctx: HandlerContext, shotDir: string, shotPanel: string | boolean | undefined ): PluginDevWatchShotHost { return { panelOf: (entry) => pluginDevWatchShotPanel(entry, typeof shotPanel === 'string' ? shotPanel : undefined), open: async (pluginKey, panelId) => { await callPlugins(ctx, 'plugins.open', { pluginKey, panelId }) }, take: async (pluginKey, panelId) => { const shot = await takePluginShotIfShown(ctx, { pluginKey, panelId, outFor: (id) => defaultPluginShotPath(shotDir, pluginKey, id) }) if ('notShown' in shot) { return { notShown: shot.notShown } } const { path: file, width, height, settled, errors, pendingRequests } = shot return { panelId, path: file, width, height, settled, errors, ...(pendingRequests === undefined ? {} : { pendingRequests }) } } } } export function bindPluginDevWatchHost(ctx: HandlerContext, path: string): PluginDevWatchHost { const approve = ctx.flags.get('approve') const check = ctx.flags.get('check') === true // Why local only: the check renders the folder's code on this machine, not on the Orca host. if (check && ctx.client.isRemote) { throw new RuntimeClientError( 'invalid_argument', '--check renders the plugin on this machine, so it needs a local folder; drop --environment or --check.' ) } const shotFlag = ctx.flags.get('shot') const shotDir = typeof shotFlag === 'string' ? resolveLocalShotPath(ctx, shotFlag) : null const shotPanel = ctx.flags.get('shot-panel') if (shotPanel !== undefined && shotDir === null) { throw new RuntimeClientError('invalid_argument', '--shot-panel needs --shot .') } return { ...(check ? { check: () => checkPluginDevFolder(path) } : {}), ...(shotDir ? { shot: bindShotHost(ctx, shotDir, shotPanel) } : {}), refreshTypes: () => refreshDevTypes(ctx, path), devLoad: (approvalFingerprint) => callPlugins(ctx, 'plugins.devLoad', { path, approvalFingerprint: approvalFingerprint ?? (typeof approve === 'string' ? approve : undefined) }), list: () => pollHost(ctx, 'plugins.list'), logs: (pluginKey, after) => pollHost(ctx, 'plugins.getLogs', { pluginKey, ...(after ? { after } : {}) }), approvalNeeded: async () => { const reloadCtx = { ...ctx, rawArgs: devReloadArgs(ctx.rawArgs ?? []) } try { await pollHost(reloadCtx, 'plugins.devLoad', { path }) return null } catch (error) { const approval = approvalOf(error) if (approval) { return approval } throw error } }, devUnload: async () => { await pollHost(ctx, 'plugins.devUnload', { path }) } } } export const PLUGIN_DEV_WATCH_HANDLERS: Record = { 'plugin dev watch': async (ctx) => { const path = resolveHostPluginPath(ctx, requirePluginPathArg(ctx, 'dir')) process.exitCode = await runPluginDevWatch({ host: bindPluginDevWatchHost(ctx, path), emit: (event) => writeStdoutLine(ctx.json ? JSON.stringify(event) : formatPluginDevWatchEvent(event)), wait: waitUnlessAborted, onInterrupt: onPluginDevWatchInterrupt, exitNow: (code) => process.exit(code), isConnectionLost: (error) => error instanceof PluginHostUnreachableError, confirm: pluginDevWatchConfirmFor(ctx.json) }) } }