@lorekit/cli 1.4.0 → 1.5.0

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

@@ -10,6 +10,7 @@ import { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
 import { mcpServer } from '../src/mcp-server.mjs';
 import { traceCommand } from '../src/telemetry.mjs';
+import { loadDotEnv } from '../src/dotenv.mjs';
 
 // Read the version from package.json so it always matches the published
 // package — release-please bumps package.json, and this tracks it for free.
@@ -76,6 +77,9 @@ ${c.bold('Environment')}
   LOREKIT_TELEMETRY / DO_NOT_TRACK     set to 0/off (or DO_NOT_TRACK=1) to opt
                                        out of anonymous command-usage telemetry
 
+A ${c.cyan('.env')} file in the current directory is loaded automatically. Real
+environment variables take precedence, so the file is a fallback.
+
 ${c.bold('Examples')}
   npx @lorekit/cli install --endpoint https://ref.supabase.co/functions/v1/mcp --token lk_rw_xxx
   npx @lorekit/cli install --global    # set up memory for every project (~/.claude)
@@ -214,6 +218,12 @@ const KNOWN_FLAGS = [
 const HUMAN_COMMANDS = new Set(['install', 'uninstall', 'doctor', 'migrate']);
 
 async function main() {
+  // Load a `.env` from the current directory (if any) before anything reads the
+  // environment — so telemetry config, tokens, and endpoints can come from a
+  // file. Best-effort and non-overriding: real env vars still win, a missing
+  // file is a silent no-op, and it never prints (safe for hook/mcp stdout).
+  loadDotEnv();
+
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },

package/package.json

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

package/src/dotenv.mjs

@@ -0,0 +1,106 @@
+// LoreKit CLI — zero-dependency `.env` loader.
+//
+// The CLI is strictly zero-dependency (see package.json), and `engines.node`
+// is `>=18`, so we can rely on neither the `dotenv` package nor Node's built-in
+// `process.loadEnvFile()` (added in 20.6). This hand-rolled loader fills the gap
+// with a small, faithful parser and a best-effort file read.
+//
+// Semantics (chosen to match the dominant `dotenv` mental model, NOT Node's
+// `--env-file`):
+//   • A `.env` in the current working directory is loaded automatically if it
+//     exists. A missing file is a silent no-op — the default for real users.
+//   • Existing real environment variables WIN. A value already present in
+//     `process.env` (an explicit `export`, a CI var, an inline `FOO=bar cmd`)
+//     is never overwritten by the file. So a committed `.env` is a fallback,
+//     and a shell opt-out like `LOREKIT_TELEMETRY=0` can't be silently undone.
+//   • Loading never throws — a malformed line is skipped, an unreadable file is
+//     ignored. Nothing is printed, so machine-facing `hook` / `mcp` stdout is
+//     never touched.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Parse the contents of a `.env` file into a flat key→value object. Pure and
+ * unit-tested. Supports: blank lines, `#` comments, an optional `export `
+ * prefix, single/double-quoted values (double quotes unescape \n \r \t \\ \"),
+ * and trailing inline comments after unquoted values. Invalid keys are skipped.
+ */
+export function parseDotEnv(text) {
+  const out = {};
+  if (!text) return out;
+  for (const rawLine of String(text).split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+
+    // Strip an optional `export ` prefix (a common shell-sourceable convention).
+    const withoutExport = line.startsWith('export ') ? line.slice(7).trimStart() : line;
+
+    const eq = withoutExport.indexOf('=');
+    if (eq <= 0) continue; // no key, or `=value` with empty key → skip
+
+    const key = withoutExport.slice(0, eq).trim();
+    if (!KEY_RE.test(key)) continue;
+
+    out[key] = parseValue(withoutExport.slice(eq + 1).trim());
+  }
+  return out;
+}
+
+/**
+ * Resolve one raw right-hand-side into its final string value: unwrap matching
+ * quotes (unescaping only inside double quotes), or, for a bare value, drop a
+ * trailing ` # comment`.
+ */
+function parseValue(raw) {
+  if (!raw) return '';
+  const q = raw[0];
+  if ((q === '"' || q === "'") && raw.length >= 2 && raw[raw.length - 1] === q) {
+    const inner = raw.slice(1, -1);
+    return q === '"'
+      ? inner.replace(/\\([nrt"\\])/g, (_, ch) =>
+          ch === 'n' ? '\n' : ch === 'r' ? '\r' : ch === 't' ? '\t' : ch,
+        )
+      : inner;
+  }
+  // Unquoted: a whitespace-preceded `#` starts an inline comment.
+  const hash = raw.search(/\s#/);
+  return (hash === -1 ? raw : raw.slice(0, hash)).trim();
+}
+
+/**
+ * Load a `.env` from `cwd` into `env`, without overriding keys already set.
+ * Best-effort: returns the list of keys it applied (empty if the file is absent
+ * or unreadable). Never throws, never prints.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]  directory to look for `.env` in (default cwd)
+ * @param {object} [opts.env]  target env object to mutate (default process.env)
+ * @returns {string[]} keys newly set from the file
+ */
+export function loadDotEnv({ cwd = process.cwd(), env = process.env } = {}) {
+  let text;
+  try {
+    text = readFileSync(path.join(cwd, '.env'), 'utf8');
+  } catch {
+    return []; // no file (ENOENT) or unreadable → nothing to do
+  }
+
+  const applied = [];
+  try {
+    const parsed = parseDotEnv(text);
+    for (const [key, value] of Object.entries(parsed)) {
+      // Real env wins: only fill keys that aren't already set.
+      if (env[key] === undefined) {
+        env[key] = value;
+        applied.push(key);
+      }
+    }
+  } catch {
+    // A malformed file must never break the CLI — leave whatever was applied.
+  }
+  return applied;
+}

package/src/telemetry-token.mjs

@@ -14,4 +14,4 @@
 // At runtime this is only the lowest-priority source: an explicit
 // LOREKIT_TELEMETRY_TOKEN env var or OTEL_EXPORTER_OTLP_HEADERS still win (see
 // resolveTelemetryConfig in telemetry.mjs).
-export const TELEMETRY_TOKEN = '';
+export const TELEMETRY_TOKEN = "auth_XFLXatTBqqgvhZ12Tn9sfttClUkBPodp";

package/src/telemetry.mjs

@@ -28,7 +28,7 @@ import { TELEMETRY_TOKEN } from './telemetry-token.mjs';
 // ── Baked-in defaults (public by design) ──────────────────────────────────────
 // The endpoint is a committed default; the token is injected at publish time
 // (empty in the source tree, so default export stays off until built/injected).
-const DEFAULT_ENDPOINT = 'https://ingress.us-east-1.aws.dash0.com';
+const DEFAULT_ENDPOINT = 'https://ingress.europe-west4.gcp.dash0-dev.com';
 const DEFAULT_TOKEN = TELEMETRY_TOKEN; // injected from LOREKIT_TELEMETRY_TOKEN at publish
 const DEFAULT_DATASET = 'lorekit-cli';