@vendoai/vendo 0.4.0

package/dist/cli/extract/stages.js

@@ -0,0 +1,398 @@
+import { join } from "node:path";
+import { rm } from "node:fs/promises";
+import { z } from "zod";
+import { draftToolSchema, parseArtifact, } from "./harness.js";
+import { readOptional, writeText } from "../shared.js";
+import { BRAND_SLOTS, modelThemeSchema } from "../theme/extract-theme.js";
+/**
+ * The staged extraction pipeline (install-dx, PostHog lesson: narrow stages
+ * beat one-shot). Four required passes plus one optional pass, all over the
+ * SAME harness seam — each is one `harness.run(instructions)` with its own
+ * narrow instructions and its own zod-validated artifact, written to
+ * `.vendo/data/extract/<stage>.json` so a failed run is diagnosable stage by
+ * stage:
+ *
+ * 1. survey — map the repo: frameworks, where the API surfaces live, and a
+ *    grouping of the static tool list into surfaces (cheap/fast; respects a
+ *    VENDO_EXTRACTION_SURVEY_MODEL override).
+ * 2. draft — one focused pass per surface, drafting judgment for just that
+ *    surface's tools. Surfaces run sequentially (rate-limit friendly); a
+ *    failed surface is SKIPPED with an honest note, never aborting the run.
+ * 3. cross-check — one pass over the combined draft for naming consistency,
+ *    duplicate coverage, and risk sanity. It may only AMEND entries within
+ *    the same schema (unknown names ignored, omitted entries stand); a
+ *    failure degrades to the uncross-checked drafts.
+ * 4. brief — drafted from what the survey and drafts learned; a failure
+ *    keeps the current brief.
+ * 5. theme — OPTIONAL, only when the caller supplies `theme` input and the
+ *    allowlist left brand slots unfilled: fills those slots the same way the
+ *    old theme model pass did, but over this harness seam (Read/Glob/Grep the
+ *    repo instead of a fixed evidence-file set). A failure degrades to a note
+ *    — the exact reads and neutral defaults still stand.
+ *
+ * The combined output feeds the EXISTING applyDraft guards in extraction.ts
+ * unchanged — deterministic verification stays the single gate. Nothing here
+ * assumes a vendor; the model override rides VENDO_EXTRACTION_MODEL, which
+ * every harness already honors.
+ */
+export const BRIEF_TEMPLATE = "Describe this product, its users, and the jobs the agent should help them complete.";
+/** Static facts don't clutter passes that only need names — kept small. */
+export const staticToolSchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    risk: z.enum(["read", "write", "destructive"]).optional(),
+    disabled: z.boolean().optional(),
+    method: z.string().optional(),
+    path: z.string().optional(),
+});
+export const surveySchema = z.object({
+    /** Frameworks/routers the surveyor identified (context for later stages). */
+    frameworks: z.array(z.string().max(120)).optional(),
+    surfaces: z.array(z.object({
+        name: z.string().min(1).max(80),
+        /** One line on where the surface lives in the code. */
+        note: z.string().max(300).optional(),
+        tools: z.array(z.string().min(1)),
+    })).min(1),
+});
+/** Draft and cross-check share one schema: the cross-check may only AMEND
+ *  the draft within it. */
+const surfaceDraftSchema = z.object({
+    tools: z.array(draftToolSchema),
+    missedSurfaces: z.array(z.string().max(300)).optional(),
+});
+const briefSchema = z.object({
+    brief: z.string().min(1).max(4000),
+});
+/** More surfaces than this get their tail merged into one pass — a runaway
+ *  survey must not turn into a runaway number of model calls. */
+const MAX_SURFACES = 12;
+export function staticFacts(tools) {
+    return JSON.stringify(tools.map((tool) => ({
+        name: tool.name,
+        ...(tool.method === undefined ? {} : { method: tool.method }),
+        ...(tool.path === undefined ? {} : { path: tool.path }),
+        risk: tool.risk,
+        ...(tool.disabled === true ? { disabled: true } : {}),
+        description: tool.description,
+    })), null, 2);
+}
+function composeSurveyInstructions(tools, appName) {
+    return [
+        "You are Vendo's extraction surveyor. Map this repo (Read/Glob/Grep only) so later",
+        "focused passes can draft tool documentation surface by surface.",
+        "",
+        `Product/package name: ${appName}`,
+        "Statically extracted tools (name, method+path when known):",
+        JSON.stringify(tools.map((tool) => ({
+            name: tool.name,
+            ...(tool.method === undefined ? {} : { method: tool.method }),
+            ...(tool.path === undefined ? {} : { path: tool.path }),
+        })), null, 2),
+        "",
+        "Rules:",
+        "- Reply with ONLY one fenced json block matching:",
+        '  { "frameworks"?: string[], "surfaces": [{ "name", "note"?, "tools": string[] }] }',
+        "- surfaces: group EVERY tool above into a small number of product surfaces (billing,",
+        "  auth, admin, …) by reading where their routes live. Each tool name appears in exactly",
+        "  one surface; use only names from the list.",
+        "- name: a short surface label. note: one line on where the surface lives in the code.",
+        "- frameworks: the frameworks/routers you identified.",
+        "- Survey only — do not draft descriptions or risk grades here.",
+    ].join("\n");
+}
+export function composeInstructions(tools, appName, surface) {
+    return [
+        "You are Vendo's extraction agent. Read this codebase (Read/Glob/Grep only) and return",
+        surface === undefined
+            ? "judgment on the API tools a static extractor already found."
+            : `judgment on the API tools a static extractor already found, focusing ONLY on the "${surface.name}" surface.`,
+        "",
+        `Product/package name: ${appName}`,
+        ...(surface?.note === undefined ? [] : [`Where this surface lives: ${surface.note}`]),
+        "Statically extracted tools (name, method+path when known, current risk, disabled state):",
+        staticFacts(tools),
+        "",
+        "Rules:",
+        "- Reply with ONLY one fenced json block matching:",
+        '  { "tools": [{ "name", "description", "risk"?, "critical"?, "disabled"?, "reasoning"? }], "missedSurfaces"?: string[] }',
+        "- tools: include ONLY names from the list above. Rewrite each description so an agent choosing tools understands what it actually does (read the handler source). <= 200 chars each.",
+        "- risk: you may RAISE risk (read->write->destructive) when the handler is more dangerous than labeled; never lower it. Mark irreversible operations critical: true.",
+        "- A tool listed as disabled was statically unclassifiable. If you can read its handler and grade it, set disabled: false WITH a risk and one-line reasoning. Leave it out otherwise.",
+        "- missedSurfaces: API surfaces you found that the list is missing (path + one line). Do not invent tools for them.",
+    ].join("\n");
+}
+function composeCrossCheckInstructions(drafted, tools, appName) {
+    return [
+        "You are Vendo's extraction cross-checker. Focused passes drafted judgment surface by",
+        "surface; review the COMBINED draft for naming consistency, duplicate coverage, and",
+        "risk sanity.",
+        "",
+        `Product/package name: ${appName}`,
+        "Combined draft:",
+        JSON.stringify(drafted, null, 2),
+        "Static facts for the same tools:",
+        staticFacts(tools),
+        "",
+        "Rules:",
+        "- Reply with ONLY one fenced json block matching:",
+        '  { "tools": [{ "name", "description", "risk"?, "critical"?, "disabled"?, "reasoning"? }] }',
+        "- Return ONLY the entries you want to AMEND. Entries you omit stand as drafted; you cannot remove a tool. Use only names from the combined draft.",
+        "- Same rules as drafting: risk may be RAISED, never lowered; mark irreversible operations critical: true.",
+    ].join("\n");
+}
+function composeBriefInstructions(input) {
+    return [
+        "You are Vendo's extraction agent, drafting the product brief. A survey and per-surface",
+        "drafting passes already ran; build on what they learned plus the code itself.",
+        "",
+        `Product/package name: ${input.appName}`,
+        ...(input.survey === null ? [] : [
+            "Surveyed surfaces:",
+            JSON.stringify(input.survey.surfaces.map(({ name, note }) => ({ name, ...(note === undefined ? {} : { note }) })), null, 2),
+        ]),
+        "Drafted tools (name + description):",
+        JSON.stringify(input.drafted.map(({ name, description }) => ({ name, description })), null, 2),
+        "",
+        "Rules:",
+        '- Reply with ONLY one fenced json block matching: { "brief": string }',
+        "- brief: one paragraph — what the product does, who uses it, the jobs the agent should help with. Written from the actual code, no marketing fluff.",
+    ].join("\n");
+}
+/**
+ * Instructions for the OPTIONAL theme stage — the SOLE copy of the theme
+ * judgment rules (extract-theme.ts's old model pass and its prompt were
+ * deleted when the deterministic split landed; that file now owns only the
+ * exact pass, validators, and assembly).
+ */
+export function composeThemeInstructions(input) {
+    return [
+        "You are Vendo's extraction agent, filling the theme's brand slots. Read this codebase",
+        "(Read/Glob/Grep — not just the hints below) to fill the brand theme slots a deterministic",
+        "allowlist pass could not read exactly.",
+        "",
+        "Slots: accent (the brand's primary interactive color), accentText (text on accent),",
+        "background (page), surface (cards/panels), text (body), mutedText (secondary text),",
+        "border (default hairline), danger (destructive/error), radius (default control corner",
+        "radius, canonical px), fontFamily (body stack), headingFamily (heading stack, only if",
+        "distinct), baseSize (body font size, px), density (compact|comfortable), motion (full|reduced).",
+        "",
+        `Product/package name: ${input.appName}`,
+        "Needed slots:",
+        JSON.stringify(input.needed, null, 2),
+        "Already exact (context — do not re-derive these):",
+        JSON.stringify(input.alreadyExact, null, 2),
+        "Evidence files found so far (starting hints — read more of the repo if useful):",
+        JSON.stringify(input.evidencePaths, null, 2),
+        "",
+        "Rules:",
+        "- Reply with ONLY one fenced json block matching:",
+        '  { "slots": { <slot>: string, ... }, "uncertain"?: [{ "slot", "note" }] }',
+        "- Fill ONLY the needed slots above, ONLY from evidence in the codebase.",
+        "- Colors must be 6-digit hex. Resolve CSS variables and color functions yourself.",
+        "- next/font: the imported font's export name is the family (underscores become spaces).",
+        "- The geist npm package's GeistSans/GeistMono imports are font sources exactly like next/font.",
+        "- fontFamily is the BODY font: the Tailwind `sans`/default fontFamily key. A `display` face",
+        "  goes to headingFamily, never fontFamily.",
+        "- A design-token sheet outranks scattered utility classes; dominant usage outranks one-offs.",
+        "- When several tokens could fill the same slot (e.g. multiple muted/soft/faint text inks),",
+        "  COUNT their usages across the sheets and pick the dominant one; if you did not count or",
+        "  the counts are close, still fill the slot with your best pick AND list it in uncertain.",
+        "- Status/state colors (success, positive, negative, warning, error, overdue, verified,",
+        "  and colors a comment demotes to data/status-only) are NEVER the brand accent.",
+        "- Monochrome brands exist: when the sheet declares no saturated non-status brand color,",
+        "  the ink/text color itself is the accent (primary buttons are painted with it).",
+        "- radius is the default CONTROL radius (buttons/inputs); a token named for cards or",
+        "  popovers rounds cards, which are typically larger than controls.",
+        "- An accessibility-only prefers-reduced-motion override does NOT make the brand 'reduced'.",
+        "- Omit any slot the codebase does not evidence. Do not invent plausible values.",
+        "- List a slot in `uncertain` ONLY when the codebase genuinely supports multiple different",
+        "  answers (a real fork, e.g. two plausible brand colors). A value settled by the rules",
+        "  above — monochrome accent, contrast-derived accentText, single-font inheritance,",
+        "  browser-default sizing — is NOT uncertain.",
+    ].join("\n");
+}
+function slugify(name, taken) {
+    const base = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "surface";
+    let slug = base;
+    for (let suffix = 2; taken.has(slug); suffix += 1)
+        slug = `${base}-${suffix}`;
+    taken.add(slug);
+    return slug;
+}
+/** Deterministic normalization of the survey grouping: unknown names are
+ *  dropped, a tool claimed twice keeps its first surface, unassigned tools
+ *  land in a catch-all pass, and a runaway surface count is merged down. The
+ *  drafting stage always covers EVERY static tool exactly once. */
+export function normalizeSurfaces(survey, tools, notes) {
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    const assigned = new Set();
+    const surfaces = [];
+    for (const surface of survey?.surfaces ?? []) {
+        const members = [];
+        for (const name of surface.tools) {
+            const fact = byName.get(name);
+            if (fact === undefined) {
+                notes.push(`survey: unknown tool "${name}" in surface "${surface.name}" ignored`);
+                continue;
+            }
+            if (assigned.has(name))
+                continue;
+            assigned.add(name);
+            members.push(fact);
+        }
+        if (members.length > 0) {
+            surfaces.push({ name: surface.name, ...(surface.note === undefined ? {} : { note: surface.note }), tools: members });
+        }
+    }
+    const unassigned = tools.filter((tool) => !assigned.has(tool.name));
+    if (unassigned.length > 0) {
+        if (surfaces.length > 0) {
+            notes.push(`survey left ${unassigned.length} tools unassigned — drafting them as "everything else"`);
+        }
+        surfaces.push({ name: surfaces.length > 0 ? "everything else" : "all tools", tools: unassigned });
+    }
+    if (surfaces.length > MAX_SURFACES) {
+        const tail = surfaces.splice(MAX_SURFACES - 1);
+        surfaces.push({ name: "everything else", tools: tail.flatMap((surface) => surface.tools) });
+        notes.push(`survey produced ${MAX_SURFACES - 1 + tail.length} surfaces — merged the tail into one pass`);
+    }
+    const taken = new Set();
+    return surfaces.map((surface) => ({ ...surface, slug: slugify(surface.name, taken) }));
+}
+function message(error) {
+    return error instanceof Error ? error.message : "unknown error";
+}
+/** Orchestrate the staged pipeline. Throws only when no stage produced
+ *  anything usable (the error names the failed stage); partial failures
+ *  degrade with notes instead. */
+export async function runStagedExtraction(input) {
+    const { root, env, harness, tools, appName, onProgress } = input;
+    const artifactDir = join(root, ".vendo", "data", "extract");
+    await rm(artifactDir, { recursive: true, force: true });
+    const notes = [];
+    async function runStage(stage, instructions, schema, stageEnv) {
+        let text = null;
+        try {
+            text = await harness.run({ root, env: stageEnv, instructions, ...(onProgress === undefined ? {} : { onProgress }) });
+            const artifact = parseArtifact(text, schema);
+            await writeText(join(artifactDir, `${stage}.json`), `${JSON.stringify(artifact, null, 2)}\n`);
+            return artifact;
+        }
+        catch (error) {
+            await writeText(join(artifactDir, `${stage}.json`), `${JSON.stringify({ stage, error: message(error), ...(text === null ? {} : { raw: text }) }, null, 2)}\n`);
+            throw error;
+        }
+    }
+    // Survey: cheap repo map; an override can point it at a faster model. A
+    // failed survey degrades to drafting everything as one surface (= v1).
+    const surveyModel = env["VENDO_EXTRACTION_SURVEY_MODEL"];
+    let survey = null;
+    onProgress?.("survey: mapping API surfaces");
+    try {
+        survey = await runStage("survey", composeSurveyInstructions(tools, appName), surveySchema, surveyModel === undefined ? env : { ...env, VENDO_EXTRACTION_MODEL: surveyModel });
+    }
+    catch (error) {
+        notes.push(`survey stage failed (${message(error)}) — drafting all ${tools.length} tools as one surface`);
+    }
+    const surfaces = normalizeSurfaces(survey, tools, notes);
+    // Draft per surface, sequentially. A failed surface is skipped, not fatal —
+    // unless EVERY surface failed, which means the harness itself is broken.
+    const drafted = new Map();
+    const missedSurfaces = [];
+    let failures = 0;
+    let lastError = "";
+    for (const surface of surfaces) {
+        onProgress?.(`drafting "${surface.name}" (${surface.tools.length} tools)`);
+        try {
+            const artifact = await runStage(`draft.${surface.slug}`, composeInstructions(surface.tools, appName, surface), surfaceDraftSchema, env);
+            // A focused pass may only draft its own surface's tools — an
+            // out-of-surface entry would defeat the containment story (a skipped
+            // surface must actually keep extractor defaults).
+            const members = new Set(surface.tools.map((tool) => tool.name));
+            for (const entry of artifact.tools) {
+                if (!members.has(entry.name)) {
+                    notes.push(`surface "${surface.name}": draft for out-of-surface tool "${entry.name}" ignored`);
+                    continue;
+                }
+                drafted.set(entry.name, entry);
+            }
+            missedSurfaces.push(...(artifact.missedSurfaces ?? []));
+        }
+        catch (error) {
+            failures += 1;
+            lastError = message(error);
+            notes.push(`surface "${surface.name}" skipped (${lastError}) — its ${surface.tools.length} tools keep extractor defaults`);
+        }
+    }
+    if (surfaces.length > 0 && failures === surfaces.length) {
+        throw new Error(`draft stage failed for every surface (${lastError})`);
+    }
+    // Cross-check: amendments only, within the draft schema. applyDraft remains
+    // the gate — an amendment can no more downgrade risk than a draft can.
+    if (drafted.size > 0) {
+        onProgress?.("cross-check: consistency pass over the combined draft");
+        try {
+            const artifact = await runStage("cross-check", composeCrossCheckInstructions([...drafted.values()], tools, appName), surfaceDraftSchema, env);
+            for (const amendment of artifact.tools) {
+                const existing = drafted.get(amendment.name);
+                if (existing === undefined) {
+                    notes.push(`cross-check: amendment for undrafted tool "${amendment.name}" ignored`);
+                    continue;
+                }
+                // Merge, never replace: a description-only amendment must not drop
+                // the risk/critical/wake judgment the focused pass produced.
+                drafted.set(amendment.name, { ...existing, ...amendment });
+            }
+        }
+        catch (error) {
+            notes.push(`cross-check stage failed (${message(error)}) — using the uncross-checked drafts`);
+        }
+    }
+    // Brief: drafted from what the earlier stages learned; on failure the
+    // current brief stands (applyDraft's hand-written-brief guard still wins).
+    let brief = null;
+    onProgress?.("brief: drafting the product brief");
+    try {
+        brief = (await runStage("brief", composeBriefInstructions({ appName, survey, drafted: [...drafted.values()] }), briefSchema, env)).brief;
+    }
+    catch (error) {
+        notes.push(`brief stage failed (${message(error)}) — keeping the current brief`);
+    }
+    const briefFromStage = brief !== null;
+    if (brief === null) {
+        const current = ((await readOptional(join(root, ".vendo", "brief.md"))) ?? "").trim();
+        brief = current === "" ? BRIEF_TEMPLATE : current;
+    }
+    // Theme: OPTIONAL, and only when the allowlist left brand slots unfilled —
+    // the non-brand slots (accentText, headingFamily, baseSize, density,
+    // motion) derive or default safely and must never trigger this stage on
+    // their own.
+    let theme;
+    const themeInput = input.theme;
+    if (themeInput !== undefined) {
+        const brandNeeded = themeInput.needed.filter((slot) => BRAND_SLOTS.includes(slot));
+        if (brandNeeded.length > 0) {
+            onProgress?.("theme: filling brand slots");
+            try {
+                theme = await runStage("theme", composeThemeInstructions({
+                    needed: themeInput.needed,
+                    alreadyExact: themeInput.alreadyExact,
+                    evidencePaths: themeInput.evidencePaths,
+                    appName,
+                }), modelThemeSchema, env);
+            }
+            catch (error) {
+                notes.push(`theme stage failed (${message(error)}) — exact reads and defaults stand`);
+            }
+        }
+    }
+    const missed = [...new Set(missedSurfaces)];
+    const draft = {
+        brief,
+        tools: [...drafted.values()],
+        ...(missed.length === 0 ? {} : { missedSurfaces: missed }),
+    };
+    await writeText(join(artifactDir, "draft.json"), `${JSON.stringify(draft, null, 2)}\n`);
+    return { draft, notes, briefFromStage, ...(theme === undefined ? {} : { theme }) };
+}

