@morphixai/mxenv 0.12.0 → 0.12.1

package/README.md

@@ -2,12 +2,16 @@
 
 L2 run face for [mxenv](https://github.com/Morphicai/morphix-env) — the project-side CLI and SDK runtime. Secrets stay with their owners (Infisical / Doppler / dotenvx / macOS Keychain / local files) and are composed into one value-safe child environment.
 
+> Upgrading from the old `morphix-env` package? See "Upgrading an existing project, step by step" in the [repository README](https://github.com/Morphicai/morphix-env#migrating-from-morphix-env--mx-env).
+
 ## Install
 
 ```bash
 npm i -D @morphixai/mxenv
 ```
 
+> ⚠️ **Do not install `@morphixai/mxenv` and `@morphixai/mxenv-cli` globally side by side** — both register the `mxenv`/`mx-env`/`morphix-env` bin names and the later install silently takes over the symlinks. Keep this package as a project devDependency and install `mxenv-cli` globally (or vice versa, never both).
+
 ## Commands
 
 `mxenv run|export|inspect|render|inject|generate|fetch|migrate|audit|edit|doc|skill` — see `mxenv --help`. Old bin names `mx-env`/`morphix-env` remain as deprecated aliases in 0.12.x (removed in 0.13).

package/dist/SKILL.md

@@ -22,11 +22,15 @@ mxenv 是密钥**组装层**，不是新的保险库：值永远留在 provider
 
 ```bash
 mxenv --version                          # 检测是否已安装
-npm install -g @morphixai/mxenv          # 安装运行面（项目内可用 devDep / npx 替代）
+npm install -D @morphixai/mxenv          # 项目内安装运行面（推荐：run/inspect/edit/migrate 全在）
 npx @morphixai/mxenv@latest inspect      # 免安装试用
-npm install -g @morphixai/mxenv-cli      # 可选：全局管理面（shell-init 等）
+npm install -g @morphixai/mxenv-cli      # 可选：机器级管理面（shell-init 等）
 ```
 
+> ⚠️ **不要把 `@morphixai/mxenv` 与 `@morphixai/mxenv-cli` 同时全局安装**：两者都注册
+> `mxenv`/`mx-env`/`morphix-env` bin，后装者会静默接管符号链接。项目用 devDep，
+> 全局只装 cli；若确要全局装运行面，就不要再装 cli。
+
 ## 配置（mxenv.config.json）
 
 配置文件**不含任何值**，只声明 source 接线与组合顺序。项目级放仓库根 `mxenv.config.json`；用户级 `~/.mxenv/config.json` 可选（全局基线，`--no-global` 可排除）。`~/.mxenv/.env` 是唯一自动发现的值文件（个人默认值）。
@@ -107,7 +111,7 @@ mxenv-cli shell-init [--write|--remove] # 为声明的命令生成 PATH shim（
 | `missing-optional, 0 keys` | `"optional": true` 的文件不存在，属预期；要强制存在就删掉 optional |
 | Keychain 权限弹框 / 拒绝 | 首次访问会请求 service 授权；拒绝后重试或换 service 命名空间 |
 | dotenvx 解密失败 | 解密密钥由 dotenvx 引导路径提供，不在本配置内 |
-| `mxenv: command not found` | `npm install -g @morphixai/mxenv`，或用 `npx @morphixai/mxenv@latest` 免安装 |
+| `mxenv: command not found` | 项目内 `npm install -D @morphixai/mxenv`（或全局装它，但勿再装 cli）；或用 `npx @morphixai/mxenv@latest` 免安装 |
 | `mxenv-cli: command not found` | shim 能力属全局管理面：`npm install -g @morphixai/mxenv-cli` |
 
 ---

package/dist/cli.js

@@ -342,6 +342,37 @@ async function executeUnit(unit, target, options = {}, homeDir = (0, import_os.h
     return { unit, status: "failed", backups, warnings: [], detail: message };
   }
 }
+function cleanupQuiet(path) {
+  try {
+    (0, import_fs.rmSync)(path, { recursive: true, force: true });
+  } catch {
+  }
+}
+function mergeScaffoldingCopy(source, dest, stamp) {
+  const merge = (src, dst) => {
+    (0, import_fs.mkdirSync)(dst, { recursive: true });
+    for (const entry of (0, import_fs.readdirSync)(src, { withFileTypes: true })) {
+      const from = (0, import_path.join)(src, entry.name);
+      const to = (0, import_path.join)(dst, entry.name);
+      if (entry.isDirectory()) {
+        merge(from, to);
+        continue;
+      }
+      if (!(0, import_fs.existsSync)(to)) {
+        (0, import_fs.copyFileSync)(from, to);
+        continue;
+      }
+      if (from.endsWith(".jsonl") && to.endsWith(".jsonl")) {
+        const base = (0, import_fs.readFileSync)(to, "utf8");
+        const extra = (0, import_fs.readFileSync)(from, "utf8");
+        (0, import_fs.appendFileSync)(to, (base && !base.endsWith("\n") ? "\n" : "") + extra);
+        continue;
+      }
+      (0, import_fs.copyFileSync)(from, (0, import_path.join)(dst, `${entry.name}.fold-${stamp}`));
+    }
+  };
+  merge(source, dest);
+}
 function copyTree(src, dest) {
   (0, import_fs.mkdirSync)(dest, { recursive: true });
   (0, import_fs.chmodSync)(dest, (0, import_fs.statSync)(src).mode & 4095);
@@ -423,8 +454,22 @@ async function migrateHome(homeDir = (0, import_os.homedir)(), options = {}) {
   const targetDir = (0, import_path.resolve)(homeDir, import_mxenv_core.GLOBAL_CONFIG_DIR);
   const markerName = ".mxenv-verify-pending";
   const markerPath = (0, import_path.join)(targetDir, markerName);
+  const asideDir = `${targetDir}.scaffold-fold`;
   const allowInsecureGlobal = options.allowInsecureGlobal ?? false;
   const backupsOnDisk = () => (0, import_fs.readdirSync)(homeDir).filter((name) => name.startsWith(`${import_mxenv_core.LEGACY_GLOBAL_CONFIG_DIR}.backup-`)).sort();
+  let mergeScaffolding = false;
+  if ((0, import_fs.existsSync)(asideDir) && !(0, import_fs.existsSync)(targetDir)) {
+    try {
+      (0, import_fs.renameSync)(asideDir, targetDir);
+    } catch (error) {
+      return {
+        status: "failed",
+        exitCode: 1,
+        keyNames: [],
+        detail: `cannot restore pre-migration scaffolding from ${asideDir}: ${error instanceof Error ? error.message : "unknown failure"} \u2014 rename it to ${targetDir} by hand, then re-run.`
+      };
+    }
+  }
   if ((0, import_fs.existsSync)(targetDir)) {
     if ((0, import_fs.existsSync)(markerPath)) {
       let backupDir2 = "";
@@ -467,13 +512,17 @@ async function migrateHome(homeDir = (0, import_os.homedir)(), options = {}) {
         };
       }
     } else if ((0, import_fs.existsSync)(legacyDir)) {
-      return {
-        status: "conflict",
-        exitCode: 1,
-        keyNames: [],
-        detail: `both ${targetDir} and ${legacyDir} exist \u2014 refusing to overwrite (no writes made). Resolve by hand: inspect both, keep what you need in ${targetDir}, then rename ${legacyDir} away and re-run.`
-      };
+      if ((0, import_mxenv_core.hasGlobalDataAt)(targetDir)) {
+        return {
+          status: "conflict",
+          exitCode: 1,
+          keyNames: [],
+          detail: `both ${targetDir} and ${legacyDir} exist \u2014 refusing to overwrite (no writes made). Resolve by hand: inspect both, keep what you need in ${targetDir}, then rename ${legacyDir} away and re-run.`
+        };
+      }
+      mergeScaffolding = true;
     } else {
+      if ((0, import_fs.existsSync)(asideDir)) cleanupQuiet(asideDir);
       return { status: "noop", exitCode: 0, keyNames: [], detail: `already migrated: ${targetDir} is in use.` };
     }
   }
@@ -516,25 +565,55 @@ async function migrateHome(homeDir = (0, import_os.homedir)(), options = {}) {
     copyTree(legacyDir, partialDir);
     (0, import_fs.writeFileSync)((0, import_path.join)(partialDir, markerName), `${backupDir}
 `);
+    if (mergeScaffolding) {
+      (0, import_fs.renameSync)(targetDir, asideDir);
+      if ((0, import_mxenv_core.hasGlobalDataAt)(asideDir)) {
+        (0, import_fs.renameSync)(asideDir, targetDir);
+        cleanup(partialDir);
+        return {
+          status: "conflict",
+          exitCode: 1,
+          keyNames: [],
+          detail: `both ${targetDir} and ${legacyDir} appeared to hold real data mid-migration \u2014 nothing was changed; inspect both, keep what you need in ${targetDir}, then rename ${legacyDir} away and re-run.`
+        };
+      }
+    }
+    if ((0, import_fs.existsSync)(asideDir)) mergeScaffoldingCopy(asideDir, partialDir, stamp);
     (0, import_fs.renameSync)(partialDir, targetDir);
   } catch (error) {
     const cleanupIssue = cleanup(partialDir);
+    let asideIssue = "";
+    if ((0, import_fs.existsSync)(asideDir) && !(0, import_fs.existsSync)(targetDir)) {
+      try {
+        (0, import_fs.renameSync)(asideDir, targetDir);
+      } catch {
+        asideIssue = `; restore ${asideDir} to ${targetDir} failed \u2014 rename it back by hand`;
+      }
+    }
     return {
       status: "failed",
       exitCode: 1,
       keyNames: [],
-      detail: `copy failed: ${error instanceof Error ? error.message : "unknown failure"}; ${cleanupIssue ?? `removed partial copy`}, original preserved at ${legacyDir}.`
+      detail: `copy failed: ${error instanceof Error ? error.message : "unknown failure"}; ${cleanupIssue ?? `removed partial copy`}, original preserved at ${legacyDir}.${asideIssue}`
     };
   }
   try {
     (0, import_fs.renameSync)(legacyDir, backupDir);
   } catch (error) {
     const cleanupIssue = [cleanup(partialDir), cleanup(targetDir)].find(Boolean) ?? null;
+    let asideIssue = "";
+    if ((0, import_fs.existsSync)(asideDir)) {
+      try {
+        (0, import_fs.renameSync)(asideDir, targetDir);
+      } catch {
+        asideIssue = `; restore ${asideDir} to ${targetDir} failed \u2014 rename it back by hand`;
+      }
+    }
     return {
       status: "failed",
       exitCode: 1,
       keyNames: [],
-      detail: `backup rename failed: ${error instanceof Error ? error.message : "unknown failure"}; ${cleanupIssue ?? `removed partial copy`}, original preserved at ${legacyDir}.`
+      detail: `backup rename failed: ${error instanceof Error ? error.message : "unknown failure"}; ${cleanupIssue ?? `removed partial copy`}, original preserved at ${legacyDir}.${asideIssue}`
     };
   }
   const restoreFromBackup = (why) => {
@@ -545,11 +624,19 @@ async function migrateHome(homeDir = (0, import_os.homedir)(), options = {}) {
     } catch {
     }
     const cleanupIssue = cleanup(targetDir);
+    let asideIssue = "";
+    if ((0, import_fs.existsSync)(asideDir)) {
+      try {
+        (0, import_fs.renameSync)(asideDir, targetDir);
+      } catch {
+        asideIssue = `; RESTORE FAILED for ${asideDir} \u2014 rename it to ${targetDir} by hand`;
+      }
+    }
     return {
       status: "failed",
       exitCode: 1,
       keyNames: [],
-      detail: `verification failed: ${why}; ${restored ? `restored from backup ${backupDir} (directory backup)` : `RESTORE FAILED \u2014 restore manually by renaming the directory backup ${backupDir} to ${legacyDir}`}; ${cleanupIssue ?? `removed partial ${targetDir}`}.`
+      detail: `verification failed: ${why}; ${restored ? `restored from backup ${backupDir} (directory backup)` : `RESTORE FAILED \u2014 restore manually by renaming the directory backup ${backupDir} to ${legacyDir}`}; ${cleanupIssue ?? `removed partial ${targetDir}`}${asideIssue}.`
     };
   };
   let after;
@@ -568,6 +655,7 @@ async function migrateHome(homeDir = (0, import_os.homedir)(), options = {}) {
     (0, import_fs.rmSync)(markerPath);
   } catch {
   }
+  if ((0, import_fs.existsSync)(asideDir)) cleanupQuiet(asideDir);
   const rc = rewriteRcBlocksForMigration(homeDir);
   const rcSummary = rc.updated.length ? `; rc PATH block rewired in ${rc.updated.join(", ")}` : "";
   const rcHint = !rc.found || rc.failures.length ? `[mxenv] shim PATH wiring: run \`mxenv-cli shell-init --write\` to point your rc block at ${(0, import_mxenv_core.shimsDir)(homeDir)}${rc.failures.length ? ` (rc rewrite failed: ${rc.failures.join("; ")})` : " (no marked rc block found)"}.` : void 0;
@@ -1209,7 +1297,7 @@ function warnOutputGitRisk(path) {
 // package.json
 var package_default = {
   name: "@morphixai/mxenv",
-  version: "0.12.0",
+  version: "0.12.1",
   description: "L2 run face for mxenv \u2014 run/export/inspect, source management, edit, migrate, skills.",
   license: "MIT",
   author: "MorphixAI <dev@morphixai.com>",
@@ -1305,6 +1393,7 @@ function parseArgs(argv) {
     write: false,
     remove: false,
     warnPlaintext: false,
+    help: false,
     unknownFlags: []
   };
   let i = 2;
@@ -1360,6 +1449,8 @@ function parseArgs(argv) {
       args.serve = true;
     } else if (arg === "--warn-plaintext") {
       args.warnPlaintext = true;
+    } else if (arg === "--help" || arg === "-h") {
+      args.help = true;
     } else if (args.command === "run") {
       args.subArgs = argv.slice(i);
       break;
@@ -1952,6 +2043,11 @@ async function main() {
   (0, import_mxenv_core3.warnDeprecatedBinInvocation)(process.argv[1]);
   Object.assign(bootInfo, (0, import_mxenv_core3.sanitizeBootEnv)());
   const args = parseArgs(process.argv);
+  if (args.help) {
+    showHelp();
+    return 0;
+  }
+  if (args.noGlobal) (0, import_mxenv_core3.suppressLegacyHomeHint)();
   switch (args.command) {
     case "run":
       return cmdRun(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morphixai/mxenv",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "L2 run face for mxenv — run/export/inspect, source management, edit, migrate, skills.",
   "license": "MIT",
   "author": "MorphixAI <dev@morphixai.com>",