@shogo-ai/cli 1.4.1

package/dist/index.js

@@ -0,0 +1,31 @@
+import {
+  AGENT_NAME_PATTERN,
+  buildSyncPayload,
+  normalizeToolEntry,
+  runDeploy,
+  validateManifest
+} from "./chunk-YYO73V5H.js";
+import {
+  NodeMissingError,
+  PlatformPackageManager,
+  _resetUnixNodeCache,
+  isNodeAvailableOnUnix,
+  isNodeAvailableOnWindows,
+  pkg,
+  resolveBinInvocation
+} from "./chunk-UB4RE2UC.js";
+export {
+  AGENT_NAME_PATTERN,
+  NodeMissingError,
+  PlatformPackageManager,
+  _resetUnixNodeCache,
+  buildSyncPayload,
+  isNodeAvailableOnUnix,
+  isNodeAvailableOnWindows,
+  normalizeToolEntry,
+  pkg,
+  resolveBinInvocation,
+  runDeploy,
+  validateManifest
+};
+//# sourceMappingURL=index.js.map

package/dist/pkg.cjs

@@ -0,0 +1,457 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/pkg.ts
+var pkg_exports = {};
+__export(pkg_exports, {
+  NodeMissingError: () => NodeMissingError,
+  PlatformPackageManager: () => PlatformPackageManager,
+  _resetUnixNodeCache: () => _resetUnixNodeCache,
+  isNodeAvailableOnUnix: () => isNodeAvailableOnUnix,
+  isNodeAvailableOnWindows: () => isNodeAvailableOnWindows,
+  pkg: () => pkg,
+  resolveBinInvocation: () => resolveBinInvocation
+});
+module.exports = __toCommonJS(pkg_exports);
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var NodeMissingError = class extends Error {
+  constructor() {
+    super(
+      "Shogo Desktop on Windows requires Node.js 20+ to run project sandboxes. npm.cmd was not found on PATH and is not present at C:\\Program Files\\nodejs\\. Install Node.js from https://nodejs.org/ (LTS recommended), then restart Shogo."
+    );
+    this.code = "NODE_NOT_INSTALLED";
+    this.name = "NodeMissingError";
+  }
+};
+var WINDOWS_NODE_DIR = "C:\\Program Files\\nodejs";
+function isNodeAvailableOnWindows(pathEnv = process.env.PATH) {
+  if (process.platform !== "win32") return true;
+  if ((0, import_node_fs.existsSync)((0, import_node_path.join)(WINDOWS_NODE_DIR, "npm.cmd"))) return true;
+  if (!pathEnv) return false;
+  for (const dir of pathEnv.split(";")) {
+    if (dir && (0, import_node_fs.existsSync)((0, import_node_path.join)(dir, "npm.cmd"))) return true;
+  }
+  return false;
+}
+var _unixNodeAvailable = null;
+function isNodeAvailableOnUnix(pathEnv = process.env.PATH) {
+  if (process.platform === "win32") return false;
+  if (pathEnv === process.env.PATH && _unixNodeAvailable !== null) return _unixNodeAvailable;
+  let found = false;
+  if (pathEnv) {
+    for (const dir of pathEnv.split(":")) {
+      if (!dir) continue;
+      if ((0, import_node_fs.existsSync)((0, import_node_path.join)(dir, "node"))) {
+        found = true;
+        break;
+      }
+    }
+  }
+  if (pathEnv === process.env.PATH) _unixNodeAvailable = found;
+  return found;
+}
+function _resetUnixNodeCache() {
+  _unixNodeAvailable = null;
+}
+function resolveBinInvocation(workspaceDir, binName) {
+  const binDir = (0, import_node_path.join)(workspaceDir, "node_modules", ".bin");
+  const isWindows = process.platform === "win32";
+  const candidates = isWindows ? [(0, import_node_path.join)(binDir, `${binName}.CMD`), (0, import_node_path.join)(binDir, `${binName}.cmd`), (0, import_node_path.join)(binDir, `${binName}.exe`)] : [(0, import_node_path.join)(binDir, binName)];
+  const shim = candidates.find((p) => (0, import_node_fs.existsSync)(p));
+  if (!shim) return null;
+  if (isWindows) return { cmd: shim, argsPrefix: [] };
+  if (isNodeAvailableOnUnix()) return { cmd: shim, argsPrefix: [] };
+  try {
+    const st = (0, import_node_fs.lstatSync)(shim);
+    if (!st.isSymbolicLink()) return { cmd: shim, argsPrefix: [] };
+    const target = (0, import_node_fs.readlinkSync)(shim);
+    const jsEntry = (0, import_node_path.isAbsolute)(target) ? target : (0, import_node_path.resolve)((0, import_node_path.dirname)(shim), target);
+    if (!(0, import_node_fs.existsSync)(jsEntry)) return { cmd: shim, argsPrefix: [] };
+    const bun = process.env.SHOGO_BUN_PATH || "bun";
+    return { cmd: bun, argsPrefix: [jsEntry] };
+  } catch {
+    return { cmd: shim, argsPrefix: [] };
+  }
+}
+var IS_WINDOWS = process.platform === "win32";
+var DEFAULT_INSTALL_TIMEOUT = parseInt(
+  process.env.SHOGO_INSTALL_TIMEOUT_MS || (IS_WINDOWS ? "300000" : "300000"),
+  10
+);
+var DEFAULT_EXEC_TIMEOUT = 6e4;
+var PlatformPackageManager = class {
+  constructor() {
+    this.isWindows = IS_WINDOWS;
+  }
+  /** Resolved path to the bun binary — prefers SHOGO_BUN_PATH (set by desktop app) over bare `bun`. */
+  get bunBinary() {
+    return process.env.SHOGO_BUN_PATH || "bun";
+  }
+  shellOpt() {
+    return IS_WINDOWS ? true : void 0;
+  }
+  spawnEnv(base) {
+    const source = base ?? process.env;
+    const env = {};
+    let pathValue = "";
+    for (const [k, v] of Object.entries(source)) {
+      if (v === void 0) continue;
+      if (IS_WINDOWS && k.toLowerCase() === "path") {
+        if (v) pathValue = v;
+        continue;
+      }
+      env[k] = v;
+    }
+    if (IS_WINDOWS) {
+      const nodePath = "C:\\Program Files\\nodejs";
+      env.PATH = pathValue.includes(nodePath) ? pathValue : `${nodePath};${pathValue}`;
+    }
+    return env;
+  }
+  // ---------------------------------------------------------------------------
+  // Install — synchronous
+  // ---------------------------------------------------------------------------
+  installSync(cwd, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_INSTALL_TIMEOUT;
+    const stdio = opts?.stdio ?? "pipe";
+    const env = this.spawnEnv(opts?.env);
+    if (IS_WINDOWS) {
+      if (isNodeAvailableOnWindows(env.PATH)) {
+        try {
+          (0, import_node_child_process.execSync)("npm.cmd install --loglevel=error", {
+            cwd,
+            timeout,
+            stdio,
+            env,
+            shell: "cmd.exe"
+          });
+          return;
+        } catch (err) {
+          const wrapped = wrapWindowsNpmError(err);
+          if (!wrapped) throw err;
+        }
+      }
+      this.installSyncBunCopyfile(cwd, opts);
+      return;
+    }
+    const bun = this.bunBinary;
+    if (opts?.frozen) {
+      try {
+        (0, import_node_child_process.execSync)(`"${bun}" install --frozen-lockfile 2>&1`, { cwd, timeout, stdio, env });
+        return;
+      } catch {
+      }
+    }
+    (0, import_node_child_process.execSync)(`"${bun}" install`, { cwd, timeout, stdio, env });
+  }
+  /**
+   * Windows-only fallback path: `bun install [--frozen-lockfile]
+   * --backend=copyfile`. Used when npm.cmd isn't available on PATH
+   * (typically: Shogo Desktop bundles bun but the user didn't install
+   * Node.js separately).
+   *
+   * The `--backend=copyfile` flag forces bun to copy package contents
+   * into `node_modules/` instead of hardlinking from
+   * `~/.bun/install/cache`. Hardlinks are bun's default for speed but
+   * fail in confusing ways on Windows (the destination directory gets
+   * created but ends up empty, and downstream `require('webidl-conversions')`
+   * etc. then crash with MODULE_NOT_FOUND). See bun#10327 / #28653.
+   */
+  installSyncBunCopyfile(cwd, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_INSTALL_TIMEOUT;
+    const stdio = opts?.stdio ?? "pipe";
+    const env = this.spawnEnv(opts?.env);
+    const bun = this.bunBinary;
+    console.warn(
+      "[platform-pkg] Node.js / npm.cmd not found on PATH \u2014 falling back to `bun install --backend=copyfile` (Shogo Desktop bundle path). This is slower than hardlink but avoids the Windows extract bug."
+    );
+    if (opts?.frozen) {
+      try {
+        (0, import_node_child_process.execSync)(`"${bun}" install --frozen-lockfile --backend=copyfile`, {
+          cwd,
+          timeout,
+          stdio,
+          env
+        });
+        return;
+      } catch {
+      }
+    }
+    (0, import_node_child_process.execSync)(`"${bun}" install --backend=copyfile`, { cwd, timeout, stdio, env });
+  }
+  // ---------------------------------------------------------------------------
+  // Install — async with spawn (used by RuntimeManager)
+  // ---------------------------------------------------------------------------
+  installAsync(cwd, opts) {
+    if (IS_WINDOWS) {
+      const env = this.spawnEnv(opts?.env);
+      if (isNodeAvailableOnWindows(env.PATH)) {
+        return this.installAsyncWindowsNpm(cwd, opts).catch((err) => {
+          if (err instanceof NodeMissingError) {
+            return this.installAsyncBunCopyfile(cwd, opts);
+          }
+          throw err;
+        });
+      }
+      return this.installAsyncBunCopyfile(cwd, opts);
+    }
+    return this.installAsyncBun(cwd, opts);
+  }
+  installAsyncWindowsNpm(cwd, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_INSTALL_TIMEOUT;
+    const env = this.spawnEnv(opts?.env);
+    const cmd = "npm.cmd";
+    const args = ["install", "--loglevel=error"];
+    return new Promise((resolve, reject) => {
+      const proc = (0, import_node_child_process.spawn)(cmd, args, {
+        cwd,
+        stdio: "pipe",
+        env,
+        shell: true
+      });
+      const timer = setTimeout(() => {
+        proc.kill();
+        reject(new Error(`${cmd} install timed out after ${timeout / 1e3}s`));
+      }, timeout);
+      let stderr = "";
+      proc.stderr?.on("data", (d) => {
+        stderr += d.toString();
+      });
+      proc.on("exit", (code) => {
+        clearTimeout(timer);
+        if (code === 0) return resolve();
+        if (/not recognized as an internal or external command/i.test(stderr)) {
+          return reject(new NodeMissingError());
+        }
+        reject(new Error(`${cmd} install exited with code ${code}
+${stderr}`));
+      });
+      proc.on("error", (err) => {
+        clearTimeout(timer);
+        if (err.code === "ENOENT") return reject(new NodeMissingError());
+        reject(err);
+      });
+    });
+  }
+  installAsyncBunCopyfile(cwd, opts) {
+    console.warn(
+      "[platform-pkg] Node.js / npm.cmd not found on PATH \u2014 falling back to `bun install --backend=copyfile` (Shogo Desktop bundle path)."
+    );
+    return this.installAsyncBun(cwd, opts, ["--backend=copyfile"]);
+  }
+  installAsyncBun(cwd, opts, extraArgs = []) {
+    const timeout = opts?.timeout ?? DEFAULT_INSTALL_TIMEOUT;
+    const env = this.spawnEnv(opts?.env);
+    const bun = this.bunBinary;
+    const baseArgs = ["install", ...extraArgs];
+    const frozenArgs = opts?.frozen ? ["install", "--frozen-lockfile", ...extraArgs] : null;
+    const runOnce = (args) => new Promise((resolve, reject) => {
+      const proc = (0, import_node_child_process.spawn)(bun, args, {
+        cwd,
+        stdio: "pipe",
+        env
+      });
+      const timer = setTimeout(() => {
+        proc.kill();
+        reject(new Error(`bun ${args.join(" ")} timed out after ${timeout / 1e3}s`));
+      }, timeout);
+      let stderr = "";
+      proc.stderr?.on("data", (d) => {
+        stderr += d.toString();
+      });
+      proc.stdout?.on("data", () => {
+      });
+      proc.on("exit", (code) => {
+        clearTimeout(timer);
+        resolve({ ok: code === 0, stderr });
+      });
+      proc.on("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+    const run = async () => {
+      if (frozenArgs) {
+        const first = await runOnce(frozenArgs);
+        if (first.ok) return;
+      }
+      const second = await runOnce(baseArgs);
+      if (!second.ok) {
+        throw new Error(`bun install failed: ${second.stderr}`);
+      }
+    };
+    return run();
+  }
+  // ---------------------------------------------------------------------------
+  // Exec — run an npx/bunx tool synchronously
+  // ---------------------------------------------------------------------------
+  execToolSync(tool, args, cwd, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_EXEC_TIMEOUT;
+    const stdio = opts?.stdio ?? "pipe";
+    const env = this.spawnEnv(opts?.env);
+    const argStr = args.length > 0 ? ` ${args.join(" ")}` : "";
+    const bun = this.bunBinary;
+    const cmd = IS_WINDOWS ? `npx ${tool}${argStr}` : `"${bun}" x ${opts?.useBunFlag ? "--bun " : ""}${tool}${argStr}`;
+    return (0, import_node_child_process.execSync)(cmd, {
+      cwd,
+      timeout,
+      stdio,
+      env,
+      // shellOpt() returns `true` on Windows so Node/Bun pick the platform
+      // default shell from `process.env.ComSpec`. ExecSyncOptions only
+      // narrowly types `shell` as `string | undefined`, but the runtime
+      // accepts a boolean and the cross-platform behavior depends on it
+      // (see shellOpt() doc).
+      shell: this.shellOpt(),
+      encoding: "utf-8"
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Exec — async variant that DOES NOT block the JS event loop.
+  //
+  // The sync variant above is fine for one-shot project scaffolding
+  // (template.copy.ts) where blocking is intentional. Inside the runtime's
+  // hot path (PreviewManager.runPrismaIfNeeded → /pool/assign) it caused
+  // a measured ~4.7s freeze of /pool/assign in staging because prisma's
+  // child process held the event loop for the full duration. Always
+  // prefer this variant in long-lived services.
+  // ---------------------------------------------------------------------------
+  async execToolAsync(tool, args, cwd, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_EXEC_TIMEOUT;
+    const stdio = opts?.stdio ?? "pipe";
+    const env = this.spawnEnv(opts?.env);
+    let cmd;
+    let argv;
+    let useShell;
+    if (IS_WINDOWS) {
+      const argStr = args.length > 0 ? ` ${args.join(" ")}` : "";
+      cmd = `npx ${tool}${argStr}`;
+      argv = [];
+      useShell = true;
+    } else {
+      cmd = this.bunBinary;
+      argv = ["x"];
+      if (opts?.useBunFlag) argv.push("--bun");
+      argv.push(tool, ...args);
+      useShell = false;
+    }
+    return new Promise((resolvePromise, rejectPromise) => {
+      const proc = (0, import_node_child_process.spawn)(cmd, argv, {
+        cwd,
+        env,
+        stdio,
+        shell: useShell ? this.shellOpt() : false
+      });
+      let stdout = "";
+      let stderr = "";
+      proc.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+      proc.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+      const timer = setTimeout(() => {
+        try {
+          proc.kill("SIGKILL");
+        } catch {
+        }
+        rejectPromise(
+          new Error(`${tool} ${args.join(" ")} timed out after ${timeout}ms`)
+        );
+      }, timeout);
+      proc.on("error", (err) => {
+        clearTimeout(timer);
+        rejectPromise(err);
+      });
+      proc.on("exit", (code) => {
+        clearTimeout(timer);
+        if (code === 0) {
+          resolvePromise(stdout);
+        } else {
+          const errMsg = stderr.trim() || stdout.trim() || `exit ${code}`;
+          rejectPromise(new Error(`${tool} ${args.join(" ")} failed: ${errMsg}`));
+        }
+      });
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Prisma convenience wrappers
+  // ---------------------------------------------------------------------------
+  prismaGenerate(cwd, opts) {
+    this.execToolSync("prisma", ["generate"], cwd, {
+      timeout: opts?.timeout ?? 3e4,
+      stdio: opts?.stdio,
+      env: opts?.env
+    });
+  }
+  prismaDbPush(cwd, opts) {
+    const args = ["db", "push"];
+    if (opts?.acceptDataLoss) args.push("--accept-data-loss");
+    this.execToolSync("prisma", args, cwd, {
+      timeout: opts?.timeout ?? DEFAULT_EXEC_TIMEOUT,
+      stdio: opts?.stdio,
+      env: opts?.env
+    });
+  }
+  // Async siblings of the prisma wrappers above. Use these from any
+  // long-running service (runtime, agent gateway, preview manager) so a
+  // 1-3s prisma child process doesn't freeze /health, /pool/assign, or
+  // other concurrent HTTP work. Same arg shape, same timeout defaults.
+  async prismaGenerateAsync(cwd, opts) {
+    await this.execToolAsync("prisma", ["generate"], cwd, {
+      timeout: opts?.timeout ?? 3e4,
+      stdio: opts?.stdio,
+      env: opts?.env
+    });
+  }
+  async prismaDbPushAsync(cwd, opts) {
+    const args = ["db", "push"];
+    if (opts?.acceptDataLoss) args.push("--accept-data-loss");
+    await this.execToolAsync("prisma", args, cwd, {
+      timeout: opts?.timeout ?? DEFAULT_EXEC_TIMEOUT,
+      stdio: opts?.stdio,
+      env: opts?.env
+    });
+  }
+};
+function wrapWindowsNpmError(err) {
+  if (!IS_WINDOWS) return null;
+  const blob = `${err?.stderr?.toString?.() ?? ""}
+${err?.stdout?.toString?.() ?? ""}
+${err?.message ?? ""}`;
+  if (/not recognized as an internal or external command/i.test(blob)) {
+    return new NodeMissingError();
+  }
+  if (err?.code === "ENOENT") return new NodeMissingError();
+  return null;
+}
+var pkg = new PlatformPackageManager();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NodeMissingError,
+  PlatformPackageManager,
+  _resetUnixNodeCache,
+  isNodeAvailableOnUnix,
+  isNodeAvailableOnWindows,
+  pkg,
+  resolveBinInvocation
+});
+//# sourceMappingURL=pkg.cjs.map

package/dist/pkg.d.cts

@@ -0,0 +1,139 @@
+import { StdioOptions } from 'node:child_process';
+
+/**
+ * PlatformPackageManager — centralises Windows vs Unix differences for
+ * package-manager operations (install, exec, prisma, etc.).
+ *
+ * On Windows Bun 1.x's default hardlink backend can leave empty package
+ * directories in `node_modules/` (most visibly under transitive deps
+ * like `whatwg-url` → `webidl-conversions`, which then crashes any
+ * `expo export` / Vite build that imports them). We mitigate by
+ * preferring `npm.cmd` for installs when Node.js is on PATH; if it
+ * isn't (Shogo Desktop ships its own bun but not Node), we fall back
+ * to `bun install --backend=copyfile` which sidesteps the hardlink
+ * path entirely. The trade-off is a slower install vs. a half-broken
+ * `node_modules` that fails downstream commands without explanation.
+ *
+ * Lifted into the SDK from `@shogo/shared-runtime` (was AGPL) under MIT
+ * so the SDK CLI (`bin/shogo.ts`) and userland tooling can use it without
+ * dragging an AGPL runtime dependency into the published `@shogo-ai/sdk`
+ * package. Shogo Technologies, Inc. holds copyright; the file is
+ * dependency-free (only `node:child_process`, `node:fs`, `node:path`).
+ */
+
+interface PkgInstallOptions {
+    timeout?: number;
+    stdio?: StdioOptions;
+    env?: NodeJS.ProcessEnv;
+    /** Attempt --frozen-lockfile first, fall back to plain install (bun only). */
+    frozen?: boolean;
+}
+/** Error thrown when the Windows Node.js prerequisite is missing. */
+declare class NodeMissingError extends Error {
+    readonly code: "NODE_NOT_INSTALLED";
+    constructor();
+}
+/**
+ * True if npm.cmd can be located via PATH or the standard Windows install dir.
+ * Cheap — only a single existsSync + PATH walk — so safe to call from hot paths.
+ * Always returns true on non-Windows (bun is used there).
+ */
+declare function isNodeAvailableOnWindows(pathEnv?: string | undefined): boolean;
+/**
+ * True if a `node` binary is on PATH (Unix-style search). The Shogo
+ * Desktop API process is spawned by Electron with a PATH inherited
+ * from `launchctl`, which on macOS frequently EXCLUDES the user's
+ * shell-managed paths (Homebrew, nvm, asdf). `process.env.PATH` is
+ * what child spawns see when they exec a `#!/usr/bin/env node` shim,
+ * so this is the right thing to check.
+ *
+ * Cached for the lifetime of the process — node-install state doesn't
+ * change between project opens, and re-walking PATH on every spawn
+ * adds up.
+ *
+ * Pass an explicit `pathEnv` only from tests; production callers should
+ * use the default.
+ */
+declare function isNodeAvailableOnUnix(pathEnv?: string | undefined): boolean;
+/** Reset the cached node-availability probe — only used by tests. */
+declare function _resetUnixNodeCache(): void;
+/**
+ * Resolve a `node_modules/.bin/<name>` invocation that works whether
+ * or not a system `node` is on PATH.
+ *
+ * Why this exists: npm publishes its `.bin/<tool>` shims with
+ * `#!/usr/bin/env node` at the top of the underlying JS file. The
+ * kernel reads the shebang and tries to exec `/usr/bin/env node`;
+ * if `node` isn't on PATH the exec fails with `env: node: No such
+ * file or directory` and the spawn exits 127. Shogo Desktop ships
+ * the bundled `bun` runtime but does not bundle Node.js, and many
+ * end-user macOS PATHs (launchctl-default) don't expose any
+ * shell-installed node either — so every `spawn(.bin/vite, ...)`
+ * fails on first use. Observed in main.log:
+ *   [CanvasBuildManager] Build error: env: node: No such file or directory
+ *   [preview-manager] Vite build --watch exited (code=127, signal=null)
+ *
+ * Returns `null` if the shim doesn't exist (caller should treat
+ * this exactly like the historical `existsSync(viteBin)` no-op
+ * path). Otherwise returns `{ cmd, argsPrefix }`:
+ *   - On Windows, or when `node` is on PATH: the shim itself with
+ *     no prefix args (preserves the current behavior — fastest path).
+ *   - When node is missing on Unix: `readlinkSync` resolves the shim
+ *     to its underlying `.../bin/<tool>.js`, and we route through
+ *     the bundled `bun` (`{ cmd: bunBinary, argsPrefix: [jsEntry] }`),
+ *     which executes the JS directly and treats the shebang as a
+ *     comment. Bun's CLI compatibility is a superset of node for
+ *     the bundler tools we ship (vite, expo) — same exit codes,
+ *     same flag parsing.
+ */
+declare function resolveBinInvocation(workspaceDir: string, binName: string): {
+    cmd: string;
+    argsPrefix: string[];
+} | null;
+interface PkgExecOptions {
+    timeout?: number;
+    stdio?: StdioOptions;
+    env?: NodeJS.ProcessEnv;
+    /** Use `bunx --bun` instead of plain `bunx` (needed for some tools). */
+    useBunFlag?: boolean;
+}
+declare class PlatformPackageManager {
+    readonly isWindows: boolean;
+    /** Resolved path to the bun binary — prefers SHOGO_BUN_PATH (set by desktop app) over bare `bun`. */
+    get bunBinary(): string;
+    private shellOpt;
+    private spawnEnv;
+    installSync(cwd: string, opts?: PkgInstallOptions): void;
+    /**
+     * Windows-only fallback path: `bun install [--frozen-lockfile]
+     * --backend=copyfile`. Used when npm.cmd isn't available on PATH
+     * (typically: Shogo Desktop bundles bun but the user didn't install
+     * Node.js separately).
+     *
+     * The `--backend=copyfile` flag forces bun to copy package contents
+     * into `node_modules/` instead of hardlinking from
+     * `~/.bun/install/cache`. Hardlinks are bun's default for speed but
+     * fail in confusing ways on Windows (the destination directory gets
+     * created but ends up empty, and downstream `require('webidl-conversions')`
+     * etc. then crash with MODULE_NOT_FOUND). See bun#10327 / #28653.
+     */
+    private installSyncBunCopyfile;
+    installAsync(cwd: string, opts?: PkgInstallOptions): Promise<void>;
+    private installAsyncWindowsNpm;
+    private installAsyncBunCopyfile;
+    private installAsyncBun;
+    execToolSync(tool: string, args: string[], cwd: string, opts?: PkgExecOptions): string;
+    execToolAsync(tool: string, args: string[], cwd: string, opts?: PkgExecOptions): Promise<string>;
+    prismaGenerate(cwd: string, opts?: PkgExecOptions): void;
+    prismaDbPush(cwd: string, opts?: PkgExecOptions & {
+        acceptDataLoss?: boolean;
+    }): void;
+    prismaGenerateAsync(cwd: string, opts?: PkgExecOptions): Promise<void>;
+    prismaDbPushAsync(cwd: string, opts?: PkgExecOptions & {
+        acceptDataLoss?: boolean;
+    }): Promise<void>;
+}
+/** Singleton — most consumers just need one. */
+declare const pkg: PlatformPackageManager;
+
+export { NodeMissingError, type PkgExecOptions, type PkgInstallOptions, PlatformPackageManager, _resetUnixNodeCache, isNodeAvailableOnUnix, isNodeAvailableOnWindows, pkg, resolveBinInvocation };