Skip to content

Commit 01a26a9

Browse files
refactor(api): move projects contract to internal/project package — #20
Pilots the feature-package layout the backend is migrating toward: a resource's inbound interface and its DTOs live with the resource, not in a central ports/ catch-all. WHY: review flagged ports/ as vague. It conflates three jobs — the outbound capability seam (legit), single-impl inbound interfaces (Go idiom wants these consumer-side), and DTOs that aren't ports at all. This moves the projects contract out as the reference shape #21/#22 follow; the merged session/lifecycle/outbound contracts are left untouched and migrated separately. Scope: INTERFACE ONLY. No implementation — handlers still answer via apispec.NotImplemented and the injected project.Manager stays nil. The impl lands in a later handler-impl PR. Changes: - new internal/project: project.go (Manager interface, 7 endpoints) + dto.go (AddInput/GetResult/UpdateConfigInput/RemoveResult/ReloadResult, moved verbatim from ports/projects.go, Project-prefix dropped). - ports/projects.go deleted; ProjectManager removed from ports/inbound.go. outbound.go and facts.go untouched. - controllers/projects.go and httpd/api.go depend on project.Manager. Domain entities (Project, ProjectSummary, DegradedProject, config types) stay in domain/ as shared vocabulary. go build/vet/test/gofmt all clean; no behavioural change.
1 parent 3906d56 commit 01a26a9

6 files changed

Lines changed: 114 additions & 87 deletions

File tree

‎backend/internal/httpd/api.go‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,20 +9,21 @@ import (
99
"github.com/aoagents/agent-orchestrator/backend/internal/config"
1010
"github.com/aoagents/agent-orchestrator/backend/internal/httpd/apispec"
1111
"github.com/aoagents/agent-orchestrator/backend/internal/httpd/controllers"
12-
"github.com/aoagents/agent-orchestrator/backend/internal/ports"
12+
"github.com/aoagents/agent-orchestrator/backend/internal/project"
1313
)
1414

1515
// APIDeps bundles every Manager the API layer's controllers depend on. There
16-
// is exactly one *Manager per resource and the controllers see ONLY that
17-
// interface — they don't reach past it to inbound/outbound ports, the LCM,
18-
// or adapters. Whether a Manager impl talks to the registry, the LCM, or
19-
// an outbound port is its own concern.
16+
// is exactly one Manager per resource, defined in that resource's own package
17+
// (project.Manager, later session.Manager, ...), and the controllers see ONLY
18+
// that interface — they don't reach past it to the LCM, adapters, or stores.
19+
// Whether a Manager impl talks to the registry, the LCM, or an outbound port
20+
// is its own concern.
2021
//
21-
// The route-shell PR (#20) leaves every field nil — handlers don't
22-
// dereference them yet. Impl PRs in the same lane wire real Managers and
23-
// flip stubs to real logic one route at a time.
22+
// The route-shell PR (#20) leaves every field nil — handlers answer via
23+
// apispec.NotImplemented and don't dereference them yet. The handler-impl PR
24+
// wires real Managers and flips stubs to real logic one route at a time.
2425
type APIDeps struct {
25-
Projects ports.ProjectManager
26+
Projects project.Manager
2627
}
2728

2829
// API owns one controller per resource and is the single Register call the

‎backend/internal/httpd/controllers/projects.go‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,15 @@ import (
1919
"github.com/go-chi/chi/v5"
2020

2121
"github.com/aoagents/agent-orchestrator/backend/internal/httpd/apispec"
22-
"github.com/aoagents/agent-orchestrator/backend/internal/ports"
22+
"github.com/aoagents/agent-orchestrator/backend/internal/project"
2323
)
2424

2525
// ProjectsController owns the 7 canonical /projects routes. The controller
26-
// depends ONLY on ports.ProjectManager — it doesn't know whether the impl
27-
// reaches into the registry, the LCM, an adapter, or all three. Mgr is nil
28-
// while handlers are stubs; impl PRs supply a real ProjectManager.
26+
// depends ONLY on project.Manager — it doesn't know whether the impl reaches
27+
// into the registry, the LCM, an adapter, or all three. Mgr is nil while
28+
// handlers are stubs; the handler-impl PR supplies a real project.Manager.
2929
type ProjectsController struct {
30-
Mgr ports.ProjectManager
30+
Mgr project.Manager
3131
}
3232

3333
// Register mounts the project routes on the supplied router. Route order

‎backend/internal/ports/inbound.go‎

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -68,18 +68,3 @@ type CleanupResult struct {
6868
Cleaned []domain.SessionID
6969
Skipped []domain.SessionID // e.g. paths that still held uncommitted work
7070
}
71-
72-
// ProjectManager is the inbound contract the API layer calls for every project
73-
// operation. The HTTP controllers see ONLY this interface — they never reach
74-
// past it to the registry, LCM, workspace adapter, or SCM. Whether a method
75-
// touches the global config registry, the LCM (to stop sessions on remove),
76-
// or an adapter (to destroy worktrees) is a private concern of the impl.
77-
type ProjectManager interface {
78-
List(ctx context.Context) ([]domain.ProjectSummary, error)
79-
Get(ctx context.Context, id domain.ProjectID) (GetProjectResult, error)
80-
Add(ctx context.Context, in AddProjectInput) (domain.Project, error)
81-
UpdateConfig(ctx context.Context, id domain.ProjectID, patch UpdateProjectConfigInput) (domain.Project, error)
82-
Remove(ctx context.Context, id domain.ProjectID) (RemoveProjectResult, error)
83-
Repair(ctx context.Context, id domain.ProjectID) (domain.Project, error)
84-
Reload(ctx context.Context) (ReloadResult, error)
85-
}

