llm-wiki-kit 0.1.1 → 0.1.3

package/README.md

@@ -84,7 +84,9 @@ If you need to think about saving every answer manually, the setup has failed.
 llm-wiki install --workspace /path/to/project --profile standard
 llm-wiki doctor
 llm-wiki status --workspace /path/to/project
+llm-wiki projects --workspace /path/to/search-root
 llm-wiki update --check --workspace /path/to/project
+llm-wiki update --all --workspace /path/to/search-root
 llm-wiki update --dry-run --workspace /path/to/project
 llm-wiki update --workspace /path/to/project
 llm-wiki uninstall
@@ -96,6 +98,10 @@ llm-wiki uninstall
 
 `llm-wiki update` upgrades the global npm package, reinstalls the hook entries, and patches only managed project files such as the marked `AGENTS.md` policy block and generated `llm-wiki/AGENTS.md`/procedure files. Existing wiki content is not overwritten.
 
+`llm-wiki projects --workspace /apps` lists project roots that already have `llm-wiki-kit` state and shows the update commands to run. `llm-wiki update --all --workspace /apps` updates the global runtime once, then reapplies managed templates across every discovered project root under `/apps`.
+
+After a plain `npm install -g llm-wiki-kit@latest`, installed hooks point at the same global binary path. The next `SessionStart`/`InstructionsLoaded` hook automatically reapplies safe managed template updates for the active project root. This only patches generated/managed files and does not overwrite wiki content.
+
 Real `update --check` and `update` require the package to exist in the npm registry. Before publication, use local tarball installs for smoke testing and fake npm in automated tests.
 
 The hook subcommands are internal runtime targets:

package/docs/operations.md

@@ -67,7 +67,9 @@ Do not delete a project `llm-wiki/` tree to reinstall the runtime. `llm-wiki uni
 
 ```bash
 llm-wiki status --workspace /path/to/project
+llm-wiki projects --workspace /path/to/search-root
 llm-wiki update --check --workspace /path/to/project
