@devinnn/docdrift 0.1.2 → 0.1.4

package/dist/src/index.js

@@ -1,9 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STATE_PATH = void 0;
+exports.runSetup = exports.STATE_PATH = void 0;
 exports.runDetect = runDetect;
 exports.runDocDrift = runDocDrift;
 exports.runValidate = runValidate;
@@ -12,6 +45,7 @@ exports.runStatus = runStatus;
 exports.resolveTrigger = resolveTrigger;
 exports.parseDurationHours = parseDurationHours;
 exports.requireSha = requireSha;
+exports.resolveBaseHead = resolveBaseHead;
 const node_path_1 = __importDefault(require("node:path"));
 const load_1 = require("./config/load");
 const validate_1 = require("./config/validate");
@@ -60,6 +94,9 @@ async function executeSessionSingle(input) {
         aggregated: input.aggregated,
         config: input.config,
         attachmentUrls,
+        runGate: input.runGate,
+        trigger: input.trigger,
+        prNumber: input.prNumber,
     });
     const session = await (0, v1_1.devinCreateSession)(input.apiKey, {
         prompt,
@@ -123,14 +160,15 @@ async function runDetect(options) {
     }
     const repo = process.env.GITHUB_REPOSITORY ?? "local/docdrift";
     const normalized = (0, load_1.loadNormalizedConfig)();
-    const { report, hasOpenApiDrift } = await (0, detect_1.buildDriftReport)({
+    const { report, runGate } = await (0, detect_1.buildDriftReport)({
         config: normalized,
         repo,
         baseSha: options.baseSha,
         headSha: options.headSha,
         trigger: options.trigger ?? "manual",
+        prNumber: options.prNumber,
     });
-    (0, log_1.logInfo)(`Drift items detected: ${report.items.length} (hasOpenApiDrift: ${hasOpenApiDrift})`);
+    (0, log_1.logInfo)(`Drift items detected: ${report.items.length} (runGate: ${runGate})`);
     return { hasDrift: report.items.length > 0 };
 }
 async function runDocDrift(options) {
@@ -144,16 +182,17 @@ async function runDocDrift(options) {
     const commitSha = process.env.GITHUB_SHA ?? options.headSha;
     const githubToken = process.env.GITHUB_TOKEN;
     const devinApiKey = process.env.DEVIN_API_KEY;
-    const { report, aggregated, runInfo, evidenceRoot, hasOpenApiDrift } = await (0, detect_1.buildDriftReport)({
+    const { report, aggregated, runInfo, evidenceRoot, runGate } = await (0, detect_1.buildDriftReport)({
         config: normalized,
         repo,
         baseSha: options.baseSha,
         headSha: options.headSha,
         trigger: options.trigger ?? "manual",
+        prNumber: options.prNumber,
     });
-    // Gate: no OpenAPI drift — exit early, no session
-    if (!hasOpenApiDrift || report.items.length === 0) {
-        (0, log_1.logInfo)("No OpenAPI drift; skipping session");
+    // Gate: no run (spec drift, conceptual-only, or infer) — exit early, no session
+    if (runGate === "none" || report.items.length === 0) {
+        (0, log_1.logInfo)("No drift; skipping session");
         return [];
     }
     const item = report.items[0];
@@ -234,6 +273,9 @@ async function runDocDrift(options) {
             aggregated: aggregated,
             attachmentPaths,
             config: normalized,
+            runGate,
+            trigger: runInfo.trigger,
+            prNumber: runInfo.prNumber,
         });
         metrics.timeToSessionTerminalMs.push(Date.now() - sessionStart);
     }
@@ -254,6 +296,14 @@ async function runDocDrift(options) {
         metrics.prsOpened += 1;
         state.lastDocDriftPrUrl = sessionOutcome.prUrl;
         state.lastDocDriftPrOpenedAt = new Date().toISOString();
+        if (githubToken && runInfo.trigger === "pull_request" && runInfo.prNumber) {
+            await (0, client_1.postPrComment)({
+                token: githubToken,
+                repository: repo,
+                prNumber: runInfo.prNumber,
+                body: `## Doc drift detected\n\nDraft doc PR: ${sessionOutcome.prUrl}\n\nMerge your API changes first, then review and merge this doc PR.`,
+            });
+        }
         const touchedRequireReview = (item.impactedDocs ?? []).filter((p) => normalized.requireHumanReview.some((glob) => (0, glob_1.matchesGlob)(glob, p)));
         if (githubToken && touchedRequireReview.length > 0) {
             issueUrl = await (0, client_1.createIssue)({
@@ -450,12 +500,12 @@ async function runStatus(sinceHours = 24) {
     }
 }
 function resolveTrigger(eventName) {
-    if (eventName === "push") {
+    if (eventName === "push")
         return "push";
-    }
-    if (eventName === "schedule") {
+    if (eventName === "schedule")
         return "schedule";
-    }
+    if (eventName === "pull_request")
+        return "pull_request";
     return "manual";
 }
 function parseDurationHours(value) {
@@ -475,4 +525,14 @@ function requireSha(value, label) {
     }
     return value;
 }
+async function resolveBaseHead(baseArg, headArg) {
+    const headRef = headArg ?? process.env.GITHUB_SHA ?? "HEAD";
+    if (baseArg) {
+        return { baseSha: baseArg, headSha: headRef };
+    }
+    const { resolveDefaultBaseHead } = await Promise.resolve().then(() => __importStar(require("./utils/git")));
+    return resolveDefaultBaseHead(headRef);
+}
 exports.STATE_PATH = node_path_1.default.resolve(".docdrift", "state.json");
+var setup_1 = require("./setup");
+Object.defineProperty(exports, "runSetup", { enumerable: true, get: function () { return setup_1.runSetup; } });

package/dist/src/setup/ai-infer.js

@@ -0,0 +1,191 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferConfigFromFingerprint = inferConfigFromFingerprint;
+const gateway_1 = require("@ai-sdk/gateway");
+const ai_1 = require("ai");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const zod_1 = require("zod");
+const repo_fingerprint_1 = require("./repo-fingerprint");
+const prompts_1 = require("./prompts");
+const pathRuleSchema = zod_1.z.object({
+    match: zod_1.z.string().min(1),
+    impacts: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+});
+const InferenceSchema = zod_1.z.object({
+    suggestedConfig: zod_1.z.object({
+        version: zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(2)]).optional(),
+        openapi: zod_1.z
+            .object({
+            export: zod_1.z.string().min(1),
+            generated: zod_1.z.string().min(1),
+            published: zod_1.z.string().min(1),
+        })
+            .optional(),
+        docsite: zod_1.z.union([zod_1.z.string().min(1), zod_1.z.array(zod_1.z.string().min(1))]).optional(),
+        exclude: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+        requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+        pathMappings: zod_1.z.array(pathRuleSchema).optional(),
+        devin: zod_1.z
+            .object({
+            apiVersion: zod_1.z.literal("v1"),
+            unlisted: zod_1.z.boolean().optional(),
+            maxAcuLimit: zod_1.z.number().optional(),
+            tags: zod_1.z.array(zod_1.z.string()).optional(),
+            customInstructions: zod_1.z.array(zod_1.z.string()).optional(),
+        })
+            .optional(),
+        policy: zod_1.z
+            .object({
+            prCaps: zod_1.z.object({ maxPrsPerDay: zod_1.z.number(), maxFilesTouched: zod_1.z.number() }).optional(),
+            confidence: zod_1.z.object({ autopatchThreshold: zod_1.z.number() }).optional(),
+            allowlist: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+            verification: zod_1.z.object({ commands: zod_1.z.array(zod_1.z.string().min(1)) }).optional(),
+            slaDays: zod_1.z.number().optional(),
+            slaLabel: zod_1.z.string().optional(),
+            allowNewFiles: zod_1.z.boolean().optional(),
+        })
+            .optional(),
+    }),
+    choices: zod_1.z.array(zod_1.z.object({
+        key: zod_1.z.string(),
+        question: zod_1.z.string(),
+        options: zod_1.z.array(zod_1.z.object({
+            value: zod_1.z.string(),
+            label: zod_1.z.string(),
+            recommended: zod_1.z.boolean().optional(),
+        })),
+        defaultIndex: zod_1.z.number(),
+        help: zod_1.z.string().optional(),
+        warning: zod_1.z.string().optional(),
+        confidence: zod_1.z.enum(["high", "medium", "low"]),
+    })),
+    skipQuestions: zod_1.z.array(zod_1.z.string()).optional(),
+});
+const CACHE_DIR = ".docdrift";
+const CACHE_FILE = "setup-cache.json";
+function getCachePath(cwd) {
+    return node_path_1.default.resolve(cwd, CACHE_DIR, CACHE_FILE);
+}
+function readCache(cwd) {
+    const cachePath = getCachePath(cwd);
+    if (!node_fs_1.default.existsSync(cachePath))
+        return null;
+    try {
+        const raw = JSON.parse(node_fs_1.default.readFileSync(cachePath, "utf8"));
+        const parsed = InferenceSchema.safeParse(raw.inference);
+        if (!parsed.success)
+            return null;
+        return {
+            fingerprintHash: String(raw.fingerprintHash),
+            inference: parsed.data,
+            timestamp: Number(raw.timestamp) || 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(cwd, fingerprintHash, inference) {
+    const dir = node_path_1.default.resolve(cwd, CACHE_DIR);
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    node_fs_1.default.writeFileSync(getCachePath(cwd), JSON.stringify({ fingerprintHash, inference, timestamp: Date.now() }, null, 2), "utf8");
+}
+function heuristicInference(fingerprint) {
+    const scripts = fingerprint.rootPackage.scripts || {};
+    const openapiExport = scripts["openapi:export"] ?? scripts["openapi:generate"] ?? "npm run openapi:export";
+    const firstOpenapi = fingerprint.foundPaths.openapi[0];
+    const firstDocsite = fingerprint.foundPaths.docusaurusConfig[0]
+        ? node_path_1.default.dirname(fingerprint.foundPaths.docusaurusConfig[0]).replace(/\\/g, "/")
+        : fingerprint.foundPaths.docsDirs[0]
+            ? node_path_1.default.dirname(fingerprint.foundPaths.docsDirs[0]).replace(/\\/g, "/")
+            : "apps/docs-site";
+    const published = firstOpenapi ?? `${firstDocsite}/openapi/openapi.json`;
+    const generated = firstOpenapi ?? "openapi/generated.json";
+    const verificationCommands = [];
+    if (scripts["docs:gen"])
+        verificationCommands.push("npm run docs:gen");
+    if (scripts["docs:build"])
+        verificationCommands.push("npm run docs:build");
+    if (verificationCommands.length === 0)
+        verificationCommands.push("npm run build");
+    return {
+        suggestedConfig: {
+            version: 1,
+            openapi: { export: openapiExport, generated, published },
+            docsite: firstDocsite,
+            exclude: ["**/CHANGELOG*", "**/blog/**"],
+            requireHumanReview: [],
+            pathMappings: [{ match: "**/api/**", impacts: [`${firstDocsite}/docs/**`, `${firstDocsite}/openapi/**`] }],
+            devin: { apiVersion: "v1", unlisted: true, maxAcuLimit: 2, tags: ["docdrift"] },
+            policy: {
+                prCaps: { maxPrsPerDay: 5, maxFilesTouched: 30 },
+                confidence: { autopatchThreshold: 0.8 },
+                allowlist: ["openapi/**", firstDocsite + "/**"],
+                verification: { commands: verificationCommands },
+                slaDays: 7,
+                slaLabel: "docdrift",
+                allowNewFiles: false,
+            },
+        },
+        choices: [
+            {
+                key: "openapi.export",
+                question: "OpenAPI export command",
+                options: [{ value: openapiExport, label: openapiExport, recommended: true }],
+                defaultIndex: 0,
+                help: "Command that generates the OpenAPI spec.",
+                confidence: "medium",
+            },
+            {
+                key: "docsite",
+                question: "Docsite path",
+                options: [{ value: firstDocsite, label: firstDocsite, recommended: true }],
+                defaultIndex: 0,
+                confidence: "medium",
+            },
+        ],
+        skipQuestions: [],
+    };
+}
+async function inferConfigFromFingerprint(fingerprint, cwd = process.cwd()) {
+    const apiKey = process.env.AI_GATEWAY_API_KEY?.trim();
+    const hash = (0, repo_fingerprint_1.fingerprintHash)(fingerprint);
+    const cached = readCache(cwd);
+    if (cached && cached.fingerprintHash === hash)
+        return cached.inference;
+    if (!apiKey)
+        return heuristicInference(fingerprint);
+    const gateway = (0, gateway_1.createGateway)({
+        apiKey,
+        baseURL: "https://ai-gateway.vercel.sh/v1/ai",
+    });
+    const prompt = `Repo fingerprint:\n${JSON.stringify(fingerprint, null, 2)}`;
+    try {
+        const result = await (0, ai_1.generateText)({
+            model: gateway("anthropic/claude-opus-4.6"),
+            system: prompts_1.SYSTEM_PROMPT,
+            prompt,
+            experimental_output: ai_1.Output.object({
+                schema: InferenceSchema,
+            }),
+            maxRetries: 2,
+            abortSignal: AbortSignal.timeout(60_000),
+        });
+        const output = result.experimental_output;
+        if (!output)
+            throw new Error("No structured output");
+        const parsed = InferenceSchema.safeParse(output);
+        if (!parsed.success)
+            throw new Error(parsed.error.message);
+        const inference = parsed.data;
+        writeCache(cwd, hash, inference);
+        return inference;
+    }
+    catch {
+        return heuristicInference(fingerprint);
+    }
+}

package/dist/src/setup/generate-yaml.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildConfigFromInference = buildConfigFromInference;
+exports.writeConfig = writeConfig;
+exports.validateGeneratedConfig = validateGeneratedConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const schema_1 = require("../config/schema");
+function deepMerge(target, source) {
+    const out = { ...target };
+    for (const key of Object.keys(source)) {
+        const s = source[key];
+        const t = out[key];
+        if (s != null && typeof s === "object" && !Array.isArray(s) && t != null && typeof t === "object" && !Array.isArray(t)) {
+            out[key] = deepMerge(t, s);
+        }
+        else if (s !== undefined) {
+            out[key] = s;
+        }
+    }
+    return out;
+}
+function applyOverrides(base, overrides) {
+    for (const [key, value] of Object.entries(overrides)) {
+        setByKey(base, key, value);
+    }
+}
+function setByKey(obj, key, value) {
+    const parts = key.split(".");
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const p = parts[i];
+        if (!(p in cur) || typeof cur[p] !== "object" || cur[p] === null || Array.isArray(cur[p])) {
+            cur[p] = {};
+        }
+        cur = cur[p];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+const DEFAULT_CONFIG = {
+    version: 1,
+    openapi: { export: "npm run openapi:export", generated: "openapi/generated.json", published: "apps/docs-site/openapi/openapi.json" },
+    docsite: "apps/docs-site",
+    exclude: [],
+    requireHumanReview: [],
+    pathMappings: [],
+    devin: {
+        apiVersion: "v1",
+        unlisted: true,
+        maxAcuLimit: 2,
+        tags: ["docdrift"],
+    },
+    policy: {
+        prCaps: { maxPrsPerDay: 5, maxFilesTouched: 30 },
+        confidence: { autopatchThreshold: 0.8 },
+        allowlist: ["openapi/**", "apps/**"],
+        verification: { commands: ["npm run docs:gen", "npm run docs:build"] },
+        slaDays: 7,
+        slaLabel: "docdrift",
+        allowNewFiles: false,
+    },
+};
+function buildConfigFromInference(inference, formResult) {
+    const base = deepMerge({ ...DEFAULT_CONFIG }, inference.suggestedConfig);
+    applyOverrides(base, formResult.configOverrides);
+    return base;
+}
+function writeConfig(config, outputPath) {
+    const dir = node_path_1.default.dirname(outputPath);
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    const yamlContent = [
+        "# yaml-language-server: $schema=./docdrift.schema.json",
+        js_yaml_1.default.dump(config, { lineWidth: 120, noRefs: true }),
+    ].join("\n");
+    node_fs_1.default.writeFileSync(outputPath, yamlContent, "utf8");
+}
+function validateGeneratedConfig(configPath) {
+    try {
+        const content = node_fs_1.default.readFileSync(configPath, "utf8");
+        const parsed = js_yaml_1.default.load(content);
+        const result = schema_1.docDriftConfigSchema.safeParse(parsed);
+        if (!result.success) {
+            const errors = result.error.errors.map((e) => `${e.path.join(".") || "root"}: ${e.message}`);
+            return { ok: false, errors };
+        }
+        return { ok: true, errors: [] };
+    }
+    catch (err) {
+        return { ok: false, errors: [err instanceof Error ? err.message : String(err)] };
+    }
+}

package/dist/src/setup/index.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSetup = runSetup;
+const node_path_1 = __importDefault(require("node:path"));
+const repo_fingerprint_1 = require("./repo-fingerprint");
+const ai_infer_1 = require("./ai-infer");
+const interactive_form_1 = require("./interactive-form");
+const generate_yaml_1 = require("./generate-yaml");
+const onboard_1 = require("./onboard");
+const index_1 = require("../index");
+async function runSetup(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
+    const configExists = await Promise.resolve().then(() => __importStar(require("node:fs"))).then((fs) => fs.existsSync(outputPath));
+    if (configExists && !options.force) {
+        const { confirm } = await Promise.resolve().then(() => __importStar(require("@inquirer/prompts")));
+        const overwrite = await confirm({
+            message: "Config already exists. Overwrite?",
+            default: false,
+        });
+        if (!overwrite) {
+            console.log("Setup cancelled.");
+            return;
+        }
+    }
+    process.stdout.write("Analyzing your repo…\n");
+    const fingerprint = (0, repo_fingerprint_1.buildRepoFingerprint)(cwd);
+    process.stdout.write("Generating suggestions…\n");
+    const inference = await (0, ai_infer_1.inferConfigFromFingerprint)(fingerprint, cwd);
+    const formResult = await (0, interactive_form_1.runInteractiveForm)(inference, cwd);
+    let config = (0, generate_yaml_1.buildConfigFromInference)(inference, formResult);
+    if (formResult.onboarding.addCustomInstructions) {
+        const devin = config.devin ?? {};
+        config.devin = {
+            ...devin,
+            customInstructions: [".docdrift/DocDrift.md"],
+        };
+    }
+    (0, generate_yaml_1.writeConfig)(config, outputPath);
+    const { created } = (0, onboard_1.runOnboarding)(cwd, formResult.onboarding);
+    const validation = (0, generate_yaml_1.validateGeneratedConfig)(outputPath);
+    if (!validation.ok) {
+        console.error("Config validation failed:\n" + validation.errors.join("\n"));
+        throw new Error("Generated config is invalid. Fix the errors above or edit docdrift.yaml manually.");
+    }
+    if (outputPath === node_path_1.default.resolve(cwd, "docdrift.yaml")) {
+        try {
+            await (0, index_1.runValidate)();
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    }
+    console.log("\ndocdrift setup complete\n");
+    console.log("  docdrift.yaml     written and validated");
+    for (const item of created) {
+        if (item === ".docdrift/")
+            console.log("  .docdrift/        created");
+        else if (item === "DocDrift.md")
+            console.log("  DocDrift.md       created (edit for custom instructions)");
+        else if (item === ".gitignore")
+            console.log("  .gitignore        updated");
+        else if (item.endsWith("docdrift.yml"))
+            console.log("  " + item + "  added");
+    }
+    console.log("\nNext steps:");
+    console.log("  1. Set DEVIN_API_KEY (local: .env or export; CI: repo secrets)");
+    console.log("  2. Set GITHUB_TOKEN in repo secrets for PR comments and issues");
+    console.log("  3. Run: docdrift validate   — verify config");
+    console.log("  4. Run: docdrift detect     — check for drift");
+    console.log("  5. Run: docdrift run        — create Devin session (requires DEVIN_API_KEY)");
+}

package/dist/src/setup/interactive-form.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInteractiveForm = runInteractiveForm;
+const prompts_1 = require("@inquirer/prompts");
+async function runInteractiveForm(inference, _cwd = process.cwd()) {
+    const configOverrides = {};
+    const skip = new Set(inference.skipQuestions ?? []);
+    for (const choice of inference.choices) {
+        if (skip.has(choice.key))
+            continue;
+        const options = choice.options;
+        if (options.length === 0)
+            continue;
+        const defaultOption = options[choice.defaultIndex] ?? options[0];
+        const choices = options.map((o, i) => ({
+            name: o.recommended ? `${o.label} (recommended)` : o.label,
+            value: o.value,
+        }));
+        const answer = await (0, prompts_1.select)({
+            message: choice.question,
+            choices,
+            default: defaultOption?.value,
+        });
+        configOverrides[choice.key] = answer;
+    }
+    const addCustomInstructions = await (0, prompts_1.confirm)({
+        message: "Add a custom instructions file for Devin? (PR titles, tone, project-specific guidance)",
+        default: true,
+    });
+    const addGitignore = await (0, prompts_1.confirm)({
+        message: "Add .docdrift artifact entries to .gitignore?",
+        default: true,
+    });
+    const addWorkflow = await (0, prompts_1.confirm)({
+        message: "Add GitHub Actions workflow for docdrift? (runs on push/PR to main)",
+        default: false,
+    });
+    const confirmed = await (0, prompts_1.confirm)({
+        message: "Write docdrift.yaml and complete setup? (will run validate)",
+        default: true,
+    });
+    if (!confirmed) {
+        throw new Error("Setup cancelled");
+    }
+    return {
+        configOverrides,
+        onboarding: { addCustomInstructions, addGitignore, addWorkflow },
+    };
+}