@wardby/cli 0.1.0 → 0.2.1

package/dist/quickstart/index.js

@@ -0,0 +1,527 @@
+import { spawnSync } from "node:child_process";
+import { createServer } from "node:net";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline/promises";
+import { composeProjectName, defaultModel, ensureWardbyIgnored, generatedSecret, providerKeyName, quickstartPaths, readQuickstartEnv, readQuickstartState, resolveProjectDir, writeQuickstartEnv, writeQuickstartState, } from "./config.js";
+import { FETCH_NOTICE, migrateFailureReason, prismaMigrateInvocation, REGISTRY_FAILURE_MESSAGE, runPrismaMigrateInvocation, } from "./migrate.js";
+const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
+const composeFile = join(packageRoot, "deploy/local/docker-compose.yml");
+const wardbyBin = join(packageRoot, "bin/wardby.js");
+const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+const DEMO_AGENT = "hello-wardby";
+const DEMO_PROMPT = "You are the Wardby quickstart agent. Reply with a short greeting, then explain in one sentence that Wardby admitted this run against an explicit maximum budget. Do not call tools.";
+function runCommand(command, args, options = {}) {
+    const spawnOptions = {
+        cwd: options.cwd,
+        env: options.env,
+        encoding: "utf8",
+        stdio: options.inherit ? "inherit" : "pipe",
+    };
+    const result = spawnSync(command, args, spawnOptions);
+    if (result.error) {
+        return { status: 1, stdout: result.stdout ?? "", stderr: result.error.message };
+    }
+    return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+function commandFailure(label, result) {
+    const detail = (result.stderr || result.stdout).trim();
+    throw new Error(`${label} failed${detail ? `: ${detail}` : ""}`);
+}
+function runtimeEnv(paths, values = readQuickstartEnv(paths)) {
+    return { ...process.env, ...values, WARDBY_PROJECT_DIR: paths.projectDir };
+}
+function composeArgs(paths, state, args) {
+    return [
+        "compose",
+        "--project-name",
+        state.composeProject,
+        "--env-file",
+        paths.envFile,
+        "--file",
+        composeFile,
+        ...args,
+    ];
+}
+function runCompose(paths, state, args, options = {}) {
+    return runCommand("docker", composeArgs(paths, state, args), {
+        cwd: paths.projectDir,
+        env: runtimeEnv(paths),
+        inherit: options.inherit,
+    });
+}
+function nodeMajor() {
+    return Number(process.versions.node.split(".")[0]);
+}
+function assertPrerequisites() {
+    if (nodeMajor() < 24)
+        throw new Error(`Node.js 24 or newer is required; found ${process.versions.node}.`);
+    const docker = runCommand("docker", ["--version"]);
+    if (docker.status !== 0)
+        throw new Error("Docker is not installed or is not on PATH.");
+    const compose = runCommand("docker", ["compose", "version"]);
+    if (compose.status !== 0)
+        throw new Error("Docker Compose v2 is required (`docker compose`).");
+    const daemon = runCommand("docker", ["info"]);
+    if (daemon.status !== 0)
+        throw new Error("Docker is installed but its daemon is not available.");
+}
+async function portAvailable(port) {
+    return await new Promise((resolve) => {
+        const server = createServer();
+        server.unref();
+        server.once("error", () => resolve(false));
+        server.listen({ host: "0.0.0.0", port }, () => server.close(() => resolve(true)));
+    });
+}
+async function selectPostgresPort(firstPort = 55432) {
+    for (let port = firstPort; port <= 55532; port += 1) {
+        if (await portAvailable(port))
+            return port;
+    }
+    throw new Error("No available local port was found between 55432 and 55532.");
+}
+async function startPostgres(paths, state, config) {
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        const up = runCompose(paths, state, ["up", "--detach", "--wait", "--wait-timeout", "90"]);
+        if (up.status === 0)
+            return;
+        const output = `${up.stderr}\n${up.stdout}`;
+        if (!/port is already allocated|address already in use|bind for .* failed/i.test(output)) {
+            commandFailure("PostgreSQL startup", up);
+        }
+        // Docker Desktop's port forwarder is not always visible to a host socket
+        // probe. Clean up the failed container and converge on the next port.
+        runCompose(paths, state, ["down"]);
+        state.postgresPort = await selectPostgresPort(state.postgresPort + 1);
+        config.WARDBY_POSTGRES_PORT = String(state.postgresPort);
+        config.DATABASE_URL = databaseUrl(config, state.postgresPort);
+        writeQuickstartEnv(paths, config);
+        writeQuickstartState(paths, state);
+        console.log(`! Port was occupied; retrying PostgreSQL on ${state.postgresPort}`);
+    }
+    throw new Error("PostgreSQL startup could not find a usable port after 10 attempts.");
+}
+function databaseUrl(config, port) {
+    const user = encodeURIComponent(config.WARDBY_POSTGRES_USER);
+    const password = encodeURIComponent(config.WARDBY_POSTGRES_PASSWORD);
+    const database = encodeURIComponent(config.WARDBY_POSTGRES_DB);
+    return `postgresql://${user}:${password}@127.0.0.1:${port}/${database}`;
+}
+async function promptLine(question, fallback) {
+    const terminal = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await terminal.question(question)).trim();
+        return answer || fallback || "";
+    }
+    finally {
+        terminal.close();
+    }
+}
+async function promptYesNo(question, defaultYes) {
+    const suffix = defaultYes ? " [Y/n] " : " [y/N] ";
+    const answer = (await promptLine(`${question}${suffix}`)).toLowerCase();
+    if (!answer)
+        return defaultYes;
+    return answer === "y" || answer === "yes";
+}
+async function promptSecret(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY || !process.stdin.setRawMode) {
+        throw new Error("A provider key is required in the environment when stdin is not an interactive terminal.");
+    }
+    process.stdout.write(question);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    return await new Promise((resolve, reject) => {
+        let value = "";
+        const finish = (error) => {
+            process.stdin.off("data", onData);
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdout.write("\n");
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const onData = (chunk) => {
+            for (const character of chunk) {
+                if (character === "\u0003")
+                    return finish(new Error("cancelled"));
+                if (character === "\r" || character === "\n")
+                    return finish();
+                if (character === "\u007f" || character === "\b")
+                    value = value.slice(0, -1);
+                else if (character >= " ")
+                    value += character;
+            }
+        };
+        process.stdin.on("data", onData);
+    });
+}
+function parseProvider(value) {
+    if (value === undefined)
+        return undefined;
+    if (value !== "openai" && value !== "anthropic") {
+        throw new Error(`--provider must be openai or anthropic; got "${value}".`);
+    }
+    return value;
+}
+function parseClient(value) {
+    if (value === undefined)
+        return undefined;
+    if (!["none", "codex", "claude", "both"].includes(value)) {
+        throw new Error(`--client must be none, codex, claude, or both; got "${value}".`);
+    }
+    return value;
+}
+async function chooseProvider(requested, previous, existing, nonInteractive) {
+    if (requested)
+        return requested;
+    if (previous)
+        return previous.provider;
+    if (existing.LLM_PROVIDER === "openai" || existing.LLM_PROVIDER === "anthropic")
+        return existing.LLM_PROVIDER;
+    if (process.env.OPENAI_API_KEY || existing.OPENAI_API_KEY)
+        return "openai";
+    if (process.env.ANTHROPIC_API_KEY || existing.ANTHROPIC_API_KEY)
+        return "anthropic";
+    if (nonInteractive)
+        throw new Error("--provider is required in non-interactive mode.");
+    const answer = (await promptLine("Model provider: [1] OpenAI, [2] Anthropic [1] ", "1")).toLowerCase();
+    if (answer === "1" || answer === "openai")
+        return "openai";
+    if (answer === "2" || answer === "anthropic")
+        return "anthropic";
+    throw new Error(`Unknown provider selection "${answer}".`);
+}
+function applyMigrations(paths) {
+    const invocation = prismaMigrateInvocation("deploy", runtimeEnv(paths));
+    if (!invocation.local)
+        console.log(FETCH_NOTICE);
+    const result = runPrismaMigrateInvocation(invocation, paths.projectDir);
+    if (result.registryFailure) {
+        const detail = /^npm (?:error|ERR!) code .*$/m.exec(result.stderr)?.[0] ?? result.stderr.trim().split("\n")[0];
+        throw new Error(`${REGISTRY_FAILURE_MESSAGE}${detail ? ` (${detail})` : ""}`);
+    }
+    if (result.status !== 0)
+        commandFailure("Database migration", result);
+}
+async function seedDemo(paths, state, budget) {
+    const { createPrismaClient } = await import("../core/db.js");
+    const db = createPrismaClient(readQuickstartEnv(paths).DATABASE_URL);
+    try {
+        const existing = await db.agent.findUnique({ where: { name: DEMO_AGENT } });
+        if (existing && existing.systemPrompt !== DEMO_PROMPT) {
+            throw new Error(`An agent named "${DEMO_AGENT}" already exists and was not created by quickstart; rename it or use --skip-demo.`);
+        }
+        if (existing) {
+            await db.agent.update({
+                where: { name: DEMO_AGENT },
+                data: { model: state.model, budgetUsd: budget, maxTurns: 2 },
+            });
+        }
+        else {
+            await db.agent.create({
+                data: {
+                    name: DEMO_AGENT,
+                    model: state.model,
+                    budgetUsd: budget,
+                    maxTurns: 2,
+                    systemPrompt: DEMO_PROMPT,
+                },
+            });
+        }
+    }
+    finally {
+        await db.$disconnect();
+    }
+}
+function runDemo(paths) {
+    const result = runCommand(process.execPath, [wardbyBin, "run", DEMO_AGENT], {
+        cwd: paths.projectDir,
+        env: runtimeEnv(paths),
+        inherit: true,
+    });
+    if (result.status !== 0)
+        throw new Error("The sample agent run failed; run `wardby doctor` for diagnostics.");
+}
+function clientInstalled(command) {
+    return runCommand(command, ["--version"]).status === 0;
+}
+function configureOneMcpClient(client, paths) {
+    if (!clientInstalled(client)) {
+        console.warn(`! ${client} is not installed; skipped its MCP configuration.`);
+        return;
+    }
+    const existing = runCommand(client, ["mcp", "get", "wardby"], { cwd: paths.projectDir });
+    if (existing.status === 0) {
+        console.log(`✓ ${client} already has an MCP server named wardby.`);
+        return;
+    }
+    const packageSpec = `@wardby/cli@${packageJson.version}`;
+    const args = client === "codex"
+        ? [
+            "mcp",
+            "add",
+            "--env",
+            `WARDBY_PROJECT_DIR=${paths.projectDir}`,
+            "wardby",
+            "--",
+            "npx",
+            "--yes",
+            packageSpec,
+            "mcp",
+        ]
+        : [
+            "mcp",
+            "add",
+            "--scope",
+            "local",
+            "-e",
+            `WARDBY_PROJECT_DIR=${paths.projectDir}`,
+            "wardby",
+            "--",
+            "npx",
+            "--yes",
+            packageSpec,
+            "mcp",
+        ];
+    const result = runCommand(client, args, { cwd: paths.projectDir });
+    if (result.status !== 0)
+        commandFailure(`${client} MCP configuration`, result);
+    console.log(`✓ Configured Wardby MCP for ${client}.`);
+}
+function configureMcpClients(client, paths) {
+    if (client === "codex" || client === "both")
+        configureOneMcpClient("codex", paths);
+    if (client === "claude" || client === "both")
+        configureOneMcpClient("claude", paths);
+}
+async function chooseClient(nonInteractive) {
+    if (nonInteractive)
+        return "none";
+    const answer = (await promptLine("Configure MCP: [n]one, [c]odex, c[l]aude, [b]oth [n] ", "n")).toLowerCase();
+    if (answer === "" || answer === "n" || answer === "none")
+        return "none";
+    if (answer === "c" || answer === "codex")
+        return "codex";
+    if (answer === "l" || answer === "claude")
+        return "claude";
+    if (answer === "b" || answer === "both")
+        return "both";
+    throw new Error(`Unknown MCP client selection "${answer}".`);
+}
+export async function quickstartCommand(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            provider: { type: "string" },
+            model: { type: "string" },
+            budget: { type: "string" },
+            client: { type: "string" },
+            "non-interactive": { type: "boolean" },
+            "skip-demo": { type: "boolean" },
+            yes: { type: "boolean", short: "y" },
+        },
+    });
+    const nonInteractive = values["non-interactive"] ?? false;
+    const skipDemo = values["skip-demo"] ?? false;
+    const budget = values.budget === undefined ? 1 : Number(values.budget);
+    if (!Number.isFinite(budget) || budget <= 0)
+        throw new Error(`--budget must be positive; got "${values.budget}".`);
+    if (nonInteractive && !skipDemo && !values.yes) {
+        throw new Error("Non-interactive demo execution requires --yes because it may incur provider charges.");
+    }
+    console.log("Wardby quickstart\n");
+    assertPrerequisites();
+    console.log(`✓ Node.js ${process.versions.node}`);
+    console.log("✓ Docker and Docker Compose are available");
+    const projectDir = resolveProjectDir();
+    const paths = quickstartPaths(projectDir);
+    const previous = readQuickstartState(paths);
+    const existing = readQuickstartEnv(paths);
+    const provider = await chooseProvider(parseProvider(values.provider), previous, existing, nonInteractive);
+    const model = values.model ?? (previous?.provider === provider ? previous.model : defaultModel(provider));
+    const keyName = providerKeyName(provider);
+    let providerKey = process.env[keyName] || existing[keyName];
+    if (!providerKey && !skipDemo) {
+        if (nonInteractive)
+            throw new Error(`${keyName} is required in non-interactive mode unless --skip-demo is used.`);
+        providerKey = await promptSecret(`${keyName}: `);
+        if (!providerKey)
+            throw new Error(`${keyName} cannot be empty.`);
+    }
+    const postgresPort = previous?.postgresPort ?? (await selectPostgresPort());
+    const postgresUser = existing.WARDBY_POSTGRES_USER || "wardby";
+    const postgresDatabase = existing.WARDBY_POSTGRES_DB || "wardby";
+    const postgresPassword = existing.WARDBY_POSTGRES_PASSWORD || generatedSecret();
+    const config = {
+        ...existing,
+        LLM_PROVIDER: provider,
+        LOCAL_PRINCIPAL: existing.LOCAL_PRINCIPAL || "local",
+        MCP_TRANSPORT: "stdio",
+        SECRET_APP_KEY: existing.SECRET_APP_KEY || generatedSecret(),
+        WARDBY_POSTGRES_DB: postgresDatabase,
+        WARDBY_POSTGRES_PASSWORD: postgresPassword,
+        WARDBY_POSTGRES_PORT: String(postgresPort),
+        WARDBY_POSTGRES_USER: postgresUser,
+    };
+    config.DATABASE_URL = databaseUrl(config, postgresPort);
+    if (providerKey)
+        config[keyName] = providerKey;
+    ensureWardbyIgnored(projectDir);
+    writeQuickstartEnv(paths, config);
+    const state = {
+        version: 1,
+        projectDir,
+        composeProject: previous?.composeProject ?? composeProjectName(projectDir),
+        postgresPort,
+        provider,
+        model,
+        packageVersion: packageJson.version,
+        createdAt: previous?.createdAt ?? new Date().toISOString(),
+    };
+    writeQuickstartState(paths, state);
+    console.log(`✓ Configuration ready in ${paths.wardbyDir}`);
+    await startPostgres(paths, state, config);
+    console.log(`✓ PostgreSQL is healthy on 127.0.0.1:${state.postgresPort}`);
+    applyMigrations(paths);
+    console.log("✓ Database migrations applied");
+    if (!skipDemo) {
+        await seedDemo(paths, state, budget);
+        console.log(`✓ Sample agent "${DEMO_AGENT}" is ready`);
+        const approved = values.yes || (await promptYesNo(`Run it now with a maximum budget of $${budget.toFixed(2)}?`, true));
+        if (approved)
+            runDemo(paths);
+        else
+            console.log(`Skipped the billed run. Start it later with: npx @wardby/cli@latest run ${DEMO_AGENT}`);
+    }
+    const client = parseClient(values.client) ?? (await chooseClient(nonInteractive));
+    if (client !== "none")
+        configureMcpClients(client, paths);
+    console.log("\nWardby is ready.");
+    console.log("  npx @wardby/cli@latest status");
+    console.log("  npx @wardby/cli@latest doctor");
+    console.log("  npx @wardby/cli@latest down");
+}
+async function databaseHealthy(paths) {
+    const env = readQuickstartEnv(paths);
+    if (!env.DATABASE_URL)
+        return false;
+    const { createPrismaClient } = await import("../core/db.js");
+    const db = createPrismaClient(env.DATABASE_URL);
+    try {
+        await db.$queryRawUnsafe("SELECT 1");
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await db.$disconnect();
+    }
+}
+export async function doctorCommand(args) {
+    parseArgs({ args, options: {} });
+    const paths = quickstartPaths(resolveProjectDir());
+    const checks = [];
+    checks.push(["Node.js 24 or newer", nodeMajor() >= 24, process.versions.node]);
+    checks.push(["Docker CLI", runCommand("docker", ["--version"]).status === 0]);
+    checks.push(["Docker Compose v2", runCommand("docker", ["compose", "version"]).status === 0]);
+    checks.push(["Docker daemon", runCommand("docker", ["info"]).status === 0]);
+    let state;
+    try {
+        state = readQuickstartState(paths);
+        checks.push(["Quickstart state", state !== undefined, paths.stateFile]);
+    }
+    catch (error) {
+        checks.push(["Quickstart state", false, error instanceof Error ? error.message : String(error)]);
+    }
+    const env = readQuickstartEnv(paths);
+    const key = state ? providerKeyName(state.provider) : undefined;
+    checks.push(["Private configuration", Object.keys(env).length > 0, paths.envFile]);
+    if (Object.keys(env).length > 0) {
+        const mode = statSync(paths.envFile).mode & 0o777;
+        checks.push(["Configuration permissions", (mode & 0o077) === 0, mode.toString(8)]);
+        checks.push(["Secret encryption key", /^[a-f0-9]{64}$/i.test(env.SECRET_APP_KEY ?? "")]);
+        if (key)
+            checks.push([`${key} configured`, Boolean(env[key] || process.env[key])]);
+    }
+    if (state) {
+        const ps = runCompose(paths, state, ["ps", "--status", "running", "--quiet"]);
+        checks.push(["PostgreSQL container", ps.status === 0 && ps.stdout.trim().length > 0]);
+        checks.push(["Database connection", await databaseHealthy(paths)]);
+        const invocation = prismaMigrateInvocation("status", runtimeEnv(paths));
+        if (!invocation.local)
+            console.log(FETCH_NOTICE);
+        const migrations = runPrismaMigrateInvocation(invocation, paths.projectDir);
+        checks.push([
+            "Database migrations",
+            migrations.status === 0,
+            migrations.status === 0 ? undefined : migrateFailureReason(migrations),
+        ]);
+    }
+    let failed = false;
+    for (const [name, ok, detail] of checks) {
+        failed ||= !ok;
+        console.log(`${ok ? "✓" : "✗"} ${name}${detail ? ` (${detail})` : ""}`);
+    }
+    if (failed)
+        process.exitCode = 1;
+}
+export async function statusCommand(args) {
+    parseArgs({ args, options: {} });
+    const paths = quickstartPaths(resolveProjectDir());
+    const state = readQuickstartState(paths);
+    if (!state)
+        throw new Error(`Wardby is not initialized in ${paths.projectDir}; run \`wardby quickstart\`.`);
+    console.log(`project: ${state.projectDir}`);
+    console.log(`version: ${state.packageVersion}`);
+    console.log(`provider/model: ${state.provider} / ${state.model}`);
+    console.log(`postgres: 127.0.0.1:${state.postgresPort}`);
+    const ps = runCompose(paths, state, ["ps"]);
+    if (ps.status !== 0)
+        commandFailure("Docker Compose status", ps);
+    process.stdout.write(ps.stdout);
+    const healthy = await databaseHealthy(paths);
+    console.log(`database: ${healthy ? "healthy" : "unavailable"}`);
+    if (!healthy)
+        process.exitCode = 1;
+}
+export async function logsCommand(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            follow: { type: "boolean", short: "f" },
+            tail: { type: "string" },
+        },
+    });
+    const paths = quickstartPaths(resolveProjectDir());
+    const state = readQuickstartState(paths);
+    if (!state)
+        throw new Error(`Wardby is not initialized in ${paths.projectDir}; run \`wardby quickstart\`.`);
+    const composeLogArgs = ["logs", "--tail", values.tail ?? "100"];
+    if (values.follow)
+        composeLogArgs.push("--follow");
+    const result = runCompose(paths, state, composeLogArgs, { inherit: true });
+    if (result.status !== 0)
+        throw new Error("Docker Compose logs failed.");
+}
+export async function downCommand(args) {
+    const { values } = parseArgs({ args, options: { volumes: { type: "boolean" } } });
+    const paths = quickstartPaths(resolveProjectDir());
+    const state = readQuickstartState(paths);
+    if (!state)
+        throw new Error(`Wardby is not initialized in ${paths.projectDir}; nothing to stop.`);
+    const composeDownArgs = ["down"];
+    if (values.volumes)
+        composeDownArgs.push("--volumes");
+    const result = runCompose(paths, state, composeDownArgs, { inherit: true });
+    if (result.status !== 0)
+        throw new Error("Docker Compose shutdown failed.");
+    console.log(values.volumes ? "Wardby stopped and its local database volume was removed." : "Wardby stopped; data retained.");
+}

