@open-skills-hub/api 1.0.0

package/src/middleware/validation.ts

@@ -0,0 +1,270 @@
+/**
+ * Open Skills Hub - Request Validation Middleware
+ */
+
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { z, ZodSchema, ZodError } from 'zod';
+import { AppError, ErrorCodes } from '@open-skills-hub/core';
+
+/**
+ * Validate request body with Zod schema
+ */
+export function validateBody<T>(schema: ZodSchema<T>) {
+  return async function(
+    request: FastifyRequest,
+    _reply: FastifyReply
+  ): Promise<void> {
+    try {
+      request.body = schema.parse(request.body);
+    } catch (error) {
+      if (error instanceof ZodError) {
+        throw error; // Will be handled by error middleware
+      }
+      throw new AppError(
+        ErrorCodes.VALIDATION_FAILED,
+        'Invalid request body',
+        400
+      );
+    }
+  };
+}
+
+/**
+ * Validate request query with Zod schema
+ */
+export function validateQuery<T>(schema: ZodSchema<T>) {
+  return async function(
+    request: FastifyRequest,
+    _reply: FastifyReply
+  ): Promise<void> {
+    try {
+      request.query = schema.parse(request.query);
+    } catch (error) {
+      if (error instanceof ZodError) {
+        throw error;
+      }
+      throw new AppError(
+        ErrorCodes.VALIDATION_FAILED,
+        'Invalid query parameters',
+        400
+      );
+    }
+  };
+}
+
+/**
+ * Validate request params with Zod schema
+ */
+export function validateParams<T>(schema: ZodSchema<T>) {
+  return async function(
+    request: FastifyRequest,
+    _reply: FastifyReply
+  ): Promise<void> {
+    try {
+      request.params = schema.parse(request.params);
+    } catch (error) {
+      if (error instanceof ZodError) {
+        throw error;
+      }
+      throw new AppError(
+        ErrorCodes.VALIDATION_FAILED,
+        'Invalid path parameters',
+        400
+      );
+    }
+  };
+}
+
+// ============================================================================
+// Common Validation Schemas
+// ============================================================================
+
+/**
+ * Pagination query schema
+ */
+export const PaginationQuerySchema = z.object({
+  cursor: z.string().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+export type PaginationQuery = z.infer<typeof PaginationQuerySchema>;
+
+/**
+ * Skill name param schema
+ */
+export const SkillNameParamSchema = z.object({
+  name: z.string().min(1).max(214),
+});
+export type SkillNameParam = z.infer<typeof SkillNameParamSchema>;
+
+/**
+ * Skill name with version param schema
+ */
+export const SkillVersionParamSchema = z.object({
+  name: z.string().min(1).max(214),
+  version: z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-.+)?$/),
+});
+export type SkillVersionParam = z.infer<typeof SkillVersionParamSchema>;
+
+/**
+ * ID param schema
+ */
+export const IdParamSchema = z.object({
+  id: z.string().min(1),
+});
+export type IdParam = z.infer<typeof IdParamSchema>;
+
+/**
+ * Search query schema
+ */
+export const SearchQuerySchema = z.object({
+  q: z.string().optional(),
+  category: z.string().optional(),
+  author: z.string().optional(),
+  sort: z.enum(['relevance', 'uses', 'updated', 'created', 'name']).default('relevance'),
+  order: z.enum(['asc', 'desc']).default('desc'),
+  cursor: z.string().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+export type SearchQuery = z.infer<typeof SearchQuerySchema>;
+
+/**
+ * Create skill body schema
+ */
+export const CreateSkillBodySchema = z.object({
+  name: z.string().regex(/^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$/, 'Invalid skill name format'),
+  scope: z.string().optional(),
+  displayName: z.string().optional(),
+  description: z.string().min(1).max(10000),
+  category: z.string().optional(),
+  keywords: z.array(z.string()).max(20).default([]),
+  license: z.string().optional(),
+  repository: z.string().url().optional(),
+  homepage: z.string().url().optional(),
+  visibility: z.enum(['public', 'private', 'unlisted']).default('public'),
+  content: z.object({
+    frontmatter: z.object({
+      name: z.string(),
+      description: z.string().optional(),
+      author: z.string().optional(), // Author field for skill attribution
+      allowedTools: z.array(z.string()).optional(),
+      argumentHint: z.string().optional(),
+      disableModelInvocation: z.boolean().optional(),
+      userInvocable: z.boolean().optional(),
+      model: z.string().optional(),
+      context: z.literal('fork').optional(),
+      agent: z.string().optional(),
+      license: z.string().optional(),
+      compatibility: z.string().optional(),
+      derivedFrom: z.object({
+        name: z.string(),
+        version: z.string(),
+        author: z.string(),
+      }).optional(),
+      metadata: z.record(z.string()).optional(),
+    }),
+    markdown: z.string().min(1),
+    files: z.array(z.object({
+      path: z.string(),
+      content: z.string(),
+      size: z.number(),
+    })).optional(),
+  }),
+  version: z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-.+)?$/).default('1.0.0'),
+  changelog: z.string().optional(),
+});
+export type CreateSkillBody = z.infer<typeof CreateSkillBodySchema>;
+
+/**
+ * Update skill body schema
+ */
+export const UpdateSkillBodySchema = z.object({
+  displayName: z.string().optional(),
+  description: z.string().min(1).max(10000).optional(),
+  category: z.string().optional(),
+  keywords: z.array(z.string()).max(20).optional(),
+  repository: z.string().url().optional().nullable(),
+  homepage: z.string().url().optional().nullable(),
+  visibility: z.enum(['public', 'private', 'unlisted']).optional(),
+});
+export type UpdateSkillBody = z.infer<typeof UpdateSkillBodySchema>;
+
+/**
+ * Publish version body schema
+ */
+export const PublishVersionBodySchema = z.object({
+  version: z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-.+)?$/),
+  content: z.object({
+    frontmatter: z.object({
+      name: z.string(),
+      description: z.string().optional(),
+      allowedTools: z.array(z.string()).optional(),
+      argumentHint: z.string().optional(),
+      disableModelInvocation: z.boolean().optional(),
+      userInvocable: z.boolean().optional(),
+      model: z.string().optional(),
+      context: z.literal('fork').optional(),
+      agent: z.string().optional(),
+      license: z.string().optional(),
+      compatibility: z.string().optional(),
+      derivedFrom: z.object({
+        name: z.string(),
+        version: z.string(),
+        author: z.string(),
+      }).optional(),
+      metadata: z.record(z.string()).optional(),
+    }),
+    markdown: z.string().min(1),
+    files: z.array(z.object({
+      path: z.string(),
+      content: z.string(),
+      size: z.number(),
+    })).optional(),
+  }),
+  changelog: z.string().optional(),
+  tag: z.string().optional(),
+});
+export type PublishVersionBody = z.infer<typeof PublishVersionBodySchema>;
+
+/**
+ * Submit feedback body schema
+ */
+export const SubmitFeedbackBodySchema = z.object({
+  skillName: z.string(),
+  skillVersion: z.string(),
+  feedbackType: z.enum(['success', 'failure', 'suggestion', 'bug']),
+  rating: z.number().min(1).max(5),
+  comment: z.string().max(5000).optional(),
+  context: z.object({
+    executionTime: z.number().optional(),
+    taskType: z.string().optional(),
+    errorMessage: z.string().optional(),
+    agentType: z.string().optional(),
+    agentVersion: z.string().optional(),
+    outcome: z.enum(['success', 'partial', 'failure']).optional(),
+  }).optional(),
+});
+export type SubmitFeedbackBody = z.infer<typeof SubmitFeedbackBodySchema>;
+
+/**
+ * Scan content body schema
+ */
+export const ScanContentBodySchema = z.object({
+  content: z.string().min(1).max(1024 * 1024), // 1MB max
+  contentType: z.enum(['markdown', 'yaml', 'json']).default('markdown'),
+});
+export type ScanContentBody = z.infer<typeof ScanContentBodySchema>;
+
+/**
+ * Audit query schema
+ */
+export const AuditQuerySchema = z.object({
+  eventType: z.string().optional(),
+  actor: z.string().optional(),
+  resourceType: z.string().optional(),
+  resourceName: z.string().optional(),
+  from: z.string().optional(),
+  to: z.string().optional(),
+  cursor: z.string().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+export type AuditQuery = z.infer<typeof AuditQuerySchema>;

package/src/routes/audit.ts

@@ -0,0 +1,74 @@
+/**
+ * Open Skills Hub - Audit Routes
+ */
+
+import type { FastifyInstance, FastifyPluginOptions } from 'fastify';
+import { z } from 'zod';
+import {
+  getAuditLogs,
+  getSkillAuditLogs,
+  getAuditLogById,
+  getAuditStats,
+} from '../controllers/audit.js';
+import { requireAuth, requirePermission } from '../middleware/auth.js';
+import {
+  validateParams,
+  validateQuery,
+  SkillNameParamSchema,
+  IdParamSchema,
+  AuditQuerySchema,
+} from '../middleware/validation.js';
+
+// Stats query schema
+const StatsQuerySchema = z.object({
+  days: z.coerce.number().int().min(1).max(365).default(30),
+});
+
+export async function auditRoutes(
+  server: FastifyInstance,
+  _opts: FastifyPluginOptions
+): Promise<void> {
+  // Get audit logs (admin only)
+  // GET /v1/audit
+  server.get('/', {
+    preHandler: [
+      requireAuth,
+      requirePermission('admin'),
+      validateQuery(AuditQuerySchema),
+    ],
+    handler: getAuditLogs,
+  });
+
+  // Get audit statistics
+  // GET /v1/audit/stats
+  server.get('/stats', {
+    preHandler: [
+      requireAuth,
+      requirePermission('admin'),
+      validateQuery(StatsQuerySchema),
+    ],
+    handler: getAuditStats,
+  });
+
+  // Get audit logs for a specific skill
+  // GET /v1/audit/skill/:name
+  server.get('/skill/:name', {
+    preHandler: [
+      requireAuth,
+      validateParams(SkillNameParamSchema),
+      validateQuery(AuditQuerySchema),
+    ],
+    handler: getSkillAuditLogs,
+  });
+
+  // Get audit log by ID
+  // GET /v1/audit/:id
+  server.get('/:id', {
+    preHandler: [
+      requireAuth,
+      requirePermission('admin'),
+      validateParams(IdParamSchema),
+    ],
+    handler: getAuditLogById,
+  });
+}

package/src/routes/cache.ts

@@ -0,0 +1,93 @@
+/**
+ * Open Skills Hub - Cache Routes
+ */
+
+import type { FastifyInstance, FastifyPluginOptions } from 'fastify';
+import {
+  getCachedSkills,
+  getSkillCacheInfo,
+  getVersionCacheInfo,
+  invalidateSkillCache,
+  invalidateVersionCache,
+  cleanExpiredCache,
+  getCacheStats,
+} from '../controllers/cache.js';
+import { optionalAuth, requireAuth, requirePermission } from '../middleware/auth.js';
+import {
+  validateParams,
+  SkillNameParamSchema,
+  SkillVersionParamSchema,
+} from '../middleware/validation.js';
+
+export async function cacheRoutes(
+  server: FastifyInstance,
+  _opts: FastifyPluginOptions
+): Promise<void> {
+  // Get all cached skills
+  // GET /v1/cache
+  server.get('/', {
+    preHandler: [
+      requireAuth,
+    ],
+    handler: getCachedSkills,
+  });
+
+  // Get cache statistics
+  // GET /v1/cache/stats
+  server.get('/stats', {
+    preHandler: [
+      requireAuth,
+    ],
+    handler: getCacheStats,
+  });
+
+  // Clean expired cache entries
+  // POST /v1/cache/clean
+  server.post('/clean', {
+    preHandler: [
+      requireAuth,
+      requirePermission('admin'),
+    ],
+    handler: cleanExpiredCache,
+  });
+
+  // Get cache info for a skill
+  // GET /v1/cache/:name
+  server.get('/:name', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillNameParamSchema),
+    ],
+    handler: getSkillCacheInfo,
+  });
+
+  // Invalidate cache for a skill
+  // DELETE /v1/cache/:name
+  server.delete('/:name', {
+    preHandler: [
+      requireAuth,
+      validateParams(SkillNameParamSchema),
+    ],
+    handler: invalidateSkillCache,
+  });
+
+  // Get cache info for a specific version
+  // GET /v1/cache/:name/:version
+  server.get('/:name/:version', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillVersionParamSchema),
+    ],
+    handler: getVersionCacheInfo,
+  });
+
+  // Invalidate cache for a specific version
+  // DELETE /v1/cache/:name/:version
+  server.delete('/:name/:version', {
+    preHandler: [
+      requireAuth,
+      validateParams(SkillVersionParamSchema),
+    ],
+    handler: invalidateVersionCache,
+  });
+}

