Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

22.3 KB
Raw Blame
package cmd

import (
	"bufio"
	"bytes"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"slices"
	"sort"
	"strings"
	"text/tabwriter"

	"github.com/spf13/cobra"

	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/intel"
	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/intelapi"
)

var intelOpts struct {
	kind   string
	limit  int
	json   bool
	file   string
	failOn string
}

var intelCmd = &cobra.Command{
	Use:   "intel",
	Short: "Check MCP servers and skills against Beacon Intel",
	Long: `Check MCP servers and agent skills against Beacon Intel (https://intel.beacon.sh), the
free public index of what MCP and skill registries list, with a security verdict for each one
that has been analyzed. No account or key is needed.

An artifact is named by a GitHub URL or owner/repo, a package (npm:<name>, pypi:<name>,
@scope/name), a name, or an entity key as lookup prints it. Each command sends only what you
name to the Beacon Intel API; set BEACON_INTEL=0 to turn these commands off, or
BEACON_INTEL_URL to use another host.

Risk is high, medium, low, benign, or unchecked (listed but not analyzed). Coverage is
complete or partial: partial means the analysis did not cover everything, so it is never a
clearance, whatever the risk. Not found means the index has never checked it: it never means
safe.`,
}

var intelLookupCmd = &cobra.Command{
	Use:          "lookup <name | owner/repo | url | package | key>",
	Short:        "Find MCP servers and skills and show their risk",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runIntelLookup,
}

var intelShowCmd = &cobra.Command{
	Use:          "show <entity-key>",
	Short:        "Show one artifact's verdict, findings, lineage and advisories",
	Args:         cobra.ExactArgs(1),
	SilenceUsage: true,
	RunE:         runIntelShow,
}

var intelCheckCmd = &cobra.Command{
	Use:   "check [<artifact>...]",
	Short: "Check many MCP servers and skills in one request",
	Long: `Check up to 50 MCP servers and skills in one request. Name them as arguments, or one per
line in a file with --file (- reads standard input; blank lines and # comments are skipped).
Nothing you send is stored.

Each is matched (with its risk), ambiguous (no artifact has exactly that name: check one of
the candidates by its key), or not_found. --fail-on exits non-zero when any matched artifact
is at or above a risk, for use in CI; --fail-on partial also fails one whose coverage is
partial, at any risk. A matched artifact whose risk this beacon does not recognize fails every
--fail-on.`,
	SilenceUsage: true,
	RunE:         runIntelCheck,
}

var intelStatusCmd = &cobra.Command{
	Use:          "status",
	Short:        "Show how much Beacon Intel covers and how current it is",
	Args:         cobra.NoArgs,
	SilenceUsage: true,
	RunE:         runIntelStatus,
}

func init() {
	rootCmd.AddCommand(intelCmd)
	intelCmd.AddCommand(intelLookupCmd, intelShowCmd, intelCheckCmd, intelStatusCmd)
	for _, c := range []*cobra.Command{intelLookupCmd, intelShowCmd, intelCheckCmd, intelStatusCmd} {
		c.Flags().BoolVar(&intelOpts.json, "json", false, "Print the API's JSON answer")
	}
	intelLookupCmd.Flags().StringVar(&intelOpts.kind, "kind", "", "Only mcp or skill")
	intelLookupCmd.Flags().IntVar(&intelOpts.limit, "limit", 10, fmt.Sprintf("Results to show (at most %d)", intelapi.MaxLimit))
	intelCheckCmd.Flags().StringVar(&intelOpts.kind, "kind", "", "Read every artifact as mcp or skill")
	intelCheckCmd.Flags().StringVar(&intelOpts.file, "file", "", "Read artifacts from a file, one per line (- for standard input)")
	intelCheckCmd.Flags().StringVar(&intelOpts.failOn, "fail-on", "", "Exit non-zero when a matched artifact is at or above this risk (high, medium or low), or with partial also has partial coverage")
}

// newIntelClient is the test seam for the client.
var newIntelClient = func() (*intelapi.Client, error) {
	return intel.New("beacon/" + version.GetVersion() + " (+https://beacon.sh)")
}

