@yourfam/yf-commit 0.1.0 → 0.2.0

package/README.md

@@ -2,98 +2,182 @@
 
 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.
+Writes `emoji type(scope): …` plus WHY, WHAT CHANGED, and FILES IMPACTED. Does **not** run your test suite. Does **not** append worktree / branch / machine trailers.
 
 YourFam does not give you an API key. Use your own OpenAI-compatible key.
 
+- **Source / README:** https://github.com/YourFam/yf-commit
+- **npm:** https://www.npmjs.com/package/@yourfam/yf-commit
+- **Issues:** https://github.com/YourFam/yf-commit/issues
+
 ## Install
 
-Node 20+. Friend one-liner:
+Node 20+.
 
 ```bash
-npx @yourfam/yf-commit
+npm install -g @yourfam/yf-commit
 ```
 
-Or install once:
+Then from any git repo:
 
 ```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).
+The command is `yf-commit`.
+
+## Alternate modes of install
 
-## First run / `yf-commit init`
+**-g** = on **your machine** (global).  
+**-D** = in **this project** (devDependency).
 
-The first `yf-commit` with no key **is** setup (same idea as `gh auth login`).
+| | `npm install -g @yourfam/yf-commit` | `npm install -D @yourfam/yf-commit` |
+|---|---|---|
+| Where it goes | Global npm prefix (your user/system) | `node_modules/` + `package.json` of the current repo |
+| Command | `yf-commit` from any folder | `npx yf-commit` (or a script) **in that repo** |
+| Other repos | Works | Not installed there |
+| Git | Not committed | Listed in `package.json`; teammates get it with `npm install` |
+| Typical use | A CLI you want everywhere | A tool this project uses in scripts/CI |
 
-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.
+For `yf-commit` as a daily command, use **-g**. Use **-D** only if this one repo should own the tool.
 
-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.
+With **-D**, the binary lives in that repo’s `node_modules/.bin/`. Your shell PATH does not include that, so **plain `yf-commit` will not work**. From that repo:
 
 ```bash
-yf-commit init         # wizard
-yf-commit init --show  # provider, model, base URL, masked key
-yf-commit init --reset # delete saved config
+npx yf-commit
+```
+
+A `package.json` script also works, because npm puts `node_modules/.bin` on PATH **for the script**:
+
+```json
+"scripts": {
+  "commit": "yf-commit"
+}
+```
+
+```bash
+npm run commit
 ```
 
-Primary env var: **`YF_COMMIT_API_KEY`**. You can also:
+Plain `yf-commit` anywhere on the machine is only after **-g**.
+
+No install at all (npm fetches and runs the published package):
 
 ```bash
-export YF_COMMIT_API_KEY=...
+npx @yourfam/yf-commit
 ```
 
-`OPENAI_API_KEY` is also accepted if the others are unset.
+## First run
+
+The first `yf-commit` with no key is setup.
+
+1. Provider: OpenAI, DeepSeek, xAI (Grok), Groq, or Ollama (local).
+2. Model: **Auto (recommended)**, or a named model.
+3. API key (hidden). Skipped for Ollama.
 
-Need a host we don't list? Set `YF_COMMIT_BASE_URL` and `YF_COMMIT_MODEL`.
+Saved to `~/.yf-commit/config.json` (Windows: `%USERPROFILE%\.yf-commit\config.json`). Never commit that file.
 
-| Env | Config key | Default |
+```bash
+yf-commit init         # wizard
+yf-commit init --show  # masked status
+yf-commit init --reset # delete config
+```
+
+Or set **`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 | 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 |
+| `YF_COMMIT_MODEL` | `model` | `auto` |
+
+## Use
+
+Flags combine. Typical paths:
+
+**You stage, then generate**
 
-## Usage
+```bash
+git add path/to/file
+yf-commit              # print draft → confirm → git commit
+yf-commit -y           # same, skip confirm (also --yes, --auto)
+```
+
+**Skip staging — let yf-commit `git add -A`**
 
-Stage files, then:
+`--all` runs `git add -A` first (tracked changes and untracked files, except ignored), then the same as above.
 
 ```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 --all        # add everything → print draft → confirm → commit
+yf-commit --all -y     # add everything → commit now (no confirm)
+```
+
+**Other flags (mix with `--all` / `-y` as needed)**
+
+```bash
+yf-commit --print      # print only; do not commit (still needs a staged diff, or add --all)
+yf-commit --all --print
 yf-commit --type fix   # force type
-yf-commit --type 4     # same (1–6: chore, docs, feat, fix, refactor, test)
+yf-commit --type 4     # same (1–11)
+yf-commit --all -y --type feat
 ```
 
