morphix-env 0.8.0 → 0.10.0

package/README.md

@@ -55,7 +55,7 @@ The same key from two sources fails by default; the later source must declare `"
 }
 ```
 
-Providers: `infisical` · `doppler` · `os-keychain` (macOS) · `dotenvx` (encrypted files) · `local` (dotenv files). Provider login and bootstrap stay on the provider side (`infisical login`, `doppler login`, dotenvx key bootstrap) and never enter repository config.
+Providers: `infisical` · `doppler` · `os-keychain` (macOS) · `dotenvx` (encrypted files) · `local` (plaintext dotenv files — **development only**; move them to encrypted storage with `mx-env migrate`). Provider login and bootstrap stay on the provider side (`infisical login`, `doppler login`, dotenvx key bootstrap) and never enter repository config.
 
 ## Compared with existing secret management
 
@@ -90,6 +90,51 @@ This is leakage minimization, not a cryptographic boundary: a process that recei
 
 `mx-env run` without `--serve` is unchanged: values are injected into the environment and redacted from forwarded output.
 
+## Terminal shims
+
+For commands you run constantly, shims remove the `mx-env run --` prefix entirely. Declare a command list and generate shims once:
+
+```jsonc
+// ~/.mx-env/config.json (global) and/or mx-env.config.json (project)
+{ "shims": ["node", "pnpm"] }
+```
+
+```bash
+mx-env shell-init          # generate shims in ~/.mx-env/shims, print the PATH line
+mx-env shell-init --write  # also maintain a marked block in ~/.zshrc / ~/.bashrc
+mx-env shell-init --remove # remove shims and the rc block
+```
+
+After the PATH line is active, typing `pnpm dev` is exactly `mx-env run -- pnpm dev`: same composition, same redaction, same exit code. Undeclared commands are untouched.
+
+- The effective list is the union of the global and project lists. A shim is only an entry hook: **what gets injected is always decided by the configuration in effect where the command runs**, so one `pnpm` shim serves every project's own profile.
+- `run` removes the shims directory from the child's PATH before composing, so a tool invoked again inside the run (or by a provider plugin mid-composition) resolves to the real binary — injection happens exactly once, never recursively.
+- `shell-init` is idempotent: re-running converges the directory to the declared list, `--write`/`--remove` use marked rc blocks and never touch your other lines or handmade files.
+- Command names are validated (bare names only; mx-env's own command names are reserved). Invalid entries fail `shell-init` loudly but only warn in composition paths — a convenience layer never breaks `run`.
+- Audit events record `via: "shim"` vs `"cli"` so the two channels stay distinguishable.
+
+**Boundary.** Shims buy convenience, not concealment: injected values live in the child's environment and are visible to same-uid processes. When the consumer is an agent you do not trust with the values, use `run --serve` instead. macOS/Linux only; Windows keeps the explicit `run` form. Do not place files in `~/.mx-env/shims` by hand.
+
+## Retiring plaintext: `mx-env migrate`
+
+Plaintext dotenv files are a development convenience, not a storage end-state — file permissions do not protect them from a same-uid agent process. `mx-env migrate` moves them into encrypted storage (dotenvx encrypted files, or the macOS Keychain) with a backup and a value-level equivalence check at every step:
+
+```bash
+mx-env migrate                                 # read-only plan: units, files, key names (never values)
+mx-env migrate --to dotenvx                    # encrypt in place; declared sources flip to provider dotenvx
+mx-env migrate --to keychain --source mysource # values move to service mx-env:mysource; plaintext is deleted
+```
+
+Scope: the global `~/.mx-env/.env` (dotenvx target only) plus every declared `local` source in the global and project configs. Legacy `.env.local`/`envFiles` are reported as hints — declare them as sources first. Two sources sharing one file are refused: split them first.
+
+- Every unit gets a **0600 backup** (`<file>.mx-env-backup-<timestamp>`) and a **post-migration equivalence check** — decrypted or keychain-read-back values must match the plaintext snapshot exactly — before any config is rewritten. On failure the plaintext and config are restored from backup and the backup paths printed. Backups stay until you delete them yourself.
+- dotenvx migrations pin the file model (`--no-native`): the private key lands in a 0600 `.env.keys` beside the file — portable and CI-friendly — instead of the OS keychain. An unignored `.env.keys` inside a git repo earns a loud warning; the encrypted `.env` itself is safe to commit (that is the dotenvx model).
+- The global file needs no config change: composition sniffs the encryption markers and loads it through the dotenvx provider automatically, with the same 0600 gate on `.env.keys` the plaintext file had.
+- Verification goes through `dotenvx decrypt`, never `run`, so a same-named shell export cannot shadow the check. At compose time, dotenvx sources are file-value-wins (`--overload`) — the same semantics `local` had, so migration does not change what your commands see.
+- Migrations are recorded in the value-free audit (`profile: migrate`).
+
+`--dry-run` with `--to` prints the full execution plan without writing. The keychain target is macOS-only and serves declared sources; the dotenvx target needs the dotenvx CLI (`npm i -g @dotenvx/dotenvx` or a project devDependency).
+
 ## Provider plugins
 
 Any executable on PATH named `mx-env-provider-<name>` is a provider — new remote stores need no changes to `config.ts` / `sources.ts` / `editor.ts`:
@@ -122,6 +167,7 @@ mx-env export [--profile agents]        # eval-able export KEY='value' lines (va
 mx-env render <template> <output>       # substitute ${VAR} into a config file (mode 0600)
 mx-env inject <template> <output>       # resolve mx-env://profile/KEY references into a file (mode 0600)
 mx-env inspect [--profile dev]          # key names + provenance, no values
+mx-env migrate [--to dotenvx|keychain]  # move plaintext local sources into encrypted storage
 mx-env edit [--profile dev | --source s] # one-shot visual editor
 mx-env generate --out public/__env.js   # public browser runtime config
 mx-env doc                              # write this project's key→source skill
@@ -145,6 +191,8 @@ mx-env skill install --target trellis   # ~/.trellis/skills/morphix-env/ — the
 
 Installs are idempotent, and a skill file the user has customized is never overwritten without `--force`. `mx-env skill show` reports each target's install state and template drift.
 
+When the consumer is an agent, prefer `mx-env run --serve -- <command>`: values never enter any process environment, and the agent fetches them one at a time over loopback. Keep secrets in encrypted storage (`mx-env migrate`) and this forms the chain where an agent never touches plaintext — at rest or in env. (Once native keychain ACLs land, the keychain itself can additionally gate access behind Touch ID.)
+
 For project-specific guidance, `mx-env doc --profile <name>` generates a value-free skill listing this project's resolved key names and their winning sources (`.agents/skills/morphix-env/SKILL.md`).
 
 ## Legacy configuration

package/dist/SKILL.md

@@ -50,6 +50,7 @@ npx morphix-env@latest inspect   # 免安装试用
 要点：
 
 - profile 内 `sources` **从低到高**排列；同 key 冲突默认**报错**，靠后 source 显式 `"override": true` 才覆盖（防止两个环境的同名凭据静默错选）。
+- `local`（明文 dotenv）**仅开发用**；长期存储用 dotenvx（加密文件）或 os-keychain，迁移走 `mx-env migrate`。
 - provider 登录与引导留在 provider 侧（`infisical login`、`doppler login`、dotenvx 解密密钥引导），**不写进项目配置**。
 - plugin source：PATH 上的 `mx-env-provider-<name> <KEY>` 把值写到 stdout（退出码 0）；插件自带登录，失败信息不含值。
 - 固定基线顺序：`inherited process.env → ~/.mx-env/.env → 全局默认 profile → 项目 profile / legacy 配置 → -f 覆盖文件`。legacy 项目（`infisical` + `envFiles` 字段）无需改动即兼容。
@@ -71,8 +72,14 @@ mx-env doc                               # 生成本项目的 key→source 工
 mx-env audit [tail]                      # 值无关的本地审计事件
 mx-env skill install [--target global|project|trellis] [--force]   # 安装本 Skill
 mx-env skill show                        # 查看各目标安装状态
+mx-env shell-init [--write|--remove]     # 为声明的命令生成 PATH shim（shims: ["node","pnpm"] 配置项）
+mx-env migrate [--to dotenvx|keychain]   # local 明文迁加密存储（无 --to 为只读 plan；备份+等价验证+可回滚）
 ```
 
+**明文退场指引**：`local` provider（明文 dotenv 文件）定位是**仅开发用**——文件权限防不住同 uid 的 agent 进程。发现项目或全局在用明文源（`mx-env inspect` 里标 `[plaintext, dev-only]`），引导用户跑 `mx-env migrate` 看 plan，再 `--to dotenvx`（加密文件，跨机/CI 友好）或 `--to keychain`（macOS 钥匙串）。迁移有 0600 备份与值级等价验证，失败自动还原。legacy `.env.local` 不自动迁移——先引导声明为 source。
+
+**shim 消费指引**：配置里声明过 `shims` 且执行过 `shell-init` 的机器上，裸敲被声明命令（如 `pnpm dev`）等价于 `mx-env run -- pnpm dev`——你可以依赖它，无需加前缀。但 shim 是方便性不是隐藏：值仍在子进程 env。**需要值不进 env 的场景（高风险 agent 能力、不可信子进程树）必须显式用 `run --serve`**，不要依赖 shim。audit 里 `via: "shim"` 与 `"cli"` 可区分两种来路。
+
 `export` / `render` / `inject` / `run` 均支持 `--dry-run`（只报 key/变量名，不出值）。值永不出现在 shell 历史里：`eval "$(mx-env export --profile dev)"` 才是 export 的消费方式。
 
 ## 进入一个新项目的标准流程