Add ability to cross-link runs

[exodist]

YathUI should support runs that live on other yathui servers. Clicking their links should take you to the remote URL.
Should also support synched runs, all data of the run is duplicated locally, but there is a link to the canonical run on a remote server.

[atoomic]

@Koan-Bot plan

[Koan-Bot]

Revised: Cross-link runs between YathUI servers with remote and synced run support

Changes in this iteration

• Phase 3 template path resolved: Confirmed the run detail template is share/templates/view.tx, rendered by lib/App/Yath/Server/Controller/View.pm. No longer a vague investigation step.
• Phase 4 option location decided: --canonical-base-url will be added to lib/App/Yath/Options/WebServer.pm (not DB.pm or inline). This is the correct home: the option configures how the web server presents itself externally, not how it connects to the database.
• Sync infrastructure noted: lib/App/Yath/Schema/Sync.pm already exists and handles run data replication. Phase 2 (synced runs) can build on this rather than implementing sync from scratch.

Summary

YathUI currently has no concept of runs living on other servers. This plan adds two related features: (1) remote runs — runs whose data lives on a remote YathUI instance, where clicking the run link redirects to the remote URL rather than trying to render data locally; and (2) synced runs — runs whose data has been fully replicated locally but carry a link back to the canonical source on a remote server. The existing Sync.pm module handles data replication already; this work adds the UI layer, schema columns, and web server configuration to make cross-server linking work.

Alternatives Considered

• Approach A (chosen): Add remote_url and canonical_url columns to the runs table. Remote runs have remote_url set and no local data; synced runs have full local data plus canonical_url pointing to the origin. Trade-off: minimal schema change, clean separation of the two use cases.
• Approach B: Store remote server registry separately. Define known remote servers in config, store only a server ID + run UUID in the runs table. Trade-off: more flexible for multi-server setups but adds indirection, a new config surface, and complexity not required by the issue.
• Approach C: Use a separate remote_runs table. Keep the runs table clean, store remote/synced metadata in a join table. Trade-off: avoids nullable columns but requires joins everywhere the runs table is queried; higher refactor cost.

Implementation Phases

Phase 1: Schema changes — add remote and canonical URL columns to runs

• What: Add two nullable text columns to all three schema result classes:

  • lib/App/Yath/Schema/MySQL/Run.pm
  • lib/App/Yath/Schema/PostgreSQL/Run.pm
  • lib/App/Yath/Schema/SQLite/Run.pm

  Columns:

  • remote_url (text, nullable) — set for remote runs; the full URL to the run on the remote server. When present, local data is absent and the UI redirects/links out.
  • canonical_url (text, nullable) — set for synced runs; the full URL to the canonical copy on the origin server. Local data is present.

  Also add a database migration script (follow the existing migration pattern in the repo).

• Why: Both features need to persist their remote URL. Keeping them as separate columns makes the two cases explicit and avoids a single overloaded field.

• Gotchas: The schema files are DBIx::Class result classes — add columns using add_columns following the exact pattern already used in each file. Check whether canon (boolean, already present) overlaps semantically with canonical_url; it appears to mean something different (local canonicality), so no conflict.

• Done when: All three result class files declare remote_url and canonical_url; a migration script exists; yath db-upgrade (or equivalent) applies cleanly on a fresh DB.

Phase 2: Synced run ingestion — populate canonical_url during sync

• What: In lib/App/Yath/Schema/Sync.pm, after write_sync/read_sync replicates a run, set canonical_url on the newly created local run row to {source_base_url}/view/{run_uuid}.

  The sync entry point (sync()) must accept a new optional source_base_url parameter. When provided, every synced run gets canonical_url populated.

• Why: The existing sync infrastructure already handles data replication. This phase adds only the bookkeeping needed for the UI to show a "view on origin" link.

• Gotchas: source_base_url is optional — existing sync callers that don't pass it must continue to work. Trailing slash normalization: strip trailing / before concatenating /view/{uuid}.

• Done when: After a sync with source_base_url set, the replicated run rows in the destination DB have canonical_url populated. Runs synced without source_base_url have canonical_url as NULL.

Phase 3: UI changes — render remote link and canonical link in run detail template

• What: Edit share/templates/view.tx and its backing controller lib/App/Yath/Server/Controller/View.pm.

  In View.pm:

  • Fetch remote_url and canonical_url from the run row.
  • Pass them as template variables.
  • If remote_url is set, redirect (302) immediately to remote_url rather than rendering the view. This handles the "clicking the link takes you to the remote URL" requirement.

  In view.tx:

  • When canonical_url is set (synced run), render a notice banner: e.g., "This run was synced from [canonical server]" with a hyperlink.
  • No template change needed for pure remote runs (controller redirects before the template is reached).

• Why: Remote runs should be transparent — users click a run link and land on the authoritative server. Synced runs should be discoverable locally but acknowledge their origin.

• Gotchas: The redirect must only happen when remote_url is set AND the request is for the run's own view URL (not an API/stream endpoint). Check lib/App/Yath/Server/Plack.pm routes — /view/:run_id covers this. Ensure the Files controller (lib/App/Yath/Server/Controller/Files.pm) also handles remote_url gracefully (currently constructs run_uri at line 80 — it should still return the local URI; the redirect is the viewer's responsibility).

• Done when: Requesting /view/{run_uuid} for a remote run returns a 302 to remote_url. Requesting it for a synced run renders the detail page with a visible "canonical source" banner linking to canonical_url.

Phase 4: CLI option — --canonical-base-url for the web server

