@herdctl/core 0.0.1

package/src/work-sources/registry.ts

@@ -0,0 +1,178 @@
+/**
+ * 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

@@ -0,0 +1,161 @@
+/**
+ * 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

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

package/vitest.config.ts

@@ -0,0 +1,19 @@
+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,
+      },
+    },
+  },
+});