huaweicloud-devkit 1.1.2-next.3 → 1.1.2-next.5

package/README.md

@@ -22,13 +22,19 @@ Supports OpenCode, Codex, CodeArts Agent, WorkBuddy, DeepSeek Harness (DSH), Off
 > ```
 >
 > Restore the default registry: `npm config delete registry`
+>
+> **Mirror lag**: npm mirrors (npmmirror, mirrors.huaweicloud.com) may lag behind the official registry for hours after a new release. If install fails with `ETARGET` or you get an older version, install via the official registry instead:
+>
+> ```bash
+> npx --yes --registry=https://registry.npmjs.org huaweicloud-devkit install --target <target>
+> ```
 
 ## Quick Start
 
 > If `--target` is omitted, the installer auto-detects agents on your machine. When multiple agents are detected, **all of them** will be installed. Specify `--target` to control which agent receives the install.
 
 ```bash
-npx --yes huaweicloud-devkit version  # print the installed plugin version per agent
+npx --yes huaweicloud-devkit version  # print CLI version and installed plugin versions per agent
 npx --yes huaweicloud-devkit uninstall --target all --clean-global  # also remove KooCLI + OBS config
 ```
 
@@ -57,14 +63,36 @@ npx --yes huaweicloud-devkit install --target codex
 **Restart the Codex session** after installation.
 
 ```bash
+codex plugin list  # verify huaweicloud-devkit@huaweicloud-devkit is installed and enabled
 npx --yes huaweicloud-devkit doctor --target codex
 npx --yes huaweicloud-devkit status --target codex
 npx --yes huaweicloud-devkit update --target codex
 npx --yes huaweicloud-devkit uninstall --target codex
 ```
 
+Then mention `@huaweicloud-devkit` in Codex or describe your Huawei Cloud task directly.
+
 > **Requires Codex CLI** — the `codex` command must be in PATH. If Codex is installed via WindowsApps (Microsoft Store), use `--target codex-desktop` instead. Run `codex --version` to verify CLI availability.
 
+### Codex Desktop
+
+Use this target when the Codex CLI is unavailable or when Codex is installed through WindowsApps on Windows.
+
+```bash
+npx --yes huaweicloud-devkit install --target codex-desktop
+```
+
+**Restart the Codex Desktop session** after installation.
+
+```bash
+npx --yes huaweicloud-devkit doctor --target codex-desktop
+npx --yes huaweicloud-devkit status --target codex-desktop
+npx --yes huaweicloud-devkit update --target codex-desktop
+npx --yes huaweicloud-devkit uninstall --target codex-desktop
+```
+
+Then mention `@huaweicloud-devkit` in a new Codex Desktop task or describe your Huawei Cloud task directly.
+
 ### CodeArts Agent
 
 ```bash

package/README.zh-CN.md

@@ -22,13 +22,19 @@
 > ```
 >
 > 恢复默认镜像：`npm config delete registry`
+>
+> **镜像滞后**：npm 镜像（npmmirror、mirrors.huaweicloud.com）在新版本发布后可能滞后官方源数小时。若安装报 `ETARGET` 或拿到旧版本，改用官方源安装：
+>
+> ```bash
+> npx --yes --registry=https://registry.npmjs.org huaweicloud-devkit install --target <target>
+> ```
 
 ## 快速开始
 
 > 省略 `--target` 时，安装器会自动检测机器上的 agent，检测到多个时**全部安装**。建议始终指定 `--target` 以明确安装目标。
 
 ```bash
-npx --yes huaweicloud-devkit version  # 查看各 agent 已安装的插件版本
+npx --yes huaweicloud-devkit version  # 查看 CLI 版本和各 agent 已安装的插件版本
 npx --yes huaweicloud-devkit uninstall --target all --clean-global  # 一并删除 KooCLI 与 OBS 配置
 ```
 
@@ -57,14 +63,36 @@ npx --yes huaweicloud-devkit install --target codex
 安装后**重启 Codex 会话**。
 
 ```bash
