Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,8 +123,10 @@ Completion defaults to `review`: successful finish opens a review to the
delegator (else owner); the person's approval completes the issue and updates
the sprint ledger. Admins may set `agentCompletion: "direct"` on the workspace
to allow agents to set completed statuses themselves. Finishing a run alone
never changes issue status. Agents may edit fields as assignee or reporter;
comments, attachments and questions/approvals can involve any issue.
never changes issue status. Agents may edit the fields of any issue and move it
among open statuses; reassigning, closing and reopening need the agent to be the
issue's assignee or reporter. Comments, attachments and questions/approvals can
involve any issue.

`GET /api/tracker/v1/agent-guide` serves the full protocol as Markdown; its route
inventory uses the handler registration table. The public `openapi.json` includes
Expand Down Expand Up @@ -176,14 +178,14 @@ a required BuildKit secret, never through build arguments or committed files.

## Catalog and release

The next app release is **0.1.14**, also recorded in `web/package.json`.
The next app release is **0.1.15**, also recorded in `web/package.json`.
`catalog/entry.yaml` carries no committed version: the first tag (`v0.1.0`)
created `versions[]` with `ghcr.io/appthrust/tracker@sha256:<index-digest>`,
stream `0.1`; later tags append at publication time. Do not add a version with
an unbuilt or placeholder image digest. OpenAPI's `info.version` describes the
API schema, not the app release. This repository has no hand-maintained changelog.

After the release prerequisites are available, push the SemVer tag `v0.1.14`.
After the release prerequisites are available, push the SemVer tag `v0.1.15`.
The tag workflow:

1. Performs one multi-platform build on `ubuntu-24.04` for Linux amd64 and arm64,
Expand All @@ -203,8 +205,8 @@ The tag workflow:
Publication commands used by the workflow:

```sh
bun hack/publish-entry.ts submit --version 0.1.14 --digest sha256:<image-index-digest>
bun hack/publish-entry.ts await --version 0.1.14 --digest sha256:<image-index-digest>
bun hack/publish-entry.ts submit --version 0.1.15 --digest sha256:<image-index-digest>
bun hack/publish-entry.ts await --version 0.1.15 --digest sha256:<image-index-digest>
```

Writers are serialized by `tracker-catalog-publish`; the workflow is guarded to
Expand All @@ -225,7 +227,7 @@ After publication, each estate's `AppCatalogSource` syncs the signed catalog.
Install Issues from the Project Marketplace (Directory is an automatic
dependency). Existing `follow` installations on stream `0.1` roll to the new
version; `pinned` installations show `UpdateAvailable` and require an explicit
version update. Confirm the installation is Ready, `/releasez` reports `0.1.14`,
version update. Confirm the installation is Ready, `/releasez` reports `0.1.15`,
the Project lists the `tracker` Access Key space as Ready, and an exchanged key reads `/api/tracker/v1/me`. These are release steps,
not actions performed by a source-only version bump.

