@remotedraw/cli 0.2.1 → 0.3.0

package/dist/scan.js

@@ -0,0 +1,563 @@
+/**
+ * `remotedraw scan` — read a codebase before proposing how RemoteDraw fits it.
+ *
+ * A coding agent handed "add RemoteDraw" and nothing else has two failure
+ * modes: inventing a product (a drawing lab nobody asked for) and inventing an
+ * implementation (a hand-written HTTP sender in a sheet when the SDK ships a
+ * full-screen surface). This command removes the excuse for both. It walks the
+ * project, names what is there — web frameworks, server-side code, iOS apps,
+ * an existing RemoteDraw wiring — and turns that into integration options plus
+ * the product questions only the user can answer.
+ *
+ * It reads manifests and file names, never file contents beyond a few kilobytes
+ * of Swift (`import SwiftUI`), and reports env *keys*, never values.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { detectPackageManager, packageManagerCommands, } from "./packageManagers.js";
+const SKIPPED_DIRECTORIES = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    ".nuxt",
+    ".svelte-kit",
+    ".output",
+    ".turbo",
+    ".cache",
+    "coverage",
+    "DerivedData",
+    "Pods",
+    "Carthage",
+    ".build",
+    ".swiftpm",
+    "vendor",
+    "target",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".agent-worktrees",
+    ".claude",
+    ".sandbox",
+]);
+const MAX_DEPTH = 4;
+const MAX_DIRECTORIES = 4000;
+const SWIFT_SAMPLE_LIMIT = 40;
+async function listDirectory(dirPath, runtime) {
+    try {
+        if (runtime.readdir)
+            return await runtime.readdir(dirPath);
+        return await readdir(dirPath);
+    }
+    catch {
+        return [];
+    }
+}
+async function isDirectory(filePath) {
+    try {
+        return (await stat(filePath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function readText(filePath, runtime) {
+    try {
+        return await runtime.readFile(filePath);
+    }
+    catch {
+        try {
+            return await readFile(filePath, "utf8");
+        }
+        catch {
+            return "";
+        }
+    }
+}
+async function readManifest(filePath, runtime) {
+    const text = await readText(filePath, runtime);
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** Breadth-first walk, bounded, skipping build output and dependencies. */
+async function walk(root, runtime) {
+    const queue = [{ dir: root, depth: 0 }];
+    const visited = [];
+    while (queue.length > 0 && visited.length < MAX_DIRECTORIES) {
+        const next = queue.shift();
+        const entries = await listDirectory(next.dir, runtime);
+        const relative = path.relative(root, next.dir) || ".";
+        visited.push({ dir: next.dir, relative, entries, depth: next.depth });
+        if (next.depth >= MAX_DEPTH)
+            continue;
+        for (const entry of entries) {
+            if (entry.startsWith("._"))
+                continue;
+            if (SKIPPED_DIRECTORIES.has(entry))
+                continue;
+            // Xcode projects and bundles are directories a walker has no business in.
+            if (/\.(xcodeproj|xcworkspace|xcassets|app|framework|bundle|playground)$/.test(entry)) {
+                continue;
+            }
+            const child = path.join(next.dir, entry);
+            if (await isDirectory(child))
+                queue.push({ dir: child, depth: next.depth + 1 });
+        }
+    }
+    return visited;
+}
+function allDependencies(manifest) {
+    return {
+        ...manifest.peerDependencies,
+        ...manifest.devDependencies,
+        ...manifest.dependencies,
+    };
+}
+const WEB_FRAMEWORKS = [
+    ["next", "next"],
+    ["react", "react"],
+    ["react-dom", "react-dom"],
+    ["@sveltejs/kit", "sveltekit"],
+    ["svelte", "svelte"],
+    ["vue", "vue"],
+    ["nuxt", "nuxt"],
+    ["@angular/core", "angular"],
+    ["solid-js", "solid"],
+    ["@remix-run/react", "remix"],
+    ["react-router", "react-router"],
+    ["react-router-dom", "react-router"],
+    ["vite", "vite"],
+    ["@tanstack/react-router", "tanstack-router"],
+    ["expo", "expo"],
+    ["react-native", "react-native"],
+    ["electron", "electron"],
+    ["@tauri-apps/api", "tauri"],
+];
+const SERVER_FRAMEWORKS = [
+    ["convex", "convex"],
+    ["express", "express"],
+    ["fastify", "fastify"],
+    ["hono", "hono"],
+    ["koa", "koa"],
+    ["@nestjs/core", "nestjs"],
+    ["@trpc/server", "trpc"],
+    ["@vercel/node", "vercel-functions"],
+    ["firebase-functions", "firebase-functions"],
+    ["@supabase/supabase-js", "supabase"],
+    ["@aws-sdk/client-lambda", "aws-lambda"],
+    ["aws-lambda", "aws-lambda"],
+    ["next", "next-route-handlers"],
+    ["@sveltejs/kit", "sveltekit-endpoints"],
+    ["nuxt", "nuxt-server"],
+    ["@remix-run/node", "remix-loaders"],
+];
+const SERVER_DIRECTORIES = ["server", "api", "backend", "functions", "convex", "worker", "workers", "lambda", "netlify/functions", "supabase/functions"];
+function classifyManifest(manifest, entries, relative) {
+    const deps = allDependencies(manifest);
+    const frameworks = [];
+    const evidence = [];
+    const serverSide = [];
+    const add = (label, proof) => {
+        if (!frameworks.includes(label))
+            frameworks.push(label);
+        evidence.push(proof);
+    };
+    let web = false;
+    for (const [dependency, label] of WEB_FRAMEWORKS) {
+        if (deps[dependency]) {
+            add(label, `${relative}/package.json depends on ${dependency}`);
+            if (!["electron", "tauri", "expo", "react-native"].includes(label))
+                web = true;
+        }
+    }
+    let server = false;
+    for (const [dependency, label] of SERVER_FRAMEWORKS) {
+        if (deps[dependency]) {
+            add(label, `${relative}/package.json depends on ${dependency}`);
+            server = true;
+            serverSide.push(label);
+        }
+    }
+    for (const directory of SERVER_DIRECTORIES) {
+        const [head] = directory.split("/");
+        if (head && entries.includes(head)) {
+            const proof = `${relative}/${directory}/ exists`;
+            if (!evidence.includes(proof))
+                evidence.push(proof);
+            server = true;
+            if (!serverSide.includes(directory))
+                serverSide.push(directory);
+        }
+    }
+    if (entries.includes("app") && deps.next) {
+        serverSide.push("app/**/route.ts (Next.js route handlers)");
+    }
+    if (entries.includes("pages") && deps.next) {
+        serverSide.push("pages/api (Next.js API routes)");
+    }
+    const kind = web
+        ? "web"
+        : server
+            ? "server"
+            : frameworks.length > 0
+                ? "web"
+                : manifest.private === false || entries.includes("src")
+                    ? "library"
+                    : "unknown";
+    return { kind, frameworks, evidence, serverSide };
+}
+async function detectSwiftUI(dir, entries, runtime) {
+    const swiftFiles = entries.filter((entry) => entry.endsWith(".swift")).slice(0, SWIFT_SAMPLE_LIMIT);
+    let swiftui = false;
+    let uikit = false;
+    for (const file of swiftFiles) {
+        const text = await readText(path.join(dir, file), runtime);
+        const head = text.slice(0, 4000);
+        if (/^\s*import SwiftUI/m.test(head))
+            swiftui = true;
+        if (/^\s*import UIKit/m.test(head))
+            uikit = true;
+        if (swiftui && uikit)
+            break;
+    }
+    return { swiftui, uikit, sampled: swiftFiles.length };
+}
+export async function scanProject(root, runtime) {
+    const visited = await walk(root, runtime);
+    const projects = [];
+    const configFiles = [];
+    const remotedrawPackages = new Set();
+    const envKeys = new Set();
+    let swiftPackage = false;
+    // iOS apps announce themselves by an .xcodeproj / .xcworkspace / project.yml
+    // beside their sources; Swift files under that directory tell us the UI
+    // framework. A directory holding both is one project, not two.
+    const iosRoots = new Map();
+    for (const entry of visited) {
+        const relative = entry.relative;
+        if (entry.entries.includes("remotedraw.config.json")) {
+            configFiles.push(relative === "." ? "remotedraw.config.json" : `${relative}/remotedraw.config.json`);
+        }
+        for (const envFile of entry.entries.filter((name) => /^\.env(\..+)?$/.test(name))) {
+            const text = await readText(path.join(entry.dir, envFile), runtime);
+            for (const match of text.matchAll(/^\s*(REMOTEDRAW_[A-Z0-9_]+)\s*=/gm)) {
+                envKeys.add(match[1]);
+            }
+        }
+        if (entry.entries.includes("package.json")) {
+            const manifest = await readManifest(path.join(entry.dir, "package.json"), runtime);
+            if (manifest) {
+                const deps = allDependencies(manifest);
+                for (const name of Object.keys(deps)) {
+                    if (name.startsWith("@remotedraw/"))
+                        remotedrawPackages.add(name);
+                }
+                const classified = classifyManifest(manifest, entry.entries, relative);
+                const isWorkspaceRoot = manifest.workspaces != null && classified.frameworks.length === 0;
+                if (!isWorkspaceRoot) {
+                    projects.push({
+                        path: relative,
+                        ...(manifest.name ? { name: manifest.name } : {}),
+                        kind: classified.kind,
+                        frameworks: classified.frameworks,
+                        evidence: classified.evidence,
+                        ...(classified.serverSide.length > 0 ? { serverSide: classified.serverSide } : {}),
+                    });
+                }
+            }
+        }
+        const xcode = entry.entries.filter((name) => !name.startsWith("._") && /\.(xcodeproj|xcworkspace)$/.test(name));
+        const hasProjectYml = entry.entries.includes("project.yml");
+        const hasPackageSwift = entry.entries.includes("Package.swift");
+        if (hasPackageSwift) {
+            const text = await readText(path.join(entry.dir, "Package.swift"), runtime);
+            if (text.includes("remotedraw-swift") || text.includes("RemoteDrawSenderKit"))
+                swiftPackage = true;
+        }
+        if (xcode.length > 0 || hasProjectYml) {
+            const project = {
+                path: relative,
+                kind: "ios",
+                frameworks: [],
+                evidence: xcode.map((name) => `${relative}/${name}`),
+            };
+            if (hasProjectYml)
+                project.evidence.push(`${relative}/project.yml (xcodegen)`);
+            for (const name of xcode) {
+                const pbxproj = path.join(entry.dir, name, "project.pbxproj");
+                const text = await readText(pbxproj, runtime);
+                if (text.includes("remotedraw-swift") || text.includes("RemoteDrawSenderKit"))
+                    swiftPackage = true;
+                if (text.includes("SwiftUI"))
+                    project.evidence.push(`${relative}/${name} references SwiftUI`);
+            }
+            const resolved = path.join(entry.dir, "Package.resolved");
+            if (entry.entries.includes("Package.resolved")) {
+                const text = await readText(resolved, runtime);
+                if (text.includes("remotedraw-swift"))
+                    swiftPackage = true;
+            }
+            iosRoots.set(relative, project);
+            projects.push(project);
+        }
+    }
+    // Second pass: UI framework per iOS root, from Swift files at or below it.
+    for (const [iosRelative, project] of iosRoots) {
+        let swiftui = false;
+        let uikit = false;
+        let sampled = 0;
+        for (const entry of visited) {
+            const inside = iosRelative === "." ||
+                entry.relative === iosRelative ||
+                entry.relative.startsWith(`${iosRelative}${path.sep}`) ||
+                entry.relative.startsWith(`${iosRelative}/`);
+            if (!inside || sampled >= SWIFT_SAMPLE_LIMIT)
+                continue;
+            const result = await detectSwiftUI(entry.dir, entry.entries, runtime);
+            sampled += result.sampled;
+            swiftui ||= result.swiftui;
+            uikit ||= result.uikit;
+        }
+        if (swiftui) {
+            project.frameworks.push("swiftui");
+            project.evidence.push("Swift sources import SwiftUI");
+        }
+        if (uikit) {
+            project.frameworks.push("uikit");
+            project.evidence.push("Swift sources import UIKit");
+        }
+        if (!swiftui && !uikit && sampled === 0) {
+            project.evidence.push("no Swift sources sampled under this directory");
+        }
+    }
+    const webProjects = projects.filter((project) => project.kind === "web");
+    const serverProjects = projects.filter((project) => project.kind === "server");
+    const iosProjects = projects.filter((project) => project.kind === "ios");
+    const serverSide = [
+        ...serverProjects.map((project) => project.path),
+        ...webProjects.flatMap((project) => (project.serverSide ?? []).map((location) => project.path === "." ? location : `${project.path} (${location})`)),
+    ];
+    const recommendations = buildRecommendations({
+        webProjects,
+        iosProjects,
+        serverSide,
+        swiftPackage,
+    });
+    const keyBoundary = { serverSide };
+    if (serverSide.length === 0) {
+        keyBoundary.warning =
+            "No server-side code was found. POST /v1/sessions needs an rd_sk_ key, which must never ship in a browser or app bundle — ask the user where their backend (or a serverless function) lives before scaffolding anything.";
+    }
+    const detected = await detectPackageManager(root, { env: runtime.env ?? {}, exists: runtime.exists, readFile: runtime.readFile }, { pathModule: path });
+    const managerCommands = packageManagerCommands[detected.manager];
+    return {
+        ok: true,
+        command: "scan",
+        schemaVersion: 1,
+        root,
+        packageManager: {
+            id: detected.manager,
+            reason: detected.reason,
+            commands: {
+                install: managerCommands.install,
+                add: managerCommands.add,
+                dlx: managerCommands.dlx,
+                run: managerCommands.run,
+            },
+        },
+        projects,
+        remotedraw: {
+            configured: configFiles.length > 0 || remotedrawPackages.size > 0 || swiftPackage,
+            configFiles,
+            packages: [...remotedrawPackages].sort(),
+            envKeys: [...envKeys].sort(),
+            swiftPackage,
+        },
+        keyBoundary,
+        recommendations,
+        questions: productQuestions({ webProjects, iosProjects }),
+        rules: INTEGRATION_RULES,
+    };
+}
+const SWIFT_PACKAGE_LINE = 'Add https://github.com/AxioSOzo/remotedraw-swift.git (from: "0.1.0"), product RemoteDrawSenderKit';
+function buildRecommendations(input) {
+    const { webProjects, iosProjects, serverSide } = input;
+    const recommendations = [];
+    const keyLocation = serverSide.length > 0
+        ? `Session creation (rd_sk_) belongs in: ${serverSide.join(", ")}`
+        : "No server-side location found — ask the user; do not scaffold createRemoteDrawSession into client source.";
+    const receiverFor = (project) => {
+        const frameworks = project.frameworks;
+        if (frameworks.includes("svelte") || frameworks.includes("sveltekit")) {
+            return {
+                receiver: `@remotedraw/svelte receiver store in ${project.path}`,
+                packages: ["@remotedraw/svelte"],
+                sdk: "svelte",
+            };
+        }
+        if (frameworks.includes("react") || frameworks.includes("next") || frameworks.includes("remix")) {
+            return {
+                receiver: `@remotedraw/react — RemoteDrawProvider + RemoteDrawReceiver + PairingCode in ${project.path}`,
+                packages: ["@remotedraw/react"],
+                sdk: "react",
+            };
+        }
+        return {
+            receiver: `@remotedraw/client — createHttpReceiverClient + createRealtimeReceiverSource in ${project.path} (${frameworks.join(", ") || "no framework detected"})`,
+            packages: ["@remotedraw/client"],
+            sdk: "js",
+        };
+    };
+    for (const project of webProjects) {
+        const { receiver, packages, sdk } = receiverFor(project);
+        const hasIos = iosProjects.length > 0;
+        recommendations.push({
+            id: `web-receiver:${project.path}`,
+            title: hasIos
+                ? `Receiver in ${project.path}, sender in the existing iOS app`
+                : `Receiver in ${project.path}, hosted phone sender (no phone code)`,
+            fit: "strong",
+            receiver,
+            sender: hasIos
+                ? `RemoteDrawSenderKit full-screen surface in ${iosProjects.map((p) => p.path).join(", ")}; the backend mints an rd_send_ token with POST /v1/sessions/direct-sender for a signed-in user, QR scan stays as the fallback`
+                : "The hosted /join page: render the session's joinUrl as a QR (PairingCode). The phone opens it in Safari or the RemoteDraw iOS app; you ship no sender code.",
+            keyLocation,
+            why: hasIos
+                ? "The product already has a phone app; making it the pen removes the QR step for signed-in users and keeps the drawing experience native."
+                : "The sender is not where the product adds value; the hosted pad is polished, full screen, and costs no code.",
+            commands: [
+                `remotedraw init --non-interactive --dry-run --format json --path ${project.path} --target web --sender ${hasIos ? "own-ios --sdk " + sdk : "remotedraw-ios --sdk " + sdk} --preset sketch`,
+            ],
+            packages,
+        });
+    }
+    for (const project of iosProjects) {
+        const swiftui = project.frameworks.includes("swiftui");
+        recommendations.push({
+            id: `ios-sender:${project.path}`,
+            title: `Native full-screen sender in ${project.path} (RemoteDrawSenderKit)`,
+            fit: swiftui ? "strong" : "possible",
+            receiver: webProjects.length > 0
+                ? `See web-receiver:${webProjects[0].path}`
+                : "Ask: which screen shows the drawing? A web app, a desktop app, or another device?",
+            sender: swiftui
+                ? "`.remoteDrawSurface(isPresented:senderToken:)` — the first-party board presented full screen with an exit; or `RemoteDrawTakeover` inside your own fullScreenCover"
+                : "`RemoteDrawTakeover` hosted in a UIHostingController presented full screen (UIKit app); do not build a canvas view",
+            keyLocation,
+            why: "It is the same board the RemoteDraw app ships: paper, instruments, undo, submit, exit. A custom canvas is a smaller, worse copy that also has to reimplement the wire protocol.",
+            commands: [SWIFT_PACKAGE_LINE],
+            packages: ["RemoteDrawSenderKit (SwiftPM)"],
+        });
+    }
+    if (webProjects.length === 0 && iosProjects.length === 0) {
+        recommendations.push({
+            id: "no-surface-found",
+            title: "No web or iOS surface detected",
+            fit: "possible",
+            receiver: "Ask the user which screen should show the drawing before choosing an SDK.",
+            sender: "Hosted /join page by default.",
+            keyLocation,
+            why: "Nothing in this tree identifies a receiver surface; scaffolding blind produces a demo, not an integration.",
+            commands: ["remotedraw options --format json"],
+            packages: [],
+        });
+    }
+    return recommendations;
+}
+function productQuestions(input) {
+    const questions = [
+        "Which screen in the product already shows the thing people will draw on, and what device is that screen on? RemoteDraw needs two devices: that screen is the receiver, and a phone is the pen. If the only screen involved is the phone's own, this is not a RemoteDraw flow.",
+        "What is on that screen — a blank sketch surface, a photo your app already shows, a PDF page it renders, a map it owns, a form field, or a shared screen? This picks target.kind and the preset. Your app renders it; the phone never supplies it.",
+        "Where does the receiver go? Name the existing screen or route; RemoteDraw does not get its own page unless the user asks for a demo.",
+        "Who holds the phone — the same signed-in user (direct sender, no QR), or anyone who scans (QR join)?",
+        "What happens to the drawing when the phone taps Submit — saved to which record, shown where, exported how?",
+        "Is this a minimal demo to evaluate RemoteDraw, or the real feature? A demo is one page; the feature is the answers above.",
+    ];
+    if (input.iosProjects.length > 0) {
+        questions.push("In the iOS app: should drawing take over the whole app (full-screen cover, default) or open as a sheet? Either way the surface fills the presentation; there is no small-canvas option.");
+    }
+    if (input.webProjects.length === 0 && input.iosProjects.length > 0) {
+        questions.push("Which screen shows the drawing? Nothing in this repository looks like a receiver surface.");
+    }
+    return questions;
+}
+export const INTEGRATION_RULES = [
+    "RemoteDraw needs two devices: the receiver is a screen the user is already looking at (desktop, laptop, large display) showing your content, and the sender is a phone. A phone that photographs something and annotates it on its own screen is not a RemoteDraw flow — say so and propose PencilKit or a canvas instead.",
+    "The phone supplies a hand, not content. Your app renders the photo, the PDF page, the map, the form; the iOS sender opens no camera and no file picker.",
+    "Ask before installing anything (packages, CLI, Swift package) — name what and why, then wait.",
+    "rd_sk_ keys live only in server-side code found by this scan; never in Vite/Next client source, Swift, or an app bundle.",
+    "iOS senders use RemoteDrawSenderKit's full-screen surface (`.remoteDrawSurface` / `RemoteDrawTakeover`). Do not write a UIViewRepresentable canvas, and do not put a small canvas inside a sheet.",
+    "Web senders use the hosted /join page unless the user explicitly wants an in-page sender.",
+    "Bluetooth and local-network pairing are not implemented anywhere in the product — the radios only advertise, nothing scans. Do not offer them; QR and direct sender are the real methods. There is no native Android SDK and no desktop sender either.",
+    "Use the ready-made components: PairingCode / RemoteDrawConnect / RemoteDrawLaunchButton for pairing, RemoteDrawReceiver (or RemoteDrawMapReceiver over a map) for ink, RemoteDrawSessionControls for state. Do not hand-roll a connect button, an SVG receiver, or a polling loop.",
+    "Timestamps (`occurredAt`, point `t`) are integer milliseconds; the SDKs handle this, hand-written clients often do not.",
+    "Session creation is billable and not idempotent: guard React StrictMode double effects, and persist the receiverToken if the receiver outlives a page load.",
+    "One API key serves every tenant: scope sessions with externalId and verify it before attaching a sender or ending a session.",
+    "Do not delete or replace existing features in the host app; integrate beside them and let the user decide what retires.",
+];
+export function renderScanText(report) {
+    const lines = [];
+    lines.push("RemoteDraw scan", "");
+    lines.push(`Root: ${report.root}`);
+    lines.push(`Package manager: ${report.packageManager.id} (${report.packageManager.reason})`, "");
+    lines.push("Projects:");
+    if (report.projects.length === 0)
+        lines.push("  (none detected)");
+    for (const project of report.projects) {
+        const frameworks = project.frameworks.length > 0 ? ` [${project.frameworks.join(", ")}]` : "";
+        lines.push(`  ${project.kind.padEnd(8)} ${project.path}${project.name ? ` (${project.name})` : ""}${frameworks}`);
+        for (const proof of project.evidence)
+            lines.push(`             - ${proof}`);
+    }
+    lines.push("");
+    lines.push("Existing RemoteDraw wiring:");
+    if (!report.remotedraw.configured) {
+        lines.push("  none — this is a fresh integration");
+    }
+    else {
+        if (report.remotedraw.configFiles.length > 0)
+            lines.push(`  config: ${report.remotedraw.configFiles.join(", ")}`);
+        if (report.remotedraw.packages.length > 0)
+            lines.push(`  packages: ${report.remotedraw.packages.join(", ")}`);
+        if (report.remotedraw.swiftPackage)
+            lines.push("  swift: RemoteDrawSenderKit is already a dependency");
+        if (report.remotedraw.envKeys.length > 0)
+            lines.push(`  env keys: ${report.remotedraw.envKeys.join(", ")}`);
+    }
+    lines.push("");
+    lines.push("Where the API key may live:");
+    if (report.keyBoundary.serverSide.length === 0) {
+        lines.push(`  ${report.keyBoundary.warning}`);
+    }
+    else {
+        for (const location of report.keyBoundary.serverSide)
+            lines.push(`  ${location}`);
+    }
+    lines.push("");
+    lines.push("Integration options:");
+    for (const recommendation of report.recommendations) {
+        lines.push(`  [${recommendation.fit}] ${recommendation.title}`);
+        lines.push(`    receiver: ${recommendation.receiver}`);
+        lines.push(`    sender:   ${recommendation.sender}`);
+        lines.push(`    key:      ${recommendation.keyLocation}`);
+        lines.push(`    why:      ${recommendation.why}`);
+        for (const command of recommendation.commands)
+            lines.push(`    next:     ${command}`);
+    }
+    lines.push("");
+    lines.push("Ask the user before building:");
+    report.questions.forEach((question, index) => lines.push(`  ${index + 1}. ${question}`));
+    lines.push("");
+    lines.push("Rules for the implementation:");
+    for (const rule of report.rules)
+        lines.push(`  - ${rule}`);
+    return lines.join("\n");
+}

