Skip to content

PRD #4173 M3: issue tracker connections and the YouTrack driver - #7

Merged
MirceaTufanDev merged 18 commits into
prd/ws-2from
agent/issue-6
Nov 11, 2026
Merged

MirceaTufanDev merged 18 commits into
prd/ws-2from
agent/issue-6

Conversation

@mirceatufan-uzi

@mirceatufan-uzi mirceatufan-uzi commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

This branch adds issue tracker connections and a YouTrack driver for PRD vtmocanu#4173 M3, built on the issue-side interface split from earlier milestones. The driver is bound to one YouTrack project, and a shared contract suite runs it alongside the forge fakes. No repo can link to an issue tracker yet, and the diff was truncated, so this description covers only the visible part.

Size: 84 files

Category Added Deleted
Code +4,289 −3
Tests +4,207 −0
Docs +19 −2
Config +12 −0
Generated +139 −0
Total +8,666 −5

What changed

  • New issue tracker package with a YouTrack driver for the issue-side methods, plus verify token, list projects and list states, bound to one project.
  • Connections store and service: the token is sealed with secretbox, bound to user, kind and base URL, and the service never returns it.
  • Connections need an https base URL on a new ISSUE_TRACKER_ALLOWED_BASE_URLS allowlist, empty by default. Redirects are refused and error text is scrubbed of the token.
  • Response bodies are size-capped and counted before decoding, so a hostile allowlisted server cannot force large allocations.
  • A shared contract suite runs against the YouTrack fake and, through a new gate task, against the GitLab, GitHub and Forgejo drivers over the Node forge fake.

Verification

Reported by the agent at f627b3b:

  • passed: task fmt-check:api
  • passed: task vet:api
  • passed: task build:api
  • passed: task check:sqlc-drift
  • passed: task lint:api
  • passed: task test:api
  • passed: task test:forge-fake-contract
  • passed: task test:issue-tracker-forge-fake-contract
  • passed: task check:changelog-entry
  • passed: task check:migration-numbering
  • passed: task check:token-literals
  • passed: task scan:secrets
  • passed: go test -race ./internal/issuetracker/... ./internal/issuetrackersvc/... ./internal/config/
  • passed: go test -run IssueTrackerConnection ./internal/store/ (live Postgres 17, UZI_TEST_DATABASE_URL)

Scope and review notes

  • Changed: The driver is bound to one YouTrack project when built. The project id argument is ignored, and calls on an unbound driver return an error.
  • Changed: Issue numbers are YouTrack's per-project numbers. An issue that has moved to another project reads as not found.
  • Changed: Labels map to YouTrack tags. Label updates make one call per tag, so they are not atomic.
  • Changed: Closing and reopening need explicit State values in configuration, and return an error when they are unset rather than guessing.
  • Dropped: No least-privilege token check runs on connect, although the forge rules include one. The branch argues that YouTrack permanent tokens expose no scopes.
  • Review: api/internal/issuetracker/youtrack_decode.go and youtrack_request.go: the response caps and value budgets that bound memory use when the allowlisted server is hostile.
  • Review: api/internal/issuetrackersvc/connect.go, driver.go and seal.go: the allowlist ordering, the sealing associated data, and the allowlist re-check before a stored token is opened.

Describes f627b3b against prd/ws-2.

Related to #6.

Closes #6

Internally reviewed by the repository's own agents, not uzi's built-in reviewer.


Opened by uzi from agent/issue-6. A human reviews and merges; uzi never merges.

