@voxgig/sdkgen-langpack 0.0.1

package/.sdk/src/cmp/dart/fragment/Main.fragment.dart

@@ -0,0 +1,339 @@
+
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:async';
+
+import 'Config.dart';
+import 'Spec.dart';
+// ProjectNameEntityBase / ProjectNameError / BaseFeature are re-exported below;
+// a Dart `export` needs no matching `import`, so importing them here too is an
+// unused_import. Keep only the imports actually referenced in this file.
+import 'utility/ErrUtility.dart';
+// PREFIXED, and deliberately not re-exported. The runtime helper class is
+// named `Utility`, and so is the generated data class for an entity named
+// `utility` (ProjectNameTypes.dart) — exporting both from this library makes
+// the name ambiguous and NO dart SDK for such an API compiles:
+//
+//   Error: 'Utility' is exported from both 'lib/ProjectNameTypes.dart'
+//          and 'lib/utility/Utility.dart'
+//
+// The entity type is the user-facing name, so it keeps the plain one; the
+// runtime helper is internal plumbing and is reached through the prefix. Any
+// entity name can collide with an internal class, so the prefix — not a
+// rename — is what makes this safe for every API.
+import 'utility/Utility.dart' as sdkutil;
+
+export 'Config.dart' show Config, config;
+export 'ProjectNameEntityBase.dart' show ProjectNameEntityBase;
+export 'ProjectNameError.dart' show ProjectNameError;
+export 'feature/base/BaseFeature.dart' show BaseFeature;
+
+final sdkutil.Utility stdutil = sdkutil.Utility();
+
+class ProjectNameSDK {
+  String mode = 'live';
+  dynamic _options;
+  final sdkutil.Utility _utility = sdkutil.Utility();
+  List<dynamic> features = [];
+  dynamic rootctx;
+
+  // Feature activity tracking store (retry attempts, cache hits, spans, ...).
+  final Map<String, dynamic> track = {};
+
+  ProjectNameSDK([dynamic options]) {
+    rootctx = _utility.makeContext({
+      'client': this,
+      'utility': _utility,
+      'config': config.toMap(),
+      'options': options,
+      'shared': {},
+    });
+
+    _options = _utility.makeOptions(rootctx);
+
+    final struct = _utility.struct;
+
+    if (true == struct.getpath(_options, 'feature.test.active')) {
+      mode = 'test';
+    }
+
+    rootctx.options = _options;
+
+    features = [];
+
+    final featureAdd = _utility.featureAdd;
+    final featureInit = _utility.featureInit;
+
+    // Add features in the resolved order (makeOptions puts an explicit List
+    // order first, else defaults to test-first). Ordering matters: the
+    // `test` feature installs the base mock transport and the transport
+    // features (retry/cache/netsim/proxy/ratelimit) wrap whatever is current,
+    // so `test` must be added before them to sit at the base of the chain.
+    final List extendList =
+        _options['extend'] is List ? _options['extend'] : [];
+
+    final featureorder =
+        struct.getpath(_options, '__derived__.featureorder') ?? [];
+    for (final fname in featureorder) {
+      final fopts = _options['feature'][fname];
+      if (fopts is Map && true == fopts['active']) {
+        // An active name with no generated class is legal when an
+        // extend-supplied instance carries that name (station's adopt
+        // path): the instance is added below, positioned by its own
+        // __after__ entry, so skip it here rather than fail construction.
+        if (!config.hasFeature(fname.toString()) &&
+            extendList.any((f) => fname.toString() == f.name.toString())) {
+          continue;
+        }
+        featureAdd(rootctx, config.makeFeature(fname.toString()));
+      }
+    }
+
+    for (final f in extendList) {
+      featureAdd(rootctx, f);
+    }
+
+    for (final f in features) {
+      featureInit(rootctx, f);
+    }
+
+    final featureHook = _utility.featureHook;
+    featureHook(rootctx, 'PostConstruct');
+  }
+
+  dynamic options() {
+    return _utility.struct.clone(_options);
+  }
+
+  sdkutil.Utility utility() {
+    return _utility;
+  }
+
+// #SecretsAccessor
+  Future<dynamic> prepare([dynamic fetchargs]) async {
+    final utility = _utility;
+
+    final makeContext = utility.makeContext;
+    final makeFetchDef = utility.makeFetchDef;
+    final prepareHeaders = utility.prepareHeaders;
+    final prepareAuth = utility.prepareAuth;
+
+    fetchargs = fetchargs ?? {};
+
+    final ctx = makeContext({
+      'opname': 'prepare',
+      'ctrl': fetchargs['ctrl'] ?? {},
+    }, rootctx);
+
+    final options = _options;
+
+    // Build spec directly from SDK options + user-provided fetch args.
+    final spec = Spec({
+      'base': options['base'],
+      'prefix': options['prefix'],
+      'suffix': options['suffix'],
+      'path': fetchargs['path'] ?? '',
+      'method': fetchargs['method'] ?? 'GET',
+      'params': fetchargs['params'] ?? {},
+      'query': fetchargs['query'] ?? {},
+      'body': fetchargs['body'],
+      'step': 'start',
+    });
+
+    ctx.spec = spec;
+
+    spec.headers = prepareHeaders(ctx);
+
+    // Merge user-provided headers over SDK defaults.
+    if (fetchargs['headers'] is Map) {
+      (fetchargs['headers'] as Map).forEach((key, val) {
+        spec.headers[key] = val;
+      });
+    }
+
+    // Apply SDK auth (apikey, auth prefix, etc.)
+    final authResult = prepareAuth(ctx);
+    if (iserr(authResult)) {
+      return authResult;
+    }
+
+    return makeFetchDef(ctx);
+  }
+
+  // Raw endpoint access is operator-controllable, like every entity op.
+  // Blocking it means denying BOTH the 'direct' and 'graphql' tokens, since
+  // either one reaches the same endpoint.
+  Future<dynamic> direct([dynamic fetchargs]) async {
+    if (!_opAllowed('direct')) {
+      return _opDenied('direct');
+    }
+
+    return _rawRequest(fetchargs);
+  }
+
+  // Is this raw-access op permitted by the SDK's allow.op option?
+  bool _opAllowed(String op) {
+    final allow = _utility.struct.getpath(_options, 'allow.op');
+    return allow is String && allow.contains(op);
+  }
+
+  dynamic _opDenied(String op) {
+    final allow = _utility.struct.getpath(_options, 'allow.op');
+    return {
+      'ok': false,
+      'err': Exception('ProjectNameSDK: $op: operation not allowed by'
+          ' SDK option allow.op value: "${allow ?? ''}"'),
+    };
+  }
+
+  // Ungated request path shared by direct and graphql, each of which checks
+  // its own allow.op token first. Private, rather than a flag on fetchargs:
+  // a caller-supplied marker would let anyone opt straight back out of the
+  // gate by passing it.
+  Future<dynamic> _rawRequest([dynamic fetchargs]) async {
+    final utility = _utility;
+    final fetcher = utility.fetcher;
+    final makeContext = utility.makeContext;
+
+    final fetchdef = await prepare(fetchargs);
+    if (iserr(fetchdef)) {
+      return fetchdef;
+    }
+
+    final ctx = makeContext({
+      'opname': 'direct',
+      'ctrl': (fetchargs ?? {})['ctrl'] ?? {},
+    }, rootctx);
+
+    try {
+      final dynamic fetched =
+          await Future.value(fetcher(ctx, fetchdef['url'], fetchdef));
+
+      if (null == fetched) {
+        return {
+          'ok': false,
+          'err': ctx.error('direct_no_response', 'response: undefined')
+        };
+      } else if (iserr(fetched)) {
+        return {'ok': false, 'err': fetched};
+      }
+
+      final status = fetched['status'];
+
+      // No body responses (204 No Content, 304 Not Modified) and explicit
+      // zero content-length must skip JSON parsing.
+      final headers = fetched['headers'];
+      final contentLength =
+          headers is Map ? headers['content-length'] : null;
+      final noBody = 204 == status ||
+          304 == status ||
+          '0' == (null == contentLength ? null : contentLength.toString());
+
+      dynamic json;
+      if (!noBody) {
+        try {
+          final jsonFn = fetched['json'];
+          json = jsonFn is Function
+              ? await Future.value(jsonFn())
+              : fetched['json'];
+        } catch (_parseErr) {
+          // Body wasn't valid JSON — surface the raw response rather than
+          // throwing. data stays null; callers can inspect status/headers.
+          json = null;
+        }
+      }
+
+      return {
+        'ok': status is num && status >= 200 && status < 300,
+        'status': status,
+        'headers': fetched['headers'],
+        'data': json,
+      };
+    } catch (err) {
+      return {'ok': false, 'err': err};
+    }
+  }
+
+  // Raw GraphQL access: the pressure valve that makes the generated
+  // surface's deliberate omissions (per-call selection sets, typed filter
+  // builders, batching, subscriptions) livable — the whole schema stays
+  // reachable.
+  //
+  // Thin wrapper over the same prepare/fetch path direct uses, with the one
+  // thing raw direct cannot do for GraphQL: a GraphQL failure rides HTTP 200
+  // as a top-level `errors` array, so status alone would report a failed
+  // query as ok.
+  //
+  // NOTE: like direct, this bypasses the feature pipeline — no retry,
+  // ratelimit or paging features apply.
+  Future<dynamic> graphql(String query,
+      [dynamic variables, dynamic ctrl]) async {
+    if (!_opAllowed('graphql')) {
+      return _opDenied('graphql');
+    }
+
+    final dynamic res = await _rawRequest({
+      'method': 'POST',
+      'headers': {'content-type': 'application/json'},
+      'body': {'query': query, 'variables': variables ?? {}},
+      'ctrl': ctrl ?? {},
+    });
+
+    if (res is! Map) {
+      return res;
+    }
+
+    // Errors are read BEFORE any status check: a GraphQL parse or validation
+    // failure comes back as HTTP 400 carrying the standard { errors: [...] }
+    // body, and the raw path represents a non-2xx as ok:false with no err —
+    // so returning early on status would discard the server's own
+    // diagnostics, which are the only useful part of that response.
+    final errors = _utility.struct.getpath(res, 'data.errors');
+
+    if (errors is List && 0 < errors.length) {
+      final first = errors[0];
+      final msg = (first is Map ? first['message'] : null);
+      res['ok'] = false;
+      res['err'] = Exception('ProjectNameSDK: graphql: '
+          '${msg is String && msg.isNotEmpty ? msg : 'graphql error'}');
+      res['graphql'] = errors;
+    }
+
+    return res;
+  }
+
+  // <[SLOT]>
+
+  static ProjectNameSDK test([dynamic testoptsarg, dynamic sdkoptsarg]) {
+    final struct = stdutil.struct;
+    final setpath = struct.setpath;
+    final getdef = struct.getdef;
+    final clone = struct.clone;
+    final setprop = struct.setprop;
+
+    final sdkopts = getdef(clone(sdkoptsarg), {});
+    final testopts = getdef(clone(testoptsarg), {});
+    setprop(testopts, 'active', true);
+    setpath(sdkopts, 'feature.test', testopts);
+
+    final testsdk = ProjectNameSDK(sdkopts);
+    testsdk.mode = 'test';
+
+    return testsdk;
+  }
+
+  ProjectNameSDK tester([dynamic testopts, dynamic sdkopts]) {
+    return ProjectNameSDK.test(testopts, sdkopts);
+  }
+
+  Map<String, dynamic> toJSON() {
+    return {'name': 'ProjectName'};
+  }
+
+  @override
+  String toString() {
+    return 'ProjectName ' + _utility.struct.jsonify(toJSON());
+  }
+}
+
+typedef SDK = ProjectNameSDK;

