monacloud-mcp 0.3.2 → 0.4.1

package/README.md

@@ -4,6 +4,29 @@
 
 Human đăng ký, duyệt chi phí, thêm DNS khi cần, nạp tiền và cung cấp OTP/KYC khi bắt buộc. Các bước tạo tài nguyên, đọc trạng thái, cấu hình webhook, test và deploy được thiết kế để AI agent làm qua MCP.
 
+## 0.4.0 — Đưa thư mục hiện tại lên web
+
+Prompt Claude Code: **“Đưa dự án này lên MONA Cloud, dùng thư mục hiện tại”**.
+
+AI làm 99%: `cloud_app_detect(local_dir)` offline → đọc host và giá → sandbox nếu cần host mới → hỏi duyệt chi phí một lần → `cloud_app_create(local_dir)` → kiểm và trả URL. Có domain riêng thì `cloud_app_domain_add` và hướng dẫn CNAME. Human đăng ký MONA Pass qua device flow và nạp ví khi hết credit 20k.
+
+| Tool | Đầu vào / hành vi 0.4.0 |
+|---|---|
+| `cloud_app_detect` | `local_dir`: stack, port, start, Dockerfile, build_type, tên env từ `.env.example`; không mạng |
+| `cloud_app_create` | `local_dir`, `name?`, `build_type?`, `env?`, `port?`, `domain?`: ZIP → tạo source=upload → multipart → poll → `{url, app_id, build, seconds}` |
+| `cloud_app_deploy` | `app_id`, `local_dir?`: có thư mục thì ZIP mới, upload, chờ rồi deploy; bỏ thư mục để dùng bản cũ |
+| `cloud_app_domain_add` | `app_id`, `host`: gắn domain và nhận hướng dẫn CNAME |
+
+```text
+cloud_app_detect({ local_dir: "/absolute/path/to/project" })
+cloud_app_create({ local_dir: "/absolute/path/to/project", name: "shop", sandbox: true })
+// Sau khi đã duyệt chi phí
+cloud_app_create({ local_dir: "/absolute/path/to/project", name: "shop" })
+cloud_app_deploy({ app_id: "<app_id>", local_dir: "/absolute/path/to/project" })
+```
+
+ZIP tối đa 80 MiB, loại `.env*`, `*.pem`, `.git`, `node_modules` và symlink; áp dụng `.gitignore`/`.dockerignore`. `dist` được giữ mặc định. Git vẫn dùng `repo_url` như trước. [Hợp đồng upload, giới hạn và cách tiếp tục job](docs/local-deploy.md).
+
 ## Yêu cầu
 
 - Node.js 20 trở lên.
@@ -160,7 +183,7 @@ cloud_services_list({ sandbox: true })
 
 - `monacloud://llms`: mô tả máy đọc của toàn stack MONA Cloud.
 - `monacloud://status`: health tổng hợp MONA Pass, Billing, compute MONA Cloud, MONA Pay và MONA Mail (`/v1/healthz`).
-- Prompt `dung-app-ban-hang-monacloud`: chuỗi VPS → database → VA/QR → webhook → deploy, đọc giá, duyệt chi phí rồi tạo; repo git dùng `cloud_app_create` (đang mở).
+- Prompt `dung-app-ban-hang-monacloud`: chuỗi VPS → database → VA/QR → webhook → deploy, đọc giá, duyệt chi phí rồi tạo; dự án local dùng `cloud_app_detect` rồi `cloud_app_create(local_dir)`; git dùng `repo_url`.
 - Prompt `gui-mail-otp-monamail(app_name?, framework?, domain?)`: account → thử onboarding → domain/DNS → verify → API key → `.env` → SDK OTP → webhook bounced; chỉ dừng ở bước thêm DNS hoặc nạp tiền.
 
 ## Spend guard và lỗi cho AI
@@ -251,7 +274,7 @@ Test dùng Node built-in, MCP transport thật qua stdio, process con và mock H
 | `cloud_app_domain_add` / `cloud_app_logs` / `cloud_app_delete` | CNAME domain, log build, xoá app; **đang mở** |
 | `cloud_app_host_list` | Xem host và tài nguyên/chi phí; **đang mở** |
 