+codex plugin list  # 验证 huaweicloud-devkit@huaweicloud-devkit 已安装并启用
 npx --yes huaweicloud-devkit doctor --target codex
 npx --yes huaweicloud-devkit status --target codex
 npx --yes huaweicloud-devkit update --target codex
 npx --yes huaweicloud-devkit uninstall --target codex
 ```
 
+随后在 Codex 中提及 `@huaweicloud-devkit`，或直接描述华为云任务。
+
 > **需要 Codex CLI** — `codex` 命令必须在 PATH 中。若 Codex 通过 WindowsApps（Microsoft Store）安装，请使用 `--target codex-desktop` 替代。运行 `codex --version` 验证 CLI 可用性。
 
+### Codex Desktop
+
+当 Codex CLI 不可用，或 Windows 上通过 WindowsApps 安装 Codex 时，使用此目标。
+
+```bash
+npx --yes huaweicloud-devkit install --target codex-desktop
+```
+
+安装后**重启 Codex Desktop 会话**。
+
+```bash
+npx --yes huaweicloud-devkit doctor --target codex-desktop
+npx --yes huaweicloud-devkit status --target codex-desktop
+npx --yes huaweicloud-devkit update --target codex-desktop
+npx --yes huaweicloud-devkit uninstall --target codex-desktop
+```
+
+随后在新的 Codex Desktop 任务中提及 `@huaweicloud-devkit`，或直接描述华为云任务。
+
 ### CodeArts Agent（码道）
 
 ```bash

package/integrations/dsh/hook-plugin.mjs

@@ -65,18 +65,23 @@ function isHuaweiCloudSkill(name) {
 // hcloud command classification (mirrors skill-tracker.js)
 // ══════════════════════════════════════════════════════════════════
 
-const HCLOUD_RE = /(?:^|[;&|]\s*)hcloud(?:\.exe)?\s+(.+)/i;
+const HCLOUD_RE = /(?:^|[;&|]\s*)hcloud(?:\.exe)?\s+([^\s;&|"<>]+(?:\s+[^\s;&|"<>]+){0,3})/i;
 const READ_VERBS = /\b(List|Show|Get|Describe|NovaList|NovaShow)\w*/i;
 const WRITE_VERBS =
   /\b(Create|Delete|Update|Modify|Remove|Revoke|Grant|Attach|Detach|Enable|Disable|Set|Add|Bind|Unbind|Reset|Change|Activate|Deactivate|Register|Unregister|Import|Export|Download|Upload|Copy|Move|Convert|Migrate|Run|Execute|Invoke|Trigger|Deploy|Push|Start|Stop|Restart|Reboot|Suspend|Resume|Terminate|Release|Allocate)\w*/i;
 
