@djolex999/vir-cli 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djolex999/vir-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Distills Claude Code sessions into a compounding knowledge vault",
   "author": "Djordje Marković <djordje@growthq.rs>",
   "license": "MIT",
@@ -24,6 +24,12 @@
   "bin": {
     "vir": "dist/cli.js"
   },
+  "files": [
+    "dist",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",

package/AGENTS.md

@@ -1,201 +0,0 @@
-# vir
-
-Local macOS daemon that distills Codex session transcripts into an
-Obsidian vault.
-
-Published to npm as `@djolex999/vir-cli` (scoped). Install:
-`npm install -g @djolex999/vir-cli`. Repo: https://github.com/djolex999/vir. Reads `~/.Codex/projects/**/*.jsonl`, filters by heuristic,
-classifies with Haiku, extracts durable knowledge with Sonnet, writes typed
-notes to the vault, maintains an index, and syncs back into AGENTS.md files.
-
-## Stack
-
-- Node.js ≥ 20, TypeScript strict (`noImplicitAny`, `noUncheckedIndexedAccess`)
-- `commander` for CLI, `chalk` for output, `zod` for config validation
-- `better-sqlite3` for state (synchronous — no async complexity)
-- `@anthropic-ai/sdk` for the Anthropic path; native `fetch` for the Kie path
-- macOS `launchd` for the daemon, `osascript` for notifications
-- `vitest` for unit tests (`npm test` → `vitest run`)
-
-## Structure
-
-```
-src/
-  cli.ts              # commander entry — every subcommand wired here
-  config.ts           # ~/.vir/config.json schema + helpers
-  pipeline/
-    run.ts            # orchestrator (scan → filter → scrub → distill → write)
-    scanner.ts        # walk ~/.Codex/projects, SHA-256 each .jsonl
-    parser.ts         # extract assistant/user text, tool calls, files touched
-    filter.ts         # heuristic scorer (length, tools, files, signal words)
-    scrubber.ts       # strip API keys, bearer tokens, absolute paths, emails
-    distiller.ts      # callLLM helper, Haiku classify + Sonnet extract,
-                      # withRateLimitRetry, buildAnthropicClient,
-                      # normalizeModelName
-    writer.ts         # frontmatter + body, wikilink injection, index/log
-    summarizer.ts     # per-project knowledge summaries
-    types.ts          # ParsedSession, Classification, DistilledNote, Category
-  search/
-    retriever.ts      # unified async search: embeddings → TF-IDF fallback
-    embedder.ts       # Ollama integration (nomic-embed-text), cosine sim
-    synthesizer.ts    # Codex synthesis for `vir query`
-  lint/
-    linter.ts         # orphans, staleness, contradictions
-  dedupe/
-    detector.ts       # candidate pairs + LLM judgment
-    merger.ts         # archive / keep / Sonnet-merge
-  Codex/
-    updater.ts        # VIR:START / VIR:END block management
-  state/
-    db.ts             # better-sqlite3, idempotent migrations
-  daemon/
-    launchd.ts        # plist render + load/unload via spawnSync('launchctl')
-  mcp/
-    server.ts         # @modelcontextprotocol/sdk stdio server — vir_query,
-                      # vir_status, vir_recent_notes, vir_project_summary;
-                      # thin facade over search+synthesize+summarizer, opens
-                      # StateDb read-only, logs to stderr only
-    install.ts        # register/unregister with Codex via
-                      # spawnSync('Codex', ['mcp', 'add'|'remove'|'list', …])
-  ui/
-    display.ts        # the ONE place console.log lives — palette, glyphs,
-                      # header(), divider(), box(), spinner(), summary(),
-                      # wrap(), sourceRow(), categoryRow()
-```
-
-## Key conventions
-
-- **Path expansion.** All paths from config (`vaultPath`, `claudeProjectsDir`)
-  must run through `expandHome()` (or `os.homedir()` directly) before use.
-  Never assume `~/` works in `fs.*`.
-- **Per-session try/catch.** The daemon must never die on a single bad
-  transcript. `pipeline/run.ts` wraps every session iteration and records the
-  error in the DB so it doesn't keep retrying.
-- **Provider routing.**
-  - `provider: 'anthropic'` → `@anthropic-ai/sdk` (`buildAnthropicClient`).
-  - `provider: 'kie'` → native `fetch` to `https://api.kie.ai/Codex/v1/messages`
-    with `Authorization: Bearer <kieApiKey>`. The SDK is **not** used for Kie
-    even with a `baseURL` override — its `x-api-key` header conflicts.
-  - Both flow through `callLLM(config, client, opts)`.
-  - On the Kie path the Anthropic SDK is **never instantiated** —
-    `maybeAnthropicClient()` returns `null` for `provider: 'kie'`, and
-    `callLLM` accepts `Anthropic | null` (guards before the Anthropic branch).
-    All 6 LLM callers use `maybeAnthropicClient`, not `buildAnthropicClient`.
-- **Model names.** `normalizeModelName(model, provider)` collapses any model
-  that *starts with* a Kie canonical id (`Codex-haiku-4-5`,
-  `Codex-sonnet-4-6`) back to the bare id. Fallback strips trailing
-  `-YYYYMMDD`. Anthropic path passes through untouched.
-- **Retries.** Every LLM call is wrapped in `withRateLimitRetry()` — three
-  attempts with `60s / 120s / 240s` backoff. The `isRetryable()` predicate
-  retries `429` on both providers; on the Kie path (`HttpError`) it also
-  retries transient `5xx` (`500/502/503/504`). The Anthropic SDK path stays
-  `429`-only — the SDK retries `5xx` itself, so we don't double-retry.
-  `isRetryable` is exported and covered by `distiller.test.ts`. Sessions are
-  processed sequentially with a `2s` delay after each successful distill.
-- **State is the source of truth.** `~/.vir/vir.db` records every session by
-  path with its SHA-256 hash. Reruns are idempotent; a session is only
-  re-distilled if its file content changes. Migrations are additive only
-  (`PRAGMA table_info(sessions)` + `ALTER TABLE ADD COLUMN`).
-- **VIR:START / VIR:END markers are sacred.** `sync-Codex` only mutates bytes
-  between those markers. When a AGENTS.md has no block, the new one is
-  appended; the rest of the file is preserved verbatim.
-- **No comments explaining obvious things.** Comment WHY a non-obvious
-  invariant exists — never WHAT the code does.
-- **All user-facing output goes through `ui/display.ts`.** Other modules
-  must not call `console.log` directly. The pipeline's `fileLog()` writes
-  to `~/.vir/daemon.log` in plain text regardless of UI mode; the
-  display module renders only when `!opts.quiet`.
-- **Ollama is best-effort.** `writer.maybeEmbed()` and the search path
-  both probe via `isOllamaAvailableCached()` and silently fall back
-  (TF-IDF for query; no-op for writer). An embedding failure must never
-  fail a write.
-- **Cost prompts respect intent.** `--yes`, `--daemon`, and
-  `--rewrite-only` all skip the > 20 new-session confirmation. The
-  daemon path *never* prompts (it has no tty).
-- **`vir init` is an @inquirer/* wizard.** Arrow-key `select` for
-  provider and models, `input` with `validate` for keys/numbers,
-  `confirm` for the "create missing path?" flow. Don't fall back to
-  raw readline here — the rest of the file already imports it for
-  dedupe/sync-Codex/cost prompts, but the init UX is the wizard.
-- **`vir run` prints a preflight line.** `N files found · M cached · K
-  new` shows after the scan in dim text, and the same triple goes to
-  the daemon log. Diagnoses "fresh DB looks stale" misconfigurations
-  in one line.
-- **MCP server is a read-only facade.** `vir mcp run` (and the bare `vir mcp`
-  alias) start an `@modelcontextprotocol/sdk` stdio server that reuses
-  `search()`, `synthesize()`, `summarizeProject()`, and
-  `db.listDistilled()`/`getStats()` — no new pipeline logic. It opens
-  `StateDb` with `{ readonly: true }` (skips the WAL pragma + migrations) and
-  must never mutate state. stdout is the JSON-RPC channel, so **all logs go to
-  stderr** via `process.stderr.write`. `SearchHit` carries no category/project,
-  so `vir_query` recovers them by parsing each note's frontmatter.
-- **MCP registration shells out to `Codex`.** `vir mcp install/uninstall/
-  status` call `Codex mcp add|remove|list` via `spawnSync` arg-arrays (never
-  shell strings). A missing `Codex` binary (spawnSync `error.code === 'ENOENT'`)
-  must yield an actionable message, never a crash — `vir mcp status` shows
-  "Codex CLI not detected". The registration runs `vir mcp`, which is why the
-  bare alias must keep launching the server.
-- **`vir --version` reads `package.json` at runtime.** `program.version()` loads
-  it from one dir up from `dist/cli.js` (rootDir is `./src`, so it can't be
-  imported) — never hardcode the version string or it drifts on every bump.
-- **Tests run on Vitest.** `npm test` (`vitest run`). Test files are
-  `*.test.ts` colocated with source and listed in `tsconfig.json` `exclude`,
-  so `tsc`/`npm run build` never emit them to `dist/` (and `src/` is
-  npmignored, so they don't ship). Vitest discovers them via its own glob.
-  Import the unit-under-test with a `.js` extension (`./distiller.js`) per
-  NodeNext — Vitest resolves it to the `.ts`. Start with pure functions.
-- **`sync-Codex` resolves project paths flexibly.** `projectClaudePath(slug)`
-  checks `~/projects/<slug>`, `~/projects/<slug>-*` (glob), `~/code/<slug>`,
-  and `~/dev/<slug>` (first existing wins; canonical fallback). The resolved
-  path flows into `PlanItem.target` and shows as the dry-run plan heading.
-
-## Commands
-
-```
-vir init                          # interactive setup
-vir run                           # one pass (used by daemon)
-vir run --full                    # ignore state cache, re-process everything
-vir run --rewrite-only            # re-render notes from stored content
-                                  # (no scan, no LLM, free)
-vir run --yes                     # skip the > 20 sessions cost prompt
-vir schedule install              # write + load ~/Library/LaunchAgents plist
-vir schedule uninstall            # unload + remove plist
-vir status                        # daemon state + knowledge base breakdown
-vir query "<question>"            # embeddings (Ollama) → TF-IDF fallback
-                                  # → Codex synthesis
-vir embed                         # generate Ollama embeddings for notes
-vir embed --force                 # regenerate all embeddings
-vir summarize <project>           # generate per-project summary
-vir summarize --all               # all projects with notes
-vir lint                          # orphans + stale + contradictions
-vir lint --orphans                # orphans only (free)
-vir lint --stale                  # staleness only (free)
-vir lint --contradictions         # contradictions only (Haiku tokens)
-vir dedupe                        # interactive duplicate review + merge
-vir sync-Codex                   # diff then confirm AGENTS.md updates
-vir sync-Codex --dry-run         # diff only, never write
-vir sync-Codex --force           # apply without confirmation
-vir sync-Codex <project>         # specific project only
-vir sync-Codex --global          # only ~/.Codex/AGENTS.md
-vir mcp                           # run MCP server over stdio (alias for run)
-vir mcp run                       # run MCP server over stdio
-vir mcp install                   # register with Codex (Codex mcp add)
-vir mcp install --scope project   # register at project scope (default: user)
-vir mcp uninstall                 # unregister (Codex mcp remove vir)
-vir mcp status                    # check registration (Codex mcp list)
-```
-
-## File locations
-
-- Config: `~/.vir/config.json`
-- State: `~/.vir/vir.db` (better-sqlite3 with WAL). A one-shot rename in
-  `StateDb`'s constructor moves the pre-rename `~/.vir/state.db` over to
-  `~/.vir/vir.db` if it's still around — preserves cache, hides the
-  history of the doc/code mismatch.
-- Daemon log: `~/.vir/daemon.log`
-- launchd plist: `~/Library/LaunchAgents/lab.growthq.vir.plist`
-- MCP registration: managed by Codex (`Codex mcp add/remove`), not by
-  vir — user scope writes to `~/.Codex.json`, project scope to `.mcp.json`
-- Vault notes: `<vaultPath>/<outputDir>/{patterns,gotchas,decisions,tools,projects,archived}/`
-- Vault index: `<vaultPath>/<outputDir>/index.md`
-- Vault run log: `<vaultPath>/<outputDir>/log.md`