@aexol/spectral 0.9.231 → 0.9.240

package/dist/cli.js

@@ -8,6 +8,8 @@
  *  - `spectral login`  → interactive auth flow (writes ~/.spectral/config.json)
  *  - `spectral logout` → deletes ~/.spectral/config.json
  *  - `spectral serve`  → start the Aexol relay WebSocket server (headless)
+ *  - `spectral desktop`→ start `serve` detached + open the Studio UI in the
+ *                        browser (the thin replacement for the old desktop app)
  *  - `spectral bind`   → link directory to an Aexol Studio project
  *  - `spectral unbind` → remove Aexol Studio project binding
  *  - `spectral --version` / `--help` → branded short-circuits, no auth needed.
@@ -16,8 +18,7 @@
 import { getVersion } from "./version.js";
 // ---- Read our own version ----------------------------------------------------
 // Centralized in src/version.ts so the standalone Bun binary, the npm
-// install, and the electron app all resolve the same real version instead of
-// silently falling back to "0.0.0".
+// install all resolve the same real version instead of falling back to "0.0.0".
 const VERSION = getVersion();
 const TAGLINE = "Coding agent that never sleeps";
 // ---- Branded helpers ---------------------------------------------------------
@@ -33,6 +34,7 @@ function printHeader() {
         "  spectral login         Interactive authentication (team API key or OAuth)",
         "  spectral logout        Remove stored Aexol credentials",
         "  spectral serve         Connect this machine to the Aexol relay backend",
+        "  spectral desktop       Start the agent in the background and open the UI",
         "  spectral bind          Link this directory to an Aexol Studio project",
         "  spectral unbind        Remove the Aexol Studio project binding",
         "  spectral update        Check for and install the latest Spectral version",
@@ -40,8 +42,9 @@ function printHeader() {
         "  spectral --version     Print version and exit",
         "  spectral --help        Print this help and exit",
         "",
-        "TUI/interactive mode has been removed. Use `spectral serve` and connect",
-        "via the Aexol Studio web frontend or relay WebSocket.",
+        "TUI/interactive mode has been removed. Use `spectral desktop` to work in",
+        "the Aexol Studio web frontend, or `spectral serve` to only connect this",
+        "machine to the relay backend.",
         "",
     ].join("\n"));
 }
@@ -99,6 +102,17 @@ async function main() {
         await runServeCli(args.slice(1));
         return;
     }
+    if (first === "desktop") {
+        const { runDesktop } = await import("./commands/desktop.js");
+        // Thin wrapper: it spawns a detached `spectral serve`, waits for its
+        // readiness marker, opens the browser, then exits. The exit code tells the
+        // shell whether the agent came up.
+        // `exitCode` (not `process.exit`) so buffered stdout is flushed and any
+        // pending cleanup still runs — the wrapper has nothing left open, but a
+        // hard exit here would truncate the message on a slow terminal.
+        process.exitCode = await runDesktop(args.slice(1));
+        return;
+    }
     if (first === "bind") {
         const { runBind } = await import("./commands/bind.js");
         await runBind(args.slice(1));

package/dist/commands/desktop.d.ts

@@ -0,0 +1,167 @@
+/**
+ * `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 { type SpectralConfig } from "../config.js";
+import { type OpenBrowserResult } from "../utils/open-browser.js";
+import { type ServeReadyResult, type ServeGenealogy } from "../utils/serve-state.js";
+/** Where the Studio agent UI lives. */
+export declare const DEFAULT_LANDING_URL = "https://aexol.ai/agent";
+/** How long to wait for the daemon's readiness signal. */
+export declare const DEFAULT_READY_TIMEOUT_MS = 15000;
+/** Grace period between SIGTERM and SIGKILL in `desktop stop`. */
+export declare const DEFAULT_STOP_TIMEOUT_MS = 10000;
+/**
+ * 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 declare const SERVE_PID_CLAIM_ENV = "SPECTRAL_SERVE_PID_CLAIM";
+export declare function getLandingUrl(env?: NodeJS.ProcessEnv): string;
+/** Render a grace window the way it is actually configured (10s, 250ms). */
+export declare function formatGraceMs(ms: number): string;
+export interface ServeSpawnPlan {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    logFile: string;
+}
+interface ResolveCommandInput {
+    execPath?: string;
+    execArgv?: readonly string[];
+    argv1?: string;
+    standalone?: boolean;
+    /** Entry points to try, in order (already-resolved absolute paths). */
+    candidates?: string[];
+    exists?: (path: string) => boolean;
+}
+/**
+ * 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 declare function resolveServeCommand(input?: ResolveCommandInput): {
+    command: string;
+    args: string[];
+};
+/** Compose the full plan for spawning the daemon. */
+export declare function planServeSpawn(env?: NodeJS.ProcessEnv, input?: ResolveCommandInput): ServeSpawnPlan;
+/**
+ * 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 declare function spawnExpectsReExec(plan: ServeSpawnPlan): boolean;
+/**
+ * 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 declare function spawnDetachedServe(plan: ServeSpawnPlan): number | null;
+export interface DesktopDeps {
+    env?: NodeJS.ProcessEnv;
+    spawnServe?: (plan: ServeSpawnPlan) => number | null;
+    waitForReady?: (opts: {
+        pid: number;
+        logFile: string;
+        logOffset: number;
+        /** Timestamp captured before the spawn, for ready-signal freshness. */
+        sinceMs: number;
+        /** True when the child re-execs, so its own exit proves nothing. */
+        expectReExec: boolean;
+        timeoutMs: number;
+    }) => Promise<ServeReadyResult>;
+    openUrl?: (url: string) => Promise<OpenBrowserResult>;
+    /** Interactive `spectral login`. */
+    runLogin?: () => Promise<void>;
+    readCfg?: () => Promise<SpectralConfig | null>;
+    signal?: (pid: number, signal: NodeJS.Signals) => void;
+    alive?: (pid: number) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+    /** Override the SIGTERM→SIGKILL grace window (tests, exotic supervisors). */
+    stopGraceMs?: number;
+    /**
+     * Injectable genealogy verdict for the serve.pid hand-off confirmation. The
+     * real probe walks `ps -o ppid=` and can transiently fail under parallel
+     * test load, so tests pin the verdict to keep the
+     * `daemon`/`foreign`/`unknown` classification deterministic.
+     */
+    genealogy?: (pid: number, ancestors: number[]) => ServeGenealogy;
+    planInput?: ResolveCommandInput;
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+    isInteractive?: () => boolean;
+}
+export interface TerminateAgentOptions {
+    /** Pid to stop — always the one from the pid file, never a stale handle. */
+    pid: number;
+    /** SIGTERM grace window before SIGKILL. */
+    graceMs: number;
+    alive: (pid: number) => boolean;
+    signal: (pid: number, signal: NodeJS.Signals) => void;
+    sleep: (ms: number) => Promise<void>;
+    out?: (text: string) => void;
+    /** Poll interval while waiting for the daemon to drain. */
+    pollMs?: number;
+    /** How long to wait after SIGKILL before giving up. */
+    killWaitMs?: number;
+}
+export type TerminateAgentOutcome = "stopped" | "killed" | "failed";
+/**
+ * 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 declare function terminateAgentPid(opts: TerminateAgentOptions): Promise<TerminateAgentOutcome>;
+/**
+ * `spectral desktop [start|status|stop]`
+ *
+ * @returns process exit code; `cli.ts` assigns it to `process.exitCode`.
+ */
+export declare function runDesktop(args?: string[], deps?: DesktopDeps): Promise<number>;
+export {};
+//# sourceMappingURL=desktop.d.ts.map

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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"}