distributor/docs/roadmap/link_generation.md

Roadmap: Link Generation Support

Purpose

Add destination-aware link generation so distributor can record human-usable URLs for published artifacts.

This feature should be implemented after destination path mapping so generated URLs use the final archive or fixed destination path semantics. It prepares the project for notification adapters, richer inspect/status output, static-site UX, and future feed generation.

Current Implementation Grounding

Current publish planning produces publish.Output values with destination path, source path, kind, transform, SHA-256, size, and optional generated data.

Current .distributor.json output records contain path, kind, source path, transform, SHA-256, and size. They do not contain URL metadata, and destination state has no top-level links block.

Current destination bundle paths preserve the source-root-relative bundle path. Latest/fixed path mapping is not implemented yet.

Goals

• Add optional destination-level link configuration.
• Generate per-output URLs when a destination has links.base_url.
• Record generated URLs in destination state when configured.
• Select a deterministic primary URL when possible.
• Keep link generation destination-local and independent of producer manifests.
• Do not infer public URLs from backend configuration automatically.

Non-Goals

• Do not deliver notifications.
• Do not require every destination to expose URLs.
• Do not add static-site indexes or feeds.
• Do not add latest path mapping.
• Do not change source manifest schema.

Configuration Shape

Add optional destination-level config:

links:
  base_url: https://weather.example.com
  primary: auto

Semantics:

• links.base_url: absolute HTTP or HTTPS URL corresponding to the destination backend root.
• links.primary: optional primary-link selection policy.

Initial primary policies:

• auto: choose the best available output;
• html: prefer generated HTML outputs;
• source: prefer copied source outputs.

If links is absent, no URL metadata is generated.

URL Construction

Construct URLs from:

1. links.base_url;
2. destination bundle path relative to the destination backend root;
3. output path relative to the destination bundle path.

Use URL path joining and escaping rules, not filesystem or storage path joins. Preserve any path prefix in base_url. Reject base_url values with query strings or fragments.

For index.html, generate a directory-style URL by omitting the filename:

https://weather.example.com/daily/brentwood/2026-06-01/

For other outputs, include the output filename:

https://weather.example.com/daily/brentwood/2026-06-01/report.html

index.html recognition should apply to any output path ending in /index.html or exactly index.html.

Primary Link Selection

For primary: auto, select in deterministic publish-plan order:

1. any index.html output;
2. first generated HTML output;
3. first source output;
4. no primary URL.

For primary: html, prefer generated HTML outputs. For primary: source, prefer source outputs. If no output matches the policy, record no primary link rather than failing publication.

Destination State

When links are configured, destination state should record:

• optional per-output URL metadata;
• optional top-level primary URL metadata.

Destinations without links should continue producing state without URL metadata.

Because distributor is still pre-release, URL metadata should be added as optional state schema version 1 fields rather than introducing destination state schema version 2 for this feature. Post-release, materially richer state semantics should use an explicit schema versioning policy.

Relationship To Other Roadmaps

HTML index mode is not required, but link generation should treat index.html as the preferred URL shape when present.

Latest path destinations should provide the destination bundle path mapping needed to build fixed/latest URLs correctly.

Producer-facing manifest creation and remote validation are independent of URL metadata.

CLI display of generated primary links should follow docs/roadmap/cli_output_policy.md so link output is exposed through the shared --format text|json model rather than one-off command output.

Testing Expectations

Suggested coverage:

• config validation accepts absent links;
• config validation accepts valid HTTP and HTTPS base URLs;
• config validation rejects invalid schemes, query strings, and fragments;
• nested bundle paths generate correct URLs;
• index.html URLs omit the filename;
• non-index URLs include filenames;
• primary selection is deterministic;
• state records URLs when configured;
• destinations without links produce no URL metadata.

Documentation Updates After Implementation

• Update docs/config.md with destination links fields.
• Update docs/operations.md with static-site URL examples.
• Update docs/internal/state.md if destination state changes.
• Update docs/cli.md only if run or inspect output displays links.

Keep this roadmap under docs/roadmap/ until implemented.

Decisions

• URL metadata is added as optional destination state schema version 1 fields while distributor remains pre-release.
• v1 implements links.primary so future notification and operator-output features have one canonical primary-link selection policy.
• run and inspect output should not display generated primary links immediately. Link display should wait for docs/roadmap/cli_output_policy.md or another explicit inspect/status output mode.

Future Work

• Define a post-release destination state schema bump policy before introducing materially incompatible state changes.
• Add CLI display of primary links through an explicit output mode or status command, preferably the shared --format text|json policy in docs/roadmap/cli_output_policy.md, rather than changing routine run output opportunistically.
• Add richer link policies only if auto, html, and source prove insufficient.