morphix-env 0.7.1 → 0.9.0

package/README.md

@@ -1,4 +1,6 @@
 <p align="center">
+
+[本仓文档入口](./docs/README.md) · [本地工程约定](./docs/engineering.md)
   <img src="docs/logo.png" width="160" alt="morphix-env" />
 </p>
 
@@ -77,10 +79,73 @@ Choosing between Infisical and Doppler still depends on each provider's own iden
 
 This is leakage minimization, not a cryptographic boundary: a process that receives a secret can still transform or exfiltrate it deliberately. For a high-risk agent capability, use a provider proxy/broker as a separate security design rather than passing that credential through `run`.
 
+## On-demand secrets with `run --serve`
+
+`mx-env run --serve -- <command>` (modeled on aws-vault's `--ecs-server`) starts a loopback HTTP server on 127.0.0.1 at a random port that shares the child's lifetime:
+
+- Composed non-public values never enter the child environment — not the direct child, its descendants, `/proc/<pid>/environ`, or core dumps. The child receives only `MXENV_ENDPOINT` and a random `MXENV_TOKEN`, and the token is redacted from child output like any injected value. Honest caveat on token visibility: an environment-delivered capability token is readable by same-uid processes on Linux via the child's `/proc/<pid>/environ` — the same inherent property as aws-vault's `--ecs-server`; the *values* themselves still appear in no process environment anywhere.
+- The child fetches one value at a time: `mx-env fetch <KEY>` (thin client that reads endpoint/token from its own environment and prints the exact value with no trailing newline), or a direct `GET /key/<KEY>` with `Authorization: Bearer $MXENV_TOKEN`. The endpoint answers 401 without the token and 404 for unknown keys; no request or value is ever logged.
+- Browser-public keys (`NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`) stay in the environment so build tools can inline them; they remain servable as well.
+- The server is destroyed the moment the child exits (and dies with the parent process itself), so no listener outlives the run.
+
+`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.
+
+## 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`:
+
+```jsonc
+// mx-env.config.json
+{
+  "sources": {
+    "vault": { "provider": "plugin", "plugin": "bitwarden", "keys": ["OPENAI_API_KEY"] }
+  }
+}
+```
+
+Plugin protocol (summon-style):
+
+- Invoked as `mx-env-provider-<plugin> <KEY>`, once per declared key; exit 0 with the value on stdout (one trailing line ending stripped).
+- A non-zero exit or a missing executable fails the source with a value-free error — the plugin's stderr is never surfaced because it may contain sensitive material. `optional: true` downgrades a missing executable to `missing-optional`.
+- Plugins intentionally inherit the already-composed environment at their precedence position (inherited env → global baseline → profile sources loaded so far), so wrapper scripts can authenticate to their own backend without a second credential channel. Least-privilege consequence: a plugin can read every value composed before it — declare plugin sources only after the sources they need and keep each `keys` list minimal. Each key invocation times out after 30s.
+- Login and bootstrap stay inside the plugin; repository config carries only wiring (plugin name + key names), never values.
+
+The five built-in providers (`infisical`, `doppler`, `os-keychain`, `dotenvx`, `local`) are unchanged.
+
 ## Commands
 
 ```bash
 mx-env run --profile dev -- <command>   # compose and run (the only injection path)
+mx-env run --serve -- <command>         # serve values over loopback instead of injecting them into env
+mx-env fetch <KEY>                      # read one value from a run --serve child environment
+mx-env export [--profile agents]        # eval-able export KEY='value' lines (values in stdout only for eval)
+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 edit [--profile dev | --source s] # one-shot visual editor
 mx-env generate --out public/__env.js   # public browser runtime config
@@ -89,6 +154,8 @@ mx-env skill install | show             # packaged Agent Skill (global / project
 mx-env audit tail                       # value-free audit events
 ```
 
+`export`, `render`, `inject`, and `run` accept `--dry-run` (key/variable names only, never values). `eval "$(mx-env export --profile agents)"` injects a profile into the current shell without putting values in shell history. `render` and `inject` write mode-0600 outputs, warn about unresolved `${VAR}` / `mx-env://` references before writing, and warn when the output path is not git-ignored. `mx-env://profile/KEY` references (mirroring 1Password's `op://`) let MCP configs and dotenv templates stay in git without values: `mx-env inject` resolves them at the file level, `mx-env run` resolves them inside composed values before spawning.
+
 Full options live in `mx-env --help`; the packaged skill mirrors the commands of the installed version.
 
 ## Agent workflow

package/dist/SKILL.md

@@ -29,14 +29,15 @@ npx morphix-env@latest inspect   # 免安装试用
 配置文件**不含任何值**，只声明 source 接线与组合顺序。项目级放仓库根 `mx-env.config.json`；用户级 `~/.mx-env/config.json` 可选（全局基线，`--no-global` 可排除）。`~/.mx-env/.env` 是唯一自动发现的值文件（个人默认值）。
 
 ```jsonc
-// 项目 mx-env.config.json — 五种 provider 全示例
+// 项目 mx-env.config.json — 全部 provider 示例
 {
   "sources": {
     "local":     { "provider": "local", "files": [".env.local"], "optional": true, "override": true },
     "encrypted": { "provider": "dotenvx", "files": [".env.shared"] },
     "keychain":  { "provider": "os-keychain", "platform": "macos", "service": "com.example/myproject" },
     "infisical": { "provider": "infisical", "paths": ["/team/api"] },
-    "doppler":   { "provider": "doppler", "project": "my-project", "config": "dev" }
+    "doppler":   { "provider": "doppler", "project": "my-project", "config": "dev" },
+    "plugin":    { "provider": "plugin", "plugin": "bitwarden", "keys": ["OPENAI_API_KEY"] }
   },
   "profiles": {
     "dev": { "sources": ["keychain", "infisical", "local"] },
@@ -50,6 +51,7 @@ npx morphix-env@latest inspect   # 免安装试用
 
 - profile 内 `sources` **从低到高**排列；同 key 冲突默认**报错**，靠后 source 显式 `"override": true` 才覆盖（防止两个环境的同名凭据静默错选）。
 - 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` 字段）无需改动即兼容。
 
 ## 命令速查
@@ -57,6 +59,11 @@ npx morphix-env@latest inspect   # 免安装试用
 ```bash
 mx-env run --profile dev -- <command>    # 组合环境并执行（子进程输出脱敏）
 mx-env run --no-global -- <command>      # 排除全局基线，可复现的项目-only 运行
+mx-env run --serve -- <command>          # 值不进 env：子进程经 MXENV_ENDPOINT/MXENV_TOKEN 按需取值
+mx-env fetch KEY                         # 在 --serve 子进程内取单个值（精确输出，无换行）
+mx-env export [--profile dev]            # 输出可 eval 的 export KEY='value' 行（值只经 stdout 进入 eval）
+mx-env render <tpl> <out>                # 把 ${VAR} 渲染进不支持插值的配置文件（0600，缺变量先告警）
+mx-env inject <tpl> <out>                # 解析 mx-env://profile/KEY 引用（0600，MCP 配置入仓不落值）
 mx-env generate --out public/__env.js    # 生成浏览器公开变量（NEXT_PUBLIC_/VITE_/EXPO_PUBLIC_ 属公开配置例外）
 mx-env inspect [--profile dev]           # key 名 + source 归属 + 状态（无值）
 mx-env edit --profile dev | --source X   # 一次性可视化编辑器（loopback + 15 分钟 TTL，保存后自动关闭）
@@ -64,8 +71,13 @@ 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"] 配置项）
 ```
 
+**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 的消费方式。
+
 ## 进入一个新项目的标准流程
 
 1. `mx-env inspect` — 看是否已有配置、哪些 key 已就绪；无配置时走 legacy `.env.local` / Infisical 兼容路径。