llm-wiki-kit 0.2.3 → 0.2.5

package/src/platform.js

@@ -0,0 +1,178 @@
+import { realpathSync } from 'fs';
+import { access, lstat, readFile } from 'fs/promises';
+import { constants as fsConstants } from 'fs';
+import { delimiter, dirname, extname, join, resolve } from 'path';
+import { packageName, packageRoot } from './version.js';
+
+export function runtimePlatform(options = {}) {
+  return options.platform || process.platform;
+}
+
+export function isWindows(options = {}) {
+  return runtimePlatform(options) === 'win32';
+}
+
+export function pathDelimiter(options = {}) {
+  return isWindows(options) ? ';' : delimiter;
+}
+
+export function pathEnvValue(env = process.env, options = {}) {
+  if (!isWindows(options)) return env.PATH || '';
+  const key = Object.keys(env).find((name) => name.toLowerCase() === 'path');
+  return key ? env[key] || '' : env.PATH || '';
+}
+
+export function dataHomeRelative(options = {}) {
+  return isWindows(options)
+    ? join('AppData', 'Local')
+    : join('.local', 'share');
+}
+
+export function cacheHomeRelative(options = {}) {
+  return isWindows(options)
+    ? join('AppData', 'Local', 'llm-wiki-kit', 'cache')
+    : '.cache';
+}
+
+export function commandQuote(value, options = {}) {
+  return isWindows(options)
+    ? `"${String(value).replace(/"/g, '""')}"`
+    : `"${String(value).replace(/(["\\$`])/g, '\\$1')}"`;
+}
+
+export function commandForNodeScript(scriptPath, args = [], options = {}) {
+  if (!isWindows(options)) {
+    return [commandQuote(process.execPath, options), commandQuote(scriptPath, options), ...args].join(' ');
+  }
+  return [process.execPath, scriptPath, ...args]
+    .map((part) => commandQuote(part, options))
+    .join(' ');
+}
+
+export function realpathOrOriginal(path) {
+  if (!path) return null;
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+export function sameResolvedPath(left, right) {
+  const resolvedLeft = realpathOrOriginal(left);
+  const resolvedRight = realpathOrOriginal(right);
+  return Boolean(resolvedLeft && resolvedRight && resolvedLeft === resolvedRight);
+}
+
+export function samePath(left, right) {
+  if (!left || !right) return false;
+  return resolve(left) === resolve(right);
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function windowsExtensions(env = process.env) {
+  return unique((env.PATHEXT || '.COM;.EXE;.BAT;.CMD;.PS1')
+    .split(';')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .flatMap((part) => [part, part.toLowerCase(), part.toUpperCase()]));
+}
+
+function commandCandidates(dir, command, options = {}) {
+  const direct = join(dir, command);
+  if (!isWindows(options) || extname(command)) return [direct];
+  return [direct, ...windowsExtensions(options.env).map((ext) => join(dir, `${command}${ext}`))];
+}
+
+async function commandFileExists(path, options = {}) {
+  try {
+    await access(path, isWindows(options) ? fsConstants.F_OK : fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function commandPaths(command, options = {}) {
+  const env = options.env || process.env;
+  const pathValue = pathEnvValue(env, options);
+  const paths = [];
+  for (const dir of pathValue.split(pathDelimiter(options)).filter(Boolean)) {
+    for (const candidate of commandCandidates(dir, command, { ...options, env })) {
+      if (await commandFileExists(candidate, options)) paths.push(candidate);
+    }
+  }
+  return unique(paths);
+}
+
+function normalizePathText(value) {
+  return String(value || '').replace(/\\/g, '/').toLowerCase();
+}
+
+async function commandShimReferencesRuntime(commandPath, binPath, options = {}) {
+  if (!isWindows(options) || !commandPath) return false;
+  const extension = extname(commandPath).toLowerCase();
+  if (!['', '.cmd', '.bat', '.ps1'].includes(extension)) return false;
+  let content = '';
+  try {
+    content = await readFile(commandPath, 'utf8');
+  } catch {
+    return false;
+  }
+  const normalized = normalizePathText(content);
+  const normalizedBin = normalizePathText(binPath);
+  if (normalized.includes(normalizedBin)) return true;
+  if (options.installSource === 'npm') {
+    const commandDirPackageRoot = join(dirname(commandPath), 'node_modules', packageName());
+    return sameResolvedPath(commandDirPackageRoot, packageRoot) &&
+      normalized.includes(`node_modules/${packageName()}/bin/llm-wiki.js`);
+  }
+  return false;
+}
+
+export async function commandMatchesRuntime(commandPath, binPath, options = {}) {
+  if (!commandPath || !binPath) return false;
+  if (sameResolvedPath(commandPath, binPath)) return true;
+  return commandShimReferencesRuntime(commandPath, binPath, options);
+}
+
+export async function inspectCommandPath(commandPath, binPath, options = {}) {
+  if (!commandPath) {
+    return {
+      path: null,
+      exists: false,
+      symlink: false,
+      target: null,
+      resolved: null,
+      managed: false,
+      matchesRuntime: false,
+    };
+  }
+  try {
+    const stat = await lstat(commandPath);
+    const resolved = realpathOrOriginal(commandPath);
+    const matchesRuntime = await commandMatchesRuntime(commandPath, binPath, options);
+    return {
+      path: commandPath,
+      exists: true,
+      symlink: stat.isSymbolicLink(),
+      target: null,
+      resolved,
+      managed: matchesRuntime,
+      matchesRuntime,
+    };
+  } catch {
+    return {
+      path: commandPath,
+      exists: false,
+      symlink: false,
+      target: null,
+      resolved: null,
+      managed: false,
+      matchesRuntime: false,
+    };
+  }
+}

package/src/projects.js

@@ -58,12 +58,17 @@ async function looksLikeProjectRoot(root) {
 export async function discoverProjectRoots(searchRoot, options = {}) {
   const root = resolve(searchRoot || process.cwd());
   const maxDirs = options.maxDirs || 5000;
+  const progressEvery = options.progressEvery || 1000;
+  const onProgress = typeof options.onProgress === 'function' ? options.onProgress : null;
   const roots = new Set();
   let seen = 0;
 
   async function walk(dir) {
     if (seen >= maxDirs) return;
     seen += 1;
+    if (onProgress && seen % progressEvery === 0) {
+      onProgress(`scanned ${seen}/${maxDirs} directories while discovering projects`);
+    }
 
     if (await looksLikeProjectRoot(dir)) {
       roots.add(dir);
@@ -91,6 +96,9 @@ export async function discoverProjectRoots(searchRoot, options = {}) {
   }
 
   await walk(root);
+  if (onProgress) {
+    onProgress(`project discovery scanned ${seen} director${seen === 1 ? 'y' : 'ies'}; found ${roots.size}`);
+  }
   return [...roots].sort();
 }
 

package/src/update.js

@@ -1,4 +1,4 @@
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import { join, resolve } from 'path';
 import { exists } from './fs-utils.js';
 import { appendWikiLog } from './project.js';
@@ -7,18 +7,101 @@ import { applyProjectTemplateUpdate, inspectProjectState } from './project-state
 import { knownProjectRoots, recordProject } from './projects.js';
 import { binPath, detectInstallSource, packageName, runtimeVersion } from './version.js';
 
-function runCommand(command, args, options = {}) {
-  const result = spawnSync(command, args, {
-    encoding: 'utf8',
-    env: options.env || process.env,
-    timeout: options.timeout || 120000,
+function commandLine(command, args) {
+  return [command, ...args].join(' ');
+}
+
+function elapsedMs(startedAt) {
+  return Date.now() - startedAt;
+}
+
+function progress(options, message) {
+  if (typeof options.onProgress === 'function') options.onProgress(message);
+}
+
+async function runCommand(command, args, options = {}) {
+  const timeout = options.timeout || 120000;
+  const killGraceMs = options.killGraceMs || 2000;
+  const label = options.label || commandLine(command, args);
+  const startedAt = Date.now();
+  const detached = process.platform !== 'win32';
+  let stdout = '';
+  let stderr = '';
+  let settled = false;
+  let timedOut = false;
+  let timeoutId = null;
+  let killId = null;
+
+  progress(options, `starting ${label}`);
+
+  return new Promise((resolveResult) => {
+    let child;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutId);
+      clearTimeout(killId);
+      progress(options, `${label} finished in ${elapsedMs(startedAt)}ms`);
+      resolveResult({
+        ...result,
+        stdout,
+        stderr,
+        elapsedMs: elapsedMs(startedAt),
+        timedOut,
+      });
+    };
+    const killChild = (signal) => {
+      if (!child?.pid) return;
+      try {
+        if (detached) {
+          process.kill(-child.pid, signal);
+        } else {
+          child.kill(signal);
+        }
+      } catch {
+        // The process may have already exited.
+      }
+    };
+
+    try {
+      child = spawn(command, args, {
+        detached,
+        env: options.env || process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      finish({ status: null, signal: null, error });
+      return;
+    }
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', (error) => {
+      finish({ status: null, signal: null, error });
+    });
+    child.on('close', (status, signal) => {
+      const error = timedOut
+        ? Object.assign(new Error(`${label} timed out after ${timeout}ms`), { code: 'ETIMEDOUT' })
+        : null;
+      finish({ status, signal, error });
+    });
+
+    timeoutId = setTimeout(() => {
+      timedOut = true;
+      progress(options, `${label} exceeded ${timeout}ms; terminating`);
+      killChild('SIGTERM');
+      killId = setTimeout(() => {
+        progress(options, `${label} did not exit after SIGTERM; killing`);
+        killChild('SIGKILL');
+      }, killGraceMs);
+    }, timeout);
   });
-  return {
-    status: result.status,
-    stdout: result.stdout || '',
-    stderr: result.stderr || '',
-    error: result.error || null,
-  };
 }
 
 function npmCommand() {
@@ -31,7 +114,11 @@ function binCommand() {
 
 function assertCommandOk(result, label) {
   if (result.status === 0 && !result.error) return;
-  const detail = result.stderr.trim() || result.stdout.trim() || result.error?.message || 'unknown error';
+  const detail = result.stderr.trim() ||
+    result.stdout.trim() ||
+    result.error?.message ||
+    (result.signal ? `signal ${result.signal}` : '') ||
+    'unknown error';
   throw new Error(`${label} failed: ${detail}`);
 }
 
@@ -45,7 +132,13 @@ function shouldUpdateAllProjects(options = {}) {
 
 async function projectRootsForUpdate(workspace, options = {}) {
   if (!shouldUpdateAllProjects(options)) return [workspace];
-  const roots = await knownProjectRoots({ workspace });
+  progress(options, `discovering project roots under ${workspace}`);
+  const roots = await knownProjectRoots({
+    workspace,
+    maxDirs: options.maxDirs,
+    onProgress: options.onProgress,
+  });
+  progress(options, `discovered ${roots.length} project root(s)`);
   return roots.length > 0 ? roots : [workspace];
 }
 
@@ -97,7 +190,9 @@ export function compareVersions(a, b) {
 export async function checkForUpdate(options = {}) {
   const target = options.to || 'latest';
   const installedVersion = runtimeVersion();
-  const result = runCommand(npmCommand(), ['view', `${packageName()}@${target}`, 'version'], {
+  const result = await runCommand(npmCommand(), ['view', `${packageName()}@${target}`, 'version'], {
+    ...options,
+    label: 'npm view',
     timeout: options.timeout || 30000,
   });
   assertCommandOk(result, 'npm view');
@@ -120,9 +215,16 @@ export async function postUpdate(options = {}) {
   });
 
   if (options.all) {
-    const workspaces = await knownProjectRoots({ workspace });
+    progress(options, `discovering project roots under ${workspace}`);
+    const workspaces = await knownProjectRoots({
+      workspace,
+      maxDirs: options.maxDirs,
+      onProgress: options.onProgress,
+    });
+    progress(options, `post-update will inspect ${workspaces.length} project root(s)`);
     const projects = [];
     for (const projectRoot of workspaces) {
+      progress(options, `applying managed templates to ${projectRoot}`);
       const projectResult = await applyTemplatesToProject(projectRoot, options);
       if (!options.noProject && await hasProjectWiki(projectRoot)) {
         await appendWikiLog(projectRoot, `llm-wiki-kit post-update applied runtime ${runtimeVersion()}; changed templates: ${projectResult.changed.length}`);
@@ -194,7 +296,9 @@ export async function update(options = {}) {
   const target = options.to || 'latest';
   const shouldRunNpmInstall = check.updateAvailable;
   const installResult = shouldRunNpmInstall
-    ? runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
+    ? await runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
+      ...options,
+      label: 'npm install -g',
       timeout: options.timeout || 120000,
     })
     : {
@@ -210,7 +314,13 @@ export async function update(options = {}) {
   if (options.noProject) postArgs.push('--no-project');
   if (options.codex === false) postArgs.push('--no-codex');
   if (options.claude === false) postArgs.push('--no-claude');
-  const postResult = runCommand(process.execPath, postArgs, {
+  const postResult = await runCommand(process.execPath, postArgs, {
+    ...options,
+    env: {
+      ...process.env,
+      LLM_WIKI_KIT_PROGRESS: process.env.LLM_WIKI_KIT_PROGRESS || '1',
+    },
+    label: 'post-update',
     timeout: options.timeout || 120000,
   });
   assertCommandOk(postResult, 'post-update');