@larkup/marketplace 0.1.1

package/src/tool-manifest.schema.ts

@@ -0,0 +1,191 @@
+import type { ToolDescriptor, ToolCategory, ToolPricing } from './types';
+
+/**
+ * Tool manifest schema validation.
+ *
+ * Provides a validation utility for `tool.manifest.json` files.
+ * Contributors creating new tools can validate their manifest
+ * against this schema to ensure correctness before publishing.
+ *
+ * Schema version: 1.0
+ */
+
+/* ------------------------------------------------------------------ */
+/* Constants                                                           */
+/* ------------------------------------------------------------------ */
+
+export const MANIFEST_SCHEMA_VERSION = '1.0';
+
+export const VALID_CATEGORIES: ToolCategory[] = [
+  'media',
+  'search',
+  'analytics',
+  'integration',
+  'embedding',
+  'ai',
+  'automation',
+  'utility',
+];
+
+export const VALID_PRICING_TIERS: ToolPricing[] = ['free', 'pro', 'enterprise'];
+
+export const VALID_CONFIG_FIELD_TYPES = ['text', 'password', 'select', 'toggle'] as const;
+
+/* ------------------------------------------------------------------ */
+/* Validation result                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface ManifestValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/* ------------------------------------------------------------------ */
+/* Validator                                                           */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Validate a tool manifest object against the ToolDescriptor schema.
+ *
+ * @example
+ * ```typescript
+ * import { validateToolManifest } from "@larkup/marketplace/manifest"
+ * import manifest from "./tool.manifest.json"
+ *
+ * const result = validateToolManifest(manifest)
+ * if (!result.valid) {
+ *   console.error("Manifest errors:", result.errors)
+ * }
+ * ```
+ */
+export function validateToolManifest(manifest: Record<string, unknown>): ManifestValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Required string fields
+  const requiredStrings = [
+    'id',
+    'name',
+    'description',
+    'version',
+    'packageName',
+    'installSize',
+    'author',
+    'icon',
+  ] as const;
+  for (const field of requiredStrings) {
+    if (!manifest[field] || typeof manifest[field] !== 'string') {
+      errors.push(`Missing or invalid required field: "${field}" (expected string)`);
+    }
+  }
+
+  // id format: lowercase, hyphenated
+  if (typeof manifest.id === 'string' && !/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(manifest.id)) {
+    errors.push(`"id" must be lowercase alphanumeric with hyphens (e.g., "video-audio")`);
+  }
+
+  // category
+  if (!manifest.category || !VALID_CATEGORIES.includes(manifest.category as ToolCategory)) {
+    errors.push(`"category" must be one of: ${VALID_CATEGORIES.join(', ')}`);
+  }
+
+  // pricing
+  if (!manifest.pricing || !VALID_PRICING_TIERS.includes(manifest.pricing as ToolPricing)) {
+    errors.push(`"pricing" must be one of: ${VALID_PRICING_TIERS.join(', ')}`);
+  }
+
+  // version semver-ish check
+  if (typeof manifest.version === 'string' && !/^\d+\.\d+\.\d+/.test(manifest.version)) {
+    errors.push(`"version" should follow semver format (e.g., "0.1.0")`);
+  }
+
+  // capabilities
+  if (!Array.isArray(manifest.capabilities) || manifest.capabilities.length === 0) {
+    errors.push(`"capabilities" must be a non-empty array of strings`);
+  }
+
+  // downloads must be a number
+  if (manifest.downloads !== undefined && typeof manifest.downloads !== 'number') {
+    errors.push(`"downloads" must be a number`);
+  }
+
+  // Optional field checks
+  if (manifest.emoji !== undefined && typeof manifest.emoji !== 'string') {
+    warnings.push(`"emoji" should be a string (e.g., "🎬")`);
+  }
+
+  if (manifest.tags !== undefined) {
+    if (!Array.isArray(manifest.tags)) {
+      warnings.push(`"tags" should be an array of strings`);
+    }
+  }
+
+  if (manifest.systemDeps !== undefined) {
+    if (!Array.isArray(manifest.systemDeps)) {
+      warnings.push(`"systemDeps" should be an array of strings`);
+    }
+  }
+
+  if (manifest.configSchema !== undefined) {
+    if (!Array.isArray(manifest.configSchema)) {
+      errors.push(`"configSchema" must be an array`);
+    } else {
+      for (let i = 0; i < manifest.configSchema.length; i++) {
+        const field = manifest.configSchema[i] as Record<string, unknown>;
+        if (!field.key || !field.label || !field.type) {
+          errors.push(`configSchema[${i}]: must have "key", "label", and "type"`);
+        }
+        if (field.type && !VALID_CONFIG_FIELD_TYPES.includes(field.type as any)) {
+          errors.push(
+            `configSchema[${i}].type must be one of: ${VALID_CONFIG_FIELD_TYPES.join(', ')}`,
+          );
+        }
+      }
+    }
+  }
+
+  // Warnings for missing recommended fields
+  if (!manifest.emoji && !manifest.iconUrl) {
+    warnings.push(`Consider adding "emoji" or "iconUrl" for a better marketplace experience`);
+  }
+  if (!manifest.tags || (Array.isArray(manifest.tags) && manifest.tags.length === 0)) {
+    warnings.push(`Consider adding "tags" for better discoverability`);
+  }
+  if (!manifest.license) {
+    warnings.push(`Consider adding "license" (e.g., "MIT", "Apache-2.0")`);
+  }
+  if (!manifest.repositoryUrl) {
+    warnings.push(`Consider adding "repositoryUrl" for collaboration`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Generate a minimal tool manifest template.
+ * Useful for bootstrapping new tool packages.
+ */
+export function generateManifestTemplate(toolId: string): Partial<ToolDescriptor> {
+  return {
+    id: toolId,
+    name: '',
+    description: '',
+    category: 'utility',
+    version: '0.1.0',
+    pricing: 'free',
+    emoji: '',
+    icon: '',
+    packageName: `@larkup/tool-${toolId}`,
+    installSize: '~1 MB',
+    author: '',
+    capabilities: [],
+    tags: [],
+    downloads: 0,
+    license: 'Apache-2.0',
+  };
+}

package/src/tool-registry.ts

@@ -0,0 +1,306 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { ToolDescriptor } from './types';
+import { DEFAULT_HUB_URL } from './types';
+
+/**
+ * Tool registry — resolves tool descriptors from multiple sources.
+ *
+ * Resolution order:
+ * 1. Local `tool.manifest.json` files from workspace packages
+ * 2. Hub API (remote catalog) when available
+ * 3. Hardcoded fallback for offline / development
+ *
+ * In the monorepo, tools under `packages/tools/` ship their own
+ * `tool.manifest.json`. This registry reads those at startup.
+ * When the Hub API is live, it supplements with remotely-published tools.
+ */
+
+/* ------------------------------------------------------------------ */
+/* Local manifest discovery                                            */
+/* ------------------------------------------------------------------ */
+
+/** Cached registry — populated on first access. */
+let cachedRegistry: Record<string, ToolDescriptor> | null = null;
+
+/**
+ * Scan workspace tool directories for `tool.manifest.json` files.
+ * This is used in monorepo development and in Docker builds where
+ * tools are bundled at build time.
+ */
+async function discoverLocalManifests(): Promise<Record<string, ToolDescriptor>> {
+  const registry: Record<string, ToolDescriptor> = {};
+
+  // Try multiple possible tool directories
+  const searchPaths = [
+    // Monorepo development: packages/tools/*
+    path.resolve(process.cwd(), 'packages', 'tools'),
+    // Next.js dev server runs in apps/web
+    path.resolve(process.cwd(), '..', '..', 'packages', 'tools'),
+    // Installed tools: .larkup/tools/node_modules/@larkup
+    path.resolve(process.cwd(), '.larkup', 'tools', 'node_modules', '@larkup'),
+    path.resolve(process.cwd(), '..', '..', '.larkup', 'tools', 'node_modules', '@larkup'),
+  ];
+
+  for (const searchPath of searchPaths) {
+    try {
+      const entries = await fs.readdir(searchPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+
+        // Check for tool.manifest.json in the directory
+        const manifestPath = path.join(searchPath, entry.name, 'tool.manifest.json');
+        try {
+          const raw = await fs.readFile(manifestPath, 'utf8');
+          const manifest = JSON.parse(raw) as ToolDescriptor;
+          if (manifest.id) {
+            registry[manifest.id] = manifest;
+          }
+        } catch {
+          // No manifest in this directory — skip
+        }
+      }
+    } catch {
+      // Directory doesn't exist — skip
+    }
+  }
+
+  return registry;
+}
+
+/* ------------------------------------------------------------------ */
+/* Hub API fetching                                                    */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Fetch the full tool catalog from the remote Hub API.
+ * Falls back gracefully if the Hub is unreachable.
+ */
+async function fetchHubCatalog(hubUrl?: string): Promise<Record<string, ToolDescriptor>> {
+  const baseUrl = hubUrl ?? DEFAULT_HUB_URL;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+
+    const res = await fetch(`${baseUrl}/v1/tools`, {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+    });
+    clearTimeout(timeout);
+
+    if (!res.ok) return {};
+
+    const data = (await res.json()) as { tools: ToolDescriptor[] };
+    const registry: Record<string, ToolDescriptor> = {};
+    for (const tool of data.tools ?? []) {
+      if (tool.id) registry[tool.id] = tool;
+    }
+    return registry;
+  } catch {
+    // Hub unreachable — offline mode
+    return {};
+  }
+}
+
+/**
+ * Fetch a single tool descriptor from the Hub API.
+ */
+export async function fetchToolFromHub(
+  toolId: string,
+  hubUrl?: string,
+): Promise<ToolDescriptor | null> {
+  const baseUrl = hubUrl ?? DEFAULT_HUB_URL;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+
+    const res = await fetch(`${baseUrl}/v1/tools/${toolId}`, {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+    });
+    clearTimeout(timeout);
+
+    if (!res.ok) return null;
+    const data = (await res.json()) as { tool: ToolDescriptor };
+    return data.tool ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Hardcoded fallback (offline safety net)                              */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Minimal hardcoded registry for offline / first-run scenarios
+ * where neither manifests nor Hub are available. This ensures the
+ * marketplace always has something to show.
+ */
+const FALLBACK_REGISTRY: Record<string, ToolDescriptor> = {
+  'video-audio': {
+    id: 'video-audio',
+    name: 'Video & Audio',
+    description: 'Index video and audio files with transcription and frame analysis.',
+    category: 'media',
+    version: '0.1.0',
+    pricing: 'free',
+    emoji: '🎬',
+    icon: 'Film',
+    packageName: '@larkup/tool-video-audio',
+    installSize: '~15 MB',
+    systemDeps: ['ffmpeg'],
+    author: 'Larkup',
+    capabilities: [
+      'video-indexing',
+      'audio-indexing',
+      'transcription',
+      'frame-extraction',
+      'youtube-import',
+    ],
+    tags: ['transcription', 'ffmpeg', 'video', 'audio', 'whisper'],
+    downloads: 0,
+    repositoryUrl: 'https://github.com/Larkup-AI/larkup-rag',
+    license: 'Apache-2.0',
+    updatedAt: '2026-07-20',
+    configSchema: [
+      {
+        key: 'frameInterval',
+        label: 'Frame extraction interval (seconds)',
+        type: 'text',
+        defaultValue: '10',
+        help: 'Baseline cadence for duration-aware coverage frames; scene changes and a reserved ending pass are added separately.',
+      },
+      {
+        key: 'audioProvider',
+        label: 'Audio Provider',
+        type: 'select',
+        help: 'Choose the provider used only for audio and video transcription.',
+        options: [
+          { label: 'OpenAI', value: 'openai' },
+          { label: 'Groq', value: 'groq' },
+          { label: 'Deepgram', value: 'deepgram' },
+          { label: 'ElevenLabs', value: 'elevenlabs' },
+          { label: 'Local Whisper', value: 'local' },
+        ],
+      },
+      {
+        key: 'audioLanguage',
+        label: 'Transcription language',
+        type: 'text',
+        defaultValue: 'auto',
+        help: 'Use auto to infer Arabic from the media title and use provider detection otherwise. Enter a language code such as ar, ar-EG, en, or de to override it.',
+      },
+      {
+        key: 'audioApiKey',
+        label: 'Audio API Key',
+        type: 'password',
+        help: 'Required for the selected audio provider and kept separate from the chat model key.',
+      },
+    ],
+  },
+
+  'clip-embeddings': {
+    id: 'clip-embeddings',
+    name: 'CLIP Image Search',
+    description: 'Direct image-to-image similarity search using CLIP/SigLIP embeddings.',
+    category: 'embedding',
+    version: '0.1.0',
+    pricing: 'free',
+    emoji: '🔍',
+    icon: 'ScanEye',
+    packageName: '@larkup/tool-clip-embeddings',
+    installSize: '~200 MB',
+    author: 'Larkup',
+    capabilities: ['clip-embeddings', 'image-similarity'],
+    tags: ['clip', 'siglip', 'image-search', 'visual-similarity'],
+    downloads: 0,
+    repositoryUrl: 'https://github.com/Larkup-AI/larkup-rag',
+    license: 'Apache-2.0',
+    updatedAt: '2026-07-20',
+    comingSoon: true,
+  },
+
+  'doc-editor': {
+    id: 'doc-editor',
+    name: 'Document Editor',
+    description: 'AI-powered form filling and document editing with Canvas-style live preview.',
+    category: 'utility',
+    version: '0.1.0',
+    pricing: 'free',
+    emoji: '📝',
+    icon: 'FileEdit',
+    packageName: '@larkup/tool-doc-editor',
+    installSize: '~5 MB',
+    systemDeps: ['docker'],
+    author: 'Larkup',
+    capabilities: ['document-editing', 'form-filling', 'document-preview'],
+    tags: ['pdf', 'docx', 'pptx', 'form', 'canvas', 'editor', 'fill'],
+    downloads: 0,
+    repositoryUrl: 'https://github.com/Larkup-AI/larkup-rag',
+    license: 'Apache-2.0',
+    updatedAt: '2026-07-20',
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Public API                                                          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Build the full tool registry by merging sources.
+ * Priority: local manifests > Hub API > hardcoded fallback.
+ * Cached after first call for the process lifetime.
+ */
+export async function buildRegistry(opts?: {
+  hubUrl?: string;
+  skipHub?: boolean;
+}): Promise<Record<string, ToolDescriptor>> {
+  if (cachedRegistry) return cachedRegistry;
+
+  // Start with hardcoded fallback
+  const registry = { ...FALLBACK_REGISTRY };
+
+  // Layer local manifests on top (they're the most up-to-date for development)
+  const localManifests = await discoverLocalManifests();
+  Object.assign(registry, localManifests);
+
+  // Layer Hub API catalog on top (newest published versions)
+  if (!opts?.skipHub) {
+    const hubCatalog = await fetchHubCatalog(opts?.hubUrl);
+    Object.assign(registry, hubCatalog);
+  }
+
+  cachedRegistry = registry;
+  return registry;
+}
+
+/** Force-refresh the registry cache (e.g., after installing a new tool). */
+export function invalidateRegistryCache(): void {
+  cachedRegistry = null;
+}
+
+/** All tools as a flat list, sorted by name. */
+export async function getAllTools(): Promise<ToolDescriptor[]> {
+  const registry = await buildRegistry();
+  return Object.values(registry).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Lookup a single tool by id. */
+export async function getToolById(id: string): Promise<ToolDescriptor | undefined> {
+  const registry = await buildRegistry();
+  return registry[id];
+}
+
+/** Tools that provide a specific capability. */
+export async function getToolsWithCapability(capability: string): Promise<ToolDescriptor[]> {
+  const all = await getAllTools();
+  return all.filter((t) => t.capabilities.includes(capability));
+}
+
+/** Get all unique categories from the registry. */
+export async function getAllCategories(): Promise<string[]> {
+  const all = await getAllTools();
+  const cats = new Set(all.map((t) => t.category));
+  return Array.from(cats).sort();
+}