@plebeiantech/lat.md 0.12.3-fork.9 → 0.13.4-fork.2

package/dist/src/cli/index.js

@@ -1,13 +1,8 @@
 #!/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)) {
         throw new InvalidArgumentError('port must be an integer from 1 to 65535');
@@ -18,8 +13,27 @@ function parsePort(value) {
     }
     return port;
 }
-/** Reserve `-- <directory>` for an explicit check target. */
-function splitCheckTarget(args) {
+function parseUiServerBuildTarget(value) {
+    if (value !== 'node' && value !== 'vercel') {
+        throw new InvalidArgumentError('target must be node or vercel');
+    }
+    return value;
+}
+function configureUiRun(command) {
+    return command
+        .option('--logo-text <text>', 'top-left logo text')
+        .option('--no-git', 'disable Git working-tree integration')
+        .option('--port <number>', 'server port (default: 4242; explicit ports are strict)', parsePort);
+}
+function parseSimilarityThreshold(value) {
+    const threshold = Number(value);
+    if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+        throw new InvalidArgumentError('min-similarity must be a number from 0 to 1');
+    }
+    return threshold;
+}
+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];
@@ -42,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 {
@@ -50,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
@@ -97,30 +93,63 @@ 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));
 });
-const ui = program
-    .command('ui')
-    .description('Open lat.md in a local browser')
-    .option('--logo-text <text>', 'top-left logo text')
-    .option('--port <number>', 'server port (default: 4242; explicit ports are strict)', parsePort)
-    .action(async (opts) => {
+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');
-    handleResult(await uiCommand(ctx, { logoText: opts.logoText, port: opts.port }));
+    handleResult(await uiCommand(ctx, {
+        git: opts.git,
+        logoText: opts.logoText,
+        port: opts.port,
+    }));
+}
+const ui = configureUiRun(program.command('ui').description('Run or build the Lat UI')).action(runUi);
+configureUiRun(ui.command('run').description('Run the local Lat UI server')).action(async (opts) => {
+    await runUi(opts);
 });
-ui.command('build')
-    .description('Export lat.md as a static website')
-    .argument('[output]', 'output directory relative to the project', 'lat-ui')
+const uiBuild = ui.command('build').description('Build a deployable Lat UI');
+uiBuild
+    .command('static')
+    .description('Build a fully static, read-only Lat UI')
+    .argument('[output]', 'output directory relative to the project (default: .lat-build/static)', '.lat-build/static')
     .option('--base <path>', 'deployment base path', '/')
+    .option('--force', 'replace an existing output path')
     .option('--logo-text <text>', 'top-left logo text')
     .action(async (output, opts) => {
     const ctx = resolveContext(program.opts());
     const { uiBuildCommand } = await import('./ui-build.js');
     handleResult(await uiBuildCommand(ctx, output, {
         basePath: opts.base,
+        force: opts.force,
+        logoText: opts.logoText ?? ui.opts().logoText,
+    }));
+});
+uiBuild
+    .command('server')
+    .description('Build a static Lat UI with a portable search server')
+    .argument('[output]', 'output directory (default: .lat-build/server for node, .vercel/output for vercel)')
+    .option('--base <path>', 'deployment base path', '/')
+    .option('--force', 'replace an existing output path')
+    .option('--logo-text <text>', 'top-left logo text')
+    .option('--target <target>', 'deployment target: node or vercel', parseUiServerBuildTarget, 'node')
+    .action(async (output, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { uiBuildServerCommand } = await import('./ui-build-server.js');
+    handleResult(await uiBuildServerCommand(ctx, output, {
+        basePath: opts.base,
+        force: opts.force,
         logoText: opts.logoText ?? ui.opts().logoText,
+        target: opts.target,
     }));
 });
 program
@@ -135,18 +164,56 @@ 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
+    .command('external')
+    .description('Manage pinned external source repositories');
+external
+    .command('add')
+    .argument('[handle]', 'stable external source handle')
+    .argument('[repo]', 'canonical HTTPS Git repository')
+    .option('--commit <commit-or-ref>', 'commit, branch, or tag to pin')
+    .option('--prefix <path>', 'repository path prefix')
+    .option('--default-file-extension <extension>', 'extension for external paths that omit one')
+    .option('--strategy <strategy>', 'retrieval strategy: fetch or checkout')
+    .option('--fetch-url <template>', 'raw-file URL template')
+    .action(async (handle, repo, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { externalAddCommand } = await import('@plebeiantech/lat.md-core/cli/external');
+    handleResult(await externalAddCommand(ctx, handle, repo, opts));
+});
+external
+    .command('show')
+    .argument('<source>', 'handle or exact external target')
+    .option('--json', 'emit structured JSON')
+    .action(async (source, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { externalShowCommand } = await import('@plebeiantech/lat.md-core/cli/external');
+    handleResult(await externalShowCommand(ctx, source, !!opts.json));
+});
+external
+    .command('list')
+    .option('--json', 'emit structured JSON')
+    .action(async (opts) => {
+    const ctx = resolveContext(program.opts());
+    const { externalListCommand } = await import('@plebeiantech/lat.md-core/cli/external');
+    handleResult(await externalListCommand(ctx, !!opts.json));
+});
 const check = program
     .command('check')
     .usage('[subcommand] [-- <directory>]')
     .description('Validate markdown, links, code references, and structure')
     .option('--fix', 'generate/update directory index files from frontmatter')
+    .option('--profile', 'show detailed validation timing')
     .action(async (opts) => {
     const ctx = resolveCheckContext(program.opts(), checkTargetArgs.target);
-    const { checkAllCommand } = await import('./check.js');
-    handleResult(await checkAllCommand(ctx, { fix: opts.fix }));
+    const { checkAllCommand } = await import('@plebeiantech/lat.md-core/cli/check');
+    handleResult(await checkAllCommand(ctx, {
+        fix: opts.fix,
+        profile: !!opts.profile,
+    }));
 });
 check
     .command('md')
@@ -154,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
@@ -163,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
@@ -172,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
@@ -187,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
@@ -196,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
@@ -205,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
@@ -214,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) {
@@ -230,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);
@@ -256,14 +323,26 @@ program
 });
 program
     .command('search')
