@lorekit/cli 1.3.0 → 1.4.1

package/README.md

@@ -1,26 +1,33 @@
 # @lorekit/cli
 
-Install the **LoreKit shared-memory skill** into a project and run health
-checks against your LoreKit MCP server — a small, zero-dependency Node CLI.
+> The fastest way to give your AI coding agent a memory that survives the session.
 
-LoreKit gives coding agents a shared, persistent memory: lessons one agent
-learns are stored centrally and read by every other agent, in every session,
-CI included. This CLI wires an agent up to it in two commands.
+[![npm](https://img.shields.io/npm/v/@lorekit/cli.svg)](https://www.npmjs.com/package/@lorekit/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
 
-## Install
+[LoreKit](https://github.com/mthines/lorekit) gives coding agents a **shared,
+persistent memory**: a lesson one agent learns — a migration gotcha, a
+flaky-test fix, a costly wrong assumption — is stored once and recalled by every
+other agent, in every session, on every machine, CI included.
 
-Install it globally — recommended. You get one pinned version, the `lorekit`
-command stays on your `PATH`, and the plugin hooks (which call `lorekit hook`
-on every lifecycle event) fire instantly instead of paying an `npx` resolution
-cost each time:
+This is the CLI that connects your agent to it. One command scaffolds
+everything — the memory skill, the MCP connection, and the lifecycle hooks — and
+it's a zero-dependency Node binary that also runs fully offline against local
+markdown files if you never want to sign up for anything.
 
 ```bash
 npm install -g @lorekit/cli
-lorekit install
-lorekit doctor
+lorekit install     # wires up the skill, MCP server, and hooks
+lorekit doctor      # verify it's all green
 ```
 
-Upgrade later with `npm install -g @lorekit/cli@latest`.
+## Install
+
+The quickstart above uses the **global install — recommended.** You get one
+pinned version, the `lorekit` command stays on your `PATH`, and the plugin hooks
+(which call `lorekit hook` on every lifecycle event) fire instantly instead of
+paying an `npx` resolution cost each time. Upgrade later with
+`npm install -g @lorekit/cli@latest`.
 
 Prefer not to install anything? Run it on demand with `npx` — same commands,
 always the latest version, fetched and cached per use:

package/bin/lorekit.mjs

@@ -83,25 +83,164 @@ ${c.bold('Examples')}
   npx @lorekit/cli doctor --deep
   npx @lorekit/cli migrate --from .lore                 # preview a rename
   npx @lorekit/cli migrate --from .lore --to project --yes
+
+Run ${c.cyan('lorekit <command> --help')} for command-specific options.
 `;
 
+// Per-command help. Keyed by command; `lorekit <command> --help` prints the
+// focused entry instead of the full top-level HELP, so a user only sees the
+// flags that actually apply to what they're running.
+const COMMAND_HELP = {
+  install: `${c.bold('lorekit install')} — scaffold the skill, wire the MCP server, install the hooks
+
+${c.bold('Usage')}
+  npx @lorekit/cli install [options]
+
+Scaffolds the lorekit-memory skill, adds the LoreKit MCP server, and wires the
+deterministic hooks (lessons on SessionStart, a nudge on tool failure + at Stop).
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --project           Install into this project: .claude/skills + .mcp.json (default)
+      --global            Install for every project: ~/.claude/skills + ~/.claude.json
+  -e, --endpoint <url>    LoreKit MCP endpoint (else LOREKIT_MCP_URL)
+  -t, --token <token>     LoreKit token: lk_rw_* read+write, lk_ro_* read-only, lk_wo_* write-only
+      --no-hooks          Skip wiring the lifecycle hooks (skill stays model-invoked only)
+      --force             Overwrite existing skill files
+  -y, --yes               Non-interactive; never prompt (defaults to --project)
+
+${c.bold('Examples')}
+  npx @lorekit/cli install --endpoint https://ref.supabase.co/functions/v1/mcp --token lk_rw_xxx
+  npx @lorekit/cli install --global
+  npx @lorekit/cli install --no-hooks --yes
+`,
+  uninstall: `${c.bold('lorekit uninstall')} — reverse install for the chosen scope
+
+${c.bold('Usage')}
+  npx @lorekit/cli uninstall [options]
+
+Removes the lorekit-memory skill, the MCP server entry, and the lifecycle hooks.
+Surgical — other servers, hooks, and settings are left untouched.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --project           Uninstall from this project (default)
+      --global            Uninstall the global (~/.claude) setup
+  -y, --yes               Non-interactive; never prompt
+
+${c.bold('Examples')}
+  npx @lorekit/cli uninstall --global
+  npx @lorekit/cli uninstall --project --yes
+`,
+  doctor: `${c.bold('lorekit doctor')} — verify the skill install and the resolved memory backend
+
+${c.bold('Usage')}
+  npx @lorekit/cli doctor [options]
+
+Checks the node runtime, skill install, resolved memory mode, MCP connectivity,
+token, and scope.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --mode <mode>       Override the resolved mode: off | local | remote
+  -e, --endpoint <url>    Endpoint override (else .mcp.json / LOREKIT_MCP_URL)
+  -t, --token <token>     Token override (else .mcp.json / LOREKIT_TOKEN)
+      --store <path>      Local project-tier store directory (default: .lorekit)
+      --deep              Do a write→read→delete round-trip
+
+${c.bold('Examples')}
+  npx @lorekit/cli doctor
+  npx @lorekit/cli doctor --deep
+  npx @lorekit/cli doctor --mode local
+`,
+  migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
+
+${c.bold('Usage')}
+  npx @lorekit/cli migrate --from <path> [options]
+
+Dry-run by default; pass --yes (or --apply) to write. Idempotent.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --from <path>       Source store to migrate from (required)
+      --to <tier>         Destination tier: home | project (default routes by scope)
+      --apply             Apply the migration (alias of --yes)
+  -y, --yes               Apply the migration; never prompt
+
+${c.bold('Examples')}
+  npx @lorekit/cli migrate --from .lore                 # preview a rename
+  npx @lorekit/cli migrate --from .lore --to project --yes
+`,
+  hook: `${c.bold('lorekit hook')} — hook engine for Claude Code / Cursor / Codex
+
+${c.bold('Usage')}
+  lorekit hook --adapter <claude|cursor|codex> --event <name> [--dir <path>]
+
+Machine-facing: reads the host's JSON on stdin and injects lessons or a
+retrospective nudge on stdout, always exiting 0. Wired into a plugin's hook
+config by \`lorekit install\` — not run by hand.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root
+      --adapter <name>    Host framework: claude | cursor | codex
+      --event <name>      Host hook event (else read from the stdin payload)
+`,
+  mcp: `${c.bold('lorekit mcp')} — local stdio MCP server
+
+${c.bold('Usage')}
+  lorekit mcp [--dir <path>]
+
+Machine-facing: exposes the memory.* tools backed by the resolved store (local
+.lorekit/ offline, or remote passthrough) over JSON-RPC on stdin/stdout, so
+.mcp.json can point at the CLI instead of mcp-remote. Not run by hand.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+`,
+};
+
+// Every long flag the CLI understands (after alias resolution). Passed to the
+// parser so an unrecognized flag is captured rather than silently ignored — a
+// typo like `--gloabl` should fail loudly, not quietly fall back to --project.
+const KNOWN_FLAGS = [
+  'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
+  'from', 'to', 'apply', 'yes', 'no-hooks', 'force', 'deep', 'adapter',
+  'event', 'help', 'version',
+];
+
+// Commands that write to disk / talk to the network on a human's behalf. These
+// reject unknown flags; the machine-facing `hook` / `mcp` do not (they must
+// never fail on a stray flag, and only ever receive flags we control).
+const HUMAN_COMMANDS = new Set(['install', 'uninstall', 'doctor', 'migrate']);
+
 async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
     booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks'],
+    known: KNOWN_FLAGS,
   });
 