Expand Down
23 changes: 22 additions & 1 deletion cmd/server/internal/api/collaboration_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,28 @@ func TestExternalAgentRoutesAndLastSeen(t *testing.T) {
missing := rawCall(t, h, assertion(scopeRead), "POST", "/issues", "", []byte(`{"title":"No scope","type":"task"}`), 403)
require.Contains(t, string(missing), `"error":"insufficient_scope"`)
unrelated := call[domain.Issue](h, "admin", "POST", "/issues", map[string]string{"title": "Unrelated", "type": "task"}, 201)
rawCall(t, h, bearer, "PATCH", "/issues/"+unrelated.ID, "", []byte(`{"title":"Denied"}`), 403)
// An agent edits any issue and moves it among open statuses; reassigning,
// closing and reopening stay with people unless the issue is its own.
status := map[string]string{}
for _, s := range call[items[domain.Status]](h, "admin", "GET", "/statuses", nil, 200).Items {
if _, seen := status[s.Category]; !seen {
status[s.Category] = s.ID
}
}
edited := rawCall(t, h, bearer, "PATCH", "/issues/"+unrelated.ID, "", []byte(`{"title":"Edited by agent","priority":"high","statusId":"`+status["started"]+`"}`), 200)
require.Contains(t, string(edited), `"title":"Edited by agent"`)
require.Contains(t, string(edited), `"statusId":"`+status["started"]+`"`)
done := call[domain.Issue](h, "admin", "POST", "/issues", map[string]string{"title": "Done", "type": "task", "statusId": status["completed"]}, 201)
for name, attempt := range map[string]struct{ id, body string }{
"cancel": {unrelated.ID, `{"statusId":"` + status["canceled"] + `"}`},
"reopen": {done.ID, `{"statusId":"` + status["started"] + `"}`},
"take": {unrelated.ID, `{"assigneeSub":"agent:` + agent.ID + `"}`},
"assign someone": {unrelated.ID, `{"assigneeSub":"owner"}`},
} {
refused := rawCall(t, h, bearer, "PATCH", "/issues/"+attempt.id, "", []byte(attempt.body), 403)
require.Contains(t, string(refused), `"error":"forbidden"`, name)
}
rawCall(t, h, bearer, "PATCH", "/issues/"+done.ID, "", []byte(`{"title":"Retitled while done"}`), 200)
rawCall(t, h, bearer, "POST", "/issues/"+unrelated.ID+"/comments", "", []byte(`{"body":"Allowed discussion"}`), 201)
for _, to := range []string{``, `,"to":null`} {
data := rawCall(t, h, bearer, "POST", "/issues/"+unrelated.ID+"/requests", "", []byte(`{"kind":"question","title":"Question"`+to+`}`), 201)
Expand Down
4 changes: 2 additions & 2 deletions cmd/server/internal/api/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"openapi": "3.1.0",
"info": {
"title": "Tracker API",
"version": "0.1.14",
"version": "0.1.15",
"description": "Contract: design/API.md. One workspace per PLATFORM_PROJECT_ID. The bearer is the signed-in user's token or an Access Key assertion (audience tracker; scope tracker:read for GET, tracker:write otherwise). External-subject assertions resolve by immutable registered agent handle. GET scopes tracker:read; other methods tracker:write; missing scope is 403 insufficient_scope. Every key is refused on Admin routes. See /agent-guide for the collaboration protocol."
},
"servers": [
Expand Down Expand Up @@ -2012,7 +2012,7 @@
"patch": {
"operationId": "patchIssue",
"summary": "patchIssue",
"description": "Authorization: any authenticated user. Every changed field emits one Activity. Changing to bug requires a report; changing away clears it. Parent cycles are invalid. Moving into completed/canceled sets completedAt; leaving clears it. Agents may edit only as assignee or reporter. expectedUpdatedAt mismatch returns 409 conflict. Under review an agent cannot set a completed status.",
"description": "Authorization: any authenticated user. Every changed field emits one Activity. Changing to bug requires a report; changing away clears it. Parent cycles are invalid. Moving into completed/canceled sets completedAt; leaving clears it. Agents may edit any issue and move it among open statuses; changing the assignee, or moving into or out of completed/canceled, requires the agent to be assignee or reporter (403 forbidden). expectedUpdatedAt mismatch returns 409 conflict. Under review an agent cannot set a completed status.",
"responses": {
"200": {
"description": "Success",
Expand Down
2 changes: 1 addition & 1 deletion cmd/server/internal/api/routes.go
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ func (a *API) routes() []routeDefinition {
{"GET /issues", false, false, a.issueList, "Filter issues; list rows include delegator, activeRun and openRequestCount.", false},
{"POST /issues", true, false, a.issueCreate, "Create an issue; you are its reporter. You may assign it to yourself.", false},
{"GET /issues/{id}", false, false, a.issueGet, "Read current fields, updatedAt and blocking issues before editing.", false},
{"PATCH /issues/{id}", true, false, a.issuePatch, "Edit only if assignee or reporter; send expectedUpdatedAt to avoid overwriting changes.", false},
{"PATCH /issues/{id}", true, false, a.issuePatch, "Edit any issue's fields and move it among open statuses; changing the assignee, closing or reopening needs you to be assignee or reporter. Send expectedUpdatedAt to avoid overwriting changes.", false},
{"DELETE /issues/{id}", true, true, a.issueDelete, "", false},
{"GET /issues/{id}/timeline", false, false, a.timeline, "Read comments, activities, runs and requests.", false},
{"POST /issues/{id}/comments", true, false, a.commentCreate, "Discuss any issue; @handle mentions a registered agent.", false},
Expand Down
8 changes: 5 additions & 3 deletions cmd/server/internal/domain/agents_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,11 @@ func TestCollaborationAuthorization(t *testing.T) {
{"agent never admin", agent, ManageWorkspace, Target{}, false},
{"agent reads", agent, Read, Target{}, true},
{"agent creates", agent, Create, Target{}, true},
{"agent edits assigned", agent, EditIssue, Target{OwnerSub: agent.Sub}, true},
{"agent edits reported", agent, EditIssue, Target{ReporterSub: agent.Sub}, true},
{"agent cannot edit unrelated", agent, EditIssue, Target{}, false},
{"agent edits unrelated", agent, EditIssue, Target{}, true},
{"agent controls assigned", agent, ControlIssue, Target{OwnerSub: agent.Sub}, true},
{"agent controls reported", agent, ControlIssue, Target{ReporterSub: agent.Sub}, true},
{"agent cannot control unrelated", agent, ControlIssue, Target{OwnerSub: person.Sub, ReporterSub: person.Sub}, false},
{"person controls any", person, ControlIssue, Target{}, true},
{"agent withdraws own", agent, WithdrawRequest, Target{OwnerSub: agent.Sub}, true},
{"agent cannot withdraw other", agent, WithdrawRequest, Target{OwnerSub: person.Sub}, false},
{"person withdraws own", person, WithdrawRequest, Target{OwnerSub: person.Sub}, true},
Expand Down
7 changes: 5 additions & 2 deletions cmd/server/internal/domain/rules.go
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ const (
Read Action = "read"
Create Action = "create"
EditIssue Action = "edit_issue"
ControlIssue Action = "control_issue"
ManageWorkspace Action = "manage_workspace"
DeleteIssue Action = "delete_issue"
EditComment Action = "edit_comment"
Expand Down Expand Up @@ -122,11 +123,13 @@ func Can(actor Actor, action Action, target Target) bool {
return actor.Sub == target.OwnerSub || (!agent && (target.OwnerSub == "" || admin))
case WithdrawRequest:
return actor.Sub == target.OwnerSub
case EditIssue:
case ControlIssue:
// Reassigning, closing and reopening decide whose work an issue is and
// whether it is over. An agent decides that only for its own issues.
return !agent || actor.Sub == target.OwnerSub || actor.Sub == target.ReporterSub
case ManageSprint:
return !agent
case Read, Create, CreateProject, EditProject:
case Read, Create, EditIssue, CreateProject, EditProject:
return true
case ManageWorkspace, DeleteIssue, ArchiveProject, DeleteProject:
return admin
Expand Down
23 changes: 22 additions & 1 deletion cmd/server/internal/store/issues_write.go
Original file line number Diff line number Diff line change
Expand Up @@ -278,9 +278,19 @@ func (t *Tx) PatchIssue(id string, input IssuePatch, actor domain.Person, assign
if old.Assignee != nil {
owner = old.Assignee.Sub
}
if !domain.Can(domain.Actor{Person: actor, Kind: domain.ActorKind(actor.Sub)}, domain.EditIssue, domain.Target{OwnerSub: owner, ReporterSub: old.Reporter.Sub}) {
who := domain.Actor{Person: actor, Kind: domain.ActorKind(actor.Sub)}
if !domain.Can(who, domain.EditIssue, domain.Target{}) {
return old, httpx.Forbidden()
}
control := domain.Can(who, domain.ControlIssue, domain.Target{OwnerSub: owner, ReporterSub: old.Reporter.Sub})
if next := ""; input.AssigneeSub.Present && !control {
if assignee != nil {
next = assignee.Sub
}
if next != owner {
return old, httpx.Forbidden()
}
}
if input.ExpectedUpdatedAt != nil && !input.ExpectedUpdatedAt.Equal(old.UpdatedAt) {
return old, httpx.Conflict("The issue has changed; read it again before editing")
}
Expand Down Expand Up @@ -380,6 +390,15 @@ func (t *Tx) PatchIssue(id string, input IssuePatch, actor domain.Person, assign
if err := t.completionAllowed(actor, after.Category); err != nil {
return item, err
}
if item.StatusID != old.StatusID && !control {
before, err := t.Status(old.StatusID)
if err != nil {
return item, err
}
if closed(before.Category) || closed(after.Category) {
return item, httpx.Forbidden()
}
}
if item.StatusID != old.StatusID {
item.CompletedAt = domain.TransitionCompletedAt(after.Category, t.now())
}
Expand Down Expand Up @@ -463,6 +482,8 @@ func (t *Tx) PatchIssue(id string, input IssuePatch, actor domain.Person, assign
}
return t.Issue(item.ID)
}

func closed(category string) bool { return category == "completed" || category == "canceled" }
func (t *Tx) DeleteIssue(id string, actor domain.Actor) error {
if !domain.Can(actor, domain.DeleteIssue, domain.Target{}) {
return httpx.Forbidden()
Expand Down
3 changes: 2 additions & 1 deletion design/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -515,7 +515,8 @@ identifier of its own: it is the free-text `session` of a Run.
| --- | --- | --- |
| Read issues, timeline, sprints, feed | any | `tracker:read` |
| Create issues, comment, attach, raise `question`/`approval` Requests, answer a `question` addressed to it — on any issue | any | `tracker:write` |
| Edit an issue's fields (`PATCH /issues/{id}`) | any | `tracker:write`, and only as the issue's assignee or reporter |
| Edit an issue's fields (`PATCH /issues/{id}`), including moving it among open statuses (`backlog`, `unstarted`, `started`) | any | `tracker:write`, on any issue (v0.1.15; before, only as assignee or reporter) |
| Change the assignee; move an issue into or out of `completed` / `canceled` | any | only as the issue's assignee or reporter. These decide whose work an issue is and whether it is over, and reassigning cancels the previous agent's run |
| Start and drive a run | n/a | `tracker:write`, assignee only |
| Set a `completed` status | any | only when `agentCompletion = direct` |
| Answer `approval` / `review` | addressee, or any person when unaddressed; Admin | never |
Expand Down
2 changes: 1 addition & 1 deletion web/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@appthrust/tracker",
"version": "0.1.14",
"version": "0.1.15",
"private": true,
"type": "module",
"scripts": {
Expand Down