npm package: @msi-credit-solutions/llm-info-cli
Description: > Command‑line utilities **and** a VS Code extension for the   > **LLM‑Info mark‑up spec** – think ESLint + Quick Fixes for annotating code so > large‑language‑models can reason about it.
Latest version: 1.2.3

# LLM‑Info Toolkit <img height="20" src="https://img.shields.io/badge/LLM--Info-v1.2-blue" />

> Command‑line utilities **and** a VS Code extension for the  
> **LLM‑Info mark‑up spec** – think ESLint + Quick Fixes for annotating code so
> large‑language‑models can reason about it.

```text
llm-info-cli/
├─ bin/                       ← runtime entry‑points (llm‑archive / extract / validate)
├─ extension/                 ← VS Code validator + Quick‑Fixes
│   ├─ src/                   ← TypeScript sources
│   ├─ dist/                  ← compiled JS (ignored)
│   └─ bin/                   ← same CLI scripts (linked at publish)
├─ docs/                      ← team / release guides
├─ scripts/                   ← package‑VSIX helper
├─ CHANGELOG.md
└─ README.md                  ← you are here
````

---

## ✨ CLI Features

| Command        | What it does                                                                                             | Typical use‑case                           |
| -------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `llm-archive`  | Concatenate all files under `--root` into a plain‑text archive.<br>`--meta-only` keeps just header lines | Feed slices into embedding / RAG pipelines |
| `llm-extract`  | Parse `// LLM:` headers + first `@purpose` and all `@action / @state` tags → emits **JSONL**             | Build a searchable catalogue / dashboards  |
| `llm-validate` | Lint for missing headers/tags; `--fix` auto‑inserts `version=1.2` and a `@purpose TBD` stub              | CI gate to keep the markup consistent      |

*Runtime deps: **only `fast-glob`** (Node ≥ 16).*

---

## ✨ VS Code Extension

| Feature               | Details                                                                    |
| --------------------- | -------------------------------------------------------------------------- |
| Real‑time diagnostics | Executes `llm‑validate` on open/save and shows bullets in Problems         |
| Quick Fixes 💡        | *Insert header stub* • *Insert @purpose stub*                              |
| Demo codemod command  | **LLM‑Info ▸ Run Demo Codemod** (rewrites `console.log` → `console.debug`) |
| Zero extra deps       | Falls back to regex if `typescript` module is absent                       |

See **[`extension/README_VSCODE.md`](extension/README_VSCODE.md)** for dev docs.

---

## 🛠 Installation

```bash
# one‑off usage
npx @msi-credit-solutions/llm-info-cli llm-validate "src/**/*.{ts,js}"

# or add to your dev‑deps (recommended)
npm install --save-dev @msi-credit-solutions/llm-info-cli@^1.2.2
```

> Installing the package gives you **both** the CLI binaries (globally runnable
> via `npx` or `npm run`) **and** the VS Code extension (auto‑updates through the
> Marketplace).

---

## 🚀 Quick Start

```bash
# Dump header lines for one slice
llm-archive --root src/features/pdf --meta-only > llm-meta.txt

# Validate whole repo & auto‑fix missing stubs
llm-validate --fix "src/**/*.{ts,tsx,js}"

# Extract JSONL catalogue for RAG pipelines
llm-extract --root packages/server/src > llm-extract.jsonl

# Local VSIX build / install
npm run build            # compiles extension
npm run vsce:package     # creates *.vsix
code --install-extension extension/*.vsix --force
```

---

## 🔍 Spec Versioning

Every header carries a `version=` key.
Current toolkit supports **v1.2**. Future breaking changes bump the CLI major
semver; older versions remain readable.

---

## 👤 Authors

| Name              | Role                               | Company              |
| ----------------- | ---------------------------------- | -------------------- |
| **Blixa Markham** | Lead Developer / Software Engineer | MSI Credit Solutions |

---

## 📄 License

MIT © 2025‑2026 **MSI Credit Solutions Inc.**

---

## 🤝 Contributing

1. Fork & branch off **`main`**
2. `npm ci && npm run build`
3. Submit a PR – include before/after examples for parser changes