@akanjs/cli 3.0.0-beta.18 → 3.0.0-beta.19

package/index-bc88j1ry.js

@@ -0,0 +1,1166 @@
+// @bun
+import {
+  getDefaultHostConfig,
+  GlobalConfig,
+  CloudApi
+} from "./index-srmay5jw.js";
+import {
+  runner
+} from "./index-qdgzsnhg.js";
+import {
+  WorkspaceExecutor,
+  AppExecutor
+} from "./index-crmeqnmf.js";
+import {
+  openBrowser
+} from "./index-9dp031by.js";
+
+// pkgs/@akanjs/devkit/platformTest/PlatformTestRun.ts
+import path6 from "path";
+import chalk from "chalk";
+
+// pkgs/@akanjs/devkit/platformTest/LinuxDockerTarget.ts
+import os from "os";
+import path3 from "path";
+
+// pkgs/@akanjs/devkit/platformTest/IdleWatchedProcess.ts
+import { mkdir } from "fs/promises";
+import path from "path";
+
+class IdleWatchedProcess {
+  #command;
+  #options;
+  constructor(command, options) {
+    this.#command = command;
+    this.#options = options;
+  }
+  async run() {
+    const { logPath, idleMs, totalMs, cwd, env, onIdle, onOutput } = this.#options;
+    await mkdir(path.dirname(logPath), { recursive: true });
+    const log = Bun.file(logPath).writer();
+    const startedAt = performance.now();
+    let lastOutputAt = startedAt;
+    let output = "";
+    let hung = false;
+    let timedOut = false;
+    const proc = Bun.spawn(this.#command, { cwd, env, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    const pump = async (stream) => {
+      const decoder = new TextDecoder;
+      for await (const chunk of stream) {
+        lastOutputAt = performance.now();
+        const text = decoder.decode(chunk, { stream: true });
+        output += text;
+        log.write(chunk);
+        onOutput?.(text);
+      }
+    };
+    const pumping = Promise.all([pump(proc.stdout), pump(proc.stderr)]);
+    const watch = setInterval(() => {
+      const now = performance.now();
+      if (now - lastOutputAt >= idleMs)
+        hung = true;
+      else if (totalMs !== undefined && now - startedAt >= totalMs)
+        timedOut = true;
+      else
+        return;
+      clearInterval(watch);
+      (async () => {
+        await onIdle?.().catch(() => {
+          return;
+        });
+        proc.kill();
+      })();
+    }, Math.max(50, Math.min(1000, idleMs / 4)));
+    const exitCode = await proc.exited;
+    clearInterval(watch);
+    await pumping;
+    await log.end();
+    return { exitCode: hung || timedOut ? null : exitCode, hung, timedOut, output, ms: performance.now() - startedAt };
+  }
+}
+
+// pkgs/@akanjs/devkit/platformTest/PlatformTestTarget.ts
+import path2 from "path";
+
+// pkgs/@akanjs/devkit/platformTest/BunTestReport.ts
+import { stripVTControlCharacters } from "util";
+
+class BunTestReport {
+  static #fileHeaderPattern = /^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/;
+  static #relistPattern = /^\d+ tests? failed:$/;
+  static #durationSuffix = /\s+\[[\d.]+m?s\]$/;
+  pass;
+  fail;
+  skip;
+  errors;
+  files;
+  hasSummary;
+  failures;
+  lastFile;
+  constructor(output) {
+    const lines = stripVTControlCharacters(output).split(/\r?\n/);
+    let currentFile = null;
+    let lastFile = null;
+    let relisted = false;
+    const failures = new Map;
+    for (const line of lines) {
+      if (BunTestReport.#relistPattern.test(line))
+        relisted = true;
+      const header = BunTestReport.#fileHeaderPattern.exec(line);
+      if (header?.[1] && !relisted) {
+        currentFile = header[1].replaceAll("\\", "/");
+        lastFile = currentFile;
+        continue;
+      }
+      if (!line.startsWith("(fail) "))
+        continue;
+      const name = line.slice("(fail) ".length).replace(BunTestReport.#durationSuffix, "");
+      if (!failures.has(name))
+        failures.set(name, { file: relisted ? null : currentFile, name });
+    }
+    const ran = lines.findLast((line) => /^Ran \d+ tests? across \d+ files?/.test(line));
+    this.hasSummary = !!ran;
+    this.files = ran ? Number(/across (\d+) files?/.exec(ran)?.[1] ?? 0) : 0;
+    this.failures = [...failures.values()];
+    this.lastFile = lastFile;
+    this.pass = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) pass$/) : lines.filter((line) => line.startsWith("(pass) ")).length;
+    this.fail = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) fail$/) : this.failures.length;
+    this.skip = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) skip$/) : 0;
+    this.errors = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) errors?$/) : 0;
+  }
+  get passed() {
+    return this.hasSummary && this.fail === 0 && this.errors === 0;
+  }
+  static #lastCount(lines, pattern) {
+    for (const line of lines.toReversed()) {
+      const count = pattern.exec(line)?.[1];
+      if (count)
+        return Number(count);
+    }
+    return 0;
+  }
+}
+
+// pkgs/@akanjs/devkit/platformTest/PlatformTestTarget.ts
+class PlatformTestTarget {
+  static installIdleMs = 5 * 60000;
+  static testIdleMs = 2 * 60000;
+  tolerateScriptFailures = [];
+  async run(context) {
+    const startedAt = performance.now();
+    const envWarnings = [];
+    const packages = [];
+    const result = (infraError) => ({
+      platform: this.platform,
+      policy: this.policy,
+      packages,
+      envWarnings,
+      infraError,
+      ms: performance.now() - startedAt
+    });
+    try {
+      await this.prepare(context);
+      await this.#install(context, envWarnings);
+      const build = await this.exec("bun run buildAkan", this.#logPath(context, "build"), PlatformTestTarget.installIdleMs);
+      if (build.exitCode !== 0)
+        throw new Error(`buildAkan failed \u2014 see ${this.#logPath(context, "build")}`);
+      for (const pkg of context.pkgs) {
+        const logPath = this.#logPath(context, `test-${pkg.replaceAll("/", "__")}`);
+        const run = await this.exec(`bun dist/pkgs/@akanjs/cli/index.js test ${pkg}`, logPath, PlatformTestTarget.testIdleMs);
+        const report = new BunTestReport(run.output);
+        const status = run.hung || run.timedOut ? "hung" : report.passed && run.exitCode === 0 ? "pass" : "fail";
+        packages.push({ pkg, status, report, ms: run.ms, logPath });
+        context.onProgress(`[${this.platform}] ${PlatformTestTarget.describe(packages.at(-1))}`);
+      }
+      return result(null);
+    } catch (error) {
+      return result(error instanceof Error ? error.message : String(error));
+    } finally {
+      await this.cleanup(context).catch(() => {
+        return;
+      });
+    }
+  }
+  static describe({ pkg, status, report, ms }) {
+    const seconds = `${Math.round(ms / 1000)}s`;
+    if (status === "hung")
+      return `${pkg}: hung${report.lastFile ? ` in ${report.lastFile}` : ""} (${seconds})`;
+    return `${pkg}: ${report.pass} pass / ${report.fail} fail${report.errors ? ` / ${report.errors} errors` : ""} (${seconds})`;
+  }
+  async#install(context, envWarnings) {
+    const logPath = this.#logPath(context, "install");
+    const install = await this.exec("bun install --frozen-lockfile", logPath, PlatformTestTarget.installIdleMs);
+    if (install.exitCode === 0)
+      return;
+    const failedScripts = [...install.output.matchAll(/(?:pre|post)?install script from "([^"]+)" exited/g)].map((match) => match[1] ?? "");
+    const tolerable = failedScripts.length > 0 && failedScripts.every((pkg) => this.tolerateScriptFailures.includes(pkg));
+    if (!tolerable)
+      throw new Error(`bun install failed \u2014 see ${logPath}`);
+    envWarnings.push(`install script failed for ${failedScripts.join(", ")} \u2014 tolerated on ${this.platform}`);
+    const relink = await this.exec("bun install --frozen-lockfile --ignore-scripts", this.#logPath(context, "install-relink"), PlatformTestTarget.installIdleMs);
+    if (relink.exitCode !== 0)
+      throw new Error(`bun install --ignore-scripts failed \u2014 see ${logPath}`);
+  }
+  #logPath(context, name) {
+    return path2.join(context.logDir, this.platform, `${name}.log`);
+  }
+}
+
+// pkgs/@akanjs/devkit/platformTest/LinuxDockerTarget.ts
+class LinuxDockerTarget extends PlatformTestTarget {
+  static cacheVolume = "akan-test-bun-cache";
+  platform = "linux";
+  policy;
+  #config;
+  #container = null;
+  constructor(config = {}) {
+    super();
+    this.#config = config;
+    this.policy = config.policy ?? "gate";
+  }
+  static dockerfile = [
+    `FROM oven/bun:${Bun.version}-slim`,
+    "RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates procps lsof && rm -rf /var/lib/apt/lists/*"
+  ].join(`
+`);
+  get image() {
+    return `akan-test-linux:bun-${Bun.version}-${Bun.hash(LinuxDockerTarget.dockerfile).toString(16).slice(0, 8)}`;
+  }
+  async prepare(context) {
+    if ((await LinuxDockerTarget.#docker(["info"])).exitCode !== 0)
+      throw new Error("Docker is not running \u2014 start Docker Desktop, or leave linux out of --platforms");
+    await this.#ensureImage();
+    const container = `akan-test-${context.runId}`;
+    const cpus = this.#config.cpus ?? Math.max(2, Math.floor(os.availableParallelism() / 2));
+    const started = await LinuxDockerTarget.#docker([
+      "run",
+      "-d",
+      "--rm",
+      "--name",
+      container,
+      "--cpus",
+      String(cpus),
+      ...this.#config.memory ? ["--memory", this.#config.memory] : [],
+      "-v",
+      `${LinuxDockerTarget.cacheVolume}:/root/.bun/install/cache`,
+      "-v",
+      `${path3.dirname(context.snapshot.tarPath)}:/io:ro`,
+      "-v",
+      `${context.envPath}:/io-env:ro`,
+      "-w",
+      "/w",
+      this.image,
+      "sleep",
+      "infinity"
+    ]);
+    if (started.exitCode !== 0)
+      throw new Error(`docker run failed: ${started.stderr.trim()}`);
+    this.#container = container;
+    const extract = await this.exec(`tar -xf /io/${path3.basename(context.snapshot.tarPath)} -C /w && cp /io-env /w/.env && git -C /w init -q`, path3.join(context.logDir, this.platform, "extract.log"), PlatformTestTarget.installIdleMs);
+    if (extract.exitCode !== 0)
+      throw new Error("extracting the snapshot into the container failed");
+  }
+  async exec(command, logPath, idleMs) {
+    const container = this.#container;
+    if (!container)
+      throw new Error("the linux container is not running");
+    return await new IdleWatchedProcess(["docker", "exec", ...LinuxDockerTarget.#gitIdentityEnv(), container, "sh", "-c", command], {
+      logPath,
+      idleMs,
+      onIdle: async () => {
+        await LinuxDockerTarget.#docker(["exec", container, "pkill", "-9", "bun"]);
+      }
+    }).run();
+  }
+  async cleanup() {
+    if (this.#container)
+      await LinuxDockerTarget.#docker(["rm", "-f", this.#container]);
+    this.#container = null;
+  }
+  async#ensureImage() {
+    if ((await LinuxDockerTarget.#docker(["image", "inspect", this.image])).exitCode === 0)
+      return;
+    const built = await LinuxDockerTarget.#docker(["build", "-t", this.image, "-"], LinuxDockerTarget.dockerfile);
+    if (built.exitCode !== 0)
+      throw new Error(`building ${this.image} failed: ${built.stderr.trim().slice(-400)}`);
+  }
+  static #gitIdentityEnv() {
+    return Object.entries({
+      GIT_AUTHOR_NAME: "akan-test",
+      GIT_AUTHOR_EMAIL: "akan-test@localhost",
+      GIT_COMMITTER_NAME: "akan-test",
+      GIT_COMMITTER_EMAIL: "akan-test@localhost",
+      GIT_CONFIG_COUNT: "1",
+      GIT_CONFIG_KEY_0: "init.defaultBranch",
+      GIT_CONFIG_VALUE_0: "main"
+    }).flatMap(([key, value]) => ["-e", `${key}=${value}`]);
+  }
+  static async#docker(args, stdin) {
+    const proc = Bun.spawn(["docker", ...args], {
+      stdin: stdin === undefined ? "ignore" : new Response(stdin),
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    return { stdout, stderr, exitCode };
+  }
+}
+
+// pkgs/@akanjs/devkit/platformTest/TestSnapshot.ts
+import { mkdir as mkdir2, stat, writeFile } from "fs/promises";
+import path4 from "path";
+
+class TestSnapshot {
+  static #secretPatterns = [
+    /(^|\/)\.env(\.(?!(template|example|sample)$)[^/]+)?$/,
+    /(^|\/)env\/env\.(client|server)\.(?!(type|example)\.ts$)[^/]+\.ts$/
+  ];
+  root;
+  tarPath;
+  digest;
+  #hashes;
+  constructor(root, tarPath, hashes) {
+    this.root = root;
+    this.tarPath = tarPath;
+    this.#hashes = hashes;
+    this.digest = TestSnapshot.#digestOf(hashes);
+  }
+  get fileCount() {
+    return this.#hashes.size;
+  }
+  static async create(root, outDir) {
+    const hashes = await TestSnapshot.#hashTree(root);
+    const untracked = await TestSnapshot.#gitList(root, ["--others", "--exclude-standard"]);
+    const secrets = untracked.filter((file) => TestSnapshot.#secretPatterns.some((re) => re.test(file)));
+    if (secrets.length)
+      throw new Error(`Refusing to snapshot env files git does not ignore \u2014 they would be copied to every test target: ${secrets.join(", ")}`);
+    await mkdir2(outDir, { recursive: true });
+    const listPath = path4.join(outDir, "files.txt");
+    const tarPath = path4.join(outDir, "src.tar");
+    await writeFile(listPath, `${[...hashes.keys()].join(`
+`)}
+`);
+    const tar = Bun.spawn(["tar", ...process.platform === "darwin" ? ["--no-xattrs"] : [], "-cf", tarPath, "-T", listPath], { cwd: root, env: { ...process.env, COPYFILE_DISABLE: "1" }, stdout: "ignore", stderr: "pipe" });
+    if (await tar.exited !== 0)
+      throw new Error(`tar failed: ${await new Response(tar.stderr).text()}`);
+    return new TestSnapshot(root, tarPath, hashes);
+  }
+  async drift() {
+    const current = await TestSnapshot.#hashTree(this.root);
+    const changed = [...current].filter(([file, hash]) => this.#hashes.has(file) && this.#hashes.get(file) !== hash);
+    return {
+      changed: changed.map(([file]) => file),
+      added: [...current.keys()].filter((file) => !this.#hashes.has(file)),
+      removed: [...this.#hashes.keys()].filter((file) => !current.has(file))
+    };
+  }
+  static async#gitList(root, args) {
+    const proc = Bun.spawn(["git", "ls-files", ...args, "-z"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    if (exitCode !== 0)
+      throw new Error(`git ls-files failed in ${root}: ${stderr.trim()}`);
+    return [...new Set(stdout.split("\x00").filter(Boolean))].sort();
+  }
+  static async#listFiles(root) {
+    const listed = await TestSnapshot.#gitList(root, ["--cached", "--others", "--exclude-standard"]);
+    const present = await Promise.all(listed.map(async (file) => (await stat(path4.join(root, file)).catch(() => null))?.isFile() ? file : null));
+    return present.filter((file) => file !== null);
+  }
+  static async#hashTree(root) {
+    const files = await TestSnapshot.#listFiles(root);
+    const hashes = new Map;
+    for (let start = 0;start < files.length; start += 64) {
+      const batch = files.slice(start, start + 64);
+      const batchHashes = await Promise.all(batch.map(async (file) => Bun.hash(await Bun.file(path4.join(root, file)).bytes()).toString(16)));
+      for (const [idx, file] of batch.entries())
+        hashes.set(file, batchHashes[idx] ?? "");
+    }
+    return hashes;
+  }
+  static #digestOf(hashes) {
+    return Bun.hash([...hashes].map(([file, hash]) => `${file}:${hash}`).join(`
+`)).toString(16).padStart(16, "0").slice(0, 12);
+  }
+}
+
+// pkgs/@akanjs/devkit/platformTest/WindowsSshTarget.ts
+import { existsSync } from "fs";
+import os2 from "os";
+import path5 from "path";
+class WindowsSshTarget extends PlatformTestTarget {
+  static utmctlPath = "/Applications/UTM.app/Contents/MacOS/utmctl";
+  static defaultWorkRoot = "C:\\akan-test";
+  static defaultTolerateScriptFailures = ["sharp", "puppeteer"];
+  static #runDirPattern = "^\\d{8}-\\d{6}$";
+  static #keptRuns = 2;
+  platform = "windows";
+  policy;
+  tolerateScriptFailures;
+  #config;
+  #host;
+  #runDir = null;
+  constructor(config) {
+    super();
+    this.#config = config;
+    this.#host = process.env.AKAN_TEST_WINDOWS_HOST ?? config.host;
+    this.policy = config.policy ?? "warn";
+    this.tolerateScriptFailures = config.tolerateScriptFailures ?? WindowsSshTarget.defaultTolerateScriptFailures;
+  }
+  get #workRoot() {
+    return this.#config.workRoot ?? WindowsSshTarget.defaultWorkRoot;
+  }
+  async prepare(context) {
+    await this.#connect();
+    const bunVersion = (await this.#ssh("bun --version")).stdout.trim();
+    if (bunVersion !== Bun.version)
+      throw new Error(`the Windows host runs Bun ${bunVersion || "(none)"}, this host ${Bun.version} \u2014 align them first`);
+    if ((await this.#ssh("git --version")).exitCode !== 0)
+      throw new Error("git is not installed on the Windows host");
+    const runDir = `${this.#workRoot}\\${context.runId}`;
+    const mkdir = await this.#ssh(`New-Item -ItemType Directory -Force -Path '${runDir}\\w' | Out-Null`);
+    if (mkdir.exitCode !== 0)
+      throw new Error(`could not create ${runDir}: ${mkdir.stderr.trim()}`);
+    this.#runDir = runDir;
+    for (const [local, remoteName] of [
+      [context.snapshot.tarPath, "src.tar"],
+      [context.envPath, "env"]
+    ]) {
+      const copied = await WindowsSshTarget.#run([
+        ...this.#scpBase(),
+        local,
+        this.#remoteScpPath(`${runDir}\\${remoteName}`)
+      ]);
+      if (copied.exitCode !== 0)
+        throw new Error(`scp ${remoteName} failed: ${copied.stderr.trim()}`);
+    }
+    const extract = await this.exec("tar -xf ..\\src.tar && copy /Y ..\\env .env >nul && git init -q", path5.join(context.logDir, this.platform, "extract.log"), PlatformTestTarget.installIdleMs);
+    if (extract.exitCode !== 0)
+      throw new Error("extracting the snapshot on the Windows host failed");
+  }
+  async exec(command, logPath, idleMs) {
+    const runDir = this.#runDir;
+    if (!runDir)
+      throw new Error("the Windows run directory was not prepared");
+    let remotePid = null;
+    const script = [
+      "$ProgressPreference = 'SilentlyContinue'",
+      "[Console]::OutputEncoding = [Text.Encoding]::UTF8",
+      "'PID=' + $PID",
+      "$env:GIT_AUTHOR_NAME = 'akan-test'",
+      "$env:GIT_AUTHOR_EMAIL = 'akan-test@localhost'",
+      "$env:GIT_COMMITTER_NAME = 'akan-test'",
+      "$env:GIT_COMMITTER_EMAIL = 'akan-test@localhost'",
+      "$env:GIT_CONFIG_COUNT = '1'",
+      "$env:GIT_CONFIG_KEY_0 = 'init.defaultBranch'",
+      "$env:GIT_CONFIG_VALUE_0 = 'main'",
+      `Set-Location -LiteralPath '${runDir}\\w'`,
+      `cmd /c "${command} 2>&1"`,
+      "exit $LASTEXITCODE"
+    ].join("; ");
+    return await new IdleWatchedProcess([...this.#sshBase(), script], {
+      logPath,
+      idleMs,
+      onOutput: (text) => {
+        remotePid ??= /PID=(\d+)/.exec(text)?.[1] ?? null;
+      },
+      onIdle: async () => {
+        if (remotePid)
+          await this.#ssh(`taskkill /F /T /PID ${remotePid} | Out-Null`);
+      }
+    }).run();
+  }
+  async cleanup() {
+    this.#runDir = null;
+    await this.#ssh([
+      `Get-ChildItem -LiteralPath '${this.#workRoot}' -Directory`,
+      `Where-Object { $_.Name -match '${WindowsSshTarget.#runDirPattern}' }`,
+      "Sort-Object Name -Descending",
+      `Select-Object -Skip ${WindowsSshTarget.#keptRuns}`,
+      "ForEach-Object { cmd /c rmdir /s /q $_.FullName }"
+    ].join(" | "));
+  }
+  async#connect() {
+    if ((await this.#ssh("exit 0")).exitCode === 0)
+      return;
+    const vm = this.#config.utmVm;
+    if (!vm || !existsSync(WindowsSshTarget.utmctlPath))
+      throw new Error(`cannot reach ${this.#config.user}@${this.#host} over ssh`);
+    const status = (await WindowsSshTarget.#run([WindowsSshTarget.utmctlPath, "status", vm])).stdout.trim();
+    if (status !== "started")
+      await WindowsSshTarget.#run([WindowsSshTarget.utmctlPath, "start", vm]);
+    for (let attempt = 0;attempt < 24; attempt++) {
+      const addresses = (await WindowsSshTarget.#run([WindowsSshTarget.utmctlPath, "ip-address", vm])).stdout;
+      const ipv4 = addresses.split(/\s+/).find((address) => /^\d+\.\d+\.\d+\.\d+$/.test(address));
+      if (ipv4)
+        this.#host = ipv4;
+      if ((await this.#ssh("exit 0")).exitCode === 0)
+        return;
+      await Bun.sleep(5000);
+    }
+    throw new Error(`UTM VM "${vm}" did not answer ssh at ${this.#host}`);
+  }
+  #sshOptions() {
+    const expand = (file) => file.startsWith("~/") ? path5.join(os2.homedir(), file.slice(2)) : file;
+    return [
+      "-i",
+      expand(this.#config.identityFile),
+      ...this.#config.knownHostsFile ? ["-o", `UserKnownHostsFile=${expand(this.#config.knownHostsFile)}`] : [],
+      "-o",
+      "BatchMode=yes",
+      "-o",
+      "ConnectTimeout=8",
+      "-o",
+      "ServerAliveInterval=30"
+    ];
+  }
+  #sshBase() {
+    return ["ssh", ...this.#sshOptions(), `${this.#config.user}@${this.#host}`];
+  }
+  #scpBase() {
+    return ["scp", "-q", ...this.#sshOptions()];
+  }
+  #remoteScpPath(windowsPath) {
+    return `${this.#config.user}@${this.#host}:/${windowsPath.replaceAll("\\", "/")}`;
+  }
+  async#ssh(script) {
+    return await WindowsSshTarget.#run([...this.#sshBase(), script]);
+  }
+  static async#run(command) {
+    const proc = Bun.spawn(command, { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    return { stdout, stderr, exitCode };
+  }
+}
+
+// pkgs/@akanjs/devkit/platformTest/PlatformTestRun.ts
+class PlatformTestRun {
+  static envKeys = [
+    "USE_AKANJS_PKGS",
+    "AKAN_PUBLIC_REPO_NAME",
+    "AKAN_PUBLIC_SERVE_DOMAIN",
+    "AKAN_PUBLIC_ENV",
+    "AKAN_PUBLIC_OPERATION_MODE",
+    "APP_OPERATION_MODE",
+    "SERVER_MODE"
+  ];
+  static promoteAfterGreenRuns = 3;
+  runId;
+  logDir;
+  snapshot;
+  #results;
+  constructor(runId, logDir, snapshot, results) {
+    this.runId = runId;
+    this.logDir = logDir;
+    this.snapshot = snapshot;
+    this.#results = results;
+  }
+  static async start({ workspaceRoot, platforms, pkgs, targets, onProgress }) {
+    const runId = PlatformTestRun.newRunId();
+    const logDir = path6.join(workspaceRoot, "local", "deploy-test", runId);
+    const snapshot = await TestSnapshot.create(workspaceRoot, logDir);
+    const envPath = path6.join(logDir, "env");
+    await Bun.write(envPath, await PlatformTestRun.allowlistedEnv(workspaceRoot));
+    const instances = platforms.map((platform) => {
+      if (platform === "linux")
+        return new LinuxDockerTarget(targets.linux);
+      if (!targets.windows)
+        throw new Error("the windows test target is not configured");
+      return new WindowsSshTarget(targets.windows);
+    });
+    const results = Promise.all(instances.map((target) => target.run({ snapshot, envPath, runId, logDir, pkgs, onProgress })));
+    return new PlatformTestRun(runId, logDir, snapshot, results);
+  }
+  async results() {
+    return await this.#results;
+  }
+  static parsePlatforms(value) {
+    const names = value.split(",").map((name) => name.trim().toLowerCase()).filter((name) => name && name !== "none");
+    const unknown = names.filter((name) => name !== "linux" && name !== "windows");
+    if (unknown.length)
+      throw new Error(`Unknown test platform: ${unknown.join(", ")} (expected linux, windows, or none)`);
+    return [...new Set(names)];
+  }
+  static newRunId(now = new Date) {
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  }
+  static async allowlistedEnv(workspaceRoot) {
+    const envFile = Bun.file(path6.join(workspaceRoot, ".env"));
+    const lines = await envFile.exists() ? (await envFile.text()).split(/\r?\n/) : [];
+    const allowed = new Set(PlatformTestRun.envKeys);
+    const kept = lines.filter((line) => allowed.has(line.split("=", 1)[0]?.trim() ?? ""));
+    return `${kept.join(`
+`)}
+`;
+  }
+  static failed(result) {
+    return !!result.infraError || result.packages.some((pkg) => pkg.status !== "pass");
+  }
+  static verdict(results) {
+    const failed = results.filter((result) => PlatformTestRun.failed(result));
+    return {
+      blocking: failed.filter((result) => result.policy === "gate"),
+      warning: failed.filter((result) => result.policy === "warn")
+    };
+  }
+  format(results, { maxFailures = 15 } = {}) {
+    const lines = [
+      chalk.bold(`Platform tests \xB7 snapshot ${this.snapshot.digest} (${this.snapshot.fileCount} files) \xB7 ${path6.relative(this.snapshot.root, this.logDir)}`)
+    ];
+    for (const result of results) {
+      const mark = PlatformTestRun.failed(result) ? chalk.red("\u2716") : chalk.green("\u2714");
+      lines.push(`${mark} ${result.platform} (${result.policy}, ${Math.round(result.ms / 1000)}s)`);
+      if (result.infraError)
+        lines.push(chalk.red(`    setup: ${result.infraError}`));
+      for (const warning of result.envWarnings)
+        lines.push(chalk.yellow(`    env: ${warning}`));
+      for (const pkg of result.packages) {
+        const line = `    ${PlatformTestTarget.describe(pkg)}`;
+        lines.push(pkg.status === "pass" ? line : chalk.red(line));
+        for (const failure of pkg.report.failures.slice(0, maxFailures))
+          lines.push(chalk.dim(`      ${failure.file ? `${failure.file} \u203A ` : ""}${failure.name}`));
+        if (pkg.report.failures.length > maxFailures)
+          lines.push(chalk.dim(`      \u2026 ${pkg.report.failures.length - maxFailures} more in ${pkg.logPath}`));
+      }
+    }
+    return lines.join(`
+`);
+  }
+  static async recordStreaks(results) {
+    const targets = await GlobalConfig.getTestTargets();
+    const windows = targets.windows;
+    const result = results.find((one) => one.platform === "windows");
+    if (!windows || !result || (windows.policy ?? "warn") !== "warn")
+      return null;
+    const greenStreak = PlatformTestRun.failed(result) ? 0 : (windows.greenStreak ?? 0) + 1;
+    const promoted = greenStreak >= PlatformTestRun.promoteAfterGreenRuns;
+    await GlobalConfig.setTestTargets({
+      windows: { ...windows, greenStreak, ...promoted ? { policy: "gate" } : {} }
+    });
+    return { platform: "windows", greenStreak, promoted };
+  }
+}
+
+// pkgs/@akanjs/cli/cloud/cloud.runner.ts
+import path7 from "path";
+import { confirm, input, select } from "@inquirer/prompts";
+import { Logger, sleep } from "akanjs/common";
+import chalk2 from "chalk";
+import * as QRcode from "qrcode";
+
+// pkgs/@akanjs/cli/npmRegistry.ts
+var defaultNpmRegistry = "https://registry.npmjs.org";
+var getNpmRegistryUrl = (registryUrl = process.env.AKAN_NPM_REGISTRY ?? defaultNpmRegistry) => registryUrl.replace(/\/+$/, "");
+async function getLatestPackageVersion(packageName, tag = "latest", registryUrl) {
+  const registry = getNpmRegistryUrl(registryUrl);
+  const url = `${registry}/${encodeURIComponent(packageName).replace(/^%40/, "@")}`;
+  const res = await fetch(url);
+  if (!res.ok)
+    throw new Error(`Failed to fetch ${packageName} metadata from ${registry}`);
+  const metadata = await res.json();
+  const version = metadata["dist-tags"]?.[tag];
+  if (!version)
+    throw new Error(`No npm dist-tag "${tag}" found for ${packageName}`);
+  return version;
+}
+
+// pkgs/@akanjs/cli/cloud/cloud.runner.ts
+var addRemoteEnvServerValue = "__addRemoteEnvServer";
+var removeRemoteEnvServerValue = "__removeRemoteEnvServer";
+
+class CloudRunner extends runner("cloud") {
+  #akanFrameworkPackages = new Set(["akanjs", "@akanjs/devkit", "@akanjs/cli", "create-akan-workspace"]);
+  #getRegistryArgs(registryUrl) {
+    return registryUrl ? ["--registry", getNpmRegistryUrl(registryUrl)] : [];
+  }
+  #getLocalRegistryAuthArgs(registryUrl) {
+    if (!registryUrl)
+      return [];
+    const { host, pathname } = new URL(getNpmRegistryUrl(registryUrl));
+    const registryPath = pathname === "/" ? "/" : `${pathname.replace(/\/+$/, "")}/`;
+    return [`--//${host}${registryPath}:_authToken=akan-local-registry`];
+  }
+  #getRegistryEnv(registryUrl) {
+    return registryUrl ? {
+      ...process.env,
+      AKAN_NPM_REGISTRY: getNpmRegistryUrl(registryUrl),
+      NPM_CONFIG_REGISTRY: getNpmRegistryUrl(registryUrl)
+    } : process.env;
+  }
+  async#addRemoteEnvServer() {
+    const name = (await input({
+      message: "Remote server name: ",
+      validate: (value) => value.trim() ? true : "Remote server name is required"
+    })).trim();
+    const host = (await input({
+      message: "Remote server host: ",
+      validate: (value) => value.trim() ? true : "Remote server host is required"
+    })).trim();
+    const username = (await input({ message: "Remote server username (optional): " })).trim() || undefined;
+    const portInput = (await input({
+      message: "Remote server SSH port (optional): ",
+      validate: (value) => {
+        const trimmed = value.trim();
+        if (!trimmed)
+          return true;
+        const port = Number(trimmed);
+        return Number.isInteger(port) && port > 0 ? true : "SSH port must be a positive integer";
+      }
+    })).trim();
+    const config = {
+      host,
+      ...username ? { username } : {},
+      ...portInput ? { port: Number(portInput) } : {}
+    };
+    await GlobalConfig.setRemoteEnvServer(name, config);
+    return { name, config };
+  }
+  async#selectRemoteEnvServer() {
+    const servers = await GlobalConfig.getRemoteEnvServers();
+    const serverEntries = Object.entries(servers).sort(([nameA], [nameB]) => nameA.localeCompare(nameB));
+    if (serverEntries.length === 0) {
+      Logger.info("No remote env servers configured. Add the first remote server for SCP mode.");
+      return await this.#addRemoteEnvServer();
+    }
+    const selectedName = await select({
+      message: "Select the remote env server",
+      choices: [
+        ...serverEntries.map(([name, config]) => ({
+          name: `${name} (${config.username ? `${config.username}@` : ""}${config.host}${config.port ? `:${config.port}` : ""})`,
+          value: name
+        })),
+        { name: "Add new remote server", value: addRemoteEnvServerValue },
+        { name: "Remove remote server", value: removeRemoteEnvServerValue }
+      ]
+    });
+    if (selectedName === addRemoteEnvServerValue)
+      return await this.#addRemoteEnvServer();
+    if (selectedName === removeRemoteEnvServerValue) {
+      await this.#removeRemoteEnvServer(serverEntries);
+      return await this.#selectRemoteEnvServer();
+    }
+    const config = servers[selectedName];
+    if (!config)
+      throw new Error(`Remote env server is not found: ${selectedName}`);
+    return { name: selectedName, config };
+  }
+  async#removeRemoteEnvServer(serverEntries) {
+    const selectedName = await select({
+      message: "Select the remote env server to remove",
+      choices: serverEntries.map(([name, config]) => ({
+        name: `${name} (${config.username ? `${config.username}@` : ""}${config.host}${config.port ? `:${config.port}` : ""})`,
+        value: name
+      }))
+    });
+    const shouldRemove = await confirm({
+      message: `Remove remote env server "${selectedName}"?`,
+      default: false
+    });
+    if (!shouldRemove)
+      return;
+    await GlobalConfig.removeRemoteEnvServer(selectedName);
+    Logger.info(`Removed remote env server "${selectedName}"`);
+  }
+  async#getRemoteEnvServerWithUsername() {
+    const remoteServer = await this.#selectRemoteEnvServer();
+    if (remoteServer.config.username)
+      return remoteServer;
+    const username = (await input({
+      message: `SSH username for ${remoteServer.config.host} (optional): `
+    })).trim();
+    return {
+      ...remoteServer,
+      config: {
+        ...remoteServer.config,
+        ...username ? { username } : {}
+      }
+    };
+  }
+  #getRemoteEnvArchivePath() {
+    return `${this.#getRemoteEnvArchiveDir()}/env.tar`;
+  }
+  #getRemoteEnvArchiveDir() {
+    const { repoName } = WorkspaceExecutor.getBaseDevEnv();
+    return `~/secrets/${repoName}`;
+  }
+  #getScpTarget(config, remotePath) {
+    return `${config.username ? `${config.username}@` : ""}${config.host}:${remotePath}`;
+  }
+  #getSshTarget(config) {
+    return `${config.username ? `${config.username}@` : ""}${config.host}`;
+  }
+  #getScpArgs(config, source, target) {
+    return [...config.port ? ["-P", config.port.toString()] : [], source, target];
+  }
+  #getSshArgs(config, command) {
+    return [...config.port ? ["-p", config.port.toString()] : [], this.#getSshTarget(config), command];
+  }
+  async login(host, workspace) {
+    const config = await GlobalConfig.getHostConfig(host);
+    const cloudApi = new CloudApi(workspace, config);
+    const self = config.auth ? await cloudApi.getRemoteSelf() : null;
+    if (self) {
+      Logger.rawLog(chalk2.green(`
+\u2713 Already logged in akan cloud as ${self.nickname}
+`));
+      return true;
+    }
+    const remoteId = crypto.randomUUID();
+    const signinUrl = `${cloudApi.host}/remoteAuth?remoteId=${encodeURIComponent(remoteId)}`;
+    Logger.rawLog(chalk2.bold(`
+${chalk2.green("\u27A4")} Authentication Required`));
+    Logger.rawLog(chalk2.dim("Please visit or click the following URL:"));
+    Logger.rawLog(`${chalk2.cyan.underline(signinUrl)}
+`);
+    try {
+      const qrcode = await new Promise((resolve, reject) => {
+        QRcode.toString(signinUrl, { type: "terminal", small: true }, (err, data) => {
+          if (err)
+            reject(err);
+          resolve(data);
+        });
+      });
+      Logger.rawLog(qrcode);
+      await openBrowser(signinUrl);
+      Logger.rawLog(chalk2.dim("Opening browser..."));
+    } catch {
+      Logger.rawLog(chalk2.yellow("Could not open browser. Please visit the URL manually."));
+    }
+    Logger.rawLog(chalk2.dim("Waiting for authentication..."));
+    const MAX_RETRY = 300;
+    for (let i = 0;i < MAX_RETRY; i++) {
+      const accessToken = await cloudApi.getRemoteAuthToken(remoteId);
+      const self = await cloudApi.getRemoteSelf();
+      if (accessToken && self) {
+        await GlobalConfig.setHostConfig({ host: config.host, auth: { accessToken, self } });
+        Logger.rawLog(chalk2.green(`\r\u2713 Authentication successful!`));
+        Logger.rawLog(chalk2.green.bold(`
+\u2728 Welcome aboard, ${self.nickname ?? "anonymous"}!`));
+        Logger.rawLog(chalk2.dim(`You're now ready to use Akan CLI!
+`));
+        return true;
+      }
+      await sleep(2000);
+    }
+    throw new Error(chalk2.red("\u2716 Authentication timed out after 10 minutes. Please try again."));
+  }
+  async logout(host) {
+    const config = await GlobalConfig.getHostConfig(host);
+    if (config.auth?.self) {
+      await GlobalConfig.setHostConfig(getDefaultHostConfig(config.host));
+      Logger.rawLog(chalk2.magenta.bold(`
+\uD83D\uDC4B Goodbye, ${config.auth.self.nickname ?? "anonymous"}!`));
+      Logger.rawLog(chalk2.dim(`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+`));
+      Logger.rawLog(chalk2.cyan("You have been successfully logged out."));
+      Logger.rawLog(chalk2.dim(`Thank you for using Akan CLI. Come back soon! \uD83C\uDF1F
+`));
+    } else {
+      Logger.rawLog(chalk2.yellow.bold(`
+\u26A0\uFE0F  No active session found`));
+      Logger.rawLog(chalk2.dim(`You were not logged in to begin with
+`));
+    }
+  }
+  async startPlatformTests(workspace, platforms, pkgs) {
+    const targets = await GlobalConfig.getTestTargets();
+    if (platforms.includes("windows") && !targets.windows) {
+      targets.windows = await this.#askWindowsTestTarget();
+      await GlobalConfig.setTestTargets({ windows: targets.windows });
+    }
+    Logger.info(`Testing ${pkgs.join(", ")} on ${platforms.join(", ")} in the background...`);
+    return await PlatformTestRun.start({
+      workspaceRoot: workspace.workspaceRoot,
+      platforms,
+      pkgs,
+      targets,
+      onProgress: (message) => Logger.info(message)
+    });
+  }
+  async settlePlatformTests(run, { interactive, recordStreaks, checkDrift }) {
+    const results = await run.results();
+    Logger.rawLog(`
+${run.format(results)}
+`);
+    if (recordStreaks) {
+      const streak = await PlatformTestRun.recordStreaks(results);
+      if (streak?.promoted)
+        Logger.info(`${streak.platform} passed ${streak.greenStreak} deploys in a row and now gates every deploy`);
+    }
+    const { blocking, warning } = PlatformTestRun.verdict(results);
+    const unreachable = blocking.filter((result) => result.infraError && !result.packages.length);
+    const failing = blocking.filter((result) => !unreachable.includes(result));
+    if (failing.length)
+      throw new Error(`Platform tests failed on ${failing.map((result) => result.platform).join(", ")} \u2014 ${run.logDir}`);
+    for (const result of [...unreachable, ...warning]) {
+      const reason = result.infraError ?? "failing tests";
+      if (!interactive)
+        continue;
+      const proceed = await confirm({
+        message: `${result.platform} did not pass (${reason}). Continue without it?`,
+        default: false
+      });
+      if (!proceed)
+        throw new Error(`Stopped after ${result.platform} platform tests \u2014 ${run.logDir}`);
+    }
+    if (!interactive && unreachable.length)
+      throw new Error(`Could not run ${unreachable.map((result) => result.platform).join(", ")} \u2014 ${run.logDir}`);
+    if (!checkDrift)
+      return results;
+    const drift = await run.snapshot.drift();
+    const drifted = [...drift.changed, ...drift.added, ...drift.removed];
+    if (drifted.length)
+      throw new Error(`The tree changed while it was being tested, so the results do not describe what would be published: ${drifted.slice(0, 20).join(", ")}${drifted.length > 20 ? ", \u2026" : ""}`);
+    return results;
+  }
+  async#askWindowsTestTarget() {
+    Logger.info("No Windows test target is configured yet; it is saved to ~/.akan/config.json once entered.");
+    const host = (await input({ message: "Windows host (ip or name): ", validate: (value) => !!value.trim() })).trim();
+    const user = (await input({ message: "SSH user: ", validate: (value) => !!value.trim() })).trim();
+    const identityFile = (await input({ message: "SSH private key path: ", validate: (value) => !!value.trim() })).trim();
+    const knownHostsFile = (await input({ message: "known_hosts file (optional): " })).trim();
+    const utmVm = (await input({ message: "UTM VM name, to start it and find its ip (optional): " })).trim();
+    return {
+      host,
+      user,
+      identityFile,
+      ...knownHostsFile ? { knownHostsFile } : {},
+      ...utmVm ? { utmVm } : {}
+    };
+  }
+  async getAkanPkgs(workspace) {
+    const pkgs = await workspace.getPkgs();
+    return pkgs.filter((pkg) => pkg === "akanjs" || pkg === "create-akan-workspace" || pkg.startsWith("@akanjs/"));
+  }
+  async deployAkan(workspace, akanPkgs, { registryUrl, confirmPublish = true, tag: distTag } = {}) {
+    const registry = registryUrl ? getNpmRegistryUrl(registryUrl) : undefined;
+    const akanPackageJson = await workspace.readJson("pkgs/akanjs/package.json");
+    const [majorVersion, minorVersion, patchVersion, devPatchVersion] = akanPackageJson.version.split(".");
+    const isOfficialRelease = !devPatchVersion;
+    const targetVersionPrefix = isOfficialRelease ? `${majorVersion}.${minorVersion}` : `${majorVersion}.${minorVersion}.${patchVersion}`;
+    const tag = distTag ?? (isOfficialRelease ? "latest" : patchVersion.split("-").at(1) ?? "dev");
+    const getNextVersion = async (prefix, tag) => {
+      try {
+        const latestPublishedVersion = await getLatestPackageVersion("akanjs", tag, registry);
+        const latestPatch = latestPublishedVersion.startsWith(prefix) ? parseInt(latestPublishedVersion.split(".").at(-1) ?? "-1") : -1;
+        const nextVersion = `${prefix}.${latestPatch + 1}`;
+        return { nextVersion, latestPublishedVersion };
+      } catch {
+        return { nextVersion: `${prefix}.0`, latestPublishedVersion: null };
+      }
+    };
+    const { nextVersion, latestPublishedVersion } = await getNextVersion(targetVersionPrefix, tag);
+    Logger.info(`Latest published version of akanjs: ${latestPublishedVersion ?? "none"}`);
+    Logger.info(`Next version of akanjs: ${nextVersion}`);
+    for (const library of akanPkgs) {
+      const packageJson = await workspace.readJson(`pkgs/${library}/package.json`);
+      const newPackageJsonStr = JSON.stringify(this.#normalizeAkanPackageJson(packageJson, library, nextVersion), null, 2);
+      await workspace.writeFile(`pkgs/${library}/package.json`, newPackageJsonStr);
+      const distPackageJson = await workspace.readJson(`dist/pkgs/${library}/package.json`);
+      const newDistPackageJson = this.#normalizeAkanPackageJson(distPackageJson, library, nextVersion);
+      await workspace.writeJson(`dist/pkgs/${library}/package.json`, newDistPackageJson);
+    }
+    if (confirmPublish) {
+      const isDeployConfirmed = await confirm({
+        message: "Are you sure you want to deploy the libraries?"
+      });
+      if (!isDeployConfirmed) {
+        Logger.error("Deployment cancelled");
+        return;
+      }
+    }
+    if (!registry) {
+      Logger.info("Logging in to npm...");
+      await workspace.spawn("npm", ["login"], { stdio: "inherit" });
+      Logger.info("Logged in to npm");
+    }
+    for (const library of akanPkgs) {
+      Logger.info(`Publishing ${library}@${nextVersion} to ${registry ?? "npm"}...`);
+      await workspace.spawn("npm", ["publish", "--tag", tag, ...this.#getRegistryArgs(registry), ...this.#getLocalRegistryAuthArgs(registry)], {
+        cwd: path7.join(workspace.workspaceRoot, "dist/pkgs", library),
+        env: this.#getRegistryEnv(registry),
+        stdio: "inherit"
+      });
+      Logger.info(`${library}@${nextVersion} is published to ${registry ?? "npm"}`);
+    }
+    Logger.info(`All libraries are published to ${registry ?? "npm"}`);
+  }
+  async update(workspace, tag = "latest", { registryUrl } = {}) {
+    const registry = registryUrl ? getNpmRegistryUrl(registryUrl) : undefined;
+    const registryArgs = this.#getRegistryArgs(registry);
+    const env = this.#getRegistryEnv(registry);
+    const globalCliArgs = ["add", "-g", `@akanjs/cli@${tag}`, ...registryArgs];
+    if (!await workspace.exists("package.json"))
+      await workspace.spawn("bun", globalCliArgs, { env });
+    else
+      await Promise.all([
+        workspace.spawn("bun", globalCliArgs, { env }),
+        this.#updateAkanPkgs(workspace, tag, registry)
+      ]);
+  }
+  async#updateAkanPkgs(workspace, tag = "latest", registryUrl) {
+    const latestPublishedVersion = await getLatestPackageVersion("akanjs", tag, registryUrl);
+    const rootPackageJson = await workspace.getPackageJson();
+    if (!rootPackageJson.dependencies)
+      throw new Error("No dependencies found in package.json");
+    if (rootPackageJson.dependencies.akanjs)
+      rootPackageJson.dependencies.akanjs = latestPublishedVersion;
+    if (rootPackageJson.devDependencies?.akanjs)
+      rootPackageJson.devDependencies.akanjs = latestPublishedVersion;
+    if (rootPackageJson.dependencies["@akanjs/devkit"])
+      rootPackageJson.dependencies["@akanjs/devkit"] = latestPublishedVersion;
+    if (rootPackageJson.devDependencies?.["@akanjs/devkit"])
+      rootPackageJson.devDependencies["@akanjs/devkit"] = latestPublishedVersion;
+    await workspace.setPackageJson(rootPackageJson);
+    await workspace.spawn("bun", ["install", ...this.#getRegistryArgs(registryUrl)], {
+      env: this.#getRegistryEnv(registryUrl)
+    });
+  }
+  #normalizeAkanPackageJson(packageJson, packageName, version) {
+    const normalized = { ...packageJson, version };
+    for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+      const dependencies = normalized[field];
+      if (!dependencies)
+        continue;
+      normalized[field] = Object.fromEntries(Object.entries(dependencies).map(([dep, depVersion]) => [
+        dep,
+        dep !== packageName && this.#akanFrameworkPackages.has(dep) ? version : depVersion
+      ]));
+    }
+    return normalized;
+  }
+  async downloadEnv(cloudApi, workspace, workspaceId) {
+    await workspace.mkdir("local");
+    const localPath = await cloudApi.downloadEnv(workspaceId);
+    const relativePath = path7.relative(workspace.workspaceRoot, localPath).split(path7.sep).join("/");
+    await workspace.spawn("tar", ["-xf", relativePath], { cwd: workspace.workspaceRoot });
+    await workspace.remove(localPath);
+  }
+  async uploadEnv(cloudApi, workspaceId, filePath) {
+    const file = new File([Bun.file(filePath)], path7.basename(filePath));
+    await cloudApi.uploadEnv(workspaceId, file);
+  }
+  async downloadEnvByScp(workspace) {
+    const envArchivePath = "local/env.tar";
+    const remoteServer = await this.#getRemoteEnvServerWithUsername();
+    const remoteArchivePath = this.#getRemoteEnvArchivePath();
+    const remoteTarget = this.#getScpTarget(remoteServer.config, remoteArchivePath);
+    await workspace.mkdir("local");
+    await workspace.remove(envArchivePath);
+    try {
+      Logger.info(`Downloading env archive from remote server "${remoteServer.name}"...`);
+      await workspace.spawn("scp", this.#getScpArgs(remoteServer.config, remoteTarget, envArchivePath), {
+        cwd: workspace.workspaceRoot,
+        stdio: "inherit"
+      });
+      await workspace.spawn("tar", ["-xf", envArchivePath], {
+        cwd: workspace.workspaceRoot
+      });
+      await workspace.remove(envArchivePath);
+    } catch (error) {
+      throw new Error(`Failed to download env archive from remote server "${remoteServer.name}"`, { cause: error });
+    }
+  }
+  async uploadEnvByScp(workspace, filePath) {
+    const remoteServer = await this.#getRemoteEnvServerWithUsername();
+    const remoteArchiveDir = this.#getRemoteEnvArchiveDir();
+    const remoteArchivePath = this.#getRemoteEnvArchivePath();
+    const remoteTarget = this.#getScpTarget(remoteServer.config, remoteArchivePath);
+    try {
+      await workspace.spawn("ssh", this.#getSshArgs(remoteServer.config, `mkdir -p ${remoteArchiveDir}`), {
+        cwd: workspace.workspaceRoot,
+        stdio: "inherit"
+      });
+      Logger.info(`Uploading env archive to remote server "${remoteServer.name}"...`);
+      await workspace.spawn("scp", this.#getScpArgs(remoteServer.config, filePath, remoteTarget), {
+        cwd: workspace.workspaceRoot,
+        stdio: "inherit"
+      });
+    } catch (error) {
+      throw new Error(`Failed to upload env archive to remote server "${remoteServer.name}"`, { cause: error });
+    }
+  }
+  async gatherEnvFiles(workspace, { scope, archivePath = "local/env.tar" } = {}) {
+    const envFilePattern = /^env\.(client|server)\.(?!(type|example)\.ts$).+\.ts$/;
+    const [workspaceAppNames, workspaceLibNames] = await workspace.getExecs();
+    const appNames = scope?.apps ?? workspaceAppNames;
+    const libNames = scope?.libs ?? workspaceLibNames;
+    const envDirs = [
+      ...appNames.map((appName) => `apps/${appName}/env`),
+      ...libNames.map((libName) => `libs/${libName}/env`)
+    ];
+    const defaultEnvFilePaths = (await Promise.all(envDirs.map(async (envDir) => (await workspace.readdir(envDir)).filter((fileName) => envFilePattern.test(fileName)).map((fileName) => `${envDir}/${fileName}`)))).flat();
+    await this.#syncSecretGitignore(workspace, workspaceAppNames);
+    const customSecretPaths = await this.#gatherCustomSecretFiles(workspace, appNames);
+    const envFilePaths = [...new Set([...defaultEnvFilePaths, ...customSecretPaths])].sort();
+    await workspace.mkdir("local");
+    await workspace.remove(archivePath);
+    if (envFilePaths.length === 0)
+      throw new Error(scope ? `No environment files found to archive for ${appNames.join(", ") || "(no apps)"}` : "No environment files found to archive");
+    await workspace.spawn("tar", ["-cf", archivePath, ...envFilePaths], {
+      cwd: workspace.workspaceRoot
+    });
+    Logger.info(`Archived ${envFilePaths.length} environment files to ${archivePath}`);
+    return { files: envFilePaths, path: archivePath };
+  }
+  async#gatherCustomSecretFiles(workspace, appNames) {
+    const secretPaths = await Promise.all(appNames.map(async (appName) => {
+      const config = await AppExecutor.from(workspace, appName).getConfig();
+      const secretGlobs = config.secrets ?? [];
+      if (secretGlobs.length === 0)
+        return [];
+      const appDir = path7.join(workspace.workspaceRoot, "apps", appName);
+      return secretGlobs.flatMap((pattern) => Array.from(new Bun.Glob(pattern).scanSync({ cwd: appDir, onlyFiles: true })).map((match) => `apps/${appName}/${match.split(path7.sep).join("/")}`));
+    }));
+    return secretPaths.flat();
+  }
+  async#syncSecretGitignore(workspace, appNames) {
+    const patterns = (await Promise.all(appNames.map(async (appName) => {
+      const config = await AppExecutor.from(workspace, appName).getConfig();
+      return (config.secrets ?? []).map((pattern) => `apps/${appName}/${pattern.replace(/^\/+/, "")}`);
+    }))).flat();
+    const uniquePatterns = [...new Set(patterns)].sort();
+    const existing = await workspace.exists(".gitignore") ? await workspace.readFile(".gitignore") : "";
+    const nextContent = this.#applySecretGitignoreBlock(existing, uniquePatterns);
+    if (nextContent === existing)
+      return;
+    await workspace.writeFile(".gitignore", nextContent);
+    Logger.info(uniquePatterns.length ? `Synced ${uniquePatterns.length} secret pattern(s) from akan.config.ts to .gitignore` : "Removed managed secret patterns from .gitignore");
+  }
+  #applySecretGitignoreBlock(content, patterns) {
+    const beginMarker = "# akan:secrets (managed by akan.config.ts \u2014 do not edit)";
+    const endMarker = "# akan:secrets:end";
+    const lines = content.split(`
+`);
+    const beginIdx = lines.indexOf(beginMarker);
+    const endIdx = lines.indexOf(endMarker);
+    const stripped = beginIdx !== -1 && endIdx !== -1 && endIdx >= beginIdx ? [...lines.slice(0, beginIdx), ...lines.slice(endIdx + 1)] : [...lines];
+    while (stripped.length && stripped[stripped.length - 1]?.trim() === "")
+      stripped.pop();
+    if (patterns.length === 0)
+      return stripped.length ? `${stripped.join(`
+`)}
+` : "";
+    const body = stripped.length ? `${stripped.join(`
+`)}
+
+` : "";
+    return `${body}${[beginMarker, ...patterns, endMarker].join(`
+`)}
+`;
+  }
+}
+
+export { getNpmRegistryUrl, getLatestPackageVersion, PlatformTestRun, CloudRunner };