@hasna/skills 0.0.2

package/skills/skill-apidocs/src/types/index.ts

@@ -0,0 +1,297 @@
+/**
+ * Configuration file structure (apidocs.json)
+ */
+export interface ApidocsConfig {
+  projectTitle: string;
+  description?: string;
+  rules?: string[];
+}
+
+/**
+ * Crawled page from documentation website
+ */
+export interface CrawledPage {
+  url: string;
+  path: string;
+  title: string;
+  content: string;
+  html: string;
+  crawledAt: string;
+}
+
+/**
+ * Configuration for web crawler
+ */
+export interface CrawlConfig {
+  startUrl: string;
+  maxPages: number;
+  allowedDomains?: string[];
+  excludePatterns?: string[];
+}
+
+/**
+ * Event emitted during crawling
+ */
+export interface CrawlEvent {
+  type: 'navigating' | 'extracted' | 'skipped' | 'error' | 'complete';
+  url?: string;
+  title?: string;
+  pageCount?: number;
+  totalPages?: number;
+  error?: string;
+  reason?: string;
+}
+
+/**
+ * Result from crawl operation
+ */
+export interface CrawlResult {
+  pages: CrawledPage[];
+  totalPages: number;
+  duration: number;
+  errors: string[];
+}
+
+/**
+ * Website URL information
+ */
+export interface WebsiteInfo {
+  url: string;
+  domain: string;
+  path: string;
+  protocol: string;
+}
+
+/**
+ * Documentation file (compatible with parser)
+ */
+export interface DocFile {
+  path: string;
+  content: string;
+}
+
+/**
+ * Parsed chunk from documentation
+ */
+export interface Chunk {
+  id: string;
+  content: string;
+  title: string;
+  type: 'code' | 'text';
+  filePath: string;
+  headingHierarchy: string[];
+  codeLanguage?: string;
+  tokenCount: number;
+}
+
+/**
+ * Vector data for S3 Vectors
+ */
+export interface VectorData {
+  key: string;
+  data: {
+    float32: number[];
+  };
+  metadata: VectorMetadata;
+}
+
+/**
+ * Metadata stored with each vector
+ */
+export interface VectorMetadata {
+  libraryId: string;
+  version: string;
+  filePath: string;
+  chunkIndex: number;
+  title: string;
+  type: 'code' | 'text';
+  content: string;
+}
+
+/**
+ * Search result from vector query
+ */
+export interface SearchResult {
+  key: string;
+  score: number;
+  metadata: VectorMetadata;
+}
+
+/**
+ * Library metadata stored locally
+ */
+export interface LibraryMetadata {
+  id: string;
+  name: string;
+  websiteUrl: string;
+  docsUrl?: string;                // Discovered documentation URL
+  domain: string;
+  indexedAt: string;
+  chunkCount: number;
+  pageCount: number;
+  endpointCount?: number;          // Number of extracted API endpoints
+  config?: ApidocsConfig;
+  indexName: string;
+  crawledUrls?: string[];
+}
+
+/**
+ * Index information from S3 Vectors
+ */
+export interface IndexInfo {
+  name: string;
+  vectorCount: number;
+  createdAt?: string;
+}
+
+/**
+ * Add command options
+ */
+export interface AddOptions {
+  name?: string;
+  maxPages?: number;
+}
+
+/**
+ * Code block extracted from markdown
+ */
+export interface CodeBlock {
+  content: string;
+  language: string;
+  filePath: string;
+  lineStart?: number;
+}
+
+/**
+ * Query options
+ */
+export interface QueryOptions {
+  library: string;
+  question: string;
+  tokens?: number;
+  topK?: number;
+  json?: boolean;
+}
+
+
+/**
+ * Formatted query result
+ */
+export interface QueryResult {
+  content: string;
+  sources: string[];
+  chunks: SearchResult[];
+}
+
+// ===== API Endpoint Types =====
+
+/**
+ * HTTP methods supported by API endpoints
+ */
+export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+
+/**
+ * API endpoint extracted from documentation
+ */
+export interface APIEndpoint {
+  id: string;                      // Hash of method:path
+  method: HTTPMethod;
+  path: string;                    // /users, /posts/{id}, /v1/chat/completions
+  title: string;                   // "Create a user", "List posts"
+  description: string;             // Full description from docs
+  resource: string;                // Grouped resource: "users", "posts", "chat"
+  parameters?: EndpointParameter[];
+  requestBody?: {
+    contentType: string;
+    schema?: Record<string, unknown>;
+    example?: unknown;
+  };
+  responses?: EndpointResponse[];
+  codeExamples?: CodeExample[];
+  sourceUrl: string;               // URL where this was found
+  sourcePageTitle: string;         // Page title
+}
+
+/**
+ * Parameter for an API endpoint
+ */
+export interface EndpointParameter {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  type: string;
+  required: boolean;
+  description?: string;
+  default?: unknown;
+}
+
+/**
+ * Response from an API endpoint
+ */
+export interface EndpointResponse {
+  status: number;
+  description: string;
+  example?: unknown;
+}
+
+/**
+ * Code example for an API endpoint
+ */
+export interface CodeExample {
+  language: string;               // curl, python, javascript, etc.
+  code: string;
+  title?: string;
+}
+
+// ===== Discovery Agent Types =====
+
+/**
+ * Event emitted during docs URL discovery
+ */
+export interface DiscoveryEvent {
+  type: 'navigating' | 'analyzing' | 'found' | 'not_found' | 'error';
+  url?: string;
+  message?: string;
+  docsUrl?: string;
+  error?: string;
+}
+
+/**
+ * Result from docs discovery
+ */
+export interface DiscoveryResult {
+  success: boolean;
+  docsUrl?: string;
+  error?: string;
+}
+
+// ===== Extraction Agent Types =====
+
+/**
+ * Event emitted during endpoint extraction
+ */
+export interface ExtractionEvent {
+  type: 'processing' | 'extracted' | 'complete' | 'error';
+  pageIndex?: number;
+  totalPages?: number;
+  pageUrl?: string;
+  endpointCount?: number;
+  error?: string;
+}
+
+/**
+ * Result from endpoint extraction
+ */
+export interface ExtractionResult {
+  endpoints: APIEndpoint[];
+  processedPages: number;
+  errors: string[];
+}
+
+/**
+ * Options for endpoints command
+ */
+export interface EndpointsOptions {
+  json?: boolean;
+  groupBy?: 'resource' | 'method';
+  filter?: string;
+}

