@frontera-sdk/cli 1.52.28 → 1.52.29

package/src/local/local-sync-merge.ts

@@ -0,0 +1,395 @@
+import { createHash } from 'node:crypto'
+
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+
+/**
+ * Three-way merge for a pull (§7 of the sync v2 design): the base (what the
+ * last pull wrote), ours (the project's files) and theirs (the workspace, as
+ * fetched). Pure: no files, no network; the caller reads and writes.
+ *
+ * Rules, the same in every kind:
+ *
+ * - **JSON and YAML** merge field by field. Object keys merge recursively; a
+ *   field one side changed takes that side; a field both sides changed the
+ *   same way takes it once; a field both changed differently is a conflict.
+ *   A field added on one side is kept; deleted on one side and untouched on
+ *   the other is deleted; deleted on one side and changed on the other is a
+ *   conflict.
+ * - **Arrays** merge as one value, except a list of objects that each carry a
+ *   stable key (`apiName`, `id`, `name`, `slug`, `filename`, `modeKey`,
+ *   `function`, `workflow`, `key`: the first one present as a unique string in
+ *   every element of all three versions). Such a list merges element by
+ *   element, matched by that key, with the object rules above. Its order is
+ *   ours, as the folder has it, unless only the workspace reordered the
+ *   elements all three share; what the other side added comes after.
+ * - **Multi-line strings** inside JSON or YAML (an Agent's prompts, a
+ *   procedure's instructions) and **every other file** (Markdown, code) merge
+ *   line by line, diff3-style: edits to different lines merge; the same lines
+ *   changed differently on both sides conflict, and so do edits to adjacent
+ *   lines with no unchanged line between them (as in git).
+ *
+ * A conflict never decides on its own: unless `choose` picks a side, the
+ * result keeps ours, and the conflict is reported with all three versions.
+ * Where both sides can stand together, as in a merge editor's Accept both,
+ * the conflict also says what taking both gives (`both`): for lines, ours
+ * then theirs; for a list, ours then what theirs adds, each element once. A
+ * single value (a name, a number, a whole file one side deleted) has no
+ * both.
+ */
+
+export type Side = 'ours' | 'theirs'
+
+/** What settles one conflict: a side, or both where the conflict offers it. */
+export type Choice = Side | 'both'
+
+export interface Conflict {
+  /** 1-based, in the order the merge meets conflicts: across an item's files when merged with `mergeItemFiles`. */
+  index: number
+  /** The field (`config.name`, `procedures[id=refund].instructions`); '' for a whole text file. */
+  path: string
+  /** The three versions of the field or the lines; `undefined` where a version does not have it. */
+  base: unknown
+  ours: unknown
+  theirs: unknown
+  /** For a line hunk: the 1-based line in our version where it starts. */
+  line?: number
+  /** What choosing both gives, where both can stand together: ours then theirs (lines), or the two lists joined without repeats. Absent for a single value. */
+  both?: unknown
+}
+
+export interface MergeOptions {
+  /** Pick a side for a conflict by its index, or both where it has `both`; `undefined` leaves it unresolved (ours is kept). */
+  choose?: (index: number) => Choice | undefined
+  /** The index the first conflict gets, minus one: so several files number on from each other. */
+  offset?: number
+}
+
+/** A key that is not there, as distinct from one holding `undefined` or `null`. */
+const ABSENT: unique symbol = Symbol('absent')
+type Value = unknown
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (Array.isArray(a)) return Array.isArray(b) && a.length === b.length && a.every((x, i) => deepEqual(x, b[i]))
+  if (isObject(a) && isObject(b)) {
+    const ka = Object.keys(a)
+    const kb = Object.keys(b)
+    return ka.length === kb.length && ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]))
+  }
+  return false
+}
+
+class Merger {
+  conflicts: Conflict[] = []
+  private n: number
+
+  constructor(private opts: MergeOptions) {
+    this.n = opts.offset ?? 0
+  }
+
+  /** Record a conflict and return what to take: the chosen side (or both, where it has both), or ours. */
+  conflict(c: Omit<Conflict, 'index'>): Choice {
+    const index = ++this.n
+    const { both, ...rest } = c
+    this.conflicts.push({ index, ...rest, base: shown(c.base), ours: shown(c.ours), theirs: shown(c.theirs), ...(both !== undefined ? { both } : {}) })
+    const choice = this.opts.choose?.(index) ?? 'ours'
+    if (choice === 'both' && both === undefined) throw new Error(`conflict ${index} is one value: keep mine or the workspace's`)
+    return choice
+  }
+
+  value(path: string, b: Value, o: Value, t: Value): Value {
+    if (deepEqual(o, t)) return o
+    if (deepEqual(b, o)) return t
+    if (deepEqual(b, t)) return o
+    if (isObject(o) && isObject(t)) return this.object(path, isObject(b) ? b : null, o, t)
+    if (Array.isArray(o) && Array.isArray(t)) return this.array(path, Array.isArray(b) ? b : null, o, t)
+    if (typeof o === 'string' && typeof t === 'string' && [b, o, t].some((s) => typeof s === 'string' && s.includes('\n'))) {
+      return this.lines(path, typeof b === 'string' ? b : '', o, t)
+    }
+    return this.conflict({ path, base: b, ours: o, theirs: t }) === 'ours' ? o : t
+  }
+
+  object(path: string, b: Record<string, unknown> | null, o: Record<string, unknown>, t: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {}
+    // Our order first, so the merged file reads like the one in the folder; then what only the workspace has.
+    const keys = [...Object.keys(o), ...Object.keys(t).filter((k) => !(k in o)), ...Object.keys(b ?? {}).filter((k) => !(k in o) && !(k in t))]
+    for (const k of keys) {
+      const at = (x: Record<string, unknown> | null) => (x && Object.prototype.hasOwnProperty.call(x, k) ? x[k] : ABSENT)
+      const v = this.value(path ? `${path}.${k}` : k, at(b), at(o), at(t))
+      if (v !== ABSENT) out[k] = v
+    }
+    return out
+  }
+
+  array(path: string, b: unknown[] | null, o: unknown[], t: unknown[]): unknown {
+    const key = stableKey([...(b ? [b] : []), o, t])
+    if (!key) {
+      const both = union(o, t)
+      const choice = this.conflict({ path, base: b ?? ABSENT, ours: o, theirs: t, both })
+      return choice === 'both' ? both : choice === 'ours' ? o : t
+    }
+    const index = (list: unknown[] | null) => new Map((list ?? []).map((x) => [(x as Record<string, string>)[key]!, x]))
+    const bm = index(b)
+    const om = index(o)
+    const tm = index(t)
+    const order = (m: Map<string, unknown>, among: Map<string, unknown>[]) => [...m.keys()].filter((k) => among.every((x) => x.has(k)))
+    const shared = (m: Map<string, unknown>) => order(m, [bm, om, tm]).join('\0')
+    // Our order, as the folder has it, unless only the workspace reordered what all three share.
+    const theirsFirst = shared(tm) !== shared(bm) && shared(om) === shared(bm)
+    const [first, second] = theirsFirst ? [tm, om] : [om, tm]
+    const keys = [...first.keys(), ...[...second.keys()].filter((k) => !first.has(k)), ...[...bm.keys()].filter((k) => !om.has(k) && !tm.has(k))]
+    const out: unknown[] = []
+    for (const k of keys) {
+      const at = (m: Map<string, unknown>) => (m.has(k) ? m.get(k) : ABSENT)
+      const v = this.value(`${path}[${key}=${k}]`, at(bm), at(om), at(tm))
+      if (v !== ABSENT) out.push(v)
+    }
+    return out
+  }
+
+  lines(path: string, base: string, ours: string, theirs: string): string {
+    const result = diff3(base.split('\n'), ours.split('\n'), theirs.split('\n'))
+    const out: string[] = []
+    for (const chunk of result) {
+      if (chunk.kind === 'ok') {
+        out.push(...chunk.lines)
+        continue
+      }
+      const both = [...chunk.ours, ...chunk.theirs]
+      const choice = this.conflict({ path, base: chunk.base.join('\n'), ours: chunk.ours.join('\n'), theirs: chunk.theirs.join('\n'), line: chunk.oursLine, both: both.join('\n') })
+      out.push(...(choice === 'both' ? both : choice === 'ours' ? chunk.ours : chunk.theirs))
+    }
+    return out.join('\n')
+  }
+}
+
+/** Two lists as one: ours in its order, then what only theirs has, each element once. */
+function union(ours: unknown[], theirs: unknown[]): unknown[] {
+  const out: unknown[] = []
+  for (const x of [...ours, ...theirs]) if (!out.some((y) => deepEqual(x, y))) out.push(x)
+  return out
+}
+
+/** A conflict's version as a reader sees it: `undefined` where it is absent. */
+function shown(v: unknown): unknown {
+  return v === ABSENT ? undefined : v
+}
+
+const KEY_FIELDS = ['apiName', 'id', 'name', 'slug', 'filename', 'modeKey', 'function', 'workflow', 'objectType', 'key']
+
+/** The field every element of every list carries as a unique string, if there is one. */
+export function stableKey(lists: unknown[][]): string | null {
+  if (!lists.some((l) => l.length)) return null
+  for (const key of KEY_FIELDS) {
+    const ok = lists.every((list) => {
+      const seen = new Set<string>()
+      for (const x of list) {
+        if (!isObject(x) || typeof x[key] !== 'string' || seen.has(x[key] as string)) return false
+        seen.add(x[key] as string)
+      }
+      return true
+    })
+    if (ok) return key
+  }
+  return null
+}
+
+/**
+ * Field-by-field merge of two documents from their base. `base` is
+ * `undefined` when there is none (an item pulled before base content was
+ * kept): then only what both sides agree on, or only one side has, merges.
+ */
+export function mergeJson(base: unknown, ours: unknown, theirs: unknown, opts: MergeOptions = {}): { merged: unknown; conflicts: Conflict[] } {
+  const m = new Merger(opts)
+  const merged = m.value('', base === undefined ? ABSENT : base, ours, theirs)
+  return { merged: merged === ABSENT ? undefined : merged, conflicts: m.conflicts }
+}
+
+/** Line-by-line merge of three texts, diff3-style. */
+export function mergeLines(base: string, ours: string, theirs: string, opts: MergeOptions = {}): { merged: string; conflicts: Conflict[] } {
+  const m = new Merger(opts)
+  const merged = ours === theirs ? ours : base === ours ? theirs : base === theirs ? ours : m.lines('', base, ours, theirs)
+  return { merged, conflicts: m.conflicts }
+}
+
+// ── diff3 ────────────────────────────────────────────────────────────────────
+
+type Chunk = { kind: 'ok'; lines: string[] } | { kind: 'conflict'; base: string[]; ours: string[]; theirs: string[]; oursLine: number }
+
+/** Past this many table cells, the middle of two texts is compared as one block instead of line by line. */
+const LCS_LIMIT = 4_000_000
+
+/** For each line of `a`, the line of `b` a longest common subsequence pairs it with, or -1. */
+function matchLines(a: string[], b: string[]): Int32Array {
+  const out = new Int32Array(a.length).fill(-1)
+  let start = 0
+  while (start < a.length && start < b.length && a[start] === b[start]) {
+    out[start] = start
+    start++
+  }
+  let endA = a.length
+  let endB = b.length
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA--
+    endB--
+    out[endA] = endB
+  }
+  const n = endA - start
+  const m = endB - start
+  if (!n || !m || n * m > LCS_LIMIT) return out
+  const table: Uint32Array[] = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1))
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) table[i]![j] = a[start + i] === b[start + j] ? table[i + 1]![j + 1]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!)
+  }
+  let i = 0
+  let j = 0
+  while (i < n && j < m) {
+    if (a[start + i] === b[start + j]) {
+      out[start + i] = start + j
+      i++
+      j++
+    } else if (table[i + 1]![j]! >= table[i]![j + 1]!) i++
+    else j++
+  }
+  return out
+}
+
+const same = (x: string[], y: string[]) => x.length === y.length && x.every((l, i) => l === y[i])
+
+/**
+ * Walk the base with both sides: a base line both sides kept is stable; the
+ * lines between two stable points changed on one side (take it), on both the
+ * same way (take it once), or on both differently (a conflict).
+ */
+export function diff3(base: string[], ours: string[], theirs: string[]): Chunk[] {
+  const mo = matchLines(base, ours)
+  const mt = matchLines(base, theirs)
+  const out: Chunk[] = []
+  const ok = (lines: string[]) => {
+    if (!lines.length) return
+    const last = out[out.length - 1]
+    if (last?.kind === 'ok') last.lines.push(...lines)
+    else out.push({ kind: 'ok', lines: [...lines] })
+  }
+  let i = 0
+  let a = 0
+  let b = 0
+  while (i < base.length || a < ours.length || b < theirs.length) {
+    if (i < base.length && mo[i] === a && mt[i] === b) {
+      ok([base[i]!])
+      i++
+      a++
+      b++
+      continue
+    }
+    // The next base line both sides kept, at or after this one.
+    let j = i
+    while (j < base.length && !(mo[j]! >= a && mt[j]! >= b)) j++
+    const oa = j < base.length ? mo[j]! : ours.length
+    const ob = j < base.length ? mt[j]! : theirs.length
+    const bs = base.slice(i, j)
+    const os = ours.slice(a, oa)
+    const ts = theirs.slice(b, ob)
+    if (same(os, bs)) ok(ts)
+    else if (same(ts, bs) || same(os, ts)) ok(os)
+    else out.push({ kind: 'conflict', base: bs, ours: os, theirs: ts, oursLine: a + 1 })
+    i = j
+    a = oa
+    b = ob
+  }
+  return out
+}
+
+// ── Files ────────────────────────────────────────────────────────────────────
+
+export interface FileMerge {
+  path: string
+  /** The merged content to write, or null for no file. Where a conflict is left unresolved, ours. */
+  merged: string | null
+  conflicts: Conflict[]
+}
+
+type Format = 'json' | 'yaml' | 'text'
+
+function formatOf(path: string): Format {
+  if (/\.json$/i.test(path)) return 'json'
+  if (/\.ya?ml$/i.test(path)) return 'yaml'
+  return 'text'
+}
+
+function parse(format: Format, text: string): { ok: true; value: unknown } | { ok: false } {
+  try {
+    return { ok: true, value: format === 'json' ? JSON.parse(text) : parseYaml(text) }
+  } catch {
+    return { ok: false }
+  }
+}
+
+/** A document as a pull writes it: two-space JSON with a final newline, YAML without wrapping. */
+function render(format: Format, value: unknown): string {
+  return format === 'json' ? `${JSON.stringify(value, null, 2)}\n` : stringifyYaml(value, { lineWidth: 0 })
+}
+
+/**
+ * One file's merge, by its kind: JSON and YAML field by field (falling back
+ * to lines when a version does not parse), anything else by line. A file one
+ * side deleted and the other changed is a conflict over the whole file.
+ */
+export function mergeFile(path: string, base: string | null, ours: string | null, theirs: string | null, opts: MergeOptions = {}): FileMerge {
+  if (ours === theirs) return { path, merged: ours, conflicts: [] }
+  if (base === ours) return { path, merged: theirs, conflicts: [] }
+  if (base === theirs) return { path, merged: ours, conflicts: [] }
+  if (ours === null || theirs === null) {
+    const m = new Merger(opts)
+    const side = m.conflict({ path: '', base: base ?? undefined, ours: ours ?? undefined, theirs: theirs ?? undefined })
+    return { path, merged: side === 'ours' ? ours : theirs, conflicts: m.conflicts }
+  }
+  const format = formatOf(path)
+  if (format !== 'text') {
+    const o = parse(format, ours)
+    const t = parse(format, theirs)
+    const b = base === null ? ({ ok: true, value: undefined } as const) : parse(format, base)
+    if (o.ok && t.ok && b.ok) {
+      const { merged, conflicts } = mergeJson(b.value, o.value, t.value, opts)
+      // Keep a side's text as it is when the merge is that side: formatting and comments survive.
+      const text = deepEqual(merged, o.value) ? ours : deepEqual(merged, t.value) ? theirs : render(format, merged)
+      return { path, merged: text, conflicts }
+    }
+  }
+  const { merged, conflicts } = mergeLines(base ?? '', ours, theirs, opts)
+  return { path, merged, conflicts }
+}
+
+/**
+ * Every file of one item: the paths any of the three versions has, in order,
+ * conflicts numbered across them so a choice by index names one conflict.
+ */
+export function mergeItemFiles(
+  base: Record<string, string | null>,
+  ours: Record<string, string | null>,
+  theirs: Record<string, string | null>,
+  opts: Omit<MergeOptions, 'offset'> = {},
+): { files: FileMerge[]; conflicts: number } {
+  const paths = [...new Set([...Object.keys(base), ...Object.keys(ours), ...Object.keys(theirs)])].sort()
+  const files: FileMerge[] = []
+  let offset = 0
+  for (const path of paths) {
+    const f = mergeFile(path, base[path] ?? null, ours[path] ?? null, theirs[path] ?? null, { ...opts, offset })
+    offset += f.conflicts.length
+    files.push(f)
+  }
+  return { files, conflicts: offset }
+}
+
+/**
+ * An item's numbered conflicts as one value: where each is and what each
+ * side holds. A choice made by number (`--picks 1=workspace`) applies only
+ * while it is the same; a workspace change that moves or renumbers the
+ * conflicts changes it, and stale picks are refused.
+ */
+export function conflictsId(files: FileMerge[]): string {
+  const list = files.flatMap((f) => f.conflicts.map((c) => [f.path, c.index, c.path, c.line ?? null, c.base ?? null, c.ours ?? null, c.theirs ?? null]))
+  return createHash('sha256').update(JSON.stringify(list)).digest('hex').slice(0, 16)
+}