-15 tool mới có 15 alias `vibecloud_` tương ứng. Tổng với MONA Pay 0.5.5 đang có: **133 tool**, gồm 20 Mail và 26 alias compute. Package/MCP binary version: **0.3.0**.
+15 tool mới có 15 alias `vibecloud_` tương ứng. Tổng với MONA Pay 0.5.5 đang có: **135 tool** ở 0.4.0, gồm 20 Mail và 27 alias compute (thêm cloud_app_detect/vibecloud_app_detect). Package/MCP binary version: **0.4.0**.
 
 ```text
 cloud_plan_list({ ram_gb: 4 })

package/STATUS.md

@@ -1,4 +1,34 @@
-# STATUS — monacloud-mcp 0.3.0
+# STATUS — monacloud-mcp 0.4.0
+
+Updated: 2026-09-05 (Asia/Ho_Chi_Minh)
+
+## Brief deploy local — hoàn tất offline
+
+- `cloud_app_detect(local_dir)` và alias `vibecloud_app_detect`: Node/Next/Vite/Python/PHP/static, port/start/Dockerfile/build_type, tên env từ `.env.example`; không mạng, không chạy code dự án.
+- `cloud_app_create(local_dir)`: ZIP nguồn local trước HTTP, tạo `{source:"upload",name,build_type,env,port,domain?}`, nhận `{id,upload_url,max_bytes}`, multipart `archive` + `build_path`, poll job, trả URL/app_id/build/seconds. Giữ luồng git và mặc định 0.3.x.
+- ZIP deflate/UTF-8/UNIX mode, tối đa 83,886,080 bytes (80 MiB); loại node_modules/.git/.env*/pem/symlink, áp dụng `.gitignore` root+nested và `.dockerignore` root. Giữ dist mặc định để không phá Dockerfile COPY output. Không cần dependency hoặc shell ZIP.
+- Local create chưa có host/preview: tự sandbox, trả estimate + needs_cost_approval; agent hỏi human duyệt một lần rồi gọi thật. Preview cùng cấu hình giữ tối đa 10 phút trong MCP session. Host chưa ready và balance thiếu đều chặn tạo thật; sandbox bỏ Billing.
+- Redeploy có local_dir: zip mới, xác minh source=upload, upload và chờ job trước POST deploy. Không local_dir: dùng bản đã upload. 409 upload_required, upload/build lỗi và timeout giữ hướng dẫn tiếp tục app/job hiện có.
+- Upload dùng đúng endpoint cùng origin, chặn redirect, không tự set multipart Content-Type, kiểm thêm max_bytes backend; error sau create giữ app_id để không tạo trùng.
+- Prompt, llms, agent guide và README theo luồng AI làm 99%; duyệt chi phí một lần, trả URL, domain+CNAME, MONA Pass/device flow và nạp ví khi hết credit 20k.
+- Package/binary/MCP handshake 0.4.0; 135 tool, 2 resource, 2 prompt. Không đổi dependency, không publish, không gọi API production.
+
+## Gate bàn giao
+
+```text
+mcp: npm test → 47 tests, 47 pass, 0 fail, 0 skip (gồm TypeScript build)
+cli: npm test → 36 tests, 36 pass, 0 fail, 0 skip
+```
+
+Test gồm ZIP/CRC/binary/UTF-8/executable bits/ignore/secrets, archive vượt 80 MiB trước HTTP, mock multipart round-trip với native Request/FormData, backend max_bytes/URL không hợp lệ, sandbox/estimate, upload/build lỗi, wait=false/timeout, source mismatch/redeploy và CLI executable → MCP thật → HTTP mock. Test launcher đặt NODE_USE_SYSTEM_CA=0 riêng cho test child vì Node 22 thừa kế biến 1 bị SIGSEGV khi đọc macOS Keychain trong sandbox; runtime sản phẩm không đổi cấu hình CA.
+
+Chi tiết hợp đồng và giới hạn: [docs/local-deploy.md](docs/local-deploy.md). Chỉ kiểm chứng offline/mock theo brief; backend upload đang được triển khai song song, chưa kiểm thử production.
+
+CODEX DONE
+
+---
+
+# Lịch sử — monacloud-mcp 0.3.0
 
 Updated: 2026-09-05 (Asia/Ho_Chi_Minh)
 

package/dist/clients.js

@@ -66,8 +66,28 @@ export class CloudClients {
                 : nextStep, { status: error.status, details: error.details, requestId: error.requestId });
         }
     }
-    balance() {
-        return this.billing('/v1/balance');
+    async balance() {
+        try {
+            return await this.billing('/v1/balance');
+        }
+        catch (error) {
+            // Ví local (token vc_live_* hoặc tài khoản chưa chuyển ví chung): billing trả 401/403/404 → đọc số dư qua compute /api/me.
+            const status = error instanceof CloudError ? error.status ?? 0 : 0;
+            if (!(error instanceof CloudError) || ![401, 403, 404, 502, 503].includes(status))
+                throw error;
+            const root = asObject(unwrapData(await this.vibecloud('/api/me')));
+            const me = asObject(root.user ?? root); // compute trả {user:{credit_vnd, promo_credit_vnd, total_credit_vnd}}
+            const balanceVnd = me.total_credit_vnd !== undefined
+                ? Number(me.total_credit_vnd)
+                : Number(me.credit_vnd ?? me.balance_vnd ?? 0) + Number(me.promo_credit_vnd ?? 0);
+            return {
+                balance_vnd: Number.isFinite(balanceVnd) ? balanceVnd : 0,
+                currency: 'VND',
+                wallet: 'local',
+                source: '/api/me',
+                note: 'Số dư ví local MONA Cloud compute (billing.monacloud.vn không nhận token này). Nạp tại console → ví. / Local compute wallet balance.',
+            };
+        }
     }
     ledger(cursor, limit = 50) {
         return this.billing('/v1/ledger', { query: { cursor, limit } });

package/dist/compute.d.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CloudClients } from './clients.js';
 type Row = Record<string, unknown>;
-export declare const APP_FLOW = "Khi user n\u00F3i \"deploy repo\", d\u00F9ng cloud_app_create (app t\u1EEB git \u0111\u00E3 live: repo public \u2192 URL https). \u0110\u1ECDc cloud_app_host_list, cloud_prices/cloud_packages v\u00E0 cloud_balance; n\u1EBFu ch\u01B0a c\u00F3 app host th\u00EC cloud_app_create sandbox=true tr\u01B0\u1EDBc \u0111\u1EC3 l\u1EA5y \u01B0\u1EDBc t\u00EDnh. \u0110\u1ECDc \u2192 \u01B0\u1EDBc t\u00EDnh VND \u2192 h\u1ECFi duy\u1EC7t n\u1EBFu ch\u01B0a \u0111\u01B0\u1EE3c duy\u1EC7t \u2192 l\u00E0m th\u1EADt \u2192 poll t\u1EDBi done/succeeded \u2192 ki\u1EC3m URL. Kh\u00F4ng g\u1ECDi agent_deploy cho repo git. / Deploy a repository with cloud_app_create; inspect, estimate, obtain approval, then deploy.";
+export declare const APP_FLOW = "AI l\u00E0m 99%: cloud_app_detect(local_dir) offline \u2192 cloud_app_host_list, cloud_prices/cloud_packages/cloud_plan_list v\u00E0 cloud_balance \u2192 cloud_app_create(local_dir, sandbox=true) n\u1EBFu ch\u01B0a c\u00F3 app host \u0111\u1EC3 \u01B0\u1EDBc t\u00EDnh chi ph\u00ED gi\u1EDD/g\u00F3i \u2192 h\u1ECFi human m\u1ED9t l\u1EA7n duy\u1EC7t chi ph\u00ED n\u1EBFu ch\u01B0a \u0111\u01B0\u1EE3c duy\u1EC7t \u2192 cloud_app_create(local_dir, sandbox=false) \u2192 poll t\u1EDBi done/succeeded \u2192 ki\u1EC3m v\u00E0 tr\u1EA3 URL. N\u1EBFu human c\u00F3 domain: cloud_app_domain_add v\u00E0 h\u01B0\u1EDBng d\u1EABn CNAME t\u1EEB API. Human \u0111\u0103ng k\u00FD MONA Pass b\u1EB1ng device flow, n\u1EA1p ti\u1EC1n khi h\u1EBFt credit 20k; AI l\u00E0m c\u00E1c b\u01B0\u1EDBc c\u00F2n l\u1EA1i. App git cloud_app_create(repo_url) \u0111\u00E3 live; kh\u00F4ng g\u1ECDi agent_deploy cho deploy d\u1EF1 \u00E1n. / Detect locally, estimate, obtain cost approval once, upload and deploy, return URL, then attach an optional domain.";
 export declare function rows(value: unknown, key: string): Row[];
 export declare function planEstimate(clients: CloudClients, code: string, cycle?: string): Promise<{
     plan: Row;

package/dist/compute.js

@@ -2,7 +2,9 @@ import { z } from 'zod';
 import { CloudError, runTool } from './errors.js';
 import { unwrapData } from './http.js';
 import { finishAppJob } from './jobs.js';
-export const APP_FLOW = 'Khi user nói "deploy repo", dùng cloud_app_create (app từ git đã live: repo public → URL https). Đọc cloud_app_host_list, cloud_prices/cloud_packages và cloud_balance; nếu chưa có app host thì cloud_app_create sandbox=true trước để lấy ước tính. Đọc → ước tính VND → hỏi duyệt nếu chưa được duyệt → làm thật → poll tới done/succeeded → kiểm URL. Không gọi agent_deploy cho repo git. / Deploy a repository with cloud_app_create; inspect, estimate, obtain approval, then deploy.';
+import { detectProject } from './local.js';
+import { localAppTools } from './local-app.js';
+export const APP_FLOW = 'AI làm 99%: cloud_app_detect(local_dir) offline → cloud_app_host_list, cloud_prices/cloud_packages/cloud_plan_list và cloud_balance → cloud_app_create(local_dir, sandbox=true) nếu chưa có app host để ước tính chi phí giờ/gói → hỏi human một lần duyệt chi phí nếu chưa được duyệt → cloud_app_create(local_dir, sandbox=false) → poll tới done/succeeded → kiểm và trả URL. Nếu human có domain: cloud_app_domain_add và hướng dẫn CNAME từ API. Human đăng ký MONA Pass bằng device flow, nạp tiền khi hết credit 20k; AI làm các bước còn lại. App git cloud_app_create(repo_url) đã live; không gọi agent_deploy cho deploy dự án. / Detect locally, estimate, obtain cost approval once, upload and deploy, return URL, then attach an optional domain.';
 const sandbox = z.boolean().optional().describe('Thử 0đ, không tạo hạ tầng thật / Sandbox, no charge');
 const id = z.string().trim().min(1).max(255);
 const planCode = z.string().trim().min(2).max(64);
@@ -90,11 +92,22 @@ export function registerComputeTools(server, clients) {
         const result = await clients.vibecloud(path, { ...options, ...(isSandbox ? { headers: { 'X-Vibecloud-Sandbox': '1' } } : {}) });
         return isSandbox ? { ...(Array.isArray(result) ? { items: result } : object(result)), sandbox: true } : result;
     };
-    register('cloud_app_create', appNotice + APP_FLOW, z.object({ repo_url: repo, branch: gitPath.default('main'), build_type: z.enum(['dockerfile', 'nixpacks', 'static']).default('dockerfile'), dockerfile: gitPath.default('Dockerfile'), env: env.default({}), domain: domain.optional(), app_host_id: id.optional(), port: z.number().int().min(1).max(65535).default(3000), sandbox, ...poll }).strict(), async ({ sandbox: requested, wait, interval_sec, timeout_sec, ...body }) => finishAppJob(clients, await clients.guardedVibecloud('/api/apps', { method: 'POST', body }, requested), clients.sandboxEnabled(requested), wait, interval_sec, timeout_sec));
+    const localDir = z.string().min(1).max(4096).refine((value) => value.trim().length > 0 && !/[\x00-\x1f]/.test(value), 'local_dir không hợp lệ.');
+    const local = localAppTools(clients);
+    register('cloud_app_detect', 'Nhận diện Node/Next/Vite/Python/PHP/static, port, start, Dockerfile, build_type và tên biến .env.example; hoàn toàn offline, không thực thi code dự án. / Detect a local app without network.', z.object({ local_dir: localDir }).strict(), ({ local_dir }) => detectProject(local_dir));
+    register('cloud_app_create', appNotice + APP_FLOW, z.object({ local_dir: localDir.optional(), name: z.string().trim().min(1).max(80).optional(), repo_url: repo.optional(), branch: gitPath.optional(), build_type: z.enum(['dockerfile', 'nixpacks', 'static']).optional(), dockerfile: gitPath.optional(), env: env.default({}), domain: domain.optional(), app_host_id: id.optional(), port: z.number().int().min(1).max(65535).optional(), sandbox, ...poll }).strict()
+        .refine((args) => Boolean(args.local_dir) !== Boolean(args.repo_url), 'Chọn đúng một local_dir hoặc repo_url.')
+        .refine((args) => !args.local_dir || (!args.branch && !args.app_host_id && (!args.dockerfile || args.dockerfile === 'Dockerfile')), 'Upload local dùng Dockerfile ở root; branch/app_host_id chỉ dùng cho git.'), async (args) => {
+        if (args.local_dir)
+            return local.create(args);
+        const { sandbox: requested, wait, interval_sec, timeout_sec, local_dir, name, ...fields } = args;
+        const body = { ...fields, branch: fields.branch || 'main', build_type: fields.build_type || 'dockerfile', dockerfile: fields.dockerfile || 'Dockerfile', port: fields.port || 3000 };
+        return finishAppJob(clients, await clients.guardedVibecloud('/api/apps', { method: 'POST', body }, requested), clients.sandboxEnabled(requested), wait, interval_sec, timeout_sec);
+    });
     register('cloud_app_list', appNotice + 'Liệt kê app trước khi tạo để tránh trùng. / List apps.', z.object({ sandbox }).strict(), ({ sandbox }) => compute('/api/apps', {}, sandbox));
     register('cloud_app_host_list', appNotice + 'Đọc app host; chưa có host thì sandbox cloud_app_create trước để ước tính. / List app hosts.', z.object({ sandbox }).strict(), ({ sandbox }) => compute('/api/app-hosts', {}, sandbox));
     register('cloud_app_get', appNotice + 'Đọc status, URL, lần deploy và app host. / Inspect app.', appId, ({ app_id, sandbox }) => compute(`/api/apps/${encodeURIComponent(app_id)}`, {}, sandbox));
-    register('cloud_app_deploy', appNotice + 'Deploy lại sau khi đọc app/log và được duyệt; poll job tới kết quả. / Redeploy and poll.', appId.extend(poll), async ({ app_id, sandbox, wait, interval_sec, timeout_sec }) => finishAppJob(clients, await clients.guardedVibecloud(`/api/apps/${encodeURIComponent(app_id)}/deploy`, { method: 'POST' }, sandbox), clients.sandboxEnabled(sandbox), wait, interval_sec, timeout_sec));
+    register('cloud_app_deploy', appNotice + 'App upload: local_dir đóng ZIP mới → upload → chờ job → deploy; bỏ local_dir để redeploy bản đã upload. / Redeploy uploaded source or a git app and poll.', appId.extend({ local_dir: localDir.optional(), ...poll }), async (args) => args.local_dir ? local.deploy(args) : finishAppJob(clients, await clients.guardedVibecloud(`/api/apps/${encodeURIComponent(args.app_id)}/deploy`, { method: 'POST' }, args.sandbox), clients.sandboxEnabled(args.sandbox), args.wait, args.interval_sec, args.timeout_sec));
     register('cloud_app_env_set', appNotice + 'Thay toàn bộ env sau khi được duyệt, gửi đầy đủ map cần giữ; không log secret. Gọi cloud_app_deploy sau đó để áp dụng. / Set app environment.', appId.extend({ env }), ({ app_id, env, sandbox }) => compute(`/api/apps/${encodeURIComponent(app_id)}/env`, { method: 'PUT', body: { env } }, sandbox));
     register('cloud_app_domain_add', appNotice + 'Thêm domain đã được duyệt, trả hướng dẫn CNAME từ API; chờ DNS trước kiểm HTTPS. / Attach custom domain.', appId.extend({ host: domain }), ({ app_id, host, sandbox }) => compute(`/api/apps/${encodeURIComponent(app_id)}/domains`, { method: 'POST', body: { host } }, sandbox));
     register('cloud_app_logs', appNotice + 'Đọc tối đa 500 dòng log; có thể chứa secret, không đưa nguyên log ra công khai. / Read deployment logs.', appId.extend({ deployment: id.optional() }), ({ app_id, deployment, sandbox }) => compute(`/api/apps/${encodeURIComponent(app_id)}/logs`, { query: { deployment } }, sandbox));

package/dist/http.js

@@ -27,9 +27,11 @@ export function apiError(response, body) {
     if (response.status === 401 || response.status === 403) {
         return new CloudError(code, `Token không có quyền hoặc đã hết hạn. ${rawMessage}`, 'Chạy `monacloud-mcp login` rồi thử lại; kiểm tra audience/scope nếu lỗi vẫn còn.', { status: response.status, details: body, requestId });
     }
-    return new CloudError(code, rawMessage, response.status >= 500
-        ? 'Kiểm tra monacloud://status rồi thử lại.'
-        : 'Kiểm tra tham số theo mô tả tool rồi gọi lại.', { status: response.status, details: body, requestId });
+    return new CloudError(code, rawMessage, code === 'upload_required'
+        ? 'Gọi cloud_app_deploy với app_id hiện có và local_dir để upload source; không tạo app mới.'
+        : response.status >= 500
+            ? 'Kiểm tra monacloud://status rồi thử lại.'
+            : 'Kiểm tra tham số theo mô tả tool rồi gọi lại.', { status: response.status, details: body, requestId });
 }
 export async function requestJson(url, options = {}) {
     const parsedUrl = new URL(url);
@@ -42,14 +44,16 @@ export async function requestJson(url, options = {}) {
         ...(options.token ? { Authorization: `Bearer ${options.token}` } : {}),
         ...options.headers,
     };
-    if (options.body !== undefined)
+    const multipart = options.body instanceof FormData;
+    if (options.body !== undefined && !multipart)
         headers['Content-Type'] = 'application/json';
     let response;
     try {
         response = await (options.fetchImpl || fetch)(parsedUrl, {
             method: options.method || 'GET',
             headers,
-            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            body: multipart ? options.body : options.body === undefined ? undefined : JSON.stringify(options.body),
+            ...(multipart ? { redirect: 'error' } : {}),
             ...(options.timeoutMs ? { signal: AbortSignal.timeout(options.timeoutMs) } : {}),
         });
     }

package/dist/index.js

@@ -22,7 +22,7 @@ async function main() {
         return;
     }
     if (command === '--version' || command === '-v') {
-        console.log('0.3.0');
+        console.log('0.4.0');
         return;
     }
     if (command === '--help' || command === '-h' || command === 'help') {

package/dist/jobs.d.ts

@@ -1,11 +1,4 @@
 import type { CloudClients } from './clients.js';
 export declare const TERMINAL_JOBS: Set<string>;
 export declare function pollJob(clients: CloudClients, jobId: string, wait: boolean, intervalSeconds: number, timeoutSeconds: number, sandbox: boolean): Promise<Record<string, unknown>>;
-export declare function finishAppJob(clients: CloudClients, created: unknown, sandbox: boolean, wait: boolean, interval: number, timeout: number): Promise<{
-    job_id?: string | undefined;
-    estimate?: {} | undefined;
-    app_id?: string | undefined;
-    url?: string | undefined;
-    application_id?: string | undefined;
-    sandbox?: boolean | undefined;
-}>;
+export declare function finishAppJob(clients: CloudClients, created: unknown, sandbox: boolean, wait: boolean, interval: number, timeout: number): Promise<Record<string, unknown>>;

package/dist/jobs.js

@@ -37,6 +37,8 @@ export async function finishAppJob(clients, created, sandbox, wait, interval, ti
         ...(result.estimated_app_host ? { estimate: result.estimated_app_host } : {}),
         ...(typeof result.app_id === 'string' ? { app_id: result.app_id } : {}),
         ...(typeof result.url === 'string' ? { url: result.url } : {}),
+        ...(result.build !== undefined ? { build: result.build } : {}),
+        ...(typeof result.seconds === 'number' ? { seconds: result.seconds } : {}),
         ...(typeof result.application_id === 'string' ? { application_id: result.application_id } : {}),
         ...(sandbox ? { sandbox: true } : {}) };
 }

package/dist/local-app.d.ts

@@ -0,0 +1,21 @@
+import type { CloudClients } from './clients.js';
+type Row = Record<string, any>;
+export declare function localAppTools(clients: CloudClients): {
+    create(args: Row): Promise<{
+        sandbox: boolean;
+        needs_cost_approval: boolean;
+        next_step: string;
+    } | {
+        estimate?: {} | undefined;
+    }>;
+    deploy(args: Row): Promise<{
+        app_id: any;
+        phase: string;
+        next_step: string;
+    } | {
+        app_id: any;
+        build: unknown;
+        seconds: {};
+    }>;
+};
+export {};

package/dist/local-app.js

@@ -0,0 +1,108 @@
+import { CloudError } from './errors.js';
+import { unwrapData } from './http.js';
+import { finishAppJob } from './jobs.js';
+import { archiveProject, detectProject, MAX_ARCHIVE_BYTES } from './local.js';
+const object = (value) => value && typeof value === 'object' ? value : {};
+const data = (value) => object(unwrapData(value));
+const ready = (host) => host.status === 'active' && (!host.power_state || host.power_state === 'running') && (!host.app_host_status || host.app_host_status === 'ready');
+export function localAppTools(clients) {
+    // Preview evidence is scoped to this MCP session and exact payload, expires after ten minutes.
+    // This is an estimate cache, not a substitute for the agent obtaining human cost approval.
+    const previews = new Map();
+    const finish = async (response, args, sandbox) => finishAppJob(clients, response, sandbox, args.wait, args.interval_sec, args.timeout_sec);
+    async function upload(appId, archive, sandbox, start) {
+        const path = `/api/apps/${encodeURIComponent(appId)}/upload`;
+        if (start) {
+            const limit = start.max_bytes;
+            if (!Number.isSafeInteger(limit) || limit <= 0 || typeof start.upload_url !== 'string')
+                throw new CloudError('invalid_upload_response', 'API thiếu upload_url/max_bytes hợp lệ.', `Đọc cloud_app_get app_id=${appId}; không tạo app mới.`);
+            let valid = false;
+            try {
+                const url = new URL(start.upload_url, clients.config.vibecloudApi);
+                const expected = new URL(`${clients.config.vibecloudApi}${path}`);
+                valid = url.href === expected.href;
+            }
+            catch { /* Do not forward project files or bearer tokens to another destination. */ }
+            if (!valid)
+                throw new CloudError('invalid_upload_url', 'upload_url không khớp endpoint upload của app trên Compute API.', `Đọc cloud_app_get app_id=${appId}; không tạo app mới.`);
+            if (archive.bytes.length > Math.min(limit, MAX_ARCHIVE_BYTES))
+                throw new CloudError('archive_too_large', `ZIP ${archive.bytes.length} bytes vượt max_bytes=${Math.min(limit, MAX_ARCHIVE_BYTES)} từ API.`, `Giảm dung lượng rồi cloud_app_deploy app_id=${appId} với local_dir; không tạo app mới.`);
+        }
+        const form = new FormData();
+        form.set('archive', new Blob([new Uint8Array(archive.bytes)], { type: 'application/zip' }), 'project.zip');
+        form.set('build_path', archive.build_path);
+        return clients.vibecloud(path, { method: 'POST', body: form, timeoutMs: 120_000,
+            ...(sandbox ? { headers: { 'X-Vibecloud-Sandbox': '1' } } : {}) });
+    }
+    async function submit(payload, archive, args, sandbox) {
+        const started = Date.now();
+        const created = data(await clients.guardedVibecloud('/api/apps', { method: 'POST', body: payload }, sandbox));
+        // Existing sandbox implementations may return an estimate job without an upload slot.
+        if (sandbox && !created.upload_url)
+            return finish(created, args, true);
+        if (typeof created.id !== 'string' || !created.id)
+            throw new CloudError('invalid_upload_response', 'API không trả app id cho source=upload.', 'Đọc cloud_app_list trước khi thử lại; không tạo trùng app.');
+        const appId = created.id;
+        try {
+            const result = await finish(await upload(appId, archive, sandbox, created), args, sandbox);
+            return { ...result, app_id: appId, build: result.build ?? result.status, seconds: result.seconds ?? (Date.now() - started) / 1000 };
+        }
+        catch (error) {
+            if (error instanceof CloudError)
+                throw new CloudError(error.code, error.message, `${error.nextStep} App đã tạo: app_id=${appId}; sửa rồi cloud_app_deploy với local_dir, không gọi cloud_app_create lại.`, { status: error.status, requestId: error.requestId });
+            throw error;
+        }
+    }
+    return {
+        async create(args) {
+            const detected = await detectProject(args.local_dir);
+            const archive = await archiveProject(detected.local_dir); // Validate and enforce 80 MiB before any HTTP.
+            const payload = { source: 'upload', name: args.name || detected.name, build_type: args.build_type || detected.build_type,
+                env: args.env || {}, port: args.port || detected.port, ...(args.domain ? { domain: args.domain } : {}) };
+            const key = JSON.stringify({ directory: detected.local_dir, ...payload });
+            const sandbox = clients.sandboxEnabled(args.sandbox);
+            let estimate;
+            if (!sandbox) {
+                const hostResult = unwrapData(await clients.vibecloud('/api/app-hosts'));
+                const hosts = Array.isArray(hostResult) ? hostResult : object(hostResult).app_hosts ?? object(hostResult).items;
+                if (!Array.isArray(hosts))
+                    throw new CloudError('invalid_app_hosts', 'Không đọc được danh sách app host.', 'Gọi cloud_app_host_list rồi thử lại.');
+                if (!hosts.some(ready)) {
+                    if (hosts.length)
+                        throw new CloudError('app_host_not_ready', 'App host hiện có chưa sẵn sàng.', 'Đọc cloud_app_host_list và start host trước khi deploy.');
+                    const cached = previews.get(key);
+                    if (!cached || Date.now() - cached.at > 600_000) {
+                        const preview = await submit(payload, archive, { ...args, wait: true }, true);
+                        estimate = preview.estimate;
+                        if (estimate && ['done', 'succeeded'].includes(String(preview.status)))
+                            previews.set(key, { at: Date.now(), estimate });
+                        return { ...preview, sandbox: true, needs_cost_approval: true,
+                            next_step: 'Báo estimate chi phí app host theo giờ/gói, hỏi human duyệt một lần; sau khi đã duyệt gọi cloud_app_create với cùng local_dir và sandbox=false. Sandbox chưa phải website thật.' };
+                    }
+                    estimate = cached.estimate;
+                }
+            }
+            const result = await submit(payload, archive, args, sandbox);
+            if (sandbox && result.estimate && ['done', 'succeeded'].includes(String(result.status)))
+                previews.set(key, { at: Date.now(), estimate: result.estimate });
+            return { ...result, ...(estimate ? { estimate } : {}) };
+        },
+        async deploy(args) {
+            const started = Date.now(), sandbox = clients.sandboxEnabled(args.sandbox);
+            const archive = await archiveProject(args.local_dir);
+            const path = `/api/apps/${encodeURIComponent(args.app_id)}`;
+            const app = data(await clients.vibecloud(path, sandbox ? { headers: { 'X-Vibecloud-Sandbox': '1' } } : {}));
+            if (app.source !== 'upload')
+                throw new CloudError('app_source_mismatch', 'local_dir chỉ dùng để redeploy app có source=upload.', 'Tạo app local bằng cloud_app_create hoặc bỏ local_dir để redeploy repo git.');
+            if (!sandbox)
+                await clients.spendGuard();
+            // The deploy endpoint must not race the upload job, even with wait=false for the final deploy.
+            const uploaded = await finish(await upload(args.app_id, archive, sandbox), { ...args, wait: true }, sandbox);
+            if (!['done', 'succeeded'].includes(String(uploaded.status)))
+                return { ...uploaded, app_id: args.app_id, phase: 'upload',
+                    next_step: `Poll cloud_job_status job_id=${uploaded.job_id}; khi done/succeeded gọi cloud_app_deploy app_id=${args.app_id} không có local_dir.` };
+            const result = await finish(await clients.guardedVibecloud(`${path}/deploy`, { method: 'POST' }, sandbox), args, sandbox);
+            return { ...result, app_id: args.app_id, build: result.build ?? result.status, seconds: result.seconds ?? (Date.now() - started) / 1000 };
+        },
+    };
+}

package/dist/local.d.ts

@@ -0,0 +1,19 @@
+export declare const MAX_ARCHIVE_BYTES: number;
+export declare function projectRoot(directory: string): Promise<string>;
+export declare function detectProject(directory: string): Promise<{
+    local_dir: string;
+    name: string;
+    stack: string;
+    port: number;
+    start_command: string | null;
+    dockerfile: boolean;
+    build_type: string;
+    env_required: string[];
+    warnings: string[];
+    network: boolean;
+}>;
+export declare function archiveProject(directory: string, limit?: number): Promise<{
+    bytes: Buffer<ArrayBuffer>;
+    file_count: number;
+    build_path: string;
+}>;

package/dist/local.js

@@ -0,0 +1,282 @@
+import { constants } from 'node:fs';
+import { lstat, open, readdir, realpath } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+import { createDeflateRaw } from 'node:zlib';
+import { CloudError } from './errors.js';
+export const MAX_ARCHIVE_BYTES = 80 * 1024 * 1024;
+const fail = (code, message) => { throw new CloudError(code, message, 'Kiểm tra local_dir và ignore rules rồi thử lại; không cần git remote.'); };
+export async function projectRoot(directory) {
+    try {
+        const root = await realpath(resolve(directory));
+        if (!(await lstat(root)).isDirectory())
+            return fail('invalid_local_dir', 'local_dir phải là thư mục dự án.');
+        return root;
+    }
+    catch (error) {
+        if (error instanceof CloudError)
+            throw error;
+        return fail('invalid_local_dir', 'Không đọc được thư mục local_dir.');
+    }
+}
+// Never follow a project symlink to credentials or files outside the chosen tree.
+async function readText(root, name) {
+    let file;
+    try {
+        if (!(await lstat(join(root, name))).isFile())
+            return undefined;
+        file = await open(join(root, name), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const info = await file.stat();
+        if (!info.isFile())
+            return undefined;
+        if (info.size > 1024 * 1024)
+            return fail('local_metadata_too_large', `${name} vượt 1 MiB; không thể đọc an toàn metadata/ignore rules.`);
+        return await file.readFile('utf8');
+    }
+    catch (error) {
+        if (['ENOENT', 'ELOOP'].includes(String(error.code)))
+            return undefined;
+        throw error;
+    }
+    finally {
+        await file?.close();
+    }
+}
+export async function detectProject(directory) {
+    const root = await projectRoot(directory);
+    const files = new Set((await readdir(root, { withFileTypes: true })).filter((f) => f.isFile()).map((f) => f.name));
+    const packageText = await readText(root, 'package.json');
+    let pkg = {};
+    if (packageText) {
+        try {
+            pkg = JSON.parse(packageText) || {};
+        }
+        catch {
+            return fail('invalid_package_json', 'package.json không phải JSON hợp lệ.');
+        }
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+    const docker = await readText(root, 'Dockerfile');
+    let stack = 'static', port = 80, start = null;
+    const warnings = [];
+    if (packageText) {
+        stack = deps.next ? 'next' : deps.vite ? 'vite' : 'node';
+        port = stack === 'vite' ? 4173 : 3000;
+        start = typeof scripts.start === 'string' ? 'npm run start'
+            : stack === 'vite' ? 'npm run build && npx --no-install vite preview --host 0.0.0.0'
+                : files.has('server.js') ? 'node server.js' : files.has('index.js') ? 'node index.js' : null;
+        if (!start)
+            warnings.push('Chưa tìm thấy lệnh start; AI cần bổ sung scripts.start hoặc Dockerfile.');
+    }
+    else if (files.has('requirements.txt') || files.has('pyproject.toml') || files.has('manage.py') || files.has('app.py')) {
+        stack = 'python';
+        port = 8000;
+        start = files.has('manage.py') ? 'gunicorn <project>.wsgi:application --bind 0.0.0.0:8000' : files.has('app.py') ? 'gunicorn app:app --bind 0.0.0.0:8000' : null;
+        warnings.push('Xác minh module Python, framework và dependency trước khi dùng lệnh start gợi ý.');
+    }
+    else if (files.has('composer.json') || files.has('index.php')) {
+        stack = 'php';
+        port = 8080;
+        start = `php -S 0.0.0.0:8080${files.has('artisan') ? ' -t public' : ''}`;
+        warnings.push('Lệnh PHP chỉ là gợi ý kiểm thử; cấu hình web server production trong Dockerfile.');
+    }
+    const startScript = typeof scripts.start === 'string' ? scripts.start : '';
+    const configuredPort = startScript.match(/(?:--port(?:=|\s+)|-p\s+|\bPORT=)(\d+)/)?.[1];
+    const exposed = docker?.match(/^\s*EXPOSE\s+(\d+)(?:\/tcp)?\b/im)?.[1];
+    const guessed = Number(exposed || configuredPort);
+    if (guessed >= 1 && guessed <= 65535)
+        port = guessed;
+    const envExample = await readText(root, '.env.example');
+    const envRequired = [...new Set([...envExample?.matchAll(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/gm) || []].map((m) => m[1]))];
+    return { local_dir: root, name: basename(root).toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'app',
+        stack, port, start_command: start, dockerfile: docker !== undefined, build_type: docker !== undefined ? 'dockerfile' : stack === 'static' ? 'static' : 'nixpacks',
+        env_required: envRequired, warnings, network: false };
+}
+function glob(pattern) {
+    let expression = '';
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === '*') {
+            if (pattern[i + 1] === '*') {
+                while (pattern[i + 1] === '*')
+                    i++;
+                if (pattern[i + 1] === '/') {
+                    expression += '(?:.*/)?';
+                    i++;
+                }
+                else
+                    expression += '.*';
+            }
+            else
+                expression += '[^/]*';
+        }
+        else if (c === '?')
+            expression += '[^/]';
+        else if (c === '[') {
+            const end = pattern.indexOf(']', i + 1);
+            if (end > i + 1) {
+                expression += `[${pattern.slice(i + 1, end).replace(/^!/, '^')}]`;
+                i = end;
+            }
+            else
+                expression += '\\[';
+        }
+        else if (c === '\\' && i + 1 < pattern.length)
+            expression += pattern[++i].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        else
+            expression += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    return expression;
+}
+function parseIgnore(text, base = '', docker = false) {
+    return (text || '').split(/\r?\n/).flatMap((line) => {
+        line = docker ? line.trim() : line.replace(/(?<!\\)\s+$/, '');
+        if (!line || line.startsWith('#') || line === '.')
+            return [];
+        const negate = line.startsWith('!');
+        if (negate)
+            line = line.slice(1);
+        const directoryOnly = !docker && line.endsWith('/');
+        const anchored = line.startsWith('/');
+        line = line.replace(/^\/+|\/+$/g, '');
+        if (!line)
+            return [];
+        const prefix = base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const anywhere = !docker && !anchored && !line.includes('/');
+        try {
+            return [{ regex: new RegExp(`^${prefix}${anywhere ? '(?:.*/)?' : ''}${glob(line)}$`), negate, directoryOnly }];
+        }
+        catch {
+            return fail('invalid_ignore', 'Ignore pattern không hợp lệ.');
+        }
+    });
+}
+function ignored(path, directory, rules) {
+    let excluded = false;
+    for (const rule of rules)
+        if ((!rule.directoryOnly || directory) && rule.regex.test(path))
+            excluded = !rule.negate;
+    return excluded;
+}
+const sensitive = (name) => name === 'node_modules' || name === '.git' || /^\.env/i.test(name) || /\.pem$/i.test(name);
+const crcTable = Array.from({ length: 256 }, (_, value) => {
+    for (let n = 0; n < 8; n++)
+        value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    return value >>> 0;
+});
+// ZIP32 with deflate, UTF-8 filenames and UNIX executable bits. No shell or package install.
+// dist is retained by default: even a Dockerfile may COPY prebuilt output.
+export async function archiveProject(directory, limit = MAX_ARCHIVE_BYTES) {
+    const root = await projectRoot(directory);
+    const maxBytes = Math.min(MAX_ARCHIVE_BYTES, limit);
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)
+        return fail('invalid_upload_limit', 'max_bytes không hợp lệ.');
+    const local = [], central = [];
+    let offset = 0, centralSize = 0, count = 0;
+    const check = (size) => {
+        if (size > maxBytes)
+            fail('archive_too_large', `ZIP vượt giới hạn ${maxBytes} bytes (${(maxBytes / 1024 / 1024).toFixed(2)} MiB; tối đa 80 MiB). Bỏ file lớn bằng ignore rules.`);
+    };
+    const dockerRules = parseIgnore(await readText(root, '.dockerignore'), '', true);
+    async function walk(relative, inheritedGit, dockerParentIgnored = false) {
+        const dir = join(root, relative);
+        const gitRules = [...inheritedGit, ...parseIgnore(await readText(dir, '.gitignore'), relative)];
+        const entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            if (sensitive(entry.name) || entry.isSymbolicLink() || (!entry.isFile() && !entry.isDirectory()))
+                continue;
+            const path = relative + entry.name;
+            if (/[\x00-\x1f\\]/.test(path))
+                fail('invalid_archive_path', 'Tên file chứa ký tự không an toàn cho ZIP.');
+            const directory = entry.isDirectory();
+            if (ignored(path, directory, gitRules))
+                continue;
+            // Docker allows !dir/file even under an excluded directory; Git requires re-including the parent.
+            let dockerIgnored = dockerParentIgnored;
+            for (const rule of dockerRules)
+                if (rule.regex.test(path))
+                    dockerIgnored = !rule.negate;
+            if (directory) {
+                if (!dockerIgnored || dockerRules.some((rule) => rule.negate))
+                    await walk(`${path}/`, gitRules, dockerIgnored);
+                continue;
+            }
+            if (dockerIgnored)
+                continue;
+            const absolute = await realpath(join(root, path));
+            if (!absolute.startsWith(root + sep))
+                fail('invalid_archive_path', 'File nằm ngoài local_dir.');
+            const file = await open(join(root, path), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const info = await file.stat();
+                if (!info.isFile())
+                    continue;
+                if (info.size > 0xffffffff || count >= 65535)
+                    fail('archive_too_large', 'Dự án vượt giới hạn ZIP32 (4 GiB/file hoặc 65535 file).');
+                const name = Buffer.from(path);
+                if (name.length > 65535)
+                    fail('invalid_archive_path', 'Tên file quá dài cho ZIP.');
+                const chunks = [];
+                let size = 0, compressedSize = 0, crc = 0xffffffff;
+                const stream = file.createReadStream({ autoClose: false });
+                const deflate = createDeflateRaw();
+                stream.on('data', (chunk) => {
+                    size += chunk.length;
+                    for (const byte of chunk)
+                        crc = crcTable[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+                });
+                stream.on('error', (error) => deflate.destroy(error));
+                stream.pipe(deflate);
+                try {
+                    for await (const chunk of deflate) {
+                        compressedSize += chunk.length;
+                        check(offset + compressedSize + centralSize + 30 + 46 + name.length * 2 + 22);
+                        chunks.push(chunk);
+                    }
+                }
+                finally {
+                    stream.destroy();
+                    deflate.destroy();
+                }
+                if (size !== info.size)
+                    fail('local_file_changed', 'File thay đổi trong lúc đóng ZIP; dừng tác vụ ghi file rồi thử lại.');
+                const checksum = (crc ^ 0xffffffff) >>> 0;
+                const header = Buffer.alloc(30);
+                header.writeUInt32LE(0x04034b50);
+                header.writeUInt16LE(20, 4);
+                header.writeUInt16LE(0x800, 6);
+                header.writeUInt16LE(8, 8);
+                header.writeUInt16LE(33, 12);
+                header.writeUInt32LE(checksum, 14);
+                header.writeUInt32LE(compressedSize, 18);
+                header.writeUInt32LE(size, 22);
+                header.writeUInt16LE(name.length, 26);
+                const index = Buffer.alloc(46);
+                index.writeUInt32LE(0x02014b50);
+                index.writeUInt16LE(0x314, 4);
+                header.copy(index, 6, 4, 30);
+                index.writeUInt32LE(((info.mode & 0xffff) * 65536) >>> 0, 38);
+                index.writeUInt32LE(offset, 42);
+                local.push(header, name, ...chunks);
+                central.push(index, name);
+                offset += header.length + name.length + compressedSize;
+                centralSize += index.length + name.length;
+                count++;
+            }
+            finally {
+                await file.close();
+            }
+        }
+    }
+    await walk('', []);
+    if (!count)
+        return fail('empty_archive', 'Không còn file nào sau khi áp dụng ignore rules.');
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50);
+    end.writeUInt16LE(count, 8);
+    end.writeUInt16LE(count, 10);
+    end.writeUInt32LE(centralSize, 12);
+    end.writeUInt32LE(offset, 16);
+    check(offset + centralSize + end.length);
+    return { bytes: Buffer.concat([...local, ...central, end]), file_count: count, build_path: '.' };
+}

package/dist/server.js

@@ -90,7 +90,7 @@ export function createServer(dependencies = {}) {
     const auth = new AuthManager(config, env, fetchImpl);
     const clients = new CloudClients(config, auth, fetchImpl);
     const catalog = new TemplateCatalog(config, fetchImpl);
-    const server = new McpServer({ name: 'monacloud-mcp', version: '0.3.0' }, { instructions: `${ENTITY}\nDùng cloud_* cho tài khoản, ví và hạ tầng; monapay_* cho thu tiền; mail_* để gửi email giao dịch (MONA Mail); agent_* cho catalog. Không bao giờ yêu cầu mật khẩu sản phẩm. Đọc → ước tính → hỏi duyệt nếu chưa được duyệt → làm. Dừng khi cần DNS, nạp tiền, duyệt chi phí, OTP hoặc KYC. ${APP_FLOW}` });
+    const server = new McpServer({ name: 'monacloud-mcp', version: '0.4.0' }, { instructions: `${ENTITY}\nDùng cloud_* cho tài khoản, ví và hạ tầng; monapay_* cho thu tiền; mail_* để gửi email giao dịch (MONA Mail); agent_* cho catalog. Không bao giờ yêu cầu mật khẩu sản phẩm. Đọc → ước tính → hỏi duyệt nếu chưa được duyệt → làm. Dừng khi cần DNS, nạp tiền, duyệt chi phí, OTP hoặc KYC. ${APP_FLOW}` });
     server.registerTool('cloud_whoami', {
         title: 'Tài khoản MONA Cloud',
         description: 'Xác minh MONA Pass hiện tại. / Return the current MONA Pass profile.',
@@ -307,7 +307,7 @@ export function createServer(dependencies = {}) {
     registerMailTools(server, clients, config);
     server.registerTool('agent_templates_list', {
         title: 'Catalog MONA Agent',
-        description: 'Đọc template từ thư mục local, URL catalog hoặc catalog wave 1 tích hợp. Deploy repo git: dùng cloud_app_create, sandbox trước nếu chưa có host.',
+        description: 'Đọc template từ thư mục local, URL catalog hoặc catalog wave 1 tích hợp. Deploy dự án: cloud_app_detect rồi cloud_app_create(local_dir), sandbox trước nếu chưa có host.',
     }, () => runTool(() => catalog.list()));
     server.registerTool('agent_templates_get', {
         title: 'Chi tiết MONA Agent template',
@@ -316,7 +316,7 @@ export function createServer(dependencies = {}) {
     }, ({ template }) => runTool(() => catalog.get(template)));
     server.registerTool('agent_deploy', {
         title: 'Dùng ngay MONA Agent template',
-        description: 'Gọi cùng runtime với cloud_agent_deploy. Với deploy repo git, dùng cloud_app_create (đã live), sandbox trước nếu chưa có host.',
+        description: 'Gọi cùng runtime với cloud_agent_deploy. Deploy thư mục: cloud_app_detect → cloud_app_create(local_dir); git dùng repo_url (đã live), sandbox trước nếu chưa có host.',
         inputSchema: { template: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/) },
     }, ({ template }) => runTool(() => agentRuntimeStub(template)));
     const imported = importedMonaPayTools(config, env, fetchImpl);
@@ -347,7 +347,7 @@ export function createServer(dependencies = {}) {
     }, async (uri) => ({ contents: [{
                 uri: uri.href,
                 mimeType: 'text/plain',
-                text: `${ENTITY}\n\n${APP_FLOW}\n\nHuman đăng ký MONA Pass, duyệt chi phí, thêm DNS khi cần, nạp tiền và cung cấp OTP/KYC bắt buộc. AI dùng MCP làm phần còn lại.\n\n- cloud_*: tài khoản, ví, ledger, usage, budget, VPS, database, job, vòng đời service, plans, subscriptions, invoices/PDF, credit và apps từ git (đang mở).\n- monapay_*: nối ngân hàng, checkout/QR, giao dịch, webhook và email.\n- mail_*: tài khoản, domain, API key, gửi mail, trạng thái, webhook, suppression (MONA Mail https://monamail.vn, API https://api.monamail.vn)\n- agent_*: catalog và deploy template.\n\nMONA Cloud: https://monacloud.vn\nCompute API: https://api.monacloud.vn\nMONA Pay: https://monapay.vn\n`,
+                text: `${ENTITY}\n\n${APP_FLOW}\n\nHuman đăng ký MONA Pass, duyệt chi phí, thêm DNS khi cần, nạp tiền và cung cấp OTP/KYC bắt buộc. AI dùng MCP làm phần còn lại.\n\n- cloud_*: tài khoản, ví, ledger, usage, budget, VPS, database, job, vòng đời service, plans, subscriptions, invoices/PDF, credit và apps từ git hoặc thư mục local (source=upload); cloud_app_detect hoàn toàn offline.\n- monapay_*: nối ngân hàng, checkout/QR, giao dịch, webhook và email.\n- mail_*: tài khoản, domain, API key, gửi mail, trạng thái, webhook, suppression (MONA Mail https://monamail.vn, API https://api.monamail.vn)\n- agent_*: catalog và deploy template.\n\nMONA Cloud: https://monacloud.vn\nCompute API: https://api.monacloud.vn\nMONA Pay: https://monapay.vn\n`,
             }] }));
     server.registerResource('monacloud-status', 'monacloud://status', {
         title: 'Trạng thái hệ MONA Cloud',
@@ -374,7 +374,7 @@ export function createServer(dependencies = {}) {
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: `Dựng app bán hàng ${app_name || 'của tôi'} bằng ${framework || 'stack phù hợp'} trên MONA Cloud theo đúng thứ tự:\n1. Gọi cloud_whoami, cloud_balance, cloud_plan_list, cloud_packages và cloud_prices. Báo ước tính và hỏi duyệt chi phí nếu chưa được duyệt. Nếu thiếu tiền, gọi cloud_topup rồi dừng để người dùng quét VietQR.\n2. Nếu dùng VPS gọi cloud_vps_create và cloud_db_create; nếu deploy repo dùng cloud_app_host_list rồi cloud_app_create (đang mở), sandbox trước nếu chưa có host. Poll từng job bằng cloud_job_status tới done/succeeded.\n3. Gọi monapay_link nếu MONA Pay còn ở lớp chuyển tiếp. Gọi monapay_whoami; nếu chưa có VA, nối ngân hàng bằng chuỗi monapay_link_bank_start → HỎI OTP → verify → notification_register → HỎI OTP lần 2 → verify. Không tự đoán OTP.\n4. Viết endpoint webhook có HMAC và idempotency theo transaction_code; đăng ký bằng monapay_create_webhook, bắn monapay_test_webhook và đọc monapay_webhook_logs.\n5. Tích hợp monapay_create_checkout hoặc monapay_create_qr vào app, chỉ giao hàng sau CHECKOUT_PAID.\n6. Với repo git, dùng cloud_app_create sau khi duyệt ước tính; kiểm cloud_app_get/cloud_app_logs và health rồi báo URL. Chỉ dùng VPS thủ công khi người dùng chọn. Không yêu cầu người dùng mở dashboard ngoài bước nạp tiền/OTP bắt buộc.`,
+                    text: `Dựng app bán hàng ${app_name || 'của tôi'} bằng ${framework || 'stack phù hợp'} trên MONA Cloud. ${APP_FLOW}\nTheo đúng thứ tự:\n1. Gọi cloud_whoami, cloud_balance, cloud_plan_list, cloud_packages và cloud_prices. Báo ước tính và hỏi duyệt chi phí nếu chưa được duyệt. Nếu thiếu tiền, gọi cloud_topup rồi dừng để người dùng quét VietQR.\n2. Nếu dùng VPS gọi cloud_vps_create và cloud_db_create; nếu deploy dự án dùng cloud_app_detect(local_dir), cloud_app_host_list rồi cloud_app_create(local_dir), sandbox trước nếu chưa có host. Poll từng job bằng cloud_job_status tới done/succeeded.\n3. Gọi monapay_link nếu MONA Pay còn ở lớp chuyển tiếp. Gọi monapay_whoami; nếu chưa có VA, nối ngân hàng bằng chuỗi monapay_link_bank_start → HỎI OTP → verify → notification_register → HỎI OTP lần 2 → verify. Không tự đoán OTP.\n4. Viết endpoint webhook có HMAC và idempotency theo transaction_code; đăng ký bằng monapay_create_webhook, bắn monapay_test_webhook và đọc monapay_webhook_logs.\n5. Tích hợp monapay_create_checkout hoặc monapay_create_qr vào app, chỉ giao hàng sau CHECKOUT_PAID.\n6. Với dự án local, dùng cloud_app_create(local_dir) sau khi duyệt ước tính; git dùng repo_url; kiểm cloud_app_get/cloud_app_logs và health rồi báo URL. Chỉ dùng VPS thủ công khi người dùng chọn. Không yêu cầu người dùng mở dashboard ngoài bước nạp tiền/OTP bắt buộc.`,
                 },
             }] }));
     server.registerPrompt('gui-mail-otp-monamail', {

package/dist/templates.js

@@ -111,7 +111,7 @@ export class TemplateCatalog {
             ...template,
             source: 'built-in-wave-1-catalog',
             status: 'catalog_only',
-            next_step: 'Catalog runtime chưa được phát hành. Deploy repo git: dùng cloud_app_host_list rồi cloud_app_create (đã live), sandbox trước nếu chưa có app host; báo ước tính và hỏi duyệt trước khi tạo thật.',
+            next_step: 'Catalog runtime chưa được phát hành. Deploy dự án: cloud_app_detect(local_dir), cloud_app_host_list rồi cloud_app_create(local_dir); git dùng repo_url (đã live), sandbox trước nếu chưa có app host; báo ước tính và hỏi duyệt trước khi tạo thật.',
         };
     }
 }