package/dist/telemetry.d.ts

@@ -16,7 +16,7 @@ export type TelemetryEnvironment = {
     platform: string;
     nodeVersion: string;
     /** Injected by the test suite so no suite run can reach the network. */
-    fetch?: typeof fetch | undefined;
+    fetch?: ((input: string | URL | Request, init?: RequestInit) => Promise<Response>) | undefined;
 };
 /**
  * Off whenever the user says so, and off in CI, where a crash report has no

package/dist/telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,MAAM,MAAM,oBAAoB,GAAG;IACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,WAOxE;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM,UAW7C;AAmBD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsClC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,oBAAoB,iBA+BlC;AAED,gEAAgE;AAChE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,GACd,oBAAoB,CAOtB"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,MAAM,MAAM,oBAAoB,GAAG;IACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,KAAK,CAAC,EACF,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,GAC1E,SAAS,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,WAOxE;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM,UAW7C;AAmBD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsClC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,oBAAoB,iBA+BlC;AAED,gEAAgE;AAChE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,GACd,oBAAoB,CAOtB"}

package/dist/update.d.ts

@@ -1,4 +1,5 @@
 import { type CloudRuntime } from "./cloud.js";
+import { type PackageManagerId } from "./packageManagers.js";
 export declare const CLI_PACKAGE_NAME = "@remotedraw/cli";
 export type UpdateRuntime = CloudRuntime & {
     /**
@@ -12,8 +13,12 @@ export type UpdateRuntime = CloudRuntime & {
 };
 export type InstallMethod = {
     /** Package manager the binary appears to have been installed with. */
