@ultimat3/cli 3.0.0 → 4.0.0

package/src/templates/scaffold-helm-templates.ts

@@ -0,0 +1,327 @@
+// The Kubernetes objects the scaffolded chart renders: one Deployment and one Service per enabled
+// role, the release-phase Job, an optional ingress and an optional per-role autoscaler.
+// Split from scaffold-helm.ts, which holds the chart's INPUTS (Chart.yaml, values.yaml).
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const helpers = (
+  app: NameSet,
+): string => `{{/* Shared naming and the one container spec every role renders. */}}
+
+{{- define "${app.kebab}.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{- define "${app.kebab}.fullname" -}}
+{{- printf "%s-%s" .Release.Name (include "${app.kebab}.name" .) | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{/*
+repository:tag, and NOT a single "image" string: x deploy --method helm passes
+--set image.repository=... --set image.tag=..., because replacing the map with a string makes
+every workload below fail on .repository and deploy nothing.
+*/}}
+{{- define "${app.kebab}.image" -}}
+{{- printf "%s:%s" .Values.image.repository (default .Chart.AppVersion .Values.image.tag) -}}
+{{- end -}}
+
+{{- define "${app.kebab}.labels" -}}
+app.kubernetes.io/name: {{ include "${app.kebab}.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+app.kubernetes.io/version: {{ default .Chart.AppVersion .Values.image.tag | quote }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end -}}
+
+{{/*
+The container spec for a role. ROLE is the only thing that varies, exactly as in
+docker-compose.prod.yml: one image, one entry point, N processes.
+
+migrate is the one role that opens no socket at all — it applies migrations and exits — so it
+declares no port and no scrape target.
+*/}}
+{{- define "${app.kebab}.container" -}}
+{{- $role := .role -}}
+{{- $cfg := .cfg -}}
+{{- $root := .root -}}
+{{- $scraped := ne $role "migrate" -}}
+{{/*
+roles.<role>.port is the port the role LISTENS on — the one number a Service, an ingress backend
+and two probes can all use. PORT is a different number for exactly one role: the sync node binds
+PORT + 1, so a sync container told PORT=3001 opens 3002 and the readiness probe polls a socket
+nobody bound. Derived here rather than stated twice in values.yaml, where the two would drift.
+*/}}
+{{- $envPort := $cfg.port -}}
+{{- if and $cfg.port (eq $role "sync") -}}
+{{- $envPort = sub (int $cfg.port) 1 -}}
+{{- end -}}
+- name: {{ $role }}
+  image: {{ include "${app.kebab}.image" $root }}
+  imagePullPolicy: {{ $root.Values.image.pullPolicy }}
+  securityContext: {{- toYaml $root.Values.securityContext | nindent 4 }}
+  env:
+    - name: ROLE
+      value: {{ $role | quote }}
+    {{- if $cfg.port }}
+    - name: PORT
+      value: {{ $envPort | quote }}
+    {{- end }}
+    {{- if $scraped }}
+    - name: METRICS_PORT
+      value: {{ $root.Values.metricsPort | quote }}
+    {{- end }}
+    {{- range $key, $value := $root.Values.env }}
+    - name: {{ $key }}
+      value: {{ $value | quote }}
+    {{- end }}
+  envFrom:
+    - secretRef:
+        name: {{ $root.Values.existingSecret }}
+  {{- if or $cfg.port $scraped }}
+  ports:
+    {{- if $cfg.port }}
+    - name: http
+      containerPort: {{ $cfg.port }}
+    {{- end }}
+    {{- if $scraped }}
+    - name: metrics
+      containerPort: {{ $root.Values.metricsPort | int }}
+    {{- end }}
+  {{- end }}
+  {{/*
+  Probes follow the role, because the roles do not agree on what they open. web and sync serve
+  HTTP and get both. worker, scheduler and replicator open no HTTP socket at all — the scrape
+  listener is their only port — so they take liveness on it and NO readiness: nothing routes to
+  them, and a readiness flap would drop the pod out of the Service and so out of the scrape.
+  */}}
+  {{- if $cfg.port }}
+  readinessProbe:
+    httpGet: { path: /readyz, port: http }
+    periodSeconds: 5
+  livenessProbe:
+    httpGet: { path: /healthz, port: http }
+    periodSeconds: 15
+  {{- else if $scraped }}
+  livenessProbe:
+    httpGet: { path: /metrics, port: metrics }
+    periodSeconds: 15
+    failureThreshold: 4
+  {{- end }}
+  resources: {{- toYaml $cfg.resources | nindent 4 }}
+  volumeMounts:
+    - name: tmp
+      mountPath: /tmp
+{{- end -}}
+`;
+
+const deployments = (app: NameSet): string => `{{/*
+One Deployment per enabled role, from one image. terminationGracePeriodSeconds matches the
+framework's SIGTERM drain: in-flight requests, open websockets and running job steps finish.
+*/}}
+{{- range $role, $cfg := .Values.roles }}
+{{- if $cfg.enabled }}
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "${app.kebab}.fullname" $ }}-{{ $role }}
+  labels:
+    {{- include "${app.kebab}.labels" $ | nindent 4 }}
+    app.kubernetes.io/component: {{ $role }}
+spec:
+  {{/* Ask whether the block EXISTS before reading through it: scheduler and replicator declare
+  none, and without the guard the whole chart fails to render. */}}
+  {{- if not (and $cfg.autoscaling $cfg.autoscaling.enabled) }}
+  replicas: {{ $cfg.replicas }}
+  {{- end }}
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ $.Release.Name }}
+      app.kubernetes.io/component: {{ $role }}
+  strategy:
+    type: RollingUpdate
+    rollingUpdate: { maxUnavailable: 0, maxSurge: 1 }
+  template:
+    metadata:
+      labels:
+        {{- include "${app.kebab}.labels" $ | nindent 8 }}
+        app.kubernetes.io/component: {{ $role }}
+    spec:
+      {{/* No role in this image calls the Kubernetes API — ROLE comes from the env and everything
+      else from app.config.ts. Mounting the token anyway hands a JWT for this namespace to any
+      code that reaches the filesystem, which for a web role is one path traversal. */}}
+      automountServiceAccountToken: false
+      securityContext: {{- toYaml $.Values.podSecurityContext | nindent 8 }}
+      {{/* At least the framework's drain deadline (25s by default), which is what
+      X_SHUTDOWN_TIMEOUT's fix line tells an operator. Raise this WITH configureLifecycle({
+      deadlineMs }), never instead of it: the drain abandons its hooks at its own deadline. */}}
+      terminationGracePeriodSeconds: 45
+      containers:
+        {{- include "${app.kebab}.container" (dict "role" $role "cfg" $cfg "root" $) | nindent 8 }}
+      volumes:
+        - name: tmp
+          emptyDir: {}
+{{- end }}
+{{- end }}
+`;
+
+const service = (app: NameSet): string => `{{/*
+One Service per enabled role. The roles that take no traffic still get one, HEADLESS: it exists so
+a scrape target and a DNS name exist, and a headless Service allocates no ClusterIP, so nothing
+about it invites traffic it would not answer.
+*/}}
+{{- range $role, $cfg := .Values.roles }}
+{{- if $cfg.enabled }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "${app.kebab}.fullname" $ }}-{{ $role }}
+  labels:
+    {{- include "${app.kebab}.labels" $ | nindent 4 }}
+    app.kubernetes.io/component: {{ $role }}
+spec:
+  type: ClusterIP
+  {{- if not $cfg.port }}
+  clusterIP: None
+  {{- end }}
+  selector:
+    app.kubernetes.io/instance: {{ $.Release.Name }}
+    app.kubernetes.io/component: {{ $role }}
+  ports:
+    {{- if $cfg.port }}
+    - name: http
+      port: 80
+      targetPort: http
+    {{- end }}
+    - name: metrics
+      port: {{ $.Values.metricsPort | int }}
+      targetPort: metrics
+{{- end }}
+{{- end }}
+`;
+
+const migrateJob = (app: NameSet): string => `{{/*
+The release phase, as a pre-install / pre-upgrade hook: ROLE=migrate applies every pending
+migration under an advisory lock and exits, before any serving role starts. Same image, same entry
+point — there is no second migration engine and no toolchain in the container.
+*/}}
+{{- if .Values.migrate.enabled }}
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: {{ include "${app.kebab}.fullname" . }}-migrate
+  labels:
+    {{- include "${app.kebab}.labels" . | nindent 4 }}
+    app.kubernetes.io/component: migrate
+  annotations:
+    helm.sh/hook: pre-install,pre-upgrade
+    helm.sh/hook-weight: "-5"
+    helm.sh/hook-delete-policy: before-hook-creation
+spec:
+  backoffLimit: {{ .Values.migrate.backoffLimit }}
+  template:
+    metadata:
+      labels:
+        {{- include "${app.kebab}.labels" . | nindent 8 }}
+        app.kubernetes.io/component: migrate
+    spec:
+      restartPolicy: Never
+      automountServiceAccountToken: false
+      securityContext: {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+        {{- include "${app.kebab}.container" (dict "role" "migrate" "cfg" .Values.migrate "root" .) | nindent 8 }}
+      volumes:
+        - name: tmp
+          emptyDir: {}
+{{- end }}
+`;
+
+const ingress = (
+  app: NameSet,
+): string => `{{/* Standard ingress, no vendor edge primitives. Off by default: the host is yours to name. */}}
+{{- if .Values.ingress.enabled }}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ include "${app.kebab}.fullname" . }}
+  labels:
+    {{- include "${app.kebab}.labels" . | nindent 4 }}
+spec:
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- if .Values.ingress.tls }}
+  tls:
+    - hosts: [{{ .Values.ingress.host | quote }}]
+      secretName: {{ include "${app.kebab}.fullname" . }}-tls
+  {{- end }}
+  rules:
+    - host: {{ .Values.ingress.host | quote }}
+      http:
+        paths:
+          {{- /* The path the sync node actually serves. Routing /_sync instead sends every
+          websocket to the web role, which answers no upgrade. */}}
+          - path: /_x/sync
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ include "${app.kebab}.fullname" . }}-sync
+                port: { name: http }
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ include "${app.kebab}.fullname" . }}-web
+                port: { name: http }
+{{- end }}
+`;
+
+const hpa = (app: NameSet): string => `{{/*
+Per-role autoscalers, off until you turn one on. Each role scales on the signal that predicts ITS
+saturation — CPU is a lagging proxy for all three and scales the wrong thing at the wrong time.
+A Pods metric needs a metrics adapter in the cluster; without one the HPA reads <unknown> and
+holds at minReplicas, which is why these are opt-in rather than a default nobody wired.
+*/}}
+{{- range $role, $cfg := .Values.roles }}
+{{- if and $cfg.enabled $cfg.autoscaling $cfg.autoscaling.enabled }}
+---
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ include "${app.kebab}.fullname" $ }}-{{ $role }}
+  labels:
+    {{- include "${app.kebab}.labels" $ | nindent 4 }}
+    app.kubernetes.io/component: {{ $role }}
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ include "${app.kebab}.fullname" $ }}-{{ $role }}
+  minReplicas: {{ $cfg.autoscaling.minReplicas }}
+  maxReplicas: {{ $cfg.autoscaling.maxReplicas }}
+  metrics:
+    - type: Pods
+      pods:
+        metric:
+          name: {{ $cfg.autoscaling.metric }}
+        target:
+          type: AverageValue
+          averageValue: {{ $cfg.autoscaling.targetAverageValue | quote }}
+  behavior:
+    scaleUp:
+      stabilizationWindowSeconds: 30
+    scaleDown:
+      stabilizationWindowSeconds: 300
+{{- end }}
+{{- end }}
+`;
+
+/** The chart's `templates/` directory, in the order a reader meets it. */
+export function helmTemplateFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'docker/helm/templates/_helpers.tpl', contents: helpers(app) },
+    { path: 'docker/helm/templates/deployments.yaml', contents: deployments(app) },
+    { path: 'docker/helm/templates/service.yaml', contents: service(app) },
+    { path: 'docker/helm/templates/migrate-job.yaml', contents: migrateJob(app) },
+    { path: 'docker/helm/templates/ingress.yaml', contents: ingress(app) },
+    { path: 'docker/helm/templates/hpa.yaml', contents: hpa(app) },
+  ];
+}

