@ngockhoale/ukit 1.1.6

package/src/index/verificationPlan.js

@@ -0,0 +1,437 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { resolveContext } from './resolveContext.js';
+
+const RISKY_SKILL_IDS = new Set(['discover-security', 'repo-maintenance']);
+const TRACKED_VERIFICATION_FILES = [
+  'package.json',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'bun.lockb',
+  'bun.lock',
+];
+const MAX_VERIFICATION_ENV_CACHE_ENTRIES = 16;
+const MAX_VERIFICATION_PLAN_CACHE_ENTRIES = 32;
+const PROJECT_VERIFICATION_ENV_CACHE = new Map();
+const VERIFICATION_PLAN_CACHE = new Map();
+
+export async function deriveVerificationPlan({
+  rootDir = process.cwd(),
+  intent = '',
+  targetFile = null,
+  taskType = null,
+  contextResult = null,
+  skillIds = [],
+} = {}) {
+  const absoluteRoot = path.resolve(rootDir);
+  const resolvedContext = contextResult ?? await resolveContext({
+    rootDir: absoluteRoot,
+    intent,
+    targetFile,
+    taskType,
+  });
+  const context = summarizeContext(resolvedContext);
+  const effectiveTaskType = resolvedContext?.taskType ?? taskType ?? 'simple';
+  const projectVerification = await readProjectVerificationFingerprint(absoluteRoot);
+  const verificationPlanCacheKey = buildVerificationPlanCacheKey({
+    rootDir: absoluteRoot,
+    projectFingerprint: projectVerification.fingerprint,
+    targetFile,
+    taskType: effectiveTaskType,
+    skillIds,
+    context,
+  });
+
+  const cachedPlan = getRecentCacheEntry(VERIFICATION_PLAN_CACHE, verificationPlanCacheKey);
+  if (cachedPlan) {
+    return cachedPlan;
+  }
+
+  const planPromise = (async () => {
+    const projectEnvironment = await loadProjectVerificationEnvironment({
+      rootDir: absoluteRoot,
+      projectFingerprint: projectVerification.fingerprint,
+      fingerprintEntries: projectVerification.entries,
+      pkg: projectVerification.pkg,
+    });
+    const scripts = projectEnvironment.scripts;
+    const packageManager = projectEnvironment.packageManager;
+    const primaryTargets = unique([
+      ...(context.primaryTargets ?? []),
+      ...(targetFile ? [targetFile] : []),
+    ]);
+    const relatedTests = unique([
+      ...(context.relatedTests ?? []),
+      ...(targetFile && isTestLikeFile(targetFile) ? [targetFile] : []),
+    ]);
+    const commands = [];
+    const fallbackCommands = [];
+    const reasons = [];
+    const notes = [];
+    const docsOnly = primaryTargets.length > 0
+      && primaryTargets.every((filePath) => filePath.startsWith('docs/'));
+    const risky = effectiveTaskType === 'non-trivial'
+      || skillIds.some((skillId) => RISKY_SKILL_IDS.has(skillId));
+
+    let mode = 'minimal';
+
+    if (docsOnly) {
+      mode = 'docs-only';
+      reasons.push('docsOnly');
+      if (scripts.lint) {
+        fallbackCommands.push(buildScriptCommand(packageManager, 'lint'));
+      }
+
+      notes.push('Docs-focused change: prefer docs syntax/format verification if available; broad test runs are not the default.');
+    } else {
+      if (relatedTests.length > 0) {
+        mode = 'targeted-tests-first';
+        reasons.push('relatedTests');
+        if (scripts.test) {
+          for (const testFile of relatedTests.slice(0, 2)) {
+            commands.push(buildScriptCommand(packageManager, 'test', [testFile]));
+          }
+        } else {
+          notes.push(`Run related tests first: ${relatedTests.slice(0, 2).join(', ')}`);
+        }
+      }
+
+      if (risky) {
+        reasons.push('riskySkillOrTask');
+        if (scripts.test) {
+          fallbackCommands.push(buildScriptCommand(packageManager, 'test'));
+        }
+      }
+
+      if (scripts.lint) {
+        fallbackCommands.push(buildScriptCommand(packageManager, 'lint'));
+      }
+      if (scripts.typecheck) {
+        fallbackCommands.push(buildScriptCommand(packageManager, 'typecheck'));
+      }
+
+      if (commands.length === 0 && scripts.test && risky) {
+        mode = 'broader-verification';
+        reasons.push('highRiskFallback');
+        commands.push(buildScriptCommand(packageManager, 'test'));
+      }
+    }
+
+    if (commands.length === 0 && fallbackCommands.length === 0) {
+      notes.push('Match verification effort to scope; no project test/lint/typecheck scripts were detected.');
+    }
+
+    const primaryCommandList = unique(commands);
+    const fallbackCommandList = unique(fallbackCommands.filter((command) => !primaryCommandList.includes(command)));
+    const reasonList = unique(reasons);
+    const noteList = unique(notes);
+
+    return {
+      taskType: effectiveTaskType,
+      packageManager,
+      mode,
+      commands: primaryCommandList,
+      fallbackCommands: fallbackCommandList,
+      reasons: reasonList,
+      notes: noteList,
+      executionPolicy: deriveExecutionPolicy({
+        taskType: effectiveTaskType,
+        mode,
+        commands: primaryCommandList,
+        fallbackCommands: fallbackCommandList,
+        reasons: reasonList,
+        context,
+      }),
+      context,
+    };
+  })().catch((error) => {
+    VERIFICATION_PLAN_CACHE.delete(verificationPlanCacheKey);
+    throw error;
+  });
+
+  setRecentCacheEntry(
+    VERIFICATION_PLAN_CACHE,
+    verificationPlanCacheKey,
+    planPromise,
+    MAX_VERIFICATION_PLAN_CACHE_ENTRIES,
+  );
+  return planPromise;
+}
+
+function summarizeContext(contextResult) {
+  const primaryTargets = unique(contextResult?.primaryTargets ?? []);
+  const relatedTests = unique([
+    ...(contextResult?.relatedTests ?? []),
+    ...primaryTargets.filter(isTestLikeFile),
+  ]);
+
+  return {
+    primaryTargets,
+    analogFiles: contextResult?.analogFiles ?? [],
+    sharedAbstractions: contextResult?.sharedAbstractions ?? [],
+    relatedTests,
+    styleFiles: contextResult?.styleFiles ?? [],
+  };
+}
+
+async function readPackageJson(rootDir) {
+  try {
+    const raw = await fs.readFile(path.join(rootDir, 'package.json'), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function readProjectVerificationFingerprint(rootDir) {
+  const entries = [];
+  let pkg = null;
+
+  try {
+    const packageJsonPath = path.join(rootDir, 'package.json');
+    const [raw, stat] = await Promise.all([
+      fs.readFile(packageJsonPath, 'utf8'),
+      fs.stat(packageJsonPath),
+    ]);
+    pkg = JSON.parse(raw);
+    entries.push({
+      filePath: 'package.json',
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+    });
+  } catch {
+    entries.push({
+      filePath: 'package.json',
+      size: null,
+      mtimeMs: null,
+    });
+  }
+
+  const trackedFiles = getDeclaredPackageManager(pkg)
+    ? []
+    : TRACKED_VERIFICATION_FILES.slice(1);
+
+  for (const relativePath of trackedFiles) {
+    const absolutePath = path.join(rootDir, relativePath);
+    try {
+      const stat = await fs.stat(absolutePath);
+      entries.push({
+        filePath: relativePath,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+      });
+    } catch {
+      entries.push({
+        filePath: relativePath,
+        size: null,
+        mtimeMs: null,
+      });
+    }
+  }
+
+  return {
+    pkg,
+    entries,
+    fingerprint: JSON.stringify(entries),
+  };
+}
+
+async function loadProjectVerificationEnvironment({
+  rootDir,
+  projectFingerprint,
+  fingerprintEntries = [],
+  pkg = null,
+}) {
+  const cacheKey = JSON.stringify({
+    rootDir,
+    projectFingerprint,
+  });
+  const cachedEnvironment = getRecentCacheEntry(PROJECT_VERIFICATION_ENV_CACHE, cacheKey);
+  if (cachedEnvironment) {
+    return cachedEnvironment;
+  }
+
+  const environmentPromise = Promise.resolve(pkg ?? readPackageJson(rootDir))
+    .then((resolvedPkg) => ({
+      pkg: resolvedPkg,
+      scripts: extractScripts(resolvedPkg),
+      packageManager: detectPackageManager({ fingerprintEntries, pkg: resolvedPkg }),
+    }))
+    .catch((error) => {
+      PROJECT_VERIFICATION_ENV_CACHE.delete(cacheKey);
+      throw error;
+    });
+
+  setRecentCacheEntry(
+    PROJECT_VERIFICATION_ENV_CACHE,
+    cacheKey,
+    environmentPromise,
+    MAX_VERIFICATION_ENV_CACHE_ENTRIES,
+  );
+  return environmentPromise;
+}
+
+function extractScripts(pkg = null) {
+  return pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+}
+
+function detectPackageManager({ fingerprintEntries = [], pkg = null } = {}) {
+  const declaredPackageManager = getDeclaredPackageManager(pkg);
+  if (declaredPackageManager) return declaredPackageManager;
+
+  const existingFiles = new Set(
+    fingerprintEntries
+      .filter((entry) => entry && entry.mtimeMs !== null)
+      .map((entry) => entry.filePath),
+  );
+  const checks = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lockb', 'bun'],
+    ['bun.lock', 'bun'],
+    ['package-lock.json', 'npm'],
+  ];
+
+  for (const [lockFile, pm] of checks) {
+    if (existingFiles.has(lockFile)) {
+      return pm;
+    }
+  }
+
+  return 'npm';
+}
+
+function getDeclaredPackageManager(pkg = null) {
+  const declared = String(pkg?.packageManager ?? '').toLowerCase();
+  if (declared.startsWith('pnpm')) return 'pnpm';
+  if (declared.startsWith('yarn')) return 'yarn';
+  if (declared.startsWith('bun')) return 'bun';
+  if (declared.startsWith('npm')) return 'npm';
+  return null;
+}
+
+function buildScriptCommand(packageManager, scriptName, args = []) {
+  const filteredArgs = args.filter(Boolean);
+
+  if (packageManager === 'npm') {
+    if (scriptName === 'test') {
+      return ['npm', 'test', filteredArgs.length > 0 ? '--' : '', ...filteredArgs]
+        .filter(Boolean)
+        .join(' ');
+    }
+
+    return ['npm', 'run', scriptName, filteredArgs.length > 0 ? '--' : '', ...filteredArgs]
+      .filter(Boolean)
+      .join(' ');
+  }
+
+  return [packageManager, scriptName, ...filteredArgs].join(' ');
+}
+
+function deriveExecutionPolicy({
+  taskType = 'simple',
+  mode = 'minimal',
+  commands = [],
+  fallbackCommands = [],
+  reasons = [],
+  context = {},
+} = {}) {
+  const relatedTests = context.relatedTests ?? [];
+  const sharedAbstractions = context.sharedAbstractions ?? [];
+  const docsOnly = mode === 'docs-only' || reasons.includes('docsOnly');
+  const risky = taskType === 'non-trivial'
+    || reasons.includes('riskySkillOrTask')
+    || reasons.includes('highRiskFallback');
+  const hasPrimaryCommands = commands.length > 0;
+  const hasTargetedPrimaryCommands = mode === 'targeted-tests-first' && hasPrimaryCommands;
+  const sharedScope = sharedAbstractions.length > 0;
+  const noRelatedTests = relatedTests.length === 0;
+  const broadOnlyPrimary = hasPrimaryCommands && !hasTargetedPrimaryCommands && noRelatedTests;
+  const requiresHumanConfirmationForBroadOrRisky = risky && broadOnlyPrimary;
+  const shouldAutoRunPrimaryCommands = hasPrimaryCommands && !docsOnly && !requiresHumanConfirmationForBroadOrRisky;
+  const shouldEscalateToFallbacks = !docsOnly && fallbackCommands.length > 0 && (risky || sharedScope);
+  const shouldAutoRunFallbacks = shouldEscalateToFallbacks && !requiresHumanConfirmationForBroadOrRisky;
+
+  let policyMode = 'recommend-only';
+  if (docsOnly) {
+    policyMode = 'docs-light';
+  } else if (hasTargetedPrimaryCommands && shouldEscalateToFallbacks) {
+    policyMode = 'auto-run-targeted-then-fallback';
+  } else if (hasTargetedPrimaryCommands) {
+    policyMode = 'auto-run-targeted';
+  } else if (requiresHumanConfirmationForBroadOrRisky) {
+    policyMode = 'confirm-then-broad';
+  } else if (shouldAutoRunPrimaryCommands) {
+    policyMode = 'auto-run-primary';
+  }
+
+  const policyReasons = unique([
+    ...reasons,
+    sharedScope ? 'sharedScope' : null,
+    noRelatedTests ? 'noRelatedTests' : null,
+  ]);
+
+  return {
+    policyMode,
+    shouldAutoRunPrimaryCommands,
+    shouldAutoRunTargetedVerification: hasTargetedPrimaryCommands && shouldAutoRunPrimaryCommands,
+    shouldEscalateToFallbacks,
+    shouldAutoRunFallbacks,
+    requiresHumanConfirmationForBroadOrRisky,
+    preferredOrder: [...commands, ...fallbackCommands],
+    reasons: policyReasons,
+  };
+}
+
+function buildVerificationPlanCacheKey({
+  rootDir,
+  projectFingerprint,
+  targetFile,
+  taskType,
+  skillIds = [],
+  context = {},
+} = {}) {
+  return JSON.stringify({
+    rootDir,
+    projectFingerprint,
+    targetFile: String(targetFile || '').trim(),
+    taskType: String(taskType || '').trim(),
+    skillIds: unique(skillIds).sort(),
+    context,
+  });
+}
+
+function getRecentCacheEntry(cache, key) {
+  if (!cache.has(key)) {
+    return null;
+  }
+
+  const value = cache.get(key);
+  cache.delete(key);
+  cache.set(key, value);
+  return value;
+}
+
+function setRecentCacheEntry(cache, key, value, maxEntries) {
+  if (cache.has(key)) {
+    cache.delete(key);
+  }
+
+  cache.set(key, value);
+
+  while (cache.size > maxEntries) {
+    const oldestKey = cache.keys().next().value;
+    cache.delete(oldestKey);
+  }
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function isTestLikeFile(filePath) {
+  return /\.(test|spec)\.[a-z0-9]+$/i.test(filePath)
+    || /(^|\/)(?:__tests__|tests?|specs?)\//i.test(filePath);
+}

package/src/manifest/loadManifest.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs/promises';
+import YAML from 'yaml';
+import { validateManifest } from './validateManifest.js';
+
+export async function loadManifest(manifestPath) {
+  const raw = await fs.readFile(manifestPath, 'utf8');
+
+  let parsed;
+  try {
+    parsed = YAML.parse(raw);
+  } catch (error) {
+    throw new Error(`Failed to parse manifest YAML: ${error.message}`);
+  }
+
+  const validation = validateManifest(parsed);
+  if (!validation.valid) {
+    const issues = validation.errors.map((error) => `- ${error}`).join('\n');
+    throw new Error(`Manifest validation failed:\n${issues}`);
+  }
+
+  return parsed;
+}

package/src/manifest/selectItems.js

@@ -0,0 +1,78 @@
+export const OPTIONAL_ADAPTER_ITEM_IDS = new Set([
+  'multi-antigravity-skills-link',
+  'multi-antigravity-ukit-link',
+  'multi-antigravity-rules',
+  'multi-antigravity-readme',
+  'multi-codex-skills-link',
+  'multi-codex-ukit-link',
+  'multi-codex-readme',
+  'multi-codex-settings-json',
+  'multi-codex-settings-local',
+  'multi-opencode-config',
+]);
+
+function resolveItemOrder(items) {
+  const itemById = new Map(items.map((item) => [item.id, item]));
+  const visiting = new Set();
+  const visited = new Set();
+  const ordered = [];
+
+  function visit(item) {
+    if (visited.has(item.id)) {
+      return;
+    }
+
+    if (visiting.has(item.id)) {
+      throw new Error(`Manifest dependency cycle detected at item: ${item.id}`);
+    }
+
+    visiting.add(item.id);
+
+    for (const dependencyId of item.requires ?? []) {
+      const dependencyItem = itemById.get(dependencyId);
+      if (!dependencyItem) {
+        throw new Error(`Manifest item ${item.id} requires missing item: ${dependencyId}`);
+      }
+
+      visit(dependencyItem);
+    }
+
+    visiting.delete(item.id);
+    visited.add(item.id);
+    ordered.push(item);
+  }
+
+  for (const item of items) {
+    visit(item);
+  }
+
+  return ordered;
+}
+
+export function selectManifestItems({ items, detectedPacks, selectedAdapterItemIds }) {
+  const packSet = detectedPacks ? new Set(detectedPacks) : null;
+  const selectedAdapterSet = selectedAdapterItemIds
+    ? new Set(selectedAdapterItemIds)
+    : null;
+
+  const selected = items.filter((item) => {
+    if (item.enabledByDefault === false) return false;
+    if (packSet && Array.isArray(item.packs) && item.packs.length > 0) {
+      if (!item.packs.some((pack) => packSet.has(pack))) {
+        return false;
+      }
+    }
+
+    if (
+      selectedAdapterSet &&
+      OPTIONAL_ADAPTER_ITEM_IDS.has(item.id) &&
+      !selectedAdapterSet.has(item.id)
+    ) {
+      return false;
+    }
+
+    return true;
+  });
+
+  return resolveItemOrder(selected);
+}

package/src/manifest/validateManifest.js

@@ -0,0 +1,115 @@
+import path from 'node:path';
+
+const VALID_ITEM_TYPES = new Set(['command', 'skill', 'agent', 'hook', 'config', 'link']);
+const VALID_MERGE_STRATEGIES = new Set(['overwrite_with_backup', 'skip', 'append', 'prepend']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+function containsPathTraversal(rawPath) {
+  const normalized = path.posix.normalize(rawPath.replaceAll('\\', '/'));
+  // Also check for bare '..' — path.posix.normalize('..') returns '..' (no
+  // trailing slash), so the startsWith('../') check misses it.
+  return normalized === '..' || normalized.startsWith('../') || normalized.includes('/../');
+}
+
+export function validateManifest(manifest) {
+  const errors = [];
+
+  if (!isPlainObject(manifest)) {
+    return { valid: false, errors: ['Manifest root must be an object.'] };
+  }
+
+  if (typeof manifest.version !== 'number' && typeof manifest.version !== 'string') {
+    errors.push('Manifest `version` must be a number or string.');
+  }
+
+  if (typeof manifest.name !== 'string' || manifest.name.trim() === '') {
+    errors.push('Manifest `name` must be a non-empty string.');
+  }
+
+  if (!Array.isArray(manifest.items) || manifest.items.length === 0) {
+    errors.push('Manifest `items` must be a non-empty array.');
+    return { valid: errors.length === 0, errors };
+  }
+
+  const seenIds = new Set();
+
+  for (let index = 0; index < manifest.items.length; index += 1) {
+    const item = manifest.items[index];
+    const prefix = `items[${index}]`;
+
+    if (!isPlainObject(item)) {
+      errors.push(`${prefix} must be an object.`);
+      continue;
+    }
+
+    if (typeof item.id !== 'string' || item.id.trim() === '') {
+      errors.push(`${prefix}.id must be a non-empty string.`);
+    } else if (seenIds.has(item.id)) {
+      errors.push(`${prefix}.id must be unique. Duplicate: ${item.id}`);
+    } else {
+      seenIds.add(item.id);
+    }
+
+    if (!VALID_ITEM_TYPES.has(item.type)) {
+      errors.push(`${prefix}.type must be one of: ${Array.from(VALID_ITEM_TYPES).join(', ')}`);
+    }
+
+    if (typeof item.sourceTemplate !== 'string' || item.sourceTemplate.trim() === '') {
+      errors.push(`${prefix}.sourceTemplate must be a non-empty string.`);
+    } else {
+      if (path.isAbsolute(item.sourceTemplate)) {
+        errors.push(`${prefix}.sourceTemplate must be a relative path.`);
+      }
+
+      if (containsPathTraversal(item.sourceTemplate)) {
+        errors.push(`${prefix}.sourceTemplate must not contain path traversal segments.`);
+      }
+    }
+
+    if (typeof item.targetPath !== 'string' || item.targetPath.trim() === '') {
+      errors.push(`${prefix}.targetPath must be a non-empty string.`);
+    } else {
+      if (path.isAbsolute(item.targetPath)) {
+        errors.push(`${prefix}.targetPath must be a relative path.`);
+      }
+
+      if (containsPathTraversal(item.targetPath)) {
+        errors.push(`${prefix}.targetPath must not contain path traversal segments.`);
+      }
+    }
+
+    if (item.type !== 'link' && !VALID_MERGE_STRATEGIES.has(item.mergeStrategy)) {
+      errors.push(
+        `${prefix}.mergeStrategy must be one of: ${Array.from(VALID_MERGE_STRATEGIES).join(', ')}`,
+      );
+    }
+
+    if (typeof item.enabledByDefault !== 'boolean') {
+      errors.push(`${prefix}.enabledByDefault must be a boolean.`);
+    }
+
+    if (item.requires !== undefined && !isStringArray(item.requires)) {
+      errors.push(`${prefix}.requires must be an array of strings when provided.`);
+    }
+
+    if (item.variables !== undefined && !isStringArray(item.variables)) {
+      errors.push(`${prefix}.variables must be an array of strings when provided.`);
+    }
+
+    if (item.packs !== undefined && !isStringArray(item.packs)) {
+      errors.push(`${prefix}.packs must be an array of strings when provided.`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/render/buildVariables.js

@@ -0,0 +1,39 @@
+export function buildTemplateVariables({ projectContext, stackContext, packageVersion, providerContext }) {
+  return {
+    project: {
+      name: projectContext.project.name,
+      root: projectContext.project.root,
+      stack: stackContext.detectedPacks.join(','),
+    },
+    runtime: {
+      packageManager: projectContext.runtime.packageManager,
+      os: projectContext.runtime.os,
+      nodeVersion: projectContext.runtime.nodeVersion,
+    },
+    stack: {
+      // original flags
+      frontend: stackContext.flags.frontend,
+      backendApi: stackContext.flags.backendApi,
+      postgres: stackContext.flags.postgres,
+      // new context flags
+      typescript: stackContext.flags.typescript ?? false,
+      testing: stackContext.flags.testing ?? false,
+      nuxt: stackContext.flags.nuxt ?? false,
+      next: stackContext.flags.next ?? false,
+      flutter: stackContext.flags.flutter ?? false,
+      reactNative: stackContext.flags.reactNative ?? false,
+      docker: stackContext.flags.docker ?? false,
+      monorepo: stackContext.flags.monorepo ?? false,
+      git: stackContext.flags.git ?? false,
+    },
+    providers: {
+      unic: providerContext.providers?.unic?.supported ?? false,
+    },
+    ukit: {
+      version: packageVersion,
+    },
+    user: {
+      profile: 'default',
+    },
+  };
+}