package/dist/quickstart/migrate.d.ts

@@ -0,0 +1,23 @@
+export declare const PRISMA_CLI_VERSION = "7.10.0";
+export declare const FETCH_NOTICE = "Fetching the Prisma CLI (prisma@7.10.0)\u2026";
+export declare const REGISTRY_FAILURE_MESSAGE: string;
+export declare const migrateConfigFile: string;
+export interface MigrateResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+    registryFailure?: boolean;
+}
+export interface MigrateInvocation {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    local: boolean;
+}
+export declare function parseLocalPrismaVersion(stdout: string): string | undefined;
+export declare function probeLocalPrismaVersion(env: NodeJS.ProcessEnv): string | undefined;
+export declare function prismaMigrateInvocation(subcommand: "deploy" | "status", env: NodeJS.ProcessEnv, probe?: (env: NodeJS.ProcessEnv) => string | undefined): MigrateInvocation;
+export declare function classifyMigrateResult(result: MigrateResult, spawnError?: Error, local?: boolean): MigrateResult;
+export declare function migrateFailureReason(result: MigrateResult): string;
+export declare function runPrismaMigrateInvocation(invocation: MigrateInvocation, cwd: string): MigrateResult;
+export declare function runPrismaMigrate(subcommand: "deploy" | "status", env: NodeJS.ProcessEnv, cwd: string, probe?: (env: NodeJS.ProcessEnv) => string | undefined): MigrateResult;

