@vendoai/vendo 0.4.0

package/dist/cli/refine.js

@@ -0,0 +1,181 @@
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { DevModelController } from "../dev-creds/model.js";
+import { runRefine } from "../refine.js";
+import { consoleOutput, exists, withCommandRun, writeText } from "./shared.js";
+const INTERVIEW_QUESTIONS = [
+    "What should users be able to ask the agent for that today's tools can't do in one step? (Enter to skip)",
+    "Any tools that look mislabeled, misdescribed, or that should be disabled? (Enter to skip)",
+];
+async function importHostModule(root, specifier) {
+    if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("file:")) {
+        const url = specifier.startsWith("file:") ? specifier : pathToFileURL(resolve(root, specifier)).href;
+        return await import(url);
+    }
+    const require = createRequire(join(root, "package.json"));
+    return await import(pathToFileURL(require.resolve(specifier)).href);
+}
+/** BYO key through the existing provider-agnostic seam: `--model-import` loads
+ * the host's own ai-SDK model module; otherwise the shared dev-credential
+ * ladder composes (the same resolver init, doctor, and createVendo ride):
+ * provider env keys first, then VENDO_API_KEY via the Cloud model gateway.
+ * Resolved EAGERLY so a credential problem fails here, with instructions,
+ * instead of mid-run. */
+export async function resolveRefineModel(options) {
+    if (options.modelImport !== undefined) {
+        let loaded;
+        try {
+            loaded = await importHostModule(options.root, options.modelImport);
+        }
+        catch (error) {
+            throw new Error(`could not import ${options.modelImport}: ${error instanceof Error ? error.message : "unknown error"}. `
+                + "Pass a runnable JS module (a TypeScript source module needs your runtime to strip types) "
+                + "exporting your ai-SDK model as `model` (or default).");
+        }
+        const model = (loaded["model"] ?? loaded["default"]);
+        if (model === undefined) {
+            throw new Error(`${options.modelImport} does not export an ai-SDK model as \`model\` (or default)`);
+        }
+        return model;
+    }
+    const controller = new DevModelController({
+        root: options.root,
+        env: options.env,
+        ...(options.importModule === undefined ? {} : { importModule: options.importModule }),
+    });
+    const resolution = await controller.resolve();
+    if (resolution.mode === "unavailable") {
+        throw new Error(`${resolution.message} Or pass --model-import <specifier> pointing at a module that exports your ai-SDK \`model\`.`);
+    }
+    return resolution.model;
+}
+async function defaultInterview(questions) {
+    if (!stdin.isTTY)
+        return [];
+    const readline = createInterface({ input: stdin, output: stdout });
+    const answers = [];
+    try {
+        for (const question of questions) {
+            const answer = (await readline.question(`${question}\n> `)).trim();
+            if (answer !== "")
+                answers.push(answer);
+        }
+    }
+    finally {
+        readline.close();
+    }
+    return answers;
+}
+async function defaultConfirm(change, output) {
+    if (!stdin.isTTY) {
+        output.error(`skipped ${change.path}; re-run interactively or with --yes to apply it`);
+        return false;
+    }
+    const readline = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = await readline.question(`Apply ${change.path}? [y/N] `);
+        return ["y", "yes"].includes(answer.trim().toLowerCase());
+    }
+    finally {
+        readline.close();
+    }
+}
+async function writeTranscript(root, transcript) {
+    const stamp = transcript.startedAt.replace(/[:.]/g, "-");
+    const path = join(root, ".vendo", "data", "refine", `${stamp}.json`);
+    await writeText(path, `${JSON.stringify(transcript, null, 2)}\n`);
+    return path;
+}
+function printRun(result, output) {
+    for (const probe of result.probes) {
+        output.log(`probe ${probe.tool}: ${probe.status}`);
+        for (const check of probe.checks) {
+            output.log(`  ${check.ok ? "ok" : "failed"}: ${check.name} — ${check.detail}`);
+        }
+    }
+    for (const drop of result.dropped) {
+        output.error(`dropped ${drop.kind} ${drop.target}: ${drop.reason}`);
+    }
+}
+export async function runRefineCommand(options) {
+    const root = resolve(options.targetDir);
+    const output = options.output ?? consoleOutput;
+    return withCommandRun({
+        command: "refine",
+        root,
+        ...(options.telemetry === undefined ? {} : { telemetry: options.telemetry }),
+    }, (failure) => refineCommand(options, output, root, failure));
+}
+async function refineCommand(options, output, root, failure) {
+    const env = options.env ?? process.env;
+    if (!await exists(join(root, ".vendo", "tools.json"))) {
+        failure.failedStep = "tools";
+        output.error("refine needs .vendo/tools.json — run `vendo init` (or `vendo sync`) first");
+        return 1;
+    }
+    let model;
+    try {
+        model = options.model ?? await resolveRefineModel({
+            root,
+            ...(options.modelImport === undefined ? {} : { modelImport: options.modelImport }),
+            env,
+        });
+    }
+    catch (error) {
+        failure.failedStep = "model";
+        output.error(error instanceof Error ? error.message : "model resolution failed");
+        return 1;
+    }
+    let interview = options.asks ?? [];
+    if (interview.length === 0 && options.yes !== true) {
+        interview = await (options.interview ?? defaultInterview)(INTERVIEW_QUESTIONS);
+    }
+    let result;
+    try {
+        result = await runRefine({
+            root,
+            model,
+            interview,
+            ...(options.url === undefined ? {} : { url: options.url }),
+            ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+        });
+    }
+    catch (error) {
+        failure.failedStep = "run";
+        output.error(error instanceof Error ? error.message : "vendo refine failed");
+        return 1;
+    }
+    printRun(result, output);
+    if (result.changes.length === 0) {
+        output.log("No changes proposed.");
+        const transcriptPath = await writeTranscript(root, result.transcript);
+        output.log(`Transcript: ${transcriptPath}`);
+        return 0;
+    }
+    let applied = 0;
+    for (const change of result.changes) {
+        output.log(`\nProposed change:\n${change.diff}\n`);
+        for (const warning of change.warnings)
+            output.error(`warning: ${warning}`);
+        const approved = options.yes === true
+            || await (options.confirm ?? ((candidate) => defaultConfirm(candidate, output)))(change);
+        if (approved) {
+            await writeText(join(root, ...change.path.split("/")), change.after);
+            applied += 1;
+            output.log(`wrote ${change.path}`);
+        }
+        else {
+            output.error(`skipped ${change.path}; run \`vendo refine\` again to re-propose`);
+        }
+        result.transcript.decisions.push({ path: change.path, applied: approved });
+    }
+    const transcriptPath = await writeTranscript(root, result.transcript);
+    output.log(`\nApplied ${applied} of ${result.changes.length} proposed change(s). Transcript: ${transcriptPath}`);
+    if (applied > 0) {
+        output.log("Review the diffs with `git diff .vendo` and commit them; the registry loads capabilities and overrides on the next boot.");
+    }
+    return 0;
+}