package/src/routes/feedback.ts

@@ -0,0 +1,93 @@
+/**
+ * Open Skills Hub - Feedback Routes
+ */
+
+import type { FastifyInstance, FastifyPluginOptions } from 'fastify';
+import { z } from 'zod';
+import {
+  submitFeedback,
+  getSkillFeedbacks,
+  getFeedbackById,
+  reviewFeedback,
+  getFeedbackStats,
+} from '../controllers/feedback.js';
+import { optionalAuth, requireAuth, requirePermission } from '../middleware/auth.js';
+import {
+  validateBody,
+  validateParams,
+  validateQuery,
+  SkillNameParamSchema,
+  IdParamSchema,
+  SubmitFeedbackBodySchema,
+  PaginationQuerySchema,
+} from '../middleware/validation.js';
+
+// Extended query schema for feedbacks
+const FeedbackQuerySchema = PaginationQuerySchema.extend({
+  feedbackType: z.enum(['success', 'failure', 'suggestion', 'bug']).optional(),
+  status: z.enum(['pending', 'reviewed', 'accepted', 'rejected']).optional(),
+});
+
+// Review feedback body schema
+const ReviewFeedbackBodySchema = z.object({
+  status: z.enum(['reviewed', 'accepted', 'rejected']),
+  notes: z.string().optional(),
+});
+
+export async function feedbackRoutes(
+  server: FastifyInstance,
+  _opts: FastifyPluginOptions
+): Promise<void> {
+  // Submit feedback
+  // POST /v1/feedback
+  server.post('/', {
+    preHandler: [
+      optionalAuth,
+      validateBody(SubmitFeedbackBodySchema),
+    ],
+    handler: submitFeedback,
+  });
+
+  // Get feedbacks for a skill
+  // GET /v1/feedback/skill/:name
+  server.get('/skill/:name', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillNameParamSchema),
+      validateQuery(FeedbackQuerySchema),
+    ],
+    handler: getSkillFeedbacks,
+  });
+
+  // Get feedback statistics for a skill
+  // GET /v1/feedback/skill/:name/stats
+  server.get('/skill/:name/stats', {
+    preHandler: [
+      optionalAuth,
+      validateParams(SkillNameParamSchema),
+    ],
+    handler: getFeedbackStats,
+  });
+
+  // Get feedback by ID
+  // GET /v1/feedback/:id
+  server.get('/:id', {
+    preHandler: [
+      optionalAuth,
+      validateParams(IdParamSchema),
+    ],
+    handler: getFeedbackById,
+  });
+
+  // Review feedback (admin only)
+  // POST /v1/feedback/:id/review
+  server.post('/:id/review', {
+    preHandler: [
+      requireAuth,
+      requirePermission('admin'),
+      validateParams(IdParamSchema),
+      validateBody(ReviewFeedbackBodySchema),
+    ],
+    handler: reviewFeedback,
+  });
+}

