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.

• manager.ts (composition root)

  • Creates createInterviewService(ctx, interviewConfig) once.
  • Chooses mode via interview.dashboard === true || interview.port > 0.
  • In dashboard mode:
  • calls tryBecomeDashboard(...) to elect one process as dashboard,
  • non-dashboard processes read auth token via readDashboardAuthFile(port),
  • sessions are registered with /api/register and sync state back via /api/interviews/{id}/state,
  • 10-second fallback polling keeps answer/nudge delivery active if needed.
  • Returns event hooks: registerCommand, handleCommandExecuteBefore, handleEvent.

• 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 and HTML renderer binding.
  • 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.

• 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 (parseInterviewState, 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,
  • 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.