package/.sdk/src/cmp/dart/fragment/SdkError.fragment.dart

@@ -0,0 +1,26 @@
+class ProjectNameError extends Error {
+  final bool isProjectNameError = true;
+
+  final String sdk = 'ProjectName';
+
+  String code;
+  String message;
+  dynamic ctx;
+
+  // Populated by makeError with the (cleaned) result and spec.
+  dynamic result;
+  dynamic spec;
+
+  // HTTP status of the response that caused this error, or -1 when the
+  // request never got one. PROMOTED to the top level: it used to be
+  // reachable only at `err.result['status']`, so every consumer coupled
+  // itself to the internal shape of `result`.
+  int status = -1;
+
+  bool get notFound => 404 == status;
+
+  ProjectNameError(this.code, this.message, [this.ctx]);
+
+  @override
+  String toString() => 'ProjectNameError: ' + code + ': ' + message;
+}

package/.sdk/src/cmp/dart/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "nodenext",
+    "noEmitOnError": true,
+    "outDir":"../dist",
+    "rootDir":".",
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2022",
+    "declaration": true,
+    "declarationDir": "../dist"
+  }
+}

package/.sdk/src/cmp/dart/utility_dart.ts

@@ -0,0 +1,155 @@
+
+import * as Path from 'node:path'
+
+
+import {
+  clone,
+  walk,
+} from '@voxgig/struct'
+
+
+// Escape a string for a single-quoted Dart string literal. `$` must be
+// escaped or Dart interpolates it (model values like '`$COPY`' would break).
+function dartString(s: string): string {
+  return "'" + String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\$/g, '\\$')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t') + "'"
+}
+
+
+// Render a JSON-like value as a deep-dynamic Dart literal. Every map is
+// emitted as `<String, dynamic>{...}` and every list as `<dynamic>[...]` so
+// the runtime struct utilities can freely mutate/extend the structures
+// (inferred literal types would be too narrow and throw at runtime).
+function dartValue(obj: any, indent: number = 0): string {
+  const pad = '  '.repeat(indent)
+  const cpad = '  '.repeat(indent + 1)
+
+  if (null == obj) {
+    return 'null'
+  }
+  if ('string' === typeof obj) {
+    return dartString(obj)
+  }
+  if ('number' === typeof obj) {
+    return isFinite(obj) ? String(obj) : 'null'
+  }
+  if ('boolean' === typeof obj) {
+    return obj ? 'true' : 'false'
+  }
+  if (Array.isArray(obj)) {
+    if (0 === obj.length) {
+      return '<dynamic>[]'
+    }
+    return '<dynamic>[\n' +
+      obj.map(v => cpad + dartValue(v, indent + 1) + ',').join('\n') +
+      '\n' + pad + ']'
+  }
+  if ('object' === typeof obj) {
+    const keys = Object.keys(obj)
+    if (0 === keys.length) {
+      return '<String, dynamic>{}'
+    }
+    return '<String, dynamic>{\n' +
+      keys.map(k => cpad + dartString(k) + ': ' + dartValue(obj[k], indent + 1) + ',')
+        .join('\n') +
+      '\n' + pad + '}'
+  }
+  return 'null'
+}
+
+
+function projectPath(suffix?: string): string {
+  return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
+}
+
+
+// Emission-time normalisation of a model subtree (L0).
+//
+// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
+// key$, val$). With `dropDefaults`, also drops keys whose value IS the
+// default the runtime already assumes when the key is absent, which is pure
+// payload — see CONFIG_DEFAULT.
+//
+// Rebuilds the tree rather than mutating during a walk. The previous
+// implementation walked a clone calling `delete p[k]`, but walk() assigns its
+// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
+// the delete was undone on the way out and the helper silently did nothing.
+// Returning `undefined` from the callback does not fix it either: setprop
+// stores undefined rather than removing the key, which then emits as a null.
+//
+// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
+// `active` means something different in feature config, where absent reads as
+// INACTIVE (see feature_init) — dropping `active: true` there would silently
+// disable the feature.
+// jostraca's iteration metadata, injected by each()/names() while it walks the
+// model. Listed explicitly rather than matched by trailing-dollar suffix: a
+// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
+// data -- so a blanket suffix match can silently drop a legitimate API field.
+const MODEL_META = ['index$', 'key$', 'val$']
+
+// Keys whose value IS the default the runtime already assumes when the key is
+// absent, so emitting them is pure payload.
+const CONFIG_DEFAULT: Record<string, any> = {
+  active: true,
+  req: false,
+  reqd: false,
+}
+
+// Subtrees carrying user payload rather than schema. An active:true inside an
+// OpenAPI example is DATA, not a default, so default-pruning stops at these
+// keys and everything below them is passed through untouched.
+const PAYLOAD_KEYS = ['default', 'example', 'examples']
+
+function clean(o: any, dropDefaults?: boolean): any {
+  const prune = (node: any, defaults: boolean): any => {
+    if (Array.isArray(node)) {
+      return node.map((n: any) => prune(n, defaults))
+    }
+    if (null != node && 'object' === typeof node) {
+      const out: any = {}
+      for (const k of Object.keys(node)) {
+        if (MODEL_META.includes(k)) {
+          continue
+        }
+        if (defaults && k in CONFIG_DEFAULT && CONFIG_DEFAULT[k] === node[k]) {
+          continue
+        }
+        out[k] = prune(node[k], defaults && !PAYLOAD_KEYS.includes(k))
+      }
+      return out
+    }
+    return node
+  }
+  return prune(o, true === dropDefaults)
+}
+
+
+
+// The JSON as a Dart string literal.
+//
+// Dart's ordinary string literals INTERPOLATE: `$name` and `${...}` are
+// substitution, and the model is full of `$` - `$STRING`, `$NUMBER`,
+// `$action`. A raw string (`r'...'`) would avoid that but cannot contain its
+// own quote character and has no escape for it, and the JSON contains both
+// quote characters in quantity.
+//
+// So: JSON.stringify's escaping, which already handles `"` and `\` and emits
+// no raw control characters, plus `$` -> `\$`. That last step is unambiguous
+// precisely because JSON.stringify has already escaped every backslash, so a
+// `\$` here can only have come from this rule.
+function dartStringLiteral(json: string): string {
+  return JSON.stringify(json).replace(/\$/g, '\\$')
+}
+
+export {
+  dartStringLiteral,
+  clean,
+  dartString,
+  dartValue,
+  projectPath,
+}

