@voxgig/sdkgen 4.10.0 → 4.11.0

package/project/.sdk/tm/zig/feature/secrets/plugin/ref.zig

@@ -0,0 +1,147 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (zig/src/ref.zig)
+// 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.
+//! Identity: name+tag, written `name$tag` (§4).
+//!
+//! The four pure functions, and the whole of what `ref` pins. They are
+//! the first thing a new port implements and the first corpus section
+//! it passes.
+
+const std = @import("std");
+const v = @import("value.zig");
+const t = @import("types.zig");
+
+const MAX_REF = 1024;
+
+fn isNameHead(c: u8) bool {
+    return (c >= 'a' and c <= 'z') or (c >= 'A' and c <= 'Z') or c == '@';
+}
+
+fn isNameBody(c: u8) bool {
+    return (c >= 'a' and c <= 'z') or (c >= 'A' and c <= 'Z') or
+        (c >= '0' and c <= '9') or
+        c == '.' or c == '~' or c == '_' or c == '-' or c == '/';
+}
+
+fn isTagChar(c: u8) bool {
+    return (c >= 'a' and c <= 'z') or (c >= 'A' and c <= 'Z') or
+        (c >= '0' and c <= '9') or
+        c == '.' or c == '~' or c == '_' or c == '-';
+}
+
+fn namely(name: []const u8) bool {
+    if (name.len == 0 or name.len > MAX_REF) return false;
+    if (!isNameHead(name[0])) return false;
+    for (name[1..]) |c| {
+        if (!isNameBody(c)) return false;
+    }
+    return true;
+}
+
+fn tagly(tag: []const u8) bool {
+    // The empty tag is an ordinary tag (§4 rule 2). The single-instance
+    // case writes no tag and never learns tags exist.
+    if (tag.len == 0) return true;
+    if (tag.len > MAX_REF) return false;
+    for (tag) |c| {
+        if (!isTagChar(c)) return false;
+    }
+    return true;
+}
+
+/// A non-string is not a name. Every port has to answer this the same
+/// way, and `ref/name` pins it for numbers, nulls and maps alike.
+pub fn checkname(name: ?*const v.Value) bool {
+    return v.isStr(name) and namely(v.asStr(name));
+}
+
+/// The asymmetry with a name is deliberate: a tag MAY start with a digit
+/// because auto-tagging assigns integer tags (`stripe$1`), and a tag
+/// admits neither `@` nor `/` because a name is a package specifier and
+/// a tag is not.
+pub fn checktag(tag: ?*const v.Value) bool {
+    return v.isStr(tag) and tagly(v.asStr(tag));
+}
+
+const Split = struct { name: []const u8, tag: []const u8 };
+
+/// Split on the FIRST `$`. Nothing in the grammar decides this — `$` is
+/// in neither character class — so the corpus is the arbiter (§4 rule
+/// 5), and it picks the split that blames the part actually at fault:
+/// `a$b$c` is a good name with a bad tag, not the reverse.
+fn split(s: []const u8) Split {
+    const cut = std.mem.indexOfScalar(u8, s, '$') orelse return .{ .name = s, .tag = "" };
+    return .{ .name = s[0..cut], .tag = s[cut + 1 ..] };
+}
+
+pub fn parseref(str: ?*const v.Value) t.Err!*v.Value {
+    if (!v.isStr(str)) return t.fail("plugin_bad_name", "ref must be a string", null);
+    const sp = split(v.asStr(str));
+    if (!namely(sp.name)) {
+        return t.fail("plugin_bad_name", v.print("invalid plugin name: {s}", .{sp.name}), t.details1("name", v.vstr(sp.name)));
+    }
+    if (!tagly(sp.tag)) {
+        return t.fail("plugin_bad_tag", v.print("invalid plugin tag: {s}", .{sp.tag}), t.details2("name", v.vstr(sp.name), "tag", v.vstr(sp.tag)));
+    }
+    const out = v.vmap();
+    v.set(out, "name", v.vstr(sp.name));
+    v.set(out, "tag", v.vstr(sp.tag));
+    return out;
+}
+
+/// An empty tag NEVER writes the separator, which is the half of
+/// canonicalization formatref owns: parse tolerates `stripe$`, format
+/// never produces it, so a round trip is idempotent.
+pub fn formatref(name: ?*v.Value, tag: ?*v.Value) t.Err![]const u8 {
+    const tagok = v.isNull(tag) or v.isStr(tag);
+    const tg = if (v.isStr(tag)) v.asStr(tag) else "";
+
+    if (!checkname(name)) {
+        const shown = if (v.isStr(name)) v.asStr(name) else "";
+        return t.fail("plugin_bad_name", v.print("invalid plugin name: {s}", .{shown}), t.details1("name", if (v.isNull(name)) v.vnull() else name));
+    }
+    if (!tagok or !tagly(tg)) {
+        return t.fail("plugin_bad_tag", v.print("invalid plugin tag: {s}", .{tg}), t.details2("name", name, "tag", if (v.isNull(tag)) v.vstr("") else tag));
+    }
+
+    if (tg.len == 0) return v.asStr(name);
+    return v.print("{s}${s}", .{ v.asStr(name), tg });
+}
+
+/// The canonical spelling. §4 rule 5: canonicalize before comparison.
+pub fn canonref(str: ?*const v.Value) t.Err![]const u8 {
+    const r = try parseref(str);
+    return formatref(v.get(r, "name"), v.get(r, "tag"));
+}
+
+pub fn canonrefs(str: []const u8) t.Err![]const u8 {
+    return canonref(v.vstr(str));
+}
+
+/// The canonical ref this string denotes, or null if it denotes none —
+/// the TOLERANT half of `canonref`, and the one a requirement name needs
+/// (§11.1). Capability names are free-form, so `2fa` is a good one and
+/// no ref could be called that; `canonref` FAILS on those, and asking it
+/// "is this a ref?" made a legal document kill the host.
+///
+/// An optional, so a caller cannot mistake "not a ref" for "the empty
+/// ref" — and infallible, because it answers rather than raises.
+pub fn tryref(str: []const u8) ?[]const u8 {
+    const sp = split(str);
+    if (!namely(sp.name) or !tagly(sp.tag)) return null;
+    if (sp.tag.len == 0) return sp.name;
+    return v.print("{s}${s}", .{ sp.name, sp.tag });
+}
+
+/// `canonref` for internal callers that want the input back unchanged
+/// when it is not well formed. NEVER use where a bad ref must be
+/// reported — the corpus pins plugin_bad_name at every public entry.
+pub fn canon(str: []const u8) []const u8 {
+    return tryref(str) orelse str;
+}
+
+/// The name half, for internal callers that only compare.
+pub fn refname(str: []const u8) []const u8 {
+    const sp = split(str);
+    return if (namely(sp.name)) sp.name else str;
+}

