@verndale/ai-commit 2.2.0 → 2.4.0

package/.env-example

@@ -0,0 +1,29 @@
+# Copy to .env and/or .env.local in your project root (do not commit secrets).
+
+# ------------------------------------------------------------
+# @verndale/ai-commit (pnpm commit / ai-commit run)
+# ------------------------------------------------------------
+# @verndale/ai-commit — OPENAI_API_KEY: OpenAI API key for conventional commit messages (ai-commit run; optional for prepare-commit-msg with AI).
+OPENAI_API_KEY=
+
+# Optional — default is gpt-4o-mini
+# COMMIT_AI_MODEL=
+
+# @verndale/ai-pr — GH_TOKEN: Set for local CLI runs; CI uses workflow env / secrets. Also reads GITHUB_TOKEN.
+GH_TOKEN=
+
+# Optional — PR behavior
+# @verndale/ai-pr — PR_BASE_BRANCH: Base branch to merge into (default main).
+# PR_BASE_BRANCH=main
+# @verndale/ai-pr — PR_DRAFT: If true (default), new PRs are drafts.
+# PR_DRAFT=true
+
+# Optional — AI summary + labels (when PR_AI=true)
+# @verndale/ai-pr — PR_AI: Set true to enable AI summary and optional labels/checklist.
+# PR_AI=true
+# @verndale/ai-pr — PR_AI_ENDPOINT: AI API URL when PR_AI is true (e.g. OpenAI Responses endpoint).
+# PR_AI_ENDPOINT=https://api.openai.com/v1/responses
+# @verndale/ai-pr — PR_AI_API_KEY: Bearer token for the AI API when PR_AI is true.
+# PR_AI_API_KEY=
+# @verndale/ai-pr — PR_AI_MODEL: Model id (default string default).
+# PR_AI_MODEL=default

package/README.md

