@vendoai/vendo 0.4.0

package/dist/cli/doctor-live.js

@@ -0,0 +1,169 @@
+import { spawn } from "node:child_process";
+import { describeDevCredential, resolveDevCredential, } from "../dev-creds/resolve.js";
+import { isVendoKey } from "./cloud/client.js";
+import { detectPackageManager } from "./shared.js";
+const DOCTOR_PROBE_PROMPT = "This is a Vendo doctor health check. Reply in one short sentence confirming you can respond.";
+/** POST one seeded turn to the live wire and stream the reply — mirrors the
+ *  init finale's route (`POST {base}/threads`, UI-message SSE frames). Exit 0
+ *  means a user would have gotten an answer: a non-empty text reply arrived. */
+export async function liveModelTurn(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const env = options.env ?? process.env;
+    const resolve = options.resolveCredential ?? resolveDevCredential;
+    const credential = await resolve({ env });
+    const rung = credential.rung;
+    const label = describeDevCredential(credential);
+    const started = Date.now();
+    const done = (partial) => ({
+        attempted: true,
+        rung,
+        credential: label,
+        elapsedMs: Date.now() - started,
+        ...partial,
+    });
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 90_000);
+    try {
+        const response = await fetchImpl(`${options.base}/threads`, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "text/event-stream" },
+            body: JSON.stringify({
+                message: {
+                    id: `msg_doctor_${Date.now()}`,
+                    role: "user",
+                    parts: [{ type: "text", text: DOCTOR_PROBE_PROMPT }],
+                },
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok || response.body === null) {
+            return done({ ok: false, error: `the wire returned ${response.status} with no stream` });
+        }
+        const reply = await readTurnStream(response.body, options.onDelta);
+        if (reply.error !== undefined)
+            return done({ ok: false, error: reply.error, reply: reply.text || undefined });
+        if (reply.text.trim().length === 0)
+            return done({ ok: false, error: "no reply text arrived" });
+        return done({ ok: true, reply: reply.text });
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? (error.name === "AbortError" ? "the turn timed out" : error.message)
+            : "unknown error";
+        return done({ ok: false, error: message });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function readTurnStream(body, onDelta) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let text = "";
+    let error;
+    for (;;) {
+        const chunk = await reader.read();
+        if (chunk.done)
+            break;
+        buffer += decoder.decode(chunk.value, { stream: true });
+        for (;;) {
+            const frameEnd = buffer.indexOf("\n\n");
+            if (frameEnd === -1)
+                break;
+            const frame = buffer.slice(0, frameEnd);
+            buffer = buffer.slice(frameEnd + 2);
+            if (!frame.startsWith("data: ") || frame === "data: [DONE]")
+                continue;
+            try {
+                const part = JSON.parse(frame.slice("data: ".length));
+                if (part.type === "text-delta" && typeof part.delta === "string") {
+                    text += part.delta;
+                    onDelta?.(part.delta);
+                }
+                else if (part.type === "error") {
+                    error = "the turn returned an error frame";
+                }
+            }
+            catch {
+                // skip malformed frame
+            }
+        }
+    }
+    return error === undefined ? { text } : { text, error };
+}
+/* ------------------------------------------------------------------------ *
+ * VENDO_API_KEY local shape check + what Cloud unlocks.
+ * ------------------------------------------------------------------------ */
+/** Human-facing list of what a Cloud key unlocks over OSS single-player. Shown
+ *  whether or not a key is present, so a keyless dev sees the offer. */
+export const CLOUD_UNLOCKS = [
+    "a free dev-mode starter model allowance (keyless first turns)",
+    "team sharing and org governance (roles, SSO)",
+    "hosted deploys of your enabled automations",
+    "registry publishing and hosted infrastructure defaults like the managed MCP broker",
+];
+/** Check VENDO_API_KEY presence and shape locally; always surface what Cloud
+ *  unlocks. Key problems surface on the first real service call — there is no
+ *  validate endpoint. */
+export async function cloudDoctor(options = {}) {
+    const env = options.env ?? process.env;
+    const key = env["VENDO_API_KEY"];
+    if (key === undefined || key.trim().length === 0) {
+        return { present: false, ok: false, unlocks: CLOUD_UNLOCKS };
+    }
+    if (!isVendoKey(key)) {
+        return { present: true, ok: false, unlocks: CLOUD_UNLOCKS, error: "VENDO_API_KEY is malformed (expected vnd_ + 40 hex chars)" };
+    }
+    return { present: true, ok: true, unlocks: CLOUD_UNLOCKS };
+}
+function defaultSpawnDev(packageManager, root) {
+    return spawn(packageManager, ["run", "dev"], { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+}
+async function waitForStatus(statusUrl, fetchImpl, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const response = await fetchImpl(`${statusUrl}/status`);
+            if (response.ok)
+                return true;
+        }
+        catch {
+            // not up yet
+        }
+        await new Promise((resolve) => setTimeout(resolve, 750));
+    }
+    return false;
+}
+/** Spawn `run dev` and wait for the wire to answer. Caller stop()s it. */
+export async function startDevServerForProbe(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const packageManager = await detectPackageManager(options.root);
+    const child = (options.spawnDev ?? defaultSpawnDev)(packageManager, options.root);
+    const log = [];
+    const record = (data) => {
+        log.push(data.toString());
+        if (log.length > 200)
+            log.shift();
+    };
+    child.stdout?.on("data", record);
+    child.stderr?.on("data", record);
+    // A spawn failure (e.g. lockfile-derived package manager missing from PATH →
+    // ENOENT) emits 'error'; without a listener that crashes the whole process.
+    // Record it and short-circuit the status wait so the caller degrades to the
+    // "could not start" warning instead.
+    let failSpawn = () => { };
+    const spawnFailed = new Promise((resolve) => { failSpawn = () => resolve(false); });
+    child.on("error", (error) => {
+        log.push(`spawn error: ${error.message}\n`);
+        failSpawn();
+    });
+    const stop = () => { child.kill("SIGTERM"); };
+    const up = await Promise.race([
+        waitForStatus(options.statusUrl, fetchImpl, options.timeoutMs ?? 120_000),
+        spawnFailed,
+    ]);
+    if (!up)
+        stop();
+    return { ok: up, stop, log };
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,52 @@
+import { type CloudDoctorResult, type LiveTurnResult } from "./doctor-live.js";
+import { type Output } from "./shared.js";
+export interface DoctorOptions {
+    targetDir: string;
+    url?: string;
+    fetchImpl?: typeof fetch;
+    output?: Output;
+    /** Machine-readable single-object output (design §5). */
+    json?: boolean;
+    /** Auto-confirm the dev-server-probe consent — works non-interactively
+     *  (piped stdio / CI); --json runs never start the server. */
+    yes?: boolean;
+    env?: Record<string, string | undefined>;
+    telemetry?: {
+        home?: string;
+        env?: Record<string, string | undefined>;
+        posthogKey?: string;
+        fetchImpl?: typeof fetch;
+    };
+    /** Seams (tests): each new probe is injectable so doctor runs without keys
+     *  or a running server. */
+    interactive?: boolean;
+    confirm?: (question: string, defaultYes?: boolean) => Promise<boolean>;
+    liveTurn?: (base: string) => Promise<LiveTurnResult>;
+    cloudProbe?: (options: {
+        env?: Record<string, string | undefined>;
+    }) => Promise<CloudDoctorResult>;
+    startDevServer?: (options: {
+        root: string;
+        statusUrl: string;
+        env?: Record<string, string | undefined>;
+        fetchImpl?: typeof fetch;
+    }) => Promise<{
+        ok: boolean;
+        stop: () => void;
+    }>;
+}
+/** Doctor runs standalone, so unlike the dev server it gets no framework
+ *  dotenv loading — without this, `VENDO_API_KEY` sitting in `.env.local`
+ *  is invisible to the cloud/live-turn checks and users must export it by
+ *  hand. Reads `.env` then `.env.local` (local wins); real process env wins
+ *  over both at the merge site. Minimal KEY=VALUE parser: `export ` prefix,
+ *  matching single/double quotes, and `#` comment lines. */
+export declare function readDotEnvFallback(root: string): Promise<Record<string, string>>;
+/** Process env wins over the dotenv fallback — except that a blank process
+ *  value yields to a concrete dotenv one, matching toolingTelemetry's
+ *  VENDO_API_KEY precedence (an exported empty `VENDO_API_KEY=` must not
+ *  mask the real key in `.env.local`). */
+export declare function mergeEnvOverDotEnv(fallback: Record<string, string>, processEnv: NodeJS.ProcessEnv): Record<string, string | undefined>;
+/** 09-vendo §5 / block-actions A — wiring checks plus live composition,
+    present-credential, and actAs mint+verify round-trips. */
+export declare function runDoctor(options: DoctorOptions): Promise<number>;