name: api-lib-sync description: "Synchronize lib/api wrappers with the generated contract under api/generated. Use when regenerated APIs or DTOs changed, when wrapper drift between api/generated/lib/** and lib/api/** must be audited, or when Codex needs a generated-first baseline sync for services, controllers, models, api.dart, or api_client.dart."

API Lib Sync

Treat api/generated/lib/** as the source of truth for wrapper sync. Never edit api/generated/** unless the user explicitly asks for regeneration or generated patching.

Workflow

1. Choose the sync mode.
   • Use the fast path for a narrow diff.
   • Use a full baseline audit when the user asks for a full, exhaustive, generated-first pass.
2. Run the bundled impact script before broad code reads.
3. Classify every generated API and model file before editing:
   • aligned
   • stale
   • missing wrapper
   • transport or helper only
   • intentional skip or manual follow-up
4. Read only the generated files and wrapper files needed to resolve each mismatch.
   • Prefer rg, sed, and parallel shell reads over full-directory scans.
   • Read references/mapping-rules.md when ownership is ambiguous or when running a full audit.
5. Update wrapper-layer code with apply_patch.
   • Sync lib/api/models/*.dart
   • Sync lib/api/services/*.dart
   • Sync lib/api/controller/*.dart
   • Update lib/api/api.dart and lib/api/api_client.dart when public wrapper ownership changes
6. Verify with targeted formatting, analysis, and tests.

Impact Script

Run the bundled script first.

scripts/api_change_impact.sh <repo-root>

Use branch-to-branch diff mode when needed.

scripts/api_change_impact.sh <repo-root> <base-ref> <head-ref>

Use a full generated-contract audit when the task is exhaustive.

scripts/api_change_impact.sh <repo-root> --full-audit --include-untracked

Useful flags:

scripts/api_change_impact.sh <repo-root> --include-untracked
scripts/api_change_impact.sh <repo-root> --wide-openapi
scripts/api_change_impact.sh <repo-root> --full-audit

Use the script output as the hard scope for deeper review. If only api/openapi.yaml changed and generated deltas are absent, regenerate first before claiming precise wrapper sync.

Classification Rules

Resolve every generated artifact explicitly before editing wrappers.

For generated API files:

• Map each file to its owning service, controller, and public wrapper surface.
• Compare method names, params, nullability, pagination, and response envelopes.
• Mark each generated method as wrapped, intentionally service-only, intentionally skipped, missing, or stale.

For generated model files:

• Decide whether the file is a domain wrapper candidate, request-only DTO, transport/helper DTO, aggregate-backed model, or intentional skip.
• Check field-level mapping for renamed fields, nullability, enums, and nested DTO changes.
• Do not force false 1:1 symmetry for DTOs that should stay service-local.

Do not mark a file as aligned until every generated method or field has an explicit ownership decision.

Editing Rules

• Generated contracts win over stale wrapper code.
• Preserve app-facing ergonomics only when they still faithfully represent the generated contract.
• Keep exception mapping intentional; do not hide transport failures behind business-state fallbacks unless the app already requires that behavior.
• Prefer minimal wrapper edits over opportunistic cleanup outside the impacted contract surface.

Verification

Run targeted checks for touched files unless the audit spans many wrapper domains.

dart format <changed-files>
dart analyze <changed-files>
flutter test <relevant-tests>

Add or update regression coverage when the sync changes:

• DTO mapping
• error classification
• controller branching
• service/controller coverage for newly wrapped generated methods

Report

Summarize:

• which mode ran
• which generated APIs or models were stale or missing before the sync
• which files changed and why
• which skips were intentional
• which validations ran
• any remaining ambiguity or follow-up risk