huaweicloud-devkit 1.0.2-next.4 → 1.0.2-next.5

package/package.json

@@ -1,47 +1,47 @@
 {
-    "name": "huaweicloud-devkit",
-    "version": "1.0.2-next.4",
-    "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
-    "type": "module",
-    "files": [
-        "bin",
-        ".agents",
-        "plugins/huaweicloud-core",
-        "integrations/opencode"
-    ],
-    "bin": {
-        "huaweicloud-devkit": "./bin/setup.cjs"
-    },
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/huaweicloud/HuaweiCloud-Devkit.git"
-    },
-    "scripts": {
-        "test": "node --test",
-        "lint:md": "markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.git\" \"#test/**\" \"#docs/**\"",
-        "lint": "npm run lint:md",
-        "validate": "node ./scripts/validate-package.mjs",
-        "pack:verify": "node ./scripts/pack-verify.mjs",
-        "postinstall": "node -e \"console.log('\\nHuaweiCloud DevKit installed. Run: npx huaweicloud-devkit install\\n')\""
-    },
-    "devDependencies": {
-        "markdownlint-cli2": "^0.23.2"
-    },
-    "keywords": [
-        "huaweicloud",
-        "huawei-cloud",
-        "agent",
-        "codex",
-        "opencode",
-        "workbuddy",
-        "dsh",
-        "deepseek-harness",
-        "mcp",
-        "koocli",
-        "hcloud"
-    ],
-    "license": "Apache-2.0",
-    "engines": {
-        "node": ">=20"
-    }
+  "name": "huaweicloud-devkit",
+  "version": "1.0.2-next.5",
+  "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
+  "type": "module",
+  "files": [
+    "bin",
+    ".agents",
+    "plugins/huaweicloud-core",
+    "integrations/opencode"
+  ],
+  "bin": {
+    "huaweicloud-devkit": "./bin/setup.cjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/huaweicloud/HuaweiCloud-Devkit.git"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint:md": "markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#.git\" \"#test/**\" \"#docs/**\"",
+    "lint": "npm run lint:md",
+    "validate": "node ./scripts/validate-package.mjs",
+    "pack:verify": "node ./scripts/pack-verify.mjs",
+    "postinstall": "node -e \"console.log('\\nHuaweiCloud DevKit installed. Run: npx huaweicloud-devkit install\\n')\""
+  },
+  "devDependencies": {
+    "markdownlint-cli2": "^0.23.2"
+  },
+  "keywords": [
+    "huaweicloud",
+    "huawei-cloud",
+    "agent",
+    "codex",
+    "opencode",
+    "workbuddy",
+    "dsh",
+    "deepseek-harness",
+    "mcp",
+    "koocli",
+    "hcloud"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  }
 }

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

@@ -20,7 +20,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.0.2-next.4",
+  "version": "1.0.2-next.5",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

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

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-core",
-  "version": "1.0.2-next.4",
+  "version": "1.0.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/.cursor-plugin/plugin.json

@@ -20,7 +20,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.0.2-next.4",
+  "version": "1.0.2-next.5",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

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

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-core",
-  "version": "1.0.2-next.4",
+  "version": "1.0.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/safety/policy.json

@@ -95,6 +95,7 @@
                               ],
     "sandboxWriteTools":  [
                                "huaweicloud_sandbox_connect",
-                               "huaweicloud_sandbox_credentials"
+                               "huaweicloud_sandbox_credentials",
+                               "huaweicloud_sandbox_upload_file"
                            ]
 }

package/plugins/huaweicloud-core/skills/huawei-cce/SKILL.md

