llm-wiki-kit 0.1.0

package/src/cli.js

@@ -0,0 +1,183 @@
+import { resolve } from 'path';
+import { handleHook } from './hook.js';
+import { install, status, uninstall } from './install.js';
+import { bootstrapProject } from './project.js';
+import { formatDoctor, runDoctor } from './doctor.js';
+import { migrate } from './migrate.js';
+import { postUpdate, update } from './update.js';
+
+function parseOptions(args) {
+  const options = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--workspace' || arg === '--cwd') {
+      options.workspace = args[++i];
+    } else if (arg === '--profile') {
+      options.profile = args[++i];
+    } else if (arg === '--to') {
+      options.to = args[++i];
+    } else if (arg === '--no-codex') {
+      options.codex = false;
+    } else if (arg === '--no-claude') {
+      options.claude = false;
+    } else if (arg === '--no-project') {
+      options.noProject = true;
+    } else if (arg === '--check') {
+      options.check = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { options, rest };
+}
+
+function printJsonOrText(value, options, formatter = null) {
+  if (options.json) {
+    console.log(JSON.stringify(value, null, 2));
+  } else if (formatter) {
+    console.log(formatter(value));
+  } else {
+    console.log(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
+  }
+}
+
+export async function runCli(args) {
+  const [command, ...tail] = args;
+  const { options, rest } = parseOptions(tail);
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    console.log(`llm-wiki-kit
+
+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 status
+  llm-wiki uninstall
+  llm-wiki hook codex <EventName>
+  llm-wiki hook claude <EventName>
+  llm-wiki bootstrap --workspace <project>
+  llm-wiki migrate --workspace <project>
+`);
+    return;
+  }
+
+  if (command === 'install') {
+    const result = await install(options);
+    printJsonOrText(result, options, (value) => [
+      'llm-wiki-kit installed',
+      `- workspace: ${value.workspace}`,
+      `- bin: ${value.localBin}`,
+      `- changed hooks: ${value.changed.length ? value.changed.join(', ') : 'none (already installed)'}`,
+      'Restart Codex/Claude Code sessions so new hooks are loaded.',
+    ].join('\n'));
+    return;
+  }
+
+  if (command === 'uninstall') {
+    const result = await uninstall(options);
+    printJsonOrText(result, options, (value) => `llm-wiki-kit uninstalled hooks: ${value.changed.length ? value.changed.join(', ') : 'none'}`);
+    return;
+  }
+
+  if (command === 'status') {
+    printJsonOrText(await status(options), options, formatStatus);
+    return;
+  }
+
+  if (command === 'update') {
+    printJsonOrText(await update(options), options, formatUpdate);
+    return;
+  }
+
+  if (command === 'post-update') {
+    printJsonOrText(await postUpdate(options), options, formatPostUpdate);
+    return;
+  }
+
+  if (command === 'doctor') {
+    const result = await runDoctor();
+    printJsonOrText(result, options, formatDoctor);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (command === 'bootstrap') {
+    const projectRoot = resolve(options.workspace || process.cwd());
+    printJsonOrText(await bootstrapProject(projectRoot, options), options);
+    return;
+  }
+
+  if (command === 'migrate') {
+    const projectRoot = resolve(options.workspace || process.cwd());
+    printJsonOrText(await migrate(projectRoot), options);
+    return;
+  }
+
+  if (command === 'hook') {
+    const provider = rest[0] || 'codex';
+    const eventName = rest[1];
+    const output = await handleHook(provider, eventName);
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+    return;
+  }
+
+  throw new Error(`unknown command: ${command}`);
+}
+
+function formatStatus(value) {
+  const project = value.project || {};
+  return [
+    'llm-wiki-kit status',
+    `- runtime: ${value.runtimeVersion} (${value.installSource})`,
+    `- bin: ${value.binPath}`,
+    `- hooks current: ${value.hooksCurrent ? 'yes' : 'no'}`,
+    `- codex hook: ${value.codexInstalled ? 'current' : 'missing/outdated'}`,
+    `- claude hook: ${value.claudeInstalled ? 'current' : 'missing/outdated'}`,
+    `- project applied runtime: ${project.lastRuntimeVersionApplied || 'unknown'}`,
+    `- project templates current: ${project.managedFilesCurrent ? 'yes' : 'no'}`,
+  ].join('\n');
+}
+
+function formatUpdate(value) {
+  if (value.mode === 'check') {
+    return [
+      'llm-wiki-kit update check',
+      `- installed: ${value.installedVersion}`,
+      `- latest: ${value.latestVersion}`,
+      `- update available: ${value.updateAvailable ? 'yes' : 'no'}`,
+      `- project applied runtime: ${value.project?.lastRuntimeVersionApplied || 'unknown'}`,
+    ].join('\n');
+  }
+  if (value.mode === 'dry-run') {
+    return [
+      'llm-wiki-kit update dry-run',
+      `- installed: ${value.installedVersion}`,
+      `- latest: ${value.latestVersion}`,
+      `- update available: ${value.updateAvailable ? 'yes' : 'no'}`,
+      `- project template changes: ${value.project?.changed?.length || 0}`,
+      `- project template skipped: ${value.project?.skipped?.length || 0}`,
+    ].join('\n');
+  }
+  return [
+    'llm-wiki-kit updated',
+    `- workspace: ${value.workspace}`,
+    `- before: ${value.before}`,
+    `- target: ${value.target}`,
+  ].join('\n');
+}
+
+function formatPostUpdate(value) {
+  return [
+    'llm-wiki-kit post-update complete',
+    `- workspace: ${value.workspace}`,
+    `- runtime: ${value.runtimeVersion}`,
+    `- changed hooks: ${value.install.changed.length ? value.install.changed.join(', ') : 'none'}`,
+    `- changed project templates: ${value.project?.changed?.length || 0}`,
+  ].join('\n');
+}

package/src/constants.js

@@ -0,0 +1,69 @@
+export const KIT_NAME = 'llm-wiki-kit';
+export const DEFAULT_PROFILE = 'standard';
+
+export const CODEX_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'PreCompact',
+  'PostCompact',
+  'SubagentStop',
+  'Stop',
+];
+
+export const CLAUDE_EVENTS = [
+  'SessionStart',
+  'InstructionsLoaded',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolBatch',
+  'PreCompact',
+  'PostCompact',
+  'SubagentStop',
+  'Stop',
+  'SessionEnd',
+];
+
+export const PROJECT_MARKERS = [
+  'llm-wiki',
+  '.git',
+  'AGENTS.md',
+  'CLAUDE.md',
+  'package.json',
+  'pyproject.toml',
+  'go.mod',
+  'Cargo.toml',
+];
+
+export const LLM_WIKI_DIRS = [
+  'raw/inbox',
+  'raw/sessions',
+  'raw/sources',
+  'raw/assets',
+  'wiki/sources',
+  'wiki/concepts',
+  'wiki/entities',
+  'wiki/decisions',
+  'wiki/architecture',
+  'wiki/debugging',
+  'wiki/context',
+  'wiki/queries',
+  'outputs/questions',
+  'outputs/reports',
+  'procedures',
+];
+
+export const WIKI_CATEGORIES = [
+  'source',
+  'concept',
+  'entity',
+  'decision',
+  'architecture',
+  'debugging',
+  'context',
+  'query',
+  'session-log',
+  'convention',
+];

