feat(explorer): v0.8.4 Explorer action workflows — editor launch, guided import, export

[tcballard]

Summary

Implements rac/roadmaps/v0.8.x-explorer/v0.8.4-explorer-action-workflow.md.

Adds:

• Editor integration — e from an artifact's context view opens it in the user's editor ($VISUAL/$EDITOR), launched fire-and-forget; Explorer never edits (ADR-024)
• Guided import — /import <source> [target] converts a document via the Core ingest service in a worker (operation feedback), previews the Markdown with its target, and writes only after explicit confirmation, never overwriting
• Export finding — x from the recommendations view exports them to a Markdown file through the same preview-and-confirm path
• A reusable confirm-write screen so every repository-changing workflow previews before applying

Roadmap / ADR Trace

Roadmap: rac/roadmaps/v0.8.x-explorer/v0.8.4-explorer-action-workflow.md (contract pinned in the first commit)

Relevant ADRs and designs:

• ADR-015 — Core owns ingestion; Explorer owns workflow presentation
• ADR-024 — Explorer is not an editor; external tools edit
• ADR-006 — document conversion
• DESIGN-action-workflows, DESIGN-editor-integration, DESIGN-import-workflow

Scope

Included

• rac.explorer.editor — resolve editor from $VISUAL then $EDITOR; launch via a module-level runner seam; guidance when unconfigured or on failure (never raises)
• ExplorerAdapter.open_in_editor, import_preview, write_import, export_recommendations; state.ImportPreview
• ContextScreen gains e + a status line; ImportScreen (convert → preview → confirm → write, worker-driven); ConfirmWriteScreen (shared preview/confirm write); RecommendationsScreen gains x
• import joins the command registry; ContextScreen now takes the adapter (threaded through all call sites)

Excluded (deliberately)

• Direct editing/authoring or saving content from Explorer (ADR-024)
• Automated fixes without confirmation; silent mutation
• Persisted editor preference and first-run editor selection — deferred to v0.8.6 preferences; v0.8.4 uses the $VISUAL/$EDITOR convention
• Terminal editors that require suspending the TUI — a later enhancement; v0.8.4 targets GUI editors per DESIGN-editor-integration
• Open Related Artifact / Show Relationship Impact as interactive traversal — v0.8.5 relationship navigation
• No Core/service changes (consumes existing ingest); no JSON contract movement

Product / Architecture Decisions

• Editor launch is fire-and-forget (Popen) so the TUI keeps running — suited to GUI editors the design emphasizes. The runner is a module seam (editor._RUNNER) so tests inject a spy; no real process starts.
• Import default target is the source stem as .md in the current directory; an explicit target overrides. write_import refuses to overwrite (matching rac new's no-clobber stance) and creates parent directories.
• Import conversion equals rac ingest (test asserts import_preview(...).markdown == ingest(...).markdown) — Explorer adds only the workflow.
• Conversion runs in a Textual thread worker (operation feedback: Converting → Preview → Result); the write is synchronous and gated on y.
• Export reuses the import preview/confirm machinery by producing an ImportPreview (converter="export") and writing through write_import, so the no-overwrite/preview guarantees hold for it too.

User-Facing Contract

CLI / Keys

rac explorer
# context view:  e → open in $EDITOR
# /import report.docx rac/requirements/new.md   → preview → y to write
# recommendations view: x → export → y to write

Human Output (interactive)

• Editor: a status line — Opened <path> in <editor>, or guidance to set $EDITOR
• Import: Converting <source>…, then a preview block (Source / Converter / Target / converted Markdown) and Press y to write this file · Esc to cancel, then the result
• Export: the same preview/confirm block for recommendations.md

JSON Output

No changes; no new contracts.

Exit Codes

Unchanged: 0 session quit · 2 not a directory or missing explorer extra.

Verification

Ran

python -m pytest                      # 751 passed
python -m ruff check src/ tests/
python -m ruff format --check src/ tests/
python -m mypy src/
rac validate rac/                     # exit 0
rac relationships rac/ --validate     # exit 0
rac review rac/                       # no priority 1–2 findings

Covered

• Editor: $VISUAL preferred over $EDITOR; launch passes [*shlex.split(cmd), path] to the runner; unconfigured → guidance; OSError → recoverable message; e in the context view launches via an injected spy and shows the status, and shows guidance when unset
• Import: preview converts without writing; import_preview equals rac ingest output; unsupported type and missing source report messages; write_import writes then refuses to overwrite; the /import flow previews, y writes the exact bytes, Esc writes nothing, unsupported reports failure
• Export: renders Markdown without writing; empty when clean; the x flow previews in ConfirmWriteScreen and y writes recommendations.md
• Registry: import discoverable and arg-splitting; /help lists all 9 entries
• Isolation battery extended to editor.py (no Textual/Core imports)

Review Path

1. rac/roadmaps/v0.8.x-explorer/v0.8.4-explorer-action-workflow.md — the pinned contract
2. src/rac/explorer/editor.py — resolution + launch seam
3. src/rac/explorer/adapter.py — open_in_editor, import_preview, write_import, export_recommendations
4. src/rac/explorer/screens/import_.py, screens/confirm.py — the worker-driven preview/confirm screens
5. src/rac/explorer/screens/context.py, recommendations.py, commands.py, screens/command.py — bindings and routing
6. tests/ — editor, adapter, app, commands
7. docs/cli.md, CHANGELOG.md

Notes For Reviewer

• Stacked on v0.8.2 (PR feat(explorer): v0.8.2 Explorer health — health view, four areas, navigable attention #53) and v0.8.3 (PR feat(explorer): v0.8.3 Explorer recommendations — categorized findings with impact and actions #54); until those merge this PR's diff also shows their commits. Merging in order narrows each.
• ContextScreen now requires the adapter (for e); all four call sites were updated. No behavior change to existing navigation.
• The largest milestone of the series; editor preference persistence and terminal-editor suspend are explicitly deferred (noted above) rather than half-built.

Implementation Process

Implemented with AI assistance under the roadmap contract.

Final scope, review, and acceptance decisions were made by the maintainer.