package/src/templates/scaffold-helm.ts

@@ -0,0 +1,144 @@
+// The chart `x deploy --method helm` runs, written by `x new`. The other method's topology file
+// (`docker/docker-compose.prod.yml`) has always been scaffolded; a deploy method whose artifact
+// only exists in a repository the app never had is a command that cannot run.
+//
+// This file is the chart's INPUTS — Chart.yaml and values.yaml. The objects they render are
+// scaffold-helm-templates.ts.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { helmTemplateFiles } from './scaffold-helm-templates';
+
+/**
+ * `appVersion` is the default image tag (`image.tag: ""` below), so it must name a tag that can
+ * exist. `x deploy --image <ref>` overrides both keys, which is the path that actually ships.
+ */
+const chart = (app: NameSet): string => `apiVersion: v2
+name: ${app.kebab}
+description: One image, N roles. Per-role deployments for ${app.kebab}.
+type: application
+version: 0.1.0
+appVersion: "0.1.0"
+kubeVersion: ">=1.27.0-0"
+`;
+
+const values = (
+  app: NameSet,
+): string => `# One image for every role; ROLE is the only difference between the workloads.
+image:
+  repository: ${app.kebab}
+  tag: ""            # defaults to .Chart.AppVersion; x deploy --image sets this and repository
+  pullPolicy: IfNotPresent
+
+# Non-secret configuration. Secrets come from an existing Secret, never from this file:
+#   kubectl create secret generic ${app.kebab}-secrets --from-literal=DATABASE_URL=...
+env:
+  NODE_ENV: production
+
+existingSecret: ${app.kebab}-secrets   # DATABASE_URL, NATS_URL, S3_*, AUTH_SECRET
+
+# The scrape listener every serving role opens, on its own port and never the app's: the ingress
+# routes / to web, so /metrics beside /healthz on 3000 is /metrics on the internet. This is
+# METRICS_PORT in the container; move one and the other follows.
+metricsPort: 9090
+
+podSecurityContext:
+  runAsNonRoot: true
+  runAsUser: 65532
+  seccompProfile: { type: RuntimeDefault }
+
+securityContext:
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities: { drop: [ALL] }
+
+# The release phase. Runs to completion before any serving role starts.
+migrate:
+  enabled: true
+  backoffLimit: 1
+  resources:
+    requests: { cpu: 100m, memory: 128Mi }
+    limits: { memory: 512Mi }
+
+# One entry per role this chart may run. \`port\` is the port the role LISTENS on, not the value of
+# PORT: they differ for sync, which binds PORT + 1, and the chart derives the env from this number
+# so there is only ever one to move.
+#
+# Autoscaling is off until you wire a metrics adapter — each \`metric\` below is a Pods metric the
+# role exports, and an HPA with no adapter behind it reads <unknown> and holds at minReplicas.
+roles:
+  web:
+    enabled: true
+    replicas: 2
+    port: 3000
+    resources:
+      requests: { cpu: 200m, memory: 256Mi }
+      limits: { memory: 512Mi }
+    autoscaling:
+      enabled: false
+      minReplicas: 2
+      maxReplicas: 30
+      metric: rps               # requests per second
+      targetAverageValue: "50"
+
+  sync:
+    enabled: true
+    replicas: 2
+    port: 3001
+    resources:
+      requests: { cpu: 200m, memory: 512Mi }
+      limits: { memory: 1Gi }
+    autoscaling:
+      enabled: false
+      minReplicas: 2
+      maxReplicas: 40
+      metric: connections       # concurrent websockets per pod
+      targetAverageValue: "2000"
+
+  worker:
+    enabled: true
+    replicas: 2
+    resources:
+      requests: { cpu: 200m, memory: 256Mi }
+      limits: { memory: 1Gi }
+    autoscaling:
+      enabled: false
+      minReplicas: 1
+      maxReplicas: 50
+      metric: queue_depth       # jobs waiting, exported by the worker role
+      targetAverageValue: "100"
+
+  scheduler:
+    enabled: true
+    # Fixed 1, and a second replica is safe but pointless: leadership is an expiring row in
+    # x_scheduler_leader, so the extra pod stands by.
+    replicas: 1
+    resources:
+      requests: { cpu: 50m, memory: 128Mi }
+      limits: { memory: 256Mi }
+
+  replicator:
+    enabled: false              # exactly one per database; enable when the change feed is in use
+    replicas: 1
+    resources:
+      requests: { cpu: 100m, memory: 256Mi }
+      limits: { memory: 512Mi }
+
+ingress:
+  enabled: false
+  className: nginx
+  host: ${app.kebab}.example.com
+  tls: true
+`;
+
+/**
+ * The chart for a new app: five kinds of object, all of them core Kubernetes. A ServiceMonitor and
+ * a PodDisruptionBudget are deliberately absent — the first needs a CRD `helm install` fails on
+ * where no Prometheus operator is installed, and both are cluster policy rather than app topology.
+ */
+export function helmFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'docker/helm/Chart.yaml', contents: chart(app) },
+    { path: 'docker/helm/values.yaml', contents: values(app) },
+    ...helmTemplateFiles(app),
+  ];
+}

