huaweicloud-devkit 1.1.9 → 1.1.10-next.1

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.
Files changed (31) hide show
  1. package/README.md +1 -1
  2. package/README.zh-CN.md +1 -1
  3. package/integrations/opencode/package-lock.json +24 -0
  4. package/integrations/opencode/package.json +10 -0
  5. package/integrations/opencode/plugins/huaweicloud-devkit.js +194 -0
  6. package/package.json +1 -1
  7. package/plugins/huaweicloud-core/.claude-plugin/plugin.json +1 -1
  8. package/plugins/huaweicloud-core/.codex-plugin/plugin.json +1 -1
  9. package/plugins/huaweicloud-core/.cursor-plugin/plugin.json +1 -1
  10. package/plugins/huaweicloud-core/.hermes-plugin/plugin.json +1 -1
  11. package/plugins/huaweicloud-core/.workbuddy-plugin/plugin.json +1 -1
  12. package/plugins/huaweicloud-core/openclaw.plugin.json +1 -1
  13. package/plugins/huaweicloud-core/safety/rules/cloud-risk-rules.json +7 -1
  14. package/plugins/huaweicloud-core/skills/huawei-ecs/references/create-instance.md +53 -0
  15. package/plugins/huaweicloud-core/skills/huawei-ecs/references/hc-activity.md +16 -0
  16. package/plugins/huaweicloud-core/skills/huawei-ecs/references/troubleshooting.md +51 -0
  17. package/plugins/huaweicloud-core/skills/huawei-ecs/references/windows-ssh.md +24 -0
  18. package/plugins/huaweicloud-core/skills/huawei-iac/SKILL.md +38 -36
  19. package/plugins/huaweicloud-core/skills/huawei-iam/SKILL.md +35 -16
  20. package/plugins/huaweicloud-core/skills/huawei-iam/references/quick-ref.md +35 -0
  21. package/plugins/huaweicloud-core/skills/huawei-sandbox/SKILL.md +8 -1
  22. package/plugins/huaweicloud-core/src/account-type.mjs +135 -0
  23. package/plugins/huaweicloud-core/src/auth/credentials.mjs +81 -0
  24. package/plugins/huaweicloud-core/src/auth/token-exchange.mjs +100 -0
  25. package/plugins/huaweicloud-core/src/hcloud-cli.mjs +58 -5
  26. package/plugins/huaweicloud-core/src/mcp-config-merge.mjs +1 -1
  27. package/plugins/huaweicloud-core/src/risk-rule-engine.mjs +1 -1
  28. package/plugins/huaweicloud-core/src/safety-policy.mjs +37 -6
  29. package/plugins/huaweicloud-core/src/sandbox/session-manager.mjs +172 -21
  30. package/plugins/huaweicloud-core/src/setup-cli.mjs +62 -4
  31. package/plugins/huaweicloud-core/src/tools.mjs +55 -5