package/.sdk/src/cmp/haskell/Config_haskell.ts

@@ -0,0 +1,98 @@
+import {
+  Content,
+  File,
+  cmp,
+  configDefinition,
+  configReprSetting,
+  isConfigData,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  formatHsValue,
+  hsString,
+} from './utility_haskell'
+
+
+// The full set of feature constructors in SdkFeatures (name -> <name>Feature).
+const FEATURE_NAMES = [
+  'log', 'test', 'retry', 'timeout', 'ratelimit', 'cache', 'idempotency',
+  'paging', 'streaming', 'proxy', 'telemetry', 'metrics', 'debug', 'audit',
+  'clienttrack', 'rbac', 'netsim',
+]
+
+
+// SdkConfig.hs: makeConfig builds the embedded API model as a struct Value;
+// makeFeature(name) is the N-feature-safe factory the client uses to
+// instantiate features named in the options.
+const Config = cmp(async function Config(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  // The same config as an OBJECT, built by the shared helper so this target's
+  // literal and the data that replaces it above the threshold are the same
+  // config by construction. The JSON is what the threshold is measured on -
+  // emitted source size varies by language, the model does not.
+  const { def: configDef, json: configJson } = configDefinition(model)
+  const asData = isConfigData(configJson, configReprSetting(model))
+
+  // ABOVE THE THRESHOLD: emit the model as DATA.
+  //
+  // The literal representation is one enormous CV expression. GHC type-checks
+  // and desugars every constructor application in it, and buildCV then walks
+  // the whole tree allocating an IORef per node. A string constant is one
+  // token, and jsonRead builds the same Value from it directly.
+  //
+  // Both branches return a FRESH Value per call - buildCV allocates new
+  // IORefs, jsonRead re-parses - so a caller that mutates one config cannot
+  // reach another's, exactly as before.
+  const configBody = asData
+    ? `-- THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
+--
+-- Emitted only above a size threshold, or when \`main.kit.config.repr\` pins
+-- it: for a small model the CV literal is smaller and far easier to read when
+-- debugging.
+configData :: String
+configData = ${hsString(configJson)}
+
+makeConfig :: IO Value
+makeConfig = jsonRead configData`
+    : `makeConfig :: IO Value
+makeConfig = buildCV ${formatHsValue(configDef)}`
+
+  File({ name: 'SdkConfig.' + target.ext }, () => {
+
+    Content(`-- Generated API configuration (make_config) and the feature factory.
+
+module SdkConfig (makeConfig, makeFeature) where
+
+import VoxgigStruct (Value)
+import ${asData ? 'SdkJson (jsonRead)' : 'SdkHelpers (CV (..), buildCV)'}
+import SdkTypes (Feature)
+import qualified SdkFeatures as F
+
+${configBody}
+
+makeFeature :: String -> IO Feature
+makeFeature name = case name of
+`)
+
+    for (const fname of FEATURE_NAMES) {
+      Content(`  "${fname}" -> F.${fname}Feature\n`)
+    }
+
+    Content(`  _ -> F.baseFeature\n`)
+  })
+})
+
+
+export {
+  Config
+}

package/.sdk/src/cmp/haskell/Entity_haskell.ts

@@ -0,0 +1,13 @@
+import { cmp } from '@voxgig/sdkgen'
+
+
+// Entities are generic in the Haskell target: there is no per-entity
+// generated module. Every entity is created by the config-driven
+// F.makeEntity (see SdkClient), so this component emits nothing. It exists
+// only so the neutral Entity component can resolve a language delegate.
+const Entity = cmp(function Entity(_props: any) {})
+
+
+export {
+  Entity
+}

package/.sdk/src/cmp/haskell/Gitignore_haskell.ts

@@ -0,0 +1,27 @@
+import {
+  Content,
+  File,
+  cmp,
+} from '@voxgig/sdkgen'
+
+
+const Gitignore = cmp(async function Gitignore(_props: any) {
+  File({ name: '.gitignore' }, () => {
+    Content(`# Haskell build output
+.hsbuild/
+dist-newstyle/
+*.hi
+*.o
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+`)
+  })
+})
+
+
+export {
+  Gitignore
+}