@voxgig/sdkgen 4.8.3 → 4.10.0

package/project/.sdk/tm/scala/feature/secrets/plugin/Env.scala

@@ -0,0 +1,144 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Env.scala)
+// Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package voxgig.plugin
+
+import scala.collection.mutable
+
+/** Environment overrides (section 9.5) - level 7 of the ladder.
+  *
+  * One prefix, so nothing drifts: `VOXGIG_PLUGIN_*`.
+  *
+  *   VOXGIG_PLUGIN_PROFILE            the profile name
+  *   VOXGIG_PLUGIN_<REF>_<PATH>       one option
+  *   VOXGIG_PLUGIN_ACTIVE/INACTIVE    comma-separated refs, INACTIVE wins
+  *
+  * THE ENCODING IS LOSSY, AND THIS SAYS SO RATHER THAN PRETENDING OTHERWISE.
+  * Ref and path are upper-snake with `$` -> `__` and `.` -> `_`. But `_` is
+  * legal in a name and in a tag, and the mapping folds case, so `retry$fast`
+  * and `retry__fast` both encode to `RETRY__FAST`.
+  *
+  * Rather than restrict a grammar the rest of the stack already uses, the host
+  * DETECTS THE COLLISION: it encodes every ref it holds, and a key two refs
+  * claim is `plugin_env_ambiguous`, naming both.
+  */
+object Env {
+
+  private val prefix = "VOXGIG_PLUGIN_"
+
+  /** `retry$fast` -> `RETRY__FAST`. */
+  def encodeRef(ref: String): String =
+    ref.replace("$", "__").replace(".", "_").toUpperCase
+
+  /** Values parse as JSON, FALLING BACK TO STRING - so `8080` is a number,
+    * `true` is a boolean, `{"a":1}` is a map, and `hello` is the string it
+    * looks like rather than a parse error.
+    */
+  private def parseValue(value: Value): Value = value.asString match {
+    case None => value
+    case Some(s) =>
+      try Json.parse(s)
+      catch { case _: Exception => value }
+  }
+
+  private def split(value: Value): List[String] =
+    value.asString.getOrElse(value.json).split(",", -1)
+      .map(_.trim).filter(_.nonEmpty).toList
+
+  private def checkReserved(ref: String, reserved: Value): Unit = {
+    if (reserved.items.contains(VStr(Refs.refName(VStr(ref))))) {
+      Types.fail(
+        "plugin_ref_reserved", "ref is reserved by the host: " + ref,
+        Map("ref" -> VStr(ref))
+      )
+    }
+  }
+
+  def applyEnv(input: Value): Value = {
+    val env = input.at("env")
+    val refs = input.at("refs").items.map(Refs.canonRef)
+    val reserved = input.at("reserved")
+
+    var options = Map.empty[String, Value]
+    val active = mutable.ListBuffer[Value]()
+    val inactive = mutable.ListBuffer[Value]()
+    var profile: Option[Value] = None
+
+    // Encode every ref the host holds, and refuse a key that two of them claim.
+    // Done up front so the collision is reported even when no environment
+    // variable exercises it - a latent ambiguity is still an ambiguity, and
+    // finding it at deploy time is the failure this exists to prevent.
+    val byencoded = mutable.LinkedHashMap[String, mutable.ListBuffer[String]]()
+    refs.foreach(ref =>
+      byencoded.getOrElseUpdate(encodeRef(ref), mutable.ListBuffer.empty) += ref
+    )
+    byencoded.keys.toList.sorted.foreach { e =>
+      if (byencoded(e).length > 1) {
+        val pair = byencoded(e).toList.sorted
+        Types.fail(
+          "plugin_env_ambiguous",
+          "refs collide in the environment encoding as " + e + ": " + pair.mkString(", "),
+          Map("encoded" -> VStr(e), "refs" -> VList(pair.map(VStr.apply)))
+        )
+      }
+    }
+
+    // Longest encoded ref first, so `retry$fast` wins over `retry` on
+    // `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+    val encoded = Types.stableSortBy(byencoded.keys.toList.sorted)(e =>
+      List(KNum(-e.length))
+    )
+
+    env.keys.foreach { key =>
+      if (key.startsWith(prefix)) {
+        val rest = key.substring(prefix.length)
+
+        if (rest == "PROFILE") {
+          profile = Some(env.at(key))
+        } else if (rest == "ACTIVE" || rest == "INACTIVE") {
+          split(env.at(key)).foreach { raw =>
+            val ref = Refs.canonRef(VStr(raw))
+            // The reservation covers EVERY input layer (section 9.1).
+            // VOXGIG_PLUGIN_INACTIVE=station is easier to set than editing a
+            // config file, and INACTIVE has the final word - so guarding
+            // documents alone would leave the one lever this mechanism exists
+            // to deny wide open.
+            checkReserved(ref, reserved)
+            if (rest == "ACTIVE") active += VStr(ref) else inactive += VStr(ref)
+          }
+        } else {
+          encoded.find(e => rest == e || rest.startsWith(e + "_")) match {
+            // Not for any ref this host holds.
+            case None => ()
+            case Some(enc) =>
+              val ref = byencoded(enc).head
+              checkReserved(ref, reserved)
+              // A ref with no path sets nothing.
+              if (rest != enc) {
+                val path = rest.substring(enc.length + 1).toLowerCase.split("_", -1).toList
+                options = options + (ref ->
+                  write(options.getOrElse(ref, VMap(Map.empty)), path, parseValue(env.at(key))))
+              }
+          }
+        }
+      }
+    }
+
+    val out = Map[String, Value](
+      "options" -> VMap(options),
+      "active" -> VList(active.toList),
+      "inactive" -> VList(inactive.toList)
+    )
+    VMap(profile.map(p => out + ("profile" -> p)).getOrElse(out))
+  }
+
+  /** Write one option at a dotted path, creating maps as it goes. A step whose
+    * current value is not a map is REPLACED, because a scalar written by a
+    * shallower variable cannot also be a container.
+    */
+  private def write(node: Value, path: List[String], value: Value): Value = {
+    val base = if (node.isMap) node else VMap(Map.empty)
+    if (path.length == 1) base.setting(path.head, value)
+    else base.setting(path.head, write(base.at(path.head), path.tail, value))
+  }
+}

