@verndale/ai-commit 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verndale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# @verndale/ai-commit
+
+AI-assisted [Conventional Commits](https://www.conventionalcommits.org/) with **bundled [commitlint](https://commitlint.js.org/)** so generated messages match the same rules enforced in hooks.
+
+## Requirements
+
+- **Node.js** `>=24.14.0`
+- This repo uses **pnpm** (`packageManager` is pinned in `package.json`; enable via [Corepack](https://nodejs.org/api/corepack.html): `corepack enable`).
+
+## Install
+
+```bash
+pnpm add -D @verndale/ai-commit
+```
+
+## 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`).
+- 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** (see [`.env.example`](./.env.example)): `PR_*` for [`tools/open-pr.js`](./tools/open-pr.js) / the **Create or update PR** workflow; `RELEASE_NOTES_AI_*` for the semantic-release notes plugin. Use a GitHub PAT as **`GH_TOKEN`** (or `GITHUB_TOKEN`) when calling the GitHub API outside Actions.
+
+## Commit policy (v2)
+
+- **Mandatory scope** — Every header is `type(scope): Subject` (or `type(scope)!:` when breaking). The **scope is not chosen by the model**; it is derived from staged paths (see [`lib/core/message-policy.js`](lib/core/message-policy.js)) and falls back to a short name from `package.json` (e.g. `ai-commit`).
+- **Types** — `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`.
+- **Subject** — Imperative, Beams-style (first word capitalized), max **50** characters, no trailing period.
+- **Body / footer** — Wrap lines at **72** characters when present.
+- **Issues** — If branch or diff mentions `#123`, footers may add `Refs #n` / `Closes #n` (no invented numbers).
+- **Breaking changes** — Only when policy detects governance-related files (commitlint, Husky, this package’s rules/preset); otherwise `!` and `BREAKING CHANGE:` lines are stripped.
+- **Staged diff for AI** — Lockfile and common binary globs are **excluded** from the diff text sent to the model (see [`lib/core/git.js`](lib/core/git.js)); path detection still uses the full staged file list.
+
+**Semver:** v2 tightens commitlint (mandatory scope, stricter lengths). If you `extends` this preset, review [lib/rules.js](lib/rules.js) and adjust overrides as needed.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `ai-commit run` | Generate a message from the staged diff and run `git commit`. |
+| `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. |
+
+## package.json scripts (example)
+
+```json
+{
+  "scripts": {
+    "commit": "ai-commit run"
+  }
+}
+```
+
+## Husky (manual setup)
+
+Install Husky in your project (`husky` + `"prepare": "husky"` in `package.json` if needed), then add hooks.
+
+**`.husky/prepare-commit-msg`**
+
+```sh
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm exec ai-commit prepare-commit-msg "$1" "$2"
+```
+
+**`.husky/commit-msg`**
+
+```sh
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm exec ai-commit lint --edit "$1"
+```
+
+Use `npx` or `yarn` instead if that matches your toolchain.
+
+## commitlint without a second install
+
+Use the packaged binary from hooks (`ai-commit lint --edit`) as above.
+
+To **extend** the default rules in your own `commitlint.config.js`, you can start from the same preset:
+
+```js
+module.exports = {
+  extends: ["@verndale/ai-commit"],
+  rules: {
+    // optional overrides
+  },
+};
+```
+
+Programmatic access to shared constants (types, line limits) is available via:
+
+```js
+const rules = require("@verndale/ai-commit/rules");
+```
+
+## Development (this repository)
+
+```bash
+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.
+
+### 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`** (`node tools/open-pr.js`) — 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.
+
+## Publishing (maintainers)
+
+Releases are automated with **[semantic-release](https://github.com/semantic-release/semantic-release)** on every push to **`main`** (see [`.releaserc.json`](./.releaserc.json) and [`tools/semantic-release-notes.cjs`](./tools/semantic-release-notes.cjs)).
+
+### Secrets and registry
+
+- **`NPM_TOKEN`** (repository or organization secret) — must be able to **`npm publish`** this package in CI **without** an interactive one-time password. The Release workflow sets both `NPM_TOKEN` and `NODE_AUTH_TOKEN` from it.
+  - **If the job fails with `EOTP` / “This operation requires a one-time password”:** the account has **2FA** that applies to publishes, and the token is not allowed to bypass OTP in CI. Fix it in one of these ways:
+    - **Classic token:** npmjs.com → **Access Tokens** → **Generate New Token** (classic) → type **Automation** (not “Publish”). Store it as **`NPM_TOKEN`**. Automation tokens are for CI and skip OTP on publish.
+    - **Granular token:** **New Granular Access Token** → turn on **Bypass two-factor authentication (2FA)**. Under **Packages and scopes**, set permissions to **Read and write** for **`@verndale/ai-commit`** (not “No access”). Leave **Allowed IP ranges** empty unless your org requires it—GitHub Actions egress IPs are not a single fixed range. Copy the token into **`NPM_TOKEN`**.
+  - Alternatively, finish **[Trusted Publishing](https://docs.npmjs.com/trusted-publishers)** for this repo and package so OIDC can authorize publishes; you may still need a compatible token or npm-side setup until that path is fully enabled—see npm’s docs for your account type.
+- **`GITHUB_TOKEN`** — provided by Actions for API calls (GitHub Release, etc.). The checkout and git plugin use **`SEMANTIC_RELEASE_TOKEN`** when set; otherwise they use `GITHUB_TOKEN` (see below).
+
+**npm provenance:** [`.releaserc.json`](./.releaserc.json) sets `"provenance": true` on `@semantic-release/npm`, which matches **npm Trusted Publishing** from this GitHub repository. On [npmjs.com](https://www.npmjs.com/), enable **Trusted Publishing** for this package linked to **`verndale/ai-commit`** (or your fork’s repo if you test there). If publish fails until that is configured, either finish Trusted Publishing setup or temporarily set `"provenance": false` in `.releaserc.json` (you lose the provenance badge).
+
+### Branch protection and release commits
+
+semantic-release pushes a **release commit** and **tag** back to `main` via `@semantic-release/git`. If **`main`** is protected and the default token cannot push, either allow **GitHub Actions** to bypass protection for this repository, or add a personal access token (classic: `repo`, or fine-grained: **Contents** read/write on this repo) as **`SEMANTIC_RELEASE_TOKEN`**. The Release workflow passes `SEMANTIC_RELEASE_TOKEN || GITHUB_TOKEN` to checkout and to semantic-release as `GITHUB_TOKEN`.
+
+### Commits that produce releases
+
+**Conventional Commits** on `main` drive `@semantic-release/commit-analyzer` (patch / minor / major). The analyzer uses the **first line** of each commit since the last tag; long PR bodies do not substitute for a releasable header.
+
+With the default plugin configuration in [`.releaserc.json`](./.releaserc.json) (no custom `releaseRules`), commits whose type is only **`chore`**, **`docs`**, **`ci`**, **`style`**, **`test`**, **`build`**, etc. **do not** trigger a version bump, `CHANGELOG.md` update, or tag. To ship semver for user-facing work, use a squash **PR title** (or merge commit message) with a releasable type—typically **`feat`**, **`fix`**, **`perf`**, or **`revert`**, or a **breaking** change (`!` / `BREAKING CHANGE:`). For **squash merge**, the merged commit message is usually the **PR title**, so match commitlint there. PR checks lint the PR title and the commits on the branch.
+
+If the project ever needs patch releases from `chore`/`docs`-only merges, maintainers can add **`releaseRules`** to `@semantic-release/commit-analyzer` in `.releaserc.json`; the default is to skip those types so releases stay signal-heavy.
+
+Tag-only npm publish was removed in favor of this flow to avoid double publishes. To try a release locally: `pnpm release` (requires appropriate tokens and git state; use a fork or `--dry-run` as appropriate).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/cli.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const { spawnSync } = require("child_process");
+
+require("../lib/load-project-env.js").loadProjectEnv();
+
+const { generateAndValidate } = require("../lib/core/generate.js");
+const {
+  assertInGitRepo,
+  hasStagedChanges,
+  commitFromFile,
+} = require("../lib/core/git.js");
+
+function presetPath() {
+  return path.join(__dirname, "..", "lib", "commitlint-preset.cjs");
+}
+
+function commitlintCliPath() {
+  return require.resolve("@commitlint/cli/cli.js");
+}
+
+function printHelp() {
+  process.stdout.write(`ai-commit — conventional commits + bundled commitlint (mandatory deterministic scope; see README).
+
+Usage:
+  ai-commit run
+  ai-commit prepare-commit-msg <file> [source]
+  ai-commit lint --edit <file>
+
+Commands:
+  run                  Generate a message from the staged diff and run git commit.
+  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).
+
+Environment:
+  OPENAI_API_KEY       Required for AI generation on \`run\` (and for prepare-commit-msg when you want AI).
+  COMMIT_AI_MODEL      Optional OpenAI model (default: gpt-4o-mini).
+
+Loads \`.env\` then \`.env.local\` from the current working directory (\`.env.local\` overrides).
+`);
+}
+
+function parseLintArgv(argv) {
+  const i = argv.indexOf("--edit");
+  if (i === -1 || !argv[i + 1]) {
+    throw new Error("Missing --edit <file> (example: ai-commit lint --edit \"$1\")");
+  }
+  return { file: argv[i + 1] };
+}
+
+function stripGitComments(text) {
+  return text
+    .split("\n")
+    .filter((line) => !/^\s*#/.test(line))
+    .join("\n");
+}
+
+async function cmdRun() {
+  assertInGitRepo();
+  if (!hasStagedChanges()) {
+    process.stderr.write("No staged changes. Stage files before running ai-commit (e.g. pnpm commit).\n");
+    process.exit(1);
+  }
+  const { message, warnings } = await generateAndValidate(process.cwd(), {
+    requireOpenAI: true,
+  });
+  for (const w of warnings) {
+    process.stderr.write(`warning: ${w}\n`);
+  }
+  commitFromFile(message);
+}
+
+async function cmdPrepareCommitMsg(file, source) {
+  if (source === "merge" || source === "squash") {
+    process.exit(0);
+  }
+  assertInGitRepo();
+  const raw = fs.readFileSync(file, "utf8");
+  const cleaned = stripGitComments(raw).trim();
+  if (cleaned.length > 0) {
+    process.exit(0);
+  }
+  if (!hasStagedChanges()) {
+    process.exit(0);
+  }
+  const { message, warnings } = await generateAndValidate(process.cwd(), {
+    requireOpenAI: false,
+  });
+  for (const w of warnings) {
+    process.stderr.write(`warning: ${w}\n`);
+  }
+  fs.writeFileSync(file, message, "utf8");
+}
+
+function cmdLint(editFile) {
+  const abs = path.isAbsolute(editFile)
+    ? editFile
+    : path.join(process.cwd(), editFile);
+  const r = spawnSync(
+    process.execPath,
+    [
+      commitlintCliPath(),
+      "--edit",
+      abs,
+      "--config",
+      presetPath(),
+    ],
+    { stdio: "inherit", cwd: process.cwd() },
+  );
+  process.exit(r.status ?? 1);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  if (!cmd || cmd === "-h" || cmd === "--help") {
+    printHelp();
+    process.exit(cmd ? 0 : 1);
+  }
+  if (cmd === "run") {
+    await cmdRun();
+    return;
+  }
+  if (cmd === "prepare-commit-msg") {
+    const file = argv[1];
+    const source = argv[2];
+    if (!file) {
+      throw new Error("Usage: ai-commit prepare-commit-msg <file> [source]");
+    }
+    await cmdPrepareCommitMsg(file, source);
+    return;
+  }
+  if (cmd === "lint") {
+    const { file } = parseLintArgv(argv);
+    cmdLint(file);
+    return;
+  }
+  throw new Error(`Unknown command: ${cmd}`);
+}
+
+main().catch((e) => {
+  process.stderr.write(`${e.message}\n`);
+  process.exit(1);
+});

package/lib/commitlint-preset.cjs

@@ -0,0 +1,8 @@
+"use strict";
+
+const { getCommitlintRuleOverrides } = require("./rules.js");
+
+module.exports = {
+  extends: ["@commitlint/config-conventional"],
+  rules: getCommitlintRuleOverrides(),
+};

package/lib/core/generate.js

@@ -0,0 +1,107 @@
+"use strict";
+
+const { lintMessage } = require("./lint.js");
+const { generateCommitMessageFull } = require("./openai.js");
+const {
+  detectIssueNumbers,
+  detectScopeFromFiles,
+  looksBreaking,
+  buildFallbackSubject,
+} = require("./message-policy.js");
+const {
+  getStagedDiff,
+  getChangedFiles,
+  getBranchName,
+} = require("./git.js");
+
+function buildChoreFallback({ files, scope, issueNumbers }) {
+  const subject = buildFallbackSubject(files);
+  let msg = `chore(${scope}): ${subject}\n\nSummarize staged changes and keep repository governance consistent.`;
+  if (issueNumbers.length) msg += `\n\nRefs #${issueNumbers[0]}`;
+  return msg;
+}
+
+async function generateAndValidate(
+  cwd = process.cwd(),
+  { requireOpenAI = false } = {},
+) {
+  const diff = getStagedDiff(cwd);
+  const files = getChangedFiles(cwd);
+  const branchName = getBranchName(cwd);
+  const issueNumbers = detectIssueNumbers({ branchName, diffText: diff });
+  const scope = detectScopeFromFiles(files, cwd);
+  const breakingAllowed = looksBreaking({ files });
+
+  if (requireOpenAI && !process.env.OPENAI_API_KEY) {
+    const err = new Error(
+      "OPENAI_API_KEY is not set. Add it to your environment or a .env / .env.local file in the project root.",
+    );
+    err.code = "ENOKEY";
+    throw err;
+  }
+
+  let msg = "";
+  let usedAi = false;
+  if (process.env.OPENAI_API_KEY) {
+    try {
+      msg = await generateCommitMessageFull(
+        {
+          diff,
+          files,
+          issueNumbers,
+          scope,
+          breakingAllowed,
+        },
+        { cwd },
+      );
+      if (msg) usedAi = true;
+    } catch (e) {
+      if (e.code === "ENOKEY") throw e;
+      msg = "";
+    }
+  }
+
+  if (!msg) {
+    msg = buildChoreFallback({ files, scope, issueNumbers });
+  }
+
+  let result = await lintMessage(msg, cwd);
+  if (result.valid) {
+    const warnings = [];
+    if (!usedAi) {
+      if (!process.env.OPENAI_API_KEY) {
+        warnings.push("OPENAI_API_KEY not set; used deterministic fallback message.");
+      } else {
+        warnings.push("Model output could not be used; used deterministic fallback message.");
+      }
+    }
+    return { message: msg, warnings };
+  }
+
+  const fallback = buildChoreFallback({ files, scope, issueNumbers });
+  result = await lintMessage(fallback, cwd);
+  if (result.valid) {
+    return {
+      message: fallback,
+      warnings: ["Used chore fallback after generated message failed commitlint."],
+    };
+  }
+
+  const minimal = `chore(${scope}): Update staged changes`;
+  result = await lintMessage(minimal, cwd);
+  if (result.valid) {
+    return {
+      message: minimal,
+      warnings: ["Used generic fallback after validation failed."],
+    };
+  }
+
+  const errors = [...result.errors, ...result.warnings]
+    .map((x) => x.message)
+    .filter(Boolean);
+  throw new Error(
+    `Commit message failed validation:\n${errors.join("\n") || result.input}`,
+  );
+}
+
+module.exports = { generateAndValidate, buildChoreFallback };

package/lib/core/git.js

@@ -0,0 +1,99 @@
+"use strict";
+
+const { execFileSync } = require("child_process");
+
+/** Large staged diffs must not throw ENOBUFS (align with generous buffer in prior tooling). */
+const GIT_DIFF_MAX_BUFFER = 50 * 1024 * 1024;
+
+/** Pathspecs excluded from staged diff text (noise / binary). */
+const DIFF_EXCLUDE_PATHSPECS = [
+  ":!pnpm-lock.yaml",
+  ":!*.png",
+  ":!*.jpg",
+  ":!*.jpeg",
+  ":!*.pdf",
+];
+
+function execGit(args, options = {}) {
+  return execFileSync("git", args, {
+    encoding: "utf8",
+    maxBuffer: GIT_DIFF_MAX_BUFFER,
+    ...options,
+  });
+}
+
+function assertInGitRepo(cwd = process.cwd()) {
+  try {
+    execGit(["rev-parse", "--git-dir"], { cwd });
+  } catch {
+    const err = new Error("Not a git repository (or git not available).");
+    err.code = "ENOTGIT";
+    throw err;
+  }
+}
+
+/**
+ * Staged diff for AI prompts; excludes lockfile and common binary globs.
+ */
+function getStagedDiff(cwd = process.cwd()) {
+  assertInGitRepo(cwd);
+  return execGit(
+    ["diff", "--cached", "--no-color", "--no-ext-diff", "--", ...DIFF_EXCLUDE_PATHSPECS],
+    { cwd },
+  );
+}
+
+function getChangedFiles(cwd = process.cwd()) {
+  assertInGitRepo(cwd);
+  return execGit(["diff", "--cached", "--name-only"], { cwd })
+    .trim()
+    .split("\n")
+    .filter(Boolean);
+}
+
+function getBranchName(cwd = process.cwd()) {
+  assertInGitRepo(cwd);
+  try {
+    return execGit(["rev-parse", "--abbrev-ref", "HEAD"], { cwd }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function getStagedStatSummary(cwd = process.cwd()) {
+  assertInGitRepo(cwd);
+  try {
+    return execGit(["diff", "--cached", "--stat"], { cwd }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function hasStagedChanges(cwd = process.cwd()) {
+  assertInGitRepo(cwd);
+  const out = execGit(["diff", "--cached", "--name-only"], { cwd });
+  return out.trim().length > 0;
+}
+
+function commitFromFile(message, cwd = process.cwd()) {
+  execFileSync("git", ["commit", "-F", "-"], {
+    cwd,
+    input: message,
+    encoding: "utf8",
+    maxBuffer: GIT_DIFF_MAX_BUFFER,
+    stdio: ["pipe", "inherit", "inherit"],
+  });
+}
+
+module.exports = {
+  GIT_DIFF_MAX_BUFFER,
+  DIFF_EXCLUDE_PATHSPECS,
+  execGit,
+  assertInGitRepo,
+  getStagedDiff,
+  getChangedFiles,
+  getBranchName,
+  getStagedStatSummary,
+  hasStagedChanges,
+  commitFromFile,
+};

package/lib/core/lint.js

@@ -0,0 +1,24 @@
+"use strict";
+
+const path = require("path");
+
+/**
+ * Lint full commit message text with the packaged commitlint preset (same rules as `ai-commit lint`).
+ */
+async function lintMessage(message, cwd = process.cwd()) {
+  const presetPath = path.join(__dirname, "..", "commitlint-preset.cjs");
+  const [{ default: load }, { default: lint }] = await Promise.all([
+    import("@commitlint/load"),
+    import("@commitlint/lint"),
+  ]);
+  const config = await load({}, { file: presetPath, cwd });
+  const result = await lint(message, config.rules, {
+    parserOpts: config.parserPreset?.parserOpts,
+    defaultIgnores: config.defaultIgnores,
+    ignores: config.ignores,
+    plugins: config.plugins ?? {},
+  });
+  return result;
+}
+
+module.exports = { lintMessage };

package/lib/core/message-policy.js

@@ -0,0 +1,189 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  COMMIT_TYPES,
+  SUBJECT_MAX_LENGTH,
+} = require("../rules.js");
+
+function unique(arr) {
+  return Array.from(new Set(arr));
+}
+
+/**
+ * Issue numbers from branch name and diff (#123).
+ */
+function detectIssueNumbers({ branchName, diffText }) {
+  const nums = [];
+  const branchMatches = branchName.match(/#\d+|\b\d{1,6}\b/g);
+  if (branchMatches) {
+    for (const m of branchMatches) {
+      const n = String(m).replace("#", "");
+      if (/^\d{1,6}$/.test(n)) nums.push(n);
+    }
+  }
+  const diffMatches = diffText.match(/#(\d{1,6})/g);
+  if (diffMatches) {
+    for (const m of diffMatches) {
+      const n = m.replace("#", "");
+      if (/^\d{1,6}$/.test(n)) nums.push(n);
+    }
+  }
+  return unique(nums);
+}
+
+/**
+ * Deterministic scope for @verndale/ai-commit repository layout.
+ */
+function detectScopeFromFiles(files, cwd = process.cwd()) {
+  const f = (p) => files.some((x) => x.startsWith(p));
+  if (f("lib/")) return "lib";
+  if (f("bin/")) return "cli";
+  if (f(".github/")) return "ci";
+  if (f("docs/")) return "docs";
+  return getDefaultScopeFromPackage(cwd);
+}
+
+function getDefaultScopeFromPackage(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  try {
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      if (pkg.name && typeof pkg.name === "string") {
+        const n = pkg.name;
+        if (n.includes("/")) return n.split("/").pop().replace(/^@/, "") || "repo";
+        return n.replace(/^@/, "") || "repo";
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return "repo";
+}
+
+/**
+ * Breaking allowed when governance / hook / preset files change.
+ */
+function looksBreaking({ files }) {
+  return files.some(
+    (file) =>
+      file.includes("commitlint.config") ||
+      file.endsWith("commitlint-preset.cjs") ||
+      file.endsWith("lib/rules.js") ||
+      file.startsWith(".husky/"),
+  );
+}
+
+function wrap72(text) {
+  const width = 72;
+  const lines = [];
+  for (const paragraph of text.split(/\n\n+/)) {
+    const p = paragraph.trim();
+    if (!p) {
+      lines.push("");
+      continue;
+    }
+    const words = p.split(/\s+/);
+    let line = "";
+    for (const w of words) {
+      if (!line) line = w;
+      else if (line.length + 1 + w.length <= width) line += ` ${w}`;
+      else {
+        lines.push(line);
+        line = w;
+      }
+    }
+    if (line) lines.push(line);
+    lines.push("");
+  }
+  while (lines.length && lines[lines.length - 1] === "") lines.pop();
+  return lines.join("\n");
+}
+
+function stripGitComments(text) {
+  return text
+    .split("\n")
+    .filter((line) => !line.trim().startsWith("#"))
+    .join("\n")
+    .trim();
+}
+
+function parseMessage(raw) {
+  const cleaned = stripGitComments(raw || "");
+  const parts = cleaned.split(/\n\n+/);
+  const header = (parts[0] || "").trim();
+  const rest = parts.slice(1).join("\n\n").trim();
+  return { header, rest };
+}
+
+function stripBreakingFooterLines(text) {
+  const lines = text.split("\n").filter((line) => !/^BREAKING CHANGE:/i.test(line.trim()));
+  while (lines.length && lines[lines.length - 1].trim() === "") lines.pop();
+  return lines.join("\n").trim();
+}
+
+function extractTypeAndSubject(header) {
+  const types = COMMIT_TYPES.join("|");
+  const re = new RegExp(
+    `^(${types})(?:\\([^)]+\\))?(!)?:\\s(.+)$`,
+  );
+  const m = header.match(re);
+  if (!m) {
+    return {
+      type: "chore",
+      subject: header.replace(/^[^:]+:\s*/, "").trim(),
+      aiBreaking: false,
+    };
+  }
+  return { type: m[1], subject: (m[3] || "").trim(), aiBreaking: !!m[2] };
+}
+
+function normalizeSubject(subject) {
+  let s = (subject || "").trim();
+  while (s.endsWith(".")) s = s.slice(0, -1);
+  if (s && !/^[A-Z]/.test(s)) s = s.charAt(0).toUpperCase() + s.slice(1);
+  if (s.length > SUBJECT_MAX_LENGTH) s = s.slice(0, SUBJECT_MAX_LENGTH).trimEnd();
+  return s;
+}
+
+function buildFallbackSubject(files) {
+  const buckets = [];
+  if (files.some((f) => f.includes("release") || f.includes(".releaserc") || f.includes("CHANGELOG"))) {
+    buckets.push("Release automation");
+  }
+  if (
+    files.some(
+      (f) =>
+        f.includes("commitlint") ||
+        f.includes(".husky") ||
+        f.includes("CONTRIBUTING"),
+    )
+  ) {
+    buckets.push("Commit governance");
+  }
+  if (files.some((f) => f.startsWith(".github/"))) buckets.push("CI workflow");
+  if (files.some((f) => f.startsWith("lib/") || f.startsWith("bin/"))) {
+    buckets.push("Package implementation");
+  }
+  if (files.some((f) => f.startsWith("docs/"))) buckets.push("Documentation");
+
+  const summary = buckets.length ? buckets[0] : "Repository updates";
+  let s = summary.length > SUBJECT_MAX_LENGTH ? summary.slice(0, SUBJECT_MAX_LENGTH) : summary;
+  if (s && !/^[A-Z]/.test(s)) s = s.charAt(0).toUpperCase() + s.slice(1);
+  return s;
+}
+
+module.exports = {
+  detectIssueNumbers,
+  detectScopeFromFiles,
+  getDefaultScopeFromPackage,
+  looksBreaking,
+  wrap72,
+  stripGitComments,
+  parseMessage,
+  stripBreakingFooterLines,
+  extractTypeAndSubject,
+  normalizeSubject,
+  buildFallbackSubject,
+};

package/lib/core/openai.js

@@ -0,0 +1,249 @@
+"use strict";
+
+const OpenAI = require("openai");
+const { COMMIT_TYPES } = require("../rules.js");
+const {
+  parseMessage,
+  extractTypeAndSubject,
+  normalizeSubject,
+  stripBreakingFooterLines,
+  wrap72,
+} = require("./message-policy.js");
+
+const DEFAULT_MODEL = "gpt-4o-mini";
+const DIFF_PROMPT_SLICE = 12000;
+
+function getClient() {
+  const key = process.env.OPENAI_API_KEY;
+  if (!key) {
+    const err = new Error(
+      "OPENAI_API_KEY is not set. Add it to your environment or a .env / .env.local file in the project root.",
+    );
+    err.code = "ENOKEY";
+    throw err;
+  }
+  return new OpenAI({ apiKey: key });
+}
+
+async function callOpenAI({ prompt, model = process.env.COMMIT_AI_MODEL || DEFAULT_MODEL }) {
+  const openai = getClient();
+  const response = await openai.chat.completions.create({
+    model,
+    temperature: 0.1,
+    messages: [
+      {
+        role: "system",
+        content:
+          "You produce strict Conventional Commit messages. Body text follows classic Beams-style prose: full sentences, imperative clarity, 72-character wrap, and normal sentence capitalization (capitalize the first word of each sentence; proper nouns as in English).",
+      },
+      { role: "user", content: prompt },
+    ],
+  });
+  return response.choices?.[0]?.message?.content?.trim() || "";
+}
+
+function coerceType(type) {
+  return COMMIT_TYPES.includes(type) ? type : "chore";
+}
+
+function assembleFromRaw(raw, { scope, breakingAllowed, issueNumbers }) {
+  if (!raw) return "";
+  let parsed = parseMessage(raw);
+  let { type, subject, aiBreaking } = extractTypeAndSubject(parsed.header);
+  type = coerceType(type);
+
+  const aiFooterBreaking = /^BREAKING CHANGE:/im.test(parsed.rest || "");
+  const finalBreaking = !!(breakingAllowed && (aiBreaking || aiFooterBreaking));
+
+  subject = normalizeSubject(subject);
+  if (!subject) return "";
+
+  parsed.header = `${type}(${scope})${finalBreaking ? "!" : ""}: ${subject}`;
+
+  if (!finalBreaking) parsed.rest = stripBreakingFooterLines(parsed.rest || "");
+
+  const wrappedRest = parsed.rest ? wrap72(parsed.rest.trim()) : "";
+  let msg = parsed.header + (wrappedRest ? `\n\n${wrappedRest}` : "");
+
+  if (issueNumbers.length) {
+    const lower = msg.toLowerCase();
+    const missingAll = issueNumbers.every((n) => !lower.includes(`#${n}`));
+    if (missingAll) msg += `\n\n${issueNumbers.map((n) => `Refs #${n}`).join("\n")}`;
+  }
+
+  return msg.trim();
+}
+
+function formatLintErrors(result) {
+  return [...result.errors, ...result.warnings]
+    .map((x) => `${x.name}: ${x.message}`)
+    .filter(Boolean)
+    .join("\n");
+}
+
+function buildBasePrompt({
+  diff,
+  files,
+  issueNumbers,
+  breakingAllowed,
+}) {
+  const issueHint = issueNumbers.length
+    ? `
+ISSUE REFERENCES:
+Detected issue numbers:
+${issueNumbers.map((n) => `- #${n}`).join("\n")}
+
+Footer:
+- Use "Closes #<n>" only if the commit fully resolves the issue
+- Otherwise use "Refs #<n>"
+- One reference per line
+- Do NOT invent issue numbers
+`
+    : `
+ISSUE REFERENCES:
+No issue numbers detected.
+Do NOT invent issue references.
+`;
+
+  const breakingRules = breakingAllowed
+    ? `
+BREAKING CHANGE:
+You MAY mark this as breaking if it truly breaks compatibility.
+If breaking, include:
+- "!" after the type (before the colon), e.g. feat!: Subject
+- Footer line: BREAKING CHANGE: <short explanation>
+If NOT breaking, do not include "!" or BREAKING CHANGE footer.
+`
+    : `
+BREAKING CHANGE:
+You are NOT allowed to mark this as breaking.
+Do NOT add "!" before the colon.
+Do NOT add any "BREAKING CHANGE:" footer lines.
+`;
+
+  const typesList = COMMIT_TYPES.join(", ");
+
+  return `
+Generate ONE git commit message.
+
+You may choose the <type> from: ${typesList}.
+Do NOT choose a scope; scope will be injected automatically.
+
+Style: classic "How to Write a Git Commit Message" (Beams-style) prose—clear, imperative subject line; body is readable narrative, not bullet fragments or all-lowercase streams.
+
+Format (first line MUST be without scope — use type only):
+<type>: <Subject>
+(blank line)
+<Detailed Body>
+(blank line)
+<Footer>
+
+Subject rules:
+- Imperative mood
+- First letter capitalized
+- Max 50 characters
+- No trailing period
+
+Body rules:
+- Robust body (2–4 short paragraphs) when the change warrants explanation
+- Wrap at 72 characters max
+- Explain WHAT changed, WHY, and IMPACT
+- Write in complete sentences with normal sentence capitalization.
+
+Footer rules:
+- Issue references only if detected
+- Breaking footer only if allowed
+
+Formatting rules:
+- Separate header/body/footer with ONE blank line each
+- No markdown fences, no backticks
+- Output ONLY the commit message text
+
+${issueHint}
+${breakingRules}
+
+Changed files:
+${files.join("\n")}
+
+Staged diff (truncated):
+${diff.slice(0, DIFF_PROMPT_SLICE)}
+`.trim();
+}
+
+function buildRetryPrompt(basePrompt, lintFeedback) {
+  return `
+Your previous output failed commitlint:
+${lintFeedback}
+
+Regenerate the commit message. Remember:
+- First line format: <type>: <Subject> only (no scope in the first line)
+- Subject <= 50 chars, capitalized, no trailing period
+- Types allowed: ${COMMIT_TYPES.join(", ")}
+- Provide a robust body in Beams-style prose when appropriate
+Return ONLY the commit message text.
+
+${basePrompt}
+`.trim();
+}
+
+/**
+ * Full pipeline: AI (no scope in header) → inject deterministic scope → wrap → issue footers → lint → one retry.
+ */
+async function generateCommitMessageFull(
+  {
+    diff,
+    files,
+    issueNumbers,
+    scope,
+    breakingAllowed,
+  },
+  { cwd, model } = {},
+) {
+  const basePrompt = buildBasePrompt({
+    diff,
+    files,
+    issueNumbers,
+    breakingAllowed,
+  });
+
+  const { lintMessage } = require("./lint.js");
+
+  let raw = "";
+  try {
+    raw = await callOpenAI({ prompt: basePrompt, model });
+  } catch {
+    return "";
+  }
+
+  let msg = assembleFromRaw(raw, { scope, breakingAllowed, issueNumbers });
+  if (!msg) return "";
+
+  let result = await lintMessage(msg, cwd);
+  if (result.valid) return msg;
+
+  const feedback = formatLintErrors(result);
+  let retryRaw = "";
+  try {
+    retryRaw = await callOpenAI({
+      prompt: buildRetryPrompt(basePrompt, feedback),
+      model,
+    });
+  } catch {
+    return "";
+  }
+
+  msg = assembleFromRaw(retryRaw, { scope, breakingAllowed, issueNumbers });
+  if (!msg) return "";
+
+  result = await lintMessage(msg, cwd);
+  return result.valid ? msg : "";
+}
+
+module.exports = {
+  generateCommitMessageFull,
+  callOpenAI,
+  assembleFromRaw,
+  buildBasePrompt,
+  getClient,
+  DEFAULT_MODEL,
+};

package/lib/load-project-env.js

@@ -0,0 +1,15 @@
+"use strict";
+
+const path = require("path");
+const dotenv = require("dotenv");
+
+/**
+ * Load `.env` then `.env.local` from cwd (`.env.local` overrides duplicate keys).
+ * @param {string} [cwd=process.cwd()]
+ */
+function loadProjectEnv(cwd = process.cwd()) {
+  dotenv.config({ path: path.join(cwd, ".env") });
+  dotenv.config({ path: path.join(cwd, ".env.local"), override: true });
+}
+
+module.exports = { loadProjectEnv };

package/lib/rules.js

@@ -0,0 +1,76 @@
+"use strict";
+
+/** @see @commitlint/types RuleConfigSeverity — avoid require() (package is ESM-only). */
+const ERROR = 2;
+const OFF = 0;
+
+/**
+ * Single source of truth for commit types, lengths, and commitlint rules.
+ * Scope is mandatory (injected deterministically by the generator); Beams-style subjects
+ * start with a capital letter, so subject-case from conventional config is disabled.
+ */
+
+const COMMIT_TYPES = [
+  "build",
+  "chore",
+  "ci",
+  "docs",
+  "feat",
+  "fix",
+  "perf",
+  "refactor",
+  "revert",
+  "style",
+  "test",
+];
+
+/** Subject line only (after `type(scope):`). */
+const SUBJECT_MAX_LENGTH = 50;
+
+/** Full first line: type(scope)!: subject */
+const HEADER_MAX_LENGTH = 120;
+
+const BODY_MAX_LINE_LENGTH = 72;
+const FOOTER_MAX_LINE_LENGTH = 72;
+
+/** Scopes produced by detectScopeFromFiles in this package (lowercase, hyphens). */
+const SCOPE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function getCommitlintRuleOverrides() {
+  return {
+    "type-enum": [ERROR, "always", COMMIT_TYPES],
+    "scope-empty": [ERROR, "never"],
+    "scope-case": [ERROR, "always", "lower-case"],
+    "subject-max-length": [ERROR, "always", SUBJECT_MAX_LENGTH],
+    "subject-case": [OFF],
+    "header-max-length": [ERROR, "always", HEADER_MAX_LENGTH],
+    "body-max-line-length": [ERROR, "always", BODY_MAX_LINE_LENGTH],
+    "footer-max-line-length": [ERROR, "always", FOOTER_MAX_LINE_LENGTH],
+  };
+}
+
+/**
+ * Short policy text for docs / external tooling (generator uses richer prompts in openai.js).
+ */
+function getPromptInstructions() {
+  return [
+    "Conventional Commits with mandatory scope: type(scope): Subject (or type(scope)!: when breaking).",
+    "",
+    `Types: ${COMMIT_TYPES.join(", ")}.`,
+    "Scope is chosen deterministically from changed paths (not by the model).",
+    `Subject: imperative, first word capitalized (Beams-style), max ${SUBJECT_MAX_LENGTH} characters, no trailing period.`,
+    `Body: optional; if present, blank line after header; wrap at ${BODY_MAX_LINE_LENGTH} characters.`,
+    `Footer: issues (Refs #n / Closes #n), BREAKING CHANGE: when applicable; wrap at ${FOOTER_MAX_LINE_LENGTH} characters.`,
+  ].join("\n");
+}
+
+module.exports = {
+  COMMIT_TYPES,
+  SUBJECT_MAX_LENGTH,
+  HEADER_MAX_LENGTH,
+  BODY_MAX_LINE_LENGTH,
+  FOOTER_MAX_LINE_LENGTH,
+  SCOPE_PATTERN,
+  getCommitlintRuleOverrides,
+  getPromptInstructions,
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@verndale/ai-commit",
+  "version": "2.0.0",
+  "description": "AI-assisted conventional commits with bundled commitlint — one install, aligned rules",
+  "license": "MIT",
+  "author": "Verndale",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verndale/ai-commit.git"
+  },
+  "keywords": [
+    "commit",
+    "commitlint",
+    "conventional-commits",
+    "openai",
+    "git",
+    "husky"
+  ],
+  "type": "commonjs",
+  "main": "lib/commitlint-preset.cjs",
+  "exports": {
+    ".": "./lib/commitlint-preset.cjs",
+    "./rules": "./lib/rules.js"
+  },
+  "bin": {
+    "ai-commit": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "packageManager": "pnpm@10.11.0",
+  "engines": {
+    "node": ">=24.14.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepare": "husky",
+    "commit": "node ./bin/cli.js run",
+    "lint:commit": "commitlint --edit .git/COMMIT_EDITMSG --config lib/commitlint-preset.cjs",
+    "open-pr": "node tools/open-pr.js",
+    "release": "semantic-release",
+    "prepublishOnly": "node -e \"require('./lib/rules.js'); require('./lib/commitlint-preset.cjs');\""
+  },
+  "dependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@commitlint/lint": "^20.5.0",
+    "@commitlint/load": "^20.5.0",
+    "@commitlint/parse": "^20.5.0",
+    "dotenv": "^16.4.7",
+    "openai": "^6.33.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "husky": "^9.1.7",
+    "semantic-release": "^25.0.3"
+  }
+}