-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.
+The JS does not classify the **type**. It does measure **size** (insertions + deletions, plus file count) and tells the model a length budget: tiny diffs get exactly 1 WHY + 1 WHAT; large diffs get more WHAT, grouped. WHY does not grow with every extra hundred lines. Mixed diffs still get **one** dominant type (`feat` / `fix` usually). Override with `--type`. Default still prints the draft so you can cancel.
+
+| # | Type | Meaning |
+|---|---|---|
+| 1 | `chore` | Maintenance that is none of the below |
+| 2 | `docs` | Docs only |
+| 3 | `feat` | User-visible new capability |
+| 4 | `fix` | User-visible bug |
+| 5 | `refactor` | Same behavior, different structure |
+| 6 | `test` | Tests only |
+| 7 | `build` | Compile, bundler, packaging |
+| 8 | `ci` | Pipeline / GitHub Actions / hooks |
+| 9 | `perf` | Same behavior, measurably faster |
+| 10 | `style` | Formatting only, zero logic |
+| 11 | `revert` | Undoes a previous commit |
+
+Priority on mixed diffs: `revert` → `fix` → `feat` → `test` → `docs` → `perf` → `refactor` → `style` → `ci` → `build` → `chore`.
+
+Default prints the draft in the terminal. 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`.
+Nothing staged → error, exit 1. No `git add` unless `--all`.
 
-Non-interactive (CI / scripts): pass `--print` or `-y`. It will not hang waiting for a paste or a confirm.
+Scripts / CI: `--print` or `-y`. It will not wait for a paste or a confirm.
 
-## Message format
+## Format
 
 ```
 ✨ feat(cli): add --print to skip git commit
 
 💡 WHY:
-- Friends can preview a message without committing
+- Preview a message without committing
 
 🔧 WHAT CHANGED:
