@plebeiantech/lat.md 0.12.3-fork.17 → 0.12.3-fork.20

package/README.md

@@ -139,7 +139,7 @@ To use higher-quality hosted embeddings instead, provide an OpenAI (`sk-...`) or
 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 — power users can set `llm_key` manually. Run `lat config` to print its location.
+4. Config file — power users can set `llm_key` manually. Run `lat paths --config` to print its location. Run `lat paths` to see cache and other storage paths with their purposes.
 
 Switch backends any time with `lat reindex` (`--local` to force the offline model, `--remote` to use your key).
 

package/dist/src/cli/agent-invocation.d.ts

@@ -0,0 +1,6 @@
+export interface AgentInvocation {
+    command: string;
+    args: string[];
+}
+/** Generated tools pass user input as argv, never as shell program text. */
+export declare function agentInvocation(style: 'local' | 'global' | 'npx', local: AgentInvocation, platform?: NodeJS.Platform): AgentInvocation;

package/dist/src/cli/agent-invocation.js

@@ -0,0 +1,23 @@
+import { existsSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+/** Generated tools pass user input as argv, never as shell program text. */
+export function agentInvocation(style, local, platform = process.platform) {
+    if (style === 'local')
+        return local;
+    // Windows npm command shims require cmd.exe. Use the installed entry point
+    // directly instead, retaining the Node launcher and its loader arguments.
+    if (style === 'global')
+        return platform === 'win32' ? local : { command: 'lat', args: [] };
+    if (platform !== 'win32')
+        return { command: 'npx', args: ['lat.md@latest'] };
+    const directories = [
+        dirname(process.execPath),
+        ...(process.env.PATH ?? '').split(delimiter),
+    ];
+    for (const directory of directories) {
+        const cli = join(directory, 'node_modules', 'npm', 'bin', 'npx-cli.js');
+        if (existsSync(cli))
+            return { command: process.execPath, args: [cli, 'lat.md@latest'] };
+    }
+    throw new Error('Cannot find the npm npx entry point. Choose the local command style or install npm.');
+}

package/dist/src/cli/fork-instructions.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { styleText } from 'node:util';
-import { contentHash, readFileHash } from '../init-version.js';
+import { contentHash, readFileHash, } from '@plebeiantech/lat.md-core/init-version';
 import { findTemplatesDir } from './templates.js';
 /**
  * The fork's own instruction channel into a consumer project.

package/dist/src/cli/fork-scaffold.js

@@ -2,8 +2,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { styleText } from 'node:util';
 import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
-import { parseFrontmatter } from '../lattice.js';
-import { DIATAXIS_MODES, MODE_DIRS, checkMode, indexNameFor, } from './check-mode.js';
+import { parseFrontmatter } from '@plebeiantech/lat.md-core/lattice';
+import { DIATAXIS_MODES, MODE_DIRS, checkMode, indexNameFor, } from '@plebeiantech/lat.md-core/cli/check-mode';
 /**
  * Give a freshly created `lat.md/` the Diátaxis shape, and turn the gate on.
  *

package/dist/src/cli/graph.d.ts

@@ -1,4 +1,4 @@
-import type { CmdContext, CmdResult } from '../context.js';
+import type { CmdContext, CmdResult } from '@plebeiantech/lat.md-core/context';
 export type GraphOptions = {
     format?: string;
     at?: string;

package/dist/src/cli/hook.js

@@ -1,18 +1,18 @@
 import { execSync } from 'node:child_process';
 import { lstatSync, readFileSync } from 'node:fs';
 import { dirname, extname, join } from 'node:path';
-import { findLatticeDir } from '../project-discovery.js';
-import { findSections } from '../lattice-model.js';
-import { plainStyler } from '../context.js';
-import { expandPrompt } from './expand.js';
+import { findLatticeDir } from '@plebeiantech/lat.md-core/project-discovery';
+import { findSections } from '@plebeiantech/lat.md-core/lattice-model';
+import { plainStyler, } from '@plebeiantech/lat.md-core/context';
+import { expandPrompt } from '@plebeiantech/lat.md-core/cli/expand';
 import { runSearch } from './search.js';
 import { DEFAULT_SEARCH_LIMIT } from '../search/search.js';
-import { getSection, formatSectionOutput } from './section.js';
-import { checkMd, checkCodeRefs, checkIndex, checkSections } from './check.js';
-import { CheckRunContext } from './check-context.js';
-import { isSourceFileExtension } from '../source-formats.js';
-import { commandProjectAnalysis } from '../project-analysis.js';
-import { checkMode } from './check-mode.js';
+import { getSection, formatSectionOutput, } from '@plebeiantech/lat.md-core/cli/section';
+import { checkMd, checkCodeRefs, checkIndex, checkSections, } from '@plebeiantech/lat.md-core/cli/check';
+import { CheckRunContext } from '@plebeiantech/lat.md-core/cli/check-context';
+import { isSourceFileExtension } from '@plebeiantech/lat.md-core/source-formats';
+import { commandProjectAnalysis } from '@plebeiantech/lat.md-core/project-analysis';
+import { checkMode } from '@plebeiantech/lat.md-core/cli/check-mode';
 import { federateTags, taggedDocsForFiles } from '../knowledge/index.js';
 import { loadSessionMarkers, saveSessionMarkers, } from '../knowledge/session.js';
 import { computeCommentReminder, } from './comment-reminder.js';
@@ -115,7 +115,7 @@ async function handleUserPromptSubmit() {
         // If we can't parse stdin, still emit the reminder
     }
     const parts = [];
-    parts.push("Before starting work, run `lat search` with one or more queries describing the user's intent.", 'ALWAYS do this, even when the task seems straightforward — search results may reveal critical design details, protocols, or constraints.', 'Use `lat section` to read the full content of relevant matches.', 'Do not read files, write code, or run commands until you have searched.', '', 'Remember: `lat.md/` must stay in sync with meaningful codebase state. If you change behavior, architecture, tests, or planned work, update the relevant current-state sections and run `lat check` before finishing. Do not use `lat.md/` as a journal/changelog or add notes for insignificant details.');
+    parts.push("Before starting work, run `lat search` with one or more queries describing the user's intent.", 'ALWAYS do this, even when the task seems straightforward — search results may reveal critical design details, protocols, or constraints.', 'Use `lat section` to read the full content of relevant matches.', 'Do not read files, write code, or run commands until you have searched.', '', 'Remember: `lat.md/` must stay in sync with meaningful codebase state. If you change implemented behavior, architecture, or tests, update the relevant current-state sections and run `lat check` before finishing. Plans may be drafted in `lat.md/` alongside implementation, with the intent that by commit time they describe what was implemented. Otherwise, keep proposals, hypothetical designs, and future work outside `lat.md/` unless the user explicitly requests them there. Do not use `lat.md/` as a journal/changelog or add notes for insignificant details.');
     const latDir = findLatticeDir();
     if (latDir && userPrompt) {
         const ctx = makeHookCtx(latDir);

package/dist/src/cli/index.js

@@ -1,13 +1,7 @@
 #!/usr/bin/env node
-// Suppress deprecation warnings from transitive dependencies unless --verbose
-if (!process.argv.includes('--verbose')) {
-    process.noDeprecation = true;
-}
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { Command, InvalidArgumentError } from 'commander';
-import { resolveCheckContext, resolveContext } from './context.js';
+import { handleResult, packageVersion, } from '@plebeiantech/lat.md-core/cli';
+import { resolveContext } from '@plebeiantech/lat.md-core/cli/context';
 import { DEFAULT_SEARCH_LIMIT, DEFAULT_MIN_SIMILARITY, } from '../search/search.js';
 function parsePort(value) {
     if (!/^\d+$/.test(value)) {
@@ -38,8 +32,8 @@ function parseSimilarityThreshold(value) {
     }
     return threshold;
 }
-/** Reserve `-- <directory>` for an explicit check target. */
-function splitCheckTarget(args) {
+import { resolveCheckContext } from '@plebeiantech/lat.md-core/cli/context';
+function splitCheckTarget(args, name) {
     let commandIndex = -1;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -62,7 +56,7 @@ function splitCheckTarget(args) {
         return { args };
     const targets = args.slice(separatorIndex + 1);
     if (targets.length !== 1 || targets[0] === '') {
-        console.error('error: `lat check --` expects exactly one directory after `--`');
+        console.error(`error: \`${name} check --\` expects exactly one directory after \`--\``);
         process.exit(1);
     }
     return {
@@ -70,45 +64,27 @@ function splitCheckTarget(args) {
         target: targets[0],
     };
 }
-const checkTargetArgs = splitCheckTarget(process.argv.slice(2));
-function findPackageJson() {
-    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;
-    }
-}
-function handleResult(result) {
-    if (result.isError) {
-        console.error(result.output);
-        process.exit(1);
-    }
-    if (result.output)
-        console.log(result.output);
-}
-const version = findPackageJson();
+const checkTargetArgs = splitCheckTarget(process.argv.slice(2), 'lat');
 const program = new Command();
 program
     .name('lat')
+    .version(packageVersion(import.meta.url))
     .description('Anchor source code to high-level concepts defined in markdown')
-    .version(version)
     .option('--dir <path>', 'project root to look for lat.md in (default: cwd)')
     .option('--no-color', 'disable color output')
     .option('--verbose', 'show deprecation warnings and extra diagnostics');
+if (checkTargetArgs.args.includes('--verbose'))
+    process.noDeprecation = false;
+else
+    process.noDeprecation = true;
+const args = checkTargetArgs.args;
 program
     .command('locate')
-    .description('Find sections by id')
-    .argument('<query>', 'section id to search for')
+    .description('Find section(s) by name or text')
+    .argument('<query>', 'name or text to search for')
     .action(async (query) => {
     const ctx = resolveContext(program.opts());
-    const { locateCommand } = await import('./locate.js');
+    const { locateCommand } = await import('@plebeiantech/lat.md-core/cli/locate');
     handleResult(await locateCommand(ctx, query));
 });
 program
@@ -117,9 +93,17 @@ program
     .argument('<query>', 'section id to look up')
     .action(async (query) => {
     const ctx = resolveContext(program.opts());
-    const { sectionCommand } = await import('./section.js');
+    const { sectionCommand } = await import('@plebeiantech/lat.md-core/cli/section');
     handleResult(await sectionCommand(ctx, query));
 });
+program
+    .command('paths')
+    .description('Show configuration, cache, and temporary file locations')
+    .option('--config', 'show only the user configuration file path')
+    .action(async (options) => {
+    const { pathsCommand } = await import('@plebeiantech/lat.md-core/cli/paths');
+    console.log(pathsCommand({ ...program.opts(), ...options, search: true }));
+});
 async function runUi(opts) {
     const ctx = resolveContext(program.opts());
     const { uiCommand } = await import('./ui.js');
@@ -180,7 +164,7 @@ program
         process.exit(1);
     }
     const ctx = resolveContext(program.opts());
-    const { refsCommand } = await import('./refs.js');
+    const { refsCommand } = await import('@plebeiantech/lat.md-core/cli/refs');
     handleResult(await refsCommand(ctx, query, scope));
 });
 const external = program
@@ -197,7 +181,7 @@ external
     .option('--fetch-url <template>', 'raw-file URL template')
     .action(async (handle, repo, opts) => {
     const ctx = resolveContext(program.opts());
-    const { externalAddCommand } = await import('./external.js');
+    const { externalAddCommand } = await import('@plebeiantech/lat.md-core/cli/external');
     handleResult(await externalAddCommand(ctx, handle, repo, opts));
 });
 external
@@ -206,7 +190,7 @@ external
     .option('--json', 'emit structured JSON')
     .action(async (source, opts) => {
     const ctx = resolveContext(program.opts());
-    const { externalShowCommand } = await import('./external.js');
+    const { externalShowCommand } = await import('@plebeiantech/lat.md-core/cli/external');
     handleResult(await externalShowCommand(ctx, source, !!opts.json));
 });
 external
@@ -214,7 +198,7 @@ external
     .option('--json', 'emit structured JSON')
     .action(async (opts) => {
     const ctx = resolveContext(program.opts());
-    const { externalListCommand } = await import('./external.js');
+    const { externalListCommand } = await import('@plebeiantech/lat.md-core/cli/external');
     handleResult(await externalListCommand(ctx, !!opts.json));
 });
 const check = program
@@ -225,7 +209,7 @@ const check = program
     .option('--profile', 'show detailed validation timing')
     .action(async (opts) => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkAllCommand } = await import('./check.js');
+    const { checkAllCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkAllCommand(ctx, {
         fix: opts.fix,
         profile: !!opts.profile,
@@ -237,7 +221,7 @@ check
     .description('Validate wiki links in markdown files')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkMdCommand } = await import('./check.js');
+    const { checkMdCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkMdCommand(ctx));
 });
 check
@@ -246,7 +230,7 @@ check
     .description('Validate relative markdown links')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkLinksCommand } = await import('./check.js');
