lat.md 0.8.0 → 0.8.2

package/dist/src/cli/init.js

@@ -1,11 +1,13 @@
 import { existsSync, cpSync, mkdirSync, writeFileSync, readFileSync, } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import { findTemplatesDir } from './templates.js';
 import { readAgentsTemplate, readCursorRulesTemplate, readPiExtensionTemplate, } from './gen.js';
-import { getConfigPath, readConfig, writeConfig, } from '../config.js';
+import { getLlmKey, getConfigPath, readConfig, writeConfig, } from '../config.js';
 import { writeInitMeta, readFileHash, contentHash } from '../init-version.js';
+import { getLocalVersion, fetchLatestVersion } from '../version.js';
 import { selectMenu } from './select-menu.js';
 async function confirm(rl, message) {
     while (true) {
@@ -86,10 +88,26 @@ function resolveLatBin() {
     // .ts file but no special loader flags — best-effort, just return the path
     return script;
 }
+/** Return the lat binary string for the given command style. */
+function latBinString(style) {
+    if (style === 'global')
+        return 'lat';
+    if (style === 'npx')
+        return 'npx lat.md@latest';
+    return resolveLatBin();
+}
+/** Return the MCP server command descriptor for the given command style. */
+function styledMcpCommand(style) {
+    if (style === 'global')
+        return { command: 'lat', args: ['mcp'] };
+    if (style === 'npx')
+        return { command: 'npx', args: ['lat.md@latest', 'mcp'] };
+    return mcpCommand();
+}
 // ── Claude Code helpers ──────────────────────────────────────────────
-/** Derive the hook command prefix from the currently running binary. */
-function latHookCommand(event) {
-    return `${resolveLatBin()} hook claude ${event}`;
+/** Derive the hook command prefix for the given command style. */
+function latHookCommand(style, event) {
+    return `${latBinString(style)} hook claude ${event}`;
 }
 /** True if any command in this entry looks like it was installed by lat. */
 function isLatHookEntry(entry) {
@@ -103,7 +121,7 @@ function isLatHookEntry(entry) {
  * Remove all lat-owned hook entries from settings, then add fresh ones.
  * Preserves any non-lat hooks the user may have configured.
  */
-function syncLatHooks(settingsPath) {
+function syncLatHooks(settingsPath, style) {
     let settings = {};
     if (existsSync(settingsPath)) {
         const raw = readFileSync(settingsPath, 'utf-8');
@@ -136,7 +154,7 @@ function syncLatHooks(settingsPath) {
             hooks[event] = [];
         }
         hooks[event].push({
-            hooks: [{ type: 'command', command: latHookCommand(event) }],
+            hooks: [{ type: 'command', command: latHookCommand(style, event) }],
         });
     }
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
@@ -154,6 +172,25 @@ function ensureGitignored(root, entry) {
             return;
         }
     }
+    // Skip if the entry is already tracked in git — adding it to .gitignore
+    // would have no effect and confuse the user.
+    if (existsSync(gitDir)) {
+        try {
+            const result = execSync(`git ls-files "${entry}"`, {
+                cwd: root,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            if (result.trim().length > 0) {
+                console.log(chalk.yellow(`  ${entry}`) +
+                    ' is already checked in to git — skipping .gitignore');
+                return;
+            }
+        }
+        catch {
+            console.log(chalk.yellow(`  Warning:`) + ' git ls-files failed — skipping check');
+        }
+    }
     if (existsSync(gitignorePath)) {
         // Append to existing .gitignore
         let content = readFileSync(gitignorePath, 'utf-8');
@@ -215,7 +252,7 @@ function hasMcpServer(configPath, key) {
         return false;
     }
 }
-function addMcpServer(configPath, key) {
+function addMcpServer(configPath, key, style) {
     let cfg = { [key]: {} };
     if (existsSync(configPath)) {
         const raw = readFileSync(configPath, 'utf-8');
@@ -228,7 +265,7 @@ function addMcpServer(configPath, key) {
             throw new Error(`Cannot parse ${configPath}: ${e.message}`);
         }
     }
-    cfg[key].lat = mcpCommand();
+    cfg[key].lat = styledMcpCommand(style);
     mkdirSync(join(configPath, '..'), { recursive: true });
     writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
 }
@@ -283,7 +320,7 @@ async function setupAgentsMd(root, latDir, template, hashes, ask) {
     if (hash)
         hashes['AGENTS.md'] = hash;
 }
-async function setupClaudeCode(root, latDir, template, hashes, ask) {
+async function setupClaudeCode(root, latDir, template, hashes, ask, style) {
     // CLAUDE.md — written directly (not a symlink)
     const hash = await writeTemplateFile(root, latDir, 'CLAUDE.md', template, 'claude.md', 'CLAUDE.md', '  ', ask);
     if (hash)
@@ -295,7 +332,7 @@ async function setupClaudeCode(root, latDir, template, hashes, ask) {
     const claudeDir = join(root, '.claude');
     const settingsPath = join(claudeDir, 'settings.json');
     mkdirSync(claudeDir, { recursive: true });
-    syncLatHooks(settingsPath);
+    syncLatHooks(settingsPath, style);
     console.log(chalk.green('  Hooks') + ' synced (UserPromptSubmit + Stop)');
     // Ensure .claude is gitignored (settings contain local absolute paths)
     ensureGitignored(root, '.claude');
@@ -308,13 +345,13 @@ async function setupClaudeCode(root, latDir, template, hashes, ask) {
         console.log(chalk.green('  MCP server') + ' already configured');
     }
     else {
-        addMcpServer(mcpPath, 'mcpServers');
+        addMcpServer(mcpPath, 'mcpServers', style);
         console.log(chalk.green('  MCP server') + ' registered in .mcp.json');
     }
     // Ensure .mcp.json is gitignored (it contains local absolute paths)
     ensureGitignored(root, '.mcp.json');
 }
-async function setupCursor(root, latDir, hashes, ask) {
+async function setupCursor(root, latDir, hashes, ask, style) {
     // .cursor/rules/lat.md
     const hash = await writeTemplateFile(root, latDir, '.cursor/rules/lat.md', readCursorRulesTemplate(), 'cursor-rules.md', 'Rules (.cursor/rules/lat.md)', '  ', ask);
     if (hash)
@@ -328,7 +365,7 @@ async function setupCursor(root, latDir, hashes, ask) {
         console.log(chalk.green('  MCP server') + ' already configured');
     }
     else {
-        addMcpServer(mcpPath, 'mcpServers');
+        addMcpServer(mcpPath, 'mcpServers', style);
         console.log(chalk.green('  MCP server') + ' registered in .cursor/mcp.json');
     }
     // Ensure .cursor/mcp.json is gitignored (it contains local absolute paths)
@@ -337,7 +374,7 @@ async function setupCursor(root, latDir, hashes, ask) {
     console.log(chalk.yellow('  Note:') +
         ' Enable MCP in Cursor: Settings → Features → MCP → check "Enable MCP"');
 }
-async function setupCopilot(root, latDir, hashes, ask) {
+async function setupCopilot(root, latDir, hashes, ask, style) {
     // .github/copilot-instructions.md
     const hash = await writeTemplateFile(root, latDir, '.github/copilot-instructions.md', readAgentsTemplate(), 'agents.md', 'Instructions (.github/copilot-instructions.md)', '  ', ask);
     if (hash)
@@ -351,18 +388,18 @@ async function setupCopilot(root, latDir, hashes, ask) {
         console.log(chalk.green('  MCP server') + ' already configured');
     }
     else {
-        addMcpServer(mcpPath, 'servers');
+        addMcpServer(mcpPath, 'servers', style);
         console.log(chalk.green('  MCP server') + ' registered in .vscode/mcp.json');
     }
 }
-async function setupPi(root, latDir, hashes, ask) {
+async function setupPi(root, latDir, hashes, ask, style) {
     // AGENTS.md — Pi reads this natively
     // (already created in the shared step if any non-Claude agent is selected)
     // .pi/extensions/lat.ts — extension that registers tools + lifecycle hooks
     console.log('');
     console.log(chalk.dim('  The Pi extension registers lat tools and hooks into the agent lifecycle'));
     console.log(chalk.dim('  to inject search context and validate lat.md/ before finishing.'));
-    const template = readPiExtensionTemplate().replace('__LAT_BIN__', resolveLatBin());
+    const template = readPiExtensionTemplate().replace('__LAT_BIN__', latBinString(style));
     const hash = await writeTemplateFile(root, latDir, '.pi/extensions/lat.ts', template, 'pi-extension.ts', 'Extension (.pi/extensions/lat.ts)', '  ', ask);
     if (hash)
         hashes['.pi/extensions/lat.ts'] = hash;
@@ -371,21 +408,11 @@ async function setupPi(root, latDir, hashes, ask) {
 }
 // ── LLM key setup ───────────────────────────────────────────────────
 async function setupLlmKey(rl) {
-    // Check env var first
-    const envKey = process.env.LAT_LLM_KEY;
-    if (envKey) {
-        console.log('');
-        console.log(chalk.green('Semantic search') + ' — LAT_LLM_KEY is set. Ready.');
-        return;
-    }
-    // Check existing config
-    const config = readConfig();
-    const configPath = getConfigPath();
-    if (config.llm_key) {
+    // Use the centralized key resolution (env var → file → helper → config)
+    const existingKey = getLlmKey();
+    if (existingKey) {
         console.log('');
-        console.log(chalk.green('Semantic search') +
-            ' — LLM key configured in ' +
-            chalk.dim(configPath));
+        console.log(chalk.green('Semantic search') + ' — LLM key found. Ready.');
         return;
     }
     // No key found — explain what semantic search is and prompt
@@ -445,18 +472,39 @@ async function setupLlmKey(rl) {
         console.log('  Saving anyway — you can update it later.');
     }
     // Save to config
-    const updatedConfig = { ...config, llm_key: key };
+    const updatedConfig = { ...readConfig(), llm_key: key };
     writeConfig(updatedConfig);
-    console.log(chalk.green('  Key saved') + ' to ' + chalk.dim(configPath));
+    console.log(chalk.green('  Key saved') + ' to ' + chalk.dim(getConfigPath()));
 }
 // ── Main init flow ───────────────────────────────────────────────────
 export async function initCmd(targetDir) {
+    // Upfront version check — let the user upgrade before proceeding
+    process.stdout.write(chalk.dim('Checking latest version...'));
+    const latest = await fetchLatestVersion();
+    const local = getLocalVersion();
+    if (latest && latest !== local) {
+        console.log(' ' +
+            chalk.yellow('update available:') +
+            ' ' +
+            local +
+            ' → ' +
+            chalk.green(latest) +
+            ' — run ' +
+            chalk.cyan('npm install -g lat.md') +
+            ' to update.');
+        console.log('');
+    }
+    else {
+        console.log(' ' + chalk.green(`latest version is used (${local})`));
+    }
     const root = resolve(targetDir ?? process.cwd());
     const latDir = join(root, 'lat.md');
     const interactive = process.stdin.isTTY ?? false;
-    const rl = interactive
-        ? createInterface({ input: process.stdin, output: process.stdout })
-        : null;
+    // Readline is created AFTER the selectMenu loop below.
+    // selectMenu puts stdin into raw mode with its own 'data' listener;
+    // if readline is already attached it receives those raw keypresses,
+    // corrupting its internal state and causing rl.question() to hang/exit.
+    let rl = null;
     const ask = async (message) => {
         if (!rl)
             return true;
@@ -468,9 +516,21 @@ export async function initCmd(targetDir) {
             console.log(chalk.green('lat.md/') + ' already exists');
         }
         else {
-            if (!(await ask('Create lat.md/ directory?'))) {
-                console.log('Aborted.');
-                return;
+            // No rl yet — selectMenu hasn't run, so use a one-off confirm
+            if (interactive) {
+                const tmpRl = createInterface({
+                    input: process.stdin,
+                    output: process.stdout,
+                });
+                try {
+                    if (!(await confirm(tmpRl, 'Create lat.md/ directory?'))) {
+                        console.log('Aborted.');
+                        return;
+                    }
+                }
+                finally {
+                    tmpRl.close();
+                }
             }
             const templateDir = join(findTemplatesDir(), 'init');
             mkdirSync(latDir, { recursive: true });
@@ -514,6 +574,32 @@ export async function initCmd(targetDir) {
         const useCopilot = selectedAgents.includes('copilot');
         const useCodex = selectedAgents.includes('codex');
         const anySelected = selectedAgents.length > 0;
+        const needsLatCommand = useClaudeCode || usePi || useCursor || useCopilot;
+        // Step 2b: How should agents run lat?
+        let commandStyle = 'local';
+        if (anySelected && needsLatCommand && interactive) {
+            console.log('');
+            const localBin = resolveLatBin();
+            const styleOptions = [
+                { label: 'lat', value: 'global' },
+                { label: localBin, value: 'local' },
+                { label: 'npx lat.md@latest', value: 'npx' },
+            ];
+            const styleChoice = await selectMenu(styleOptions, 'How should agents run lat?', 0);
+            if (!styleChoice) {
+                console.log('Aborted.');
+                return;
+            }
+            commandStyle = styleChoice;
+        }
+        // Now that selectMenu is done, it's safe to create the readline interface.
+        // selectMenu has restored stdin to its original state (paused, non-raw).
+        if (interactive) {
+            rl = createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+        }
         if (!anySelected) {
             console.log('');
             console.log(chalk.dim('No agents selected. You can re-run') +
@@ -533,22 +619,22 @@ export async function initCmd(targetDir) {
         if (useClaudeCode) {
             console.log('');
             console.log(chalk.bold('Setting up Claude Code...'));
-            await setupClaudeCode(root, latDir, template, fileHashes, ask);
+            await setupClaudeCode(root, latDir, template, fileHashes, ask, commandStyle);
         }
         if (usePi) {
             console.log('');
             console.log(chalk.bold('Setting up Pi...'));
-            await setupPi(root, latDir, fileHashes, ask);
+            await setupPi(root, latDir, fileHashes, ask, commandStyle);
         }
         if (useCursor) {
             console.log('');
             console.log(chalk.bold('Setting up Cursor...'));
-            await setupCursor(root, latDir, fileHashes, ask);
+            await setupCursor(root, latDir, fileHashes, ask, commandStyle);
         }
         if (useCopilot) {
             console.log('');
             console.log(chalk.bold('Setting up VS Code Copilot...'));
-            await setupCopilot(root, latDir, fileHashes, ask);
+            await setupCopilot(root, latDir, fileHashes, ask, commandStyle);
         }
         if (useCodex) {
             console.log('');

package/dist/src/version.d.ts

@@ -0,0 +1,7 @@
+/** Walk up from this file to find the nearest package.json version. */
+export declare function getLocalVersion(): string;
+/**
+ * Fetch the latest published version of `lat.md` from the npm registry.
+ * Returns null if the fetch fails or times out (3s).
+ */
+export declare function fetchLatestVersion(): Promise<string | null>;

package/dist/src/version.js

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Walk up from this file to find the nearest package.json version. */
+export function getLocalVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = join(dir, 'package.json');
+        try {
+            return JSON.parse(readFileSync(candidate, 'utf-8')).version;
+        }
+        catch { }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return '0.0.0';
+        dir = parent;
+    }
+}
+/**
+ * Fetch the latest published version of `lat.md` from the npm registry.
+ * Returns null if the fetch fails or times out (3s).
+ */
+export async function fetchLatestVersion() {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3000);
+        const res = await fetch('https://registry.npmjs.org/lat.md/latest', {
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

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