primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

package/dist/src/lib/template.js

@@ -1,8 +1,50 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, renameSync, rmSync, statSync, } from "fs";
+import { cpSync, existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "fs";
+import { execFileSync } from "child_process";
 import { join } from "path";
+import { tmpdir } from "os";
 import * as tar from "tar";
-const TEMPLATE_URL = "https://github.com/Primitive-Labs/primitive-app-template/archive/refs/heads/main.tar.gz";
+import { PRODUCTION_SERVER_URL } from "./constants.js";
+import { installArgv, PRIMITIVE_CLI_PACKAGE } from "./package-manager.js";
+import { resolveChannelBranch, DEFAULT_CHANNEL_BRANCH } from "./channel.js";
+// Mirror repos pushed from this monorepo at publish time:
+// templates/primitive-vue-template via scripts/sync-vue-template.mjs, and
+// templates/primitive-swift-template via scripts/publish-swift-packages.sh.
+// The branch is the channel (issue #1934): `main` = production, `alpha` =
+// the alpha environment (its Primitive deps are pinned to the alpha
+// prerelease npm versions / mirror branches).
+export function vueTemplateUrl(branch = DEFAULT_CHANNEL_BRANCH) {
+    return `https://github.com/Primitive-Labs/primitive-vue-template/archive/refs/heads/${branch}.tar.gz`;
+}
+export function iosTemplateUrl(branch = DEFAULT_CHANNEL_BRANCH) {
+    return `https://api.github.com/repos/Primitive-Labs/primitive-swift-template/tarball/${branch}`;
+}
+const TEMPLATE_URL = vueTemplateUrl();
+const IOS_TEMPLATE_URL = iosTemplateUrl();
+/**
+ * Resolve which template branch `primitive init` scaffolds from — same
+ * precedence as `primitive guides` (see resolveChannelBranch): the
+ * undocumented `PRIMITIVE_TEMPLATE_BRANCH` override (validated), then alpha
+ * server-URL detection, then `main`.
+ */
+export function resolveTemplateBranch(serverUrl, override = process.env.PRIMITIVE_TEMPLATE_BRANCH) {
+    return resolveChannelBranch(serverUrl, override, "PRIMITIVE_TEMPLATE_BRANCH");
+}
 const DOWNLOAD_TIMEOUT_MS = 30000; // 30 seconds
+/**
+ * Tries to get a GitHub token from the gh CLI for authenticated downloads.
+ * Returns null if gh is not installed or not authenticated.
+ */
+async function getGitHubToken() {
+    const { execSync } = await import("child_process");
+    try {
+        return execSync("gh auth token", { stdio: ["ignore", "pipe", "ignore"] })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Check if a directory is empty.
  */
@@ -13,21 +55,21 @@ export function isDirectoryEmpty(dir) {
     const files = readdirSync(dir);
     return files.length === 0;
 }
-/**
- * Downloads and extracts the Primitive app template.
- * The tarball extracts to a subfolder, so we strip that prefix by moving contents up.
- */
-export async function downloadAndExtractTemplate(options) {
-    const { targetDir, onProgress } = options;
-    // Ensure target directory exists
-    mkdirSync(targetDir, { recursive: true });
-    onProgress?.("Downloading template...");
+async function fetchTemplateTarball(url) {
     // Fetch the tarball with timeout
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
     let response;
     try {
-        response = await fetch(TEMPLATE_URL, { signal: controller.signal });
+        const headers = {
+            "User-Agent": "primitive-cli",
+        };
+        // For private repos, use GitHub token if available (from gh CLI)
+        const ghToken = await getGitHubToken();
+        if (ghToken) {
+            headers["Authorization"] = `token ${ghToken}`;
+        }
+        response = await fetch(url, { signal: controller.signal, headers });
     }
     catch (err) {
         clearTimeout(timeout);
@@ -43,50 +85,118 @@ export async function downloadAndExtractTemplate(options) {
         throw new Error(`Failed to download template: HTTP ${response.status}`);
     }
     const arrayBuffer = await response.arrayBuffer();
-    const buffer = Buffer.from(arrayBuffer);
-    onProgress?.("Extracting template...");
-    // Create a temporary directory for extraction
-    const tempDir = join(targetDir, ".primitive-temp-" + Date.now());
-    mkdirSync(tempDir, { recursive: true });
-    // Write buffer to temp file and extract
-    const tempTarPath = join(tempDir, "template.tar.gz");
-    writeFileSync(tempTarPath, buffer);
-    // Extract tarball using tar
-    await tar.extract({
-        file: tempTarPath,
-        cwd: tempDir,
-    });
-    // Remove the temp tarball
-    rmSync(tempTarPath);
-    // Find the extracted directory (e.g., "primitive-app-template-main")
-    const extractedItems = readdirSync(tempDir);
-    if (extractedItems.length !== 1) {
-        throw new Error(`Unexpected template structure: expected 1 directory, found ${extractedItems.length}`);
-    }
-    const extractedDir = join(tempDir, extractedItems[0]);
-    // Verify it's a directory
-    if (!statSync(extractedDir).isDirectory()) {
-        throw new Error("Unexpected template structure: expected a directory");
-    }
-    // Move contents to target directory
-    for (const item of readdirSync(extractedDir)) {
-        const src = join(extractedDir, item);
-        const dest = join(targetDir, item);
-        // Remove existing item if it exists (for overwrite scenarios)
-        if (existsSync(dest)) {
-            rmSync(dest, { recursive: true, force: true });
+    return Buffer.from(arrayBuffer);
+}
+async function downloadTemplateBuffer(options) {
+    const { onProgress, onFallback, fallbackTemplateUrl } = options;
+    onProgress?.("Downloading template...");
+    try {
+        return await fetchTemplateTarball(options.templateUrl || TEMPLATE_URL);
+    }
+    catch (err) {
+        if (!fallbackTemplateUrl)
+            throw err;
+        // A channel branch that hasn't been pushed yet 404s — fall back to the
+        // default branch rather than failing the scaffold.
+        onFallback?.(err.message);
+        return await fetchTemplateTarball(fallbackTemplateUrl);
+    }
+}
+/**
+ * Downloads and validates the Primitive app template in a temporary staging
+ * directory. Nothing is written to the final target directory until install()
+ * is called.
+ */
+export async function prepareTemplate(options = {}) {
+    const tempDir = mkdtempSync(join(tmpdir(), "primitive-template-"));
+    try {
+        const buffer = await downloadTemplateBuffer(options);
+        options.onProgress?.("Extracting template...");
+        const extractRoot = join(tempDir, "extract");
+        mkdirSync(extractRoot, { recursive: true });
+        const tempTarPath = join(tempDir, "template.tar.gz");
+        writeFileSync(tempTarPath, buffer);
+        await tar.extract({
+            file: tempTarPath,
+            cwd: extractRoot,
+        });
+        rmSync(tempTarPath);
+        // Find the extracted directory (e.g., "primitive-vue-template-main")
+        const extractedItems = readdirSync(extractRoot);
+        if (extractedItems.length !== 1) {
+            throw new Error(`Unexpected template structure: expected 1 directory, found ${extractedItems.length}`);
+        }
+        const extractedDir = join(extractRoot, extractedItems[0]);
+        // Verify it's a directory
+        if (!statSync(extractedDir).isDirectory()) {
+            throw new Error("Unexpected template structure: expected a directory");
         }
-        renameSync(src, dest);
+        options.onProgress?.("Template downloaded and validated.");
+        return {
+            install(targetDir) {
+                // Ensure target directory exists
+                mkdirSync(targetDir, { recursive: true });
+                // Move contents to target directory
+                for (const item of readdirSync(extractedDir)) {
+                    const src = join(extractedDir, item);
+                    const dest = join(targetDir, item);
+                    // Remove existing item if it exists (for overwrite scenarios)
+                    if (existsSync(dest)) {
+                        rmSync(dest, { recursive: true, force: true });
+                    }
+                    cpSync(src, dest, { recursive: true, force: true });
+                }
+            },
+            cleanup() {
+                rmSync(tempDir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (err) {
+        rmSync(tempDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+/**
+ * Derives VITE_API_URL and VITE_WS_URL from a server URL.
+ * https:// → wss://, http:// → ws://
+ */
+function deriveEnvUrls(serverUrl) {
+    const apiUrl = serverUrl.replace(/\/+$/, "");
+    if (!/^https?:\/\//.test(apiUrl)) {
+        throw new Error(`Invalid server URL (must start with http:// or https://): ${apiUrl}`);
+    }
+    const wsUrl = apiUrl
+        .replace(/^https:\/\//, "wss://")
+        .replace(/^http:\/\//, "ws://");
+    return { apiUrl, wsUrl };
+}
+/**
+ * Replaces a key=value pair in env file content IF the key is already there.
+ *
+ * Replace-only, deliberately (#2873): the Vue template no longer authors the
+ * identity keys — `primitiveEnv()` fills them from `.primitive/config.json` —
+ * so appending one would re-create the second source of truth this change
+ * removed, and `cf-deploy` treats an identity key in a `.env` file as a hard
+ * error. An OLD template still carries the keys, and those must keep being
+ * filled in, which is exactly what "replace if present" does.
+ */
+function setEnvVar(content, key, value) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`^${escapedKey}=.*`, "m");
+    // Quote values that contain characters dotenv would misparse (# starts
+    // a comment, leading/trailing whitespace is stripped, etc.)
+    const formatted = /[#\n]/.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value;
+    if (pattern.test(content)) {
+        return content.replace(pattern, `${key}=${formatted}`);
     }
-    // Clean up temp directory
-    rmSync(tempDir, { recursive: true, force: true });
-    onProgress?.("Template extracted successfully.");
+    return content;
 }
 /**
- * Updates a single env file with the app ID.
+ * Updates a single env file with the app ID and server URLs.
  * Returns true if the file was updated, false if it didn't exist.
  */
-function updateSingleEnvFile(envPath, appId, fallbackPath) {
+function updateSingleEnvFile(envPath, appId, serverUrl, appName, fallbackPath) {
     let envContent = "";
     // If file doesn't exist but fallback does, copy from fallback
     if (!existsSync(envPath) && fallbackPath && existsSync(fallbackPath)) {
@@ -98,29 +208,34 @@ function updateSingleEnvFile(envPath, appId, fallbackPath) {
     else {
         return false;
     }
-    // Update or add VITE_APP_ID
-    if (envContent.includes("VITE_APP_ID=")) {
-        envContent = envContent.replace(/VITE_APP_ID=.*/, `VITE_APP_ID=${appId}`);
-    }
-    else {
-        envContent = envContent.trimEnd() + `\nVITE_APP_ID=${appId}\n`;
+    envContent = setEnvVar(envContent, "VITE_APP_ID", appId);
+    if (appName) {
+        envContent = setEnvVar(envContent, "VITE_APP_NAME", appName);
     }
+    const { apiUrl, wsUrl } = deriveEnvUrls(serverUrl);
+    envContent = setEnvVar(envContent, "VITE_API_URL", apiUrl);
+    envContent = setEnvVar(envContent, "VITE_WS_URL", wsUrl);
     writeFileSync(envPath, envContent.trimEnd() + "\n");
     return true;
 }
 /**
- * Updates .env and .env.production files with the app ID.
+ * Updates .env and .env.production files with the app ID and server URLs.
  * For .env, if it doesn't exist but .env.example does, copies from example first.
  * Returns information about which files were updated.
+ *
+ * `production` names the backend/app pair a production build should talk to.
+ * Omit it and `.env.production` points at the hosted production server with
+ * this app id — the historical behavior, which is correct for an app created
+ * there and wrong for one created anywhere else, so composed runs derive the
+ * pair from the project's own environments and pass it in (#2890).
  */
-export function updateEnvFile(targetDir, appId) {
+export function updateEnvFile(targetDir, appId, serverUrl, appName, production) {
     const envPath = join(targetDir, ".env");
     const envExamplePath = join(targetDir, ".env.example");
     const envProductionPath = join(targetDir, ".env.production");
     // Update .env (create from .env.example if needed)
-    const envUpdated = updateSingleEnvFile(envPath, appId, envExamplePath);
-    // Update .env.production if it exists
-    const envProductionUpdated = updateSingleEnvFile(envProductionPath, appId);
+    const envUpdated = updateSingleEnvFile(envPath, appId, serverUrl, appName, envExamplePath);
+    const envProductionUpdated = updateSingleEnvFile(envProductionPath, production?.appId ?? appId, production?.serverUrl ?? PRODUCTION_SERVER_URL, production?.appName ?? appName);
     return { envUpdated, envProductionUpdated };
 }
 /**
@@ -183,14 +298,14 @@ export async function installPnpmGlobally() {
     });
 }
 /**
- * Checks if the primitive CLI (primitive-admin) is installed globally.
- * Uses npm list -g to check for actual global installation, not just
- * temporary availability via npx.
+ * Checks if the primitive CLI is installed and available in PATH.
+ * Checks for the `primitive` command directly, which covers installs via
+ * npm, pnpm, yarn, or any other package manager.
  */
 export async function isPrimitiveCliInstalled() {
     const { execSync } = await import("child_process");
     try {
-        execSync("npm list -g primitive-admin", { stdio: "ignore" });
+        execSync("primitive --version", { stdio: "ignore" });
         return true;
     }
     catch {
@@ -198,12 +313,313 @@ export async function isPrimitiveCliInstalled() {
     }
 }
 /**
- * Installs the primitive CLI (primitive-admin) globally using npm.
+ * Initializes a git repository in the target directory.
+ */
+async function spawnGit(args, cwd) {
+    const { spawn } = await import("child_process");
+    return new Promise((resolve, reject) => {
+        const proc = spawn("git", args, {
+            cwd,
+            stdio: "ignore",
+            shell: process.platform === "win32",
+        });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`git ${args[0]} exited with code ${code}`));
+            }
+        });
+        proc.on("error", reject);
+    });
+}
+export async function gitInitRepo(targetDir) {
+    await spawnGit(["init"], targetDir);
+}
+export async function gitInitialCommit(targetDir) {
+    await spawnGit(["add", "-A"], targetDir);
+    await spawnGit(["commit", "--allow-empty", "-m", "Initial Commit"], targetDir);
+}
+/**
+ * Tries to connect to `host:port`. Returns true if something answered
+ * (port occupied), false if the connection was refused (port free).
+ */
+function canConnect(port, host) {
+    return new Promise((resolve) => {
+        import("net").then(({ createConnection }) => {
+            const socket = createConnection({ port, host });
+            socket.once("connect", () => {
+                socket.destroy();
+                resolve(true);
+            });
+            socket.once("error", () => resolve(false));
+        });
+    });
+}
+/**
+ * Checks whether a TCP port is currently in use on localhost.
+ * Tries both IPv4 (127.0.0.1) and IPv6 (::1) since a server may only
+ * bind to one address family.
+ */
+export async function isPortFree(port) {
+    const [v4, v6] = await Promise.all([
+        canConnect(port, "127.0.0.1"),
+        canConnect(port, "::1"),
+    ]);
+    return !v4 && !v6;
+}
+/**
+ * Locates the `{` that opens the configuration object literal of a vite
+ * config, so a `server` block can be inserted into it. Returns null when the
+ * shape isn't one we can patch safely.
+ *
+ * The shipped template exports `defineConfig(({ mode }) => { ... return {...} })`,
+ * so matching only `defineConfig({` — as this used to — silently patched
+ * nothing (#2720).
+ */
+function findConfigObjectStart(content) {
+    const call = /defineConfig\s*\(\s*/.exec(content);
+    if (call) {
+        const afterCall = call.index + call[0].length;
+        // `defineConfig({ ... })` — a direct object literal.
+        if (content[afterCall] === "{")
+            return afterCall;
+        // `defineConfig((env) => ...)` — an arrow function, with either a concise
+        // object body or a block body that returns the config.
+        const arrow = /^(?:async\s+)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>\s*/.exec(content.slice(afterCall));
+        if (arrow) {
+            const body = afterCall + arrow[0].length;
+            // Concise body: `=> ({ ... })`.
+            const concise = /^\(\s*\{/.exec(content.slice(body));
+            if (concise)
+                return body + concise[0].length - 1;
+            // Block body: the config is whatever the function returns.
+            if (content[body] === "{") {
+                const ret = /\breturn\s*\{/.exec(content.slice(body));
+                if (ret)
+                    return body + ret.index + ret[0].length - 1;
+            }
+        }
+    }
+    // `export default { ... }` — a plain object config, no `defineConfig`.
+    const plain = /export\s+default\s*\{/.exec(content);
+    if (plain)
+        return plain.index + plain[0].length - 1;
+    return null;
+}
+/** Indentation of the line the given offset sits on. */
+function indentOfLineAt(content, index) {
+    const lineStart = content.lastIndexOf("\n", index) + 1;
+    return /^[ \t]*/.exec(content.slice(lineStart, index))?.[0] ?? "";
+}
+/**
+ * Pins `server.port` in the source of a vite config. Returns the patched
+ * source, or null when the config's shape is one we can't patch — the caller
+ * must not claim success in that case.
+ *
+ * Exported for tests, which pin this against the real shipped template.
+ */
+export function patchViteConfigPort(content, port) {
+    // An existing numeric `server.port`: retarget it.
+    if (/server\s*:\s*\{[^}]*port\s*:\s*\d+/.test(content)) {
+        return content.replace(/(server\s*:\s*\{[^}]*port\s*:\s*)\d+/, `$1${port}`);
+    }
+    // A `server.port` set to something other than a literal (`env.PORT`, say).
+    // Rewriting it would either be a no-op or clobber the author's intent.
+    if (/server\s*:\s*\{[^}]*port\s*:/.test(content))
+        return null;
+    // A `server` block with no port: add one.
+    if (/server\s*:\s*\{/.test(content)) {
+        const match = /server\s*:\s*\{/.exec(content);
+        const indent = indentOfLineAt(content, match.index);
+        return content.replace(/(server\s*:\s*\{)/, `$1\n${indent}  port: ${port},`);
+    }
+    // No `server` block at all: insert one at the head of the config object.
+    const objectStart = findConfigObjectStart(content);
+    if (objectStart === null)
+        return null;
+    const indent = indentOfLineAt(content, objectStart) + "  ";
+    return (content.slice(0, objectStart + 1) +
+        `\n${indent}server: {\n${indent}  port: ${port},\n${indent}},` +
+        content.slice(objectStart + 1));
+}
+/**
+ * Pins the dev server port in vite.config.{ts,js,mts,mjs} by injecting or
+ * updating the `server.port` field. Returns true only if a config file was
+ * found *and* actually rewritten.
+ */
+export function updateViteConfig(targetDir, port) {
+    const candidates = [
+        "vite.config.ts",
+        "vite.config.js",
+        "vite.config.mts",
+        "vite.config.mjs",
+    ];
+    let configPath = null;
+    for (const name of candidates) {
+        const p = join(targetDir, name);
+        if (existsSync(p)) {
+            configPath = p;
+            break;
+        }
+    }
+    if (!configPath)
+        return false;
+    const content = readFileSync(configPath, "utf-8");
+    const patched = patchViteConfigPort(content, port);
+    if (patched === null)
+        return false;
+    writeFileSync(configPath, patched);
+    return true;
+}
+/**
+ * Updates port-sensitive env vars (VITE_OAUTH_REDIRECT_URI, VITE_BASE_URL)
+ * in the project's .env file to point at the given localhost port.
+ */
+export function updateEnvPort(targetDir, port) {
+    const envPath = join(targetDir, ".env");
+    if (!existsSync(envPath))
+        return;
+    const origin = `http://localhost:${port}`;
+    let content = readFileSync(envPath, "utf-8");
+    if (content.includes("VITE_OAUTH_REDIRECT_URI=")) {
+        content = content.replace(/VITE_OAUTH_REDIRECT_URI=.*/, `VITE_OAUTH_REDIRECT_URI=${origin}/oauth/callback`);
+    }
+    else {
+        content =
+            content.trimEnd() +
+                `\nVITE_OAUTH_REDIRECT_URI=${origin}/oauth/callback\n`;
+    }
+    if (content.includes("VITE_BASE_URL=")) {
+        content = content.replace(/VITE_BASE_URL=.*/, `VITE_BASE_URL=${origin}`);
+    }
+    else {
+        content = content.trimEnd() + `\nVITE_BASE_URL=${origin}\n`;
+    }
+    writeFileSync(envPath, content.trimEnd() + "\n");
+}
+/**
+ * Starting from `startPort` (default 5173), finds the first free port and
+ * returns which ports were already occupied and which port vite will bind to.
+ * `exhausted` is true when all checked ports were occupied and the returned
+ * port is a best-guess beyond the checked range.
+ */
+export async function findDevPort(startPort = 5173, maxChecks = 10) {
+    const takenPorts = [];
+    for (let port = startPort; port < startPort + maxChecks; port++) {
+        if (await isPortFree(port)) {
+            return { availablePort: port, takenPorts, exhausted: false };
+        }
+        takenPorts.push(port);
+    }
+    // All checked ports were occupied — best guess is the next one
+    return { availablePort: startPort + maxChecks, takenPorts, exhausted: true };
+}
+// ── iOS template helpers ──────────────────────────────────────────────
+export { IOS_TEMPLATE_URL };
+/**
+ * Updates primitive.json in the iOS template with app ID, server URL, and app name.
+ * Replaces __PRIMITIVE_*__ placeholder values.
+ * Returns true if the file was found and updated.
+ */
+export function updatePrimitiveJson(targetDir, appId, serverUrl, appName) {
+    const jsonPath = join(targetDir, "primitive.json");
+    if (!existsSync(jsonPath))
+        return false;
+    let content = readFileSync(jsonPath, "utf-8");
+    content = content.replace(/__PRIMITIVE_APP_ID__/g, appId);
+    content = content.replace(/__PRIMITIVE_SERVER_URL__/g, serverUrl.replace(/\/+$/, ""));
+    if (appName) {
+        content = content.replace(/__PRIMITIVE_APP_NAME__/g, appName);
+    }
+    writeFileSync(jsonPath, content);
+    return true;
+}
+/**
+ * Gives an Apple scaffold a working `primitive.json`.
+ *
+ * In a current template that file is a BUILD PRODUCT generated from the
+ * Primitive environment in `.primitive/config.json` (#2873) — the one place
+ * the app ID and server URL are typed. `init` has just scaffolded that config,
+ * so running the template's own resolve script here means the scaffold has a
+ * `primitive.json` immediately rather than only after its first build, and
+ * there is exactly one implementation of the resolution.
+ *
+ * A template that predates the change has no such script and ships a tracked
+ * file with `__PRIMITIVE_*__` placeholders instead; filling those in keeps a
+ * new CLI working against an old template.
+ */
+export function configurePrimitiveJson(targetDir, appId, serverUrl, appName, options = {}) {
+    const script = join(targetDir, "scripts", "resolve-primitive-config.sh");
+    if (existsSync(script)) {
+        try {
+            execFileSync("bash", [
+                "scripts/resolve-primitive-config.sh",
+                ...(options.environmentName
+                    ? ["--primitive-env", options.environmentName]
+                    : []),
+            ], {
+                cwd: targetDir,
+                stdio: "pipe",
+            });
+            return { outcome: "generated" };
+        }
+        catch (err) {
+            const detail = [err?.stderr?.toString(), err?.stdout?.toString(), err?.message]
+                .filter(Boolean)
+                .join("\n")
+                .trim();
+            return { outcome: "failed", detail };
+        }
+    }
+    return updatePrimitiveJson(targetDir, appId, serverUrl, appName)
+        ? { outcome: "filled" }
+        : { outcome: "missing" };
+}
+/**
+ * Checks if Xcode command-line tools are installed.
+ */
+export async function isXcodeInstalled() {
+    const { execSync } = await import("child_process");
+    try {
+        execSync("xcodebuild -version", { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Runs `swift package resolve` in the target directory to download SPM dependencies.
+ */
+export async function runSwiftPackageResolve(targetDir) {
+    const { spawn } = await import("child_process");
+    return new Promise((resolve, reject) => {
+        const proc = spawn("swift", ["package", "resolve"], {
+            cwd: targetDir,
+            stdio: "inherit",
+        });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`swift package resolve exited with code ${code}`));
+            }
+        });
+        proc.on("error", reject);
+    });
+}
+/**
+ * Installs the primitive CLI (primitive-admin) globally, using whichever
+ * package manager already owns a global copy — pnpm by default.
  */
 export async function installPrimitiveCli() {
     const { spawn } = await import("child_process");
+    const { command, args } = installArgv(PRIMITIVE_CLI_PACKAGE);
     return new Promise((resolve, reject) => {
-        const proc = spawn("npm", ["install", "-g", "primitive-admin"], {
+        const proc = spawn(command, args, {
             stdio: "inherit",
             shell: process.platform === "win32",
         });
@@ -212,7 +628,7 @@ export async function installPrimitiveCli() {
                 resolve();
             }
             else {
-                reject(new Error(`npm install -g primitive-admin exited with code ${code}`));
+                reject(new Error(`${[command, ...args].join(" ")} exited with code ${code}`));
             }
         });
         proc.on("error", reject);