@ngockhoale/ukit 1.1.6

package/templates/.claude/skills/webapp-testing/scripts/with_server.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""
+Start one or more servers, wait for them to be ready, run a command, then clean up.
+
+Usage:
+    # Single server
+    python scripts/with_server.py --server "npm run dev" --port 5173 -- python automation.py
+    python scripts/with_server.py --server "npm start" --port 3000 -- python test.py
+
+    # Multiple servers
+    python scripts/with_server.py \
+      --server "cd backend && python server.py" --port 3000 \
+      --server "cd frontend && npm run dev" --port 5173 \
+      -- python test.py
+"""
+
+import subprocess
+import socket
+import time
+import sys
+import argparse
+
+def is_server_ready(port, timeout=30):
+    """Wait for server to be ready by polling the port."""
+    start_time = time.time()
+    while time.time() - start_time < timeout:
+        try:
+            with socket.create_connection(('localhost', port), timeout=1):
+                return True
+        except (socket.error, ConnectionRefusedError):
+            time.sleep(0.5)
+    return False
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Run command with one or more servers')
+    parser.add_argument('--server', action='append', dest='servers', required=True, help='Server command (can be repeated)')
+    parser.add_argument('--port', action='append', dest='ports', type=int, required=True, help='Port for each server (must match --server count)')
+    parser.add_argument('--timeout', type=int, default=30, help='Timeout in seconds per server (default: 30)')
+    parser.add_argument('command', nargs=argparse.REMAINDER, help='Command to run after server(s) ready')
+
+    args = parser.parse_args()
+
+    # Remove the '--' separator if present
+    if args.command and args.command[0] == '--':
+        args.command = args.command[1:]
+
+    if not args.command:
+        print("Error: No command specified to run")
+        sys.exit(1)
+
+    # Parse server configurations
+    if len(args.servers) != len(args.ports):
+        print("Error: Number of --server and --port arguments must match")
+        sys.exit(1)
+
+    servers = []
+    for cmd, port in zip(args.servers, args.ports):
+        servers.append({'cmd': cmd, 'port': port})
+
+    server_processes = []
+
+    try:
+        # Start all servers
+        for i, server in enumerate(servers):
+            print(f"Starting server {i+1}/{len(servers)}: {server['cmd']}")
+
+            # Use shell=True to support commands with cd and &&
+            process = subprocess.Popen(
+                server['cmd'],
+                shell=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE
+            )
+            server_processes.append(process)
+
+            # Wait for this server to be ready
+            print(f"Waiting for server on port {server['port']}...")
+            if not is_server_ready(server['port'], timeout=args.timeout):
+                raise RuntimeError(f"Server failed to start on port {server['port']} within {args.timeout}s")
+
+            print(f"Server ready on port {server['port']}")
+
+        print(f"\nAll {len(servers)} server(s) ready")
+
+        # Run the command
+        print(f"Running: {' '.join(args.command)}\n")
+        result = subprocess.run(args.command)
+        sys.exit(result.returncode)
+
+    finally:
+        # Clean up all servers
+        print(f"\nStopping {len(server_processes)} server(s)...")
+        for i, process in enumerate(server_processes):
+            try:
+                process.terminate()
+                process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+            print(f"Server {i+1} stopped")
+        print("All servers stopped")
+
+
+if __name__ == '__main__':
+    main()

package/templates/.claude/ukit/index/build-index.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { buildCodeIndex } from './lib/index-core.mjs';
+
+const args = process.argv.slice(2);
+const rootDir = getRootDir(args);
+const summary = await buildCodeIndex({ rootDir });
+
+console.log('[ukit:index:build] completed');
+console.log(`root: ${rootDir}`);
+console.log(`files: ${summary.fileCount}`);
+console.log(`symbols: ${summary.symbolCount}`);
+console.log(`imports: ${summary.importCount}`);
+console.log(`tests-map: ${summary.testsMapCount}`);
+console.log(`hotspots: ${summary.hotspotCount}`);
+console.log(`indexDir: ${summary.indexDir}`);
+
+function getRootDir(argv) {
+  const value = readFlagValue(argv, '--root');
+  return value ? path.resolve(value) : process.cwd();
+}
+
+function readFlagValue(argv, flag) {
+  const exact = argv.indexOf(flag);
+  if (exact >= 0 && argv[exact + 1]) return argv[exact + 1];
+  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
+  return withEquals ? withEquals.slice(flag.length + 1) : null;
+}

package/templates/.claude/ukit/index/cache-utils.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEFAULT_RECENT_CACHE_MAX_ENTRIES = 6;
+
+export async function readRecentCache(cachePath, { maxEntries = DEFAULT_RECENT_CACHE_MAX_ENTRIES } = {}) {
+  const raw = await readJson(cachePath, null);
+  return normalizeCacheDocument(raw, { maxEntries });
+}
+
+export async function readRecentCacheEntry(
+  cachePath,
+  requestKey,
+  {
+    maxEntries = DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+    touch = false,
+  } = {},
+) {
+  if (typeof requestKey !== 'string' || !requestKey) {
+    return null;
+  }
+
+  const cache = await readRecentCache(cachePath, { maxEntries });
+  const entryIndex = cache.entries.findIndex((entry) => entry.requestKey === requestKey);
+  if (entryIndex < 0) {
+    return null;
+  }
+
+  const entry = cache.entries[entryIndex];
+  if (!touch || entryIndex === 0) {
+    return entry;
+  }
+
+  const touchedEntry = {
+    ...entry,
+    updatedAt: Date.now(),
+  };
+  const entries = [
+    touchedEntry,
+    ...cache.entries.slice(0, entryIndex),
+    ...cache.entries.slice(entryIndex + 1),
+  ].slice(0, maxEntries);
+  const document = buildCacheDocument(entries, { maxEntries });
+  await writeJson(cachePath, document);
+  return document.entries[0] ?? touchedEntry;
+}
+
+export async function writeRecentCacheEntry(
+  cachePath,
+  entry,
+  { maxEntries = DEFAULT_RECENT_CACHE_MAX_ENTRIES } = {},
+) {
+  const normalizedEntry = normalizeCacheEntry(entry);
+  if (!normalizedEntry) {
+    return readRecentCache(cachePath, { maxEntries });
+  }
+
+  const cache = await readRecentCache(cachePath, { maxEntries });
+  const entries = [
+    normalizedEntry,
+    ...cache.entries.filter((existingEntry) => existingEntry.requestKey !== normalizedEntry.requestKey),
+  ].slice(0, maxEntries);
+  const document = buildCacheDocument(entries, { maxEntries });
+  await writeJson(cachePath, document);
+  return document;
+}
+
+function normalizeCacheDocument(raw, { maxEntries = DEFAULT_RECENT_CACHE_MAX_ENTRIES } = {}) {
+  const candidates = [];
+
+  if (Array.isArray(raw?.entries)) {
+    candidates.push(...raw.entries);
+  }
+
+  if (
+    !Array.isArray(raw?.entries)
+    && raw
+    && typeof raw === 'object'
+    && typeof raw.requestKey === 'string'
+    && raw.requestKey
+  ) {
+    candidates.push(raw);
+  }
+
+  return buildCacheDocument(candidates, { maxEntries });
+}
+
+function buildCacheDocument(entries, { maxEntries = DEFAULT_RECENT_CACHE_MAX_ENTRIES } = {}) {
+  const normalizedEntries = entries
+    .map((entry) => normalizeCacheEntry(entry))
+    .filter(Boolean)
+    .sort((left, right) => (right.updatedAt ?? 0) - (left.updatedAt ?? 0))
+    .filter((entry, index, list) => list.findIndex((candidate) => candidate.requestKey === entry.requestKey) === index)
+    .slice(0, maxEntries);
+
+  const latestEntry = normalizedEntries[0] ?? null;
+  return latestEntry
+    ? {
+        requestKey: latestEntry.requestKey,
+        updatedAt: latestEntry.updatedAt,
+        entries: normalizedEntries,
+      }
+    : {
+        entries: [],
+      };
+}
+
+function normalizeCacheEntry(entry) {
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+
+  const requestKey = typeof entry.requestKey === 'string' ? entry.requestKey : '';
+  if (!requestKey) {
+    return null;
+  }
+
+  const updatedAt = Number(entry.updatedAt);
+  const normalizedEntry = {
+    ...entry,
+    requestKey,
+    updatedAt: Number.isFinite(updatedAt) ? updatedAt : Date.now(),
+  };
+  delete normalizedEntry.entries;
+  return normalizedEntry;
+}
+
+async function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(typeof filePath === 'string' && filePath ? filePath : '.'), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(value), 'utf8');
+}