@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/tm/ts/test/live-runner.ts

@@ -1,7 +1,15 @@
 // Execute every independent live step before deciding the suite's result.
 // Values never appear in reports: they can contain credentials or API data.
 
-type LiveState = 'passed' | 'failed' | 'blocked' | 'excluded'
+type LiveState = 'passed' | 'failed' | 'blocked' | 'empty' | 'excluded'
+
+type LiveRequest = {
+  method: string
+  path: string
+  status?: number
+  type?: string
+  agent?: string
+}
 
 type LiveResult = {
   id: string
@@ -10,14 +18,14 @@ type LiveResult = {
   role?: string
   retention?: string
   reason?: string
-  requests?: { method: string, path: string, status?: number }[]
+  requests?: LiveRequest[]
 }
 
 type LiveContext = {
   values: Map<string, any>
   publish(value: any): void
   attempted(): void
-  requests: { method: string, path: string, status?: number }[]
+  requests: LiveRequest[]
 }
 
 type LiveStep = {
@@ -32,16 +40,27 @@ type LiveStep = {
 
 class LiveBlocked extends Error {}
 
+// The account answered, but holds no record the step could act on.
+class LiveEmpty extends Error {}
+
 type LiveReport = {
   planned: number
   attempted: number
   passed: number
   failed: number
   blocked: number
+  empty: number
   excluded: number
   results: LiveResult[]
 }
 
+// What main.kit.test.live.strict decides: a strict run fails a live test
+// that did not succeed, a lenient one skips it with the reason.
+type LiveSettle = {
+  strict?: boolean
+  t?: { skip(message?: string): void }
+}
+
 async function runLiveSteps(
   steps: LiveStep[],
   options: { delayMs?: number, report?: (result: LiveResult) => void } = {},
@@ -100,11 +119,10 @@ async function runLiveSteps(
           record({ id: step.id, state: 'passed', attempted, requests })
         }
         catch (error) {
-          // Ordinary SDK errors can contain request headers, bodies, or an
-          // issued token. Report the step's failure without serializing it.
-          record({ id: step.id, state: error instanceof LiveBlocked ? 'blocked' : 'failed',
-            attempted, requests,
-            reason: error instanceof LiveBlocked ? error.message : 'Request or assertion failed' })
+          const state: LiveState = error instanceof LiveEmpty ? 'empty'
+            : error instanceof LiveBlocked ? 'blocked' : 'failed'
+          record({ id: step.id, state, attempted, requests,
+            reason: 'failed' === state ? failureReason(error) : (error as Error).message })
         }
         if (attempted && (options.delayMs || 0) > 0) {
           await new Promise(resolve => setTimeout(resolve, options.delayMs))
@@ -125,17 +143,53 @@ async function runLiveSteps(
     passed: results.filter(result => result.state === 'passed').length,
     failed: results.filter(result => result.state === 'failed').length,
     blocked: results.filter(result => result.state === 'blocked').length,
+    empty: results.filter(result => result.state === 'empty').length,
     excluded: results.filter(result => result.state === 'excluded').length,
     results,
   }
 }
 
+// An SDK error's code and an assertion's own fixed message say what went
+// wrong without repeating a value; a message built from values could
+// carry a header, a body or a token, so it is not reported.
+function failureReason(error: any): string {
+  if (null != error?.sdk && 'string' === typeof error.code) {
+    return 'Request failed: ' + error.code
+  }
+  // Node appends the compared values to a custom assertion message.
+  if ('ERR_ASSERTION' === error?.code && false === error.generatedMessage) {
+    return 'Assertion failed: ' + String(error.message).split('\n')[0]
+  }
+  return 'Request or assertion failed'
+}
+
+function liveIncomplete(report: LiveReport): boolean {
+  return 0 < report.failed || 0 < report.blocked || 0 === report.attempted
+}
+
 function assertLiveReport(report: LiveReport): void {
-  if (report.failed || report.blocked || !report.attempted) {
+  if (liveIncomplete(report)) {
     throw new Error('Live coverage incomplete: ' + JSON.stringify(report))
   }
 }
 
+// An account with no record for a step to read skips in either mode.
+function settleLiveReport(report: LiveReport, settle: LiveSettle = {}): void {
+  if (liveIncomplete(report)) {
+    if (false !== settle.strict || null == settle.t) return assertLiveReport(report)
+    return settle.t.skip('Live coverage incomplete (main.kit.test.live.strict is false): ' +
+      liveSummary(report))
+  }
+  if (0 < report.empty) settle.t?.skip('Live coverage incomplete: ' + liveSummary(report))
+}
+
+function liveSummary(report: LiveReport): string {
+  const open = report.results.filter(result => 'passed' !== result.state)
+  return 0 === open.length ? 'no request attempted' :
+    open.map(result => result.id + ' ' + result.state +
+      (result.reason ? ' (' + result.reason + ')' : '')).join('; ')
+}
+
 function createLiveTransport(timeoutMs = 30000) {
   let context: LiveContext | undefined
   const requests: LiveContext['requests'] = []
@@ -145,8 +199,11 @@ function createLiveTransport(timeoutMs = 30000) {
     enter(next: LiveContext) { context = next },
     fetch: async (input: any, init?: any) => {
       const url = new URL(String(input))
-      const request: LiveContext['requests'][number] = {
+      // A credential can travel as the agent (auth.name), so only whether
+      // the request carried one is recorded, never its value.
+      const request: LiveRequest = {
         method: init?.method || 'GET', path: url.origin + url.pathname,
+        agent: null == new Headers(init?.headers).get('user-agent') ? 'transport default' : 'configured',
       }
       requests.push(request)
       context?.requests.push(request)
@@ -156,11 +213,21 @@ function createLiveTransport(timeoutMs = 30000) {
       const signal = init?.signal ? AbortSignal.any([init.signal, timeout]) : timeout
       const response = await nativeFetch(input, { ...init, signal })
       request.status = response.status
+      const type = response.headers.get('content-type')
+      if (type) request.type = type.split(';')[0].trim()
       if (!context) console.log('LIVE RESPONSE ' + JSON.stringify(request))
       return response
     },
   }
 }
 
-export { runLiveSteps, assertLiveReport, LiveBlocked, createLiveTransport }
-export type { LiveStep, LiveContext, LiveReport, LiveResult }
+export {
+  runLiveSteps,
+  assertLiveReport,
+  settleLiveReport,
+  liveSummary,
+  LiveBlocked,
+  LiveEmpty,
+  createLiveTransport,
+}
+export type { LiveStep, LiveContext, LiveReport, LiveResult, LiveSettle }

package/project/.sdk/tm/ts/test/live-scenarios.ts

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict'
-import { LiveBlocked, runLiveSteps, assertLiveReport, createLiveTransport } from './live-runner'
+import { LiveBlocked, runLiveSteps, settleLiveReport, createLiveTransport } from './live-runner'
+import type { LiveSettle } from './live-runner'
 import { requestContract, synthesizeInput, validateContract } from './live-contract'
 import { liveClientOptions, liveDelayMs, isControlSkipped } from './utility'
 
@@ -31,7 +32,7 @@ export function recipeNeeds(value: any): string[] {
   return [...new Set([...(typeof value.from === 'string' ? [value.from] : []), ...Object.values(value).flatMap(recipeNeeds)])]
 }
 
-export async function runLiveScenarios(SDK: any, plan: any[], envPrefix: string, liveDefaults: any = {}) {
+export async function runLiveScenarios(SDK: any, plan: any[], envPrefix: string, liveDefaults: any = {}, settle: LiveSettle = {}) {
   const transport = createLiveTransport()
   const steps = plan.map(point => {
     const hint = point.facts.live || {}
@@ -44,7 +45,7 @@ export async function runLiveScenarios(SDK: any, plan: any[], envPrefix: string,
         // Every operation point is planned, not only the hinted ones; a hint
         // only decides whether this file is generated. Absent a recipe there
         // is no consent to call the operation, so block rather than
-        // synthesize input for it. Blocked fails assertLiveReport, so an
+        // synthesize input for it. A strict run fails a blocked step, so an
         // omission surfaces instead of passing quietly.
         if (!point.facts.live) throw new LiveBlocked('No live recipe: add a live hint for this operation in the guide, or give it an explicit excluded reason')
         if (point.contractVersion && point.contractVersion !== 1) throw new LiveBlocked('Unsupported operation contract version')
@@ -113,6 +114,6 @@ export async function runLiveScenarios(SDK: any, plan: any[], envPrefix: string,
   })
   const report = await runLiveSteps(steps, { delayMs: liveDelayMs(), report: result => console.log('LIVE STEP ' + JSON.stringify(result)) })
   console.log('LIVE SUMMARY ' + JSON.stringify(report))
-  assertLiveReport(report)
+  settleLiveReport(report, settle)
   return report
 }

package/project/.sdk/tm/ts/test/pipeline.test.ts

@@ -3,7 +3,7 @@
 import { test, describe } from 'node:test'
 import { strictEqual, ok, deepStrictEqual } from 'node:assert'
 
-import { stdutil } from '..'
+import { ProjectNameSDK, stdutil } from '..'
 
 
 const struct: any = (stdutil as any).struct
@@ -73,6 +73,23 @@ describe('pipeline:makePoint + makeSpec', () => {
     strictEqual((stdutil as any).makePoint(base({ out: { point: preset } })), preset)
   })
 
+  test('an allow list names whole operations, in any case', () => {
+    const point = { method: 'GET', parts: ['a'] }
+    const op = { name: 'load', points: [point] }
+    strictEqual((stdutil as any).makePoint(base({ op, options: { allow: { op: 'reload,unload' } } })).code,
+      'point_op_allow')
+    strictEqual((stdutil as any).makePoint(base({ op, options: { allow: { op: 'list, LOAD' } } })), point)
+  })
+
+  test('an allow list names whole methods', () => {
+    const ctx = base({
+      op: { name: 'update', points: [] },
+      point: { method: 'pu', parts: ['a'] },
+      options: { allow: { method: 'GET,PUT' }, base: 'http://x' },
+    })
+    strictEqual((stdutil as any).makeSpec(ctx).code, 'spec_method_allow')
+  })
+
   test('makeSpec short-circuits a feature-supplied spec', () => {
     const preset = { method: 'GET' }
     strictEqual((stdutil as any).makeSpec(base({ out: { spec: preset } })), preset)
@@ -80,6 +97,20 @@ describe('pipeline:makePoint + makeSpec', () => {
 })
 
 
+describe('pipeline:direct', () => {
+
+  test('direct and graphql answer a method allow.method refuses with a result map', async () => {
+    const sdk = ProjectNameSDK.test({}, { allow: { method: 'GET' } })
+    const direct: any = await sdk.direct({ path: '/a', method: 'POST' })
+    strictEqual(direct.ok, false)
+    strictEqual(direct.err.code, 'spec_method_allow')
+    const graphql: any = await sdk.graphql('{ a }')
+    strictEqual(graphql.ok, false)
+    strictEqual(graphql.err.code, 'spec_method_allow')
+  })
+})
+
+
 describe('pipeline:makeResponse', () => {
 
   test('guards missing spec / response / result', async () => {
@@ -479,4 +510,24 @@ describe('pipeline:result helpers', () => {
     await (stdutil as any).resultBody(ctx)
     strictEqual(ctx.result.body, undefined)
   })
+
+  // The agent and the body preview may carry a registered value; the body is
+  // cleaned before the bound so a split value cannot leave its prefix.
+  test('resultBody masks a registered value in the agent and across the preview bound', async () => {
+    const secret = 'PIPELINE-SECRET-a1b2c3d4e5f6'
+    const text = 'x'.repeat(150) + secret + 'y'.repeat(100)
+    const ctx = base({
+      options: { __derived__: { clean: { active: true, keys: [], values: [], mask: '[redacted]', hint: 0, min: 4 } } },
+      spec: { headers: { 'user-agent': 'Probe ' + secret } },
+      response: { body: 'body', json: async () => { throw Object.assign(new SyntaxError('bad json'), { text }) } },
+      result: { status: 200, headers: { 'content-type': 'text/html' } },
+    })
+    ;(stdutil as any).cleanAdd(ctx, secret)
+    await (stdutil as any).resultBody(ctx)
+    const message = String(ctx.result.err.message)
+    strictEqual(ctx.result.err.code, 'response_content_type')
+    ok(message.includes('user-agent Probe [redacted]'), message)
+    ok(message.includes('body: ' + 'x'.repeat(150) + '[redacted]'), message)
+    ok(!message.includes(secret.slice(0, 8)), message)
+  })
 })

package/project/.sdk/tm/ts/test/tsconfig.json

@@ -11,5 +11,6 @@
     "strict": true,
     "target": "ES2022",
     "types": ["node"]
-  }
+  },
+  "references": [{ "path": "../src" }]
 }

package/project/.sdk/tm/ts/test/utility.ts

@@ -144,16 +144,41 @@ function maybeSkipControl(
 }
 
 
-// Skips the current live test when required idmap keys aren't supplied.
-// Generated tests call this when they would otherwise pass `undefined`
-// values into a path/query param and 4xx the request.
-function skipIfMissingIds(t: any, setup: any, requiredKeys: string[]): boolean {
+// A live test without the ids its request needs is blocked rather than sent
+// with `undefined` in a path or query parameter. Returns true when skipped.
+function skipIfMissingIds(t: any, setup: any, requiredKeys: string[], strict = true): boolean {
   if (!setup.live) return false
   const missing = requiredKeys.filter(k => null == setup.idmap?.[k])
-  if (missing.length > 0) {
-    throw new Error(`Live test blocked: needs ${missing.join(', ')} via *_ENTID env var`)
+  return 0 < missing.length &&
+    liveMiss(t, strict, `Live test blocked: needs ${missing.join(', ')} via *_ENTID env var`)
+}
+
+
+// A live check that did not pass: strict fails the test, lenient skips it.
+function liveMiss(t: any, strict: boolean, reason: string): boolean {
+  if (strict) throw new Error(reason)
+  t.skip(reason)
+  return true
+}
+
+
+// An empty list is a valid answer, so a test needing a record skips.
+function liveEmpty(t: any, reason: string): boolean {
+  t.skip(reason)
+  return true
+}
+
+
+// The SDK's error, already bounded and cleaned, or else status and content type.
+function describeLive(result: any): string {
+  const err = result?.err
+  if (null != err) {
+    return String(err.message || err.code || err)
   }
-  return false
+  const headers = result?.headers
+  const type = 'function' === typeof headers?.get ? headers.get('content-type') :
+    Object.entries(headers || {}).find(([k]) => 'content-type' === k.toLowerCase())?.[1]
+  return 'HTTP ' + result?.status + (type ? ' ' + String(type).split(';')[0] : '')
 }
 
 
@@ -264,6 +289,9 @@ export {
   isControlSkipped,
   maybeSkipControl,
   skipIfMissingIds,
+  liveMiss,
+  liveEmpty,
+  describeLive,
   liveClientOptions,
   liveDelayMs,
   liveDelay,

package/project/.sdk/tm/zig/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Voxgig
+Copyright (c) $$const.year$$ PROJECTPUBLISHER
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/project/.sdk/tm/zig/core/context.zig

@@ -194,7 +194,8 @@ pub const Context = struct {
 
         const opcfg = h.getpath(&.{ "entity", entname, "op", opname }, self.config);
 
-        const input: []const u8 = if (std.mem.eql(u8, opname, "update") or std.mem.eql(u8, opname, "create")) "data" else "match";
+        const input: []const u8 = if (std.mem.eql(u8, opname, "update") or std.mem.eql(u8, opname, "create") or
+            std.mem.eql(u8, opname, "patch")) "data" else "match";
 
         const targets: Value = switch (h.getp(opcfg, "points")) {
             .array => h.getp(opcfg, "points"),

package/project/.sdk/tm/zig/core/helpers.zig

@@ -132,6 +132,20 @@ pub fn setp(val: Value, key: []const u8, newval: Value) void {
     }
 }
 
+// Whether a comma-separated allow option names the item: whole names, any case.
+pub fn allow_list_has(names: Value, item: []const u8) bool {
+    const list: []const u8 = switch (names) {
+        .string => |text| text,
+        else => return false,
+    };
+    if (item.len == 0) return false;
+    var it = std.mem.splitScalar(u8, list, ',');
+    while (it.next()) |name| {
+        if (std.ascii.eqlIgnoreCase(std.mem.trim(u8, name, " \t\r\n"), item)) return true;
+    }
+    return false;
+}
+
 // Path read on a Value store.
 pub fn getpath(path: []const []const u8, store: Value) Value {
     const pl = Value.makeList(A()) catch unreachable;
@@ -365,3 +379,22 @@ pub fn unsupported_op(opname: []const u8, entityname: []const u8) *SdkError {
     const msg = std.fmt.allocPrint(A(), "operation '{s}' not supported by entity '{s}'", .{ opname, entityname }) catch "unsupported op";
     return SdkError.make("unsupported_op", msg);
 }
+
+// The caller's cookie pieces with the named cookies removed: a cookie is one
+// ;-delimited piece, whatever its value holds.
+pub fn cookie_keep(header: []const u8, names: []const []const u8) []const []const u8 {
+    var kept: std.ArrayList([]const u8) = .empty;
+    var pieces = std.mem.splitScalar(u8, header, ';');
+    while (pieces.next()) |piece| {
+        const cookie = std.mem.trim(u8, piece, " \t");
+        if (0 == cookie.len) continue;
+        const eq = std.mem.indexOfScalar(u8, cookie, '=') orelse cookie.len;
+        const name = std.mem.trim(u8, cookie[0..eq], " \t");
+        var owned = false;
+        for (names) |n| {
+            if (std.mem.eql(u8, n, name)) owned = true;
+        }
+        if (!owned) kept.append(A(), cookie) catch {};
+    }
+    return kept.items;
+}

package/project/.sdk/tm/zig/core/response.zig

@@ -12,6 +12,8 @@ pub const Response = struct {
     json: Value = .{ .null = {} },
     body: Value = .{ .null = {} },
     err: ?*err.ProjectNameError = null,
+    // Set by a transport that could not read a non-blank body as JSON.
+    unreadable: bool = false,
 
     pub fn make(resmap: Value) *Response {
         const r = h.A().create(Response) catch unreachable;
@@ -26,6 +28,7 @@ pub const Response = struct {
             .json = h.getp(resmap, "json"),
             .body = h.getp(resmap, "body"),
             .err = null,
+            .unreadable = h.get_bool(resmap, "unreadable") orelse false,
         };
         return r;
     }

package/project/.sdk/tm/zig/core/spec.zig

@@ -1,5 +1,6 @@
 // Request specification (mirrors go core/spec.go).
 
+const std = @import("std");
 const h = @import("helpers.zig");
 const Value = h.Value;
 
@@ -17,6 +18,9 @@ pub const Spec = struct {
     body: Value = .{ .null = {} },
     url: []const u8 = "",
     path: []const u8 = "",
+    // The query parameters prepare_auth placed: the credential, which the
+    // request sends and the entity's match leaves out.
+    authquery: []const []const u8 = &.{},
 
     pub fn make(specmap: Value) *Spec {
         const s = h.A().create(Spec) catch unreachable;
@@ -49,6 +53,29 @@ pub const Spec = struct {
         return s;
     }
 
+    // Whatever prepare_auth set in the query, under whichever name, is the
+    // credential; a key it left as it was is the caller's.
+    pub fn note_authquery(self: *Spec, before: Value) void {
+        var out: std.ArrayList([]const u8) = .empty;
+        if (self.query == .object) {
+            var it = self.query.object.iterator();
+            while (it.next()) |kv| {
+                const was = h.getp(before, kv.key_ptr.*);
+                if (h.is_noval(was) or !h.veq(was, kv.value_ptr.*)) {
+                    out.append(h.A(), kv.key_ptr.*) catch {};
+                }
+            }
+        }
+        self.authquery = out.toOwnedSlice(h.A()) catch &.{};
+    }
+
+    pub fn authquery_has(self: *const Spec, key: []const u8) bool {
+        for (self.authquery) |name| {
+            if (std.mem.eql(u8, name, key)) return true;
+        }
+        return false;
+    }
+
     pub fn to_value(self: *const Spec) Value {
         const out = h.omap();
         h.setp(out, "base", h.vstr(self.base));

package/project/.sdk/tm/zig/core/types.zig

@@ -91,6 +91,12 @@ pub const OpResult = union(enum) {
     err: *err.ProjectNameError,
 };
 
+// The public result of a stream: its items, or the error that failed it.
+pub const StreamResult = union(enum) {
+    ok: []Value,
+    err: *err.ProjectNameError,
+};
+
 // Pipeline stage products staged on ctx.out.
 pub const OutVal = union(enum) {
     val: Value,