gh issue artifact stack 4/11: Add view - #14567

Part of the pull request stack tracked in #14563.

This adds gh issue artifact view from #14524.

Description

Issue artifacts are Markdown documents and links attached to an issue. The previous pull request added the gh issue artifact command group and list. This one adds view, which shows one artifact the way gh issue view shows an issue:

$ gh issue artifact view 142 2
OAuth callback plan monalisa/monas-cafe#142
Artifact 2 • generic • Copilot created about 3 days ago • monalisa updated about 2 hours ago


   OAuth callback plan

  1. Register the callback URL.
  2. Wire up  order-history  sync.


Edit history
12  monalisa  about 2 hours ago  Current
11  Copilot   about 5 hours ago
10  Copilot   about 7 hours ago
9   monalisa  about 1 day ago
8   Copilot   about 1 day ago
7   Copilot   about 1 day ago
6   Copilot   about 2 days ago
5   monalisa  about 2 days ago
4   Copilot   about 2 days ago
3   Copilot   about 3 days ago
2   Copilot   about 3 days ago
1   Copilot   about 3 days ago

View this issue on GitHub: https://github.com/monalisa/monas-cafe/issues/142

• A document's body is rendered as Markdown. A link shows its URL instead.
• The edit history lists every version the API returns, newest first. --version 5 shows version 5 instead, marked "Viewing".
• In a terminal, view uses the pager, like gh issue view. Piped output has key: lines, then -- and the raw body.
• --json has the same fields as list, plus versions, the edit history with each version's body.
• --web opens a link's URL in the browser.
• Like list, it refuses pull requests after one lookup and GitHub Enterprise Server before any artifact request. API errors are shown as the API returns them.

The client gains Get, for one artifact and its versions. The shared package gains three checks that later commands need too: the artifact number argument, refusing types gh doesn't know, and a strict check for http(s) URLs.

How did you test this change?

I recorded the built gh in bagtoad/issue-artifacts-demo viewing a document with its edit history, --version, a link, piped output, --json versions, --web on a link and on a document, and an artifact that doesn't exist, each checked with gh api, list or cat -t. It leaves out the pager, issue URL arguments, GitHub Enterprise Server, pull requests and types gh doesn't know.

Open chapters and agent notes

Key points

• No artifact URLs yet. [Design] gh issue artifact view #14524 shows a footer that links to the artifact's own page, --web opening a document's page, artifact URL arguments and a url field. The API doesn't return artifact URLs yet, as discussed in RFC: gh issue artifact #14529, so view keeps the first design: the footer links to the issue, and --web refuses a document with "artifact 2 is not a link; --web only opens link artifacts". A later pull request in this stack will add URLs.

• --version picks from the versions the API returned. The API returns them newest first, including the current one. findVersion looks the number up in that list:

  i := slices.IndexFunc(a.Versions, func(v client.Version) bool { return v.Version == number })
  switch {
  case i < 0:
  	// Not among the versions the API returned
  	return nil, fmt.Errorf("version %d not found for artifact %d", number, a.Number)
  case i == 0:
  	// The newest version is the current one, so show the default view
  	return nil, nil
  }
  return &a.Versions[i], nil

  --version can't be combined with --json, since --json versions has every version, or with --web.

• Types gh doesn't know are refused. As discussed in RFC: gh issue artifact #14529, a new artifact type needs a gh update, since it can need handling gh doesn't have. Until then, view fails with artifact 7 has type "bad-type", which this version of gh doesn't support; upgrade gh, with --json too. list still lists them.

• --web shows the whole URL. gh issue view --web shortens its message with text.DisplayURL, which drops the port, query and fragment. A link can point anywhere, so view shows it whole. A link whose stored body isn't an http(s) URL is refused. The shared check accepts only an absolute http or https URL with a host, in printable ASCII with no spaces.

• The pager is only for the terminal view. --json output never pages, like gh discussion view and unlike gh issue view. list follows the same rule.

• The edit history is a table without a header. The bold "Edit history" heading stands in for column headers, so it uses the table printer's NoHeader, like gh codespace view. "Current" is bold cyan, like "Newest comment" in gh issue view.

• Null values. A null user shows as ghost when its time exists, and a null time leaves out its part of the line. Piped output prints empty fields, and --json keeps null.

Notes for reviewers

Start with the view run function, which shows the order of the checks and the output paths. Then read printHumanArtifact and printEditHistory for the terminal layout. TestViewRun has a row for each rule, including a type gh doesn't know, null users and times with and without --version, a pager that fails to start, and a stored link that isn't an http(s) URL.

Three messages aren't in #14524, so each follows the closest existing message:

• specify only one of `--version` or `--web` , like the --json message.
• artifact 3 doesn't link to an http(s) URL; --web only opens http(s) URLs, for a stored link that isn't one.
• invalid artifact number: "abc", like invalid issue format: "abc".

Related issues:

• [Design] gh issue artifact view #14524 is the view design, with a screen for each scenario.
• RFC: gh issue artifact #14529 is the RFC for the command group. Its discussion covers new artifact types and artifact URLs.

Authorship and follow-up

Who wrote this:

• A human wrote it.
• An agent wrote it under close human direction.
• An agent wrote it independently, and no human has guided the implementation beyond the initial prompt.

Who answers review comments:

• @BagToad will read and reply directly. Name the account.
• An agent will draft replies and @BagToad will read them before they are posted.
• Nobody has explicitly committed to replying.