@herdctl/core 0.0.1 → 0.1.0

package/src/work-sources/registry.ts

@@ -1,178 +0,0 @@
-/**
- * Work Source Registry
- *
- * Provides a singleton registry for work source adapters.
- * Allows registration of factory functions that create adapter instances
- * based on configuration.
- */
-
-import type { WorkSourceAdapter } from "./index.js";
-import type { WorkSourceLabels } from "../config/schema.js";
-import { UnknownWorkSourceError, DuplicateWorkSourceError } from "./errors.js";
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/**
- * Configuration for a work source adapter
- *
- * This is a flexible configuration type that allows any work source type
- * to be registered. For type-safe configuration of known types, use the
- * specific config types (e.g., GitHubWorkSourceConfig).
- */
-export interface WorkSourceConfig {
-  /** The type identifier for this work source (e.g., 'github', 'linear') */
-  type: string;
-  /** Label configuration for work item states */
-  labels?: WorkSourceLabels;
-  /** Whether to clean up in-progress labels on startup */
-  cleanup_in_progress?: boolean;
-  /** Additional adapter-specific configuration */
-  [key: string]: unknown;
-}
-
-/**
- * Factory function that creates a work source adapter instance
- *
- * @param config - The configuration for the work source
- * @returns A configured WorkSourceAdapter instance
- */
-export type WorkSourceFactory = (config: WorkSourceConfig) => WorkSourceAdapter;
-
-// =============================================================================
-// Registry State (Module-level Singleton)
-// =============================================================================
-
-/**
- * Internal registry map storing factories by type
- */
-const registry = new Map<string, WorkSourceFactory>();
-
-// =============================================================================
-// Registry Functions
-// =============================================================================
-
-/**
- * Register a work source adapter factory
- *
- * Registers a factory function that will be used to create adapter instances
- * for the specified type. The factory is called when `getWorkSource()` is
- * invoked with a matching type.
- *
- * @param type - The unique type identifier (e.g., 'github', 'linear')
- * @param factory - Factory function that creates adapter instances
- * @throws {DuplicateWorkSourceError} If the type is already registered
- *
- * @example
- * ```typescript
- * registerWorkSource('github', (config) => new GitHubAdapter(config));
- * registerWorkSource('linear', (config) => new LinearAdapter(config));
- * ```
- */
-export function registerWorkSource(
-  type: string,
-  factory: WorkSourceFactory
-): void {
-  if (registry.has(type)) {
-    throw new DuplicateWorkSourceError(type);
-  }
-  registry.set(type, factory);
-}
-
-/**
- * Get a configured work source adapter instance
- *
- * Looks up the factory for the specified type and calls it with the
- * provided configuration to create an adapter instance.
- *
- * @param config - The work source configuration (must include `type`)
- * @returns A configured WorkSourceAdapter instance
- * @throws {UnknownWorkSourceError} If no factory is registered for the type
- *
- * @example
- * ```typescript
- * const adapter = getWorkSource({
- *   type: 'github',
- *   labels: { ready: 'agent-ready', in_progress: 'agent-working' }
- * });
- *
- * const { items } = await adapter.fetchAvailableWork();
- * ```
- */
-export function getWorkSource(config: WorkSourceConfig): WorkSourceAdapter {
-  const factory = registry.get(config.type);
-
-  if (!factory) {
-    throw new UnknownWorkSourceError(config.type, getRegisteredTypes());
-  }
-
-  return factory(config);
-}
-
-/**
- * Get a list of all registered work source types
- *
- * @returns Array of registered type identifiers
- *
- * @example
- * ```typescript
- * const types = getRegisteredTypes();
- * // ['github', 'linear', 'jira']
- * ```
- */
-export function getRegisteredTypes(): string[] {
-  return Array.from(registry.keys());
-}
-
-/**
- * Check if a work source type is registered
- *
- * @param type - The type identifier to check
- * @returns True if the type is registered
- *
- * @example
- * ```typescript
- * if (isWorkSourceRegistered('github')) {
- *   const adapter = getWorkSource({ type: 'github' });
- * }
- * ```
- */
-export function isWorkSourceRegistered(type: string): boolean {
-  return registry.has(type);
-}
-
-/**
- * Unregister a work source adapter factory
- *
- * Removes the factory for the specified type. Primarily useful for testing.
- *
- * @param type - The type identifier to unregister
- * @returns True if the type was registered and removed, false otherwise
- *
- * @example
- * ```typescript
- * // In tests
- * unregisterWorkSource('github');
- * registerWorkSource('github', mockFactory);
- * ```
- */
-export function unregisterWorkSource(type: string): boolean {
-  return registry.delete(type);
-}
-
-/**
- * Clear all registered work source factories
- *
- * Removes all registered factories. Primarily useful for testing.
- * Note: This will also clear built-in adapters.
- *
- * @example
- * ```typescript
- * // In test setup/teardown
- * clearWorkSourceRegistry();
- * ```
- */
-export function clearWorkSourceRegistry(): void {
-  registry.clear();
-}

