@miosa/cli 1.0.55 → 1.0.57

package/dist/commands/sandbox.js

@@ -15,7 +15,7 @@ import { handleError, isJsonMode } from "./util.js";
 import { renderTable } from "../ui/table.js";
 import { formatDuration, hintBlock, icon, kvPanel, printBanner, printElapsed, } from "../ui/render.js";
 import { formatBytes } from "../ui/progress.js";
-import { UserError } from "../errors.js";
+import { ApiResponseError, MiosaError, NetworkError, ServerError, UserError, } from "../errors.js";
 export function register(program) {
     // -------------------------------------------------------------------------
     // sandbox / sandboxes command group — built manually to avoid subcommand
@@ -383,6 +383,9 @@ export function register(program) {
         .allowExcessArguments()
         .option("--cwd <path>", "Working directory inside the Sandbox")
         .option("--workdir <path>", "Alias for --cwd")
+        .option("--cmd <command>", "Explicit command string to run; avoids CLI parsing command flags")
+        .option("--command <command>", "Alias for --cmd")
+        .option("--shell-cmd <shell>", "Run --cmd through this shell, e.g. 'bash -lc'")
         .option("--env <pair>", "Environment variable KEY=VALUE. Repeatable.", collectOption, [])
         .option("--background", "Start the command in the background and return immediately")
         .option("--detached", "Create a durable backend command and return command_id immediately")
@@ -400,7 +403,7 @@ export function register(program) {
             await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, {});
             return;
         }
-        const cmd = joinCommandWords(words);
+        const cmd = resolveSandboxCommand(words, opts);
         const effectiveCommand = opts.background
             ? backgroundCommand(cmd)
             : cmd;
@@ -414,7 +417,7 @@ export function register(program) {
         }
         const env = parseEnvPairs(opts.env ?? []);
         if (opts.detached) {
-            const result = await createSandboxCommand(id, words.join(" "), {
+            const result = await createSandboxCommand(id, cmd, {
                 cwd,
                 env,
                 user: opts.user,
@@ -448,6 +451,9 @@ export function register(program) {
         .allowExcessArguments()
         .option("--cwd <path>", "Working directory inside the Sandbox")
         .option("--workdir <path>", "Alias for --cwd")
+        .option("--cmd <command>", "Explicit command string to run; avoids CLI parsing command flags")
+        .option("--command <command>", "Alias for --cmd")
+        .option("--shell-cmd <shell>", "Run --cmd through this shell, e.g. 'bash -lc'")
         .option("--env <pair>", "Environment variable KEY=VALUE. Repeatable.", collectOption, [])
         .option("--background", "Start the command in the background and return immediately")
         .option("--detached", "Create a durable backend command and return command_id immediately")
@@ -465,7 +471,7 @@ export function register(program) {
             await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, {});
             return;
         }
-        const cmd = joinCommandWords(words);
+        const cmd = resolveSandboxCommand(words, opts);
         const effectiveCommand = opts.background
             ? backgroundCommand(cmd)
             : cmd;
@@ -479,7 +485,7 @@ export function register(program) {
         }
         const env = parseEnvPairs(opts.env ?? []);
         if (opts.detached) {
-            const result = await createSandboxCommand(id, words.join(" "), {
+            const result = await createSandboxCommand(id, cmd, {
                 cwd,
                 env,
                 user: opts.user,
@@ -510,12 +516,10 @@ export function register(program) {
         .description("List listening TCP ports inside a Sandbox")
         .option("--json", "Output as JSON")
         .action((id, opts) => runAction(async () => {
-        const c = client();
-        const result = await execSandboxRaw(c, id, "ss -ltnH 2>/dev/null || cat /proc/net/tcp /proc/net/tcp6 2>/dev/null");
-        const stdout = String(result["stdout"] ?? "");
-        const ports = parseListeningPorts(stdout);
+        const result = await client().apiGet(apiPath(`/sandboxes/${enc(id)}/ports`));
+        const ports = sandboxPortsFromResponse(result);
         if (isJsonMode(opts)) {
-            console.log(JSON.stringify(ports, null, 2));
+            console.log(JSON.stringify(result, null, 2));
             return;
         }
         if (ports.length === 0) {
@@ -523,6 +527,11 @@ export function register(program) {
             return;
         }
         renderTable(ports, [
+            {
+                header: "PROTO",
+                key: (p) => p.protocol ?? "tcp",
+                width: 8,
+            },
             {
                 header: "PORT",
                 key: "port",
@@ -533,8 +542,33 @@ export function register(program) {
                 key: "address",
                 width: 24,
             },
+            {
+                header: "STATE",
+                key: (p) => p.state ?? "listen",
+                width: 10,
+            },
+            {
+                header: "PROCESS",
+                key: (p) => p.process?.name
+                    ? `${p.process.name}${p.process.pid ? `:${p.process.pid}` : ""}`
+                    : chalk.dim("-"),
+                width: 28,
+            },
         ]);
     }));
+    sandbox
+        .command("metrics <sandbox-id>")
+        .description("Show Sandbox resource, uptime, timeout, and readiness metrics")
+        .option("--window <window>", "Metrics window: 1h, 24h, or 7d", "1h")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(async () => {
+        const result = await client().apiGet(apiPath(`/sandboxes/${enc(id)}/metrics?window=${enc(opts.window)}`));
+        if (isJsonMode(opts)) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        renderResourceMetrics("Sandbox metrics", result);
+    }));
     sandbox
         .command("deploy [local-dir]")
         .description("Upload an app directory, start it in a sandbox, expose a preview URL, and wait for readiness")
@@ -553,21 +587,26 @@ export function register(program) {
         .option("--timeout <duration>", "Wait timeout, e.g. 180s or 3m", parseDurationSec, 180)
         .option("--probe-path <path>", "HTTP path to probe")
         .option("--json", "Output as JSON")
-        .action((localDir = ".", opts) => runAction(async () => {
-        const result = await deploySandbox(localDir, opts);
-        if (isJsonMode(opts)) {
-            console.log(JSON.stringify(result, null, 2));
-            return;
+        .action(async (localDir = ".", opts) => {
+        try {
+            const result = await deploySandbox(localDir, opts);
+            if (isJsonMode(opts)) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log();
+            console.log(`  ${chalk.bold("Sandbox")}  ${result.sandbox_id}`);
+            console.log(`  ${chalk.bold("Port")}     ${result.port}`);
+            console.log(`  ${chalk.bold("Preview")}  ${chalk.cyan(result.preview_url)}`);
+            console.log(`  ${chalk.bold("Ready")}    ${result.preview_ready
+                ? chalk.green("yes")
+                : chalk.yellow("not verified")}`);
+            console.log();
         }
-        console.log();
-        console.log(`  ${chalk.bold("Sandbox")}  ${result.sandbox_id}`);
-        console.log(`  ${chalk.bold("Port")}     ${result.port}`);
-        console.log(`  ${chalk.bold("Preview")}  ${chalk.cyan(result.preview_url)}`);
-        console.log(`  ${chalk.bold("Ready")}    ${result.preview_ready
-            ? chalk.green("yes")
-            : chalk.yellow("not verified")}`);
-        console.log();
-    }));
+        catch (err) {
+            handleSandboxDeployError(err, opts);
+        }
+    });
     sandbox
         .command("preview <sandbox-id>")
         .description("Expose a sandbox port and optionally wait for the public preview to answer")
@@ -647,6 +686,7 @@ export function register(program) {
         .option("--run-command <cmd>", "Run command for dynamic/server deployments")
         .option("--docker-deploy", "Publish onto the workspace Docker Deploy runtime instead of standard app hosting")
         .option("--domain <domain>", "Custom domain to attach")
+        .option("--deployment-type <type>", "Deployment runtime type: miosa_deploy, docker_deploy, dynamic, static")
         .option("--database <mode>", "none, create:postgres, postgres, or existing:<db-id>")
         .option("--port <port>", "Runtime port for dynamic deployments", parseIntegerOption)
         .option("--wait", "Wait for the production URL to answer")
@@ -664,6 +704,10 @@ export function register(program) {
         console.log(`  ${chalk.bold("App")}      ${result.deployment_id ?? result.app_id ?? ""}`);
         if (result.release_id)
             console.log(`  ${chalk.bold("Release")}  ${result.release_id}`);
+        if (result.deployment_product)
+            console.log(`  ${chalk.bold("Product")}  ${String(result.deployment_product)}`);
+        if (result.docker_deploy_host_id)
+            console.log(`  ${chalk.bold("Docker")}   ${String(result.docker_deploy_host_id)}`);
         if (result.url)
             console.log(`  ${chalk.bold("URL")}      ${chalk.cyan(String(result.url))}`);
         console.log(`  ${chalk.bold("Ready")}    ${result.ready ? chalk.green("yes") : chalk.yellow("pending")}`);
@@ -728,6 +772,7 @@ export function register(program) {
         .description("Manage named long-running processes inside a sandbox");
     service
         .command("start <sandbox-id> <name>")
+        .alias("up")
         .requiredOption("--cmd <command>", "Command to start")
         .option("--cwd <path>", "Working directory inside the sandbox", "/workspace")
         .option("--port <port>", "Port served by this service", parseIntegerOption)
@@ -896,6 +941,20 @@ export function register(program) {
         }
         renderDoctorReport(report);
     }));
+    sandbox
+        .command("recover <name-or-id>")
+        .description("Inspect a failed or partial sandbox deploy and print recovery commands")
+        .option("--port <port>", "App port to diagnose", parseIntegerOption)
+        .option("--probe-path <path>", "HTTP path to probe", "/")
+        .option("--json", "Output as JSON")
+        .action((idOrName, opts) => runAction(async () => {
+        const report = await recoverSandboxDeploy(idOrName, opts);
+        if (isJsonMode(opts)) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        renderRecoverReport(report);
+    }));
     // write-file — POST /sandboxes/:id/files with base64 content.
     // If <content-or-file> is an existing local path, reads the file bytes;
     // otherwise treats the argument as literal UTF-8 text.
@@ -908,8 +967,7 @@ export function register(program) {
             const contentBytes = fs.existsSync(contentArg)
                 ? fs.readFileSync(contentArg)
                 : Buffer.from(contentArg, "utf8");
-            const base64 = contentBytes.toString("base64");
-            const result = await fetchApiRaw(apiPath(`/sandboxes/${enc(id)}/files`), { path: remotePath, content: base64 });
+            const result = await writeBytesToSandbox(client(), id, remotePath, contentBytes);
             if (!isJsonMode(opts)) {
                 console.log(chalk.green(`Written to ${remotePath}`));
             }
@@ -970,10 +1028,8 @@ export function register(program) {
                 console.error(chalk.red(`File not found: ${localPath}`));
                 process.exit(1);
             }
-            const data = fs.readFileSync(localPath);
-            const base64 = data.toString("base64");
             const c = client();
-            const result = await c.apiPost(apiPath(`/sandboxes/${enc(id)}/files`), { path: remotePath, content: base64 });
+            const result = await writeBytesToSandbox(c, id, remotePath, fs.readFileSync(localPath));
             if (isJsonMode(opts)) {
                 printValue(result, opts);
             }
@@ -1499,6 +1555,18 @@ async function runSandboxPortForward(id, opts) {
     process.stderr.write("\n");
     server.close();
 }
+class SandboxDeployPartialError extends Error {
+    causeError;
+    sandboxId;
+    recoveryCommand;
+    constructor(causeError, sandboxId, recoveryCommand) {
+        super(causeError instanceof Error ? causeError.message : String(causeError));
+        this.causeError = causeError;
+        this.sandboxId = sandboxId;
+        this.recoveryCommand = recoveryCommand;
+        this.name = "SandboxDeployPartialError";
+    }
+}
 async function showSandboxWithPreview(sandboxId, port, probePath) {
     const c = client();
     const sandbox = unwrap(await c.apiGet(apiPath(`/sandboxes/${enc(sandboxId)}`)));
@@ -1610,6 +1678,13 @@ async function createSandboxCommand(sandboxId, command, opts) {
         status: result["status"] ?? "running",
     };
 }
+function warnOnTemplatePortMismatch(template, port, opts) {
+    if (isJsonMode(opts))
+        return;
+    if ((template === "nextjs" || template === "next-js") && port !== 3000) {
+        console.error(chalk.yellow("Next.js sandbox templates default to port 3000. Use --port 3000 unless you intentionally changed the app readiness port."));
+    }
+}
 function serviceLogPath(name) {
     return `/tmp/miosa-services/${name}.log`;
 }
@@ -1638,74 +1713,85 @@ async function deploySandbox(localDir, opts) {
         manifestPort(appManifest) ??
         detection?.port ??
         5173;
+    warnOnTemplatePortMismatch(opts.template ?? appManifest?.template ?? null, port, opts);
     const probePath = opts.probePath ?? manifestProbePath(appManifest) ?? "/";
     let remoteWorkdir = normalizeRemoteWorkdir(appManifest?.workdir ?? "/workspace");
     const start = opts.start ??
         manifestStartCommand(appManifest) ??
         defaultStartCommand(detection?.framework ?? appManifest?.framework, port);
-    const sandboxId = opts.sandbox ??
-        (deployStep(opts, "Creating sandbox"),
-            await createSandboxForDeploy(c, opts.template ?? appManifest?.template ?? "miosa-sandbox", opts.name, {
+    let sandboxId = opts.sandbox ?? null;
+    try {
+        if (!sandboxId) {
+            deployStep(opts, "Creating sandbox");
+            sandboxId = await createSandboxForDeploy(c, opts.template ?? appManifest?.template ?? "miosa-sandbox", opts.name, {
                 source: opts.source,
                 revision: opts.revision,
                 depth: opts.depth,
-            }));
-    deployStep(opts, "Waiting for sandbox");
-    await waitForSandboxRunning(c, sandboxId, Math.min(opts.timeout, 120));
-    if (sourceBacked) {
-        deployStep(opts, "Waiting for source import");
-        appManifest = await readRemoteAppManifest(c, sandboxId, opts.timeout);
-        remoteWorkdir = normalizeRemoteWorkdir(appManifest?.workdir ?? "/workspace");
-    }
-    else {
-        deployStep(opts, "Uploading files");
-        const archivePath = createDeployArchive(sourceDir);
-        const remoteArchive = `/tmp/miosa-deploy-${Date.now()}.tgz`;
-        try {
-            await uploadFileToSandbox(c, sandboxId, archivePath, remoteArchive);
-            deployStep(opts, "Extracting workspace");
-            await execSandbox(c, sandboxId, `mkdir -p ${shellQuote(remoteWorkdir)} && tar -xzf ${shellQuote(remoteArchive)} -C ${shellQuote(remoteWorkdir)}`, "/");
+            });
         }
-        finally {
-            fs.rmSync(archivePath, { force: true });
+        deployStep(opts, "Waiting for sandbox");
+        await waitForSandboxRunning(c, sandboxId, Math.min(opts.timeout, 120));
+        if (sourceBacked) {
+            deployStep(opts, "Waiting for source import");
+            appManifest = await readRemoteAppManifest(c, sandboxId, opts.timeout);
+            remoteWorkdir = normalizeRemoteWorkdir(appManifest?.workdir ?? "/workspace");
         }
+        else {
+            deployStep(opts, "Uploading files");
+            const archivePath = createDeployArchive(sourceDir);
+            const remoteArchive = `/tmp/miosa-deploy-${Date.now()}.tgz`;
+            try {
+                await uploadFileToSandbox(c, sandboxId, archivePath, remoteArchive);
+                deployStep(opts, "Extracting workspace");
+                await execSandbox(c, sandboxId, `mkdir -p ${shellQuote(remoteWorkdir)} && tar -xzf ${shellQuote(remoteArchive)} -C ${shellQuote(remoteWorkdir)}`, "/");
+            }
+            finally {
+                fs.rmSync(archivePath, { force: true });
+            }
+        }
+        const resolvedPort = opts.port ?? opts.publishPort ?? manifestPort(appManifest) ?? port;
+        const resolvedProbePath = opts.probePath ?? manifestProbePath(appManifest) ?? probePath;
+        const resolvedStart = opts.start ?? manifestStartCommand(appManifest) ?? start;
+        const installCommand = opts.install === false
+            ? null
+            : (opts.installCommand ??
+                (appManifest?.install === false ? null : appManifest?.install) ??
+                (sourceBacked ? "npm install" : defaultInstallCommand(sourceDir)));
+        if (installCommand) {
+            deployStep(opts, `Installing dependencies: ${installCommand}`);
+            await execSandbox(c, sandboxId, installCommand, remoteWorkdir, opts.timeout);
+        }
+        deployStep(opts, `Starting app on port ${resolvedPort}`);
+        await execSandbox(c, sandboxId, `fuser -k ${resolvedPort}/tcp >/dev/null 2>&1 || true; nohup sh -lc ${shellQuote(resolvedStart)} > ${shellQuote(`/tmp/miosa-app-${resolvedPort}.log`)} 2>&1 & echo $!`, remoteWorkdir);
+        deployStep(opts, "Checking internal app readiness");
+        const internal = await waitForInternalHttp(c, sandboxId, resolvedPort, resolvedProbePath, Math.min(opts.timeout, 60));
+        deployStep(opts, "Creating public preview route");
+        const exposed = await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/expose`), { port: resolvedPort, title: "app preview" });
+        const previewUrl = extractUrl(unwrap(exposed));
+        if (!previewUrl) {
+            throw new UserError("Sandbox expose did not return a preview URL.");
+        }
+        if (opts.wait)
+            deployStep(opts, "Checking public preview readiness");
+        const edge = opts.wait
+            ? await waitForPublicPreview(previewUrl, resolvedProbePath, opts.timeout)
+            : { ok: false, status: null };
+        return {
+            sandbox_id: sandboxId,
+            port: resolvedPort,
+            preview_url: previewUrl,
+            preview_ready: edge.ok,
+            internal_status: internal.status,
+            edge_status: edge.status,
+            latency_ms: edge.latency_ms ?? null,
+        };
     }
-    const resolvedPort = opts.port ?? opts.publishPort ?? manifestPort(appManifest) ?? port;
-    const resolvedProbePath = opts.probePath ?? manifestProbePath(appManifest) ?? probePath;
-    const resolvedStart = opts.start ?? manifestStartCommand(appManifest) ?? start;
-    const installCommand = opts.install === false
-        ? null
-        : (opts.installCommand ??
-            (appManifest?.install === false ? null : appManifest?.install) ??
-            (sourceBacked ? "npm install" : defaultInstallCommand(sourceDir)));
-    if (installCommand) {
-        deployStep(opts, `Installing dependencies: ${installCommand}`);
-        await execSandbox(c, sandboxId, installCommand, remoteWorkdir, opts.timeout);
-    }
-    deployStep(opts, `Starting app on port ${resolvedPort}`);
-    await execSandbox(c, sandboxId, `fuser -k ${resolvedPort}/tcp >/dev/null 2>&1 || true; nohup sh -lc ${shellQuote(resolvedStart)} > ${shellQuote(`/tmp/miosa-app-${resolvedPort}.log`)} 2>&1 & echo $!`, remoteWorkdir);
-    deployStep(opts, "Checking internal app readiness");
-    const internal = await waitForInternalHttp(c, sandboxId, resolvedPort, resolvedProbePath, Math.min(opts.timeout, 60));
-    deployStep(opts, "Creating public preview route");
-    const exposed = await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/expose`), { port: resolvedPort, title: "app preview" });
-    const previewUrl = extractUrl(unwrap(exposed));
-    if (!previewUrl) {
-        throw new UserError("Sandbox expose did not return a preview URL.");
+    catch (err) {
+        if (sandboxId) {
+            throw new SandboxDeployPartialError(err, sandboxId, recoveryCommandForSandboxDeploy(sandboxId, opts, localDir));
+        }
+        throw err;
     }
-    if (opts.wait)
-        deployStep(opts, "Checking public preview readiness");
-    const edge = opts.wait
-        ? await waitForPublicPreview(previewUrl, resolvedProbePath, opts.timeout)
-        : { ok: false, status: null };
-    return {
-        sandbox_id: sandboxId,
-        port: resolvedPort,
-        preview_url: previewUrl,
-        preview_ready: edge.ok,
-        internal_status: internal.status,
-        edge_status: edge.status,
-        latency_ms: edge.latency_ms ?? null,
-    };
 }
 const NON_TERMINAL_DEPLOY_STATES = new Set([
     "building",
@@ -1778,6 +1864,11 @@ async function publishSandbox(sandboxId, opts) {
         body["domain"] = opts.domain;
     if (opts.port != null)
         body["port"] = opts.port;
+    const deploymentType = opts.dockerDeploy
+        ? "docker-deploy"
+        : opts.deploymentType;
+    if (deploymentType)
+        body["deployment_type"] = deploymentType;
     const database = parsePublishDatabase(opts.database);
     if (database !== undefined)
         body["database"] = database;
@@ -1798,11 +1889,29 @@ async function publishSandbox(sandboxId, opts) {
         extractUrl(deployment) ??
         stringField(data, "url") ??
         null;
+    let deploymentProduct = stringField(response, "deployment_product") ??
+        stringField(data, "deployment_product") ??
+        stringField(deployment, "deployment_product") ??
+        stringField(asRecord(deployment?.["metadata"]), "deployment_product") ??
+        null;
+    let dockerDeployHostId = stringField(response, "docker_deploy_host_id") ??
+        stringField(data, "docker_deploy_host_id") ??
+        stringField(deployment, "docker_deploy_host_id") ??
+        stringField(asRecord(deployment?.["metadata"]), "docker_deploy_host_id") ??
+        null;
     if (opts.wait && deploymentId) {
         deployStep(opts, "Waiting for durable deployment");
         const waited = await waitForDeploymentReady(c, deploymentId, opts.timeout);
         state = stringField(waited, "state") ?? state;
         url = extractUrl(waited) ?? url;
+        deploymentProduct =
+            stringField(waited, "deployment_product") ??
+                stringField(asRecord(waited["metadata"]), "deployment_product") ??
+                deploymentProduct;
+        dockerDeployHostId =
+            stringField(waited, "docker_deploy_host_id") ??
+                stringField(asRecord(waited["metadata"]), "docker_deploy_host_id") ??
+                dockerDeployHostId;
         response["state"] = state;
         if (url)
             response["url"] = url;
@@ -1828,6 +1937,8 @@ async function publishSandbox(sandboxId, opts) {
         version_id: versionId,
         url,
         state,
+        deployment_product: deploymentProduct,
+        docker_deploy_host_id: dockerDeployHostId,
         ready,
         probe,
         data: raw,
@@ -1926,6 +2037,188 @@ function renderDoctorReport(report) {
         console.log();
     }
 }
+async function recoverSandboxDeploy(idOrName, opts) {
+    const c = client();
+    const resolved = await resolveSandboxForRecovery(c, idOrName);
+    if (!resolved.sandbox) {
+        return {
+            query: idOrName,
+            sandbox: null,
+            sandbox_id: null,
+            matched_by: null,
+            exec_ok: false,
+            app_port: opts.port ?? null,
+            preview_ready: null,
+            preview_url: null,
+            doctor: null,
+            recommendations: [
+                "No matching sandbox was found. Run `miosa sandbox list --json` and retry with a sandbox ID.",
+            ],
+            commands: {
+                list: "miosa sandbox list --json",
+            },
+        };
+    }
+    const sandbox = resolved.sandbox;
+    const sandboxId = str(sandbox["id"]);
+    const name = stringOrNull(sandbox["name"]);
+    const template = stringOrNull(sandbox["template_id"]);
+    const port = opts.port ?? suggestedRecoveryPort(template);
+    const execOk = await checkSandboxExec(c, sandboxId);
+    const doctor = port != null ? await safeDoctorSandbox(sandboxId, port, opts.probePath) : null;
+    const previewUrl = stringOrNull(doctor?.["preview_url"]);
+    const previewReady = doctor && typeof doctor["preview_ready"] === "boolean"
+        ? Boolean(doctor["preview_ready"])
+        : null;
+    const recommendations = buildRecoveryRecommendations({
+        sandbox,
+        execOk,
+        port,
+        previewReady,
+        template,
+    });
+    return {
+        query: idOrName,
+        sandbox,
+        sandbox_id: sandboxId,
+        matched_by: resolved.matchedBy,
+        exec_ok: execOk,
+        app_port: port,
+        preview_ready: previewReady,
+        preview_url: previewUrl,
+        doctor,
+        recommendations,
+        commands: recoveryCommands(sandboxId, name, port),
+    };
+}
+async function resolveSandboxForRecovery(c, idOrName) {
+    try {
+        const direct = unwrap(await c.apiGet(apiPath(`/sandboxes/${enc(idOrName)}`)));
+        const sandbox = asRecord(direct);
+        if (sandbox)
+            return { sandbox, matchedBy: "id" };
+    }
+    catch {
+        // Fall through to name lookup.
+    }
+    const list = unwrap(await c.apiGet(apiPath("/sandboxes")));
+    const items = Array.isArray(list)
+        ? list
+        : Array.isArray((asRecord(list) ?? {})["data"])
+            ? (asRecord(list) ?? {})["data"]
+            : [];
+    const matches = items
+        .map(asRecord)
+        .filter((item) => Boolean(item))
+        .filter((item) => {
+        const name = stringOrNull(item["name"]);
+        const id = stringOrNull(item["id"]);
+        return name === idOrName || id?.startsWith(idOrName);
+    })
+        .sort((a, b) => {
+        const aTime = Date.parse(stringOrNull(a["created_at"]) ?? "") || 0;
+        const bTime = Date.parse(stringOrNull(b["created_at"]) ?? "") || 0;
+        return bTime - aTime;
+    });
+    return { sandbox: matches[0] ?? null, matchedBy: matches[0] ? "name" : null };
+}
+async function checkSandboxExec(c, sandboxId) {
+    try {
+        const result = unwrap(await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/exec`), {
+            command: "pwd",
+        }));
+        const record = asRecord(result);
+        return Number(record?.["exit_code"] ?? 0) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeDoctorSandbox(sandboxId, port, probePath) {
+    try {
+        return await doctorSandbox(sandboxId, port, probePath);
+    }
+    catch (err) {
+        return {
+            preview_ready: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function suggestedRecoveryPort(template) {
+    if (template === "nextjs" || template === "next-js")
+        return 3000;
+    return null;
+}
+function buildRecoveryRecommendations(input) {
+    const recs = [];
+    const state = stringOrNull(input.sandbox["state"]);
+    const ready = Boolean(input.sandbox["ready"]);
+    if (state !== "running") {
+        recs.push(`Sandbox state is ${state ?? "unknown"}; wait or recreate before uploading files.`);
+    }
+    else if (!ready) {
+        recs.push("Sandbox exists but is not fully ready; try exec/write-file before retrying deploy.");
+    }
+    if (!input.execOk) {
+        recs.push("Exec health failed; retry later or recreate the sandbox.");
+    }
+    else {
+        recs.push("Exec works; if upload/deploy failed, use write-file/patch plus service up.");
+    }
+    if (input.template === "nextjs" && input.port !== 3000) {
+        recs.push("Next.js templates default to port 3000; use 3000 unless you intentionally reconfigured readiness.");
+    }
+    if (input.port != null && input.previewReady === false) {
+        recs.push("Preview is not ready; start the app process, then run sandbox wait.");
+    }
+    if (input.previewReady === true) {
+        recs.push("Preview is ready; publish the sandbox to a durable deployment.");
+    }
+    return recs;
+}
+function recoveryCommands(sandboxId, name, port) {
+    const commands = {
+        health: `miosa sandbox exec ${sandboxId} --json -- pwd`,
+        files: `miosa sandbox write-file ${sandboxId} /workspace/app/page.jsx ./page.jsx --json`,
+    };
+    if (port != null) {
+        commands.start = `miosa sandbox service up ${sandboxId} next --cwd /workspace --port ${port} --cmd "npm run dev -- --hostname 0.0.0.0 --port ${port}" --json`;
+        commands.wait = `miosa sandbox wait ${sandboxId} --port ${port} --timeout 180 --json`;
+        commands.publish = `miosa sandbox publish ${sandboxId} --path /workspace --name ${shellArg(name ?? "Recovered app")} --build-command "npm run build" --run-command "npm run start" --port ${port} --wait --timeout 900s --json`;
+    }
+    return commands;
+}
+function renderRecoverReport(report) {
+    if (!report.sandbox_id) {
+        console.log(chalk.red("No matching sandbox found."));
+        console.log(`  ${report.commands["list"]}`);
+        return;
+    }
+    console.log(chalk.bold("Sandbox recovery"));
+    console.log();
+    console.log(`  ${chalk.bold("Sandbox")} ${report.sandbox_id}`);
+    console.log(`  ${chalk.bold("Matched")} ${report.matched_by}`);
+    console.log(`  ${chalk.bold("Exec")}    ${report.exec_ok ? chalk.green("ok") : chalk.red("failed")}`);
+    if (report.app_port != null) {
+        console.log(`  ${chalk.bold("Port")}    ${report.app_port}`);
+    }
+    if (report.preview_url) {
+        console.log(`  ${chalk.bold("Preview")} ${chalk.cyan(report.preview_url)}`);
+    }
+    if (report.preview_ready != null) {
+        console.log(`  ${chalk.bold("Ready")}   ${report.preview_ready ? chalk.green("yes") : chalk.yellow("no")}`);
+    }
+    console.log();
+    for (const rec of report.recommendations) {
+        console.log(`  - ${rec}`);
+    }
+    console.log();
+    console.log(chalk.bold("Next commands"));
+    for (const [label, command] of Object.entries(report.commands)) {
+        console.log(`  ${chalk.dim(label.padEnd(7))} ${command}`);
+    }
+}
 async function createSandboxForDeploy(c, template, name, source) {
     const body = { template_id: template };
     if (name)
@@ -2011,10 +2304,123 @@ function createDeployArchive(sourceDir) {
     return archivePath;
 }
 async function uploadFileToSandbox(c, sandboxId, localPath, remotePath) {
-    await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/files`), {
-        path: remotePath,
-        content: fs.readFileSync(localPath).toString("base64"),
-    });
+    return writeBytesToSandbox(c, sandboxId, remotePath, fs.readFileSync(localPath));
+}
+async function writeBytesToSandbox(c, sandboxId, remotePath, bytes) {
+    try {
+        return await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/files`), {
+            path: remotePath,
+            content: bytes.toString("base64"),
+        });
+    }
+    catch (err) {
+        if (!shouldFallbackSandboxUpload(err))
+            throw err;
+        await writeBytesToSandboxViaExec(c, sandboxId, remotePath, bytes);
+        return {
+            data: {
+                sandbox_id: sandboxId,
+                path: remotePath,
+                size: bytes.length,
+                transport: "exec_chunked_fallback",
+            },
+        };
+    }
+}
+async function writeBytesToSandboxViaExec(c, sandboxId, remotePath, bytes) {
+    const base64 = bytes.toString("base64");
+    const base64Path = `${remotePath}.b64`;
+    const chunkSize = 48_000;
+    await execSandbox(c, sandboxId, `mkdir -p ${shellQuote(path.posix.dirname(remotePath))} && rm -f ${shellQuote(remotePath)} ${shellQuote(base64Path)}`, "/");
+    for (let offset = 0; offset < base64.length; offset += chunkSize) {
+        const chunk = base64.slice(offset, offset + chunkSize);
+        await execSandbox(c, sandboxId, `printf '%s' ${shellQuote(chunk)} >> ${shellQuote(base64Path)}`, "/");
+    }
+    await execSandbox(c, sandboxId, `base64 -d ${shellQuote(base64Path)} > ${shellQuote(remotePath)} && rm -f ${shellQuote(base64Path)}`, "/");
+}
+function shouldFallbackSandboxUpload(err) {
+    if (err instanceof NetworkError || err instanceof ServerError)
+        return true;
+    if (err instanceof ApiResponseError) {
+        return (err.retryable ||
+            /AGENT_UNAVAILABLE|SANDBOX_FILE_AGENT_UNAVAILABLE/i.test(err.code));
+    }
+    if (err instanceof Error) {
+        return /fetch failed|ECONNRESET|HTTP 502|AGENT_UNAVAILABLE|other side closed|socket hang up/i.test(err.message);
+    }
+    return false;
+}
+function recoveryCommandForSandboxDeploy(sandboxId, opts, localDir) {
+    const parts = [
+        "miosa",
+        "sandbox",
+        "deploy",
+        shellQuote(localDir),
+        "--sandbox",
+        shellQuote(sandboxId),
+    ];
+    if (opts.port != null)
+        parts.push("--port", String(opts.port));
+    if (opts.publishPort != null)
+        parts.push("--publish-port", String(opts.publishPort));
+    if (opts.installCommand)
+        parts.push("--install-command", shellQuote(opts.installCommand));
+    if (opts.install === false)
+        parts.push("--no-install");
+    if (opts.start)
+        parts.push("--start", shellQuote(opts.start));
+    if (opts.wait)
+        parts.push("--wait");
+    if (opts.timeout != null)
+        parts.push("--timeout", `${opts.timeout}s`);
+    if (opts.probePath)
+        parts.push("--probe-path", shellQuote(opts.probePath));
+    return parts.join(" ");
+}
+function handleSandboxDeployError(err, opts) {
+    if (err instanceof SandboxDeployPartialError) {
+        const cause = err.causeError;
+        const message = cause instanceof Error ? cause.message : String(cause);
+        const retryable = cause instanceof ApiResponseError
+            ? cause.retryable
+            : shouldFallbackSandboxUpload(cause);
+        if (isJsonMode(opts)) {
+            console.log(JSON.stringify({
+                ok: false,
+                error: {
+                    code: errorCodeForDeployCause(cause),
+                    message,
+                    retryable,
+                    ...(cause instanceof MiosaError && cause.requestId
+                        ? { request_id: cause.requestId }
+                        : {}),
+                },
+                partial_resource: {
+                    type: "sandbox",
+                    id: err.sandboxId,
+                    recovery_command: err.recoveryCommand,
+                },
+            }, null, 2));
+            return process.exit(1);
+        }
+        console.error(chalk.red(`Error: ${message}`));
+        console.error(chalk.yellow(`Sandbox ${err.sandboxId} exists. Retry into it with:\n  ${err.recoveryCommand}`));
+        return process.exit(1);
+    }
+    handleError(err);
+}
+function errorCodeForDeployCause(err) {
+    if (err instanceof ApiResponseError)
+        return err.code;
+    if (err instanceof NetworkError)
+        return "NETWORK";
+    if (err instanceof ServerError)
+        return "SERVER";
+    if (err instanceof MiosaError)
+        return err.constructor.name.toUpperCase();
+    if (err instanceof Error && /fetch failed|ECONNRESET/i.test(err.message))
+        return "NETWORK";
+    return "UNEXPECTED_ERROR";
 }
 async function uploadDirToSandbox(sandboxId, localDir, remoteDir, opts) {
     const sourceDir = path.resolve(localDir);
@@ -2067,37 +2473,93 @@ async function execSandboxRaw(c, sandboxId, command, cwd, timeout) {
         body["timeout"] = timeout;
     return unwrap(await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/exec`), body));
 }
-function parseListeningPorts(stdout) {
-    const lines = stdout.split("\n").map((l) => l.trim());
-    const seen = new Set();
-    const out = [];
-    // ss -ltnH columns: State Recv-Q Send-Q Local-Address:Port Peer-Address:Port
-    const ssLine = /^LISTEN\s+\d+\s+\d+\s+(\S+):(\d+)\s+/;
-    // /proc/net/tcp: sl local_address rem_address st ... (hex)
-    const procLine = /^\d+:\s+([0-9A-Fa-f]+):([0-9A-Fa-f]+)\s+\S+\s+([0-9A-Fa-f]+)/;
-    for (const line of lines) {
-        if (!line)
-            continue;
-        const ss = ssLine.exec(line);
-        if (ss && ss[2]) {
-            const port = Number(ss[2]);
-            if (!seen.has(port)) {
-                seen.add(port);
-                out.push({ port, address: ss[1] ?? "*" });
-            }
-            continue;
-        }
-        const proc = procLine.exec(line);
-        if (proc && proc[3] === "0A" && proc[2]) {
-            const port = parseInt(proc[2], 16);
-            if (!Number.isNaN(port) && !seen.has(port)) {
-                seen.add(port);
-                out.push({ port, address: "*" });
-            }
-        }
+function sandboxPortsFromResponse(raw) {
+    const root = unwrap(raw);
+    if (Array.isArray(root))
+        return root;
+    if (root && typeof root === "object") {
+        const row = root;
+        if (Array.isArray(row["ports"]))
+            return row["ports"];
+        if (Array.isArray(row["data"]))
+            return row["data"];
     }
-    out.sort((a, b) => a.port - b.port);
-    return out;
+    return [];
+}
+function renderResourceMetrics(title, raw) {
+    const root = unwrap(raw);
+    if (!root || typeof root !== "object") {
+        printValue(root, {});
+        return;
+    }
+    const row = root;
+    const current = row["current"] && typeof row["current"] === "object"
+        ? row["current"]
+        : {};
+    printBanner({ subtitle: title });
+    console.log(kvPanel([
+        { label: "resource_id", value: String(row["resource_id"] ?? row["sandbox_id"] ?? "-") },
+        { label: "window", value: String(row["window"] ?? "1h") },
+        { label: "state", value: formatState(current["state"]) },
+        { label: "ready", value: formatBool(current["ready"]) },
+        { label: "cpu", value: formatMaybe(current["cpu_count"]) },
+        { label: "memory", value: formatMb(current["memory_mb"]) },
+        { label: "disk", value: formatMb(current["disk_size_mb"]) },
+        { label: "uptime", value: formatSeconds(current["uptime_sec"]) },
+        {
+            label: "timeout_remaining",
+            value: formatSecondsOrAlwaysOn(current["timeout_remaining_sec"]),
+        },
+        { label: "node", value: formatMaybe(current["node_id"]) },
+        { label: "ip", value: formatMaybe(current["ip_address"]) },
+        { label: "boot", value: formatMs(current["boot_ms"]) },
+        { label: "envd_ready", value: formatMs(current["envd_ready_ms"]) },
+    ]));
+}
+function formatState(value) {
+    const state = String(value ?? "unknown");
+    if (["running", "active", "healthy", "ready"].includes(state)) {
+        return chalk.green(state);
+    }
+    if (["provisioning", "starting", "building", "pending"].includes(state)) {
+        return chalk.yellow(state);
+    }
+    if (["failed", "error", "unhealthy"].includes(state)) {
+        return chalk.red(state);
+    }
+    return state;
+}
+function formatBool(value) {
+    if (value === true)
+        return chalk.green("true");
+    if (value === false)
+        return chalk.red("false");
+    return chalk.dim("-");
+}
+function formatMaybe(value) {
+    if (value === null || value === undefined || value === "")
+        return chalk.dim("-");
+    return String(value);
+}
+function formatMb(value) {
+    if (typeof value !== "number")
+        return formatMaybe(value);
+    return formatBytes(value * 1024 * 1024);
+}
+function formatMs(value) {
+    if (typeof value !== "number")
+        return formatMaybe(value);
+    return `${value}ms`;
+}
+function formatSeconds(value) {
+    if (typeof value !== "number")
+        return formatMaybe(value);
+    return formatDuration(value * 1000);
+}
+function formatSecondsOrAlwaysOn(value) {
+    if (value === null || value === undefined)
+        return chalk.dim("always-on/none");
+    return formatSeconds(value);
 }
 // Stream exec output: run in background to a log file, poll-read new bytes
 // until the process exits, then print the final exit code.
@@ -2387,6 +2849,15 @@ function backgroundCommand(command) {
     const logPath = `/tmp/miosa-bg-${Date.now()}.log`;
     return `nohup sh -lc ${shellQuote(command)} > ${shellQuote(logPath)} 2>&1 & echo $!`;
 }
+function resolveSandboxCommand(words, opts) {
+    const positional = words.length === 1 ? (words[0] ?? "") : joinCommandWords(words);
+    const cmd = opts.cmd ?? opts.command ?? positional;
+    if (!opts.shellCmd)
+        return cmd;
+    if (!cmd.trim())
+        return opts.shellCmd;
+    return `${opts.shellCmd} ${shellQuote(cmd)}`;
+}
 function collectOption(value, previous) {
     return [...previous, value];
 }
@@ -2520,6 +2991,12 @@ function str(v) {
         return chalk.dim("—");
     return String(v);
 }
+function stringOrNull(v) {
+    return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+function shellArg(value) {
+    return `'${value.replace(/'/g, "'\"'\"'")}'`;
+}
 /** Apply semantic color to a sandbox status string. */
 function statusColor(s) {
     const lower = s.toLowerCase().trim();