package/dist/quickstart/migrate.js

@@ -0,0 +1,125 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+// The installed npm package does not carry the Prisma CLI (a devDependency:
+// its tree pulled advisories into every consumer install), so quickstart and
+// doctor first look for a `prisma` executable on PATH and use it only if it
+// reports exactly this version; anything else -- wrong version, not on PATH,
+// a spawn error, a non-zero exit, or a timeout -- falls back to running the
+// pinned version through npx, with a config file shipped in the package.
+// Keep this equal to package.json's devDependencies.prisma (migrate.test.ts
+// enforces it).
+//
+// Not supported on Windows: npx is `npx.cmd` there (and a local install would
+// be `prisma.cmd`), which spawnSync can only run through a shell, and
+// quickstart has no win32 handling anywhere else (Docker Compose paths,
+// POSIX file modes) either.
+export const PRISMA_CLI_VERSION = "7.10.0";
+export const FETCH_NOTICE = `Fetching the Prisma CLI (prisma@${PRISMA_CLI_VERSION})…`;
+export const REGISTRY_FAILURE_MESSAGE = `Could not download the Prisma CLI (prisma@${PRISMA_CLI_VERSION}) from the npm registry. ` +
+    "quickstart and doctor fetch it on demand. Check your internet connection or npm registry settings " +
+    "(.npmrc, proxy), then retry. You can also install it yourself " +
+    `(\`npm i -g prisma@${PRISMA_CLI_VERSION}\`) and rerun quickstart -- doctor benefits too.`;
+export const migrateConfigFile = fileURLToPath(new URL("../../prisma/migrate.config.mjs", import.meta.url));
+// A short timeout so a wedged or misbehaving local binary can't stall
+// quickstart/doctor -- any hang past this falls back to npx.
+const LOCAL_PRISMA_PROBE_TIMEOUT_MS = 5000;
+// `prisma --version` prints a fixed-label, padded-column report, e.g.:
+//   prisma               : 7.10.0
+//   @prisma/client       : 7.10.0
+//   Operating System     : darwin
+//   ...
+// Several other lines carry their own version-shaped numbers (Node.js,
+// TypeScript, the schema engine hash), so key off the "prisma" label
+// specifically -- not the first x.y.z token anywhere in the output.
+const LOCAL_VERSION_LINE = /^prisma\s*:\s*(\S+)$/m;
+export function parseLocalPrismaVersion(stdout) {
+    return LOCAL_VERSION_LINE.exec(stdout)?.[1];
+}
+// Runs a local `prisma --version` under the given env's PATH and returns the
+// version it reports, or undefined for anything that isn't a clean match:
+// not on PATH, a spawn error, a non-zero exit, a timeout, or unparseable
+// output. Never throws.
+export function probeLocalPrismaVersion(env) {
+    const result = spawnSync("prisma", ["--version"], {
+        env,
+        encoding: "utf8",
+        stdio: "pipe",
+        timeout: LOCAL_PRISMA_PROBE_TIMEOUT_MS,
+    });
+    if (result.error || result.status !== 0)
+        return undefined;
+    return parseLocalPrismaVersion(result.stdout ?? "");
+}
+// DATABASE_URL travels in the child's environment only -- never argv, where
+// any local user could read it from the process table. `probe` is injectable
+// so tests never depend on the developer's real PATH.
+export function prismaMigrateInvocation(subcommand, env, probe = probeLocalPrismaVersion) {
+    const childEnv = {
+        ...env,
+        PRISMA_HIDE_UPDATE_MESSAGE: "1",
+        npm_config_update_notifier: "false",
+        npm_config_fund: "false",
+    };
+    if (probe(childEnv) === PRISMA_CLI_VERSION) {
+        return {
+            command: "prisma",
+            args: ["migrate", subcommand, "--config", migrateConfigFile],
+            env: childEnv,
+            local: true,
+        };
+    }
+    return {
+        command: "npx",
+        args: ["--yes", `prisma@${PRISMA_CLI_VERSION}`, "migrate", subcommand, "--config", migrateConfigFile],
+        env: childEnv,
+        local: false,
+    };
+}
+// npm's own error lines when it cannot fetch a package (npm 7+ prints
+// "npm error", older "npm ERR!"): network failures and registry HTTP / version
+// errors. A failed migration is printed by Prisma itself and never carries
+// these -- in particular a database ECONNREFUSED is Prisma's P1001, not an
+// "npm error code" line.
+const REGISTRY_ERROR = /^npm (?:error|ERR!) (?:code|errno) (?:ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ETARGET|E[45]\d\d)\b|^npm (?:error|ERR!) network /m;
+// `local` marks that `result`/`spawnError` came from the locally installed
+// binary rather than npx: nothing was fetched, so neither an npm-shaped
+// error line nor a spawn error is a registry failure there -- a spawn error
+// still gets a clear message (below), just not that one.
+export function classifyMigrateResult(result, spawnError, local = false) {
+    if (spawnError) {
+        if (local)
+            return { ...result, status: 1, stderr: spawnError.message };
+        return { ...result, status: 1, stderr: spawnError.message, registryFailure: true };
+    }
+    if (!local && result.status !== 0 && REGISTRY_ERROR.test(result.stderr))
+        return { ...result, registryFailure: true };
+    return result;
+}
+// The one-line reason for a failed run: the registry message, or Prisma's own
+// first error line (URLs masked, though Prisma prints host and database only).
+export function migrateFailureReason(result) {
+    if (result.registryFailure)
+        return REGISTRY_FAILURE_MESSAGE;
+    const lines = `${result.stderr}\n${result.stdout}`
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    // A line that starts with "Error", or that carries a Prisma error code anywhere.
+    const line = lines.find((candidate) => candidate.startsWith("Error") || /\bP\d{4}\b/.test(candidate)) ?? lines[0] ?? "no output";
+    return line.replace(/postgres(ql)?:\/\/[^\s`'"]+/gi, "<database url>");
+}
+// Runs an already-resolved invocation (from `prismaMigrateInvocation`). Split
+// out so callers can decide whether to print `FETCH_NOTICE` -- which only
+// applies to the npx path -- before running it.
+export function runPrismaMigrateInvocation(invocation, cwd) {
+    const result = spawnSync(invocation.command, invocation.args, {
+        cwd,
+        env: invocation.env,
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    return classifyMigrateResult({ status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" }, result.error, invocation.local);
+}
+export function runPrismaMigrate(subcommand, env, cwd, probe) {
+    return runPrismaMigrateInvocation(prismaMigrateInvocation(subcommand, env, probe), cwd);
+}