lega-scri-thin-adap-brid

name	lega-scri-thin-adap-brid
description	Wrap an existing standalone script or replay flow into a typed app adapter/orchestrator with minimal drift. Use when a repo already has working legacy automation that must be integrated into a new architecture without rewriting the old script first.
tags	["adapters","legacy-code","orchestration","anti-drift","testing"]
version	1

lega-scri-thin-adap-brid

When to use

Use when all are true:

• a legacy script already works well enough
• a new architecture now expects an interface/adapter/orchestrator
• user wants fast integration with low risk
• rewriting the old script would widen change surface too early

Typical triggers:

• "把旧脚本包进 adapter"
• "先接线，别重写"
• "thin wrapper"
• "legacy replay / browser flow 接入新 pipeline"

Core rule

Do not rewrite the legacy script first. First wrap it with a thin bridge that preserves old behavior and emits the new contract.

Preferred integration order

1. Freeze the old script surface.
   • Identify the one callable entrypoint to reuse.
   • Treat its current return shape as external behavior.
2. Define the target contract.
   • List the exact fields the new adapter/orchestrator must return.
   • Keep key names stable even if some values are temporarily None.
3. Add one thin wrapper in the new architecture.
   • Example placement: app/probes/, app/adapters/, or app/providers/.
   • Wrapper should only:
     • call the legacy entrypoint
     • normalize result shape
     • apply narrow fallback semantics
     • avoid new business logic
4. Export the wrapper cleanly.
   • Add __init__.py export if the package uses explicit exports.
5. Verify with targeted tests before touching bootstrap/CLI wiring.
   • Monkeypatch the legacy entrypoint.
   • Assert contract keys and fallback behavior.
6. Run full tests after targeted tests pass.

Change-surface discipline

Before coding, declare or update a change-surface artifact when the repo uses them. Good minimal scope:

• docs/change-surface.md
• new thin wrapper file
• package export file
• targeted tests

Avoid touching in phase 1 unless required:

• legacy script internals
• database schema
• pipeline orchestration
• bootstrap/container wiring
• CLI flags

Those come in phase 2 after the bridge proves stable.

Fallback pattern

When the legacy script does not fully satisfy the new contract yet:

• preserve required keys
• fill unknowns with None
• use the last trustworthy prior value from existing state only when explicitly safe
• keep status semantics honest

Example pattern:

• if new checkout URL exists -> set status = "checkout_ready"
• else -> fall back to existing persisted URL
• do not pretend the new flow succeeded if it only returned partial data

Testing pattern

Use a narrow unit test around the wrapper first. Good assertions:

• legacy entrypoint called with expected args
• normalized result contains every contract key
• fallback fields behave correctly on missing data
• no accidental dependency on live browser/network state

Then run:

• targeted test file
• full suite

Reporting pattern

When done, report truthfully:

• legacy script untouched or touched
• wrapper path added
• contract keys stabilized
• targeted/full tests passed
• next safe integration step

Anti-patterns

Do not:

• refactor the old script and the new adapter in one step
• widen scope into bootstrap/CLI/database before wrapper tests exist
• collapse old script semantics into a vague generic dict
• mark statuses as success when only fallback data exists
• change multiple layers just because the wrapper compiled

Good outcome

A low-drift bridge that lets the new architecture call old automation now, while preserving freedom to replace the internals later.

Proven pattern from use

In the windsurf auto-register repo, the safe first move was:

• keep windsurf_trial_browser.py unchanged
• add a PaymentOrchestrator thin wrapper under app/probes/
• normalize return keys to the new payment contract
• fall back to existing account checkout URL if browser flow returned none
• verify with a dedicated pytest file, then run full suite

This reduced risk and preserved momentum before bootstrap/CLI wiring.

Additional proven pattern: phase-2 wiring after wrapper stabilizes

Once the thin wrapper tests pass, do container/CLI wiring as a separate phase.

Safe phase-2 order:

1. Add a backend selector in bootstrap/container, defaulting to stub.
2. Keep explicit dependency injection override higher priority than backend flags.
   • Example: register_adapter passed directly must win over register_backend.
3. Add only the minimum CLI flags needed to select the real backend and pass through stable parameters.
4. Add dedicated bootstrap/CLI tests for:
   • default stub backend
   • real backend selection
   • unknown backend rejection
   • explicit adapter override precedence
5. Run targeted tests first, then the full suite.

Runtime-object reuse rule

When wrapping a large legacy script, prefer reusing its runtime classes/functions over importing its full CLI/config constructor surface.

Preferred order:

• reuse legacy runtime client classes/functions directly
• build a tiny compatibility config object in the new layer
• avoid depending on the legacy script's full argparse/AppConfig constructor unless field shapes are known stable

Reason:

• legacy CLI/config objects often drift faster than runtime call signatures
• thin wrappers should depend on the narrowest stable surface

Config compatibility pattern

If the legacy runtime only needs attribute access, use a tiny compatibility object in the new layer instead of constructing the legacy dataclass wholesale. Examples: types.SimpleNamespace, a small local dataclass, or a minimal config class.

Use this when:

• the legacy AppConfig constructor has many fields
• field names have already drifted from what the new layer guessed
• only a subset is actually needed by WindsurfClient or provider factory helpers

This avoids accidental coupling to unrelated legacy options while still letting the thin bridge call real runtime objects.

Proven pattern from use: register replay bridge

In the same repo, the safe follow-up move was:

• keep windsurf_auth_replay.py unchanged
• add WindsurfReplayRegisterAdapter that creates a session, WindsurfClient, and mail provider at runtime
• delegate actual registration mapping to the narrower WindsurfRpcRegisterAdapter
• use a local compatibility config object rather than constructing legacy AppConfig directly after constructor drift was observed
• wire stub vs windsurf_replay selection in bootstrap/CLI only after adapter tests passed
• verify explicit adapter injection still overrides backend selection

This preserved low drift while allowing old replay logic to participate in the new architecture.