@h-ai/cli 0.1.0-alpha.60 → 0.1.0-alpha.61

package/README.en.md

@@ -159,10 +159,20 @@ Default SQLite, local storage and memory cache suit a single-instance mini admin
 
 ## Application configuration and display
 
+Every generated `.gitignore` includes `**/data/`, covering runtime data and `.gitkeep` at every workspace depth. Runtime code creates the required directories.
+
+Fullstack always includes 13 `.yml` files in `packages/<project>-serv/config/`: `_core`, `_serv`, `_db`, `_cache`, `_iam`, `_storage`, `_audit`, `_reach`, `_ai`, `_vecdb`, `_payment`, `_scheduler`, and `_deploy`. Used modules retain working defaults; unused modules, optional fields, and alternative providers remain as comments. `.env.example` also includes commented credentials for unused modules. Module choices entered during creation are preserved.
+
+To extend the service, install the required package in its workspace, validate with the public schema, initialize it and close it in reverse order in `src/server/runtime.ts`, then uncomment the relevant configuration. For a fully commented file, remove one outer comment layer first and enable optional blocks as needed. A configuration file alone does not connect business features. Replace connection blocks when switching SQLite/Redis/S3 or Reach providers, keeping each provider name unique. `crypto.init()` takes no configuration and datapipe provides pure functions; neither gets an invented YAML file.
+
 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.
 
+Leaf overrides apply only to existing YAML paths: uncomment the key first, or replace the whole object with `HAI_DB`, `HAI_CACHE`, etc. CamelCase remains one segment: `connectTimeout` maps to `HAI_CACHE_CONNECTTIMEOUT`. Locale lists belong in each frontend/shared `project.inlang/settings.json`; `_core.yml` specifies only the default locale.
+
+The automatically generated fullstack `.env` enables only the initial administrator password and `PUBLIC_API_BASE`. Module overrides remain commented so YAML supplies defaults. Explicitly uncomment environment overrides when needed, and check existing overrides when editing YAML.
+
 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

package/README.ja.md

@@ -159,12 +159,22 @@ Web/App/Desktop は同じ `AdminWorkspace`、management store、型付き client
 
 ## アプリ設定と表示
 
+生成されるすべての `.gitignore` に `**/data/` を含め、ルートと各 workspace の実行データおよび `.gitkeep` を除外します。必要なディレクトリは実行時に作成します。
+
+Fullstack の `packages/<project>-serv/config/` は `_core`、`_serv`、`_db`、`_cache`、`_iam`、`_storage`、`_audit`、`_reach`、`_ai`、`_vecdb`、`_payment`、`_scheduler`、`_deploy` の 13 個の `.yml` を常に生成します。使用するモジュールは既定値を有効にし、未使用のモジュール、任意項目、代替 Provider はコメントとして残します。`.env.example` も未使用モジュールの認証情報をコメントで示し、作成時に指定した設定値を保持します。
+
+拡張時はサービスの workspace に必要なパッケージを追加し、`src/server/runtime.ts` で公開 Schema による検証、初期化、逆順の終了処理を実装してから設定を有効にします。全体がコメントのファイルは外側のコメントを一層外し、任意ブロックは必要なものだけ有効にします。設定ファイルの存在だけでは業務機能は接続されません。SQLite/Redis/S3 や Reach Provider の切り替え時は既存の接続ブロックを置き換え、Provider 名を重複させません。`crypto.init()` は設定引数を取らず、datapipe は純関数のため、架空の YAML は生成しません。
+
 全テンプレートは `_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/モジュール設定全体、秘密情報、ログのマスキング文脈はブラウザーに公開しません。
 
+葉の環境変数は YAML に存在するパスだけを上書きします。コメントの項目は先に有効にするか、`HAI_DB`、`HAI_CACHE` などでオブジェクト全体を置き換えます。camelCase は分割せず、`connectTimeout` は `HAI_CACHE_CONNECTTIMEOUT` に対応します。言語一覧は各フロントエンド/shared の `project.inlang/settings.json` で管理し、`_core.yml` は既定言語のみを指定します。
+
+Fullstack が自動生成する `.env` は初期管理者パスワードと `PUBLIC_API_BASE` のみ有効にします。モジュールの環境変数上書きはコメントとして残し、YAML を既定値の元にします。必要な環境変数だけを明示的に有効にし、YAML 編集時は既存の上書きも確認します。
+
 ## 共通オプション
 
 | オプション         | 説明                     |

package/README.md

@@ -159,10 +159,20 @@ Web/App/Desktop 复用同一个 `AdminWorkspace`、management store 和 typed cl
 
 ## 应用配置与显示
 
+所有生成项目的 `.gitignore` 都包含 `**/data/`，忽略根目录及嵌套 workspace 的运行数据，包括 `.gitkeep`；运行时会创建需要的数据目录。
+
+Fullstack 的 `packages/<project>-serv/config/` 始终保留 13 份配置：`_core`、`_serv`、`_db`、`_cache`、`_iam`、`_storage`、`_audit`、`_reach`、`_ai`、`_vecdb`、`_payment`、`_scheduler`、`_deploy`（均为 `.yml`）。已用模块保留有效默认值，未启用模块整份注释，各模块的可选字段和替代 Provider 也以注释保留。`.env.example` 同时提供未启用模块的注释凭据示例。创建时填写的模块选项会保留。
+
+扩展时先在服务端 workspace 安装所需模块，在 `src/server/runtime.ts` 按公开 Schema 校验配置、初始化并反序关闭，再取消所需配置的注释。整份注释的文件先去掉一层外层注释，可选块继续按需开启；配置文件存在并不等于业务能力已接入。切换 SQLite/Redis/S3 或 Reach Provider 时替换原连接块，同名 Provider 只保留一个。`crypto.init()` 无配置参数，datapipe 是纯函数，不生成虚构的 YAML 配置。
+
 所有模板从 `_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`，由该值启用生产安全策略。
 
+叶子环境变量只覆盖 YAML 中已有的路径；注释掉的键须先取消注释，或使用 `HAI_DB`、`HAI_CACHE` 等整体对象覆盖。camelCase 不拆词，例如 `connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。语言列表由各前端与 shared 的 `project.inlang/settings.json` 维护，`_core.yml` 只配置默认语言。
+
+Fullstack 自动生成的 `.env` 默认只启用初始管理员密码和 `PUBLIC_API_BASE`；模块环境覆盖全部保留注释，以 YAML 为默认值来源。需要环境覆盖时显式取消对应变量的注释，修改 YAML 时同步核对已有环境覆盖。
+
 SvelteKit 的服务端 layout 只下发名称、版本、环境和默认语言等公开白名单。独立 mobile-app 的 Vite 配置在 Node 构建阶段通过 core 解析 YAML，再注入公开值及浏览器日志级别/格式；修改 YAML 或覆盖变量后需要重新构建。Fullstack 前端通过加密的 `app.info` 获取服务端公开元信息。任何模板都不能把完整 core/模块配置、密钥或日志脱敏上下文注入浏览器。
 
 ## 全局选项