package/src/templates/scaffold-repo.ts

@@ -120,6 +120,13 @@ const envDeclaration = (): string => `${envSchemaSource()}
  */
 export const env = defineEnv(envSchema);`;
 
+/**
+ * No `installPrompt`. `PwaConfig` declares it, `defineConfig` defaults it, and NO file reads it —
+ * `packages/core/src/config.ts` carries the marker saying so. Scaffolding it wrote a switch with
+ * no wire into every generated app, and the note belongs HERE rather than in the emitted file: an
+ * app author has no use for a comment about a framework key their config does not name. Deleting
+ * the key itself is core's edit; not writing it is this template's half.
+ */
 const appConfig = (
   app: NameSet,
 ): string => `// The one config file. Everything the app needs to boot is here, typed and validated at startup —
@@ -142,7 +149,7 @@ export const config = defineConfig({
   jobs: { driver: 'postgres', queues: ['${app.kebab}-default'], concurrency: 4 },
   // In-process transport by default; set urlEnv and transport: 'nats' to scale past one node.
   realtime: { enabled: true, tier: 'live-queries', transport: 'memory' },
-  pwa: { enabled: true, offline: 'runtime', installPrompt: true },
+  pwa: { enabled: true, offline: 'runtime' },
   ai: { mcp: { expose: true, path: '/mcp' } },
 });
 `;
