depbot-policy 0.1.0 → 0.2.0

package/README.md

@@ -39,6 +39,7 @@ npx depbot-policy generate
 - [Why](#why)
 - [Quick start](#quick-start)
 - [CLI](#cli)
+- [Writing a policy with AI](#writing-a-policy-with-ai)
 - [Policy reference](#policy-reference)
 - [What gets generated](#what-gets-generated)
 - [Repository setup](#repository-setup)
@@ -86,6 +87,9 @@ git commit -m "Manage Dependabot with depbot-policy"
 
 Then do the one-time [repository setup](#repository-setup), so that auto-merge waits for CI.
 
+Prefer to describe what you want? `npx depbot-policy init --describe "…"` has an AI model (Claude
+or Gemini) write the policy for you. See [Writing a policy with AI](#writing-a-policy-with-ai).
+
 To change anything later, edit `depbot.policy.yml` and run `npx depbot-policy generate` again.
 Don't edit the generated files by hand. [`check`](#keeping-files-in-sync-in-ci) catches that.
 
@@ -95,7 +99,7 @@ Don't edit the generated files by hand. [`check`](#keeping-files-in-sync-in-ci)
 depbot-policy <command> [options]
 
 Commands:
-  init        Create a starter depbot.policy.yml
+  init        Create a starter depbot.policy.yml, or one written by AI with --describe
   generate    Write .github/dependabot.yml and the auto-merge workflow
   check       Fail if the policy is invalid or the generated files are out of date
   reviewer    Print this week's reviewer from review.rotation
@@ -104,6 +108,17 @@ Options:
   --policy <file>   Policy file (default: depbot.policy.yml)
   --out <dir>       Repository root to write to or check (default: .)
   --dry-run         generate: print the files instead of writing them
+  --describe <text> init: have an AI model write the policy from a description
+                    (needs ANTHROPIC_API_KEY or GEMINI_API_KEY)
+  --model <id>      init --describe: which model to use (default: claude-opus-5-5)
+                      Claude models:
+                      claude-opus-5-5         Recommended: best balance of quality and cost, about 3–5¢ per policy
+                      claude-sonnet-5-5       Faster and cheaper, about 2¢ per policy
+                      claude-haiku-5-5        Fastest and cheapest, well under 1¢ per policy
+                      claude-fable-5-1        Most capable and most expensive, about 8–13¢ per policy
+                      Gemini models:
+                      gemini-3-flash-preview  Fast and cheap, under 1¢ per policy (free tier available)
+                      gemini-3.1-pro-preview  More capable, about 2–3¢ per policy
   --force           init: overwrite an existing policy file
   --date <date>     reviewer: use this date instead of today (e.g. 2026-10-12)
   -h, --help        Show this help
@@ -113,7 +128,7 @@ Options:
 | Command | Exit code |
 |---|---|
 | Success | `0` |
-| Invalid policy, or `check` found missing or outdated files | `1` |
+| Invalid policy, `check` found missing or outdated files, or `--describe` failed | `1` |
 | Wrong usage (unknown command or option, bad `--date`) | `2` |
 
 Examples:
@@ -128,6 +143,73 @@ npx depbot-policy reviewer --date 2026-12-28         # ...and in the last week o
 You can also install it as a dev dependency (`npm install --save-dev depbot-policy`) and call
 `depbot-policy` from npm scripts.
 
+## Writing a policy with AI
+
+Describe your setup in plain words and let an AI model (Claude or Gemini) write the policy:
+
+```sh
+export ANTHROPIC_API_KEY=sk-ant-...     # or: export GEMINI_API_KEY=AIza... with a gemini model
+npx depbot-policy init --describe "pnpm monorepo with apps in /apps/web and /apps/api, \
+  plus Dockerfiles. Auto-merge patch updates to dev dependencies. Never update react \
+  until we migrate to 19. alice and bob-smith take turns reviewing."
+
+npx depbot-policy init --describe "..." --model gemini-3-flash-preview   # use Gemini instead
+```
+
+Example output (the model's notes vary):
+
+```text
+Asking Claude Opus 5.5 to write the policy...
+Note: Assumed a weekly schedule, since none was given.
+Created depbot.policy.yml. Review it, then run: depbot-policy generate
+```
+
+The [playground](#web-playground) has the same feature under **Describe with AI**.
+
+**How it works.** The model only writes the *policy*. It never writes the workflow or
+`dependabot.yml`.
+
+1. The model fills in a simplified version of the policy schema and adds short notes about any
+   assumptions it made. Claude uses
+   [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs);
+   Gemini uses JSON output with a response schema. Both are held to the same schema.
+2. depbot-policy turns that into YAML and validates it with the same rules as a hand-written
+   policy.
+3. If anything fails validation, the errors go back to the model once to fix. Anything still wrong
+   is reported with its line and column, like any other policy error.
+4. You review the policy. `generate` then produces the files with the same deterministic code as
+   always.
+
+So the safety properties of the generated workflow (pinned actions, minimal permissions, the
+Dependabot-only checks, no major auto-merges) don't depend on the model.
+
+**Details:**
+
+- **Models:** pick one with `--model <id>` (or the Model menu in the playground). Claude models run
+  at low effort. Costs are rough list-price estimates per policy:
+
+  | Model | `--model` | About |
+  |---|---|---|
+  | Claude Opus 5.5 (default) | `claude-opus-5-5` | 3–5¢, best balance of quality and cost |
+  | Claude Sonnet 5.5 | `claude-sonnet-5-5` | 2¢, faster and cheaper |
+  | Claude Haiku 5.5 | `claude-haiku-5-5` | well under 1¢, fastest and cheapest |
+  | Claude Fable 5.1 | `claude-fable-5-1` | 8–13¢, most capable |
+  | Gemini 3 Flash | `gemini-3-flash-preview` | under 1¢, and Google lists it as free-tier eligible |
+  | Gemini 3.1 Pro | `gemini-3.1-pro-preview` | 2–3¢, more capable |
+
+  Try a cheaper model first. This is a short, well-specified task, and every result is validated
+  and shown to you before it's used. The Gemini models are previews, so Google may change or
+  retire them.
+- **Credentials:** for Claude, the CLI reads `ANTHROPIC_API_KEY`, or a login from Anthropic's
+  `ant` CLI. For Gemini, it reads `GEMINI_API_KEY` (or `GOOGLE_API_KEY`). In the playground, paste
+  a key for the provider of the model you picked.
+- **Privacy:** only your description is sent, to the provider whose model you choose (Anthropic or
+  Google). The playground sends it straight from your browser, keeps your key in memory only, and
+  forgets it when you leave the page.
+- **Exit codes:** if the model declines, or the result still has errors after the repair attempt,
+  `init --describe` exits with `1`. If there are remaining errors, it still writes the file so you
+  can fix them by hand.
+
 ## Policy reference
 
 A complete policy, with every option:
@@ -387,6 +469,10 @@ Rules worth knowing:
 **[heyhadi.github.io/depbot-policy](https://heyhadi.github.io/depbot-policy/)** lets you write a
 policy and see the generated files as you type.
 
+- **Describe with AI.** Describe your setup in plain words, paste your own Anthropic API key, and
+  the model writes the policy into the editor, with notes on any assumptions it made. You can choose
+  between four Claude models and two Gemini models. See
+  [Writing a policy with AI](#writing-a-policy-with-ai).
 - **Live validation.** Errors are underlined in the editor and listed below it in line order.
   Click one to jump to the exact text.
 - **Generated files in tabs**, with Copy and Download buttons. While the policy has errors, the
@@ -440,6 +526,30 @@ if (!result.ok) {
 Everything is pure: no file system, network or global state. That's what lets the same code run in
 the CLI, in tests and in the browser.
 
+To write a policy from a description, import from `depbot-policy/describe`. It's a separate entry
+point, so the core library never loads the Anthropic or Google SDKs:
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { describePolicy } from "depbot-policy/describe";
+
+const { source, errors, notes } = await describePolicy(
+  "npm project at the root; auto-merge patch updates",
+  new Anthropic(), // reads ANTHROPIC_API_KEY
+  { model: "claude-sonnet-5-5" }, // optional; defaults to claude-opus-5-5
+);
+// source: policy YAML, errors: [] when valid, notes: the model's assumptions
+```
+
+For a Gemini model, pass a Google client instead. The client has to match the model's provider, or
+`describePolicy` throws:
+
+```ts
+import { GoogleGenAI } from "@google/genai";
+
+await describePolicy("npm project", new GoogleGenAI({ apiKey }), { model: "gemini-3-flash-preview" });
+```
+
 ## Development
 
 Requires Node 22 or newer (see [`.nvmrc`](.nvmrc)). Node runs the TypeScript source directly
@@ -483,6 +593,8 @@ src/
   dependabot.ts      dependabot.yml generator
   workflow.ts        Auto-merge workflow generator
   rotation.ts        Weekly reviewer: TypeScript formula and the workflow's shell version
+  describe.ts        Write a policy from a description with Claude or Gemini (depbot-policy/describe)
+  describe-models.ts The models it can use, kept free of the SDK so help text and UI can list them
   files.ts           generateFiles: every generated file and its path
   cli.ts, bin.ts     The depbot-policy command (bin.ts is the executable entry point)
   starter.ts         The policy written by `init`
@@ -508,6 +620,10 @@ depbot.policy.yml    This repository's own policy; .github/dependabot.yml and th
 - **Rotation:** the workflow's shell script runs in bash, with stand-in `date` and `gh` commands,
   and must pick the same person as `reviewerFor` on every test date.
 - **CLI:** every command runs against a real temporary directory.
+- **AI:** tests use real client objects with the request method stubbed, so they never call an API.
+  They cover the request (model,
+  structured output format, refusal fallback for each model), the repair loop, replies the model can't use, and
+  error messages.
 - **Playground:** unit tests for its logic, plus tests of the whole page with React Testing Library.
   CodeMirror can't run in jsdom, so the tests replace the two small editor components with plain
   elements.
@@ -570,6 +686,9 @@ Short versions of the main decisions. The pull requests have the full reasoning.
   browser.
 - **Generated YAML via the `yaml` document API**, not string templates. The library handles quoting
   (`"@types/*"` must be quoted) and comments.
+- **AI writes the policy, never the workflow.** The model handles what needs judgment (understanding a
+  description). Validation and generation stay deterministic, so a bad model reply can't weaken
+  the security properties.
 - **Stateless rotation.** The reviewer is a function of the week, so there's nothing to store, sync
   or get out of date.
 - **Pinned actions.** Actions are referenced by commit SHA with a `# vX.Y.Z` comment, both in the

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { run } from "./cli.js";
-process.exitCode = run(process.argv.slice(2), {
+process.exitCode = await run(process.argv.slice(2), {
     cwd: process.cwd(),
     stdout: (text) => process.stdout.write(text),
     stderr: (text) => process.stderr.write(text),

package/dist/cli.d.ts

@@ -1,8 +1,12 @@
+import { type DescribeModelId } from "./describe-models.ts";
+import type { DescribeResult } from "./describe.ts";
 import { type PolicyError } from "./parse.ts";
 export interface CliIo {
     cwd: string;
     stdout: (text: string) => void;
     stderr: (text: string) => void;
+    /** Writes a policy from a description. Defaults to calling the chosen provider; tests pass a stand-in. */
+    describe?: (description: string, model: DescribeModelId) => Promise<DescribeResult>;
 }
 /** Exit codes: 0 success, 1 invalid policy or outdated files, 2 wrong usage. */
 export declare const exitCodes: {
@@ -11,6 +15,6 @@ export declare const exitCodes: {
     readonly usage: 2;
 };
 /** Runs the CLI and returns its exit code. Side effects go through `io` and the file system. */
-export declare function run(argv: readonly string[], io: CliIo): number;
+export declare function run(argv: readonly string[], io: CliIo): Promise<number>;
 /** `file:line:column: path: message`, the format editors and CI annotations understand. */
 export declare function formatError(file: string, error: PolicyError): string;

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
+import { defaultDescribeModel, describeModel, describeModels, isDescribeModelId, providerLabel, } from "./describe-models.js";
 import { generateFiles } from "./files.js";
 import { parsePolicy } from "./parse.js";
 import { reviewerFor } from "./rotation.js";
@@ -8,10 +9,23 @@ import { starterPolicy } from "./starter.js";
 /** Exit codes: 0 success, 1 invalid policy or outdated files, 2 wrong usage. */
 export const exitCodes = { ok: 0, failed: 1, usage: 2 };
 const defaultPolicyPath = "depbot.policy.yml";
+// The model list, grouped by provider, for the --model help. Each provider gets its own heading
+// so the two sets of models don't blur together.
+const modelHelp = ["anthropic", "google"]
+    .map((provider) => {
+    const heading = provider === "anthropic" ? "Claude models:" : "Gemini models:";
+    return [
+        `                      ${heading}`,
+        ...describeModels
+            .filter((model) => model.provider === provider)
+            .map((model) => `                      ${model.id.padEnd(23)} ${model.summary}`),
+    ].join("\n");
+})
+    .join("\n");
 const usage = `Usage: depbot-policy <command> [options]
 
 Commands:
-  init        Create a starter ${defaultPolicyPath}
+  init        Create a starter ${defaultPolicyPath}, or one written by AI with --describe
   generate    Write .github/dependabot.yml and the auto-merge workflow
   check       Fail if the policy is invalid or the generated files are out of date
   reviewer    Print this week's reviewer from review.rotation
@@ -20,13 +34,17 @@ Options:
   --policy <file>   Policy file (default: ${defaultPolicyPath})
   --out <dir>       Repository root to write to or check (default: .)
   --dry-run         generate: print the files instead of writing them
+  --describe <text> init: have an AI model write the policy from a description
+                    (needs ANTHROPIC_API_KEY or GEMINI_API_KEY)
+  --model <id>      init --describe: which model to use (default: ${defaultDescribeModel})
+${modelHelp}
   --force           init: overwrite an existing policy file
   --date <date>     reviewer: use this date instead of today (e.g. 2026-10-12)
   -h, --help        Show this help
   -v, --version     Show the version
 `;
 /** Runs the CLI and returns its exit code. Side effects go through `io` and the file system. */
-export function run(argv, io) {
+export async function run(argv, io) {
     let parsed;
     try {
         parsed = parseArgs({
@@ -37,6 +55,8 @@ export function run(argv, io) {
                 out: { type: "string", default: "." },
                 "dry-run": { type: "boolean", default: false },
                 force: { type: "boolean", default: false },
+                describe: { type: "string" },
+                model: { type: "string" },
                 date: { type: "string" },
                 help: { type: "boolean", short: "h", default: false },
                 version: { type: "boolean", short: "v", default: false },
@@ -61,6 +81,10 @@ export function run(argv, io) {
         io.stderr(`Unexpected argument: ${extra[0]}\n\n${usage}`);
         return exitCodes.usage;
     }
+    if (values.model !== undefined && values.describe === undefined) {
+        io.stderr("--model only applies to init --describe.\n");
+        return exitCodes.usage;
+    }
     const policyPath = values.policy;
     const resolve = (file) => path.resolve(io.cwd, file);
     switch (command) {
@@ -69,9 +93,12 @@ export function run(argv, io) {
                 io.stderr(`${policyPath} already exists. Use --force to overwrite it.\n`);
                 return exitCodes.failed;
             }
-            writeFileSync(resolve(policyPath), starterPolicy);
-            io.stdout(`Created ${policyPath}. Edit it, then run: depbot-policy generate\n`);
-            return exitCodes.ok;
+            if (values.describe === undefined) {
+                writeFileSync(resolve(policyPath), starterPolicy);
+                io.stdout(`Created ${policyPath}. Edit it, then run: depbot-policy generate\n`);
+                return exitCodes.ok;
+            }
+            return describeInto(policyPath, values.describe, values.model, resolve, io);
         }
         case "generate": {
             const policy = loadPolicy(policyPath, resolve, io);
@@ -129,6 +156,51 @@ export function run(argv, io) {
             return exitCodes.usage;
     }
 }
+async function describeInto(policyPath, description, modelOption, resolve, io) {
+    if (description.trim() === "") {
+        io.stderr("--describe needs a description, e.g. --describe \"pnpm monorepo, auto-merge patches\"\n");
+        return exitCodes.usage;
+    }
+    // Loaded on demand, so the other commands never load the provider SDKs.
+    const describeModule = await import("./describe.js");
+    const model = modelOption ?? defaultDescribeModel;
+    if (!isDescribeModelId(model)) {
+        const ids = describeModels.map((candidate) => candidate.id).join(", ");
+        io.stderr(`Unknown model: ${model}. Use one of: ${ids}\n`);
+        return exitCodes.usage;
+    }
+    const describe = io.describe ??
+        ((text, chosen) => describeModule.describePolicy(text, describeModule.environmentClient(describeModel(chosen).provider), {
+            model: chosen,
+        }));
+    const { label } = describeModels.find((candidate) => candidate.id === model);
+    io.stdout(`Asking ${label} to write the policy...\n`);
+    let result;
+    try {
+        result = await describe(description, model);
+    }
+    catch (error) {
+        io.stderr(`${describeModule.describeFailureMessage(error)}\n`);
+        // A missing Gemini key already says so. For Claude, the SDK's own error doesn't.
+        if (describeModel(model).provider === "anthropic" &&
+            !process.env.ANTHROPIC_API_KEY &&
+            !process.env.ANTHROPIC_AUTH_TOKEN) {
+            io.stderr("Set ANTHROPIC_API_KEY (or log in with `ant auth login`) to use --describe.\n");
+        }
+        return exitCodes.failed;
+    }
+    writeFileSync(resolve(policyPath), result.source);
+    for (const note of result.notes)
+        io.stdout(`Note: ${note}\n`);
+    if (result.errors.length > 0) {
+        io.stderr(`Created ${policyPath}, but it still has problems to fix by hand:\n`);
+        for (const error of result.errors)
+            io.stderr(`${formatError(policyPath, error)}\n`);
+        return exitCodes.failed;
+    }
+    io.stdout(`Created ${policyPath}. Review it, then run: depbot-policy generate\n`);
+    return exitCodes.ok;
+}
 function loadPolicy(policyPath, resolve, io) {
     let source;
     try {

package/dist/describe-models.d.ts

@@ -0,0 +1,61 @@
+/** Which API a model runs on. Drives the SDK client, the key it reads, and the failure copy. */
+export type DescribeProvider = "anthropic" | "google";
+export interface DescribeModel {
+    id: string;
+    label: string;
+    /** One line for pickers: what it's good for and roughly what one policy costs. */
+    summary: string;
+    /** Which provider runs the model. */
+    provider: DescribeProvider;
+    /**
+     * Whether the API may retry a refusal on another model (`fallbacks: "default"`).
+     * Claude Haiku 5.5 has no server-side fallback, so it must not send the parameter.
+     */
+    serverSideFallback: boolean;
+}
+export declare const describeModels: readonly [{
+    readonly id: "claude-opus-5-5";
+    readonly label: "Claude Opus 5.5";
+    readonly summary: "Recommended: best balance of quality and cost, about 3–5¢ per policy";
+    readonly provider: "anthropic";
+    readonly serverSideFallback: true;
+}, {
+    readonly id: "claude-sonnet-5-5";
+    readonly label: "Claude Sonnet 5.5";
+    readonly summary: "Faster and cheaper, about 2¢ per policy";
+    readonly provider: "anthropic";
+    readonly serverSideFallback: true;
+}, {
+    readonly id: "claude-haiku-5-5";
+    readonly label: "Claude Haiku 5.5";
+    readonly summary: "Fastest and cheapest, well under 1¢ per policy";
+    readonly provider: "anthropic";
+    readonly serverSideFallback: false;
+}, {
+    readonly id: "claude-fable-5-1";
+    readonly label: "Claude Fable 5.1";
+    readonly summary: "Most capable and most expensive, about 8–13¢ per policy";
+    readonly provider: "anthropic";
+    readonly serverSideFallback: true;
+}, {
+    readonly id: "gemini-3-flash-preview";
+    readonly label: "Gemini 3 Flash";
+    readonly summary: "Fast and cheap, under 1¢ per policy (free tier available)";
+    readonly provider: "google";
+    readonly serverSideFallback: false;
+}, {
+    readonly id: "gemini-3.1-pro-preview";
+    readonly label: "Gemini 3.1 Pro";
+    readonly summary: "More capable, about 2–3¢ per policy";
+    readonly provider: "google";
+    readonly serverSideFallback: false;
+}];
+export type DescribeModelId = (typeof describeModels)[number]["id"];
+export declare const defaultDescribeModel: DescribeModelId;
+/** The model with the given id, or undefined if it isn't supported. */
+export declare function describeModel(model: DescribeModelId): DescribeModel;
+/** A short, friendly name for a provider, used in CLI and playground copy. */
+export declare function providerLabel(provider: DescribeProvider): string;
+/** The provider a given model runs on. */
+export declare function providerFor(model: DescribeModelId): DescribeProvider;
+export declare function isDescribeModelId(value: string): value is DescribeModelId;

package/dist/describe-models.js

@@ -0,0 +1,66 @@
+// The models `describePolicy` can use. Kept apart from describe.ts, which loads the provider SDKs,
+// so the CLI's help text and the playground's picker can list them without loading any SDK.
+// Each model names its provider; everything else (clients, schemas) follows from that.
+// Costs assume ~2.5k input and 1–2k output tokens per policy, at each model's list price.
+// Gemini ids are exactly as listed on ai.google.dev/gemini-api/docs/models. Both are preview
+// models, so Google may change or retire them.
+export const describeModels = [
+    {
+        id: "claude-opus-5-5",
+        label: "Claude Opus 5.5",
+        summary: "Recommended: best balance of quality and cost, about 3–5¢ per policy",
+        provider: "anthropic",
+        serverSideFallback: true,
+    },
+    {
+        id: "claude-sonnet-5-5",
+        label: "Claude Sonnet 5.5",
+        summary: "Faster and cheaper, about 2¢ per policy",
+        provider: "anthropic",
+        serverSideFallback: true,
+    },
+    {
+        id: "claude-haiku-5-5",
+        label: "Claude Haiku 5.5",
+        summary: "Fastest and cheapest, well under 1¢ per policy",
+        provider: "anthropic",
+        serverSideFallback: false,
+    },
+    {
+        id: "claude-fable-5-1",
+        label: "Claude Fable 5.1",
+        summary: "Most capable and most expensive, about 8–13¢ per policy",
+        provider: "anthropic",
+        serverSideFallback: true,
+    },
+    {
+        id: "gemini-3-flash-preview",
+        label: "Gemini 3 Flash",
+        summary: "Fast and cheap, under 1¢ per policy (free tier available)",
+        provider: "google",
+        serverSideFallback: false,
+    },
+    {
+        id: "gemini-3.1-pro-preview",
+        label: "Gemini 3.1 Pro",
+        summary: "More capable, about 2–3¢ per policy",
+        provider: "google",
+        serverSideFallback: false,
+    },
+];
+export const defaultDescribeModel = "claude-opus-5-5";
+/** The model with the given id, or undefined if it isn't supported. */
+export function describeModel(model) {
+    return describeModels.find((candidate) => candidate.id === model);
+}
+/** A short, friendly name for a provider, used in CLI and playground copy. */
+export function providerLabel(provider) {
+    return provider === "anthropic" ? "Claude" : "Gemini";
+}
+/** The provider a given model runs on. */
+export function providerFor(model) {
+    return describeModel(model).provider;
+}
+export function isDescribeModelId(value) {
+    return describeModels.some((model) => model.id === value);
+}

package/dist/describe.d.ts

@@ -0,0 +1,116 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { GoogleGenAI } from "@google/genai";
+import { z } from "zod";
+import { type DescribeModelId, type DescribeProvider } from "./describe-models.ts";
+import { type PolicyError } from "./parse.ts";
+export { defaultDescribeModel, describeModel, describeModels, isDescribeModelId, providerFor, providerLabel, type DescribeModel, type DescribeModelId, type DescribeProvider, } from "./describe-models.ts";
+/**
+ * What Claude fills in. It's a simplified, refinement-free version of the policy schema, because
+ * structured outputs can't express cross-field rules or defaults. Our own code turns the draft into
+ * YAML, and `parsePolicy` still applies every rule, so the model can never bypass validation.
+ * A reply outside this schema (say, `major` as an update type) is rejected when the SDK parses it.
+ */
+export declare const policyDraftSchema: z.ZodObject<{
+    ecosystems: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            bundler: "bundler";
+            cargo: "cargo";
+            composer: "composer";
+            docker: "docker";
+            "github-actions": "github-actions";
+            gomod: "gomod";
+            gradle: "gradle";
+            maven: "maven";
+            mix: "mix";
+            npm: "npm";
+            nuget: "nuget";
+            pip: "pip";
+            pub: "pub";
+            swift: "swift";
+            terraform: "terraform";
+        }>;
+        directory: z.ZodString;
+        schedule: z.ZodEnum<{
+            daily: "daily";
+            monthly: "monthly";
+            weekly: "weekly";
+        }>;
+    }, z.core.$strip>>;
+    autoMerge: z.ZodObject<{
+        updateTypes: z.ZodArray<z.ZodEnum<{
+            minor: "minor";
+            patch: "patch";
+        }>>;
+        dependencyTypes: z.ZodArray<z.ZodEnum<{
+            development: "development";
+            production: "production";
+        }>>;
+        mergeMethod: z.ZodEnum<{
+            merge: "merge";
+            rebase: "rebase";
+            squash: "squash";
+        }>;
+    }, z.core.$strip>;
+    block: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        reason: z.ZodString;
+        ecosystems: z.ZodArray<z.ZodEnum<{
+            bundler: "bundler";
+            cargo: "cargo";
+            composer: "composer";
+            docker: "docker";
+            "github-actions": "github-actions";
+            gomod: "gomod";
+            gradle: "gradle";
+            maven: "maven";
+            mix: "mix";
+            npm: "npm";
+            nuget: "nuget";
+            pip: "pip";
+            pub: "pub";
+            swift: "swift";
+            terraform: "terraform";
+        }>>;
+    }, z.core.$strip>>;
+    reviewRotation: z.ZodArray<z.ZodString>;
+    notes: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type PolicyDraft = z.infer<typeof policyDraftSchema>;
+export interface DescribeResult {
+    /** The policy as YAML, ready to save as depbot.policy.yml. */
+    source: string;
+    /** Validation errors still present after one repair attempt; empty when the policy is valid. */
+    errors: PolicyError[];
+    /** Claude's notes on assumptions it made. */
+    notes: string[];
+}
+export declare class DescribeError extends Error {
+    name: string;
+}
+export interface DescribeOptions {
+    /** Which model writes the policy. Defaults to `defaultDescribeModel`. */
+    model?: DescribeModelId;
+}
+/**
+ * A provider-agnostic way to ask a model for a policy draft. Each provider (Claude, Gemini) has an
+ * adapter that knows how to call its SDK with structured output and how to turn its replies into
+ * a `PolicyDraft`. `describePolicy` stays the same regardless of which one it's given.
+ */
+export interface DescribeBackend {
+    draft(content: string): Promise<PolicyDraft>;
+}
+/** Either SDK's client. The adapters narrow this with `instanceof`. */
+export type DescribeBackendClient = Anthropic | GoogleGenAI;
+/**
+ * Asks a model to write a policy from a plain-language description, validates it with
+ * `parsePolicy`, and gives the model one chance to fix any errors.
+ */
+export declare function describePolicy(description: string, client: DescribeBackendClient, { model }?: DescribeOptions): Promise<DescribeResult>;
+/** Turns a draft into policy YAML, leaving out empty optional sections. */
+export declare function draftToYaml(draft: PolicyDraft, provider?: DescribeProvider): string;
+/** A short, user-facing explanation for an error thrown while describing a policy. */
+export declare function describeFailureMessage(error: unknown): string;
+/** A client for use in a browser, with a key the user typed in. */
+export declare function browserClient(provider: DescribeProvider, apiKey: string): DescribeBackendClient;
+/** A backend that reads credentials from the environment for the given provider. */
+export declare function environmentClient(provider: DescribeProvider): DescribeBackendClient;

package/dist/describe.js

@@ -0,0 +1,262 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { betaZodOutputFormat } from "@anthropic-ai/sdk/helpers/beta/zod";
+import { ApiError, GoogleGenAI } from "@google/genai";
+import { Document, isScalar, visit } from "yaml";
+import { z } from "zod";
+import { defaultDescribeModel, describeModel, describeModels, providerLabel, } from "./describe-models.js";
+import { parsePolicy } from "./parse.js";
+import { ecosystemTypes } from "./schema.js";
+export { defaultDescribeModel, describeModel, describeModels, isDescribeModelId, providerFor, providerLabel, } from "./describe-models.js";
+/**
+ * What Claude fills in. It's a simplified, refinement-free version of the policy schema, because
+ * structured outputs can't express cross-field rules or defaults. Our own code turns the draft into
+ * YAML, and `parsePolicy` still applies every rule, so the model can never bypass validation.
+ * A reply outside this schema (say, `major` as an update type) is rejected when the SDK parses it.
+ */
+export const policyDraftSchema = z.object({
+    ecosystems: z
+        .array(z.object({
+        type: z.enum(ecosystemTypes),
+        directory: z.string().describe('Path from the repository root, starting with "/"'),
+        schedule: z.enum(["daily", "weekly", "monthly"]),
+    }))
+        .describe("One entry per package manager and directory"),
+    autoMerge: z.object({
+        updateTypes: z.array(z.enum(["patch", "minor"])),
+        dependencyTypes: z.array(z.enum(["development", "production"])),
+        mergeMethod: z.enum(["squash", "merge", "rebase"]),
+    }),
+    block: z
+        .array(z.object({
+        name: z.string().describe('Package name or glob, e.g. "@types/*"'),
+        reason: z.string().describe("Why it's blocked, in the user's words where possible"),
+        ecosystems: z
+            .array(z.enum(ecosystemTypes))
+            .describe("Ecosystems the block applies to; empty means all of them"),
+    }))
+        .describe("Packages Dependabot must never update; empty if none were mentioned"),
+    reviewRotation: z
+        .array(z.string())
+        .describe("GitHub usernames without @, in the order given; empty if none were named"),
+    notes: z
+        .array(z.string())
+        .describe("Short notes on assumptions made or requests that couldn't be honoured"),
+});
+const systemPrompt = `You turn a team's plain-language description of how they want Dependabot to behave into a depbot-policy draft.
+
+How to fill each field:
+- ecosystems: one entry per package manager and directory. Yarn, pnpm and Bun projects use "npm"; Poetry and Pipenv use "pip"; Go modules use "gomod"; Rust uses "cargo"; Ruby uses "bundler"; Dockerfiles use "docker"; GitHub Actions workflows use "github-actions" with directory "/". Directories start with "/", and "/" is the repository root. In a monorepo, list each package directory the user mentions. Use the schedule they ask for, otherwise "weekly" ("monthly" for github-actions).
+- autoMerge: unless the user says otherwise, use updateTypes ["patch"], both dependency types, and "squash". Include "minor" only if the user explicitly allows it. Major updates can never be auto-merged; if the user asks for that, leave majors out and say so in notes.
+- block: only packages the user says to pin, freeze or never update. Keep their reason. Limit the block to an ecosystem when the package clearly belongs to one.
+- reviewRotation: only GitHub usernames the user actually gives, without "@". Never invent people.
+- notes: brief, one sentence each, for any assumption you made or anything you couldn't do. Leave it empty when there's nothing worth saying.`;
+export class DescribeError extends Error {
+    name = "DescribeError";
+}
+/**
+ * Asks a model to write a policy from a plain-language description, validates it with
+ * `parsePolicy`, and gives the model one chance to fix any errors.
+ */
+export async function describePolicy(description, client, { model = defaultDescribeModel } = {}) {
+    const backend = backendFor(client, model);
+    const provider = providerOf(model);
+    const first = await backend.draft(description);
+    const firstSource = draftToYaml(first, provider);
+    const firstResult = parsePolicy(firstSource);
+    if (firstResult.ok)
+        return { source: firstSource, errors: [], notes: first.notes };
+    const repair = await backend.draft(`${description}
+
+A previous attempt produced this policy, which fails validation:
+
+${firstSource}
+Errors:
+${firstResult.errors.map((error) => `- ${error.path || "(file)"}: ${error.message}`).join("\n")}
+
+Return a corrected draft.`);
+    const source = draftToYaml(repair, provider);
+    const result = parsePolicy(source);
+    return { source, errors: result.ok ? [] : result.errors, notes: repair.notes };
+}
+/**
+ * Picks the adapter for the client the caller passed. Claude and Gemini use different SDKs and
+ * request shapes, so each gets its own adapter; everything above it is shared.
+ */
+function backendFor(client, model) {
+    const provider = providerOf(model);
+    if (provider === "google" && client instanceof GoogleGenAI)
+        return geminiBackend(client, model);
+    if (provider === "anthropic" && client instanceof Anthropic)
+        return anthropicBackend(client, model);
+    throw new DescribeError(`${describeModel(model).label} needs a ${providerLabel(provider)} client, but a different one was passed.`);
+}
+/** Claude adapter: structured outputs via the Anthropic SDK's `messages.parse`. */
+function anthropicBackend(client, model) {
+    return {
+        async draft(content) {
+            let response;
+            try {
+                response = await sendAnthropicRequest(client, model, content);
+            }
+            catch (error) {
+                // The SDK reports a reply that fails policyDraftSchema as a plain AnthropicError. API errors
+                // (a subclass) and anything else, such as missing credentials, go to the caller unchanged.
+                if (error instanceof Anthropic.AnthropicError && !(error instanceof Anthropic.APIError)) {
+                    throw new DescribeError("The model's reply didn't match the policy format. Try again.");
+                }
+                throw error;
+            }
+            if (response.stop_reason === "refusal") {
+                throw new DescribeError("The model declined to write a policy for this description.");
+            }
+            if (response.stop_reason === "max_tokens") {
+                throw new DescribeError("The answer was cut off. Try a shorter description.");
+            }
+            if (response.parsed_output == null) {
+                throw new DescribeError("The model didn't return a policy. Try rephrasing the description.");
+            }
+            return response.parsed_output;
+        },
+    };
+}
+function sendAnthropicRequest(client, model, content) {
+    const { serverSideFallback } = describeModel(model);
+    return client.beta.messages.parse({
+        model,
+        max_tokens: 16000,
+        // On a refusal, the API retries on a fallback model it picks for the refusal category.
+        ...(serverSideFallback && {
+            betas: ["server-side-fallback-2026-07-01"],
+            fallbacks: "default",
+        }),
+        system: systemPrompt,
+        messages: [{ role: "user", content }],
+        output_config: {
+            // A short, well-specified extraction; low effort keeps it fast.
+            effort: "low",
+            format: betaZodOutputFormat(policyDraftSchema),
+        },
+    });
+}
+/** Gemini adapter: JSON output via `generateContent` + `responseJsonSchema`. */
+function geminiBackend(client, model) {
+    return {
+        async draft(content) {
+            // API failures, including a 400 for a bad key, are explained by describeFailureMessage.
+            // Only a reply we can't parse (below) means the model didn't follow the format.
+            const response = await client.models.generateContent({
+                model,
+                contents: content,
+                config: {
+                    systemInstruction: systemPrompt,
+                    responseMimeType: "application/json",
+                    // The same draft schema the Claude path uses, so both providers are held to one
+                    // contract. Gemini returns plain JSON, which we validate with Zod below.
+                    responseJsonSchema: geminiResponseSchema,
+                },
+            });
+            const text = response.text;
+            if (!text) {
+                throw new DescribeError("The model didn't return a policy. Try rephrasing the description.");
+            }
+            try {
+                return policyDraftSchema.parse(JSON.parse(text));
+            }
+            catch {
+                throw new DescribeError("The model's reply didn't match the policy format. Try again.");
+            }
+        },
+    };
+}
+// Gemini's `responseJsonSchema` accepts only a subset of JSON Schema properties, and `$schema`
+// isn't one of them.
+const { $schema: _dialect, ...geminiResponseSchema } = z.toJSONSchema(policyDraftSchema);
+/** Turns a draft into policy YAML, leaving out empty optional sections. */
+export function draftToYaml(draft, provider = "anthropic") {
+    const doc = new Document({
+        version: 1,
+        ecosystems: draft.ecosystems,
+        autoMerge: draft.autoMerge,
+        ...(draft.block.length > 0 && {
+            block: draft.block.map(({ ecosystems, ...entry }) => ({
+                ...entry,
+                ...(ecosystems.length > 0 && { ecosystems }),
+            })),
+        }),
+        ...(draft.reviewRotation.length > 0 && { review: { rotation: draft.reviewRotation } }),
+    });
+    doc.commentBefore = ` Written by ${providerLabel(provider)} from a description. Review it before committing.`;
+    // Short lists of plain values read better inline: updateTypes: [patch, minor]
+    visit(doc, {
+        Seq(_, node) {
+            if (node.items.every(isScalar))
+                node.flow = true;
+        },
+    });
+    return doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+}
+/** The provider a given model runs on. */
+function providerOf(model) {
+    return describeModel(model).provider;
+}
+/** A short, user-facing explanation for an error thrown while describing a policy. */
+export function describeFailureMessage(error) {
+    if (error instanceof DescribeError)
+        return error.message;
+    if (error instanceof Anthropic.AuthenticationError)
+        return "The API key was rejected. Check it and try again.";
+    if (error instanceof Anthropic.PermissionDeniedError)
+        return "This API key isn't allowed to use the model.";
+    if (error instanceof Anthropic.RateLimitError)
+        return "Rate limited by the Anthropic API. Wait a moment and try again.";
+    if (error instanceof Anthropic.APIConnectionError)
+        return "Couldn't reach the Anthropic API. Check your connection.";
+    if (error instanceof Anthropic.APIError)
+        return `The Anthropic API returned an error (${error.status ?? "unknown"}).`;
+    if (error instanceof ApiError) {
+        // Google reports a bad key as HTTP 400 with the reason API_KEY_INVALID, not as 401.
+        if (googleErrorReason(error) === "API_KEY_INVALID" || error.status === 401 || error.status === 403) {
+            return "The API key was rejected. Check it and try again.";
+        }
+        if (error.status === 404)
+            return "The Gemini API doesn't know that model, or this key can't use it.";
+        if (error.status === 429)
+            return "Rate limited by the Gemini API. Wait a moment and try again.";
+        if (error.status === 400)
+            return "The Gemini API rejected the request (400).";
+        return `The Gemini API returned an error (${error.status}).`;
+    }
+    return "Something went wrong while generating the policy.";
+}
+/** The `reason` in a Gemini API error's details, such as `API_KEY_INVALID`, if there is one. */
+function googleErrorReason(error) {
+    try {
+        const body = JSON.parse(error.message);
+        return body.error?.details?.find((detail) => detail.reason !== undefined)?.reason;
+    }
+    catch {
+        // The message isn't JSON (for example a network failure), so there's no reason to read.
+        return undefined;
+    }
+}
+/** A client for use in a browser, with a key the user typed in. */
+export function browserClient(provider, apiKey) {
+    if (provider === "google")
+        return new GoogleGenAI({ apiKey });
+    return new Anthropic({ apiKey, dangerouslyAllowBrowser: true });
+}
+/** A backend that reads credentials from the environment for the given provider. */
+export function environmentClient(provider) {
+    return providerClient(provider);
+}
+/** The provider's SDK client, reading its key from the environment. */
+function providerClient(provider) {
+    if (provider === "anthropic")
+        return new Anthropic();
+    // Passing the key explicitly keeps the Gemini SDK from printing its own messages, or from
+    // probing for Google Cloud credentials, when none is set.
+    const apiKey = process.env.GEMINI_API_KEY ?? process.env.GOOGLE_API_KEY;
+    if (!apiKey)
+        throw new DescribeError("No Gemini API key found. Set GEMINI_API_KEY.");
+    return new GoogleGenAI({ apiKey });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depbot-policy",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One policy file → dependabot.yml, a safe auto-merge workflow, a block list, and a weekly review rotation",
   "keywords": [
     "dependabot",
@@ -22,6 +22,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./describe": {
+      "types": "./dist/describe.d.ts",
+      "default": "./dist/describe.js"
     }
   },
   "bin": {
@@ -41,6 +45,8 @@
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.131.0",
+    "@google/genai": "^2.28.0",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"
   },