@hasna/skills 0.0.2

package/skills/skill-apidocs/scripts/publish.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env bun
+/**
+ * Auto-versioning publish script
+ * - Fetches current npm version
+ * - Auto-bumps patch version if local version <= npm version
+ * - Creates git tag
+ * - Publishes to npm
+ */
+
+import { $ } from 'bun';
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+interface PackageJson {
+  name: string;
+  version: string;
+  [key: string]: unknown;
+}
+
+type BumpType = 'patch' | 'minor' | 'major';
+
+function parseVersion(version: string): { major: number; minor: number; patch: number } {
+  const [major, minor, patch] = version.split('.').map(Number);
+  return { major, minor, patch };
+}
+
+function bumpVersion(version: string, type: BumpType = 'patch'): string {
+  const { major, minor, patch } = parseVersion(version);
+
+  switch (type) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+    default:
+      return `${major}.${minor}.${patch + 1}`;
+  }
+}
+
+function compareVersions(a: string, b: string): number {
+  const vA = parseVersion(a);
+  const vB = parseVersion(b);
+
+  if (vA.major !== vB.major) return vA.major - vB.major;
+  if (vA.minor !== vB.minor) return vA.minor - vB.minor;
+  return vA.patch - vB.patch;
+}
+
+async function getNpmVersion(packageName: string): Promise<string | null> {
+  try {
+    const result = await $`npm view ${packageName} version 2>/dev/null`.text();
+    return result.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function hasUncommittedChanges(): Promise<boolean> {
+  try {
+    const result = await $`git status --porcelain`.text();
+    return result.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function isGitRepo(): Promise<boolean> {
+  try {
+    await $`git rev-parse --git-dir 2>/dev/null`.text();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function createGitTag(version: string, packageName: string): Promise<boolean> {
+  const tagName = `${packageName}@${version}`;
+
+  try {
+    // Check if tag already exists
+    const existingTags = await $`git tag -l ${tagName}`.text();
+    if (existingTags.trim()) {
+      console.log(`⚠️  Tag ${tagName} already exists, skipping tag creation`);
+      return true;
+    }
+
+    await $`git tag -a ${tagName} -m "Release ${tagName}"`;
+    console.log(`✅ Created git tag: ${tagName}`);
+    return true;
+  } catch (error) {
+    console.error(`❌ Failed to create git tag: ${error}`);
+    return false;
+  }
+}
+
+async function commitVersionBump(version: string, packageName: string): Promise<boolean> {
+  try {
+    await $`git add package.json`;
+    await $`git commit -m "chore(${packageName}): bump version to ${version}"`;
+    console.log(`✅ Committed version bump`);
+    return true;
+  } catch (error) {
+    console.error(`❌ Failed to commit: ${error}`);
+    return false;
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const bumpType = (args.find(a => ['patch', 'minor', 'major'].includes(a)) || 'patch') as BumpType;
+  const skipGit = args.includes('--skip-git');
+  const dryRun = args.includes('--dry-run');
+  const force = args.includes('--force');
+
+  // Read package.json
+  const pkgPath = join(process.cwd(), 'package.json');
+  const pkg: PackageJson = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+  console.log(`\n📦 Publishing ${pkg.name}\n`);
+
+  // Get current npm version
+  const npmVersion = await getNpmVersion(pkg.name);
+  let newVersion = pkg.version;
+
+  if (npmVersion) {
+    console.log(`📌 Current npm version: ${npmVersion}`);
+    console.log(`📌 Local version: ${pkg.version}`);
+
+    // Check if we need to bump
+    if (compareVersions(pkg.version, npmVersion) <= 0) {
+      newVersion = bumpVersion(npmVersion, bumpType);
+      console.log(`🔄 Auto-bumping to: ${newVersion}`);
+    } else {
+      console.log(`✅ Local version is ahead, using: ${pkg.version}`);
+    }
+  } else {
+    console.log(`📌 Package not yet published to npm`);
+    console.log(`📌 Using local version: ${pkg.version}`);
+  }
+
+  // Update package.json if version changed
+  if (newVersion !== pkg.version) {
+    if (dryRun) {
+      console.log(`\n🧪 DRY RUN: Would update version to ${newVersion}`);
+    } else {
+      pkg.version = newVersion;
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      console.log(`✅ Updated package.json to version ${newVersion}`);
+    }
+  }
+
+  // Git operations
+  const isGit = await isGitRepo();
+
+  if (isGit && !skipGit) {
+    const hasChanges = await hasUncommittedChanges();
+
+    if (hasChanges && newVersion !== pkg.version) {
+      if (dryRun) {
+        console.log(`🧪 DRY RUN: Would commit version bump`);
+      } else {
+        await commitVersionBump(newVersion, pkg.name.replace('@hasnaxyz/', ''));
+      }
+    }
+
+    if (dryRun) {
+      console.log(`🧪 DRY RUN: Would create tag ${pkg.name}@${newVersion}`);
+    } else {
+      await createGitTag(newVersion, pkg.name.replace('@hasnaxyz/', ''));
+    }
+  }
+
+  // Build
+  console.log(`\n🔨 Building...`);
+  if (!dryRun) {
+    await $`bun run build`;
+  } else {
+    console.log(`🧪 DRY RUN: Would run build`);
+  }
+
+  // Publish
+  console.log(`\n🚀 Publishing to npm...`);
+  if (dryRun) {
+    console.log(`🧪 DRY RUN: Would publish ${pkg.name}@${newVersion}`);
+  } else {
+    try {
+      await $`npm publish`;
+      console.log(`\n✅ Successfully published ${pkg.name}@${newVersion}`);
+    } catch (error) {
+      console.error(`\n❌ Publish failed: ${error}`);
+      process.exit(1);
+    }
+  }
+
+  // Push tags
+  if (isGit && !skipGit && !dryRun) {
+    console.log(`\n📤 Pushing tags to remote...`);
+    try {
+      await $`git push --tags`;
+      console.log(`✅ Pushed tags to remote`);
+    } catch {
+      console.log(`⚠️  Could not push tags (no remote or not configured)`);
+    }
+  }
+
+  console.log(`\n✨ Done!\n`);
+}
+
+main().catch(console.error);

package/skills/skill-apidocs/src/commands/add.ts

@@ -0,0 +1,279 @@
+import type { AddOptions, Chunk, VectorData, LibraryMetadata, DocFile } from '../types/index.js';
+import { parseWebsiteUrl, createLibraryIdFromUrl, createIndexNameFromUrl } from '../utils/paths.js';
+import * as output from '../utils/output.js';
+import { crawlDocumentation, crawlSimple } from '../lib/crawler.js';
+import { parseMarkdown } from '../lib/parser.js';
+import { generateEmbeddings } from '../lib/embeddings.js';
+import { createIndex, upsertVectors, indexExists, deleteIndex } from '../lib/vectors.js';
+import {
+  initStorage,
+  saveLibraryMetadata,
+  cacheChunks,
+  getLibraryMetadata,
+  saveCrawledPages,
+  saveEndpoints,
+} from '../lib/storage.js';
+import { discoverDocsUrl, isLikelyDocsUrl } from '../lib/discovery.js';
+import { extractEndpoints } from '../lib/endpoint-extractor.js';
+
+/**
+ * Add a library from a documentation website
+ */
+export async function add(websiteUrl: string, options: AddOptions): Promise<void> {
+  // Parse website URL
+  const parsed = parseWebsiteUrl(websiteUrl);
+  if (!parsed) {
+    output.error(`Invalid URL: ${websiteUrl}`);
+    process.exit(1);
+  }
+
+  const libraryId = createLibraryIdFromUrl(websiteUrl, options.name);
+  const libraryName = options.name || parsed.domain.replace(/^(www\.|docs\.|api\.|platform\.)/, '');
+
+  output.info(`Adding library: ${libraryName}`);
+  output.info(`URL: ${websiteUrl}`);
+
+  // Initialize storage
+  await initStorage();
+
+  // Check if already indexed
+  const existing = await getLibraryMetadata(libraryId);
+  if (existing) {
+    output.warn(`Library ${libraryName} is already indexed`);
+    output.info('Use `service-apidocs sync` to update the index');
+    return;
+  }
+
+  // Discover documentation URL if needed
+  let docsUrl = websiteUrl;
+  if (!isLikelyDocsUrl(websiteUrl)) {
+    output.step('Discovering documentation URL...');
+    const discovery = await discoverDocsUrl(websiteUrl, (event) => {
+      switch (event.type) {
+        case 'navigating':
+          output.step(`Checking: ${event.url || event.message}`);
+          break;
+        case 'analyzing':
+          output.step(event.message || 'Analyzing page...');
+          break;
+        case 'found':
+          output.success(`Found docs: ${event.docsUrl}`);
+          break;
+        case 'not_found':
+          output.warn(event.message || 'Could not find specific documentation URL');
+          break;
+        case 'error':
+          output.warn(`Discovery error: ${event.error}`);
+          break;
+      }
+    });
+
+    if (discovery.success && discovery.docsUrl) {
+      docsUrl = discovery.docsUrl;
+    }
+    console.log();
+  } else {
+    output.info('URL appears to be documentation, skipping discovery');
+  }
+
+  // Set max pages
+  const maxPages = options.maxPages || 500;
+  output.info(`Max pages: ${maxPages}`);
+
+  // Crawl documentation
+  output.step('Crawling documentation...');
+  console.log();
+
+  const crawlResult = await crawlSimple(
+    {
+      startUrl: docsUrl,
+      maxPages,
+    },
+    (event) => {
+      switch (event.type) {
+        case 'navigating':
+          output.step(`Navigating: ${event.url}`);
+          break;
+        case 'extracted':
+          output.success(`[${event.pageCount}/${event.totalPages}] ${event.title || event.url}`);
+          break;
+        case 'skipped':
+          // Don't log skipped pages to reduce noise
+          break;
+        case 'error':
+          output.warn(`Error: ${event.error}`);
+          break;
+        case 'complete':
+          console.log();
+          output.success(`Crawl complete: ${event.pageCount} pages`);
+          break;
+      }
+    }
+  );
+
+  if (crawlResult.pages.length === 0) {
+    output.error('No documentation pages found');
+    output.info('The crawler could not find any documentation content at this URL');
+    return;
+  }
+
+  // Save crawled pages
+  await saveCrawledPages(libraryId, crawlResult.pages);
+
+  // Convert crawled pages to DocFiles for parsing
+  const files: DocFile[] = crawlResult.pages.map((page) => ({
+    path: page.path || new URL(page.url).pathname,
+    content: page.content,
+  }));
+
+  // Parse and chunk files
+  output.step('Parsing and chunking documentation...');
+  const allChunks: Chunk[] = [];
+
+  for (const file of files) {
+    try {
+      const chunks = parseMarkdown(file.content, file.path);
+      allChunks.push(...chunks);
+    } catch (error) {
+      output.warn(`Failed to parse ${file.path}: ${(error as Error).message}`);
+    }
+  }
+
+  output.success(`Created ${allChunks.length} chunks`);
+
+  if (allChunks.length === 0) {
+    output.error('No chunks created from documentation');
+    return;
+  }
+
+  // Generate embeddings
+  output.step('Generating embeddings...');
+  const texts = allChunks.map((chunk) => chunk.content);
+  let embeddings: number[][];
+
+  try {
+    embeddings = await generateEmbeddings(texts, (processed, total) => {
+      output.step(`Generating embeddings... ${processed}/${total}`);
+    });
+    output.success(`Generated ${embeddings.length} embeddings`);
+  } catch (error) {
+    output.error(`Failed to generate embeddings: ${(error as Error).message}`);
+    output.info('Make sure OPENAI_API_KEY is set');
+    process.exit(1);
+  }
+
+  // Create vector index
+  const indexName = createIndexNameFromUrl(websiteUrl, options.name);
+  output.step(`Creating vector index: ${indexName}`);
+
+  try {
+    // Delete existing index if it exists
+    if (await indexExists(indexName)) {
+      await deleteIndex(indexName);
+    }
+    await createIndex(indexName);
+    output.success('Vector index created');
+  } catch (error) {
+    output.error(`Failed to create index: ${(error as Error).message}`);
+    process.exit(1);
+  }
+
+  // Prepare and upsert vectors
+  output.step('Uploading vectors...');
+  const vectors: VectorData[] = allChunks.map((chunk, i) => ({
+    key: chunk.id,
+    data: {
+      float32: embeddings[i],
+    },
+    metadata: {
+      libraryId,
+      version: new Date().toISOString().split('T')[0],
+      filePath: chunk.filePath,
+      chunkIndex: i,
+      title: chunk.title,
+      type: chunk.type,
+      content: chunk.content,
+    },
+  }));
+
+  try {
+    await upsertVectors(indexName, vectors);
+    output.success(`Uploaded ${vectors.length} vectors`);
+  } catch (error) {
+    output.error(`Failed to upload vectors: ${(error as Error).message}`);
+    process.exit(1);
+  }
+
+  // Extract API endpoints
+  output.step('Extracting API endpoints...');
+  console.log();
+
+  let endpointCount = 0;
+  try {
+    const extractionResult = await extractEndpoints(crawlResult.pages, (event) => {
+      switch (event.type) {
+        case 'processing':
+          if (event.pageUrl) {
+            output.step(`[${event.pageIndex}/${event.totalPages}] Processing: ${event.pageUrl}`);
+          }
+          break;
+        case 'extracted':
+          output.success(`Processed ${event.pageIndex}/${event.totalPages} pages, found ${event.endpointCount} endpoints`);
+          break;
+        case 'complete':
+          console.log();
+          output.success(`Extraction complete: ${event.endpointCount} endpoints`);
+          break;
+        case 'error':
+          output.warn(`Extraction error: ${event.error}`);
+          break;
+      }
+    });
+
+    if (extractionResult.endpoints.length > 0) {
+      await saveEndpoints(libraryId, extractionResult.endpoints);
+      endpointCount = extractionResult.endpoints.length;
+    }
+  } catch (error) {
+    output.warn(`Endpoint extraction failed: ${(error as Error).message}`);
+    output.info('Continuing without endpoint data...');
+  }
+
+  // Save metadata locally
+  output.step('Saving metadata...');
+  const metadata: LibraryMetadata = {
+    id: libraryId,
+    name: libraryName,
+    websiteUrl,
+    docsUrl: docsUrl !== websiteUrl ? docsUrl : undefined,
+    domain: parsed.domain,
+    indexedAt: new Date().toISOString(),
+    chunkCount: allChunks.length,
+    pageCount: crawlResult.pages.length,
+    endpointCount: endpointCount > 0 ? endpointCount : undefined,
+    indexName,
+    crawledUrls: crawlResult.pages.map((p) => p.url),
+  };
+
+  await saveLibraryMetadata(libraryId, metadata);
+  await cacheChunks(libraryId, allChunks);
+
+  console.log();
+  output.success(`Library "${libraryName}" indexed successfully!`);
+  output.info(`Pages: ${crawlResult.pages.length}`);
+  output.info(`Chunks: ${allChunks.length}`);
+  if (endpointCount > 0) {
+    output.info(`Endpoints: ${endpointCount}`);
+  }
+  output.info(`Index: ${indexName}`);
+  output.info(`Duration: ${(crawlResult.duration / 1000).toFixed(1)}s`);
+
+  if (crawlResult.errors.length > 0) {
+    console.log();
+    output.warn(`${crawlResult.errors.length} errors during crawl:`);
+    crawlResult.errors.slice(0, 5).forEach((err) => output.info(`  - ${err}`));
+    if (crawlResult.errors.length > 5) {
+      output.info(`  ... and ${crawlResult.errors.length - 5} more`);
+    }
+  }
+}

package/skills/skill-apidocs/src/commands/endpoints.ts

@@ -0,0 +1,157 @@
+import chalk from 'chalk';
+import type { EndpointsOptions, APIEndpoint } from '../types/index.js';
+import * as output from '../utils/output.js';
+import { initStorage, findLibrary, loadEndpoints } from '../lib/storage.js';
+import { groupByResource, groupByMethod } from '../lib/endpoint-extractor.js';
+
+/**
+ * Display API endpoints from indexed documentation
+ */
+export async function endpoints(library: string, options: EndpointsOptions): Promise<void> {
+  await initStorage();
+
+  // Find library
+  const meta = await findLibrary(library);
+  if (!meta) {
+    output.error(`Library not found: ${library}`);
+    output.info('Use `service-apidocs list` to see indexed libraries');
+    process.exit(1);
+  }
+
+  // Load endpoints
+  const allEndpoints = await loadEndpoints(meta.id);
+
+  if (allEndpoints.length === 0) {
+    output.warn(`No API endpoints found for library: ${meta.name}`);
+    output.info('Endpoints are extracted during indexing. Try re-indexing with `service-apidocs sync`.');
+    return;
+  }
+
+  // Apply filter if specified
+  let filteredEndpoints = allEndpoints;
+  if (options.filter) {
+    const filterMethod = options.filter.toUpperCase();
+    filteredEndpoints = allEndpoints.filter((e) => e.method === filterMethod);
+
+    if (filteredEndpoints.length === 0) {
+      output.warn(`No ${filterMethod} endpoints found`);
+      return;
+    }
+  }
+
+  // JSON output
+  if (options.json) {
+    output.json({
+      library: meta.name,
+      libraryId: meta.id,
+      docsUrl: meta.docsUrl || meta.websiteUrl,
+      endpointCount: filteredEndpoints.length,
+      endpoints: filteredEndpoints,
+    });
+    return;
+  }
+
+  // Header
+  const docsUrl = meta.docsUrl || meta.websiteUrl;
+  console.log();
+  console.log(chalk.bold(`${meta.name} API Endpoints`) + chalk.dim(` (${filteredEndpoints.length} total)`));
+  console.log(chalk.dim(`Docs: ${docsUrl}`));
+  console.log();
+
+  // Group and display
+  const groupBy = options.groupBy || 'resource';
+
+  if (groupBy === 'method') {
+    displayGroupedByMethod(filteredEndpoints);
+  } else {
+    displayGroupedByResource(filteredEndpoints);
+  }
+}
+
+/**
+ * Display endpoints grouped by resource
+ */
+function displayGroupedByResource(endpoints: APIEndpoint[]): void {
+  const grouped = groupByResource(endpoints);
+
+  for (const [resource, resourceEndpoints] of grouped) {
+    // Resource header
+    console.log(chalk.bold.cyan(capitalizeFirst(resource)));
+
+    // Endpoints in this resource
+    for (const endpoint of resourceEndpoints) {
+      const methodColor = getMethodColor(endpoint.method);
+      const method = chalk[methodColor](endpoint.method.padEnd(7));
+      const path = endpoint.path;
+      const title = chalk.dim(truncate(endpoint.title, 50));
+
+      console.log(`  ${method} ${path}  ${title}`);
+    }
+
+    console.log(); // Space between resources
+  }
+}
+
+/**
+ * Display endpoints grouped by HTTP method
+ */
+function displayGroupedByMethod(endpoints: APIEndpoint[]): void {
+  const grouped = groupByMethod(endpoints);
+
+  for (const [method, methodEndpoints] of grouped) {
+    if (methodEndpoints.length === 0) continue;
+
+    // Method header
+    const methodColor = getMethodColor(method);
+    console.log(chalk.bold[methodColor](`${method}`) + chalk.dim(` (${methodEndpoints.length} endpoints)`));
+
+    // Endpoints with this method
+    for (const endpoint of methodEndpoints) {
+      const path = endpoint.path.padEnd(40);
+      const title = chalk.dim(truncate(endpoint.title, 40));
+
+      console.log(`  ${path} ${title}`);
+    }
+
+    console.log(); // Space between methods
+  }
+}
+
+/**
+ * Get chalk color for HTTP method
+ */
+function getMethodColor(method: string): 'green' | 'blue' | 'yellow' | 'red' | 'magenta' | 'cyan' {
+  switch (method) {
+    case 'GET':
+      return 'green';
+    case 'POST':
+      return 'blue';
+    case 'PUT':
+      return 'yellow';
+    case 'PATCH':
+      return 'yellow';
+    case 'DELETE':
+      return 'red';
+    case 'HEAD':
+      return 'magenta';
+    case 'OPTIONS':
+      return 'cyan';
+    default:
+      return 'cyan';
+  }
+}
+
+/**
+ * Capitalize first letter
+ */
+function capitalizeFirst(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Truncate string with ellipsis
+ */
+function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.substring(0, maxLength - 3) + '...';
+}

package/skills/skill-apidocs/src/commands/list.ts

@@ -0,0 +1,51 @@
+import * as output from '../utils/output.js';
+import { listLibraries, initStorage } from '../lib/storage.js';
+import { formatNumber } from '../utils/output.js';
+import chalk from 'chalk';
+
+/**
+ * List all indexed libraries
+ */
+export async function list(): Promise<void> {
+  await initStorage();
+
+  const libraries = await listLibraries();
+
+  if (libraries.length === 0) {
+    output.info('No libraries indexed yet');
+    output.info('Use `service-apidocs add <website-url>` to add documentation');
+    return;
+  }
+
+  console.log();
+  console.log(chalk.bold('Indexed Libraries'));
+  console.log('─'.repeat(80));
+
+  const rows = libraries.map((lib) => {
+    const name = chalk.cyan(lib.name);
+    const domain = chalk.yellow(lib.domain);
+    const pages = chalk.gray(`${formatNumber(lib.pageCount || 0)} pages`);
+    const chunks = chalk.gray(`${formatNumber(lib.chunkCount)} chunks`);
+    const endpoints = lib.endpointCount
+      ? chalk.magenta(`${formatNumber(lib.endpointCount)} endpoints`)
+      : chalk.gray('-');
+    const date = new Date(lib.indexedAt).toLocaleDateString();
+
+    return [name, domain, pages, chunks, endpoints, chalk.gray(date)];
+  });
+
+  console.log(output.table(rows, ['Library', 'Domain', 'Pages', 'Chunks', 'Endpoints', 'Indexed']));
+
+  // Show docs URLs for libraries that have them
+  const withDocsUrl = libraries.filter((lib) => lib.docsUrl);
+  if (withDocsUrl.length > 0) {
+    console.log();
+    console.log(chalk.dim('Documentation URLs:'));
+    for (const lib of withDocsUrl) {
+      console.log(chalk.dim(`  ${lib.name}: ${lib.docsUrl}`));
+    }
+  }
+
+  console.log();
+  console.log(chalk.gray(`Total: ${libraries.length} libraries`));
+}