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

src/interview/

Responsibility

• Implement the /interview command flow:
  • command registration and pre-exec interception,
  • interactive stateful interview prompts,
  • markdown document generation/persistence,
  • local HTTP UI server and shared dashboard mode.
• Keep interview lifecycle synchronized across:
  • in-memory session/interview maps,
  • markdown artifacts under outputFolder,
  • dashboard cache used for cross-process recovery and browser polling.
• Support two runtime modes:
  • per-session mode (local interview server)
  • dashboard mode (distributed cache + shared interview pages).

Design

• index.ts exports createInterviewManager.

• runtime.ts defines the interview-only session boundary (messages, notify, continue, and rename). v1 uses nested SDK calls (createV1InterviewSessionRuntime); v2 supplies a context-backed implementation without expanding the global client shim.

• manager.ts (composition root)

  • Chooses mode via the shared pure computeInterviewMode (also used by the v2 interview bridge): interview.dashboard === true || interview.port > 0:
  • per-session mode → createPerSessionInterviewServer (session-server.ts)
  • dashboard mode → createDashboardManager (dashboard-manager.ts)
  • Returns event hooks: registerCommand, handleCommandExecuteBefore, handleEvent, dispose.

• session-server.ts

  • Per-session composition: binds a lazy createInterviewServer({ port: 0 }) to a single createInterviewService, wiring command/event hooks and cleanup.

• dashboard-manager.ts

  • Dashboard composition: creates the dashboard server and service, calls tryBecomeDashboard(...) to elect one process as dashboard, non-dashboard processes read auth token via readDashboardAuthFile(port), registers/unregisters sessions over HTTP, and pushes state back via /api/interviews/{id}/state; 10-second fallback polling keeps answer/nudge delivery active if needed.

• createInterviewService (service.ts)

  • Manages interview domain maps:
  • interviewsById, activeInterviewIds, sessionBusy, sessionModel.
  • Creates and resumes interviews:
  • resolveExistingInterviewPath, createInterview, resumeInterview.
  • Syncs state from session messages:
  • loads messages,
  • extracts assistant state via findLatestAssistantState,
  • fallbacks through buildFallbackState when needed,
  • rewrites markdown with rewriteInterviewDocument.
  • Injects prompts:
  • kickoff (buildKickoffPrompt),
  • resume (buildResumePrompt),
  • answer/nudge handling (buildAnswerPrompt, handleNudgeAction).
  • Handles events:
  • session.status updates busy tracking,
  • session.deleted marks interview abandoned and drains maps.
  • Pushes updates:
  • onStateChange callback for dashboard mode,
  • onInterviewCreated callback for immediate registration,
  • optional openBrowser for initial UI open.

• createInterviewServer (server.ts)

  • Owns the per-session HTTP endpoints; HTML rendering lives in ui.ts.
  • createInterviewServerDeps(service, outputFolder, port) builds the service-delegating deps object shared by the per-session server, the dashboard fallback server, and the v2 interview bridge.
  • Supports:
  • GET /, GET /api/interviews, GET /interview/{id}
  • GET /api/interviews/{id}/state
  • POST /api/interviews/{id}/answers
  • POST /api/interviews/{id}/nudge
  • Maps domain errors to HTTP status in getSubmissionStatus.

• ui.ts

  • HTML/JS renderers for interview pages (list/detail), shared client-side helpers (clipboard, polling), and the dashboard brand UI; uses escapeHtml from src/utils/escape-html.ts.

• dashboard.ts

  • Implements a shared dashboard server and state cache.
  • Auth path:
  • random token written to ${XDG_DATA_HOME}/opencode/.dashboard-<port>.json,
  • validated via cookie, query token, or Bearer header.
  • In-memory state/cache contracts:
  • sessions registry,
  • stateCache keyed by interview ID,
  • pending answers and nudge actions with consume-on-read semantics.
  • Recovery/scan:
  • periodic rebuildFromFiles() from markdown frontmatter,
  • session directory discovery via SDK + manual folders,
  • file scanning in known directories and cached file lists.
  • TTL cleanup removes terminal states after 24h.

• Supporting modules:

  • document.ts: markdown/file helpers (slugify, path resolution, frontmatter, title/summary extraction).
  • parser.ts: assistant state parse pipeline (parseAssistantState, findLatestAssistantState, buildFallbackState).
  • prompts.ts: prompt templates for create/resume/answer/nudge.
  • helpers.ts: request parsing and HTML/JSON response helpers.
  • types.ts: domain schemas and interview contracts.

Flow

• src/index.ts wires this folder through createInterviewManager(ctx, config).

• Per-session mode

  • service created and bound to a lazy createInterviewServer({ port: 0 }),
  • command hook calls flow directly into service.

• Dashboard mode

  1. createInterviewManager invokes tryBecomeDashboard.
  2. Dashboard election succeeds:
     • dashboard keeps local cache callbacks (setStatePushCallback, setOnInterviewCreated),
     • self-registers session directory and rebuilds file-derived state.
  3. Election fails:
     • process becomes client session,
     • reads token file,
     • registers with dashboard,
     • pushes state + interview creation over HTTP,
     • polls /pending and /nudge on idle.
  4. If probe+fallback fails twice, manager falls back to per-session server.

• handleCommandExecuteBefore

  • blank input with no active interview starts ideation,
  • matching slug/path resumes an existing interview only for its durable frontmatter owner session,
  • otherwise creates a new interview and injects kickoff prompt.

• handleEvent

  • on session.status: idle:
  • consume dashboard pending answers/nudge first,
  • then refresh interview state so sessionBusy is reflected accurately.
  • on session.deleted:
  • unregisters session from the dashboard and local bookkeeping.

Integration

• Used by src/index.ts as the interview plugin module.
• Uses OpenCode SDK session APIs for messages, prompts, and status events.
• Uses local HTTP server contracts for:
  • dashboard browsing,
  • browser ↔ session sync endpoints,
  • manual file/discovery settings.
• Existing tests cover service, parser, manager, server, dashboard, and helpers under src/interview/*.test.ts.

Repaired lifecycle details

• The interview-only runtime.ts boundary owns message reads, notifications, orchestrator continuation, and session rename operations. The v2 bridge uses this boundary instead of expanding the global client shim.
• After confirm-complete, the next clean assistant response is persisted with rewriteInterviewDocumentWithFinalSpec only after an idle/text-ended completion event; a stream prefix cannot overwrite the final markdown.
• Dashboard clients register at /api/register, unregister at /api/unregister, and receive 202 {"status":"queued"} for deferred browser submissions. Session polling claims each queued value and must acknowledge it after service delivery; rejected deliveries roll the claim back without clearing the answer, chat message, block comment, or nudge.
• Markdown documents persist their owning sessionID in frontmatter. A different session cannot resume or mutate an owned document, while the original session can resume it across plugin processes.