@voxgig/build 4.0.0 → 4.2.0

package/env/lambda/srv_yml.ts

@@ -0,0 +1,201 @@
+/* Copyright © 2022-2026 Voxgig Ltd, MIT License. */
+
+// gen/serverless/srv.yml template: one Serverless function definition per
+// lambda-active service, derived from the model.
+
+import Fs from 'fs'
+import Path from 'path'
+
+import { camelify } from '@voxgig/util'
+
+import { CoreConfShape } from '../../shape/conf'
+
+import { generate, empty, TM, loadFragment, renderFragment } from './generate'
+
+
+const srv_yml = async (model: any, spec: {
+  folder: string
+  tm?: string
+}) => {
+
+  const core = CoreConfShape(model.main.conf.core)
+
+  let appname = core.name
+  let AppName = camelify(appname)
+
+  const frag = loadFragment('srv.yml.frag', spec)
+
+  let srv_yml_prefix_path = Path.join(spec.folder, 'srv.prefix.yml')
+  let srv_yml_suffix_path = Path.join(spec.folder, 'srv.suffix.yml')
+
+  let prefixContent = Fs.existsSync(srv_yml_prefix_path) ?
+    Fs.readFileSync(srv_yml_prefix_path) : ''
+  let suffixContent = Fs.existsSync(srv_yml_suffix_path) ?
+    Fs.readFileSync(srv_yml_suffix_path) : ''
+
+  let content =
+
+    prefixContent +
+    Object
+      .entries(model.main.srv)
+      .filter((entry: any) => entry[1].env?.lambda?.active)
+      .map((entry: any) => {
+        const name = entry[0]
+        const srv = entry[1]
+
+        const lambda = srv.env.lambda
+        const handler = lambda.handler
+
+        // NOTE: gen.custom convention: allows for complete overwrite
+        // as a get-out-of-jail
+        if (srv.gen?.custom?.lambda?.srv_yml) {
+          return srv.gen.custom.lambda.srv_yml
+        }
+
+        const web = srv.api.web
+
+        let events = ''
+
+        let onEvents = srv.on
+
+        if (onEvents) {
+          Object.entries(onEvents).forEach((entry: any[]) => {
+            // let name = entry[0]
+            let spec = entry[1]
+
+            if ('aws' === spec.provider) {
+              spec.events.forEach((ev: any) => {
+                if ('s3' === ev.source) {
+                  events += TM(`
+    - s3:
+        bucket: ${ev.bucket}
+        event: ${ev.event}
+        existing: true
+`)
+                  if (ev.rules) {
+                    events += TM(`
+        rules:
+`)
+                    if (ev.rules.prefix) {
+                      events += TM(`
+          - prefix: ${ev.rules.prefix}
+`)
+                    }
+
+                    if (ev.rules.suffix) {
+                      events += TM(`
+          - suffix: ${ev.rules.suffix}
+`)
+                    }
+                  }
+                }
+                else if ('schedule' === ev.source) {
+                  let entries =
+                    'string' === typeof ev.recur ? [ev.recur] : (ev.recur || [])
+                  let recur = entries.map((entry: string) => {
+                    let schedule = `
+    - schedule:
+        rate: ${entry}`
+                    if (ev.msg) {
+                      schedule += `
+        input:
+          msg: ${JSON.stringify(ev.msg)} `
+                    }
+                    return schedule
+                  })
+
+                  events += TM(`
+${recur}
+`)
+
+                }
+                else if ('sqs' === ev.source) {
+                  events += TM(`
+    - sqs:
+        arn:
+          Fn::GetAtt:
+            - ${ev.qrn}
+            - Arn
+        batchSize: 1
+`)
+
+                }
+              })
+            }
+          })
+        }
+
+        // TODO: move to `on`
+        if (web.active) {
+          let prefix = web.path.prefix
+          let suffix = web.path.suffix
+          let area = web.path.area
+          let method = web.method
+          let corsflag = 'false'
+          let corsprops = ''
+
+          let methods = method.split(',')
+          // console.log('METHODS', methods)
+
+          if (web.cors.active) {
+            corsflag = 'true'
+            if (web.cors.props && !empty(web.cors.props)) {
+              corsflag = ''
+              corsprops = Object
+                .entries(web.cors.props)
+                .reduce(((a: any, nv: any) => (
+                  a += `          ${nv[0]}: ${nv[1]}\n`
+                  , a)), '')
+            }
+          }
+
+          if ('v2' === web.lambda?.gateway) {
+            for (let method of methods) {
+              events += TM(`
+    - httpApi:
+        path: "${prefix}${area}${name}${suffix}"
+        method: ${method}
+`)
+            }
+          }
+          else {
+            for (let method of methods) {
+              events += TM(`
+    - http:
+        path: "${prefix}${area}${name}${suffix}"
+        method: ${method}
+        cors: ${corsflag}
+${corsprops}
+`)
+            }
+          }
+        }
+
+
+
+        let eventsBlock = ''
+        if ('' !== events) {
+          eventsBlock = TM(`
+  events:
+${events}
+`)
+        }
+
+        return renderFragment(frag, {
+          name,
+          handler: handler.path.prefix + name + handler.path.suffix,
+          AppName,
+          timeout: lambda.timeout,
+          memory: lambda.memory || 1024,
+          events: eventsBlock,
+        })
+      }).join('\n\n\n') +
+    suffixContent
+
+  await generate(spec.folder, [{ name: 'srv.yml', content }])
+}
+
+
+export {
+  srv_yml,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/build",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "main": "dist/build.js",
   "type": "commonjs",
   "types": "dist/build.d.ts",
@@ -18,7 +18,7 @@
     "url": "git://github.com/voxgig/build.git"
   },
   "scripts": {
-    "model-s01": "voxgig-model test/s01/model/model.jsonic",
+    "model-s01": "voxgig-model test/s01/model/model.aontu",
     "test": "jest --coverage",
     "test-some": "jest -t",
     "test-watch": "jest --coverage --watchAll",
@@ -42,7 +42,9 @@
     "lib",
     "dist",
     "bin",
-    "LICENSE"
+    "LICENSE",
+    "tm",
+    "env"
   ],
   "dependencies": {
     "@voxgig/util": "0.5.4",
@@ -54,7 +56,7 @@
     "@types/jest": "^29.5.12",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "26.1.2",
-    "@voxgig/model": "^2.1.0",
+    "@voxgig/model": "^9.2.4",
     "@voxgig/system": "^1.2.0",
     "esbuild": "^0.23.0",
     "jest": "^29.7.0",

package/tm/env/aws/README.md.frag

@@ -0,0 +1,9 @@
+# $$Name$$ - aws environment (Serverless Framework)
+
+    cd backend && npm run build
+    cd gen/env/aws && npx serverless deploy --stage $$stage$$
+
+serverless.yml composes the generated srv.yml (functions) and res.yml
+(resources); both are regenerated by model-build. Provider settings
+(region/stage/runtime) come from the model env entry - change them with
+the model, or eject env/aws/serverless.yml.frag for structural edits.

package/tm/env/aws/lambda.entry.ts.frag

@@ -0,0 +1,89 @@
+
+// $$Name$$ backend - AWS Lambda environment bootstrap (generated once;
+// this file is yours to edit). The generated handlers
+// (src/handler/lambda/<srv>.ts) call getSeneca() for a ready Seneca
+// instance wired for the Lambda + API Gateway path, configured by the
+// shared setup (src/env/shared/basic.ts).
+
+import Seneca from 'seneca'
+import { Live } from '@voxgig/system'
+
+import { basic, base } from '../shared/basic'
+
+import Pkg from '../../../package.json'
+import Model from '../../../model/model.json'
+
+
+const STAGE = process.env.STAGE || 'local'
+
+const Main = Model.main as any
+
+let seneca: any = null
+
+
+async function getSeneca(srvname: string, complete: Function): Promise<any> {
+  const { deep } = Seneca.util
+
+  if (null == seneca) {
+    const srv = Main.srv[srvname]
+
+    seneca = Seneca(deep(base.seneca, {
+      tag: srvname + '-$$name$$-' + STAGE + '@' + Pkg.version,
+      timeout: srv.env.lambda.timeout * 60 * 1000,
+    })).test()
+
+    seneca.context.model = Model
+    seneca.context.srvname = srvname
+    seneca.context.stage = STAGE
+    seneca.context.env = 'lambda'
+    seneca.context.pkg = Pkg
+
+    basic(seneca, { reload: { active: false } })
+
+    seneca
+      .use('gateway')
+      .use('gateway-lambda', {
+        auth: {
+          token: {
+            name: '$$name$$-auth',
+          },
+        },
+      })
+      .use('gateway-auth', {
+        spec: {
+          lambda_cookie: {
+            active: true,
+            token: {
+              name: '$$name$$-auth',
+            },
+            user: {
+              auth: true,
+              require: srv.user?.required ?? true,
+            },
+          },
+        },
+      })
+
+    seneca.use(Live, {
+      srv: {
+        name: srvname,
+        folder: __dirname + '/../../srv',
+      },
+    })
+
+    // Call ready() exactly once - a second ready() on an already-ready
+    // instance never resolves under seneca 4.0.0-rc4.
+    await seneca.ready()
+
+    if (complete) {
+      await complete(seneca)
+    }
+  }
+
+  return seneca
+}
+
+
+export {
+  getSeneca,
+}

package/tm/env/aws/serverless.yml.frag

@@ -0,0 +1,23 @@
+# $$Name$$ backend - Serverless Framework config (generated; customize via
+# tm/env/aws/). Composes the model-generated pieces: per-service function
+# definitions (srv.yml) and resources (res.yml) live beside this file and
+# are regenerated by model-build - edit the model, not those files.
+service: $$name$$-backend
+
+frameworkVersion: '4'
+
+provider:
+  name: aws
+  runtime: nodejs$$node$$.x
+  region: $$region$$
+  stage: ${opt:stage, '$$stage$$'}
+
+custom:
+  # res.yml derives the IAM role name suffix from this index.
+  index:
+    BasicLambdaRole: '01'
+
+functions: ${file(./srv.yml)}
+
+resources:
+  Resources: ${file(./res.yml)}

package/tm/env/azure/README.md.frag

@@ -0,0 +1,7 @@
+# $$Name$$ - azure environment (starting point)
+
+Azure Functions host config for the $$Name$$ backend. This is a starting
+point: Azure needs one function.json binding per exposed function - derive
+them from the service definitions the model generates for aws
+(gen/env/aws/srv.yml lists every handler and route). Eject
+env/azure/host.json.frag to customize.

package/tm/env/azure/entry.ts.frag

@@ -0,0 +1,49 @@
+
+// $$Name$$ backend - azure environment entry (generated once; this file is
+// yours to edit). STARTING POINT: an Azure Functions HTTP handler shape -
+// wire the Seneca gateway the way src/env/lambda/lambda.ts does for AWS.
+
+import Seneca from 'seneca'
+
+import { basic, base } from '../shared/basic'
+
+import Pkg from '../../../package.json'
+import Model from '../../../model/model.json'
+
+
+let seneca: any = null
+
+async function getSeneca(): Promise<any> {
+  if (null == seneca) {
+    seneca = Seneca(Seneca.util.deep(base.seneca, {
+      tag: '$$name$$-azure@' + Pkg.version,
+    })).test()
+
+    seneca.context.model = Model
+    seneca.context.env = 'azure'
+    seneca.context.pkg = Pkg
+
+    basic(seneca, { reload: { active: false } })
+
+    await seneca.ready()
+  }
+  return seneca
+}
+
+
+// Azure Functions v4 programming model handler (add @azure/functions and
+// register per-route handlers derived from the model - see
+// gen/env/aws/srv.yml for the full route list).
+async function handler(request: any, _context: any) {
+  await getSeneca()
+  return {
+    status: 501,
+    jsonBody: { ok: false, why: '$$name$$-backend azure entry not yet wired' },
+  }
+}
+
+
+export {
+  getSeneca,
+  handler,
+}

package/tm/env/azure/host.json.frag

@@ -0,0 +1,8 @@
+{
+  "version": "2.0",
+  "logging": {
+    "applicationInsights": {
+      "samplingSettings": { "isEnabled": true }
+    }
+  }
+}

package/tm/env/basic/README.md.frag

@@ -0,0 +1,7 @@
+# $$Name$$ - basic environment (remote server)
+
+Runs the backend like local, on a plain server under systemd.
+
+    BASIC_HOST=user@host sh gen/env/basic/deploy.sh
+
+Installs to /opt/$$name$$/backend with unit $$name$$-backend.service.

package/tm/env/basic/backend.service.frag

@@ -0,0 +1,14 @@
+# systemd unit for the $$Name$$ backend (generated; customize via tm/env/basic/)
+[Unit]
+Description=$$Name$$ backend
+After=network.target
+
+[Service]
+WorkingDirectory=/opt/$$name$$/backend
+ExecStart=/usr/bin/node dist/env/local/local.js
+Restart=always
+Environment=NODE_ENV=production
+Environment=PORT=$$port$$
+
+[Install]
+WantedBy=multi-user.target

package/tm/env/basic/deploy.sh.frag

@@ -0,0 +1,13 @@
+#!/bin/sh
+# Deploy the $$Name$$ backend to a plain remote server (generated).
+# Usage: BASIC_HOST=user@host sh deploy.sh
+set -e
+: "${BASIC_HOST:?set BASIC_HOST=user@host}"
+cd "$(dirname "$0")/../../.."
+npm run build
+rsync -az --delete \
+  --exclude node_modules --exclude gen --exclude dist-test \
+  ./ "$BASIC_HOST:/opt/$$name$$/backend/"
+ssh "$BASIC_HOST" "cd /opt/$$name$$/backend && npm install --omit=dev \
+  && sudo cp gen/env/basic/$$name$$-backend.service /etc/systemd/system/ \
+  && sudo systemctl daemon-reload && sudo systemctl restart $$name$$-backend"

package/tm/env/cloudflare/README.md.frag

@@ -0,0 +1,7 @@
+# $$Name$$ - cloudflare environment (starting point)
+
+    cd gen/env/cloudflare && npx wrangler deploy
+
+The worker entry (src/env/cloudflare/worker.ts - yours to edit, wrangler
+bundles the TS directly) is a 501 stub: wire the Seneca gateway into the
+fetch handler (src/env/lambda/lambda.ts is the AWS model to follow).

package/tm/env/cloudflare/worker.ts.frag

@@ -0,0 +1,13 @@
+// $$Name$$ backend - Cloudflare Worker entry (generated once; this file is
+// yours to edit). STARTING POINT: Workers use a fetch handler rather than
+// a long-lived process - adapt the gateway wiring (src/env/lambda/lambda.ts
+// is the AWS equivalent) to route requests into Seneca here.
+
+export default {
+  async fetch(_request: Request, _env: unknown, _ctx: unknown) {
+    return new Response(JSON.stringify({
+      ok: false,
+      why: '$$name$$-backend worker entry not yet wired',
+    }), { status: 501, headers: { 'content-type': 'application/json' } })
+  },
+}

package/tm/env/cloudflare/wrangler.toml.frag

@@ -0,0 +1,7 @@
+# $$Name$$ backend - Cloudflare Workers config (generated; starting point)
+name = "$$name$$-backend"
+main = "../../../src/env/cloudflare/worker.ts"
+compatibility_date = "2026-01-01"
+
+[vars]
+NODE_ENV = "production"

package/tm/env/docker/Dockerfile.frag

@@ -0,0 +1,10 @@
+# $$Name$$ backend image (generated; customize via tm/env/docker/)
+FROM node:$$node$$-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY model/model.json model/model.json
+COPY dist/ dist/
+ENV NODE_ENV=production
+EXPOSE $$port$$
+CMD ["node", "dist/env/local/local.js"]

package/tm/env/docker/README.md.frag

@@ -0,0 +1,7 @@
+# $$Name$$ - docker environment
+
+    cd backend && npm run build
+    docker compose -f gen/env/docker/compose.yml up --build
+
+Port $$port$$. The image runs the local (in-memory) runner; wire a real
+store before production use.

package/tm/env/docker/compose.yml.frag

@@ -0,0 +1,10 @@
+# $$Name$$ backend - docker compose (generated; customize via tm/env/docker/)
+services:
+  $$name$$-backend:
+    build:
+      context: ../../..
+      dockerfile: gen/env/docker/Dockerfile
+    ports:
+      - "$$port$$:$$port$$"
+    environment:
+      NODE_ENV: production

package/tm/env/local/README.md.frag

@@ -0,0 +1,7 @@
+# $$Name$$ - local environment
+
+Runs the backend in-process with the in-memory store:
+
+    sh gen/env/local/run.sh    # or: cd backend && npm run local
+
+Port: $$port$$. No external services required.

package/tm/env/local/run.sh.frag

@@ -0,0 +1,6 @@
+#!/bin/sh
+# $$Name$$ backend - local run (generated; customize via tm/env/local/)
+# In-process Seneca instance, in-memory store, port $$port$$.
+cd "$(dirname "$0")/../../.."
+export NODE_ENV=development
+exec npm run local

package/tm/env/server.entry.ts.frag

@@ -0,0 +1,48 @@
+
+// $$Name$$ backend - $$env$$ environment entry (generated once; this file
+// is yours to edit). A long-lived server process using the shared Seneca
+// setup (src/env/shared/basic.ts); reads its env config from the model
+// (main.env.$$env$$).
+
+import Seneca from 'seneca'
+import { Local } from '@voxgig/system'
+
+import { basic, base } from '../shared/basic'
+
+import Pkg from '../../../package.json'
+import Model from '../../../model/model.json'
+
+
+run()
+
+
+async function run() {
+  const { deep } = Seneca.util
+
+  const envdef: any = (Model as any).main.env?.['$$env$$'] || {}
+
+  const seneca = Seneca(deep(base.seneca, {
+    tag: '$$name$$-$$env$$',
+    log: { level: envdef.log || 'warn' },
+  }, envdef.seneca || {}))
+
+  seneca.context.model = Model
+  seneca.context.env = '$$env$$'
+  seneca.context.stage = process.env.STAGE || '$$env$$'
+  seneca.context.srvname = 'all'
+  seneca.context.pkg = Pkg
+
+  basic(seneca)
+
+  seneca.use(Local, {
+    srv: {
+      folder: __dirname + '/../../../dist/srv',
+    },
+  })
+
+  await seneca.ready()
+
+  console.log('$$name$$-backend started', {
+    env: '$$env$$', version: Pkg.version, port: $$port$$,
+  })
+}

package/tm/env/vm/README.md.frag

@@ -0,0 +1,5 @@
+# $$Name$$ - vm environment
+
+Boot any cloud VM with gen/env/vm/cloud-init.yaml as user-data, then push
+code with the basic deploy script (BASIC_HOST=user@vm sh
+gen/env/basic/deploy.sh) or your own pipeline.

package/tm/env/vm/cloud-init.yaml.frag

@@ -0,0 +1,23 @@
+#cloud-config
+# $$Name$$ backend VM bootstrap (generated; customize via tm/env/vm/)
+packages:
+  - nodejs
+  - npm
+  - rsync
+write_files:
+  - path: /etc/systemd/system/$$name$$-backend.service
+    content: |
+      [Unit]
+      Description=$$Name$$ backend
+      After=network.target
+      [Service]
+      WorkingDirectory=/opt/$$name$$/backend
+      ExecStart=/usr/bin/node dist/env/local/local.js
+      Restart=always
+      Environment=NODE_ENV=production
+      [Install]
+      WantedBy=multi-user.target
+runcmd:
+  - mkdir -p /opt/$$name$$/backend
+  - systemctl daemon-reload
+  - systemctl enable $$name$$-backend

package/tm/lambda/res.queue.yml.frag

@@ -0,0 +1,6 @@
+$$resname$$:
+  Type: "AWS::SQS::Queue"
+  Properties:
+    QueueName: '$$queueName$$'
+    VisibilityTimeout: $$queueTimeout$$
+

package/tm/lambda/res.role.yml.frag

@@ -0,0 +1,35 @@
+
+Basic$$AppName$$LambdaRole:
+  Type: AWS::IAM::Role
+  Properties:
+    RoleName: Basic$$AppName$$LambdaRole${self:custom.index.BasicLambdaRole,"01"}
+    AssumeRolePolicyDocument:
+      Version: '2012-10-17'
+      Statement:
+        - Effect: Allow
+          Principal:
+            Service:
+              - lambda.amazonaws.com
+              - events.amazonaws.com
+              - ecs-tasks.amazonaws.com
+          Action: sts:AssumeRole
+    Policies:
+      - PolicyName: LambdaServiceAccess
+        PolicyDocument:
+          Version: '2012-10-17'
+          Statement:
+            - Effect: Allow
+              Action:
+                - dynamodb:DescribeTable
+                - dynamodb:GetItem
+                - dynamodb:PutItem
+                - dynamodb:UpdateItem
+                - dynamodb:DeleteItem
+                - dynamodb:Query
+                - dynamodb:Scan
+              Resource: 
+$$dynamoArns$$
+$$customPolicy$$
+    ManagedPolicyArns:
+      - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
+

package/tm/lambda/srv.yml.frag

@@ -0,0 +1,6 @@
+$$name$$:
+  handler: $$handler$$
+  role: Basic$$AppName$$LambdaRole
+  timeout: $$timeout$$
+  memorySize: $$memory$$
+$$events$$