@weapp-tailwindcss/hbuilderx-runner 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -47,6 +47,8 @@ The default channel is `auto`. Resolution uses this precedence:
47
47
 
48
48
  The macOS defaults are `/Applications/HBuilderX.app/Contents/MacOS/cli` and `/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli`. Set `HBUILDERX_CLI_PATH` for non-standard Windows/Linux installations.
49
49
 
50
+ `resolveHBuilderXCli` returns an explicitly configured existing path without querying running processes. `resolveHBuilderXCliInfo` also reports `isRunning`, so it still queries the operating system. A configured runner connects through the native CLI host handshake.
51
+
50
52
  If one CLI matches multiple hosts, the runner reports an ambiguity instead of guessing. Set `HBUILDERX_HOST` or pass `host` to `createHBuilderXRunner`.
51
53
 
52
54
  Some HBuilderX releases reject concurrent stable and Alpha processes. The runner never closes an existing instance automatically; it reports `cli-instance-mismatch` when the target edition cannot start, so close the conflicting instance before retrying.
package/README.zh-CN.md CHANGED
@@ -48,6 +48,8 @@ await launch.stop()
48
48
 
49
49
  macOS 默认路径为 `/Applications/HBuilderX.app/Contents/MacOS/cli` 和 `/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli`。Windows/Linux 的非标准安装请设置 `HBUILDERX_CLI_PATH`。
50
50
 
51
+ `resolveHBuilderXCli` 只返回已配置且存在的路径,不查询运行进程;`resolveHBuilderXCliInfo` 还需要返回 `isRunning`,因此保留操作系统查询。已配置路径的 runner 通过原生 CLI 的 host 握手连接实例。
52
+
51
53
  当同一 CLI 匹配到多个 host 时,runner 会拒绝猜测。请设置 `HBUILDERX_HOST`,或向 `createHBuilderXRunner` 传入 `host`。
52
54
 
53
55
  部分 HBuilderX 版本自身会拒绝 stable 与 Alpha 跨版本并行运行。runner 不会擅自关闭当前实例;目标版本无法启动时会抛出 `cli-instance-mismatch`,请关闭冲突实例后重试。
package/dist/index.cjs CHANGED
@@ -27,7 +27,10 @@ let node_path = require("node:path");
27
27
  node_path = __toESM(node_path, 1);
28
28
  let node_process = require("node:process");
29
29
  node_process = __toESM(node_process, 1);
30
+ let node_buffer = require("node:buffer");
30
31
  let node_child_process = require("node:child_process");
32
+ let cross_spawn = require("cross-spawn");
33
+ cross_spawn = __toESM(cross_spawn, 1);
31
34
  //#region src/fs.ts
