@h-ai/cli 0.1.0-alpha.56 → 0.1.0-alpha.58

package/README.en.md

@@ -0,0 +1,239 @@
+# @h-ai/cli
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
+
+> hai Agent Framework CLI: interactive project scaffolding and code generation.
+
+## Capabilities
+
+`hai deploy` exits nonzero on missing modules/configuration, credential loading, scanning, initialization, deployment, or closure failures. Scripts must check the exit code; only complete deployment success can unlock subsequent steps.
+
+- **Project creation**: guided creation of SvelteKit apps, Svelte 5 mobile/desktop frontends, and hai backends.
+- **Module addition**: incrementally enable modules in an existing project with dependency resolution.
+- **Configuration initialization**: validate completeness and create missing configuration files.
+- **Code generation**: pages, components, API endpoints, data models, and migrations.
+- **Templates**: minimal / default / full / custom project templates.
+- **Feature composition**: enable IAM, DB, AI, Storage, Crypto, and more as needed.
+- **API service scaffolding**: compose contracts/procedures with `@h-ai/api-contract` + `@h-ai/serv`, consumed through the `@h-ai/api-client` typed client.
+- **Dependency resolution**: selecting features automatically includes their dependencies (for example, IAM adds Crypto).
+
+## AI usage guidance
+
+Claude Code v2.1.277 and later can also read root `AGENTS.md` directly when no higher-priority project CLAUDE file overrides it and the built-in support is enabled. The single-line `@AGENTS.md` bridge supports older or disabled sessions without duplicating instructions or requiring a `.claude/` directory. See [AGENTS.md support](https://code.claude.com/docs/en/memory#agentsmd).
+
+The CLI copies complete selected skill directories from `templates/skills/` into the generated project's `.agents/skills/`. `SKILL.md` defines boundaries and task navigation; `reference.md`/`guide.md` hold on-demand examples. Do not copy only the entry file. AGENTS.md holds application constraints and Claude/Copilot bridge files reference it. Template changes must sync relevant repository skills. Generation tests verify delivery of reference files.
+
+For everyday feature additions, changes and fixes, `AGENTS.md` routes to `hai-app-create/SKILL.md` and `development.md`. Map requirements to existing framework features, configuration and extension points before implementing against the installed package's exports and types. Reuse applicable capabilities and explain concrete gaps; do not install unrelated dependencies to increase module coverage. Codex uses `.agents/skills/` and the project root's persistent `AGENTS.md` rules.
+
+Tool entry points share one set of rules and skills: Codex/Cursor use AGENTS and `.agents/skills/`; Copilot uses `.github/copilot-instructions.md` and shared skills; OpenCode uses AGENTS, opencode.json and shared skills. Claude Code's root CLAUDE.md contains only `@AGENTS.md`; task navigation in the shared rules leads to skill bodies and references in `.agents/skills/` as needed. The CLI does not create `.claude/`, duplicate skills or require symlinks. This setup does not register native Claude skills or `/skill` commands; existing Claude settings and skills are preserved. Sources: [Claude project instructions](https://code.claude.com/docs/en/memory), [Claude native skills](https://code.claude.com/docs/en/skills), [Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills), [OpenCode](https://docs.opencode.ai/docs/skills/), [Cursor](https://cursor.com/docs/skills).
+
+Generated projects share `eslint-rules.js`. Lint rejects explicit `any`, console calls, unexplained suppressions, double unknown assertions, internal framework source imports and writes to known sensitive localStorage keys. A necessary third-party workaround requires a documented local exception. Static rules do not prove authorization, input safety, transaction behavior or log redaction; verify those through tests and review.
+
+For existing projects, update the CLI and run `hai init` to fill missing workflow skills, resources and entry files. Existing files are preserved, including AI rules when using `--force`. Merge existing entry files, skills, ESLint configuration and scripts against a newly generated project, and restore missing .npmrc/.gitignore files; filling missing files does not upgrade old rules. Before release, use the CLI built from this repository to create the comparison project and keep unpublished capabilities separate from installed package capabilities.
+
+Before writing AI files, the CLI resolves existing file and directory links. Shared skills and project bridges must stay inside the project; external targets stop the write. Existing `.claude/` directories and links are outside generation; `hai init` / `hai add` do not modify or delete their contents.
+
+Delivery checks cover both the package archive and generated projects. Source `.npmrc` / `.gitignore` templates use a `.hbs` suffix to avoid packaging exclusions; generation restores their normal names and preserves dependency layout and sensitive-artifact ignore rules. An archive regression verifies every template is in the `.tgz`, beyond creation from the source checkout.
+
+## Quick start
+
+Requires Node.js 22.22.2+ / 24.15.0+ / 26+; generated root projects and workspace packages declare the same minimum.
+
+### Create a project
+
+```bash
+# 交互式创建（推荐）
+npx hai create my-admin-app
+
+# 指定模板与功能
+npx hai create my-app -t full
+npx hai create my-app -t custom -f iam,db,ai
+```
+
+Interactive steps:
+
+1. Enter the project name.
+2. Choose a template (minimal / default / full / custom).
+3. Select feature modules (custom template).
+4. Choose whether to include example code.
+5. Choose a package manager (pnpm / npm / yarn).
+6. Choose whether to install dependencies.
+7. Choose whether to initialize Git.
+
+### Add modules
+
+```bash
+# 交互式选择
+npx hai add
+
+# 指定模块
+npx hai add iam
+npx hai add storage
+```
+
+Add modules incrementally to an existing project. The CLI updates `package.json`, creates configuration, and resolves dependencies.
+
+### Initialize/validate configuration
+
+```bash
+# 校验配置完整性，补全缺失配置
+npx hai init
+
+# 强制重新生成所有配置
+npx hai init --force
+```
+
+### Code generation
+
+Names must start with a letter and contain only letters, digits, hyphens, or underscores; paths are rejected. All outputs are preflighted and overwrites rejected by default; only explicit `--force` replaces files. Outputs and symlink targets must stay in the working directory.
+
+Page/API generators target SvelteKit; components use Svelte 5 children snippets. APIs use `kit.handler` and Zod validation. Migrations export explicit `up()` / `down()`; initialize `reldb` before calling and check HaiResult afterward. This is not an automatic migration runner. `down()` deletes tables and requires application confirmation before execution.
+
+```bash
+# 交互式生成
+npx hai generate
+
+# 指定类型
+npx hai generate page users
+npx hai generate component UserCard
+npx hai generate api users
+npx hai generate model user
+npx hai generate migration add-users
+
+# 快捷命令
+npx hai g:page dashboard
+npx hai g:component StatusBadge
+npx hai g:api orders
+npx hai g:model order
+```
+
+## Project templates
+
+| Template  | Description | Included features                                         |
+| --------- | ----------- | --------------------------------------------------------- |
+| `minimal` | Minimal     | Basic SvelteKit/hai skeleton (Svelte 5 + Vite on mobile)  |
+| `default` | Default     | IAM + DB + Cache + Crypto                                 |
+| `full`    | Full        | All business modules + API Service / contract integration |
+| `custom`  | Custom      | Choose as needed                                          |
+
+## Fullstack mini administration
+
+`--type fullstack` generates an administration workspace with IAM, reldb, cache, audit, storage and crypto by default. The required management modules remain enabled even with the minimal preset. `--frontends` selects Web, Capacitor App and Tauri Desktop; miniapp remains a documentation placeholder excluded from runtime and builds.
+
+```powershell
+npx hai create mini-admin --type fullstack --frontends web,app,desktop
+cd mini-admin
+pnpm.cmd install
+pnpm.cmd dev
+```
+
+The CLI generates a root `.env` with a unique random strong `HAI_ADMIN_DEFAULT_PASSWORD`, so `dev` / `start` work directly. Sign in as `admin` using that password; an environment variable with the same name overrides it. Passwords follow `_iam.yml` policy, with a default minimum of 8 characters. Startup logs include the specific validation reason and error code when a password violates the policy. Once users exist, the variable does not reset accounts or passwords. Git and container builds ignore `.env`, while `.env.example` contains only a placeholder. Set a separate password in each deployment environment.
+
+- Administrators can search, paginate, create, edit, enable, disable and delete users and upload avatars. The server protects the current administrator and rechecks authorization inside a mutation lock so concurrent actions cannot remove every administrator's access.
+- Roles are fixed as `admin` / `user`. The role page shows member counts and edits descriptions; the user page assigns roles. Ordinary users only access personal settings, and the server rejects direct management API calls from them.
+- The audit page filters by action, resource and date. Successful login, logout, password changes and management writes produce audit records without passwords, tokens or avatar contents.
+- Personal settings cover profile, avatar, language, theme and password changes. Preferences are stored in IAM user metadata. Avatars accept PNG/JPEG/WebP up to 512 KiB; the server validates image contents and generates the storage key.
+
+The typed api-client and serv crypto transport encrypt JSON business requests, login and refresh in both directions. Web uses an in-memory access token and an HttpOnly refresh Cookie. Native App uses Capacitor secure TokenStorage; native Desktop stores tokens only in memory and requires login after restart. The native refresh body channel verifies the client identifier, explicit transport header and trusted Origin; browser previews use Cookie mode. Public avatars are binary image resources restricted by a whitelist.
+
+Web/App/Desktop share one `AdminWorkspace`, management store and typed client. Current-user and refresh routes use the framework's default IAM procedures; theme caching and DOM updates use `@h-ai/ui/theme`. Application code composes fixed roles, self-protection, avatars and business auditing.
+
+Default SQLite, local storage and memory cache suit a single-instance mini administration service. Management writes support one writer instance. Multiple read instances require shared database, storage, Redis cache and sticky transport sessions; all management writes must still reach the same writer. Redis alone does not provide atomic last-administrator protection across arbitrary writers. Generated root scripts provide typecheck, lint, build, test and test:e2e; Capacitor/Tauri delivery additionally requires the appropriate native build and packaging.
+
+## Application configuration and display
+
+Every template reads `name`, `version`, `env`, `defaultLocale` and `logging` from `_core.yml`, obtains metadata through `core.config` and uses `core.logger`. Single-app configuration lives in `config/`, API workspace configuration in `apps/<project>-service/config/`, and fullstack configuration in `packages/<project>-serv/config/`. YAML controls log level and format; initialization does not replace them with a fixed `logging` option.
+
+Core environment overrides include `HAI_CORE_NAME`, `HAI_CORE_VERSION`, `HAI_CORE_ENV` and `HAI_CORE_LOGGING_LEVEL`; a whole `HAI_CORE` override follows parent-node precedence. Restart services after server configuration changes. Containers explicitly set `HAI_CORE_ENV=production`, which enables production security policy.
+
+SvelteKit server layouts expose only whitelisted public metadata such as name, version, environment and default locale. Standalone mobile-app Vite configuration parses YAML through core in the Node build process and injects public values plus browser logging level/format; YAML or override changes require a rebuild. Fullstack frontends obtain public server metadata through encrypted `app.info`. No template exposes complete core/module configuration, secrets or log-redaction context to the browser.
+
+## Global options
+
+| Option             | Description               |
+| ------------------ | ------------------------- |
+| `-v, --verbose`    | Verbose output            |
+| `-C, --cwd <path>` | Set the working directory |
+
+## Local development usage
+
+> For local CLI development in the monorepo before publishing to npm.
+
+### 1. Build
+
+```bash
+# 构建 CLI（生成 dist/）
+pnpm --filter @h-ai/cli build
+
+# 或启动 watch 模式（修改源码后自动重建）
+pnpm --filter @h-ai/cli dev
+```
+
+### 2. Run directly (no installation)
+
+After building, invoke `dist/index.js` directly with `node`:
+
+```bash
+# 从仓库根目录运行
+node packages/cli/dist/index.js create my-app
+node packages/cli/dist/index.js create my-app --type admin --features iam,db
+```
+
+Or invoke it by absolute path from any directory:
+
+```bash
+node /path/to/hai-framework/packages/cli/dist/index.js create my-app
+```
+
+### 3. Global linking (`pnpm link`)
+
+To use `hai` directly in a terminal, create a global link:
+
+```bash
+# 在 packages/cli 目录下执行
+cd packages/cli
+pnpm link --global
+
+# 验证
+hai --version
+hai create my-app
+```
+
+> Remove the link afterward with `pnpm unlink --global @h-ai/cli`.
+
+### 4. Use in other monorepo apps
+
+Projects in `apps/*` reference local packages through `workspace:*` and can use them directly:
+
+```bash
+# 在仓库根目录执行，对任意 app 类型生成项目
+node packages/cli/dist/index.js create ../my-new-project
+```
+
+### 5. Run tests
+
+```bash
+# 单元测试 + E2E 模板生成测试
+pnpm --filter @h-ai/cli test
+
+# 真实脚手架 E2E 门禁（生成项目后执行 install/typecheck/lint/build/test/e2e）
+pnpm --filter @h-ai/cli test:e2e
+
+# watch 模式
+pnpm --filter @h-ai/cli test:watch
+
+# 覆盖率
+pnpm --filter @h-ai/cli test:coverage
+```
+
+## License
+
+Apache-2.0
+
+Failures and degraded-state messages must also be localized: website APIs use the request locale for AI fallback and email delivery status; undelivered messages must not be described as received. CLI deployment status uses cliM, and Gallery encryption limitations use bilingual messages. Verify unconfigured, failed, and successful paths in Chinese and English without paid service calls.
+
+Provisioned configuration: Neon emits HAI_DB (PostgreSQL JSON), Upstash HAI_CACHE (Redis rediss URL JSON), and R2 HAI_STORAGE (flat S3 JSON). Email/SMS emit HAI_REACH_PROVIDERS; deployApp merges both channels while preserving YAML message templates, replacing the original providers array. Core supports whole-object/array overrides, with parents preceding leaves and schema validation retained. Build subprocesses and target runtimes share provisioned values. R2 needs existing S3 accessKeyId/secretAccessKey, Resend a verified-domain from address, and Alibaba Cloud approved signName/templates. Applications need matching `_db.yml` / `_cache.yml` / `_storage.yml` / `_reach.yml` loaded at startup; network clients require Node.
+
+Deployment recovery: `ProvisionResult.resourceStatus` marks created/reused. `getDeployRecovery(result.error)` reads projectName, stage, platformProjectId, and resource lists; unknown means an uncertain request result that must first be checked in the provider console. Preserve returned IDs for failed resources. Recovery excludes envVars, raw exceptions, and credentials; the CLI shows resources and advice. Same-name retries reuse resources. Reused resources are never deleted automatically; clean up newly created resources only after manually confirming they are unused.

package/README.ja.md

@@ -0,0 +1,239 @@
+# @h-ai/cli
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
+
+> hai Agent Framework CLI：対話式のプロジェクト生成とコード生成ツール。
+
+## 主な機能
+
+`hai deploy` はモジュール・設定不足、認証情報読み込み、走査、初期化、デプロイ、終了処理の失敗で非ゼロの終了コードを返します。スクリプトは終了コードを確認し、デプロイ全体の成功を後続処理の条件にしてください。
+
+- **プロジェクト作成**：SvelteKit アプリ、Svelte 5 モバイル・デスクトップ画面、hai バックエンドを対話式で生成。
+- **モジュール追加**：既存プロジェクトに機能を追加し、依存関係を自動解決。
+- **設定初期化**：設定の完全性を検証し、不足ファイルを生成。
+- **コード生成**：ページ、コンポーネント、API endpoint、データモデル、DB マイグレーションを生成。
+- **テンプレート**：minimal / default / full / custom の 4 種類。
+- **機能の組み合わせ**：IAM、DB、AI、Storage、Crypto などを必要に応じて有効化。
+- **API サービス生成**：`@h-ai/api-contract` + `@h-ai/serv` で公開 contract / procedures を組み合わせ、`@h-ai/api-client` の型付きクライアントで利用。
+- **依存関係の自動解決**：機能選択時に依存を追加（例：IAM が Crypto を追加）。
+
+## AI 向け使用ガイド
+
+Claude Code v2.1.277 以降は、優先されるプロジェクト CLAUDE ファイルがなく、標準機能が有効ならルート `AGENTS.md` を直接読めます。一行の `@AGENTS.md` ブリッジは旧版や無効なセッションも支援し、規則の重複や `.claude/` ディレクトリーを必要としません。[AGENTS.md の対応](https://code.claude.com/docs/en/memory#agentsmd)を参照してください。
+
+CLI は選択した skill のディレクトリー全体を `templates/skills/` から生成先の `.agents/skills/` にコピーします。`SKILL.md` は機能の境界とタスク案内、`reference.md`/`guide.md` は必要時に読む例を提供します。入口だけをコピーしてはいけません。AGENTS.md にアプリの制約を置き、Claude/Copilot のブリッジから参照します。テンプレート変更は関連するリポジトリー skill と同期し、生成テストで参照ファイルの完全な提供を確認します。
+
+通常の機能追加・変更・修正では、`AGENTS.md` が `hai-app-create/SKILL.md` と `development.md` に案内します。要件を既存のフレームワーク機能・設定・拡張点に対応付け、インストール済みバージョンの exports と型を確認して実装します。適用できる機能を優先して再利用し、不足する能力を具体的に説明します。利用率のために無関係な依存を追加しません。Codex は `.agents/skills/` とプロジェクトルートの `AGENTS.md` を使用します。
+
+各ツールの入口は一つの規則と skill を共有します。Codex/Cursor は AGENTS と `.agents/skills/`、Copilot は `.github/copilot-instructions.md` と共有 skill、OpenCode は AGENTS・opencode.json と共有 skill を使用します。Claude Code のルート CLAUDE.md は `@AGENTS.md` のみを含み、共有規則のタスク案内から `.agents/skills/` の本文と参照ファイルを必要時に読みます。CLI は `.claude/` を生成せず、skill の複製やシンボリックリンクも不要です。この構成では Claude のネイティブ skill 自動検出や `/skill` コマンドは登録されません。既存の Claude 設定と skill は保持します。根拠：[Claude プロジェクト指針](https://code.claude.com/docs/en/memory)、[Claude ネイティブ skills](https://code.claude.com/docs/en/skills)、[Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)、[OpenCode](https://docs.opencode.ai/docs/skills/)、[Cursor](https://cursor.com/docs/skills)。
+
+生成プロジェクトは `eslint-rules.js` を共有します。lint は明示的な `any`、console、説明のない抑制、unknown を介した二重アサーション、フレームワーク内部ソースの import、既知の機密 localStorage キーへの書き込みを拒否します。必要なサードパーティーの回避策は局所的な説明を付けます。権限分離・入力安全性・トランザクション・ログのマスキングは静的規則だけでは証明できないため、テストとレビューで確認します。
+
+既存プロジェクトは CLI を更新して `hai init` を実行すると、不足するワークフロー skill・参照リソース・入口ファイルが補完されます。`--force` を使っても既存の AI 規則は上書きしません。既存の入口・skills・ESLint 設定・scripts は新規生成プロジェクトと比較してマージし、不足する .npmrc/.gitignore も補完してください。ファイル補完だけで古い規則は更新されません。公開前は本リポジトリーでビルドした CLI で比較用プロジェクトを生成し、未公開の能力とインストール済みパッケージの能力を区別します。
+
+AI ファイルの書き込み前に既存のファイル・ディレクトリーリンクを解決します。共有 skill とプロジェクトのブリッジはプロジェクト内に限定し、外部へのリンクでは書き込みを停止します。既存の `.claude/` ディレクトリーとリンクは生成対象外で、`hai init` / `hai add` はその内容を変更・削除しません。
+
+配布検証はパッケージアーカイブと生成プロジェクトの両方を対象にします。`.npmrc` / `.gitignore` のテンプレート源には `.hbs` を付けて梱包時の除外を避け、生成時に通常の名前へ戻します。依存配置と機密生成物の無視規則を維持し、全テンプレートが `.tgz` に含まれることを回帰検証します。
+
+## クイックスタート
+
+Node.js 22.22.2+ / 24.15.0+ / 26+ が必要です。生成するルートプロジェクトと各 workspace パッケージも同じ最低バージョンを宣言します。
+
+### プロジェクトの作成
+
+```bash
+# 交互式创建（推荐）
+npx hai create my-admin-app
+
+# 指定模板与功能
+npx hai create my-app -t full
+npx hai create my-app -t custom -f iam,db,ai
+```
+
+対話式の手順：
+
+1. プロジェクト名を入力。
+2. テンプレートを選択（minimal / default / full / custom）。
+3. 機能モジュールを選択（custom の場合）。
+4. サンプルコードを追加するか選択。
+5. パッケージマネージャーを選択（pnpm / npm / yarn）。
+6. 依存をインストールするか選択。
+7. Git を初期化するか選択。
+
+### モジュールの追加
+
+```bash
+# 交互式选择
+npx hai add
+
+# 指定模块
+npx hai add iam
+npx hai add storage
+```
+
+既存プロジェクトにモジュールを追加します。`package.json` の更新、設定生成、依存解決を自動実行します。
+
+### 設定の初期化・検証
+
+```bash
+# 校验配置完整性，补全缺失配置
+npx hai init
+
+# 强制重新生成所有配置
+npx hai init --force
+```
+
+### コード生成
+
+名前は英字で始まり、英字・数字・ハイフン・アンダースコアのみ使用でき、パスは受け付けません。既定では全出力を事前確認して上書きを拒否し、明示的な `--force` のみで置換します。出力とシンボリックリンク先は作業ディレクトリー内に限定されます。
+
+ページ/API 生成は SvelteKit 向けで、コンポーネントは Svelte 5 の children snippet を使います。API は `kit.handler` と Zod 入力検証を使用します。マイグレーションは明示的な `up()` / `down()` を出力し、実行前に `reldb` を初期化、実行後に HaiResult を確認します。自動マイグレーションランナーではありません。`down()` はテーブルを削除するため、アプリ側の確認後に実行してください。
+
+```bash
+# 交互式生成
+npx hai generate
+
+# 指定类型
+npx hai generate page users
+npx hai generate component UserCard
+npx hai generate api users
+npx hai generate model user
+npx hai generate migration add-users
+
+# 快捷命令
+npx hai g:page dashboard
+npx hai g:component StatusBadge
+npx hai g:api orders
+npx hai g:model order
+```
+
+## プロジェクトテンプレート
+
+| テンプレート | 説明       | 含まれる機能                                              |
+| ------------ | ---------- | --------------------------------------------------------- |
+| `minimal`    | 最小構成   | 基本的な SvelteKit/hai 構成（モバイルは Svelte 5 + Vite） |
+| `default`    | 標準構成   | IAM + DB + Cache + Crypto                                 |
+| `full`       | 全機能構成 | すべての業務モジュール + API Service / contract の仕組み  |
+| `custom`     | カスタム   | 必要に応じて選択                                          |
+
+## Fullstack mini 管理画面
+
+`--type fullstack` は IAM、reldb、cache、audit、storage、crypto を含む管理 workspace を既定で生成します。minimal を選んでも管理に必要なモジュールは有効です。`--frontends` で Web、Capacitor App、Tauri Desktop を選択します。miniapp は説明用のプレースホルダーで、実行・ビルド対象には含まれません。
+
+```powershell
+npx hai create mini-admin --type fullstack --frontends web,app,desktop
+cd mini-admin
+pnpm.cmd install
+pnpm.cmd dev
+```
+
+CLI はルート `.env` にプロジェクトごとに異なるランダムな強い `HAI_ADMIN_DEFAULT_PASSWORD` を生成するため、`dev` / `start` を直接実行できます。初回ログインは `admin` とそのパスワードを使います。同名の環境変数で上書きできます。パスワードは `_iam.yml` のポリシーに従い、既定では 8 文字以上です。違反すると起動ログに具体的な理由とエラーコードを表示します。ユーザーが存在する場合、この変数でアカウントやパスワードはリセットされません。`.env` は Git とコンテナビルドから除外され、`.env.example` はプレースホルダーのみです。デプロイ先ごとに別のパスワードを設定してください。
+
+- 管理者はユーザーの検索、ページング、作成、編集、有効・無効化、削除、アバター更新を行えます。サーバーは現在の管理者を保護し、更新ロック内で認可を再確認するため、同時操作で全管理者の権限を失うことを防ぎます。
+- ロールは `admin` / `user` の 2 種類です。ロール画面は人数表示と説明編集、ユーザー画面はロール割り当てを担当します。一般ユーザーは個人設定のみ利用でき、管理 API への直接アクセスもサーバーで拒否します。
+- 監査画面は操作、リソース、日付で記録を検索します。ログイン成功、ログアウト、パスワード変更、管理の書き込みを監査に記録し、パスワード、token、アバター内容は含めません。
+- 個人設定はプロフィール、アバター、言語、テーマ、パスワード変更を提供します。設定は IAM ユーザー metadata に保存します。アバターは PNG/JPEG/WebP、最大 512 KiB で、サーバーが画像内容を検証して storage key を生成します。
+
+型付き api-client と serv の crypto transport が、JSON 業務リクエスト、ログイン、更新を双方向に暗号化します。Web はメモリー内 access token と HttpOnly refresh Cookie を使います。App のネイティブ版は Capacitor の安全な TokenStorage、Desktop のネイティブ版はメモリーのみを使い、再起動後は再ログインします。ネイティブの refresh body 通路はクライアント識別子、明示的な通信ヘッダー、信頼する Origin を検証し、ブラウザープレビューは Cookie モードを使います。公開アバターはホワイトリスト内のバイナリー画像リソースです。
+
+Web/App/Desktop は同じ `AdminWorkspace`、management store、型付き client を使います。現在のユーザーと refresh はフレームワーク標準 IAM procedures、テーマの保存と DOM 更新は `@h-ai/ui/theme` を使い、アプリは固定ロール、自己保護、アバター、業務監査を組み合わせます。
+
+既定の SQLite、ローカル storage、memory cache は単一インスタンスの mini 管理サービス向けです。管理の書き込みは単一 writer のみ対応します。複数の読み取りインスタンスには共有 DB、storage、Redis cache と transport セッションの固定ルーティングが必要で、管理の書き込みは同じ writer に送ります。Redis への変更だけでは任意の複数 writer 間で最後の管理者を原子的に保護できません。生成するルート scripts は typecheck、lint、build、test、test:e2e を提供し、Capacitor/Tauri の配布には対応するネイティブビルドとパッケージ作成も必要です。
+
+## アプリ設定と表示
+
+全テンプレートは `_core.yml` から `name`、`version`、`env`、`defaultLocale`、`logging` を読み、`core.config` でメタ情報を取得して `core.logger` を使います。単一アプリの設定は `config/`、API workspace は `apps/<project>-service/config/`、fullstack は `packages/<project>-serv/config/` にあります。ログレベルと形式は YAML で決め、初期化で固定の `logging` を指定して上書きしません。
+
+Core の環境変数上書きには `HAI_CORE_NAME`、`HAI_CORE_VERSION`、`HAI_CORE_ENV`、`HAI_CORE_LOGGING_LEVEL` を使えます。`HAI_CORE` 全体の上書きは親ノード優先です。サーバー設定の変更後はサービスを再起動します。コンテナは `HAI_CORE_ENV=production` を明示し、この値で本番の安全ポリシーを有効にします。
+
+SvelteKit のサーバー layout は名称、バージョン、環境、既定言語など公開メタ情報のホワイトリストのみを渡します。単独 mobile-app の Vite 設定は Node ビルド時に core で YAML を解析し、公開値とブラウザーログレベル・形式を注入するため、YAML や上書き変数を変えたら再ビルドが必要です。Fullstack の画面は暗号化された `app.info` でサーバーの公開メタ情報を取得します。core/モジュール設定全体、秘密情報、ログのマスキング文脈はブラウザーに公開しません。
+
+## 共通オプション
+
+| オプション         | 説明                     |
+| ------------------ | ------------------------ |
+| `-v, --verbose`    | 詳細な出力               |
+| `-C, --cwd <path>` | 作業ディレクトリーの指定 |
+
+## 開発時のローカル利用
+
+> npm 公開前に monorepo 内で CLI をローカル実行・デバッグする場合に使います。
+
+### 1. ビルド
+
+```bash
+# 构建 CLI（生成 dist/）
+pnpm --filter @h-ai/cli build
+
+# 或启动 watch 模式（修改源码后自动重建）
+pnpm --filter @h-ai/cli dev
+```
+
+### 2. 直接実行（インストール不要）
+
+ビルド後、`node` で `dist/index.js` を直接実行できます：
+
+```bash
+# 从仓库根目录运行
+node packages/cli/dist/index.js create my-app
+node packages/cli/dist/index.js create my-app --type admin --features iam,db
+```
+
+任意のディレクトリーから絶対パスでも実行できます：
+
+```bash
+node /path/to/hai-framework/packages/cli/dist/index.js create my-app
+```
+
+### 3. グローバルリンク（`pnpm link`）
+
+ターミナルで `hai` を直接使うにはグローバルリンクを作成します：
+
+```bash
+# 在 packages/cli 目录下执行
+cd packages/cli
+pnpm link --global
+
+# 验证
+hai --version
+hai create my-app
+```
+
+> 使用後は `pnpm unlink --global @h-ai/cli` でリンクを解除できます。
+
+### 4. monorepo のほかの app で使用
+
+`apps/*` は `workspace:*` でローカルパッケージを参照し、そのまま利用できます：
+
+```bash
+# 在仓库根目录执行，对任意 app 类型生成项目
+node packages/cli/dist/index.js create ../my-new-project
+```
+
+### 5. テスト実行
+
+```bash
+# 单元测试 + E2E 模板生成测试
+pnpm --filter @h-ai/cli test
+
+# 真实脚手架 E2E 门禁（生成项目后执行 install/typecheck/lint/build/test/e2e）
+pnpm --filter @h-ai/cli test:e2e
+
+# watch 模式
+pnpm --filter @h-ai/cli test:watch
+
+# 覆盖率
+pnpm --filter @h-ai/cli test:coverage
+```
+
+## License
+
+Apache-2.0
+
+失敗・縮退時の表示も国際化します。サイト API はリクエストの locale で AI 縮退・メール到達状態を表示し、未到達を受信済みと表現しません。CLI のデプロイ状態は cliM、Gallery の暗号化制限は二言語メッセージを使います。中国語・英語で未設定・失敗・成功を検証し、有料サービスの呼び出しは不要です。
+
+クラウド設定の利用：Neon は HAI_DB（PostgreSQL JSON）、Upstash は HAI_CACHE（Redis rediss URL JSON）、R2 は HAI_STORAGE（フラットな S3 JSON）を出力します。メール・SMS は HAI_REACH_PROVIDERS を出力し、deployApp が両チャネルと YAML のメッセージテンプレートを統合して元の providers 配列を置換します。Core はオブジェクト・配列全体の上書きをサポートし、親ノードを末端より優先して Schema 検証を維持します。ビルド子プロセスと対象環境は同じ値を使います。R2 は既存の S3 accessKeyId/secretAccessKey、Resend は検証済みドメインの from、Alibaba Cloud は承認済み signName・テンプレートが必要です。アプリは対応する `_db.yml` / `_cache.yml` / `_storage.yml` / `_reach.yml` を起動時に読み込み、ネットワーククライアントには Node が必要です。
+
+デプロイ失敗からの復旧：`ProvisionResult.resourceStatus` は created/reused を示します。`getDeployRecovery(result.error)` で projectName、stage、platformProjectId、リソース一覧を取得し、unknown は結果不明なので先にサービス側の管理画面で確認します。失敗リソースの ID が返った場合は保持します。復旧情報に envVars・元の例外・接続認証情報は含まれず、CLI が一覧と提案を表示します。同名の再試行は既存リソースを再利用し、自動削除しません。新規作成分も未使用を人が確認した後にのみ削除します。

package/README.md

@@ -1,5 +1,9 @@
 # @h-ai/cli
 
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
+
 > hai Agent Framework CLI — 交互式项目脚手架与代码生成工具。
 
 ## 支持的能力
@@ -19,9 +23,23 @@
 
 CLI 从 `templates/skills/` 将所选 skill 的完整目录复制到生成项目 `.agents/skills/`。`SKILL.md` 提供能力边界和任务导航，`reference.md`/`guide.md` 保留按需范本；同步时不能只复制入口。AGENTS.md 保存应用约束，Claude/Copilot 桥接文件引用它；修改模板需同步相关仓库 skills。模板生成测试会核对参考文件的完整交付。
 
+日常新增、修改、修复功能由 `AGENTS.md` 引导读取 `hai-app-create/SKILL.md` 与 `development.md`：先把需求映射到框架现成功能、配置和扩展点，再依据当前安装版本的 exports/类型实现。适用能力优先复用；能力不足时说明具体缺口，不为模块覆盖率安装无关依赖。Codex 使用 `.agents/skills/`，仍需遵循项目根 `AGENTS.md` 的常驻规则。
+
+工具入口共享同一份规则与技能：Codex/Cursor 使用 AGENTS 与 `.agents/skills/`；Copilot 使用 `.github/copilot-instructions.md` 与共享技能；OpenCode 使用 AGENTS、opencode.json 与共享技能。Claude Code 的根 CLAUDE.md 仅包含 `@AGENTS.md`，通过共享规则的任务导航按需读取 `.agents/skills/` 正文和参考文件。CLI 不创建 `.claude/`，无需重复技能或符号链接。此模式不提供 Claude 原生技能自动发现或 `/skill` 命令；项目已有的 Claude 设置与技能保留。依据：[Claude 项目指引](https://code.claude.com/docs/en/memory)、[Claude 原生 skills](https://code.claude.com/docs/en/skills)、[Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)、[OpenCode](https://docs.opencode.ai/docs/skills/)、[Cursor](https://cursor.com/docs/skills)。
+
+Claude Code v2.1.277 起也可直接读取根 `AGENTS.md`（没有更高优先级项目 CLAUDE 文件且相关内置插件启用时）。保留这一行导入可兼容旧版及未开启该能力的会话，官方说明导入不会重复加载规则；仍无须 `.claude/` 目录。参见 [AGENTS.md 支持](https://code.claude.com/docs/en/memory#agentsmd)。
+
+生成项目共享 `eslint-rules.js`，lint 拦截显式 `any`、console、无理由抑制、双重 unknown 断言、框架内部源码导入及明确的 localStorage 敏感键写入；合理的第三方 workaround 需局部说明。静态规则不能证明权限隔离、输入安全、事务或日志脱敏，相关行为仍需测试与审查。
+
+已有项目先更新 CLI，再运行 `hai init` 补齐缺失的流程 skill、参考资源和入口；该操作保留现有文件，即使 `--force` 也不覆盖 AI 规则。旧入口、已存在的 skills、ESLint 配置与脚本需要对照新生成项目合并，缺失的 .npmrc/.gitignore 也需补齐；只补文件不会自动升级旧规则。模板变更未发布前可通过本仓库构建的 CLI 生成对照项目，不要把未发布能力当作已安装包能力。
+
+AI 文件写入前会解析已有文件和目录链接；共享技能与项目桥接文件均限制在当前项目内。链接指向项目外时停止写入。已有 `.claude/` 目录及其链接不参与生成，`hai init` / `hai add` 不修改或删除其中的内容。
+
+交付验证同时检查发布归档和生成项目。`.npmrc` / `.gitignore` 在模板源中使用 `.hbs` 后缀，避免打包时被排除；生成时仍恢复正常文件名，保留依赖布局与敏感产物忽略规则。归档回归检查全部模板都进入 `.tgz`，不能仅验证源码目录中的 create。
+
 ## 快速开始
 
-要求 Node.js ≥ 22.12.0；生成的根项目和工作区包均声明相同最低版本。
+要求 Node.js 22.22.2+ / 24.15.0+ / 26+；生成的根项目和工作区包均声明相同最低版本。
 
 ### 创建项目
 
@@ -100,6 +118,38 @@ npx hai g:model order
 | `full`    | 完整模板 | 全量业务模块 + API Service / contract 机制          |
 | `custom`  | 自定义   | 按需选择                                            |
 
+## Fullstack mini 管理后台
+
+`--type fullstack` 默认生成包含 IAM、reldb、cache、audit、storage、crypto 的管理工程；即使选择 minimal，管理所需模块也会保留。`--frontends` 选择 Web、Capacitor App 和 Tauri Desktop；miniapp 仍是说明占位，不参与运行或构建。
+
+```powershell
+npx hai create mini-admin --type fullstack --frontends web,app,desktop
+cd mini-admin
+pnpm.cmd install
+pnpm.cmd dev
+```
+
+CLI 自动生成根目录 `.env`，其中 `HAI_ADMIN_DEFAULT_PASSWORD` 是每个项目独立的随机强密码；直接运行 `dev` / `start` 即可。首次登录使用 `admin` 和 `.env` 中的密码，同名环境变量可以覆盖它。密码遵循 `_iam.yml` 策略，默认至少 8 位；不符合策略时启动日志显示具体校验原因与错误码。已有用户后，该变量不会重设账号或密码。`.env` 被 Git 和容器构建忽略，`.env.example` 仅保留占位；部署时设置目标环境自己的密码。
+
+- 管理员可搜索、分页、新增、编辑、启禁用、删除用户并上传头像；服务端保护当前管理员，管理写操作在锁内重新鉴权，防止并发操作使管理员全部失权。
+- 角色固定为 `admin` / `user`，角色页显示人数并编辑说明，用户页分配角色。普通用户仅进入个人设置，直接请求管理接口也会被服务端拒绝。
+- 审计页按操作、资源与日期查询记录；成功登录、退出、密码变更和管理写操作写入审计，记录不含密码、token 或头像内容。
+- 个人设置提供资料、头像、语言、主题和密码修改；偏好保存到 IAM 用户 metadata。头像接受 PNG/JPEG/WebP，最大 512 KiB，服务端验证图片内容并生成 storage key。
+
+前端 typed api-client 与 serv 的 crypto transport 统一加解密 JSON 业务、登录与刷新。Web 使用内存 access token 和 HttpOnly refresh Cookie；App 原生端使用 Capacitor 安全 TokenStorage，Desktop 原生端仅在内存保存 token，重启后重新登录。原生刷新 body 通道校验客户端标识、显式传输头和受信 Origin；浏览器预览沿用 Cookie。公开头像是白名单内的二进制图片资源。
+
+Web/App/Desktop 复用同一个 `AdminWorkspace`、management store 和 typed client。当前用户与刷新直接选用框架默认 IAM procedures，主题缓存与 DOM 更新复用 `@h-ai/ui/theme`；应用只编排固定角色、自我保护、头像与审计等业务规则。
+
+默认 SQLite、本地 storage 与 memory cache 适用于单实例 mini 后台。管理写入仅支持单写实例；多实例读取需要共享数据库、存储、Redis cache 和传输会话粘性路由，管理写请求仍须路由至同一实例。仅更换 Redis 不能保证任意多写副本的最后管理员原子保护。生成后的根脚本提供 typecheck、lint、build、test、test:e2e；Capacitor/Tauri 交付另执行对应原生构建和打包。
+
+## 应用配置与显示
+
+所有模板从 `_core.yml` 统一读取 `name`、`version`、`env`、`defaultLocale` 和 `logging`，通过 `core.config` 获取元信息并使用 `core.logger`。单应用配置在 `config/`；API workspace 在 `apps/<project>-service/config/`；fullstack 在 `packages/<project>-serv/config/`。日志级别与格式由 YAML 决定，不在初始化时另写固定 `logging` 覆盖。
+
+环境变量可按 core 约定覆盖，如 `HAI_CORE_NAME`、`HAI_CORE_VERSION`、`HAI_CORE_ENV`、`HAI_CORE_LOGGING_LEVEL`；整体 `HAI_CORE` 覆盖遵循父节点优先规则。服务端配置变更后重启服务，容器显式设置 `HAI_CORE_ENV=production`，由该值启用生产安全策略。
+
+SvelteKit 的服务端 layout 只下发名称、版本、环境和默认语言等公开白名单。独立 mobile-app 的 Vite 配置在 Node 构建阶段通过 core 解析 YAML，再注入公开值及浏览器日志级别/格式；修改 YAML 或覆盖变量后需要重新构建。Fullstack 前端通过加密的 `app.info` 获取服务端公开元信息。任何模板都不能把完整 core/模块配置、密钥或日志脱敏上下文注入浏览器。
+
 ## 全局选项
 
 | 选项               | 说明         |