-    .description('Semantic search across lat.md sections')
+    .description('Hybrid search across lat.md sections')
     .argument('[query]', 'search query in plain English')
-    .option('--limit <n>', 'max results', '5')
+    .option('--limit <n>', `max results (default: ${DEFAULT_SEARCH_LIMIT})`, String(DEFAULT_SEARCH_LIMIT))
+    .option('--preview <variant>', 'preview passage, intro, or both', (value) => {
+    if (!['passage', 'intro', 'both'].includes(value))
+        throw new InvalidArgumentError('preview must be passage, intro, or both');
+    return value;
+}, 'passage')
+    .option('--debug', 'show retrieval scores and candidate diagnostics')
+    .option('--min-similarity <score>', `minimum cosine similarity score (default: ${DEFAULT_MIN_SIMILARITY})`, parseSimilarityThreshold)
     .action(async (query, opts) => {
     const ctx = resolveContext(program.opts());
     const { searchCommand, cliProgress } = await import('./search.js');
     const progress = cliProgress(ctx.styler);
-    const result = await searchCommand(ctx, query, { limit: parseInt(opts.limit) }, progress);
+    const result = await searchCommand(ctx, query, {
+        limit: parseInt(opts.limit),
+        debug: opts.debug,
+        minSimilarity: opts.minSimilarity,
+        preview: opts.preview,
+    }, progress);
     handleResult(result);
 });
 program
@@ -310,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')
@@ -329,4 +406,35 @@ program
     const { graphCommand } = await import('./graph.js');
     handleResult(await graphCommand(ctx, opts));
 });
+const wikiCmd = program
+    .command('wiki')
+    .description('Publish Diátaxis documentation to GitHub Wiki');
+wikiCmd
+    .command('build [output]')
+    .description('Build GitHub Wiki pages into a directory')
+    .option('--repo <owner/repo-or-url>', 'GitHub repository to resolve blob links against')
+    .option('--ref <ref>', 'Git revision for source links')
+    .action(async (output, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { wikiBuildCommand } = await import('./wiki.js');
+    try {
+        handleResult(await wikiBuildCommand(ctx, output, opts));
+    }
+    catch (err) {
+        handleResult({ output: err.message, isError: true });
+    }
+});
+wikiCmd
+    .command('publish')
+    .description('Publish GitHub Wiki pages to companion .wiki.git repository')
+    .option('--remote <remote-or-url>', 'Git remote or URL (default: origin)')
+    .option('--repo <owner/repo-or-url>', 'GitHub repository for blob links')
+    .option('--ref <ref>', 'Git revision for source links')
+    .option('--message <message>', 'Commit message for the wiki push')
+    .option('--dry-run', 'Commit locally in the clone without pushing')
+    .action(async (opts) => {
+    const ctx = resolveContext(program.opts());
+    const { wikiPublishCommand } = await import('./wiki.js');
+    handleResult(await wikiPublishCommand(ctx, opts));
+});
 await program.parseAsync(checkTargetArgs.args, { from: 'user' });

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

@@ -0,0 +1,4 @@
+/** Read machine-local checklist defaults without inferring installed agents. */
+export declare function readInitAgents(latDir: string): string[];
+/** Update just the confirmed selection, preserving other YAML and comments. */
+export declare function writeInitAgents(latDir: string, agents: string[]): void;

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

@@ -0,0 +1,36 @@
+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 = 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}`);
+    }
+    if (document.contents !== null && !isMap(document.contents)) {
+        throw new Error(`${path} must be a mapping`);
+    }
+    if (document.has('init') && !isMap(document.get('init', true))) {
+        throw new Error(`${path}: init must be a mapping`);
+    }
+    return { path, document };
+}
+/** Read machine-local checklist defaults without inferring installed agents. */
+export function readInitAgents(latDir) {
+    const { path, document } = readPreferences(latDir);
+    const agents = document.toJS()?.init?.agents;
+    if (agents === undefined)
+        return [];
+    if (!Array.isArray(agents) ||
+        agents.some((agent) => typeof agent !== 'string')) {
+        throw new Error(`${path}: init.agents must be a list of strings`);
+    }
+    return agents;
+}
+/** Update just the confirmed selection, preserving other YAML and comments. */
+export function writeInitAgents(latDir, agents) {
+    const { path, document } = readPreferences(latDir);
+    document.setIn(['init', 'agents'], agents);
+    writeProjectFile(dirname(latDir), path, document.toString());
+}

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

@@ -3,7 +3,8 @@ 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>;
 export {};