package/src/doctor.js

@@ -0,0 +1,89 @@
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+import { mkdtemp } from 'fs/promises';
+import { tmpdir } from 'os';
+import { exists, kitDataDir } from './fs-utils.js';
+import { status } from './install.js';
+
+function nodeMajor() {
+  return Number.parseInt(process.versions.node.split('.')[0], 10);
+}
+
+export async function runDoctor() {
+  const checks = [];
+  const add = (name, ok, detail = '') => checks.push({ name, ok, detail });
+  const stat = await status();
+
+  add('node >= 20', nodeMajor() >= 20, process.version);
+  add('runtime version detected', Boolean(stat.runtimeVersion), stat.runtimeVersion || 'unknown');
+  add('llm-wiki bin exists', await exists(stat.binPath), stat.binPath);
+  add('Codex hook installed', stat.codexInstalled, stat.codexHooksPath);
+  add('Claude hook installed', stat.claudeInstalled, stat.claudeSettingsPath);
+  add('project templates current', stat.project.managedFilesCurrent, stat.project.statePath);
+  add('codex command available', spawnSync('codex', ['--version'], { encoding: 'utf8' }).status === 0, 'codex --version');
+  add('claude command available', spawnSync('claude', ['--version'], { encoding: 'utf8' }).status === 0, 'claude --version');
+  add('state directory writable', await canWrite(join(kitDataDir(), '.doctor')), kitDataDir());
+  add('docs present', await docsPresent(), 'README.md and docs/');
+  add('sample hook roundtrip', await sampleHookRoundtrip(stat.binPath), 'UserPromptSubmit fixture');
+
+  const allOk = checks.every((check) => check.ok);
+  return { ok: allOk, checks };
+}
+
+async function docsPresent() {
+  const root = new URL('..', import.meta.url).pathname;
+  return (await exists(join(root, 'README.md'))) &&
+    (await exists(join(root, 'docs', 'concepts.md'))) &&
+    (await exists(join(root, 'docs', 'security.md')));
+}
+
+async function sampleHookRoundtrip(binPath) {
+  try {
+    const root = await mkdtemp(join(tmpdir(), 'llm-wiki-kit-doctor-'));
+    const env = {
+      ...process.env,
+      XDG_DATA_HOME: join(root, '.data'),
+      XDG_CACHE_HOME: join(root, '.cache'),
+    };
+    const payload = {
+      hook_event_name: 'UserPromptSubmit',
+      cwd: root,
+      session_id: 'doctor',
+      prompt: 'doctor sample prompt',
+    };
+    const result = spawnSync(process.execPath, [binPath, 'hook', 'codex', 'UserPromptSubmit'], {
+      input: JSON.stringify(payload),
+      encoding: 'utf8',
+      env,
+      timeout: 10000,
+    });
+    return result.status === 0 && result.stdout.includes('additionalContext');
+  } catch {
+    return false;
+  }
+}
+
+async function canWrite(path) {
+  try {
+    const { ensureDir } = await import('./fs-utils.js');
+    const { writeFile, unlink } = await import('fs/promises');
+    await ensureDir(join(path, '..'));
+    await writeFile(path, 'ok', 'utf8');
+    await unlink(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function formatDoctor(result) {
+  const lines = [`llm-wiki-kit doctor: ${result.ok ? 'PASS' : 'WARN'}`];
+  for (const check of result.checks) {
+    lines.push(`- ${check.ok ? 'PASS' : 'WARN'} ${check.name}${check.detail ? ` (${check.detail})` : ''}`);
+  }
+  if (!result.ok) {
+    lines.push('');
+    lines.push('Run ./install.sh --workspace /apps --profile standard to install hooks, then restart Codex/Claude Code sessions.');
+  }
+  return lines.join('\n');
+}

package/src/fs-utils.js

@@ -0,0 +1,173 @@
+import { createHash } from 'crypto';
+import { constants as fsConstants } from 'fs';
+import {
+  access,
+  appendFile,
+  copyFile,
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  symlink,
+  unlink,
+  writeFile,
+} from 'fs/promises';
+import { dirname, join, parse, resolve } from 'path';
+import { PROJECT_MARKERS } from './constants.js';
+
+export function homeDir() {
+  return process.env.HOME || process.env.USERPROFILE || process.cwd();
+}
+
+export function dataHome() {
+  return process.env.XDG_DATA_HOME || join(homeDir(), '.local', 'share');
+}
+
+export function cacheHome() {
+  return process.env.XDG_CACHE_HOME || join(homeDir(), '.cache');
+}
+
+export function kitDataDir() {
+  return join(dataHome(), 'llm-wiki-kit');
+}
+
+export async function exists(path) {
+  try {
+    await access(path, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isDirectory(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+
+export async function readText(path, fallback = '') {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeTextIfMissing(path, content) {
+  if (await exists(path)) return false;
+  await ensureDir(dirname(path));
+  await writeFile(path, content, 'utf8');
+  return true;
+}
+
+export async function writeText(path, content) {
+  await ensureDir(dirname(path));
+  await writeFile(path, content, 'utf8');
+}
+
+export async function appendText(path, content) {
+  await ensureDir(dirname(path));
+  await appendFile(path, content, 'utf8');
+}
+
+export async function readJson(path, fallback = null) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeJson(path, value) {
+  await ensureDir(dirname(path));
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export async function backupFile(path, label) {
+  if (!(await exists(path))) return null;
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, '');
+  const destDir = join(kitDataDir(), 'backups', stamp);
+  await ensureDir(destDir);
+  const safeLabel = label.replace(/[^a-zA-Z0-9._-]+/g, '-');
+  const dest = join(destDir, safeLabel || parse(path).base);
+  await copyFile(path, dest);
+  return dest;
+}
+
+export async function safeSymlink(target, linkPath) {
+  await ensureDir(dirname(linkPath));
+  try {
+    await unlink(linkPath);
+  } catch {
+    // No existing link.
+  }
+  await symlink(target, linkPath);
+}
+
+export async function findProjectRoot(startDir = process.cwd()) {
+  let current = resolve(startDir);
+  while (true) {
+    for (const marker of PROJECT_MARKERS) {
+      if (await exists(join(current, marker))) return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return resolve(startDir);
+    current = parent;
+  }
+}
+
+export async function listMarkdownFiles(root, maxFiles = 500) {
+  const output = [];
+  async function walk(dir) {
+    if (output.length >= maxFiles) return;
+    let entries = [];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (output.length >= maxFiles) return;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        await walk(full);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        output.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return output;
+}
+
+export function sha256(input) {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+export function todayKst() {
+  const formatter = new Intl.DateTimeFormat('en-CA', {
+    timeZone: 'Asia/Seoul',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  });
+  return formatter.format(new Date());
+}
+
+export function timeKst() {
+  const formatter = new Intl.DateTimeFormat('en-GB', {
+    timeZone: 'Asia/Seoul',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  });
+  return formatter.format(new Date());
+}

package/src/hook.js

@@ -0,0 +1,133 @@
+import { findProjectRoot } from './fs-utils.js';
+import { bootstrapProject, appendContextNote, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
+import { extractPathsFromText, hasSecretLikeText, isSensitivePath, summarizeForStorage } from './redaction.js';
+import { buildEntryFromState, rememberQuestion, rememberTool } from './state.js';
+
+async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (!raw) return {};
+  return JSON.parse(raw);
+}
+
+function normalizeEvent(explicit, payload) {
+  return explicit || payload.hook_event_name || payload.hookEventName || payload.event || payload.name || 'Unknown';
+}
+
+function promptText(payload) {
+  return payload.prompt || payload.user_prompt || payload.userPrompt || payload.message || payload.input || '';
+}
+
+function toolSummary(payload) {
+  const toolName = payload.tool_name || payload.toolName || payload.name || payload.tool?.name || 'tool';
+  const input = payload.tool_input || payload.toolInput || payload.input || payload.arguments || payload.tool?.input || {};
+  return `${toolName}: ${summarizeForStorage(input, 1200)}`;
+}
+
+function toolInputText(payload) {
+  const input = payload.tool_input || payload.toolInput || payload.input || payload.arguments || payload.tool?.input || {};
+  return typeof input === 'string' ? input : JSON.stringify(input);
+}
+
+function contextOutput(eventName, context) {
+  if (!context) return {};
+  return {
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: context,
+    },
+  };
+}
+
+function blockOutput(provider, reason) {
+  if (provider === 'claude') {
+    return {
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+      decision: 'block',
+      reason,
+    };
+  }
+  return {
+    decision: 'block',
+    reason,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      additionalContext: reason,
+    },
+  };
+}
+
+function shouldBlockTool(payload) {
+  const input = toolInputText(payload);
+  const paths = extractPathsFromText(input);
+  if (paths.some(isSensitivePath)) {
+    return 'llm-wiki-kit blocked access to a secret-looking path. Do not read or store .env, keys, token files, credentials, raw_private, or secrets.';
+  }
+  if (hasSecretLikeText(input)) {
+    return 'llm-wiki-kit blocked a tool call containing secret-like text. Redact secrets before continuing.';
+  }
+  return null;
+}
+
+export async function handleHook(provider, explicitEvent) {
+  const payload = await readStdinJson();
+  payload.__provider = provider;
+  const eventName = normalizeEvent(explicitEvent, payload);
+  const cwd = payload.cwd || process.cwd();
+  const projectRoot = await findProjectRoot(cwd);
+  await bootstrapProject(projectRoot);
+  await appendSessionEnvelope(projectRoot, eventName, payload).catch(() => {});
+
+  if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded') {
+    const context = await buildContextBrief(projectRoot, 'SessionStart');
+    return contextOutput(eventName, context);
+  }
+
+  if (eventName === 'UserPromptSubmit') {
+    const prompt = promptText(payload);
+    await rememberQuestion(projectRoot, payload, prompt);
+    const context = await buildContextBrief(projectRoot, eventName, prompt);
+    const warning = hasSecretLikeText(prompt)
+      ? '\n\nSecurity note: the prompt appears to contain secret-like text. Do not persist raw secret values; store only redacted summaries.'
+      : '';
+    return contextOutput(eventName, `${context}${warning}`);
+  }
+
+  if (eventName === 'PreToolUse') {
+    const reason = shouldBlockTool(payload);
+    if (reason) return blockOutput(provider, reason);
+    await rememberTool(projectRoot, payload, `pre ${toolSummary(payload)}`);
+    return {};
+  }
+
+  if (eventName === 'PostToolUse' || eventName === 'PostToolBatch') {
+    await rememberTool(projectRoot, payload, `post ${toolSummary(payload)}`);
+    return {};
+  }
+
+  if (eventName === 'PreCompact' || eventName === 'PostCompact') {
+    await appendContextNote(projectRoot, eventName, 'Compaction lifecycle event captured by llm-wiki-kit.');
+    if (eventName === 'PostCompact') {
+      return contextOutput(eventName, await buildContextBrief(projectRoot, eventName));
+    }
+    return {};
+  }
+
+  if (eventName === 'Stop' || eventName === 'SubagentStop' || eventName === 'SessionEnd') {
+    const assistantText = payload.last_assistant_message || payload.response || payload.assistant_response || '';
+    const entry = await buildEntryFromState(projectRoot, payload, assistantText);
+    if (entry.question !== '(not captured)' || entry.result !== '(not captured)') {
+      await appendLiveQa(projectRoot, entry);
+      const queryPath = await writeQueryPage(projectRoot, entry);
+      const decisionPath = await writeDecisionPage(projectRoot, entry);
+      await appendWikiLog(projectRoot, `captured ${eventName}${queryPath ? `; query=${queryPath}` : ''}${decisionPath ? `; decision=${decisionPath}` : ''}`);
+    }
+    return {};
+  }
+
+  return {};
+}