package/dist/cli/semantics.d.ts

@@ -0,0 +1,31 @@
+/**
+ * W3 (v3 spec §Context) — `.vendo/semantics.json`, written by `vendo sync`.
+ *
+ * Per tool response field: `money(cents|dollars)`, `date(iso|epoch)`,
+ * `enum(value→label)`, `id(entity)`, `percent(ratio|0-100)` — everything else
+ * stays plain and is omitted. Priority per field:
+ *
+ *   1. host annotation (`overrides.json.tools[name].semantics`)
+ *   2. what this file already says (inference runs ONCE — a host edit here
+ *      is never overwritten, and an inference never churns)
+ *   3. fresh inference (the dev server samples each zero-input read tool at
+ *      POST /sync/semantics and returns classifications, never values)
+ *
+ * The `domains` manifest (has / has-NOT) is derived from tool names on FIRST
+ * sync and host-owned afterwards.
+ */
+export interface SemanticsSyncOptions {
+    vendoDir: string;
+    /** The dev-server wire base (same seam as /sync/impact). */
+    url: string;
+    fetchImpl?: typeof fetch;
+    /** CLI-note sink (unreachable server, malformed file). */
+    note: (message: string) => void;
+}
+/** host_listAccountTransactions → "account transactions". */
+export declare const domainFromToolName: (name: string) => string | undefined;
+export declare const deriveDomains: (toolNames: readonly string[]) => string[];
+/** Read tools + annotations + the existing file, fetch one-time inference,
+ *  merge by priority, and write `.vendo/semantics.json`. Fail-soft: any
+ *  problem becomes a note, never a sync failure. */
+export declare function syncSemantics(options: SemanticsSyncOptions): Promise<void>;

