msdevflow 0.7.7 → 0.7.8

package/README.md

@@ -58,6 +58,25 @@ Claude Code + Codex         -> 两套受管副本
 
 每个物理目标都包含完整套件，薄路由器不复制核心业务规则。已有 entry 只有在 manifest 精确匹配自身名称时才允许更新；由旧版包管理的 `msdevflow` 目录会在新套件全部验证后安全迁移，来源不明的目录、文件或符号链接会阻断安装。
 
+### WSL 与 Windows Agent
+
+setup 以 **Agent 可执行文件实际所在环境** 决定安装侧，而不是只看命令从哪个 shell 发起：
+
+- Agent 只安装在 Windows：可以从 WSL 调用 Windows `npx.cmd`，setup 会标记 `Runtime mode: windows-bridge-from-wsl`，并把 Skill、Python venv 和 GitCode CLI 安装在 Windows 用户环境。
+- Agent 只安装在 WSL：必须使用 WSL 内的 Linux Node.js/npm；若误用了 Windows Node，setup 会在写入任何 Python、npm 或 Skill 文件前停止。
+- 同名 Agent 同时存在于 Windows 与 WSL：setup 不猜目标；请从目标环境的终端重新运行。
+
+准备 WSL 原生 Agent 时先确认以下命令全部解析为 Linux 路径，而不是 `/mnt/<drive>/...` 或 `.cmd`：
+
+```bash
+type -a node npm npx opencode
+npx msdevflow@latest setup
+```
+
+示例使用 OpenCode；使用 Claude Code 或 Codex 时把 `opencode` 替换为实际 Agent 命令。
+
+Windows bridge 模式应从 WSL 中解析到 Windows Agent；也可直接在 Windows Terminal/PowerShell 中运行 setup。此前失败后可直接重跑，setup 会安全复用或修复带受管 marker 的 runtime，不需要手动删除。
+
 自定义目录：
 
 ```bash

package/lib/bootstrap.js

@@ -799,6 +799,219 @@ export function detectClients(run, platform) {
   return SUPPORTED_CLIENTS.filter((client) => Boolean(resolveExecutable(client, run, platform)));
 }
 
+function wslDistroFromUnc(value) {
+  return typeof value === "string"
+    ? value.match(/^\\\\wsl(?:\.localhost|\$)\\([^\\]+)/i)?.[1] || ""
+    : "";
+}
+
+function windowsNodeFromWsl(environment, platform) {
+  // Windows Node keeps process.platform=win32 when a WSL shell launches npx.cmd.
+  if (platform !== "win32") {
+    return null;
+  }
+  const distro = environment.WSL_DISTRO_NAME
+    || wslDistroFromUnc(environment.INIT_CWD)
+    || wslDistroFromUnc(environment.PWD);
+  if (!distro && !environment.WSL_INTEROP) {
+    return null;
+  }
+  return { distro: distro || "" };
+}
+
+async function detectClientExecutables(run, platform) {
+  const entries = await Promise.all(SUPPORTED_CLIENTS.map(async (client) => [
+    client,
+    await resolveExecutableAsync(client, run, platform),
+  ]));
+  return Object.fromEntries(entries.filter(([, executable]) => executable));
+}
+
+function wslClientLookup(distro) {
+  const args = [];
+  if (distro) {
+    args.push("--distribution", distro);
+  }
+  const script = [
+    "for name do",
+    "  old_ifs=$IFS",
+    "  IFS=: ",
+    "  for dir in $PATH; do",
+    "    IFS=$old_ifs",
+    "    [ -n \"$dir\" ] || dir=.",
+    "    for candidate in \"$dir/$name\" \"$dir/$name.cmd\" \"$dir/$name.exe\" \"$dir/$name.bat\"; do",
+    "      [ -f \"$candidate\" ] || continue",
+    "      case \"$candidate\" in",
+    "        /mnt/[a-zA-Z]/*)",
+    "          [ -f \"${candidate}.cmd\" ] && candidate=\"${candidate}.cmd\"",
+    "          windows=$(wslpath -w -- \"$candidate\" 2>/dev/null) || continue",
+    "          printf '%s\\twindows\\t%s\\n' \"$name\" \"$windows\"",
+    "          ;;",
+    "        *)",
+    "          [ -x \"$candidate\" ] || continue",
+    "          native=$(readlink -f -- \"$candidate\" 2>/dev/null || printf '%s' \"$candidate\")",
+    "          case \"$native\" in",
+    "            /mnt/[a-zA-Z]/*)",
+    "              [ -f \"${native}.cmd\" ] && native=\"${native}.cmd\"",
+    "              windows=$(wslpath -w -- \"$native\" 2>/dev/null) || continue",
+    "              printf '%s\\twindows\\t%s\\n' \"$name\" \"$windows\"",
+    "              ;;",
+    "            *) printf '%s\\twsl\\t%s\\n' \"$name\" \"$native\" ;;",
+    "          esac",
+    "          ;;",
+    "      esac",
+    "      break",
+    "    done",
+    "    IFS=: ",
+    "  done",
+    "  IFS=$old_ifs",
+    "done",
+  ].join("\n");
+  args.push("--exec", "sh", "-lc", script, "sh", ...SUPPORTED_CLIENTS);
+  return { command: "wsl.exe", args };
+}
+
+async function detectWslClientExecutables(run, distro) {
+  const result = await runOptionalAsync(run, wslClientLookup(distro));
+  if (result.status !== 0) {
+    return { wsl: {}, windows: {} };
+  }
+  const clients = { wsl: {}, windows: {} };
+  for (const line of result.stdout.split(/\r?\n/)) {
+    const [name, side, executable] = line.split("\t", 3);
+    if (
+      SUPPORTED_CLIENTS.includes(name)
+      && (side === "wsl" || side === "windows")
+      && executable
+      && !clients[side][name]
+    ) {
+      clients[side][name] = executable;
+    }
+  }
+  return clients;
+}
+
+async function inspectMixedWslClients(run, context) {
+  const [windowsPath, wslLookup] = await Promise.all([
+    detectClientExecutables(run, "win32"),
+    detectWslClientExecutables(run, context.distro),
+  ]);
+  return {
+    ...context,
+    windows: { ...wslLookup.windows, ...windowsPath },
+    wsl: wslLookup.wsl,
+  };
+}
+
+function clientLocations(inspection, clients) {
+  return clients.map((client) => ({
+    client,
+    windows: inspection.windows[client] || "",
+    wsl: inspection.wsl[client] || "",
+  }));
+}
+
+function mixedClientError(inspection, clients, reason) {
+  const locations = clientLocations(inspection, clients);
+  const details = locations.map(({ client, windows, wsl }) => [
+    `${client}:`,
+    windows ? `Windows=${windows}` : "Windows=not-found",
+    wsl ? `WSL=${wsl}` : "WSL=not-found",
+  ].join(" ")).join("; ");
+  const guidance = `Use Node.js >=18 and npm installed inside WSL, verify "type -a node npm npx ${clients.join(" ")}" resolves to Linux paths, then rerun "npx msdevflow@latest setup" from WSL. To configure a Windows agent instead, run setup from a Windows terminal. No changes were applied.`;
+  return new BootstrapError(`${reason} ${details}. ${guidance}`, 2);
+}
+
+function resolveMixedWslTargets(inspection, clients) {
+  const locations = clientLocations(inspection, clients);
+  const ambiguous = locations.filter(({ windows, wsl }) => windows && wsl);
+  if (ambiguous.length) {
+    throw mixedClientError(
+      inspection,
+      ambiguous.map(({ client }) => client),
+      "The selected agent exists in both Windows and WSL, so setup cannot safely choose which environment owns it.",
+    );
+  }
+  const wslOnly = locations.filter(({ windows, wsl }) => !windows && wsl);
+  if (wslOnly.length) {
+    throw mixedClientError(
+      inspection,
+      wslOnly.map(({ client }) => client),
+      "The selected agent exists only inside WSL, but msdevflow is running with Windows Node.js.",
+    );
+  }
+  const missing = locations.filter(({ windows, wsl }) => !windows && !wsl);
+  if (missing.length) {
+    throw mixedClientError(
+      inspection,
+      missing.map(({ client }) => client),
+      "The selected agent was not found in either Windows or WSL.",
+    );
+  }
+  return {
+    mode: "windows-bridge-from-wsl",
+    agentExecutables: Object.fromEntries(
+      locations.map(({ client, windows }) => [client, windows]),
+    ),
+  };
+}
+
+async function resolveSetupContext(
+  options,
+  environment,
+  platform,
+  run,
+  runLong,
+  selectClients,
+  progress,
+) {
+  const context = windowsNodeFromWsl(environment, platform);
+  if (!context) {
+    return {
+      targetSelection: await resolveClientTargets(
+        options,
+        run,
+        platform,
+        selectClients,
+      ),
+      runtime: {
+        mode: platform === "win32" ? "windows-native" : "posix-native",
+        agentExecutables: {},
+      },
+    };
+  }
+
+  const inspection = await progress.run(
+    "Inspecting Windows and WSL agent installations",
+    () => inspectMixedWslClients(runLong, context),
+  );
+  let targetSelection;
+  if (options.targetsSpecified) {
+    targetSelection = {
+      clients: options.targets,
+      source: "explicit",
+      detected: [],
+    };
+  } else if (options.skillsDir) {
+    targetSelection = {
+      clients: ["claude"],
+      source: "legacy-skills-dir",
+      detected: [],
+    };
+  } else {
+    const detected = SUPPORTED_CLIENTS.filter(
+      (client) => inspection.windows[client] || inspection.wsl[client],
+    );
+    targetSelection = detected.length
+      ? { clients: detected, source: "detected", detected }
+      : { clients: await selectClients(), source: "selected", detected: [] };
+  }
+  return {
+    targetSelection,
+    runtime: resolveMixedWslTargets(inspection, targetSelection.clients),
+  };
+}
+
 async function selectClientTargets(input, output, promptOutput = output) {
   if (!input.isTTY || !output.isTTY) {
     throw new BootstrapError(
@@ -1257,11 +1470,15 @@ export function gitcodeInstallDetails(
       npmCommand: ["npm", "install", "-g", GITCODE_PACKAGE, "--prefix", installPrefix, `--registry=${REGISTRY}`],
     };
   }
+  const installPrefix = npmPrefix || "<npm-global-prefix>";
   return {
     mode: classification === "npm-official" ? "upgrade-npm" : "standard",
     workflowCommand: "gitcode",
-    target: npmPrefix || "<npm-global-prefix>",
-    cliTarget: null,
+    target: installPrefix,
+    cliTarget: pathApi.join(
+      installPrefix,
+      ...(platform === "win32" ? ["gitcode.cmd"] : ["bin", "gitcode"]),
+    ),
     wrapperDir: null,
     wrapper: null,
     npmCommand: ["npm", "install", "-g", GITCODE_PACKAGE, `--registry=${REGISTRY}`],
@@ -1357,12 +1574,20 @@ async function installGitcode(plan, runLong, run, platform) {
     };
   }
   const executable = resolveExecutable("gitcode", run, platform);
-  if (!executable) {
-    throw new BootstrapError("GitCode npm CLI was installed but the gitcode executable is not available on PATH.");
+  if (executable) {
+    return {
+      command: plan.gitcodeInstall.workflowCommand,
+      executable,
+    };
   }
+  // The parent process keeps its original PATH after npm creates a global shim.
+  verifyFile(
+    plan.gitcodeInstall.cliTarget,
+    `GitCode npm CLI was installed but its executable was not found on PATH or at ${plan.gitcodeInstall.cliTarget}.`,
+  );
   return {
     command: plan.gitcodeInstall.workflowCommand,
-    executable,
+    executable: plan.gitcodeInstall.cliTarget,
   };
 }
 
@@ -1388,6 +1613,10 @@ function safeAuthStatus(output) {
 function printPlan(plan, write) {
   write("Setup plan (no changes made yet):");
   write(`  Client targets: ${plan.clientTargets.clients.join(", ")} (${plan.clientTargets.source})`);
+  write(`  Runtime mode: ${plan.clientTargets.runtimeMode}`);
+  for (const [client, executable] of Object.entries(plan.clientTargets.agentExecutables)) {
+    write(`  Agent executable (${client}): ${executable}`);
+  }
   write(`  Bundled skill suite: ${plan.skillInstalls[0].details.source}`);
   for (const { layout, details } of plan.skillInstalls) {
     write(`  Skill root: ${details.target}`);
@@ -1524,6 +1753,7 @@ async function authenticateGitcode(
 function textResult(result, write) {
   write("Setup completed:");
   write(`  Client targets: ${result.clients.join(", ")}`);
+  write(`  Runtime mode: ${result.runtimeMode}`);
   for (const skill of result.skills) {
     write(`  Skill suite: ${skill.status} at ${skill.target} (${skill.clients.join(", ")})`);
     write(`    Entries: ${skill.entries.map((entry) => entry.name).join(", ")}`);
@@ -1558,16 +1788,20 @@ export async function runSetup(options, dependencies = {}) {
     writeProgress,
     dependencies.timers,
   );
-  const targetSelection = await resolveClientTargets(
+  const setupContext = await resolveSetupContext(
     options,
-    run,
+    environment,
     platform,
+    run,
+    runLong,
     dependencies.selectClients || (() => selectClientTargets(
       process.stdin,
       process.stdout,
       options.json ? process.stderr : process.stdout,
     )),
+    progress,
   );
+  const targetSelection = setupContext.targetSelection;
   const layouts = resolveLayouts(
     options,
     targetSelection.clients,
@@ -1584,6 +1818,8 @@ export async function runSetup(options, dependencies = {}) {
   }));
   const clientTargets = {
     ...targetSelection,
+    runtimeMode: setupContext.runtime.mode,
+    agentExecutables: setupContext.runtime.agentExecutables,
     warnings: clientTargetWarnings(targetSelection.clients, layouts),
   };
 
@@ -1675,7 +1911,20 @@ export async function runSetup(options, dependencies = {}) {
   if (!options.yes && !(await (dependencies.confirm || confirmPlan)(process.stdin, process.stdout))) {
     throw new BootstrapError("Setup cancelled; no changes were applied.", 2);
   }
-  await progress.run("Revalidating command ownership", async () => {
+  await progress.run("Revalidating environment ownership", async () => {
+    const runtimeContext = windowsNodeFromWsl(environment, platform);
+    if (clientTargets.runtimeMode === "windows-bridge-from-wsl") {
+      const currentRuntime = resolveMixedWslTargets(
+        await inspectMixedWslClients(runLong, runtimeContext),
+        clientTargets.clients,
+      );
+      if (JSON.stringify(currentRuntime) !== JSON.stringify(setupContext.runtime)) {
+        throw new BootstrapError(
+          "Agent installation locations changed after confirmation; refusing to install.",
+          3,
+        );
+      }
+    }
     const currentDiagnosis = await diagnoseGitcodeAsync(runLong, platform);
     if (currentDiagnosis.classification !== diagnosis.classification
         || currentDiagnosis.existingExecutable !== diagnosis.existingExecutable) {
@@ -1736,6 +1985,8 @@ export async function runSetup(options, dependencies = {}) {
     git: gitVersion,
     clients: clientTargets.clients,
     targetSource: clientTargets.source,
+    runtimeMode: clientTargets.runtimeMode,
+    agentExecutables: clientTargets.agentExecutables,
     warnings: clientTargets.warnings,
     skills,
     gitcode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msdevflow",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "Install the msdevflow GitCode skill and its runtime dependencies",
   "type": "module",
   "bin": {

package/skill/msd/README.md

@@ -273,6 +273,8 @@ Claude Code + Codex    -> 两套受管副本
 
 每个物理目标都包含一个 `msd` 核心和十个 `msd-<action>` 路由器；业务规则仍只有一份。
 
+WSL 中的安装侧按 Agent 可执行文件实际所在环境决定：Agent 只在 Windows 时允许通过 Windows Node bridge 安装到 Windows 用户环境；Agent 只在 WSL 时必须使用 WSL 内 Linux Node/npm；同名 Agent 同时存在于两侧时停止而不猜测。WSL 原生模式先用 `type -a node npm npx opencode`（以实际选中的 Agent 命令替换 `opencode`） 确认所选命令解析为 Linux 路径，而不是 `/mnt/<drive>/...` 或 `.cmd`。此前失败后可直接按正确模式重跑，受管 runtime 会被复用或修复，无需手动删除。
+
 显式选择客户端、只读预检或自定义目录：
 
 ```bash