+    const { checkLinksCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkLinksCommand(ctx));
 });
 check
@@ -255,7 +239,7 @@ check
     .description('Validate @lat code references and coverage')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkCodeRefsCommand } = await import('./check.js');
+    const { checkCodeRefsCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkCodeRefsCommand(ctx));
 });
 check
@@ -270,7 +254,7 @@ check
     // read it off `check.opts()` instead.
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkIndexCommand } = await import('./check.js');
+    const { checkIndexCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkIndexCommand(ctx, { fix: check.opts().fix }));
 });
 check
@@ -279,7 +263,7 @@ check
     .description('Validate section leading paragraphs')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkSectionsCommand } = await import('./check.js');
+    const { checkSectionsCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkSectionsCommand(ctx));
 });
 check
@@ -288,7 +272,7 @@ check
     .description('Validate Diátaxis modes and document shape')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkModeCommand } = await import('./check.js');
+    const { checkModeCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkModeCommand(ctx));
 });
 check
@@ -297,7 +281,7 @@ check
     .description('Validate provenance status and detect stale reviews')
     .action(async () => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkStatusCommand } = await import('./check.js');
+    const { checkStatusCommand } = await import('@plebeiantech/lat.md-core/cli/check');
     handleResult(await checkStatusCommand(ctx));
 });
 async function runExpand(text, opts) {
@@ -313,7 +297,7 @@ async function runExpand(text, opts) {
         process.exit(1);
     }
     const ctx = resolveContext(program.opts());
-    const { expandCommand } = await import('./expand.js');
+    const { expandCommand } = await import('@plebeiantech/lat.md-core/cli/expand');
     const result = await expandCommand(ctx, text);
     if (result.isError) {
         console.error(result.output);
@@ -405,13 +389,11 @@ program
     await startMcpServer();
 });
 program