+  const command = args._[0];
+
+  // Help is intercepted first — before the machine-facing hook/mcp dispatch — so
+  // `lorekit <command> --help` always documents the command (even hook/mcp)
+  // instead of blocking on stdin. Real hook/mcp invocations never pass --help.
+  if (args.help) {
+    log(command && COMMAND_HELP[command] ? COMMAND_HELP[command] : HELP);
+    return 0;
+  }
+
   // `hook` is machine-facing: it must never print help/errors to stdout
   // (that would corrupt the JSON the host parses). Handle it before the
-  // help/usage branch and always resolve to exit 0.
-  if (args._[0] === 'hook') {
+  // usage branch and always resolve to exit 0.
+  if (command === 'hook') {
     return hook(args);
   }
 
   // `mcp` is machine-facing too: only JSON-RPC frames may reach stdout, so it
-  // must bypass the help/usage branch. It serves stdio until the client closes.
-  if (args._[0] === 'mcp') {
+  // must bypass the usage branch. It serves stdio until the client closes.
+  if (command === 'mcp') {
     return mcpServer(args);
   }
 
@@ -110,11 +249,18 @@ async function main() {
     return 0;
   }
 
-  const command = args._[0];
-
-  if (args.help || !command) {
+  if (!command) {
     log(HELP);
-    return command ? 0 : args.help ? 0 : 1;
+    return 1;
+  }
+
+  // Reject unrecognized flags on human-facing commands with an actionable
+  // pointer, rather than silently ignoring a typo that would change behavior.
+  if (HUMAN_COMMANDS.has(command) && args._unknown.length > 0) {
+    const plural = args._unknown.length > 1 ? 's' : '';
+    err(`${c.red(`Unknown option${plural}:`)} ${args._unknown.join(', ')}`);
+    err(`Run ${c.cyan(`lorekit ${command} --help`)} to see valid options.`);
+    return 1;
   }
 
   // Human-facing commands are wrapped so we can see which commands people run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/util.mjs

@@ -119,8 +119,13 @@ export function select(question, options, { defaultIndex = 0 } = {}) {
 
 // Minimal flag parser: --key value, --key=value, -k value, and bare --flags.
 // `aliases` maps short → long; `booleans` lists flags that take no value.
-export function parseArgs(argv, { aliases = {}, booleans = [] } = {}) {
+// When `known` is a non-null list of long flag names, any flag whose resolved
+// name isn't in it is collected (as its original token) into `out._unknown` —
+// letting the caller reject typos like `--gloabl` instead of silently ignoring
+// them. `out._unknown` is only present when `known` was supplied.
+export function parseArgs(argv, { aliases = {}, booleans = [], known = null } = {}) {
   const out = { _: [] };
+  const unknown = [];
   for (let i = 0; i < argv.length; i++) {
     let token = argv[i];
     if (!token.startsWith('-')) {
@@ -135,6 +140,7 @@ export function parseArgs(argv, { aliases = {}, booleans = [] } = {}) {
     }
     let key = token.replace(/^-+/, '');
     if (aliases[key]) key = aliases[key];
+    if (known && !known.includes(key)) unknown.push(token);
     if (booleans.includes(key)) {
       out[key] = true;
       continue;
@@ -150,5 +156,6 @@ export function parseArgs(argv, { aliases = {}, booleans = [] } = {}) {
     }
     out[key] = value;
   }
+  if (known) out._unknown = unknown;
   return out;
 }