feat: REPL interactive mode

[enaboapps]

Summary

• Replaces the bare timberlogs invocation with a persistent REPL session
• timberlogs repl also works as an alias
• Persistent header shows version, org name (fetched async), and available commands at a glance
• Commands work exactly like the CLI — same flags, same output
• Interactive commands (logs, stats, flows show) take over the screen with keyboard nav; q returns to the prompt
• Static commands (whoami, flows, config list) render inline in the scroll buffer
• login runs the device flow inline (no subprocess); logout is synchronous
• Command history persisted to ~/.config/timberlogs/history.json (max 500, ↑/↓ to navigate)
• Fix: CMD window no longer flashes on Windows when opening the browser for login

New files

• src/lib/history.ts — history load/save
• src/lib/replParser.ts — shell tokenizer → ParsedCommand
• src/lib/flagParser.ts — string[] args → typed options via Zod v3
• src/components/ReplOutput.tsx — scroll buffer entry renderer
• src/components/ReplPrompt.tsx — prompt line with history navigation
• src/components/ReplView.tsx — root REPL component
• src/components/commandViews/ — async fetch adapters per command
• src/commands/repl.tsx — alias entry point

Changed files

• src/commands/index.tsx — replaced static help with <ReplView />
• src/components/LogTable.tsx, StatsView.tsx, FlowTimeline.tsx — added onBack? prop so q returns to REPL instead of process.exit(0)
• src/commands/login.tsx, src/components/commandViews/LoginView.tsx — use spawn with windowsHide: true to suppress CMD flash on Windows
• docs/cli/overview.mdx — REPL section added

Test plan

• timberlogs launches REPL with header showing version + org name
• timberlogs repl also launches REPL
• logs, stats, flows show take over screen; q returns to prompt
• whoami, flows render inline in scroll buffer
• login runs device flow inline, header updates with org name after auth
• logout clears session, header updates to not-logged-in state
• ↑/↓ navigates history; history persists across sessions
• clear empties scroll buffer; exit quits
• config reset --force resets config; without --force shows error
• No CMD window flash on Windows during login

Summary by CodeRabbit

• New Features

  • Interactive REPL mode when running the CLI with no arguments: persistent history, command help, multi-view interactive commands (logs, flows, stats, whoami, login/logout), and keyboard navigation (press q to go back/exit).
  • Config management: config reset supports --force for non-interactive deletion; REPL requires --force for reset.

• Bug Fixes

  • Improved behavior opening URLs in the system browser.

• Documentation

  • Updated CLI overview with REPL usage, examples, and config details.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 41a0bc8d-2b8b-4d14-92f6-e00c261d3f04

📥 Commits

Reviewing files that changed from the base of the PR and between 5f768b3 and 8df2b66.

📒 Files selected for processing (3)

• src/components/ReplView.tsx
• src/components/commandViews/FlowShowView.tsx
• src/lib/flagParser.ts

---

📝 Walkthrough

Walkthrough

Adds a new interactive REPL mode and associated UI, command parsing, flag parsing, history persistence, multiple command views (login, whoami, logs, flows, stats, flow show), and navigation/back callbacks; updates CLI entry to render the REPL and adjusts browser-open behavior.

Changes

Cohort / File(s)	Summary
Documentation docs/cli/overview.mdx	Adds REPL section and examples; updates config command examples (list/reset/--force) and notes REPL-specific confirmation behavior.
REPL Core Components src/components/ReplView.tsx, src/components/ReplPrompt.tsx, src/components/ReplOutput.tsx	Implements main REPL UI, input prompt with history navigation, and discriminated output rendering; state, history persistence, token/org resolution, command dispatching, and phase-driven views added.
Command Views src/components/commandViews/LoginView.tsx, src/components/commandViews/WhoamiView.tsx, src/components/commandViews/LogsView.tsx, src/components/commandViews/FlowsView.tsx, src/components/commandViews/FlowShowView.tsx, src/components/commandViews/StatsViewCmd.tsx	Adds six new command view components that fetch/validate API responses, compute presentation data, and signal results via onDone/onError/onBack callbacks.
Command Entry Points src/commands/index.tsx, src/commands/repl.tsx, src/commands/login.tsx	Index route now renders ReplView; new repl command exports Repl wrapper; login uses platform-specific spawn to open browser (cmd/open/xdg-open) instead of exec.
Utilities src/lib/replParser.ts, src/lib/flagParser.ts, src/lib/history.ts	Adds REPL input parser with shell-like tokenization and command recognition, flag parsing with Zod validation/coercion, and JSON-backed history persistence with file-permissions handling.
Component API updates src/components/FlowTimeline.tsx, src/components/LogTable.tsx, src/components/StatsView.tsx	Adds optional onBack?: () => void to components; pressing 'q' now calls onBack if provided (falls back to process.exit).

Sequence Diagram

sequenceDiagram
    actor User
    participant ReplView
    participant ReplParser
    participant FlagParser
    participant ApiClient
    participant ConfigStore
    participant SubView as SubView (Logs/Flows/Stats/Login/Whoami)

    User->>ReplView: Start CLI (no args)
    ReplView->>ConfigStore: load history & token
    ReplView->>ReplView: render header & prompt

    loop REPL loop
        User->>ReplView: enter input
        ReplView->>ReplParser: parseReplInput(input)
        ReplParser-->>ReplView: ParsedCommand
        alt builtin
            ReplView->>ReplView: handle builtin (help/clear/exit)
        else command
            ReplView->>FlagParser: parseFlags(tokens, schema?)
            FlagParser-->>ReplView: flags,positional,error
            ReplView->>ApiClient: create client(token) / call endpoints
            ApiClient-->>SubView: response
            SubView->>ReplView: onDone(output, interactive) or onError(msg)
            ReplView->>ConfigStore: save history
        end
        ReplView->>User: render output & prompt
    end

    User->>ReplView: press 'q' or back
    ReplView->>SubView: onBack or exit

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Replace API key auth with OAuth device flow #65: Related changes around CLI authentication/device flow and token/session management that intersect with LoginView and token usage.

Poem

🐰 A rabbit hops in, with keys aglow,
Prompting the CLI where commands can flow,
History saved, views summoned with cheer,
From login to logs, back-navigation near,
Repl dawns, interactive and ready to go!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: REPL interactive mode' directly summarizes the main change: introducing an interactive REPL mode to the CLI.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/repl-interactive-mode-72

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}