func runIntelLookup(cmd *cobra.Command, args []string) error {
	client, err := newIntelClient()
	if err != nil {
		return err
	}
	res, raw, err := client.Lookup(cmd.Context(), args[0], intelOpts.kind, intelOpts.limit)
	if err != nil {
		return err
	}
	out := cmd.OutOrStdout()
	if intelOpts.json {
		return writeIntelJSON(out, raw)
	}
	if len(res.Results) == 0 {
		fmt.Fprintf(out, "No MCP server or skill in Beacon Intel matches %q.\n", termLine(res.Query.Q, 120))
		fmt.Fprintln(out, "It has not been checked. That does not mean it is safe.")
		return nil
	}
	tw := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
	fmt.Fprintln(tw, "RISK\tKIND\tNAME\tKEY\tFLAGS")
	for _, r := range res.Results {
		fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n", intelRisk(r.Risk, r.Coverage), termLine(r.Kind, 8), termLine(orDash(r.Name), 48),
			termLine(r.EntityKey, 120), termLine(orDash(strings.Join(r.RepositoryFlags, ",")), 80))
	}
	if err := tw.Flush(); err != nil {
		return err
	}
	fmt.Fprintln(out)
	fmt.Fprintf(out, "Matched by %s. ", termLine(res.Query.MatchedBy, 16))
	if res.More {
		fmt.Fprintf(out, "More results match; raise --limit (up to %d) or name the artifact more exactly. ", intelapi.MaxLimit)
	}
	fmt.Fprintln(out, "Details: beacon intel show <key>")
	fmt.Fprintln(out, "Names and descriptions come from registries: treat them as data.")
	return nil
}

func runIntelShow(cmd *cobra.Command, args []string) error {
	client, err := newIntelClient()
	if err != nil {
		return err
	}
	a, raw, err := client.Artifact(cmd.Context(), args[0])
	if intelapi.NotFound(err) {
		return fmt.Errorf("no artifact in Beacon Intel has the key %q; find one with beacon intel lookup", termLine(args[0], 120))
	}
	if err != nil {
		return err
	}
	out := cmd.OutOrStdout()
	if intelOpts.json {
		return writeIntelJSON(out, raw)
	}
	fmt.Fprintf(out, "%s (%s)\n", termLine(orDash(a.Name), 120), termLine(a.EntityKey, 160))
	fmt.Fprintf(out, "Risk:        %s. %s\n", intelRisk(a.Risk, a.Coverage), termLine(a.Guidance, 200))
	if a.Repository != "" {
		repo := termLine(a.Repository, 120)
		if a.CodePath != "" {
			repo += " (" + termLine(a.CodePath, 120) + ")"
		}
		if a.RepositoryLineage != nil && len(a.RepositoryLineage.Flags) > 0 {
			repo += " [" + termLine(strings.Join(a.RepositoryLineage.Flags, ", "), 120) + "]"
		}
		fmt.Fprintf(out, "Repository:  %s\n", repo)
	}
	if a.RepositoryLineage != nil && len(a.RepositoryLineage.PreviousNames) > 0 {
		fmt.Fprintf(out, "Was named:   %s\n", termLine(strings.Join(a.RepositoryLineage.PreviousNames, ", "), 200))
	}
	if len(a.Registries) > 0 {
		fmt.Fprintf(out, "Listed on:   %s\n", termLine(strings.Join(a.Registries, ", "), 200))
	}
	if v := a.Verdict; v != nil {
		line := "Analyzed:    " + termLine(orDash(v.AnalyzedAt), 40)
		if v.Model != "" {
			line += " by " + termLine(v.Model, 80)
		}
		if v.Commit != "" {
			line += " at commit " + termLine(v.Commit, 40)
		}
		fmt.Fprintln(out, line)
		if v.Coverage != "" {
			fmt.Fprintf(out, "Coverage:    %s\n", termLine(v.Coverage, 16))
		}
	}
	fmt.Fprintf(out, "Page:        %s\n", termLine(a.URL, 300))
	if v := a.Verdict; v != nil {
		printIntelList(out, "Reasons", v.Reasons)
		printIntelList(out, "Why coverage is partial", v.CoverageReasons)
		if len(v.Findings) > 0 || v.RefutedFindings > 0 {
			fmt.Fprintf(out, "\nFindings (%d shown of %d; %d refuted on review):\n", len(v.Findings), v.FindingsTotal, v.RefutedFindings)
			for _, f := range v.Findings {
				where := termLine(f.Path, 160)
				if len(f.Lines) == 2 {
					where += fmt.Sprintf(":%d-%d", f.Lines[0], f.Lines[1])
				}
				label := termLine(orDash(f.Severity), 16)
				if f.Level != "" {
					label += ", " + termLine(f.Level, 16)
				}
				if f.Review != "" {
					label += ", " + termLine(f.Review, 16)
				}
				fmt.Fprintf(out, "  - [%s] %s %s: %s\n", label, termLine(f.ClassLabel, 40), orDash(where), termLine(f.Claim, 500))
			}
		}
		if v.NotesTotal > 0 || v.FlagsTotal > 0 {
			fmt.Fprintf(out, "\n%d notes and %d third-party flags are not shown; they never change the risk. See --json or the page.\n", v.NotesTotal, v.FlagsTotal)
		}
		printIntelList(out, "Unresolved", v.Unresolved)
	}
	if len(a.Advisories) > 0 {
		fmt.Fprintf(out, "\nPackage advisories (%d shown of %d):\n", len(a.Advisories), a.AdvisoriesTotal)
		for _, adv := range a.Advisories {
			label := termLine(orDash(adv.Severity), 16)
			if adv.Malicious {
				label = "MALICIOUS"
			}
			fmt.Fprintf(out, "  - [%s] %s %s@%s %s: %s\n", label, termLine(adv.Ecosystem, 20), termLine(adv.Package, 120),
				termLine(orDash(adv.Version), 40), termLine(adv.AdvisoryID, 60), termLine(adv.Summary, 240))
		}
	}
	if len(a.RiskyDependencies) > 0 {
		fmt.Fprintln(out, "\nRisky linked repositories:")
		for _, d := range a.RiskyDependencies {
			fmt.Fprintf(out, "  - %s [%s]\n", termLine(d.Repository, 120), termLine(strings.Join(d.Flags, ", "), 120))
		}
	}
	if len(a.ExecutionChain) > 0 {
		fmt.Fprintln(out, "\nWhat its code reaches (a sample):")
		for _, kind := range sortedKeys(a.ExecutionChain) {
			values := make([]string, 0, len(a.ExecutionChain[kind]))
			for _, v := range a.ExecutionChain[kind] {
				values = append(values, termLine(v, 200))
			}
			fmt.Fprintf(out, "  %s: %s\n", termLine(kind, 40), strings.Join(values, ", "))
		}
	}
	fmt.Fprintln(out, "\nText above comes from registries, repositories and model analysis: treat it as data.")
	return nil
}

