@nwire/cli 0.12.1 → 0.13.1

package/dist/lib/ensure-scan.js

@@ -4,36 +4,63 @@
  * every CLI command that reads the scan cache.
  *
  * Cheap path: compute fingerprint, compare to saved; if match, return.
- * Expensive path: spawn the cache-runner under vite-node to rebuild,
- * then save the new fingerprint. The expensive path runs at most once
- * per source change.
+ * Expensive path: rebuild the manifest IN-PROCESS via `@nwire/scan`'s
+ * `buildManifest` + `writeManifest` — a pure static scan of the source
+ * tree plus the folded `.nwire/topology.json` a running app self-emits.
+ * No app boot, no loader, no subprocess.
+ *
+ * If `.nwire/topology.json` is absent (the app has never run), the
+ * manifest still writes — static-only; the topology layer fills in the
+ * next time the app runs and re-emits.
  */
-import { existsSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { buildManifest, writeManifest } from "@nwire/scan";
 import { palette } from "./colors.js";
-import { execSync } from "./exec.js";
+import { loadConfig } from "../load-config.js";
 import { fingerprint, isFresh, writeFingerprint } from "./scan-cache.js";
-const here = dirname(fileURLToPath(import.meta.url));
-export function ensureScanFresh(cwd = process.cwd(), opts = {}) {
+/**
+ * Read the app name from the emitted `<cwd>/.nwire/topology.json` so the
+ * static manifest tags records with the same name a running app reports.
+ * The static scan treats the name as a label only, so an empty string is
+ * harmless when no topology has been emitted yet.
+ */
+function appNameFromTopology(cwd) {
+    const p = resolve(cwd, ".nwire", "topology.json");
+    if (!existsSync(p))
+        return "";
+    try {
+        const file = JSON.parse(readFileSync(p, "utf8"));
+        return file.topology?.apps?.[0]?.name ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+export async function ensureScanFresh(cwd = process.cwd(), opts = {}) {
     const fp = fingerprint(cwd);
     if (!opts.force && isFresh(cwd, fp)) {
         return { rebuilt: false, fingerprint: fp };
     }
-    const builderPath = resolve(here, "..", "cache-runner.js");
-    if (!existsSync(builderPath)) {
-        // Builder is missing from dist (dev-mode oddity). Skip — commands
-        // that need the cache will surface their own "no manifest" error.
-        return { rebuilt: false, fingerprint: fp };
-    }
     if (!opts.quiet) {
         // eslint-disable-next-line no-console
         console.error(palette.dim("scanning project…"));
     }
-    const code = execSync("pnpm", ["exec", "vite-node", builderPath]);
-    if (code !== 0) {
-        // Cache build failed; keep whatever's on disk. Don't update the
-        // fingerprint, so the next call retries.
+    try {
+        const config = await loadConfig(cwd);
+        const appName = appNameFromTopology(cwd);
+        // Pure static scan + folded topology.json — no app boot, no loader.
+        const manifest = buildManifest(cwd, appName);
+        const outDir = resolve(cwd, config.cacheDir ?? ".nwire");
+        await writeManifest(manifest, outDir);
+    }
+    catch (err) {
+        if (!opts.quiet) {
+            // eslint-disable-next-line no-console
+            console.error(palette.err("nwire cache:") + ` scan failed — ${err.message}`);
+        }
+        // Keep whatever's on disk; don't update the fingerprint so the next
+        // call retries.
         return { rebuilt: false, fingerprint: fp };
     }
     writeFingerprint(cwd, fp);

package/dist/lib/studio-host-api.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Studio data API for the one-Vite dev host.
+ *
+ * The standalone Studio process serves `/__nwire/*` by reading `.nwire/`
+ * from disk and proxying `/_nwire/*` to a separately-started wire process.
+ * The one-Vite host has the wire running IN-PROCESS, which is strictly better:
+ *
+ *   - telemetry/live: subscribe `runtime.onTelemetry` directly — no disk writes
+ *     required, records arrive at zero-latency with no file-tail polling loop.
+ *   - manifest.json: serve the disk `.nwire/manifest.json` (built by `nwire cache`)
+ *     and, when a live runtime is present, fold in the runtime topology so the
+ *     manifest stays fresh even during HMR reloads without a full cache rebuild.
+ *   - telemetry/runs: disk-based history — same as standalone Studio (these are
+ *     past run files; there is no in-process equivalent).
+ *
+ * Routes owned here (all under `/__nwire/*`):
+ *
+ *   GET  /__nwire/manifest.json          disk (.nwire/manifest.json) + runtime fold
+ *   GET  /__nwire/telemetry/live         SSE — runtime.onTelemetry (runtime-direct)
+ *   GET  /__nwire/telemetry/runs         disk list { runs: TelemetryRunMeta[] }
+ *   GET  /__nwire/telemetry/runs/:id     disk single run { id, records: unknown[] }
+ *   GET  /__nwire/endpoints              list { endpoints: EndpointInfo[] }
+ *   POST /__nwire/endpoints/active       { name } → switch active HTTP front
+ *   *    /__nwire/run/*                  501 — supervisor belongs to standalone Studio
+ *   *    /__nwire/*                      501 — not yet implemented
+ *
+ * `/__nwire/project`, `/__nwire/source`, `/__nwire/projects/*` are the
+ * multi-project shell routes. They are out of scope for the dev-host context
+ * (the host always serves one project — the one it loaded) and return 501.
+ *
+ * The wire's own `/_nwire/*` surface (inspect, events) is NOT owned here. The
+ * dev-host routes it to `wireHandlers[0]` via the hardcoded prefix check in
+ * dev-host.ts (a known tech-debt; see the review findings). Once that prefix
+ * check is removed, the wire's handler self-dispatches via Connect-style `next`.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { DevHostMount } from "@nwire/endpoint";
+/** Minimal runtime surface needed by this module. Duck-typed so the host never
+ * imports from `@nwire/runtime` directly — it reads whatever the app exposes. */
+export interface RuntimeLike {
+    /** Subscribe to the telemetry stream. Returns an unsubscribe function. */
+    onTelemetry(listener: (record: unknown) => void): () => void;
+}
+/** Per-endpoint summary returned by `GET /__nwire/endpoints`. */
+export interface EndpointInfo {
+    /** Endpoint name — from `endpoint("name")`. */
+    readonly name: string;
+    /** True when this is the currently active HTTP front. */
+    readonly active: boolean;
+    /** True when this endpoint registered at least one HTTP handler. */
+    readonly hasHttp: boolean;
+}
+export interface StudioHostApiOptions {
+    /**
+     * Live mounts from the endpoint collector. The API reads `mount.apps[0].runtime`
+     * (duck-typed as `RuntimeLike`) from whichever mount has a booted forge app.
+     * Safe to pass a live, mutable array — the handler reads it on each request.
+     */
+    readonly mounts: readonly DevHostMount[];
+    /**
+     * Project root — where `.nwire/` lives. Defaults to `process.cwd()`.
+     */
+    readonly cwd?: string;
+    /**
+     * Return the name of the currently active HTTP front. Used by
+     * `GET /__nwire/endpoints` to mark the active entry. Optional — when
+     * absent, the API reports no endpoint as active.
+     */
+    readonly getActiveEndpointName?: () => string | undefined;
+    /**
+     * Switch the active HTTP front. Called by `POST /__nwire/endpoints/active`.
+     * Should throw when the named endpoint is not found. Optional — when absent,
+     * the switch endpoint returns 501.
+     */
+    readonly setActiveEndpoint?: (name: string) => void;
+}
+/** The handler signature: returns `true` when it handled the request (caller
+ * must not pass to the next handler), `false` to fall through. */
+export type StudioHostApiHandler = (req: IncomingMessage, res: ServerResponse) => boolean;
+/**
+ * Create the `/__nwire/*` request handler for the one-Vite dev host.
+ *
+ * Returns `true` when it handled the request (caller stops). `false` means
+ * the request was not for `/__nwire/*` and should fall through to Vite's
+ * middlewares.
+ *
+ * @example
+ * ```ts
+ * const studioApi = createStudioHostApi({ mounts, cwd: opts.cwd });
+ *
+ * const server = createHttpServer((req, res) => {
+ *   if (studioApi(req, res)) return;
+ *   vite.middlewares(req, res, () => { ... });
+ * });
+ * ```
+ */
+export declare function createStudioHostApi(opts: StudioHostApiOptions): StudioHostApiHandler;

package/dist/lib/studio-host-api.js

@@ -0,0 +1,337 @@
+/**
+ * Studio data API for the one-Vite dev host.
+ *
+ * The standalone Studio process serves `/__nwire/*` by reading `.nwire/`
+ * from disk and proxying `/_nwire/*` to a separately-started wire process.
+ * The one-Vite host has the wire running IN-PROCESS, which is strictly better:
+ *
+ *   - telemetry/live: subscribe `runtime.onTelemetry` directly — no disk writes
+ *     required, records arrive at zero-latency with no file-tail polling loop.
+ *   - manifest.json: serve the disk `.nwire/manifest.json` (built by `nwire cache`)
+ *     and, when a live runtime is present, fold in the runtime topology so the
+ *     manifest stays fresh even during HMR reloads without a full cache rebuild.
+ *   - telemetry/runs: disk-based history — same as standalone Studio (these are
+ *     past run files; there is no in-process equivalent).
+ *
+ * Routes owned here (all under `/__nwire/*`):
+ *
+ *   GET  /__nwire/manifest.json          disk (.nwire/manifest.json) + runtime fold
+ *   GET  /__nwire/telemetry/live         SSE — runtime.onTelemetry (runtime-direct)
+ *   GET  /__nwire/telemetry/runs         disk list { runs: TelemetryRunMeta[] }
+ *   GET  /__nwire/telemetry/runs/:id     disk single run { id, records: unknown[] }
+ *   GET  /__nwire/endpoints              list { endpoints: EndpointInfo[] }
+ *   POST /__nwire/endpoints/active       { name } → switch active HTTP front
+ *   *    /__nwire/run/*                  501 — supervisor belongs to standalone Studio
+ *   *    /__nwire/*                      501 — not yet implemented
+ *
+ * `/__nwire/project`, `/__nwire/source`, `/__nwire/projects/*` are the
+ * multi-project shell routes. They are out of scope for the dev-host context
+ * (the host always serves one project — the one it loaded) and return 501.
+ *
+ * The wire's own `/_nwire/*` surface (inspect, events) is NOT owned here. The
+ * dev-host routes it to `wireHandlers[0]` via the hardcoded prefix check in
+ * dev-host.ts (a known tech-debt; see the review findings). Once that prefix
+ * check is removed, the wire's handler self-dispatches via Connect-style `next`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { listTelemetryRuns, readTelemetryRun } from "@nwire/scan";
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function json(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(body));
+}
+/**
+ * Walk the mounts to find the first `RuntimeLike` available. Returns `undefined`
+ * when no forge runtime is mounted (transport-only endpoints without an app, or
+ * apps that haven't exposed `.runtime`).
+ */
+function findRuntime(mounts) {
+    for (const mount of mounts) {
+        for (const app of mount.apps) {
+            const runtime = app.runtime;
+            if (runtime !== null &&
+                runtime !== undefined &&
+                typeof runtime.onTelemetry === "function") {
+                return runtime;
+            }
+        }
+    }
+    return undefined;
+}
+// ── SSE helpers ───────────────────────────────────────────────────────────────
+const KEEPALIVE_MS = 25_000;
+/** Write a raw SSE event frame. Returns false when the socket has closed. */
+function sseWrite(res, event, data) {
+    try {
+        if (event !== null) {
+            res.write(`event: ${event}\ndata: ${data}\n\n`);
+        }
+        else {
+            res.write(`data: ${data}\n\n`);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Route handlers ───────────────────────────────────────────────────────────
+/**
+ * GET /__nwire/manifest.json
+ *
+ * Serves the disk-built `.nwire/manifest.json`. When a live runtime is
+ * present the static file already reflects the source tree as of the last
+ * scan; the intent for future increments is to fold live handler
+ * registrations from the runtime so the manifest stays accurate during HMR.
+ * Today the disk file is served verbatim (the same as standalone Studio) —
+ * the dev host calls `ensureScanFresh` on each (re)load so the file exists
+ * from the first request and tracks source edits across HMR.
+ *
+ * A `?force=true` query param is reserved for a future "rebuild" button
+ * trigger but is not acted on here (that requires spawning `nwire cache`).
+ */
+function handleManifest(req, res, cwd) {
+    const manifestPath = resolve(cwd, ".nwire", "manifest.json");
+    if (!existsSync(manifestPath)) {
+        json(res, 404, {
+            error: "manifest not built — run `nwire cache` or start with `nwire dev` which builds it automatically",
+        });
+        return;
+    }
+    let raw;
+    try {
+        raw = readFileSync(manifestPath, "utf8");
+    }
+    catch (err) {
+        json(res, 500, { error: err.message });
+        return;
+    }
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "application/json");
+    res.end(raw);
+}
+/**
+ * GET /__nwire/telemetry/live  (SSE)
+ *
+ * Runtime-direct: subscribes `runtime.onTelemetry` and streams each record
+ * as a plain SSE `data:` event. This replaces the file-tail approach used in
+ * standalone Studio — records arrive at zero-latency with no disk I/O.
+ *
+ * On open the server emits a `run` event carrying `null` (no discrete run ID
+ * in the in-process path — the runtime emits all records on one continuous
+ * stream). Studio's `useTelemetry` composable handles a null runId gracefully.
+ *
+ * When no runtime is available (transport-only endpoint), the stream stays
+ * open with keepalive comments — Studio will show an empty live view rather
+ * than an error.
+ */
+function handleTelemetryLive(req, res, mounts) {
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.setHeader("Connection", "keep-alive");
+    // Signal which run the client is tailing. In dev-host mode there is no
+    // discrete run file — the stream is continuous — so we emit null.
+    sseWrite(res, "run", JSON.stringify(null));
+    const runtime = findRuntime(mounts);
+    let unsubscribe;
+    if (runtime) {
+        unsubscribe = runtime.onTelemetry((record) => {
+            sseWrite(res, null, JSON.stringify(record));
+        });
+    }
+    const keepalive = setInterval(() => {
+        try {
+            res.write(": keepalive\n\n");
+        }
+        catch {
+            clearInterval(keepalive);
+        }
+    }, KEEPALIVE_MS);
+    // Don't let the keepalive timer hold the process open: an idle SSE
+    // connection must never be the reason Node (or a test runner) can't exit.
+    keepalive.unref();
+    req.on("close", () => {
+        unsubscribe?.();
+        clearInterval(keepalive);
+    });
+}
+/**
+ * GET /__nwire/telemetry/runs
+ * GET /__nwire/telemetry/runs/:id
+ *
+ * Disk-based telemetry history — same as standalone Studio. History records
+ * come from `.nwire/telemetry/*.jsonl` files written by the telemetry reporter.
+ * The dev-host writes these too (the reporter is installed per-app at boot).
+ *
+ * The sub-path after the `/runs` prefix determines whether this is a list
+ * or a single-run fetch. In the Vite middleware model the mount prefix is
+ * stripped before `req.url` is set; in the raw Node http.Server model used
+ * by dev-host, `req.url` still carries the full path. We parse against the
+ * full path to be safe.
+ */
+function handleTelemetryRuns(req, res, cwd) {
+    const url = req.url ?? "/";
+    const pathname = new URL(url, "http://x").pathname;
+    // Exact list: /__nwire/telemetry/runs
+    if (pathname === "/__nwire/telemetry/runs" || pathname === "/__nwire/telemetry/runs/") {
+        json(res, 200, { runs: listTelemetryRuns(cwd) });
+        return;
+    }
+    // Single run: /__nwire/telemetry/runs/:id
+    const runIdMatch = /^\/__nwire\/telemetry\/runs\/([^/]+)$/.exec(pathname);
+    if (runIdMatch) {
+        const runId = decodeURIComponent(runIdMatch[1]);
+        const file = resolve(cwd, ".nwire", "telemetry", `${runId}.jsonl`);
+        if (!existsSync(file)) {
+            json(res, 404, { error: "run not found", id: runId });
+            return;
+        }
+        const records = readTelemetryRun(cwd, runId);
+        json(res, 200, { id: runId, records });
+        return;
+    }
+    json(res, 404, { error: "not found" });
+}
+// ── Endpoint list + active-front switch ──────────────────────────────────────
+/**
+ * GET /__nwire/endpoints
+ *
+ * Returns the list of collected endpoint mounts with their HTTP status and
+ * which one is currently active. The payload shape is intentionally minimal —
+ * Studio uses it only for the picker and does not need adapter-level detail.
+ *
+ * For a single-endpoint project the list has one entry that is always active;
+ * the picker renders as a no-op label rather than a selectable list.
+ *
+ * Response: `{ endpoints: EndpointInfo[] }`
+ */
+function handleEndpointsList(_req, res, mounts, getActive) {
+    const activeName = getActive();
+    const endpoints = mounts.map((m) => ({
+        name: m.name,
+        active: m.name === activeName,
+        hasHttp: m.handlers.length > 0,
+    }));
+    json(res, 200, { endpoints });
+}
+/**
+ * POST /__nwire/endpoints/active
+ *
+ * Body: `{ name: string }` — the endpoint to make the active HTTP front.
+ * Response: `{ name }` on success, `{ error }` on failure.
+ *
+ * Reads the JSON body (the server never gets large bodies here so we buffer
+ * synchronously via the request `data` event — no streaming needed).
+ */
+function handleSetActiveEndpoint(req, res, setter) {
+    let body = "";
+    req.on("data", (chunk) => {
+        body += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    });
+    req.on("end", () => {
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            json(res, 400, { error: "Invalid JSON body" });
+            return;
+        }
+        const name = parsed !== null &&
+            typeof parsed === "object" &&
+            typeof parsed.name === "string"
+            ? parsed.name
+            : undefined;
+        if (!name) {
+            json(res, 400, { error: 'Body must be { "name": "<endpoint-name>" }' });
+            return;
+        }
+        try {
+            setter(name);
+            json(res, 200, { name });
+        }
+        catch (err) {
+            json(res, 404, { error: err.message });
+        }
+    });
+    req.on("error", () => {
+        json(res, 400, { error: "Failed to read request body" });
+    });
+}
+// ── Public factory ────────────────────────────────────────────────────────────
+/**
+ * Create the `/__nwire/*` request handler for the one-Vite dev host.
+ *
+ * Returns `true` when it handled the request (caller stops). `false` means
+ * the request was not for `/__nwire/*` and should fall through to Vite's
+ * middlewares.
+ *
+ * @example
+ * ```ts
+ * const studioApi = createStudioHostApi({ mounts, cwd: opts.cwd });
+ *
+ * const server = createHttpServer((req, res) => {
+ *   if (studioApi(req, res)) return;
+ *   vite.middlewares(req, res, () => { ... });
+ * });
+ * ```
+ */
+export function createStudioHostApi(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const getActive = opts.getActiveEndpointName ?? (() => undefined);
+    return function studioHostApi(req, res) {
+        const url = req.url ?? "/";
+        const pathname = new URL(url, "http://x").pathname;
+        if (!pathname.startsWith("/__nwire/"))
+            return false;
+        // ── manifest ───────────────────────────────────────────────────────────
+        if (req.method === "GET" && pathname === "/__nwire/manifest.json") {
+            handleManifest(req, res, cwd);
+            return true;
+        }
+        // ── telemetry live (SSE) ───────────────────────────────────────────────
+        if (req.method === "GET" && pathname === "/__nwire/telemetry/live") {
+            handleTelemetryLive(req, res, opts.mounts);
+            return true;
+        }
+        // ── telemetry runs (disk history) ──────────────────────────────────────
+        if (req.method === "GET" && pathname.startsWith("/__nwire/telemetry/runs")) {
+            handleTelemetryRuns(req, res, cwd);
+            return true;
+        }
+        // ── endpoints list ─────────────────────────────────────────────────────
+        if (req.method === "GET" && pathname === "/__nwire/endpoints") {
+            handleEndpointsList(req, res, opts.mounts, getActive);
+            return true;
+        }
+        // ── switch active HTTP front ───────────────────────────────────────────
+        if (req.method === "POST" && pathname === "/__nwire/endpoints/active") {
+            if (!opts.setActiveEndpoint) {
+                json(res, 501, {
+                    error: "Active endpoint switching is not configured for this host. " +
+                        "Pass `setActiveEndpoint` to createStudioHostApi to enable it.",
+                });
+                return true;
+            }
+            handleSetActiveEndpoint(req, res, opts.setActiveEndpoint);
+            return true;
+        }
+        // ── run/* — supervisor is standalone-Studio only ───────────────────────
+        if (pathname.startsWith("/__nwire/run/")) {
+            json(res, 501, {
+                error: "/__nwire/run/* is not available in the one-Vite dev host. " +
+                    "Process management runs in the standalone Studio (`nwire studio`).",
+            });
+            return true;
+        }
+        // ── everything else under /__nwire/* ──────────────────────────────────
+        json(res, 501, {
+            error: `Studio data API route not yet implemented in the one-Vite dev host: ${req.method} ${pathname}`,
+            hint: "Use `nwire studio` for the full Studio experience while this route is being ported.",
+        });
+        return true;
+    };
+}

package/dist/lib/studio-probe.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Singleton detection for `nwire studio`. Before spawning a second vite,
+ * probe the studio port: if a studio is already running there, register the
+ * current project with it and open the browser instead of starting a rival
+ * server. Keeps one studio owning the deterministic port (7777) so every
+ * later invocation attaches rather than scattering across 7778, 7779, …
+ *
+ * The decision logic is factored pure (`decideStudioProbe`) so it can be
+ * tested without a live server; the live HTTP is in `probeStudio` /
+ * `registerProject` and the platform opener in `openBrowser`.
+ */
+/** Default studio port — mirrors tool-studio's `vite.config.ts`. */
+export declare const DEFAULT_STUDIO_PORT = 7777;
+/** What a probe of `GET /__nwire/project` told us about the port. */
+export type ProbeResult = {
+    kind: "free";
+} | {
+    kind: "studio";
+    cwd: string;
+    name?: string;
+} | {
+    kind: "foreign";
+};
+/** What the studio command should do, given a probe result. */
+export type StudioDecision = {
+    action: "attach";
+    cwd: string;
+    name?: string;
+} | {
+    action: "spawn";
+} | {
+    action: "spawn-foreign";
+};
+/**
+ * Pure mapping from a probe result to the action the command takes. Kept
+ * free of I/O so it is exhaustively unit-testable.
+ */
+export declare function decideStudioProbe(probe: ProbeResult): StudioDecision;
+/**
+ * Interpret a `GET /__nwire/project` response body + status into a
+ * ProbeResult. A 200 with a JSON body carrying a `cwd` string is a studio;
+ * a 200 without that shape (or non-JSON) is a foreign service. Factored
+ * pure so the JSON-shape branch is testable without sockets.
+ */
+export declare function classifyProjectResponse(status: number, body: string): ProbeResult;
+/** Base URL for a studio on `127.0.0.1:<port>`. */
+export declare function studioBaseUrl(port: number): string;
+/**
+ * Live probe of the studio port. Returns `free` on any connection error or
+ * timeout (port unbound or unresponsive), otherwise classifies the answer.
+ */
+export declare function probeStudio(port: number, timeoutMs?: number): Promise<ProbeResult>;
+/** POST the current project's cwd to a running studio's register endpoint. */
+export declare function registerProject(port: number, cwd: string): Promise<boolean>;
+/** Open a URL in the platform's default browser. Best-effort, fire-and-forget. */
+export declare function openBrowser(url: string): void;
+/**
+ * Resolve the studio port for this invocation. Honors a `--port <n>` or
+ * `--port=<n>` flag in the raw args (vite's own flag), else the default.
+ */
+export declare function resolveStudioPort(rawArgs: readonly string[]): number;
+/** True when the raw args already pin a `--port` (so we shouldn't add one). */
+export declare function hasExplicitPort(rawArgs: readonly string[]): boolean;