@@ -0,0 +1,100 @@
1
+ import { fetchWithProxy } from '../proxy/proxy-agent.mjs';
2
+
3
+ const DEFAULT_DURATION_SECONDS = 900;
4
+ const DEFAULT_IAM_ENDPOINT = 'https://iam.myhuaweicloud.com';
5
+
6
+ export async function exchangeTokenForCredentials(token, options = {}) {
7
+ const durationSeconds = options.durationSeconds ?? DEFAULT_DURATION_SECONDS;
8
+ const iamEndpoint = options.iamEndpoint || process.env.HW_TOKEN_IAM_ENDPOINT || DEFAULT_IAM_ENDPOINT;
9
+ const fetchImpl = options.fetchImpl;
10
+
11
+ const body = {
12
+ auth: {
13
+ identity: {
14
+ methods: ['token'],
15
+ token: { id: token, duration_seconds: durationSeconds },
16
+ },
17
+ },
18
+ };
19
+
20
+ const fetchOpts = {
21
+ method: 'POST',
22
+ headers: { 'Content-Type': 'application/json;charset=utf8' },
23
+ body: JSON.stringify(body),
24
+ };
25
+
26
+ const url = `${iamEndpoint}/v3.0/OS-CREDENTIAL/securitytokens`;
27
+
28
+ let resp;
29
+ try {
30
+ resp = fetchImpl ? await fetchImpl(url, fetchOpts) : await fetchWithProxy(url, fetchOpts);
31
+ } catch (error) {
32
+ const err = new Error(`Token exchange request failed: ${error.message}`);
33
+ err.code = 'TOKEN_EXCHANGE_FAILED';
34
+ throw err;
35
+ }
36
+
37
+ if (resp.status === 401 || resp.status === 403) {
38
+ const err = new Error('X-Auth-Token is invalid or expired.');
39
+ err.code = 'TOKEN_INVALID';
40
+ throw err;
41
+ }
42
+ if (resp.status !== 201) {
43
+ const err = new Error(`Token exchange returned unexpected status ${resp.status}.`);
44
+ err.code = 'TOKEN_EXCHANGE_FAILED';
45
+ throw err;
46
+ }
47
+
48
+ let data;
49
+ try {
50
+ data = await resp.json();
51
+ } catch (error) {
52
+ const err = new Error(`Token exchange returned malformed JSON: ${error.message}`);
53
+ err.code = 'TOKEN_EXCHANGE_FAILED';
54
+ throw err;
55
+ }
56
+ const cred = data?.credential;
57
+ if (!cred?.access || !cred?.secret || !cred?.securitytoken) {
58
+ const err = new Error('Token exchange response missing credential fields.');
59
+ err.code = 'TOKEN_EXCHANGE_FAILED';
60
+ throw err;
61
+ }
62
+ // IAM always returns expires_at; if it is absent (or unparseable) we store
63
+ // expiresAt:null, which never satisfies the `cached.expiresAt && …` guard in
64
+ // getTokenCredentials — so the cache is always a miss and we deliberately
65
+ // re-exchange on every call rather than risk caching credentials forever.
66
+ const expiresAt = cred.expires_at ? Date.parse(cred.expires_at) : NaN;
67
+ return {
68
+ ak: cred.access,
69
+ sk: cred.secret,
70
+ securityToken: cred.securitytoken,
71
+ expiresAt: Number.isFinite(expiresAt) ? expiresAt : null,
72
+ };
73
+ }
74
+
75
+ const GRACE_MS = 60 * 1000;
76
+
77
+ let cached = null; // { ak, sk, securityToken, expiresAt }
78
+ let inflight = null; // Promise 单飞
79
+
80
+ export function __resetTokenCache() {
81
+ cached = null;
82
+ inflight = null;
83
+ }
84
+
85
+ export async function getTokenCredentials(token, options = {}) {
86
+ const now = Date.now();
87
+ if (cached && cached.expiresAt && cached.expiresAt - GRACE_MS > now) {
88
+ return cached;
89
+ }
90
+ if (inflight) return inflight;
91
+ inflight = (async () => {
92
+ try {
93
+ cached = await exchangeTokenForCredentials(token, options);
94
+ return cached;
95
+ } finally {
96
+ inflight = null;
97
+ }
98
+ })();
99
+ return inflight;
100
+ }
@@ -7,7 +7,13 @@ import { dirname, join } from 'node:path';
7
7
  import { classifyHcloudArgs, redactSecrets, assertAllowed } from './safety-policy.mjs';
8
8
  import { getProxySettings } from './proxy/proxy-config.mjs';
9
9
  import { resolveHcloudCommand } from './hcloud-probe.mjs';
10
- import { parseStsExpiry, resolveCredentialsWithRuntime } from './auth/credentials.mjs';
10
+ import {
11
+ parseStsExpiry,
12
+ resolveCredentialsWithRuntime,
13
+ resolveXAuthToken,
14
+ resolveXAuthTokenExpiry,
15
+ } from './auth/credentials.mjs';
16
+ import { getTokenCredentials } from './auth/token-exchange.mjs';
11
17
 
12
18
  const DEFAULT_TIMEOUT_MS = 60_000;
13
19
  const DEFAULT_FORCE_KILL_AFTER_MS = 2_000;
@@ -297,7 +303,7 @@ export function redactArgsWithObs(rawArgs) {
297
303
  return redactSecrets(out);
298
304
  }
299
305
 
