@voxgig/sdkgen 1.2.1 → 1.3.1

package/src/cmp/Deploy.ts

@@ -0,0 +1,258 @@
+import { cmp, each, Content, File } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
+
+// Generate the SDK root deployment Makefile from the model's per-target
+// `publish` sections (see model/sdkgen.jsonic):
+//
+//   publish.tag       — git release tag `<prefix>/vX.Y.Z`; every port has
+//                       one, pushed with a token from the aql key vault
+//                       (--for recipe + alias, default github/github).
+//   publish.registry  — package registry details (name, url, vault
+//                       credential recipe or raw env mapping) plus a
+//                       `state` (pending | active | inactive; the legacy
+//                       `active: true` bool is honoured as an alias for
+//                       state === 'active'). While a registry is NOT
+//                       active (publish pending) a real deploy publishes
+//                       the git tag only; the package upload starts when
+//                       state flips to 'active'. Tag-only ports (go
+//                       family) have no registry.
+//
+// Follows the voxgig/struct root Makefile conventions: per-target deploy
+// targets, deliberately no all-targets real deploy (each upload is
+// irreversible), and an everything-at-once DRY run leaning on
+// `aql vault exec --dry-run` filler-token cooperation in each target's
+// publish recipe.
+const Deploy = cmp(function Deploy(props: any) {
+  const { ctx$ } = props
+  const { model } = ctx$
+
+  const targetMap = getModelPath(model, `main.${KIT}.target`) || {}
+  const targets: any[] = []
+  each(targetMap, (t: any) => {
+    if (false !== t.active) targets.push(t)
+  })
+
+  if (0 === targets.length) {
+    return
+  }
+
+  File({ name: 'Makefile' }, () => {
+    Content(makeDeployMakefile(model, targets))
+  })
+
+  ctx$.log.info({
+    point: 'generate-deploy',
+    note: 'targets: ' + targets.map((t: any) =>
+      t.name + (registryOf(t) ? (':' + registryOf(t).name + (regIsActive(registryOf(t)) ? '' : '(publish pending)')) : ':tag-only')
+    ).join(',')
+  })
+})
+
+
+function registryOf(t: any): any | undefined {
+  const reg = t.publish?.registry
+  return (reg && '' !== (reg.name || '')) ? reg : undefined
+}
+
+
+// A registry is active (package really uploaded) when its tri-state
+// `state === 'active'`. The legacy boolean `active: true` is honoured as a
+// back-compat alias. Anything else — 'pending' (the default), 'inactive' —
+// means a deploy publishes the git tag only.
+function regIsActive(reg: any): boolean {
+  if (null == reg) return false
+  if (true === reg.active) return true // legacy alias
+  return 'active' === reg.state
+}
+
+
+function aliasVarName(name: string): string {
+  return name.toUpperCase().replace(/[^A-Z0-9]+/g, '_') + '_ALIAS'
+}
+
+
+// The aql vault exec argument string for a target: `--for=<recipe>=<alias>`
+// flags where a preset recipe exists, or a raw `'alias=ENV_VAR,...'`
+// mapping when any credential lacks a preset (e.g. luarocks). The github
+// token for the tag push is always included.
+function vaultExecArgs(t: any): string {
+  const tagVault = t.publish?.tag?.vault || {}
+  const ghRecipe = tagVault.recipe || 'github'
+  const ghVar = aliasVarName(ghRecipe)
+  const reg = registryOf(t)
+  const regVault = reg?.vault || {}
+  const regVar = reg ? aliasVarName(reg.name) : ''
+
+  if (reg && '' === (regVault.recipe || '') && '' !== (regVault.env || '')) {
+    // Raw env mapping style: every credential as alias=ENV_VAR.
+    return `'$(${regVar})=${regVault.env},$(${ghVar})=GITHUB_TOKEN'`
+  }
+
+  const flags = []
+  if (reg && '' !== (regVault.recipe || '')) {
+    flags.push(`--for=${regVault.recipe}=$(${regVar})`)
+  }
+  flags.push(`--for=${ghRecipe}=$(${ghVar})`)
+  return flags.join(' ')
+}
+
+
+function makeDeployMakefile(model: any, targets: any[]): string {
+  // Alias variables: one per distinct vault credential, defaulting to the
+  // model's alias (or the registry/recipe name).
+  const aliasVars = new Map<string, string>()
+  for (const t of targets) {
+    const tagVault = t.publish?.tag?.vault || {}
+    const ghRecipe = tagVault.recipe || 'github'
+    if (!aliasVars.has(aliasVarName(ghRecipe))) {
+      aliasVars.set(aliasVarName(ghRecipe), tagVault.alias || ghRecipe)
+    }
+    const reg = registryOf(t)
+    if (reg && !aliasVars.has(aliasVarName(reg.name))) {
+      aliasVars.set(aliasVarName(reg.name), reg.vault?.alias || reg.name)
+    }
+  }
+
+  const summary = targets.map((t: any) => {
+    const reg = registryOf(t)
+    const state = reg
+      ? `${reg.name} (${regIsActive(reg) ? 'ACTIVE' : 'publish pending: deploy publishes the git tag only'}) ${reg.url || ''}`.trim()
+      : 'tag-only'
+    return `#   ${t.name.padEnd(8)} ${state}`
+  }).join('\n')
+
+  const deployRules = targets.map((t: any) => {
+    const reg = registryOf(t)
+    // The github token is the only credential a tag-only deploy needs.
+    const tagVault = t.publish?.tag?.vault || {}
+    const ghRecipe = tagVault.recipe || 'github'
+    const ghArgs = `--for=${ghRecipe}=$(${aliasVarName(ghRecipe)})`
+    const args = vaultExecArgs(t)
+
+    const via = t.publish?.tag?.via || 'port'
+
+    if (!reg && 'root' === via) {
+      // Tag-only port with no Makefile of its own (e.g. go-cli): the
+      // root tag-push recipe is the whole deploy.
+      return `
+deploy-${t.name}:
+\t@echo "deploy-${t.name}: tag-only port — publishing the git tag."
+\taql vault exec ${ghArgs} -- $(MAKE) tag-push-${t.name}
+
+deploy-dry-${t.name}:
+\taql vault exec --dry-run ${ghArgs} -- $(MAKE) tag-push-${t.name}
+${tagPushRecipe(t.name, 'tag-only port')}
+`
+    }
+
+    if (reg && !regIsActive(reg)) {
+      // Publish pending: deploying this target publishes its git tag
+      // only. The package upload turns on by flipping
+      // publish.registry.state to 'active' in the model and regenerating.
+      return `
+deploy-${t.name}:
+\t@echo "deploy-${t.name}: ${reg.name} publication is pending — publishing the git tag only."
+\taql vault exec ${ghArgs} -- $(MAKE) tag-push-${t.name}
+
+deploy-dry-${t.name}:
+\taql vault exec --dry-run ${ghArgs} -- $(MAKE) tag-push-${t.name}
+${tagPushRecipe(t.name, reg.name + ' publication pending — tag-only deploy')}
+`
+    }
+
+    return `
+deploy-${t.name}:
+\taql vault exec ${args} -- $(MAKE) -C ${t.name} publish
+
+deploy-dry-${t.name}:
+\taql vault exec --dry-run ${args} -- $(MAKE) -C ${t.name} publish
+`
+  }).join('')
+
+  const varLines = Array.from(aliasVars.entries())
+    .map(([v, def]) => `${v} ?= ${def}`).join('\n')
+
+  return `# ${model.Name} SDK deployment. GENERATED by @voxgig/sdkgen — regenerated
+# on every \`npm run generate\` in .sdk/; publication details live in the
+# model (.sdk/model/target/<target>.jsonic, \`publish\` section).
+#
+# Every port gets a git release tag <target>/vX.Y.Z. Ports with an ACTIVE
+# registry also publish a package there. Credentials are injected at exec
+# time by the aql key vault (https://github.com/aql-lang/aql) — never
+# stored on disk or passed on the command line.
+#
+# Publication state (from the model):
+${summary}
+#
+#   make deploy               list per-target deploy commands
+#   make deploy-<target>      deploy ONE target (no deploy-all: each
+#                             registry upload is irreversible); while a
+#                             registry is pending this publishes the
+#                             port's git tag only
+#   make deploy-dry           rehearse EVERY target: aql --dry-run
+#                             injects a filler token that each publish
+#                             recipe detects, so build + test run in full
+#                             but nothing is uploaded and no tag is cut
+#
+# Vault aliases (override per invocation, e.g. make deploy-ts NPM_ALIAS=work:npm):
+
+SHELL := /bin/bash
+
+${varLines}
+
+# Lockstep SDK version, read from the canonical ts manifest.
+VERSION := $(shell node -p "require('./ts/package.json').version" 2>/dev/null || echo 0.0.0)
+AQL_DRY_RUN_FILLER := AQL-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+
+TARGETS := ${targets.map((t: any) => t.name).join(' ')}
+
+.PHONY: deploy deploy-dry \\
+  $(addprefix deploy-,$(TARGETS)) $(addprefix deploy-dry-,$(TARGETS)) \\
+  $(addprefix tag-push-,$(TARGETS))
+
+deploy:
+\t@echo "Deployment is per-target — pick one (each upload is irreversible):"
+\t@echo "  make deploy-<target>    targets: $(TARGETS)"
+\t@echo "Registry state is set in the model (.sdk/model/target/<t>.jsonic):"
+${targets.map((t: any) => {
+    const reg = registryOf(t)
+    const state = reg ? `${reg.name} ${regIsActive(reg) ? 'ACTIVE' : 'publish pending (deploy = git tag only)'}` : 'tag-only'
+    return `\t@echo "  deploy-${t.name.padEnd(8)} ${state}"`
+  }).join('\n')}
+\t@echo "Rehearse everything safely first: make deploy-dry"
+
+deploy-dry: $(addprefix deploy-dry-,$(TARGETS))
+\t@echo "deploy-dry: all targets rehearsed OK ($(TARGETS))"
+${deployRules}`
+}
+
+
+
+// The root-level tag creation + push recipe for a target: aql --dry-run
+// filler cooperation, idempotent tag creation, token-authenticated https
+// push (works from an ssh-remote clone without ssh keys).
+function tagPushRecipe(name: string, note: string): string {
+  return `
+tag-push-${name}:
+\t@set -e; tag="${name}/v$(VERSION)"; \\
+\ttoken="\$\${GITHUB_TOKEN:-$$GH_TOKEN}"; \\
+\tif [ "$$token" = "$(AQL_DRY_RUN_FILLER)" ]; then \\
+\t  echo "[dry-run] aql filler token detected: would create (if missing) and push tag $$tag; nothing pushed."; exit 0; fi; \\
+\tif [ -z "$$token" ]; then echo "tag-push-${name}: no GITHUB_TOKEN in env — run via make deploy-${name} (aql vault exec)"; exit 1; fi; \\
+\tif git rev-parse -q --verify "refs/tags/$$tag" >/dev/null; then \\
+\t  echo "tag $$tag already exists — pushing existing tag"; \\
+\telse git tag -a "$$tag" -m "Release $$tag"; fi; \\
+\turl=$$(git remote get-url origin | sed -E 's#^git@github.com:#https://github.com/#'); \\
+\thdr="AUTHORIZATION: basic $$(printf 'x-access-token:%s' "$$token" | base64 | tr -d '\\n')"; \\
+\tgit -c http.extraheader="$$hdr" push "$$url" "$$tag"; \\
+\techo "pushed $$tag (${note})"`
+}
+
+export {
+  Deploy
+}

