@miosa/cli 1.0.94 → 1.0.95

package/dist/commands/sandbox.js

@@ -11,12 +11,15 @@ import { loadAppManifest, manifestPort, manifestProbePath, manifestStartCommand,
 import { detectFramework } from "../framework-detector.js";
 import { addDataOption, client, apiPath, deleteAndPrint, enc, getAndPrint, postAndPrint, printValue, runAction, unwrap, } from "./enterprise-util.js";
 import { loadConfig } from "../config.js";
+import { assertDeletableRemoteDir } from "./sandbox-delete-guard.js";
+import { ENV_FILE_OPTION_HELP, ENV_INLINE_SHELL_WARNING, ENV_STDIN_OPTION_HELP, resolveEnvInputs, } from "./env-input.js";
 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 { ApiResponseError, MiosaError, NetworkError, ServerError, UserError, } from "../errors.js";
+import { ApiResponseError, MiosaError, NetworkError, ServerError, UserError, mapHttpError, } from "../errors.js";
 import { EXIT_USER_ERROR } from "../types.js";
+import { registerSandboxDevCommands, runFullSandboxDoctor, } from "./sandbox-dev.js";
 const DEFAULT_INTERACTIVE_SANDBOX_TIMEOUT_SEC = 3_600;
 const DEFAULT_CREATE_WAIT_TIMEOUT_SEC = 120;
 const EXPIRING_SANDBOX_THRESHOLD_SEC = 5 * 60;
@@ -30,6 +33,7 @@ export function register(program) {
         .command("sandbox")
         .alias("sandboxes")
         .description("Manage Sandboxes — lightweight code-only Computers (Firecracker microVMs without a desktop)");
+    registerSandboxDevCommands(sandbox);
     // list
     sandbox
         .command("list")
@@ -182,6 +186,9 @@ export function register(program) {
         .option("--depth <n>", "Git clone depth when --source git: is used", parseIntegerOption)
         .option("--snapshot <id>", "Create from a sandbox snapshot")
         .option("--workspace <id-or-slug>", "Workspace ID/slug")
+        .option("--external-workspace <id>", "White-label workspace/customer ID for billing attribution")
+        .option("--external-user <id>", "White-label user ID for billing attribution")
+        .option("--external-project <id>", "White-label project ID for billing attribution")
         .option("--agent-profile <id>", "Agent runtime profile ID to mount into the sandbox")
         .option("--skip-agent-profile", "Do not apply the tenant/workspace default agent runtime profile")
         .option("--network-policy <policy>", "Network policy: allow-all or deny-all")
@@ -192,6 +199,12 @@ export function register(program) {
         .option("--non-persistent", "Discard filesystem state on timeout instead of pausing for resume")
         .option("--auto-start", "Seed and start the template app after the sandbox reaches running"))
         .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Note:
+  White-label preview domains require external attribution at creation.
+  Pass --external-workspace / --external-user / --external-project when the
+  sandbox will be exposed on a white-label preview domain.
+`)
         .action((opts) => runAction(async () => {
         const t0 = Date.now();
         const json = !!isJsonMode(opts) || process.env["MIOSA_JSON"] === "1";
@@ -236,6 +249,15 @@ export function register(program) {
             process.env["MIOSA_WORKSPACE"];
         if (workspace)
             body["workspace_id"] = workspace;
+        if (opts.externalWorkspace) {
+            body["external_workspace_id"] = opts.externalWorkspace;
+        }
+        if (opts.externalUser) {
+            body["external_user_id"] = opts.externalUser;
+        }
+        if (opts.externalProject) {
+            body["external_project_id"] = opts.externalProject;
+        }
         const networkPolicy = buildNetworkPolicy(opts);
         if (networkPolicy) {
             body["metadata"] = {
@@ -385,7 +407,9 @@ export function register(program) {
         .option("--connector <uid>", "MIOSA Connect connector UID to preflight before running the agent")
         .option("--preflight", "Verify the Sandbox has the requested provider connector before exec")
         .option("--cwd <path>", "Working directory inside the Sandbox")
-        .option("--env <KEY=VALUE>", "Environment variable for the run. Repeatable.", collectOption, [])
+        .option("--env <KEY=VALUE>", `Environment variable for the Agent Run. Repeatable. ${ENV_INLINE_SHELL_WARNING}`, collectOption, [])
+        .option("--env-file <path>", ENV_FILE_OPTION_HELP)
+        .option("--env-stdin", ENV_STDIN_OPTION_HELP)
         .option("--agent-profile <id>", "Agent runtime profile ID")
         .option("--skip-agent-profile", "Do not apply the default agent runtime profile")
         .option("--external-workspace <id>", "White-label workspace/customer ID for billing attribution")
@@ -423,8 +447,9 @@ export function register(program) {
             body["model"] = opts.model;
         if (opts.cwd)
             body["cwd"] = opts.cwd;
-        if (opts.env && opts.env.length > 0) {
-            body["env"] = parseEnvPairs(opts.env);
+        const env = await resolveEnvInputs(parseEnvPairs(opts.env ?? []), opts);
+        if (Object.keys(env).length > 0) {
+            body["env"] = env;
         }
         if (opts.agentProfile) {
             body["agent_runtime_profile_id"] = opts.agentProfile;
@@ -479,7 +504,9 @@ export function register(program) {
         .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("--env <pair>", `Environment variable KEY=VALUE. Repeatable. ${ENV_INLINE_SHELL_WARNING}`, collectOption, [])
+        .option("--env-file <path>", ENV_FILE_OPTION_HELP)
+        .option("--env-stdin", ENV_STDIN_OPTION_HELP)
         .option("--background", "Start the command in the background and return immediately")
         .option("--detached", "Create a durable backend command and return command_id immediately")
         .option("--follow", "Stream command output until it exits (alias --stream)")
@@ -508,7 +535,7 @@ export function register(program) {
             body["cwd"] = cwd;
             body["dir"] = cwd;
         }
-        const env = parseEnvPairs(opts.env ?? []);
+        const env = await resolveEnvInputs(parseEnvPairs(opts.env ?? []), opts);
         if (opts.detached) {
             const result = await createSandboxCommand(id, cmd, {
                 cwd,
@@ -547,7 +574,9 @@ export function register(program) {
         .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("--env <pair>", `Environment variable KEY=VALUE. Repeatable. ${ENV_INLINE_SHELL_WARNING}`, collectOption, [])
+        .option("--env-file <path>", ENV_FILE_OPTION_HELP)
+        .option("--env-stdin", ENV_STDIN_OPTION_HELP)
         .option("--background", "Start the command in the background and return immediately")
         .option("--detached", "Create a durable backend command and return command_id immediately")
         .option("--follow", "Stream command output until it exits (alias --stream)")
@@ -576,7 +605,7 @@ export function register(program) {
             body["cwd"] = cwd;
             body["dir"] = cwd;
         }
-        const env = parseEnvPairs(opts.env ?? []);
+        const env = await resolveEnvInputs(parseEnvPairs(opts.env ?? []), opts);
         if (opts.detached) {
             const result = await createSandboxCommand(id, cmd, {
                 cwd,
@@ -963,11 +992,17 @@ export function register(program) {
         ]);
     }));
     env
-        .command("set <sandbox-id> <pairs...>")
-        .description("Set encrypted sandbox env vars as KEY=VALUE")
+        .command("set <sandbox-id> [pairs...]")
+        .description(`Set encrypted sandbox env vars as KEY=VALUE. ${ENV_INLINE_SHELL_WARNING}`)
+        .option("--env-file <path>", ENV_FILE_OPTION_HELP)
+        .option("--env-stdin", ENV_STDIN_OPTION_HELP)
         .option("--json", "Output as JSON")
         .action((id, pairs, opts) => runAction(async () => {
-        const vars = Object.entries(parseEnvPairs(pairs)).map(([key, value]) => ({
+        const values = await resolveEnvInputs(parseEnvPairs(pairs ?? []), opts);
+        if (Object.keys(values).length === 0) {
+            throw new UserError("No env vars provided.", "Pass KEY=VALUE pairs, --env-file <path>, or --env-stdin.");
+        }
+        const vars = Object.entries(values).map(([key, value]) => ({
             key,
             value,
         }));
@@ -1024,12 +1059,34 @@ export function register(program) {
         console.log(chalk.green(`Attached database ${databaseId} to sandbox ${id}.`));
     }));
     sandbox
-        .command("doctor <sandbox-id>")
+        .command("doctor [sandbox-id]")
         .description("Diagnose sandbox app readiness across sandbox state, internal HTTP, public route, and TLS/edge reachability")
-        .requiredOption("--port <port>", "Port inside the sandbox to check", parseIntegerOption)
+        .option("--port <port>", "Port inside the sandbox to check", parseIntegerOption)
         .option("--probe-path <path>", "HTTP path to probe", "/")
+        .option("--full", "Inspect the complete canonical developer contract")
+        .option("--dir <path>", "Project directory for --full", ".")
         .option("--json", "Output as JSON")
         .action((id, opts) => runAction(async () => {
+        if (opts.full) {
+            const report = await runFullSandboxDoctor(opts.dir, id);
+            if (!report.ok)
+                process.exitCode = 1;
+            if (isJsonMode(opts)) {
+                console.log(JSON.stringify(report, null, 2));
+                return;
+            }
+            console.log();
+            console.log(chalk.bold("Sandbox Doctor Full"));
+            console.log();
+            for (const check of report.checks) {
+                console.log(`  ${check.ok ? chalk.green("ok") : chalk.red("fail")} ${check.id}: ${check.message}`);
+            }
+            console.log();
+            return;
+        }
+        if (!id || opts.port == null) {
+            throw new UserError("Sandbox ID and --port are required unless --full is used.", "Use miosa sandbox doctor <sandbox-id> --port <port>, or miosa sandbox doctor --full.");
+        }
         const report = await doctorSandbox(id, opts.port, opts.probePath);
         if (isJsonMode(opts)) {
             console.log(JSON.stringify(report, null, 2));
@@ -1082,7 +1139,7 @@ export function register(program) {
         .option("--json", "Output raw JSON response")
         .action(async (id, remotePath, opts) => {
         try {
-            const result = await fetchApiRaw(apiPath(`/sandboxes/${enc(id)}/files/read?path=${enc(remotePath)}`));
+            const result = await client().apiGet(apiPath(`/sandboxes/${enc(id)}/files/read?path=${enc(remotePath)}`));
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify(typeof result === "string" ? { content: result } : result, null, 2));
                 return;
@@ -1142,11 +1199,14 @@ export function register(program) {
         .command("upload-dir <sandbox-id> <local-dir> <remote-dir>")
         .description("Upload a local directory into a Sandbox")
         .option("--delete", "Delete the remote directory contents before extracting")
+        .option("--force", "Skip the --delete confirmation prompt")
+        .option("--yes", "Alias for --force")
         .option("--json", "Output as JSON")
         .action(async (id, localDir, remoteDir, opts) => {
         try {
             const result = await uploadDirToSandbox(id, localDir, remoteDir, {
                 delete: !!opts.delete,
+                force: !!(opts.force || opts.yes),
             });
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify(result, null, 2));
@@ -1163,11 +1223,14 @@ export function register(program) {
         .description("Sync a local directory into a sandbox")
         .requiredOption("--sandbox <id>", "Sandbox ID")
         .option("--delete", "Delete the remote directory contents before extracting")
+        .option("--force", "Skip the --delete confirmation prompt")
+        .option("--yes", "Alias for --force")
         .option("--json", "Output as JSON")
         .action(async (localDir, remoteDir, opts) => {
         try {
             const result = await uploadDirToSandbox(opts.sandbox, localDir, remoteDir, {
                 delete: !!opts.delete,
+                force: !!(opts.force || opts.yes),
             });
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify(result, null, 2));
@@ -1184,6 +1247,8 @@ export function register(program) {
         .alias("copy")
         .description("Copy a local file or directory into a sandbox, e.g. ./app/. sbx_123:/workspace")
         .option("--delete", "Delete the remote directory contents before extracting directories")
+        .option("--force", "Skip the --delete confirmation prompt")
+        .option("--yes", "Alias for --force")
         .option("--json", "Output as JSON")
         .action(async (source, target, opts) => {
         try {
@@ -1204,7 +1269,10 @@ export function register(program) {
             const local = source.endsWith("/.") ? source.slice(0, -2) : source;
             const stat = fs.statSync(local);
             if (stat.isDirectory()) {
-                const result = await uploadDirToSandbox(parsed.sandboxId, local, parsed.remotePath, { delete: !!opts.delete });
+                const result = await uploadDirToSandbox(parsed.sandboxId, local, parsed.remotePath, {
+                    delete: !!opts.delete,
+                    force: !!(opts.force || opts.yes),
+                });
                 if (isJsonMode(opts)) {
                     console.log(JSON.stringify(result, null, 2));
                     return;
@@ -1314,7 +1382,10 @@ export function register(program) {
             console.log(kvPanel([
                 { label: "Export", value: chalk.bold(str(exportData["id"])) },
                 { label: "Sandbox", value: id },
-                { label: "Status", value: statusColor(str(exportData["status"])) },
+                {
+                    label: "Status",
+                    value: statusColor(str(exportData["status"])),
+                },
                 {
                     label: "Archive",
                     value: str(exportData["archive_download_url"]),
@@ -1555,7 +1626,7 @@ function normalizeConnectorMode(value) {
 //   4. Spawn `ssh` pointing at localhost:<port> with the key and user.
 //   5. On ssh exit, close the TCP server and exit.
 const SANDBOX_KEY_PATH = path.join(os.homedir(), ".ssh", "miosa_sandbox_ed25519");
-async function ensureSandboxSshKey(id, apiKey, endpoint) {
+async function ensureSandboxSshKey(id, config) {
     if (!fs.existsSync(SANDBOX_KEY_PATH)) {
         console.log(chalk.dim("Generating SSH keypair for MIOSA sandbox access..."));
         fs.mkdirSync(path.join(os.homedir(), ".ssh"), { recursive: true });
@@ -1583,22 +1654,54 @@ async function ensureSandboxSshKey(id, apiKey, endpoint) {
     // already exist from a previous sandbox, but a fresh sandbox still needs it
     // installed in authorized_keys before SSH auth can succeed.
     const pubKey = fs.readFileSync(`${SANDBOX_KEY_PATH}.pub`, "utf8").trim();
-    const base = endpoint.replace(/\/$/, "");
-    const res = await fetch(`${base}/api/v1/sandboxes/${encodeURIComponent(id)}/ssh-keys`, {
+    const endpoint = config.endpoint.replace(/\/$/, "");
+    const response = await fetch(`${endpoint}${apiPath(`/sandboxes/${encodeURIComponent(id)}/ssh-keys`)}`, {
         method: "POST",
         headers: {
+            ...sandboxTransportHeaders(config),
             "Content-Type": "application/json",
-            Authorization: `Bearer ${apiKey}`,
         },
         body: JSON.stringify({ public_key: pubKey }),
     });
-    if (!res.ok) {
-        const body = await res.text();
-        throw new Error(`Failed to register SSH key: ${res.status} ${body}`);
+    if (!response.ok) {
+        const rawBody = await response.text();
+        let body = {};
+        try {
+            body = JSON.parse(rawBody);
+        }
+        catch {
+            body = { message: rawBody || `HTTP ${response.status}` };
+        }
+        throw mapHttpError(response.status, body, rawBody, response.headers.get("x-request-id"));
     }
     console.log(chalk.green("SSH key registered."));
 }
-function bridgeSandboxWs(socket, wsUrl, apiKey) {
+function sandboxTransportHeaders(config) {
+    if (!config.api_key)
+        throw new Error("Not authenticated. Run: miosa login");
+    const headers = {
+        Authorization: `Bearer ${String(config.api_key)}`,
+    };
+    if (config.tenant)
+        headers["X-MIOSA-Tenant"] = config.tenant;
+    if (config.workspace)
+        headers["X-MIOSA-Workspace"] = config.workspace;
+    return headers;
+}
+export function buildSandboxWebSocketRequest(config, id) {
+    const base = config.endpoint.replace(/\/$/, "");
+    const wsBase = base.replace(/^https?/, (protocol) => protocol === "https" ? "wss" : "ws");
+    const url = new URL(`${wsBase}/api/v1/sandboxes/${encodeURIComponent(id)}/ssh-tunnel`);
+    const headers = sandboxTransportHeaders(config);
+    if (config.tenant) {
+        url.searchParams.set("tenant", config.tenant);
+    }
+    if (config.workspace) {
+        url.searchParams.set("workspace", config.workspace);
+    }
+    return { url: url.toString(), headers };
+}
+function bridgeSandboxWs(socket, request) {
     let closed = false;
     function cleanup() {
         if (closed)
@@ -1607,8 +1710,8 @@ function bridgeSandboxWs(socket, wsUrl, apiKey) {
         if (!socket.destroyed)
             socket.destroy();
     }
-    const ws = new WebSocket(wsUrl, {
-        headers: { Authorization: `Bearer ${apiKey}` },
+    const ws = new WebSocket(request.url, {
+        headers: request.headers,
     });
     ws.on("open", () => {
         socket.on("data", (chunk) => {
@@ -1634,14 +1737,8 @@ function bridgeSandboxWs(socket, wsUrl, apiKey) {
 }
 async function runSandboxSsh(id, opts) {
     const config = loadConfig();
-    const apiKey = config.api_key;
-    if (!apiKey)
-        throw new Error("Not authenticated. Run: miosa login");
-    const endpoint = config.endpoint ?? "https://api.miosa.ai";
-    const base = endpoint.replace(/\/$/, "");
-    const wsBase = base.replace(/^https?/, (p) => (p === "https" ? "wss" : "ws"));
-    const wsUrl = `${wsBase}/api/v1/sandboxes/${encodeURIComponent(id)}/ssh-tunnel`;
-    await ensureSandboxSshKey(id, String(apiKey), endpoint);
+    const wsRequest = buildSandboxWebSocketRequest(config, id);
+    await ensureSandboxSshKey(id, config);
     // Pick a free local port
     const localPort = opts.port ?? (await pickFreePort());
     const user = opts.user ?? "root";
@@ -1650,13 +1747,13 @@ async function runSandboxSsh(id, opts) {
             sandbox_id: id,
             local_port: localPort,
             user,
-            ws_url: wsUrl,
+            ws_url: wsRequest.url,
             key_path: SANDBOX_KEY_PATH,
         }));
         return;
     }
     const server = createServer((socket) => {
-        bridgeSandboxWs(socket, wsUrl, String(apiKey));
+        bridgeSandboxWs(socket, wsRequest);
     });
     await new Promise((resolve, reject) => {
         server.on("error", reject);
@@ -2783,13 +2880,16 @@ async function uploadDirToSandbox(sandboxId, localDir, remoteDir, opts) {
     if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) {
         throw new UserError(`Local directory not found: ${sourceDir}`);
     }
+    const deleteTarget = opts.delete
+        ? await confirmRemoteDeleteDir(sandboxId, remoteDir, !!opts.force)
+        : null;
     const c = client();
     const archivePath = createDeployArchive(sourceDir);
     const remoteArchive = `/tmp/miosa-upload-${Date.now()}.tgz`;
     try {
         await uploadFileToSandbox(c, sandboxId, archivePath, remoteArchive);
-        const clean = opts.delete
-            ? `rm -rf ${shellQuote(remoteDir)} && mkdir -p ${shellQuote(remoteDir)}`
+        const clean = deleteTarget != null
+            ? `rm -rf ${shellQuote(deleteTarget)} && mkdir -p ${shellQuote(deleteTarget)}`
             : `mkdir -p ${shellQuote(remoteDir)}`;
         await execSandbox(c, sandboxId, `${clean} && tar -xzf ${shellQuote(remoteArchive)} -C ${shellQuote(remoteDir)} && rm -f ${shellQuote(remoteArchive)}`, "/");
     }
@@ -2803,6 +2903,31 @@ async function uploadDirToSandbox(sandboxId, localDir, remoteDir, opts) {
         files_label: path.basename(sourceDir) || sourceDir,
     };
 }
+// --delete runs `rm -rf` inside the sandbox. Refuse protected roots, then
+// require an explicit confirmation (interactive prompt, or --force/--yes)
+// before anything is wiped. Returns the normalized remote dir to delete.
+async function confirmRemoteDeleteDir(sandboxId, remoteDir, force) {
+    const target = assertDeletableRemoteDir(remoteDir);
+    if (force)
+        return target;
+    if (!process.stdin.isTTY) {
+        throw new UserError(`--delete will permanently wipe ${target} on sandbox ${sandboxId}.`, "Non-interactive session: re-run with --force (or --yes) to confirm the wipe.");
+    }
+    console.log(chalk.yellow(`--delete will permanently wipe sandbox ${sandboxId}:${target} before uploading.`));
+    const { default: inquirer } = await import("inquirer");
+    const { confirmed } = await inquirer.prompt([
+        {
+            type: "confirm",
+            name: "confirmed",
+            message: `Wipe ${sandboxId}:${target}?`,
+            default: false,
+        },
+    ]);
+    if (!confirmed) {
+        throw new UserError("Cancelled - nothing was deleted or uploaded.");
+    }
+    return target;
+}
 async function execSandbox(c, sandboxId, command, cwd, timeout) {
     const body = { command: commandInCwd(command, cwd) };
     if (cwd) {
@@ -3170,33 +3295,6 @@ async function readSandboxFile(c, sandboxId, remotePath) {
     }
     throw new UserError(`Could not read sandbox file: ${remotePath}`);
 }
-async function fetchApiRaw(path, body) {
-    const config = loadConfig();
-    const apiKey = config.api_key;
-    if (!apiKey)
-        throw new UserError("Not authenticated. Run: miosa login");
-    const endpoint = (config.endpoint ?? "https://api.miosa.ai").replace(/\/$/, "");
-    const res = await fetch(`${endpoint}${path}`, {
-        method: body === undefined ? "GET" : "POST",
-        headers: {
-            Authorization: `Bearer ${String(apiKey)}`,
-            Accept: "application/json, text/plain, */*",
-            "Content-Type": "application/json",
-            "User-Agent": "@miosa/cli",
-        },
-        body: body === undefined ? undefined : JSON.stringify(body),
-    });
-    const text = await res.text();
-    if (!res.ok) {
-        throw new UserError(`Server error (${res.status}): HTTP ${res.status}`, text || res.statusText);
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return text;
-    }
-}
 function commandInCwd(command, cwd) {
     if (!cwd)
         return command;