@open-skills-hub/api 1.0.0

package/src/controllers/skills.ts

@@ -0,0 +1,489 @@
+/**
+ * Open Skills Hub - Skills Controller
+ */
+
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import {
+  getStorage,
+  generateUUID,
+  now,
+  sha256,
+  buildSkillFullName,
+  parseSkillFullName,
+  AppError,
+  ErrorCodes,
+} from '@open-skills-hub/core';
+import type { Skill, Version, SkillContent, AuditLog } from '@open-skills-hub/core';
+import { sendSuccess, sendError } from '../middleware/error.js';
+import { logger } from '../middleware/logger.js';
+import type {
+  SkillNameParam,
+  SkillVersionParam,
+  CreateSkillBody,
+  UpdateSkillBody,
+  PublishVersionBody,
+  PaginationQuery,
+  SearchQuery,
+} from '../middleware/validation.js';
+// Re-export for use in routes
+export type { SearchQuery };
+
+/**
+ * Search skills
+ */
+export async function searchSkills(
+  request: FastifyRequest<{ Querystring: SearchQuery }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { q, category, author, sort, order, cursor, limit } = request.query;
+
+  const result = await storage.searchSkills({
+    query: q,
+    category,
+    author,
+    sort,
+    order,
+    cursor,
+    limit,
+  });
+
+  sendSuccess(request, reply, result.items, 200, result.pagination);
+}
+
+/**
+ * Get skill by name
+ */
+export async function getSkillByName(
+  request: FastifyRequest<{ Params: SkillNameParam }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+
+  // Parse name (might be scoped like @scope/name)
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const skill = await storage.getSkillByName(fullName);
+  if (!skill) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Skill '${fullName}' not found`,
+      404
+    );
+  }
+
+  // Get latest version info
+  const latestVersion = await storage.getLatestVersion(skill.id);
+
+  sendSuccess(request, reply, {
+    ...skill,
+    latestVersionDetails: latestVersion ? {
+      version: latestVersion.version,
+      publishedAt: latestVersion.publishedAt,
+      securityLevel: latestVersion.securityLevel,
+    } : undefined,
+  });
+}
+
+/**
+ * Get skill content (fetch-on-use)
+ */
+export async function getSkillContent(
+  request: FastifyRequest<{ Params: SkillNameParam; Querystring: { version?: string } }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+  const { version: requestedVersion } = request.query;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const skill = await storage.getSkillByName(fullName);
+  if (!skill) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Skill '${fullName}' not found`,
+      404
+    );
+  }
+
+  // Get version
+  let version: Version | null;
+  if (requestedVersion) {
+    version = await storage.getVersion(skill.id, requestedVersion);
+    if (!version) {
+      throw new AppError(
+        ErrorCodes.VERSION_NOT_FOUND,
+        `Version '${requestedVersion}' not found for skill '${fullName}'`,
+        404
+      );
+    }
+  } else {
+    version = await storage.getLatestVersion(skill.id);
+    if (!version) {
+      throw new AppError(
+        ErrorCodes.VERSION_NOT_FOUND,
+        `No versions found for skill '${fullName}'`,
+        404
+      );
+    }
+  }
+
+  // Increment use counters
+  await Promise.all([
+    storage.incrementSkillUses(skill.id),
+    storage.incrementVersionUses(version.id),
+  ]);
+
+  // Record use
+  const useRecord = {
+    id: generateUUID(),
+    skillId: skill.id,
+    versionId: version.id,
+    userId: request.user?.id,
+    source: 'api' as const,
+    cacheHit: false,
+    clientVersion: request.headers['x-client-version'] as string | undefined,
+    platform: request.headers['x-platform'] as string | undefined,
+    arch: request.headers['x-arch'] as string | undefined,
+    ip: request.ip,
+    userAgent: request.headers['user-agent'],
+    createdAt: now(),
+  };
+  await storage.createUseRecord(useRecord);
+
+  sendSuccess(request, reply, {
+    skill: {
+      name: skill.fullName,
+      displayName: skill.displayName,
+      description: skill.description,
+      securityLevel: skill.securityLevel,
+    },
+    version: version.version,
+    content: version.content,
+    packageHash: version.packageHash,
+    securityScore: version.securityScore,
+    securityLevel: version.securityLevel,
+  });
+}
+
+/**
+ * Create/publish a new skill
+ */
+export async function createSkill(
+  request: FastifyRequest<{ Body: CreateSkillBody }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const body = request.body;
+  const userId = request.user?.id;
+
+  // Build full name
+  const fullName = buildSkillFullName(body.name, body.scope);
+
+  // Check if skill already exists
+  const existing = await storage.getSkillByName(fullName);
+  if (existing) {
+    throw new AppError(
+      ErrorCodes.SKILL_EXISTS,
+      `Skill '${fullName}' already exists`,
+      409
+    );
+  }
+
+  // Calculate content hash
+  const contentString = JSON.stringify(body.content);
+  const contentHash = sha256(contentString);
+
+  const skillId = generateUUID();
+  const versionId = generateUUID();
+  const timestamp = now();
+
+  // Extract author from frontmatter or use userId
+  const author = body.content.frontmatter.author || userId || 'anonymous';
+  const ownerType = (body.scope || author.startsWith('@')) ? 'organization' : 'user';
+
+  // Create skill
+  const skill: Skill = {
+    id: skillId,
+    name: body.name,
+    scope: body.scope,
+    fullName,
+    ownerId: author,
+    ownerType,
+    displayName: body.displayName,
+    description: body.description,
+    category: body.category,
+    keywords: body.keywords,
+    license: body.license,
+    repository: body.repository,
+    homepage: body.homepage,
+    latestVersion: body.version,
+    latestVersionId: versionId,
+    visibility: body.visibility,
+    status: 'active',
+    stats: { totalUses: 0, weeklyUses: 0, monthlyUses: 0, versionCount: 1, derivationCount: 0 },
+    rating: { average: 0, count: 0 },
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    publishedAt: timestamp,
+  };
+
+  // Create version
+  const version: Version = {
+    id: versionId,
+    skillId,
+    version: body.version,
+    tag: 'latest',
+    content: body.content,
+    packageUrl: `local://${fullName}/${body.version}`,
+    packageSize: contentString.length,
+    packageHash: contentHash,
+    changelog: body.changelog,
+    status: 'published',
+    publishedBy: author,
+    uses: 0,
+    createdAt: timestamp,
+    publishedAt: timestamp,
+  };
+
+  // Save to storage
+  await storage.createSkill(skill);
+  await storage.createVersion(version);
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp,
+    eventType: 'skill.published',
+    actor: {
+      type: request.user?.type ?? 'user',
+      id: userId,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'skill',
+      id: skillId,
+      name: fullName,
+      version: body.version,
+    },
+    action: 'create',
+    result: 'success',
+    details: {
+      visibility: body.visibility,
+      category: body.category,
+    },
+  };
+  await storage.createAuditLog(auditLog);
+
+  logger.info('Skill published', { skillId, fullName, version: body.version });
+
+  sendSuccess(request, reply, { skill, version }, 201);
+}
+
+/**
+ * Update skill metadata
+ */
+export async function updateSkill(
+  request: FastifyRequest<{ Params: SkillNameParam; Body: UpdateSkillBody }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+  const updates = request.body;
+  const userId = request.user?.id;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const skill = await storage.getSkillByName(fullName);
+  if (!skill) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Skill '${fullName}' not found`,
+      404
+    );
+  }
+
+  // Check ownership (simplified - in production, check more thoroughly)
+  if (skill.ownerId && skill.ownerId !== userId && request.user?.type !== 'system') {
+    throw new AppError(
+      ErrorCodes.FORBIDDEN,
+      'You do not have permission to update this skill',
+      403
+    );
+  }
+
+  // Build update object (remove null values to unset optional fields)
+  const updateData: Partial<Skill> = {};
+  if (updates.displayName !== undefined) updateData.displayName = updates.displayName;
+  if (updates.description !== undefined) updateData.description = updates.description;
+  if (updates.category !== undefined) updateData.category = updates.category;
+  if (updates.keywords !== undefined) updateData.keywords = updates.keywords;
+  if (updates.repository !== undefined) updateData.repository = updates.repository ?? undefined;
+  if (updates.homepage !== undefined) updateData.homepage = updates.homepage ?? undefined;
+  if (updates.visibility !== undefined) updateData.visibility = updates.visibility;
+
+  const updated = await storage.updateSkill(skill.id, updateData);
+
+  if (!updated) {
+    throw new AppError(
+      ErrorCodes.INTERNAL_ERROR,
+      'Failed to update skill',
+      500
+    );
+  }
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp: now(),
+    eventType: 'skill.updated',
+    actor: {
+      type: request.user?.type ?? 'user',
+      id: userId,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'skill',
+      id: skill.id,
+      name: fullName,
+    },
+    action: 'update',
+    result: 'success',
+    changes: {
+      before: skill,
+      after: updated,
+    },
+  };
+  await storage.createAuditLog(auditLog);
+
+  logger.info('Skill updated', { skillId: skill.id, fullName });
+
+  sendSuccess(request, reply, updated);
+}
+
+/**
+ * Delete/deprecate a skill
+ */
+export async function deleteSkill(
+  request: FastifyRequest<{ Params: SkillNameParam; Querystring: { hard?: string } }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+  const { hard } = request.query;
+  const userId = request.user?.id;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const skill = await storage.getSkillByName(fullName);
+  if (!skill) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Skill '${fullName}' not found`,
+      404
+    );
+  }
+
+  // Check ownership
+  if (skill.ownerId && skill.ownerId !== userId && request.user?.type !== 'system') {
+    throw new AppError(
+      ErrorCodes.FORBIDDEN,
+      'You do not have permission to delete this skill',
+      403
+    );
+  }
+
+  let result: boolean;
+  if (hard === 'true') {
+    // Hard delete
+    result = await storage.deleteSkill(skill.id);
+  } else {
+    // Soft delete (mark as deleted)
+    const updated = await storage.updateSkill(skill.id, { status: 'deleted' });
+    result = !!updated;
+  }
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp: now(),
+    eventType: 'skill.deleted',
+    actor: {
+      type: request.user?.type ?? 'user',
+      id: userId,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'skill',
+      id: skill.id,
+      name: fullName,
+    },
+    action: hard === 'true' ? 'hard_delete' : 'soft_delete',
+    result: result ? 'success' : 'failure',
+  };
+  await storage.createAuditLog(auditLog);
+
+  logger.info('Skill deleted', { skillId: skill.id, fullName, hard: hard === 'true' });
+
+  sendSuccess(request, reply, { deleted: result });
+}
+
+/**
+ * Get skills by owner
+ */
+export async function getSkillsByOwner(
+  request: FastifyRequest<{ Params: { ownerId: string }; Querystring: PaginationQuery }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { ownerId } = request.params;
+  const { cursor, limit } = request.query;
+
+  const result = await storage.getSkillsByOwner(ownerId, { cursor, limit });
+
+  sendSuccess(request, reply, result.items, 200, result.pagination);
+}
+
+/**
+ * Get derived skills
+ */
+export async function getDerivedSkills(
+  request: FastifyRequest<{ Params: SkillNameParam; Querystring: PaginationQuery }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+  const { cursor, limit } = request.query;
+
+  // Parse name
+  const { scope, name: skillName } = parseSkillFullName(name);
+  const fullName = buildSkillFullName(skillName, scope);
+
+  const skill = await storage.getSkillByName(fullName);
+  if (!skill) {
+    throw new AppError(
+      ErrorCodes.SKILL_NOT_FOUND,
+      `Skill '${fullName}' not found`,
+      404
+    );
+  }
+
+  const result = await storage.getDerivedSkills(skill.id, { cursor, limit });
+
+  sendSuccess(request, reply, result.items, 200, result.pagination);
+}