make-app-runtime

make-app-runtime

Make App のランタイムおよびパッケージングの契約には、このスキルを使用してください。プラットフォームのイメージエントリポイントと公開アーティファクトが POC ごとに変わらないよう、これらのルールは意図的に厳格に定められています。

このスキルの対象は、プロジェクトのランタイム構成、ワークスペースマニフェスト、ビルド出力、Service の起動エントリ、Service のポートの基本設定、ランタイム設定ファイルの配置、Docker/K8s のランタイムエントリの整合、公開準備スクリプトのガイダンス、および公開準備チェックです。

UI レイアウト（makeui）、認証の実装（make-app-auth）、単一アプリの権限ロジック（make-app-permission）、Make アダプターの環境変数のセマンティクス（make-app-service）、DSL のモデリング（makedsl）、Make リソースのデプロイ（makecli）、またはキャンバステーブルの動作（canvas-table-integration）は対象外です。

クイックスタート

1. タスクが apps/、apps/service、apps/ui/dist、パッケージスクリプト、Docker/K8s、イメージエントリポイント、公開準備、または Cannot find module '/app/apps/service/dist/server.js' のようなランタイムエラーに関係するかを確認します。
2. ユーザーがプラットフォームの契約自体を変更すると明示していない限り、プラットフォームイメージの契約を維持します。
3. 新しい App または明示的なランタイム移行では、apps/package.json のランタイムの基本設定を確認します。"packageManager": "[email protected]" および "engines": { "node": "22.20.0", "pnpm": "10.20.0" } を宣言している必要があります。既存の Make App は、無関係な作業の際には宣言済みのランタイムを維持し、ユーザーが明示的なランタイム移行を依頼した場合にのみ変更します。
4. 新しい App または明示的に移行する App では、パッケージコマンドの実行に、環境にある pnpm バイナリではなく Corepack（corepack pnpm）を使用します。ランタイム移行を行わない既存の App では、互換性のある宣言済みパッケージマネージャー、ロックファイル、および確立されたワークスペースのワークフローを使用します。
5. 新しい App または明示的に再構成する App では、ワークスペースマニフェスト（apps/package.json、apps/pnpm-workspace.yaml、apps/ui/package.json、apps/service/package.json）を確認します。レガシー App では、書き換える前に実際のワークスペース構成を特定します。
6. 準備完了と判断する前に、ビルド成果物を確認します。フロントエンドの apps/ui/dist と、実際のプラットフォームイメージが選択する Service エントリ（デフォルトの契約では apps/service/dist/server.js）を確認します。
7. Service のランタイムエントリに対する契約テストを追加するか、維持します。

ワークスペースの契約

新規生成する Make App プロジェクト、またはランタイム構成を明示的に再編成する Make App プロジェクトでは、次を使用します。

