morphix-env 0.6.0-beta.2 → 0.7.0-beta.1

package/README.md

@@ -6,6 +6,8 @@
 
 The concise command is `mx-env`; the published `morphix-env` command remains fully supported.
 
+The package also ships a maintained, value-free Agent Skill (`mx-env skill install`) so agents can adopt the whole workflow — safety rules, configuration schema, commands — without a second distribution; see [Agent workflow](#agent-workflow).
+
 ## Quick start: global local defaults
 
 Create this file once:
@@ -202,6 +204,12 @@ mx-env edit --profile api-dev
 # Generate this project's value-free Agent workflow Skill
 mx-env doc --profile api-dev
 
+# Install the packaged Agent Skill (global | project | trellis)
+mx-env skill install --target project
+
+# Show per-target install state and template drift
+mx-env skill show
+
 # Value-free audit events
 mx-env audit tail
 ```
@@ -217,12 +225,31 @@ Options:
 | `--no-global` | Ignore `~/.mx-env/.env` and `~/.mx-env/config.json`. |
 | `--allow-insecure-global` | Explicitly permit a global dotenv file readable by group/other users. Avoid this outside controlled troubleshooting. |
 | `--print-editor-url` | Explicitly print the one-time local editor URL; normally the browser opens without emitting it to the terminal. |
+| `--target <scope>` | `skill install` destination: `global` (`~/.claude/skills/`), `project` (`.claude/skills/` inside the repo — commit it), or `trellis` (`~/.trellis/skills/` canonical store). |
+| `--force` | Replace an installed skill that differs from this version's template; a modified file is never overwritten without it. |
 | `-o, --out <path>` / `--filter <prefix>` | Configure public browser-env generation. |
 | `-v, --verbose` | Show source state and key counts, not values. |
 
 ## Agent workflow
 
-`mx-env doc --profile <profile>` writes a value-free workflow Skill to `.agents/skills/morphix-env/SKILL.md` by default. Generated or maintained Skills contain this rule:
+### Packaged Agent Skill
+
+The npm package ships a maintained, value-free Agent Skill at `dist/SKILL.md`. It teaches an agent the full workflow: safety red lines (inspect for validation, `edit` for changes, `run` as the only injection path), the complete `mx-env.config.json` schema for all five providers, a command cheatsheet, project onboarding steps, and troubleshooting. Because it travels with the CLI, it always documents commands that exist in the installed version.
+
+```bash
+# Agent bootstrap straight from npm — no global install required
+npx morphix-env@latest skill install --target project
+
+mx-env skill install --target project   # <repo>/.claude/skills/morphix-env/SKILL.md — commit it with the repository
+mx-env skill install --target global    # ~/.claude/skills/morphix-env/SKILL.md — every project on this machine
+mx-env skill install --target trellis   # ~/.trellis/skills/morphix-env/SKILL.md — then `trellis sync skills`
+```
+
+Installs are idempotent: a re-run against an unchanged template is a no-op, and a skill file the user has customized is never overwritten without `--force`. `mx-env skill show` reports each target's install state and whether it still matches the shipped template.
+
+### Project workflow Skill
+
+`mx-env doc --profile <profile>` writes a value-free workflow Skill to `.agents/skills/morphix-env/SKILL.md` by default, listing this project's resolved key names and their winning sources. Generated or maintained Skills contain this rule:
 
 ```md
 When the user asks to add, modify, or rotate a credential:

package/dist/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: morphix-env
+description: 通过 morphix-env（mx-env）为项目组装、检查、可视化编辑环境变量与密钥——多 provider（本地 .env / dotenvx 加密 / macOS 钥匙串 / Infisical / Doppler）、按 profile 组合、Agent 上下文零密钥。当用户提到环境变量、密钥、API key、credentials、.env、Infisical、Doppler、Keychain、"配置环境"、担心 secret 泄露，或需要 Agent/进程带着密钥运行而值不出现在对话里时使用。
+user-invocable: true
+argument-hint: "[install|show]"
+---
+
+# morphix-env（mx-env）Agent 密钥工作流
+
+morphix-env 是密钥**组装层**，不是新的保险库：值永远留在 provider（本地文件、macOS 钥匙串、Infisical、Doppler、dotenvx）里。CLI 只把 profile 选定的 sources 组合成一次性子进程环境，并保证 inspect / audit / run 子进程输出全部脱敏。
+
+## 安全红线（任何情况下都不违反）
+
+1. 绝不打印、记录、索取密钥值：不运行 `env` / `printenv` / `cat .env*` / `doppler secrets get --plain`，也不让用户把值粘贴进对话。
+2. 只用 key 名验证状态：`mx-env inspect --profile <name>` 输出 key → source 归属与状态，不含值。
+3. 增删改密钥一律走可视化编辑器：`mx-env edit --profile <name>`（或 `--source <name>`），用户在本地浏览器完成，值不经过 CLI 与对话。
+4. 进程获得密钥的唯一方式是 `mx-env run`；子进程 stdout/stderr 中的注入值会被替换为 `[REDACTED]`。
+
+## 安装与检测
+
+```bash
+mx-env --version                 # 检测是否已安装
+npm install -g morphix-env       # 安装（mx-env 与 morphix-env 两个 bin 等价）
+npx morphix-env@latest inspect   # 免安装试用
+```
+
+## 配置（mx-env.config.json）
+
+配置文件**不含任何值**，只声明 source 接线与组合顺序。项目级放仓库根 `mx-env.config.json`；用户级 `~/.mx-env/config.json` 可选（全局基线，`--no-global` 可排除）。`~/.mx-env/.env` 是唯一自动发现的值文件（个人默认值）。
+
+```jsonc
+// 项目 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" }
+  },
+  "profiles": {
+    "dev": { "sources": ["keychain", "infisical", "local"] },
+    "ci":  { "sources": ["doppler"] }
+  },
+  "defaultProfile": "dev"
+}
+```
+
+要点：
+
+- profile 内 `sources` **从低到高**排列；同 key 冲突默认**报错**，靠后 source 显式 `"override": true` 才覆盖（防止两个环境的同名凭据静默错选）。
+- provider 登录与引导留在 provider 侧（`infisical login`、`doppler login`、dotenvx 解密密钥引导），**不写进项目配置**。
+- 固定基线顺序：`inherited process.env → ~/.mx-env/.env → 全局默认 profile → 项目 profile / legacy 配置 → -f 覆盖文件`。legacy 项目（`infisical` + `envFiles` 字段）无需改动即兼容。
+
+## 命令速查
+
+```bash
+mx-env run --profile dev -- <command>    # 组合环境并执行（子进程输出脱敏）
+mx-env run --no-global -- <command>      # 排除全局基线，可复现的项目-only 运行
+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，保存后自动关闭）
+mx-env doc                               # 生成本项目的 key→source 工作流 Skill（.agents/skills/morphix-env/）
+mx-env audit [tail]                      # 值无关的本地审计事件
+mx-env skill install [--target global|project|trellis] [--force]   # 安装本 Skill
+mx-env skill show                        # 查看各目标安装状态
+```
+
+## 进入一个新项目的标准流程
+
+1. `mx-env inspect` — 看是否已有配置、哪些 key 已就绪；无配置时走 legacy `.env.local` / Infisical 兼容路径。
+2. 项目密钥来源多而杂且无 `mx-env.config.json` → 引导用户创建：给出上面模板改 source 名与 provider 选择，**不填值**。
+3. 缺值时 `mx-env edit --profile <name>` 打开本地编辑器让用户填写；macOS 浏览器自动打开，编辑器 URL 默认不打印（`--print-editor-url` 显式索取）。
+4. `mx-env doc` — 生成**本项目**的 key→source 表（`.agents/skills/morphix-env/SKILL.md`，0600），后续以它为准。
+5. 运行：`mx-env run --profile <name> -- <command>`。
+
+## 故障排查
+
+| 症状 | 处理 |
+|---|---|
+| 冲突报错：同 key 来自两个 source | 确认哪个 source 应赢，给靠后的加 `"override": true` |
+| `missing-optional, 0 keys` | `"optional": true` 的文件不存在，属预期；要强制存在就删掉 optional |
+| Keychain 权限弹框 / 拒绝 | 首次访问会请求 service 授权；拒绝后重试或换 service 命名空间 |
+| dotenvx 解密失败 | 解密密钥由 dotenvx 引导路径提供，不在本配置内 |
+| `mx-env: command not found` | `npm install -g morphix-env`，或用 `npx morphix-env@latest` 免安装 |
+
+---
+
+本 Skill 与安装它的 CLI 同版本分发：`mx-env skill install` 覆盖安装即升级。模板内容 value-free；项目专属的 key 清单请以 `mx-env doc` 的输出为准。

package/dist/cli.js

@@ -29482,9 +29482,9 @@ var require_jsx_runtime = __commonJS({
 
 // src/cli.ts
 var import_cross_spawn = __toESM(require("cross-spawn"));
-var import_fs7 = require("fs");
-var import_os4 = require("os");
-var import_path7 = require("path");
+var import_fs8 = require("fs");
+var import_os5 = require("os");
+var import_path8 = require("path");
 
 // src/audit.ts
 var import_fs = require("fs");
@@ -37182,11 +37182,81 @@ var StreamingRedactor = class {
   }
 };
 
+// src/skill.ts
+var import_fs7 = require("fs");
+var import_os4 = require("os");
+var import_path7 = require("path");
+var SKILL_TARGETS = ["global", "project", "trellis"];
+function resolveSkillPath(target) {
+  if (target === "project") return (0, import_path7.join)(process.cwd(), ".claude", "skills", "morphix-env", "SKILL.md");
+  if (target === "trellis") return (0, import_path7.join)((0, import_os4.homedir)(), ".trellis", "skills", "morphix-env", "SKILL.md");
+  return (0, import_path7.join)((0, import_os4.homedir)(), ".claude", "skills", "morphix-env", "SKILL.md");
+}
+function targetHint(target) {
+  if (target === "project") {
+    return "Project skill installed; commit it so every Agent working in this repository picks it up.";
+  }
+  if (target === "trellis") {
+    return "Installed into the Trellis canonical store; run `trellis sync skills` to distribute it to managed agents.";
+  }
+  return "Installed as a Claude Code global skill; available in every project.";
+}
+function printNextSteps() {
+  console.log(`[morphix-env] Next steps:
+  1. mx-env inspect                        check this project's config and resolved key names
+  2. create mx-env.config.json if absent   see the skill's configuration section (source wiring only, no values)
+  3. mx-env edit --profile <name>          let the user fill values in the local visual editor
+  4. mx-env doc                            generate this project's key-to-source workflow Skill`);
+}
+function cmdSkill(subcommand, options) {
+  const templatePath = (0, import_path7.join)(__dirname, "SKILL.md");
+  const template = (0, import_fs7.readFileSync)(templatePath, "utf8");
+  if (subcommand === "show") {
+    console.log(`[morphix-env] Skill template: ${templatePath}`);
+    for (const target2 of SKILL_TARGETS) {
+      const path = resolveSkillPath(target2);
+      if (!(0, import_fs7.existsSync)(path)) {
+        console.log(`  ${target2}: not installed (${path})`);
+        continue;
+      }
+      const state = (0, import_fs7.readFileSync)(path, "utf8") === template ? "installed (matches this version)" : "installed (differs from this version)";
+      console.log(`  ${target2}: ${state} (${path})`);
+    }
+    return 0;
+  }
+  if (subcommand !== "install") {
+    console.error(`[morphix-env] Unknown skill subcommand "${subcommand}". Use install or show.`);
+    return 1;
+  }
+  const target = options.target ?? "global";
+  if (!SKILL_TARGETS.includes(target)) {
+    console.error(`[morphix-env] Unknown skill target "${options.target}". Use global, project, or trellis.`);
+    return 1;
+  }
+  const dest = resolveSkillPath(target);
+  if ((0, import_fs7.existsSync)(dest)) {
+    if ((0, import_fs7.readFileSync)(dest, "utf8") === template) {
+      console.log(`[morphix-env] Skill already installed and up to date: ${dest}`);
+      return 0;
+    }
+    if (!options.force) {
+      console.error(`[morphix-env] ${dest} exists with different content; refusing to overwrite. Re-run with --force to replace it.`);
+      return 1;
+    }
+  }
+  (0, import_fs7.mkdirSync)((0, import_path7.dirname)(dest), { recursive: true });
+  (0, import_fs7.writeFileSync)(dest, template, { mode: 420 });
+  console.log(`[morphix-env] Installed skill: ${dest}`);
+  console.log(`[morphix-env] ${targetHint(target)}`);
+  printNextSteps();
+  return 0;
+}
+
 // package.json
 var package_default = {
   name: "morphix-env",
-  version: "0.6.0-beta.2",
-  description: "Environment variable toolkit \u2014 Infisical integration, local overrides, and client-side runtime injection for Next.js / Vite / Express.",
+  version: "0.7.0-beta.1",
+  description: "Secret composition CLI \u2014 Infisical, Doppler, macOS Keychain, dotenvx, and local files stay value owners; composes them into one value-safe child environment and ships a built-in Agent Skill (mx-env skill install).",
   author: "MorphixAI <dev@morphixai.com>",
   homepage: "https://github.com/Morphicai/morphix-env#readme",
   repository: {
@@ -37201,7 +37271,7 @@ var package_default = {
     "mx-env": "./dist/cli.js"
   },
   scripts: {
-    build: "node scripts/build-editor-ui.mjs && tsup src/cli.ts --format cjs --dts --clean --external keytar",
+    build: "node scripts/build-editor-ui.mjs && tsup src/cli.ts --format cjs --dts --clean --external keytar && node scripts/copy-skill.mjs",
     dev: "node scripts/build-editor-ui.mjs && tsup src/cli.ts --format cjs --watch",
     pretest: "pnpm build",
     test: "vitest run",
@@ -37217,7 +37287,12 @@ var package_default = {
     "environment-variables",
     "cross-env",
     "infisical",
+    "doppler",
+    "keychain",
     "secrets",
+    "secret-management",
+    "agent",
+    "agent-skills",
     "runtime-env",
     "nextjs",
     "vite",
@@ -37268,7 +37343,9 @@ function parseArgs(argv) {
     noGlobal: false,
     allowInsecureGlobal: false,
     printEditorUrl: false,
-    source: null
+    source: null,
+    target: null,
+    force: false
   };
   let i = 2;
   const command = argv[i];
@@ -37303,6 +37380,10 @@ function parseArgs(argv) {
       args.allowInsecureGlobal = true;
     } else if (arg === "--print-editor-url") {
       args.printEditorUrl = true;
+    } else if (arg === "--target") {
+      if (argv[++i]) args.target = argv[i];
+    } else if (arg === "--force") {
+      args.force = true;
     } else if (args.command === "run") {
       args.subArgs = argv.slice(i);
       break;
@@ -37312,7 +37393,7 @@ function parseArgs(argv) {
   return args;
 }
 function resolveComposition(args) {
-  const layers = loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os4.homedir)() });
+  const layers = loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os5.homedir)() });
   return composeEnvironment(layers, {
     profile: args.profile,
     noGlobal: args.noGlobal,
@@ -37320,11 +37401,11 @@ function resolveComposition(args) {
     envName: args.env,
     allowInsecureGlobal: args.allowInsecureGlobal,
     envFiles: args.envFiles,
-    homeDir: (0, import_os4.homedir)()
+    homeDir: (0, import_os5.homedir)()
   });
 }
 function generatedOptions(args) {
-  const config = loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os4.homedir)() }).project.config;
+  const config = loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os5.homedir)() }).project.config;
   return {
     outFile: args.outFile || config.generate?.out || "public/__env.js",
     filter: args.filter || config.generate?.filter || null
@@ -37333,8 +37414,8 @@ function generatedOptions(args) {
 function generateClientEnv(outFile, filter, environment) {
   let vars = extractPublicVars(environment);
   if (filter) vars = Object.fromEntries(Object.entries(vars).filter(([key]) => key.startsWith(filter)));
-  (0, import_fs7.mkdirSync)((0, import_path7.dirname)(outFile), { recursive: true });
-  (0, import_fs7.writeFileSync)(outFile, `window.__ENV=${JSON.stringify(vars)};`);
+  (0, import_fs8.mkdirSync)((0, import_path8.dirname)(outFile), { recursive: true });
+  (0, import_fs8.writeFileSync)(outFile, `window.__ENV=${JSON.stringify(vars)};`);
   console.log(`[morphix-env] Generated ${outFile} (${Object.keys(vars).length} client vars)`);
 }
 async function runChild(command, commandArgs, composition) {
@@ -37382,7 +37463,7 @@ async function cmdRun(args) {
   }
   if (args.outFile || generatedOptions(args).outFile) {
     const { outFile, filter } = generatedOptions(args);
-    const configured = Boolean(args.outFile || loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os4.homedir)() }).project.config.generate);
+    const configured = Boolean(args.outFile || loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os5.homedir)() }).project.config.generate);
     if (configured) generateClientEnv(outFile, filter, composition.environment);
   }
   const [command, ...commandArgs] = args.subArgs;