+llm-wiki update --all --workspace /path/to/search-root
 llm-wiki update --dry-run --workspace /path/to/project
 llm-wiki update --workspace /path/to/project
 ```
@@ -81,6 +83,8 @@ llm-wiki update --workspace /path/to/project
 
 `update --check` is online and asks npm whether a newer package version exists.
 
+`projects --workspace <search-root>` lists discovered project roots that have `llm-wiki/.kit-state.json`, reports whether their managed templates are current, and prints the update commands for the search root.
+
 `update` applies changes explicitly only when the user runs it:
 
 - runs `npm install -g llm-wiki-kit@<target>`
@@ -89,6 +93,10 @@ llm-wiki update --workspace /path/to/project
 - patches only managed project files
 - backs up changed files under `~/.local/share/llm-wiki-kit/backups/`
 
+`update --all --workspace <search-root>` performs the npm runtime update once, then reapplies managed templates to every discovered project root under the search root.
+
+After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep pointing at the global package path. On the next `SessionStart` or `InstructionsLoaded`, the runtime automatically reapplies safe managed template updates for the active project root.
+
 Managed project files are conservative:
 
 - root `AGENTS.md` is patched only inside the `llm-wiki-kit` marker block

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
   "type": "module",
   "files": [

package/src/cli.js

@@ -2,6 +2,8 @@ import { resolve } from 'path';
 import { handleHook } from './hook.js';
 import { install, status, uninstall } from './install.js';
 import { bootstrapProject } from './project.js';
+import { inspectProjectState } from './project-state.js';
+import { commandForProject, knownProjectRoots } from './projects.js';
 import { formatDoctor, runDoctor } from './doctor.js';
 import { migrate } from './migrate.js';
 import { postUpdate, update } from './update.js';
@@ -29,6 +31,8 @@ function parseOptions(args) {
       options.dryRun = true;
     } else if (arg === '--replace-hooks') {
       options.replaceHooks = true;
+    } else if (arg === '--all') {
+      options.all = true;
     } else if (arg === '--json') {
       options.json = true;
     } else {
@@ -59,6 +63,7 @@ Usage:
   llm-wiki install --workspace /apps [--profile standard]
   llm-wiki update --workspace <project> [--check|--dry-run|--to <version-or-tag>]
   llm-wiki doctor
+  llm-wiki projects --workspace /apps
   llm-wiki status
   llm-wiki uninstall
   llm-wiki hook codex <EventName>
@@ -92,6 +97,12 @@ Usage:
     return;
   }
 
+  if (command === 'projects') {
+    const result = await listProjects(options);
+    printJsonOrText(result, options, formatProjects);
+    return;
+  }
+
   if (command === 'update') {
     printJsonOrText(await update(options), options, formatUpdate);
     return;
@@ -132,6 +143,28 @@ Usage:
   throw new Error(`unknown command: ${command}`);
 }
 
+async function listProjects(options) {
+  const workspace = resolve(options.workspace || process.cwd());
+  const roots = await knownProjectRoots({ workspace });
+  const projects = [];
+  for (const root of roots) {
+    let state = null;
+    let error = null;
+    try {
+      state = await inspectProjectState(root);
+    } catch (err) {
+      error = err.message;
+    }
+    projects.push({
+      workspace: root,
+      runtime: state?.lastRuntimeVersionApplied || 'unknown',
+      current: Boolean(state?.runtimeUpToDateWithProject && state?.managedFilesCurrent),
+      error,
+    });
+  }
+  return { workspace, projects };
+}
+
 function formatStatus(value) {
   const project = value.project || {};
   return [
@@ -171,10 +204,21 @@ function formatUpdate(value) {
     `- workspace: ${value.workspace}`,
     `- before: ${value.before}`,
     `- target: ${value.target}`,
+    ...(value.projects ? [`- projects updated: ${value.projects.length}`] : []),
   ].join('\n');
 }
 
 function formatPostUpdate(value) {
+  if (Array.isArray(value.projects)) {
+    return [
+      'llm-wiki-kit post-update complete',
+      `- workspace: ${value.workspace}`,
+      `- runtime: ${value.runtimeVersion}`,
+      `- changed hooks: ${value.install.changed.length ? value.install.changed.join(', ') : 'none'}`,
+      `- projects updated: ${value.projects.length}`,
+      ...value.projects.map((item) => `  - ${item.workspace}: changed ${item.project?.changed?.length || 0}, skipped ${item.project?.skipped?.length || 0}`),
+    ].join('\n');
+  }
   return [
     'llm-wiki-kit post-update complete',
     `- workspace: ${value.workspace}`,
@@ -183,3 +227,21 @@ function formatPostUpdate(value) {
     `- changed project templates: ${value.project?.changed?.length || 0}`,
   ].join('\n');
 }
+
+function formatProjects(value) {
+  const lines = [
+    'llm-wiki-kit projects',
+    `- search root: ${value.workspace}`,
+  ];
+  if (value.projects.length === 0) {
+    lines.push('- no applied project roots found');
+  } else {
+    for (const project of value.projects) {
+      const status = project.error ? `error: ${project.error}` : project.current ? 'current' : `needs update (applied ${project.runtime})`;
+      lines.push(`- ${project.workspace}: ${status}`);
+    }
+  }
+  lines.push('', 'To update every listed project root:', commandForProject('update --all', value.workspace));
+  lines.push('To reapply templates without npm install:', commandForProject('post-update --all', value.workspace));
+  return lines.join('\n');
+}

package/src/fs-utils.js

@@ -12,7 +12,7 @@ import {
   unlink,
   writeFile,
 } from 'fs/promises';
-import { dirname, join, parse, resolve } from 'path';
+import { basename, dirname, join, parse, resolve } from 'path';
 import { PROJECT_MARKERS } from './constants.js';
 import { normalizeForStorage } from './redaction.js';
 
@@ -112,8 +112,27 @@ export async function safeSymlink(target, linkPath) {
   await symlink(target, linkPath);
 }
 
+async function containingWikiParent(path) {
+  let current = path;
+  while (true) {
+    if (
+      basename(current) === 'llm-wiki' &&
+      await exists(join(current, 'wiki', 'index.md')) &&
+      await exists(join(current, 'raw')) &&
+      await exists(join(current, 'outputs'))
+    ) {
+      return dirname(current);
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
 export async function findProjectRoot(startDir = process.cwd()) {
   let current = resolve(startDir);
+  const wikiParent = await containingWikiParent(current);
+  if (wikiParent) return wikiParent;
   while (true) {
     for (const marker of PROJECT_MARKERS) {
       if (await exists(join(current, marker))) return current;

package/src/hook.js

@@ -1,5 +1,7 @@
 import { findProjectRoot } from './fs-utils.js';
 import { bootstrapProject, appendContextNote, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
+import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
+import { recordProject } from './projects.js';
 import { summarizeForStorage } from './redaction.js';
 import { buildEntryFromState, rememberQuestion, rememberTool } from './state.js';
 
@@ -37,6 +39,15 @@ function contextOutput(eventName, context) {
   };
 }
 
+async function autoUpdateManagedProject(projectRoot, eventName) {
+  if (process.env.LLM_WIKI_KIT_AUTO_PROJECT_UPDATE === '0') return;
+  if (eventName !== 'SessionStart' && eventName !== 'InstructionsLoaded') return;
+  const state = await inspectProjectState(projectRoot);
+  if (state.runtimeUpToDateWithProject && state.managedFilesCurrent) return;
+  const result = await applyProjectTemplateUpdate(projectRoot);
+  await appendWikiLog(projectRoot, `llm-wiki-kit auto-update applied runtime ${result.runtimeVersion}; changed templates: ${result.changed.length}; skipped templates: ${result.skipped.length}`);
+}
+
 export async function handleHook(provider, explicitEvent) {
   const payload = await readStdinJson();
   payload.__provider = provider;
@@ -44,6 +55,8 @@ export async function handleHook(provider, explicitEvent) {
   const cwd = payload.cwd || process.cwd();
   const projectRoot = await findProjectRoot(cwd);
   await bootstrapProject(projectRoot);
+  await recordProject(projectRoot, 'hook').catch(() => {});
+  await autoUpdateManagedProject(projectRoot, eventName).catch(() => {});
   await appendSessionEnvelope(projectRoot, eventName, payload).catch(() => {});
 
   if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded') {

package/src/install.js

@@ -4,6 +4,7 @@ import { CLAUDE_EVENTS, CODEX_EVENTS, KIT_NAME } from './constants.js';
 import { backupFile, ensureDir, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
 import { inspectProjectState } from './project-state.js';
 import { bootstrapProject } from './project.js';
+import { recordProject } from './projects.js';
 import { binPath, detectInstallSource, packageRoot, runtimeVersion } from './version.js';
 
 function shellQuote(value) {
@@ -59,6 +60,7 @@ export async function install(options = {}) {
   }
   await safeSymlink(binPath, localBinPath);
   await bootstrapProject(workspace, { profile: options.profile || 'standard', recordState: true });
+  await recordProject(workspace, 'install');
 
   const codexHooksPath = join(homeDir(), '.codex', 'hooks.json');
   const claudeSettingsPath = join(homeDir(), '.claude', 'settings.json');

package/src/projects.js

@@ -0,0 +1,104 @@
+import { readdir } from 'fs/promises';
+import { join, resolve } from 'path';
+import { exists, isDirectory, kitDataDir, readJson, writeJson } from './fs-utils.js';
+
+const REGISTRY_SCHEMA_VERSION = 1;
+const PROJECTS_FILE = 'projects.json';
+const SKIP_DIRS = new Set(['.cache', '.git', 'node_modules', 'llm-wiki']);
+
+function registryPath() {
+  return join(kitDataDir(), PROJECTS_FILE);
+}
+
+function emptyRegistry() {
+  return {
+    schemaVersion: REGISTRY_SCHEMA_VERSION,
+    projects: {},
+  };
+}
+
+function normalizeRegistry(raw) {
+  return {
+    ...emptyRegistry(),
+    ...(raw || {}),
+    projects: {
+      ...((raw && raw.projects) || {}),
+    },
+  };
+}
+
+export async function readProjectRegistry() {
+  return normalizeRegistry(await readJson(registryPath(), null));
+}
+
+export async function writeProjectRegistry(registry) {
+  await writeJson(registryPath(), normalizeRegistry(registry));
+}
+
+export async function recordProject(projectRoot, source = 'unknown') {
+  const workspace = resolve(projectRoot);
+  const registry = await readProjectRegistry();
+  const previous = registry.projects[workspace] || {};
+  const now = new Date().toISOString();
+  registry.projects[workspace] = {
+    workspace,
+    firstSeenAt: previous.firstSeenAt || now,
+    lastSeenAt: now,
+    source,
+  };
+  await writeProjectRegistry(registry);
+  return registry.projects[workspace];
+}
+
+export async function discoverProjectRoots(searchRoot, options = {}) {
+  const root = resolve(searchRoot || process.cwd());
+  const maxDirs = options.maxDirs || 5000;
+  const roots = new Set();
+  let seen = 0;
+
+  async function walk(dir) {
+    if (seen >= maxDirs) return;
+    seen += 1;
+
+    if (await exists(join(dir, 'llm-wiki', '.kit-state.json'))) {
+      roots.add(dir);
+    }
+
+    let entries = [];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (seen >= maxDirs) return;
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
+      await walk(join(dir, entry.name));
+    }
+  }
+
+  await walk(root);
+  return [...roots].sort();
+}
+
+export async function knownProjectRoots(options = {}) {
+  const registry = await readProjectRegistry();
+  const roots = new Set(Object.keys(registry.projects || {}));
+  if (options.discover !== false) {
+    const discovered = await discoverProjectRoots(options.workspace || process.cwd(), options);
+    for (const root of discovered) roots.add(root);
+  }
+
+  const existing = [];
+  for (const root of [...roots].sort()) {
+    if (await isDirectory(root) && await exists(join(root, 'llm-wiki', '.kit-state.json'))) {
+      existing.push(root);
+    }
+  }
+  return existing;
+}
+
+export function commandForProject(command, workspace) {
+  return `llm-wiki ${command} --workspace ${workspace}`;
+}

package/src/update.js

@@ -3,6 +3,7 @@ import { resolve } from 'path';
 import { appendWikiLog, bootstrapProject } from './project.js';
 import { install } from './install.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
+import { knownProjectRoots } from './projects.js';
 import { binPath, detectInstallSource, packageName, runtimeVersion } from './version.js';
 
 function runCommand(command, args, options = {}) {
@@ -60,6 +61,30 @@ export async function postUpdate(options = {}) {
     workspace,
     replaceHooks: true,
   });
+
+  if (options.all) {
+    const workspaces = await knownProjectRoots({ workspace });
+    const projects = [];
+    for (const projectRoot of workspaces) {
+      const projectResult = options.noProject
+        ? null
+        : await applyProjectTemplateUpdate(projectRoot);
+      if (!options.noProject) {
+        await appendWikiLog(projectRoot, `llm-wiki-kit post-update applied runtime ${runtimeVersion()}; changed templates: ${projectResult.changed.length}`);
+      }
+      projects.push({
+        workspace: projectRoot,
+        project: projectResult,
+      });
+    }
+    return {
+      workspace,
+      runtimeVersion: runtimeVersion(),
+      install: installResult,
+      projects,
+    };
+  }
+
   const projectResult = options.noProject
     ? null
     : await applyProjectTemplateUpdate(workspace);
@@ -110,6 +135,7 @@ export async function update(options = {}) {
   assertCommandOk(installResult, 'npm install -g');
 
   const postArgs = [binCommand(), 'post-update', '--workspace', workspace];
+  if (options.all) postArgs.push('--all');
   if (options.profile) postArgs.push('--profile', options.profile);
   if (options.noProject) postArgs.push('--no-project');
   if (options.codex === false) postArgs.push('--no-codex');