@@ -189,11 +196,16 @@ const biome = (): string => `{
  * to any root with an `app.config.ts`. Typed as `VerifyStepName`, so a name the gate does not run
  * is a compile error rather than a floor that covers nothing.
  *
- * Four are deliberately absent. `contract`, `live` and `job` have no scaffolded file; `e2e` has
- * one, and it is an `e2eTest` — `test.skip` until the app registers a browser driver, so the step
- * would run zero tests and fail the ratchet on the scaffold's own placeholder. `contract-diff`
- * needs a committed `x.manifest.json`, which `x manifest` writes later. Each joins the list in the
- * commit that makes the app's own gate run it.
+ * Plus `contract`, which every variant now ships a file for — `apps/web/api/health.contract.test.ts`
+ * — and, with the example slice, `live` and `job`: its query is a `liveTest` and its job a
+ * `jobTest`, and both were written into plain `<name>.test.ts` files that the `unit` step ran while
+ * `x test live` and `x test job` answered X_TEST_NO_FILES. This is the commit that makes the app's
+ * own gate run them, which is what the paragraph below always said the condition was.
+ *
+ * Two remain absent. `e2e` has a scaffolded file and it is an `e2eTest` — `test.skip` until the app
+ * registers a browser driver, so the step would run zero tests and fail the ratchet on the
+ * scaffold's own placeholder. `contract-diff` needs a committed `x.manifest.json`, which
+ * `x manifest` writes later. Each joins the list in the commit that makes the app's gate run it.
  */
 const SCAFFOLD_FLOOR: readonly VerifyStepName[] = [
   'typecheck',
@@ -203,13 +215,18 @@ const SCAFFOLD_FLOOR: readonly VerifyStepName[] = [
   'package-shape',
   'errors',
   'unit',
+  'contract',
   'eval',
   'drift',
   'budgets',
   'manifest',
 ];
 
-const verifyFloor = (): string => `${JSON.stringify({ steps: SCAFFOLD_FLOOR }, null, 2)}\n`;
+/** The two suites only the example slice writes a file for — a floor step with no file is red. */
+const EXAMPLE_FLOOR: readonly VerifyStepName[] = ['live', 'job'];
+
+const verifyFloor = (example: boolean): string =>
+  `${JSON.stringify({ steps: example ? [...SCAFFOLD_FLOOR, ...EXAMPLE_FLOOR] : SCAFFOLD_FLOOR }, null, 2)}\n`;
 
 const bunfig = (): string => `[test]
 root = "."
@@ -276,7 +293,7 @@ export function repoFiles(
     { path: 'biome.json', contents: biome() },
     { path: 'bunfig.toml', contents: bunfig() },
     { path: 'app.config.ts', contents: appConfig(app) },
-    { path: VERIFY_FLOOR_FILE, contents: verifyFloor() },
+    { path: VERIFY_FLOOR_FILE, contents: verifyFloor(example) },
     { path: 'types/scss.d.ts', contents: scssTypes() },
     { path: '.gitignore', contents: gitignore() },
     { path: '.env.development', contents: envDevelopment() },