@yourfam/yf-commit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YourFam
+
+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,99 @@
+# yf-commit
+
+AI commit message from your staged git diff.
+
+```
+npx @yourfam/yf-commit
+```
+
+Writes a conventional first line (`emoji type(scope): …`) plus WHY, WHAT CHANGED, and FILES IMPACTED. It does **not** run your test suite and does **not** append worktree / branch / machine trailers.
+
+YourFam does not give you an API key. Use your own OpenAI-compatible key.
+
+## Install
+
+Node 20+. Friend one-liner:
+
+```bash
+npx @yourfam/yf-commit
+```
+
+Or install once:
+
+```bash
+npm install -g @yourfam/yf-commit
+yf-commit
+```
+
+The command is `yf-commit` (not `ai-commit` — that name is already used by other packages).
+
+## First run / `yf-commit init`
+
+The first `yf-commit` with no key **is** setup (same idea as `gh auth login`).
+
+1. Pick a provider (numbered list): OpenAI, DeepSeek, xAI (Grok), Groq, Ollama (local).
+2. Pick a model. First item is always **Auto (recommended)** — a cheap, fast Chat Completions model for summarizing a diff. Named picks stay pinned; Auto tracks our lightweight default.
+3. Paste an API key (hidden). Skipped for Ollama.
+
+Saved to `~/.yf-commit/config.json` (Windows: `%USERPROFILE%\.yf-commit\config.json`). Mode `0600` where the OS allows. This file lives in your home directory; never commit it.
+
+```bash
+yf-commit init         # wizard
+yf-commit init --show  # provider, model, base URL, masked key
+yf-commit init --reset # delete saved config
+```
+
+Primary env var: **`YF_COMMIT_API_KEY`**. You can also:
+
+```bash
+export YF_COMMIT_API_KEY=...
+```
+
+`OPENAI_API_KEY` is also accepted if the others are unset.
+
+Need a host we don't list? Set `YF_COMMIT_BASE_URL` and `YF_COMMIT_MODEL`.
+
+| Env | Config key | Default |
+|---|---|---|
+| `YF_COMMIT_API_KEY` | `apiKey` | — |
+| `YF_COMMIT_BASE_URL` | `baseUrl` | `https://api.openai.com/v1` |
+| `YF_COMMIT_MODEL` | `model` | `auto` → lightweight model for that provider |
+
+## Usage
+
+Stage files, then:
+
+```bash
+yf-commit              # print draft in the terminal → confirm → git commit
+yf-commit -y           # no confirm (also --yes, --auto)
+yf-commit --print      # print only; do not commit
+yf-commit --all        # git add -A, then same as default
+yf-commit --type fix   # force type
+yf-commit --type 4     # same (1–6: chore, docs, feat, fix, refactor, test)
+```
+
+Default: the draft is printed in the terminal. Press Enter or `y` to commit, `n` or Ctrl+C to cancel. It does not open an editor.
+
+If nothing is staged: one-line error, exit non-zero. It will not `git add -A` unless you pass `--all`.
+
+Non-interactive (CI / scripts): pass `--print` or `-y`. It will not hang waiting for a paste or a confirm.
+
+## Message format
+
+```
+✨ feat(cli): add --print to skip git commit
+
+💡 WHY:
+- Friends can preview a message without committing
+
+🔧 WHAT CHANGED:
+- Added a --print flag that writes the draft to stdout and exits
+
+📁 FILES IMPACTED:
+- src/index.js
+- README.md
+```
+
+## License
+
+MIT

package/bin/yf-commit.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from "../src/index.js";
+
+run(process.argv);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@yourfam/yf-commit",
+  "version": "0.1.0",
+  "description": "AI commit message from your staged git diff",
+  "type": "module",
+  "bin": {
+    "yf-commit": "./bin/yf-commit.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "yf-commit": "node ./bin/yf-commit.js"
+  },
+  "keywords": [
+    "git",
+    "commit",
+    "conventional-commits",
+    "cli"
+  ],
+  "author": "YourFam",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YourFam/yf-commit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YourFam/yf-commit/issues"
+  },
+  "homepage": "https://github.com/YourFam/yf-commit#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0"
+  }
+}

package/src/args.js