32
35
  async function fileExists(file) {
33
36
  try {
@@ -44,9 +47,34 @@ function wait(ms) {
44
47
  return new Promise((resolve) => setTimeout(resolve, ms));
45
48
  }
46
49
  //#endregion
47
- //#region src/hbuilderx/discovery.ts
50
+ //#region src/hbuilderx/configured-cli.ts
48
51
  const macOSStableCli = "/Applications/HBuilderX.app/Contents/MacOS/cli";
49
52
  const macOSAlphaCli = "/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli";
53
+ function resolveCandidateSource(candidate, env) {
54
+ if (candidate === env.HBUILDERX_CLI_PATH) return "env";
55
+ if (candidate === "/Applications/HBuilderX.app/Contents/MacOS/cli" || candidate === "/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli") return "default-path";
56
+ return "candidate";
57
+ }
58
+ async function firstExisting$1(items) {
59
+ for (const item of items) if (await fileExists(item)) return item;
60
+ }
61
+ async function resolveConfiguredCli(options) {
62
+ const env = options.env ?? node_process.default.env;
63
+ if (options.candidates) {
64
+ const candidate = await firstExisting$1(options.candidates);
65
+ if (!candidate) throw new Error("未找到显式指定的 HBuilderX CLI candidate。");
66
+ return {
67
+ path: candidate,
68
+ source: resolveCandidateSource(candidate, env)
69
+ };
70
+ }
71
+ if (env.HBUILDERX_CLI_PATH && await fileExists(env.HBUILDERX_CLI_PATH)) return {
72
+ path: env.HBUILDERX_CLI_PATH,
73
+ source: "env"
74
+ };
75
+ }
76
+ //#endregion
77
+ //#region src/hbuilderx/discovery.ts
50
78
  function unique(items) {
51
79
  return [...new Set(items)];
52
80
  }
@@ -92,27 +120,57 @@ function extractHBuilderXExecutableFromProcessOutput(output, platform = node_pro
92
120
  return extractHBuilderXExecutablesFromProcessOutput(output, platform)[0];
93
121
  }
94
122
  async function findRunningHBuilderXCliCandidates(platform = node_process.default.platform) {
95
- const result = platform === "win32" ? (0, node_child_process.spawnSync)("wmic", [
96
- "process",
97
- "where",
98
- "name='HBuilderX.exe'",
99
- "get",
100
- "executablepath",
101
- "/format:csv"
102
- ], {
103
- encoding: "utf8",
104
- windowsHide: true
105
- }) : (0, node_child_process.spawnSync)("ps", [
123
+ const command = platform === "win32" ? "powershell.exe" : "ps";
124
+ const args = platform === "win32" ? [
125
+ "-NoLogo",
126
+ "-NoProfile",
127
+ "-NonInteractive",
128
+ "-Command",
129
+ [
130
+ "$ErrorActionPreference = 'Stop'",
131
+ "[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)",
132
+ `$PSModuleAutoLoadingPreference = 'None'`,
133
+ `[Console]::Error.WriteLine('process-discovery: querying')`,
134
+ `$paths = [System.Collections.Generic.List[string]]::new()`,
135
+ `foreach ($p in [System.Diagnostics.Process]::GetProcessesByName('HBuilderX')) { try { $paths.Add([Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($p.MainModule.FileName))) } finally { $p.Dispose() } }`,
136
+ `[Console]::Error.WriteLine('process-discovery: complete')`,
137
+ `[Console]::WriteLine('WT-HBUILDERX-PROCESSES/1')`,
138
+ `[Console]::WriteLine([string]::Join([Environment]::NewLine, $paths))`,
139
+ `[Console]::WriteLine('END')`
140
+ ].join("; ")
141
+ ] : [
106
142
  "-ax",
107
143
  "-o",
108
144
  "command="
109
- ], { encoding: "utf8" });
110
- if (result.error || result.status !== 0) return [];
111
- const executables = extractHBuilderXExecutablesFromProcessOutput(`${result.stdout ?? ""}${result.stderr ?? ""}`, platform);
145
+ ];
146
+ const result = (0, node_child_process.spawnSync)(command, args, {
147
+ encoding: "utf8",
148
+ stdio: [
149
+ "ignore",
150
+ "pipe",
151
+ "pipe"
152
+ ],
153
+ windowsHide: true,
154
+ timeout: 1e4,
155
+ maxBuffer: 1048576
156
+ });
157
+ if (result.error || result.status !== 0) throw new Error(`HBuilderX 进程探测失败:${command}, exit=${result.status}, signal=${result.signal}, cwd=${node_process.default.cwd()}\n${result.error?.message ?? ""}\n${result.stderr ?? ""}\n${result.stdout ?? ""}`);
158
+ let executables;
159
+ if (platform === "win32") {
160
+ const lines = result.stdout.replace(/^\uFEFF/, "").trim().split(/\r?\n/);
161
+ if (lines.shift() !== "WT-HBUILDERX-PROCESSES/1" || lines.pop() !== "END") throw new Error("HBuilderX Windows 进程探测返回了不完整的路径列表");
162
+ executables = lines.filter(Boolean).map((line) => {
163
+ const bytes = node_buffer.Buffer.from(line, "base64");
164
+ const executable = bytes.toString("utf8");
165
+ if (bytes.toString("base64") !== line || !node_buffer.Buffer.from(executable).equals(bytes) || !node_path.default.win32.isAbsolute(executable) || node_path.default.win32.parse(executable).root.length < 3 || node_path.default.win32.basename(executable).toLowerCase() !== "hbuilderx.exe") throw new Error("HBuilderX Windows 进程探测返回了无效路径列表");
166
+ return executable;
167
+ });
168
+ } else executables = extractHBuilderXExecutablesFromProcessOutput(result.stdout, platform);
169
+ const paths = platform === "win32" ? node_path.default.win32 : node_path.default.posix;
112
170
  const candidates = [];
113
171
  for (const executable of executables) {
114
172
  if (!await fileExists(executable)) continue;
115
- const cli = node_path.default.join(node_path.default.dirname(executable), platform === "win32" ? "cli.exe" : "cli");
173
+ const cli = paths.join(paths.dirname(executable), platform === "win32" ? "cli.exe" : "cli");
116
174
  if (await fileExists(cli)) candidates.push(cli);
117
175
  }
118
176
  return unique(candidates);
@@ -132,11 +190,6 @@ function selectHBuilderXCliCandidatesForChannel(items, channel) {
132
190
  if (channel === "auto") return sortByChannel(items);
133
191
  return items.filter((item) => inferHBuilderXChannel(item) === channel);
134
192
  }
135
- function resolveCandidateSource(candidate, env) {
136
- if (candidate === env.HBUILDERX_CLI_PATH) return "env";
137
- if (candidate === "/Applications/HBuilderX.app/Contents/MacOS/cli" || candidate === "/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli") return "default-path";
138
- return "candidate";
139
- }
140
193
  async function firstExisting(items) {
141
194
  for (const item of items) if (await fileExists(item)) return item;
142
195
  }
@@ -144,21 +197,11 @@ async function resolveHBuilderXCliInfoFromOptions(options = {}) {
144
197
  const env = options.env ?? node_process.default.env;
145
198
  const channel = resolveHBuilderXChannel(options.channel ?? env.HBUILDERX_CHANNEL);
146
199
  const running = await findRunningHBuilderXCliCandidates();
147
- if (options.candidates) {
148
- const candidate = await firstExisting(options.candidates);
149
- if (candidate) return {
150
- path: candidate,
151
- isRunning: running.some((item) => normalizeFile(item) === normalizeFile(candidate)),
152
- source: resolveCandidateSource(candidate, env),
153
- channel: inferHBuilderXChannel(candidate)
154
- };
155
- throw new Error("未找到显式指定的 HBuilderX CLI candidate。");
156
- }
157
- if (env.HBUILDERX_CLI_PATH && await fileExists(env.HBUILDERX_CLI_PATH)) return {
158
- path: env.HBUILDERX_CLI_PATH,
159
- isRunning: running.some((item) => normalizeFile(item) === normalizeFile(env.HBUILDERX_CLI_PATH)),
160
- source: "env",
161
- channel: inferHBuilderXChannel(env.HBUILDERX_CLI_PATH)
200
+ const configured = await resolveConfiguredCli(options);
201
+ if (configured) return {
202
+ ...configured,
203
+ isRunning: running.some((item) => normalizeFile(item) === normalizeFile(configured.path)),
204
+ channel: inferHBuilderXChannel(configured.path)
162
205
  };
163
206
  const runningCandidate = selectHBuilderXCliCandidatesForChannel(running, channel)[0];
164
207
  if (runningCandidate) return {
@@ -223,8 +266,8 @@ function createLogBuffer(maxChunks = 160) {
223
266
  }
224
267
  function collectProcessOutput(child, maxChunks = 160) {
225
268
  const buffer = createLogBuffer(maxChunks);
226
- child.stdout?.on("data", (chunk) => buffer.push(chunk));
227
- child.stderr?.on("data", (chunk) => buffer.push(chunk));
269
+ child.stdout?.setEncoding("utf8").on("data", (chunk) => buffer.push(chunk));
270
+ child.stderr?.setEncoding("utf8").on("data", (chunk) => buffer.push(chunk));
228
271
  return buffer.logs;
229
272
  }
230
273
  function classifyHBuilderXOutput(output) {
@@ -363,10 +406,9 @@ function buildCommandError(prefix, options, exit, logs, timedOut = false) {
363
406
  ].filter(Boolean).join("\n"), result);
364
407
  }
365
408
  function spawnCommand(options) {
366
- const child = (0, node_child_process.spawn)(options.command, options.args, {
409
+ const child = (0, cross_spawn.default)(options.command, options.args, {
367
410
  cwd: options.cwd,
368
411
  detached: options.detached ?? node_process.default.platform !== "win32",
369
- shell: node_process.default.platform === "win32",
370
412
  stdio: options.stdio === "inherit" ? "inherit" : [
371
413
  "ignore",
372
414
  "pipe",
@@ -379,6 +421,7 @@ function spawnCommand(options) {
379
421
  }
380
422
  });
381
423
  const logs = options.stdio === "inherit" ? [] : collectProcessOutput(child);
424
+ child.on("error", (error) => logs.push(`${error.message}\n`));
382
425
  let exit;
383
426
  const closed = new Promise((resolve) => {
384
427
  child.on("close", (code, signal) => {
@@ -452,11 +495,8 @@ function createProcessExitTracker(child) {
452
495
  };
453
496
  }
454
497
  //#endregion
455
- //#region src/hbuilderx/runner.ts
498
+ //#region src/hbuilderx/hosts.ts
456
499
  const ansiRE = new RegExp(`${String.fromCharCode(27)}\\[[\\d;]*m`, "g");
457
- const defaultStartupTimeoutMs = 6e4;
458
- const hostPollIntervalMs = 500;
459
- const maxSessionLogChunks = 160;
460
500
  function stripAnsi(value) {
461
501
  return value.replace(ansiRE, "");
462
502
  }
@@ -469,18 +509,6 @@ function parseHBuilderXVersion(output) {
469
509
  function inferHBuilderXChannelFromVersion(version) {
470
510
  return /(?:^|-)alpha(?:\.|$)/i.test(version) ? "alpha" : "stable";
471
511
  }
472
- function createHBuilderXNativeLaunchArgs(options) {
473
- const args = [
474
- "launch",
475
- options.platform,
476
- "--project",
477
- node_path.default.resolve(options.cwd),
478
- ...options.args ?? []
479
- ];
480
- if (options.compile != null && !args.includes("--compile")) args.push("--compile", String(options.compile));
481
- if (options.runtimeLog != null && !args.includes("--runtime-log")) args.push("--runtime-log", String(options.runtimeLog));
482
- return args;
483
- }
484
512
  function createRunnerError(cliPath, cwd, args, kind, message, hint, logs) {
485
513
  const output = formatRecentLogs(logs);
486
514
  return new HBuilderXCommandError([
@@ -506,55 +534,55 @@ function createRunnerError(cliPath, cwd, args, kind, message, hint, logs) {
506
534
  }
507
535
  });
508
536
  }
509
- function bindHost(args, host) {
510
- const hostIndex = args.indexOf("--host");
511
- if (hostIndex < 0) return [
512
- ...args,
513
- "--host",
514
- host
515
- ];
516
- if (args[hostIndex + 1] !== host) throw new Error(`runner 已绑定 HBuilderX host=${host},不能改为 ${args[hostIndex + 1] ?? "空值"}。`);
517
- return args;
518
- }
519
- function appendLogs(target, source) {
520
- target.push(...source);
521
- if (target.length > maxSessionLogChunks) target.splice(0, target.length - maxSessionLogChunks);
522
- }
523
- async function listCompatibleHosts(cliPath, cwd, env, expectedChannel, explicitHost, timeoutMs) {
524
- const startedAt = Date.now();
537
+ async function connectHBuilderXHost(options) {
538
+ const { cliPath, cwd, env, expectedChannel, explicitHost } = options;
539
+ const deadline = Date.now() + options.timeoutMs;
525
540
  const logs = [];
526
- do {
527
- const listed = await runCommand({
541
+ const timeoutError = (args) => new HBuilderXCommandError(`HBuilderX host 连接超时:${cliPath} ${args.join(" ")}\ncwd=${cwd}\nexit=null\nissue=timeout\n${formatRecentLogs(logs)}`, {
542
+ command: cliPath,
543
+ args,
544
+ cwd,
545
+ exit: {
546
+ code: null,
547
+ signal: null
548
+ },
549
+ logs,
550
+ output: formatRecentLogs(logs),
551
+ issue: createTimeoutIssue()
552
+ });
553
+ const command = async (args, maxTimeoutMs = 1e4) => {
554
+ const remaining = deadline - Date.now();
555
+ if (remaining <= 0) throw timeoutError(args);
556
+ const result = await runCommand({
528
557
  command: cliPath,
529
- args: ["listhost"],
558
+ args,
530
559
  cwd,
531
560
  env,
532
- timeoutMs: Math.min(timeoutMs, 1e4),
561
+ timeoutMs: Math.min(remaining, maxTimeoutMs),
533
562
  allowFailure: true
534
563
  });
535
- appendLogs(logs, listed.logs);
536
- const hosts = explicitHost ? [explicitHost] : parseHBuilderXHosts(listed.output);
564
+ logs.push(...result.logs);
565
+ if (logs.length > 160) logs.splice(0, logs.length - 160);
566
+ return result;
567
+ };
568
+ const assertCommand = (result) => {
569
+ if (result.issue.kind === "cli-instance-mismatch" || result.issue.kind === "cli-host-ambiguous") throw createRunnerError(cliPath, cwd, result.args, result.issue.kind, result.issue.message, result.issue.hint ?? "请检查目标 HBuilderX host。", logs);
570
+ if (result.exit.code !== 0) throw new HBuilderXCommandError(`HBuilderX host 命令失败:${cliPath} ${result.args.join(" ")}\ncwd=${cwd}\nexit=${result.exit.signal ?? result.exit.code}\nissue=${result.issue.kind}\n${formatRecentLogs(logs)}`, result);
571
+ };
572
+ const probe = async () => {
573
+ const listed = await command(["listhost"]);
574
+ if (!(listed.issue.kind !== "timeout" && /HBuilderX is not detected running\. Please execute cli open/i.test(stripAnsi(listed.output)))) assertCommand(listed);
575
+ const hosts = parseHBuilderXHosts(listed.output);
537
576
  const compatible = [];
538
- for (const host of hosts) {
539
- const versionResult = await runCommand({
540
- command: cliPath,
541
- args: [
542
- "version",
543
- "--host",
544
- host
545
- ],
546
- cwd,
547
- env,
548
- timeoutMs: Math.min(timeoutMs, 1e4),
549
- allowFailure: true
550
- });
551
- appendLogs(logs, versionResult.logs);
552
- if (versionResult.issue.kind === "cli-instance-mismatch") return {
553
- compatible: [],
554
- logs
555
- };
556
- const version = versionResult.exit.code === 0 ? parseHBuilderXVersion(versionResult.output) : void 0;
557
- if (!version) continue;
577
+ for (const host of explicitHost ? [explicitHost] : hosts) {
578
+ const result = await command([
579
+ "version",
580
+ "--host",
581
+ host
582
+ ]);
583
+ assertCommand(result);
584
+ const version = parseHBuilderXVersion(result.output);
585
+ if (!version) throw createRunnerError(cliPath, cwd, result.args, "cli-instance-mismatch", `无法验证 HBuilderX host=${host} 的版本`, "请检查目标实例是否就绪。", logs);
558
586
  const channel = inferHBuilderXChannelFromVersion(version);
559
587
  if (expectedChannel === "unknown" || channel === expectedChannel) compatible.push({
560
588
  host,
@@ -562,16 +590,44 @@ async function listCompatibleHosts(cliPath, cwd, env, expectedChannel, explicitH
562
590
  channel
563
591
  });
564
592
  }
565
- if (compatible.length > 0) return {
566
- compatible,
567
- logs
568
- };
569
- await wait(hostPollIntervalMs);
570
- } while (Date.now() - startedAt < timeoutMs);
571
- return {
572
- compatible: [],
573
- logs
593
+ if (compatible.length > 1) throw createRunnerError(cliPath, cwd, ["listhost"], "cli-host-ambiguous", `检测到多个匹配的 HBuilderX host:${compatible.map((item) => item.host).join(", ")}`, "请设置 HBUILDERX_HOST,或显式传入 host。", logs);
594
+ if (!compatible.length && (hosts.length || explicitHost)) throw createRunnerError(cliPath, cwd, ["listhost"], "cli-instance-mismatch", `未找到与 ${expectedChannel} CLI 匹配的 HBuilderX host`, "请检查 HBUILDERX_CLI_PATH、HBUILDERX_CHANNEL 和 HBUILDERX_HOST。", logs);
595
+ return compatible[0];
574
596
  };
597
+ const existing = await probe();
598
+ if (existing) return existing;
599
+ assertCommand(await command(["open"], options.timeoutMs));
600
+ do {
601
+ const selected = await probe();
602
+ if (selected) return selected;
603
+ await wait(Math.min(500, Math.max(0, deadline - Date.now())));
604
+ } while (Date.now() < deadline);
605
+ throw timeoutError(["listhost"]);
606
+ }
607
+ //#endregion
608
+ //#region src/hbuilderx/runner.ts
609
+ const defaultStartupTimeoutMs = 6e4;
610
+ function createHBuilderXNativeLaunchArgs(options) {
611
+ const args = [
612
+ "launch",
613
+ options.platform,
614
+ "--project",
615
+ node_path.default.resolve(options.cwd),
616
+ ...options.args ?? []
617
+ ];
618
+ if (options.compile != null && !args.includes("--compile")) args.push("--compile", String(options.compile));
619
+ if (options.runtimeLog != null && !args.includes("--runtime-log")) args.push("--runtime-log", String(options.runtimeLog));
620
+ return args;
621
+ }
622
+ function bindHost(args, host) {
623
+ const hostIndex = args.indexOf("--host");
624
+ if (hostIndex < 0) return [
625
+ ...args,
626
+ "--host",
627
+ host
628
+ ];
629
+ if (args[hostIndex + 1] !== host) throw new Error(`runner 已绑定 HBuilderX host=${host},不能改为 ${args[hostIndex + 1] ?? "空值"}。`);
630
+ return args;
575
631
  }
576
632
  async function createHBuilderXRunner(options = {}) {
577
633
  const env = {
@@ -580,35 +636,32 @@ async function createHBuilderXRunner(options = {}) {
580
636
  };
581
637
  const cwd = options.cwd ?? node_process.default.cwd();
582
638
  const timeoutMs = options.timeoutMs ?? defaultStartupTimeoutMs;
583
- const resolution = await resolveHBuilderXCliInfoFromOptions({
639
+ const resolveOptions = {
584
640
  candidates: options.hbuilderxCliPath ? [options.hbuilderxCliPath] : options.candidates,
585
641
  channel: options.channel,
586
642
  env,
587
643
  host: options.host
588
- });
644
+ };
645
+ const configured = await resolveConfiguredCli(resolveOptions);
646
+ const resolution = configured ? {
647
+ ...configured,
648
+ channel: inferHBuilderXChannel(configured.path)
649
+ } : await resolveHBuilderXCliInfoFromOptions(resolveOptions);
589
650
  const cliEnv = {
590
651
  ...env,
591
652
  HBUILDERX_CLI_PATH: resolution.path
592
653
  };
593
- if (!resolution.isRunning) {
594
- const opened = await runCommand({
595
- command: resolution.path,
596
- args: ["open"],
597
- cwd,
598
- env: cliEnv,
599
- timeoutMs,
600
- allowFailure: true
601
- });
602
- const openIssue = classifyHBuilderXOutput(opened.output);
603
- if (opened.exit.code !== 0 || openIssue.kind === "cli-instance-mismatch" || openIssue.kind === "cli-host-ambiguous") throw createRunnerError(resolution.path, cwd, ["open"], openIssue.kind === "cli-host-ambiguous" ? "cli-host-ambiguous" : "cli-instance-mismatch", openIssue.message, openIssue.hint ?? "请检查目标 HBuilderX 运行实例。", opened.logs);
604
- }
605
654
  const requestedChannel = resolveHBuilderXChannel(options.channel ?? env.HBUILDERX_CHANNEL);
606
655
  const expectedChannel = resolution.channel !== "unknown" ? resolution.channel : requestedChannel === "auto" ? inferHBuilderXChannel(resolution.path) : requestedChannel;
607
656
  const explicitHost = options.host ?? env.HBUILDERX_HOST;
608
- const { compatible, logs } = await listCompatibleHosts(resolution.path, cwd, cliEnv, expectedChannel, explicitHost, timeoutMs);
609
- if (compatible.length === 0) throw createRunnerError(resolution.path, cwd, ["listhost"], "cli-instance-mismatch", `未找到与 ${expectedChannel} CLI 匹配的 HBuilderX host`, "请启动对应版本,或检查 HBUILDERX_CLI_PATH、HBUILDERX_CHANNEL 和 HBUILDERX_HOST。", logs);
610
- if (compatible.length > 1) throw createRunnerError(resolution.path, cwd, ["listhost"], "cli-host-ambiguous", `检测到多个匹配的 HBuilderX host:${compatible.map((item) => item.host).join(", ")}`, "请设置 HBUILDERX_HOST,或在 createHBuilderXRunner options 中显式传入 host。", logs);
611
- const selected = compatible[0];
657
+ const selected = await connectHBuilderXHost({
658
+ cliPath: resolution.path,
659
+ cwd,
660
+ env: cliEnv,
661
+ expectedChannel,
662
+ explicitHost,
663
+ timeoutMs
664
+ });
612
665
  const boundResolution = {
613
666
  ...resolution,
614
667
  isRunning: true,
@@ -694,7 +747,9 @@ async function resolveHBuilderXCliInfo(candidatesOrOptions, env = node_process.d
694
747
  } : candidatesOrOptions);
695
748
  }
696
749
  async function resolveHBuilderXCli(candidatesOrOptions) {
697
- return (await resolveHBuilderXCliInfo(candidatesOrOptions)).path;
750
+ const options = Array.isArray(candidatesOrOptions) ? { candidates: candidatesOrOptions } : candidatesOrOptions ?? {};
751
+ resolveHBuilderXChannel(options.channel ?? (options.env ?? node_process.default.env).HBUILDERX_CHANNEL);
752
+ return (await resolveConfiguredCli(options))?.path ?? (await resolveHBuilderXCliInfoFromOptions(options)).path;
698
753
  }
699
754
  function createHBuilderXEnv(options = {}) {
700
755
  return {
package/dist/index.d.ts CHANGED
@@ -1,27 +1,27 @@
1
1
  import { ChildProcess } from "node:child_process";
2
2
  import { Buffer } from "node:buffer";
3
3
  //#region src/fs.d.ts
4
- declare function fileExists(file: string): Promise<boolean>;
5
- declare function readUtf8(file: string): Promise<string>;
6
- declare function wait(ms: number): Promise<unknown>;
4
+ export declare function fileExists(file: string): Promise<boolean>;
5
+ export declare function readUtf8(file: string): Promise<string>;
6
+ export declare function wait(ms: number): Promise<unknown>;
7
7
  //#endregion
8
8
  //#region src/types.d.ts
9
- type HBuilderXMiniProgramPlatform = 'mp-weixin' | 'mp-alipay' | 'mp-baidu' | 'mp-toutiao';
10
- type HBuilderXAppPlatform = 'app-android' | 'app-ios' | 'app-harmony';
11
- type HBuilderXPlatform = HBuilderXMiniProgramPlatform | HBuilderXAppPlatform;
12
- type HBuilderXChannel = 'auto' | 'stable' | 'alpha';
13
- type HBuilderXResolvedChannel = Exclude<HBuilderXChannel, 'auto'> | 'unknown';
14
- type HBuilderXIssueKind = 'cli-not-found' | 'cli-instance-mismatch' | 'cli-host-ambiguous' | 'project-not-uni-app' | 'project-type-unsupported' | 'config-load-failed' | 'android-toolchain-missing' | 'ios-toolchain-missing' | 'harmony-toolchain-missing' | 'harmony-build-failed' | 'timeout' | 'process-exit' | 'unknown';
15
- interface HBuilderXIssue {
9
+ export type HBuilderXMiniProgramPlatform = 'mp-weixin' | 'mp-alipay' | 'mp-baidu' | 'mp-toutiao';
10
+ export type HBuilderXAppPlatform = 'app-android' | 'app-ios' | 'app-harmony';
11
+ export type HBuilderXPlatform = HBuilderXMiniProgramPlatform | HBuilderXAppPlatform;
12
+ export type HBuilderXChannel = 'auto' | 'stable' | 'alpha';
13
+ export type HBuilderXResolvedChannel = Exclude<HBuilderXChannel, 'auto'> | 'unknown';
14
+ export type HBuilderXIssueKind = 'cli-not-found' | 'cli-instance-mismatch' | 'cli-host-ambiguous' | 'project-not-uni-app' | 'project-type-unsupported' | 'config-load-failed' | 'android-toolchain-missing' | 'ios-toolchain-missing' | 'harmony-toolchain-missing' | 'harmony-build-failed' | 'timeout' | 'process-exit' | 'unknown';
15
+ export interface HBuilderXIssue {
16
16
  kind: HBuilderXIssueKind;
17
17
  message: string;
18
18
  hint?: string;
19
19
  }
20
- interface CommandExit {
20
+ export interface CommandExit {
21
21
  code: number | null;
22
22
  signal: NodeJS.Signals | null;
23
23
  }
24
- interface HBuilderXCommandOptions {
24
+ export interface HBuilderXCommandOptions {
25
25
  command: string;
26
26
  args: string[];
27
27
  cwd: string;
@@ -31,7 +31,7 @@ interface HBuilderXCommandOptions {
31
31
  detached?: boolean;
32
32
  stdio?: 'pipe' | 'inherit';
33
33
  }
34
- interface HBuilderXCommandResult {
34
+ export interface HBuilderXCommandResult {
35
35
  command: string;
36
36
  args: string[];
37
37
  cwd: string;
@@ -40,7 +40,7 @@ interface HBuilderXCommandResult {
40
40
  output: string;
41
41
  issue: HBuilderXIssue;
42
42
  }
43
- interface SpawnedHBuilderXCommand {
43
+ export interface SpawnedHBuilderXCommand {
44
44
  child: ChildProcess;
45
45
  logs: string[];
46
46
  command: string;
@@ -50,7 +50,7 @@ interface SpawnedHBuilderXCommand {
50
50
  closed: Promise<CommandExit>;
51
51
  ensureRunning: () => void;
52
52
  }
53
- interface HBuilderXProjectOptions {
53
+ export interface HBuilderXProjectOptions {
54
54
  cwd: string;
55
55
  hbuilderxCliPath?: string;
56
56
  channel?: HBuilderXChannel;
@@ -59,31 +59,31 @@ interface HBuilderXProjectOptions {
59
59
  timeoutMs?: number;
60
60
  allowFailure?: boolean;
61
61
  }
62
- interface HBuilderXLaunchOptions extends HBuilderXProjectOptions {
62
+ export interface HBuilderXLaunchOptions extends HBuilderXProjectOptions {
63
63
  platform: HBuilderXPlatform;
64
64
  args?: string[];
65
65
  compile?: boolean;
66
66
  runtimeLog?: boolean;
67
67
  }
68
- interface ToolResult {
68
+ export interface ToolResult {
69
69
  ok: boolean;
70
70
  output: string;
71
71
  status: number | null;
72
72
  signal: NodeJS.Signals | null;
73
73
  }
74
- interface AndroidToolchain {
74
+ export interface AndroidToolchain {
75
75
  command: string;
76
76
  output: string;
77
77
  env: Record<string, string> | undefined;
78
78
  }
79
- type HBuilderXCliResolutionSource = 'running-process' | 'env' | 'default-path' | 'candidate';
80
- interface HBuilderXCliResolveOptions {
79
+ export type HBuilderXCliResolutionSource = 'running-process' | 'env' | 'default-path' | 'candidate';
80
+ export interface HBuilderXCliResolveOptions {
81
81
  candidates?: string[];
82
82
  channel?: HBuilderXChannel;
83
83
  env?: NodeJS.ProcessEnv;
84
84
  host?: string;
85
85
  }
86
- interface HBuilderXCliResolution {
86
+ export interface HBuilderXCliResolution {
87
87
  path: string;
88
88
  isRunning: boolean;
89
89
  source: HBuilderXCliResolutionSource;
@@ -91,7 +91,7 @@ interface HBuilderXCliResolution {
91
91
  host?: string;
92
92
  version?: string;
93
93
  }
94
- interface HBuilderXNativeCommandOptions {
94
+ export interface HBuilderXNativeCommandOptions {
95
95
  args: string[];
96
96
  cwd?: string;
97
97
  timeoutMs?: number;
@@ -100,12 +100,12 @@ interface HBuilderXNativeCommandOptions {
100
100
  detached?: boolean;
101
101
  stdio?: 'pipe' | 'inherit';
102
102
  }
103
- interface HBuilderXRunnerOptions extends HBuilderXCliResolveOptions {
103
+ export interface HBuilderXRunnerOptions extends HBuilderXCliResolveOptions {
104
104
  cwd?: string;
105
105
  hbuilderxCliPath?: string;
106
106
  timeoutMs?: number;
107
107
  }
108
- interface HBuilderXRunner {
108
+ export interface HBuilderXRunner {
109
109
  resolution: HBuilderXCliResolution;
110
110
  run: (options: HBuilderXNativeCommandOptions) => Promise<HBuilderXCommandResult>;
111
111
  spawn: (options: HBuilderXNativeCommandOptions) => SpawnedHBuilderXCommand;
@@ -116,100 +116,103 @@ interface HBuilderXRunner {
116
116
  startLaunch: (options: HBuilderXLaunchOptions) => SpawnedHBuilderXCommand;
117
117
  }
118
118
  //#endregion
119
+ //#region src/hbuilderx/configured-cli.d.ts
120
+ export declare const macOSStableCli = "/Applications/HBuilderX.app/Contents/MacOS/cli";
121
+ export declare const macOSAlphaCli = "/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli";
122
+ //#endregion
119
123
  //#region src/hbuilderx/discovery.d.ts
120
- declare const macOSStableCli = "/Applications/HBuilderX.app/Contents/MacOS/cli";
121
- declare const macOSAlphaCli = "/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli";
122
- declare function resolveHBuilderXChannel(channel?: string): HBuilderXChannel;
123
- declare function inferHBuilderXChannel(file: string): HBuilderXResolvedChannel;
124
- declare function getDefaultHBuilderXCliCandidates(env?: NodeJS.ProcessEnv, channel?: HBuilderXChannel, platform?: NodeJS.Platform): string[];
125
- declare function extractHBuilderXMacOSExecutables(output: string): string[];
126
- declare function extractHBuilderXWindowsExecutables(output: string): string[];
127
- declare function extractHBuilderXExecutablesFromProcessOutput(output: string, platform?: NodeJS.Platform): string[];
128
- declare function extractHBuilderXMacOSExecutable(line: string): string | undefined;
129
- declare function extractHBuilderXWindowsExecutable(line: string): string | undefined;
130
- declare function extractHBuilderXExecutableFromProcessOutput(output: string, platform?: NodeJS.Platform): string | undefined;
131
- declare function findRunningHBuilderXCliCandidates(platform?: NodeJS.Platform): Promise<string[]>;
132
- declare function findRunningHBuilderXCli(platform?: NodeJS.Platform): Promise<string | undefined>;
133
- declare function selectHBuilderXCliCandidatesForChannel(items: string[], channel: HBuilderXChannel): string[];
134
- declare function resolveHBuilderXCliInfoFromOptions(options?: HBuilderXCliResolveOptions): Promise<HBuilderXCliResolution>;
124
+ export declare function resolveHBuilderXChannel(channel?: string): HBuilderXChannel;
125
+ export declare function inferHBuilderXChannel(file: string): HBuilderXResolvedChannel;
126
+ export declare function getDefaultHBuilderXCliCandidates(env?: NodeJS.ProcessEnv, channel?: HBuilderXChannel, platform?: NodeJS.Platform): string[];
127
+ export declare function extractHBuilderXMacOSExecutables(output: string): string[];
128
+ export declare function extractHBuilderXWindowsExecutables(output: string): string[];
129
+ export declare function extractHBuilderXExecutablesFromProcessOutput(output: string, platform?: NodeJS.Platform): string[];
130
+ export declare function extractHBuilderXMacOSExecutable(line: string): string | undefined;
131
+ export declare function extractHBuilderXWindowsExecutable(line: string): string | undefined;
132
+ export declare function extractHBuilderXExecutableFromProcessOutput(output: string, platform?: NodeJS.Platform): string | undefined;
133
+ export declare function findRunningHBuilderXCliCandidates(platform?: NodeJS.Platform): Promise<string[]>;
134
+ export declare function findRunningHBuilderXCli(platform?: NodeJS.Platform): Promise<string | undefined>;
135
+ export declare function selectHBuilderXCliCandidatesForChannel(items: string[], channel: HBuilderXChannel): string[];
136
+ export declare function resolveHBuilderXCliInfoFromOptions(options?: HBuilderXCliResolveOptions): Promise<HBuilderXCliResolution>;
137
+ //#endregion
138
+ //#region src/process.d.ts
139
+ export declare class HBuilderXCommandError extends Error {
140
+ readonly result: HBuilderXCommandResult;
141
+ constructor(message: string, result: HBuilderXCommandResult);
142
+ }
143
+ export declare function killProcessTree(child: ChildProcess, signal?: NodeJS.Signals): void;
144
+ export declare function spawnCommand(options: HBuilderXCommandOptions): SpawnedHBuilderXCommand;
145
+ export declare function runCommand(options: HBuilderXCommandOptions): Promise<HBuilderXCommandResult>;
146
+ export declare function createProcessExitTracker(child: ChildProcess): {
147
+ closed: Promise<CommandExit>;
148
+ ensureRunning(logs: string[]): void;
149
+ };
150
+ //#endregion
151
+ //#region src/hbuilderx/hosts.d.ts
152
+ export declare function stripAnsi(value: string): string;
153
+ export declare function parseHBuilderXHosts(output: string): string[];
154
+ export declare function parseHBuilderXVersion(output: string): string | undefined;
155
+ export declare function inferHBuilderXChannelFromVersion(version: string): HBuilderXResolvedChannel;
135
156
  //#endregion
136
157
  //#region src/hbuilderx/runner.d.ts
137
- declare function stripAnsi(value: string): string;
138
- declare function parseHBuilderXHosts(output: string): string[];
139
- declare function parseHBuilderXVersion(output: string): string | undefined;
140
- declare function inferHBuilderXChannelFromVersion(version: string): HBuilderXResolvedChannel;
141
- declare function createHBuilderXNativeLaunchArgs(options: HBuilderXLaunchOptions): string[];
142
- declare function createHBuilderXRunner(options?: HBuilderXRunnerOptions): Promise<HBuilderXRunner>;
158
+ export declare function createHBuilderXNativeLaunchArgs(options: HBuilderXLaunchOptions): string[];
159
+ export declare function createHBuilderXRunner(options?: HBuilderXRunnerOptions): Promise<HBuilderXRunner>;
143
160
  //#endregion
144
161
  //#region src/hbuilderx.d.ts
145
- declare function resolveHBuilderXCliInfo(options?: HBuilderXCliResolveOptions): ReturnType<typeof resolveHBuilderXCliInfoFromOptions>;
146
- declare function resolveHBuilderXCliInfo(candidates?: string[], env?: NodeJS.ProcessEnv): ReturnType<typeof resolveHBuilderXCliInfoFromOptions>;
147
- declare function resolveHBuilderXCli(options?: HBuilderXCliResolveOptions): Promise<string>;
148
- declare function resolveHBuilderXCli(candidates?: string[]): Promise<string>;
149
- declare function createHBuilderXEnv(options?: {
162
+ export declare function resolveHBuilderXCliInfo(options?: HBuilderXCliResolveOptions): ReturnType<typeof resolveHBuilderXCliInfoFromOptions>;
163
+ export declare function resolveHBuilderXCliInfo(candidates?: string[], env?: NodeJS.ProcessEnv): ReturnType<typeof resolveHBuilderXCliInfoFromOptions>;
164
+ export declare function resolveHBuilderXCli(options?: HBuilderXCliResolveOptions): Promise<string>;
165
+ export declare function resolveHBuilderXCli(candidates?: string[]): Promise<string>;
166
+ export declare function createHBuilderXEnv(options?: {
150
167
  hbuilderxCliPath?: string;
151
168
  env?: Record<string, string | undefined>;
152
169
  }): {
153
170
  HBUILDERX_CLI_PATH: string | undefined;
154
171
  NODE_OPTIONS: string;
155
172
  };
156
- declare function hbuilderxPnpmArgs(args: string[]): string[];
157
- declare function runPnpmCommand(options: HBuilderXProjectOptions & {
173
+ export declare function hbuilderxPnpmArgs(args: string[]): string[];
174
+ export declare function runPnpmCommand(options: HBuilderXProjectOptions & {
158
175
  args: string[];
159
176
  }): Promise<HBuilderXCommandResult>;
160
- declare function spawnPnpmCommand(options: HBuilderXProjectOptions & {
177
+ export declare function spawnPnpmCommand(options: HBuilderXProjectOptions & {
161
178
  args: string[];
162
179
  }): SpawnedHBuilderXCommand;
163
- declare function closeProject(options: HBuilderXProjectOptions): Promise<HBuilderXCommandResult>;
164
- declare function openProject(options: HBuilderXProjectOptions): Promise<HBuilderXCommandResult>;
165
- declare function prepareProject(options: HBuilderXProjectOptions): Promise<HBuilderXCommandResult>;
166
- declare function createLaunchArgs(options: HBuilderXLaunchOptions): string[];
167
- declare function launchProject(options: HBuilderXLaunchOptions): Promise<HBuilderXCommandResult>;
180
+ export declare function closeProject(options: HBuilderXProjectOptions): Promise<HBuilderXCommandResult>;
181
+ export declare function openProject(options: HBuilderXProjectOptions): Promise<HBuilderXCommandResult>;
182
+ export declare function prepareProject(options: HBuilderXProjectOptions): Promise<HBuilderXCommandResult>;
183
+ export declare function createLaunchArgs(options: HBuilderXLaunchOptions): string[];
184
+ export declare function launchProject(options: HBuilderXLaunchOptions): Promise<HBuilderXCommandResult>;
168
185
  /**
169
186
  * @deprecated 需要固定 stable/alpha 与 host 时,请使用 `createHBuilderXRunner().startLaunch()`。
170
187
  */
171
- declare function startLaunch(options: HBuilderXLaunchOptions): SpawnedHBuilderXCommand;
188
+ export declare function startLaunch(options: HBuilderXLaunchOptions): SpawnedHBuilderXCommand;
172
189
  //#endregion
173
190
  //#region src/logs.d.ts
174
- declare function createLogBuffer(maxChunks?: number): {
191
+ export declare function createLogBuffer(maxChunks?: number): {
175
192
  logs: string[];
176
193
  push(chunk: Buffer | string): void;
177
194
  text(): string;
178
195
  };
179
- declare function collectProcessOutput(child: ChildProcess, maxChunks?: number): string[];
180
- declare function classifyHBuilderXOutput(output: string): HBuilderXIssue;
181
- declare function createTimeoutIssue(): HBuilderXIssue;
182
- declare function formatRecentLogs(logs: string[], maxLength?: number): string;
183
- //#endregion
184
- //#region src/process.d.ts
185
- declare class HBuilderXCommandError extends Error {
186
- readonly result: HBuilderXCommandResult;
187
- constructor(message: string, result: HBuilderXCommandResult);
188
- }
189
- declare function killProcessTree(child: ChildProcess, signal?: NodeJS.Signals): void;
190
- declare function spawnCommand(options: HBuilderXCommandOptions): SpawnedHBuilderXCommand;
191
- declare function runCommand(options: HBuilderXCommandOptions): Promise<HBuilderXCommandResult>;
192
- declare function createProcessExitTracker(child: ChildProcess): {
193
- closed: Promise<CommandExit>;
194
- ensureRunning(logs: string[]): void;
195
- };
196
+ export declare function collectProcessOutput(child: ChildProcess, maxChunks?: number): string[];
197
+ export declare function classifyHBuilderXOutput(output: string): HBuilderXIssue;
198
+ export declare function createTimeoutIssue(): HBuilderXIssue;
199
+ export declare function formatRecentLogs(logs: string[], maxLength?: number): string;
196
200
  //#endregion
197
201
  //#region src/toolchains.d.ts
198
- declare function runTool(command: string, args: string[]): ToolResult;
199
- declare function resolveAdbCommand(env?: NodeJS.ProcessEnv): AndroidToolchain;
200
- declare function assertAndroidToolchain(env?: NodeJS.ProcessEnv): Record<string, string> | undefined;
201
- declare function assertIosSimulatorToolchain(env?: NodeJS.ProcessEnv): void;
202
- interface IosSimulatorDevice {
202
+ export declare function runTool(command: string, args: string[]): ToolResult;
203
+ export declare function resolveAdbCommand(env?: NodeJS.ProcessEnv): AndroidToolchain;
204
+ export declare function assertAndroidToolchain(env?: NodeJS.ProcessEnv): Record<string, string> | undefined;
205
+ export declare function assertIosSimulatorToolchain(env?: NodeJS.ProcessEnv): void;
206
+ export interface IosSimulatorDevice {
203
207
  lastBootedAt?: string;
204
208
  name: string;
205
209
  state: string;
206
210
  udid: string;
207
211
  }
208
- declare function parseIosSimulatorDevices(output: string): IosSimulatorDevice[];
209
- declare function selectPreferredIosSimulatorDevice(devices: IosSimulatorDevice[]): IosSimulatorDevice | undefined;
210
- declare function resolveIosSimulatorDeviceId(env?: NodeJS.ProcessEnv): string;
211
- declare function resolveHdcCommand(env?: NodeJS.ProcessEnv): string;
212
- declare function parseHdcTargets(output: string): string[];
213
- declare function assertHarmonyToolchain(env?: NodeJS.ProcessEnv, deviceId?: string): string;
214
- //#endregion
215
- export { AndroidToolchain, CommandExit, HBuilderXAppPlatform, HBuilderXChannel, HBuilderXCliResolution, HBuilderXCliResolutionSource, HBuilderXCliResolveOptions, HBuilderXCommandError, HBuilderXCommandOptions, HBuilderXCommandResult, HBuilderXIssue, HBuilderXIssueKind, HBuilderXLaunchOptions, HBuilderXMiniProgramPlatform, HBuilderXNativeCommandOptions, HBuilderXPlatform, HBuilderXProjectOptions, HBuilderXResolvedChannel, HBuilderXRunner, HBuilderXRunnerOptions, IosSimulatorDevice, SpawnedHBuilderXCommand, ToolResult, assertAndroidToolchain, assertHarmonyToolchain, assertIosSimulatorToolchain, classifyHBuilderXOutput, closeProject, collectProcessOutput, createHBuilderXEnv, createHBuilderXNativeLaunchArgs, createHBuilderXRunner, createLaunchArgs, createLogBuffer, createProcessExitTracker, createTimeoutIssue, extractHBuilderXExecutableFromProcessOutput, extractHBuilderXExecutablesFromProcessOutput, extractHBuilderXMacOSExecutable, extractHBuilderXMacOSExecutables, extractHBuilderXWindowsExecutable, extractHBuilderXWindowsExecutables, fileExists, findRunningHBuilderXCli, findRunningHBuilderXCliCandidates, formatRecentLogs, getDefaultHBuilderXCliCandidates, hbuilderxPnpmArgs, inferHBuilderXChannel, inferHBuilderXChannelFromVersion, killProcessTree, launchProject, macOSAlphaCli, macOSStableCli, openProject, parseHBuilderXHosts, parseHBuilderXVersion, parseHdcTargets, parseIosSimulatorDevices, prepareProject, readUtf8, resolveAdbCommand, resolveHBuilderXChannel, resolveHBuilderXCli, resolveHBuilderXCliInfo, resolveHBuilderXCliInfoFromOptions, resolveHdcCommand, resolveIosSimulatorDeviceId, runCommand, runPnpmCommand, runTool, selectHBuilderXCliCandidatesForChannel, selectPreferredIosSimulatorDevice, spawnCommand, spawnPnpmCommand, startLaunch, stripAnsi, wait };
212
+ export declare function parseIosSimulatorDevices(output: string): IosSimulatorDevice[];
213
+ export declare function selectPreferredIosSimulatorDevice(devices: IosSimulatorDevice[]): IosSimulatorDevice | undefined;
214
+ export declare function resolveIosSimulatorDeviceId(env?: NodeJS.ProcessEnv): string;
215
+ export declare function resolveHdcCommand(env?: NodeJS.ProcessEnv): string;
216
+ export declare function parseHdcTargets(output: string): string[];
217
+ export declare function assertHarmonyToolchain(env?: NodeJS.ProcessEnv, deviceId?: string): string;
218
+ //#endregion
package/dist/index.mjs CHANGED
@@ -1,7 +1,9 @@
1
1
  import fs from "node:fs/promises";
2
2
  import path from "node:path";
3
3
  import process from "node:process";
4
- import { spawn, spawnSync } from "node:child_process";
4
+ import { Buffer } from "node:buffer";
5
+ import { spawnSync } from "node:child_process";
6
+ import spawn from "cross-spawn";
5
7
  //#region src/fs.ts
6
8
  async function fileExists(file) {
7
9
  try {
@@ -18,9 +20,34 @@ function wait(ms) {
18
20
  return new Promise((resolve) => setTimeout(resolve, ms));
19
21
  }
20
22
  //#endregion
21
- //#region src/hbuilderx/discovery.ts
23
+ //#region src/hbuilderx/configured-cli.ts
22
24
  const macOSStableCli = "/Applications/HBuilderX.app/Contents/MacOS/cli";
23
25
  const macOSAlphaCli = "/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli";
26
+ function resolveCandidateSource(candidate, env) {
27
+ if (candidate === env.HBUILDERX_CLI_PATH) return "env";
28
+ if (candidate === "/Applications/HBuilderX.app/Contents/MacOS/cli" || candidate === "/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli") return "default-path";
29
+ return "candidate";
30
+ }
31
+ async function firstExisting$1(items) {
32
+ for (const item of items) if (await fileExists(item)) return item;
33
+ }
34
+ async function resolveConfiguredCli(options) {
35
+ const env = options.env ?? process.env;
36
+ if (options.candidates) {
37
+ const candidate = await firstExisting$1(options.candidates);
38
+ if (!candidate) throw new Error("未找到显式指定的 HBuilderX CLI candidate。");
39
+ return {
40
+ path: candidate,
41
+ source: resolveCandidateSource(candidate, env)
42
+ };
43
+ }
44
+ if (env.HBUILDERX_CLI_PATH && await fileExists(env.HBUILDERX_CLI_PATH)) return {
45
+ path: env.HBUILDERX_CLI_PATH,
46
+ source: "env"
47
+ };
48
+ }
49
+ //#endregion
50
+ //#region src/hbuilderx/discovery.ts
24
51
  function unique(items) {
25
52
  return [...new Set(items)];
26
53
  }
@@ -66,27 +93,57 @@ function extractHBuilderXExecutableFromProcessOutput(output, platform = process.
66
93
  return extractHBuilderXExecutablesFromProcessOutput(output, platform)[0];
67
94
  }
68
95
  async function findRunningHBuilderXCliCandidates(platform = process.platform) {
69
- const result = platform === "win32" ? spawnSync("wmic", [
70
- "process",
71
- "where",
72
- "name='HBuilderX.exe'",
73
- "get",
74
- "executablepath",
75
- "/format:csv"
76
- ], {
77
- encoding: "utf8",
78
- windowsHide: true
79
- }) : spawnSync("ps", [
96
+ const command = platform === "win32" ? "powershell.exe" : "ps";
97
+ const args = platform === "win32" ? [
98
+ "-NoLogo",
99
+ "-NoProfile",
100
+ "-NonInteractive",
101
+ "-Command",
102
+ [
103
+ "$ErrorActionPreference = 'Stop'",
104
+ "[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)",
105
+ `$PSModuleAutoLoadingPreference = 'None'`,
106
+ `[Console]::Error.WriteLine('process-discovery: querying')`,
107
+ `$paths = [System.Collections.Generic.List[string]]::new()`,
108
+ `foreach ($p in [System.Diagnostics.Process]::GetProcessesByName('HBuilderX')) { try { $paths.Add([Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($p.MainModule.FileName))) } finally { $p.Dispose() } }`,
109
+ `[Console]::Error.WriteLine('process-discovery: complete')`,
110
+ `[Console]::WriteLine('WT-HBUILDERX-PROCESSES/1')`,
111
+ `[Console]::WriteLine([string]::Join([Environment]::NewLine, $paths))`,
112
+ `[Console]::WriteLine('END')`
113
+ ].join("; ")
114
+ ] : [
80
115
  "-ax",
81
116
  "-o",
82
117
  "command="
83
- ], { encoding: "utf8" });
84
- if (result.error || result.status !== 0) return [];
85
- const executables = extractHBuilderXExecutablesFromProcessOutput(`${result.stdout ?? ""}${result.stderr ?? ""}`, platform);
118
+ ];
119
+ const result = spawnSync(command, args, {
120
+ encoding: "utf8",
121
+ stdio: [
122
+ "ignore",
123
+ "pipe",
124
+ "pipe"
125
+ ],
126
+ windowsHide: true,
127
+ timeout: 1e4,
128
+ maxBuffer: 1048576
129
+ });
130
+ if (result.error || result.status !== 0) throw new Error(`HBuilderX 进程探测失败:${command}, exit=${result.status}, signal=${result.signal}, cwd=${process.cwd()}\n${result.error?.message ?? ""}\n${result.stderr ?? ""}\n${result.stdout ?? ""}`);
131
+ let executables;
132
+ if (platform === "win32") {
133
+ const lines = result.stdout.replace(/^\uFEFF/, "").trim().split(/\r?\n/);
134
+ if (lines.shift() !== "WT-HBUILDERX-PROCESSES/1" || lines.pop() !== "END") throw new Error("HBuilderX Windows 进程探测返回了不完整的路径列表");
135
+ executables = lines.filter(Boolean).map((line) => {
136
+ const bytes = Buffer.from(line, "base64");
137
+ const executable = bytes.toString("utf8");
138
+ if (bytes.toString("base64") !== line || !Buffer.from(executable).equals(bytes) || !path.win32.isAbsolute(executable) || path.win32.parse(executable).root.length < 3 || path.win32.basename(executable).toLowerCase() !== "hbuilderx.exe") throw new Error("HBuilderX Windows 进程探测返回了无效路径列表");
139
+ return executable;
140
+ });
141
+ } else executables = extractHBuilderXExecutablesFromProcessOutput(result.stdout, platform);
142
+ const paths = platform === "win32" ? path.win32 : path.posix;
86
143
  const candidates = [];
87
144
  for (const executable of executables) {
88
145
  if (!await fileExists(executable)) continue;
89
- const cli = path.join(path.dirname(executable), platform === "win32" ? "cli.exe" : "cli");
146
+ const cli = paths.join(paths.dirname(executable), platform === "win32" ? "cli.exe" : "cli");
90
147
  if (await fileExists(cli)) candidates.push(cli);
91
148
  }
92
149
  return unique(candidates);
@@ -106,11 +163,6 @@ function selectHBuilderXCliCandidatesForChannel(items, channel) {
106
163
  if (channel === "auto") return sortByChannel(items);
107
164
  return items.filter((item) => inferHBuilderXChannel(item) === channel);
108
165
  }
109
- function resolveCandidateSource(candidate, env) {
110
- if (candidate === env.HBUILDERX_CLI_PATH) return "env";
111
- if (candidate === "/Applications/HBuilderX.app/Contents/MacOS/cli" || candidate === "/Applications/HBuilderX-Alpha.app/Contents/MacOS/cli") return "default-path";
112
- return "candidate";
113
- }
114
166
  async function firstExisting(items) {
115
167
  for (const item of items) if (await fileExists(item)) return item;
116
168
  }
@@ -118,21 +170,11 @@ async function resolveHBuilderXCliInfoFromOptions(options = {}) {
118
170
  const env = options.env ?? process.env;
119
171
  const channel = resolveHBuilderXChannel(options.channel ?? env.HBUILDERX_CHANNEL);
120
172
  const running = await findRunningHBuilderXCliCandidates();
121
- if (options.candidates) {
122
- const candidate = await firstExisting(options.candidates);
123
- if (candidate) return {
124
- path: candidate,
125
- isRunning: running.some((item) => normalizeFile(item) === normalizeFile(candidate)),
126
- source: resolveCandidateSource(candidate, env),
127
- channel: inferHBuilderXChannel(candidate)
128
- };
129
- throw new Error("未找到显式指定的 HBuilderX CLI candidate。");
130
- }
131
- if (env.HBUILDERX_CLI_PATH && await fileExists(env.HBUILDERX_CLI_PATH)) return {
132
- path: env.HBUILDERX_CLI_PATH,
133
- isRunning: running.some((item) => normalizeFile(item) === normalizeFile(env.HBUILDERX_CLI_PATH)),
134
- source: "env",
135
- channel: inferHBuilderXChannel(env.HBUILDERX_CLI_PATH)
173
+ const configured = await resolveConfiguredCli(options);
174
+ if (configured) return {
175
+ ...configured,
176
+ isRunning: running.some((item) => normalizeFile(item) === normalizeFile(configured.path)),
177
+ channel: inferHBuilderXChannel(configured.path)
136
178
  };
137
179
  const runningCandidate = selectHBuilderXCliCandidatesForChannel(running, channel)[0];
138
180
  if (runningCandidate) return {
@@ -197,8 +239,8 @@ function createLogBuffer(maxChunks = 160) {
197
239
  }
198
240
  function collectProcessOutput(child, maxChunks = 160) {
199
241
  const buffer = createLogBuffer(maxChunks);
200
- child.stdout?.on("data", (chunk) => buffer.push(chunk));
201
- child.stderr?.on("data", (chunk) => buffer.push(chunk));
242
+ child.stdout?.setEncoding("utf8").on("data", (chunk) => buffer.push(chunk));
243
+ child.stderr?.setEncoding("utf8").on("data", (chunk) => buffer.push(chunk));
202
244
  return buffer.logs;
203
245
  }
204
246
  function classifyHBuilderXOutput(output) {
@@ -340,7 +382,6 @@ function spawnCommand(options) {
340
382
  const child = spawn(options.command, options.args, {
341
383
  cwd: options.cwd,
342
384
  detached: options.detached ?? process.platform !== "win32",
343
- shell: process.platform === "win32",
344
385
  stdio: options.stdio === "inherit" ? "inherit" : [
345
386
  "ignore",
346
387
  "pipe",
@@ -353,6 +394,7 @@ function spawnCommand(options) {
353
394
  }
354
395
  });
355
396
  const logs = options.stdio === "inherit" ? [] : collectProcessOutput(child);
397
+ child.on("error", (error) => logs.push(`${error.message}\n`));
356
398
  let exit;
357
399
  const closed = new Promise((resolve) => {
358
400
  child.on("close", (code, signal) => {
@@ -426,11 +468,8 @@ function createProcessExitTracker(child) {
426
468
  };
427
469
  }
428
470
  //#endregion
429
- //#region src/hbuilderx/runner.ts
471
+ //#region src/hbuilderx/hosts.ts
430
472
  const ansiRE = new RegExp(`${String.fromCharCode(27)}\\[[\\d;]*m`, "g");
431
- const defaultStartupTimeoutMs = 6e4;
432
- const hostPollIntervalMs = 500;
433
- const maxSessionLogChunks = 160;
434
473
  function stripAnsi(value) {
435
474
  return value.replace(ansiRE, "");
436
475
  }
@@ -443,18 +482,6 @@ function parseHBuilderXVersion(output) {
443
482
  function inferHBuilderXChannelFromVersion(version) {
444
483
  return /(?:^|-)alpha(?:\.|$)/i.test(version) ? "alpha" : "stable";
445
484
  }
446
- function createHBuilderXNativeLaunchArgs(options) {
447
- const args = [
448
- "launch",
449
- options.platform,
450
- "--project",
451
- path.resolve(options.cwd),
452
- ...options.args ?? []
453
- ];
454
- if (options.compile != null && !args.includes("--compile")) args.push("--compile", String(options.compile));
455
- if (options.runtimeLog != null && !args.includes("--runtime-log")) args.push("--runtime-log", String(options.runtimeLog));
456
- return args;
457
- }
458
485
  function createRunnerError(cliPath, cwd, args, kind, message, hint, logs) {
459
486
  const output = formatRecentLogs(logs);
460
487
  return new HBuilderXCommandError([
@@ -480,55 +507,55 @@ function createRunnerError(cliPath, cwd, args, kind, message, hint, logs) {
480
507
  }
481
508
  });
482
509
  }
483
- function bindHost(args, host) {
484
- const hostIndex = args.indexOf("--host");
485
- if (hostIndex < 0) return [
486
- ...args,
487
- "--host",
488
- host
489
- ];
490
- if (args[hostIndex + 1] !== host) throw new Error(`runner 已绑定 HBuilderX host=${host},不能改为 ${args[hostIndex + 1] ?? "空值"}。`);
491
- return args;
492
- }
493
- function appendLogs(target, source) {
494
- target.push(...source);
495
- if (target.length > maxSessionLogChunks) target.splice(0, target.length - maxSessionLogChunks);
496
- }
497
- async function listCompatibleHosts(cliPath, cwd, env, expectedChannel, explicitHost, timeoutMs) {
498
- const startedAt = Date.now();
510
+ async function connectHBuilderXHost(options) {
511
+ const { cliPath, cwd, env, expectedChannel, explicitHost } = options;
512
+ const deadline = Date.now() + options.timeoutMs;
499
513
  const logs = [];
500
- do {
501
- const listed = await runCommand({
514
+ const timeoutError = (args) => new HBuilderXCommandError(`HBuilderX host 连接超时:${cliPath} ${args.join(" ")}\ncwd=${cwd}\nexit=null\nissue=timeout\n${formatRecentLogs(logs)}`, {
515
+ command: cliPath,
516
+ args,
517
+ cwd,
518
+ exit: {
519
+ code: null,
520
+ signal: null
521
+ },
522
+ logs,
523
+ output: formatRecentLogs(logs),
524
+ issue: createTimeoutIssue()
525
+ });
526
+ const command = async (args, maxTimeoutMs = 1e4) => {
527
+ const remaining = deadline - Date.now();
528
+ if (remaining <= 0) throw timeoutError(args);
529
+ const result = await runCommand({
502
530
  command: cliPath,
503
- args: ["listhost"],
531
+ args,
504
532
  cwd,
505
533
  env,
506
- timeoutMs: Math.min(timeoutMs, 1e4),
534
+ timeoutMs: Math.min(remaining, maxTimeoutMs),
507
535
  allowFailure: true
508
536
  });
509
- appendLogs(logs, listed.logs);
510
- const hosts = explicitHost ? [explicitHost] : parseHBuilderXHosts(listed.output);
537
+ logs.push(...result.logs);
538
+ if (logs.length > 160) logs.splice(0, logs.length - 160);
539
+ return result;
540
+ };
541
+ const assertCommand = (result) => {
542
+ if (result.issue.kind === "cli-instance-mismatch" || result.issue.kind === "cli-host-ambiguous") throw createRunnerError(cliPath, cwd, result.args, result.issue.kind, result.issue.message, result.issue.hint ?? "请检查目标 HBuilderX host。", logs);
543
+ if (result.exit.code !== 0) throw new HBuilderXCommandError(`HBuilderX host 命令失败:${cliPath} ${result.args.join(" ")}\ncwd=${cwd}\nexit=${result.exit.signal ?? result.exit.code}\nissue=${result.issue.kind}\n${formatRecentLogs(logs)}`, result);
544
+ };
545
+ const probe = async () => {
546
+ const listed = await command(["listhost"]);
547
+ if (!(listed.issue.kind !== "timeout" && /HBuilderX is not detected running\. Please execute cli open/i.test(stripAnsi(listed.output)))) assertCommand(listed);
548
+ const hosts = parseHBuilderXHosts(listed.output);
511
549
  const compatible = [];
512
- for (const host of hosts) {
513
- const versionResult = await runCommand({
514
- command: cliPath,
515
- args: [
516
- "version",
517
- "--host",
518
- host
519
- ],
520
- cwd,
521
- env,
522
- timeoutMs: Math.min(timeoutMs, 1e4),
523
- allowFailure: true
524
- });
525
- appendLogs(logs, versionResult.logs);
526
- if (versionResult.issue.kind === "cli-instance-mismatch") return {
527
- compatible: [],
528
- logs
529
- };
530
- const version = versionResult.exit.code === 0 ? parseHBuilderXVersion(versionResult.output) : void 0;
531
- if (!version) continue;
550
+ for (const host of explicitHost ? [explicitHost] : hosts) {
551
+ const result = await command([
552
+ "version",
553
+ "--host",
554
+ host
555
+ ]);
556
+ assertCommand(result);
557
+ const version = parseHBuilderXVersion(result.output);
558
+ if (!version) throw createRunnerError(cliPath, cwd, result.args, "cli-instance-mismatch", `无法验证 HBuilderX host=${host} 的版本`, "请检查目标实例是否就绪。", logs);
532
559
  const channel = inferHBuilderXChannelFromVersion(version);
533
560
  if (expectedChannel === "unknown" || channel === expectedChannel) compatible.push({
534
561
  host,
@@ -536,16 +563,44 @@ async function listCompatibleHosts(cliPath, cwd, env, expectedChannel, explicitH
536
563
  channel
537
564
  });
538
565
  }
539
- if (compatible.length > 0) return {
540
- compatible,
541
- logs
542
- };
543
- await wait(hostPollIntervalMs);
544
- } while (Date.now() - startedAt < timeoutMs);
545
- return {
546
- compatible: [],
547
- logs
566
+ if (compatible.length > 1) throw createRunnerError(cliPath, cwd, ["listhost"], "cli-host-ambiguous", `检测到多个匹配的 HBuilderX host:${compatible.map((item) => item.host).join(", ")}`, "请设置 HBUILDERX_HOST,或显式传入 host。", logs);
567
+ if (!compatible.length && (hosts.length || explicitHost)) throw createRunnerError(cliPath, cwd, ["listhost"], "cli-instance-mismatch", `未找到与 ${expectedChannel} CLI 匹配的 HBuilderX host`, "请检查 HBUILDERX_CLI_PATH、HBUILDERX_CHANNEL 和 HBUILDERX_HOST。", logs);
568
+ return compatible[0];
548
569
  };
570
+ const existing = await probe();
571
+ if (existing) return existing;
572
+ assertCommand(await command(["open"], options.timeoutMs));
573
+ do {
574
+ const selected = await probe();
575
+ if (selected) return selected;
576
+ await wait(Math.min(500, Math.max(0, deadline - Date.now())));
577
+ } while (Date.now() < deadline);
578
+ throw timeoutError(["listhost"]);
579
+ }
580
+ //#endregion
581
+ //#region src/hbuilderx/runner.ts
582
+ const defaultStartupTimeoutMs = 6e4;
583
+ function createHBuilderXNativeLaunchArgs(options) {
584
+ const args = [
585
+ "launch",
586
+ options.platform,
587
+ "--project",
588
+ path.resolve(options.cwd),
589
+ ...options.args ?? []
590
+ ];
591
+ if (options.compile != null && !args.includes("--compile")) args.push("--compile", String(options.compile));
592
+ if (options.runtimeLog != null && !args.includes("--runtime-log")) args.push("--runtime-log", String(options.runtimeLog));
593
+ return args;
594
+ }
595
+ function bindHost(args, host) {
596
+ const hostIndex = args.indexOf("--host");
597
+ if (hostIndex < 0) return [
598
+ ...args,
599
+ "--host",
600
+ host
601
+ ];
602
+ if (args[hostIndex + 1] !== host) throw new Error(`runner 已绑定 HBuilderX host=${host},不能改为 ${args[hostIndex + 1] ?? "空值"}。`);
603
+ return args;
549
604
  }
550
605
  async function createHBuilderXRunner(options = {}) {
551
606
  const env = {
@@ -554,35 +609,32 @@ async function createHBuilderXRunner(options = {}) {
554
609
  };
555
610
  const cwd = options.cwd ?? process.cwd();
556
611
  const timeoutMs = options.timeoutMs ?? defaultStartupTimeoutMs;
557
- const resolution = await resolveHBuilderXCliInfoFromOptions({
612
+ const resolveOptions = {
558
613
  candidates: options.hbuilderxCliPath ? [options.hbuilderxCliPath] : options.candidates,
559
614
  channel: options.channel,
560
615
  env,
561
616
  host: options.host
562
- });
617
+ };
618
+ const configured = await resolveConfiguredCli(resolveOptions);
619
+ const resolution = configured ? {
620
+ ...configured,
621
+ channel: inferHBuilderXChannel(configured.path)
622
+ } : await resolveHBuilderXCliInfoFromOptions(resolveOptions);
563
623
  const cliEnv = {
564
624
  ...env,
565
625
  HBUILDERX_CLI_PATH: resolution.path
566
626
  };
567
- if (!resolution.isRunning) {
568
- const opened = await runCommand({
569
- command: resolution.path,
570
- args: ["open"],
571
- cwd,
572
- env: cliEnv,
573
- timeoutMs,
574
- allowFailure: true
575
- });
576
- const openIssue = classifyHBuilderXOutput(opened.output);
577
- if (opened.exit.code !== 0 || openIssue.kind === "cli-instance-mismatch" || openIssue.kind === "cli-host-ambiguous") throw createRunnerError(resolution.path, cwd, ["open"], openIssue.kind === "cli-host-ambiguous" ? "cli-host-ambiguous" : "cli-instance-mismatch", openIssue.message, openIssue.hint ?? "请检查目标 HBuilderX 运行实例。", opened.logs);
578
- }
579
627
  const requestedChannel = resolveHBuilderXChannel(options.channel ?? env.HBUILDERX_CHANNEL);
580
628
  const expectedChannel = resolution.channel !== "unknown" ? resolution.channel : requestedChannel === "auto" ? inferHBuilderXChannel(resolution.path) : requestedChannel;
581
629
  const explicitHost = options.host ?? env.HBUILDERX_HOST;
582
- const { compatible, logs } = await listCompatibleHosts(resolution.path, cwd, cliEnv, expectedChannel, explicitHost, timeoutMs);
583
- if (compatible.length === 0) throw createRunnerError(resolution.path, cwd, ["listhost"], "cli-instance-mismatch", `未找到与 ${expectedChannel} CLI 匹配的 HBuilderX host`, "请启动对应版本,或检查 HBUILDERX_CLI_PATH、HBUILDERX_CHANNEL 和 HBUILDERX_HOST。", logs);
584
- if (compatible.length > 1) throw createRunnerError(resolution.path, cwd, ["listhost"], "cli-host-ambiguous", `检测到多个匹配的 HBuilderX host:${compatible.map((item) => item.host).join(", ")}`, "请设置 HBUILDERX_HOST,或在 createHBuilderXRunner options 中显式传入 host。", logs);
585
- const selected = compatible[0];
630
+ const selected = await connectHBuilderXHost({
631
+ cliPath: resolution.path,
632
+ cwd,
633
+ env: cliEnv,
634
+ expectedChannel,
635
+ explicitHost,
636
+ timeoutMs
637
+ });
586
638
  const boundResolution = {
587
639
  ...resolution,
588
640
  isRunning: true,
@@ -668,7 +720,9 @@ async function resolveHBuilderXCliInfo(candidatesOrOptions, env = process.env) {
668
720
  } : candidatesOrOptions);
669
721
  }
670
722
  async function resolveHBuilderXCli(candidatesOrOptions) {
671
- return (await resolveHBuilderXCliInfo(candidatesOrOptions)).path;
723
+ const options = Array.isArray(candidatesOrOptions) ? { candidates: candidatesOrOptions } : candidatesOrOptions ?? {};
724
+ resolveHBuilderXChannel(options.channel ?? (options.env ?? process.env).HBUILDERX_CHANNEL);
725
+ return (await resolveConfiguredCli(options))?.path ?? (await resolveHBuilderXCliInfoFromOptions(options)).path;
672
726
  }
673
727
  function createHBuilderXEnv(options = {}) {
674
728
  return {
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "@weapp-tailwindcss/hbuilderx-runner",
3
3
  "type": "module",
4
- "version": "0.1.2",
4
+ "version": "0.1.4",
5
5
  "description": "HBuilderX runner utilities for cross-platform uni-app Tailwind CSS workflows. 跨端 uni-app Tailwind CSS 工作流的 HBuilderX 运行器工具。",
6
6
  "author": "ice breaker <1324318532@qq.com>",
7
7
  "license": "MIT",
8
+ "homepage": "https://tw.weapp.dev/docs/quick-start/frameworks/hbuilderx",
8
9
  "repository": {
9
10
  "type": "git",
10
11
  "url": "git+https://github.com/sonofmagic/weapp-tailwindcss.git",
@@ -41,7 +42,12 @@
41
42
  "publishConfig": {
42
43
  "access": "public"
43
44
  },
44
- "devDependencies": {},
45
+ "dependencies": {
46
+ "cross-spawn": "^7.0.6"
47
+ },
48
+ "devDependencies": {
49
+ "@types/cross-spawn": "^6.0.6"
50
+ },
45
51
  "scripts": {
46
52
  "dev": "tsdown --watch --sourcemap",
47
53
  "build": "tsdown",