300
- export function resolveStsInjectArgs(rawArgs) {
306
+ export async function resolveStsInjectArgs(rawArgs) {
301
307
  const normalized = Array.isArray(rawArgs) ? rawArgs.map(String) : [];
302
308
  if (normalized.length === 0) return [];
303
309
  const flat = normalized.map(String);
@@ -350,7 +356,25 @@ export function resolveStsInjectArgs(rawArgs) {
350
356
  } catch {
351
357
  return [];
352
358
  }
353
- if (!creds || !creds.ak || !creds.sk || !creds.securityToken) return [];
359
+ if (!creds || !creds.ak || !creds.sk) {
360
+ const token = resolveXAuthToken();
361
+ if (token) {
362
+ const expiry = resolveXAuthTokenExpiry();
363
+ if (expiry !== null && expiry - 60000 <= Date.now()) {
364
+ const err = new Error('X-Auth-Token 已过期,请重启进程重新注入凭证。');
365
+ err.code = 'TOKEN_EXPIRED';
366
+ throw err;
367
+ }
368
+ const temp = await getTokenCredentials(token);
369
+ return [
370
+ '--cli-access-key=' + temp.ak,
371
+ '--cli-secret-key=' + temp.sk,
372
+ '--cli-security-token=' + temp.securityToken,
373
+ ];
374
+ }
375
+ return [];
376
+ }
377
+ if (!creds.securityToken) return [];
354
378
 
355
379
  // R3: if we can derive an expiry and the token is already at/within 60s of
356
380
  // expiring, skip injection — using a dead token would make a doomed IAM round
@@ -468,7 +492,22 @@ export async function runHcloud(args, options = {}) {
468
492
  // and R3 forbids writing them to disk). Inject per-command so hcloud actually
469
493
  // authenticates with the platform-provided STS. Injection args are appended to
470
494
  // the EXECUTED args only; classification/approval used the original args.
471
- const stsInject = resolveStsInjectArgs(normalizedArgs);
495
+ let stsInject;
496
+ try {
497
+ stsInject = await resolveStsInjectArgs(normalizedArgs);
498
+ } catch (error) {
499
+ if (error?.code === 'TOKEN_INVALID' || error?.code === 'TOKEN_EXCHANGE_FAILED' || error?.code === 'TOKEN_EXPIRED') {
500
+ return {
501
+ ok: false,
502
+ code: error.code,
503
+ error: error.message,
504
+ stderr: '',
505
+ stdout: '',
506
+ plan,
507
+ };
508
+ }
509
+ throw error;
510
+ }
472
511
  if (stsInject.length > 0) {
473
512
  plan.rawArgs = [...plan.rawArgs, ...stsInject];
474
513
  }
@@ -799,8 +838,22 @@ export function extractApiError(stdout) {
799
838
  return null;
800
839
  }
801
840
 
841
+ // A4 (#935): KooCLI 7.2.x prints a version-upgrade banner on EVERY command
842
+ // output (e.g. 「可执行 hcloud update 更新至 7.3.12」), which floods agent
843
+ // conversations and drowns the actual result. Banner lines are stripped from
844
+ // command output here; the only upgrade hint DevKit emits is check_cli/doctor's
845
+ // soft, one-shot mismatch hint — kooCliVersion in package.json is the single
846
+ // source of truth for the paired version, and check_cli/doctor keep their
847
+ // non-blocking semantics.
848
+ export function stripKooCliUpdateBanner(output) {
849
+ return String(output || '')
850
+ .split('\n')
851
+ .filter((line) => !(/hcloud\s+update/i.test(line) && /更新至|update to/i.test(line)))
852
+ .join('\n');
853
+ }
854
+
802
855
  export function redactOutput(output) {
803
- let text = String(output || '');
856
+ let text = stripKooCliUpdateBanner(String(output || ''));
804
857
  const bracketIdx = text.indexOf('{');
805
858
  if (bracketIdx > 0) text = text.substring(bracketIdx);
806
859
  try {
@@ -3,7 +3,7 @@
3
3
  // Program-owned fields (the node executable + mcp-server.mjs path, required env
4
4
  // keys) are corrected by the installer; everything else belongs to the user.
5
5
 
6
- function isPlainObject(value) {
6
+ export function isPlainObject(value) {
7
7
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
8
8
  }
9
9
 
@@ -19,7 +19,7 @@ export function loadRiskRules(options = {}) {
19
19
  function redactEvidence(text) {
20
20
  return String(text)
21
21
  .replace(
22
- /((?:access[_-]?key|secret[_-]?key|secret|security[_-]?token|x[_-]?auth[_-]?token|token|authorization|password|passwd|admin[_-]?pass|credential)\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;]+)/gi,
22
+ /((?:access[_-]?key|secret[_-]?key|secret|security[_-]?token|x[_-]?auth[_-]?token|x[_-]?subject[_-]?token|token|authorization|password|passwd|admin[_-]?pass|credential)\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;]+)/gi,
23
23
  '$1<redacted>',
24
24
  )
25
25
  .replace(/(AK|SK)\s*[:=]\s*("[^"]*"|'[^']*'|[^\s,;]+)/g, '$1=<redacted>');
@@ -39,7 +39,7 @@ function redactString(text) {
39
39
  // Redact the ENTIRE value of this arg — not just the first whitespace token.
40
40
  .replace(/((?:user[_-]?data|metadata|private[_-]?key)\s*[:=]\s*).*/gi, '$1<redacted>')
41
41
  .replace(
42
- /((?:access[_-]?key|secret[_-]?key|security[_-]?token|x[_-]?auth[_-]?token|token|authorization|password|passwd|admin[_-]?pass|credential)\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;]+)/gi,
42
+ /((?:access[_-]?key|secret[_-]?key|security[_-]?token|x[_-]?auth[_-]?token|x[_-]?subject[_-]?token|token|authorization|password|passwd|admin[_-]?pass|credential)\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;]+)/gi,
43
43
  '$1<redacted>',
44
44
  )
45
45
  .replace(/(AK|SK)\s*[:=]\s*("[^"]*"|'[^']*'|[^\s,;]+)/g, '$1=<redacted>')
@@ -394,7 +394,13 @@ function splitSimpleCommand(command) {
394
394
  return (
395
395
  String(command)
396
396
  .match(/"[^"]*"|'[^']*'|\S+/g)
397
- ?.map((part) => part.replace(/^['"]|['"]$/g, '')) || []
397
+ // Strip ALL quote characters (not just the outer pair): POSIX shells
398
+ // remove quotes before executing, so an embedded-quote form like
399
+ // `hcloud ECS De'leteServer …` actually runs `DeleteServer`. Stripping
400
+ // only outer quotes left `De'leteServer` in the token and let the write/
401
+ // secret/execution matchers miss it (#927). This hcloud classification
402
+ // path only — credential-var lookbehind still sees raw text with quotes.
403
+ .map((part) => part.replace(/['"]/g, '')) || []
398
404
  );
399
405
  }
400
406
 
@@ -478,12 +484,37 @@ export function extractInnerCommand(text, depth = 0) {
478
484
  // ^hcloud still catches wrapped commands and prompt-injections using
479
485
  // separators. sudo\s+ preserves the dev-baseline behaviour where
480
486
  // `sudo hcloud …` is treated as a real command, not documentation (#760 P0).
487
+ // Keyword-locator pattern shared by the raw-text match and the quote-stripped
488
+ // retry in extractHcloudSubcommand (`im` flag, no `g` — no lastIndex state).
489
+ const HCLOUD_KEYWORD_PATTERN = /(?:^|[;|&]\s*|\$\(\s*|`\s*|sudo\s+|\r?\n\s*)(hcloud(?:\.exe)?\b)/im;
490
+
481
491
  function extractHcloudSubcommand(text) {
482
492
  const t = String(text || '');
483
- const match = /(?:^|[;|&]\s*|\$\(\s*|`\s*|sudo\s+)(hcloud(?:\.exe)?\b)/i.exec(t);
484
- if (!match) return null;
485
- const hcloudIndex = match.index + match[0].length - match[1].length;
486
- return t.slice(hcloudIndex);
493
+ // `m` flag + newline in the separator class: a hcloud command at the start
494
+ // of any line (not just the first) must be located and fully classified —
495
+ // previously `echo hello\nhcloud ECS DeleteServer …` fell through as
496
+ // not_huaweicloud allow (#927).
497
+ const match = HCLOUD_KEYWORD_PATTERN.exec(t);
498
+ if (match) {
499
+ const hcloudIndex = match.index + match[0].length - match[1].length;
500
+ return t.slice(hcloudIndex);
501
+ }
502
+ // Keyword-embedded quotes fallback (#927 B1): POSIX shells strip quotes
503
+ // before execution, so `hc'loud ECS DeleteServer …` runs `hcloud …` — but
504
+ // the literal match above never sees the keyword through the quotes and the
505
+ // command fell through as not_huaweicloud allow (its de-quoted form is
506
+ // DENY). Retry on a quote-stripped COPY used only for hcloud keyword
507
+ // location; the returned subcommand is the de-quoted text, matching the
508
+ // de-quote semantics splitSimpleCommand already applies to tokens.
509
+ // Credential/env-var checks in classifyTextCommand still run on the raw
510
+ // text — the two paths stay independent — and natural-language mentions
511
+ // ("see hcloud docs", "echo hcloud is a CLI") match the same anchored
512
+ // pattern, so no new false positives are introduced.
513
+ const stripped = t.replace(/['"]/g, '');
514
+ const strippedMatch = HCLOUD_KEYWORD_PATTERN.exec(stripped);
515
+ if (!strippedMatch) return null;
516
+ const hcloudIndex = strippedMatch.index + strippedMatch[0].length - strippedMatch[1].length;
517
+ return stripped.slice(hcloudIndex);
487
518
  }
488
519
 
489
520
  export function classifyTextCommand(command, options = {}) {
@@ -226,12 +226,48 @@ export function buildExposeRemediation(port) {
226
226
  return `In the sandbox: source /tmp/hw_creds.sh; source /tmp/hw_api_key 2>/dev/null; devbridge delete-all; devbridge create <name>; devbridge port create <tunnelId> -p ${port} --protocol http -a; nohup devbridge host <tunnelId> -p ${port} > /tmp/host.log 2>&1 & If deploy_nginx reported a different (auto-incremented) port in its "port" field, use THAT port instead of the one shown here. Full procedure in huawei-sandbox skill, Step 7 (Expose via DevBridge).`;
227
227
  }
228
228
 
229
- export async function uploadFileWithSession(workspaceId, localPath, remotePath, username = 'root', timeoutMs = 30000) {
230
- if (!existsSync(localPath)) {
231
- throw new Error(`sandbox upload: local file not found: ${localPath}`);
229
+ // #953: classify a local upload path BEFORE touching the file, so the error names
230
+ // the real problem instead of a misleading "not found" when an entire parent
231
+ // directory is missing (agent-side paths often do not exist at all).
232
+ // kind: 'file' (uploadFileWithSession) | 'directory' (uploadProjectWithSession).
233
+ // Returns null when the path exists with the expected type; otherwise an Error
234
+ // whose message distinguishes missing-path from missing-parent, with a copy-to-tmp
235
+ // hint that names the actual OS temp dir.
236
+ export function classifyLocalUploadPath(localPath, kind = 'file') {
237
+ const expected = kind === 'directory' ? 'directory' : 'regular file';
238
+ const prefix = kind === 'directory' ? 'sandbox upload project' : 'sandbox upload';
239
+ if (existsSync(localPath)) {
240
+ const stat = statSync(localPath);
241
+ const matches = kind === 'directory' ? stat.isDirectory() : stat.isFile();
242
+ if (!matches) {
243
+ return new Error(`${prefix}: path is not a ${expected}: ${localPath}`);
244
+ }
245
+ return null;
232
246
  }
233
- if (!statSync(localPath).isFile()) {
234
- throw new Error(`sandbox upload: path is not a regular file: ${localPath}`);
247
+ const parent = dirname(localPath);
248
+ if (!existsSync(parent)) {
249
+ return new Error(
250
+ `${prefix}: directory not found: ${parent}. The DevKit MCP server reads files from ` +
251
+ `the machine it runs on. Verify the path, or first copy the ${expected} to the local ` +
252
+ `temp directory (${tmpdir()}) and upload from there.`,
253
+ );
254
+ }
255
+ return new Error(`${prefix}: local ${expected} not found: ${localPath}`);
256
+ }
257
+
258
+ // #953: reset command for uploadFileWithSession. mkdir -p the remote parent BEFORE any
259
+ // chunk writes — the `printf >>` appends land in "${remotePath}.b64tmp" next to the
260
+ // target, so an absent directory (e.g. /workspace/game2048/) would fail the very first
261
+ // batch. This aligns base64-path behavior with upload_project's file server (which
262
+ // already makedirs). Both paths are quoted; "path with spaces" is covered by tests.
263
+ export function buildUploadResetCommand(remotePath, tmpPath) {
264
+ return `mkdir -p "$(dirname "${remotePath}")" && rm -f "${tmpPath}"`;
265
+ }
266
+
267
+ export async function uploadFileWithSession(workspaceId, localPath, remotePath, username = 'root', timeoutMs = 30000) {
268
+ const localError = classifyLocalUploadPath(localPath, 'file');
269
+ if (localError) {
270
+ throw localError;
235
271
  }
236
272
  const content = readFileSync(localPath);
237
273
  const base64 = content.toString('base64');
@@ -239,7 +275,7 @@ export async function uploadFileWithSession(workspaceId, localPath, remotePath,
239
275
  const chunks = splitBase64Chunks(base64);
240
276
  const tmp = `${remotePath}.b64tmp`;
241
277
 
242
- const reset = await execWithSession(workspaceId, `rm -f "${tmp}"`, username, timeoutMs);
278
+ const reset = await execWithSession(workspaceId, buildUploadResetCommand(remotePath, tmp), username, timeoutMs);
243
279
  if (reset.exitCode !== 0) {
244
280
  throw new Error(`sandbox upload: failed to reset temp file: ${reset.stdout || reset.error || reset.exitCode}`);
245
281
  }
@@ -639,11 +675,9 @@ export async function uploadProjectWithSession(
639
675
  'Set HW_WORKSPACE_ID env var or ensure huaweicloud_sandbox_connect was called first.',
640
676
  );
641
677
  }
642
- if (!existsSync(localDir)) {
643
- throw new Error(`sandbox upload project: local directory not found: ${localDir}`);
644
- }
645
- if (!statSync(localDir).isDirectory()) {
646
- throw new Error(`sandbox upload project: path is not a directory: ${localDir}`);
678
+ const localError = classifyLocalUploadPath(localDir, 'directory');
679
+ if (localError) {
680
+ throw localError;
647
681
  }
648
682
 
649
683
  rotateUploadLog();
@@ -740,6 +774,56 @@ export async function uploadProjectWithSession(
740
774
  };
741
775
  }
742
776
 
777
+ // A1 (#935): normalize the deploy_nginx configName to a bare filename. A value
778
+ // carrying path separators (e.g. `/root/hc-activity.conf`, `./x/y.conf`) used to
779
+ // be spliced verbatim into `/etc/nginx/conf.d/${configName}.conf`, producing the
780
+ // broken path `/etc/nginx/conf.d//root/hc-activity.conf` (nginx never serves it,
781
+ // the tunnel answers 502). Only the basename is kept and the `.conf` suffix is
782
+ // stripped before the path is rebuilt as `/etc/nginx/conf.d/<name>.conf`. A
783
+ // pure filename (no separators) keeps the previous behavior unchanged.
784
+ export function resolveNginxConfigPath(configName, project) {
785
+ const raw = String(configName || project || '');
786
+ const base = raw.split(/[\\/]/).filter(Boolean).pop() || '';
787
+ const name = base.replace(/\.conf$/i, '') || 'default';
788
+ return `/etc/nginx/conf.d/${name}.conf`;
789
+ }
790
+
791
+ // A1 (#935): parse the write-verification block appended to the deploy_nginx
792
+ // script. The old flow returned ok:true whenever the deploy script exited 0,
793
+ // even when the tee write silently failed — the config file never existed and
794
+ // the tunnel answered 502. The verification block emits explicit markers:
795
+ // DB_NGINX_CONFIG_MISSING=1 — the target config file does not exist
796
+ // DB_NGINX_T=PASS|FAIL — nginx -t verdict, with failure output echoed
797
+ // as `DB_NGINX_T_OUTPUT: ...` lines
798
+ export function parseDeployNginxVerifyOutput(stdout) {
799
+ const text = String(stdout || '');
800
+ const configMissing = /DB_NGINX_CONFIG_MISSING=1/.test(text);
801
+ const nginxTest = (text.match(/^DB_NGINX_T=(\w+)$/m) || [])[1] || '';
802
+ const nginxTestOutput = (text.match(/^DB_NGINX_T_OUTPUT: .*$/gm) || [])
803
+ .map((line) => line.replace(/^DB_NGINX_T_OUTPUT: /, ''))
804
+ .join('\n');
805
+ return { configMissing, nginxTest, nginxTestOutput };
806
+ }
807
+
808
+ // A1 (#935): the deploy verdict. A deploy script exit of 0 alone is NOT proof
809
+ // of success — the tee write can fail silently (broken pipe) and nginx -t can
810
+ // reject the config. Returns ok:false with an explicit, actionable error for
811
+ // any verification failure; a pure function so the verdict is unit-testable.
812
+ export function evaluateDeployNginxVerify(result, verify, configPath) {
813
+ const exitCode = result?.exitCode;
814
+ const writeVerified = exitCode === 0 && !verify.configMissing && verify.nginxTest === 'PASS';
815
+ if (writeVerified) return { ok: true };
816
+ const problems = [];
817
+ if (exitCode !== 0) problems.push(`deploy script exited with code ${exitCode}`);
818
+ if (verify.configMissing) problems.push(`nginx config file ${configPath} was not created (tee write failed)`);
819
+ if (verify.nginxTest !== 'PASS')
820
+ problems.push(`nginx -t did not pass${verify.nginxTestOutput ? ` — ${verify.nginxTestOutput}` : ''}`);
821
+ return {
822
+ ok: false,
823
+ error: `sandbox deploy nginx: configuration write verification failed — ${problems.join('; ')}.`,
824
+ };
825
+ }
826
+
743
827
  export async function deployNginx(
744
828
  workspaceId,
745
829
  { nginxType, port, project, outputDir, nodePort, publicPort, configName },
@@ -874,10 +958,14 @@ fi`;
874
958
  throw new Error(`sandbox deploy nginx: unknown nginxType "${nginxType}". Must be one of: spa, proxy, static`);
875
959
  }
876
960
 
961
+ // A1 (#935): configName is normalized to a bare filename so a path-shaped
962
+ // value can never produce `/etc/nginx/conf.d//root/xxx.conf` again.
963
+ const configPath = resolveNginxConfigPath(configName, project);
964
+
877
965
  const cmd = [
878
966
  resolveScript,
879
967
  `sudo mkdir -p /etc/nginx/conf.d`,
880
- `sudo tee /etc/nginx/conf.d/${configName || project}.conf > /dev/null << 'NGINX_EOF'`,
968
+ `sudo tee ${configPath} > /dev/null << 'NGINX_EOF'`,
881
969
  config,
882
970
  `NGINX_EOF`,
883
971
  `# Resolve symlinks for chmod (chmod does not follow symlinks on Linux)`,
@@ -886,6 +974,11 @@ fi`;
886
974
  `find "$REAL_PROJECT" -type f -path "*/node_modules/.bin/*" -exec chmod +x {} \\; 2>/dev/null || true`,
887
975
  `if pgrep -x nginx > /dev/null 2>&1; then sudo killall -9 nginx 2>/dev/null; sleep 1; fi
888
976
  sudo nginx`,
977
+ `# A1 (#935): verify the config write took effect before reporting success`,
978
+ `NGINX_CONFIG_PATH=${configPath}`,
979
+ `if [ ! -f "$NGINX_CONFIG_PATH" ]; then echo "DB_NGINX_CONFIG_MISSING=1"; fi`,
980
+ `NGINX_T_OUTPUT=$(sudo nginx -t 2>&1 || true)`,
981
+ `if echo "$NGINX_T_OUTPUT" | grep -Eq "syntax is ok|test is successful"; then echo "DB_NGINX_T=PASS"; else echo "DB_NGINX_T=FAIL"; echo "$NGINX_T_OUTPUT" | sed "s/^/DB_NGINX_T_OUTPUT: /"; fi`,
889
982
  ].join('\n');
890
983
 
891
984
  const result = await execOneShot(workspaceId, cmd, username, timeoutMs);
@@ -912,13 +1005,36 @@ fi`;
912
1005
  const driftWarning = tunnelActive ? formatPortDriftWarning(basePort, targetPort) : undefined;
913
1006
  if (driftWarning) warnings.push(driftWarning);
914
1007
 
1008
+ // A1 (#935): verify the config write before reporting success. Any
1009
+ // verification failure returns ok:false with an explicit, actionable error.
1010
+ const verify = parseDeployNginxVerifyOutput(result.stdout);
1011
+ const verdict = evaluateDeployNginxVerify(result, verify, configPath);
1012
+ if (!verdict.ok) {
1013
+ return {
1014
+ ok: false,
1015
+ error: verdict.error,
1016
+ nginxType,
1017
+ port: targetPort,
1018
+ nodePort: effectiveNodePort || undefined,
1019
+ outputPath,
1020
+ projectPath,
1021
+ configPath,
1022
+ exitCode: result.exitCode,
1023
+ stdout: result.stdout,
1024
+ nextStep: 'fix_and_retry',
1025
+ warning: warnings.length > 0 ? warnings.join(' | ') : undefined,
1026
+ };
1027
+ }
1028
+
915
1029
  return {
916
- ok: result.exitCode === 0,
1030
+ ok: true,
917
1031
  nginxType,
918
1032
  port: targetPort,
919
1033
  nodePort: effectiveNodePort || undefined,
920
1034
  outputPath,
921
1035
  projectPath,
1036
+ configPath,
1037
+ verification: { configPath, nginxTest: verify.nginxTest },
922
1038
  exitCode: result.exitCode,
923
1039
  stdout: result.stdout,
924
1040
  nextStep: 'expose_via_devbridge',
@@ -1318,11 +1434,22 @@ export function buildDevbridgeExposeScript(port, expiryHours = DEVBRIDGE_HOST_EX
1318
1434
  // not abort the script.
1319
1435
  `if command -v setsid > /dev/null 2>&1; then setsid nohup devbridge host -p ${port} -e ${expiryHours} > ${hostLog} 2>&1 < /dev/null & else nohup devbridge host -p ${port} -e ${expiryHours} > ${hostLog} 2>&1 < /dev/null & fi`,
1320
1436
  `disown 2>/dev/null || true`,
1321
- `sleep 12`,
1322
- // Port-anchored extraction: a multi-port host prints one "Tunnel URL:" line per
1437
+ `sleep 6`,
1438
+ // Port-anchored extraction (#943): a multi-port host prints one "Tunnel URL:" line per
1323
1439
  // port, so a port-blind `sed | tail -1` can pick another port's URL.
1324
1440
  `TUNNEL_URL=$(grep -oE "https://[A-Za-z0-9_-]+-${port}\\.devbridge-s2\\.hwtunnel\\.com" ${hostLog} | head -1)`,
1325
- `HTTP_CODE=$(curl -s -o /tmp/.db_probe_body -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")`,
1441
+ // A2 (#935): probe with retries + backoff — 502/000 before the gateway is
1442
+ // ready is not a failure; the LAST probe decides reachability. The body is
1443
+ // captured every probe so DB_TUNNEL_BODY reflects the final one (#943).
1444
+ `HTTP_CODE="000"`,
1445
+ `if [ -n "$TUNNEL_URL" ]; then`,
1446
+ ` for i in 1 2 3 4; do`,
1447
+ ` HTTP_CODE=$(curl -s -o /tmp/.db_probe_body -w "%{http_code}" --max-time 10 "$TUNNEL_URL" 2>/dev/null || echo "000")`,
1448
+ ` echo "DB_PROBE_$i=$HTTP_CODE"`,
1449
+ ` if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "304" ]; then break; fi`,
1450
+ ` if [ "$i" != "4" ]; then sleep 5; fi`,
1451
+ ` done`,
1452
+ `fi`,
1326
1453
  `echo "DB_HOST_LOG="`,
1327
1454
  `tail -n 5 ${hostLog}`,
1328
1455
  `echo "DB_TUNNEL_URL=$TUNNEL_URL"`,
@@ -1362,6 +1489,30 @@ export function buildDevbridgeVerifyScript(tunnelUrl) {
1362
1489
  ].join('\n');
1363
1490
  }
1364
1491
 
1492
+ // A2 (#935): parse the probe sequence emitted by buildDevbridgeExposeScript.
1493
+ // Each probe echo is `DB_PROBE_<n>=<code>`; reachability is decided by the
1494
+ // LAST probe — intermediate 502/000 probes are gateway-not-ready noise, not
1495
+ // failures, so they must not leak into the tool's verdict.
1496
+ export function parseDevbridgeProbeSequence(stdout) {
1497
+ const text = String(stdout || '');
1498
+ const probes = [];
1499
+ for (const m of text.matchAll(/^DB_PROBE_(\d+)=(\S*)$/gm)) {
1500
+ probes.push({ attempt: Number(m[1]), httpCode: m[2] });
1501
+ }
1502
+ const finalHttpCode = probes.length > 0 ? probes[probes.length - 1].httpCode : '';
1503
+ return { probes, finalHttpCode };
1504
+ }
1505
+
1506
+ // A2 (#935): the reachability warning must come from the LAST probe's HTTP
1507
+ // status, not from a single early curl — the old single-shot check warned
1508
+ // "Tunnel reachable check returned HTTP (expected 200/304)" while the same
1509
+ // log showed DB_HTTP_CODE=200. 200/304 = no warning; anything else surfaces
1510
+ // as-is.
1511
+ export function formatTunnelReachabilityWarning(httpCode) {
1512
+ if (httpCode === '200' || httpCode === '304') return undefined;
1513
+ return `Tunnel reachable check returned HTTP ${httpCode || '000'} (expected 200/304). The URL may not be serving yet — the final probe decides.`;
1514
+ }
1515
+
1365
1516
  // Parse the raw stdout of buildDevbridgeExposeScript into structured fields.
1366
1517
  // `gatewayTunnelError` marks a URL the s2 gateway itself reports as dead
1367
1518
  // (404 "tunnel not found" / "port not configured") — it can never serve content
@@ -1553,15 +1704,15 @@ export async function exposeTunnel(workspaceId, { port }, username = 'root', tim
1553
1704
  }
1554
1705
  }
1555
1706
 
1707
+ // A2 (#935): the reachability warning uses the FINAL probe's HTTP status —
1708
+ // intermediate 502/000 probes (gateway not ready yet) must not leak into
1709
+ // the verdict, and a sequence of 502/000 → 200 must NOT warn.
1556
1710
  if (parsed.badGateway)
1557
1711
  warnings.push(
1558
1712
  'Tunnel reachable but the gateway reports "bad gateway" — the local service on the exposed port is not serving.',
1559
1713
  );
1560
- if (parsed.httpCode !== '200' && parsed.httpCode !== '304') {
1561
- warnings.push(
1562
- `Tunnel reachable check returned HTTP ${parsed.httpCode} (expected 200/304). The URL may not be serving yet.`,
1563
- );
1564
- }
1714
+ const reachabilityWarning = formatTunnelReachabilityWarning(parsed.httpCode);
1715
+ if (reachabilityWarning) warnings.push(reachabilityWarning);
1565
1716
  const expiresAt =
1566
1717
  parsed.expiryHours !== undefined
1567
1718
  ? new Date(Date.now() + parsed.expiryHours * 3_600_000).toISOString()