@ngockhoale/ukit 1.1.6

package/src/cli/commands/install.js

@@ -0,0 +1,293 @@
+import { buildPathConfig } from '../../core/paths.js';
+import { runInstallPipeline } from '../../core/runInstallPipeline.js';
+import { buildCodeIndex } from '../../index/buildIndex.js';
+import { installIndexRefreshHooks } from '../../index/gitHooks.js';
+import fs from 'node:fs/promises';
+import { pathExists, readJsonIfExists, removeFileOrLinkOnly } from '../../core/fileOps.js';
+import { removeTrackedPathsFromMetadata } from '../../core/metadata.js';
+import {
+  ADAPTER_BY_KEY,
+  DEFAULT_OPTIONAL_TOOL_KEYS,
+  parseToolsArg,
+  resolveOptionalToolKeys,
+  toSelectedAdapterItemIds,
+  formatSelectedTools,
+} from '../adapters.js';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import path from 'node:path';
+
+function getDeselectedAdapterKeys(optionalToolKeys) {
+  const selected = new Set(optionalToolKeys);
+  return DEFAULT_OPTIONAL_TOOL_KEYS.filter((key) => !selected.has(key));
+}
+
+async function adapterHasManagedFiles(projectRoot, adapter) {
+  const existingPaths = await getExistingManagedPaths(projectRoot, adapter);
+  return existingPaths.length > 0;
+}
+
+async function getExistingManagedPaths(projectRoot, adapter) {
+  const existingPaths = [];
+  for (const relativePath of adapter.managedPaths) {
+    const absolutePath = path.join(projectRoot, relativePath);
+    try {
+      // Use lstat (not access) so broken symlinks are also detected.
+      // fs.access follows the link and throws on a broken symlink;
+      // fs.lstat returns info about the link itself regardless of target.
+      await fs.lstat(absolutePath);
+      existingPaths.push(relativePath);
+    } catch {
+      // path does not exist at all
+    }
+  }
+  return existingPaths;
+}
+
+function normalizeTrackedPath(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return trimmed.replace(/\\/g, '/');
+}
+
+function isSameOrDescendantPath(candidatePath, parentPath) {
+  if (!candidatePath || !parentPath) {
+    return false;
+  }
+
+  return candidatePath === parentPath || candidatePath.startsWith(`${parentPath}/`);
+}
+
+async function loadTrackedManagedPathSet(projectRoot) {
+  const installMetaPath = path.join(projectRoot, '.claude', 'ukit', '.ukit', 'install.json');
+  const installMeta = await readJsonIfExists(installMetaPath);
+  if (installMeta?.tool !== 'ukit' || !Array.isArray(installMeta.files)) {
+    return null;
+  }
+
+  return new Set(
+    installMeta.files
+      .map((entry) => normalizeTrackedPath(typeof entry === 'string' ? entry : entry?.p))
+      .filter(Boolean),
+  );
+}
+
+async function promptYesNo(line, question) {
+  while (true) {
+    const answer = (await line.question(question)).trim().toLowerCase();
+
+    if (answer === '') {
+      return false;
+    }
+
+    if (answer === 'y' || answer === 'yes') {
+      return true;
+    }
+
+    if (answer === 'n' || answer === 'no') {
+      return false;
+    }
+
+    console.log('[UKit] Please answer y/yes or n/no.');
+  }
+}
+
+export async function pruneDeselectedAdapters({
+  projectRoot,
+  optionalToolKeys,
+  io = { input, output },
+  createInterface = readline.createInterface,
+}) {
+  const retainedManagedPaths = [];
+  const installMetaPath = path.join(projectRoot, '.claude', 'ukit', '.ukit', 'install.json');
+  const deselectedKeys = getDeselectedAdapterKeys(optionalToolKeys);
+  if (deselectedKeys.length === 0) {
+    return { retainedManagedPaths };
+  }
+  const trackedManagedPathSet = await loadTrackedManagedPathSet(projectRoot);
+  if (!trackedManagedPathSet || trackedManagedPathSet.size === 0) {
+    return { retainedManagedPaths };
+  }
+
+  const existingDeselectedAdapters = [];
+  for (const key of deselectedKeys) {
+    const adapter = ADAPTER_BY_KEY.get(key);
+    if (!adapter) {
+      continue;
+    }
+
+    const existingManagedPaths = (await getExistingManagedPaths(projectRoot, adapter))
+      .filter((relativePath) =>
+        [...trackedManagedPathSet].some((trackedPath) => isSameOrDescendantPath(trackedPath, relativePath)),
+      );
+    if (existingManagedPaths.length > 0) {
+      existingDeselectedAdapters.push({ adapter, existingManagedPaths });
+    }
+  }
+
+  if (existingDeselectedAdapters.length === 0) {
+    return { retainedManagedPaths };
+  }
+
+  const { input: inputStream, output: outputStream } = io;
+  if (!inputStream?.isTTY || !outputStream?.isTTY) {
+    const adapterNames = existingDeselectedAdapters.map(({ adapter }) => adapter.label).join(', ');
+    await removeTrackedPathsFromMetadata({
+      installMetaPath,
+      projectRoot,
+      removeRelativePaths: existingDeselectedAdapters.flatMap(({ existingManagedPaths }) => existingManagedPaths),
+    });
+    console.log(
+      `[UKit] Deselected adapters with existing files detected (${adapterNames}). Skipping removal in non-interactive mode.`,
+    );
+    return { retainedManagedPaths: [...new Set(retainedManagedPaths)] };
+  }
+
+  const line = createInterface({ input: inputStream, output: outputStream });
+
+  try {
+    for (const { adapter, existingManagedPaths } of existingDeselectedAdapters) {
+      const shouldRemove = await promptYesNo(
+        line,
+        `[UKit] ${adapter.label} is deselected, but existing files were found. Remove now? (y/N): `,
+      );
+
+      if (!shouldRemove) {
+        await removeTrackedPathsFromMetadata({
+          installMetaPath,
+          projectRoot,
+          removeRelativePaths: existingManagedPaths,
+        });
+        continue;
+      }
+
+      let removedCount = 0;
+      for (const relativePath of adapter.managedPaths) {
+        const absolutePath = path.join(projectRoot, relativePath);
+        const removed = await removeFileOrLinkOnly(absolutePath);
+        if (removed) {
+          removedCount += 1;
+          await removeTrackedPathsFromMetadata({
+            installMetaPath,
+            projectRoot,
+            removeRelativePaths: [relativePath],
+          });
+        } else if (await pathExists(absolutePath)) {
+          console.log(
+            `[UKit] Skipping removal of ${relativePath} because it is not a symlink. Remove it manually if intended.`,
+          );
+          await removeTrackedPathsFromMetadata({
+            installMetaPath,
+            projectRoot,
+            removeRelativePaths: [relativePath],
+          });
+        }
+      }
+
+      console.log(`[UKit] Removed ${removedCount} ${adapter.label} path(s).`);
+    }
+  } finally {
+    line.close();
+  }
+
+  return { retainedManagedPaths: [...new Set(retainedManagedPaths)] };
+}
+
+export async function runInstall({ packageRoot, projectRoot, packageVersion, argv = [] }) {
+  const toolsArg = parseToolsArg(argv);
+  const selectedOptionalTools = resolveOptionalToolKeys(toolsArg);
+
+  const pruneResult = await pruneDeselectedAdapters({
+    projectRoot,
+    optionalToolKeys: selectedOptionalTools,
+  });
+
+  const selectedAdapterItemIds = toSelectedAdapterItemIds(selectedOptionalTools);
+  const pathConfig = buildPathConfig({ packageRoot, projectRoot });
+
+  const result = await runInstallPipeline({
+    packageVersion,
+    pathConfig,
+    dryRun: false,
+    selectedAdapterItemIds,
+    retainedManagedRelativePaths: pruneResult?.retainedManagedPaths ?? [],
+  });
+
+  const { create, update, unchanged, skip } = result.summary;
+
+  console.log(`[UKit] Project: ${result.projectContext.project.name}`);
+  console.log(`[UKit] Manifest: ${result.manifest.name} (v${result.manifest.version})`);
+  console.log(`[UKit] Detected packs: ${result.stackContext.detectedPacks.join(', ')}`);
+  console.log(`[UKit] Tools selected: ${formatSelectedTools(selectedOptionalTools)}`);
+
+  if (create === 0 && update === 0) {
+    console.log(`[UKit] Already up to date. (unchanged=${unchanged}, skip=${skip})`);
+  } else {
+    console.log(
+      `[UKit] Summary: create=${create}, update=${update}, unchanged=${unchanged}, skip=${skip} (user files, not overwritten)`,
+    );
+  }
+
+  const providerNames = Object.keys(result.providerContext.providers);
+  const providerStatus = providerNames
+    .map((name) => `${name}=${result.providerContext.providers[name]?.supported ?? 'unknown'}`)
+    .join(', ');
+  console.log(`[UKit] Providers: ${providerStatus}, all=${result.providerContext.allSupported}`);
+
+  const docsPaths = [
+    path.join(projectRoot, 'docs', 'PROJECT.md'),
+    path.join(projectRoot, 'docs', 'MEMORY.md'),
+    path.join(projectRoot, 'docs', 'WORKLOG.md'),
+  ];
+  const docsLabels = ['docs/PROJECT.md', 'docs/MEMORY.md', 'docs/WORKLOG.md'];
+  const missingDocs = [];
+  for (let i = 0; i < docsPaths.length; i++) {
+    if (!(await pathExists(docsPaths[i]))) {
+      missingDocs.push(docsLabels[i]);
+    }
+  }
+
+  if (missingDocs.length > 0) {
+    console.log(`[UKit] Missing docs — fill these in before first use: ${missingDocs.join(', ')}`);
+  } else {
+    console.log('[UKit] Docs baseline ready: docs/PROJECT.md, docs/MEMORY.md, docs/WORKLOG.md');
+    console.log('[UKit] Fill them once with real project context for the best results.');
+  }
+
+  let indexSummary;
+  try {
+    indexSummary = await buildCodeIndex({ rootDir: projectRoot });
+  } catch (error) {
+    console.log('[UKit] Install files synced, but source index build failed.');
+    console.log('[UKit] Fix the repo state, then rerun `ukit install` so the AI can index source code first.');
+    throw error;
+  }
+
+  console.log(
+    `[UKit] Index cache ready: files=${indexSummary.fileCount}, symbols=${indexSummary.symbolCount}, cache=${indexSummary.indexDir}`,
+  );
+
+  try {
+    const hookResult = await installIndexRefreshHooks({ projectRoot });
+    console.log(
+      `[UKit] Index auto-refresh hooks: installed=${hookResult.installed}, unchanged=${hookResult.unchanged}`,
+    );
+  } catch (error) {
+    console.log(
+      `[UKit] Index auto-refresh hooks skipped: ${error?.message ?? String(error)}`,
+    );
+  }
+
+  console.log('[UKit] Install completed.');
+  console.log('[UKit] Team rule: remember only `ukit install`.');
+  console.log(
+    '[UKit] Next: if this is the first install, fill the docs baseline once. Then open your AI tool and give a natural-language task.',
+  );
+}