package/dist/cli/semantics.js

@@ -0,0 +1,122 @@
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { fieldSemanticSchema, semanticsFileSchema, VENDO_SEMANTICS_FORMAT, } from "@vendoai/core";
+import { overridesFileSchema, toolsFileSchema } from "@vendoai/actions";
+const readJson = async (file) => {
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Verb tokens dropped from a tool name when deriving its data domain. */
+const NAME_VERBS = /^(get|list|create|update|delete|set|send|reset|simulate|search|fetch|read|add|remove|post|put|patch)$/i;
+/** Whole tools that are plumbing, not a data domain. */
+const NOISE_TOKENS = /^(auth|demo|voice|session|sessions|webhook|webhooks|health|ping)$/i;
+/** host_listAccountTransactions → "account transactions". */
+export const domainFromToolName = (name) => {
+    const tokens = name
+        .replace(/^host_/, "")
+        .split(/[_.]/)
+        .flatMap((part) => part.split(/(?=[A-Z])/))
+        .map((token) => token.toLowerCase())
+        .filter((token) => token.length > 0);
+    if (tokens.some((token) => NOISE_TOKENS.test(token)))
+        return undefined;
+    const nouns = tokens.filter((token) => !NAME_VERBS.test(token));
+    if (nouns.length === 0)
+        return undefined;
+    return nouns.join(" ");
+};
+export const deriveDomains = (toolNames) => [...new Set(toolNames.map(domainFromToolName).filter((domain) => domain !== undefined))].sort();
+const fetchInferred = async (options) => {
+    try {
+        const response = await (options.fetchImpl ?? fetch)(`${options.url}/sync/semantics`, {
+            method: "POST",
+            headers: { accept: "application/json", "content-type": "application/json" },
+            body: "{}",
+        });
+        if (!response.ok)
+            throw new Error(`sync semantics returned ${response.status}`);
+        const body = await response.json();
+        if (typeof body !== "object" || body === null || typeof body.tools !== "object" || body.tools === null) {
+            throw new Error("invalid sync semantics response");
+        }
+        // Validate every entry; a malformed one drops rather than poisoning the file.
+        const tools = {};
+        for (const [tool, fields] of Object.entries(body.tools)) {
+            const cleaned = {};
+            for (const [path, semantic] of Object.entries(fields)) {
+                const parsed = fieldSemanticSafe(semantic);
+                if (parsed !== undefined)
+                    cleaned[path] = parsed;
+            }
+            if (Object.keys(cleaned).length > 0)
+                tools[tool] = cleaned;
+        }
+        return tools;
+    }
+    catch {
+        options.note(`semantics inference skipped — dev server not reachable at ${options.url}`);
+        return undefined;
+    }
+};
+const fieldSemanticSafe = (value) => {
+    const result = fieldSemanticSchema.safeParse(value);
+    return result.success ? result.data : undefined;
+};
+/** Read tools + annotations + the existing file, fetch one-time inference,
+ *  merge by priority, and write `.vendo/semantics.json`. Fail-soft: any
+ *  problem becomes a note, never a sync failure. */
+export async function syncSemantics(options) {
+    const toolsRaw = await readJson(join(options.vendoDir, "tools.json"));
+    const toolsParse = toolsFileSchema.safeParse(toolsRaw);
+    if (!toolsParse.success)
+        return; // no tools file → nothing to describe
+    const toolNames = toolsParse.data.tools.map((tool) => tool.name);
+    const overridesRaw = await readJson(join(options.vendoDir, "overrides.json"));
+    const overridesParse = overridesFileSchema.safeParse(overridesRaw);
+    const annotations = {};
+    if (overridesParse.success) {
+        for (const [tool, override] of Object.entries(overridesParse.data.tools)) {
+            if (override.semantics !== undefined)
+                annotations[tool] = override.semantics;
+        }
+    }
+    const file = join(options.vendoDir, "semantics.json");
+    const existingRaw = await readJson(file);
+    const existingParse = semanticsFileSchema.safeParse(existingRaw);
+    const existing = existingParse.success ? existingParse.data : undefined;
+    if (existingRaw !== undefined && existing === undefined) {
+        options.note("semantics.json is malformed; regenerating it (host edits in the old file are not carried over)");
+    }
+    const inferred = await fetchInferred(options) ?? {};
+    const tools = {};
+    for (const name of toolNames) {
+        const merged = {
+            ...inferred[name],
+            ...existing?.tools[name],
+            ...annotations[name],
+        };
+        if (Object.keys(merged).length > 0)
+            tools[name] = merged;
+    }
+    const next = {
+        format: VENDO_SEMANTICS_FORMAT,
+        note: "Generated by `vendo sync` and safe to edit: field entries are inferred ONCE and your edits are preserved; overrides.json tools[name].semantics wins over everything. `domains` is derived from tool names on first sync and yours afterwards — keep has/hasNot honest, generation treats them as fact.",
+        tools,
+        // First sync derives the positive list; afterwards the manifest is
+        // host-owned (curation survives every sync).
+        domains: existing?.domains ?? { has: deriveDomains(toolNames), hasNot: [] },
+    };
+    const bytes = `${JSON.stringify(next, null, 2)}\n`;
+    try {
+        if (await fs.readFile(file, "utf8") === bytes)
+            return;
+    }
+    catch {
+        // absent — write below
+    }
+    await fs.writeFile(file, bytes, "utf8");
+}

package/dist/cli/shared.d.ts

@@ -0,0 +1,68 @@
+import { type Telemetry } from "@vendoai/telemetry";
+export declare const CLI_VERSION = "0.4.0";
+export interface Output {
+    log(message: string): void;
+    error(message: string): void;
+}
+export declare const consoleOutput: Output;
+export declare function askYesNo(question: string, defaultYes?: boolean): Promise<boolean>;
+export declare function exists(path: string): Promise<boolean>;
+export declare function readOptional(path: string): Promise<string | null>;
+export declare function writeText(path: string, content: string): Promise<void>;
+/** The injectable telemetry deps every CLI command's options carry
+    (init/doctor already ride this exact shape). */
+export interface TelemetryOptions {
+    home?: string;
+    env?: Record<string, string | undefined>;
+    posthogKey?: string;
+    fetchImpl?: typeof fetch;
+    /** The command's TARGET project dir: projectIdHash/packageManager derive
+        from it (not the shell cwd — `vendo sync ../app` must attribute to
+        ../app), and it is where the .env.local cloud-key read looks. Defaults
+        to process.cwd(). */
+    cwd?: string;
+}
+/**
+ * The value of one NAME=value line in `<root>/.env.local`. Matches dotenv
+ * semantics for hand-authored entries: surrounding quotes are stripped, and
+ * unquoted values lose their ` #…` inline comment. Non-throwing: a missing
+ * or unreadable file is null. Sync on purpose — telemetry client creation is
+ * synchronous.
+ */
+export declare function envLocalValueSync(root: string, name: string): string | null;
+/** One value grammar for every CLI dotenv reader (envLocalValueSync, doctor's
+ * readDotEnvFallback): matching surrounding quotes are stripped; unquoted
+ * values lose their ` #…` inline comment. */
+export declare function normalizeDotEnvValue(value: string): string;
+export declare function toolingTelemetry(options?: TelemetryOptions & {
+    log?: (message: string) => void;
+}): Telemetry;
+export declare function errorClass(error: unknown): string;
+/** The closed `command_run.command` enum (TELEMETRY.md). init keeps its own
+    richer events; "theme" is reserved — no `vendo theme` entrypoint exists
+    yet. "login" is the top-level claim ceremony; init's embedded run of the
+    same ceremony stays "cloud-init". */
+export type CommandName = "login" | "extract" | "theme" | "eject" | "playground" | "refine" | "sync" | "cloud-init" | "mcp";
+/** Cloud-lane project identity (projectName + repoHost) for commands that
+    have a target project dir. Anonymous-lane sends strip both keys. */
+export declare function cloudProjectProps(root: string | undefined): Promise<Record<string, unknown>>;
+/**
+ * Run a CLI command body with one `command_run` telemetry row: ok is the
+ * exit code (0 = true), a throw records the error class and rethrows, and a
+ * body can name the step it failed at via the mutable `failure` argument.
+ * The body also receives the telemetry client for extra events (extract's
+ * `extract_completed`). Telemetry NEVER changes command behavior or exit
+ * codes — the client never throws, and this wrapper's own prop assembly is
+ * guarded too.
+ */
+export declare function withCommandRun(input: {
+    command: CommandName;
+    telemetry?: TelemetryOptions;
+    /** Host project dir for the cloud lane's projectName/repoHost; omitted
+        for commands without a target project (playground, mcp). */
+    root?: string;
+}, body: (failure: {
+    failedStep?: string;
+}, telemetry: Telemetry) => Promise<number>): Promise<number>;
+/** Lockfile-derived package manager for `run dev` (doctor's probe starter). */
+export declare function detectPackageManager(root: string): Promise<"pnpm" | "yarn" | "bun" | "npm">;

package/dist/cli/shared.js

@@ -0,0 +1,184 @@
+import { readFileSync } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { initTelemetry, repoHost } from "@vendoai/telemetry";
+export const CLI_VERSION = "0.4.0";
+export const consoleOutput = {
+    log: (message) => console.log(message),
+    error: (message) => console.error(message),
+};
+export async function askYesNo(question, defaultYes = false) {
+    if (!stdin.isTTY || !stdout.isTTY)
+        return false;
+    const prompt = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = (await prompt.question(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+        if (answer === "")
+            return defaultYes;
+        return ["y", "yes"].includes(answer);
+    }
+    finally {
+        prompt.close();
+    }
+}
+export async function exists(path) {
+    return access(path).then(() => true, () => false);
+}
+export async function readOptional(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export async function writeText(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+}
+function noTelemetry() {
+    return { async track() { } };
+}
+/**
+ * The value of one NAME=value line in `<root>/.env.local`. Matches dotenv
+ * semantics for hand-authored entries: surrounding quotes are stripped, and
+ * unquoted values lose their ` #…` inline comment. Non-throwing: a missing
+ * or unreadable file is null. Sync on purpose — telemetry client creation is
+ * synchronous.
+ */
+export function envLocalValueSync(root, name) {
+    try {
+        const raw = readFileSync(join(root, ".env.local"), "utf8");
+        const match = raw.match(new RegExp(`^\\s*${name}\\s*=\\s*(.+?)\\s*$`, "m"));
+        const value = match?.[1];
+        if (value === undefined)
+            return null;
+        return normalizeDotEnvValue(value);
+    }
+    catch {
+        return null;
+    }
+}
+/** One value grammar for every CLI dotenv reader (envLocalValueSync, doctor's
+ * readDotEnvFallback): matching surrounding quotes are stripped; unquoted
+ * values lose their ` #…` inline comment. */
+export function normalizeDotEnvValue(value) {
+    const quoted = value.match(/^(["'])(.*)\1$/);
+    if (quoted?.[2] !== undefined)
+        return quoted[2];
+    return value.replace(/\s+#.*$/, "").trimEnd();
+}
+export function toolingTelemetry(options = {}) {
+    try {
+        let env = options.env ?? process.env;
+        // Cloud-lane key sourcing widens to the project's .env.local — exactly
+        // where `vendo login` / cloud-init / --cloud-key land the key — because
+        // a dev-mode key almost never lives in the process env. Only
+        // VENDO_API_KEY widens: consent vars (DO_NOT_TRACK, CI, …) keep coming
+        // from the caller's env untouched, and an explicit non-blank env value
+        // always wins over .env.local (the same precedence init's credential
+        // merge uses).
+        if ((env.VENDO_API_KEY ?? "").trim() === "") {
+            const stored = envLocalValueSync(options.cwd ?? process.cwd(), "VENDO_API_KEY");
+            if (stored !== null)
+                env = { ...env, VENDO_API_KEY: stored };
+        }
+        return initTelemetry({
+            version: CLI_VERSION,
+            runtime: false,
+            home: options.home,
+            env,
+            cwd: options.cwd,
+            posthogKey: options.posthogKey ?? process.env.VENDO_POSTHOG_KEY,
+            fetchImpl: options.fetchImpl,
+            log: options.log,
+        });
+    }
+    catch {
+        return noTelemetry();
+    }
+}
+export function errorClass(error) {
+    if (error instanceof Error && error.name)
+        return error.name.slice(0, 64);
+    return "unknown";
+}
+/** Cloud-lane project identity (projectName + repoHost) for commands that
+    have a target project dir. Anonymous-lane sends strip both keys. */
+export async function cloudProjectProps(root) {
+    if (root === undefined)
+        return {};
+    const props = {};
+    try {
+        const name = JSON.parse((await readOptional(join(root, "package.json"))) ?? "{}").name;
+        if (typeof name === "string" && name.length > 0)
+            props.projectName = name;
+    }
+    catch {
+        // No usable package.json — the cloud lane just omits projectName.
+    }
+    const forge = repoHost(root);
+    if (forge !== undefined)
+        props.repoHost = forge;
+    return props;
+}
+/**
+ * Run a CLI command body with one `command_run` telemetry row: ok is the
+ * exit code (0 = true), a throw records the error class and rethrows, and a
+ * body can name the step it failed at via the mutable `failure` argument.
+ * The body also receives the telemetry client for extra events (extract's
+ * `extract_completed`). Telemetry NEVER changes command behavior or exit
+ * codes — the client never throws, and this wrapper's own prop assembly is
+ * guarded too.
+ */
+export async function withCommandRun(input, body) {
+    const started = Date.now();
+    // The first-run notice keeps its console.error default — several wrapped
+    // commands (sync --json, mcp server-json) own their stdout byte-for-byte.
+    // The target root rides in as the client's cwd so projectIdHash and the
+    // .env.local cloud-key read attribute to the project being operated on,
+    // not the shell cwd (an explicit seam cwd still wins).
+    const telemetry = toolingTelemetry({
+        ...(input.root === undefined ? {} : { cwd: input.root }),
+        ...(input.telemetry ?? {}),
+    });
+    const failure = {};
+    const track = async (ok, thrown) => {
+        try {
+            await telemetry.track("command_run", {
+                command: input.command,
+                ok,
+                durationMs: Date.now() - started,
+                ...(failure.failedStep === undefined ? {} : { failedStep: failure.failedStep }),
+                ...(thrown === undefined ? {} : { errorClass: errorClass(thrown.error) }),
+                ...(await cloudProjectProps(input.root)),
+            });
+        }
+        catch {
+            // Telemetry must never break a command. Intentional silent failure.
+        }
+    };
+    try {
+        const exit = await body(failure, telemetry);
+        await track(exit === 0);
+        return exit;
+    }
+    catch (error) {
+        await track(false, { error });
+        throw error;
+    }
+}
+/** Lockfile-derived package manager for `run dev` (doctor's probe starter). */
+export async function detectPackageManager(root) {
+    if (await exists(join(root, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (await exists(join(root, "yarn.lock")))
+        return "yarn";
+    if (await exists(join(root, "bun.lockb")) || await exists(join(root, "bun.lock")))
+        return "bun";
+    return "npm";
+}

package/dist/cli/sync.d.ts

@@ -0,0 +1,36 @@
+import { vendoSync, type SyncReportWithWarnings } from "@vendoai/actions";
+import type { ToolImpact } from "../sync-impact.js";
+import { type Output, type TelemetryOptions } from "./shared.js";
+export interface SyncReportPayload {
+    report: SyncReportWithWarnings;
+    impact?: ToolImpact[];
+    at: string;
+}
+export interface SyncOptions {
+    targetDir: string;
+    strict?: boolean;
+    output?: Output;
+    sync?: typeof vendoSync;
+    url?: string;
+    fetchImpl?: typeof fetch;
+    report?: boolean;
+    push?: (report: SyncReportPayload) => Promise<void>;
+    apiKey?: string;
+    apiUrl?: string;
+    json?: boolean;
+    /** Injectable telemetry deps (matches init/doctor). */
+    telemetry?: TelemetryOptions;
+}
+/** `sync --json` — the one machine-readable object printed on stdout. */
+export interface SyncJsonResult {
+    ok: boolean;
+    exitCode: 0 | 2 | 3;
+    report: SyncReportWithWarnings;
+    /** [] = nothing referenced the changed tools; null = impact unknown (dev server unreachable). */
+    impact: ToolImpact[] | null;
+    /** CLI-level events not carried by the report (unreachable impact endpoint, report-push problems). */
+    notes: string[];
+    error?: string;
+}
+/** 04-actions §1 / 09-vendo §5 — fail-soft extraction, strict CI gate. */
+export declare function runSync(options: SyncOptions): Promise<number>;