Extract the Maestro engine as a plugin (0.22)
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 8/100
- issue の種類
- リファクタリング
- 明瞭さ
- おおむね明確
- 活発さ
- 活発
- 技術スタック
- typescript
調査の方向性
Start with the seam PR the issue says must land first: read packages/replay-port (the five session-replay-maestro-runtime* and -observer/-failure files plus session-test-source-discovery.ts) and src/core/platform-plugin-registry.ts. Check the grep proof that no production code imports @agent-device/maestro outside the registration site, and that cli-startup-import-closure.test.ts still passes. Done means the seam is merged and the layering and conformance checks are green.
索引モデルが issue の本文から書いたものです。
説明
Purpose
Extract the Maestro compatibility engine (packages/maestro, ~11.5k production LOC) into a plugin so the core daemon, CLI, and replay-port stop naming it directly, while the --maestro replay surface, the ADR 0015 performance contract, and the three-layer conformance oracle stay intact. This issue tracks the full 0.22 extraction; the paired seam PR is the non-breaking first step.
Current coupling (what must invert)
Today the daemon↔engine relationship is almost inverted — packages/replay-port is the adapter and the engine talks back only through invoke + a package-owned operation request (per #2544). Remaining direct couplings:
packages/replay-port→ engine imports (5 files):session-replay-maestro-runtime.ts(executeMaestroFlow,inspectMaestroFlow,createDaemonMaestroRuntimePort),-request.ts,-response.ts,-observer.ts,-failure.ts, plussession-test-source-discovery.ts(inspectMaestroFlow).src/import sites (4):src/cli/commands/replay.ts(static, lazy-loaded; export conversion),src/commands/schema/cli-help.ts(compat-reference strings),src/commands/replay/script-source-bundle.ts(dynamic; source closure),src/daemon/replay-device-selection.ts(dynamic; advisory device binding).- Backend-id vocabulary spread across layers:
ReplayFormat = 'ad' | 'maestro'inpackages/ad-script, the--maestroflag inpackages/command-registry,CommandFlags.maestroruntime flags, and Maestro-shapedReplayDispatchOptionskeys (closeAppOnly,observationOnly,gestureViewport,gestureExecutionProfile,settingsAppBundleId). - No engine-plugin seam exists.
src/plugins/*is scoped to provider runtimes only (plugins.md: plugins cannot register arbitrary commands). The registration culture to follow issrc/core/platform-plugin-registry.ts+register-builtins.ts: static registration, lazy implementation.
Explicitly out of scope: the maestro-direct-selector / maestro-non-hittable-fallback iOS fast paths and the flags.maestro.* daemon runtime flags. Per the comment in interaction-guarantees.ts, those are not the flow engine; they stay in shared runtimes. Decide during extraction whether that flag namespace gets renamed or documented as replay-compat vocabulary.
Required behavior
- Seam first (in flight): an owning replay-engine port that the daemon/replay-port depend on, with maestro as the single registered implementation behind a backend id. No npm-style dynamic loading in the seam PR — one static registration site in the daemon composition, structured so the extraction PR swaps it for a dynamic lookup.
- Behavior unchanged through the seam: same CLI surface (
replay --maestro,test --suites,replay export,help maestro), same daemon dispatch keys and response shapes, same error projection and divergence suggestions. - Laziness preserved: the CLI startup import closure must never evaluate the engine (
cli-startup-import-closure.test.tspins this; the replay closure may evaluate it only inside flow source collection). Any registry module's eager closure stays engine-free; eager-closure budgets must not grow. - Performance preserved (ADR 0015): the seam must not add a round trip, a second hierarchy capture, or per-operation indirection cost between
MaestroRuntimeOperationsandinvoke. Android stays faster than upstream Maestro. - Conformance preserved:
pnpm maestro:conformanceand the layer-3 differential keep running against the extracted engine with declared divergences only. - Extraction (0.22 target): move
@agent-device/maestroout of the root workspace dependency, narrow its package exports to exactly what the plugin host needs, and decide whether./daemon-runtime-port(host-side adapter glue) stays an engine export or moves to the plugin package.
Completion conditions
- Seam PR merged: replay-port and
src/import an owning port/registry, not@agent-device/maestro;check:layering,check:di-seams,maestro:conformance, andcheck:affected --rungreen. - Backend-id vocabulary owned in one place; the
Pick<ReplayDispatchOptions, keyof MaestroDaemonDispatchOptions>key-lock invariant survives the split. - Engine reachable only through the registration seam (grep proof: no production imports of
@agent-device/maestrooutside the registration/adapter site). - Plugin package extracted with its own manifest and a host contract versioned like
apiVersioninsrc/plugins/manifest.ts. - Layering bookkeeping resolved at each owning type:
architecture-ownership.ts,model.tsrank,daemon-modularity.tsengine prefixes,package-boundaries.test.tsexport/dependency pins,.fallowrc.json, check-affected routing, conformance CI lanes.
Dependencies
- Blocked by: the seam PR (linked below) landing first.
- Related policy: ADR 0015 (direct engine, five responsibilities, performance contract), ADR 0013 (gesture normalization boundary must survive),
docs/dependency-graph-findings.md(#2544 adapter inversion).
- 主要言語
- TypeScript
- スター
- 4.9k
- フォーク
- 328
- 平均マージ
- 12時間 18分
- マージ済み PR(30日)
- 561
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートなし
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
callstack/agent-device のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
callstack/agent-device#3407 ·
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
callstack/agent-device#3353 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
callstack/agent-device#1869 ·
メンテナーはふだん 1 日以内に返信
-
needs-triage
難易度 3/5 1〜2日 初心者へのやさしさ 76/100
callstack/agent-device#3453 ·
メンテナーはふだん 1 日以内に返信
-
CRAP: newly scored platform-apple simulator boot retry and macOS helper file listing対応中かも このイシューにリンクされたプルリクエストがオープン中、またはマージ済みです。 オープン
難易度 4/5 3〜5日 初心者へのやさしさ 52/100
callstack/agent-device#3451 ·
メンテナーはふだん 1 日以内に返信
callstack/agent-device の issue をすべて見る