lat.md 0.4.0 → 0.4.2

package/README.md

@@ -29,7 +29,7 @@ npm install -g lat.md
 
 Or use directly with `npx lat.md@latest <command>`.
 
-For semantic search (`lat search`), set the `LAT_LLM_KEY` environment variable with an OpenAI (`sk-...`) or Vercel AI Gateway (`vck_...`) API key.
+After installing, run `lat init` in the repo you want to use lat in.
 
 ## How it works
 
@@ -58,6 +58,15 @@ npx lat.md search "how do we auth?"    # semantic search via embeddings
 npx lat.md prompt "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
 ```
 
+## Configuration
+
+Semantic search (`lat search`) requires an OpenAI (`sk-...`) or Vercel AI Gateway (`vck_...`) API key. The key is resolved in order:
+
+1. `LAT_LLM_KEY` env var — direct value
+2. `LAT_LLM_KEY_FILE` env var — path to a file containing the key
+3. `LAT_LLM_KEY_HELPER` env var — shell command that prints the key (10s timeout)
+4. Config file — saved by `lat init`. Run `lat config` to see its location.
+
 ## Development
 
 Requires Node.js 22+ and pnpm.

package/dist/src/cli/check.js

@@ -289,10 +289,17 @@ export async function checkAllCmd(ctx) {
         process.exit(1);
     console.log(ctx.chalk.green('All checks passed'));
     const { getLlmKey } = await import('../config.js');
-    if (!getLlmKey()) {
+    let hasKey = false;
+    try {
+        hasKey = !!getLlmKey();
+    }
+    catch {
+        // key resolution failed (e.g. empty file) — treat as missing
+    }
+    if (!hasKey) {
         console.log(ctx.chalk.yellow('Warning:') +
             ' No LLM key found — semantic search (lat search) will not work.' +
-            ' Set LAT_LLM_KEY env var or run ' +
+            ' Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run ' +
             ctx.chalk.cyan('lat init') +
             ' to configure.');
     }

package/dist/src/cli/index.js

@@ -3,7 +3,7 @@
 if (!process.argv.includes('--verbose')) {
     process.noDeprecation = true;
 }
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
@@ -145,4 +145,13 @@ program
     const { startMcpServer } = await import('../mcp/server.js');
     await startMcpServer();
 });
+program
+    .command('config')
+    .description('Show configuration file path')
+    .action(async () => {
+    const { getConfigPath } = await import('../config.js');
+    const configPath = getConfigPath();
+    const exists = existsSync(configPath);
+    console.log(`Config file: ${configPath}${exists ? '' : ' (not found)'}`);
+});
 await program.parseAsync();

package/dist/src/cli/init.js

@@ -106,31 +106,31 @@ function ensureGitignored(root, entry) {
 function mcpCommand() {
     return { command: resolve(process.argv[1]), args: ['mcp'] };
 }
-function hasMcpServer(configPath) {
+function hasMcpServer(configPath, key) {
     if (!existsSync(configPath))
         return false;
     try {
         const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
-        return !!cfg?.mcpServers?.lat;
+        return !!cfg?.[key]?.lat;
     }
     catch {
         return false;
     }
 }
-function addMcpServer(configPath) {
-    let cfg = { mcpServers: {} };
+function addMcpServer(configPath, key) {
+    let cfg = { [key]: {} };
     if (existsSync(configPath)) {
         const raw = readFileSync(configPath, 'utf-8');
         try {
             cfg = JSON.parse(raw);
-            if (!cfg.mcpServers)
-                cfg.mcpServers = {};
+            if (!cfg[key])
+                cfg[key] = {};
         }
         catch (e) {
             throw new Error(`Cannot parse ${configPath}: ${e.message}`);
         }
     }
-    cfg.mcpServers.lat = mcpCommand();
+    cfg[key].lat = mcpCommand();
     mkdirSync(join(configPath, '..'), { recursive: true });
     writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
 }
@@ -182,11 +182,11 @@ async function setupClaudeCode(root, template) {
     console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
     console.log(chalk.dim('  more visibility and makes agents more likely to use it proactively.'));
     const mcpPath = join(root, '.mcp.json');
-    if (hasMcpServer(mcpPath)) {
+    if (hasMcpServer(mcpPath, 'mcpServers')) {
         console.log(chalk.green('  MCP server') + ' already configured');
     }
     else {
-        addMcpServer(mcpPath);
+        addMcpServer(mcpPath, 'mcpServers');
         console.log(chalk.green('  MCP server') + ' registered in .mcp.json');
         created.push('.mcp.json');
     }
@@ -213,11 +213,11 @@ async function setupCursor(root) {
     console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
     console.log(chalk.dim('  more visibility and makes agents more likely to use it proactively.'));
     const mcpPath = join(root, '.cursor', 'mcp.json');
-    if (hasMcpServer(mcpPath)) {
+    if (hasMcpServer(mcpPath, 'mcpServers')) {
         console.log(chalk.green('  MCP server') + ' already configured');
     }
     else {
-        addMcpServer(mcpPath);
+        addMcpServer(mcpPath, 'mcpServers');
         console.log(chalk.green('  MCP server') + ' registered in .cursor/mcp.json');
         created.push('.cursor/mcp.json');
     }
@@ -248,11 +248,11 @@ async function setupCopilot(root) {
     console.log(chalk.dim('  Agents can call `lat` from the command line, but an MCP server gives lat'));
     console.log(chalk.dim('  more visibility and makes agents more likely to use it proactively.'));
     const mcpPath = join(root, '.vscode', 'mcp.json');
-    if (hasMcpServer(mcpPath)) {
+    if (hasMcpServer(mcpPath, 'servers')) {
         console.log(chalk.green('  MCP server') + ' already configured');
     }
     else {
-        addMcpServer(mcpPath);
+        addMcpServer(mcpPath, 'servers');
         console.log(chalk.green('  MCP server') + ' registered in .vscode/mcp.json');
         created.push('.vscode/mcp.json');
     }

package/dist/src/cli/search.js

@@ -7,12 +7,19 @@ import { loadAllSections, flattenSections } from '../lattice.js';
 import { formatResultList } from '../format.js';
 import { getLlmKey, getConfigPath } from '../config.js';
 export async function searchCmd(ctx, query, opts) {
-    const key = getLlmKey();
+    let key;
+    try {
+        key = getLlmKey();
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
     if (!key) {
-        console.error(chalk.red('LAT_LLM_KEY is not set.') +
-            ' Set the LAT_LLM_KEY env var, or run ' +
+        console.error(chalk.red('No API key configured.') +
+            ' Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run ' +
             chalk.cyan('lat init') +
-            ' to save a key in ' +
+            ' to save one in ' +
             chalk.dim(getConfigPath()) +
             '.');
         process.exit(1);

package/dist/src/config.d.ts

@@ -8,8 +8,10 @@ export declare function writeConfig(config: LatConfig): void;
 /**
  * Returns the LLM key from (in priority order):
  * 1. LAT_LLM_KEY environment variable
- * 2. llm_key field in ~/.config/lat/config.json
+ * 2. LAT_LLM_KEY_FILE — path to a file containing the key
+ * 3. LAT_LLM_KEY_HELPER — shell command that prints the key
+ * 4. llm_key field in ~/.config/lat/config.json
  *
- * Returns undefined if neither is set.
+ * Returns undefined if none is set.
  */
 export declare function getLlmKey(): string | undefined;

package/dist/src/config.js

@@ -1,3 +1,4 @@
+import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import xdg from '@folder/xdg';
@@ -28,14 +29,37 @@ export function writeConfig(config) {
 /**
  * Returns the LLM key from (in priority order):
  * 1. LAT_LLM_KEY environment variable
- * 2. llm_key field in ~/.config/lat/config.json
+ * 2. LAT_LLM_KEY_FILE — path to a file containing the key
+ * 3. LAT_LLM_KEY_HELPER — shell command that prints the key
+ * 4. llm_key field in ~/.config/lat/config.json
  *
- * Returns undefined if neither is set.
+ * Returns undefined if none is set.
  */
 export function getLlmKey() {
     const envKey = process.env.LAT_LLM_KEY;
     if (envKey)
         return envKey;
+    const file = process.env.LAT_LLM_KEY_FILE;
+    if (file) {
+        const content = readFileSync(file, 'utf-8').trim();
+        if (!content) {
+            throw new Error(`LAT_LLM_KEY_FILE (${file}) is empty.`);
+        }
+        return content;
+    }
+    const helper = process.env.LAT_LLM_KEY_HELPER;
+    if (helper) {
+        const result = execSync(helper, {
+            encoding: 'utf-8',
+            timeout: 10_000,
+        }).trim();
+        if (!result) {
+            throw new Error('LAT_LLM_KEY_HELPER command returned an empty string.');
+        }
+        return result;
+    }
     const config = readConfig();
-    return config.llm_key || undefined;
+    if (config.llm_key)
+        return config.llm_key;
+    return undefined;
 }

package/dist/src/mcp/server.js

@@ -70,13 +70,22 @@ export async function startMcpServer() {
             .describe('Max results (default 5)'),
     }, async ({ query, limit }) => {
         const { getLlmKey } = await import('../config.js');
-        const key = getLlmKey();
+        let key;
+        try {
+            key = getLlmKey();
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: err.message }],
+                isError: true,
+            };
+        }
         if (!key) {
             return {
                 content: [
                     {
                         type: 'text',
-                        text: 'No LLM key found. Set LAT_LLM_KEY env var or run `lat init` to save a key in ~/.config/lat/config.json.',
+                        text: 'No LLM key found. Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run `lat init`.',
                     },
                 ],
                 isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lat.md",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "packageManager": "pnpm@10.30.2",

package/templates/AGENTS.md

@@ -29,7 +29,7 @@ lat check                      # validate all links and code refs
 
 Run `lat --help` when in doubt about available commands or options.
 
-If `lat search` fails because `LAT_LLM_KEY` is not set, explain to the user that semantic search requires an API key (`export LAT_LLM_KEY=sk-...` for OpenAI or `export LAT_LLM_KEY=vck_...` for Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
+If `lat search` fails because no API key is configured, explain to the user that semantic search requires a key provided via `LAT_LLM_KEY` (direct value), `LAT_LLM_KEY_FILE` (path to key file), or `LAT_LLM_KEY_HELPER` (command that prints the key). Supported key prefixes: `sk-...` (OpenAI) or `vck_...` (Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
 
 # Syntax primer