diff --git a/src/lib/file-watcher.ts b/src/lib/file-watcher.ts new file mode 100644 index 000000000..1d3d07cc8 --- /dev/null +++ b/src/lib/file-watcher.ts @@ -0,0 +1,182 @@ +/** + * JSON file watcher shared by runner and UI machinery. + * + * `fs.watch` alone is unreliable for atomic-rename writes, so the watcher + * pairs it with a continuous mtime-polled re-read. The poll catches missed + * events; the watch keeps latency low when it does fire. + */ + +import * as fs from 'fs'; +import { basename, dirname } from 'node:path'; +import { logToFile } from '@utils/debug'; + +const DEFAULT_POLL_INTERVAL_MS = 5000; +const DEFAULT_ATTACH_RETRY_INTERVAL_MS = 1000; +const DEFAULT_WATCH_DEBOUNCE_MS = 25; + +export interface FileWatcherHandle { + refresh(): void; + stop(): void; +} + +export interface FileWatcherOptions { + /** ms between mtime checks once the file exists. */ + pollIntervalMs?: number; + /** ms between attach attempts while waiting for the file to appear. */ + attachRetryIntervalMs?: number; + /** ms to coalesce duplicate filesystem events. */ + watchDebounceMs?: number; + /** Ignore the file that exists when the watcher starts until it changes. */ + ignoreInitialFile?: boolean; + /** Refuse to read files larger than this many bytes. */ + maxFileSizeBytes?: number; +} + +/** Watch `path` for JSON updates and call `onUpdate(parsed)` whenever the + * file's mtime changes and the contents are valid JSON. Caller must invoke + * `handle.stop()` to release the watcher. */ +export function startFileWatcher( + path: string, + onUpdate: (parsed: unknown) => void, + options: FileWatcherOptions = {}, +): FileWatcherHandle { + const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS; + const attachRetryIntervalMs = + options.attachRetryIntervalMs ?? DEFAULT_ATTACH_RETRY_INTERVAL_MS; + const watchDebounceMs = options.watchDebounceMs ?? DEFAULT_WATCH_DEBOUNCE_MS; + + const watchers: fs.FSWatcher[] = []; + const intervals: Array> = []; + const targetDir = dirname(path); + const targetName = basename(path); + let lastMtimeMs = 0; + let ignoredInitialSignature: string | null = null; + let watchDebounceTimer: ReturnType | null = null; + let lastReadErrorSignature: string | null = null; + let stopped = false; + + const signature = (stat: fs.Stats): string => + `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`; + + if (options.ignoreInitialFile) { + try { + const stat = fs.lstatSync(path); + if (stat.isFile() && !stat.isSymbolicLink()) { + ignoredInitialSignature = signature(stat); + } + } catch { + // No initial file to ignore. + } + } + + const logReadError = (errorSignature: string, message: string) => { + if (lastReadErrorSignature === errorSignature) return; + lastReadErrorSignature = errorSignature; + logToFile(`[file-watcher] ${message}: ${path}`); + }; + + const read = (force = false) => { + let stat: fs.Stats; + try { + stat = fs.lstatSync(path); + } catch { + return; + } + + if (!stat.isFile() || stat.isSymbolicLink()) return; + const fileSignature = signature(stat); + + try { + if (ignoredInitialSignature) { + if (fileSignature === ignoredInitialSignature) return; + ignoredInitialSignature = null; + } + if ( + options.maxFileSizeBytes !== undefined && + stat.size > options.maxFileSizeBytes + ) { + logReadError( + `oversized:${fileSignature}`, + `refusing oversized JSON file (${stat.size} bytes, limit ${options.maxFileSizeBytes} bytes)`, + ); + return; + } + if (!force && stat.mtimeMs === lastMtimeMs) return; + lastMtimeMs = stat.mtimeMs; + const parsed: unknown = JSON.parse(fs.readFileSync(path, 'utf-8')); + lastReadErrorSignature = null; + onUpdate(parsed); + } catch (error) { + logReadError( + `invalid:${fileSignature}:${String(error)}`, + `could not read valid JSON (${String(error)})`, + ); + } + }; + + const scheduleRead = () => { + if (stopped) return; + if (watchDebounceTimer) clearTimeout(watchDebounceTimer); + watchDebounceTimer = setTimeout(() => { + watchDebounceTimer = null; + read(true); + }, watchDebounceMs); + }; + + const attachWatch = () => { + watchers.push( + fs.watch(targetDir, (_eventType, filename) => { + if (filename == null || filename.toString() === targetName) { + scheduleRead(); + } + }), + ); + }; + + intervals.push(setInterval(() => read(), pollIntervalMs)); + + try { + attachWatch(); + // Defer the initial callback until the caller has received the handle, so + // callbacks that stop their watcher cannot race handle assignment. + queueMicrotask(() => { + if (!stopped) read(true); + }); + } catch { + // Parent directory does not exist yet. Polling still covers a later file; + // retry attaching the low-latency directory watcher until it appears. + const attachInterval = setInterval(() => { + try { + fs.accessSync(targetDir); + clearInterval(attachInterval); + const idx = intervals.indexOf(attachInterval); + if (idx >= 0) intervals.splice(idx, 1); + attachWatch(); + read(true); + } catch { + // Still waiting. + } + }, attachRetryIntervalMs); + intervals.push(attachInterval); + } + + return { + refresh() { + if (stopped) return; + if (watchDebounceTimer) { + clearTimeout(watchDebounceTimer); + watchDebounceTimer = null; + } + read(true); + }, + stop() { + stopped = true; + if (watchDebounceTimer) { + clearTimeout(watchDebounceTimer); + watchDebounceTimer = null; + } + for (const watcher of watchers) watcher.close(); + for (const interval of intervals) clearInterval(interval); + }, + }; +} diff --git a/src/lib/programs/posthog-integration/index.ts b/src/lib/programs/posthog-integration/index.ts index 02e10b4d1..1b504349c 100644 --- a/src/lib/programs/posthog-integration/index.ts +++ b/src/lib/programs/posthog-integration/index.ts @@ -21,6 +21,7 @@ import type { HostResolution } from '@lib/host-resolution'; import { POSTHOG_INTEGRATION_PROGRAM } from './steps.js'; import { getContentBlocks } from './content/index.js'; import { buildCodingAgentPrompt } from './handoff.js'; +import { EVENT_PLAN_FILE } from './constants.js'; const DASHBOARD_DEEP_LINK_KEY = 'dashboardDeepLink'; @@ -42,6 +43,7 @@ export const posthogIntegrationConfig: ProgramConfig = { description: 'Set up PostHog SDK integration', id: 'posthog-integration', agentFlow: 'integration-v2', + eventPlanFile: EVENT_PLAN_FILE, steps: POSTHOG_INTEGRATION_PROGRAM, getContentBlocks, // Basic integration runs without structured user input; drop wizard_ask diff --git a/src/lib/programs/program-step.ts b/src/lib/programs/program-step.ts index 42a28a92c..532ae74e1 100644 --- a/src/lib/programs/program-step.ts +++ b/src/lib/programs/program-step.ts @@ -241,6 +241,13 @@ export interface ProgramConfig { * read it synchronously without resolving a deferred `run` function. */ reportFile?: string; + /** + * Agent-authored event-plan artifact to mirror into the wizard session. + * Relative to `session.installDir`. Programs that do not produce an event + * plan leave this unset, so generic runner machinery does not inspect a + * stale or unrelated `.posthog-events.json` file. + */ + eventPlanFile?: string; /** * LearnCard deck rendered in the shared `RunScreen` while the agent * runs. Lives at `/content/index.tsx` by convention. diff --git a/src/lib/runners/run-non-interactive.ts b/src/lib/runners/run-non-interactive.ts index 1c2f2395d..702c0e3e9 100644 --- a/src/lib/runners/run-non-interactive.ts +++ b/src/lib/runners/run-non-interactive.ts @@ -6,6 +6,7 @@ import { analytics } from '@utils/analytics'; import { resolveNoTelemetry } from './resolve-no-telemetry'; import type { WizardStore } from '@ui/tui/store'; import type { TaskStreamPush } from '@lib/task-stream/task-stream-push'; +import { join } from 'node:path'; import type { OutroData, RunPhase as RunPhaseT } from '@lib/wizard-session'; /** @@ -153,6 +154,9 @@ export function runNonInteractive( onError: (e) => logToFile('[headless task-stream]', e.message), }), ], + eventPlanPath: config.eventPlanFile + ? join(session.installDir, config.eventPlanFile) + : undefined, enabled: !session.noTelemetry, }); taskStream.attach(); diff --git a/src/lib/runners/run-wizard.ts b/src/lib/runners/run-wizard.ts index 7885220d3..3b4a2bbef 100644 --- a/src/lib/runners/run-wizard.ts +++ b/src/lib/runners/run-wizard.ts @@ -10,6 +10,7 @@ import type { WizardSession } from '@lib/wizard-session'; import type { TaskStreamPush as TaskStreamPushClass } from '@lib/task-stream/task-stream-push'; import { resolveNoTelemetry } from './resolve-no-telemetry'; import { runCleanups } from '@utils/wizard-abort'; +import { join } from 'node:path'; const WIZARD_VERSION = VERSION; @@ -121,6 +122,9 @@ export function runWizard( onError: (err) => logToFile('[task-stream-push]', err.message), }), ], + eventPlanPath: config.eventPlanFile + ? join(session.installDir, config.eventPlanFile) + : undefined, enabled: taskStreamEnabled, }); const activeStream = taskStream; diff --git a/src/lib/task-stream/__tests__/event-plan-watcher.test.ts b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts new file mode 100644 index 000000000..81bde5be2 --- /dev/null +++ b/src/lib/task-stream/__tests__/event-plan-watcher.test.ts @@ -0,0 +1,163 @@ +import { + mkdtempSync, + rmSync, + symlinkSync, + unlinkSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { + EventPlanWatcher, + normalizeEventPlan, +} from '@lib/task-stream/event-plan-watcher'; +import { EVENT_PLAN_FILE } from '@lib/programs/posthog-integration/constants'; +import type { PlannedEvent, WizardStore } from '@ui/tui/store'; + +const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); + +function createStore(installDir: string) { + let eventPlan: PlannedEvent[] = []; + return { + session: { installDir }, + get eventPlan() { + return eventPlan; + }, + setEventPlan(events: PlannedEvent[]) { + eventPlan = events; + }, + } as WizardStore; +} + +describe('EventPlanWatcher', () => { + let installDir: string; + let watcher: EventPlanWatcher | undefined; + + beforeEach(() => { + installDir = mkdtempSync(join(tmpdir(), 'wizard-event-plan-')); + }); + + afterEach(() => { + watcher?.stop(); + watcher = undefined; + rmSync(installDir, { recursive: true, force: true }); + }); + + it('normalizes canonical fields and legacy fallbacks', () => { + expect( + normalizeEventPlan([ + { event_name: 'signed_up', event_description: 'User signs up' }, + { name: 'invited_user', description: 'User sends an invite' }, + { event: 'created_team' }, + { event_name: 42, name: 'valid_fallback' }, + { event_name: 'x'.repeat(401) }, + { event_name: ' ' }, + { description: 'missing name' }, + ]), + ).toEqual([ + { name: 'signed_up', description: 'User signs up' }, + { name: 'invited_user', description: 'User sends an invite' }, + { name: 'created_team', description: '' }, + { name: 'valid_fallback', description: '' }, + ]); + }); + + it('caps event count and description length', () => { + const events = Array.from({ length: 60 }, (_, index) => ({ + event_name: `event_${index}`, + event_description: 'x'.repeat(5000), + })); + + const normalized = normalizeEventPlan(events); + + expect(normalized).toHaveLength(50); + expect(normalized?.[0].description).toHaveLength(4000); + }); + + it('captures the plan when the file is written after startup', async () => { + const store = createStore(installDir); + const path = join(installDir, EVENT_PLAN_FILE); + watcher = new EventPlanWatcher(store, path, { + pollIntervalMs: 30, + }); + watcher.start(); + + writeFileSync( + path, + JSON.stringify([{ event_name: 'completed_onboarding' }]), + ); + await wait(120); + + expect(store.eventPlan).toEqual([ + { name: 'completed_onboarding', description: '' }, + ]); + }); + + it('captures the first non-empty plan once', async () => { + const store = createStore(installDir); + const path = join(installDir, EVENT_PLAN_FILE); + watcher = new EventPlanWatcher(store, path, { + pollIntervalMs: 30, + }); + watcher.start(); + + writeFileSync(path, JSON.stringify([])); + await wait(40); + expect(store.eventPlan).toEqual([]); + + writeFileSync(path, JSON.stringify([{ event_name: 'first_event' }])); + await wait(40); + writeFileSync(path, JSON.stringify([{ event_name: 'later_event' }])); + watcher.refresh(); + + expect(store.eventPlan).toEqual([{ name: 'first_event', description: '' }]); + }); + + it('keeps the last captured plan after the file is deleted', async () => { + const path = join(installDir, EVENT_PLAN_FILE); + const store = createStore(installDir); + watcher = new EventPlanWatcher(store, path, { + pollIntervalMs: 30, + }); + watcher.start(); + writeFileSync(path, JSON.stringify([{ event_name: 'created_report' }])); + await wait(40); + + unlinkSync(path); + await wait(80); + + expect(store.eventPlan).toEqual([ + { name: 'created_report', description: '' }, + ]); + }); + + it('ignores a plan file that predates the current run', () => { + const path = join(installDir, EVENT_PLAN_FILE); + writeFileSync(path, JSON.stringify([{ event_name: 'stale_event' }])); + const store = createStore(installDir); + watcher = new EventPlanWatcher(store, path); + + watcher.start(); + watcher.refresh(); + + expect(store.eventPlan).toEqual([]); + }); + + it('rejects oversized and symbolic-link plan files', () => { + const path = join(installDir, EVENT_PLAN_FILE); + const store = createStore(installDir); + watcher = new EventPlanWatcher(store, path); + watcher.start(); + + writeFileSync(path, JSON.stringify([{ event_name: 'x'.repeat(300_000) }])); + watcher.refresh(); + expect(store.eventPlan).toEqual([]); + + unlinkSync(path); + const target = join(installDir, 'external-plan.json'); + writeFileSync(target, JSON.stringify([{ event_name: 'linked_event' }])); + symlinkSync(target, path); + watcher.refresh(); + expect(store.eventPlan).toEqual([]); + }); +}); diff --git a/src/lib/task-stream/__tests__/task-stream-push.test.ts b/src/lib/task-stream/__tests__/task-stream-push.test.ts index ebdc3c611..2e6155078 100644 --- a/src/lib/task-stream/__tests__/task-stream-push.test.ts +++ b/src/lib/task-stream/__tests__/task-stream-push.test.ts @@ -6,6 +6,10 @@ import type { } from '@lib/task-stream/types'; import type { WizardStore, TaskItem } from '@ui/tui/store'; import { RunPhase } from '@lib/wizard-session'; +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { EVENT_PLAN_FILE } from '@lib/programs/posthog-integration/constants'; type Listener = () => void; @@ -14,6 +18,7 @@ interface MockStoreState { skillId: string | null; tasks: TaskItem[]; eventPlan: unknown[]; + installDir?: string; } function createMockStore(overrides: Partial = {}) { @@ -32,6 +37,7 @@ function createMockStore(overrides: Partial = {}) { runPhase: state.runPhase, skillId: state.skillId, outroData: null, + installDir: state.installDir, }; }, get tasks() { @@ -40,6 +46,10 @@ function createMockStore(overrides: Partial = {}) { get eventPlan() { return state.eventPlan; }, + setEventPlan(eventPlan: unknown[]) { + state.eventPlan = eventPlan; + for (const cb of listeners) cb(); + }, subscribe(cb: Listener) { listeners.push(cb); return () => { @@ -84,6 +94,7 @@ function createPush( opts: { dest?: ReturnType; enabled?: boolean; + eventPlanPath?: string; } = {}, ) { const dest = opts.dest ?? createMockDestination(); @@ -91,6 +102,7 @@ function createPush( store, programId: 'test-program', destinations: [dest], + eventPlanPath: opts.eventPlanPath, enabled: opts.enabled, }); return { push, dest }; @@ -103,6 +115,47 @@ describe('TaskStreamPush', () => { // ── Existing event-sequencing behaviour ──────────────────────── + it('populates the event plan when destination delivery is disabled', async () => { + const installDir = mkdtempSync(join(tmpdir(), 'wizard-headless-plan-')); + const eventPlanPath = join(installDir, EVENT_PLAN_FILE); + const store = createMockStore({ installDir }); + const { push, dest } = createPush(store, { + enabled: false, + eventPlanPath, + }); + + push.attach(); + writeFileSync( + eventPlanPath, + JSON.stringify([{ event_name: 'created_workspace' }]), + ); + await push.shutdown(2000); + + expect(store.eventPlan).toEqual([ + { name: 'created_workspace', description: '' }, + ]); + expect(dest.calls).toHaveLength(0); + + rmSync(installDir, { recursive: true, force: true }); + }); + + it('does not inspect event-plan artifacts unless explicitly configured', () => { + const installDir = mkdtempSync(join(tmpdir(), 'wizard-unrelated-plan-')); + writeFileSync( + join(installDir, EVENT_PLAN_FILE), + JSON.stringify([{ event_name: 'stale_event' }]), + ); + const store = createMockStore({ installDir }); + const { push } = createPush(store); + + push.attach(); + + expect(store.eventPlan).toEqual([]); + + push.detach(); + rmSync(installDir, { recursive: true, force: true }); + }); + describe('event ordering (imperative push)', () => { it('first push sends CREATE', async () => { const store = createMockStore(); @@ -301,7 +354,7 @@ describe('TaskStreamPush', () => { }); describe('spec: enabled=false', () => { - it('attach is a no-op and no destination ever fires', () => { + it('does not subscribe or deliver to destinations', () => { const store = createMockStore({ runPhase: RunPhase.Running }); const { push, dest } = createPush(store, { enabled: false }); @@ -441,6 +494,43 @@ describe('TaskStreamPush', () => { }); describe('spec: shutdown flushes terminal phase', () => { + it('includes the captured event plan in the final Completed push', async () => { + const installDir = mkdtempSync(join(tmpdir(), 'wizard-final-plan-')); + const eventPlanPath = join(installDir, EVENT_PLAN_FILE); + const plan = [ + { name: 'created_dashboard', description: 'User creates a dashboard' }, + ]; + const store = createMockStore({ + installDir, + runPhase: RunPhase.Running, + }); + const { push, dest } = createPush(store, { eventPlanPath }); + + try { + push.attach(); + store._emit(); + await flushMicrotasks(); + + writeFileSync( + eventPlanPath, + JSON.stringify([ + { + event_name: plan[0].name, + event_description: plan[0].description, + }, + ]), + ); + store._setAndEmit({ runPhase: RunPhase.Completed }); + await push.shutdown(2000); + + expect(dest.calls.at(-1)?.[0]).toBe(StreamEvent.Complete); + expect(dest.calls.at(-1)?.[1].event_plan).toEqual({ events: plan }); + } finally { + push.detach(); + rmSync(installDir, { recursive: true, force: true }); + } + }); + it('shutdown awaits one final push when phase is terminal', async () => { const store = createMockStore({ runPhase: RunPhase.Completed }); const { push, dest } = createPush(store); diff --git a/src/lib/task-stream/event-plan-watcher.ts b/src/lib/task-stream/event-plan-watcher.ts new file mode 100644 index 000000000..d04cee77c --- /dev/null +++ b/src/lib/task-stream/event-plan-watcher.ts @@ -0,0 +1,83 @@ +import type { PlannedEvent, WizardStore } from '@ui/tui/store'; +import { + startFileWatcher, + type FileWatcherHandle, + type FileWatcherOptions, +} from '@lib/file-watcher'; + +const MAX_EVENT_PLAN_FILE_BYTES = 256 * 1024; +const MAX_EVENT_COUNT = 50; +const MAX_EVENT_NAME_LENGTH = 400; +const MAX_EVENT_DESCRIPTION_LENGTH = 4000; + +function firstString(...values: unknown[]): string | null { + const value = values.find((candidate) => typeof candidate === 'string'); + return typeof value === 'string' ? value : null; +} + +export function normalizeEventPlan(parsed: unknown): PlannedEvent[] | null { + if (!Array.isArray(parsed)) return null; + + const events: PlannedEvent[] = []; + for (const value of parsed) { + if (events.length >= MAX_EVENT_COUNT) break; + + const entry = + value && typeof value === 'object' + ? (value as Record) + : {}; + const name = firstString(entry.event_name, entry.name, entry.event); + if (!name || !name.trim() || name.length > MAX_EVENT_NAME_LENGTH) continue; + + const description = + firstString(entry.event_description, entry.description) ?? ''; + events.push({ + name, + description: description.slice(0, MAX_EVENT_DESCRIPTION_LENGTH), + }); + } + + return events; +} + +export class EventPlanWatcher { + private handle: FileWatcherHandle | null = null; + private captured = false; + + constructor( + private readonly store: WizardStore, + private readonly path: string, + private readonly options: FileWatcherOptions = {}, + ) {} + + start(): void { + if (this.handle || this.captured) return; + + this.handle = startFileWatcher( + this.path, + (parsed) => { + const events = normalizeEventPlan(parsed); + if (!events || events.length === 0) return; + + this.captured = true; + this.store.setEventPlan(events); + this.stop(); + }, + { + ignoreInitialFile: true, + maxFileSizeBytes: MAX_EVENT_PLAN_FILE_BYTES, + ...this.options, + }, + ); + } + + refresh(): void { + if (this.captured) return; + this.handle?.refresh(); + } + + stop(): void { + this.handle?.stop(); + this.handle = null; + } +} diff --git a/src/lib/task-stream/task-stream-push.ts b/src/lib/task-stream/task-stream-push.ts index 028154199..054004cd7 100644 --- a/src/lib/task-stream/task-stream-push.ts +++ b/src/lib/task-stream/task-stream-push.ts @@ -7,7 +7,7 @@ * - task updates debounced 250ms (trailing edge) * - phase transitions flush immediately, bypass debounce * - RunPhase.Idle skipped (no push) - * - enabled === false attach is a no-op + * - enabled === false destination delivery is disabled * - shutdown(timeoutMs) cancel pending, flush terminal phase * with timeout, never throw * @@ -27,6 +27,7 @@ import { StreamTaskStatus, StreamEvent, } from './types'; +import { EventPlanWatcher } from './event-plan-watcher'; /** Trailing-edge debounce window for non-phase-change emits. */ const DEBOUNCE_MS = 250; @@ -81,7 +82,9 @@ export interface TaskStreamPushOptions { store: WizardStore; programId: string; destinations: TaskStreamDestination[]; - /** When false, `attach` is a no-op and no destination ever fires. */ + /** Optional absolute event-plan path to load into the store once. */ + eventPlanPath?: string; + /** When false, destination subscription/delivery remains disabled. */ enabled?: boolean; } @@ -91,6 +94,7 @@ export class TaskStreamPush { private readonly startedAt: string; private readonly programId: string; private readonly sessionId: string; + private readonly eventPlanWatcher: EventPlanWatcher | null; private enabled: boolean; private created = false; @@ -107,7 +111,11 @@ export class TaskStreamPush { this.programId = sanitizeChannelId(opts.programId); this.destinations = opts.destinations; this.enabled = opts.enabled ?? true; - this.startedAt = secondPrecisionIso(new Date()); + const startedAt = new Date(); + this.eventPlanWatcher = opts.eventPlanPath + ? new EventPlanWatcher(this.store, opts.eventPlanPath) + : null; + this.startedAt = secondPrecisionIso(startedAt); // skillId may not be set yet — fall back to programId so the // session_id is stable for the whole run regardless of when the // program metadata is populated. @@ -118,10 +126,12 @@ export class TaskStreamPush { } /** - * Subscribe to store changes. No-op when `enabled === false`. - * Idempotent — repeat calls are ignored. + * Load the event plan and subscribe to store changes. Destination delivery + * remains disabled when `enabled === false`, but the plan still populates the + * store for local and headless consumers. */ attach(store?: WizardStore): void { + this.eventPlanWatcher?.start(); if (!this.enabled) return; if (this.unsubscribe) return; const target = store ?? this.store; @@ -130,6 +140,7 @@ export class TaskStreamPush { /** Stop subscribing. Does not flush. */ detach(): void { + this.eventPlanWatcher?.stop(); if (this.unsubscribe) { this.unsubscribe(); this.unsubscribe = null; @@ -149,6 +160,7 @@ export class TaskStreamPush { timeoutMs: number = DEFAULT_SHUTDOWN_TIMEOUT_MS, ): Promise { this.shuttingDown = true; + this.eventPlanWatcher?.refresh(); if (this.debounceTimer) { clearTimeout(this.debounceTimer); this.debounceTimer = null; diff --git a/src/ui/headless-ui.ts b/src/ui/headless-ui.ts index 6d1a8da28..740056634 100644 --- a/src/ui/headless-ui.ts +++ b/src/ui/headless-ui.ts @@ -6,8 +6,9 @@ import type { WizardStore } from './tui/store'; * wizard-session sync (`TaskStreamPush`) can observe a headless run. We extend * `LoggingUI` (not `InkUI`) because its blocking/gate methods would wait on a * TUI that never renders; the runner drives phase transitions on the store - * directly, so only the per-run updates (today: the task list) tee through here. - * To stream more later, override `setEventPlan` / `setStage` the same way. + * directly, so only UI-originated per-run updates tee through here. Runner + * machinery loads agent-authored artifacts such as the event plan directly + * into the store. */ export class HeadlessUI extends LoggingUI { constructor(private readonly store: WizardStore) { diff --git a/src/ui/tui/hooks/__tests__/file-watcher.test.ts b/src/ui/tui/hooks/__tests__/file-watcher.test.ts index 8a467d254..4d764222b 100644 --- a/src/ui/tui/hooks/__tests__/file-watcher.test.ts +++ b/src/ui/tui/hooks/__tests__/file-watcher.test.ts @@ -5,6 +5,11 @@ import { startFileWatcher, type FileWatcherHandle, } from '@ui/tui/hooks/file-watcher'; +import { logToFile } from '@utils/debug'; + +vi.mock('@utils/debug', () => ({ + logToFile: vi.fn(), +})); const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); @@ -14,6 +19,7 @@ describe('startFileWatcher', () => { beforeEach(() => { workdir = mkdtempSync(path.join(tmpdir(), 'wizard-fw-')); + vi.mocked(logToFile).mockClear(); }); afterEach(() => { @@ -97,6 +103,22 @@ describe('startFileWatcher', () => { await wait(100); expect(onUpdate).not.toHaveBeenCalled(); + expect(logToFile).toHaveBeenCalledWith( + expect.stringContaining('could not read valid JSON'), + ); + }); + + it('allows an initial update callback to stop its watcher', async () => { + const target = path.join(workdir, 'data.json'); + writeFileSync(target, JSON.stringify({ a: 1 })); + const onUpdate = vi.fn(() => handle?.stop()); + + handle = startFileWatcher(target, onUpdate, { pollIntervalMs: 30 }); + await wait(20); + writeFileSync(target, JSON.stringify({ a: 2 })); + await wait(100); + + expect(onUpdate).toHaveBeenCalledTimes(1); }); it('stop() halts polling and watchers', async () => { @@ -132,4 +154,45 @@ describe('startFileWatcher', () => { await wait(150); expect(onUpdate.mock.calls.at(-1)?.[0]).toEqual({ v: 2 }); }); + + it('refreshes synchronously before shutdown', () => { + const onUpdate = vi.fn(); + const target = path.join(workdir, 'data.json'); + handle = startFileWatcher(target, onUpdate, { pollIntervalMs: 10_000 }); + writeFileSync(target, JSON.stringify({ final: true })); + + handle.refresh(); + + expect(onUpdate).toHaveBeenCalledWith({ final: true }); + }); + + it('ignores a pre-existing file until it changes', () => { + const onUpdate = vi.fn(); + const target = path.join(workdir, 'data.json'); + writeFileSync(target, JSON.stringify({ stale: true })); + handle = startFileWatcher(target, onUpdate, { + ignoreInitialFile: true, + }); + + handle.refresh(); + expect(onUpdate).not.toHaveBeenCalled(); + + writeFileSync(target, JSON.stringify({ current: true })); + handle.refresh(); + expect(onUpdate).toHaveBeenCalledWith({ current: true }); + }); + + it('enforces file-size bounds', () => { + const onUpdate = vi.fn(); + const target = path.join(workdir, 'data.json'); + + writeFileSync(target, JSON.stringify({ oversized: 'x'.repeat(100) })); + handle = startFileWatcher(target, onUpdate, { maxFileSizeBytes: 20 }); + handle.refresh(); + + expect(onUpdate).not.toHaveBeenCalled(); + expect(logToFile).toHaveBeenCalledWith( + expect.stringContaining('refusing oversized JSON file'), + ); + }); }); diff --git a/src/ui/tui/hooks/file-watcher.ts b/src/ui/tui/hooks/file-watcher.ts index 1167a3acb..5dd272aa0 100644 --- a/src/ui/tui/hooks/file-watcher.ts +++ b/src/ui/tui/hooks/file-watcher.ts @@ -1,92 +1,8 @@ -/** - * File watcher (UI concern). - * - * `fs.watch` alone is unreliable for atomic-rename writes (which is how Claude - * rewrites JSON files), so the watcher pairs `fs.watch` with a continuous - * mtime-polled re-read. The poll catches missed events; the watch keeps - * latency low when it does fire. We dedupe with `mtimeMs` so steady-state - * polls cost a single `stat`. - * - * Screens that need to mirror an agent-emitted JSON file into the store call - * `useFileWatcher(absolutePath, onUpdate)`; the watcher starts on mount and - * tears down on unmount. - */ - -import * as fs from 'fs'; import { useEffect } from 'react'; +import { startFileWatcher, type FileWatcherOptions } from '@lib/file-watcher'; -const DEFAULT_POLL_INTERVAL_MS = 5000; -const DEFAULT_ATTACH_RETRY_INTERVAL_MS = 1000; - -export interface FileWatcherHandle { - stop(): void; -} - -export interface FileWatcherOptions { - /** ms between mtime checks once the file exists. */ - pollIntervalMs?: number; - /** ms between attach attempts while waiting for the file to appear. */ - attachRetryIntervalMs?: number; -} - -/** Watch `path` for JSON updates and call `onUpdate(parsed)` whenever the - * file's mtime changes and the contents are valid JSON. Caller must invoke - * `handle.stop()` to release the watcher. */ -export function startFileWatcher( - path: string, - onUpdate: (parsed: unknown) => void, - options: FileWatcherOptions = {}, -): FileWatcherHandle { - const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS; - const attachRetryIntervalMs = - options.attachRetryIntervalMs ?? DEFAULT_ATTACH_RETRY_INTERVAL_MS; - - const watchers: fs.FSWatcher[] = []; - const intervals: Array> = []; - let lastMtimeMs = 0; - - const read = (force = false) => { - try { - const stat = fs.statSync(path); - if (!force && stat.mtimeMs === lastMtimeMs) return; - lastMtimeMs = stat.mtimeMs; - const parsed: unknown = JSON.parse(fs.readFileSync(path, 'utf-8')); - onUpdate(parsed); - } catch { - // File missing or not yet valid JSON. - } - }; - - intervals.push(setInterval(() => read(), pollIntervalMs)); - - try { - watchers.push(fs.watch(path, () => read(true))); - read(true); - } catch { - // File doesn't exist yet — retry attaching the watch periodically until - // it appears. The poll above already covers updates; this just upgrades - // latency once the file shows up. - const attachInterval = setInterval(() => { - try { - fs.accessSync(path); - clearInterval(attachInterval); - const idx = intervals.indexOf(attachInterval); - if (idx >= 0) intervals.splice(idx, 1); - watchers.push(fs.watch(path, () => read(true))); - } catch { - // Still waiting. - } - }, attachRetryIntervalMs); - intervals.push(attachInterval); - } - - return { - stop() { - for (const w of watchers) w.close(); - for (const i of intervals) clearInterval(i); - }, - }; -} +export { startFileWatcher } from '@lib/file-watcher'; +export type { FileWatcherHandle, FileWatcherOptions } from '@lib/file-watcher'; /** React hook wrapping `startFileWatcher`. Starts on mount, stops on unmount * or when `path` changes. `onUpdate` and `options` are captured at mount diff --git a/src/ui/tui/screens/RunScreen.tsx b/src/ui/tui/screens/RunScreen.tsx index da78ce378..ecb10c175 100644 --- a/src/ui/tui/screens/RunScreen.tsx +++ b/src/ui/tui/screens/RunScreen.tsx @@ -7,7 +7,6 @@ */ import { useMemo, useSyncExternalStore } from 'react'; -import { join } from 'node:path'; import { Box } from 'ink'; import type { WizardStore } from '@ui/tui/store'; import { @@ -23,8 +22,6 @@ import { ADDITIONAL_FEATURE_LABELS } from '@lib/wizard-session'; import { LearnCard } from '@ui/tui/components/LearnCard'; import { TipsCard } from '@ui/tui/components/TipsCard'; import { useStdoutDimensions } from '@ui/tui/hooks/useStdoutDimensions'; -import { useFileWatcher } from '@ui/tui/hooks/file-watcher'; -import { EVENT_PLAN_FILE } from '@lib/programs/posthog-integration/index'; import { getProgramConfig } from '@lib/programs/program-registry'; import { getContentBlocks as getSkillContentBlocks } from '@lib/programs/agent-skill/content/index'; @@ -41,24 +38,6 @@ export const RunScreen = ({ store }: RunScreenProps) => { () => store.getSnapshot(), ); - // Mirror the agent's `.posthog-events.json` plan into the store so the - // Event plan tab appears as soon as the agent emits the file. The skill - // tells the agent to use `event_name`/`event_description` (the canonical - // form); `name`/`event`/`description` are legacy fallbacks for skills or - // one-off runs that drift. Drop any entry that still ends up nameless so - // the outro never shows blank bullets. - useFileWatcher(join(store.session.installDir, EVENT_PLAN_FILE), (parsed) => { - if (!Array.isArray(parsed)) return; - store.setEventPlan( - parsed - .map((e: Record) => ({ - name: (e.event_name ?? e.name ?? e.event ?? '') as string, - description: (e.event_description ?? e.description ?? '') as string, - })) - .filter((e) => e.name), - ); - }); - const [columns] = useStdoutDimensions(); const progressItems: ProgressItem[] = store.tasks.map((t) => ({