-- Added a --print flag that writes the draft to stdout and exits
+- --print writes the draft to stdout and exits
 
 📁 FILES IMPACTED:
 - src/index.js
 - README.md
 ```
 
+## Development
+
+This is the GitHub repo, not a second package. Docs and source live here; `npx` / `npm install` still install whatever version is **published on npm**.
+
+```bash
+git clone https://github.com/YourFam/yf-commit.git
+cd yf-commit
+npm install
+npm test
+node ./bin/yf-commit.js --help
+```
+
+Maintainer: YourFam (`kamal-yourfam` on npm). License MIT.
+
 ## License
 
 MIT

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@yourfam/yf-commit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AI commit message from your staged git diff",
   "type": "module",
   "bin": {
-    "yf-commit": "./bin/yf-commit.js"
+    "yf-commit": "bin/yf-commit.js"
   },
   "files": [
     "bin",
@@ -25,7 +25,11 @@
     "conventional-commits",
     "cli"
   ],
-  "author": "YourFam",
+  "author": {
+    "name": "YourFam",
+    "email": "kamal@yourfam.co",
+    "url": "https://github.com/YourFam"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/args.js

@@ -1,5 +1,5 @@
 import { CliError } from "./errors.js";
-import { parseType } from "./types.js";
+import { parseType, typeHelpLines } from "./types.js";
 
 /**
  * @typedef {object} ParsedArgs
@@ -58,7 +58,7 @@ export function parseArgs(argv) {
     } 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.");
+        throw new CliError("Flag --type requires a value: feat|fix|… or 1–11.");
       }
       result.type = parseType(value);
       i += 1;
@@ -96,11 +96,14 @@ Usage:
   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 --type fix   Force type (name or 1–11)
   yf-commit init         Provider, model, API key → ~/.yf-commit/config.json
   yf-commit init --show  Masked status
   yf-commit init --reset Delete saved config
 
+Types (mixed diffs: one dominant type, not a blend):
+${typeHelpLines()}
+
 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/diff-profile.js

@@ -0,0 +1,114 @@
+const ORDER = ["tiny", "small", "medium", "large", "xl"];
+
+export const PROFILES = {
+  tiny: {
+    id: "tiny",
+    why: "exactly 1 bullet",
+    what: "exactly 1 bullet",
+    groupWhat: false,
+    maxTokens: 400,
+  },
+  small: {
+    id: "small",
+    why: "1–2 bullets",
+    what: "2–3 bullets",
+    groupWhat: false,
+    maxTokens: 700,
+  },
+  medium: {
+    id: "medium",
+    why: "2–3 bullets",
+    what: "4–6 bullets",
+    groupWhat: false,
+    maxTokens: 1200,
+  },
+  large: {
+    id: "large",
+    why: "2–3 bullets",
+    what: "6–10 bullets, grouped by area if needed",
+    groupWhat: true,
+    maxTokens: 1800,
+  },
+  xl: {
+    id: "xl",
+    why: "2–4 bullets (do not grow WHY with every file)",
+    what: "8–14 bullets, grouped by area",
+    groupWhat: true,
+    maxTokens: 2500,
+  },
+};
+
+/**
+ * Count changed lines (+ and −, excluding +++ / --- headers) and files.
+ * @param {string} diff
+ */
+export function countDiff(diff) {
+  const lines = String(diff).split(/\r?\n/);
+  let loc = 0;
+  const files = new Set();
+
+  for (const line of lines) {
+    if (line.startsWith("diff --git ")) {
+      const m = line.match(/^diff --git a\/(.+) b\/(.+)$/);
+      if (m) {
+        const path = m[2] === "/dev/null" ? m[1] : m[2];
+        files.add(path.replace(/^"|"$/g, ""));
+      }
+      continue;
+    }
+    if (line.startsWith("Binary files ")) {
+      loc += 1;
+      continue;
+    }
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      loc += 1;
+      continue;
+    }
+    if (line.startsWith("-") && !line.startsWith("---")) {
+      loc += 1;
+    }
+  }
+
+  return { loc, files: files.size };
+}
+
+function profileIdFromLoc(loc) {
+  if (loc <= 20) return "tiny";
+  if (loc <= 80) return "small";
+  if (loc <= 300) return "medium";
+  if (loc <= 800) return "large";
+  return "xl";
+}
+
+function applyFileFloor(id, fileCount) {
+  let i = ORDER.indexOf(id);
+  if (fileCount >= 8) i = Math.max(i, ORDER.indexOf("small"));
+  if (fileCount >= 20) i = Math.max(i, ORDER.indexOf("medium"));
+  return ORDER[i];
+}
+
+/**
+ * @param {string} diff
+ */
+export function diffProfile(diff) {
+  const { loc, files } = countDiff(diff);
+  const id = applyFileFloor(profileIdFromLoc(loc), files);
+  const spec = PROFILES[id];
+  return { ...spec, loc, files };
+}
+
+/**
+ * @param {ReturnType<typeof diffProfile>} profile
+ */
+export function lengthInstruction(profile) {
+  const fileNote =
+    profile.files >= 8
+      ? "FILES IMPACTED: list real paths; group under area headings if that helps. Never write \"Updated N files.\""
+      : "FILES IMPACTED: list each real path. Never write \"Updated N files.\"";
+
+  return `Diff size: ${profile.loc} line(s), ${profile.files} file(s). Profile: ${profile.id}.
+WHY: ${profile.why}. Reasons only — do not recap every file.
+WHAT CHANGED: ${profile.what}.
+${fileNote}
+Do not add extra bullets to look complete. Do not pad.`;
+}

package/src/index.js

@@ -24,6 +24,7 @@ import { completeChat } from "./llm.js";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { diffProfile, lengthInstruction } from "./diff-profile.js";
 import { buildSystemPrompt, buildUserPrompt } from "./prompt.js";
 
 const pkg = JSON.parse(
@@ -74,12 +75,14 @@ export async function main(argv) {
     }
   }
 
+  const profile = diffProfile(diff);
   const message = await completeChat({
     baseUrl: settings.baseUrl,
     model: settings.resolvedModel,
     apiKey: settings.apiKey || "ollama",
     systemPrompt: buildSystemPrompt({ forcedType: args.type }),
-    userPrompt: buildUserPrompt(diff),
+    userPrompt: buildUserPrompt(diff, lengthInstruction(profile)),
+    maxTokens: profile.maxTokens,
   });
 
   if (args.print) {

package/src/llm.js

@@ -15,6 +15,7 @@ export async function completeChat({
   apiKey,
   systemPrompt,
   userPrompt,
+  maxTokens = 1500,
 }) {
   const root = String(baseUrl || "").replace(/\/+$/, "");
   const url = `${root}/chat/completions`;
@@ -34,7 +35,7 @@ export async function completeChat({
       body: JSON.stringify({
         model,
         temperature: 0.3,
-        max_tokens: 1500,
+        max_tokens: maxTokens,
         messages: [
           { role: "system", content: systemPrompt },
           { role: "user", content: userPrompt },

package/src/prompt.js

@@ -1,11 +1,20 @@
-import { TYPE_EMOJI } from "./types.js";
+import {
+  TYPE_DEFS,
+  TYPE_EMOJI,
+  TYPE_PRIORITY,
+  TYPES,
+} from "./types.js";
 
 const MAX_DIFF_CHARS = 100_000;
 
+const EMOJI_LINE = TYPES.map((t) => `${TYPE_EMOJI[t]} ${t}`).join(", ");
+
+const DEF_LINES = TYPES.map((t) => `- ${t}: ${TYPE_DEFS[t]}`).join("\n");
+
 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.";
+    : `Use exactly one conventional commit type: ${TYPES.join(", ")}.`;
 
   return `You are a commit message generator. Output only the commit message. No preamble, no markdown fences, no extra commentary.
 
