morphix-env 0.8.0 → 0.9.0

package/README.md

@@ -90,6 +90,31 @@ 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.
+
 ## 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`:

package/dist/SKILL.md

@@ -71,8 +71,11 @@ 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 的消费方式。
 
 ## 进入一个新项目的标准流程

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_fs9 = require("fs");
-var import_os6 = require("os");
-var import_path9 = require("path");
+var import_fs10 = require("fs");
+var import_os7 = require("os");
+var import_path10 = require("path");
 
 // src/audit.ts
 var import_fs = require("fs");
@@ -37437,10 +37437,267 @@ async function startSecretServer(values) {
   };
 }
 
-// src/template.ts
-var import_child_process4 = require("child_process");
+// src/shims.ts
 var import_fs8 = require("fs");
+var import_os6 = require("os");
 var import_path8 = require("path");
+var SHIM_MARKER = "# mx-env shim \u2014 regenerated by `mx-env shell-init`; do not edit by hand.";
+var RESERVED_SHIM_NAMES = [
+  "run",
+  "fetch",
+  "export",
+  "render",
+  "inject",
+  "generate",
+  "gen",
+  "inspect",
+  "audit",
+  "edit",
+  "doc",
+  "skill",
+  "shell-init",
+  "help",
+  "mx-env",
+  "morphix-env",
+  "__mx_editor"
+];
+var SHIM_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function shimsDir(homeDir = (0, import_os6.homedir)()) {
+  return (0, import_path8.join)(homeDir, ".mx-env", "shims");
+}
+function validateShimList(list, label) {
+  if (list === void 0 || list === null) return [];
+  if (!Array.isArray(list)) return [`${label}: "shims" must be an array of command names`];
+  const errors = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of list) {
+    if (typeof entry !== "string" || !entry) {
+      errors.push(`${label}: shim entries must be non-empty command names`);
+      continue;
+    }
+    if (!SHIM_NAME_PATTERN.test(entry)) {
+      errors.push(`${label}: shim entry "${entry}" must be a bare command name (letters, digits, ".", "_", "-"; no path separators or whitespace)`);
+      continue;
+    }
+    const lower = entry.toLowerCase();
+    if (RESERVED_SHIM_NAMES.includes(lower)) {
+      errors.push(`${label}: shim entry "${entry}" conflicts with a reserved mx-env command name`);
+      continue;
+    }
+    if (seen.has(lower)) {
+      errors.push(`${label}: duplicate shim entry "${entry}" (comparison is case-insensitive)`);
+      continue;
+    }
+    seen.add(lower);
+  }
+  return errors;
+}
+function resolveShimCommands(layers, includeGlobal = true) {
+  const seen = /* @__PURE__ */ new Set();
+  const commands = [];
+  const push = (list) => {
+    if (!Array.isArray(list)) return;
+    for (const entry of list) {
+      if (typeof entry !== "string") continue;
+      const lower = entry.toLowerCase();
+      if (seen.has(lower)) continue;
+      seen.add(lower);
+      commands.push(entry);
+    }
+  };
+  if (includeGlobal) push(layers.global.config.shims);
+  push(layers.project.config.shims);
+  return commands;
+}
+function renderShimScript(command) {
+  return `#!/bin/sh
+${SHIM_MARKER}
+command -v mx-env >/dev/null 2>&1 || { echo "[mx-env] mx-env not on PATH; reinstall morphix-env or run 'mx-env shell-init --remove' to clean up this shim." >&2; exit 127; }
+MXENV_SHIM=1 exec mx-env run -- ${command} "$@"
+`;
+}
+function readIfExists(path) {
+  try {
+    return (0, import_fs8.readFileSync)(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function writeShims(commands, homeDir = (0, import_os6.homedir)()) {
+  const dir = shimsDir(homeDir);
+  (0, import_fs8.mkdirSync)(dir, { recursive: true, mode: 448 });
+  const wanted = new Set(commands.map((command) => command.toLowerCase()));
+  const written = [];
+  const removed = [];
+  const skipped = [];
+  for (const file of (0, import_fs8.readdirSync)(dir)) {
+    const path = (0, import_path8.join)(dir, file);
+    const content = readIfExists(path);
+    if (content === null || !content.includes(SHIM_MARKER)) continue;
+    if (!wanted.has(file.toLowerCase())) {
+      (0, import_fs8.rmSync)(path);
+      removed.push(file);
+    }
+  }
+  for (const command of commands) {
+    const path = (0, import_path8.join)(dir, command);
+    const content = renderShimScript(command);
+    let isSymlink = false;
+    try {
+      isSymlink = (0, import_fs8.lstatSync)(path).isSymbolicLink();
+    } catch {
+    }
+    const existing = isSymlink ? null : readIfExists(path);
+    if (!isSymlink && existing !== null && !existing.includes(SHIM_MARKER)) {
+      skipped.push(command);
+      continue;
+    }
+    if (isSymlink) (0, import_fs8.rmSync)(path);
+    else if (existing === content) continue;
+    (0, import_fs8.writeFileSync)(path, content, { mode: 493 });
+    (0, import_fs8.chmodSync)(path, 493);
+    written.push(command);
+  }
+  return { written, removed, skipped };
+}
+function removeAllShims(homeDir = (0, import_os6.homedir)()) {
+  const dir = shimsDir(homeDir);
+  if (!(0, import_fs8.existsSync)(dir)) return [];
+  const removed = [];
+  for (const file of (0, import_fs8.readdirSync)(dir)) {
+    const path = (0, import_path8.join)(dir, file);
+    const content = readIfExists(path);
+    if (content !== null && content.includes(SHIM_MARKER)) {
+      (0, import_fs8.rmSync)(path);
+      removed.push(file);
+    }
+  }
+  return removed;
+}
+function detectHandmadeReservedShims(homeDir = (0, import_os6.homedir)()) {
+  const dir = shimsDir(homeDir);
+  if (!(0, import_fs8.existsSync)(dir)) return [];
+  const found = [];
+  for (const file of (0, import_fs8.readdirSync)(dir)) {
+    if (!RESERVED_SHIM_NAMES.includes(file.toLowerCase())) continue;
+    const content = readIfExists((0, import_path8.join)(dir, file));
+    if (content === null || !content.includes(SHIM_MARKER)) found.push(file);
+  }
+  return found;
+}
+var RC_BLOCK_BEGIN = "# >>> mx-env shims >>>";
+var RC_BLOCK_END = "# <<< mx-env shims <<<";
+function rcBlock(homeDir = (0, import_os6.homedir)()) {
+  const dir = shimsDir(homeDir);
+  if (/["$`\\]/.test(dir)) {
+    throw new Error("[morphix-env] Shims directory path contains characters that are unsafe in a shell rc line.");
+  }
+  return `${RC_BLOCK_BEGIN}
+export PATH="${dir}:$PATH"
+${RC_BLOCK_END}`;
+}
+function defaultRcPath(shell, homeDir = (0, import_os6.homedir)()) {
+  const name = shell ? shell.split("/").pop() : "";
+  if (name === "zsh") return (0, import_path8.join)(homeDir, ".zshrc");
+  if (name === "bash") return (0, import_path8.join)(homeDir, ".bashrc");
+  return null;
+}
+function writeFileAtomic(path, content) {
+  const tmp = `${path}.mx-env-${process.pid}.tmp`;
+  (0, import_fs8.writeFileSync)(tmp, content);
+  (0, import_fs8.renameSync)(tmp, path);
+}
+function upsertRcBlock(rcPath, homeDir = (0, import_os6.homedir)()) {
+  const existing = readIfExists(rcPath) ?? "";
+  const block = rcBlock(homeDir);
+  const pattern = new RegExp(`${escapeRegExp(RC_BLOCK_BEGIN)}[\\s\\S]*?${escapeRegExp(RC_BLOCK_END)}`, "g");
+  if (pattern.test(existing)) {
+    const replaced = existing.replace(pattern, block);
+    if (replaced === existing) return "unchanged";
+    writeFileAtomic(rcPath, replaced.endsWith("\n") ? replaced : `${replaced}
+`);
+    return "updated";
+  }
+  const separator = existing.length && !existing.endsWith("\n") ? "\n" : "";
+  writeFileAtomic(rcPath, `${existing}${separator}${block}
+`);
+  return "added";
+}
+function removeRcBlock(rcPath) {
+  const existing = readIfExists(rcPath);
+  if (existing === null) return "absent";
+  const pattern = new RegExp(`\\n?${escapeRegExp(RC_BLOCK_BEGIN)}[\\s\\S]*?${escapeRegExp(RC_BLOCK_END)}\\n?`, "g");
+  if (!pattern.test(existing)) return "absent";
+  writeFileAtomic(rcPath, existing.replace(pattern, "\n"));
+  return "removed";
+}
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function stripShimsFromPath(pathValue, homeDir = (0, import_os6.homedir)()) {
+  if (!pathValue) return pathValue;
+  const target = shimsDir(homeDir);
+  let targetReal = target;
+  try {
+    targetReal = (0, import_fs8.realpathSync)(target);
+  } catch {
+  }
+  const equal = (a, b) => process.platform === "darwin" ? a.toLowerCase() === b.toLowerCase() : a === b;
+  const entries = pathValue.split(import_path8.delimiter).filter((entry) => {
+    if (!entry) return true;
+    const literal = entry.replace(/\/+$/, "");
+    let resolved = literal;
+    try {
+      resolved = (0, import_fs8.realpathSync)(literal);
+    } catch {
+    }
+    return !equal(literal, target) && !equal(resolved, targetReal);
+  });
+  return entries.join(import_path8.delimiter);
+}
+function sanitizeBootEnv(env = process.env, homeDir) {
+  const originalPath = env.PATH;
+  const viaShim = env.MXENV_SHIM === "1";
+  try {
+    const home = homeDir ?? (0, import_os6.homedir)();
+    const stripped = stripShimsFromPath(originalPath, home);
+    if (stripped !== originalPath) {
+      if (stripped) env.PATH = stripped;
+      else delete env.PATH;
+    }
+  } catch {
+  }
+  delete env.MXENV_SHIM;
+  return { viaShim, originalPath };
+}
+function findShadowedCommands(commands, originalPath, homeDir = (0, import_os6.homedir)()) {
+  if (!originalPath) return { absent: [...commands], shadowed: [] };
+  const dirs = originalPath.split(import_path8.delimiter).filter(Boolean);
+  const absent = [];
+  const shadowed = [];
+  for (const command of commands) {
+    const shimPath = (0, import_path8.join)(shimsDir(homeDir), command);
+    let resolvedTo = null;
+    for (const dir of dirs) {
+      const candidate = (0, import_path8.join)(dir, command);
+      try {
+        (0, import_fs8.accessSync)(candidate, import_fs8.constants.X_OK);
+        resolvedTo = candidate;
+        break;
+      } catch {
+      }
+    }
+    const samePath = (a, b) => process.platform === "darwin" ? a.toLowerCase() === b.toLowerCase() : a === b;
+    if (resolvedTo === null) absent.push(command);
+    else if (!samePath(resolvedTo, shimPath)) shadowed.push(command);
+  }
+  return { absent, shadowed };
+}
+
+// src/template.ts
+var import_child_process4 = require("child_process");
+var import_fs9 = require("fs");
+var import_path9 = require("path");
 function shellQuote(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -37487,15 +37744,15 @@ function renderTemplate(text, environment) {
   return { output, missing: [...missing] };
 }
 function writePrivateFile(path, content) {
-  const absolute = (0, import_path8.resolve)(path);
-  (0, import_fs8.mkdirSync)((0, import_path8.dirname)(absolute), { recursive: true, mode: 448 });
-  (0, import_fs8.writeFileSync)(absolute, content, { mode: 384 });
-  (0, import_fs8.chmodSync)(absolute, 384);
+  const absolute = (0, import_path9.resolve)(path);
+  (0, import_fs9.mkdirSync)((0, import_path9.dirname)(absolute), { recursive: true, mode: 448 });
+  (0, import_fs9.writeFileSync)(absolute, content, { mode: 384 });
+  (0, import_fs9.chmodSync)(absolute, 384);
 }
 function gitOutputStatus(path) {
-  const absolute = (0, import_path8.resolve)(path);
-  const cwd = (0, import_path8.dirname)(absolute);
-  const name = (0, import_path8.basename)(absolute);
+  const absolute = (0, import_path9.resolve)(path);
+  const cwd = (0, import_path9.dirname)(absolute);
+  const name = (0, import_path9.basename)(absolute);
   const inside = (0, import_child_process4.spawnSync)("git", ["rev-parse", "--is-inside-work-tree"], { cwd, encoding: "utf8" });
   if (inside.status !== 0) return "outside-repo";
   const tracked = (0, import_child_process4.spawnSync)("git", ["ls-files", "--error-unmatch", "--", name], { cwd, encoding: "utf8" });
@@ -37517,7 +37774,7 @@ function warnOutputGitRisk(path) {
 // package.json
 var package_default = {
   name: "morphix-env",
-  version: "0.8.0",
+  version: "0.9.0",
   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",
@@ -37624,7 +37881,10 @@ function parseArgs(argv) {
     target: null,
     force: false,
     dryRun: false,
-    serve: false
+    serve: false,
+    write: false,
+    remove: false,
+    unknownFlags: []
   };
   let i = 2;
   const command = argv[i];
@@ -37665,6 +37925,10 @@ function parseArgs(argv) {
       args.force = true;
     } else if (arg === "--dry-run") {
       args.dryRun = true;
+    } else if (arg === "--write") {
+      args.write = true;
+    } else if (arg === "--remove") {
+      args.remove = true;
     } else if (arg === "--serve") {
       args.serve = true;
     } else if (args.command === "run") {
@@ -37672,13 +37936,15 @@ function parseArgs(argv) {
       break;
     } else if (!arg.startsWith("-")) {
       args.positionals.push(arg);
+    } else {
+      args.unknownFlags.push(arg);
     }
     i++;
   }
   return args;
 }
 function configLayers() {
-  return loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os6.homedir)() });
+  return loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os7.homedir)() });
 }
 function composeOptions(args) {
   return {
@@ -37688,14 +37954,29 @@ function composeOptions(args) {
     envName: args.env,
     allowInsecureGlobal: args.allowInsecureGlobal,
     envFiles: args.envFiles,
-    homeDir: (0, import_os6.homedir)()
+    homeDir: (0, import_os7.homedir)()
   };
 }
+var bootInfo = { viaShim: false };
+var shimWarned = false;
+function warnInvalidShims(layers, includeGlobal) {
+  if (shimWarned) return;
+  shimWarned = true;
+  const problems = [
+    ...includeGlobal ? validateShimList(layers.global.config.shims, layers.global.path) : [],
+    ...validateShimList(layers.project.config.shims, layers.project.path)
+  ];
+  if (problems.length) {
+    console.warn(`[morphix-env] Ignoring invalid "shims" entries (${problems.length} problem(s)); run \`mx-env shell-init\` for the details.`);
+  }
+}
 function resolveComposition(args) {
-  return composeEnvironment(configLayers(), composeOptions(args));
+  const layers = configLayers();
+  warnInvalidShims(layers, !args.noGlobal);
+  return composeEnvironment(layers, composeOptions(args));
 }
 function generatedOptions(args) {
-  const config = loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os6.homedir)() }).project.config;
+  const config = loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os7.homedir)() }).project.config;
   return {
     outFile: args.outFile || config.generate?.out || "public/__env.js",
     filter: args.filter || config.generate?.filter || null
@@ -37704,12 +37985,15 @@ 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_fs9.mkdirSync)((0, import_path9.dirname)(outFile), { recursive: true });
-  (0, import_fs9.writeFileSync)(outFile, `window.__ENV=${JSON.stringify(vars)};`);
+  (0, import_fs10.mkdirSync)((0, import_path10.dirname)(outFile), { recursive: true });
+  (0, import_fs10.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) {
   return new Promise((resolve7) => {
+    if (composition.environment.PATH) {
+      composition.environment.PATH = stripShimsFromPath(composition.environment.PATH) ?? composition.environment.PATH;
+    }
     const child = (0, import_cross_spawn.default)(command, commandArgs, { env: composition.environment, stdio: ["inherit", "pipe", "pipe"] });
     const stdout = new StreamingRedactor(composition.redactionValues);
     const stderr = new StreamingRedactor(composition.redactionValues);
@@ -37736,7 +38020,8 @@ function writeRunAudit(composition, startedAt, outcome, exitCode) {
     keys: Object.keys(composition.provenance).sort(),
     outcome,
     exitCode,
-    durationMs: Date.now() - startedAt
+    durationMs: Date.now() - startedAt,
+    via: bootInfo.viaShim ? "shim" : "cli"
   });
 }
 async function startServeFor(composition, verbose) {
@@ -37802,7 +38087,7 @@ async function cmdRun(args) {
   await resolveEnvironmentReferences(composition, args);
   if (args.outFile || generatedOptions(args).outFile) {
     const { outFile, filter } = generatedOptions(args);
-    const configured = Boolean(args.outFile || loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os6.homedir)() }).project.config.generate);
+    const configured = Boolean(args.outFile || loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os7.homedir)() }).project.config.generate);
     if (configured) generateClientEnv(outFile, filter, composition.environment);
   }
   const [command, ...commandArgs] = args.subArgs;
