@vendoai/vendo 0.4.0

package/dist/cli/doctor.js

@@ -0,0 +1,467 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { stdin, stdout } from "node:process";
+import { cloudDoctor, liveModelTurn, startDevServerForProbe, } from "./doctor-live.js";
+import { installedAiVersion } from "./dep-versions.js";
+import { doctorFixRef } from "./doctor-codes.js";
+import { EJECT_MANIFEST_FILE } from "./eject.js";
+import { detectFramework, detectVendoWiring } from "./framework.js";
+import { walk } from "./theme/walk.js";
+import { remoteUrls, sameUrl, validateRegistryServer } from "./mcp/registry.js";
+import { askYesNo, CLI_VERSION, consoleOutput, exists, normalizeDotEnvValue, readOptional, toolingTelemetry } from "./shared.js";
+async function hasDependency(root) {
+    try {
+        const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+        return [manifest.dependencies, manifest.devDependencies].some((deps) => deps?.["@vendoai/vendo"] !== undefined || deps?.vendoai !== undefined);
+    }
+    catch {
+        return false;
+    }
+}
+/** root rides in as the client's cwd: projectIdHash/packageManager and the
+    .env.local cloud-key read attribute to the TARGET project, not the shell
+    cwd. Seams in options.telemetry win. */
+function telemetryFor(options, output, root) {
+    return toolingTelemetry({ cwd: root, ...options.telemetry, log: (message) => output.log(message) });
+}
+async function probeBody(response) {
+    try {
+        const body = await response.json();
+        return typeof body === "object" && body !== null ? body : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** 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 async function readDotEnvFallback(root) {
+    const env = {};
+    for (const file of [".env", ".env.local"]) {
+        const source = await readOptional(join(root, file));
+        if (source === null)
+            continue;
+        for (const rawLine of source.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (line === "" || line.startsWith("#"))
+                continue;
+            const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line);
+            if (!match)
+                continue;
+            env[match[1]] = normalizeDotEnvValue(match[2].trim());
+        }
+    }
+    return env;
+}
+/** 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 function mergeEnvOverDotEnv(fallback, processEnv) {
+    const merged = { ...fallback, ...processEnv };
+    for (const [key, value] of Object.entries(processEnv)) {
+        if ((value ?? "").trim() === "" && fallback[key] !== undefined)
+            merged[key] = fallback[key];
+    }
+    return merged;
+}
+/** 09-vendo §5 / block-actions A — wiring checks plus live composition,
+    present-credential, and actAs mint+verify round-trips. */
+export async function runDoctor(options) {
+    const root = resolve(options.targetDir);
+    const output = options.output ?? consoleOutput;
+    const json = options.json === true;
+    const env = options.env ?? mergeEnvOverDotEnv(await readDotEnvFallback(root), process.env);
+    const telemetry = telemetryFor(options, output, root);
+    let failures = 0;
+    let warnings = 0;
+    const checks = [];
+    // In --json mode nothing but the final object may reach stdout; human lines
+    // are suppressed and the same information rides the checks array instead.
+    const note = (message) => { if (!json)
+        output.log(message); };
+    // Human lines stay exactly as before (the fix_ref URL is a machine
+    // affordance; --json is the agent surface, so no per-line URL noise here).
+    const pass = (id, message) => { checks.push({ id, status: "ok", message }); if (!json)
+        output.log(`ok: ${message}`); };
+    const fail = (id, code, message) => { failures += 1; checks.push({ id, status: "broken", message, error_code: code, fix_ref: doctorFixRef(code) }); if (!json)
+        output.error(`broken: ${message}`); };
+    const warn = (id, code, message) => { warnings += 1; checks.push({ id, status: "warning", message, error_code: code, fix_ref: doctorFixRef(code) }); if (!json)
+        output.error(`warning: ${message}`); };
+    const framework = await detectFramework(root);
+    if (framework === "express") {
+        const wiring = await detectVendoWiring(root);
+        if (wiring.server)
+            pass("wiring/express-server", "Express server is wired");
+        else
+            fail("wiring/express-server", "E-WIRE-001", "Express server is not wired with createVendo from @vendoai/vendo/server");
+        if (wiring.client)
+            pass("wiring/express-client", "<VendoRoot> wraps the client");
+        else
+            fail("wiring/express-client", "E-WIRE-002", "Express client is not wrapped in <VendoRoot>");
+    }
+    else {
+        const routeCandidates = [
+            join(root, "app", "api", "vendo", "[...vendo]", "route.ts"),
+            join(root, "src", "app", "api", "vendo", "[...vendo]", "route.ts"),
+        ];
+        if ((await Promise.all(routeCandidates.map(exists))).some(Boolean))
+            pass("wiring/next-route", "catch-all handler is wired");
+        else
+            fail("wiring/next-route", "E-WIRE-003", "missing app/api/vendo/[...vendo]/route.ts");
+        const layoutCandidates = [join(root, "app", "layout.tsx"), join(root, "src", "app", "layout.tsx")];
+        let rootWired = false;
+        for (const path of layoutCandidates) {
+            try {
+                if ((await readFile(path, "utf8")).includes("<VendoRoot"))
+                    rootWired = true;
+            }
+            catch {
+                // Try the other layout convention.
+            }
+        }
+        if (rootWired)
+            pass("wiring/next-root", "<VendoRoot> wraps the app");
+        else
+            fail("wiring/next-root", "E-WIRE-004", "root layout is not wrapped in <VendoRoot>");
+    }
+    if (await hasDependency(root))
+        pass("wiring/dependency", "@vendoai/vendo dependency is declared");
+    else
+        fail("wiring/dependency", "E-WIRE-005", "@vendoai/vendo (or vendoai alias) is not declared");
+    // #478 short-term — @vendoai/vendo speaks AI SDK v6 to the host's `ai`
+    // package (peer `ai >=6 <7`), but npm installs the peer conflict anyway:
+    // the static checks all pass and every internal turn then throws
+    // AI_InvalidPromptError (v7 removed system-role messages). Fail fast on the
+    // installed major. An absent install is the wiring/turn checks' story, and
+    // pre-v6 installs predate the peer contract — both skip silently.
+    const aiVersion = await installedAiVersion(root);
+    const aiMajor = aiVersion === null ? Number.NaN : Number.parseInt(aiVersion, 10);
+    if (aiMajor >= 7) {
+        fail("deps/ai-sdk-major", "E-DEP-001", `installed ai@${aiVersion} is unsupported — Vendo supports ai@6; downgrade (npm install ai@^6 @ai-sdk/anthropic@^3 @ai-sdk/react@^3) or track github.com/runvendo/vendo/issues/478`);
+    }
+    else if (aiMajor === 6) {
+        pass("deps/ai-sdk-major", `installed ai@${aiVersion} is the supported AI SDK major (v6)`);
+    }
+    for (const file of ["tools.json", "overrides.json", "policy.json", "brief.md", "theme.json"]) {
+        if (await exists(join(root, ".vendo", file)))
+            pass(`config/${file}`, `.vendo/${file}`);
+        else
+            fail(`config/${file}`, "E-CFG-001", `missing .vendo/${file}`);
+    }
+    if (!await exists(join(root, ".vendo", "data", ".gitignore")))
+        warn("config/data-gitignore", "E-CFG-002", ".vendo/data/.gitignore is missing");
+    // §4 customization ladder — ejected chrome drift. The ejected pixels are the
+    // host's code, so a version gap is awareness (warn), never breakage (fail):
+    // the hooks/wire dependency keeps working; only new presentation is missed.
+    const installedUi = await readOptional(join(root, "node_modules", "@vendoai", "ui", "package.json"));
+    let uiVersion = null;
+    try {
+        if (installedUi !== null)
+            uiVersion = JSON.parse(installedUi).version ?? null;
+    }
+    catch {
+        // Malformed install metadata — skip the drift check rather than fail doctor.
+    }
+    if (uiVersion !== null) {
+        for (const manifestPath of await walk(root, (rel) => rel.endsWith(EJECT_MANIFEST_FILE))) {
+            let ejected;
+            try {
+                ejected = JSON.parse(await readFile(manifestPath, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            if (ejected.version === uiVersion) {
+                pass(`eject/${ejected.surface}`, `ejected ${ejected.surface} matches @vendoai/ui v${uiVersion}`);
+            }
+            else {
+                warn(`eject/${ejected.surface}`, "E-UI-001", `ejected ${ejected.surface} came from @vendoai/ui v${ejected.version} but v${uiVersion} is installed — review the changelog (https://github.com/runvendo/vendo/releases) and \`vendo eject ${ejected.surface} --force\` if you want the new presentation`);
+            }
+        }
+    }
+    const statusUrl = options.url
+        ?? env.VENDO_URL?.replace(/\/$/, "")
+        ?? "http://localhost:3000/api/vendo";
+    const fetchImpl = options.fetchImpl ?? fetch;
+    // Consent-gated dev-server start (design §5): when nothing is listening on
+    // the dev port and doctor is interactive, offer to boot it so the live probes
+    // have something to reach. --yes is the documented non-interactive consent
+    // (quickstart: "pass --yes to start it non-interactively"), so it bypasses
+    // the TTY gate. Skipped in --json runs (stdout carries only the final object).
+    const interactive = options.interactive ?? (Boolean(stdout.isTTY) && Boolean(stdin.isTTY));
+    const confirm = options.confirm ?? askYesNo;
+    let devServerStop = null;
+    if (!json && (interactive || options.yes === true)) {
+        let listening = false;
+        try {
+            listening = (await fetchImpl(`${statusUrl}/status`)).ok;
+        }
+        catch {
+            listening = false;
+        }
+        if (!listening) {
+            const go = options.yes === true
+                || await confirm("Nothing is listening on the dev port. Start the dev server for the probe?", true);
+            if (go) {
+                note(`\nStarting the dev server so the probe has a live composition to reach…`);
+                const start = options.startDevServer ?? startDevServerForProbe;
+                const started = await start({ root, statusUrl, env, fetchImpl });
+                if (started.ok) {
+                    devServerStop = started.stop;
+                    pass("dev/start", "started the dev server for the probe");
+                }
+                else
+                    warn("dev/start", "E-DEV-001", "could not start the dev server for the probe; start it yourself (e.g. `npm run dev`) and re-run `vendo doctor`");
+            }
+        }
+    }
+    let mcpEnabled = false;
+    let sandboxVenue;
+    let liveComposition = false;
+    try {
+        const response = await fetchImpl(`${statusUrl}/status`, {
+            headers: { accept: "application/json" },
+        });
+        const body = await response.json();
+        if (!response.ok || typeof body.posture !== "string" || typeof body.version !== "string"
+            || typeof body.blocks !== "object" || body.blocks === null) {
+            fail("live/status", "E-LIVE-001", `/status returned an invalid composition response (${response.status})`);
+        }
+        else {
+            pass("live/status", `/status live round-trip (${body.version}, ${body.posture})`);
+            liveComposition = true;
+            // 10-mcp §1 — the door flag lives under blocks.mcp.
+            mcpEnabled = body.blocks.mcp === true;
+            sandboxVenue = body.blocks.sandbox;
+            if (sandboxVenue === "e2b" || sandboxVenue === "cloud" || sandboxVenue === "custom") {
+                pass("live/venue", `execution venue: ${sandboxVenue}`);
+            }
+            else if (sandboxVenue === false) {
+                warn("live/venue", "E-LIVE-004", "install the e2b package and set E2B_API_KEY, or set VENDO_API_KEY for the managed Cloud sandbox, or pass sandbox: to createVendo; without one, server apps (rungs 2-4) return sandbox-unavailable");
+            }
+            else if (sandboxVenue === undefined) {
+                // Older hosts predate blocks.sandbox — version skew, not a broken install.
+                warn("live/venue", "E-LIVE-005", "host /status does not report an execution venue; upgrade @vendoai/vendo to enable the venue check");
+            }
+            else {
+                fail("live/venue", "E-LIVE-003", "/status returned an invalid execution venue");
+            }
+        }
+    }
+    catch {
+        fail("live/status", "E-LIVE-002", `/status is unreachable at ${statusUrl}/status`);
+    }
+    if (!liveComposition) {
+        fail("auth/present", "E-AUTH-003", `present credential probe cannot run; start the dev server at ${statusUrl} and retry`);
+        fail("auth/act-as", "E-AUTH-006", `cannot probe actAs; start the dev server at ${statusUrl} and retry`);
+    }
+    else {
+        try {
+            const response = await fetchImpl(`${statusUrl}/doctor/present`, {
+                method: "POST",
+                headers: {
+                    accept: "application/json",
+                    "content-type": "application/json",
+                    authorization: "Bearer vendo-doctor-present",
+                    cookie: "vendo_doctor_present=1",
+                },
+                body: "{}",
+            });
+            const body = await probeBody(response);
+            if (response.ok && body.ok === true) {
+                pass("auth/present", "present credentials reach the host API");
+            }
+            else {
+                fail("auth/present", "E-AUTH-001", "present credentials did not reach the host API; set VENDO_BASE_URL to the running host origin and restart the dev server");
+            }
+        }
+        catch {
+            fail("auth/present", "E-AUTH-002", `present credential probe is unreachable at ${statusUrl}/doctor/present; restart the dev server and verify VENDO_BASE_URL`);
+        }
+        try {
+            const response = await fetchImpl(`${statusUrl}/doctor/act-as`, {
+                method: "POST",
+                headers: { accept: "application/json", "content-type": "application/json" },
+                body: "{}",
+            });
+            const body = await probeBody(response);
+            if (response.ok && body.ok === true) {
+                pass("auth/act-as", "actAs mint + host verification live round-trip");
+            }
+            else if (body.error?.code === "act-as-not-configured") {
+                warn("auth/act-as", "E-AUTH-007", "actAs is not configured; pass createVendo({ actAs }) before enabling away host actions");
+            }
+            else {
+                fail("auth/act-as", "E-AUTH-004", "actAs mint + host verification failed; check createVendo({ actAs }), its verifier middleware, and the host principal resolver");
+            }
+        }
+        catch {
+            fail("auth/act-as", "E-AUTH-005", `actAs probe is unreachable at ${statusUrl}/doctor/act-as; restart the dev server and check createVendo({ actAs })`);
+        }
+    }
+    // 10-mcp §5 — when the door is open, verify both discovery documents resolve
+    // and the server card parses. The metadata is path-inserted (RFC 9728 §3): a
+    // door mounted at /api/vendo/mcp serves /.well-known/...-resource/api/vendo/mcp.
+    if (mcpEnabled) {
+        const origin = new URL(statusUrl).origin;
+        const mountPath = `${new URL(statusUrl).pathname.replace(/\/$/, "")}/mcp`;
+        const resolves = async (id, code, url, valid, label) => {
+            try {
+                const response = await fetchImpl(url, { headers: { accept: "application/json" } });
+                const body = await response.json();
+                if (response.ok && valid(body))
+                    pass(id, label);
+                else
+                    fail(id, code, `${label} (${response.status})`);
+            }
+            catch {
+                fail(id, code, `${label} is unreachable`);
+            }
+        };
+        await resolves("mcp/protected-resource", "E-MCP-001", `${origin}/.well-known/oauth-protected-resource${mountPath}`, (body) => typeof body.resource === "string", "MCP protected-resource metadata resolves");
+        await resolves("mcp/authorization-server", "E-MCP-002", `${origin}/.well-known/oauth-authorization-server${mountPath}`, (body) => typeof body.issuer === "string", "MCP authorization-server metadata resolves");
+        await resolves("mcp/server-card", "E-MCP-003", `${origin}/.well-known/mcp/server-card.json`, (body) => typeof body.name === "string" && Array.isArray(body.transports), "MCP server card parses");
+        // 10-mcp §5 — the official registry artifact is optional until a host is
+        // published, but once present it must describe this live door exactly.
+        const serverJson = await readOptional(join(root, "server.json"));
+        if (serverJson !== null) {
+            try {
+                const server = JSON.parse(serverJson);
+                const errors = validateRegistryServer(server);
+                if (errors.length === 0)
+                    pass("mcp/server-json", "server.json matches MCP registry discovery requirements");
+                else
+                    fail("mcp/server-json", "E-MCP-004", `server.json is invalid: ${errors.join("; ")}`);
+                const liveDoorUrl = `${origin}${mountPath}`;
+                if (remoteUrls(server).some((remote) => sameUrl(remote, liveDoorUrl))) {
+                    pass("mcp/server-json-remote", "server.json remote agrees with the live MCP door");
+                }
+                else {
+                    fail("mcp/server-json-remote", "E-MCP-005", `server.json remote does not match the live MCP door ${liveDoorUrl}`);
+                }
+            }
+            catch {
+                fail("mcp/server-json", "E-MCP-006", "server.json is invalid JSON");
+            }
+        }
+        const localChallenge = await readOptional(join(root, "public", ".well-known", "mcp-registry-auth"));
+        if (localChallenge !== null) {
+            if (localChallenge.trim().startsWith("v=MCPv1"))
+                pass("mcp/registry-auth-local", "local MCP registry auth challenge parses");
+            else
+                fail("mcp/registry-auth-local", "E-MCP-007", "local MCP registry auth challenge must start with v=MCPv1");
+        }
+        try {
+            const response = await fetchImpl(`${origin}/.well-known/mcp-registry-auth`, {
+                headers: { accept: "text/plain" },
+            });
+            if (response.ok) {
+                const challenge = await response.text();
+                if (challenge.trim().startsWith("v=MCPv1"))
+                    pass("mcp/registry-auth-live", "MCP registry auth challenge parses");
+                else
+                    fail("mcp/registry-auth-live", "E-MCP-008", "MCP registry auth challenge must start with v=MCPv1");
+            }
+        }
+        catch {
+            // The HTTP proof is optional; DNS verification may be in use instead.
+        }
+    }
+    // execution-v2 Lane D — machine + schedule REPORTING (no new subcommand):
+    // which apps carry a machine, whether a schedule caller is configured for
+    // the authenticated /tick surface, and each schedule's last-fired time.
+    // /doctor/machines is a dev-only route, so an unreachable or older host
+    // simply skips the section (reporting must never break doctor).
+    if (liveComposition) {
+        try {
+            const response = await fetchImpl(`${statusUrl}/doctor/machines`, { headers: { accept: "application/json" } });
+            if (response.ok) {
+                const body = await response.json();
+                const machines = Array.isArray(body.machines) ? body.machines : [];
+                pass("machines/apps", machines.length === 0
+                    ? "no machine-bearing apps"
+                    : `${machines.length} machine-bearing app${machines.length === 1 ? "" : "s"}`);
+                for (const machine of machines) {
+                    note(`  ${machine.appId ?? "?"} (${machine.name ?? "unnamed"}): ${machine.awake === true ? "awake" : "asleep"}`);
+                    for (const schedule of machine.schedules ?? []) {
+                        const lastFired = schedule.lastFiredAt === undefined
+                            ? "never fired"
+                            : `last fired ${schedule.lastFiredAt}${schedule.lastStatus === "error" ? " (error)" : ""}`;
+                        note(`    ${schedule.cron ?? "?"} -> POST /fn/${schedule.fn ?? "?"} — ${lastFired}`);
+                    }
+                }
+                const declaresSchedules = machines.some((machine) => (machine.schedules?.length ?? 0) > 0);
+                if (body.scheduleCallerConfigured === true) {
+                    pass("machines/schedule-caller", "schedule caller configured (VENDO_TICK_SECRET); point an external cron at POST /api/vendo/tick");
+                }
+                else if (declaresSchedules) {
+                    warn("machines/schedule-caller", "E-SCHED-001", "apps declare vendo.json schedules but no schedule caller is configured — set VENDO_TICK_SECRET and point an external cron (Vercel cron, GitHub Actions, crontab) at POST /api/vendo/tick");
+                }
+                else if (machines.length > 0) {
+                    note("  no schedule caller configured (VENDO_TICK_SECRET unset) — needed once an app declares vendo.json schedules");
+                }
+            }
+        }
+        catch {
+            // Reporting only — an unreachable machines route never fails doctor.
+        }
+    }
+    note("Ladder: execution venue is checked above; actAs for away host actions; connectors for external tools.");
+    // One real model turn through the wired route (design §5). Exit 0 == a user
+    // would have gotten an answer. Reuses the resolver + devModel: the running
+    // dev server serves the turn over the same credential doctor reports.
+    let liveTurn;
+    if (liveComposition) {
+        liveTurn = await (options.liveTurn ?? ((base) => liveModelTurn({
+            base,
+            fetchImpl,
+            env,
+        })))(statusUrl);
+        if (liveTurn.ok) {
+            pass("turn/model", `live model turn answered over ${liveTurn.credential} (${liveTurn.elapsedMs}ms)`);
+            if (liveTurn.reply !== undefined)
+                note(`\n  ${liveTurn.reply.trim()}\n`);
+        }
+        else {
+            fail("turn/model", "E-TURN-001", `live model turn did not answer over ${liveTurn.credential}: ${liveTurn.error ?? "no reply"}`);
+        }
+    }
+    else {
+        liveTurn = { attempted: false, ok: false, rung: "none", credential: "n/a", elapsedMs: 0, error: "dev server unreachable" };
+        fail("turn/model", "E-TURN-002", `live model turn cannot run; start the dev server at ${statusUrl} and retry`);
+    }
+    // VENDO_API_KEY local shape check + what Cloud unlocks (design §5-6). Key
+    // problems surface on the first real service call — no validate round-trip.
+    const cloud = await (options.cloudProbe ?? cloudDoctor)({ env });
+    if (cloud.present && cloud.ok) {
+        pass("cloud/key", "Vendo Cloud key present and well-formed");
+    }
+    else if (cloud.present) {
+        warn("cloud/key", "E-CLOUD-001", `VENDO_API_KEY is set but not usable: ${cloud.error ?? "malformed"}`);
+    }
+    else {
+        note(`Vendo Cloud (optional): no VENDO_API_KEY. A key unlocks ${cloud.unlocks.join("; ")}. Run \`vendo login\` to start.`);
+    }
+    if (devServerStop !== null)
+        devServerStop();
+    const wired = failures === 0;
+    await telemetry.track("doctor_run", { failures, warnings, wired });
+    if (json) {
+        output.log(JSON.stringify({
+            vendo: "doctor",
+            version: CLI_VERSION,
+            wired,
+            exit: wired ? 0 : 1,
+            checks,
+            liveTurn,
+            cloud,
+            summary: { failures, warnings },
+        }, null, 2));
+    }
+    return wired ? 0 : 1;
+}

package/dist/cli/eject.d.ts

@@ -0,0 +1,29 @@
+import { type Output, type TelemetryOptions } from "./shared.js";
+export interface EjectOptions {
+    targetDir: string;
+    surface?: string;
+    list?: boolean;
+    force?: boolean;
+    output?: Output;
+    /** Injectable telemetry deps (matches init/doctor). */
+    telemetry?: TelemetryOptions;
+}
+export declare const EJECT_MANIFEST_FILE = ".vendo-eject.json";
+export interface EjectedManifest {
+    surface: string;
+    package: "@vendoai/ui";
+    version: string;
+}
+/**
+ * Rewrite one template source for life in the host repo. Relative specifiers
+ * resolve against the surface's src/-relative sourceBase: imports landing in
+ * the surface's own directory stay relative (dropping the .js extension for
+ * host bundlers), everything else maps to the public package subpath it is
+ * exported from (tree/ → @vendoai/ui/tree, chrome/ → @vendoai/ui/chrome,
+ * hooks/context/theme → @vendoai/ui).
+ */
+export declare function rewriteTemplateSource(source: string, shape: {
+    sourceBase: string;
+    sourceDir?: string;
+}): string;
+export declare function runEject(options: EjectOptions): Promise<number>;

package/dist/cli/eject.js

@@ -0,0 +1,141 @@
+/**
+ * `vendo eject <surface>` — copy a shipped chrome surface's presentation
+ * source out of the installed @vendoai/ui into the host repo as code the
+ * developer owns, shadcn-style (§4 customization ladder, eject rung).
+ *
+ * Pixels are copied; data/wire logic stays a package dependency: the
+ * templates' package-internal relative imports are rewritten to the public
+ * @vendoai/ui subpaths, so protocol updates keep flowing to ejected code.
+ * A `.vendo-eject.json` manifest in the ejected directory records surface +
+ * package version for doctor's drift check.
+ */
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, posix, relative } from "node:path";
+import { consoleOutput, exists, withCommandRun } from "./shared.js";
+export const EJECT_MANIFEST_FILE = ".vendo-eject.json";
+/** dist/eject-templates of the installed @vendoai/ui — host install first
+    (its version is what the host runs), the CLI's own copy as fallback for
+    strict layouts where the host doesn't depend on @vendoai/ui directly. */
+function templatesRoot(targetDir) {
+    const anchors = [join(targetDir, "package.json"), import.meta.url];
+    for (const anchor of anchors) {
+        try {
+            const entry = createRequire(anchor).resolve("@vendoai/ui");
+            return join(dirname(entry), "eject-templates");
+        }
+        catch {
+            // try the next anchor
+        }
+    }
+    return null;
+}
+/**
+ * Rewrite one template source for life in the host repo. Relative specifiers
+ * resolve against the surface's src/-relative sourceBase: imports landing in
+ * the surface's own directory stay relative (dropping the .js extension for
+ * host bundlers), everything else maps to the public package subpath it is
+ * exported from (tree/ → @vendoai/ui/tree, chrome/ → @vendoai/ui/chrome,
+ * hooks/context/theme → @vendoai/ui).
+ */
+export function rewriteTemplateSource(source, shape) {
+    // from-clauses, side-effect imports, and dynamic import() all carry
+    // specifiers; the quote never follows "import" directly in a from-clause,
+    // so the alternation cannot double-match.
+    return source.replace(/(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(["'])([^"']+)\2/g, (whole, lead, quote, specifier) => {
+        if (!specifier.startsWith("."))
+            return whole;
+        const resolved = posix.normalize(posix.join(shape.sourceBase, specifier)).replace(/\.js$/, "");
+        let rewritten;
+        if (shape.sourceDir !== undefined &&
+            (resolved === shape.sourceDir || resolved.startsWith(`${shape.sourceDir}/`))) {
+            rewritten = specifier.replace(/\.js$/, "");
+        }
+        else if (resolved.startsWith("tree/"))
+            rewritten = "@vendoai/ui/tree";
+        else if (resolved.startsWith("chrome/"))
+            rewritten = "@vendoai/ui/chrome";
+        else
+            rewritten = "@vendoai/ui";
+        return `${lead}${quote}${rewritten}${quote}`;
+    });
+}
+/** components/vendo/<surface>, under src/ when the host keeps its app there
+    (same layout probe as init's appDirectory). `srcLayout` also picks the
+    swap hint's import form: src hosts import via their @/ alias. */
+async function destinationDir(root, surface) {
+    const srcLayout = await exists(join(root, "src", "app"));
+    const base = srcLayout ? join(root, "src") : root;
+    return { destination: join(base, "components", "vendo", surface), srcLayout };
+}
+export async function runEject(options) {
+    const output = options.output ?? consoleOutput;
+    const root = options.targetDir;
+    return withCommandRun({
+        command: "eject",
+        root,
+        ...(options.telemetry === undefined ? {} : { telemetry: options.telemetry }),
+    }, (failure) => eject(options, output, root, failure));
+}
+async function eject(options, output, root, failure) {
+    const templates = templatesRoot(root);
+    if (templates === null || !(await exists(join(templates, "templates.json")))) {
+        failure.failedStep = "templates";
+        output.error("vendo eject: could not find an installed @vendoai/ui with eject templates — install vendoai (or @vendoai/ui) first.");
+        return 1;
+    }
+    const manifest = JSON.parse(await readFile(join(templates, "templates.json"), "utf8"));
+    const available = Object.keys(manifest.surfaces).sort();
+    if (options.list === true) {
+        output.log(`Ejectable surfaces (@vendoai/ui v${manifest.version}):`);
+        for (const surface of available) {
+            output.log(`  ${surface}  ${manifest.surfaces[surface].description}`);
+        }
+        output.log("\nRun `vendo eject <surface>` to copy one into your repo.");
+        return 0;
+    }
+    const surface = options.surface;
+    if (surface === undefined || surface === "") {
+        failure.failedStep = "surface";
+        output.error(`vendo eject: name a surface (${available.join(", ")}) or use --list.`);
+        return 1;
+    }
+    const entry = manifest.surfaces[surface];
+    if (entry === undefined) {
+        failure.failedStep = "surface";
+        output.error(`vendo eject: unknown surface "${surface}" — available: ${available.join(", ")}.`);
+        return 1;
+    }
+    const { destination, srcLayout } = await destinationDir(root, surface);
+    if (await exists(destination)) {
+        if (options.force !== true) {
+            failure.failedStep = "exists";
+            output.error(`vendo eject: ${relative(root, destination)} already exists — it may hold your edits. Re-run with --force to overwrite.`);
+            return 1;
+        }
+        await rm(destination, { recursive: true, force: true });
+    }
+    await mkdir(destination, { recursive: true });
+    const shape = { sourceBase: entry.sourceBase, ...(entry.sourceDir === undefined ? {} : { sourceDir: entry.sourceDir }) };
+    for (const file of entry.files) {
+        const source = await readFile(join(templates, surface, file), "utf8");
+        await writeFile(join(destination, file), rewriteTemplateSource(source, shape), "utf8");
+    }
+    const ejected = { surface, package: "@vendoai/ui", version: manifest.version };
+    await writeFile(join(destination, EJECT_MANIFEST_FILE), `${JSON.stringify(ejected, null, 2)}\n`, "utf8");
+    const relDir = relative(root, destination);
+    const componentName = entry.component;
+    // src hosts import through their @/ alias; "./src/…" would mislead (Devin
+    // ANALYSIS_0001 — an importer under src/ never writes the src/ segment).
+    const importHint = srcLayout ? `@/components/vendo/${surface}` : `./components/vendo/${surface}`;
+    output.log(`Ejected ${surface} → ${relDir} (${entry.files.length} files, @vendoai/ui v${manifest.version})`);
+    output.log("");
+    output.log("Swap it in:");
+    output.log(`  import { ${componentName} } from "${importHint}";`);
+    output.log(surface === "thread"
+        ? `  <VendoOverlay thread={${componentName}} />`
+        : `  <${componentName} />  (in place of the @vendoai/ui/chrome import)`);
+    output.log("");
+    output.log("The files are yours to edit. Data and wire logic still flow from @vendoai/ui.");
+    return 0;
+}

package/dist/cli/extract/apply.d.ts

@@ -0,0 +1,26 @@
+import { type Output, type TelemetryOptions } from "../shared.js";
+/**
+ * `vendo extract --apply <draft.json>` — the delegation surface. An external
+ * coding agent read the codebase against the aiPolish contract from
+ * `vendo init --agent` and wrote a draft; this command parses it (the same
+ * parseDraft init's built-in pass uses), runs the SAME deterministic guards
+ * (applyDraft), writes the same artifacts, re-syncs, and prints the same
+ * summary. Non-interactive safe; exits non-zero on an unusable draft.
+ */
+export interface ExtractApplyOptions {
+    targetDir: string;
+    /** Path to the draft file (cwd-relative or absolute). */
+    apply: string;
+    force?: boolean;
+    output?: Output;
+    /** Test seam (matches sync.ts): the re-sync implementation. */
+    sync?: (input: {
+        root: string;
+        out: string;
+    }) => Promise<{
+        warnings: string[];
+    }>;
+    /** Injectable telemetry deps (matches init/doctor). */
+    telemetry?: TelemetryOptions;
+}
+export declare function runExtractApply(options: ExtractApplyOptions): Promise<number>;