@yourfam/yf-commit 0.1.0 → 0.1.1

package/README.md

@@ -2,98 +2,164 @@
 
 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`. After a **global** install, npm prints a short hint (`yf-commit installed…`). That does not run for `-D`, CI, or `npx`.
 
-## First run / `yf-commit init`
+## Alternate modes of install
 
-The first `yf-commit` with no key **is** setup (same idea as `gh auth login`).
+**-g** = on **your machine** (global).  
+**-D** = in **this project** (devDependency).
 
-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.
+| | `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 |
 
-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.
+For `yf-commit` as a daily command, use **-g**. Use **-D** only if this one repo should own the tool.
+
+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
 ```
 
-Primary env var: **`YF_COMMIT_API_KEY`**. You can also:
+A `package.json` script also works, because npm puts `node_modules/.bin` on PATH **for the script**:
+
+```json
+"scripts": {
+  "commit": "yf-commit"
+}
+```
 
 ```bash
-export YF_COMMIT_API_KEY=...
+npm run commit
 ```
 
-`OPENAI_API_KEY` is also accepted if the others are unset.
+Plain `yf-commit` anywhere on the machine is only after **-g**.
+
+No install at all (npm fetches and runs the published package):
 
-Need a host we don't list? Set `YF_COMMIT_BASE_URL` and `YF_COMMIT_MODEL`.
+```bash
+npx @yourfam/yf-commit
+```
 
-| Env | Config key | Default |
+## 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.
+
+Saved to `~/.yf-commit/config.json` (Windows: `%USERPROFILE%\.yf-commit\config.json`). Never commit that file.
+
+```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**
+
+```bash
+git add path/to/file
+yf-commit              # print draft → confirm → git commit
+yf-commit -y           # same, skip confirm (also --yes, --auto)
+```
 
-## Usage
+**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 --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.
+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,6 +1,6 @@
 {
   "name": "@yourfam/yf-commit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AI commit message from your staged git diff",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "node": ">=20"
   },
   "scripts": {
+    "postinstall": "node ./src/postinstall-run.js",
     "test": "node --test test/*.test.js",
     "yf-commit": "node ./bin/yf-commit.js"
   },
@@ -25,7 +26,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/postinstall-run.js

@@ -0,0 +1,7 @@
+import { runPostinstall } from "./postinstall.js";
+
+try {
+  runPostinstall();
+} catch {
+  // Never fail install.
+}

package/src/postinstall.js

@@ -0,0 +1,22 @@
+/**
+ * Print a short hint after `npm install -g` only.
+ * Stay silent for -D, CI, npx, and repo `npm install`.
+ */
+export function isGlobalNpmInstall(env = process.env) {
+  return env.npm_config_global === "true";
+}
+
+export function installHint() {
+  return `yf-commit installed. Run: yf-commit
+First time: provider → model → API key
+Docs: https://github.com/YourFam/yf-commit`;
+}
+
+export function runPostinstall(
+  env = process.env,
+  write = (s) => process.stderr.write(s),
+) {
+  if (!isGlobalNpmInstall(env)) return false;
+  write(`${installHint()}\n`);
+  return true;
+}