nexakit 0.0.0-stage → 0.2.0

package/src/skill-catalog-audit.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { loadSkillCatalog, resolveCatalogResource, SkillCatalogError } from './skill-catalog.js';
+import { hashSkillFiles, readSkillFiles } from './skill-files.js';
+import { scanSkillFiles } from './skill-scan.js';
+
+// Re-exported so existing callers keep their import path.
+export { hashSkillFiles, readSkillFiles };
+
+export const DEFAULT_CATALOG_ROOT = fileURLToPath(new URL('../', import.meta.url));
+
+// This inventory is read-only; updating the manifest remains an explicit authoring step.
+export async function inventoryCatalogSkill({ toolkitRoot = DEFAULT_CATALOG_ROOT, installedPath } = {}) {
+  if (!/^(?:skills|catalogs\/skills)\/[a-z0-9-]+$/u.test(installedPath ?? '')) {
+    throw new SkillCatalogError('La carpeta debe ser skills/<nombre> o catalogs/skills/<nombre>.');
+  }
+  const root = await resolveCatalogResource(toolkitRoot, installedPath);
+  return hashSkillFiles(await readSkillFiles(root, installedPath));
+}
+
+export async function auditSkillCatalog({ toolkitRoot = DEFAULT_CATALOG_ROOT } = {}) {
+  const report = { ok: false, skillsCount: 0, verifiedSkillsCount: 0, errors: [], warnings: [] };
+  let catalog;
+  try {
+    const catalogPath = await resolveCatalogResource(toolkitRoot, 'catalogs/skills.json');
+    catalog = await loadSkillCatalog({ catalogUrl: pathToFileURL(catalogPath) });
+  } catch (error) {
+    report.errors.push(error.message);
+    return report;
+  }
+  report.skillsCount = catalog.skills.length;
+  for (const skill of catalog.skills) {
+    try {
+      if (!/^(?:skills|catalogs\/skills)\/[a-z0-9-]+$/u.test(skill.installedPath ?? '')) {
+        throw new SkillCatalogError('La carpeta debe ser skills/<nombre> o catalogs/skills/<nombre>.');
+      }
+      const bytes = await readSkillFiles(await resolveCatalogResource(toolkitRoot, skill.installedPath), skill.installedPath);
+      const actual = hashSkillFiles(bytes);
+      const expected = [...skill.files].sort((a, b) => a.path.localeCompare(b.path));
+      if (actual.length !== expected.length || actual.some((file, index) => file.path !== expected[index].path || file.sha256 !== expected[index].sha256)) {
+        throw new SkillCatalogError(`${skill.name}: inventario o hashes SHA-256 distintos del manifiesto.`);
+      }
+      report.verifiedSkillsCount++;
+      const scan = scanSkillFiles(bytes);
+      for (const f of scan.findings) {
+        if (f.severity === 'bloqueo') report.errors.push(`${skill.name}: bloqueo del escáner (${f.rule} en ${f.file}:${f.line}).`);
+        else if (f.severity === 'aviso') report.warnings.push(`${skill.name}: aviso del escáner (${f.rule} en ${f.file}:${f.line}).`);
+      }
+      for (const [capability, detected] of Object.entries(scan.capabilities)) {
+        if (detected && skill.review.capabilities[capability] === 'none') report.warnings.push(`${skill.name}: capacidad no declarada: ${capability}.`);
+      }
+      if (!skill.scenarios.some(scenario => scenario.status === 'passed')) report.warnings.push(`${skill.name}: sin escenario funcional pasado; no acredita utilidad.`);
+      if (skill.review.status === 'pending' || skill.review.status === 'rejected') report.warnings.push(`${skill.name}: revisión ${skill.review.status}; no puede recomendarse.`);
+    } catch (error) {
+      report.errors.push(error.message);
+    }
+  }
+  // Anything left in catalogs/skills without an entry (an interrupted registration, a stray copy) would ship in the package.
+  const listed = new Set(catalog.skills.map(skill => skill.installedPath));
+  const entries = await fs.readdir(path.join(toolkitRoot, 'catalogs/skills'), { withFileTypes: true }).catch(() => []);
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const rel = `catalogs/skills/${entry.name}`;
+    if (!listed.has(rel)) report.warnings.push(`Carpeta sin entrada en el catálogo: ${rel}.`);
+  }
+  report.ok = report.errors.length === 0;
+  return report;
+}