• apps/ui
• apps/service
• apps/dsl
• apps/docs
• 共有パッケージが必要な場合は apps/packages/*

必須のワークスペースファイル：

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

apps/pnpm-workspace.yaml には次を含める必要があります。

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

パッケージマネージャーの契約

新規生成するすべての Make App React ワークスペースと、明示的なランタイム移行を行う既存の App では、固定のランタイム構成である Node.js 22.20.0、同梱の Corepack 0.34.0、および pnpm 10.20.0 を使用します。ワークスペースのルート（apps/package.json）では、Node と pnpm の正確なバージョンを宣言する必要があります。

{
  "packageManager": "[email protected]",
  "engines": {
    "node": "22.20.0",
    "pnpm": "10.20.0"
  }
}

apps/ui/package.json および apps/service/package.json を含む、実行可能な各ワークスペースパッケージでは、"engines": { "node": "22.20.0" } を宣言する必要があります。プロジェクトの engines.node フィールドは、サポート対象外のランタイムを拒否します。このランタイムの基本設定だけを目的として engineStrict を追加しないでください。engineStrict は依存関係のエンジン宣言にも適用され、リポジトリ固有の互換性判断が必要になります。

リポジトリには、正確に 22.20.0 を記載した .nvmrc も含める必要があります。また、CI または Make のビルドイメージでは、正確に Node.js 22.20.0 を選択する必要があります。engines は互換性を確認するためのガードであり、ビルド環境で使用する Node バイナリを選択するものではありません。 既存の Make App は、UI、認証、フィルタリング、Service、DSL の作業中も、宣言済みの Node とパッケージマネージャーのバージョンを維持します。互換性のある npm プロジェクトと Yarn プロジェクトも対象です。既存の package-lock.json または yarn.lock、ワークスペースのインストール先、CI ワークフローをそのまま保持してください。ユーザーが明示的にランタイムの移行を依頼しない限り、packageManager、engines、ロックファイル、Node 選択ファイルを書き換えないでください。移行する場合は、プロジェクトのテストと Beta デプロイを含む独立した変更として実施してください。マネージャーの宣言、ロックファイル、ワークスペース／CI ワークフロー、または対象プラットフォームのビルド要件が競合する場合は、作業を中止して互換性の問題を make-app-runtime の項目として報告してください。2 つ目のロックファイルを生成したり、App をひそかに pnpm に変換したりしないでください。

新規または明示的に移行した pnpm App では、プロジェクト作業の前に Corepack を有効にし、インストール、テスト、ビルド、パッケージの追加、公開ゲートを corepack pnpm ... として実行してください。Corepack はプロジェクトの宣言を読み取ります。グローバルにインストールされた pnpm は、より新しいメジャーバージョンであっても、これらの App で使用してはいけません。互換性のある既存の pnpm App では、Corepack を通じて宣言済みの pnpm バージョンを使用してください。移行を行わない既存の npm または Yarn App では、リポジトリで既に使われているコマンドとロックファイルを使用してください。無関係な変更のためだけに Corepack や pnpm を導入してはいけません。子ワークスペースのマニフェストで、競合するパッケージマネージャーのバージョンを宣言してはいけません。

新規または明示的に移行した pnpm App では、apps/package.json に app:ui、app:service、dev、test、build などの実行可能なスクリプトを用意してください。corepack pnpm --filter の対象は、スコープ付きの名前を含め、実際のパッケージ名と一致させてください。レガシー App では、既存の同等スクリプトとワークスペースの対象を維持してください。

make-app-runtime が apps/package.json の生成と修復を担当します。makecli app deploy でワークスペースのマニフェストを生成または書き換えてはいけません。

対象の makecli バージョンが、より厳格な公開ゲートを実行すると確認できない限り、makecli app deploy はコードのデプロイ境界として扱ってください。デプロイに成功したというだけで、生成された App を公開準備完了と報告してはいけません。

新規または明示的に移行した App を公開に備えて準備する際は、デプロイ前にエージェントまたは CI が公開準備チェックを実行できるよう、プロジェクト内に十分なスクリプトとドキュメントを用意してください。

• Corepack を有効にし、corepack pnpm install --frozen-lockfile で apps の依存関係をインストールする
• Node.js が厳密に 22.20.0、Corepack が厳密に 0.34.0 であることを確認する
• ワークスペースのビルドを実行する
• Service 経由の App では、公開済みの make-app-auth 契約監査を実行する
• すべての新しい Make App で、ゲートウェイに直接接続する App と Service 経由の App のどちらでも、make-app-observability の Trace 監査と動作テストを実行する
• シングル App の権限適用が有効になっている場合、またはリポジトリ内の配信基準で必須の場合は、make-app-permission の契約監査を実行する
• ローカルプレビューと公開済みのアップストリームのスコープが分離されていることを証明する、Service のゲートウェイモード契約テストを実行する
• apps/ui/dist と apps/service/dist/server.js が存在することを確認する
• テストが存在する場合は、認証コールバックのプロキシ動作を含む Service の契約テストを実行する

新規または明示的に移行した pnpm の Service 経由 App では、公開ゲートを 1 つのコマンドで実行するプロジェクト内の verify:publish スクリプトを推奨します。ビルド／成果物のチェックには check:publish を使用しますが、リリースゲートをこれだけにしてはいけません。すべての新しい App に trace:audit を追加してください。シングル App の権限適用が有効またはローカルで必須の場合は、そのコマンドに permission:audit を追加してください。無関係な App が、存在しない権限ランタイムに依存するようにしてはいけません。レガシー App では、適用可能な同等のチェックを含む既存のリリースコマンドを使用してください。

新規または明示的に移行した pnpm App に推奨するワークスペーススクリプトです。これらを package.json に追加する前に、監査ユーティリティをプロジェクト内の scripts/ にコピーするか、ラッパーを作成してください。生成されるプロジェクトに、ユーザー固有のスキルのインストールパスを書き込んではいけません。ランタイムの明示的な移行がない限り、これらの pnpm 固有のスクリプトをレガシーの npm／Yarn App にコピーしてはいけません。

{
  "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"
  }
}

単一アプリの権限適用を行う App では、"permission:audit": "node scripts/audit-make-app-permission.mjs ." を追加し、verify:publish に && corepack pnpm run permission:audit を追記します。

ダイレクトゲートウェイ App では、trace:audit で --mode direct を使用し、同じデフォルトの Trace 要件を維持します。Trace の契約自体は make-app-observability に属します。この Skill では、デプロイ前にそのチェックが実行されることだけを保証します。

対象の makecli バージョンが対応していない限り、verify:publish を汎用的な makecli フックとして説明しないでください。これは makecli app deploy の前に実行する、プロジェクト固有の品質ゲートです。

verify:publish にバックエンドコンテキストのフラグを渡さないでください。新規または明示的に移行された pnpm App では、corepack pnpm run verify:publish としてゲートを実行します。互換性のあるレガシー App では、既存の同等のゲートとパッケージマネージャーを使用します。その後、makecli app deploy --context <context> --profile <profile> --wait でコードを Beta にデプロイします。Beta 完了ガイドに従うには makecli スキルを参照し、ユーザーから明示的な許可を得た後、makecli app promote --context <context> --profile <profile> --yes --wait でその Beta バージョンを Prod に公開します。バックエンドのコンテキストとプロファイルは一貫して同じものを使用します。プロモーションではデプロイ済みの Beta バージョンが使用され、ローカルコードはプッシュされません。プロジェクト固有の Node ラッパーで corepack pnpm run 経由のフラグを受け取る必要がある場合は、解析前に単独の -- を削除して argv を正規化してください。corepack pnpm run <script> -- --flag では、その区切り文字がスクリプトに渡されることがあります。

Service が前段にある App では、Service のテストスイート（プロジェクトで宣言されたパッケージマネージャー経由で実行し、新規または移行済みの pnpm App では corepack pnpm run test を使用）に、次のゲートウェイモードの契約を含める必要があります。

• MAKE_APP_LOCAL_PREVIEW=true：Service は makecli configure resolve --target local-preview --output=json のフィールド make_api_origin と /api/make/** を使用します。
• 公開済みモード（フラグが存在しない、または false の場合）：Service はデプロイ済みの k8s 内部ゲートウェイのオリジンと /make/** を使用します。
• ローカルプレビューのトークン分岐は、公開済みモードでは到達できません。

フロントエンドのビルド契約

フロントエンドの公開アーティファクトは apps/ui/dist に配置されます。

生成または更新する Vite 設定では、次の値を設定します。

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

ルートの dist や apps/dist を対象に、静的アセットの検出を設定したり、そこに公開したりしないでください。

Service のランタイム契約

プラットフォームイメージにおけるデフォルトの Service エントリは次のとおりです。

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

したがって、デフォルトの TypeScript Service 契約は次のとおりです。

• ソースエントリ：apps/service/src/server.ts
• コンパイル済みエントリ：apps/service/dist/server.js
• 本番用起動スクリプト：node dist/server.js
• 開発用スクリプトでは tsx watch src/server.ts を使用できますが、本番用起動では tsx を使用してはいけません。
• Service の HTTP ポート：3000
• 一元化されたランタイム設定エントリ：apps/service/src/config.ts

apps/service/tsconfig.json では、ランタイムソースを次のパスにコンパイルする必要があります。

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

新規または明示的に移行された pnpm App では、apps/service/package.json に Node エンジンと、次と同等のスクリプトを含める必要があります。

{
  "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"
  }
}

プロジェクトで宣言されたビルドワークフロー（新規または移行済みの pnpm App では corepack pnpm --filter <service-package> build）によって apps/service/dist/server.js が生成される場合を除き、Docker、K8s、makecli、パッケージスクリプト、ドキュメントから /app/apps/service/dist/server.js への参照を残さないでください。

レガシープロジェクトで意図的に異なる Service エントリやビルドツールを使用している場合は、すべてのランタイム参照が一致している場合に限り、その構成を維持します。対象となるのは、Docker/K8s のエントリポイント、パッケージの start、ドキュメント、ビルド出力、レディネステストです。

Service のビルド契約テスト

Service を利用する App には、ランタイムのエントリー契約を保護するテストを含めてください。テストは apps/service/test/service-build-contract.test.ts またはプロジェクトで確立されているテスト配置場所に置けます。以下の固定バージョンに関するアサーションは、新規または明示的に移行した pnpm App にのみ適用されます。レガシー App では、変更を加えずに、独自に宣言したランタイムとロックファイルをアサーションしてください。

次の項目をアサーションしてください。

• apps/package.json で packageManager: "[email protected]" が宣言されている
• apps/package.json で engines.node: "22.20.0" と engines.pnpm: "10.20.0" が宣言されている
• .nvmrc に 22.20.0 が記載され、CI または Make のビルドイメージが Node.js 22.20.0 を使用している
• apps/ui/package.json と apps/service/package.json のそれぞれで engines.node: "22.20.0" が宣言されている
• apps/service/package.json に build スクリプトがある
• プラットフォームのイメージがそのエントリーを使用する場合、apps/service/package.json の本番環境向け start が node dist/server.js を指している
• apps/service/tsconfig.json で rootDir: "src" と outDir: "dist" が使用されている
• ビルド後に apps/service/dist/server.js が存在する

このアーティファクトを利用する前に、Service をビルドしてください。新規または明示的に移行した pnpm App の場合：

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

レガシー App の場合は、確立されているパッケージマネージャーのビルドコマンドを使用し、実際の本番エントリーアーティファクトを検証してください。

ランタイム設定の配置場所とポート

新しいプロジェクトでは、Service のランタイム環境変数の読み取りを apps/service/src/config.ts に集約します。このスキルで必要なのは、ランタイム／起動に必要な設定エントリーの配置場所と固定ポートの処理のみです。MAKE_API_BASE_URL、MAKE_SERVER_URL、MAKE_AUTH_BASE_URL、MAKE_BUSINESS_BASE_URL などの Make アダプター変数は make-app-service に属します。

Service の HTTP ポートは 3000 に固定されています。生成またはリファクタリングする Service コード、.env.example、ドキュメント、ヘルスチェック、テスト、CORS、UI のローカル Service ベース URL の例は、すべて 3000 に合わせてください。

開発中にローカルの 3000 が使用中の場合は、その競合を報告してください。Service 契約のポートを暗黙に変更しないでください。

make-app-runtime は、どの環境がどの Make ドメイン、ゲートウェイ、API ホストに接続するかを決定しません。ドメインのマッピング、ゲートウェイのルーティング、シークレットの注入は、バックエンド、オペレーション、Make ツール、またはデプロイ済みランタイム設定に属します。

転送されるリクエストヘッダー

Service が Make ゲートウェイにリクエストを転送し、そのゲートウェイがリクエストの発信元コンテキストを必要とする場合は、標準の転送ヘッダーを保持するか設定してください。

• X-Forwarded-Host
• X-Forwarded-Proto

生成する Service コードに環境ドメインをハードコードしないでください。受信リクエストのコンテキストまたはホストランタイムのプロキシ契約を使用してください。

準備状況の確認

Service を使用する App を公開可能、またはユーザードメインからアクセス可能と報告する前に、新規 App／明示的に移行された pnpm App と、従来の App を区別してください。前者の場合：

1. node --version が v22.20.0 を、corepack --version が 0.34.0 を報告することを確認します。次に cd apps && corepack pnpm install --frozen-lockfile を実行し、corepack pnpm --version が 10.20.0 を報告することを確認します。
2. プロジェクトで提供されている場合は、cd apps && corepack pnpm run verify:publish を実行します。
3. それ以外の場合は、apps/ui/dist を生成するワークスペースのビルドを実行します。
4. Service のビルドを実行します。
5. ランタイムのエントリーポイントが apps/service/dist/server.js を指す場合は、そのファイルが存在することを確認します。
6. Service を前面に置く App では、Service のコントラクトテストと make-app-auth の公開監査を実行します。
7. Service を前面に置く App では、Service のコントラクトテストがローカルプレビューと公開ゲートウェイの両モードを対象としていることを確認します。公開時の上流リクエストでは /api/make/** を使用してはなりません。ローカルプレビューでは、makecli の解決結果に含まれる make_api_origin を使用し、k8s 内部用の /make/** を使用してはなりません。
8. 起動スモークテストを実施できる場合は、本番用の起動スクリプトでビルド済みの Service を起動し、想定されるヘルスチェックまたはルート応答が返ることを確認してから、停止します。

ランタイム移行を行っていない既存の App では、まず、宣言されている Node／パッケージマネージャー、ロックファイル、ワークスペース、CI／インストールのワークフローが、対象プラットフォームのビルドイメージと一致することを確認します。その App で確立されている固定バージョンを使ったクリーンインストール、テスト、ビルド、リリースの各コマンドを実行し、上記の認証、権限、ゲートウェイモード、成果物、起動に関する該当する確認も行います。無関係な UI 機能を変更しただけで、22.20.0／10.20.0 の組み合わせ、pnpm-workspace.yaml、または corepack pnpm run verify:publish を必須にしてはなりません。プラットフォームが実際に要求するランタイムを従来の App が満たせない場合は、公開のブロッカーとして報告し、明示的な移行を求めてください。ローカルビルドが成功しただけでは、リリース可能とは判断できません。

ローカルでの tsx src/server.ts による開発起動が成功しただけで、Service を使用する App を準備完了としてはなりません。

よくあるエラーの診断

エラー：

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

ランタイムコントラクトの失敗として扱ってください。

• ビルドが実行されていない、または
• src/server.ts が存在しない、または
• tsconfig が別の場所に出力した、または
• パッケージの start／イメージのエントリーポイントが、ビルドで生成されないファイルを指している。

ビルドと起動のコントラクトを修正してください。UI コードや認証の動作を変更して回避してはなりません。