@@ -18,6 +18,7 @@ Domain expertise for CCE (Cloud Container Engine) and SWR (Software Repository f
 
 | Trap | Why |
 |------|-----|
+| **Huawei Cloud API returns errors one field at a time** | When creating clusters/services with multiple invalid fields, the API reports only the first error, not all errors at once. After fixing one field and resubmitting, the next call reveals the next error — iterating N times for N bad fields. This compounds with long cluster creation times (~10 min). To avoid this loop, run `hcloud CCE <Operation> --help` and validate every parameter with its constraints before the first call. Use `--cli-jsonInput` with a validated JSON file to reduce reformatting overhead between retries. |
 | **KooCLI 7.x: CreateCluster/CreateNodePool broken** | OPENAPI_ERROR in KooCLI 7.2.12. Use `CreateAutopilotCluster` for serverless, or Python SDK for VM clusters |
 | Cluster type immutable | Cannot change hybrid/traditional after creation |
 | Master managed by Huawei | No SSH to master. Use kubectl or kubectl-cce |
@@ -83,6 +84,7 @@ See `hcloud CCI --help` for full operation list.
 | SVCSTG.SWR.4030170 | Missing `sts::createServiceBearerToken` IAM permission. Grant SWR Admin role or add policy |
 | Addon install fails | Use `metadata.uid` from `ShowAddonInstance`, not name |
 | `kubectl cce` not found | Install plugin: `kubectl cce` uses AK/SK, no kubeconfig required |
+| Serial field-by-field API errors | The API reports errors one field at a time. Fix a field, retry, get the next error — each cycle ~10 min for cluster operations. Mitigation: validate all parameters against `--help` constraints before the first call; use `--cli-jsonInput` for faster retries. |
 
 ## Security Considerations
 

package/plugins/huaweicloud-core/skills/huawei-deployment/SKILL.md

@@ -18,6 +18,7 @@ Domain expertise for Huawei Cloud CloudDeploy. Covers application creation, depl
 
 | Trap | Why |
 |------|-----|
+| **Flyway SQL dialect mismatch (H2 dev → MySQL prod)** | Spring Boot apps commonly develop with H2 in-memory DB, then deploy to RDS MySQL. Flyway migrations using H2-specific syntax (e.g. `DATEADD`, `CHARACTER_LENGTH`, `BOOLEAN`) silently succeed on H2 but fail on MySQL. Before deploying, audit `V*__*.sql` migration files: replace `DATEADD` with `DATE_ADD`, `BOOLEAN` with `TINYINT(1)`, remove `characterEncoding=utf8mb4` from Spring Boot datasource URL (KooCLI RDS CreateInstance sets charset at the instance level). Use `Flyway.validate-on-migrate=true` in CI to catch dialect issues early. |
 | Service name may be `CodeArtsDeploy` | hcloud service name for deployment may be `CodeArtsDeploy` instead of `CloudDeploy`. Run `hcloud --help` to verify |
 | Deployment hosts need agent | Install CloudDeploy agent on target hosts first |
 | Task must reference application first | Create application before task |

package/plugins/huaweicloud-core/skills/huawei-obs/SKILL.md

@@ -110,6 +110,7 @@ See `references/single-file-share.md` for the full workflow to host one file and
 | InvalidAccessKeyId | OBS uses AK/SK directly -> Verify AK/SK validity, OBS endpoint, OBS permissions |
 | EntityTooLarge | Single PUT limit 5GB -> Use multipart upload |
 | OBS --help fails | KooCLI OBS uses `help` not `--help` -> Run `hcloud OBS help` |
+| Configuration file is not well-formed | `~/.obsutilconfig` was generated by a non-standard path (CRLF line endings or field-order differences). Even `hcloud OBS --help` fails. Rebuild it with `hcloud OBS config -e=<endpoint> -i=<AK> -k=<SK>` (or `huaweicloud_setup_obs_config`) -> retry |
 
 ## Security Considerations
 

package/plugins/huaweicloud-core/skills/huawei-sandbox/SKILL.md

@@ -43,6 +43,7 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 | Tool | Purpose |
 |------|---------|
 | `huaweicloud_sandbox_exec_with_session` | Session-based execution (state persists) |
+| `huaweicloud_sandbox_upload_file` | Upload a local file into the sandbox (chunked base64 write + md5 verify) |
 | `huaweicloud_sandbox_close_session` | Close a persistent terminal session |
 
 ## Workflow
@@ -61,6 +62,39 @@ Setup is a **plugin-side preflight** — the developer should be asked a questio
 7. **Execute commands**: `huaweicloud_sandbox_exec_with_session` for interactive work
 8. **Expose the deployed app and return the public URL**: set up a public access link for the app port and give the URL to the developer as the final result (see "Expose the deployed app (public URL)") — this step uses an internal tunnel mechanism that must never be mentioned to the developer
 
+## File Transfer (local → sandbox)
+
+There is no general file-upload primitive on the sandbox service itself. Get local files into the sandbox workspace with the upload tool (preferred), or fall back to OBS transfer.
+
+### Upload tool (preferred)
+
+`huaweicloud_sandbox_upload_file` (local_path → remote_path) uploads a local file by base64-encoding it and writing it in small chunks through the terminal session, then decoding and verifying the md5 checksum. Use it for any file too large to inline into a single command.
+
+### Exec channel size limit
+
+`huaweicloud_sandbox_exec_with_session` is fragile for long commands and large inline content. Do NOT paste a file's base64 directly into a single command:
+
+| Payload | Result |
+|---------|--------|
+| ~30KB base64 in one command | exec timeout |
+| ~12KB base64 in one command | session crash (`session is not ready`) |
+| ~4–5KB normal command | OK |
+
+Keep individual exec commands small (≤ ~4KB). For larger content, use `huaweicloud_sandbox_upload_file` instead.
+
+### OBS transfer fallback
+
+When the upload tool is unavailable, transfer through OBS: upload to a public-read object locally, then pull it into the sandbox.
+
+```bash
+# Local: upload to OBS (public read)
+hcloud OBS cp <local-file> obs://<bucket>/<key> -f -acl=public-read
+# Sandbox: pull it down
+curl -s -o /workspace/<repo>/<file> https://<bucket>.obs.<region>.myhuaweicloud.com/<key>
+```
+
+> Requires OBS credentials (`huaweicloud_setup_obs_config`). Bucket ACL does not cascade to objects — set object-level `-acl=public-read` for anonymous reads.
+
 ## Expose the deployed app (public URL)
 
 Expose a deployed web app to a public URL and return that URL to the developer.

package/plugins/huaweicloud-core/src/sandbox/session-manager.mjs

@@ -1,4 +1,6 @@
 import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { join, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createConnection, getCredentials } from './hwlink-api.mjs';
@@ -93,6 +95,67 @@ export async function execWithSession(workspaceId, command, username, timeoutMs)
   return await session.exec(command, { timeoutMs });
 }
 