package/src/skill-catalog.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import schema from '../schemas/skill-catalog.schema.json' with { type: 'json' };
+
+const DEFAULT_CATALOG_URL = new URL('../catalogs/skills.json', import.meta.url);
+
+let compiledValidator = null;
+function getValidator() {
+  if (!compiledValidator) {
+    const ajv = new Ajv2020({ strict: true, allErrors: true });
+    compiledValidator = ajv.compile(schema);
+  }
+  return compiledValidator;
+}
+
+export class SkillCatalogError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SkillCatalogError';
+    this.code = 'SKILL_CATALOG_INVALID';
+  }
+}
+
+function isSafeRelativeSubpath(relPath) {
+  if (typeof relPath !== 'string' || !relPath || relPath.startsWith('/') || relPath.includes('\\') || relPath.includes('\0')) {
+    return false;
+  }
+  const normalized = path.posix.normalize(relPath);
+  if (normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized !== relPath) {
+    return false;
+  }
+  return relPath.split('/').every(segment => segment.length > 0 && segment !== '.' && segment !== '..');
+}
+
+function deepFreeze(value) {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}
+
+export function validateSkillCatalog(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new SkillCatalogError('El catálogo de skills debe ser un objeto JSON válido.');
+  }
+  const copy = structuredClone(value);
+  const validate = getValidator();
+  if (!validate(copy)) {
+    throw new SkillCatalogError('El catálogo de skills no cumple el esquema requerido.');
+  }
+
+  const seenSkills = new Set();
+  for (const skill of copy.skills) {
+    if (seenSkills.has(skill.name)) {
+      throw new SkillCatalogError(`Skill duplicada en el catálogo: ${skill.name}.`);
+    }
+    seenSkills.add(skill.name);
+
+    if (skill.installedPath !== `skills/${skill.name}` && skill.installedPath !== `catalogs/skills/${skill.name}`) {
+      throw new SkillCatalogError(`Ruta instalada incoherente para ${skill.name}.`);
+    }
+    if (!isSafeRelativeSubpath(skill.sourcePath)) {
+      throw new SkillCatalogError(`Ruta origen inválida para ${skill.name}.`);
+    }
+
+    const seenFiles = new Set();
+    let hasSkillMd = false;
+    for (const file of skill.files) {
+      if (!isSafeRelativeSubpath(file.path)) {
+        throw new SkillCatalogError(`Ruta de archivo fuera de alcance en ${skill.name}: ${file.path}.`);
+      }
+      if (seenFiles.has(file.path)) {
+        throw new SkillCatalogError(`Archivo repetido en el manifiesto de ${skill.name}: ${file.path}.`);
+      }
+      seenFiles.add(file.path);
+      if (file.path === 'SKILL.md') hasSkillMd = true;
+    }
+    if (!hasSkillMd) {
+      throw new SkillCatalogError(`Falta SKILL.md en el manifiesto de ${skill.name}.`);
+    }
+
+    const scenarioIds = new Set();
+    for (const scenario of skill.scenarios) {
+      if (scenarioIds.has(scenario.id)) throw new SkillCatalogError(`Escenario duplicado en ${skill.name}: ${scenario.id}.`);
+      scenarioIds.add(scenario.id);
+      if (scenario.revision !== skill.revision) {
+        throw new SkillCatalogError(`El escenario ${scenario.id} de ${skill.name} apunta a otra revisión.`);
+      }
+      if (!skill.matching.profiles.includes(scenario.profile)) {
+        throw new SkillCatalogError(`El escenario ${scenario.id} de ${skill.name} usa un perfil no cubierto.`);
+      }
+      if (!skill.matching.taskClasses.includes(scenario.taskClass)) {
+        throw new SkillCatalogError(`El escenario ${scenario.id} de ${skill.name} usa una clase de tarea no cubierta.`);
+      }
+      if (!isSafeRelativeSubpath(scenario.evidencePath)) {
+        throw new SkillCatalogError(`Ruta de evidencia inválida en el escenario ${scenario.id}.`);
+      }
+    }
+  }
+
+  const seenRefs = new Set();
+  for (const ref of copy.externalReferences) {
+    if (seenSkills.has(ref.name) || seenRefs.has(ref.name)) {
+      throw new SkillCatalogError(`Referencia externa duplicada: ${ref.name}.`);
+    }
+    seenRefs.add(ref.name);
+  }
+
+  const seenAddons = new Set();
+  for (const addon of copy.addons) {
+    if (seenAddons.has(addon.id)) {
+      throw new SkillCatalogError(`Añadido duplicado en el catálogo: ${addon.id}.`);
+    }
+    seenAddons.add(addon.id);
+  }
+
+  return deepFreeze(copy);
+}
+
+// Refuse symbolic parents as well as symbolic files when checking catalog resources.
+export async function resolveCatalogResource(toolkitRoot, relativePath) {
+  if (!isSafeRelativeSubpath(relativePath)) throw new SkillCatalogError('Ruta de recurso de catálogo inválida.');
+  let target = await fs.realpath(toolkitRoot);
+  const segments = relativePath.split('/');
+  for (let i = 0; i < segments.length; i++) {
+    target = path.join(target, segments[i]);
+    const stat = await fs.lstat(target);
+    if (stat.isSymbolicLink() || (i < segments.length - 1 && !stat.isDirectory())) {
+      throw new SkillCatalogError(`Recurso del catálogo con enlace o padre no regular: ${relativePath}.`);
+    }
+  }
+  return target;
+}
+
+export async function loadSkillCatalog({ catalogUrl = DEFAULT_CATALOG_URL } = {}) {
+  let raw;
+  try {
+    const stat = await fs.lstat(catalogUrl);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2 * 1024 * 1024) {
+      throw new SkillCatalogError('El catálogo debe ser un archivo regular de hasta 2 MiB, sin enlaces simbólicos.');
+    }
+    raw = await fs.readFile(catalogUrl, 'utf8');
+  } catch (error) {
+    if (error instanceof SkillCatalogError) throw error;
+    throw new SkillCatalogError('No se pudo leer el catálogo confiable de skills.');
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new SkillCatalogError('El catálogo de skills no contiene JSON válido.');
+  }
+  const catalog = validateSkillCatalog(parsed);
+  const filename = catalogUrl instanceof URL ? fileURLToPath(catalogUrl) : path.resolve(catalogUrl);
+  const toolkitRoot = path.dirname(path.dirname(filename));
+  for (const skill of catalog.skills) {
+    for (const scenario of skill.scenarios.filter(item => item.status === 'passed')) {
+      try {
+        const evidencePath = await resolveCatalogResource(toolkitRoot, scenario.evidencePath);
+        const stat = await fs.lstat(evidencePath);
+        if (!stat.isFile() || stat.size === 0 || stat.size > 512 * 1024) throw new Error('Invalid evidence file');
+      } catch {
+        throw new SkillCatalogError(`Evidencia ausente, vacía o no regular para ${skill.name}/${scenario.id}: ${scenario.evidencePath}.`);
+      }
+    }
+  }
+  return catalog;
+}