package/src/cmp/FeatureHook.ts

@@ -1,5 +1,5 @@
 
-import { each, cmp, names, Content } from 'jostraca'
+import { each, cmp } from 'jostraca'
 
 import {
   KIT,
@@ -12,14 +12,12 @@ const FeatureHook = cmp(function FeatureHook(props: any, children: any) {
 
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
-  const hook: any = {}
-  names(hook, props.name)
-
-  // TODO: much better error reporting for invalid feature hook names
+  // A feature need not implement every pipeline stage; only fire the hook
+  // for features that declare it as active. Optional chaining guards
+  // features whose `hook` map omits this stage entirely.
   each(feature)
-    // .map(feature => (console.log(props.name, feature), feature))
-    .filter(feature => feature.active && feature.hook[props.name].active)
-    .map(feature => each(children, { call: true, args: feature }))
+    .filter(feature => feature.active && feature.hook?.[props.name]?.active)
+    .forEach(feature => each(children, { call: true, args: feature }))
 })
 
 

package/src/cmp/License.ts

@@ -0,0 +1,49 @@
+import { cmp, Content, File } from 'jostraca'
+
+import { PUBLISHER, nonAffiliation } from '../helpers/packageMeta'
+
+
+// Root MIT LICENSE for the generated SDK repo. The copyright holder is the
+// PUBLISHER (Voxgig): this is an unofficial, generated SDK, so it is NOT
+// attributed to the upstream API owner. A non-affiliation note is appended so
+// the license file itself carries the disclosure.
+const License = cmp(function License(props: any) {
+  const { ctx$ } = props
+  const { model } = ctx$
+
+  const year = (model.const && model.const.year) || new Date().getFullYear()
+
+  File({ name: 'LICENSE' }, () => {
+    Content(`MIT License
+
+Copyright (c) ${year} ${PUBLISHER}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+${nonAffiliation(model)}
+`)
+  })
+})
+
+
+export {
+  License
+}

package/src/cmp/Readme.ts

@@ -5,6 +5,7 @@ import { cmp, File, Content } from 'jostraca'
 import { ReadmeIntro } from './ReadmeIntro'
 import { ReadmeInstall } from './ReadmeInstall'
 import { ReadmeQuick } from './ReadmeQuick'
+import { ReadmeErrors } from './ReadmeErrors'
 import { ReadmeModel } from './ReadmeModel'
 import { ReadmeOptions } from './ReadmeOptions'
 import { ReadmeEntity } from './ReadmeEntity'
@@ -22,6 +23,7 @@ const Readme = cmp(function Readme(props: any) {
     ReadmeIntro({ target })
     ReadmeInstall({ target })
     ReadmeQuick({ target })
+    ReadmeErrors({ target })
     ReadmeHowto({ target })
     ReadmeModel({ target })
     ReadmeOptions({ target })

package/src/cmp/ReadmeErrors.ts

@@ -0,0 +1,257 @@
+
+import { cmp, Content } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
+import { entityIdField, entityPrimaryOp } from '../helpers/opShape'
+import { primaryOpCall } from '../helpers/opExample'
+import type { ExampleLang, PrimaryCall } from '../helpers/opExample'
+import { safeVarName } from '../helpers/naming'
+
+
+// Error handling is one of the everyday developer tasks, so it gets its
+// own user-facing section rather than being buried in the pipeline
+// explanation. The convention differs by language in two ways:
+//
+//   1. Entity operations (load/list/create/update/remove) either THROW
+//      (ts, js, py, php, rb) or return an error value (go, lua).
+//   2. The low-level `direct()`/`prepare()` escape hatch does NOT always
+//      follow the entity-op convention. In go/lua it returns (value, err);
+//      in ts/js it returns the value or an `Error`; in py/php/rb it returns
+//      the result envelope — branch on `ok`, and read `err` on failure.
+//
+// The entity-op snippet is rendered from the entity's PRIMARY op (never a
+// hardcoded `load`, which a create-only entity lacks) with a type-correct
+// match id (a numeric id renders `1`, not "example_id"). Targets not listed
+// here (ts, js) use DEFAULT_LANG.
+type LangErrors = {
+  // prose + snippet for the entity-op convention, given the pre-rendered
+  // primary-op invocation and its op name.
+  entity: (call: PrimaryCall, op: string) => string
+  // prose + snippet for the direct()/prepare() convention
+  direct: string
+}
+
+
+const DEFAULT_LANG: LangErrors = {
+  entity: (call, op) => `Entity operations reject on failure, so wrap them in \`try\` / \`catch\`:
+
+\`\`\`ts
+try {
+  const ${call.resultVar} = await ${call.expr}
+  console.log(${call.resultVar})
+} catch (err) {
+  console.error('${op} failed:', err)
+}
+\`\`\`
+
+`,
+  direct: `The low-level \`direct()\` method does **not** throw — it returns the
+value or an \`Error\`, so check the result before using it:
+
+\`\`\`ts
+const result = await client.direct({
+  path: '/api/resource/{id}',
+  method: 'GET',
+  params: { id: 'example_id' },
+})
+
+if (result instanceof Error) {
+  throw result
+}
+\`\`\`
+
+`,
+}
+
+
+const LANGS: Record<string, LangErrors> = {
+  py: {
+    entity: (call, op) => `Entity operations raise on failure, so wrap them in \`try\` / \`except\`:
+
+\`\`\`python
+try:
+    ${call.resultVar} = ${call.expr}
+    print(${call.resultVar})
+except Exception as err:
+    print(f"${op} failed: {err}")
+\`\`\`
+
+`,
+    direct: `\`direct()\` does **not** raise — it returns the result envelope. Branch
+on \`ok\`; on failure \`status\` holds the HTTP status (for error responses)
+and \`err\` holds a transport error, so read both defensively:
+
+\`\`\`python
+result = client.direct({
+    "path": "/api/resource/{id}",
+    "method": "GET",
+    "params": {"id": "example_id"},
+})
+
+if not result["ok"]:
+    print("request failed:", result.get("status"), result.get("err"))
+\`\`\`
+
+`,
+  },
+
+  php: {
+    entity: (call, op) => `Entity operations throw a \`\\Throwable\` on failure, so wrap them in
+\`try\` / \`catch\`:
+
+\`\`\`php
+try {
+    $${call.resultVar} = ${call.expr};
+} catch (\\Throwable $err) {
+    echo "Error: " . $err->getMessage();
+}
+\`\`\`
+
+`,
+    direct: `\`direct()\` does **not** throw — it returns the result array. Branch on
+\`ok\`; on failure \`status\` holds the HTTP status (for error responses) and
+\`err\` holds a transport error, so read both defensively:
+
+\`\`\`php
+$result = $client->direct([
+    "path" => "/api/resource/{id}",
+    "method" => "GET",
+    "params" => ["id" => "example_id"],
+]);
+
+if (! $result["ok"]) {
+    $err = $result["err"] ?? null;
+    echo "request failed: " . ($err ? $err->getMessage() : "HTTP " . $result["status"]);
+}
+\`\`\`
+
+`,
+  },
+
+  rb: {
+    entity: (call, op) => `Entity operations raise on failure, so rescue them:
+
+\`\`\`ruby
+begin
+  ${call.resultVar} = ${call.expr}
+rescue => err
+  warn "${op} failed: #{err}"
+end
+\`\`\`
+
+`,
+    direct: `\`direct\` does **not** raise — it returns the result hash. Branch on
+\`ok\`; on failure \`status\` holds the HTTP status (for error responses) and
+\`err\` holds a transport error, so read both defensively:
+
+\`\`\`ruby
+result = client.direct({
+  "path" => "/api/resource/{id}",
+  "method" => "GET",
+  "params" => { "id" => "example_id" },
+})
+
+warn "request failed: #{result["err"] || "HTTP #{result["status"]}"}" unless result["ok"]
+\`\`\`
+
+`,
+  },
+
+  lua: {
+    entity: (call, op) => `Entity operations return \`(value, err)\`. Check \`err\` before using
+the value:
+
+\`\`\`lua
+local ${call.resultVar}, err = ${call.expr}
+if err then error(err) end
+\`\`\`
+
+`,
+    direct: `\`direct\` follows the same \`(value, err)\` convention:
+
+\`\`\`lua
+local result, err = client:direct({
+  path = "/api/resource/{id}",
+  method = "GET",
+  params = { id = "example_id" },
+})
+if err then error(err) end
+\`\`\`
+
+`,
+  },
+
+  go: {
+    entity: (call, op) => `Every entity operation returns \`(value, error)\`. Check \`err\` before
+using the value — there is no exception to catch:
+
+\`\`\`go
+${call.resultVar}, err := ${call.expr}
+if err != nil {
+    // handle err
+    return
+}
+_ = ${call.resultVar}
+\`\`\`
+
+`,
+    direct: `\`Direct\` follows the same \`(value, error)\` convention:
+
+\`\`\`go
+result, err := client.Direct(map[string]any{
+    "path":   "/api/resource/{id}",
+    "method": "GET",
+    "params": map[string]any{"id": "example_id"},
+})
+if err != nil {
+    // handle err
+}
+_ = result
+\`\`\`
+
+`,
+  },
+}
+
+
+const ReadmeErrors = cmp(function ReadmeErrors(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  const lang = LANGS[target.name] || DEFAULT_LANG
+
+  // Derive a real example entity from the model (the same way the sibling
+  // Readme components do) so the snippet never references a phantom entity.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
+  const ex = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
+  const eName = ex ? (ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))) : 'Entity'
+  // Sanitise the variable name against the target's reserved words (a `Delete`
+  // entity must not bind `const delete = ...`).
+  const eLower = safeVarName(eName.toLowerCase(), target.name)
+
+  // The entity's id-like key field name, or null when it has none.
+  const idF = entityIdField(ex)
+  // The entity's PRIMARY op — an op it actually exposes (prefer list/load, else
+  // create/update/remove). A create-only entity therefore never shows a
+  // phantom `.load()`.
+  const primaryOp = entityPrimaryOp(ex) || 'load'
+  const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)
+
+  Content(`
+## Error handling
+
+`)
+
+  Content(lang.entity(call, primaryOp))
+
+  Content(lang.direct)
+})
+
+
+export {
+  ReadmeErrors
+}