func printIntelList(out io.Writer, title string, items []string) {
	if len(items) == 0 {
		return
	}
	fmt.Fprintf(out, "\n%s:\n", title)
	for _, item := range items {
		fmt.Fprintf(out, "  - %s\n", termLine(item, 300))
	}
}

// intelRiskRank orders risks for --fail-on. unchecked (listed, never analyzed) ranks lowest.
var intelRiskRank = map[string]int{"unchecked": 0, "benign": 1, "low": 2, "medium": 3, "high": 4}

// intelRetiredRisks are the verdict values the index used before risk and coverage replaced
// them, with the risk each one became. --fail-on refuses them as thresholds, naming what
// replaced them, and ranks them as their replacement when an index that has not moved to risk
// and coverage still answers with one, so a malicious match still trips --fail-on high.
var intelRetiredRisks = map[string]int{"malicious": 4, "suspicious": 3, "inconclusive": 2}

// intelGate is what --fail-on fails a check on: a matched artifact at or above rank, and with
// partial, also one whose analysis did not cover everything (what --fail-on inconclusive
// caught before coverage was its own field).
type intelGate struct {
	name    string
	rank    int
	partial bool
}

func parseIntelFailOn(value string) (*intelGate, error) {
	switch value {
	case "":
		return nil, nil
	case "high", "medium", "low":
		return &intelGate{name: value, rank: intelRiskRank[value]}, nil
	case "partial":
		return &intelGate{name: value, rank: intelRiskRank["low"], partial: true}, nil
	}
	if _, ok := intelRetiredRisks[value]; ok {
		hint := "use high, medium or low"
		if value == "inconclusive" {
			hint = "use partial, which fails on low or above and on partial coverage at any risk, as inconclusive did"
		}
		return nil, fmt.Errorf("--fail-on %s is no longer a risk: Beacon Intel now rates risk as high, medium, low or benign, with coverage apart; %s", value, hint)
	}
	return nil, fmt.Errorf("--fail-on must be high, medium, low or partial, not %q", termLine(value, 40))
}

