@devinnn/docdrift 0.1.6 → 0.1.11

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. **In the consuming repo** add a `docdrift.yaml` at the root (see this repo’s `docdrift.yaml` and `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/schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PatchResultSchema = exports.PatchPlanSchema = void 0;
+exports.PatchResultSchema = exports.SetupOutputSchema = exports.PatchPlanSchema = void 0;
 exports.PatchPlanSchema = {
     type: "object",
     additionalProperties: false,
@@ -59,6 +59,27 @@ exports.PatchPlanSchema = {
         },
     },
 };
+/** Structured output for docdrift setup (Devin generates config files) */
+exports.SetupOutputSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["docdriftYaml", "summary"],
+    properties: {
+        docdriftYaml: { type: "string", description: "Full docdrift.yaml content, valid per schema" },
+        docDriftMd: {
+            type: "string",
+            description: "Content for .docdrift/DocDrift.md custom instructions (project-specific guidance for Devin)",
+        },
+        workflowYml: {
+            type: "string",
+            description: "Content for .github/workflows/docdrift.yml — must use npx @devinnn/docdrift for validate and run",
+        },
+        summary: {
+            type: "string",
+            description: "Brief summary of what you inferred (openapi paths, docsite, verification commands)",
+        },
+    },
+};
 exports.PatchResultSchema = {
     type: "object",
     additionalProperties: false,

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

@@ -0,0 +1,157 @@
+"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.runSetupDevin = runSetupDevin;
+exports.runSetupDevinAndValidate = runSetupDevinAndValidate;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+require("dotenv/config");
+const v1_1 = require("../devin/v1");
+const schemas_1 = require("../devin/schemas");
+const setup_prompt_1 = require("./setup-prompt");
+const generate_yaml_1 = require("./generate-yaml");
+const index_1 = require("../index");
+const onboard_1 = require("./onboard");
+/** Resolve path to docdrift.schema.json in the package */
+function getSchemaPath() {
+    // dist/src/setup -> ../../../ ; src/setup (tsx) -> ../..
+    const candidates = [
+        node_path_1.default.join(__dirname, "../../../docdrift.schema.json"),
+        node_path_1.default.join(__dirname, "../../docdrift.schema.json"),
+    ];
+    const schemaPath = candidates.find((p) => node_fs_1.default.existsSync(p));
+    if (!schemaPath) {
+        throw new Error(`docdrift.schema.json not found. Tried: ${candidates.join(", ")}`);
+    }
+    return schemaPath;
+}
+function parseSetupOutput(session) {
+    const raw = session?.structured_output ?? session?.data?.structured_output;
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    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: "",
+    };
+}
+async function runSetupDevin(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
+    const apiKey = process.env.DEVIN_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error("DEVIN_API_KEY is required for setup. Set it in .env or export.");
+    }
+    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("Uploading schema…\n");
+    const schemaPath = getSchemaPath();
+    const attachmentUrl = await (0, v1_1.devinUploadAttachment)(apiKey, schemaPath);
+    const prompt = (0, setup_prompt_1.buildSetupPrompt)([attachmentUrl]);
+    process.stdout.write("Creating Devin session…\n");
+    const session = await (0, v1_1.devinCreateSession)(apiKey, {
+        prompt,
+        unlisted: true,
+        max_acu_limit: 2,
+        tags: ["docdrift", "setup"],
+        attachments: [attachmentUrl],
+        structured_output: {
+            schema: schemas_1.SetupOutputSchema,
+        },
+        metadata: { purpose: "docdrift-setup" },
+    });
+    process.stdout.write("Devin is analyzing the repo and generating config…\n");
+    process.stdout.write(`Session: ${session.url}\n`);
+    const finalSession = await (0, v1_1.pollUntilTerminal)(apiKey, session.session_id, 15 * 60_000);
+    const result = parseSetupOutput(finalSession);
+    if (!result) {
+        throw new Error("Devin session did not return valid setup output. Check the session for details: " + session.url);
+    }
+    result.sessionUrl = session.url;
+    // Write files
+    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) {
+        (0, onboard_1.ensureDocdriftDir)(cwd);
+        const docDriftPath = node_path_1.default.resolve(cwd, ".docdrift", "DocDrift.md");
+        node_fs_1.default.writeFileSync(docDriftPath, result.docDriftMd, "utf8");
+    }
+    if (result.workflowYml) {
+        const workflowsDir = node_path_1.default.resolve(cwd, ".github", "workflows");
+        node_fs_1.default.mkdirSync(workflowsDir, { recursive: true });
+        node_fs_1.default.writeFileSync(node_path_1.default.join(workflowsDir, "docdrift.yml"), result.workflowYml, "utf8");
+        (0, onboard_1.addSlaCheckWorkflow)(cwd);
+    }
+    (0, onboard_1.ensureGitignore)(cwd);
+    const validation = (0, generate_yaml_1.validateGeneratedConfig)(outputPath);
+    if (!validation.ok) {
+        throw new Error("Generated config failed validation:\n" + validation.errors.join("\n"));
+    }
+    return result;
+}
+async function runSetupDevinAndValidate(options) {
+    const result = await runSetupDevin(options);
+    const cwd = options.cwd ?? process.cwd();
+    const outputPath = node_path_1.default.resolve(cwd, options.outputPath ?? "docdrift.yaml");
+    if (outputPath === node_path_1.default.resolve(cwd, "docdrift.yaml")) {
+        try {
+            await (0, index_1.runValidate)();
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    }
+    return result;
+}

package/dist/src/setup/index.js

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

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureDocdriftDir = ensureDocdriftDir;
 exports.createCustomInstructionsFile = createCustomInstructionsFile;
 exports.ensureGitignore = ensureGitignore;
+exports.addSlaCheckWorkflow = addSlaCheckWorkflow;
 exports.addGitHubWorkflow = addGitHubWorkflow;
 exports.runOnboarding = runOnboarding;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -19,7 +20,129 @@ const GITIGNORE_BLOCK = `
 .docdrift/state.json
 .docdrift/run-output.json
 `;
-const WORKFLOW_CONTENT = "name: docdrift\n\non:\n  push:\n    branches: [\"main\"]\n  pull_request:\n    branches: [\"main\"]\n  workflow_dispatch:\n\njobs:\n  docdrift:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n      pull-requests: write\n      issues: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"20\"\n\n      - run: npm install\n\n      - name: Determine SHAs\n        id: shas\n        run: |\n          if [ \"${{ github.event_name }}\" = \"pull_request\" ]; then\n            HEAD_SHA=\"${{ github.event.pull_request.head.sha }}\"\n            BASE_SHA=\"${{ github.event.pull_request.base.sha }}\"\n          else\n            HEAD_SHA=\"${{ github.sha }}\"\n            BASE_SHA=\"${{ github.event.before }}\"\n            if [ -z \"$BASE_SHA\" ] || [ \"$BASE_SHA\" = \"0000000000000000000000000000000000000000\" ]; then\n              BASE_SHA=\"$(git rev-parse HEAD^)\"\n            fi\n          fi\n          echo \"head=${HEAD_SHA}\" >> $GITHUB_OUTPUT\n          echo \"base=${BASE_SHA}\" >> $GITHUB_OUTPUT\n          echo \"pr_number=${{ github.event.pull_request.number || '' }}\" >> $GITHUB_OUTPUT\n\n      - name: Validate config\n        run: npx docdrift validate\n\n      - name: Run Doc Drift\n        env:\n          DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          GITHUB_REPOSITORY: ${{ github.repository }}\n          GITHUB_SHA: ${{ github.sha }}\n          GITHUB_EVENT_NAME: ${{ github.event_name }}\n          GITHUB_PR_NUMBER: ${{ steps.shas.outputs.pr_number }}\n        run: |\n          PR_ARGS=\"\"\n          if [ -n \"$GITHUB_PR_NUMBER\" ]; then\n            PR_ARGS=\"--trigger pull_request --pr-number $GITHUB_PR_NUMBER\"\n          fi\n          npx docdrift run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }} $PR_ARGS\n\n      - name: Upload artifacts\n        if: always()\n        uses: actions/upload-artifact@v4\n        with:\n          name: docdrift-artifacts\n          path: |\n            .docdrift/drift_report.json\n            .docdrift/metrics.json\n            .docdrift/run-output.json\n            .docdrift/evidence/**\n            .docdrift/state.json\n";
+const WORKFLOW_CONTENT = `name: docdrift
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  docdrift:
+    if: github.event_name != 'pull_request' || !startsWith(github.event.pull_request.head.ref, 'docdrift/')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: npm install
+
+      - name: Determine SHAs
+        id: shas
+        run: |
+          if [ "\$\{\{ github.event_name \}\}" = "pull_request" ]; then
+            HEAD_SHA="\$\{\{ github.event.pull_request.head.sha \}\}"
+            BASE_SHA="\$\{\{ github.event.pull_request.base.sha \}\}"
+          else
+            HEAD_SHA="\$\{\{ github.sha \}\}"
+            BASE_SHA="\$\{\{ github.event.before \}\}"
+            if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+              BASE_SHA="$(git rev-parse HEAD^)"
+            fi
+          fi
+          echo "head=\${HEAD_SHA}" >> $GITHUB_OUTPUT
+          echo "base=\${BASE_SHA}" >> $GITHUB_OUTPUT
+          echo "pr_number=\$\{\{ github.event.pull_request.number || '' \}\}" >> $GITHUB_OUTPUT
+
+      - name: Restore docdrift state
+        uses: actions/cache/restore@v4
+        id: docdrift-cache
+        with:
+          path: .docdrift
+          key: docdrift-state-\$\{\{ github.event_name \}\}-\$\{\{ github.event.pull_request.number || 'main' \}\}-\$\{\{ github.run_id \}\}
+          restore-keys: |
+            docdrift-state-\$\{\{ github.event_name \}\}-\$\{\{ github.event.pull_request.number || 'main' \}\}-
+
+      - name: Validate config
+        run: npx @devinnn/docdrift validate
+
+      - name: Run Doc Drift
+        env:
+          DEVIN_API_KEY: \$\{\{ secrets.DEVIN_API_KEY \}\}
+          GITHUB_TOKEN: \$\{\{ secrets.GITHUB_TOKEN \}\}
+          GITHUB_REPOSITORY: \$\{\{ github.repository \}\}
+          GITHUB_SHA: \$\{\{ github.sha \}\}
+          GITHUB_EVENT_NAME: \$\{\{ github.event_name \}\}
+          GITHUB_PR_NUMBER: \$\{\{ steps.shas.outputs.pr_number \}\}
+        run: |
+          PR_ARGS=""
+          if [ -n "$GITHUB_PR_NUMBER" ]; then
+            PR_ARGS="--trigger pull_request --pr-number $GITHUB_PR_NUMBER"
+          fi
+          npx @devinnn/docdrift run --base \$\{\{ steps.shas.outputs.base \}\} --head \$\{\{ steps.shas.outputs.head \}\} $PR_ARGS
+
+      - name: Save docdrift state
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: .docdrift
+          key: docdrift-state-\$\{\{ github.event_name \}\}-\$\{\{ github.event.pull_request.number || 'main' \}\}-\$\{\{ github.run_id \}\}
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docdrift-artifacts
+          path: |
+            .docdrift/drift_report.json
+            .docdrift/metrics.json
+            .docdrift/run-output.json
+            .docdrift/evidence/**
+            .docdrift/state.json
+`;
+const SLA_CHECK_WORKFLOW_CONTENT = `name: docdrift-sla-check
+
+on:
+  schedule:
+    # Run daily at 09:00 UTC (checks for doc-drift PRs open 7+ days)
+    - cron: "0 9 * * *"
+  workflow_dispatch:
+
+jobs:
+  sla-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: npm install
+
+      - name: Validate config
+        run: npx @devinnn/docdrift validate
+
+      - name: Run SLA check
+        env:
+          GITHUB_TOKEN: \$\{\{ secrets.GITHUB_TOKEN \}\}
+          GITHUB_REPOSITORY: \$\{\{ github.repository \}\}
+        run: npx @devinnn/docdrift sla-check
+`;
 function ensureDocdriftDir(cwd) {
     const dir = node_path_1.default.resolve(cwd, DOCDRIFT_DIR);
     node_fs_1.default.mkdirSync(dir, { recursive: true });
@@ -54,11 +177,16 @@ function ensureGitignore(cwd) {
     const toAppend = content.endsWith("\n") ? GITIGNORE_BLOCK.trimStart() : GITIGNORE_BLOCK;
     node_fs_1.default.writeFileSync(gitignorePath, content + toAppend, "utf8");
 }
+function addSlaCheckWorkflow(cwd) {
+    const workflowsDir = node_path_1.default.resolve(cwd, ".github", "workflows");
+    node_fs_1.default.mkdirSync(workflowsDir, { recursive: true });
+    node_fs_1.default.writeFileSync(node_path_1.default.join(workflowsDir, "docdrift-sla-check.yml"), SLA_CHECK_WORKFLOW_CONTENT, "utf8");
+}
 function addGitHubWorkflow(cwd) {
     const workflowsDir = node_path_1.default.resolve(cwd, ".github", "workflows");
     node_fs_1.default.mkdirSync(workflowsDir, { recursive: true });
-    const workflowPath = node_path_1.default.join(workflowsDir, "docdrift.yml");
-    node_fs_1.default.writeFileSync(workflowPath, WORKFLOW_CONTENT, "utf8");
+    node_fs_1.default.writeFileSync(node_path_1.default.join(workflowsDir, "docdrift.yml"), WORKFLOW_CONTENT, "utf8");
+    addSlaCheckWorkflow(cwd);
 }
 function runOnboarding(cwd, choices) {
     const created = [];
@@ -75,6 +203,7 @@ function runOnboarding(cwd, choices) {
     if (choices.addWorkflow) {
         addGitHubWorkflow(cwd);
         created.push(".github/workflows/docdrift.yml");
+        created.push(".github/workflows/docdrift-sla-check.yml");
     }
     return { created };
 }

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

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Prompt for Devin setup session — Devin analyzes the repo and generates
+ * docdrift.yaml, DocDrift.md, and GitHub workflow. The repo is already in
+ * Devin's Machine, so Devin has full context.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSetupPrompt = buildSetupPrompt;
+function attachmentBlock(urls) {
+    return urls.map((url, i) => `- ATTACHMENT ${i + 1}: ${url}`).join("\n");
+}
+function buildSetupPrompt(attachmentUrls) {
+    return [
+        "You are Devin. Task: set up docdrift for this repository.",
+        "",
+        "This repo is already loaded in your environment. Analyze it and produce the docdrift configuration files.",
+        "",
+        "ATTACHMENTS (read these for spec and schema):",
+        attachmentBlock(attachmentUrls),
+        "",
+        "REQUIREMENTS:",
+        "",
+        "1) docdrift.yaml (REQUIRED)",
+        "   - Use version: 2",
+        "   - Use specProviders format with format: openapi3",
+        "   - Infer: current (type: export, command, outputPath), published path",
+        "   - Set docsite to your docs root (e.g. docs, apps/docs-site)",
+        "   - devin: apiVersion v1, unlisted true, maxAcuLimit 2, tags [docdrift]",
+        "   - If you find an OpenAPI/swagger file or export script, use it",
+        "   - policy: prCaps, confidence, allowlist (paths Devin may edit), verification.commands (e.g. npm run docs:build, npm run build)",
+        "   - Add schema comment at top: # yaml-language-server: $schema=https://unpkg.com/@devinnn/docdrift/docdrift.schema.json",
+        "",
+        "2) .docdrift/DocDrift.md (RECOMMENDED)",
+        "   - Starter custom instructions: PR title prefix [docdrift], tone, project-specific guidance",
+        "   - If you include this, set devin.customInstructions: [.docdrift/DocDrift.md] in docdrift.yaml",
+        "",
+        "3) .github/workflows/docdrift.yml (RECOMMENDED)",
+        "   - CRITICAL: Use npx @devinnn/docdrift (not npx docdrift)",
+        "   - Steps: checkout, setup-node 20, Determine SHAs (base/head for push or PR), Validate config, Run Doc Drift",
+        "   - Env: DEVIN_API_KEY, GITHUB_TOKEN, GITHUB_REPOSITORY, GITHUB_SHA",
+        "   - Skip when PR head ref starts with docdrift/ (avoid feedback loop)",
+        "   - Upload .docdrift artifacts (drift_report.json, metrics.json, evidence, state.json)",
+        "   - 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.",
+        "- 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.",
+    ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devinnn/docdrift",
-  "version": "0.1.6",
+  "version": "0.1.11",
   "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",
@@ -61,4 +68,4 @@
     "vitest": "^3.0.5",
     "zod-to-json-schema": "^3.25.1"
   }
-}
+}