package/dist/cli/framework.d.ts

@@ -0,0 +1,8 @@
+export type HostFramework = "next" | "express" | "unknown";
+export interface VendoWiring {
+    server: boolean;
+    client: boolean;
+}
+export declare function detectFramework(root: string): Promise<HostFramework>;
+/** Bounded source scan shared by init and doctor so their wiring verdicts agree. */
+export declare function detectVendoWiring(root: string): Promise<VendoWiring>;

package/dist/cli/framework.js

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { walk } from "./theme/walk.js";
+const SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/;
+const SOURCE_SCAN_MAX_FILES = 2_000;
+export async function detectFramework(root) {
+    try {
+        const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+        const sections = [manifest.dependencies, manifest.devDependencies];
+        if (sections.some((dependencies) => dependencies?.next !== undefined))
+            return "next";
+        if (sections.some((dependencies) => dependencies?.express !== undefined))
+            return "express";
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Bounded source scan shared by init and doctor so their wiring verdicts agree. */
+export async function detectVendoWiring(root) {
+    let server = false;
+    let client = false;
+    const files = await walk(root, (relativePath) => SOURCE_FILE.test(relativePath), SOURCE_SCAN_MAX_FILES);
+    for (const file of files) {
+        const source = await readFile(file, "utf8").catch(() => "");
+        const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+        if (code.includes("@vendoai/vendo/server") && /\bcreateVendo\s*\(/.test(code))
+            server = true;
+        if (code.includes("<VendoRoot"))
+            client = true;
+        if (server && client)
+            break;
+    }
+    return { server, client };
+}

package/dist/cli/init-auth.d.ts

@@ -0,0 +1,67 @@
+import type { SelectOption } from "./pretty.js";
+/** The auth families init detects in package.json (09-vendo §2.1). */
+export type AuthPresetName = "authJs" | "clerk" | "supabase" | "auth0";
+/** Each zero-arg preset function ships on its own subpath — not
+    `@vendoai/vendo/server` — so importing one preset never resolves the
+    others' optional peer deps (corpus-triage Task 9: a shared barrel meant
+    ANY host importing the server entry statically re-resolved every
+    preset's optional peer, e.g. @auth/core, even unused). Scaffolded code
+    imports the preset from here and createVendo/nextVendoHandler from
+    "@vendoai/vendo/server" separately. */
+export declare const AUTH_PRESET_SPECIFIER: Record<AuthPresetName, string>;
+export interface AuthMatch {
+    preset: AuthPresetName;
+    dependency: string;
+    /** How the family was chosen: detection (default) cites the dependency it
+        found; a picker pick says so honestly — nothing was detected. */
+    source?: "picked";
+}
+export interface AuthDetection {
+    /** Exactly one family matched — the preset init wires silently. */
+    wired: AuthMatch | null;
+    /** Every family that matched (for the ambiguity advisory). */
+    matches: AuthMatch[];
+}
+export declare const AUTH_FAMILIES: ReadonlyArray<{
+    preset: AuthPresetName;
+    test: (dependency: string) => boolean;
+}>;
+/** Silent auth-preset detection from the host's package.json (zero-question
+    contract): one unambiguous family gets wired; none or several stay
+    anonymous and become one advisory line (detection-as-advice). */
+export declare function detectAuthPreset(root: string): Promise<AuthDetection>;
+/** The one calm auth line for the none/ambiguous cases — names the exact
+    line to add, never asks a question. Emitted only when init scaffolds the
+    composition (a hand-wired host may already have auth). */
+export declare function authAdvisory(detection: AuthDetection, compositionPath: string): string | null;
+/** The declined-confirm advisory: anonymous composition, exact line in hand. */
+export declare function declinedAuthAdvisory(match: AuthMatch, compositionPath: string): string;
+export type ConfirmAuth = (question: string, defaultYes: boolean) => Promise<boolean>;
+export type SelectAuth = (question: string, options: SelectOption[]) => Promise<string>;
+/** Picker labels + the runtime package each zero-arg preset lazy-loads (the
+    install hint when the picked family's SDK is absent; the preset's own
+    lazy-load error already guards runtime). */
+export declare const AUTH_FAMILY_INFO: Record<AuthPresetName, {
+    name: string;
+    label: string;
+    runtime: string;
+}>;
+/** The auth picker (decline or ambiguity): none — stay anonymous — is first
+    and the default; detected families come next (named), then the remaining
+    zero-arg presets, then jwt (recipe only — it cannot be zero-arg). */
+export declare function pickScaffoldAuth(detection: AuthDetection, compositionPath: string, selectAuth: SelectAuth): Promise<{
+    wired: AuthMatch | null;
+    advice: string | null;
+}>;
+/** Detect + confirm + choose: in interactive runs, exactly one detected
+    family gets ONE calm [Y/n] question before anything is written (Enter
+    accepts and wires it — no picker on the happy path). A decline — and the
+    ambiguous case (several families) — offers the picker instead of settling
+    for anonymous. Without the seams (non-interactive, --yes, --agent) silent
+    detection stands and none/ambiguous keep the advisory line — a default
+    has to exist. None-detected never asks: there is nothing to choose from
+    that the advisory doesn't already name. */
+export declare function resolveScaffoldAuth(root: string, compositionPath: string, authAnswer: AuthPresetName | "jwt" | "none" | undefined, confirmAuth: ConfirmAuth | undefined, selectAuth: SelectAuth | undefined): Promise<{
+    wired: AuthMatch | null;
+    advice: string | null;
+}>;

package/dist/cli/init-auth.js

@@ -0,0 +1,142 @@
+import { join } from "node:path";
+import { readOptional } from "./shared.js";
+/** Each zero-arg preset function ships on its own subpath — not
+    `@vendoai/vendo/server` — so importing one preset never resolves the
+    others' optional peer deps (corpus-triage Task 9: a shared barrel meant
+    ANY host importing the server entry statically re-resolved every
+    preset's optional peer, e.g. @auth/core, even unused). Scaffolded code
+    imports the preset from here and createVendo/nextVendoHandler from
+    "@vendoai/vendo/server" separately. */
+export const AUTH_PRESET_SPECIFIER = {
+    authJs: "@vendoai/vendo/auth/auth-js",
+    clerk: "@vendoai/vendo/auth/clerk",
+    supabase: "@vendoai/vendo/auth/supabase",
+    auth0: "@vendoai/vendo/auth/auth0",
+};
+export const AUTH_FAMILIES = [
+    { preset: "authJs", test: (dependency) => dependency === "next-auth" || dependency.startsWith("@auth/") },
+    { preset: "clerk", test: (dependency) => dependency.startsWith("@clerk/") },
+    { preset: "supabase", test: (dependency) => dependency.startsWith("@supabase/") },
+    { preset: "auth0", test: (dependency) => dependency.startsWith("@auth0/") },
+];
+/** Silent auth-preset detection from the host's package.json (zero-question
+    contract): one unambiguous family gets wired; none or several stay
+    anonymous and become one advisory line (detection-as-advice). */
+export async function detectAuthPreset(root) {
+    let dependencies = [];
+    try {
+        const manifest = JSON.parse((await readOptional(join(root, "package.json"))) ?? "{}");
+        dependencies = Object.keys({ ...manifest.dependencies, ...manifest.devDependencies });
+    }
+    catch {
+        // No readable manifest — nothing to detect; anonymous is the safe default.
+    }
+    const matches = AUTH_FAMILIES.flatMap(({ preset, test }) => {
+        const dependency = dependencies.find(test);
+        return dependency === undefined ? [] : [{ preset, dependency }];
+    });
+    return { wired: matches.length === 1 ? matches[0] : null, matches };
+}
+/** The one calm auth line for the none/ambiguous cases — names the exact
+    line to add, never asks a question. Emitted only when init scaffolds the
+    composition (a hand-wired host may already have auth). */
+export function authAdvisory(detection, compositionPath) {
+    if (detection.wired !== null)
+        return null;
+    if (detection.matches.length === 0) {
+        return `Auth: no provider detected — sessions stay anonymous. When you add one, add one line in ${compositionPath}: ` +
+            `auth: authJs() (Auth.js), clerk(), supabase(), auth0(), or jwt({ secret }).`;
+    }
+    const names = detection.matches.map((match) => match.dependency).join(", ");
+    const calls = detection.matches.map((match) => `auth: ${match.preset}()`).join(" or ");
+    return `Auth: several providers detected (${names}) — staying anonymous rather than guessing. Add one line in ${compositionPath}: ${calls}.`;
+}
+/** The declined-confirm advisory: anonymous composition, exact line in hand. */
+export function declinedAuthAdvisory(match, compositionPath) {
+    return `Auth: left anonymous. To wire ${match.dependency} later, add one line in ${compositionPath}: auth: ${match.preset}().`;
+}
+/** Picker labels + the runtime package each zero-arg preset lazy-loads (the
+    install hint when the picked family's SDK is absent; the preset's own
+    lazy-load error already guards runtime). */
+export const AUTH_FAMILY_INFO = {
+    authJs: { name: "Auth.js", label: "authJs() — Auth.js / next-auth", runtime: "@auth/core" },
+    clerk: { name: "Clerk", label: "clerk() — Clerk", runtime: "@clerk/backend" },
+    supabase: { name: "Supabase Auth", label: "supabase() — Supabase Auth", runtime: "jose" },
+    auth0: { name: "Auth0", label: "auth0() — Auth0", runtime: "jose" },
+};
+/** The auth picker (decline or ambiguity): none — stay anonymous — is first
+    and the default; detected families come next (named), then the remaining
+    zero-arg presets, then jwt (recipe only — it cannot be zero-arg). */
+export async function pickScaffoldAuth(detection, compositionPath, selectAuth) {
+    const detected = detection.matches;
+    const undetected = Object.keys(AUTH_FAMILY_INFO)
+        .filter((preset) => !detected.some((match) => match.preset === preset));
+    const picked = await selectAuth("Which auth should Vendo wire?", [
+        { value: "none", label: "none — stay anonymous, add it later" },
+        ...detected.map((match) => ({
+            value: match.preset,
+            label: AUTH_FAMILY_INFO[match.preset].label,
+            hint: `detected ${match.dependency}`,
+        })),
+        ...undetected.map((preset) => ({ value: preset, label: AUTH_FAMILY_INFO[preset].label })),
+        { value: "jwt", label: "jwt — my own JWT scheme (prints the recipe)" },
+    ]);
+    if (picked === "jwt") {
+        // jwt() cannot be zero-arg — nothing is wired; the recipe is the answer.
+        return {
+            wired: null,
+            advice: `Auth: your own JWT — add one line in ${compositionPath}: auth: jwt({ secret: <your signing secret> }). ` +
+                "Options and the claim mapping: docs/act-as-presets.md.",
+        };
+    }
+    const detectedMatch = detected.find((match) => match.preset === picked);
+    if (detectedMatch !== undefined)
+        return { wired: detectedMatch, advice: null };
+    if (picked in AUTH_FAMILY_INFO) {
+        // Picked without its SDK in package.json: wire it exactly like a
+        // detection-accept, plus one install hint.
+        const preset = picked;
+        const info = AUTH_FAMILY_INFO[preset];
+        return {
+            wired: { preset, dependency: info.runtime, source: "picked" },
+            advice: `Auth: ${preset}() wired — ${info.runtime} is not in package.json yet; install it ` +
+                `(npm install ${info.runtime}) before the first authenticated run (the preset fails loud until then).`,
+        };
+    }
+    // none (or anything unrecognized): today's decline behavior.
+    return detection.wired !== null
+        ? { wired: null, advice: declinedAuthAdvisory(detection.wired, compositionPath) }
+        : { wired: null, advice: authAdvisory(detection, compositionPath) };
+}
+/** Detect + confirm + choose: in interactive runs, exactly one detected
+    family gets ONE calm [Y/n] question before anything is written (Enter
+    accepts and wires it — no picker on the happy path). A decline — and the
+    ambiguous case (several families) — offers the picker instead of settling
+    for anonymous. Without the seams (non-interactive, --yes, --agent) silent
+    detection stands and none/ambiguous keep the advisory line — a default
+    has to exist. None-detected never asks: there is nothing to choose from
+    that the advisory doesn't already name. */
+export async function resolveScaffoldAuth(root, compositionPath, authAnswer, confirmAuth, selectAuth) {
+    const detection = await detectAuthPreset(root);
+    // --auth answers the confirm AND the picker in one flag: route it through
+    // the picker path so a flag answer and an interactive pick wire identically
+    // (detection-accept, install hint, jwt recipe, none advisory).
+    if (authAnswer !== undefined) {
+        return pickScaffoldAuth(detection, compositionPath, async () => authAnswer);
+    }
+    if (confirmAuth === undefined) {
+        return { wired: detection.wired, advice: authAdvisory(detection, compositionPath) };
+    }
+    if (detection.wired !== null) {
+        const accepted = await confirmAuth(`Detected ${detection.wired.dependency} — wire auth: ${detection.wired.preset}()?`, true);
+        if (accepted)
+            return { wired: detection.wired, advice: null };
+        if (selectAuth !== undefined)
+            return pickScaffoldAuth(detection, compositionPath, selectAuth);
+        return { wired: null, advice: declinedAuthAdvisory(detection.wired, compositionPath) };
+    }
+    if (detection.matches.length > 1 && selectAuth !== undefined) {
+        return pickScaffoldAuth(detection, compositionPath, selectAuth);
+    }
+    return { wired: null, advice: authAdvisory(detection, compositionPath) };
+}