// intelRetiredShape reports whether a check answer comes from an index still on the retired
// verdicts: its counts or results carry malicious, suspicious or inconclusive, or no matched
// result names a coverage at all (the current shape always does). In that shape the verdict
// carried coverage itself, inconclusive being the partial one, so a benign there was covered
// and --fail-on partial must not read its missing coverage as unrecognized. An answer where
// some matched results name a coverage and others do not is current, and still fails closed.
func intelRetiredShape(res *intelapi.CheckResult) bool {
	for key, n := range res.Counts {
		if _, ok := intelRetiredRisks[key]; ok && n > 0 {
			return true
		}
	}
	matched := false
	for _, r := range res.Results {
		if r.Status != "matched" {
			continue
		}
		if _, ok := intelRetiredRisks[r.Risk]; ok {
			return true
		}
		if r.Coverage != "" {
			return false
		}
		matched = true
	}
	return matched
}

// fails says why a check result fails the gate, or "" when it passes. Only matched results
// can fail: ambiguous and not_found claim no risk. It fails closed: a matched result whose
// risk this build does not know fails at every threshold rather than ranking lowest, and with
// partial, so does one whose coverage is neither complete nor partial.
// retiredShape is intelRetiredShape of the whole answer.
func (g *intelGate) fails(r intelapi.CheckOutcome, retiredShape bool) string {
	if r.Status != "matched" {
		return ""
	}
	risk := termLine(orDash(r.Risk), 16)
	rank, known := intelRiskRank[r.Risk]
	retired := false
	if !known {
		rank, retired = intelRetiredRisks[r.Risk]
		known = retired
	}
	switch {
	case !known:
		return fmt.Sprintf("%s (risk %s not recognized)", termLine(r.Q, 80), risk)
	case rank >= g.rank:
		if r.Coverage == "partial" {
			return fmt.Sprintf("%s (%s, partial)", termLine(r.Q, 80), risk)
		}
		return fmt.Sprintf("%s (%s)", termLine(r.Q, 80), risk)
	case !g.partial || r.Risk == "unchecked" || retired || r.Coverage == "complete" || (retiredShape && r.Coverage == ""):
		// unchecked was never analyzed, so it has no coverage, and a retired verdict carried
		// its coverage in the verdict itself (inconclusive ranks as low above), as does a
		// benign in an answer of the retired shape.
		return ""
	case r.Coverage == "partial":
		return fmt.Sprintf("%s (%s, partial)", termLine(r.Q, 80), risk)
	default:
		return fmt.Sprintf("%s (%s, coverage %s not recognized)", termLine(r.Q, 80), risk, termLine(orDash(r.Coverage), 16))
	}
}

func (g *intelGate) describe() string {
	if g.partial {
		return "at or above low or with partial coverage"
	}
	return "at or above " + g.name
}

// intelRisk is a risk as the tables print it, marked when the analysis covered only part of
// the artifact, which is never a clearance.
func intelRisk(risk, coverage string) string {
	out := termLine(orDash(risk), 16)
	if coverage == "partial" {
		out += " (partial)"
	}
	return out
}

// errIntelCheckFailed is the error --fail-on returns; its message names what failed.
var errIntelCheckFailed = errors.New("intel check failed")

