@verndale/ai-commit 2.0.0 → 2.1.0

package/.env.example

@@ -0,0 +1,7 @@
+# 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=

package/README.md

@@ -13,11 +13,25 @@ AI-assisted [Conventional Commits](https://www.conventionalcommits.org/) with **
 pnpm add -D @verndale/ai-commit
 ```
 
+The same package works with **npm** or **yarn** (for example `npm install -D @verndale/ai-commit`); use your package manager’s `exec` / `npx` equivalent where the docs show `pnpm exec`.
+
+## 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`** / **`.env.example`** (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`** with the bundled template (destructive) or to overwrite existing Husky hook files. **`init` does not** fully replace a committed **`.env.example`**; it only appends missing ai-commit keys there.
+
 ## 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** (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.
+- **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.
 
 ## Commit policy (v2)
 
@@ -36,6 +50,7 @@ pnpm add -D @verndale/ai-commit
 | 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 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. |
 
@@ -51,7 +66,7 @@ pnpm add -D @verndale/ai-commit
 
 ## Husky (manual setup)
 
-Install Husky in your project (`husky` + `"prepare": "husky"` in `package.json` if needed), then add hooks.
+**`pnpm exec ai-commit init`** does this automatically. To add hooks by hand, install Husky (`husky` + `"prepare": "husky"` in `package.json` if needed), then add the snippets below.
 
 **`.husky/prepare-commit-msg`**
 
@@ -71,7 +86,9 @@ pnpm exec ai-commit prepare-commit-msg "$1" "$2"
 pnpm exec ai-commit lint --edit "$1"
 ```
 
-Use `npx` or `yarn` instead if that matches your toolchain.
+Hooks created by **`init`** use **`pnpm exec ai-commit`** when **`pnpm-lock.yaml`** exists, otherwise **`npx --no ai-commit`**. Edit the hook files if you use another runner.
+
+**If Husky is already set up:** **`init`** does not run **`npx husky@9 init`** when **`.husky/_/husky.sh`** already exists. **`package.json`** is only updated for missing **`commit`**, **`prepare`**, or **`devDependencies.husky`** (nothing is replaced). Hook files **`.husky/prepare-commit-msg`** and **`.husky/commit-msg`** are left alone if they already exist; use **`ai-commit init --force`** to overwrite them with the ai-commit snippets.
 
 ## commitlint without a second install
 
@@ -108,7 +125,7 @@ Copy `.env.example` to `.env` and/or `.env.local` and set **`OPENAI_API_KEY`**.
 | 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/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/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.

package/bin/cli.js

@@ -10,9 +10,18 @@ require("../lib/load-project-env.js").loadProjectEnv();
 const { generateAndValidate } = require("../lib/core/generate.js");
 const {
   assertInGitRepo,
+  isInGitRepo,
   hasStagedChanges,
   commitFromFile,
 } = require("../lib/core/git.js");
+const { mergeAiCommitEnvFile } = require("../lib/init-env.js");
+const {
+  detectPackageExec,
+  hookScript,
+  runHuskyInit,
+  mergePackageJsonForAiCommit,
+  warnIfPrepareMissingHusky,
+} = require("../lib/init-workspace.js");
 
 function presetPath() {
   return path.join(__dirname, "..", "lib", "commitlint-preset.cjs");
@@ -27,11 +36,13 @@ function printHelp() {
 
 Usage:
   ai-commit run
+  ai-commit init [--force] [--env-only] [--husky] [--workspace]
   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.
+  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.
   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).
 
@@ -51,6 +62,150 @@ function parseLintArgv(argv) {
   return { file: argv[i + 1] };
 }
 
+function parseInitArgv(argv) {
+  let force = false;
+  let husky = false;
+  let workspace = false;
+  let envOnly = false;
+  for (const a of argv) {
+    if (a === "--force") {
+      force = true;
+    } else if (a === "--husky") {
+      husky = true;
+    } else if (a === "--workspace") {
+      workspace = true;
+    } else if (a === "--env-only") {
+      envOnly = true;
+    }
+  }
+  return { force, husky, workspace, envOnly };
+}
+
+function cmdInit(argv) {
+  const { force, husky, workspace, envOnly } = parseInitArgv(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");
+
+  if (!fs.existsSync(examplePath)) {
+    throw new Error("Missing bundled .env.example (corrupt install?).");
+  }
+
+  const envDest = path.join(cwd, ".env");
+  const envResult = mergeAiCommitEnvFile(envDest, examplePath, { force });
+  const envRel = path.relative(cwd, envDest) || ".env";
+  switch (envResult.kind) {
+    case "replaced":
+      process.stdout.write(`Replaced ${envRel} with bundled template (--force).\n`);
+      break;
+    case "wrote":
+      process.stdout.write(`Wrote ${envRel} from bundled template.\n`);
+      break;
+    case "merged":
+      process.stdout.write(`Appended missing @verndale/ai-commit keys to ${envRel}.\n`);
+      break;
+    case "unchanged":
+      process.stdout.write(
+        `No missing @verndale/ai-commit keys in ${envRel}; left unchanged. Use --force to replace the file with the bundled template.\n`,
+      );
+      break;
+    default:
+      break;
+  }
+
+  const envExampleDest = path.join(cwd, ".env.example");
+  if (fs.existsSync(envExampleDest)) {
+    const exResult = mergeAiCommitEnvFile(envExampleDest, examplePath, { force: false });
+    const exRel = path.relative(cwd, envExampleDest) || ".env.example";
+    switch (exResult.kind) {
+      case "wrote":
+        process.stdout.write(`Wrote ${exRel} from bundled template.\n`);
+        break;
+      case "merged":
+        process.stdout.write(`Appended missing @verndale/ai-commit keys to ${exRel}.\n`);
+        break;
+      case "unchanged":
+        process.stdout.write(`No missing @verndale/ai-commit keys in ${exRel}; left unchanged.\n`);
+        break;
+      default:
+        break;
+    }
+  }
+
+  if (envOnly) {
+    return;
+  }
+
+  if (!isInGitRepo(cwd)) {
+    process.stdout.write(
+      "Not a git repository (or git unavailable); skipped Husky and package.json. Re-run from a repo root for hooks and scripts.\n",
+    );
+    return;
+  }
+
+  const huskyHelper = path.join(cwd, ".husky", "_", "husky.sh");
+
+  if (!fs.existsSync(huskyHelper)) {
+    const r = runHuskyInit(cwd);
+    if (!r.ok) {
+      process.stderr.write(
+        r.error
+          ? `husky init failed: ${r.error}\n`
+          : `husky init failed (exit ${r.status ?? "unknown"}). Run \`npx husky init\` in this repo, then run ai-commit init again.\n`,
+      );
+      process.exit(1);
+    }
+    process.stdout.write("Ran `npx husky@9 init`.\n");
+  } else {
+    process.stdout.write(
+      "Husky already initialized (found .husky/_/husky.sh); skipped `npx husky@9 init`.\n",
+    );
+  }
+
+  if (mergePackageJson) {
+    const pkgPath = path.join(cwd, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      const { changed } = mergePackageJsonForAiCommit(pkgPath);
+      if (changed) {
+        process.stdout.write(
+          "Updated package.json (commit script, prepare, and/or devDependencies.husky). Run your package manager install if you added dependencies.\n",
+        );
+      }
+      warnIfPrepareMissingHusky(pkgPath);
+    } else {
+      process.stdout.write("No package.json in this directory; skipped package.json merge (hooks still written).\n");
+    }
+  }
+
+  const huskyDir = path.join(cwd, ".husky");
+  if (!fs.existsSync(huskyDir)) {
+    fs.mkdirSync(huskyDir, { recursive: true });
+  }
+
+  const execPrefix = detectPackageExec(cwd);
+  const preparePath = path.join(huskyDir, "prepare-commit-msg");
+  const commitMsgPath = path.join(huskyDir, "commit-msg");
+
+  for (const [hookPath, hookKind] of [
+    [preparePath, "prepare-commit-msg"],
+    [commitMsgPath, "commit-msg"],
+  ]) {
+    const body = hookScript(execPrefix, hookKind);
+    if (fs.existsSync(hookPath) && !force) {
+      process.stderr.write(`Skipped ${path.relative(cwd, hookPath)} (already exists). Use --force to overwrite.\n`);
+    } else {
+      fs.writeFileSync(hookPath, body, { encoding: "utf8" });
+      try {
+        fs.chmodSync(hookPath, 0o755);
+      } catch {
+        // ignore on platforms that do not support chmod
+      }
+      process.stdout.write(`Wrote ${path.relative(cwd, hookPath)}.\n`);
+    }
+  }
+}
+
 function stripGitComments(text) {
   return text
     .split("\n")
@@ -124,6 +279,10 @@ async function main() {
     await cmdRun();
     return;
   }
+  if (cmd === "init") {
+    cmdInit(argv.slice(1));
+    return;
+  }
   if (cmd === "prepare-commit-msg") {
     const file = argv[1];
     const source = argv[2];

package/lib/core/git.js

@@ -22,10 +22,17 @@ function execGit(args, options = {}) {
   });
 }
 
-function assertInGitRepo(cwd = process.cwd()) {
+function isInGitRepo(cwd = process.cwd()) {
   try {
     execGit(["rev-parse", "--git-dir"], { cwd });
+    return true;
   } catch {
+    return false;
+  }
+}
+
+function assertInGitRepo(cwd = process.cwd()) {
+  if (!isInGitRepo(cwd)) {
     const err = new Error("Not a git repository (or git not available).");
     err.code = "ENOTGIT";
     throw err;
@@ -89,6 +96,7 @@ module.exports = {
   GIT_DIFF_MAX_BUFFER,
   DIFF_EXCLUDE_PATHSPECS,
   execGit,
+  isInGitRepo,
   assertInGitRepo,
   getStagedDiff,
   getChangedFiles,

package/lib/init-env.js

@@ -0,0 +1,168 @@
+"use strict";
+
+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 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).`,
+];
+
+/**
+ * Keys assigned on non-comment lines (`KEY=value` or `export KEY=value`).
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+function parseDotenvAssignedKeys(text) {
+  const keys = new Set();
+  for (const line of text.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) {
+      continue;
+    }
+    const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(t);
+    if (m) {
+      keys.add(m[1]);
+    }
+  }
+  return keys;
+}
+
+function hasOurDocForKey(lines, key) {
+  const needle = `${MARKER_PREFIX}${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.
+ * @param {string} content
+ * @returns {string}
+ */
+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, "COMMIT_AI_MODEL")) {
+    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);
+      changed = true;
+    }
+  }
+
+  return changed ? lines.join("\n") : content;
+}
+
+/**
+ * Build text to append so OPENAI_API_KEY / COMMIT_AI_MODEL placeholders exist.
+ * Returns null if nothing to add.
+ * @param {string} existing
+ * @returns {string | null}
+ */
+function buildAiCommitEnvAppend(existing) {
+  const keys = parseDotenvAssignedKeys(existing);
+  const hasCommitPlaceholder =
+    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`);
+  }
+  if (!keys.has("COMMIT_AI_MODEL") && !hasCommitPlaceholder) {
+    parts.push(`${DOC_COMMIT_MODEL[0]}\n# COMMIT_AI_MODEL=\n`);
+  }
+  if (parts.length === 0) {
+    return null;
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Merge bundled ai-commit env keys into a file. Never removes existing lines.
+ * @param {string} destPath
+ * @param {string} bundledPath
+ * @param {{ force?: boolean }} [options]
+ * @returns {{ kind: 'replaced' | 'wrote' | 'merged' | 'unchanged' }}
+ */
+function mergeAiCommitEnvFile(destPath, bundledPath, options = {}) {
+  const { force = false } = options;
+  const bundled = fs.readFileSync(bundledPath, "utf8");
+
+  if (force) {
+    fs.writeFileSync(destPath, bundled, "utf8");
+    return { kind: "replaced" };
+  }
+
+  let existing = "";
+  if (fs.existsSync(destPath)) {
+    existing = fs.readFileSync(destPath, "utf8");
+  }
+
+  if (!existing.trim()) {
+    fs.writeFileSync(destPath, bundled, "utf8");
+    return { kind: "wrote" };
+  }
+
+  let text = injectAiCommitDocsForExistingKeys(existing);
+  const append = buildAiCommitEnvAppend(text);
+  if (append !== null) {
+    const sep = text.endsWith("\n") ? "" : "\n";
+    text = `${text}${sep}${append}`;
+  }
+
+  if (text === existing) {
+    return { kind: "unchanged" };
+  }
+
+  fs.writeFileSync(destPath, text, "utf8");
+  return { kind: "merged" };
+}
+
+module.exports = {
+  parseDotenvAssignedKeys,
+  buildAiCommitEnvAppend,
+  injectAiCommitDocsForExistingKeys,
+  mergeAiCommitEnvFile,
+};

package/lib/init-workspace.js

@@ -0,0 +1,113 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const HUSKY_RANGE = "^9.1.7";
+
+/**
+ * @param {string} cwd
+ * @returns {string} `pnpm exec` when a pnpm lockfile exists; otherwise `npx --no` (npm and Yarn).
+ */
+function detectPackageExec(cwd) {
+  if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) {
+    return "pnpm exec";
+  }
+  return "npx --no";
+}
+
+/**
+ * @param {string} execPrefix from detectPackageExec
+ * @param {"prepare-commit-msg" | "commit-msg"} hook
+ */
+function hookScript(execPrefix, hook) {
+  const cmd =
+    hook === "prepare-commit-msg"
+      ? `${execPrefix} ai-commit prepare-commit-msg "$1" "$2"`
+      : `${execPrefix} ai-commit lint --edit "$1"`;
+  return `#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+${cmd}
+`;
+}
+
+/**
+ * Run Husky’s initializer when `.husky/_/husky.sh` is missing (installs husky, creates `.husky`, sets prepare).
+ * @param {string} cwd
+ * @returns {{ ok: boolean, status: number | null, error?: string }}
+ */
+function runHuskyInit(cwd) {
+  const npx = process.platform === "win32" ? "npx.cmd" : "npx";
+  const r = spawnSync(npx, ["--yes", "husky@9", "init"], {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  if (r.error) {
+    return { ok: false, status: null, error: r.error.message };
+  }
+  const status = r.status ?? 1;
+  return { ok: status === 0, status };
+}
+
+/**
+ * Ensure `commit` script, `prepare` for husky, and `devDependencies.husky`. Does not remove existing scripts.
+ * @param {string} packageJsonPath
+ * @returns {{ changed: boolean }}
+ */
+function mergePackageJsonForAiCommit(packageJsonPath) {
+  const raw = fs.readFileSync(packageJsonPath, "utf8");
+  const pkg = JSON.parse(raw);
+  let changed = false;
+
+  pkg.scripts = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  if (!pkg.scripts.commit) {
+    pkg.scripts.commit = "ai-commit run";
+    changed = true;
+  }
+  if (!pkg.scripts.prepare) {
+    pkg.scripts.prepare = "husky";
+    changed = true;
+  }
+
+  pkg.devDependencies =
+    pkg.devDependencies && typeof pkg.devDependencies === "object"
+      ? pkg.devDependencies
+      : {};
+  if (!pkg.devDependencies.husky) {
+    pkg.devDependencies.husky = HUSKY_RANGE;
+    changed = true;
+  }
+
+  if (changed) {
+    fs.writeFileSync(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+  }
+
+  return { changed };
+}
+
+/**
+ * If `prepare` exists but does not run husky, print a hint (do not rewrite arbitrary scripts).
+ * @param {string} packageJsonPath
+ */
+function warnIfPrepareMissingHusky(packageJsonPath) {
+  const raw = fs.readFileSync(packageJsonPath, "utf8");
+  const pkg = JSON.parse(raw);
+  const p = pkg.scripts && pkg.scripts.prepare;
+  if (typeof p === "string" && p.trim() && !/\bhusky\b/.test(p)) {
+    process.stderr.write(
+      "warning: package.json has a \"prepare\" script that does not mention husky; ensure Husky runs on install (see https://typicode.github.io/husky/).\n",
+    );
+  }
+}
+
+module.exports = {
+  HUSKY_RANGE,
+  detectPackageExec,
+  hookScript,
+  runHuskyInit,
+  mergePackageJsonForAiCommit,
+  warnIfPrepareMissingHusky,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verndale/ai-commit",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "AI-assisted conventional commits with bundled commitlint — one install, aligned rules",
   "license": "MIT",
   "author": "Verndale",
@@ -28,6 +28,7 @@
   "files": [
     "bin",
     "lib",
+    ".env.example",
     "README.md",
     "LICENSE"
   ],
@@ -42,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": "node tools/open-pr.js",
+    "open-pr": "ai-pr",
     "release": "semantic-release",
-    "prepublishOnly": "node -e \"require('./lib/rules.js'); require('./lib/commitlint-preset.cjs');\""
+    "prepublishOnly": "node -e \"require('./lib/rules.js'); require('./lib/commitlint-preset.cjs'); require('./lib/init-env.js'); require('./lib/init-workspace.js');\""
   },
   "dependencies": {
     "@commitlint/cli": "^20.5.0",
@@ -56,6 +57,7 @@
     "openai": "^6.33.0"
   },
   "devDependencies": {
+    "@verndale/ai-pr": "^1.0.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",