package/skills/skill-apidocs/src/utils/output.ts

@@ -0,0 +1,132 @@
+import chalk from 'chalk';
+
+/**
+ * Log info message
+ */
+export function info(message: string): void {
+  console.log(chalk.blue('ℹ'), message);
+}
+
+/**
+ * Log success message
+ */
+export function success(message: string): void {
+  console.log(chalk.green('✓'), message);
+}
+
+/**
+ * Log warning message
+ */
+export function warn(message: string): void {
+  console.log(chalk.yellow('⚠'), message);
+}
+
+/**
+ * Log error message
+ */
+export function error(message: string): void {
+  console.error(chalk.red('✗'), message);
+}
+
+/**
+ * Log step in a process
+ */
+export function step(message: string): void {
+  console.log(chalk.cyan('→'), message);
+}
+
+/**
+ * Create a spinner-like progress indicator
+ */
+export function progress(message: string): { update: (msg: string) => void; done: (msg?: string) => void } {
+  process.stdout.write(chalk.cyan('⏳') + ' ' + message);
+
+  return {
+    update: (msg: string) => {
+      process.stdout.clearLine(0);
+      process.stdout.cursorTo(0);
+      process.stdout.write(chalk.cyan('⏳') + ' ' + msg);
+    },
+    done: (msg?: string) => {
+      process.stdout.clearLine(0);
+      process.stdout.cursorTo(0);
+      if (msg) {
+        console.log(chalk.green('✓'), msg);
+      }
+    },
+  };
+}
+
+/**
+ * Format number with commas
+ */
+export function formatNumber(num: number): string {
+  return num.toLocaleString();
+}
+
+/**
+ * Format bytes to human readable
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Create a table for CLI output
+ */
+export function table(rows: string[][], headers?: string[]): string {
+  const columnWidths: number[] = [];
+
+  // Calculate column widths
+  const allRows = headers ? [headers, ...rows] : rows;
+  for (const row of allRows) {
+    for (let i = 0; i < row.length; i++) {
+      const len = stripAnsi(row[i]).length;
+      columnWidths[i] = Math.max(columnWidths[i] || 0, len);
+    }
+  }
+
+  // Format rows
+  const formatRow = (row: string[]): string => {
+    return row.map((cell, i) => {
+      const padding = columnWidths[i] - stripAnsi(cell).length;
+      return cell + ' '.repeat(padding);
+    }).join('  ');
+  };
+
+  let output = '';
+
+  if (headers) {
+    output += chalk.bold(formatRow(headers)) + '\n';
+    output += columnWidths.map(w => '─'.repeat(w)).join('──') + '\n';
+  }
+
+  for (const row of rows) {
+    output += formatRow(row) + '\n';
+  }
+
+  return output.trimEnd();
+}
+
+/**
+ * Strip ANSI codes from string
+ */
+function stripAnsi(str: string): string {
+  return str.replace(/\x1B\[[0-9;]*m/g, '');
+}
+
+/**
+ * Print JSON output
+ */
+export function json(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+/**
+ * Print markdown content
+ */
+export function markdown(content: string): void {
+  console.log(content);
+}

package/skills/skill-apidocs/src/utils/paths.ts

@@ -0,0 +1,126 @@
+import { join } from 'path';
+import { homedir } from 'os';
+import type { WebsiteInfo } from '../types/index.js';
+
+/**
+ * Base directory for service-apidocs data
+ */
+export const SERVICE_DIR = join(homedir(), '.service', 'service-apidocs');
+
+/**
+ * Libraries metadata directory
+ */
+export const LIBRARIES_DIR = join(SERVICE_DIR, 'libraries');
+
+/**
+ * Global config file path
+ */
+export const CONFIG_FILE = join(SERVICE_DIR, 'config.json');
+
+/**
+ * Get library directory path
+ */
+export function getLibraryDir(libraryId: string): string {
+  const sanitized = libraryId.replace(/[^a-zA-Z0-9.-]/g, '-');
+  return join(LIBRARIES_DIR, sanitized);
+}
+
+/**
+ * Get library metadata file path
+ */
+export function getLibraryMetadataPath(libraryId: string): string {
+  return join(getLibraryDir(libraryId), 'metadata.json');
+}
+
+/**
+ * Get library cache directory
+ */
+export function getLibraryCacheDir(libraryId: string): string {
+  return join(getLibraryDir(libraryId), 'cache');
+}
+
+/**
+ * Parse website URL to extract domain and path
+ * Only allows http and https protocols for security
+ */
+export function parseWebsiteUrl(url: string): WebsiteInfo | null {
+  try {
+    const parsed = new URL(url);
+
+    // Only allow http and https protocols
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return null;
+    }
+
+    return {
+      url: parsed.href,
+      domain: parsed.hostname,
+      path: parsed.pathname,
+      protocol: parsed.protocol.replace(':', ''),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create library ID from URL and optional custom name
+ */
+export function createLibraryIdFromUrl(url: string, customName?: string): string {
+  if (customName) {
+    return customName.toLowerCase().replace(/[^a-zA-Z0-9.-]/g, '-');
+  }
+
+  const parsed = parseWebsiteUrl(url);
+  if (!parsed) {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  // Use domain without common prefixes
+  let domain = parsed.domain.replace(/^(www\.|docs\.|api\.|platform\.)/, '');
+
+  // Include path if it's meaningful (e.g., /docs)
+  const pathPart = parsed.path.replace(/^\/+|\/+$/g, '').split('/')[0];
+  if (pathPart && pathPart !== 'docs' && pathPart !== 'documentation') {
+    domain = `${domain}-${pathPart}`;
+  }
+
+  return domain.toLowerCase().replace(/[^a-zA-Z0-9.-]/g, '-');
+}
+
+/**
+ * Create index name for S3 Vectors from URL
+ */
+export function createIndexNameFromUrl(url: string, customName?: string): string {
+  const libraryId = createLibraryIdFromUrl(url, customName);
+  const timestamp = new Date().toISOString().split('T')[0].replace(/-/g, '');
+  return `${libraryId}-${timestamp}`.toLowerCase();
+}
+
+/**
+ * Ensure directory exists
+ */
+export async function ensureDir(dir: string): Promise<void> {
+  const fs = await import('fs/promises');
+  await fs.mkdir(dir, { recursive: true });
+}
+
+/**
+ * Check if file matches exclude patterns
+ */
+export function matchesPattern(path: string, patterns: string[]): boolean {
+  for (const pattern of patterns) {
+    // Convert glob pattern to regex
+    const regexPattern = pattern
+      .replace(/\*\*/g, '{{GLOBSTAR}}')
+      .replace(/\*/g, '[^/]*')
+      .replace(/{{GLOBSTAR}}/g, '.*')
+      .replace(/\?/g, '.');
+
+    const regex = new RegExp(`^${regexPattern}$|/${regexPattern}$|^${regexPattern}/|/${regexPattern}/`);
+    if (regex.test(path)) {
+      return true;
+    }
+  }
+  return false;
+}

package/skills/skill-apidocs/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "types": ["bun-types"],
+    "lib": ["ESNext"],
+    "noEmit": true
+  },
+  "include": ["src/**/*", "bin/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/skills/skill-architecture-docs/CLAUDE.md

@@ -0,0 +1,19 @@
+# skill-architecture-docs
+
+Architecture Docs skill.
+
+## Tech Stack
+
+- Runtime: Bun
+- Language: TypeScript
+- CLI: Commander.js
+
+## CLI
+
+```bash
+skill-architecture-docs run
+```
+
+## Data Directory
+
+~/.skill/skill-architecture-docs/

package/skills/skill-architecture-docs/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@hasnaxyz/skill-architecture-docs",
+  "version": "0.1.0",
+  "description": "Architecture Docs skill",
+  "type": "module",
+  "bin": {
+    "skill-architecture-docs": "./bin/cli.ts"
+  },
+  "scripts": {
+    "dev": "bun run bin/cli.ts",
+    "build": "bun build bin/cli.ts --outdir dist --target node",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": ["bin", "src", "tsconfig.json"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasnaxyz/skill-architecture-docs.git"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}