feat: enrich install completion summary and stream agent file ops

src/integrations/nextjs/index.ts

@@ -75,6 +75,10 @@ export const config: FrameworkConfig = {
       'Start your development server to test authentication',
       'Visit the WorkOS Dashboard to manage users and settings',
     ],
+    // Client-side sign-in per the AuthKit Next.js guidance: trigger sign-in from
+    // a click handler with refreshAuth (getSignInUrl must not run during render).
+    getSignInSnippet: () =>
+      'Add a sign-in button in a client component: call refreshAuth({ ensureSignedIn: true }) on click',
   },
 };
 

src/lib/adapters/cli-adapter.spec.ts

@@ -222,17 +222,105 @@ describe('CLIAdapter', () => {
       expect(sendEvent).toHaveBeenCalledWith({ type: 'CANCEL' });
     });
 
-    it('shows success summary box on complete', async () => {
+    it('shows structured success summary box on complete', async () => {
       await adapter.start();
       const consoleSpy = vi.spyOn(console, 'log');
 
-      emitter.emit('complete', { success: true, summary: 'All done!' });
+      emitter.emit('complete', {
+        success: true,
+        summary: 'All done!',
+        completion: {
+          integration: 'nextjs',
+          devCommand: 'pnpm run dev',
+          url: 'http://localhost:3000',
+          files: ['app/auth/route.ts'],
+          nextSteps: [
+            'Run `pnpm run dev` to start your dev server',
+            'Open http://localhost:3000 to test authentication',
+          ],
+          docsUrl: 'https://workos.com/docs/user-management/authkit/nextjs',
+          dashboardUrl: 'https://dashboard.workos.com',
+        },
+      });
 
       const output = consoleSpy.mock.calls.map((c) => String(c[0])).join('\n');
       expect(output).toContain('WorkOS AuthKit Installed');
+      expect(output).toContain('pnpm run dev');
+      expect(output).toContain('app/auth/route.ts');
       consoleSpy.mockRestore();
     });
 
+    it('renders persistent step lines for file operations', async () => {
+      await adapter.start();
+      const clack = await import('../../utils/clack.js');
+
+      emitter.emit('agent:start', {});
+      emitter.emit('file:write', { path: '/proj/src/auth.ts', content: 'secret' });
+      emitter.emit('file:edit', { path: '/proj/src/app.ts', oldContent: 'a', newContent: 'b' });
+
+      const stepCalls = vi.mocked(clack.default.log.step).mock.calls.map((c) => String(c[0]));
+      expect(stepCalls.some((s) => s.includes('src/auth.ts'))).toBe(true);
+      expect(stepCalls.some((s) => s.includes('src/app.ts'))).toBe(true);
+    });
+
+    it('dedupes consecutive same-path file operations', async () => {
+      await adapter.start();
+      const clack = await import('../../utils/clack.js');
+
+      emitter.emit('agent:start', {});
+      emitter.emit('file:edit', { path: '/proj/src/app.ts', oldContent: 'a', newContent: 'b' });
+      emitter.emit('file:edit', { path: '/proj/src/app.ts', oldContent: 'b', newContent: 'c' });
+
+      const appCalls = vi.mocked(clack.default.log.step).mock.calls.filter((c) => String(c[0]).includes('src/app.ts'));
+      expect(appCalls).toHaveLength(1);
+    });
+
+    it('does not clobber the phase message back to a generic string', async () => {
+      vi.useFakeTimers();
+      try {
+        await adapter.start();
+        const clack = await import('../../utils/clack.js');
+        const spinnerMock = { start: vi.fn(), stop: vi.fn(), message: vi.fn() };
+        vi.mocked(clack.default.spinner).mockReturnValue(spinnerMock);
+
+        emitter.emit('agent:start', {});
+        emitter.emit('agent:progress', { step: 'Configuring middleware' });
+        vi.advanceTimersByTime(5000);
+
+        const clobbered = spinnerMock.message.mock.calls
+          .map((c) => String(c[0]))
+          .filter((m) => /Running AI agent/.test(m));
+        expect(clobbered).toHaveLength(0);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('restarts the spinner on the last phase message after logging a file op', async () => {
+      await adapter.start();
+      const clack = await import('../../utils/clack.js');
+      const spinnerMock = { start: vi.fn(), stop: vi.fn(), message: vi.fn() };
+      vi.mocked(clack.default.spinner).mockReturnValue(spinnerMock);
+
+      emitter.emit('agent:start', {});
+      emitter.emit('agent:progress', { step: 'Configuring middleware' });
+      emitter.emit('file:write', { path: '/proj/src/auth.ts', content: 'x' });
+
+      expect(spinnerMock.stop).toHaveBeenCalled();
+      expect(spinnerMock.start).toHaveBeenCalledWith('Configuring middleware');
+    });
+
+    it('renders Bash tool calls as step lines (agent:tool)', async () => {
+      await adapter.start();
+      const clack = await import('../../utils/clack.js');
+
+      emitter.emit('agent:start', {});
+      emitter.emit('agent:tool', { kind: 'command', detail: 'pnpm add @workos-inc/authkit-nextjs' });
+
+      const stepCalls = vi.mocked(clack.default.log.step).mock.calls.map((c) => String(c[0]));
+      expect(stepCalls.some((s) => s.includes('pnpm add @workos-inc/authkit-nextjs'))).toBe(true);
+    });
+
     it('shows error summary box on failure complete', async () => {
       await adapter.start();
       const consoleSpy = vi.spyOn(console, 'log');

src/lib/adapters/cli-adapter.ts

@@ -1,5 +1,6 @@
 import type { InstallerAdapter, AdapterConfig } from './types.js';
 import type { InstallerEventEmitter, InstallerEvents } from '../events.js';
+import { relative } from 'node:path';
 import clack from '../../utils/clack.js';
 import chalk from 'chalk';
 import { getConfig } from '../settings.js';
@@ -35,9 +36,14 @@ export class CLIAdapter implements InstallerAdapter {
   // SIGINT handler for cleanup
   private sigIntHandler: (() => void) | null = null;
 
-  // Long-running agent update interval
+  // Long-running agent update interval (kept as a no-op field; never started)
   private agentUpdateInterval: NodeJS.Timeout | null = null;
 
+  // Last phase message shown on the agent spinner, restored after logging above it.
+  private lastAgentMessage = 'Running AI agent...';
+  // Last file path rendered as a step line, to dedupe consecutive same-path ops.
+  private lastFileOp: string | null = null;
+
   constructor(config: AdapterConfig) {
     this.emitter = config.emitter;
     this.sendEvent = config.sendEvent;
@@ -112,6 +118,10 @@ export class CLIAdapter implements InstallerAdapter {
     this.subscribe('config:complete', this.handleConfigComplete);
     this.subscribe('agent:start', this.handleAgentStart);
     this.subscribe('agent:progress', this.handleAgentProgress);
+    // Persistent, append-only log of file operations + tool calls above the spinner.
+    this.subscribe('file:write', this.handleFileWrite);
+    this.subscribe('file:edit', this.handleFileEdit);
+    this.subscribe('agent:tool', this.handleAgentTool);
     this.subscribe('validation:start', this.handleValidationStart);
     this.subscribe('validation:issues', this.handleValidationIssues);
     this.subscribe('validation:complete', this.handleValidationComplete);
@@ -359,22 +369,52 @@ export class CLIAdapter implements InstallerAdapter {
 
   private handleAgentStart = (): void => {
     this.spinner = clack.spinner();
-    this.spinner.start('Running AI agent...');
-
-    // Periodic status updates for long-running operations
-    let dots = 0;
-    this.agentUpdateInterval = setInterval(() => {
-      dots = (dots + 1) % 4;
-      const dotStr = '.'.repeat(dots + 1);
-      this.spinner?.message(`Running AI agent${dotStr}`);
-    }, 2000);
+    this.spinner.start(this.lastAgentMessage);
+    // No setInterval: clack animates its own frames, and the old 2s reset
+    // clobbered the current phase text set by handleAgentProgress.
   };
 
   private handleAgentProgress = ({ step, detail }: InstallerEvents['agent:progress']): void => {
     const message = detail ? `${step}: ${detail}` : step;
+    this.lastAgentMessage = message;
     this.spinner?.message(message);
   };
 
+  /**
+   * Render a persistent line above the running spinner: stop the spinner to
+   * finalize its line, emit the log, then restart it on the last phase message.
+   * Mirrors the existing stop→log and stop→start-new-spinner precedents.
+   */
+  private logAboveSpinner(render: () => void): void {
+    const wasRunning = this.spinner !== null;
+    this.spinner?.stop();
+    this.spinner = null;
+    render();
+    if (wasRunning) {
+      this.spinner = clack.spinner();
+      this.spinner.start(this.lastAgentMessage);
+    }
+  }
+
+  private handleFileWrite = ({ path }: InstallerEvents['file:write']): void => {
+    if (path === this.lastFileOp) return; // dedupe consecutive same-path ops
+    this.lastFileOp = path;
+    const rel = relative(process.cwd(), path);
+    this.logAboveSpinner(() => clack.log.step(`Creating ${chalk.dim(rel)}`));
+  };
+
+  private handleFileEdit = ({ path }: InstallerEvents['file:edit']): void => {
+    if (path === this.lastFileOp) return;
+    this.lastFileOp = path;
+    const rel = relative(process.cwd(), path);
+    this.logAboveSpinner(() => clack.log.step(`Editing ${chalk.dim(rel)}`));
+  };
+
+  private handleAgentTool = ({ detail }: InstallerEvents['agent:tool']): void => {
+    const cmd = detail.length > 80 ? `${detail.slice(0, 77)}…` : detail;
+    this.logAboveSpinner(() => clack.log.step(`Running ${chalk.dim(cmd)}`));
+  };
+
   private handleValidationStart = (): void => {
     this.stopAgentUpdates();
     this.stopSpinner('Agent completed');
@@ -401,12 +441,12 @@ export class CLIAdapter implements InstallerAdapter {
     }
   };
 
-  private handleComplete = ({ success, summary }: InstallerEvents['complete']): void => {
+  private handleComplete = ({ success, summary, completion }: InstallerEvents['complete']): void => {
     this.stopAgentUpdates();
     this.stopSpinner(success ? 'Done' : 'Failed');
 
     console.log('');
-    console.log(renderCompletionSummary(success, summary));
+    console.log(renderCompletionSummary(success, summary, completion));
     console.log('');
 
     // When we scaffolded a fresh app, the install ran in the current dir, so

src/lib/adapters/dashboard-adapter.ts

@@ -1,5 +1,5 @@
 import type { InstallerAdapter, AdapterConfig } from './types.js';
-import type { InstallerEventEmitter, InstallerEvents } from '../events.js';
+import type { InstallerEventEmitter, InstallerEvents, CompletionData } from '../events.js';
 import { renderCompletionSummary } from '../../utils/summary-box.js';
 
 /**
@@ -13,7 +13,7 @@ export class DashboardAdapter implements InstallerAdapter {
   private sendEvent: AdapterConfig['sendEvent'];
   private cleanup: (() => void) | null = null;
   private isStarted = false;
-  private completionData: { success: boolean; summary?: string } | null = null;
+  private completionData: { success: boolean; summary?: string; completion?: CompletionData } | null = null;
 
   constructor(config: AdapterConfig) {
     this.emitter = config.emitter;
@@ -65,8 +65,8 @@ export class DashboardAdapter implements InstallerAdapter {
   /**
    * Capture completion data for display after exit.
    */
-  private handleComplete = ({ success, summary }: InstallerEvents['complete']): void => {
-    this.completionData = { success, summary };
+  private handleComplete = ({ success, summary, completion }: InstallerEvents['complete']): void => {
+    this.completionData = { success, summary, completion };
   };
 
   async stop(): Promise<void> {
@@ -87,7 +87,13 @@ export class DashboardAdapter implements InstallerAdapter {
 
     if (this.completionData) {
       console.log();
-      console.log(renderCompletionSummary(this.completionData.success, this.completionData.summary));
+      console.log(
+        renderCompletionSummary(
+          this.completionData.success,
+          this.completionData.summary,
+          this.completionData.completion,
+        ),
+      );
       console.log();
     }
 

src/lib/adapters/headless-adapter.spec.ts

@@ -329,6 +329,56 @@ describe('HeadlessAdapter', () => {
     });
   });
 
+  describe('file operations', () => {
+    it('writes path-only NDJSON for file:write (never content)', async () => {
+      const adapter = createAdapter();
+      await adapter.start();
+
+      emitter.emit('file:write', { path: 'src/auth.ts', content: 'secret' });
+
+      expect(mockWriteNDJSON).toHaveBeenCalledWith({ type: 'file:write', path: 'src/auth.ts' });
+      const leakedContent = mockWriteNDJSON.mock.calls.some((c) => c[0] && 'content' in (c[0] as object));
+      expect(leakedContent).toBe(false);
+      await adapter.stop();
+    });
+
+    it('writes path-only NDJSON for file:edit (never content)', async () => {
+      const adapter = createAdapter();
+      await adapter.start();
+
+      emitter.emit('file:edit', { path: 'src/app.ts', oldContent: 'a', newContent: 'b' });
+
+      expect(mockWriteNDJSON).toHaveBeenCalledWith({ type: 'file:edit', path: 'src/app.ts' });
+      const leaked = mockWriteNDJSON.mock.calls.some(
+        (c) => c[0] && ('oldContent' in (c[0] as object) || 'newContent' in (c[0] as object)),
+      );
+      expect(leaked).toBe(false);
+      await adapter.stop();
+    });
+
+    it('dedupes consecutive same-path file operations', async () => {
+      const adapter = createAdapter();
+      await adapter.start();
+
+      emitter.emit('file:edit', { path: 'src/app.ts', oldContent: 'a', newContent: 'b' });
+      emitter.emit('file:edit', { path: 'src/app.ts', oldContent: 'b', newContent: 'c' });
+
+      const editCalls = mockWriteNDJSON.mock.calls.filter((c) => (c[0] as { type?: string })?.type === 'file:edit');
+      expect(editCalls).toHaveLength(1);
+      await adapter.stop();
+    });
+
+    it('writes agent:tool NDJSON for surfaced commands', async () => {
+      const adapter = createAdapter();
+      await adapter.start();
+
+      emitter.emit('agent:tool', { kind: 'command', detail: 'ls' });
+
+      expect(mockWriteNDJSON).toHaveBeenCalledWith({ type: 'agent:tool', kind: 'command', detail: 'ls' });
+      await adapter.stop();
+    });
+  });
+
   describe('terminal events', () => {
     it('writes complete event', async () => {
       const adapter = createAdapter();
@@ -345,6 +395,38 @@ describe('HeadlessAdapter', () => {
       await adapter.stop();
     });
 
+    it('spreads structured completion fields into the complete event when present', async () => {
+      const adapter = createAdapter();
+      await adapter.start();
+
+      emitter.emit('complete', {
+        success: true,
+        summary: 'ok',
+        completion: {
+          integration: 'nextjs',
+          devCommand: 'pnpm run dev',
+          url: 'http://localhost:3000',
+          files: ['a.ts'],
+          nextSteps: ['x'],
+          docsUrl: 'https://d',
+          dashboardUrl: 'https://dash',
+        },
+      });
+
+      expect(mockWriteNDJSON).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'complete',
+          success: true,
+          integration: 'nextjs',
+          devCommand: 'pnpm run dev',
+          url: 'http://localhost:3000',
+          files: ['a.ts'],
+          nextSteps: ['x'],
+        }),
+      );
+      await adapter.stop();
+    });
+
     it('writes error event', async () => {
       const adapter = createAdapter();
       await adapter.start();