• What: Add a canonical_base_url option to lib/App/Yath/Options/WebServer.pm following the existing option_group pattern:

  option canonical_base_url => (
      type        => 'Scalar',
      category    => "Web Server Options",
      description => "The public base URL of this YathUI server, used when generating canonical run links for sync consumers.",
      default     => undef,
  );

  In lib/App/Yath/Schema/RunProcessor.pm, where the run review link is already generated (around line 274), also expose the canonical URL in the same message if canonical_base_url is configured.

• Why: This option lets operators declare how their server is publicly addressable, so sync consumers can store the right canonical_url. It belongs in WebServer.pm because it describes how the web server presents itself externally — not a database connection parameter.

• Gotchas: This option is only meaningful when the server is the source in a sync relationship. Document this in the option description. It is not required for the remote-run redirect feature, which uses URLs stored per-run.

• Done when: yath server --canonical-base-url https://ci.example.com works without error; the option is accessible via $settings->webserver->canonical_base_url; RunProcessor includes the canonical URL in its output message when the option is set.

Phase 5: Run creation path — support inserting remote runs

• What: Provide a way to create a run row with remote_url set and no associated test data. The most likely entry point is the import/API layer. Find where runs are inserted (likely RunProcessor.pm or a dedicated importer) and add support for a --remote-url parameter that skips data ingestion and sets only remote_url + minimal metadata (project, user, timestamps).

• Why: Without a creation path, operators have no way to register a remote run so it appears in the local run list with an outbound link.

• Gotchas: A remote run has no jobs, events, or coverage data — any code that aggregates or queries these for a run must tolerate empty sets. Check lib/App/Yath/Server/Controller/View.pm redirect logic handles the case before attempting to fetch jobs.

• Done when: A remote run can be inserted via CLI; it appears in the run list; clicking it redirects to its remote_url.

Corner Cases

• run_uuid collision: If a synced run's UUID already exists locally (re-sync), update canonical_url rather than inserting a duplicate.
• Broken remote URL: The redirect for a remote run is a blind 302 — if the remote server is down, the user gets a browser error. Consider adding a small HTML interstitial that shows the URL so users can copy it even when the remote is unreachable.
• canonical_url on a non-synced run: Guard against accidentally setting canonical_url on a locally originated run — it should only be set by the sync ingestion path.
• Mixed run lists: The Files controller constructs run_uri using $req->base . "view/" . $run->run_uuid — this local URI is correct even for remote runs (the redirect happens at the view controller level). No change needed there.
• Trailing slash normalization: Ensure canonical_base_url and any stored URLs have consistent trailing-slash handling before concatenation.
• URL scheme: If the server is behind a reverse proxy, $req->base may return http:// when the public URL is https://. The canonical_base_url option solves this for the source server; for stored remote_url / canonical_url values, document that operators must supply the correct public scheme.

Testing Strategy

• Unit tests for schema: Verify remote_url and canonical_url columns exist and accept NULL/string values.
• Unit test for sync: Call Sync::sync() with source_base_url set; assert the resulting run row has canonical_url = "{source_base_url}/view/{uuid}".
• Controller test for redirect: Insert a run with remote_url = "https://remote.example.com/view/abc", issue GET /view/{uuid}, assert 302 response with Location: https://remote.example.com/view/abc.
• Template test for canonical banner: Insert a synced run with canonical_url set, render the view, assert the banner text and link are present.
• CLI option smoke test: Start the server with --canonical-base-url and verify $settings->webserver->canonical_base_url returns the value.

Risks & Alternatives

• Risk: The redirect approach for remote runs is simple but means the local server has no way to show any metadata about the remote run (title, status) before sending the user away. If operators want a preview page, the approach would need to change to an async fetch of remote metadata — out of scope for now.
• Risk: Schema migrations need to be applied across all three DB drivers (MySQL, PostgreSQL, SQLite). If the migration pattern is inconsistent across driver schema files, additional investigation of the migration tooling may be needed before Phase 1 can be completed.

Open Questions

• Should remote runs appear in the local run list (requiring at minimum project + timestamp metadata to be stored), or should the run list only show runs with local data? The current plan assumes they appear in the list (otherwise the redirect feature is unreachable from the UI).
• Is there an existing HTTP API endpoint for registering runs, or will Phase 5 require adding one? Clarification needed before starting Phase 5.

⚠️ Plan review flagged unresolved items after 3 rounds — human review recommended.

• Phase 1, Concrete file paths: The migration script location is not specified. The plan says "Also add a database migration script (follow the existing migration pattern in the repo)" but doesn't name the directory or file path where migrations are stored (e.g., lib/App/Yath/Schema/Migrations/YYYY-MM-DD_add_remote_canonical_urls.pm or similar).
• Phases 1–4, Testing strategy: All testing strategies list specific assertions (e.g., "assert remote_url and canonical_url columns exist") but don't name the test files. A concrete testing strategy must specify which test files to add/update, e.g., "update t/schema/run.t to add...", "create t/controller/view_redirect.t with...", etc. Currently the test scenarios are too vague to execute.
• Phase 5, Concrete file paths: The plan says "Find where runs are inserted (likely RunProcessor.pm or a dedicated importer)" — this is a research task, not a concrete file path. The phase should either name the exact file and location (e.g., lib/App/Yath/Schema/RunProcessor.pm, line ~274, in subroutine X) or move this unknown to the "Open Questions" section before the implementation plan starts, so it can be resolved before Phase 5 execution begins.
• Phase 5, Testing strategy: The testing strategy is vague — "A remote run can be inserted via CLI; it appears in the run list; clicking it redirects to its remote_url" doesn't specify test file locations, test structure (unit vs. integration), or specific test function names. This must be concrete.

---

Generated by Kōan /plan — iteration on existing issue