spike: generate the assistant's API client from the OpenAPI document

Aperta
  • Qualcosa non va?
#434 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
csharp, openapi
Ambito
backend-api-design

Direzione di ricerca

Start by reading assistant/src/TaskFlow.Mcp/Api/ApiModels.cs and TaskFlowApiClient.cs to list the operations and DTOs in use; compare them with the OpenAPI document and the generated web client under TaskFlow.Web/src/api/client/**. Prototype the task endpoints with a candidate option, then measure source size, plugin publish size, build needs, CI changes, and test impact. Finish with the comparison table, prototype test results, recommendation, and any required follow-up issues.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

tech-debt

Found while reviewing the assistant-builder agent for #400 (piece 8). The assistant's HTTP client and its DTOs are written by hand to mirror TaskFlow.Api, while the web client is generated from the API's OpenAPI document. This spike asks whether the assistant's client should be generated too.

What I found

  • assistant/src/TaskFlow.Mcp/Api/ holds 341 lines: ApiModels.cs (101), TaskFlowApiClient.cs (221) and TaskFlowApiException.cs (19). None of it is generated.
  • The web client (TaskFlow.Web/src/api/client/**) is generated from /openapi/v1.json with openapi-ts and committed. The backend builder regenerates it when the API surface changes, so a stale web client is caught at the source.
  • Nothing equivalent protects the assistant. When the API changes a DTO or endpoint, the assistant mirror is updated by hand, by the assistant builder, from the brief. A change nobody remembers shows up only as a runtime error from a tool or as a failing test, if one exists.
  • assistant/ is a separate solution (its own .sln, Directory.Build.props and .editorconfig) that ships as a plugin binary, so any option has to respect that boundary and the published size.

Scope

  1. Read the client and models and list which API operations and DTOs the assistant actually uses (a subset of the API).
  2. Compare these options on a prototype of one endpoint family (the task endpoints are a good candidate):
    • Generate a C# client from the OpenAPI document (Kiota, NSwag, openapi-generator or the Microsoft OpenAPI client tooling). Check generated size, how it fits ToolGuard and TaskFlowApiException, and how little of it the assistant needs.
    • Reference the API's DTOs directly (a shared project or a project reference). Check what it does to the separate solution and the plugin publish.
    • Keep the hand-written client and add a contract test that compares it to the OpenAPI document and fails on drift.
    • Keep things as they are.
  3. For each option, measure or estimate: lines of source kept in the repo, publish size of the plugin binary, build-time needs (a running API or a committed spec file), CI changes, and test impact. The assistant has about 480 tests.
  4. Say how each option changes the pipeline from #400: who regenerates the assistant client, and in which stage, if it is generated.
  5. Note how this interacts with #428, the enum casing spike. If responses use PascalCase enum names, a generated client's enum handling depends on that decision.
  6. Recommend one option.

Acceptance criteria

  1. A comparison table is posted on this issue, with the measurements from scope item 3 for at least three options.
  2. The prototype for the leading option builds and the existing task tool tests still pass against it, or the issue says why it was dropped.
  3. A recommendation is recorded. If generation is recommended, follow-up issues are opened for the migration and for the pipeline change; if not, the issue says what keeps the mirror honest (for example the contract test).

Out of scope

  • Migrating the assistant to the generated client. This issue produces a decision and follow-up issues.
  • The web client, which is already generated.
  • The timezone offset representation (a separate spike).
Lingua principale
C#
Stelle
1
Fork
0
Merge medio
2h 2m
PR unite (30g)
98

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di nevridge/TaskFlow

Tutte le issue di nevridge/TaskFlow

Issue simili

Altre issue su C#

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.