@open-skills-hub/api 1.0.0

package/src/controllers/versions.ts

@@ -0,0 +1,427 @@
+/**
+ * Open Skills Hub - Versions Controller
+ */
+
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import {
+  getStorage,
+  generateUUID,
+  now,
+  sha256,
+  buildSkillFullName,
+  parseSkillFullName,
+  AppError,
+  ErrorCodes,
+} from '@open-skills-hub/core';
+import type { Version, AuditLog } from '@open-skills-hub/core';
+import { sendSuccess } from '../middleware/error.js';
+import { logger } from '../middleware/logger.js';
+import type {
+  SkillNameParam,
+  SkillVersionParam,
+  PublishVersionBody,
+  PaginationQuery,
+} from '../middleware/validation.js';
+
+/**
+ * Get all versions of a skill
+ */
+export async function getVersions(
+  request: FastifyRequest<{ Params: SkillNameParam; Querystring: PaginationQuery & { includeDeprecated?: string } }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+  const { cursor, limit, includeDeprecated } = 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.getVersions(skill.id, {
+    cursor,
+    limit,
+    includeDeprecated: includeDeprecated === 'true',
+  });
+
+  // Map versions to public format (exclude full content)
+  const versions = result.items.map(v => ({
+    id: v.id,
+    version: v.version,
+    tag: v.tag,
+    status: v.status,
+    securityScore: v.securityScore,
+    securityLevel: v.securityLevel,
+    uses: v.uses,
+    changelog: v.changelog,
+    publishedAt: v.publishedAt,
+    deprecatedAt: v.deprecatedAt,
+    deprecatedMessage: v.deprecatedMessage,
+  }));
+
+  sendSuccess(request, reply, versions, 200, result.pagination);
+}
+
+/**
+ * Get a specific version
+ */
+export async function getVersion(
+  request: FastifyRequest<{ Params: SkillVersionParam }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name, version: versionStr } = request.params;
+
+  // 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 version = await storage.getVersion(skill.id, versionStr);
+  if (!version) {
+    throw new AppError(
+      ErrorCodes.VERSION_NOT_FOUND,
+      `Version '${versionStr}' not found for skill '${fullName}'`,
+      404
+    );
+  }
+
+  sendSuccess(request, reply, {
+    id: version.id,
+    skillId: version.skillId,
+    version: version.version,
+    tag: version.tag,
+    status: version.status,
+    securityScore: version.securityScore,
+    securityLevel: version.securityLevel,
+    uses: version.uses,
+    changelog: version.changelog,
+    packageSize: version.packageSize,
+    packageHash: version.packageHash,
+    publishedAt: version.publishedAt,
+    deprecatedAt: version.deprecatedAt,
+    deprecatedMessage: version.deprecatedMessage,
+    content: version.content,
+  });
+}
+
+/**
+ * Publish a new version
+ */
+export async function publishVersion(
+  request: FastifyRequest<{ Params: SkillNameParam; Body: PublishVersionBody }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name } = request.params;
+  const body = 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
+  if (skill.ownerId && skill.ownerId !== userId && request.user?.type !== 'system') {
+    throw new AppError(
+      ErrorCodes.FORBIDDEN,
+      'You do not have permission to publish versions for this skill',
+      403
+    );
+  }
+
+  // Check if version already exists
+  const existingVersion = await storage.getVersion(skill.id, body.version);
+  if (existingVersion) {
+    throw new AppError(
+      ErrorCodes.VERSION_EXISTS,
+      `Version '${body.version}' already exists for skill '${fullName}'`,
+      409
+    );
+  }
+
+  // Calculate content hash
+  const contentString = JSON.stringify(body.content);
+  const contentHash = sha256(contentString);
+
+  const versionId = generateUUID();
+  const timestamp = now();
+
+  // Create version
+  const version: Version = {
+    id: versionId,
+    skillId: skill.id,
+    version: body.version,
+    tag: body.tag,
+    content: body.content,
+    packageUrl: `local://${fullName}/${body.version}`,
+    packageSize: contentString.length,
+    packageHash: contentHash,
+    changelog: body.changelog,
+    status: 'published',
+    publishedBy: userId,
+    uses: 0,
+    createdAt: timestamp,
+    publishedAt: timestamp,
+  };
+
+  await storage.createVersion(version);
+
+  // Update 'latest' tag on previous version
+  const versions = await storage.getVersions(skill.id, { limit: 100 });
+  for (const v of versions.items) {
+    if (v.id !== versionId && v.tag === 'latest') {
+      await storage.updateVersion(v.id, { tag: undefined });
+    }
+  }
+
+  // Set latest tag on new version if specified
+  if (body.tag === 'latest' || !body.tag) {
+    await storage.updateVersion(versionId, { tag: 'latest' });
+  }
+
+  // Update skill's latest version
+  await storage.updateSkill(skill.id, {
+    latestVersion: body.version,
+    latestVersionId: versionId,
+    stats: {
+      ...skill.stats,
+      versionCount: skill.stats.versionCount + 1,
+    },
+  });
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp,
+    eventType: 'version.published',
+    actor: {
+      type: request.user?.type ?? 'user',
+      id: userId,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'version',
+      id: versionId,
+      name: fullName,
+      version: body.version,
+    },
+    action: 'create',
+    result: 'success',
+    details: {
+      contentHash,
+      packageSize: contentString.length,
+    },
+  };
+  await storage.createAuditLog(auditLog);
+
+  logger.info('Version published', {
+    skillId: skill.id,
+    fullName,
+    version: body.version,
+    versionId,
+  });
+
+  sendSuccess(request, reply, {
+    id: version.id,
+    version: version.version,
+    tag: body.tag ?? 'latest',
+    publishedAt: version.publishedAt,
+    packageHash: version.packageHash,
+  }, 201);
+}
+
+/**
+ * Deprecate a version
+ */
+export async function deprecateVersion(
+  request: FastifyRequest<{ Params: SkillVersionParam; Body: { message?: string } }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name, version: versionStr } = request.params;
+  const { message } = 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
+  if (skill.ownerId && skill.ownerId !== userId && request.user?.type !== 'system') {
+    throw new AppError(
+      ErrorCodes.FORBIDDEN,
+      'You do not have permission to deprecate versions for this skill',
+      403
+    );
+  }
+
+  const version = await storage.getVersion(skill.id, versionStr);
+  if (!version) {
+    throw new AppError(
+      ErrorCodes.VERSION_NOT_FOUND,
+      `Version '${versionStr}' not found for skill '${fullName}'`,
+      404
+    );
+  }
+
+  const deprecatedVersion = await storage.deprecateVersion(
+    version.id,
+    message ?? 'This version has been deprecated'
+  );
+
+  // Create audit log
+  const auditLog: AuditLog = {
+    id: generateUUID(),
+    timestamp: now(),
+    eventType: 'version.deprecated',
+    actor: {
+      type: request.user?.type ?? 'user',
+      id: userId,
+      username: request.user?.username,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+    resource: {
+      type: 'version',
+      id: version.id,
+      name: fullName,
+      version: versionStr,
+    },
+    action: 'deprecate',
+    result: 'success',
+    details: { message },
+  };
+  await storage.createAuditLog(auditLog);
+
+  logger.info('Version deprecated', {
+    skillId: skill.id,
+    fullName,
+    version: versionStr,
+  });
+
+  sendSuccess(request, reply, {
+    id: deprecatedVersion?.id,
+    version: deprecatedVersion?.version,
+    status: deprecatedVersion?.status,
+    deprecatedAt: deprecatedVersion?.deprecatedAt,
+    deprecatedMessage: deprecatedVersion?.deprecatedMessage,
+  });
+}
+
+/**
+ * Delete a version (yank)
+ */
+export async function deleteVersion(
+  request: FastifyRequest<{ Params: SkillVersionParam }>,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const { name, version: versionStr } = request.params;
+  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 versions for this skill',
+      403
+    );
+  }
+
+  const version = await storage.getVersion(skill.id, versionStr);
+  if (!version) {
+    throw new AppError(
+      ErrorCodes.VERSION_NOT_FOUND,
+      `Version '${versionStr}' not found for skill '${fullName}'`,
+      404
+    );
+  }
+
+  // Instead of hard delete, mark as yanked
+  await storage.updateVersion(version.id, {
+    status: 'yanked',
+    tag: undefined, // Remove any tag
+  });
+
+  // If this was the latest version, update skill's latestVersion
+  if (skill.latestVersion === versionStr) {
+    // Find next latest version
+    const versions = await storage.getVersions(skill.id, { limit: 10 });
+    const nextLatest = versions.items.find(v => v.id !== version.id && v.status === 'published');
+    
+    if (nextLatest) {
+      await storage.updateSkill(skill.id, {
+        latestVersion: nextLatest.version,
+        latestVersionId: nextLatest.id,
+      });
+      await storage.updateVersion(nextLatest.id, { tag: 'latest' });
+    }
+  }
+
+  // Update version count
+  await storage.updateSkill(skill.id, {
+    stats: {
+      ...skill.stats,
+      versionCount: Math.max(0, skill.stats.versionCount - 1),
+    },
+  });
+
+  logger.info('Version yanked', {
+    skillId: skill.id,
+    fullName,
+    version: versionStr,
+  });
+
+  sendSuccess(request, reply, { yanked: true });
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Open Skills Hub - API Entry Point
+ */
+
+import { createServer, startServer, stopServer } from './server.js';
+import { initConfig, logger } from '@open-skills-hub/core';
+
+// Export server utilities
+export { createServer, startServer, stopServer } from './server.js';
+export * from './middleware/index.js';
+export * from './controllers/index.js';
+export * from './routes/index.js';
+
+/**
+ * Main entry point
+ */
+async function main(): Promise<void> {
+  // Initialize configuration
+  const config = initConfig();
+  await config.load();
+
+  logger.info('Starting Open Skills Hub API', {
+    mode: config.get().mode,
+    port: config.get().server.port,
+  });
+
+  // Create and start server
+  const server = await createServer();
+  
+  // Handle shutdown signals
+  const shutdown = async (signal: string) => {
+    logger.info(`Received ${signal}, shutting down...`);
+    try {
+      await stopServer(server);
+      process.exit(0);
+    } catch (error) {
+      logger.error('Error during shutdown', { error });
+      process.exit(1);
+    }
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+
+  // Handle uncaught errors
+  process.on('uncaughtException', (error) => {
+    logger.error('Uncaught exception', { error });
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    logger.error('Unhandled rejection', { reason });
+    process.exit(1);
+  });
+
+  // Start the server
+  try {
+    const address = await startServer(server);
+    logger.info(`Open Skills Hub API started at ${address}`);
+    
+    // Log available endpoints
+    logger.info('Available endpoints:', {
+      health: `${address}/health`,
+      ready: `${address}/ready`,
+      skills: `${address}/v1/skills`,
+      search: `${address}/v1/search`,
+      scan: `${address}/v1/scan`,
+      feedback: `${address}/v1/feedback`,
+      cache: `${address}/v1/cache`,
+      audit: `${address}/v1/audit`,
+    });
+  } catch (error) {
+    logger.error('Failed to start server', { error });
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+const isMainModule = import.meta.url === `file://${process.argv[1]}` || 
+                     decodeURIComponent(import.meta.url) === `file://${process.argv[1]}`;
+if (isMainModule) {
+  main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}