package/project/.sdk/tm/zig/feature/secrets/plugin/resolve.zig

@@ -0,0 +1,74 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (zig/src/resolve.zig)
+// 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.
+//! Dynamic resolution (§10.2) — name to candidate module ids.
+//!
+//! PURE. It returns the ids a host WOULD try, in order; it does not load
+//! anything. That separation is what lets the corpus pin resolution in
+//! every language including those with no dynamic loading at all — zig
+//! among them — and it is why §15.4 puts real module loading in per-port
+//! integration tests rather than here.
+
+const std = @import("std");
+const v = @import("value.zig");
+
+fn pushuniq(out: *v.Value, id: []const u8) void {
+    for (v.items(out)) |x| {
+        if (std.mem.eql(u8, v.asStr(x), id)) return;
+    }
+    v.push(out, v.vstr(id));
+}
+
+const DEFAULT_PREFIX = [_][]const u8{ "@voxgig/plugin-", "voxgig-plugin-", "plugin-", "" };
+
+pub fn resolvecandidates(name: ?*v.Value, sources: ?*v.Value) *v.Value {
+    const out = v.vlist();
+    const n = if (v.isStr(name)) v.asStr(name) else "";
+
+    // A SCOPED NAME RESOLVES VERBATIM ONLY (§10.2). `@acme/thing` is
+    // already a package id; prefixing it produces
+    // `@voxgig/plugin-@acme/thing`, which is not a thing that can exist.
+    if (n.len > 0 and n[0] == '@') {
+        v.push(out, v.vstr(n));
+        return out;
+    }
+
+    if (!(v.isList(sources) and v.len(sources) > 0)) {
+        for (DEFAULT_PREFIX) |p| pushuniq(out, v.print("{s}{s}", .{ p, n }));
+        return out;
+    }
+
+    for (v.items(sources)) |src| {
+        const kind = v.asStr(v.get(src, "kind"));
+        if (std.mem.eql(u8, kind, "module")) {
+            const prefix = v.get(src, "prefix");
+            if (v.isList(prefix) and v.len(prefix) > 0) {
+                for (v.items(prefix)) |p| pushuniq(out, v.print("{s}{s}", .{ v.asStr(p), n }));
+            } else {
+                pushuniq(out, n);
+            }
+        } else if (std.mem.eql(u8, kind, "path")) {
+            var dir = v.asStr(v.get(src, "dir"));
+            // Trailing slashes are trimmed, so `lib/` and `lib` give one
+            // id rather than two spellings of it.
+            while (dir.len > 0 and dir[dir.len - 1] == '/') dir = dir[0 .. dir.len - 1];
+            pushuniq(out, v.print("{s}/{s}", .{ dir, n }));
+        }
+    }
+
+    return out;
+}
+
+/// A MODULE PATH IS NOT A NAME (§10.2). The ref grammar starts a name
+/// with a letter or `@`, so `./local/thing` is not a ref and never
+/// reaches candidate generation — seneca allows a path where a plugin
+/// name goes, and this design deliberately does not, because a ref is an
+/// ADDRESS WITHIN A HOST and a path is a LOCATION ON A DISK.
+///
+/// Loading from an explicit location bypasses candidate generation
+/// entirely: `from` is passed to the resolver verbatim.
+pub fn resolvefrom(from: ?*v.Value) *v.Value {
+    const out = v.vlist();
+    v.push(out, if (v.isNull(from)) v.vnull() else from);
+    return out;
+}