@@ -24,22 +33,26 @@ emoji type(scope): brief description
 
 Rules:
 - ${typeLine}
-- Emoji on line 1 (✨ feat, 🐛 fix, ♻️ refactor, 🔧 chore, 📝 docs, 🧪 test).
+- Type meanings:
+${DEF_LINES}
+- ${TYPE_PRIORITY}
+- Emoji on line 1 (${EMOJI_LINE}).
 - 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)."
+- Obey the length profile in the user message (bullet counts for WHY / WHAT). 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) {
+export function buildUserPrompt(diff, lengthBlock = "") {
   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}`;
+  const prefix = lengthBlock ? `${lengthBlock}\n\n` : "";
+  return `${prefix}Generate a commit message for this staged git diff:\n\n${body}`;
 }
 
 export function cleanMessage(text) {

package/src/types.js

@@ -1,7 +1,22 @@
 import { CliError } from "./errors.js";
 
-/** Alphabetical 1–6 map: chore, docs, feat, fix, refactor, test */
-export const TYPES = ["chore", "docs", "feat", "fix", "refactor", "test"];
+/**
+ * 1–6 stay stable (chore, docs, feat, fix, refactor, test).
+ * 7–11 are the extra conventional types.
+ */
+export const TYPES = [
+  "chore",
+  "docs",
+  "feat",
+  "fix",
+  "refactor",
+  "test",
+  "build",
+  "ci",
+  "perf",
+  "style",
+  "revert",
+];
 
 export const TYPE_EMOJI = {
   feat: "✨",
@@ -10,8 +25,42 @@ export const TYPE_EMOJI = {
   chore: "🔧",
   docs: "📝",
   test: "🧪",
+  build: "📦",
+  ci: "👷",
+  perf: "⚡",
+  style: "🎨",
+  revert: "⏪",
+};
+
+export const TYPE_DEFS = {
+  feat: "User-visible new capability",
+  fix: "User-visible bug",
+  docs: "Documentation only, no product code",
+  test: "Tests only",
+  revert: "Undoes a previous commit",
+  perf: "Same behavior, measurably faster",
+  refactor: "Same behavior, different structure",
+  style: "Formatting only, zero logic",
+  ci: "Pipeline / GitHub Actions / hooks only",
+  build: "Compile, bundler, packaging only",
+  chore: "Maintenance that is none of the above",
 };
 
+/** Mixed diffs: one primary type, not a blend. */
+export const TYPE_PRIORITY = `Pick exactly one type for the whole commit. Mixed diffs are normal — choose the dominant type, in this order:
+1. revert — the change undoes a previous commit
+2. fix — any user-visible bug
+3. feat — any user-visible new capability (tests/docs/formatting in the same diff stay feat)
+4. test — tests only
+5. docs — docs only
+6. perf — same feature, measurably faster (not a bugfix)
+7. refactor — same behavior, different structure (not formatting-only)
+8. style — formatting / lint only, zero logic
+9. ci — CI / GitHub Actions / hooks only
+10. build — compile, bundler, native addons, packaging only
+11. chore — everything else (deps, ignore files, version bump with no product change)
+Do not invent extra types. Do not combine types.`;
+
 /**
  * @param {string | null | undefined} raw
  * @returns {string | null}
@@ -19,9 +68,19 @@ export const TYPE_EMOJI = {
 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 (/^\d+$/.test(s)) {
+    const n = Number(s);
+    if (n >= 1 && n <= TYPES.length) return TYPES[n - 1];
+  }
   if (TYPES.includes(s)) return s;
   throw new CliError(
-    `Unknown type "${raw}". Use feat, fix, refactor, chore, docs, test, or 1–6.`,
+    `Unknown type "${raw}". Use ${TYPES.join(", ")}, or 1–${TYPES.length}.`,
   );
 }
+
+export function typeHelpLines() {
+  return TYPES.map((name, i) => {
+    const n = i + 1;
+    return `  ${n}. ${TYPE_EMOJI[name]} ${name} — ${TYPE_DEFS[name]}`;
+  }).join("\n");
+}