@@ -0,0 +1,107 @@
+import { CliError } from "./errors.js";
+import { parseType } from "./types.js";
+
+/**
+ * @typedef {object} ParsedArgs
+ * @property {"commit" | "init"} command
+ * @property {boolean} auto
+ * @property {boolean} all
+ * @property {boolean} print
+ * @property {string | null} type
+ * @property {boolean} show
+ * @property {boolean} reset
+ * @property {boolean} help
+ * @property {boolean} version
+ */
+
+/**
+ * @param {string[]} argv process.argv
+ * @returns {ParsedArgs}
+ */
+export function parseArgs(argv) {
+  const args = argv.slice(2);
+  /** @type {ParsedArgs} */
+  const result = {
+    command: "commit",
+    auto: false,
+    all: false,
+    print: false,
+    type: null,
+    show: false,
+    reset: false,
+    help: false,
+    version: false,
+  };
+
+  let i = 0;
+  if (args[0] === "init") {
+    result.command = "init";
+    i = 1;
+  }
+
+  while (i < args.length) {
+    const a = args[i];
+    if (a === "--auto" || a === "--yes" || a === "-y") {
+      result.auto = true;
+    } else if (a === "--all") {
+      result.all = true;
+    } else if (a === "--print") {
+      result.print = true;
+    } else if (a === "--show") {
+      result.show = true;
+    } else if (a === "--reset") {
+      result.reset = true;
+    } else if (a === "--help" || a === "-h") {
+      result.help = true;
+    } else if (a === "--version" || a === "-V") {
+      result.version = true;
+    } else if (a === "--type") {
+      const value = args[i + 1];
+      if (value == null || value.startsWith("-")) {
+        throw new CliError("Flag --type requires a value: feat|fix|… or 1–6.");
+      }
+      result.type = parseType(value);
+      i += 1;
+    } else if (a.startsWith("--type=")) {
+      result.type = parseType(a.slice("--type=".length));
+    } else if (a.startsWith("-")) {
+      throw new CliError(
+        `Unknown flag: ${a}\nSee yf-commit --help`,
+      );
+    } else {
+      throw new CliError(
+        `Unknown argument: ${a}\nNot a command. Use yf-commit, yf-commit init, or flags like -y / --auto.`,
+      );
+    }
+    i += 1;
+  }
+
+  if (result.command === "commit") {
+    if (result.show) {
+      throw new CliError("Use yf-commit init --show");
+    }
+    if (result.reset) {
+      throw new CliError("Use yf-commit init --reset");
+    }
+  }
+
+  return result;
+}
+
+export function helpText() {
+  return `yf-commit — AI commit message from your staged git diff
+
+Usage:
+  yf-commit              Generate, print draft, confirm, then git commit
+  yf-commit -y           Commit immediately (also --yes, --auto)
+  yf-commit --print      Print message only; do not commit
+  yf-commit --all        git add -A, then same as default
+  yf-commit --type fix   Force type (name or 1–6)
+  yf-commit init         Provider, model, API key → ~/.yf-commit/config.json
+  yf-commit init --show  Masked status
+  yf-commit init --reset Delete saved config
+
+This does not run your test suite. YourFam does not give you an API key.
+
+Need a host we don't list? Set YF_COMMIT_BASE_URL and YF_COMMIT_MODEL.`;
+}

package/src/config.js