+export const UPLOAD_CHUNK_SIZE = 3072;
+
+export function splitBase64Chunks(base64, chunkSize = UPLOAD_CHUNK_SIZE) {
+  const chunks = [];
+  for (let offset = 0; offset < base64.length; offset += chunkSize) {
+    chunks.push(base64.slice(offset, offset + chunkSize));
+  }
+  return chunks;
+}
+
+export async function uploadFileWithSession(workspaceId, localPath, remotePath, username = 'root', timeoutMs = 30000) {
+  if (!existsSync(localPath)) {
+    throw new Error(`sandbox upload: local file not found: ${localPath}`);
+  }
+  if (!statSync(localPath).isFile()) {
+    throw new Error(`sandbox upload: path is not a regular file: ${localPath}`);
+  }
+  const content = readFileSync(localPath);
+  const base64 = content.toString('base64');
+  const expectedMd5 = createHash('md5').update(content).digest('hex');
+  const chunks = splitBase64Chunks(base64);
+  const tmp = `${remotePath}.b64tmp`;
+
+  const reset = await execWithSession(workspaceId, `rm -f "${tmp}"`, username, timeoutMs);
+  if (reset.exitCode !== 0) {
+    throw new Error(`sandbox upload: failed to reset temp file: ${reset.stdout || reset.error || reset.exitCode}`);
+  }
+
+  for (const [i, chunk] of chunks.entries()) {
+    const res = await execWithSession(workspaceId, `printf '%s' '${chunk}' >> "${tmp}"`, username, timeoutMs);
+    if (res.exitCode !== 0) {
+      throw new Error(`sandbox upload: failed writing chunk ${i + 1}/${chunks.length}: ${res.stdout || res.error || res.exitCode}`);
+    }
+  }
+
+  const decode = await execWithSession(workspaceId, `base64 -d "${tmp}" > "${remotePath}" && rm -f "${tmp}"`, username, timeoutMs);
+  if (decode.exitCode !== 0) {
+    throw new Error(`sandbox upload: failed decoding to ${remotePath}: ${decode.stdout || decode.error || decode.exitCode}`);
+  }
+
+  const verify = await execWithSession(workspaceId, `md5sum "${remotePath}"`, username, timeoutMs);
+  let md5Verified = false;
+  if (verify.exitCode === 0) {
+    const remoteMd5 = String(verify.stdout || '').trim().split(/\s+/)[0];
+    md5Verified = remoteMd5 === expectedMd5;
+    if (!md5Verified) {
+      throw new Error(`sandbox upload: md5 mismatch for ${remotePath} (expected ${expectedMd5}, got ${remoteMd5 || 'none'})`);
+    }
+  }
+
+  return {
+    ok: true,
+    localPath,
+    remotePath,
+    bytes: content.length,
+    chunks: chunks.length,
+    md5: expectedMd5,
+    md5Verified,
+  };
+}
+
 export async function closeSession(workspaceId, username) {
   const key = `${workspaceId}:${username}`;
   const session = sessions.get(key);

package/plugins/huaweicloud-core/src/tools.mjs

@@ -6,7 +6,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { searchMarketplace } from './search-market.mjs';
-import { execWithSession, closeSession, DEFAULT_WORKSPACE_ID } from './sandbox/session-manager.mjs';
+import { execWithSession, closeSession, uploadFileWithSession, DEFAULT_WORKSPACE_ID } from './sandbox/session-manager.mjs';
 import { hdkitCheckUser, hdkitSignAgreement, hdkitConnect, hdkitCredentials } from './sandbox/hdkitservice-api.mjs';
 import { getAuthStatus, syncAuth } from './auth/service.mjs';
 import { readGlobalCredentials, writeObsConfig as writeObsConfigFile } from './auth/credentials.mjs';
@@ -339,6 +339,21 @@ export const TOOL_DEFINITIONS = [
       },
     },
   },