@@ -37420,7 +37501,7 @@ async function cmdEdit(args) {
   }
   const composition = await resolveComposition(args);
   if (args.source && !composition.sourceEntries.some((entry) => entry.name === args.source)) {
-    const layers = loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os4.homedir)() });
+    const layers = loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os5.homedir)() });
     const declared = layers.project.config.sources?.[args.source] ? { source: layers.project.config.sources[args.source], baseDir: layers.project.baseDir } : !args.noGlobal && layers.global.config.sources?.[args.source] ? { source: layers.global.config.sources[args.source], baseDir: layers.global.baseDir } : null;
     if (!declared) {
       console.error(`[morphix-env] Unknown source "${args.source}".`);
@@ -37438,7 +37519,7 @@ async function cmdEdit(args) {
 }
 async function cmdDoc(args) {
   const composition = await resolveComposition(args);
-  const outFile = args.outFile || (0, import_path7.join)(process.cwd(), ".agents", "skills", "morphix-env", "SKILL.md");
+  const outFile = args.outFile || (0, import_path8.join)(process.cwd(), ".agents", "skills", "morphix-env", "SKILL.md");
   const keyRows = Object.entries(composition.provenance).sort(([a], [b]) => a.localeCompare(b)).map(([key, provenance]) => `| \`${key}\` | ${provenance.source} (${provenance.provider}) |`).join("\n") || "| _No resolved keys_ | \u2014 |";
   const skill = `---
 name: morphix-env
@@ -37472,18 +37553,18 @@ ${keyRows}
 
 Secret values and value prefixes do not belong in this Skill, command output, audit records, or conversation context.
 `;
-  (0, import_fs7.mkdirSync)((0, import_path7.dirname)(outFile), { recursive: true });
-  (0, import_fs7.writeFileSync)(outFile, skill, { mode: 384 });
+  (0, import_fs8.mkdirSync)((0, import_path8.dirname)(outFile), { recursive: true });
+  (0, import_fs8.writeFileSync)(outFile, skill, { mode: 384 });
   console.log(`[morphix-env] Generated value-free workflow Skill: ${outFile}`);
   return 0;
 }
 function cmdAudit(args) {
-  const file = (0, import_path7.join)((0, import_os4.homedir)(), ".mx-env", "audit", `${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}.jsonl`);
-  if (!(0, import_fs7.existsSync)(file)) {
+  const file = (0, import_path8.join)((0, import_os5.homedir)(), ".mx-env", "audit", `${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}.jsonl`);
+  if (!(0, import_fs8.existsSync)(file)) {
     console.log("[morphix-env] No audit events for today.");
     return 0;
   }
-  const lines = (0, import_fs7.readFileSync)(file, "utf8").trim().split("\n").filter(Boolean);
+  const lines = (0, import_fs8.readFileSync)(file, "utf8").trim().split("\n").filter(Boolean);
   const selected = args.subArgs[0] === "tail" ? lines.slice(-20) : lines;
   for (const line of selected) console.log(line);
   return 0;
@@ -37499,6 +37580,8 @@ Usage:
   mx-env doc [options]                    Generate a value-free project Skill
   mx-env audit [tail]                     Read value-free local audit events
   mx-env edit --profile <name>            Open the one-shot visual editor
+  mx-env skill install [--target <t>]     Install the Agent Skill (global|project|trellis)
+  mx-env skill show                       Show skill install status per target
 
 Both mx-env and morphix-env are supported.
 
@@ -37512,6 +37595,8 @@ Options:
   --no-global              Ignore ~/.mx-env/.env and ~/.mx-env/config.json
   --allow-insecure-global  Allow a global .env with permissive file mode
   --print-editor-url       Explicitly print the one-time local editor URL
+  --target <scope>         Skill install target: global, project, or trellis
+  --force                  Overwrite an installed skill that differs from this version
   -v, --verbose            Print source status and key counts only
   --help, -h               Show this help
   --version                Show version
@@ -37533,6 +37618,10 @@ async function main() {
       return cmdEdit(args);
     case "doc":
       return cmdDoc(args);
+    case "skill": {
+      const positional = process.argv.slice(3).find((arg) => !arg.startsWith("-")) ?? "install";
+      return cmdSkill(positional, { target: args.target, force: args.force });
+    }
     case "--help":
     case "-h":
     case "help":

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "morphix-env",
-  "version": "0.6.0-beta.2",
-  "description": "Environment variable toolkit — Infisical integration, local overrides, and client-side runtime injection for Next.js / Vite / Express.",
+  "version": "0.7.0-beta.1",
+  "description": "Secret composition CLI — Infisical, Doppler, macOS Keychain, dotenvx, and local files stay value owners; composes them into one value-safe child environment and ships a built-in Agent Skill (mx-env skill install).",
   "author": "MorphixAI <dev@morphixai.com>",
   "homepage": "https://github.com/Morphicai/morphix-env#readme",
   "repository": {
@@ -16,7 +16,7 @@
     "mx-env": "./dist/cli.js"
   },
   "scripts": {
-    "build": "node scripts/build-editor-ui.mjs && tsup src/cli.ts --format cjs --dts --clean --external keytar",
+    "build": "node scripts/build-editor-ui.mjs && tsup src/cli.ts --format cjs --dts --clean --external keytar && node scripts/copy-skill.mjs",
     "dev": "node scripts/build-editor-ui.mjs && tsup src/cli.ts --format cjs --watch",
     "pretest": "pnpm build",
     "test": "vitest run",
@@ -32,7 +32,12 @@
     "environment-variables",
     "cross-env",
     "infisical",
+    "doppler",
+    "keychain",
     "secrets",
+    "secret-management",
+    "agent",
+    "agent-skills",
     "runtime-env",
     "nextjs",
     "vite",