uzi-agent and others added 18 commits November 11, 2026 08:29
…(PRD vtmocanu#4173 M3)

The package an issue tracker driver lives in (D6): the Driver interface
(forge.IssueTracker plus verify, list projects, list states), the kind
registry, a redactor that scrubs every encoded form of the token and strips
control and bidi characters, an HTTP client that never follows a redirect,
bounded body reads and paging backstops (S3), and the loud ErrNotStubbed
BaseFake (D7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Total byte budget across pages, the full control and format character
predicate, every encoded form of the token and its secret segment, status
class on oversize errors, no package-level test transport, and a redaction
test that fails when any one form is dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tmocanu#4173 M3)

The YouTrack driver implements every forge.IssueTracker method plus verify
token, list projects and list states, bound to one YouTrack project. Every
per-issue call checks the issue is still in that project, so a moved issue
reads as gone and is never written to. youtracktest is an in-process HTTPS
YouTrack fake that fails the test on any route it does not model, and
issuetrackertest.RunContract is the one contract suite every IssueTracker
implementation runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The issue_tracker_connections table (migration 00424), its owner-scoped
queries and the service: https-only base URL on the separate
ISSUE_TRACKER_ALLOWED_BASE_URLS allowlist (empty by default, so no
connection can be created), token verified then sealed in secretbox bound to
user, kind and base URL, no field that can reveal it, and the allowlist
re-checked before a stored token is opened.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Nested tags count toward the item ceiling and are capped per issue and
activity; error bodies are scrubbed before they are cut; every id taken
from a response is validated before it reaches a path; the token has an
upper bound and no control characters; and tests now pin every claimed
behaviour the mutation pass found unpinned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ListStates binds no project, project references are validated as bad
requests, the token is bounded and free of control characters, the strict
base URL must be idempotent with a host, and tests pin the nil allowlist,
bare query or fragment and non-canonical stored URL refusals.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uards

List pages stream through a json.Decoder that refuses past the requested
page size, and nested tag arrays stop at the per-item cap while decoding,
so a hostile response cannot allocate far beyond its wire size. The
service reuses the driver's exported token and project validators, and
tests now pin every guard the mutation pass found unpinned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Nested tag arrays and list pages are counted with a byte scan and then
unmarshalled once into the existing slice, so a response that repeats the
tags key allocates nothing extra. One exported invisible-character
predicate now guards tokens, labels, messages and hosts in both the
driver and the service, and a refused token says which rule it broke.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A byte scan counts values at every depth and refuses a page or object
over its structural budget before json.Unmarshal runs, and tag elements
must be objects, so repeated wrong-typed values cannot amplify into
per-element error allocations. Page whitespace follows JSON's own rules
and each decode sentinel is pinned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A page is validated whole, then each element is budgeted and unmarshalled
on its own, stopping at the first error, so wrong-typed scalars cost at
most one element's worth of error values. The item budget leaves room
for real YouTrack activities with $type tags at the nested ceiling, and
the duplicate-key and tag-shape tests now reach the code they pin.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A null tags value keeps the backing array, the real-shaped fixtures carry
one more member per tag so the documented headroom is tested, and the
decode comments and allocation figures match what was measured.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
encoding/json reuses slice elements without zeroing them, so a repeated
tags key could inherit an id an earlier key set. Reused elements are now
cleared, and tests pin both that and the null branch's allocation bound
(race-aware).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TestIssueTrackerForgeFakeContracts runs issuetrackertest.RunContract
against the real GitLab, GitHub and Forgejo drivers over the Node forge
fake, launched by the new gate:repo task
test:issue-tracker-forge-fake-contract. The fake's extra issue routes and
label catalogs answer only under FORGE_FAKE_ISSUE_CONTRACT=1, so the e2e
harness sees the fake exactly as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ment

Tick M3 with its verification, record the M3 choices in the Decision Log,
add the changelog fragment, and correct two forge-fake comments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
errcheck on deferred closes and test helpers, staticcheck struct
conversions and the embedded selector, and reasoned gosec suppressions
where a test deliberately redirects or posts to a local fake; plus three
Decision Log and one Taskfile wording corrections.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…anch

The PRD is the reviewed one from prd/ws-2. The M3 decision log entries
that still hold are kept; M3 stays unticked until the driver follows
D10 and D14 and the chart wiring and ADR land.

Co-Authored-By: Claude <noreply@anthropic.com>
@MirceaTufanDev
MirceaTufanDev merged commit c733ba8 into prd/ws-2 Nov 11, 2026
24 of 25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

PRD #4173 M3: issue tracker connections and the YouTrack driver

2 participants