package/src/work-sources/types.ts

@@ -1,161 +0,0 @@
-/**
- * Type definitions for work sources
- *
- * Defines common types for work items, fetch options, and operation results
- * that all work source adapters must implement.
- */
-
-// =============================================================================
-// Work Item Types
-// =============================================================================
-
-/**
- * Priority levels for work items
- */
-export type WorkItemPriority = "critical" | "high" | "medium" | "low";
-
-/**
- * A work item that can be processed by an agent
- *
- * Represents a unit of work from any source (GitHub Issues, Linear, etc.)
- * with normalized fields for consistent handling across sources.
- */
-export interface WorkItem {
-  /** Unique identifier within herdctl (source-prefixed) */
-  id: string;
-  /** The type of source this work item came from (e.g., 'github', 'linear') */
-  source: string;
-  /** The original ID from the external system */
-  externalId: string;
-  /** Title or summary of the work item */
-  title: string;
-  /** Full description or body of the work item */
-  description: string;
-  /** Priority level of the work item */
-  priority: WorkItemPriority;
-  /** Labels/tags associated with the work item */
-  labels: string[];
-  /** Source-specific metadata (e.g., GitHub milestone, assignees) */
-  metadata: Record<string, unknown>;
-  /** URL to view the work item in the external system */
-  url: string;
-  /** When the work item was created */
-  createdAt: Date;
-  /** When the work item was last updated */
-  updatedAt: Date;
-}
-
-// =============================================================================
-// Fetch Options Types
-// =============================================================================
-
-/**
- * Options for fetching available work items
- *
- * Supports filtering by labels/priority and pagination for large result sets.
- */
-export interface FetchOptions {
-  /** Filter by labels (items must have ALL specified labels) */
-  labels?: string[];
-  /** Filter by priority levels (items must match ONE of the priorities) */
-  priority?: WorkItemPriority[];
-  /** Maximum number of items to return */
-  limit?: number;
-  /** Cursor for pagination (opaque string from previous response) */
-  cursor?: string;
-  /** Include items that are already claimed by this source */
-  includeClaimed?: boolean;
-}
-
-/**
- * Result of fetching work items with pagination info
- */
-export interface FetchResult {
-  /** The fetched work items */
-  items: WorkItem[];
-  /** Cursor for fetching the next page (undefined if no more pages) */
-  nextCursor?: string;
-  /** Total count of matching items (if available from source) */
-  totalCount?: number;
-}
-
-// =============================================================================
-// Claim Result Types
-// =============================================================================
-
-/**
- * Reasons why claiming a work item might fail
- */
-export type ClaimFailureReason =
-  | "already_claimed"
-  | "not_found"
-  | "permission_denied"
-  | "source_error"
-  | "invalid_state";
-
-/**
- * Result of attempting to claim a work item
- *
- * Indicates whether the claim succeeded and provides details on failure.
- */
-export interface ClaimResult {
-  /** Whether the claim was successful */
-  success: boolean;
-  /** The claimed work item (if successful) */
-  workItem?: WorkItem;
-  /** Reason for failure (if unsuccessful) */
-  reason?: ClaimFailureReason;
-  /** Human-readable error message (if unsuccessful) */
-  message?: string;
-}
-
-// =============================================================================
-// Work Result Types
-// =============================================================================
-
-/**
- * Outcome status of completing work
- */
-export type WorkOutcome = "success" | "failure" | "partial";
-
-/**
- * Result of completing a work item
- *
- * Captures the outcome and any artifacts or comments to post back to the source.
- */
-export interface WorkResult {
-  /** The outcome of the work */
-  outcome: WorkOutcome;
-  /** Summary of what was accomplished */
-  summary: string;
-  /** Detailed description of changes made (for PR descriptions, etc.) */
-  details?: string;
-  /** Artifacts produced (e.g., file paths, URLs) */
-  artifacts?: string[];
-  /** Error message if outcome is failure or partial */
-  error?: string;
-}
-
-// =============================================================================
-// Release Options Types
-// =============================================================================
-
-/**
- * Options for releasing a claimed work item
- */
-export interface ReleaseOptions {
-  /** Reason for releasing the work item */
-  reason?: string;
-  /** Whether to add a comment to the work item explaining the release */
-  addComment?: boolean;
-}
-
-/**
- * Result of releasing a work item
- */
-export interface ReleaseResult {
-  /** Whether the release was successful */
-  success: boolean;
-  /** Error message if unsuccessful */
-  message?: string;
-}

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}

package/vitest.config.ts

@@ -1,19 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    include: ["src/**/__tests__/**/*.test.ts"],
-    coverage: {
-      provider: "v8",
-      include: ["src/**/*.ts"],
-      exclude: ["src/**/__tests__/**", "src/**/*.test.ts"],
-      reporter: ["text", "json", "html"],
-      thresholds: {
-        lines: 85,
-        functions: 85,
-        branches: 65,
-        statements: 85,
-      },
-    },
-  },
-});