oh-my-opencode-slim/src/interview/codemap.md

src/interview/

Responsibility

• Implement the /interview command with session prompt orchestration, interview markdown persistence, and a local HTTP interface.
• Run in one of two modes:
  • per-session server mode (default)
  • shared dashboard mode (for multi-process/session sharing).
• Keep interview lifecycle synchronized between:
  • in-memory interview/session maps,
  • markdown artifacts under outputFolder,
  • dashboard cache entries for resume/recovery.

Design

• manager.ts is the composition root and returns:
  • registerCommand
  • handleCommandExecuteBefore
  • handleEvent
• It creates one createInterviewService(ctx, interviewConfig) and selects mode via:
  • interview.dashboard === true || interview.port > 0.

createInterviewService (service.ts)

• Owns interview orchestration state:
  • interviewsById, activeInterviewIds, sessionBusy, fileCache.
• Creates/resumes interviews via:
  • resolveExistingInterviewPath, createInterview, resumeInterview.
• Ensures markdown and URLs are prepared with document.ts helpers, then notifies users with notifyInterviewUrl.
• Re-hydrates interview state from messages via syncInterview:
  • loads new messages,
  • parses latest <interview_state> using parseAssistantState / findLatestAssistantState (parser.ts) with zod-backed validation,
  • rebuilds fallback state when needed,
  • computes mode (awaiting-agent, awaiting-user, completed, error, abandoned).
• Handles UI-facing mutation:
  • submitAnswers validates active questions and injects answer prompts via session.promptAsync.
  • handleNudgeAction injects either continuation questions or finalization directives.
• Handles OpenCode events:
  • session.status updates sessionBusy,
  • session.deleted marks active interview as abandoned and cleans the maps.

createInterviewServer (server.ts)

• Lightweight HTTP server used in per-session mode and for rendering UI views.
• Routes:
  • GET / and GET /api/interviews (dashboard list APIs)
  • GET /interview/{id} (interview page)
  • GET /api/interviews/{id}/state
  • POST /api/interviews/{id}/answers
  • POST /api/interviews/{id}/nudge
• Converts service errors into HTTP status (400/404/409/500) and delegates rendering to ui.ts.

dashboard.ts

• Implements shared dashboard process behavior and transport contract.
• createDashboardServer maintains:
  • random auth token and local auth file (.dashboard-<port>.json),
  • session registry, manual/discovered folders, and TTL-scoped session state cache,
  • pending answers/nudge queues with consume-on-read semantics.
• Adds resilience:
  • rebuildFromFiles() reconstructs state from markdown when sessions rejoin,
  • session discovery via session client + folder scanners,
  • periodic cleanup of terminal interview states.
• Public endpoints include:
  • GET /api/health, /api/settings, /api/sessions, /api/files,
  • POST /api/register, /api/interviews (create), /api/interviews/{id}/state,
  • /pending and /nudge GET/POST paths for agent/browser sync.

Supporting modules

• document.ts: path normalization, markdown creation/rewrite/read, and frontmatter/title/summary extraction.
• parser.ts: parseInterviewState + findLatestAssistantState state extraction pipeline.
• prompts.ts: command/answer/nudge prompt builders.
• helpers.ts: request parsing and HTTP response helpers.
• types.ts: domain contracts and zod schemas (InterviewRecord, InterviewState, InterviewStateEntry, RawInterviewStateSchema, RawQuestionSchema).

Flow

• src/index.ts initializes interview plugin integration through createInterviewManager(ctx, config).

• Per-session mode (dashboard false / port=0):

  • service built, output folder resolved from interview.outputFolder,
  • server started lazily through createInterviewServer({ port: 0 }),
  • manager forwards hooks directly to service callbacks.

• Dashboard mode (dashboard true or port > 0):

  1. createInterviewManager calls tryBecomeDashboard.
  2. If elected, process becomes dashboard:
     • keep in-process cache via statePushCallback and setOnInterviewCreated,
     • self-register and refresh directories with discoverSessionDirectories + refreshFiles,
     • expose auth token for sibling sessions.
  3. If not elected, process becomes session:
     • reads token via readDashboardAuthFile,
     • registers via POST /api/register,
     • pushes state to dashboard via POST /api/interviews/{id}/state,
     • sends newly created interview metadata via POST /api/interviews,
     • starts periodic poll timer (10s) for /pending and /nudge.
  4. If dashboard probe fails after retry, it falls back to local per-session server.

• handleCommandExecuteBefore:

  • blank argument with no active interview → asks user for idea,
  • matching slug/path → resume flow,
  • otherwise create new interview and inject kickoff prompt.

• handleEvent:

  • on session.status.idle: consume pending dashboard actions then refresh state,
  • on session.deleted: unregister session and remove linked dashboard entries.

Integration

• All runtime calls remain through manager methods returned to src/index.ts.
• Integrates directly with OpenCode session client for message reads and prompt injection.
• Outputs are surfaced to users by sending interview URLs back through the same session prompt stream.
• Dashboard and server flows are validated in src/interview/*test.ts.