@herdctl/core 0.0.1

package/dist/work-sources/registry.js

@@ -0,0 +1,132 @@
+/**
+ * Work Source Registry
+ *
+ * Provides a singleton registry for work source adapters.
+ * Allows registration of factory functions that create adapter instances
+ * based on configuration.
+ */
+import { UnknownWorkSourceError, DuplicateWorkSourceError } from "./errors.js";
+// =============================================================================
+// Registry State (Module-level Singleton)
+// =============================================================================
+/**
+ * Internal registry map storing factories by type
+ */
+const registry = new Map();
+// =============================================================================
+// 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, factory) {
+    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) {
+    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() {
+    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) {
+    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) {
+    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() {
+    registry.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/work-sources/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/work-sources/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAgC/E,gFAAgF;AAChF,0CAA0C;AAC1C,gFAAgF;AAEhF;;GAEG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;AAEtD,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,OAA0B;IAE1B,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAAC,MAAwB;IACpD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE1C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,sBAAsB,CAAC,MAAM,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/work-sources/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Type definitions for work sources
+ *
+ * Defines common types for work items, fetch options, and operation results
+ * that all work source adapters must implement.
+ */
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/work-sources/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/work-sources/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,gDAAgD;IAChD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,SAAS,EAAE,IAAI,CAAC;IAChB,0CAA0C;IAC1C,SAAS,EAAE,IAAI,CAAC;CACjB;AAMD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,iBAAiB,GACjB,WAAW,GACX,mBAAmB,GACnB,cAAc,GACd,eAAe,CAAC;AAEpB;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,OAAO,EAAE,WAAW,CAAC;IACrB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/work-sources/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for work sources
+ *
+ * Defines common types for work items, fetch options, and operation results
+ * that all work source adapters must implement.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/work-sources/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/work-sources/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@herdctl/core",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
+    "yaml": "^2.3.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.17",
+    "typescript": "^5",
+    "vitest": "^4.0.17"
+  }
+}