-    .command('config')
-    .description('Show configuration file path')
+    .command('config', { hidden: true })
+    .description('Alias for paths --config')
     .action(async () => {
-    const { getConfigPath } = await import('../config.js');
-    const configPath = getConfigPath();
-    const exists = existsSync(configPath);
-    console.log(`Config file: ${configPath}${exists ? '' : ' (not found)'}`);
+    const { pathsCommand } = await import('@plebeiantech/lat.md-core/cli/paths');
+    console.log(pathsCommand({ config: true }));
 });
 program
     .command('graph')

package/dist/src/cli/init-preferences.js

@@ -1,8 +1,9 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { projectWritePath, writeProjectFile, } from '@plebeiantech/lat.md-core/project-write';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { isMap, parseDocument } from 'yaml';
 function readPreferences(latDir) {
-    const path = join(latDir, 'config.local.yaml');
+    const path = projectWritePath(dirname(latDir), join(latDir, 'config.local.yaml'));
     const document = parseDocument(existsSync(path) ? readFileSync(path, 'utf8') : '');
     if (document.errors.length > 0) {
         throw new Error(`Cannot parse ${path}: ${document.errors[0].message}`);
@@ -31,5 +32,5 @@ export function readInitAgents(latDir) {
 export function writeInitAgents(latDir, agents) {
     const { path, document } = readPreferences(latDir);
     document.setIn(['init', 'agents'], agents);
-    writeFileSync(path, document.toString());
+    writeProjectFile(dirname(latDir), path, document.toString());
 }

package/dist/src/cli/init.d.ts

@@ -3,7 +3,7 @@ type LatCommandStyle = 'global' | 'local' | 'npx';
  * Remove all lat-owned hook entries from settings, then add fresh ones.
  * Preserves any non-lat hooks the user may have configured.
  */
-export declare function syncLatHooks(settingsPath: string, style: LatCommandStyle, agent?: 'claude' | 'codex'): void;
+export declare function syncLatHooks(settingsPath: string, style: LatCommandStyle, agent?: 'claude' | 'codex', root?: string): void;
 export declare function readLogo(): string;
 export declare function ensureLatLocalConfigIgnored(latDir: string): void;
 export declare function initCmd(targetDir?: string): Promise<void>;