-function classifyHcloud(text) {
+export function classifyHcloud(text) {
   const m = HCLOUD_RE.exec(text);
   if (!m) return null;
-  const rest = m[1].trim();
-  const parts = rest.split(/\s+/).filter((p) => !p.startsWith('--'));
-  const cmd = parts.join(' ');
-  if (!cmd) return null;
+  const raw = m[1].trim();
+  if (!raw) return null;
+  const cmdTokens = [];
+  for (const t of raw.split(/\s+/)) {
+    if (t.startsWith('--')) break;
+    cmdTokens.push(t);
+  }
+  if (cmdTokens.length === 0) return null;
+  const cmd = cmdTokens.join(' ');
   if (READ_VERBS.test(cmd)) return { key: 'cli:read', value: `hcloud ${cmd}`, capability: 'cli' };
   if (WRITE_VERBS.test(cmd)) return { key: 'cli:write', value: `hcloud ${cmd}`, capability: 'cli' };
   return { key: 'cli:invoke', value: `hcloud ${cmd}`, capability: 'cli' };

package/integrations/opencode/hooks/skill-tracker.js

@@ -28,7 +28,7 @@ function writeEvent(key, value, extra = {}) {
 
 // ── CLI command classification ────────────────────────────────
 
-const HCLOUD_RE = /(?:^|[;&|]\s*)hcloud(?:\.exe)?\s+(.+)/i;
+const HCLOUD_RE = /(?:^|[;&|]\s*)hcloud(?:\.exe)?\s+([^\s;&|"<>]+(?:\s+[^\s;&|"<>]+){0,3})/i;
 const READ_VERBS = /\b(List|Show|Get|Describe|NovaList|NovaShow)\w*/i;
 const WRITE_VERBS = new RegExp(
   '\\b(Create|Delete|Update|Modify|Remove|Revoke|Grant|Attach|Detach|' +
@@ -42,14 +42,15 @@ const WRITE_VERBS = new RegExp(
 function classifyHcloud(text) {
   const m = HCLOUD_RE.exec(text);
   if (!m) return null;
-  const rest = m[1].trim();
-  const cmdEnd = rest.search(/\s[|&<>;]/);
-  const cmdPart = cmdEnd > -1 ? rest.slice(0, cmdEnd) : rest;
-  const parts = cmdPart
-    .split(/\s+/)
-    .filter((p) => !p.startsWith('--') && !/^\d*>(&?\d*|%devnull)/.test(p) && !/^(&\d+)$/.test(p));
-  const cmd = parts.join(' ');
-  if (!cmd) return null;
+  const raw = m[1].trim();
+  if (!raw) return null;
+  const cmdTokens = [];
+  for (const t of raw.split(/\s+/)) {
+    if (t.startsWith('--')) break;
+    cmdTokens.push(t);
+  }
+  if (cmdTokens.length === 0) return null;
+  const cmd = cmdTokens.join(' ');
   if (READ_VERBS.test(cmd)) return { key: 'cli:read', value: `hcloud ${cmd}` };
   if (WRITE_VERBS.test(cmd)) return { key: 'cli:write', value: `hcloud ${cmd}` };
   return { key: 'cli:invoke', value: `hcloud ${cmd}` };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.2-next.3",
+  "version": "1.1.2-next.5",
   "kooCliVersion": "7.2.12",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",

package/plugins/huaweicloud-core/.claude-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.2-next.3",
+  "version": "1.1.2-next.5",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.codex-plugin/plugin.json

@@ -20,7 +20,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "skills": "./skills/",
-  "version": "1.1.2-next.3",
+  "version": "1.1.2-next.5",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.cursor-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.2-next.3",
+  "version": "1.1.2-next.5",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.hermes-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.2-next.3",
+  "version": "1.1.2-next.5",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/.workbuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.2-next.3",
+  "version": "1.1.2-next.5",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/huaweicloud-safety.py\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/huaweicloud-safety.mjs\"",
             "timeout": 5
           }
         ]
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/huaweicloud-safety.py\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/huaweicloud-safety.mjs\"",
             "timeout": 5
           }
         ]

package/plugins/huaweicloud-core/hooks/huaweicloud-safety.mjs

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+
+import { classifyTextCommand } from '../src/safety-policy.mjs';
+
+const DENY_PREFIX = 'Huawei Cloud safety hook blocked this action: ';
+
+function commandText(toolInput) {
+  if (typeof toolInput === 'string') return toolInput;
+  if (toolInput && typeof toolInput === 'object') {
+    const values = [];
+    for (const key of ['command', 'cmd', 'script', 'args', 'arguments']) {
+      const value = toolInput[key];
+      if (Array.isArray(value)) values.push(value.map(String).join(' '));
+      else if (value !== undefined && value !== null) values.push(String(value));
+    }
+    if (values.length > 0) return values.join('\n');
+    return JSON.stringify(toolInput);
+  }
+  return JSON.stringify(toolInput);
+}
+
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: DENY_PREFIX + reason,
+      },
+    }) + '\n',
+  );
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function main() {
+  const input = readStdin();
+  let data;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    return;
+  }
+
+  const text = commandText(data.tool_input ?? {});
+  const result = classifyTextCommand(text);
+  if (result.decision === 'deny') deny(result.reason);
+}
+
+main();

package/plugins/huaweicloud-core/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "name": "huaweicloud-devkit",
   "id": "huaweicloud-devkit",
   "displayName": "HuaweiCloud DevKit",
-  "version": "1.1.2-next.3",
+  "version": "1.1.2-next.5",
   "family": "bundle-plugin",
   "bundleFormat": "codex",
   "description": "Guide coding agents to use Huawei Cloud safely — KooCLI, APIs, SDKs, 28 MCP tools, skills, and safety guardrails.",

package/plugins/huaweicloud-core/skills/huaweicloud-safety/SKILL.md

@@ -27,7 +27,7 @@ Use this skill before any Huawei Cloud action that may expose secrets, change re
 
 ## Enforcement Layers
 
-- Hooks: `hooks/huaweicloud-safety.py` can block risky tool calls on platforms that support plugin hooks.
+- Hooks: `hooks/huaweicloud-safety.mjs` blocks risky Codex native hook calls without requiring Python; `hooks/huaweicloud-safety.py` remains for Hermes/Python hook compatibility.
 - MCP wrapper: the Node MCP server applies the same safety policy for Codex/OpenCode paths that do not enforce hooks.
 - Skills: this document teaches agents the rule before they act.
 

package/plugins/huaweicloud-core/src/auth/credential-validator.mjs

