@aexol/spectral 0.9.234 → 0.9.241

package/dist/commands/desktop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop.d.ts","sourceRoot":"","sources":["../../src/commands/desktop.ts"],"names":[],"mappings":"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"}

package/dist/commands/desktop.js

@@ -0,0 +1,540 @@
+/**
+ * `spectral desktop` — the thin, headless replacement for the Electron shell.
+ *
+ * What the Electron app actually contributed was four things, all reproduced
+ * here without a bundled Chromium:
+ *
+ *   1. single-instance guarantee      → `~/.spectral/serve.pid` + liveness check
+ *   1. single-instance guarantee      → `~/.spectral/serve.pid`, claimed
+ *                                       atomically (`O_EXCL`) before the spawn
+ *   2. start the local relay daemon   → detached `spectral serve`, unref'd,
+ *                                       stdout+stderr appended to serve.log
+ *   3. "wait until it is really up"   → the `SPECTRAL_SERVE_READY` stdout marker
+ *                                       and `serve-ready.json` (see
+ *                                       src/utils/serve-state.ts), replacing the
+ *                                       old "assume ready after 3 s" heuristic
+ *   4. show the UI                    → open the system browser at
+ *                                       https://aexol.ai/agent
+ *                                       (override: SPECTRAL_LANDING_URL)
+ *
+ * The PATH augmentation the app performed for its child process now happens in
+ * `augmentPath()` (src/utils/augment-path.ts) and is applied to the spawned
+ * daemon, so MCP servers launched via `npx` keep working.
+ *
+ * What is deliberately NOT reproduced (see the removal notes): the splash
+ * window, in-app auto-update (use `spectral update`), the native app menu, and
+ * the JWT-via-IPC login bridge — authentication goes through the existing
+ * `spectral login` browser flow, which already writes `userJwt` to
+ * `~/.spectral/config.json`.
+ *
+ * Exit codes: 0 success / already running, 1 failure, 3 stopped-state for
+ * `status` when the daemon is not running.
+ */
+import { closeSync, fchmodSync, existsSync, mkdirSync, openSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import pc from "picocolors";
+import { readConfig } from "../config.js";
+import { getVersion } from "../version.js";
+import { augmentPath, getPathEnvKey } from "../utils/augment-path.js";
+import { openBrowser } from "../utils/open-browser.js";
+import { isStandaloneBinary } from "../utils/standalone.js";
+import { claimServePidFile, clearServeState, confirmServePidChild, fileSizeOf, getLiveServePid, getServeLogFile, getServePidFile, isProcessAlive, readServePidFile, readServeReadyFile, releaseServePidClaim, rotateServeLogFile, DEFAULT_SERVE_LOG_MAX_BYTES, waitForServeReady, writeServePid, } from "../utils/serve-state.js";
+/** Where the Studio agent UI lives. */
+export const DEFAULT_LANDING_URL = "https://aexol.ai/agent";
+/** How long to wait for the daemon's readiness signal. */
+export const DEFAULT_READY_TIMEOUT_MS = 15_000;
+/** Grace period between SIGTERM and SIGKILL in `desktop stop`. */
+export const DEFAULT_STOP_TIMEOUT_MS = 10_000;
+/**
+ * Set in the daemon's env to the wrapper's own pid. The daemon sees the
+ * placeholder we left in `serve.pid` and must not read it as "another serve is
+ * running" — it is the claim of the process that just launched it.
+ */
+export const SERVE_PID_CLAIM_ENV = "SPECTRAL_SERVE_PID_CLAIM";
+export function getLandingUrl(env = process.env) {
+    const override = env.SPECTRAL_LANDING_URL?.trim();
+    return override && override.length > 0 ? override : DEFAULT_LANDING_URL;
+}
+function readyTimeoutMs(env = process.env) {
+    const raw = env.SPECTRAL_DESKTOP_READY_TIMEOUT_MS;
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_READY_TIMEOUT_MS;
+}
+/** Grace period the daemon gets to drain in-flight turns before SIGKILL. */
+function stopGraceMs(env = process.env) {
+    const raw = env.SPECTRAL_DESKTOP_STOP_TIMEOUT_MS;
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_STOP_TIMEOUT_MS;
+}
+/**
+ * Serve-log size that triggers a rotation at start. Overridable so the rotation
+ * path is testable without writing 10 MB.
+ */
+function logMaxBytes(env = process.env) {
+    const raw = env.SPECTRAL_DESKTOP_LOG_MAX_BYTES;
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_SERVE_LOG_MAX_BYTES;
+}
+/** Render a grace window the way it is actually configured (10s, 250ms). */
+export function formatGraceMs(ms) {
+    return ms >= 1_000 && ms % 1_000 === 0 ? `${ms / 1_000}s` : `${ms}ms`;
+}
+/**
+ * Decide how to launch a detached `spectral serve`.
+ *
+ * Three launch shapes must all work:
+ *   - standalone Bun binary  → exec the binary itself with `serve`
+ *   - npm install (`spectral` bin → dist/cli.js) → `node <cli.js> serve`
+ *   - `npm run dev` (tsx src/cli.ts) → re-run the very entry the user invoked,
+ *     with `process.execArgv` so the tsx loader is carried over
+ *
+ * @returns the spawn plan's command/args portion. Falls back to whatever
+ *   `spectral` is on PATH when no entry point can be identified.
+ */
+export function resolveServeCommand(input = {}) {
+    const execPath = input.execPath ?? process.execPath;
+    const execArgv = input.execArgv ?? process.execArgv;
+    const argv1 = input.argv1 ?? process.argv[1];
+    const standalone = input.standalone ?? isStandaloneBinary();
+    const exists = input.exists ?? ((p) => existsSync(p));
+    if (standalone)
+        return { command: execPath, args: ["serve"] };
+    const candidates = (input.candidates ?? [argv1, ...defaultEntryCandidates()]).filter((candidate) => typeof candidate === "string" && candidate.length > 0);
+    const entry = candidates.find((candidate) => exists(candidate));
+    if (entry)
+        return { command: execPath, args: [...execArgv, entry, "serve"] };
+    return { command: "spectral", args: ["serve"] };
+}
+/**
+ * Entry points relative to this module, covering both the compiled (`dist/`)
+ * and the source (`src/`, via tsx) layouts.
+ */
+function defaultEntryCandidates() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return [
+        join(here, "..", "cli.js"), // dist/commands/desktop.js -> dist/cli.js
+        join(here, "..", "..", "src", "cli.ts"), // src/commands -> src/cli.ts (dev)
+        join(here, "..", "..", "dist", "cli.js"), // src/commands -> dist/cli.js
+    ];
+}
+/** Compose the full plan for spawning the daemon. */
+export function planServeSpawn(env = process.env, input = {}) {
+    const { command, args } = resolveServeCommand(input);
+    const pathKey = getPathEnvKey(env);
+    return {
+        command,
+        args,
+        cwd: homedir(),
+        // The env we were given is the source of truth — `augmentPath(undefined)`
+        // would silently fall back to *this* process's PATH and leak it into a
+        // caller-supplied env.
+        env: {
+            ...env,
+            [pathKey]: augmentPath(env[pathKey] ?? ""),
+            [SERVE_PID_CLAIM_ENV]: String(process.pid),
+        },
+        logFile: getServeLogFile(env),
+    };
+}
+/**
+ * Will this spawn re-exec into the daemon instead of becoming it directly?
+ *
+ * Matters for readiness: a standalone binary and `node dist/cli.js serve` are
+ * the daemon, so their exit is a hard failure we can report instantly. Under
+ * `npm run dev` (`tsx src/cli.ts`) the child is a loader wrapper that execs
+ * something else — its death tells us nothing, and only the ready signal or the
+ * timeout may decide.
+ */
+export function spawnExpectsReExec(plan) {
+    if (isStandaloneBinary())
+        return false;
+    const command = basename(plan.command).replace(/\.exe$/i, "");
+    if (command === "tsx" || command === "ts-node" || command === "oxnode")
+        return true;
+    return plan.args.some((arg) => /(?:^|[/\\.-])(?:tsx|ts-node)(?:$|[/\\._])/.test(arg) || arg.startsWith("--loader"));
+}
+/**
+ * Launch the daemon detached from this terminal so it survives the wrapper
+ * exiting (that is the whole point: close the shell, the agent stays up).
+ * Returns the child pid, or null when the spawn itself failed.
+ */
+export function spawnDetachedServe(plan) {
+    try {
+        mkdirSync(dirname(plan.logFile), { recursive: true, mode: 0o700 });
+    }
+    catch {
+        // The log dir may already exist or be read-only; spawning with an
+        // unwritable log is still worth trying.
+    }
+    let fd;
+    try {
+        // 0600: the daemon log carries machine ids and relay diagnostics, and this
+        // file is created by whoever happened to start the agent first. The mode
+        // argument is umask-masked, so chmod the fresh descriptor as well.
+        fd = openSync(plan.logFile, "a", 0o600);
+        try {
+            fchmodSync(fd, 0o600);
+        }
+        catch {
+            // filesystem without POSIX modes
+        }
+    }
+    catch {
+        fd = undefined;
+    }
+    try {
+        const child = spawn(plan.command, plan.args, {
+            cwd: plan.cwd,
+            // detached: new process group, so `desktop stop` can signal the daemon
+            // without touching this CLI's own group, and Ctrl-C in the wrapper's
+            // terminal does not take the agent down.
+            detached: true,
+            stdio: [
+                "ignore",
+                fd ?? "ignore",
+                // Same fd for stdout and stderr, as the daemon interleaves them. When
+                // the log could not be opened, drop both rather than leaking the
+                // daemon's chatter into the wrapper's terminal (which we are about to
+                // exit) — the readiness fallback file still works.
+                fd ?? "ignore",
+            ],
+            env: plan.env,
+        });
+        child.unref();
+        return child.pid ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        // The child dup'd the descriptor at spawn time; our copy is dead weight.
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function tailLines(tail, max = 12) {
+    if (!tail)
+        return "";
+    return tail
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .slice(-max)
+        .join("\n");
+}
+/**
+ * SIGTERM → wait out the drain → SIGKILL. Shared by `desktop stop` and by the
+ * start path's "it never came up, do not leave it half-started" branch — the
+ * old start path fired a bare SIGTERM and walked away, which left a detached
+ * daemon that ignored TERM (or won the race) running behind a failed command.
+ *
+ * The wait is bounded by a poll COUNT rather than a wall-clock deadline, so a
+ * caller with a synchronous `sleep` (tests) is both fast and deterministic.
+ */
+export async function terminateAgentPid(opts) {
+    const out = opts.out ?? (() => { });
+    const pollMs = opts.pollMs ?? 100;
+    const killWaitMs = opts.killWaitMs ?? 2_000;
+    try {
+        opts.signal(opts.pid, "SIGTERM");
+    }
+    catch (err) {
+        // ESRCH: it exited between the liveness check and the signal.
+        const code = err.code;
+        if (code !== "ESRCH")
+            throw err;
+    }
+    // `serve` drains in-flight turns on SIGTERM, so wait the grace window out
+    // before escalating. Then SIGKILL — bounded, never a hang.
+    for (let i = 0; i < Math.max(1, Math.ceil(opts.graceMs / pollMs)) && opts.alive(opts.pid); i++) {
+        await opts.sleep(pollMs);
+    }
+    if (!opts.alive(opts.pid))
+        return "stopped";
+    out(pc.yellow(`  Agent did not exit within ${formatGraceMs(opts.graceMs)}; forcing SIGKILL.\n`));
+    try {
+        opts.signal(opts.pid, "SIGKILL");
+    }
+    catch {
+        // racing exit — fine
+    }
+    for (let i = 0; i < Math.max(1, Math.ceil(killWaitMs / pollMs)) && opts.alive(opts.pid); i++) {
+        await opts.sleep(pollMs);
+    }
+    return opts.alive(opts.pid) ? "failed" : "killed";
+}
+/**
+ * Which pid may this wrapper signal? Only the one recorded in the pid file:
+ * the spawn handle names the loader wrapper under `tsx`, and once the daemon
+ * has claimed the file the handle may refer to a process that is already gone.
+ *
+ * `placeholderPid` is what we wrote ourselves before spawning, so it counts as
+ * ours and falls back to the child handle. A *missing* entry means somebody
+ * else cleared the state — then nothing is signalled, rather than a guessed pid.
+ */
+function stopTargetPid(childPid, placeholderPid) {
+    const recorded = readServePidFile();
+    if (recorded === null)
+        return null;
+    return recorded === placeholderPid ? childPid : recorded;
+}
+// ---------------------------------------------------------------------------
+// Subcommands
+// ---------------------------------------------------------------------------
+async function startDesktop(deps) {
+    const out = deps.out ?? ((t) => process.stdout.write(t));
+    const err = deps.err ?? ((t) => process.stderr.write(t));
+    const env = deps.env ?? process.env;
+    const landingUrl = getLandingUrl(env);
+    const logFile = getServeLogFile(env);
+    const alive = deps.alive ?? isProcessAlive;
+    const readCfg = deps.readCfg ?? readConfig;
+    /** What both single-instance paths print: the agent is up, open the UI. */
+    const reportAlreadyRunning = async (pid) => {
+        out(pc.yellow(`Spectral agent is already running (pid ${pid}).\n`));
+        const opened = await (deps.openUrl ?? openBrowser)(landingUrl);
+        out(opened.opened ? `Opened ${landingUrl}\n` : `Agent: ${landingUrl}\n`);
+        out(`Stop it with ${pc.bold("spectral desktop stop")}.\n`);
+        return 0;
+    };
+    // Single instance. The pid file is only trusted after a liveness check, so a
+    // crashed daemon does not block a restart.
+    const running = getLiveServePid();
+    if (running !== null) {
+        return reportAlreadyRunning(running);
+    }
+    // Auth gate: the web UI needs a user JWT, and `serve` needs credentials too.
+    const cfg = await readCfg();
+    if (!cfg?.userJwt) {
+        const interactive = deps.isInteractive ?? (() => Boolean(process.stdin.isTTY));
+        if (!interactive()) {
+            err(pc.red("✗ Not signed in for Aexol Studio.\n"));
+            err(`  Run ${pc.bold("spectral login")} in a terminal, then retry.\n`);
+            return 1;
+        }
+        out(pc.dim("Not signed in for Aexol Studio — opening the sign-in flow…\n"));
+        const runLogin = deps.runLogin ??
+            (async () => {
+                const { runLogin: login } = await import("./login.js");
+                await login();
+            });
+        await runLogin();
+        const afterLogin = await readCfg();
+        if (!afterLogin?.userJwt) {
+            err(pc.red("✗ Sign-in finished without a Studio token, so the desktop UI cannot start.\n"));
+            err(`  Run ${pc.bold("spectral login")} and choose the OAuth option.\n`);
+            return 1;
+        }
+    }
+    // Claim the pid file NOW, before spawning. The liveness check above is only
+    // an optimisation: two invocations can both see "not running" and then both
+    // spawn, which is the race `open(O_EXCL)` closes. The claim records this
+    // wrapper's pid as a placeholder, so a late racer sees a live holder.
+    const claim = claimServePidFile();
+    if (claim.status === "failed") {
+        err(pc.red(`✗ Could not claim ${getServePidFile()}: ${claim.error}\n`));
+        return 1;
+    }
+    if (claim.status === "busy") {
+        return reportAlreadyRunning(claim.pid);
+    }
+    // Keep the daemon log bounded before anything is appended to it, and only
+    // THEN snapshot the offset — after a rotation the fresh log starts at byte 0,
+    // and the readiness marker of a previous run must never satisfy this one.
+    const maxLogBytes = logMaxBytes(env);
+    if (rotateServeLogFile(logFile, maxLogBytes)) {
+        out(pc.dim(`Rotated ${logFile} to ${logFile}.old (larger than ${maxLogBytes} bytes)\n`));
+    }
+    const logOffset = fileSizeOf(logFile);
+    const plan = planServeSpawn(env, deps.planInput);
+    const spawnServe = deps.spawnServe ?? spawnDetachedServe;
+    // Captured before the spawn: a ready file older than this is from an earlier
+    // run and must not be accepted as this one's signal.
+    const spawnStartedAt = Date.now();
+    const pid = spawnServe(plan);
+    if (pid === null || pid === undefined) {
+        err(pc.red(`✗ Could not start the Spectral agent (${plan.command}).\n`));
+        err(`  Log: ${logFile}\n`);
+        releaseServePidClaim(claim.placeholderPid);
+        return 1;
+    }
+    // Hand the claim over: the pid file must end up naming the daemon, not us.
+    const ownership = confirmServePidChild(pid, claim.placeholderPid, {
+        genealogy: deps.genealogy,
+    });
+    // A foreign or unverifiable holder both mean "not provably ours": warn the
+    // user and leave the recorded state untouched instead of hijacking it.
+    if (ownership.status === "foreign" || ownership.status === "unknown") {
+        const held = ownership.pid === null
+            ? `${getServePidFile()} is held by a process this command could not verify`
+            : ownership.status === "foreign"
+                ? `${getServePidFile()} is held by pid ${ownership.pid}, which this command did not start`
+                : `${getServePidFile()} is held by pid ${ownership.pid}, which could not be verified as ours`;
+        err(pc.yellow(`⚠ ${held}; leaving its state alone.\n`));
+    }
+    const waitForReady = deps.waitForReady ?? ((o) => waitForServeReady(o));
+    const result = await waitForReady({
+        pid,
+        logFile,
+        logOffset,
+        sinceMs: spawnStartedAt,
+        expectReExec: spawnExpectsReExec(plan),
+        timeoutMs: readyTimeoutMs(env),
+    });
+    if (!result.ok) {
+        const why = result.reason === "process-exited"
+            ? "the agent process exited during startup"
+            : `no readiness signal within ${Math.round((result.waitedMs ?? 0) / 1000)}s`;
+        err(pc.red(`✗ Spectral agent did not become ready: ${why}.\n`));
+        err(`  Log: ${logFile}\n`);
+        const tail = tailLines(result.logTail);
+        if (tail)
+            err(pc.dim(`${tail}\n`));
+        // A half-started detached daemon that may still connect later is worse than
+        // a restart, so stop it the same way `desktop stop` would — SIGTERM, grace,
+        // then SIGKILL — but only when the pid file provably names a process WE
+        // launched (`child` or `daemon`). A foreign or unverifiable holder must
+        // never be signalled, so its state is released untouched instead.
+        const target = ownership.status === "child" || ownership.status === "daemon"
+            ? stopTargetPid(pid, claim.placeholderPid)
+            : null;
+        if (target !== null && alive(target)) {
+            await terminateAgentPid({
+                pid: target,
+                graceMs: deps.stopGraceMs ?? stopGraceMs(env),
+                alive,
+                signal: deps.signal ?? ((p, s) => process.kill(p, s)),
+                sleep: deps.sleep ?? defaultSleep,
+                out,
+            });
+        }
+        releaseServePidClaim(claim.placeholderPid, pid);
+        return 1;
+    }
+    // The daemon writes its own pid file; backfill if it could not (read-only
+    // config dir races) so `status`/`stop` always have something to work with.
+    if (getLiveServePid() === null)
+        writeServePid(result.info?.pid ?? pid);
+    const opened = await (deps.openUrl ?? openBrowser)(landingUrl);
+    out(pc.green(`✓ Spectral agent running (pid ${result.info?.pid ?? pid}).\n`));
+    out(opened.opened
+        ? `  Opened ${pc.cyan(landingUrl)} in your browser.\n`
+        : `  Open ${pc.cyan(landingUrl)} in your browser (auto-open failed: ${opened.error ?? "no browser"}).\n`);
+    out(`  Logs: ${logFile}\n`);
+    out(`  Stop with ${pc.bold("spectral desktop stop")}, check with ${pc.bold("spectral desktop status")}.\n`);
+    return 0;
+}
+async function statusDesktop(deps) {
+    const out = deps.out ?? ((t) => process.stdout.write(t));
+    const env = deps.env ?? process.env;
+    const landingUrl = getLandingUrl(env);
+    const pid = getLiveServePid();
+    if (pid === null) {
+        out("Spectral agent: not running\n");
+        out(`  Start with ${pc.bold("spectral desktop")}.\n`);
+        return 3;
+    }
+    const ready = readServeReadyFile();
+    out(pc.green(`Spectral agent: running (pid ${pid})`) + "\n");
+    if (ready) {
+        out(`  Version: ${ready.version}\n`);
+        out(`  Ready since: ${new Date(ready.ts).toISOString()}\n`);
+        out(`  CLI version now: ${getVersion()}\n`);
+    }
+    else {
+        out(`  Process is alive, but no readiness signal was recorded (relay may not be connected).\n`);
+    }
+    out(`  Agent UI: ${landingUrl}\n`);
+    out(`  Logs: ${getServeLogFile(env)}\n`);
+    return 0;
+}
+async function stopDesktop(deps) {
+    const out = deps.out ?? ((t) => process.stdout.write(t));
+    const err = deps.err ?? ((t) => process.stderr.write(t));
+    const alive = deps.alive ?? isProcessAlive;
+    const signal = deps.signal ?? ((p, s) => process.kill(p, s));
+    const sleep = deps.sleep ?? defaultSleep;
+    const graceMs = deps.stopGraceMs ?? stopGraceMs(deps.env ?? process.env);
+    const pid = readServePidFile();
+    if (pid === null) {
+        clearServeState();
+        out("Spectral agent: not running\n");
+        return 0;
+    }
+    if (!alive(pid)) {
+        clearServeState();
+        out(`Spectral agent was not running (stale pid ${pid}); cleaned up.\n`);
+        return 0;
+    }
+    out(`Stopping Spectral agent (pid ${pid})…\n`);
+    // Same escalation the start path uses when the daemon never came up. The
+    // target is always the pid read back from the pid file — never a pid cached
+    // from an earlier lookup, which could already have been recycled.
+    const outcome = await terminateAgentPid({
+        pid: readServePidFile() ?? pid,
+        graceMs,
+        alive,
+        signal,
+        sleep,
+        out,
+    });
+    if (outcome === "failed") {
+        err(pc.red(`✗ Could not stop pid ${pid}; it is still alive. Kill it manually.\n`));
+        return 1;
+    }
+    clearServeState();
+    out(pc.green("✓ Spectral agent stopped.\n"));
+    return 0;
+}
+function printUsage(out) {
+    out([
+        "spectral desktop — run the Spectral agent and open the Studio UI",
+        "",
+        "  spectral desktop           Start the agent (or reuse a running one) and open the UI",
+        "  spectral desktop status    Report whether the agent is running",
+        `  spectral desktop stop      Stop the agent (SIGTERM, then SIGKILL after ${formatGraceMs(DEFAULT_STOP_TIMEOUT_MS)})`,
+        "",
+        "Environment:",
+        "  SPECTRAL_LANDING_URL                  UI to open (default https://aexol.ai/agent)",
+        "  SPECTRAL_SERVE_LOG_PATH               Daemon log (default ~/.spectral/serve.log)",
+        "  SPECTRAL_DESKTOP_READY_TIMEOUT_MS     Readiness timeout (default 15000)",
+        `  SPECTRAL_DESKTOP_STOP_TIMEOUT_MS      SIGTERM grace before SIGKILL (default ${DEFAULT_STOP_TIMEOUT_MS})`,
+        "",
+    ].join("\n"));
+}
+/**
+ * `spectral desktop [start|status|stop]`
+ *
+ * @returns process exit code; `cli.ts` assigns it to `process.exitCode`.
+ */
+export async function runDesktop(args = [], deps = {}) {
+    const out = deps.out ?? ((t) => process.stdout.write(t));
+    const sub = args[0];
+    switch (sub) {
+        case undefined:
+        case "start":
+            return startDesktop(deps);
+        case "status":
+            return statusDesktop(deps);
+        case "stop":
+            return stopDesktop(deps);
+        case "--help":
+        case "-h":
+            printUsage(out);
+            return 0;
+        default:
+            out(`spectral desktop: unknown subcommand "${sub}".\n`);
+            printUsage(out);
+            return 1;
+    }
+}

package/dist/commands/serve.d.ts

@@ -88,6 +88,13 @@ export interface RunServeOptions {
     fetchImpl?: typeof fetch;
     /** Override the WebSocket constructor (tests, RelayClient). */
     webSocketImpl?: ConstructorParameters<typeof RelayClient>[0]["webSocketImpl"];
+    /**
+     * Write the `serve.pid` / `serve-ready.json` bookkeeping files and print the
+     * `SPECTRAL_SERVE_READY` stdout marker once the relay socket opens. Defaults
+     * to true — it is the readiness contract `spectral desktop` waits on.
+     * Tests pass false to keep a temp config dir clean.
+     */
+    serveState?: boolean;
 }
 export interface RunServeHandle {
     /** Open store. Exposed for tests. */
@@ -104,7 +111,8 @@ export interface RunServeHandle {
 export declare function runServe(opts?: RunServeOptions): Promise<RunServeHandle>;
 /**
  * CLI entry point used by `cli.ts`. Surfaces the deprecation warning for
- * `--port`/`SPECTRAL_PORT` once, then defers to `runServe`.
+ * `--port`/`SPECTRAL_PORT` once, augments PATH for child processes, then defers
+ * to `runServe`.
  */
 export declare function runServeCli(rawArgs: string[]): Promise<RunServeHandle>;
 //# sourceMappingURL=serve.d.ts.map

package/dist/commands/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAwBH,OAAO,EAAE,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AAclE,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGnE,OAAO,EAAmB,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAarE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAazD;AAED,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA6B9D;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,wDAAwD;IACxD,OAAO,EAAE,oBAAoB,CAAC;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,WAAW,CAAC;IACnB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CA8lBlF;AAmFD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAc5E"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAwBH,OAAO,EAAE,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AAclE,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGnE,OAAO,EAAmB,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAsBrE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAazD;AAED,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA6B9D;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;IAC9E;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,wDAAwD;IACxD,OAAO,EAAE,oBAAoB,CAAC;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,WAAW,CAAC;IACnB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAoqBlF;AAmFD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAsB5E"}