package/project/.sdk/tm/scala/feature/secrets/plugin/Export.scala

@@ -0,0 +1,59 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Export.scala)
+// Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package voxgig.plugin
+
+/** Exports (section 11).
+  *
+  * An instance publishes values for other plugins and for the application. Read
+  * with `host.exports("retry$fast/client")`.
+  *
+  * THE UNQUALIFIED ALIAS IS THE INTERESTING PART. `retry/client` resolves to
+  * the UNTAGGED instance if one exists; if not, and exactly one tagged instance
+  * exports that key, it resolves to that one; if two do, it is
+  * `plugin_export_ambiguous` - deliberately diverging from seneca's silent
+  * last-wins, because with multi-instance as a headline feature an ambiguous
+  * alias is a defect waiting for production.
+  */
+object Export {
+
+  /** One published value. An internal shape, never a corpus value. */
+  final case class Exported(ref: String, key: String, value: Value)
+
+  def resolveExport(spec: String, exported: List[Exported]): Value = {
+    val cut = spec.indexOf('/')
+    if (cut < 0) {
+      Types.fail(
+        "plugin_export_ambiguous", "export spec needs a key: " + spec,
+        Map("spec" -> VStr(spec))
+      )
+    }
+    val head = spec.substring(0, cut)
+    val key = spec.substring(cut + 1)
+
+    // A fully qualified ref: exactly one answer or none.
+    val want = Refs.canon(VStr(head))
+    exported.find(e => e.ref == want && e.key == key) match {
+      case Some(e) => e.value
+      case None =>
+        // An alias: the name, not a ref. Look at every instance of it.
+        val byname = exported.filter(e => Refs.refName(VStr(e.ref)) == head && e.key == key)
+        if (byname.isEmpty) {
+          VNull
+        } else {
+          byname.find(e => Refs.parseRef(VStr(e.ref)).at("tag") == VStr("")) match {
+            case Some(e)                    => e.value
+            case None if byname.length == 1 => byname.head.value
+            case None =>
+              val refs = byname.map(_.ref).sorted
+              Types.fail(
+                "plugin_export_ambiguous",
+                "alias " + spec + " matches " + refs.length + " instances: " +
+                  refs.mkString(", "),
+                Map("spec" -> VStr(spec), "refs" -> VList(refs.map(VStr.apply)))
+              )
+          }
+        }
+    }
+  }
+}

package/project/.sdk/tm/scala/feature/secrets/plugin/Graph.scala

