Problem
The Overview* family of types is defined twice — once as server-internal types in packages/codev/src/agent-farm/servers/overview.ts, once as wire-contract types in packages/types/src/api.ts. Five paired interfaces, structurally identical:
overview.ts (server-internal) | api.ts (wire contract) |
|---|
BuilderOverview | OverviewBuilder |
PROverview | OverviewPR |
BacklogItem | OverviewBacklogItem |
RecentlyClosedItem | OverviewRecentlyClosed |
OverviewData | OverviewData |
Only differences worth noting: minor docstring wording variants (e.g. roleId, lastDataAt), and BuilderOverview.planPhases: PlanPhase[] (named local interface) vs OverviewBuilder.planPhases: Array<{ id: string; title: string; status: string }> (inlined shape) — structurally equivalent.
The server emits objects that exactly match the wire shape. No transformation, no internal-only fields, no field renaming.
Cost of the current state
Every field addition has to land in both files, manually kept in sync. Recent example: #819 added area: string to both BacklogItem and OverviewBacklogItem (and the matching pair for builders). Two parallel edits per field, in two separate commits crossing package boundaries. Drift risk is real — someone can land a field on one side, forget the other, and the server's TypeScript happily compiles while the wire types silently lie.
Why both exist (speculative)
Server type was probably defined first; the wire-contract package (packages/types) was extracted later and the server-internal types were duplicated rather than replaced with imports. No principled reason to keep them separate today.
Proposed change
- Source of truth: keep
OverviewBuilder, OverviewPR, OverviewBacklogItem, OverviewRecentlyClosed, OverviewData in @cluesmith/codev-types. Already aligned with the rule that the types package is wire contracts only. - Server-side:
packages/codev/src/agent-farm/servers/overview.ts imports them via import type { OverviewBuilder, OverviewBacklogItem, ... } from '@cluesmith/codev-types' and uses them directly. Delete the local interface declarations. PlanPhase: keep the named interface, but co-locate it with the wire types (move from overview.ts to api.ts) so OverviewBuilder.planPhases: PlanPhase[] can use the same named shape on both sides. Drop the inlined Array<{id, title, status}>.- Internal-only fields (if ever needed): if a server later needs a truly server-internal field (e.g. a
Symbol-keyed cache pointer), define a local type that extends the wire type — the wire type stays the public contract.
Mostly mechanical diff
- Replace ~5
export interface XxxOverview { ... } blocks in overview.ts with import type { XxxOverview } from '@cluesmith/codev-types'. - Rename the server-side identifiers if needed (e.g.
BuilderOverview → OverviewBuilder) — or keep an alias to minimize churn (type BuilderOverview = OverviewBuilder). - Move
PlanPhase to api.ts and replace the inlined planPhases shape with the named reference. - Run
pnpm -w build — TypeScript will surface any leftover divergence.
Acceptance criteria
Out of scope
- Restructuring how the overview endpoint constructs the data (the construction code in
getOverview / deriveBacklog / discoverBuilders stays as-is; only the type identifiers change). - Adding genuinely server-internal fields (none exist today; if they did, the proposed pattern is "extend the wire type locally").
Related
Problem
The
Overview*family of types is defined twice — once as server-internal types inpackages/codev/src/agent-farm/servers/overview.ts, once as wire-contract types inpackages/types/src/api.ts. Five paired interfaces, structurally identical:overview.ts(server-internal)api.ts(wire contract)BuilderOverviewOverviewBuilderPROverviewOverviewPRBacklogItemOverviewBacklogItemRecentlyClosedItemOverviewRecentlyClosedOverviewDataOverviewDataOnly differences worth noting: minor docstring wording variants (e.g.
roleId,lastDataAt), andBuilderOverview.planPhases: PlanPhase[](named local interface) vsOverviewBuilder.planPhases: Array<{ id: string; title: string; status: string }>(inlined shape) — structurally equivalent.The server emits objects that exactly match the wire shape. No transformation, no internal-only fields, no field renaming.
Cost of the current state
Every field addition has to land in both files, manually kept in sync. Recent example: #819 added
area: stringto bothBacklogItemandOverviewBacklogItem(and the matching pair for builders). Two parallel edits per field, in two separate commits crossing package boundaries. Drift risk is real — someone can land a field on one side, forget the other, and the server's TypeScript happily compiles while the wire types silently lie.Why both exist (speculative)
Server type was probably defined first; the wire-contract package (
packages/types) was extracted later and the server-internal types were duplicated rather than replaced with imports. No principled reason to keep them separate today.Proposed change
OverviewBuilder,OverviewPR,OverviewBacklogItem,OverviewRecentlyClosed,OverviewDatain@cluesmith/codev-types. Already aligned with the rule that the types package is wire contracts only.packages/codev/src/agent-farm/servers/overview.tsimports them viaimport type { OverviewBuilder, OverviewBacklogItem, ... } from '@cluesmith/codev-types'and uses them directly. Delete the local interface declarations.PlanPhase: keep the named interface, but co-locate it with the wire types (move fromoverview.tstoapi.ts) soOverviewBuilder.planPhases: PlanPhase[]can use the same named shape on both sides. Drop the inlinedArray<{id, title, status}>.Symbol-keyed cache pointer), define a local type that extends the wire type — the wire type stays the public contract.Mostly mechanical diff
export interface XxxOverview { ... }blocks inoverview.tswithimport type { XxxOverview } from '@cluesmith/codev-types'.BuilderOverview→OverviewBuilder) — or keep an alias to minimize churn (type BuilderOverview = OverviewBuilder).PlanPhasetoapi.tsand replace the inlinedplanPhasesshape with the named reference.pnpm -w build— TypeScript will surface any leftover divergence.Acceptance criteria
overview.tsdeclares zeroOverview*/*Overviewinterfaces (all imported from@cluesmith/codev-types).PlanPhaselives inapi.tsand is the single shape used byOverviewBuilder.planPhases.pnpm -w buildis green (no field divergence remaining).Overview*type requires editing exactly one file.Out of scope
getOverview/deriveBacklog/discoverBuildersstays as-is; only the type identifiers change).Related
@cluesmith/codev-typesis wire contracts only; implementation/policy in@cluesmith/codev-core. This issue cleans up an existing violation-by-duplication of that rule.area: stringto both halves of the pair.