@@ -18,20 +18,20 @@ The same package works with **npm** or **yarn** (for example `npm install -D @ve
 ## Quick setup (deterministic order)
 
 1. **Install** the dev dependency (see [Install](#install)).
-2. **Init** — From the **git repo root** (where **`package.json`** lives), run **`pnpm exec ai-commit init`**. That merges **`.env`** and **`.env.example`** (creates **`.env.example`** from the bundled template if it is missing; see [`.env.example`](.env.example) for keys and comments), runs **`npx husky@9 init`** if Husky is not present, adds missing **`commit`** / **`prepare`** / **`husky`** entries to **`package.json`** when the file exists, and writes **`.husky`** hooks. **Install dependencies** afterward if **`package.json`** changed (`pnpm install`, `npm install`, etc.).  
+2. **Init** — From the **git repo root** (where **`package.json`** lives), run **`pnpm exec ai-commit init`**. That merges **`.env`** and **`.env-example`** (creates **`.env-example`** from the bundled template if it is missing; see [`.env-example`](.env-example) for keys and comments), runs **`npx husky@9 init`** if Husky is not present, adds missing **`commit`** / **`prepare`** / **`husky`** entries to **`package.json`** when the file exists, and writes **`.husky`** hooks. **Install dependencies** afterward if **`package.json`** changed (`pnpm install`, `npm install`, etc.).  
    - Not in a git repo? **init** only updates env files and explains that Git/Husky were skipped.  
    - Env files only? Use **`pnpm exec ai-commit init --env-only`**.  
    - Hooks only (no **`package.json`** changes)? Use **`pnpm exec ai-commit init --husky`**.
 3. **Secrets** — Set **`OPENAI_API_KEY`** in `.env` and/or `.env.local` (`.env.local` overrides `.env` for duplicate keys).
 
-Use **`ai-commit init --force`** to replace **`.env`** and **`.env.example`** with the bundled template (destructive) or to overwrite existing Husky hook files. Without **`--force`**, **init** creates **`.env.example`** when missing and otherwise appends missing ai-commit keys (same as **`.env`**).
+Use **`ai-commit init --force`** to replace **`.env`** and **`.env-example`** with the bundled template (destructive) or to overwrite existing Husky hook files. Without **`--force`**, **init** creates **`.env-example`** when missing and otherwise appends missing ai-commit keys (same as **`.env`**). The published template file is **`.env-example`** (hyphen, not **`.env.example`**).
 
 ## Environment
 
 - **`OPENAI_API_KEY`** — Required for `ai-commit run` (and for AI-filled `prepare-commit-msg` when you want the model). Optional `COMMIT_AI_MODEL` (default `gpt-4o-mini`).
 - **Shared env vars** — If another tool already documents **`OPENAI_API_KEY`** or **`COMMIT_AI_MODEL`**, **`ai-commit init`** adds its own `# @verndale/ai-commit — …` line immediately above the assignment when missing; it does not remove or replace existing comment lines.
 - The CLI loads **`.env`** then **`.env.local`** from the current working directory (project root); values in `.env.local` override `.env` for the same key.
-- **Optional tooling:** `PR_*` env vars for [`@verndale/ai-pr`](https://www.npmjs.com/package/@verndale/ai-pr) (`pnpm open-pr` in this repo) / the **Create or update PR** workflow; `RELEASE_NOTES_AI_*` for [`tools/semantic-release-notes.cjs`](./tools/semantic-release-notes.cjs). Use a GitHub PAT as **`GH_TOKEN`** (or `GITHUB_TOKEN`) when calling the GitHub API outside Actions.
+- **Optional tooling:** `PR_*` env vars for [`@verndale/ai-pr`](https://www.npmjs.com/package/@verndale/ai-pr) (`pnpm run pr:create` in this repo) / the **Create or update PR** workflow; `RELEASE_NOTES_AI_*` for [`tools/semantic-release-notes.cjs`](./tools/semantic-release-notes.cjs). Use a GitHub PAT as **`GH_TOKEN`** (or `GITHUB_TOKEN`) when calling the GitHub API outside Actions.
 
 ## Commit policy (v2)
 
@@ -50,7 +50,7 @@ Use **`ai-commit init --force`** to replace **`.env`** and **`.env.example`** wi
 | Command | Purpose |
 | --- | --- |
 | `ai-commit run` | Generate a message from the staged diff and run `git commit`. |
-| `ai-commit init [--force] [--env-only] [--husky] [--workspace]` | Merge env keys, then **`npx husky@9 init`** if needed, merge **`package.json`** when present, write hooks. **`--env-only`** stops after env files. **`--husky`** skips `package.json` (hooks + Husky only); use **`--husky --workspace`** to include **`package.json`** again. **`--force`** replaces `.env` / overwrites hooks. |
+| `ai-commit init [--force] [--env-only] [--husky] [--workspace]` | Merge env keys (including **`.env-example`**), then **`npx husky@9 init`** if needed, merge **`package.json`** when present, write hooks. **`--env-only`** stops after env files. **`--husky`** skips `package.json` (hooks + Husky only); use **`--husky --workspace`** to include **`package.json`** again. **`--force`** replaces `.env` / `.env-example` / overwrites hooks. |
 | `ai-commit prepare-commit-msg <file> [source]` | Git `prepare-commit-msg` hook: fill an empty message; skips `merge` / `squash`. |
 | `ai-commit lint --edit <file>` | Git `commit-msg` hook: run commitlint with this package’s default config. |
 
@@ -118,17 +118,17 @@ corepack enable
 pnpm install
 ```
 
-Copy `.env.example` to `.env` and/or `.env.local` and set **`OPENAI_API_KEY`**. After staging, **`pnpm commit`** runs this repo’s CLI (`node ./bin/cli.js run`; the published package exposes `ai-commit` in `node_modules/.bin` for dependents). Hooks under `.husky/` call **`pnpm exec ai-commit`** from this checkout.
+Copy **`.env-example`** to `.env` and/or `.env.local` and set **`OPENAI_API_KEY`**. After staging, **`pnpm commit`** runs this repo’s CLI (`node ./bin/cli.js run`; the published package exposes `ai-commit` in `node_modules/.bin` for dependents). Hooks under `.husky/` call **`pnpm exec ai-commit`** from this checkout.
 
 ### Repository automation
 
 | Workflow | Trigger | Purpose |
 | --- | --- | --- |
 | [`.github/workflows/commitlint.yml`](./.github/workflows/commitlint.yml) | PRs to `main`, pushes to non-`main` branches | Commitlint on PR range or last push commit |
-| [`.github/workflows/pr.yml`](./.github/workflows/pr.yml) | Pushes (not `main`) and `workflow_dispatch` | Install deps, run **`pnpm open-pr`** ([**`@verndale/ai-pr`**](https://www.npmjs.com/package/@verndale/ai-pr)) — set **`PR_HEAD_BRANCH`** / **`PR_BASE_BRANCH`** in CI via env (workflow sets them). Use a PAT secret **`PR_BOT_TOKEN`** if branch protection requires it; otherwise document your org’s policy. |
+| [`.github/workflows/pr.yml`](./.github/workflows/pr.yml) | Pushes (not `main`) and `workflow_dispatch` | Install deps, run **`pnpm run pr:create`** ([**`@verndale/ai-pr`**](https://www.npmjs.com/package/@verndale/ai-pr)) — set **`PR_HEAD_BRANCH`** / **`PR_BASE_BRANCH`** in CI via env (workflow sets them). Use a PAT secret **`PR_BOT_TOKEN`** if branch protection requires it; otherwise document your org’s policy. |
 | [`.github/workflows/release.yml`](./.github/workflows/release.yml) | Push to **`main`** (including when a PR merges) | **`semantic-release`** — version bump, `CHANGELOG.md`, git tag, npm publish (with provenance), GitHub Release |
 
-Optional **`pnpm open-pr`** locally: set **`GH_TOKEN`** (or **`GITHUB_TOKEN`**) and branch overrides **`PR_BASE_BRANCH`** / **`PR_HEAD_BRANCH`** as needed.
+Optional **`pnpm run pr:create`** locally: set **`GH_TOKEN`** (or **`GITHUB_TOKEN`**) and branch overrides **`PR_BASE_BRANCH`** / **`PR_HEAD_BRANCH`** as needed.
 
 ## Publishing (maintainers)
 

package/bin/cli.js

@@ -42,7 +42,7 @@ Usage:
 
 Commands:
   run                  Generate a message from the staged diff and run git commit.
-  init                 Merge env, then Husky + package.json + hooks (from a git repo). \`--env-only\` stops after env files. \`--husky\` skips package.json. \`--force\` replaces \`.env\` / hooks.
+  init                 Merge env, then Husky + package.json + hooks (from a git repo). \`--env-only\` stops after env files. \`--husky\` skips package.json. \`--force\` replaces \`.env\` / \`.env-example\` / hooks.
   prepare-commit-msg   Git hook: fill an empty commit message file (merge/squash skipped).
   lint                 Run commitlint with the package default config (for commit-msg hook).
 
@@ -86,10 +86,10 @@ function cmdInit(argv) {
   const cwd = process.cwd();
   /** Full package.json merge: default on, or `--workspace`; off for `--husky` alone (legacy). */
   const mergePackageJson = !husky || workspace;
-  const examplePath = path.join(__dirname, "..", ".env.example");
+  const examplePath = path.join(__dirname, "..", ".env-example");
 
   if (!fs.existsSync(examplePath)) {
-    throw new Error("Missing bundled .env.example (corrupt install?).");
+    throw new Error("Missing bundled .env-example (corrupt install?).");
   }
 
   const envDest = path.join(cwd, ".env");
@@ -114,9 +114,9 @@ function cmdInit(argv) {
       break;
   }
 
-  const envExampleDest = path.join(cwd, ".env.example");
+  const envExampleDest = path.join(cwd, ".env-example");
   const exResult = mergeAiCommitEnvFile(envExampleDest, examplePath, { force });
-  const exRel = path.relative(cwd, envExampleDest) || ".env.example";
+  const exRel = path.relative(cwd, envExampleDest) || ".env-example";
   switch (exResult.kind) {
     case "replaced":
       process.stdout.write(`Replaced ${exRel} with bundled template (--force).\n`);

package/lib/init-env.js

@@ -5,13 +5,57 @@ const fs = require("fs");
 /** Detect our doc line so we do not duplicate or replace other packages’ comments. */
 const MARKER_PREFIX = "# @verndale/ai-commit — ";
 
+const SECTION_DIVIDER = "# ------------------------------------------------------------";
+const SECTION_TITLE = "# @verndale/ai-commit (pnpm commit / ai-commit run)";
+const SECTION_HEADER = [SECTION_DIVIDER, SECTION_TITLE, SECTION_DIVIDER];
+
+const SUBSECTION_OPTIONAL_MODEL = "# Optional — default is gpt-4o-mini";
+
 const DOC_OPENAI = [
   `${MARKER_PREFIX}OPENAI_API_KEY: OpenAI API key for conventional commit messages (ai-commit run; optional for prepare-commit-msg with AI).`,
 ];
 
-const DOC_COMMIT_MODEL = [
-  `${MARKER_PREFIX}COMMIT_AI_MODEL: OpenAI model for commit messages (optional; default gpt-4o-mini).`,
-];
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+function hasAiCommitSectionHeader(text) {
+  return (
+    text.includes(SECTION_DIVIDER) &&
+    text.includes("@verndale/ai-commit (pnpm commit / ai-commit run)")
+  );
+}
+
+/**
+ * True when COMMIT_AI_MODEL is already documented (long marker, subsection, or legacy block).
+ * @param {string[]} lines
+ * @returns {boolean}
+ */
+function hasCommitModelNotes(lines) {
+  if (hasOurDocForKey(lines, "COMMIT_AI_MODEL")) {
+    return true;
+  }
+  const commitIdx = lines.findIndex(
+    (line) =>
+      /^\s*COMMIT_AI_MODEL\s*=/.test(line) || /^\s*#\s*COMMIT_AI_MODEL\s*=/.test(line),
+  );
+  if (commitIdx === -1) {
+    return false;
+  }
+  for (let i = commitIdx - 1; i >= 0 && i >= commitIdx - 12; i--) {
+    const t = lines[i].trim();
+    if (t === "") {
+      continue;
+    }
+    if (t === SUBSECTION_OPTIONAL_MODEL.trim()) {
+      return true;
+    }
+    if (lines[i].includes(`${MARKER_PREFIX}COMMIT_AI_MODEL:`)) {
+      return true;
+    }
+  }
+  return false;
+}
 
 /**
  * Keys assigned on non-comment lines (`KEY=value` or `export KEY=value`).
@@ -38,27 +82,6 @@ function hasOurDocForKey(lines, key) {
   return lines.some((line) => line.includes(needle));
 }
 
-/**
- * Insert ai-commit doc lines immediately before an assignment line, without changing
- * existing comments above that line (we insert after those lines, before the key line).
- * @param {string[]} lines mutable
- * @param {RegExp} assignmentRegex
- * @param {string[]} docLines
- * @param {string} key for marker check
- * @returns {boolean} whether lines were mutated
- */
-function injectDocBeforeAssignment(lines, assignmentRegex, docLines, key) {
-  if (hasOurDocForKey(lines, key)) {
-    return false;
-  }
-  const idx = lines.findIndex((line) => assignmentRegex.test(line));
-  if (idx === -1) {
-    return false;
-  }
-  lines.splice(idx, 0, ...docLines);
-  return true;
-}
-
 /**
  * For keys already present (possibly with another package’s comments), add our doc line(s)
  * above the assignment if missing. Does not remove or edit existing comment lines.
@@ -69,24 +92,27 @@ function injectAiCommitDocsForExistingKeys(content) {
   const lines = content.split(/\r?\n/);
   let changed = false;
 
-  if (
-    injectDocBeforeAssignment(
-      lines,
-      /^\s*OPENAI_API_KEY\s*=/,
-      DOC_OPENAI,
-      "OPENAI_API_KEY",
-    )
-  ) {
-    changed = true;
+  if (!hasOurDocForKey(lines, "OPENAI_API_KEY")) {
+    const idx = lines.findIndex((line) => /^\s*OPENAI_API_KEY\s*=/.test(line));
+    if (idx !== -1) {
+      const insert = hasAiCommitSectionHeader(lines.join("\n"))
+        ? [DOC_OPENAI[0]]
+        : [...SECTION_HEADER, DOC_OPENAI[0]];
+      lines.splice(idx, 0, ...insert);
+      changed = true;
+    }
   }
 
-  if (!hasOurDocForKey(lines, "COMMIT_AI_MODEL")) {
+  if (!hasCommitModelNotes(lines)) {
     let idx = lines.findIndex((line) => /^\s*COMMIT_AI_MODEL\s*=/.test(line));
     if (idx === -1) {
       idx = lines.findIndex((line) => /^\s*#\s*COMMIT_AI_MODEL\s*=/.test(line));
     }
     if (idx !== -1) {
-      lines.splice(idx, 0, ...DOC_COMMIT_MODEL);
+      const insert = hasAiCommitSectionHeader(lines.join("\n"))
+        ? [SUBSECTION_OPTIONAL_MODEL]
+        : [...SECTION_HEADER, "", SUBSECTION_OPTIONAL_MODEL];
+      lines.splice(idx, 0, ...insert);
       changed = true;
     }
   }
@@ -106,17 +132,43 @@ function buildAiCommitEnvAppend(existing) {
     keys.has("COMMIT_AI_MODEL") ||
     /^\s*#\s*COMMIT_AI_MODEL\s*=/m.test(existing) ||
     /^\s*COMMIT_AI_MODEL\s*=/m.test(existing);
-  const parts = [];
-  if (!keys.has("OPENAI_API_KEY")) {
-    parts.push(`${DOC_OPENAI[0]}\nOPENAI_API_KEY=\n`);
+  const needOpenai = !keys.has("OPENAI_API_KEY");
+  const needCommit = !keys.has("COMMIT_AI_MODEL") && !hasCommitPlaceholder;
+  const hasSection = hasAiCommitSectionHeader(existing);
+
+  if (!needOpenai && !needCommit) {
+    return null;
   }
-  if (!keys.has("COMMIT_AI_MODEL") && !hasCommitPlaceholder) {
-    parts.push(`${DOC_COMMIT_MODEL[0]}\n# COMMIT_AI_MODEL=\n`);
+
+  if (needOpenai && needCommit) {
+    return [
+      ...SECTION_HEADER,
+      DOC_OPENAI[0],
+      "OPENAI_API_KEY=",
+      "",
+      SUBSECTION_OPTIONAL_MODEL,
+      "# COMMIT_AI_MODEL=",
+      "",
+      "",
+    ].join("\n");
   }
-  if (parts.length === 0) {
-    return null;
+
+  if (needOpenai) {
+    return [...SECTION_HEADER, DOC_OPENAI[0], "OPENAI_API_KEY=", ""].join("\n");
+  }
+
+  if (hasSection) {
+    return [SUBSECTION_OPTIONAL_MODEL, "# COMMIT_AI_MODEL=", "", ""].join("\n");
   }
-  return parts.join("\n");
+
+  return [
+    ...SECTION_HEADER,
+    "",
+    SUBSECTION_OPTIONAL_MODEL,
+    "# COMMIT_AI_MODEL=",
+    "",
+    "",
+  ].join("\n");
 }
 
 /**
@@ -124,7 +176,7 @@ function buildAiCommitEnvAppend(existing) {
  * @param {string} destPath
  * @param {string} bundledPath
  * @param {{ force?: boolean }} [options]
- * @returns {{ kind: 'replaced' | 'wrote' | 'merged' | 'unchanged' }}
+ * @returns {{ kind: 'replaced' | 'wrote' | 'unchanged' }}
  */
 function mergeAiCommitEnvFile(destPath, bundledPath, options = {}) {
   const { force = false } = options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verndale/ai-commit",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "AI-assisted conventional commits with bundled commitlint — one install, aligned rules",
   "license": "MIT",
   "author": "Verndale",
@@ -28,7 +28,7 @@
   "files": [
     "bin",
     "lib",
-    ".env.example",
+    ".env-example",
     "README.md",
     "LICENSE"
   ],
@@ -43,9 +43,9 @@
     "prepare": "husky",
     "commit": "node ./bin/cli.js run",
     "lint:commit": "commitlint --edit .git/COMMIT_EDITMSG --config lib/commitlint-preset.cjs",
-    "open-pr": "ai-pr",
     "release": "semantic-release",
-    "prepublishOnly": "node -e \"require('./lib/rules.js'); require('./lib/commitlint-preset.cjs'); require('./lib/init-env.js'); require('./lib/init-workspace.js');\""
+    "prepublishOnly": "node -e \"require('./lib/rules.js'); require('./lib/commitlint-preset.cjs'); require('./lib/init-env.js'); require('./lib/init-workspace.js');\"",
+    "pr:create": "ai-pr"
   },
   "dependencies": {
     "@commitlint/cli": "^20.5.0",
@@ -57,7 +57,7 @@
     "openai": "^6.33.0"
   },
   "devDependencies": {
-    "@verndale/ai-pr": "^1.0.0",
+    "@verndale/ai-pr": "^1.1.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",

package/.env.example

@@ -1,7 +0,0 @@
-# Copy to .env and/or .env.local in your project root (do not commit secrets).
-
-# @verndale/ai-commit — OPENAI_API_KEY: OpenAI API key for conventional commit messages (ai-commit run; optional for prepare-commit-msg with AI).
-OPENAI_API_KEY=
-
-# @verndale/ai-commit — COMMIT_AI_MODEL: OpenAI model for commit messages (optional; default gpt-4o-mini).
-# COMMIT_AI_MODEL=