@@ -37907,11 +38192,11 @@ async function cmdRender(args) {
     console.error("[morphix-env] Usage: mx-env render <template-file> <output-file> [options]");
     return 1;
   }
-  if (!(0, import_fs9.existsSync)(templatePath)) {
+  if (!(0, import_fs10.existsSync)(templatePath)) {
     console.error(`[morphix-env] Template not found: ${templatePath}`);
     return 1;
   }
-  const template = (0, import_fs9.readFileSync)(templatePath, "utf8");
+  const template = (0, import_fs10.readFileSync)(templatePath, "utf8");
   const composition = await resolveComposition(args);
   const names = findTemplateVariables(template);
   const missing = names.filter((name) => composition.environment[name] === void 0 || composition.environment[name] === null);
@@ -37936,12 +38221,14 @@ async function cmdInject(args) {
     console.error("[morphix-env] Usage: mx-env inject <template-file> <output-file> [options]");
     return 1;
   }
-  if (!(0, import_fs9.existsSync)(templatePath)) {
+  if (!(0, import_fs10.existsSync)(templatePath)) {
     console.error(`[morphix-env] Template not found: ${templatePath}`);
     return 1;
   }
-  const template = (0, import_fs9.readFileSync)(templatePath, "utf8");
-  const resolver = new ReferenceResolver(configLayers(), composeOptions(args));
+  const template = (0, import_fs10.readFileSync)(templatePath, "utf8");
+  const layers = configLayers();
+  warnInvalidShims(layers, !args.noGlobal);
+  const resolver = new ReferenceResolver(layers, composeOptions(args));
   const references = findMxEnvReferences(template);
   if (args.dryRun) {
     for (const reference of references) {
@@ -37974,7 +38261,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_os6.homedir)() });
+    const layers = loadConfigLayers({ cwd: process.cwd(), homeDir: (0, import_os7.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}".`);
@@ -37992,7 +38279,7 @@ async function cmdEdit(args) {
 }
 async function cmdDoc(args) {
   const composition = await resolveComposition(args);
-  const outFile = args.outFile || (0, import_path9.join)(process.cwd(), ".agents", "skills", "morphix-env", "SKILL.md");
+  const outFile = args.outFile || (0, import_path10.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
@@ -38026,18 +38313,90 @@ ${keyRows}
 
 Secret values and value prefixes do not belong in this Skill, command output, audit records, or conversation context.
 `;
-  (0, import_fs9.mkdirSync)((0, import_path9.dirname)(outFile), { recursive: true });
-  (0, import_fs9.writeFileSync)(outFile, skill, { mode: 384 });
+  (0, import_fs10.mkdirSync)((0, import_path10.dirname)(outFile), { recursive: true });
+  (0, import_fs10.writeFileSync)(outFile, skill, { mode: 384 });
   console.log(`[morphix-env] Generated value-free workflow Skill: ${outFile}`);
   return 0;
 }
+function cmdShellInit(args) {
+  if (process.platform === "win32") {
+    console.error("[morphix-env] shell-init is supported on macOS/Linux only; on Windows keep using explicit `mx-env run -- <command>`.");
+    return 1;
+  }
+  if (args.unknownFlags.length) {
+    console.error(`[morphix-env] shell-init: unrecognized flag(s): ${args.unknownFlags.join(", ")}`);
+    return 1;
+  }
+  if (args.write && args.remove) {
+    console.error("[morphix-env] shell-init: --write and --remove are mutually exclusive.");
+    return 1;
+  }
+  try {
+    return runShellInit(args);
+  } catch (error) {
+    const code = error?.code;
+    console.error(`[morphix-env] shell-init failed${code ? ` (${code})` : ""}: check that your home directory and rc file are writable, then retry.`);
+    return 1;
+  }
+}
+function runShellInit(args) {
+  const layers = configLayers();
+  const home = (0, import_os7.homedir)();
+  const rcPath = defaultRcPath(process.env.SHELL, home);
+  if (args.remove) {
+    const removed2 = removeAllShims(home);
+    const rcOutcome = rcPath ? removeRcBlock(rcPath) : "absent";
+    console.log(`[morphix-env] Removed ${removed2.length} shim(s)${removed2.length ? ` (${removed2.join(", ")})` : ""}; rc block ${rcOutcome}${rcPath ? ` in ${rcPath}` : ""}.`);
+    return 0;
+  }
+  const problems = [
+    ...validateShimList(layers.global.config.shims, layers.global.path),
+    ...validateShimList(layers.project.config.shims, layers.project.path)
+  ];
+  if (problems.length) {
+    for (const problem of problems) console.error(`[morphix-env] ${problem}`);
+    return 1;
+  }
+  const commands = resolveShimCommands(layers, !args.noGlobal);
+  const { written, removed, skipped } = writeShims(commands, home);
+  console.log(`[morphix-env] Shims ready in ${shimsDir(home)} (${commands.length} command(s): ${commands.join(", ") || "none"}; ${written.length} written, ${removed.length} removed).`);
+  for (const command of skipped) {
+    console.warn(`[morphix-env] Warning: "${command}" exists in the shims directory as a handmade file (no mx-env marker); refusing to overwrite. Remove or rename it by hand, then re-run shell-init.`);
+  }
+  for (const file of detectHandmadeReservedShims(home)) {
+    console.warn(`[morphix-env] Warning: "${file}" in the shims directory was not created by mx-env and shadows a reserved command; delete it by hand. Do not place files in ${shimsDir(home)} manually.`);
+  }
+  const { absent, shadowed } = findShadowedCommands(commands, bootInfo.originalPath, home);
+  if (absent.length) {
+    console.warn(`[morphix-env] Note: ${absent.join(", ")} cannot be resolved on the current PATH yet \u2014 add the shims directory (below) and open a new shell.`);
+  }
+  if (shadowed.length) {
+    console.warn(`[morphix-env] Warning: these commands resolve to a different executable ahead of their shim: ${shadowed.join(", ")} \u2014 move ${shimsDir(home)} ahead of the entries that provide them.`);
+  }
+  if (args.write) {
+    if (!rcPath) {
+      console.error("[morphix-env] shell-init: cannot infer an rc file from $SHELL (zsh/bash supported); add the PATH line manually.");
+      return 1;
+    }
+    const outcome = upsertRcBlock(rcPath, home);
+    console.log(`[morphix-env] rc block ${outcome} in ${rcPath}. Open a new shell to activate.`);
+    return 0;
+  }
+  console.log(`
+Add the shims directory to PATH${rcPath ? ` (e.g. in ${rcPath})` : ""}:
+
+  export PATH="${shimsDir(home)}:$PATH"
+
+Or re-run with --write to let mx-env maintain a marked block in your rc file.`);
+  return 0;
+}
 function cmdAudit(args) {
-  const file = (0, import_path9.join)((0, import_os6.homedir)(), ".mx-env", "audit", `${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}.jsonl`);
-  if (!(0, import_fs9.existsSync)(file)) {
+  const file = (0, import_path10.join)((0, import_os7.homedir)(), ".mx-env", "audit", `${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}.jsonl`);
+  if (!(0, import_fs10.existsSync)(file)) {
     console.log("[morphix-env] No audit events for today.");
     return 0;
   }
-  const lines = (0, import_fs9.readFileSync)(file, "utf8").trim().split("\n").filter(Boolean);
+  const lines = (0, import_fs10.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;
@@ -38059,6 +38418,7 @@ Usage:
   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
+  mx-env shell-init [--write|--remove]    Generate PATH shims for declared commands
 
 Both mx-env and morphix-env are supported.
 
@@ -38082,6 +38442,7 @@ Options:
 `);
 }
 async function main() {
+  Object.assign(bootInfo, sanitizeBootEnv());
   const args = parseArgs(process.argv);
   switch (args.command) {
     case "run":
@@ -38105,6 +38466,8 @@ async function main() {
       return cmdEdit(args);
     case "doc":
       return cmdDoc(args);
+    case "shell-init":
+      return cmdShellInit(args);
     case "skill": {
       const positional = process.argv.slice(3).find((arg) => !arg.startsWith("-")) ?? "install";
       return cmdSkill(positional, { target: args.target, force: args.force });

package/dist/index.d.ts

@@ -69,6 +69,14 @@ interface MxEnvConfig {
     profiles?: Record<string, ProfileInput>;
     /** Profile selected when a caller does not pass --profile. */
     defaultProfile?: string;
+    /**
+     * Commands that get a PATH shim via `mx-env shell-init` (global and project
+     * lists are unioned). Wiring only — never values. Deliberately excluded from
+     * validateConfig's hard errors: a convenience layer must not break the core
+     * injection path, so `shell-init` validates and hard-fails while composition
+     * paths only warn (see shims.ts validateShimList).
+     */
+    shims?: string[];
 }
 interface LoadedConfig {
     config: MxEnvConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "morphix-env",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "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",