feat(runtime): add flow-aware execution runtime

[chhoumann]

Add a shared flow-aware execution runtime across QuickAdd engines and isolate Templater integration behind an explicit capability boundary.

This introduces runtime execution context/result/diagnostic/artifact models, threads shared flow state through macro/capture/template execution, and moves Templater probing into src/integrations/* instead of scattering duck-typed checks through engine code. It also includes the follow-up fixes from review validation: non-interactive CLI runs now use whole-flow preflight, CLI/API callers honor ChoiceExecutionResult failure states, and Templater diagnostics are gated to meaningful cases.

This work was done because the existing execution model treated too much behavior as isolated string transforms, which made nested flow execution hard to reason about and made Templater integration brittle. The follow-up fixes make the new runtime safer at the boundaries without changing persisted choice schemas.

Focus review on src/engine/runtime/*, src/integrations/*, src/choiceExecutor.ts, the engine/runtime callers, and the CLI/preflight/API boundary changes. No persisted schema migration is included.

Summary by CodeRabbit

• New Features

  • CLI check/run returns richer structured diagnostics (missing inputs/flags, diagnosticCount, flow.choice metadata) and explicit run outcomes (success/aborted/failed).
  • Macros and nested choices run in one shared flow context with preserved variable scoping and immediate abort propagation.
  • Improved capture/template behavior and Templater handling (suppression on-create, trigger waiting, cursor jump, diagnostics).

• Documentation

  • Updated docs for flow-aware CLI validation, diagnostics, capture/template semantics, and integration details.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quickadd	Ready	Preview	Apr 26, 2026 4:15pm

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Introduces a runtime ChoiceExecutionContext and structured ChoiceExecutionResult/CommandExecutionResult models; adds flow-aware preflight traversal (collectChoiceFlowPreflight) that reports diagnostics and flow.choice metadata; centralizes Templater integration via IntegrationRegistry and FormatOrchestrator; threads execution context through executors, engines, and formatters; surfaces diagnostics and structured results in CLI handlers.

Changes

Cohort / File(s)	Summary
Documentation docs/docs/Advanced/CLI.md, docs/docs/Advanced/onePageInputs.md, docs/docs/Choices/MacroChoice.md, docs/docs/Choices/CaptureChoice.md, docs/docs/QuickAddAPI.md	Document flow-aware CLI preflight, new CLI JSON fields (diagnostics, flow.choices, missingFlags), nested-choice scoping, capture/macro semantics, and executeChoice variable snapshotting.
Runtime models src/engine/runtime/artifact.ts, src/engine/runtime/context.ts, src/engine/runtime/diagnostic.ts, src/engine/runtime/result.ts, src/engine/runtime/index.ts	Add ChoiceExecutionContext, artifact/diagnostic/result models and factories; provide context step IDs, artifact creation, diagnostic shape, and barrel exports.
Preflight traversal src/preflight/collectChoiceFlowPreflight.ts, src/preflight/collectChoiceFlowPreflight.test.ts	New traversal that walks nested choices (macros/conditionals), collects/deduplicates requirements, computes unresolved inputs, emits templater/integration diagnostics, and returns flattened choice summaries (path/depth).
CLI & handlers src/cli/registerQuickAddCliHandlers.ts, src/cli/registerQuickAddCliHandlers.test.ts	Switch run/check to use collectChoiceFlowPreflight; include diagnostics/flow metadata and diagnosticCount/choiceCount in responses; handle structured ChoiceExecutionResult statuses (success/aborted/failed) and serialize diagnostics.
Choice execution core src/IChoiceExecutor.ts, src/choiceExecutor.ts, src/choiceExecutor.runtime.test.ts	IChoiceExecutor.execute now returns ChoiceExecutionResult; ChoiceExecutor creates/reuses ChoiceExecutionContext, tracks executionDepth, returns standardized results (success/skipped/aborted/failed), exposes getExecutionContext, and tests updated for result/abort semantics.
Engines & formatters src/engine/QuickAddEngine.ts, src/engine/TemplateEngine.ts, src/engine/TemplateChoiceEngine.ts, src/engine/SingleTemplateEngine.ts, src/engine/CaptureChoiceEngine.ts, src/formatters/completeFormatter.ts, src/formatters/captureChoiceFormatter.ts	Thread ChoiceExecutionContext into engines/formatters; update constructors and run contracts; delegate templater operations to FormatOrchestrator; derive originLeaf from context; record artifacts/diagnostics into context.
Format orchestration src/engine/runtime/FormatOrchestrator.ts, src/engine/runtime/FormatOrchestrator.test.ts	New FormatOrchestrator centralizes templater integration calls, emits capability diagnostics when integrations/capabilities are missing, provides parse/overwrite/wait/jump helpers, and records capture plans/results as artifacts.
Templater integrations & registry src/integrations/TemplaterIntegration.ts, src/integrations/TemplaterIntegration.test.ts, src/integrations/IntegrationRegistry.ts, src/integrations/index.ts	Add TemplaterIntegration interface with Noop/Obsidian implementations, capability reporting, overwrite/wait/jump/suppression behavior; add per-App IntegrationRegistry and accessors; tests included.
Macro engine updates src/engine/MacroChoiceEngine.ts, src/engine/MacroChoiceEngine.entry.test.ts, src/engine/MacroChoiceEngine.notice.test.ts	Macro run now returns ChoiceExecutionResult, records per-command CommandExecutionResult array, centralizes child-abort handling using returned ChoiceExecutionResult, and exposes getCommandResults(); tests updated for typed results and abort semantics.
API & utilities src/quickAddApi.ts, src/quickAddApi.executeChoice.test.ts, src/utilityObsidian.ts, src/utilityObsidian.templater-binding.test.ts	executeChoice snapshots/restores executor variables and validates child ChoiceExecutionResult (throws on aborted/failed); templater helpers delegate to IntegrationRegistry.templater; tests updated to integration-backed behavior.
Plugin wiring src/main.ts	QuickAdd plugin gains an integrations field and registers an IntegrationRegistry on plugin load.
Misc. tests & startup src/engine/StartupMacroEngine.ts, src/engine/StartupMacroEngine.test.ts, src/engine/.../*.test.ts	Added/updated tests covering choice execution results, diagnostics/artifacts propagation, templater capability diagnostics, abort propagation, and startup macro abort handling.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as CLI Handler
    participant Preflight as collectChoiceFlowPreflight
    participant Executor as ChoiceExecutor
    participant Engine as ChoiceEngine
    participant Orchestrator as FormatOrchestrator
    participant Templater as TemplaterIntegration

    CLI->>Preflight: collectChoiceFlowPreflight(choice)
    Preflight->>Preflight: traverse choices, collect requirements & diagnostics
    Preflight->>Templater: inspect templates / check capabilities
    Preflight-->>CLI: ChoiceFlowPreflightResult { requirements, unresolvedRequirements, diagnostics, choices }

    CLI->>Executor: execute(choice)
    Executor->>Executor: create/reuse ChoiceExecutionContext
    Executor->>Engine: run(choice, executionContext)
    Engine->>Orchestrator: parse/overwrite/wait/jump as needed
    Orchestrator->>Templater: parseTemplate / overwriteFileOnce / wait / jump
    Templater-->>Orchestrator: capability/result
    Engine-->>Executor: ChoiceExecutionResult { status, artifacts, diagnostics, error? }
    Executor-->>CLI: mapped CLI response (ok/aborted/failed + diagnostics/flow)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat(cli): add native QuickAdd Obsidian CLI handlers #1129 — Related: CLI handler and preflight changes integrating flow-aware preflight and structured CLI responses.
• Templater: deterministic snippet rendering (capture + template append) #1017 — Related: Templater/file-creation behavior and integration centralization overlapping with IntegrationRegistry/FormatOrchestrator work.
• fix: stop macros and APIs immediately when cancellations occur #976 — Related: Abort signaling and propagation through executor/engine; overlaps with result/status handling.

Suggested labels

released

Poem

🐰 I hop through contexts, variables tucked tight,

Preflight maps choices by path and depth tonight,
Templater hums under orchestrated light,
Diagnostics bloom and results take flight,
A rabbit cheers — the flow feels right!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(runtime): add flow-aware execution runtime' directly and concisely summarizes the main change: introducing a shared, flow-aware execution runtime across QuickAdd engines.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/flow-runtime-review-fixes

---

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.}

[cloudflare-workers-and-pages]

Deploying quickadd with    Cloudflare Pages

Latest commit:	a5d5cfc
Status:	✅  Deploy successful!
Preview URL:	https://02a3f5fc.quickadd.pages.dev
Branch Preview URL:	https://codex-flow-runtime-review-fi.quickadd.pages.dev

View logs

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 7 additional findings.