package/src/routes/health.ts

@@ -0,0 +1,151 @@
+/**
+ * Open Skills Hub - Health Check Routes
+ */
+
+import type { FastifyInstance, FastifyPluginOptions, FastifyRequest, FastifyReply } from 'fastify';
+import { getStorage, getConfig } from '@open-skills-hub/core';
+import { sendSuccess } from '../middleware/error.js';
+
+/**
+ * Basic health check
+ */
+async function healthCheck(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  sendSuccess(request, reply, {
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+  });
+}
+
+/**
+ * Readiness check (includes storage health)
+ */
+async function readinessCheck(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const config = getConfig().get();
+
+  const storageHealthy = await storage.healthCheck();
+
+  if (!storageHealthy) {
+    reply.status(503).send({
+      success: false,
+      error: {
+        code: 'SERVICE_UNAVAILABLE',
+        message: 'Storage is not available',
+      },
+      meta: {
+        requestId: request.id as string,
+        timestamp: new Date().toISOString(),
+      },
+    });
+    return;
+  }
+
+  sendSuccess(request, reply, {
+    status: 'ready',
+    timestamp: new Date().toISOString(),
+    checks: {
+      storage: storageHealthy ? 'healthy' : 'unhealthy',
+    },
+    config: {
+      mode: config.mode,
+      version: '1.0.0',
+    },
+  });
+}
+
+/**
+ * Detailed system info (admin only)
+ */
+async function systemInfo(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  const config = getConfig();
+
+  const storageHealthy = await storage.healthCheck();
+
+  sendSuccess(request, reply, {
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    system: {
+      nodeVersion: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      uptime: process.uptime(),
+      memoryUsage: process.memoryUsage(),
+    },
+    config: {
+      mode: config.get().mode,
+      storagePath: config.getStoragePath(),
+      serverPort: config.get().server.port,
+      authRequired: config.get().auth.requireAuth,
+      scannerEnabled: config.get().scanner.enabled,
+      rateLimitEnabled: config.get().rateLimit.enabled,
+      cacheTTL: config.get().cache.ttl,
+    },
+    checks: {
+      storage: storageHealthy ? 'healthy' : 'unhealthy',
+    },
+  });
+}
+
+/**
+ * Reload database from disk
+ * Useful when CLI or external processes have updated the database
+ */
+async function reloadDatabase(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  const storage = await getStorage();
+  
+  try {
+    await storage.reload();
+    sendSuccess(request, reply, {
+      status: 'reloaded',
+      timestamp: new Date().toISOString(),
+      message: 'Database reloaded successfully from disk',
+    });
+  } catch (error) {
+    reply.status(500).send({
+      success: false,
+      error: {
+        code: 'RELOAD_FAILED',
+        message: 'Failed to reload database',
+        details: error instanceof Error ? error.message : String(error),
+      },
+      meta: {
+        requestId: request.id as string,
+        timestamp: new Date().toISOString(),
+      },
+    });
+  }
+}
+
+export async function healthRoutes(
+  server: FastifyInstance,
+  _opts: FastifyPluginOptions
+): Promise<void> {
+  // Basic health check
+  // GET /health
+  server.get('/health', healthCheck);
+
+  // Readiness check (for k8s)
+  // GET /ready
+  server.get('/ready', readinessCheck);
+
+  // System info (admin)
+  // GET /system
+  server.get('/system', systemInfo);
+
+  // Reload database from disk
+  // POST /reload
+  server.post('/reload', reloadDatabase);
+}

package/src/routes/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Open Skills Hub - Routes Exports
+ */
+
+export * from './skills.js';
+export * from './versions.js';
+export * from './search.js';
+export * from './scan.js';
+export * from './feedback.js';
+export * from './audit.js';
+export * from './cache.js';
+export * from './health.js';