@herdctl/core 0.0.1

package/dist/state/session.js

@@ -0,0 +1,173 @@
+/**
+ * Session state persistence operations
+ *
+ * Provides CRUD operations for session info files stored at
+ * .herdctl/sessions/<agent-name>.json
+ */
+import { unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWriteJson } from "./utils/atomic.js";
+import { safeReadJson } from "./utils/reads.js";
+import { SessionInfoSchema, createSessionInfo, } from "./schemas/session-info.js";
+import { StateFileError } from "./errors.js";
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get the file path for an agent's session
+ */
+function getSessionFilePath(sessionsDir, agentName) {
+    return join(sessionsDir, `${agentName}.json`);
+}
+// =============================================================================
+// CRUD Operations
+// =============================================================================
+/**
+ * Get session info for an agent
+ *
+ * Returns null if no session exists (handles missing file gracefully).
+ *
+ * @param sessionsDir - Path to the sessions directory
+ * @param agentName - Name of the agent
+ * @param options - Optional operation options
+ * @returns The session info, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const session = await getSessionInfo('/path/to/.herdctl/sessions', 'my-agent');
+ * if (session) {
+ *   console.log(`Session ${session.session_id} has ${session.job_count} jobs`);
+ * } else {
+ *   console.log('No existing session');
+ * }
+ * ```
+ */
+export async function getSessionInfo(sessionsDir, agentName, options = {}) {
+    const { logger = console } = options;
+    const filePath = getSessionFilePath(sessionsDir, agentName);
+    const result = await safeReadJson(filePath);
+    if (!result.success) {
+        // File not found is not an error - return null
+        if (result.error.code === "ENOENT") {
+            return null;
+        }
+        // Log other errors but don't throw - treat as missing
+        logger.warn(`Failed to read session file for ${agentName}: ${result.error.message}`);
+        return null;
+    }
+    // Parse and validate
+    const parseResult = SessionInfoSchema.safeParse(result.data);
+    if (!parseResult.success) {
+        logger.warn(`Corrupted session file for ${agentName}: ${parseResult.error.message}. Returning null.`);
+        return null;
+    }
+    return parseResult.data;
+}
+/**
+ * Update session info for an agent
+ *
+ * If no session exists, creates a new one with the provided updates.
+ * Automatically updates last_used_at timestamp.
+ *
+ * @param sessionsDir - Path to the sessions directory
+ * @param agentName - Name of the agent
+ * @param updates - Updates to apply to the session
+ * @returns The updated session info
+ * @throws StateFileError if the file cannot be written
+ *
+ * @example
+ * ```typescript
+ * // Update existing session
+ * const session = await updateSessionInfo('/path/to/.herdctl/sessions', 'my-agent', {
+ *   job_count: 5,
+ *   mode: 'interactive',
+ * });
+ *
+ * // Create new session
+ * const newSession = await updateSessionInfo('/path/to/.herdctl/sessions', 'new-agent', {
+ *   session_id: 'claude-session-abc123',
+ *   mode: 'autonomous',
+ * });
+ * ```
+ */
+export async function updateSessionInfo(sessionsDir, agentName, updates) {
+    const filePath = getSessionFilePath(sessionsDir, agentName);
+    // Try to read existing session
+    const existingResult = await safeReadJson(filePath);
+    let existingSession = null;
+    if (existingResult.success) {
+        const parseResult = SessionInfoSchema.safeParse(existingResult.data);
+        if (parseResult.success) {
+            existingSession = parseResult.data;
+        }
+    }
+    const now = new Date().toISOString();
+    let updatedSession;
+    if (existingSession) {
+        // Update existing session
+        updatedSession = {
+            ...existingSession,
+            ...updates,
+            last_used_at: now, // Always update last_used_at
+        };
+    }
+    else {
+        // Create new session - session_id is required for new sessions
+        if (!updates.session_id) {
+            throw new StateFileError("session_id is required when creating a new session", filePath, "write");
+        }
+        const newSession = createSessionInfo({
+            agent_name: agentName,
+            session_id: updates.session_id,
+            mode: updates.mode,
+        });
+        updatedSession = {
+            ...newSession,
+            ...updates,
+            agent_name: agentName, // Ensure agent_name is not overwritten
+            created_at: newSession.created_at, // Preserve created_at
+            last_used_at: now,
+        };
+    }
+    // Validate the updated session
+    const validated = SessionInfoSchema.parse(updatedSession);
+    // Write atomically
+    try {
+        await atomicWriteJson(filePath, validated);
+    }
+    catch (error) {
+        throw new StateFileError(`Failed to update session file for ${agentName}: ${error.message}`, filePath, "write", error);
+    }
+    return validated;
+}
+/**
+ * Clear session info for an agent (delete the session file)
+ *
+ * @param sessionsDir - Path to the sessions directory
+ * @param agentName - Name of the agent
+ * @returns true if the session was deleted, false if it didn't exist
+ *
+ * @example
+ * ```typescript
+ * const cleared = await clearSession('/path/to/.herdctl/sessions', 'my-agent');
+ * if (cleared) {
+ *   console.log('Session cleared');
+ * } else {
+ *   console.log('No session to clear');
+ * }
+ * ```
+ */
+export async function clearSession(sessionsDir, agentName) {
+    const filePath = getSessionFilePath(sessionsDir, agentName);
+    try {
+        await unlink(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw new StateFileError(`Failed to delete session file for ${agentName}: ${error.message}`, filePath, "write", error);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/state/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/state/session.ts"],"names":[],"mappings":"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"}

package/dist/state/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Type definitions for state management
+ *
+ * Defines types for state directory structure and configuration
+ */
+/**
+ * Paths to all state directory subdirectories and files
+ */
+export interface StateDirectory {
+    /** Root state directory path (e.g., .herdctl/) */
+    root: string;
+    /** Path to jobs subdirectory */
+    jobs: string;
+    /** Path to sessions subdirectory */
+    sessions: string;
+    /** Path to logs subdirectory */
+    logs: string;
+    /** Path to state.yaml file */
+    stateFile: string;
+}
+/**
+ * Options for initializing the state directory
+ */
+export interface InitStateDirectoryOptions {
+    /**
+     * Custom path for the state directory.
+     * Defaults to .herdctl/ in the current working directory.
+     */
+    path?: string;
+}
+/**
+ * Result of state directory validation
+ */
+export interface StateDirectoryValidation {
+    /** Whether the directory structure is valid */
+    valid: boolean;
+    /** List of missing directories or files */
+    missing: string[];
+    /** List of validation errors */
+    errors: string[];
+}
+/**
+ * Subdirectory names within the state directory
+ */
+export declare const STATE_SUBDIRECTORIES: readonly ["jobs", "sessions", "logs"];
+/**
+ * Default state directory name
+ */
+export declare const DEFAULT_STATE_DIR_NAME = ".herdctl";
+/**
+ * Default state file name
+ */
+export declare const STATE_FILE_NAME = "state.yaml";
+//# sourceMappingURL=types.d.ts.map

package/dist/state/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/state/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,KAAK,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gCAAgC;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,uCAAwC,CAAC;AAE1E;;GAEG;AACH,eAAO,MAAM,sBAAsB,aAAa,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,eAAe,eAAe,CAAC"}

package/dist/state/types.js

@@ -0,0 +1,18 @@
+/**
+ * Type definitions for state management
+ *
+ * Defines types for state directory structure and configuration
+ */
+/**
+ * Subdirectory names within the state directory
+ */
+export const STATE_SUBDIRECTORIES = ["jobs", "sessions", "logs"];
+/**
+ * Default state directory name
+ */
+export const DEFAULT_STATE_DIR_NAME = ".herdctl";
+/**
+ * Default state file name
+ */
+export const STATE_FILE_NAME = "state.yaml";
+//# sourceMappingURL=types.js.map

package/dist/state/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/state/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyCH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAU,CAAC;AAE1E;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC"}

package/dist/state/utils/__tests__/atomic.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=atomic.test.d.ts.map

package/dist/state/utils/__tests__/atomic.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.test.d.ts","sourceRoot":"","sources":["../../../../src/state/utils/__tests__/atomic.test.ts"],"names":[],"mappings":""}