package/src/local/local-sync-names.ts

@@ -0,0 +1,169 @@
+/**
+ * One name for each synced item everywhere it is said: the CLI's status,
+ * preview and pull lines, Forge's Pull and Propose dialogs, the change
+ * request's rows and steps. An item is called by its display name (the
+ * Agent's own name, the Blueprint file's display name, a skill's display
+ * name), else its slug made readable, and a sentence puts its kind first:
+ * "Action Notify the customer", "Skill Brand".
+ */
+
+const KIND_WORD: Record<string, string> = {
+  agent: 'Agent',
+  workflow: 'Workflow',
+  function: 'Function',
+  skill: 'Skill',
+  knowledge: 'Knowledge base',
+  plugin: 'Plugin',
+  evaluation: 'Evaluation dataset',
+  dataset: 'Dataset',
+  theme: 'Slide theme',
+  'chat-app': 'Chat App',
+  app: 'App',
+  brand: 'Brand',
+  library: 'Library installation',
+  lessons: 'Lessons for Agent',
+}
+
+const BLUEPRINT_WORD: Record<string, string> = {
+  'object-types': 'Object type',
+  'link-types': 'Link type',
+  'shared-fields': 'Shared field',
+  'semantic-types': 'Semantic type',
+  metrics: 'Metric',
+  actions: 'Action',
+  'object-sets': 'Saved object set',
+}
+
+/** `word-count` → "Word count". */
+export function readableName(slug: string): string {
+  const words = slug.replace(/[-_]+/g, ' ').trim()
+  return words ? words[0]!.toUpperCase() + words.slice(1) : slug
+}
+
+/** The kind of the item a reference names, in a word: `blueprint/actions/x` is an Action. */
+export function kindWord(ref: string): string {
+  const [kind, sub] = ref.split('/')
+  if (kind === 'blueprint') return BLUEPRINT_WORD[sub ?? ''] ?? 'Blueprint'
+  return KIND_WORD[kind ?? ''] ?? readableName(kind ?? 'item')
+}
+
+/** An item as a sentence names it: its kind, then its name. A name that already says its kind ("Organization brand") stands alone. */
+export function kindTitle(ref: string, title: string): string {
+  const word = kindWord(ref)
+  return title.toLowerCase().includes(word.toLowerCase()) ? title : `${word} ${title}`
+}
+
+/** A display name from a document's `displayName` or `name`, when it has one. */
+function declared(doc: unknown, ...keys: string[]): string | null {
+  if (!doc || typeof doc !== 'object') return null
+  for (const k of keys) {
+    const v = (doc as Record<string, unknown>)[k]
+    if (typeof v === 'string' && v.trim()) return v.trim()
+  }
+  return null
+}
+
+function parseJson(text: string | undefined): unknown {
+  if (!text) return null
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+/** `displayName:` or `name:` at the top level of YAML (a Blueprint file, a workflow) or in a Markdown file's front matter. */
+function yamlField(text: string | undefined, key: string): string | null {
+  if (!text) return null
+  const m = text.match(new RegExp(`^${key}:\\s*(.+?)\\s*$`, 'm'))
+  if (!m) return null
+  const raw = m[1]!.replace(/^(['"])(.*)\1$/, '$2').trim()
+  return raw && !raw.startsWith('{') && !raw.startsWith('[') ? raw : null
+}
+
+/**
+ * Whether a title someone kept is only a slug form, not a name: empty, the
+ * item's slug or reference, a Blueprint file's apiName, or the "apiName
+ * (kind)" a snapshot gave Blueprint files before they were named by display
+ * name. A change request proposed before items were named this way keeps
+ * such titles; whoever shows it names the item afresh instead.
+ */
+export function isSlugTitle(ref: string, title: string | null | undefined): boolean {
+  const t = title?.trim()
+  if (!t) return true
+  const [kind, ...rest] = ref.split('/')
+  const name = rest.join('/')
+  if (t === ref || t === name) return true
+  if (kind !== 'blueprint') return false
+  return t === rest[1] || / \((semantic type|shared field|object type|link type|metric|action|saved object set|blueprint)\)$/i.test(t)
+}
+
+/**
+ * The files `itemTitle` reads a name from, by project path: a caller that
+ * holds only the reference (a kept change request) reads these from the
+ * project. A kind named from its slug alone has none.
+ */
+export function namingPaths(kind: string, name: string): string[] {
+  if (kind === 'agent') return [`agents/${name}/agent.json`]
+  if (kind === 'blueprint') {
+    const [dir, apiName] = name.split('/')
+    return ['yaml', 'yml', 'json'].map((ext) => `blueprint/${dir}/${apiName}.${ext}`)
+  }
+  if (kind === 'skill') return [`skills/${name}/SKILL.md`]
+  if (kind === 'workflow') return [`workflows/${name}.yaml`, `workflows/${name}.yml`]
+  if (kind === 'chat-app') return [`chat-apps/${name}.json`]
+  if (kind === 'app') return [`apps/${name}.json`]
+  if (kind === 'knowledge') return [`knowledge/${name}/knowledge.json`]
+  return []
+}
+
+/**
+ * An item's name as people know it: the name the workspace gave it
+ * (`known`), else what its files declare, else its slug made readable.
+ * `files` are the item's files by project path, as the project or the
+ * workspace holds them. A `known` that is only a slug form (`isSlugTitle`)
+ * gives way to the files.
+ */
+export function itemTitle(kind: string, name: string, files: Record<string, string>, known?: string | null): string {
+  if (known && !isSlugTitle(`${kind}/${name}`, known)) return known.trim()
+  if (kind === 'agent') {
+    const doc = parseJson(files[`agents/${name}/agent.json`]) as { config?: unknown; name?: unknown } | null
+    const own = declared(doc?.config, 'name') ?? declared(doc, 'name')
+    if (own) return own
+  }
+  if (kind === 'blueprint') {
+    const [dir, apiName] = name.split('/')
+    const file = Object.entries(files).find(([p]) => p.startsWith(`blueprint/${dir}/${apiName}.`))?.[1]
+    const own = yamlField(file, 'displayName') ?? declared(parseJson(file), 'displayName')
+    return own ?? (dir === 'object-sets' ? readableName(apiName ?? name) : (apiName ?? name))
+  }
+  if (kind === 'skill') {
+    const own = yamlField(files[`skills/${name}/SKILL.md`], 'displayName')
+    if (own) return own
+  }
+  if (kind === 'workflow') {
+    const file = files[`workflows/${name}.yaml`] ?? files[`workflows/${name}.yml`]
+    const own = yamlField(file, 'displayName')
+    if (own) return own
+  }
+  if (kind === 'chat-app' || kind === 'app') {
+    const file = Object.entries(files).find(([p]) => p.endsWith('.json'))?.[1]
+    const own = declared(parseJson(file), 'displayName', 'name')
+    if (own) return own
+  }
+  if (kind === 'knowledge') {
+    const own = declared(parseJson(files[`knowledge/${name}/knowledge.json`]), 'displayName', 'name')
+    if (own) return own
+  }
+  // An Agent's lessons are named by their Agent: "Lessons for Agent Claims desk".
+  if (kind === 'lessons') {
+    const own = declared((parseJson(files[`agents/${name}/agent.json`]) as { config?: unknown } | null)?.config, 'name')
+    return own ?? readableName(name)
+  }
+  if (kind === 'evaluation') {
+    // As a pull names it: the dataset, then the Agent its cases test.
+    const [agent, dataset] = name.split('.')
+    return `${readableName(dataset ?? name)} → ${agent}`
+  }
+  return readableName(name)
+}