func runIntelCheck(cmd *cobra.Command, args []string) error {
	gate, err := parseIntelFailOn(intelOpts.failOn)
	if err != nil {
		return err
	}
	if err := intelapi.ValidateKind(intelOpts.kind); err != nil {
		return err
	}
	names := append([]string(nil), args...)
	if intelOpts.file != "" {
		fromFile, err := readIntelCheckFile(cmd.InOrStdin(), intelOpts.file)
		if err != nil {
			return err
		}
		names = append(names, fromFile...)
	}
	if len(names) == 0 {
		return errors.New("name artifacts to check as arguments or with --file")
	}
	if len(names) > intelapi.MaxCheck {
		return fmt.Errorf("at most %d artifacts per check, got %d; split them into several checks", intelapi.MaxCheck, len(names))
	}
	items := make([]intelapi.CheckItem, len(names))
	for i, name := range names {
		items[i] = intelapi.CheckItem{Q: name, Kind: intelOpts.kind}
	}
	client, err := newIntelClient()
	if err != nil {
		return err
	}
	res, raw, err := client.Check(cmd.Context(), items)
	if err != nil {
		return err
	}
	out := cmd.OutOrStdout()
	if intelOpts.json {
		if err := writeIntelJSON(out, raw); err != nil {
			return err
		}
	} else {
		tw := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
		fmt.Fprintln(tw, "STATUS\tRISK\tARTIFACT\tMATCH")
		for _, r := range res.Results {
			match := "-"
			switch {
			case r.Status == "matched" && len(r.Matches) > 0:
				match = r.Matches[0].EntityKey
			case r.Status == "ambiguous":
				keys := make([]string, 0, len(r.Matches))
				for _, m := range r.Matches {
					keys = append(keys, m.EntityKey)
				}
				match = "candidates: " + strings.Join(keys, ", ")
			}
			fmt.Fprintf(tw, "%s\t%s\t%s\t%s\n", termLine(r.Status, 16), intelRisk(r.Risk, r.Coverage), termLine(r.Q, 80), termLine(match, 300))
		}
		if err := tw.Flush(); err != nil {
			return err
		}
		fmt.Fprintln(out)
		fmt.Fprintln(out, intelCountsLine(res.Counts))
		fmt.Fprintln(out, "not_found means never checked, not safe; partial coverage is never a clearance. Details: beacon intel show <key>")
	}
	if gate != nil {
		var failed []string
		retiredShape := intelRetiredShape(res)
		for _, r := range res.Results {
			if why := gate.fails(r, retiredShape); why != "" {
				failed = append(failed, why)
			}
		}
		if len(failed) > 0 {
			return fmt.Errorf("%w: %d %s: %s", errIntelCheckFailed, len(failed), gate.describe(), strings.Join(failed, ", "))
		}
	}
	return nil
}

// intelCountKeys are the check counts in the order the summary line prints them.
var intelCountKeys = []string{"high", "medium", "low", "benign", "unchecked", "ambiguous", "not_found"}

func intelCountsLine(counts map[string]int) string {
	parts := []string{}
	for _, key := range intelCountKeys {
		if counts[key] > 0 {
			parts = append(parts, fmt.Sprintf("%d %s", counts[key], key))
		}
	}
	// Never hide a count the server sent: one this build does not know (a retired verdict
	// such as malicious, or a value added later) is printed after the known ones.
	var others []string
	for key, n := range counts {
		if n > 0 && key != "partial" && !slices.Contains(intelCountKeys, key) {
			others = append(others, key)
		}
	}
	sort.Strings(others)
	for _, key := range others {
		parts = append(parts, fmt.Sprintf("%d %s", counts[key], termLine(key, 32)))
	}

	if len(parts) == 0 {
		return "Nothing checked."
	}
	line := strings.Join(parts, ", ") + "."
	// partial overlaps the risk counts: how many of the matched ones had partial coverage.
	if n := counts["partial"]; n > 0 {
		line += fmt.Sprintf(" %d matched with partial coverage.", n)
	}
	return line
}

// intelCheckFileMax bounds what --file reads.
const intelCheckFileMax = 1 << 20

func readIntelCheckFile(stdin io.Reader, path string) ([]string, error) {
	var r io.Reader
	if path == "-" {
		r = stdin
	} else {
		f, err := os.Open(path)
		if err != nil {
			return nil, err
		}
		defer f.Close()
		r = f
	}
	// Read one byte past the limit so a longer file is refused rather than cut short: an
	// artifact past the cut would go unchecked, and --fail-on would pass without it.
	data, err := io.ReadAll(io.LimitReader(r, intelCheckFileMax+1))
	if err != nil {
		return nil, err
	}
	if len(data) > intelCheckFileMax {
		return nil, fmt.Errorf("--file is larger than %d bytes; a check names at most %d artifacts, so split the list", intelCheckFileMax, intelapi.MaxCheck)
	}
	var names []string
	scanner := bufio.NewScanner(bytes.NewReader(data))
	for scanner.Scan() {
		line := strings.TrimSpace(scanner.Text())
		if line == "" || strings.HasPrefix(line, "#") {
			continue
		}
		names = append(names, line)
	}
	return names, scanner.Err()
}

