From e0becd525c914ce676b5be1962836a414af50967 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 23 Sep 2026 03:15:27 +1000 Subject: [PATCH] feat(artifacts): publish the completed PR review to the collaborative editor Implements docs/prds/artifact-sender.md (Approved). archie-core now sends generated artifacts to the offloaded.dev collaborative editor, whose POST /api/artifacts route, bearer service token, PocketBase-backed versions and idempotency semantics are the receiving contract. - [artifacts] config section: base_url + token SecretRef with a token_env fallback naming WORKSPACE_INGEST_TOKEN. An empty base_url disables the sender entirely; a base_url with an unresolvable token disables it with a warning, because a missing credential disables a capability rather than stopping the daemon. - internal/infrastructure/artifactsync: one-method Publish seam in the Courier posture, full source per publish (versions of record are snapshots), 503 retried three times with backoff, 401/400 surfaced immediately with the field reason, deterministic request ids (artifact:pr-review:/#). - ReviewReport gains a pure markdown renderer in internal/domain/workflow: summary, one subsection per finding with the failure scenario and disposition when present, verified properties as a checked-clean list. - The daemon's PR reviewer publishes after a completed review when the sender is configured, records the editor deep link on the result, and degrades a failed publish to a log line -- publishing never fails the producing work. --- config.example.toml | 8 + docs/prds/artifact-sender.md | 83 ++++++++ internal/app/archied/pr_review.go | 94 ++++++++- internal/app/archied/pr_review_test.go | 74 +++++++ internal/config/config.go | 18 ++ internal/domain/workflow/review_report_md.go | 56 ++++++ .../domain/workflow/review_report_md_test.go | 78 ++++++++ internal/gateway/review_tools.go | 3 + .../infrastructure/artifactsync/sender.go | 181 ++++++++++++++++++ .../artifactsync/sender_test.go | 159 +++++++++++++++ .../configuration/artifacts_config_test.go | 52 +++++ .../infrastructure/configuration/defaults.go | 12 ++ 12 files changed, 817 insertions(+), 1 deletion(-) create mode 100644 docs/prds/artifact-sender.md create mode 100644 internal/domain/workflow/review_report_md.go create mode 100644 internal/domain/workflow/review_report_md_test.go create mode 100644 internal/infrastructure/artifactsync/sender.go create mode 100644 internal/infrastructure/artifactsync/sender_test.go create mode 100644 internal/infrastructure/configuration/artifacts_config_test.go diff --git a/config.example.toml b/config.example.toml index bd7aa71d3..f20a4fbfd 100644 --- a/config.example.toml +++ b/config.example.toml @@ -227,6 +227,14 @@ class = "ollama" # work_dir = "/path/to/workspace" # parallel_tool_calls = false +# Publish artifacts (review reports, design docs) to the collaborative editor. +# An empty base_url disables publishing entirely. The token is runtime config: +# set WORKSPACE_INGEST_TOKEN in the daemon's environment or use a secret ref. +[artifacts] +# base_url = "https://offloaded.dev" +# token = { engine = "env", key = "WORKSPACE_INGEST_TOKEN" } +# token_env = "WORKSPACE_INGEST_TOKEN" + # archied's own liveness surface, always on. GET /healthz and /health answer # 200 once the daemon is serving (503 while it is still booting), and # /health/detailed reports the readiness probes. This is what the update diff --git a/docs/prds/artifact-sender.md b/docs/prds/artifact-sender.md new file mode 100644 index 000000000..64924072e --- /dev/null +++ b/docs/prds/artifact-sender.md @@ -0,0 +1,83 @@ +# Artifact sender + +**Status:** Approved +**Revision:** 1 +**Authority:** this document + +## Purpose + +archie-core publishes artifacts — design documents, review reports, research briefs, +runnable pages — to the offloaded.dev collaborative editor. A person reads the +artifact, comments on it, and the artifact page is the shared surface for iteration. + +The receiving contract is owned by the editor: `POST /api/artifacts` with a bearer +service token, a closed field set, and server-side idempotency on `requestId` plus +last-write-wins on `sentAt`. This document owns only what archie-core sends. + +## Scope + +Version one publishes one-way: archie-core sends, the editor receives. The first +producer is the pull-request adversarial review: a completed `ReviewReport` is +rendered to markdown and published after the review completes. + +Chat-surface tools (`create_artifact`, `update_artifact`), comment read-back, share +tokens, and runnable-format producers (`html`, `react`, `vue`) are later slices. The +receiving contract already carries them; version one does not exercise them. + +## Configuration + +- New `[artifacts]` section: `base_url` (site origin), `token` (`SecretRef`) with + `token_env` fallback naming `WORKSPACE_INGEST_TOKEN`. +- An empty `base_url` disables the sender: no client is constructed, nothing is + registered, and publishing degrades to a log line. +- The token is runtime configuration. It is never baked at build time. + +## Sender + +- New package `internal/infrastructure/artifactsync` exposing one method, + `Publish(ctx, Artifact) (string, error)`, where the string is the artifact URL. + One-method injected seam, concrete client constructed by the boot path when the + configuration resolves — the `crondelivery.Courier` posture. +- The client POSTs the frozen contract body. Each publish sends the complete + source: versions of record are full snapshots, never diffs. +- A `503` response is retried three times with backoff. `401` and `400` are not + retried; they are logged with the field reason the response names. +- `requestId` is `artifact::` when the producer is task-backed, + otherwise `artifact::`. Sending the same `requestId` with + an equal or older `sentAt` must be a server-side no-op, which makes sender-side + retry safe. + +## Report rendering + +- `ReviewReport` gains a pure markdown renderer in `internal/domain/workflow`: + the summary as the lede, one finding per subsection with file, line, verdict, + level and the failure scenario, and the verified properties as a "checked + clean" list. Findings carry their disposition when present. +- The renderer performs no I/O and imports no infrastructure. + +## Attribution + +- `actor`: the producing identity. The reviewer publishes as `system:pr-reviewer` + when no task identity resolves; otherwise the task's identity name. +- `source`: the producing subsystem, `pr-review` for version one. +- `task`: owner, repository and issue number from the task when one exists. + +## Failure behaviour + +- Publishing never fails the producing work. A failed publish is logged with its + status and reason; the artifact is republished on the next production of the + same artifact. +- A successful publish records the artifact URL in the run report, so the PR + description or task log links to the readable artifact. +- The published URL is the editor deep link for the artifact, keyed on its + immutable id. archie-core never mints share links; sharing is an + account-holder decision made in the editor. + +## Verification + +- Client tests against a test server cover 201, 401, 400 with a field reason, + and 503 retry behaviour. +- The report renderer test covers a report with findings, checks, dispositions + and a not-run status. +- Configuration tests cover the disabled case, the `SecretRef` path and the + `token_env` fallback. \ No newline at end of file diff --git a/internal/app/archied/pr_review.go b/internal/app/archied/pr_review.go index 55b2bbb30..30116537d 100644 --- a/internal/app/archied/pr_review.go +++ b/internal/app/archied/pr_review.go @@ -8,6 +8,7 @@ import ( "strconv" "strings" "sync" + "time" "github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/app/agentworker" @@ -15,6 +16,7 @@ import ( "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/forge" "github.com/samcharles93/archie-core/internal/gateway" + "github.com/samcharles93/archie-core/internal/infrastructure/artifactsync" "github.com/samcharles93/archie-core/internal/worktree" ) @@ -29,6 +31,9 @@ type prReviewer struct { models map[string]string providers map[string]agentexec.Provider maxSteps int + // artifacts publishes the completed review to the collaborative editor. + // nil = publishing is disabled (no [artifacts] base_url configured). + artifacts artifactsync.Sender // currentMaxSteps lets the composition root apply live control-plane // versions to reviews that have not started yet. Tests and direct // constructions retain maxSteps as the fallback. @@ -115,7 +120,9 @@ func (r *prReviewer) ReviewPR(ctx context.Context, identity *string, repo string MaxSteps: maxSteps, }) r.logReview(key, model, report) - return mapReviewResult(repo, number, model, report), nil + + result := mapReviewResult(repo, number, model, report) + return r.attachArtifact(ctx, result, identity, owner, name, number, report), nil } // authorize enforces the identity-scoped repository allow-list. A nil @@ -174,6 +181,62 @@ func (r *prReviewer) logReview(key, model string, report workflow.ReviewReport) "findings", len(report.Findings), "blocking", blocking) } +// attachArtifact publishes the report when the sender is configured and +// records the editor deep link on the result. Publishing never fails the +// review: a failure degrades to an empty URL. +func (r *prReviewer) attachArtifact(ctx context.Context, result gateway.PRReviewResult, identity *string, owner, name string, number int, report workflow.ReviewReport) gateway.PRReviewResult { + result.ArtifactURL = r.publishArtifact(ctx, reviewActor(identity), owner, name, number, report) + return result +} + +// reviewActor resolves the attribution: the requesting chat identity when one +// exists, else the daemon's operator-reviewer actor. +func reviewActor(identity *string) string { + if identity != nil && *identity != "" { + return *identity + } + return "system:pr-reviewer" +} + +// publishArtifact renders the report and hands it to the collaborative +// editor when artifact publishing is configured. It returns the editor deep +// link, or "" when publishing is disabled or failed: a publish failure is a +// logged degradation, never an error that fails the producing review. +func (r *prReviewer) publishArtifact(ctx context.Context, actor, owner, name string, number int, report workflow.ReviewReport) string { + if r.artifacts == nil { + return "" + } + title := fmt.Sprintf("Review of %s/%s#%d", owner, name, number) + artifact := artifactsync.Artifact{ + Title: title, + Source: report.RenderMarkdown(title), + Meta: artifactsync.Meta{ + Format: "markdown", + Category: "pr-review", + Visibility: "account-only", + Egress: "none", + Actor: actor, + Origin: "pr-review", + RequestID: "artifact:pr-review:" + owner + "/" + name + "#" + strconv.Itoa(number), + Version: "r1", + SentAt: time.Now().UTC(), + Task: &artifactsync.Task{Owner: owner, Repo: name, Number: number}, + }, + } + url, err := r.artifacts.Publish(ctx, artifact) + if err != nil { + if r.log != nil { + r.log.Warn("artifact publish failed; the review result is unaffected", + "artifact", artifact.RequestID(), "err", err) + } + return "" + } + if r.log != nil { + r.log.Info("artifact published", "artifact", artifact.RequestID(), "url", url) + } + return url +} + // splitOwnerRepo splits "owner/name" with the same validation the gateway's // task_spawn allow-list uses. func splitOwnerRepo(s string) (owner, repo string, err error) { @@ -264,6 +327,7 @@ func (b *boot) prReviewer() gateway.ChatPRReviewer { models: b.cfg.Models, providers: executionProviders(b.cfg), maxSteps: maxSteps, + artifacts: b.artifactSender(), allowed: buildReviewAllowlist(b.cfg), log: b.log, } @@ -273,3 +337,31 @@ func (b *boot) prReviewer() gateway.ChatPRReviewer { b.chatPRReviewer = review return b.chatPRReviewer } + +// artifactSender builds the collaborative-editor sender when the [artifacts] +// section configures one. An empty base_url disables publishing entirely; a +// base_url with an unresolvable token is a missing credential, which disables +// the capability with a loud warning rather than stopping the daemon +// (docs/architecture/configuration.md, "A missing credential disables a +// capability"). +func (b *boot) artifactSender() artifactsync.Sender { + cfg := b.cfg.Artifacts + if cfg.BaseURL == "" { + return nil + } + token, err := b.secrets.Resolve(cfg.Token) + if err != nil { + b.log.Warn("artifact publishing disabled: the service credential could not be resolved", + "base_url", cfg.BaseURL, "token_engine", cfg.Token.Engine, "err", err) + return nil + } + if token == "" { + token = b.secrets.Getenv(cfg.TokenEnv) + } + if token == "" { + b.log.Warn("artifact publishing disabled: no service token; set the token secret or its environment variable", + "base_url", cfg.BaseURL, "token_env", cfg.TokenEnv) + return nil + } + return artifactsync.NewClient(cfg.BaseURL, token) +} diff --git a/internal/app/archied/pr_review_test.go b/internal/app/archied/pr_review_test.go index 93384e455..2adc23d84 100644 --- a/internal/app/archied/pr_review_test.go +++ b/internal/app/archied/pr_review_test.go @@ -2,13 +2,16 @@ package archied import ( "context" + "errors" "log/slog" + "strings" "testing" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/forge" "github.com/samcharles93/archie-core/internal/gateway" + "github.com/samcharles93/archie-core/internal/infrastructure/artifactsync" "github.com/samcharles93/archie-core/internal/tools" "github.com/samcharles93/archie-core/internal/worktree" ) @@ -241,3 +244,74 @@ func hasReviewPRTool(entries []tools.ToolEntry) bool { } return false } + +type fakeArtifactSender struct { + calls int + url string + err error + last artifactsync.Artifact +} + +func (f *fakeArtifactSender) Publish(_ context.Context, a artifactsync.Artifact) (string, error) { + f.calls++ + f.last = a + if f.err != nil { + return "", f.err + } + return f.url, nil +} + +func TestPrReviewerPublishesTheCompletedReview(t *testing.T) { + fake := &fakeArtifactSender{url: "https://offloaded.dev/collab?document=a_1"} + r := &prReviewer{artifacts: fake, log: slog.New(slog.DiscardHandler)} + report := workflow.NewCompletedReviewReport([]workflow.ReviewFinding{{ + File: "handler.go", Line: 42, Defect: "nil deref", + FailureScenario: "empty payload crashes", Verdict: workflow.ReviewVerdictConfirmed, + Level: workflow.ReviewLevelError, + }}, "one finding") + report.Checked = []workflow.ReviewCheck{{Property: "p", Evidence: "e"}} + + url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, report) + if url != fake.url { + t.Fatalf("publishArtifact = %q, want the sender's url %q", url, fake.url) + } + if fake.calls != 1 { + t.Fatalf("Publish called %d times, want 1", fake.calls) + } + got := fake.last + if got.Meta.Format != "markdown" || got.Meta.Category != "pr-review" { + t.Fatalf("format/category = %s/%s, want markdown/pr-review", got.Meta.Format, got.Meta.Category) + } + if got.Meta.Actor != "system:pr-reviewer" || got.Meta.Origin != "pr-review" { + t.Fatalf("attribution = %s/%s", got.Meta.Actor, got.Meta.Origin) + } + if got.Meta.Visibility != "account-only" || got.Meta.Egress != "none" { + t.Fatalf("visibility/egress = %s/%s", got.Meta.Visibility, got.Meta.Egress) + } + if got.Title != "Review of acme/widget#7" { + t.Fatalf("title = %q", got.Title) + } + if got.Meta.RequestID != "artifact:pr-review:acme/widget#7" { + t.Fatalf("requestId = %q, want the deterministic artifact key", got.Meta.RequestID) + } + if got.Meta.Task == nil || got.Meta.Task.Owner != "acme" || got.Meta.Task.Number != 7 { + t.Fatalf("task coordinates = %+v", got.Meta.Task) + } + if !strings.Contains(got.Source, "## Findings") { + t.Fatalf("source is not the rendered report:\n%s", got.Source) + } +} + +func TestPrReviewerPublishDegradesOnSenderFailure(t *testing.T) { + r := &prReviewer{artifacts: &fakeArtifactSender{err: errors.New("503 exhausted")}, log: slog.New(slog.DiscardHandler)} + if url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, workflow.NewCompletedReviewReport(nil, "s")); url != "" { + t.Fatalf("url = %q, want empty on a failed publish", url) + } +} + +func TestPrReviewerPublishIsANoOpWithoutASender(t *testing.T) { + r := &prReviewer{} + if url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, workflow.NewCompletedReviewReport(nil, "s")); url != "" { + t.Fatalf("url = %q, want empty when the sender is disabled", url) + } +} diff --git a/internal/config/config.go b/internal/config/config.go index 4eeb1de13..df758e437 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -534,6 +534,10 @@ type Config struct { // Tools holds MCP server and tool policy configuration (from config.tools.yaml). Tools ToolsConfig `toml:"tools" yaml:"tools"` + // Artifacts configures publishing artifacts to the collaborative editor. + // An empty BaseURL disables the sender entirely. + Artifacts ArtifactsConfig `toml:"artifacts" yaml:"artifacts"` + // Identities declares multi-identity configurations. When non-empty, // each identity runs its own poll loop with its own forge client, // worktree manager, repo list, model/provider config, and NATS subject @@ -557,6 +561,20 @@ type Config struct { Extra map[string]any `toml:"-" yaml:"-" json:"extra,omitempty"` } +// ArtifactsConfig locates the collaborative editor that receives artifacts. +// An absent section is valid and disables publishing: the capability degrades +// to a log line rather than stopping the daemon. +type ArtifactsConfig struct { + // BaseURL is the editor origin, e.g. https://offloaded.dev. Empty + // disables artifact publishing. + BaseURL string `toml:"base_url" yaml:"base_url"` + // Token is the service credential the editor's ingest route requires. + Token SecretRef `toml:"token" yaml:"token"` + // TokenEnv names the environment variable holding the token when Token + // is unset. Defaults to WORKSPACE_INGEST_TOKEN. + TokenEnv string `toml:"token_env" yaml:"token_env"` +} + // IdentityConfig is a per-identity configuration subset. Each identity // gets its own poll loop goroutine with isolated forge, repo, model, // and dispatch configuration. diff --git a/internal/domain/workflow/review_report_md.go b/internal/domain/workflow/review_report_md.go new file mode 100644 index 000000000..64cf1d730 --- /dev/null +++ b/internal/domain/workflow/review_report_md.go @@ -0,0 +1,56 @@ +package workflow + +import ( + "fmt" + "strings" +) + +// RenderMarkdown renders an adversarial review report as the artifact source +// the collaborative editor publishes. It is a pure function over the report: +// no I/O, no infrastructure, so the rendered form is testable in isolation. +// +// A completed review renders its summary, every finding as its own subsection +// (file, line, verdict, level, failure scenario, and the mechanical suggestion +// and disposition when present) and the verified properties as a "checked +// clean" list. A review that did not run renders only its reason, because a +// report that never executed has no findings or checks to stand behind. +func (r ReviewReport) RenderMarkdown(title string) string { + var b strings.Builder + fmt.Fprintf(&b, "# %s\n\n", title) + + if r.Status == ReviewStatusNotRun || (r.SkipReason != "" && len(r.Findings) == 0 && len(r.Checked) == 0) { + fmt.Fprintf(&b, "> This review did not run: %s\n", r.SkipReason) + return strings.TrimRight(b.String(), "\n") + "\n" + } + + if r.Summary != "" { + b.WriteString(r.Summary) + b.WriteString("\n\n") + } + + if len(r.Findings) > 0 { + b.WriteString("## Findings\n\n") + for _, f := range r.Findings { + fmt.Fprintf(&b, "### %s:%d — %s (%s)\n\n", f.File, f.Line, f.Level, f.Verdict) + fmt.Fprintf(&b, "**Defect:** %s\n\n", f.Defect) + if f.FailureScenario != "" { + fmt.Fprintf(&b, "**Failure scenario:** %s\n\n", f.FailureScenario) + } + if f.Suggestion != "" { + fmt.Fprintf(&b, "Suggested fix: %s\n\n", f.Suggestion) + } + if f.Disposition != "" { + fmt.Fprintf(&b, "Disposition: %s\n\n", f.Disposition) + } + } + } + + if len(r.Checked) > 0 { + b.WriteString("## Checked clean\n\n") + for _, c := range r.Checked { + fmt.Fprintf(&b, "- %s — %s\n", c.Property, c.Evidence) + } + } + + return strings.TrimRight(b.String(), "\n") + "\n" +} diff --git a/internal/domain/workflow/review_report_md_test.go b/internal/domain/workflow/review_report_md_test.go new file mode 100644 index 000000000..0634930f1 --- /dev/null +++ b/internal/domain/workflow/review_report_md_test.go @@ -0,0 +1,78 @@ +package workflow + +import ( + "strings" + "testing" +) + +func mdFixture() ReviewReport { + disposition := ReviewDisposition("fixed") + return ReviewReport{ + Status: ReviewStatusCompleted, + Summary: "The nil-deref path is reachable from a malformed payload.", + Findings: []ReviewFinding{ + { + File: "handler.go", Line: 42, Defect: "nil deref on empty payload", + FailureScenario: "POST with a body lacking the field crashes the handler.", + Suggestion: "guard the field before use", Verdict: ReviewVerdictConfirmed, + Level: ReviewLevelError, Category: "correctness", Disposition: disposition, + }, + { + File: "store.go", Line: 9, Defect: "query loses the filter", + FailureScenario: "paged reads return rows from other scopes", + Verdict: ReviewVerdictPlausible, Level: ReviewLevelWarn, + }, + }, + Checked: []ReviewCheck{ + {Property: "nil-safety of Foo callers", Evidence: "read all 4 callers; each nil-checks"}, + }, + } +} + +func TestReviewReportRendersFindingsAsMarkdown(t *testing.T) { + got := mdFixture().RenderMarkdown("Review of acme/widget#42") + for _, want := range []string{ + "# Review of acme/widget#42", + "The nil-deref path is reachable", + "### handler.go:42", + "**Defect:** nil deref on empty payload", + "**Failure scenario:** POST with a body lacking the field crashes the handler.", + "error (confirmed)", + "Suggested fix: guard the field before use", + "Disposition: fixed", + "### store.go:9", + "warn (plausible)", + "## Checked clean", + "- nil-safety of Foo callers — read all 4 callers; each nil-checks", + } { + if !strings.Contains(got, want) { + t.Fatalf("rendered report missing %q:\n%s", want, got) + } + } +} + +func TestReviewReportRendersNotRunStatus(t *testing.T) { + report := NewNotRunReviewReport("no reviewer model configured") + got := report.RenderMarkdown("Review of acme/widget#42") + if !strings.Contains(got, "no reviewer model configured") { + t.Fatalf("skip reason missing:\n%s", got) + } + if strings.Contains(got, "## Findings") || strings.Contains(got, "## Checked clean") { + t.Fatalf("a not-run report must not render finding or check sections:\n%s", got) + } +} + +func TestReviewReportRendersACleanReview(t *testing.T) { + report := ReviewReport{ + Status: ReviewStatusCompleted, + Summary: "No defects found.", + Checked: []ReviewCheck{{Property: "p", Evidence: "e"}}, + } + got := report.RenderMarkdown("Review") + if strings.Contains(got, "### ") { + t.Fatalf("a zero-finding review must not render finding sections:\n%s", got) + } + if !strings.Contains(got, "No defects found.") || !strings.Contains(got, "- p — e") { + t.Fatalf("summary and checks missing:\n%s", got) + } +} diff --git a/internal/gateway/review_tools.go b/internal/gateway/review_tools.go index d3e1a83aa..1c42c5dd1 100644 --- a/internal/gateway/review_tools.go +++ b/internal/gateway/review_tools.go @@ -24,6 +24,9 @@ type PRReviewResult struct { // Reason explains why a not_run/skipped review did not execute. Reason string `json:"reason,omitempty"` Findings []PRReviewFinding `json:"findings"` + // ArtifactURL is the editor deep link for the published review artifact, + // empty when artifact publishing is disabled or failed. + ArtifactURL string `json:"artifact_url,omitempty"` } // PRReviewFinding is one defect from an operator-triggered review. diff --git a/internal/infrastructure/artifactsync/sender.go b/internal/infrastructure/artifactsync/sender.go new file mode 100644 index 000000000..c3fee3ae4 --- /dev/null +++ b/internal/infrastructure/artifactsync/sender.go @@ -0,0 +1,181 @@ +// Package artifactsync publishes artifacts to the offloaded.dev collaborative +// editor: archie-core generates and sends, the editor hosts, renders and +// shares. It is infrastructure in the Courier posture — one method, injected +// by the composition root, absent when configuration does not resolve. +package artifactsync + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "strings" + "time" +) + +const contractFormat = "offloaded-collab-artifact" + +// Artifact is one publishable artifact: the rendered source plus the metadata +// the receiving contract carries. +type Artifact struct { + Title string + Source string // CommonMark for prose, raw source for runnable formats + Meta Meta +} + +// Meta is the artifact block of the receiving contract: shape, attribution and +// idempotency fields. Origin is named "source" on the wire; the top-level +// Source field carries the content. +type Meta struct { + Format string `json:"format"` + Category string `json:"category"` + Entry string `json:"entry,omitempty"` // required for html/react/vue, one file per artifact + Visibility string `json:"visibility"` + Egress string `json:"egress"` + Actor string `json:"actor"` + Origin string `json:"source"` // the producing subsystem, e.g. "pr-review" + RequestID string `json:"requestId"` + Version string `json:"version,omitempty"` + SentAt time.Time `json:"sentAt"` + Task *Task `json:"task,omitempty"` +} + +// Task carries the forge coordinates the artifact was produced for. +type Task struct { + Owner string `json:"owner"` + Repo string `json:"repo"` + Number int `json:"number"` + Task string `json:"task,omitempty"` +} + +// Sender publishes one artifact and returns the editor deep link for it. +type Sender interface { + Publish(ctx context.Context, a Artifact) (string, error) +} + +// Client is the Sender against a deployed editor. +type Client struct { + baseURL string + token string + client *http.Client + // wait is the base delay between 503 retries, doubled per attempt. + wait time.Duration +} + +// NewClient builds a Client against the editor origin. It returns nil when +// baseURL is empty, which is the disabled posture: the composition root skips +// wiring the sender entirely rather than carrying one that cannot be called. +func NewClient(baseURL, token string) *Client { + if baseURL == "" { + return nil + } + return &Client{ + baseURL: strings.TrimRight(baseURL, "/"), + token: token, + client: &http.Client{Timeout: 20 * time.Second}, + wait: 250 * time.Millisecond, + } +} + +// publishBody is the frozen receiving contract. Its shape is the public API; +// changing it is a contract change with the editor, not a refactor. +type publishBody struct { + Format string `json:"format"` + Title string `json:"title"` + Source string `json:"source"` + Artifact Meta `json:"artifact"` +} + +type publishResponse struct { + OK bool `json:"ok"` + ID string `json:"id"` + URL string `json:"url"` +} + +type errorResponse struct { + Error string `json:"error"` +} + +// Publish posts the artifact once. The full source is always sent: versions of +// record are full snapshots stored per publish, never diffs. +func (c *Client) Publish(ctx context.Context, a Artifact) (string, error) { + if c == nil { + return "", fmt.Errorf("artifactsync: sender is not configured") + } + body := publishBody{Format: contractFormat, Title: a.Title, Source: a.Source, Artifact: a.Meta} + payload, err := json.Marshal(body) + if err != nil { + return "", fmt.Errorf("artifactsync: encode artifact: %w", err) + } + + const attempts = 4 // the initial attempt plus three retries + var lastErr error + for attempt := 0; attempt < attempts; attempt++ { + if attempt > 0 { + select { + case <-ctx.Done(): + return "", fmt.Errorf("artifactsync: publish %q: %w", a.RequestID(), ctx.Err()) + case <-time.After(c.wait << (attempt - 1)): + } + } + url, retryable, err := c.postOnce(ctx, payload) + if err == nil { + return url, nil + } + lastErr = err + if !retryable { + return "", err + } + } + return "", fmt.Errorf("artifactsync: publish %q: %w", a.RequestID(), lastErr) +} + +// RequestID is the artifact's own idempotency key, for logging and for callers +// that compose one from the producer's natural key. +func (a Artifact) RequestID() string { return a.Meta.RequestID } + +// postOnce performs one HTTP attempt. retryable marks failures worth another +// attempt: 503 and transport errors. Client errors are configuration or shape +// mistakes and are surfaced immediately with the field reason. +func (c *Client) postOnce(ctx context.Context, payload []byte) (url string, retryable bool, err error) { + req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+"/api/artifacts", bytes.NewReader(payload)) + if err != nil { + return "", false, fmt.Errorf("artifactsync: build request: %w", err) + } + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+c.token) + + resp, err := c.client.Do(req) + if err != nil { + return "", true, fmt.Errorf("artifactsync: post artifact: %w", err) + } + defer resp.Body.Close() + + switch resp.StatusCode { + case http.StatusCreated: + var out publishResponse + if err := json.NewDecoder(resp.Body).Decode(&out); err != nil { + return "", false, fmt.Errorf("artifactsync: decode publish response: %w", err) + } + if out.URL == "" { + return "", false, fmt.Errorf("artifactsync: publish response carries no url") + } + return out.URL, false, nil + case http.StatusServiceUnavailable: + return "", true, fmt.Errorf("artifactsync: editor store unavailable (503)") + case http.StatusUnauthorized: + return "", false, fmt.Errorf("artifactsync: editor rejected the service token (401); check [artifacts].token") + case http.StatusBadRequest: + reason := "unknown" + raw, _ := io.ReadAll(io.LimitReader(resp.Body, 4096)) + var e errorResponse + if json.Unmarshal(raw, &e) == nil && e.Error != "" { + reason = e.Error + } + return "", false, fmt.Errorf("artifactsync: editor rejected the artifact (400): %s", reason) + default: + return "", true, fmt.Errorf("artifactsync: unexpected publish status %d", resp.StatusCode) + } +} diff --git a/internal/infrastructure/artifactsync/sender_test.go b/internal/infrastructure/artifactsync/sender_test.go new file mode 100644 index 000000000..930cf725c --- /dev/null +++ b/internal/infrastructure/artifactsync/sender_test.go @@ -0,0 +1,159 @@ +package artifactsync + +import ( + "context" + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "strings" + "sync/atomic" + "testing" + "time" +) + +func sampleArtifact() Artifact { + return Artifact{ + Title: "Review of PR #7", + Source: "# Review\n\none finding, one check", + Meta: Meta{ + Format: "markdown", + Category: "pr-review", + Visibility: "account-only", + Egress: "none", + Actor: "system:pr-reviewer", + Origin: "pr-review", + RequestID: "artifact:pr-review:acme/widget#7", + Version: "r1", + SentAt: time.Date(2026, 9, 22, 16, 45, 0, 0, time.UTC), + Task: &Task{Owner: "acme", Repo: "widget", Number: 7}, + }, + } +} + +func TestPublishPostsTheContractBody(t *testing.T) { + var gotPath, gotAuth string + var gotBody map[string]any + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + gotPath, gotAuth = r.URL.Path, r.Header.Get("Authorization") + body, _ := io.ReadAll(r.Body) + _ = json.Unmarshal(body, &gotBody) + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusCreated) + _, _ = w.Write([]byte(`{"ok":true,"id":"a_1","url":"https://offloaded.dev/collab?document=a_1"}`)) + })) + defer srv.Close() + + c := NewClient(srv.URL, "secret-token") + url, err := c.Publish(context.Background(), sampleArtifact()) + if err != nil { + t.Fatalf("Publish: %v", err) + } + if url != "https://offloaded.dev/collab?document=a_1" { + t.Fatalf("url = %q, want the editor deep link", url) + } + if gotPath != "/api/artifacts" { + t.Fatalf("path = %q, want /api/artifacts", gotPath) + } + if gotAuth != "Bearer secret-token" { + t.Fatalf("Authorization = %q, want the bearer token", gotAuth) + } + if gotBody["format"] != "offloaded-collab-artifact" { + t.Fatalf("top-level format = %v, want the contract envelope", gotBody["format"]) + } + if gotBody["title"] != "Review of PR #7" || gotBody["source"] != sampleArtifact().Source { + t.Fatalf("title/source did not round-trip: %v", gotBody) + } + artifact, ok := gotBody["artifact"].(map[string]any) + if !ok { + t.Fatalf("artifact block missing: %v", gotBody) + } + if artifact["format"] != "markdown" || artifact["category"] != "pr-review" { + t.Fatalf("artifact format/category = %v", artifact) + } + if artifact["actor"] != "system:pr-reviewer" || artifact["source"] != "pr-review" { + t.Fatalf("attribution = %v", artifact) + } + if artifact["requestId"] != "artifact:pr-review:acme/widget#7" || artifact["version"] != "r1" { + t.Fatalf("idempotency fields = %v", artifact) + } + if artifact["visibility"] != "account-only" || artifact["egress"] != "none" { + t.Fatalf("visibility/egress = %v", artifact) + } + task, ok := artifact["task"].(map[string]any) + if !ok || task["owner"] != "acme" || task["repo"] != "widget" { + t.Fatalf("task coordinates = %v", artifact["task"]) + } +} + +func TestPublishDoesNotRetryAClientError(t *testing.T) { + for _, status := range []int{http.StatusUnauthorized, http.StatusBadRequest} { + var attempts atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + attempts.Add(1) + w.WriteHeader(status) + _, _ = w.Write([]byte(`{"error":"source is required"}`)) + })) + _, err := NewClient(srv.URL, "tok").Publish(context.Background(), sampleArtifact()) + srv.Close() + if err == nil { + t.Fatalf("status %d: Publish error = nil, want failure", status) + } + if attempts.Load() != 1 { + t.Fatalf("status %d attempts = %d, want exactly one attempt", status, attempts.Load()) + } + } +} + +func TestPublishSurfacesTheFieldReasonOn400(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(http.StatusBadRequest) + _, _ = w.Write([]byte(`{"error":"source is required"}`)) + })) + defer srv.Close() + _, err := NewClient(srv.URL, "tok").Publish(context.Background(), sampleArtifact()) + if err == nil || !strings.Contains(err.Error(), "source is required") { + t.Fatalf("error = %v, want it to carry the field reason", err) + } +} + +func TestPublishRetries503UntilSuccess(t *testing.T) { + var attempts atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if attempts.Add(1) < 3 { + w.WriteHeader(http.StatusServiceUnavailable) + return + } + w.WriteHeader(http.StatusCreated) + _, _ = w.Write([]byte(`{"ok":true,"id":"a_2","url":"u"}`)) + })) + defer srv.Close() + + c := NewClient(srv.URL, "tok") + c.wait = time.Millisecond + url, err := c.Publish(context.Background(), sampleArtifact()) + if err != nil || url != "u" { + t.Fatalf("Publish = (%q, %v), want success after two 503s", url, err) + } + if attempts.Load() != 3 { + t.Fatalf("attempts = %d, want 3", attempts.Load()) + } +} + +func TestPublishFailsWhen503Persists(t *testing.T) { + var attempts atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + attempts.Add(1) + w.WriteHeader(http.StatusServiceUnavailable) + })) + defer srv.Close() + + c := NewClient(srv.URL, "tok") + c.wait = time.Millisecond + if _, err := c.Publish(context.Background(), sampleArtifact()); err == nil { + t.Fatal("Publish error = nil, want failure after exhausting retries") + } + if attempts.Load() != 4 { + t.Fatalf("attempts = %d, want the initial attempt plus three retries", attempts.Load()) + } +} diff --git a/internal/infrastructure/configuration/artifacts_config_test.go b/internal/infrastructure/configuration/artifacts_config_test.go new file mode 100644 index 000000000..a7bef8923 --- /dev/null +++ b/internal/infrastructure/configuration/artifacts_config_test.go @@ -0,0 +1,52 @@ +package configuration + +import ( + "os" + "path/filepath" + "testing" + + "github.com/samcharles93/archie-core/internal/config" +) + +func TestArtifactsConfigDefaults(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + contents := "bot_user = \"widget\"\n" + + "[forge]\ntype = \"gitea\"\nhost = \"https://git.example.test\"\ntoken_env = \"T\"\n" + if err := os.WriteFile(path, []byte(contents), 0o600); err != nil { + t.Fatal(err) + } + cfg, err := loadFile(path) + if err != nil { + t.Fatal(err) + } + if cfg.Artifacts.BaseURL != "" { + t.Errorf("BaseURL = %q, want empty so the sender stays disabled", cfg.Artifacts.BaseURL) + } + if cfg.Artifacts.TokenEnv != "WORKSPACE_INGEST_TOKEN" { + t.Errorf("TokenEnv = %q, want the documented fallback", cfg.Artifacts.TokenEnv) + } +} + +func TestArtifactsConfigPreservesExplicitValues(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + contents := "bot_user = \"widget\"\n" + + "[artifacts]\nbase_url = \"https://offloaded.dev\"\n" + + "token = { engine = \"env\", key = \"ARCHIE_GITHUB_TOKEN\" }\n" + + "token_env = \"OTHER_TOKEN\"\n" + if err := os.WriteFile(path, []byte(contents), 0o600); err != nil { + t.Fatal(err) + } + cfg, err := loadFile(path) + if err != nil { + t.Fatal(err) + } + if cfg.Artifacts.BaseURL != "https://offloaded.dev" { + t.Errorf("BaseURL = %q, want the explicit value", cfg.Artifacts.BaseURL) + } + if want := (config.SecretRef{Engine: "env", Key: "ARCHIE_GITHUB_TOKEN"}); cfg.Artifacts.Token != want { + t.Errorf("Token = %+v, want %+v", cfg.Artifacts.Token, want) + } + if cfg.Artifacts.TokenEnv != "OTHER_TOKEN" { + t.Errorf("TokenEnv = %q, want the explicit value", cfg.Artifacts.TokenEnv) + } +} diff --git a/internal/infrastructure/configuration/defaults.go b/internal/infrastructure/configuration/defaults.go index a328625ba..18344a82f 100644 --- a/internal/infrastructure/configuration/defaults.go +++ b/internal/infrastructure/configuration/defaults.go @@ -76,6 +76,7 @@ func (l *Loader) applyDefaults(cfg *config.Config) { } l.applyGeneralDefaults(cfg) applyForgeDefaults(cfg) + applyArtifactsDefaults(cfg) applyDispatchDefaults(cfg) applyIdentityDefaults(cfg) applyContainerDefaults(cfg) @@ -279,6 +280,17 @@ func applyForgeDefaults(cfg *config.Config) { } } +// applyArtifactsDefaults fills the artifacts section, promoting the +// token_env fallback to a secret reference when no explicit one was given. +func applyArtifactsDefaults(cfg *config.Config) { + if cfg.Artifacts.TokenEnv == "" { + cfg.Artifacts.TokenEnv = "WORKSPACE_INGEST_TOKEN" + } + if cfg.Artifacts.Token == (config.SecretRef{}) { + cfg.Artifacts.Token = config.SecretRef{Engine: "env", Key: cfg.Artifacts.TokenEnv} + } +} + // applyNATSDefaults resolves the nats mode from URL when the operator left it // unset. URL set implies external; URL empty implies embedded. func applyNATSDefaults(cfg *config.Config) {