package/docs/ai-agent.md

@@ -2,6 +2,18 @@
 
 Tài liệu này dành cho Claude, Codex, Cursor và agent dùng Model Context Protocol. Mục tiêu là hoàn thành tích hợp end-to-end mà không yêu cầu người dùng mở dashboard; các bước human gồm đăng ký MONA Pass, duyệt chi phí, thêm DNS khi cần, nạp tiền và OTP/KYC bắt buộc.
 
+## Luồng chuẩn 0.4.0: AI làm 99%
+
+Prompt Claude Code: **“Đưa dự án này lên MONA Cloud, dùng thư mục hiện tại”**.
+
+1. `cloud_app_detect({local_dir: "/đường/dẫn/tuyệt/đối"})` nhận diện stack/port/build và tên env hoàn toàn offline. AI sửa start/Dockerfile nếu cần, không chạy lệnh start gợi ý một cách mù quáng, không đọc/in giá trị `.env.example` ra chat.
+2. `cloud_app_list`, `cloud_app_host_list`, `cloud_prices`/`cloud_packages`/`cloud_plan_list` và `cloud_balance`. Chưa có host thì `cloud_app_create` cùng local_dir với `sandbox:true` để lấy `estimate` chi phí giờ/gói. Hỏi human **một lần** duyệt chi phí; đã duyệt thì tiếp tục.
+3. `cloud_app_create({local_dir, name?, env?, sandbox:false})` đóng ZIP và upload. Poll tới done/succeeded, kiểm HTTPS/health rồi trả `{url, app_id, build, seconds}`. Khi response có `sandbox:true`/`needs_cost_approval:true`, đó vẫn là preview; làm theo `next_step` trước khi gọi thật.
+4. Nếu human có domain, `cloud_app_domain_add({app_id, host})`, đưa đúng CNAME do API trả, chờ DNS và kiểm HTTPS. Không tự đoán target CNAME.
+5. Sửa code local: `cloud_app_deploy({app_id, local_dir})`. Chỉ đổi env: `cloud_app_env_set` với map đầy đủ rồi `cloud_app_deploy({app_id})`. Timeout giữ job_id/app_id để tiếp tục, không tạo app mới.
+
+Human chỉ cần đăng ký MONA Pass/device flow, duyệt chi phí một lần và nạp tiền khi hết credit 20k; DNS là bước thêm khi dùng domain riêng. AI làm các bước kỹ thuật còn lại. `.env*` kể cả `.env.example` không vào ZIP; truyền secret cần thiết qua `env`, không công khai. Xem [hợp đồng local deploy](local-deploy.md). VPS/database thủ công dưới đây chỉ dùng khi dự án cần hoặc người dùng chọn.
+
 ## Quy tắc vận hành
 
 1. Bắt đầu bằng `cloud_whoami`. Nếu nhận `login_required`, yêu cầu người dùng chạy `monacloud-mcp login`; không hỏi username hoặc password trong chat.
