make-app-runtime

Use this skill for Make App runtime and packaging contracts. These rules are intentionally strict because platform image entrypoints and publish artifacts should not vary per POC.

This skill owns project runtime structure, workspace manifests, build outputs, Service start entry, Service port baseline, runtime config file location, Docker/K8s runtime entry alignment, publish-readiness script guidance, and publish-readiness checks.

It does not own UI layout (

makeui

), authentication implementation (

make-app-auth

), single-app permission logic (

make-app-permission

), Make adapter environment variable semantics (

make-app-service

), DSL modeling (

makedsl

), Make resource deployment (

makecli

), or canvas-table behavior (

canvas-table-integration

Quick start

Identify whether the task touches
```
apps/
```
,
```
apps/service
```
,
```
apps/ui/dist
```
, package scripts, Docker/K8s, image entrypoints, publish readiness, or a runtime error such as
```
Cannot find module '/app/apps/service/dist/server.js'
```
.
Preserve the platform image contract unless the user explicitly says the platform contract itself is changing.
For a new App or an explicit runtime migration, verify the runtime baseline in
```
apps/package.json
```
: it must declare
```
"packageManager": "pnpm@10.20.0"
```
and
```
"engines": { "node": "22.20.0", "pnpm": "10.20.0" }
```
. Existing Make Apps keep their declared runtime during unrelated work; change it only after the user requests an explicit runtime migration.
For a new or explicitly migrated App, run package commands through Corepack (
```
corepack pnpm
```
), not an ambient
```
pnpm
```
binary. For an existing App without a runtime migration, use its compatible declared package manager, lockfile, and established workspace workflow.
For a new or explicitly reorganized App, verify workspace manifests:
```
apps/package.json
```
,
```
apps/pnpm-workspace.yaml
```
,
```
apps/ui/package.json
```
, and
```
apps/service/package.json
```
. For a legacy App, first identify its actual workspace structure without rewriting it.
Verify build artifacts before declaring ready: frontend
```
apps/ui/dist
```
and the Service entry selected by the actual platform image (
```
apps/service/dist/server.js
```
for the default contract).
Add or preserve a contract test for the Service runtime entry.

Workspace contract

Newly generated or explicitly runtime-reorganized Make App projects use:

```
apps/ui
```
```
apps/service
```
```
apps/dsl
```
```
apps/docs
```
```
apps/packages/*
```
when shared packages are needed

Required workspace files:

```
apps/package.json
```
```
apps/pnpm-workspace.yaml
```
```
apps/ui/package.json
```
```
apps/service/package.json
```

apps/pnpm-workspace.yaml

must include:

yaml

packages:
  - "ui"
  - "service"
  - "packages/*"

Package manager contract

All newly generated Make App React workspaces, and existing Apps undergoing an explicit runtime migration, use the fixed runtime triple: Node.js 22.20.0, its bundled Corepack 0.34.0, and pnpm 10.20.0. The workspace root (

apps/package.json

) must declare the exact Node and pnpm versions:

json

{
  "packageManager": "pnpm@10.20.0",
  "engines": {
    "node": "22.20.0",
    "pnpm": "10.20.0"
  }
}

Each executable workspace package, including

apps/ui/package.json

and

apps/service/package.json

, must declare

"engines": { "node": "22.20.0" }

. The project

engines.node

field rejects unsupported runtimes. Do not add

engineStrict

solely for this runtime baseline: it also enforces dependency engine declarations and requires a repository-specific compatibility decision.

The repository must also contain a

.nvmrc

with exactly

22.20.0

, and CI or the Make build image must select exactly Node.js

22.20.0

engines

is a compatibility guard; it does not select the Node binary used by a build environment.

Existing Make Apps retain their declared Node and package-manager versions during UI, auth, filtering, Service, or DSL work. That includes compatible npm and Yarn projects: preserve their existing

package-lock.json

yarn.lock

, workspace install target, and CI workflow. Do not rewrite

packageManager

engines

, lockfiles, or Node-selection files unless the user explicitly requests an explicit runtime migration. Perform that migration in a dedicated change with the project's tests and a Beta deployment. If the manager declaration, lockfile, workspace/CI workflow, or target platform build requirement conflicts, stop and report the compatibility blocker under

make-app-runtime

; do not generate a second lockfile or silently convert the App to pnpm.

For new or explicitly migrated pnpm Apps, enable Corepack before project work and run installation, tests, builds, package additions, and publish gates as

corepack pnpm ...

. Corepack reads the project declaration; a globally installed

pnpm

, including a newer major version, must not be used for these Apps. For an existing compatible pnpm App, use its declared pnpm version through Corepack. For an existing npm or Yarn App without migration, use the repository's established commands and lockfile; do not introduce Corepack or pnpm solely for an unrelated change. Child workspace manifests must not declare a conflicting package-manager version.

For a new or explicitly migrated pnpm App,

apps/package.json

must provide runnable scripts such as

app:ui

app:service

dev

test

, and

build

corepack pnpm --filter

targets must match the actual package names, including scoped names. A legacy App keeps its established equivalent scripts and workspace targets.

make-app-runtime

is the owner of

apps/package.json

generation and repair.

makecli app deploy

must not generate or rewrite workspace manifests.

Treat

makecli app deploy

as a code deployment boundary unless the target makecli version is proven to run a stricter publish gate. Do not report a generated App as publish-ready merely because deploy succeeded.

When preparing a new or explicitly migrated App for publish, provide enough project-local scripts and documentation for the agent or CI to run publish-readiness checks before deploy:

enable Corepack and install dependencies for
```
apps
```
with
```
corepack pnpm install --frozen-lockfile
```
verify Node.js is exactly
```
22.20.0
```
and Corepack is exactly
```
0.34.0
```
run the workspace build
run the
```
make-app-auth
```
published contract audit for Service-fronted Apps
run the
```
make-app-observability
```
Trace audit and behavior tests for every new Make App, whether direct-gateway or Service-fronted
run the
```
make-app-permission
```
contract audit when single-app permission enforcement is enabled or required by a repository-local delivery baseline
run Service gateway-mode contract tests proving local preview and published upstream scopes are separated
verify
```
apps/ui/dist
```
and
```
apps/service/dist/server.js
```
run Service contract tests, including auth callback proxy behavior, when tests exist

For a new or explicitly migrated pnpm Service-fronted App, prefer a project-local

verify:publish

script that runs the publish gate in one command. Keep

check:publish

for build/artifact checks, but do not make it the only release gate. Add

trace:audit

for every new App. When single-app permission enforcement is enabled or locally required, add

permission:audit

to that command; do not make unrelated Apps depend on a missing permission runtime. A legacy App uses its existing release command with the equivalent applicable checks.

Recommended workspace scripts for a new or explicitly migrated pnpm App. Before adding these to

package.json

, copy or wrap the audit utilities into project-local

scripts/

; do not write user-specific skill install paths into generated projects. Do not copy these pnpm-specific scripts into a legacy npm/Yarn App without an explicit runtime migration.

json

{
  "scripts": {
    "check:runtime": "node -e \"if (process.versions.node !== '22.20.0') throw new Error(`Make Apps require Node.js 22.20.0; got ${process.versions.node}`)\" && test \"$(corepack --version)\" = \"0.34.0\"",
    "auth:audit": "node scripts/audit-auth-contract.mjs . --mode service-fronted --published",
    "trace:audit": "node scripts/audit-trace-contract.mjs . --mode service-fronted",
    "schema:diff": "cd .. && makecli diff -f apps/dsl --output=json",
    "check:publish": "corepack pnpm run build && test -f service/dist/server.js && test -d ui/dist",
    "verify:publish": "corepack pnpm run check:runtime && corepack pnpm run test && corepack pnpm run auth:audit && corepack pnpm run trace:audit && corepack pnpm run check:publish && corepack pnpm run schema:diff"
  }
}

For an App with single-app permission enforcement, add

"permission:audit": "node scripts/audit-make-app-permission.mjs ."

and append

&& corepack pnpm run permission:audit

verify:publish

For a direct-gateway App, use

--mode direct

trace:audit

and keep the same default Trace requirement. The Trace contract itself belongs to

make-app-observability

; this Skill only ensures its checks run before deployment.

Do not describe

verify:publish

as a universal makecli hook unless the target makecli version supports it. It is a project-local quality gate to run before

makecli app deploy

Do not pass backend-context flags through

verify:publish

. For a new or explicitly migrated pnpm App, run the gate as

corepack pnpm run verify:publish

; a compatible legacy App uses its established equivalent gate and package manager. Then deploy code to Beta with

makecli app deploy --context <context> --profile <profile> --wait

. Follow the

makecli

skill for the Beta completion guide and, after explicit user authorization, publish that Beta version to Prod with

makecli app promote --context <context> --profile <profile> --yes --wait

. Keep the same backend context/profile throughout; promotion uses the deployed Beta version and does not push local code. If a project-local Node wrapper must accept flags through

corepack pnpm run

, normalize argv by dropping a standalone

--

before parsing because

corepack pnpm run <script> -- --flag

can expose that separator to the script.

For Service-fronted Apps, the Service test suite (run via the project's declared package manager;

corepack pnpm run test

for a new/migrated pnpm App) must include the gateway-mode contract:

MAKE_APP_LOCAL_PREVIEW=true

: Service uses

makecli configure resolve --target local-preview --output=json

field

make_api_origin

and

/api/make/**

published mode, where the flag is absent or false: Service uses the deployed k8s-internal gateway origin and
```
/make/**
```
.
The local-preview token branch is unreachable in published mode.

Frontend build contract

Frontend publish artifacts live in

apps/ui/dist

Generated or updated Vite config should set:

```
build.outDir: "dist"
```
```
build.emptyOutDir: true
```

Do not publish or configure static asset discovery against root

dist

apps/dist

Service runtime contract

The platform image default Service entry is:

text

/app/apps/service/dist/server.js

Therefore the default TypeScript Service contract is:

source entry:
```
apps/service/src/server.ts
```
compiled entry:
```
apps/service/dist/server.js
```
production start script:
```
node dist/server.js
```
dev script may use
```
tsx watch src/server.ts
```
, but production start must not use
```
tsx
```
Service HTTP port:
```
3000
```
centralized runtime config entry:
```
apps/service/src/config.ts
```

apps/service/tsconfig.json

must compile the runtime source to that path:

json

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.test.ts", "test", "dist"]
}

For a new or explicitly migrated pnpm App,

apps/service/package.json

must include the Node engine and scripts equivalent to:

json

{
  "engines": {
    "node": "22.20.0"
  },
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc -p tsconfig.json",
    "start": "node dist/server.js",
    "test": "vitest run"
  }
}

Do not leave Docker, K8s, makecli, package scripts, or docs pointing at

/app/apps/service/dist/server.js

unless the project's declared build workflow creates

apps/service/dist/server.js

(for a new or migrated pnpm App,

corepack pnpm --filter <service-package> build

If a legacy project intentionally uses a different Service entry or build tool, keep it only when all runtime references agree: Docker/K8s entrypoint, package

start

, docs, build output, and readiness tests.

Service build contract test

Service-backed Apps should include a test that protects the runtime entry contract. The test may live in

apps/service/test/service-build-contract.test.ts

or the project's established test location. The fixed-version assertions below apply only to new or explicitly migrated pnpm Apps; legacy Apps assert their own declared runtime and lockfile without changing them.

It should assert:

apps/package.json

declares

packageManager: "pnpm@10.20.0"

apps/package.json

declares

engines.node: "22.20.0"

and

engines.pnpm: "10.20.0"

```
.nvmrc
```
contains
```
22.20.0
```
, and the CI or Make build image uses Node.js
```
22.20.0
```

apps/ui/package.json

and

apps/service/package.json

each declare

engines.node: "22.20.0"

```
apps/service/package.json
```
has a
```
build
```
script
```
apps/service/package.json
```
production start points to
```
node dist/server.js
```
when the platform image uses that entry

apps/service/tsconfig.json

uses

rootDir: "src"

and

outDir: "dist"

after build,
```
apps/service/dist/server.js
```
exists

Run the Service build before relying on that artifact. For a new or explicitly migrated pnpm App:

bash

corepack pnpm --filter <service-package-name> build
test -f apps/service/dist/server.js

For a legacy App, use its established package-manager build command and verify the actual production entry artifact instead.

Runtime config location and port

Service runtime environment reads are centralized in

apps/service/src/config.ts

for new projects. This skill only requires the config entry location and fixed port handling needed by runtime/startup. Make adapter variables such as

MAKE_API_BASE_URL

MAKE_SERVER_URL

MAKE_AUTH_BASE_URL

, and

MAKE_BUSINESS_BASE_URL

belong to

make-app-service

Service HTTP port is fixed to

. Generated or refactored Service code,

.env.example

, docs, health checks, tests, CORS, and UI local Service base URL examples must align to

If local

is occupied during development, report the conflict. Do not silently change the Service contract port.

make-app-runtime

does not decide which environment connects to which Make domain, gateway, or API host. Domain mapping, gateway routing, and secret injection belong to backend, operations, Make tooling, or deployed runtime config.

Forwarded request headers

When Service forwards requests to a Make gateway and that gateway needs request-origin context, preserve or set standard forwarded headers:

```
X-Forwarded-Host
```
```
X-Forwarded-Proto
```

Do not hard-code environment domains in generated Service code. Use the incoming request context or the host runtime proxy contract.

Readiness checks

Before reporting a Service-backed App as ready to publish or ready for user-domain access, distinguish a new/explicitly migrated pnpm App from a legacy App. For the former:

Verify

node --version

reports

v22.20.0

and

corepack --version

reports

0.34.0

. Then run

cd apps && corepack pnpm install --frozen-lockfile

and verify

corepack pnpm --version

reports

10.20.0

Run

cd apps && corepack pnpm run verify:publish

when the project provides it.

Otherwise, run the workspace build that produces
```
apps/ui/dist
```
.
Run the Service build.
Verify
```
apps/service/dist/server.js
```
exists when the runtime entry points there.
Run the Service contract test and the make-app-auth published audit for Service-fronted Apps.
For Service-fronted Apps, verify the Service contract test covers both local-preview and published gateway modes. Published upstream requests must not use
```
/api/make/**
```
; local preview must consume makecli resolve
```
make_api_origin
```
and must not use k8s-internal
```
/make/**
```
.
If a start smoke is available, start the built Service with the production start script and verify it reaches the expected health or root response, then stop it.

For an existing App without runtime migration, first verify that its declared Node/package manager, lockfile, workspace and CI/install workflow agree with the target platform build image. Use that App's established frozen/clean install, test, build and release commands, then perform the same applicable auth, permission, gateway-mode, artifact and start checks above. Do not require the

22.20.0

10.20.0

triple,

pnpm-workspace.yaml

, or

corepack pnpm run verify:publish

merely because an unrelated UI feature changed. If the platform actually requires a runtime the legacy App cannot meet, report a publish blocker and request an explicit migration; a successful local build alone is not release readiness.

Do not mark a Service-backed App ready based only on successful local

tsx src/server.ts

development startup.

Common failure diagnosis

Error:

text

Cannot find module '/app/apps/service/dist/server.js'

Treat it as a runtime contract failure:

build did not run, or
```
src/server.ts
```
was missing, or
```
tsconfig
```
emitted somewhere else, or
package
```
start
```
/ image entry points to a file the build does not create.

Fix the build/start contract. Do not work around it by changing UI code or auth behavior.

make-app-runtime

NPX Install

Tags

SKILL.md Content

make-app-runtime

Quick start

Workspace contract

Package manager contract

Frontend build contract

Service runtime contract

Service build contract test

Runtime config location and port

Forwarded request headers

Readiness checks

Common failure diagnosis