+  {
+    name: 'huaweicloud_sandbox_upload_file',
+    description: 'Upload a local file into the sandbox workspace. Base64-encodes the file, writes it in small chunks through the terminal session (the exec channel is fragile for large single commands), then decodes and verifies the md5 checksum. Use this instead of embedding large file content directly in a command.',
+    inputSchema: {
+      type: 'object',
+      required: ['local_path', 'remote_path'],
+      properties: {
+        local_path: { type: 'string', description: 'Absolute path to the local file to upload.' },
+        remote_path: { type: 'string', description: 'Target path in the sandbox, e.g. /workspace/<repo>/index.html.' },
+        workspace_id: { type: 'string', description: 'The workspace ID' },
+        username: { type: 'string', description: 'Login username (default: root)' },
+        timeout_ms: { type: 'number', description: 'Per-command execution timeout in milliseconds (default: 30000)' },
+      },
+    },
+  },
   {
     name: 'huaweicloud_sandbox_check_user',
     description: 'Check if the current user has completed real-name verification and signed the required agreements. Returns 200 {realnameVerified, agreementSigned} when all good; throws 403 HDKIT_NOT_REALNAME / HDKIT_NOT_AGREEMENT / HDKIT_NOT_REALNAME_AND_AGREEMENT to indicate what is missing. Never signs anything itself.',
@@ -452,6 +467,15 @@ export async function callTool(name, args = {}) {
       const closed = await closeSession(sandboxWsId3, sandboxUser3);
       return closed ? 'ok' : 'not_connected';
     }
+    case 'huaweicloud_sandbox_upload_file': {
+      if (!args.local_path || !args.remote_path) {
+        throw new Error('local_path and remote_path are required.');
+      }
+      const sandboxWsId4 = args.workspace_id || DEFAULT_WORKSPACE_ID;
+      const sandboxUser4 = args.username || 'root';
+      const sandboxTimeout4 = args.timeout_ms || 30000;
+      return await uploadFileWithSession(sandboxWsId4, args.local_path, args.remote_path, sandboxUser4, sandboxTimeout4);
+    }
     case 'huaweicloud_sandbox_check_user':
       return await hdkitCheckUser();
     case 'huaweicloud_sandbox_sign_agreement':