@devinnn/docdrift 0.1.7 → 0.1.12

package/README.md

@@ -2,198 +2,98 @@
 
 Docs that never lie: detect drift between merged code and docs, then open low-noise, evidence-grounded remediation via Devin sessions.
 
+## Table of contents
+
+- [Deliverables](#deliverables)
+- [Quick start](#quick-start)
+- [Modes & spec providers](#modes--spec-providers)
+- [Guides](#guides)
+- [Project docs layout](#project-docs-layout)
+
+---
+
 ## Deliverables
 
 - **npm package**: [@devinnn/docdrift](https://www.npmjs.com/package/@devinnn/docdrift) — TypeScript CLI (`docdrift`)
-  - `validate`
-  - `detect --base <sha> --head <sha>`
-  - `run --base <sha> --head <sha>`
-  - `status --since 24h`
+  - `validate` — Validate docdrift.yaml
+  - `detect --base <sha> --head <sha>` — Check for drift
+  - `run --base <sha> --head <sha>` — Full run with Devin
+  - `status --since 24h` — Show run status
   - `sla-check` — Check for doc-drift PRs open 7+ days and open a reminder issue
-- GitHub Action: `/Users/cameronking/Desktop/sideproject/docdrift/.github/workflows/devin-doc-drift.yml`
-- Repo-local config: `/Users/cameronking/Desktop/sideproject/docdrift/docdrift.yaml`
+  - `setup` — Interactive setup (Devin analyzes repo, generates v2 docdrift.yaml)
+  - `generate-yaml` — Generate config from repo fingerprint `[--output path] [--force]`
+- GitHub Action: `.github/workflows/devin-doc-drift.yml`
+- Repo-local config: `docdrift.yaml`
 - Demo API + OpenAPI exporter + driftable docs
-- PR template + Loom script
-
-## Why this is low-noise
-
-- **Single session, single PR** — One Devin session handles the whole docsite (API reference + guides).
-- **Gate on API spec diff** — We only run when OpenAPI drift is detected; no session for docs-check-only failures.
-- **requireHumanReview** — When the PR touches guides/prose, we open an issue after the PR to direct attention.
-- **7-day SLA** — If a doc-drift PR is open 7+ days, we open a reminder issue (configurable `slaDays`; use `sla-check` CLI or cron workflow).
-- Confidence gating and allowlist/exclude enforcement.
-- Idempotency key prevents duplicate actions for same repo/SHAs/action.
-
-## Detection and gate
-
-- **Gate:** We only run a Devin session when **OpenAPI drift** is detected. No drift → no session.
-- Tier 1: OpenAPI drift (`openapi/generated.json` vs published spec)
-- Tier 2: Heuristic path impacts from docAreas (e.g. `apps/api/src/auth/**` → guides)
-
-Output artifacts (under `.docdrift/`):
-
-- `drift_report.json`
-- `metrics.json` (after `run`)
+- PR template + [Loom script](loom.md)
 
-When you run docdrift as a package (e.g. `npx docdrift` or from another repo), all of this is written to **that repo’s** `.docdrift/` — i.e. the current working directory where the CLI is invoked, not inside the package. Add `.docdrift/` to the consuming repo’s `.gitignore` if you don’t want to commit run artifacts.
+---
 
-## Core flow (`docdrift run`)
-
-1. Validate config and command availability.
-2. Build drift report. **Gate:** If no OpenAPI drift, exit (no session).
-3. Policy decision (`OPEN_PR | UPDATE_EXISTING_PR | OPEN_ISSUE | NOOP`).
-4. Build one aggregated evidence bundle for the whole docsite.
-5. One Devin session with whole-docsite prompt; poll to terminal status.
-6. If PR opened and touches `requireHumanReview` paths → create issue to direct attention.
-7. Surface result via GitHub commit comment; open issue on blocked/low-confidence paths.
-8. Persist state (including `lastDocDriftPrUrl` for SLA); write `.docdrift/metrics.json`.
-
-## Where the docs are (this repo)
-
-| Path                                       | Purpose                                                                 |
-| ------------------------------------------ | ----------------------------------------------------------------------- |
-| `apps/docs-site/openapi/openapi.json`      | Published OpenAPI spec (docdrift updates this when drift is detected).  |
-| `apps/docs-site/docs/api/`                 | API reference MDX generated from the spec (`npm run docs:gen`).        |
-| `apps/docs-site/docs/guides/auth.md`       | Conceptual auth guide (updated only for conceptual drift).              |
-
-The docsite is a Docusaurus app with `docusaurus-plugin-openapi-docs`. The **generated** spec from code lives at `openapi/generated.json` (from `npm run openapi:export`). Drift = generated vs published differ. Verification runs `docs:gen` and `docs:build` so the docsite actually builds.
-
-## How Devin updates them
-
-1. **Evidence bundle** — Docdrift builds a tarball with the drift report, OpenAPI diff, and impacted doc snippets, and uploads it to the Devin API as session attachments.
-2. **Devin session** — Devin is prompted (see `src/devin/prompts.ts`) to update only files under the allowlist (`openapi/**`, `apps/docs-site/**`), make minimal correct edits, run verification (`npm run docs:gen`, `npm run docs:build`), and open **one PR** per doc area with a clear description.
-3. **PR** — Devin updates `apps/docs-site/openapi/openapi.json` to match the current API, runs `docs:gen` to regenerate API reference MDX, and opens a pull request. You review and merge; the docsite builds and the docs are updated.
-
-So the “fix” is a **PR opened by Devin** that you merge; the repo’s docs don’t change until that PR is merged.
-
-## Local usage
+## Quick start
 
 ```bash
-npm install
-npx tsx src/cli.ts validate
-npm run openapi:export
-npx tsx src/cli.ts detect --base <sha> --head <sha>
-DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha> npx tsx src/cli.ts run --base <sha> --head <sha>
+# Interactive setup (requires DEVIN_API_KEY; add repo in Devin Machine first)
+npx @devinnn/docdrift setup
+
+# Or generate config only (scriptable)
+npx @devinnn/docdrift generate-yaml --output docdrift.yaml --force
 ```
 
-## Local demo (no GitHub)
-
-You can run a full end-to-end demo locally with no remote repo. Ensure `.env` has `DEVIN_API_KEY` (and optionally `GITHUB_TOKEN` only when you have a real repo).
-
-1. **One-time setup (already done if you have two commits with drift)**
-   - Git is inited; baseline commit has docs in sync with API.
-   - A later commit changes `apps/api/src/model.ts` (e.g. `name` → `fullName`) and runs `npm run openapi:export`, so `openapi/generated.json` drifts from `docs/reference/openapi.json`.
-
-2. **Run the pipeline**
-
-   ```bash
-   npm install
-   npx tsx src/cli.ts validate
-   npx tsx src/cli.ts detect --base b0f624f --head 6030902
-   ```
-
-   - Use your own `git log --oneline -3` to get `base` (older) and `head` (newer) SHAs if you recreated the demo.
+→ [**Setup guide**](docs/guides/setup.md) — Setup options, prerequisites
 
-3. **Run with Devin (no GitHub calls)**  
-   Omit `GITHUB_TOKEN` so the CLI does not post comments or create issues. Devin session still runs; results are printed to stdout and written to `.docdrift/state.json` and `metrics.json`.
+---
 
-   ```bash
-   export $(grep -v '^#' .env | xargs)
-   unset GITHUB_TOKEN GITHUB_REPOSITORY GITHUB_SHA
-   npx tsx src/cli.ts run --base b0f624f --head 6030902
-   ```
+## Modes & spec providers
 
-   - `run` can take 1–3 minutes while the Devin session runs.
+| Mode | When it runs |
+| ---- | -------------- |
+| **strict** (default) | Only when spec drift is detected (OpenAPI, GraphQL, etc.). No spec drift → no Devin session. |
+| **auto** | Also when pathMappings match (file changes hit `match` patterns). |
 
-4. **What you’ll see**
-   - `.docdrift/drift_report.json` — drift items (e.g. OpenAPI `name` → `fullName`).
-   - `.docdrift/evidence/<runId>/` — evidence bundles and OpenAPI diff.
-   - Stdout — per–doc-area outcome (e.g. PR opened by Devin or blocked).
-   - `.docdrift/metrics.json` — counts and timing.
+| Spec formats | openapi3, swagger2, graphql, fern, postman |
 
-## CI usage
+→ [**Configuration**](docs/guides/configuration.md) — Modes, spec providers, full config
 
-- Add secret: `DEVIN_API_KEY`
-- Push to `main` or run `workflow_dispatch`
-- Action uploads:
-  - `.docdrift/drift_report.json`
-  - `.docdrift/evidence/**`
-  - `.docdrift/metrics.json`
+---
 
-## Run on GitHub
+## Guides
 
-1. **Create a repo** on GitHub (e.g. `your-org/docdrift`), then add the remote and push:
+| Guide | What’s inside |
+| ----- | -------------- |
+| [Setup](docs/guides/setup.md) | `setup` vs `generate-yaml`, prerequisites |
+| [Configuration](docs/guides/configuration.md) | Modes, spec providers; links to full schema |
+| [How it works](docs/guides/how-it-works.md) | Detection, gate, core flow, low-noise design |
+| [Ecosystems](docs/guides/ecosystems.md) | OpenAPI, FastAPI, Fern, GraphQL, Mintlify, Postman, monorepos |
+| [Local development](docs/guides/local-development.md) | Local usage, demo without GitHub |
+| [CI & GitHub](docs/guides/ci-github.md) | GitHub Actions, secrets, demo on GitHub |
+| [Using in another repo](docs/guides/consuming-repo.md) | Published package, CLI, GitHub Actions |
+| [Publishing](docs/guides/publishing.md) | Publishing the npm package |
+| [Loom script](loom.md) | Recording script for demos |
 
-   ```bash
-   git remote add origin https://github.com/your-org/docdrift.git
-   git push -u origin main
-   ```
+### Reference
 
-2. **Add secret**  
-   Repo → **Settings** → **Secrets and variables** → **Actions** → **New repository secret**
-   - Name: `DEVIN_API_KEY`
-   - Value: your Devin API key (same as in `.env` locally)
+- [docdrift.yaml](docdrift-yml.md) — Full configuration schema and validation
 
-   `GITHUB_TOKEN` is provided automatically; the workflow uses it for commit comments and issues.
+---
 
-3. **Trigger the workflow**
-   - **Push to `main`** — runs on every push (compares previous commit vs current).
-   - **Manual run** — **Actions** tab → **devin-doc-drift** → **Run workflow** (uses `HEAD` and `HEAD^` as head/base).
+## Project docs layout (this repo)
 
-## See it work (demo on GitHub)
+| Path | Purpose |
+| ---- | ------- |
+| `apps/docs-site/openapi/openapi.json` | Published OpenAPI spec (docdrift updates when drift detected) |
+| `apps/docs-site/docs/api/` | API reference MDX (`npm run docs:gen`) |
+| `apps/docs-site/docs/guides/` | Conceptual guides (auth, etc.) |
 
-This repo has **intentional drift**: the API has been expanded (new fields `fullName`, `avatarUrl`, `createdAt`, `role` and new endpoint `GET /v1/users` with pagination), but **docs are unchanged** (`docs/reference/openapi.json` and `docs/reference/api.md` still describe the old single-endpoint, `id`/`name`/`email` only). Running docdrift will detect that and hand a large diff to Devin to fix via a PR. To see it:
+Generated spec from code: `openapi/generated.json` (`npm run openapi:export`). Drift = generated vs published differ.
 
-1. **Create a new GitHub repo** (e.g. `docdrift-demo`) so you have a clean place to run the workflow.
-2. **Push this project with full history** (so both commits are on `main`):
-   ```bash
-   git remote add origin https://github.com/YOUR_ORG/docdrift-demo.git
-   git push -u origin main
-   ```
-3. **Add secret** in that repo: **Settings** → **Secrets and variables** → **Actions** → `DEVIN_API_KEY` = your Devin API key.
-4. **Trigger the workflow**
-   - Either push another small commit (e.g. README tweak), or
-   - **Actions** → **devin-doc-drift** → **Run workflow**.
-5. **Where to look**
-   - **Actions** → open the run → **Run Doc Drift** step: the step logs print JSON with `sessionUrl`, `prUrl`, and `outcome` per doc area. Open any `sessionUrl` in your browser to see the Devin session.
-   - **Artifacts**: download **docdrift-artifacts** for `.docdrift/drift_report.json`, `.docdrift/metrics.json`, and evidence.
-   - **Devin dashboard**: sessions are tagged `docdrift`; you’ll see the run there once the step completes (often 1–3 minutes).
+---
 
-## Using in another repo (published package)
+## Why low-noise
 
-Once published to npm, any repo can use the CLI locally or in GitHub Actions.
+- **Single session, single PR** — One Devin session for the whole docsite
+- **Gate on spec diff** — No session when no drift (strict mode)
+- **requireHumanReview** — Issue when PR touches guides/prose
+- **7-day SLA** — Reminder issue for stale doc-drift PRs
+- **Confidence gating** — Allowlist, exclude, idempotency
 
-1. **Setup** — `npx @devinnn/docdrift setup` (requires `DEVIN_API_KEY`). Devin generates `docdrift.yaml`, `.docdrift/DocDrift.md`, and `.github/workflows/docdrift.yml`. Prerequisite: add your repo in Devin's Machine first. Or add `docdrift.yaml` manually (see `docdrift-yml.md`).
-2. **CLI**
-   ```bash
-   npx @devinnn/docdrift validate
-   npx @devinnn/docdrift detect --base <base-sha> --head <head-sha>
-   # With env for run:
-   DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha> npx @devinnn/docdrift run --base <base-sha> --head <head-sha>
-   ```
-3. **GitHub Actions** — add a step that runs the CLI (e.g. after checkout and setting base/head):
-   ```yaml
-   - run: npx @devinnn/docdrift run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }}
-     env:
-       DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
-       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-       GITHUB_REPOSITORY: ${{ github.repository }}
-       GITHUB_SHA: ${{ github.sha }}
-   ```
-   Add repo secret `DEVIN_API_KEY`; `GITHUB_TOKEN` is provided by the runner.
-
-## Publishing the package
-
-- Set `"private": false` in `package.json` (or omit it).
-- Set `"repository": { "type": "git", "url": "https://github.com/your-org/docdrift.git" }`.
-- Run `pnpm build` (or `npm run build`), then `npm publish` (for a scoped package use `npm publish --access public`).
-- Only the `dist/` directory is included (`files` in `package.json`). Consumers get the built CLI; they provide their own `docdrift.yaml` in their repo.
-
-## Demo scenario
-
-- Autogen drift: rename a field in `apps/api/src/model.ts`, merge to `main`, observe docs PR path.
-- Conceptual drift: change auth behavior under `apps/api/src/auth/**`, merge to `main`, observe single escalation issue.
-
-## Loom
-
-See `/Users/cameronking/Desktop/sideproject/docdrift/loom.md` for the minute-by-minute recording script.
+→ [**How it works**](docs/guides/how-it-works.md) — Detection, flow, evidence bundle

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,6 +64,43 @@ function getSchemaPath() {
     }
     return schemaPath;
 }
+/** 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: "",
+    };
+}
 function parseSetupOutput(session) {
     const raw = session?.structured_output ?? session?.data?.structured_output;
     if (!raw || typeof raw !== "object")

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,28 @@ 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);
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devinnn/docdrift",
-  "version": "0.1.7",
+  "version": "0.1.12",
   "private": false,
   "description": "Detect and remediate documentation drift with Devin sessions",
   "main": "dist/src/index.js",
@@ -17,7 +17,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": ""
+    "url": "git+https://github.com/cameronking4/docdrift.git"
+  },
+  "homepage": "https://github.com/cameronking4/docdrift#readme",
+  "bugs": {
+    "url": "https://github.com/cameronking4/docdrift/issues"
   },
   "keywords": [
     "docs",
@@ -27,6 +31,9 @@
     "github-actions"
   ],
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",