@@ -0,0 +1,163 @@
+import crypto from 'node:crypto';
+
+import { getProxyDispatcher } from '../proxy/proxy-agent.mjs';
+
+function iamBaseUrl() {
+  return process.env.HW_IAM_ENDPOINT || 'https://iam.myhuaweicloud.com';
+}
+
+function sha256Hex(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+function hmacSha256(key, data) {
+  return crypto.createHmac('sha256', key).update(data).digest('hex');
+}
+
+function urlEncode(str) {
+  const hex = (c) => '%' + (c < 16 ? '0' : '') + c.toString(16).toUpperCase();
+  const noEscape = new Set('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.~'.split(''));
+  let out = '';
+  for (const ch of str) {
+    const c = ch.codePointAt(0);
+    out += noEscape.has(ch) && c < 0x80 ? ch : c < 0x80 ? hex(c) : encodeURIComponent(ch);
+  }
+  return out;
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+/, '') + 'Z';
+}
+
+function signIamRequest(path, query, ak, sk, securitytoken) {
+  const ts = timestamp();
+  const host = new URL(iamBaseUrl()).host;
+
+  const cqs = Object.entries(query)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => `${urlEncode(k)}=${urlEncode(v)}`)
+    .join('&');
+
+  const curi =
+    '/' +
+    path
+      .split('/')
+      .filter(Boolean)
+      .map((s) => urlEncode(s))
+      .join('/') +
+    '/';
+
+  const signedHeaders = securitytoken ? 'host;x-sdk-date;x-security-token' : 'host;x-sdk-date';
+  const canonicalHeaders = securitytoken
+    ? `host:${host}\nx-sdk-date:${ts}\nx-security-token:${securitytoken}\n`
+    : `host:${host}\nx-sdk-date:${ts}\n`;
+
+  const payloadHash = sha256Hex('');
+  const canonicalRequest = ['GET', curi, cqs, canonicalHeaders, signedHeaders, payloadHash].join('\n');
+  const stringToSign = `SDK-HMAC-SHA256\n${ts}\n${sha256Hex(canonicalRequest)}`;
+  const signature = hmacSha256(sk, stringToSign);
+
+  const headers = {
+    host,
+    'x-sdk-date': ts,
+    Authorization: `SDK-HMAC-SHA256 Access=${ak}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+  };
+  if (securitytoken) {
+    headers['x-security-token'] = securitytoken;
+  }
+  return headers;
+}
+
+function projectForRegion(projects, region) {
+  if (region) {
+    const match = projects.find((p) => p && p.name === region && p.id);
+    if (match) return match.id;
+  }
+  return projects.find((p) => p && p.id)?.id || null;
+}
+
+/**
+ * Validate AK/SK by calling IAM KeystoneListProjects (read-only) with
+ * SDK-HMAC-SHA256 request signing. A wrong SK produces an invalid signature,
+ * which IAM rejects with HTTP 401 before any project data is returned.
+ *
+ * Returns { valid, projectId, error, warning }:
+ * - valid: true when IAM verified the signature (or the rejection is not
+ *   authentication-related), false when the credentials are unusable.
+ * - projectId: first project matching `region`, else the first visible project.
+ * - warning: set when credentials passed but project discovery was denied.
+ */
+export async function validateIamCredentials({ ak, sk, securityToken, region, timeoutMs = 15000 } = {}) {
+  if (!ak || !sk) {
+    return { valid: false, projectId: null, error: 'AK and SK are both required for credential validation.' };
+  }
+
+  const base = iamBaseUrl();
+  const path = '/v3/projects';
+  const query = region ? { name: region } : {};
+  const qs = Object.entries(query)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join('&');
+  const url = `${base}${path}${qs ? `?${qs}` : ''}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let resp;
+  try {
+    const headers = signIamRequest(path, query, ak, sk, securityToken);
+    const fetchOpts = { headers, signal: controller.signal };
+    const dispatcher = await getProxyDispatcher(url);
+    if (dispatcher) {
+      fetchOpts.dispatcher = dispatcher;
+      const { fetch: undiciFetch } = await import('undici');
+      resp = await undiciFetch(url, fetchOpts);
+    } else {
+      resp = await fetch(url, fetchOpts);
+    }
+  } catch (error) {
+    return {
+      valid: false,
+      projectId: null,
+      skipped: true,
+      error: `IAM validation request failed (treating credentials as unverified): ${error.message}`,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const text = await resp.text();
+  let data = null;
+  try {
+    data = JSON.parse(text);
+  } catch {}
+
+  if (resp.status === 200) {
+    const projects = Array.isArray(data?.projects) ? data.projects : [];
+    return { valid: true, projectId: projectForRegion(projects, region), error: null, warning: null };
+  }
+
+  if (resp.status === 401) {
+    const msg = data?.error?.message || text.slice(0, 200);
+    return {
+      valid: false,
+      projectId: null,
+      error: `IAM rejected the credentials (HTTP 401: ${msg}). The AK/SK is invalid - check the SK for typos or expired security tokens.`,
+    };
+  }
+
+  if (resp.status === 403) {
+    return {
+      valid: true,
+      projectId: null,
+      error: null,
+      warning: `Credentials signed successfully but project listing was denied (HTTP 403). Continuing without project_id.`,
+    };
+  }
+
+  return {
+    valid: false,
+    projectId: null,
+    skipped: true,
+    error: `Unexpected IAM response (HTTP ${resp.status}): ${text.slice(0, 200)}`,
+  };
+}

package/plugins/huaweicloud-core/src/auth/credentials.mjs

@@ -272,10 +272,14 @@ export function readLastSync() {
   }
 }
 
-export function writeLastSync() {
+export function writeLastSync(metadata = {}) {
   const path = lastSyncPath();
   mkdirSync(dirname(path), { recursive: true });
-  const payload = { ts: Date.now() };
+  const payload = {
+    ts: Date.now(),
+    ...(metadata.kooCliProfile ? { kooCliProfile: String(metadata.kooCliProfile) } : {}),
+    ...(metadata.s1Fingerprint ? { s1Fingerprint: String(metadata.s1Fingerprint) } : {}),
+  };
   writeFileSync(path, JSON.stringify(payload), { encoding: 'utf8', mode: 0o600 });
   ensurePrivateMode(path);
 }

package/plugins/huaweicloud-core/src/auth/project-id.mjs

@@ -0,0 +1,68 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+function hcloudCommand(args) {
+  const bin = process.env.HCLOUD_BIN || 'hcloud';
+  // Test doubles (and exotic setups) may point HCLOUD_BIN at a Node script;
+  // those must be launched through node instead of the shell.
+  if (/\.(mjs|cjs|js)$/i.test(bin) && existsSync(bin)) {
+    return { file: process.execPath, args: [bin, ...args] };
+  }
+  return { file: bin, args };
+}
+
+function runHcloud(args, timeoutMs = 20000) {
+  const { file, args: spawnArgs } = hcloudCommand(args);
+  return spawnSync(file, spawnArgs, {
+    windowsHide: true,
+    stdio: 'pipe',
+    timeout: timeoutMs,
+  });
+}
+
+/**
+ * Resolve the project_id for `region` via IAM KeystoneListProjects using the
+ * credentials already stored in the KooCLI profile, then write it back with
+ * `hcloud configure set --cli-project-id=<id>`. Read-only discovery + local
+ * config write only - no secrets appear in process arguments because the
+ * profile carries the credentials.
+ *
+ * Best-effort by design: any failure returns { ok: false, reason } and never
+ * throws, so callers can stay non-fatal.
+ */
+export function resolveAndApplyProjectId({ region, profile } = {}) {
+  if (!region) return { ok: false, reason: 'region is required' };
+  const profileArgs = profile ? [`--cli-profile=${profile}`] : [];
+  try {
+    const list = runHcloud([
+      'IAM',
+      'KeystoneListProjects',
+      ...profileArgs,
+      `--cli-region=${region}`,
+      `--name=${region}`,
+    ]);
+    if (list.status !== 0) {
+      return { ok: false, reason: `KeystoneListProjects failed (exit ${list.status})` };
+    }
+    let projects = null;
+    try {
+      const parsed = JSON.parse(String(list.stdout || ''));
+      projects = Array.isArray(parsed?.projects) ? parsed.projects : Array.isArray(parsed) ? parsed : null;
+    } catch {
+      return { ok: false, reason: 'could not parse KeystoneListProjects output' };
+    }
+    if (!projects || projects.length === 0) {
+      return { ok: false, reason: `no projects found for region ${region}` };
+    }
+    const match = projects.find((p) => p && p.name === region && p.id) || projects.find((p) => p && p.id);
+    if (!match) return { ok: false, reason: 'project list contained no usable ids' };
+
+    const set = runHcloud(['configure', 'set', ...profileArgs, `--cli-project-id=${match.id}`]);
+    if (set.status !== 0) {
+      return { ok: false, reason: `configure set --cli-project-id failed (exit ${set.status})` };
+    }
+    return { ok: true, projectId: match.id };
+  } catch (error) {
+    return { ok: false, reason: error.message };
+  }
+}