@frontera-sdk/cli 1.52.27 → 1.52.29

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

@@ -0,0 +1,221 @@
+/**
+ * References between a project's files, by name instead of runtime id.
+ *
+ * An operating config names the Function a step calls by its id, a workflow
+ * names the Agent or Plugin a node runs by its id, and ids differ on every
+ * runtime. A project file writes `function/refund-eligibility` instead (the
+ * kind, a slash, the resource's name), and an instruction link writes
+ * `[[function:refund-eligibility]]`. Pulling from a workspace rewrites ids to
+ * names (`toNames`); applying to a runtime rewrites names to that runtime's ids
+ * (`toIds`). The rewrite walks the whole document, so a new field that holds
+ * a reference needs no change here.
+ *
+ * A value that is not a reference (a procedure's own id, a variable key) is
+ * left as it is: only a whole string of the form `kind/name`, or an id the
+ * directory knows, is rewritten.
+ */
+
+/**
+ * `object` is an object definition an Agent's object tools work on
+ * (`object/claim_ticket`), by slug; its fields travel in the Agent's file.
+ */
+export const REF_KINDS = ['function', 'workflow', 'agent', 'knowledge', 'plugin', 'objectType', 'action', 'model', 'skill', 'objectSet', 'object'] as const
+export type RefKind = (typeof REF_KINDS)[number]
+
+/** Names as resources are named: slugs, API names, install names. */
+const NAME = '[A-Za-z0-9][A-Za-z0-9._-]*'
+const REF = new RegExp(`^(${REF_KINDS.join('|')})/(${NAME})$`)
+/** `[[function:<id or name>]]` in guidance text, the platform's link form. */
+const LINK = new RegExp(`\\[\\[(${REF_KINDS.join('|')}):([^\\]\\s]+)\\]\\]`, 'g')
+/** `function:<id or name>` as a whole value: a procedure's tool list names its tools this way. */
+const PREFIXED = new RegExp(`^(${REF_KINDS.join('|')}):([^\\s:]+)$`)
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export function isUuid(value: string): boolean {
+  return UUID.test(value)
+}
+
+export function parseRef(value: string): { kind: RefKind; name: string } | null {
+  const m = REF.exec(value)
+  return m ? { kind: m[1] as RefKind, name: m[2]! } : null
+}
+
+export function formatRef(kind: RefKind, name: string): string {
+  return `${kind}/${name}`
+}
+
+/**
+ * The pulled item a reference needs: an object type, a governed Action and a
+ * saved object set are Blueprint items (`blueprint/object-types/Customer`,
+ * `blueprint/actions/resetLine`, `blueprint/object-sets/open-cases`),
+ * everything else its own ref.
+ */
+export function itemRef(kind: RefKind, name: string): string {
+  if (kind === 'objectType') return `blueprint/object-types/${name}`
+  if (kind === 'action') return `blueprint/actions/${name}`
+  if (kind === 'objectSet') return `blueprint/object-sets/${name}`
+  return formatRef(kind, name)
+}
+
+/**
+ * One runtime's resources: for each kind, name → id. Built from the runtime's
+ * own lists (`local-sync-directory.ts`), for the platform workspace when
+ * pulling and for the local runtime when applying.
+ */
+export type Directory = Partial<Record<RefKind, Map<string, string>>>
+
+/** The same directory the other way round: id → reference. */
+export function invert(directory: Directory): Map<string, { kind: RefKind; name: string }> {
+  const out = new Map<string, { kind: RefKind; name: string }>()
+  for (const kind of REF_KINDS) {
+    for (const [name, id] of directory[kind] ?? []) {
+      if (!out.has(id)) out.set(id, { kind, name })
+    }
+  }
+  return out
+}
+
+export interface Unresolved {
+  /** Where in the document: `procedures.0.steps.2.functionId`. */
+  path: string
+  /** The value that could not be rewritten: an id the directory does not know, or a name it does not have. */
+  value: string
+  kind?: RefKind
+  /** It is a `[[kind:name]]` link inside guidance text, not a whole value. */
+  link?: boolean
+}
+
+/** Keys whose value looks like `kind/name` but is a format, not a resource (`apiVersion: workflow/v1`). */
+const NOT_REFERENCES = new Set(['apiVersion', '$schema'])
+
+function walk(value: unknown, path: string[], visit: (s: string, path: string[]) => string): unknown {
+  if (typeof value === 'string') return NOT_REFERENCES.has(path[path.length - 1] ?? '') ? value : visit(value, path)
+  if (Array.isArray(value)) return value.map((v, i) => walk(v, [...path, String(i)], visit))
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, walk(v, [...path, k], visit)]))
+  }
+  return value
+}
+
+/** Keys whose value is another resource's id, where an unknown id is worth reporting. */
+const REFERENCE_KEY = /(^|[a-z])(Id|Ids|id|ids)$|^resourceId$|^ref$/
+
+/**
+ * Ids → `kind/name`, for a document read from a runtime. An id the directory
+ * does not know stays as it is and is reported when it sits where a reference
+ * would (`functionId`, `resourceId`, a list of `ids`): the pull plan shows it,
+ * and nothing writes a name that points nowhere.
+ */
+export function toNames<T>(doc: T, directory: Directory): { doc: T; unresolved: Unresolved[] } {
+  const byId = invert(directory)
+  const unresolved: Unresolved[] = []
+  const out = walk(doc, [], (s, path) => {
+    const known = byId.get(s)
+    if (known) return formatRef(known.kind, known.name)
+    const prefixed = PREFIXED.exec(s)
+    if (prefixed && isUuid(prefixed[2]!)) {
+      const named = byId.get(prefixed[2]!)
+      if (named) return `${prefixed[1]}:${named.name}`
+      unresolved.push({ path: path.join('.'), value: prefixed[2]!, kind: prefixed[1] as RefKind })
+      return s
+    }
+    if (isUuid(s)) {
+      const key = path.findLast((p) => !/^\d+$/.test(p)) ?? ''
+      if (REFERENCE_KEY.test(key)) unresolved.push({ path: path.join('.'), value: s })
+      return s
+    }
+    if (!s.includes('[[')) return s
+    return s.replace(LINK, (whole, kind: RefKind, target: string) => {
+      const named = byId.get(target)
+      if (named) return `[[${kind}:${named.name}]]`
+      if (isUuid(target)) unresolved.push({ path: path.join('.'), value: target, kind })
+      return whole
+    })
+  }) as T
+  return { doc: out, unresolved }
+}
+
+/**
+ * `kind/name` → ids, for a document about to be applied to a runtime. A name
+ * the runtime does not have is reported with where it is, and the document
+ * is not applied: a missing Function is a missing file, not a blank field.
+ * Ids already in the document pass through, so files written before names
+ * existed still apply.
+ */
+export function toIds<T>(doc: T, directory: Directory): { doc: T; unresolved: Unresolved[] } {
+  const unresolved: Unresolved[] = []
+  const out = walk(doc, [], (s, path) => {
+    const ref = parseRef(s)
+    if (ref) {
+      const id = directory[ref.kind]?.get(ref.name)
+      if (id) return id
+      unresolved.push({ path: path.join('.'), value: s, kind: ref.kind })
+      return s
+    }
+    const prefixed = PREFIXED.exec(s)
+    if (prefixed && !isUuid(prefixed[2]!) && directory[prefixed[1] as RefKind] !== undefined) {
+      const id = directory[prefixed[1] as RefKind]?.get(prefixed[2]!)
+      if (id) return `${prefixed[1]}:${id}`
+      unresolved.push({ path: path.join('.'), value: `${prefixed[1]}/${prefixed[2]}`, kind: prefixed[1] as RefKind })
+      return s
+    }
+    if (!s.includes('[[')) return s
+    return s.replace(LINK, (whole, kind: RefKind, target: string) => {
+      if (isUuid(target)) return whole
+      const id = directory[kind]?.get(target)
+      if (id) return `[[${kind}:${id}]]`
+      unresolved.push({ path: path.join('.'), value: `${kind}/${target}`, kind, link: true })
+      return whole
+    })
+  }) as T
+  return { doc: out, unresolved }
+}
+
+/** Every `kind/name` a document refers to, for listing what a pulled item needs. */
+export function referencesIn(doc: unknown): Array<{ kind: RefKind; name: string }> {
+  const seen = new Map<string, { kind: RefKind; name: string }>()
+  walk(doc, [], (s) => {
+    const ref = parseRef(s)
+    if (ref) seen.set(formatRef(ref.kind, ref.name), ref)
+    const prefixed = PREFIXED.exec(s)
+    if (prefixed && !isUuid(prefixed[2]!)) seen.set(formatRef(prefixed[1] as RefKind, prefixed[2]!), { kind: prefixed[1] as RefKind, name: prefixed[2]! })
+    for (const m of s.matchAll(LINK)) {
+      if (!isUuid(m[2]!)) seen.set(formatRef(m[1] as RefKind, m[2]!), { kind: m[1] as RefKind, name: m[2]! })
+    }
+    return s
+  })
+  return [...seen.values()]
+}
+
+/** Which kinds a document refers to by name, so a resolver lists only those. */
+export function kindsIn(doc: unknown): Set<RefKind> {
+  return new Set(referencesIn(doc).map((r) => r.kind))
+}
+
+/**
+ * The workflow nodes that run a governed Action still named by its platform id
+ * (`kind: action`, `resourceId: <uuid>`), branches included: a file pulled
+ * before Actions were named, or by a key that could not name them.
+ */
+export function governedActionIds(doc: unknown): Array<{ path: string; id: string }> {
+  const out: Array<{ path: string; id: string }> = []
+  const visit = (v: unknown, path: string[]) => {
+    if (Array.isArray(v)) return v.forEach((x, i) => visit(x, [...path, String(i)]))
+    if (!v || typeof v !== 'object') return
+    const o = v as Record<string, unknown>
+    if (o.kind === 'action' && typeof o.resourceId === 'string' && isUuid(o.resourceId)) out.push({ path: [...path, 'resourceId'].join('.'), id: o.resourceId })
+    for (const [k, x] of Object.entries(o)) visit(x, [...path, k])
+  }
+  visit(doc, [])
+  return out
+}
+
+/** One line per unresolved reference, for an error or a plan. */
+export function describeUnresolved(items: Unresolved[], file?: string): string[] {
+  return items.map((u) => {
+    const where = `${file ? `${file}: ` : ''}${u.path || '(document)'}`
+    if (u.kind === 'action' && !isUuid(u.value)) return `${where}: the governed Action ${parseRef(u.value)?.name ?? u.value} is not on this runtime`
+    if (u.kind === 'object' && !isUuid(u.value)) return `${where}: the object definition ${parseRef(u.value)?.name ?? u.value} is not on this runtime`
+    return u.kind && !isUuid(u.value) ? `${where}: ${u.value} is not on this runtime` : `${where}: ${u.value} could not be named (deleted, outside the workspace, or not readable with this key)`
+  })
+}