@h-ai/deploy 1.0.0-beta.22 → 1.0.0-beta.24

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/deploy",
   "type": "module",
-  "version": "1.0.0-beta.22",
+  "version": "1.0.0-beta.24",
   "description": "Hai Framework deployment automation module.",
   "license": "Apache-2.0",
   "exports": {
@@ -24,14 +24,14 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.12.1"
   },
   "dependencies": {
-    "@h-ai/api-contract": "1.0.0-beta.22",
-    "@h-ai/core": "1.0.0-beta.22",
-    "@h-ai/crypto": "1.0.0-beta.22",
+    "@h-ai/api-contract": "1.0.0-beta.24",
+    "@h-ai/core": "1.0.0-beta.24",
+    "@h-ai/crypto": "1.0.0-beta.24",
     "yaml": "^2.9.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@h-ai/reldb": "1.0.0-beta.22",
+    "@h-ai/reldb": "1.0.0-beta.24",
     "@types/node": "^26.6.6",
     "rimraf": "^6.1.4",
     "tsup": "^9.0.0",

package/docs/credential-import.en.md

@@ -1,40 +0,0 @@
-# Importing and recovering legacy deployment credentials
-
-Ordinary deployment still stops when existing volumes have no managed-secrets.env. Never delete volumes, generate replacement passwords, truncate old values or copy random candidates from a new bundle.
-
-Run matching installed CLI/deploy versions with supported Node on the target Linux server as its deployment owner or administrator. Ordinary offline deployment does not require server Node. Stop business writes, exclude old deployment processes, and back up the database, objects, volumes, original credentials, current and successful release before importing. Import does not stop services, rotate passwords, migrate databases or advance current.
-
-Original services must remain running. Verification checks Compose project/service labels and actual volume mounts, then authenticates read-only: PostgreSQL/MySQL SELECT 1, LDAP bind, or S3 bucket HEAD. S3 uses the same project's running hai-<projectName>-app Node container on a shared network without installing tools or writing client configuration. Keep the application in maintenance mode. Missing tools, wrong credentials or mismatched identity are rejected.
-
-PostgreSQL uses a non-loopback connection and explicitly requires require_auth=scram-sha-256,md5,password (psql/libpq 16+), rejecting trust or incomplete authentication. For both application and root accounts, MySQL must accept the supplied password and reject a random incorrect password with an authentication error; bypassed authorization cannot pass. See [libpq authentication requirements](https://www.postgresql.org/docs/16/libpq-connect.html#LIBPQ-CONNECT-REQUIRE-AUTH).
-
-Create an operator-approved, non-symlink JSON input with mode 0600. Its version is 1; projectName includes the environment suffix and excludes the automatic hai- prefix. Example structure:
-
-```json
-{
-  "version": 1,
-  "projectName": "shop-test",
-  "credentials": { "DB_PASSWORD": "original-password-from-protected-source" },
-  "services": [{
-    "service": "db", "kind": "postgresql", "container": "hai-shop-test-db",
-    "volumes": ["hai-shop-test_shop-test-db-data"], "username": "hai", "database": "hai"
-  }]
-}
-```
-
-Replace every example identifier and password placeholder with verified original values. List only managed services: db/vecdb share DB_PASSWORD, storage uses STORAGE_PASSWORD, ldap uses LDAP_PASSWORD. Supported kinds are postgresql/mysql/s3/ldap. S3 fields accessKeyId, bucket and region default to hai-storage, hai and us-east-1. LDAP bindDn defaults to cn=admin,dc=example,dc=org. Passwords preserve spaces, quotes, backslashes, dollar signs and Unicode; empty values, newlines, NUL and control characters are rejected. Every specified volume must belong to the verified service.
-
-Managed sidecars currently require account/database hai, S3 hai-storage/bucket hai/us-east-1, and the default LDAP bindDn. MySQL additionally verifies that root and application passwords match. Custom identities are explicitly rejected rather than silently changed after import; retain their external middleware configuration or plan a separate identity migration.
-
-```sh
-chmod 600 /private/shop-import.json
-hai deploy-secrets /opt/hai/apps/shop-test --import /private/shop-import.json --runtime docker
-# Review the value-free receipt before committing.
-hai deploy-secrets /opt/hai/apps/shop-test --import /private/shop-import.json --runtime docker --apply
-```
-
-SDK: importDeploymentSecrets({ directory, inputFile, runtime, dryRun: true }). Only dryRun:false commits. Preflight creates no lock or state file. Apply shares the fixed deployment flock, writes a private temporary file, fsyncs it, atomically publishes v2 state with mode 0600 and syncs the directory. It does not replace the lock file. Identical imports are repeatable; conflicting, damaged or symlink states are rejected. A failed receipt with error.ext.state=unknown requires checking state before retrying: a missing receipt does not prove that commit never happened.
-
-V2 stores passwords as UTF-8 hexadecimal, which is **encoding, not encryption**. Protect state and backups as secrets. Project and verified volume bindings prevent reusing state for unrelated data. Runtime files correctly serialize dotenv, JSON and URL passwords. Existing new-project random-password state remains supported without mandatory conversion.
-
-Regenerate a complete fixed bundle while retaining project, directory and volume identities. Verify old database records, S3 objects and hashes before resuming writes. Subsequent full/partial deployment, another packaging machine, and stop/recovery reuse server credentials. Restore a protected matching backup first if state is lost; otherwise reverify trusted original credentials against running original services and import again. Isolate damaged/symlink state for investigation. Interrupted .managed-secrets-*.next files are never treated as committed state. Only clean identified temporary files after checking that no import/deployment process remains. Failure does not advance current or delete volumes. Binary rollback uses a successful release and the same credentials; data recovery follows the backup plan. Password rotation is a separate controlled operation.

package/docs/credential-import.ja.md

@@ -1,40 +0,0 @@
-# 旧デプロイ認証情報の導入と復旧
-
-既存ボリュームに managed-secrets.env がない通常配布は引き続き停止します。ボリューム削除、新しいパスワード生成、旧値の切り詰め、新パッケージのランダム候補の転用は行わないでください。
-
-対象 Linux サーバーで、配置所有者または管理者として対応 Node と同じ版の CLI/deploy を実行します。通常のオフライン配布にサーバー Node は不要です。旧デプロイ処理を終了し、業務書込を停止して、DB・オブジェクト・ボリューム・旧認証情報・current・成功済みリリースをバックアップしてください。導入はサービス停止、パスワード変更、DB移行、current更新を行いません。
-
-旧サービスは起動したままにします。Compose のプロジェクト/サービスラベルと実マウントを確認し、旧認証情報で読み取り専用検証を行います。PostgreSQL/MySQL は SELECT 1、LDAP は bind、S3 は bucket HEAD です。S3 は同じプロジェクトとネットワークの hai-<projectName>-app Node コンテナを使い、ツール導入やクライアント設定保存をしません。アプリは書込停止の保守状態にしてください。ツール不足、誤認証、異なる所有関係では拒否します。
-
-PostgreSQL は非ループバック接続と require_auth=scram-sha-256,md5,password（psql/libpq 16以降）で trust や未完了認証を拒否します。MySQL はアプリと root の両方で正しいパスワードの成功とランダムな誤パスワードの認証拒否を確認し、認可を迂回する設定も拒否します。[libpq の認証要件](https://www.postgresql.org/docs/16/libpq-connect.html#LIBPQ-CONNECT-REQUIRE-AUTH)を参照してください。
-
-運用者が確認した秘密情報から、0600かつシンボリックリンクでないJSONを用意します。入力 version は1、projectName は環境接尾辞を含み、自動付与される hai- は除きます。
-
-```json
-{
-  "version": 1,
-  "projectName": "shop-test",
-  "credentials": { "DB_PASSWORD": "保護された情報源から取得した元のパスワード" },
-  "services": [{
-    "service": "db", "kind": "postgresql", "container": "hai-shop-test-db",
-    "volumes": ["hai-shop-test_shop-test-db-data"], "username": "hai", "database": "hai"
-  }]
-}
-```
-
-識別子とパスワード例は必ず実際の旧値へ置換してください。db/vecdb は同じ DB_PASSWORD、storage は STORAGE_PASSWORD、ldap は LDAP_PASSWORD を使用します。kind は postgresql/mysql/s3/ldap。S3 の accessKeyId/bucket/region の既定は hai-storage/hai/us-east-1、LDAP bindDn は cn=admin,dc=example,dc=org です。空白・引用符・バックスラッシュ・ドル記号・Unicode は保持し、空値・改行・NUL・制御文字は拒否します。指定ボリュームは検証済みサービスへマウントされている必要があります。
-
-現在の管理対象 sidecar は hai アカウント/DB、S3 の hai-storage/桶 hai/us-east-1、LDAP の既定 bindDn を要求します。MySQL は root とアプリの同じパスワードも確認します。独自の識別情報は勝手に変更せず拒否し、外部ミドルウェアの元設定を維持するか別の識別情報移行を計画してください。
-
-```sh
-chmod 600 /private/shop-import.json
-hai deploy-secrets /opt/hai/apps/shop-test --import /private/shop-import.json --runtime docker
-# 値を含まない検査結果を確認してから確定します。
-hai deploy-secrets /opt/hai/apps/shop-test --import /private/shop-import.json --runtime docker --apply
-```
-
-SDK は importDeploymentSecrets({ directory, inputFile, runtime, dryRun: true })、確定は dryRun:false のみです。検査はロック/状態ファイルを作りません。確定は固定デプロイ flock を共有し、非公開一時ファイルを fsync 後に0600で原子的に公開してディレクトリを同期します。ロックを置換しません。同じ入力は再実行可能で、競合・破損・リンク状態は上書きしません。error.ext.state=unknown の失敗は状態確認が必要です。応答がないことは未確定の証明ではありません。
-
-v2 の UTF-8 十六進表現は**符号化であり暗号化ではありません**。状態とバックアップを秘密として保護してください。プロジェクト/検証済みボリュームを束縛し、dotenv・JSON・URL を正しく生成します。新規プロジェクトの従来ランダム状態は引き続き利用でき、変換を強制しません。
-
-同じプロジェクト・配置先・ボリュームの完全パッケージを再生成し、旧DBレコード・S3オブジェクト・ハッシュを確認してから書込を再開します。完全/部分配布、別の梱包端末、停止/復旧もサーバー状態を再利用します。状態喪失時は対応する保護バックアップを優先し、なければ旧サービスに対し元の認証情報を再検証して導入します。破損/リンクは隔離して調査してください。中断した .managed-secrets-*.next は確定状態として採用されません。プロセス終了確認後に今回所有する一時ファイルだけを清掃します。失敗しても current やデータボリュームを変更しません。旧リリースへ戻す場合も同じ認証情報を使い、データ復元はバックアップ計画に従います。パスワード変更は別の管理された操作です。

package/docs/credential-import.md

@@ -1,70 +0,0 @@
-# 旧部署凭据导入与恢复
-
-已有卷却缺少 `managed-secrets.env` 时，普通部署继续停止。不要删除卷、重新生成密码、截断旧密码或手工复制新包的随机候选。
-
-## 前置条件
-
-在目标 Linux 服务器以部署目录所有者或管理员运行已安装且版本一致的 CLI/deploy，使用框架支持的 Node。普通离线部署仍不需要服务器 Node。确认没有旧部署进程，停止业务写入，备份数据库、对象、卷、原凭据和 current/成功发布目录，记录恢复点。导入不停止服务、不轮换密码、不运行数据库迁移，也不会推进 current。
-
-原中间件必须仍在运行。工具核验 Compose 项目/服务标签和实际挂载卷，并用原凭据执行只读检查：PostgreSQL/MySQL `SELECT 1`、LDAP bind、S3 bucket HEAD。S3 验证使用同项目且共享网络的 `hai-<projectName>-app` Node 容器，不安装额外服务、不写客户端配置；此时应用可处于停写维护状态。缺验证工具、错误密码、错误项目/卷均拒绝，不降级成“信任旧包”。
-
-PostgreSQL 使用非回环连接并显式要求 libpq 的 require_auth=scram-sha-256,md5,password，拒绝 trust 或未完成认证；因此需要 psql/libpq 16+，不支持时停止。MySQL 对应用和 root 同时执行正向认证和随机错误密码的反向认证；正确密码须成功，错误密码须收到认证拒绝，因此跳过授权校验也不能通过。参考 [libpq 认证要求](https://www.postgresql.org/docs/16/libpq-connect.html#LIBPQ-CONNECT-REQUIRE-AUTH)。
-
-## 私有输入
-
-从操作者确认的秘密来源建立权限 0600、非软链接的 JSON 文件，不提交 Git。下例密码文字仅为占位，须替换为原服务的真实密码；容器、用户名、数据库、bucket 和卷名必须与旧部署实际值一致。`projectName` 包含环境后缀，但不包含自动添加的 `hai-` 前缀。
-
-```json
-{
-  "version": 1,
-  "projectName": "shop-test",
-  "credentials": {
-    "DB_PASSWORD": "从受保护来源取得的原数据库密码",
-    "STORAGE_PASSWORD": "从受保护来源取得的原对象存储密码"
-  },
-  "services": [
-    {
-      "service": "db",
-      "kind": "postgresql",
-      "container": "hai-shop-test-db",
-      "volumes": ["hai-shop-test_shop-test-db-data"],
-      "username": "hai",
-      "database": "hai"
-    },
-    {
-      "service": "storage",
-      "kind": "s3",
-      "container": "hai-shop-test-storage",
-      "volumes": ["hai-shop-test_shop-test-storage-data"],
-      "accessKeyId": "hai-storage",
-      "bucket": "hai",
-      "region": "us-east-1"
-    }
-  ]
-}
-```
-
-只列实际托管的服务与凭据组：db/vecdb 使用 DB_PASSWORD（两者存在时密码必须一致），storage 使用 STORAGE_PASSWORD，ldap 使用 LDAP_PASSWORD。kind 支持 postgresql/mysql/s3/ldap；LDAP 可填写 bindDn，默认 `cn=admin,dc=example,dc=org`。所有指定卷均须挂载到已验证服务。密码支持空格、引号、反斜杠、美元符号及 Unicode，不允许空值、换行、NUL 或其他控制字符；不会转换、截断或替换密码。
-
-当前受管 sidecar 固定 PostgreSQL/MySQL 的 hai 账户与 hai 数据库、S3 的 hai-storage/桶 hai/us-east-1、LDAP 的默认 bindDn。MySQL 还会核验 root 与应用密码一致。自定义身份不能仅凭密码导入：工具明确拒绝，应保留外部中间件模式的原连接，或先制定独立的身份迁移方案。
-
-## 预检与提交
-
-```sh
-chmod 600 /private/shop-import.json
-hai deploy-secrets /opt/hai/apps/shop-test --import /private/shop-import.json --runtime docker
-# 核对只含项目、凭据组和卷名的回执；此步骤不创建锁或状态文件。
-hai deploy-secrets /opt/hai/apps/shop-test --import /private/shop-import.json --runtime docker --apply
-```
-
-SDK 对应 `importDeploymentSecrets({ directory, inputFile, runtime, dryRun: true })`；只有 dryRun:false 提交。apply 复用固定 `.deploy.lock`，不删除/替换锁文件。持锁进程创建私有临时文件、fsync 后原子发布 v2 状态并同步目录；锁或验证失败不启动服务。相同输入可重复导入，既有不同/损坏状态不被覆盖。返回失败且 error.ext.state 为 unknown 时，先核对状态文件；不要将未收到提交回执解释为未写入。
-
-v2 的密码使用 UTF-8 十六进制编码，**编码不提供加密**，状态与备份仍是秘密，必须保持 0600。状态绑定项目及已验证卷，后续部署正确派生 dotenv、JSON 与 URL 编码，不把特殊字符当脚本执行。普通新项目仍可沿用已有随机凭据状态；无需强制迁移。
-
-## 后续交付与恢复
-
-保持原项目名、卷名与部署目录，使用当前 CLI 生成新部署 ID 的完整包。导入不创建成功基线；没有 `current` 时，首次接管必须完整全量，不能带 `--services` 或使用部分构建。只有完整部署成功后，才可按成功基线增量更新。先核对原 DB 记录、S3 对象及摘要，再恢复写入；导入与容器接管不执行数据库数据恢复或格式迁移。
-
-对 `db`、`storage`、`vecdb` 的未认领旧卷，后续部署同时核对合法 v2 中的项目、凭据组和精确卷绑定，以及同项目/服务的唯一运行原容器：Docker/Podman 标签不得冲突，实际命名卷与 Config.Image 家族必须匹配候选。db 与 vecdb 虽共用 DB_PASSWORD，仍分别核验服务角色。FORMAT1、停止的原容器、缺失或不一致的标签/挂载/镜像均不能替代证据。已知 `persistent-backends` 绑定冲突或 daemon/store 身份变化不会因导入放行；先恢复原运行环境，或另行制定数据迁移方案，不编辑/删除账本强行接管。
-
-状态丢失时，优先恢复与该项目/卷对应的受保护备份；没有备份但拥有可信原凭据时，原服务运行期间重新预检并导入。损坏或软链接状态必须先隔离并核对来源，不能让工具盲目覆盖。中断留下的 `.managed-secrets-*.next` 不是已提交状态，普通部署不会采用它；只在确认没有部署/导入进程后核对并清理本次文件。导入失败不修改 current、不删除数据卷。回退部署沿用成功发布与相同服务器凭据，数据恢复遵循备份方案；凭据轮换属于独立的受控操作。