package/src/cli/commands/memory.js

@@ -0,0 +1,126 @@
+import {
+  exportMemory,
+  forgetMemoryItem,
+  listMemoryItems,
+} from '../../core/memory/store.js';
+import { getContextInjection, search } from '../../core/memory/retrieval.js';
+import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
+import { buildRuntimePaths } from '../../core/runtimePaths.js';
+import { pathExists } from '../../core/fileOps.js';
+import { detectProjectContext } from '../../context/detectProjectContext.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+
+export async function runMemory({ projectRoot, argv = [] }) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  if (!(await pathExists(runtimePaths.runtimeRoot))) {
+    throw new Error('Shared UKit runtime not found. Run `ukit install` first.');
+  }
+
+  const [subcommandRaw, ...rest] = argv;
+  const subcommand = (subcommandRaw ?? 'list').toLowerCase();
+
+  if (HELP_FLAGS.has(subcommand)) {
+    printMemoryHelp();
+    return;
+  }
+
+  if (subcommand === 'list') {
+    const items = await listMemoryItems(projectRoot);
+    if (items.length === 0) {
+      console.log('[UKit] No memory items found.');
+      return;
+    }
+
+    for (const item of items) {
+      console.log(`${item.id} — ${item.summary}`);
+    }
+    return;
+  }
+
+  if (subcommand === 'search') {
+    const query = rest.join(' ').trim();
+    if (!query) {
+      throw new Error('Missing query. Usage: ukit memory search <query>');
+    }
+
+    const results = await search(query, 'all', 10, { projectRoot });
+    if (results.length === 0) {
+      console.log('[UKit] No memory matches found.');
+      return;
+    }
+
+    for (const result of results) {
+      console.log(`${result.id} — ${result.summary}`);
+    }
+    return;
+  }
+
+  if (subcommand === 'recall') {
+    const query = rest.join(' ').trim();
+    if (!query) {
+      throw new Error('Missing task/query. Usage: ukit memory recall <task>');
+    }
+
+    const runtimeConfigInspection = await inspectRuntimeConfig(projectRoot);
+    if (!runtimeConfigInspection.valid) {
+      throw new Error('Runtime config is invalid. Run `ukit doctor` or rerun `ukit install`.');
+    }
+
+    const runtimeConfig = runtimeConfigInspection.config;
+    if (!runtimeConfig.memory?.enabled || !runtimeConfig.memory?.progressiveRetrieval) {
+      throw new Error('Memory recall is disabled in .ukit/storage/config.json.');
+    }
+
+    const projectContext = await detectProjectContext(projectRoot);
+    const injection = await getContextInjection(query, projectContext.project.name, {
+      projectRoot,
+      maxTokens: runtimeConfig.memory.maxInjectionTokens,
+      promptCache: Boolean(runtimeConfig.tokenPipeline?.promptCache),
+      inputCompression: Boolean(runtimeConfig.tokenPipeline?.inputCompression),
+    });
+
+    if (!injection) {
+      console.log('[UKit] No relevant memory context found.');
+      return;
+    }
+
+    console.log(injection);
+    return;
+  }
+
+  if (subcommand === 'forget') {
+    const memoryId = rest.join(' ').trim();
+    if (!memoryId) {
+      throw new Error('Missing memory id. Usage: ukit memory forget <id>');
+    }
+
+    const result = await forgetMemoryItem(projectRoot, memoryId);
+    if (!result.removed) {
+      throw new Error(`Memory item not found: ${memoryId}`);
+    }
+
+    console.log(`[UKit] Forgot ${memoryId}.`);
+    return;
+  }
+
+  if (subcommand === 'export') {
+    const data = await exportMemory(projectRoot);
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  throw new Error(`Unknown memory subcommand: ${subcommand}. Run "ukit memory help".`);
+}
+
+export function printMemoryHelp() {
+  console.log('UKit Memory Commands');
+  console.log('Usage: ukit memory <list|search|recall|forget|export> [args]');
+  console.log('');
+  console.log('Subcommands:');
+  console.log('  list               List memory items in shared .ukit/storage/memory');
+  console.log('  search <query>     Search memory summaries and content');
+  console.log('  recall <task>      Print a compact previous-context block for the current task');
+  console.log('  forget <id>        Remove one memory item by id');
+  console.log('  export             Print all memory as JSON');
+}

