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:<owner>/<repo>#<n>).
- 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.
This commit is contained in:
sam committed 2026-09-23 03:15:27 +10:00
1 parent 8542f0d42c
commit 0e6c6fc6d1
12 files changed
+817 -1

No files matched your search

+8
View File
@@ -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
+83
View File
@@ -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:<task-id>:<version>` when the producer is task-backed,
otherwise `artifact:<identity>:<sentAt-utc>`. 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.
+93 -1
View File
@@ -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)
}
+74
View File
@@ -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)
}
}
+18
View File
@@ -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.
@@ -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"
}
@@ -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)
}
}
+3
View File
@@ -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.
@@ -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)
}
}
@@ -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())
}
}
@@ -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)
}
}
@@ -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) {