package/project/.sdk/tm/zig/feature/secrets/plugin/types.zig

@@ -0,0 +1,140 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (zig/src/types.zig)
+// 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.
+//! Errors, and the raise mechanism (§12).
+//!
+//! ZIG ERRORS ARE VALUES WITHOUT PAYLOADS, and that is this port's one
+//! big decision. There is no `throw` carrying an object and no
+//! `setjmp`; there is `error.Plugin` and an explicit `try` at every
+//! call. So the DIAGNOSTIC TRAVELS BESIDE THE ERROR: `fail` parks a
+//! `PluginError` in `pending` and returns `error.Plugin`, and every
+//! handler reads it with `take()` as its first act.
+//!
+//! THAT DISCIPLINE IS LOAD-BEARING. `pending` holds one error; a
+//! handler that calls something fallible before reading it gets the
+//! second error's payload with the first error's control flow. Every
+//! `catch` in this port takes first and works afterwards, and that is
+//! the thing to check when adding one.
+//!
+//! The upside is what `c` pays `volatile` for and does not get: an
+//! explicit `try` means the compiler will not let a fallible call be
+//! ignored, so the "missed check continues silently past a failure"
+//! failure mode `c`'s longjmp exists to prevent cannot happen here at
+//! all.
+//!
+//! Ports compare by CODE and never by message: wording is a port's own
+//! business. The FORMAT is pinned, because a parseable message is what
+//! makes a log searchable across twenty languages.
+
+const std = @import("std");
+const v = @import("value.zig");
+
+pub const Err = error{Plugin};
+
+pub const PluginError = struct {
+    code: []const u8,
+    text: []const u8,
+    details: *v.Value,
+    message: []const u8,
+};
+
+var pending: ?PluginError = null;
+
+/// §12's detail fields render in a FIXED ORDER — part of the contract,
+/// not a formatting preference, because otherwise each port invents its
+/// own and message parity is gone.
+const detail_order = [_][]const u8{
+    "host",  "ref",     "name",  "tag",        "point", "key",     "capability",
+    "range", "version", "match", "candidates", "cycle", "holders", "refs",
+    "path",  "cause",
+};
+
+pub fn formatError(code: []const u8, text: []const u8, details: ?*v.Value) []const u8 {
+    // Values render as COMPACT JSON, so a value containing a space or a
+    // bracket cannot break the parse and a list renders as an array. The
+    // bracket is absent entirely when no field applies.
+    var tail = v.List(u8).init(v.arena());
+    for (detail_order) |k| {
+        if (!v.has(details, k)) continue;
+        if (tail.items.len > 0) tail.append(' ') catch @panic("oom");
+        tail.appendSlice(k) catch @panic("oom");
+        tail.append('=') catch @panic("oom");
+        tail.appendSlice(v.json(v.get(details, k))) catch @panic("oom");
+    }
+    if (tail.items.len == 0) return v.print("plugin/{s}: {s}", .{ code, text });
+    return v.print("plugin/{s}: {s} [{s}]", .{ code, text, tail.items });
+}
+
+/// Raise. Use as `return fail(...)` or `try` through it.
+pub fn fail(code: []const u8, text: []const u8, details: ?*v.Value) Err {
+    const d = details orelse v.vmap();
+    pending = .{
+        .code = v.dupe(code),
+        .text = v.dupe(text),
+        .details = d,
+        .message = formatError(code, text, d),
+    };
+    return error.Plugin;
+}
+
+/// Read and clear the parked error. THE FIRST THING EVERY HANDLER DOES.
+pub fn take() PluginError {
+    const e = pending orelse PluginError{
+        .code = "plugin_bad_state",
+        .text = "error raised with no diagnostic",
+        .details = v.vmap(),
+        .message = "plugin/plugin_bad_state: error raised with no diagnostic",
+    };
+    pending = null;
+    return e;
+}
+
+/// Re-park an error a handler has already taken, so it can be
+/// propagated unchanged.
+pub fn reraise(e: PluginError) Err {
+    pending = e;
+    return error.Plugin;
+}
+
+pub fn details1(k: []const u8, val: ?*v.Value) *v.Value {
+    const d = v.vmap();
+    v.set(d, k, val);
+    return d;
+}
+
+pub fn details2(k1: []const u8, v1: ?*v.Value, k2: []const u8, v2: ?*v.Value) *v.Value {
+    const d = v.vmap();
+    v.set(d, k1, v1);
+    v.set(d, k2, v2);
+    return d;
+}
+
+/// Deep merge, struct's semantics: maps merge, everything else
+/// replaces. §16 permits voxgig/struct for this and zig has no port of
+/// it.
+pub fn mergeValue(a: ?*v.Value, b: ?*v.Value) ?*v.Value {
+    if (!v.isMap(a) or !v.isMap(b)) return b orelse a;
+    const out = v.vmap();
+    for (v.keys(a)) |k| v.set(out, k, v.get(a, k));
+    for (v.keys(b)) |k| {
+        const bv = v.get(b, k);
+        const av = v.get(out, k);
+        if (v.isMap(av) and v.isMap(bv)) v.set(out, k, mergeValue(av, bv)) else v.set(out, k, bv);
+    }
+    return out;
+}
+
+/// §11.1's partial match: every leaf in `want` must be present and
+/// equal in `have`; keys not mentioned are not checked.
+pub fn matchValue(want: ?*v.Value, have: ?*v.Value) bool {
+    if (v.isNull(want)) return true;
+    if (v.isMap(want)) {
+        if (!v.isMap(have)) return false;
+        for (v.keys(want)) |k| {
+            if (!v.has(have, k)) return false;
+            if (!matchValue(v.get(want, k), v.get(have, k))) return false;
+        }
+        return true;
+    }
+    return v.same(want, have);
+}