@morphixai/mxenv-cli 0.0.0-stage → 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Morphicai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# mxenv-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+L3 management face for [mxenv](https://github.com/Morphicai/morphix-env) — machine-level extras beyond the project CLI.
+
+## Install
+
+```bash
+npm i -g @morphixai/mxenv-cli
+```
+
+## Commands
+
+- `mxenv-cli shell-init` — generate/remove PATH shims and the marked rc block (global + project shim manifests)
+- `gui` / `global` / `host` — reserved for Wave B (not implemented; rejected with guidance)
+
+Project commands (`run`/`export`/`edit`/…) come from [`@morphixai/mxenv`](https://www.npmjs.com/package/@morphixai/mxenv) installed as a devDependency — the global face deliberately does not include them.
+
+## License
+
+MIT © Morphicai — see [LICENSE](./LICENSE). Security policy: [SECURITY.md](./SECURITY.md).

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+`mxenv` composes secrets into short-lived processes; reports about secret leakage, unauthorized value disclosure, or bypass of the value-safety guarantees are handled with priority.
+
+## Supported Versions
+
+| Version | Supported |
+|---|---|
+| 0.12.x | ✅ |
+| 0.11.x | ✅ (security fixes during the 0.12.x migration window) |
+| < 0.11 | ❌ |
+
+## Reporting a Vulnerability
+
+Report privately via **GitHub Security Advisories → Private Vulnerability Reporting** on this repository ("Report a vulnerability"). Do not open a public issue for anything that involves secret exposure, redaction bypass, audit leaks, or local API/token handling.
+
+Include: affected version, reproduction steps (value-free — never attach real secrets), and impact. You will get an acknowledgement within 72 hours and a status update within 7 days. Fixes land in a patch release; disclosure is coordinated with the reporter.
+
+## Scope notes
+
+- The tool's value-safety model is **leakage minimization, not a cryptographic boundary** — see "Value safety" in the README. Reports that only restate this documented boundary (e.g. same-uid process reads a child's environment) are expected behavior, not vulnerabilities.
+- Issues in upstream providers (Infisical, Doppler, dotenvx, macOS Keychain) belong to those projects.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,460 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli.ts
+var import_os2 = require("os");
+var import_mxenv_core3 = require("@morphixai/mxenv-core");
+
+// src/shims.ts
+var import_fs = require("fs");
+var import_os = require("os");
+var import_path = require("path");
+var import_mxenv_core = require("@morphixai/mxenv-core");
+var import_mxenv_core2 = require("@morphixai/mxenv-core");
+var SHIM_MARKER = "# mxenv shim \u2014 regenerated by `mxenv shell-init`; do not edit by hand.";
+var LEGACY_SHIM_MARKER = "# mx-env shim \u2014 regenerated by `mx-env shell-init`; do not edit by hand.";
+function isGeneratedShim(content) {
+  return content.includes(SHIM_MARKER) || content.includes(LEGACY_SHIM_MARKER);
+}
+function renderShimScript(command) {
+  return `#!/bin/sh
+${SHIM_MARKER}
+command -v mxenv >/dev/null 2>&1 || { echo "[mxenv] mxenv not on PATH; reinstall mxenv or run 'mxenv-cli shell-init --remove' to clean up this shim." >&2; exit 127; }
+MXENV_SHIM=1 exec mxenv run -- ${command} "$@"
+`;
+}
+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 readIfExists(path) {
+  try {
+    return (0, import_fs.readFileSync)(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function writeShims(commands, homeDir = (0, import_os.homedir)()) {
+  const dir = (0, import_mxenv_core.shimsDir)(homeDir);
+  (0, import_fs.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_fs.readdirSync)(dir)) {
+    const path = (0, import_path.join)(dir, file);
+    const content = readIfExists(path);
+    if (content === null || !isGeneratedShim(content)) continue;
+    if (!wanted.has(file.toLowerCase())) {
+      (0, import_fs.rmSync)(path);
+      removed.push(file);
+    }
+  }
+  for (const command of commands) {
+    const path = (0, import_path.join)(dir, command);
+    const content = renderShimScript(command);
+    let isSymlink = false;
+    try {
+      isSymlink = (0, import_fs.lstatSync)(path).isSymbolicLink();
+    } catch {
+    }
+    const existing = isSymlink ? null : readIfExists(path);
+    if (!isSymlink && existing !== null && !isGeneratedShim(existing)) {
+      skipped.push(command);
+      continue;
+    }
+    if (isSymlink) (0, import_fs.rmSync)(path);
+    else if (existing === content) continue;
+    (0, import_fs.writeFileSync)(path, content, { mode: 493 });
+    (0, import_fs.chmodSync)(path, 493);
+    written.push(command);
+  }
+  return { written, removed, skipped };
+}
+function removeAllShims(homeDir = (0, import_os.homedir)()) {
+  const dir = (0, import_mxenv_core.shimsDir)(homeDir);
+  if (!(0, import_fs.existsSync)(dir)) return [];
+  const removed = [];
+  for (const file of (0, import_fs.readdirSync)(dir)) {
+    const path = (0, import_path.join)(dir, file);
+    const content = readIfExists(path);
+    if (content !== null && isGeneratedShim(content)) {
+      (0, import_fs.rmSync)(path);
+      removed.push(file);
+    }
+  }
+  return removed;
+}
+function detectHandmadeReservedShims(homeDir = (0, import_os.homedir)()) {
+  const dir = (0, import_mxenv_core.shimsDir)(homeDir);
+  if (!(0, import_fs.existsSync)(dir)) return [];
+  const found = [];
+  for (const file of (0, import_fs.readdirSync)(dir)) {
+    if (!import_mxenv_core.RESERVED_SHIM_NAMES.includes(file.toLowerCase())) continue;
+    const content = readIfExists((0, import_path.join)(dir, file));
+    if (content === null || !isGeneratedShim(content)) found.push(file);
+  }
+  return found;
+}
+function defaultRcPath(shell, homeDir = (0, import_os.homedir)()) {
+  const name = shell ? shell.split("/").pop() : "";
+  if (name === "zsh") return (0, import_path.join)(homeDir, ".zshrc");
+  if (name === "bash") return (0, import_path.join)(homeDir, ".bashrc");
+  return null;
+}
+function writeFileAtomic(path, content) {
+  const tmp = `${path}.mxenv-${process.pid}.tmp`;
+  (0, import_fs.writeFileSync)(tmp, content);
+  (0, import_fs.renameSync)(tmp, path);
+}
+function upsertRcBlock(rcPath, homeDir = (0, import_os.homedir)()) {
+  const existing = readIfExists(rcPath) ?? "";
+  const block = (0, import_mxenv_core.rcBlock)(homeDir);
+  const pattern = (0, import_mxenv_core.rcBlockPattern)();
+  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?${(0, import_mxenv_core.rcBlockPattern)().source}\\n?`, "g");
+  if (!pattern.test(existing)) return "absent";
+  writeFileAtomic(rcPath, existing.replace(pattern, "\n"));
+  return "removed";
+}
+function findShadowedCommands(commands, originalPath, homeDir = (0, import_os.homedir)()) {
+  if (!originalPath) return { absent: [...commands], shadowed: [] };
+  const dirs = originalPath.split(import_path.delimiter).filter(Boolean);
+  const absent = [];
+  const shadowed = [];
+  for (const command of commands) {
+    const shimPath = (0, import_path.join)((0, import_mxenv_core.shimsDir)(homeDir), command);
+    let resolvedTo = null;
+    for (const dir of dirs) {
+      const candidate = (0, import_path.join)(dir, command);
+      try {
+        (0, import_fs.accessSync)(candidate, import_fs.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 };
+}
+
+// package.json
+var package_default = {
+  name: "@morphixai/mxenv-cli",
+  version: "0.12.0",
+  description: "L3 management face for mxenv \u2014 machine-level extras like shell-init.",
+  license: "MIT",
+  author: "MorphixAI <dev@morphixai.com>",
+  homepage: "https://github.com/Morphicai/morphix-env#readme",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/Morphicai/morphix-env.git",
+    directory: "packages/mxenv-cli"
+  },
+  bugs: {
+    url: "https://github.com/Morphicai/morphix-env/issues"
+  },
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      default: "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  files: [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
+  ],
+  engines: {
+    node: ">=18"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  scripts: {
+    build: "tsup",
+    test: "pnpm --filter @morphixai/mxenv-core build && pnpm --filter @morphixai/mxenv build && pnpm build && vitest run",
+    typecheck: "pnpm --filter @morphixai/mxenv-core build && tsc --noEmit",
+    prepublishOnly: "node ../../scripts/prepublish-guard.mjs"
+  },
+  devDependencies: {
+    "@types/node": "^25.5.0",
+    tsup: "^8.0.0",
+    typescript: "^5.0.0",
+    vitest: "^4.1.1"
+  },
+  bin: {
+    mxenv: "./dist/cli.js",
+    "mx-env": "./dist/cli.js",
+    "morphix-env": "./dist/cli.js",
+    "mxenv-cli": "./dist/cli.js"
+  },
+  dependencies: {
+    "@morphixai/mxenv-core": "^0.12.0"
+  }
+};
+
+// src/cli.ts
+var VERSION = package_default.version;
+function parseArgs(argv) {
+  const args = {
+    command: "",
+    subArgs: [],
+    positionals: [],
+    envFiles: [],
+    outFile: null,
+    verbose: false,
+    filter: null,
+    noInfisical: false,
+    env: null,
+    profile: null,
+    noGlobal: false,
+    allowInsecureGlobal: false,
+    printEditorUrl: false,
+    source: null,
+    target: null,
+    to: null,
+    service: null,
+    force: false,
+    dryRun: false,
+    home: false,
+    serve: false,
+    write: false,
+    remove: false,
+    warnPlaintext: false,
+    unknownFlags: []
+  };
+  let i = 2;
+  const command = argv[i];
+  if (!command) return args;
+  args.command = command;
+  i++;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === "--") {
+      args.subArgs = argv.slice(i + 1);
+      break;
+    }
+    if (arg === "--env-file" || arg === "-f") {
+      if (argv[++i]) args.envFiles.push(argv[i]);
+    } else if (arg === "--out" || arg === "-o") {
+      if (argv[++i]) args.outFile = argv[i];
+    } else if (arg === "--filter") {
+      if (argv[++i]) args.filter = argv[i];
+    } else if (arg === "--env" || arg === "-e") {
+      if (argv[++i]) args.env = argv[i];
+    } else if (arg === "--profile" || arg === "-p") {
+      if (argv[++i]) args.profile = argv[i];
+    } else if (arg === "--source") {
+      if (argv[++i]) args.source = argv[i];
+    } else if (arg === "--verbose" || arg === "-v") {
+      args.verbose = true;
+    } else if (arg === "--no-infisical") {
+      args.noInfisical = true;
+    } else if (arg === "--no-global") {
+      args.noGlobal = true;
+    } else if (arg === "--allow-insecure-global") {
+      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 === "--to") {
+      if (argv[++i]) args.to = argv[i];
+    } else if (arg === "--service") {
+      if (argv[++i]) args.service = argv[i];
+    } else if (arg === "--force") {
+      args.force = true;
+    } else if (arg === "--dry-run") {
+      args.dryRun = true;
+    } else if (arg === "--home") {
+      args.home = true;
+    } else if (arg === "--write") {
+      args.write = true;
+    } else if (arg === "--remove") {
+      args.remove = true;
+    } else if (arg === "--serve") {
+      args.serve = true;
+    } else if (arg === "--warn-plaintext") {
+      args.warnPlaintext = true;
+    } else if (args.command === "run") {
+      args.subArgs = argv.slice(i);
+      break;
+    } else if (!arg.startsWith("-")) {
+      args.positionals.push(arg);
+    } else {
+      args.unknownFlags.push(arg);
+    }
+    i++;
+  }
+  return args;
+}
+function configLayers() {
+  return (0, import_mxenv_core3.loadConfigLayers)({ cwd: process.cwd(), homeDir: (0, import_os2.homedir)() });
+}
+var bootInfo = { viaShim: false };
+function cmdShellInit(args) {
+  if (process.platform === "win32") {
+    console.error("[mxenv] shell-init is supported on macOS/Linux only; on Windows keep using explicit `mxenv run -- <command>`.");
+    return 1;
+  }
+  if (args.unknownFlags.length) {
+    console.error(`[mxenv] shell-init: unrecognized flag(s): ${args.unknownFlags.join(", ")}`);
+    return 1;
+  }
+  if (args.home) {
+    console.error("[mxenv] shell-init: --home belongs to `migrate` (global directory migration) and is not accepted here.");
+    return 1;
+  }
+  if (args.write && args.remove) {
+    console.error("[mxenv] shell-init: --write and --remove are mutually exclusive.");
+    return 1;
+  }
+  try {
+    return runShellInit(args);
+  } catch (error) {
+    const code = error?.code;
+    console.error(`[mxenv] 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_os2.homedir)();
+  const rcPath = defaultRcPath(process.env.SHELL, home);
+  if (args.remove) {
+    const removed2 = removeAllShims(home);
+    const rcOutcome = rcPath ? removeRcBlock(rcPath) : "absent";
+    console.log(`[mxenv] Removed ${removed2.length} shim(s)${removed2.length ? ` (${removed2.join(", ")})` : ""}; rc block ${rcOutcome}${rcPath ? ` in ${rcPath}` : ""}.`);
+    return 0;
+  }
+  const problems = [
+    ...(0, import_mxenv_core3.validateShimList)(layers.global.config.shims, layers.global.path),
+    ...(0, import_mxenv_core3.validateShimList)(layers.project.config.shims, layers.project.path)
+  ];
+  if (problems.length) {
+    for (const problem of problems) console.error(`[mxenv] ${problem}`);
+    return 1;
+  }
+  const commands = resolveShimCommands(layers, !args.noGlobal);
+  const { written, removed, skipped } = writeShims(commands, home);
+  console.log(`[mxenv] Shims ready in ${(0, import_mxenv_core3.shimsDir)(home)} (${commands.length} command(s): ${commands.join(", ") || "none"}; ${written.length} written, ${removed.length} removed).`);
+  for (const command of skipped) {
+    console.warn(`[mxenv] Warning: "${command}" exists in the shims directory as a handmade file (no mxenv marker); refusing to overwrite. Remove or rename it by hand, then re-run shell-init.`);
+  }
+  for (const file of detectHandmadeReservedShims(home)) {
+    console.warn(`[mxenv] Warning: "${file}" in the shims directory was not created by mxenv and shadows a reserved command; delete it by hand. Do not place files in ${(0, import_mxenv_core3.shimsDir)(home)} manually.`);
+  }
+  const { absent, shadowed } = findShadowedCommands(commands, bootInfo.originalPath, home);
+  if (absent.length) {
+    console.warn(`[mxenv] 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(`[mxenv] Warning: these commands resolve to a different executable ahead of their shim: ${shadowed.join(", ")} \u2014 move ${(0, import_mxenv_core3.shimsDir)(home)} ahead of the entries that provide them.`);
+  }
+  if (args.write) {
+    if (!rcPath) {
+      console.error("[mxenv] 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(`[mxenv] 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="${(0, import_mxenv_core3.shimsDir)(home)}:$PATH"
+
+Or re-run with --write to let mxenv maintain a marked block in your rc file.`);
+  return 0;
+}
+function showHelp() {
+  console.log(`
+mxenv CLI (mxenv-cli) v${VERSION} \u2014 machine-level management face
+
+Usage:
+  mxenv-cli shell-init [--write|--remove]    Generate PATH shims for declared commands
+
+Options:
+  --write                  Also maintain a marked PATH block in your rc file
+  --remove                 Remove every generated shim and the rc PATH block
+  --no-global              Generate project-declared shims only (skip the global config list)
+  --help, -h               Show this help
+  --version                Show version
+
+Project-level commands (run, export, inspect, edit, migrate, \u2026) come from the
+project-local install (node_modules/.bin); this CLI manages the machine only.
+`);
+}
+function cmdReserved(command) {
+  console.error(`[mxenv] "${command}" is reserved for a future release and is not implemented yet.`);
+  return 1;
+}
+async function main() {
+  (0, import_mxenv_core3.warnDeprecatedBinInvocation)(process.argv[1]);
+  Object.assign(bootInfo, (0, import_mxenv_core3.sanitizeBootEnv)());
+  const args = parseArgs(process.argv);
+  switch (args.command) {
+    case "shell-init":
+      return cmdShellInit(args);
+    // Wave B skeleton (package-split 4.3): reserved, not implemented.
+    case "gui":
+    case "global":
+    case "host":
+      return cmdReserved(args.command);
+    case "--help":
+    case "-h":
+    case "help":
+      showHelp();
+      return 0;
+    case "--version":
+      console.log(VERSION);
+      return 0;
+    default:
+      if (args.command) console.error(`[mxenv] Unknown command: ${args.command}`);
+      showHelp();
+      return args.command ? 1 : 0;
+  }
+}
+main().then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  const message = error instanceof Error ? error.message : "[mxenv] Command failed.";
+  console.error(message);
+  process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { ConfigLayers } from '@morphixai/mxenv-core';
+export { LEGACY_RC_BLOCK_BEGIN, LEGACY_RC_BLOCK_END, RC_BLOCK_BEGIN, RC_BLOCK_END, hasRcBlock, rcBlock, rcBlockPattern, replaceRcBlocks } from '@morphixai/mxenv-core';
+
+/**
+ * D5 spawn 版本对齐（spec package-boundary「项目态写操作版本对齐」）：
+ * 全局 CLI（L3）在项目作用域执行写操作（修改项目来源/配置）时，必须 spawn
+ * 项目本地 CLI（L2，项目 node_modules 钉定版本）执行，绝不以全局侧自身版本
+ * 直接改写项目数据。解析顺序 cwd → `node_modules/.bin` → PATH，与
+ * mxenv-core 的 ensureCommand 哲学一致；解析失败硬失败并给安装指引。
+ * Wave A 消费方为 Wave B 的 gui/global/host 命令预留；本模块先落地机制与
+ * 两向验证（「项目写走本地版本」「无本地 CLI 明确失败」）。
+ */
+/** L2 CLI 的 bin 名（命名全切归 mxenv-naming-cutover，此处不改名）。 */
+/** 新名 `mxenv` 优先；旧名 alias 于 0.12.x 垫片窗口内照认（naming-migration）。 */
+declare const LOCAL_CLI_BIN_NAMES: readonly ["mxenv", "mx-env", "morphix-env"];
+declare class LocalCliMissingError extends Error {
+    readonly cwd: string;
+    constructor(cwd: string);
+}
+/**
+ * Resolves the project-local L2 CLI. Order mirrors ensureCommand:
+ * `<cwd>/node_modules/.bin/<bin>` first, then PATH lookup. Returns null when
+ * nothing resolves — callers turn that into a hard failure, never a fallback
+ * to the global engine.
+ */
+declare function resolveLocalCli(cwd?: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Runs a project-scoped write through the project-local CLI. Throws
+ * LocalCliMissingError (actionable install guidance, value-free) when no local
+ * CLI resolves — the global CLI must never write project data itself.
+ * Returns the child's exit status.
+ */
+declare function spawnLocalCliWrite(args: string[], options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): number;
+
+/**
+ * Shim generation / stripping / two-level manifests for `shell-init` (L3).
+ * The shared pure PATH/list logic (shimsDir, RESERVED_SHIM_NAMES,
+ * validateShimList, stripShimsFromPath, sanitizeBootEnv) lives in
+ * mxenv-core so the L2 CLI shares one implementation (package-split 4.1).
+ */
+/** Marks files generated by `mxenv-cli shell-init`; handmade files lack it and are never touched. */
+declare const SHIM_MARKER = "# mxenv shim \u2014 regenerated by `mxenv shell-init`; do not edit by hand.";
+/** 0.12.x 前生成的 shim 标记：识别/剥离双认（升级后旧块不得泄漏），写侧只产新名。 */
+declare const LEGACY_SHIM_MARKER = "# mx-env shim \u2014 regenerated by `mx-env shell-init`; do not edit by hand.";
+/** 工具生成判定（新旧双认）：无标记=手工文件，永不触碰。 */
+declare function isGeneratedShim(content: string): boolean;
+/**
+ * Shim body: guard against a missing mxenv (uninstall, nvm switch) with an
+ * actionable message instead of a bare "command not found", then hand off to
+ * `run`. The marker line identifies tool-generated shims for --remove and
+ * convergence; MXENV_SHIM is read by the CLI at boot and stripped before any
+ * composition or child spawn.
+ */
+declare function renderShimScript(command: string): string;
+/** Effective shim list: global ∪ project, deduplicated case-insensitively. */
+declare function resolveShimCommands(layers: ConfigLayers, includeGlobal?: boolean): string[];
+/**
+ * Writes shims for the declared commands and converges the directory: stale
+ * tool-generated shims (marker present) whose command is no longer declared
+ * are removed. **Handmade files (no marker) are never touched** — a declared
+ * command colliding with one is skipped and reported, never overwritten.
+ * Idempotent — rewriting an up-to-date shim is skipped byte-for-byte.
+ */
+declare function writeShims(commands: string[], homeDir?: string): {
+    written: string[];
+    removed: string[];
+    skipped: string[];
+};
+/** Removes every tool-generated shim; handmade files are left alone. */
+declare function removeAllShims(homeDir?: string): string[];
+/**
+ * Handmade files that shadow reserved mxenv names would wrap mxenv itself in
+ * a shim (weird but terminating) — surface them so the user can delete them.
+ */
+declare function detectHandmadeReservedShims(homeDir?: string): string[];
+/** Infers the rc file from $SHELL; returns null for shells we do not write. */
+declare function defaultRcPath(shell: string | undefined, homeDir?: string): string | null;
+/** Idempotently installs the PATH block; all existing marked blocks are replaced. */
+declare function upsertRcBlock(rcPath: string, homeDir?: string): 'added' | 'updated' | 'unchanged';
+/** Idempotently removes every marked PATH block, leaving other content intact. */
+declare function removeRcBlock(rcPath: string): 'removed' | 'absent';
+/**
+ * Per-command PATH parity: a declared command must resolve to its shim file.
+ * `absent` — no executable by that name anywhere on PATH (first install: the
+ * shims dir is not on PATH yet); `shadowed` — an earlier PATH entry (volta,
+ * another tool) wins and the shim silently never fires. Uses the
+ * pre-sanitization PATH captured at boot.
+ */
+declare function findShadowedCommands(commands: string[], originalPath: string | undefined, homeDir?: string): {
+    absent: string[];
+    shadowed: string[];
+};
+
+export { LEGACY_SHIM_MARKER, LOCAL_CLI_BIN_NAMES, LocalCliMissingError, SHIM_MARKER, defaultRcPath, detectHandmadeReservedShims, findShadowedCommands, isGeneratedShim, removeAllShims, removeRcBlock, renderShimScript, resolveLocalCli, resolveShimCommands, spawnLocalCliWrite, upsertRcBlock, writeShims };

package/dist/index.js

@@ -0,0 +1,291 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  LEGACY_RC_BLOCK_BEGIN: () => import_mxenv_core2.LEGACY_RC_BLOCK_BEGIN,
+  LEGACY_RC_BLOCK_END: () => import_mxenv_core2.LEGACY_RC_BLOCK_END,
+  LEGACY_SHIM_MARKER: () => LEGACY_SHIM_MARKER,
+  LOCAL_CLI_BIN_NAMES: () => LOCAL_CLI_BIN_NAMES,
+  LocalCliMissingError: () => LocalCliMissingError,
+  RC_BLOCK_BEGIN: () => import_mxenv_core2.RC_BLOCK_BEGIN,
+  RC_BLOCK_END: () => import_mxenv_core2.RC_BLOCK_END,
+  SHIM_MARKER: () => SHIM_MARKER,
+  defaultRcPath: () => defaultRcPath,
+  detectHandmadeReservedShims: () => detectHandmadeReservedShims,
+  findShadowedCommands: () => findShadowedCommands,
+  hasRcBlock: () => import_mxenv_core2.hasRcBlock,
+  isGeneratedShim: () => isGeneratedShim,
+  rcBlock: () => import_mxenv_core2.rcBlock,
+  rcBlockPattern: () => import_mxenv_core2.rcBlockPattern,
+  removeAllShims: () => removeAllShims,
+  removeRcBlock: () => removeRcBlock,
+  renderShimScript: () => renderShimScript,
+  replaceRcBlocks: () => import_mxenv_core2.replaceRcBlocks,
+  resolveLocalCli: () => resolveLocalCli,
+  resolveShimCommands: () => resolveShimCommands,
+  spawnLocalCliWrite: () => spawnLocalCliWrite,
+  upsertRcBlock: () => upsertRcBlock,
+  writeShims: () => writeShims
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/local-cli.ts
+var import_child_process = require("child_process");
+var import_fs = require("fs");
+var import_path = require("path");
+var LOCAL_CLI_BIN_NAMES = ["mxenv", "mx-env", "morphix-env"];
+var LocalCliMissingError = class extends Error {
+  constructor(cwd) {
+    super(
+      `[mxenv] No project-local mxenv CLI found for ${cwd} (checked node_modules/.bin and PATH).
+Install it in the project so writes run the project-pinned version: npm i -D @morphixai/mxenv (or: pnpm add -D @morphixai/mxenv).
+Refusing to write project data with the global CLI.`
+    );
+    this.name = "LocalCliMissingError";
+    this.cwd = cwd;
+  }
+};
+function resolveLocalCli(cwd = process.cwd(), env = process.env) {
+  for (const name of LOCAL_CLI_BIN_NAMES) {
+    const localBinary = (0, import_path.resolve)(cwd, "node_modules", ".bin", name);
+    if (isExecutable(localBinary)) return localBinary;
+  }
+  for (const dir of (env.PATH ?? "").split(import_path.delimiter).filter(Boolean)) {
+    for (const name of LOCAL_CLI_BIN_NAMES) {
+      const candidate = (0, import_path.join)(dir, name);
+      if (isExecutable(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+function isExecutable(candidate) {
+  try {
+    if (!(0, import_fs.existsSync)(candidate)) return false;
+    (0, import_fs.accessSync)(candidate, import_fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function spawnLocalCliWrite(args, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const cli = resolveLocalCli(cwd, options.env);
+  if (!cli) throw new LocalCliMissingError(cwd);
+  const result = (0, import_child_process.spawnSync)(cli, args, {
+    cwd,
+    env: options.env ?? process.env,
+    stdio: ["ignore", "inherit", "inherit"]
+  });
+  if (result.error) {
+    throw new Error(`[mxenv] Failed to execute the project-local CLI (${cli}): ${result.error.message}`);
+  }
+  return result.status ?? 1;
+}
+
+// src/shims.ts
+var import_fs2 = require("fs");
+var import_os = require("os");
+var import_path2 = require("path");
+var import_mxenv_core = require("@morphixai/mxenv-core");
+var import_mxenv_core2 = require("@morphixai/mxenv-core");
+var SHIM_MARKER = "# mxenv shim \u2014 regenerated by `mxenv shell-init`; do not edit by hand.";
+var LEGACY_SHIM_MARKER = "# mx-env shim \u2014 regenerated by `mx-env shell-init`; do not edit by hand.";
+function isGeneratedShim(content) {
+  return content.includes(SHIM_MARKER) || content.includes(LEGACY_SHIM_MARKER);
+}
+function renderShimScript(command) {
+  return `#!/bin/sh
+${SHIM_MARKER}
+command -v mxenv >/dev/null 2>&1 || { echo "[mxenv] mxenv not on PATH; reinstall mxenv or run 'mxenv-cli shell-init --remove' to clean up this shim." >&2; exit 127; }
+MXENV_SHIM=1 exec mxenv run -- ${command} "$@"
+`;
+}
+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 readIfExists(path) {
+  try {
+    return (0, import_fs2.readFileSync)(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function writeShims(commands, homeDir = (0, import_os.homedir)()) {
+  const dir = (0, import_mxenv_core.shimsDir)(homeDir);
+  (0, import_fs2.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_fs2.readdirSync)(dir)) {
+    const path = (0, import_path2.join)(dir, file);
+    const content = readIfExists(path);
+    if (content === null || !isGeneratedShim(content)) continue;
+    if (!wanted.has(file.toLowerCase())) {
+      (0, import_fs2.rmSync)(path);
+      removed.push(file);
+    }
+  }
+  for (const command of commands) {
+    const path = (0, import_path2.join)(dir, command);
+    const content = renderShimScript(command);
+    let isSymlink = false;
+    try {
+      isSymlink = (0, import_fs2.lstatSync)(path).isSymbolicLink();
+    } catch {
+    }
+    const existing = isSymlink ? null : readIfExists(path);
+    if (!isSymlink && existing !== null && !isGeneratedShim(existing)) {
+      skipped.push(command);
+      continue;
+    }
+    if (isSymlink) (0, import_fs2.rmSync)(path);
+    else if (existing === content) continue;
+    (0, import_fs2.writeFileSync)(path, content, { mode: 493 });
+    (0, import_fs2.chmodSync)(path, 493);
+    written.push(command);
+  }
+  return { written, removed, skipped };
+}
+function removeAllShims(homeDir = (0, import_os.homedir)()) {
+  const dir = (0, import_mxenv_core.shimsDir)(homeDir);
+  if (!(0, import_fs2.existsSync)(dir)) return [];
+  const removed = [];
+  for (const file of (0, import_fs2.readdirSync)(dir)) {
+    const path = (0, import_path2.join)(dir, file);
+    const content = readIfExists(path);
+    if (content !== null && isGeneratedShim(content)) {
+      (0, import_fs2.rmSync)(path);
+      removed.push(file);
+    }
+  }
+  return removed;
+}
+function detectHandmadeReservedShims(homeDir = (0, import_os.homedir)()) {
+  const dir = (0, import_mxenv_core.shimsDir)(homeDir);
+  if (!(0, import_fs2.existsSync)(dir)) return [];
+  const found = [];
+  for (const file of (0, import_fs2.readdirSync)(dir)) {
+    if (!import_mxenv_core.RESERVED_SHIM_NAMES.includes(file.toLowerCase())) continue;
+    const content = readIfExists((0, import_path2.join)(dir, file));
+    if (content === null || !isGeneratedShim(content)) found.push(file);
+  }
+  return found;
+}
+function defaultRcPath(shell, homeDir = (0, import_os.homedir)()) {
+  const name = shell ? shell.split("/").pop() : "";
+  if (name === "zsh") return (0, import_path2.join)(homeDir, ".zshrc");
+  if (name === "bash") return (0, import_path2.join)(homeDir, ".bashrc");
+  return null;
+}
+function writeFileAtomic(path, content) {
+  const tmp = `${path}.mxenv-${process.pid}.tmp`;
+  (0, import_fs2.writeFileSync)(tmp, content);
+  (0, import_fs2.renameSync)(tmp, path);
+}
+function upsertRcBlock(rcPath, homeDir = (0, import_os.homedir)()) {
+  const existing = readIfExists(rcPath) ?? "";
+  const block = (0, import_mxenv_core.rcBlock)(homeDir);
+  const pattern = (0, import_mxenv_core.rcBlockPattern)();
+  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?${(0, import_mxenv_core.rcBlockPattern)().source}\\n?`, "g");
+  if (!pattern.test(existing)) return "absent";
+  writeFileAtomic(rcPath, existing.replace(pattern, "\n"));
+  return "removed";
+}
+function findShadowedCommands(commands, originalPath, homeDir = (0, import_os.homedir)()) {
+  if (!originalPath) return { absent: [...commands], shadowed: [] };
+  const dirs = originalPath.split(import_path2.delimiter).filter(Boolean);
+  const absent = [];
+  const shadowed = [];
+  for (const command of commands) {
+    const shimPath = (0, import_path2.join)((0, import_mxenv_core.shimsDir)(homeDir), command);
+    let resolvedTo = null;
+    for (const dir of dirs) {
+      const candidate = (0, import_path2.join)(dir, command);
+      try {
+        (0, import_fs2.accessSync)(candidate, import_fs2.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 };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LEGACY_RC_BLOCK_BEGIN,
+  LEGACY_RC_BLOCK_END,
+  LEGACY_SHIM_MARKER,
+  LOCAL_CLI_BIN_NAMES,
+  LocalCliMissingError,
+  RC_BLOCK_BEGIN,
+  RC_BLOCK_END,
+  SHIM_MARKER,
+  defaultRcPath,
+  detectHandmadeReservedShims,
+  findShadowedCommands,
+  hasRcBlock,
+  isGeneratedShim,
+  rcBlock,
+  rcBlockPattern,
+  removeAllShims,
+  removeRcBlock,
+  renderShimScript,
+  replaceRcBlocks,
+  resolveLocalCli,
+  resolveShimCommands,
+  spawnLocalCliWrite,
+  upsertRcBlock,
+  writeShims
+});

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@morphixai/mxenv-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.12.0",
+  "description": "L3 management face for mxenv \u2014 machine-level extras like shell-init.",
+  "license": "MIT",
+  "author": "MorphixAI <dev@morphixai.com>",
+  "homepage": "https://github.com/Morphicai/morphix-env#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Morphicai/morphix-env.git",
+    "directory": "packages/mxenv-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Morphicai/morphix-env/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "pnpm --filter @morphixai/mxenv-core build && pnpm --filter @morphixai/mxenv build && pnpm build && vitest run",
+    "typecheck": "pnpm --filter @morphixai/mxenv-core build && tsc --noEmit",
+    "prepublishOnly": "node ../../scripts/prepublish-guard.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.1"
+  },
+  "bin": {
+    "mxenv": "./dist/cli.js",
+    "mx-env": "./dist/cli.js",
+    "morphix-env": "./dist/cli.js",
+    "mxenv-cli": "./dist/cli.js"
+  },
+  "dependencies": {
+    "@morphixai/mxenv-core": "^0.12.0"
+  }
+}