package/src/cli/commands/status.js

@@ -0,0 +1,8 @@
+import { buildStatusReport, formatStatusReport } from '../../core/status.js';
+
+export async function runStatus({ projectRoot }) {
+  const report = await buildStatusReport(projectRoot);
+  for (const line of formatStatusReport(report)) {
+    console.log(line);
+  }
+}

package/src/cli/commands/uninstall.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { uninstallUkit } from '../../core/uninstall.js';
+
+const KNOWN_UNINSTALL_FLAGS = new Set(['--dry-run', '--help', '-h']);
+
+export async function runUninstall({ projectRoot, argv = [] }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('Usage: ukit uninstall [options]');
+    console.log('');
+    console.log('Remove all UKit-managed assets from the current project.');
+    console.log('');
+    console.log('Options:');
+    console.log('  --dry-run   Preview what would be removed without deleting anything');
+    console.log('  --help, -h  Show this help message');
+    return;
+  }
+
+  const unknownFlags = argv.filter((a) => a.startsWith('-') && !KNOWN_UNINSTALL_FLAGS.has(a));
+  if (unknownFlags.length > 0) {
+    throw new Error(
+      `Unknown option(s): ${unknownFlags.join(', ')}. Run \`ukit uninstall --help\` for usage.`,
+    );
+  }
+
+  const positionalArgs = argv.filter((a) => !a.startsWith('-'));
+  if (positionalArgs.length > 0) {
+    throw new Error(
+      `Unexpected argument(s): ${positionalArgs.join(', ')}. Run \`ukit uninstall --help\` for usage.`,
+    );
+  }
+
+  const dryRun = argv.includes('--dry-run');
+  const result = await uninstallUkit({ projectRoot, dryRun });
+
+  if (!result.wasInstalled) {
+    console.log('[UKit] UKit does not appear to be installed in this project. Nothing to remove.');
+    return;
+  }
+
+  if (dryRun) {
+    console.log('[UKit] Dry-run: the following paths would be removed:');
+    for (const p of result.wouldRemove) {
+      console.log(`  - ${path.relative(projectRoot, p)}`);
+    }
+    console.log(`[UKit] Would remove ${result.wouldRemove.length} path(s). Run without --dry-run to actually uninstall.`);
+    return;
+  }
+
+  console.log(`[UKit] Uninstall complete. Removed ${result.removed}/${result.attempted} managed paths.`);
+  console.log('[UKit] Note: docs/PROJECT.md, docs/MEMORY.md, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
+}