@@ -0,0 +1,100 @@
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import {
+  DEFAULT_PROVIDER_ID,
+  isOllama,
+  providerById,
+  resolveAutoModel,
+} from "./providers.js";
+
+export function configDir() {
+  return path.join(homedir(), ".yf-commit");
+}
+
+export function configPath() {
+  return path.join(configDir(), "config.json");
+}
+
+/**
+ * @returns {Record<string, string> | null}
+ */
+export function loadConfig() {
+  try {
+    const raw = readFileSync(configPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {object} data
+ */
+export function saveConfig(data) {
+  const dir = configDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const payload = { ...data };
+  if (!payload.apiKey) delete payload.apiKey;
+  writeFileSync(configPath(), `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
+export function deleteConfig() {
+  try {
+    unlinkSync(configPath());
+    return true;
+  } catch (err) {
+    if (err && err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+/**
+ * @param {string} key
+ */
+export function maskKey(key) {
+  if (!key) return "(none)";
+  const last = key.slice(-4);
+  if (key.startsWith("sk-")) return `sk-…${last}`;
+  if (key.length <= 4) return "…";
+  return `…${last}`;
+}
+
+/**
+ * @param {Record<string, string> | null} fileConfig
+ */
+export function resolveSettings(fileConfig = null) {
+  const file = fileConfig && typeof fileConfig === "object" ? fileConfig : {};
+  const provider = file.provider || DEFAULT_PROVIDER_ID;
+  const fallback = providerById(provider) || providerById(DEFAULT_PROVIDER_ID);
+  const baseUrl =
+    process.env.YF_COMMIT_BASE_URL || file.baseUrl || fallback.baseUrl;
+  const model = process.env.YF_COMMIT_MODEL || file.model || "auto";
+  const resolvedModel =
+    model === "auto" ? resolveAutoModel(provider, baseUrl) : model;
+  const apiKey =
+    process.env.YF_COMMIT_API_KEY ||
+    file.apiKey ||
+    process.env.OPENAI_API_KEY ||
+    "";
+  return {
+    provider,
+    baseUrl,
+    model,
+    resolvedModel,
+    apiKey,
+  };
+}
+
+/**
+ * @param {ReturnType<typeof resolveSettings>} settings
+ */
+export function hasUsableKey(settings) {
+  if (isOllama(settings.provider, settings.baseUrl)) return true;
+  return Boolean(settings.apiKey);
+}

package/src/errors.js

@@ -0,0 +1,11 @@
+export class CliError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} [exitCode]
+   */
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}

package/src/git.js

@@ -0,0 +1,80 @@
+import { spawnSync } from "node:child_process";
+import { CliError } from "./errors.js";
+
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ * @param {{ input?: string }} [opts]
+ */
+function git(cwd, args, opts = {}) {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    input: opts.input,
+    windowsHide: true,
+  });
+  if (result.error) {
+    if (result.error.code === "ENOENT") {
+      throw new CliError("git was not found on PATH.");
+    }
+    throw new CliError(result.error.message);
+  }
+  if (result.status !== 0) {
+    const err = (result.stderr || result.stdout || "").trim();
+    throw new CliError(err || `git ${args.join(" ")} failed`);
+  }
+  return result.stdout ?? "";
+}
+
+/**
+ * @param {string} cwd
+ */
+export function ensureGitRepo(cwd) {
+  try {
+    const out = git(cwd, ["rev-parse", "--is-inside-work-tree"]).trim();
+    if (out !== "true") {
+      throw new CliError("Not a git work tree. Run this from a git repository.");
+    }
+  } catch (err) {
+    if (err instanceof CliError) {
+      if (/not a git repository/i.test(err.message)) {
+        throw new CliError("Not a git work tree. Run this from a git repository.");
+      }
+      throw err;
+    }
+    throw new CliError("Not a git work tree. Run this from a git repository.");
+  }
+}
+
+/**
+ * @param {string} cwd
+ */
+export function gitAddAll(cwd) {
+  git(cwd, ["add", "-A"]);
+}
+
+/**
+ * @param {string} cwd
+ */
+export function getStagedDiff(cwd) {
+  return git(cwd, ["diff", "--cached"]);
+}
+
+/**
+ * @param {string} diff
+ */
+export function requireStagedDiff(diff) {
+  if (!diff || !String(diff).trim()) {
+    throw new CliError("Nothing staged. Stage files first, or pass --all.");
+  }
+  return diff;
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} message
+ */
+export function commitWithMessage(cwd, message) {
+  git(cwd, ["commit", "-F", "-"], { input: message });
+}

package/src/index.js

@@ -0,0 +1,131 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { helpText, parseArgs } from "./args.js";
+import {
+  hasUsableKey,
+  loadConfig,
+  resolveSettings,
+} from "./config.js";
+import { CliError } from "./errors.js";
+import {
+  commitWithMessage,
+  ensureGitRepo,
+  getStagedDiff,
+  gitAddAll,
+  requireStagedDiff,
+} from "./git.js";
+import {
+  isTTY,
+  offerInitNow,
+  printSetupBlock,
+  runInitCommand,
+} from "./init.js";
+import { completeChat } from "./llm.js";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildSystemPrompt, buildUserPrompt } from "./prompt.js";
+
+const pkg = JSON.parse(
+  readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"),
+    "utf8",
+  ),
+);
+
+export async function main(argv) {
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    console.log(helpText());
+    return 0;
+  }
+  if (args.version) {
+    console.log(pkg.version);
+    return 0;
+  }
+
+  if (args.command === "init") {
+    return runInitCommand(args);
+  }
+
+  const cwd = process.cwd();
+  ensureGitRepo(cwd);
+
+  if (args.all) gitAddAll(cwd);
+
+  const diff = requireStagedDiff(getStagedDiff(cwd));
+
+  let settings = resolveSettings(loadConfig());
+  if (!hasUsableKey(settings)) {
+    printSetupBlock();
+    if (!isTTY()) {
+      throw new CliError(
+        "Non-interactive stdin: set YF_COMMIT_API_KEY or run yf-commit init in a terminal.",
+      );
+    }
+    const ok = await offerInitNow();
+    if (!ok) {
+      throw new CliError("No API key. Run yf-commit init or export YF_COMMIT_API_KEY.");
+    }
+    settings = resolveSettings(loadConfig());
+    if (!hasUsableKey(settings)) {
+      throw new CliError("No API key. Run yf-commit init or export YF_COMMIT_API_KEY.");
+    }
+  }
+
+  const message = await completeChat({
+    baseUrl: settings.baseUrl,
+    model: settings.resolvedModel,
+    apiKey: settings.apiKey || "ollama",
+    systemPrompt: buildSystemPrompt({ forcedType: args.type }),
+    userPrompt: buildUserPrompt(diff),
+  });
+
+  if (args.print) {
+    console.log(message);
+    return 0;
+  }
+
+  console.log(message);
+
+  if (!args.auto) {
+    if (!isTTY()) {
+      throw new CliError(
+        "Non-interactive stdin: pass --auto / -y to commit, or --print to only print.",
+      );
+    }
+    const yes = await confirmCommit();
+    if (!yes) {
+      throw new CliError("Cancelled.");
+    }
+  }
+
+  commitWithMessage(cwd, message);
+  return 0;
+}
+
+async function confirmCommit() {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question(
+      "\nCommit this message? Press Enter or y to commit, n to cancel: ",
+    );
+    const t = answer.trim().toLowerCase();
+    return t === "" || t === "y" || t === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+export function run(argv) {
+  main(argv)
+    .then((code) => {
+      process.exit(typeof code === "number" ? code : 0);
+    })
+    .catch((err) => {
+      const message = err instanceof CliError ? err.message : err.message || String(err);
+      console.error(message);
+      process.exit(err instanceof CliError ? err.exitCode : 1);
+    });
+}

package/src/init.js

@@ -0,0 +1,126 @@
+import * as p from "@clack/prompts";
+import { CliError } from "./errors.js";
+import {
+  configPath,
+  deleteConfig,
+  loadConfig,
+  maskKey,
+  saveConfig,
+} from "./config.js";
+import { PROVIDERS, providerById } from "./providers.js";
+
+export function printSetupBlock() {
+  console.error(`This tool needs an OpenAI-compatible API key (OpenAI, DeepSeek, xAI, Groq, Ollama).
+Create a key at the provider; YourFam does not issue keys.
+
+Then either:
+  yf-commit init
+  export YF_COMMIT_API_KEY=...
+`);
+}
+
+export function isTTY() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+export async function runInitCommand({ show, reset }) {
+  if (reset) {
+    const removed = deleteConfig();
+    if (removed) console.error(`Deleted ${configPath()}`);
+    else console.error("No config file to delete.");
+    return 0;
+  }
+  if (show) {
+    showStatus();
+    return 0;
+  }
+  if (!isTTY()) {
+    printSetupBlock();
+    throw new CliError("Non-interactive stdin: set YF_COMMIT_API_KEY or run yf-commit init in a terminal.");
+  }
+  await runWizard();
+  return 0;
+}
+
+export function showStatus() {
+  const file = loadConfig();
+  if (!file) {
+    console.error("No config at " + configPath());
+    console.error("Run yf-commit init or set YF_COMMIT_API_KEY.");
+    return;
+  }
+  console.error(`provider: ${file.provider || "(none)"}`);
+  console.error(`model:    ${file.model || "(none)"}`);
+  console.error(`baseUrl:  ${file.baseUrl || "(none)"}`);
+  console.error(`apiKey:   ${maskKey(file.apiKey || "")}`);
+  console.error(`file:     ${configPath()}`);
+}
+
+export async function offerInitNow() {
+  const yes = await p.confirm({
+    message: "Set up now (provider, model, key)?",
+    initialValue: true,
+  });
+  if (p.isCancel(yes) || !yes) {
+    p.cancel("Setup skipped.");
+    return false;
+  }
+  await runWizard();
+  return true;
+}
+
+export async function runWizard() {
+  p.intro("yf-commit setup");
+
+  const providerId = await p.select({
+    message: "Provider",
+    initialValue: "openai",
+    options: PROVIDERS.map((prov) => ({
+      value: prov.id,
+      label: prov.label,
+    })),
+  });
+  if (p.isCancel(providerId)) {
+    p.cancel("Setup cancelled.");
+    throw new CliError("Setup cancelled.", 1);
+  }
+
+  const provider = providerById(providerId);
+  const model = await p.select({
+    message: "Model",
+    initialValue: "auto",
+    options: [
+      { value: "auto", label: "Auto (recommended)" },
+      ...provider.models.map((id) => ({ value: id, label: id })),
+    ],
+  });
+  if (p.isCancel(model)) {
+    p.cancel("Setup cancelled.");
+    throw new CliError("Setup cancelled.", 1);
+  }
+
+  /** @type {string | undefined} */
+  let apiKey;
+  if (providerId !== "ollama") {
+    const pasted = await p.password({
+      message: "API key",
+      validate(value) {
+        if (!value || !String(value).trim()) return "Paste a non-empty key.";
+      },
+    });
+    if (p.isCancel(pasted)) {
+      p.cancel("Setup cancelled.");
+      throw new CliError("Setup cancelled.", 1);
+    }
+    apiKey = String(pasted).trim();
+  }
+
+  const data = {
+    provider: providerId,
+    baseUrl: provider.baseUrl,
+    model,
+  };
+  if (apiKey) data.apiKey = apiKey;
+  saveConfig(data);
+  p.outro(`Saved to ${configPath()}`);
+}

package/src/llm.js

@@ -0,0 +1,77 @@
+import { CliError } from "./errors.js";
+import { cleanMessage } from "./prompt.js";
+
+/**
+ * @param {object} opts
+ * @param {string} opts.baseUrl
+ * @param {string} opts.model
+ * @param {string} opts.apiKey
+ * @param {string} opts.systemPrompt
+ * @param {string} opts.userPrompt
+ */
+export async function completeChat({
+  baseUrl,
+  model,
+  apiKey,
+  systemPrompt,
+  userPrompt,
+}) {
+  const root = String(baseUrl || "").replace(/\/+$/, "");
+  const url = `${root}/chat/completions`;
+  const headers = {
+    "content-type": "application/json",
+  };
+  if (apiKey) headers.authorization = `Bearer ${apiKey}`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 60_000);
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        model,
+        temperature: 0.3,
+        max_tokens: 1500,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt },
+        ],
+      }),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    if (err && err.name === "AbortError") {
+      throw new CliError("The model request timed out.");
+    }
+    throw new CliError(`Could not reach ${root}: ${err.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const raw = await res.text();
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    data = null;
+  }
+
+  if (!res.ok) {
+    const msg =
+      data?.error?.message ||
+      data?.message ||
+      raw.slice(0, 400) ||
+      res.statusText;
+    throw new CliError(`API error ${res.status}: ${msg}`);
+  }
+
+  const content = data?.choices?.[0]?.message?.content;
+  const message = cleanMessage(content);
+  if (!message) {
+    throw new CliError("The model returned an empty commit message.");
+  }
+  return message;
+}

package/src/prompt.js

@@ -0,0 +1,61 @@
+import { TYPE_EMOJI } from "./types.js";
+
+const MAX_DIFF_CHARS = 100_000;
+
+export function buildSystemPrompt({ forcedType } = {}) {
+  const typeLine = forcedType
+    ? `You MUST use type "${forcedType}" and emoji ${TYPE_EMOJI[forcedType]} on line 1.`
+    : "Use conventional commit types: feat, fix, refactor, chore, docs, test.";
+
+  return `You are a commit message generator. Output only the commit message. No preamble, no markdown fences, no extra commentary.
+
+Follow this exact format:
+
+emoji type(scope): brief description
+
+💡 WHY:
+- …
+
+🔧 WHAT CHANGED:
+- …
+
+📁 FILES IMPACTED:
+- path/relative/to/this/repo
+
+Rules:
+- ${typeLine}
+- Emoji on line 1 (✨ feat, 🐛 fix, ♻️ refactor, 🔧 chore, 📝 docs, 🧪 test).
+- First line under 72 characters.
+- WHY: user/business impact, plain language.
+- WHAT CHANGED: technical, from the diff, not staging stats.
+- FILES IMPACTED: paths relative to this repository's root (the current working directory).
+- Adaptive length: tiny diffs → few bullets; large diffs → more, grouped if needed. Never pad. Never write "Updated N staged file(s)."
+- No footer. Do not add WORKTREE, BRANCH, MACHINE, or hostname lines.
+- Do not mention any product or company unless it appears in the diff.`;
+}
+
+export function buildUserPrompt(diff) {
+  let body = String(diff);
+  if (body.length > MAX_DIFF_CHARS) {
+    body = `${body.slice(0, MAX_DIFF_CHARS)}\n\n[diff truncated]`;
+  }
+  return `Generate a commit message for this staged git diff:\n\n${body}`;
+}
+
+export function cleanMessage(text) {
+  let t = String(text || "").trim();
+  if (!t) return "";
+  if (t.startsWith("```")) {
+    t = t.replace(/^```[a-zA-Z]*\r?\n?/, "").replace(/\r?\n?```$/, "").trim();
+  }
+  t = t.replace(/\n(?:WORKTREE|BRANCH|MACHINE)\b.*$/gim, "").trim();
+  return t;
+}
+
+export function looksLikeLockedFormat(message) {
+  return (
+    /💡 WHY:/m.test(message) &&
+    /🔧 WHAT CHANGED:/m.test(message) &&
+    /📁 FILES IMPACTED:/m.test(message)
+  );
+}

package/src/providers.js

@@ -0,0 +1,81 @@
+/** Locked V1 provider table. Bump auto + named lists in patch releases. */
+
+export const PROVIDERS = [
+  {
+    id: "openai",
+    label: "OpenAI",
+    baseUrl: "https://api.openai.com/v1",
+    autoModel: "gpt-4o-mini",
+    models: ["gpt-4o-mini", "gpt-4o"],
+  },
+  {
+    id: "deepseek",
+    label: "DeepSeek",
+    baseUrl: "https://api.deepseek.com/v1",
+    autoModel: "deepseek-chat",
+    models: ["deepseek-chat"],
+  },
+  {
+    id: "xai",
+    label: "xAI (Grok)",
+    baseUrl: "https://api.x.ai/v1",
+    autoModel: "grok-4-fast-non-reasoning",
+    models: ["grok-4-fast-non-reasoning", "grok-4"],
+  },
+  {
+    id: "groq",
+    label: "Groq",
+    baseUrl: "https://api.groq.com/openai/v1",
+    autoModel: "llama-3.3-70b-versatile",
+    models: ["llama-3.3-70b-versatile"],
+  },
+  {
+    id: "ollama",
+    label: "Ollama (local)",
+    baseUrl: "http://127.0.0.1:11434/v1",
+    autoModel: "llama3.2",
+    models: ["llama3.2"],
+  },
+];
+
+export const DEFAULT_PROVIDER_ID = "openai";
+
+/**
+ * @param {string} id
+ */
+export function providerById(id) {
+  return PROVIDERS.find((p) => p.id === id) ?? null;
+}
+
+/**
+ * @param {string} baseUrl
+ */
+export function providerByBaseUrl(baseUrl) {
+  const normalized = String(baseUrl || "").replace(/\/+$/, "");
+  return (
+    PROVIDERS.find(
+      (p) => p.baseUrl.replace(/\/+$/, "") === normalized,
+    ) ?? null
+  );
+}
+
+/**
+ * @param {string} providerId
+ * @param {string} [baseUrl]
+ */
+export function resolveAutoModel(providerId, baseUrl) {
+  const p =
+    providerById(providerId) ||
+    providerByBaseUrl(baseUrl || "") ||
+    providerById(DEFAULT_PROVIDER_ID);
+  return p.autoModel;
+}
+
+/**
+ * @param {string} providerId
+ * @param {string} baseUrl
+ */
+export function isOllama(providerId, baseUrl) {
+  if (providerId === "ollama") return true;
+  return /11434/.test(String(baseUrl || ""));
+}

package/src/types.js

@@ -0,0 +1,27 @@
+import { CliError } from "./errors.js";
+
+/** Alphabetical 1–6 map: chore, docs, feat, fix, refactor, test */
+export const TYPES = ["chore", "docs", "feat", "fix", "refactor", "test"];
+
+export const TYPE_EMOJI = {
+  feat: "✨",
+  fix: "🐛",
+  refactor: "♻️",
+  chore: "🔧",
+  docs: "📝",
+  test: "🧪",
+};
+
+/**
+ * @param {string | null | undefined} raw
+ * @returns {string | null}
+ */
+export function parseType(raw) {
+  if (raw == null || raw === "") return null;
+  const s = String(raw).trim().toLowerCase();
+  if (/^[1-6]$/.test(s)) return TYPES[Number(s) - 1];
+  if (TYPES.includes(s)) return s;
+  throw new CliError(
+    `Unknown type "${raw}". Use feat, fix, refactor, chore, docs, test, or 1–6.`,
+  );
+}