package/src/skill-files.js

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { SkillCatalogError } from './skill-catalog.js';
+
+export function hashSkillFiles(files) {
+  return files
+    .map(file => ({ path: file.path, sha256: createHash('sha256').update(file.bytes).digest('hex') }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// The one safe walk of a skill folder: no links, only regular files, bounded size. Never executes anything.
+export async function readSkillFiles(root, label) {
+  if (!(await fs.lstat(root)).isDirectory()) throw new SkillCatalogError(`No es una carpeta de skill: ${label}.`);
+  const files = [];
+  let totalBytes = 0;
+  async function visit(dir, prefix = '') {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (rel.length > 200 || rel.split('/').length > 32) throw new SkillCatalogError(`Ruta demasiado larga en ${label}.`);
+      const full = path.join(dir, entry.name);
+      const stat = await fs.lstat(full);
+      if (stat.isSymbolicLink()) throw new SkillCatalogError(`Enlace no admitido en ${label}/${rel}.`);
+      if (stat.isDirectory()) await visit(full, rel);
+      else if (stat.isFile()) {
+        if (files.length >= 256 || stat.size > 512 * 1024 || totalBytes + stat.size > 64 * 1024 * 1024) {
+          throw new SkillCatalogError(`Límite de archivos o tamaño excedido en ${label}.`);
+        }
+        const bytes = await fs.readFile(full);
+        totalBytes += bytes.length;
+        files.push({ path: rel, bytes });
+      } else throw new SkillCatalogError(`Archivo no regular en ${label}/${rel}.`);
+    }
+  }
+  await visit(root);
+  if (!files.some(file => file.path === 'SKILL.md')) throw new SkillCatalogError(`Falta SKILL.md en ${label}.`);
+  return files;
+}