package/src/cli/index.js

@@ -0,0 +1,109 @@
+import { runInstall } from './commands/install.js';
+import { runDiff } from './commands/diff.js';
+import { runDoctor, printDoctorHelp, DOCTOR_HELP_FLAGS } from './commands/doctor.js';
+import { runUninstall } from './commands/uninstall.js';
+import { runIndexTools } from './commands/indexTools.js';
+import { runStatus } from './commands/status.js';
+import { runMemory } from './commands/memory.js';
+
+const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
+
+export async function runCli({ argv, packageRoot, projectRoot, packageVersion }) {
+  // Global flags take priority — never default-route them to install.
+  // After that, if argv[0] is missing or starts with -- it is an install-specific flag
+  // (e.g. --tools=none), so treat it as the default `install` command.
+  const first = argv[0];
+  const isGlobalFlag = first && GLOBAL_FLAGS.has(first);
+  const isDefaultCommand = !isGlobalFlag && (!first || first.startsWith('--'));
+  const command = isDefaultCommand ? 'install' : (first ?? '').toLowerCase();
+  const commandArgv = isDefaultCommand ? argv : argv.slice(1);
+
+  if (command === 'install') {
+    await runInstall({ packageRoot, projectRoot, packageVersion, argv: commandArgv });
+    return;
+  }
+
+  if (command === 'diff') {
+    await runDiff({ packageRoot, projectRoot, packageVersion, argv: commandArgv });
+    return;
+  }
+
+  if (command === 'doctor') {
+    if (commandArgv.some((flag) => DOCTOR_HELP_FLAGS.has(flag))) {
+      printDoctorHelp();
+      return;
+    }
+
+    await runDoctor({ packageRoot, projectRoot, argv: commandArgv });
+    return;
+  }
+
+  if (command === 'uninstall') {
+    await runUninstall({ projectRoot, argv: commandArgv });
+    return;
+  }
+
+  if (command === 'index') {
+    await runIndexTools({ projectRoot, argv: commandArgv });
+    return;
+  }
+
+  if (command === 'status') {
+    await runStatus({ projectRoot, argv: commandArgv });
+    return;
+  }
+
+  if (command === 'memory') {
+    await runMemory({ projectRoot, argv: commandArgv });
+    return;
+  }
+
+  if (command === 'build' && (commandArgv[0] ?? '').toLowerCase() === 'index') {
+    await runIndexTools({ projectRoot, argv: ['build', ...commandArgv.slice(1)] });
+    return;
+  }
+
+  if (command === 'version' || command === '--version' || command === '-v') {
+    console.log(`ukit ${packageVersion}`);
+    return;
+  }
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    console.log('UKit CLI');
+    console.log('Usage: ukit [command] [options]');
+    console.log('');
+    console.log('Team workflow: remember only `ukit install`.');
+    console.log('After the first install, fill the docs baseline once, then open your AI tool and work in natural language.');
+    console.log('');
+    console.log('Primary command:');
+    console.log('  install (default)  Install/update UKit assets into the current project');
+    console.log('');
+    console.log('Advanced / maintainer commands:');
+    console.log('  diff               Preview install actions without writing any files');
+    console.log('  doctor             Validate manifest, stack, docs, and UKit state');
+    console.log('  uninstall          Remove all UKit-managed assets');
+    console.log('  index              Codebase index tools (build/query/triage)');
+    console.log('  status             Show UKit runtime status');
+    console.log('  memory             Inspect shared UKit memory');
+    console.log('  version            Show UKit version');
+    console.log('');
+    console.log('Options (install / diff):');
+    console.log('  --tools=<list>     Comma-separated adapters to enable (default: all)');
+    console.log('                     Values: claude, antigravity, codex, opencode');
+    console.log('                     Example: ukit install --tools=claude,codex,opencode');
+    console.log('                     Use --tools=none to disable all optional adapters');
+    console.log('');
+    console.log('Maintainer / debug examples:');
+    console.log('  ukit index build');
+    console.log('  ukit index query "writeFileAtomic EACCES"');
+    console.log('  ukit index triage "writeFileAtomic EACCES"');
+    console.log('  ukit index hooks install');
+    console.log('  ukit build index   # alias');
+    console.log('');
+    console.log('Options (uninstall):');
+    console.log('  --dry-run          Preview what would be removed without deleting anything');
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}. Run ukit help for usage.`);
+}

package/src/context/detectProjectContext.js

@@ -0,0 +1,49 @@
+import path from 'node:path';
+import { pathExists, readJsonIfExists } from '../core/fileOps.js';
+
+async function inferPackageManager(projectRoot, packageJson) {
+  // packageManager field takes priority over lockfiles — it is an explicit
+  // declaration of intent, while lockfiles may be stale (e.g. old yarn.lock
+  // leftover after switching to npm).
+  const declared = packageJson?.packageManager;
+  if (typeof declared === 'string') {
+    if (declared.startsWith('yarn@')) return 'yarn';
+    if (declared.startsWith('pnpm@')) return 'pnpm';
+    if (declared.startsWith('npm@')) return 'npm';
+  }
+
+  if (await pathExists(path.join(projectRoot, 'yarn.lock'))) {
+    return 'yarn';
+  }
+
+  if (await pathExists(path.join(projectRoot, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+
+  return 'npm';
+}
+
+function inferProjectName(projectRoot, packageJson) {
+  if (typeof packageJson?.name === 'string' && packageJson.name.trim() !== '') {
+    return packageJson.name;
+  }
+
+  return path.basename(projectRoot);
+}
+
+export async function detectProjectContext(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const packageJson = await readJsonIfExists(packageJsonPath);
+
+  return {
+    project: {
+      root: projectRoot,
+      name: inferProjectName(projectRoot, packageJson),
+    },
+    runtime: {
+      packageManager: await inferPackageManager(projectRoot, packageJson),
+      os: process.platform,
+      nodeVersion: process.version,
+    },
+  };
+}

package/src/context/detectProviders.js

@@ -0,0 +1,12 @@
+export async function detectProviders(_projectRoot) {
+  const providers = {
+    unic: {
+      supported: true,
+    },
+  };
+
+  return {
+    providers,
+    allSupported: true,
+  };
+}