-    manager: "npm" | "pnpm" | "yarn" | "bun";
-    /** True when the binary was resolved by npx/bunx, which never needs updating. */
+    manager: PackageManagerId;
+    /**
+     * True when the binary was resolved by a throwaway runner (npx, pnpm dlx,
+     * yarn dlx, bunx). Nothing survives the command, so there is nothing to
+     * update: the next run fetches the latest by itself.
+     */
     ephemeral: boolean;
     command: string;
     args: string[];
@@ -29,10 +34,11 @@ export declare function parseVersion(value: string): {
 };
 export declare function compareVersions(a: string, b: string): 1 | 0 | -1;
 /**
- * Derives the update command from where the running binary lives. Guessing
- * wrong only prints the wrong suggestion, so the fallback is plain npm.
+ * Derives the update command from where the running binary lives, falling back
+ * to the manager that invoked us. Guessing wrong only prints the wrong
+ * suggestion, so the last fallback is plain npm.
  */
-export declare function detectInstallMethod(binPath: string): InstallMethod;
+export declare function detectInstallMethod(binPath: string, env?: Record<string, string | undefined>): InstallMethod;
 export declare function installMethodDisplay(method: InstallMethod): string;
 export declare function updateCachePath(runtime: UpdateRuntime): string;
 export declare function latestPublishedVersion(runtime: UpdateRuntime, timeoutMs?: number): Promise<string | undefined>;

package/dist/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../src/update.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAGjE,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAOlD,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG;IACzC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CACb,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,sEAAsE;IACtE,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IACzC,iFAAiF;IACjF,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAiBF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM;;;EAczC;AA2BD,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,cASnD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAoClE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,UAEzD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,UAErD;AAgDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,aAAa,EACtB,SAAS,SAAmB,+BAoC7B;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,WAO3E;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CA2BlC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,UAWrE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa;;;;;;GAM7E"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../src/update.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAOlD,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG;IACzC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CACb,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,sEAAsE;IACtE,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAiBF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM;;;EAczC;AA2BD,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,cASnD;AAuCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM,GAC3C,aAAa,CAsCf;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,UAEzD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,UAErD;AAgDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,aAAa,EACtB,SAAS,SAAmB,+BAoC7B;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,WAO3E;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CA2BlC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,UAWrE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa;;;;;;GAM7E"}