@devinnn/docdrift 0.1.11 → 0.1.13

package/dist/src/cli.js

@@ -57,7 +57,7 @@ async function main() {
             "  status            Show run status [--since 24h]\n" +
             "  sla-check         Check SLA for unmerged PRs\n" +
             "  setup             Interactive setup (generates v2 docdrift.yaml)\n" +
-            "  generate-yaml     Generate config [--output path] [--force]");
+            "  generate-yaml     Generate config [--output path] [--force] [--open-pr]");
     }
     if (command === "setup" || command === "generate-yaml") {
         require("dotenv").config();
@@ -65,6 +65,7 @@ async function main() {
         await runSetup({
             outputPath: getArg(args, "--output") ?? "docdrift.yaml",
             force: args.includes("--force"),
+            openPr: args.includes("--open-pr"),
         });
         return;
     }

package/dist/src/devin/v1.js

@@ -112,8 +112,10 @@ function hasPrUrl(session) {
         return true;
     return false;
 }
+const PROGRESS_INTERVAL_MS = 30_000; // Print "still waiting" every 30s
 async function pollUntilTerminal(apiKey, sessionId, timeoutMs = 30 * 60_000) {
     const started = Date.now();
+    let lastProgressAt = 0;
     while (Date.now() - started < timeoutMs) {
         const session = await devinGetSession(apiKey, sessionId);
         const status = String(session.status_enum ?? session.status ?? "UNKNOWN").toLowerCase();
@@ -124,6 +126,12 @@ async function pollUntilTerminal(apiKey, sessionId, timeoutMs = 30 * 60_000) {
         if (hasPrUrl(session)) {
             return session;
         }
+        const now = Date.now();
+        if (now - lastProgressAt >= PROGRESS_INTERVAL_MS) {
+            const elapsed = Math.round((now - started) / 1000);
+            process.stdout.write(`  Still waiting for Devin… (${elapsed}s elapsed; open session URL in browser to watch)\n`);
+            lastProgressAt = now;
+        }
         await new Promise((resolve) => setTimeout(resolve, 5000));
     }
     throw new Error(`Session polling timed out for ${sessionId}`);

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

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.heuristicInference = heuristicInference;
 exports.inferConfigFromFingerprint = inferConfigFromFingerprint;
 const gateway_1 = require("@ai-sdk/gateway");
 const ai_1 = require("ai");
@@ -100,21 +101,32 @@ function writeCache(cwd, fingerprintHash, inference) {
 }
 function heuristicInference(fingerprint) {
     const scripts = fingerprint.rootPackage.scripts || {};
-    const scriptNames = Object.keys(scripts);
-    const openapiScriptName = scriptNames.find((s) => s === "openapi:export" || s === "openapi:generate");
-    const openapiExport = openapiScriptName ? `npm run ${openapiScriptName}` : "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 && firstOpenapi.includes(firstDocsite)
+    const fp = fingerprint.foundPaths;
+    const exportScript = fp.exportScript;
+    const openapiExport = exportScript
+        ? `npm run ${exportScript.scriptName}`
+        : "npm run openapi:export";
+    const firstOpenapi = fp.openapi[0];
+    const generatedPath = exportScript?.inferredOutputPath ??
+        (firstOpenapi && !node_path_1.default.dirname(firstOpenapi).includes("docs") ? firstOpenapi : "openapi/generated.json");
+    const firstDocsite = fp.docusaurusConfig[0]
+        ? node_path_1.default.dirname(fp.docusaurusConfig[0]).replace(/\\/g, "/")
+        : fp.mkdocs[0]
+            ? node_path_1.default.dirname(fp.mkdocs[0]).replace(/\\/g, "/")
+            : fp.vitepressConfig?.[0]
+                ? node_path_1.default.dirname(fp.vitepressConfig[0]).replace(/\\/g, "/")
+                : fp.nextConfig?.[0]
+                    ? node_path_1.default.dirname(fp.nextConfig[0]).replace(/\\/g, "/")
+                    : fp.docsDirParents[0]
+                        ? fp.docsDirParents[0].replace(/\\/g, "/")
+                        : fp.docsDirs[0]
+                            ? node_path_1.default.dirname(fp.docsDirs[0]).replace(/\\/g, "/") || undefined
+                            : undefined;
+    const published = firstOpenapi && firstDocsite && firstOpenapi.includes(firstDocsite)
         ? firstOpenapi
-        : `${firstDocsite}/openapi/openapi.json`;
-    const generated = firstOpenapi && !firstOpenapi.includes(firstDocsite)
-        ? firstOpenapi
-        : "openapi/generated.json";
+        : firstDocsite
+            ? `${firstDocsite}/openapi/openapi.json`
+            : firstOpenapi ?? "openapi/openapi.json";
     const verificationCommands = [];
     if (scripts["docs:gen"])
         verificationCommands.push("npm run docs:gen");
@@ -122,29 +134,88 @@ function heuristicInference(fingerprint) {
         verificationCommands.push("npm run docs:build");
     if (verificationCommands.length === 0)
         verificationCommands.push("npm run build");
-    const treeKeys = Object.keys(fingerprint.fileTree);
-    const hasAppsApi = treeKeys.some((k) => k === "apps/api" || k.startsWith("apps/api/"));
-    const matchGlob = hasAppsApi ? "apps/api/**" : "**/api/**";
-    const allowlist = treeKeys.some((k) => k === "apps" || k.startsWith("apps/"))
-        ? ["openapi/**", "apps/**"]
-        : ["openapi/**", `${firstDocsite}/**`];
-    const requireHumanReview = fingerprint.foundPaths.docsDirs.length > 0
+    const apiDir = fp.apiDirs[0];
+    const matchGlob = apiDir ? `${apiDir}/**` : "**/api/**";
+    const allowlistParts = ["openapi/**"];
+    if (firstDocsite)
+        allowlistParts.push(`${firstDocsite}/**`);
+    if (firstOpenapi) {
+        const openapiDir = node_path_1.default.dirname(firstOpenapi).replace(/\\/g, "/");
+        if (openapiDir && openapiDir !== "." && !allowlistParts.includes(`${openapiDir}/**`)) {
+            allowlistParts.push(`${openapiDir}/**`);
+        }
+    }
+    const allowlist = allowlistParts;
+    const requireHumanReview = firstDocsite && (fp.docsDirs.length > 0 || fp.docusaurusConfig.length > 0)
         ? [`${firstDocsite}/docs/guides/**`]
         : [];
+    const pathMappings = firstDocsite || apiDir
+        ? [
+            {
+                match: matchGlob,
+                impacts: firstDocsite
+                    ? [`${firstDocsite}/docs/**`, `${firstDocsite}/openapi/**`]
+                    : ["**/docs/**", "**/openapi/**"],
+            },
+        ]
+        : [];
+    const choices = [
+        {
+            key: "specProviders.0.current.command",
+            question: "OpenAPI export command",
+            options: [{ value: openapiExport, label: openapiExport, recommended: true }],
+            defaultIndex: 0,
+            help: "Use the npm script that generates the spec (e.g. npm run openapi:export).",
+            confidence: "medium",
+        },
+    ];
+    if (!firstDocsite) {
+        choices.push({
+            key: "docsite",
+            question: "Docsite path",
+            options: [{ value: "", label: "(specify path to docs site root)", recommended: false }],
+            defaultIndex: 0,
+            help: "Path to Docusaurus, MkDocs, VitePress, or other docs site root.",
+            confidence: "low",
+        });
+    }
+    else {
+        choices.push({
+            key: "docsite",
+            question: "Docsite path",
+            options: [{ value: firstDocsite, label: firstDocsite, recommended: true }],
+            defaultIndex: 0,
+            confidence: "medium",
+        });
+    }
+    if (!apiDir) {
+        choices.push({
+            key: "pathMappings.0.match",
+            question: "API/source code path (pathMappings.match)",
+            options: [{ value: "**/api/**", label: "**/api/** (generic)", recommended: true }],
+            defaultIndex: 0,
+            help: "Glob for API or source code that, when changed, may require doc updates.",
+            confidence: "low",
+        });
+    }
     return {
         suggestedConfig: {
             version: 2,
             specProviders: [
                 {
                     format: "openapi3",
-                    current: { type: "export", command: openapiExport, outputPath: generated },
+                    current: {
+                        type: "export",
+                        command: openapiExport,
+                        outputPath: generatedPath,
+                    },
                     published,
                 },
             ],
-            docsite: firstDocsite,
+            ...(firstDocsite ? { docsite: firstDocsite } : {}),
             exclude: ["**/CHANGELOG*", "**/blog/**"],
             requireHumanReview,
-            pathMappings: [{ match: matchGlob, impacts: [`${firstDocsite}/docs/**`, `${firstDocsite}/openapi/**`] }],
+            pathMappings,
             mode: "strict",
             devin: { apiVersion: "v1", unlisted: true, maxAcuLimit: 2, tags: ["docdrift"] },
             policy: {
@@ -157,23 +228,7 @@ function heuristicInference(fingerprint) {
                 allowNewFiles: false,
             },
         },
-        choices: [
-            {
-                key: "specProviders.0.current.command",
-                question: "OpenAPI export command",
-                options: [{ value: openapiExport, label: openapiExport, recommended: true }],
-                defaultIndex: 0,
-                help: "Use the npm script that generates the spec (e.g. npm run openapi:export).",
-                confidence: "medium",
-            },
-            {
-                key: "docsite",
-                question: "Docsite path",
-                options: [{ value: firstDocsite, label: firstDocsite, recommended: true }],
-                defaultIndex: 0,
-                confidence: "medium",
-            },
-        ],
+        choices,
         skipQuestions: [],
     };
 }

package/dist/src/setup/devin-setup.js

@@ -36,6 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSetupLocal = runSetupLocal;
 exports.runSetupDevin = runSetupDevin;
 exports.runSetupDevinAndValidate = runSetupDevinAndValidate;
 const node_path_1 = __importDefault(require("node:path"));
@@ -47,6 +48,9 @@ const setup_prompt_1 = require("./setup-prompt");
 const generate_yaml_1 = require("./generate-yaml");
 const index_1 = require("../index");
 const onboard_1 = require("./onboard");
+const repo_fingerprint_1 = require("./repo-fingerprint");
+const ai_infer_1 = require("./ai-infer");
+const interactive_form_1 = require("./interactive-form");
 /** Resolve path to docdrift.schema.json in the package */
 function getSchemaPath() {
     // dist/src/setup -> ../../../ ; src/setup (tsx) -> ../..
@@ -60,23 +64,125 @@ function getSchemaPath() {
     }
     return schemaPath;
 }
-function parseSetupOutput(session) {
-    const raw = session?.structured_output ?? session?.data?.structured_output;
-    if (!raw || typeof raw !== "object")
+/** Generate docdrift.yaml from repo fingerprint + heuristic (no Devin). */
+async function runSetupLocal(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
+    const configExists = node_fs_1.default.existsSync(outputPath);
+    if (configExists && !options.force) {
+        const { confirm } = await Promise.resolve().then(() => __importStar(require("@inquirer/prompts")));
+        const overwrite = await confirm({
+            message: "docdrift.yaml already exists. Overwrite?",
+            default: false,
+        });
+        if (!overwrite) {
+            throw new Error("Setup cancelled.");
+        }
+    }
+    process.stdout.write("Scanning repo…\n");
+    const fingerprint = (0, repo_fingerprint_1.buildRepoFingerprint)(cwd);
+    const inference = await (0, ai_infer_1.inferConfigFromFingerprint)(fingerprint, cwd);
+    process.stdout.write("Inferred config from repo layout. Adjust if needed.\n");
+    const formResult = await (0, interactive_form_1.runInteractiveForm)(inference, cwd);
+    const config = (0, generate_yaml_1.buildConfigFromInference)(inference, formResult);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(outputPath), { recursive: true });
+    (0, generate_yaml_1.writeConfig)(config, outputPath);
+    const yamlContent = node_fs_1.default.readFileSync(outputPath, "utf8");
+    (0, onboard_1.runOnboarding)(cwd, formResult.onboarding);
+    const validation = (0, generate_yaml_1.validateGeneratedConfig)(outputPath);
+    if (!validation.ok) {
+        throw new Error("Generated config failed validation:\n" + validation.errors.join("\n"));
+    }
+    return {
+        docdriftYaml: yamlContent,
+        docDriftMd: formResult.onboarding.addCustomInstructions ? "(created)" : undefined,
+        workflowYml: formResult.onboarding.addWorkflow ? "(added)" : undefined,
+        summary: "Generated from repo fingerprint (local detection, no Devin).",
+        sessionUrl: "",
+    };
+}
+/** Extract transcript text from session for fallback parsing */
+function getSessionTranscript(session) {
+    const messages = session.messages ?? session.data?.messages;
+    if (!Array.isArray(messages))
+        return "";
+    return messages
+        .map((m) => (typeof m.content === "string" ? m.content : m.text ?? ""))
+        .filter(Boolean)
+        .join("\n");
+}
+/** Parse setup output from <docdrift_setup_output>...</docdrift_setup_output> JSON block in text */
+function parseFromStrictTag(text) {
+    const openTag = `<${setup_prompt_1.DOCDRIFT_SETUP_OUTPUT_TAG}>`;
+    const closeTag = `</${setup_prompt_1.DOCDRIFT_SETUP_OUTPUT_TAG}>`;
+    const openIdx = text.indexOf(openTag);
+    const closeIdx = text.indexOf(closeTag, openIdx);
+    if (openIdx === -1 || closeIdx === -1)
+        return null;
+    const inner = text.slice(openIdx + openTag.length, closeIdx).trim();
+    try {
+        const o = JSON.parse(inner);
+        const yaml = o.docdriftYaml;
+        const summary = o.summary;
+        if (typeof yaml !== "string" || typeof summary !== "string")
+            return null;
+        return {
+            docdriftYaml: yaml,
+            docDriftMd: typeof o.docDriftMd === "string" && o.docDriftMd ? o.docDriftMd : undefined,
+            workflowYml: typeof o.workflowYml === "string" && o.workflowYml ? o.workflowYml : undefined,
+            summary,
+            sessionUrl: "",
+        };
+    }
+    catch {
         return null;
-    const o = raw;
-    const yaml = o.docdriftYaml;
-    const summary = o.summary;
-    if (typeof yaml !== "string" || typeof summary !== "string")
+    }
+}
+/** Fallback: parse from markdown blocks like **docdriftYaml:** ```yaml ... ``` */
+function parseFromMarkdownBlocks(text) {
+    const yamlMatch = text.match(/\*\*docdriftYaml:\*\*[\s\S]*?```(?:yaml)?\s*([\s\S]*?)```/i);
+    const docMdMatch = text.match(/\*\*docDriftMd:\*\*[\s\S]*?```(?:markdown)?\s*([\s\S]*?)```/i);
+    const workflowMatch = text.match(/\*\*workflowYml:\*\*[\s\S]*?```(?:yaml)?\s*([\s\S]*?)```/i);
+    const summaryBlock = text.match(/\*\*summary:\*\*([\s\S]*?)(?=\n\n\*\*|$)/i)?.[1]?.trim();
+    const yaml = yamlMatch?.[1]?.trim();
+    const summary = (summaryBlock || "Inferred from repo analysis").slice(0, 500);
+    if (!yaml)
         return null;
     return {
         docdriftYaml: yaml,
-        docDriftMd: typeof o.docDriftMd === "string" && o.docDriftMd ? o.docDriftMd : undefined,
-        workflowYml: typeof o.workflowYml === "string" && o.workflowYml ? o.workflowYml : undefined,
+        docDriftMd: docMdMatch?.[1]?.trim() || undefined,
+        workflowYml: workflowMatch?.[1]?.trim() || undefined,
         summary,
         sessionUrl: "",
     };
 }
+function parseSetupOutput(session) {
+    const raw = session?.structured_output ?? session?.data?.structured_output;
+    if (raw && typeof raw === "object") {
+        const o = raw;
+        const yaml = o.docdriftYaml;
+        const summary = o.summary;
+        if (typeof yaml === "string" && typeof summary === "string") {
+            return {
+                docdriftYaml: yaml,
+                docDriftMd: typeof o.docDriftMd === "string" && o.docDriftMd ? o.docDriftMd : undefined,
+                workflowYml: typeof o.workflowYml === "string" && o.workflowYml ? o.workflowYml : undefined,
+                summary,
+                sessionUrl: "",
+            };
+        }
+    }
+    const transcript = getSessionTranscript(session);
+    if (transcript) {
+        const fromTag = parseFromStrictTag(transcript);
+        if (fromTag)
+            return fromTag;
+        const fromMarkdown = parseFromMarkdownBlocks(transcript);
+        if (fromMarkdown)
+            return fromMarkdown;
+    }
+    return null;
+}
 async function runSetupDevin(options) {
     const cwd = options.cwd ?? process.cwd();
     const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
@@ -98,7 +204,7 @@ async function runSetupDevin(options) {
     process.stdout.write("Uploading schema…\n");
     const schemaPath = getSchemaPath();
     const attachmentUrl = await (0, v1_1.devinUploadAttachment)(apiKey, schemaPath);
-    const prompt = (0, setup_prompt_1.buildSetupPrompt)([attachmentUrl]);
+    const prompt = (0, setup_prompt_1.buildSetupPrompt)([attachmentUrl], { openPr: options.openPr });
     process.stdout.write("Creating Devin session…\n");
     const session = await (0, v1_1.devinCreateSession)(apiKey, {
         prompt,
@@ -119,7 +225,12 @@ async function runSetupDevin(options) {
         throw new Error("Devin session did not return valid setup output. Check the session for details: " + session.url);
     }
     result.sessionUrl = session.url;
-    // Write files
+    const prUrl = finalSession.pull_request_url ??
+        finalSession.pr_url ??
+        finalSession.pull_request?.url;
+    if (prUrl)
+        result.prUrl = prUrl;
+    // Write files (always write for validation; when openPr, Devin also created PR)
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(outputPath), { recursive: true });
     node_fs_1.default.writeFileSync(outputPath, result.docdriftYaml, "utf8");
     if (result.docDriftMd) {

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

@@ -67,20 +67,10 @@ function setByKey(obj, key, value) {
     }
     cur[parts[parts.length - 1]] = value;
 }
+/** Structural defaults only; path fields (docsite, specProviders, allowlist paths) come from inference. */
 const DEFAULT_CONFIG = {
     version: 2,
-    specProviders: [
-        {
-            format: "openapi3",
-            current: {
-                type: "export",
-                command: "npm run openapi:export",
-                outputPath: "openapi/generated.json",
-            },
-            published: "apps/docs-site/openapi/openapi.json",
-        },
-    ],
-    docsite: "apps/docs-site",
+    specProviders: [],
     exclude: [],
     requireHumanReview: [],
     pathMappings: [],
@@ -94,8 +84,8 @@ const DEFAULT_CONFIG = {
     policy: {
         prCaps: { maxPrsPerDay: 5, maxFilesTouched: 30 },
         confidence: { autopatchThreshold: 0.8 },
-        allowlist: ["openapi/**", "apps/**"],
-        verification: { commands: ["npm run docs:gen", "npm run docs:build"] },
+        allowlist: ["openapi/**"],
+        verification: { commands: ["npm run build"] },
         slaDays: 7,
         slaLabel: "docdrift",
         allowNewFiles: false,

package/dist/src/setup/index.js

@@ -1,20 +1,106 @@
 "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 prompts_1 = require("@inquirer/prompts");
 const devin_setup_1 = require("./devin-setup");
+/** Ask user whether repo is set up with Devin; if not, we use local (manual) setup. */
+async function chooseSetupMode() {
+    if (!process.stdin.isTTY) {
+        return "local";
+    }
+    const choice = await (0, prompts_1.select)({
+        message: "Is this repo already set up with Devin? (e.g. added in Devin's Machine)",
+        choices: [
+            {
+                name: "No — use local setup (scan repo, answer a few questions)",
+                value: "local",
+            },
+            {
+                name: "Yes — use Devin to generate config (requires repo in Devin + DEVIN_API_KEY)",
+                value: "devin",
+            },
+        ],
+    });
+    return choice;
+}
 async function runSetup(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
-    const result = await (0, devin_setup_1.runSetupDevinAndValidate)({
-        cwd,
-        outputPath: options.outputPath ?? "docdrift.yaml",
-        force: options.force,
-        openPr: options.openPr,
-    });
+    const mode = await chooseSetupMode();
+    const hasDevinKey = Boolean(process.env.DEVIN_API_KEY?.trim());
+    let result;
+    let usedLocalFallback = false;
+    if (mode === "local" || (mode === "devin" && !hasDevinKey)) {
+        if (mode === "devin" && !hasDevinKey) {
+            console.log("\nDEVIN_API_KEY is not set. Using local setup instead.\n");
+        }
+        result = await (0, devin_setup_1.runSetupLocal)({
+            cwd,
+            outputPath: options.outputPath ?? "docdrift.yaml",
+            force: options.force,
+        });
+    }
+    else {
+        try {
+            result = await (0, devin_setup_1.runSetupDevinAndValidate)({
+                cwd,
+                outputPath: options.outputPath ?? "docdrift.yaml",
+                force: options.force,
+                openPr: options.openPr,
+            });
+        }
+        catch (err) {
+            console.error("\nDevin setup failed:", err instanceof Error ? err.message : String(err));
+            console.log("\nFalling back to local detection (repo fingerprint + heuristic)…\n");
+            usedLocalFallback = true;
+            result = await (0, devin_setup_1.runSetupLocal)({
+                cwd,
+                outputPath: options.outputPath ?? "docdrift.yaml",
+                force: options.force,
+            });
+        }
+    }
+    if (outputPath === node_path_1.default.resolve(cwd, "docdrift.yaml")) {
+        const { runValidate } = await Promise.resolve().then(() => __importStar(require("../index")));
+        await runValidate();
+    }
     console.log("\ndocdrift setup complete\n");
     console.log("  docdrift.yaml     written and validated");
     if (result.docDriftMd)
@@ -25,11 +111,30 @@ async function runSetup(options = {}) {
     }
     console.log("  .gitignore        updated");
     console.log("\nSummary: " + result.summary);
-    console.log("\nSession: " + result.sessionUrl);
+    if (result.sessionUrl)
+        console.log("\nSession: " + result.sessionUrl);
+    if (result.prUrl)
+        console.log("PR: " + result.prUrl);
     console.log("\nNext steps:");
-    console.log("  1. Add DEVIN_API_KEY to repo secrets (Settings > Secrets > Actions)");
-    console.log("  2. Ensure your repo is set up in Devin (Devin's Machine > Add repository)");
-    console.log("  3. Run: npx @devinnn/docdrift validate   — verify config");
-    console.log("  4. Run: npx @devinnn/docdrift detect     — check for drift");
-    console.log("  5. Run: npx @devinnn/docdrift run        — create Devin session (requires DEVIN_API_KEY)");
+    const usedLocal = mode === "local" || (mode === "devin" && !hasDevinKey) || usedLocalFallback;
+    if (usedLocal) {
+        console.log("  1. Run: npx @devinnn/docdrift validate   — verify config");
+        console.log("  2. Run: npx @devinnn/docdrift detect     — check for drift");
+        if (usedLocalFallback) {
+            console.log("  3. (Optional) Fix Devin and run setup again, or keep using local config");
+        }
+        else if (mode === "local") {
+            console.log("  3. (Optional) Add repo to Devin and set DEVIN_API_KEY to use Devin for setup next time");
+        }
+        else {
+            console.log("  3. (Optional) Set DEVIN_API_KEY and run setup again to use Devin");
+        }
+    }
+    else {
+        console.log("  1. Add DEVIN_API_KEY to repo secrets (Settings > Secrets > Actions)");
+        console.log("  2. Ensure your repo is set up in Devin (Devin's Machine > Add repository)");
+        console.log("  3. Run: npx @devinnn/docdrift validate   — verify config");
+        console.log("  4. Run: npx @devinnn/docdrift detect     — check for drift");
+        console.log("  5. Run: npx @devinnn/docdrift run        — create Devin session (requires DEVIN_API_KEY)");
+    }
 }

package/dist/src/setup/prompts.js

@@ -7,7 +7,11 @@ exports.SYSTEM_PROMPT = `You are a docdrift config expert. Given a repo fingerpr
 
 Minimal valid config uses: version: 2, specProviders (or pathMappings only for path-only setups), docsite, devin, policy.
 
-Example:
+Use paths from the fingerprint only. Do not invent or assume paths. If docsite or API/source path cannot be determined, add them to choices so the user can specify.
+
+Common repo layouts: packages/api + packages/docs, apps/api + apps/docs-site, docs/ at root, openapi/ at root, etc. Infer from foundPaths (docusaurusConfig, mkdocs, vitepressConfig, nextConfig, docsDirs, docsDirParents, openapi, exportScript, apiDirs).
+
+Example (replace {docsitePath} and {apiDir} with actual paths from the fingerprint):
 \`\`\`yaml
 version: 2
 specProviders:
@@ -16,12 +20,12 @@ specProviders:
       type: export
       command: "npm run openapi:export"
       outputPath: "openapi/generated.json"
-    published: "apps/docs-site/openapi/openapi.json"
-docsite: "apps/docs-site"
+    published: "{docsitePath}/openapi/openapi.json"
+docsite: "{docsitePath}"
 pathMappings:
-  - match: "apps/api/**"
-    impacts: ["apps/docs-site/docs/**", "apps/docs-site/openapi/**"]
-exclude: ["**/CHANGELOG*", "apps/docs-site/blog/**"]
+  - match: "{apiDir}/**"
+    impacts: ["{docsitePath}/docs/**", "{docsitePath}/openapi/**"]
+exclude: ["**/CHANGELOG*", "**/blog/**"]
 requireHumanReview: []
 mode: strict
 devin:
@@ -32,7 +36,7 @@ devin:
 policy:
   prCaps: { maxPrsPerDay: 5, maxFilesTouched: 30 }
   confidence: { autopatchThreshold: 0.8 }
-  allowlist: ["openapi/**", "apps/**"]
+  allowlist: ["openapi/**", "{docsitePath}/**"]
   verification:
     commands: ["npm run docs:gen", "npm run docs:build"]
   slaDays: 7
@@ -43,87 +47,29 @@ policy:
 ## Field rules
 
 - version: Always use 2.
-- specProviders: Array of spec sources. For OpenAPI: format "openapi3", current.type "export", current.command = npm script (e.g. "npm run openapi:export"), current.outputPath = where export writes (e.g. "openapi/generated.json"), published = docsite path (e.g. "apps/docs-site/openapi/openapi.json"). Never use raw script body; use "npm run <scriptName>".
-- docsite: Path to the docs site root (Docusaurus, Next.js docs, VitePress, MkDocs). Single string or array of strings.
-- pathMappings: Array of { match, impacts }. match = glob for source/API code; impacts = globs for doc files that may need updates when match changes.
-- mode: "strict" (only run on spec drift) or "auto" (also run when pathMappings match without spec drift). Default: strict.
-- policy.verification.commands: Commands to run after patching (e.g. "npm run docs:gen", "npm run docs:build"). Must exist in repo.
+- specProviders: Use paths from fingerprint. current.command = npm script from root or workspace (e.g. from foundPaths.exportScript or scripts containing openapi/swagger/spec). current.outputPath = where export writes (from exportScript.inferredOutputPath or openapi paths). published = path under docsite (e.g. {docsitePath}/openapi/openapi.json). Never use raw script body; use "npm run <scriptName>".
+- docsite: Path from fingerprint (docusaurusConfig dir, mkdocs dir, vitepressConfig dir, nextConfig dir, or docsDirParents). If missing, add to choices.
+- pathMappings: match = API/source dir from fingerprint (apiDirs[0] or exportScript.inferredApiDir), or "**/api/**" if unknown. impacts = docsite docs and openapi globs.
+- mode: "strict" or "auto". Default: strict.
+- policy.verification.commands: Commands that exist in repo (from rootPackage.scripts).
 - exclude: Globs to never touch (e.g. blog, CHANGELOG).
-- requireHumanReview: Globs that require human review when touched (e.g. guides).
+- requireHumanReview: Globs for guides (e.g. {docsitePath}/docs/guides/**).
 
 ## Path-only config (no OpenAPI)
 
-If no OpenAPI/spec found, use version: 2 with pathMappings only (no specProviders):
-\`\`\`yaml
-version: 2
-docsite: "apps/docs-site"
-pathMappings: [...]
-mode: auto
-\`\`\`
+If no OpenAPI/spec found, use version: 2 with pathMappings only (no specProviders). Use docsite path from fingerprint or add to choices.
 
 ## Common patterns
 
-- Docusaurus: docsite often has docusaurus.config.*; docs:gen may be "docusaurus -- gen-api-docs api"; published path often under docsite/openapi/.
-- Next/VitePress/MkDocs: docsite is the app root; look for docs/ or similar.
+- Docusaurus: foundPaths.docusaurusConfig; docsite = dir of config; published often under docsite/openapi/.
+- MkDocs/VitePress/Next: docsite = dir of mkdocs.yml or vitepress.config.* or next.config.*.
+- Generic: docsDirParents or dir containing docs/.
 
 ## Output rules
 
-1. Infer suggestedConfig from the fingerprint. Use version: 2. Only include fields you can confidently infer. Use existing paths and scripts from the fingerprint; do not invent paths that are not present.
-2. For each field where confidence is medium or low, OR where multiple valid options exist, add an entry to choices with: key (e.g. "specProviders.0.current.command"), question, options (array of { value, label, recommended? }), defaultIndex, help?, warning?, confidence ("high"|"medium"|"low").
-3. Add to skipQuestions the keys for which you are highly confident so the CLI will not ask the user.
-4. Prefer fewer, high-quality choices. If truly uncertain, set confidence to "low" and provide 2–3 options.
-5. Do not suggest paths that do not exist in the fingerprint. Prefer existing package.json scripts for export and verification commands.
-6. suggestedConfig must be a valid partial docdrift config; policy.allowlist and policy.verification.commands are required if you include policy. devin.apiVersion must be "v1" if you include devin.
-
-## Example docdrift.yaml
-# yaml-language-server: $schema=./docdrift.schema.json
-version: 2
-
-specProviders:
-  - format: openapi3
-    current:
-      type: export
-      command: "npm run openapi:export"
-      outputPath: "openapi/generated.json"
-    published: "apps/docs-site/openapi/openapi.json"
-
-docsite: "apps/docs-site"
-mode: strict
-
-pathMappings:
-  - match: "apps/api/**"
-    impacts: ["apps/docs-site/docs/**", "apps/docs-site/openapi/**"]
-
-exclude:
-  - "apps/docs-site/blog/**"
-  - "**/CHANGELOG*"
-
-requireHumanReview:
-  - "apps/docs-site/docs/guides/**"
-
-devin:
-  apiVersion: v1
-  unlisted: true
-  maxAcuLimit: 2
-  tags:
-    - docdrift
-  customInstructions:
-    - "DocDrift.md"
-
-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
+1. Infer suggestedConfig from the fingerprint. Use only paths and script names that appear in the fingerprint. Do not invent paths.
+2. For each field where confidence is medium or low, or path cannot be inferred, add an entry to choices (e.g. docsite, pathMappings.0.match).
+3. Add to skipQuestions the keys for which you are highly confident.
+4. If docsite or API path cannot be determined, add to choices so the user can specify.
+5. suggestedConfig must be a valid partial docdrift config; policy.allowlist and policy.verification.commands are required if you include policy. devin.apiVersion must be "v1" if you include devin.
 `;

package/dist/src/setup/repo-fingerprint.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferExportFromScript = inferExportFromScript;
 exports.buildRepoFingerprint = buildRepoFingerprint;
 exports.fingerprintHash = fingerprintHash;
 const node_crypto_1 = __importDefault(require("node:crypto"));
@@ -93,6 +94,103 @@ function findDirsNamed(cwd, name) {
     scan(cwd, 0);
     return out;
 }
+/** Infer API dir and optional output path from a script string (e.g. "tsx apps/api/scripts/export-openapi.ts"). */
+function inferExportFromScript(script, cwd) {
+    const result = {};
+    // Match tsx/node/npx path/to/file.ts or .js
+    const fileMatch = script.match(/\b(?:tsx|node|npx)\s+(.+?\.(?:ts|js|mjs|cjs))(?:\s|$)/);
+    if (fileMatch) {
+        const filePath = fileMatch[1].trim().replace(/\\/g, "/");
+        const absPath = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.resolve(cwd, filePath);
+        const relPath = node_path_1.default.relative(cwd, absPath).replace(/\\/g, "/");
+        const parts = relPath.split("/");
+        if (parts.length >= 2 && parts[parts.length - 1].toLowerCase().includes("export")) {
+            const dir = node_path_1.default.dirname(relPath);
+            if (dir.endsWith("/scripts") || dir.endsWith("scripts")) {
+                result.apiDir = node_path_1.default.dirname(dir);
+            }
+            else {
+                result.apiDir = dir;
+            }
+        }
+        else if (parts.length >= 1) {
+            result.apiDir = node_path_1.default.dirname(relPath) || ".";
+        }
+        if (node_fs_1.default.existsSync(absPath)) {
+            try {
+                const content = node_fs_1.default.readFileSync(absPath, "utf8");
+                const outMatch = content.match(/outputPath\s*[=:]\s*["'`]([^"'`]+)["'`]/);
+                if (outMatch)
+                    result.outputPath = outMatch[1];
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return result;
+}
+const EXPORT_SCRIPT_NAMES = [
+    "openapi:export",
+    "openapi:generate",
+    "openapi:build",
+    "spec:export",
+    "spec:generate",
+];
+const EXPORT_SCRIPT_PATTERN = /(openapi|swagger|spec).*(export|generate|build)/i;
+function findExportScript(scripts, cwd) {
+    const name = Object.keys(scripts).find((k) => EXPORT_SCRIPT_NAMES.includes(k)) ??
+        Object.keys(scripts).find((k) => EXPORT_SCRIPT_PATTERN.test(k));
+    if (!name)
+        return undefined;
+    const script = scripts[name];
+    if (!script || typeof script !== "string")
+        return undefined;
+    const { outputPath, apiDir } = inferExportFromScript(script, cwd);
+    return { scriptName: name, script, inferredApiDir: apiDir, inferredOutputPath: outputPath };
+}
+function collectApiDirCandidates(fileTree, exportScriptApiDir, workspacePackages) {
+    const candidates = [];
+    const seen = new Set();
+    if (exportScriptApiDir && !seen.has(exportScriptApiDir)) {
+        candidates.push(exportScriptApiDir);
+        seen.add(exportScriptApiDir);
+    }
+    const roots = ["packages", "apps", "libs", "services"];
+    for (const [relDir, names] of Object.entries(fileTree)) {
+        const parts = relDir.split("/").filter(Boolean);
+        const top = parts[0];
+        if (top && roots.includes(top) && names.some((n) => n === "api/" || n === "server/" || n === "backend/")) {
+            for (const name of names) {
+                if (name === "api/" || name === "server/" || name === "backend/") {
+                    const dir = parts.length > 0 ? `${relDir}/${name.replace(/\/$/, "")}` : name.replace(/\/$/, "");
+                    if (!seen.has(dir)) {
+                        candidates.push(dir);
+                        seen.add(dir);
+                    }
+                }
+            }
+        }
+        const lower = relDir.toLowerCase();
+        if ((lower.endsWith("/api") || lower.endsWith("/server") || lower.endsWith("/backend")) && !seen.has(relDir)) {
+            candidates.push(relDir);
+            seen.add(relDir);
+        }
+    }
+    for (const wp of workspacePackages) {
+        const pkgPath = wp.path.replace(/\\/g, "/");
+        if (pkgPath.toLowerCase().includes("api") && !seen.has(pkgPath)) {
+            candidates.push(pkgPath);
+            seen.add(pkgPath);
+        }
+        const treeEntry = fileTree[pkgPath];
+        if (treeEntry?.some((n) => n === "routes/" || n === "controllers/" || n === "src/") && !seen.has(pkgPath)) {
+            candidates.push(pkgPath);
+            seen.add(pkgPath);
+        }
+    }
+    return candidates;
+}
 function buildRepoFingerprint(cwd = process.cwd()) {
     const fileTree = {};
     walkDir(cwd, 0, fileTree);
@@ -137,16 +235,68 @@ function buildRepoFingerprint(cwd = process.cwd()) {
             }
         }
     }
-    const openapi = findMatchingFiles(cwd, (_, name) => /^openapi.*\.json$/i.test(name));
-    const swagger = findMatchingFiles(cwd, (_, name) => /^swagger.*\.json$/i.test(name));
+    const openapi = findMatchingFiles(cwd, (rel, name) => {
+        if (/^openapi.*\.(json|yaml|yml)$/i.test(name))
+            return true;
+        if (/^(api-spec|spec)\.(json|yaml|yml)$/i.test(name))
+            return true;
+        return false;
+    });
+    const openapiDirSpecs = findMatchingFiles(cwd, (rel) => {
+        const norm = rel.replace(/\\/g, "/");
+        return ((norm.startsWith("openapi/") && (norm.endsWith("openapi.json") || norm.endsWith("generated.json") || norm.endsWith("published.json"))) ||
+            norm === "openapi/openapi.json" ||
+            norm === "openapi/generated.json" ||
+            norm === "openapi/published.json");
+    });
+    const allOpenapi = [...openapi];
+    for (const p of openapiDirSpecs) {
+        if (!allOpenapi.includes(p))
+            allOpenapi.push(p);
+    }
+    const swagger = findMatchingFiles(cwd, (_, name) => /^swagger.*\.(json|yaml|yml)$/i.test(name));
     const docusaurusConfig = findMatchingFiles(cwd, (_, name) => name.startsWith("docusaurus.config."));
     const mkdocs = findMatchingFiles(cwd, (_, name) => name === "mkdocs.yml");
+    const vitepressConfig = findMatchingFiles(cwd, (_, name) => name.startsWith("vitepress.config."));
+    const nextConfig = findMatchingFiles(cwd, (_, name) => name.startsWith("next.config."));
     const docsDirs = findDirsNamed(cwd, "docs");
+    const docsDirParents = [];
+    for (const d of docsDirs) {
+        const parent = node_path_1.default.dirname(d);
+        if (parent && parent !== "." && !docsDirParents.includes(parent))
+            docsDirParents.push(parent);
+    }
+    let exportScript = findExportScript(rootPackage.scripts || {}, cwd);
+    if (!exportScript) {
+        for (const wp of workspacePackages) {
+            const wpCwd = node_path_1.default.join(cwd, wp.path);
+            exportScript = findExportScript(wp.scripts || {}, wpCwd);
+            if (exportScript) {
+                const apiDir = exportScript.inferredApiDir
+                    ? node_path_1.default.join(wp.path, exportScript.inferredApiDir).replace(/\\/g, "/")
+                    : wp.path;
+                exportScript = { ...exportScript, inferredApiDir: apiDir };
+                break;
+            }
+        }
+    }
+    const apiDirs = collectApiDirCandidates(fileTree, exportScript?.inferredApiDir, workspacePackages);
     return {
         fileTree,
         rootPackage,
         workspacePackages,
-        foundPaths: { openapi, swagger, docusaurusConfig, mkdocs, docsDirs },
+        foundPaths: {
+            openapi: allOpenapi,
+            swagger,
+            docusaurusConfig,
+            mkdocs,
+            vitepressConfig,
+            nextConfig,
+            docsDirs,
+            docsDirParents,
+            exportScript,
+            apiDirs,
+        },
     };
 }
 function fingerprintHash(fingerprint) {

package/dist/src/setup/setup-prompt.js

@@ -5,11 +5,46 @@
  * Devin's Machine, so Devin has full context.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCDRIFT_SETUP_OUTPUT_TAG = void 0;
 exports.buildSetupPrompt = buildSetupPrompt;
+/** XML tag used as strict delimiter for fallback parsing from chat transcript */
+exports.DOCDRIFT_SETUP_OUTPUT_TAG = "docdrift_setup_output";
 function attachmentBlock(urls) {
     return urls.map((url, i) => `- ATTACHMENT ${i + 1}: ${url}`).join("\n");
 }
-function buildSetupPrompt(attachmentUrls) {
+function strictOutputBlock() {
+    return [
+        "",
+        "STRICT OUTPUT FORMAT (REQUIRED FOR PARSING):",
+        "You MUST include this exact block in your final message so we can reliably parse it.",
+        "Format: open with <" +
+            exports.DOCDRIFT_SETUP_OUTPUT_TAG +
+            ">, then valid JSON, then close with </" +
+            exports.DOCDRIFT_SETUP_OUTPUT_TAG +
+            ">.",
+        "Example (escape quotes in strings as \\\"):",
+        "",
+        `<${exports.DOCDRIFT_SETUP_OUTPUT_TAG}>`,
+        '{"docdriftYaml":"# yaml...","docDriftMd":"# DocDrift...","workflowYml":"name: docdrift...","summary":"OpenAPI at..."}',
+        `</${exports.DOCDRIFT_SETUP_OUTPUT_TAG}>`,
+        "",
+        "Rules: Valid JSON only. Newlines in YAML/yml strings become \\n. Escape \" as \\\".",
+    ].join("\n");
+}
+function buildSetupPrompt(attachmentUrls, options) {
+    const openPr = options?.openPr ?? false;
+    const createFilesBlock = openPr
+        ? [
+            "",
+            "CREATE A PULL REQUEST:",
+            "- Create branch docdrift/setup from main",
+            "- Create docdrift.yaml, .docdrift/DocDrift.md, .github/workflows/docdrift.yml in the repo",
+            "- Commit with message: [docdrift] Add docdrift configuration",
+            "- Push and open a PR to main with title: [docdrift] Add docdrift configuration",
+            "- In the PR description, explain what was inferred (openapi export, docsite path, verification commands)",
+            "- You MUST still emit the strict output block below so we can validate the config",
+        ].join("\n")
+        : "Do NOT create files in the repo. Only produce the structured output and the strict output block.";
     return [
         "You are Devin. Task: set up docdrift for this repository.",
         "",
@@ -43,12 +78,12 @@ function buildSetupPrompt(attachmentUrls) {
         "   - Note: docdrift-sla-check.yml (daily cron for PRs open 7+ days) is added automatically",
         "",
         "OUTPUT:",
-        "Emit your final output in the provided structured output schema.",
+        "Emit your final output in the provided structured output schema if possible.",
         "- docdriftYaml: complete YAML string (no leading/trailing comments about the task)",
         "- docDriftMd: content for .docdrift/DocDrift.md, or empty string to omit",
         "- workflowYml: content for .github/workflows/docdrift.yml, or empty string to omit",
         "- summary: what you inferred (openapi export, docsite path, verification commands)",
-        "",
-        "Do NOT create files in the repo. Only produce the structured output.",
+        createFilesBlock,
+        strictOutputBlock(),
     ].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devinnn/docdrift",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "private": false,
   "description": "Detect and remediate documentation drift with Devin sessions",
   "main": "dist/src/index.js",