Extract the Maestro engine as a plugin (0.22)
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 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
- 平均合并
- 11 小时 49 分钟
- 30 天内合并 PR
- 585
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 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 天内回复
-
Client stop paths treat EPERM as a confirmed exit and drop state for a live companion可能已有人在做 @thymikee 今天认领。 未关闭
难度 4/5 3-5 天 新手友好度 52/100
callstack/agent-device#3540 ·
维护者通常 1 天内回复
-
enhancement needs-triage
难度 5/5 一周以上 新手友好度 35/100
callstack/agent-device#3531 ·
维护者通常 1 天内回复
查看 callstack/agent-device 的全部 Issue
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 77/100
apache/rocketmq-dashboard#6610 ·
维护者通常 3 天内回复
-
nextjs-tracking
难度 2/5 1-3 小时 新手友好度 69/100
cloudflare/vinext#3920 ·
维护者通常 1 天内回复
-
Team:Dashboards
难度 2/5 1-3 小时 新手友好度 65/100
elastic/kibana#297299 · 1 条评论 ·
维护者通常 1 天内回复
-
analytics beginner friendly community contributions-welcome good first issue hacktoberfest help wanted up-for-grabs
难度 2/5 1-3 小时 新手友好度 82/100
维护者通常 1 天内回复
-
affected/v17 affected/v18 area/frontend type/bug
难度 2/5 1-3 小时 新手友好度 82/100
umbraco/Umbraco-CMS#24186 ·
维护者通常 2 天内回复