‎backend/internal/ports/projects.go‎

Lines changed: 0 additions & 58 deletions
This file was deleted.

‎backend/internal/project/dto.go‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
package project
2+
3+
import "github.com/aoagents/agent-orchestrator/backend/internal/domain"
4+
5+
// Request/response shapes for Manager. They carry the data across the service
6+
// boundary; the canonical entities (Project, ProjectSummary, DegradedProject)
7+
// stay in domain/. Named without a "Project" prefix because the package name
8+
// already supplies it (project.AddInput, project.GetResult).
9+
10+
// GetResult is the discriminated union returned by Manager.Get. Exactly one of
11+
// Project / Degraded is non-nil; Status mirrors the discriminator on the wire
12+
// so consumers branch on it without nil-checking both fields.
13+
type GetResult struct {
14+
Status string // "ok" | "degraded"
15+
Project *domain.Project // populated when Status == "ok"
16+
Degraded *domain.DegradedProject // populated when Status == "degraded"
17+
}
18+
19+
// AddInput is the body shape for POST /api/v1/projects. Path is required;
20+
// ProjectID and Name default to basename(path) at the manager. Pointer fields
21+
// preserve the "field absent" vs "field present empty" distinction so the
22+
// manager can decide what to default and what to reject.
23+
type AddInput struct {
24+
Path string `json:"path"`
25+
ProjectID *string `json:"projectId,omitempty"`
26+
Name *string `json:"name,omitempty"`
27+
}
28+
29+
// UpdateConfigInput is the body shape for PATCH /api/v1/projects/{id}. Only
30+
// behaviour fields are mutable; identity fields (projectId, path, repo,
31+
// defaultBranch) are rejected by the handler with a 400 IDENTITY_FROZEN.
32+
type UpdateConfigInput struct {
33+
Agent *string `json:"agent,omitempty"`
34+
Runtime *string `json:"runtime,omitempty"`
35+
Tracker *domain.TrackerConfig `json:"tracker,omitempty"`
36+
SCM *domain.SCMConfig `json:"scm,omitempty"`
37+
Reactions *map[string]*domain.ReactionConfig `json:"reactions,omitempty"`
38+
}
39+
40+
// RemoveResult reports what DELETE /api/v1/projects/{id} actually did.
41+
// RemovedStorageDir is false when the project was registry-only (no on-disk
42+
// session/workspace directory existed).
43+
type RemoveResult struct {
44+
ProjectID domain.ProjectID `json:"projectId"`
45+
RemovedStorageDir bool `json:"removedStorageDir"`
46+
}
47+
48+
// ReloadResult is the response body of POST /api/v1/projects/reload — the
49+
// manager invalidates its cached config and re-scans the registry; the counts
50+
// help the dashboard show "loaded N projects, M degraded" feedback.
51+
type ReloadResult struct {
52+
Reloaded bool `json:"reloaded"`
53+
ProjectCount int `json:"projectCount"`
54+
DegradedCount int `json:"degradedCount"`
55+
}
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// Package project owns the projects service contract: the Manager interface
2+
// the HTTP layer calls and the request/response DTOs that cross it (dto.go).
3+
//
4+
// This is the pilot for the feature-package layout the backend is migrating
5+
// toward: a resource's interface and DTOs live with the resource, not in a
6+
// central catch-all. Controllers depend on project.Manager and nothing
7+
// beneath it — whether the implementation reaches into the config registry,
8+
// the lifecycle manager (to stop sessions on remove), or a workspace adapter
9+
// (to destroy worktrees) is a private concern of the impl, which lands in a
10+
// later handler-impl PR. This PR defines only the contract.
11+
package project
12+
13+
import (
14+
"context"
15+
16+
"github.com/aoagents/agent-orchestrator/backend/internal/domain"
17+
)
18+
19+
// Manager is the inbound contract for the /api/v1/projects surface. One
20+
// implementation (this package, later); the HTTP controller is the consumer.
21+
type Manager interface {
22+
// List returns every registered project, including degraded entries
23+
// (those whose config failed to load but whose registry entry survives).
24+
List(ctx context.Context) ([]domain.ProjectSummary, error)
25+
26+
// Get returns one project, discriminating ok vs degraded via GetResult.
27+
Get(ctx context.Context, id domain.ProjectID) (GetResult, error)
28+
29+
// Add registers a new project from a git repository path.
30+
Add(ctx context.Context, in AddInput) (domain.Project, error)
31+
32+
// UpdateConfig patches behaviour-only fields; identity fields are frozen.
33+
UpdateConfig(ctx context.Context, id domain.ProjectID, patch UpdateConfigInput) (domain.Project, error)
34+
35+
// Remove unregisters a project, stopping its sessions and reclaiming
36+
// managed workspaces.
37+
Remove(ctx context.Context, id domain.ProjectID) (RemoveResult, error)
38+
39+
// Repair recovers a degraded project where automatic repair is available.
40+
Repair(ctx context.Context, id domain.ProjectID) (domain.Project, error)
41+
42+
// Reload invalidates cached config and re-scans the global registry.
43+
Reload(ctx context.Context) (ReloadResult, error)
44+
}

0 commit comments

Comments
 (0)