You’re viewing Paradaux’s public workspaceSign in to vote Get taskl.ie for your team

PAR-413

Loading issues

PAR-413 · A5 · Reference domain end to end: labels (facade, use… · Paradaux · taskl.ie

PAR-413

A5 · Reference domain end to end: labels (facade, use cases, persistence, controller, OpenAPI, web data/ + screen)

Architecture epic, foundation step 5 of 5. Depends on A3 and A4. This is the template every later domain copies (commandment 35: "start new work from a reference domain"). Labels is small, used everywhere, and has both reads and writes, so it covers every layer.

Backend: `io.paradaux.tasklie.labels`

labels/model/Label.java: a record with its behaviour (colour validation, name normalisation).
labels/persistence/LabelRepository.java: JdbcClient, named parameters, every query scoped by tenant_id, rows mapped to Label. Optional for lookups.
labels/usecase/: ListLabels, CreateLabel, RenameLabel, RecolourLabel, MergeLabels and DeleteLabel. Each is one class with one public method, execute(ctx, input), returning Result<…, LabelError>.
labels/LabelError.java: a sealed set of domain errors with HTTP statuses (NotFound, NameTaken, Forbidden, Invalid).
labels/LabelsFacade.java: the only public entry and the transaction boundary. It checks permissions and composes use cases.
Adapters:
- labels/api/LabelController.java (REST under /api/public/w/{ws}/labels, request records with @Valid)
- labels/mcp/LabelMcpTools.java, which moves the label tools out of TaskMcpTools and calls the same facade
Remove the label SQL from PostgresTaskSystem. Other domains that need labels call LabelsFacade.
Tests:
- use cases with a fake repository
- LabelRepository with Testcontainers Postgres, including a cross-tenant isolation test
- a controller contract test against the OpenAPI spec

Web: `apps/web/domains/labels`

data/server.ts (listLabels(ws)) and data/hooks.ts (useLabels, useCreateLabel…), built on the generated client.
Replace every Kysely label read (in lib/sql/*) with these. Prune the related ESLint suppressions.
Settings → Labels page: build it to the PAR-400 design (story "Settings / Labels": colour-wash chips, description, issue count, ⋯ menu with rename, recolour, merge and delete). This one screen proves the UI half of the template.

Docs

Add a section to docs/architecture.md, "Reference domain: labels", that maps each commandment to the file implementing it. Later agents copy from it.

Acceptance

Every test passes, and story a11y passes.
ArchUnit: labels has zero violations, and the frozen store shrinks (the PostgresTaskSystem label SQL is gone).
ESLint suppressions shrink.
The PR lists both deltas.

Activity

taskl.ie created the issue 6d ago
taskl.ie6d ago
Added scope (from the PAR-411 review): browser-side API calls go through a token-attaching proxy.

The browser must never hold a Keycloak token or service key. Client hooks (data/hooks.ts) need authenticated calls, so:
- Proxy route: add a Next route handler at apps/web/app/api/private/backend/[...path]/route.ts. The UI owns /api/private/**. It forwards the method, query and body to TASKLIE_API_BASE + /api/public/..., and attaches the session's actor token server-side with the same plumbing as lib/api/client.server.ts (getActorToken, actorHeaders). With no session, it forwards as guest.
- Proxy limits: only allow /api/public/w/** paths (no webhooks, no MCP). Strip hop-by-hop headers, and pass the status and body through unchanged.
- Browser client: point createBrowserClient() in lib/api/client.ts at /api/private/backend by default.
- Tests: a test that the proxy attaches the token and refuses non-allowed paths.
Labels' client mutations (create, rename, recolour, merge, delete) are the first users, and every later domain's hooks reuse this proxy. Document it in domains/README.md.
taskl.ie set status to In Progress 6d ago
taskl.ie6d ago
Plan (agent, branch par-413-labels-reference):
1. Platform (no domain imports): PermissionKeys, WorkspaceAccess port (slug -> workspace-scoped RequestContext, implemented in security/ so labels never imports it), McpToolProvider/McpToolSupport (context-based MCP tool base, builds RequestContext from the transport context).
2. labels domain: model/Label, persistence/LabelRepository (JdbcClient, tenant-scoped), six use cases, sealed LabelError, LabelsFacade (the only transactional entry), api/LabelController (/api/public/w/{ws}/labels), mcp/LabelMcpTools (same tool names). Label SQL removed from PostgresTaskSystem/WorkspaceAdminService; remaining callers use the facade. One additive migration (label.description) because the PAR-400 design shows a description.
3. Web: token-attaching proxy app/api/private/backend/[...path] (only /api/public/w/**), createBrowserClient pointed at it, domains/labels/{data,components}, Settings -> Labels page, Kysely label reads replaced, ESLint suppressions pruned.
4. Docs: "Reference domain: labels" in docs/architecture.md (commandment -> file). Ratchet deltas (ArchUnit store + ESLint suppressions) reported in the PR.
taskl.ie6d ago
PR open: https://github.com/ParadauxIO/taskl.ie/pull/45 (ArchUnit store -58 lines, ESLint suppressions unchanged at 36 files / 89, see the PR for why).
taskl.ie set status to Pending Release 6d ago
taskl.ie6d ago
Merged into rebuild (PR #45, after one review round). This is now the template for every domain migration. See "Reference domain: labels" in docs/architecture.md.

Ratchet: the ArchUnit store went from 1986 to 1928 lines (−58). The 10 added lines are existing violations whose text changed when constructors gained a LabelsFacade parameter; the orchestrator checked them. ESLint suppressions are unchanged, because the issue and board queries still join labels until PAR-414.

Decisions every later domain copies
- Permissions come from RequestContext through the platform.WorkspaceAccess port (implemented in security/WorkspaceAccessService), so domains never import security.
- Public workspace (any public team): guests, non-members and the bare service key get read-only issue.read. Writes always require membership. Private workspaces stay closed. (Fixed in review; this is the PAR-423 rule in its minimal form.)
- Controllers take @InWorkspace RequestContext ctx, which resolves {slug} and permissions.
- Facades call Rollback.onErr when they return an Err after writing.
- MCP tools are a McpToolProvider bean extending McpToolSupport.
- Browser calls go through app/api/private/backend/[...path]:
  
  token attached server-side
  
  client auth headers stripped
  
  only /api/public/w/<slug>/…
  
  mutations same-origin
  
  guests forwarded without the service key
- The web domain barrel exports server functions and screens, never hooks (that would leak server-only code into client bundles).
- Configuration: the backend needs KEYCLOAK_ISSUER (set in the gitops base) for verified actors.
Deferred: a unique index on lowercased label names (uniqueness is enforced in the use case for now), and the issue↔label association SQL (moves in PAR-414).
taskl.ie changed status from Pending release to Done 5d ago

Workspace permission required to comment

Comments and reactions require workspace permission. Ask a workspace owner or admin for access. You can sign in to vote.