reader-library.md

Reader Library

pkg/productize/runs is the public read-only library for inspecting daemon-managed runs through the shared snapshot, pagination, and stream APIs.

The snippets below are mirrored by executable examples in pkg/productize/runs/examples_test.go, so go test ./pkg/productize/runs compiles and runs the same usage patterns.

Import

import "github.com/itseffi/productize/pkg/productize/runs"

List

Use List to enumerate daemon-managed runs for one workspace.

workspaceRoot := "/path/to/workspace"

summaries, err := runs.List(workspaceRoot, runs.ListOptions{
	Status: []string{"completed", "failed"},
	Mode:   []string{"prd-tasks", "pr-review"},
	Limit:  20,
})
if err != nil {
	return err
}

for _, summary := range summaries {
	fmt.Printf("%s %s %s\n", summary.RunID, summary.Mode, summary.Status)
}

Open

Use Open when you already know the run id and want the resolved metadata plus replay/tail access through the daemon transport.

workspaceRoot := "/path/to/workspace"
runID := "run-20260406-120000"

run, err := runs.Open(workspaceRoot, runID)
if err != nil {
	return err
}

summary := run.Summary()
fmt.Printf("%s %s %s\n", summary.RunID, summary.Mode, summary.Status)

Replay

Use Replay to iterate historical events from a sequence number.

workspaceRoot := "/path/to/workspace"
runID := "run-20260406-120000"

run, err := runs.Open(workspaceRoot, runID)
if err != nil {
	return err
}

for event, replayErr := range run.Replay(0) {
	if replayErr != nil {
		return replayErr
	}
	fmt.Printf("%d %s\n", event.Seq, event.Kind)
}

Tail

Use Tail to replay historical events and then follow newly appended events until the context is canceled.

workspaceRoot := "/path/to/workspace"
runID := "run-20260406-120000"

run, err := runs.Open(workspaceRoot, runID)
if err != nil {
	return err
}

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

eventsCh, errsCh := run.Tail(ctx, 0)
for {
	select {
	case event, ok := <-eventsCh:
		if !ok {
			return nil
		}
		fmt.Printf("%d %s\n", event.Seq, event.Kind)
	case err, ok := <-errsCh:
		if ok && err != nil {
			return err
		}
	}
}

WatchWorkspace

Use WatchWorkspace to observe run lifecycle changes across the whole workspace.

workspaceRoot := "/path/to/workspace"

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

eventsCh, errsCh := runs.WatchWorkspace(ctx, workspaceRoot)
for {
	select {
	case event, ok := <-eventsCh:
		if !ok {
			return nil
		}
		status := ""
		if event.Summary != nil {
			status = event.Summary.Status
		}
		fmt.Printf("%s %s %s\n", event.Kind, event.RunID, status)
	case err, ok := <-errsCh:
		if ok && err != nil {
			return err
		}
	}
}

WatchWorkspace emits:

• created when the daemon reports a new run for the workspace
• status_changed when the daemon-backed RunSummary changes
• removed when a run disappears from the daemon-backed workspace listing