func runIntelStatus(cmd *cobra.Command, args []string) error {
	client, err := newIntelClient()
	if err != nil {
		return err
	}
	s, raw, err := client.Status(cmd.Context())
	if err != nil {
		return err
	}
	out := cmd.OutOrStdout()
	if intelOpts.json {
		return writeIntelJSON(out, raw)
	}
	fmt.Fprintf(out, "Beacon Intel: %s\n\n", client.BaseURL)
	tw := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
	fmt.Fprintln(tw, "KIND\tLISTED\tANALYZED\tHIGH\tMEDIUM\tLOW\tBENIGN\tPARTIAL")
	for _, kind := range []string{"mcp", "skill"} {
		k := s.Index[kind]
		fmt.Fprintf(tw, "%s\t%d\t%d\t%d\t%d\t%d\t%d\t%d\n", kind, k.Artifacts, k.Analyzed, k.High, k.Medium, k.Low, k.Benign, k.Partial)
	}
	if err := tw.Flush(); err != nil {
		return err
	}
	for _, kind := range []string{"mcp", "skill"} {
		if line := intelStatusOthers(kind, s.Index[kind]); line != "" {
			fmt.Fprintln(out, line)
		}
	}
	fmt.Fprintf(out, "\nNewest verdict:         %s\n", termLine(orDash(s.LatestAnalyzedAt), 40))
	fmt.Fprintf(out, "Newest registry update: %s\n", termLine(orDash(s.LatestListedAt), 40))
	return nil
}

// intelStatusOthers names analyzed artifacts the table's risk columns do not show: counts
// under a risk this build does not know (an index still on the retired verdicts answers with
// malicious, suspicious and inconclusive), and analyzed artifacts no count accounts for.
// PARTIAL overlaps the risk columns, so it is not part of the sum.
func intelStatusOthers(kind string, k intelapi.IndexCounts) string {
	var parts []string
	keys := make([]string, 0, len(k.Other))
	for key := range k.Other {
		keys = append(keys, key)
	}
	sort.Strings(keys)
	shown := k.High + k.Medium + k.Low + k.Benign
	for _, key := range keys {
		if n := k.Other[key]; n > 0 {
			parts = append(parts, fmt.Sprintf("%d %s", n, termLine(key, 32)))
			shown += n
		}
	}
	if rest := k.Analyzed - shown; rest > 0 {
		parts = append(parts, fmt.Sprintf("%d with no risk count", rest))
	}
	if len(parts) == 0 {
		return ""
	}
	return fmt.Sprintf("%s also: %s (not in the columns above; --json shows the full answer)", kind, strings.Join(parts, ", "))
}

// writeIntelJSON re-indents the API's answer. It was decoded already, so it is valid JSON.
// encoding/json escapes C0 controls but writes C1 controls and bidirectional formatting
// characters as they are, so those are escaped here: the JSON decodes the same, and the
// terminal never sees them raw. They can only occur inside strings.
func writeIntelJSON(out io.Writer, raw []byte) error {
	var v any
	if err := json.Unmarshal(raw, &v); err != nil {
		return err
	}
	var buf bytes.Buffer
	enc := json.NewEncoder(&buf)
	enc.SetIndent("", "  ")
	if err := enc.Encode(v); err != nil {
		return err
	}
	var b strings.Builder
	for _, r := range buf.String() {
		if r >= 0x80 && intelapi.IsUnsafeRune(r) {
			fmt.Fprintf(&b, "\\u%04x", r)
			continue
		}
		b.WriteRune(r)
	}
	_, err := io.WriteString(out, b.String())
	return err
}

// termLine makes untrusted text safe to print on a terminal: one line, bounded, with no
// control, escape or bidirectional formatting characters (intelapi.IsUnsafeRune).
func termLine(s string, max int) string {
	var b strings.Builder
	space := false
	for _, r := range s {
		if r == ' ' || intelapi.IsUnsafeRune(r) {
			space = b.Len() > 0
			continue
		}
		if space {
			b.WriteByte(' ')
			space = false
		}
		b.WriteRune(r)
	}
	out := []rune(b.String())
	if len(out) > max {
		return string(out[:max-1]) + "…"
	}
	return string(out)
}

func orDash(s string) string {
	if strings.TrimSpace(s) == "" {
		return "-"
	}
	return s
}

func sortedKeys[V any](m map[string]V) []string {
	keys := make([]string, 0, len(m))
	for k := range m {
		keys = append(keys, k)
	}
	sort.Strings(keys)
	return keys
}