@@ -0,0 +1,149 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (scala/src/Graph.scala)
+// Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package voxgig.plugin
+
+/** Whole-graph resolution (section 11.4) - a phase, not a discovery.
+  *
+  * "Activate, and wait in `pending` if you must" is correct and, on its own,
+  * produces a terrible experience: apply twenty instances against a registry
+  * missing one thing and you get NINETEEN pending rows and no statement of what
+  * is actually wrong.
+  *
+  * `resolveGraph` is a PURE FUNCTION of the registry and the intended
+  * activation set. No callbacks run, no state changes, nothing is touched. It
+  * answers for the whole graph at once which instances can be live, and for
+  * each blocked one THE SPECIFIC REQUIREMENT that is unmet, and why.
+  *
+  * The failure mode being designed against is a famous one: OSGi's resolver is
+  * correct and its diagnostics are legendarily unusable. A resolver that says
+  * "blocked" without saying WHY has moved the problem rather than solved it, so
+  * `why` is part of the contract and the corpus pins its shape.
+  */
+object Graph {
+
+  def resolveGraph(nodes: Value): Value = {
+    val list = nodes.items
+    val byref = list.map(n => n.at("ref").asString.getOrElse("") -> n).toMap
+
+    // Fixed point: a node resolves when every mandatory requirement is met by
+    // an ALREADY-RESOLVED provider. Iterating to a fixed point is what makes a
+    // provider that is itself blocked propagate, rather than each node being
+    // judged against the raw registry.
+    def settle(resolved: Set[String]): Set[String] = {
+      val next = list.foldLeft(resolved) { (acc, n) =>
+        val ref = n.at("ref").asString.getOrElse("")
+        if (acc.contains(ref) || firstUnmet(n, byref, acc).isDefined) acc else acc + ref
+      }
+      if (next.size == resolved.size) resolved else settle(next)
+    }
+    val resolved = settle(Set.empty)
+
+    val blocked = list
+      .filterNot(n => resolved.contains(n.at("ref").asString.getOrElse("")))
+      .flatMap(n => firstUnmet(n, byref, resolved).map(w => n.at("ref").asString.getOrElse("") -> w))
+      .sortBy(_._1)
+      .map(_._2)
+
+    Value.map(
+      "resolved" -> VList(resolved.toList.sorted.map(VStr.apply)),
+      "blocked" -> VList(blocked)
+    )
+  }
+
+  /** The FIRST unmet requirement, with the most specific explanation available.
+    * Order matters: "no provider at all" and "a provider at the wrong version"
+    * are different problems and a reader must not have to guess which they
+    * have.
+    */
+  def firstUnmet(node: Value, byref: Map[String, Value], resolved: Set[String])
+      : Option[Value] =
+    node.at("requires").items
+      .filterNot(_.at("optional").truthy)
+      .flatMap(req => unmet(node, req, byref, resolved))
+      .headOption
+
+  private def unmet(
+      node: Value, req: Value, byref: Map[String, Value], resolved: Set[String]
+  ): Option[Value] = {
+    val name = req.at("name").asString.getOrElse("")
+    val all = graphCandidates(byref, name)
+    if (all.isEmpty) return Some(why(node, name, Value.map("kind" -> VStr("absent"))))
+
+    val ok = Capability.resolveCapability(req, VList(all))
+    if (ok.nonEmpty) {
+      // A provider exists and matches - but if none of them is itself resolved,
+      // this node is blocked BEHIND it, and the chain is the useful answer
+      // rather than "unmet".
+      if (ok.exists(c => resolved.contains(c.at("ref").asString.getOrElse("")))) {
+        return None
+      }
+      val chain = ok.map(_.at("ref").asString.getOrElse("")).sorted
+      return Some(why(node, name, Value.map(
+        "kind" -> VStr("blocked"), "chain" -> VList(chain.map(VStr.apply))
+      )))
+    }
+
+    // Providers exist and none matched. Say which test failed.
+    val range = req.at("range")
+    if (!range.isNull) {
+      val versions = all.map(_.at("provides").at("version"))
+        .filter(v => v.isNull || !Version.satisfiesq(v, range))
+        .map(v => v.asString.getOrElse("(none)"))
+      if (versions.nonEmpty) {
+        return Some(why(node, name, Value.map(
+          "kind" -> VStr("version"), "range" -> range,
+          "found" -> VList(versions.sorted.map(VStr.apply))
+        )))
+      }
+    }
+
+    val matchSpec = req.at("match")
+    if (!matchSpec.isNull) {
+      val bad = all.flatMap { c =>
+        val attrs = c.at("provides").at("attrs")
+        matchSpec.keys
+          .filterNot(k => attrs.has(k) && Capability.matchValue(matchSpec.at(k), attrs.at(k)))
+          .map(k => why(node, name, Value.map(
+            "kind" -> VStr("match"), "failing" -> VStr(k),
+            "want" -> matchSpec.at(k), "found" -> attrs.at(k)
+          )))
+      }
+      if (bad.nonEmpty) return Some(bad.head)
+    }
+
+    Some(why(node, name, Value.map("kind" -> VStr("absent"))))
+  }
+
+  private def why(node: Value, name: String, reason: Value): Value =
+    Value.map("ref" -> node.at("ref"), "unmet" -> VStr(name), "why" -> reason)
+
+  // A NODE SATISFIES ITS OWN REF (section 11.1), and the graph learned it
+  // here. Considering only declared capabilities made `resolve` answer
+  // `absent` about a provider sitting right there and live - section
+  // 11.4's job is explaining the graph the runtime reconciles, and it was
+  // explaining a different one. The ref match WINS OUTRIGHT for that node,
+  // as at runtime: one candidate, not two, for a node both named `b` and
+  // providing `b`.
+  def graphCandidates(byref: Map[String, Value], name: String): List[Value] = {
+    val asref = Refs.canon(VStr(name))
+    byref.keys.toList.sorted.flatMap { ref =>
+      val node = byref(ref)
+      if (ref == asref) {
+        List(Value.map(
+          "ref" -> node.at("ref"),
+          "pos" -> node.get("pos").getOrElse(VNum(0)),
+          "provides" -> Value.map("name" -> VStr(name))
+        ))
+      } else {
+        node.at("provides").items
+          .filter(_.at("name").asString.contains(name))
+          .map(prov => Value.map(
+            "ref" -> node.at("ref"),
+            "pos" -> node.get("pos").getOrElse(VNum(0)),
+            "provides" -> prov
+          ))
+      }
+    }
+  }
+}