npm - @h-ai/deploy - Versions diffs - 0.1.0-alpha.65 → 0.1.0-alpha.66 - Mend

@h-ai/deploy 0.1.0-alpha.65 → 0.1.0-alpha.66

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.en.md CHANGED Viewed

@@ -1,202 +1,79 @@
 # @h-ai/deploy
-[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+[简体中文](README.md) | [English](README.en.md) | [日本語](README.ja.md)
-[Framework home](../../README.en.md) · [CLI](../cli/README.en.md) · [Environment and middleware](../cli/templates/skills/hai-deploy/middleware.md)
+Deploy consumes existing artifacts. It never compiles source or builds images. Build once, deploy the same images to multiple environments.
-Deployment SDK used by the `hai deploy` command in `@h-ai/cli`. It also runs independently in Node.js scripts.
+Follow the [usage guide](../../docs/usage/README.en.md) for the complete creation, development, build, and deployment workflow. This page focuses on deployment requirements, the SDK, and module development.
-## Features and scope
+## Build
-| Target       | Application                                         | Operation                                                                           |
-| ------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `docker-ssh` | Native Node services or SvelteKit with adapter-node | Build locally, upload over SSH, run Compose on Linux and check HTTP health          |
-| `vercel`     | SvelteKit with adapter-vercel                       | Build, upload, set environment variables and wait for deployment; requires internet |
+Node `^22.22.2 || ^24.15.0 || >=26.0.0`, pnpm 12.11.2; Windows: `pnpm.cmd`. Node 20 / pnpm 9.5.0 are unsupported.
-- Follow runtime dependencies and workspace links from the target importer in `pnpm-lock.yaml`, excluding development dependencies and peers. Application configuration selects middleware backends. Optional AI peers do not enable AI/CUDA.
-- Select an environment and require `.env.<mode>` before choosing defaults, custom connections or keep unchanged per middleware. Complete environments can skip all middleware processing.
-- Compose supports PostgreSQL, MySQL, Redis, RustFS/MinIO, Qdrant, pgvector, Chroma, OpenLDAP and Mailpit. SQLite, memory, local and LanceDB use their respective local storage. Mailpit captures test mail only.
-- Cloud provisioning supports Neon, Upstash, Cloudflare R2, Resend and Alibaba Cloud SMS. R2 needs existing S3 credentials, Resend a verified sender domain, and SMS approved signatures/templates. Use custom connections for other backends.
-**Fullstack API and Web are separate deployments.** `hai deploy packages/my-app-serv` deploys the API only. The root template Dockerfile has `runtime` and `web` targets for API and static Web images. Upload and run Web separately, setting `PUBLIC_API_BASE` and API CORS. There is no command to publish both together, nor automatic domain, TLS or reverse proxy configuration.
-## Command-line deployment
-### 1. Install and prepare
-Node must satisfy `^22.22.2 || ^24.15.0 || >=26.0.0`; generated projects pin `pnpm@12.11.2`. Node 20 / pnpm 9.5.0 are unsupported. Use `pnpm.cmd` in Windows PowerShell.
-In the generated workspace root, install CLI/SDK versions matching the application's framework and retain the lockfile. Installation needs a package source or complete offline dependencies:
-```powershell
-pnpm.cmd add -Dw @h-ai/cli @h-ai/deploy
-pnpm.cmd exec hai --help
-```
-Creation with `--features deploy` already adds the local SDK, but does not install a global `hai`. With a global CLI, run `hai deploy` directly. The template's `pnpm run deploy` packages artifacts; it does not invoke this deployment command.
-For docker-ssh, prepare:
-- A running local Docker/Podman engine capable of building Linux images for the server architecture. Windows needs the corresponding virtualization/WSL2/VM environment; a client alone is insufficient. `auto` prefers Podman; Docker can be selected explicitly.
-- Local `ssh` and `scp`, noninteractive key/agent authentication and the server host fingerprint.
-- Remote Docker/Podman with its `compose` command. The SSH user must run containers and write the deployment directory. Windows must reach SSH and the exposed application port.
-- `config/_deploy.yml` in the target package and `.env.prod` or `.env.test` in the environment directory. Missing environment files stop deployment.
-### 2. Configure target and environment
-Minimal `config/_deploy.yml` for Docker; supply machine-specific target details through the whole-object `HAI_DEPLOY_PROVIDER` override in `.env.local`:
-```yaml
-provider:
-  type: docker-ssh
-container:
-  runtime: docker
-  s3Engine: rustfs
-services: {}
-```
-Replace the host, user, ports and key path for your environment. Never commit `.env.local`:
-```dotenv
-HAI_DEPLOY_PROVIDER='{"type":"docker-ssh","ssh":{"host":"10.0.0.20","port":22,"username":"deploy","identityFile":"C:/Users/me/.ssh/hai_deploy"},"remote":{"baseDir":"/opt/hai/apps","runtime":"docker"},"expose":{"type":"port","containerPort":3000,"hostPort":18080}}'
+```sh
+pnpm build                               # source only; no environment selection
+pnpm build --target docker               # reachable Podman first, then Docker
+pnpm build --target docker --runtime docker
+pnpm build --target desktop --platform windows --arch x64
 ```
-Alternatively, the wizard asks for missing target details, saves them in `.env.local` and reuses them. Store private key paths only. Edit `HAI_DEPLOY_PROVIDER` to switch a complete target.
-Precedence: `.env` → `.env.<mode>` → `.env.local` → process environment. Parent JSON such as `HAI_DB` overrides child variables. `.env.example` documents all fields and enums. Commit `.env` and `.env.dev/test/prod`; keep real credentials in `.env.local`. Fullstack's first start also needs a private `HAI_ADMIN_DEFAULT_PASSWORD` satisfying the IAM password policy.
-Fullstack production also requires an explicit Web Origin in `.env.prod`, such as `HAI_SERV_CORS_ORIGIN=https://app.hai.internal`; the default `*` prevents production startup. Production refresh cookies use Secure, so Web/API need trusted HTTPS endpoints. Exposing HTTP ports alone does not validate complete login/session refresh.
+`hai.build.json` describes Docker targets and Tauri directories. Images and SHA-256 manifest are under `.hai/build/docker/<buildId>`. API/Web share one build ID; latest changes only after complete success. Tauri runs on the matching Windows/Linux/macOS host with Rust targets, SDKs and packaging tools installed; installers are under `src-tauri/target/<target>/release/bundle`. Build has no dev/test/prod mode and excludes deployment credentials.
-### 3. Deploy
+Versions come from the application root package.json.version. For version 1.2.3, archives are app-1.2.3.tar/web-1.2.3.tar and Compose is docker-compose-1.2.3.yml. Manifest version: 2 is its format; appVersion is the application version. --output release-prod.tar becomes release-prod-1.2.3.tar, and Tauri receives the same root version. See the [complete guide](../../docs/usage/README.en.md) for defaults and examples.
-From the fullstack root, replace the service directory:
-```powershell
-pnpm.cmd exec hai deploy packages/my-app-serv --env prod --env-dir .
-```
+## Deployment
-The wizard shows the effective backend and purpose. Defaults generate Compose services/volumes; custom connections omit that middleware container. Keep unchanged is offered only when the target environment file explicitly declares complete configuration. Public values go to the selected environment file, credentials to `.env.local`, with redacted output.
-When all database, cache and storage connections are already configured:
-```powershell
-pnpm.cmd exec hai deploy packages/my-app-serv --env prod --env-dir . --yes --skip-middleware
+```sh
+pnpm run deploy --env test
+pnpm run deploy --env prod --artifact-dir .hai/build/docker/<buildId> --skip-middleware
+pnpm run deploy --env prod --bundle-only --output release-prod.tar
+# equivalent fullstack CLI invocation
+pnpm exec hai deploy packages/my-app-serv --env prod --env-dir .
 ```
-`--skip-middleware` (alias `--skip-provision`) skips middleware prompts, configuration updates and resource creation; application build/deployment still run. It does not start external middleware. `--yes` alone keeps complete settings and otherwise uses the current backend defaults.
-`--project-name <name>` sets the name; an explicit environment adds a suffix. **`--skip-build` currently skips only Vercel application builds. docker-ssh always builds an image and has no option to deploy a specified existing image directly.** Failures return a nonzero exit code.
-## docker-ssh execution and files
-1. Use the target package's Dockerfile, or generate a fallback with the workspace root as context. Fullstack service packages use the fallback by default, not the root Web target.
-2. Build the image locally and export a tar with `docker/podman save`.
-3. Check the remote engine and Compose over SSH, upload the tar with SCP, then run `load` remotely.
-4. Generate `compose.yml`, `.env.runtime` and `start-<mode>.sh` locally and upload each to `<baseDir>/<projectName>-<mode>/`. These are separate from the image archive; no single Compose bundle is uploaded and no source build runs on Linux.
-5. The remote script sets `HAI_DEPLOY_ENVIRONMENT`/`HAI_CORE_ENV` and runs `compose --env-file .env.runtime ... up -d`. The SDK checks native `/health` or SvelteKit `/` from the local machine before succeeding.
-Local artifacts live in the target package's Git-ignored `.hai/deploy/<mode>/`. Remote `.env.runtime` uses mode `600`. Retain local artifacts for repeat deployment: keep unchanged preserves services/volumes from the previous local Compose, not arbitrary server-side Compose definitions. Exclude private environment files and deployment archives from image contexts.
-## Fully offline deployment
-Offline means no internet; Windows and Linux must still communicate over an internal SSH/HTTP network. Vercel and cloud provisioning are unavailable.
-### Materials to bring in advance
+Requires matching `@h-ai/cli` / `@h-ai/deploy`, `_deploy.yml`, lockfile and `.env.<mode>`. Missing environment files stop deployment. Public `.env`, `.env.dev/test/prod` and documented `.env.example` are committed; private `.env.local` is ignored. Priority: process > local > mode > base. SSH fields/tokens can be stored in private `HAI_DEPLOY_PROVIDER` JSON. Bundle-only needs no SSH config or local container engine.
-| Location      | Requirements                                                                                                                                                                                                                |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Windows tools | Compatible Node (for example a supported Node 24), pnpm 12.11.2, installed CLI/SDK and transitive dependencies, OpenSSH, initialized and runnable Linux container engine                                                    |
-| Project       | Complete source, pinned lockfile, environment files and private credentials; `pnpm.cmd exec hai --help` must work offline. Avoid on-demand `npx` / `pnpm dlx` downloads                                                     |
-| Linux         | Docker CLI/Engine, Compose plugin (`docker compose version` works), authorized SSH key, container permissions, writable deployment directory, ports and disk space. Host Node/pnpm are unnecessary for running images       |
-| Images        | API, Web and middleware images matching Linux CPU architecture and exact Compose names/tags; import with `docker load -i <archive.tar>`                                                                                     |
-| Application   | PostgreSQL database/account, Redis connection/password, RustFS keys/bucket and initial administrator password. Existing services must already run and be reachable from the app container; `localhost` means that container |
+The wizard traverses only lockfile runtime dependencies, excluding dev/peer. Select default, custom or keep for each middleware; `--skip-middleware` bypasses all middleware work. Compose supports PostgreSQL/MySQL/Redis/RustFS/MinIO/Qdrant/pgvector/Chroma/OpenLDAP/Mailpit. Optional cloud provisioning supports Neon/Upstash/R2/Resend/Aliyun SMS and requires network access.
-Defaults use `postgres:16-alpine`, `redis:7-alpine` and `ghcr.io/rustfs/rustfs:1.0.1`. Other tags do not match automatically: import the exact images, correctly retag verified compatible images, or use custom connections. The SDK does not transfer middleware images. Other pinned images are in the [Compose implementation](src/container/deploy-container-compose.ts).
+Optional `container.s3Engine` defaults to rustfs and chooses RustFS/MinIO only when creating a Compose S3 service. Existing custom S3 services are unaffected. Use `--skip-middleware` to bypass middleware setup; the SDK field is `skipMiddleware`.
-**The default source build is not ready for offline use without preparation.** Dockerfiles prepare pnpm and download packages and SQLite prebuilds; the fullstack root also runs `pnpm fetch` and uses an external Dockerfile frontend. Windows `node_modules`/pnpm store cannot replace Linux build dependencies. For offline source builds, bring Node base images, the build frontend, Corepack/pnpm, Linux dependencies and native binary caches into the local engine/build environment, adapt the Dockerfile, and rehearse with internet disconnected. `pnpm install --offline --frozen-lockfile` only addresses package-store access, not additional downloads by install scripts.
+A single private tar contains Compose, runtime env, app/web images, optional Web proxy, checksums, README and `start-<mode>.sh`. SSH uploads this tar, extracts and starts it remotely. No source upload or remote build. With app/web images, Web exposes the public port and proxies the internal API on the same origin; no API secrets enter Web. Online success requires both health checks. Vercel uploads existing `.vercel/output` , sets runtime variables and never builds locally.
-SQLite prebuilds must match better-sqlite3 version, Node ABI, CPU architecture and libc. Installation may still need them when runtime uses PostgreSQL. Preload prebuild-install's Linux cache or use an internal `container.sqlitePrebuildMirror`; otherwise bring the binary or a finished image. Default fullstack needs no CUDA.
+## Offline / manual transfer
-### Reuse prebuilt images through the SDK offline
+Prepare supported Node/pnpm and installed project CLI/SDK dependencies on Windows, plus the complete prebuilt image directory for the Linux server architecture. Deploy requires tar locally; automatic mode also needs ssh/scp, trusted host keys and reachable SSH/application ports. Bundle-only works with removable media and no network between machines.
-Prepare finished images before delivery. For a project named `my-app` with a Web frontend, build on the server's architecture in an environment with dependencies available:
-```powershell
-docker build --target runtime -t my-app-api:offline .
-docker build --target web -t my-app-web:offline .
-docker save -o my-app-images.tar my-app-api:offline my-app-web:offline
-```
-Import the archive into the offline Windows Linux engine with `docker load -i my-app-images.tar`. Create `packages/my-app-serv/Dockerfile` containing only:
-```dockerfile
-FROM my-app-api:offline
-```
-Add a service-package `.dockerignore` containing `*`. This makes the SDK's mandatory build reuse the finished API without package installation. Rebuild the finished image after source changes. Configure the target, then run the deployment command above. To create middleware containers, select `HAI_DB_TYPE=postgresql`, `HAI_CACHE_TYPE=redis`, `HAI_STORAGE_TYPE=s3` in `.env.prod` and choose defaults in the wizard. For existing services, enter custom connections; once complete, `--skip-middleware` is available. The SDK uploads the API image. Rehearse with internet disconnected to confirm the builder needs no network.
-Transfer the Web image separately. This example assumes separately prepared internal TLS endpoints `https://app.hai.internal` and `https://api.hai.internal`, proxying Web port 18081 and API port 18080. Bring proxy configuration/images and certificates, configure internal DNS/hosts and client certificate trust, then run over SSH:
+Linux needs Docker/Podman, compose, sh, tar, sha256sum, writable deployment/data directories and container permissions. Middleware images must already be loaded with the exact names/tags printed in the bundle README; app/web archives are included. Missing images stop startup without downloading. Custom connections require reachable running services, accounts, databases/buckets and credentials.
 ```sh
-docker load -i /path/to/my-app-images.tar
-docker run -d --name my-app-web-prod --restart unless-stopped -p 18081:8080 -e PUBLIC_API_BASE=https://api.hai.internal my-app-web:offline
+mkdir -p release && chmod 700 release
+tar -xf release-prod-1.2.3.tar -C release
+cd release
+HAI_DEPLOY_PROVIDER_REMOTE_RUNTIME=docker sh start-prod.sh
 ```
-Use a browser-reachable API URL and set API `HAI_SERV_CORS_ORIGIN=https://app.hai.internal`. Verify API `/health`, Web login/business requests, hash-route reload, session refresh, restarts and persistence. These are preparation/adaptation instructions; online deployment tests do not prove offline acceptance.
-Official references: Docker [save](https://docs.docker.com/reference/cli/docker/image/save/) / [load](https://docs.docker.com/reference/cli/docker/image/load/), [pnpm install](https://pnpm.io/cli/install), [Compose plugin installation](https://docs.docker.com/compose/install/linux/).
-## SDK and failures
-Scripts do not need the CLI. Supply parsed configuration; use public `loadDeploymentEnvironment` / `loadDeploymentConfig` for the same environment resolution:
-```typescript
-import type { DeployConfigInput } from '@h-ai/deploy'
-import { deploy } from '@h-ai/deploy'
-/**
- * 使用现有中间件发布生产 API，并释放部署模块。
- * @param config - 从部署环境解析得到的配置
- * @returns 初始化或部署的 HaiResult，由调用者检查 success
- * @example `const result = await publish(config)`
- */
-export async function publish(config: DeployConfigInput) {
-  const initialized = await deploy.init(config)
-  if (!initialized.success)
-    return initialized
-  try {
-    return await deploy.deployApp('./packages/my-app-serv', {
-      environment: 'prod',
-      envDir: '.',
-      skipProvision: true,
-    })
-  }
-  finally {
-    await deploy.close()
-  }
-}
-```
+The tar contains secrets: restrict permissions and never commit it. `packaged` means no server has been started or health-checked. After manual startup, use `docker compose -f docker-compose-1.2.3.yml --env-file .env.runtime ps` (or logs), then verify Web, /health, real login/refresh, restart and persistence. Production sessions need HTTPS, trusted certificates, DNS and correct CORS; TLS is managed separately.
-Check `result.success` before reading `error.code/message` or `data.url/healthCheck`. `deploy.scan()` and `deploy.credentials.*()` require no initialization. `deployApp()` includes provisioning, so do not also call `provisionAll()` beforehand. Check results for manual provisioning too. SDK `skipProvision` has the CLI's skip-middleware semantics.
+Prebuilt deployment needs no local container engine, Linux Node base image, compiler, CUDA or SQLite download. Fully offline **building** separately needs Linux base images, pnpm/Corepack, complete Linux dependency caches and SQLite prebuilds matching driver/ABI/architecture/libc. Windows node_modules are insufficient. Use `pnpm build --target docker --sqlite-prebuild-mirror http://trusted-host/better-sqlite3` when appropriate. No AI runtime dependency means no AI/CUDA installation. Cloud services are unsuitable offline. Prove offline behavior by actually disconnecting; online tests do not establish it.
-Cloud provisioners return whole-object `HAI_DB`, `HAI_CACHE`, `HAI_STORAGE` or `HAI_REACH_PROVIDERS`; applications must load their YAML and initialize the modules. `getDeployRecovery(result.error)` returns stage/resource IDs; verify `unknown` outcomes in the platform before retrying. Same-name retries reuse resources without automatic deletion. Types, configuration and error codes are available through the [public entry](src/index.ts).
+## SDK / development
-## Testing and development
+Call `deploy.init(config)`, check success, then `deploy.deployApp(appDir, { environment: 'prod', envDir: '.', artifactDir, bundleOnly: true })`, check success and finally `deploy.close()`. `deploy.scan` / credentials do not require init. Results return bundlePath/instructions for packaged mode, URL and health status for automatic deployment.
-After installing dependencies, run from the framework root (Windows: `pnpm.cmd`):
-```powershell
-pnpm.cmd --filter @h-ai/deploy typecheck
-pnpm.cmd --filter @h-ai/deploy lint
-pnpm.cmd --filter @h-ai/deploy build
-pnpm.cmd --filter @h-ai/deploy test
-pnpm.cmd check:skills
+```sh
+pnpm --filter @h-ai/deploy typecheck
+pnpm --filter @h-ai/deploy lint
+pnpm --filter @h-ai/deploy build
+pnpm --filter @h-ai/deploy test
+pnpm --filter @h-ai/cli test
+pnpm --filter @h-ai/cli test:scaffold-gates
+pnpm --filter @h-ai/cli test:deploy-gates
 ```
-`src/deploy-scanner.ts` handles lockfile traversal, `deploy-middleware.ts` connection fields, `container/` engines/SSH/Compose, `providers/` deployment targets and `provisioners/` cloud resources. CLI prompts live in `../cli/src/commands/cli-deploy*.ts`. Changes to backends/configuration must update consumers, environment examples, tests and the [deployment skill](../cli/templates/skills/hai-deploy/SKILL.md).
+Deploy gates generate fullstack from current archives, build API/Web once, exercise SSH and manual bundle startup and run real browser flows. Tests clean temporary projects, images, containers, screenshots/reports and helper processes in finally/teardown even on failure. Native installer acceptance requires each OS. See [configuration and middleware](../cli/templates/skills/hai-deploy/middleware.md) and [complete examples](README.md).
-For deployment changes, also run CLI typecheck/lint/build/test and `pnpm.cmd --filter @h-ai/cli test:deploy-gates`: current package archives → generated fullstack → Podman/SSH → health, environment, login and repeat deployment. This needs a local engine and OpenSSH; first fixture setup downloads images and OS/Node dependencies, so it is not an offline acceptance test. Template changes also require `pnpm.cmd --filter @h-ai/cli test:scaffold-gates`. Unit tests do not prove cloud resource creation; validate paid cloud operations separately. Keep logs/screenshots/reports in Git-ignored `tmp/` or `test-results/`.
+Deploy gates do not forward host proxies by default. To download build dependencies through a proxy, set test-only `HAI_DEPLOY_E2E_CONTAINER_PROXY` (unset by default), for example `$env:HAI_DEPLOY_E2E_CONTAINER_PROXY='http://host.containers.internal:10808'` in PowerShell for Windows Podman. The address must be reachable from build containers; it is not written to application configuration or release images.
-## License
+Test-only `HAI_DEPLOY_E2E_CONTAINER_NETWORK` is unset by default and forwards its value to build's `--network`. For example, rootless Podman can use `$env:HAI_DEPLOY_E2E_CONTAINER_NETWORK='pasta'`. Build and run networks may differ; verify the proxy address on the build network too.
-Apache-2.0
+On Windows, set test-only HAI_CLI_NATIVE_BUILD=1 (unset by default), then run `pnpm --filter @h-ai/cli test:scaffold-gates -t "fullstack scaffold"`. With Rust/MSVC/Windows SDK installed, it additionally builds the generated Tauri installer and checks that root version 2.4.6 appears in the exe filename. The temporary project and native output are cleaned automatically.

package/README.ja.md CHANGED Viewed

@@ -1,202 +1,79 @@
 # @h-ai/deploy
-[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+[简体中文](README.md) | [English](README.en.md) | [日本語](README.ja.md)
-[フレームワーク](../../README.ja.md) · [CLI](../cli/README.ja.md) · [環境とミドルウェア](../cli/templates/skills/hai-deploy/middleware.md)
+deploy は既存の成果物だけを配布します。ソースのコンパイルやイメージのビルドは行いません。同じイメージを複数環境へ配布できます。
-`@h-ai/cli` の `hai deploy` が利用するデプロイ SDK です。Node.js スクリプトから単独でも利用できます。
+作成、開発、ビルド、デプロイの全体は[使用ガイド](../../docs/usage/README.ja.md)を参照してください。本ページではデプロイの準備、SDK、モジュール開発を説明します。
-## 機能と対象範囲
+## ビルド
-| デプロイ先   | アプリ                                       | 処理                                                                                   |
-| ------------ | -------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `docker-ssh` | Node サービス、adapter-node を使う SvelteKit | ローカルでイメージをビルドし、SSH で転送、Linux の Compose で起動、HTTP ヘルスチェック |
-| `vercel`     | adapter-vercel を使う SvelteKit              | ビルド、転送、環境変数設定、結果の待機。インターネット接続が必要                       |
+Node `^22.22.2 || ^24.15.0 || >=26.0.0` と pnpm 12.11.2 を使用します。Windows では `pnpm.cmd` を実行してください。Node 20 / pnpm 9.5.0 は対象外です。
-- 対象の `pnpm-lock.yaml` importer から実行依存と workspace link をたどり、開発依存・peer を除外します。アプリ設定でバックエンドを判定し、任意の AI peer だけで AI/CUDA を有効化しません。
-- 最初に環境を選び `.env.<mode>` を確認します。各ミドルウェアは既定設定・カスタム接続・変更しないを選択でき、設定済みなら全処理を省略できます。
-- Compose は PostgreSQL、MySQL、Redis、RustFS/MinIO、Qdrant、pgvector、Chroma、OpenLDAP、Mailpit に対応します。SQLite、memory、local、LanceDB はそれぞれのローカル保存方式を使います。Mailpit はテストメール捕捉専用です。
-- クラウド作成は Neon、Upstash、Cloudflare R2、Resend、Alibaba Cloud SMS に対応します。R2 は既存の S3 鍵、Resend は検証済み送信ドメイン、SMS は承認済み署名・テンプレートが必要です。他はカスタム接続を使います。
-**fullstack の API と Web は別々にデプロイします。** `hai deploy packages/my-app-serv` は API のみが対象です。ルート Dockerfile の `runtime` / `web` target で API / 静的 Web イメージをビルドできます。Web は別途転送・起動し、`PUBLIC_API_BASE` と API の CORS を設定します。同時公開コマンド、ドメイン・TLS・リバースプロキシの自動設定はありません。
-## コマンドラインでの利用
-### 1. インストールと準備
-Node は `^22.22.2 || ^24.15.0 || >=26.0.0` が必要です。生成プロジェクトは `pnpm@12.11.2` を固定します。Node 20 / pnpm 9.5.0 は非対応です。Windows PowerShell では `pnpm.cmd` を使います。
-生成 workspace のルートでアプリのフレームワークに合う CLI/SDK をインストールし、lockfile を保持します。パッケージ配布元または完全なオフライン依存が必要です。
-```powershell
-pnpm.cmd add -Dw @h-ai/cli @h-ai/deploy
-pnpm.cmd exec hai --help
-```
-作成時の `--features deploy` はローカル SDK を追加しますが、グローバル `hai` のインストールは行いません。CLI をグローバル導入済みなら `hai deploy` を直接使えます。テンプレートの `pnpm run deploy` はパッケージ作成用で、このコマンドとは異なります。
-docker-ssh の前提条件：
-- サーバーのアーキテクチャー向け Linux イメージをビルドできるローカル Docker/Podman エンジン。Windows は仮想化/WSL2/VM の準備・起動が必要で、クライアントだけでは不足します。`auto` は Podman 優先、Docker の明示指定も可能です。
-- ローカル `ssh` / `scp`、非対話の鍵/agent 認証、サーバーのホスト指紋。
-- Linux の Docker/Podman と対応する `compose` コマンド。SSH ユーザーのコンテナ実行・ディレクトリー書き込み権限。Windows から SSH とアプリ公開ポートへ接続できること。
-- 対象パッケージの `config/_deploy.yml` と、環境ディレクトリーの `.env.prod` / `.env.test`。環境ファイルがなければ停止します。
-### 2. 接続先と環境の設定
-Docker 用の最小 `config/_deploy.yml` です。実際の接続先は `.env.local` の `HAI_DEPLOY_PROVIDER` オブジェクトで上書きします。
-```yaml
-provider:
-  type: docker-ssh
-container:
-  runtime: docker
-  s3Engine: rustfs
-services: {}
-```
-ホスト、ユーザー、ポート、鍵のパスを実際の値に置き換えます。`.env.local` は Git に登録しません。
-```dotenv
-HAI_DEPLOY_PROVIDER='{"type":"docker-ssh","ssh":{"host":"10.0.0.20","port":22,"username":"deploy","identityFile":"C:/Users/me/.ssh/hai_deploy"},"remote":{"baseDir":"/opt/hai/apps","runtime":"docker"},"expose":{"type":"port","containerPort":3000,"hostPort":18080}}'
+```sh
+pnpm build                               # ソースだけをコンパイル。環境は選択しない
+pnpm build --target docker               # 利用可能な Podman、次に Docker
+pnpm build --target docker --runtime docker
+pnpm build --target desktop --platform windows --arch x64
 ```
-未設定の接続先はウィザードでも入力できます。`.env.local` に保存して次回再利用し、秘密鍵はパスだけを保存します。接続先の変更は `HAI_DEPLOY_PROVIDER` を編集します。
-上書き順は `.env` → `.env.<mode>` → `.env.local` → プロセス環境変数です。`HAI_DB` など親 JSON が子の変数より優先されます。`.env.example` に全項目・説明・列挙値を記載し、`.env` と `.env.dev/test/prod` は Git 登録、実際の認証情報は `.env.local` に保存します。fullstack 初回起動には IAM ポリシーを満たす非公開の `HAI_ADMIN_DEFAULT_PASSWORD` も必要です。
-fullstack 本番は `.env.prod` に `HAI_SERV_CORS_ORIGIN=https://app.hai.internal` など明示的な Web Origin が必要です。既定の `*` では本番起動に失敗します。本番 refresh Cookie は Secure のため、Web/API に信頼済み HTTPS 入口を準備します。HTTP ポートの公開だけでログイン・セッション更新まで検証済みとは判定できません。
+`hai.build.json` で Dockerfile のステージと Tauri ディレクトリーを指定します。イメージと SHA-256 付きマニフェストは `.hai/build/docker/<buildId>` に出力されます。API/Web は同じビルド ID を使い、すべて成功してから latest を更新します。Tauri は対象の Windows/Linux/macOS 上で実行し、対応する Rust target、SDK、パッケージツールが必要です。インストーラーは `src-tauri/target/<target>/release/bundle` に出力されます。ビルドでは dev/test/prod を選ばず、デプロイの認証情報も取り込みません。
-### 3. デプロイ
+版はアプリルートの package.json.version を使います。例 1.2.3 では app-1.2.3.tar、web-1.2.3.tar、docker-compose-1.2.3.yml を生成します。マニフェスト形式の版は version: 2、アプリ版は appVersion です。--output release-prod.tar は release-prod-1.2.3.tar になり、Tauri も同じ版を使います。既定値と例は[完全ガイド](../../docs/usage/README.ja.md)を参照してください。
-fullstack ルートからサービス名を置き換えて実行します。
-```powershell
-pnpm.cmd exec hai deploy packages/my-app-serv --env prod --env-dir .
-```
+## デプロイ
-ウィザードは現在のバックエンドと用途を示します。既定設定は Compose サービス/ボリュームを作成し、カスタム接続では当該コンテナを作成しません。「変更しない」は対象環境ファイルに完全な設定が明示されている場合のみ表示します。公開値は対象環境、認証情報は `.env.local` に保存し、表示をマスクします。
-DB・キャッシュ・ストレージ接続がすべて設定済みの場合：
-```powershell
-pnpm.cmd exec hai deploy packages/my-app-serv --env prod --env-dir . --yes --skip-middleware
+```sh
+pnpm run deploy --env test
+pnpm run deploy --env prod --artifact-dir .hai/build/docker/<buildId> --skip-middleware
+pnpm run deploy --env prod --bundle-only --output release-prod.tar
+# fullstack で同じ処理を直接呼ぶ場合
+pnpm exec hai deploy packages/my-app-serv --env prod --env-dir .
 ```
-`--skip-middleware`（別名 `--skip-provision`）はミドルウェアの入力・設定変更・リソース作成を省略します。アプリのビルド・デプロイは行い、停止中の外部サービスを起動しません。`--yes` 単独では完全な設定を維持し、それ以外は現在のバックエンド既定値を採用します。
-`--project-name <name>` で名前を指定し、環境指定時は環境サフィックスが付きます。**`--skip-build` は現在 Vercel のアプリビルドのみを省略します。docker-ssh は必ずイメージをビルドし、既存イメージを直接指定するオプションはありません。** 失敗時は非ゼロ終了コードを返します。
-## docker-ssh の処理とファイル
-1. 対象パッケージの Dockerfile を使います。なければ workspace ルートを context にする代替 Dockerfile を生成します。fullstack サービスの既定は代替で、ルートの Web target は使いません。
-2. ローカルでビルドし、`docker/podman save` で tar を作成します。
-3. SSH で遠隔エンジンと Compose を確認し、SCP で tar を転送、遠隔で `load` します。
-4. `compose.yml`、`.env.runtime`、`start-<mode>.sh` をローカル生成して個別に `<baseDir>/<projectName>-<mode>/` へ転送します。イメージとは別送で、Compose 全体の圧縮パッケージや Linux 上でのソースビルドではありません。
-5. 遠隔スクリプトが `HAI_DEPLOY_ENVIRONMENT` / `HAI_CORE_ENV` を設定し、`compose --env-file .env.runtime ... up -d` を実行します。SDK はローカルから Node の `/health` または SvelteKit の `/` を確認して成功を返します。
-ローカル成果物は対象パッケージの Git 対象外 `.hai/deploy/<mode>/` に保存します。遠隔 `.env.runtime` は権限 `600` です。再デプロイ用にローカル成果物を保持してください。「変更しない」は前回のローカル Compose のサービス/ボリュームを維持するもので、任意の遠隔 Compose を読み込みません。非公開環境ファイル・デプロイアーカイブはイメージに含めません。
-## 完全オフラインのデプロイ
-インターネットに接続しなくても、Windows と Linux 間の内部 SSH/HTTP 通信は必要です。Vercel・クラウド作成は利用できません。
-### 事前に持ち込む材料
+対応する版の `@h-ai/cli` / `@h-ai/deploy`、`_deploy.yml`、lockfile、`.env.<mode>` が必要です。環境ファイルがなければ処理を停止します。公開設定の `.env`、`.env.dev/test/prod` と説明付き `.env.example` は Git に登録し、私有の `.env.local` は除外します。優先順位はプロセス変数 > local > 環境別 > 基本設定です。SSH の接続情報やトークンは私有の `HAI_DEPLOY_PROVIDER` JSON に保存できます。bundle-only では SSH 設定やローカルのコンテナーエンジンは不要です。
-| 場所         | 必要な材料・状態                                                                                                                                                                  |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Windows      | 対応 Node（条件を満たす Node 24 など）、pnpm 12.11.2、導入済み CLI/SDK と推移的依存、OpenSSH、初期化・起動済み Linux コンテナエンジン                                             |
-| プロジェクト | 完全なソース・固定 lockfile・環境設定・認証情報。オフラインで `pnpm.cmd exec hai --help` が成功すること。現場での `npx` / `pnpm dlx` ダウンロードを避ける                         |
-| Linux        | Docker CLI/Engine と Compose プラグイン（`docker compose version` 成功）、SSH 公開鍵登録、権限、公開ポート、書き込み先、ディスク容量。イメージ実行だけならホスト Node/pnpm は不要 |
-| イメージ     | Linux の CPU 構成と一致する API・Web・ミドルウェア。Compose と完全一致する名前/tag。`docker load -i <archive.tar>` で読み込む                                                     |
-| アプリ設定   | PostgreSQL DB/アカウント、Redis 接続/パスワード、RustFS 鍵/バケット、初回管理者パスワード。既存サービスは起動・到達可能にする。`localhost` はアプリコンテナ自身                   |
+ウィザードは lockfile の実行時依存だけをたどり、dev/peer を除外します。ミドルウェアごとに既定構成、独自構成、既存設定の保持を選べます。`--skip-middleware` はミドルウェア処理全体を省略します。Compose は PostgreSQL/MySQL/Redis/RustFS/MinIO/Qdrant/pgvector/Chroma/OpenLDAP/Mailpit に対応します。任意のクラウド作成は Neon/Upstash/R2/Resend/Aliyun SMS に対応し、ネットワーク接続が必要です。
-既定は `postgres:16-alpine`、`redis:7-alpine`、`ghcr.io/rustfs/rustfs:1.0.1` です。別 tag では自動一致しません。正しいイメージの持ち込み、互換性確認済みイメージの適切な tag 設定、またはカスタム接続が必要です。SDK はミドルウェアイメージを転送しません。他の固定イメージは [Compose 実装](src/container/deploy-container-compose.ts) を参照してください。
+`container.s3Engine` は任意で、既定値は rustfs です。Compose で S3 サービスを自動作成するときだけ RustFS/MinIO を選び、独自の既存 S3 には影響しません。ミドルウェア処理の省略は CLI の `--skip-middleware`、SDK の `skipMiddleware` で指定します。
-**既定のソースビルドは準備なしでオフライン動作しません。** Dockerfile は pnpm・パッケージ・SQLite バイナリーを取得し、fullstack ルートは `pnpm fetch` と外部 Dockerfile frontend も使用します。Windows の `node_modules` / pnpm store は Linux ビルド依存の代用になりません。現場でソースビルドする場合は Node ベースイメージ、frontend、Corepack/pnpm、Linux 依存・ネイティブキャッシュをローカルエンジン/ビルド環境に持ち込み、Dockerfile を調整し、外部接続を切って全ビルドを確認します。`pnpm install --offline --frozen-lockfile` はパッケージストア読み込みのみを対象とし、インストールスクリプトの追加取得は対象外です。
+一つの私有 tar に Compose、実行時の環境変数、app/web イメージ、必要な Web プロキシ、チェックサム、README、`start-<mode>.sh` をまとめます。SSH でこの tar を転送し、リモートで展開・起動します。ソースの転送やリモートビルドは行いません。app/web 構成では Web の公開ポートから同一オリジンで内部 API に接続し、API の秘密情報は Web に渡しません。自動デプロイの成功には両方のヘルスチェック通過が必要です。Vercel は既存の `.vercel/output` を転送して実行時変数を設定し、ローカルビルドは行いません。
-SQLite バイナリーは better-sqlite3 版、Node ABI、CPU、libc と一致する必要があります。PostgreSQL 運用でも依存導入時に必要な場合があります。Linux ビルド環境の prebuild-install キャッシュを用意するか、`container.sqlitePrebuildMirror` を内部サーバーへ向けます。どちらもなければバイナリーまたは完成イメージを事前準備します。既定の fullstack に CUDA は不要です。
+## オフラインと手動転送
-### 完成イメージを SDK 経由で利用する
+Windows 側に対応する Node/pnpm、インストール済みの CLI/SDK 依存関係、Linux サーバーのアーキテクチャーに合う構築済みイメージのディレクトリー全体を準備します。ローカルには tar が必要です。自動転送では ssh/scp、信頼済みホスト鍵、SSH とアプリのポートへの接続も必要です。bundle-only なら、二台の間にネットワークがなくても外部メディアで運べます。
-依存が使える準備環境で、完成イメージを事前作成すると現場の手順を減らせます。例は `my-app`、Web あり、サーバーと同じビルドアーキテクチャーです。
-```powershell
-docker build --target runtime -t my-app-api:offline .
-docker build --target web -t my-app-web:offline .
-docker save -o my-app-images.tar my-app-api:offline my-app-web:offline
-```
-オフライン Windows の Linux エンジンに `docker load -i my-app-images.tar` で導入します。`packages/my-app-serv/Dockerfile` は次の一行にします。
-```dockerfile
-FROM my-app-api:offline
-```
-サービスパッケージに内容 `*` の `.dockerignore` を追加します。SDK の必須ビルドは完成 API を再利用し、パッケージを取得しません。ソース変更後は完成イメージを再作成します。接続先を設定して上記デプロイを実行してください。ミドルウェアコンテナを作成するなら `.env.prod` で `HAI_DB_TYPE=postgresql`、`HAI_CACHE_TYPE=redis`、`HAI_STORAGE_TYPE=s3` を選び、ウィザードで既定設定を使います。既存サービスはカスタム接続を設定し、完了後は `--skip-middleware` も使えます。API イメージは SDK が転送します。外部接続を切ったリハーサルで、ビルダーが通信不要であることを確認します。
-Web イメージは別途転送します。以下は内網 TLS 入口 `https://app.hai.internal` / `https://api.hai.internal` が準備済みで、それぞれ Web 18081 / API 18080 を代理する前提です。プロキシ設定/イメージ・証明書を持ち込み、内部 DNS/hosts とクライアントの信頼を設定してから SSH で実行します。
+Linux 側には Docker/Podman、compose、sh、tar、sha256sum、書き込み可能な配布・データディレクトリー、コンテナー操作権限が必要です。ミドルウェアイメージは tar 内の README に記載された名前とタグで読み込んでください。app/web のアーカイブは同梱されます。イメージが不足すると、ダウンロードせずに起動を停止します。独自接続では利用可能なサービス、アカウント、DB/バケット、認証情報を準備します。
 ```sh
-docker load -i /path/to/my-app-images.tar
-docker run -d --name my-app-web-prod --restart unless-stopped -p 18081:8080 -e PUBLIC_API_BASE=https://api.hai.internal my-app-web:offline
+mkdir -p release && chmod 700 release
+tar -xf release-prod-1.2.3.tar -C release
+cd release
+HAI_DEPLOY_PROVIDER_REMOTE_RUNTIME=docker sh start-prod.sh
 ```
-API URL はブラウザーから到達可能にし、API に `HAI_SERV_CORS_ORIGIN=https://app.hai.internal` を設定します。API `/health`、Web ログイン/業務、hash ページ再読み込み、セッション更新、再起動・永続化を確認します。これは材料と適応方法の説明で、オンライン試験は実際のオフライン検証の代わりにはなりません。
-公式資料：[Docker save](https://docs.docker.com/reference/cli/docker/image/save/) / [load](https://docs.docker.com/reference/cli/docker/image/load/)、[pnpm install](https://pnpm.io/cli/install)、[Compose プラグイン](https://docs.docker.com/compose/install/linux/)。
-## SDK とエラー処理
-スクリプト利用に CLI は不要です。解析済み設定を渡し、同じ環境解決には公開 `loadDeploymentEnvironment` / `loadDeploymentConfig` を使います。
-```typescript
-import type { DeployConfigInput } from '@h-ai/deploy'
-import { deploy } from '@h-ai/deploy'
-/**
- * 使用现有中间件发布生产 API，并释放部署模块。
- * @param config - 从部署环境解析得到的配置
- * @returns 初始化或部署的 HaiResult，由调用者检查 success
- * @example `const result = await publish(config)`
- */
-export async function publish(config: DeployConfigInput) {
-  const initialized = await deploy.init(config)
-  if (!initialized.success)
-    return initialized
-  try {
-    return await deploy.deployApp('./packages/my-app-serv', {
-      environment: 'prod',
-      envDir: '.',
-      skipProvision: true,
-    })
-  }
-  finally {
-    await deploy.close()
-  }
-}
-```
+tar には秘密情報が含まれるため、アクセス権を制限し、Git に登録しないでください。`packaged` はサーバー起動やヘルスチェックをまだ行っていない状態です。手動起動後は `docker compose -f docker-compose-1.2.3.yml --env-file .env.runtime ps`（または logs）、Web、/health、実際のログインと再読み込み、再起動とデータ保持を確認します。本番のセッションには HTTPS、信頼できる証明書、DNS、正しい CORS が必要で、TLS は別途設定します。
-`result.success` を確認してから `error.code/message` または `data.url/healthCheck` を読みます。`deploy.scan()` / `deploy.credentials.*()` は初期化不要です。`deployApp()` がリソース作成を含むため、事前の `provisionAll()` は不要です。手動作成も結果を確認します。SDK `skipProvision` は CLI のミドルウェア省略と同じ意味です。
+構築済み成果物の配布には、ローカルのコンテナーエンジン、Linux Node ベースイメージ、コンパイラー、CUDA、SQLite のダウンロードは不要です。完全オフラインでの**ビルド**には、別途 Linux ベースイメージ、pnpm/Corepack、Linux 用依存キャッシュ一式、driver/ABI/アーキテクチャー/libc が一致する SQLite バイナリーが必要です。Windows の node_modules だけでは足りません。必要に応じて `pnpm build --target docker --sqlite-prebuild-mirror http://trusted-host/better-sqlite3` を使えます。AI の実行時依存がなければ AI/CUDA は不要です。クラウドサービスはオフラインでは使えません。完全オフラインの動作は実際に接続を切って確認してください。
-クラウドは `HAI_DB`、`HAI_CACHE`、`HAI_STORAGE`、`HAI_REACH_PROVIDERS` 全体を返し、アプリは対応 YAML の読み込みとモジュール初期化が必要です。`getDeployRecovery(result.error)` は段階・リソース ID を返します。`unknown` は管理画面で確認してから再試行します。同名再試行は既存リソースを再利用し、自動削除しません。型・設定・エラーコードは [公開エントリー](src/index.ts) を参照してください。
+## SDK とモジュール開発
-## テストと開発
+`deploy.init(config)` の成功を確認してから `deploy.deployApp(appDir, { environment: 'prod', envDir: '.', artifactDir, bundleOnly: true })` を呼び、結果を確認し、最後に `deploy.close()` を実行します。`deploy.scan` と credentials は初期化不要です。packaged の結果には bundlePath/instructions、自動デプロイの結果には URL とヘルス状態が入ります。
-依存導入後、フレームワークルートで実行します（Windows は `pnpm.cmd`）。
-```powershell
-pnpm.cmd --filter @h-ai/deploy typecheck
-pnpm.cmd --filter @h-ai/deploy lint
-pnpm.cmd --filter @h-ai/deploy build
-pnpm.cmd --filter @h-ai/deploy test
-pnpm.cmd check:skills
+```sh
+pnpm --filter @h-ai/deploy typecheck
+pnpm --filter @h-ai/deploy lint
+pnpm --filter @h-ai/deploy build
+pnpm --filter @h-ai/deploy test
+pnpm --filter @h-ai/cli test
+pnpm --filter @h-ai/cli test:scaffold-gates
+pnpm --filter @h-ai/cli test:deploy-gates
 ```
-`src/deploy-scanner.ts` が lockfile 走査、`deploy-middleware.ts` が接続項目、`container/` がエンジン・SSH・Compose、`providers/` がデプロイ先、`provisioners/` がクラウド作成を担当します。CLI ウィザードは `../cli/src/commands/cli-deploy*.ts` です。バックエンド/設定変更時は利用側、環境例、テスト、[デプロイ skill](../cli/templates/skills/hai-deploy/SKILL.md) を同期します。
+デプロイのゲートは現在のソースをパッケージ化して fullstack を生成し、API/Web を一度構築してから、SSH と手動 tar の起動、実際のブラウザー操作を検証します。失敗時も finally/teardown で一時プロジェクト、イメージ、コンテナー、スクリーンショット・レポート、補助プロセスを削除します。ネイティブインストーラーは各 OS での確認が必要です。[設定とミドルウェア](../cli/templates/skills/hai-deploy/middleware.md)、[詳細な例](README.md)も参照してください。
-処理変更後は CLI の typecheck/lint/build/test と `pnpm.cmd --filter @h-ai/cli test:deploy-gates` を実行します。現在のパッケージから fullstack を生成し、Podman/SSH でヘルス・環境・ログイン・再デプロイを確認します。ローカルエンジンと OpenSSH が必要で、初回はイメージ・OS/Node 依存を取得するためオフライン検証ではありません。テンプレート変更時は `pnpm.cmd --filter @h-ai/cli test:scaffold-gates` も実行します。単体テストでクラウド作成済みとは判定せず、有料操作は別途検証します。ログ・画像・報告は Git 対象外の `tmp/` / `test-results/` に保存します。
+デプロイのゲートは既定でホストのプロキシを転送しません。依存のダウンロードに必要な場合、テスト専用 `HAI_DEPLOY_E2E_CONTAINER_PROXY`（既定は未設定）を設定します。Windows Podman の PowerShell の例は `$env:HAI_DEPLOY_E2E_CONTAINER_PROXY='http://host.containers.internal:10808'` です。ビルドコンテナーから到達できるアドレスを使い、アプリ設定や配布イメージには保存しません。
-## License
+テスト専用 `HAI_DEPLOY_E2E_CONTAINER_NETWORK` は既定では未設定で、設定値を build の `--network` に渡します。rootless Podman の例は `$env:HAI_DEPLOY_E2E_CONTAINER_NETWORK='pasta'` です。build と run ではネットワークが異なる場合があるため、ビルド側でプロキシの到達性も確認してください。
-Apache-2.0
+Windows ではテスト専用 HAI_CLI_NATIVE_BUILD=1（既定は未設定）を指定し、`pnpm --filter @h-ai/cli test:scaffold-gates -t "fullstack scaffold"` を実行できます。Rust/MSVC/Windows SDK が必要で、生成 Tauri インストーラーの exe 名にルート版 2.4.6 が反映されることを確認します。一時プロジェクトとネイティブ出力も自動削除します。