@@ -119,7 +131,7 @@ Dùng `monapay_create_qr` khi đã có đủ thông tin ACB/VA và cần render
 
 ### 6. Deploy và xác minh
 
-Với repo git, ưu tiên `cloud_app_create` (đang mở): đọc `cloud_app_host_list`, sandbox trước nếu chưa có host, báo ước tính và duyệt rồi deploy thật. Dùng secret env, chạy migration và kiểm HTTPS/health. Chỉ triển khai VPS thủ công nếu người dùng chọn. Sau đó:
+Với dự án local, ưu tiên `cloud_app_detect` rồi `cloud_app_create(local_dir)`; git dùng `repo_url`: đọc `cloud_app_host_list`, sandbox trước nếu chưa có host, báo ước tính và duyệt rồi deploy thật. Dùng secret env, chạy migration và kiểm HTTPS/health. Chỉ triển khai VPS thủ công nếu người dùng chọn. Sau đó:
 
 - tạo checkout sandbox;
 - tạo transaction sandbox;

package/docs/local-deploy.md

@@ -0,0 +1,41 @@
+# Local deploy 0.4.0
+
+Prompt Claude Code: **“Đưa dự án này lên MONA Cloud, dùng thư mục hiện tại”**.
+
+`local_dir` nằm trên máy chạy MCP; dùng đường dẫn tuyệt đối khi MCP host có cwd khác editor. Không cần git, remote hoặc commit. CLI cùng máy gọi đúng các tool này qua stdio, dùng cùng cơ chế ZIP và MONA Pass.
+
+| Tool | Hợp đồng |
+|---|---|
+| `cloud_app_detect({local_dir})` | Chỉ đọc local: `{local_dir,name,stack,port,start_command,dockerfile,build_type,env_required,warnings,network:false}`. Stack node/next/vite/python/php/static; `env_required` là tên biến trong `.env.example`, không gồm giá trị. Lệnh start là gợi ý cần AI xác minh. |
+| `cloud_app_create({local_dir,name?,build_type?,env?,port?,domain?,sandbox?,wait?,interval_sec?,timeout_sec?})` | POST `/api/apps` JSON `{source:"upload",name,build_type,env,port,domain?}` → `{id,upload_url,max_bytes}` → POST multipart upload → poll job |
+| `cloud_app_deploy({app_id,local_dir?,sandbox?,wait?,interval_sec?,timeout_sec?})` | Có local_dir: GET app, yêu cầu source=upload, ZIP mới → upload → chờ upload done/succeeded → POST deploy → poll. Không local_dir: POST deploy dùng source đã lưu. |
+
+Mỗi tool có alias `vibecloud_` cùng schema/handler. Tổng 135 tool, 2 resource, 2 prompt. Phiên bản package, binary và handshake là 0.4.0.
+
+Upload gửi đúng POST `/api/apps/{id}/upload`, FormData gồm `archive` (file `project.zip`, MIME `application/zip`) và `build_path` (`.`). ZIP chứa nội dung thư mục ở root, không bọc thêm tên thư mục. Fetch tự sinh multipart boundary, dùng token compute hiện tại; upload không follow redirect. `upload_url` phải đúng endpoint cùng origin, không gửi ZIP/token sang host khác. Nếu server trả `max_bytes` nhỏ hơn giới hạn local, MCP dừng upload và giữ app_id cho lần sửa tiếp.
+
+Create upload chờ job upload/build và trả `{url,app_id,build,seconds}` cùng status/job_id. `build` giữ dữ liệu API; nếu API không có thì dùng trạng thái build/job. `seconds` giữ số API trả hoặc thời gian xử lý request khi chưa có. `wait:false` có thể trả job queued và chưa có URL; với redeploy có source mới, MCP vẫn phải chờ job upload trước khi gửi deploy. Job upload timeout trả `phase:"upload"`: poll job đó rồi gọi deploy không local_dir. Không tự retry POST hoặc tạo app khác.
+
+## ZIP và nhận diện offline
+
+- Không cài dependency, chạy shell, thực thi code dự án hoặc gửi mạng trong detect/ZIP.
+- Giới hạn ZIP local **83,886,080 bytes (80 MiB)**, tính cả header/central directory; kiểm trước HTTP. ZIP32 deflate, UTF-8 filenames, giữ bit executable. Giới hạn ZIP32: 65,535 file, 4 GiB mỗi file.
+- Luôn loại `node_modules`, `.git`, `.env*` (kể cả `.env.example`), `*.pem` ở mọi cấp và mọi symlink. Ignore negation không thể đưa các file này trở lại.
+- Áp dụng `.gitignore` ở root và thư mục con, `.dockerignore` ở root. Hai bộ rule cùng áp dụng: file phải được cả hai cho phép. Hỗ trợ `*`, `**`, `?`, character classes, comments, anchored paths và negation `!`. Git không re-include được file nếu thư mục cha vẫn bị exclude; Docker cho phép `!dir/file` dưới thư mục excluded.
+- `dist` không tự loại: Dockerfile có thể `COPY dist`. Chỉ thêm `dist` vào ignore khi build có thể tạo lại nó. File được ignore theo cấu hình dự án vẫn bị bỏ.
+- Metadata/ignore file tối đa 1 MiB; lỗi đọc/JSON/ignore/ZIP báo lỗi rõ ràng, không upload một phần. Không sinh archive tạm trên đĩa.
+- Dockerfile root gợi ý `dockerfile`; không có Dockerfile thì Node/Next/Vite/Python/PHP gợi ý `nixpacks`, static gợi ý `static`. Port ưu tiên EXPOSE, port trong scripts.start, rồi mặc định stack. AI cần xác minh start và bind `0.0.0.0`.
+
+## AI làm 99%, duyệt chi phí một lần
+
+Detect → đọc app host/giá giờ hoặc gói và ví → sandbox nếu chưa có host → báo estimate để human duyệt một lần → create local thật → poll, kiểm và trả URL. Host hiện có tiếp tục tính phí theo kỳ đang dùng; host chưa ready thì cần start trước. Human đăng ký MONA Pass/device flow và nạp ví khi hết credit 20k. Có domain riêng: `cloud_app_domain_add`, đưa CNAME từ API và kiểm DNS/HTTPS.
+
+Nếu gọi create local thật khi chưa có host và chưa có preview hợp lệ trong MCP session, MCP chỉ chạy sandbox và trả `needs_cost_approval:true`. Preview cùng thư mục/cấu hình có estimate terminal được giữ 10 phút trong session. Sau khi agent đã lấy duyệt chi phí, gọi lại cấu hình đó với `sandbox:false`; nếu preview hết hạn, báo lại estimate trước khi tiếp tục. Sandbox explicit hoặc `MONACLOUD_SANDBOX=1` luôn 0đ, không đọc Billing. Backend sandbox cũ trả thẳng job estimate cũng được hỗ trợ.
+
+Lỗi upload/build sau create có app_id trong `next_step`; sửa rồi dùng `cloud_app_deploy` với cùng app_id/local_dir. 409 `upload_required` hướng dẫn upload lại bằng tool deploy. 402 hướng dẫn nạp ví. Không báo URL sandbox hoặc job đang chạy là website thật.
+
+## Tương thích git
+
+`cloud_app_create({repo_url,branch?,build_type?,dockerfile?,env?,domain?,app_host_id?,port?})` giữ mặc định main/dockerfile/Dockerfile/3000 như 0.3.x. Chọn đúng một `local_dir` hoặc `repo_url`. `branch`, `app_host_id` và Dockerfile tuỳ chỉnh chỉ áp dụng git; backend upload tự chọn host theo tài khoản, dùng Dockerfile root. Không đổi tên field hợp đồng backend trong brief ngày 05/09/2026.
+
+Tất cả kiểm chứng bản này dùng local test và HTTP mock; không gọi production và không publish.

package/docs/wave-ab.md

@@ -1,5 +1,7 @@
 # Wave A/B — gói tháng, hoá đơn và app từ git (0.3.0)
 
+Bổ sung 0.4.0: [deploy từ thư mục local và cloud_app_detect](local-deploy.md). Các mặc định repo/branch dưới đây áp dụng cho nguồn git.
+
 Luồng mặc định: **đọc → ước tính VND → hỏi duyệt nếu chưa được duyệt → làm → kiểm kết quả**. Các tool dưới đây đều có alias `vibecloud_` cùng hậu tố, schema và hành vi; riêng alias VPS cũ vẫn là `vibecloud_create_vps`.
 
 ## Bảng tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monacloud-mcp",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Unified MCP server for MONA Cloud, MONA Pay and MONA Agent.",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test test/*.test.mjs",
+    "test": "npm run build && node support/test.mjs",
     "start": "node dist/index.js"
   },
   "engines": {